@womp/spark-agent 5.2.3 → 5.4.0

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/server/standalone.js

@@ -5,10 +5,11 @@ import express from "express";
 import { getSparkModel, SPARK_MODELS } from "../models.js";
 import { KakapoAPI, KakapoRpcError, KakapoSceneCommitError } from "@womp/kakapo-sdk";
 import { captureSdkSceneScreenshot } from "../sdk-scene-screenshot.js";
-import { composeCapabilities, createAccountCapability, createGeometryCapability, createOpenScadCapability, createSceneCapability, } from "../capabilities.js";
+import { composeCapabilities, createAccountCapability, createGeometryCapability, createMaterialsCapability, createOpenScadCapability, createSceneCapability, } from "../capabilities.js";
 import { loadDemoSceneMaterials } from "./demo-scene-materials.js";
 import { createDemoAccountHost } from "./demo-account.js";
 import { createSdkSceneEditor, createSdkSceneHost, } from "../sdk-scene-host.js";
+import { createSdkMaterialsHost } from "../sdk-materials-host.js";
 import { createSdkGeometryHost } from "../sdk-geometry-host.js";
 import { createSdkOpenScadHost } from "../sdk-openscad-host.js";
 import { createSdkSceneHealthHost } from "../sdk-scene-health-host.js";
@@ -114,6 +115,10 @@ export async function createStandaloneSparkAgentApp(options) {
                 });
                 const capabilityBindings = {
                     scene: createSceneCapability(sceneHost),
+                    materials: createMaterialsCapability(createSdkMaterialsHost({
+                        editor,
+                        assertAvailable: editorOptions.assertEditable,
+                    }), sceneHost),
                     geometry: createGeometryCapability(createSdkGeometryHost({
                         editor,
                         repairs,

package/dist/ui.d.ts

@@ -116,16 +116,24 @@ export type SparkUITools = {
     read_skill: {
         input: {
             name: string;
+            names?: never;
+        } | {
+            names: string[];
+            name?: never;
         };
-        output: ({
-            ok: true;
-        } & SparkSkill) | {
-            ok: false;
-            error: string;
-            available: string[];
+        output: SkillReadResult | {
+            ok: boolean;
+            skills: SkillReadResult[];
         };
     };
 };
+export type SkillReadResult = ({
+    ok: true;
+} & SparkSkill) | {
+    ok: false;
+    error: string;
+    available: string[];
+};
 export type SparkUIMessage = UIMessage<SparkMessageMetadata, SparkDataParts, SparkUITools>;
 export type SparkUIMessageChunk = InferUIMessageChunk<SparkUIMessage>;
 export type StoredSparkChunk = {
@@ -168,12 +176,24 @@ export declare const sparkMessageMetadataSchema: z.ZodObject<{
             code: z.ZodOptional<z.ZodString>;
             status: z.ZodOptional<z.ZodNumber>;
             requestId: z.ZodOptional<z.ZodString>;
+            eventType: z.ZodOptional<z.ZodString>;
+            issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                code: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                expected: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
             cause: z.ZodOptional<z.ZodObject<{
                 message: z.ZodString;
                 name: z.ZodOptional<z.ZodString>;
                 code: z.ZodOptional<z.ZodString>;
                 status: z.ZodOptional<z.ZodNumber>;
                 requestId: z.ZodOptional<z.ZodString>;
+                eventType: z.ZodOptional<z.ZodString>;
+                issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    code: z.ZodString;
+                    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                    expected: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         message: z.ZodString;
@@ -181,6 +201,12 @@ export declare const sparkMessageMetadataSchema: z.ZodObject<{
         code: z.ZodOptional<z.ZodString>;
         status: z.ZodOptional<z.ZodNumber>;
         requestId: z.ZodOptional<z.ZodString>;
+        eventType: z.ZodOptional<z.ZodString>;
+        issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            expected: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const sparkDataPartSchemas: {
@@ -243,12 +269,24 @@ export declare const sparkDataPartSchemas: {
                 code: z.ZodOptional<z.ZodString>;
                 status: z.ZodOptional<z.ZodNumber>;
                 requestId: z.ZodOptional<z.ZodString>;
+                eventType: z.ZodOptional<z.ZodString>;
+                issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    code: z.ZodString;
+                    path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                    expected: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
                 cause: z.ZodOptional<z.ZodObject<{
                     message: z.ZodString;
                     name: z.ZodOptional<z.ZodString>;
                     code: z.ZodOptional<z.ZodString>;
                     status: z.ZodOptional<z.ZodNumber>;
                     requestId: z.ZodOptional<z.ZodString>;
+                    eventType: z.ZodOptional<z.ZodString>;
+                    issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        code: z.ZodString;
+                        path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                        expected: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>>>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>;
             message: z.ZodString;
@@ -256,6 +294,12 @@ export declare const sparkDataPartSchemas: {
             code: z.ZodOptional<z.ZodString>;
             status: z.ZodOptional<z.ZodNumber>;
             requestId: z.ZodOptional<z.ZodString>;
+            eventType: z.ZodOptional<z.ZodString>;
+            issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                code: z.ZodString;
+                path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                expected: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
         label: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "5.2.3",
+  "version": "5.4.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",
@@ -110,7 +110,7 @@
     "@ai-sdk/openai": "4.0.63",
     "@jitl/quickjs-wasmfile-release-sync": "0.32.0",
     "@womp/flowir": "0.3.0",
-    "@womp/kakapo-sdk": "0.7.2",
+    "@womp/kakapo-sdk": "0.7.3",
     "ai": "7.0.95",
     "eventsource-parser": "^3.0.6",
     "express": "^5.2.1",