@pascal-app/core 1.0.4 → 1.0.6

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

@@ -0,0 +1,143 @@
+import { area, intersection, union } from '../lib/polygon-boolean.js';
+import { polygonInteriorPoint } from '../lib/polygon-label.js';
+import { distanceToSegment } from '../lib/room-topology-index.js';
+import { detectSpacesForLevel } from '../lib/space-detection.js';
+import { nodesOnLevel } from './scene-queries.js';
+/** No name, or the bare word an older scene or a blank name leaves: "Room", "Zone". */
+const PLACEHOLDER_NAME = /^\s*(room|zone)?\s*$/i;
+/** A space is covered, a room enclosed, a zone in a space, and a zone walled like a room, past half. */
+const HALF = 0.5;
+/** How far past a wall's face its outline may run and still be walled, m. */
+const ALONG_WALL = 0.1;
+/** The step a zone's outline is sampled at to see how much of it walls run along, m. */
+const OUTLINE_STEP = 0.25;
+/** A wall that bounds a room stands at least this high, m; a garden wall is lower. */
+const ROOM_WALL_HEIGHT = 2;
+const round = (value) => Math.round(value * 100) / 100;
+function shapeOf(outer, holes = []) {
+    const polygon = { outer, holes };
+    const xs = outer.map(([x]) => x);
+    const zs = outer.map(([, z]) => z);
+    return {
+        polygon,
+        box: [Math.min(...xs), Math.min(...zs), Math.max(...xs), Math.max(...zs)],
+        area: area([polygon]),
+    };
+}
+const overlap = (a, b) => a.box[0] < b.box[2] && b.box[0] < a.box[2] && a.box[1] < b.box[3] && b.box[1] < a.box[3];
+/** How much of `part` the shapes cover, 0 to 1; only the shapes whose boxes meet it are joined. */
+function covered(part, cover) {
+    if (part.area <= 0)
+        return 0;
+    const near = cover.filter((shape) => overlap(part, shape));
+    if (near.length === 0)
+        return 0;
+    const joined = near.length === 1 ? near[0].polygon : union(near.map((shape) => shape.polygon));
+    return area(intersection(part.polygon, joined)) / part.area;
+}
+/** How much of a zone's outline runs along a wall, 0 to 1: a zone mostly walled is meant as a room. */
+function walled(zone, walls) {
+    const ring = zone.polygon;
+    let along = 0;
+    let samples = 0;
+    ring.forEach((start, i) => {
+        const end = ring[(i + 1) % ring.length];
+        const steps = Math.max(1, Math.ceil(Math.hypot(end[0] - start[0], end[1] - start[1]) / OUTLINE_STEP));
+        for (let k = 0; k < steps; k++) {
+            const t = (k + 0.5) / steps;
+            const point = [
+                start[0] + (end[0] - start[0]) * t,
+                start[1] + (end[1] - start[1]) * t,
+            ];
+            samples++;
+            if (walls.some((wall) => distanceToSegment(point, wall.start, wall.end) <=
+                (wall.thickness ?? 0.2) / 2 + ALONG_WALL))
+                along++;
+        }
+    });
+    return samples > 0 ? along / samples : 0;
+}
+const label = (zone) => PLACEHOLDER_NAME.test(zone.name) ? zone.id : `"${zone.name}" (${zone.id})`;
+/**
+ * A room is a zone with `spaceRole: 'room'`, or a generic one walls of a room's height bound along
+ * most of its outline, which may be a room drawn before its last wall (no reconcile could adopt
+ * it) or a courtyard, so what is found on it is info; a zone garden walls bound, or no walls (an
+ * analysis area), is no room. Every space the walls enclose wants one zone over it (any zone: a drawn one is
+ * adopted as the room on load): none, or several rooms lying in it (the reconciler's "Room N"
+ * beside a zone drawn over it, a plan's rooms split by lines no wall draws), is a finding. Every
+ * room wants walls or separators closing around it, and a name. A terrace closes with separators,
+ * so it is enclosed; a room a person declared open (`enclosureStatus: 'open'` on a room the walls
+ * never derived) needs no walls; an automatic room the reconciler opened when its walls stopped
+ * closing it does.
+ */
+export function roomFindings(nodes, levelId, levelName) {
+    const onLevel = nodesOnLevel(nodes, levelId);
+    const walls = onLevel.filter((node) => node.type === 'wall');
+    const boundaries = onLevel.filter((node) => node.type === 'wall' || node.type === 'separator');
+    const zones = onLevel.filter((node) => node.type === 'zone' && node.polygon.length >= 3);
+    const { spaces } = detectSpacesForLevel(levelId, boundaries);
+    const spaceShapes = spaces.map((space) => shapeOf(space.polygon, space.holes));
+    const zoneShapes = zones.map((zone) => shapeOf(zone.polygon, zone.holes));
+    // A wall with no height of its own stands as high as its storey.
+    const roomWalls = walls.filter((wall) => (wall.height ?? ROOM_WALL_HEIGHT) >= ROOM_WALL_HEIGHT);
+    const rooms = zones.map((zone) => zone.spaceRole === 'room' || walled(zone, roomWalls) >= HALF);
+    const issues = [];
+    spaces.forEach((space, index) => {
+        const shape = spaceShapes[index];
+        // A mezzanine stands over its room, and a zone no room (an analysis area) lies in it: neither
+        // splits the space.
+        const inside = zones.filter((zone, z) => rooms[z] && zone.floor?.support !== 'open' && covered(zoneShapes[z], [shape]) >= HALF);
+        const noRoom = covered(shape, zoneShapes) < HALF;
+        if (!noRoom && inside.length < 2)
+            return;
+        const spaceArea = round(shape.area);
+        const [x, z] = polygonInteriorPoint(space, true).map(round);
+        const place = {
+            levelId,
+            area: spaceArea,
+            at: [x, z],
+            wallIds: space.wallIds,
+        };
+        const where = `On ${levelName}, walls ${space.wallIds.join(', ')} enclose a ${spaceArea.toFixed(1)} m² space at (${x.toFixed(2)}, ${z.toFixed(2)})`;
+        issues.push(noRoom
+            ? { type: 'space_no_room', message: `${where} with no room over it.`, ...place }
+            : {
+                type: 'space_many_rooms',
+                message: `${where} with ${inside.length} rooms over it and no wall between them: ${inside.map(label).join(', ')}. Keep one room per space: name the space's room (create_room over the whole space names it) and delete the others, or divide the space with a wall or separator.`,
+                ...place,
+                zoneIds: inside.map((zone) => zone.id),
+            });
+    });
+    zones.forEach((zone, index) => {
+        if (!rooms[index])
+            return;
+        const room = zone.spaceRole === 'room';
+        const unnamed = PLACEHOLDER_NAME.test(zone.name);
+        const declaredOpen = zone.enclosureStatus === 'open' && !zone.autoFromWalls;
+        const opened = zone.enclosureStatus === 'open' && zone.autoFromWalls;
+        if (!declaredOpen && (opened || covered(zoneShapes[index], spaceShapes) < HALF))
+            issues.push(room
+                ? {
+                    type: 'room_not_enclosed',
+                    message: `Room ${label(zone)} on ${levelName}: its walls do not close around it.`,
+                    levelId,
+                    zoneId: zone.id,
+                }
+                : {
+                    type: 'room_not_enclosed',
+                    message: `Zone ${label(zone)} on ${levelName}: walls run along most of it and do not close around it, a room missing a wall or a courtyard.`,
+                    severity: 'info',
+                    levelId,
+                    zoneId: zone.id,
+                });
+        if (unnamed)
+            issues.push({
+                type: 'room_unnamed',
+                message: `Room ${zone.id} on ${levelName} has no name${zone.name.trim() ? ` but "${zone.name.trim()}"` : ''}.`,
+                severity: 'info',
+                levelId,
+                zoneId: zone.id,
+            });
+    });
+    return { spaces: spaces.length, issues };
+}

package/dist/agent-operations/room-floor-script.d.ts

@@ -0,0 +1,23 @@
+import { type FloorScriptInputs } from '../lib/floor-script.js';
+import { type CompiledGeometryScript } from '../schema/index.js';
+import type { AgentOperation } from './types.js';
+export type SetRoomFloorScriptInput = {
+    zoneId: string;
+    /** The module compiled for `inputs` (`floorScriptInputs` of the room, read before compiling). */
+    compiled: CompiledGeometryScript;
+    inputs: FloorScriptInputs;
+} | {
+    zoneId: string;
+    remove: true;
+};
+/**
+ * `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 declare const setRoomFloorScript: AgentOperation<SetRoomFloorScriptInput>;
+//# sourceMappingURL=room-floor-script.d.ts.map

package/dist/agent-operations/room-floor-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-floor-script.d.ts","sourceRoot":"","sources":["../../src/agent-operations/room-floor-script.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,iBAAiB,EAAwC,MAAM,qBAAqB,CAAA;AAElG,OAAO,EAAE,KAAK,sBAAsB,EAAkC,MAAM,WAAW,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,MAAM,MAAM,uBAAuB,GAC/B;IACE,MAAM,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,QAAQ,EAAE,sBAAsB,CAAA;IAChC,MAAM,EAAE,iBAAiB,CAAA;CAC1B,GACD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAA;AAIpC;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,uBAAuB,CAsDtE,CAAA"}

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

@@ -25,7 +25,7 @@ export declare const ROOM_OPERATIONS: {
             width: number;
             depth: number;
         };
-        drawnOn?: "floor" | "ceiling";
+        drawnOn?: 'floor' | 'ceiling';
         cutsPrimary?: boolean;
         cutsAdjacent?: boolean;
     }>;
@@ -80,7 +80,7 @@ export declare const ROOM_OPERATIONS: {
     }>;
     readonly delete_zone: AgentOperation<{
         zoneId: string;
-        contents: "delete" | "keep";
+        contents: 'delete' | 'keep';
     }>;
 };
 export {};

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

@@ -1 +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;;kBA7JhB,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;;;YAagC,MAAM;;;eAMU,OAAO;;;gBAUrE,MAAM;iBACL,MAAM;eACR,OAAO;;;iCAU0B,MAAM,GAAG,IAAI;;;oBAQzC,MAAM;iBACT,MAAM,EAAE,EAAE;oBACP,MAAM;oBACN,MAAM;;;;mBAgB2D,MAAM,EAAE;;;gBAW7E,MAAM;sBACA,MAAM;mBACT,MAAM;gBACT,OAAO;;;kBAc2C,MAAM;kBAAY,MAAM,EAAE;;;gBAY/B,MAAM;eAAS,OAAO;;;gBAOnE,MAAM;cACR,MAAM,EAAE,EAAE;eACT,MAAM,EAAE,EAAE;iBACR,OAAO;0BACE,MAAM;wBACR,MAAM;;;iBAc6B,MAAM,EAAE;;;gBAMT,MAAM;kBAAY,QAAQ,GAAG,MAAM;;CAyB7E,CAAA"}
+{"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/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;
+}