@womp/spark-agent 4.1.2 → 4.2.1

package/dist/agent-tools.js

@@ -1,5 +1,6 @@
 import { tool } from "ai";
 import { z } from "zod";
+import { boundedResultText } from "./bounded-output.js";
 import { completedInputString } from "./tool-input-label.js";
 import { UserWait } from "./execution-lifetime.js";
 function errorMessage(error) {
@@ -246,9 +247,14 @@ export function createSparkTools(options) {
                         return { ...entry, artifact: { id, mediaType, ...(name ? { name } : {}) } };
                     }),
                 };
+                // `print` and a returned value are each already refused over 1 MiB; the
+                // rest of the envelope -- a rejected call's `error`, and the receipts --
+                // was not, and one unbounded compiler diagnostic cost a whole turn. Only
+                // model input is bounded: persistence and the UI stream keep the
+                // original (./bounded-output.ts).
                 return {
                     type: "content",
-                    value: [{ type: "text", text: JSON.stringify(modelOutput) }, ...images],
+                    value: [{ type: "text", text: boundedResultText(modelOutput) }, ...images],
                 };
             },
         }),

package/dist/bounded-output.d.ts

@@ -0,0 +1,37 @@
+export declare const MODEL_RESULT_BYTE_LIMIT: number;
+export declare const MODEL_ERROR_BYTE_LIMIT: number;
+export declare function byteLength(text: string): number;
+/**
+ * `text` cut to at most `limit` bytes on a character boundary. A cut that lands
+ * inside a multi-byte sequence decodes to a trailing replacement character,
+ * which is dropped.
+ */
+export declare function truncateUtf8(text: string, limit: number): string;
+/**
+ * `text` bounded to `limit` bytes with the omission stated in the same shape as
+ * the existing print budget message, so a model reading it knows the text is
+ * incomplete rather than wrong.
+ */
+export declare function boundedText(text: string, limit: number, label: string): string;
+/**
+ * The serialized tool result the model reads, bounded to
+ * `MODEL_RESULT_BYTE_LIMIT`. Persistence, the UI stream and the host's own
+ * receipts keep the full output; only model input is bounded here.
+ *
+ * Stages, in order, so the most useful part survives: bound `error`, then bound
+ * each receipt's `details`, then keep only as many receipts as the budget
+ * allows, and finally fall back to the envelope with a note in place of the
+ * logs. Every stage leaves valid JSON -- a truncated JSON document would cost
+ * the model more than the bytes it saves.
+ */
+export declare function boundedResultText<Output extends {
+    version: number;
+    ok: boolean;
+    purpose: string;
+    logs: string[];
+    receipts: {
+        id: string;
+        details?: Record<string, unknown>;
+    }[];
+    error?: string;
+}>(output: Output, limit?: number): string;

package/dist/bounded-output.js

@@ -0,0 +1,110 @@
+// Byte budgets for everything a tool call hands back to the model.
+//
+// WHY THIS FILE EXISTS. `execute_javascript` already refuses a printed payload
+// or a returned value over 1 MiB (agent-tools.ts `jsonValue` and `print`), but
+// nothing bounded the rest of the envelope: the `error` string and the receipts.
+// One rejected `geometry.write` over a one-character enum value produced a
+// compiler diagnostic that repeated the offending source line once per
+// diagnostic, and the resulting tool result cost a whole turn -- 65,136 output
+// tokens, a run that ended `incomplete`, ~235 KB rendered into the panel and an
+// unresponsive tab. A bad argument must cost one tool result, not a turn, so the
+// same budget that guards `print` now guards the whole serialized result.
+//
+// These helpers truncate and say so. They never throw: an over-long diagnostic
+// is still the most useful thing the model can read, so it is cut and labelled
+// rather than replaced.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export const MODEL_RESULT_BYTE_LIMIT = 1024 * 1024;
+export const MODEL_ERROR_BYTE_LIMIT = 8 * 1024;
+export function byteLength(text) {
+    return encoder.encode(text).byteLength;
+}
+/**
+ * `text` cut to at most `limit` bytes on a character boundary. A cut that lands
+ * inside a multi-byte sequence decodes to a trailing replacement character,
+ * which is dropped.
+ */
+export function truncateUtf8(text, limit) {
+    const bytes = encoder.encode(text);
+    if (bytes.byteLength <= limit)
+        return text;
+    return decoder.decode(bytes.subarray(0, limit)).replace(/�$/u, "");
+}
+/**
+ * `text` bounded to `limit` bytes with the omission stated in the same shape as
+ * the existing print budget message, so a model reading it knows the text is
+ * incomplete rather than wrong.
+ */
+export function boundedText(text, limit, label) {
+    const total = byteLength(text);
+    if (total <= limit)
+        return text;
+    const kept = truncateUtf8(text, limit);
+    return `${kept}\n[${label} truncated at ${limit} bytes; ${total - byteLength(kept)} bytes omitted.]`;
+}
+/**
+ * The serialized tool result the model reads, bounded to
+ * `MODEL_RESULT_BYTE_LIMIT`. Persistence, the UI stream and the host's own
+ * receipts keep the full output; only model input is bounded here.
+ *
+ * Stages, in order, so the most useful part survives: bound `error`, then bound
+ * each receipt's `details`, then keep only as many receipts as the budget
+ * allows, and finally fall back to the envelope with a note in place of the
+ * logs. Every stage leaves valid JSON -- a truncated JSON document would cost
+ * the model more than the bytes it saves.
+ */
+export function boundedResultText(output, limit = MODEL_RESULT_BYTE_LIMIT) {
+    const errorBounded = typeof output.error === "string"
+        ? { ...output, error: boundedText(output.error, MODEL_ERROR_BYTE_LIMIT, "Error") }
+        : output;
+    const asText = (value) => JSON.stringify(value) ?? "null";
+    let text = asText(errorBounded);
+    if (byteLength(text) <= limit)
+        return text;
+    const detailsLimit = Math.max(1024, Math.floor(limit / Math.max(errorBounded.receipts.length, 1)));
+    const trimmedReceipts = errorBounded.receipts.map((receipt) => {
+        if (receipt.details === undefined)
+            return receipt;
+        const details = asText(receipt.details);
+        if (byteLength(details) <= detailsLimit)
+            return receipt;
+        return {
+            ...receipt,
+            details: {
+                omitted: `This receipt's details were ${byteLength(details)} bytes, over the ${detailsLimit} byte limit for one receipt in a tool result. Read the receipt from the host if the outcome matters.`,
+            },
+        };
+    });
+    text = asText({ ...errorBounded, receipts: trimmedReceipts });
+    if (byteLength(text) <= limit)
+        return text;
+    const kept = [];
+    let used = byteLength(asText({ ...errorBounded, receipts: [] }));
+    for (const receipt of trimmedReceipts) {
+        const size = byteLength(asText(receipt)) + 1;
+        if (used + size > limit)
+            break;
+        kept.push(receipt);
+        used += size;
+    }
+    if (kept.length < trimmedReceipts.length) {
+        text = asText({
+            ...errorBounded,
+            receipts: kept,
+            receiptsOmitted: `${trimmedReceipts.length - kept.length} of ${trimmedReceipts.length} receipts were omitted to keep this result under the ${limit} byte limit.`,
+        });
+        if (byteLength(text) <= limit)
+            return text;
+    }
+    return asText({
+        version: errorBounded.version,
+        ok: errorBounded.ok,
+        purpose: errorBounded.purpose,
+        value: null,
+        logs: [],
+        receipts: [],
+        artifacts: [],
+        error: boundedText(`This result exceeded the ${limit} byte limit and was omitted. Print a filtered summary instead of whole objects.${typeof errorBounded.error === "string" ? ` The call also failed: ${errorBounded.error}` : ""}`, MODEL_ERROR_BYTE_LIMIT, "Error"),
+    });
+}

package/dist/capabilities/geometry.js

@@ -15,20 +15,20 @@ export function createGeometryCapability(host, reference) {
                 name: "geometry-nodes",
                 version: "5",
                 description: "Create and edit visual Geometry Nodes graphs with adjustable parameters and animation.",
-                instructions: `Use womp.geometry for requested Geometry Nodes or parametric geometry workflows, not Workbench Flow graphs.
-Keep follow-up edits to an existing Geometry Nodes object in its graph, preserving its adjustable parameters and instances.
-Read the target after any scene edit this build needs. read(0) reads the scene root as a creation container.
-write updates an existing shared graph, attaches a new graph to an Area without one, or creates a new Area beneath the root/Group target. Use the returned objectId for follow-up edits.
-Read geometry-nodes-reference before writing source. Supply the complete FlowIR text and the exact revision returned by the latest read. JavaScript calls execute JavaScript; source is a FlowIR string, not JavaScript or JSON.
-After a stale revision rejection, read the latest graph and adapt the edit while preserving intervening user changes. Ask only when the edits conflict or remain ambiguous; never retry the old replacement with a refreshed revision token.
-If source is null and diagnostics are present, the existing graph cannot be edited without loss. Explain the limitation; never treat it as empty or create a replacement to bypass the refusal.
-Preserve unrelated statements, parameter names, and FlowIR node IDs from the read. Shared graph edits affect all listed instances; report the affected objects. Valid overrides migrate by parameter name and type. Removed or type-changed parameters return to graph defaults and are reported.
-Use min/max/step for naturally bounded parameters and omit ranges for free-form positions/rotations. Meaningful parameter names become editor labels. Do not invent label fields.
-SetMaterial assigns one scene material to every primitive it receives. Its Material input is a scene material ID, not a color; 0 selects the scene default material.
-Obtain that ID from the scene-editing skill inside one scene.edit, where those lookups live: materialList with materialGetName and materialGetColor to reuse an existing material, materialCreate with materialSetColor and materialSetName for a new one, or listSuperMaterials with materialImport for a library material. Prefer reusing a material that already matches the request over creating another, and do not recolor a shared material unless every object using it should change.
-A scene edit changes the scene revision, so create or import the material before reading the geometry target, then write, all within one JavaScript call. Each call has a fresh scope and cannot read an earlier call's variables.
-Positions and sizes are millimetres; Boolean Blend uses the conversion in geometry-nodes-reference. Coordinates are right-handed, +X right, +Y up, +Z forward. Rotations are degrees, intrinsic X-Z-Y.
-On compiler errors, repair the source in this same conversation and retry with a fresh read. A rejected write made no change. Committed/unknown effects remain in execution receipts even if a later call fails; inspect before retrying.
+                instructions: `Use womp.geometry for requested Geometry Nodes or parametric geometry workflows, not Workbench Flow graphs.
+Keep follow-up edits to an existing Geometry Nodes object in its graph, preserving its adjustable parameters and instances.
+Read the target after any scene edit this build needs. read(0) reads the scene root as a creation container.
+write updates an existing shared graph, attaches a new graph to an Area without one, or creates a new Area beneath the root/Group target. Use the returned objectId for follow-up edits.
+Read geometry-nodes-reference before writing source. Supply the complete FlowIR text and the exact revision returned by the latest read. JavaScript calls execute JavaScript; source is a FlowIR string, not JavaScript or JSON.
+After a stale revision rejection, read the latest graph and adapt the edit while preserving intervening user changes. Ask only when the edits conflict or remain ambiguous; never retry the old replacement with a refreshed revision token.
+If source is null and diagnostics are present, the existing graph cannot be edited without loss. Explain the limitation; never treat it as empty or create a replacement to bypass the refusal.
+Preserve unrelated statements, parameter names, and FlowIR node IDs from the read. Shared graph edits affect all listed instances; report the affected objects. Valid overrides migrate by parameter name and type. Removed or type-changed parameters return to graph defaults and are reported.
+Use min/max/step for naturally bounded parameters and omit ranges for free-form positions/rotations. Meaningful parameter names become editor labels. Do not invent label fields.
+SetMaterial assigns one scene material to every primitive it receives. Its Material input is a scene material ID, not a color; 0 selects the scene default material.
+Obtain that ID from the scene-editing skill inside one scene.edit, where those lookups live: materialList with materialGetName and materialGetColor to reuse an existing material, materialCreate with materialSetColor and materialSetName for a new one, or listSuperMaterials with materialImport for a library material. Prefer reusing a material that already matches the request over creating another, and do not recolor a shared material unless every object using it should change.
+A scene edit changes the scene revision, so create or import the material before reading the geometry target, then write, all within one JavaScript call. Each call has a fresh scope and cannot read an earlier call's variables.
+Positions and sizes are millimetres; Boolean Blend uses the conversion in geometry-nodes-reference. Coordinates are right-handed, +X right, +Y up, +Z forward. Rotations are degrees, intrinsic X-Z-Y.
+On compiler errors, repair the source in this same conversation and retry with a fresh read. A rejected write made no change. Committed/unknown effects remain in execution receipts even if a later call fails; inspect before retrying.
 After applying, read the returned object and use the scene screenshot API with emitImage to inspect the applied result.`,
                 declarations: WOMP_GEOMETRY_DECLARATIONS,
                 examples: [

package/dist/capabilities/operations.js

@@ -79,38 +79,38 @@ export function createOperationsCapability(host) {
                 name: "generation",
                 version: "7",
                 description: "Generate or edit images and meshes, inspect jobs, and wait for their outputs.",
-                instructions: `Read operations.catalog() for the currently available models and selected defaults.
-Use generation for inline chat results. If the user is working in their Flow graph and flow-graphs is available,
-add the generation to that graph instead unless they request an inline result. When they want repeated variations,
-offer a reusable Flow workflow if available; accepting that offer means editing the graph, not submitting another inline job.
-Use generate() for image/mesh generation, image editing, upscaling, or background removal. Model IDs must
-come from the catalog and support the requested operation. An unavailable or restricted explicit choice
-is an error; do not silently substitute another model. Omit model IDs to use the user's defaults.
-For text-to-mesh, imageParams configures the image step and params configures the mesh step. For
-image-to-mesh, an optional prompt requests an image-editing step first. Advanced params are JSON
-values passed to the existing service; use documented options and do not invent provider settings.
-Author the full text-to-mesh image prompt yourself, preserving the user's requested subject and details.
-For a standalone object, describe a clear three-quarter view with a plain background and even lighting
-unless the user requests otherwise. Do not rely on another model to expand or rewrite this prompt.
-Inputs are image references returned by the available assets API or a previous completed operation.
-Do not fabricate references, replace a missing input with another image, or pass arbitrary URLs.
-Assign a short, distinct key to each intended job. Reuse that key when checking the same submission;
-never choose a new key merely to retry a timeout or unknown outcome. A key cannot identify two
-different requests. Host receipts and saved message IDs record submitted effects.
-generate() waits for cost confirmation and then for completion, failure, or cancellation.
-Use exactly one generation per execute_javascript call and print its result. Put follow-up work in
-another call. Do not poll, start background work, use Promise.all, or report success before completion.
-The host waits without consuming model steps. Stop ends agent execution; the host handles cancellation of its accepted jobs.
-Refresh recovery reconnects the same job. It never resumes the interrupted JavaScript stack.
-Read the recovered status and artifact references, then continue any requested remaining work in a new call; do not repeat generation.
-generate() returns the terminal status and job.outputs artifact references directly, including after recovery.
-Completed 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.
-For a simple generation request, finish with a brief acknowledgement of the completed status.
-Inspect images deliberately when needed for verification or reference comparisons; never claim visual verification without inspecting the image.
-Omitted image bytes are expected; missing artifact references are not. If a completed job has no outputs, recover the references or report the missing result.
-Reserve list() for older jobs or missing references. Follow nextFrom even when a page has no jobs.
-Verify an uncertain submission's job status, never issue a replacement request.
-Only returned outputs exist. Generating a mesh does not import it into the scene. Use the assets skill for requested imports.
+                instructions: `Read operations.catalog() for the currently available models and selected defaults.
+Use generation for inline chat results. If the user is working in their Flow graph and flow-graphs is available,
+add the generation to that graph instead unless they request an inline result. When they want repeated variations,
+offer a reusable Flow workflow if available; accepting that offer means editing the graph, not submitting another inline job.
+Use generate() for image/mesh generation, image editing, upscaling, or background removal. Model IDs must
+come from the catalog and support the requested operation. An unavailable or restricted explicit choice
+is an error; do not silently substitute another model. Omit model IDs to use the user's defaults.
+For text-to-mesh, imageParams configures the image step and params configures the mesh step. For
+image-to-mesh, an optional prompt requests an image-editing step first. Advanced params are JSON
+values passed to the existing service; use documented options and do not invent provider settings.
+Author the full text-to-mesh image prompt yourself, preserving the user's requested subject and details.
+For a standalone object, describe a clear three-quarter view with a plain background and even lighting
+unless the user requests otherwise. Do not rely on another model to expand or rewrite this prompt.
+Inputs are image references returned by the available assets API or a previous completed operation.
+Do not fabricate references, replace a missing input with another image, or pass arbitrary URLs.
+Assign a short, distinct key to each intended job. Reuse that key when checking the same submission;
+never choose a new key merely to retry a timeout or unknown outcome. A key cannot identify two
+different requests. Host receipts and saved message IDs record submitted effects.
+generate() waits for cost confirmation and then for completion, failure, or cancellation.
+Use exactly one generation per execute_javascript call and print its result. Put follow-up work in
+another call. Do not poll, start background work, use Promise.all, or report success before completion.
+The host waits without consuming model steps. Stop ends agent execution; the host handles cancellation of its accepted jobs.
+Refresh recovery reconnects the same job. It never resumes the interrupted JavaScript stack.
+Read the recovered status and artifact references, then continue any requested remaining work in a new call; do not repeat generation.
+generate() returns the terminal status and job.outputs artifact references directly, including after recovery.
+Completed 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.
+For a simple generation request, finish with a brief acknowledgement of the completed status.
+Inspect images deliberately when needed for verification or reference comparisons; never claim visual verification without inspecting the image.
+Omitted image bytes are expected; missing artifact references are not. If a completed job has no outputs, recover the references or report the missing result.
+Reserve list() for older jobs or missing references. Follow nextFrom even when a page has no jobs.
+Verify an uncertain submission's job status, never issue a replacement request.
+Only returned outputs exist. Generating a mesh does not import it into the scene. Use the assets skill for requested imports.
 Never resume stopped work or resubmit a job because cancellation or submission is uncertain.`,
                 declarations: WOMP_OPERATIONS_DECLARATIONS,
                 examples: [
@@ -147,7 +147,12 @@ Never resume stopped work or resubmit a job because cancellation or submission i
                                 failures = 0;
                             }
                             catch (error) {
-                                context.signal.throwIfAborted();
+                                // An aborted wait still stops here, but with the host's own
+                                // error: crow answers a cancelled generation with a sentence
+                                // explaining it, and `throwIfAborted` replaced that with the
+                                // bare abort reason.
+                                if (context.signal.aborted)
+                                    throw error;
                                 if (++failures >= 3)
                                     throw error;
                                 await new Promise((resolve, reject) => {

package/dist/capabilities/scene.js

@@ -1,6 +1,27 @@
 import { z } from "zod";
 import { WOMP_SCENE_DECLARATIONS } from "../generated/scene-declarations.js";
 import { unverifiedSceneHealth } from "../scene-health.js";
+// A node id, as `scene.read()` publishes them: the scene root is 0, so a health
+// read has to accept it. `openscad.ts` and `geometry.ts` spell an object id the
+// same way; `positive()` here refused an id this capability had just handed out.
+const objectId = z.number().int().nonnegative();
+const healthObjectIds = z.array(objectId).default([]);
+function display(value) {
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value) ?? String(value);
+}
+/** Ids for a health read, or a sentence -- never a raw validation dump. */
+function readHealthObjectIds(objectIds) {
+    const parsed = healthObjectIds.safeParse(objectIds);
+    if (parsed.success)
+        return parsed.data;
+    const invalid = Array.isArray(objectIds)
+        ? objectIds.filter((value) => objectId.safeParse(value).success === false)
+        : [objectIds];
+    const named = invalid.slice(0, 3).map(display).join(", ");
+    throw new Error(`scene.health takes object ids from scene.read(): whole numbers from 0 up, in an array. ${named} ${invalid.length === 1 ? "is not one" : "are not ids"}.`);
+}
 const cameraVector = z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).strict();
 const screenshotOptions = z.object({
     camera: z.object({
@@ -16,82 +37,82 @@ export function createSceneCapability(host) {
         skills: [
             {
                 name: "scene-editing",
-                version: "29",
+                version: "30",
                 description: "Inspect the open scene and edit its objects, materials, curves, and environment.",
-                instructions: `Read the scene first and keep its revision and object IDs. read() includes health.
-Use womp.scene.health() to refresh whole-scene health or womp.scene.health(objectIds) to check specific objects (mapped to their owning Areas).
-Health is a separate snapshot, not proof of consistency with read().revision or that the latest edit finished evaluating. Inspect post-edit health in receipts before claiming success; refresh only when needed.
-Unavailable, stale, or unverified feedback must not trigger blind regeneration or a claim that the model passed. Hosts without health services return unverified health with a reason.
-For confirmed primitive or depth overflow, repair the same target while preserving design, dimensions, active parameter overrides, and unrelated objects. At most two geometry repairs are allowed per target in one logical run.
-Empty Areas may be pending, intentionally empty, mesh-only, or failed. Overflow flags take precedence over possibly stale counts.
-max_total_depth reports the engine's tier-dependent nesting allowance, not measured depth. Compiled Boolean depth includes generated grouping; organizational Groups do not add a level. Use flag_depth_overflow to detect evaluator rejection.
-Call scene.edit(callback, expectedRevision)
-for one coherent undoable change. The callback receives a draft; all node/material/curve functions and enums
-are properties of that draft. The draft expires when the callback ends. Await asynchronous methods.
-Do not start unrelated operations from inside an edit. A stale revision requires reading again.
-Preserve the existing scene unless asked to remove or replace content. Use semantic object names and reuse
-known IDs when editing rather than creating duplicates. Distances follow the current project's units
-(read().unitMultiplier is 1 for millimetres, 0.1 for centimetres, approximately 0.0393701 for inches).
-Convert a dimension in millimetres to project units by multiplying it by read().unitMultiplier.
-The SDK-backed draft clamps dimension writes to 0.01–1000 mm per component before converting to native units; this is an adapter limit, not a scene-wide size limit. Read back dimensions when physical size matters.
-Area size is a dimensionless scale; Group size stays fixed at one. Lights must be created at root (parentId 0); their size has x/y dimensions.
-Light power must be a finite number in [0, 100].
-nodeCreate(Curve, parentId) creates an empty curve with zero blend. curvePointAdd(curveId, point, index?) returns the new index; omit index to append or supply an integer from 0 through point count to insert before that position.
-Point defaults: position/rotation/handles zero, profile size {x:1,y:1,z:1} in project units, the curve's material, fixed false, round 0. Pass {} for defaults.
-Removing all points is supported. One point renders a single profile primitive, not a path.
-Curves render sampled profiles, not a continuous sweep. For smooth curves, start with nodeSetDensity(curveId, 250) and nodeSetBlend(curveId, 3).
-Density increases sampling and primitive cost; the 3 mm blend softens joins, not sample positions. Adjust blend to preserve thin features and the intended silhouette; these settings do not guarantee continuity.
-nodeSetUnionResolution(unionId, resolution) sets Area/Union resolution, not child-part resolution, and clamps to 0.01–0.65; higher values increase detail and voxel cost. Material emission ranges from 0 to 1.
-nodeSetBlend and mirror goop take radii in millimetres before parent scaling, regardless of project units, and clamp to 0–500 mm. This does not apply to the FlowIR Boolean Blend port, which takes native units; geometry-nodes-reference gives its conversion.
-V1/V2 curve transforms are read-only;
-edit their points instead. Handles and closure are available only on V3 Bezier curves.
-Typed rotations are right-handed intrinsic XYZ Euler degrees, relative to the parent (R = Rx Ry Rz), including curve points and mirrors.
-Points and curve mirrors use the owning curve frame; primitive mirrors use the primitive's parent frame.
-lookAt(origin, target) aligns local +Z; both points must be in the same parent-local space. For a segment along a different local axis,
-use alignAxis(direction, 'x'|'y'|'z'); cylinders and cones extend along local Y. These return rotations, not world-space transforms.
-Alignment chooses a deterministic roll using Y-up (Z-up fallback when parallel); coincident/non-finite directions are errors.
-The SDK handles native XZY conversion; do not swap Euler components or convert again. Geometry Nodes source remains native XZY.
-Colors use RGB values from 0 to 255. Use the exposed enums instead of guessing values.
-For visible geometry color, create or clone a material, call materialSetColor, and assign it with nodeSetMaterialId only to
-Primitive, Curve, Text, SVG, Mesh, Field, Decal or OpenSCAD nodes. Assigning a curve material recolors its existing points; use curvePointSetMaterialId for per-point overrides afterward.
-Areas/Unions, Groups, Lights and Sockets do not accept direct materials. Color ordinary containers through their supported children.
-Geometry Nodes materials belong in the graph: create or import the material here, then assign it inside the graph with the FlowIR SetMaterial node, passing the numeric ID this skill returns.
-Never replace a parametric graph with ordinary primitives to color it. Ordinary Stain/CSG children do not modify graph output.
-nodeSetColor writes the node color field (used by lights); it does not replace a geometry object's material color.
-Do not recolor a shared material unless every object using it should change. Create and assign the material in the same edit as the scene geometry that uses it; a Geometry Nodes graph instead consumes a material ID created in an earlier edit.
-Create primitives, curves, and text inside Areas/Unions. Respect tree order for subtraction and intersection.
-Groups are organizational only; move and rotate their child Areas individually, not the Group. Use unions for blended masses.
-Sphere uses size.x as uniform diameter (y/z do not stretch it), including new or resized spherical curve points. Cylinder/Cone/Pyramid use x as base diameter/width and y as height;
-Torus uses x as outer diameter and y as tube thickness. For these four primitives, nodeSetSize accepts {x, y}; z follows x even when supplied. Cube uses all three dimensions. Node and curve-point round are dimensionless fractions clamped to [0, 1], not radii in project units; rounding does not set size. Cube rounding reaches half its shortest dimension at 1, so a shallow Cube retains broad flat faces rather than becoming an ellipsoid.
-Build and verify coarse geometry and unfamiliar operations before replicating details. Check one representative result, then repeat it.
+                instructions: `Read the scene first and keep its revision and object IDs. read() includes health.
+Use womp.scene.health() to refresh whole-scene health or womp.scene.health(objectIds) to check specific objects (mapped to their owning Areas).
+Health is a separate snapshot, not proof of consistency with read().revision or that the latest edit finished evaluating. Inspect post-edit health in receipts before claiming success; refresh only when needed.
+Unavailable, stale, or unverified feedback must not trigger blind regeneration or a claim that the model passed. Hosts without health services return unverified health with a reason.
+For confirmed primitive or depth overflow, repair the same target while preserving design, dimensions, active parameter overrides, and unrelated objects. At most two geometry repairs are allowed per target in one logical run.
+Empty Areas may be pending, intentionally empty, mesh-only, or failed. Overflow flags take precedence over possibly stale counts.
+max_total_depth reports the engine's tier-dependent nesting allowance, not measured depth. Compiled Boolean depth includes generated grouping; organizational Groups do not add a level. Use flag_depth_overflow to detect evaluator rejection.
+Call scene.edit(callback, expectedRevision)
+for one coherent undoable change. The callback receives a draft; all node/material/curve functions and enums
+are properties of that draft. The draft expires when the callback ends. Await asynchronous methods.
+Do not start unrelated operations from inside an edit. A stale revision requires reading again.
+Preserve the existing scene unless asked to remove or replace content. Use semantic object names and reuse
+known IDs when editing rather than creating duplicates. Distances follow the current project's units
+(read().unitMultiplier is 1 for millimetres, 0.1 for centimetres, approximately 0.0393701 for inches).
+Convert a dimension in millimetres to project units by multiplying it by read().unitMultiplier.
+The SDK-backed draft clamps dimension writes to 0.01–1000 mm per component before converting to native units; this is an adapter limit, not a scene-wide size limit. Read back dimensions when physical size matters.
+Area size is a dimensionless scale; Group size stays fixed at one. Lights must be created at root (parentId 0); their size has x/y dimensions.
+Light power must be a finite number in [0, 100].
+nodeCreate(Curve, parentId) creates an empty curve with zero blend. curvePointAdd(curveId, point, index?) returns the new index; omit index to append or supply an integer from 0 through point count to insert before that position.
+Point defaults: position/rotation/handles zero, profile size {x:1,y:1,z:1} in project units, the curve's material, fixed false, round 0. Pass {} for defaults.
+Removing all points is supported. One point renders a single profile primitive, not a path.
+Curves render sampled profiles, not a continuous sweep. For smooth curves, start with nodeSetDensity(curveId, 250) and nodeSetBlend(curveId, 3).
+Density increases sampling and primitive cost; the 3 mm blend softens joins, not sample positions. Adjust blend to preserve thin features and the intended silhouette; these settings do not guarantee continuity.
+nodeSetUnionResolution(unionId, resolution) sets Area/Union resolution, not child-part resolution, and clamps to 0.01–0.65; higher values increase detail and voxel cost. Material emission ranges from 0 to 1.
+nodeSetBlend and mirror goop take radii in millimetres before parent scaling, regardless of project units, and clamp to 0–500 mm. This does not apply to the FlowIR Boolean Blend port, which takes native units; geometry-nodes-reference gives its conversion.
+V1/V2 curve transforms are read-only;
+edit their points instead. Handles and closure are available only on V3 Bezier curves.
+Typed rotations are right-handed intrinsic XYZ Euler degrees, relative to the parent (R = Rx Ry Rz), including curve points and mirrors.
+Points and curve mirrors use the owning curve frame; primitive mirrors use the primitive's parent frame.
+lookAt(origin, target) aligns local +Z; both points must be in the same parent-local space. For a segment along a different local axis,
+use alignAxis(direction, 'x'|'y'|'z'); cylinders and cones extend along local Y. These return rotations, not world-space transforms.
+Alignment chooses a deterministic roll using Y-up (Z-up fallback when parallel); coincident/non-finite directions are errors.
+The SDK handles native XZY conversion; do not swap Euler components or convert again. Geometry Nodes source remains native XZY.
+Colors use RGB values from 0 to 255. Use the exposed enums instead of guessing values.
+For visible geometry color, create or clone a material, call materialSetColor, and assign it with nodeSetMaterialId only to
+Primitive, Curve, Text, SVG, Mesh, Field, Decal or OpenSCAD nodes. Assigning a curve material recolors its existing points; use curvePointSetMaterialId for per-point overrides afterward.
+Areas/Unions, Groups, Lights and Sockets do not accept direct materials. Color ordinary containers through their supported children.
+Geometry Nodes materials belong in the graph: create or import the material here, then assign it inside the graph with the FlowIR SetMaterial node, passing the numeric ID this skill returns.
+Never replace a parametric graph with ordinary primitives to color it. Ordinary Stain/CSG children do not modify graph output.
+nodeSetColor writes the node color field (used by lights); it does not replace a geometry object's material color.
+Do not recolor a shared material unless every object using it should change. Create and assign the material in the same edit as the scene geometry that uses it; a Geometry Nodes graph instead consumes a material ID created in an earlier edit.
+Create primitives, curves, and text inside Areas/Unions. Respect tree order for subtraction and intersection.
+Groups are organizational only; move and rotate their child Areas individually, not the Group. Use unions for blended masses.
+Sphere uses size.x as uniform diameter (y/z do not stretch it), including new or resized spherical curve points. Cylinder/Cone/Pyramid use x as base diameter/width and y as height;
+Torus uses x as outer diameter and y as tube thickness. For these four primitives, nodeSetSize accepts {x, y}; z follows x even when supplied. Cube uses all three dimensions. Node and curve-point round are dimensionless fractions clamped to [0, 1], not radii in project units; rounding does not set size. Cube rounding reaches half its shortest dimension at 1, so a shallow Cube retains broad flat faces rather than becoming an ellipsoid.
+Build and verify coarse geometry and unfamiliar operations before replicating details. Check one representative result, then repeat it.
 Reference fidelity:
 When recreating an image, treat its visible geometry and level of detail as the target—not merely its subject, colors, or list of parts. Preserve the user's chosen workflow and editability requirements.
 Establish a comparison view matching the reference's angle, projection, and subject framing as closely as practical. Match silhouette, proportions, pose, and negative spaces first; then local contours, thickness, curvature, surface transitions, and defining details. Infer unseen geometry conservatively.
 Compare each rendered pass directly with the source. Identify the largest remaining visible shape mismatch, edit it, and verify that it improved before moving to smaller details. Use close-ups when the comparison view cannot resolve a feature; return to the comparison view afterward. Adjust sampling or resolution when visible faceting or segmentation requires it—not as a substitute for reshaping.
 Do not stop at semantic resemblance or after a fixed number of screenshots. Continue while substantial visible mismatches remain and supported edits are making progress, within the available budget. If progress stalls or the chosen representation cannot achieve the requested fidelity, explain the specific limitation and ask before changing workflows. Before finishing, compare the latest render with the reference and address the largest remaining visible mismatch; if substantial differences remain, identify the concrete stopping reason rather than treating an approximation disclaimer as completion.
 
-nodeClone is shallow (no children). await cloneSubtree(id, { parentId?, name?, index? }) copies the complete hierarchy with fresh IDs,
-preserving local transforms, order and metadata, remapping internal references and sharing external materials/assets.
-Cloning requires a host transport with atomic scene patches; an unsupported host rejects it without changing the draft.
-For primitives, nodeSetBlend joins against all accumulated preceding geometry in the Area, not only the nearest part. A Union's blend affects its outer join, not joins between its children; top-level Area blend does not smooth its contents.
-For organic joins, overlap primitives and tune blend on the joining children while preserving intended gaps; keep crisp accessories separate.
-Check font, HDR, and material catalogs before selecting names. A host can explicitly report a catalog as
-unavailable. Selecting an HDR resets its intensity; apply a custom intensity after selecting it.
-For library materials, use listSuperMaterials(), then await materialImport(name) inside scene.edit and assign the returned numeric ID the way that object requires: nodeSetMaterialId or curvePointSetMaterialId for scene nodes, the FlowIR SetMaterial node for a Geometry Nodes graph. A failed import rolls back the draft.
-Filter large read results with JavaScript and print only useful details.
-After a major edit, capture a screenshot outside the transaction and emitImage its reference.
-screenshot({ camera: { position: {x,y,z}, target: {x,y,z}, projection: 'perspective', horizontalFovDegrees: 60 } })
-sets a world-space camera in the same Womp coordinates and project units as scene positions (Y-up).
-For orthographic framing use projection: 'orthographic' and orthographicWidth in project units instead of FOV.
-Direction is derived from position/target; do not use coincident points or an exactly vertical viewing direction.
+nodeClone is shallow (no children). await cloneSubtree(id, { parentId?, name?, index? }) copies the complete hierarchy with fresh IDs,
+preserving local transforms, order and metadata, remapping internal references and sharing external materials/assets.
+Cloning requires a host transport with atomic scene patches; an unsupported host rejects it without changing the draft.
+For primitives, nodeSetBlend joins against all accumulated preceding geometry in the Area, not only the nearest part. A Union's blend affects its outer join, not joins between its children; top-level Area blend does not smooth its contents.
+For organic joins, overlap primitives and tune blend on the joining children while preserving intended gaps; keep crisp accessories separate.
+Check font, HDR, and material catalogs before selecting names. A host can explicitly report a catalog as
+unavailable. Selecting an HDR resets its intensity; apply a custom intensity after selecting it.
+For library materials, use listSuperMaterials(), then await materialImport(name) inside scene.edit and assign the returned numeric ID the way that object requires: nodeSetMaterialId or curvePointSetMaterialId for scene nodes, the FlowIR SetMaterial node for a Geometry Nodes graph. A failed import rolls back the draft.
+Filter large read results with JavaScript and print only useful details.
+After a major edit, capture a screenshot outside the transaction and emitImage its reference.
+screenshot({ camera: { position: {x,y,z}, target: {x,y,z}, projection: 'perspective', horizontalFovDegrees: 60 } })
+sets a world-space camera in the same Womp coordinates and project units as scene positions (Y-up).
+For orthographic framing use projection: 'orthographic' and orthographicWidth in project units instead of FOV.
+Direction is derived from position/target; do not use coincident points or an exactly vertical viewing direction.
 Omitted projection/lens settings come from the active camera. Pass the camera again for repeatable captures.
 For object-focused screenshots, identify the requested object and frame it with an explicit camera position and target using its bounds; reuse established framing when appropriate. Choose a view that reveals the requested features without clipping the subject.
 Omitting camera captures the active viewport without auto-fit. Use it when the user asks about the current viewport or clearly refers to what is visible on screen, not on the assumption that it shows the requested object.
 Respect the host's camera-lock restrictions. Verify silhouette,
-connections, openings, proportions, and materials before claiming completion. Use the owning top-level Area for scene-space bounds;
-OpenSCAD part bounds are local to the part; individual primitive and curve bounds are unsupported. Renderer bounds and resize calls
-must finish before subsequent writes. Inside scene.edit, complete renderer-backed bounds reads before the first
-draft mutation; the SDK rejects them once the draft is dirty. Inspect committed results when renderer state has not caught up.
+connections, openings, proportions, and materials before claiming completion. Use the owning top-level Area for scene-space bounds;
+OpenSCAD part bounds are local to the part; individual primitive and curve bounds are unsupported. Renderer bounds and resize calls
+must finish before subsequent writes. Inside scene.edit, complete renderer-backed bounds reads before the first
+draft mutation; the SDK rejects them once the draft is dirty. Inspect committed results when renderer state has not caught up.
 A failed script can retain earlier committed effects. Use receipts and inspect unknown outcomes before retrying.`,
                 declarations: WOMP_SCENE_DECLARATIONS,
                 examples: [
@@ -104,7 +125,7 @@ A failed script can retain earlier committed effects. Use receipts and inspect u
         ],
         createApi: (context) => {
             const health = async (objectIds) => {
-                const ids = z.array(z.number().int().positive()).default([]).parse(objectIds);
+                const ids = readHealthObjectIds(objectIds);
                 context.signal.throwIfAborted();
                 if (!host.health)
                     return unverifiedSceneHealth([], "This host does not provide scene health services.");

package/dist/color.d.ts

@@ -0,0 +1,8 @@
+/**
+ * True when every component is strictly between 0 and 1 and none is an integer
+ * -- which no color anyone means in 0-255 terms can be, and no saturated 0-1
+ * color is either, since 0 and 1 are integers.
+ */
+export declare function looksLikeUnitColor(components: readonly number[]): boolean;
+/** Refuses a 0-1 color, carrying the 0-255 conversion so it can be corrected in one step. */
+export declare function assertColor255(components: readonly number[], label?: string): void;

package/dist/color.js

@@ -0,0 +1,29 @@
+// The one place that says what a color component means here.
+//
+// WHY THIS FILE EXISTS. Every model-facing color in this package is 0-255 per
+// channel, converted to the engine's 0-1 by dividing by 255. A model handed a
+// unitless `{ r, g, b }` next to `nodeSetPos`/`nodeSetRot`, which are in project
+// units, has every reason to read it as 0-1: `nodeSetColor({ r: 0.2, g: 0.4,
+// b: 0.6 })` used to divide again and read back as `{ r: 0, g: 0, b: 1 }` --
+// silently near-black, with no error and no warning. Saturated colors survive
+// either reading (`{ r: 1, g: 0, b: 0 }` and `{ r: 255, g: 0, b: 0 }` are both
+// legible), which is what hid it.
+//
+// So a color that can only be a 0-1 one is refused, and nothing is auto-scaled:
+// multiplying by 255 would reinterpret a legitimate near-black instead of
+// asking, and guessing is what made this a defect in the first place.
+/**
+ * True when every component is strictly between 0 and 1 and none is an integer
+ * -- which no color anyone means in 0-255 terms can be, and no saturated 0-1
+ * color is either, since 0 and 1 are integers.
+ */
+export function looksLikeUnitColor(components) {
+    return components.every((value) => Number.isFinite(value) && value > 0 && value < 1 && Number.isInteger(value) === false);
+}
+/** Refuses a 0-1 color, carrying the 0-255 conversion so it can be corrected in one step. */
+export function assertColor255(components, label = "Color") {
+    if (looksLikeUnitColor(components) === false)
+        return;
+    const [r = 0, g = 0, b = 0] = components;
+    throw new Error(`${label} components are 0-255, so {r:${r}, g:${g}, b:${b}} is near-black. Use {r:${Math.round(r * 255)}, g:${Math.round(g * 255)}, b:${Math.round(b * 255)}} for that color, or {r:0, g:0, b:0} for black.`);
+}