4,435 words
The harness is the supported way to move the universe, in the browser and in
Node. This page is the agent-oriented short list. The full API is
the harness guide. Launch, screenshots, and browser
gotchas are in the drive skill.
Two ways in
Prefer the cheap one. The headless runner drives the same harness object
the browser exposes as window.ir.
pnpm sim --self-test # twelve capability checks (~0.4s)
pnpm sim --targets --goto b:2 # the same navigation from a terminal
pnpm sim --terrain-baseline # what terrain costs, measured (~16s)
pnpm sim --helpThe baseline is the slow one because it is the one that generates: forty-eight patches per zoo body, at 24 to 69 ms each. Its request pattern is the deterministic half and costs nothing, which is what a caller that passes no clock gets.
A shader question has a rung of its own between these and the browser:
pnpm test:gpu compiles and runs a TSL graph on the physical GPU from a
*.gpu.test.ts. Name the relevant file to keep the run focused; total cost
depends on the selected tests and physical adapter
(testing). Use the
browser only for what only a compositor can prove: LOD at real display pixels,
framing, a cutscene, presentation, a strobe.
ir.help()
ir.targets() // start here — every other verb takes an address
ir.goTo('b:2')
ir.dossier('b:2') // what it is, rather than where it is
await ir.selfTest()
await ir.scenario('surface')goTo and the observatory's look accept human forms (SOL, s:SOL/b:2,
b:2 relative to the current system). The low-level parseAddress stays strict.
ir.look moves only a camera. ir.goTo teleports the ship. Both can fill the
frame with Jupiter; only one leaves you in orbit of it.
Terrain, without a browser
The streamer's selection rule is a pure function
(selectTerrain), so what a camera
would ask for is arithmetic rather than an observation. Every verb here runs
headlessly and gives the same numbers in a console, in pnpm sim and in a test.
ir.zoo() // one body per surface archetype, found rather than listed
ir.sites('g:milky-way/s:SOL/b:5.6') // the named places on a body
ir.descend('g:milky-way/s:SOL/b:5.6', { site: 'summit' }) // orbit → 2 m, on paper
ir.terrainBaseline() // the zoo, its descents, and measured patch costStanding on one runs anywhere; it is only worth doing where there is a picture. It moves a camera and nothing else:
ir.visit('g:milky-way/s:SOL/b:5.6', { site: 'summit', height: 2 })
ir.preset('earthrise') // a named picture: address, framing and lens, in one call
ir.chrome(false) // the interface out of the frame — the state a plate is taken in
ir.layers(false) // names and traces off, which is a different claim from the chrome
ir.terrain() // the live streamer and the rocks on it — null headlessly
ir.ascend() // back to the framing the camera left, or abandon a drop
ir.drop(20, -30, { seconds: 6 }) // fly down instead of cutting, facing the starA patch count is only comparable against the lens it was taken through. The
headless probes measure at the flight lens over 1920×1080 and state both in
their reports; the live streamer uses whatever the camera panel is set to and
the display's own pixels, so an ir.terrain() taken at another lens is a
different question rather than a disagreement. Past the flight lens the live
selection also reads where the camera looks and refines at the lens only inside
the frame, which ir.terrain().outside counts and the headless probes, with no
camera to aim, do not do. ir.lens() is what the picture is being taken with,
and ir.descend takes a lens and a viewport to ask at another one.
ir.visit cuts and ir.drop flies. Use visit for a plate — the frame
after it returns is the frame asked for — and drop when the descent itself is
the subject, which takes its seconds and ends facing the star. A --shot
taken straight after drop photographs the top of the arc.
ir.visit stands a camera on the ground; ir.land teleports the ship onto it.
The same distinction as look and goTo, one clamp lower — and they are not the
same ground: the camera stands on drawnSurfaceRadius and the ship lands on
surfaceRadius, up to 1.25 m apart
(ADR-0021). Sites are summit,
basin, shore, rough, corner and pole, derived from the body's own field
rather than authored, so they survive regeneration.
The browser, when only a compositor will do
scripts/drive.mjs is the one way in. It speaks the
Chrome DevTools Protocol to a Chrome it launches itself, on its own profile and
port, so it needs no focus and does not touch the browser a person is using.
node scripts/drive.mjs --js "ir.look('g:milky-way/s:SOL/b:5')" \
--wait 3000 --shot saturn.jpg
node scripts/drive.mjs --keep-storage --sample 240 --sample-js "ir.terrain()"
node scripts/drive.mjs --downSteps run in the order written, in one session, and Chrome stays up between
calls. Each invocation clears local storage and cookies, then boots the requested
page. --keep-storage retains them and permits attaching to the booted page;
--fresh still forces a reload when combined with it. IndexedDB saves, asset
caches and service workers are retained. Batch setup and measurements in one
invocation when they must share state. --reload steps keep that invocation's
storage.
Public HTML before the scene
Use --document to wait for the document to become readable without waiting
for a renderer. --no-javascript implies this mode and disables page
scripts before navigation, including the first navigation of a new rig.
Inspection expressions passed through --js still run through DevTools.
node scripts/drive.mjs --url http://localhost:8787/docs/architecture \
--document --no-javascript \
--js '({title:document.title, text:document.body.innerText})' \
--shot docs-without-javascript.jpg
node scripts/drive.mjs --url http://localhost:8787/docs/architecture \
--document --block-url '*App.*.js' --wait 2000 --logs \
--shot docs-without-runtime.jpgRepeat --block-url for additional request patterns. Match the actual chunk
names emitted by the build. Blocking bypasses service workers so a cached
response cannot conceal the requested failure. These settings are per
invocation, and changing script execution or blocked patterns reloads a warm
page. Omitting the flags restores scripts and ordinary service worker behavior.
Document screenshots capture the compositor directly, without the renderer's
extra activation capture. Frame sampling and screencasts require scripts and
reject --no-javascript. Default readiness still waits for the renderer and
its boot cover, and default screenshots retain the two captures it needs.
A saved shot as the setup
The driver can open a bundled preset or a single-shot JSON export through the same URL the planetarium shares. This exercises time, orbit anchor, tracking, surface stance and lens restoration together.
node scripts/drive.mjs --preset earthrise --wait 2000 --shot earthrise.jpg
node scripts/drive.mjs --picture .scratch/shoreline.json \
--query 'lens.zoom=2' --query 'label=Sea + sky' --shot shoreline.jpg
node scripts/drive.mjs --picture .scratch/shoreline.json \
--query 'save=1' --logs--preset expands the named bundled shot into a complete URL. --picture
accepts the public JSON envelope containing exactly one shot; the two flags are
mutually exclusive. Both select /planetarium on the host given by --url,
which also supports a copied share link directly. To exercise a built-in's
short alias, use --url 'http://localhost:5173/planetarium?preset=earthrise'.
Repeat --query 'key=value' to override individual fields after selecting the
shot. Values are raw text, with shell quotes around the argument; the driver
handles URL escaping. Repeating a key keeps its last value. These are session
flags, applied before all steps, and must be repeated for a matching warm attach.
The driver always sets presentation=occluded.
Add --print-url to print the resolved link without starting Chrome or a server.
The URL uses shot=2 plus dotted picture keys such as time,
framing.state.distance, and lens.zoom. Numbers retain full precision.
Time is seconds from J2000, camera angles are radians, and camera distances
are meters. Lens focal length and gauge are millimeters.
lens.focus=null means infinity; framing.surface=null means an orbit camera.
save=1 restores the view and opens its save prompt at /planetarium/presets
without writing to the library. See the
preset format.
A picture with weather is shot=3 and carries weather.regime. The
cornerstones (weather-e1-cumulus-orbit … weather-g6-descent) are
--preset ids like the bundled shots; add --query clouds=1 to draw their
weather, and without it they draw Earth's deck and no volume
(ADR-0067).
--settle waits on the clouds as well under the flag: their caches and 32
frames of their history.
Invalid query overrides reach the page for error-path tests. Invalid JSON
fixtures fail before Chrome starts. Run pnpm vitest run presetUrl.test driveUrl.test for the codec and driver tests without a browser. In the browser,
verify URL restoration and field edits, preservation of the pose across dialog
navigation, and removal of shot fields when focusing another body.
Session lifetime
Run shutdown separately. --down exits before step processing, so a command
containing both --js and --down closes Chrome without evaluating the script.
The same applies to --file and --shot. Finish the inspection batch, then
call node scripts/drive.mjs --port <port> --down for that rig.
Which checkout is served
A server answering --url is not evidence of a tree. A sibling worktree's
Vite on 5173 boots the same app under the same build id, because worktrees
cut from one commit describe it alike. After every boot and every attach the
driver reads ir.build() and holds the served tree against its own
checkout's git rev-parse --show-toplevel. A page another checkout serves is
refused before the first step, and the refusal names both trees. The usual
cause is a sibling's Vite on 5173: while the port answers the driver starts no
server, and pnpm dev refuses the taken port. Serve this checkout on a port of
its own, pnpm dev:client --port <n>, and drive it with
--url http://localhost:<n>/ --no-serve. Pass --tree <path> only when you
mean to drive another checkout. Naming the sibling to get past a refusal
drives the sibling and reports it as this tree. A production build names no
tree, and neither does a build older than the verb, so both read
identity unchecked and proceed: --url at pnpm preview on 8787 and
presets:compare --base at an older commit. The preset commands pass the
tree they serve and print which tree each set of plates came from. Trees
compare after realpath, so a symlinked worktree, or /tmp against
/private/tmp, is one tree. The check names the served tree, not the edit:
the build id is stamped when the server starts.
The operating point
A figure is a figure about the point it was taken at, and the wrong point
boots and answers like the right one. So after every boot, attach and
--reload, and before the first step, the driver holds the page to its
operating point with the launch guard in
scripts/driveLaunch.mjs, over its own
socket:
- a WebGPU renderer;
- an adapter that is neither a fallback nor, by name, a software rasterizer:
the engine's own device's
adapterInfowhere it has one, and a fresh request's otherwise; - the viewport and ratio the invocation's
--width,--heightand--dprasked for, as the page reports them, the ratio compared as the float32 Chrome keeps it in; - a drawing buffer of that viewport × min(DPR,
dprCeilingfor the pointer) × the picture's supersampling factor, floored as three floors it, at the ratio the page reports; - the served tree, as above.
--document and --no-javascript ask for no renderer, so the page is held to
the window and the served tree alone; with scripts off it answers no
ir.build(), and its tree reads identity unchecked. The window is checked as well as the
buffer because a page whose emulation another session cleared reports the
window it was left at, and on Chrome 157 the app's ratio follows an emulated
change, so its buffer agrees with that window and the buffer rule alone
passes it. The buffer is read two animation frames after the rig's
window is set, because a warm attach sets it on a page that has been at
another size: Chrome drops an invocation's emulation when its socket closes,
so between invocations the page sits at the window's own size and ratio,
1600×933 at DPR 2 on the Mac mini's display for a rig at 1600×900 at 1. A
page the guard finds with nothing booted in it is booted once more, for the
reload a fresh Vite makes inside the boot, and refused the second time.
A refusal prints the guard's reason, exits 1 and runs no step. It means the
page is not the point the command asked for, and the remedy depends on the
check: a buffer the rig did not ask for is the remount of trap 5 below, and
--fresh boots the page again at the rig's window; a WebGL backend or a
software adapter means this Chrome is not drawing on the GPU, and trap 4's
--down and a fresh start is the first thing to try; a tree mismatch is the
section above. Forced sRGB, --color-profile srgb, is recorded as
dynamicRangeHigh false and is not refused.
The record is a line of narration unless --quiet, the operatingPoint of
--json with identity beside it, and each --reload step's point. It
names the adapter and backend, the buffer against the window and the ratio,
the dynamic range, whether the system is Sol, a catalog star or generated,
and the served tree. Chrome's version from /json/version is in it too. The
port's session records it with the kind, the tree, the window and the
controls, and only once a page has passed, so a run that fails at boot or is
refused does not consume the warning. A version other than the one the
session recorded is warned about once per entry and never refused, because
Chrome stable updates itself.
--status reads the point again without navigating or booting. It prints
the rig's lines and the GPU's holder first, then sets the window, the kind
and the tree the session recorded for the last page that passed, prints the
line and the full record, and exits 1 when the guard refuses. It reads
nothing while another invocation is driving the page, and says so with that
invocation's pid: each invocation lists itself in the session until it
exits, because setting a window replaces the running invocation's, and the
status socket's close clears the page's device emulation for every session,
so a cast or a settle in progress would drop to the window's own size and
ratio. A page that does not answer within five seconds is not read rather
than refused, and so is a socket that does not open. A baseline older than both
engine.picture and ir.build(), which presets:compare --base can serve
from an older commit, names no picture to hold the buffer against, so its
buffer reads unchecked and the rig proceeds.
One GPU job at a time
Every GPU job on the machine takes one lock, in the clone's git common
directory, because two at once have crashed macOS:
scripts/gpuLock.mjs. A rig holds it from before
its Chrome launches until --down has closed that Chrome, and a later call on
the same --port joins it. Beside a rig, pnpm test:gpu and a rig on another
port are refused at once, with the holder's name, pid, age and worktree. A
refusal means wait or ask whoever is working in that checkout; never --down
a rig you did not start. --gpu-wait <seconds> queues instead, and
pnpm test:gpu takes IR_GPU_WAIT=<seconds>. --down is never refused, and
--status names the holder. A sandbox that cannot write the clone's .git,
Codex's workspace-write sandbox among them, fails every GPU command closed with
cannot write the GPU lock. The
drive skill has
the preset commands' part and the sandbox's remedy.
The traps
These are the browser, not bugs in the clock, and the driver handles the first three; they are here because they explain what it is doing:
requestAnimationFrameis suspended while the window is occluded. Focus emulation is what makes the page render anyway. Without it boot never leaves "first light…" and every capture is the boot cover.- Every screenshot is taken twice. The first capture activates the page and draws the frame, so alone it shows the state before the step that preceded it. The second is the evidence. After a cutscene seek, wait 2–4 seconds more for asynchronous textures.
- HMR does not reliably rebuild the renderer. After a source edit,
--reload. A tab that has taken a dozen hot updates draws its HUD withengine.glnull, which looks like a rendering bug and is not one. - A wedged Chrome needs
--downand a fresh start. Reloading is not always enough to recover its GPU state. - The page is told its own pixels are not to be sampled, with
?presentation=occluded, and the driver adds it to every URL. The presentation watchdog decides whether the canvas has presented by reading the bitmap back from inside an animation frame, and skips the check whiledocument.visibilityStateis notvisible— because an occluded window legitimately never presents. Focus emulation, which is what makes trap 1 work, reportsvisiblefor a window that is still behind everything else; the in-frame sample reads the drawn texture rather than the composited one, so it reads correctly there, but a driven boot is a measurement and a ladder run is what it must never contain. Exhausted, the ladder remounts the canvas: a second full preload and warm-up census 4.5 s after the first — about 6.5 s of a 10.2 snavigation to first light— an uncaught dispose from inside Three on the way, and a drawing buffer measured at 3200×1800 for a rig asking for 1600×900 at DPR 1. Every terrain figure taken after a rebuild in this rig is a retina figure, which is the trap below arriving without being asked for, and the launch guard refuses that page before a step. On Chrome 157 the app's ratio follows an emulated DPR change while focus emulation runs, and that buffer has not been reproduced there, so the guard's unit case inscripts/drivePage.test.mjsholds the refusal; CONTEXT.md § "Every drive.mjs boot runs the guard, and a page between invocations is at no rig's point" has the runs. Boot from this rig is one census and ~4.3 s to first light. - Chrome left running is contention the test suite feels. The driver keeps
it up on purpose, and a full
pnpm testbeside it has timed out on a different unrelated file each run and passed clean once--downhad run. A single timeout that moves between runs is a reading about the machine. --servecannot start a dev server in a worktree that has never built —cf devneedsapps/game/dist. Usepnpm dev:clientand--no-serve, or build once. development § Commands.- The MacBook Air steps every figure up about 35% after about 3.5 minutes
of load. It is fanless (Mac17,4, base M5). At the far-shore preset,
1600×900 at DPR 1, in Chrome 157 headless on the dev build,
ir.gpugoes from 10.2 ms to 13.4–15.3, settle from 12–18 s to 28–31 and boot from 5 s to 7–8, and five idle minutes bring it back. Two cool sessions still disagree by 8%, andpmsetrecords no warning. Onset and recovery each rest on one observation at that point, and the cause is inferred, becausepowermetricsneeds sudo. So compare base and candidate interleaved in one session first. Idling five minutes between arms suits a short arm only: a six-boot series or a thirteen-plate pass runs 3–6 minutes and outlasts the onset. Name the thermal state of every figure: cool, or how many minutes under load, and on the Mac mininotifyutil -g com.apple.system.thermalpressurelevelbefore and after. The fan-cooled Mac mini (Mac18,5, M6) heldir.gpuflat through 10.4 sustained minutes at far-shore 1600×900@1 and 1440×900@2, thermal pressure 0 throughout, but that is one session at each window, so the rule holds there too until repeated sessions give a between-session spread.
Default readiness is ir.status().boot: drawing once a renderer exists,
booted once the boot cover lifts. The bare harness appears seconds earlier,
so a probe on its presence alone captures an unlit canvas. --document uses
the committed document's readiness for public HTML checks.
Terrain streams only below the eight-pixel relief gate, and above it
ir.terrain() reports zeros that read exactly like a broken streamer. From
the root URL, neither ir.land nor ir.orbit(address, 8) was close enough:
both left visited: 0 and lens: null. ir.visit(address, { site: 'summit', height: 2 }) in the planetarium is what makes the streamer run. Check
visited before concluding anything about ground.
And visited is a figure about the last frame that walked, not about this
one. visited, culled, starved and level are mirrors of whichever
frame last re-selected, and a converged stance re-selects on none of them — the
walks are a pure function of the eye, the optics, the level floor and the
geometry cache, so a frame in which none of them moved reuses the answer. The
counter that says whether a frame walked is selections, a total since the
streamer was made: two reads a second apart that differ by sixty are a
selection recomputed every frame, and two that agree are the memo holding.
Read it beside visited or the other four will describe a frame that walked
nothing.
A pooled streamer's first frame on a body selects nothing at all. The
subdivision floor is a worker answer — universe.prepareSurface is 33–43 ms of
floor search cold, plus the drainage graph on a wet body, and a frame cannot
carry either — so a body it has not prepared yet has no ceiling to select
against and the ground waits, the same way it waits for the heightfields
themselves. --wait through it; a single frame
after ir.visit reports zeros for a reason that is not the gate above.
Why was that frame slow
The panel answers "is it fast right now" while you fly; the timeline answers "why was that frame slow" afterward, and it is the only instrument here with a time axis the others can be laid against.
node scripts/drive.mjs --js "(await ir.profile(2000)).text" # a table and a verdict
node scripts/drive.mjs --url "http://localhost:5173/?timing=trace" --trace 3000
pnpm timing --threads # read the trace backir.profile arms the level, records, disarms and reports, so nothing is left
retaining. It ends on the line worth having — "9 of 61 frames over 25 ms; terrain.select
was the largest measured span in 7 of them, 8.4 ms of 31.0 ms" — which names
the largest span inside the late frames rather than the busiest one overall,
and puts the frame duration beside it so the ratio says whether the name is an
explanation. Where it is not, the line says so: everything the GPU does happens
after frame returns, so a late frame with nothing large inside it is the
expected shape rather than a gap in the report.
Off is the default everywhere and a recording without ?timing=trace carries
none of these tracks. The worker tracks are in a trace and never in a drain,
because each side of the boundary times against its own timeOrigin.
ADR-0022.
Measuring so the number means something
Take a performance figure on a quiet machine, and take nothing else at the
same time. A worker figure is the one that goes wrong silently: the same
summit arrival reads 45 ms runs quiet and 285 ms with a build running beside
it, so a pnpm test in another shell does not make the measurement noisy, it
makes it a measurement of the test run. Finish the suite, let the machine
settle, then measure. Chrome left up by the driver is part of the same
contention in both directions — trap 6 above is this one seen from the test
suite's side.
Say which build. Dev React is about five times the shipped cost and every
number below is a dev-build number; both are real and only one is about a
player. pnpm preview on 8787 is the shipped one, and it is worth re-measuring
anything that lands in a design document there.
Name the thermal state. On the fanless MacBook Air a figure taken after a few minutes of load is a figure about a different machine; trap 8 above has the step and the rule.
A headless frame interval detects nothing under the 16.7 ms budget, and a
CPU span is not a control for a GPU change. Headless rAF is a fixed 60 Hz
clock: a DPR change from 1 to 1.05 at far-shore on the Air raised ir.gpu
6.5% across seven interleaved pairs and moved rAF p95 by 0.00 ms. The same
change raised the CPU-only spans Engine/snapshot 28% and Render/sensor
24%: on the Air's M5 the CPU spans move with GPU load. Read ir.gpu
for a GPU question; a CPU span that moves beside a GPU change is not, by that
alone, CPU work.
Name the operating point, and prefer two. A figure measured at one is a
figure about that point. The four that recur, all dev build, 1600×900 at DPR 1
on an Apple M5, with Engine/frame vsync-bound at 16.7 ms throughout:
| point | engine | notable |
|---|---|---|
| Planetarium, Earth from 14,400 km | 0.36 ms | snapshot 0.26, orbitTraces 0.13, starfield ~0 |
| Converged summit stance, 2 m | 0.45 ms | terrainPatches 1.10, terrain 0.15, select 0.01 |
| Four retargets in a Sol tour | 0.33 ms | orbits max 0.20, bodies max 25.7 on one frame |
| Jump to a generated system | 0.45 ms | one Boot/bake atmosphere of 39.7 ms mid-jump |
?workers=N overrides the pool size, bounded at sixteen, and it is how the
ceiling in engine/browserWorker.ts was chosen rather than assumed. The
experiment is worth re-running on any machine whose core count is not this
one's: land, converge for twenty seconds, and read jobs/s, averageRunMs and
ir.terrain().level together — throughput alone hides the dilation, and the
drawn level is the one a player watches.
When a visual defect is reported
Terrain selection is measured in display pixels, so the streamer at a retina window asks for four times the patches and behaves like a different subsystem. A defect that will not reproduce is usually a window that has not been matched: get the reporter's size and device pixel ratio before concluding anything about the code.
A Chrome performance trace recorded with Screenshots gives both at once, plus one JPEG per composited frame at the page's real rate — a recording of what they actually saw, on their machine. It is the strongest evidence a report can carry and the cheapest thing to ask for.
node scripts/traceFrames.mjs ~/Downloads/Trace-*.json.gz # frames, period, Hz, url
node scripts/drive.mjs --dpr 2 --width 1920 --height 1200 … --cast 200Both difference consecutive frames and report the ones that differ from both
neighbors while those neighbors match each other. That shape is a strobe; motion
produces none, which is what makes a clean result mean something. A still cannot show
any of it and neither can --shot.
A Firefox profile answers what no picture can. Its markers say whether frame
pacing is even involved — the lunar strobe ran at a clean 60 fps with one long frame
in 261, which ruled out a hitch immediately — and its JS samples say what the app was
doing: buildPatch present on every frame of a 4.3 s capture is a terrain streamer
that never converged, and that was the finding.
The author's instruments
Press the bug in the IR menu at the bottom center of the frame, or `.
Four panels appear, all closed: controls, telemetry, perf, graphics. Every
panel calls the harness and nothing else, so anything you can do by clicking is
reproducible in a test. The Controls panel carries a Harness section —
cutscenes, scenarios and the self-test — which is where scaffolding belongs.
P opens perf, H clears both panes and Shift+H clears every piece of
chrome, which is the state a plate is taken in. All three are defaults; the
bindings live at /settings/controls and ? prints the live ones.
Going somewhere is the Catalog, and it is not one of these: it is a panel of the product's own, in the planetarium and in the flight workspace, with a verb that depends on the mode.
The planetarium's Camera panel is where the observatory reads out — range, altitude, frame fill, the two orbit angles and the address — because those are facts about where the camera is standing rather than about the body in front of it. The object panel is the body's record and carries none of them.
Look at the perf panel before optimizing anything, and before believing a performance claim in a design document.