@pascal-app/core 1.0.3 → 1.0.5

package/dist/agent-operations/__fixtures__/view-assets-cases.d.ts

@@ -0,0 +1,3 @@
+import type { AgentToolCase } from './cases.js';
+export declare const VIEW_ASSETS_CASES: AgentToolCase[];
+//# sourceMappingURL=view-assets-cases.d.ts.map

package/dist/agent-operations/__fixtures__/view-assets-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-assets-cases.d.ts","sourceRoot":"","sources":["../../../src/agent-operations/__fixtures__/view-assets-cases.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,SAAS,CAAA;AAwCxD,eAAO,MAAM,iBAAiB,EAAE,aAAa,EA+H5C,CAAA"}

package/dist/agent-operations/__fixtures__/view-assets-cases.js

@@ -0,0 +1,155 @@
+/**
+ * `view_assets`: a picture of catalog items by id, with their size and the names of their
+ * paintable surfaces. The host reads the pictures and the surfaces before the call (`assetViews`);
+ * the operation says what it was given and what it was not, as facts. What goes wrong, written
+ * first: an id the library lacks answered with nothing; an item with no named surfaces read as one
+ * whose surfaces are unknown; a host that cannot fetch pictures answering as if it had.
+ */
+const item = (id, name, dimensions) => ({
+    id,
+    name,
+    category: 'furniture',
+    tags: [],
+    thumbnail: `https://library.test/${id}/thumbnail.png`,
+    src: `https://library.test/${id}/model.glb`,
+    dimensions,
+});
+const LIBRARY = [
+    item('single-bed', 'Single Bed', [1.5, 0.7, 2.5]),
+    item('bunkbed', 'Bunkbed', [1.2, 1.8, 2.1]),
+    item('sofa', 'Sofa', [2.5, 0.8, 1.5]),
+    item('desk', 'Desk', [1.4, 0.75, 0.7]),
+    item('dresser', 'Dresser', [1.5, 0.8, 1]),
+    item('lamp', 'Lamp', [0.3, 1.5, 0.3]),
+];
+const PICTURE = 'data:image/webp;base64,UklGRg==';
+const seen = (...surfaces) => ({ picture: PICTURE, surfaces });
+const noScene = () => ({ nodes: {}, rootNodeIds: [] });
+const library = (assetViews) => ({
+    activeLevelId: null,
+    catalog: LIBRARY,
+    ...(assetViews ? { assetViews } : {}),
+});
+export const VIEW_ASSETS_CASES = [
+    {
+        name: 'one item: its size, category and surface names, and a picture shown',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: ['single-bed'] },
+        context: library({ 'single-bed': seen('sheet', 'pillow', 'matress', 'frame') }),
+        readOnly: true,
+        expect: {
+            result: {
+                shown: 1,
+                items: [
+                    {
+                        id: 'single-bed',
+                        name: 'Single Bed',
+                        category: 'furniture',
+                        dimensions: [1.5, 0.7, 2.5],
+                        surfaces: ['sheet', 'pillow', 'matress', 'frame'],
+                        picture: true,
+                    },
+                ],
+            },
+            check: (result) => ('note' in result ? ['a note on a call that showed everything'] : []),
+        },
+    },
+    {
+        name: 'six items in one call, each with a picture, in the order asked',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: LIBRARY.map((entry) => entry.id) },
+        context: library(Object.fromEntries(LIBRARY.map((entry) => [entry.id, seen('body')]))),
+        readOnly: true,
+        expect: {
+            result: { shown: 6 },
+            check: (result) => {
+                const ids = result.items.map((entry) => entry.id);
+                return ids.join() === LIBRARY.map((entry) => entry.id).join()
+                    ? []
+                    : [`items came back as ${ids.join()}`];
+            },
+        },
+    },
+    {
+        name: 'an id twice is one picture',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: ['sofa', 'sofa'] },
+        context: library({ sofa: seen('body', 'cushion', 'pillow') }),
+        readOnly: true,
+        expect: { result: { shown: 1, items: [{ id: 'sofa' }] } },
+    },
+    {
+        name: 'an id the library lacks is refused with the fact, and nothing is shown',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: ['sofa', 'throne'] },
+        context: library({ sofa: seen('body') }),
+        readOnly: true,
+        expect: {
+            refusal: 'unknown_asset',
+            mentions: ['"throne" is not in the item library', 'search_assets', 'Nothing was shown'],
+        },
+    },
+    {
+        name: 'an item whose model names no surface says so',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: ['bunkbed'] },
+        context: library({ bunkbed: seen() }),
+        readOnly: true,
+        expect: { result: { shown: 1, items: [{ id: 'bunkbed', surfaces: [], picture: true }] } },
+    },
+    {
+        name: 'a host that read nothing gives the sizes, and says no picture is shown',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: ['desk', 'lamp'] },
+        context: library(),
+        readOnly: true,
+        expect: {
+            result: {
+                shown: 0,
+                items: [
+                    { id: 'desk', dimensions: [1.4, 0.75, 0.7], surfaces: null, picture: false },
+                    { id: 'lamp', surfaces: null, picture: false },
+                ],
+            },
+            mentions: ['2 of 2 items show no picture here'],
+        },
+    },
+    {
+        name: 'a picture that could not be fetched leaves the surfaces and names why',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: ['dresser', 'sofa'] },
+        context: library({
+            dresser: { surfaces: ['drawers', 'body'], unavailable: 'its picture could not be fetched (the file answered 404)' },
+            sofa: seen('body'),
+        }),
+        readOnly: true,
+        expect: {
+            result: {
+                shown: 1,
+                items: [
+                    { id: 'dresser', surfaces: ['drawers', 'body'], picture: false },
+                    { id: 'sofa', picture: true },
+                ],
+            },
+            mentions: ['1 of 2 items show no picture here', 'the file answered 404'],
+        },
+    },
+    {
+        name: 'a host with no library has nothing to look in',
+        tool: 'view_assets',
+        scene: noScene,
+        input: { ids: ['sofa'] },
+        context: { activeLevelId: null },
+        // The standalone MCP always has its built-in list.
+        surfaces: ['core', 'chat'],
+        readOnly: true,
+        expect: { refusal: 'no_catalog' },
+    },
+];

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

@@ -0,0 +1,50 @@
+import { type AnyNode } from '../../schema/index.js';
+import type { SceneViewBox, SceneViewCurrentCamera, SceneViewInput, SceneViewLighting, SceneViewPose } from '../scene-view.js';
+/**
+ * `view_scene`'s case table: every view the house picture tool it replaces (`screenshot_3d`, a
+ * street-relative picture of the finished house) was asked for, as the `view_scene` call that
+ * covers it, run without a model by the core, MCP and chat runners. `was` is the call it replaces:
+ * its every view, light and size, and the calls stored Pro threads made (`{}`, `street-left`,
+ * `back-left` in daylight). The expected sides and boxes are worked by hand from each lot, not read
+ * back from the planner.
+ */
+type Pt = [number, number];
+type Surface = 'core' | 'mcp' | 'chat';
+export type ViewSceneCase = {
+    name: string;
+    was: string;
+    scene: () => Record<string, AnyNode>;
+    input: SceneViewInput;
+    /** The person's own view, for the hosts that have one (the chat). */
+    currentCamera?: SceneViewCurrentCamera;
+    surfaces?: Surface[];
+    expect: {
+        refusal: string;
+    } | {
+        /** The plan direction (x, z) the eye stands in from what it looks at, within 2°. */
+        eyeToward?: Pt;
+        /** The least angle above the horizon the eye looks down from, in degrees. */
+        eyeAbove?: number;
+        /** A box every corner of which is in the picture. */
+        frames?: SceneViewBox;
+        pose?: SceneViewPose;
+        size?: {
+            w: number;
+            h: number;
+        };
+        /** The light the host renders in; absent for the scene's own. */
+        lighting?: SceneViewLighting;
+    };
+};
+export declare const VIEW_SCENE_CASES: readonly ViewSceneCase[];
+/** What a planned view gets wrong against its case: the problems, if any. */
+export declare function viewSceneCaseProblems(c: ViewSceneCase, plan: {
+    pose: SceneViewPose;
+    size: {
+        w: number;
+        h: number;
+    };
+    lighting?: SceneViewLighting;
+}): string[];
+export {};
+//# sourceMappingURL=view-scene-cases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"view-scene-cases.d.ts","sourceRoot":"","sources":["../../../src/agent-operations/__fixtures__/view-scene-cases.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACd,MAAM,eAAe,CAAA;AAEtB;;;;;;;GAOG;AAEH,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAC1B,KAAK,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;AAEtC,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,KAAK,EAAE,cAAc,CAAA;IACrB,qEAAqE;IACrE,aAAa,CAAC,EAAE,sBAAsB,CAAA;IACtC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;IACpB,MAAM,EACF;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GACnB;QACE,oFAAoF;QACpF,SAAS,CAAC,EAAE,EAAE,CAAA;QACd,6EAA6E;QAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,qDAAqD;QACrD,MAAM,CAAC,EAAE,YAAY,CAAA;QACrB,IAAI,CAAC,EAAE,aAAa,CAAA;QACpB,IAAI,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;QAC/B,iEAAiE;QACjE,QAAQ,CAAC,EAAE,iBAAiB,CAAA;KAC7B,CAAA;CACN,CAAA;AA6KD,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAoPpD,CAAA;AAID,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,CAAC,EAAE,aAAa,EAChB,IAAI,EAAE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;CAAE,GAC1F,MAAM,EAAE,CAuBV"}

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

@@ -0,0 +1,425 @@
+import { BuildingNode, LevelNode, RoofNode, RoofSegmentNode, SiteNode, WallNode, } from '../../schema/index.js';
+const H = Math.SQRT1_2;
+/** Links parents' children; the graph's roots are its sites, or its buildings with none. */
+function scene(...nodes) {
+    const byId = Object.fromEntries(nodes.map((node) => [node.id, { ...node }]));
+    for (const node of Object.values(byId)) {
+        const parent = node.parentId ? byId[node.parentId] : undefined;
+        if (parent && Array.isArray(parent.children) && !parent.children.includes(node.id))
+            parent.children = [...parent.children, node.id];
+    }
+    return byId;
+}
+const LOT = [
+    [0, 0],
+    [30, 0],
+    [30, 30],
+    [0, 30],
+];
+/**
+ * A two-storey house, 12 × 8 m and 2.7 m a storey, its hip roof (30°, 12 × 8 m) on a roof level
+ * of its own, standing at `at` on a 30 m lot. Edge 1 of the lot runs from (30, 0) to (30, 30): the
+ * east line. The roof peaks 4 tan 30° m over its 4 m half-span, on the 5.4 m of the two storeys.
+ */
+function house(site, { at = [9, 0, 11], yaw = 0, roof = 'core', suffix = '', } = {}) {
+    const lot = site && SiteNode.parse({ id: `site_lot${suffix}`, children: [], ...site });
+    const building = BuildingNode.parse({
+        id: `building_house${suffix}`,
+        ...(lot ? { parentId: lot.id } : {}),
+        children: [],
+        position: at,
+        rotation: [0, yaw, 0],
+    });
+    const storeys = [0, 1].map((index) => LevelNode.parse({
+        id: `level_${index}${suffix}`,
+        parentId: building.id,
+        level: index,
+        height: 2.7,
+        children: [],
+    }));
+    const corners = [
+        [0, 0],
+        [12, 0],
+        [12, 8],
+        [0, 8],
+    ];
+    const walls = storeys.flatMap((level) => corners.map((start, index) => WallNode.parse({
+        id: `wall_${level.id}_${index}`,
+        parentId: level.id,
+        start,
+        end: corners[(index + 1) % 4],
+    })));
+    const roofLevel = LevelNode.parse({
+        id: `level_roof${suffix}`,
+        parentId: building.id,
+        level: 2,
+        height: 3,
+        children: [],
+    });
+    const segment = RoofSegmentNode.parse({
+        id: `rseg_house${suffix}`,
+        parentId: `roof_house${suffix}`,
+        roofType: 'hip',
+        width: 12,
+        depth: 8,
+        pitch: 30,
+        wallHeight: 0,
+    });
+    const roofNodes = roof === 'core'
+        ? [
+            RoofNode.parse({
+                id: `roof_house${suffix}`,
+                parentId: roofLevel.id,
+                position: [6, 0, 4],
+                children: [segment.id],
+            }),
+            segment,
+        ]
+        : [
+            {
+                id: `roofplane_house${suffix}`,
+                type: 'procedural:roof-plane',
+                parentId: roofLevel.id,
+                polygon: [
+                    [-0.5, -0.5],
+                    [12.5, -0.5],
+                    [12.5, 4],
+                    [-0.5, 4],
+                ],
+                baseline: [
+                    [-0.5, -0.5],
+                    [12.5, -0.5],
+                ],
+                baseHeight: 0,
+                pitch: 12,
+            },
+        ];
+    return scene(...(lot ? [lot] : []), building, ...storeys, ...walls, roofLevel, ...roofNodes);
+}
+const PEAK = 5.4 + 4 * Math.tan(Math.PI / 6);
+/** The house at (9, 0, 11), square to the lot: every storey and the roof. */
+const WHOLE_HOUSE = { min: [9, 0, 11], max: [21, PEAK, 19] };
+/** A lot whose recorded front is its east line. */
+const eastFront = () => house({ polygon: { type: 'polygon', points: LOT }, frontEdge: 1 });
+const STREET_SIDES = [
+    { from: 'street', toward: [1, 0], words: 'straight at the front, from the street (east)' },
+    {
+        from: 'street-left',
+        toward: [H, H],
+        words: "the street viewer's left front corner: facing west from the street, the south-east",
+    },
+    { from: 'street-right', toward: [H, -H], words: 'the right front corner, the north-east' },
+    { from: 'left', toward: [0, 1], words: "the street viewer's left side, the south" },
+    { from: 'right', toward: [0, -1], words: 'the right side, the north' },
+    { from: 'back', toward: [-1, 0], words: 'the back, away from the street: the west' },
+    { from: 'back-left', toward: [-H, H], words: 'the back-left corner, the south-west' },
+    { from: 'back-right', toward: [-H, -H], words: 'the back-right corner, the north-west' },
+];
+/** Two lots side by side, each with a house: the west lot's street is north, the east lot's east. */
+function twoLots() {
+    const west = house({ polygon: { type: 'polygon', points: LOT }, frontEdge: 0 });
+    const east = house({
+        polygon: { type: 'polygon', points: LOT.map(([x, z]) => [x + 40, z]) },
+        frontEdge: 1,
+    }, { at: [49, 0, 11], suffix: '_east' });
+    return { ...west, ...east };
+}
+const PERSON = {
+    position: [-6, 9, 30],
+    target: [15, 2, 15],
+    projection: 'perspective',
+    fov: 50,
+    viewWidth: 24,
+    aspect: 16 / 9,
+};
+export const VIEW_SCENE_CASES = [
+    {
+        name: 'by default, every storey and the roof, whatever floor the person is on',
+        was: "every screenshot_3d picture: the finished house, every storey and the roof (from view_scene's own default, the south-west; screenshot_3d {} was street-left, the next row)",
+        scene: eastFront,
+        input: {},
+        expect: { eyeToward: [-H, H], frames: WHOLE_HOUSE },
+    },
+    ...STREET_SIDES.map(({ from, toward, words }) => ({
+        name: `${from}: ${words}, every storey and the roof in frame`,
+        was: from === 'street-left'
+            ? "screenshot_3d {} or { view: 'street-left' }, as stored Pro threads call it"
+            : `screenshot_3d { view: '${from}' }`,
+        scene: eastFront,
+        input: { from },
+        expect: { eyeToward: toward, frames: WHOLE_HOUSE },
+    })),
+    {
+        name: 'an aerial view: the street-left corner, high',
+        was: "screenshot_3d { view: 'aerial' }",
+        scene: eastFront,
+        input: { from: 'street-left', elevation: 40 },
+        expect: { eyeToward: [H, H], eyeAbove: 39, frames: WHOLE_HOUSE },
+    },
+    {
+        name: 'the house from above',
+        was: "screenshot_3d { view: 'top' }",
+        scene: eastFront,
+        input: { from: 'above' },
+        expect: { eyeAbove: 85, frames: WHOLE_HOUSE },
+    },
+    {
+        name: 'a lot that records only its street edges takes the first as its street',
+        was: "screenshot_3d { view: 'street' }",
+        // Edge 2 runs from (30, 30) to (0, 30): the south line.
+        scene: () => house({ polygon: { type: 'polygon', points: LOT }, streetEdges: [2] }),
+        input: { from: 'street' },
+        expect: { eyeToward: [0, 1], frames: WHOLE_HOUSE },
+    },
+    {
+        name: 'a house turned on its lot is still seen from the street, not from its own front',
+        was: "screenshot_3d { view: 'street' }",
+        // A quarter turn at (15, 0, 15): its (x, z) lands at (15 + z, 15 - x), x 15 to 23, z 3 to 15.
+        scene: () => house({ polygon: { type: 'polygon', points: LOT }, frontEdge: 1 }, { at: [15, 0, 15], yaw: Math.PI / 2 }),
+        input: { from: 'street' },
+        expect: { eyeToward: [1, 0], frames: { min: [15, 0, 3], max: [23, PEAK, 15] } },
+    },
+    {
+        name: "a roof of Architect's roof planes is framed to its roof level's top",
+        was: "screenshot_3d {} over a roof drawn with create_roof_plane (it framed every level's top)",
+        scene: () => house({ polygon: { type: 'polygon', points: LOT }, frontEdge: 1 }, { roof: 'planes' }),
+        input: { from: 'street' },
+        // The roof level's 3 m over the two storeys' 5.4 m.
+        expect: { eyeToward: [1, 0], frames: { min: [9, 0, 11], max: [21, 8.4, 19] } },
+    },
+    {
+        name: 'an empty site beside the one the house stands on takes nothing from the view',
+        was: "screenshot_3d { view: 'street' }",
+        scene: () => ({
+            ...house({ polygon: { type: 'polygon', points: LOT }, frontEdge: 1 }),
+            site_empty: SiteNode.parse({ id: 'site_empty', children: [] }),
+        }),
+        input: { from: 'street' },
+        expect: { eyeToward: [1, 0], frames: WHOLE_HOUSE },
+    },
+    {
+        name: 'houses on two lots, each facing its own street, need the house as target',
+        was: "screenshot_3d { view: 'street' } (it took the lowest storey it found)",
+        scene: twoLots,
+        input: { from: 'street' },
+        expect: { refusal: 'which_building' },
+    },
+    {
+        name: 'the house on the east lot, as target, is seen from its own street',
+        was: "screenshot_3d { view: 'street' }",
+        scene: twoLots,
+        input: { from: 'street', target: 'building_house_east' },
+        expect: { eyeToward: [1, 0], frames: { min: [49, 0, 11], max: [61, PEAK, 19] } },
+    },
+    {
+        name: 'the house on the west lot, as target, is seen from its own street (north)',
+        was: "screenshot_3d { view: 'street' }",
+        scene: twoLots,
+        input: { from: 'street', target: 'building_house' },
+        expect: { eyeToward: [0, -1], frames: WHOLE_HOUSE },
+    },
+    {
+        name: "a lot that records no street is seen from the house's own front (-z), as Architect's tools read it",
+        was: "screenshot_3d { view: 'street' } on a lot with no street (Pro's placeholder lot)",
+        scene: () => house({ polygon: { type: 'polygon', points: LOT } }),
+        input: { from: 'street' },
+        expect: { eyeToward: [0, -1], frames: WHOLE_HOUSE },
+    },
+    {
+        name: "on a lot with no street, street-left is the left front corner of the house's own front: the north-east",
+        was: 'screenshot_3d {} on a lot with no street',
+        scene: () => house({ polygon: { type: 'polygon', points: LOT } }),
+        input: { from: 'street-left' },
+        expect: { eyeToward: [H, -H], frames: WHOLE_HOUSE },
+    },
+    {
+        name: 'a house turned a quarter on a lot with no street is seen from its own front, the west',
+        was: "screenshot_3d { view: 'street' } on a lot with no street",
+        scene: () => house({ polygon: { type: 'polygon', points: LOT } }, { at: [15, 0, 15], yaw: Math.PI / 2 }),
+        input: { from: 'street' },
+        expect: { eyeToward: [-1, 0], frames: { min: [15, 0, 3], max: [23, PEAK, 15] } },
+    },
+    {
+        name: "a scene with no site is seen from the house's own front",
+        was: 'screenshot_3d {} in a scene with no site',
+        scene: () => house(null),
+        input: { from: 'street-left' },
+        expect: { eyeToward: [H, -H], frames: WHOLE_HOUSE },
+    },
+    {
+        name: "inside a floor of the house on the east lot, the street is that house's own",
+        was: "screenshot_3d { view: 'street' }, looking into a floor",
+        scene: twoLots,
+        input: { interior: { levelId: 'level_0_east' }, from: 'street' },
+        expect: { eyeToward: [1, 0] },
+    },
+    {
+        name: 'the back-left corner in daylight',
+        was: "screenshot_3d { view: 'back-left', lighting: 'day' }, as a stored Pro thread calls it",
+        scene: eastFront,
+        input: { from: 'back-left', lighting: 'day' },
+        expect: { eyeToward: [-H, H], frames: WHOLE_HOUSE, lighting: 'day' },
+    },
+    ...['day', 'overcast', 'sunset', 'dusk', 'night'].map((lighting) => ({
+        name: `in the ${lighting} light`,
+        was: `screenshot_3d { lighting: '${lighting}' }`,
+        scene: eastFront,
+        input: { from: 'street', lighting },
+        expect: { eyeToward: [1, 0], lighting },
+    })),
+    {
+        name: "in the scene's own light",
+        was: "screenshot_3d { lighting: 'current' }",
+        scene: eastFront,
+        input: { from: 'street', lighting: 'current' },
+        expect: { eyeToward: [1, 0] },
+    },
+    {
+        name: 'a thumbnail, 320 px on its longest side',
+        was: 'screenshot_3d { maxPx: 320 } (a saved design’s thumbnail)',
+        scene: eastFront,
+        input: { from: 'street-left', maxPx: 320 },
+        expect: { size: { w: 320, h: 200 }, frames: WHOLE_HOUSE },
+    },
+    {
+        name: 'a picture 1600 px across',
+        was: 'screenshot_3d { maxPx: 1600 } (its default)',
+        scene: eastFront,
+        input: { from: 'street-left', maxPx: 1600 },
+        expect: { size: { w: 1600, h: 1000 } },
+    },
+    {
+        name: 'the smallest picture, 64 px on its longest side',
+        was: 'screenshot_3d { maxPx: 64 }',
+        scene: eastFront,
+        input: { from: 'street-left', maxPx: 64 },
+        expect: { size: { w: 64, h: 40 } },
+    },
+    {
+        name: 'the largest picture, 1920 px on its longest side',
+        was: 'screenshot_3d { maxPx: 1920 }',
+        scene: eastFront,
+        input: { from: 'street-left', maxPx: 1920 },
+        expect: { size: { w: 1920, h: 1200 } },
+    },
+    {
+        name: 'a picture past 1920 px is refused: a vision model would scale it down',
+        was: 'screenshot_3d { maxPx: 2048 }',
+        scene: eastFront,
+        input: { from: 'street-left', maxPx: 2048 },
+        // The contract's schema refuses it before anything runs; the chat's model API does the same.
+        surfaces: ['core'],
+        expect: { refusal: 'invalid_input' },
+    },
+    {
+        name: "the person's own view, at their canvas' aspect",
+        was: "screenshot_3d { view: 'current' }",
+        scene: eastFront,
+        input: { camera: 'current' },
+        currentCamera: PERSON,
+        surfaces: ['core', 'chat'],
+        expect: {
+            pose: { projection: 'perspective', position: [-6, 9, 30], target: [15, 2, 15], fov: 50 },
+            size: { w: 1920, h: 1080 },
+        },
+    },
+    {
+        name: "the person's own view through an orthographic camera stays orthographic",
+        was: "screenshot_3d { view: 'current' }",
+        scene: eastFront,
+        input: { camera: 'current', maxPx: 960 },
+        currentCamera: { ...PERSON, projection: 'orthographic' },
+        surfaces: ['core', 'chat'],
+        expect: {
+            pose: {
+                projection: 'orthographic',
+                position: [-6, 9, 30],
+                target: [15, 2, 15],
+                viewWidth: 24,
+            },
+            size: { w: 960, h: 540 },
+        },
+    },
+    {
+        name: "the person's view on a tall, narrow canvas is 1920 px on its longest side",
+        was: "screenshot_3d { view: 'current' } in a portrait window",
+        scene: eastFront,
+        input: { camera: 'current' },
+        currentCamera: { ...PERSON, aspect: 0.6 },
+        surfaces: ['core', 'chat'],
+        expect: { size: { w: 1152, h: 1920 } },
+    },
+    {
+        name: "the MCP has no view of the person's to look through",
+        was: "screenshot_3d { view: 'current' }",
+        scene: eastFront,
+        input: { camera: 'current' },
+        surfaces: ['mcp'],
+        expect: { refusal: 'no_current_camera' },
+    },
+    {
+        name: "the person's view and a side of the agent's own are refused together",
+        was: "screenshot_3d { view: 'current' }",
+        scene: eastFront,
+        input: { camera: 'current', from: 'street' },
+        currentCamera: PERSON,
+        expect: { refusal: 'camera_and_viewpoint' },
+    },
+];
+const DEG = 180 / Math.PI;
+/** What a planned view gets wrong against its case: the problems, if any. */
+export function viewSceneCaseProblems(c, plan) {
+    if ('refusal' in c.expect)
+        return [`planned a view, expected the refusal ${c.expect.refusal}`];
+    const { eyeToward, eyeAbove, frames, pose, size } = c.expect;
+    const problems = [];
+    const [ex, ey, ez] = plan.pose.position;
+    const [tx, ty, tz] = plan.pose.target;
+    const flat = Math.hypot(ex - tx, ez - tz);
+    if (eyeToward) {
+        const off = Math.acos(Math.min(1, ((ex - tx) * eyeToward[0] + (ez - tz) * eyeToward[1]) / (flat || 1)));
+        if (off * DEG > 2)
+            problems.push(`the eye stands ${Math.round(off * DEG)}° off its side`);
+    }
+    if (eyeAbove !== undefined && Math.atan2(ey - ty, flat) * DEG < eyeAbove)
+        problems.push(`the eye is ${Math.round(Math.atan2(ey - ty, flat) * DEG)}° up, not ${eyeAbove}`);
+    if (frames && !framesBox(plan.pose, plan.size.w / plan.size.h, frames))
+        problems.push('part of what it should frame is outside the picture');
+    if (pose && JSON.stringify(plan.pose) !== JSON.stringify(pose))
+        problems.push(`the pose is ${JSON.stringify(plan.pose)}`);
+    if (size && (plan.size.w !== size.w || plan.size.h !== size.h))
+        problems.push(`the picture is ${plan.size.w} × ${plan.size.h}`);
+    if (plan.lighting !== c.expect.lighting)
+        problems.push(`the light is ${plan.lighting ?? 'its own'}`);
+    return problems;
+}
+/** Every corner of the box in front of a perspective eye, inside its frame at `aspect`. */
+function framesBox(pose, aspect, box) {
+    if (pose.projection !== 'perspective')
+        return false;
+    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];
+    const unit = (a) => a.map((v) => v / (Math.hypot(...a) || 1));
+    const cross = (a, b) => [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ];
+    const forward = unit(sub(pose.target, pose.position));
+    const right = unit(cross(forward, [0, 1, 0]));
+    const up = cross(right, forward);
+    const half = Math.tan((pose.fov * Math.PI) / 360);
+    for (const x of [box.min[0], box.max[0]])
+        for (const y of [box.min[1], box.max[1]])
+            for (const z of [box.min[2], box.max[2]]) {
+                const v = sub([x, y, z], pose.position);
+                const depth = dot(v, forward);
+                if (depth <= 0)
+                    return false;
+                if (Math.abs(dot(v, right) / depth) > half * aspect + 1e-9)
+                    return false;
+                if (Math.abs(dot(v, up) / depth) > half + 1e-9)
+                    return false;
+            }
+    return true;
+}

package/dist/agent-operations/achieved.d.ts

@@ -0,0 +1,21 @@
+import type { SceneChanges, SceneNodes } from './types.js';
+export type Achieved = {
+    created: Record<string, number>;
+    updated: number;
+    deleted: Record<string, number>;
+    /** The call left the scene as it was: what it reports was not built. */
+    unchanged?: true;
+};
+/**
+ * What a mutating call really changed, read from the scene before and after its changes, so a
+ * result never claims what the scene does not hold (a facade was once reported "applied" on 432
+ * walls that placed no window). Cheap: one pass over the ids; a scene check per call is not (2.7 s
+ * on a scene of 4,362 nodes).
+ */
+export declare function achievedChanges(before: SceneNodes, changes: SceneChanges): Achieved;
+/**
+ * Reads changes made through a host's own write path. `before` must be a copy
+ * when the host mutates the node map it returns.
+ */
+export declare function achievedBetween(before: SceneNodes, after: SceneNodes): Achieved;
+//# sourceMappingURL=achieved.d.ts.map

package/dist/agent-operations/achieved.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"achieved.d.ts","sourceRoot":"","sources":["../../src/agent-operations/achieved.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEvD,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,wEAAwE;IACxE,SAAS,CAAC,EAAE,IAAI,CAAA;CACjB,CAAA;AAWD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,GAAG,QAAQ,CAmBnF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,QAAQ,CAU/E"}