@womp/spark-agent 5.2.3 → 5.4.0

package/dist/materials/surface-recipes.js

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import { INTERNAL_UNITS_PER_MM } from "../coordinates.js";
+import { makeMaterialNode } from "./graph.js";
+export const MATERIAL_RECIPE_RELIEF_GUIDANCE = `Pattern-specific calibration observations (native strength, object coordinates, detail 4, height and bump tested independently):
+- Dual-scale grid, featureSize 1: height 0.0003–0.001; start at 0.0003.
+- Noise, featureSize 0.04: 0.01–0.03 produced visible fine relief.
+- Crossed periodic threads, featureSize 0.04: 0.003–0.03 retained rounded thread shading.
+- Noise, featureSize 0.08: 0.01–0.03 produced low-amplitude grain.
+- Fine directional grain, featureSize {x:0.015,y:0.015,z:2}: 0.0003–0.003 produced faint directional relief; 0.01 and above produced stronger ridges.
+These observations on curved and flat fixtures under fixed lighting are starting points, not quality targets or upper limits. Use independently weighted structural and micro height fields. Choose visible relief by its actual gradient, scale and requested finish; universal bump multipliers can destroy gloss. Compare close and grazing views without changing the scene. Height and bump strengths are not generally interchangeable.`;
+const positiveVector = z.object({ x: z.number().finite().positive(), y: z.number().finite().positive(), z: z.number().finite().positive() }).strict();
+const color = z.object({ x: z.number().min(0).max(1), y: z.number().min(0).max(1), z: z.number().min(0).max(1) }).strict();
+export const materialRecipeSchema = z.object({
+    pattern: z.enum(["noise", "grain", "woven", "grid"]),
+    coordinateSpace: z.enum(["object", "world"]),
+    featureSize: z.union([z.number().finite().positive(), positiveVector]),
+    colorA: color,
+    colorB: color,
+    roughnessA: z.number().min(0).max(1),
+    roughnessB: z.number().min(0).max(1),
+    metalness: z.number().min(0).max(1).optional(),
+    detail: z.number().int().min(1).max(16).optional(),
+    relief: z.enum(["height", "bump"]),
+    reliefScale: z.number().finite(),
+}).strict();
+export const materialFieldSchema = materialRecipeSchema.pick({ coordinateSpace: true, featureSize: true, detail: true }).extend({
+    pattern: z.enum(["noise", "grain", "woven", "grid", "cells"]),
+    rotation: z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).strict().optional(),
+    cellMode: z.enum(["Distance", "Edge distance", "Color", "Smooth Distance", "Smooth Color"]).optional(),
+    remap: z.object({ low: z.number().finite(), high: z.number().finite() }).strict().refine(range => range.low !== range.high, "Remap endpoints must differ").optional(),
+}).strict().refine(options => options.cellMode === undefined || options.pattern === "cells", "cellMode requires cells");
+export function materialFieldOperations(options) {
+    return [options.coordinateSpace === "object" ? "InputPosition" : "InputWorldPosition", "Mapping", "MathLerp",
+        ...(["noise", "grain"].includes(options.pattern) ? ["NoiseFBM"] : []),
+        ...(options.pattern === "cells" ? ["NoiseVoronoi"] : []),
+        ...(["woven", "grid"].includes(options.pattern) ? [options.coordinateSpace === "object" ? "InputNormal" : "InputWorldNormal", "Projection", "GetComponent"] : []),
+        ...(["woven", "grid"].includes(options.pattern) || options.remap ? ["Math"] : [])];
+}
+export function materialRecipeOperations(options) {
+    return [...materialFieldOperations(options), "Constant", "OutputMaterial",
+        ...(options.relief === "height" ? ["OutputHeight"] : ["Bump", "OutputSurfaceNormal"])];
+}
+export function makeMaterialField(options, catalogue) {
+    const graph = { nodes: [], connections: [] };
+    const node = (op, inputs, name) => {
+        if (!catalogue.nodes[op])
+            throw new Error("Recipe operation unavailable: " + op);
+        graph.nodes.push(makeMaterialNode({ op, inputs, name }));
+        return graph.nodes.length - 1;
+    };
+    const connect = (source, target, port, output = 0) => {
+        graph.connections.push({ input_node: source, input_slot: output, output_node: target, output_slot: port, flags: 0 });
+    };
+    const selector = (op, port, label) => {
+        const index = catalogue.nodes[op]?.inputs[port]?.values?.indexOf(label) ?? -1;
+        if (index < 0)
+            throw new Error("Recipe requires " + op + " option " + label);
+        return index;
+    };
+    const size = typeof options.featureSize === "number" ? { x: options.featureSize, y: options.featureSize, z: options.featureSize } : options.featureSize;
+    const coordinateUnit = options.coordinateSpace === "world" ? 1 / INTERNAL_UNITS_PER_MM : 1;
+    const frequency = { x: coordinateUnit / size.x, y: coordinateUnit / size.y, z: coordinateUnit / size.z };
+    const positionOp = options.coordinateSpace === "object" ? "InputPosition" : "InputWorldPosition";
+    const normalOp = options.coordinateSpace === "object" ? "InputNormal" : "InputWorldNormal";
+    let position = node(positionOp, {}, options.coordinateSpace + " coordinates");
+    if (options.pattern === "woven" || options.pattern === "grid") {
+        let normal = node(normalOp, {}, "Matching projection normal");
+        if (options.rotation) {
+            const rotatePosition = node("Mapping", { 1: 0, 2: options.rotation, 3: 1 }, "Rotated position");
+            const rotateNormal = node("Mapping", { 1: 0, 2: options.rotation, 3: 1 }, "Rotated projection normal");
+            connect(position, rotatePosition, 0);
+            connect(normal, rotateNormal, 0);
+            position = rotatePosition;
+            normal = rotateNormal;
+        }
+        const projected = node("Projection", { 0: selector("Projection", 0, "Cubic"), 3: 1, 4: 0, 5: 0 }, "Physical face coordinates");
+        connect(position, projected, 1);
+        connect(normal, projected, 2);
+        position = projected;
+    }
+    const mapping = node("Mapping", { 1: 0, 2: options.pattern === "woven" || options.pattern === "grid" ? 0 : options.rotation ?? 0, 3: frequency }, "Feature size in selected coordinates");
+    connect(position, mapping, 0);
+    const detail = options.detail ?? 4;
+    let pattern;
+    if (options.pattern === "grid") {
+        const lines = (coordinates, label) => {
+            const fraction = node("Math", { 0: selector("Math", 0, "Fraction"), 3: 0 }, "Grid cell coordinates");
+            connect(coordinates, fraction, 1);
+            const edges = [0, 1].map(axis => {
+                const component = node("GetComponent", { 1: axis }, "Grid axis");
+                connect(fraction, component, 0);
+                const reverse = node("Math", { 0: selector("Math", 0, "Subtract"), 1: 1, 3: 0 }, "Opposite cell edge");
+                connect(component, reverse, 2);
+                const edge = node("Math", { 0: selector("Math", 0, "Min"), 3: 0 }, "Nearest cell edge");
+                connect(component, edge, 1);
+                connect(reverse, edge, 2);
+                return edge;
+            });
+            const edge = node("Math", { 0: selector("Math", 0, "Min"), 3: 0 }, "Grid line distance");
+            connect(edges[0], edge, 1);
+            connect(edges[1], edge, 2);
+            const coverage = node("Math", { 0: selector("Math", 0, "Divide"), 2: 0.04, 3: 1 }, "Grid line coverage");
+            connect(edge, coverage, 1);
+            const mask = node("Math", { 0: selector("Math", 0, "Subtract"), 1: 1, 3: 0 }, label);
+            connect(coverage, mask, 2);
+            return mask;
+        };
+        const major = lines(mapping, "Major grid lines");
+        const minorCoordinates = node("Mapping", { 1: 0, 2: 0, 3: 10 }, "One-tenth-unit grid coordinates");
+        connect(mapping, minorCoordinates, 0);
+        const minor = lines(minorCoordinates, "Minor grid lines");
+        const minorContrast = node("Math", { 0: selector("Math", 0, "Mulitiply"), 2: 0.35, 3: 0 }, "Lower-contrast minor grid");
+        connect(minor, minorContrast, 1);
+        pattern = node("Math", { 0: selector("Math", 0, "Max"), 3: 0 }, "Combined two-scale grid");
+        connect(major, pattern, 1);
+        connect(minorContrast, pattern, 2);
+    }
+    else if (options.pattern === "grain") {
+        const warp = node("NoiseFBM", { 1: 0.16, 2: 3, 3: 0.35, 4: 1 }, "Slow grain meander");
+        connect(mapping, warp, 0);
+        const warped = node("Mapping", { 1: 0, 2: 0, 3: 1 }, "Warped grain coordinates");
+        connect(mapping, warped, 0);
+        connect(warp, warped, 1);
+        pattern = node("NoiseFBM", { 1: 1, 2: detail, 3: 1, 4: 0 }, "Directional grain");
+        connect(warped, pattern, 0);
+    }
+    else if (options.pattern === "woven") {
+        const threads = [0, 1].map(axis => {
+            const component = node("GetComponent", { 1: axis }, axis === 0 ? "Warp axis" : "Weft axis");
+            connect(mapping, component, 0);
+            const phase = node("Math", { 0: selector("Math", 0, "Mulitiply"), 2: Math.PI * 2, 3: 0 }, "Thread repeat phase");
+            connect(component, phase, 1);
+            const sine = node("Math", { 0: selector("Math", 0, "Sine"), 3: 0 }, "Rounded thread profile");
+            connect(phase, sine, 1);
+            const thread = node("MathLerp", { 0: 0.5, 1: 1 }, "Positive thread height");
+            connect(sine, thread, 2);
+            return thread;
+        });
+        pattern = node("MathLerp", { 2: 0.5 }, "Crossed warp and weft");
+        connect(threads[0], pattern, 0);
+        connect(threads[1], pattern, 1);
+    }
+    else if (options.pattern === "cells") {
+        pattern = node("NoiseVoronoi", { 1: 1, 2: selector("NoiseVoronoi", 2, options.cellMode ?? "Distance"), 3: selector("NoiseVoronoi", 3, "Euclidean") }, "Cellular structure");
+        connect(mapping, pattern, 0);
+    }
+    else {
+        pattern = node("NoiseFBM", { 1: 1, 2: detail, 3: 1, 4: 0 }, "Irregular surface structure");
+        connect(mapping, pattern, 0);
+    }
+    if (options.remap) {
+        const shifted = node("Math", { 0: selector("Math", 0, "Subtract"), 2: options.remap.low, 3: 0 }, "Mask offset");
+        connect(pattern, shifted, 1);
+        const normalized = node("Math", { 0: selector("Math", 0, "Divide"), 2: options.remap.high - options.remap.low, 3: 1 }, "Clamped field contrast");
+        connect(shifted, normalized, 1);
+        pattern = normalized;
+    }
+    return { graph, source: { node: pattern, slot: 0 } };
+}
+export function makeMaterialRecipe(options, catalogue) {
+    const { graph, source } = makeMaterialField(options, catalogue);
+    const pattern = source.node;
+    const node = (op, inputs, name) => {
+        if (!catalogue.nodes[op])
+            throw new Error("Recipe operation unavailable: " + op);
+        graph.nodes.push(makeMaterialNode({ op, inputs, name }));
+        return graph.nodes.length - 1;
+    };
+    const connect = (input, output, slot, sourceSlot = 0) => graph.connections.push({ input_node: input, input_slot: sourceSlot, output_node: output, output_slot: slot, flags: 0 });
+    const colorMix = node("MathLerp", { 0: options.colorA, 1: options.colorB }, "Structure-correlated color");
+    connect(pattern, colorMix, 2);
+    const roughness = node("MathLerp", { 0: options.roughnessA, 1: options.roughnessB }, "Structure-correlated roughness");
+    connect(pattern, roughness, 2);
+    const metal = node("Constant", { 1: options.metalness ?? 0 }, "Metalness");
+    const output = node("OutputMaterial", {}, "Editable surface material");
+    connect(colorMix, output, 0);
+    connect(roughness, output, 4);
+    connect(metal, output, 3, 1);
+    const strength = node("Constant", { 1: options.reliefScale, 3: 3 }, "Surface relief strength");
+    if (options.relief === "height") {
+        const height = node("OutputHeight", {}, "Height shading");
+        connect(pattern, height, 0);
+        connect(strength, height, 2, 1);
+    }
+    else {
+        const bump = node("Bump", {}, "Procedural bump normal");
+        connect(pattern, bump, 0);
+        connect(strength, bump, 1, 1);
+        const normal = node("OutputSurfaceNormal", {}, "Tangent normal output");
+        connect(bump, normal, 0);
+    }
+    return graph;
+}

package/dist/materials/types.d.ts

@@ -0,0 +1,222 @@
+/** Native graph values: colors are 0..1, positions use renderer units. */
+export type MaterialJson = null | boolean | number | string | MaterialJson[] | {
+    [key: string]: MaterialJson;
+};
+export type MaterialVector = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type MaterialNode = {
+    op: string;
+    [key: string]: unknown;
+};
+export type MaterialConnection = {
+    input_node: number;
+    input_slot: number;
+    output_node: number;
+    output_slot: number;
+    flags?: number;
+};
+export type MaterialGraph = {
+    nodes: MaterialNode[];
+    connections: MaterialConnection[];
+};
+export type MaterialConstant = {
+    value: MaterialVector;
+    color: MaterialVector;
+};
+export type MaterialPort = {
+    title: string;
+    type: string;
+    values?: string[];
+};
+export type MaterialNodeDescription = {
+    type: string;
+    title: string;
+    description: string;
+    inputs: MaterialPort[];
+    outputs: MaterialPort[];
+};
+export type MaterialCatalog = {
+    operations: {
+        op: string;
+        category: string;
+        title: string;
+    }[];
+    nodes: Record<string, MaterialNodeDescription>;
+    textureCount: number;
+    textures?: string[];
+    /** Metadata availability for the listed textures; names do not establish their encoding. */
+    textureMetadata?: {
+        channels: "unknown";
+        colorSpace: "unknown";
+        normalConvention: "unknown";
+        reason: string;
+    };
+};
+export type MaterialCatalogOptions = {
+    refreshTextures?: boolean;
+    includeTextures?: boolean;
+    operations?: string[];
+};
+export type MaterialSnapshot = {
+    materials: {
+        id: number;
+        shaderIds: number[];
+        objectIds: number[];
+    }[];
+    material?: {
+        id: number;
+        data: {
+            [key: string]: unknown;
+        };
+        layers: (MaterialGraph | null)[];
+    };
+    /** Direct assignments and curve points; procedural geometry can also reference this ID. */
+    diagnostics: string[];
+};
+export type MaterialWrite = {
+    /** Existing material: affects every reference to this material ID. */
+    materialId?: number;
+    /** Create an independent copy, including base properties. */
+    cloneFrom?: number;
+    /** Complete ordered replacement, maximum eight slots. null is an empty slot. */
+    layers?: (MaterialGraph | null)[];
+    /** Partial override changes. null resets a Constant using a new reference ID. */
+    constants?: Record<string, MaterialConstant | null>;
+    /** Assign to these nodes; curves assign every point. */
+    objectIds?: number[];
+};
+export type MaterialWriteResult = {
+    materialId: number;
+    objectIds: number[];
+    /** Remapped Constants after resets or replacement of unoverridden graph nodes. */
+    referenceIdChanges: Record<string, number>;
+    /** SDK hosts return current Constant handles after allocation/reset/remapping. */
+    parameters?: {
+        name: string;
+        referenceId: number;
+        value: MaterialVector;
+        color: MaterialVector;
+        exposed?: boolean;
+    }[];
+    status: "applied";
+    rendering: "unverified";
+};
+export type MaterialNodeOptions = {
+    op: string;
+    name?: string;
+    reference_id?: number;
+    /** Native input slots; scalar literals are broadcast to x/y/z. */
+    inputs?: Record<string, number | MaterialVector>;
+    texture?: string;
+    ramp?: {
+        position: number;
+        color: MaterialVector;
+    }[];
+    options?: {
+        name: string;
+        value: number;
+    }[];
+};
+/** Editable starting graphs with explicit coordinate space; not complete reference matches. */
+export type MaterialRecipeOptions = {
+    pattern: "noise" | "grain" | "woven" | "grid";
+    coordinateSpace: "object" | "world";
+    /** Object-space units, or physical millimeters for world space. Vectors use graph axes. */
+    featureSize: number | MaterialVector;
+    /** Linear RGB in 0..1; decode display/reference colors before supplying them. */
+    colorA: MaterialVector;
+    /** Linear RGB in 0..1. */
+    colorB: MaterialVector;
+    roughnessA: number;
+    roughnessB: number;
+    metalness?: number;
+    detail?: number;
+    relief: "height" | "bump";
+    /** Native shading-normal strength, not displacement distance. */
+    reliefScale: number;
+};
+/** Numeric structure without surface outputs. Scalars drive finish/relief; RGB fields preserve color components. */
+export type MaterialField = {
+    graph: MaterialGraph;
+    source: {
+        node: number;
+        slot: number;
+    };
+};
+export type MaterialFieldOptions = {
+    pattern: "noise" | "grain" | "woven" | "grid" | "cells";
+    coordinateSpace: "object" | "world";
+    /** Object-coordinate units, or millimeters for world space. */
+    featureSize: number | MaterialVector;
+    detail?: number;
+    /** Rotation in degrees, applied to paired position/normal coordinates. */
+    rotation?: MaterialVector;
+    /** Cellular output; defaults to Distance. */
+    cellMode?: "Distance" | "Edge distance" | "Color" | "Smooth Distance" | "Smooth Color";
+    /** Clamp (field - low) / (high - low) to 0..1. Reversed endpoints invert the mask. */
+    remap?: {
+        low: number;
+        high: number;
+    };
+};
+export type MaterialCompositionOptions = {
+    /** Copied fields get independent Constant handles on write; source handles are not retained. */
+    fields: MaterialField[];
+    /** Linear RGB endpoints. Weights correspond to fields and sum to at most 1. */
+    color?: {
+        low: MaterialVector;
+        high: MaterialVector;
+        weights: number[];
+    };
+    roughness?: {
+        low: number;
+        high: number;
+        weights: number[];
+    };
+    metalness?: number;
+    /** Combine scalar height fields before deriving normals. Weights may be signed. */
+    relief?: {
+        mode: "height" | "bump";
+        scale: number;
+        weights: number[];
+        center?: number;
+    };
+};
+/** Generic analytic shaping; coordinates default to the field's feature-size Mapping. */
+export type MaterialShapeOptions = {
+    name?: string;
+} & ({
+    kind: "remap";
+    low: number;
+    high: number;
+} | {
+    kind: "ridge";
+    center: number;
+    width: number;
+} | {
+    kind: "periodic";
+    coordinates?: number;
+    axis: 0 | 1 | 2;
+    sharpness: number;
+} | {
+    kind: "warp";
+    coordinates?: number;
+    frequency: number;
+    amplitude: number;
+} | {
+    kind: "palette";
+    mode: "Constant" | "Linear" | "Smooth";
+    stops: {
+        position: number;
+        color: MaterialVector;
+    }[];
+}
+/** Linear interpolation from this field to overlay. A mask field uses its X component, clamped to 0..1. */
+ | {
+    kind: "blend";
+    overlay: MaterialField | MaterialVector;
+    mask: MaterialField | number;
+});

package/dist/materials/types.js

@@ -0,0 +1 @@
+export {};

package/dist/models.d.ts

@@ -17,6 +17,13 @@ export declare const SPARK_MODELS: readonly [{
     readonly note: "Best OpenAI quality";
     readonly provider: "openai";
     readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
+}, {
+    readonly id: "gpt-6.1-sol";
+    readonly contextWindow: 1050000;
+    readonly label: "GPT-6.1 Sol";
+    readonly note: "Complex coding and agentic workflows";
+    readonly provider: "openai";
+    readonly reasoningEfforts: readonly ["low", "medium", "high", "xhigh", "max"];
 }, {
     readonly id: "gpt-6-sol";
     readonly contextWindow: 1050000;

package/dist/models.js

@@ -22,6 +22,14 @@ export const SPARK_MODELS = [
         provider: "openai",
         reasoningEfforts: EXTENDED_REASONING_EFFORTS,
     },
+    {
+        id: "gpt-6.1-sol",
+        contextWindow: 1_050_000,
+        label: "GPT-6.1 Sol",
+        note: "Complex coding and agentic workflows",
+        provider: "openai",
+        reasoningEfforts: EXTENDED_REASONING_EFFORTS,
+    },
     {
         id: "gpt-6-sol",
         // https://developers.openai.com/api/docs/models/gpt-6-sol

package/dist/pricing.js

@@ -1,5 +1,10 @@
 // Standard, global, direct API rates in USD per million tokens, checked 2026-09-09.
 const PRICES = {
+    "gpt-6.1-sol": {
+        input: 2, read: 0.1, write: 2.5, output: 10, longContext: 272_000,
+        source: "https://developers.openai.com/api/docs/models/gpt-6.1-sol",
+        pricingDate: "2026-09-29",
+    },
     "gpt-6-sol": {
         input: 2, read: 0.2, write: 2.5, output: 10, longContext: 272_000,
         source: "https://developers.openai.com/api/docs/pricing",

package/dist/prompt.d.ts

@@ -1 +1 @@
-export declare const SPARK_AGENT_PROMPT = "You are Spark, Womp's unified assistant.\nUse read_skill to discover the APIs needed for the user's request. Skills provide TypeScript\ndeclarations for documentation; execute_javascript runs JavaScript, with top-level await.\nOnly the listed capabilities are available. Reading a skill does not grant additional permissions.\nUse only the supplied womp APIs and output helpers to access application services and state.\nIf a capability is unavailable, explain what is missing and ask the user to enable it when applicable.\nDo not work around missing capabilities by inspecting page globals, DOM or framework internals,\nor making direct network requests. Native execution is not a security sandbox; it does not expand\nthe supported API or the user's granted capabilities.\nGive each execute_javascript call a concise present-progressive purpose, such as \"Generating a car image\", \"Inspecting the scene\", or \"Importing the model\". Write purpose before code.\nEach execution has fresh local variables. Keep stable object, job, and artifact references.\nUse print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact\nreference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.\nCompleted generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.\nDo not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.\nInspect the scene before editing and verify the committed result.\nPreserve existing content unless the user asks to replace or delete it. Use the latest target revision\nwhen a write requires one. Capabilities own transactions: an entire script is not atomic.\nIf an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.\nNever claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.\nComplete related work in this conversation without delegating to another agent. Report limits,\nunsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation\nof the result in the user's language; keep implementation details out of that explanation.\n\nCreation intent\n\nResolve the requested outcome from the current message and preceding dialogue, not keyword matches.\nExplicit method choices take precedence. Continue edits in the existing representation unless the user\nasks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.\n\n- Build ordinary or underspecified creations directly with editable scene shapes, including\n  \"a car\" and \"make X in 3D\". Proceed without an image preview or method-selection menu.\n  Organic appearance alone does not require mesh generation or Geometry Nodes.\n\n- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,\n  except when another method is explicit (including primitives with dimensions), or when\n  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:\n  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.\n\n- Generate/edit images or generate meshes when requested. An attached image or reference alone\n  does not request generation; use it for the requested workflow or clarify an unresolved request.\n  Generating a result does not authorize importing, converting, or building it in the scene.\n\n- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or\n  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be\n  open; explain that prerequisite if closed instead of silently generating inline. Merely opening\n  Flow does not redirect ordinary scene requests or inline generation to it.\n\n- After completing explicitly requested generation, you may briefly suggest a relevant next step\n  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,\n  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing\n  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the\n  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.\n\n- Choose construction methods by the user's requested workflow and the\n  available capabilities, not by assuming editable shapes require lower\n  fidelity. A sculpted appearance does not by itself require mesh generation.\n  Respect an explicit method choice and pursue the reference's visible shape\n  and detail with that method. Offer alternatives only for a specific\n  demonstrated limitation; ask before switching or simplifying the requested\n  result. No method guarantees exact reconstruction from a single image.\n\n- Ask at most one focused question at a time, only when a sensible default\n  would likely produce the wrong outcome. Do not repeat resolved questions.\n  Interpret replies using the preceding offer; if several options were\n  offered and \u201Cyes\u201D does not identify one, clarify briefly.\n\n- Treat a clear answer to your question as an instruction to proceed.\n  Continue from existing results rather than restarting the workflow.\n\nOffer only workflows available in this host. Follow their authorization\nand confirmation requirements before generation or scene changes. If a requested workflow is unavailable,\nexplain the limitation rather than silently substituting another.";
+export declare const SPARK_AGENT_PROMPT = "You are Spark, Womp's unified assistant.\nUse read_skill({names:[...]}) to load the required APIs together. Skills provide TypeScript\ndeclarations for documentation; execute_javascript runs JavaScript, with top-level await.\nOnly the listed capabilities are available. Reading a skill does not grant additional permissions.\nUse only the supplied womp APIs and output helpers to access application services and state.\nIf a capability is unavailable, explain what is missing and ask the user to enable it when applicable.\nDo not work around missing capabilities by inspecting page globals, DOM or framework internals,\nor making direct network requests. Native execution is not a security sandbox; it does not expand\nthe supported API or the user's granted capabilities.\nGive each execute_javascript call a concise present-progressive purpose, such as \"Generating a car image\", \"Inspecting the scene\", or \"Importing the model\". Write purpose before code.\nEach execution has fresh local variables. Keep stable object, job, and artifact references.\nUse print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact\nreference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.\nCompleted generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.\nDo not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.\nInspect the scene before editing and verify the committed result.\nPreserve existing content unless the user asks to replace or delete it. Use the latest target revision\nwhen a write requires one. Capabilities own transactions: an entire script is not atomic.\nIf an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.\nNever claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.\nComplete related work in this conversation without delegating to another agent. Report limits,\nunsupported actions, cancellation, and incomplete work truthfully. Finish with a concise explanation\nof the result in the user's language; keep implementation details out of that explanation.\n\nCreation intent\n\nResolve the requested outcome from the current message and preceding dialogue, not keyword matches.\nExplicit method choices take precedence. Continue edits in the existing representation unless the user\nasks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.\n\n- Build ordinary or underspecified creations directly with editable scene shapes, including\n  \"a car\" and \"make X in 3D\". Proceed without an image preview or method-selection menu.\n  Organic appearance alone does not require mesh generation or Geometry Nodes.\n\n- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,\n  except when another method is explicit (including primitives with dimensions), or when\n  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:\n  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.\n\n- Generate/edit images or generate meshes when requested. An attached image or reference alone\n  does not request generation; use it for the requested workflow or clarify an unresolved request.\n  Generating a result does not authorize importing, converting, or building it in the scene.\n\n- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or\n  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be\n  open; explain that prerequisite if closed instead of silently generating inline. Merely opening\n  Flow does not redirect ordinary scene requests or inline generation to it.\n\n- After completing explicitly requested generation, you may briefly suggest a relevant next step\n  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,\n  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing\n  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the\n  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.\n\n- Choose construction methods by the user's requested workflow and the\n  available capabilities, not by assuming editable shapes require lower\n  fidelity. A sculpted appearance does not by itself require mesh generation.\n  Respect an explicit method choice and pursue the reference's visible shape\n  and detail with that method. Offer alternatives only for a specific\n  demonstrated limitation; ask before switching or simplifying the requested\n  result. No method guarantees exact reconstruction from a single image.\n\n- Ask at most one focused question at a time, only when a sensible default\n  would likely produce the wrong outcome. Do not repeat resolved questions.\n  Interpret replies using the preceding offer; if several options were\n  offered and \u201Cyes\u201D does not identify one, clarify briefly.\n\n- Treat a clear answer to your question as an instruction to proceed.\n  Continue from existing results rather than restarting the workflow.\n\nOffer only workflows available in this host. Follow their authorization\nand confirmation requirements before generation or scene changes. If a requested workflow is unavailable,\nexplain the limitation rather than silently substituting another.";

package/dist/prompt.js

@@ -1,5 +1,5 @@
 export const SPARK_AGENT_PROMPT = `You are Spark, Womp's unified assistant.
-Use read_skill to discover the APIs needed for the user's request. Skills provide TypeScript
+Use read_skill({names:[...]}) to load the required APIs together. Skills provide TypeScript
 declarations for documentation; execute_javascript runs JavaScript, with top-level await.
 Only the listed capabilities are available. Reading a skill does not grant additional permissions.
 Use only the supplied womp APIs and output helpers to access application services and state.
@@ -24,41 +24,41 @@ of the result in the user's language; keep implementation details out of that ex
 
 Creation intent
 
-Resolve the requested outcome from the current message and preceding dialogue, not keyword matches.
-Explicit method choices take precedence. Continue edits in the existing representation unless the user
-asks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.
+Resolve the requested outcome from the current message and preceding dialogue, not keyword matches.
+Explicit method choices take precedence. Continue edits in the existing representation unless the user
+asks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.
 
-- Build ordinary or underspecified creations directly with editable scene shapes, including
-  "a car" and "make X in 3D". Proceed without an image preview or method-selection menu.
-  Organic appearance alone does not require mesh generation or Geometry Nodes.
+- Build ordinary or underspecified creations directly with editable scene shapes, including
+  "a car" and "make X in 3D". Proceed without an image preview or method-selection menu.
+  Organic appearance alone does not require mesh generation or Geometry Nodes.
 
-- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,
-  except when another method is explicit (including primitives with dimensions), or when
-  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:
-  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.
+- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,
+  except when another method is explicit (including primitives with dimensions), or when
+  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:
+  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.
 
-- Generate/edit images or generate meshes when requested. An attached image or reference alone
-  does not request generation; use it for the requested workflow or clarify an unresolved request.
-  Generating a result does not authorize importing, converting, or building it in the scene.
+- Generate/edit images or generate meshes when requested. An attached image or reference alone
+  does not request generation; use it for the requested workflow or clarify an unresolved request.
+  Generating a result does not authorize importing, converting, or building it in the scene.
 
-- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or
-  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be
-  open; explain that prerequisite if closed instead of silently generating inline. Merely opening
-  Flow does not redirect ordinary scene requests or inline generation to it.
+- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or
+  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be
+  open; explain that prerequisite if closed instead of silently generating inline. Merely opening
+  Flow does not redirect ordinary scene requests or inline generation to it.
 
-- After completing explicitly requested generation, you may briefly suggest a relevant next step
-  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,
-  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing
-  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the
-  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.
+- After completing explicitly requested generation, you may briefly suggest a relevant next step
+  using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,
+  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing
+  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the
+  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.
 
-- Choose construction methods by the user's requested workflow and the
-  available capabilities, not by assuming editable shapes require lower
-  fidelity. A sculpted appearance does not by itself require mesh generation.
-  Respect an explicit method choice and pursue the reference's visible shape
-  and detail with that method. Offer alternatives only for a specific
-  demonstrated limitation; ask before switching or simplifying the requested
-  result. No method guarantees exact reconstruction from a single image.
+- Choose construction methods by the user's requested workflow and the
+  available capabilities, not by assuming editable shapes require lower
+  fidelity. A sculpted appearance does not by itself require mesh generation.
+  Respect an explicit method choice and pursue the reference's visible shape
+  and detail with that method. Offer alternatives only for a specific
+  demonstrated limitation; ask before switching or simplifying the requested
+  result. No method guarantees exact reconstruction from a single image.
 
 - Ask at most one focused question at a time, only when a sensible default
   would likely produce the wrong outcome. Do not repeat resolved questions.
@@ -68,6 +68,6 @@ asks to change it. Creation defaults do not apply to help, discussion, imports,
 - Treat a clear answer to your question as an instruction to proceed.
   Continue from existing results rather than restarting the workflow.
 
-Offer only workflows available in this host. Follow their authorization
-and confirmation requirements before generation or scene changes. If a requested workflow is unavailable,
+Offer only workflows available in this host. Follow their authorization
+and confirmation requirements before generation or scene changes. If a requested workflow is unavailable,
 explain the limitation rather than silently substituting another.`;

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;