@womp/spark-agent 5.2.3 → 5.4.0

package/dist/materials/composition.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { graphSchema, makeMaterialNode, pruneMaterialGraph, validateMaterialGraph } from "./graph.js";
+const weights = z.array(z.number().finite());
+const mixWeights = weights.refine(values => values.every(value => value >= 0) && values.reduce((a, b) => a + b, 0) <= 1 + 1e-9, "Color/roughness weights must be nonnegative and sum to at most 1");
+const unit = z.number().min(0).max(1);
+const color = z.object({ x: unit, y: unit, z: unit }).strict();
+export const materialCompositionSchema = z.object({
+    fields: z.array(z.object({ graph: graphSchema, source: z.object({ node: z.number().int().nonnegative(), slot: z.number().int().min(0).max(19) }).strict() }).strict()).min(1),
+    color: z.object({ low: color, high: color, weights: mixWeights }).strict().optional(),
+    roughness: z.object({ low: unit, high: unit, weights: mixWeights }).strict().optional(),
+    metalness: unit.optional(),
+    relief: z.object({ mode: z.enum(["height", "bump"]), scale: z.number().finite(), weights, center: z.number().finite().optional() }).strict().optional(),
+}).strict().superRefine((options, context) => {
+    for (const channel of ["color", "roughness", "relief"])
+        if (options[channel] && options[channel].weights.length !== options.fields.length)
+            context.addIssue({ code: "custom", path: [channel, "weights"], message: "Provide one weight per field" });
+    options.fields.forEach((field, index) => {
+        if (!field.graph.nodes[field.source.node])
+            context.addIssue({ code: "custom", path: ["fields", index, "source"], message: "Field output node does not exist" });
+        if (field.graph.nodes.some(node => node.op.startsWith("Output")))
+            context.addIssue({ code: "custom", path: ["fields", index], message: "Fields must not contain surface output nodes" });
+    });
+});
+export function materialCompositionOperations(options) {
+    return [...new Set([...options.fields.flatMap(field => field.graph.nodes.map(node => node.op)), "Constant", "Math", "MathLerp", "OutputMaterial",
+            ...(options.relief ? options.relief.mode === "height" ? ["OutputHeight"] : ["Bump", "OutputSurfaceNormal"] : [])])];
+}
+export function makeMaterialComposition(options, catalogue) {
+    const graph = { nodes: [], connections: [] };
+    const sources = options.fields.map((field, index) => {
+        const offset = graph.nodes.length;
+        const output = catalogue.nodes[field.graph.nodes[field.source.node].op]?.outputs[field.source.slot];
+        if (!output || !["Float", "Float3", "Color"].includes(output.type))
+            throw new Error("Field requires a numeric output port");
+        graph.nodes.push(...field.graph.nodes.map(node => {
+            const copy = { ...structuredClone(node), name: `field.${index}.${node.name ?? node.op}` };
+            // Composition creates independent controls; the host allocates their handles.
+            if (copy.op === "Constant")
+                delete copy.reference_id;
+            return copy;
+        }));
+        graph.connections.push(...field.graph.connections.map(edge => ({ ...edge, input_node: edge.input_node + offset, output_node: edge.output_node + offset })));
+        return { node: field.source.node + offset, slot: field.source.slot };
+    });
+    const selector = (op, slot, label) => {
+        const index = catalogue.nodes[op]?.inputs[slot]?.values?.indexOf(label) ?? -1;
+        if (index < 0)
+            throw new Error(`${op} requires option ${label}`);
+        return index;
+    };
+    const add = (op, inputs, name) => {
+        graph.nodes.push(makeMaterialNode({ op, inputs, name }));
+        return { node: graph.nodes.length - 1, slot: 0 };
+    };
+    const wire = (source, target, port) => graph.connections.push({ input_node: source.node, input_slot: source.slot, output_node: target.node, output_slot: port, flags: 0 });
+    const constant = (value, name, isColor = false) => {
+        const exposed = isColor || ["roughness.low", "roughness.high", "metalness", "relief.scale"].includes(name);
+        const result = add("Constant", isColor ? { 2: value, 3: selector("Constant", 3, "Expose Color") } : { 1: value, 3: selector("Constant", 3, exposed ? "Expose X" : "Do not expose") }, name);
+        return { ...result, slot: isColor ? 2 : 1 };
+    };
+    const combine = (values, name) => {
+        let sum;
+        values.forEach((value, index) => {
+            if (value === 0)
+                return;
+            const weight = constant(value, `${name}.weight.${index}`);
+            const product = add("Math", { 0: selector("Math", 0, "Mulitiply"), 3: 0 }, `${name} contribution`);
+            wire(sources[index], product, 1);
+            wire(weight, product, 2);
+            if (!sum) {
+                sum = product;
+                return;
+            }
+            const combined = add("Math", { 0: selector("Math", 0, "Add"), 3: 0 }, `${name} superposition`);
+            wire(sum, combined, 1);
+            wire(product, combined, 2);
+            sum = combined;
+        });
+        return sum;
+    };
+    const output = add("OutputMaterial", {}, "Composed surface");
+    for (const channel of ["color", "roughness"]) {
+        const settings = options[channel];
+        if (!settings)
+            continue;
+        const field = combine(settings.weights, channel);
+        if (!field)
+            continue;
+        const palette = add("MathLerp", {}, `${channel} range`);
+        wire(constant(settings.low, `${channel}.low`, channel === "color"), palette, 0);
+        wire(constant(settings.high, `${channel}.high`, channel === "color"), palette, 1);
+        wire(field, palette, 2);
+        wire(palette, output, channel === "color" ? 0 : 4);
+    }
+    if (options.metalness !== undefined)
+        wire(constant(options.metalness, "metalness"), output, 3);
+    if (options.relief) {
+        let field = combine(options.relief.weights, "relief");
+        if (field) {
+            if (options.relief.center !== undefined) {
+                const centered = add("Math", { 0: selector("Math", 0, "Subtract"), 3: 0 }, "Centered height");
+                wire(field, centered, 1);
+                wire(constant(options.relief.center, "relief.center"), centered, 2);
+                field = centered;
+            }
+            const strength = constant(options.relief.scale, "relief.scale");
+            if (options.relief.mode === "height") {
+                const height = add("OutputHeight", {}, "Combined height");
+                wire(field, height, 0);
+                wire(strength, height, 2);
+            }
+            else {
+                const bump = add("Bump", {}, "Combined bump");
+                wire(field, bump, 0);
+                wire(strength, bump, 1);
+                wire(bump, add("OutputSurfaceNormal", {}, "Composed normal"), 0);
+            }
+        }
+    }
+    return pruneMaterialGraph(validateMaterialGraph(graph, catalogue.nodes));
+}

package/dist/materials/graph.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import type { MaterialGraph, MaterialNode, MaterialNodeDescription, MaterialNodeOptions, MaterialVector } from "./types.js";
+export declare const materialId: z.ZodNumber;
+export declare const graphSchema: 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>>>>;
+export declare const catalogOptionsSchema: z.ZodObject<{
+    refreshTextures: z.ZodOptional<z.ZodBoolean>;
+    includeTextures: z.ZodOptional<z.ZodBoolean>;
+    operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const writeSchema: z.ZodObject<{
+    materialId: z.ZodOptional<z.ZodNumber>;
+    cloneFrom: z.ZodOptional<z.ZodNumber>;
+    layers: z.ZodOptional<z.ZodArray<z.ZodNullable<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>>>>>>>;
+    constants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+        value: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>;
+        color: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>>;
+    objectIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strict>;
+export declare const value3: (value: number) => MaterialVector;
+export declare function makeMaterialNode(options: MaterialNodeOptions): MaterialNode;
+export declare function parseMaterialCatalog(value: unknown): Record<string, MaterialNodeDescription>;
+export declare function validateMaterialGraph(input: MaterialGraph, catalog: Record<string, MaterialNodeDescription>): MaterialGraph;
+/** Drop nodes that cannot contribute to any surface output after validating the graph. */
+export declare function pruneMaterialGraph(graph: MaterialGraph): MaterialGraph;

package/dist/materials/graph.js

@@ -0,0 +1,336 @@
+import { z } from "zod";
+const finite = z
+    .number()
+    .refine(Number.isFinite, "Expected a finite number")
+    .refine((v) => Math.abs(v) <= 3.4028234663852886e38, "Exceeds float32 range");
+export const materialId = z.number().int().min(1).max(65535);
+const referenceId = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER);
+const vector = z.object({ x: finite, y: finite, z: finite }).strict();
+const index = z.number().int().nonnegative();
+const json = z.lazy(() => z.union([
+    z.null(),
+    z.boolean(),
+    finite,
+    z.string(),
+    z.array(json),
+    z.record(z.string(), json),
+]));
+const node = z
+    .object({
+    op: z.string().min(1),
+    name: z.string().optional(),
+    location: z.object({ x: finite, y: finite }).strict().optional(),
+    editor_flags: z.number().int().min(0).max(4294967295).optional(),
+    reference_id: z
+        .number()
+        .int()
+        .min(0)
+        .max(Number.MAX_SAFE_INTEGER)
+        .optional(),
+    out: vector.optional(),
+})
+    .catchall(json);
+const connection = z
+    .object({
+    input_node: index,
+    input_slot: index.max(19),
+    output_node: index,
+    output_slot: index.max(19),
+    flags: z.union([z.literal(0), z.literal(2)]).optional(),
+})
+    .strict();
+export const graphSchema = z
+    .object({ nodes: z.array(node).min(1), connections: z.array(connection) })
+    .catchall(json);
+export const catalogOptionsSchema = z
+    .object({
+    refreshTextures: z.boolean().optional(),
+    includeTextures: z.boolean().optional(),
+    operations: z.array(z.string()).optional(),
+})
+    .strict();
+export const writeSchema = z
+    .object({
+    materialId: materialId.optional(),
+    cloneFrom: materialId.optional(),
+    layers: z.array(graphSchema.nullable()).max(8).optional(),
+    constants: z
+        .record(z.string().regex(/^[1-9]\d*$/), z.object({ value: vector, color: vector }).strict().nullable())
+        .optional(),
+    objectIds: z.array(index).optional(),
+})
+    .strict()
+    .refine((v) => v.materialId === undefined || v.cloneFrom === undefined, "Use materialId or cloneFrom, not both");
+const nodeOptions = z
+    .object({
+    op: z.string().min(1),
+    name: z.string().optional(),
+    reference_id: referenceId.optional(),
+    inputs: z
+        .record(z.string().regex(/^(0|[1-9]|1[0-9])$/), z.union([finite, vector]))
+        .optional(),
+    texture: z
+        .string()
+        .min(1)
+        .refine((v) => !v.includes("\0"), "Texture names cannot contain NUL")
+        .optional(),
+    ramp: z
+        .array(z.object({ position: finite, color: vector }).strict())
+        .min(2)
+        .optional(),
+    options: z
+        .array(z.object({ name: z.string(), value: finite }).strict())
+        .min(1)
+        .max(32)
+        .optional(),
+})
+    .strict();
+export const value3 = (value) => ({
+    x: value,
+    y: value,
+    z: value,
+});
+const readVector = (node, slot) => vector.parse(node[`in${slot}`] ?? value3(0));
+export function makeMaterialNode(options) {
+    const spec = nodeOptions.parse(options);
+    const result = { op: spec.op };
+    if (spec.name !== undefined)
+        result.name = spec.name;
+    if (spec.reference_id !== undefined)
+        result.reference_id = spec.reference_id;
+    for (const [slot, input] of Object.entries(spec.inputs ?? {}))
+        result[`in${slot}`] = typeof input === "number" ? value3(input) : input;
+    const payloads = [spec.texture, spec.ramp, spec.options].filter((v) => v !== undefined);
+    if (payloads.length > 1)
+        throw new Error("A node accepts only one payload");
+    if (spec.texture !== undefined) {
+        if (!["Texture", "PredefinedTexture"].includes(spec.op))
+            throw new Error("Texture payload requires a texture node");
+        result.external_data = [...new TextEncoder().encode(spec.texture), 0];
+    }
+    if (spec.ramp) {
+        if (spec.op !== "ColorRamp")
+            throw new Error("Ramp payload requires ColorRamp");
+        const bytes = new Uint8Array(spec.ramp.length * 16);
+        const view = new DataView(bytes.buffer);
+        spec.ramp.forEach(({ position, color }, i) => [position, color.x, color.y, color.z].forEach((v, j) => view.setFloat32(i * 16 + j * 4, v, true)));
+        result.external_data = Array.from(bytes);
+        result.in1 = value3(spec.ramp.length);
+    }
+    if (spec.options) {
+        if (spec.op !== "OptionSelector")
+            throw new Error("Options payload requires OptionSelector");
+        const bytes = new Uint8Array(spec.options.length * 36);
+        const view = new DataView(bytes.buffer);
+        spec.options.forEach(({ name, value }, i) => {
+            const text = new TextEncoder().encode(name);
+            if (text.length > 31 || name.includes("\0"))
+                throw new Error("Option names must fit 31 UTF-8 bytes without NUL");
+            view.setFloat32(i * 36, value, true);
+            bytes.set(text, i * 36 + 4);
+        });
+        result.external_data = Array.from(bytes);
+        result.in0 = value3(spec.options.length);
+    }
+    return result;
+}
+const port = z.object({
+    title: z.string(),
+    type: z.string(),
+    values: z.array(z.string()).optional(),
+});
+const description = z.object({
+    type: z.string(),
+    title: z.string(),
+    description: z.string(),
+    inputs: z.array(port).max(20),
+    outputs: z.array(port).max(20),
+});
+export function parseMaterialCatalog(value) {
+    const parsed = z
+        .record(z.string(), description)
+        .parse(typeof value === "string" ? JSON.parse(value) : value);
+    if (!parsed.OutputMaterial)
+        throw new Error("Kakapo returned no procedural material catalogue");
+    return parsed;
+}
+/** Fields omitted by the runtime catalogue, verified against native registrations. */
+function hidden(op, slot) {
+    return ((["Texture", "PredefinedTexture"].includes(op) && slot === 1) ||
+        (op === "OutputHeight" && slot === 1));
+}
+function payloadBytes(node) {
+    return Uint8Array.from(z.array(z.number().int().min(0).max(255)).parse(node.external_data ?? []));
+}
+function checkPayload(node, textures) {
+    const bytes = payloadBytes(node);
+    const view = new DataView(bytes.buffer);
+    const fail = (message) => {
+        throw new Error(`${node.op}: ${message}`);
+    };
+    const length = (count, stride) => {
+        if (!Number.isInteger(count) || count < 1 || count * stride > bytes.length)
+            fail("invalid payload count/size");
+        if (bytes.slice(count * stride).some((v) => v !== 0))
+            fail("unexpected trailing payload data");
+        node.external_data = Array.from(bytes.slice(0, count * stride));
+    };
+    if (node.op === "ColorRamp") {
+        const count = readVector(node, 1).x;
+        length(count, 16);
+        if (count < 2)
+            fail("at least two ramp stops are required");
+        let previous = -Infinity;
+        for (let i = 0; i < count; i++) {
+            const values = Array.from({ length: 4 }, (_, j) => view.getFloat32(i * 16 + j * 4, true));
+            values.forEach((v) => finite.parse(v));
+            if (values[0] <= previous || values[0] < 0 || values[0] > 1)
+                fail("ramp positions must increase within 0..1");
+            previous = values[0];
+        }
+    }
+    else if (node.op === "OptionSelector") {
+        const count = readVector(node, 0).x;
+        length(count, 36);
+        if (count > 32)
+            fail("at most 32 options are supported");
+        for (let i = 0; i < count; i++) {
+            finite.parse(view.getFloat32(i * 36, true));
+            if (!bytes.slice(i * 36 + 4, i * 36 + 36).includes(0))
+                fail("option name is not NUL terminated");
+        }
+        const selected = readVector(node, 1).x;
+        if (!Number.isInteger(selected) || selected < 0 || selected >= count)
+            fail("selected index is outside the options");
+    }
+    else if (["Texture", "PredefinedTexture"].includes(node.op)) {
+        const end = bytes.indexOf(0);
+        if (end <= 0 || bytes.slice(end).some((v) => v !== 0))
+            fail("expected a NUL-terminated texture resource name");
+        const name = new TextDecoder("utf-8", { fatal: true }).decode(bytes.slice(0, end));
+        if (!textures.includes(name))
+            fail(`texture ${JSON.stringify(name)} is not in the refreshed resource catalogue`);
+        node.external_data = Array.from(bytes.slice(0, end + 1));
+        node.in1 = value3(0); // Renderer owns the GPU slot and dimensions.
+        if (node.op === "PredefinedTexture")
+            node.in2 = value3(textures.indexOf(name));
+    }
+    else if (bytes.length > 0) {
+        fail("this node's binary payload is not supported for editing");
+    }
+}
+export function validateMaterialGraph(input, catalog) {
+    const graph = graphSchema.parse(input);
+    const textures = catalog.PredefinedTexture?.inputs[2]?.values ?? [];
+    const descriptors = graph.nodes.map((node) => {
+        node.location ??= { x: 0, y: 0 };
+        const desc = catalog[node.op];
+        if (!desc || desc.type === "UNDEFINED" || node.op === "Noop")
+            throw new Error(`Unknown/unsupported material operation: ${node.op}`);
+        if (node.reference_id !== undefined && node.reference_id !== 0)
+            referenceId.parse(node.reference_id);
+        for (const key of Object.keys(node)) {
+            if (key.startsWith("in") && /^in\d+$/.test(key)) {
+                const slot = Number(key.slice(2));
+                if (slot >= 20)
+                    throw new Error(`${node.op}: invalid input ${slot}`);
+                vector.parse(node[key]);
+                if ((!desc.inputs[slot] || desc.inputs[slot].type === "Disabled") &&
+                    Object.values(readVector(node, slot)).some((v) => v !== 0))
+                    throw new Error(`${node.op}: input ${slot} is disabled`);
+            }
+        }
+        checkPayload(node, textures);
+        desc.inputs.forEach((port, slot) => {
+            const x = readVector(node, slot).x;
+            if (port.type === "Enum" &&
+                (!Number.isInteger(x) || x < 0 || x >= (port.values?.length ?? 0)))
+                throw new Error(`${node.op}: enum input ${slot} is out of range`);
+            if (port.type === "Integer" && !Number.isInteger(x))
+                throw new Error(`${node.op}: input ${slot} requires an integer`);
+            if (port.type === "Boolean" && x !== 0 && x !== 1)
+                throw new Error(`${node.op}: input ${slot} requires 0 or 1`);
+        });
+        if (["Noise1D", "Noise3D", "NoiseFBM"].includes(node.op)) {
+            const detail = readVector(node, 2).x;
+            if (detail < 1 || detail > 16)
+                throw new Error(`${node.op}: detail must be within 1..16`);
+        }
+        return desc;
+    });
+    const incoming = new Set();
+    const adjacency = graph.nodes.map(() => []);
+    const degree = graph.nodes.map(() => 0);
+    graph.connections.forEach((edge) => {
+        const source = descriptors[edge.input_node];
+        const target = descriptors[edge.output_node];
+        const output = source?.outputs[edge.input_slot];
+        const inputPort = target?.inputs[edge.output_slot];
+        if (!source ||
+            !target ||
+            !output ||
+            !inputPort ||
+            graph.nodes[edge.input_node].op.startsWith("Output") ||
+            !["Float", "Float3", "Color"].includes(output.type) ||
+            !["Float", "Float3", "Color"].includes(inputPort.type))
+            throw new Error("Invalid connection: use existing numeric ports; output nodes are terminal and selectors are literals");
+        const node = graph.nodes[edge.output_node];
+        if (hidden(node.op, edge.output_slot) ||
+            (node.op === "OptionSelector" && edge.output_slot === 1))
+            throw new Error("This input cannot be connected safely on this Kakapo build");
+        const key = `${edge.output_node}:${edge.output_slot}`;
+        if (incoming.has(key))
+            throw new Error("A material input has more than one source");
+        incoming.add(key);
+        adjacency[edge.input_node].push(edge.output_node);
+        degree[edge.output_node]++;
+    });
+    const queue = degree.flatMap((n, i) => (n === 0 ? [i] : []));
+    for (let cursor = 0; cursor < queue.length; cursor++)
+        for (const next of adjacency[queue[cursor]])
+            if (--degree[next] === 0)
+                queue.push(next);
+    if (queue.length !== graph.nodes.length)
+        throw new Error("Material graph contains a cycle");
+    if (!graph.nodes.some((node) => node.op.startsWith("Output")))
+        throw new Error("Material graph needs an output node");
+    for (const op of graph.nodes
+        .filter((node) => node.op.startsWith("Output"))
+        .map((node) => node.op))
+        if (graph.nodes.filter((n) => n.op === op).length > 1)
+            throw new Error(`Only one ${op} per layer is supported`);
+    graph.nodes.forEach((node, i) => {
+        if (node.op === "OutputMaterial")
+            for (let s = 0; s < descriptors[i].inputs.length; s++)
+                if (!incoming.has(`${i}:${s}`) &&
+                    Object.values(readVector(node, s)).some((v) => v !== 0))
+                    throw new Error("Unconnected OutputMaterial literals are ignored by Kakapo; connect a Constant/Passthrough node instead");
+    });
+    return graph;
+}
+/** Drop nodes that cannot contribute to any surface output after validating the graph. */
+export function pruneMaterialGraph(graph) {
+    const needed = new Set();
+    const incoming = new Map();
+    for (const edge of graph.connections) {
+        const sources = incoming.get(edge.output_node) ?? [];
+        sources.push(edge.input_node);
+        incoming.set(edge.output_node, sources);
+    }
+    const queue = graph.nodes.flatMap((node, index) => node.op.startsWith("Output") ? [index] : []);
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const node = queue[cursor];
+        if (needed.has(node))
+            continue;
+        needed.add(node);
+        queue.push(...(incoming.get(node) ?? []));
+    }
+    const indices = new Map();
+    const nodes = graph.nodes.filter((_, index) => {
+        if (!needed.has(index))
+            return false;
+        indices.set(index, indices.size);
+        return true;
+    });
+    return { ...graph, nodes, connections: graph.connections.filter(edge => needed.has(edge.output_node)).map(edge => ({ ...edge, input_node: indices.get(edge.input_node), output_node: indices.get(edge.output_node) })) };
+}

package/dist/materials/inspection.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { type SceneHost, type SceneScreenshotOptions } from "../capabilities/scene.js";
+import type { ArtifactRef, SparkInvocationContext } from "../capabilities.js";
+import type { MaterialsHost, MaterialStatus } from "../capabilities/materials.js";
+export type MaterialInspectionOptions = {
+    views: SceneScreenshotOptions[];
+    /** Maximum compilation/resource wait, milliseconds. Defaults to 60 seconds. */
+    timeoutMs?: number;
+};
+export type MaterialInspectionResult = {
+    frames: ArtifactRef[];
+    queueSettled: boolean;
+    timedOut: boolean;
+    status: MaterialStatus;
+};
+export type MaterialInspectionHost = Pick<SceneHost, "screenshot">;
+export declare const materialInspectionSchema: z.ZodObject<{
+    views: z.ZodArray<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>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare function inspectMaterial(host: MaterialsHost, captures: MaterialInspectionHost, options: MaterialInspectionOptions, context: SparkInvocationContext): Promise<MaterialInspectionResult>;

package/dist/materials/inspection.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { screenshotOptions } from "../capabilities/scene.js";
+export const materialInspectionSchema = z.object({ views: z.array(screenshotOptions).min(1), timeoutMs: z.number().int().positive().max(300000).optional() }).strict();
+export async function inspectMaterial(host, captures, options, context) {
+    const action = async () => {
+        const frames = [];
+        const deadline = performance.now() + (options.timeoutMs ?? 60000);
+        const settled = (status) => status.remaining === 0 && status.pendingResources !== null && Object.values(status.pendingResources).every(names => names.length === 0) && !status.errors?.length;
+        const observe = async () => { context.signal.throwIfAborted(); const status = await host.status(context); context.signal.throwIfAborted(); return status; };
+        const wait = async (initial) => {
+            let status = initial;
+            while (!settled(status) && status.remaining !== null && status.pendingResources !== null && !status.errors?.length && performance.now() < deadline) {
+                await new Promise((resolve, reject) => {
+                    const abort = () => { clearTimeout(timer); reject(context.signal.reason); };
+                    const timer = setTimeout(() => { context.signal.removeEventListener("abort", abort); resolve(); }, Math.min(200, Math.max(0, deadline - performance.now())));
+                    context.signal.addEventListener("abort", abort, { once: true });
+                    if (context.signal.aborted) {
+                        context.signal.removeEventListener("abort", abort);
+                        abort();
+                    }
+                });
+                status = await observe();
+            }
+            return status;
+        };
+        const result = (status) => ({ frames, status, queueSettled: settled(status), timedOut: !settled(status) && performance.now() >= deadline });
+        context.signal.throwIfAborted();
+        // A first frame registers shaders even when the queue was initially empty.
+        await captures.screenshot(options.views[0], context);
+        let status = await wait(await observe());
+        if (!settled(status))
+            return result(status);
+        for (const view of options.views) {
+            context.signal.throwIfAborted();
+            let frame = await captures.screenshot(view, context);
+            const next = await observe();
+            // Another angle can expose previously hidden shaders; settle and recapture it.
+            if (!settled(next)) {
+                status = await wait(next);
+                if (!settled(status))
+                    return result(status);
+                frame = await captures.screenshot(view, context);
+                status = await observe();
+                if (!settled(status))
+                    return result(status);
+            }
+            else
+                status = next;
+            frames.push(frame);
+        }
+        return result(status);
+    };
+    return context.waitForService ? context.waitForService("Inspecting material views", action) : action();
+}