Repository navigation
Description
Status: approved
Part of #3096 (it merges into ground-plan). Size: L, in four pull requests (P1, A1, B1, A2) and one run by the
owner.
Depends on: pull request #3268 (merged). Pull request B1 lands after #3273 B2 (the far look's viewer part), which
rewrites the records' row allocator. P1 and A1 depend on nothing else.
Source: the audit of 2026-11-09, the measurements of checkpoint 2 (2026-11-10), the reviews and follow-up notes of
#3268, the review of #3263, a design in three versions with two adversarial reviews
(/media/timo/OSM1/tmp/ground-plan/memory-tier/DESIGN.md, REVIEW.md, REVIEW-delta.md: every number with its
source).
Paths are relative to builder/web/src/lib/trailview/ unless they start with host/ or builder/. A name marked
(new) does not exist on ground-plan db3264c. Folders named below without a root are under
/media/timo/OSM1/tmp/ground-plan/.
Problem
The viewer allocates the same GPU pools on every device: 655–676 MiB at 1920 × 960 (ground 219.6, pages 136.0,
features 82.0, instances 52.1, records 32.0, and smaller ones). The GPU process holds 153–172 MiB of VRAM beside
them. The renderer process holds 465–684 MiB at idle, 305–379 MiB of it not named by any measurement, and more in
a load. An iPhone 13 has 4 GB of RAM; iOS ends a process that holds too much, with no error. No phone run exists.
Most pools already leave out what does not fit, the farthest first (Pages.fit, the mask holders, the ground
pages). What is missing:
- The sizes are constants.
- Where a cell inside the mesh range has no mesh, the picture is not whole by construction. A page left out
rests every cell for at least 120 frames (trailview: a terrain page shortage leaves out the farthest fine pages; their parents draw in their place #3268, all or none). A cell whose records block found no room, a
failed build and a mesh that is not computed yet leave a cell without a mesh beside a drawing cell: the mesh
draws whole to that border, and the terrain past it stands at its own height. - A mesh comes and goes in one frame.
- Nobody knows what a phone holds, or what it needs.
Design
Words
- share: a number from 0.4 to 1: the part of today's sizes that a device gets.
- split:
rule.range / 2^18: where level 18 ends, 480 m at 47° N for a render height up to 1,360 pixels. An
iPhone 13 in portrait renders 1,182 pixels high, so its split is 480 m and its mesh cells are 14. - mesh cell: a cell of
meshCells()(plan/pieces.ts). mesh field: the cells whose meshes draw, inside
the split. - unit: a world unit (2^30 across the world); a cell is 16,384 units, a level-18 grid step is 64.
1. P1: a left-out page draws until its stand-in draws (follow-up D2 of #3268)
Pages.slot(terrain/pages.ts) never evicts a left-out page that still draws, except for its own stand-in (a
page above it).resolvepasses its node toslot('stored', node), so a stored stand-in can take its child's
slot. The doc offallbacksays "until the page in its place draws".- A page that fits (
fits) and finds no slot waits; it is not left out:allocateandresolvedo not callleave()for it. It has no entry inleftOut,leftorfallbacks.- It stays missing, so frames go on.
- Its ancestor draws in its place, as in a load.
- Arrivals: an arrival whose page fits and finds no slot stays in
arrivals, in its place, and the intake goes on
with the next arrival. An arrival that the frame does not need and that finds no slot is dropped, as today.
2. A1: the share, and the first pools
budget.ts(new):LEAST = 0.4;budget(share)gives{ share, of }with
of(full, unit = 1, least = 0) = unit × max(1, ceil(least / unit), round(full × share / unit)).budgetOf(search)(new,view.ts, besidepoolOf):budget=from 0.05 to 1, else 1. The page
(builder/web/src/trailview.ts) passes it toTrailView.start(engine.ts), which hands it on as it hands
pooltoTerraintoday.pool=stays as it is: the page pools alone, after the budget, also under their
least.- Four pools take the share in A1. Each keeps its constant as
full. None of the first three has its size in a
shader: a slot gives its layer (page >> 6,layer × CACHE_PLANES + plane), and the layer count is the
texture's.
| Pool | full |
unit | least |
|---|---|---|---|
| pages, synthesized | 280 slots (terrain/terrain.ts SYNTH_PAGES) |
1 | 140 (measured: the walk and the drive keep every mesh) |
| pages, stored | 808 slots (BUDGET) |
1; the texture has whole layers of 64, and the spare slots of the last layer go to this pool | from A0, if it shows one |
| masks | MASKS 128 (terrain/terrain.ts): mask, paint, moved, cliff share and snaps follow |
8 | from A0, if it shows one |
| ground pages | POOL 192 (ground/ground.ts) |
16 | from A0, if it shows one |
- The shadow maps:
SIDE(light/shadow.ts) is 2048 for a share over 0.5, else 1024. The shader
(light/shadow.wgsl) reads the side withtextureDimensions(shadow_maps)and the levels with
textureNumLevels(shadow_maps)in place ofSHADOW_SIDEandSHADOW_LEVELS. No override constant:prepare
compiles the pipelines before the share is known, andgpu.onceshares them across engines. - These sizes do not change in this issue:
STAMP_WORDS(it is also the most that one node holds,
terrain/bins.ts),ARRIVALSand the ground'sJOBS, the instances' atlas, staging and mesh pools, the canopy,
the sky, theplanpool (no cap),SLOTSofplan/pieces.ts. stats()getsbudget. The HUD (hud.ts):- one more line:
budget 0.40 · pools 381 MiB · <adapter> · timestamps yes|no · clip yes|no; - its first line always shows
cpuand the median interval of the last 30 drawn frames (new, from the frame
loop'snowinengine.ts), with or without timestamp queries; - its problems line also shows
waterDropped,structuresDroppedand the count of records cells that are
over(new inRecordsStats).
- one more line:
3. A0, in the same pull request as A1: what the phone needs, and where the memory is
A stats patch and a measurement. No product behaviour changes.
stats()gets the demand of each pool: the pages wanted per kind (Pages.wanted), the masks wanted (the near
pages with features, before the cut inholders), the largest house tile and the largest records block, and for
eachPool(structures/pool.ts) and the instances' mesh pools the used bytes, the largest mesh and the count
of restarts.- The working set of each CPU cache that A2 shrinks: the bytes of the stamp nodes that the mesh cells and the
drawn near pages read in a frame (NODE_BYTES,terrain/stamps.ts), the house worker's largest decoded tile,
the rasters and the tile bodies that a view's pages read. - The memory probe: a copy of
checkpoint2/tools/mem.mjsthat keeps each worker'sbackingStorageSize, samples
the PSS of the renderer and of the GPU process every 100 ms through a cold load, and reads the VRAM with
nvidia-smi --loop-ms=100.
4. B1: the mesh field (after #3273 B2)
T = PLAN_TRIANGLE_UNITS = 256 units (it exists in plan/cells.wgsl). F = PLAN_FADE_UNITS = 768 units (new).
The weight. Each cell of the window has a weight from 0 to 1. A weight over 0 means that the cell's mesh
draws in this frame, at that share. The cells buffer holds it in bits 8 to 15 of the cell's word, beside the
slot + 1 in bits 0 to 7 (plan/pieces.ts write, plan/cells.wgsl plan_slot). A cell without a piece has the
weight 0: also a cell that Records knows as empty.
drawable = the piece is computed and has a slot, its records block is on the device,
and the meshes draw at this frame's level (meshLevel > 0)
target = 1 when drawable and Pages.fallback(cell, finest) ≥ COARSEST_MESH (the `rests` callback of today)
= 0 else
weight = 0 at once when not drawable
= one step of dt / FADE_S toward target else (FADE_S = 0.2 s, new; dt = the time since the last drawn
frame, at most 50 ms)
the pieces that draw = those with a weight over 0, of the cells in range
- Each computed piece of the window has a slot, also out of range.
- A piece leaves through the fade:
Records.unmeshedgives it the target 0, andPiecesremoves it at weight 0. - A mesh that comes again for a cell (
Pieces.add) does not remove the old piece at once: the old piece draws
until the new one is computed, and then the new one takes its place. Pieces.updatereturns true while a weight moves (new content: frames go on, and a still view's 16 frames
start after the last move).Pieces.updateloses the termrange.some(rests): no cell rests for another.meshLevelstays for a finest
level below 17 (finest=16); with it at 0 every weight is 0 at once.
The field (plan/cells.wgsl, one function, new; no state):
plan_field(point, margin) = the least, over the point's cell and its 8 neighbours with a weight under 1, of
weight + max(0, distance in units from the point to that cell's square − margin) / F
and 1 where every one of them has the weight 1
plan_near(u): today's radial test, andplan_field(u, 0) = 1.plan_sunk(u): today's radial test,plan_field(u, T) = 1, and the sunk bit. Its three border tests and
plan_meshedgo.- A cut piece's share at a pixel (
roads/corridor.wgsl,if (PIECE && CUT)): the least of today's radial share
andplan_field(pixel, 0). plan_owns(the debug viewowned) takes the same field.- A piece draws with the cut pipelines when it reaches past the plateau (today) or when its cell or one of its 8
neighbours has a weight under 1.
What the rider sees. Beside a cell without a mesh, the mesh is whole to 19.5 m before the border and
cross-fades to the page's look over those 19.5 m. A mesh comes and goes in 0.2 s. In a load the meshes come cell
by cell as today, the eye's cell first. In the first frame of a fade-out the cell's terrain comes back under the
mesh; where the page stands above the mesh (the slope at a wall or a kerb) a sliver of the page appears.
The double surface. In the band the mesh draws over terrain that is not sunk, and their surfaces lie in one
plane to within the interpolation, so the visible one can change per pixel where they shade differently. If the
pictures of the gate show a mottle or a crawl, the remedy is a small depthBias on the piece pipelines
(piecePipelines, plan/pieces.ts), so that the mesh wins every near tie.
The records. #3273 B2 owns the rank of the rows. B1 adds to that allocator:
RECORDS_MB(terrain/model.ts) throughof, unit one row, with a least of the largest block that step 0
reports. The records get no share of their own.- A near block of a piece with a weight over 0 does not leave at once.
RecordsasksPiecesto fade the piece
and counts the block's rows as room only at weight 0. The cell that waits isoverand asks again. TrailView ground plan: far cells build only their lines, and the pages of level 17 and 16 are drawn as strokes #3273's
Pages.restamp(cell, 18, 18)for that block runs then, not before.
#3273. Two sentences of its text change before its B2 starts
(/media/timo/OSM1/tmp/ground-plan/memory-tier/for-3273.md): "nearer" in the rank of the rows is the cell's own
distance; an iPhone 13 in portrait has the split 480 m and 14 mesh cells. This design relies on #3273's owner
check, which passed on 2026-11-10: a mesh may stand over a level-17 stroke page (the threshold 17 above), and a
cell without a near block shows the stroke look, also on the page side of a band and past the meshes of a dense
town.
5. A2: the pools with a limit per item, and the CPU caches
- Houses (
structures/houses.ts). The first tile whose records do not fit ends the list: no nearer tile is
left out while a farther one draws. No tile past it is asked.HouseStatscounts the tiles left out, and the
HUD's problems line shows them. ThenHOUSES,OUTLINE_BYTESandDRAWNtakeof, with a least of the largest
tile of A0. - Structures, kinds, water (
structures/structures.ts,terrain/water.ts): the byte sizes takeof, unit 4,
with a least from A0: the largest mesh, and the used bytes of the three views at 780 × 1688. - CPU caches through
of, each with the least of its working set from A0:NODE_BYTES(terrain/stamps.ts:
the stamp nodes of the mesh cells and of the drawn near pages), the decoded tiles ofstream/features.ts(four
times the largest tile), the ground worker's rasters (stream/ground-worker.ts),BODIES(terrain/pages.ts),
FEATURE_BODIES(stream/terrain.ts),BODIES(stream/ground.ts), the stamp worker'stileBudget
(terrain/stamp-worker.ts). - No worker count changes.
Not in this issue
- A render scale, a frame rate or a work budget that follows the frame time. A start rule without
budget=. A
smaller share after a lost device or a kill. Two shares. Each waits for the owner's run 1. - A cap on the
planpool. The instances' pools. The job counts. The ground cache planes at half size. A pixel
ratio under 2. - The stamp worker's heap in a town (100–150 MiB): a new issue, "the stamp worker keeps the shapes of the part of
a tile that its jobs read". It waits for A0's table with and without the baked stamp layer. - A hold of a left-out page while its cell's mesh fades. trailview: a terrain page shortage leaves out the farthest fine pages; their parents draw in their place #3268's follow-up N5 (a left-out page as an undrawn
resident) and its run R3 (a tall screen at a small pool).
Invariants
- With share 1, every pool has today's bytes. P1, A1 and A2 change no picture at share 1. B1 changes none in a
loaded view where every cell in range draws its mesh; it changes Lucerne, where cells have no block, by design. - A pool's size is a function of the share alone, and it does not change in a session. No size that follows the
share is a constant of a shader or a pipeline. - A pool or a cache takes the share only if it leaves out its farthest or oldest content first and counts what
it leaves out, and only at or over a least where its size is also a limit for one item or under a working set. - A left-out page draws until its stand-in draws. A page that fits and waits for a slot is not left out. A still
view always comes to idle: the intake never stops behind a waiting arrival. - A cell with a weight over 0 has a piece that draws in this frame; with the weight 1 the piece draws every
pixel of its mesh inside the radial plateau. A cell without a piece, a piece that cannot draw, and every cell
while the meshes do not draw have the weight 0. - Every terrain triangle that drops lies under a mesh that draws every pixel: a point sinks only where the field
is 1 with a triangle's reach to spare. - The mesh field depends only on the weights. No cell loses its mesh for another cell's cause; a cell without a
mesh costs its neighbours the band at its border. - A weight moves at most dt / 0.2 s a frame, except to 0 for a piece that cannot draw (a lost device,
finest=
under 17). A piece and its near block leave only at weight 0. A still view's picture depends only on the
targets. plan_fieldis the only place that decides how far the mesh reaches at a cell's border.
Done when
The orchestrator opens every picture. The owner judges look. A gate that fails means: stop, and report with the
numbers and the pictures. Runs: local GPU, one user at a time, MemoryMax=3G.
Data: the Engelberg fixture (builder/web/tests/browser/trailview/fixture); the demo release (demo/release-fix,
served as checkpoint2/READY.md says), with its views v17, m1 and Lucerne. Owner views:
quick-shortage/scripts/owner-views.json (3). Far views: builder/web/tests/browser/trailview/road-views-far.json
(18). Flights: the walk (601 frames) and the valley drive (1,201 frames) of
quick-shortage/scripts/flightq.mjs, on the fixture; the Lucerne drive (new): from the Lucerne view, 600 m along
heading 60° in 10 m steps. Viewports: 1920 × 960, 780 × 1688, 1688 × 780, at device scale 1.
P1.
terrain/pages.test.ts: a left-out page that draws keeps its slot until its stand-in draws; a stand-in takes
its child's slot; a page that fits and finds no slot is in neitherleftnorleftOutand is missing; a
stand-in behind a waiting arrival is taken in in the same frame; an arrival that the frame does not need and
that finds no slot is dropped; that still view comes to idle; no two pages share a slot or a copy.- The walk at
pool=0.5: 0 frames with a mesh over a page coarser than 17 (base 2); 0 frames without a mesh.
A1 with A0.
budget.test.ts(new):ofwith a unit and a least; share 1 givesfull;budgetOf.- Share 1, base | head:
stats().poolsequal per pool; the 3 owner views: 0 pixels differ. budget=0.4at 780 × 1688: pages 64.0, ground 93.6, features 30.8, shadow 5.3 MiB, each within one unit.budget=0.4, v17 and m1 at the three viewports, a still view of 300 frames and 4 s more: after the load no
change of the pages left out, of the quality or of the drawn cells; 0 frames in the 4 s. The sheets share 1 |
share 0.4 go to the owner, with no question.- A0, a report in the pull request:
- Share 1, the demo release's three views at the three viewports, and the flights: the demand per pool and
the working set per cache. Each demand of a pool of A1 at 780 × 1688 is at most its size at share 0.4; else
that pool gets a least. - The memory probe at share 1 and
budget=0.4, v17 and Lucerne, cold: per holder the idle and the peak size;
the VRAM and the GPU process's PSS less the pools, against a blank WebGPU page. The target, chosen so that
the table is worth acting on: under 50 MiB of the renderer stay unnamed; else the report says what does. - The stamp worker's heap and its wished tiles at Lucerne at 780 × 1688, with and without the baked stamp
layer.
- Share 1, the demo release's three views at the three viewports, and the flights: the demand per pool and
The owner's run 1 on his iPhone 13, after A1: the recipe in the first comment of this issue. It has
no pass. It gives: whether the page loads; the first share that ends, and which process; whether Safari has
timestamp queries; cpu and the frame interval. In a town it shows no way past the last cell with a block, until
#3273 B2. The page may reload at every share: A1 lowers only the GPU pools.
B1.
- Step 0, before product code, on TrailView ground plan: far cells build only their lines, and the pages of level 17 and 16 are drawn as strokes #3273 B2's allocator: Lucerne at
RECORDS_MB12.8, three loads: the cells that
hold a block; the largest block; theovercells whose rows the free rows hold in total but not in one run.
Pass: the same cells each time, and they are the nearest. plan/pieces.test.ts: the target of a weight; a step of dt / 0.2 s with dt capped; a cell without a piece (an
empty cell) has the weight 0; withmeshLevel0 every weight is 0 at once; a piece that is not drawable has the
weight 0 at once; a piece leaves only at weight 0; a replaced mesh keeps the old piece until the new one is
computed; each computed piece of the window has a slot;updatereturns true while a weight moves; no cell
rests for another.- Share 1, the fixture, loaded: the 3 owner views and the 18 far views, base | head: 0 pixels differ. With the
depthBias: pixels differ only past 390 m, and the sheet is opened. budget=0.4, and in a second runpool=0.3at share 1: the walk, the drive and the Lucerne drive, with
debug=cracksand withdebug=ownedon every 20th frame; and v17 withfinest=16, still: no new hole pixel;
no blue pixel inowned; once loaded, the eye's cell has the weight 1 in every frame of the fixture flights;
the count of fade-outs per run, and no cell with more than one in 2 s (else: a cell stays at weight 0 forCALM
frames before it comes back); the most slots used is at most 24; the frame time of the walk within the base's
spread.- Cold v17, three loads, base | head: the eye piece at weight 1 at most 0.25 s after the base's median.
- Pictures at 780 × 1688, base | head, Lucerne at
budget=0.4: a road that crosses a border to a cell without a
mesh, and a road that runs along such a border inside the band, each 5–15 m from the eye, as a still view and as
two frames 1 m apart while moving; the frames of the worst fade-out, with its first frame; a cold load of v17 as
a strip. Pass: no mottle and no crawl in the band, or thedepthBiasgoes in and the pictures are made again;
then the owner answers the one question: may the meshes fade into the page's look over the last 20 m before a
cell without a mesh, and come and go in 0.2 s?
A2.
budget=0.4, v17 and Lucerne: every drop is counted in the HUD; the houses left out are the farthest tiles; no
lake and no bridge of the three views is missing.- The memory probe at
budget=0.4, 780 × 1688, three views, cold, base | head: the renderer's peak PSS is lower
than the base's; the report gives idle and peak per holder. - Cold v17 and Lucerne, three loads each: share 1 base | head, and
budget=0.4base | head: the time to a clean
frame within the base's spread; no more tile decodes in the house worker and no more stamp nodes asked again
than the base (else that cache's least is too low).
In each pull request: the test files that cover the changed code, npm run check, npm run check:wgsl where a
shader changes (A1, B1), obc suites check where a test file is new. No new browser suite.
Risks
- No phone fact exists. Safari may not load the page at all (the ground decode through WebGL 2 in a worker,
clip-distances, six WASM memories). Run 1 comes right after A1 for that reason. - A1 lowers the GPU pools only. The renderer is as large as today until A2, so run 1 may end in a reload at every
share. - This issue does not reach 600–700 MB for the page: about 350–370 MiB of pools at share 0.4, plus the GPU
process's overhead, plus a renderer that nobody has taken apart yet. - The cross-fade of a mesh and its page 20 m from the eye is a new look, with two surfaces in one plane.
- The field's proof is an argument and two debug views; the shader has no unit test.
- The terrain of a fading cell comes back in one frame; slivers of the page show at walls and kerbs.
- A piece beside a cell without a mesh draws with a pipeline that discards, which costs hidden-surface removal on
an Apple GPU for that piece. In a dense town at share 0.4 that is most pieces. - In a dense town at share 0.4 the records hold about 4 near blocks, and a block needs one run of rows.
terrain/pages.ts,terrain/model.ts,plan/pieces.tsandplan/cells.wgslchange in TrailView ground plan: far cells build only their lines, and the pages of level 17 and 16 are drawn as strokes #3273 and in the water
work.
Activity
timohueser commentedon Nov 10, 2026
The recipe of run 1 (the owner, on his iPhone 13, after pull request A1)
The host is not set yet (
HOST). The orchestrator sets up an https host that serves the A1 build with the demo release before the run.For the orchestrator, before the run
ground-plan.HOSTmust be an https address with a trusted certificate (WebGPU needs a secure page) that the phone canreach. It must serve the
ground-planbuild with A1, with the demo release (demo/release-fix) as its activerelease. The repository has a deploy path to the VPS; the orchestrator sets the host up, checks the three
addresses below on the desktop, and puts the host in place of
HOST.budgetline, andcpuwith the frame interval in the first line.Why
No phone has run TrailView. This run gives four facts: does the page load in Safari; how much memory the phone
lets it hold, and which process ends first; does Safari give GPU times; how long a frame takes.
There is no pass and no fail. The page may reload at every share. That is expected, and it is a result: this
build is smaller only on the GPU side. Nothing can break: a kill only reloads the page.
Before you start
WebGPU (this path is from memory, not checked). Note the iOS version.
must stay open, note which.
phone.
The three views (add the part after
&that each step names):https://HOST/trailview.html?lat=46.821866&lon=8.404830&heading=153.3&pitch=-8&eye=1.7&date=2026-08-15&time=10:30&weather=sunny&ground=planhttps://HOST/trailview.html?lat=46.7905&lon=8.3933&heading=200&pitch=-5&eye=1.7&date=2026-08-15&time=10:30&weather=sunny&ground=planhttps://HOST/trailview.html?lat=47.05135&lon=8.30525&heading=60&pitch=-8&eye=1.7&date=2026-08-15&time=10:30&weather=sunny&ground=planSteps
"Wait" means 60 seconds, or less when the picture and the HUD's numbers have stopped changing.
&budget=0.4&budget=0.6, then0.8, then1&budget=0.4&scale=0.25, then&budget=0.4&scale=0.75&budget=0.4&budget=0.4&budget=0.4When to stop or skip:
screen flashes black twice in a row. Do not try a third time: after a black flash the page takes the same
memory again.
Step 1 is the only first load. Steps 2 to 6 load from what the phone kept of step 1, so they are faster and a
little lighter. That is fine; it is noted on our side.
Do not judge the Lucerne picture. Until the far look (#3273 B2) lands, a town shows no road past the last cell
that has its road data: about 900 m from the eye. That is known and is not what this run asks.
Do not judge the looks at all in this run. A sheet of pictures comes for that.
What to send back
The screenshots, the iOS version, and one line per step: "1: 12 s, fine", "2: 0.6 fine, 0.8 reload", and so on.
What the notes mean (for the orchestrator)
LEAST, and how far the 600–700 MB target is from the real limitbudgetline:timestamps yesorno,clip yesorno, the adaptercpu … ms, the frame interval, and the GPU time if there is one, at scale 0.25 and 0.75cpuis near the interval, the main thread doesoverin the HUD's "!" line