@womp/spark-agent 5.2.2 → 5.3.0

package/dist/scene-operations.js

@@ -41,13 +41,13 @@ export async function recoverSceneOperation(options) {
     }
     return previous;
 }
-/** The host owns connection/target validation and execution exclusivity. Never replays an existing edit. */
+/** Hosts may omit persistence; journal-backed hosts retain duplicate-operation protection. */
 export async function executeSceneOperation(options) {
     const { api, store, operation: identity } = options;
     const savesScene = options.saveToRenderer === true;
     await options.assertEditable();
-    const previous = await store.getSceneOperation(identity.targetKey, identity.id);
-    if (previous) {
+    const previous = await store?.getSceneOperation(identity.targetKey, identity.id);
+    if (previous && store) {
         if ((previous.save !== undefined) !== savesScene)
             throw new Error("Scene operation identity was reused with a different save policy");
         if (previous.status === "committed")
@@ -65,7 +65,7 @@ export async function executeSceneOperation(options) {
         ...identity, revision: 0, status: "started",
         ...(savesScene ? { save: { status: "unknown" } } : {}),
     };
-    if (!await store.createSceneOperation(operation))
+    if (store && !await store.createSceneOperation(operation))
         throw new Error("Scene operation is already in progress");
     try {
         const edit = async (draft) => {
@@ -77,10 +77,12 @@ export async function executeSceneOperation(options) {
             save: savesScene,
             beforeCommit: async (changed) => {
                 await options.assertEditable();
-                operation = await store.saveSceneOperation({
+                operation = {
                     ...operation, status: "prepared", changed,
                     ...(savesScene && !changed ? { save: { status: "not_needed" } } : {}),
-                });
+                };
+                if (store)
+                    operation = await store.saveSceneOperation(operation);
                 await options.assertEditable();
                 if (changed)
                     await options.prepareCommit?.(operation);
@@ -88,18 +90,23 @@ export async function executeSceneOperation(options) {
         });
         if (savesScene)
             operation = { ...operation, save: committed.save };
+        operation = complete(operation, "committed");
+        options.onOutcome?.(operation);
         if (committed.changed)
             options.onCommittedScene?.(committed.scene);
     }
     catch (error) {
-        const status = error instanceof KakapoSceneCommitError ? error.outcome
-            : "rolled_back";
+        const status = operation.status === "committed" ? "committed"
+            : error instanceof KakapoSceneCommitError ? error.outcome : "rolled_back";
         try {
-            await store.saveSceneOperation({
+            operation = {
                 ...(status === "rolled_back" ? complete(operation, status) : { ...operation, status }),
                 error: error instanceof Error ? error.message : String(error),
                 ...(operation.save && status === "rolled_back" ? { save: { status: "not_needed" } } : {}),
-            });
+            };
+            options.onOutcome?.(operation);
+            if (store)
+                operation = await store.saveSceneOperation(operation);
         }
         catch {
             // Keep the original error; recovery can inspect the prepared record.
@@ -107,6 +114,7 @@ export async function executeSceneOperation(options) {
         throw error;
     }
     // A prepared record alone never proves an uncertain commit succeeded.
-    operation = await store.saveSceneOperation(complete(operation, "committed"));
+    if (store)
+        operation = await store.saveSceneOperation(complete(operation, "committed"));
     return { value: resultValue(operation), operation };
 }

package/dist/sdk-geometry-host.js

@@ -1,3 +1,4 @@
+import { SceneOperationError } from "./sdk-scene-host.js";
 import { compileGeometry, migrateGraphExt, readEditableGeometry, } from "./geometry/compiler.js";
 import { graphExtSchema } from "./geometry/graph.js";
 import { boundedDiagnostics } from "./geometry/diagnostics.js";
@@ -264,7 +265,8 @@ export function createSdkGeometryHost(options) {
                 }
                 catch (error) {
                     if (operationId !== undefined && target.graphId !== undefined) {
-                        const operation = await editor.getOperation(operationId);
+                        const operation = error instanceof SceneOperationError
+                            ? error.operation : await editor.getOperation(operationId);
                         if (operation?.status === "rolled_back")
                             await repairs.refund(String(target.graphId), operationId);
                     }

package/dist/sdk-materials-host.d.ts

@@ -0,0 +1,9 @@
+import type { SparkInvocationContext } from "./capabilities.js";
+import type { MaterialsHost } from "./capabilities/materials.js";
+import type { SdkSceneEditor } from "./sdk-scene-host.js";
+export type SdkMaterialsHostOptions = {
+    editor: SdkSceneEditor;
+    /** Host-owned procedural-material entitlement/availability check, run for reads and writes. */
+    assertAvailable(context: SparkInvocationContext): void | Promise<void>;
+};
+export declare function createSdkMaterialsHost(options: SdkMaterialsHostOptions): MaterialsHost;

package/dist/sdk-materials-host.js

@@ -0,0 +1,360 @@
+import { sparkErrorDiagnostics } from "./error-diagnostics.js";
+import { graphSchema, materialId, parseMaterialCatalog, validateMaterialGraph, writeSchema, value3, } from "./materials/graph.js";
+function record(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`Invalid ${label}`);
+    return value;
+}
+function storage(source) {
+    const data = source.getSceneStorage();
+    return {
+        materials: record(data.materials ?? {}, "material storage"),
+        shaders: record(data.shaders ?? {}, "shader storage"),
+    };
+}
+function rawMaterial(source, id) {
+    return record(storage(source).materials[String(id)], `material ${id}`);
+}
+function layers(source, id) {
+    const data = storage(source);
+    const material = rawMaterial(source, id);
+    if (material.shaders === undefined)
+        return [];
+    if (!Array.isArray(material.shaders) || material.shaders.length > 8)
+        throw new Error(`Material ${id} has invalid shader slots`);
+    return material.shaders.map((value) => value === 0
+        ? null
+        : graphSchema.parse(data.shaders[String(materialId.parse(value))]));
+}
+function directUsers(source, id) {
+    return source
+        .listNodes()
+        .filter((node) => ("materialId" in node && node.materialId === id) ||
+        (node.kind === "curve" && node.points.some((p) => p.materialId === id)))
+        .map((node) => node.id);
+}
+function unusedId(entries) {
+    for (let id = 1; id <= 65535; id++)
+        if (!(String(id) in entries))
+            return id;
+    throw new Error("No free 16-bit shader IDs remain");
+}
+function freshReference(used) {
+    // Same reference IDs survive save/reopen; random IDs also avoid retired native cache entries.
+    for (;;) {
+        const bits = globalThis.crypto.getRandomValues(new Uint32Array(2));
+        const id = (bits[0] & 0x1fffff) * 4294967296 + bits[1];
+        if (id > 0 && !used.has(id)) {
+            used.add(id);
+            return id;
+        }
+    }
+}
+function allReferences(source) {
+    const data = storage(source);
+    const used = new Set();
+    for (const graph of Object.values(data.shaders)) {
+        const nodes = record(graph, "shader").nodes;
+        if (Array.isArray(nodes))
+            for (const node of nodes) {
+                if (node &&
+                    typeof node === "object" &&
+                    !Array.isArray(node) &&
+                    typeof node.reference_id === "number")
+                    used.add(node.reference_id);
+            }
+    }
+    for (const material of Object.values(data.materials)) {
+        const constants = record(record(material, "material").data, "material data").constants;
+        if (constants && typeof constants === "object")
+            for (const id of Object.keys(constants))
+                used.add(Number(id));
+    }
+    return used;
+}
+function patchEntry(draft, collection, id, value) {
+    if (!(collection in draft.getSceneStorage()))
+        draft.patchSceneStorage([{ op: "add", path: `/${collection}`, value: {} }]);
+    draft.patchSceneStorage([
+        { op: "add", path: `/${collection}/${id}`, value: value },
+    ]);
+}
+export function createSdkMaterialsHost(options) {
+    const initialized = new WeakSet();
+    const catalogue = async (api, context, refresh) => {
+        await options.assertAvailable(context);
+        context.signal.throwIfAborted();
+        if (refresh || !initialized.has(api)) {
+            await api.rpc("reload_textures", []);
+            context.signal.throwIfAborted();
+            initialized.add(api);
+        }
+        const nodes = parseMaterialCatalog(await api.rpc("get_procedural_nodes", []));
+        context.signal.throwIfAborted();
+        return nodes;
+    };
+    const snapshot = async (api, id) => {
+        const items = api.listMaterials().map((material) => ({
+            id: material.id,
+            shaderIds: material.shaderIds,
+            objectIds: directUsers(api, material.id),
+        }));
+        return {
+            materials: items,
+            ...(id === undefined
+                ? {}
+                : {
+                    material: {
+                        id,
+                        data: record(rawMaterial(api, id).data, "material data"),
+                        layers: layers(api, id),
+                    },
+                }),
+            diagnostics: [
+                "Object IDs list direct assignments and curve points. Geometry Nodes/OpenSCAD can also refer to a material ID; existing-material edits affect all references.",
+            ],
+        };
+    };
+    return {
+        catalog: (settings, context) => options.editor.read(context, async (api) => {
+            const nodes = await catalogue(api, context, settings.refreshTextures === true);
+            const selected = {};
+            for (const op of settings.operations ?? []) {
+                if (!nodes[op])
+                    throw new Error(`Material operation ${op} is unavailable`);
+                selected[op] = nodes[op];
+            }
+            return {
+                operations: Object.entries(nodes).map(([op, node]) => ({
+                    op,
+                    category: node.type,
+                    title: node.title,
+                })),
+                nodes: selected,
+                textureCount: nodes.PredefinedTexture?.inputs[2]?.values?.length ?? 0,
+                ...(settings.includeTextures
+                    ? {
+                        textures: nodes.PredefinedTexture?.inputs[2]?.values ?? [],
+                        textureMetadata: {
+                            channels: "unknown",
+                            colorSpace: "unknown",
+                            normalConvention: "unknown",
+                            reason: "The SDK texture catalogue supplies names, not channel or encoding metadata.",
+                        },
+                    }
+                    : {}),
+            };
+        }),
+        read: (id, context) => options.editor.read(context, async (api) => {
+            await options.assertAvailable(context);
+            context.signal.throwIfAborted();
+            return snapshot(api, id === undefined ? undefined : materialId.parse(id));
+        }),
+        status: (context) => options.editor.read(context, async (api) => {
+            await options.assertAvailable(context);
+            context.signal.throwIfAborted();
+            const errors = [];
+            let remaining = null;
+            let pendingResources = null;
+            try {
+                const result = await api.rpc("get_procedural_materials_progress", []);
+                const data = record(typeof result === "string" ? JSON.parse(result) : result, "compiler progress");
+                if (typeof data.remaining !== "number" ||
+                    !Number.isSafeInteger(data.remaining) || data.remaining < 0)
+                    throw new Error("Invalid compiler progress counter");
+                remaining = data.remaining;
+            }
+            catch (error) {
+                context.signal.throwIfAborted();
+                errors.push({ source: "compiler-progress", message: sparkErrorDiagnostics(error).message });
+            }
+            context.signal.throwIfAborted();
+            await options.assertAvailable(context);
+            context.signal.throwIfAborted();
+            try {
+                const pending = record(await api.getPendingResources(), "pending resources");
+                const validated = {};
+                for (const [kind, names] of Object.entries(pending)) {
+                    if (!Array.isArray(names) || !names.every((name) => typeof name === "string"))
+                        throw new Error("Invalid pending resource list");
+                    Object.defineProperty(validated, kind, { value: names, enumerable: true });
+                }
+                pendingResources = validated;
+            }
+            catch (error) {
+                context.signal.throwIfAborted();
+                errors.push({ source: "pending-resources", message: sparkErrorDiagnostics(error).message });
+            }
+            context.signal.throwIfAborted();
+            await options.assertAvailable(context);
+            context.signal.throwIfAborted();
+            return {
+                remaining,
+                pendingResources,
+                errors,
+                shaderDiagnostics: {
+                    status: "unavailable",
+                    reason: "The current SDK/native RPC exposes global queue length, not per-shader compiler results or errors bound to a scene revision.",
+                },
+                rendering: "unverified",
+                explanation: "A zero queue does not prove compilation, texture loading or the new rendered appearance succeeded. Inspect a scene screenshot.",
+            };
+        }),
+        write: async (input, context) => {
+            const request = writeSchema.parse(input);
+            await options.assertAvailable(context);
+            let resultId = request.materialId;
+            const edited = await options.editor.access({
+                capability: "materials",
+                operation: "write",
+                target: () => resultId === undefined ? {} : { materialId: resultId },
+            }, async (api, draft) => {
+                await options.assertAvailable(context);
+                context.signal.throwIfAborted();
+                if (request.materialId !== undefined &&
+                    request.layers === undefined &&
+                    request.constants === undefined) {
+                    draft.getMaterial(request.materialId);
+                    for (const id of request.objectIds ?? [])
+                        draft.setNodeMaterial(id, request.materialId);
+                    return {
+                        materialId: request.materialId,
+                        objectIds: directUsers(draft, request.materialId),
+                        referenceIdChanges: {},
+                    };
+                }
+                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 used = allReferences(draft);
+                const refs = new Map();
+                for (const graph of graphs)
+                    for (const node of graph?.nodes ?? [])
+                        if (node.op === "Constant") {
+                            const id = typeof node.reference_id === "number" && node.reference_id > 0
+                                ? node.reference_id
+                                : freshReference(used);
+                            if (refs.has(id))
+                                throw new Error(`Constant reference ${id} is duplicated across layers; give independent constants unique IDs`);
+                            if (node.reference_id !== id)
+                                rewriteGraphs = true;
+                            node.reference_id = id;
+                            used.add(id);
+                            refs.set(id, node);
+                        }
+                const sourceData = original
+                    ? record(original.data, "material data")
+                    : undefined;
+                const constants = record(sourceData?.constants ?? {}, "material constants");
+                const referenceIdChanges = {};
+                for (const [key, override] of Object.entries(request.constants ?? {})) {
+                    const node = refs.get(Number(key));
+                    if (!node)
+                        throw new Error(`Constant reference ${key} does not exist in the resulting layers`);
+                    if (override === null)
+                        delete constants[key];
+                    else
+                        constants[key] = override;
+                }
+                for (const [reference, node] of refs) {
+                    const key = String(reference);
+                    // Replaced graphs can reuse IDs whose deleted overrides remain in the native cache.
+                    if (request.constants?.[key] === null ||
+                        (request.materialId !== undefined &&
+                            request.layers !== undefined &&
+                            constants[key] === undefined)) {
+                        const id = freshReference(used);
+                        rewriteGraphs = true;
+                        node.reference_id = id;
+                        referenceIdChanges[key] = id;
+                    }
+                }
+                context.signal.throwIfAborted();
+                if (resultId === undefined)
+                    resultId = materialId.parse(draft.createMaterial(sourceId === undefined
+                        ? undefined
+                        : api.getMaterial(sourceId).data, Array(8).fill(0)).id);
+                const target = rawMaterial(draft, resultId);
+                const data = sourceData ?? record(target.data, "material data");
+                // Keep complete override pairs; unoverridden replacement nodes use fresh references.
+                data.constants = constants;
+                const current = storage(draft);
+                const oldSlots = original && Array.isArray(original.shaders) ? original.shaders : [];
+                const slots = graphs.map((graph, slot) => {
+                    if (graph === null)
+                        return 0;
+                    if (!rewriteGraphs)
+                        return materialId.parse(oldSlots[slot]);
+                    const oldId = oldSlots[slot];
+                    const references = Object.values(current.materials).reduce((count, entry) => {
+                        const ids = record(entry, "material").shaders;
+                        return (count +
+                            (Array.isArray(ids)
+                                ? ids.filter((id) => id === oldId).length
+                                : 0));
+                    }, 0);
+                    // A clone or shared shader gets independent storage; other materials keep their graph.
+                    const shaderId = request.materialId !== undefined &&
+                        typeof oldId === "number" &&
+                        oldId > 0 &&
+                        references === 1
+                        ? materialId.parse(oldId)
+                        : unusedId(current.shaders);
+                    current.shaders[String(shaderId)] =
+                        graph;
+                    patchEntry(draft, "shaders", shaderId, graph);
+                    return shaderId;
+                });
+                while (slots.length < 8)
+                    slots.push(0);
+                patchEntry(draft, "materials", resultId, {
+                    ...target,
+                    ...(original ?? {}),
+                    data,
+                    shaders: slots,
+                });
+                if (request.cloneFrom !== undefined) {
+                    const ext = draft.getSceneExt();
+                    const metadata = record(ext.materialsExt ?? {}, "material metadata");
+                    if (metadata[String(request.cloneFrom)] !== undefined) {
+                        if (ext.materialsExt === undefined)
+                            draft.patchSceneExt([
+                                { op: "add", path: "/materialsExt", value: {} },
+                            ]);
+                        draft.patchSceneExt([
+                            {
+                                op: "add",
+                                path: `/materialsExt/${resultId}`,
+                                value: metadata[String(request.cloneFrom)],
+                            },
+                        ]);
+                    }
+                }
+                for (const id of request.objectIds ?? [])
+                    draft.setNodeMaterial(id, resultId);
+                return {
+                    materialId: resultId,
+                    objectIds: directUsers(draft, resultId),
+                    referenceIdChanges,
+                    parameters: 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,
+                            exposed: node.in3?.x !== undefined && node.in3.x > 0,
+                            value: override?.value ?? node.in1 ?? value3(0),
+                            color: override?.color ?? node.in2 ?? value3(0),
+                        };
+                    }) ?? []),
+                };
+            }, context);
+            return {
+                ...edited.value,
+                status: "applied",
+                rendering: "unverified",
+            };
+        },
+    };
+}

package/dist/sdk-openscad-host.js

@@ -1,3 +1,4 @@
+import { SceneOperationError } from "./sdk-scene-host.js";
 import { z } from "zod";
 import { getOpenScadGroundedPosition, MAX_PRINTABILITY_REPAIR_ATTEMPTS, requestTurnOpenScadPrintability, toOpenScadCompileResponse, } from "./openscad.js";
 import { createGeometryRepairTracker, createRepairTracker, } from "./repair-state.js";
@@ -237,7 +238,8 @@ export function createSdkOpenScadHost(options) {
         }
         catch (error) {
             if (creating === false && operationId !== "") {
-                const operation = await editor.getOperation(operationId);
+                const operation = error instanceof SceneOperationError
+                    ? error.operation : await editor.getOperation(operationId);
                 if (operation?.status === "rolled_back") {
                     await geometryRepairs.refund(resolved.repairKey, operationId);
                     await printabilityRepairs.refund(resolved.repairKey, operationId);

package/dist/sdk-scene-host.d.ts

@@ -18,7 +18,7 @@ export type SdkSceneServices = {
 export type SdkSceneEditorOptions = {
     targetKey: string;
     projectId?: number;
-    operations: SceneOperationStore;
+    operations?: SceneOperationStore;
     saveToRenderer?: boolean;
     withConnection<T>(context: SparkInvocationContext, action: (api: KakapoAPI, beginSettlement: () => void, 
     /** Supply this when the host adds a stricter connection lifetime. */
@@ -34,6 +34,11 @@ export type SdkSceneEditIdentity = {
     operation: string;
     target?: Record<string, unknown> | (() => Record<string, unknown>);
 };
+/** Carries this invocation's outcome without requiring a persistent journal. */
+export declare class SceneOperationError extends Error {
+    readonly operation: SceneOperation;
+    constructor(operation: SceneOperation, cause: unknown);
+}
 export type SdkSceneEditor = {
     getOperation(operationId: string): Promise<SceneOperation | undefined>;
     withConnection<T>(context: SparkInvocationContext, action: (api: KakapoAPI, beginSettlement: () => void) => T | Promise<T>): Promise<T>;

package/dist/sdk-scene-host.js

@@ -10,6 +10,15 @@ function assertSceneSaved(operation) {
     if (operation.save?.status === "unknown" || operation.save?.status === "requested")
         throw new Error("The scene edit was applied, but its save outcome is unknown. Inspect persistence before continuing; do not repeat the edit.");
 }
+/** Carries this invocation's outcome without requiring a persistent journal. */
+export class SceneOperationError extends Error {
+    operation;
+    constructor(operation, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.operation = operation;
+        this.name = "SceneOperationError";
+    }
+}
 export function createSdkSceneDraft(api, scene, services) {
     let defaultMaterialId = scene
         .listMaterials()
@@ -65,7 +74,7 @@ export function createSdkSceneDraft(api, scene, services) {
 export function createSdkSceneEditor(options) {
     const ordinals = new WeakMap();
     return {
-        getOperation: (operationId) => options.operations.getSceneOperation(options.targetKey, operationId),
+        getOperation: (operationId) => options.operations?.getSceneOperation(options.targetKey, operationId) ?? Promise.resolve(undefined),
         withConnection: (context, action) => options.withConnection(context, async (api, settle, active = context) => {
             active.signal.throwIfAborted();
             return action(api, settle);
@@ -102,6 +111,7 @@ export function createSdkSceneEditor(options) {
                 let synchronized = false;
                 let saveSettled = true;
                 let committedScene;
+                let outcome;
                 let hostDetails = {};
                 const record = async (operation, details) => {
                     hostDetails = { ...hostDetails, ...details };
@@ -121,7 +131,7 @@ export function createSdkSceneEditor(options) {
                             result: operation.result,
                             save: operation.save,
                             error: operation.error,
-                            synchronized,
+                            ...(options.operations ? { synchronized } : {}),
                         }),
                     });
                 };
@@ -133,6 +143,7 @@ export function createSdkSceneEditor(options) {
                         result = await executeSceneOperation({
                             api,
                             store: options.operations,
+                            onOutcome: operation => { outcome = operation; },
                             saveToRenderer: options.saveToRenderer,
                             operation: {
                                 id,
@@ -157,7 +168,7 @@ export function createSdkSceneEditor(options) {
                     catch (error) {
                         // Receipt persistence must not replace the original SDK/tool error.
                         try {
-                            const operation = await options.operations.getSceneOperation(options.targetKey, id);
+                            const operation = outcome ?? await options.operations?.getSceneOperation(options.targetKey, id);
                             if (operation) {
                                 synchronized = operation.status === "rolled_back";
                                 await record(operation);
@@ -204,6 +215,11 @@ export function createSdkSceneEditor(options) {
                     }
                     return result;
                 }
+                catch (error) {
+                    if (!options.operations && outcome)
+                        throw new SceneOperationError(outcome, error);
+                    throw error;
+                }
                 finally {
                     await releaseCommit?.(synchronized && saveSettled);
                 }

package/dist/server/fixtures/materials/matte-blue.json

@@ -1,14 +1,14 @@
-{
-  "name": "Development: Matte Blue",
-  "resource": {
-    "data": {
-      "color.x": 0.08,
-      "color.y": 0.3,
-      "color.z": 0.8,
-      "roughness": 0.85,
-      "metalness": 0,
-      "index_of_refraction": 1.5
-    },
-    "shaders": []
-  }
-}
+{
+  "name": "Development: Matte Blue",
+  "resource": {
+    "data": {
+      "color.x": 0.08,
+      "color.y": 0.3,
+      "color.z": 0.8,
+      "roughness": 0.85,
+      "metalness": 0,
+      "index_of_refraction": 1.5
+    },
+    "shaders": []
+  }
+}

package/dist/server/fixtures/materials/polished-copper.json

@@ -1,14 +1,14 @@
-{
-  "name": "Development: Polished Copper",
-  "resource": {
-    "data": {
-      "color.x": 0.955,
-      "color.y": 0.638,
-      "color.z": 0.538,
-      "roughness": 0.18,
-      "metalness": 1,
-      "index_of_refraction": 1.5
-    },
-    "shaders": []
-  }
-}
+{
+  "name": "Development: Polished Copper",
+  "resource": {
+    "data": {
+      "color.x": 0.955,
+      "color.y": 0.638,
+      "color.z": 0.538,
+      "roughness": 0.18,
+      "metalness": 1,
+      "index_of_refraction": 1.5
+    },
+    "shaders": []
+  }
+}