session

Functions

getNodeCatalog()

function getNodeCatalog(document?, registry?): MaterialXNodeSpec[];

Parameters

Parameter	Type
document?	MaterialXDocument
registry?	MaterialXNodeSpec[]

Returns

MaterialXNodeSpec[]

---

graphScopes()

function graphScopes(document): string[];

Parameters

Parameter	Type
document	MaterialXDocument

Returns

string[]

---

readGraph()

function readGraph(
   document, 
   scope?, 
   catalog?
): object;

Resolve the nodes and connections in a scope without adding viewer state or default positions.

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
scope?	string	''
catalog?	MaterialXNodeSpec[]	...

Returns

object

Name	Type
nodes	GraphNode[]
edges	GraphEdge[]

---

isStructural()

function isStructural(spec): boolean;

Parameters

Parameter	Type
spec	MaterialXNodeSpec

Returns

boolean

---

addNode()

function addNode(
   document, 
   spec, 
   position?, 
   scope?
): MaterialXDocument;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
spec	MaterialXNodeSpec	undefined
position?	Point	undefined
scope?	string	''

Returns

MaterialXDocument

---

setInterfacePort()

function setInterfacePort(
   document, 
   id, 
   changes, 
   scope?
): MaterialXDocument;

Retype an interface input or output of a node graph, or set the input's default value. A new type drops the old value.

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
id	string	undefined
changes	{ type?: string; value?: string; }	undefined
changes.type?	string	undefined
changes.value?	string	undefined
scope?	string	''

Returns

MaterialXDocument

---

cloneNode()

function cloneNode(
   document, 
   id, 
   position?, 
   scope?
): MaterialXDocument;

Copy a node's values and incoming connections, leaving downstream connections unchanged.

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
id	string	undefined
position?	Point	undefined
scope?	string	''

Returns

MaterialXDocument

---

pasteNodes()

function pasteNodes(
   document, 
   elements, 
   scope?, 
   offset?
): MaterialXDocument;

Insert copies of nodes into a scope: colliding names get suffixed, wires among them are kept, wires to anything else are dropped.

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
elements	readonly MaterialXElement[]	undefined
scope?	string	''
offset?	Point	...

Returns

MaterialXDocument

---

setInputValue()

function setInputValue(
   document, 
   node, 
   input, 
   value, 
   scope?, 
   catalog?, 
   valueType?
): MaterialXDocument;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
node	string	undefined
input	string	undefined
value	string	undefined
scope?	string	''
catalog?	MaterialXNodeSpec[]	...
valueType?	string	undefined

Returns

MaterialXDocument

---

resetInput()

function resetInput(
   document, 
   node, 
   input, 
   scope?
): MaterialXDocument;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
node	string	undefined
input	string	undefined
scope?	string	''

Returns

MaterialXDocument

---

connectionError()

function connectionError(
   document, 
   connection, 
   scope?, 
   catalog?
): string | undefined;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
connection	GraphConnection	undefined
scope?	string	''
catalog?	MaterialXNodeSpec[]	...

Returns

string | undefined

---

connectNodes()

function connectNodes(
   document, 
   connection, 
   scope?, 
   catalog?
): MaterialXDocument;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
connection	GraphConnection	undefined
scope?	string	''
catalog?	MaterialXNodeSpec[]	...

Returns

MaterialXDocument

---

disconnectInput()

function disconnectInput(
   document, 
   target, 
   input, 
   scope?
): MaterialXDocument;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
target	string	undefined
input	string	undefined
scope?	string	''

Returns

MaterialXDocument

---

removeNodes()

function removeNodes(
   document, 
   ids, 
   scope?
): MaterialXDocument;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
ids	string[]	undefined
scope?	string	''

Returns

MaterialXDocument

---

groupNodes()

function groupNodes(
   document, 
   ids, 
   catalog?
): MaterialXDocument;

Collapse root-scope nodes into a new node graph. Wires crossing the boundary become interface inputs and outputs.

Parameters

Parameter	Type
document	MaterialXDocument
ids	string[]
catalog?	MaterialXNodeSpec[]

Returns

MaterialXDocument

---

moveNodes()

function moveNodes(
   document, 
   positions, 
   scope?
): MaterialXDocument;

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
positions	Record<string, Point>	undefined
scope?	string	''

Returns

MaterialXDocument

---

renameNode()

function renameNode(
   document, 
   id, 
   name, 
   scope?
): MaterialXDocument;

Rename a node and every reference to it: sibling wires, interface names, nested graph paths, and material assignments.

Parameters

Parameter	Type	Default value
document	MaterialXDocument	undefined
id	string	undefined
name	string	undefined
scope?	string	''

Returns

MaterialXDocument

---

getNodeFamilies()

function getNodeFamilies(catalog): NodeFamily[];

Preserve catalog order: it determines the fallback definition and its implicit defaults.

Parameters

Parameter	Type
catalog	MaterialXNodeSpec[]

Returns

NodeFamily[]

---

findNodeFamily()

function findNodeFamily(element, catalog): NodeFamily | undefined;

Stored nodedef/type identify an interface family, never constrain its type variants.

Parameters

Parameter	Type
element	MaterialXElement
catalog	MaterialXNodeSpec[]

Returns

NodeFamily | undefined

---

createEditorSession()

function createEditorSession(options): EditorSession;

Parameters

Parameter	Type
options	EditorSessionOptions

Returns

EditorSession

---

resolutionKey()

function resolutionKey(scope, id): string;

Parameters

Parameter	Type
scope	string
id	string

Returns

string

---

invalidateTypeResolution()

function invalidateTypeResolution(document): void;

Parameters

Parameter	Type
document	MaterialXDocument

Returns

void

---

resolveTypes()

function resolveTypes(document, catalog?): TypeResolution;

Parameters

Parameter	Type
document	MaterialXDocument
catalog?	MaterialXNodeSpec[]

Returns

TypeResolution

---

materializeDocument()

function materializeDocument(document, catalog?): MaterialXDocument;

Resolve a copy for consumers of concrete MaterialX. Never author defaults or pin inferred types.

Parameters

Parameter	Type
document	MaterialXDocument
catalog?	MaterialXNodeSpec[]

Returns

MaterialXDocument

Classes

EditorError

Extends

• Error

Constructors

Constructor

new EditorError(diagnostic): EditorError;

Parameters

Parameter	Type
diagnostic	EditorDiagnostic

Returns

EditorError

Overrides

Error.constructor

Properties

code

readonly code: string;

scope?

readonly scope?: string;

node?

readonly node?: string;

input?

readonly input?: string;

---

EditorSession

Headless editing state. Only successful commits publish immutable snapshots.

Constructors

Constructor

new EditorSession(options): EditorSession;

Parameters

Parameter	Type
options	EditorSessionOptions

Returns

EditorSession

Methods

getDocument()

getDocument(): ReadonlyMaterialXDocument;

Reads inside a transaction see its working snapshot. Subscribers see getSnapshot().

Returns

ReadonlyMaterialXDocument

getCatalog()

getCatalog(): readonly DeepReadonly<MaterialXNodeSpec>[];

Returns

readonly DeepReadonly<MaterialXNodeSpec>[]

getSnapshot()

getSnapshot(): EditorSnapshot;

Returns

EditorSnapshot

toXml()

toXml(): string;

Returns

string

markClean()

markClean(): void;

Treat the current document as saved; dirty clears until the next edit.

Returns

void

subscribe()

subscribe(listener): () => void;

Parameters

Parameter	Type
listener	() => void

Returns

() => void

setScope()

setScope(scope): void;

Show the given scope; selection belongs to a scope, so it clears.

Parameters

Parameter	Type
scope	string

Returns

void

select()

select(ids): void;

Parameters

Parameter	Type
ids	readonly string[]

Returns

void

setError()

setError(message?): void;

Record a failed command for whichever surface shows errors; no argument clears it.

Parameters

Parameter	Type
message?	string

Returns

void

transaction()

transaction<T>(label, operation): T;

Synchronous transactions support nested savepoints; an uncaught error rolls back the enclosing transaction.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
label	string
operation	() => T extends PromiseLike<unknown> ? never : T

Returns

T

replaceDocument()

replaceDocument(document): void;

Loading a document accepts existing diagnostics and clears undo/redo. Input ownership stays with the caller.

Parameters

Parameter	Type
document	ReadonlyMaterialXDocument

Returns

void

undo()

undo(): void;

Returns

void

redo()

redo(): void;

Returns

void

getDiagnostics()

getDiagnostics(): readonly EditorDiagnostic[];

Returns

readonly EditorDiagnostic[]

listScopes()

listScopes(): readonly string[];

Returns

readonly string[]

graph()

graph(scope?): Readonly<{
  scope: string;
  listNodes: () => readonly DeepReadonly<GraphNode>[];
  getNode: (id) => DeepReadonly<GraphNode>;
  getInputs: (id) => readonly DeepReadonly<MaterialXNodePortSpec>[];
  getOutputs: (id) => readonly DeepReadonly<MaterialXNodePortSpec>[];
  getConnection: (target) => Readonly<OutputRef> | undefined;
  addNode: (__namedParameters) => string;
  cloneNode: (id) => string;
  pasteNodes: (elements, offset?) => string[];
  removeNodes: (ids) => void;
  groupNodes: (ids) => string;
  renameNode: (id, name) => void;
  setInterfacePort: (id, changes) => void;
  setInputValue: (id, input, value, options) => void;
  resetInput: (id, input) => void;
  disconnectInput: (id, input) => void;
  checkConnection: (source, target) => EditorDiagnostic | undefined;
  connect: (source, target) => void;
}>;

Graph handles resolve against current state, so they remain useful across commits and undo.

Parameters

Parameter	Type	Default value
scope?	string	''

Returns

Readonly<{ scope: string; listNodes: () => readonly DeepReadonly<GraphNode>[]; getNode: (id) => DeepReadonly<GraphNode>; getInputs: (id) => readonly DeepReadonly<MaterialXNodePortSpec>[]; getOutputs: (id) => readonly DeepReadonly<MaterialXNodePortSpec>[]; getConnection: (target) => Readonly<OutputRef> | undefined; addNode: (__namedParameters) => string; cloneNode: (id) => string; pasteNodes: (elements, offset?) => string[]; removeNodes: (ids) => void; groupNodes: (ids) => string; renameNode: (id, name) => void; setInterfacePort: (id, changes) => void; setInputValue: (id, input, value, options) => void; resetInput: (id, input) => void; disconnectInput: (id, input) => void; checkConnection: (source, target) => EditorDiagnostic | undefined; connect: (source, target) => void; }>

Properties

layout

readonly layout: object;

Positions remain a separate view operation, but share atomic commits and undo history.

moveNodes

moveNodes: (positions, scope) => void;

Parameters

Parameter	Type	Default value
positions	Readonly<Record<string, Point>>	undefined
scope?	string	''

Returns

void

Interfaces

Point

Persisted node coordinates; default placement belongs to the viewer.

Properties

Property	Type
x	number
y	number

---

GraphConnection

Extended by

• GraphEdge

Properties

Property	Type
source	string
sourceHandle	string
target	string
targetHandle	string

---

GraphNode

Semantic graph node. Contains authored XML metadata, without canvas placement or interaction state.

Properties

Property	Type	Description
id	string	-
element	MaterialXElement	-
inputs	MaterialXNodePortSpec[]	-
outputs	MaterialXNodePortSpec[]	-
type?	string	Inferred output type; absent while the family is ambiguous.
definition?	MaterialXNodeSpec	Concrete fallback for implicit defaults. Does not constrain the inferred type.
candidates?	MaterialXNodeSpec[]	Compatible definition variants for this node.
compoundScope?	string	Document scope containing this compound node’s implementation, when available.

---

GraphEdge

Extends

• GraphConnection

Properties

Property	Type	Inherited from
source	string	GraphConnection.source
sourceHandle	string	GraphConnection.sourceHandle
target	string	GraphConnection.target
targetHandle	string	GraphConnection.targetHandle
id	string	-

---

NodeFamily

Properties

Property	Type	Description
id	string	A representative nodedef identifies the family.
variants	MaterialXNodeSpec[]	-

---

OutputRef

Properties

Property	Type
node	string
output	string

---

InputRef

Properties

Property	Type
node	string
input	string

---

EditorDiagnostic

Properties

Property	Modifier	Type
code	readonly	string
message	readonly	string
scope?	readonly	string
node?	readonly	string
input?	readonly	string

---

EditorSnapshot

Properties

Property	Modifier	Type	Description
document	readonly	ReadonlyMaterialXDocument	-
canUndo	readonly	boolean	-
canRedo	readonly	boolean	-
dirty	readonly	boolean	Whether the document differs from the one last loaded or marked clean.
undoLabel?	readonly	string	-
redoLabel?	readonly	string	-
scope	readonly	string	View state shared by every surface (canvas, toolbar, inspector); never part of undo history.
selection	readonly	readonly string[]	Selected node ids in the current scope, in selection order. Ids of removed nodes drop out.
error?	readonly	string	Message from the last failed command, until the next command succeeds or clears it.

---

EditorSessionOptions

Properties

Property	Type	Description
document	ReadonlyMaterialXDocument	-
catalog?	readonly DeepReadonly<MaterialXNodeSpec>[]	A complete catalog; otherwise derive it from the document and standard registry.
historyLimit?	number	-

---

ResolvedNode

Properties

Property	Type	Description
element	MaterialXElement	-
scope	string	-
family?	NodeFamily	-
candidates	MaterialXNodeSpec[]	-
definition?	MaterialXNodeSpec	A jointly compatible fallback; never an inference constraint.
type?	string	-
inputs	MaterialXNodePortSpec[]	-
outputs	MaterialXNodePortSpec[]	-
conflict	boolean	-

---

TypeResolution

Properties

Property	Type
nodes	Map<string, ResolvedNode>
conflicts	object[]

References

DeepReadonly

Re-exports DeepReadonly

---

ReadonlyMaterialXDocument

Re-exports ReadonlyMaterialXDocument

Type Aliases

InputValue

type InputValue = string | number | boolean | readonly number[];

---

EditorGraph

type EditorGraph = ReturnType<EditorSession["graph"]>;

Variables

structuralSpecs

const structuralSpecs: readonly MaterialXNodeSpec[];

Compound-graph structure the editor adds without a nodedef: a node graph and its interface ports. Ports are untyped until placed.

---

nonNodes

const nonNodes: Set<string>;

Element tags that never appear as graph nodes.