@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,513 @@
+# 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.*
+
+---
+
+## 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.

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

@@ -7,7 +7,11 @@
  */
 export const TRANSFORM64_MATRIX_OFFSET: number;
 /**
- * Index of the first element of the translation (x, y, z) inside a {@link Transform64}
+ * Index of the first element of the translation (x, y, z) inside a {@link Transform64}.
+ *
+ * It is 12, which is inside the matrix: for a column-major affine matrix elements 12..14 are the
+ * translation column, and neither rotation nor scale ever touch it, so the transform keeps a single
+ * copy and the translation is that column. See {@link Transform64#translation} for what that implies.
  * @type {number}
  */
 export const TRANSFORM64_TRANSLATION_OFFSET: number;
@@ -31,7 +35,7 @@ export const TRANSFORM64_SIZE: number;
  * packed into a single `Float64Array`.
  *
  * This is the passive counterpart of {@link Transform}. There are no signals, no flags and no change
- * detection: setting the translation, rotation or scale does **not** refresh {@link matrix}, you call
+ * detection: setting the rotation or scale does **not** refresh {@link matrix}, you call
  * {@link updateMatrix} yourself once you are done mutating. What you get for that is one allocation of one
  * contiguous buffer per transform, plain array stores instead of setter dispatch, and double precision
  * throughout.
@@ -40,18 +44,29 @@ export const TRANSFORM64_SIZE: number;
  * write the buffer without going through the accessors:
  * ```
  * [ 0..15] matrix, column-major
- * [16..18] translation  x, y, z
- * [19..22] rotation     x, y, z, w
- * [23..25] scale        x, y, z
+ * [12..14] translation  x, y, z   (aliased into the matrix)
+ * [16..19] rotation     x, y, z, w
+ * [20..22] scale        x, y, z
  * ```
  *
+ * The translation is not stored twice: it *is* the matrix's translation column, elements 12..14. Which
+ * gives the staleness rule its exact shape - {@link matrix} is correct as long as the rotation and scale
+ * have not changed since the last {@link updateMatrix}. A translation-only change needs no
+ * {@link updateMatrix}, it lands in the matrix as it is written.
+ *
+ * NOTE: the flip side of that is a matrix that can describe a state that never existed. Change the
+ * translation *and* the rotation without an {@link updateMatrix} in between, and the matrix now carries
+ * the new translation under the old orientation, rather than lagging wholesale as it did when the
+ * translation had its own copy. Nothing reads such a matrix on your behalf, but if you hand it out
+ * between the two writes, that is what the receiver sees.
+ *
  * @example
  *  const t = new Transform64();
  *
  *  t.setTranslation(1, 2, 3);
  *  t.setScale(2, 2, 2);
  *
- *  // nothing has touched the matrix up to this point
+ *  // the translation is already in the matrix, the scale is not
  *  t.updateMatrix();
  *
  * @example
@@ -99,7 +114,14 @@ export class Transform64 extends Float64Array {
      * Affine transform matrix, column-major.
      *
      * Unlike {@link Transform}, this is not maintained for you - it holds whatever {@link updateMatrix},
-     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set a component.
+     * {@link fromMatrix} or {@link multiply} last wrote, and goes stale the moment you set the rotation
+     * or the scale.
+     *
+     * The translation column, elements 12..14, is shared with {@link translation} - the two are views over
+     * the same three numbers. Writing `matrix[12]` moves the transform, and setting the translation edits
+     * the matrix, so a translation-only change never leaves the matrix stale. Note the trap in the other
+     * direction: after poking the matrix directly, {@link translation} tracks it, while {@link rotation}
+     * and {@link scale} still lag until {@link updateComponents}.
      *
      * NOTE: the returned array is a live view over the transform's own buffer, but a freshly allocated
      * view on every access. Hold on to it rather than reading this property in a loop, or index the
@@ -108,12 +130,18 @@ export class Transform64 extends Float64Array {
      */
     get matrix(): Float64Array;
     /**
-     * Reads 3 elements, does not update {@link matrix}
+     * Reads 3 elements. Lands in {@link matrix} directly, since the translation is a column of it - no
+     * {@link updateMatrix} is needed for a translation-only change.
      * @param {number[]|Float32Array|Float64Array} v
      */
     set translation(arg: Float64Array);
     /**
      * Position in 3D space.
+     *
+     * This is the translation column of {@link matrix}, elements 12..14, not a separate copy: writing
+     * `translation[0]` edits the matrix, and writing `matrix[12]` shows up here. See {@link matrix} for
+     * the trap that comes with that.
+     *
      * NOTE: live view over the transform's own buffer, freshly allocated on every access
      * @returns {Float64Array}
      */
@@ -122,7 +150,8 @@ export class Transform64 extends Float64Array {
     get translation_y(): number;
     get translation_z(): number;
     /**
-     * Does not update {@link matrix}
+     * Lands in {@link matrix} directly, since the translation is a column of it - no {@link updateMatrix}
+     * is needed for a translation-only change.
      * @param {number} x
      * @param {number} y
      * @param {number} z
@@ -278,7 +307,11 @@ export class Transform64 extends Float64Array {
     setScaleScalar(s: number): void;
     /**
      * Write {@link matrix} from the current {@link translation}, {@link rotation} and {@link scale}.
-     * Nothing calls this for you, and until you do, the matrix is whatever it was before.
+     * Nothing calls this for you, and until you do, the rotation and scale part of the matrix is whatever
+     * it was before. The translation column needs no help - it is the translation, see {@link matrix}.
+     *
+     * The translation is passed in as three scalars, read before the first store, so writing it back
+     * over its own column is safe.
      */
     updateMatrix(): void;
     /**
@@ -287,6 +320,9 @@ export class Transform64 extends Float64Array {
      *
      * A matrix carrying shear cannot be described by a translation, a rotation and a scale, so shear is
      * dropped from the components. It survives in {@link matrix} until the next {@link updateMatrix}.
+     *
+     * The matrix itself is left bit-identical: the decompose reads every element before its first store,
+     * and the translation it writes is the matrix's own column copied onto itself.
      */
     updateComponents(): void;
     /**
@@ -327,7 +363,8 @@ export class Transform64 extends Float64Array {
     15: number;
     /**
      * Whether the translation is exactly [0,0,0], the rotation exactly [0,0,0,1] and the scale exactly
-     * [1,1,1]. Says nothing about {@link matrix}, which only agrees after an {@link updateMatrix}.
+     * [1,1,1]. Says nothing about the rotation and scale part of {@link matrix}, which only agrees after
+     * an {@link updateMatrix}; the translation column is the translation, so that much is covered.
      * @returns {boolean}
      */
     isIdentity(): boolean;

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

@@ -1 +1 @@
-{"version":3,"file":"Transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform64.js"],"names":[],"mappings":"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"}