@pascal-app/mcp 0.2.0 → 0.3.1

package/README.md

@@ -227,6 +227,76 @@ console.log(scene)
 See [`examples/embed-in-agent.ts`](./examples/embed-in-agent.ts) for a
 compilable version.
 
+## Coordinate conventions
+
+Pascal is a **right-handed** scene where **X and Z form the ground plane and Y
+is up**. Lengths are in **metres**; rotations are **radians**, stored as Euler
+`[x, y, z]` tuples.
+
+**Plan → world.** Every 2-D point you pass is a level/building-local
+ground-plane coordinate
+`[x, z]` — this includes `wall.start` / `wall.end` and the `polygon` / `holes`
+arrays of `slab`, `zone`, and `ceiling`. With the default identity building
+transform, it appears in world space as:
+
+```
+[x, z]  →  (x, y, z)      // the 2nd component is world Z (depth), not "up"
+```
+
+There is no sign flip in the stored convention: tooling consumes the second
+component as world Z directly. The vertical `y` starts from the owning level's
+stacked height as computed by the level system from accumulated level heights,
+plus the element's own height; slabs additionally carry an absolute
+`elevation`.
+
+**Heads-up when you compute coordinates outside the editor.** Pascal's
+viewports apply their own rotations on top of the world axes: the 2-D plan
+panel wraps its content in a 90° rotation (`FLOORPLAN_VIEW_ROTATION_DEG`), and
+the 3-D "top-down" snap preserves the camera's current azimuth, so when invoked
+from the iso default position, world and screen axes are offset by ~45° until
+you orbit to an axis-aligned view. So a layout authored as if
+*"Y = north, viewed top-down"* — common in land surveys, north-up site plans,
+and 2-D plotting libraries — will arrive **rotated** relative to its source
+when viewed in Pascal (and possibly further reflected, depending on which
+viewport and camera state you're in). The editor's own 2-D and 3-D tools are
+internally consistent with their stored coordinates, so this only affects
+geometry authored programmatically. To verify orientation before trusting
+externally-computed coordinates, place a scaled guide image at known anchor
+points and check alignment; apply whatever rotation (or reflection) your
+authoring side needs to match.
+
+A worked demonstration of all of this — axis-aligned baseline, the rotated
+30° example below, and a paired "page-intent vs world-result" L for the
+external-coordinate gotcha — lives in
+[`examples/coordinate-conventions-demo.md`](./examples/coordinate-conventions-demo.md)
+and [`examples/coordinate-conventions-demo.json`](./examples/coordinate-conventions-demo.json).
+Load the JSON with
+`pascal-mcp --stdio --scene examples/coordinate-conventions-demo.json`.
+
+**Example — a 6 × 4 m slab rotated 30° about its first corner** (coordinates
+rounded to 3 dp; sides ≈ 6 m / 4 m; not axis-aligned, so the mapping is
+actually exercised):
+
+```json
+{
+  "op": "create",
+  "parentId": "<levelId>",
+  "node": {
+    "type": "slab",
+    "elevation": 0.0,
+    "polygon": [[0, 0], [5.196, 3.0], [3.196, 6.464], [-2.0, 3.464]]
+  }
+}
+```
+
+This lands flat on the ground (Y = 0), about 6 m along a heading 30° off the +X
+axis and 4 m along its perpendicular — i.e. occupying world (x, z) directly.
+
+One separate gotcha: wall-attached coordinates are wall-local, not plan
+coordinates. Stored door/window `position[0]`, and `place_item` `position[0]`
+when the target is a wall, are metres along the wall; wall-attached rotations
+are wall-local too.
+
 ## Tools
 
 All tools validate their inputs and outputs with Zod. Mutation tools are

package/dist/lib/rehydrate-site-children.d.ts

@@ -1,12 +1,10 @@
 import type { SceneGraph } from '@pascal-app/core/clone-scene-graph';
 /**
- * `cloneSceneGraph` normalises `SiteNode.children` to an array of node IDs,
- * but core's `SiteNode` schema expects an array of embedded `BuildingNode` /
- * `ItemNode` objects (see `packages/mcp/CROSS_CUTTING.md` §2). To keep the
- * cloned graph validating against `AnyNode`, re-embed the site children from
- * the flat dict.
- *
- * Pure: returns a new graph without mutating the input.
+ * Previously re-embedded `SiteNode.children` from flat IDs back to full node
+ * objects to match the old schema. Since `SiteNode.children` is now
+ * `string[]` (upstream change), `cloneSceneGraph` / `forkSceneGraph` already
+ * produce the correct form — this function is a no-op kept for call-site
+ * compatibility.
  */
 export declare function rehydrateSiteChildren(graph: SceneGraph): SceneGraph;
 //# sourceMappingURL=rehydrate-site-children.d.ts.map

package/dist/lib/rehydrate-site-children.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rehydrate-site-children.d.ts","sourceRoot":"","sources":["../../src/lib/rehydrate-site-children.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAGpE;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CA2BnE"}
+{"version":3,"file":"rehydrate-site-children.d.ts","sourceRoot":"","sources":["../../src/lib/rehydrate-site-children.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAEpE;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAEnE"}

package/dist/lib/rehydrate-site-children.js

@@ -1,40 +1,10 @@
 /**
- * `cloneSceneGraph` normalises `SiteNode.children` to an array of node IDs,
- * but core's `SiteNode` schema expects an array of embedded `BuildingNode` /
- * `ItemNode` objects (see `packages/mcp/CROSS_CUTTING.md` §2). To keep the
- * cloned graph validating against `AnyNode`, re-embed the site children from
- * the flat dict.
- *
- * Pure: returns a new graph without mutating the input.
+ * Previously re-embedded `SiteNode.children` from flat IDs back to full node
+ * objects to match the old schema. Since `SiteNode.children` is now
+ * `string[]` (upstream change), `cloneSceneGraph` / `forkSceneGraph` already
+ * produce the correct form — this function is a no-op kept for call-site
+ * compatibility.
  */
 export function rehydrateSiteChildren(graph) {
-    const out = {
-        nodes: { ...graph.nodes },
-        rootNodeIds: [...graph.rootNodeIds],
-        ...(graph.collections ? { collections: graph.collections } : {}),
-    };
-    for (const [id, node] of Object.entries(out.nodes)) {
-        if (node.type !== 'site')
-            continue;
-        const childrenField = node.children;
-        if (!Array.isArray(childrenField))
-            continue;
-        const rehydrated = [];
-        for (const child of childrenField) {
-            if (typeof child === 'string') {
-                const target = out.nodes[child];
-                if (target && (target.type === 'building' || target.type === 'item')) {
-                    rehydrated.push(target);
-                }
-            }
-            else if (child && typeof child === 'object' && 'id' in child) {
-                rehydrated.push(child);
-            }
-        }
-        out.nodes[id] = {
-            ...node,
-            children: rehydrated,
-        };
-    }
-    return out;
+    return graph;
 }

package/dist/templates/empty-studio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"empty-studio.d.ts","sourceRoot":"","sources":["../../src/templates/empty-studio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAgQpE,eAAO,MAAM,QAAQ,EAAE,UAA4B,CAAA;AAEnD,eAAO,MAAM,QAAQ;;;;CAKX,CAAA"}
+{"version":3,"file":"empty-studio.d.ts","sourceRoot":"","sources":["../../src/templates/empty-studio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAsPpE,eAAO,MAAM,QAAQ,EAAE,UAA4B,CAAA;AAEnD,eAAO,MAAM,QAAQ;;;;CAKX,CAAA"}

package/dist/templates/empty-studio.js

@@ -210,13 +210,6 @@ function buildTemplate() {
     for (const node of [n.site, n.building, n.level, ...n.walls, n.zone, n.door, n.window]) {
         nodes[node.id] = node;
     }
-    // SiteNode.children is a discriminatedUnion of BuildingNode/ItemNode objects
-    // (not string ids) — so the site must embed the full building node. The
-    // rest of the tree uses string ids per the BaseNode/LevelNode/WallNode
-    // schemas. We mutate the flat-dict copy of the site here so the nested
-    // representation round-trips through AnyNode.safeParse.
-    const siteInDict = nodes['site_empty'];
-    siteInDict.children = [nodes['building_empty']];
     return {
         nodes,
         rootNodeIds: ['site_empty'],

package/dist/templates/garden-house.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"garden-house.d.ts","sourceRoot":"","sources":["../../src/templates/garden-house.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAmRpE,eAAO,MAAM,QAAQ,EAAE,UAA4B,CAAA;AAEnD,eAAO,MAAM,QAAQ;;;;CAKX,CAAA"}
+{"version":3,"file":"garden-house.d.ts","sourceRoot":"","sources":["../../src/templates/garden-house.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AA+QpE,eAAO,MAAM,QAAQ,EAAE,UAA4B,CAAA;AAEnD,eAAO,MAAM,QAAQ;;;;CAKX,CAAA"}

package/dist/templates/garden-house.js

@@ -228,7 +228,6 @@ function buildTemplate() {
             'fence_w',
         ],
     };
-    nodes.site_garden.children = [nodes.building_garden];
     return {
         nodes: nodes,
         rootNodeIds: ['site_garden'],

package/dist/templates/two-bedroom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"two-bedroom.d.ts","sourceRoot":"","sources":["../../src/templates/two-bedroom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AA+SpE,eAAO,MAAM,QAAQ,EAAE,UAA4B,CAAA;AAEnD,eAAO,MAAM,QAAQ;;;;CAKX,CAAA"}
+{"version":3,"file":"two-bedroom.d.ts","sourceRoot":"","sources":["../../src/templates/two-bedroom.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AA2SpE,eAAO,MAAM,QAAQ,EAAE,UAA4B,CAAA;AAEnD,eAAO,MAAM,QAAQ;;;;CAKX,CAAA"}

package/dist/templates/two-bedroom.js

@@ -256,7 +256,6 @@ function buildTemplate() {
             'zone_bed2',
         ],
     };
-    nodes.site_2br.children = [nodes.building_2br];
     return {
         nodes: nodes,
         rootNodeIds: ['site_2br'],

package/dist/tools/construction-tools.d.ts

@@ -41,7 +41,7 @@ export declare const createRoofInput: {
         dutch: "dutch";
         mansard: "mansard";
     }>>;
-    roofHeight: z.ZodDefault<z.ZodNumber>;
+    pitch: z.ZodDefault<z.ZodNumber>;
     wallHeight: z.ZodDefault<z.ZodNumber>;
     wallThickness: z.ZodDefault<z.ZodNumber>;
     overhang: z.ZodDefault<z.ZodNumber>;

package/dist/tools/construction-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"construction-tools.d.ts","sourceRoot":"","sources":["../../src/tools/construction-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAYxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAOpD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAajC,CAAA;AAED,eAAO,MAAM,sBAAsB;;;;;;CAMlC,CAAA;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;CAiB3B,CAAA;AAED,eAAO,MAAM,gBAAgB;;;;;;CAM5B,CAAA;AAED,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;CAqBzC,CAAA;AAED,eAAO,MAAM,8BAA8B;;;;;;CAM1C,CAAA;AA4GD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CA8S1F"}
+{"version":3,"file":"construction-tools.d.ts","sourceRoot":"","sources":["../../src/tools/construction-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAaxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAOpD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAajC,CAAA;AAED,eAAO,MAAM,sBAAsB;;;;;;CAMlC,CAAA;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;CAiB3B,CAAA;AAED,eAAO,MAAM,gBAAgB;;;;;;CAM5B,CAAA;AAED,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;CAqBzC,CAAA;AAED,eAAO,MAAM,8BAA8B;;;;;;CAM1C,CAAA;AA4GD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAiT1F"}

package/dist/tools/construction-tools.js

@@ -1,4 +1,4 @@
-import { CeilingNode, LevelNode, RoofNode, RoofSegmentNode, SlabNode, StairNode, StairSegmentNode, WallNode, } from '@pascal-app/core/schema';
+import { CeilingNode, getActiveRoofHeight, LevelNode, RoofNode, RoofSegmentNode, SlabNode, StairNode, StairSegmentNode, WallNode, } from '@pascal-app/core/schema';
 import { z } from 'zod';
 import { publishLiveSceneSnapshot } from './live-sync';
 import { NodeIdSchema, Vec2Schema, Vec3Schema } from './schemas';
@@ -36,7 +36,7 @@ export const createRoofInput = {
     width: z.number().positive(),
     depth: z.number().positive(),
     roofType: z.enum(ROOF_TYPES).default('hip'),
-    roofHeight: z.number().positive().default(1.8),
+    pitch: z.number().min(0).max(85).default(35),
     wallHeight: z.number().min(0).default(0.35),
     wallThickness: z.number().positive().default(0.16),
     overhang: z.number().min(0).default(0.45),
@@ -222,7 +222,10 @@ export function registerConstructionTools(server, bridge) {
         description: 'Create a roof container with one roof segment. By default creates a dedicated roof level above the reference level so exploded/solo level views can isolate the roof.',
         inputSchema: createRoofInput,
         outputSchema: createRoofOutput,
-    }, async ({ levelId, roofLevelId, useDedicatedRoofLevel, roofLevelLabel, roofLevelElevation, roofLevelHeight, center, width, depth, roofType, roofHeight, wallHeight, wallThickness, overhang, materialPreset, name, }) => {
+    }, async ({ levelId, roofLevelId, useDedicatedRoofLevel, roofLevelLabel, roofLevelElevation, roofLevelHeight, center, width, depth, roofType, pitch, wallHeight, wallThickness, overhang, materialPreset, name, }) => {
+        // Peak height is derived from pitch + footprint + type; we still
+        // need it to size the auto-generated roof level container below.
+        const peakHeight = getActiveRoofHeight({ roofType, pitch, width, depth });
         const referenceLevel = assertNode(bridge, levelId, 'level');
         const patches = [];
         let targetRoofLevelId = levelId;
@@ -244,7 +247,7 @@ export function registerConstructionTools(server, bridge) {
                     role: 'roof',
                     label: roofLevelLabel,
                     referenceLevelId: levelId,
-                    height: roofLevelHeight ?? Math.max(wallHeight + roofHeight, 0.2),
+                    height: roofLevelHeight ?? Math.max(wallHeight + peakHeight, 0.2),
                 },
             });
             targetRoofLevelId = roofLevel.id;
@@ -256,7 +259,7 @@ export function registerConstructionTools(server, bridge) {
             width,
             depth,
             wallHeight,
-            roofHeight,
+            pitch,
             wallThickness,
             overhang,
             ...(materialPreset ? { materialPreset } : {}),

package/dist/tools/find-nodes.d.ts

@@ -5,10 +5,10 @@ export declare const findNodesInput: {
     type: z.ZodOptional<z.ZodEnum<{
         site: "site";
         building: "building";
-        item: "item";
         level: "level";
         wall: "wall";
         fence: "fence";
+        item: "item";
         zone: "zone";
         slab: "slab";
         stair: "stair";

package/dist/tools/photo-to-scene/photo-to-scene.js

@@ -164,7 +164,7 @@ function buildSceneGraphFromVision(vision, defaultWallThickness, defaultWallHeig
     // Build the skeleton: site → building → level.
     const building = BuildingNode.parse({});
     const level = LevelNode.parse({ level: 0 });
-    const site = SiteNode.parse({ children: [building] });
+    const site = SiteNode.parse({ children: [building.id] });
     // Link parent ids so downstream traversal works.
     const siteId = site.id;
     const buildingId = building.id;

package/dist/tools/variants/generate-variants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-variants.d.ts","sourceRoot":"","sources":["../../../src/tools/variants/generate-variants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAcvD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;CAYjC,CAAA;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;CAWlC,CAAA;AAmDD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CA4FzF"}
+{"version":3,"file":"generate-variants.d.ts","sourceRoot":"","sources":["../../../src/tools/variants/generate-variants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAGxE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAcvD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;CAYjC,CAAA;AAED,eAAO,MAAM,sBAAsB;;;;;;;;;CAWlC,CAAA;AAcD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CA0FzF"}

package/dist/tools/variants/generate-variants.js

@@ -35,45 +35,6 @@ export const generateVariantsOutput = {
         graph: z.any().optional(),
     })),
 };
-/**
- * `forkSceneGraph` normalises `SiteNode.children` to string IDs, but the
- * `SiteNode` schema declares that field as an array of full `BuildingNode` /
- * `ItemNode` objects (see CROSS_CUTTING §2). To keep variants validating
- * against `AnyNode`, re-embed the site children from the flat dict.
- *
- * Pure: returns a new graph without mutating the input.
- */
-function rehydrateSiteChildren(graph) {
-    const out = {
-        nodes: { ...graph.nodes },
-        rootNodeIds: [...graph.rootNodeIds],
-        ...(graph.collections ? { collections: graph.collections } : {}),
-    };
-    for (const [id, node] of Object.entries(out.nodes)) {
-        if (node.type !== 'site')
-            continue;
-        const childrenField = node.children;
-        if (!Array.isArray(childrenField))
-            continue;
-        const rehydrated = [];
-        for (const child of childrenField) {
-            if (typeof child === 'string') {
-                const target = out.nodes[child];
-                if (target && (target.type === 'building' || target.type === 'item')) {
-                    rehydrated.push(target);
-                }
-            }
-            else if (child && typeof child === 'object' && 'id' in child) {
-                rehydrated.push(child);
-            }
-        }
-        out.nodes[id] = {
-            ...node,
-            children: rehydrated,
-        };
-    }
-    return out;
-}
 /**
  * Count how many nodes in a graph fail `AnyNode` validation. Used to keep the
  * tool from returning silently corrupt variants.
@@ -120,8 +81,6 @@ export function registerGenerateVariants(server, bridge) {
             for (const kind of mutations) {
                 forked = applyMutation(forked, rng, kind);
             }
-            // Re-embed site children so variants match the SiteNode schema.
-            forked = rehydrateSiteChildren(forked);
             const invalidCount = countInvalidNodes(forked);
             if (invalidCount > 0) {
                 throwMcpError(ErrorCode.InternalError, `variant_invalid: variant ${i} produced ${invalidCount} invalid node(s)`, { index: i });