@womp/spark-agent 4.4.1 → 5.0.1

package/README.md

@@ -6,7 +6,25 @@ 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 without options capture the current native viewport. Explicit `camera`
+  position/target, projection, `horizontalFovDegrees` and `orthographicWidth` are supported;
+  remove `targetId` and `view` presets. Camera distances use current project units.
+- 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
@@ -339,7 +357,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

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.`;

package/dist/capabilities/openscad.d.ts

@@ -6,13 +6,11 @@ export type OpenScadTarget = {
     title: string;
     source: string | null;
     params: Record<string, unknown>;
-    revision: string;
 };
 export type OpenScadSource = {
     source: string;
     title: string;
     params?: Record<string, unknown>;
-    expectedRevision: string;
 };
 export type OpenScadCreate = OpenScadSource & {
     parentId: number;
@@ -35,7 +33,6 @@ export type OpenScadPrintability = {
 export type OpenScadWriteResult = {
     status: "applied" | "rejected";
     objectId?: number;
-    revision: string;
     validation: OpenScadValidation;
     printability?: OpenScadPrintability;
     repairAttempts: number;

package/dist/capabilities/openscad.js

@@ -6,7 +6,6 @@ const source = z.object({
     source: z.string().trim().min(1),
     title: z.string().trim().min(1),
     params: z.record(z.string(), z.json()).optional(),
-    expectedRevision: z.string().min(1),
 });
 const create = source.extend({ parentId: nodeId }).strict();
 const update = source.extend({ objectId: nodeId.positive() }).strict();
@@ -21,7 +20,7 @@ export function createOpenScadCapability(host) {
                 declarations: WOMP_OPENSCAD_DECLARATIONS,
                 examples: [
                     "const part = await womp.openscad.read(objectId); print(part);",
-                    "const part = await womp.openscad.read(objectId); print(await womp.openscad.update({ objectId: part.objectId, source: part.source, title: part.title, params: { width: 30 }, expectedRevision: part.revision }));",
+                    "const part = await womp.openscad.read(objectId); print(await womp.openscad.update({ objectId: part.objectId, source: part.source, title: part.title, params: { width: 30 } }));",
                 ],
             },
         ],

package/dist/capabilities/scene.d.ts

@@ -3,8 +3,6 @@ import type { ArtifactRef, SparkCapability, SparkInvocationContext } from "../ca
 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;
     nodes: {
@@ -19,18 +17,16 @@ export type SceneScreenshotOptions = {
     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>;
+    access<T>(callback: (draft: WompSceneDraft) => T | Promise<T>): Promise<T>;
     screenshot(options?: SceneScreenshotOptions): Promise<ArtifactRef>;
 };
 export interface SceneHealthHost {
     read(objectIds: number[], context: SparkInvocationContext): Promise<SceneHealth>;
 }
 export interface SceneHost {
-    read(context: SparkInvocationContext): Promise<Omit<SceneSnapshot, "health">>;
     health?: SceneHealthHost["read"];
-    edit<T>(callback: (draft: WompSceneDraft) => T | Promise<T>, expectedRevision: string, context: SparkInvocationContext): Promise<T>;
+    access<T>(callback: (draft: WompSceneDraft) => T | Promise<T>, context: SparkInvocationContext): Promise<T>;
     screenshot(options: SceneScreenshotOptions, context: SparkInvocationContext): Promise<ArtifactRef>;
 }
 export declare function createSceneCapability(host: SceneHost): SparkCapability<WompSceneApi>;

package/dist/capabilities/scene.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { maxLightIntensity } from "@womp/kakapo-sdk";
 import { WOMP_SCENE_DECLARATIONS } from "../generated/scene-declarations.js";
 import { unverifiedSceneHealth } from "../scene-health.js";
-// A node id, as `scene.read()` publishes them: the scene root is 0, so a health
+// A node id, as `scene.access()` publishes them: the scene root is 0, so a health
 // read has to accept it. `openscad.ts` and `geometry.ts` spell an object id the
 // same way; `positive()` here refused an id this capability had just handed out.
 const objectId = z.number().int().nonnegative();
@@ -21,7 +21,7 @@ function readHealthObjectIds(objectIds) {
         ? objectIds.filter((value) => objectId.safeParse(value).success === false)
         : [objectIds];
     const named = invalid.slice(0, 3).map(display).join(", ");
-    throw new Error(`scene.health takes object ids from scene.read(): whole numbers from 0 up, in an array. ${named} ${invalid.length === 1 ? "is not one" : "are not ids"}.`);
+    throw new Error(`scene.health takes object ids from scene.access(): whole numbers from 0 up, in an array. ${named} ${invalid.length === 1 ? "is not one" : "are not ids"}.`);
 }
 const cameraVector = z.object({ x: z.number().finite(), y: z.number().finite(), z: z.number().finite() }).strict();
 const screenshotOptions = z.object({
@@ -38,35 +38,34 @@ export function createSceneCapability(host) {
         skills: [
             {
                 name: "scene-editing",
-                version: "42",
+                version: "45",
                 description: "Inspect the open scene and edit its objects, materials, curves, and environment.",
-                instructions: `Read the scene first and keep its revision and object IDs. read() includes health.
+                instructions: `Use womp.scene.access(callback) for both inspection and edits. Inspect targets inside each callback using scene.nodes({ name, type, parentId, ids, offset, limit }) and detailed getters; filters are optional, name is a case-insensitive substring, and results default to 100 (maximum 1000). Page with offset as needed. Inspection reflects changes made in the callback. scene.unitMultiplier gives project units. Do not reuse an earlier inspection as current state.
 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.
+Health is requested only through scene.health(); access does not request it automatically. It is renderer feedback, not proof that the latest edit finished evaluating. Request it when needed to verify the result.
 Unavailable, stale, or unverified feedback must not trigger blind regeneration or a claim that the model passed. Hosts without health services return unverified health with a reason.
 For confirmed primitive or depth overflow, repair the same target while preserving design, dimensions, active parameter overrides, and unrelated objects. At most two geometry repairs are allowed per target in one logical run.
 Empty Areas may be pending, intentionally empty, mesh-only, or failed. Overflow flags take precedence over possibly stale counts.
 max_total_depth reports the engine's tier-dependent nesting allowance, not measured depth. Compiled Boolean depth includes generated grouping; organizational Groups do not add a level. Use flag_depth_overflow to detect evaluator rejection.
-Call scene.edit(callback, expectedRevision)
-for one coherent undoable change. The callback receives a draft; all node/material/curve functions and enums
+Call scene.access(callback) for one coherent change or read-only inspection. 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.
+Do not start unrelated operations from inside an access. Draft handles expire when its callback returns. An unchanged draft does not submit or save anything.
 Preserve the existing scene unless asked to remove or replace content. Use semantic object names and reuse
 known IDs when editing rather than creating duplicates. Distances follow the current project's units
-(read().unitMultiplier is 1 for millimetres, 0.1 for centimetres, approximately 0.0393701 for inches).
-Convert a dimension in millimetres to project units by multiplying it by read().unitMultiplier.
+(scene.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 scene.unitMultiplier.
 The SDK-backed draft clamps dimension writes to 0.01–1000 mm per component before converting to native units; this is an adapter limit, not a scene-wide size limit. Read back dimensions when physical size matters.
 Area size is a dimensionless scale; Group size stays fixed at one. Lights must be created at root (parentId 0); their size has x/y dimensions.
-Light power is linear emitted intensity before collimation, not a percentage or physical unit: doubling it doubles emission, not tone-mapped pixel brightness. Valid ranges are 0–${maxLightIntensity("rect")} for Rect/Sphere and 0–${maxLightIntensity("distant")} for Distant; these limits are not brightness targets. A light-type change preserves intensity and rejects values outside the new type's range; lower intensity first if needed. Rect size is width/height; Sphere uses x as diameter; Distant uses direction, not position or size.
-Use nodeSetFacing(id, target - position) to aim light emission or the readable face of text/decals at a target in the same parent-local space. It keeps Y up (Z up for vertical directions); generic lookAt aligns a different axis and does not aim these faces.
-For text, nodeSetTextSize(id, {fontSize, depth}) sets font em size and extrusion in project units, not a bounding box. Layout width and additional letter spacing also use project units; spacing clamps to ±25 mm. Line height is a multiplier clamped to 0.5–3. The origin anchors the first baseline; alignment uses the layout width. Empty text clears its geometry.
-Decals require an existing loaded image and receiving geometry. Projection is a uniform cube: native scale.x (public size.z) controls all dimensions, not independent width/height/depth. Restriction to an Area requires that parent Area; root decals project globally. Missing image data can yield no projection even when no resource is pending.
+Light power is linear emitted intensity before collimation, not a percentage or physical unit: doubling it doubles emission, not tone-mapped pixel brightness. Valid ranges are 0–${maxLightIntensity("rect")} for Rect/Sphere and 0–${maxLightIntensity("distant")} for Distant; these limits are not brightness targets. A light-type change preserves intensity and rejects values outside the new type's range; lower intensity first if needed. Rect size is width/height; Sphere uses x as diameter; Distant uses direction, not position or size.
+Use nodeSetFacing(id, target - position) to aim light emission or the readable face of text/decals at a target in the same parent-local space. It keeps Y up (Z up for vertical directions); generic lookAt aligns a different axis and does not aim these faces.
+For text, nodeSetTextSize(id, {fontSize, depth}) sets font em size and extrusion in project units, not a bounding box. Layout width and additional letter spacing also use project units; spacing clamps to ±25 mm. Line height is a multiplier clamped to 0.5–3. The origin anchors the first baseline; alignment uses the layout width. Empty text clears its geometry.
+Decals require an existing loaded image and receiving geometry. Projection is a uniform cube: native scale.x (public size.z) controls all dimensions, not independent width/height/depth. Restriction to an Area requires that parent Area; root decals project globally. Missing image data can yield no projection even when no resource is pending.
 nodeCreate(Curve, parentId) creates an empty curve with zero blend. curvePointAdd(curveId, point, index?) returns the new index; omit index to append or supply an integer from 0 through point count to insert before that position.
 Point defaults: position/rotation/handles zero, profile size {x:1,y:1,z:1} in project units, the curve's material, fixed false, round 0. Pass {} for defaults.
 Removing all points is supported. One point renders a single profile primitive, not a path.
 Curves render sampled profiles, not a continuous sweep. For smooth curves, start with nodeSetDensity(curveId, 250) and nodeSetBlend(curveId, 3).
 Density increases sampling and primitive cost; the 3 mm blend softens joins, not sample positions. Adjust blend to preserve thin features and the intended silhouette; these settings do not guarantee continuity.
-nodeSetUnionResolution(unionId, resolution) sets a dimensionless detail level, clamped to 0.01–0.65: higher is finer and costs more voxels. Set the owning outermost Area, not a nested Union. Material emission ranges from 0 to 1.
+nodeSetUnionResolution(unionId, resolution) sets a dimensionless detail level, clamped to 0.01–0.65: higher is finer and costs more voxels. Set the owning outermost Area, not a nested Union. Material emission ranges from 0 to 1.
 nodeSetBlend and mirror goop take radii in millimetres before parent scaling, regardless of project units, and clamp to 0–500 mm. This does not apply to the FlowIR Boolean Blend port, which takes native units; geometry-nodes-reference gives its conversion.
 V1/V2 curve transforms are read-only;
 edit their points instead. Handles and closure are available only on V3 Bezier curves.
@@ -85,50 +84,51 @@ Never replace a parametric graph with ordinary primitives to color it. Ordinary
 nodeSetColor writes the node color field (used by lights); it does not replace a geometry object's material color.
 Do not recolor a shared material unless every object using it should change. Create and assign the material in the same edit as the scene geometry that uses it; a Geometry Nodes graph instead consumes a material ID created in an earlier edit.
 Create primitives, curves, and text inside Areas/Unions. Respect tree order for subtraction and intersection.
-Groups are organizational only; move and rotate their child Areas individually, not the Group.
-An Area is an outermost Union with no Union ancestor: it has its own modeller, bounds, and volumetric resolution. Nested Unions share that Area's resolution, even through Groups.
-Choose Area boundaries for evaluation needs, not individual editability: parts within an Area remain independently editable. Sibling Areas under a Group can overlap without blending together, while each blends internally and has independent resolution. Keep required shared smooth joins or Boolean evaluation within one Area; overlapping independent Areas are not a watertight Boolean union.
-Prioritize requested visual fidelity over minimizing voxel use. If correctly placed thin features render fragmented or missing, increase their owning Area's resolution, up to 0.65 as needed, and compare the same camera; distinguish sampling loss from material/lighting contrast or authored gaps. A higher voxel count is acceptable when detail improves within engine limits. If resolution is insufficient or hits resource limits/downscaling, consider smaller independent Areas where shared blending or Booleans are unnecessary.
+Groups are organizational only; move and rotate their child Areas individually, not the Group.
+An Area is an outermost Union with no Union ancestor: it has its own modeller, bounds, and volumetric resolution. Nested Unions share that Area's resolution, even through Groups.
+Choose Area boundaries for evaluation needs, not individual editability: parts within an Area remain independently editable. Sibling Areas under a Group can overlap without blending together, while each blends internally and has independent resolution. Keep required shared smooth joins or Boolean evaluation within one Area; overlapping independent Areas are not a watertight Boolean union.
+Prioritize requested visual fidelity over minimizing voxel use. If correctly placed thin features render fragmented or missing, increase their owning Area's resolution, up to 0.65 as needed, and compare the same camera; distinguish sampling loss from material/lighting contrast or authored gaps. A higher voxel count is acceptable when detail improves within engine limits. If resolution is insufficient or hits resource limits/downscaling, consider smaller independent Areas where shared blending or Booleans are unnecessary.
 Sphere uses size.x as uniform diameter (y/z do not stretch it), including new or resized spherical curve points. Cylinder/Cone/Pyramid use x as base diameter/width and y as height;
-Torus lies in local XZ (axis +Y), with x as outer diameter and y as tube thickness. For these four primitives, nodeSetSize accepts {x, y}; z follows x even when supplied. Cube uses all three dimensions. Node and curve-point round are dimensionless fractions clamped to [0, 1], not radii in project units; rounding does not set size. Cube rounding reaches half its shortest dimension at 1, so a shallow Cube retains broad flat faces rather than becoming an ellipsoid.
-Build and verify coarse geometry and unfamiliar operations before replicating details. Check one representative result, then repeat it.
-Construct both sides of a joint from shared attachment points and axes. Create each mounted part together with its contact or mounting geometry, derived from the supporting surface; preserve intended clearances and separate editability. If contact is uncertain, check the authored positions, dimensions, and axes in 3D: projected overlap is not a connection.
-Fix unintended gaps, floating attachments, and fragmented geometry before decorative detail or presentation. Use inspection to identify a concrete defect and verify its correction, not merely to collect screenshots or healthy receipts.
-Reference fidelity:
+Torus lies in local XZ (axis +Y), with x as outer diameter and y as tube thickness. For these four primitives, nodeSetSize accepts {x, y}; z follows x even when supplied. Cube uses all three dimensions. Node and curve-point round are dimensionless fractions clamped to [0, 1], not radii in project units; rounding does not set size. Cube rounding reaches half its shortest dimension at 1, so a shallow Cube retains broad flat faces rather than becoming an ellipsoid.
+Build and verify coarse geometry and unfamiliar operations before replicating details. Check one representative result, then repeat it.
+Construct both sides of a joint from shared attachment points and axes. Create each mounted part together with its contact or mounting geometry, derived from the supporting surface; preserve intended clearances and separate editability. If contact is uncertain, check the authored positions, dimensions, and axes in 3D: projected overlap is not a connection.
+Fix unintended gaps, floating attachments, and fragmented geometry before decorative detail or presentation. Use inspection to identify a concrete defect and verify its correction, not merely to collect screenshots or healthy receipts.
+Reference fidelity:
 When recreating an image, treat its visible geometry and level of detail as the target—not merely its subject, colors, or list of parts. Preserve the user's chosen workflow and editability requirements.
 Establish a comparison view matching the reference's angle, projection, and subject framing as closely as practical. Match silhouette, proportions, pose, and negative spaces first; then local contours, thickness, curvature, surface transitions, and defining details. Infer unseen geometry conservatively.
 Compare each rendered pass directly with the source. Identify the largest remaining visible shape mismatch, edit it, and verify that it improved before moving to smaller details. Use close-ups when the comparison view cannot resolve a feature; return to the comparison view afterward. Adjust sampling or resolution when visible faceting or segmentation requires it—not as a substitute for reshaping.
-Do not stop at semantic resemblance or after a fixed number of screenshots. Continue while substantial visible mismatches remain and supported edits are making progress, within the available budget. If progress stalls or the chosen representation cannot achieve the requested fidelity, explain the specific limitation and ask before changing workflows. Before finishing, compare the latest render with the reference and address the largest remaining visible mismatch; if substantial differences remain, identify the concrete stopping reason rather than treating an approximation disclaimer as completion.
+Do not stop at semantic resemblance or after a fixed number of screenshots. Continue while substantial visible mismatches remain and supported edits are making progress, within the available budget. If progress stalls or the chosen representation cannot achieve the requested fidelity, explain the specific limitation and ask before changing workflows. Before finishing, compare the latest render with the reference and address the largest remaining visible mismatch; if substantial differences remain, identify the concrete stopping reason rather than treating an approximation disclaimer as completion.
 
 nodeClone is shallow (no children). await cloneSubtree(id, { parentId?, name?, index? }) copies the complete hierarchy with fresh IDs,
 preserving local transforms, order and metadata, remapping internal references and sharing external materials/assets.
-Cloning requires a host transport with atomic scene patches; an unsupported host rejects it without changing the draft.
+Cloning stages changes in the draft and commits them with the rest of the access.
 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.
+For organic joins, overlap primitives and tune blend on the joining children while preserving intended gaps.
 Check font, HDR, and material catalogs before selecting names. A host can explicitly report a catalog as
 unavailable. Selecting an HDR resets its intensity; apply a custom intensity after selecting it.
-For library materials, use listSuperMaterials(), then await materialImport(name) inside scene.edit and assign the returned numeric ID the way that object requires: nodeSetMaterialId or curvePointSetMaterialId for scene nodes, the FlowIR SetMaterial node for a Geometry Nodes graph. A failed import rolls back the draft.
+For library materials, use listSuperMaterials(), then await materialImport(name) inside scene.access and assign the returned numeric ID the way that object requires: nodeSetMaterialId or curvePointSetMaterialId for scene nodes, the FlowIR SetMaterial node for a Geometry Nodes graph. A failed import rolls back the draft.
 Filter large read results with JavaScript and print only useful details.
 After a major edit, capture a screenshot outside the transaction and emitImage its reference.
-screenshot({ camera: { position: {x,y,z}, target: {x,y,z}, projection: 'perspective', horizontalFovDegrees: 60 } })
-sets a world-space camera in the same Womp coordinates and project units as scene positions (Y-up).
-For orthographic framing use projection: 'orthographic' and orthographicWidth in project units instead of FOV.
-Direction is derived from position/target; do not use coincident points or an exactly vertical viewing direction.
-Omitted projection/lens settings come from the active camera. Pass the camera again for repeatable captures.
-For object-focused screenshots, identify the requested object and frame it with an explicit camera position and target using its bounds; reuse established framing when appropriate. Choose a view that reveals the requested features without clipping the subject.
-Omitting camera captures the active viewport without auto-fit. Use it when the user asks about the current viewport or clearly refers to what is visible on screen, not on the assumption that it shows the requested object.
-Respect the host's camera-lock restrictions. Verify silhouette,
-connections, openings, proportions, and materials before claiming completion. Use the owning top-level Area for scene-space bounds;
+screenshot() captures the current Kakapo viewport without moving or fitting the camera.
+screenshot({ camera: { position: {x,y,z}, target: {x,y,z}, projection: 'perspective', horizontalFovDegrees: 60 } })
+sets a world-space camera in Womp scene coordinates and current project units (Y-up), and leaves it active.
+Use horizontalFovDegrees for perspective zoom, or projection: 'orthographic' with orthographicWidth in project units.
+Omitted projection/lens settings are preserved. Position and target are required together; avoid coincident points or an exactly vertical direction.
+Pass an explicit camera again for repeatable captures; targetId and view presets are not supported.
+Respect the host's camera-lock restrictions. Only claim visual verification for features visible in the captured view. 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
+must finish before subsequent writes. Inside scene.access, 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());",
                     "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({ camera: { position: { x: diameter * 2, y: diameter * 1.5, z: diameter * 2 }, target: { x: 0, y: diameter / 2, z: 0 }, projection: 'perspective', horizontalFovDegrees: 60 } }));",
+                    "print(await womp.scene.access(scene => scene.nodes({ name: 'body' })));",
+                    "const unit = await womp.scene.access(scene => scene.unitMultiplier); await emitImage(await womp.scene.screenshot({ camera: { position: { x: 100 * unit, y: 75 * unit, z: 100 * unit }, target: { x: 0, y: 0, z: 0 }, projection: 'perspective', horizontalFovDegrees: 60 } }));",
+                    "const unit = await womp.scene.access(scene => scene.unitMultiplier); await emitImage(await womp.scene.screenshot({ camera: { position: { x: 0, y: 25 * unit, z: 100 * unit }, target: { x: 0, y: 0, z: 0 }, projection: 'orthographic', orthographicWidth: 80 * unit } }));",
+                    "const result = await womp.scene.access(scene => { const diameter = 20 * scene.unitMultiplier; 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 }; }); print(result); await emitImage(await womp.scene.screenshot());",
                 ],
             },
         ],
@@ -149,12 +149,11 @@ A failed script can retain earlier committed effects. Use receipts and inspect u
                 }
             };
             return {
-                read: async () => ({ ...await host.read(context), health: await health() }),
                 health,
-                edit: (callback, expectedRevision) => {
+                access: (callback) => {
                     if (typeof callback !== "function")
-                        throw new Error("scene.edit requires a callback.");
-                    return host.edit(callback, z.string().min(1).parse(expectedRevision), context);
+                        throw new Error("scene.access requires a callback.");
+                    return host.access(callback, context);
                 },
                 screenshot: (options) => host.screenshot(screenshotOptions.parse(options ?? {}), context),
             };