@origingame/engine 0.2.0 → 0.3.0

package/knowledge/wiki/probe.md

@@ -20,7 +20,7 @@ module probe {
   # declarations follow, each quoted below
 ```
 
-<sub>`api.ogt` line 10526</sub>
+<sub>`api.ogt` line 12248</sub>
 
 ## Contents
 
@@ -36,11 +36,13 @@ module probe {
 | [`ProbeTunable`](#type-ProbeTunable) | struct | One published tunable parameter and the range it means something over. |
 | [`ProbeEntityRef`](#type-ProbeEntityRef) | struct | One entity the probe publishes in state(). |
 | [`ProbeTimings`](#type-ProbeTimings) | struct | The fixed timings head of state(). |
+| [`ProbeTiming`](#type-ProbeTiming) | struct | One named span of the last tick or frame. |
 | [`ProbeState`](#type-ProbeState) | struct | The probe's state(): a fixed head, then the game's own facts. |
 | [`AdvanceOperation`](#type-AdvanceOperation) | struct | The advance operation's payload. |
 | [`InputOperation`](#type-InputOperation) | struct | The input operation's payload. |
 | [`PickOperation`](#type-PickOperation) | struct | The pick operation's payload. |
 | [`EntityOperation`](#type-EntityOperation) | struct | The entity operation's payload. |
+| [`ExpectOperation`](#type-ExpectOperation) | struct | The expect operation's payload. |
 | [`ProbeOperation`](#type-ProbeOperation) | union | One operation of a probe program, which runs in one evaluation so a scripted segment costs one round trip. |
 | [`ProbeProgramResult`](#type-ProbeProgramResult) | struct | What a program observed: one answer per operation that ran. A false, or entity's null, stops the program and `refused` names its index. |
 | [`Hello`](#type-Hello) | struct | The wire's hello: who is speaking. |
@@ -65,7 +67,21 @@ module probe {
 | [`UiElement`](#type-UiElement) | struct | One UI element with its bounds. |
 | [`UiSurface`](#type-UiSurface) | struct | The surface UI bounds are laid out on. |
 | [`UiDump`](#type-UiDump) | struct | The UI tree, flattened in draw order. |
+| [`DesyncDump`](#type-DesyncDump) | struct | The first desync of this peer's lockstep session (og.net), as `dump_desync` writes it. |
 | [`DumpResult`](#type-DumpResult) | union | A dump, tagged by its kind. |
+| [`ScreenBox`](#type-ScreenBox) | struct | A box on the play surface. |
+| [`ScreenPoint`](#type-ScreenPoint) | struct | A point on the play surface. |
+| [`DescribedEntity`](#type-DescribedEntity) | struct | One entity the frame shows, from the entity-id pass (a CPU rasterisation of the frame's meshes, skinned meshes and world sprites at a quarter of its pixels). |
+| [`DescribedView`](#type-DescribedView) | struct | A secondary camera (og.CameraView, og.Mirror) and what its image shows: its own entity-id pass, from its eye and on its layers, at a quarter of its image's pixels, whatever its `every`. An entity only its layers admit (a layer the main camera leaves out) is listed here and not in Description.entities. |
+| [`DescribedUi`](#type-DescribedUi) | struct | One UI element as describe lists it (the tree dump_ui writes). |
+| [`DescribedCamera`](#type-DescribedCamera) | struct | The camera as drawn, with its shake. |
+| [`PassSize`](#type-PassSize) | struct | The entity-id pass's size. |
+| [`Description`](#type-Description) | struct | The frame as data: deterministic, the same JSON on every host and backend for the same world. |
+| [`ExpectStatus`](#type-ExpectStatus) | enum | How an expectation came out. |
+| [`ExpectResult`](#type-ExpectResult) | struct | One evaluated expectation. |
+| [`ExpectReport`](#type-ExpectReport) | struct | The expectations evaluated since the last call. |
+| [`SavedScene`](#type-SavedScene) | struct | The scenes written back from the world: the head is the boot scene's (or the first instantiated one's), `scenes` lists every one. |
+| [`SavedSceneFile`](#type-SavedSceneFile) | struct | One scene file written back. |
 | [`RuntimeProbe`](#type-RuntimeProbe) | interface | RuntimeProbe protocol 5, member for member. Every member answers synchronously with JSON-serialisable values. |
 | [`EngineProbe`](#type-EngineProbe) | interface | The engine's probe: protocol 5 plus the wire members of the loopback WebSocket and the in-page request ring. |
 
@@ -84,7 +100,7 @@ interface RuntimeProbe {
   # members follow, each quoted below
 ```
 
-<sub>`api.ogt` line 10869</sub>
+<sub>`api.ogt` line 12778</sub>
 
 <a id="member-RuntimeProbe-version"></a>
 
@@ -104,7 +120,7 @@ prop version u32 "PROBE_VERSION." {
 }
 ```
 
-<sub>`api.ogt` line 10873</sub>
+<sub>`api.ogt` line 12782</sub>
 
 <a id="member-RuntimeProbe-tick"></a>
 
@@ -128,7 +144,7 @@ fn tick {
 }
 ```
 
-<sub>`api.ogt` line 10876</sub>
+<sub>`api.ogt` line 12785</sub>
 
 <a id="member-RuntimeProbe-state"></a>
 
@@ -152,7 +168,7 @@ fn state {
 }
 ```
 
-<sub>`api.ogt` line 10881</sub>
+<sub>`api.ogt` line 12790</sub>
 
 <a id="member-RuntimeProbe-advance"></a>
 
@@ -180,7 +196,7 @@ fn advance {
 }
 ```
 
-<sub>`api.ogt` line 10886</sub>
+<sub>`api.ogt` line 12795</sub>
 
 <a id="member-RuntimeProbe-pause"></a>
 
@@ -203,7 +219,7 @@ fn pause {
 }
 ```
 
-<sub>`api.ogt` line 10891</sub>
+<sub>`api.ogt` line 12800</sub>
 
 <a id="member-RuntimeProbe-resume"></a>
 
@@ -226,7 +242,7 @@ fn resume {
 }
 ```
 
-<sub>`api.ogt` line 10895</sub>
+<sub>`api.ogt` line 12804</sub>
 
 <a id="member-RuntimeProbe-input"></a>
 
@@ -255,7 +271,7 @@ fn input {
 }
 ```
 
-<sub>`api.ogt` line 10899</sub>
+<sub>`api.ogt` line 12808</sub>
 
 <a id="member-RuntimeProbe-accepted"></a>
 
@@ -278,7 +294,7 @@ fn accepted {
 }
 ```
 
-<sub>`api.ogt` line 10905</sub>
+<sub>`api.ogt` line 12814</sub>
 
 <a id="member-RuntimeProbe-pick"></a>
 
@@ -309,7 +325,7 @@ fn pick {
 }
 ```
 
-<sub>`api.ogt` line 10909</sub>
+<sub>`api.ogt` line 12818</sub>
 
 <a id="member-RuntimeProbe-entity"></a>
 
@@ -338,7 +354,7 @@ fn entity {
 }
 ```
 
-<sub>`api.ogt` line 10916</sub>
+<sub>`api.ogt` line 12825</sub>
 
 <a id="member-RuntimeProbe-bounds"></a>
 
@@ -366,7 +382,7 @@ fn bounds {
 }
 ```
 
-<sub>`api.ogt` line 10922</sub>
+<sub>`api.ogt` line 12831</sub>
 
 <a id="member-RuntimeProbe-patch"></a>
 
@@ -398,7 +414,7 @@ fn patch {
 }
 ```
 
-<sub>`api.ogt` line 10927</sub>
+<sub>`api.ogt` line 12836</sub>
 
 <a id="member-RuntimeProbe-run"></a>
 
@@ -426,7 +442,7 @@ fn run {
 }
 ```
 
-<sub>`api.ogt` line 10934</sub>
+<sub>`api.ogt` line 12843</sub>
 
 <a id="type-EngineProbe"></a>
 
@@ -444,7 +460,7 @@ interface EngineProbe {
   # members follow, each quoted below
 ```
 
-<sub>`api.ogt` line 10941</sub>
+<sub>`api.ogt` line 12850</sub>
 
 <a id="member-EngineProbe-hello"></a>
 
@@ -468,7 +484,7 @@ fn hello {
 }
 ```
 
-<sub>`api.ogt` line 10946</sub>
+<sub>`api.ogt` line 12855</sub>
 
 <a id="member-EngineProbe-capture"></a>
 
@@ -509,7 +525,7 @@ fn capture {
 }
 ```
 
-<sub>`api.ogt` line 10951</sub>
+<sub>`api.ogt` line 12860</sub>
 
 <a id="member-EngineProbe-sweep"></a>
 
@@ -539,7 +555,7 @@ fn sweep {
 }
 ```
 
-<sub>`api.ogt` line 10964</sub>
+<sub>`api.ogt` line 12873</sub>
 
 <a id="member-EngineProbe-reload"></a>
 
@@ -562,7 +578,7 @@ fn reload {
 }
 ```
 
-<sub>`api.ogt` line 10971</sub>
+<sub>`api.ogt` line 12880</sub>
 
 <a id="member-EngineProbe-snapshot"></a>
 
@@ -585,7 +601,7 @@ fn snapshot {
 }
 ```
 
-<sub>`api.ogt` line 10975</sub>
+<sub>`api.ogt` line 12884</sub>
 
 <a id="member-EngineProbe-restore"></a>
 
@@ -613,7 +629,7 @@ fn restore {
 }
 ```
 
-<sub>`api.ogt` line 10979</sub>
+<sub>`api.ogt` line 12888</sub>
 
 <a id="member-EngineProbe-dump"></a>
 
@@ -643,7 +659,7 @@ fn dump {
 }
 ```
 
-<sub>`api.ogt` line 10984</sub>
+<sub>`api.ogt` line 12893</sub>
 
 <a id="member-EngineProbe-commands"></a>
 
@@ -671,7 +687,7 @@ fn commands {
 }
 ```
 
-<sub>`api.ogt` line 10991</sub>
+<sub>`api.ogt` line 12900</sub>
 
 <a id="member-EngineProbe-listen"></a>
 
@@ -701,7 +717,7 @@ fn listen {
 }
 ```
 
-<sub>`api.ogt` line 10996</sub>
+<sub>`api.ogt` line 12905</sub>
 
 <a id="member-EngineProbe-memory"></a>
 
@@ -724,7 +740,115 @@ fn memory {
 }
 ```
 
-<sub>`api.ogt` line 11003</sub>
+<sub>`api.ogt` line 12912</sub>
+
+<a id="member-EngineProbe-describe"></a>
+
+#### `EngineProbe.describe`
+
+The frame of the current tick as data: the visible entities with screen boxes, depth order and occlusion from the entity-id pass, their names, archetypes and labels; the UI elements with rects and text; the camera. Answers without a renderer too (the pass runs on the CPU).
+
+```ts
+EngineProbe.describe(): Description
+```
+
+**Returns** `Description`.
+
+Binding symbol `og_engine_probe_describe` · publish builds: dropped
+
+```ogt
+fn describe {
+  doc "The frame of the current tick as data: the visible entities with screen boxes, depth order and occlusion from the entity-id pass, their names, archetypes and labels; the UI elements with rects and text; the camera. Answers without a renderer too (the pass runs on the CPU)."
+  returns Description
+}
+```
+
+<sub>`api.ogt` line 12916</sub>
+
+<a id="member-EngineProbe-expect"></a>
+
+#### `EngineProbe.expect`
+
+Evaluate one expectation now (the forms of the command channel's `expect:`); the result is also kept for expectations().
+
+```ts
+EngineProbe.expect(what: string): ExpectResult
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `what` | `string` | no | The expectation, such as `entity:crate:within:0,0.4,-1,1,0.6,1`. |
+
+**Returns** `ExpectResult`: A malformed expectation is a malformed call.
+
+Binding symbol `og_engine_probe_expect` · publish builds: dropped
+
+```ogt
+fn expect {
+  doc "Evaluate one expectation now (the forms of the command channel's `expect:`); the result is also kept for expectations()."
+  param what String "The expectation, such as `entity:crate:within:0,0.4,-1,1,0.6,1`."
+  returns ExpectResult "A malformed expectation is a malformed call."
+}
+```
+
+<sub>`api.ogt` line 12920</sub>
+
+<a id="member-EngineProbe-expectations"></a>
+
+#### `EngineProbe.expectations`
+
+Every expectation evaluated since the last call (scripts' `expect:` steps, programs, expect()), and the counts.
+
+```ts
+EngineProbe.expectations(): ExpectReport
+```
+
+**Returns** `ExpectReport`.
+
+Binding symbol `og_engine_probe_expectations` · publish builds: dropped
+
+```ogt
+fn expectations {
+  doc "Every expectation evaluated since the last call (scripts' `expect:` steps, programs, expect()), and the counts."
+  returns ExpectReport
+}
+```
+
+<sub>`api.ogt` line 12925</sub>
+
+<a id="member-EngineProbe-saveScene"></a>
+
+#### `EngineProbe.saveScene`
+
+Write every scene the world was assembled from back from the world (the boot scene's and each og.world.instantiate made): its entities' and resources' changed field lines and the fields set and patch tuned, keeping every other line, comment and the order; with spawned, the entities the game spawned under the boot scene's marked section. The probe writes the files only with write; otherwise the texts are returned.
+
+```ts
+EngineProbe.saveScene(write?: boolean, spawned?: boolean): SavedScene | null
+```
+
+| Parameter | Type | Optional | Doc |
+|---|---|---|---|
+| `write` | `boolean` | yes | Replace each scene's source file. Default `false`. |
+| `spawned` | `boolean` | yes | Write the entities the game spawned at run time under the boot scene's marked section. Default `false`. |
+
+**Returns** `SavedScene | null`: Null without a scene to write back (the reason is in the log).
+
+Binding symbol `og_engine_probe_save_scene` · publish builds: dropped
+
+```ogt
+fn saveScene {
+  doc "Write every scene the world was assembled from back from the world (the boot scene's and each og.world.instantiate made): its entities' and resources' changed field lines and the fields set and patch tuned, keeping every other line, comment and the order; with spawned, the entities the game spawned under the boot scene's marked section. The probe writes the files only with write; otherwise the texts are returned."
+  param write bool "Replace each scene's source file." {
+    default false
+  }
+  param spawned bool "Write the entities the game spawned at run time under the boot scene's marked section." {
+    default false
+  }
+  returns Option.SavedScene "Null without a scene to write back (the reason is in the log)."
+}
+```
+
+<sub>`api.ogt` line 12929</sub>
 
 ## Types
 
@@ -749,7 +873,7 @@ struct PickResult {
 }
 ```
 
-<sub>`api.ogt` line 10540</sub>
+<sub>`api.ogt` line 12262</sub>
 
 <a id="type-ProbeTunable"></a>
 
@@ -784,7 +908,7 @@ struct ProbeTunable {
 }
 ```
 
-<sub>`api.ogt` line 10547</sub>
+<sub>`api.ogt` line 12269</sub>
 
 <a id="type-ProbeEntityRef"></a>
 
@@ -807,7 +931,7 @@ struct ProbeEntityRef {
 }
 ```
 
-<sub>`api.ogt` line 10564</sub>
+<sub>`api.ogt` line 12286</sub>
 
 <a id="type-ProbeTimings"></a>
 
@@ -820,6 +944,10 @@ The fixed timings head of state().
 | `step` | `number` | `0` | — | `ms` | — | Time the last tick took. |
 | `render` | `number` | `0` | — | `ms` | — | Time the last frame's render took; 0 without a renderer. |
 | `frameMs` | `number` | `0` | — | `ms` | — | step + render. |
+| `systems` | `readonly ProbeTiming[]` | `[]` | — | — | — | The last tick's systems in run order, each with its milliseconds. |
+| `passes` | `readonly ProbeTiming[]` | `[]` | — | — | — | The last rendered frame's render passes in the render graph's order, each with its milliseconds of CPU encoding (empty without a renderer). |
+| `gpuPasses` | `readonly ProbeTiming[]` | `[]` | — | — | — | The render passes of the newest frame the GPU's timestamps were read back for (a frame or two behind `passes`), each with the GPU's milliseconds from the end of the pass before it to its own end; empty where the device has no timestamp queries (RenderCapabilities.gpuTimestamps) or without a renderer. |
+| `triangles` | `number` | `0` | — | — | — | Triangles the last frame's main pass drew (after culling and level of detail); 0 without a renderer. |
 
 ```ogt
 struct ProbeTimings {
@@ -833,10 +961,37 @@ struct ProbeTimings {
   field frameMs f32 "step + render." {
     unit ms
   }
+  field systems List.ProbeTiming "The last tick's systems in run order, each with its milliseconds."
+  field passes List.ProbeTiming "The last rendered frame's render passes in the render graph's order, each with its milliseconds of CPU encoding (empty without a renderer)."
+  field gpuPasses List.ProbeTiming "The render passes of the newest frame the GPU's timestamps were read back for (a frame or two behind `passes`), each with the GPU's milliseconds from the end of the pass before it to its own end; empty where the device has no timestamp queries (RenderCapabilities.gpuTimestamps) or without a renderer."
+  field triangles u32 "Triangles the last frame's main pass drew (after culling and level of detail); 0 without a renderer."
+}
+```
+
+<sub>`api.ogt` line 12294</sub>
+
+<a id="type-ProbeTiming"></a>
+
+### `ProbeTiming` (struct)
+
+One named span of the last tick or frame.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `name` | `string` | `""` | — | — | — | A system's name, or a render pass's (`Main`, `Cascade0`, `Bloom`). |
+| `ms` | `number` | `0` | — | `ms` | — | Its time. |
+
+```ogt
+struct ProbeTiming {
+  doc "One named span of the last tick or frame."
+  field name String "A system's name, or a render pass's (`Main`, `Cascade0`, `Bloom`)."
+  field ms f32 "Its time." {
+    unit ms
+  }
 }
 ```
 
-<sub>`api.ogt` line 10572</sub>
+<sub>`api.ogt` line 12311</sub>
 
 <a id="type-ProbeState"></a>
 
@@ -849,7 +1004,7 @@ The probe's state(): a fixed head, then the game's own facts.
 | `tick` | `number` | `0` | — | — | — | Fixed steps since load. |
 | `paused` | `boolean` | `false` | — | — | — | Whether the clock is held. |
 | `seed` | `number` | `0` | — | — | — | The seed the world was assembled from. |
-| `timings` | `ProbeTimings` | `{ step: 0, render: 0, frameMs: 0 }` | — | — | — | The last tick's timings. |
+| `timings` | `ProbeTimings` | `{ step: 0, render: 0, frameMs: 0, systems: [], passes: [], gpuPasses: [], triangles: 0 }` | — | — | — | The last tick's timings. |
 | `entities` | `readonly ProbeEntityRef[]` | `[]` | — | — | — | The named entities. |
 | `facts` | `unknown` | `null` | — | — | — | What GameDesc.facts returned, or null. |
 
@@ -865,7 +1020,7 @@ struct ProbeState {
 }
 ```
 
-<sub>`api.ogt` line 10585</sub>
+<sub>`api.ogt` line 12319</sub>
 
 <a id="type-AdvanceOperation"></a>
 
@@ -884,7 +1039,7 @@ struct AdvanceOperation {
 }
 ```
 
-<sub>`api.ogt` line 10595</sub>
+<sub>`api.ogt` line 12329</sub>
 
 <a id="type-InputOperation"></a>
 
@@ -903,7 +1058,7 @@ struct InputOperation {
 }
 ```
 
-<sub>`api.ogt` line 10600</sub>
+<sub>`api.ogt` line 12334</sub>
 
 <a id="type-PickOperation"></a>
 
@@ -924,7 +1079,7 @@ struct PickOperation {
 }
 ```
 
-<sub>`api.ogt` line 10605</sub>
+<sub>`api.ogt` line 12339</sub>
 
 <a id="type-EntityOperation"></a>
 
@@ -943,7 +1098,26 @@ struct EntityOperation {
 }
 ```
 
-<sub>`api.ogt` line 10611</sub>
+<sub>`api.ogt` line 12345</sub>
+
+<a id="type-ExpectOperation"></a>
+
+### `ExpectOperation` (struct)
+
+The expect operation's payload.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `what` | `string` | `""` | — | — | — | The expectation, as after `expect:` in a script, such as `state:started==true`. |
+
+```ogt
+struct ExpectOperation {
+  doc "The expect operation's payload."
+  field what String "The expectation, as after `expect:` in a script, such as `state:started==true`."
+}
+```
+
+<sub>`api.ogt` line 12350</sub>
 
 <a id="type-ProbeOperation"></a>
 
@@ -962,6 +1136,8 @@ Tagged by `op`.
 | `op: "read"` | — | Read the state; answers `{ tick, state }`. |
 | `op: "pick"` | [`PickOperation`](#type-PickOperation) | Pick a point; answers its result or null. |
 | `op: "entity"` | [`EntityOperation`](#type-EntityOperation) | Read an entity's parameters; null is a refusal. |
+| `op: "expect"` | [`ExpectOperation`](#type-ExpectOperation) | Evaluate an expectation; answers its ExpectResult, failed or not (a malformed one is a refusal). |
+| `op: "describe"` | — | Describe the frame; answers its Description. |
 
 ```ogt
 union ProbeOperation {
@@ -974,10 +1150,12 @@ union ProbeOperation {
   case read "Read the state; answers `{ tick, state }`."
   case pick PickOperation "Pick a point; answers its result or null."
   case entity EntityOperation "Read an entity's parameters; null is a refusal."
+  case expect ExpectOperation "Evaluate an expectation; answers its ExpectResult, failed or not (a malformed one is a refusal)."
+  case describe "Describe the frame; answers its Description."
 }
 ```
 
-<sub>`api.ogt` line 10616</sub>
+<sub>`api.ogt` line 12355</sub>
 
 <a id="type-ProbeProgramResult"></a>
 
@@ -1000,7 +1178,7 @@ struct ProbeProgramResult {
 }
 ```
 
-<sub>`api.ogt` line 10628</sub>
+<sub>`api.ogt` line 12369</sub>
 
 <a id="type-Hello"></a>
 
@@ -1037,7 +1215,7 @@ struct Hello {
 }
 ```
 
-<sub>`api.ogt` line 10635</sub>
+<sub>`api.ogt` line 12376</sub>
 
 <a id="type-BuildProfile"></a>
 
@@ -1062,7 +1240,7 @@ enum BuildProfile {
 }
 ```
 
-<sub>`api.ogt` line 10650</sub>
+<sub>`api.ogt` line 12391</sub>
 
 <a id="type-Capture"></a>
 
@@ -1087,7 +1265,7 @@ struct Capture {
 }
 ```
 
-<sub>`api.ogt` line 10657</sub>
+<sub>`api.ogt` line 12398</sub>
 
 <a id="type-Heard"></a>
 
@@ -1118,7 +1296,7 @@ struct Heard {
 }
 ```
 
-<sub>`api.ogt` line 10665</sub>
+<sub>`api.ogt` line 12406</sub>
 
 <a id="type-ProbeHeap"></a>
 
@@ -1145,7 +1323,7 @@ struct ProbeHeap {
 }
 ```
 
-<sub>`api.ogt` line 10677</sub>
+<sub>`api.ogt` line 12418</sub>
 
 <a id="type-ProbeWorldMemory"></a>
 
@@ -1164,7 +1342,7 @@ struct ProbeWorldMemory {
 }
 ```
 
-<sub>`api.ogt` line 10688</sub>
+<sub>`api.ogt` line 12429</sub>
 
 <a id="type-ProbeStreamMemory"></a>
 
@@ -1193,7 +1371,7 @@ struct ProbeStreamMemory {
 }
 ```
 
-<sub>`api.ogt` line 10693</sub>
+<sub>`api.ogt` line 12434</sub>
 
 <a id="type-ProbeMemory"></a>
 
@@ -1230,7 +1408,7 @@ struct ProbeMemory {
 }
 ```
 
-<sub>`api.ogt` line 10706</sub>
+<sub>`api.ogt` line 12447</sub>
 
 <a id="type-SweepDesc"></a>
 
@@ -1262,7 +1440,7 @@ struct SweepDesc {
 }
 ```
 
-<sub>`api.ogt` line 10723</sub>
+<sub>`api.ogt` line 12464</sub>
 
 <a id="type-SweepFrame"></a>
 
@@ -1285,7 +1463,7 @@ struct SweepFrame {
 }
 ```
 
-<sub>`api.ogt` line 10734</sub>
+<sub>`api.ogt` line 12475</sub>
 
 <a id="type-SweepResult"></a>
 
@@ -1304,7 +1482,7 @@ struct SweepResult {
 }
 ```
 
-<sub>`api.ogt` line 10741</sub>
+<sub>`api.ogt` line 12482</sub>
 
 <a id="type-ReloadReport"></a>
 
@@ -1333,7 +1511,7 @@ struct ReloadReport {
 }
 ```
 
-<sub>`api.ogt` line 10746</sub>
+<sub>`api.ogt` line 12487</sub>
 
 <a id="type-SnapshotInfo"></a>
 
@@ -1360,7 +1538,7 @@ struct SnapshotInfo {
 }
 ```
 
-<sub>`api.ogt` line 10757</sub>
+<sub>`api.ogt` line 12498</sub>
 
 <a id="type-DumpKind"></a>
 
@@ -1375,6 +1553,7 @@ A string: one of the variants below. The zero value is `"world"`.
 | `"world"` | Archetype tables, systems and their matched counts. |
 | `"entity"` | One entity's components and transform. |
 | `"ui"` | The UI tree with bounds. |
+| `"desync"` | The first desync of a lockstep session (og.net): its tick, both hashes and the component-level diff of the two peers' snapshots. |
 
 ```ogt
 enum DumpKind {
@@ -1382,10 +1561,11 @@ enum DumpKind {
   variant world "Archetype tables, systems and their matched counts."
   variant entity "One entity's components and transform."
   variant ui "The UI tree with bounds."
+  variant desync "The first desync of a lockstep session (og.net): its tick, both hashes and the component-level diff of the two peers' snapshots."
 }
 ```
 
-<sub>`api.ogt` line 10767</sub>
+<sub>`api.ogt` line 12508</sub>
 
 <a id="type-DumpDesc"></a>
 
@@ -1409,7 +1589,7 @@ struct DumpDesc {
 }
 ```
 
-<sub>`api.ogt` line 10774</sub>
+<sub>`api.ogt` line 12516</sub>
 
 <a id="type-ArchetypeDump"></a>
 
@@ -1430,7 +1610,7 @@ struct ArchetypeDump {
 }
 ```
 
-<sub>`api.ogt` line 10781</sub>
+<sub>`api.ogt` line 12523</sub>
 
 <a id="type-SystemDump"></a>
 
@@ -1459,7 +1639,7 @@ struct SystemDump {
 }
 ```
 
-<sub>`api.ogt` line 10787</sub>
+<sub>`api.ogt` line 12529</sub>
 
 <a id="type-WorldDump"></a>
 
@@ -1488,7 +1668,7 @@ struct WorldDump {
 }
 ```
 
-<sub>`api.ogt` line 10798</sub>
+<sub>`api.ogt` line 12540</sub>
 
 <a id="type-EntityDump"></a>
 
@@ -1511,7 +1691,7 @@ struct EntityDump {
 }
 ```
 
-<sub>`api.ogt` line 10808</sub>
+<sub>`api.ogt` line 12550</sub>
 
 <a id="type-UiElement"></a>
 
@@ -1531,6 +1711,7 @@ One UI element with its bounds.
 | `name` | `string` | `""` | — | — | — | Its accessible name: its text, a name the widget gives it (an icon's name, a dialog's title, Decrease and Increase for a stepper's buttons), a control's own text gathered from its children, or else its id. |
 | `value` | `string` | `""` | — | — | — | Its value as text: a slider's or stepper's number, a progress's or meter's amount, a field's text, a select's choice; empty for none. |
 | `states` | `readonly string[]` | `[]` | — | — | — | Its states: disabled, focused, focusable (keys and pads reach it now, in this order), checked, selected, expanded, pressed, busy. |
+| `opaque` | `boolean` | `false` | — | — | — | It draws an opaque background over its whole box (its fill's alpha times its opacity is 1), hiding the scene under it. |
 | `x` | `number` | `0` | — | `cssPx` | — | Left edge. |
 | `y` | `number` | `0` | — | `cssPx` | — | Top edge. |
 | `width` | `number` | `0` | — | `cssPx` | — | Width. |
@@ -1549,6 +1730,7 @@ struct UiElement {
   field name String "Its accessible name: its text, a name the widget gives it (an icon's name, a dialog's title, Decrease and Increase for a stepper's buttons), a control's own text gathered from its children, or else its id."
   field value String "Its value as text: a slider's or stepper's number, a progress's or meter's amount, a field's text, a select's choice; empty for none."
   field states List.String "Its states: disabled, focused, focusable (keys and pads reach it now, in this order), checked, selected, expanded, pressed, busy."
+  field opaque bool "It draws an opaque background over its whole box (its fill's alpha times its opacity is 1), hiding the scene under it."
   field x f32 "Left edge." {
     unit cssPx
   }
@@ -1564,7 +1746,7 @@ struct UiElement {
 }
 ```
 
-<sub>`api.ogt` line 10815</sub>
+<sub>`api.ogt` line 12557</sub>
 
 <a id="type-UiSurface"></a>
 
@@ -1593,7 +1775,7 @@ struct UiSurface {
 }
 ```
 
-<sub>`api.ogt` line 10841</sub>
+<sub>`api.ogt` line 12584</sub>
 
 <a id="type-UiDump"></a>
 
@@ -1616,7 +1798,34 @@ struct UiDump {
 }
 ```
 
-<sub>`api.ogt` line 10854</sub>
+<sub>`api.ogt` line 12597</sub>
+
+<a id="type-DesyncDump"></a>
+
+### `DesyncDump` (struct)
+
+The first desync of this peer's lockstep session (og.net), as `dump_desync` writes it.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `desync` | `boolean` | `false` | — | — | — | Whether a desync happened; false lists the ticks compared with each peer so far. |
+| `tick` | `number \| null` | `null` | — | — | — | The first divergent tick: og.Time.tick of the two worlds that differ. |
+| `local` | `unknown` | `null` | — | — | — | This peer: `{ peer, player, hash }`. |
+| `remote` | `unknown` | `null` | — | — | — | The other peer: `{ peer, player, hash }`. |
+| `diff` | `unknown` | `null` | — | — | — | What differs: `{ components: [{ entity, component, fields: [{ field, local, remote }] }], entities: { onlyLocal, onlyRemote }, resources, events, blocks, allocator }`, in the local world's entity order (the first entry is the first difference in storage order); `{ pending }` until the other peer's snapshot arrived. |
+
+```ogt
+struct DesyncDump {
+  doc "The first desync of this peer's lockstep session (og.net), as `dump_desync` writes it."
+  field desync bool "Whether a desync happened; false lists the ticks compared with each peer so far."
+  field tick Option.u32 "The first divergent tick: og.Time.tick of the two worlds that differ."
+  field local Json "This peer: `{ peer, player, hash }`."
+  field remote Json "The other peer: `{ peer, player, hash }`."
+  field diff Json "What differs: `{ components: [{ entity, component, fields: [{ field, local, remote }] }], entities: { onlyLocal, onlyRemote }, resources, events, blocks, allocator }`, in the local world's entity order (the first entry is the first difference in storage order); `{ pending }` until the other peer's snapshot arrived."
+}
+```
+
+<sub>`api.ogt` line 12604</sub>
 
 <a id="type-DumpResult"></a>
 
@@ -1631,6 +1840,7 @@ Tagged by `kind`.
 | `kind: "world"` | [`WorldDump`](#type-WorldDump) | The world dump. |
 | `kind: "entity"` | [`EntityDump`](#type-EntityDump) | An entity dump. |
 | `kind: "ui"` | [`UiDump`](#type-UiDump) | The UI dump. |
+| `kind: "desync"` | [`DesyncDump`](#type-DesyncDump) | The desync dump. |
 
 ```ogt
 union DumpResult {
@@ -1639,10 +1849,414 @@ union DumpResult {
   case world WorldDump "The world dump."
   case entity EntityDump "An entity dump."
   case ui UiDump "The UI dump."
+  case desync DesyncDump "The desync dump."
+}
+```
+
+<sub>`api.ogt` line 12613</sub>
+
+<a id="type-ScreenBox"></a>
+
+### `ScreenBox` (struct)
+
+A box on the play surface.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `x` | `number` | `0` | — | `cssPx` | — | Left edge. |
+| `y` | `number` | `0` | — | `cssPx` | — | Top edge. |
+| `width` | `number` | `0` | — | `cssPx` | — | Width. |
+| `height` | `number` | `0` | — | `cssPx` | — | Height. |
+
+```ogt
+struct ScreenBox {
+  doc "A box on the play surface."
+  field x f32 "Left edge." {
+    unit cssPx
+  }
+  field y f32 "Top edge." {
+    unit cssPx
+  }
+  field width f32 "Width." {
+    unit cssPx
+  }
+  field height f32 "Height." {
+    unit cssPx
+  }
+}
+```
+
+<sub>`api.ogt` line 12622</sub>
+
+<a id="type-ScreenPoint"></a>
+
+### `ScreenPoint` (struct)
+
+A point on the play surface.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `x` | `number` | `0` | — | `cssPx` | — | Horizontal position. |
+| `y` | `number` | `0` | — | `cssPx` | — | Vertical position. |
+
+```ogt
+struct ScreenPoint {
+  doc "A point on the play surface."
+  field x f32 "Horizontal position." {
+    unit cssPx
+  }
+  field y f32 "Vertical position." {
+    unit cssPx
+  }
+}
+```
+
+<sub>`api.ogt` line 12638</sub>
+
+<a id="type-DescribedEntity"></a>
+
+### `DescribedEntity` (struct)
+
+One entity the frame shows, from the entity-id pass (a CPU rasterisation of the frame's meshes, skinned meshes and world sprites at a quarter of its pixels).
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `id` | `string` | `""` | — | — | — | Its probe id. |
+| `name` | `string \| null` | `null` | — | — | — | Its name. |
+| `order` | `number` | `0` | — | — | — | Its depth order: 0 is the nearest. |
+| `archetype` | `readonly string[]` | `[]` | — | — | — | Its components, by name. |
+| `labels` | `readonly string[]` | `[]` | — | — | — | What draws it: `model` with its asset path, `mesh`, `skinned`, `sprite`. |
+| `box` | `ScreenBox` | `{ x: 0, y: 0, width: 0, height: 0 }` | — | — | — | The box of its visible pixels. |
+| `drawn` | `ScreenBox` | `{ x: 0, y: 0, width: 0, height: 0 }` | — | — | — | The box of what it covers with nothing in front of it. |
+| `point` | `ScreenPoint` | `{ x: 0, y: 0 }` | — | — | — | A visible point nearest the box's centre: pick answers this entity there. |
+| `depth` | `number` | `0` | — | `m` | — | From the camera to its nearest visible point, along the view. |
+| `coverage` | `number` | `0` | — | `ratio` | — | Its visible share of the surface. |
+| `occlusion` | `number` | `0` | — | `ratio` | — | The share of what it covers alone that something else hides: another object in front, or a UI element drawn opaque over it (DescribedUi.opaque); on a secondary camera's image, objects only. |
+| `views` | `readonly string[]` | `[]` | — | — | — | The probe ids of the og.CameraView and og.Mirror entities whose image also shows it, from their own id passes on their own layers; empty when only the main camera does (under DescribedView.entities it is empty). |
+
+```ogt
+struct DescribedEntity {
+  doc "One entity the frame shows, from the entity-id pass (a CPU rasterisation of the frame's meshes, skinned meshes and world sprites at a quarter of its pixels)."
+  field id String "Its probe id."
+  field name Option.String "Its name."
+  field order u32 "Its depth order: 0 is the nearest."
+  field archetype List.String "Its components, by name."
+  field labels List.String "What draws it: `model` with its asset path, `mesh`, `skinned`, `sprite`."
+  field box ScreenBox "The box of its visible pixels."
+  field drawn ScreenBox "The box of what it covers with nothing in front of it."
+  field point ScreenPoint "A visible point nearest the box's centre: pick answers this entity there."
+  field depth f32 "From the camera to its nearest visible point, along the view." {
+    unit m
+  }
+  field coverage f32 "Its visible share of the surface." {
+    unit ratio
+  }
+  field occlusion f32 "The share of what it covers alone that something else hides: another object in front, or a UI element drawn opaque over it (DescribedUi.opaque); on a secondary camera's image, objects only." {
+    unit ratio
+  }
+  field views List.String "The probe ids of the og.CameraView and og.Mirror entities whose image also shows it, from their own id passes on their own layers; empty when only the main camera does (under DescribedView.entities it is empty)."
+}
+```
+
+<sub>`api.ogt` line 12648</sub>
+
+<a id="type-DescribedView"></a>
+
+### `DescribedView` (struct)
+
+A secondary camera (og.CameraView, og.Mirror) and what its image shows: its own entity-id pass, from its eye and on its layers, at a quarter of its image's pixels, whatever its `every`. An entity only its layers admit (a layer the main camera leaves out) is listed here and not in Description.entities.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `id` | `string` | `""` | — | — | — | The view entity's probe id. |
+| `name` | `string \| null` | `null` | — | — | — | Its name. |
+| `kind` | `string` | `""` | — | — | — | `camera` (og.CameraView) or `mirror` (og.Mirror). |
+| `size` | `PassSize` | `{ width: 0, height: 0 }` | — | — | — | The pixels its image covers: its render target's, or its viewport's rect of the frame. |
+| `entities` | `readonly DescribedEntity[]` | `[]` | — | — | — | What it shows, nearest its eye first, boxes and points in its image's pixels. |
+
+```ogt
+struct DescribedView {
+  doc "A secondary camera (og.CameraView, og.Mirror) and what its image shows: its own entity-id pass, from its eye and on its layers, at a quarter of its image's pixels, whatever its `every`. An entity only its layers admit (a layer the main camera leaves out) is listed here and not in Description.entities."
+  field id String "The view entity's probe id."
+  field name Option.String "Its name."
+  field kind String "`camera` (og.CameraView) or `mirror` (og.Mirror)."
+  field size PassSize "The pixels its image covers: its render target's, or its viewport's rect of the frame."
+  field entities List.DescribedEntity "What it shows, nearest its eye first, boxes and points in its image's pixels."
+}
+```
+
+<sub>`api.ogt` line 12670</sub>
+
+<a id="type-DescribedUi"></a>
+
+### `DescribedUi` (struct)
+
+One UI element as describe lists it (the tree dump_ui writes).
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `id` | `string` | `""` | — | — | — | Its id. |
+| `parent` | `string` | `""` | — | — | — | Its parent's id. |
+| `kind` | `string` | `""` | — | — | — | What made it. |
+| `role` | `string` | `""` | — | — | — | Its accessibility role. |
+| `text` | `string` | `""` | — | — | — | The text it shows. |
+| `value` | `string` | `""` | — | — | — | Its value as text. |
+| `states` | `readonly string[]` | `[]` | — | — | — | Its states. |
+| `opaque` | `boolean` | `false` | — | — | — | It draws an opaque background over its whole box: the entities under it count it in their occlusion. |
+| `box` | `ScreenBox` | `{ x: 0, y: 0, width: 0, height: 0 }` | — | — | — | Its rect. |
+
+```ogt
+struct DescribedUi {
+  doc "One UI element as describe lists it (the tree dump_ui writes)."
+  field id String "Its id."
+  field parent String "Its parent's id."
+  field kind String "What made it."
+  field role String "Its accessibility role."
+  field text String "The text it shows."
+  field value String "Its value as text."
+  field states List.String "Its states."
+  field opaque bool "It draws an opaque background over its whole box: the entities under it count it in their occlusion."
+  field box ScreenBox "Its rect."
+}
+```
+
+<sub>`api.ogt` line 12679</sub>
+
+<a id="type-DescribedCamera"></a>
+
+### `DescribedCamera` (struct)
+
+The camera as drawn, with its shake.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `position` | `[number, number, number]` | `[0, 0, 0]` | — | — | — | Where it is. |
+| `target` | `[number, number, number]` | `[0, 0, 0]` | — | — | — | What it looks at. |
+| `up` | `[number, number, number]` | `[0, 0, 0]` | — | — | — | Its up. |
+| `projection` | `string` | `""` | — | — | — | `perspective` or `orthographic`. |
+| `fov` | `number \| null` | `null` | — | `deg` | — | The vertical field of view (perspective). |
+| `height` | `number \| null` | `null` | — | `m` | — | The height in view (orthographic). |
+| `near` | `number` | `0` | — | `m` | — | The near plane. |
+| `far` | `number` | `0` | — | `m` | — | The far plane. |
+
+```ogt
+struct DescribedCamera {
+  doc "The camera as drawn, with its shake."
+  field position Array.f32.3 "Where it is."
+  field target Array.f32.3 "What it looks at."
+  field up Array.f32.3 "Its up."
+  field projection String "`perspective` or `orthographic`."
+  field fov Option.f32 "The vertical field of view (perspective)." {
+    unit deg
+  }
+  field height Option.f32 "The height in view (orthographic)." {
+    unit m
+  }
+  field near f32 "The near plane." {
+    unit m
+  }
+  field far f32 "The far plane." {
+    unit m
+  }
+}
+```
+
+<sub>`api.ogt` line 12692</sub>
+
+<a id="type-PassSize"></a>
+
+### `PassSize` (struct)
+
+The entity-id pass's size.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `width` | `number` | `0` | — | — | — | Width in pixels. |
+| `height` | `number` | `0` | — | — | — | Height in pixels. |
+
+```ogt
+struct PassSize {
+  doc "The entity-id pass's size."
+  field width u32 "Width in pixels."
+  field height u32 "Height in pixels."
+}
+```
+
+<sub>`api.ogt` line 12712</sub>
+
+<a id="type-Description"></a>
+
+### `Description` (struct)
+
+The frame as data: deterministic, the same JSON on every host and backend for the same world.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `tick` | `number` | `0` | — | — | — | The tick. |
+| `surface` | `UiSurface \| null` | `null` | — | — | — | The play surface. |
+| `pass` | `PassSize \| null` | `null` | — | — | — | The entity-id pass; null without a scene. |
+| `camera` | `DescribedCamera \| null` | `null` | — | — | — | The camera; null without a scene. |
+| `entities` | `readonly DescribedEntity[]` | `[]` | — | — | — | The entities the main camera shows, nearest first (each names the views that also show it). |
+| `views` | `readonly DescribedView[]` | `[]` | — | — | — | The secondary cameras the frame draws, in its view order, each with what it shows. |
+| `ui` | `readonly DescribedUi[]` | `[]` | — | — | — | The UI elements in draw order. |
+
+```ogt
+struct Description {
+  doc "The frame as data: deterministic, the same JSON on every host and backend for the same world."
+  field tick u32 "The tick."
+  field surface Option.UiSurface "The play surface."
+  field pass Option.PassSize "The entity-id pass; null without a scene."
+  field camera Option.DescribedCamera "The camera; null without a scene."
+  field entities List.DescribedEntity "The entities the main camera shows, nearest first (each names the views that also show it)."
+  field views List.DescribedView "The secondary cameras the frame draws, in its view order, each with what it shows."
+  field ui List.DescribedUi "The UI elements in draw order."
+}
+```
+
+<sub>`api.ogt` line 12718</sub>
+
+<a id="type-ExpectStatus"></a>
+
+### `ExpectStatus` (enum)
+
+How an expectation came out.
+
+A string: one of the variants below. The zero value is `"pass"`.
+
+| Variant | Doc |
+|---|---|
+| `"pass"` | It held. |
+| `"fail"` | It did not: the result carries the tick and the observed value. |
+| `"unchecked"` | It reads a frame and the host has no renderer. |
+
+```ogt
+enum ExpectStatus {
+  doc "How an expectation came out."
+  variant pass "It held."
+  variant fail "It did not: the result carries the tick and the observed value."
+  variant unchecked "It reads a frame and the host has no renderer."
+}
+```
+
+<sub>`api.ogt` line 12729</sub>
+
+<a id="type-ExpectResult"></a>
+
+### `ExpectResult` (struct)
+
+One evaluated expectation.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `tick` | `number` | `0` | — | — | — | The tick it was evaluated at. |
+| `at` | `number \| null` | `null` | — | `s` | — | The script step's time, when a script ran it. |
+| `expect` | `string` | `""` | — | — | — | As written after `expect:`. |
+| `kind` | `string` | `""` | — | — | — | `entity`, `event`, `ui`, `region`, `frame` or `state`. |
+| `status` | `ExpectStatus` | `"pass"` | — | — | — | The outcome. |
+| `expected` | `unknown` | `null` | — | — | — | What was expected. |
+| `observed` | `unknown` | `null` | — | — | — | What was there. |
+| `reason` | `string` | `""` | — | — | — | Why it failed or was unchecked; empty on a pass. |
+
+```ogt
+struct ExpectResult {
+  doc "One evaluated expectation."
+  field tick u32 "The tick it was evaluated at."
+  field at Option.f32 "The script step's time, when a script ran it." {
+    unit s
+  }
+  field expect String "As written after `expect:`."
+  field kind String "`entity`, `event`, `ui`, `region`, `frame` or `state`."
+  field status ExpectStatus "The outcome."
+  field expected Json "What was expected."
+  field observed Json "What was there."
+  field reason String "Why it failed or was unchecked; empty on a pass."
+}
+```
+
+<sub>`api.ogt` line 12736</sub>
+
+<a id="type-ExpectReport"></a>
+
+### `ExpectReport` (struct)
+
+The expectations evaluated since the last call.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `passed` | `number` | `0` | — | — | — | Those that held. |
+| `failed` | `number` | `0` | — | — | — | Those that did not. |
+| `unchecked` | `number` | `0` | — | — | — | Those that needed a renderer. |
+| `results` | `readonly ExpectResult[]` | `[]` | — | — | — | Each, in order. |
+
+```ogt
+struct ExpectReport {
+  doc "The expectations evaluated since the last call."
+  field passed u32 "Those that held."
+  field failed u32 "Those that did not."
+  field unchecked u32 "Those that needed a renderer."
+  field results List.ExpectResult "Each, in order."
+}
+```
+
+<sub>`api.ogt` line 12750</sub>
+
+<a id="type-SavedScene"></a>
+
+### `SavedScene` (struct)
+
+The scenes written back from the world: the head is the boot scene's (or the first instantiated one's), `scenes` lists every one.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `tick` | `number` | `0` | — | — | — | The tick of the world it was written from. |
+| `source` | `string` | `""` | — | — | — | The first scene's source, project-relative. |
+| `written` | `string` | `""` | — | — | — | Where it was written; empty when only returned. |
+| `lines` | `readonly number[]` | `[]` | — | — | — | The 1-based lines of the first scene's new text that changed or were added. |
+| `skipped` | `readonly string[]` | `[]` | — | — | — | Tuned fields that were not written, each with its reason: an entity no scene made (without `spawned`), a resource no scene sets where no boot scene takes it. |
+| `text` | `string` | `""` | — | — | — | The first scene's new text. |
+| `spawned` | `number` | `0` | — | — | — | Entities written under the boot scene's spawned section (0 without `spawned`). |
+| `scenes` | `readonly SavedSceneFile[]` | `[]` | — | — | — | Every scene written back: the boot scene's first, then each og.world.instantiate made, once each. |
+
+```ogt
+struct SavedScene {
+  doc "The scenes written back from the world: the head is the boot scene's (or the first instantiated one's), `scenes` lists every one."
+  field tick u32 "The tick of the world it was written from."
+  field source String "The first scene's source, project-relative."
+  field written String "Where it was written; empty when only returned."
+  field lines List.u32 "The 1-based lines of the first scene's new text that changed or were added."
+  field skipped List.String "Tuned fields that were not written, each with its reason: an entity no scene made (without `spawned`), a resource no scene sets where no boot scene takes it."
+  field text String "The first scene's new text."
+  field spawned u32 "Entities written under the boot scene's spawned section (0 without `spawned`)."
+  field scenes List.SavedSceneFile "Every scene written back: the boot scene's first, then each og.world.instantiate made, once each."
+}
+```
+
+<sub>`api.ogt` line 12758</sub>
+
+<a id="type-SavedSceneFile"></a>
+
+### `SavedSceneFile` (struct)
+
+One scene file written back.
+
+| Field | Type | Default | Range | Unit | Notes | Doc |
+|---|---|---|---|---|---|---|
+| `source` | `string` | `""` | — | — | — | Its source, project-relative. |
+| `written` | `string` | `""` | — | — | — | Where it was written; empty when only returned. |
+| `lines` | `readonly number[]` | `[]` | — | — | — | The 1-based lines of its new text that changed or were added. |
+| `text` | `string` | `""` | — | — | — | Its new text. |
+
+```ogt
+struct SavedSceneFile {
+  doc "One scene file written back."
+  field source String "Its source, project-relative."
+  field written String "Where it was written; empty when only returned."
+  field lines List.u32 "The 1-based lines of its new text that changed or were added."
+  field text String "Its new text."
 }
 ```
 
-<sub>`api.ogt` line 10861</sub>
+<sub>`api.ogt` line 12770</sub>
 
 ## Constants
 
@@ -1659,34 +2273,34 @@ union DumpResult {
 const PROBE_GLOBAL String "__runtime_probe__" "The global the page publishes the probe on."
 ```
 
-<sub>`api.ogt` line 10533</sub>
+<sub>`api.ogt` line 12255</sub>
 
 ```ogt
 const PROBE_VERSION u32 5 "The RuntimeProbe contract revision both sides speak."
 ```
 
-<sub>`api.ogt` line 10534</sub>
+<sub>`api.ogt` line 12256</sub>
 
 ```ogt
 const PROBE_WIRE_VERSION u32 1 "The wire revision hello reports."
 ```
 
-<sub>`api.ogt` line 10535</sub>
+<sub>`api.ogt` line 12257</sub>
 
 ```ogt
 const REPLAY_SEED_PARAM String "replay-seed" "The page query parameter that starts a deterministic replay from a uint32 seed."
 ```
 
-<sub>`api.ogt` line 10536</sub>
+<sub>`api.ogt` line 12258</sub>
 
 ```ogt
 const PLAYTEST_MAX_TICKS u32 3600 "The longest playtest one request may advance, in fixed steps."
 ```
 
-<sub>`api.ogt` line 10537</sub>
+<sub>`api.ogt` line 12259</sub>
 
 ```ogt
 const PROBE_PROGRAM_MAX_OPERATIONS u32 256 "The most operations one probe program may carry."
 ```
 
-<sub>`api.ogt` line 10538</sub>
+<sub>`api.ogt` line 12260</sub>