@compilr-dev/sdk 0.29.8 → 0.30.0

package/dist/canvas/index.d.ts

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

package/dist/canvas/index.js

@@ -4,6 +4,13 @@
  */
 export * from './types.js';
 export * from './validate.js';
+/*
+  3D scenes — the `scene` canvas type. Pure (no imports beyond each other) so Desktop's
+  renderer can validate, preview an edit (applySceneOps) and compute lift/bounds/fit with the
+  SAME code the writer uses. The node-side writer lives in platform/scene-writer.ts.
+*/
+export * from './scene.js';
+export * from './scene-ops.js';
 /*
   ⚠️ Renderer-safe on purpose. Both modules are pure arithmetic with no imports beyond
   each other, so Desktop's renderer can use them for the surface ramp without pulling the

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

@@ -0,0 +1,122 @@
+/**
+ * Scene ops — the PURE half of the scene writer (3d-canvas-spec §4.2).
+ *
+ * `applySceneOps(scene, ops)` is the whole edit pipeline minus storage: apply every op, validate
+ * the FINAL scene, normalise it. All or nothing — a batch whose result is invalid returns an
+ * error and no scene. The node-side writer (`platform/scene-writer.ts`) wraps it with a
+ * per-canvas lock, revisions and the user-edit journal; Desktop's renderer can use it directly
+ * for an optimistic preview of an inspector edit (the writer's reply stays authoritative).
+ *
+ * Renderer-safe: imports only `scene.ts`.
+ */
+import type { SceneCamera, SceneFile, SceneObject, SceneObjectType } from './scene.js';
+/** An object as a caller supplies it — untrusted until the final validation. */
+export type SceneObjectInput = Record<string, unknown>;
+export type SceneOp = 
+/** Add one object. `index` inserts at a position (undo of a remove re-adds at its index). */
+{
+    op: 'add';
+    object: SceneObjectInput;
+    index?: number;
+}
+/** Add up to SCENE_MAX_BATCH objects atomically (Q-1). */
+ | {
+    op: 'add';
+    objects: SceneObjectInput[];
+    index?: number;
+}
+/** Shallow merge; arrays replaced whole; `null` clears an optional field; id/type rejected. */
+ | {
+    op: 'update';
+    id: string;
+    patch: Record<string, unknown>;
+}
+/** Removes descendants too (reported). */
+ | {
+    op: 'remove';
+    id: string;
+}
+/** `{ fit: true }` removes the stored camera — the viewer then fits the objects. */
+ | {
+    op: 'camera';
+    camera: SceneCamera | {
+        fit: true;
+    };
+}
+/** Whole-scene replace (scene_create, JSON import). */
+ | {
+    op: 'replace';
+    scene: unknown;
+};
+export type SceneEditSource = {
+    kind: 'agent';
+    agentId?: string;
+} | {
+    kind: 'user';
+};
+export type SceneChangeKind = 'moved' | 'resized' | 'rotated' | 'recoloured' | 'renamed' | 'removed' | 'added' | 'edited' | 'camera' | 'replaced';
+/** One journalled change (the writer stamps `rev`). */
+export interface SceneChange {
+    rev: number;
+    id: string;
+    what: SceneChangeKind;
+    from?: unknown;
+    to?: unknown;
+}
+export interface SceneOpOptions {
+    /** Who is editing. Locked objects refuse USER edits and warn on AGENT edits (Q-12). */
+    source?: SceneEditSource;
+    /** For messages ("No object "sofa" in scene 12"). */
+    canvasId?: number;
+}
+export interface SceneOpResult {
+    scene: SceneFile;
+    summary: string;
+    /** Ids added / changed / removed by this op. */
+    ids: string[];
+    changes: Omit<SceneChange, 'rev'>[];
+    warnings: string[];
+    /** Objects a remove took out, with their former index — enough to undo it (Q-4). */
+    removed?: {
+        index: number;
+        object: SceneObject;
+    }[];
+}
+export type SceneOpsResult = {
+    ok: true;
+    scene: SceneFile;
+    summaries: string[];
+    ids: string[];
+    changes: Omit<SceneChange, 'rev'>[];
+    warnings: string[];
+    removed: {
+        index: number;
+        object: SceneObject;
+    }[];
+} | {
+    ok: false;
+    error: string;
+};
+/** A fresh id from the name (or type): slug, suffixed -2, -3… on collision. */
+export declare function generateSceneId(base: string, taken: Set<string>): string;
+/**
+ * Apply ONE op to a scene. Pure. Does not validate the resulting scene as a whole — use
+ * `applySceneOps` for the full pipeline (apply all → validate → normalise).
+ */
+export declare function applySceneOp(scene: SceneFile, op: SceneOp, opts?: SceneOpOptions): SceneOpResult | {
+    error: string;
+};
+/** Cap and bullet validation errors for a tool result. */
+export declare function formatValidationErrors(errors: string[], max?: number): string;
+/**
+ * The whole edit pipeline, pure: apply every op in order, then validate the FINAL scene and
+ * normalise it. All or nothing. `scene` may be null only when the first op is `replace`.
+ */
+export declare function applySceneOps(scene: SceneFile | null, ops: SceneOp[], opts?: SceneOpOptions): SceneOpsResult;
+/**
+ * "The user edited this scene since your last call: moved "sofa" to [1.2, 0, -0.4]; removed
+ * "lamp". Re-read with scene_get if you depend on other fields." — null when no changes.
+ */
+export declare function formatUserEditNotice(changes: SceneChange[], max?: number): string | null;
+/** Type guard used by hosts on untrusted IPC payloads. */
+export declare function isSceneObjectType(v: unknown): v is SceneObjectType;

package/dist/canvas/scene-ops.js

@@ -0,0 +1,375 @@
+/**
+ * Scene ops — the PURE half of the scene writer (3d-canvas-spec §4.2).
+ *
+ * `applySceneOps(scene, ops)` is the whole edit pipeline minus storage: apply every op, validate
+ * the FINAL scene, normalise it. All or nothing — a batch whose result is invalid returns an
+ * error and no scene. The node-side writer (`platform/scene-writer.ts`) wraps it with a
+ * per-canvas lock, revisions and the user-edit journal; Desktop's renderer can use it directly
+ * for an optimistic preview of an inspector edit (the writer's reply stays authoritative).
+ *
+ * Renderer-safe: imports only `scene.ts`.
+ */
+import { SCENE_ID_PATTERN, SCENE_MAX_BATCH, SCENE_OBJECT_TYPES, descendantsOf, fmtVec, normalizeScene, slugifySceneId, validateScene, } from './scene.js';
+// =============================================================================
+// Helpers
+// =============================================================================
+const SIZE_KEYS = new Set(['size', 'radius', 'height', 'tube', 'points']);
+function sceneRef(opts) {
+    return opts?.canvasId !== undefined ? `scene ${String(opts.canvasId)}` : 'this scene';
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function clone(v) {
+    return JSON.parse(JSON.stringify(v));
+}
+function unknownId(id, opts) {
+    return `No object "${id}" in ${sceneRef(opts)}. List ids with scene_get.`;
+}
+/** A fresh id from the name (or type): slug, suffixed -2, -3… on collision. */
+export function generateSceneId(base, taken) {
+    const stem = slugifySceneId(base);
+    if (!taken.has(stem))
+        return stem;
+    for (let n = 2;; n++) {
+        const candidate = `${stem}-${String(n)}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+function lockedMessage(id) {
+    return `"${id}" is locked — unlock it before moving, resizing or removing it.`;
+}
+function lockedWarning(id) {
+    return `⚠ "${id}" is locked by the user; you changed it anyway. Tell the user, or leave locked objects alone unless asked.`;
+}
+// =============================================================================
+// Single op
+// =============================================================================
+function addObjects(scene, inputs, index, opts) {
+    if (inputs.length === 0)
+        return { error: 'Nothing to add — pass at least one object.' };
+    if (inputs.length > SCENE_MAX_BATCH) {
+        return {
+            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 = [];
+    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));
+        if (obj.type === 'wall') {
+            return {
+                error: `${at}: use type "extrude" with points [[x,z],…] and height for walls.`,
+            };
+        }
+        if (typeof obj.type !== 'string' ||
+            !SCENE_OBJECT_TYPES.includes(obj.type)) {
+            return {
+                error: `${at}.type = ${obj.type === undefined ? 'missing' : JSON.stringify(obj.type)} — must be one of ${SCENE_OBJECT_TYPES.join(', ')}.`,
+            };
+        }
+        if (obj.id === undefined) {
+            const base = typeof obj.name === 'string' && obj.name.trim() ? obj.name : obj.type;
+            obj.id = generateSceneId(base, taken);
+        }
+        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];
+    const at = index === undefined ? objects.length : Math.max(0, Math.min(objects.length, Math.floor(index)));
+    objects.splice(at, 0, ...added);
+    const ids = added.map((o) => o.id);
+    const summary = added.length === 1
+        ? `Added ${added[0].type} "${added[0].id}" at ${showVal(added[0].position)}.`
+        : `Added ${String(added.length)} objects: ${ids.map((id) => `"${id}"`).join(', ')}.`;
+    return {
+        scene: { ...scene, objects },
+        summary,
+        ids,
+        changes: added.map((o) => ({ id: o.id, what: 'added', to: o.type })),
+        warnings: [],
+    };
+}
+function changeKindFor(key) {
+    if (key === 'position')
+        return 'moved';
+    if (key === 'rotation')
+        return 'rotated';
+    if (key === 'color')
+        return 'recoloured';
+    if (key === 'name')
+        return 'renamed';
+    if (SIZE_KEYS.has(key))
+        return 'resized';
+    return 'edited';
+}
+function showVal(v) {
+    if (v === undefined)
+        return '(unset)';
+    if (Array.isArray(v) && v.every((n) => typeof n === 'number'))
+        return fmtVec(v);
+    return JSON.stringify(v);
+}
+function updateObject(scene, id, patch, opts) {
+    const idx = scene.objects.findIndex((o) => o.id === id);
+    if (idx < 0)
+        return { error: unknownId(id, opts) };
+    if (!isRecord(patch) || Object.keys(patch).length === 0) {
+        return {
+            error: 'patch must be a non-empty object of fields to change, e.g. { "position": [1, 0, 2] }.',
+        };
+    }
+    if ('id' in patch || 'type' in patch) {
+        const which = 'id' in patch ? 'id' : 'type';
+        return {
+            error: `patch.${which} cannot change — remove the object (scene_remove_object) and add it again (scene_add_object).`,
+        };
+    }
+    const before = scene.objects[idx];
+    const warnings = [];
+    if (before.locked === true) {
+        const onlyLock = Object.keys(patch).every((k) => k === 'locked');
+        if (opts?.source?.kind === 'user') {
+            if (!onlyLock)
+                return { error: lockedMessage(id) };
+        }
+        else if (!onlyLock) {
+            warnings.push(lockedWarning(id));
+        }
+    }
+    const next = clone(before);
+    const changes = [];
+    const parts = [];
+    for (const [k, v] of Object.entries(patch)) {
+        const from = before[k];
+        if (v === null)
+            Reflect.deleteProperty(next, k);
+        else
+            next[k] = clone(v); // shallow merge: arrays and nested objects replaced whole
+        const to = next[k];
+        if (JSON.stringify(from) === JSON.stringify(to))
+            continue;
+        changes.push({ id, what: changeKindFor(k), from, to });
+        parts.push(`${k} ${showVal(from)} → ${showVal(to)}`);
+    }
+    const objects = [...scene.objects];
+    objects[idx] = next;
+    return {
+        scene: { ...scene, objects },
+        summary: parts.length
+            ? `Updated "${id}": ${parts.join('; ')}.`
+            : `"${id}" unchanged (same values).`,
+        ids: [id],
+        changes,
+        warnings,
+    };
+}
+function removeObject(scene, id, opts) {
+    const idx = scene.objects.findIndex((o) => o.id === id);
+    if (idx < 0)
+        return { error: unknownId(id, opts) };
+    const children = descendantsOf(scene, id);
+    const all = new Set([id, ...children]);
+    const lockedIds = scene.objects
+        .filter((o) => all.has(o.id) && o.locked === true)
+        .map((o) => o.id);
+    const warnings = [];
+    if (lockedIds.length > 0) {
+        if (opts?.source?.kind === 'user')
+            return { error: lockedMessage(lockedIds[0]) };
+        for (const l of lockedIds)
+            warnings.push(lockedWarning(l));
+    }
+    const removed = [];
+    scene.objects.forEach((o, i) => {
+        if (all.has(o.id))
+            removed.push({ index: i, object: clone(o) });
+    });
+    const objects = scene.objects.filter((o) => !all.has(o.id));
+    const childNote = children.length
+        ? ` and ${String(children.length)} ${children.length === 1 ? 'child' : 'children'} (${children.map((c) => `"${c}"`).join(', ')})`
+        : '';
+    return {
+        scene: { ...scene, objects },
+        summary: `Removed "${id}"${childNote}.`,
+        ids: [id, ...children],
+        changes: [id, ...children].map((rid) => ({ id: rid, what: 'removed' })),
+        warnings,
+        removed,
+    };
+}
+function setCamera(scene, camera) {
+    if (isRecord(camera) && camera.fit === true) {
+        const rest = { ...scene };
+        delete rest.camera;
+        return {
+            scene: rest,
+            summary: 'Camera cleared — the view now fits the objects.',
+            ids: [],
+            changes: [{ id: '', what: 'camera', from: scene.camera, to: 'fit' }],
+            warnings: [],
+        };
+    }
+    if (!isRecord(camera)) {
+        return { error: 'camera must be { position: [x, y, z], target: [x, y, z] } or { fit: true }.' };
+    }
+    const next = { position: camera.position, target: camera.target };
+    return {
+        scene: { ...scene, camera: next },
+        summary: `Camera set: position ${showVal(camera.position)}, target ${showVal(camera.target)}.`,
+        ids: [],
+        changes: [{ id: '', what: 'camera', from: scene.camera, to: next }],
+        warnings: [],
+    };
+}
+/**
+ * Apply ONE op to a scene. Pure. Does not validate the resulting scene as a whole — use
+ * `applySceneOps` for the full pipeline (apply all → validate → normalise).
+ */
+export function applySceneOp(scene, op, opts) {
+    switch (op.op) {
+        case 'add':
+            return 'objects' in op
+                ? Array.isArray(op.objects)
+                    ? addObjects(scene, op.objects, op.index, opts)
+                    : { error: 'objects must be an array of objects.' }
+                : addObjects(scene, [op.object], op.index, opts);
+        case 'update':
+            return updateObject(scene, op.id, op.patch, opts);
+        case 'remove':
+            return removeObject(scene, op.id, opts);
+        case 'camera':
+            return setCamera(scene, op.camera);
+        case 'replace': {
+            const v = validateScene(op.scene);
+            if (!v.ok)
+                return { error: formatValidationErrors(v.errors) };
+            return {
+                scene: v.scene,
+                summary: `Replaced the scene (${String(v.scene.objects.length)} objects).`,
+                ids: v.scene.objects.map((o) => o.id),
+                changes: [{ id: '', what: 'replaced' }],
+                warnings: [],
+            };
+        }
+        default: {
+            const unknownOp = op.op;
+            return { error: `Unknown scene op ${JSON.stringify(unknownOp)}.` };
+        }
+    }
+}
+/** Cap and bullet validation errors for a tool result. */
+export function formatValidationErrors(errors, max = 8) {
+    const shown = errors.slice(0, max).map((e) => `- ${e}`);
+    if (errors.length > max)
+        shown.push(`- …and ${String(errors.length - max)} more.`);
+    return `The scene is invalid; nothing was stored:\n${shown.join('\n')}`;
+}
+/**
+ * The whole edit pipeline, pure: apply every op in order, then validate the FINAL scene and
+ * normalise it. All or nothing. `scene` may be null only when the first op is `replace`.
+ */
+export function applySceneOps(scene, ops, opts) {
+    if (ops.length === 0)
+        return { ok: false, error: 'No edits given.' };
+    let cur = scene;
+    const summaries = [];
+    const ids = [];
+    const changes = [];
+    const warnings = [];
+    const removed = [];
+    for (const op of ops) {
+        if (!cur && op.op !== 'replace') {
+            return {
+                ok: false,
+                error: 'The stored scene could not be read; only a full replace can fix it.',
+            };
+        }
+        const base = cur ?? { version: 1, name: 'Scene', units: 'm', objects: [] };
+        const r = applySceneOp(base, op, opts);
+        if ('error' in r)
+            return { ok: false, error: r.error };
+        cur = r.scene;
+        summaries.push(r.summary);
+        for (const id of r.ids)
+            if (!ids.includes(id))
+                ids.push(id);
+        changes.push(...r.changes);
+        warnings.push(...r.warnings);
+        if (r.removed)
+            removed.push(...r.removed);
+    }
+    const v = validateScene(cur);
+    if (!v.ok)
+        return { ok: false, error: formatValidationErrors(v.errors) };
+    return {
+        ok: true,
+        scene: normalizeScene(v.scene),
+        summaries,
+        ids,
+        changes,
+        warnings,
+        removed,
+    };
+}
+// =============================================================================
+// The user-edit notice (§4.3)
+// =============================================================================
+function describeChange(c) {
+    const q = `"${c.id}"`;
+    switch (c.what) {
+        case 'moved':
+            return `moved ${q} to ${showVal(c.to)}`;
+        case 'rotated':
+            return `rotated ${q} to ${showVal(c.to)}`;
+        case 'recoloured':
+            return `recoloured ${q} to ${typeof c.to === 'string' ? c.to : showVal(c.to)}`;
+        case 'renamed':
+            return `renamed ${q} to ${showVal(c.to)}`;
+        case 'resized':
+            return `resized ${q}`;
+        case 'removed':
+            return `removed ${q}`;
+        case 'added':
+            return `added ${typeof c.to === 'string' ? `${c.to} ` : ''}${q}`;
+        case 'camera':
+            return 'changed the camera';
+        case 'replaced':
+            return 'replaced the whole scene';
+        case 'edited':
+            return `edited ${q}`;
+    }
+}
+/**
+ * "The user edited this scene since your last call: moved "sofa" to [1.2, 0, -0.4]; removed
+ * "lamp". Re-read with scene_get if you depend on other fields." — null when no changes.
+ */
+export function formatUserEditNotice(changes, max = 12) {
+    if (changes.length === 0)
+        return null;
+    const parts = changes.slice(0, max).map(describeChange);
+    if (changes.length > max)
+        parts.push(`and ${String(changes.length - max)} more`);
+    return (`The user edited this scene since your last call: ${parts.join('; ')}. ` +
+        'Re-read with scene_get if you depend on other fields.');
+}
+/** Type guard used by hosts on untrusted IPC payloads. */
+export function isSceneObjectType(v) {
+    return typeof v === 'string' && SCENE_OBJECT_TYPES.includes(v);
+}