Skip to content

TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110

Open

Description

@timohueser

Status: approved
Part of #3096. One pull request into ground-plan.
Depends on: #3097 (GP0), #3111 (GP1), #3098 (GP2), #3112 (GP3), #3099 (GP4), #3100 (GP5), #3113 (GP6), #3101 (GP7), #3102 (GP8), #3103 (GP9), #3114 (GP10), #3104 (GP11), #3105 (GP12), #3106 (GP13), #3107 (GP14), #3108 (GP15), #3115 (GP16), #3116 (GP17), #3109 (GP18)

TL;DR

Goal: The viewer has one path, the ground plan, with no switch and no old road, stamp, snap or near-water code; the docs describe it; the budgets of the epic's section 15 hold on the GTX and the M1 Pro; and ground-plan has merged into develop.
Problem: Until GP19, every new viewer path runs only behind ground=plan, and the old path (corridors, today's stamp and its snap, the stream ribbons near the eye, culverts, corridor decks, the old placement) stays the default. Two paths double the code, the tests and the pools, and the old path reads none of the plan's rules. The guide and the README still describe corridors.
Decision: First fold the switch: the plan side of every branch, override and option stays, and the other side goes. This changes no pixel of the plan path, and a byte compare of all reference views proves it. Then make the two replacements that no GP item made (building signs and arête rocks test the far stamp's core, not the old cores; far ribbons lose today's culvert cuts), with their changed views named. Then delete every module that no kept path reaches, found by a sweep of the build and the WGSL includes, not by a hand list alone; each kept importer of a deleted file has a decision (table of A.7). Then measure the budgets against develop's head at the merge base, rewrite the guide and the README in one docs: commit, and merge ground-plan into develop with a merge commit after the owner accepts.
Rejected:

  • Keep the old path behind ground=old as a fallback: it keeps 9,000 lines and the corridor pools alive for a case that the plan already covers (a failed cell or a failed bridge shows the far stamp, GP9 section 6).
  • Delete by the epic's list of section 16 alone: the list leaves out the corridor pipeline itself (roads.ts, road-worker.ts, mesh.ts, piece.ts), and a hand list cannot see what a kept module still imports.
  • Rename roads/ or move the looks: it changes the import paths of every look include for no gain. roads/ becomes the home of the way looks.
  • Squash the merge into develop: git history is the archive; each sub-issue's pull request stays readable.
    Systems: trailview
    Contracts: none change in meaning. docs/design/trailview.md: owns must name host/obc-ground-plan/** and the bridge crate (GP1, GP5); GP19 checks it. specs/trailview-features.md: only prose that still names deleted viewer code changes.
    Size: L (deletes about 9,000 lines in roads/, terrain/ and the census, folds overrides in about 15 files, moves about 400 lines of kept helpers and the part pipeline into their readers (table of step A.7), adds under 150 lines (the core test of R1, the fallback test); one guide rewrite; all reference views and both flights measured)

Facts

  • The old path enters the terrain in a few places: terrain/terrain.ts:18-19 (imports Roads, RoadPiece), :222 (new Roads), :449 (roads.update), :500-502 (the snap pass), :576 and :587 (the corridor casters and draw), :890 (held from Roads.write()). engine.ts:330 waits for terrain.roadsLoading in waitForIdle().
  • terrain/stamp.wgsl:6, terrain/audit.wgsl:5 and terrain/water.wgsl:12 include stamp-core.wgsl. It declares the bindings (:14, :37), the record kinds (:47-59, with JUNCTION and CORNER), the buckets (:85-103), the helpers (:180-412) and stamp_at (:444). water.wgsl uses unit_metres, water_lift and crosses from it (GP8, Facts).
  • GP8 adds terrain/far-stamp.wgsl, which includes stamp-core.wgsl for its helpers and declares override FAR_STAMP and stamp_of (far stamp if FAR_STAMP, else stamp_at). GP8 leaves to GP19: delete stamp_at, stamp_of, FAR_STAMP, the snap pass, corners.ts, approaches.ts and the old branches of bins.ts, and fold the helpers that far-stamp.wgsl uses into it (GP8, "Interfaces").
  • GP9 adds the overrides PLAN and BACKSTOP in terrain/terrain.wgsl and PIECE in roads/corridor.wgsl. plan/piece.wgsl includes ../roads/corridor.wgsl and uses corridor_fragment with PIECE = 1 and BAND = 1. BACKSTOP selects the backstop pipeline of debug=owned; it is not the switch (GP9 sections 7, 8, 12).
  • GP5 adds groundPlanOf(search) in view.ts, read once at page start, and the bridge crate obc-ground-plan-bridge in builder/ground-plan-wasm, built into builder/web/src/lib/trailview/plan/pkg. Without the switch, no Plan, no worker and no WASM request exist (GP5 section 8).
  • gpu/wgsl.ts:3 loads every .wgsl file with import.meta.glob(..., eager: true), so the bundle holds every WGSL file and a module graph cannot show a dead one.
  • Workers start as new Worker(new URL('./x.ts', import.meta.url)) (terrain/stamps.ts:59). Vite's build follows these URLs into a chunk per worker; esbuild's bundle does not.
  • The table of step A.7 lists every kept importer of a file to delete, on develop and on the plan path.
  • The plan path reuses the corridor's part code: models in PARTS (roads/parts.ts; GP13, GP15, GP16), drawParts (roads/roads.ts:215), part_vertex and part_caster (corridor.wgsl:185, :203), the MAT and LOOK ids (roads/section.ts:17-19, GP11, GP13, GP15).
  • Far placement runs on the old cores for every node: structures/node.ts:91 builds cores: coresOf(shapes) and cornered from cornerAt of terrain/corners.ts; pointModels (kinds/kind.ts:73, besideWays), the building signs (kinds/building.ts:48, coreAt) and the arête rocks (kinds/arete.ts:30, coreAt) read them. roads/cores.ts (281 lines) imports corners, arms, decks, section and stations. GP17 gives pointModels a plan branch with no besideWays and no beside bits, and leaves the building signs to GP19.
  • besideWays is the only producer of beside bits (instances/points.ts:17). instances/points.wgsl:6 includes ../roads/band.wgsl; its branch at :34-43 (drawn_height, band_face) runs only for a point with beside bits.
  • terrain/culverts.ts (366 lines) shapes today's ribbons near and far: joinCulverts joins short culverts into their stream and buries long ones (:153), standMouths cuts each ribbon at its mouths (:339). A ribbon also stops at a way's mask in the shader (terrain/water.wgsl:158-167). terrain/water-mesh.ts:42 reads only underDeck of waysOf. models/amenities.ts:4 takes the MOUTH_* constants for culvertMouth, which GP15 replaced.
  • roads/looks.wgsl is included by roads/corridor.wgsl:11 and roads/details.wgsl:4, and it includes details.wgsl and track-looks.wgsl (looks.wgsl:8-9). ground/roads.wgsl:83 and terrain/features.wgsl:38 name it only in comments.
  • gpu/include.ts:27 CLIP_DISTANCES swaps in terrain/unknown-clip.wgsl and terrain/water-cut-clip.wgsl. terrain/terrain.ts:924 (terrain/${file}.wgsl) and instances/instances.ts:661 (module(label, path)) call wgsl() with computed paths.
  • On develop, the only kept reader of terrain/town.ts outside bins.ts is ground/rules.ts:8 (KERB).
  • The census: scripts/road-census.ts, test-support/trailview/census.ts (it imports roads/cores, decks, mesh, piece, section, lines 9-15), test-support/trailview/census.test.ts, tests/browser/trailview/census.mjs. scripts/road-meshes.ts:7 imports roads/mesh. roads/mesh.test.ts:111 gates the census counts. The torn-face gate of TrailView G5: a check that fails on torn faces #3085 is on the branch claude/road-g5-torn-faces, not on develop at 4f8b8b255.
  • GP10 adds census.mjs --plan. Only plants-in-water reads the page: a GPU probe of kept_off at the samples of waterSamples (census.mjs:142, census.ts:308) (it needs only bins.ts). objects-on-ways is a Node count over coresOf, coreAt and cornerAt (census.ts:211-219) and never reads the plan path.
  • debug=cracks clears to red (engine.ts:617, view.ts:9). tests/browser/trailview/smoke.test.js:52 uses it for the terrain's own LOD cracks, and skyline.mjs:28 for its sky mask. smoke.test.js:35 asserts terrain.roads.pieces > 0.
  • flights.json:2-4 holds walk (600 frames), valley-drive (1,200) and zoom-out; only walk and drive count (README.md, "Shots and flights").
  • The TrailView README has 794 prose words (cap 800, tools/prose.py:34; tables, code and headings are not prose, :55). The guide docs/content/software/trailview-roads.md has 1,234 words (cap 2,500); its nav entry is docs/content/nav.json:21.
  • cairn.py check (suite ci.cairn, tools/testing/suites.toml:656-658) requires one owner per source file. web.trailview-smoke triggers on builder/web/src/lib/trailview/** (suites.toml:312-318).
  • specs/trailview-features.md:11 lists the readers of the feature tiles; :135 calls the other fields of roads.json "the stamp profile of the engine". data/trailview/README.md:15-16 describes roads.json and waterways.json.
  • Develop takes merge commits.

Design

Invariants

  • I1, the fold changes no pixel. After the fold (step A, items 1 to 8), each view of road-views.json and road-views-top.json without a query gives the same PNG as ground-plan's head before GP19 with &ground=plan. The base is shot twice. Gate per view: the head's PNG is byte-equal to one base shot; or, where the two base shots differ, the count of differing pixels between the head and each base shot is at most the count between the two base shots. Commands in Verification.
  • I1b, named differences only. The replacements R1 and R2 (step A.9) change only building signs, arête rocks and far ribbons at ways. Every view whose PNG on GP19's head differs from its fold shot is listed in the pull request with the replacement that explains it, and is on the slider page.
  • I2, no dead module. After step B, every .ts file under builder/web/src/lib/trailview/ is in the production module graph or is a test of a file that is; every .wgsl file is reached from a root (step B.4) through // #include lines.
  • I3, no old name. No file of the repository names a deleted file, ground=plan, groundPlanOf, FAR_STAMP, stamp_at, stamp_of, the Roads class, RoadPiece, roadsLoading or the snap words, except git history and closed issues.
  • I4, one source per value. No value of data/trailview lives in code (epic section 3). The old constants of bins.ts (SURFACES, PAVED, PATH_HALF, SHOULDER_M) and roads/section.ts go with their readers.
  • I5, a defined fallback. With the plan as the only path, every case that cannot build or draw ends the mesh at R_eff and shows the far stamp (GP9 section 6). A failed start of the bridge is that case for every cell.

Step A: fold the switch

Rule: where a branch, an override, an option or a message field exists only to tell the old path from the plan path, the plan side stays and the other side goes. Where an override selects a pipeline variant on the plan path (BACKSTOP for debug=owned, the casters, the far interior), it stays.

  1. The address. view.ts: delete groundPlanOf. ground=plan in an old address then does nothing: parseView ignores unknown names. plan (off, faces, and the views that GP7 added) and finest (GP9) stay as debug parameters.

  2. The engine. trailview.ts, engine.ts, terrain/terrain.ts: delete the plan option. Terrain always makes Plan, Pieces and the plan layer. waitForIdle() waits for the plan's loading in place of roadsLoading. TerrainStats.roads goes; TerrainStats.plan stays. The HUD always shows GP5's plan line.

  3. The terrain pipelines. terrain/terrain.wgsl: delete override PLAN; the floor branch of vertex_main runs always. grid_vertex(u, level, snap) loses its snap parameter; terrain/drawn-mesh.wgsl loses the snap code (:39-53 on develop) and the snap words. terrain.ts: delete the snap pipeline, its layout L.snap, the snaps texture, snapGroup and its entry in featureGroup; renumber no other binding. Where a binding becomes free, it stays free.

  4. The stamp. far-stamp.wgsl: delete override FAR_STAMP and stamp_of; stamp.wgsl and audit.wgsl call far_stamp_at. Move into far-stamp.wgsl the declarations of stamp-core.wgsl that a kept shader reads (the bindings, Profile, Rules, the record format, the record kinds that bins.ts still writes, the buckets, Along, along, Stamp, and the helpers). water.wgsl includes far-stamp.wgsl in place of stamp-core.wgsl: the bindings are the same, and WGSL ignores the far stamp's unused functions. Delete stamp-core.wgsl with stamp_at, JUNCTION, CORNER, JOIN_A, JOIN_B, the walk and driveway bits, the shelf, the bench, the ditch, the corner rule and the junction rule. A constant that only deleted code reads goes.

  5. The stamp worker. terrain/stamps.ts, terrain/stamp-worker.ts, terrain/bins.ts: delete the plan message field and parameter. bins.ts keeps only GP8's plan branch: delete approaches, junctionPlanes, townPieces, the JUNCTION and CORNER records, the JOIN caps, profileTable's old form and the viewer's own sidewalk decision (bins.ts:472 on develop; the plan reads the bake's walk, GP4). terrain/town.ts loses the sidewalk and paving parts; the sweep of B.4 and the export search of B.5 decide the rest (on develop only KERB has a kept reader, ground/rules.ts:8).

  6. The corridors. Delete Roads and its worker. In plan/piece.wgsl, inline what it uses of roads/corridor.wgsl with PIECE = 1 folded: corridor_fragment becomes piece_fragment, CorridorOut becomes PieceOut, and part_vertex, part_caster and PartIn come with their constants (table of A.7). BAND is an override of ground/look.wgsl:40 that the terrain also compiles, so the pieces pipeline keeps passing the constant BAND: 1. plan/piece.wgsl itself includes ../ground/look.wgsl and ../roads/looks.wgsl, which corridor.wgsl included for it. The corridor vertex stage, the corridor's band (band.wgsl, band_dive), the paint dither and the detail fade go. Delete roads/corridor.wgsl. terrain/features.wgsl: paint_share no longer reads masks.held; GP10's fade decides where the paint draws. masks.held and its write at terrain.ts:890 go.

  7. Water, bridges, placement. The near-eye branches of terrain/water-mesh.ts and terrain/water.wgsl (the ribbons that GP14 replaces within the range), the corridor-deck hand-over of structures/bridges.ts (GP12: WALK_INSIDE_M, the corridor span, decksOf), the culvert mouths (roads/mouths.ts, culvertMouth), the street lamps of roads/lamps.ts and the point placement by cores (besideWays): each keeps the side that GP12, GP14, GP15 and GP17 made the plan path's. Far water and far bridges stay as those items left them. The beside branch of instances/points.wgsl (:34-43), its include of band.wgsl, Point.beside, besideBits and BESIDE_STEP_M go here too: on the plan path no point has beside bits (GP17), so the branch never runs, and I1 covers the fold.

    Kept importers. Each import of a file to delete has one decision. Rows with a line number are on develop; the others are the plan path's readers (GP9 to GP16). Plan step 1 checks each row on ground-plan, and a row that does not fit is the gap rule (B.3).

    Kept importer Takes Decision
    structures/mesh.ts:4 stationsOf, strokeMetres, Station Move them with STEP_M, SAME_M and CUT into structures/mesh.ts (about 70 lines); Station.paint (type Paint of marks.ts) goes. If GP13 left a second reader, they move to structures/stations.ts.
    structures/bridges.ts:6-7 isPaved, onDeck, PARAPET_M, teesOf, wider, KERB_RISE_M; decksOf Move the first five with deckHalf into bridges.ts (about 60 lines); KERB_RISE_M from terrain/bins.ts; decksOf goes (GP12).
    structures/node.ts:3,9,10,16,17 coresOf, cornerAt, deckHalf, culvertMouths, streetLamps Build.cores and Build.cornered go (R1); deckHalf from bridges.ts; culvertMouths goes (GP15); streetLamps goes (GP17).
    kinds/kind.ts:12 besideWays, Beside, Cores, Stand, Taken pointModels keeps GP17's plan branch; Stand and Taken move into kind.ts (under 10 lines) if that branch reads them, else they go.
    kinds/kind.test.ts:9-10 coresOf, streetLamps The cases of besideWays and rule lamps go; GP17's plan-branch cases stay.
    kinds/road.ts:2 lampKind Move lampKind (the lamp model and its light, about 15 lines) into kinds/road.ts, which GP17's road/lamp points use.
    kinds/stream.ts:2, models/amenities.ts:4 mouthKind; MOUTH_* Go with culvertMouth; GP15's objects draw the mouths.
    kinds/building.ts:6, kinds/arete.ts:6 coreAt R1 (A.9).
    instances/points.ts:5 Beside Goes with beside (above).
    terrain/water-mesh.ts:11 waysOf (underDeck only) Move underDeck with DECK_MARGIN_M into water-mesh.ts (about 15 lines).
    terrain/water-mesh.test.ts:3 shoreOf Its cases test the near ribbons and go with them.
    terrain/bins.ts:9-11, bins.test.ts:12-13 approaches, halfAt, partnersOf, boxOf, cornersOf, joinCulverts, standMouths The old branches that read them go (A.5); joinCulverts and standMouths go (R2). If GP8's plan branch reads halfAt or partnersOf, they move into bins.ts (about 30 lines).
    test-support/trailview/census.ts:9-15 roads/* "Census": only waterSamples stays.

| plan/piece.wgsl (GP9, GP13) | part_vertex, part_caster, PartIn of corridor.wgsl | Inline them (A.6). |
| GP9's piece renderer (GP13) | drawParts, the part pipelines, partMeshes() of roads/roads.ts | Move into the piece renderer if GP13 did not. |
| GP13, GP15, GP16 | PART, PARTS, partMeshes | git mv to plan/parts.ts with GP13's parts.test.ts; the constants they read from tracks.ts move into it. |
| roads/parts.ts, its test | lookWord, PART_FINE, PART_TURN, PART_GRADE, FINE_SHIFT of piece.ts | Move into plan/parts.ts. The crate packs the instances (GP13), so PieceBuilder goes. |
| GP11, GP13, GP15, plan/parts.ts | MAT, LOOK, CF, BED_M and the look constants of section.ts | Move into roads/looks.ts (about 30 lines, beside the same ids in looks.wgsl) with GP11's id test; the rest goes. |

  1. Scripts and tests. shoot.mjs, flight.mjs, census.mjs and every committed views or flights file: delete ground=plan from every default and query. --query stays as a general option.

Items 1 to 8 end with the I1 compare (Verification). A pixel that differs is a fault of the fold. Fix it before step A.9; never accept it as noise.

  1. The replacements. Two behaviours of deleted files have no plan-path replacement in GP1 to GP18. GP19 owns them, in one commit after the I1 compare:
    • R1, the far stamp's core for signs and rocks. Build.cores and Build.cornered go. kinds/kind.ts gets onWay(ways, x, y, past): true where the point lies within h + past metres of a segment of a road or path line of Build.ways, with h the line's half-width from GP8's plan branch (the far stamp's paint half). building.ts:48 and arete.ts:30 call it in place of coreAt and cornered. The far stamp has no corner fill (GP8), so nothing replaces cornered. About 15 lines with a unit test.
    • R2, far ribbons without culvert cuts. joinCulverts, standMouths, waysOf and terrain/culverts.ts go. Past the range, a ribbon is the stream line as features() gives it: a short culvert is not joined into its stream, and no ribbon is cut at a mouth. The shader's mask stop (water.wgsl:158-167) still ends each ribbon at a way. Within the range GP14 and GP15 draw the water, so R2 changes only ribbons past it (streams-under-far, stream-lake-far). Question 2 asks the owner to accept it.

Step B: delete what no kept path reaches

  1. Delete the epic's list (section 16, with band.wgsl, lamps.ts and terrain/culverts.ts) after the moves of A.7, the census parts of "Census", and the torn-face gate of TrailView G5: a check that fails on torn faces #3085 if it reached develop. Delete also the corridor pipeline, which the list leaves out: roads/roads.ts, road-worker.ts, mesh.ts, piece.ts, marks.ts, section.ts and corridor.wgsl after their kept parts move (A.7), and details.ts and tracks.ts where GP13 and GP16 replaced them. parts.ts moves to plan/ (A.7). Each test file of a deleted module goes with it.
  2. The move rule. Where a kept module imports a small pure function or a constant from a deleted file, move only that function into the kept module that uses it (if two use it, into the lower one in the import graph). The table of A.7 applies this rule. A moved function takes its test with it. No deleted module stays for one constant.
  3. The gap rule. The table of A.7 and A.9 decide every import known at design time. Where ground-plan shows another kept path that needs a behaviour of a listed file that no GP item replaced, do not keep the file and do not design a replacement here: report to the owner the import, the behaviour and the GP item that owns it. GP19 continues when that item's fix has merged into ground-plan.
  4. The sweep. Build the production page with source maps into a scratch directory (in builder/web: VITE_PLANNER_CONFIG="$(cat tests/browser/trailview/fixture/config.json)" npx vite build --mode trailview --sourcemap --outDir <scratch>), collect the sources of every .map, and list each non-test .ts file under src/lib/trailview/ that is not in them. For WGSL, the roots are: every literal wgsl('…') argument in a live .ts file; every path that a computed call builds, listed by hand from its callers (each file of terrain/terrain.ts:924, each path of instances/instances.ts:661); and the values of CLIP_DISTANCES (gpu/include.ts:27). The script also lists each wgsl( call whose argument it cannot resolve, so a new computed call cannot hide a file. List each .wgsl file that no root reaches through // #include lines (transitively). Every listed file is dead: delete it, or say in the pull request why it stays (a debug tool that a script uses). Repeat until both lists are empty. The scan is a scratch script, not a committed guard.
  5. The exports. npm run check and npx vitest run src/lib/trailview find every dangling import. An export that no file imports any more goes (search each export of the changed files with grep -rn).

What stays in roads/: looks.wgsl, track-looks.wgsl, details.wgsl and looks.ts, their ids (epic: "the looks stay"; looks.wgsl:9 includes details.wgsl). The README's row says so.

Rule tables

A field of data/trailview/*.json that no kept reader reads (the viewer, the crate, the bake) goes, with its line in data/trailview/README.md. Find the readers with grep -rn '"<field>"\|\.<field>\b' over builder/web/src, host/obc-ground-plan, host/obc-trailview-features and host/obc-data-steps. A field that host/obc-data-steps/src/planner.rs passes as an option of the feature step stays, so the step's options and its cache key do not change, and planner-map-baking is not touched. GP19 adds no rule-table field.

Census

The census goes with the old code (epic section 14), except plants-in-water, because it is the only count that reads the drawn plan path (GPU, census.mjs:142). The census keeps waterSamples and the code that writes and probes its samples; the rest of census.ts, census.test.ts and scripts/road-census.ts goes. objects-on-ways goes: it counts the old cores, and check 6 proves point objects. gaps, short-sidewalks, tears and lifts read the corridor faces, so they go, with roads/mesh.test.ts's gate and scripts/road-meshes.ts. census.mjs --plan folds into the default. Before the deletion, run the census once on GP19's head; its counts go in the pull request next to GP0's baseline.

debug=cracks stays

GP9 lists the deletion of debug=cracks for GP19. It stays: smoke.test.js:52 counts the terrain's own LOD cracks with it, and skyline.mjs:28 uses its red clear colour as the sky mask. debug=owned and flight.mjs --owned N count the plan's cracks.

A new test for the fallback

With the plan as the only path, a failed bridge start must not break the page. One smoke test, not @gpu, in tests/browser/trailview/smoke.test.js: the village view with the request of the plan's WASM file aborted (page.route). After waitForIdle(), the page has no page error, the HUD's ! line names the bridge's start error, stats().plan.pieces is 0, and the probe gives a height. The old test at smoke.test.js:35 asserts terrain.plan.pieces > 0 in place of terrain.roads.pieces > 0.

Budgets

All GPU runs on the GTX 1660 SUPER, flight.mjs --gpu (clock held), under flock /tmp/trailview-gpu.lock, three runs each. A flight's number is the median over the three runs of each pass's median.

  • The base. Develop's head at the merge base of GP19's head and develop, built and flown in a worktree on the same day as the head. Only that base runs GP19's code for everything but ways, water and ownership. GP0's record shows only the trend.
  • Frame, gate F1: for walk and valley-drive, the sum F of all pass medians (the stamp and ground passes amortized) on GP19's head is at most F on the base. This is the epic's first budget.
  • Frame, gate F2: F on GP19's head minus F_none is at most 0.8 ms, where F_none is the base's flight with no ways if GP0 added a switch for it, else the base's F minus the base's corridor, band and stamp medians (GP0's rule).
  • Cracks: flight.mjs --gpu --owned 10 on walk and valley-drive, and again with &finest=17 in the query: every cracks and inside value is 0. flight.mjs --gpu --surface 10 (GP10): 0 red pixels.
  • Cell build: GP7's native timing command over the fixture and GP5's timing page in Chrome on the GTX box, on GP19's head. Gate: the owner's gates of GP7, and on one owner run of the page on the iPhone, GP7's iPhone gate.
  • Jump: the view near the eye is complete within 2 s of a jump on the GTX box: plan.ready (GP9, stats.ready of GP5) for each view of road-views.json, as shoot.mjs prints it after a cold load; gate: the largest at most 2,000 ms. A cold load is an upper bound of a jump. A view that fails only by its cold terrain load is measured after a jump from a nearby view (GP9's method).
  • Memory: at the end of each flight, from stats().plan: use and capacity of the piece vertex and index pools, the floor slots, the object pool, the plan layer pool and the worker heap. Gate: pieces, floors and objects within 27 MiB (vertices) and 20 MiB (indices), the worker heap within 55 MiB, the plan layer pool as GP10 sized it. Report the total GPU pool memory against the base.
  • WASM: the size guard of GP5 passes in CI; report the raw and gzip bytes of the bridge.
  • Tiles: the sum of the gzip bytes of tests/browser/trailview/fixture/features/ per zoom, on develop's head and on GP19's head. Gate: the total grows by less than 2 %.
  • Bake: the fixture's feature bake, timed as GP0 timed it, three runs on develop's head and three on GP19's head, under nice. Gate: the median on GP19's head is less than 1.10 times the base's. The production rebake is the owner's later check over a whole region.
  • M1 Pro: the owner flies the walk and valley-drive flights on the M1 Pro on develop's head and on GP19's head, as at the earlier checkpoints. Gate: the owner's pass, written into the pull request.

A gate that fails stops the merge into develop. The implementer reports the passes, the cause it found, and the GP item that owns the cause; GP19 does not tune a rule or a pool for one flight.

Docs (one docs: commit)

  • Guide docs/content/software/trailview-roads.md, rewritten: title "How TrailView draws roads and water", nav title "TrailView roads and water" (nav.json:21), same path. Sections: why one ground plan (the four derivations of TrailView roads: why the road system tears, and a planar road map #3095 in one paragraph, without the issue number); faces, owners and surfaces; heights after faces, and why walls stand only where a slope has no room; the mesh, the strip and the floors, and why the terrain needs no hole and no discard; the far stamp and the handover at the end of the range; readers on the plan layer; placement; a region is rules, not code; frame time, memory and the phone (level 17 as the finest level). Each claim links its code with [text](src:path): the crate's stage modules, plan/pieces.ts, plan/piece.wgsl, terrain/far-stamp.wgsl, terrain/terrain.wgsl, the rule tables, and specs/trailview-features.md. No spec table is restated, and no date, issue number or measurement appears. At most 2,000 words (the cap is 2,500).
  • README builder/web/src/lib/trailview/README.md: the Layout table gets a plan/ row (the plan client, the worker and the bridge's output, the pieces, the floors, the plan layer, the debug draw) and new roads/ and terrain/ rows (the far stamp, no corners, no culverts). "The address" gains plan, finest and debug=owned. "Shots and flights" keeps only the plants-in-water row of the census table, and gains --owned N, --surface N, --query Q and the timing page. The prose stays at most 800 words.
  • Crate README host/obc-ground-plan/README.md (GP1): checked; it changes only where it names the switch or a deleted file.
  • Contracts: specs/trailview-features.md:11 names the crate's decoder among the readers, if GP1 did not; :135 names the readers of the cross-section table, if GP18 did not. docs/design/trailview.md: owns names host/obc-ground-plan/** and builder/ground-plan-wasm/**, if GP1 and GP5 did not. data/trailview/README.md: the lines of removed fields.

Merge into develop

  1. GP19's pull request merges into ground-plan after its review and green CI.
  2. ground-plan takes in develop (a merge). A develop change to a file that GP19 deleted: a fix of the old path is dropped and listed in the merge commit's message; a change to a moved helper is ported to its new place. If the merge changes a file under builder/web/src/lib/trailview/**, data/trailview/** or host/obc-ground-plan/** (git diff --stat), the merged head is measured again before the owner accepts: the flagged views and the views that the changed files reach, compared with GP19's head as in I1; the smoke; F1 and F2 (three runs). The pull request into develop shows them.
  3. A pull request ground-plan → develop holds the acceptance record (Verification) and the line Requirements: none (or the TrailView requirements that the owner names). CI runs on it.
  4. It merges with a merge commit, never a squash, only after the owner accepts the views and the budgets in the pull request or in chat. CodeRabbit threads must be resolved; agents may not resolve them, so the owner does.
  5. After the merge: close GP19, and tell the owner that the production rebake can start. The epic stays open until the owner's production rebake is published.

Edge cases

  1. A view that the owner flags in the acceptance: GP19 does not merge into develop and does not fix the look in GP19. The fix goes into a pull request into ground-plan under the GP item that owns the rule, proven over the whole fixture. Then GP19 shoots the affected views again, and the owner looks again.
  2. A kept path that still needs an old behaviour: the gap rule of step B.
  3. An old address with ground=plan: ignored, the view draws.
  4. Fewer storage buffers: GP9's counts hold (7 of 8); step A frees the snap texture's binding and adds none.
  5. The bridge fails to start or a cell fails: I5, and the new smoke test.
  6. Quality below level 17: no piece draws; the far stamp shows the ways (GP9 section 10). Shot at finest=16 (Pictures).
  7. The phone's path: level 17 is the finest level at the first quality step (terrain/terrain.ts:795). Shot at finest=17 (Pictures), counted with --owned.
  8. Cell and tile borders, levels, steep ground, empty cells: GP19 changes no rule; the checks of section 14 pass in CI on GP19's head.
  9. A WGSL file that only a test or a script reads (check-wgsl.mjs validates every file): the sweep lists it; it goes unless a kept script uses it.
  10. The fixture's feature tiles: GP19 does not rebake them and changes no format; a kind whose only reader goes stays in the tiles.

Plan

  1. Branch claude/gp19-only-path from ground-plan after the develop merge of wave 12. Check each row of the table of A.7 against ground-plan (grep -rn of each import); a row that does not fit is the gap rule, before any code. Build the page (npm run pretest:trailview in builder/web/tests/browser) and shoot both views files twice with --query '&ground=plan', the base of I1, into /media/timo/OSM1/tmp/ground-plan/gp19/base-1/ and base-2/. Fly walk and valley-drive with the same query, three runs: the plan path's numbers before the fold.
  2. Step A.1 and A.2: view.ts, src/trailview.ts, engine.ts, terrain/terrain.ts.
  3. Step A.3: terrain/terrain.ts, terrain.wgsl, drawn-mesh.wgsl, features.wgsl.
  4. Step A.4; delete terrain/stamp-core.wgsl.
  5. Step A.5; delete terrain/corners.ts, terrain/approaches.ts.
  6. Step A.6; delete roads/corridor.wgsl.
  7. Step A.7, by its table.
  8. Step A.8: delete ground=plan in the scripts and the views and flights files. Commit the fold. Shoot both views files on it into .../gp19/fold/ and compare with step 1's PNGs (I1). Fix every difference. Then step A.9 (R1, R2) in its own commit; the final pictures of Verification on GP19's head are compared with fold/ (I1b).
  9. Step B: delete the files of B.1; run the sweep of B.4 until it lists nothing; delete unused exports.
  10. Tests: delete the tests of deleted modules; smoke.test.js: the assertion at :35 and the new fallback test; the census per "Census"; roads/mesh.test.ts and scripts/road-meshes.ts go. Run the census once before its reduction and keep the counts for the pull request.
  11. data/trailview/*.json and data/trailview/README.md: remove the fields that no reader reads.
  12. cargo fmt --all; the checks of Verification; obc suites check.
  13. The docs: commit: the guide, nav.json, the README, the crate README, data/trailview/README.md, specs/trailview-features.md, docs/design/trailview.md as "Docs" says. python3 docs/build_docs.py --check-links, obc prose --check.
  14. The budgets and the pictures of Verification: one slider page, and the live viewer for the owner.
  15. The pull request into ground-plan: Mode: change #<GP19>, Requirements: none, "Public docs changed: yes, in the docs: commit", the record. Review, fixes, merge.
  16. "Merge into develop", steps 2 to 5.

Files

  • builder/web/src/lib/trailview/roads/: delete: every file but looks.wgsl, track-looks.wgsl, details.wgsl and looks.ts, with their tests; the corridors, the sweep, the junction plan and the old placement. roads/looks.ts: create: the MAT, LOOK and CF ids of section.ts.
  • builder/web/src/lib/trailview/plan/parts.ts (moved from roads/), parts.test.ts, GP9's piece renderer: change: the part models, lookWord, the instance constants, drawParts (table of A.7).
  • builder/web/src/lib/trailview/terrain/stamp-core.wgsl, corners.ts, approaches.ts, culverts.ts and their tests: delete: today's stamp, corners, approaches and culverts.
  • builder/web/src/lib/trailview/terrain/far-stamp.wgsl: change: the helpers of stamp-core.wgsl that kept shaders read; no FAR_STAMP, no stamp_of.
  • builder/web/src/lib/trailview/terrain/stamp.wgsl, audit.wgsl, water.wgsl: change: include far-stamp.wgsl, call far_stamp_at; no snap entry.
  • builder/web/src/lib/trailview/terrain/terrain.ts, terrain.wgsl, drawn-mesh.wgsl, features.wgsl: change: no switch, no snap, no corridors, no held.
  • builder/web/src/lib/trailview/terrain/bins.ts, stamps.ts, stamp-worker.ts, town.ts, water-mesh.ts: change: the plan branch only.
  • builder/web/src/lib/trailview/plan/piece.wgsl: change: the piece fragment and the part vertex stages inlined from corridor.wgsl.
  • builder/web/src/lib/trailview/structures/bridges.ts, node.ts, mesh.ts, builder/web/src/lib/trailview/kinds/*.ts, models/amenities.ts, instances/points.ts, instances/points.wgsl: change: no import from deleted files; moved helpers (table of A.7); onWay (R1); no beside; purpose comments that name corridors (kinds/road.ts:1) state the present behaviour.
  • host/obc-trailview-features/src/bake.rs:28: change: the comment names terrain/culverts.ts; it states the rule without the deleted file.
  • builder/web/src/lib/trailview/view.ts, engine.ts, hud.ts, builder/web/src/trailview.ts: change: no switch.
  • builder/web/tests/browser/trailview/smoke.test.js: change: the plan assertion and the fallback test.
  • builder/web/tests/browser/trailview/shoot.mjs, flight.mjs, the views and flights files: change: no ground=plan.
  • builder/web/scripts/road-meshes.ts: delete. builder/web/scripts/road-census.ts, builder/web/test-support/trailview/census.ts, census.test.ts, builder/web/tests/browser/trailview/census.mjs: change: only plants-in-water, per "Census".
  • data/trailview/*.json, data/trailview/README.md: change: fields that no reader reads.
  • docs/content/software/trailview-roads.md: change: rewritten for the ground plan. docs/content/nav.json: change: the title.
  • builder/web/src/lib/trailview/README.md: change: layout, address, shots and flights. host/obc-ground-plan/README.md: change only if it names the switch.
  • specs/trailview-features.md, docs/design/trailview.md: change only where "Docs" says.

Verification

  • Checks:
    • obc test -p obc-ground-plan and obc exec cargo clippy -p obc-ground-plan --all-targets -- -D warnings: the checks of section 14 (1 to 7) pass over every fixture cell, the native and WASM bytes included.
    • In builder/web: npx vitest run src/lib/trailview (every kept unit test passes; no test imports a deleted file), npm run check (no dangling import or type), npm run check:wgsl (every kept WGSL file composes with its includes).
    • In builder/web/tests/browser: npm run test:trailview -- --grep-invert @gpu (the smoke, the new fallback test); flock /tmp/trailview-gpu.lock npm run test:trailview on the GTX box (the @gpu tests, GP9's owned test among them). CI skips @gpu; the pull request reports the local run.
    • I1: for each view, cmp base-1/V.png fold/V.png and cmp base-2/V.png fold/V.png; gate: one is equal. For a view where cmp base-1/V.png base-2/V.png fails, a scratch script (pixdiff.mjs A B: pixels whose RGBA differ, decoded in Chromium) gives d(base-1, base-2), d(fold, base-1) and d(fold, base-2); gate: both fold counts are at most the base count.
    • I1b: the same cmp of fold/ against the final head shots; every view that differs is listed with R1 or R2 and is on the slider page.
    • I2: the sweep of step B.4 prints two empty lists and no unresolved wgsl( call.
    • I3: git grep -nE 'ground=plan|groundPlanOf|FAR_STAMP|stamp_at|stamp_of|roadsLoading|RoadPiece|RoadStats|new Roads\b|stamp-core|corners\.ts|approaches\.ts|culverts\.ts|road-meshes|besideWays|coresOf' -- builder/web docs specs data/trailview/README.md host/obc-trailview-features host/obc-ground-plan prints nothing.
    • obc suites check (the suites still name existing files and commands), python3 tools/cairn/cairn.py check (one owner per file), python3 docs/build_docs.py --check-links, obc prose --check.
    • obc test affected --base origin/ground-plan for GP19's pull request; for the pull request into develop, obc test affected --base origin/develop --dry-run prints the plan, and CI runs it.
  • Measurements: the budgets of Design, with the commands there: F1 and F2 (with p95 and the per-pass table: base, head, step 1's plan-path numbers, GP0's record), the crack and surface counts, cell build times, plan.ready, memory, WASM bytes, tile bytes, bake time, the owner's M1 Pro verdict. Cost: about 25 minutes of flights, 40 minutes of shots and three fixture bakes per build; the pull request states the real times.
  • Pictures: flock /tmp/trailview-gpu.lock node trailview/shoot.mjs --gpu --views FILE --width 1920 --height 960, from builder/web/tests/browser, on one slider page, before (develop's head) and after (GP19's head), with the debug tool's picture of the place beside each -top view:
    • Every view of road-views.json (eye height and the near views) and every view of road-views-top.json (from above, pitch −89). The owner looks for no torn, folded or sliver face, crack or gap; junctions, mouths, sidewalk ends, bends, walls, bridges, tunnels, railways, steps, water and objects as in a real street; the looks of develop.
    • v01 to v17 at eye height and their -top views with --query '&finest=17' (the phone's path), and v12-good-town-junctions with &finest=16 (no piece, the far stamp alone, no hole).
    • GP10's handover-views.json: no jump of a corner, sidewalk, wall or slope between 540 and 640 m.
    • Every picture at 2×, judged against a real street; the implementer looks at each before it reports.
    • The live viewer on timosPC: the owner flies the fixture in a GPU Chromium window.

Done when

  • With no query, the viewer draws the ground plan; no switch, old corridor, old stamp, snap or near-eye ribbon exists in the repository (I3).
  • The I1 compare shows no difference beyond the base's own noise, and every difference of I1b is named.
  • The sweep of step B.4 lists no dead .ts or .wgsl file (I2).
  • The checks of Verification pass locally and in CI, and the @gpu tests pass on the GTX box.
  • The budgets F1, F2, cracks, cell build, jump, memory, WASM, tiles and bake hold, and the owner's M1 Pro flight passes.
  • The guide describes the ground plan, the README and the contracts name no deleted file, and the docs live in their own docs: commit.
  • GP19's pull request has merged into ground-plan after its review.
  • The owner accepts the reference views and the budgets, and ground-plan has merged into develop with a merge commit.
  • GP19 is closed, and the owner knows that the production rebake can start.

Out of scope

  • A change to any rule, look, height, mesh or placement: the GP item that owns it (edge case 1).
  • The bake and the fixture's tiles: GP18.
  • The production rebake and its publication: the owner, after the merge.
  • The body of docs/design/trailview.md: cairn document, which the owner runs; GP19 checks only owns.
  • The iOS app and its static library of the crate.

Questions for the owner

Owner decision (2026-11-03): every recommendation in this section is accepted.

  1. The census: the epic deletes it whole. GP10 and GP14 gate plants-in-water on the plan path, and no other check proves on the drawn result that no plant stands in water. Recommendation: keep only plants-in-water; objects-on-ways and the four corridor counts go.
  2. Far ribbons (R2): past the range, a ribbon loses today's culvert joins and mouth cuts; the mask stop still ends it at a way. The alternative keeps joinCulverts and standMouths (about 230 lines, with their own corner shapes). Recommendation: accept R2; a 1 m stream is about one pixel wide past 560 m, and the views streams-under-far and stream-lake-far show the result.
  3. The guide's title: "How TrailView draws roads and water" and nav title "TrailView roads and water", at the same path. Recommendation: accept; the page then also covers water, which the plan draws near the eye.

Epic note: section 16 does not list the corridor pipeline itself (B.1). GP19 deletes it by the sweep, and moves the piece's fragment and the part pipeline into plan/ (A.7).
Epic note: section 14 says the census goes in GP19; question 1 proposes to keep plants-in-water.
Epic note: section 16 deletes terrain/culverts.ts and roads/cores.ts, but far ribbons and far building signs and arête rocks still read them, and no GP item replaces that. GP19 owns both (R1, R2).

Review notes

  • Kept (partly): band.wgsl deletion changes point heights: no plan-path point has beside bits (GP17), so points.wgsl:34-43 never runs; the fold is in A.7 under I1.
    Epic note: GP9 leaves the deletion of debug=cracks to GP19. It stays, because the terrain's own crack test (smoke.test.js:52) and skyline.mjs:28 use it.

Activity

  1. timohueser commented on Nov 3, 2026

    @timohueser
    OwnerAuthor

    Deviation from GP0 (PR #3118), for this sub-issue's frame measurements: the viewer has no GPU timer of its own for corridors, band or water; all draw inside the one terrain pass, and the viewer has no switch for "ways off". GP0 measured ways-off with a scratch copy of flight.mjs that skips the corridors' draw and cast (see the baseline comment on #3096). The 0.8 ms gate compares the terrain + stamp passes with and without ways. Alternate the runs and correct for clock drift (the lighter frame drops the GPU clock by 2–7 %). If this sub-issue needs per-pass numbers for the new path, add its own timestamps or a switch.

  2. timohueser commented on Nov 3, 2026

    @timohueser
    OwnerAuthor

    Open owner question from GP0 (baseline comment on #3096): develop's water draw near the eye costs 0.125 ms (walk) and 0.073 ms (drive) on the GTX, measured with the alternate-frame toggle. The epic's frame budget charges ways, water and ownership on the new side but compares them only with develop's corridors, band and stamp (0.27 ms walk, 0.42 ms drive). Until the owner decides, report both: the reference without and with develop's water.

  3. timohueser commented on Nov 15, 2026

    @timohueser
    OwnerAuthor

    Owner decision, 2026-11-15 (his note on the merge document for ground-plan → develop, #3491):

    why switched off? We can switch all improvements on and in fact remove all the wiring to switch them off, that's not needed!

    What this means for this step:

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions