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 047 (spike): "Problem melden" — the crash report with somewhere to go

Executor instructions: This is a design spike, not a build plan. Its deliverable is a short decision note (appended to this file under "Findings") plus, if the gate in step 3 passes, a small prototype on a branch. Do not merge a prototype without the maintainer's answer to the open questions. Honour the privacy constraints below — they are not optional. When done, update this plan's row in docs/plans/README.md.

Drift check (run first): git diff --stat a28de75..HEAD -- app/_components/crash-report.tsx lib/city/crash-trail.ts app/_components/crash-trail.ts lib/docs/routes.ts docs/adr/0001-client-only-static-app.md docs/guide

Status

  • Priority: P3 (direction option, chosen by the maintainer on 2026-10-01)
  • Effort: S (spike) → S (build)
  • Risk: LOW technically; MED for privacy if done carelessly
  • Depends on: 038 step 3 (the crash panel's offer logic) — do 038 first
  • Category: direction
  • Planned at: commit a28de75, 2026-10-01

2026-10-03: ADR 0043 sends the crash trail (never the view) to an error tracker on its own where the build has a DSN, and the card says so. This spike's question is now the view on opt-in and the destination for a deploy without a DSN; offerAsCrash (plan 038 step 3) is in place.

Why this matters

The 2026-09-28…30 memory work was driven by iPhone crashes only the maintainer saw. Since then the viewer keeps a crash trail (boot stages, errors, a lost device, heartbeats with frame rate, GPU and heap estimates) and offers it on the next load — but the panel says "Kopiere den Bericht und schick ihn weiter" without saying where, and no guide page mentions it. A visitor who hits a crash has no way to close the loop. A "Problem melden" action that opens a prefilled report (the trail, and — only if the visitor agrees — the view as a Snapshot) would turn a visitor's crash into a reproducible case for bun run shots, while the site stays a static app with no backend (ADR 0001).

Current state

app/_components/crash-report.tsx (CrashReport): shown when the previous page died in use (or always with ?trail=1); a read-only Textarea with formatTrail(trail), buttons Schließen and Kopieren:

      <p className="text-muted-foreground text-xs">
        Kopiere den Bericht und schick ihn weiter — er hilft, den Absturz zu
        finden.
      </p>

lib/city/crash-trail.ts: Trail holds startedAt, url (path and query), userAgent, backend, screen, events (≤ 40, { t, kind, detail? }) and beats (≤ 12: frames, fps, gpuMB, heldMB, calls, triangles, heapMB, cities, dressings, style, mode, heightM) — no coordinates. formatTrail(trail) renders it as text (a few KB).

lib/docs/routes.ts:17: export const REPO_URL = "https://github.com/mdugue/bridge"; lib/brand.ts: SUPPORT_URL — the pattern for an outbound link: a plain <a>, nothing loaded from the other site until it is clicked.

lib/city/snapshot.ts encodeSnapshot(look, camera, date) → { v, camera, date, look }; camera.epsg is the position. After "Standort" (locate me) or live mode, that position is the visitor's real location. The user guide promises "the location never leaves the device" (docs/guide/en/using-the-viewer.md ≈ :76, DE ≈ :81).

docs/adr/0001-client-only-static-app.md: no backend, no stateful API routes.

Privacy constraints (hard)

  1. Nothing leaves the device without an explicit click, and the visitor sees the exact text before it is sent.
  2. The Snapshot (position) is off by default and offered as a separate, clearly labelled opt-in ("Ansicht mitsenden — enthält den Ort der Kamera"). If locate-me or live mode was used in the crashed session (the trail can record that as an event — add one if it does not), say so next to the checkbox.
  3. The destination must be stated before the click ("öffnet ein öffentliches GitHub-Issue" or "öffnet dein E-Mail-Programm").
  4. The guide's "the location never leaves the device" stays true or is reworded in both languages to "… unless you choose to attach your view to a problem report".

Steps

Step 1: Destinations — evaluate and write down

Compare, in the "Findings" section of this file:

  • GitHub issue prefilled: ${REPO_URL}/issues/new?title=…&body=… (check GitHub's documented query parameters; measure the maximum practical URL length — browsers ~32 k+, GitHub's limit is lower: try bodies of 4, 8 and 16 KB). Needs a GitHub account; the issue is public.
  • mailto: to an address the maintainer chooses (do not invent one — leave a placeholder and list it as an open question); body length limits of common mail clients (~2 KB safe).
  • Copy + link to a short page in /wissen explaining where to send it.

Step 2: Size the report

Measure formatTrail output for a realistic trail (run bun dev, use the viewer for a minute, window.crashTrail.current() in the console, count bytes; then with ?trail=1 on the next load). Decide what to trim for the chosen destination (e.g. beats to the last 6) — a pure function reportBody(trail, snapshot?) in lib/city/crash-trail.ts with tests.

Step 3: Gate — the maintainer's answers

Write the open questions into "Findings" and stop for the maintainer:

  • GitHub issues (public) or e-mail (which address)?
  • Is a GitHub issue template wanted (.github/ISSUE_TEMPLATE/crash.md)?
  • Should the HUD's Erweitert tab also offer "Problem melden" without a crash (with ?trail=1's current trail)?

Step 4 (only after the answers): Prototype

  • reportBody + tests (lengths, trimming, the snapshot only when opted in).
  • In crash-report.tsx: a "Problem melden" link (<a target="_blank" rel="noopener noreferrer">) with the prefilled URL, the opt-in checkbox, and the destination sentence; keep Kopieren.
  • Guide paragraph in both languages (docs/guide/{en,de}/using-the-viewer.md) on the crash panel and the report; a line in docs/rendering.md next to the GPU recovery; an amendment line in ADR 0001 listing what the page stores locally (crash trail ring, style memory, toolbar fold, the recovery Snapshot in session storage).
  • bun run verify → exit 0; the guide-label test from plan 037 passes.

Findings

(Executor: write the comparison, measurements and open questions here.)

Done criteria (spike)

  • "Findings" has the destination comparison with measured URL limits
  • formatTrail sizes measured; trimming rule proposed
  • Open questions listed for the maintainer
  • (After answers) prototype on a branch with tests; privacy constraints 1–4 met

STOP conditions

  • Any design that sends data without a click, or includes the position by default → do not build it.
  • The maintainer has not answered step 3 → stop after step 3.
Previous
Plan 021: /wissen on Astro Starlight instead of a hand-built Next route
Next
Plan 048 (spike): Share a view as a link, and commit the reference views the GPU checks need
Source on GitHub: docs/plans/047-spike-report-a-problem.md
On this page
  • Status
  • Why this matters
  • Current state
  • Privacy constraints (hard)
  • Steps
  • Step 1: Destinations — evaluate and write down
  • Step 2: Size the report
  • Step 3: Gate — the maintainer's answers
  • Step 4 (only after the answers): Prototype
  • Findings
  • Done criteria (spike)
  • STOP conditions