feat: scene north direction (northDirectionDeg) + compass heading

[dkbbdev]

Closes #362

Approach

• SiteNode.northDirectionDeg: finite degree heading, clockwise from world −Z toward +X; default 0 preserves today's convention (as documented in two-bedroom.ts, +Z points south). Field documented on the schema.
• Legacy sites get the default; non-finite legacy values normalize to 0; JSON + scene-store round trips preserve custom headings.
• Compass: reuses the existing viewport compass mounted by ViewerStage (bottom-left, z-30) — now reflects the site heading, camera rotation, and align-to-north action.

Files

• packages/core/src/schema/nodes/site.ts (+ test), schema/index.ts, store/use-scene.ts (+ north-direction test), host-children.test.ts
• packages/editor/src/components/viewer/floorplan-preview.tsx, floorplan-preview-navigation.ts (+ test)

Verification

• core bun test: 2,848 passed / 127 files
• editor bun test: 1,037 passed / 139 files
• tsgo --noEmit clean in both packages; biome clean

Notes / follow-ups

• No authoring UI yet for the heading (schema/store only) — happy to add a site-orientation control if the convention is accepted.
• Can follow up with MCP/template docs mentioning the field.

---

Note

Medium Risk
Introduces a persisted site field and changes floorplan compass/north-up behavior, but defaults and load migration preserve legacy scenes.

Overview
Adds northDirectionDeg on site nodes so each scene can store where north points (degrees clockwise from world −Z toward +X). Default 0 keeps the existing convention (+Z = south); values are validated, canonicalized to [0, 360), and legacy loads get the default or 0 for non-finite values via migrateNodes.

The floorplan compass and align-to-north paths now offset needle rotation and north-up alignment by the site heading (compassRotationFromFloorplanRotation, floorplanRotationForNorthUp) in the editor floorplan panel and preview, without rotating plan geometry. DEFAULT_NORTH_DIRECTION_DEG is exported from core for consumers.

Tests cover schema parsing, scene load persistence, host-children baseline expectations, and navigation math (including negative/multi-turn headings).

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

[pascal]

I hit an error while handling your request (Model unavailable on AI Gateway free tier: Free tier users do not have access to this model. Upgrade to paid credits at https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%3Fmodal%3Dtop-up for unrestricted…).

Please try again, rephrase, or reach out if it keeps failing.

Error id: 503f8013-bdd1-49fe-811f-84f275d94ab3

[dkbbdev]

Post-review fixes in 735c12c:

• 2D parity: FloorplanPanel (edit mode) now applies compassRotationFromFloorplanRotation / floorplanRotationForNorthUp — the 2D compass needle and align-to-north now follow the site heading instead of world 0°, matching FloorplanPreview
• Canonicalization: SiteNode.northDirectionDeg is normalized to [0, 360) in the schema (Zod transform, -0 guarded)
• Tests: added negative-heading and multi-turn wraparound boundary cases

Verified: targeted 19 tests pass, tsgo clean in core+editor, full suite 7,993 — only the pre-existing unrelated safeFetch mcp failure remains.