@compilr-dev/sdk 0.40.0 → 0.41.0

package/dist/canvas/scene-ops.d.ts

@@ -25,7 +25,7 @@ export type SceneOp =
     objects: SceneObjectInput[];
     index?: number;
 }
-/** Shallow merge; arrays replaced whole; `null` clears an optional field; id/type rejected. */
+/** Shallow merge; arrays replaced whole; `material` MERGES; `null` clears; id/type rejected. */
  | {
     op: 'update';
     id: string;

package/dist/canvas/scene-ops.js

@@ -171,6 +171,30 @@ function showVal(v) {
         return fmtVec(v);
     return JSON.stringify(v);
 }
+/**
+ * `material` MERGES, where every other object-valued field is replaced whole.
+ *
+ * ⚠️ IT USED TO REPLACE, AND THAT COST SOMEONE A SURFACE. A material is a bag of independent
+ * knobs — roughness, metalness, opacity, emissive, wireframe — so "make this glow" is naturally
+ * `{ material: { emissive: "#f59e0b" } }`, and under replace that ALSO reset the metalness and
+ * roughness that were there. Reported from real use: a ring patched to glow quietly lost its
+ * metal finish, and the agent only caught it because it re-read the scene. Nothing errored, and
+ * the patch did exactly what it said.
+ *
+ * Arrays still replace whole (a position is one value, not three independent ones). To clear a
+ * single knob, pass it as `null`; to clear the whole material, pass `material: null`, which is
+ * the same rule one level up.
+ */
+function mergeMaterial(before, patch) {
+    const base = isRecord(before) ? { ...before } : {};
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null)
+            Reflect.deleteProperty(base, k);
+        else
+            base[k] = clone(v);
+    }
+    return base;
+}
 function updateObject(scene, id, patch, opts) {
     const idx = scene.objects.findIndex((o) => o.id === id);
     if (idx < 0)
@@ -205,8 +229,10 @@ function updateObject(scene, id, patch, opts) {
         const from = before[k];
         if (v === null)
             Reflect.deleteProperty(next, k);
+        else if (k === 'material' && isRecord(v))
+            next[k] = mergeMaterial(before[k], v);
         else
-            next[k] = clone(v); // shallow merge: arrays and nested objects replaced whole
+            next[k] = clone(v); // shallow merge: arrays replaced whole
         const to = next[k];
         if (JSON.stringify(from) === JSON.stringify(to))
             continue;

package/dist/platform/tools/scene-tools.js

@@ -233,7 +233,10 @@ const OBJECT_PROPERTIES = {
         type: 'string',
         description: 'label only: the words to show (≤ 120, ONE line — no newline; use two labels). The scene is ' +
             'otherwise unlabelled solids, so name the rooms and the parts: a screenshot with no text in ' +
-            'it cannot be read back by you or by anyone else.',
+            'it cannot be read back by you or by anyone else. ⚠️ SIZE IT AGAINST WHAT IT NAMES: the text ' +
+            'is in METRES like everything else, so the 0.25 default is right for a desk and unreadable ' +
+            'across a building. Roughly a tenth of the thing it labels — a 4 m wall wants ~0.4, a whole ' +
+            'floor plan wants more. A label you have to zoom in to read is one nobody reads.',
     },
     background: {
         type: 'string',
@@ -538,7 +541,10 @@ export function createSceneTools(config, options) {
     const sceneUpdateObjectTool = defineTool({
         name: 'scene_update_object',
         description: 'Change fields of one object in a 3D scene. patch is a SHALLOW merge — arrays (position, size, ' +
-            'points, rotation) and material are replaced whole; null clears an optional field (e.g. group). ' +
+            'points, rotation) are replaced whole, since a position is one value and not three independent ' +
+            'ones. MATERIAL IS THE EXCEPTION: it merges, so { material: { emissive: "#f59e0b" } } adds a glow ' +
+            'and leaves the roughness, metalness and opacity that were already there. null clears an optional ' +
+            'field (group, or material itself); a null INSIDE material clears that one knob. ' +
             'id and type cannot change: remove the object and add it again. Read ids with scene_get first.',
         inputSchema: {
             type: 'object',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",