@womp/spark-agent 4.4.0 → 5.0.0

package/.env.example

@@ -0,0 +1,6 @@
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+KAKAPO_URL=ws://127.0.0.1:5502
+PORT=8787
+SPARK_STORAGE_PATH=.spark/spark.sqlite

package/README.md

@@ -6,7 +6,23 @@ Spark Agent uses AI SDK 7 `UIMessage` and `UIMessageChunk` as its public chat pr
 JavaScript uses the host's executor and capabilities. Native browser execution and isolated QuickJS
 execution use the same model loop. The host owns conversations, artifacts, authorization, and connections.
 
-## Requirements
+## Requirements
+
+### Migrating to 5.0
+
+- Replace scene capability `read`/`edit` with `access(callback)`. Inspect the current draft
+  through `scene.nodes({ ids, name, type, parentId, offset, limit })`, not a `nodes` array.
+  Results default to 100, with a maximum page size of 1,000.
+- Update custom scene hosts to `SceneHost.access` and SDK adapters to `acquireAccess`.
+  `onCommitted` receives the acknowledged scene; keep host access suspended until synchronization succeeds.
+- Remove scene revision arguments from Geometry/OpenSCAD writes. Current parameters and overrides
+  are prepared inside protected access. Hosts must still enforce connection/project ownership.
+- Screenshot calls capture the current native viewport; remove target, view and camera options.
+- Scene health is explicitly requested through `scene.health()`, not automatically after each edit.
+- This release requires Kakapo SDK 0.7.0. Native and QuickJS executors now allow 100,000 host calls
+  per execution. Receipts, cancellation, timeout limits and uncertain-outcome handling remain enforced.
+
+### Runtime
 
 - Node.js 22.13 or newer
 - AI SDK 7
@@ -102,11 +118,12 @@ A failed barrier aborts the loop. The default model-step limit is 100; a limit r
 
 Spark does not estimate or limit input tokens or automatically shorten conversation history.
 The provider enforces its context limit; rejections follow the normal provider-error path.
-Provider-reported usage and cost tracking are unchanged.
 
-Screenshot and file APIs return serializable artifact references. `emitImage` and `emitFile` resolve
-them through the host's artifact resolver. Keep references resolvable when reloading history, and
-pass `createSparkTools(...)` to AI SDK's `convertToModelMessages` to reconstruct multimodal results.
+Screenshot and file APIs return serializable artifact references. `emitImage` and `emitFile` resolve
+them through the host's artifact resolver. Keep references resolvable when reloading history, and
+pass `createSparkTools(...)` to AI SDK's `convertToModelMessages` to reconstruct multimodal results.
+`emitImage(artifact, { inspect: false })` displays an image without adding its bytes to model input,
+including restored history. Inspection is enabled by default.
 Kakapo skill declarations are generated from its actual typed API during the build and packaged as
 JavaScript strings; they do not need filesystem or Markdown loading in the browser.
 
@@ -142,9 +159,11 @@ const chat = useChat<SparkUIMessage>({
 ```
 
 Render `message.parts`. Standard AI SDK parts represent text, reasoning, files, tool inputs, tool
-outputs, approvals, and step boundaries. Spark adds typed `data-console`, `data-artifact`,
-`data-run-status`, `data-step-metrics`, and `data-execution-receipt` parts. Receipts are emitted before
-their storage barrier, keeping known effects visible even when saving the tool result fails.
+outputs, approvals, and step boundaries. Spark adds typed `data-console`, `data-artifact`,
+`data-run-status`, `data-step-metrics`, and `data-execution-receipt` parts. Receipts are emitted before
+their storage barrier, keeping known effects visible even when saving the tool result fails.
+Hosts can consume `data-tool-input-label` once the tool's label field is complete, while the
+remaining input is still streaming.
 
 An explicit Stop action must cancel the durable run before stopping local observation:
 
@@ -174,7 +193,7 @@ that turn, independently of the selector.
 
 Custom stores must implement `saveConversationSettings` as a settings-only update, and preserve
 stored settings during `saveConversation` so streaming history saves cannot overwrite preferences.
-The built-in memory and SQLite stores do this without a database migration.
+The built-in memory and SQLite stores implement this contract.
 
 The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
 
@@ -219,9 +238,17 @@ app.use(
 );
 ```
 
-`MemorySparkAgentStore` and `MemorySparkArtifactStore` are development implementations. Production
-hosts must supply durable implementations backed by their database/object storage and must preserve
-the ordering contract of `appendRunChunk()`.
+`MemorySparkAgentStore` and `MemorySparkArtifactStore` are development implementations. Production
+hosts must supply durable implementations backed by their database/object storage and must preserve
+the ordering contract of `appendRunChunk()`.
+
+`SparkAgentServiceOptions.endOrphanedRuns` defaults to `false`. Enable it only when one process
+owns the store: a message or Stop then ends unfinished runs not held by that process. On a shared
+store, enabling it could end another process's live run.
+
+Custom stores can implement `releaseActiveRun(conversationId, runId, updatedAt)` to clear the active
+run only if its ID still matches. Memory and SQLite stores implement it. Without it, the service
+serializes read-and-save release against its own submissions.
 
 ## Standalone development server
 
@@ -257,8 +284,8 @@ acknowledgement proves only renderer-local history, not durable backend storage.
 The standalone server persists conversations, run streams, and screenshot bytes in SQLite. Only
 one local process can execute against a database. After a terminated process is replaced, startup
 preserves recorded output and marks abandoned queued/running runs incomplete without replaying
-scene edits. Pending approvals remain pending. Full operation reconciliation and run continuation
-are still being integrated. Node 22 reports an experimental warning for its built-in SQLite module.
+scene edits. Pending approvals remain pending; startup does not resume abandoned runs.
+Node 22 reports an experimental warning for its built-in SQLite module.
 
 Set `SPARK_SCENE_IDENTITY` only when the host can verify that the value names the same durable
 scene across renderer reconnects. Without it, Spark uses a process-scoped identity and does not
@@ -267,9 +294,8 @@ authorize interrupted scene mutations to continue after a server restart.
 `createStandaloneSparkAgentApp(options)` is asynchronous. Await it before listening, and call
 `await app.dispose()` on shutdown to settle active runs and release storage ownership.
 
-This development branch currently installs `kakapo-sdk` from the sibling checkout. Run `yarn build`
-in `../kakapo-sdk` before installing Spark dependencies. A registry version must replace this local
-dependency before release; no new package has been published by this migration.
+When using a sibling `kakapo-sdk` dependency, run `yarn build` in `../kakapo-sdk` before installing
+Spark dependencies. Replace local dependencies with registry versions before publishing.
 
 For the explicit fictional account profile, use `yarn dev:demo-account` or
 `spark-agent --profile demo-account`. It adds the `account` skill and `womp.account.read`
@@ -329,7 +355,10 @@ The standalone host uses a fresh QuickJS runtime for each JavaScript execution.
 or browser globals and receives only the composed capability APIs. Imports, filesystem access,
 network APIs, and host environment variables are not exposed. QuickJS limits memory, stack size,
 execution time, source size, host calls, and data crossing the host bridge. Browser hosts can instead
-choose native page execution, with the page-global access and interruption limitations described above.
+choose native page execution, with the page-global access and interruption limitations described above.
+Both executors allow 100,000 host calls per execution by default; the counter resets for each
+execution. QuickJS supports overriding this through `maxHostCalls`. Cancellation, timeouts,
+and the other execution limits still apply.
 
 QuickJS isolates generated code from the JavaScript host API; it is not an operating-system security
 boundary. Multi-tenant deployments must additionally isolate workers, authorize every Kakapo
@@ -345,85 +374,17 @@ yarn test
 yarn web:build
 ```
 
-## Release procedure
-
-Releases use a manual package publication; no separate release service is required.
-
-### Migration to 0.3
-
-- The package root is browser-safe. Import `KakapoRuntime`, `createWompSceneApi`, and its enums
-  from `/kakapo`, and `QuickJSJavaScriptExecutor` from `/quickjs`.
-- `runSparkAgent` takes the host's selected model, executor, capability composition, artifact
-  resolver, and persistence hooks. The host owns connection setup and disposal. The model sees
-  only `read_skill` and `execute_javascript`; domain methods live under the supplied `womp` APIs.
-- Replace fixed scene/screenshot tool history with the host's history adapter. Use
-  `convertSparkMessages` when rebuilding model input from current Spark UI messages so artifact
-  references become model-visible content. Preserve old records; do not replay historical tools.
-- Custom server executors receive `uiMessages` and convert them using their actual capability
-  tools. `SparkRunExecutionContext.modelMessages` has been removed.
-- Custom JavaScript executors must honor cancellation and host-owned user waits. Callback-based
-  scene edits and artifact references work with both the native and QuickJS executors.
-
-### 4.1.0
-
-- `emitImage(artifact, { inspect: false })` displays an image without adding its bytes to model input, including restored history. Inspection remains the default.
-- Generation instructions use completed outputs directly and avoid redundant listing or emission; explicit inspection and follow-up imports remain supported.
-- Streamed tool labels are emitted only after their label field is complete. Hosts can consume `data-tool-input-label` while the rest of the input streams.
-- Server cancellation waits for active execution to settle before reporting its terminal state.
-- Includes the latest geometry material, scalar-port, and primitive improvements from main.
-
-### 4.2.2
-
-The published 4.2.1 was packed from the 4.2.0 sources and differs from 4.2.0 only in its version
-number, so none of the changes below are in it. Use 4.2.2.
-
-Compatible: both additions are optional, and a host that sets neither behaves as before except that a
-run whose progress cannot be stored now ends instead of staying `running`.
-
-- A run whose stream chunk, `running` status or ending cannot be stored ends `failed` with a sentence
-  instead of staying `running` until a restart. The final status and the conversation release are
-  retried in the background for about five minutes; a message or a Stop for that conversation stores
-  the ending at once.
-- `SparkAgentServiceOptions.endOrphanedRuns` (default `false`): a message or a Stop ends an unfinished
-  active run that no execution in this process holds, with "This run stopped unexpectedly and could
-  not be finished." Turn it on only when one process owns the store; on a shared store it would end
-  another process's live runs.
-- `SparkAgentStore.releaseActiveRun(conversationId, runId, updatedAt)` (optional): clears the active
-  run only while it still names that run. The memory and SQLite stores implement it. A store without
-  it has the read-and-save release serialised against the service's own submits, so a late retry
-  cannot overwrite a newer message.
-
-### 4.2.0
-
-Incompatible: a color that can only be a 0-1 one is now refused where it used to be stored as
-near-black, and the `scene-editing` skill payload changed. Hosts that pin the skill surface in a
-fixture must regenerate it.
-
-- Model-facing colors state their domain in the declared parameter name: `nodeSetColor`,
-  `materialSetColor`, `materialSetSecondaryColor`, `materialSetSubsurfaceColor` and
-  `setBackgroundColor` take `rgb255`, and the internal type is `Color255`. The `scene-editing` skill
-  version is 30.
-- A color whose every component is strictly between 0 and 1 and none an integer throws, naming the
-  0-255 conversion (`{r:0.2, g:0.4, b:0.6}` → "use `{r:51, g:102, b:153}` … or `{r:0, g:0, b:0}` for
-  black"). Nothing is auto-scaled: `{r:1, g:0, b:0}`, `{r:0, g:0, b:0}`, `{r:0.5, g:0, b:0}` and
-  every 0-255 color write exactly as before.
-- `scene.health` accepts the object ids `scene.read()` publishes, including `0`; a value that is not
-  an id is refused with a sentence naming it instead of a serialized schema error. Ids belonging to
-  no Area (the root, a root-level Group, a Light) are dropped and reported rather than making the
-  whole reading `unverified`.
-- A tool result can no longer cost a turn. Geometry diagnostics quote a source line once per line
-  and cap at 5 diagnostics and 4 KiB; the `execute_javascript` envelope bounds the error to 8 KiB and
-  the receipts to a 1 MiB model input, always as valid JSON. Only model input is bounded —
-  `persistence.afterToolCall`, the UI stream and the host's own receipts keep the original object.
-- A scene-health receipt keeps its totals, limits and overflow flags whole and bounds the per-Area
-  rows to 8, affected and overflowing Areas first, naming the omission in `reason`. Health read for a
-  decision (`hasGeometryOverflow`, `hasSceneResourcePressure`, `options.onHealth`) still sees every
-  row, so no repair decision changes. A consumer fixture that recorded a receipt with more than 8
-  Areas will differ.
-- `operations.generate` keeps a host's own cancellation message on a stopped generation instead of
-  replacing it with the bare abort reason.
-
-### Publishing
+## Release procedure
+
+Releases use a manual package publication; no separate release service is required.
+
+Versions follow **MAJOR.MINOR.PATCH** (for example, `4.4.0`):
+
+- **Major:** breaking changes.
+- **Minor:** backward-compatible new features.
+- **Patch:** backward-compatible bug fixes.
+
+### Publishing
 
 1. Choose an unused package version after checking `npm view @womp/spark-agent versions --json`.
    Update `package.json` and record public API changes and migration notes. Use a new minor version

package/dist/bench-camera.d.ts

@@ -0,0 +1,9 @@
+import type { KakapoAPI, Vec3, CameraConfiguration } from "@womp/kakapo-sdk";
+export type BenchBounds = {
+    min: Vec3;
+    max: Vec3;
+};
+/** Groups organize geometry; query their visible renderable children, not Group bounds. */
+export declare function benchGeometryIds(api: Pick<KakapoAPI, "listNodes">, parentId?: number): number[];
+/** Fixed Spark-space three-quarter view, fitted against all eight native-world bounding-box corners. */
+export declare function benchCamera(bounds: BenchBounds, aspect: number): CameraConfiguration;

package/dist/bench-camera.js

@@ -0,0 +1,32 @@
+import { toEnginePosition } from "./coordinates.js";
+/** Groups organize geometry; query their visible renderable children, not Group bounds. */
+export function benchGeometryIds(api, parentId = 0) {
+    return api.listNodes({ parentId }).flatMap(node => {
+        if (("hidden" in node && node.hidden) || node.kind === "light")
+            return [];
+        return node.kind === "group" ? benchGeometryIds(api, node.id) : [node.id];
+    });
+}
+/** Fixed Spark-space three-quarter view, fitted against all eight native-world bounding-box corners. */
+export function benchCamera(bounds, aspect) {
+    const axes = ["x", "y", "z"];
+    if (!Number.isFinite(aspect) || aspect <= 0 || axes.some(a => !Number.isFinite(bounds.min[a]) || !Number.isFinite(bounds.max[a]) || bounds.min[a] > bounds.max[a]))
+        throw new Error("Benchmark framing requires finite ordered bounds and a positive aspect ratio.");
+    const target = { x: (bounds.min.x + bounds.max.x) / 2, y: (bounds.min.y + bounds.max.y) / 2, z: (bounds.min.z + bounds.max.z) / 2 };
+    const offset = toEnginePosition({ x: 1, y: 0.65, z: 1 });
+    const length = Math.hypot(offset.x, offset.y, offset.z);
+    const back = { x: offset.x / length, y: offset.y / length, z: offset.z / length };
+    const horizontal = Math.hypot(back.x, back.z);
+    const right = { x: back.z / horizontal, y: 0, z: -back.x / horizontal };
+    const up = { x: -back.x * back.y / horizontal, y: horizontal, z: -back.z * back.y / horizontal };
+    const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+    const tanH = Math.tan(Math.PI / 6);
+    let distance = 0.1;
+    for (const x of [bounds.min.x, bounds.max.x])
+        for (const y of [bounds.min.y, bounds.max.y])
+            for (const z of [bounds.min.z, bounds.max.z]) {
+                const point = { x: x - target.x, y: y - target.y, z: z - target.z };
+                distance = Math.max(distance, dot(point, back) + 1.1 * Math.max(Math.abs(dot(point, right)) / tanH, Math.abs(dot(point, up)) * aspect / tanH));
+            }
+    return { position: { x: target.x + back.x * distance, y: target.y + back.y * distance, z: target.z + back.z * distance }, target, projection: "perspective", horizontalFovDegrees: 60 };
+}

package/dist/bounded-output.js

@@ -1,18 +1,5 @@
-// 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.
+// Bound the full serialized tool result, including errors and receipts, before
+// handing it to the model. Oversized diagnostics are cut and labelled.
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 export const MODEL_RESULT_BYTE_LIMIT = 1024 * 1024;
@@ -37,10 +24,11 @@ export function truncateUtf8(text, limit) {
  * incomplete rather than wrong.
  */
 export function boundedText(text, limit, label) {
-    const total = byteLength(text);
+    const bytes = encoder.encode(text);
+    const total = bytes.byteLength;
     if (total <= limit)
         return text;
-    const kept = truncateUtf8(text, limit);
+    const kept = decoder.decode(bytes.subarray(0, limit)).replace(/�$/u, "");
     return `${kept}\n[${label} truncated at ${limit} bytes; ${total - byteLength(kept)} bytes omitted.]`;
 }
 /**
@@ -67,12 +55,13 @@ export function boundedResultText(output, limit = MODEL_RESULT_BYTE_LIMIT) {
         if (receipt.details === undefined)
             return receipt;
         const details = asText(receipt.details);
-        if (byteLength(details) <= detailsLimit)
+        const detailsBytes = byteLength(details);
+        if (detailsBytes <= 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.`,
+                omitted: `This receipt's details were ${detailsBytes} bytes, over the ${detailsLimit} byte limit for one receipt in a tool result. Read the receipt from the host if the outcome matters.`,
             },
         };
     });

package/dist/capabilities/geometry.d.ts

@@ -17,13 +17,11 @@ export type GeometryTarget = {
     instanceId?: number;
     source: string | null;
     instances: GeometryInstance[];
-    revision: string;
     diagnostics: string[];
 };
 export type GeometryWrite = {
     objectId: number;
     source: string;
-    expectedRevision: string;
 };
 export type GeometryWriteResult = {
     status: "applied" | "rejected";
@@ -31,7 +29,6 @@ export type GeometryWriteResult = {
     graphId?: number;
     instanceId?: number;
     affectedObjectIds: number[];
-    revision: string;
     diagnostics: string[];
 };
 export type WompGeometryApi = {

package/dist/capabilities/geometry.js

@@ -5,7 +5,6 @@ const write = z
     .object({
     objectId,
     source: z.string().trim().min(1),
-    expectedRevision: z.string().min(1),
 })
     .strict();
 export function createGeometryCapability(host, reference) {
@@ -15,26 +14,26 @@ 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, parametric organic/procedural geometry, or animation.
+                instructions: `Use womp.geometry for requested Geometry Nodes, parametric organic/procedural geometry, or animation.
 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.
+Read geometry-nodes-reference before writing source. Supply the complete FlowIR text after inspecting the target. JavaScript calls execute JavaScript; source is a FlowIR string, not JavaScript or JSON.
+Inspect the current target before replacing its graph; preserve unrelated geometry and parameter overrides.
 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.
+Obtain that ID from the scene-editing skill inside one scene.access, 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.
+Create or import the material inside scene.access before writing the geometry target, 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: [
                     "const target = await womp.geometry.read(objectId); print(target);",
-                    "const target = await womp.geometry.read(objectId); print(await womp.geometry.write({ objectId: target.objectId, source: editedFlowIR, expectedRevision: target.revision }));",
-                    "const materialId = await womp.scene.edit(scene => { const id = scene.materialCreate(); scene.materialSetName(id, 'Red'); scene.materialSetColor(id, { r: 255, g: 0, b: 0 }); return id; }, (await womp.scene.read()).revision); const target = await womp.geometry.read(0); const source = ['param Float size = 20.0 min=1 max=100 step=1', 'node box Primitive Type=Cube Position=Vec3(0.0,0.0,0.0) Rotation=Vec3(0.0,0.0,0.0) Size=size Roundness=0.0', `node painted SetMaterial Material=${materialId} Geometry=box.Geometry`, 'out Geometry=painted.Geometry'].join('\\n'); print(await womp.geometry.write({ objectId: target.objectId, source, expectedRevision: target.revision }));",
+                    "const target = await womp.geometry.read(objectId); print(await womp.geometry.write({ objectId: target.objectId, source: editedFlowIR }));",
+                    "const materialId = await womp.scene.access(scene => { const id = scene.materialCreate(); scene.materialSetName(id, 'Red'); scene.materialSetColor(id, { r: 255, g: 0, b: 0 }); return id; }); const target = await womp.geometry.read(0); const source = ['param Float size = 20.0 min=1 max=100 step=1', 'node box Primitive Type=Cube Position=Vec3(0.0,0.0,0.0) Rotation=Vec3(0.0,0.0,0.0) Size=size Roundness=0.0', `node painted SetMaterial Material=${materialId} Geometry=box.Geometry`, 'out Geometry=painted.Geometry'].join('\\n'); print(await womp.geometry.write({ objectId: target.objectId, source }));",
                 ],
             },
             {

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

@@ -1 +1 @@
-export declare const OPENSCAD_INSTRUCTIONS = "Use womp.openscad to create or update one adjustable CAD part. Read an existing part before editing it.\nKeep follow-up edits to an existing CAD part in that part unless the user asks to change representation.\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. 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 CAD part. Read an existing part before editing it.\nKeep follow-up edits to an existing CAD part in that part unless the user asks to change representation.\nread(0) returns the root container 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.\nPreserve intervening user changes. Ask the user when the intended edits conflict or remain ambiguous.\nExisting 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 scene.unitMultiplier inside the access callback, 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. 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

@@ -1,82 +1,81 @@
-export const OPENSCAD_INSTRUCTIONS = `Use womp.openscad to create or update one adjustable CAD part. Read an existing part before editing it.
-Keep follow-up edits to an existing CAD part in that part unless the user asks to change representation.
-read(0) returns the root container and a scene revision for creation. read(id) returns an existing
-part or container. Use the scene-editing skill when available to discover other scene objects.
-create requires a parentId (0 means the scene root); update requires the existing objectId.
-Both methods compile the effective source and parameters, apply one undoable change, and check wall thickness.
-A stale revision requires reading again and adapting the edit while preserving intervening user changes.
-Ask the user only when the intended edits conflict or remain ambiguous; never reuse the old replacement
-with a refreshed revision token. Existing overrides are preserved for parameters still present;
-params supplies overrides to merge into the current values. Keep top-level parameter names stable.
-Return complete source on every update and preserve unrelated geometry. Never create a replacement to repair a part.
-Compile errors return status rejected without applying. Creation requires validated placement bounds.
-An update may apply with validation unavailable; that is a diagnostic, not proof that it compiles.
-An applied part remains in the scene even if thickness fails or is unavailable. Use the returned objectId for repairs.
-When thickness fails, increase thin walls and fragile connections while preserving requested dimensions and openings.
-At most four applied printability repairs are allowed per logical build/edit in this run. Respect the returned limit;
-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.
-
-RUNTIME
-- Produce a single OpenSCAD file.
-- Do not use imports, includes, external libraries, text, hull, minkowski, polyhedron, or extrudes.
-- Prefer cube, sphere, cylinder, translate, rotate, color, union, difference, and intersection.
-- Do not use $fn, $fa, or $fs; tessellation controls are ignored.
-- Build faceted geometry by combining supported primitives with CSG operations and transforms.
-- 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(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
-- Copy helical_ridge below for rounded screw threads, necks, caps, and coils. It joins spheres with cylinders; never use stacked rings or disconnected spheres.
-- Dimensions are mm: radius = ridge centerline radius; pitch = axial travel/turn; tube_radius = half ridge thickness; handedness = 1 (right) or -1 (left).
-- For a hand control use thread_hand = 1; // [-1:Left, 1:Right] and pass it directly. Ternary expressions (?:) are unsupported.
-- 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.
-- 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.
-- Build heads/grips separately using cylinders, tapered cylinders, and radial ribs/cutters, not thread samples.
-
-module helical_ridge(radius, pitch, turns, tube_radius, handedness) {
-  if (radius > 0 && pitch > 0 && turns > 0 && tube_radius > 0) {
-    // Limit chord error to 0.03 mm or 3% of the ridge radius.
-    chord_error = min(0.03, tube_radius * 0.03);
-    steps_per_turn = max(48, ceil(180 / acos(1 - min(1, chord_error / radius))));
-    steps = ceil(turns * steps_per_turn);
-    for (i = [0:steps]) {
-      angle = handedness * 360 * turns * i / steps;
-      p = [radius * cos(angle), radius * sin(angle), pitch * turns * i / steps];
-      translate(p) sphere(r = tube_radius);
-      if (i < steps) {
-        next_angle = handedness * 360 * turns * (i + 1) / steps;
-        dx = radius * cos(next_angle) - p[0];
-        dy = radius * sin(next_angle) - p[1];
-        dz = pitch * turns / steps;
-        segment_length = sqrt(dx * dx + dy * dy + dz * dz);
-        translate(p)
-          rotate([0, acos(dz / segment_length), atan2(dy, dx)])
-            cylinder(h = segment_length, r = tube_radius);
-      }
-    }
-  }
-}
-
-PARAMETERS
-- Make important top-level constants user-adjustable with OpenSCAD Customizer comments:
-  - Numbers with ranges: body_radius = 12; // [4:0.5:40]
-  - Counts: leg_count = 4; // [2:8]
-  - Booleans: show_base = true;
-  - Options: style = "round"; // [round, sharp, chunky]
-- Prefer stable size/count/ratio/style controls; keep fragile dependent dimensions as local expressions.
-
-SUPPORTED SUBSET
-- Export is best-effort from a supported CSG subset: cube, sphere, cylinder, translate, rotate, color, union, difference, intersection, and goop.
-- difference() cutters become subtractive primitives, so use clean cutters that fully pass through the target solid.
+export const OPENSCAD_INSTRUCTIONS = `Use womp.openscad to create or update one adjustable CAD part. Read an existing part before editing it.
+Keep follow-up edits to an existing CAD part in that part unless the user asks to change representation.
+read(0) returns the root container for creation. read(id) returns an existing
+part or container. Use the scene-editing skill when available to discover other scene objects.
+create requires a parentId (0 means the scene root); update requires the existing objectId.
+Both methods compile the effective source and parameters, apply one undoable change, and check wall thickness.
+Preserve intervening user changes. Ask the user when the intended edits conflict or remain ambiguous.
+Existing overrides are preserved for parameters still present;
+params supplies overrides to merge into the current values. Keep top-level parameter names stable.
+Return complete source on every update and preserve unrelated geometry. Never create a replacement to repair a part.
+Compile errors return status rejected without applying. Creation requires validated placement bounds.
+An update may apply with validation unavailable; that is a diagnostic, not proof that it compiles.
+An applied part remains in the scene even if thickness fails or is unavailable. Use the returned objectId for repairs.
+When thickness fails, increase thin walls and fragile connections while preserving requested dimensions and openings.
+At most four applied printability repairs are allowed per logical build/edit in this run. Respect the returned limit;
+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 scene.unitMultiplier inside the access callback, 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.
+
+RUNTIME
+- Produce a single OpenSCAD file.
+- Do not use imports, includes, external libraries, text, hull, minkowski, polyhedron, or extrudes.
+- Prefer cube, sphere, cylinder, translate, rotate, color, union, difference, and intersection.
+- Do not use $fn, $fa, or $fs; tessellation controls are ignored.
+- Build faceted geometry by combining supported primitives with CSG operations and transforms.
+- 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(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
+- Copy helical_ridge below for rounded screw threads, necks, caps, and coils. It joins spheres with cylinders; never use stacked rings or disconnected spheres.
+- Dimensions are mm: radius = ridge centerline radius; pitch = axial travel/turn; tube_radius = half ridge thickness; handedness = 1 (right) or -1 (left).
+- For a hand control use thread_hand = 1; // [-1:Left, 1:Right] and pass it directly. Ternary expressions (?:) are unsupported.
+- 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.
+- 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.
+- Build heads/grips separately using cylinders, tapered cylinders, and radial ribs/cutters, not thread samples.
+
+module helical_ridge(radius, pitch, turns, tube_radius, handedness) {
+  if (radius > 0 && pitch > 0 && turns > 0 && tube_radius > 0) {
+    // Limit chord error to 0.03 mm or 3% of the ridge radius.
+    chord_error = min(0.03, tube_radius * 0.03);
+    steps_per_turn = max(48, ceil(180 / acos(1 - min(1, chord_error / radius))));
+    steps = ceil(turns * steps_per_turn);
+    for (i = [0:steps]) {
+      angle = handedness * 360 * turns * i / steps;
+      p = [radius * cos(angle), radius * sin(angle), pitch * turns * i / steps];
+      translate(p) sphere(r = tube_radius);
+      if (i < steps) {
+        next_angle = handedness * 360 * turns * (i + 1) / steps;
+        dx = radius * cos(next_angle) - p[0];
+        dy = radius * sin(next_angle) - p[1];
+        dz = pitch * turns / steps;
+        segment_length = sqrt(dx * dx + dy * dy + dz * dz);
+        translate(p)
+          rotate([0, acos(dz / segment_length), atan2(dy, dx)])
+            cylinder(h = segment_length, r = tube_radius);
+      }
+    }
+  }
+}
+
+PARAMETERS
+- Make important top-level constants user-adjustable with OpenSCAD Customizer comments:
+  - Numbers with ranges: body_radius = 12; // [4:0.5:40]
+  - Counts: leg_count = 4; // [2:8]
+  - Booleans: show_base = true;
+  - Options: style = "round"; // [round, sharp, chunky]
+- Prefer stable size/count/ratio/style controls; keep fragile dependent dimensions as local expressions.
+
+SUPPORTED SUBSET
+- Export is best-effort from a supported CSG subset: cube, sphere, cylinder, translate, rotate, color, union, difference, intersection, and goop.
+- difference() cutters become subtractive primitives, so use clean cutters that fully pass through the target solid.
 - Unsupported OpenSCAD may validate but can warn or skip during export; prefer the supported subset above.`;