City Walk/WissenZum StadtspaziergangViewer
ImpressumDatenschutz
Leitfaden
  • So funktioniert der Stadtspaziergang
  • Woher die Daten kommen
  • Quellen nach Stadt
  • Wie der Viewer zu einer Angabe kommt
  • Der Weg der Daten
  • Bedienung
  • Glossar
Guide (English)
  • How the city walker works
  • Where the data comes from
  • Sources by city
  • How the viewer comes by what it shows
  • From download to browser
  • Using the viewer
  • Glossary
Entwicklung (English)
  • docs/ — the project knowledge base
  • Rendering — how the data becomes pixels
  • Data pipeline — the bakes, the build step and the artifact contracts
  • Architecture decision records
  • Data → feature provenance
  • Transformation catalog
  • Portability — rendering any location, with whatever data it has
  • Writing a walk
  • Routines: the twin's scheduled agents
  • Implementation plans, backlog and audit history
    • Completed plans — condensed records
    • Plan 086 [rewrite]: The rewrite series — faster on the device, fewer bytes on the wire, less to hold in the head
    • Plan 017: Any German city — the open half: a second Land, NAS input, OSM land cover, a site check
    • Plan 019: The GPU checklist — look at everything built headless, on real GPUs and phones
    • Plan 021: /wissen on Astro Starlight instead of a hand-built Next route
    • Plan 047 (spike): "Problem melden" — the crash report with somewhere to go
    • Plan 048 (spike): Share a view as a link, and commit the reference views the GPU checks need
    • Plan 050: Landmarks and what LoD2 leaves out — measured in DOM1, named by OSM and Wikidata
    • Plan 051: Stand-ins where a Land publishes less, and looks derived from each city's data
    • Plan 052: A queryable twin — identity, semantics and provenance, asked on demand
    • Plan 053: Time and live sources — the twin's fourth dimension
    • Plan 054: Scenarios — what-if studies drawn in the scene's own hand
    • Plan 069: Find what holds the load at 52 %, then take it off the tile path
    • Plan 070: Each tile holds a fraction of the raster memory it holds today
    • Plan 071: A phone renders a lean scene, a desktop a lighter one
    • Plan 074: Bake the static dressing, load the optional features on demand, one store for the HUD
    • 076 — Streaming without holes: the ground first, a plate under everything, coarse buildings and trees from the start
    • Plan 077: One rasters module — a tile's rasters loaded, shared and weighed behind one interface, their files named by the artifact table
    • 078 — One scene environment the dressings bind at birth
    • Plan 079: A page that lost its GPU comes back where it stood, through one recovery session
    • 080 — One row per inquiry kind: the twin's per-kind dispatch in one place
    • 082 — One answer turn, and a code for every way it ends
    • 084 — One session for an answer's lifetime: reading aloud, dictation and the scene's waits in one module
    • 085 — Window niches and shop windows: performance and follow-ups
    • Plan 087 [rewrite]: Plates compared on a real GPU, and one ledger every plan of the series writes its figures into
    • Plan 088 [rewrite]: The tileset is a published product, named by a lock file; the web build bakes nothing and data/ leaves git
    • Plan 089 [rewrite]: The bakes are type-checked in CI against a baseline that only shrinks
    • Plan 090 [rewrite]: A tile's dressing arrives in the layout the GPU draws from
    • Plan 091 [rewrite]: A tile's rasters arrive as the GPU reads them — plain arrays for ids, blocks for soft fields, a few files and bindings
    • Plan 092 [rewrite]: The bakes work on site-wide typed tables, cut tiles last, and no step rewrites another's file
    • Plan 093 [rewrite]: The stream's tile is smaller than the bake's — a quadtree whose levels replace the raster twins, built only if a phone still asks for it
    • Plan 094 [rewrite]: The clay's limits are counted by a test, and every pipeline the scene draws with is known at boot
    • Plan 095 [rewrite]: The viewer is a package with one entrance, a coordinate's frame is its type, and bootApp is owners
    • Plan 096 [rewrite]: Every bake heuristic that guesses has a reference set and a score a bake PR must hold
  • What the data streams carry that the walker does not use yet
Contents
Leitfaden
  • So funktioniert der Stadtspaziergang
  • Woher die Daten kommen
  • Quellen nach Stadt
  • Wie der Viewer zu einer Angabe kommt
  • Der Weg der Daten
  • Bedienung
  • Glossar
Guide (English)
  • How the city walker works
  • Where the data comes from
  • Sources by city
  • How the viewer comes by what it shows
  • From download to browser
  • Using the viewer
  • Glossary
Entwicklung (English)
  • docs/ — the project knowledge base
  • Rendering — how the data becomes pixels
  • Data pipeline — the bakes, the build step and the artifact contracts
  • Architecture decision records
  • Data → feature provenance
  • Transformation catalog
  • Portability — rendering any location, with whatever data it has
  • Writing a walk
  • Routines: the twin's scheduled agents
  • Implementation plans, backlog and audit history
    • Completed plans — condensed records
    • Plan 086 [rewrite]: The rewrite series — faster on the device, fewer bytes on the wire, less to hold in the head
    • Plan 017: Any German city — the open half: a second Land, NAS input, OSM land cover, a site check
    • Plan 019: The GPU checklist — look at everything built headless, on real GPUs and phones
    • Plan 021: /wissen on Astro Starlight instead of a hand-built Next route
    • Plan 047 (spike): "Problem melden" — the crash report with somewhere to go
    • Plan 048 (spike): Share a view as a link, and commit the reference views the GPU checks need
    • Plan 050: Landmarks and what LoD2 leaves out — measured in DOM1, named by OSM and Wikidata
    • Plan 051: Stand-ins where a Land publishes less, and looks derived from each city's data
    • Plan 052: A queryable twin — identity, semantics and provenance, asked on demand
    • Plan 053: Time and live sources — the twin's fourth dimension
    • Plan 054: Scenarios — what-if studies drawn in the scene's own hand
    • Plan 069: Find what holds the load at 52 %, then take it off the tile path
    • Plan 070: Each tile holds a fraction of the raster memory it holds today
    • Plan 071: A phone renders a lean scene, a desktop a lighter one
    • Plan 074: Bake the static dressing, load the optional features on demand, one store for the HUD
    • 076 — Streaming without holes: the ground first, a plate under everything, coarse buildings and trees from the start
    • Plan 077: One rasters module — a tile's rasters loaded, shared and weighed behind one interface, their files named by the artifact table
    • 078 — One scene environment the dressings bind at birth
    • Plan 079: A page that lost its GPU comes back where it stood, through one recovery session
    • 080 — One row per inquiry kind: the twin's per-kind dispatch in one place
    • 082 — One answer turn, and a code for every way it ends
    • 084 — One session for an answer's lifetime: reading aloud, dictation and the scene's waits in one module
    • 085 — Window niches and shop windows: performance and follow-ups
    • Plan 087 [rewrite]: Plates compared on a real GPU, and one ledger every plan of the series writes its figures into
    • Plan 088 [rewrite]: The tileset is a published product, named by a lock file; the web build bakes nothing and data/ leaves git
    • Plan 089 [rewrite]: The bakes are type-checked in CI against a baseline that only shrinks
    • Plan 090 [rewrite]: A tile's dressing arrives in the layout the GPU draws from
    • Plan 091 [rewrite]: A tile's rasters arrive as the GPU reads them — plain arrays for ids, blocks for soft fields, a few files and bindings
    • Plan 092 [rewrite]: The bakes work on site-wide typed tables, cut tiles last, and no step rewrites another's file
    • Plan 093 [rewrite]: The stream's tile is smaller than the bake's — a quadtree whose levels replace the raster twins, built only if a phone still asks for it
    • Plan 094 [rewrite]: The clay's limits are counted by a test, and every pipeline the scene draws with is known at boot
    • Plan 095 [rewrite]: The viewer is a package with one entrance, a coordinate's frame is its type, and bootApp is owners
    • Plan 096 [rewrite]: Every bake heuristic that guesses has a reference set and a score a bake PR must hold
  • What the data streams carry that the walker does not use yet
Entwicklung (English)

Plan 074: Bake the static dressing, load the optional features on demand, one store for the HUD

Executor instructions: This is a direction plan from the 2026-10-10 architecture review (improve-codebase-architecture, run beside the performance audit that produced plans 069–073). Its four parts are independent; each opens with a spike whose numbers decide whether the rest is built. Read AGENTS.md first. If a STOP condition occurs, stop and report. Update this plan's row in docs/plans/README.md when done.

Drift check (run first): git diff --stat <this plan's commit>..HEAD -- app/_components/tile-stream.ts app/_components/create-app.ts app/_components/city-walk.tsx app/_components/scene-sidebar.tsx scripts/prepare-data.ts

Status

  • Priority: P2 (part A P1 once plan 069's measurements are in)
  • Effort: L (A), M (B), M (C), S–M (D)
  • Risk: MED — A moves geometry from the runtime into the build
  • Depends on: plan 069 steps 1–2 (the timing marks name what part A saves); none for B–D
  • Category: architecture, perf (boot, jank, bundle)
  • Planned at: 2026-10-10, on top of the performance PR that built plan 068, plan 070 steps 1–3, plan 069 step 5 and the maintainer's look decisions

Why this matters

The maintainer reported a load that freezes at 52 %, jerky movement and crashing phones, and asked whether the code "simply grew a lot or is optimised for niches". Measured on the reference site (SwiftShader, full profile, 400×300): the first frame at 58 s, loaded at 501 s, the Umgebung stage done only at 456 s — right after the sixth of eight dressings, because a fine terrain level holds a tile-renderer parse slot while it waits (≤ 10 s, HAND_OVER_WAIT_MS) for its dressing, and dressings are built one at a time for the site. The dressing is built on the main thread from up to 17 side files per fine level. The structural causes are below; the per-tile ones (raster sizes, the fog-bounded stream, meshopt workers) were fixed in the PR this plan follows.

Part A — Bake the static dressing into the fine level (top recommendation)

Problem. Every fine terrain level fetches its side files and rebuilds about ten static parts on the main thread inside buildDressing (tile-stream.ts): rails, tram, riverside, bridge decks and their superstructure, furniture, monuments, lamps, sport fixtures, cultivated rows, hedges — and then compiles them. None of it depends on the viewer's state beyond the look's uniforms. ADR 0030 already moved walls, kerbs, stairs and fences into the fine glTF and named rails as the next candidate once deck heights were solved by the build — ADR 0041 did that (scripts/line-levels.ts).

Solution. Bake the geometry into the L0 glTF as named nodes (as stairs is), each with the material key the runtime binds to its scene material; furniture and lamps as instance tables over one site-wide model set; trees as a baked instance table (the build already places them for the coarse crowns, lib/city/coarse-crowns.ts — only the placement moves; LOD, season and wind stay at runtime). The inquiry's data become a per-tile file fetched with the first question (the artifact table's ask column already works this way for trees).

First step (spike). Rails, tram and riverside only: bake them in prepare-data.ts through the same builders (they are DOM-free or can be made so), name the nodes, dress them with their existing scene materials in dressTerrain, and drop their side files from the fine level's dressing extras. Measure with plan 069's marks: dressing:build per tile, requests per fine level, the fine glb's size. scripts/ground-joins.test.ts already holds baked parts to the ground (list them in JOIN_PARTS).

Benefits. Fewer requests and long tasks per fine level, buffers quantised and meshopt-compressed instead of Float32, no GeoJSON parse on a phone, and the parse slot no longer waits on a dressing chain. Most of ≈ 7 400 lines of mesh builders leave the viewer chunk.

STOP if the fine glb of the spawn tile grows by more than 30 % gz, or if a baked part breaks a ground-joins budget.

Part B — Optional features behind one lazy seam

Problem. Modell (≈ 3 500 lines: model-rig.ts, model-camera.ts, model-cuts.ts, projection-panel.tsx, image-export.ts), the picture styles (≈ 1 900: stylize-effect.ts, paper-scene.ts, style-dressing.ts) and the data layers (≈ 3 500: traffic-layer.ts, data-overlays.ts, bike-layer.ts, tram-cars.ts, glass.ts) ship in the scene chunk and are wired into bootApp by hand. The maintainer: "they are important, but not for the initial load, and often never loaded — lazy?". Their runtime cost on the initial load is gone (no tier warms the styles any more, the data layers build on first switch-on), so what is left is ≈ 33 KB gz of code and the coupling.

Solution. A feature seam in create-app.ts: the spine (renderer, stream, post stack, render loop, clock) exposes hooks (onFrame, onStreamChange, onLook, onSun, input claims); each optional feature is a module loaded with import() on first use that registers against them. Modell's input checks become a claim it installs while on; the styles' pipelines are built by the module when a style is first picked (the post stack keeps the pastel pair); the data layers' tile slot in tile-stream.ts becomes a registration.

First step. The data layers: they already build on first switch-on (showDataLayers); move their modules behind import() and measure the scene chunk (gzip -9c) before and after. Then the styles, then Modell.

STOP if a lazy feature's first use hitches longer than its warmed build did before (measure on a real GPU), or if the seam needs a module global.

Part C — The spine as a module with a test surface

Problem. bootApp in create-app.ts is one closure of ≈ 2 200 lines; its four hubs (setSun, applyLook, the stream-change handler, the frame) hard-code ≈ 31 feature hookups; the handle has 49 members, the options 18 callbacks; neither create-app.ts nor post-stack.ts has a unit test — only the SwiftShader e2e reaches them.

Solution. Follows from part B: once features register through hooks, the spine is testable with fake features (does a stream change reach every registered feature once per task; does a lost GPU stop the loop). Do it after B, not before — B decides the hook set.

Part D — A scene-status store for the HUD

Problem. CityWalk (city-walk.tsx) holds 31 useStates and takes 18 scene callbacks; SceneSidebar takes ≈ 40 props, so every report from the scene (stages, stats, fps, pose, data-layer status) re-renders the whole HUD.

Solution. A store with slices, shaped like the existing look store (lib/city/look-state.ts, useSyncExternalStore), so each widget subscribes to its slice. Measure with React's profiler: renders per second of SceneSidebar while streaming, before and after.

Also seen (backlog, not planned)

  • One raster stack per tile (terrain-layer.ts loaders, ground-detail, sport-ground, road-markings, cultivated-layer, sky-light): a fine level binds ≈ 12 textures from 9 files; bake one set both levels name (class, NDVI, sky view, horizon) and one fine-only set grouped by sampler — 9 loads to 2, 12 bindings to ≈ 4.
  • Building level of detail: one full LoD2 mesh at every distance (≈ 2 M triangles, 75 MB for the spawn tile). A simplified per-tile city level (meshopt simplify, feature ids kept, REPLACE to the full mesh near the camera) would need no BVH and no CPU copies far away.
  • City BVH lazily: only for building tiles within ~1 km, or on the first ray (plan 043 is blocked on bundling a worker; this is the no-worker half, plan 069 step 7).

Done criteria

Per part: its spike's numbers recorded in this file's Findings; the part built or rejected with the reason; bun run verify and the e2e suite green; docs (docs/rendering.md, docs/data-pipeline.md, AGENTS.md "Where things live", ADR 0030 amended for part A) current.

Findings

Part B — the data layers behind the seam (2026-10-10): STOPPED at the chunk

Built on plan 069's branch (claude/plan-069-streaming-without-stalls).

Method. Both sides built the same way: NEXT_PUBLIC_POC_DEBUG=1 next build (the e2e build; the __poc hook is the same constant on both sides), Next.js 16.3.7 with Turbopack, all seven sites' data. The base is the branch's head exported to a scratch folder (git archive). Each build served by next start; headless Chromium (SwiftShader, as the e2e) at /dresden?scene=lite, 800×600, records every /_next/static/*.js it fetches until __poc.ready — the first-load set: the route's own chunks, the HUD's (city-walk.tsx) and the scene's (create-app.ts and three.js); each file then gzip -9-ed from the build's own .next/static. Then __poc.look.set({ trafficLayer: true }), and the chunks fetched after it. The scene chunk is told by a string only create-app.ts holds, the data layers' code by DataGlassBackdrop / traffic-glass / the tram status's failure text.

buildfirst-load JS, gzrawthe scene's chunk(s), raw / gzon the first switch-on
base904 6192 799 4711 574 194 / 493 506 (data layers inside)nothing
data layers behind import()927 361 (+22 742)2 896 987 (+97 516)576 471 + 1 086 665 / 211 003 + 301 06023 749 / 10 089
… and the rail module out of its reach (a stub, measured only)924 669 (+20 050)2 891 542618 739 + 1 040 07323 709 / 10 080
the seam with the module imported statically (built)904 716 (+97)2 801 0481 575 601 / 493 561nothing

Why the chunk cost more than it moved. Turbopack hoists the modules one chunk group alone needs into one scope: the scene's own code and three.js were one scope, three's functions called by local, mangled names. The data layers import three/webgpu and three/tsl too, so as a chunk group of their own three.js became a module both groups share — it left the scene's scope for a shared chunk (its WebGPU backend moved from the scene's chunk to the second one), and every call into it became a property access on the module: the scene's code made 180 such (0,X.fn)(…) calls before and 2 929 after. Taking the rail module (the largest the data layers share with the scene, via buildDeckTable) out of their reach won back only 2.7 KB: the cost is three's, not the app modules'. It is paid once, by the first lazy chunk that imports three — ≈ 32.8 KB gz (22.7 net + the 10.1 moved) — and this part's own estimate of everything it could move is ≈ 33 KB gz. Styles and Modell import three/tsl as much as the data layers do, so even all three behind import() would about break even, for a seam with Modell's ≈ 111 references still to untangle. Escaping the tax means a lazy chunk that takes TSL from the spine instead of importing it — every layer module a factory with a prologue of injected functions, a bigger framework than the three features need.

What was kept (refactor(scene), byte-neutral as measured: +97 B gz; the decision is ADR 0040): the seam itself. feature-seam.ts — the spine's hooks (frame, streamChange, the look store, the scene's clock as a watched value a late starter reads first), lazyFeature (since 2026-11-11 startOnce: starts once, on first want; never after the spine is gone; a failed load asked for again — by the spine on the next switch-on, wantOnSwitchOn); data-layers-feature.ts — the data layers start on the first switch-on of any of them against those hooks (create-app.ts no longer wires the overlays into setSun, applyLook, the stream-change handler and the frame by hand, nor writes the glass's clock: it emits, and keeps three reads of a started feature — the probe's asks, the census, the card's hour); the tiles' traffic slot takes its builder through TileStreamContext.trafficBuilder and waits for it outside the dressings' turn — a tile hung before the first switch-on and one landing after build from the same start, a builder that did not come is asked for again on the next switch-on and never reported as the tile's failed build, one that comes after the layer went off again builds nothing (three new tile-stream.test.ts cases); traffic-flow.ts — the flows' hour uniforms, position node, attributes and mesh lookup, which the asked section's outline (its pass compiled at boot, its shape) reads, split from the layer's builder. Going lazy is then the one line in create-app.ts (() => Promise.resolve(dataLayersModule) → an import()), at the cost measured above.

What stopped and why. The import() itself, and with it the styles and Modell: not by the plan's STOP conditions (no module global was needed; the first switch-on's extra cost would have been the chunk's fetch, 48–173 ms from a local server, and its parse) but by the measurement — the chunk makes the first load larger, the one number this part exists to lower. Neither the styles nor Modell was started.

Timings, for the record, not for conclusions. Boot to ready 228 s (base), 204 s (lazy), 230 s (rail stub), 186 s (static); first switch-on of the traffic to its first triangles in the stats (a 250 ms timer) 26.2 s, 36.7 s, 40.4 s, 27.7 s. One run each on a shared four-core box at load 7–11 under SwiftShader: noise-dominated.

Verified. bun run verify green (2 468 pass); e2e against the static build (production, NEXT_PUBLIC_POC_DEBUG=1): @desktop-hud 10 passed (7.9 min) — the data layers' switch-on spec among them —, @desktop-render 8 passed (13.1 min). Run with CI's timeouts (CI=1, --timeout=900000): on this box the boot took longer than the local 120 s wait for ready, and the first local run stopped there before any test ran. The whole-site shard and @phone were not run.

Part D — built (2026-10-10)

What was built. lib/city/slice-store.ts: a store of named slices, DOM- and React-free — get/set/update/subscribe per slice, an equality per slice (Object.is, or dataEqual for plain data), and an optional schedule that hears a burst once per slice. On it app/_components/scene-status.ts: the HUD's slices (the stages, busy, a failed tile, the GPU failure, the stats' three counters, the footprints, the frame rate in whole frames, the site, the mode, Modell's view, the inquiry, the data layers' three statuses, the pose), a useSceneStatus(key) hook over useSyncExternalStore, and sceneReports, which turns the store into the CityWalkOptions callbacks — create-app.ts is unchanged. The HUD's store notifies in the task after a write (afterTask), so a report from inside a frame (the frame rate, Modell's view, the pose) re-renders after it, as the transitions did. Each widget reads its own slice: the loading screen and the pill (ShellLoadScreen, ScenePill), the failed-tile line, the centre mark, the failure card, the inquiry panel, the overlays (mode, inquiry) and Modell's instruments, and in the sidebar the minimap (footprints; the pose straight to its canvas), the mode switch, the key table, Projektion (ModelProjection), the counters (SceneCounters) and the data layers' lines. CityWalk holds 12 useStates instead of 30 (the store itself one of them; the rest HUD-local: boot phase, veil, tab, snapshot, …) and SceneSidebar takes 28 props instead of 38, none of them a scene report.

Measured (production build with NEXT_PUBLIC_POC_DEBUG=1, /dresden?scene=lite, 800×600, headless Chromium on SwiftShader, on a 4-core container at a load average of ~17 from other jobs — frames took 4–8 s, so wall-clock rates mean little; the windows are anchored to the scene's milestones instead). Render calls (component bodies run) and commits, counted by a temporary counter on window (React's <Profiler> is a no-op in a production build), cumulative from goto:

window (end)reports so far (stage / stats / fps / modelView)CityWalk renders (commits) before → afterSceneSidebar commits before → after
first frame8 / 3 / 16 / 017 (9) → 3 (3)9 → 3
ready12 / 6 / 56 / 031 (17) → 4 (4)17 → 4
+ 30 frames standing12 / 6 / 84 / 086 (44) → 4 (4)44 → 4
+ 30 frames in Modell12 / 6 / 113 / 30147 (75) → 4 (4)75 → 4

Before, every frame-rate report (2 Hz on a real device) was one commit of the whole HUD, and in Modell every view report (10 Hz) another: up to 12 whole-HUD renders a second in Modell on a phone. After, the HUD's two big components render only for the HUD's own state (4 times in the whole run: mount, the site, the first frame, the veil). What renders instead is small: over the same run ShellLoadScreen 6, ScenePill 5, MinimapCard 6, ModelProjection 7, Modell's instruments 3 (a view standing still is the same data, so 30 view reports were 3 renders), the counters 0 (their tab was not open).

The handover. The veil leaves VEIL_HOLD_MS after the first frame on a timer, and a stage report is now an urgent render (an external store's update is never a transition) — the failure the old onStage comment warned about. Under this load the first frame is followed by seconds-long frames during which neither timers nor React's scheduled tasks run (presumably the compiles after the first frame), in both builds: first frame → veil gone took 0.8, 54.6, 95.3 and 67.5 s on the base and 72.5, 68.3, 87.9, 85.1 and 76.9 s on the branch; the veil's own 600 ms timer fired 0.7, 62 and 49 s after it was set on the base, 71, 68 and 61 s on the branch (traced by wrapping setTimeout in the page). The ranges overlap, the path (a timer, a default update in CityWalk) is unchanged code, and the stage renders are now a loading screen's, not the HUD's; judged no regression on this evidence, but the handover is worth a look on a phone.

Checks. bun run verify green; the e2e against the same build (the counters are behaviourally inert) with the timeouts widened locally for the load: @desktop-hud 10/10 (a first run lost live mode to a race in the spec under the load — switched off, the button is gone a second later once the compass has been quiet for five seconds; the rerun passed), @phone 1/1, @desktop-render 8/8, the start page, the 404 and the viewer shell 3/3; the whole-site spec not run.

Not done here: a real-device profile (the numbers above are counts, not milliseconds). Parts A and C stay open (part B above).

Previous
Plan 071: A phone renders a lean scene, a desktop a lighter one
Next
076 — Streaming without holes: the ground first, a plate under everything, coarse buildings and trees from the start
Source on GitHub: docs/plans/074-architecture-deepening.md
On this page
  • Status
  • Why this matters
  • Part A — Bake the static dressing into the fine level (top recommendation)
  • Part B — Optional features behind one lazy seam
  • Part C — The spine as a module with a test surface
  • Part D — A scene-status store for the HUD
  • Also seen (backlog, not planned)
  • Done criteria
  • Findings
  • Part B — the data layers behind the seam (2026-10-10): STOPPED at the chunk
  • Part D — built (2026-10-10)