karti
2aa4049258
**Seven new shots**, because the world grew the most photogenic things in it
after the last pass: `sfo`, `lax`, `golden-gate`, `bay-bridge`, `freeway`,
`california-relief` and `pacific-sea`. All nine existing ids are unchanged — the
manifest emits a `ShotId` union that lumbridge-v4 imports, so ids are added and
never renamed.
**A shot can now aim itself.** The chapter list has no camera for SFO, LAX, the
bridges, the freeway or the open sea, and the engine has no `?pose=` back door,
so a shot points itself by driving the app's own inputs: a click on the plan view
slides the orbit target to a lat/lng while keeping the chapter's stance, wheel
notches set the standoff, and a drag sets azimuth and elevation. The plan view's
pixel-to-coordinate map is solved at runtime from three hovers of
`#minimap-readout` rather than hard-coded, so it survives a board resize or a
restyle of the widget.
**The tera share card was a picture of the wrong thing, and had been.** Its art
came from `keyboard.press("2")`, which had landed on the California board's drive
mode once the default board changed — so the card under the headline "Cities from
above." was a chase camera on US-101, showing metre-scale cars driving between
kilometre-wide buildings, with the DRIVE readout and the mode pill baked into the
art. It renders, it looks deliberate, and it is why an unguarded key press has no
place in a capture script. `capture.mjs` now clicks an indexed chapter and
asserts its `shortLabel` the way `shots.mjs` does, waits on `#boot` and
`#chapters` instead of sleeping twenty seconds, and gives each card its own hour.
**`npm run refresh` is the durable half.** One command: build, stills, cards,
films, both manifests, and a hashed before/after diff of every deliverable. It
fails loudly and specifically on the two conditions that otherwise produce
confident wrong output — the renderer coming up as SwiftShader, and a chapter
`expect` guard firing. `--stills-only` / `--cards-only` / `--films-only` compose,
`--dry-run` lists the plan without opening a browser, and
`shots.mjs --list` prints the whole shot plan — board, chapter, expect, aim, both
hours — which is what to run first when a guard does fire.
It also re-stamps `PROVENANCE.json`, narrowly: only entries whose origin is
`repository-generated` and whose `generator` names a script the run actually
executed, by literal hash substitution rather than re-serialising the file.
Without that, every legitimate card re-shoot leaves `npm run provenance` red.
**Every film re-shot.** They were at `9c9e78f`, captured 2026-08-07, and predated
the tone mapping, the reflective sea, the sky dome, terrain shadows, the rebuilt
California board, SFO, LAX, both bridges and the moving aircraft.
Tests 1137, typecheck, build, eight budget cells and every provenance and licence
check pass.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
132 lines
7.6 KiB
Markdown
132 lines
7.6 KiB
Markdown
# Open work on Tera
|
||
|
||
Short, and only things that are decided but not done. Anything speculative belongs
|
||
in an issue, not here.
|
||
|
||
## One command re-shoots the imagery: `npm run refresh`
|
||
|
||
```sh
|
||
npm run refresh # build, stills, cards, films, both manifests
|
||
npm run refresh -- --dry-run # what it would shoot; no browser, no build
|
||
npm run refresh -- --stills-only # …--cards-only, --films-only; they compose
|
||
npm run refresh -- --rough # films at 24 frames, for looking at
|
||
npm run refresh -- --skip-build # you just built; do not build again
|
||
```
|
||
|
||
`scripts/brand-assets/refresh.mjs` exists because re-shooting used to be a
|
||
*procedure* — build first, because the scripts photograph `dist/` and not `src/`;
|
||
then three commands in an order that matters; then check the run actually got the
|
||
GPU. A procedure that lives in somebody's head gets half-run, and the evidence was
|
||
in this file: the stills were re-shot at one commit and the films at another two
|
||
weeks older, and nothing said so until a human compared two files.
|
||
|
||
It prints a diff of the deliverables at the end — new, changed with the size delta,
|
||
byte-identical — and it **fails loudly and specifically** on the only two failures
|
||
that otherwise produce confident wrong output:
|
||
|
||
- **SwiftShader.** Software rendering makes the same pictures fifteen times slower
|
||
and reports success. Any child that prints a software renderer stops the run.
|
||
- **A chapter `expect` guard firing.** That means a pack was reordered under the
|
||
shot list, so re-running cannot fix it. `node scripts/brand-assets/shots.mjs
|
||
--list` prints what the shot list believes.
|
||
|
||
Two things it does **not** do, on purpose: it does not commit, and it does not
|
||
re-stamp the manifests afterwards. Commit tera first, then
|
||
`shots.mjs --manifest-only` and `films.mjs --manifest-only`, so the manifests name
|
||
a clean sha rather than a dirty tree.
|
||
|
||
## Re-shoot the time-lapse films
|
||
|
||
The 25 product stills and both share cards were re-shot on 2026-08-22 at the
|
||
airports-and-bridges commit and are current. **The films were not** — they were
|
||
last shot on 2026-08-07 at `9c9e78f`. `films.ts` in lumbridge-v4 records the tera
|
||
commit each reel was shot at, so a stale reel is visually stale and no caption edit
|
||
fixes it — check that commit against tera HEAD before assuming a reel is current.
|
||
|
||
What the reels predate: ACES tone mapping and the runtime PMREM environment rig; a
|
||
sea that reflects, with a swell normal map, Fresnel and sun glitter, in place of a
|
||
flat `MeshLambertMaterial` that had no specular term at all; a world-space sky dome
|
||
replacing the screen-space gradient, which at dusk painted the sunset band along the
|
||
*bottom* of the picture, under the board; terrain that casts shadows; a California
|
||
board with the Basin and Range, Death Valley, the Salton Sea and San Diego on it;
|
||
SFO, LAX, both bridges and a freeway that reads as a road; aircraft that move,
|
||
carrying registration and type; a rebuilt LA studio; the studio device hardware; and
|
||
a new UI chrome with a first-run flow.
|
||
|
||
```sh
|
||
npm run refresh -- --films-only --rough # rough cut first: ~20 s a reel, and it is
|
||
# the cheapest way to find out a camera is
|
||
# pointed at the wrong thing
|
||
npm run refresh -- --films-only # ~90 s per 180-frame film on the Radeon
|
||
```
|
||
|
||
Worth knowing before starting (the rest is in `~/.claude/skills/tera-capture`):
|
||
|
||
- Check the run prints the Radeon and not SwiftShader. The software path is ~15x
|
||
slower — 22 minutes a film rather than 90 seconds — and it reports success.
|
||
- `hero-soma` is a different animal: `chrome: "bare"`, midnight to midnight, and a
|
||
two-stage encode (a CRF 18 master, then 1440w CRF 28 and 960w CRF 30 delivered).
|
||
- **The hero camera is worth reconsidering.** Whole-board was tried and rejected
|
||
because the edge of the terrain plate showed against the sky. That seam no longer
|
||
exists: the sea now runs eighteen board spans and ends past the fog's far plane.
|
||
- After tuning the hero, run `npm run check:hero` in lumbridge-v4.
|
||
- `#onboarding-host` is in `FURNITURE.CLUTTER` now, and `#mode-dock` and
|
||
`#play-hud` are in `FURNITURE.BARE`. Every *new* overlay has to be added to one
|
||
of those two lists on the day it lands, because a frame with a stray card in it
|
||
still renders and still looks deliberate. The mode dock proved it: it shipped
|
||
inside the tera share card for a fortnight and nobody noticed.
|
||
- **The two capture scripts both serve on port 5210.** Two of them at once is
|
||
`EADDRINUSE` a minute into a run, so do not start a film while a stills pass is
|
||
going — or give one of them `--site`-style isolation first.
|
||
- Commit tera first, then re-run, so the manifest records a clean sha.
|
||
|
||
## The Bay Area board drops a frame in twenty, on desktop only
|
||
|
||
`bay-area.desktop.p95FrameIntervalMs` carries a **33.4 ms allowance and that is a
|
||
recorded defect, not a target.** The board renders a median frame in 16.7 ms and
|
||
drops roughly one frame in twenty: p50 16.7, p95 33.3, and 443–456 frame samples
|
||
in a window where every other cell returns 480.
|
||
|
||
It is desktop-only, and it is **not fill rate**: the mobile cell runs the *same*
|
||
2.26 M triangles at a comparable pixel count — 1.32 MP against desktop's 1.30 —
|
||
and holds 16.7 ms flat. The obvious suspect is the shadow map, which `stage.ts`
|
||
sizes **2048 on desktop and 1024 on handheld**, over what is now the heaviest
|
||
shadow-casting scene in the product.
|
||
|
||
**It is not a regression, and this was checked rather than assumed.** Measured at
|
||
the commit before the airports and bridges landed, with the same harness:
|
||
p95 33.3, p50 16.7, 443 samples, **2,771,606 triangles**. After that work:
|
||
p95 33.3, p50 16.7, 456 samples, **2,265,056 triangles** — the board got
|
||
506,550 triangles *lighter* while gaining SFO, both bridges and a surfaced
|
||
freeway. The stutter was simply invisible until `bay-area` became a measured
|
||
cell, which it had never been.
|
||
|
||
The allowance is there so the cell still guards the numbers that are healthy —
|
||
triangles, draw calls, and the mobile frame time — rather than sitting
|
||
permanently red and therefore permanently ignored. **Fix the stutter and put the
|
||
cap back to 16.7.** Start with the desktop shadow-map size and the shadow
|
||
frustum over the SF board; a 2048 map over 2.26 M triangles of casters is the
|
||
first thing to rule in or out.
|
||
|
||
## The aeroplane glyph is still larger than the Golden Gate
|
||
|
||
`GLYPH_MAX_SCALE` in `src/engine/flights.ts` is 52 and that is a mitigation, not
|
||
a cure. The glyph has a screen-space *floor* — never smaller than legible — which
|
||
scales by the distance to the **aircraft**, when what makes it look wrong is how
|
||
far the camera is from **what it is looking at**. At a whole-board pose those are
|
||
the same thing; at the Golden Gate chapter the bridge is two units from the camera
|
||
and the traffic is two thousand, so the floor fires hard on the aeroplane and not
|
||
at all on the bridge.
|
||
|
||
A ceiling of 52 was chosen because the raw scale at 1,160 units — the far end of
|
||
the orbit over the California corridor — is 51.0 at a 60-degree field of view, so
|
||
anything lower shrinks aeroplanes at a pose people actually use. (26 was tried
|
||
first and put the glyph at 0.0123 of the frame, against the 0.012 at which
|
||
`flights.ts` says the wings stop resolving.) 52 takes the worst case from about
|
||
two and a half times the bridge's main span down to about one and a half.
|
||
|
||
The complete fix is to clamp against the camera's focus distance rather than the
|
||
aircraft's, so the glyph collapses toward its authored size whenever the viewer
|
||
has zoomed in on something near, at any aircraft range. That is a signature change
|
||
through `glyphScale`, `tick` and their callers.
|