8,391 words · 3 diagrams
A single object that can drive and interrogate the whole simulation without
touching the UI. It is exposed as window.ir in the browser and used directly
by the Node runner and the tests.
ir.help()in the console is the quickest list. This page explains the supported vocabulary and the distinctions that the one-line help cannot.Code:
packages/devtools/src/harness.ts, over the port inhost.ts
Why it exists in a package, not the app
flowchart LR
H["<b>GameHarness</b>"]
H --> B["browser<br/><code>window.ir</code>"]
H --> N["headless runner<br/><code>pnpm sim</code>"]
H --> T["tests<br/><code>devtools.test.ts</code>"]
B --> R["a bug reproduced in Chrome…"]
R --> T2["…replays as a Node test"]
T2 -.- NOTE["this has happened repeatedly —<br/>the frame-transition and save<br/>bugs were both found this way"]
classDef note fill:none,stroke:none,color:#64748b,font-style:italic
class NOTE note
style H fill:#0369a1,stroke:#0c4a6e,color:#fffEverything it returns is JSON-serializable, for exactly that reason: an agent driving a browser over the debug protocol gets structured state back, not pixels.
Reading state
| Call | Returns |
|---|---|
ir.summary() |
one line: tick, hash, frame, speed, systems |
ir.status() |
everything the debug overlay shows, structured |
ir.build() |
BUILD_ID, and the tree the dev server serves |
ir.inspect(id?) |
one entity in full — frames, canonical + local coords, velocities |
ir.dossier(address) |
one star, body or station as a page of astronomy |
ir.snapshot(alpha?) |
the raw presentation snapshot |
ir.picture(debug?) |
reconstruction dimensions, history, allocations and GPU timings |
ir.lens() |
the camera as an instrument — mm, f-stop, depth of field, EV |
ir.bodies(system?) |
flat listing of a system's bodies with addresses |
ir.stations(system?) |
a system's stations: parent, reach, perigee, apogee and period |
ir.systemsNearby(ly) |
nearest star systems, catalog and procedural |
ir.logs(n) |
recent structured log records |
ir.summary()
// tick 2590 (40.47 s, 1x) | hash fdf43017 | Debug One in sf:g:milky-way/s:SOL/b:0@0.350000,-1.100000 | 51849.8 m/s alt 0.000 mm | systems 1, frames 19inspect and dossier answer different questions and take different
arguments. inspect takes an entity id and reports a pose and a velocity;
dossier takes an address and reports what the thing is — mass, orbit,
rotation, atmosphere, light — in the groups the planetarium's object panel
draws. A body is not an entity, so "what is Europa" has no answer in the entity
store. Fields nothing has measured come back as a Fact with a null value and
a pending reason, and pendingCount is how many
(ADR-0014). It is lenient about its
input in the same way ir.look is, through the same resolver, and returns null
for an address that names nothing.
ir.status().boot says whether the app has booted: booting before
there is a renderer, drawing while the boot cover is still up over a scene
that already renders, and booted once the cover is gone. It is answered by
the presentation host, so the driver waits on it rather than on a DOM selector
or an engine field a rename would silently break. Headlessly it is booted.
ir.build() says which build this is and which checkout serves it, as
{ id, tree }. id is BUILD_ID: the commit, -dirty when the tree had
edits. tree is the served checkout's root, from git rev-parse --show-toplevel, and only the dev server has it. Sibling worktrees cut from
one commit share an id, so the tree is what tells them apart, and the driver
holds it against the tree it means to measure before it runs a step
(driving). A production build
reports tree: null, because a shipped bundle carries no filesystem path, and
pnpm build refuses one that names this checkout. Headlessly both are null:
no build produced that host.
ir.lens() is the optics, and ir.status().lens is the same object. Focal
length, gauge and zoom are what the camera is set to; the field of view, the
sharp band, the blur circle against the pixel it has to hide inside, the Airy
disk and the exposure are derived from them against the viewport the picture
actually lands on (ADR-0017). It is on status
because a still is a body, a pose and an optical setup — a capture that
records the first two is not reproducible. Both are null headlessly, which is
the honest answer rather than a plausible one taken at a nominal resolution: a
circle of confusion is a claim about a display, and there is no display.
Measuring the stellar field
ir.galaxy() returns a read-only inspector for the current world's galaxy
seed. sample(position?) accepts a UniverseVector, defaults to the Sun, and
reports population densities, Johnson V emission, RGB extinction per parsec,
dust modulation, normalization, and both
field and active generation versions. count(options?) integrates the
reference cylinder; tangencies() reports the arm curve's tangent longitudes.
ray(direction, options?, origin?) returns emergent RGB radiance, optical depth,
and transmittance. Direction is a displacement in simulation axes; origin
defaults to the Sun. Options include distanceParsecs, maxStepParsecs, and
sampling, which accepts reference, observer, or settled.
pnpm sim --galaxy-plates .scratch/galaxy --galaxy-width 384 --quietThe command writes face-on, edge-on, observer, young-arms, bar-bulge,
and halo PNGs, paired .f64 arrays, and report.json. The report declares
units, dimensions, sample counts, timings, hashes and the shared display
stretch. The raw arrays contain interleaved RGB float64 little-endian values in
V-anchored nW m⁻² sr⁻¹. Green is Johnson V radiance; red and blue describe
illustrative chromaticity, and the channel sum is not bolometric power. The observer plate
is an equirectangular sky with the galactic center in the middle and longitude
increasing to the left.
In a script, openSession().harness.galaxy().plate({ view: 'face-on', width: 192, height: 192 }) returns the raw image. The population option selects
thinDisk, thickDisk, youngArms, barBulge, or halo; observer supplies
a different UniverseVector for the observer view. Calling these functions
does not advance or mutate the world. Plates use dust transport with a 10 pc
step maximum by default. dustScale: 0 selects the emission-only control and
its 100 pc default; maxStepParsecs overrides either. Metadata records these
settings. See
ADR-0032 for parameters and calibration limits.
pnpm sim --galaxy-calibration --quiet emits the linear-light acceptance report
and exits with status 1 if a bound fails. ir.galaxy().calibration() returns the
same report without an exposure or display response; localDust() lists the
Local Bubble approximation and nine source-derived cloud records. The reference
sky includes diffuse Galactic and extragalactic light beyond the modeled stellar
component. The report declares that limitation, its units, and the 0.3 mag bound.
Enhanced processing consumes that calibrated field separately from this report.
Matched camera images and transitions remain subject to preview acceptance;
passing the linear-light bounds does not establish their appearance.
To regenerate the checked-in source manifest and runtime cloud/sky tables:
node apps/ingest/src/galaxyReference.ts /path/to/cube_ext.fits /path/to/RadianceOut.csv
pnpm exec prettier -w packages/universe/src/galaxy/localClouds.generated.ts packages/universe/src/galaxy/skyCalibration.generated.tsThe inputs are the uncompressed Lallement 2022 FITS cube and GAMBONS supplemental
sky map; source links, hashes and exact selection windows accompany the output in
data/reference/galaxy.json. No catalog or procedural systems are regenerated.
To regenerate the cloud droplets' phase table:
node apps/ingest/src/mieTable.ts
pnpm exec prettier -w packages/rendering/src/mieDroplets.generated.tsIt takes no input: the series, the size distribution and water's index are in
the generator. It runs in about 24 s on the Mac mini and writes the same table
every time, and apps/ingest/src/mieTable.test.ts holds the committed file to
the series
(ADR-0066).
In the browser's planetarium, ir.galaxyView('face-on') and
ir.galaxyView('edge-on') select the fixed external instruments also available
under Presets → Milky Way. Each scopes its recipe lens and photographic
exposure while it owns the view. Leaving it releases that scope and restores
the player's lens and mode; no world state or global preference is rewritten.
ir.look('s:SOL/b:2') returns to an Earth view.
ir.galaxyJourney(0) holds 64,000 km above Earth with the player's lens and
selected camera mode. ir.galaxyJourney(1, 36) travels to 30 kpc above the
galactic center over 36 presentation seconds; ir.galaxyJourney(0, 36) returns.
The first argument is progress from zero to one, and an omitted duration holds
the requested view immediately. ir.observerStatus().journey reads progress,
destination and remaining duration without moving the camera. The Milky Way
controls expose the same trip and a slider. Automatic adapts to the framed
light, Manual retains the chosen lens exposure, and Enhanced keeps its declared
composition. Entering a journey does not select a long-exposure instrument.
ir.galaxy().render() returns the projected target's dimensions and bytes,
field and kernel versions, normalization, galactic-center origin in parsecs,
step bounds, dust scale, sampling profile, settled state, readiness, observer
frame, sensor exposure and bounded sky selection. submissions counts scene
submissions requested from the volume; draws includes integral tiles and
projection draws; held says whether the projected target was reused on the
last submission. A held projection may coexist with an advancing cache bake.
When the ordinary physical cache is enabled, cache reports initialFaceSize,
faceSize and selectedFaceSize, tile progress, publication and cancellation
counts, retained entries, the 0.15 pc reuse radius, allocated bytes and physical
units. using identifies the selected cache path; liveDraws and
samplingDraws distinguish integration from cache sampling. The first complete
cube has 32-pixel faces, followed by 128 and 512 pixels. All retain physical
V-anchored RGB in units of 1,000 nW m⁻² sr⁻¹ per stored unit. The display
response is applied afterward. A bounded live target serves a cold or
translated view while a replacement bakes; only complete cubes publish.
temporal reports the live history dimensions, interleave stride, ray target,
phase count, resets and owned bytes. stars reports source count, source
uploads, maximum reductions, projection bytes and the resolved-star extinction
cache. Its queue, lag and completed-source counts distinguish delayed physical
refresh from an idle selection. cache.archive reports successful disk restores,
completed writes and storage failures. A failed disk cache does not prevent a
new bake.
--sample 12 --sample-js "ir.galaxy().render()" records that state one frame
at a time. Read cache publication and draw counters beside frame timings;
submission counts alone do not measure cost. The report is null without a
renderer. ir.lens() gives the resolved optics and exposure. The fixed face-on
instrument uses f/2, 2,400 s, ISO 400; edge-on uses f/2, 600 s, ISO 400. These
recipes apply only while the named instrument owns the view.
The field transports stellar emission through the shared dust model. A declared
photopic/V ratio of 1.25 converts V power to luminance; color remains
illustrative. resolvedStarExtinction reports the resolved-star cache's
readiness. Star sprites use source-bounded dust columns; the report's queue,
lag and completion counters show whether they are still catching up with an
observer move. ADR-0038 defines
the catalog-relative transmission and finite update cycles.
node scripts/drive.mjs --url http://localhost:5173/planetarium \
--width 1920 --height 1080 --dpr 1 \
--js "ir.galaxyView('face-on')" --js "ir.chrome(false)" \
--wait 1500 --js "ir.galaxy().render()" --shot galaxy-face-on.jpgFinding and loading destinations
| Call | Effect |
|---|---|
ir.targets() |
destinations near the player, with addresses — start here |
ir.search(text) |
everywhere matching a name, nearest first — the whole catalog |
ir.rowsFor([…]) |
those addresses, as listing rows measured from here |
ir.findWorlds(q) |
bodies matching what a world is, swept in worker batches |
ir.goTo(target) |
resolve a human form and move the ship to that system or body |
ir.loadSystem(id) |
generate a system without moving the ship |
The first four are functions over the world and a vantage — the ship, and
the planetarium's eye when it holds one — in
finding.ts, beside the per-question
answers in travel.ts; the harness forwards to them, and their tests call them
directly.
goTo and the observatory's look accept human forms such as SOL,
s:SOL/b:2, or b:2 relative to the current system. The low-level
parseAddress function remains strict; use the harness resolver for human input.
findWorlds is a third question and the expensive one. targets and
search read what is already there; this generates every system inside the
radius to test it, because a body does not exist until its seed is expanded and
so cannot be indexed. It answers in batches on the worker pool:
const sweep = ir.findWorlds(
{ starClasses: ['M'], sea: true, landable: true },
{
lightYears: 25,
onBatch: (found, progress) => console.log(found.length, progress),
},
)
sweep.systems // how many systems it will walk
await sweep.done // the nearest matches, sorted
sweep.cancel() // stop; queued jobs are dropped and running ones are toldThe nearest thousand are kept and the rest counted — "rocky, within 150 light years" is 37,929 systems and over a hundred thousand bodies. ADR-0035.
targets and search are not the same list narrowed. targets is a star
sweep with a radius and answers "what is near me"; search is an index lookup
over the whole catalog and answers "what is called this". Filtering the survey
to serve a name query can only ever find what was already a few light years
away. Both take { origin: 'observer' } when the question is about the
planetarium's camera rather than the ship — in that mode the two are nowhere
near each other.
Driving the clock
| Call | Effect |
|---|---|
ir.step(ticks) |
advance exactly N ticks, ignoring wall clock |
ir.runSeconds(s) |
advance exactly s × 64 ticks |
ir.pause() / ir.resume() |
|
ir.timeWarp(x) |
multiplier on how many ticks a second of wall clock buys (1 = real time) |
step is the deterministic one — it does not consult the clock at all, which is
what makes scripted scenarios reproducible.
Every detent timeWarp accepts is delivered over a ship that is coasting,
and the ceiling is on integration. A ship with no control input, no spin under
flight assist, and a periapsis above the ground band is propagated from an epoch
rather than stepped, so the frame jumps (ADR-0025);
one that is thrusting or skimming an atmosphere is stepped through every tick
and capped at 1,920 simulated seconds a second. Which of the two is happening is
the difference between a warp that reads as delivered and one that reads as
capped, so both ir.summary() and ir.inspect() say: the summary line appends
, coasting, and the inspection carries a coasting boolean.
ir.status().world.achievedTimeScale against timeScale is the same fact from
the clock's side.
Flying
flowchart TB
subgraph POS["put the ship somewhere"]
O["ir.orbit(address, altitudeKm)<br/><i>a valid two-body solution —<br/>it stays there</i>"]
L["ir.land(address, latDeg, lonDeg)<br/><i>places on the pad —<br/>landed after one tick</i>"]
G["ir.goToSystem(id, au)"]
end
subgraph AIM["aim and burn"]
F["ir.face(address)<br/><i>free — changes nothing else</i>"]
BT["ir.burnToward(address, throttle)"]
T["ir.throttle(0..1)<br/><i>the main drive — a setting,<br/>not a held key</i>"]
C["ir.control({translation, rotation, throttle})<br/><i>the thrusters, the attitude,<br/>and the drive if given</i>"]
HOLD["ir.hold()<br/><i>hands off everything,<br/>drive included</i>"]
end
POS --> AIMTwo notes worth internalizing:
orbitis not a teleport to coordinates — it sets a state that solves the two-body problem, so the ship stays in that orbit. It also places the ship on the sunward side, pointing along the orbit, because a debug tool that drops you on the night side of an unlit world facing nothing is technically correct and useless.faceandburnTowardare separate because looking and accelerating are different acts.facecosts nothing and does not perturb the trajectory.- The thrusters and the drive are two controls.
translationis the reaction-control system, six ways at under a g, and holds only while it is set;throttleis the main drive, ahead only, at three g, and stays where it is put — throughcontrolcalls that do not mention it, and through a save.burnTowardsets the throttle, and every placement verb cuts it, because a ship put into a circular orbit with its drive lit is not in that orbit on the next tick. landdoes not land you. It puts the ship on the pad — localy = 0in a surface frame is the ground — and the contact test makes it landed on the next tick, soir.land(...).player.landedisfalseand oneir.step()fixes it.ir.scenario('surface')hides this because it steps 64 ticks. Landedness is only ever a consequence of touching the ground:stepFlightshort-circuits for an entity that is already landed, so a ship declared landed three meters up never meets the contact test and hovers there while the overlay reports an altitude of zero.- Every angle a verb takes is in degrees —
land,visit,drop,descend— and every listing prints degrees, soir.sites()output pastes into any of them. Under TypeScript theDegreesbrand makes the caller say so (deg(20)from@inertialref/shared); radians begin below the harness.ir.observatory.standis the object itself and takes radians:ir.visitis the degree door to it. - The verbs live in
Maneuvers(packages/devtools/src/maneuvers.ts), which a test can build over a session directly. Each returns what it promises — the state it wrote, the nose, the phase it framed — where the harness returns its status.ir.status().playercarries the sameheadingandphase, so "arrives looking at it" is the dot ofheadingwith-local. ir.flightAssist(enabled)exists and is absent fromir.help(). It is control input and it is in the state hash, so a test comparing hashes has to know it is there.ir.scenarios()lists the five scenario names.
On foot
The pilot of a landed ship can step out. ir.onFoot is the session's half of
walking — the browser keeps pointer lock, the look and the view — so a test or
pnpm sim puts a walker on the ground with no renderer:
ir.land('g:milky-way/s:SOL/b:3', 20, -63)
ir.step(1) // landed after one tick
ir.onFoot.stepOut() // a walker beside the ship, and now the player
ir.onFoot.status() // active, walker, ship, canFly, grounded, …
ir.onFoot.board() // back into the ship it stepped out of
ir.onFoot.atMarsPad() // parked on the Mars pad, standing beside the RocinantestepOut and board answer { ok, value } or { ok: false, error }: a ship
that has not landed on solid ground has nowhere to put a walker, and a walker
whose ship is gone has nothing to board.
A ship verb on foot boards first. goTo, orbit, shot, land, face,
burnToward, goToSystem, control, throttle, hold and flightAssist
step the walker back into its ship and then act on the ship, as the dock's
travel buttons do; with no ship to board they throw. The walker records the
ship it left and the save keeps it, so with two ships landed board reaches
the one it came from after a reload. Every session grants the walkers a loaded
save carries its own flight permission: openSession({ canFly: false })
refuses flight to a walker the save says may fly. Stepping out headlessly
leaves the clock alone; the game runs time at 1× when its player steps out.
Moving only the camera
ir.look(target, options?) moves the observatory camera without moving the
ship or changing canonical state. That distinction is deliberate:
ir.look('s:SOL/b:4') and ir.goTo('s:SOL/b:4') can both fill the frame with
Jupiter, but only goTo leaves the ship there.
ir.observatory exposes the camera itself for repeated interaction:
ir.observatory.drag(dx, dy)
ir.observatory.zoom(delta)
ir.observatory.setPhase(angle)
ir.observatory.frameTarget()
ir.observatory.clear()ir.aim(yawDeg, pitchDeg) turns the head without moving the camera. It is an
offset on whatever the pose aims at, so ir.aim(0, 0) is the way back to
the subject; it survives a drag, a dolly and a wheel notch, and is cleared by
whatever replaces the pose — a focus, a frame, a stance, a composition. Standing,
it drives the stance's own heading and pitch.
In flight the ship arm has a camera of its own, with two views. ir.view('orbit')
stands it off the hull and looks at the ship while it maneuvers — the view the
thrusters and the drive are watched from — and ir.view('chase') puts it back
behind the hull; ir.view() cycles. ir.flightCamera is the camera itself:
ir.flightCamera.drag(dx, dy) // orbit, or turn the head in the chase
ir.flightCamera.turn(dx, dy) // turn the head in either view
ir.flightCamera.zoom(factor) // dolly the orbit; above 1 retreats
ir.flightCamera.recenter() // look where the view aims againThe orbit is measured in hull lengths about the ship in the world's own axes,
pole on the local up, and tethered at eight lengths; it opens where the chase was
standing. ir.status().flightCamera reports the view, the orbit and the look,
so a plate taken beside the hull records the camera it was taken from.
Compositions
Sixteen named framings, relative to whatever is under the camera, with two placers:
ir.shots() // names and descriptions
ir.shot('crescent', address) // teleports the ship into the picture
ir.compose('crescent') // moves the camera into itThe ids are portrait, blue-marble, close, wide, half-lit, raking,
high-angle, far-crescent, backlit, full-face, gibbous, half,
crescent, glint, sunset and oblique. The last three aim at a limb or a
specular point rather than at the body's center, which is why they were
ship-only until the aim became an offset; sunset and oblique stand off below
the orbit floor, so ir.compose lands them on the surface arm.
Pictures
A portable picture stores its seed and algorithm manifest, photographic instant, target, framing and tracking state, full lens and camera processing. Built-ins and imported shots use the same validated format.
ir.presets() // ids, labels and what each one is
ir.preset('earthrise') // takes it, and fits the lens it solved
const picture = ir.capturePicture('my-view', 'My view') // held instant and full camera
ir.takePicture(picture) // validates and restores the picturetakePicture refuses a different seed or algorithm manifest. Pictures do not
carry a catalog version, so a changed catalog can move a restored shot without
a warning. This differs from canonical-save drift reporting.
ADR-0033 records the format
and current limitation.
A picture can hold its weather. Version 3 adds weather: { regime }, a
scenario's id or 'climate', and takePicture returns what became of it:
weather: 'drawn' under ?clouds=1 on WebGPU, 'unavailable' without the
flag or for a regime the build does not know, 'none' for a picture with no
weather. Taking it sets three of the clouds' levers — on, weather, and
served when the body is outside the volume's default set, which is how
Earth is drawn at all — and puts them back when the observatory lets go.
On a flagged page, taking a picture with no weather turns the clouds off
until then, so set engine.clouds after ir.preset, not before.
ADR-0067
records it.
The cornerstones are the nine pictures the weather is judged on, ids
weather-e1-cumulus-orbit to weather-g6-descent. ir.preset takes them
like any picture, and no list a player sees shows them. Each was solved for a
sun, and apps/headless/src/cornerstoneLedger.test.ts holds it there in Node;
pnpm cornerstones:ledger rewrites its snapshot.
ir.sun('s:SOL/b:2', { latitude: -5, longitude: -60 }) // { elevation, azimuth } at the held instant, degrees
ir.solveSun(
's:SOL/b:2',
{ latitude: -5, longitude: -60 },
{
elevation: 50, // or 'noon'
trend: 'falling',
after: 0,
},
) // the first instant at or after `after`, with the sun there; null if neverscripts/weather/capture.mjs takes every cornerstone in its arms — the volume
under the flag, and for E1 to E3 the deck without it — and the six scripted
casts with the clouds on and off, into the main checkout's
.data/weather/phase-<n>/, against a production preview it does not start:
pnpm build && pnpm preview &
node scripts/weather/capture.mjs --phase 1 --url http://localhost:8787/ --gpu-wait 1800 --twice --cut e1
node scripts/weather/sheet.mjs --dir <that directory> --base <the last phase's>It refuses a still that did not settle or whose weather is not its arm's, and
a cast presented outside 58 to 62 Hz: a cast's path
(scripts/weather/descent.mjs) is scheduled by frame index, a descent's
height max(h₀·(1 − rate)ᵏ, 2), so at another rate the same path runs in
other seconds.
ir.rise() is the framing behind Earthrise on its own: it stands on the body
being looked at with its parent a stated clearance over the horizon, and returns
the field of view it solved — Earth is 1.90° across from Luna and Mars is 42.39°
from Phobos, so the lens is part of the picture rather than a setting beside it.
ir.rise({ clearance: 3, height: 110000 }) // degrees and meters
ir.chrome(false) // the interface out of the frame — the plate state
ir.layers(false) // names and traces off, which is a different claimStanding on a body
The observatory has a second arm, below the orbit camera's 1.5-radii clamp.
ir.visit puts the camera on the ground and ir.ascend takes it back to the
framing it left; both are camera moves, so world.stateHash() is untouched —
ir.land is the one that teleports the ship.
ir.sites(address?) // the named places on a body, with the sun over each
ir.light(address?) // sun elevation on the ground, phase from orbit, and a verdict
ir.visit(address?, { site, height }) // stand there, now. Degrees and meters
ir.visit(address?, { latitude, longitude, heading, pitch })
ir.drop(lat, lon, { address, seconds }) // fly down there, facing the star
ir.observatory.setStanceScrub(0.5) // the height slider, logarithmic
ir.ascend() // and this abandons a drop in flight
ir.settled() // whether the sky, the ground and the clouds have stopped arrivingStand where the sun is. A picture taken in the dark compares nothing: a
star field jittering under a black disk, or a slope a low sun has left in
shadow, differs from the next capture by thousands of pixels while a lit face
differs by none. ir.sites() carries sun, the star's elevation over each
place in degrees at the held instant, so the lit site is the one with the
largest; ir.light() says the same for the view as it stands — sun on the
ground, phase from orbit with zero the full face and 180 the silhouette —
and lit is the verdict a fixture is chosen by. ir.settled() is what a
capture waits for instead of a number of milliseconds: the sky's physical
cubes publish tile by tile and the streamer fills a ring at a time, and a
still taken while either is in flight is a still of something still
arriving. The ground is also not settled until the body's deposit slope
table lands (ir.terrain().depositsPending), seconds after its tiles,
because it moves the ground's tone once at every coarse level
(ADR-0051).
pnpm drive --settle <ms> polls it.
visit cuts and drop flies, and the difference is the intent rather than
the destination. visit is what a plate is captured through, so the frame after
it returns is the frame asked for; drop is eight seconds of ballistic entry
that ends level with the horizon facing the star, which is a thing to watch and
useless to photograph the start of. ir.ascend() abandons one part-way at the
framing it left. ADR-0034.
The arm is its own module beside the observatory.
surfaceArm.ts owns the stance,
the site, the held keys, a drop in flight and the aim, and the observatory
forwards ir.observatory's surface verbs to it by the same names.
stanceGeometry.ts is its
arithmetic — the drop aid's rings and arc, a held-key flight step, the stance
at each instant of a drop — as functions of a body, a direction and an eye in
the body's rotating axes, with the figures' claims tested as properties.
heldTime.ts is the photographic
instant every pose is taken at, held or live.
Sites are derived from the body's own terrain rather than authored, so
"the highest ground on this world" survives regeneration and is still the
interesting place afterward. Four come from a beam search — summit, basin,
shore, rough — and two are chosen outright for the renderer: corner, where
three faces of the addressing cube meet, and pole, where the east/north basis
is singular. A world that drains names four more off its drainage graph
(ADR-0043) — headwater, confluence,
mouth and lake: the source of the largest river, the junction of its
largest tributary, where it meets the sea, and the largest lake — each stood
on the water the field draws. On a body with no solid surface ir.sites returns an empty list:
a giant's parameters run through the survey without complaint, but every row
would be a place ir.visit refuses to stand. A station gets the same empty
list and the same refusal from ir.descend, named or as the subject on screen.
The height is set outright rather than eased, which is what makes a plate loop
work: each ir.visit is the frame you asked for, with nothing settling in
between.
for (const height of [40000, 2000, 120, 2]) {
ir.visit('g:milky-way/s:SOL/b:5.6', { site: 'pole', height })
// capture here
}The performance timeline
ir.timing() // the level: off | trace | full
ir.timing('trace') // the same switch the URL, the preference and the panel reach
ir.timing.tracks() // what this session has actually emitted onto
ir.timing.mark('after the seek') // a marker of your own, across every track
ir.timing.drain() // the retained entries, cleared by name on the way out
await ir.profile(2000) // arm, record, disarm, reportir.profile is the one that answers a question. It returns structured data and
a .text block — the shape terrainBaseline established — because the point is
a terminal-readable answer from a single --js call:
node scripts/drive.mjs --url http://localhost:5173/planetarium \
--js "ir.visit('g:milky-way/s:SOL/b:2',{site:'summit',height:2})" \
--wait 5000 --js "(await ir.profile(2000)).text"
node scripts/drive.mjs --downThe last line of the report is the deliverable: "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" rather than a screenshot and a p95. It names the largest span inside the late frames, not the busiest one overall — a span that is cheap on average and catastrophic four times is exactly what a mean hides — and carries the frame duration beside it, because the ratio is what says whether the name explains anything. A worker job is never named: the pool times it from dispatch to answer on the page's clock, so it starts inside a frame and outlives it, and it ran on another thread.
Three things it will not tell you, each for a reason worth knowing.
The worker tracks are absent from a drain. A worker's User Timing entries
live on the worker's own performance timeline, invisible to the page's
getEntriesByType, because each side times and emits against its own
timeOrigin. They are in a trace, on their own threads — pnpm timing --threads separates them.
A share of frame time is undefined for concurrent spans, printed as an em dash. Worker queue waits overlap each other and the frames they cross, so the ratio is real and describes nothing.
A span under about 300 µs is a mean, not a reading. performance.now() here
steps in 100 µs — nothing sets COOP/COEP — so one bar is not a measurement even
though a window of them is.
ir.profile restores the level it found, so a profile taken mid-session does
not leave the timeline retaining for the rest of it. off is the default
everywhere: there is no capability query for the custom-track arguments, so a
level that turned itself on would make browsers that cannot draw these entries
pay for them anyway.
Recording a trace instead, and reading it back:
node scripts/drive.mjs --url "http://localhost:5173/?timing=trace" --wait 5000 --trace 3000
pnpm timing --top 20 # the table and the verdict
pnpm timing --track Tasks --threads # one row per workerMeasuring the picture
ir.picture() // live reconstruction report; null without a renderer
ir.picture('motion') // temporal velocity
ir.picture('disocclusion') // rejected history
ir.picture('reactivity') // blended regions that reduce history reuse
ir.picture('none') // return to the imageThe other temporal debug views are depth, age, locks, exposure and
shading. The report states path, integer renderWidth/renderHeight and
displayWidth/displayHeight, jitter phase and phaseCount, submitted
frames, history resets, initialization initMs and gpuTimings by pass.
Timestamp availability depends on the backend and detailed timing being enabled.
workingTextureBytes counts raw upscaler textures, excluding the scene,
optical targets and driver overhead. It is not total GPU memory.
Select a repeatable picture through the URL: ?picture=native,
?picture=msaa:quality, ?picture=temporal:quality or
?picture=bilinear:quality. An optional third field selects sharpness, such as
temporal:quality:crisp; the bilinear diagnostic takes only the scale. The
page override does not change saved settings. Temporal native is available as
?picture=temporal:native.
Compare a fixed camera on a generated world outside Sol, at a held photographic
instant and identical display dimensions. Allow at least phaseCount presented
frames after a temporal cut, record the phase with the plate and compare two
boots of the same build to establish its own variation. Use ir.gpu() for the
complete chain and the report's per-pass readings for reconstruction alone.
Testing gives the focused gates.
Where the GPU's frame goes
await ir.gpu(40) // ms per presented frame, across a drained queue
await ir.passes(40) // the same frames, by named passir.passes holds the loop, submits the frames through the presenting chain
with a timestamp pair on every pass three encodes, and names each pass by its
target: scene is the sensor's pass, scene after copy is the same pass
resumed after the sea read the frame behind it, defocus 0–3,
motion tile max, motion neighbor max, motion blur, psf down 0–5,
psf up 0–4 and psf resolve are the optics, galaxy volume,
galaxy rays, galaxy history, galaxy structure and galaxy sky are the
galaxy's, canvas is the output, and under ?clouds=1 with the clouds on,
scene over clouds is the second scene pass and cloud maps,
cloud clipmap, cloud volume, cloud sun grid, cloud far atlas,
cloud far second, cloud depth, cloud trace and cloud history are the
passes issued inside it (Measuring the weather). Every quad pass is named where it draws,
by runQuadPasses in render/quadPass.ts. It returns wallMs —
ir.gpu()'s figure over the same frames — beside busyMs, the passes' shares
summed, and the two agree within 2% at the shore; a larger disagreement is time
in work the timeline does not see, such as the upscaler's own passes, which
shows in gaps. Those passes are also reported beside the rest under owned:
the upscaler lends the timeline its own timer for the run, and its compute
passes come back as { source, label, samples, latencyMs } — the package's
begin-to-end means, latency rather than share, and not in busyMs. Adding
owned to gaps counts that work twice. The package's timer has eight query
slots and a run draws its frames back to back, so samples is at most eight
whatever the frame count: the run's first frames.
A frame's pass count sets how many frames a read can take. One query set
holds 2,048 passes, and a read that runs out drops the rest and reports
dropped; the summary divides by the frames asked for, so a read that dropped
passes reports every label low. A frame without clouds is about 21 passes and
ir.passes(40) fits. A steady cloud frame is about 40, and one that rebuilds
its caches about 100, so read one frame first, take
floor(2000 / passes) frames up to 40, and refuse a read with dropped > 0.
The weather's runner does exactly that.
A pass's ms is its share, not its timestamp pair. Apple's GPUs pipeline
passes and frames, and Metal samples a pass's timestamps at its stage
boundaries, so the raw pair is latency: at the shore every pass, a 60×37 blur
level and the output quad included, read 23–35 ms begin to end in a 24 ms
frame. Each pass is charged for how far it moved the completion frontier
instead, and the raw pair is kept as latencyMs.
render/passTimeline.ts has the
arithmetic, and why three's own timestamp tracking cannot be read for this.
A lever's cost is the difference in wallMs with the lever moved, taken in
one boot: the default read at the start and the end of a sweep agrees within
1.5 ms, and a second boot can read every pass a third slower at once. Set the
lever on engine.surfaceQuality, let the terrain settle, then measure.
Name the thermal state with the figure. The fanless MacBook Air steps every figure up about 35% after about three and a half minutes of load, so a sweep there that outlasts the onset charges the step to whichever lever it lands on. Read the default again between levers, and say whether the machine was cool or how many minutes it had been under load. Driving, trap 8, has the step, the fan-cooled Mac mini's figures and the rule.
Measuring terrain
ir.zoo() // one body per surface archetype, found rather than listed
ir.descend(address?, { site, steps }) // fly a descent on paper
ir.terrain() // what the live streamer holds this frame, rocks included, and who produces it
ir.terrainBaseline() // the zoo, its descents, and measured patch cost
engine.surfaceQuality = { terrain: 'coarse', ground: 'lean', sea: 'plain', rocks: false } // the levers
orbitalBaker.report() // which generated bodies have a baked sphere, and whether it is ready
orbitalBaker.targetFor(address) // its two cube targets — albedo and relief — for a face readback
ir.dossier(address) // the record, whose Geology card is the surface grammarir.descend runs with no world state changed, no worker used and no frame
drawn, so it produces the same level churn, peak burst and cache numbers in a
browser console, in pnpm sim --terrain-baseline and in a Node test. It takes
latitude and longitude in degrees, the same boundary ir.visit, ir.drop
and ir.land state — ir.sites output pastes straight in, and radians begin
below the harness.
ir.terrain is the counterpart: what the streamer actually has, which is
null headlessly rather than a zero. Its patches counts ground built and
placed this frame, not the selection's length — a cold arrival reports zero
patches over zero vertices rather than six regions still in a worker. It states
both caches, cached for heightfields and geometry for meshes, because they
fail differently: refinement gates on the mesh, so a geometry cache losing what
the draw set is standing on collapses the selection to the roots while cached
sits at its steady value and reports nothing wrong.
visited, culled, starved and level are from the last frame that
walked, not from this one. The walks are a pure function of the eye, the
optics, the level floor and the geometry cache, so a stance or a converged
hover holds all four still and reuses the answer — the counters stay at
whatever the last re-selection left. selections is the one that says so: a
total since the streamer was made, so 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 the rest or visited: 446 will describe a frame that
walked nothing.
ir.terrain().producer is where the next heightfield request goes — gpu
for the tile producer, pool for the worker pool, none for a session with
neither; headlessly ir.terrain() itself is null — rather than where the
ground on screen came from, because a producer can stop mid
session and the fields already held came from wherever they came from.
?producer=cpu on the URL keeps the pool on a WebGPU page, which is the A/B
every GPU figure was taken against.
The browser's persistent archive is separate from those live streamer counts:
await engine.terrainCache() // availability, activity counters and retained storage
await engine.clearTerrainCache() // discard the archive without changing savesactivity distinguishes hits, misses, invalid records, successful writes,
read/write errors, cancellation and pending writes. storage reports retained
entries and bytes alongside their limits. An unavailable store reports
available: false; generation continues. CPU and GPU producer records remain
separate even though their storage and activity counters share the archive.
The first frame on a body reports zeros for a reason that is not the relief gate. The subdivision floor is a worker answer, so a body the streamer has not measured has no ceiling to select against and it holds the ground back rather than guessing one — the same way it waits for the heightfields.
ir.terrain().scatter is the rocks on it, and it is part of the terrain report
rather than a verb of its own because a rock count without the ground under it
is not a number anyone can act on: resolving above zero beside rocks at zero
is a field filling in, and the same pair beside starved is a descent
outrunning both budgets at once. range is how far rocks are drawn this frame —
212 m at the flight lens over the baseline viewport, and a function of the lens
like everything else here.
Every frame-rate figure is a function of the surface levers as well, so
state them. engine.surfaceQuality is the field the frame loop reads — the
refinement threshold, the ground's octaves, the sea's frame read and waves,
the rocks — and a driving script can set it between two --casts to measure
one term: render/quality.ts names what each step spends. ground: 'full'
is the macro band and the eroded detail under it — the micro octave and the
grain damped by their slope, the gullies, the talus clamp — and 'lean' is
the macro band alone, so the two differ by everything finer than a
kilometer. The materials
compare before they write, so flipping a lever costs the next frame nothing
but the change. The record that outlives the session is the render.surface
preference, which the graphics panel edits and state/engineKnobs.ts carries
to the field, so a script's write holds until that key next moves and does not
survive a reload — which is what you want of a measurement.
Every count here is a function of the lens, so every report states one. The
demand climbs steeply with the pixels-per-radian — measured, a whole disk at the
telephoto end wants 2,063 to 12,330 patches standing where the flight lens wants
456 to 1,061 — so a figure taken without the optics beside it is one nobody can
reproduce or compare with yesterday's. The live streamer also knows where the
picture looks: past the flight lens it refines at the lens only where the frame
can reach, and ir.terrain().outside counts the patches it refined at the
flight lens instead. ir.descend and ir.terrainBaseline have no camera to
aim, so they refine the whole disk at whatever lens they are handed — the
conservative question, and a different one. ir.descend and ir.terrainBaseline print the lens and the
viewport in their headers and carry both in the returned object; ir.terrain
carries the live one. Both probes take a lens and a viewport to ask the
question at another setting, and ir.descend takes a maxPatches — the
streamer's own 1,280 is a safety net that degrades the whole disk by a level
when it bites, so raising it is the only way to see what a selection wanted.
Measuring the weather
The cloud system exists only under ?clouds=1, and draws only once its lever
is on. Without the flag there is no cloud object, pipeline, allocation or layer
mark, and ir.clouds() is null.
engine.clouds = { ...engine.clouds, on: true, weather: 'broken-horizon' }
ir.clouds() // the report: levers, their hash, frame, caches, bytes, steps
ir.clouds().leversHash // eight hex digits over the levers the frame drew with
ir.clouds().settle // { pending, history: 'n/32', caches } — null while off
await ir.cloudRadiance() // the next frame at the trace's texels: luminance and cloud mask
ir.cloudRadianceDifference(a, b) // two captures' radiance RMSE over their cloud texelsengine.clouds is the lever set (render/cloudLevers.ts). The chain reads it
every render call, so a change lands on the next frame, and the setter throws on
a set with an unknown key or a value out of range. Always spread the current
value: the guard takes a whole set.
The volume serves a wet world with no authored cloud deck, and no other
unasked. Earth has a deck, so on alone draws nothing over Earth: name it,
served: 'g:milky-way/s:SOL/b:2', and its deck hides while the volume draws.
leversHash binds a capture to its lever set. It covers every lever but
the ones that only steer a measurement (force, warp, scrubSeconds,
flySpeed, jitterFrame, stats), so a forced row and its steady row share
one hash.
| Lever | What it does |
|---|---|
on |
Draws the clouds. Off by default |
weather |
What every clouded body draws. climate, the default, is the body's own, which is one regime, fair-cumulus, on every wet body. A regime's id holds that regime over the whole body: fair-cumulus, broken-horizon, inside, two-decks, near-gap-far, cirrus-over-cumulus, anvil, overcast, fog, and the cornerstones' altocumulus, dusk-altocumulus (the deck ending where the local sun clears the horizon) and stratocumulus |
maxSteps, lightTaps, farFootprint |
The quality ladders: 192 steps, 4 taps, a handover where a trace texel spans 800 m. lightTaps takes 0, 2, 4, 6 and 8, and 6 and 8 draw as 4 |
traceScale |
0.5, 1 or 2 times the trace's extent |
composite |
identity, thin, or residual, which draws nothing and fills ir.clouds().residual after the frame |
force |
A path a held loop never takes: reset, cut, scrub, warp, fly |
warp, scrubSeconds, flySpeed |
The forced paths' time scale, seconds a frame and m/s |
jitterFrame |
Holds the trace's jitter at one frame index, so a held still repeats every four frames |
served, second |
Force the served body, and a second clouded one, by address |
deck |
hidden hides every cloud deck whatever on is, which prices Earth's deck against the volume |
stats |
Counts each ray's steps into ir.clouds().steps |
phaseMode, phaseBins, jitter, transport, over, sunSlices, sunRamp, farBlocks |
The measured choices: two or more candidates behind one lever until a campaign picks one. Each stands at the candidate the frame draws, and setting another draws the same frame |
handoverBand, clip |
The handover band's width as a ratio of footprint, and the history clip's half-width in standard deviations. Neither is read by a pass |
ir.gpu() and ir.passes() hold the loop, and a held loop never cuts,
scrubs or flies. The frame's cloud state is built inside the chain, so a held
frame still measures real work with live uniforms, but it is always the steady
path. force makes every held frame take the path named: under cut each
frame rebuilds every eye-anchored cache as a teleport does, under scrub each
jumps the field scrubSeconds and turns the sun with the body, and under fly
the rays and the caches follow a synthetic eye at flySpeed. The cost is the
real one and the picture is not.
ir.settled() waits on the clouds. Its clouds is the report's own
settle, null while the system is off or absent. settle.pending is true
while any cache is pending or the history is under 32 frames old, the frames
its 1/8 weight floor takes to hold eight samples a pixel. A forced path never
settles, so cap the wait: 240 frames is longer than the far atlas's 45-frame
cycle.
Compare two images with the jitter held. Two frames four apart differ by
about 2% of radiance under the moving jitter, which is more than a 1% rule can
read. Set jitterFrame, capture with ir.cloudRadiance() on each side, and
difference them.
The runner
scripts/clouds/measure.mjs runs the weather's batches on the rig, base and
candidate interleaved in one boot, under one hold on the machine's GPU lock.
scripts/clouds/campaign.mjs runs them end to end, detached, for the hours a
campaign takes.
pnpm preview # builds, then serves 8787
node scripts/clouds/measure.mjs --batch stances # every scenario's sun, passes and a still
node scripts/clouds/measure.mjs --batch targets --gpu-wait 900
node scripts/clouds/measure.mjs --batch images --dry-run # the plan; nothing launches
node scripts/clouds/campaign.mjs start landed # detaches; prints where it writes
node scripts/clouds/campaign.mjs status
node scripts/clouds/campaign.mjs stop # rigs closed, lock and preview released
node scripts/clouds/campaign.mjs start landed --resume # where a stopped one left off| Batch | Measures |
|---|---|
stances |
Each scenario's sun, its pass list and a still, before a batch stands on it |
images |
The radiance differences the quality ladders are read from |
targets |
The landed frame against clouds off: steady, cut, scrub and fly, on a generated world and on Earth with its deck priced |
memory |
Cold compile: three boots with the flag and three without at each size, each on a deleted Chrome profile |
error |
The composite's residuals on the scene as built, Enhanced off and on |
A campaign is choices (images, then the instruments) or landed
(targets, memory, error, then the instruments). Each batch writes
.data/clouds/<batch>-<time>.json and prints its Markdown tables; a campaign
keeps its state, its log and its summary in .data/clouds/campaign/.
- Production only. Dev React costs about five times the shipped CPU, and
the second scene pass's traversal is a CPU cost. Every invocation passes
--no-serveagainst the preview, and the runner refuses a URL that does not answer. The preview names no tree, so a figure is tied to the code by the commit, a clean status and a build that carries the commit's build id (thegit describethatvite.config.tsdefines into the bundle). A file's time cannot say it: a bundle built at one commit is newer than an older commit checked out after it. A dirty tree is refused without--allow-dirty, which marks every row. - A quiet machine is checked, not assumed. The GPU lock keeps other GPU
jobs off the machine and nothing else. Before and after every run the runner
reads the one-minute load and scans the process table for
vitest,tsc,tsgo,vite,astro,oxlint,knip,pnpmand another rig'sdrive.mjs. Quiet is a load of at most half the cores (--max-load) with none of them running. It waits up to ten minutes for a quiet start, takes again a run that ends under load, and a row marked not quiet counts toward no decision. A Stop-hook gate in a sibling session is the usual cause. - Every row records the rate it presented at.
operatingPoint.presentHzis read with the clouds off before the row measures. A CPU span and a late-frame count follow the rate;ir.gpu()'s difference does not. Compare frame-paced figures only between rows at one rate. - The rigs are the runner's own: measurement on port 9341 and cold boots
on 9342. Before each cold boot the runner closes the rig and deletes
.data/drive/profile-9342, becausedrive.mjskeeps one Chrome profile a port and Chrome's GPU caches live in it;--freshonly reboots the page. The OS's Metal shader cache lives outside the profile and is not cleared, so a cold figure is "a fresh Chrome profile, the OS cache possibly warm". - Every stance starts from its preset's picture. One page serves every run
of a size and preset in turn, and
ir.visitsets no lens, so a stance applies its preset first: its lens, time and processing, then the visit, the rise or the raise over them. Without it, a run after the moon's rise looks through the rise's lens. A forced row's clouds-off base and its stance's steady one should agree; where they do not, the stance is not the one specified. - A row finishes its run only when it is quiet and whole. A residual drawn
under the other processing, a radiance capture that answered null, or a
stance whose scene drive.mjs's settle gave up on is kept in the document,
named in the table's
quietcolumn, and written as a failure of its run. - A batch can be continued.
--resume <file>keeps the runs whose rows finished them and runs the rest. Exit 1 is a batch that stopped and is worth continuing; exit 2 is a refusal the same command would meet again.
The instruments
Three GPU tests measure rather than gate. They are skipped unless
IR_CLOUD_MEASURE is set, write .data/clouds/<name>.json, and assert only
that every figure is finite and inside a sanity bound.
IR_CLOUD_MEASURE=1 IR_GPU_WAIT=900 pnpm vitest run --config apps/game/vitest.gpu.config.ts cloudFarCompare cloudSunAccuracy cloudCompositeError| Test | Scores |
|---|---|
cloudFarCompare |
The far atlas against the fine march over the whole ray, on four handover cases at three footprints |
cloudSunAccuracy |
The sun grid's T_cloud against a 256-step march of the field, at five scenarios and two suns |
cloudCompositeError |
The identity and the thin form against a 512-sample joint march of air and cloud, on analytic slabs |
Each run overwrites its file. A campaign's summary names the three paths and
copies none of them, so keep a copy under the campaign's name before the next
one runs; phase 0's are in
design/plans/weather/phase0/measurements/.
ADR-0063
and
ADR-0064
have what they measured.
Scripted scenes
ir.cutscene.list() // scenes with descriptions and durations
ir.play('tng-intro')
ir.pause()
ir.seekCutscene(1150)
ir.cutscene.status() // the playhead, or null
ir.cutscene.lastOutcome() // ended, stopped or abandoned
ir.stopCutscene()ir.cutscene is the director itself, the way ir.observatory is the
observatory; play, seekCutscene and stopCutscene stay on ir as the
verbs a console types. The scenes it plays are a session option,
openSession({ cutscenes }), defaulting to the shipped ones.
Pause before seeking for a frame-exact still. The browser needs to render after the seek before the sampled cinematic state is current; follow the capture procedure in Driving.
The soundtrack
ir.soundtrackStatus() // state, track, position, upcoming, context, and why not
ir.soundtrack('next') // the panel's verbs: play, pause, next, previous, card
ir.soundtrack('seek', 120) // seconds into the current track
ir.soundtrack('select', 'stellardrone-red-giant') // jump the queue to a track
ir.soundtrack('cue', 'lofi') // a category, or a track id, over the crossfadeThe rig has no ears, so this is how a run proves the player does what its panel
claims: a track id that changes after next, a position that advances, a
state that reads waiting until a gesture and playing after it. context is
the AudioContext's own state, none until the first gesture builds the graph.
Both answer available: false outside a build with the player mounted, and the
player plays only in the Planetarium, so a status read anywhere else says off.
Scenarios
await ir.scenario('orbit') // circular orbit, 300 km
await ir.scenario('approach') // burning toward a world
await ir.scenario('surface') // parked on the ground
await ir.scenario('interstellar') // holding off Alpha Centauri
await ir.scenario('descent') // orbit to 2 m over every zoo body, on paperNamed, repeatable set-ups. Each returns the resulting status, so a test can assert on it directly.
Proving
const report = await ir.selfTest()
console.log(report.report)Runs the twelve capability checks and returns { passed, total, results, report }.
The results array is structured, so a driver can assert on individual checks
rather than parsing text.
12/12 capabilities proven
PASS 5. Approach a planet — fell 16.65 m in 60 s at 0.0092 m/s², within 0.03% of free fall
PASS 9. Origin rebasing — 500 rebases, 2560 km of origin travel, zero drift
…Five checks build scratch worlds. The rest read the live session — and capability 3 is not read-only: it loads Alpha Centauri in order to measure the distance to it, so after a self-test the session has two systems loaded rather than one. Worth knowing before using the self-test as a mid-session probe.
Persistence
const text = ir.save() // serialized save; size follows dynamic state and references
ir.load(text) // → Result<stateHash, error>load returns a Result rather than throwing — a save is untrusted input.
Driving from an automated browser session
scripts/drive.mjs is the driver — the Chrome
DevTools Protocol against a Chrome it launches itself, never an extension in
somebody's own browser. pnpm drive --help, and the
drive skill for the traps.
drive.mjs is the entry point, and holds the flags, the
help text, the state file, Chrome and the dev server, and the main() that
wires them. driveSteps.mjs plans the step
list from the command line and runs it over a rig of callbacks, and holds the
--settle rule — two consecutive quiet ir.settled() answers inside a
budget. cdp.mjs is the wire: connect over a
socket, evaluate, the buffered logs, and the screencast and trace
recordings. drivePage.mjs clears storage,
climbs the boot ladder — drawing, booted, document mode, the twelve-second
cover give-up — and holds every entry, and --status's read, to its operating
point; driveLaunch.mjs is that guard's
checks: the renderer, the adapter, the window, the drawing buffer and the
served tree. driveLock.mjs is the rig's hold
on the machine's GPU lock, gpuLock.mjs, from
before Chrome launches until --down. Each has a .test.mjs beside it that
runs against a fake socket, a scripted send, a fake rig or a lock file of its
own, so a change to how the driver decides is checked by pnpm test without a
browser; only what a compositor shows needs the real invocation.
The pattern that works well:
sequenceDiagram
participant A as driver
participant P as page
A->>P: navigate
A->>P: wait (textures stream in after a look or a seek)
A->>P: ir.scenario('surface')
A->>P: ir.step(20000)
A->>P: JSON.stringify(ir.status())
P-->>A: structured state
A->>A: assert, screenshot, iterateRead state back as JSON and assert on it. A screenshot tells you something
rendered; ir.status() tells you what. --sample <n> reads one value per
animation frame from inside the page, which is the only way to see something
that moves — a strobe, a level churn, a stall — because a still cannot show it
and a round trip per frame is longer than a frame.
Extending the harness
Add a method when a sequence is one you keep retyping — that is the signal it is
part of the vocabulary rather than a one-off. Keep the return JSON-serializable
and add the line to help(), which is what people actually read.
window.ir keeps every name it has. Verbs a console types stay flat on the
harness and instruments are sub-objects (ir.cutscene, ir.observatory,
ir.onFoot, ir.timing); scripts/drive.mjs, this page and help() are the
callers a rename breaks. One of those breaks is silent: the guard in
scripts/driveLaunch.mjs reads ir.build() with optional chaining, because a
build older than the verb is a legitimate baseline, so a renamed build reads
as identity unchecked and the served-tree check stops refusing anything.
Anything lifted out of the harness or the observatory
takes Host from host.ts, or a narrower port declared beside it, and is
tested through openSession({ workers: null }) the way maneuvers.test.ts is.
If a set-up sequence is shared with the app or the runner, it belongs in
openSession instead, which owns standing a world up — see
extending.
Related
- Observability — what the harness reads from
- Testing — turning a session into a regression test