Repository navigation
Description
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=oldas 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:ownsmust namehost/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 inroads/,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(importsRoads,RoadPiece),:222(new Roads),:449(roads.update),:500-502(the snap pass),:576and:587(the corridor casters and draw),:890(heldfromRoads.write()).engine.ts:330waits forterrain.roadsLoadinginwaitForIdle(). terrain/stamp.wgsl:6,terrain/audit.wgsl:5andterrain/water.wgsl:12includestamp-core.wgsl. It declares the bindings (:14,:37), the record kinds (:47-59, withJUNCTIONandCORNER), the buckets (:85-103), the helpers (:180-412) andstamp_at(:444).water.wgslusesunit_metres,water_liftandcrossesfrom it (GP8, Facts).- GP8 adds
terrain/far-stamp.wgsl, which includesstamp-core.wgslfor its helpers and declaresoverride FAR_STAMPandstamp_of(far stamp ifFAR_STAMP, elsestamp_at). GP8 leaves to GP19: deletestamp_at,stamp_of,FAR_STAMP, the snap pass,corners.ts,approaches.tsand the old branches ofbins.ts, and fold the helpers thatfar-stamp.wgsluses into it (GP8, "Interfaces"). - GP9 adds the overrides
PLANandBACKSTOPinterrain/terrain.wgslandPIECEinroads/corridor.wgsl.plan/piece.wgslincludes../roads/corridor.wgsland usescorridor_fragmentwithPIECE = 1andBAND = 1.BACKSTOPselects the backstop pipeline ofdebug=owned; it is not the switch (GP9 sections 7, 8, 12). - GP5 adds
groundPlanOf(search)inview.ts, read once at page start, and the bridge crateobc-ground-plan-bridgeinbuilder/ground-plan-wasm, built intobuilder/web/src/lib/trailview/plan/pkg. Without the switch, noPlan, no worker and no WASM request exist (GP5 section 8). gpu/wgsl.ts:3loads every.wgslfile withimport.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_vertexandpart_caster(corridor.wgsl:185,:203), theMATandLOOKids (roads/section.ts:17-19, GP11, GP13, GP15). - Far placement runs on the old cores for every node:
structures/node.ts:91buildscores: coresOf(shapes)andcorneredfromcornerAtofterrain/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) importscorners,arms,decks,sectionandstations. GP17 givespointModelsa plan branch with nobesideWaysand nobesidebits, and leaves the building signs to GP19. besideWaysis the only producer ofbesidebits (instances/points.ts:17).instances/points.wgsl:6includes../roads/band.wgsl; its branch at:34-43(drawn_height,band_face) runs only for a point withbesidebits.terrain/culverts.ts(366 lines) shapes today's ribbons near and far:joinCulvertsjoins short culverts into their stream and buries long ones (:153),standMouthscuts 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:42reads onlyunderDeckofwaysOf.models/amenities.ts:4takes theMOUTH_*constants forculvertMouth, which GP15 replaced.roads/looks.wgslis included byroads/corridor.wgsl:11androads/details.wgsl:4, and it includesdetails.wgslandtrack-looks.wgsl(looks.wgsl:8-9).ground/roads.wgsl:83andterrain/features.wgsl:38name it only in comments.gpu/include.ts:27CLIP_DISTANCESswaps interrain/unknown-clip.wgslandterrain/water-cut-clip.wgsl.terrain/terrain.ts:924(terrain/${file}.wgsl) andinstances/instances.ts:661(module(label, path)) callwgsl()with computed paths.- On develop, the only kept reader of
terrain/town.tsoutsidebins.tsisground/rules.ts:8(KERB). - The census:
scripts/road-census.ts,test-support/trailview/census.ts(it importsroads/cores,decks,mesh,piece,section, lines 9-15),test-support/trailview/census.test.ts,tests/browser/trailview/census.mjs.scripts/road-meshes.ts:7importsroads/mesh.roads/mesh.test.ts:111gates the census counts. The torn-face gate of TrailView G5: a check that fails on torn faces #3085 is on the branchclaude/road-g5-torn-faces, not on develop at4f8b8b255. - GP10 adds
census.mjs --plan. Onlyplants-in-waterreads the page: a GPU probe ofkept_offat the samples ofwaterSamples(census.mjs:142,census.ts:308) (it needs onlybins.ts).objects-on-waysis a Node count overcoresOf,coreAtandcornerAt(census.ts:211-219) and never reads the plan path. debug=cracksclears to red (engine.ts:617,view.ts:9).tests/browser/trailview/smoke.test.js:52uses it for the terrain's own LOD cracks, andskyline.mjs:28for its sky mask.smoke.test.js:35assertsterrain.roads.pieces > 0.flights.json:2-4holdswalk(600 frames),valley-drive(1,200) andzoom-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 guidedocs/content/software/trailview-roads.mdhas 1,234 words (cap 2,500); its nav entry isdocs/content/nav.json:21. cairn.py check(suiteci.cairn,tools/testing/suites.toml:656-658) requires one owner per source file.web.trailview-smoketriggers onbuilder/web/src/lib/trailview/**(suites.toml:312-318).specs/trailview-features.md:11lists the readers of the feature tiles;:135calls the other fields ofroads.json"the stamp profile of the engine".data/trailview/README.md:15-16describesroads.jsonandwaterways.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.jsonandroad-views-top.jsonwithout a query gives the same PNG asground-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
.tsfile underbuilder/web/src/lib/trailview/is in the production module graph or is a test of a file that is; every.wgslfile is reached from a root (step B.4) through// #includelines. - I3, no old name. No file of the repository names a deleted file,
ground=plan,groundPlanOf,FAR_STAMP,stamp_at,stamp_of, theRoadsclass,RoadPiece,roadsLoadingor the snap words, except git history and closed issues. - I4, one source per value. No value of
data/trailviewlives in code (epic section 3). The old constants ofbins.ts(SURFACES,PAVED,PATH_HALF,SHOULDER_M) androads/section.tsgo 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_effand 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.
-
The address.
view.ts: deletegroundPlanOf.ground=planin an old address then does nothing:parseViewignores unknown names.plan(off,faces, and the views that GP7 added) andfinest(GP9) stay as debug parameters. -
The engine.
trailview.ts,engine.ts,terrain/terrain.ts: delete theplanoption.Terrainalways makesPlan,Piecesand the plan layer.waitForIdle()waits for the plan'sloadingin place ofroadsLoading.TerrainStats.roadsgoes;TerrainStats.planstays. The HUD always shows GP5's plan line. -
The terrain pipelines.
terrain/terrain.wgsl: deleteoverride PLAN; the floor branch ofvertex_mainruns always.grid_vertex(u, level, snap)loses itssnapparameter;terrain/drawn-mesh.wgslloses the snap code (:39-53on develop) and the snap words.terrain.ts: delete thesnappipeline, its layoutL.snap, thesnapstexture,snapGroupand its entry infeatureGroup; renumber no other binding. Where a binding becomes free, it stays free. -
The stamp.
far-stamp.wgsl: deleteoverride FAR_STAMPandstamp_of;stamp.wgslandaudit.wgslcallfar_stamp_at. Move intofar-stamp.wgslthe declarations ofstamp-core.wgslthat a kept shader reads (the bindings,Profile,Rules, the record format, the record kinds thatbins.tsstill writes, the buckets,Along,along,Stamp, and the helpers).water.wgslincludesfar-stamp.wgslin place ofstamp-core.wgsl: the bindings are the same, and WGSL ignores the far stamp's unused functions. Deletestamp-core.wgslwithstamp_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. -
The stamp worker.
terrain/stamps.ts,terrain/stamp-worker.ts,terrain/bins.ts: delete theplanmessage field and parameter.bins.tskeeps only GP8's plan branch: deleteapproaches,junctionPlanes,townPieces, the JUNCTION and CORNER records, the JOIN caps,profileTable's old form and the viewer's own sidewalk decision (bins.ts:472on develop; the plan reads the bake'swalk, GP4).terrain/town.tsloses the sidewalk and paving parts; the sweep of B.4 and the export search of B.5 decide the rest (on develop onlyKERBhas a kept reader,ground/rules.ts:8). -
The corridors. Delete
Roadsand its worker. Inplan/piece.wgsl, inline what it uses ofroads/corridor.wgslwithPIECE = 1folded:corridor_fragmentbecomespiece_fragment,CorridorOutbecomesPieceOut, andpart_vertex,part_casterandPartIncome with their constants (table of A.7).BANDis an override ofground/look.wgsl:40that the terrain also compiles, so the pieces pipeline keeps passing the constantBAND: 1.plan/piece.wgslitself includes../ground/look.wgsland../roads/looks.wgsl, whichcorridor.wgslincluded for it. The corridor vertex stage, the corridor's band (band.wgsl,band_dive), the paint dither and the detail fade go. Deleteroads/corridor.wgsl.terrain/features.wgsl:paint_shareno longer readsmasks.held; GP10's fade decides where the paint draws.masks.heldand its write atterrain.ts:890go. -
Water, bridges, placement. The near-eye branches of
terrain/water-mesh.tsandterrain/water.wgsl(the ribbons that GP14 replaces within the range), the corridor-deck hand-over ofstructures/bridges.ts(GP12:WALK_INSIDE_M, thecorridorspan,decksOf), the culvert mouths (roads/mouths.ts,culvertMouth), the street lamps ofroads/lamps.tsand 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. Thebesidebranch ofinstances/points.wgsl(:34-43), its include ofband.wgsl,Point.beside,besideBitsandBESIDE_STEP_Mgo here too: on the plan path no point hasbesidebits (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:4stationsOf,strokeMetres,StationMove them with STEP_M,SAME_MandCUTintostructures/mesh.ts(about 70 lines);Station.paint(typePaintofmarks.ts) goes. If GP13 left a second reader, they move tostructures/stations.ts.structures/bridges.ts:6-7isPaved,onDeck,PARAPET_M,teesOf,wider,KERB_RISE_M;decksOfMove the first five with deckHalfintobridges.ts(about 60 lines);KERB_RISE_Mfromterrain/bins.ts;decksOfgoes (GP12).structures/node.ts:3,9,10,16,17coresOf,cornerAt,deckHalf,culvertMouths,streetLampsBuild.coresandBuild.corneredgo (R1);deckHalffrombridges.ts;culvertMouthsgoes (GP15);streetLampsgoes (GP17).kinds/kind.ts:12besideWays,Beside,Cores,Stand,TakenpointModelskeeps GP17's plan branch;StandandTakenmove intokind.ts(under 10 lines) if that branch reads them, else they go.kinds/kind.test.ts:9-10coresOf,streetLampsThe cases of besideWaysand rule lamps go; GP17's plan-branch cases stay.kinds/road.ts:2lampKindMove lampKind(the lamp model and its light, about 15 lines) intokinds/road.ts, which GP17'sroad/lamppoints use.kinds/stream.ts:2,models/amenities.ts:4mouthKind;MOUTH_*Go with culvertMouth; GP15's objects draw the mouths.kinds/building.ts:6,kinds/arete.ts:6coreAtR1 (A.9). instances/points.ts:5BesideGoes with beside(above).terrain/water-mesh.ts:11waysOf(underDeckonly)Move underDeckwithDECK_MARGIN_Mintowater-mesh.ts(about 15 lines).terrain/water-mesh.test.ts:3shoreOfIts cases test the near ribbons and go with them. terrain/bins.ts:9-11,bins.test.ts:12-13approaches,halfAt,partnersOf,boxOf,cornersOf,joinCulverts,standMouthsThe old branches that read them go (A.5); joinCulvertsandstandMouthsgo (R2). If GP8's plan branch readshalfAtorpartnersOf, they move intobins.ts(about 30 lines).test-support/trailview/census.ts:9-15roads/*"Census": only waterSamplesstays.
| 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. |
- Scripts and tests.
shoot.mjs,flight.mjs,census.mjsand every committed views or flights file: deleteground=planfrom every default and query.--querystays 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.
- 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.coresandBuild.corneredgo.kinds/kind.tsgetsonWay(ways, x, y, past): true where the point lies withinh + pastmetres of a segment of a road or path line ofBuild.ways, withhthe line's half-width from GP8's plan branch (the far stamp's paint half).building.ts:48andarete.ts:30call it in place ofcoreAtandcornered. The far stamp has no corner fill (GP8), so nothing replacescornered. About 15 lines with a unit test. - R2, far ribbons without culvert cuts.
joinCulverts,standMouths,waysOfandterrain/culverts.tsgo. Past the range, a ribbon is the stream line asfeatures()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.
- R1, the far stamp's core for signs and rocks.
Step B: delete what no kept path reaches
- Delete the epic's list (section 16, with
band.wgsl,lamps.tsandterrain/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.tsandcorridor.wgslafter their kept parts move (A.7), anddetails.tsandtracks.tswhere GP13 and GP16 replaced them.parts.tsmoves toplan/(A.7). Each test file of a deleted module goes with it. - 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.
- The gap rule. The table of A.7 and A.9 decide every import known at design time. Where
ground-planshows 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 intoground-plan. - 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 thesourcesof every.map, and list each non-test.tsfile undersrc/lib/trailview/that is not in them. For WGSL, the roots are: every literalwgsl('…')argument in a live.tsfile; every path that a computed call builds, listed by hand from its callers (eachfileofterrain/terrain.ts:924, eachpathofinstances/instances.ts:661); and the values ofCLIP_DISTANCES(gpu/include.ts:27). The script also lists eachwgsl(call whose argument it cannot resolve, so a new computed call cannot hide a file. List each.wgslfile that no root reaches through// #includelines (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. - The exports.
npm run checkandnpx vitest run src/lib/trailviewfind every dangling import. An export that no file imports any more goes (search each export of the changed files withgrep -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
stampandgroundpasses 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 10on walk and valley-drive, and again with&finest=17in the query: everycracksandinsidevalue 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.readyof GP5) for each view ofroad-views.json, asshoot.mjsprints 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, andspecs/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 aplan/row (the plan client, the worker and the bridge's output, the pieces, the floors, the plan layer, the debug draw) and newroads/andterrain/rows (the far stamp, no corners, no culverts). "The address" gainsplan,finestanddebug=owned. "Shots and flights" keeps only theplants-in-waterrow of the census table, and gains--owned N,--surface N,--query Qand 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:11names the crate's decoder among the readers, if GP1 did not;:135names the readers of the cross-section table, if GP18 did not.docs/design/trailview.md:ownsnameshost/obc-ground-plan/**andbuilder/ground-plan-wasm/**, if GP1 and GP5 did not.data/trailview/README.md: the lines of removed fields.
Merge into develop
- GP19's pull request merges into
ground-planafter its review and green CI. ground-plantakes 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 underbuilder/web/src/lib/trailview/**,data/trailview/**orhost/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.- A pull request
ground-plan→developholds the acceptance record (Verification) and the lineRequirements: none(or the TrailView requirements that the owner names). CI runs on it. - 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.
- 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
- 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-planunder the GP item that owns the rule, proven over the whole fixture. Then GP19 shoots the affected views again, and the owner looks again. - A kept path that still needs an old behaviour: the gap rule of step B.
- An old address with
ground=plan: ignored, the view draws. - Fewer storage buffers: GP9's counts hold (7 of 8); step A frees the snap texture's binding and adds none.
- The bridge fails to start or a cell fails: I5, and the new smoke test.
- Quality below level 17: no piece draws; the far stamp shows the ways (GP9 section 10). Shot at
finest=16(Pictures). - The phone's path: level 17 is the finest level at the first quality step (
terrain/terrain.ts:795). Shot atfinest=17(Pictures), counted with--owned. - 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.
- A WGSL file that only a test or a script reads (
check-wgsl.mjsvalidates every file): the sweep lists it; it goes unless a kept script uses it. - 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
- Branch
claude/gp19-only-pathfromground-planafter the develop merge of wave 12. Check each row of the table of A.7 againstground-plan(grep -rnof each import); a row that does not fit is the gap rule, before any code. Build the page (npm run pretest:trailviewinbuilder/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/andbase-2/. Fly walk and valley-drive with the same query, three runs: the plan path's numbers before the fold. - Step A.1 and A.2:
view.ts,src/trailview.ts,engine.ts,terrain/terrain.ts. - Step A.3:
terrain/terrain.ts,terrain.wgsl,drawn-mesh.wgsl,features.wgsl. - Step A.4; delete
terrain/stamp-core.wgsl. - Step A.5; delete
terrain/corners.ts,terrain/approaches.ts. - Step A.6; delete
roads/corridor.wgsl. - Step A.7, by its table.
- Step A.8: delete
ground=planin 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 withfold/(I1b). - Step B: delete the files of B.1; run the sweep of B.4 until it lists nothing; delete unused exports.
- Tests: delete the tests of deleted modules;
smoke.test.js: the assertion at:35and the new fallback test; the census per "Census";roads/mesh.test.tsandscripts/road-meshes.tsgo. Run the census once before its reduction and keep the counts for the pull request. data/trailview/*.jsonanddata/trailview/README.md: remove the fields that no reader reads.cargo fmt --all; the checks of Verification;obc suites check.- The
docs:commit: the guide,nav.json, the README, the crate README,data/trailview/README.md,specs/trailview-features.md,docs/design/trailview.mdas "Docs" says.python3 docs/build_docs.py --check-links,obc prose --check. - The budgets and the pictures of Verification: one slider page, and the live viewer for the owner.
- The pull request into
ground-plan:Mode: change #<GP19>,Requirements: none, "Public docs changed: yes, in thedocs:commit", the record. Review, fixes, merge. - "Merge into develop", steps 2 to 5.
Files
builder/web/src/lib/trailview/roads/: delete: every file butlooks.wgsl,track-looks.wgsl,details.wgslandlooks.ts, with their tests; the corridors, the sweep, the junction plan and the old placement.roads/looks.ts: create: theMAT,LOOKandCFids ofsection.ts.builder/web/src/lib/trailview/plan/parts.ts(moved fromroads/),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.tsand their tests: delete: today's stamp, corners, approaches and culverts.builder/web/src/lib/trailview/terrain/far-stamp.wgsl: change: the helpers ofstamp-core.wgslthat kept shaders read; noFAR_STAMP, nostamp_of.builder/web/src/lib/trailview/terrain/stamp.wgsl,audit.wgsl,water.wgsl: change: includefar-stamp.wgsl, callfar_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, noheld.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 fromcorridor.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); nobeside; purpose comments that name corridors (kinds/road.ts:1) state the present behaviour.host/obc-trailview-features/src/bake.rs:28: change: the comment namesterrain/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: noground=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: onlyplants-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-planandobc 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:trailviewon the GTX box (the@gputests, GP9'sownedtest among them). CI skips@gpu; the pull request reports the local run. - I1: for each view,
cmp base-1/V.png fold/V.pngandcmp base-2/V.png fold/V.png; gate: one is equal. For a view wherecmp base-1/V.png base-2/V.pngfails, 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
cmpoffold/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-planprints 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-planfor GP19's pull request; for the pull request into develop,obc test affected --base origin/develop --dry-runprints 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, frombuilder/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-topview:- Every view of
road-views.json(eye height and the near views) and every view ofroad-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
-topviews with--query '&finest=17'(the phone's path), andv12-good-town-junctionswith&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.
- Every view of
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
.tsor.wgslfile (I2). - The checks of Verification pass locally and in CI, and the
@gputests 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-planafter its review. - The owner accepts the reference views and the budgets, and
ground-planhas 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: cairndocument, which the owner runs; GP19 checks onlyowns. - 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.
- The census: the epic deletes it whole. GP10 and GP14 gate
plants-in-wateron the plan path, and no other check proves on the drawn result that no plant stands in water. Recommendation: keep onlyplants-in-water;objects-on-waysand the four corridor counts go. - 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
joinCulvertsandstandMouths(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 viewsstreams-under-farandstream-lake-farshow the result. - 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.wgsldeletion changes point heights: no plan-path point hasbesidebits (GP17), sopoints.wgsl:34-43never runs; the fold is in A.7 under I1.
Epic note: GP9 leaves the deletion ofdebug=cracksto GP19. It stays, because the terrain's own crack test (smoke.test.js:52) andskyline.mjs:28use it.
Activity
timohueser commentedon Nov 3, 2026
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
terrainpass, and the viewer has no switch for "ways off". GP0 measured ways-off with a scratch copy offlight.mjsthat skips the corridors' draw and cast (see the baseline comment on #3096). The 0.8 ms gate compares theterrain+stamppasses 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.timohueser commentedon Nov 3, 2026
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.
timohueser commentedon Nov 15, 2026
Owner decision, 2026-11-15 (his note on the merge document for
ground-plan→develop, #3491):What this means for this step:
ground=parameter stay.Generated by Claude Code