@compilr-dev/sdk 0.30.0 → 0.31.0

package/dist/canvas/scene-ops.js

@@ -13,7 +13,17 @@ import { SCENE_ID_PATTERN, SCENE_MAX_BATCH, SCENE_OBJECT_TYPES, descendantsOf, f
 // =============================================================================
 // Helpers
 // =============================================================================
-const SIZE_KEYS = new Set(['size', 'radius', 'height', 'tube', 'points']);
+/** Geometry fields — a change to any of them is journalled as "resized". */
+const SIZE_KEYS = new Set([
+    'size',
+    'radius',
+    'height',
+    'tube',
+    'points',
+    'ridge',
+    'segments',
+    'axis',
+]);
 function sceneRef(opts) {
     return opts?.canvasId !== undefined ? `scene ${String(opts.canvasId)}` : 'this scene';
 }
@@ -54,15 +64,59 @@ function addObjects(scene, inputs, index, opts) {
             error: `A batch adds at most ${String(SCENE_MAX_BATCH)} objects (got ${String(inputs.length)}). Split it over several scene_add_object calls.`,
         };
     }
-    const taken = new Set(scene.objects.map((o) => o.id));
-    const added = [];
+    const existing = new Map(scene.objects.map((o) => [o.id, o]));
+    const taken = new Set(existing.keys());
+    const label = (i) => (inputs.length > 1 ? `objects[${String(i)}]` : 'The object');
+    // Explicit nulls are a caller's "not set" — dropped.
+    const objs = [];
     for (let i = 0; i < inputs.length; i++) {
         const raw = inputs[i];
-        const at = inputs.length > 1 ? `objects[${String(i)}]` : 'The object';
         if (!isRecord(raw))
-            return { error: `${at} must be a JSON object.` };
-        // Explicit nulls are a caller's "not set" — dropped.
-        const obj = Object.fromEntries(Object.entries(clone(raw)).filter(([, v]) => v !== null));
+            return { error: `${label(i)} must be a JSON object.` };
+        objs.push(Object.fromEntries(Object.entries(clone(raw)).filter(([, v]) => v !== null)));
+    }
+    // Caller-chosen ids first: they are reserved before any id is generated, so a generated id
+    // never takes a name the caller picked later in the same batch. A collision with a CHOSEN
+    // id is an error naming the existing object (never a silent "-2" — the caller would then
+    // reference the wrong object).
+    const chosenAt = new Map();
+    for (let i = 0; i < objs.length; i++) {
+        const id = objs[i].id;
+        if (id === undefined)
+            continue;
+        if (typeof id !== 'string' || !SCENE_ID_PATTERN.test(id)) {
+            return {
+                error: `${label(i)}.id = ${JSON.stringify(id)} — ids are 1–48 chars of lowercase letters, digits, "-" or "_", starting with a letter or digit. Omit id to have one generated from the name.`,
+            };
+        }
+        const prior = existing.get(id);
+        if (prior) {
+            const suggestion = generateSceneId(id, new Set([...taken, ...chosenAt.keys()]));
+            return {
+                error: `${label(i)}.id = "${id}" — ${sceneRef(opts)} already has an object with that id ` +
+                    `(${prior.type}${prior.name ? ` "${prior.name}"` : ''}). Choose another id (e.g. "${suggestion}"), ` +
+                    `change the existing one with scene_update_object id "${id}", or omit id to have one generated. scene_get lists ids.`,
+            };
+        }
+        const first = chosenAt.get(id);
+        if (first !== undefined) {
+            return {
+                error: `${label(i)}.id = "${id}" — objects[${String(first)}] in this batch already uses that id; ids must be unique.`,
+            };
+        }
+        chosenAt.set(id, i);
+    }
+    for (const id of chosenAt.keys())
+        taken.add(id);
+    /*
+      Parents (`group`) are NOT resolved here: the final validation of the whole op list does it
+      (validateGroups), so a batch may name a parent created anywhere in the same batch or in an
+      earlier op of the same apply — e.g. an undo that re-adds a removed subtree child-first.
+    */
+    const added = [];
+    for (let i = 0; i < objs.length; i++) {
+        const at = label(i);
+        const obj = objs[i];
         if (obj.type === 'wall') {
             return {
                 error: `${at}: use type "extrude" with points [[x,z],…] and height for walls.`,
@@ -75,20 +129,11 @@ function addObjects(scene, inputs, index, opts) {
             };
         }
         if (obj.id === undefined) {
+            // Generated ids keep the P1 behaviour: slug of the name (or type), -2, -3… on collision.
             const base = typeof obj.name === 'string' && obj.name.trim() ? obj.name : obj.type;
             obj.id = generateSceneId(base, taken);
+            taken.add(obj.id);
         }
-        else if (typeof obj.id !== 'string' || !SCENE_ID_PATTERN.test(obj.id)) {
-            return {
-                error: `${at}.id = ${JSON.stringify(obj.id)} — ids are 1–48 chars of lowercase letters, digits, "-" or "_". Omit id to have one generated from the name.`,
-            };
-        }
-        else if (taken.has(obj.id)) {
-            return {
-                error: `An object "${obj.id}" already exists in ${sceneRef(opts)}. Choose another id, or omit id to have one generated (scene_get lists ids).`,
-            };
-        }
-        taken.add(obj.id);
         added.push(obj);
     }
     const objects = [...scene.objects];

package/dist/canvas/scene.d.ts

@@ -13,8 +13,11 @@
 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';
+export type SceneObjectType = 'box' | 'sphere' | 'cylinder' | 'cone' | 'torus' | 'extrude' | 'wedge' | 'group';
 export declare const SCENE_OBJECT_TYPES: readonly SceneObjectType[];
+/** The direction an extrude extends along (§17). */
+export type ExtrudeAxis = 'x' | 'y' | 'z';
+export declare const SCENE_EXTRUDE_AXES: readonly ExtrudeAxis[];
 export interface SceneMaterial {
     /** 0..1, default 0.78 */
     roughness?: number;
@@ -35,7 +38,11 @@ export interface SceneObjectBase {
     rotation?: Vec3;
     /** '#RRGGBB'. Filled by the writer from the neutral palette when absent. */
     color?: string;
-    /** Parent object id — position/rotation are relative to the parent's frame. */
+    /**
+     * Parent object id — position/rotation are relative to the parent's frame. A `group` is the
+     * intended container, but ANY object may be a parent (P1 scenes parent to shapes; kept for
+     * backward compatibility). No cycles, depth ≤ SCENE_MAX_GROUP_DEPTH.
+     */
     group?: string;
     material?: SceneMaterial;
     /** User-only lock: the inspector cannot move/remove it; agents still can (and are warned). */
@@ -50,15 +57,24 @@ export interface SphereObject extends SceneObjectBase {
     type: 'sphere';
     radius: number;
 }
+/**
+ * `segments` (integer 3–64, optional): a faceted prism instead of a smooth round one. Omitted =
+ * smooth. Vertex k sits at angle θ = 2πk/segments with x = radius·sin θ, z = radius·cos θ
+ * (three.js CylinderGeometry/ConeGeometry, thetaStart 0) — so vertex 0 is on +z, and `radius`
+ * is the CIRCUMradius. A 4-segment cone is a pyramid with corners on the ±x/±z axes (rotate 45°
+ * about Y for sides parallel to the axes; its base side is radius·√2).
+ */
 export interface CylinderObject extends SceneObjectBase {
     type: 'cylinder';
     radius: number;
     height: number;
+    segments?: number;
 }
 export interface ConeObject extends SceneObjectBase {
     type: 'cone';
     radius: number;
     height: number;
+    segments?: number;
 }
 /** Lies flat (ring in the x–z plane). radius = ring radius, tube = tube radius. */
 export interface TorusObject extends SceneObjectBase {
@@ -66,13 +82,50 @@ export interface TorusObject extends SceneObjectBase {
     radius: number;
     tube: number;
 }
-/** An outline in plan (x, z), local to position, extruded upward by `height`. Walls and floors. */
+/**
+ * An outline extruded by `height` along `axis` (default 'y'). Points are local to `position`;
+ * which world axes a point [a, b] maps to depends on the axis:
+ *
+ * | axis | point [a, b] is | the outline lies in | extends along  |
+ * |------|-----------------|---------------------|----------------|
+ * | 'y'  | [x, z] (plan)   | the floor (x–z)     | +y, 0 → height |
+ * | 'z'  | [x, y] (side)   | the x–y plane       | +z, 0 → height |
+ * | 'x'  | [z, y] (side)   | the z–y plane       | +x, 0 → height |
+ *
+ * For 'x'/'z' the SECOND coordinate is up (y) and the first is the horizontal one — a side
+ * profile (a gable, a roof section) pushed sideways. y-bottom rule: the mesh is lifted by
+ * −min(b) for 'x'/'z' (0 for 'y'), so the lowest point of the outline sits at `position.y`.
+ * The rotation pivot is the outline's [0, 0] at the start of the extrusion (lifted likewise).
+ */
 export interface ExtrudeObject extends SceneObjectBase {
     type: 'extrude';
     points: Vec2[];
     height: number;
+    axis?: ExtrudeAxis;
 }
-export type SceneObject = BoxObject | SphereObject | CylinderObject | ConeObject | TorusObject | ExtrudeObject;
+/**
+ * A triangular prism (roofs): `size` [w, h, d]. The triangle is in the x–y plane and the ridge
+ * runs along z. Mesh-local (centred like a box, lift h/2): base corners (−w/2, −h/2) and
+ * (w/2, −h/2), apex (−w/2 + ridge·w, h/2); the prism spans z ∈ [−d/2, d/2]. `ridge` 0–1,
+ * default 0.5 (centred apex; 0 or 1 = a lean-to with a vertical side).
+ */
+export interface WedgeObject extends SceneObjectBase {
+    type: 'wedge';
+    size: Vec3;
+    ridge?: number;
+}
+/**
+ * A transform node — no geometry, no size, no colour/material (rejected: colour its children).
+ * Children (`group: "<this id>"`) are positioned in its frame: its `position` is their origin
+ * (a group has no height, so its lift is 0 and child y = 0 is the group's y) and its rotation
+ * pivots there. Its bounds are the union of its descendants' (none while it is empty).
+ */
+export interface GroupObject extends SceneObjectBase {
+    type: 'group';
+    color?: never;
+    material?: never;
+}
+export type SceneObject = BoxObject | SphereObject | CylinderObject | ConeObject | TorusObject | ExtrudeObject | WedgeObject | GroupObject;
 export interface SceneCamera {
     position: Vec3;
     target: Vec3;
@@ -111,6 +164,11 @@ export declare const SCENE_SIZE_MAX = 500;
 export declare const SCENE_RADIUS_MIN = 0.01;
 export declare const SCENE_RADIUS_MAX = 250;
 export declare const SCENE_TUBE_MIN = 0.005;
+/** `segments` on cone/cylinder: integer range (§17). */
+export declare const SCENE_SEGMENTS_MIN = 3;
+export declare const SCENE_SEGMENTS_MAX = 64;
+/** wedge `ridge` default: apex centred across the width. */
+export declare const SCENE_WEDGE_RIDGE_DEFAULT = 0.5;
 export declare const SCENE_POINTS_MIN = 3;
 export declare const SCENE_POINTS_MAX = 256;
 export declare const SCENE_MAX_LIGHTS = 4;
@@ -178,17 +236,29 @@ export declare function normalizeAngle(deg: number): number;
 export declare function normalizeScene(scene: SceneFile): SceneFile;
 /**
  * Half-height from the object's BOTTOM (its `position.y`) to its geometric centre, where the
- * mesh sits. extrude is 0: its geometry already starts at the floor. ONE function — the
- * viewer, the fit and the GLB export must agree.
+ * mesh sits. extrude along y is 0: its geometry already starts at the floor; along x/z it is
+ * −min(profile y), so the profile's lowest point sits at position.y. A group has no height: 0.
+ * ONE function — the viewer, the fit and the GLB export must agree.
  */
 export declare function liftFor(obj: SceneObject): number;
 /**
  * World matrix of each object's mesh (row-major 4×4), keyed by id, with group parenting
- * applied. Assumes a validated scene (no cycles).
+ * applied. A `group` has no mesh and lift 0, so its entry is its frame: T(position) · R,
+ * rotating about its position. Assumes a validated scene (no cycles).
  */
 export declare function sceneWorldMatrices(scene: SceneFile): Map<string, number[]>;
-/** World-space AABB of all objects (conservative for rotated shapes). null when empty. */
+/**
+ * World-space AABB of all objects (conservative for rotated shapes). null when nothing has
+ * geometry — an empty scene, or one holding only empty groups (the camera then uses the
+ * reference default, as for an empty scene).
+ */
 export declare function sceneBounds(scene: SceneFile): SceneBounds | null;
+/**
+ * World AABB of one object and everything grouped under it — for a `group`, the union of its
+ * descendants (null while it holds no geometry); for a shape, its own mesh plus any children.
+ * null for an unknown id. (The viewer outlines a selected group's whole subtree with this.)
+ */
+export declare function sceneObjectBounds(scene: SceneFile, id: string): SceneBounds | null;
 /** The reference view direction ([7, 5.5, 8], normalised). */
 export declare const SCENE_CAMERA_DIRECTION: Readonly<Vec3>;
 /**
@@ -199,7 +269,7 @@ export declare const SCENE_CAMERA_DIRECTION: Readonly<Vec3>;
 export declare function fitCamera(bounds: SceneBounds | null, fovDeg?: number): SceneCamera;
 /** The camera to view a scene with: its own, or the fit. */
 export declare function sceneCamera(scene: SceneFile): SceneCamera;
-/** One line: "12 objects, bounds 6.2 × 4 × 2.7 m" (W × D × H). */
+/** One line: "12 objects (2 groups), bounds 6.2 × 4 × 2.7 m" (W × D × H). */
 export declare function describeScene(scene: SceneFile): string;
 /** The ids of an object's descendants (children, grandchildren, …), in scene order. */
 export declare function descendantsOf(scene: SceneFile, id: string): string[];

package/dist/canvas/scene.js

@@ -21,7 +21,10 @@ export const SCENE_OBJECT_TYPES = [
     'cone',
     'torus',
     'extrude',
+    'wedge',
+    'group',
 ];
+export const SCENE_EXTRUDE_AXES = ['x', 'y', 'z'];
 // =============================================================================
 // Limits and defaults (§2.3, §2.4, Q-1, Q-14)
 // =============================================================================
@@ -35,6 +38,11 @@ export const SCENE_SIZE_MAX = 500;
 export const SCENE_RADIUS_MIN = 0.01;
 export const SCENE_RADIUS_MAX = 250;
 export const SCENE_TUBE_MIN = 0.005;
+/** `segments` on cone/cylinder: integer range (§17). */
+export const SCENE_SEGMENTS_MIN = 3;
+export const SCENE_SEGMENTS_MAX = 64;
+/** wedge `ridge` default: apex centred across the width. */
+export const SCENE_WEDGE_RIDGE_DEFAULT = 0.5;
 export const SCENE_POINTS_MIN = 3;
 export const SCENE_POINTS_MAX = 256;
 export const SCENE_MAX_LIGHTS = 4;
@@ -114,6 +122,10 @@ export function defaultObjectFor(type, id) {
                 ],
                 height: 1,
             };
+        case 'wedge':
+            return { ...base, type, size: [1, 1, 1] };
+        case 'group':
+            return { ...base, type };
     }
 }
 /** The stored form: pretty-printed, because agents read and cite it (§4.1). */
@@ -147,33 +159,29 @@ 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',
-    'color',
-    'group',
-    'material',
-    'locked',
-];
+const BASE_KEYS = ['id', 'name', 'type', 'position', 'rotation', 'group', 'locked'];
+/** Surface fields: every type but `group` (a group has no surface of its own). */
+const SURFACE_KEYS = ['color', 'material'];
 const TYPE_KEYS = {
     box: ['size'],
     sphere: ['radius'],
-    cylinder: ['radius', 'height'],
-    cone: ['radius', 'height'],
+    cylinder: ['radius', 'height', 'segments'],
+    cone: ['radius', 'height', 'segments'],
     torus: ['radius', 'tube'],
-    extrude: ['points', 'height'],
+    extrude: ['points', 'height', 'axis'],
+    wedge: ['size', 'ridge'],
+    group: [],
 };
 /** How each type is described in errors (what fields it takes). */
 const TYPE_SHAPE = {
     box: 'box takes size [w, h, d]',
     sphere: 'sphere takes radius',
-    cylinder: 'cylinder takes radius and height',
-    cone: 'cone takes radius and height',
+    cylinder: 'cylinder takes radius, height and optional segments',
+    cone: 'cone takes radius, height and optional segments',
     torus: 'torus takes radius and tube',
-    extrude: 'extrude takes points [[x, z], …] and height',
+    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',
 };
 const MATERIAL_KEYS = new Set(['roughness', 'metalness', 'opacity']);
 const HEX_RE = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
@@ -321,7 +329,11 @@ function validateObject(raw, i, errors) {
     }
     const type = t;
     // Unknown keys: rejected, because they would round-trip silently and read as honoured.
-    const allowed = new Set([...BASE_KEYS, ...TYPE_KEYS[type]]);
+    const allowed = new Set([
+        ...BASE_KEYS,
+        ...(type === 'group' ? [] : SURFACE_KEYS),
+        ...TYPE_KEYS[type],
+    ]);
     for (const k of Object.keys(raw)) {
         if (!allowed.has(k)) {
             errors.push(`${label}.${k} is not a ${type} field — ${TYPE_SHAPE[type]}.`);
@@ -339,7 +351,7 @@ function validateObject(raw, i, errors) {
     if (raw.rotation !== undefined) {
         checkVec(raw.rotation, `${label}.rotation`, 3, -Number.MAX_VALUE, Number.MAX_VALUE, 'rotation is degrees [x, y, z]; rotate about Y — x/z tilt breaks the floor rule', errors);
     }
-    if (raw.color !== undefined) {
+    if (type !== 'group' && raw.color !== undefined) {
         if (typeof raw.color !== 'string' || !HEX_RE.test(raw.color)) {
             errors.push(`${label}.color = ${show(raw.color)} — colours are "#RGB" or "#RRGGBB" hex.`);
         }
@@ -350,7 +362,7 @@ 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.material !== undefined) {
+    if (type !== 'group' && raw.material !== undefined) {
         if (!isRecord(raw.material)) {
             errors.push(`${label}.material = ${show(raw.material)} — { roughness?, metalness?, opacity? }.`);
         }
@@ -381,6 +393,21 @@ function validateObject(raw, i, errors) {
         case 'cone':
             checkNumber(raw.radius, `${label}.radius`, SCENE_RADIUS_MIN, SCENE_RADIUS_MAX, RADIUS_RULE, errors);
             checkNumber(raw.height, `${label}.height`, SCENE_SIZE_MIN, SCENE_SIZE_MAX, SIZE_RULE, errors);
+            if (raw.segments !== undefined) {
+                const rule = `segments is a whole number ${String(SCENE_SEGMENTS_MIN)}–${String(SCENE_SEGMENTS_MAX)} (4 on a cone = a pyramid); omit it for a smooth round ${type}`;
+                if (checkNumber(raw.segments, `${label}.segments`, SCENE_SEGMENTS_MIN, SCENE_SEGMENTS_MAX, rule, errors) &&
+                    !Number.isInteger(raw.segments)) {
+                    errors.push(`${label}.segments = ${fmtNum(raw.segments)} — ${rule}.`);
+                }
+            }
+            break;
+        case 'wedge':
+            checkVec(raw.size, `${label}.size`, 3, SCENE_SIZE_MIN, SCENE_SIZE_MAX, SIZE_RULE, errors);
+            if (raw.ridge !== undefined) {
+                checkNumber(raw.ridge, `${label}.ridge`, 0, 1, 'ridge is 0–1: where the apex sits across the width (0.5 = centred, 0 or 1 = a lean-to)', errors);
+            }
+            break;
+        case 'group':
             break;
         case 'torus': {
             const rOk = checkNumber(raw.radius, `${label}.radius`, SCENE_RADIUS_MIN, SCENE_RADIUS_MAX, RADIUS_RULE, errors);
@@ -388,15 +415,31 @@ function validateObject(raw, i, errors) {
             checkNumber(raw.tube, `${label}.tube`, SCENE_TUBE_MIN, maxTube, `tube is ${fmtNum(SCENE_TUBE_MIN)} m up to the ring radius (a tube wider than its ring self-intersects)`, errors);
             break;
         }
-        case 'extrude':
+        case 'extrude': {
             checkNumber(raw.height, `${label}.height`, SCENE_SIZE_MIN, SCENE_SIZE_MAX, SIZE_RULE, errors);
-            validatePoints(raw.points, `${label}.points`, errors);
+            let axis = 'y';
+            if (raw.axis !== undefined) {
+                if (typeof raw.axis !== 'string' ||
+                    !SCENE_EXTRUDE_AXES.includes(raw.axis)) {
+                    errors.push(`${label}.axis = ${show(raw.axis)} — "y" (default: a plan outline [x, z] rising vertically), "z" (a side profile [x, y] pushed along +z) or "x" (a side profile [z, y] pushed along +x).`);
+                }
+                else
+                    axis = raw.axis;
+            }
+            validatePoints(raw.points, `${label}.points`, errors, axis);
             break;
+        }
     }
 }
-function validatePoints(v, path, errors) {
+/** What an extrude point [a, b] means, per axis — for messages. */
+const POINT_MEANING = {
+    y: '[x, z] plan points',
+    z: '[x, y] side-profile points (axis "z")',
+    x: '[z, y] side-profile points (axis "x")',
+};
+function validatePoints(v, path, errors, axis = 'y') {
     if (!Array.isArray(v)) {
-        errors.push(`${path} = ${show(v)} — an array of [x, z] plan points.`);
+        errors.push(`${path} = ${show(v)} — an array of ${POINT_MEANING[axis]}.`);
         return;
     }
     const before = errors.length;
@@ -435,7 +478,7 @@ function validateGroups(objects, errors) {
             return;
         }
         if (!byId.has(o.group)) {
-            errors.push(`${label}.group = "${o.group}" — no object with that id in the scene.`);
+            errors.push(`${label}.group = "${o.group}" — no object with that id in the scene. Add the parent first (type "group" with your own id), or create it in the same batch; scene_get lists ids.`);
             return;
         }
         // Walk up: cycle / depth.
@@ -614,10 +657,14 @@ export function normalizeScene(scene) {
     const out = JSON.parse(JSON.stringify(scene));
     out.objects = out.objects.map((o, i) => {
         const next = { ...o };
-        next.color =
-            next.color !== undefined
-                ? normalizeColor(next.color)
-                : SCENE_NEUTRAL_PALETTE[i % SCENE_NEUTRAL_PALETTE.length];
+        // A group has no surface: no colour to fill (the palette index stays the array index, so
+        // scenes without groups colour exactly as before).
+        if (next.type !== 'group') {
+            next.color =
+                next.color !== undefined
+                    ? normalizeColor(next.color)
+                    : SCENE_NEUTRAL_PALETTE[i % SCENE_NEUTRAL_PALETTE.length];
+        }
         if (next.rotation) {
             next.rotation = next.rotation.map(normalizeAngle);
         }
@@ -633,12 +680,14 @@ export function normalizeScene(scene) {
 // =============================================================================
 /**
  * Half-height from the object's BOTTOM (its `position.y`) to its geometric centre, where the
- * mesh sits. extrude is 0: its geometry already starts at the floor. ONE function — the
- * viewer, the fit and the GLB export must agree.
+ * mesh sits. extrude along y is 0: its geometry already starts at the floor; along x/z it is
+ * −min(profile y), so the profile's lowest point sits at position.y. A group has no height: 0.
+ * ONE function — the viewer, the fit and the GLB export must agree.
  */
 export function liftFor(obj) {
     switch (obj.type) {
         case 'box':
+        case 'wedge':
             return obj.size[1] / 2;
         case 'sphere':
             return obj.radius;
@@ -647,14 +696,61 @@ export function liftFor(obj) {
             return obj.height / 2;
         case 'torus':
             return obj.tube;
-        case 'extrude':
+        case 'extrude': {
+            if ((obj.axis ?? 'y') === 'y')
+                return 0;
+            const lowest = Math.min(...obj.points.map((p) => p[1]));
+            return lowest === 0 ? 0 : -lowest; // no -0 in matrices/summaries
+        }
+        case 'group':
             return 0;
     }
 }
-/** Local AABB of the mesh around its own origin (the pivot). */
+/**
+ * Extreme x / z of a faceted round shape: vertex k at θ = 2πk/n, x = r·sin θ, z = r·cos θ
+ * (three.js thetaStart 0). Smooth (no segments) → the circle's ±r.
+ */
+function roundExtent(radius, segments) {
+    if (segments === undefined)
+        return { x: [-radius, radius], z: [-radius, radius] };
+    const xs = [];
+    const zs = [];
+    for (let k = 0; k < segments; k++) {
+        const t = (2 * Math.PI * k) / segments;
+        xs.push(radius * Math.sin(t));
+        zs.push(radius * Math.cos(t));
+    }
+    return { x: [Math.min(...xs), Math.max(...xs)], z: [Math.min(...zs), Math.max(...zs)] };
+}
+/**
+ * Mesh-local AABB of an extrude, per axis (see ExtrudeObject): the outline's [a, b] mapped to
+ * world axes, the extrusion 0 → height along the axis. Before the lift.
+ */
+function extrudeBox(obj) {
+    const as = obj.points.map((p) => p[0]);
+    const bs = obj.points.map((p) => p[1]);
+    const [aMin, aMax, bMin, bMax] = [
+        Math.min(...as),
+        Math.max(...as),
+        Math.min(...bs),
+        Math.max(...bs),
+    ];
+    switch (obj.axis ?? 'y') {
+        case 'y': // [x, z] plan → (x, 0..h, z) — the reference mapping (§2.2)
+            return { min: [aMin, 0, bMin], max: [aMax, obj.height, bMax] };
+        case 'z': // [x, y] → (x, y, 0..h)
+            return { min: [aMin, bMin, 0], max: [aMax, bMax, obj.height] };
+        case 'x': // [z, y] → (0..h, y, z)
+            return { min: [0, bMin, aMin], max: [obj.height, bMax, aMax] };
+    }
+}
+/** Local AABB of the mesh around its own origin (the pivot). null for a group (no geometry). */
 function localBox(obj) {
     switch (obj.type) {
-        case 'box': {
+        case 'box':
+        case 'wedge': {
+            // A wedge's triangle spans the full width at its base and the full height at its apex,
+            // so its AABB is exactly the box's, whatever the ridge.
             const [w, h, d] = obj.size;
             return { min: [-w / 2, -h / 2, -d / 2], max: [w / 2, h / 2, d / 2] };
         }
@@ -664,24 +760,21 @@ function localBox(obj) {
                 max: [obj.radius, obj.radius, obj.radius],
             };
         case 'cylinder':
-        case 'cone':
+        case 'cone': {
+            const e = roundExtent(obj.radius, obj.segments);
             return {
-                min: [-obj.radius, -obj.height / 2, -obj.radius],
-                max: [obj.radius, obj.height / 2, obj.radius],
+                min: [e.x[0], -obj.height / 2, e.z[0]],
+                max: [e.x[1], obj.height / 2, e.z[1]],
             };
+        }
         case 'torus': {
             const r = obj.radius + obj.tube;
             return { min: [-r, -obj.tube, -r], max: [r, obj.tube, r] };
         }
-        case 'extrude': {
-            // Plan (x, z) → world (x, y∈[0,h], z) — the reference mapping (§2.2).
-            const xs = obj.points.map((p) => p[0]);
-            const zs = obj.points.map((p) => p[1]);
-            return {
-                min: [Math.min(...xs), 0, Math.min(...zs)],
-                max: [Math.max(...xs), obj.height, Math.max(...zs)],
-            };
-        }
+        case 'extrude':
+            return extrudeBox(obj);
+        case 'group':
+            return null;
     }
 }
 const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
@@ -726,7 +819,8 @@ function objectFrame(obj) {
 }
 /**
  * World matrix of each object's mesh (row-major 4×4), keyed by id, with group parenting
- * applied. Assumes a validated scene (no cycles).
+ * applied. A `group` has no mesh and lift 0, so its entry is its frame: T(position) · R,
+ * rotating about its position. Assumes a validated scene (no cycles).
  */
 export function sceneWorldMatrices(scene) {
     const byId = new Map(scene.objects.map((o) => [o.id, o]));
@@ -746,16 +840,18 @@ export function sceneWorldMatrices(scene) {
         out.set(o.id, mul(frameOf(o), translate(0, liftFor(o), 0)));
     return out;
 }
-/** World-space AABB of all objects (conservative for rotated shapes). null when empty. */
-export function sceneBounds(scene) {
-    if (scene.objects.length === 0)
-        return null;
+/** World AABB of the given objects' meshes. Groups add nothing; null when nothing has geometry. */
+function boundsOf(scene, objects) {
     const mats = sceneWorldMatrices(scene);
     const min = [Infinity, Infinity, Infinity];
     const max = [-Infinity, -Infinity, -Infinity];
-    for (const o of scene.objects) {
-        const m = mats.get(o.id) ?? IDENTITY;
+    let any = false;
+    for (const o of objects) {
         const b = localBox(o);
+        if (!b)
+            continue;
+        any = true;
+        const m = mats.get(o.id) ?? IDENTITY;
         for (const cx of [b.min[0], b.max[0]])
             for (const cy of [b.min[1], b.max[1]])
                 for (const cz of [b.min[2], b.max[2]]) {
@@ -768,7 +864,29 @@ export function sceneBounds(scene) {
                     }
                 }
     }
-    return { min, max };
+    return any ? { min, max } : null;
+}
+/**
+ * World-space AABB of all objects (conservative for rotated shapes). null when nothing has
+ * geometry — an empty scene, or one holding only empty groups (the camera then uses the
+ * reference default, as for an empty scene).
+ */
+export function sceneBounds(scene) {
+    if (scene.objects.length === 0)
+        return null;
+    return boundsOf(scene, scene.objects);
+}
+/**
+ * World AABB of one object and everything grouped under it — for a `group`, the union of its
+ * descendants (null while it holds no geometry); for a shape, its own mesh plus any children.
+ * null for an unknown id. (The viewer outlines a selected group's whole subtree with this.)
+ */
+export function sceneObjectBounds(scene, id) {
+    const self = scene.objects.find((o) => o.id === id);
+    if (!self)
+        return null;
+    const members = new Set([id, ...descendantsOf(scene, id)]);
+    return boundsOf(scene, scene.objects.filter((o) => members.has(o.id)));
 }
 /** The reference view direction ([7, 5.5, 8], normalised). */
 export const SCENE_CAMERA_DIRECTION = (() => {
@@ -802,11 +920,13 @@ export function fitCamera(bounds, fovDeg = SCENE_CAMERA_FOV) {
 export function sceneCamera(scene) {
     return scene.camera ?? fitCamera(sceneBounds(scene));
 }
-/** One line: "12 objects, bounds 6.2 × 4 × 2.7 m" (W × D × H). */
+/** One line: "12 objects (2 groups), bounds 6.2 × 4 × 2.7 m" (W × D × H). */
 export function describeScene(scene) {
     const n = scene.objects.length;
+    const g = scene.objects.filter((o) => o.type === 'group').length;
     const b = sceneBounds(scene);
-    const count = `${String(n)} object${n === 1 ? '' : 's'}`;
+    const groups = g > 0 ? ` (${String(g)} group${g === 1 ? '' : 's'})` : '';
+    const count = `${String(n)} object${n === 1 ? '' : 's'}${groups}`;
     if (!b)
         return count;
     const w = b.max[0] - b.min[0];

package/dist/capabilities/packs.js

@@ -285,11 +285,17 @@ export const CAPABILITY_PACKS = {
         promptModules: ['platform-tool-hints'],
         promptSnippet: "3D scenes are JSON, not code. Units metres; position.y is the object's BOTTOM (0 = on the floor); " +
             'rotation in degrees (rotate about Y). Types: box(size w,h,d), sphere(radius), cylinder/cone(radius, ' +
-            'height), torus(radius, tube; flat), extrude(points [[x,z],…], height) for walls and floors. Read with ' +
-            'scene_get before editing — the user edits too. Add up to 50 objects per scene_add_object call ' +
-            '(objects: [...]). Keep neutral colours unless asked. After building, scene_screenshot to check.',
-        estimatedPromptTokens: 120,
-        estimatedToolTokens: 1400,
+            'height, segments?), torus(radius, tube; flat), extrude(points, height, axis?) for walls and floors, ' +
+            'wedge(size, ridge?), group (a container, no geometry). BUILD HIERARCHICALLY: give groups your own ids ' +
+            'and nest the parts, e.g. house → walls, roof, doors, furniture — one scene_add_object batch per group ' +
+            '(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,
+        estimatedToolTokens: 3000,
     },
     plans: {
         id: 'plans',

package/dist/index.d.ts

@@ -96,8 +96,8 @@ export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createL
 export { classifyAgentError, isApiKeyError } from './errors/classify.js';
 export type { AgentErrorCategory, AgentErrorInfo } from './errors/classify.js';
 export { validateControlManifest, seedValues } from './canvas/index.js';
-export { validateScene, normalizeScene, serializeScene, emptyScene, sceneBounds, fitCamera, liftFor, describeScene, applySceneOp, applySceneOps, formatUserEditNotice, SCENE_MAX_OBJECTS, SCENE_MAX_BYTES, SCENE_MAX_BATCH, HTML_CANVAS_TYPES, } from './canvas/index.js';
-export type { HtmlCanvasType, SceneFile, SceneObject, SceneObjectType, SceneCamera, SceneLight, SceneMaterial, SceneOp, SceneChange, SceneEditSource, } from './canvas/index.js';
+export { validateScene, normalizeScene, serializeScene, emptyScene, sceneBounds, sceneObjectBounds, fitCamera, liftFor, describeScene, applySceneOp, applySceneOps, formatUserEditNotice, SCENE_MAX_OBJECTS, SCENE_MAX_BYTES, SCENE_MAX_BATCH, HTML_CANVAS_TYPES, } from './canvas/index.js';
+export type { HtmlCanvasType, SceneFile, SceneObject, SceneObjectType, ExtrudeAxis, GroupObject, WedgeObject, SceneCamera, SceneLight, SceneMaterial, SceneOp, SceneChange, SceneEditSource, } from './canvas/index.js';
 export type { ISceneWriter, SceneReadResult, SceneApplyResult, SceneCreateResult, SceneLastEdit, } from './platform/index.js';
 export type { CanvasType, ParamValue, Control, ControlManifest, CanvasRecord, CanvasSummary, CreateCanvasInput, UpdateCanvasInput, SliderControl, NumberControl, ToggleControl, SelectControl, ColorControl, TextControl, ManifestValidationResult, } from './canvas/index.js';
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, PermissionHandlerResponse, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';

package/dist/index.js

@@ -208,7 +208,7 @@ export { classifyAgentError, isApiKeyError } from './errors/classify.js';
 // Also exposed at the renderer-safe subpath `@compilr-dev/sdk/canvas`.
 export { validateControlManifest, seedValues } from './canvas/index.js';
 // 3D scenes (the `scene` canvas type) — contract + pure ops. Also at `@compilr-dev/sdk/canvas`.
-export { validateScene, normalizeScene, serializeScene, emptyScene, sceneBounds, fitCamera, liftFor, describeScene, applySceneOp, applySceneOps, formatUserEditNotice, SCENE_MAX_OBJECTS, SCENE_MAX_BYTES, SCENE_MAX_BATCH, HTML_CANVAS_TYPES, } from './canvas/index.js';
+export { validateScene, normalizeScene, serializeScene, emptyScene, sceneBounds, sceneObjectBounds, fitCamera, liftFor, describeScene, applySceneOp, applySceneOps, formatUserEditNotice, SCENE_MAX_OBJECTS, SCENE_MAX_BYTES, SCENE_MAX_BATCH, HTML_CANVAS_TYPES, } from './canvas/index.js';
 // =============================================================================
 // Shared Permission Defaults & Utilities
 // =============================================================================

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

@@ -40,11 +40,31 @@ export function sceneOutline(scene) {
         list.push(o);
         byParent.set(key, list);
     }
+    /** The type column, with what changes its shape: "group (3 inside)", "cone (4 sides)", … */
+    const typeOf = (o) => {
+        switch (o.type) {
+            case 'group': {
+                const n = byParent.get(o.id)?.length ?? 0;
+                return n === 0 ? 'group (empty)' : `group (${String(n)} inside)`;
+            }
+            case 'cone':
+            case 'cylinder':
+                return o.segments !== undefined ? `${o.type} (${String(o.segments)} sides)` : o.type;
+            case 'extrude':
+                return o.axis !== undefined && o.axis !== 'y' ? `extrude (along ${o.axis})` : o.type;
+            case 'wedge':
+                return o.ridge !== undefined && o.ridge !== 0.5
+                    ? `wedge (ridge ${String(o.ridge)})`
+                    : o.type;
+            default:
+                return o.type;
+        }
+    };
     const rows = [];
     const walk = (parent, depth) => {
         for (const o of byParent.get(parent) ?? []) {
             const lock = o.locked ? ' · locked' : '';
-            rows.push(`${'  '.repeat(depth)}${o.id} · ${o.type}${o.name ? ` · ${o.name}` : ''}${lock}`);
+            rows.push(`${'  '.repeat(depth)}${o.id} · ${typeOf(o)}${o.name ? ` · ${o.name}` : ''}${lock}`);
             if (depth < 8)
                 walk(o.id, depth + 1);
         }
@@ -88,8 +108,10 @@ const OBJECT_PROPERTIES = {
     type: {
         type: 'string',
         enum: SCENE_OBJECT_TYPES,
-        description: 'box (size [w,h,d]) · sphere (radius) · cylinder / cone (radius, height) · torus (radius, tube; lies flat) · ' +
-            'extrude (points [[x,z],…] + height) for walls and floors. There is no "wall" type — use extrude.',
+        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.',
     },
     position: {
         ...VEC3,
@@ -97,17 +119,49 @@ const OBJECT_PROPERTIES = {
     },
     id: {
         type: 'string',
-        description: 'Optional stable id (lowercase, digits, - or _; ≤ 48). Omit to generate one from name.',
+        description: 'Your own id (lowercase letters, digits, - or _; ≤ 48), e.g. "house", "roof-left". Choose ids for ' +
+            'groups so later objects — even in the same batch — can say group: "<id>". Must be new: an id already ' +
+            'in the scene is an error (never renamed). Omit to generate one from name.',
     },
     name: { type: 'string', description: 'Display name (≤ 80 chars), e.g. "Sofa".' },
-    size: { ...VEC3, description: 'box only: [width, height, depth] in metres (0.01–500).' },
-    radius: { type: 'number', description: 'sphere/cylinder/cone/torus: radius in metres.' },
-    height: { type: 'number', description: 'cylinder/cone/extrude: height in metres.' },
+    size: {
+        ...VEC3,
+        description: 'box / wedge: [width (x), height (y), depth (z)] in metres (0.01–500).',
+    },
+    radius: {
+        type: 'number',
+        description: 'sphere/cylinder/cone/torus: radius in metres. With segments it is the corner (circum-) radius.',
+    },
+    height: {
+        type: 'number',
+        description: 'cylinder/cone: height in metres. extrude: how far it extends along its axis.',
+    },
     tube: { type: 'number', description: 'torus only: tube radius (≤ radius).' },
+    segments: {
+        type: 'integer',
+        minimum: 3,
+        maximum: 64,
+        description: 'cone/cylinder only: number of flat sides (3–64); omit for smooth. cone + 4 = a pyramid (hip roof) — ' +
+            'its corners point along ±x/±z, so add rotation [0, 45, 0] for sides parallel to the axes (side = radius·√2).',
+    },
     points: {
         type: 'array',
         items: { type: 'array', items: { type: 'number' }, minItems: 2, maxItems: 2 },
-        description: 'extrude only: plan outline [[x, z], …] local to position, 3–256 points, not self-intersecting.',
+        description: 'extrude only: outline [[a, b], …] local to position, 3–256 points, not self-intersecting. ' +
+            'axis "y" (default): [x, z] plan points, rising 0 → height. axis "z": [x, y] side profile ' +
+            '(b is up), pushed 0 → height along +z. axis "x": [z, y] side profile (b is up), pushed 0 → height along +x. ' +
+            "The profile's lowest point sits at position.y.",
+    },
+    axis: {
+        type: 'string',
+        enum: ['x', 'y', 'z'],
+        description: 'extrude only: the direction it extends. "y" (default) = a plan outline rising vertically (walls, floors); ' +
+            '"x" / "z" = a side profile (a gable, a roof section) extended horizontally — see points.',
+    },
+    ridge: {
+        type: 'number',
+        description: 'wedge only: where the apex sits across the width, 0–1 (default 0.5 = centred; 0 or 1 = a lean-to). ' +
+            'The triangle is in the x–y plane; the ridge runs along z (the depth). Rotate [0, 90, 0] for a ridge along x.',
     },
     rotation: {
         ...VEC3,
@@ -115,15 +169,16 @@ const OBJECT_PROPERTIES = {
     },
     color: {
         type: 'string',
-        description: '"#RRGGBB". Omit for the neutral palette — keep neutral colours unless asked.',
+        description: '"#RRGGBB". Omit for the neutral palette — keep neutral colours unless asked. Not on a group.',
     },
     group: {
         type: 'string',
-        description: "Parent object id. position/rotation become relative to the parent (y = 0 is the parent's bottom).",
+        description: 'Parent id — normally a type "group" container, created earlier or in the same batch. position/rotation ' +
+            "become relative to the parent (y = 0 is the group's y); moving the group moves its children.",
     },
     material: {
         type: 'object',
-        description: '{ roughness 0–1, metalness 0–1, opacity 0.05–1 }.',
+        description: '{ roughness 0–1, metalness 0–1, opacity 0.05–1 }. Not on a group.',
         properties: {
             roughness: { type: 'number' },
             metalness: { type: 'number' },
@@ -257,7 +312,9 @@ export function createSceneTools(config, options) {
         name: 'scene_add_object',
         description: 'Add one object to a 3D scene, or up to 50 at once with objects: [...] (atomic: all or none). ' +
             "Units are metres; position.y is the object's BOTTOM (0 = on the floor); rotation in degrees about Y. " +
-            'Returns the new id(s) — generated from name when id is omitted.',
+            'Build hierarchically: a type "group" with your own id (e.g. "house", then "walls", "roof" inside it), ' +
+            'and its parts with group: "<id>" — a batch may name a group it creates itself. ' +
+            'Returns the new id(s) — yours, or generated from name when id is omitted.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -315,7 +372,9 @@ export function createSceneTools(config, options) {
                 id: { type: 'string', description: 'The object id to change.' },
                 patch: {
                     type: 'object',
-                    description: 'Fields to set, e.g. { "position": [1.2, 0, -0.4], "color": "#8FA3B0" }. Same fields as scene_add_object.',
+                    description: 'Fields to set, e.g. { "position": [1.2, 0, -0.4], "color": "#8FA3B0" }. Same fields as scene_add_object: ' +
+                        'size, radius, height, tube, points, segments (cone/cylinder), axis (extrude), ridge (wedge), group ' +
+                        '(move it into a group; null = back to the root), name, rotation, color/material (not on a group), locked.',
                 },
             },
             required: ['canvas_id', 'id', 'patch'],

package/package.json

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