Repository navigation
Description
Status: approved
Part of #3656. Depends on #3778.
TL;DR
Goal: On the iPhone 13 at tier=phone, the stamp worker holds at most 112 MiB after the walk load, down from 192 MiB. The water meshes stay the same, and the far views show no changed pixel.
Problem: For each feature tile that the stamp worker keeps, it also keeps two things that it made from the tile: the tile's shapes in world units (features of terrain/bins.ts) and a grid index of these shapes (tileIndex). The worker's cap counts neither. In WebKit they are about 8 times as large as the decoded features. During a load, the view wants 14 to 19 tiles at once, among them four zoom 8 tiles, and the worker keeps each wanted tile past its cap.
Decision: Two changes in terrain/bins.ts. The cells of a tile's grid index grow with the tile, to at most 16 × 16 cells across it. At a node level where no line can show (level 12 and coarser), a node reads only the water lines, bridges and tunnels of its tile: its tile keeps only these lines, and the node writes no junction and no corner records. The decoded features keep their form.
Rejected:
- A compact form of the decoded features, the first direction of this issue. In WebKit the decoded features take half of the bytes that the cap's estimate counts, and about one eighth of what the worker keeps for a tile. It saves at most about 20 MiB of the peak.
- The cap also counts the shapes and the index (
chargeTileofstream/features.ts). The peak comes from the tiles that the view wants, and the worker keeps those past its cap. - A compact form of the shapes, with typed arrays in
Line. It changes every reader of the shapes, about 4,000 lines, for bytes that the two changes remove.
Systems: trailview
Contracts: none
Size: S (1 system, no contract, under 100 changed lines)
Facts
Measured on the M1 Pro: the page at tier=phone drove the walk and the valley drive (to and fro twice) in Chromium. A script recorded each message to the stamp worker and fed the messages, one at a time, to develop's built stamp worker in the JavaScriptCore shell of macOS, the JavaScript engine of WebKit. It hashed each job result to compare builds. The comment below has the method.
- The live heap of the stamp worker peaks during the load: 209 MiB on the walk, 197 MiB on the drive. At the end it is 58 MiB. The phone's 192 MiB of TrailView phone tier: smaller caches and fewer workers #3778 is near the peak.
- For the 42 tiles of the walk, the worker makes about 40 MiB of decoded features, 170 MiB of shapes and 136 MiB of grid index. A zoom 8 tile holds about 7 MiB of features, 22 MiB of shapes and 23 MiB of index.
- JavaScriptCore keeps the decoded features in 0.49 times the bytes that
decodedBytesofstream/features.tsestimates. V8 keeps them in 1.00 times. - The grid index (
gridOfofterrain/town.ts, cells of 2^13 world units, about 200 m) lists a line, a lake or an area in each cell that its box covers. On a zoom 8 tile, the box of one long river covers thousands of cells. - A node of level L reads the feature tile of zoom L − 1, up to zoom 13 (
featureTile). So the nodes of a zoom 11 tile have level 12. The road worker and the house worker read zoom 13 tiles only. - At level 12 and coarser, no line passes
shows: its reach limit, 40 m − 2 × the texel (gateTexel) − 1 m, is below 0, and the half-width and the profile'sleastare not below 0.nodeStampsskips such a line below the near levels, but it writes the junction and corner records of its roads, bridges and tunnels at every level. - At these levels the shader draws nothing from these records: it skips a corner whose road does not show (
road_showsofstamp-core.wgsl), and the reach of a junction (junction_reach) is below 0, so a junction turns no cell into a junction. Its shelf acts only where a sidewalk shows, and no road and no corner shows there. The pixel compare of the far views is the proof. - The other readers of a coarse tile's lines: the water mesh (
waterMesh) reads the water lines and the bridges and tunnels over them;portalBoxesreads the tunnels;waterLevelsreads the water lines; the audit samples read the roads and rails, andaudit.wgslskips a road that does not show at the level.floorsOfandstructureMesheswork only at the owner level, 15.
The changes on the recorded walk and drive (1,254 jobs). The time is the sum of the job times in the second of two runs; the zoom 12 and 13 jobs stay within the spread of the two runs.
| Stamp worker | Peak, walk | Peak, drive | Time, walk | Time, drive | Jobs whose results change |
|---|---|---|---|---|---|
| develop | 209 MiB | 197 MiB | 5.0 s | 4.3 s | – |
| The index cells grow with the tile | 133 MiB | 127 MiB | 2.9 s | 3.7 s | none |
| Level 12 and coarser read only water lines, bridges and tunnels | 119 MiB | 116 MiB | 1.9 s | 2.6 s | 116: the stamp data of zoom 8 to 11 tiles |
| Both | 48 MiB | 54 MiB | 1.8 s | 3.0 s | the same 116 |
Each change alone stays above 112 MiB. Without the stop on junction and corner records, the tiles keep bridges and tunnels, so 34 jobs still write such records.
Plan
tileIndexofterrain/bins.ts: the cell size of a tile's grids is the larger of 2^13 world units and the tile's size / 16. A zoom 13 tile keeps cells of 2^13.featuresputs the tile's zoom on its shapes (Shapesgetszoom), anddeckIndextakes the same cell size.terrain/bins.ts: one function says whether a line can show at a level: its reach limit (RULES.BUFFER_M− 2 ×gateTexel(level)− 1) is at or above 0. No level number is written in the code.nodeStampsofterrain/bins.ts: a node at a level where no line can show writes no junction and no corner records.featuresofterrain/bins.ts: a tile under zoom 13 whose nodes (zoom + 1) are at a level where no line can show keeps only its lines of kindRIVER,STREAM,BRIDGEandTUNNEL.terrain/bins.test.ts: the test oflinesNearruns on a zoom 13 tile and on a zoom 8 tile. A test holds thatshowsis false for every profile at each level where no line can show, so a change of the rules that lets a line show there fails. A test holds that a node at such a level writes no junction and no corner record. Tests that makeShapesby hand give it a zoom.- The far views:
shoot.mjsdraws, with develop and with this change, the start of the four kit scenes (walk, valley drive, zoom-out, bridge and tunnel) and the two far views of the epic's galleries. The zoom-out looks down over the towns of the valley, where the coarse nodes had most junctions.
Files
Paths under builder/web/src/lib/trailview/.
terrain/bins.ts: change: steps 1 to 4.terrain/bins.test.ts: change: step 5.kinds/kind.test.ts,roads/cores.test.ts: change: their hand-madeShapesget a zoom.
No guide page changes.
Done when
- In
builder/web:npx vitest run src/lib/trailviewandnpm run checkpass. - The views of step 6 show no changed pixel. If a pixel changes, the owner approves their gallery in a comment on this issue.
- The replay of the comment below gives the same results as develop for every job of a zoom 12 or 13 tile, and those jobs take no longer than with develop, within the spread of two runs.
- On the phone at
tier=phone(the app host ofprototype/trailview-ios-app), the kind runp-end-stampgives back at most 112 MiB. - The soak
p-soakends with at least 512 MiB of headroom. It ended with 416 MiB in TrailView phone tier: smaller caches and fewer workers #3778. This change alone is expected to close the gap of 96 MiB: the stamp worker is expected to give back about 130 MiB less. TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110 adds about 64 MiB more.
Limits
- The replay runs the jobs one at a time. On the phone, the page runs up to 4 jobs at once, so the phone's peak can be higher.
- The replay ran with
plan: false. With the ground plan, a coarse node writes no junction and no corner records already, and skips the roads, paths and rails below the near levels. - The cap still counts only the decoded features, by an estimate fitted to V8.
- The house worker keeps its own data made from zoom 13 tiles (
fronts). It was not measured and does not change.
Requirements: none
Activity
timohueser commentedon Nov 22, 2026
How the facts of the design were measured (M1 Pro, 2026-11-22, about 45 minutes, no phone run).
vite build --mode trailviewagainst the catalogue of the local release (Central Switzerland). The page runs attier=phonein new-headless Chromium, 390 × 844 CSS pixels.Worker.prototype.postMessageand records each message to the stamp worker: the tile, the node, the job, the cap (bytes, 24 MiB) and the wanted tiles. It keeps each tile body once. The walk: load, then the 20 s flight of the kit (339 messages, 72 bodies). The drive: load, then the valley drive to and fro twice, 80 s (1,137 messages, 76 bodies).stamp-worker-*.jsin the JavaScriptCore shell of macOS (jsc -m), with smallTextDecoderandTextEncoderstand-ins, and feeds the recorded messages one at a time withplan: false. Every 20 messages it runsfullGC()and readsgcHeapSize(). It hashes each job result (every field, typed arrays by bytes) to compare builds.features(shapes), thentileIndex, each withfullGC()before and after, all tiles kept.Per tile zoom, walk tiles, live MiB in JavaScriptCore (index with the cells of develop):
A second run gave 40, 169 and 137 MiB for all tiles.
With index cells of at most 16 × 16 per tile, the index of all 42 tiles is 4 MiB; with 32 × 32, 8 MiB; with 64 × 64, 15 MiB.
The decoded features of the 42 tiles: 37.5 MiB live in JavaScriptCore, 76.7 MiB in V8 (node
--expose-gc, heap and array buffers), 76.5 MiB bydecodedBytes.At the walk's load peak the view wants 14 to 19 tiles, for example at message 99: four zoom 8 tiles, two zoom 9, five zoom 10, three zoom 11, two zoom 12 and three zoom 13.
The replay holds one job at a time, so its peak can be lower than the page's, which runs up to 4 stamp jobs at once on the phone.
Job times: the driver sums
performance.now()around each job, by tile zoom and job kind. Each of four builds (develop, index cells, the coarse rule, both) ran the walk and the drive twice, one build after the other. The first round runs slower than the second for every build; the design gives the second.Each cell gives the first run, then the second.
[-]TrailView phone tier: a compact form of the decoded features[/-][+]TrailView phone tier: the stamp worker keeps less for each feature tile[/+]