Skip to content

TrailView phone tier: the stamp worker keeps less for each feature tile #3793

Open

Description

@timohueser

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 (chargeTile of stream/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 decodedBytes of stream/features.ts estimates. V8 keeps them in 1.00 times.
  • The grid index (gridOf of terrain/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's least are not below 0. nodeStamps skips 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_shows of stamp-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; portalBoxes reads the tunnels; waterLevels reads the water lines; the audit samples read the roads and rails, and audit.wgsl skips a road that does not show at the level. floorsOf and structureMeshes work 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

  1. tileIndex of terrain/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. features puts the tile's zoom on its shapes (Shapes gets zoom), and deckIndex takes the same cell size.
  2. 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.
  3. nodeStamps of terrain/bins.ts: a node at a level where no line can show writes no junction and no corner records.
  4. features of terrain/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 kind RIVER, STREAM, BRIDGE and TUNNEL.
  5. terrain/bins.test.ts: the test of linesNear runs on a zoom 13 tile and on a zoom 8 tile. A test holds that shows is 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 make Shapes by hand give it a zoom.
  6. The far views: shoot.mjs draws, 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-made Shapes get a zoom.

No guide page changes.

Done when

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

  1. timohueser commented on Nov 22, 2026

    @timohueser
    OwnerAuthor

    How the facts of the design were measured (M1 Pro, 2026-11-22, about 45 minutes, no phone run).

    1. develop at 447fa75, built with vite build --mode trailview against the catalogue of the local release (Central Switzerland). The page runs at tier=phone in new-headless Chromium, 390 × 844 CSS pixels.
    2. A script wraps Worker.prototype.postMessage and 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).
    3. A driver loads the built stamp-worker-*.js in the JavaScriptCore shell of macOS (jsc -m), with small TextDecoder and TextEncoder stand-ins, and feeds the recorded messages one at a time with plan: false. Every 20 messages it runs fullGC() and reads gcHeapSize(). It hashes each job result (every field, typed arrays by bytes) to compare builds.
    4. Per tile: decode alone, then features (shapes), then tileIndex, each with fullGC() before and after, all tiles kept.

    Per tile zoom, walk tiles, live MiB in JavaScriptCore (index with the cells of develop):

    Zoom Tiles Decoded Shapes Index
    8 4 26.4 86.9 93.0
    9 4 4.8 30.9 22.9
    10 8 3.0 18.2 15.1
    11 8 0.5 5.3 2.6
    12 7 0.2 1.3 0.6
    13 11 3.7 32.4 1.4
    all 42 39 175 136

    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 by decodedBytes.

    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.

    Build Walk, all Drive, all Walk, zoom 8 to 11 Drive, zoom 8 to 11 Walk, zoom 12 Drive, zoom 12 Walk, zoom 13 stamps Drive, zoom 13 stamps
    develop 6.0, 5.0 s 8.2, 4.3 s 4.3, 3.5 s 5.3, 2.3 s 44, 38 ms 42, 27 ms 1.15, 0.96 s 2.17, 1.49 s
    index cells 5.2, 2.9 s 5.7, 3.7 s 3.3, 1.9 s 2.7, 2.0 s 37, 27 ms 35, 20 ms 1.18, 0.62 s 2.13, 1.23 s
    coarse rule 3.6, 1.9 s 4.2, 2.6 s 1.6, 0.9 s 1.6, 0.8 s 47, 27 ms 30, 21 ms 1.31, 0.64 s 1.91, 1.19 s
    both 2.8, 1.8 s 4.2, 3.0 s 1.3, 0.7 s 1.0, 0.8 s 40, 27 ms 34, 24 ms 0.96, 0.70 s 2.23, 1.60 s

    Each cell gives the first run, then the second.

  2. changed the title [-]TrailView phone tier: a compact form of the decoded features[/-] [+]TrailView phone tier: the stamp worker keeps less for each feature tile[/+] on Nov 22, 2026
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