@womp/spark-agent 4.3.0 → 4.4.0

package/dist/capabilities/scene.js

@@ -37,7 +37,7 @@ export function createSceneCapability(host) {
         skills: [
             {
                 name: "scene-editing",
-                version: "30",
+                version: "39",
                 description: "Inspect the open scene and edit its objects, materials, curves, and environment.",
                 instructions: `Read the scene first and keep its revision and object IDs. read() includes health.
 Use womp.scene.health() to refresh whole-scene health or womp.scene.health(objectIds) to check specific objects (mapped to their owning Areas).
@@ -62,7 +62,7 @@ Point defaults: position/rotation/handles zero, profile size {x:1,y:1,z:1} in pr
 Removing all points is supported. One point renders a single profile primitive, not a path.
 Curves render sampled profiles, not a continuous sweep. For smooth curves, start with nodeSetDensity(curveId, 250) and nodeSetBlend(curveId, 3).
 Density increases sampling and primitive cost; the 3 mm blend softens joins, not sample positions. Adjust blend to preserve thin features and the intended silhouette; these settings do not guarantee continuity.
-nodeSetUnionResolution(unionId, resolution) sets Area/Union resolution, not child-part resolution, and clamps to 0.01–0.65; higher values increase detail and voxel cost. Material emission ranges from 0 to 1.
+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.
@@ -81,21 +81,26 @@ 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. Use unions for blended masses.
+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 uses x as outer diameter and y as tube thickness. For these four primitives, nodeSetSize accepts {x, y}; z follows x even when supplied. Cube uses all three dimensions. Node and curve-point round are dimensionless fractions clamped to [0, 1], not radii in project units; rounding does not set size. Cube rounding reaches half its shortest dimension at 1, so a shallow Cube retains broad flat faces rather than becoming an ellipsoid.
-Build and verify coarse geometry and unfamiliar operations before replicating details. Check one representative result, then repeat it.
-Reference fidelity:
+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.
 For primitives, nodeSetBlend joins against all accumulated preceding geometry in the Area, not only the nearest part. A Union's blend affects its outer join, not joins between its children; top-level Area blend does not smooth its contents.
-For organic joins, overlap primitives and tune blend on the joining children while preserving intended gaps; keep crisp accessories separate.
+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.
@@ -109,7 +114,7 @@ Omitted projection/lens settings come from the active camera. Pass the camera ag
 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;
+connections, openings, proportions, and materials before claiming completion. Use the owning top-level Area for scene-space bounds;
 OpenSCAD part bounds are local to the part; individual primitive and curve bounds are unsupported. Renderer bounds and resize calls
 must finish before subsequent writes. Inside scene.edit, complete renderer-backed bounds reads before the first
 draft mutation; the SDK rejects them once the draft is dirty. Inspect committed results when renderer state has not caught up.

package/dist/scene-metadata.js

@@ -4,21 +4,21 @@ export function metadataObject(value) {
         : {};
 }
 export function readMaterialMetadata(scene, id) {
-    return metadataObject(metadataObject(scene.getSceneExt().materialsExt)[String(id)]);
+    return metadataObject(metadataObject(scene.getSceneExt(["materialsExt"]).materialsExt)[String(id)]);
 }
 export function writeMaterialMetadata(scene, id, changes) {
-    const materials = metadataObject(scene.getSceneExt().materialsExt);
+    const materials = metadataObject(scene.getSceneExt(["materialsExt"]).materialsExt);
     scene.patchSceneExt([{
             op: "add",
             path: "/materialsExt",
             value: { ...materials, [id]: { ...metadataObject(materials[String(id)]), ...changes } },
-        }]);
+        }], { returnScene: false });
 }
 export function removeMaterialMetadata(scene, id) {
-    const materials = metadataObject(scene.getSceneExt().materialsExt);
+    const materials = metadataObject(scene.getSceneExt(["materialsExt"]).materialsExt);
     if (!Object.hasOwn(materials, id))
         return;
-    scene.patchSceneExt([{ op: "remove", path: `/materialsExt/${id}` }]);
+    scene.patchSceneExt([{ op: "remove", path: `/materialsExt/${id}` }], { returnScene: false });
 }
 export function shiftCurvePointMetadata(scene, curveId, index, direction) {
     const shift = (value) => {
@@ -35,7 +35,7 @@ export function shiftCurvePointMetadata(scene, curveId, index, direction) {
         }
         return result;
     };
-    const ext = scene.getSceneExt();
+    const ext = scene.getSceneExt([String(curveId), "perUserExt"]);
     const curve = metadataObject(ext[String(curveId)]);
     const points = shift(curve.pointsExt);
     if (direction === 1) {
@@ -45,7 +45,7 @@ export function shiftCurvePointMetadata(scene, curveId, index, direction) {
             name: `Point ${index + 1}`,
         };
     }
-    scene.patchSceneExt([{ op: "add", path: `/${curveId}`, value: { ...curve, pointsExt: points } }]);
+    scene.patchSceneExt([{ op: "add", path: `/${curveId}`, value: { ...curve, pointsExt: points } }], { returnScene: false });
     const users = metadataObject(ext.perUserExt);
     const updatedUsers = { ...users };
     let changed = false;
@@ -61,5 +61,5 @@ export function shiftCurvePointMetadata(scene, curveId, index, direction) {
         changed = true;
     }
     if (changed)
-        scene.patchSceneExt([{ op: "add", path: "/perUserExt", value: updatedUsers }]);
+        scene.patchSceneExt([{ op: "add", path: "/perUserExt", value: updatedUsers }], { returnScene: false });
 }

package/dist/sdk-scene-host.js

@@ -42,9 +42,7 @@ export function createSdkSceneDraft(api, scene, services) {
             });
             return material.id;
         },
-        requireNode: (id) => {
-            scene.getNode(id);
-        },
+        requireNode: (id) => scene.getNode(id),
         requireMaterial: (id) => {
             scene.getMaterial(id);
         },

package/dist/womp-scene-api.d.ts

@@ -1,4 +1,4 @@
-import type { FontFamily, KakapoAPI, NodeKind, SceneEdit, Vec2, Vec3 } from "@womp/kakapo-sdk";
+import type { FontFamily, KakapoAPI, KakapoNode, NodeKind, SceneEdit, Vec2, Vec3 } from "@womp/kakapo-sdk";
 import { type SceneHdr } from "./scene-environment.js";
 import { type MirrorAxis } from "./coordinates.js";
 export declare const NodeType: {
@@ -68,7 +68,7 @@ export type WompSceneApiContext = {
     importLibraryMaterial?(name: string): Promise<number>;
     getDefaultMaterialId(): number;
     fonts: FontFamily[];
-    requireNode(id: number): void;
+    requireNode(id: number): KakapoNode | void;
     trackNode(id: number): void;
     trackMaterial(id: number): void;
     untrackMaterial(id: number): void;

package/dist/womp-scene-api.js

@@ -200,8 +200,7 @@ export function createWompSceneApi(context) {
     const actualParent = (parentId) => (parentId === 0 ? context.rootId : parentId);
     const publicParent = (parentId) => parentId === null || parentId === context.rootId ? 0 : parentId;
     const requireNode = (id) => {
-        context.requireNode(id);
-        return scene.getNode(id);
+        return context.requireNode(id) ?? scene.getNode(id);
     };
     const requireEditableTransform = (id) => {
         const node = requireNode(id);
@@ -336,7 +335,7 @@ export function createWompSceneApi(context) {
             throw new Error("Name cannot be empty");
         if (Array.from(normalized).length > 120)
             throw new Error("Name is too long (max 120 characters)");
-        const curve = metadataObject(scene.getSceneExt()[String(curveId)]);
+        const curve = metadataObject(scene.getSceneExt([String(curveId)])[String(curveId)]);
         const points = metadataObject(curve.pointsExt);
         scene.patchSceneExt([{
                 op: "add",
@@ -348,7 +347,7 @@ export function createWompSceneApi(context) {
                         [index]: { ...metadataObject(points[String(index)]), name: normalized },
                     },
                 },
-            }]);
+            }], { returnScene: false });
     };
     const addCurvePoint = (curveId, point, pointIndex) => {
         const curve = requireCurve(curveId);
@@ -605,11 +604,11 @@ export function createWompSceneApi(context) {
         nodeGetPos: nodePosition,
         nodeGetLock: (id) => {
             requireNode(id);
-            return Boolean(metadataObject(scene.getSceneExt()[String(id)]).locked);
+            return Boolean(metadataObject(scene.getSceneExt([String(id)])[String(id)]).locked);
         },
         nodeSetLock: (id, locked) => {
             requireNode(id);
-            const current = metadataObject(scene.getSceneExt()[String(id)]);
+            const current = metadataObject(scene.getSceneExt([String(id)])[String(id)]);
             scene.patchSceneExt([{ op: "add", path: `/${id}`, value: { ...current, locked: Boolean(locked) } }]);
         },
         nodeSetPos: (id, position) => {
@@ -849,7 +848,7 @@ export function createWompSceneApi(context) {
         },
         curvePointGetName: (curveId, pointIndex) => {
             const index = requirePoint(curveId, pointIndex);
-            const points = metadataObject(metadataObject(scene.getSceneExt()[String(curveId)]).pointsExt);
+            const points = metadataObject(metadataObject(scene.getSceneExt([String(curveId)])[String(curveId)]).pointsExt);
             const name = metadataObject(points[String(index)]).name;
             return typeof name === "string" ? name : `Point ${index + 1}`;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",
@@ -110,7 +110,7 @@
     "@ai-sdk/openai": "4.0.63",
     "@jitl/quickjs-wasmfile-release-sync": "0.32.0",
     "@womp/flowir": "0.3.0",
-    "@womp/kakapo-sdk": "0.4.0",
+    "@womp/kakapo-sdk": "0.5.0",
     "ai": "7.0.95",
     "eventsource-parser": "^3.0.6",
     "express": "^5.2.1",

package/.env.example

@@ -1,6 +0,0 @@
-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