@womp/spark-agent 5.2.2 → 5.3.0

package/dist/materials/shaping.d.ts

@@ -0,0 +1,294 @@
+import { z } from "zod";
+import type { MaterialCatalog, MaterialField, MaterialShapeOptions } from "./types.js";
+type MaterialShapeRequest = MaterialShapeOptions & {
+    field: MaterialField;
+};
+export declare const materialShapeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"remap">;
+    low: z.ZodNumber;
+    high: z.ZodNumber;
+    field: 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>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"ridge">;
+    center: z.ZodNumber;
+    width: z.ZodNumber;
+    field: 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>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"periodic">;
+    coordinates: z.ZodOptional<z.ZodNumber>;
+    axis: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<2>]>;
+    sharpness: z.ZodNumber;
+    field: 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>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"warp">;
+    coordinates: z.ZodOptional<z.ZodNumber>;
+    frequency: z.ZodNumber;
+    amplitude: z.ZodNumber;
+    field: 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>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"palette">;
+    mode: z.ZodEnum<{
+        Constant: "Constant";
+        Linear: "Linear";
+        Smooth: "Smooth";
+    }>;
+    stops: z.ZodArray<z.ZodObject<{
+        position: z.ZodNumber;
+        color: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    field: 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>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"blend">;
+    overlay: z.ZodUnion<readonly [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>, z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>]>;
+    mask: z.ZodUnion<readonly [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>, z.ZodNumber]>;
+    field: 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>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "kind">;
+export declare function materialShapeOperations(options: MaterialShapeRequest): string[];
+export declare function makeMaterialShape(options: MaterialShapeRequest, catalogue: MaterialCatalog): MaterialField;
+export {};

package/dist/materials/shaping.js

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { graphSchema, makeMaterialNode, pruneMaterialGraph, validateMaterialGraph } from "./graph.js";
+const number = z.number().finite();
+const coordinate = z.number().int().nonnegative().optional();
+const field = z.object({ graph: graphSchema, source: z.object({ node: z.number().int().nonnegative(), slot: z.number().int().min(0).max(19) }).strict() }).strict();
+const color = z.object({ x: number.min(0).max(1), y: number.min(0).max(1), z: number.min(0).max(1) }).strict();
+const base = { field, name: z.string().min(1).optional() };
+export const materialShapeSchema = z.discriminatedUnion("kind", [
+    z.object({ ...base, kind: z.literal("remap"), low: number, high: number }).strict(),
+    z.object({ ...base, kind: z.literal("ridge"), center: number, width: number.positive() }).strict(),
+    z.object({ ...base, kind: z.literal("periodic"), coordinates: coordinate, axis: z.union([z.literal(0), z.literal(1), z.literal(2)]), sharpness: number.positive() }).strict(),
+    z.object({ ...base, kind: z.literal("warp"), coordinates: coordinate, frequency: number.positive(), amplitude: number }).strict(),
+    z.object({ ...base, kind: z.literal("palette"), mode: z.enum(["Constant", "Linear", "Smooth"]), stops: z.array(z.object({ position: number.min(0).max(1), color: z.object({ x: number.min(0).max(1), y: number.min(0).max(1), z: number.min(0).max(1) }).strict() }).strict()).min(2) }).strict(),
+    z.object({ ...base, kind: z.literal("blend"), overlay: z.union([field, color]), mask: z.union([field, number.min(0).max(1)]) }).strict(),
+]).superRefine((options, context) => {
+    if (options.kind === "remap" && options.low === options.high)
+        context.addIssue({ code: "custom", message: "Mask endpoints must differ" });
+    const fields = [options.field, ...(options.kind === "blend" ? [...("graph" in options.overlay ? [options.overlay] : []), ...(typeof options.mask === "object" ? [options.mask] : [])] : [])];
+    for (const field of fields) {
+        if (!field.graph.nodes[field.source.node])
+            context.addIssue({ code: "custom", message: "Field output node does not exist" });
+        if (field.graph.nodes.some(node => node.op.startsWith("Output")))
+            context.addIssue({ code: "custom", message: "Fields must not contain surface output nodes" });
+    }
+});
+export function materialShapeOperations(options) {
+    const fields = [options.field, ...(options.kind === "blend" ? [...("graph" in options.overlay ? [options.overlay] : []), ...(typeof options.mask === "object" ? [options.mask] : [])] : [])];
+    return [...new Set([...fields.flatMap(field => field.graph.nodes.map(node => node.op)), "OutputMaterial", "Constant", "Math", "GetComponent",
+            ...(options.kind === "blend" ? ["MathLerp"] : []),
+            ...(options.kind === "palette" ? ["ColorRamp"] : []),
+            ...(options.kind === "periodic" ? ["GetComponent", "MathLerp"] : []),
+            ...(options.kind === "warp" ? ["Mapping", "NoiseFBM"] : []),
+        ])];
+}
+export function makeMaterialShape(options, catalogue) {
+    const graph = structuredClone(options.field.graph);
+    const inputOutput = catalogue.nodes[graph.nodes[options.field.source.node].op]?.outputs[options.field.source.slot];
+    if (!inputOutput || !["Float", "Float3", "Color"].includes(inputOutput.type))
+        throw new Error("Field requires a numeric output port");
+    const label = options.name ?? options.kind + "." + graph.nodes.length;
+    const selector = (op, slot, value) => {
+        const index = catalogue.nodes[op]?.inputs[slot]?.values?.indexOf(value) ?? -1;
+        if (index < 0)
+            throw new Error(op + " requires option " + value);
+        return index;
+    };
+    const add = (op, inputs, name) => {
+        graph.nodes.push(makeMaterialNode({ op, inputs, name: label + "." + 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 math = (operation, inputs, name) => add("Math", { 0: selector("Math", 0, operation), 3: 0, ...inputs }, name);
+    const control = (value, name) => {
+        const constant = { ...add("Constant", { 1: value, 3: selector("Constant", 3, "Expose X") }, name), slot: 1 };
+        const scalar = add("GetComponent", { 1: 0 }, `${name}.scalar`);
+        wire(constant, scalar, 0);
+        return scalar;
+    };
+    const coordinateSource = () => {
+        const index = "coordinates" in options && options.coordinates !== undefined ? options.coordinates : graph.nodes.findIndex(node => node.name === "Feature size in selected coordinates");
+        const output = catalogue.nodes[graph.nodes[index]?.op ?? ""]?.outputs[0];
+        if (!output || !["Float3", "Color"].includes(output.type))
+            throw new Error("Select an existing vector coordinate node; custom fields require coordinates");
+        return { node: index, slot: 0 };
+    };
+    let source = options.field.source;
+    if (options.kind === "remap" || options.kind === "ridge") {
+        const center = control(options.kind === "remap" ? options.low : options.center, "center");
+        const shifted = math("Subtract", {}, "offset");
+        wire(source, shifted, 1);
+        wire(center, shifted, 2);
+        let distance = shifted;
+        if (options.kind === "ridge") {
+            distance = math("Absolute Value", {}, "distance");
+            wire(shifted, distance, 1);
+        }
+        const scaled = math("Divide", { 3: 1 }, "normalized");
+        wire(distance, scaled, 1);
+        if (options.kind === "ridge")
+            wire(control(options.width, "width"), scaled, 2);
+        else {
+            const width = math("Subtract", {}, "range");
+            wire(control(options.high, "high"), width, 1);
+            wire(center, width, 2);
+            wire(width, scaled, 2);
+        }
+        source = scaled;
+        if (options.kind === "ridge") {
+            source = math("Subtract", { 1: 1, 3: 1 }, "ridge");
+            wire(scaled, source, 2);
+        }
+    }
+    else if (options.kind === "periodic") {
+        const coordinates = coordinateSource();
+        const component = add("GetComponent", { 1: options.axis }, "axis");
+        wire(coordinates, component, 0);
+        const phase = math("Mulitiply", { 2: 2 * Math.PI }, "phase");
+        wire(component, phase, 1);
+        const sine = math("Sine", {}, "sine");
+        wire(phase, sine, 1);
+        const positive = add("MathLerp", { 0: 0.5, 1: 1 }, "positive");
+        wire(sine, positive, 2);
+        source = math("Power", { 3: 1 }, "profile");
+        wire(positive, source, 1);
+        wire(control(options.sharpness, "sharpness"), source, 2);
+    }
+    else if (options.kind === "warp") {
+        const coordinates = coordinateSource();
+        const consumers = graph.connections.filter(edge => edge.input_node === coordinates.node && edge.input_slot === coordinates.slot);
+        const frequency = control(options.frequency, "frequency"), amplitude = control(options.amplitude, "amplitude");
+        const components = [0, 1, 2].map(axis => {
+            const shifted = add("Mapping", { 1: { x: 17 * (axis + 1), y: 31 * (axis + 1), z: 47 * (axis + 1) }, 2: 0, 3: 1 }, "seed");
+            wire(coordinates, shifted, 0);
+            const noise = add("NoiseFBM", { 2: 3, 3: 1, 4: 0 }, "variation");
+            wire(shifted, noise, 0);
+            wire(frequency, noise, 1);
+            const centered = math("Subtract", { 2: 0.5 }, "centered");
+            wire(noise, centered, 1);
+            const scaled = math("Mulitiply", {}, "strength");
+            wire(centered, scaled, 1);
+            wire(amplitude, scaled, 2);
+            const basis = { x: axis === 0 ? 1 : 0, y: axis === 1 ? 1 : 0, z: axis === 2 ? 1 : 0 };
+            const component = math("Mulitiply", { 2: basis }, "component");
+            wire(scaled, component, 1);
+            return component;
+        });
+        const xy = math("Add", {}, "xy");
+        wire(components[0], xy, 1);
+        wire(components[1], xy, 2);
+        const xyz = math("Add", {}, "xyz");
+        wire(xy, xyz, 1);
+        wire(components[2], xyz, 2);
+        const warped = add("Mapping", { 2: 0, 3: 1 }, "coordinates");
+        wire(coordinates, warped, 0);
+        wire(xyz, warped, 1);
+        consumers.forEach(edge => { edge.input_node = warped.node; edge.input_slot = 0; });
+        if (source.node === coordinates.node && source.slot === coordinates.slot)
+            source = warped;
+    }
+    else if (options.kind === "palette") {
+        const palette = graph.nodes.length;
+        graph.nodes.push(makeMaterialNode({ op: "ColorRamp", name: label + ".palette", inputs: { 3: selector("ColorRamp", 3, options.mode) }, ramp: options.stops }));
+        const output = { node: palette, slot: 0 };
+        wire(source, output, 0);
+        source = output;
+    }
+    else {
+        // Each branch owns independent controls, even when the same source is reused.
+        graph.nodes.forEach(node => { if (node.op === "Constant")
+            delete node.reference_id; });
+        const append = (field, branch) => {
+            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");
+            const offset = graph.nodes.length;
+            graph.nodes.push(...structuredClone(field.graph.nodes).map(node => {
+                if (node.op === "Constant")
+                    delete node.reference_id;
+                node.name = label + "." + branch + "." + (node.name ?? node.op);
+                return node;
+            }));
+            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 overlay = "graph" in options.overlay ? append(options.overlay, "overlay") : { ...add("Constant", { 2: options.overlay, 3: selector("Constant", 3, "Expose Color") }, "color"), slot: 2 };
+        let mask = typeof options.mask === "number" ? control(options.mask, "amount") : append(options.mask, "mask");
+        const scalar = add("GetComponent", { 1: 0 }, "mask.scalar");
+        wire(mask, scalar, 0);
+        mask = math("Add", { 2: 0, 3: 1 }, "mask.clamped");
+        wire(scalar, mask, 1);
+        const blended = add("MathLerp", {}, "blend");
+        wire(source, blended, 0);
+        wire(overlay, blended, 1);
+        wire(mask, blended, 2);
+        source = blended;
+    }
+    // Validate terminal-free fields through a temporary output, then prune unused generators.
+    const output = add("OutputMaterial", {}, "validation");
+    wire(source, output, 0);
+    const validated = pruneMaterialGraph(validateMaterialGraph(graph, catalogue.nodes));
+    const terminal = validated.nodes.length - 1;
+    const edge = validated.connections.find(edge => edge.output_node === terminal);
+    return { graph: { ...validated, nodes: validated.nodes.slice(0, terminal), connections: validated.connections.filter(edge => edge.output_node !== terminal) }, source: { node: edge.input_node, slot: edge.input_slot } };
+}

package/dist/materials/structure.d.ts

@@ -0,0 +1,2 @@
+export declare const MATERIALS_STRUCTURE_GUIDANCE = "shape(field, options) constructs generic remap, ridge, periodic, warp, palette and masked-blend fields. Name features for later editing. Remap endpoints, ridge center/width, periodic sharpness and warp frequency/amplitude are exposed Constants; palette stops remain graph data. Remap/ridge/periodic use analytic math. For a smooth nonlinear scalar profile, use the palette shape with mode:'Smooth' and grayscale stops (equal RGB components); compose reads X for relief or masks. Use this when a simple remap or ridge cannot reproduce the intended shape.\nshape(base,{kind:'blend',overlay,mask,name}) layers an RGB/scalar field or linear RGB literal over the base using a field mask or numeric amount. Zero mask retains the base; one selects the overlay. Field masks use clamped X broadcast to RGB. This helper resolves MathLerp internally; literal overlay colors and amounts become editable Constants. Build independent palettes and masks, then chain blend calls for feature-specific colors in one construction batch.\nPeriodic and warp coordinates default to the field's feature-size Mapping. Custom fields require an explicit vector coordinate node. Warp frequency/amplitude are relative to those coordinates; preserve measured feature size. Build periodic profiles, warp their coordinates, then form ridges/masks. Resolve indices in each returned graph because unused nodes are pruned. Independent XYZ warp avoids diagonal distortion.\nA generic noise layer counts only when it reproduces the requested shape. Construct defining boundaries, strands and crossings explicitly. Palette vector fields preserve RGB with compose color low:{x:0,y:0,z:0}, high:{x:1,y:1,z:1}, weight 1; use separate scalar fields for finish/relief and combine heights before deriving normals once. Composed fields have independent Constant handles.\nFor custom graphs, node({inputs}) keys are numeric input-slot indices, never displayed port titles. Arithmetic uses op:'Math', with its operation selected by literal input 0; this engine's multiplication selector is 2 (label 'Mulitiply'). Check the current descriptor for other modes. Use exact catalogue operation names. When removing a graph node, remove and reindex its connections instead of leaving an unsupported placeholder.";
+export declare const MATERIALS_QUALITY_GUIDANCE = "Create materials with the highest achievable fidelity, quality and detail resolution supported by these capabilities.\nFor every new material: inspect target dimensions and ancestor transforms, then create and inspect an isolated base-color grid probe BEFORE building final surface structure. Use object-space featureSize:1: major lines every 1 unit and lower-contrast minor lines every 0.1 unit together, with visible line colors and shallow height relief. Assess spacing, stretch, orientation and relief on relevant faces. Correct unintended coordinate distortion without changing geometry or transforms. Replace the probe completely; preserve other material users and assignments. World-space field sizes are physical millimeters; object-space sizes follow carrier coordinates and transforms. Non-uniform dimensions and ancestor transforms affect mapping. Keep physical feature size consistent and all channels aligned; distinguish intended directional anatomy from smeared stretching.\nBefore construction, decompose the description/reference into broad variation, defining structure and fine grain. Record each component's relative scale, shape, direction, distribution, edge character and contrast, and its color/roughness/relief contributions. Apply text overrides while preserving remaining reference features. Distinguish reference illumination from intrinsic structure. Give microstructure independent scale and strength; superimpose components without dominant motifs obscuring it.\nBuild all planned components and finish channels together using field, shape and compose. Their supported operations and selectors are resolved internally; construct masks, palettes and blends directly from these helpers. For textured surfaces, apply the tested readability adjustment in the first construction: bump scale \u00D71.25, palette saturation \u00D71.15, palette lightness \u00D70.95 and scalar feature contrast \u00D71.15 around 0.5, clamped to 0..1. Apply color factors in the known display-color encoding, then decode back to linear RGB; native HSL inputs are additive offsets. Incorporate this once into chosen base controls, without an extra material/render pass or compounding it during refinement. Explicit flat, muted or pale requests take precedence; retain reference hues, defining features and the requested finish. These factors are a starting adjustment, not universal optimum values. Keep defining height and fine-noise height independently weighted; increasing all bump together can erase coherent highlights and change gloss into a matte finish. Relief responds to height slope: finer spacing, sharper edges and more noise octaves can strengthen normals at unchanged scale. Calibrated ranges describe particular fields, not quality ceilings or universal strengths.\nAdjust palette saturation/lightness separately from feature coverage and edge contrast; use bounded scalar remaps before palettes or masked blends, checking clipped colors and changed coverage. Keep intrinsic color separate from illumination; preserve natural low-saturation features and coherent highlights. Author linear RGB; decode reference/display colors and preserve already-linear colors and scalar channels. Use roughness variation for finish breakup and signed height profiles for actual ridges/cavities; a dark spot alone does not establish a pit.\nInspect complementary overall, close and grazing views together under the existing scene lighting, geometry and render settings; adjust viewpoints for inspection. Match tonal contrast and reflectivity through highlight width, strength and breakup. Confirm every planned feature remains visibly resolved: a fine-noise node does not prove fine grain. Check that defining relief reads through lighting at the intended viewing distance, rather than only through its color mask. Subpixel features cannot remain individually resolved by increasing strength or octaves. If relief destroys the requested sheen, rebalance the offending feature's height/frequency before compensating roughness.\nFor each refinement, name the largest visible mismatch and the expected correction. Wrong topology/shape needs construction changes; wrong spacing, color, roughness or relief needs the corresponding parameter changes. Use known construction inputs and returned control handles to apply the correction in that batch. Read graphs when editing a previously unknown material or recovering unavailable/stale handles. Adjust related controls together and inspect once. Compare each candidate with the best inspected version at the same views; restore the better graph if a change weakens a defining feature. If tuning fails to improve a mismatch, change its construction rather than repeating strength changes. Continue while a specific, supported correction is likely to improve a substantial mismatch; stop when the result meets the request or further edits cease to help. Do not end with an uninspected edit. Print only relevant IDs, controls and observations; retain full graphs locally for edits.";

package/dist/materials/structure.js

@@ -0,0 +1,12 @@
+export const MATERIALS_STRUCTURE_GUIDANCE = `shape(field, options) constructs generic remap, ridge, periodic, warp, palette and masked-blend fields. Name features for later editing. Remap endpoints, ridge center/width, periodic sharpness and warp frequency/amplitude are exposed Constants; palette stops remain graph data. Remap/ridge/periodic use analytic math. For a smooth nonlinear scalar profile, use the palette shape with mode:'Smooth' and grayscale stops (equal RGB components); compose reads X for relief or masks. Use this when a simple remap or ridge cannot reproduce the intended shape.
+shape(base,{kind:'blend',overlay,mask,name}) layers an RGB/scalar field or linear RGB literal over the base using a field mask or numeric amount. Zero mask retains the base; one selects the overlay. Field masks use clamped X broadcast to RGB. This helper resolves MathLerp internally; literal overlay colors and amounts become editable Constants. Build independent palettes and masks, then chain blend calls for feature-specific colors in one construction batch.
+Periodic and warp coordinates default to the field's feature-size Mapping. Custom fields require an explicit vector coordinate node. Warp frequency/amplitude are relative to those coordinates; preserve measured feature size. Build periodic profiles, warp their coordinates, then form ridges/masks. Resolve indices in each returned graph because unused nodes are pruned. Independent XYZ warp avoids diagonal distortion.
+A generic noise layer counts only when it reproduces the requested shape. Construct defining boundaries, strands and crossings explicitly. Palette vector fields preserve RGB with compose color low:{x:0,y:0,z:0}, high:{x:1,y:1,z:1}, weight 1; use separate scalar fields for finish/relief and combine heights before deriving normals once. Composed fields have independent Constant handles.
+For custom graphs, node({inputs}) keys are numeric input-slot indices, never displayed port titles. Arithmetic uses op:'Math', with its operation selected by literal input 0; this engine's multiplication selector is 2 (label 'Mulitiply'). Check the current descriptor for other modes. Use exact catalogue operation names. When removing a graph node, remove and reindex its connections instead of leaving an unsupported placeholder.`;
+export const MATERIALS_QUALITY_GUIDANCE = `Create materials with the highest achievable fidelity, quality and detail resolution supported by these capabilities.
+For every new material: inspect target dimensions and ancestor transforms, then create and inspect an isolated base-color grid probe BEFORE building final surface structure. Use object-space featureSize:1: major lines every 1 unit and lower-contrast minor lines every 0.1 unit together, with visible line colors and shallow height relief. Assess spacing, stretch, orientation and relief on relevant faces. Correct unintended coordinate distortion without changing geometry or transforms. Replace the probe completely; preserve other material users and assignments. World-space field sizes are physical millimeters; object-space sizes follow carrier coordinates and transforms. Non-uniform dimensions and ancestor transforms affect mapping. Keep physical feature size consistent and all channels aligned; distinguish intended directional anatomy from smeared stretching.
+Before construction, decompose the description/reference into broad variation, defining structure and fine grain. Record each component's relative scale, shape, direction, distribution, edge character and contrast, and its color/roughness/relief contributions. Apply text overrides while preserving remaining reference features. Distinguish reference illumination from intrinsic structure. Give microstructure independent scale and strength; superimpose components without dominant motifs obscuring it.
+Build all planned components and finish channels together using field, shape and compose. Their supported operations and selectors are resolved internally; construct masks, palettes and blends directly from these helpers. For textured surfaces, apply the tested readability adjustment in the first construction: bump scale ×1.25, palette saturation ×1.15, palette lightness ×0.95 and scalar feature contrast ×1.15 around 0.5, clamped to 0..1. Apply color factors in the known display-color encoding, then decode back to linear RGB; native HSL inputs are additive offsets. Incorporate this once into chosen base controls, without an extra material/render pass or compounding it during refinement. Explicit flat, muted or pale requests take precedence; retain reference hues, defining features and the requested finish. These factors are a starting adjustment, not universal optimum values. Keep defining height and fine-noise height independently weighted; increasing all bump together can erase coherent highlights and change gloss into a matte finish. Relief responds to height slope: finer spacing, sharper edges and more noise octaves can strengthen normals at unchanged scale. Calibrated ranges describe particular fields, not quality ceilings or universal strengths.
+Adjust palette saturation/lightness separately from feature coverage and edge contrast; use bounded scalar remaps before palettes or masked blends, checking clipped colors and changed coverage. Keep intrinsic color separate from illumination; preserve natural low-saturation features and coherent highlights. Author linear RGB; decode reference/display colors and preserve already-linear colors and scalar channels. Use roughness variation for finish breakup and signed height profiles for actual ridges/cavities; a dark spot alone does not establish a pit.
+Inspect complementary overall, close and grazing views together under the existing scene lighting, geometry and render settings; adjust viewpoints for inspection. Match tonal contrast and reflectivity through highlight width, strength and breakup. Confirm every planned feature remains visibly resolved: a fine-noise node does not prove fine grain. Check that defining relief reads through lighting at the intended viewing distance, rather than only through its color mask. Subpixel features cannot remain individually resolved by increasing strength or octaves. If relief destroys the requested sheen, rebalance the offending feature's height/frequency before compensating roughness.
+For each refinement, name the largest visible mismatch and the expected correction. Wrong topology/shape needs construction changes; wrong spacing, color, roughness or relief needs the corresponding parameter changes. Use known construction inputs and returned control handles to apply the correction in that batch. Read graphs when editing a previously unknown material or recovering unavailable/stale handles. Adjust related controls together and inspect once. Compare each candidate with the best inspected version at the same views; restore the better graph if a change weakens a defining feature. If tuning fails to improve a mismatch, change its construction rather than repeating strength changes. Continue while a specific, supported correction is likely to improve a substantial mismatch; stop when the result meets the request or further edits cease to help. Do not end with an uninspected edit. Print only relevant IDs, controls and observations; retain full graphs locally for edits.`;

package/dist/materials/surface-recipes.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import type { MaterialCatalog, MaterialField, MaterialFieldOptions, MaterialGraph, MaterialRecipeOptions } from "./types.js";
+export declare const MATERIAL_RECIPE_RELIEF_GUIDANCE = "Pattern-specific calibration observations (native strength, object coordinates, detail 4, height and bump tested independently):\n- Dual-scale grid, featureSize 1: height 0.0003\u20130.001; start at 0.0003.\n- Noise, featureSize 0.04: 0.01\u20130.03 produced visible fine relief.\n- Crossed periodic threads, featureSize 0.04: 0.003\u20130.03 retained rounded thread shading.\n- Noise, featureSize 0.08: 0.01\u20130.03 produced low-amplitude grain.\n- Fine directional grain, featureSize {x:0.015,y:0.015,z:2}: 0.0003\u20130.003 produced faint directional relief; 0.01 and above produced stronger ridges.\nThese 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.";
+export declare const materialRecipeSchema: z.ZodObject<{
+    pattern: z.ZodEnum<{
+        noise: "noise";
+        grain: "grain";
+        woven: "woven";
+        grid: "grid";
+    }>;
+    coordinateSpace: z.ZodEnum<{
+        object: "object";
+        world: "world";
+    }>;
+    featureSize: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>]>;
+    colorA: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>;
+    colorB: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>;
+    roughnessA: z.ZodNumber;
+    roughnessB: z.ZodNumber;
+    metalness: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodNumber>;
+    relief: z.ZodEnum<{
+        height: "height";
+        bump: "bump";
+    }>;
+    reliefScale: z.ZodNumber;
+}, z.core.$strict>;
+export declare const materialFieldSchema: z.ZodObject<{
+    coordinateSpace: z.ZodEnum<{
+        object: "object";
+        world: "world";
+    }>;
+    featureSize: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>]>;
+    detail: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodEnum<{
+        noise: "noise";
+        grain: "grain";
+        woven: "woven";
+        grid: "grid";
+        cells: "cells";
+    }>;
+    rotation: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strict>>;
+    cellMode: z.ZodOptional<z.ZodEnum<{
+        Color: "Color";
+        Distance: "Distance";
+        "Edge distance": "Edge distance";
+        "Smooth Distance": "Smooth Distance";
+        "Smooth Color": "Smooth Color";
+    }>>;
+    remap: z.ZodOptional<z.ZodObject<{
+        low: z.ZodNumber;
+        high: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare function materialFieldOperations(options: MaterialFieldOptions): string[];
+export declare function materialRecipeOperations(options: MaterialRecipeOptions): string[];
+export declare function makeMaterialField(options: MaterialFieldOptions, catalogue: MaterialCatalog): MaterialField;
+export declare function makeMaterialRecipe(options: MaterialRecipeOptions, catalogue: MaterialCatalog): MaterialGraph;