@woosh/meep-engine 3.15.0 → 3.17.0

package/src/engine/ecs/transform/TRANSFORM64_EVENT_CHANGE.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Entity event announcing that an entity's {@link Transform64} was mutated in place.
+ *
+ * A {@link Transform64} carries no signals - that is the point of it - so a write is invisible
+ * until someone says so, and saying so is the writer's job. Everything that used to wake on
+ * `position.onChanged` waits on this instead: the render placement, the parent/child sync,
+ * fog-of-war, the grid mirror, the spatial audio refit.
+ *
+ * The name is the whole message, and there is no payload. A listener is registered against one
+ * entity and one event name, so by the time it runs it already knows which entity moved, that what
+ * moved was the transform, and which instance that is - it was handed the instance when it linked.
+ * Anything sent alongside would only be handing back what the listener already holds, at the price
+ * of an `if` at the top of every listener to discard the dispatches meant for somebody else.
+ *
+ * Announce with {@link t64_announce_change}, once per group of writes:
+ *
+ * ```
+ * transform.setRotation(x, y, z, w);
+ * transform.updateMatrix();
+ *
+ * t64_announce_change(ecd, entity);
+ * ```
+ *
+ * Deliberately coarse - it says *that* the transform changed, not *what* changed inside it. A
+ * transform rewritten wholesale, as {@link Transform64#multiplyTransforms} rewrites one, has no
+ * finer answer to give, and a per-channel axis running beside this one would be a second mechanism
+ * describing one write. Waking on a superset of what you care about is expected: a consumer woken
+ * by a scale write when it only tracks translation does redundant work, not wrong work. Where that
+ * is too expensive, that one consumer keeps a copy and compares against it.
+ *
+ * @type {string}
+ *
+ * @see t64_announce_change
+ * @see TRANSFORM_ATTACHMENT_EVENT_CHANGE
+ * @see EntityComponentDataset#addEntityEventListener
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const TRANSFORM64_EVENT_CHANGE: string;
+//# sourceMappingURL=TRANSFORM64_EVENT_CHANGE.d.ts.map

package/src/engine/ecs/transform/TRANSFORM64_EVENT_CHANGE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TRANSFORM64_EVENT_CHANGE.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/TRANSFORM64_EVENT_CHANGE.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,uCATU,MAAM,CAS8C"}

package/src/engine/ecs/transform/TRANSFORM64_EVENT_CHANGE.js

@@ -0,0 +1,40 @@
+/**
+ * Entity event announcing that an entity's {@link Transform64} was mutated in place.
+ *
+ * A {@link Transform64} carries no signals - that is the point of it - so a write is invisible
+ * until someone says so, and saying so is the writer's job. Everything that used to wake on
+ * `position.onChanged` waits on this instead: the render placement, the parent/child sync,
+ * fog-of-war, the grid mirror, the spatial audio refit.
+ *
+ * The name is the whole message, and there is no payload. A listener is registered against one
+ * entity and one event name, so by the time it runs it already knows which entity moved, that what
+ * moved was the transform, and which instance that is - it was handed the instance when it linked.
+ * Anything sent alongside would only be handing back what the listener already holds, at the price
+ * of an `if` at the top of every listener to discard the dispatches meant for somebody else.
+ *
+ * Announce with {@link t64_announce_change}, once per group of writes:
+ *
+ * ```
+ * transform.setRotation(x, y, z, w);
+ * transform.updateMatrix();
+ *
+ * t64_announce_change(ecd, entity);
+ * ```
+ *
+ * Deliberately coarse - it says *that* the transform changed, not *what* changed inside it. A
+ * transform rewritten wholesale, as {@link Transform64#multiplyTransforms} rewrites one, has no
+ * finer answer to give, and a per-channel axis running beside this one would be a second mechanism
+ * describing one write. Waking on a superset of what you care about is expected: a consumer woken
+ * by a scale write when it only tracks translation does redundant work, not wrong work. Where that
+ * is too expensive, that one consumer keeps a copy and compares against it.
+ *
+ * @type {string}
+ *
+ * @see t64_announce_change
+ * @see TRANSFORM_ATTACHMENT_EVENT_CHANGE
+ * @see EntityComponentDataset#addEntityEventListener
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export const TRANSFORM64_EVENT_CHANGE = "@transform64/change";

package/src/engine/ecs/transform/TRANSFORM64_MIGRATION_PLAN_2026_09_04.md

@@ -0,0 +1,521 @@
+# Transform → Transform64 migration plan
+
+*Revision 3, 2026-09-04. Revision 2 was rejected on three counts, all correctly: it invented a
+change-detection mechanism next to one the ECS already has, it proposed deleting engine code on
+"no importers" evidence, and its facade would have left the abstraction layers Transform64 exists to
+remove. This revision replaces the architecture; the survey work underneath it stands.*
+
+*Update, 2026-09-05: the change-detection mechanism specified below - `EventType.ComponentChanged`
+carrying `{klass, instance}` - has been replaced by one event name per component that announces
+itself: `TRANSFORM64_EVENT_CHANGE` (`@transform64/change`) and `TRANSFORM_ATTACHMENT_EVENT_CHANGE`
+(`@transform_attachment/change`), each sent with no payload, so a listener is woken only by the
+thing it asked about and has nothing to filter. `EventType.ComponentChanged` is gone, and with it
+the residual unknown about broadening it. Everything else here stands; read `ComponentChanged`
+throughout as "the changed component's own event".*
+
+---
+
+## Where things stand
+
+`Transform64` is a `Float64Array` subclass, 23 elements: a column-major matrix at `[0..15]` whose
+translation column `[12..14]` **is** the translation, a rotation quaternion at `[16..19]`, a scale at
+`[20..22]`. One buffer, one allocation, no sub-objects, no signals, no flags. Thirty-six source files
+use it — `Node3D`, `Mesh`, the pose and skinning pipeline, the glTF loader, `MeshSystem`,
+`m4_decompose_array`.
+
+`Transform` is the registered ECS component: a class holding a live `Vector3` position, a live
+`Quaternion` rotation, a live `Vector3` scale, and a `Float32Array` matrix, whose constructor
+subscribes to all three sub-object signals and recomposes the matrix on every change. **256 files**
+import it across `src`, `editor` and `samples` — **100 production, 156 spec**.
+
+The origin commit `71ae86be1` calls Transform64 "a passive Float64Array transform **component**". The
+ECS side was always the destination. The work stalled at the renderer seam, and the seam is where the
+engine currently loses precision.
+
+### The gap
+
+`Transform` tells the world it moved. `Transform64` cannot, and — by design — must not learn how:
+it is one prototype over a `Float64Array` and nothing else. No fields, no callbacks, no version
+counter, no cached views. Anything that would widen the buffer or hang state off the instance
+defeats the reason the type exists.
+
+So notification has to live where notification already lives: in the dataset.
+
+---
+
+## The three decisions this revision makes
+
+### 1. Change detection is `EventType.ComponentChanged`, sent through `sendEvent`
+
+The ECS already has a per-entity event channel, and component lifecycle already travels on it:
+
+```js
+// EntityComponentDataset.js:1202
+this.sendEvent(entity_id, EventType.ComponentAdded,   { klass: componentClass, instance: component_instance });
+// EntityComponentDataset.js:1068
+this.sendEvent(entity_id, EventType.ComponentRemoved, { klass: componentClass, instance: componentInstance });
+```
+
+`EventType` (`src/engine/ecs/EventType.js`) has exactly three members today. The addition is a
+fourth, with the identical payload shape:
+
+```js
+export const EventType = {
+    EntityRemoved:    "entityRemoved",
+    ComponentAdded:   "componentAdded",
+    ComponentRemoved: "componentRemoved",
+    ComponentChanged: "componentChanged"     // <- new: { klass, instance }
+};
+```
+
+A writer that mutates a component in place announces it:
+
+```js
+ecd.sendEvent(entity, EventType.ComponentChanged, { klass: Transform64, instance: t64 });
+```
+
+A consumer subscribes the way `PathDisplaySystem.js:125` already does, in `link`, and filters on
+`klass`. `addEntityEventListener` / `removeEntityEventListener` need no change, and the existing
+"any event" listener path picks it up for free.
+
+**Why coarse, and not per-field channels.** An earlier draft proposed a per-channel version column
+(translation / rotation / scale). That is wrong on its own terms: after
+`Transform64.multiplyTransforms` or `fromMatrix` rewrites the buffer wholesale, there is no channel
+the write belongs to — the honest answer is "all of them", which is the same as no channel at all.
+It also duplicates a distinction the dataset already draws: added / removed / changed is the
+component's lifecycle, and a second, finer axis running beside it is two mechanisms where one will
+do. Fine granularity is only meaningful when component data is flat, and a transform's is not.
+
+Making it the consumer's problem to work out what changed is the correct trade. **Over-reaction is
+acceptable** — a consumer that only cares about translation waking on a rotation write does redundant
+work, not wrong work. Where a consumer genuinely cannot afford that, it compares against its own
+retained copy; that cost sits with the one consumer that needs it rather than in the type everyone
+pays for.
+
+### 2. Nothing gets deleted on reachability evidence
+
+Revision 2 proposed deleting `EntityPath` / `EntityPathMarker`, `PerfectPanner`, `createDebugLabel`,
+`fabrik_solve`, `SpriteSystemPE` / `Sprite`, `setMesh` and `updateNodeByTransformAndBBB`, on the
+grounds that nothing in the repository imports them.
+
+**That reasoning does not hold for a library.** meep is an engine; its consumers are downstream
+applications, and `package.json` exports `./src/*`, `./editor/*` and `./samples/*` wholesale with all
+three in `files`. Every source file is published API. "No internal importer" is a statement about
+this repository, not about whether anyone calls it.
+
+There is no delete stage. Those files migrate like everything else. Two notes carried forward, as
+observations rather than licence:
+
+- `engine/graphics/ecs/mesh/setMesh.js:47` calls `component.internalApplyTransform`, which a
+  repository-wide grep finds at exactly that one call site. It would throw if reached. That is a bug
+  to fix or report, not evidence of death.
+- `src/view/minimap/**` imports `../../../../model/game/...` from the parent `moh` repository, and
+  `vitest.config.mjs:14-19` excludes its spec for that reason, in its own words. It is live code
+  whose dependency and whose consumer both sit outside this tree. Do not remove that exclude line.
+
+### 3. No facade, no views. `Transform` survives untouched and ends up unused
+
+Revision 2 proposed making `Transform` a subclass of `Transform64` with live `Vector3`/`Quaternion`
+views over its buffer, so the 256 importers would keep compiling unchanged. Rejected, for the reason
+that motivates the whole exercise: persisting a view layer reinstates exactly the abstraction
+Transform64 was built to strip. A `Transform64` is a bare `Float64Array` with one prototype in the
+chain. Views over its buffer, held anywhere durable, are the old design wearing new storage.
+
+The end state instead:
+
+| | |
+|---|---|
+| `Transform.js` | **Unchanged.** Byte-identical to today, still exported, still serializable |
+| `Transform64.js` | **Unchanged in shape.** 23 elements, no added fields |
+| Engine use of `Transform` | **None.** Every system, every editor tool, every spec is on `Transform64` |
+| `EventType.ComponentChanged` | The one new mechanism, in the ECS where it belongs |
+
+`Transform` becomes what an engine keeps for its consumers: a supported type that the engine itself
+no longer builds on. No shim to remove, no deprecation cliff, no deletion to schedule.
+
+**What replaces the facade as the migration vehicle** is the bridge that already exists and already
+works. `TerrainSystem` and `MeshSystem` do this today: hold a `Transform64`, poll the entity's
+`Transform`, and use `t64_equals_transform` to skip the copy when nothing moved. That is the
+sanctioned temporary state — one side owns the value, the other mirrors it — and it is temporary per
+subsystem, not per codebase.
+
+**The allocating getters stay as they are.** `t.translation` returning a fresh `Float64Array` view is
+the correct behaviour for a type that holds no state; caching it would mean a field. Hot paths use
+the scalar accessors (`translation_x`, `rotation_w`, …) and free functions that take
+`(array, offset)`. That is a call-site rule, enforced by the audit in Stage 2, not a type change.
+
+---
+
+## Stages
+
+Ordering is by dependency, not by size. Every stage leaves the repository green.
+
+### Stage 0 — `Transform64` becomes a registered component · **M**
+
+**Goal:** an entity can carry a `Transform64`, and it survives a save round-trip.
+
+**Touches** `engine/ecs/transform/Transform64SerializationAdapter.js` (new),
+`engine/ecs/storage/populateEngineSerializationRegistry.js`, `engine/ecs/EntityComponentDataset.js`
+(verification only).
+
+**Work.** `registerComponentType` (`EntityComponentDataset.js:802`) keys off the class reference and
+imposes no shape requirement, so a `Float64Array` subclass registers as-is — but confirm the storage
+path, the clone path and `getAllComponents` before relying on it, since a typed-array subclass is
+unlike every component registered so far. Then add the adapter, modelled directly on
+`TransformSerializationAdapter`:
+
+```js
+export class Transform64SerializationAdapter extends BinaryClassSerializationAdapter {
+    klass = Transform64;
+    version = 1;
+    // translation: 3 × Float64, as TransformSerializationAdapter already does
+    // rotation:    quat3_encode_to_uint32, as today
+    // scale:       v3_binary_equality_encode, as today
+    // matrix:      NOT serialized — derived by updateMatrix() on load
+}
+```
+
+Register it beside the existing one at `populateEngineSerializationRegistry.js:200`.
+
+**Note on the save format.** `TransformSerializationAdapter` already writes `writeFloat64` for
+position (`:24-26`) and already encodes rotation to a uint32. The byte layout for a `Transform64` is
+therefore *the same layout*, and the two adapters can share an encoding. Save compatibility is a
+smaller problem than it looks; the open question is the type name the registry keys on, which
+Stage 8 settles.
+
+**Proves it** A new `Transform64SerializationAdapter.spec.js` round-tripping through `BinaryBuffer`,
+plus a dataset spec that registers `Transform64`, links it to an entity, reads it back by class, and
+removes it.
+
+**Unblocks** everything.
+
+---
+
+### Stage 1 — `EventType.ComponentChanged` · **S**
+
+**Goal:** the signalling mechanism exists and is documented, before anything sends it.
+
+**Touches** `engine/ecs/EventType.js`, `engine/ecs/EntityComponentDataset.js` (doc only).
+
+**Work.** Add the enum member. Document the `{ klass, instance }` payload contract on `sendEvent`
+next to the `@see` block at `:1721`. Nothing dispatches it yet, and no consumer subscribes — this
+stage is deliberately inert so the mechanism can be reviewed on its own.
+
+Decide here, and write down, whether the dataset itself should send it from any built-in path
+(it should not: the dataset cannot know a caller finished mutating a buffer, and a write-through
+accessor is the field-carrying design this plan rejects).
+
+**Proves it** `EventType.spec.js`: sending `ComponentChanged` reaches a listener registered with
+`addEntityEventListener`, reaches an "any event" listener, and does not fire on unrelated entities.
+
+**Unblocks** every migrated writer.
+
+---
+
+### Stage 2 — Tripwires and the enrolment ratchet · **M**
+
+**Goal:** "the migration progressed" and "no hot path regressed" both become machine-checkable.
+
+**Touches** a new `engine/ecs/transform/migration_enrolment.spec.js`; a dev-only allocation counter.
+
+**Work.** Two guards.
+
+*The ratchet.* A spec holding the explicit list of files still importing `Transform.js`, scanning
+`src`, `editor` and `samples`. It fails if a file not on the list imports it (new coupling) and fails
+if a listed file no longer does (stale list — update it, and the number only falls). This is the
+progress meter for every later stage and the exit criterion at the end.
+
+*The allocation audit.* A dev-mode counter incremented by `Transform64`'s `translation` / `rotation` /
+`scale` getters — **behind a build flag, not a field on the instance**, so the shipped type is
+unchanged. Specs for the hot paths (physics step, `MeshSystem` update, first-person camera
+composition) assert the count is zero across a simulated frame. This is what makes "hot paths use
+scalar accessors" enforceable rather than a review convention.
+
+**Proves it** Both specs, red before the guard exists and green after.
+
+**Unblocks** every claim of progress made below.
+
+---
+
+### Stage 3 — The scalar and free-function vocabulary · **M**
+
+**Goal:** every read and write a migrated call site needs, without allocating and without a view.
+
+**Touches** `core/geom/vec3/**`, `core/geom/3d/quaternion/**`, `core/geom/3d/mat4/**`,
+`engine/ecs/transform/t64_*.js`.
+
+**Work.** Inventory what the 256 files actually call — the census is dominated by `.position.set`,
+`.position.x/y/z`, `.rotation.set`, quaternion conversions (`toEulerAnglesYXZ`,
+`fromEulerAnglesYXZ`, `fromAxisAngle`, `multiplyQuaternions`, `rotateTowards`, `computeTwistAngle`)
+and `.scale.setScalar`. Map each to an existing `v3_*` / `quat3_*` free function; write only the ones
+genuinely missing. Follow the established convention — free functions over methods, no variant
+factories.
+
+The reading vocabulary is already there: `translation_x`, `rotation_w`, `scale_z`, and raw indexing
+via the exported offset constants. The writing vocabulary is `setTranslation` / `setRotation` /
+`setScale` plus `updateMatrix`.
+
+**The one rule that matters.** A write to rotation or scale needs `updateMatrix()`; a translation-only
+write does not, because the translation *is* the matrix column. Both then need the Stage 1 event.
+Where a call site does several writes, one `updateMatrix()` and one event at the end — not per write.
+
+**Proves it** Each new free function gets a spec. No behaviour change yet.
+
+**Unblocks** Stages 4–10.
+
+---
+
+### Stage 4 — The graphics3 ↔ shade seam · **S**
+
+**Goal:** close the half-migrated seam first, because it is the one place both types already meet and
+the pattern the rest copies.
+
+**Touches** `engine/graphics3/MeshSystem.js`, `TerrainSystem.js`, `pose/query_entity_node_world_pose.js`,
+`shade_node_to_entity_composition.js`, `camera_sync_from_transform.js`, `DecalSystem.js`.
+
+**Work.** These systems hold a `Transform64` and mirror an entity's `Transform` into it. Once the
+entity carries a `Transform64` directly, the mirror and the poll both go away: the system reads the
+component. `t64_copy_from_transform` loses callers here; keep it until its last caller anywhere is
+gone.
+
+**The trap, verified.** `TerrainSystem.js:352` guards with `t64_equals_transform`, which compares
+*components only, by deliberate design* — its own doc says a matrix comparison "would answer a
+question about the lossy half", because `Transform`'s matrix is f32 while its components are f64.
+`Transform64.equals` is the opposite: "strict equality across the whole transform, `matrix` included".
+Swapping one for the other turns the guard matrix-inclusive, so a stale matrix on either side reads
+as a move, and the per-frame top-level acceleration structure rebuild this guard exists to prevent
+comes back. The replacement is a components-only comparison between two `Transform64`s — a new
+`t64_equals_components`, not `equals`.
+
+**Proves it** Existing `MeshSystem.spec.js` / `TerrainSystem.spec.js` green, plus a new spec asserting
+the tile guard still skips when only the matrix differs.
+
+**Unblocks** the pattern every later system follows.
+
+---
+
+### Stage 5 — Readers · **L**
+
+**Goal:** migrate every site that only reads a transform. No event, no ordering question.
+
+**Touches** roughly 34 production files across `engine/sound/**`, `engine/navigation/ecs/**`,
+`engine/grid/**`, `engine/intelligence/behavior/**`, `engine/achievements/**`,
+`generation/markers/**`, `engine/ecs/terrain/**`, `engine/ecs/fow/**`, and the read half of
+`engine/graphics3/*System.js`.
+
+**Work.** Switch `dependencies` from `Transform` to `Transform64`; replace `.position.x` with
+`.translation_x` and friends. Hot loops take the scalar accessors; cold sites may use the allocating
+getters. Mechanical, one commit per subsystem, each independently revertible.
+
+**Proves it** Each subsystem's existing spec, unchanged in intent, with its fixture switched.
+
+---
+
+### Stage 6 — Writers, and physics determinism · **L**
+
+**Goal:** migrate every site that writes a transform, and settle what f64 does to determinism.
+
+**Touches** `engine/physics/**` (the largest cluster), `engine/ecs/parent`,
+`engine/ecs/transform-attachment`, `engine/graphics3` write paths, `engine/animation/**`.
+
+**Work.** Each writer: write through the scalar setters, call `updateMatrix()` once if rotation or
+scale changed, then send `EventType.ComponentChanged`. Subscribers that previously hung off
+`position.onChanged` move to `addEntityEventListener` in `link` and drop it in `unlink`.
+
+**The precision change, and it is a fix.** `Transform.multiplyTransforms` composes through a
+module-level `const scratch_matrix = new Float32Array(16)` (`Transform.js:15`, used at `:361`), and
+that is the method `TransformAttachmentSystem.UpdateContext.update()` (`:63-67`) calls for **every
+attached entity's world pose**. Measured: `16777218` where exact is `16777217.75`. Every attachment's
+world transform is quantised to f32 today. Moving to `Transform64.multiplyTransforms` removes the
+quantisation — which means `engine/physics/determinism.spec.js` will see different numbers. They will
+be *more* accurate, and determinism is preserved (f64 arithmetic is as reproducible as f32 across
+platforms), but any fixture with baked-in expected values must be re-baselined deliberately, in its
+own commit, with the diff reviewed rather than accepted wholesale.
+
+**Proves it** Physics suite green after a reviewed re-baseline; a new spec asserting a rotation write
+emits exactly one `ComponentChanged` and a translation write emits one without an `updateMatrix`.
+
+---
+
+### Stage 7 — Retained sub-object references · **M**
+
+**Goal:** close the pattern that has no `Transform64` equivalent.
+
+**Touches** roughly 14 sites in `engine/sound/**` and `engine/animation/**`, plus anything the
+Stage 2 ratchet surfaces.
+
+**Work.** These hold `transform.position` past the statement that fetched it — stored in a field,
+captured in a closure, or handed to an animation track. A `Transform64` getter returns a fresh view
+each call, so the reference is not live and identity comparison is meaningless. Each site becomes
+either a retained *copy* (when it wanted a snapshot) or a retained `{ entity, dataset }` pair re-read
+on use (when it wanted liveness). Animation tracks that write into a retained sub-object become
+writes through the component plus a Stage 1 event.
+
+**Proves it** A spec per converted site asserting the value tracks (or deliberately does not track)
+subsequent writes.
+
+---
+
+### Stage 8 — Serialization identity, network, rollback · **M**
+
+**Goal:** decide what the persisted type is called, and what goes on the wire.
+
+**Touches** `Transform64SerializationAdapter`, `populateEngineSerializationRegistry.js`,
+`engine/network/adapters/TransformReplicationAdapter.js`, `engine/interpolation/**`.
+
+**Work.** Two decisions, both one-way.
+
+*Save identity.* The registry keys on the adapter's `klass`. Entities saved with a `Transform` load
+as `Transform`; entities saved with a `Transform64` load as `Transform64`. Whether old saves upgrade
+in place (via `TransformSerializationUpgrader_0_1`, extended) or the engine simply reads both is a
+product decision, not a technical one — state it and move on.
+
+*Wire format.* `TransformReplicationAdapter` deliberately uses Float32 for position and says so at
+`:19-30`: distinct from the save adapter precisely so saves keep full precision while the wire stays
+cheap. **That reasoning survives the migration unchanged** — the replication adapter keeps quantising
+on the wire regardless of the component's internal precision. This is not a bandwidth regression, and
+any claim that f64 doubles the packet is wrong.
+
+**Rollback.** Snapshot/restore must copy the buffer, not alias it. A `Transform64` is a
+`Float64Array`, so `set()` on a same-length buffer is the copy; `slice()` returns a plain
+`Float64Array` by the type's `Symbol.species`, which is correct for a snapshot but is *not* a
+`Transform64` — restore paths must not assume the prototype survived.
+
+**Proves it** Round-trip specs both ways; the existing network end-to-end and rollback specs green.
+
+---
+
+### Stage 9 — Editor and samples · **L**
+
+**Goal:** the 19 production and 14 spec files in `editor/`, plus 2 in `samples/`.
+
+**Touches** `editor/ecs/component/{prototypeObjectEditor,registerEngineComponentEditors}.js`,
+`editor/tools/{TransformToolV2.js,v2/TransformControls.js,v2/GizmoNode.js}`,
+`editor/actions/concrete/TransformModifyAction.js`, the six `process/symbolic/*SymbolicDisplay.js`,
+`editor/selection/editor_pick.js`, `editor/templates/entity_templates.js`,
+`editor/persistence/buildNewSceneDataset.js`, `editor/camera/camera_framing.js`,
+`editor/view/prepareMeshLibrary.js`.
+
+**Work.** Two genuinely hard files and a mechanical tail.
+
+*The inspector.* `prototypeObjectEditor` builds a UI by walking a component's shape. A `Transform64`
+is 23 indexed numbers with accessors on the prototype — walked naively it renders 23 unlabelled
+fields. It needs a dedicated `Transform64Editor` registered by constructor identity, ahead of any
+generic `Float64Array` handling, presenting translation / rotation / scale as the three groups a user
+expects.
+
+*Undo/redo.* `TransformModifyAction` captures and restores a transform. Establish exactly what it
+captures; a captured `Transform64` must be a copied buffer, and a captured sub-object view is not a
+capture at all. This is Stage 7's problem in the one place where getting it wrong silently corrupts a
+user's edit history.
+
+**Proves it** Editor specs green; a new spec asserting an undo after a gizmo drag restores the exact
+prior buffer.
+
+**Unblocks** the exit criterion, which scans `editor/` too.
+
+---
+
+### Stage 10 — First-person · **L**
+
+**Goal:** the largest single cluster — 32 files, of which 3 are production.
+
+**Touches** `engine/control/first-person/**`.
+
+**Work.** The survey's useful finding is that the cluster is 29 specs over a small production
+surface, concentrated in `FirstPersonPlayerControllerSystem.js`. The work is mostly fixture
+migration. The production work is the euler/quaternion conversions and the `forward`/`up`/`right`
+axes, all of which `Transform64` already offers directly — including as setters, which `Transform`
+does not have.
+
+**Proves it** The 29 specs, migrated fixture by fixture.
+
+---
+
+### Stage 11 — Specs, docs, and the exit · **L**
+
+**Goal:** the remaining spec tree, the published surface, and a checkable finish.
+
+**Touches** the residual specs across all three roots, `README.md`, any shipped `.md` naming
+`Transform`, `npm run generate-types` output.
+
+**Work.** Migrate remaining fixtures. Regenerate declarations and confirm the consumer type-check
+budget has not risen. Note in the CHANGELOG that the engine now builds on `Transform64` and that
+`Transform` remains supported and unchanged — this is an addition, not a break, so it needs no major.
+
+**Exit criterion**
+
+```bash
+# 1. the engine no longer builds on the legacy component
+npx vitest run src/engine/ecs/transform/migration_enrolment.spec.js
+#    ALLOWED list === [] , roots = ["src", "editor", "samples"]
+
+# 2. Transform is byte-identical to where it started
+git diff --stat <migration-base>..HEAD -- src/engine/ecs/transform/Transform.js   # expect: EMPTY
+
+# 3. Transform64 gained no fields
+git diff <migration-base>..HEAD -- src/engine/ecs/transform/Transform64.js | grep '^+' | grep -v '^+++'
+#    expect: no new instance fields; TRANSFORM64_SIZE still 23
+
+# 4. no hot path allocates a view
+npx vitest run -t "allocates no component views"
+
+# 5. everything still passes
+npx vitest run && npm run check-types && npm run build-module
+```
+
+Checks 2 and 3 are the ones that distinguish this plan from the revision it replaces: the migration
+is done when the engine stopped using `Transform`, **not** when `Transform` changed.
+
+---
+
+## Risk register
+
+| Risk | Early sign | Mitigation |
+|---|---|---|
+| Two sources of truth on one entity — a system reads `Transform` while another writes `Transform64` | A value that updates one frame late, or not at all, in a partially migrated subsystem | Migrate by entity archetype, not by file. The bridge helpers are the sanctioned interim, and only one side owns the value at a time |
+| Missing `updateMatrix()` after a rotation or scale write | A stale matrix reaching the renderer — visible as an object rendering at its previous orientation | The Stage 2 audit spec; and the rule that one write group ends in one `updateMatrix` + one event |
+| Over-reaction becomes a perf problem, not just redundant work | Frame time rising in a subsystem after its Stage 6 commit | Accepted by design; where it bites, the one affected consumer retains a copy and compares. Do not reintroduce channels |
+| Determinism fixtures re-baselined without review | A physics fixture diff accepted wholesale in a large commit | Re-baseline in its own commit, diff reviewed, and only after Stage 6's precision change is understood |
+| `Float64Array` subclass breaks something in component storage that only shows at scale | Clone, snapshot or serialization behaving oddly for `Transform64` but not other components | Stage 0 verifies the storage, clone and `getAllComponents` paths explicitly before anything depends on them |
+| Undo/redo captures a view instead of a copy | An undo that restores the *current* value, i.e. does nothing | Stage 9's dedicated spec |
+| `Symbol.species` surprises — `slice()` returns a plain `Float64Array` | A restore path producing an object without `Transform64`'s prototype | Called out in Stage 8; snapshot with `set()` into a real `Transform64` |
+
+---
+
+## Summary
+
+| # | Stage | Effort | Blocked by |
+|---|---|---|---|
+| 0 | `Transform64` registered as a component + serialization adapter | M | — |
+| 1 | `EventType.ComponentChanged` | S | — |
+| 2 | Tripwires: enrolment ratchet + allocation audit | M | — |
+| 3 | Scalar and free-function vocabulary | M | — |
+| 4 | graphics3 ↔ shade seam | S | 0, 3 |
+| 5 | Readers | L | 3, 4 |
+| 6 | Writers + physics determinism | L | 1, 3, 5 |
+| 7 | Retained sub-object references | M | 3, 6 |
+| 8 | Serialization identity, network, rollback | M | 0 |
+| 9 | Editor and samples | L | 3, 6 |
+| 10 | First-person | L | 3, 6 |
+| 11 | Specs, docs, exit | L | 4–10 |
+
+**Critical path:** 0 → 3 → 4 → 5 → 6 → 11. Stages 1, 2 and 8 run alongside. Stages 9 and 10 are
+large but parallel to each other once 6 lands.
+
+---
+
+## Residual unknowns
+
+- **Whether component storage handles a typed-array subclass cleanly.** Registration does — it keys
+  on the class reference and imposes no shape. Storage, cloning and any structured-clone path are
+  unverified. Stage 0 exists to settle this, and if it fails, the shape of the answer changes (a thin
+  subclass carrying ECS metadata, which would be a departure from "one prototype, nothing more" and
+  would need your call).
+- **Whether `EventType.ComponentChanged` should be sent for components other than transforms.** It is
+  a general mechanism and this plan only uses it for one type. Broadening it is a separate decision.
+- **The migration-by-archetype boundary.** Which entities carry which transform during the interim is
+  the highest-risk part of this plan and the least specified. Stage 4 establishes the pattern on the
+  smallest cluster deliberately, so the boundary is learned somewhere cheap.
+- **File counts** are `256 / 100 / 156` by direct grep across `src`, `editor` and `samples` on
+  2026-09-04. Re-derive before building the Stage 2 ratchet rather than trusting this number.