@womp/spark-agent 3.0.2 → 4.0.0

package/dist/agent.js

@@ -2,7 +2,6 @@ import { createUIMessageStream, stepCountIs, streamText, } from "ai";
 import { createSparkTools } from "./agent-tools.js";
 import { SPARK_AGENT_PROMPT } from "./prompt.js";
 import { calculateStepCost } from "./pricing.js";
-import { prepareSparkContext, SparkContextLimitError } from "./context.js";
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -91,7 +90,6 @@ export function runSparkAgent(options) {
         execute: async ({ writer }) => {
             let generationError;
             let stepCount = 0;
-            let readUsage;
             try {
                 controller.signal.throwIfAborted();
                 const tools = createSparkTools({
@@ -123,12 +121,9 @@ export function runSparkAgent(options) {
                             ? messages
                             : await options.prepareMessages(messages);
                         controller.signal.throwIfAborted();
-                        const system = readSystem();
                         return {
-                            system,
-                            messages: prepareSparkContext(prepared, system, {
-                                maxInputTokens: options.maxInputTokens ?? 128_000,
-                            }),
+                            system: readSystem(),
+                            messages: prepared,
                         };
                     },
                     onError: ({ error }) => {
@@ -158,12 +153,9 @@ export function runSparkAgent(options) {
                         }
                     },
                 });
-                readUsage = () => generation.totalUsage;
-                writer.merge(generation
-                    .toUIMessageStream({
+                writer.merge(generation.toUIMessageStream({
                     generateMessageId: () => options.messageId,
                     onError: (error) => {
-                        // Record the error before its UI chunk reaches the filter below;
                         // streamText's onError callback may run later on another stream branch.
                         generationError = error;
                         return errorMessage(error);
@@ -178,16 +170,7 @@ export function runSparkAgent(options) {
                         }
                         return undefined;
                     },
-                })
-                    .pipeThrough(new TransformStream({
-                    transform(chunk, streamController) {
-                        // A context limit is a controlled terminal outcome. An SDK error
-                        // chunk would make chat consumers stop before its final checkpoint.
-                        if (chunk.type === "error" && generationError instanceof SparkContextLimitError)
-                            return;
-                        streamController.enqueue(chunk);
-                    },
-                })));
+                }));
                 const [text, usage, finishReason] = await Promise.all([
                     generation.text,
                     generation.totalUsage,
@@ -201,21 +184,6 @@ export function runSparkAgent(options) {
             }
             catch (error) {
                 const failure = generationError ?? error;
-                if (failure instanceof SparkContextLimitError && !options.signal?.aborted) {
-                    const usage = await Promise.resolve(readUsage?.()).catch(() => undefined);
-                    writer.write({
-                        type: "message-metadata",
-                        messageMetadata: { ...metadata("incomplete", usage), error: failure.message },
-                    });
-                    completedResult = {
-                        text: failure.message,
-                        steps: stepCount,
-                        usage,
-                        status: "incomplete",
-                        finishReason: "context-limit",
-                    };
-                    return;
-                }
                 const status = options.signal?.aborted ? "cancelled" : "failed";
                 writer.write({
                     type: "message-metadata",

package/dist/capabilities/geometry.js

@@ -25,7 +25,7 @@ After a stale revision rejection, read the latest graph and adapt the edit while
 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.
-Units are millimetres. Coordinates are right-handed, +X right, +Y up, +Z forward. Rotations are degrees, intrinsic X-Z-Y.
+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 inspect a screenshot through scene-verification when available.`,
                 declarations: WOMP_GEOMETRY_DECLARATIONS,

package/dist/capabilities/openscad-instructions.d.ts

@@ -1 +1 @@
-export declare const OPENSCAD_INSTRUCTIONS = "Use womp.openscad to create or update one adjustable part. Read an existing part before editing it.\nChoose CAD for mechanical, measured, and hard-surface parametric parts even without explicit dimensions.\nFor an explicit visual node graph, parametric organic or smoothly blended forms, or parametric animation,\nuse geometry-nodes when available. Do not force organic sculpture into CAD or silently change the requested editing surface.\nread(0) returns the root container and a scene revision for creation. read(id) returns an existing\npart or container. Use the scene-editing skill when available to discover other scene objects.\ncreate requires a parentId (0 means the scene root); update requires the existing objectId.\nBoth methods compile the effective source and parameters, apply one undoable change, and check wall thickness.\nA stale revision requires reading again and adapting the edit while preserving intervening user changes.\nAsk the user only when the intended edits conflict or remain ambiguous; never reuse the old replacement\nwith a refreshed revision token. Existing overrides are preserved for parameters still present;\nparams supplies overrides to merge into the current values. Keep top-level parameter names stable.\nReturn complete source on every update and preserve unrelated geometry. Never create a replacement to repair a part.\nCompile errors return status rejected without applying. Creation requires validated placement bounds.\nAn update may apply with validation unavailable; that is a diagnostic, not proof that it compiles.\nAn applied part remains in the scene even if thickness fails or is unavailable. Use the returned objectId for repairs.\nWhen thickness fails, increase thin walls and fragile connections while preserving requested dimensions and openings.\nAt most four applied printability repairs are allowed per logical build/edit in this run. Respect the returned limit;\ndo not bypass it by recreating the part. Unavailable thickness is not a pass. Report unresolved issues honestly.\nBuild connected geometry and avoid features below 1.4 mm. OpenSCAD source dimensions use millimetres,\nindependently of the scene display unit. New parts are centered and grounded from compiled bounds.\nAfter a major change, use the scene screenshot API and emitImage to inspect the applied result.\nA committed effect can survive later failure. Inspect receipts and the existing part before retrying.\nDo not print source in the final answer unless requested; describe the result and any unresolved diagnostics.\n\nRUNTIME\n- Produce a single OpenSCAD file.\n- Do not use imports, includes, external libraries, text, hull, minkowski, polyhedron, or extrudes.\n- Prefer cube, sphere, cylinder, translate, rotate, color, union, difference, and intersection.\n- Do not use $fn, $fa, or $fs; tessellation controls are ignored.\n- Build faceted geometry by combining supported primitives with CSG operations and transforms.\n- Do not use scale(); size primitives directly instead.\n- Use color(\"#rrggbb\") around distinct visible parts.\n- Keep the model centered near the origin and use millimeter-like units consistently.\n- For organic blending, use goop(amount) { ... }. It is ordered: the first child seeds with blend 0, and each later child blends using amount.\n- Put core primitives first. Avoid wrapping goop children in union() when they should blend individually.\n\nSCREWS AND THREADS\n- Copy helical_ridge below for rounded screw threads, necks, caps, and coils. Like geometry-node curves, it joins spheres with cylinders; never use stacked rings or disconnected spheres.\n- Dimensions are mm: radius = ridge centerline radius; pitch = axial travel/turn; tube_radius = half ridge thickness; handedness = 1 (right) or -1 (left).\n- For a hand control use thread_hand = 1; // [-1:Left, 1:Right] and pass it directly. Ternary expressions (?:) are unsupported.\n- Embed the ridge in the shaft/neck (e.g. radius = shaft_radius). Hollow fittings: subtract the bore from body + thread. Internal threads: subtract the helix from the socket wall with mating clearance. Mating parts need matching pitch and handedness.\n- Expose diameter, pitch, thread length, and thickness in Customizer; derive sampling. Keep 2 * tube_radius < pitch and allow tube_radius beyond both path endpoints for rounded ends. This is a rounded profile, not ISO/metric V-thread; never claim standards compliance.\n- Build heads/grips separately using cylinders, tapered cylinders, and radial ribs/cutters, not thread samples.\n\nmodule helical_ridge(radius, pitch, turns, tube_radius, handedness) {\n  if (radius > 0 && pitch > 0 && turns > 0 && tube_radius > 0) {\n    // Limit chord error to 0.03 mm or 3% of the ridge radius.\n    chord_error = min(0.03, tube_radius * 0.03);\n    steps_per_turn = max(48, ceil(180 / acos(1 - min(1, chord_error / radius))));\n    steps = ceil(turns * steps_per_turn);\n    for (i = [0:steps]) {\n      angle = handedness * 360 * turns * i / steps;\n      p = [radius * cos(angle), radius * sin(angle), pitch * turns * i / steps];\n      translate(p) sphere(r = tube_radius);\n      if (i < steps) {\n        next_angle = handedness * 360 * turns * (i + 1) / steps;\n        dx = radius * cos(next_angle) - p[0];\n        dy = radius * sin(next_angle) - p[1];\n        dz = pitch * turns / steps;\n        segment_length = sqrt(dx * dx + dy * dy + dz * dz);\n        translate(p)\n          rotate([0, acos(dz / segment_length), atan2(dy, dx)])\n            cylinder(h = segment_length, r = tube_radius);\n      }\n    }\n  }\n}\n\nPARAMETERS\n- Make important top-level constants user-adjustable with OpenSCAD Customizer comments:\n  - Numbers with ranges: body_radius = 12; // [4:0.5:40]\n  - Counts: leg_count = 4; // [2:8]\n  - Booleans: show_base = true;\n  - Options: style = \"round\"; // [round, sharp, chunky]\n- Prefer stable size/count/ratio/style controls; keep fragile dependent dimensions as local expressions.\n\nSUPPORTED SUBSET\n- Export is best-effort from a supported CSG subset: cube, sphere, cylinder, translate, rotate, color, union, difference, intersection, and goop.\n- difference() cutters become subtractive primitives, so use clean cutters that fully pass through the target solid.\n- Unsupported OpenSCAD may validate but can warn or skip during export; prefer the supported subset above.";
+export declare const OPENSCAD_INSTRUCTIONS = "Use womp.openscad to create or update one adjustable part. Read an existing part before editing it.\nChoose CAD for mechanical, measured, and hard-surface parametric parts even without explicit dimensions.\nFor an explicit visual node graph, parametric organic or smoothly blended forms, or parametric animation,\nuse geometry-nodes when available. Do not force organic sculpture into CAD or silently change the requested editing surface.\nread(0) returns the root container and a scene revision for creation. read(id) returns an existing\npart or container. Use the scene-editing skill when available to discover other scene objects.\ncreate requires a parentId (0 means the scene root); update requires the existing objectId.\nBoth methods compile the effective source and parameters, apply one undoable change, and check wall thickness.\nA stale revision requires reading again and adapting the edit while preserving intervening user changes.\nAsk the user only when the intended edits conflict or remain ambiguous; never reuse the old replacement\nwith a refreshed revision token. Existing overrides are preserved for parameters still present;\nparams supplies overrides to merge into the current values. Keep top-level parameter names stable.\nReturn complete source on every update and preserve unrelated geometry. Never create a replacement to repair a part.\nCompile errors return status rejected without applying. Creation requires validated placement bounds.\nAn update may apply with validation unavailable; that is a diagnostic, not proof that it compiles.\nAn applied part remains in the scene even if thickness fails or is unavailable. Use the returned objectId for repairs.\nWhen thickness fails, increase thin walls and fragile connections while preserving requested dimensions and openings.\nAt most four applied printability repairs are allowed per logical build/edit in this run. Respect the returned limit;\ndo not bypass it by recreating the part. Unavailable thickness is not a pass. Report unresolved issues honestly.\nBuild connected geometry and avoid features below 1.4 mm. OpenSCAD source dimensions use millimetres,\nindependently of the scene display unit. New parts are centered and grounded from compiled bounds.\nOpenSCAD is Z-up; the scene-editing API is Y-up. For an unrotated part at its creation-time scale and an identity parent transform,\na source point [x,y,z] mm maps to scene {x:y, y:z, z:-x} times the unitMultiplier returned by scene.read(), plus nodeGetPos(partId).\nAccount for the part and parent transforms when they are not identity; source coordinates are not scene coordinates.\nAfter a major change, use the scene screenshot API and emitImage to inspect the applied result.\nA committed effect can survive later failure. Inspect receipts and the existing part before retrying.\nDo not print source in the final answer unless requested; describe the result and any unresolved diagnostics.\n\nRUNTIME\n- Produce a single OpenSCAD file.\n- Do not use imports, includes, external libraries, text, hull, minkowski, polyhedron, or extrudes.\n- Prefer cube, sphere, cylinder, translate, rotate, color, union, difference, and intersection.\n- Do not use $fn, $fa, or $fs; tessellation controls are ignored.\n- Build faceted geometry by combining supported primitives with CSG operations and transforms.\n- Do not use scale(); size primitives directly instead.\n- Use color(\"#rrggbb\") around distinct visible parts.\n- Keep the model centered near the origin and use millimeter-like units consistently.\n- For organic blending, use goop(radius_mm) { ... }. The radius is in millimetres before parent scaling, matching scene-editing; do not multiply by project unitMultiplier. It is ordered: the first child seeds with blend 0, and each later child uses radius_mm.\n- Put core primitives first. Avoid wrapping goop children in union() when they should blend individually.\n\nSCREWS AND THREADS\n- Copy helical_ridge below for rounded screw threads, necks, caps, and coils. Like geometry-node curves, it joins spheres with cylinders; never use stacked rings or disconnected spheres.\n- Dimensions are mm: radius = ridge centerline radius; pitch = axial travel/turn; tube_radius = half ridge thickness; handedness = 1 (right) or -1 (left).\n- For a hand control use thread_hand = 1; // [-1:Left, 1:Right] and pass it directly. Ternary expressions (?:) are unsupported.\n- Embed the ridge in the shaft/neck (e.g. radius = shaft_radius). Hollow fittings: subtract the bore from body + thread. Internal threads: subtract the helix from the socket wall with mating clearance. Mating parts need matching pitch and handedness.\n- Expose diameter, pitch, thread length, and thickness in Customizer; derive sampling. Keep 2 * tube_radius < pitch and allow tube_radius beyond both path endpoints for rounded ends. This is a rounded profile, not ISO/metric V-thread; never claim standards compliance.\n- Build heads/grips separately using cylinders, tapered cylinders, and radial ribs/cutters, not thread samples.\n\nmodule helical_ridge(radius, pitch, turns, tube_radius, handedness) {\n  if (radius > 0 && pitch > 0 && turns > 0 && tube_radius > 0) {\n    // Limit chord error to 0.03 mm or 3% of the ridge radius.\n    chord_error = min(0.03, tube_radius * 0.03);\n    steps_per_turn = max(48, ceil(180 / acos(1 - min(1, chord_error / radius))));\n    steps = ceil(turns * steps_per_turn);\n    for (i = [0:steps]) {\n      angle = handedness * 360 * turns * i / steps;\n      p = [radius * cos(angle), radius * sin(angle), pitch * turns * i / steps];\n      translate(p) sphere(r = tube_radius);\n      if (i < steps) {\n        next_angle = handedness * 360 * turns * (i + 1) / steps;\n        dx = radius * cos(next_angle) - p[0];\n        dy = radius * sin(next_angle) - p[1];\n        dz = pitch * turns / steps;\n        segment_length = sqrt(dx * dx + dy * dy + dz * dz);\n        translate(p)\n          rotate([0, acos(dz / segment_length), atan2(dy, dx)])\n            cylinder(h = segment_length, r = tube_radius);\n      }\n    }\n  }\n}\n\nPARAMETERS\n- Make important top-level constants user-adjustable with OpenSCAD Customizer comments:\n  - Numbers with ranges: body_radius = 12; // [4:0.5:40]\n  - Counts: leg_count = 4; // [2:8]\n  - Booleans: show_base = true;\n  - Options: style = \"round\"; // [round, sharp, chunky]\n- Prefer stable size/count/ratio/style controls; keep fragile dependent dimensions as local expressions.\n\nSUPPORTED SUBSET\n- Export is best-effort from a supported CSG subset: cube, sphere, cylinder, translate, rotate, color, union, difference, intersection, and goop.\n- difference() cutters become subtractive primitives, so use clean cutters that fully pass through the target solid.\n- Unsupported OpenSCAD may validate but can warn or skip during export; prefer the supported subset above.";

package/dist/capabilities/openscad-instructions.js

@@ -19,6 +19,9 @@ At most four applied printability repairs are allowed per logical build/edit in
 do not bypass it by recreating the part. Unavailable thickness is not a pass. Report unresolved issues honestly.
 Build connected geometry and avoid features below 1.4 mm. OpenSCAD source dimensions use millimetres,
 independently of the scene display unit. New parts are centered and grounded from compiled bounds.
+OpenSCAD is Z-up; the scene-editing API is Y-up. For an unrotated part at its creation-time scale and an identity parent transform,
+a source point [x,y,z] mm maps to scene {x:y, y:z, z:-x} times the unitMultiplier returned by scene.read(), plus nodeGetPos(partId).
+Account for the part and parent transforms when they are not identity; source coordinates are not scene coordinates.
 After a major change, use the scene screenshot API and emitImage to inspect the applied result.
 A committed effect can survive later failure. Inspect receipts and the existing part before retrying.
 Do not print source in the final answer unless requested; describe the result and any unresolved diagnostics.
@@ -32,7 +35,7 @@ RUNTIME
 - Do not use scale(); size primitives directly instead.
 - Use color("#rrggbb") around distinct visible parts.
 - Keep the model centered near the origin and use millimeter-like units consistently.
-- For organic blending, use goop(amount) { ... }. It is ordered: the first child seeds with blend 0, and each later child blends using amount.
+- For organic blending, use goop(radius_mm) { ... }. The radius is in millimetres before parent scaling, matching scene-editing; do not multiply by project unitMultiplier. It is ordered: the first child seeds with blend 0, and each later child uses radius_mm.
 - Put core primitives first. Avoid wrapping goop children in union() when they should blend individually.
 
 SCREWS AND THREADS

package/dist/capabilities/scene.d.ts

@@ -1,6 +1,9 @@
+import type { CameraConfiguration } from "@womp/kakapo-sdk";
 import type { ArtifactRef, SparkCapability, SparkInvocationContext } from "../capabilities.js";
 import type { WompSceneDraft } from "./scene-draft.js";
+import { type SceneHealth } from "../scene-health.js";
 export type SceneSnapshot = {
+    health: SceneHealth;
     revision: string;
     projectId?: number;
     unitMultiplier: number;
@@ -12,16 +15,21 @@ export type SceneSnapshot = {
     }[];
 };
 export type SceneScreenshotOptions = {
-    targetId?: number;
-    view?: "front" | "back" | "left" | "right" | "top" | "bottom" | "isometric";
+    /** Position/target and orthographic width use Womp scene coordinates and current project units. */
+    camera?: CameraConfiguration;
 };
 export type WompSceneApi = {
     read(): Promise<SceneSnapshot>;
+    health(objectIds?: number[]): Promise<SceneHealth>;
     edit<T>(callback: (draft: WompSceneDraft) => T | Promise<T>, expectedRevision: string): Promise<T>;
     screenshot(options?: SceneScreenshotOptions): Promise<ArtifactRef>;
 };
+export interface SceneHealthHost {
+    read(objectIds: number[], context: SparkInvocationContext): Promise<SceneHealth>;
+}
 export interface SceneHost {
-    read(context: SparkInvocationContext): Promise<SceneSnapshot>;
+    read(context: SparkInvocationContext): Promise<Omit<SceneSnapshot, "health">>;
+    health?: SceneHealthHost["read"];
     edit<T>(callback: (draft: WompSceneDraft) => T | Promise<T>, expectedRevision: string, context: SparkInvocationContext): Promise<T>;
     screenshot(options: SceneScreenshotOptions, context: SparkInvocationContext): Promise<ArtifactRef>;
 }

package/dist/capabilities/scene.js

@@ -1,17 +1,30 @@
 import { z } from "zod";
 import { WOMP_SCENE_DECLARATIONS } from "../generated/scene-declarations.js";
+import { unverifiedSceneHealth } from "../scene-health.js";
+const cameraVector = z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).strict();
 const screenshotOptions = z.object({
-    targetId: z.number().int().optional(),
-    view: z.enum(["front", "back", "left", "right", "top", "bottom", "isometric"]).optional(),
-});
+    camera: z.object({
+        position: cameraVector,
+        target: cameraVector,
+        projection: z.enum(["perspective", "orthographic"]).optional(),
+        horizontalFovDegrees: z.number().finite().optional(),
+        orthographicWidth: z.number().finite().positive().optional(),
+    }).strict().optional(),
+}).strict();
 export function createSceneCapability(host) {
     return {
         skills: [
             {
                 name: "scene-editing",
-                version: "5",
+                version: "10",
                 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. Call scene.edit(callback, expectedRevision)
+                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 is a scene hierarchy limit, not measured Boolean depth.
+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.
@@ -19,42 +32,90 @@ Preserve the existing scene unless asked to remove or replace content. Use seman
 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.
-Area size is a dimensionless scale; Group size stays fixed at one. Light size has x/y dimensions.
-Blend and mirror goop use millimetres regardless of project units. V1/V2 curve transforms are read-only;
+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.
+nodeSetUnionResolution(unionId, resolution) sets Area/Union resolution, not child-part resolution, and clamps to 0.01–0.65. Material emission ranges from 0 to 1.
+Blend and mirror goop are radii in millimetres before parent scaling, regardless of project units. nodeSetBlend clamps to 0–500 mm.
+V1/V2 curve transforms are read-only;
 edit their points instead. Handles and closure are available only on V3 Bezier curves.
-Rotations use degrees and 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.
+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: the current FlowIR API does not expose native SetMaterial/SetMaterialIndex.
+Report that limitation without replacing a parametric graph with ordinary primitives. 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 geometry.
 Create primitives, curves, and text inside Areas/Unions. Respect tree order for subtraction and intersection.
-Use groups for organization and unions for blended masses. Build silhouette and proportions before detail.
-For organic joins, overlap primitives and use appropriate blend; keep crisp accessories separate.
+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). 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; round controls rounding, not size.
+Build and verify coarse geometry and unfamiliar operations before replicating details. Check one representative result, then repeat it.
+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 with nodeSetMaterialId or curvePointSetMaterialId. Await the import before returning from the edit; a failed import rolls back the draft.
-Filter large read results with JavaScript and print only useful details. Never dump the entire scene by default.
-After a major edit, capture a screenshot outside the transaction and emitImage its reference. To inspect a
-new object, frame its owning Area with screenshot({ targetId: areaId, view: 'isometric' }); omit these options
-to preserve the current camera view. Do not change a locked camera without the user's instruction. Verify silhouette,
-connections, openings, proportions, and materials before claiming completion. Renderer bounds and resize calls
+For library materials, use listSuperMaterials(), then await materialImport(name) inside scene.edit and assign the returned numeric ID with nodeSetMaterialId or curvePointSetMaterialId. 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 are preserved. The camera changes immediately and remains active; there is no auto-fit.
+screenshot() keeps the active camera. Do not change a locked camera without the user's instruction. 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.
 A failed script can retain earlier committed effects. Use receipts and inspect unknown outcomes before retrying.`,
                 declarations: WOMP_SCENE_DECLARATIONS,
                 examples: [
+                    "const snapshot = await womp.scene.read(); print(snapshot.health);",
+                    "print(await womp.scene.health([objectId]));",
                     "const snapshot = await womp.scene.read(); print(snapshot.nodes.filter(node => /body/i.test(node.name)));",
-                    "const snapshot = await womp.scene.read(); const diameter = 20 * snapshot.unitMultiplier; const result = await womp.scene.edit(scene => { const areaId = scene.nodeCreate(scene.NodeType.Union, 0); const bodyId = scene.nodeCreate(scene.NodeType.Primitive, areaId); scene.nodeSetName(bodyId, '20 mm orange sphere'); scene.nodeSetPrimType(bodyId, scene.PrimitiveType.Sphere); scene.nodeSetSize(bodyId, { x: diameter, y: diameter, z: diameter }); scene.nodeSetPos(bodyId, { x: 0, y: diameter / 2, z: 0 }); const materialId = scene.materialCreate(); scene.materialSetColor(materialId, { r: 255, g: 128, b: 0 }); scene.nodeSetMaterialId(bodyId, materialId); return { areaId, bodyId }; }, snapshot.revision); print(result); await emitImage(await womp.scene.screenshot({ targetId: result.areaId, view: 'isometric' }));",
+                    "const snapshot = await womp.scene.read(); const diameter = 20 * snapshot.unitMultiplier; const result = await womp.scene.edit(scene => { const areaId = scene.nodeCreate(scene.NodeType.Union, 0); const bodyId = scene.nodeCreate(scene.NodeType.Primitive, areaId); scene.nodeSetName(bodyId, '20 mm orange sphere'); scene.nodeSetPrimType(bodyId, scene.PrimitiveType.Sphere); scene.nodeSetSize(bodyId, { x: diameter, y: diameter, z: diameter }); scene.nodeSetPos(bodyId, { x: 0, y: diameter / 2, z: 0 }); const materialId = scene.materialCreate(); scene.materialSetColor(materialId, { r: 255, g: 128, b: 0 }); scene.nodeSetMaterialId(bodyId, materialId); return { areaId, bodyId }; }, snapshot.revision); print(result); await emitImage(await womp.scene.screenshot({ camera: { position: { x: diameter * 2, y: diameter * 1.5, z: diameter * 2 }, target: { x: 0, y: diameter / 2, z: 0 }, projection: 'perspective', horizontalFovDegrees: 60 } }));",
                 ],
             },
         ],
-        createApi: (context) => ({
-            read: () => host.read(context),
-            edit: (callback, expectedRevision) => {
-                if (typeof callback !== "function")
-                    throw new Error("scene.edit requires a callback.");
-                return host.edit(callback, z.string().min(1).parse(expectedRevision), context);
-            },
-            screenshot: (options) => host.screenshot(screenshotOptions.parse(options ?? {}), context),
-        }),
+        createApi: (context) => {
+            const health = async (objectIds) => {
+                const ids = z.array(z.number().int().positive()).default([]).parse(objectIds);
+                context.signal.throwIfAborted();
+                if (!host.health)
+                    return unverifiedSceneHealth([], "This host does not provide scene health services.");
+                try {
+                    const result = await host.health(ids, context);
+                    context.signal.throwIfAborted();
+                    return result;
+                }
+                catch (error) {
+                    context.signal.throwIfAborted();
+                    return unverifiedSceneHealth([], `Scene health unavailable: ${String(error)}`);
+                }
+            };
+            return {
+                read: async () => ({ ...await host.read(context), health: await health() }),
+                health,
+                edit: (callback, expectedRevision) => {
+                    if (typeof callback !== "function")
+                        throw new Error("scene.edit requires a callback.");
+                    return host.edit(callback, z.string().min(1).parse(expectedRevision), context);
+                },
+                screenshot: (options) => host.screenshot(screenshotOptions.parse(options ?? {}), context),
+            };
+        },
     };
 }

package/dist/capabilities.d.ts

@@ -14,8 +14,7 @@ export type { AccountHost, AccountRead, AccountSection, AccountScope, AccountRes
 export type { KnowledgeAnswer, KnowledgeHost, WompKnowledgeApi, } from "./capabilities/knowledge.js";
 export { createOpenScadCapability } from "./capabilities/openscad.js";
 export { createGeometryCapability } from "./capabilities/geometry.js";
-export { createSceneHealthCapability } from "./capabilities/health.js";
-export type { SceneHealthHost, WompHealthApi } from "./capabilities/health.js";
+export type { SceneHealthHost } from "./capabilities/scene.js";
 export { createFlowCapability } from "./capabilities/flow.js";
 export type { FlowHost, FlowSnapshot, FlowWrite, FlowWriteResult, WompFlowApi, } from "./capabilities/flow.js";
 export type { GeometryHost, GeometryTarget, GeometryInstance, GeometryParamValue, GeometryWrite, GeometryWriteResult, WompGeometryApi, } from "./capabilities/geometry.js";

package/dist/capabilities.js

@@ -5,7 +5,6 @@ export { createOperationsCapability } from "./capabilities/operations.js";
 export { createAssetsCapability } from "./capabilities/assets.js";
 export { createOpenScadCapability } from "./capabilities/openscad.js";
 export { createGeometryCapability } from "./capabilities/geometry.js";
-export { createSceneHealthCapability } from "./capabilities/health.js";
 export { createFlowCapability } from "./capabilities/flow.js";
 /** The enabled bindings are also the only source of discoverable skills. */
 export function composeCapabilities(capabilities) {

package/dist/client.d.ts

@@ -10,6 +10,7 @@ export type SparkChatTransportOptions = {
     headers?: HeadersResolver;
     fetch?: typeof globalThis.fetch;
     getSettings?: () => SparkRunSettings;
+    onRun?: (run: SparkRun) => void;
 };
 export declare class SparkChatTransport implements ChatTransport<SparkUIMessage> {
     private readonly api;
@@ -17,6 +18,7 @@ export declare class SparkChatTransport implements ChatTransport<SparkUIMessage>
     private readonly headers?;
     private readonly fetchImplementation;
     private readonly getSettings?;
+    private readonly onRun?;
     private readonly activeRuns;
     constructor(options: SparkChatTransportOptions);
     sendMessages(options: {
@@ -36,6 +38,9 @@ export declare class SparkChatTransport implements ChatTransport<SparkUIMessage>
         title?: string;
     }): Promise<SparkConversation>;
     getConversation(id: string): Promise<SparkConversation>;
+    getRun(id: string): Promise<SparkRun>;
+    saveConversationSettings(id: string, settings: SparkRunSettings): Promise<void>;
+    deleteConversation(id: string): Promise<void>;
     listConversations(): Promise<SparkConversationSummary[]>;
     private settingsFrom;
     private openRunStream;

package/dist/client.js

@@ -27,6 +27,7 @@ export class SparkChatTransport {
     headers;
     fetchImplementation;
     getSettings;
+    onRun;
     activeRuns = new Map();
     constructor(options) {
         this.api = options.api.replace(/\/$/u, "");
@@ -34,6 +35,7 @@ export class SparkChatTransport {
         this.headers = options.headers;
         this.fetchImplementation = options.fetch ?? globalThis.fetch.bind(globalThis);
         this.getSettings = options.getSettings;
+        this.onRun = options.onRun;
     }
     async sendMessages(options) {
         const message = options.messageId === undefined
@@ -56,6 +58,7 @@ export class SparkChatTransport {
             throw await responseError(response);
         const body = await response.json();
         this.activeRuns.set(options.chatId, body.run.id);
+        this.onRun?.(body.run);
         return this.openRunStream(body.run.id, options.abortSignal, options.headers);
     }
     async reconnectToStream(options) {
@@ -107,6 +110,25 @@ export class SparkChatTransport {
         const body = await response.json();
         return body.conversation;
     }
+    async getRun(id) {
+        const response = await this.request(`/runs/${encodeURIComponent(id)}`, { method: "GET" });
+        if (!response.ok)
+            throw await responseError(response);
+        return (await response.json()).run;
+    }
+    async saveConversationSettings(id, settings) {
+        const response = await this.request(`/conversations/${encodeURIComponent(id)}/settings`, {
+            method: "PATCH", body: JSON.stringify(settings),
+        });
+        if (response.ok === false)
+            throw await responseError(response);
+    }
+    async deleteConversation(id) {
+        const response = await this.request(`/conversations/${encodeURIComponent(id)}`, { method: "DELETE" });
+        if (response.ok === false)
+            throw await responseError(response);
+        this.activeRuns.delete(id);
+    }
     async listConversations() {
         const response = await this.request("/conversations", { method: "GET" });
         if (response.ok === false)

package/dist/coordinates.d.ts

@@ -1,9 +1,5 @@
 import type { Transform, Vec3 } from "@womp/kakapo-sdk";
 export declare const INTERNAL_UNITS_PER_MM: number;
-export declare const WOMP_BLEND_MULTIPLIER = 55;
-export declare const MAX_ENGINE_BLEND = 500;
-export declare const MAX_GOOP_MM: number;
-export declare const MAX_MIRROR_GOOP_MM = 1000;
 export declare function sceneUnitMultiplier(value: unknown): number;
 export declare function toEnginePosition(value: Vec3, unitMultiplier?: number): Vec3;
 export declare function fromEnginePosition(value: Vec3, unitMultiplier?: number): Vec3;
@@ -15,9 +11,6 @@ export declare function toEngineTransform(input: {
     rotation?: Vec3;
     dimensions?: Vec3;
 }): Partial<Transform>;
-export declare function toEngineBlend(goopMm: number): number;
-export declare function fromEngineBlend(blend: number): number;
-export declare function toEngineMirrorGoop(goopMm: number): number;
 export type MirrorAxis = "x" | "y" | "z";
 export declare function toEngineMirrorRotation(axis: MirrorAxis): Vec3;
 export declare function fromEngineMirrorRotation(rotation: Vec3): MirrorAxis | undefined;

package/dist/coordinates.js

@@ -1,8 +1,5 @@
+import { xyzRotationMatrix, xyzRotationFromMatrix } from "@womp/kakapo-sdk";
 export const INTERNAL_UNITS_PER_MM = 1 / 25;
-export const WOMP_BLEND_MULTIPLIER = 55;
-export const MAX_ENGINE_BLEND = 500;
-export const MAX_GOOP_MM = MAX_ENGINE_BLEND / WOMP_BLEND_MULTIPLIER;
-export const MAX_MIRROR_GOOP_MM = 1000;
 const BASIS = [
     [0, 0, -1],
     [0, 1, 0],
@@ -50,21 +47,8 @@ export function fromEngineDimensions(value, unitMultiplier = 1) {
     };
 }
 export function convertRotationBasis(value) {
-    // Womp and Kakapo compose and extract Euler angles in XZY order.
-    const x = value.x * Math.PI / 180;
-    const y = value.y * Math.PI / 180;
-    const z = value.z * Math.PI / 180;
-    const a = Math.cos(x);
-    const b = Math.sin(x);
-    const c = Math.cos(y);
-    const d = Math.sin(y);
-    const e = Math.cos(z);
-    const f = Math.sin(z);
-    const source = [
-        [c * e, -f, d * e],
-        [a * c * f + b * d, a * e, a * d * f - b * c],
-        [b * c * f - a * d, b * e, b * d * f + a * c],
-    ];
+    // Both typed APIs use XYZ. Only change basis here; the SDK owns native XZY conversion.
+    const source = xyzRotationMatrix(value);
     const multiply = (left, right) => {
         const cell = (row, column) => left[row][0] * right[0][column] +
             left[row][1] * right[1][column] +
@@ -76,19 +60,7 @@ export function convertRotationBasis(value) {
         ];
     };
     const converted = multiply(multiply(BASIS, source), BASIS);
-    const convertedZ = Math.asin(Math.min(1, Math.max(-1, -converted[0][1])));
-    const nearGimbalLock = Math.abs(converted[0][1]) >= 0.9999999;
-    const convertedX = nearGimbalLock
-        ? Math.atan2(-converted[1][2], converted[2][2])
-        : Math.atan2(converted[2][1], converted[1][1]);
-    const convertedY = nearGimbalLock
-        ? 0
-        : Math.atan2(converted[0][2], converted[0][0]);
-    return {
-        x: clean(convertedX * 180 / Math.PI),
-        y: clean(convertedY * 180 / Math.PI),
-        z: clean(convertedZ * 180 / Math.PI),
-    };
+    return xyzRotationFromMatrix(converted);
 }
 export function toEngineTransform(input) {
     return {
@@ -97,15 +69,6 @@ export function toEngineTransform(input) {
         ...(input.dimensions ? { scale: toEngineDimensions(input.dimensions) } : {}),
     };
 }
-export function toEngineBlend(goopMm) {
-    return Math.min(MAX_ENGINE_BLEND, Math.max(0, goopMm * WOMP_BLEND_MULTIPLIER));
-}
-export function fromEngineBlend(blend) {
-    return blend / WOMP_BLEND_MULTIPLIER;
-}
-export function toEngineMirrorGoop(goopMm) {
-    return Math.min(MAX_MIRROR_GOOP_MM, Math.max(0, goopMm)) * WOMP_BLEND_MULTIPLIER;
-}
 export function toEngineMirrorRotation(axis) {
     if (axis === "x")
         return { x: 0, y: 90, z: 0 };
@@ -114,13 +77,11 @@ export function toEngineMirrorRotation(axis) {
     return { x: 0, y: 180, z: 0 };
 }
 export function fromEngineMirrorRotation(rotation) {
-    const x = rotation.x * Math.PI / 180;
-    const y = rotation.y * Math.PI / 180;
-    const z = rotation.z * Math.PI / 180;
+    const matrix = xyzRotationMatrix(rotation);
     const engineNormal = {
-        x: Math.cos(y) * Math.cos(z),
-        y: Math.cos(x) * Math.sin(z) + Math.sin(x) * Math.cos(z) * Math.sin(y),
-        z: Math.sin(x) * Math.sin(z) - Math.cos(x) * Math.cos(z) * Math.sin(y),
+        x: matrix[0][0],
+        y: matrix[1][0],
+        z: matrix[2][0],
     };
     const publicNormal = {
         x: -engineNormal.z,