@compilr-dev/sdk 0.39.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;
@@ -48,6 +48,11 @@ export type SceneOp =
     op: 'layers';
     layers: unknown;
 }
+/** Replace the lights (§20.5); `[]` restores the default studio light. */
+ | {
+    op: 'lights';
+    lights: unknown;
+}
 /** Whole-scene replace (scene_create, JSON import). */
  | {
     op: 'replace';
@@ -59,7 +64,7 @@ export type SceneEditSource = {
 } | {
     kind: 'user';
 };
-export type SceneChangeKind = 'moved' | 'resized' | 'rotated' | 'recoloured' | 'renamed' | 'removed' | 'added' | 'edited' | 'camera' | 'layers' | 'replaced';
+export type SceneChangeKind = 'moved' | 'resized' | 'rotated' | 'recoloured' | 'renamed' | 'removed' | 'added' | 'edited' | 'camera' | 'layers' | 'lights' | 'replaced';
 /** One journalled change (the writer stamps `rev`). */
 export interface SceneChange {
     rev: number;

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;
@@ -291,6 +317,43 @@ function setLayers(scene, layers) {
         warnings: [],
     };
 }
+/**
+ * Replace the lights.
+ *
+ * `[]` DELETES the field rather than storing an empty list, which is the difference between
+ * "the default studio light" and "no light at all" — an empty array would render a black scene
+ * and read in the JSON as if lighting had been configured.
+ */
+function setLights(scene, lights) {
+    if (!Array.isArray(lights)) {
+        return {
+            error: 'lights must be an array of { type: "sun" | "ambient", … } — or [] to go back to the default studio light.',
+        };
+    }
+    const probe = validateScene({ ...scene, lights: lights.length === 0 ? undefined : lights });
+    if (!probe.ok)
+        return { error: formatValidationErrors(probe.errors) };
+    const before = scene.lights ?? [];
+    const next = { ...scene };
+    if (lights.length === 0)
+        delete next.lights;
+    else
+        next.lights = probe.scene.lights;
+    const summary = lights.length === 0
+        ? 'Lights cleared — back to the default studio light.'
+        : `Lights set: ${lights
+            .map((l) => isRecord(l) && typeof l.type === 'string'
+            ? `${l.type} ${typeof l.intensity === 'number' ? String(l.intensity) : 'default'}`
+            : '?')
+            .join(', ')}.`;
+    return {
+        scene: next,
+        summary,
+        ids: [],
+        changes: [{ id: '', what: 'lights', from: before, to: lights }],
+        warnings: [],
+    };
+}
 function setCamera(scene, camera) {
     if (isRecord(camera) && camera.fit === true) {
         const rest = { ...scene };
@@ -335,6 +398,8 @@ export function applySceneOp(scene, op, opts) {
             return setCamera(scene, op.camera);
         case 'layers':
             return setLayers(scene, op.layers);
+        case 'lights':
+            return setLights(scene, op.lights);
         case 'replace': {
             const v = validateScene(op.scene);
             if (!v.ok)
@@ -431,6 +496,8 @@ function describeChange(c) {
             return 'changed the camera';
         case 'layers':
             return 'changed which layers can be hidden';
+        case 'lights':
+            return 'changed the lighting';
         case 'replaced':
             return 'replaced the whole scene';
         case 'edited':

package/dist/capabilities/packs.js

@@ -280,6 +280,7 @@ export const CAPABILITY_PACKS = {
             'scene_remove_object',
             'scene_set_camera',
             'scene_set_layers',
+            'scene_set_lights',
             'scene_screenshot',
         ],
         readOnly: false,

package/dist/platform/tools/scene-tools.d.ts

@@ -15,7 +15,7 @@
 import type { PlatformContext, PlatformToolsConfig } from '../context.js';
 import { type ISceneWriter } from '../scene-writer.js';
 import { type SceneFile } from '../../canvas/scene.js';
-export declare const SCENE_TOOL_NAMES: readonly ["scene_create", "scene_get", "scene_add_object", "scene_update_object", "scene_remove_object", "scene_set_camera", "scene_set_layers", "scene_screenshot"];
+export declare const SCENE_TOOL_NAMES: readonly ["scene_create", "scene_get", "scene_add_object", "scene_update_object", "scene_remove_object", "scene_set_camera", "scene_set_layers", "scene_set_lights", "scene_screenshot"];
 /**
  * "sofa · box · Sofa" rows, indented under their group parent; `#tag` suffixes when `withTags`.
  *
@@ -103,6 +103,9 @@ export declare function createSceneTools(config: PlatformToolsConfig, options?:
 }> | import("@compilr-dev/agents").Tool<{
     canvas_id: number;
     layers?: unknown;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    lights?: unknown;
 }> | import("@compilr-dev/agents").Tool<{
     canvas_id: number;
     width?: number;

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

@@ -14,7 +14,7 @@
  */
 import { defineTool, createErrorResult } from '@compilr-dev/agents';
 import { createSceneWriter } from '../scene-writer.js';
-import { SCENE_MAX_BATCH, SCENE_MAX_LAYERS, SCENE_OBJECT_TYPES, SCENE_LABEL_FACES, describeScene, serializeScene, } from '../../canvas/scene.js';
+import { SCENE_MAX_BATCH, SCENE_MAX_LAYERS, SCENE_OBJECT_TYPES, SCENE_MAX_LIGHTS, SCENE_MAX_SHADOW_LIGHTS, SCENE_LIGHT_INTENSITY_MAX, SCENE_LABEL_FACES, describeScene, serializeScene, } from '../../canvas/scene.js';
 import { describeLayers, emptyLayers, undeclaredTags } from '../../canvas/scene-layers.js';
 import { formatUserEditNotice, } from '../../canvas/scene-ops.js';
 export const SCENE_TOOL_NAMES = [
@@ -25,6 +25,7 @@ export const SCENE_TOOL_NAMES = [
     'scene_remove_object',
     'scene_set_camera',
     'scene_set_layers',
+    'scene_set_lights',
     'scene_screenshot',
 ];
 const DEFAULT_SHOT = { width: 1280, height: 800 };
@@ -232,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',
@@ -305,7 +309,13 @@ const OBJECT_PROPERTIES = {
             },
             emissiveIntensity: {
                 type: 'number',
-                description: '0–5, default 1. Does nothing without emissive. Past ~3 the colour clips to white.',
+                description: '0–5, default 1. Does nothing without emissive. ⚠️ MEASURED on a real scene: a sphere at ' +
+                    '1.5 loses its shading and reads as a flat disc, and a ring at 2 washes to near-white and ' +
+                    'loses its hue. Emission adds a flat colour OVER the shading, so the bigger or paler the ' +
+                    'object, the sooner it stops looking like a solid. Stay at or below ~0.3 for anything ' +
+                    'larger than a token and save the high end for small accents. Against a bright scene a ' +
+                    'glow reads poorly whatever the number — dim the scene with scene_set_lights rather than ' +
+                    'turning this up.',
             },
             wireframe: {
                 type: 'boolean',
@@ -531,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',
@@ -683,6 +696,56 @@ export function createSceneTools(config, options) {
         },
     });
     // ---------------------------------------------------------------------------
+    const sceneSetLightsTool = defineTool({
+        name: 'scene_set_lights',
+        description: "Replace a scene's lighting. Until this existed, lights could only be set at creation, so " +
+            'dimming a finished scene meant rebuilding every object in it. ' +
+            'Two kinds: { type: "ambient", intensity } is the overall fill — it also sets how much of ' +
+            'the room glossy and metallic surfaces reflect, so dropping it to 0 makes a genuinely dark ' +
+            'scene — and { type: "sun", position: [x, y, z], intensity, castShadow } is a directional ' +
+            'light that can cast shadows. [] goes back to the default studio light (ambient fill + one ' +
+            'sun from above-right), which is what most scenes want. ' +
+            `Up to ${String(SCENE_MAX_LIGHTS)} lights, ${String(SCENE_MAX_SHADOW_LIGHTS)} of them casting shadows ` +
+            '(each shadow costs a render pass). ⚠️ Lighting a scene darker makes emissive objects stand ' +
+            'out; it also makes everything else harder to read, so change it for a reason.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                lights: {
+                    type: 'array',
+                    maxItems: SCENE_MAX_LIGHTS,
+                    description: '[] restores the default studio light.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: { type: 'string', enum: ['sun', 'ambient'] },
+                            position: { ...VEC3, description: 'sun only: where it shines FROM, in metres.' },
+                            intensity: {
+                                type: 'number',
+                                description: `0–${String(SCENE_LIGHT_INTENSITY_MAX)}. The default studio light is ambient ~1 and sun ~1.6.`,
+                            },
+                            castShadow: { type: 'boolean', description: 'sun only. Default false.' },
+                        },
+                        required: ['type'],
+                    },
+                },
+            },
+            required: ['canvas_id', 'lights'],
+        },
+        execute: async (input) => {
+            try {
+                if (!Array.isArray(input.lights)) {
+                    return createErrorResult('lights must be an array of { type: "sun" | "ambient", … } — or [] to go back to the default studio light.');
+                }
+                return await applyAsAgent(input.canvas_id, [{ op: 'lights', lights: input.lights }], () => null);
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('set lights', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
     const sceneScreenshotTool = defineTool({
         name: 'scene_screenshot',
         description: 'RENDER a 3D scene and SEE it — check proportions, overlaps, gaps and floating objects after ' +
@@ -736,6 +799,7 @@ export function createSceneTools(config, options) {
         sceneRemoveObjectTool,
         sceneSetCameraTool,
         sceneSetLayersTool,
+        sceneSetLightsTool,
         sceneScreenshotTool,
     ];
 }

package/dist/team/tool-config.js

@@ -315,6 +315,7 @@ export const TOOL_GROUPS = {
             'scene_remove_object',
             'scene_set_camera',
             'scene_set_layers',
+            'scene_set_lights',
             'scene_screenshot',
         ],
         readOnly: false,

package/package.json

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