@vizij/node-graph-authoring 0.0.4 → 0.0.5

package/dist/index.d.ts

@@ -1,40 +1,11 @@
-import { NodeType, GraphSpec } from '@vizij/node-graph-wasm';
-import { RigBindingDefinition, RigBindingSlot, BindingValueType, AnimatableComponent, StandardRigInput, RemapSettings, AnimatableValue } from '@vizij/utils';
+import { GraphSpec, NodeType } from '@vizij/node-graph-wasm';
+import { RigBindingDefinition, RigBindingSlot, BindingValueType, AnimatableComponent, StandardRigInput, RemapSettings, AnimatableValue, RigBindingMetadata } from '@vizij/utils';
 export { BindingValueType } from '@vizij/utils';
 
-type BindingOperatorType = "spring" | "damp" | "slew";
-interface BindingOperatorState {
-    type: BindingOperatorType;
-    enabled: boolean;
-    params: Record<string, number>;
-}
-interface BindingOperatorParamDefinition {
-    id: string;
-    label: string;
-    doc?: string;
-    min?: number;
-    max?: number;
-    defaultValue: number;
-}
-interface BindingOperatorDefinition {
-    type: BindingOperatorType;
-    nodeType: NodeType;
-    label: string;
-    description?: string;
-    inputs: string[];
-    params: BindingOperatorParamDefinition[];
-}
-declare function getBindingOperatorDefinition(type: BindingOperatorType): BindingOperatorDefinition;
-declare const bindingOperatorDefinitions: BindingOperatorDefinition[];
-declare function createDefaultOperatorSettings(type: BindingOperatorType): BindingOperatorState;
-declare function ensureOperatorParams(operator: BindingOperatorState): BindingOperatorState;
-declare const bindingOperatorTypes: readonly BindingOperatorType[];
-
 type AnimatableBindingSlot = RigBindingSlot;
 interface AnimatableBinding extends RigBindingDefinition {
     targetId: string;
     slots: AnimatableBindingSlot[];
-    operators?: BindingOperator[];
 }
 interface BindingTarget {
     id: string;
@@ -52,7 +23,6 @@ type InputBindingMap = Record<string, AnimatableBinding>;
 type StandardInputValues = Record<string, number>;
 declare const PRIMARY_SLOT_ID = "s1";
 declare const PRIMARY_SLOT_ALIAS = "s1";
-type BindingOperator = BindingOperatorState;
 declare function createDefaultRemap(target: BindingTarget): RemapSettings;
 declare function createDefaultBindings(components: BindingTarget[]): BindingMap;
 declare function createDefaultBinding(component: BindingTarget): AnimatableBinding;
@@ -63,8 +33,7 @@ declare function getPrimaryBindingSlot(binding: AnimatableBinding): AnimatableBi
 declare function addBindingSlot(binding: AnimatableBinding, target: BindingTarget): AnimatableBinding;
 declare function removeBindingSlot(binding: AnimatableBinding, target: BindingTarget, slotId: string): AnimatableBinding;
 declare function updateBindingSlotAlias(binding: AnimatableBinding, target: BindingTarget, slotId: string, nextAlias: string): AnimatableBinding;
-declare function setBindingOperatorEnabled(binding: AnimatableBinding, type: BindingOperatorType, enabled: boolean): AnimatableBinding;
-declare function updateBindingOperatorParam(binding: AnimatableBinding, type: BindingOperatorType, paramId: string, value: number): AnimatableBinding;
+declare function updateBindingSlotValueType(binding: AnimatableBinding, target: BindingTarget, slotId: string, nextValueType: BindingValueType): AnimatableBinding;
 declare function updateBindingExpression(binding: AnimatableBinding, target: BindingTarget, expression: string): AnimatableBinding;
 declare function updateBindingSlotRemap(binding: AnimatableBinding, target: BindingTarget, slotId: string, field: keyof RemapSettings, value: number): AnimatableBinding;
 declare function updateBindingWithInput(binding: AnimatableBinding, target: BindingTarget, input: StandardRigInput | undefined, slotId?: string): AnimatableBinding;
@@ -72,8 +41,110 @@ declare function remapValue(value: number, remap: RemapSettings): number;
 declare function reconcileBindings(previous: BindingMap, components: BindingTarget[]): BindingMap;
 declare function bindingToDefinition(binding: AnimatableBinding): RigBindingDefinition;
 declare function bindingFromDefinition(target: BindingTarget, definition: RigBindingDefinition | null | undefined): AnimatableBinding;
+declare function buildPiecewiseRemapExpression(alias: string, remap: RemapSettings): string;
+declare function buildDefaultSlotExpression(alias: string, inputId: string | null, remap: RemapSettings): string;
+declare function buildCanonicalBindingExpression(binding: AnimatableBinding): string;
+
+type IrValueType = "scalar" | "vector" | "boolean" | "color" | "quaternion" | "transform" | "unknown";
+interface IrPortRef {
+    nodeId: string;
+    portId?: string;
+    component?: string;
+}
+interface IrNodeInput {
+    id: string;
+    valueType: IrValueType;
+    cardinality?: "single" | "variadic";
+    required?: boolean;
+}
+interface IrNodeOutput {
+    id: string;
+    valueType: IrValueType;
+    cardinality?: "single" | "variadic";
+}
+interface IrNode {
+    id: string;
+    type: string;
+    category?: string;
+    label?: string;
+    description?: string;
+    params?: Record<string, unknown>;
+    inputDefaults?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface IrEdge {
+    id?: string;
+    from: IrPortRef;
+    to: IrPortRef;
+    metadata?: Record<string, unknown>;
+}
+interface IrConstant {
+    id: string;
+    value: number;
+    valueType: IrValueType;
+    metadata?: Record<string, unknown>;
+}
+interface IrIssue {
+    id: string;
+    severity: "error" | "warning" | "info";
+    message: string;
+    targetId?: string;
+    tags?: string[];
+    details?: Record<string, unknown>;
+}
+interface IrBindingSummary {
+    targetId: string;
+    animatableId: string;
+    component?: string;
+    slotId: string;
+    slotAlias: string;
+    inputId: string | null;
+    remap: Record<string, unknown>;
+    expression: string;
+    valueType: "scalar" | "vector";
+    nodeId: string;
+    expressionNodeId: string;
+    issues?: string[];
+}
+interface IrGraphSummary {
+    faceId: string;
+    inputs: string[];
+    outputs: string[];
+    bindings: IrBindingSummary[];
+}
+interface IrGraphMetadata {
+    source: string;
+    registryVersion?: string;
+    generatedAt?: string;
+    annotations?: Record<string, unknown>;
+}
+interface IrLegacyArtifacts {
+    spec?: GraphSpec;
+}
+interface IrGraph {
+    id: string;
+    faceId: string;
+    nodes: IrNode[];
+    edges: IrEdge[];
+    constants: IrConstant[];
+    issues: IrIssue[];
+    summary: IrGraphSummary;
+    metadata: IrGraphMetadata;
+    legacy?: IrLegacyArtifacts;
+}
+interface IrCompileOptions {
+    preferLegacySpec?: boolean;
+}
+interface IrCompileResult {
+    spec: GraphSpec;
+    issues: IrIssue[];
+}
 
 type VectorComponent = "x" | "y" | "z" | "r" | "g" | "b";
+interface InputExportMetadata {
+    source?: "auto" | "custom" | "preset";
+    root?: string;
+}
 interface BuildGraphOptions {
     faceId: string;
     animatables: Record<string, AnimatableValue>;
@@ -81,6 +152,7 @@ interface BuildGraphOptions {
     bindings: BindingMap;
     inputsById: Map<string, StandardRigInput>;
     inputBindings: InputBindingMap;
+    inputMetadata?: Map<string, InputExportMetadata>;
 }
 interface GraphBindingSummary {
     targetId: string;
@@ -92,7 +164,10 @@ interface GraphBindingSummary {
     remap: RemapSettings;
     expression: string;
     valueType: BindingValueType;
+    nodeId: string;
+    expressionNodeId: string;
     issues?: string[];
+    metadata?: RigBindingMetadata;
 }
 interface BuildGraphResult {
     spec: GraphSpec;
@@ -106,12 +181,19 @@ interface BuildGraphResult {
         byTarget: Record<string, string[]>;
         fatal: string[];
     };
+    ir?: {
+        graph: IrGraph;
+        compile: (options?: IrCompileOptions) => IrCompileResult;
+    };
 }
-declare function buildRigGraphSpec({ faceId, animatables, components, bindings, inputsById, inputBindings, }: BuildGraphOptions): BuildGraphResult;
+declare function buildRigGraphSpec({ faceId, animatables, components, bindings, inputsById, inputBindings, inputMetadata, }: BuildGraphOptions): BuildGraphResult;
 
 type ControlExpressionNode = {
     type: "Literal";
     value: number;
+} | {
+    type: "VectorLiteral";
+    values: number[];
 } | {
     type: "Reference";
     name: string;
@@ -143,4 +225,273 @@ declare function parseControlExpression(expression: string): ExpressionParseResu
 declare function collectExpressionReferences(node: ControlExpressionNode | null, target?: Set<string>): Set<string>;
 declare function mapExpression(node: ControlExpressionNode, visit: (node: ControlExpressionNode) => void): void;
 
-export { type AnimatableBinding, type AnimatableBindingSlot, type BindingMap, type BindingOperator, type BindingOperatorDefinition, type BindingOperatorParamDefinition, type BindingOperatorState, type BindingOperatorType, type BindingTarget, type BuildGraphResult, type ControlExpressionNode, type ExpressionParseError, type ExpressionParseResult, type GraphBindingSummary, type InputBindingMap, PRIMARY_SLOT_ALIAS, PRIMARY_SLOT_ID, type StandardInputValues, addBindingSlot, bindingFromDefinition, bindingOperatorDefinitions, bindingOperatorTypes, bindingTargetFromComponent, bindingTargetFromInput, bindingToDefinition, buildRigGraphSpec, collectExpressionReferences, createDefaultBinding, createDefaultBindings, createDefaultInputValues, createDefaultOperatorSettings, createDefaultParentBinding, createDefaultRemap, ensureBindingStructure, ensureOperatorParams, getBindingOperatorDefinition, getPrimaryBindingSlot, mapExpression, parseControlExpression, reconcileBindings, remapValue, removeBindingSlot, setBindingOperatorEnabled, updateBindingExpression, updateBindingOperatorParam, updateBindingSlotAlias, updateBindingSlotRemap, updateBindingWithInput };
+type ExpressionVariableKind = "slot" | "reserved";
+interface SlotVariableMetadata {
+    slotId: string;
+    slotAlias: string;
+    inputId: string | null;
+    targetId: string;
+    animatableId: string;
+    component?: string;
+    valueType: BindingValueType;
+    remap?: RemapSettings;
+    autoRemap?: boolean;
+}
+interface ReservedVariableMetadata {
+    targetId?: string;
+    animatableId?: string;
+    component?: string;
+}
+interface ExpressionVariableEntry {
+    name: string;
+    kind: ExpressionVariableKind;
+    nodeId: string | null;
+    metadata?: SlotVariableMetadata | ReservedVariableMetadata;
+    description?: string;
+}
+interface RegisterSlotVariableOptions extends SlotVariableMetadata {
+    name: string;
+    nodeId: string;
+}
+interface RegisterReservedVariableOptions extends ReservedVariableMetadata {
+    name: string;
+    nodeId: string | null;
+    description?: string;
+}
+interface ExpressionVariableMissing {
+    name: string;
+    reason: "unknown" | "unresolved";
+    entry?: ExpressionVariableEntry;
+}
+interface ExpressionVariableTable {
+    registerSlotVariable(options: RegisterSlotVariableOptions): void;
+    registerReservedVariable(options: RegisterReservedVariableOptions): void;
+    resolve(name: string): ExpressionVariableEntry | null;
+    resolveNodeId(name: string): string | null;
+    entries(): ExpressionVariableEntry[];
+    firstNodeId(): string | null;
+    missing(names: Iterable<string>): ExpressionVariableMissing[];
+}
+declare function createExpressionVariableTable(): ExpressionVariableTable;
+
+type ExpressionFunctionCategory = "math" | "logic" | "time" | "utility" | "vector";
+type ExpressionValueType = "scalar" | "vector" | "boolean" | "any";
+interface OrderedInputSpec {
+    id: string;
+    optional: boolean;
+    valueType: ExpressionValueType;
+}
+interface VariadicInputSpec {
+    id: string;
+    min: number;
+    max: number | null;
+    valueType: ExpressionValueType;
+}
+interface ParamArgumentSpec {
+    id: string;
+    label: string;
+    doc?: string;
+    optional: boolean;
+    valueType: ExpressionValueType;
+    min?: number;
+    max?: number;
+}
+interface ScalarFunctionDefinition {
+    nodeType: NodeType;
+    inputs: OrderedInputSpec[];
+    variadic: VariadicInputSpec | null;
+    params: ParamArgumentSpec[];
+    minArgs: number;
+    maxArgs: number | null;
+    resultValueType: ExpressionValueType;
+}
+interface ScalarFunctionVocabularyEntry {
+    name: string;
+    aliases: string[];
+    nodeType: NodeType;
+    category: ExpressionFunctionCategory;
+    description?: string;
+}
+declare const SCALAR_FUNCTIONS: Map<string, ScalarFunctionDefinition>;
+declare const SCALAR_FUNCTION_VOCABULARY: ScalarFunctionVocabularyEntry[];
+
+type ReservedExpressionScope = "binding" | "graph";
+interface ReservedExpressionVariableDefinition {
+    name: string;
+    description: string;
+    scope: ReservedExpressionScope;
+    defaultValueType?: BindingValueType;
+    available?: boolean;
+}
+declare const RESERVED_EXPRESSION_VARIABLES: ReservedExpressionVariableDefinition[];
+declare const EXPRESSION_FUNCTION_VOCABULARY: ScalarFunctionVocabularyEntry[];
+
+interface IrGraphBuilderOptions {
+    faceId: string;
+    source?: string;
+    registryVersion?: string;
+    generatedAt?: string;
+    annotations?: Record<string, unknown>;
+}
+interface IrGraphBuilder {
+    addNode(node: IrNode): IrNode;
+    addEdge(edge: IrEdge): IrEdge;
+    addConstant(constant: IrConstant): IrConstant;
+    addIssue(issue: IrIssue): IrIssue;
+    setSummary(summary: IrGraphSummary): void;
+    updateMetadata(metadata: Partial<IrGraphMetadata>): void;
+    build(): IrGraph;
+}
+declare function createIrGraphBuilder(options: IrGraphBuilderOptions): IrGraphBuilder;
+interface LegacyIrGraphPayload {
+    faceId: string;
+    summary: IrGraphSummary;
+    issues?: IrIssue[];
+    registryVersion?: string;
+    source?: string;
+    annotations?: Record<string, unknown>;
+    spec: GraphSpec;
+}
+declare function createLegacyIrGraph(payload: LegacyIrGraphPayload): IrGraph;
+declare function toIrBindingSummary(summaries: {
+    targetId: string;
+    animatableId: string;
+    component?: string;
+    slotId: string;
+    slotAlias: string;
+    inputId: string | null;
+    remap: Record<string, unknown>;
+    expression: string;
+    valueType: "scalar" | "vector";
+    issues?: string[];
+    nodeId: string;
+    expressionNodeId: string;
+}[]): IrBindingSummary[];
+
+/**
+ * Compile an IR graph into a runtime-ready GraphSpec. The current implementation
+ * falls back to any legacy GraphSpec that was attached during migration,
+ * allowing the IR surface to land incrementally while the dedicated compiler
+ * is built.
+ */
+declare function compileIrGraph(graph: IrGraph, options?: IrCompileOptions): IrCompileResult;
+
+declare const MACHINE_REPORT_VERSION = 1;
+interface MachineReport {
+    reportVersion: number;
+    faceId: string;
+    summary: MachineSummary;
+    issues: MachineIssues;
+    irGraph?: NormalizedIrGraph;
+}
+interface MachineSummary {
+    faceId: string;
+    inputs: string[];
+    outputs: string[];
+    bindings: MachineBindingSummary[];
+}
+interface MachineBindingSummary {
+    targetId: string;
+    animatableId: string;
+    component?: string;
+    slotId: string;
+    slotAlias: string;
+    inputId: string | null;
+    remap: RemapSettings;
+    expression: string;
+    valueType: "scalar" | "vector";
+    nodeId: string;
+    expressionNodeId: string;
+    issues?: string[];
+    metadata?: RigBindingMetadata;
+}
+interface MachineIssues {
+    fatal: string[];
+    byTarget: Record<string, string[]>;
+}
+interface NormalizedIrGraph {
+    id: string;
+    faceId: string;
+    nodes: NormalizedIrNode[];
+    edges: NormalizedIrEdge[];
+    constants: NormalizedIrConstant[];
+    issues: NormalizedIrIssue[];
+    summary: NormalizedIrGraphSummary;
+    metadata: NormalizedIrGraphMetadata;
+}
+interface NormalizedIrNode extends IrNode {
+    annotations?: NodeInspectionAnnotations;
+}
+type NormalizedIrEdge = IrEdge;
+type NormalizedIrConstant = IrConstant;
+type NormalizedIrIssue = IrIssue & {
+    tags?: string[];
+};
+interface NormalizedIrGraphSummary extends IrGraphSummary {
+    bindings: NormalizedIrBindingSummary[];
+}
+type NormalizedIrBindingSummary = IrBindingSummary & {
+    issues?: string[];
+};
+interface NormalizedIrGraphMetadata {
+    source: string;
+    registryVersion?: string;
+    annotations?: Record<string, unknown>;
+}
+interface NodeInspectionAnnotations {
+    registry?: NormalizedRegistrySignature;
+}
+interface NormalizedRegistrySignature {
+    typeId: NodeType;
+    name: string;
+    category: string;
+    doc?: string;
+    inputs: NormalizedRegistryPortSpec[];
+    variadicInputs?: NormalizedRegistryVariadicSpec;
+    outputs: NormalizedRegistryPortSpec[];
+    variadicOutputs?: NormalizedRegistryVariadicSpec;
+    params: NormalizedRegistryParamSpec[];
+}
+interface NormalizedRegistryPortSpec {
+    id: string;
+    label: string;
+    doc?: string;
+    optional?: boolean;
+    type: string;
+}
+interface NormalizedRegistryVariadicSpec {
+    id: string;
+    label: string;
+    doc?: string;
+    type: string;
+    min: number;
+    max?: number;
+}
+interface NormalizedRegistryParamSpec {
+    id: string;
+    label: string;
+    doc?: string;
+    type: string;
+    defaultValue?: unknown;
+    min?: number;
+    max?: number;
+}
+type DiffKind = "mismatch" | "missing" | "unexpected";
+interface MachineDiffEntry {
+    kind: DiffKind;
+    path: string;
+    actual?: unknown;
+    expected?: unknown;
+}
+interface MachineDiffResult {
+    equal: boolean;
+    differences: MachineDiffEntry[];
+    limitReached: boolean;
+}
+interface MachineDiffOptions {
+    limit?: number;
+}
+declare function buildMachineReport(result: BuildGraphResult): MachineReport;
+declare function diffMachineReports(actual: MachineReport, expected: MachineReport, options?: MachineDiffOptions): MachineDiffResult;
+
+export { type AnimatableBinding, type AnimatableBindingSlot, type BindingMap, type BindingTarget, type BuildGraphOptions, type BuildGraphResult, type ControlExpressionNode, type DiffKind, EXPRESSION_FUNCTION_VOCABULARY, type ExpressionFunctionCategory, type ExpressionParseError, type ExpressionParseResult, type ExpressionValueType, type ExpressionVariableEntry, type ExpressionVariableKind, type ExpressionVariableMissing, type ExpressionVariableTable, type GraphBindingSummary, type InputBindingMap, type IrBindingSummary, type IrCompileOptions, type IrCompileResult, type IrConstant, type IrEdge, type IrGraph, type IrGraphBuilder, type IrGraphBuilderOptions, type IrGraphMetadata, type IrGraphSummary, type IrIssue, type IrLegacyArtifacts, type IrNode, type IrNodeInput, type IrNodeOutput, type IrPortRef, type IrValueType, type LegacyIrGraphPayload, MACHINE_REPORT_VERSION, type MachineBindingSummary, type MachineDiffEntry, type MachineDiffOptions, type MachineDiffResult, type MachineIssues, type MachineReport, type MachineSummary, type NodeInspectionAnnotations, type NormalizedIrBindingSummary, type NormalizedIrConstant, type NormalizedIrEdge, type NormalizedIrGraph, type NormalizedIrGraphMetadata, type NormalizedIrGraphSummary, type NormalizedIrIssue, type NormalizedIrNode, type NormalizedRegistryParamSpec, type NormalizedRegistryPortSpec, type NormalizedRegistrySignature, type NormalizedRegistryVariadicSpec, PRIMARY_SLOT_ALIAS, PRIMARY_SLOT_ID, RESERVED_EXPRESSION_VARIABLES, type RegisterReservedVariableOptions, type RegisterSlotVariableOptions, type ReservedExpressionScope, type ReservedExpressionVariableDefinition, type ReservedVariableMetadata, SCALAR_FUNCTIONS, SCALAR_FUNCTION_VOCABULARY, type ScalarFunctionDefinition, type ScalarFunctionVocabularyEntry, type SlotVariableMetadata, type StandardInputValues, addBindingSlot, bindingFromDefinition, bindingTargetFromComponent, bindingTargetFromInput, bindingToDefinition, buildCanonicalBindingExpression, buildDefaultSlotExpression, buildMachineReport, buildPiecewiseRemapExpression, buildRigGraphSpec, collectExpressionReferences, compileIrGraph, createDefaultBinding, createDefaultBindings, createDefaultInputValues, createDefaultParentBinding, createDefaultRemap, createExpressionVariableTable, createIrGraphBuilder, createLegacyIrGraph, diffMachineReports, ensureBindingStructure, getPrimaryBindingSlot, mapExpression, parseControlExpression, reconcileBindings, remapValue, removeBindingSlot, toIrBindingSummary, updateBindingExpression, updateBindingSlotAlias, updateBindingSlotRemap, updateBindingSlotValueType, updateBindingWithInput };