Repository navigation
Description
Status: approved
Part of #2747. Related: #2863 (the quality controller), #3096 (the road rebuild), #3651 (structures as ready-made parts), #3765 (the app spike), #3685 (the shader shrink of the new roads).
TL;DR
Goal: In the iOS app on the iPhone 13, TrailView shows the view about the eye within 4 s of a cold open, holds a steady 30 frames per second with a GPU median of at most 20 ms per frame (60 % of a frame), and never uses more than 896 MiB during a load or a session (GPU memory included). Its look has the owner's approval. It is the same engine as on the desktop, with a phone tier of values.
Problem: iOS stops a web page at about 1,408 MiB on the iPhone 13 (#3765). The lighter preset P of the lever measurement still uses 1,120 to 1,216 MiB after one walk load. The page and the engine with no data take about 256 MiB. The largest part of the rest, about 512 MiB, is the data that the workers keep after the load. Each CPU cache has a fixed byte cap, and the caps add up to more than one load fills, so a long session can grow past that: 10 minutes of driving added 96 MiB. With P, the GPU takes 21 to 22 ms per frame (median). A redraw of the far shadow map takes about 12 ms and makes the longest frames. After about 3 minutes of loads the phone is warm ("fair").
Decision:
- One budget table in the engine. Each GPU pool, each CPU cache, each worker count and each count of loads in flight has one row with a desktop value and a phone value. Each module reads its size from the table, not from a constant of its own. A worker gets its values in its first message.
- The tier is chosen once, at the start, as the render scale is. The iOS app opens TrailView with
tier=phonein the address, on every iOS device, an iPad too. Every other host gets the desktop tier. - The budget is a sum. A unit test adds the phone's byte caps of the CPU caches, and fails above the sum that the Plan assumes. On the phone, a run proves the peak: each scene loads after the page takes 512 MiB of other memory first (1,408 − 512 = 896), and a 10-minute drive ends with at least 512 MiB of headroom.
- Place before cutting. Phone runs that end one kind of worker at a time placed the memory before the Plan. The caches of the workers hold the most, so the Plan cuts them first.
- The phone values: 30 fps, a coarser far terrain, smaller pools and caches, fewer workers, half the loads in flight. The render scale stays at the desktop's 0.7, and both shadow maps stay. Each value has its measured or expected saving in the Plan.
- The look: each cut that the eye can see gets a before/after gallery, rendered on the M1 Pro at the phone's size. The owner approves the gallery before the cut merges.
- The ground plan: it becomes the only path with TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110, so the table has its rows (records, masks, plan workers, mesh range). Until it compiles on the phone (TrailView parts P8: the old tunnel code of the new roads goes #3685), the phone runs measure today's path, and the plan's rows come from the M1 Pro at the phone's size.
Rejected:
- A native renderer, or a second viewer for the phone (the owner, 2026-11-21). The memory is the loaded data, and a native renderer holds the same data.
- A memory controller that changes the pools at run time. WebGPU reports no free memory, and iOS stops a page with no warning. Values chosen at the start can be tested; TrailView: fit the device: dynamic resolution for 60 fps, and memory tiers #2786 also chose its memory tiers once.
- Dropping the far shadow map on the phone. Without it, a view more than 100 m above the ground has no object shadows (the gallery of 2026-11-21). The owner keeps it: a redraw of about 12 ms after 400 m of movement is an acceptable cost.
- The tier from device signals (adapter limits,
navigator.deviceMemory). WebKit has nodeviceMemory, and the app knows that it is the app. - A dynamic render scale to hold the frame time on the phone. On the iPhone 13 the scales 0.5 and 0.7 give the same GPU time.
- Cuts of the tree ranges, the small objects, the street lamps and the finest terrain level. On the phone each changed the GPU time and the memory by less than the noise, so they keep their desktop values.
Systems: trailview, trailview-page
Contracts: none
Size: L (set by explore; an epic of several pull requests)
Facts
On the phone (app host, iPhone 13, preset P, walk; comments of 2026-11-21):
- After a walk load, P's footprint is 1,120 to 1,216 MiB (two sessions). The parts: the page and the engine with no data and no workers, about 256 MiB; the 11 workers with no data, about 64; the data of the workers, about 448; the pools, the JavaScript of the main page and the rest, about 352 (ending the engine gave back 128 of it within 10 s). The kinds of worker, ended one kind at a time, gave back 416 MiB in all; all workers at once gave back 512. One minute with the view still gives nothing back.
- The peak of a load is above about 1,008 MiB: with 400 MiB taken first, iOS stopped the load.
- GPU time, the median of each pass when it runs: main pass 13.4 ms, vegetation 5.9, near shadow casters 5.5, resolve 2.4, ground look 1.8, far shadow casters 11.8. The GPU median per frame is 21 to 22 ms. The render scales 0.5 and 0.7 give the same time.
- Load, cold: eye ready 2.1 to 2.8 s (once 6.3 s), near ready 3.3 to 4.4 s, complete 11.7 to 17.7 s.
- Levers against P: far shadows on add the longest frames (158 against 75 ms) and about 96 MiB. The terrain range × 0.8 saves 4.5 ms of GPU time and about 96 MiB, and the frames over 33 ms go from 64 % to 27 %. The tree ranges, the small objects,
finest=17and the loads in flight change the time and the memory by less than the noise.
On the M1 Pro (headless Chromium on Metal, the phone's canvas of 780 × 1688):
- P's JavaScript after the flight is about 420 MiB: main page 104 + canvas 15, ground workers 2 × 80–85, stamp 64, road 49, houses 13, tree models 3 × 3, plants 1, terrain decode 2 × 1.
- P's pools are 409 MiB, the same count as on the phone. With
ground=planthey are 462 MiB: feature masks 82, records 32, plan pieces 20, and no road pool. The two plan workers hold 37 MiB each. - The ground look of P holds 64 pages; the walk wants 102. At the default of 192 pages it holds 138.
In the code (develop bddbbcf, paths under builder/web/src/lib/trailview/):
- Worker caps: ground decode 96 MiB per worker, 2 workers (
stream/ground-worker.ts:18); stamp 48 MiB (terrain/stamp-worker.ts:19); house 32 MiB, the default oftileBudget, whichstructures/house-worker.tsdoes not call; road 55 MiB and 9 decoded ground tiles of 1 MiB (roads/road-worker.ts:8,roads/ground.ts:23); plan 55 MiB per worker (HEAP_LIMITofplan/plan.ts:27, checked inplan.tsandterrain/model.ts), 2 workers (WORKERSofterrain/model.ts, whichsrc/trailview.tsgives topreload); tree models 3 workers (WORKERSofvegetation/tree-models.ts). - The caps are not hard limits. A worker's tile cache keeps the tiles that a view wants, and the newest one, past its cap (
triminstream/features.ts); on the phone the stamp worker gave back about 160 MiB against its cap of 48. A plan worker restarts above its heap limit only when no job waits (terrain/model.ts:259). - Main-page caps: stamped nodes 64 MiB (
terrain/stamps.ts:12), road meshes 32 MiB (roads/roads.ts:30), plan records 32 MiB (plan/plan.ts:25), encoded terrain bodies 64 MiB (terrain/pages.ts:15): a page that comes back into the pool decodes its kept body again, the plan's records and cells read their tiles from it (pages.body), and a new device after a lost one gets its pages again without a request, feature bodies 32 MiB (stream/terrain.ts:13), ground bodies 16 MiB per archive, six archives: the ground, the four colour quarters and the snow (stream/ground.ts:24). - Pools: terrain pages 104 + 67 MiB, scaled by
pool=(terrain/terrain.ts:34); feature masks of 128 pages, 32 MiB per texture, four textures withground=plan(terrain/terrain.ts:41); ground look 192 pages (ground/ground.ts:14); records 32 MiB (RECORDS_MBofterrain/model.ts); shadow maps, 2 cascades of 2048 × 2048 (light/shadow.ts). - The near shadow map fades out between 50 and 100 m above the ground, the far map up to 1,638 m (
aboveofCASCADESinlight/shadow.ts). Above 100 m only the far map gives object shadows. - A shadow map draws again when the eye moves 50 m (near) or 400 m (far), when the sun turns, or when new casters arrive (
Shadow.dueinlight/shadow.ts). A still view draws none. - The phone renders 1,182 rows: the canvas is 1,688 pixels high (the engine caps the pixel ratio at 2) and the render scale is 0.7. There
bestRangegives 4.0 node sizes, below the least, so the terrain range is the least, 4.6 (RANGEinterrain/lod.ts:21,bestRangeinterrain/terrain.ts:1085). Below it, neighbouring nodes can fail to meet. - The lever run's terrain range × 0.8 multiplied after that least: 3.7 node sizes. A least of 3.7 alone gives 4.0 on the phone, the value of
bestRange.lod.test.tsat 3.7 finds 41 grid vertices outside their node's level at walk height. With the morph band at 0.15 levels in place of 0.3, the test passes at 3.7 from all four of its eyes. The morph band isMORPHoflod.ts;drawn-height.wgsl,plan/cells.wgsl,plan/pieces.tsandroads/corridor.wgsluse it too. The choice of the drawn nodes does not read it (splitofcdlod). scale,poolandfinestcome from the address once and go toTrailView.start(view.ts,engine.ts:241). A worker cannot read the address.- TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110 deletes the road worker, the road meshes and the road pool, and makes the plan path the only path.
Plan
The budget
The budget is the footprint of the page on the iPhone 13: 1,408 MiB minus the headroom that the kit's probe finds, in steps of 32 MiB. The kit measures a part by the headroom that the probe gains when that part ends (after= of phone-measure.js on the prototype branch). The column "P" is preset P on today's path (sessions of 2026-11-21). The phone tier stays at or under 896 MiB after 10 minutes of driving and at the peak of a load.
| Part | P | Phone | How |
|---|---|---|---|
| The page and the engine with no data and no workers | 256 | 256 | no change |
| Ground decode workers (2) | 160 | 40 | decoded images kept: 96 → 16 MiB per worker |
| Stamp worker | 160 | 80 | feature tiles kept: 48 → 24 MiB |
| Road worker | 64 | 0 | #3110 deletes it |
| Plan worker | none (2 × 37 on the M1 Pro) | 40 | one worker; its heap limit 55 → 40 MiB |
| Terrain decode (2), house, tree model (3) and plant workers | 32 | 16 | the tree model workers end after 10 s with no job; house tiles kept: 32 → 16 MiB |
| Workers, not placed by kind | 96 | 96 | all workers at once gave back 512, the kinds one at a time 416; no cut assumed |
| Pools, the main page's data and the rest | 352 | about 314 | the main page's caches about −100 (stamped nodes 64 → 24 MiB, plan records 32 → 16, encoded terrain bodies 64 → 16, feature bodies 32 → 8, ground bodies 6 × 16 → 6 × 2); coarser far terrain (T3): this budget counts −32, one run measured −96, within the noise; the far shadow map +11, which P did not have; the plan path's pools +53 (M1 Pro count) |
| After a walk load | 1,120 to 1,216 | about 842 | |
| Growth in 10 minutes of driving | 96 | not known; the smaller caps hold less | valley drive, to and fro: 1,184 after the load, 1,280 after 10 minutes |
| After 10 minutes of driving | 1,280 | gate ≤ 896 | the soak run (p-soak of the kit) |
| Peak of a load | > 1,008 | gate ≤ 896 | each scene loads after 512 MiB of ballast |
The worker rows are what the probe gains when that kind ends. On the phone the ground decode workers hold what Chromium reports. The stamp worker holds more, because for each tile that it keeps it also keeps the tile's shapes and their grid index, which its cap does not count (#3793). The pools allocate 409 MiB with P (462 with the plan path); iOS counts only the parts that a view has written, so a long session writes more of them.
The budget is at its limit: the phone column after 10 minutes is about 842 plus a growth that P had at 96. #3778 runs the soak at tier=phone as soon as it merges. If it is above 896 MiB, the next levers, in order:
- The stamp worker keeps less for each feature tile (TrailView phone tier: the stamp worker keeps less for each feature tile #3793): a smaller grid index, and coarse tiles keep only the lines that their nodes read. In a replay of the walk, its peak falls from 209 to 48 MiB.
- One ground decode worker on the phone: about −25 MiB, and the ground jobs of a load run one at a time.
- A placement session at
tier=phonefor the 96 MiB that no kind explains.
On the phone the new roads draw their ground mesh as on the desktop, with one plan worker in place of two. The device cache does not change: the app keeps what the workers make (the plan's cells, the stamped nodes, the house records, the tree models) in the page's Cache Storage, up to 296 MiB on the disk (CAPS of terrain/device-cache.ts). That is disk, not memory. The GPU time of the plan path on the phone is not known until #3685; the epic's last check measures it.
The cuts
Each cut against its desktop value. P has the cuts of T1 already, so they are in the column "Now" of the budget. P also had no far shadow map; the phone tier keeps it, which adds the map (about 11 MiB) and its redraws to the column "Phone".
| Cut | Frame | Memory | Load | Look |
|---|---|---|---|---|
| Terrain pages × 0.5 (T1) | – | 32 MiB against the full pool (measured) | – | coarser far pages where the pool is short: gallery |
| Ground look 64 pages, from 192 (T1) | – | needed to load at all (measured) | – | coarser far ground; 38 of 102 pages short: gallery |
| Half the loads in flight (T1) | – | lower peak (expected) | complete 17.7 against 24.7 s (measured, one session) | none |
| 30 fps (T1) | the GPU idles between frames | – | – | none |
| Worker and main-page caches (T2) | – | about 300 MiB (expected from the kind runs) | tiles that leave a cache decode again when the eye comes back: expected under 1 s more to complete | none |
| One plan worker (T2) | – | about 40 MiB (expected) | the near mesh completes later: measured in T2 | none |
| Tree model workers end when idle (T2, both tiers) | – | about 9 MiB (expected: 3 × 3 MiB on the M1 Pro) | – | none |
| Coarser far terrain: the least range 3.7 node sizes, from 4.6, and the morph band 0.15 levels, from 0.3 (T3) | GPU −4.5 ms; frames over 33 ms 64 % → 27 % (measured with the range alone) | 32 to 96 MiB (one run measured 96, within the noise) | – | coarser far terrain, and the near meshes of the new roads end at about 0.89 times the desktop's distance, where level 18 ends: gallery; the shorter morph shows only in motion: the owner watches a walk in one viewer window |
The range alone does not work: below 4.6 node sizes, neighbouring terrain nodes do not meet (Facts). A narrower morph band lets them meet at 3.7. The choice of the drawn nodes does not read the morph band, so the measured GPU time holds.
The render scale (0.7), the tree ranges, the small objects, the street lamps and the finest level keep their desktop values: on the phone each changed the GPU time and the memory by less than the noise. The render targets are made for the largest scale in any case (MAX_SCALE of resolve/targets.ts). No object kind goes on the phone. The fixed values of the tier hold the frame rate, with no quality controller (#2863).
The galleries
Each sub-issue with a visible cut renders a gallery before its pull request merges: the desktop tier against the desktop tier with that one cut, and the desktop tier against the whole phone tier. The renders run on the M1 Pro (headless Chromium on Metal, shoot.mjs, a canvas of 780 × 1688), at the start of the four scenes of the kit (walk, valley drive, zoom-out, bridge and tunnel) and two far views, because the far views must stay the most similar. One local page shows each pair: with, without, and the difference, with a hover to flip. The owner approves in a comment on the sub-issue.
Sub-issues
Each sub-issue holds its plan steps.
- TrailView phone tier: one budget table,
tier=phoneand the values of preset P #3777 The phone tier: one budget table,tier=phone, and the values of preset P - TrailView phone tier: smaller caches and fewer workers #3778 The phone's caches and workers
- TrailView phone tier: a coarser far terrain whose nodes still meet #3779 A coarser far terrain on the phone
- TrailView phone tier: the stamp worker keeps less for each feature tile #3793 The stamp worker keeps less for each feature tile (the first lever after TrailView phone tier: smaller caches and fewer workers #3778's soak)
Files
Paths under builder/web/src/lib/trailview/ unless they start with builder/.
#3777 (the phone tier):
budget.ts: create: the tiers and the values of each.view.ts: change:tierOfin,poolOfout.engine.ts: change:TrailView.starttakes the tier and gives each part its values.terrain/terrain.ts,ground/ground.ts,pacer.ts: change: the page bytes, the ground pages and the frame rate come from the budget.terrain/pages.ts,ground/pages.ts,structures/houses.ts,terrain/stamps.ts,vegetation/canopy.ts: change: the loads in flight come from the budget.builder/web/src/trailview.ts: change: reads the tier from the address.README.md: change:tierin the table of address options.
#3778 (caches and workers):
stream/ground-worker.ts,stream/ground.ts,terrain/stamp-worker.ts,terrain/stamps.ts,structures/house-worker.ts,structures/houses.ts,plan/bridge.ts,terrain/model.ts: change: each worker gets its cap, heap limit or count from the budget.plan/plan.ts,terrain/pages.ts,stream/terrain.ts: change: the main page's caches come from the budget.vegetation/tree-models.ts: change: an idle worker ends.budget.ts: change:PHONE_CAPS.budget.test.ts: create: the phone's caps add up to at mostPHONE_CAPS.
#3779 (far terrain):
terrain/lod.ts: change:cdlodtakes the morph band;MORPHgoes.terrain/lod.test.ts: change: the selection test runs at the values of each tier.terrain/terrain.ts: change: the least range and the morph band come from the budget; the morph band goes into the surface uniform; the comment ofPROBE_ABOVE_M.terrain/drawn-height.wgsl,plan/cells.wgsl,roads/corridor.wgsl: change: the morph band from the uniform.plan/pieces.ts: change: the morph band from the rule.budget.ts: change: the least range and the morph band of each tier.
Outside develop: the kit's variant p on the prototype branch becomes tier=phone. No guide page changes.
Done when
Each sub-issue, in builder/web:
npx vitest run src/lib/trailviewandnpm run checkpass; TrailView phone tier: a coarser far terrain whose nodes still meet #3779 alsonpm run check:wgsl.- TrailView phone tier: one budget table,
tier=phoneand the values of preset P #3777 and TrailView phone tier: a coarser far terrain whose nodes still meet #3779: the owner approves the gallery in a comment on the sub-issue. - TrailView phone tier: a coarser far terrain whose nodes still meet #3779: the crack flight at
tier=phonefinds no cracks, and the owner has watched one walk in the viewer. - TrailView phone tier: smaller caches and fewer workers #3778: on the phone at
tier=phone, the kind runs (p-end-*) give back at most the phone value of each worker row plus one probe step (32 MiB), and the soak (p-soak) ends with at least 512 MiB of headroom. If it does not, the next lever of the budget becomes a sub-issue.
The epic, after #3777, #3778, #3779, #3673, #3685 and #3110, in one phone session that the owner runs (about 35 minutes, iPhone 13, the app host of the prototype branch, tier=phone):
- Each of the four scenes loads with 512 MiB of ballast.
- The soak (10 minutes of the valley drive, to and fro) ends with at least 512 MiB of headroom.
- On the walk, the GPU median is at most 20 ms, and the 95th percentile of the frame interval is at most 40 ms.
- Eye ready within 4 s of a cold open, and within 8 s of the first open after an install.
- The soak, run unplugged, ends at the thermal state "fair" or better.
Limits
The owner's words of 2026-11-18:
- The phone gets the same TrailView, with almost all code shared. It is not a second viewer.
- Settings can be lower on the phone: the render distance, the resolution.
- Objects can go on the phone if they cost too much. His examples: street lamps, benches, signposts.
- The look is similar to the desktop. The far views above all are very similar.
- 30 frames per second on the phone is fine. More is better.
- TrailView runs inside the iOS app, not in the browser of the phone.
- The work is planned and done in order, not in a hurry.
From the earlier decisions: the target device is the iPhone 13. The two costs that count are the frame time and the time to the first complete picture.
Out of scope
- The web planner on a phone browser. Phone browsers get "download the app".
- Android.
- Touch controls for walk and fly (the owner, 2026-11-21: an issue of their own).
- The TrailView screen of the released iOS app. The measurements use the host of the prototype branch
prototype/trailview-ios-app.
Requirements: none
Generated by Claude Code
Activity
timohueser commentedon Nov 18, 2026
Findings of the two fault-check runs on the iPhone 13 (2026-11-18)
The fault check is a second page of the measuring kit (
/phone/diagnose, branchclaude/trailview-phone-measure). It sends the errors of each shader and pipeline, pictures of the canvas, and the heights at three stages. Sessions on the owner's PC:phone/results/20261118113457-d9e4and20261118195400-du5n; the same check on the PC is20261118145602-d54s.probe()instream/ground-worker.ts). WebKit multiplies the colour by the alpha when it decodes an image. The ground tiles hold data under a low alpha, so the test fails and the engine draws no ground.claude/trailview-safari-faults(a WebP decode in WASM for browsers that fail the test). It is not built and not tested.audit, after 41 s forstampwith the road model). No buffer and no texture failed. The samestampmodule compiles without the road model (heights.wgsl).If the hypothesis is correct, the height rules of the new roads in the shader (
terrain/heights.wgsland what includes it) are too large for the phone as one program. The options are: smaller passes, a call of the heavy functions at one place only, or heights that the CPU or the bake makes for the phone. This is a question for the design of this issue, and it touches #3651, which removes the tunnel rules from these shaders.Generated by Claude Code
timohueser commentedon Nov 18, 2026
The size test confirms the hypothesis (iPhone 13, 2026-11-18, session
20261118201642-cgoe)The page
/phone/compileof the measuring kit compiles the refused shaders in smaller sizes, each in a new page load. The size is the length of the code after each call is copied into its caller, which is what the Metal compiler does.audit, wholeaudit, 70 %audit, 45 %stampwithout the road model, wholestampwith the road model, 25 %stampwith the road model, 50 %stampwith the road model, wholeA small shader compiles directly after a refusal, in the same page load. So a refusal does not break the device for other shaders.
Result: the Metal compiler of the phone has not enough memory for the largest shaders. The limit of
auditlies between 266 kB and 383 kB. The size ofstampwith the road model is not measured correctly by the page (it shows the size without the model), so its limit is known only as a share: between 50 % and 100 %. The shaders must become smaller by a part, not by a factor of ten.Generated by Claude Code
timohueser commentedon Nov 18, 2026
The "spiky" terrain of the first run did not show again in any later run on the iPhone 13 (two fault checks, one measurement with four flights). The owner confirms it (2026-11-18): the terrain is correct on screen, and with the ground fix of #3673 the view has its ground look and its forest. The cause of the spikes in the first run is not known. Numbers of the measurement with the fix (today's app, no stamp layer in the test data): first complete picture 9.3 s (walk), 11.6 s (valley), 31.1 s (zoom-out), 18.1 s (bridge and tunnel); frame median 29 ms, 49 ms, 29 ms, 35 ms; pools 616 MiB. The new roads still do not start (the shader size).
Generated by Claude Code
timohueser commentedon Nov 21, 2026
The owner's goals for TrailView on the phone (2026-11-21)
The owner's words, in short:
The iOS app spike #3765 comes first. It answers whether the web view of the app runs TrailView as well as Safari.
Generated by Claude Code
timohueser commentedon Nov 21, 2026
The owner's budgets for the phone tier (2026-11-21)
After the app spike #3765, the owner set these targets for TrailView in the iOS app on the iPhone 13:
The measurements that these targets apply to are in #3765. In short: one web page on the iPhone 13 has about 1.4 GB of memory, GPU memory included, and the load of today's TrailView goes over it. A native app has about 2.1 GB. When TrailView survives its load, the frame time is 41 to 71 ms, the GPU time is 28 to 33 ms, and the view is complete after 27 to 42 s.
Generated by Claude Code
timohueser commentedon Nov 21, 2026
Lever measurement on the iPhone 13 (2026-11-21)
The app host of #3765, two sessions on the walk flight, the phone unplugged. Session A started "nominal" and ended "fair"; session B started "fair" and reached "serious" after 2.5 minutes, so its GPU times are about 3–5 ms higher. Build and data as in #3765. Branch
prototype/trailview-ios-app(throwaway switches).The phone preset P:
scale=0.5, terrain pool 0.5, ground-look pool 0.33, near shadows only, tree ranges ×0.5, no small objects and no street lamps, requests in flight ×0.5, 30 fps. "Headroom" is the memory that a probe could add after the flight before iOS stopped the page (steps of 32 MiB). A web page has about 1,408 MiB.scale=0.5&pool=0.5), for comparisonscale=0.7(B)finest=17(B)GPU passes of P (A, median of each pass when it runs): main pass ("terrain": the terrain, houses, roads and objects) 13.4 ms, vegetation 5.9 ms, near shadow casters 5.5 ms (when the near map is drawn), resolve 2.4 ms, ground look 1.8 ms. The far shadow casters cost 11.8 ms each time the far map is drawn.
What the levers show:
terrain/lod.ts).finest=17and requests in flight change the GPU time and the memory by less than the noise. They can stay at their desktop values.groundShort38 on the walk).Generated by Claude Code
timohueser commentedon Nov 21, 2026
Where the memory of the phone preset goes (2026-11-21)
Follow-up of the lever table above. Same preset P, same build and data. "Footprint" is about 1,408 MiB (the limit of a web page on the iPhone 13) minus the headroom that a probe could still fill.
So the engine's fixed cost is small: 11 workers, 60 pipelines from 30 shader modules (1 MB of WGSL), and the pools before they hold data. The load of one view adds about 900 MiB.
What the load fills, measured as far as possible:
createBufferandcreateTextureof the page, counted on the phone: the same as the pools. Nothing large is outside them.measureUserAgentSpecificMemoryafter a full load of P (headless, SwiftShader). WebKit's numbers can differ.The empty pools cost little because iOS backs a GPU allocation only when it is written. They count fully once a view fills them.
For the design:
prototype/trailview-ios-app:phone-measure.jscounts the GPU objects (memory.alloc), the variantp-emptymeasures the fixed cost,phone-wasm.jsreports each worker's WASM, and the kit's local listener (--local) lets Chromium split the JavaScript memory by worker.Generated by Claude Code
prototype #3656: the probe after a still minute, after the workers en…
timohueser commentedon Nov 21, 2026
Where the memory of the phone preset goes: the placement (2026-11-21)
Follow-up of the comment "Where the memory of the phone preset goes". Same build, data and preset P. App host, iPhone 13 unplugged. Each run is a cold walk load with its 20 s flight, then the step of the run, then the memory probe in steps of 32 MiB. Session
app-20261121144156-pr7c(results of the kit on the Mac). Kit: branchprototype/trailview-ios-appat 60acffe, address optionafter=ofphone-measure.js.destroy()destroys every pool), and the workers endThe footprint of P in this session is about 1,120 MiB (1,408 − 288). In the session of 14:05 it was about 1,216 MiB: two sessions differ by up to 96 MiB.
The same preset on the M1 Pro (headless Chromium on Metal, the phone's canvas of 780 × 1688, two runs): the JavaScript after the walk flight is 417–423 MiB, not 245 MiB. The earlier figure was read before the flight. Main page 104 + canvas 15, ground workers 2 × 80–85, stamp 64, road 49, houses 13, tree models 3 × 3, plants 1, terrain decode 2 × 1. With
ground=plan, the GPU pools are 462 MiB (feature masks 82, records 32, plan pieces 20, no road pool), and the JavaScript is about the same: two plan workers of 37 MiB each take the place of the road worker.What this places:
Each kind of worker (session
app-20261121160859-hhhi)P on the walk, then one kind of worker ends, then the probe. This session had no run of P alone; the table takes P's 288 MiB of the session before.
The kinds add up to about 416 MiB; all 11 workers at once gave back 512 MiB. The difference is within the noise between sessions (up to 96 MiB).
Generated by Claude Code
tier=phoneand the values of preset P #3777prototype #3656: a 10-minute soak of P, then the probe
timohueser commentedon Nov 21, 2026
Does a session grow? The soak of preset P
Session
app-20261121190117-jv6r(iPhone 13, the app host ofprototype/trailview-ios-app, commit 20001fd), plugged in. Both runs fly the kit's valley drive; the probe fills memory in steps of 32 MiB until iOS stops the page.pp-soakTen minutes of driving add 96 MiB (three probe steps). The engine counts the same pools at the start and at the end (409 MiB), so the growth is in what iOS counts: more written pool parts, fuller caches, or both. The ground jobs: 1,848 in the soak, none failed; the ground look was short of 17 pages at the end.
The design now gates the soak at
tier=phone(≤ 896 MiB, the owner's limit of 2026-11-21) and runs it as soon as #3778 merges.The shadow gallery of the same day (11 views at 780 × 1688, the near map against both maps) showed that without the far map, views more than 100 m above the ground lose every object shadow. The owner keeps the far map on the phone.
timohueser commentedon Nov 21, 2026
Turn reuse prototype on the iPhone 13 (2026-11-21)
The turn prototype (
reuse=1, from the turn optimization session) ran once on the iPhone 13 in the prototype app. Preset P (pacer 30, scale 0.5), canvas 780 × 1688, eye at rest at the start of the walk, phone unplugged. Kit: commits 95c0651 and cbb09e6 on draft PR #3768.Variants: off; reuse (margin 1.25, 15 scene frames/s); margin (1.5 × 1.1, 8/s); lead (1.5 × 1.1 ahead of the turn, 5/s).
reuse=1, iOS ended the page 10 s into the load. This is one sample, so the cause is open: the 27 MiB of wide targets on top of a load near the limit, or chance.For T3 (coarser far terrain): these runs do not remove the need for it. Turn reuse helps only if a turn's scene frame stays within one frame budget on the phone, for example with a lower render scale for the wide frames. That is not tested.
prototype #3656: the turn prototype (reuse=1) and its phone runs
prototype #3656: turn frames wider on one axis, and ahead of the turn
prototype #3656: the second phone run of the turn prototype
timohueser commentedon Nov 21, 2026
Turn reuse, second iPhone 13 run: turn step cut for the phone, load step passes (2026-11-21)
Setup as in the first run (preset P, canvas 780 × 1688, eye at rest, unplugged). Kit commit 5821c70 on draft PR #3768. The stop rule was agreed before the run between the turn session and the phone session.
Turn step. The candidate is margin 1.1 × 1.02 ahead of the turn, at 15 scene frames/s. It had to pass all three checks on both scenes: fps within 1 of off, p95 interval within 10 % of off, and at least 25 % less GPU per shown frame.
The candidate fails all three checks on both scenes. The wide margin (1.5 × 1.1) at 15/s gave 46 ms scene frames, against 67–70 ms at 5–8/s in the first run. So the GPU clock adds cost at low rates, but the wider frame is also real work. The thermal state was "nominal" for the off runs and "fair" for the candidate runs.
Load step (
reuse=1&margin=1,1, no wide frames), two loads each:Verdict of the turn session (quoted): "the turn step is cut for the phone, and the load step passes." A normal frame already takes 27–30 ms of the 33 ms budget, so any scheme that makes some frames larger drops frames. The phone needs a cheaper normal frame first. The load step may come back as its own change. Whether the cut also ends the turn step on the desktop is the owner's decision.
prototype #3656: the kit's P is tier=phone, the zoom-out starts above…
timohueser commentedon Nov 21, 2026
#3778 on the iPhone 13: the caches at
tier=phone(2026-11-21)The soak misses its gate: it ends with 416 MiB of headroom, and the gate is 512. The kind runs also miss their gates for the ground workers, the stamp worker and the small workers. The next lever is #3793.
Setup: the iPhone 13 in the prototype app (draft PR #3768, kit commit f0d3d77, which holds PR #3789). The kit's variant
pis nowtier=phone. The tier keeps the far shadow map and the render scale 0.7, which preset P did not have. Each run is a cold load. A headroom is what the probe can still fill, in steps of 32 MiB. Two sessions:app-20261121205441-2vcb(6 runs) andapp-20261121211443-k98l(the base run).tier=phonep-empty)p)p-soak)The footprint (1,408 − headroom):
What each kind gives back (its run minus the base of 448), against #3778's gate (the phone value plus 32):
The noise is large. The road worker's cap did not change, but it gave back 160 MiB against 64 with P. There is only one base run, and P's base differed by 96 MiB between sessions. So each gain above can be off by about ±96 MiB. The ground and small-worker misses are within that noise. The stamp worker's is not: it holds more than its 24 MiB cap allows, and more than with P's cap of 48. Its cap does not bound it, because it keeps the tiles that a view wants, and WebKit holds its decoded features as many small objects.
Load times show no change: eye ready 2.1 to 2.4 s (the first run of the session 6.5 s, a first open), near ready 3.4 to 5.4 s, complete 11.7 to 15.4 s. The full turn completed in 14.6 s (P: 13.4 and 13.6 s), one sample. Soak frames: interval median 31 ms, p95 49 ms. GPU median 23.6 ms (P: 22.8 ms with scale 0.5 and no far shadows).
What is not in yet: #3110 deletes the road worker (about 64 MiB with P), and #3779 makes the far terrain coarser (32 to 96 MiB). With both, the soak lands at about 832 to 896 MiB, at the gate with no margin. So the next lever starts now: #3793, a compact form of the decoded features in the stamp worker.
Time: the phone sessions took about 17 minutes, and the analysis about 10.
timohueser commentedon Nov 21, 2026
The load step of the turn prototype ships as #3790 (design #3784): a view at rest draws 10 frames a second while it loads. iPhone 13, 8 cold loads of the walk view in both orders: GPU time −20 % (median 8,612 → 6,880 ms), drawn frames about halved, time to idle 14.0 s median in both, all loads survived. The table is in the pull request.