Project North direction: data-model property + viewport compass

[marcelgruber]

Problem or motivation

Pascal has no first-class North in its data model. The word "north"
appears only as informal English in template comments, and the two
templates that use it don't even agree:

• packages/mcp/src/templates/two-bedroom.ts:14
  — "z running north/south (positive z points south)"
• packages/mcp/src/templates/garden-house.ts:14
  — "back garden zone immediately to the north of the house"
  (without specifying which axis)

There's no northDirection, northDeg, compass, or any other
orientation primitive anywhere in the schema. So:

• Templates that try to use north pick their own convention silently.
• Authors generating geometry from a real-world source (a land survey
  with bearings from North, a north-up site plan, a 2-D plotting
  library) have nothing to anchor their input against. The
  external-coordinate gotcha documented in Docs: document the plan↔world coordinate convention for MCP/API authors #337 / docs(mcp): document plan↔world coordinate convention #356 is partly
  because there's no canonical North to map page-up coordinates
  onto — the README has to tell authors to verify with a guide image.
• Users have no on-screen indication of which direction is north when
  inspecting a scene. The 2-D plan panel applies a 90° rotation and
  the 3-D top-down snap defaults to a ~45° offset (also documented in
  Docs: document the plan↔world coordinate convention for MCP/API authors #337), so "north on the page" doesn't map intuitively to anything.

This is what surfaced #337 in the first place — building geometry
programmatically from a surveyor's report (every wall a bearing from
True North) means chasing the rotation manually, because the editor
has nothing to anchor it against.

Proposed solution

A tiered approach so the maintainer can pick a starting point. Tier 1
on its own would close the gap meaningfully; Tier 2 makes it complete.

Tier 1 — minimum viable (a property, a widget, a default)

• Add northDirection: number (radians, CCW from world +X to match
  Pascal's existing rotation conventions) to Site or Building.
  Default to whatever the current templates implicitly assume so
  existing scenes don't move.
• Render a small north-arrow widget in viewport corners (or near the
  existing camera-mode button in
  apps/editor/components/viewer-toolbar.tsx),
  rotating with the camera so it always points to true north on screen.
• Clean up the conflicting template comments while in the area.

Tier 2 — high-leverage follow-ups

• "Rotate to north-up" view command — orbits the 3-D top-down camera so
  north faces screen-up, and adjusts FLOORPLAN_VIEW_ROTATION_DEG /
  the floor-plan SVG group rotation so 2-D plan view does the same.
• Surface northDirection over MCP (settable via apply_patch /
  readable from get_scene). Agents authoring from a survey can drop
  the value in once and have everything else line up — closes the loop
  the README PR opens.

Tier 3 — explicitly out of scope for v1, mentioned so it doesn't
get baked into the wrong place

• Revit-style True North vs Project North separation (Project
  North = aligned to a building facade for drawing clarity, True North
  = the cardinal). Worth considering if Pascal ever wants sun-studies
  • multi-building campuses, but not necessary for the immediate gap.
• Sun / shadow studies tied to northDirection + lat/long + date/time.

Alternatives considered

• Document the gap only (what PR docs(mcp): document plan↔world coordinate convention #356 does). Helpful but doesn't
  solve the underlying issue: even after reading the docs an author
  still has to verify orientation against a guide image every time.
• Per-template / per-author conventions (status quo). Already
  visibly broken — the two-bedroom template says +Z is south and the
  garden-house template says the garden is to the north without
  saying which axis.
• Skip the data-model change; add only a UI compass that points to
  world +Z (or +X) regardless. Tempting but doesn't help anyone
  authoring from a real-world bearings source; it just relabels the
  existing world axes.

Additional context

Every comparable tool has this:

Tool	What they do
Revit	Distinct True North vs Project North; sun/shadow studies, energy modelling key off it
ArchiCAD	Project north in Project Preferences
SketchUp	Solar North toolbar with a settable north angle
Vectorworks	Plan rotation to true north as a project setting
Civil 3D / AutoCAD	North angle on the drawing; standard in civil/site work
Floorplanner / Roomstyler / similar SaaS	Rotatable north-arrow widget
QGIS / ArcGIS / any GIS layout	North arrow as a first-class layout primitive

So Pascal not exposing this is the unusual position rather than the
ask being unusual.

Open questions

1. Site or Building? Site is the outermost container and
   multiple buildings could share a site's north. Building already
   has a rotation: [x,y,z], so Building.rotation[1] is roughly "this
   building's facade angle relative to site axes". Storing north on
   Site keeps these orthogonal; storing on Building lets each building
   have its own. My instinct says Site, but you may have a reason to
   put it on Building.
2. Default value? Defaulting to "true north = +Z" matches the
   two-bedroom.ts template's stated convention ("+Z = south" inverted)
   and is the most common assumption in north-up site plans. Worth
   defaulting explicitly rather than leaving it implicit as today.
3. Widget UI? A separate corner widget is the obvious choice, but
   could also be a small N marker on the existing camera-mode button,
   or a compass overlay near the orthographic-camera toggle in
   viewer-toolbar.tsx:438.
   Likely a design call.

Happy to take a stab at Tier 1 if there's interest; want to confirm
the schema placement and widget direction first.

Related: #337, #356.