@compilr-dev/sdk 0.33.1 → 0.34.0

package/dist/canvas/index.d.ts

@@ -6,6 +6,7 @@ export * from './types.js';
 export * from './validate.js';
 export * from './scene.js';
 export * from './scene-ops.js';
+export * from './scene-layers.js';
 export { parseColor, relativeLuminance, contrastRatio, oklabLightness, lightnessDeltaPct, isNeutral, hueAngle, AA_TEXT, SURFACE_DELTA_MIN, SURFACE_DELTA_TARGET, SURFACE_DELTA_MAX, HAIRLINE_MIN_PCT, HAIRLINE_MAX_PCT, } from './color.js';
 export type { Rgb } from './color.js';
 export { runQualityChecks, checkSurfaceTokens, checkTextContrast, checkHueCount, checkDeadTweaks, primaryVarNames, } from './quality-checks.js';

package/dist/canvas/index.js

@@ -11,6 +11,7 @@ export * from './validate.js';
 */
 export * from './scene.js';
 export * from './scene-ops.js';
+export * from './scene-layers.js';
 /*
   ⚠️ Renderer-safe on purpose. Both modules are pure arithmetic with no imports beyond
   each other, so Desktop's renderer can use them for the surface ramp without pulling the

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

@@ -0,0 +1,57 @@
+/**
+ * Scene layers → the Tweaks panel (3d-canvas-spec §18).
+ *
+ * A scene's control manifest is DERIVED from `scene.layers`, never stored on the canvas row:
+ * one source of truth, so a toggle cannot drift from the scene that declares it. What IS stored
+ * is the row's `values` — `layer_exterior: false` — because which layers are showing is the
+ * user's view state, not a change to the model. That split is the whole point of §18.2: hiding a
+ * wall to look inside must not bump the rev, enter the undo journal, or tell the agent the user
+ * edited the scene.
+ */
+import type { ControlManifest, ParamValue } from './types.js';
+import type { SceneFile, SceneObject } from './scene.js';
+/** The panel group every layer toggle sits in. */
+export declare const LAYER_GROUP = "Layers";
+/**
+ * `exterior` → `layer_exterior`, `load-bearing` → `layer_load_bearing`.
+ *
+ * ⚠️ `PARAM_RE` (canvas/validate.ts) is `/^[a-zA-Z_][a-zA-Z0-9_]*$/`, so the obvious
+ * `layer:exterior` fails manifest validation — hence the prefix and the `-` → `_` mapping. Tags
+ * forbid underscores (`SCENE_TAG_PATTERN`) precisely so this stays reversible: without that,
+ * `load-bearing` and `load_bearing` would both land on `layer_load_bearing`.
+ */
+export declare function layerParam(tag: string): string;
+/** The inverse of `layerParam`; null for any other param. Unambiguous — see the note there. */
+export declare function layerTagFromParam(param: string): string | null;
+/** One toggle per declared layer, in declaration order. Empty when the scene declares none. */
+export declare function sceneControlManifest(scene: SceneFile): ControlManifest;
+/** Does this scene have anything to tweak? Drives whether the host shows the panel at all. */
+export declare function sceneHasLayers(scene: SceneFile): boolean;
+/** Every tag actually carried by an object, in first-seen order. */
+export declare function sceneTags(scene: SceneFile): string[];
+/**
+ * Tags objects carry that no layer declares — metadata, not controls.
+ *
+ * Reported by `scene_get` so the agent can see that a label it has been applying is not yet
+ * togglable, rather than wondering why the user has no switch for it.
+ */
+export declare function undeclaredTags(scene: SceneFile): string[];
+/** Layers declared with no object carrying the tag — a control that governs nothing, yet. */
+export declare function emptyLayers(scene: SceneFile): string[];
+/**
+ * The tags currently switched OFF, from the row's values.
+ *
+ * A layer with no entry in `values` falls back to its declared default, so a scene read before
+ * the user has touched anything hides exactly what the agent asked to be hidden.
+ */
+export declare function hiddenTags(scene: SceneFile, values: Record<string, ParamValue> | undefined): Set<string>;
+/**
+ * Is this object hidden in its own right?
+ *
+ * Only its OWN tags: a hidden ancestor hides its subtree through the renderer's node tree
+ * (three.js propagates `visible`), so walking the ancestry here would double-count and would
+ * disagree with what is drawn.
+ */
+export declare function isTagHidden(object: SceneObject, hidden: ReadonlySet<string>): boolean;
+/** One line for `scene_get`'s header: `exterior (on), glazing (off)`, or null when there are none. */
+export declare function describeLayers(scene: SceneFile, values?: Record<string, ParamValue>): string | null;

package/dist/canvas/scene-layers.js

@@ -0,0 +1,94 @@
+/** The panel group every layer toggle sits in. */
+export const LAYER_GROUP = 'Layers';
+/**
+ * `exterior` → `layer_exterior`, `load-bearing` → `layer_load_bearing`.
+ *
+ * ⚠️ `PARAM_RE` (canvas/validate.ts) is `/^[a-zA-Z_][a-zA-Z0-9_]*$/`, so the obvious
+ * `layer:exterior` fails manifest validation — hence the prefix and the `-` → `_` mapping. Tags
+ * forbid underscores (`SCENE_TAG_PATTERN`) precisely so this stays reversible: without that,
+ * `load-bearing` and `load_bearing` would both land on `layer_load_bearing`.
+ */
+export function layerParam(tag) {
+    return `layer_${tag.replace(/-/g, '_')}`;
+}
+/** The inverse of `layerParam`; null for any other param. Unambiguous — see the note there. */
+export function layerTagFromParam(param) {
+    if (!param.startsWith('layer_'))
+        return null;
+    const tag = param.slice('layer_'.length).replace(/_/g, '-');
+    return tag.length > 0 ? tag : null;
+}
+/** One toggle per declared layer, in declaration order. Empty when the scene declares none. */
+export function sceneControlManifest(scene) {
+    const controls = (scene.layers ?? []).map((l) => ({
+        type: 'toggle',
+        param: layerParam(l.tag),
+        label: l.label,
+        default: l.visible ?? true,
+        group: LAYER_GROUP,
+    }));
+    return { controls };
+}
+/** Does this scene have anything to tweak? Drives whether the host shows the panel at all. */
+export function sceneHasLayers(scene) {
+    return (scene.layers ?? []).length > 0;
+}
+/** Every tag actually carried by an object, in first-seen order. */
+export function sceneTags(scene) {
+    const out = [];
+    for (const o of scene.objects) {
+        for (const t of o.tags ?? [])
+            if (!out.includes(t))
+                out.push(t);
+    }
+    return out;
+}
+/**
+ * Tags objects carry that no layer declares — metadata, not controls.
+ *
+ * Reported by `scene_get` so the agent can see that a label it has been applying is not yet
+ * togglable, rather than wondering why the user has no switch for it.
+ */
+export function undeclaredTags(scene) {
+    const declared = new Set((scene.layers ?? []).map((l) => l.tag));
+    return sceneTags(scene).filter((t) => !declared.has(t));
+}
+/** Layers declared with no object carrying the tag — a control that governs nothing, yet. */
+export function emptyLayers(scene) {
+    const used = new Set(sceneTags(scene));
+    return (scene.layers ?? []).map((l) => l.tag).filter((t) => !used.has(t));
+}
+/**
+ * The tags currently switched OFF, from the row's values.
+ *
+ * A layer with no entry in `values` falls back to its declared default, so a scene read before
+ * the user has touched anything hides exactly what the agent asked to be hidden.
+ */
+export function hiddenTags(scene, values) {
+    const hidden = new Set();
+    for (const layer of scene.layers ?? []) {
+        const raw = values?.[layerParam(layer.tag)];
+        const on = raw === undefined ? (layer.visible ?? true) : raw === true || raw === 'true' || raw === 1;
+        if (!on)
+            hidden.add(layer.tag);
+    }
+    return hidden;
+}
+/**
+ * Is this object hidden in its own right?
+ *
+ * Only its OWN tags: a hidden ancestor hides its subtree through the renderer's node tree
+ * (three.js propagates `visible`), so walking the ancestry here would double-count and would
+ * disagree with what is drawn.
+ */
+export function isTagHidden(object, hidden) {
+    return (object.tags ?? []).some((t) => hidden.has(t));
+}
+/** One line for `scene_get`'s header: `exterior (on), glazing (off)`, or null when there are none. */
+export function describeLayers(scene, values) {
+    const layers = scene.layers ?? [];
+    if (layers.length === 0)
+        return null;
+    const hidden = hiddenTags(scene, values);
+    return layers.map((l) => `${l.tag} (${hidden.has(l.tag) ? 'off' : 'on'})`).join(', ');
+}

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

@@ -43,6 +43,11 @@ export type SceneOp =
         fit: true;
     };
 }
+/** Replace the whole layer list (§18); `[]` clears it, so the scene has no Tweaks panel. */
+ | {
+    op: 'layers';
+    layers: unknown;
+}
 /** Whole-scene replace (scene_create, JSON import). */
  | {
     op: 'replace';
@@ -54,7 +59,7 @@ export type SceneEditSource = {
 } | {
     kind: 'user';
 };
-export type SceneChangeKind = 'moved' | 'resized' | 'rotated' | 'recoloured' | 'renamed' | 'removed' | 'added' | 'edited' | 'camera' | 'replaced';
+export type SceneChangeKind = 'moved' | 'resized' | 'rotated' | 'recoloured' | 'renamed' | 'removed' | 'added' | 'edited' | 'camera' | 'layers' | 'replaced';
 /** One journalled change (the writer stamps `rev`). */
 export interface SceneChange {
     rev: number;

package/dist/canvas/scene-ops.js

@@ -259,6 +259,38 @@ function removeObject(scene, id, opts) {
         removed,
     };
 }
+/**
+ * Replace `scene.layers` (§18). The shape is checked by the final `validateScene`, like every
+ * other op; this only rejects what would otherwise be stored as a non-list.
+ *
+ * ⚠️ This changes which toggles EXIST, not which are on — that is the canvas row's `values` and
+ * is not a scene edit at all.
+ */
+function setLayers(scene, layers) {
+    if (!Array.isArray(layers)) {
+        return {
+            error: 'layers must be an array of { tag, label, visible? } — or [] to remove every toggle.',
+        };
+    }
+    const before = scene.layers ?? [];
+    const next = { ...scene };
+    if (layers.length === 0)
+        delete next.layers;
+    else
+        next.layers = layers;
+    const summary = layers.length === 0
+        ? `Layers cleared${before.length > 0 ? ` (was ${String(before.length)})` : ''}.`
+        : `Layers set: ${layers
+            .map((l) => (isRecord(l) && typeof l.tag === 'string' ? l.tag : '?'))
+            .join(', ')}.`;
+    return {
+        scene: next,
+        summary,
+        ids: [],
+        changes: [{ id: '', what: 'layers', from: before, to: layers }],
+        warnings: [],
+    };
+}
 function setCamera(scene, camera) {
     if (isRecord(camera) && camera.fit === true) {
         const rest = { ...scene };
@@ -301,6 +333,8 @@ export function applySceneOp(scene, op, opts) {
             return removeObject(scene, op.id, opts);
         case 'camera':
             return setCamera(scene, op.camera);
+        case 'layers':
+            return setLayers(scene, op.layers);
         case 'replace': {
             const v = validateScene(op.scene);
             if (!v.ok)
@@ -395,6 +429,8 @@ function describeChange(c) {
             return `added ${typeof c.to === 'string' ? `${c.to} ` : ''}${q}`;
         case 'camera':
             return 'changed the camera';
+        case 'layers':
+            return 'changed which layers can be hidden';
         case 'replaced':
             return 'replaced the whole scene';
         case 'edited':

package/dist/canvas/scene.d.ts

@@ -47,6 +47,14 @@ export interface SceneObjectBase {
     material?: SceneMaterial;
     /** User-only lock: the inspector cannot move/remove it; agents still can (and are warned). */
     locked?: boolean;
+    /**
+     * Cross-cutting labels (§18): `exterior`, `glazing`, `structure`. A tag on a GROUP applies to
+     * its whole subtree. Tags declared as `layers` become show/hide toggles for the user.
+     *
+     * ⚠️ Lowercase, hyphens, NO underscore — `layerParam` maps `-` to `_`, so allowing both would
+     * let `load-bearing` and `load_bearing` collide on one toggle.
+     */
+    tags?: string[];
 }
 export interface BoxObject extends SceneObjectBase {
     type: 'box';
@@ -139,6 +147,21 @@ export type SceneLight = {
     type: 'ambient';
     intensity?: number;
 };
+/**
+ * A user-togglable layer (§18): one tag, one toggle in the Tweaks panel.
+ *
+ * Which layers are currently SHOWING is not here — it lives in the canvas record's `values`, so
+ * hiding a wall to look inside is not an edit to the scene (no rev, no undo entry, no user-edit
+ * notice to the agent). `visible` is only the default.
+ */
+export interface SceneLayer {
+    /** The tag this layer governs. */
+    tag: string;
+    /** Panel label — "Exterior walls", not "exterior". */
+    label: string;
+    /** Showing by default. Default true. */
+    visible?: boolean;
+}
 export interface SceneFile {
     version: 1;
     name: string;
@@ -149,12 +172,23 @@ export interface SceneFile {
     /** Missing → the default studio light. */
     lights?: SceneLight[];
     objects: SceneObject[];
+    /**
+     * Tags the user may show/hide (§18). A tag no layer declares is metadata, not a control.
+     * Missing or empty → the scene has no Tweaks panel.
+     */
+    layers?: SceneLayer[];
 }
 export interface SceneBounds {
     min: Vec3;
     max: Vec3;
 }
 export declare const SCENE_MAX_OBJECTS = 500;
+/** Tag format (§18.3): no underscore, so `layerParam` cannot produce a collision. */
+export declare const SCENE_TAG_PATTERN: RegExp;
+export declare const SCENE_MAX_TAGS_PER_OBJECT = 8;
+/** Distinct tags in one scene, and layers — beyond this a panel of toggles is a tree. */
+export declare const SCENE_MAX_TAGS = 24;
+export declare const SCENE_MAX_LAYERS = 24;
 export declare const SCENE_MAX_BYTES: number;
 /** Max objects in one scene_add_object batch (Q-1). */
 export declare const SCENE_MAX_BATCH = 50;

package/dist/canvas/scene.js

@@ -29,6 +29,12 @@ export const SCENE_EXTRUDE_AXES = ['x', 'y', 'z'];
 // Limits and defaults (§2.3, §2.4, Q-1, Q-14)
 // =============================================================================
 export const SCENE_MAX_OBJECTS = 500;
+/** Tag format (§18.3): no underscore, so `layerParam` cannot produce a collision. */
+export const SCENE_TAG_PATTERN = /^[a-z0-9][a-z0-9-]{0,23}$/;
+export const SCENE_MAX_TAGS_PER_OBJECT = 8;
+/** Distinct tags in one scene, and layers — beyond this a panel of toggles is a tree. */
+export const SCENE_MAX_TAGS = 24;
+export const SCENE_MAX_LAYERS = 24;
 export const SCENE_MAX_BYTES = 512 * 1024;
 /** Max objects in one scene_add_object batch (Q-1). */
 export const SCENE_MAX_BATCH = 50;
@@ -158,8 +164,8 @@ export function utf8Bytes(s) {
     }
     return n;
 }
-const TOP_KEYS = new Set(['version', 'name', 'units', 'camera', 'lights', 'objects']);
-const BASE_KEYS = ['id', 'name', 'type', 'position', 'rotation', 'group', 'locked'];
+const TOP_KEYS = new Set(['version', 'name', 'units', 'camera', 'lights', 'objects', 'layers']);
+const BASE_KEYS = ['id', 'name', 'type', 'position', 'rotation', 'group', 'locked', 'tags'];
 /** Surface fields: every type but `group` (a group has no surface of its own). */
 const SURFACE_KEYS = ['color', 'material'];
 const TYPE_KEYS = {
@@ -181,7 +187,7 @@ const TYPE_SHAPE = {
     torus: 'torus takes radius and tube',
     extrude: 'extrude takes points [[a, b], …], height and optional axis',
     wedge: 'wedge takes size [w, h, d] and optional ridge',
-    group: 'a group is a container: id, name, position, rotation, group, locked only — colour its children',
+    group: 'a group is a container: id, name, position, rotation, group, locked, tags only — colour its children',
 };
 const MATERIAL_KEYS = new Set(['roughness', 'metalness', 'opacity']);
 const HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
@@ -362,6 +368,24 @@ function validateObject(raw, i, errors) {
     if (raw.locked !== undefined && typeof raw.locked !== 'boolean') {
         errors.push(`${label}.locked = ${show(raw.locked)} — true or false.`);
     }
+    if (raw.tags !== undefined) {
+        if (!Array.isArray(raw.tags)) {
+            errors.push(`${label}.tags = ${show(raw.tags)} — an array of labels, e.g. ["exterior"].`);
+        }
+        else if (raw.tags.length > SCENE_MAX_TAGS_PER_OBJECT) {
+            errors.push(`${label}.tags has ${String(raw.tags.length)} labels (max ${String(SCENE_MAX_TAGS_PER_OBJECT)}).`);
+        }
+        else {
+            for (const t of raw.tags) {
+                if (typeof t !== 'string' || !SCENE_TAG_PATTERN.test(t)) {
+                    errors.push(`${label}.tags has ${show(t)} — a tag is 1–24 chars of lowercase letters, digits or "-" (no underscore: "load-bearing", not "load_bearing").`);
+                }
+            }
+            if (new Set(raw.tags).size !== raw.tags.length) {
+                errors.push(`${label}.tags repeats a label.`);
+            }
+        }
+    }
     if (type !== 'group' && raw.material !== undefined) {
         if (!isRecord(raw.material)) {
             errors.push(`${label}.material = ${show(raw.material)} — { roughness?, metalness?, opacity? }.`);
@@ -501,6 +525,44 @@ function validateGroups(objects, errors) {
         }
     });
 }
+/** `layers` (§18): one toggle per tag, with a label the panel can show. */
+function validateLayers(v, errors) {
+    if (!Array.isArray(v)) {
+        errors.push(`layers = ${show(v)} — an array of { tag, label, visible? }.`);
+        return;
+    }
+    if (v.length > SCENE_MAX_LAYERS) {
+        errors.push(`layers has ${String(v.length)} entries (max ${String(SCENE_MAX_LAYERS)}).`);
+        return;
+    }
+    const seen = new Set();
+    v.forEach((raw, i) => {
+        const at = `layers[${String(i)}]`;
+        if (!isRecord(raw)) {
+            errors.push(`${at} = ${show(raw)} — { tag, label, visible? }.`);
+            return;
+        }
+        for (const k of Object.keys(raw)) {
+            if (k !== 'tag' && k !== 'label' && k !== 'visible') {
+                errors.push(`${at}.${k} is not a layer field — tag, label, visible.`);
+            }
+        }
+        if (typeof raw.tag !== 'string' || !SCENE_TAG_PATTERN.test(raw.tag)) {
+            errors.push(`${at}.tag = ${show(raw.tag)} — 1–24 chars of lowercase letters, digits or "-" (no underscore).`);
+        }
+        else if (seen.has(raw.tag)) {
+            errors.push(`${at}.tag = "${raw.tag}" — already declared; one layer per tag.`);
+        }
+        else
+            seen.add(raw.tag);
+        if (typeof raw.label !== 'string' || raw.label.trim().length < 1 || raw.label.length > 48) {
+            errors.push(`${at}.label = ${show(raw.label)} — a string of 1–48 chars, e.g. "Exterior walls".`);
+        }
+        if (raw.visible !== undefined && typeof raw.visible !== 'boolean') {
+            errors.push(`${at}.visible = ${show(raw.visible)} — true or false.`);
+        }
+    });
+}
 function validateLights(v, errors) {
     if (!Array.isArray(v)) {
         errors.push(`lights = ${show(v)} — an array of { type: "sun" | "ambient", … }.`);
@@ -561,7 +623,7 @@ export function validateScene(input) {
     }
     for (const k of Object.keys(input)) {
         if (!TOP_KEYS.has(k)) {
-            errors.push(`${k} is not a scene field — version, name, units, camera, lights, objects.`);
+            errors.push(`${k} is not a scene field — version, name, units, camera, lights, objects, layers.`);
         }
     }
     if (input.version !== SCENE_VERSION) {
@@ -590,6 +652,8 @@ export function validateScene(input) {
     }
     if (input.lights !== undefined)
         validateLights(input.lights, errors);
+    if (input.layers !== undefined)
+        validateLayers(input.layers, errors);
     if (!Array.isArray(input.objects)) {
         errors.push(`objects = ${show(input.objects)} — must be an array.`);
         return { ok: false, errors };
@@ -612,6 +676,17 @@ export function validateScene(input) {
         }
     });
     validateGroups(objects.filter(isRecord), errors);
+    const distinct = new Set();
+    for (const o of objects) {
+        if (isRecord(o) && Array.isArray(o.tags)) {
+            for (const t of o.tags)
+                if (typeof t === 'string')
+                    distinct.add(t);
+        }
+    }
+    if (distinct.size > SCENE_MAX_TAGS) {
+        errors.push(`The scene uses ${String(distinct.size)} different tags (max ${String(SCENE_MAX_TAGS)}). Reuse the labels you have — a tag is a layer the user toggles, not a note on one object.`);
+    }
     if (errors.length === 0) {
         const text = JSON.stringify(input, null, 2);
         const bytes = utf8Bytes(text);

package/dist/capabilities/packs.js

@@ -279,6 +279,7 @@ export const CAPABILITY_PACKS = {
             'scene_update_object',
             'scene_remove_object',
             'scene_set_camera',
+            'scene_set_layers',
             'scene_screenshot',
         ],
         readOnly: false,
@@ -291,10 +292,13 @@ export const CAPABILITY_PACKS = {
             '(objects: [...], ≤ 50), the group first, its parts with group: "<id>"; children are positioned in the ' +
             "group's frame. Roofs: wedge (gable; ridge along z, rotate 90° for x), cone with segments 4 (pyramid/hip), " +
             'or extrude with axis "x"/"z" (a side profile pushed horizontally). Read with scene_get before editing — ' +
-            'the user edits too. Keep neutral colours unless asked. After building, scene_screenshot to check.',
-        // ≈ chars / 4: the snippet is ~910 chars; the seven schemas serialise to ~12 KB (§17 added
-        // group/wedge/segments/axis/ridge and the axis mapping, ~3.7 KB).
-        estimatedPromptTokens: 230,
+            "the user edits too (it returns an outline; pass ids: [...] for an object's numbers). TAG AS YOU BUILD: " +
+            'tags: ["exterior"] etc. on each object, then scene_set_layers to give the user show/hide toggles — a tag ' +
+            'spans groups, so "exterior" covers walls on every floor, and tagging afterwards means a pass over every ' +
+            'object. Keep neutral colours unless asked. After building, scene_screenshot to check.',
+        // ≈ chars / 4: the snippet is ~1,250 chars; the eight schemas serialise to ~13 KB (§17 added
+        // group/wedge/segments/axis/ridge and the axis mapping, ~3.7 KB; §18 tags + scene_set_layers).
+        estimatedPromptTokens: 315,
         estimatedToolTokens: 3000,
     },
     plans: {

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

@@ -15,9 +15,16 @@
 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_screenshot"];
-/** "sofa · box · Sofa" rows, indented under their group parent. */
-export declare function sceneOutline(scene: SceneFile): string;
+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"];
+/**
+ * "sofa · box · Sofa" rows, indented under their group parent; `#tag` suffixes when `withTags`.
+ *
+ * ⚠️ `withTags` exists because tags are DECORATION and addressing is the job. 400 objects each
+ * carrying two tags pushes the outline past `SCENE_READ_MAX_CHARS` (measured: 20,723 chars), and
+ * refusing the cheap read — the one every edit depends on — to make room for labels would be the
+ * wrong trade. `sceneReadBody` drops them, with a count, rather than failing.
+ */
+export declare function sceneOutline(scene: SceneFile, withTags?: boolean): string;
 /**
  * The most JSON one `scene_get` may return.
  *
@@ -93,6 +100,9 @@ export declare function createSceneTools(config: PlatformToolsConfig, options?:
     position?: unknown;
     target?: unknown;
     fit?: boolean;
+}> | import("@compilr-dev/agents").Tool<{
+    canvas_id: number;
+    layers?: unknown;
 }> | import("@compilr-dev/agents").Tool<{
     canvas_id: number;
     width?: number;

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

@@ -14,7 +14,8 @@
  */
 import { defineTool, createErrorResult } from '@compilr-dev/agents';
 import { createSceneWriter } from '../scene-writer.js';
-import { SCENE_MAX_BATCH, SCENE_OBJECT_TYPES, describeScene, serializeScene, } from '../../canvas/scene.js';
+import { SCENE_MAX_BATCH, SCENE_MAX_LAYERS, SCENE_OBJECT_TYPES, 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 = [
     'scene_create',
@@ -23,13 +24,21 @@ export const SCENE_TOOL_NAMES = [
     'scene_update_object',
     'scene_remove_object',
     'scene_set_camera',
+    'scene_set_layers',
     'scene_screenshot',
 ];
 const DEFAULT_SHOT = { width: 1280, height: 800 };
 const SHOT_MIN = 320;
 const SHOT_MAX = 2048;
-/** "sofa · box · Sofa" rows, indented under their group parent. */
-export function sceneOutline(scene) {
+/**
+ * "sofa · box · Sofa" rows, indented under their group parent; `#tag` suffixes when `withTags`.
+ *
+ * ⚠️ `withTags` exists because tags are DECORATION and addressing is the job. 400 objects each
+ * carrying two tags pushes the outline past `SCENE_READ_MAX_CHARS` (measured: 20,723 chars), and
+ * refusing the cheap read — the one every edit depends on — to make room for labels would be the
+ * wrong trade. `sceneReadBody` drops them, with a count, rather than failing.
+ */
+export function sceneOutline(scene, withTags = true) {
     if (scene.objects.length === 0)
         return '(no objects yet)';
     const byParent = new Map();
@@ -64,7 +73,9 @@ export function sceneOutline(scene) {
     const walk = (parent, depth) => {
         for (const o of byParent.get(parent) ?? []) {
             const lock = o.locked ? ' · locked' : '';
-            rows.push(`${'  '.repeat(depth)}${o.id} · ${typeOf(o)}${o.name ? ` · ${o.name}` : ''}${lock}`);
+            // §18: only tagged rows pay for this, and §6.4's budget still has to hold.
+            const tags = withTags && o.tags && o.tags.length > 0 ? ` · ${o.tags.map((t) => `#${t}`).join(' ')}` : '';
+            rows.push(`${'  '.repeat(depth)}${o.id} · ${typeOf(o)}${o.name ? ` · ${o.name}` : ''}${lock}${tags}`);
             if (depth < 8)
                 walk(o.id, depth + 1);
         }
@@ -81,6 +92,7 @@ export function sceneOutline(scene) {
  * for. So an oversized read must be refused with instructions, never silently shortened.
  */
 export const SCENE_READ_MAX_CHARS = 20_000;
+const OUTLINE_HEAD = '--- objects (id · type · name) ---';
 /** "roof, walls" — the first few of a list, for an error that has to name what is available. */
 function someIds(ids, limit = 12) {
     return ids.length <= limit
@@ -136,10 +148,18 @@ export function sceneReadBody(scene, head, ids, full) {
     if (full === true) {
         return guard(serializeScene(scene), `This scene's JSON is over ${String(SCENE_READ_MAX_CHARS)} characters, which would be summarised before you saw it and you would lose the ids. Call scene_get without full for the outline, then with ids: [...] for the objects you need.`);
     }
-    return {
-        ok: true,
-        text: `${head}\n\n--- objects (id · type · name) ---\n${sceneOutline(scene)}`,
-    };
+    /*
+      The outline must always be readable: it is the cheap path every edit depends on, and the
+      object count is what bounds it. So when tags would push it over the ceiling they come OFF,
+      with a count — an explicit "tags omitted" is nothing like a silently shortened JSON dump,
+      which is what the guard exists to prevent.
+    */
+    const outlineWithTags = `${head}\n\n${OUTLINE_HEAD}\n${sceneOutline(scene)}`;
+    if (outlineWithTags.length <= SCENE_READ_MAX_CHARS)
+        return { ok: true, text: outlineWithTags };
+    const tagged = scene.objects.filter((o) => (o.tags ?? []).length > 0).length;
+    const note = `(tags omitted on ${String(tagged)} objects — this outline is near the read limit; the layers line above lists them, and scene_get with ids: [...] shows an object's own tags)`;
+    return guard(`${OUTLINE_HEAD}\n${sceneOutline(scene, false)}\n\n${note}`, `This scene's outline is over ${String(SCENE_READ_MAX_CHARS)} characters even without tags (${String(scene.objects.length)} objects). Read a part of it instead: scene_get with ids: [...] for the objects you are working on.`);
 }
 function clampShot(v, fallback) {
     if (typeof v !== 'number' || !Number.isFinite(v))
@@ -258,6 +278,14 @@ const OBJECT_PROPERTIES = {
         type: 'boolean',
         description: 'Lock against USER edits in the inspector (agents can still edit it).',
     },
+    tags: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Cross-cutting labels, e.g. ["exterior"], ["glazing"]. Lowercase, hyphens, no underscore; ' +
+            'up to 8 per object. Declare a tag with scene_set_layers and the user gets a show/hide ' +
+            'toggle for it. A tag on a GROUP covers everything inside it. Tag as you build: labelling ' +
+            'afterwards means a pass over every object.',
+    },
 };
 const OBJECT_FIELD_NAMES = Object.keys(OBJECT_PROPERTIES);
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
@@ -382,7 +410,17 @@ export function createSceneTools(config, options) {
                 const r = await writer.read(input.canvas_id);
                 if (!r.ok)
                     return createErrorResult(r.error);
-                const head = `Scene "${r.title}" (canvas ${String(r.canvasId)}): ${describeScene(r.scene)} · rev ${String(r.rev)}`;
+                /*
+                  §18. The layer line goes in the HEADER, so it is there whichever read shape the agent
+                  asked for — it needs to know a layer is hidden before it decides the scene is wrong.
+                  `undefined` values: the defaults the scene declares, not the user's current toggles,
+                  which the tools never see.
+                */
+                const layerLine = describeLayers(r.scene);
+                const untagged = undeclaredTags(r.scene);
+                const head = `Scene "${r.title}" (canvas ${String(r.canvasId)}): ${describeScene(r.scene)} · rev ${String(r.rev)}` +
+                    (layerLine === null ? '' : `\nlayers: ${layerLine}`) +
+                    (untagged.length > 0 ? `\ntags with no toggle: ${untagged.join(', ')}` : '');
                 const body = sceneReadBody(r.scene, head, input.ids, input.full);
                 if (!body.ok)
                     return createErrorResult(body.error);
@@ -544,6 +582,67 @@ export function createSceneTools(config, options) {
         },
     });
     // ---------------------------------------------------------------------------
+    const sceneSetLayersTool = defineTool({
+        name: 'scene_set_layers',
+        description: 'Declare which tags the USER can show and hide, giving each a label for the Tweaks panel — ' +
+            'e.g. [{ tag: "exterior", label: "Exterior walls" }]. Replaces the whole list; [] removes ' +
+            'every toggle. Tags themselves go on objects (see tags on scene_add_object), and one tag can ' +
+            'span groups, which is the point: "exterior" covers walls on every floor. Pass visible: false ' +
+            "to start a layer hidden (a cutaway). Toggling is the user's, not yours: it changes their " +
+            'view, never the scene.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                canvas_id: { type: 'number', description: 'The scene canvas id.' },
+                layers: {
+                    type: 'array',
+                    maxItems: SCENE_MAX_LAYERS,
+                    description: `Up to ${String(SCENE_MAX_LAYERS)} layers, in panel order. [] clears them.`,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            tag: { type: 'string', description: 'The tag this toggle governs.' },
+                            label: { type: 'string', description: 'Panel label, e.g. "Exterior walls".' },
+                            visible: { type: 'boolean', description: 'Showing by default. Default true.' },
+                        },
+                        required: ['tag', 'label'],
+                    },
+                },
+            },
+            required: ['canvas_id', 'layers'],
+        },
+        execute: async (input) => {
+            try {
+                if (!Array.isArray(input.layers)) {
+                    return createErrorResult('layers must be an array of { tag, label, visible? } — or [] to remove every toggle.');
+                }
+                const r = await applyAsAgent(input.canvas_id, [{ op: 'layers', layers: input.layers }], () => null);
+                if (!r.success)
+                    return r;
+                // A toggle that governs nothing is not an error — the agent may label the objects next —
+                // but it is invisible in the panel, so say so rather than let it look applied.
+                const read = await writer.read(input.canvas_id);
+                if (read.ok) {
+                    const empty = emptyLayers(read.scene);
+                    const undeclared = undeclaredTags(read.scene);
+                    const notes = [];
+                    if (empty.length > 0) {
+                        notes.push(`No object carries ${empty.length === 1 ? 'the tag' : 'the tags'} ${empty.join(', ')} yet — add tags with scene_update_object and the toggle starts working.`);
+                    }
+                    if (undeclared.length > 0) {
+                        notes.push(`Tags in use with no toggle: ${undeclared.join(', ')}.`);
+                    }
+                    if (notes.length > 0)
+                        return { ...r, result: `${String(r.result)}\n\n${notes.join('\n')}` };
+                }
+                return r;
+            }
+            catch (error) {
+                return createErrorResult(errorMessage('set layers', error));
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
     const sceneScreenshotTool = defineTool({
         name: 'scene_screenshot',
         description: 'RENDER a 3D scene and SEE it — check proportions, overlaps, gaps and floating objects after ' +
@@ -596,6 +695,7 @@ export function createSceneTools(config, options) {
         sceneUpdateObjectTool,
         sceneRemoveObjectTool,
         sceneSetCameraTool,
+        sceneSetLayersTool,
         sceneScreenshotTool,
     ];
 }

package/dist/team/tool-config.js

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

package/package.json

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