@compilr-dev/sdk 0.29.8 → 0.31.0

package/dist/canvas/scene.js

@@ -0,0 +1,963 @@
+/**
+ * 3D scene contract — the `scene` canvas type (3d-canvas-spec §2).
+ *
+ * A scene is VALIDATED JSON DATA, never code: a list of primitives in metres. Agents write
+ * it through the scene tools; the host draws it (three.js in Desktop's renderer). This module
+ * is the contract both sides bind to — types, limits, validation, normalisation and the few
+ * pieces of geometry (lift, bounds, fit) that must be ONE function everywhere.
+ *
+ * ⚠️ Renderer-safe on purpose: no imports at all. Desktop's renderer imports this through
+ * `@compilr-dev/sdk/canvas`; one node import here breaks its bundle (see
+ * `tests/canvas-subpath.test.ts`).
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export const SCENE_VERSION = 1;
+export const SCENE_OBJECT_TYPES = [
+    'box',
+    'sphere',
+    'cylinder',
+    'cone',
+    'torus',
+    'extrude',
+    'wedge',
+    'group',
+];
+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;
+export const SCENE_MAX_BYTES = 512 * 1024;
+/** Max objects in one scene_add_object batch (Q-1). */
+export const SCENE_MAX_BATCH = 50;
+export const SCENE_MAX_COORD = 1000;
+export const SCENE_SIZE_MIN = 0.01;
+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;
+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;
+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. */
+export const SCENE_NEUTRAL_PALETTE = [
+    '#D6D3CE',
+    '#A8A29E',
+    '#57534E',
+    '#C9B8A3',
+    '#8FA3B0',
+    '#B8B2A8',
+    '#7C8A6E',
+];
+/** Accessible names for the palette swatches, same order (Q-10). */
+export const SCENE_PALETTE_NAMES = [
+    'Stone',
+    'Taupe',
+    'Charcoal',
+    'Sand',
+    'Slate',
+    'Ash',
+    'Moss',
+];
+export const SCENE_DEFAULT_MATERIAL = {
+    roughness: 0.78,
+    metalness: 0.02,
+    opacity: 1,
+};
+/** The reference camera, used for an empty scene. */
+export const SCENE_DEFAULT_CAMERA = {
+    position: [7, 5.5, 8],
+    target: [0, 0.6, 0],
+};
+/** Vertical field of view of the viewer camera, degrees. */
+export const SCENE_CAMERA_FOV = 38;
+/** A new, empty scene. */
+export function emptyScene(name) {
+    return {
+        version: SCENE_VERSION,
+        name: name.trim().slice(0, SCENE_NAME_MAX) || 'Scene',
+        units: 'm',
+        objects: [],
+    };
+}
+/**
+ * Defaults for a freshly added shape of each type (the reference's fallbacks), for the
+ * inspector's "Add a shape" menu. Position is the origin.
+ */
+export function defaultObjectFor(type, id) {
+    const base = { id, position: [0, 0, 0] };
+    switch (type) {
+        case 'box':
+            return { ...base, type, size: [1, 1, 1] };
+        case 'sphere':
+            return { ...base, type, radius: 0.5 };
+        case 'cylinder':
+            return { ...base, type, radius: 0.5, height: 1 };
+        case 'cone':
+            return { ...base, type, radius: 0.5, height: 1 };
+        case 'torus':
+            return { ...base, type, radius: 0.6, tube: 0.18 };
+        case 'extrude':
+            return {
+                ...base,
+                type,
+                points: [
+                    [0, 0],
+                    [1, 0],
+                    [1, 1],
+                    [0, 1],
+                ],
+                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). */
+export function serializeScene(scene) {
+    return JSON.stringify(scene, null, 2);
+}
+/** `slug(title).scene.json` — the display file name and the JSON export's default name. */
+export function sceneFileName(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `${slug || 'scene'}.scene.json`;
+}
+/** UTF-8 byte length without TextEncoder (keeps this module free of DOM/node typings). */
+export function utf8Bytes(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const c = s.charCodeAt(i);
+        if (c < 0x80)
+            n += 1;
+        else if (c < 0x800)
+            n += 2;
+        else if (c >= 0xd800 && c <= 0xdbff) {
+            n += 4;
+            i++;
+        }
+        else
+            n += 3;
+    }
+    return n;
+}
+const TOP_KEYS = new Set(['version', 'name', 'units', 'camera', 'lights', 'objects']);
+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', 'segments'],
+    cone: ['radius', 'height', 'segments'],
+    torus: ['radius', 'tube'],
+    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, height and optional segments',
+    cone: 'cone takes radius, height and optional segments',
+    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',
+};
+const MATERIAL_KEYS = new Set(['roughness', 'metalness', 'opacity']);
+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) {
+    return String(Math.round(n * 1000) / 1000);
+}
+export function fmtVec(v) {
+    return `[${v.map(fmtNum).join(', ')}]`;
+}
+function show(v) {
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? fmtNum(v) : String(v);
+    if (typeof v === 'string')
+        return JSON.stringify(v);
+    if (v === undefined)
+        return 'missing';
+    try {
+        const s = JSON.stringify(v);
+        return s.length > 60 ? `${s.slice(0, 57)}...` : s;
+    }
+    catch {
+        return '(unprintable)';
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** A finite number within [min, max]; pushes an error naming the path otherwise. */
+function checkNumber(v, path, min, max, rule, errors) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        errors.push(`${path} = ${show(v)} — must be a finite number (${rule}).`);
+        return false;
+    }
+    if (v < min || v > max) {
+        errors.push(`${path} = ${fmtNum(v)} — ${rule}.`);
+        return false;
+    }
+    return true;
+}
+function checkVec(v, path, len, min, max, rule, errors) {
+    if (!Array.isArray(v) || v.length !== len) {
+        errors.push(`${path} = ${show(v)} — must be an array of ${String(len)} numbers (${rule}).`);
+        return false;
+    }
+    let ok = true;
+    v.forEach((n, i) => {
+        if (!checkNumber(n, `${path}[${String(i)}]`, min, max, rule, errors))
+            ok = false;
+    });
+    return ok;
+}
+const COORD_RULE = `coordinates are metres within ±${String(SCENE_MAX_COORD)}`;
+const SIZE_RULE = `sizes are ${fmtNum(SCENE_SIZE_MIN)}–${fmtNum(SCENE_SIZE_MAX)} m. Heights are in metres, not cm`;
+const RADIUS_RULE = `radii are ${fmtNum(SCENE_RADIUS_MIN)}–${fmtNum(SCENE_RADIUS_MAX)} m`;
+function checkCoord(v, path, errors) {
+    return checkVec(v, path, 3, -SCENE_MAX_COORD, SCENE_MAX_COORD, COORD_RULE, errors);
+}
+/** Drop a closing duplicate of the first point (§2.3: dropped, not rejected). */
+export function openOutline(points) {
+    if (points.length >= 2) {
+        const a = points[0];
+        const b = points[points.length - 1];
+        if (a[0] === b[0] && a[1] === b[1])
+            return points.slice(0, -1);
+    }
+    return points;
+}
+const EPS = 1e-9;
+function orient(a, b, c) {
+    const v = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+    return Math.abs(v) < EPS ? 0 : v > 0 ? 1 : -1;
+}
+function onSegment(a, b, p) {
+    return (Math.min(a[0], b[0]) - EPS <= p[0] &&
+        p[0] <= Math.max(a[0], b[0]) + EPS &&
+        Math.min(a[1], b[1]) - EPS <= p[1] &&
+        p[1] <= Math.max(a[1], b[1]) + EPS);
+}
+function segmentsIntersect(p1, p2, p3, p4) {
+    const d1 = orient(p3, p4, p1);
+    const d2 = orient(p3, p4, p2);
+    const d3 = orient(p1, p2, p3);
+    const d4 = orient(p1, p2, p4);
+    if (d1 !== d2 && d3 !== d4 && d1 !== 0 && d2 !== 0 && d3 !== 0 && d4 !== 0)
+        return true;
+    if (d1 === 0 && onSegment(p3, p4, p1))
+        return true;
+    if (d2 === 0 && onSegment(p3, p4, p2))
+        return true;
+    if (d3 === 0 && onSegment(p1, p2, p3))
+        return true;
+    if (d4 === 0 && onSegment(p1, p2, p4))
+        return true;
+    return false;
+}
+/** Adjacent edges a→b, b→c fold back onto each other (collinear, c heading back over a→b). */
+function foldsBack(a, b, c) {
+    if (orient(a, b, c) !== 0)
+        return false;
+    const dot = (a[0] - b[0]) * (c[0] - b[0]) + (a[1] - b[1]) * (c[1] - b[1]);
+    return dot > 0;
+}
+/**
+ * Is the (open) outline a simple polygon? O(n²) segment test — ExtrudeGeometry's
+ * triangulation silently breaks on self-intersection. Returns the first offending edge pair.
+ */
+export function findSelfIntersection(points) {
+    const n = points.length;
+    for (let i = 0; i < n; i++) {
+        const a = points[i];
+        const b = points[(i + 1) % n];
+        // Adjacent edge (shares b): only a fold-back overlaps.
+        if (foldsBack(a, b, points[(i + 2) % n]))
+            return [i, (i + 1) % n];
+        for (let j = i + 2; j < n; j++) {
+            if (i === 0 && j === n - 1)
+                continue; // adjacent through the closing vertex
+            if (segmentsIntersect(a, b, points[j], points[(j + 1) % n]))
+                return [i, j];
+        }
+    }
+    return null;
+}
+function objectLabel(i, raw) {
+    return typeof raw.id === 'string' && raw.id
+        ? `objects[${String(i)}] ("${raw.id}")`
+        : `objects[${String(i)}]`;
+}
+function validateObject(raw, i, errors) {
+    const at = `objects[${String(i)}]`;
+    if (!isRecord(raw)) {
+        errors.push(`${at} = ${show(raw)} — each object must be a JSON object.`);
+        return;
+    }
+    const label = objectLabel(i, raw);
+    const t = raw.type;
+    if (t === 'wall') {
+        errors.push(`${label}.type = "wall" — use type "extrude" with points [[x,z],…] and height for walls.`);
+        return;
+    }
+    if (typeof t !== 'string' || !SCENE_OBJECT_TYPES.includes(t)) {
+        errors.push(`${label}.type = ${show(t)} — must be one of ${SCENE_OBJECT_TYPES.join(', ')}.`);
+        return;
+    }
+    const type = t;
+    // Unknown keys: rejected, because they would round-trip silently and read as honoured.
+    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]}.`);
+        }
+    }
+    if (typeof raw.id !== 'string' || !SCENE_ID_PATTERN.test(raw.id)) {
+        errors.push(`${at}.id = ${show(raw.id)} — ids are 1–48 chars of lowercase letters, digits, "-" or "_", starting with a letter or digit.`);
+    }
+    if (raw.name !== undefined) {
+        if (typeof raw.name !== 'string' || raw.name.length < 1 || raw.name.length > SCENE_NAME_MAX) {
+            errors.push(`${label}.name = ${show(raw.name)} — a string of 1–${String(SCENE_NAME_MAX)} chars.`);
+        }
+    }
+    checkCoord(raw.position, `${label}.position`, 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 (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.`);
+        }
+    }
+    if (raw.group !== undefined && typeof raw.group !== 'string') {
+        errors.push(`${label}.group = ${show(raw.group)} — the parent object's id (a string).`);
+    }
+    if (raw.locked !== undefined && typeof raw.locked !== 'boolean') {
+        errors.push(`${label}.locked = ${show(raw.locked)} — true or false.`);
+    }
+    if (type !== 'group' && raw.material !== undefined) {
+        if (!isRecord(raw.material)) {
+            errors.push(`${label}.material = ${show(raw.material)} — { roughness?, metalness?, opacity? }.`);
+        }
+        else {
+            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.`);
+                }
+            }
+            if (m.roughness !== undefined)
+                checkNumber(m.roughness, `${label}.material.roughness`, 0, 1, 'roughness is 0–1', errors);
+            if (m.metalness !== undefined)
+                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);
+        }
+    }
+    // Type-specific dimensions.
+    switch (type) {
+        case 'box':
+            checkVec(raw.size, `${label}.size`, 3, SCENE_SIZE_MIN, SCENE_SIZE_MAX, SIZE_RULE, errors);
+            break;
+        case 'sphere':
+            checkNumber(raw.radius, `${label}.radius`, SCENE_RADIUS_MIN, SCENE_RADIUS_MAX, RADIUS_RULE, errors);
+            break;
+        case 'cylinder':
+        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);
+            const maxTube = rOk ? raw.radius : SCENE_RADIUS_MAX;
+            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': {
+            checkNumber(raw.height, `${label}.height`, SCENE_SIZE_MIN, SCENE_SIZE_MAX, SIZE_RULE, 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;
+        }
+    }
+}
+/** 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 ${POINT_MEANING[axis]}.`);
+        return;
+    }
+    const before = errors.length;
+    v.forEach((p, i) => {
+        checkVec(p, `${path}[${String(i)}]`, 2, -SCENE_MAX_COORD, SCENE_MAX_COORD, COORD_RULE, errors);
+    });
+    if (errors.length > before)
+        return;
+    const pts = openOutline(v);
+    if (pts.length < SCENE_POINTS_MIN || pts.length > SCENE_POINTS_MAX) {
+        errors.push(`${path} has ${String(pts.length)} points — an outline needs ${String(SCENE_POINTS_MIN)}–${String(SCENE_POINTS_MAX)} (a closing repeat of the first point is not counted).`);
+        return;
+    }
+    for (let i = 0; i + 1 < pts.length; i++) {
+        if (pts[i][0] === pts[i + 1][0] && pts[i][1] === pts[i + 1][1]) {
+            errors.push(`${path}[${String(i + 1)}] repeats the previous point ${fmtVec(pts[i])} — remove it.`);
+            return;
+        }
+    }
+    const hit = findSelfIntersection(pts);
+    if (hit) {
+        errors.push(`${path} is not a simple polygon — edge ${String(hit[0])}→${String(hit[0] + 1)} crosses or overlaps edge ${String(hit[1])}→${String(hit[1] + 1)}. Outlines must not self-intersect; split it into two extrudes.`);
+    }
+}
+function validateGroups(objects, errors) {
+    const byId = new Map();
+    for (const o of objects)
+        if (typeof o.id === 'string')
+            byId.set(o.id, o);
+    objects.forEach((o, i) => {
+        if (typeof o.group !== 'string')
+            return;
+        const label = objectLabel(i, o);
+        if (o.group === o.id) {
+            errors.push(`${label}.group = "${o.group}" — an object cannot be its own parent.`);
+            return;
+        }
+        if (!byId.has(o.group)) {
+            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.
+        const seen = new Set([String(o.id)]);
+        let cur = o.group;
+        let depth = 0;
+        while (cur !== undefined) {
+            depth++;
+            if (seen.has(cur)) {
+                errors.push(`${label}.group = "${o.group}" — the group chain loops back through "${cur}".`);
+                return;
+            }
+            if (depth > SCENE_MAX_GROUP_DEPTH) {
+                errors.push(`${label}.group — groups nest at most ${String(SCENE_MAX_GROUP_DEPTH)} deep.`);
+                return;
+            }
+            seen.add(cur);
+            const parent = byId.get(cur);
+            cur = parent && typeof parent.group === 'string' ? parent.group : undefined;
+        }
+    });
+}
+function validateLights(v, errors) {
+    if (!Array.isArray(v)) {
+        errors.push(`lights = ${show(v)} — an array of { type: "sun" | "ambient", … }.`);
+        return;
+    }
+    if (v.length > SCENE_MAX_LIGHTS) {
+        errors.push(`lights has ${String(v.length)} entries (max ${String(SCENE_MAX_LIGHTS)}).`);
+    }
+    let shadows = 0;
+    v.forEach((l, i) => {
+        const at = `lights[${String(i)}]`;
+        if (!isRecord(l)) {
+            errors.push(`${at} = ${show(l)} — must be a JSON object.`);
+            return;
+        }
+        if (l.type === 'sun') {
+            for (const k of Object.keys(l)) {
+                if (!['type', 'position', 'intensity', 'castShadow'].includes(k))
+                    errors.push(`${at}.${k} is not a sun-light field — position, intensity, castShadow.`);
+            }
+            checkCoord(l.position, `${at}.position`, errors);
+            if (l.castShadow !== undefined && typeof l.castShadow !== 'boolean') {
+                errors.push(`${at}.castShadow = ${show(l.castShadow)} — true or false.`);
+            }
+            if (l.castShadow === true)
+                shadows++;
+        }
+        else if (l.type === 'ambient') {
+            for (const k of Object.keys(l)) {
+                if (!['type', 'intensity'].includes(k))
+                    errors.push(`${at}.${k} is not an ambient-light field — intensity.`);
+            }
+        }
+        else {
+            errors.push(`${at}.type = ${show(l.type)} — "sun" or "ambient".`);
+            return;
+        }
+        if (l.intensity !== undefined) {
+            checkNumber(l.intensity, `${at}.intensity`, 0, SCENE_LIGHT_INTENSITY_MAX, `intensity is 0–${String(SCENE_LIGHT_INTENSITY_MAX)}`, errors);
+        }
+    });
+    if (shadows > SCENE_MAX_SHADOW_LIGHTS) {
+        errors.push(`lights: ${String(shadows)} lights cast shadows (max ${String(SCENE_MAX_SHADOW_LIGHTS)} — each costs a render pass).`);
+    }
+}
+/**
+ * Validate an untrusted scene (agent JSON, a stored row, an import). Every error names the
+ * field path and what is allowed. On success the returned scene is a deep copy of the input
+ * (not yet normalised — see `normalizeScene`).
+ */
+export function validateScene(input) {
+    const errors = [];
+    if (!isRecord(input)) {
+        return {
+            ok: false,
+            errors: ['The scene must be a JSON object { version, name, units, objects }.'],
+        };
+    }
+    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.`);
+        }
+    }
+    if (input.version !== SCENE_VERSION) {
+        errors.push(`version = ${show(input.version)} — must be ${String(SCENE_VERSION)}.`);
+    }
+    if (input.units !== 'm') {
+        errors.push(`units = ${show(input.units)} — only "m" (metres) in v1.`);
+    }
+    if (typeof input.name !== 'string' ||
+        input.name.trim().length < 1 ||
+        input.name.length > SCENE_NAME_MAX) {
+        errors.push(`name = ${show(input.name)} — a string of 1–${String(SCENE_NAME_MAX)} chars.`);
+    }
+    if (input.camera !== undefined) {
+        if (!isRecord(input.camera)) {
+            errors.push(`camera = ${show(input.camera)} — { position: [x, y, z], target: [x, y, z] }.`);
+        }
+        else {
+            for (const k of Object.keys(input.camera)) {
+                if (k !== 'position' && k !== 'target')
+                    errors.push(`camera.${k} is not a camera field — position, target.`);
+            }
+            checkCoord(input.camera.position, 'camera.position', errors);
+            checkCoord(input.camera.target, 'camera.target', errors);
+        }
+    }
+    if (input.lights !== undefined)
+        validateLights(input.lights, errors);
+    if (!Array.isArray(input.objects)) {
+        errors.push(`objects = ${show(input.objects)} — must be an array.`);
+        return { ok: false, errors };
+    }
+    const objects = input.objects;
+    if (objects.length > SCENE_MAX_OBJECTS) {
+        errors.push(`Scene would have ${String(objects.length)} objects (max ${String(SCENE_MAX_OBJECTS)}). Merge repeated parts or split the scene into two canvases (scene_create).`);
+        return { ok: false, errors };
+    }
+    const seen = new Map();
+    objects.forEach((o, i) => {
+        validateObject(o, i, errors);
+        if (isRecord(o) && typeof o.id === 'string') {
+            const prev = seen.get(o.id);
+            if (prev !== undefined) {
+                errors.push(`objects[${String(i)}].id = "${o.id}" — duplicate of objects[${String(prev)}]; ids must be unique.`);
+            }
+            else
+                seen.set(o.id, i);
+        }
+    });
+    validateGroups(objects.filter(isRecord), errors);
+    if (errors.length === 0) {
+        const text = JSON.stringify(input, null, 2);
+        const bytes = utf8Bytes(text);
+        if (bytes > SCENE_MAX_BYTES) {
+            errors.push(`The scene serialises to ${String(Math.round(bytes / 1024))} KB (max ${String(SCENE_MAX_BYTES / 1024)} KB). Simplify outlines or split the scene into two canvases (scene_create).`);
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, scene: JSON.parse(JSON.stringify(input)) };
+}
+// =============================================================================
+// Normalisation (what the writer owns)
+// =============================================================================
+/** '#abc' / '#aabbcc' → '#AABBCC'. Assumes a valid hex (validated first). */
+export function normalizeColor(hex) {
+    const h = hex.slice(1);
+    const full = h.length === 3
+        ? h
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : h;
+    return `#${full.toUpperCase()}`;
+}
+/** Degrees → (−180, 180]. */
+export function normalizeAngle(deg) {
+    let a = deg % 360;
+    if (a <= -180)
+        a += 360;
+    else if (a > 180)
+        a -= 360;
+    // Avoid -0 in the stored JSON.
+    return a === 0 ? 0 : a;
+}
+/**
+ * Fill what the writer owns: upper-case #RRGGBB colours, the neutral default colour by
+ * insertion index (so the stored file is explicit and agent-readable), rotations wrapped to
+ * (−180, 180], closing duplicate points dropped. Never fills camera/lights — their absence
+ * means "fit" / "studio light". Pure; returns a new scene.
+ */
+export function normalizeScene(scene) {
+    const out = JSON.parse(JSON.stringify(scene));
+    out.objects = out.objects.map((o, i) => {
+        const next = { ...o };
+        // 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);
+        }
+        if (next.type === 'extrude') {
+            next.points = openOutline(next.points);
+        }
+        return next;
+    });
+    return out;
+}
+// =============================================================================
+// Geometry shared by viewer, fit and export
+// =============================================================================
+/**
+ * Half-height from the object's BOTTOM (its `position.y`) to its geometric centre, where the
+ * 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;
+        case 'cylinder':
+        case 'cone':
+            return obj.height / 2;
+        case 'torus':
+            return obj.tube;
+        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;
+    }
+}
+/**
+ * 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 '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] };
+        }
+        case 'sphere':
+            return {
+                min: [-obj.radius, -obj.radius, -obj.radius],
+                max: [obj.radius, obj.radius, obj.radius],
+            };
+        case 'cylinder':
+        case 'cone': {
+            const e = roundExtent(obj.radius, obj.segments);
+            return {
+                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':
+            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];
+function mul(a, b) {
+    const r = new Array(16).fill(0);
+    for (let i = 0; i < 4; i++)
+        for (let j = 0; j < 4; j++)
+            for (let k = 0; k < 4; k++)
+                r[i * 4 + j] += a[i * 4 + k] * b[k * 4 + j];
+    return r;
+}
+function translate(x, y, z) {
+    return [1, 0, 0, x, 0, 1, 0, y, 0, 0, 1, z, 0, 0, 0, 1];
+}
+/** Euler XYZ (three.js default): R = Rx · Ry · Rz. */
+function rotateXYZ(deg) {
+    const [x, y, z] = deg.map((d) => (d * Math.PI) / 180);
+    const cx = Math.cos(x), sx = Math.sin(x), cy = Math.cos(y), sy = Math.sin(y), cz = Math.cos(z), sz = Math.sin(z);
+    const rx = [1, 0, 0, 0, 0, cx, -sx, 0, 0, sx, cx, 0, 0, 0, 0, 1];
+    const ry = [cy, 0, sy, 0, 0, 1, 0, 0, -sy, 0, cy, 0, 0, 0, 0, 1];
+    const rz = [cz, -sz, 0, 0, sz, cz, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+    return mul(mul(rx, ry), rz);
+}
+function apply(m, p) {
+    return [
+        m[0] * p[0] + m[1] * p[1] + m[2] * p[2] + m[3],
+        m[4] * p[0] + m[5] * p[1] + m[6] * p[2] + m[7],
+        m[8] * p[0] + m[9] * p[1] + m[10] * p[2] + m[11],
+    ];
+}
+/**
+ * An object's FRAME (Q-3): origin at its bottom point (`position`), rotated about its
+ * geometric centre. Children are placed in this frame, so a child's y = 0 sits at the
+ * parent's bottom. As matrices: T(position) · T(0, lift, 0) · R · T(0, −lift, 0).
+ * The mesh itself is frame · T(0, lift, 0) — for a root object that is exactly the
+ * reference: the mesh at position + lift, rotated about its centre.
+ */
+function objectFrame(obj) {
+    const lift = liftFor(obj);
+    const [x, y, z] = obj.position;
+    return mul(mul(mul(translate(x, y, z), translate(0, lift, 0)), rotateXYZ(obj.rotation ?? [0, 0, 0])), translate(0, -lift, 0));
+}
+/**
+ * World matrix of each object's mesh (row-major 4×4), keyed by id, with group parenting
+ * 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]));
+    const frames = new Map();
+    const frameOf = (o, depth = 0) => {
+        const cached = frames.get(o.id);
+        if (cached)
+            return cached;
+        const parent = o.group !== undefined ? byId.get(o.group) : undefined;
+        const base = parent && depth <= SCENE_MAX_GROUP_DEPTH ? frameOf(parent, depth + 1) : IDENTITY;
+        const f = mul(base, objectFrame(o));
+        frames.set(o.id, f);
+        return f;
+    };
+    const out = new Map();
+    for (const o of scene.objects)
+        out.set(o.id, mul(frameOf(o), translate(0, liftFor(o), 0)));
+    return out;
+}
+/** 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];
+    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]]) {
+                    const p = apply(m, [cx, cy, cz]);
+                    for (let k = 0; k < 3; k++) {
+                        if (p[k] < min[k])
+                            min[k] = p[k];
+                        if (p[k] > max[k])
+                            max[k] = p[k];
+                    }
+                }
+    }
+    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 = (() => {
+    const [x, y, z] = SCENE_DEFAULT_CAMERA.position;
+    const l = Math.hypot(x, y, z);
+    return [x / l, y / l, z / l];
+})();
+/**
+ * The camera used when a scene has none: look at the bounds' centre from the reference
+ * direction, at the distance that fits the bounding sphere in the vertical FOV, × 1.2.
+ * null bounds (empty scene) → the reference default.
+ */
+export function fitCamera(bounds, fovDeg = SCENE_CAMERA_FOV) {
+    if (!bounds) {
+        return {
+            position: [...SCENE_DEFAULT_CAMERA.position],
+            target: [...SCENE_DEFAULT_CAMERA.target],
+        };
+    }
+    const c = [
+        (bounds.min[0] + bounds.max[0]) / 2,
+        (bounds.min[1] + bounds.max[1]) / 2,
+        (bounds.min[2] + bounds.max[2]) / 2,
+    ];
+    const radius = Math.max(0.25, Math.hypot(bounds.max[0] - bounds.min[0], bounds.max[1] - bounds.min[1], bounds.max[2] - bounds.min[2]) / 2);
+    const dist = (radius / Math.sin(((fovDeg / 2) * Math.PI) / 180)) * 1.2;
+    const d = SCENE_CAMERA_DIRECTION;
+    return { position: [c[0] + d[0] * dist, c[1] + d[1] * dist, c[2] + d[2] * dist], target: c };
+}
+/** The camera to view a scene with: its own, or the fit. */
+export function sceneCamera(scene) {
+    return scene.camera ?? fitCamera(sceneBounds(scene));
+}
+/** 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 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];
+    const d = b.max[2] - b.min[2];
+    const h = b.max[1] - b.min[1];
+    return `${count}, bounds ${fmtNum(w)} × ${fmtNum(d)} × ${fmtNum(h)} m`;
+}
+/** The ids of an object's descendants (children, grandchildren, …), in scene order. */
+export function descendantsOf(scene, id) {
+    const out = [];
+    const frontier = new Set([id]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const o of scene.objects) {
+            if (o.group !== undefined && frontier.has(o.group) && !frontier.has(o.id)) {
+                frontier.add(o.id);
+                out.push(o.id);
+                grew = true;
+            }
+        }
+    }
+    return scene.objects.map((o) => o.id).filter((oid) => out.includes(oid));
+}
+/** Turn a display name (or type) into an id candidate: lowercase slug, ≤ 48 chars. */
+export function slugifySceneId(text) {
+    const s = text
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^[-_]+|[-_]+$/g, '')
+        .slice(0, 40)
+        .replace(/[-_]+$/g, '');
+    return s || 'object';
+}