@pascal-app/core 1.0.3 → 1.0.5

package/dist/agent-operations/place-items.js

@@ -0,0 +1,239 @@
+import { refuse } from '../agent-tools/refusal.js';
+import { OUTSIDE_SOURCES } from '../agent-tools/sources.js';
+import { floorItemFit } from '../building/floor-item-fit.js';
+import { flushMountRotation, geometrySurfaceAt, geometryUndersideAt, mountsFlush, } from '../lib/geometry-surfaces.js';
+import { ItemNode } from '../schema/index.js';
+import { getWallLocalFaceZ } from '../systems/wall/wall-frame.js';
+import { collectDoorKeepouts } from './door-clearance.js';
+import { targetLevel } from './level-target.js';
+import { pointInPolygon, projectWorldPointToWallLocalX, wallLength, } from './plan-geometry.js';
+import { roofLevelRefusal } from './roof-writes.js';
+/**
+ * What belongs on the lot rather than in a room. Anything else placed outside every room of a
+ * level that has rooms is refused: in production a model that had fallen back to raw place_items
+ * put a bed on the lawn (2026-09-04).
+ */
+const OUTDOOR_ASSET = /tree|plant|shrub|bush|hedge|flower|palm|\bfir\b|bench|grill|bbq|barbecue|\bcar\b|vehicle|truck|bike|bicycle|pool|fence|gate|lamp ?post|street|outdoor|garden|patio|deck|swing|trampoline|planter|mailbox|umbrella|parasol/i;
+const isOutdoor = (asset) => OUTDOOR_ASSET.test(`${asset.name} ${asset.category ?? ''} ${(asset.tags ?? []).join(' ')}`);
+function roomsOn(nodes, levelId) {
+    return Object.values(nodes).flatMap((node) => node.type === 'zone' && node.parentId === levelId && node.polygon.length >= 3
+        ? [node.polygon]
+        : []);
+}
+const refused = (assetId, code, error) => ({
+    ok: false,
+    assetId,
+    code,
+    error,
+});
+const round = (value) => Math.round(value * 100) / 100;
+/**
+ * A floor item that does not fit where it is put (`floorItemFit`), refused with what to do:
+ * one its room cannot hold in any turn points to a smaller one; one in a door's way names the door
+ * and a spot in the room that clears every door, when there is one.
+ */
+function floorFit(nodes, levelId, entry, asset, doors) {
+    const misfit = floorItemFit(nodes, {
+        levelId,
+        x: entry.x,
+        z: entry.z,
+        rotationDeg: entry.rotation ?? 0,
+        dimensions: asset.dimensions,
+        doors,
+    });
+    if (!misfit)
+        return null;
+    const [width = 1, , depth = 1] = asset.dimensions ?? [1, 1, 1];
+    if (misfit.code === 'too_large_for_room')
+        return refused(entry.assetId, 'too_large_for_room', `"${asset.name}" is ${round(width)} × ${round(depth)} m; the room it stands in is ${round(misfit.room.width)} × ${round(misfit.room.depth)} m, so it fits in no turn. Pick a smaller one (search_assets), or build one at the room's size with add_object.`);
+    const { candidate } = misfit;
+    return refused(entry.assetId, 'blocks_door', `"${asset.name}" at (${entry.x}, ${entry.z}) stands in the space door ${misfit.doorId} needs to open and be walked through.${candidate
+        ? ` A spot that fits: (${round(candidate.x)}, ${round(candidate.z)}), turned ${candidate.rotationDeg}°.`
+        : ' No spot in this room clears its doors: pick a smaller one, or none.'}`);
+}
+/**
+ * On a wall: along it from its start, the height given for the item's bottom, on the side of the
+ * wall the point is on (the front faces the wall's left, the back is turned round), centred in the
+ * wall or, for a wall-side fixture, on its face. Kept inside the wall's span and height, as the
+ * editor's wall placement keeps it.
+ */
+function onWall(wall, entry, asset) {
+    const [width = 0, height = 0] = asset.dimensions ?? [1, 1, 1];
+    const wallHeight = wall.height ?? 2.5;
+    if (entry.y === undefined)
+        return refused(entry.assetId, 'height_required', `On wall ${wall.id}, give y: the height of the item's bottom above the floor (its top, y + ${height.toFixed(2)} m, must stay under the wall's ${wallHeight.toFixed(2)} m). Art centred at eye level is 1.5 − its height / 2; a sconce about 1.5.`);
+    if (height > wallHeight)
+        return refused(entry.assetId, 'item_too_tall', `"${asset.name}" is ${height.toFixed(2)} m tall; wall ${wall.id} is ${wallHeight.toFixed(2)} m. Pick a shorter item or a taller wall.`);
+    const length = wallLength(wall);
+    const along = projectWorldPointToWallLocalX(wall, [entry.x, 0, entry.z]);
+    const x = Math.max(width / 2, Math.min(length - width / 2, along));
+    const y = Math.max(0, Math.min(wallHeight - height, entry.y));
+    const [dx, dz] = [wall.end[0] - wall.start[0], wall.end[1] - wall.start[1]];
+    // The wall's left (its local +z) is its front.
+    const left = -dz * (entry.x - wall.start[0]) + dx * (entry.z - wall.start[1]) >= 0;
+    const side = left ? 'front' : 'back';
+    const z = asset.attachTo === 'wall-side' ? getWallLocalFaceZ(wall, left ? 'a' : 'b') : 0;
+    const turn = left ? 0 : Math.PI;
+    return {
+        parentId: wall.id,
+        position: [x, y, z],
+        rotation: [0, turn, 0],
+        extra: { wallId: wall.id, wallT: length ? x / length : 0, side },
+        side,
+    };
+}
+/**
+ * On an item standing on the floor: in its frame (translation, turn, scale). An object built with
+ * add_object takes the item on its real surface under the point, or hangs a ceiling item from its
+ * underside above it; a catalog item, on its top. A height given (y above 0) is kept.
+ */
+function onItem(host, entry, asset) {
+    const [hx, hy, hz] = host.position;
+    const yaw = host.rotation[1] ?? 0;
+    const [dx, dz] = [entry.x - hx, entry.z - hz];
+    const lx = (Math.cos(yaw) * dx - Math.sin(yaw) * dz) / host.scale[0];
+    const lz = (Math.sin(yaw) * dx + Math.cos(yaw) * dz) / host.scale[2];
+    const turn = ((entry.rotation ?? 0) * Math.PI) / 180 - yaw;
+    const hanging = asset.attachTo === 'ceiling' && !!host.source;
+    const surface = host.source
+        ? hanging
+            ? geometryUndersideAt(host.source.manifest, lx, lz)
+            : geometrySurfaceAt(host.source.manifest, lx, lz)
+        : null;
+    const explicit = !hanging && entry.y !== undefined && entry.y > 0;
+    const flush = hanging && mountsFlush(asset);
+    const drop = hanging ? (flush ? 0.02 : (asset.dimensions?.[1] ?? 0)) : 0;
+    const y = explicit
+        ? entry.y - hy
+        : surface
+            ? surface.y * host.scale[1] - drop
+            : (host.asset.surface?.height ?? host.asset.dimensions[1]) * host.scale[1];
+    return {
+        parentId: host.id,
+        position: [lx * host.scale[0], y, lz * host.scale[2]],
+        // A flush fixture tilts with a sloped underside (a can in a vault plane).
+        rotation: flush && surface && 'normal' in surface
+            ? flushMountRotation(surface.normal, turn)
+            : [0, turn, 0],
+        ...(!explicit && surface?.part ? { restingOn: surface.part } : {}),
+    };
+}
+/**
+ * `place_items`: catalog items on a level's floor, or on the host each names (a wall, a ceiling,
+ * an item standing on the floor), each placed or refused on its own.
+ */
+export const placeItems = (nodes, input, context) => {
+    const catalog = context.catalog;
+    if (!catalog)
+        refuse('no_catalog', 'This host has no item library to place from; build it with add_object.');
+    const level = targetLevel(nodes, input, context);
+    const create = [];
+    const doorsOn = {};
+    const make = (asset, pose) => {
+        const node = ItemNode.parse({
+            name: asset.name,
+            parentId: pose.parentId,
+            position: pose.position,
+            rotation: pose.rotation,
+            asset,
+            ...pose.extra,
+        });
+        create.push({ node, parentId: pose.parentId });
+        return node;
+    };
+    const items = input.items.map((entry) => {
+        const { assetId, x, z, rotation = 0, targetNodeId } = entry;
+        const asset = catalog.find((candidate) => candidate.id === assetId);
+        if (!asset)
+            return refused(assetId, 'asset_not_found', `Asset "${assetId}" is not in the library. Find a valid id with search_assets.`);
+        const host = targetNodeId ? nodes[targetNodeId] : undefined;
+        if (targetNodeId && !host)
+            return refused(assetId, 'host_not_found', `Host not found: ${targetNodeId}.`);
+        if (host?.type === 'wall' || host?.type === 'ceiling' || host?.type === 'item') {
+            let pose;
+            if (host.type === 'wall')
+                pose = onWall(host, entry, asset);
+            else if (host.type === 'ceiling')
+                // Under its underside, its top flush with it.
+                pose = {
+                    parentId: host.id,
+                    position: [x, -(asset.dimensions?.[1] ?? 0), z],
+                    rotation: [0, (rotation * Math.PI) / 180, 0],
+                };
+            else {
+                if (nodes[host.parentId ?? '']?.type !== 'level')
+                    return refused(assetId, 'host_not_on_level', `${host.name ?? host.id} rests on ${host.parentId}: only an item standing on a floor hosts another here.`);
+                pose = onItem(host, entry, asset);
+            }
+            if ('ok' in pose)
+                return pose;
+            const node = make(asset, pose);
+            return {
+                ok: true,
+                itemId: node.id,
+                assetId,
+                name: asset.name,
+                x,
+                z,
+                hostId: host.id,
+                ...(pose.side ? { side: pose.side } : {}),
+                ...(pose.restingOn ? { restingOn: pose.restingOn } : {}),
+                ...(host.type === 'wall' && entry.rotation !== undefined
+                    ? {
+                        info: {
+                            code: 'rotation_ignored',
+                            message: 'Rotation is ignored on a wall host: the item faces its selected wall side in the wall’s local frame.',
+                        },
+                    }
+                    : {}),
+            };
+        }
+        // A floor: the level named, or the level holding the room or slab named.
+        const floorId = !host
+            ? level.id
+            : host.type === 'level'
+                ? host.id
+                : host.type === 'zone' || host.type === 'slab'
+                    ? (host.parentId ?? '')
+                    : null;
+        if (!floorId || nodes[floorId]?.type !== 'level')
+            return refused(assetId, 'unsupported_host', `A ${host?.type} hosts no item: name a wall, a ceiling, an item standing on the floor, or a room, slab or level for its floor.`);
+        const onRoofLevel = roofLevelRefusal(nodes, floorId, `"${asset.name}"`);
+        if (onRoofLevel)
+            return refused(assetId, onRoofLevel.code, onRoofLevel.message);
+        const rooms = roomsOn(nodes, floorId);
+        const room = rooms.find((polygon) => pointInPolygon([x, z], polygon));
+        if (rooms.length && !isOutdoor(asset) && !room)
+            return refused(assetId, 'outside_rooms', `"${asset.name}" at (${x}, ${z}) is outside every room on this level: indoor items go inside a room (read the rooms with get_zones); trees and garden items may stand outside. Outside a room, ${OUTSIDE_SOURCES}`);
+        doorsOn[floorId] ??= collectDoorKeepouts(Object.values(nodes), { levelId: floorId });
+        const misfit = floorFit(nodes, floorId, entry, asset, doorsOn[floorId]);
+        if (misfit)
+            return misfit;
+        const node = make(asset, {
+            parentId: floorId,
+            position: [x, 0, z],
+            rotation: [0, (rotation * Math.PI) / 180, 0],
+        });
+        return {
+            ok: true,
+            itemId: node.id,
+            assetId,
+            name: asset.name,
+            x,
+            z,
+            ...(host ? { hostId: floorId } : {}),
+        };
+    });
+    const failed = items.length - create.length;
+    return {
+        result: {
+            ok: failed === 0,
+            levelId: level.id,
+            items,
+            message: failed
+                ? `Placed ${create.length} of ${items.length} items (${failed} refused).`
+                : `Placed ${create.length} item${create.length === 1 ? '' : 's'}.`,
+        },
+        ...(create.length ? { changes: { create } } : {}),
+    };
+};

package/dist/agent-operations/plan-geometry.d.ts

@@ -0,0 +1,24 @@
+import type { WallNode } from '../schema/index.js';
+export type Vec2 = [number, number];
+export type Vec3 = [number, number, number];
+export declare function distance2D(a: Vec2, b: Vec2): number;
+export declare function wallLength(wall: Pick<WallNode, 'start' | 'end'>): number;
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function wallLocalXFromT(wall: Pick<WallNode, 'start' | 'end'>, t: number, width: number): number;
+export declare function projectWorldPointToWallLocalX(wall: Pick<WallNode, 'start' | 'end'>, position: Vec3): number;
+export declare function polygonArea(points: Vec2[]): number;
+export declare function polygonBounds(points: Vec2[]): {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+    width: number;
+    depth: number;
+    centerX: number;
+    centerZ: number;
+};
+export declare function pointInBoundsWithPadding(x: number, z: number, bounds: ReturnType<typeof polygonBounds>, padding: number): boolean;
+export declare function pointOnSegment(point: Vec2, a: Vec2, b: Vec2, tolerance?: number): boolean;
+export declare function pointInPolygon(point: Vec2, polygon: Vec2[], includeBoundary?: boolean): boolean;
+export declare function polygonContainsPolygon(outer: Vec2[], inner: Vec2[]): boolean;
+//# sourceMappingURL=plan-geometry.d.ts.map

package/dist/agent-operations/plan-geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-geometry.d.ts","sourceRoot":"","sources":["../../src/agent-operations/plan-geometry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEzC,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AACnC,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAE3C,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAInD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC,GAAG,MAAM,CAExE;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC,EACrC,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,GACZ,MAAM,CAGR;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC,EACrC,QAAQ,EAAE,IAAI,GACb,MAAM,CAWR;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CASlD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG;IAC7C,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB,CAiBA;AAED,wBAAgB,wBAAwB,CACtC,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,EACxC,OAAO,EAAE,MAAM,GACd,OAAO,CAOT;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,SAAO,GAAG,OAAO,CASvF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,eAAe,UAAO,GAAG,OAAO,CAgB5F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAE5E"}

package/dist/agent-operations/plan-geometry.js

@@ -0,0 +1,97 @@
+export function distance2D(a, b) {
+    const dx = b[0] - a[0];
+    const dz = b[1] - a[1];
+    return Math.sqrt(dx * dx + dz * dz);
+}
+export function wallLength(wall) {
+    return distance2D(wall.start, wall.end);
+}
+export function clamp(value, min, max) {
+    if (max < min)
+        return (min + max) / 2;
+    return Math.max(min, Math.min(max, value));
+}
+export function wallLocalXFromT(wall, t, width) {
+    const length = wallLength(wall);
+    return clamp(t * length, width / 2, length - width / 2);
+}
+export function projectWorldPointToWallLocalX(wall, position) {
+    const [sx, sz] = wall.start;
+    const [ex, ez] = wall.end;
+    const dx = ex - sx;
+    const dz = ez - sz;
+    const len = Math.sqrt(dx * dx + dz * dz);
+    if (len === 0)
+        return 0;
+    const px = position[0] - sx;
+    const pz = position[2] - sz;
+    const distance = px * (dx / len) + pz * (dz / len);
+    return clamp(distance, 0, len);
+}
+export function polygonArea(points) {
+    if (points.length < 3)
+        return 0;
+    let area = 0;
+    for (let i = 0; i < points.length; i++) {
+        const current = points[i];
+        const next = points[(i + 1) % points.length];
+        area += current[0] * next[1] - next[0] * current[1];
+    }
+    return Math.abs(area) / 2;
+}
+export function polygonBounds(points) {
+    const xs = points.map((p) => p[0]);
+    const zs = points.map((p) => p[1]);
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+    return {
+        minX,
+        maxX,
+        minZ,
+        maxZ,
+        width: maxX - minX,
+        depth: maxZ - minZ,
+        centerX: (minX + maxX) / 2,
+        centerZ: (minZ + maxZ) / 2,
+    };
+}
+export function pointInBoundsWithPadding(x, z, bounds, padding) {
+    return (x >= bounds.minX + padding &&
+        x <= bounds.maxX - padding &&
+        z >= bounds.minZ + padding &&
+        z <= bounds.maxZ - padding);
+}
+export function pointOnSegment(point, a, b, tolerance = 1e-6) {
+    // A segment of no length (an outline's repeated corner) is its one point, not every point.
+    if (a[0] === b[0] && a[1] === b[1])
+        return distance2D(point, a) <= tolerance;
+    const cross = (point[1] - a[1]) * (b[0] - a[0]) - (point[0] - a[0]) * (b[1] - a[1]);
+    if (Math.abs(cross) > tolerance)
+        return false;
+    const dot = (point[0] - a[0]) * (b[0] - a[0]) + (point[1] - a[1]) * (b[1] - a[1]);
+    if (dot < -tolerance)
+        return false;
+    const lenSq = (b[0] - a[0]) ** 2 + (b[1] - a[1]) ** 2;
+    return dot <= lenSq + tolerance;
+}
+export function pointInPolygon(point, polygon, includeBoundary = true) {
+    if (polygon.length < 3)
+        return false;
+    let inside = false;
+    const [x, z] = point;
+    for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+        const a = polygon[i];
+        const b = polygon[j];
+        if (pointOnSegment(point, a, b))
+            return includeBoundary;
+        const intersects = a[1] > z !== b[1] > z && x < ((b[0] - a[0]) * (z - a[1])) / (b[1] - a[1]) + a[0];
+        if (intersects)
+            inside = !inside;
+    }
+    return inside;
+}
+export function polygonContainsPolygon(outer, inner) {
+    return inner.every((point) => pointInPolygon(point, outer, true));
+}

package/dist/agent-operations/point-context.d.ts

@@ -0,0 +1,139 @@
+/**
+ * What a person pointed at in the scene, and from where: ids first, the picture as evidence.
+ *
+ * One shape for every surface that can carry it. The editor's Point and ask mode builds it; the
+ * chat sends it on the message (`metadata.pointContext`) and tells the agent to act on the ids; the
+ * hosted MCP can take the same object as a tool input later. `camera` is `view_scene`'s own
+ * `camera` input plus the projection, so the agent can look from the person's eye.
+ */
+export type PointContext = {
+    kind: 'scene-point';
+    version: 1;
+    /** "ask_…", minted where the person pointed: the pin, the chat chip and the turn share it. */
+    askId: string;
+    /** ISO time of the moment of pointing (pointer-down), not of sending. */
+    capturedAt: string;
+    source: 'editor' | 'mcp';
+    gesture: 'click' | 'multi' | 'region';
+    /** The level in view. */
+    level: {
+        id: string;
+        name: string;
+    };
+    /** Every pointed element, with no cap: a preview limit is for display, not for the agent. */
+    targets: PointTarget[];
+    /** A region's visible elements, by screen area, top 12; `more` counts the rest. */
+    inRegion?: {
+        ids: string[];
+        more: number;
+    };
+    camera: PointCamera;
+    /** [left, top, right, bottom], each 0–1 of the full frame. */
+    region?: [number, number, number, number];
+    /** The crop. `marked`: the targets are outlined in it. */
+    image?: PointImage;
+    /** The id of the suggestion chip when one was sent as it is. */
+    suggestion?: string;
+};
+export type PointTarget = {
+    /** Authoritative: read it with `get_node` before changing it. */
+    id: string;
+    /** The node type: 'zone' | 'wall' | 'window' | 'door' | 'item' | … */
+    type: string;
+    /** "Kitchen", "Wall, north side of Kitchen", "Sofa, Oslo 3-seat". */
+    name: string;
+    levelId: string;
+    /** The room it is in or bounds. */
+    zoneId?: string;
+    /** The wall an opening is in, the item an item stands on. */
+    parentId?: string;
+    /** Where the finger landed, in world metres. */
+    hit?: {
+        point: [number, number, number];
+        normal: [number, number, number];
+        face?: 'interior' | 'exterior' | 'top' | 'bottom';
+    };
+    box: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    /** Metres: wall {length, height, thickness}; zone {area, width, depth}; opening {width, height, sill}; item {width, depth, height}. */
+    size: Record<string, number>;
+};
+export type PointCamera = {
+    position: [number, number, number];
+    target: [number, number, number];
+    fov: number;
+    aspect: number;
+    projection: 'perspective' | 'orthographic';
+    /** Orthographic only. */
+    viewWidth?: number;
+};
+export type PointImage = {
+    /** Where the crop is stored, once the chat has uploaded it. */
+    url?: string;
+    /** The crop as the editor captured it, before it is uploaded. */
+    dataUrl?: string;
+    width: number;
+    height: number;
+    marked: boolean;
+};
+/** What the editor hands the chat when the person sends an ask. */
+export type PointAskSubmit = {
+    askId: string;
+    /** The person's words. */
+    text: string;
+    context: PointContext;
+    /** The bubble text's screen rect in CSS px, where the message's flight starts. */
+    from: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+/**
+ * The chat's answer to a submit. `busy`: Pascal is on a turn and the host does not queue asks, so
+ * the bubble keeps its words and says so.
+ */
+export type PointAskSubmitResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: 'busy' | 'out_of_credits' | 'unavailable' | 'error';
+    message: string;
+};
+/** What the chat tells the pin about the ask's turn. */
+export type PointAskStatus = {
+    askId: string;
+    turnId?: string;
+} /** Pascal is on another turn: the ask waits as its own turn, never steered into it. */ & ({
+    status: 'queued';
+}
+/** The turn started or its live sentence changed. */
+ | {
+    status: 'working';
+    sentence?: string;
+}
+/** The turn is waiting for the person's answer to a question. */
+ | {
+    status: 'asking';
+    question: string;
+} | {
+    status: 'ended';
+    outcome: 'completed' | 'cancelled' | 'errored';
+    /** The turn ended while still waiting on a question. */
+    asked: boolean;
+    /** The turn made at least one successful scene-writing tool call. */
+    wroteScene: boolean;
+    /** The final reply text. */
+    answer?: string;
+    /** What went wrong, in words. */
+    error?: string;
+});
+/** What the pin tells the chat: its turn lights on hover and opens on click. */
+export type PointAskPin = {
+    askId: string;
+    action: 'hover' | 'leave' | 'open';
+};
+//# sourceMappingURL=point-context.d.ts.map

package/dist/agent-operations/point-context.d.ts.map

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

package/dist/agent-operations/point-context.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-operations/project-files.d.ts

@@ -0,0 +1,9 @@
+import { type ProjectFileToolName } from '../agent-tools/project-files.js';
+export type ProjectFileToolExecutor = (request: {
+    name: ProjectFileToolName;
+    projectId?: string;
+    input: Record<string, unknown>;
+    signal?: AbortSignal;
+}) => Promise<unknown>;
+export declare function executeProjectFileTool(name: string, raw: unknown, execute: ProjectFileToolExecutor, signal?: AbortSignal): Promise<unknown>;
+//# sourceMappingURL=project-files.d.ts.map

package/dist/agent-operations/project-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-files.d.ts","sourceRoot":"","sources":["../../src/agent-operations/project-files.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAGpG,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE;IAC9C,IAAI,EAAE,mBAAmB,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAEtB,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,uBAAuB,EAChC,MAAM,CAAC,EAAE,WAAW,oBA0BrB"}

package/dist/agent-operations/project-files.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { PROJECT_FILE_TOOL_CONTRACTS } from '../agent-tools/project-files.js';
+import { AgentRefusal } from '../agent-tools/refusal.js';
+export async function executeProjectFileTool(name, raw, execute, signal) {
+    const contract = PROJECT_FILE_TOOL_CONTRACTS.find((tool) => tool.name === name);
+    if (!contract)
+        throw new AgentRefusal('unknown_file_tool', 'This project file tool is not available.');
+    const parsed = z.object(contract.input).strict().safeParse(raw);
+    if (!parsed.success)
+        throw new AgentRefusal('invalid_file_input', 'Invalid project file input.', {
+            issues: parsed.error.issues,
+        });
+    const { projectId, ...input } = parsed.data;
+    if (name === 'upload_project_file') {
+        const valid = input.phase === 'text'
+            ? typeof input.content === 'string'
+            : typeof input.size === 'number' &&
+                (input.phase === 'prepare' ||
+                    (typeof input.fileId === 'string' && typeof input.storageKey === 'string'));
+        if (!valid)
+            throw new AgentRefusal('invalid_file_input', 'Text uploads need content; prepare needs size; complete needs size, fileId and storageKey.');
+    }
+    signal?.throwIfAborted();
+    return execute({ name: contract.name, projectId, input, signal });
+}

package/dist/agent-operations/record-made.d.ts

@@ -0,0 +1,18 @@
+import { type SessionKeep, type SessionRecord } from './scene-checkpoint.js';
+import type { SceneNodes } from './types.js';
+/** What a surface lends the recorder: its scene and the session record it keeps. */
+export type MadeRecorderHost = {
+    getNodes: () => SceneNodes;
+    readSession: () => SessionRecord;
+    keep: (keep: SessionKeep) => void;
+};
+/**
+ * Runs a call and keeps what it made in the agent's session: every node in the scene after it that
+ * was not before, whichever way the call wrote it (a tool of its own, a patch, a shell). Writers that
+ * report their own creations (`applyAgentOutcome`) say the same, and a node is made once.
+ *
+ * The session's first call also takes `start`, before anything is written. A call that replaces the
+ * scene (a load, a clear) begins another session, and what it lays down is not the agent's.
+ */
+export declare function recordMade<Result>(host: MadeRecorderHost, run: () => Promise<Result>): Promise<Result>;
+//# sourceMappingURL=record-made.d.ts.map

package/dist/agent-operations/record-made.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-made.d.ts","sourceRoot":"","sources":["../../src/agent-operations/record-made.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,aAAa,EAEnB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEzC,oFAAoF;AACpF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,UAAU,CAAA;IAC1B,WAAW,EAAE,MAAM,aAAa,CAAA;IAChC,IAAI,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;CAClC,CAAA;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,MAAM,EACrC,IAAI,EAAE,gBAAgB,EACtB,GAAG,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GACzB,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/dist/agent-operations/record-made.js

@@ -0,0 +1,28 @@
+import { createdBetween, startOfSession, } from './scene-checkpoint.js';
+/**
+ * Runs a call and keeps what it made in the agent's session: every node in the scene after it that
+ * was not before, whichever way the call wrote it (a tool of its own, a patch, a shell). Writers that
+ * report their own creations (`applyAgentOutcome`) say the same, and a node is made once.
+ *
+ * The session's first call also takes `start`, before anything is written. A call that replaces the
+ * scene (a load, a clear) begins another session, and what it lays down is not the agent's.
+ */
+export async function recordMade(host, run) {
+    // A copy: a host may write its own map in place, and a "before" that grows reads nothing as new.
+    const before = { ...host.getNodes() };
+    const first = startOfSession(host.readSession(), before);
+    if (first)
+        host.keep(first);
+    const began = host.readSession().checkpoints.start;
+    try {
+        return await run();
+    }
+    finally {
+        // The session of a scene too large to remember has no start, and nothing to look back from.
+        if (began && host.readSession().checkpoints.start === began) {
+            const made = createdBetween(before, host.getNodes());
+            if (made.length)
+                host.keep({ made });
+        }
+    }
+}

package/dist/agent-operations/roof-footprint.d.ts

@@ -0,0 +1,24 @@
+type Pt = [number, number];
+export type RoofRectangle = {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+};
+export type RoofFootprint = {
+    rectangles: RoofRectangle[];
+    roofType: 'gable' | 'hip' | 'flat';
+};
+export declare function roofRectangles(polygons: readonly (readonly Pt[])[]): RoofFootprint;
+/**
+ * The frame a roof is swept in: the footprint's own axes, from its longest edge, so a rotated
+ * building gets whole wings, not a staircase of segments along the world axes. The rotation
+ * convention is a roof node's: local (x, z) → (x c + z s, -x s + z c).
+ */
+export declare function buildingFrame(polygons: readonly (readonly Pt[])[]): {
+    angle: number;
+    polygons: Pt[][];
+    toWorld: ([x, z]: Pt) => Pt;
+};
+export {};
+//# sourceMappingURL=roof-footprint.d.ts.map

package/dist/agent-operations/roof-footprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roof-footprint.d.ts","sourceRoot":"","sources":["../../src/agent-operations/roof-footprint.ts"],"names":[],"mappings":"AAOA,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAC1B,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AACtF,MAAM,MAAM,aAAa,GAAG;IAAE,UAAU,EAAE,aAAa,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;CAAE,CAAA;AAoE/F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,GAAG,aAAa,CA6HlF;AA4DD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE;;;sBAmB5C,EAAE,KAAG,EAAE;EAE5B"}