@pascal-app/core 1.0.3 → 1.0.5

package/dist/agent-operations/room-floor-script.js

@@ -0,0 +1,54 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { floorScriptInputs, floorScriptRecord } from '../lib/floor-script.js';
+import { scriptedSize } from '../lib/geometry-script-node.js';
+import { ZoneFloorScript } from '../schema/index.js';
+const round = (value) => Math.round(value * 1000) / 1000;
+/**
+ * `setRoomFloorScript`: a room's floor finish built by a three.js module, or the module taken off.
+ * The host reads the room's floor (`floorScriptInputs`), compiles the module for it (geometry-script
+ * `inputs`: the module reads `params.polygon`, `params.holes`, `params.elevation`, in level
+ * coordinates) and stores the artifacts; this writes the result on the zone, with the key of the
+ * floor it was built for. When the structure re-derives the room's floor the script is stale and
+ * `refreshFinishScripts` runs it again. The script owns the floor's colours: paint on that floor is
+ * refused while it is there.
+ */
+export const setRoomFloorScript = (nodes, input) => {
+    const zone = nodes[input.zoneId];
+    if (zone?.type !== 'zone')
+        refuse('target_not_found', `${input.zoneId} is not a room in the scene: nothing was changed.`, {
+            target: input.zoneId,
+        });
+    const name = zone.name?.trim() || zone.id;
+    if ('remove' in input) {
+        if (!zone.floor?.script)
+            return { result: { ok: true, zoneId: zone.id, removed: false } };
+        const { script: _, ...floor } = zone.floor;
+        return {
+            result: { ok: true, zoneId: zone.id, removed: true },
+            changes: {
+                update: [{ id: zone.id, data: { floor: Object.keys(floor).length ? floor : undefined } }],
+            },
+        };
+    }
+    const { compiled } = input;
+    if (compiled.language !== 'three')
+        refuse('three_only', `A room's floor script is a three.js module: it is given the room's floor, which a Blender build is not. Nothing was changed on ${name}.`, { target: zone.id });
+    if (!floorScriptInputs(nodes, zone.id))
+        refuse('no_floor', `${name} has no floor to build on (its walls do not close it, or its floor is off): nothing was changed.`, { target: zone.id });
+    const { min, max } = compiled.manifest.bounds;
+    if (![...min, ...max].every(Number.isFinite))
+        refuse('unmeasurable_object', `${name}'s floor script built geometry that cannot be measured: a mesh in it has a position, rotation or scale that is not a number. Nothing was changed.`, { target: zone.id });
+    const script = ZoneFloorScript.parse(floorScriptRecord(compiled, input.inputs, zone.floor?.script));
+    const floor = { ...zone.floor, script };
+    return {
+        result: {
+            ok: true,
+            zoneId: zone.id,
+            size: scriptedSize(compiled.manifest).map(round),
+            slots: compiled.manifest.slots.map((slot) => slot.id),
+            triangles: compiled.manifest.triangles,
+            note: `The script owns ${name}'s floor colours: painting that floor is refused until the script is removed. It runs again whenever the room's floor changes.`,
+        },
+        changes: { update: [{ id: zone.id, data: { floor } }] },
+    };
+};

package/dist/agent-operations/room-structure.d.ts

@@ -0,0 +1,87 @@
+import type { AgentOperation } from './types.js';
+type RoomTransformInput = {
+    zoneId: string;
+    translate?: number[];
+    rotate?: {
+        angle: number;
+        pivot?: number[];
+    };
+    force?: boolean;
+};
+type SlabTarget = {
+    slabId?: string;
+    slabIds?: string[];
+};
+/** The room and floor-construction tools' operations, by tool name. */
+export declare const ROOM_OPERATIONS: {
+    readonly cut_floor_opening: AgentOperation<{
+        levelId?: string;
+        zoneId?: string;
+        levelIds?: string[];
+        polygon?: number[][];
+        rect?: {
+            x: number;
+            z: number;
+            width: number;
+            depth: number;
+        };
+        drawnOn?: 'floor' | 'ceiling';
+        cutsPrimary?: boolean;
+        cutsAdjacent?: boolean;
+    }>;
+    readonly remove_floor_opening: AgentOperation<{
+        id: string;
+    }>;
+    readonly set_floor_foundation: AgentOperation<SlabTarget & {
+        patch: unknown;
+    }>;
+    readonly set_room_floor_construction: AgentOperation<{
+        zoneId: string;
+        slabId?: string;
+        patch: unknown;
+    }>;
+    readonly rebase_floor_reference: AgentOperation<SlabTarget & {
+        referenceFloorElevation: number | null;
+    }>;
+    readonly create_mezzanine: AgentOperation<{
+        hostZoneId: string;
+        polygon: number[][];
+        elevation?: number;
+        thickness?: number;
+    }>;
+    readonly move_zone: AgentOperation<RoomTransformInput>;
+    readonly duplicate_zone: AgentOperation<RoomTransformInput & {
+        translate: number[];
+    }>;
+    readonly rotate_zone: AgentOperation<{
+        zoneId: string;
+        quarterTurns: number;
+        gridStep?: number;
+        force?: boolean;
+    }>;
+    readonly lock_outside_faces: AgentOperation<{
+        levelId?: string;
+        zoneIds?: string[];
+    }>;
+    readonly set_zone_intent: AgentOperation<{
+        zoneId: string;
+        patch: unknown;
+    }>;
+    readonly divide_zone: AgentOperation<{
+        zoneId: string;
+        cut?: number[][];
+        path?: number[][];
+        closed?: boolean;
+        startBoundaryId?: string;
+        endBoundaryId?: string;
+    }>;
+    readonly merge_zones: AgentOperation<{
+        zoneIds: string[];
+    }>;
+    readonly delete_zone: AgentOperation<{
+        zoneId: string;
+        contents: 'delete' | 'keep';
+    }>;
+};
+export {};
+//# sourceMappingURL=room-structure.d.ts.map

package/dist/agent-operations/room-structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-structure.d.ts","sourceRoot":"","sources":["../../src/agent-operations/room-structure.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,cAAc,EAAmD,MAAM,SAAS,CAAA;AA6G9F,KAAK,kBAAkB,GAAG;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAUD,KAAK,UAAU,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AA+JzD,uEAAuE;AACvE,eAAO,MAAM,eAAe;aAC1B,iBAAiB;kBA9JP,MAAM;iBACP,MAAM;mBACJ,MAAM,EAAE;kBACT,MAAM,EAAE,EAAE;eACb;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE;kBACnD,OAAO,GAAG,SAAS;sBACf,OAAO;uBACN,OAAO;;aAwJtB,oBAAoB;YA3IkC,MAAM;;aA4I5D,oBAAoB;eAtIkD,OAAO;;aAuI7E,2BAA2B;gBA7HnB,MAAM;iBACL,MAAM;eACR,OAAO;;aA4Hd,sBAAsB;iCAlHkB,MAAM,GAAG,IAAI;;aAmHrD,gBAAgB;oBA3GJ,MAAM;iBACT,MAAM,EAAE,EAAE;oBACP,MAAM;oBACN,MAAM;;aAyGlB,SAAS;aACT,cAAc;mBA1F+D,MAAM,EAAE;;aA2FrF,WAAW;gBAhFH,MAAM;sBACA,MAAM;mBACT,MAAM;gBACT,OAAO;;aA8Ef,kBAAkB;kBAhEwC,MAAM;kBAAY,MAAM,EAAE;;aAiEpF,eAAe;gBArDsC,MAAM;eAAS,OAAO;;aAsD3E,WAAW;gBA/CH,MAAM;cACR,MAAM,EAAE,EAAE;eACT,MAAM,EAAE,EAAE;iBACR,OAAO;0BACE,MAAM;wBACR,MAAM;;aA2CtB,WAAW;iBA7BwC,MAAM,EAAE;;aA8B3D,WAAW;gBAxBuC,MAAM;kBAAY,QAAQ,GAAG,MAAM;;CAyB7E,CAAA"}

package/dist/agent-operations/room-structure.js

@@ -0,0 +1,144 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { createMezzanine, cutFloorOpening, deleteZone, divideZone, duplicateZone, lockOutsideFaces, mergeZones, rebaseFloorReference, removeFloorOpening, resolveZoneTransformHosts, rotateZone, setFloorFoundation, setRoomFloorConstruction, setZoneIntent, transformZone, } from '../commands/structure/index.js';
+import { containsPoint } from '../lib/polygon-boolean.js';
+import { generateId } from '../schema/index.js';
+import { mergeSceneChanges } from './apply-changes.js';
+/** A plan's ordered changes as one set, landing where applying them one by one does. */
+function sceneChanges(changes) {
+    return mergeSceneChanges(changes.map((change) => change.op === 'create'
+        ? { create: [{ node: change.node, parentId: change.node.parentId ?? undefined }] }
+        : change.op === 'update'
+            ? { update: [{ id: change.id, data: change.data }] }
+            : { delete: [change.id] }));
+}
+/** The commands throw a plain Error for an edit they cannot make ("Room not found: …"). */
+function plan(command) {
+    try {
+        return command();
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'Error')
+            refuse('structure_refused', error.message);
+        throw error;
+    }
+}
+/**
+ * A room or floor command's plan as a shared tool's outcome, as the editor applies it: conflicts
+ * are answers and change nothing unless forced; otherwise the plan's changes, then — once the host
+ * has re-derived rooms and ceilings — the copied fixtures onto their new ceilings, and the result's
+ * rooms read from the derived scene (a room the reconciler re-minted is found by its seed).
+ */
+function roomOutcome(nodes, plan, force = false) {
+    const result = (zoneId = plan.zoneId, zoneIds) => ({
+        changes: plan.changes.length,
+        ...(zoneId ? { zoneId } : {}),
+        ...(plan.openingId ? { openingId: plan.openingId } : {}),
+        ...(plan.openingIds ? { openingIds: plan.openingIds } : {}),
+        ...(plan.hints ? { hints: plan.hints } : {}),
+        ...(plan.idMap
+            ? {
+                idMap: Object.fromEntries(Object.entries(plan.idMap).map(([id, targets]) => [
+                    id,
+                    targets.map((target) => (target === plan.zoneId ? zoneId : target)),
+                ])),
+            }
+            : {}),
+        ...(zoneIds ? { zoneIds } : {}),
+        ...(plan.payload ? { payload: plan.payload } : {}),
+        ...(plan.separatorId ? { separatorId: plan.separatorId } : {}),
+        ...(plan.separatorIds ? { separatorIds: plan.separatorIds } : {}),
+        ...(plan.conflicts ? { conflicts: plan.conflicts } : {}),
+    });
+    if (!plan.changes.length || (plan.conflicts?.length && !force))
+        return { result: result() };
+    let plannedZone = plan.zoneId ? nodes[plan.zoneId] : undefined;
+    for (const change of plan.changes) {
+        if (change.op === 'create' && change.node.id === plan.zoneId)
+            plannedZone = change.node;
+        else if (change.op === 'update' && change.id === plan.zoneId && plannedZone?.type === 'zone')
+            plannedZone = { ...plannedZone, ...change.data };
+    }
+    return {
+        result: result(),
+        changes: sceneChanges(plan.changes),
+        afterReconcile: (derived) => {
+            let zoneId = plan.zoneId;
+            if (zoneId && !derived[zoneId] && plannedZone?.type === 'zone' && plannedZone.seed) {
+                const { seed, parentId } = plannedZone;
+                zoneId =
+                    Object.values(derived).find((node) => node.type === 'zone' &&
+                        node.parentId === parentId &&
+                        containsPoint([{ outer: node.polygon, holes: node.holes }], seed))?.id ?? zoneId;
+            }
+            const zoneIds = plan.separatorIds?.length && !plan.conflicts?.length
+                ? Object.values(derived)
+                    .filter((node) => node.type === 'zone' &&
+                    plan.separatorIds.some((id) => node.boundarySeparatorIds.includes(id)))
+                    .map((node) => node.id)
+                    .sort()
+                : undefined;
+            const hosts = resolveZoneTransformHosts(derived, plan);
+            return {
+                result: result(zoneId, zoneIds),
+                ...(hosts.length ? { changes: sceneChanges(hosts) } : {}),
+            };
+        },
+    };
+}
+const points = (list) => list;
+const transform = ({ translate, rotate, ...input }) => ({
+    ...input,
+    ...(translate ? { translate: translate } : {}),
+    ...(rotate
+        ? { rotate: { angle: rotate.angle, ...(rotate.pivot ? { pivot: rotate.pivot } : {}) } }
+        : {}),
+    mintId: generateId,
+});
+const cutFloorOpeningOperation = (nodes, { polygon, ...input }) => roomOutcome(nodes, plan(() => cutFloorOpening(nodes, {
+    ...input,
+    ...(polygon ? { polygon: points(polygon) } : {}),
+    mintId: generateId,
+})));
+const removeFloorOpeningOperation = (nodes, { id }) => roomOutcome(nodes, plan(() => removeFloorOpening(nodes, id)));
+const setFloorFoundationOperation = (nodes, input) => roomOutcome(nodes, plan(() => setFloorFoundation(nodes, { ...input, patch: input.patch })));
+const setRoomFloorConstructionOperation = (nodes, input) => roomOutcome(nodes, plan(() => setRoomFloorConstruction(nodes, { ...input, patch: input.patch })));
+const rebaseFloorReferenceOperation = (nodes, input) => roomOutcome(nodes, plan(() => rebaseFloorReference(nodes, input)));
+const createMezzanineOperation = (nodes, input) => roomOutcome(nodes, plan(() => createMezzanine(nodes, { ...input, polygon: points(input.polygon), mintId: generateId })));
+const moveZoneOperation = (nodes, input) => roomOutcome(nodes, plan(() => transformZone(nodes, transform(input))), input.force);
+const duplicateZoneOperation = (nodes, input) => roomOutcome(nodes, plan(() => duplicateZone(nodes, { ...transform(input), translate: input.translate })), input.force);
+const rotateZoneOperation = (nodes, input) => roomOutcome(nodes, plan(() => rotateZone(nodes, {
+    ...input,
+    quarterTurns: input.quarterTurns,
+    mintId: generateId,
+})), input.force);
+const lockOutsideFacesOperation = (nodes, { levelId, zoneIds }) => {
+    if (Boolean(levelId) === Boolean(zoneIds))
+        refuse('target_required', 'Supply either levelId or zoneIds.');
+    return roomOutcome(nodes, plan(() => lockOutsideFaces(nodes, levelId ? { levelId } : { zoneIds: zoneIds })));
+};
+const setZoneIntentOperation = (nodes, input) => roomOutcome(nodes, plan(() => setZoneIntent(nodes, { ...input, patch: input.patch })));
+const divideZoneOperation = (nodes, { cut, path, ...input }) => roomOutcome(nodes, plan(() => divideZone(nodes, {
+    ...input,
+    ...(cut ? { cut: points(cut) } : {}),
+    ...(path ? { path: points(path) } : {}),
+    mintId: generateId,
+})));
+const mergeZonesOperation = (nodes, { zoneIds }) => roomOutcome(nodes, plan(() => mergeZones(nodes, { zoneIds: zoneIds })));
+const deleteZoneOperation = (nodes, input) => roomOutcome(nodes, plan(() => deleteZone(nodes, input)));
+/** The room and floor-construction tools' operations, by tool name. */
+export const ROOM_OPERATIONS = {
+    cut_floor_opening: cutFloorOpeningOperation,
+    remove_floor_opening: removeFloorOpeningOperation,
+    set_floor_foundation: setFloorFoundationOperation,
+    set_room_floor_construction: setRoomFloorConstructionOperation,
+    rebase_floor_reference: rebaseFloorReferenceOperation,
+    create_mezzanine: createMezzanineOperation,
+    move_zone: moveZoneOperation,
+    duplicate_zone: duplicateZoneOperation,
+    rotate_zone: rotateZoneOperation,
+    lock_outside_faces: lockOutsideFacesOperation,
+    set_zone_intent: setZoneIntentOperation,
+    divide_zone: divideZoneOperation,
+    merge_zones: mergeZonesOperation,
+    delete_zone: deleteZoneOperation,
+};

package/dist/agent-operations/scene-checkpoint.d.ts

@@ -0,0 +1,94 @@
+import { type DesignBrief } from '../agent-tools/design-brief.js';
+import { type AnyNode } from '../schema/index.js';
+import { type SceneMeasure } from './scene-measure.js';
+import type { SceneChanges, SceneNodes } from './types.js';
+/**
+ * What an agent session keeps about its own work: the moments it named, and what it made. The core
+ * computes and reads these and stores none: each host keeps its record where its sessions live, so
+ * a checkpoint is never scene data (it would dirty the scene, enter undo and change its hash).
+ */
+/** One node as a checkpoint remembers it: enough to say what it was when it is gone. */
+export type CheckpointNode = {
+    type: string;
+    levelId: string | null;
+    hash: string;
+    name?: string;
+};
+/** A node the agent created, kept when it is later deleted: the proof it was there. */
+export type MadeEntry = {
+    id: string;
+    type: string;
+    levelId: string | null;
+    name?: string;
+};
+export type SessionCheckpoint = {
+    name: string;
+    /** The registered families' places, for `changesSince` (windows, lit rooms…). */
+    measure: SceneMeasure;
+    nodes: Record<string, CheckpointNode>;
+    /** Issue ids an older version recorded; records taken now write none. */
+    issues: string[];
+    /** How many entries of the session's `made` list there were: what follows was made after it. */
+    madeAt: number;
+};
+export type SessionRecord = {
+    checkpoints: Record<string, SessionCheckpoint>;
+    made: MadeEntry[];
+    /** The design brief in force: the last one written, which furnishing follows (design_brief). */
+    designBrief?: DesignBrief;
+    /** The catalog ids view_assets showed: a brief keeps a catalog piece as it is only after one. */
+    viewed?: string[];
+};
+/**
+ * What an operation or a write asks its host to keep; a `designBrief` of null takes the brief away,
+ * `viewed` adds the catalog ids view_assets showed and null forgets them.
+ */
+export type SessionKeep = {
+    checkpoint?: SessionCheckpoint;
+    made?: readonly MadeEntry[];
+    designBrief?: DesignBrief | null;
+    viewed?: readonly string[] | null;
+};
+export declare const EMPTY_SESSION: SessionRecord;
+/** A session names at most this many moments, `start` included. */
+export declare const MAX_CHECKPOINTS = 8;
+/** A checkpoint of a larger scene is refused: it is about 60 bytes a node, kept with the session. */
+export declare const MAX_CHECKPOINT_NODES = 5000;
+/** The made list stops growing here; the session record stays bounded. */
+export declare const MAX_MADE = 20000;
+/** The viewed list keeps the most recent ids up to here. */
+export declare const MAX_VIEWED = 500;
+/**
+ * The record after a keep: a checkpoint of the same name is replaced, made entries accumulate. A node
+ * is made once, however many writers report it, and the list only ever grows at its end (a
+ * checkpoint's `madeAt` indexes into it). What the scene had when the session began was never made
+ * by the agent: an undo that puts it back does not make it.
+ */
+export declare function keepInSession(session: SessionRecord, keep: SessionKeep): SessionRecord;
+/**
+ * A node's fingerprint, eight hex digits. Its children are left out (a wall that gained a door did
+ * not change; the door is new) and so are the notes older versions kept in `metadata.coherence`: a
+ * session record taken before them must not read them as an edit of the building.
+ */
+export declare function hashNode(node: AnyNode): string;
+/** The scene as a checkpoint remembers it: every node's fingerprint and the registered families' places. */
+export declare function takeCheckpoint(nodes: SceneNodes, name: string, madeAt: number): SessionCheckpoint;
+/** The nodes a write created, as the session remembers them. */
+export declare function madeEntries(after: SceneNodes, written: readonly SceneChanges[]): MadeEntry[];
+/**
+ * The nodes that are in `after` and were not in `before`: what a writer that diffs made, which is
+ * every tool that writes, whatever it calls to do so.
+ */
+export declare function createdBetween(before: SceneNodes, after: SceneNodes): MadeEntry[];
+/**
+ * What a host keeps at a session's first call, before anything is written: the scene as it stood,
+ * under the name `start`. The beginning of the agent's work is always a checkpoint. Nothing when
+ * the session has one, or the scene is too large to remember.
+ */
+export declare function startOfSession(session: SessionRecord, nodes: SceneNodes): SessionKeep | undefined;
+/**
+ * A session record read back from where a host stored it. Anything that is not one is no record:
+ * the session starts empty rather than the host failing on what is only a convenience.
+ */
+export declare function parseSessionRecord(input: unknown): SessionRecord;
+//# sourceMappingURL=scene-checkpoint.d.ts.map

package/dist/agent-operations/scene-checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-checkpoint.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/agent-operations/scene-checkpoint.js

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+import { DesignBriefRecord } from '../agent-tools/design-brief.js';
+import { isDefaultGutterNode } from '../schema/index.js';
+import { isDerivedNode } from '../store/derived-node-guard.js';
+import { measureScene } from './scene-measure.js';
+import { levelIdOf } from './scene-queries.js';
+export const EMPTY_SESSION = { checkpoints: {}, made: [] };
+/** A session names at most this many moments, `start` included. */
+export const MAX_CHECKPOINTS = 8;
+/** A checkpoint of a larger scene is refused: it is about 60 bytes a node, kept with the session. */
+export const MAX_CHECKPOINT_NODES = 5000;
+/** The made list stops growing here; the session record stays bounded. */
+export const MAX_MADE = 20_000;
+/** The viewed list keeps the most recent ids up to here. */
+export const MAX_VIEWED = 500;
+/**
+ * The record after a keep: a checkpoint of the same name is replaced, made entries accumulate. A node
+ * is made once, however many writers report it, and the list only ever grows at its end (a
+ * checkpoint's `madeAt` indexes into it). What the scene had when the session began was never made
+ * by the agent: an undo that puts it back does not make it.
+ */
+export function keepInSession(session, keep) {
+    const known = new Set(session.made.map((entry) => entry.id));
+    const began = session.checkpoints.start?.nodes;
+    const fresh = (keep.made ?? []).filter((entry) => {
+        if (known.has(entry.id) || began?.[entry.id])
+            return false;
+        known.add(entry.id);
+        return true;
+    });
+    const designBrief = 'designBrief' in keep ? keep.designBrief : session.designBrief;
+    const incomingViewed = new Set(keep.viewed ?? []);
+    const viewed = keep.viewed === null
+        ? []
+        : [
+            ...(session.viewed ?? []).filter((id) => !incomingViewed.has(id)),
+            ...incomingViewed,
+        ].slice(-MAX_VIEWED);
+    return {
+        checkpoints: keep.checkpoint
+            ? { ...session.checkpoints, [keep.checkpoint.name]: keep.checkpoint }
+            : session.checkpoints,
+        made: fresh.length ? [...session.made, ...fresh].slice(0, MAX_MADE) : session.made,
+        ...(designBrief ? { designBrief } : {}),
+        ...(viewed.length ? { viewed } : {}),
+    };
+}
+const FNV_PRIME = 0x01000193;
+/** Plain JSON in a fixed key order, numbers to a tenth of a millimetre, undefined dropped. */
+function stable(value) {
+    if (typeof value === 'number')
+        return String(Math.round(value * 1e4) / 1e4);
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record)
+        .sort()
+        .filter((key) => record[key] !== undefined)
+        .map((key) => `${JSON.stringify(key)}:${stable(record[key])}`)
+        .join(',')}}`;
+}
+/**
+ * A node's fingerprint, eight hex digits. Its children are left out (a wall that gained a door did
+ * not change; the door is new) and so are the notes older versions kept in `metadata.coherence`: a
+ * session record taken before them must not read them as an edit of the building.
+ */
+export function hashNode(node) {
+    const { children: _children, metadata, ...rest } = node;
+    const { coherence: _notes, ...kept } = metadata ?? {};
+    let hash = 0x811c9dc5;
+    const text = stable({ ...rest, metadata: kept });
+    for (let index = 0; index < text.length; index++) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, FNV_PRIME) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+const nameOf = (node) => typeof node.name === 'string' && node.name ? { name: node.name } : {};
+/** The scene as a checkpoint remembers it: every node's fingerprint and the registered families' places. */
+export function takeCheckpoint(nodes, name, madeAt) {
+    const remembered = {};
+    for (const node of Object.values(nodes))
+        remembered[node.id] = {
+            type: node.type,
+            levelId: levelIdOf(nodes, node.id),
+            hash: hashNode(node),
+            ...nameOf(node),
+        };
+    return {
+        name,
+        measure: measureScene(nodes),
+        nodes: remembered,
+        issues: [],
+        madeAt,
+    };
+}
+/**
+ * Construction the editor derives from what the agent drew: floor plates, auto ceilings, default
+ * gutters. Their ids change as the reconciler rebuilds them, so none is a thing the agent made.
+ */
+const isDerivedConstruction = (node) => isDerivedNode(node) || isDefaultGutterNode(node);
+const madeEntry = (nodes, node) => ({
+    id: node.id,
+    type: node.type,
+    levelId: levelIdOf(nodes, node.id),
+    ...nameOf(node),
+});
+/** The nodes a write created, as the session remembers them. */
+export function madeEntries(after, written) {
+    return written
+        .flatMap((changes) => (changes.create ?? []).map(({ node }) => after[node.id] ?? node))
+        .filter((node) => !isDerivedConstruction(node))
+        .map((node) => madeEntry(after, node));
+}
+/**
+ * The nodes that are in `after` and were not in `before`: what a writer that diffs made, which is
+ * every tool that writes, whatever it calls to do so.
+ */
+export function createdBetween(before, after) {
+    return Object.values(after)
+        .filter((node) => !(node.id in before) && !isDerivedConstruction(node))
+        .map((node) => madeEntry(after, node));
+}
+/**
+ * What a host keeps at a session's first call, before anything is written: the scene as it stood,
+ * under the name `start`. The beginning of the agent's work is always a checkpoint. Nothing when
+ * the session has one, or the scene is too large to remember.
+ */
+export function startOfSession(session, nodes) {
+    if (session.checkpoints.start || Object.keys(nodes).length > MAX_CHECKPOINT_NODES)
+        return undefined;
+    return { checkpoint: takeCheckpoint(nodes, 'start', session.made.length) };
+}
+const Place = z.object({ x: z.number(), z: z.number(), name: z.string().optional() });
+const Measure = z.object({
+    levels: z.record(z.string(), z.object({ name: z.string(), families: z.record(z.string(), z.array(Place)) })),
+});
+const Remembered = z.object({
+    type: z.string(),
+    levelId: z.string().nullable(),
+    hash: z.string().regex(/^[0-9a-f]{8}$/),
+    name: z.string().optional(),
+});
+const Checkpoint = z.object({
+    name: z.string().min(1),
+    measure: Measure,
+    nodes: z
+        .record(z.string(), Remembered)
+        .refine((nodes) => Object.keys(nodes).length <= MAX_CHECKPOINT_NODES),
+    issues: z.array(z.string()),
+    madeAt: z.number().int().min(0),
+});
+const Made = z.object({
+    id: z.string(),
+    type: z.string(),
+    levelId: z.string().nullable(),
+    name: z.string().optional(),
+});
+const Record_ = z.object({
+    checkpoints: z
+        .record(z.string(), Checkpoint)
+        .refine((checkpoints) => Object.keys(checkpoints).length <= MAX_CHECKPOINTS),
+    made: z.array(Made).max(MAX_MADE),
+    designBrief: DesignBriefRecord.optional(),
+    viewed: z.array(z.string()).max(MAX_VIEWED).optional(),
+});
+/**
+ * A session record read back from where a host stored it. Anything that is not one is no record:
+ * the session starts empty rather than the host failing on what is only a convenience.
+ */
+export function parseSessionRecord(input) {
+    const parsed = Record_.safeParse(input);
+    return parsed.success ? parsed.data : EMPTY_SESSION;
+}

package/dist/agent-operations/scene-materials.d.ts

@@ -0,0 +1,15 @@
+import { MaterialSchema } from '../schema/material.js';
+import { type SceneMaterial, type SceneMaterialId } from '../schema/scene-material.js';
+/**
+ * A native material as the editor's Paint keeps a one-off: the scene's equal material when it has
+ * one (compared as the schema reads both), else a new scene material. Refused where the host
+ * cannot store scene materials, so no node points at a material nothing keeps.
+ */
+export declare function resolveInlinePaintMaterial(materials: Readonly<Record<SceneMaterialId, SceneMaterial>> | undefined, input: MaterialSchema, name?: string): {
+    ref: string;
+    sceneMaterial: SceneMaterial;
+    created: boolean;
+};
+/** The scene materials a node points at, in its slots and its role fields alike. */
+export declare function referencedSceneMaterialIds(value: unknown): Set<string>;
+//# sourceMappingURL=scene-materials.d.ts.map

package/dist/agent-operations/scene-materials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-materials.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-materials.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAA;AAqBjC;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,GAAG,SAAS,EACvE,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAqBjE;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAWtE"}

package/dist/agent-operations/scene-materials.js

@@ -0,0 +1,62 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { parseMaterialRef, toSceneMaterialRef } from '../material-library.js';
+import { MaterialSchema } from '../schema/material.js';
+import { generateSceneMaterialId, } from '../schema/scene-material.js';
+/** Whether two parsed values are the same, whatever their keys' order. */
+function equal(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    if (Array.isArray(a) || Array.isArray(b))
+        return (Array.isArray(a) &&
+            Array.isArray(b) &&
+            a.length === b.length &&
+            a.every((value, index) => equal(value, b[index])));
+    const left = a;
+    const right = b;
+    return (Object.keys(left).length === Object.keys(right).length &&
+        Object.keys(left).every((key) => Object.hasOwn(right, key) && equal(left[key], right[key])));
+}
+/**
+ * A native material as the editor's Paint keeps a one-off: the scene's equal material when it has
+ * one (compared as the schema reads both), else a new scene material. Refused where the host
+ * cannot store scene materials, so no node points at a material nothing keeps.
+ */
+export function resolveInlinePaintMaterial(materials, input, name) {
+    if (!materials)
+        refuse('materials_unavailable', 'This host cannot keep native materials: give a library material or a colour. Nothing was painted.');
+    const parsed = MaterialSchema.safeParse(input);
+    if (!parsed.success)
+        refuse('invalid_material', `Not a native material: ${parsed.error.message}`);
+    for (const existing of Object.values(materials)) {
+        const normalized = MaterialSchema.safeParse(existing.material);
+        if (normalized.success && equal(normalized.data, parsed.data))
+            return { ref: toSceneMaterialRef(existing.id), sceneMaterial: existing, created: false };
+    }
+    let id = generateSceneMaterialId();
+    while (materials[id])
+        id = generateSceneMaterialId();
+    const sceneMaterial = {
+        id,
+        name: name ?? `Material ${Object.keys(materials).length + 1}`,
+        material: parsed.data,
+    };
+    return { ref: toSceneMaterialRef(id), sceneMaterial, created: true };
+}
+/** The scene materials a node points at, in its slots and its role fields alike. */
+export function referencedSceneMaterialIds(value) {
+    const ids = new Set();
+    const visit = (entry) => {
+        if (typeof entry === 'string') {
+            const parsed = parseMaterialRef(entry);
+            if (parsed?.kind === 'scene')
+                ids.add(parsed.id);
+        }
+        else if (entry && typeof entry === 'object')
+            for (const child of Object.values(entry))
+                visit(child);
+    };
+    visit(value);
+    return ids;
+}