editor: add lean-to roof extensions and automatic drainage

[sudhir9297]

What does this PR do?

• Adds configurable wall-hosted lean-to roof extensions with 2D/3D placement, movement, snapping, collision validation, roof attachment, flashing, framing, supports, paint slots, and parametric controls.
• Adds automatic roof gutters, outlets, and terrain-aware downspouts, including segmented-eave coordination, attached-extension suppression, and manual adjustment support.
• Keeps derived drainage and extension assemblies synchronized within scene commits using mutation-scoped reconciliation, and defaults ridge vents off for newly created roof segments.

How to test

1. Run bun dev, open the editor, create a building, and place a lean-to extension from the Build panel against a straight exterior wall; verify the preview snaps to the wall and the extension is selected after placement.
2. Move and resize the extension in both 3D and floorplan views; switch snapping modes and dependency locks, and verify the high edge, low edge, pitch, overhangs, framing, flashing, supports, and drainage update consistently.
3. Enable automatic gutters on simple and segmented roofs; verify gutters stop or split at intersecting roof extensions, do not cross attached shed-roof edges, and generated downspouts reach the resolved slab/terrain ground.
4. Move or resize a generated outlet/downspout manually and verify the adjustment persists after another roof or extension edit.
5. Run bun run check-types, bun run check, bun run test, and bun run build.

Screenshots / screen recording

Recording to be added — this is a visual and interactive change.

Checklist

• I've tested this locally with bun dev
• 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

---

Note

High Risk
Large cross-cutting change to scene mutations (automatic child create/delete on roof/lean-to edits) and derived geometry; bugs could corrupt drainage graphs or orphan nodes, though coverage includes extensive tests.

Overview
Adds wall-hosted lean-to extensions as a first-class structure kind: placement and move on walls (3D + floorplan), managed child assembly (shed roof segment, columns, gutter/downspout), roof-edge attachment, and exposure under Build → Roof Features & extensions via paletteGroup: 'roof-features'.

Introduces automatic gutters and downspouts for roof segments (autoGutter metadata): eave runs derived from roof type/trim/sibling segments, split around intersecting geometry and lean-to host-edge exclusions, with planAutomaticDownspouts placing outlets and terrain-aware to-ground lengths. Store create/update/delete paths reconcile generated gutter/downspout nodes while preserving manual edits and IDs where possible.

Platform/editor wiring: SceneApi gains batched createMany / applyChanges / subscribeNodes; registry tools receive sceneApi + activeLevelId; floorplan affordances/move targets can mutate via sceneApi; parametric derive may receive previous; clone remaps hostRoofId / hostRoofSegmentId. Gutter/downspout handles add grid/magnetic snap; a downspout system keeps automatic lengths in sync after scene changes.

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

[cursor]

Manual mode reattaches automatically

High Severity

In resolveEffectiveLeanTo, a lean-to left in connectionMode: 'manual' is still magnetically reattached whenever a nearby roof edge is within ROOF_EDGE_REATTACH_TOLERANCE. That path calls applyLeanToRoofAttachment, which forces connectionMode back to auto and restores host roof fields. Inspector-driven manual mode therefore cannot stick under a typical eave, so host gutter suppression and attachment locks flip back on after the next sync.

Additional Locations (2)

• packages/nodes/src/lean-to-extension/roof-attachment.ts#L290-L317
• packages/nodes/src/lean-to-extension/parametrics.ts#L64-L72

 

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

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

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

[cursor]

Asymmetric overhangs skew edge exclusion

Low Severity

Attachment overlap and hostRoofEdgeRange are computed with a symmetric halfSpan that uses the larger of leftOverhang and rightOverhang on both sides, while layout offsets the roof with roofCenterX for true asymmetric overhangs. Uneven side overhangs therefore claim the wrong portion of the host eave and can suppress or keep host gutters incorrectly.

Additional Locations (1)

• packages/nodes/src/lean-to-extension/roof-attachment.ts#L170-L186

 

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