@womp/spark-agent 5.2.3 → 5.4.0

package/dist/agent-run.d.ts

@@ -8,7 +8,7 @@ export declare function parseAgentRunArgs(args: string[]): {
     output: string | undefined;
     images: string[];
     settings: {
-        modelId: "gpt-6-astra" | "gpt-6-sol" | "gpt-6-luna" | "gemini-3.8-flash" | "claude-opus-5-5" | "claude-fable-5";
+        modelId: "gpt-6-astra" | "gpt-6.1-sol" | "gpt-6-sol" | "gpt-6-luna" | "gemini-3.8-flash" | "claude-opus-5-5" | "claude-fable-5";
         reasoningEffort: ReasoningEffort;
     };
 } | null;

package/dist/agent-tools.js

@@ -54,7 +54,16 @@ export function createSparkTools(options) {
                 if (previous === undefined)
                     return;
                 const text = previous + inputTextDelta;
-                const value = completedInputString(text, field);
+                let value = completedInputString(text, field);
+                if (value === undefined && field === "name") {
+                    try {
+                        const input = JSON.parse(text);
+                        const names = input?.names;
+                        if (Array.isArray(names) && names.every(name => typeof name === "string" && name.length > 0))
+                            value = names.join(", ").slice(0, 160);
+                    }
+                    catch { /* The streamed input is not complete yet. */ }
+                }
                 if (value === undefined) {
                     inputs.set(toolCallId, text);
                     return;
@@ -70,18 +79,27 @@ export function createSparkTools(options) {
     return {
         read_skill: tool({
             ...inputLabels("name"),
-            description: "Read a skill from the available directory, including instructions, TypeScript API declarations, and JavaScript examples.",
-            inputSchema: z.object({ name: z.string().min(1).max(160) }),
+            description: "Read required skills together with names, or one skill with name. Returns instructions, TypeScript API declarations, and JavaScript examples from the available directory.",
+            inputSchema: z.union([
+                z.object({ names: z.array(z.string().min(1).max(160)).min(1) }).strict(),
+                z.object({ name: z.string().min(1).max(160) }).strict(),
+            ]),
             execute: (input, { toolCallId }) => execute({ id: toolCallId, name: "read_skill", input }, async () => {
-                const skill = options.capabilities.skills.find(({ name }) => name === input.name);
-                if (skill === undefined) {
-                    return {
-                        ok: false,
-                        error: `Skill unavailable: ${input.name}`,
-                        available: options.capabilities.skills.map(({ name }) => name),
-                    };
-                }
-                return { ok: true, ...skill };
+                const read = (requested) => {
+                    const skill = options.capabilities.skills.find(({ name }) => name === requested);
+                    if (skill === undefined) {
+                        return {
+                            ok: false,
+                            error: `Skill unavailable: ${requested}`,
+                            available: options.capabilities.skills.map(({ name }) => name),
+                        };
+                    }
+                    return { ok: true, ...skill };
+                };
+                if ("name" in input)
+                    return read(input.name);
+                const skills = [...new Set(input.names)].map(read);
+                return { ok: skills.every(skill => skill.ok), skills };
             }),
         }),
         execute_javascript: tool({

package/dist/capabilities/materials.d.ts

@@ -0,0 +1,45 @@
+import type { SparkCapability, SparkInvocationContext } from "../capabilities.js";
+import { type MaterialInspectionOptions, type MaterialInspectionResult, type MaterialInspectionHost } from "../materials/inspection.js";
+import type { MaterialCatalog, MaterialCatalogOptions, MaterialNode, MaterialNodeOptions, MaterialRecipeOptions, MaterialGraph, MaterialField, MaterialFieldOptions, MaterialCompositionOptions, MaterialShapeOptions, MaterialSnapshot, MaterialWrite, MaterialWriteResult } from "../materials/types.js";
+export type * from "../materials/types.js";
+export type { MaterialInspectionOptions, MaterialInspectionResult, MaterialInspectionHost } from "../materials/inspection.js";
+export type MaterialStatus = {
+    /** null means this observation failed, not that the queue is empty. */
+    remaining: number | null;
+    /** null means this observation failed, not that all resources loaded. */
+    pendingResources: Record<string, string[]> | null;
+    errors?: {
+        source: "compiler-progress" | "pending-resources";
+        message: string;
+    }[];
+    shaderDiagnostics?: {
+        status: "unavailable";
+        reason: string;
+    };
+    rendering: "unverified";
+    explanation: string;
+};
+export type WompMaterialsApi = {
+    catalog(options?: MaterialCatalogOptions): Promise<MaterialCatalog>;
+    read(materialId?: number): Promise<MaterialSnapshot>;
+    node(options: MaterialNodeOptions): MaterialNode;
+    /** Build an editable starting graph; reads live descriptors internally and does not commit. */
+    recipe(options: MaterialRecipeOptions): Promise<MaterialGraph>;
+    /** Terminal-free scalar structure, editable before composition. */
+    field(options: MaterialFieldOptions): Promise<MaterialField>;
+    /** Merge arbitrary scalar fields and independently wire color, finish and relief. No commit. */
+    compose(options: MaterialCompositionOptions): Promise<MaterialGraph>;
+    /** Shape a field analytically with editable controls; no commit or descriptor inspection needed. */
+    shape(field: MaterialField, options: MaterialShapeOptions): Promise<MaterialField>;
+    /** Available when the host supplies scene captures. Primes, waits and returns joint inspection views. */
+    inspect?: (options: MaterialInspectionOptions) => Promise<MaterialInspectionResult>;
+    write(options: MaterialWrite): Promise<MaterialWriteResult>;
+    status(): Promise<MaterialStatus>;
+};
+export interface MaterialsHost {
+    catalog(options: MaterialCatalogOptions, context: SparkInvocationContext): Promise<MaterialCatalog>;
+    read(materialId: number | undefined, context: SparkInvocationContext): Promise<MaterialSnapshot>;
+    write(options: MaterialWrite, context: SparkInvocationContext): Promise<MaterialWriteResult>;
+    status(context: SparkInvocationContext): Promise<MaterialStatus>;
+}
+export declare function createMaterialsCapability(host: MaterialsHost, captures?: MaterialInspectionHost): SparkCapability<WompMaterialsApi>;

package/dist/capabilities/materials.js

@@ -0,0 +1,89 @@
+import { WOMP_MATERIALS_DECLARATIONS } from "../generated/materials-declarations.js";
+import { catalogOptionsSchema, makeMaterialNode, materialId, writeSchema, } from "../materials/graph.js";
+import { MATERIALS_REFERENCE } from "../materials/reference.js";
+import { MATERIALS_RECIPES } from "../materials/recipes.js";
+import { MATERIALS_STRUCTURE_GUIDANCE, MATERIALS_QUALITY_GUIDANCE } from "../materials/structure.js";
+import { makeMaterialShape, materialShapeOperations, materialShapeSchema } from "../materials/shaping.js";
+import { inspectMaterial, materialInspectionSchema } from "../materials/inspection.js";
+import { makeMaterialField, materialFieldOperations, materialFieldSchema, makeMaterialRecipe, materialRecipeOperations, materialRecipeSchema, MATERIAL_RECIPE_RELIEF_GUIDANCE } from "../materials/surface-recipes.js";
+import { makeMaterialComposition, materialCompositionOperations, materialCompositionSchema } from "../materials/composition.js";
+export function createMaterialsCapability(host, captures) {
+    return {
+        skills: [
+            {
+                name: "procedural-materials",
+                version: "15",
+                description: "Discover live texture resources, build procedural shader layers, edit material constants, clone and assign materials.",
+                instructions: `Use womp.materials for procedural surface appearance.
+recipe() builds editable grid, noise, grain and woven starting graphs and resolves live operation selectors internally. Use it directly for these patterns; no preliminary descriptor dump is needed. It does not write or assign a material. featureSize is in object-coordinate units for coordinateSpace:'object', or physical millimeters for 'world'; vector components use graph axes. Object mapping follows the owning carrier and its transforms; world mapping stays fixed in the scene. Grid includes major cells at featureSize and minor cells at one tenth of it, with lower minor contrast. colorA is the base and colorB the grid-line color. Use shallow relief for probes.
+field() builds terminal-free noise, grain, woven, grid or cellular structures. It shares the recipe coordinate/feature-size convention; rotation is in degrees. cellMode selects a cellular pattern or boundary mask; remap controls contrast and can invert a mask. compose() merges these fields or arbitrary custom {graph,source:{node,slot}} fields, wiring independent color, roughness and combined height/bump weights. Color/roughness weights are nonnegative and sum to at most 1; fields must be normalized to 0..1. Relief weights may be signed. This is generic construction, not a finished material preset. Keep broad variation, defining shapes and fine roughness/relief separate. Independent feature colors use shape palette and blend; compose preserves their RGB with color low zero, high one, and weight one. Scalar channels consume X.
+Coordinate axes are known: scene.access public X corresponds to negative renderer Z, public Y to renderer Y, public Z to negative renderer X. World-space featureSize uses renderer axes in physical mm: for grain running along public X, make Z the largest feature-size component, such as {x:1,y:1,z:40}; public Z uses the largest X component. These are orientation examples; choose sizes from the target. Object-space coordinates additionally follow carrier transforms and primitive/mesh mapping. A symmetric grid measures spacing/stretch but cannot establish axis identity. Use the known basis plus carrier transforms, or physical world mapping when local axis identity is uncertain; world mapping remains scene anchored.
+${MATERIALS_STRUCTURE_GUIDANCE}
+Composed controls are named Constants. Palette colors, roughness endpoints, metalness and overall relief are exposed for editing; structural weights and centering stay internal. SDK write results include parameters with current referenceId, value and color; print only the controls relevant to refinement. Change those through constants without rebuilding the graph, preserving the counterpart value/color. Use the new handles after resets/replacements; when a host omits parameters, recover them from read().
+${MATERIAL_RECIPE_RELIEF_GUIDANCE}
+${MATERIALS_QUALITY_GUIDANCE}
+For custom operations, use exact names from catalog().operations; request catalog({operations:[...]}) only for descriptors not already known in this conversation. Request includeTextures:true when you need texture resource names. Request refreshTextures:true after adding/replacing texture resources or switching resource context. Never infer availability from files on the agent's machine or persist catalogue indices as texture identity.
+read() lists materials and direct users; read(id) returns native base data and graph layers. Existing material edits affect every reference, including Geometry Nodes/OpenSCAD references not listed as direct users. To isolate an edit, use cloneFrom with objectIds. Shader storage shared with another material is copied automatically.
+Use node() to construct literals and encode ramps, texture names and option payloads. For custom nodes, discover unfamiliar descriptors before connecting output slots to input slots. OutputMaterial needs connections; its unconnected ports inherit the incoming material.
+write replaces the full layers array when supplied. Preserve unrelated layers, nodes and references from read. Omit layers for assignment/constant-only edits. When rebuilding an existing graph, carry forward intended Constant overrides; omitted overrides reset with replacement nodes, including finish controls. constants entries require both value and color; preserve the counterpart when editing one. A null entry resets a Constant and returns its new reference ID: read again before further edits.
+Base properties and names remain available through scene.access; material names have a 63-character limit. Procedural colors, including recipe palettes, Constant colors and ramp stops, are linear RGB in 0..1. Decode display RGB before supplying it; for this renderer's gamma-2.2 base colors use (channel/255)**2.2. Do not apply this conversion to roughness, metalness, height or normals, or to colors already linear. Graph coordinates use native conventions, not scene.access's mm convenience API.
+Writes use the host's protected scene access, persistence, permissions and receipts. Read current layers before replacing them. After an uncertain commit/save, inspect receipts and scene state; do not replay blindly.
+status() reports independent global compiler-queue and pending-resource observations. A null field means its query failed; errors identifies the source. Per-shader diagnostics are unavailable. Catalogue names do not establish texture channels, color space or normal convention; choose decoding only when the resource encoding is known. Applied means committed. When inspect is available, use inspect({views:[...]}) after writes; it primes registration once, polls status without screenshot loops and captures the angles sequentially. Emit every returned frame within the same execution for joint comparison. queueSettled describes observations, not visual correctness; Report pending/unavailable observations honestly; fewer frames than requested means inspection is incomplete. When inspect is unavailable, prime with a screenshot, then observe status and capture the needed angles.`,
+                declarations: WOMP_MATERIALS_DECLARATIONS,
+                examples: [
+                    "const fields = await Promise.all([womp.materials.field({pattern:'noise',coordinateSpace:'world',featureSize:8}),womp.materials.field({pattern:'noise',coordinateSpace:'world',featureSize:0.2})]); const graph = await womp.materials.compose({fields,color:{low:{x:0.2,y:0.15,z:0.1},high:{x:0.4,y:0.3,z:0.2},weights:[0.7,0.1]},roughness:{low:0.6,high:0.9,weights:[0.1,0.8]},relief:{mode:'height',scale:0.003,weights:[0.3,0.05]}}); const result = await womp.materials.write({materialId,layers:[graph]}); print({materialId:result.materialId,parameters:result.parameters?.filter(p=>['relief.scale','color.low','color.high','roughness.low','roughness.high'].includes(p.name))});",
+                    "const graph = await womp.materials.recipe({pattern:'grid',coordinateSpace:'object',featureSize:1,colorA:{x:0.45,y:0.35,z:0.2},colorB:{x:0.02,y:0.02,z:0.02},roughnessA:0.45,roughnessB:0.45,relief:'height',reliefScale:0.0003}); print(await womp.materials.write({cloneFrom:materialId,layers:[graph],objectIds:[objectId]}));",
+                    "const graph = await womp.materials.recipe({pattern:'noise',coordinateSpace:'world',featureSize:2,colorA:{x:0.6,y:0.55,z:0.45},colorB:{x:0.65,y:0.6,z:0.5},roughnessA:0.8,roughnessB:0.85,relief:'height',reliefScale:0.003}); print(await womp.materials.write({materialId,layers:[graph],objectIds:[objectId]}));",
+                    "print(await womp.materials.write({cloneFrom: materialId, objectIds: [objectId]}));",
+                ],
+            },
+            {
+                name: "procedural-materials-reference",
+                version: "8",
+                description: "Native material graph contracts, units, layer semantics and binary payload helpers.",
+                instructions: MATERIALS_REFERENCE,
+                declarations: "",
+                examples: [],
+            },
+            {
+                name: "procedural-materials-recipes",
+                version: "9",
+                description: "Generic mapping, scalar-field composition, generator, color and normal/bump snippets, plus isolated cloning and Constant reset workflows.",
+                instructions: MATERIALS_RECIPES,
+                declarations: "",
+                examples: [],
+            },
+        ],
+        createApi: (context) => ({
+            catalog: (options) => host.catalog(catalogOptionsSchema.parse(options ?? {}), context),
+            read: (id) => host.read(id === undefined ? undefined : materialId.parse(id), context),
+            node: (options) => {
+                context.signal.throwIfAborted();
+                return makeMaterialNode(options);
+            },
+            recipe: async (options) => {
+                const parsed = materialRecipeSchema.parse(options);
+                const catalogue = await host.catalog({ operations: materialRecipeOperations(parsed) }, context);
+                return makeMaterialRecipe(parsed, catalogue);
+            },
+            field: async (options) => {
+                const parsed = materialFieldSchema.parse(options);
+                const catalogue = await host.catalog({ operations: materialFieldOperations(parsed) }, context);
+                return makeMaterialField(parsed, catalogue);
+            },
+            compose: async (options) => {
+                const parsed = materialCompositionSchema.parse(options);
+                const catalogue = await host.catalog({ operations: materialCompositionOperations(parsed) }, context);
+                return makeMaterialComposition(parsed, catalogue);
+            },
+            shape: async (field, options) => {
+                const parsed = materialShapeSchema.parse({ ...options, field });
+                const catalogue = await host.catalog({ operations: materialShapeOperations(parsed) }, context);
+                return makeMaterialShape(parsed, catalogue);
+            },
+            ...(captures ? { inspect: (options) => inspectMaterial(host, captures, materialInspectionSchema.parse(options), context) } : {}),
+            write: (options) => host.write(writeSchema.parse(options), context),
+            status: () => host.status(context),
+        }),
+    };
+}

package/dist/capabilities/scene.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import type { CameraConfiguration } from "@womp/kakapo-sdk";
 import type { ArtifactRef, SparkCapability, SparkInvocationContext } from "../capabilities.js";
 import type { WompSceneDraft } from "./scene-draft.js";
@@ -29,4 +30,24 @@ export interface SceneHost {
     access<T>(callback: (draft: WompSceneDraft) => T | Promise<T>, context: SparkInvocationContext): Promise<T>;
     screenshot(options: SceneScreenshotOptions, context: SparkInvocationContext): Promise<ArtifactRef>;
 }
+export declare const screenshotOptions: z.ZodObject<{
+    camera: z.ZodOptional<z.ZodObject<{
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>;
+        target: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>;
+        projection: z.ZodOptional<z.ZodEnum<{
+            perspective: "perspective";
+            orthographic: "orthographic";
+        }>>;
+        horizontalFovDegrees: z.ZodOptional<z.ZodNumber>;
+        orthographicWidth: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare function createSceneCapability(host: SceneHost): SparkCapability<WompSceneApi>;

package/dist/capabilities/scene.js

@@ -24,7 +24,7 @@ function readHealthObjectIds(objectIds) {
     throw new Error(`scene.health takes object ids from scene.access(): whole numbers from 0 up, in an array. ${named} ${invalid.length === 1 ? "is not one" : "are not ids"}.`);
 }
 const cameraVector = z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).strict();
-const screenshotOptions = z.object({
+export const screenshotOptions = z.object({
     camera: z.object({
         position: cameraVector,
         target: cameraVector,
@@ -40,7 +40,7 @@ export function createSceneCapability(host) {
                 name: "scene-editing",
                 version: "45",
                 description: "Inspect the open scene and edit its objects, materials, curves, and environment.",
-                instructions: `Use womp.scene.access(callback) for both inspection and edits. Inspect targets inside each callback using scene.nodes({ name, type, parentId, ids, offset, limit }) and detailed getters; filters are optional, name is a case-insensitive substring, and results default to 100 (maximum 1000). Page with offset as needed. Inspection reflects changes made in the callback. scene.unitMultiplier gives project units. Do not reuse an earlier inspection as current state.
+                instructions: `Use womp.scene.access(callback) for both inspection and edits. Inspect targets inside each callback using scene.nodes({ name, type, parentId, ids, offset, limit }) and detailed getters; filters are optional, name is a case-insensitive substring, and results default to 100 (maximum 1000). Page with offset as needed. Inspection reflects changes made in the callback. scene.unitMultiplier gives project units. Do not reuse an earlier inspection as current state.
 Use womp.scene.health() to refresh whole-scene health or womp.scene.health(objectIds) to check specific objects (mapped to their owning Areas).
 Health is requested only through scene.health(); access does not request it automatically. It is renderer feedback, not proof that the latest edit finished evaluating. Request it when needed to verify the result.
 Unavailable, stale, or unverified feedback must not trigger blind regeneration or a claim that the model passed. Hosts without health services return unverified health with a reason.
@@ -52,8 +52,8 @@ are properties of that draft. The draft expires when the callback ends. Await as
 Do not start unrelated operations from inside an access. Draft handles expire when its callback returns. An unchanged draft does not submit or save anything.
 Preserve the existing scene unless asked to remove or replace content. Use semantic object names and reuse
 known IDs when editing rather than creating duplicates. Distances follow the current project's units
-(scene.unitMultiplier is 1 for millimetres, 0.1 for centimetres, approximately 0.0393701 for inches).
-Convert a dimension in millimetres to project units by multiplying it by scene.unitMultiplier.
+(scene.unitMultiplier is 1 for millimetres, 0.1 for centimetres, approximately 0.0393701 for inches).
+Convert a dimension in millimetres to project units by multiplying it by scene.unitMultiplier.
 The SDK-backed draft clamps dimension writes to 0.01–1000 mm per component before converting to native units; this is an adapter limit, not a scene-wide size limit. Read back dimensions when physical size matters.
 Area size is a dimensionless scale; Group size stays fixed at one. Lights must be created at root (parentId 0); their size has x/y dimensions.
 Light power is linear emitted intensity before collimation, not a percentage or physical unit: doubling it doubles emission, not tone-mapped pixel brightness. Valid ranges are 0–${maxLightIntensity("rect")} for Rect/Sphere and 0–${maxLightIntensity("distant")} for Distant; these limits are not brightness targets. A light-type change preserves intensity and rejects values outside the new type's range; lower intensity first if needed. Rect size is width/height; Sphere uses x as diameter; Distant uses direction, not position or size.
@@ -108,15 +108,15 @@ Check font, HDR, and material catalogs before selecting names. A host can explic
 unavailable. Selecting an HDR resets its intensity; apply a custom intensity after selecting it.
 For library materials, use listSuperMaterials(), then await materialImport(name) inside scene.access and assign the returned numeric ID the way that object requires: nodeSetMaterialId or curvePointSetMaterialId for scene nodes, the FlowIR SetMaterial node for a Geometry Nodes graph. A failed import rolls back the draft.
 Filter large read results with JavaScript and print only useful details.
-After a major edit, capture a screenshot outside the transaction and emitImage its reference.
-screenshot({ camera: { position: {x,y,z}, target: {x,y,z}, projection: 'perspective', horizontalFovDegrees: 60 } })
-sets a world-space camera in the same Womp coordinates and project units as scene positions (Y-up).
-For orthographic framing use projection: 'orthographic' and orthographicWidth in project units instead of FOV.
-Direction is derived from position/target; do not use coincident points or an exactly vertical viewing direction.
-Omitted projection/lens settings come from the active camera. Pass the camera again for repeatable captures.
-For object-focused screenshots, identify the requested object and frame it using world-space bounds. Convert local bounds using the object’s and applicable ancestor transforms, including translation, rotation, and scale; do not transform world-space bounds again. Reuse established framing when appropriate and avoid clipping the subject.
-Omitting camera captures the active viewport without auto-fit. Use it when the user asks about the current viewport or clearly refers to what is visible on screen, not on the assumption that it shows the requested object.
-Respect the host's camera-lock restrictions. Verify silhouette,
+After a major edit, capture a screenshot outside the transaction and emitImage its reference.
+screenshot({ camera: { position: {x,y,z}, target: {x,y,z}, projection: 'perspective', horizontalFovDegrees: 60 } })
+sets a world-space camera in the same Womp coordinates and project units as scene positions (Y-up).
+For orthographic framing use projection: 'orthographic' and orthographicWidth in project units instead of FOV.
+Direction is derived from position/target; do not use coincident points or an exactly vertical viewing direction.
+Omitted projection/lens settings come from the active camera. Pass the camera again for repeatable captures.
+For object-focused screenshots, identify the requested object and frame it using world-space bounds. Convert local bounds using the object’s and applicable ancestor transforms, including translation, rotation, and scale; do not transform world-space bounds again. Reuse established framing when appropriate and avoid clipping the subject.
+Omitting camera captures the active viewport without auto-fit. Use it when the user asks about the current viewport or clearly refers to what is visible on screen, not on the assumption that it shows the requested object.
+Respect the host's camera-lock restrictions. Verify silhouette,
 connections, openings, proportions, and materials before claiming completion. Use the owning top-level Area for scene-space bounds;
 OpenSCAD part bounds are local to the part; individual primitive and curve bounds are unsupported. Renderer bounds and resize calls
 must finish before subsequent writes. Inside scene.access, complete renderer-backed bounds reads before the first

package/dist/capabilities.d.ts

@@ -68,3 +68,4 @@ export interface SparkArtifactResolver {
         data: Uint8Array;
     }>;
 }
+export * from "./capabilities/materials.js";

package/dist/capabilities.js

@@ -23,3 +23,4 @@ export function composeCapabilities(capabilities) {
         ])),
     };
 }
+export * from "./capabilities/materials.js";

package/dist/error-diagnostics.d.ts

@@ -6,6 +6,12 @@ export type SparkErrorDiagnostics = {
     code?: string;
     status?: number;
     requestId?: string;
+    eventType?: string;
+    issues?: {
+        code: string;
+        path: (string | number)[];
+        expected?: string;
+    }[];
     cause?: SparkErrorDiagnostics;
 };
 export declare const sparkErrorDiagnosticsSchema: z.ZodObject<{
@@ -15,12 +21,24 @@ export declare const sparkErrorDiagnosticsSchema: 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;
@@ -28,5 +46,11 @@ export declare const sparkErrorDiagnosticsSchema: 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>;
 export declare function sparkErrorDiagnostics(error: unknown): SparkErrorDiagnostics;

package/dist/error-diagnostics.js

@@ -5,6 +5,12 @@ const fields = {
     code: z.string().max(128).optional(),
     status: z.number().int().min(100).max(599).optional(),
     requestId: z.string().max(128).optional(),
+    eventType: z.string().max(128).optional(),
+    issues: z.array(z.object({
+        code: z.string().max(64),
+        path: z.array(z.union([z.string().max(128), z.number().int().nonnegative()])).max(16),
+        expected: z.string().max(32).optional(),
+    })).max(32).optional(),
 };
 const causeSchema = z.object(fields);
 export const sparkErrorDiagnosticsSchema = z.object({
@@ -68,6 +74,41 @@ function text(value, limit = 1024) {
         .slice(0, limit);
 }
 const PLACEHOLDER = /\[(?:payload|data|url|credential) omitted\]/gu;
+// Zod union errors nest issues. Keep schema facts, never messages, input,
+// received values or literal/enum alternatives (which can contain user data).
+function validationIssues(value) {
+    const result = [];
+    let remaining = 128;
+    const walk = (items, depth) => {
+        if (!Array.isArray(items) || depth > 8)
+            return;
+        for (const item of items) {
+            if (--remaining < 0 || result.length === 32)
+                return;
+            const issue = record(item);
+            if (issue.code === "invalid_union") {
+                const branches = issue.errors ?? issue.unionErrors;
+                if (Array.isArray(branches) && branches.length) {
+                    for (const branch of branches.slice(0, 32)) {
+                        walk(Array.isArray(branch) ? branch : record(branch).issues, depth + 1);
+                    }
+                    continue;
+                }
+            }
+            if (typeof issue.code === "string" && Array.isArray(issue.path)) {
+                const code = text(issue.code, 64);
+                const path = issue.path.slice(0, 16).map(part => typeof part === "number" && Number.isSafeInteger(part) && part >= 0
+                    ? part : text(part, 128) ?? "[key omitted]");
+                const expected = typeof issue.expected === "string" &&
+                    /^(string|number|boolean|object|array|null|undefined|bigint|symbol|function|date|integer|int|float|never|unknown|any|void|map|set|promise|nan)$/.test(issue.expected)
+                    ? issue.expected : undefined;
+                result.push({ code, path, ...(expected === undefined ? {} : { expected }) });
+            }
+        }
+    };
+    walk(value, 0);
+    return result;
+}
 /** Whether redacted text still says anything once its placeholders are removed. */
 function informative(value) {
     return value !== undefined && /[\p{L}\p{N}]/u.test(value.replace(PLACEHOLDER, ""));
@@ -113,9 +154,21 @@ export function sparkErrorDiagnostics(error) {
             result.status = status;
         if (requestId)
             result.requestId = requestId;
+        const eventType = source.eventType ?? (source.name === "AI_TypeValidationError" ? record(source.value).type : undefined);
+        if (typeof eventType === "string" && /^(response\.[a-z_.]+|error)$/.test(eventType) && eventType.length <= 128)
+            result.eventType = eventType;
+        const issues = validationIssues(source.issues);
+        if (issues.length)
+            result.issues = issues;
         const cause = source.cause ?? source.lastError;
         if (depth < 2 && cause !== undefined && !seen.has(cause))
             result.cause = visit(cause, depth + 1);
+        const details = issues.length ? issues : result.cause?.issues;
+        if ((name === "AI_TypeValidationError" || name === "ZodError") && details?.length) {
+            result.message = text(`Validation failed${result.eventType ? ` (${result.eventType})` : ""}: ${details.slice(0, 3)
+                .map(issue => `${issue.path.join(".") || "<root>"}: ${issue.code}${issue.expected ? ` (expected ${issue.expected})` : ""}`)
+                .join("; ")}`);
+        }
         return result;
     };
     return visit(error, 0);

package/dist/generated/materials-declarations.d.ts

@@ -0,0 +1 @@
+export declare const WOMP_MATERIALS_DECLARATIONS = "declare const womp: { materials: {\n\"catalog\": ((options?: undefined | {\n\"refreshTextures\"?: undefined | false | true;\n\"includeTextures\"?: undefined | false | true;\n\"operations\"?: undefined | Array<string>;\n}) => Promise<{\n\"operations\": Array<{\n\"op\": string;\n\"category\": string;\n\"title\": string;\n}>;\n\"nodes\": {\n[key: string]: {\n\"type\": string;\n\"title\": string;\n\"description\": string;\n\"inputs\": Array<{\n\"title\": string;\n\"type\": string;\n\"values\"?: undefined | Array<string>;\n}>;\n\"outputs\": Array<{\n\"title\": string;\n\"type\": string;\n\"values\"?: undefined | Array<string>;\n}>;\n};\n};\n\"textureCount\": number;\n\"textures\"?: undefined | Array<string>;\n\"textureMetadata\"?: undefined | {\n\"channels\": \"unknown\";\n\"colorSpace\": \"unknown\";\n\"normalConvention\": \"unknown\";\n\"reason\": string;\n};\n}>);\n\"read\": ((materialId?: undefined | number) => Promise<{\n\"materials\": Array<{\n\"id\": number;\n\"shaderIds\": Array<number>;\n\"objectIds\": Array<number>;\n}>;\n\"material\"?: undefined | {\n\"id\": number;\n\"data\": {\n[key: string]: unknown;\n};\n\"layers\": Array<null | {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>;\n};\n\"diagnostics\": Array<string>;\n}>);\n\"node\": ((options: {\n\"op\": string;\n\"name\"?: undefined | string;\n\"reference_id\"?: undefined | number;\n\"inputs\"?: undefined | {\n[key: string]: number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"texture\"?: undefined | string;\n\"ramp\"?: undefined | Array<{\n\"position\": number;\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n}>;\n\"options\"?: undefined | Array<{\n\"name\": string;\n\"value\": number;\n}>;\n}) => {\n\"op\": string;\n[key: string]: unknown;\n});\n\"recipe\": ((options: {\n\"pattern\": \"noise\" | \"grain\" | \"woven\" | \"grid\";\n\"coordinateSpace\": \"object\" | \"world\";\n\"featureSize\": number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"colorA\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"colorB\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"roughnessA\": number;\n\"roughnessB\": number;\n\"metalness\"?: undefined | number;\n\"detail\"?: undefined | number;\n\"relief\": \"height\" | \"bump\";\n\"reliefScale\": number;\n}) => Promise<{\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>);\n\"field\": ((options: {\n\"pattern\": \"noise\" | \"grain\" | \"woven\" | \"grid\" | \"cells\";\n\"coordinateSpace\": \"object\" | \"world\";\n\"featureSize\": number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"detail\"?: undefined | number;\n\"rotation\"?: undefined | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"cellMode\"?: undefined | \"Distance\" | \"Edge distance\" | \"Color\" | \"Smooth Distance\" | \"Smooth Color\";\n\"remap\"?: undefined | {\n\"low\": number;\n\"high\": number;\n};\n}) => Promise<{\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}>);\n\"compose\": ((options: {\n\"fields\": Array<{\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}>;\n\"color\"?: undefined | {\n\"low\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"high\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"weights\": Array<number>;\n};\n\"roughness\"?: undefined | {\n\"low\": number;\n\"high\": number;\n\"weights\": Array<number>;\n};\n\"metalness\"?: undefined | number;\n\"relief\"?: undefined | {\n\"mode\": \"height\" | \"bump\";\n\"scale\": number;\n\"weights\": Array<number>;\n\"center\"?: undefined | number;\n};\n}) => Promise<{\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>);\n\"shape\": ((field: {\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}, options: {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"remap\";\n\"low\": number;\n\"high\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"ridge\";\n\"center\": number;\n\"width\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"periodic\";\n\"coordinates\"?: undefined | number;\n\"axis\": 0 | 1 | 2;\n\"sharpness\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"warp\";\n\"coordinates\"?: undefined | number;\n\"frequency\": number;\n\"amplitude\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"palette\";\n\"mode\": \"Constant\" | \"Linear\" | \"Smooth\";\n\"stops\": Array<{\n\"position\": number;\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n}>;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"blend\";\n\"overlay\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n} | {\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n};\n\"mask\": number | {\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n};\n}) => Promise<{\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}>);\n\"inspect\"?: undefined | ((options: {\n\"views\": Array<{\n\"camera\"?: undefined | {\n\"position\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"target\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"projection\"?: undefined | \"perspective\" | \"orthographic\";\n\"horizontalFovDegrees\"?: undefined | number;\n\"orthographicWidth\"?: undefined | number;\n};\n}>;\n\"timeoutMs\"?: undefined | number;\n}) => Promise<{\n\"frames\": Array<{\n\"id\": string;\n\"mediaType\": string;\n\"name\"?: undefined | string;\n}>;\n\"queueSettled\": false | true;\n\"timedOut\": false | true;\n\"status\": {\n\"remaining\": null | number;\n\"pendingResources\": null | {\n[key: string]: Array<string>;\n};\n\"errors\"?: undefined | Array<{\n\"source\": \"compiler-progress\" | \"pending-resources\";\n\"message\": string;\n}>;\n\"shaderDiagnostics\"?: undefined | {\n\"status\": \"unavailable\";\n\"reason\": string;\n};\n\"rendering\": \"unverified\";\n\"explanation\": string;\n};\n}>);\n\"write\": ((options: {\n\"materialId\"?: undefined | number;\n\"cloneFrom\"?: undefined | number;\n\"layers\"?: undefined | Array<null | {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>;\n\"constants\"?: undefined | {\n[key: string]: null | {\n\"value\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n};\n\"objectIds\"?: undefined | Array<number>;\n}) => Promise<{\n\"materialId\": number;\n\"objectIds\": Array<number>;\n\"referenceIdChanges\": {\n[key: string]: number;\n};\n\"parameters\"?: undefined | Array<{\n\"name\": string;\n\"referenceId\": number;\n\"value\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"exposed\"?: undefined | false | true;\n}>;\n\"status\": \"applied\";\n\"rendering\": \"unverified\";\n}>);\n\"status\": (() => Promise<{\n\"remaining\": null | number;\n\"pendingResources\": null | {\n[key: string]: Array<string>;\n};\n\"errors\"?: undefined | Array<{\n\"source\": \"compiler-progress\" | \"pending-resources\";\n\"message\": string;\n}>;\n\"shaderDiagnostics\"?: undefined | {\n\"status\": \"unavailable\";\n\"reason\": string;\n};\n\"rendering\": \"unverified\";\n\"explanation\": string;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";

package/dist/generated/materials-declarations.js

@@ -0,0 +1,3 @@
+// Generated by scripts/generate-skill-declarations.mjs.
+// prettier-ignore
+export const WOMP_MATERIALS_DECLARATIONS = "declare const womp: { materials: {\n\"catalog\": ((options?: undefined | {\n\"refreshTextures\"?: undefined | false | true;\n\"includeTextures\"?: undefined | false | true;\n\"operations\"?: undefined | Array<string>;\n}) => Promise<{\n\"operations\": Array<{\n\"op\": string;\n\"category\": string;\n\"title\": string;\n}>;\n\"nodes\": {\n[key: string]: {\n\"type\": string;\n\"title\": string;\n\"description\": string;\n\"inputs\": Array<{\n\"title\": string;\n\"type\": string;\n\"values\"?: undefined | Array<string>;\n}>;\n\"outputs\": Array<{\n\"title\": string;\n\"type\": string;\n\"values\"?: undefined | Array<string>;\n}>;\n};\n};\n\"textureCount\": number;\n\"textures\"?: undefined | Array<string>;\n\"textureMetadata\"?: undefined | {\n\"channels\": \"unknown\";\n\"colorSpace\": \"unknown\";\n\"normalConvention\": \"unknown\";\n\"reason\": string;\n};\n}>);\n\"read\": ((materialId?: undefined | number) => Promise<{\n\"materials\": Array<{\n\"id\": number;\n\"shaderIds\": Array<number>;\n\"objectIds\": Array<number>;\n}>;\n\"material\"?: undefined | {\n\"id\": number;\n\"data\": {\n[key: string]: unknown;\n};\n\"layers\": Array<null | {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>;\n};\n\"diagnostics\": Array<string>;\n}>);\n\"node\": ((options: {\n\"op\": string;\n\"name\"?: undefined | string;\n\"reference_id\"?: undefined | number;\n\"inputs\"?: undefined | {\n[key: string]: number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n\"texture\"?: undefined | string;\n\"ramp\"?: undefined | Array<{\n\"position\": number;\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n}>;\n\"options\"?: undefined | Array<{\n\"name\": string;\n\"value\": number;\n}>;\n}) => {\n\"op\": string;\n[key: string]: unknown;\n});\n\"recipe\": ((options: {\n\"pattern\": \"noise\" | \"grain\" | \"woven\" | \"grid\";\n\"coordinateSpace\": \"object\" | \"world\";\n\"featureSize\": number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"colorA\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"colorB\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"roughnessA\": number;\n\"roughnessB\": number;\n\"metalness\"?: undefined | number;\n\"detail\"?: undefined | number;\n\"relief\": \"height\" | \"bump\";\n\"reliefScale\": number;\n}) => Promise<{\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>);\n\"field\": ((options: {\n\"pattern\": \"noise\" | \"grain\" | \"woven\" | \"grid\" | \"cells\";\n\"coordinateSpace\": \"object\" | \"world\";\n\"featureSize\": number | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"detail\"?: undefined | number;\n\"rotation\"?: undefined | {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"cellMode\"?: undefined | \"Distance\" | \"Edge distance\" | \"Color\" | \"Smooth Distance\" | \"Smooth Color\";\n\"remap\"?: undefined | {\n\"low\": number;\n\"high\": number;\n};\n}) => Promise<{\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}>);\n\"compose\": ((options: {\n\"fields\": Array<{\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}>;\n\"color\"?: undefined | {\n\"low\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"high\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"weights\": Array<number>;\n};\n\"roughness\"?: undefined | {\n\"low\": number;\n\"high\": number;\n\"weights\": Array<number>;\n};\n\"metalness\"?: undefined | number;\n\"relief\"?: undefined | {\n\"mode\": \"height\" | \"bump\";\n\"scale\": number;\n\"weights\": Array<number>;\n\"center\"?: undefined | number;\n};\n}) => Promise<{\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>);\n\"shape\": ((field: {\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}, options: {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"remap\";\n\"low\": number;\n\"high\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"ridge\";\n\"center\": number;\n\"width\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"periodic\";\n\"coordinates\"?: undefined | number;\n\"axis\": 0 | 1 | 2;\n\"sharpness\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"warp\";\n\"coordinates\"?: undefined | number;\n\"frequency\": number;\n\"amplitude\": number;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"palette\";\n\"mode\": \"Constant\" | \"Linear\" | \"Smooth\";\n\"stops\": Array<{\n\"position\": number;\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n}>;\n} | {\n\"name\"?: undefined | string;\n} & {\n\"kind\": \"blend\";\n\"overlay\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n} | {\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n};\n\"mask\": number | {\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n};\n}) => Promise<{\n\"graph\": {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n};\n\"source\": {\n\"node\": number;\n\"slot\": number;\n};\n}>);\n\"inspect\"?: undefined | ((options: {\n\"views\": Array<{\n\"camera\"?: undefined | {\n\"position\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"target\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"projection\"?: undefined | \"perspective\" | \"orthographic\";\n\"horizontalFovDegrees\"?: undefined | number;\n\"orthographicWidth\"?: undefined | number;\n};\n}>;\n\"timeoutMs\"?: undefined | number;\n}) => Promise<{\n\"frames\": Array<{\n\"id\": string;\n\"mediaType\": string;\n\"name\"?: undefined | string;\n}>;\n\"queueSettled\": false | true;\n\"timedOut\": false | true;\n\"status\": {\n\"remaining\": null | number;\n\"pendingResources\": null | {\n[key: string]: Array<string>;\n};\n\"errors\"?: undefined | Array<{\n\"source\": \"compiler-progress\" | \"pending-resources\";\n\"message\": string;\n}>;\n\"shaderDiagnostics\"?: undefined | {\n\"status\": \"unavailable\";\n\"reason\": string;\n};\n\"rendering\": \"unverified\";\n\"explanation\": string;\n};\n}>);\n\"write\": ((options: {\n\"materialId\"?: undefined | number;\n\"cloneFrom\"?: undefined | number;\n\"layers\"?: undefined | Array<null | {\n\"nodes\": Array<{\n\"op\": string;\n[key: string]: unknown;\n}>;\n\"connections\": Array<{\n\"input_node\": number;\n\"input_slot\": number;\n\"output_node\": number;\n\"output_slot\": number;\n\"flags\"?: undefined | number;\n}>;\n}>;\n\"constants\"?: undefined | {\n[key: string]: null | {\n\"value\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n};\n};\n\"objectIds\"?: undefined | Array<number>;\n}) => Promise<{\n\"materialId\": number;\n\"objectIds\": Array<number>;\n\"referenceIdChanges\": {\n[key: string]: number;\n};\n\"parameters\"?: undefined | Array<{\n\"name\": string;\n\"referenceId\": number;\n\"value\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"color\": {\n\"x\": number;\n\"y\": number;\n\"z\": number;\n};\n\"exposed\"?: undefined | false | true;\n}>;\n\"status\": \"applied\";\n\"rendering\": \"unverified\";\n}>);\n\"status\": (() => Promise<{\n\"remaining\": null | number;\n\"pendingResources\": null | {\n[key: string]: Array<string>;\n};\n\"errors\"?: undefined | Array<{\n\"source\": \"compiler-progress\" | \"pending-resources\";\n\"message\": string;\n}>;\n\"shaderDiagnostics\"?: undefined | {\n\"status\": \"unavailable\";\n\"reason\": string;\n};\n\"rendering\": \"unverified\";\n\"explanation\": string;\n}>);\n} };\ndeclare function print(...values: unknown[]): void;\ndeclare function emitImage(ref: { id: string; mediaType: string; name?: string }, options?: { inspect?: boolean }): Promise<void>;\ndeclare function emitFile(ref: { id: string; mediaType: string; name?: string }): Promise<void>;\n";

package/dist/kakapo.d.ts

@@ -8,3 +8,4 @@ export { createSdkOpenScadHost, type SdkOpenScadHostOptions, } from "./sdk-opens
 export { createSdkSceneHealthHost } from "./sdk-scene-health-host.js";
 export * from "./scene-health.js";
 export * from "./repair-state.js";
+export { createSdkMaterialsHost, type SdkMaterialsHostOptions } from "./sdk-materials-host.js";

package/dist/kakapo.js

@@ -6,3 +6,4 @@ export { createSdkOpenScadHost, } from "./sdk-openscad-host.js";
 export { createSdkSceneHealthHost } from "./sdk-scene-health-host.js";
 export * from "./scene-health.js";
 export * from "./repair-state.js";
+export { createSdkMaterialsHost } from "./sdk-materials-host.js";

package/dist/materials/composition.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import type { MaterialCatalog, MaterialCompositionOptions, MaterialGraph } from "./types.js";
+export declare const materialCompositionSchema: z.ZodObject<{
+    fields: z.ZodArray<z.ZodObject<{
+        graph: z.ZodObject<{
+            nodes: z.ZodArray<z.ZodObject<{
+                op: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+                location: z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strict>>;
+                editor_flags: z.ZodOptional<z.ZodNumber>;
+                reference_id: z.ZodOptional<z.ZodNumber>;
+                out: z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                    z: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$catchall<z.ZodType<import("./types.js").MaterialJson, unknown, z.core.$ZodTypeInternals<import("./types.js").MaterialJson, unknown>>>>>;
+            connections: z.ZodArray<z.ZodObject<{
+                input_node: z.ZodNumber;
+                input_slot: z.ZodNumber;
+                output_node: z.ZodNumber;
+                output_slot: z.ZodNumber;
+                flags: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<2>]>>;
+            }, z.core.$strict>>;
+        }, z.core.$catchall<z.ZodType<import("./types.js").MaterialJson, unknown, z.core.$ZodTypeInternals<import("./types.js").MaterialJson, unknown>>>>;
+        source: z.ZodObject<{
+            node: z.ZodNumber;
+            slot: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    color: z.ZodOptional<z.ZodObject<{
+        low: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>;
+        high: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>;
+        weights: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>>;
+    roughness: z.ZodOptional<z.ZodObject<{
+        low: z.ZodNumber;
+        high: z.ZodNumber;
+        weights: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>>;
+    metalness: z.ZodOptional<z.ZodNumber>;
+    relief: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            height: "height";
+            bump: "bump";
+        }>;
+        scale: z.ZodNumber;
+        weights: z.ZodArray<z.ZodNumber>;
+        center: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare function materialCompositionOperations(options: MaterialCompositionOptions): string[];
+export declare function makeMaterialComposition(options: MaterialCompositionOptions, catalogue: MaterialCatalog): MaterialGraph;