core: the site comes first — get_site, place_building, one setback envelope

[Aymericr]

What does this PR do?

This PR places a house on its lot by moving the building node, never its walls. The model's coordinates stay as written. Every path places the house the same way: a layout program, a hand trace, a DXF import, the lot drop-in.

It is rebased on editor main (cc978fe8: Bundle 2's #1024, then #1039, #1040, #1041, #1043).

• One envelope, in core.
  • The edge roles, setbackEnvelope (with Site: lot as a block in mapped surroundings, straight front setbacks #1017's straight-front rule) and the oriented yards move from editor/.../site-plan/geometry.ts to core/src/lib/setback-envelope.ts.
  • The building footprint (levelFootprintLoops, footprintOutline, siteFrame, levelFrame) moves to core/src/lib/building-footprint.ts.
  • The site plan, the lot code and the 3D site import them from core. The 3D copy in nodes/src/site/setbacks.ts is deleted, so the 2D and 3D envelopes can't drift apart. Its ribbon tests are now line-ribbon.test.ts.
  • siteFrontEdge(site) and siteSetbackEnvelope(site) are the one recipe the site plan, the 3D site and the agents use. The front edge is the recorded front edge, else the first street edge, else the north-facing guess.
• core/src/lib/site-placement.ts (also exported as @pascal-app/core/site-placement):
  • siteBrief reads the site in the building's level frame:
    • the lot, and the buildable area with its state (lot / setbacks / none / advisory) and centre. Setbacks of zero exclude nothing.
    • the street side and the squareRotationDeg that squares the house to it
    • north, the address, APN and zoning, and the new-project placeholder flag
    • the footprint's fit, yards and overhang. Fit is judged by area; the overhang counts a piece's middle, so a house across a notch reports how far it reaches.
  • placeBuildingPose centres a footprint in the buildable area. The footprint is an outline about to be drawn, or the walls already standing. It tries the centroid first, then the most interior point.
    • It can place by the yards given (one of front/rear, one of left/right). These are solved together at the rotation asked, so a lot askew to the house still meets both, and a pose that misses them is refused.
    • A house with no walls yet is turned square to the street. A standing house keeps its rotation unless asked.
    • It never resizes the lot.
    • Its inputs don't depend on the current pose, so a repeated call changes nothing.
  • describeSiteBrief writes the same facts as a few lines. The hosted chat prints them at the top of its scene snapshot. The street line names a rotation only for a standing house that is askew.
• Two shared tools, on both surfaces:
  • get_site (read).
  • place_building (writes only the building node). Refusals: needs_footprint, other_building_on_site, no_street, yards_conflict, yards_infeasible.
  • Both get annotations, justifications, the README table, and an MCP agent-guide line: "the site comes first, before the first wall".
• Reported where the agent looks:
  • verify_scene reports footprint_outside_site, footprint_outside_setbacks and buildable_area_none. Off-centre is never an issue.
  • create_room and add_wall return site: { fit: 'outside', overhangM, sides } when the walls they raise, mitred and curved, cross the lot line. Only the lot is read to do it.
• Lot drop-in: a house the new lot leaves outside is re-centred through placeBuildingPose, keeping its facing. buildingRecentreOffset is gone.
• The site's facts move apart from the node schema: SiteAddress, SiteParcel, SiteSetbacks and migrateSiteMetadata now live in schema/nodes/site-facts.ts. This lets the site brief run inside a workflow, whose bundle refuses anything that reaches nanoid.

Reconciled with Bundle 2

Bundle 2 (#1024) and the editor PRs that landed after it touched the same registration and test files. Nothing in this PR was already there: Bundle 2 has no site placement.

• Dropped: nothing.
• Kept, both sides:
  • verify_scene: Bundle 2's description, with "a house past its lot line or in its required yards" added to its list. The three site codes sit after Bundle 2's new item and wall codes.
  • The case tables: the site cases next to Bundle 2's corner-window and merge-windows cases and Editing foundations: roofs on the building's roof level, add_fence shared, corner-window editing and review fixes #1039's ADD_FENCE_CASES.
  • The MCP registrations: get_site and place_building between Bundle 2's place_in_room and search_assets, whose catalog: true is unchanged.
  • create_room: Bundle 2's room-name import beside lotOverhang and levelFootprintLoops. add_wall: Editing foundations: roofs on the building's roof level, add_fence shared, corner-window editing and review fixes #1039's isRoofLevel beside them.
  • The site plan: Editing foundations: roofs on the building's roof level, add_fence shared, corner-window editing and review fixes #1039's roof rings over every storey (aboveGradeLevels) and its roof-level storey count, with the footprint now read from core.
• Not added: get_site and place_building are not in run_batch's list (BATCHABLE_TOOLS). That list belongs to Bundle 2, and both tools work on their own.

How to test

1. bun test packages/core/src/agent-operations. The tables in __fixtures__/site-cases.ts also run on the MCP (packages/mcp/src/tools/shared-tools.test.ts) and in the hosted chat. They cover get_site, place_building, the lot-line flags and the verify_scene issues:
   • a corner-traced house that lands centred
   • an outline on an empty building, and on a turned parcel, where it stands square to the street inside the setbacks
   • a replay that moves nothing
   • a parcel turned 20° off the origin; a yaw of 0.7 rad kept
   • yards, conflicts and infeasible yards, yards with a new rotation and its replay, and front and side yards on a lot askew to the house
   • two buildings; a fenced house; an oversize house centred without the lot being resized
   • the pole winning on a lot whose centroid is too near its edge
   • a U lot whose notch a house bridges with every corner on the lot, and how far it reaches past it
   • zero setbacks; a street edge with no front edge
   • a room drawn to the lot line, and a curved wall whose chord stays on the lot
2. Draw a lot with setbacks in the site plan. The 2D and 3D dashed envelopes match.
3. Drop in a lot by address on a project whose house falls outside the new lot. The house is re-centred and still faces the same way.

Screenshots / screen recording

Verified end to end through the hosted app in pascalorg/private-editor#910, which has the screenshots. Those runs used this code before the rebase; the hosted PR now pins this branch's head:

• An Architect Low turn on a turned parcel stood the house square to the street, centred 0.00 m off the buildable centre, inside its setbacks, in one program.
• An Architect Pro turn on a blueprint PDF read get_site and called place_building with the outline before its first wall. The house was centred on the lot when its walls first went up.

Review

The pascalorg/private-editor#910 reviews covered this code. On the editor side:

Fixed

• Squaring. A house about to rise on a turned lot now stands square to the street.
• Yards. Yards given with a new rotation are read at that rotation, and front and side yards on a lot askew to the house are solved together.
• Front edge. The setbacks and the street use one front edge, and the 3D renderer now goes through siteSetbackEnvelope like the site plan.
• Zero setbacks no longer read as "nothing buildable".
• Notch. The overhang of a house across a notch counts the piece's middle.
• create_room / add_wall measure their walls' mitred, curved bands, reading only the lot.

Rejected

• which_building for the tools' ambiguous case. The tools resolve the building through targetBuilding, the helper every building-targeted tool shares, which refuses building_required. Renaming it would give one case two names.

Checklist

• I've tested this locally with bun dev (through the hosted app's dev server, before the Bundle 2 rebase)
• My code follows the existing code style (run bun check to verify)
• I've updated relevant documentation (if applicable)
• This PR targets the main branch

Checks run on this branch (rebased on editor main cc978fe8), from the hosted worktree:

• check-types for every editor package: 9 of 9.
• bun test for core, mcp, the editor's site-plan and lot code, nodes' site code and the tool-annotation policy: 5475 pass, 0 fail. The metadata references (R3) failure is gone; fix(core): the embed page's robots metadata is Next.js page metadata #1045 fixed it on main.
• Biome on the touched files.

🤖 Generated with Claude Code

---

Note

Medium Risk
New shared placement/setback geometry affects editor, 3D site, and agent tools; incorrect math would misplace buildings or miss lot violations, though coverage is heavy on fixtures.

Overview
Adds site-first agent workflows: new read tool get_site and write tool place_building (building pose only; walls keep level coordinates), backed by shared core libraries site-placement, building-footprint, and a unified setback envelope in setback-envelope.

Consolidates lot geometry that was duplicated across editor site-plan, 3D site renderer, and nodes—editor/nodes now import siteFrontEdge, siteSetbackEnvelope, footprint loops, etc. from core; deletes nodes/src/site/setbacks.ts and buildingRecentreOffset. Site address/parcel/setback schemas move to site-facts.ts.

Surfaces lot compliance in verify_scene (footprint_outside_site, footprint_outside_setbacks, buildable_area_none) and in create_room / add_wall via lotOverhang on mitred wall bands. Lot drop-in re-centres with placeBuildingPose when the footprint is outside the new lot.

Large site-cases fixture suite exercises placement, yards, rotated parcels, and refusals; MCP README and agent guide updated.

^{Reviewed by Cursor Bugbot for commit 77931d5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 77931d5. Configure here.}

[cursor]

Lot drop-in skips multi-building recentre

Medium Severity

Lot drop-in recentres an outside house by calling placeBuildingPose without yards. That helper refuses with other_building_on_site whenever another walled building shares the site, so the update is skipped and recentred stays false. A house-plus-garage project whose house falls outside a newly imported lot is left sitting past the property line, with no error.

Additional Locations (1)

• packages/core/src/lib/site-placement.ts#L709-L714

 

^{Reviewed by Cursor Bugbot for commit 77931d5. Configure here.}