@womp/spark-agent 9.0.0 → 9.1.0

package/dist/materials/types.d.ts

@@ -101,9 +101,24 @@ export type MaterialWriteResult = {
         color: MaterialVector;
         exposed?: boolean;
     }[];
+    /** Parameter overrides reset by a FlowIR replacement. */
+    diagnostics?: string[];
     status: "applied";
     rendering: "unverified";
 };
+export type MaterialProgramWrite = {
+    materialId?: number;
+    cloneFrom?: number;
+    layerIndex: number;
+    source: string;
+    objectIds?: number[];
+};
+export type MaterialProgramRead = {
+    materialId: number;
+    layerIndex: number;
+    source: string | null;
+    diagnostics: string[];
+};
 export type MaterialNodeOptions = {
     op: string;
     name?: string;

package/dist/sdk-materials-host.js

@@ -1,5 +1,8 @@
 import { sparkErrorDiagnostics } from "./error-diagnostics.js";
-import { graphSchema, materialId, parseMaterialCatalog, validateMaterialGraph, writeSchema, value3, } from "./materials/graph.js";
+import { graphSchema, materialId, parseMaterialCatalog, validateMaterialGraph, writeSchema, programWriteSchema, value3, } from "./materials/graph.js";
+import { comparableMaterialGraph, compileMaterialFlowir } from "./materials/flowir.js";
+import { liftMaterialFlowir } from "./materials/lift.js";
+import { boundedDiagnostics } from "./geometry/diagnostics.js";
 function record(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error(`Invalid ${label}`);
@@ -115,7 +118,7 @@ export function createSdkMaterialsHost(options) {
             ],
         };
     };
-    return {
+    const host = {
         catalog: (settings, context) => options.editor.read(context, async (api) => {
             const nodes = await catalogue(api, context, settings.refreshTextures === true);
             const selected = {};
@@ -200,7 +203,7 @@ export function createSdkMaterialsHost(options) {
                 explanation: "A zero queue does not prove compilation, texture loading or the new rendered appearance succeeded. Inspect a scene screenshot.",
             };
         }),
-        write: async (input, context) => {
+        write: async (input, context, program) => {
             const request = writeSchema.parse(input);
             await options.assertAvailable(context);
             let resultId = request.materialId;
@@ -211,7 +214,8 @@ export function createSdkMaterialsHost(options) {
             }, async (api, draft) => {
                 await options.assertAvailable(context);
                 context.signal.throwIfAborted();
-                if (request.materialId !== undefined &&
+                if (program === undefined &&
+                    request.materialId !== undefined &&
                     request.layers === undefined &&
                     request.constants === undefined) {
                     draft.getMaterial(request.materialId);
@@ -226,12 +230,58 @@ export function createSdkMaterialsHost(options) {
                 const catalog = await catalogue(api, context, false);
                 const sourceId = request.materialId ?? request.cloneFrom;
                 const original = sourceId === undefined ? undefined : rawMaterial(draft, sourceId);
-                const graphs = (request.layers ??
-                    (sourceId === undefined ? [] : layers(draft, sourceId))).map((graph) => graph === null ? null : validateMaterialGraph(graph, catalog));
-                let rewriteGraphs = request.layers !== undefined || request.materialId === undefined;
+                const sourceLayers = sourceId === undefined ? [] : layers(draft, sourceId);
+                const proposedLayers = program ? [...sourceLayers] : request.layers ?? sourceLayers;
+                let programSymbols;
+                const programDiagnostics = [];
+                if (program) {
+                    while (proposedLayers.length <= program.layerIndex)
+                        proposedLayers.push(null);
+                    const compiled = compileMaterialFlowir(program.source, catalog);
+                    const replacement = compiled.graph;
+                    programSymbols = compiled.symbols;
+                    const previous = sourceLayers[program.layerIndex];
+                    for (const node of replacement.nodes) {
+                        const matches = previous?.nodes.filter(candidate => candidate.op === node.op && candidate.name === node.name) ?? [];
+                        const old = matches.length === 1 ? matches[0] : undefined;
+                        if (!old || node.name === undefined)
+                            continue;
+                        if (old.location !== undefined)
+                            node.location = old.location;
+                        if (old.editor_flags !== undefined)
+                            node.editor_flags = old.editor_flags;
+                        if (node.op !== "Constant")
+                            continue;
+                        const exposure = node.in3.x;
+                        const oldExposure = old.in3?.x ?? 0;
+                        const nodeSlot = replacement.connections.find(edge => edge.input_node === replacement.nodes.indexOf(node))?.input_slot;
+                        const oldSlot = previous?.connections.find(edge => edge.input_node === previous.nodes.indexOf(old))?.input_slot;
+                        const vectorWidget = exposure === 1 && oldExposure === 2 && oldSlot === 1;
+                        const compatible = (nodeSlot === oldSlot && exposure === oldExposure) || vectorWidget;
+                        if (compatible) {
+                            if (vectorWidget) {
+                                node.in1 = node.in2;
+                                delete node.in2;
+                                for (const edge of replacement.connections)
+                                    if (edge.input_node === replacement.nodes.indexOf(node) && edge.input_slot === 2)
+                                        edge.input_slot = 1;
+                            }
+                            if (old.reference_id !== undefined)
+                                node.reference_id = old.reference_id;
+                            if (old.in3 !== undefined)
+                                node.in3 = old.in3;
+                        }
+                    }
+                    for (const option of previous?.nodes.filter(node => node.op === "Options") ?? [])
+                        replacement.nodes.push(option);
+                    proposedLayers[program.layerIndex] = replacement;
+                }
+                const graphs = proposedLayers.map((graph, slot) => graph === null ? null : program && slot !== program.layerIndex ? graph : validateMaterialGraph(graph, catalog));
+                let rewriteGraphs = program !== undefined || request.layers !== undefined || request.materialId === undefined;
                 const used = allReferences(draft);
                 const refs = new Map();
-                for (const graph of graphs)
+                const changedGraphs = program && request.materialId !== undefined ? [graphs[program.layerIndex]] : graphs;
+                for (const graph of changedGraphs)
                     for (const node of graph?.nodes ?? [])
                         if (node.op === "Constant") {
                             const id = typeof node.reference_id === "number" && node.reference_id > 0
@@ -249,6 +299,18 @@ export function createSdkMaterialsHost(options) {
                     ? record(original.data, "material data")
                     : undefined;
                 const constants = record(sourceData?.constants ?? {}, "material constants");
+                if (program) {
+                    const retained = new Set(graphs.flatMap(graph => graph?.nodes.filter(node => node.op === "Constant").map(node => String(node.reference_id)) ?? []));
+                    for (const node of sourceLayers[program.layerIndex]?.nodes ?? []) {
+                        if (node.op !== "Constant" || retained.has(String(node.reference_id)))
+                            continue;
+                        const key = String(node.reference_id);
+                        if (constants[key] !== undefined) {
+                            delete constants[key];
+                            programDiagnostics.push(`Reset override for ${String(node.name ?? key)}: parameter removed or type changed.`);
+                        }
+                    }
+                }
                 const referenceIdChanges = {};
                 for (const [key, override] of Object.entries(request.constants ?? {})) {
                     const node = refs.get(Number(key));
@@ -264,7 +326,7 @@ export function createSdkMaterialsHost(options) {
                     // Replaced graphs can reuse IDs whose deleted overrides remain in the native cache.
                     if (request.constants?.[key] === null ||
                         (request.materialId !== undefined &&
-                            request.layers !== undefined &&
+                            (request.layers !== undefined || program !== undefined) &&
                             constants[key] === undefined)) {
                         const id = freshReference(used);
                         rewriteGraphs = true;
@@ -286,6 +348,8 @@ export function createSdkMaterialsHost(options) {
                 const slots = graphs.map((graph, slot) => {
                     if (graph === null)
                         return 0;
+                    if (program && request.materialId !== undefined && slot !== program.layerIndex)
+                        return materialId.parse(oldSlots[slot]);
                     if (!rewriteGraphs)
                         return materialId.parse(oldSlots[slot]);
                     const oldId = oldSlots[slot];
@@ -310,6 +374,30 @@ export function createSdkMaterialsHost(options) {
                 });
                 while (slots.length < 8)
                     slots.push(0);
+                if (program) {
+                    const ext = draft.getSceneExt();
+                    if (!ext.shadersExt)
+                        draft.patchSceneExt([{ op: "add", path: "/shadersExt", value: {} }], { returnScene: false });
+                    const previousMetadata = ext.shadersExt;
+                    if (request.cloneFrom !== undefined)
+                        for (let slot = 0; slot < slots.length; slot++) {
+                            if (slot === program.layerIndex || !slots[slot])
+                                continue;
+                            const originalShader = oldSlots[slot];
+                            const metadata = previousMetadata?.[String(originalShader)];
+                            if (metadata !== undefined)
+                                draft.patchSceneExt([{ op: "add", path: `/shadersExt/${slots[slot]}`, value: metadata }], { returnScene: false });
+                        }
+                    draft.patchSceneExt([{
+                            op: "add",
+                            path: `/shadersExt/${slots[program.layerIndex]}`,
+                            value: {
+                                ...record(previousMetadata?.[String(oldSlots[program.layerIndex])] ?? {}, "shader metadata"),
+                                flowirSource: program.source,
+                                flowirSymbols: programSymbols,
+                            },
+                        }], { returnScene: false });
+                }
                 patchEntry(draft, "materials", resultId, {
                     ...target,
                     ...(original ?? {}),
@@ -339,7 +427,8 @@ export function createSdkMaterialsHost(options) {
                     materialId: resultId,
                     objectIds: directUsers(draft, resultId),
                     referenceIdChanges,
-                    parameters: graphs.flatMap(graph => graph?.nodes.filter(node => node.op === "Constant").map(node => {
+                    ...(program ? { diagnostics: boundedDiagnostics(programDiagnostics) } : {}),
+                    parameters: (program ? changedGraphs : graphs).flatMap(graph => graph?.nodes.filter(node => node.op === "Constant").map(node => {
                         const referenceId = node.reference_id;
                         const override = constants[String(referenceId)];
                         return { name: node.name ?? "", referenceId,
@@ -356,5 +445,42 @@ export function createSdkMaterialsHost(options) {
                 rendering: "unverified",
             };
         },
+        writeProgram: async (input, context) => {
+            const request = programWriteSchema.parse(input);
+            return host.write({
+                ...(request.materialId === undefined ? {} : { materialId: request.materialId }),
+                ...(request.cloneFrom === undefined ? {} : { cloneFrom: request.cloneFrom }),
+                ...(request.objectIds === undefined ? {} : { objectIds: request.objectIds }),
+            }, context, request);
+        },
+        readProgram: async (material, layerIndex, context) => options.editor.read(context, async (api) => {
+            await options.assertAvailable(context);
+            context.signal.throwIfAborted();
+            const id = materialId.parse(material);
+            if (!Number.isInteger(layerIndex) || layerIndex < 0 || layerIndex > 7)
+                throw new Error("layerIndex must be within 0..7");
+            const materialData = rawMaterial(api, id);
+            const shaderId = Array.isArray(materialData.shaders) ? materialData.shaders[layerIndex] : undefined;
+            if (typeof shaderId !== "number" || shaderId <= 0)
+                return { materialId: id, layerIndex, source: null, diagnostics: ["This layer is empty."] };
+            const metadata = api.getSceneExt().shadersExt?.[String(shaderId)];
+            const source = metadata?.flowirSource;
+            const catalog = await catalogue(api, context, false);
+            const actual = layers(api, id)[layerIndex];
+            if (!actual)
+                return { materialId: id, layerIndex, source: null, diagnostics: ["This layer is empty."] };
+            try {
+                if (typeof source === "string") {
+                    const rebuilt = compileMaterialFlowir(source, catalog).graph;
+                    if (comparableMaterialGraph(rebuilt) === comparableMaterialGraph(actual))
+                        return { materialId: id, layerIndex, source, diagnostics: [] };
+                }
+                return { materialId: id, layerIndex, source: liftMaterialFlowir(actual, catalog), diagnostics: [] };
+            }
+            catch (error) {
+                return { materialId: id, layerIndex, source: null, diagnostics: boundedDiagnostics([sparkErrorDiagnostics(error).message]) };
+            }
+        }),
     };
+    return host;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",
@@ -74,6 +74,7 @@
     "dist/**/*.d.ts",
     "dist/server/fixtures/**/*.json",
     "dist/geometry/schemas/**/*.json",
+    "dist/materials/schemas/**/*.json",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -105,6 +106,7 @@
     "web:build": "yarn build && tsc --noEmit -p web/tsconfig.json && vite build --config web/vite.config.ts",
     "test": "yarn build && tsx --tsconfig tsconfig.json --test test/**/*.test.ts && node --input-type=module -e \"await Promise.all([import('@womp/spark-agent'), import('@womp/spark-agent/ui'), import('@womp/spark-agent/client'), import('@womp/spark-agent/server'), import('@womp/spark-agent/express'), import('@womp/spark-agent/kakapo'), import('@womp/spark-agent/geometry'), import('@womp/spark-agent/openscad')])\"",
     "test:live": "tsx --tsconfig tsconfig.json test/womp-scene-api.live.ts",
+    "test:live:materials": "tsx --tsconfig tsconfig.json test/materials-flowir.live.ts",
     "prepack": "yarn build",
     "release:pack": "node scripts/npm-release.mjs pack"
   },