@pascal-app/core 1.0.4 → 1.0.5

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

@@ -1,9 +1,40 @@
 import { refuse } from '../agent-tools/refusal.js';
+import { VIEW_MAX_PX, } from '../agent-tools/view-scene.js';
+import { levelGradeStanding } from '../lib/grade-standing.js';
+import { buildingGroundBox, levelGroundBox, terrainBetweenEyeAndBox } from '../lib/ground-window.js';
+import { distanceToSegment } from '../lib/room-topology-index.js';
+import { buildingStreet } from '../lib/site-placement.js';
 import { getActiveRoofHeight } from '../schema/index.js';
-import { getLevelElevations } from '../services/storey.js';
+import { isCeilingGeometry, isRoofGeometry } from '../services/roof-level.js';
+import { EXPLODED_GAP, getLevelElevations } from '../services/storey.js';
 import { resolveWallExteriorSide } from '../systems/wall/wall-assembly.js';
+import { pointInPolygon } from './plan-geometry.js';
+/** Validate against the scene being rendered as well as the scene used to request the view. */
+export function sceneViewPresentationLevel(nodes, presentation) {
+    if (presentation?.mode !== 'solo')
+        return undefined;
+    const level = nodes[presentation.levelId];
+    if (level?.type !== 'level')
+        refuse('presentation_level_invalid', 'Solo needs an existing level id.', {
+            levelId: presentation.levelId,
+        });
+    if (ancestry(nodes, level).some((node) => node.visible === false && node.type !== 'site'))
+        refuse('presentation_level_hidden', 'Show the level before inspecting it in Solo.', {
+            levelId: level.id,
+        });
+    return level;
+}
+/** Older renderers may ignore new view options; their frames cannot verify those views. */
+export function confirmSceneViewPresentation(requested, applied) {
+    if (requested &&
+        (applied?.mode !== requested.mode ||
+            (requested.mode === 'solo' &&
+                (applied?.mode !== 'solo' || applied.levelId !== requested.levelId))))
+        refuse('view_presentation_unconfirmed', 'The renderer did not confirm the requested level view. Refresh the renderer and retry; this picture cannot verify Solo or Exploded behavior.', { requested, applied: applied ?? null });
+}
 /** How high up its storey an interior view cuts a floor: low enough to see every room. */
 const INTERIOR_CUT = 0.65;
+const INTERIOR_CUT_WORDS = `${INTERIOR_CUT}`;
 /** Degrees above the horizon an interior view looks down from, by default. */
 const INTERIOR_ELEVATION = 55;
 /** A node and every node it stands under, nearest first. */
@@ -39,7 +70,7 @@ export function sceneViewInterior(nodes, levelId) {
     const hiddenIds = Object.values(nodes)
         .filter((node) => node.type === 'level'
         ? node.id !== levelId
-        : (node.type === 'roof' || node.type === 'ceiling') &&
+        : (isRoofGeometry(node) || isCeilingGeometry(node)) &&
             ancestry(nodes, node).some((at) => at.id === levelId))
         .map((node) => node.id);
     if (level.children.length && level.children.every((id) => hiddenIds.includes(id)))
@@ -62,8 +93,11 @@ function cropOf(photo) {
         refuse('photo_region_invalid', `The region [${photo.region.join(', ')}] holds nothing: give [left, top, right, bottom] in the photo's pixels, right of left and below top.`, { region: photo.region });
     return { source: photo.source, region: [left, top, right, bottom] };
 }
-/** The picture's size: enough to read a facade's bays, few tokens. */
-export const VIEW_SIZE = { w: 1280, h: 800 };
+/**
+ * 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 const VIEW_SIZE = { w: 1920, h: 1200 };
 const ASPECT = VIEW_SIZE.w / VIEW_SIZE.h;
 /** A crop comes back at most this long on either host: the region as the photo has it, never larger than a view. */
 export const PHOTO_CROP_LONGEST = VIEW_SIZE.w;
@@ -91,11 +125,47 @@ const COMPASS = {
     west: [-1, 0],
     'north-west': [-Math.SQRT1_2, -Math.SQRT1_2],
 };
+/** How far each street side turns from the street toward the street viewer's left, in degrees. */
+const STREET_TURN = {
+    street: 0,
+    'street-left': 45,
+    left: 90,
+    'back-left': 135,
+    back: 180,
+    'back-right': -135,
+    right: -90,
+    'street-right': -45,
+};
+const isStreetSide = (side) => Object.hasOwn(STREET_TURN, side);
 /**
- * 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; every wall by default. Plan guides never count: an imported plan
- * is drawn much larger than its building.
+ * Where a street side stands in the plan, from the street of the house it looks at (core's
+ * `buildingStreet`: the street its site records, else the house's own front). Standing in the
+ * street facing the house you look along -toward, and in this frame (x east, z south, y up) your
+ * left hand points along (-toward.z, toward.x): on a lot whose street is north, that is east.
+ */
+function streetDirection(nodes, side, lookedAt) {
+    const [fx, fz] = buildingStreet(nodes, framedBuilding(nodes, lookedAt)?.id);
+    const turn = (STREET_TURN[side] * Math.PI) / 180;
+    // `+ 0` so a vector along an axis reads 0, not -0.
+    return [
+        fx * Math.cos(turn) - fz * Math.sin(turn) + 0,
+        fz * Math.cos(turn) + fx * Math.sin(turn) + 0,
+    ];
+}
+/**
+ * The building a view is of: the one holding what it looks at (a target, an interior's floor),
+ * else the scene's. Buildings on several sites each face their own street, so a street side then
+ * needs the building as target.
  */
+function framedBuilding(nodes, lookedAt) {
+    if (lookedAt)
+        return ancestry(nodes, lookedAt).find((node) => node.type === 'building') ?? null;
+    const buildings = Object.values(nodes).filter((node) => node.type === 'building');
+    const sites = new Set(buildings.map((building) => building.parentId ?? null));
+    if (sites.size > 1)
+        refuse('which_building', `The scene has buildings on ${sites.size} sites, each facing its own street: give the building as target.`, { buildings: buildings.map((building) => building.id) });
+    return buildings[0] ?? null;
+}
 /** A door or a window and the wall it is in, when the target is one. */
 function openingOf(nodes, target) {
     if (target?.type !== 'door' && target?.type !== 'window')
@@ -300,6 +370,21 @@ function outwardOf(opening, wall, yaw) {
     // `+ 0` so a vector along an axis reads 0, not -0.
     return [ux * Math.cos(yaw) + uz * Math.sin(yaw) + 0, -ux * Math.sin(yaw) + uz * Math.cos(yaw) + 0];
 }
+/**
+ * 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 function sceneViewFacing(nodes, id) {
+    const opening = openingOf(nodes, nodes[id]);
+    if (opening)
+        return outwardOf(opening.opening, opening.wall, standingOf(nodes, opening.wall.parentId).yaw);
+    const wall = nodes[id];
+    if (wall?.type !== 'wall' || resolveWallExteriorSide(wall) === null)
+        return null;
+    return outwardOf(wall, wall, standingOf(nodes, wall.parentId).yaw);
+}
 const AT_ORIGIN = { x: 0, y: 0, z: 0, yaw: 0 };
 function standingOf(nodes, levelId) {
     const level = levelId ? nodes[levelId] : undefined;
@@ -337,14 +422,23 @@ function placedBox(box, at) {
         ],
     };
 }
-export function sceneViewBounds(nodes, targetId) {
+/**
+ * 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 function sceneViewBounds(nodes, targetId, presentation) {
     const target = targetId ? nodes[targetId] : undefined;
     if (targetId && !target)
         refuse('target_not_found', `Nothing to look at: ${targetId} is not in the scene.`, {
             target: targetId,
         });
     const elevations = getLevelElevations(nodes);
-    const baseOf = (levelId) => (levelId ? elevations.get(levelId)?.baseY : undefined) ?? 0;
+    const baseOf = (levelId) => {
+        const level = levelId ? elevations.get(levelId) : undefined;
+        return ((level?.baseY ?? 0) +
+            (presentation?.mode === 'exploded' ? (level?.ordinal ?? 0) * EXPLODED_GAP : 0));
+    };
     const placed = (box, levelId) => placedBox(box, standingOf(nodes, levelId));
     const opening = openingOf(nodes, target);
     if (opening)
@@ -364,8 +458,11 @@ export function sceneViewBounds(nodes, targetId) {
     const levelOf = (node) => (node.parentId ? nodes[node.parentId] : undefined);
     const outlines = [];
     // With no walls yet, what the level holds frames it: furniture placed from a plan before the
-    // walls are built, a site with its paving and fences.
+    // walls are built, a site with its paving and fences. The roofs frame with the walls, and so does
+    // a plugin's node (a roof plane), whose shape core cannot read: up to its storey's top.
     const held = [];
+    const roofs = [];
+    let pluginTop = Number.NEGATIVE_INFINITY;
     for (const node of Object.values(nodes)) {
         const level = levelOf(node);
         if (level?.type !== 'level')
@@ -388,18 +485,21 @@ export function sceneViewBounds(nodes, targetId) {
                 levelId: level.id,
             });
         else if (node.type === 'item')
-            held.push(placedBox(itemBox(node, baseOf(level.id)), at));
+            (isRoofGeometry(node) ? roofs : held).push(placedBox(itemBox(node, baseOf(level.id)), at));
+        else if (node.type.includes(':')) {
+            const storey = elevations.get(level.id);
+            if (storey)
+                pluginTop = Math.max(pluginTop, baseOf(level.id) + storey.height + at.y);
+        }
         else {
             const box = levelChildBox(nodes, node, baseOf(level.id));
             if (box)
-                held.push(placedBox(box, at));
+                (node.type === 'roof' ? roofs : held).push(placedBox(box, at));
         }
     }
-    if (!outlines.length && held.length)
-        return {
-            min: [0, 1, 2].map((axis) => Math.min(...held.map((box) => box.min[axis]))),
-            max: [0, 1, 2].map((axis) => Math.max(...held.map((box) => box.max[axis]))),
-        };
+    const upTo = (box) => pluginTop > box.max[1] ? { min: box.min, max: [box.max[0], pluginTop, box.max[2]] } : box;
+    if (!outlines.length && (held.length || roofs.length))
+        return upTo(union([...held, ...roofs]));
     if (!outlines.length)
         refuse('nothing_to_view', target
             ? `${target.type} ${target.id} holds nothing built to look at: give a building, a level, a wall, a zone or what was placed.`
@@ -409,8 +509,8 @@ export function sceneViewBounds(nodes, targetId) {
     for (const { points, levelId } of outlines) {
         const storey = elevations.get(levelId) ?? { baseY: 0, height: 3 };
         const lift = standingOf(nodes, levelId).y;
-        min[1] = Math.min(min[1], storey.baseY + lift);
-        max[1] = Math.max(max[1], storey.baseY + storey.height + lift);
+        min[1] = Math.min(min[1], baseOf(levelId) + lift);
+        max[1] = Math.max(max[1], baseOf(levelId) + storey.height + lift);
         for (const [x, z] of points) {
             min[0] = Math.min(min[0], x);
             max[0] = Math.max(max[0], x);
@@ -418,7 +518,14 @@ export function sceneViewBounds(nodes, targetId) {
             max[2] = Math.max(max[2], z);
         }
     }
-    return { min, max };
+    return upTo(union([{ min, max }, ...roofs]));
+}
+/** The box around boxes. */
+function union(boxes) {
+    return {
+        min: [0, 1, 2].map((axis) => Math.min(...boxes.map((box) => box.min[axis]))),
+        max: [0, 1, 2].map((axis) => Math.max(...boxes.map((box) => box.max[axis]))),
+    };
 }
 const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
 const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
@@ -446,7 +553,7 @@ export function sceneViewPose(box, input) {
     const radius = Math.hypot(...sub(box.max, box.min)) / 2 || 1;
     const side = input.from ?? 'south-west';
     const elevation = ((side === 'above' ? 89 : (input.elevation ?? DEFAULT_ELEVATION)) * Math.PI) / 180;
-    const [dx, dz] = side === 'above' ? COMPASS.south : COMPASS[side];
+    const [dx, dz] = side === 'above' ? COMPASS.south : typeof side === 'string' ? COMPASS[side] : side;
     const direction = [Math.cos(elevation) * dx, Math.sin(elevation), Math.cos(elevation) * dz];
     const corners = [];
     for (const x of [box.min[0], box.max[0]])
@@ -499,20 +606,244 @@ export function sceneViewPose(box, input) {
         fov,
     };
 }
+/** What a picture into a floor below grade shows over it, said so the agent describes it right. */
+const BELOW_GRADE_NOTE = 'The floor lies below grade: the ground over it is drawn as a faint veil, so its rooms show through it.';
+const PARTLY_BELOW_GRADE_NOTE = 'The floor lies partly below grade: the ground stands over part of it.';
+const GROUND_IN_THE_WAY_NOTE = 'Ground stands between this viewpoint and the building: where it would hide it, the ground is drawn as a faint veil; the rest of the ground is solid.';
+const ROOM_EYE_NOTE = (name) => `The eye stands inside ${name} at a person's height, looking across it: the walls, openings and furniture of its floor are cut at ${INTERIOR_CUT_WORDS} of the storey's height and its ceiling is left out.`;
 /**
- * The view to render and its size: from a photo's camera at the photo's aspect, so the two lay
- * one beside the other; else framing the target at the standard size.
+ * 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.
  */
-/** What a view comes with, on both surfaces: a picture to compare, not a measure. */
-export function sceneViewNote() {
-    return 'A picture to compare with the reference, not a measure: take sizes and counts from the tools.';
+export function sceneViewNote(nodes, interior, pose) {
+    const notes = [
+        'A picture to compare with the reference, not a measure: take sizes and counts from the tools.',
+    ];
+    if (nodes && interior) {
+        const standing = levelGradeStanding(nodes, interior.levelId);
+        if (standing === 'below-grade')
+            notes.push(BELOW_GRADE_NOTE);
+        if (standing === 'partly-below-grade')
+            notes.push(PARTLY_BELOW_GRADE_NOTE);
+    }
+    if (nodes && pose) {
+        const asNodes = nodes;
+        const box = interior ? levelGroundBox(asNodes, interior.levelId) : buildingGroundBox(asNodes);
+        if (box && terrainBetweenEyeAndBox(asNodes, pose.position, box))
+            notes.push(GROUND_IN_THE_WAY_NOTE);
+    }
+    const room = interior?.roomId ? nodes?.[interior.roomId] : undefined;
+    if (nodes && pose && room?.type === 'zone') {
+        const { bounds } = sceneViewInterior(nodes, interior.levelId);
+        const { outline, holes } = roomOnSite(nodes, room, bounds.min[1]);
+        const eye = [pose.position[0], pose.position[2]];
+        if (pointInPolygon(eye, outline, false) &&
+            !holes.some((hole) => pointInPolygon(eye, hole)) &&
+            pose.position[1] >= bounds.min[1] &&
+            pose.position[1] <= bounds.max[1])
+            notes.push(ROOM_EYE_NOTE(room.name || room.id));
+    }
+    return notes.join(' ');
+}
+/** A picture of `w` × `h`, made smaller to `maxPx` on its longest side, `VIEW_MAX_PX` at most. */
+function sized(w, h, maxPx = VIEW_MAX_PX) {
+    const scale = Math.min(1, maxPx / Math.max(w, h));
+    return { w: Math.round(w * scale), h: Math.round(h * scale) };
+}
+/** The pose of a camera given whole: a photo's, or the person's own. */
+function cameraPose(camera, current) {
+    if (camera !== 'current')
+        return {
+            pose: {
+                projection: 'perspective',
+                position: camera.position,
+                target: camera.target,
+                fov: camera.fov,
+            },
+            aspect: camera.aspect,
+        };
+    if (!current)
+        refuse('no_current_camera', "There is no view of the person's to look through here: give a side (from), a position or a photo's camera.");
+    const { position, target, aspect } = current;
+    return {
+        pose: current.projection === 'orthographic' && current.viewWidth
+            ? { projection: 'orthographic', position, target, viewWidth: current.viewWidth }
+            : { projection: 'perspective', position, target, fov: current.fov ?? DEFAULT_FOV },
+        aspect,
+    };
 }
-export function sceneViewPlan(nodes, input) {
+/** How high a person's eyes stand above the floor: the eye of a room view, unless eyeHeight says. */
+const ROOM_EYE_HEIGHT = 1.6;
+/** The field of view of a view from inside a room: wide, as a person takes a room in. */
+const ROOM_FOV = 75;
+/** Height of the point a room view looks at: the middle of what stands in the room. */
+const ROOM_AIM_HEIGHT = 1.0;
+/** What an interior asks for, checked: the floor it looks into, and the room it stands in if any. */
+function interiorRequest(nodes, request) {
+    const { levelId, zoneId } = request;
+    if (Boolean(levelId) === Boolean(zoneId))
+        refuse('interior_one_of', 'interior takes a levelId (look into a floor) or a zoneId (stand inside a room), one of them.');
+    if (levelId)
+        return { interior: { levelId } };
+    const zone = nodes[zoneId];
+    if (zone?.type !== 'zone')
+        refuse('interior_room_invalid', `An interior view of a room needs a zone id (get_zones lists them): ${zoneId} is none.`, { zoneId });
+    const level = nodes[zone.parentId ?? ''];
+    if (level?.type !== 'level' || zone.polygon.length < 3)
+        refuse('interior_room_invalid', `${zoneId} has no outline on a floor to stand in: give another room, or a levelId.`, { zoneId });
+    return { interior: { levelId: level.id, roomId: zone.id }, room: zone };
+}
+/** A room's outline and holes on the site, and the box of its floor's height over its outline. */
+function roomOnSite(nodes, room, floorY) {
+    const at = standingOf(nodes, room.parentId);
+    const outline = room.polygon.map((point) => onSite(point, at));
+    const holes = room.holes.map((hole) => hole.map((point) => onSite(point, at)));
+    const storey = getLevelElevations(nodes).get(room.parentId ?? '');
+    const xs = outline.map((point) => point[0]);
+    const zs = outline.map((point) => point[1]);
+    const box = {
+        min: [Math.min(...xs), floorY, Math.min(...zs)],
+        max: [Math.max(...xs), floorY + (storey?.height ?? 3), Math.max(...zs)],
+    };
+    return { outline, holes, box };
+}
+/** How far a point stands from the nearest wall of an outline. */
+function clearanceOf(outline, point) {
+    return Math.min(...outline.map((corner, i) => distanceToSegment(point, corner, outline[(i + 1) % outline.length])));
+}
+/**
+ * The point of a room farthest from its walls: the middle of an L as well as of a square, which
+ * the corners' average is not.
+ */
+function roomMiddle(outline, inRoom) {
+    const xs = outline.map((point) => point[0]);
+    const zs = outline.map((point) => point[1]);
+    const [minX, maxX] = [Math.min(...xs), Math.max(...xs)];
+    const [minZ, maxZ] = [Math.min(...zs), Math.max(...zs)];
+    let best = [(minX + maxX) / 2, (minZ + maxZ) / 2];
+    let bestClearance = inRoom(best) ? clearanceOf(outline, best) : -1;
+    const steps = 24;
+    for (let i = 0; i <= steps; i++)
+        for (let j = 0; j <= steps; j++) {
+            const point = [minX + ((maxX - minX) * i) / steps, minZ + ((maxZ - minZ) * j) / steps];
+            if (!inRoom(point))
+                continue;
+            const room = clearanceOf(outline, point);
+            if (room > bestClearance)
+                [best, bestClearance] = [point, room];
+        }
+    return best;
+}
+/**
+ * A person standing in a room, looking across it: the eye a step in from the corner farthest from
+ * what it looks at (or, given a side, from the corner on that side), at eye height, aimed at the
+ * room's middle or at the target. Everything is on the site, in metres.
+ */
+function roomEyeView(outline, holes, floorY, { aim, side, eyeHeight = ROOM_EYE_HEIGHT, fov = ROOM_FOV, }) {
+    const inRoom = (point) => pointInPolygon(point, outline, false) && !holes.some((hole) => pointInPolygon(point, hole));
+    const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+    const middle = roomMiddle(outline, inRoom);
+    const looksAt = aim ? [aim[0], aim[2]] : middle;
+    let eye;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    for (const corner of outline) {
+        const toMiddle = distance(corner, middle) || 1;
+        const inward = [(middle[0] - corner[0]) / toMiddle, (middle[1] - corner[1]) / toMiddle];
+        // A step in from the corner, further in a room too narrow to hold the first.
+        const standing = [0.6, 1, 1.6]
+            .filter((step) => step <= toMiddle * 0.8)
+            .map((step) => [corner[0] + inward[0] * step, corner[1] + inward[1] * step])
+            .find((point) => inRoom(point) && clearanceOf(outline, point) >= 0.25);
+        if (!standing)
+            continue;
+        const score = side
+            ? ((corner[0] - middle[0]) * side[0] + (corner[1] - middle[1]) * side[1]) / toMiddle
+            : distance(standing, looksAt);
+        if (score > bestScore)
+            [eye, bestScore] = [standing, score];
+    }
+    if (!eye) {
+        // A room too small for a corner to stand in: from its middle, toward its farthest corner.
+        const far = outline.reduce((a, b) => (distance(b, middle) > distance(a, middle) ? b : a));
+        return {
+            projection: 'perspective',
+            position: [round(middle[0]), round(floorY + eyeHeight), round(middle[1])],
+            target: [round(far[0]), round(floorY + ROOM_AIM_HEIGHT), round(far[1])],
+            fov,
+        };
+    }
+    if (aim)
+        return {
+            projection: 'perspective',
+            position: [round(eye[0]), round(floorY + eyeHeight), round(eye[1])],
+            target: [round(aim[0]), round(aim[1]), round(aim[2])],
+            fov,
+        };
+    // Across the room: the far end of the line from the eye through the room's middle, so the eye
+    // looks level at a wall and not down at the floor a step away.
+    const length = distance(eye, middle) || 1;
+    const along = [(middle[0] - eye[0]) / length, (middle[1] - eye[1]) / length];
+    let far = middle;
+    for (let reach = length; reach < 100; reach += 0.1) {
+        const point = [eye[0] + along[0] * reach, eye[1] + along[1] * reach];
+        if (!inRoom(point))
+            break;
+        far = point;
+    }
+    return {
+        projection: 'perspective',
+        position: [round(eye[0]), round(floorY + eyeHeight), round(eye[1])],
+        target: [round(far[0]), round(floorY + ROOM_AIM_HEIGHT), round(far[1])],
+        fov,
+    };
+}
+/**
+ * A level below grade on all of its footprint is seen from inside: from outside, the ground
+ * covers it. One only partly below grade keeps its outside view — the ground in the way is
+ * veiled in the picture instead.
+ */
+function belowGradeInterior(nodes, target) {
+    return target?.type === 'level' &&
+        levelGradeStanding(nodes, target.id) === 'below-grade'
+        ? { levelId: target.id }
+        : undefined;
+}
+/**
+ * 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 function sceneViewPlan(nodes, input, { currentCamera } = {}) {
     const { camera } = input;
+    const presentation = input.presentation;
+    if (presentation && input.interior)
+        refuse('presentation_and_interior', 'Choose a level presentation or a clipped interior view.');
+    const solo = sceneViewPresentationLevel(nodes, presentation);
+    if (solo) {
+        if (input.target && !nodes[input.target])
+            refuse('target_not_found', 'The target is not in the scene.', { target: input.target });
+        if (input.target && !ancestry(nodes, nodes[input.target]).some((node) => node.id === solo.id))
+            refuse('presentation_target_elsewhere', 'The target must belong to the soloed level.', {
+                target: input.target,
+                levelId: solo.id,
+            });
+    }
     const crop = cropOf(input.photo);
-    const inside = input.interior && sceneViewInterior(nodes, input.interior.levelId);
-    const interior = input.interior && { levelId: input.interior.levelId };
     const target = input.target ? nodes[input.target] : undefined;
+    const requested = input.interior ? interiorRequest(nodes, input.interior) : undefined;
+    const room = requested?.room;
+    // A level below grade is looked into when none is asked for: from outside, the ground covers it.
+    const interior = requested?.interior ?? belowGradeInterior(nodes, target);
+    const inside = interior && sceneViewInterior(nodes, interior.levelId);
+    const lighting = input.lighting === 'current' ? undefined : input.lighting;
+    const extras = {
+        ...(crop ? { crop } : {}),
+        ...(interior ? { interior } : {}),
+        ...(presentation ? { presentation } : {}),
+        ...(lighting ? { lighting } : {}),
+    };
     // An interior view shows this floor alone, without its roofs and ceilings: a target left out of
     // the picture would frame nothing shown.
     if (interior && inside && target) {
@@ -526,34 +857,60 @@ export function sceneViewPlan(nodes, input) {
     if (camera) {
         const own = ['from', 'position', 'elevation', 'eyeHeight', 'fov', 'projection'].filter((key) => input[key] !== undefined);
         if (own.length)
-            refuse('camera_and_viewpoint', `Give the photo's camera or a viewpoint of your own, not both (${own.join(', ')}).`, { fields: own });
-        return {
-            pose: {
-                projection: 'perspective',
-                position: camera.position,
-                target: camera.target,
-                fov: camera.fov,
-            },
-            size: { w: VIEW_SIZE.w, h: Math.round(VIEW_SIZE.w / camera.aspect) },
-            ...(crop ? { crop } : {}),
-            ...(interior ? { interior } : {}),
-        };
+            refuse('camera_and_viewpoint', `Give a camera or a viewpoint of your own, not both (${own.join(', ')}).`, { fields: own });
+        const { pose, aspect } = cameraPose(camera, currentCamera);
+        return { pose, size: sized(VIEW_SIZE.w, VIEW_SIZE.w / aspect, input.maxPx), ...extras };
     }
     const opening = openingOf(nodes, target);
-    const from = input.from ??
-        (opening && !input.position
+    const side = input.from;
+    const from = side
+        ? isStreetSide(side)
+            ? streetDirection(nodes, side, target ?? solo ?? (interior && nodes[interior.levelId]))
+            : side
+        : opening && !input.position
             ? outsideSide(opening.opening, opening.wall, standingOf(nodes, opening.wall.parentId).yaw)
-            : undefined);
+            : undefined;
     // Inside a floor, the eye looks down into it over the cut walls.
     const lookDown = inside && input.elevation === undefined && input.eyeHeight === undefined;
+    const { position, elevation, eyeHeight, fov, projection } = input;
+    const placedRoom = room && inside && roomOnSite(nodes, room, inside.bounds.min[1]);
+    // A room is looked at from inside, a person's height up, unless the eye is put (position) or
+    // lifted over it (elevation, from above, orthographic): then it is the cut room from outside.
+    if (placedRoom &&
+        position === undefined &&
+        elevation === undefined &&
+        side !== 'above' &&
+        projection !== 'orthographic') {
+        const aimBox = input.target ? sceneViewBounds(nodes, input.target) : undefined;
+        return {
+            pose: roomEyeView(placedRoom.outline, placedRoom.holes, inside.bounds.min[1], {
+                aim: aimBox && [
+                    (aimBox.min[0] + aimBox.max[0]) / 2,
+                    (aimBox.min[1] + aimBox.max[1]) / 2,
+                    (aimBox.min[2] + aimBox.max[2]) / 2,
+                ],
+                side: typeof from === 'string' ? (from === 'above' ? undefined : COMPASS[from]) : from,
+                eyeHeight,
+                fov,
+            }),
+            size: sized(VIEW_SIZE.w, VIEW_SIZE.h, input.maxPx),
+            ...extras,
+        };
+    }
     return {
-        pose: sceneViewPose(input.target || !inside ? sceneViewBounds(nodes, input.target) : inside.bounds, {
-            ...input,
-            ...(lookDown ? { elevation: INTERIOR_ELEVATION } : {}),
-            ...(from ? { from } : {}),
+        pose: sceneViewPose(input.target || !inside
+            ? sceneViewBounds(nodes, input.target ?? solo?.id, presentation)
+            : placedRoom
+                ? placedRoom.box
+                : inside.bounds, {
+            position,
+            elevation: lookDown ? INTERIOR_ELEVATION : elevation,
+            eyeHeight,
+            fov,
+            projection,
+            from,
         }),
-        size: { ...VIEW_SIZE },
-        ...(crop ? { crop } : {}),
-        ...(interior ? { interior } : {}),
+        size: sized(VIEW_SIZE.w, VIEW_SIZE.h, input.maxPx),
+        ...extras,
     };
 }

package/dist/agent-operations/search-assets.d.ts

@@ -6,8 +6,8 @@ type SearchAssetsInput = {
     }[];
 };
 /**
- * `search_assets`: the host's item library, one group of hits per query. A miss points to
- * add_object, the way to build what no library holds, without naming a design for it.
+ * `search_assets`: the host's item library, one group of hits per query. A miss names the other
+ * sources there are for the need, as a fact.
  */
 export declare const searchAssets: AgentOperation<SearchAssetsInput>;
 export {};

package/dist/agent-operations/search-assets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-assets.d.ts","sourceRoot":"","sources":["../../src/agent-operations/search-assets.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,KAAK,iBAAiB,GAAG;IAAE,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,CAAA;AAY5E;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,iBAAiB,CA0B1D,CAAA"}
+{"version":3,"file":"search-assets.d.ts","sourceRoot":"","sources":["../../src/agent-operations/search-assets.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,KAAK,iBAAiB,GAAG;IAAE,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,CAAA;AAY5E;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,iBAAiB,CA0B1D,CAAA"}

package/dist/agent-operations/search-assets.js

@@ -1,4 +1,5 @@
 import { refuse } from '../agent-tools/refusal.js';
+import { OTHER_SOURCES } from '../agent-tools/sources.js';
 function matches(item, { query, category }) {
     if (category && item.category !== category)
         return false;
@@ -10,8 +11,8 @@ function matches(item, { query, category }) {
         .every((term) => haystack.includes(term));
 }
 /**
- * `search_assets`: the host's item library, one group of hits per query. A miss points to
- * add_object, the way to build what no library holds, without naming a design for it.
+ * `search_assets`: the host's item library, one group of hits per query. A miss names the other
+ * sources there are for the need, as a fact.
  */
 export const searchAssets = (_nodes, { queries }, context) => {
     const catalog = context.catalog;
@@ -35,7 +36,7 @@ export const searchAssets = (_nodes, { queries }, context) => {
             groups,
             total: groups.reduce((sum, group) => sum + group.total, 0),
             ...(missed.length && {
-                hint: `Nothing in the library matches ${missed.join(', ')}. Build what it lacks with add_object.`,
+                hint: `Nothing in the library matches ${missed.join(', ')}. ${OTHER_SOURCES}`,
             }),
         },
     };

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

@@ -1,12 +1,18 @@
-import { type MaterialSurface } from '../material-library.js';
+import type { MaterialCategory, MaterialSurface } from '../material-kinds.js';
 import type { AgentOperation } from './types.js';
 type SearchMaterialsInput = {
     queries: {
-        query: string;
+        query?: string;
+        kind?: MaterialCategory;
         surface?: MaterialSurface;
+        offset?: number;
     }[];
 };
-/** `search_materials`: the library's materials by words, best first, and the words none answers. */
+/**
+ * `search_materials`: the library's materials by words, best first, and the words none answers;
+ * without a query, a browse of a kind, a surface or the whole library. Either lists a page at a
+ * time, saying how many more there are and the offset that lists them.
+ */
 export declare const searchMaterials: AgentOperation<SearchMaterialsInput>;
 export {};
 //# sourceMappingURL=search-materials.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"search-materials.d.ts","sourceRoot":"","sources":["../../src/agent-operations/search-materials.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,KAAK,oBAAoB,GAAG;IAAE,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,eAAe,CAAA;KAAE,EAAE,CAAA;CAAE,CAAA;AA6FvF,oGAAoG;AACpG,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,oBAAoB,CAoC/D,CAAA"}
+{"version":3,"file":"search-materials.d.ts","sourceRoot":"","sources":["../../src/agent-operations/search-materials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAM1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7C,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;QAAC,OAAO,CAAC,EAAE,eAAe,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACnG,CAAA;AA+HD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,oBAAoB,CAkDhE,CAAA"}