@compilr-dev/sdk 0.37.1 → 0.39.0

package/dist/canvas/scene.d.ts

@@ -13,7 +13,7 @@
 export declare const SCENE_VERSION = 1;
 export type Vec3 = [number, number, number];
 export type Vec2 = [number, number];
-export type SceneObjectType = 'box' | 'sphere' | 'cylinder' | 'cone' | 'torus' | 'extrude' | 'wedge' | 'group';
+export type SceneObjectType = 'box' | 'sphere' | 'cylinder' | 'cone' | 'torus' | 'extrude' | 'wedge' | 'group' | 'label';
 export declare const SCENE_OBJECT_TYPES: readonly SceneObjectType[];
 /** The direction an extrude extends along (§17). */
 export type ExtrudeAxis = 'x' | 'y' | 'z';
@@ -21,10 +21,26 @@ export declare const SCENE_EXTRUDE_AXES: readonly ExtrudeAxis[];
 export interface SceneMaterial {
     /** 0..1, default 0.78 */
     roughness?: number;
-    /** 0..1, default 0.02 */
+    /**
+     * 0..1, default 0.02.
+     *
+     * ⚠️ Metal is MIRROR, not colour: a metal with nothing to reflect renders near-black. The
+     * viewer lights the scene with a neutral room environment so this means something; without
+     * one, raising it made objects darker, which is why it had looked like a dead knob.
+     */
     metalness?: number;
     /** 0.05..1, default 1 (transparent when < 1) */
     opacity?: number;
+    /**
+     * '#RRGGBB' the object gives off, default '#000000' (none). Emission is NOT light: it
+     * brightens the object itself and casts nothing on its neighbours, so it marks a thing as
+     * live or active — an indicator, a hot path, a selected step — rather than lighting a room.
+     */
+    emissive?: string;
+    /** How strong the emission is. 0..5, default 1. Only means anything with `emissive` set. */
+    emissiveIntensity?: number;
+    /** Draw the edges only. Default false. For the parts of a diagram that are logical, not built. */
+    wireframe?: boolean;
 }
 export interface SceneObjectBase {
     /** Unique in the scene; /^[a-z0-9][a-z0-9_-]{0,47}$/ */
@@ -133,7 +149,32 @@ export interface GroupObject extends SceneObjectBase {
     color?: never;
     material?: never;
 }
-export type SceneObject = BoxObject | SphereObject | CylinderObject | ConeObject | TorusObject | ExtrudeObject | WedgeObject | GroupObject;
+/** Which way a label turns (§19, D-L2). */
+export type LabelFace = 'camera' | 'fixed';
+export declare const SCENE_LABEL_FACES: readonly LabelFace[];
+/**
+ * Visible text in the scene (§19). Drawn as an unlit textured plane, so it reads the same in
+ * shadow as in the sun and it survives into the GLB and into `scene_screenshot` — which a DOM
+ * overlay would not, and those are the two places the work leaves the app.
+ *
+ * `color` is the INK. `material` is rejected: roughness and metalness mean nothing for unlit
+ * text, and a half-faded label is a request nobody has.
+ *
+ * Parent it to name a thing — `group: "<id>"` — and it moves when that thing moves.
+ */
+export interface LabelObject extends SceneObjectBase {
+    type: 'label';
+    /** One line, 1–120 chars. A newline is rejected: use two labels. */
+    text: string;
+    /** Cap height in metres (the width follows the text). */
+    size?: number;
+    /** '#RRGGBB' plate behind the text. Omitted = transparent. */
+    background?: string;
+    /** 'camera' (default) turns to face the viewer; 'fixed' obeys `rotation`. */
+    face?: LabelFace;
+    material?: never;
+}
+export type SceneObject = BoxObject | SphereObject | CylinderObject | ConeObject | TorusObject | ExtrudeObject | WedgeObject | GroupObject | LabelObject;
 export interface SceneCamera {
     position: Vec3;
     target: Vec3;
@@ -210,6 +251,24 @@ export declare const SCENE_MAX_SHADOW_LIGHTS = 2;
 export declare const SCENE_LIGHT_INTENSITY_MAX = 10;
 export declare const SCENE_MAX_GROUP_DEPTH = 8;
 export declare const SCENE_NAME_MAX = 80;
+/** Label text (§19). One line — long enough for a room name or a dimension, not a paragraph. */
+export declare const SCENE_LABEL_TEXT_MAX = 120;
+/** Label cap height in metres. */
+export declare const SCENE_LABEL_SIZE_MIN = 0.02;
+export declare const SCENE_LABEL_SIZE_MAX = 20;
+export declare const SCENE_LABEL_SIZE_DEFAULT = 0.25;
+/**
+ * Estimated advance per character, as a fraction of the cap height — used for a label's BOUNDS.
+ *
+ * ⚠️ An estimate on purpose. The real width comes from measuring the text in a 2D canvas, which
+ * this module cannot do (it runs in Node, in the CLI, and in tests with no DOM). The renderer
+ * measures and builds its plane from that; this number only decides how much room a label is
+ * given when the camera is fitted to the scene, where being a few centimetres out is invisible.
+ * Anything that must agree exactly uses `liftFor`, which depends on the height alone.
+ */
+export declare const SCENE_LABEL_ADVANCE = 0.62;
+/** A label's plane in metres, [width, height] — the width estimated (see SCENE_LABEL_ADVANCE). */
+export declare function labelPlaneSize(obj: LabelObject): Vec2;
 export declare const SCENE_OPACITY_MIN = 0.05;
 export declare const SCENE_ID_PATTERN: RegExp;
 /** Object colours never read as state (README) — a neutral palette, filled by insertion index. */
@@ -217,6 +276,8 @@ export declare const SCENE_NEUTRAL_PALETTE: readonly string[];
 /** Accessible names for the palette swatches, same order (Q-10). */
 export declare const SCENE_PALETTE_NAMES: readonly string[];
 export declare const SCENE_DEFAULT_MATERIAL: Readonly<Required<SceneMaterial>>;
+/** `material.emissiveIntensity` range. Above ~5 everything clips to white. */
+export declare const SCENE_EMISSIVE_INTENSITY_MAX = 5;
 /** The reference camera, used for an empty scene. */
 export declare const SCENE_DEFAULT_CAMERA: Readonly<SceneCamera>;
 /** Vertical field of view of the viewer camera, degrees. */

package/dist/canvas/scene.js

@@ -23,8 +23,10 @@ export const SCENE_OBJECT_TYPES = [
     'extrude',
     'wedge',
     'group',
+    'label',
 ];
 export const SCENE_EXTRUDE_AXES = ['x', 'y', 'z'];
+export const SCENE_LABEL_FACES = ['camera', 'fixed'];
 // =============================================================================
 // Limits and defaults (§2.3, §2.4, Q-1, Q-14)
 // =============================================================================
@@ -56,6 +58,27 @@ export const SCENE_MAX_SHADOW_LIGHTS = 2;
 export const SCENE_LIGHT_INTENSITY_MAX = 10;
 export const SCENE_MAX_GROUP_DEPTH = 8;
 export const SCENE_NAME_MAX = 80;
+/** Label text (§19). One line — long enough for a room name or a dimension, not a paragraph. */
+export const SCENE_LABEL_TEXT_MAX = 120;
+/** Label cap height in metres. */
+export const SCENE_LABEL_SIZE_MIN = 0.02;
+export const SCENE_LABEL_SIZE_MAX = 20;
+export const SCENE_LABEL_SIZE_DEFAULT = 0.25;
+/**
+ * Estimated advance per character, as a fraction of the cap height — used for a label's BOUNDS.
+ *
+ * ⚠️ An estimate on purpose. The real width comes from measuring the text in a 2D canvas, which
+ * this module cannot do (it runs in Node, in the CLI, and in tests with no DOM). The renderer
+ * measures and builds its plane from that; this number only decides how much room a label is
+ * given when the camera is fitted to the scene, where being a few centimetres out is invisible.
+ * Anything that must agree exactly uses `liftFor`, which depends on the height alone.
+ */
+export const SCENE_LABEL_ADVANCE = 0.62;
+/** A label's plane in metres, [width, height] — the width estimated (see SCENE_LABEL_ADVANCE). */
+export function labelPlaneSize(obj) {
+    const h = obj.size ?? SCENE_LABEL_SIZE_DEFAULT;
+    return [Math.max(h * 0.5, obj.text.length * h * SCENE_LABEL_ADVANCE), h];
+}
 export const SCENE_OPACITY_MIN = 0.05;
 export const SCENE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,47}$/;
 /** Object colours never read as state (README) — a neutral palette, filled by insertion index. */
@@ -82,7 +105,12 @@ export const SCENE_DEFAULT_MATERIAL = {
     roughness: 0.78,
     metalness: 0.02,
     opacity: 1,
+    emissive: '#000000',
+    emissiveIntensity: 1,
+    wireframe: false,
 };
+/** `material.emissiveIntensity` range. Above ~5 everything clips to white. */
+export const SCENE_EMISSIVE_INTENSITY_MAX = 5;
 /** The reference camera, used for an empty scene. */
 export const SCENE_DEFAULT_CAMERA = {
     position: [7, 5.5, 8],
@@ -132,6 +160,8 @@ export function defaultObjectFor(type, id) {
             return { ...base, type, size: [1, 1, 1] };
         case 'group':
             return { ...base, type };
+        case 'label':
+            return { ...base, type, text: 'Label' };
     }
 }
 /** The stored form: pretty-printed, because agents read and cite it (§4.1). */
@@ -177,6 +207,7 @@ const TYPE_KEYS = {
     extrude: ['points', 'height', 'axis'],
     wedge: ['size', 'ridge'],
     group: [],
+    label: ['text', 'size', 'background', 'face'],
 };
 /** How each type is described in errors (what fields it takes). */
 const TYPE_SHAPE = {
@@ -188,8 +219,16 @@ const TYPE_SHAPE = {
     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, tags only — colour its children',
+    label: 'label takes text and optional size (cap height in metres), background, face ("camera" or "fixed"); color is the ink and material is not allowed',
 };
-const MATERIAL_KEYS = new Set(['roughness', 'metalness', 'opacity']);
+const MATERIAL_KEYS = new Set([
+    'roughness',
+    'metalness',
+    'opacity',
+    'emissive',
+    'emissiveIntensity',
+    'wireframe',
+]);
 const HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
 /** Short, stable number rendering for messages and summaries. */
 export function fmtNum(n) {
@@ -337,7 +376,8 @@ function validateObject(raw, i, errors) {
     // Unknown keys: rejected, because they would round-trip silently and read as honoured.
     const allowed = new Set([
         ...BASE_KEYS,
-        ...(type === 'group' ? [] : SURFACE_KEYS),
+        // A group has no surface at all; a label has ink (`color`) but no material (§19.2).
+        ...(type === 'group' ? [] : type === 'label' ? ['color'] : SURFACE_KEYS),
         ...TYPE_KEYS[type],
     ]);
     for (const k of Object.keys(raw)) {
@@ -386,7 +426,7 @@ function validateObject(raw, i, errors) {
             }
         }
     }
-    if (type !== 'group' && raw.material !== undefined) {
+    if (type !== 'group' && type !== 'label' && raw.material !== undefined) {
         if (!isRecord(raw.material)) {
             errors.push(`${label}.material = ${show(raw.material)} — { roughness?, metalness?, opacity? }.`);
         }
@@ -394,7 +434,7 @@ function validateObject(raw, i, errors) {
             const m = raw.material;
             for (const k of Object.keys(m)) {
                 if (!MATERIAL_KEYS.has(k)) {
-                    errors.push(`${label}.material.${k} is not a material field — roughness, metalness, opacity.`);
+                    errors.push(`${label}.material.${k} is not a material field — roughness, metalness, opacity, emissive, emissiveIntensity, wireframe.`);
                 }
             }
             if (m.roughness !== undefined)
@@ -403,6 +443,15 @@ function validateObject(raw, i, errors) {
                 checkNumber(m.metalness, `${label}.material.metalness`, 0, 1, 'metalness is 0–1', errors);
             if (m.opacity !== undefined)
                 checkNumber(m.opacity, `${label}.material.opacity`, SCENE_OPACITY_MIN, 1, `opacity is ${fmtNum(SCENE_OPACITY_MIN)}–1`, errors);
+            if (m.emissive !== undefined &&
+                (typeof m.emissive !== 'string' || !HEX_RE.test(m.emissive))) {
+                errors.push(`${label}.material.emissive = ${show(m.emissive)} — a colour the object gives off, "#RGB" or "#RRGGBB" ("#000000" for none).`);
+            }
+            if (m.emissiveIntensity !== undefined)
+                checkNumber(m.emissiveIntensity, `${label}.material.emissiveIntensity`, 0, SCENE_EMISSIVE_INTENSITY_MAX, `emissiveIntensity is 0–${String(SCENE_EMISSIVE_INTENSITY_MAX)}, and only does anything with emissive set`, errors);
+            if (m.wireframe !== undefined && typeof m.wireframe !== 'boolean') {
+                errors.push(`${label}.material.wireframe = ${show(m.wireframe)} — true or false.`);
+            }
         }
     }
     // Type-specific dimensions.
@@ -433,6 +482,29 @@ function validateObject(raw, i, errors) {
             break;
         case 'group':
             break;
+        case 'label': {
+            if (typeof raw.text !== 'string' || raw.text.length < 1) {
+                errors.push(`${label}.text = ${show(raw.text)} — the words to show, 1–${String(SCENE_LABEL_TEXT_MAX)} chars.`);
+            }
+            else if (raw.text.length > SCENE_LABEL_TEXT_MAX) {
+                errors.push(`${label}.text is ${String(raw.text.length)} chars (max ${String(SCENE_LABEL_TEXT_MAX)}) — a label is one short line, not a paragraph.`);
+            }
+            else if (/[\n\r]/.test(raw.text)) {
+                errors.push(`${label}.text has a line break — a label is one line; use two labels.`);
+            }
+            if (raw.size !== undefined) {
+                checkNumber(raw.size, `${label}.size`, SCENE_LABEL_SIZE_MIN, SCENE_LABEL_SIZE_MAX, `size is the cap height in metres, ${fmtNum(SCENE_LABEL_SIZE_MIN)}–${fmtNum(SCENE_LABEL_SIZE_MAX)} (the width follows the text)`, errors);
+            }
+            if (raw.background !== undefined &&
+                (typeof raw.background !== 'string' || !HEX_RE.test(raw.background))) {
+                errors.push(`${label}.background = ${show(raw.background)} — colours are "#RGB" or "#RRGGBB" hex.`);
+            }
+            if (raw.face !== undefined &&
+                !SCENE_LABEL_FACES.includes(raw.face)) {
+                errors.push(`${label}.face = ${show(raw.face)} — "camera" (turns to face the viewer) or "fixed" (obeys rotation).`);
+            }
+            break;
+        }
         case 'torus': {
             const rOk = checkNumber(raw.radius, `${label}.radius`, SCENE_RADIUS_MIN, SCENE_RADIUS_MAX, RADIUS_RULE, errors);
             const maxTube = rOk ? raw.radius : SCENE_RADIUS_MAX;
@@ -779,6 +851,9 @@ export function liftFor(obj) {
         }
         case 'group':
             return 0;
+        // Half the plane's height, so `y` is the bottom here too (D-L6).
+        case 'label':
+            return (obj.size ?? SCENE_LABEL_SIZE_DEFAULT) / 2;
     }
 }
 /**
@@ -822,6 +897,12 @@ function extrudeBox(obj) {
 /** Local AABB of the mesh around its own origin (the pivot). null for a group (no geometry). */
 function localBox(obj) {
     switch (obj.type) {
+        // A flat plane in x–y, centred on the pivot. Its depth is zero, and the width is the
+        // estimate (SCENE_LABEL_ADVANCE) — a label never decides a scene's extents on its own.
+        case 'label': {
+            const [w, h] = labelPlaneSize(obj);
+            return { min: [-w / 2, -h / 2, 0], max: [w / 2, h / 2, 0] };
+        }
         case 'box':
         case 'wedge': {
             // A wedge's triangle spans the full width at its base and the full height at its apex,

package/dist/models/providers.js

@@ -40,7 +40,12 @@ export const PROVIDER_METADATA = {
         displayName: 'Google AI (Gemini)',
         description: 'Gemini models from Google',
         endpoint: 'https://generativelanguage.googleapis.com/v1beta',
-        envVar: 'GOOGLE_API_KEY',
+        // Must be a variable `detectProviderFromEnv` actually reads (see ENV_PROVIDER_MAP in
+        // provider.ts). It said `GOOGLE_API_KEY` for months — a variable nothing anywhere reads —
+        // and that string is what the CLI prints in "export <var>=..." when the key is missing and
+        // in the /model detail pane, so the one user who followed it set a variable that was then
+        // ignored. `GEMINI_API_KEY` is also accepted as a fallback.
+        envVar: 'GOOGLE_AI_API_KEY',
         keyUrl: 'https://aistudio.google.com/apikey',
         requiresKey: true,
         category: 'primary',

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, describeScene, serializeScene, } from '../../canvas/scene.js';
+import { SCENE_MAX_BATCH, SCENE_MAX_LAYERS, SCENE_OBJECT_TYPES, 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 = [
@@ -200,7 +200,9 @@ const OBJECT_PROPERTIES = {
         description: 'box (size [w,h,d]) · sphere (radius) · cylinder / cone (radius, height, optional segments) · torus (radius, tube; lies flat) · ' +
             'extrude (points + height, optional axis) for walls, floors and profiles · wedge (size [w,h,d], optional ridge) — a ' +
             'triangular prism for roofs · group — a container with no geometry: give it your own id and put parts in it with ' +
-            'group: "<id>". There is no "wall" type — use extrude.',
+            'group: "<id>" · label (text) — VISIBLE TEXT in the scene, for room names, part names and ' +
+            'callouts; parent it with group: "<id>" to name a thing and it moves with it. ' +
+            'There is no "wall" type — use extrude.',
     },
     position: {
         ...VEC3,
@@ -226,6 +228,25 @@ const OBJECT_PROPERTIES = {
         description: 'cylinder/cone: height in metres. extrude: how far it extends along its axis.',
     },
     tube: { type: 'number', description: 'torus only: tube radius (≤ radius).' },
+    text: {
+        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.',
+    },
+    background: {
+        type: 'string',
+        description: 'label only: "#RRGGBB" plate behind the text. Omit for transparent — add one only where the ' +
+            'label sits over busy geometry.',
+    },
+    face: {
+        type: 'string',
+        enum: SCENE_LABEL_FACES,
+        description: 'label only: "camera" (default) turns the text to the viewer, for a callout. "fixed" obeys ' +
+            'rotation, for text that belongs to a surface — a room name lying on the floor needs ' +
+            'face: "fixed" with rotation [-90, 0, 0]. ⚠️ A GLB export bakes whichever way a "camera" ' +
+            'label happened to face.',
+    },
     segments: {
         type: 'integer',
         minimum: 3,
@@ -267,11 +288,30 @@ const OBJECT_PROPERTIES = {
     },
     material: {
         type: 'object',
-        description: '{ roughness 0–1, metalness 0–1, opacity 0.05–1 }. Not on a group.',
+        description: 'Not on a group or a label. { roughness 0–1 (0 = mirror-smooth, 1 = matt) · metalness 0–1 ' +
+            '(metal is MIRROR, not colour: it shows the room, so it reads dark against a plain ' +
+            'background — use it for a few accents, not everything) · opacity 0.05–1 (a pane of glass, ' +
+            'a volume you want to see into) · emissive "#RRGGBB" + emissiveIntensity 0–5 · wireframe }.',
         properties: {
             roughness: { type: 'number' },
             metalness: { type: 'number' },
             opacity: { type: 'number' },
+            emissive: {
+                type: 'string',
+                description: 'A colour the object GIVES OFF, so it reads as live rather than lit: an indicator, an ' +
+                    'active path, the step being explained. ⚠️ It brightens the object only — it casts no ' +
+                    "light on its neighbours and draws no halo. Pair it with the object's own colour, and " +
+                    'use it on a few things: everything glowing is nothing glowing.',
+            },
+            emissiveIntensity: {
+                type: 'number',
+                description: '0–5, default 1. Does nothing without emissive. Past ~3 the colour clips to white.',
+            },
+            wireframe: {
+                type: 'boolean',
+                description: 'Edges only. For the parts of a diagram that are LOGICAL rather than built — a boundary, ' +
+                    'a planned phase, a region — beside solid objects that are real.',
+            },
         },
     },
     locked: {

package/package.json

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