@pascal-app/core 1.0.3 → 1.0.5

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene-queries.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAA;AACvD,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAOD,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,CAAC,OAAO,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,EAAE,CAI3E;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAStE;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,EAAE,CAetE;AAED,6EAA6E;AAC7E,eAAO,MAAM,YAAY,UAAW,UAAU,WAAW,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAAkC,CAAA;AAEjG,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,aAAa,CAexE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO;;;;EAY1D"}

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

@@ -0,0 +1,74 @@
+import { isCeilingGeometry, isRoofGeometry, servesAsRoofLevel } from '../services/roof-level.js';
+const metadataString = (node, key) => {
+    const value = node.metadata?.[key];
+    return typeof value === 'string' ? value : undefined;
+};
+/** Every level, in floor order (ties by id). */
+export function levelsOf(nodes) {
+    return Object.values(nodes)
+        .filter((node) => node.type === 'level')
+        .sort((a, b) => a.level - b.level || a.id.localeCompare(b.id));
+}
+/** The level a node sits on, walking up its parents (a level resolves to itself). */
+export function levelIdOf(nodes, id) {
+    const seen = new Set();
+    let current = nodes[id];
+    while (current && !seen.has(current.id)) {
+        if (current.type === 'level')
+            return current.id;
+        seen.add(current.id);
+        current = current.parentId ? nodes[current.parentId] : undefined;
+    }
+    return null;
+}
+/** Everything under a node, at any depth, in the order the editor lists it; the node excluded. */
+export function descendantsOf(nodes, id) {
+    const found = [];
+    const seen = new Set([id]);
+    const walk = (parentId) => {
+        const node = nodes[parentId];
+        if (!node || !('children' in node) || !Array.isArray(node.children))
+            return;
+        for (const child of node.children) {
+            if (seen.has(child) || !nodes[child])
+                continue;
+            seen.add(child);
+            found.push(nodes[child]);
+            walk(child);
+        }
+    };
+    walk(id);
+    return found;
+}
+/** Everything on a level, at any depth, in the order the editor lists it. */
+export const nodesOnLevel = (nodes, levelId) => descendantsOf(nodes, levelId);
+export function contentCounts(content) {
+    const count = (type) => content.filter((node) => node.type === type).length;
+    return {
+        walls: count('wall'),
+        zones: count('zone'),
+        doors: count('door'),
+        windows: count('window'),
+        items: content.filter((node) => node.type === 'item' && !isRoofGeometry(node) && !isCeilingGeometry(node)).length,
+        slabs: count('slab'),
+        ceilings: content.filter(isCeilingGeometry).length,
+        roofs: content.filter(isRoofGeometry).length,
+        stairs: count('stair'),
+    };
+}
+/**
+ * A level is a storey unless it serves as its building's roof level (`servesAsRoofLevel`, the one
+ * rule) or is declared a support.
+ */
+export function levelRole(nodes, level) {
+    const role = level.type === 'level' && servesAsRoofLevel(nodes, level)
+        ? 'roof'
+        : metadataString(level, 'role') === 'support'
+            ? 'support'
+            : 'occupied';
+    return {
+        role,
+        metadataRole: metadataString(level, 'role') ?? null,
+        referenceLevelId: metadataString(level, 'referenceLevelId') ?? null,
+    };
+}

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

@@ -0,0 +1,52 @@
+import { type SessionRecord } from './scene-checkpoint.js';
+import { type LostSinceCheckpointIssue, type MeasureChange } from './scene-measure.js';
+import type { SceneNodes } from './types.js';
+export type ReviewGroup = {
+    levelId: string | null;
+    level: string;
+    kind: string;
+    created: number;
+    changed: number;
+    deleted: number;
+    ids: {
+        created: string[];
+        changed: string[];
+        deleted: string[];
+    };
+    /** A ready view_scene call that shows the group. */
+    view?: {
+        target: string;
+        from: 'south-west';
+        elevation: 35;
+    };
+};
+export type LostElement = {
+    id: string;
+    kind: string;
+    level: string;
+    name?: string;
+    when: 'there at the checkpoint' | 'made since the checkpoint';
+};
+export type SinceReview = {
+    checkpoint: string;
+    totals: {
+        created: number;
+        changed: number;
+        deleted: number;
+    };
+    groups: ReviewGroup[];
+    /** What the agent made and is gone now, since the checkpoint. */
+    lost: LostElement[];
+    /** The registered families, by place: windows, lit rooms… that are gone or new. */
+    places?: {
+        changes: MeasureChange[];
+        issues: LostSinceCheckpointIssue[];
+    };
+};
+/**
+ * The scene now against a checkpoint the session named: what was created, changed and deleted,
+ * grouped by level and kind with a view each, and what the agent made that is gone. Pure: the
+ * session record comes from the host.
+ */
+export declare function reviewSince(session: SessionRecord, name: string, nodes: SceneNodes): SinceReview;
+//# sourceMappingURL=scene-review.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scene-review.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-review.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAgB,KAAK,wBAAwB,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAOzC,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IAChE,oDAAoD;IACpD,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAC;QAAC,SAAS,EAAE,EAAE,CAAA;KAAE,CAAA;CAC7D,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,yBAAyB,GAAG,2BAA2B,CAAA;CAC9D,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7D,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,iEAAiE;IACjE,IAAI,EAAE,WAAW,EAAE,CAAA;IACnB,mFAAmF;IACnF,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAAC,MAAM,EAAE,wBAAwB,EAAE,CAAA;KAAE,CAAA;CAC1E,CAAA;AAUD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,WAAW,CAiGhG"}

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

@@ -0,0 +1,106 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { getLevelDisplayName } from '../lib/level-name.js';
+import { hashNode as hashOf } from './scene-checkpoint.js';
+import { changesSince } from './scene-measure.js';
+import { levelIdOf, levelsOf } from './scene-queries.js';
+/** A node of these kinds can be the target of a view_scene; the others are seen through their level. */
+const VIEWABLE = new Set(['wall', 'zone', 'door', 'window', 'item']);
+/** A group lists this many ids of each kind; the counts are exact. */
+const IDS_PER_KIND = 12;
+/**
+ * The scene now against a checkpoint the session named: what was created, changed and deleted,
+ * grouped by level and kind with a view each, and what the agent made that is gone. Pure: the
+ * session record comes from the host.
+ */
+export function reviewSince(session, name, nodes) {
+    const checkpoint = session.checkpoints[name];
+    if (!checkpoint) {
+        const names = Object.keys(session.checkpoints);
+        refuse('checkpoint_not_found', names.length
+            ? `There is no checkpoint "${name}". The session has: ${names.join(', ')}.`
+            : `There is no checkpoint "${name}", and the session has none: name this moment with set_checkpoint.`, { checkpoints: names });
+    }
+    const buckets = new Map();
+    const bucket = (levelId, kind) => {
+        const key = `${levelId ?? ''}|${kind}`;
+        let found = buckets.get(key);
+        if (!found) {
+            found = { levelId, kind, created: [], changed: [], deleted: [] };
+            buckets.set(key, found);
+        }
+        return found;
+    };
+    const levelName = (levelId) => {
+        if (!levelId)
+            return 'The building';
+        const level = nodes[levelId];
+        if (level?.type === 'level')
+            return getLevelDisplayName(level);
+        return checkpoint.nodes[levelId]?.name ?? levelId;
+    };
+    for (const node of Object.values(nodes)) {
+        const was = checkpoint.nodes[node.id];
+        const levelId = levelIdOf(nodes, node.id);
+        if (!was)
+            bucket(levelId, node.type).created.push(node.id);
+        else if (was.hash !== hashOf(node))
+            bucket(levelId, node.type).changed.push(node.id);
+    }
+    for (const [id, was] of Object.entries(checkpoint.nodes))
+        if (!nodes[id])
+            bucket(was.levelId, was.type).deleted.push(id);
+    const order = new Map(levelsOf(nodes).map((level, index) => [level.id, index]));
+    const groups = [...buckets.values()]
+        .sort((a, b) => (order.get(a.levelId ?? '') ?? 1e6) - (order.get(b.levelId ?? '') ?? 1e6) ||
+        a.kind.localeCompare(b.kind))
+        .map((entry) => {
+        const touched = [...entry.created, ...entry.changed];
+        const only = touched.length === 1 && entry.deleted.length === 0 ? touched[0] : undefined;
+        const target = only && VIEWABLE.has(entry.kind) ? only : (entry.levelId ?? firstBuilding(nodes));
+        const cap = (ids) => ids.slice().sort().slice(0, IDS_PER_KIND);
+        return {
+            levelId: entry.levelId,
+            level: levelName(entry.levelId),
+            kind: entry.kind,
+            created: entry.created.length,
+            changed: entry.changed.length,
+            deleted: entry.deleted.length,
+            ids: {
+                created: cap(entry.created),
+                changed: cap(entry.changed),
+                deleted: cap(entry.deleted),
+            },
+            ...(target
+                ? { view: { target, from: 'south-west', elevation: 35 } }
+                : {}),
+        };
+    });
+    const lost = [];
+    session.made.forEach((entry, index) => {
+        if (nodes[entry.id])
+            return;
+        const there = entry.id in checkpoint.nodes;
+        if (!there && index < checkpoint.madeAt)
+            return;
+        lost.push({
+            id: entry.id,
+            kind: entry.type,
+            level: levelName(entry.levelId),
+            ...(entry.name ? { name: entry.name } : {}),
+            when: there ? 'there at the checkpoint' : 'made since the checkpoint',
+        });
+    });
+    const places = changesSince({ name: checkpoint.name, measure: checkpoint.measure }, nodes);
+    return {
+        checkpoint: name,
+        totals: {
+            created: groups.reduce((sum, group) => sum + group.created, 0),
+            changed: groups.reduce((sum, group) => sum + group.changed, 0),
+            deleted: groups.reduce((sum, group) => sum + group.deleted, 0),
+        },
+        groups,
+        lost,
+        ...(places.changes.length ? { places } : {}),
+    };
+}
+const firstBuilding = (nodes) => Object.values(nodes).find((node) => node.type === 'building')?.id;

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

@@ -0,0 +1,165 @@
+import { type COMPASS_SIDES, type VIEW_LIGHTING, type VIEW_SIDES } from '../agent-tools/view-scene.js';
+import type { AnyNode, LevelNode } from '../schema/index.js';
+/**
+ * Where `view_scene` looks from, the same on every surface; the picture is the host's: the chat's
+ * editor renders it, the MCP asks an editor tab open on the project.
+ */
+export type SceneViewBox = {
+    min: [number, number, number];
+    max: [number, number, number];
+};
+export type SceneViewSide = (typeof VIEW_SIDES)[number];
+type CompassSide = (typeof COMPASS_SIDES)[number];
+/** The light a host renders a view in; the scene's own when absent. */
+export type SceneViewLighting = Exclude<(typeof VIEW_LIGHTING)[number], 'current'>;
+export type SceneViewInput = {
+    target?: string;
+    interior?: SceneViewInteriorInput;
+    presentation?: SceneViewPresentation;
+    from?: SceneViewSide;
+    position?: number[];
+    elevation?: number;
+    eyeHeight?: number;
+    fov?: number;
+    projection?: 'perspective' | 'orthographic';
+    camera?: 'current' | {
+        position: number[];
+        target: number[];
+        fov: number;
+        aspect: number;
+    };
+    lighting?: (typeof VIEW_LIGHTING)[number];
+    maxPx?: number;
+    photo?: {
+        source: string;
+        region: number[];
+    };
+};
+/**
+ * The person's own view, as the host's editor shows it now: what `camera: 'current'` looks
+ * through. A host with no person's view (the MCP) has none.
+ */
+export type SceneViewCurrentCamera = {
+    position: [number, number, number];
+    target: [number, number, number];
+    projection: 'perspective' | 'orthographic';
+    fov?: number;
+    /** Metres across the view at its target, for an orthographic camera. */
+    viewWidth?: number;
+    /** The canvas' width over its height. */
+    aspect: number;
+};
+/** A region of the reference photo the host crops and returns beside the view. */
+export type SceneViewCrop = {
+    source: string;
+    region: [number, number, number, number];
+};
+/** A look inside one floor; the host cuts it from its own scene with sceneViewInterior. */
+export type SceneViewInterior = {
+    levelId: string;
+    roomId?: string;
+};
+/** What the agent asks for: a floor to look into, or a room (zone) to stand inside. */
+export type SceneViewInteriorInput = {
+    levelId?: string;
+    zoneId?: string;
+};
+export type SceneViewPresentation = {
+    mode: 'stacked' | 'exploded';
+} | {
+    mode: 'solo';
+    levelId: string;
+};
+/** Validate against the scene being rendered as well as the scene used to request the view. */
+export declare function sceneViewPresentationLevel(nodes: Readonly<Record<string, AnyNode>>, presentation: SceneViewPresentation | undefined): LevelNode | undefined;
+/** Older renderers may ignore new view options; their frames cannot verify those views. */
+export declare function confirmSceneViewPresentation(requested: SceneViewPresentation | undefined, applied: SceneViewPresentation | undefined): void;
+/**
+ * What an interior view of a floor shows, from the scene the host renders: the floor's box (its
+ * walls' extent, its storey's height), the height its walls are cut at, and what the picture leaves
+ * out, every other floor and this floor's roofs and ceilings. The live scene is never changed.
+ */
+export declare function sceneViewInterior(nodes: Readonly<Record<string, AnyNode>>, levelId: string): {
+    bounds: SceneViewBox;
+    cutHeight: number;
+    hiddenIds: string[];
+};
+export type SceneViewPose = {
+    projection: 'perspective';
+    position: [number, number, number];
+    target: [number, number, number];
+    fov: number;
+} | {
+    projection: 'orthographic';
+    position: [number, number, number];
+    target: [number, number, number];
+    viewWidth: number;
+};
+/**
+ * The picture's size, the most of each side: a shelf's books and a door's handles read. Vision
+ * models scale a picture down past ~1568 px on its long side, so more costs bytes and nothing seen.
+ */
+export declare const VIEW_SIZE: {
+    readonly w: 1920;
+    readonly h: 1200;
+};
+/** A crop comes back at most this long on either host: the region as the photo has it, never larger than a view. */
+export declare const PHOTO_CROP_LONGEST: 1920;
+/** A crop comes back at least this long, enlarged if smaller, so a small element's detail reads. */
+export declare const PHOTO_CROP_SHORTEST_LONG_SIDE = 512;
+/** The size a crop of `width` × `height` pixels comes back at. */
+export declare function photoCropSize(width: number, height: number): {
+    width: number;
+    height: number;
+};
+type Pt = [number, number];
+/**
+ * Which way a door or a window faces, outward, as a unit vector in the site's plan (x, z): what a
+ * view of it is taken from, and what a camera that follows the build looks at it along. The same
+ * for a wall with an exterior side: the way that side faces. Null for anything else, and for a wall
+ * with no exterior side.
+ */
+export declare function sceneViewFacing(nodes: Readonly<Record<string, AnyNode>>, id: string): [number, number] | null;
+/**
+ * What a view frames: the walls of the target (a building, a level, a wall) or a zone's outline,
+ * each at its storey's height, and the roofs over them up to their peaks; every storey by default.
+ * Plan guides never count: an imported plan is drawn much larger than its building.
+ */
+export declare function sceneViewBounds(nodes: Readonly<Record<string, AnyNode>>, targetId?: string, presentation?: SceneViewPresentation): SceneViewBox;
+/** A viewpoint of the eye's own, the side it stands on a compass side, above, or a plan direction. */
+export type SceneViewPoseInput = Pick<SceneViewInput, 'position' | 'elevation' | 'eyeHeight' | 'fov' | 'projection'> & {
+    from?: CompassSide | 'above' | Pt;
+};
+/**
+ * Where the eye stands: on the side asked (south-west by default), a few degrees up, far enough
+ * that the whole target is in frame; or at a street-level height; or exactly where it is put.
+ * The orthographic view looks square on and is as wide as the target seen from there.
+ */
+export declare function sceneViewPose(box: SceneViewBox, input: SceneViewPoseInput): SceneViewPose;
+/**
+ * What a view comes with, on both surfaces: a picture to compare, not a measure; a floor below grade
+ * is seen through the veiled ground. With the picture's `pose`, also the fact of ground standing
+ * between that viewpoint and the building, veiled where it would hide it.
+ */
+export declare function sceneViewNote(nodes?: Readonly<Record<string, AnyNode>>, interior?: SceneViewInterior, pose?: SceneViewPose): string;
+/**
+ * The view to render, its size and its light: through a camera given whole (a photo's, at the
+ * photo's aspect so the two lay one beside the other, or the person's own, which the host passes
+ * as `currentCamera`); else framing the target at the standard size, from a compass side or a side
+ * of the street the site records.
+ */
+export declare function sceneViewPlan(nodes: Readonly<Record<string, AnyNode>>, input: SceneViewInput, { currentCamera }?: {
+    currentCamera?: SceneViewCurrentCamera | null;
+}): {
+    pose: SceneViewPose;
+    size: {
+        w: number;
+        h: number;
+    };
+    crop?: SceneViewCrop;
+    interior?: SceneViewInterior;
+    presentation?: SceneViewPresentation;
+    lighting?: SceneViewLighting;
+};
+export {};
+//# sourceMappingURL=scene-view.d.ts.map

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

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