Boundary import + layout model, metric elevation migration, content toggles, segment slope

[kfarr]

Supersedes #1733 (includes its managed-street building import work, rebuilt on the canonical boundary object). Addresses #1775 and #1774; part of the building-parity epic #1286 / #1720; lays groundwork for #1751. Up to date with main.

Boundary layout model (building → boundary)

The segment type is renamed boundary — the better term for the set it covers (buildings, waterfront, fences, parking lots). More importantly, the layout model changed:

• The travelled way is the only layout input. street-align centers the travelled way alone; street-ground and street-label span it alone. Boundary segments are positioned outside the travelled way's edges by their side property (stacking outward if multiple), whether visible or not.
• Nothing ever moves: adding, removing, hiding, or showing a boundary cannot shift the street. The sidebar toggle and the scene-graph eye are pure visibility.
• Ends-only by construction: a boundary renders at the street edge regardless of its position in the segment list (structural editing rules remain with Move a managed street segment left/right (reorder segment index) #1751).
• This anticipates the future centerline mechanism: the travelled way will anchor to centerline points; boundaries stay edge-derived.
• Load-time migrations for saved scenes: type: building → type: boundary and showBuildings → showBoundaries (string + object forms, unit-tested); json-blobs accepting legacy building too. The legacy street component's processBuildings path is untouched.

Elevation: integer level → metric elevation

Streetmix schema 33+ stores elevation in meters; we were down-converting to a lossy integer "curb level". Killed before beta exit:

• street-segment.elevation (number, meters) replaces level (int); presets updated (1 → 0.15); calculateHeight() takes meters; CURB_HEIGHT kept only as the migration constant
• convertStreetValues() normalizes pre-33 integer levels to meters; 33+ passes through
• Hard cut-over on save; legacy scenes migrate at load time (migrateSegmentLevelToElevation in createEntityFromObj, levelToElevation fallback in parseStreetObject)
• Negative elevations intentionally unsupported: schema min: 0, render clamp, legacy negative levels migrate to 0
• Sidebar shows "Elevation (m)" (localized); AI tool schemas, presets, StreetPlan path all swept

Boundary object import (#1775)

• getBoundaryFromStreetData() reads the canonical v34 boundary.left/right (variant/floors/elevation in meters) with flat-field fallback; boundary wins when both present
• Boundary elevation applies to the segment (coastmix raised edges import correctly); floors persists via a new schema prop (metadata only; height mapping is an open question)
• Unknown variants warn and skip; legacy streetmix-loader reads the boundary variant too

Toggles: showBoundaries, showGround, showStriping, showVehicles

Migrated from the legacy street prototype (skipping globalAnimated) as managed-street schema props with sidebar rows. Realtime, non-destructive, visibility-only:

• Boundaries: always imported, toggle hides/shows in place (no reflow — see layout model)
• Ground: hides the dirtbox · Striping: hides generated striping planes · Vehicles: hides vehicle/cyclist clones by mixin catalog category (pedestrians untouched)
• A subtree observer re-applies content visibility to late-generated clones while a toggle is off
• Creation functions/AI tools that already passed these flags now actually take effect

Segment slope (#1774, coastmix v34)

• getSegmentSlope() parses slope: {on, values: [start, end]} (meters); seeded v34 defaults stay flat
• below-box tilts its top face between the two edge heights; entity sits at mean height (generated content at mean elevation); round-trips through save/load
• Direction assumption: values[0] → segment start (−x) edge; confirm against a live coastmix export

Drive-by fix

wobble-geometry-box.play() used object3D.children[0].geometry — crashes entity load when clone Groups attach before the surface mesh (waterfront boundaries after main's clone changes). Now getObject3D('mesh') + object3dset retry.

Verification (headless Chromium against the dev server)

• Layout invariance: 17.4 m travelled way — sidewalk x = −7.5 and ground = 17.4 m across ALL states (boundaries on / off / one eyed-on / a boundary reparented mid-DOM); boundaries hold x = −13.7 / +10.7 throughout
• Triple legacy migration in one pass: a scene with type: building; level: 1 + showBuildings: false loads as a boundary at elevation: 0.15 with showBoundaries: false
• Boundary import (floors 2/3, 0.15 m), content toggles (striping/vehicles/ground, pedestrians untouched, late-regenerated clones stay hidden), slope tilt (+0.075/−0.075 at mean 0.225 m), metric elevation math — all exercised live

Tests

• v34 fixtures: coastal-boundary-street.streetmix.json (synthesized; keeps slope coverage) + kfarr-demo-street-v34.streetmix.json (real streetmix.net export of kfarr/3, fetched 2026-07-04 — covers the boundary object and metric elevations against production data; the live export has no sloped segments, hence keeping the synthesized one)
• 88 mocha + 368 vitest + 30 component tests passing locally; lint + prettier + i18n:check clean; CI green including test:components
• Parity harness run locally against the dev server (19 fixtures, SHOW_BUILDINGS=false): exit 0; coastal-boundary-street is the closest match of all at 2.37% pixel diff; higher outliers (marina-parking 19%, kfarr-demo-v34 16.6%) are the known parking non-parity and random clone placement noise on content-heavy streets
• Docs PR: Update managed-street docs for elevation/boundary format 3dstreet-docs#91 (JSON format + component pages; hold until this deploys)

Open questions for review

• floors → model height mapping (proposal: pick models by floor count from catalog as follow-up)
• compound-wall aliases seawall; beach/other new coastmix variants unmapped (warn-and-skip); boundary id not persisted
• Slope editing UI not included — import/round-trip only
• Existing-scene layout shift: pre-PR layout included visible building segments in centering; the new model centers the travelled way alone. Old saved scenes with visible asymmetric-width boundaries re-center on load, shifting the travelled way by (leftW−rightW)/2 relative to other layers (matters most for geo-anchored scenes). Scope confirmed narrow: main's managed streetmix import never creates buildings, so streetmix-sourced scenes are unaffected. Saved scenes with buildings exist only via the "Building Placement Demo" add-layer card (6.5 m/6 m asymmetry → 0.25 m shift), saved StreetPlan imports, or a manual type change. Judged acceptable-by-design
• One-way migration: scenes re-saved by this version (elevation/boundary) will not render correctly if opened by a pre-PR build (segments flatten to level 0, unknown segment type) — relevant to rollbacks and self-hosted older deployments
• Structural ends-only editing rules (drag-restrictions in scene graph) → Move a managed street segment left/right (reorder segment index) #1751
• Accepted behaviors from manual testing (keep as-is for now): the Boundaries toggle on a street with no boundary segments is a no-op (it does not create blank boundaries — possible future affordance); two boundaries on the same side stack outward, which is fine since >1 per side is unintended/undefined

🤖 Generated with Claude Code

https://claude.ai/code/session_014eU9iRHukcxHhvXxDFjeSs

[kfarr]

Manual test plan (pre-merge)

Setup: npm start, open http://localhost:3333 in a fresh profile (or clear local scene state).

1. Streetmix import with boundaries

• New scene → Add Layer → Streetmix import → https://streetmix.net/kfarr/3
• Street loads with a waterfront (left) and fence (right) boundary; water surface animates
• Scene graph shows Boundary • waterfront (left) first and Boundary • fence (right) last
• Select each boundary: sidebar shows "Boundary Variant" + Side; Elevation (m) = 0.15; floors persisted (2 left / 3 right in the properties panel / saved JSON)

2. Layout invariance (the core behavioral guarantee)

• Note the x-position of the leftmost sidewalk and the ground extent
• Toggle Boundaries off/on in the managed street sidebar → street and ground never shift; only boundaries hide/show
• Hide a single boundary via the scene-graph eye icon → same: no reflow
• Drag a boundary to the middle of the layer list → it still renders at the street edge (position in list is cosmetic)
• Street label (Labels toggle on) spans only the travelled way, not the boundaries

3. Content toggles

• Ground toggle hides/shows the dirt slab
• Striping toggle hides/shows lane striping only
• Vehicles toggle hides vehicles + cyclists but leaves pedestrians
• With Vehicles off, change a drive lane's width (forces clone regeneration) → new clones stay hidden
• All four toggles survive save + reload

4. Elevation editing

• Select a sidewalk → "Elevation (m)" shows 0.15; set to 0.3 → segment raises visibly
• Try entering a negative value → rejected/clamped to 0
• Undo/redo the elevation change works

5. Slope (import + round-trip only)

• Streetmix URL dialog → http://localhost:3333/test/parity/fixtures/coastal-boundary-street.streetmix.json
• Last segment renders tilted (0.15 → 0 across its width); generated content sits at mean height
• Save scene, reload → tilt is identical (slope/slopeStart/slopeEnd round-trip)

6. Legacy scene migration (back-compat)

• Load a pre-change saved scene (or fixture) containing type: building, level: 1, showBuildings: false
• It loads as boundary at elevation: 0.15 with boundaries hidden; no console errors
• Re-save → JSON now contains elevation / boundary (hard cut-over), loads again cleanly
• Layout-shift check: load an old saved managed-street scene with visible, asymmetric-width buildings (e.g. waterfront 6 m left, fence 4 m right). Old layout included visible buildings in centering; the new model centers the travelled way alone, so the street shifts by (leftW−rightW)/2 (1 m in that example) relative to other layers. Verify this is acceptable — especially in a geo-anchored scene where the street was aligned to real-world tiles
• Old scene with a level: -1 (below-grade) segment loads clamped to road level (intentional; negative unsupported)

7. Regression sweep

• StreetPlan import still works (remember share URLs expire ~30 min — generate fresh)
• Default streets from Add Layer panel look unchanged
• Create street via AI assistant / JSON paste with new-format fields works
• Legacy street + streetmix-loader scenes unaffected

Pre-merge/deploy checklist

• 88 mocha + 368 vitest + 30 component tests green locally; CI green (incl. test:components)
• lint / prettier / i18n check clean
• Parity harness run locally against dev server (SHOW_BUILDINGS=false path)
• Real kfarr/3 v34 export added as fixture (covers boundary object on production data; synthesized coastal fixture retained for slope coverage — the live kfarr/3 has no sloped segments)
• Docs PR opened: Update managed-street docs for elevation/boundary format 3dstreet-docs#91 (hold merge until this PR deploys)
• Manual test plan above executed by a human on the PR build
• Slope direction assumption (values[0] = segment −x edge) confirmed against a live coastmix export — no public coastmix instance with slope data was reachable; needs a real export from the coastmix team
• Mark PR ready for review (currently draft) + reviewer pass on the open questions (floors→height mapping, unmapped coastmix variants, boundary id not persisted)
• After deploy: merge docs PR Update managed-street docs for elevation/boundary format 3dstreet-docs#91

Deferred (tracked, not blockers): floors → model height mapping proposal, slope editing UI, structural ends-only drag rules (#1751).