@vgai/engine 0.5.22 → 0.5.24

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.22",
+  "version": "0.5.24",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
   "keywords": [
     "game-engine",

package/schemas/engine-capabilities.json

@@ -2,7 +2,7 @@
   "$comment": "Curated by human/agent review, NOT auto-generated (unlike engine-api.json beside it). Every claim was verified against code — see each entry's `evidence`. Staleness is machine-checked at two granularities: `schemaDirHash` (sha256 over packages/engine/src/asset-formats/) and per-entry `evidenceHashes` (sha256 of each cited evidence FILE — catches drift in files outside the schema dir, which is where most entries' evidence lives; T5.5/§7.2).",
   "_readme": "Read this before authoring scene JSON or engine code, to avoid the negatives below. Refresh flow after a schema-dir OR evidence-file change: `npx tsx scripts/capabilities-hash.ts --check` (fails naming the stale entry) -> re-review affected entries against current code -> `--write` to record fresh hashes. The pre-commit hook runs --check automatically. Each entry's `evidenceHashes` maps the repo-relative file path parsed off the front of each `evidence[]` citation (before any `:line-range` suffix) to a sha256 of that file's current content.",
   "schemaDirPath": "packages/engine/src/asset-formats/",
-  "schemaDirHash": "4b984af5ddc2d4e756db14576a3a267f2d25e0b26490bfb953e614edc635625e",
+  "schemaDirHash": "cc141166e16e49380581a0a80f014057b3cf31030df741ce41480a1e8dc8d3f6",
   "reviewedAt": "2026-07-01",
   "entries": [
     {
@@ -11,11 +11,11 @@
       "status": "unsupported",
       "claim": "No Continuous Collision Detection (CCD). Fast/small dynamic bodies can tunnel through thin colliders in one step.",
       "evidence": [
-        "packages/engine/src/adapter/setup-three-root-adapter.ts (the Rapier home: world init + step; no ccd flag is ever set)"
+        "packages/engine/src/world3d-react/rapier-physics-bridge.tsx (the engine's one physics-facing module: observation/debug bridge only — it constructs no world, no bodies, and sets no ccd flag)"
       ],
-      "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches. The engine constructs no rigid bodies itself — games build their own descs via ctx.RAPIER — and nothing engine-side ever enables ccd. Workaround: keep dynamic-body per-step travel small relative to the thinnest collider, or add intermediate colliders; a game may also call setCcdEnabled on its own bodies directly.",
+      "notes": "Grepped packages/engine/src for ccd/CCD/setCcdEnabled: zero matches. The engine constructs no Rapier world or rigid bodies at all — physics lives in the game's own tree via @react-three/rapier (<Physics>/<RigidBody>), so CCD is a game choice: @react-three/rapier's `ccd` prop (or setCcdEnabled on a body ref) enables it per body with no engine involvement.",
       "evidenceHashes": {
-        "packages/engine/src/adapter/setup-three-root-adapter.ts": "14cef0975f38ecceb25b607ef62232c1002bdd172a3456571f50aa9e39263c0c"
+        "packages/engine/src/world3d-react/rapier-physics-bridge.tsx": "03e8b28f7c60884a6fc9f00f488e6e157bc34287670c6cf723ee5e28e7924ce7"
       }
     },
     {
@@ -35,15 +35,17 @@
       "id": "input-value-model",
       "area": "input",
       "status": "supported-with-caveats",
-      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked (requestPointerLock / exitPointerLock) and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Device-poll getters (isDeviceKeyPressed / isDeviceMouseButtonPressed / getDeviceMouseDelta / getDeviceMousePosition / hasDeviceGamepad / isDeviceGamepadButtonPressed / getDeviceGamepadAxis) read the same keysDown/mouseButtons/gamepads stores without inventing implicit actions, and return inert at READ time when inputActive is false. getDeviceGamepadAxis is deliberately RAW — no deadzone: the engine's own stick deadzone is on the action path (gamepad_axis / gamepad_axis_pair, where a game declares and can override it), and a device-door caller that wants a stick applies its own engine's processor (unity-compat reproduces Unity's StickDeadzone at 0.125/0.925). Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
+      "claim": "F1 (spec §12) added a typed action-value model (digital/scalar/vector2/pointerDelta/pointerPosition, default digital) with real deadzone/combine rules and a valueType-mismatch throw. F2 ('Complete Device Backends') un-rejects mouse_move/gamepad_axis_pair, giving both real readers (mouse_move -> pointerDelta/vector2 off the real mouse-delta accumulator; gamepad_axis_pair -> vector2 off a coupled xAxis/yAxis stick, deadzone-rescaled like gamepad_axis), and adds touch_button/touch_stick (digital/vector2) via setTouchButton/setTouchStick. Real window focus (blur/focus) and pointer-lock state are tracked (requestPointerLock / exitPointerLock) and flush held REAL-device input on loss (#144: virtual/scheduled machine input gates on enabled only and survives blur); gamepad device identity (id/mapping) is exposed via getGamepadInfo/ActionValueSource.gamepadId. F4 adds getLastActiveDevice() + an optional getPrompt device param. Device-poll getters (isDeviceKeyPressed / isDeviceMouseButtonPressed / getDeviceMouseDelta / getDeviceMousePosition / hasDeviceGamepad / isDeviceGamepadButtonPressed / getDeviceGamepadAxis) read the same keysDown/mouseButtons/gamepads stores without inventing implicit actions, and return inert at READ time when inputActive is false. getDeviceGamepadAxis is deliberately RAW — no deadzone: the engine's own stick deadzone is on the action path (gamepad_axis / gamepad_axis_pair, where a game declares and can override it), and a device-door caller that wants a stick applies its own engine's processor (unity-compat reproduces Unity's StickDeadzone at 0.125/0.925). The DOM edge those touch setters were written for now ships beside the manager as `input/host-pointer.ts` (`createHostPointer`): the host pointer stream resolved against a render surface, mapped into the game's own design space, with DENSE finger indices and a bounded queue, gated on the manager's own `isInputActive()` (published for exactly that, so a caller never recomposes `isEnabled() && isFocused()` into a looser gate). Caveat on that half: it reports fingers and does not press anything — the control layer (which rect owns which finger, how a knob becomes a stick vector) is the UI's, and no first-party game ships one. Caveat: pointerPosition still has no real-device backend (test_pointer_position injection only); scalar isn't fed by mouse_move (no axis-select field).",
       "evidence": [
         "packages/engine/src/input/input-types.ts:2-40 (InputBinding union incl. mouse_move/gamepad_axis_pair/touch_button/touch_stick/test_*)",
-        "packages/engine/src/input/input-manager.ts (digital/gating/typed getters/device-poll/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt/requestPointerLock/exitPointerLock)"
+        "packages/engine/src/input/input-manager.ts (digital/gating/typed getters/device-poll/inject*/setTouch*/getGamepadInfo/F4 getLastActiveDevice+getPrompt/requestPointerLock/exitPointerLock)",
+        "packages/engine/src/input/host-pointer.ts (createHostPointer: surface/design-space mapping, dense finger indices, isInputActive gate)"
       ],
       "notes": "gamepad disconnect/reconnect needs no special-cased code: poll() re-reads navigator.getGamepads() and every read skips a null slot, so a disconnected gamepad's actions go neutral with a correct isJustReleased edge for free — see input-device-backends-f2.test.ts.",
       "evidenceHashes": {
-        "packages/engine/src/input/input-types.ts": "62d9005609a72b55a8214c869d1b27825b1a17b9389f3f3f5d0b04725331b382",
-        "packages/engine/src/input/input-manager.ts": "928a1cde1c7245cfd8afc47794ddf28db8d1368bf7f88e602bb645f79f92ba61"
+        "packages/engine/src/input/input-types.ts": "b21ab448fc16d4881c900c57076ca1269241e1b23f8746fb8daa09c628f00f2b",
+        "packages/engine/src/input/input-manager.ts": "3cc14b5d3c5097bddfefbf1d620fc1ba8b0fb1d106191d9c640d94723330e888",
+        "packages/engine/src/input/host-pointer.ts": "aa012e3ddbcc236240e394614fb9e470e9ea18952faa848ffc1fa6597a2bdda9"
       }
     },
     {
@@ -57,8 +59,8 @@
       ],
       "notes": "This is a compatibility integration, not the canonical animation model: project-owned native controllers may drive AnimationMixer directly. When XState is deliberately used, parallel regions use distinct layer names; the binding filters native clip tracks, uses AnimationUtils.makeClipAdditive, can register with ctx.systems, and publishes format-neutral native runtime inspection until disposal.",
       "evidenceHashes": {
-        "packages/engine/src/animation/xstate-animation-meta.ts": "80376ac74819803616c4b396244a971cb9a6b2859c33409d032363bfeb3db44f",
-        "packages/engine/src/animation/xstate-animation-binding.ts": "8ec400c5abe1550a72adca3dfe30e57c42239fdd1eb986b8e05ec973ea3f3d7b"
+        "packages/engine/src/animation/xstate-animation-meta.ts": "d976f58b0bbd8b8159209083075c8860e02a59dd2475e55d9551794b06334035",
+        "packages/engine/src/animation/xstate-animation-binding.ts": "984db5596e51a2ea4e20e419f94fbb3af47c1abbadfaf80431bcd2ba4577032c"
       }
     },
     {
@@ -73,7 +75,7 @@
       "notes": "Limits: ARCHITECTURE-CORE.md. Any editor capability a mount does not reach stands warned per capability until it works.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "257a362030a10f4d72a3280815069fbd83f436e1619391635b6f8df2ddd6c339",
-        "packages/engine/src/manifest/schema.ts": "ce385bc9181b82f9d5044da6a41a025a5cb8ba1fc7156263665080c9fdf2b11c"
+        "packages/engine/src/manifest/schema.ts": "1f191ca4d77de85bc9ec4dbe4e5cc83c571dab017ff070ac0d5ee344ebec6fa2"
       }
     },
     {
@@ -83,12 +85,12 @@
       "claim": "Unmodified native-React DOM games run via the manifest `ingest-react` identity: vendored byte-for-byte (vendor/games/, zero-diff CI), mounted through the react world stack under the host React 19 (deduped). NO authoring in v1 (the editor never writes JSX back into an unmodified game, D-N4).",
       "evidence": [
         "vendor/games/verify-unaltered.mjs (vendored-bytes gate: zero UNRECORDED diff — byte-identical files, plus any recorded per-file patch that must reverse-apply to the pinned upstream)",
-        "packages/editor/src/adapter-resolver.ts"
+        "packages/editor/src/roots/react-root.ts"
       ],
       "notes": "Scope is native-DOM React ONLY (D-N1): R3F/@pixi/react games are canvas games and ride the three.js/pixi seams instead. Generality limit: ONE proven game (react-rpg — menu-to-dungeon e2e under React 19; both game-2 candidates rejected on evidence, R-N7). Game deps must be host-installed root deps (D-N6). Open R-N6: vendored react games' raw window listeners bypass the play-mode input gate.",
       "evidenceHashes": {
         "vendor/games/verify-unaltered.mjs": "257a362030a10f4d72a3280815069fbd83f436e1619391635b6f8df2ddd6c339",
-        "packages/editor/src/adapter-resolver.ts": "63e4204afceb4395f395d5a4df48a5148de75da597a4407ee74ccf233c5d2fa6"
+        "packages/editor/src/roots/react-root.ts": "68c54cd5426b4480f40e48f11e1445e85697796c280d4f88addbdcd21981cfbd"
       }
     },
     {
@@ -104,7 +106,7 @@
       "notes": "This file exists for negatives engine-api.json can't express (e.g. 'parses but does nothing'). For the full positive surface, read engine-api.json/.md — regenerated by `npm run generate-engine-manifest`, can't drift.",
       "evidenceHashes": {
         "packages/engine/schemas/engine-api.json": "cdfd395fab88575a13c74451051e6c86f8b07980152120f00caa62098ecf7917",
-        "packages/engine/src/animation/xstate-animation-binding.ts": "8ec400c5abe1550a72adca3dfe30e57c42239fdd1eb986b8e05ec973ea3f3d7b",
+        "packages/engine/src/animation/xstate-animation-binding.ts": "984db5596e51a2ea4e20e419f94fbb3af47c1abbadfaf80431bcd2ba4577032c",
         "packages/engine/src/animation/blend-node.ts": "9e1d2018acf138bb984fd0d2c7ff1045ef00689e613abf531453af0a1ba06b2e"
       }
     }

package/schemas/vgai-project.schema.json

@@ -35,6 +35,7 @@
       "required": [
         "version"
       ],
+      "additionalProperties": false,
       "description": "Engine version pin"
     },
     "roots": {
@@ -138,24 +139,6 @@
                       "captureTimeoutMs": {
                         "description": "How long the host waits for this game's first captured frame before the mount FAILS by name. A game that needs a long boot (streamed world assets, a menu the player must clear) raises it; the default is 10s.",
                         "type": "number"
-                      },
-                      "world": {
-                        "description": "The component this root's WORLD is, in the game's own source — a three root whose scene is a React/R3F component tree names it here. Two readers, and they mount different things: the editor mounts THIS component alone as the root's design-time document (a still scene — its frameloop runs ONE bounded settle at mount, so physics-owned bodies rest at their authored spawn, and is then frozen forever; nothing moves in Edit), while `entry` above stays what PLAY mounts (the whole game, its own composition, its own HUD and loop). Declaring it is what lets a scene be a scene in Edit rather than the running game's mount surfaces. A game whose world is not a component omits it and keeps mounting through `entry` in both modes.",
-                        "type": "object",
-                        "properties": {
-                          "entry": {
-                            "type": "string",
-                            "description": "Project-relative path to the game's OWN module exporting that component"
-                          },
-                          "export": {
-                            "description": "Named export to read from that module; omit when the module default-exports it",
-                            "type": "string"
-                          }
-                        },
-                        "required": [
-                          "entry"
-                        ],
-                        "additionalProperties": false
                       }
                     },
                     "additionalProperties": false,
@@ -181,6 +164,24 @@
               "type": "string"
             }
           },
+          "world": {
+            "description": "The component this root's WORLD is, in the game's own source. Two readers, and they mount different things: the EDITOR mounts THIS component alone as the root's design-time document, while `entry` above stays what PLAY mounts (the whole game — its own composition, its own HUD, its own loop). It sits on the ROOT rather than inside any one adapter because the split it names is not about ingest: a game whose runtime entry is a SHELL over the thing an author actually edits has this shape whether the source is vendored or first-party. Two shipped cases, one field: an ingested game whose `entry` mounts game+HUD+loop while the named export is the world alone; and a translated Unity/Godot port, whose `entry` is a scene HOST that mounts the scene the built player starts on (`EditorBuildSettings` index 0 — routinely a menu with no 3D content at all) while the named export opens the scene an author edits. That is Unity's own split: build settings say where the PLAYER starts; the Scene view opens a scene, and Unity keeps that fact somewhere else entirely. A game whose world is not a separate component omits this and keeps mounting through `entry` in both modes.",
+            "type": "object",
+            "properties": {
+              "entry": {
+                "type": "string",
+                "description": "Project-relative path to the game's OWN module exporting that component"
+              },
+              "export": {
+                "description": "Named export to read from that module; omit when the module default-exports it",
+                "type": "string"
+              }
+            },
+            "required": [
+              "entry"
+            ],
+            "additionalProperties": false
+          },
           "zOrder": {
             "default": 0,
             "description": "Canvas stacking order; ties broken by array order",
@@ -256,12 +257,15 @@
                   "id",
                   "label",
                   "roots"
-                ]
+                ],
+                "additionalProperties": false
               }
             }
-          }
+          },
+          "additionalProperties": false
         }
-      }
+      },
+      "additionalProperties": false
     },
     "server": {
       "description": "Multiplayer server config (Colyseus), if this game registers a room",
@@ -305,7 +309,8 @@
       },
       "required": [
         "room"
-      ]
+      ],
+      "additionalProperties": false
     },
     "resolution": {
       "description": "Canvas resolution",
@@ -323,7 +328,8 @@
       "required": [
         "width",
         "height"
-      ]
+      ],
+      "additionalProperties": false
     },
     "rendering": {
       "description": "Construction-time renderer properties, which no world can declare after the fact. Everything a world CAN declare (tone mapping, output colour space, clear colour, shadow filter) lives on the world's own renderer config instead.",
@@ -350,7 +356,8 @@
       },
       "required": [
         "allowInProduction"
-      ]
+      ],
+      "additionalProperties": false
     },
     "determinism": {
       "description": "Seeded-RNG determinism contract (D15) — governs whether ctx.random is boot-seeded from a reproducible seed and whether the gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.",
@@ -369,7 +376,8 @@
       },
       "required": [
         "seededRandom"
-      ]
+      ],
+      "additionalProperties": false
     },
     "budget": {
       "description": "Performance budget (W3d, F11 perf regression gates) asserted by `vgai perf --assert-budget`: a seeded, fixed-step headless run samples the engine profiler and fails (nonzero exit) when any metric here is exceeded. Only headlessly-measurable metrics are budgetable; real GPU frame time is not (SwiftShader).",
@@ -403,7 +411,8 @@
           "exclusiveMinimum": 0,
           "maximum": 9007199254740991
         }
-      }
+      },
+      "additionalProperties": false
     },
     "learn": {
       "description": "Optional learner-facing metadata (FT-5) — set on shipped example projects so the gallery/wizard/Learn-catalog registries can be generated from the manifest itself",

package/src/adapter/adapter-module.ts

@@ -325,10 +325,8 @@ const AdapterRegionOverlaySchema = z
  * the full REPLACEMENT, and its entries carry `include`/`mounts` themselves.
  * Two homes for one fact is how a declaration goes stale in one of them.
  *
- * MEASURED BASIS (PR #2281, verified twice): the region binding was
- * replace-only, so no `nativeAdapter()` project could declare a single include
- * without restating every region — which is what blocked the source-text R3F
- * floor's retirement across the five shipped 3D projects.
+ * MEASURED BASIS: a replace-only region binding means no `nativeAdapter()`
+ * project can declare a single include without restating every region.
  */
 const RegionIncludesSchema = z
   .record(z.string().min(1), AdapterRegionOverlaySchema)

package/src/adapter/adapter-surface.ts

@@ -18,7 +18,7 @@ export type AdapterSurface = 'three' | 'canvas' | 'dom';
  * site, not silently contribute nothing or silently default to an existing
  * kind). Lives here — colocated with the kind vocabulary itself, not in a
  * generic util module — so the three call sites that need it
- * (`runtime/create-runtime.ts`'s mount loop, `editor/adapter-resolver.ts`'s
+ * (`runtime/create-runtime.ts`'s mount loop, `editor/binding-resolver.ts`'s
  * `resolveAllRoots`, `editor/play-mode.ts`'s `installMultiRootAuthoring`)
  * import it from the same leaf module that defines `AdapterSurface`, keeping the
  * type and its guard from drifting apart. The `never` parameter is the

package/src/adapter/authoring.ts

@@ -2,8 +2,8 @@
  * AuthoringAdapter — the editor's authoring contract. The editor talks to THIS,
  * keyed by opaque string node ids, instead of to a concrete document format.
  *
- * `.vscn` / `SceneEntity` is the private model of ONE implementer
- * (`VgaiSceneAuthoringAdapter`); an ingested game's adapter implements the same
+ * An implementer's document model is its own private business; an ingested
+ * game's adapter implements the same
  * providers directly over its live `Object3D` tree. The editor sees only the
  * interface and the advertised `capabilities` — it never branches on which
  * implementer it is talking to.
@@ -29,8 +29,7 @@ import type { Transform } from './transform';
  * Deliberately SMALL: a capability flag earns its place only when the shell
  * actually branches on it. Structural affordances (create/delete/reparent) are
  * gated by `structure` PROVIDER PRESENCE instead — the flag and the provider
- * cannot disagree that way. (WO-2 deleted `material`/`create`/`delete`/
- * `reparent`/`layout`, which no shell code ever read.)
+ * cannot disagree that way.
  */
 export interface AuthoringCapabilities {
   transform: boolean;
@@ -89,7 +88,7 @@ export type EditorNodeRole =
   | 'entity'
   | 'boundary';
 
-/** A node in the authoring hierarchy — format-neutral (not a `SceneEntity`). */
+/** A node in the authoring hierarchy — format-neutral. */
 export interface EditorNode {
   /** STABLE id — survives reload (see ingest structural-path ids). */
   id: string;
@@ -202,9 +201,9 @@ export interface SelectionProvider {
 }
 
 /** Adapter-owned result of semantic selection resolution: the raw native/render
- * hit mapped to the node the author actually means. (The former
- * `inspectorId`/`transformId`/`boundaryId` aliases were never read by the
- * shell — deleted in WO-2.) */
+ * hit mapped to the node the author actually means. ONE id, deliberately:
+ * separate inspector/transform/boundary aliases would have to agree, and
+ * nothing in the shell can enforce that. */
 export interface SelectionResolution {
   /** Hierarchy selection and Inspector subject. */
   id: string;
@@ -316,7 +315,7 @@ export interface TransformObservation {
 }
 
 export interface InspectorProvider {
-  /** Schema-driven — NOT fixed to `SceneEntity`. */
+  /** Schema-driven — fixed to no document format. */
   properties(id: string): PropertyDescriptor[];
   get(id: string, path: string): unknown;
   /**
@@ -620,24 +619,24 @@ export interface PersistenceProvider {
    * subsequent persistence clears it. Auto-saving source adapters use this to
    * report a rolled-back source write without inventing a dirty document. */
   lastError?(): string | null;
-  /** Save to the adapter's OWN source of truth (.vscn / overlay file / …). */
+  /** Save to the adapter's OWN source of truth (its source file, its own
+   *  data, …) — whatever that adapter defines it to be. */
   save(): Promise<void>;
   /**
    * Human/agent-readable destination this provider persists to — e.g.
-   * `"scenes/main.vscn.json"`, `"live-only (not saved)"`, or `"ephemeral
+   * `"src/world.tsx"`, `"live-only (not saved)"`, or `"ephemeral
    * (discarded on stop)"`. Drives the save-status UI and makes routing
    * inspectable (design §2). Implementers whose destination can change during
-   * the session (e.g. the first-party provider tracks the loaded `.vscn` path)
+   * the session (a provider that tracks the currently focused document, say)
    * should expose this as a live getter rather than a value captured once.
    */
   readonly destination: string;
   /**
    * The reload contract (design §5): apply an external change to this
    * provider's persisted artifact into the RUNNING session (e.g. a file-watcher
-   * update to the `.vscn` or the overlay). Absent ⇒ the host must remount to
-   * pick up external changes (the honest floor). Implemented (T3.2 slice 3) by
-   * the first-party provider (`applyExternalUpdate`) and the ingest overlay
-   * provider (`applyOverlay`); absent (correctly) on the ephemeral provider.
+   * update to the artifact). Absent ⇒ the host must remount to
+   * pick up external changes — the honest floor, and correctly what the
+   * ephemeral provider reports.
    *
    * `rawContent`, when the host has it (the file-watcher SSE payload carries the
    * artifact's exact bytes), is an OPTIONAL second parameter enabling own-echo
@@ -823,7 +822,7 @@ export interface ColorSampleProvider {
 }
 
 /**
- * WO-IDX1 — where a node's live object CAME FROM in the game's own truth.
+ * Where a node's live object CAME FROM in the game's own truth.
  *
  * `display` is the string the editor shows verbatim. The unanchored shape
  * carries a `reason` rather than a blank, because "we don't know" and "a
@@ -1172,10 +1171,9 @@ export interface AuthoringAdapter {
    * Observe transform GESTURES on this adapter's nodes — the one seam the
    * animation sequencer needs to record a drag as keyframes and to refresh its
    * design baselines. Deliberately narrow (one event shape, one consumer, no
-   * general event bus): before it existed, the sequencer could only observe
-   * the first-party store's own `.vscn` transform path, so a live or
-   * source-backed world's gestures were invisible to it. Absent ⇒ this
-   * adapter reports no gestures.
+   * general event bus): without it the sequencer can only observe the store's
+   * own transform path, so a live or source-backed world's gestures are
+   * invisible to it. Absent ⇒ this adapter reports no gestures.
    */
   observeTransforms?(listener: (event: TransformObservation) => void): () => void;
 }