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 090 [rewrite]: A tile's dressing arrives in the layout the GPU draws from

Executor instructions: Read 086-rewrite-programme.md and AGENTS.md first, then load the city-walker, new-scene-layer and new-bake-step skills. The plan goes a family of layers at a time; each phase is one PR and ends in a Verify and in figures written into the ledger plan 087 sets up. If a STOP condition occurs, stop and report with the figures — do not improvise. Update this plan's row in docs/plans/README.md after every phase.

Drift check (run first): git diff --stat 5dfa300d..HEAD -- app/_components/tile-stream.ts app/_components/instancing.ts app/_components/late-parts.ts lib/city/tile.ts lib/city/tileset.ts lib/city/build-steps.ts lib/city/coarse-crowns.ts lib/city/point-pack.ts scripts/coarse-crowns.ts scripts/bake-entries.ts scripts/ground-joins.ts — on a change, compare "Current state" with the code before going on.

Status

  • Priority: P1
  • Effort: L — six phases, each S–M
  • Risk: MED–HIGH — the picture must not change, and three's public API has to take a compact instance record (Phase 0 finds out)
  • Depends on: 087 (plates and ledger; hard); 088 for the byte gates as a visitor is served (until then they are measured on public/data)
  • Category: rewrite — faster on the device; fewer bytes and requests; less code in the viewer
  • Series: 086-rewrite-programme.md
  • Planned at: commit 5dfa300d, 2026-11-16
  • Status: TODO

Why this matters

A fine terrain level fetches up to seventeen side files, parses most of them as GeoJSON and rebuilds its dressing — trees, lamps, rails, trams, furniture, monuments — in JavaScript on the thread that draws, on every device, on every visit. All of it is a function of committed files; none of it depends on the visitor. Before the builders were cut into slices a phone lost 0.7–1.3 s a builder a tile; since then the cost is spread, not gone, and the viewer carries the machinery that spreads it. After this plan the build has placed everything, a tile brings its dressing as tables whose bytes are the vertex buffers, and the viewer uploads them. It takes over plan 074 part A and its spike, PR #156.

Current state

Counted and read on 2026-11-16 at 5dfa300d.

The seventeen dressing kinds (lib/city/tile.ts, the ARTIFACTS rows with dressing: true): vegrows, canopy, cultivated, lamps, monuments, furniture, mly, rail, bridge, railarea, platform, tram, riverside, trees, traffic, lowveg, canopyx. The coarse level has three (coarse: true): bridge, traffic and the built crowns. One file is fetched only with a question (ask: true): treeFacts. canopy and canopyx are published packed (lib/city/point-pack.ts, magic PTS1, 12–20 bytes a point); the other fifteen are GeoJSON.

Where they are built: buildDressing in app/_components/tile-stream.ts fetches every kind at once (allNamed({ rows: get("vegrows"), canopy: getPoints("canopy"), … })), loads the NDVI raster a second time as a CPU sampler for the trees (loadNdviSampler), joins kinds (const lamps = [...osmLamps, ...fromMapillary.lamps], lampsBy(rails, trams, …), tramSteps(trams, bridges, pinned), offMonuments(canopy, monuments)), filters by seam ownership (ownsPoint) and runs the builders one after another, with await nextTask(signal) between them and inSlices(…) inside the long ones. The inquiry's solids (lib/city/ask-items.ts: treeSets, monumentItems, bridgeItems, moreSetsSteps) are built from the same features in idle time.

What the slices cost and hide (docs/rendering.md, "The frame budget"; lib/city/build-steps.ts): as one task each, on the phone profile, the rails took 1.3 s (a yard's ballast draped at 1 m), the trees 0.8–1.3 s, the tram 0.7 s, the ask sets 0.4–0.7 s. They now run in slices of SLICE_MS = 8 (REST_SLICE_MS = 30 while the camera rests), and every pause costs a frame.

How an instance is drawn (app/_components/instancing.ts): an Instances set is a Mesh over an InstancedBufferGeometry whose matrices are one InstancedInterleavedBuffer of sixteen floats an instance (new Float32Array(capacity * 16), attributes iMat0…iMat3), written on the CPU with setMatrixAt; colours are a second buffer (iColor, three floats), further per-instance values a buffer each (instanceFloat(name): the trunks' TRUNK_DROP, the monuments' iFinish). instancePosition() branches on builder.geometry.hasAttribute("iMat0"). That is 64 bytes an instance before colour, against the 20 bytes of the record the build already writes for a coarse crown.

The pattern to follow is in the repository twice.

  • lib/city/coarse-crowns.ts and scripts/coarse-crowns.ts: the build runs "the fine level's own placement … on the fine level's own ground" and publishes crowns_<tile>.crw.gz — CRW1, 20 bytes a crown: float32 x, z; uint8 code, ndvi, genus; int8 jitter; uint16 rot; uint16 a, b, c. The viewer (coarse-crowns-layer.ts, 225 lines) still turns each record into a matrix and reads the ground for its height (ctx.heightAt).
  • ADR 0030, decision 3: stairs, walls, kerbs and fences are named nodes in the fine terrain glTF, "and the browser computes nothing"; scripts/ground-joins.ts holds them to budgets (JOIN_PARTS: kerbs, walls, stairs, fences, sheds, doors, plinths, monorails).

The spike, PR #156 (branch claude/plan-074a-bake-lines-spike, draft since 2026-10-11, based on 073a00d, unmerged, not looked at on a real GPU). It baked rails, trams and riverside as triangles into the fine glTF (24 named nodes, lib/city/line-nodes.ts), with the builders made DOM-free (lib/city/rail-mesh.ts, tram-mesh.ts, riverside-mesh.ts, wire-mesh.ts, mesh3.ts, scripts/bake-lines.ts). Its numbers: the spawn fine glb 1 862 749 → 2 073 882 bytes gz (+11.3 %); all fifteen of Dresden 31.2 → 34.4 MB (+10.1 %, the worst tile, the Neustadt yards, +34.5 %); side files a fine level 19 → 14; dressing:build on the spawn level 1.65–2.90 s → 0.78–1.75 s (SwiftShader). Float positions were rejected (+27.6 %). Left open: the line materials compiled inside the content's compile, which holds a tile-renderer parse slot; street rails stand 2 cm proud while a 16-bit position steps up to 3 cm over a tile. Triangles weigh more than the lines they come from: that is why this plan prefers tables the GPU expands (086, joint 5).

What already expands on the GPU: app/_components/wire-ribbons.ts draws wires as camera-facing ribbons from per-vertex direction, side and half-width; the crowns' shape, lean, sway and season are vertex and fragment nodes over one geometry (vegetation-layer.ts, crown-season.ts); the tiers a 250 m chunk draws are planned at runtime (lib/city/vegetation-lod.ts).

Sizes (lines, 2026-11-16): vegetation-layer.ts 2 093, bridge-layer.ts 1 448, rail-layer.ts 1 216, furniture-layer.ts 1 202, monument-layer.ts 1 021, lamp-layer.ts 807, tram-layer.ts 781, riverside-layer.ts 600, low-vegetation-layer.ts 534, tree-inventory-layer.ts 500, catenary-layer.ts 410, cultivated-layer.ts 392, coarse-crowns-layer.ts 225 — about 11 200 lines in thirteen modules, materials included.

Rules that bind every phase (AGENTS.md): WebGPU draws from at most eight vertex buffers and the clay is two inter-stage variables short of sixteen — past either a mesh vanishes; never InstancedMesh; a material without per-tile data is a sceneMaterial; what a tile brings is built in the dressing plugin's processTileModel (later: a late part, late-parts.ts), compiled before it shows, freed in disposeTile, and weighed in calculateBytesUsed; anything added after the first frame calls invalidateShadows(); a part that stands on the ground uses lib/city/ground-join.ts and reports its joins; a line takes its level from the build (lineLevelsAt, ADR 0041); every tile carries the same baked files (lib/city/tile-data.test.ts); a bake's modules are in its row of scripts/bake-entries.ts; a file a bake writes and TypeScript reads has one zod schema (ADR 0059); a phone's memory must not grow (ADR 0047).

Commands you will need

PurposeCommandExpected
Installbun installexit 0
Autofix, then the gatebun run fix && bun run verifyexit 0
One site's tilesetbun scripts/prepare-data.ts dresdenpublishes under public/data/dresden/
Every sitebun run buildexit 0
Ground joinsbun test scripts/ground-joins.test.tspass
Same files a tile, bake keysbun test lib/city/tile-data.test.ts scripts/bake-entries.test.tspass
Headless e2ebun run test:e2epass
Real-GPU platesbun run shots and plan 087's comparisonwithin its tolerance
Ledgerthe command plan 087 definesa row per figure, before and after

Scope

In scope: app/_components/tile-stream.ts (buildDressing, buildCoarseDressing, the dressing plugin), instancing.ts, the thirteen layer modules above and sport-fixtures.ts, tree-foot.ts, track-bed.ts; lib/city/tile.ts, tileset.ts, build-steps.ts, point-pack.ts, coarse-crowns.ts, tree-placement.ts, tree-inventory.ts, ask-items.ts, ask-solids.ts; new lib/city/dressing-pack.ts and one lib/city/<kind>-file.ts a kind; new scripts/dressing-sources.ts, scripts/bake-dressing.ts, scripts/prepare/dressing.ts; scripts/bake-entries.ts, scripts/ground-joins.ts; the docs and ADRs named in Phase 5.

Out of scope: the Python bakes and the files they write (their format is plan 092's); the rasters (091); the tile grid (093); the buildings' glTF and the clay; the window niches (plan 085); the data layers' live sources; the murals; a worker pool (086, joint 6); merging or closing PR #156 (say what became of it in this plan's row; the maintainer closes it).

Where every kind goes

Four homes. Stands: an instance table the vertex shader expands. Lines: a table of segments the GPU expands. Nodes: triangles baked into the fine glTF beside the ground, as ADR 0030's parts are. Runtime: it moves, or a visitor switches it on.

Kind todayHomeReason; what stays at runtime
canopy, canopyx, the tree rows of vegrows, trees, the orchards of cultivatedstands — one table, sorted by 250 m chunkthe largest counts (a forest chunk ≈ 1 300 trees; a tile up to 81 000 canopy points) and the build already places them for the coarse crowns. Runtime: the tiers (vegetation-lod.ts), season, sway, colour
crowns (coarse)stands — the same recordalready a table; the viewer stops making matrices from it and reading the ground
lamps, the lamps of mlystandsa post, an arm, a head. Runtime: the fixed pool of real lights and the night
furniture, the bins of mly, the sport fixturesstands, over one site-wide set of modelsa model, a place, a turn. Runtime: a flag's cloth, a clock's hands
monumentsstands for statues, stones and columns; nodes for basinsa basin is a ring of its own shape. Runtime: a fountain's water
masts, piles, posts, stop signs (in tram, riverside, rail)standsthe spike merged them into triangles; an instance is smaller
lowveg, the hedge rows of vegrows, the vine rows of cultivatedlinesa hedge is a section along a line
the rails of rail and tram, the wires of trams, railways and lampslines or nodes — Phase 0 decides by bytes and by millisecondsa rail is a profile along a line; the wires already expand on the GPU. Against it: a street rail needs centimetres
railarea, platform, the tram's beds, the piers, pontoons, huts and groynes of riversidenodesareas draped on the ground and a few irregular solids; no table is smaller than their triangles
bridgenodes on both levels — last, behind a STOPthe largest builder, asked through its meshes today and drawn by the coarse level too
trafficruntimea data layer, off at start, bodies built on the first switch-on (ADR 0040). Its lines arrive as a table, not as GeoJSON
tram cars, bikes, the ferry's wake, water sheetsruntimethey move, or come from the level's own triangles

Phases

Phase 0 — the baseline and two spikes (one PR, nothing visible)

  1. Baseline. With plan 087's ledger, record for Dresden's spawn tile 33412_5656_2_sn, a forest tile (33416_5658_2_sn), the Neustadt yards (the spike's worst tile) and München's heaviest (32690_5334), on the desktop and the phone profile: wire bytes and requests of a fine level by kind; scene-thread milliseconds by builder (?trace=1, the dressing:build and dressing:asks marks of stream-timing.ts); the bytes the dressing weighs (calculateBytesUsed); the longest task of a flight.
  2. The stand record, on the coarse crowns. They are the smallest case and their file is the record. Draw a coarse level's crowns from the fetched bytes without setMatrixAt: give Instances a second way in (attributes over the record's own bytes instead of iMat0…iMat3) and let instancePosition() compose place, turn and scale in the vertex stage when the geometry has them. Target record, to be confirmed here: place x, y, z as 16 bits each over the tile's box plus the turn in the fourth (the height baked — the build stood it on the level's ground); three sizes and a spare as 16 bits; code, ndvi, genus, jitter as four bytes — 20 bytes, stride a multiple of 4. Find out, on public API only: which typed arrays and normalized flags reach TSL as which types; whether one interleaved buffer can hold 16-bit and 8-bit fields or the record needs two or three buffers; that the tile's box reaches the shader through the set's own matrix or a slot (app/_components/material-slots.ts), never a material a tile; that sets of one layout still share one build and one pipeline. Count vertex buffers and inter-stage variables of every variant (plan 094 turns the count into a test).
  3. Lines three ways, on the yards' tile: today's runtime builders; the spike's triangles (port rail-mesh.ts and bake-lines.ts from its branch, do not rebase the branch); a segment table (two ends, the level at each from lineLevelsAt, a profile id) drawn as an instanced profile. For each: bytes gz, scene-thread milliseconds, GPU bytes, and the street rail's height error against the road.

Verify: bun run verify → exit 0; plates of 087's views that show trees and rails → within tolerance for arm 2, recorded for the three arms of 3; the ledger holds the baseline and both spikes. Write the chosen record and the chosen home of the rails into this file's Findings.

Phase 1 — the container and the trees

  1. lib/city/dressing-pack.ts (no THREE, no DOM, as point-pack.ts): one table of sections — name, record fields, formats — from which the packer, the reader and the vertex layout are all derived, so the file's layout cannot differ from the GPU's. A file is a magic, a directory (section, stride, count, offset, the chunks' ranges and boxes) and the sections, each 4-byte aligned so a typed-array view needs no copy. One file a fine level (dressing), one a coarse level; every tile has both, with empty sections where it has nothing (tile-data.test.ts). It takes rows in ARTIFACTS (built: true) and in scripts/bake-entries.ts.
  2. scripts/dressing-sources.ts: one reader a kind, each through parseBakeFile and a schema module lib/city/<kind>-file.ts (ADR 0059; this ends the excuse AGENTS.md grants the crown and canopy layers for the kinds it touches). Every baker below reads through it and nothing else opens those files — plan 092 then changes the format here once (086, joint 7).
  3. The build places the trees as scripts/coarse-crowns.ts does today (tree-placement.ts, tree-inventory.ts, the register's veto, the monuments' veto offMonuments, the orchards), on the fine ground, sorted by 250 m chunk, with what the ground says where each stands baked into its record (height, the trunk's drop, the foot's slope — tree-foot.ts computes them at runtime today) and its NDVI.
  4. The viewer uploads: a chunk's sets are views over the file's bytes; tileVegetationSteps, the runtime placement and loadNdviSampler in the dressing go; vegetation-lod.ts, the season and the sway stay as they are. canopy, canopyx, trees and the coarse crowns stop being published; vegrows and cultivated stay until Phase 3.
  5. The inquiry: a tree's cylinders come from its record, built when a ray first reaches the tile; treeFacts stays, its row the record's source index.

Verify: bun test lib/city/dressing-pack.test.ts (round trip; every stride a multiple of 4; the layout derived from the table) → pass; bun run verify, bun run test:e2e → pass, the scene census still counts the vegetation; plates of the tree views → within tolerance; ledger: a fine level's bytes not larger, its requests 2 fewer (three files leave, one arrives), the trees' scene-thread time near zero, the vegetation's GPU bytes smaller.

Phase 2 — everything that stands

Lamps, furniture, sport fixtures, monuments' markers, masts, piles, posts, stop signs. The joins move into the build: Mapillary's lamps and bins into their tables (mapillaryParts), seam ownership (ownsPoint), which lamp stands by a track (lampsBy) or over water. The models become one set for the site, shared across tiles and detached before a tile's geometry is disposed (markSceneShared; the rule is in the city-walker skill, "Tiles"). The lamp pool and the facades' street light read heads from the table.

Verify: as Phase 1, for the night and furniture views; lamps, furniture, mly, monuments no longer published.

Phase 3 — lines

As Phase 0 decided. Hedges and vine rows as segments in any case; rails and wires as segments or as nodes. A line's level comes from the build (lineLevelsAt); a part on the ground reports joins and is listed in JOIN_PARTS with a budget at its measured state.

Verify: bun test scripts/ground-joins.test.ts → pass with the new parts; plates of the tram, rail and vineyard views; ledger as before.

Phase 4 — areas and solids

Ballast, platforms, tram beds, the riverside's structures (the spike's builders), monument basins: nodes in the fine glTF, quantised and meshopt-compressed like the walls. Bridges last, on both levels, their inquiry through ask-solids.ts' Slab. Per kind: if the level's bytes grow, the kind stays at runtime and this file says so.

Verify: as Phase 3; no kind but traffic is left in buildDressing.

Phase 5 — what is deleted, and the records

buildDressing becomes a fetch of one file and its upload; the slices go (inSlices, setSliceBudget, REST_SLICE_MS and their callers in create-app.ts; finished stays if a test needs it), with pointFeatures, the viewer's GeoJSON guards for the kinds that left and the idle-time ask build. One ask file a tile carries what a card says of the things in the tables (ADR 0042, point 1). Measure whether a fine level still needs its ground prepared before it shows now that nothing stands things on it at runtime; if only walking and rays read it, make it lazy like the BVH — or note the figure and leave it.

Docs (docs-upkeep skill): rewrite ADR 0024 (what a tile brings, the side files, the two phases), ADR 0030 (decision 3 and 5: tables beside nodes), ADR 0041 (who places a line), ADR 0042 (the inquiry's files), ADR 0047 (bytes an instance), and write one new ADR — a tile's dressing is tables the GPU expands — with the next free number (docs/adr/README.md, "Numbering"); docs/rendering.md (scene graph, frame budget, boot sequence), docs/data-pipeline.md (the contracts, "Measuring what the browser downloads"), docs/transformations.md, docs/data-flow.md, the guide's data journey in both languages, AGENTS.md, the city-walker and new-scene-layer skills. Condense plan 074 part A into completed.md.

Verify: grep -rn "inSlices\|setSliceBudget" app lib → no match; grep -c "dressing: true" lib/city/tile.ts → at most 2; bun run verify, bun run build, bun run test:e2e → pass; the ledger's final row against Phase 0's baseline.

Test plan

  • lib/city/dressing-pack.test.ts: round trip of every section; the vertex layout equals the table; an unknown section is refused. Pattern: lib/city/point-pack.test.ts.
  • A placement test a family: the build's records against today's runtime builder on the committed spawn tile (same count, positions within the quantisation step) — written before the builder moves, kept afterwards against a committed digest.
  • The look stays out of the bake: a test over the import graph (scripts/bake-sources.ts) that the dressing entry reaches none of the palette, season, style or look modules (lib/city/landcover.ts's colours, tree-season.ts, render-style.ts, look-controls.ts), so a colour change re-bakes nothing (086, joint 3).
  • scripts/ground-joins.test.ts, tile-data.test.ts, bake-entries.test.ts, features.test.ts, bake-files.test.ts for each new schema.
  • e2e: the per-layer census keeps every layer; a question on a tree, a lamp and a bench still opens its card.

Done criteria

  • buildDressing fetches one file a level; no GeoJSON is parsed in the scene (grep -rn "fetchFeatures" app/_components → only the data layers' own)
  • lib/city/build-steps.ts' slicing is gone and no worker was added
  • Ledger, against Phase 0: a fine level's wire bytes ≤ baseline on every measured tile; requests a fine level down by at least 12; dressing:build scene-thread time down by at least 80 %; a phone's tile bytes ≤ baseline
  • Plan 087's plates within tolerance on a real GPU for every view that shows a moved layer
  • bun run verify, bun run build, bun run test:e2e exit 0
  • The ADRs and docs of Phase 5 are current; the row in docs/plans/README.md says what was built and what stayed

STOP conditions

  • Plan 087's ledger or plates do not exist yet: stop before Phase 1.
  • Phase 0: the record cannot be drawn on public API without a material or a build a tile, or a variant needs a ninth vertex buffer or a seventeenth inter-stage variable. Report the layout that failed.
  • Any phase: a fine level's wire bytes grow on a measured tile, or a phone's bytes grow (ADR 0047). Leave that kind where it was.
  • A ground-join budget would have to rise.
  • A plate differs beyond 087's tolerance and the cause is not found in one attempt: report with both plates and the snapshot JSON.
  • A kind's place depends on something only the page knows (a setting, a live source): it belongs to the runtime row of the table.
  • The dressing's compile, once it is uploads only, still holds a tile-renderer parse slot on a real GPU (the spike's open question): keep it a late part and report the timing.

Maintenance notes

  • A new kind takes a section in dressing-pack.ts, a reader in dressing-sources.ts and a row in the table above; it never adds a fetch to the scene.
  • A record field is a fact about the place, never a colour. Review any import a baker gains.
  • The dressing's cache key covers the fine ground of every tile it stands things on (as the coarse crowns' does), so a DGM change re-bakes its neighbours' dressings.
  • Instances' matrix mode stays for what moves (tram cars, traffic).
  • Deferred: the BVH and the ground's index stay runtime work in their workers — large, derived, and needed only near the walker.

What the series changes about this plan

Built alone, this plan would have taken PR #156 as it is — triangles in the glTF, ten per cent more bytes — because its only aim would be the thread. The series counts bytes as well, hence tables first. Alone it would also have kept a worker for the builders as the cheap interim (README, Direction 8); with everything placed by the build there is nothing left to hand to one. The one-reader rule exists for 092, the one file a level for 093 (sixteen times the tiles must not be sixteen times seventeen requests), the fixed layouts for 094, and the edge the builders leave behind is where 095 cuts the viewer's package. Until 088 serves the files compressed, the container is pre-gzipped like the packs it replaces.

Findings

(Phase 0 writes the chosen record, the rails' home and the baseline here.)

Previous
Plan 089 [rewrite]: The bakes are type-checked in CI against a baseline that only shrinks
Next
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
Source on GitHub: docs/plans/090-rewrite-dressing-gpu-ready.md
On this page
  • Status
  • Why this matters
  • Current state
  • Commands you will need
  • Scope
  • Where every kind goes
  • Phases
  • Phase 0 — the baseline and two spikes (one PR, nothing visible)
  • Phase 1 — the container and the trees
  • Phase 2 — everything that stands
  • Phase 3 — lines
  • Phase 4 — areas and solids
  • Phase 5 — what is deleted, and the records
  • Test plan
  • Done criteria
  • STOP conditions
  • Maintenance notes
  • What the series changes about this plan
  • Findings