@woosh/meep-engine 2.169.6 → 2.170.0

package/editor/REWORK_PLAN_2026_08.md

@@ -0,0 +1,692 @@
+# Editor Rework Plan — 2026-08 (rev 2, post adversarial review)
+
+> **Status — as built, 2026-08-15.** P0–P7 landed, including both features P7
+> demoted (layout persistence, tab-drag docking), and are shipped through the
+> submodule chain. Automated verification: the full suite is green — 1601 jest
+> suites / 9899 tests from `H:/git/moh`. Hands-on verification: three of the four
+> §4 acceptance stories walked end to end through the editor's own menus, the
+> fourth partly; what remains of them needs a *displayed* browser pane rather than
+> the headless one available here. Results and the one defect the walkthrough
+> found are in **§8**, which is now the live inventory — the follow-up notes below
+> are kept as history, and where they say something is open, §8 is authoritative.
+>
+> Deviations from the plan below:
+> the tick-driven gizmo tool tracks drag transitions instead of per-entity gizmo
+> events (the gizmo entity is destroyed/rebuilt on every attach, so entity
+> listeners cannot hold); the rendering camera resolves from the active Camera
+> component (not `graphics.camera`); LUT edits reach the emitter through a
+> module-static `onParameterLutEdited` signal consumed by a default-on
+> `ParticleEmitterRebuildProcess` (debounced) — plain-data tables carry no
+> signals; `DatGuiController` was relocated to the dat.gui vendor boundary
+> (`src/view/controller/dat/`) instead of deleted — library widgets and test
+> harnesses consume it; `EntityList`/`makeEntityDecorators` were kept (recently
+> maintained, resolvable surface); drag-a-tab docking overlay and layout
+> persistence remain future polish, panels move between zones via the tab menu.
+>
+> **Follow-up, 2026-08-15** — first hands-on session against the harness surfaced
+> four defects the phase specs could not see, all now fixed with specs
+> (`EditorCameraNavigation.spec.js`, `MeshLibraryView.spec.js`,
+> `ToolEngine.spec.js`):
+>
+> - *Nothing in the shell was clickable.* `ViewStack`'s root carries
+>   `pointer-events: none` (a game HUD lets clicks through to the 3D scene) and
+>   the shell inherited it. Only `.meep-entity-tree` had a local override, which
+>   is why the scene tree alone responded. The shell root now opts back in, and
+>   the two local overrides are gone. §D2's "no app-side stylesheets" goal makes
+>   the shell root the only place this can live.
+> - *The asset grid rendered as a diagonal staircase.* `MeshLibraryView` places
+>   cells itself and `View.position` is a transform, so in-flow cells were nudged
+>   sideways while still consuming a flow row each. Its stylesheet
+>   (`app/css/editor/MeshLibraryView.scss`) was the one editor sheet §D2's move
+>   missed. Ported into `editor/style/editor.scss`; cells are out of flow, the
+>   thumbnail has a sized placeholder so a cell claims its extent before the
+>   render lands, and the grid reflows when the library grows.
+> - *Camera navigation (§D4).* Wheel deltas arrive sign-normalized from
+>   `PointerDevice`, so a step scaled by the raw delta moved the distance 0.1% per
+>   notch; pan was unconstrained and lifted the orbit pivot off the ground, so
+>   later orbits swung about a point in the air (the strategy camera's existing
+>   `(1,0,1)` pan axis is the precedent); and the pitch clamp was symmetric,
+>   letting the camera swing under the ground plane where the scene is backfacing.
+> - *Navigation destroyed the selection.* `ToolEngine` called `tool.stop()` on
+>   every pointer release, including the right/middle buttons it deliberately
+>   withholds from tools — so ending an orbit ran `SelectionTool.stop()` and
+>   committed a marquee that never started. Release is now paired with the press
+>   that actually handed the gesture over. This is what §4 story (b), "move a tree
+>   with the gizmo while orbiting mid-edit", needed.
+>
+> Two gaps found in the same pass and **left open**, both pre-existing and outside
+> the reported scope: `focusEntity` recentres in XZ only and never derives a
+> distance, so `F` is a recentre rather than the frame-from-AABB §D4 specifies;
+> and `ToolEngine` listens for pointer-up on the canvas only, so a primary-button
+> drag released outside the viewport leaves the tool running.
+>
+> **Follow-up, 2026-08-15 (docking, rev 2)** — the fixed zones are gone. Four notes on
+> the first cut asked for things zones cannot express, so the dock is now a **tree of tab
+> groups** divided by splitters, with no privileged left/right/bottom/centre at all:
+>
+> - *Undocking was nearly impossible* — the zones tiled the dock, so every point in it was
+>   a placement. Every group now keeps a **margin** around itself (26px, capped at a fifth
+>   of the group so a small one stays droppable) where a drop leaves the layout instead.
+>   The seams between groups and the outside edge of the dock are the way out.
+> - *A floating window snapped while being moved.* Its title bar now carries two gestures,
+>   because it answers two questions: the **tab** at the left asks where the panel should
+>   go and the dock takes that over, previews and all; the **bar beside it** asks nothing
+>   and simply moves the window, live, with no docking.
+> - *An emptied section stayed.* A group that loses its last panel is **folded away** and
+>   its other half takes the room back — except the last group in the dock, which stays,
+>   empty, so there is always somewhere to drop. This replaced the "collapse the zone to
+>   zero and re-open it for the duration of a drag" of rev 1, which existed only because
+>   zones could not be created or destroyed.
+> - *Panels could not be split apart.* Dropping near one of a group's four **cardinal
+>   edges** splits it and takes that side, previewed as the half it will take, VSCode
+>   style; the middle and the tab strip dock as a tab as before. `DockSide`, and the four
+>   verbs `addPanel` / `tabPanel` / `splitPanel` / `floatPanel` — the host builds its
+>   default arrangement with the same verbs an author's drags use, so a sidebar is a group
+>   split off one side rather than a zone the layout was built around.
+>
+> The bottom `DrawerView` went with the zones: a collapsible bottom is a fixed zone by
+> another name, and what it did for the author — get a panel out of the way — is what
+> floating and folding do now. The construct itself stays in the library.
+>
+> Verified against the running editor as well as in jest (33 layout specs): the default
+> arrangement lays out to the same geometry the zones did (300 / 320 / 968×592 / 968×266);
+> all four cardinal previews are exact halves and a drop lands at exactly the previewed
+> size; a drop four pixels inside a group's edge reads "floating window" while one forty
+> pixels in reads "split right"; emptying the right-hand group folded it and gave its
+> 320+6 back to the middle; the title bar moved a window across the layout with the drag
+> overlay never appearing; a drag-created split's own divider resizes and persists; and a
+> nested tree came back byte-identical after a full page reload. An arrangement saved by
+> the zone-era build is recognised as another shape and left alone, so the editor opens on
+> the host's defaults rather than on a mistranslation.
+>
+> **Follow-up, 2026-08-15 (docking, rev 1)** — a second hands-on session found the docking
+> surface itself wanting on three counts, all now fixed. Where this note describes zones,
+> rev 2 above is what shipped:
+>
+> - *Dragging a panel showed nothing.* The drop feedback was painted on the zone views
+>   themselves — and a zone's box is covered by its own opaque tab strip and panel
+>   content, so every bit of it was underneath what the author was looking at. The
+>   earlier note below arguing an overlay would be "a second geometry to keep in step
+>   with the splitters" was wrong twice over: the feedback it defended was invisible, and
+>   the overlay does not track the splitters at all — it is handed the rectangle by the
+>   same `#planDrop` that performs the drop. Preview and outcome are now one computation,
+>   so they cannot disagree; the rectangle is exactly the space the panel will occupy,
+>   labelled with where that is (`DockDragOverlayView`, `DockDropPlan`).
+> - *Panels could not be undocked.* There was no placement outside the three zones.
+>   `DockZoneId.Float` and `FloatingPanelView` add one: released over no zone, a panel
+>   stands in a window of its own, and because that window's title bar **is** the tab it
+>   wore, dragging it back over a zone re-docks it through the very same gesture. Windows
+>   resize by a grip, come forward when reached into, and are recorded in the layout.
+>   Zones that end up holding nothing collapse, and open back up for the duration of a
+>   drag — a zone the author cannot see is a zone they cannot drop into.
+> - *The scene view was not a panel.* The dock's centre was a raw view slot the layout was
+>   built around. It is a zone like the others now, and the viewport is `DockPanel`
+>   `'viewport'` inside it: it wears a tab, it moves, it floats.
+>
+> Verified in the harness as well as in jest (34 layout specs): the preview rectangle over
+> the right zone measured 320×864 at x=1280 and the window that a drop produced measured
+> the same 360×300 at x=680 the preview had shown; the viewport floated with its live
+> canvas and came back to the centre at 968×564; a collapsed left zone opened to 300 the
+> moment a drag began; and a floating Inspector came back floating at the same place after
+> a full page reload. That reload is what turned up the one defect this pass introduced and
+> fixed — `fromJSON` can land before the host has sized the dock, and squaring a window up
+> against a dock with no extent would have destroyed where it goes.
+>
+> **Follow-up, 2026-08-15 (later)** — both of those gaps are now closed.
+> `focusEntity` frames from bounds (`editor/camera/camera_framing.js`, specced
+> pure plus through the editor), and `PointerDevice` exposes its window-level
+> release as `on.globalUp` for `ToolEngine` to pair gestures with. §8 carries
+> what is still open.
+
+Goal: bring `meep/editor` from its current broken state to a usable scene editor, scoped
+entirely to the meep package. Deliverables, in the user's words: decent UI layout
+constructs (drawers, dockable panels), the ability to **load/store and compose scenes**,
+**terrain editing**, **standard TRS via gizmos**, and **competent ParticleEmitter editing**.
+
+The Askara game layer is out of scope; the broader repo is used only for testing and
+prototyping (webpack harness entries, dev-server middleware, jest run from the moh root).
+Where a meep API change requires a matching one-line adjustment in a game-side consumer
+(`initializeEditor.js`, `GameBinarySerializationRegistry.js`, `GameBootstrap.js`), that
+adjustment is in scope as integration maintenance.
+
+> Rev 2 incorporates a three-lens adversarial review (feasibility vs codebase, scope vs
+> mandate, API design vs house style). Major corrections from rev 1: the transform model
+> (world-space `Transform`, no parent-chain math), persistent camera navigation, meep-side
+> registration of component editors and default processes (not just serialization
+> adapters), empty-scene authoring (templates, ground fallback, grid), reactive scene
+> tree, additive scene import ("compose"), save-back-to-source, repair-not-replace for
+> `TabbedView`/`SplitView`, uniform multi-select gizmo semantics, and a keymap without
+> the X-key conflict. Drag-docking and layout persistence are demoted to final polish.
+
+---
+
+## 1. Current state (condensed; full receipts in recon)
+
+The editor last saw structural work in early 2024. Since then the ECS API moved under it
+(`EntityManager.getComponent` no longer exists — component access lives on
+`EntityComponentDataset`) and the `ActionProcessor` became async. Nothing was migrated.
+Concretely, today:
+
+**Hard-broken, user-visible** (all line refs verified)
+
+| What | Where | Why |
+|---|---|---|
+| Transform gizmo throws on every drag | `tools/TransformTool.js:339,355` | calls `entityManager.getComponent` (removed) |
+| Transform undo/redo throws | `actions/concrete/TransformModifyAction.js:30,40` | same |
+| Component-remove undo broken twice | `actions/concrete/ComponentRemoveAction.js:25,30` | `apply` stores void return of `removeComponentFromEntity`; revert calls removed API |
+| Grid paint tool dead | `tools/GridPaintTool.js:37,104,110` | undefined `self`, removed API |
+| Box-select selects nothing | `tools/SelectionTool.js:286-310` | returns a never-populated array |
+| Click-pick ray malformed | `tools/SelectionTool.js:266` | passes `ray_origin.y` twice, never `.z` |
+| Paste / duplicate create components on `null` | `Editor.js:218-231` | `actions.do()` is async, never awaited |
+| Ctrl+S depends on `window.engine`, swallows errors, mutates the live scene | `Editor.js:481,485,490-495` | bare global; try/catch then downloads truncated buffer; `resetSoundEmitterTracks` runs on shared component instances (`maskedCopy` shares, not clones) |
+| Paint-tool deactivation throws | `tools/paint/TerrainPaintTool.js:280` | bare global `engine` in `finalize()` |
+| Camera navigation is modal | `ToolEngine.js:23` single active tool; `TopDownCameraControlTool` | can't orbit/pan while any editing tool is active; RMB/MMB unused (`ToolEngine.js:130-140`) |
+
+**Architectural rot**
+
+- 69 of 187 JS files (37%) unreachable from the live editor. Orphaned: the
+  `ComponentControlFactory` controller tree (31 files, includes the *good* interactive
+  particle curve/gradient editors), the `tools/v2` ECS-native gizmo port (8 files),
+  `view/node-graph` (17 files, separately alive via its own harness).
+- Two generations of everything; nothing deleted when superseded.
+- `Editor.js` imports `app/css/**` and game code, so the published `./editor/*` export
+  cannot resolve outside this repo — and `Editor.js` cannot even be imported under jest
+  (no scss handling in `jest.conf.json`). All editor styling lives in `app/css/editor/**`.
+  `dat.gui` is imported by meep but not declared in meep's package.json.
+- Three independent RAF loops outside the engine tick (`ToolEngine.js:106-122`, one per
+  selected entity in `SelectionVisualizer.js:47-53`, plus the engine's).
+- `ActionProcessor` does not serialize concurrent callers: `do()`/`doMany()`/`navigateTo()`
+  assign `__last_promise` only after awaiting the barrier; `mark()` never joins the chain;
+  `doMany`'s executor never rejects (wedges the chain on a failing action).
+- Registrations that belong to meep live game-side: serialization adapters
+  (`GameBinarySerializationRegistry.js` — ~40 of its adapters import purely from meep),
+  component type-editors (`initializeEditor.js:90-109` — `TerrainEditor`,
+  `ParticleEmitterEditor`, `MeshEditor`… are meep classes), and the three default editor
+  processes. Standalone meep gets a reflection-only inspector, invisible
+  lights/emitters/cameras, and no scene round-trip.
+
+**The transform model (established during review — implementation contract)**
+
+`Transform` components are **world-space by contract**. `ParentEntity` is a *lifecycle*
+tree only (`ParentEntity.js:2`, `serializable = false`); the spatial hierarchy is
+`TransformAttachment`, whose system composes parent × local and **writes the result into
+the child's `Transform`** (`TransformAttachmentSystem.js:51-56`). Consequences:
+
+- A gizmo places itself at, and writes to, the entity's own `Transform`. No parent-chain
+  composition exists or is needed. The v2 gizmo's identity-parent assumption is correct.
+- Editing an entity that carries a `TransformAttachment` must write through to
+  `attachment.transform` (world delta converted by the parent's world `Transform`),
+  otherwise the attachment system snaps it back.
+- `TransformAttachment` has no registered serialization adapter — serialized scenes
+  contain plain world transforms.
+
+**Solid, to build on** — `View` lifecycle (`link`/`unlink`, `bindSignal`, observable px
+`size`/`position` — layout fully computable in jsdom; `addChild` asserts unlinked child,
+`removeChild` unlinks, and asserts are LIVE under jest), `EmptyView`, `ListView`,
+`VirtualListView`, `LabelView`/`ButtonView`/`CheckboxView`/`NumberController`/
+`DropDownSelectionView`/`CanvasView`, tooltip manager, `DraggableAspect` (+spec, the
+jsdom drive pattern), `DomSizeObserver`, `ActionProcessor` + marks, `BaseProcess`/
+`ProcessEngine` lifecycle, `type_editor_registry` + `createObjectEditor` pipeline,
+symbolic displays (`EditorEntity.referenceEntity` dereferencing), terrain brush math +
+`ModifyPatchSampler2DAction` family, `tools/v2/TransformControls` (needs snap fix +
+consumer; `dispose()` is fine — rev 1's "listener leak" item was wrong), binary scene
+format + `engine.storage`, `EngineHarness`, `ViewStack` push/pop hand-over (verified
+mechanically sound for the shell).
+
+---
+
+## 2. Design decisions
+
+**D1 — Repair first, then rebuild on top.** Phase 0 makes the existing editor
+functional and testable; later phases replace layers. No big-bang rewrite.
+
+**D2 — Self-contained editor.** No `app/**` or `model/game/**` imports in the **live
+editor import closure** (pre-existing `meep/src` offenders like `SerializedScene.js:1`
+are out of scope but must not be pulled into editor code — editor persistence gets its
+own load path and never imports from `SerializedScene.js`). All editor CSS moves to
+`meep/editor/style/` — global partials with semantic class names, one `editor.scss`
+entry; **logic modules never import styles** (jest has no scss handling);
+`HierarchicalEntityListView` migrates off its `.module.scss` (the only one in meep) so
+one pattern remains. Theming via CSS custom properties: framework tokens (`--meep-*`)
+declared with fallbacks in `src/view/layout/layout.scss` (self-contained), editor theme
+overrides them in `editor.scss`. `dat.gui` leaves live editor paths. Meep-side
+registration hoists (mirroring the serialization one):
+`registerEngineComponentEditors(registry)` and default-process registration in
+`Editor.initialize()`; `initializeEditor.js` keeps only game components (pruned as
+integration maintenance).
+
+**D3 — Layout library at `src/view/layout/`** (framework surface, editor is first
+consumer). House style: typed classes, class fields, `#private`, `List`-driven children,
+`Observed*` state, `-View` suffix for views.
+
+- `SplitView` — **repaired and relocated** (`editor/view/v2/SplitView.js` becomes a
+  re-export shim; the `:95` vertical-split bug is fixed in P0 before relocation).
+  Enhanced: draggable 6px divider (`DraggableAspect`), sizing model = **divider offset
+  in px anchored to one side** with min/max clamps (fraction accepted as initializer
+  only — dock zones keep px width while the center flexes; no dual fraction/px model).
+  Back-compatible `from({a,b,type,fraction})` and setters.
+- `TabbedView` — **repaired in place** (`src/view/common/TabbedView.js` constructs its
+  containers but never adds them — two-line fix), extended with closable tabs. No new
+  near-duplicate widget. `TabDefinition` stays the typed item class.
+- `DrawerView` — edge-anchored collapsible container, `ObservedBoolean` open state,
+  header toggle. **Instant toggle** (no CSS transitions — they'd desync the DOM from
+  the px model; model-driven animation is later polish).
+- `DockPanel` (model class: `id`, `title: ObservedString`, `view`, `closable`) and
+  `DockLayoutView` — center view + left/right/bottom zones, each zone a `TabbedView`
+  of panels, zone sizes via internal `SplitView`s. Panel moves between zones via a
+  typed API (`movePanel(panel, zone)`) surfaced as a per-tab menu. Panel ids exist
+  **solely** for layout persistence matching; no id→factory map, no `getPanel(string)`
+  lookup API. Moving a panel is an unlink→relink cycle (enforced by `View` asserts);
+  panels hold models, not DOM state.
+- **Deferred to P7 polish:** drag-a-tab-between-zones with drop-zone overlay, and
+  layout persistence (`DockLayoutView.toJSON/fromJSON` via `engine.storage` under a
+  host-supplied key — not raw localStorage). Fixed zones + menu moves carry the
+  mandate's daily workflow.
+
+**D4 — Shell.** `EditorShellView` (`editor/view/shell/`) on `DockLayoutView`:
+
+- center: viewport panel hosting `engine.gameView` (`ViewStack` hand-over as today,
+  formalized in `link`/`unlink`);
+- left: Scene panel — `HierarchicalEntityListView` made **reactive** (subscribes to
+  dataset entity/component events, patches via its existing diff; `#child_map` cleared
+  on dataset swap) and **wired to selection** (click → `Selection*Action`s, ctrl-click
+  multi-select, double-click → frame), plus a filter box and an entity **template
+  menu**: Empty, Mesh, Light, Camera, ParticleEmitter (one default layer), Terrain —
+  every template attaches `Transform` + `Name`;
+- right: Inspector (`EntityEditor`, kept);
+- bottom drawer: Assets panel (revived `MeshLibraryView`, drag-to-place with **y=0
+  ground-plane fallback** when the scene has no terrain — `prepareMeshLibrary.js:88`
+  currently dereferences `obtainTerrain` unguarded) and Processes panel;
+- top strip: tool buttons, undo/redo, scene menu, native `ToolSettingsView` (rewritten
+  — the dat.gui one's `typeof x === object` bug means settings were never editable).
+
+`Editor.js` becomes an ES class; keymap → `EditorKeyMap.js`; clipboard →
+`editor/clipboard.js`; persistence → `editor/persistence/`. **Preserved public
+surface** (inventoried from real consumers): `enableEditor`, `editor.engine`,
+`editor.actions`, `editor.selection`, `editor.toolEngine`, `editor.processEngine`,
+`editor.type_editor_registry`, `editor.meshLibrary`, `editor.cameraEntity`,
+`initialize/attach/detach`, `isEditorEntity`-equivalent filtering. NumLock toggle stays.
+
+**Camera navigation becomes persistent** (this was the largest usability defect):
+while the editor is attached, an always-on editor camera controller handles RMB-orbit,
+MMB-pan, wheel-zoom; tools own LMB only (`ToolEngine` already filters primary-button).
+The modal `camera_control` tool is retired; `G` is freed. Brush size moves off the
+wheel to `[`/`]` + settings. A ground **grid display process** (default-on) gives empty
+scenes a spatial reference. `F` / tree-double-click frames the selection (camera target
++ distance from selection AABB).
+
+Final keymap (spec'd; X-delete conflict from rev 1 resolved): `W/E/R` gizmo mode,
+`Q` world/local toggle, `F` frame selection, `X`/`Delete` delete selection,
+`Ctrl+Z/Y` undo/redo, `Ctrl+C/V` copy/paste, `Shift+D` duplicate, `[`/`]` brush size,
+`Ctrl+S` save. Marquee-vs-transform switching lives on the toolbar (`1`/`2` keys).
+
+**Headless tolerance:** `Editor.attach()`/`ToolEngine.startup()` must run under jsdom
+(guard the pointer device and viewport wiring on `engine.graphics` availability) so
+editor-level specs are possible. `ToolEngine`'s RAF loop and `SelectionVisualizer`'s
+per-entity RAFs are replaced by engine-tick-driven updates.
+
+**D5 — Scene I/O** (`editor/persistence/` + one engine-side registration module).
+
+- `populateEngineSerializationRegistry(registry)` (new, `src/engine/ecs/storage/`;
+  name follows `populateSopraSerializationRegistry` precedent) — registers the
+  engine-side adapters **and upgraders** that today only the game list carries
+  (verified assemblable purely from meep imports). Registry semantics are first-wins
+  (`BinarySerializationRegistry.js:71-77` warns and keeps the first; upgraders dedup
+  by instance identity), so `GameBinarySerializationRegistry` is **pruned to delegate**
+  to this function for engine types (integration maintenance) — no double
+  registration, no warn-spam, no divergent duplicate upgrader nodes.
+- Export, uniform-flow (no hook arrays): `buildExportDataset(engine) → ecd` (masked
+  copy; strip `EditorEntity`-marked entities; **clone** the camera component to set
+  `active=true` — never mutate shared instances) and `serializeDataset(engine, ecd) →
+  EncodingBinaryBuffer` (big-endian; **rethrows** on failure). `exportSceneToBuffer(engine)`
+  composes the two. A host wanting extra scrubbing (e.g. the game's sound-track reset)
+  calls the primitives around its own step.
+- `importSceneFromBuffer(engine, arrayBuffer)` — fresh dataset with the engine's
+  component type map, executor-driven deserialization task, then scene swap with the
+  explicit `SceneManager` discipline (remove-then-recreate the editing scene; unique
+  name; editor detaches before the swap and reattaches after).
+- `importSceneAdditive(engine, arrayBuffer)` — **"compose scenes"**: deserialize into
+  a scratch dataset, then copy into the live scene with **fresh entity ids** (raw ids
+  from the file would graft components onto existing entities —
+  `BinaryBufferDeSerializer.js:170-179`). Undoable as one mark.
+- `SceneSlotManager` — named slots over `engine.storage` (IndexedDB in browser;
+  `InMemoryStorage` in specs) with a typed `SceneMetadata` class (`toJSON/fromJSON`),
+  following the `GameSaveStateManager` shape without its game-isms. Plus: file export
+  (`downloadAsFile`), file import (`<input type=file>` → ArrayBuffer), URL load, and
+  **save-to-URL** via a dev-server PUT endpoint (a small `devServer.setupMiddlewares`
+  addition in moh's `webpack.config.js` writing under `app/data/levels/**` — dev-only
+  repo tooling, explicitly permitted) so the load→edit→save-back loop closes.
+- Scene panel UI: New (template scene: camera + sun + ambient — a fresh dataset would
+  otherwise export camera-less), Open (slot / file / URL), Save / Save As, Export,
+  Import, Merge.
+
+**D6 — Gizmos: adopt `tools/v2`, retire the surrogate bridge.**
+
+- Fix v2 translation snap (operates on `_tempTransform`, never on the entity-id
+  `object` — `TransformControls.js:361-409`); reset `dragging` on `detach()`.
+- `TransformToolV2` (registered as `spatial_transform`): gizmo attaches at the primary
+  (last) selection's `Transform` (world by contract, no conversion). **Uniform
+  multi-select semantics across all modes**: per-entity snapshot on drag start;
+  translate applies the shared world delta to every selected entity; rotate/scale
+  apply the same delta about **each entity's own pivot in its own frame** (matches the
+  node-graph precedent of dragging whole selections; no mode asymmetry). Drag end
+  emits one mark + per-entity `TransformModifyAction`s (fixed: dataset API, no
+  `oldState` re-capture in `apply`). Entities carrying `TransformAttachment` get
+  write-through to `attachment.transform`; if that proves deep, they are excluded from
+  gizmo editing with a visible notice — never silently wrong.
+- Snapping (translate increment, rotate degrees) + space toggle in tool settings/keymap.
+- Delete legacy `TransformTool.js` + vendored `three/TransfromControls.js` after the
+  keymap switches to v2 `TransformMode` (legacy `TransformerMode` import at
+  `Editor.js:70` dies with the keymap extraction).
+
+**D7 — Terrain.**
+
+- P0 one-liners: `finalize()` bare global; bicubic `(tY,tY)`→`(tX,tY)`; splat
+  `depth===1` handled as "no redistribution targets" (uniform branch, not a guard);
+  the `u1` width/height mixup — the UV-rect computation is **extracted as a pure
+  function** and specced directly (black-box through live terrain machinery would
+  need the tile worker; the pure function is the honest test seam).
+- One `TerrainTexturePaintTool` with `settings.layer` + swatch picker rendered from
+  `TerrainLayers` (count/get/diffuse verified present); delete the four hardcoded
+  instances. Brush radius/strength editable via the native settings view; `[`/`]`.
+- Per-stroke QuadTree rebuild for entity height-follow (index is stale today).
+- "New terrain" template (allocated height sampler, one layer, splat filled) — a bare
+  `new Terrain()` from the add-component dropdown is not a functioning terrain.
+- Delete dead-and-broken `PatchTerrainTextureAction.js`.
+
+**D8 — Particles: revive the good editors into the live pipeline.**
+
+- `ScalarParameterLUTController` / `ColorParameterLUTController` move to
+  `editor/view/particles/` and become the guts of `ParameterLookupTableEditor`
+  (which keeps its trackName gate: scale/color get editors, other names stay hidden).
+  Canvas 2d context acquired **lazily at `link()`** (jsdom-tolerant); LUT mutation
+  logic extracted into plain functions over `ParameterLookupTable` (spec'd without
+  canvas).
+- `rebuildParticleEmitter(ecd, entity)` — the remove→clear-flags→
+  `registerLayerParameters`→`build`→`initialize`→`computeBoundingBox` dance from the
+  orphaned controller — invoked on structural edits (layer add/remove, `imageURL`
+  change) and exposed as a Rebuild button.
+- Fixes: `emisionBounds`→`emissionBounds` transient typo; `ParameterTrackEditor`
+  imports real `ParticleParameters`; symbolic-display `removeLayer` implemented
+  (currently orphans gizmo geometry).
+- Non-goals: sprite-atlas picker, velocity-cone handles, parameters beyond
+  scale/color (engine has exactly those two).
+
+**D9 — Cleanup.** Delete: `ComponentControlFactory` + dead controller tree (minus
+revived pieces; `buildGridObstaclePreview` moves next to its consumer), 0-byte
+`ViewManagementSystem.js`, old `EditorView` + `ViewManager` (superseded by the shell),
+legacy `TransformTool` + vendored three controls, `PatchTerrainTextureAction`,
+`makeStoryTriggerSetAreaDisplay` (game-coupled, unresolvable import), the
+`.stories.js` + `@storybook` import, `controls_v2` TS stubs — **plus each deleted
+module's committed `.d.ts`/`.d.ts.map`**. These removals are acknowledged as breaking
+for the published `./editor/*` surface; that is the rework mandate (the game-coupled
+files never resolved outside this repo anyway). Truly generic widgets are repaired,
+not removed (`SplitView`, `TabbedView`). `view/node-graph/**` untouched. GridPaintTool
+is **kept and fixed** (exported, referenced, trivial fixes). `OptionsView`'s dat.gui
+is game-facing — out of scope.
+
+**D10 — Launch.** `editor/prototypeEditorShell.js`: `EngineHarness` bootstrap +
+`ShadedGeometrySystem`, `TransformAttachmentSystem`, `ParentEntitySystem` (the v2
+gizmo builds entities carrying those components — `EngineHarness` does not register
+them), `populateEngineSerializationRegistry`, seeded mesh library + demo emitter +
+terrain, editor enabled. Webpack entry line added per repo convention.
+
+---
+
+## 3. Phases
+
+Each phase: jest green from `H:/git/moh`, then a meep commit. Submodule bumps
+(meep → mir-engine → moh) at milestones or at the end.
+
+**P0 — Repairs + foundations** (existing editor functional; `Editor.js` importable)
+1. `Editor.js` de-coupling: the two scss imports and `resetSoundEmitterTracks` move
+   game-side (`initializeEditor.js` / bootstrap — integration maintenance); the
+   Ctrl+S sound reset is dropped (it mutates the live scene); bare-global fix;
+   rethrow on serialize failure; await the action sequences in paste/duplicate/
+   delete; `disabledSystems` `window.name` bug; `lastTool` null crash.
+2. `ActionProcessor`: serialize **all** entry points (`do`/`doMany`/`undo`/`redo`/
+   `navigateTo`/`mark`) through one rejection-tolerant promise chain (tail
+   swallowed-on-await, never wedged; `doMany` rejects on action failure); clear
+   future marks on divergence. Specs: sync back-to-back ordering, failing action
+   doesn't wedge, marks consistent after divergence.
+3. Dataset-API migration: `TransformModifyAction` (+ no `oldState` re-capture),
+   `ComponentRemoveAction` (capture component before remove; revert via dataset),
+   `TransformTool` minimal fix (functional until P4), `GridPaintTool` (+`self`).
+4. `SelectionTool`: marquee population (frustum test over dataset), ray typo.
+5. Terrain one-liners + pure UV-rect extraction (D7).
+6. `SplitView.js:95` fix (pre-relocation).
+7. `populateEngineSerializationRegistry` + round-trip spec (dataset with Transform/
+   Mesh/Terrain/Light/Camera/Name/Tag/ParticleEmitter/SoundEmitter/Water…); game
+   registry delegates (prune engine entries).
+8. Specs: transform action round-trip on real dataset, component remove/undo, paste
+   creates components on real entities, patch-rect regression, splat depth-1.
+
+**P1 — Layout library** (`src/view/layout/`)
+- `SplitView` (relocated + divider + px-anchor model + shim), `TabbedView` repair
+  (+closable), `DrawerView`, `DockPanel` + `DockLayoutView` (fixed zones, typed move
+  API + menu), `layout.scss` (self-contained, `--meep-*` tokens; imported by the P2
+  editor entry — unverifiable visually until P2, accepted).
+- Specs (jsdom): divider drag via synthetic events (DraggableAspect pattern), min/max
+  clamps, anchor-side px retention on resize, TabbedView activate/close/reorder,
+  DockLayout move-between-zones with unlink/relink verified, Drawer state, SplitView
+  back-compat (`from({fraction})`).
+
+**P2 — Editor core modernization + shell** (two commits)
+- *P2a — core*: `Editor` ES class + extraction (keymap with the final table above,
+  clipboard, persistence seam); persistent camera navigation (RMB/MMB/wheel,
+  `camera_control` retired); `ToolEngine` tick-driven (no own RAF; headless guards on
+  `engine.graphics`); `SelectionVisualizer` single tick-driven update;
+  `registerEngineComponentEditors` + default processes registered meep-side
+  (`initializeEditor.js` pruned to game components).
+- *P2b — shell*: `EditorShellView` on `DockLayoutView` (viewport/Scene/Inspector/
+  Assets-drawer/Processes/top strip); reactive + selection-wired
+  `HierarchicalEntityListView` (+filter, off module.scss); entity template menu;
+  native `ToolSettingsView`; `editor/style/editor.scss` + partials (app-css editor
+  styles obsolete); grid display process; frame-selected (F / double-click);
+  y=0 mesh-drop fallback; `prototypeEditorShell.js` harness + webpack entry.
+- Specs: keymap dispatch, camera-controller attach/detach symmetry, tree reacts to
+  dataset create/remove and drives selection actions, templates build the advertised
+  components, `Editor.attach()`/`detach()` round-trip headless (graphics-less).
+- Browser: shell renders; dock/resize/collapse; viewport live; tree↔selection↔
+  inspector loop; place mesh on empty scene.
+
+**P3 — Scene I/O**
+- Export primitives + `importSceneFromBuffer` (scene-swap discipline) +
+  `importSceneAdditive` (scratch dataset + id remap) + `SceneSlotManager`/
+  `SceneMetadata` + file/URL/save-to-URL endpoints + dev-server PUT middleware
+  (moh webpack, dev-only) + Scene panel UI (New-template/Open/Save/Save As/Export/
+  Import/Merge).
+- Specs: export strips editor entities + activates a cloned camera without touching
+  the live dataset; import swap at dataset level + editor detach/reattach; additive
+  import remaps colliding ids (verified against a populated dataset); slot round-trip
+  over `InMemoryStorage`; New-template contents (camera + lights present).
+- Browser: load `data/levels/first/level.bin` (2.4 MB), edit, save to URL, reload,
+  verify; merge a second scene additively.
+
+**P4 — Gizmos**
+- v2 snap fix + `detach()` drag-state fix; `TransformToolV2` with uniform
+  multi-select semantics + undo marks; `TransformAttachment` write-through (or
+  explicit exclusion with notice); settings (snap, space); delete legacy tool +
+  vendored controls; keymap on v2 `TransformMode`.
+- Specs (jsdom — constructor needs a DOM element; drive via pointer structs,
+  `button === -1` for moves): translate/rotate/scale on a real dataset with
+  `ShadedGeometry`/`TransformAttachment`/`ParentEntity` types registered; undo
+  restores; multi-entity translate + per-pivot rotate; snapped translate lands on
+  increments.
+- Browser: handle drags, W/E/R/Q, snapping.
+
+**P5 — Terrain tools**
+- Single splat tool + layer swatch picker; brush settings live (native view from
+  P2); `[`/`]`; per-stroke QuadTree rebuild; "New terrain" template.
+- Specs: weight-stamp partition preserved across layers (incl. depth 1), layer-picker
+  model, height-follow samples `(tX,tY)`, template terrain is functional
+  (sampler allocated, layer present).
+- Browser: sculpt + paint on harness terrain; undo/redo strokes; create terrain from
+  template in an empty scene and paint it.
+
+**P6 — Particle editing**
+- LUT ops module + revived controllers (lazy 2d context) wired into
+  `ParameterLookupTableEditor` (trackName gate kept); `rebuildParticleEmitter`
+  auto-invocation + button; the three small fixes (D8).
+- Specs: LUT mutation ops; rebuild leaves a live emitter (flags/bounds sane);
+  `emissionBounds` hidden; non-scale/color tracks stay hidden (no crash).
+- Browser: author a campfire from scratch — create emitter entity from template,
+  set texture, shape curve + gradient, watch the live system change on rebuild.
+
+**P7 — Polish + cleanup**
+- D9 deletion list (+ their committed `.d.ts`); dat.gui out of live paths; RAF
+  audit (none outside engine tick); *optional if pillars are done:* drag-docking
+  overlay + layout persistence via `engine.storage`; update this doc to as-built;
+  full-suite jest; final browser walkthrough of the four acceptance stories; final
+  commits + bumps.
+
+## 4. Acceptance stories (exit criteria, run in the browser before "done")
+
+(a) Start the harness with an **empty scene**: place 5 meshes (drag from Assets onto
+the y=0 grid), arrange with gizmos, save to a slot, reload the page, reopen, continue.
+(b) Open `data/levels/first/level.bin`, move a tree with the gizmo while orbiting the
+camera mid-edit, repaint a hill (height + splat), save back to the same URL, reload,
+verify.
+(c) Author a campfire emitter from scratch on a fresh scene (template entity → texture
+→ curve → gradient → rebuild) with the emission-shape symbolic display visible.
+(d) Build a small diorama: terrain from template, water, two lights, meshes; arrange
+using panels/drawers as needed; undo/redo mixed edits across tools survives.
+
+## 5. Testing rules
+
+Jest from `H:/git/moh` (root `jest.conf.json`; jsdom for view/editor specs; asserts
+are live). Real objects only (real datasets, components, `ActionProcessor`;
+`InMemoryStorage` is a real engine class, not a mock); black-box assertions;
+no call-count/private-path assertions. Canvas rendering is not asserted in jest —
+mutation logic is factored out; rendering verified in-browser via the harness.
+
+## 6. Risks
+
+| Risk | Mitigation |
+|---|---|
+| P2 is the biggest phase and could stall | split into P2a/P2b commits; the old shell remains functional until P2b lands |
+| Dock complexity balloons | fixed zones + menu moves first; drag overlay demoted to P7 optional |
+| v2 gizmo hides more unknowns | legacy tool stays functional (P0-fixed) until P4 specs pass |
+| Engine/game registry divergence | single engine list, game delegates; spec asserts every serializable harness component has an adapter |
+| `TransformAttachment` write-through is deeper than expected | fallback: exclude attached entities from gizmo editing with a visible notice |
+| Scene-swap leaves editor bound to a dead dataset | editor detach/reattach around swaps; headless attach makes this spec-able |
+| Dev-server PUT middleware is repo-side | dev-only, guarded to `data/levels/**`; documented as testing infrastructure |
+
+## 7. Out of scope (this pass)
+
+Node-graph integration; stroke coalescing; free-floating windows; nested docks;
+group-pivot rotate/scale about a common center; Transform64; sprite-atlas picker;
+velocity-cone handles; simulation-step authoring UI; mesh-library categories/search;
+object-v2 serializer adoption; `OptionsView` dat.gui migration; compiled editor.css
+in `build/` for no-sass consumers (release-tooling note: worth adding to `release.sh`
+later); pre-existing `meep/src` → game imports outside the editor closure
+(`SerializedScene.js`, `hideEntityGracefully.js`, …).
+
+## 8. Outstanding work (inventory, 2026-08-15)
+
+Everything the plan calls a pillar is built, specced and shipped; so are both P7
+features it demoted, and so are the sweepings. Three of the four acceptance stories
+are walked and the fourth is partly done — what remains of them needs a displayed
+browser pane rather than a headless one.
+
+> An earlier revision of this section claimed the terrain paint tools "latch Running
+> forever" for want of a `super.stop()`. That was wrong — neither overrides `stop()`, so
+> both inherit `Tool.stop()` and reset correctly. The real defect was narrower and worse,
+> and is recorded under "closed" below.
+
+**(1) Acceptance stories — three of four walked, one partly.** Driven through the
+editor's own menus in the browser harness on 2026-08-15, not through internals:
+
+- **(a) PASS.** New scene, five entities placed from the `+ Entity` template menu
+  (3 meshes, light, emitter), arranged, `Scene ▸ Save to slot`, **full page reload**,
+  `Scene ▸ Open slot`. All eight entities and every position returned exactly; editor
+  stayed attached, one shell.
+- **(b) PASS.** `Scene ▸ Open URL` on `data/levels/first/level.bin` (2.4 MB) → 68
+  entities, editor attached. Moved a prop to a marker position, `Scene ▸ Save to URL`
+  over the dev-server PUT endpoint (2 381 217 bytes written), **page reload**, reopened:
+  68 entities, prop still at the marker. Written to `data/levels/dev/` rather than over
+  the project's own level — the loop is identical and the real asset is left alone.
+- **(c) PARTLY.** The authoring surface is verified: the emitter template builds a
+  live one-layer emitter, and its inspector exposes the whole parameter set (Image URL,
+  Particle Life/Size/Rotation, Emission Shape/From/Rate, Parameter Tracks) with **both
+  revived LUT editors rendering** — a 220×90 curve canvas and a 220×40 gradient canvas.
+  What is *not* verified is dragging curve and gradient control points and watching the
+  live system change: that needs eyes on a displayed pane, not a headless one.
+- **(d) PASS (core).** Mixed-tool undo/redo over a scene built from the terrain, light
+  and mesh templates: undo peels the sequence back in order (mesh, then light), redo
+  restores both, and undoing past the terrain returns exactly to the `newScene` baseline.
+  Terrain *painting* strokes were not exercised — same headless limitation as (c).
+
+The walkthrough earned its place: it found one real defect, now fixed — the **inspector
+came up blank when its tab was brought forward** with an entity already selected, because
+the component rows were only built on `model.onChanged` and a background tab is unlinked.
+
+**(2) Repo-side sweepings** (none affect the running editor):
+
+- `src/view/elements/button/ButtonView.stories.js` still imports `@storybook/html` and
+  `@storybook/addon-actions`. D9 listed it for deletion; it is the only storybook consumer
+  left in meep, and `@storybook/*` is in neither `dependencies` nor `devDependencies`.
+  **Done** — deleted; the host has no storybook config either, so nothing could render it.
+- `dat.gui` is imported by meep (`src/view/controller/dat/**`, `src/view/controller/controls/**`,
+  `src/engine/options/OptionsView.js`, several `prototype*.js`) but was declared nowhere.
+  **Done** — declared as an *optional* peer dependency alongside `three`. Optional because
+  D9's goal is met: no editor or engine path touches dat.gui, so a consumer that never
+  imports those view modules should not be told to install it.
+- Orphaned app-side stylesheets in moh now that §D2's move landed. **Done** — every editor
+  sheet under `app/css/editor/` is gone: the 14 nothing imported (`MeshLibraryView.scss`,
+  `tools/ToolView.scss`, `controllers/**`), plus `EditorView.scss` and the
+  `EntityListView.scss` it `@import`ed, once their last consumer went. That consumer was
+  `prototypeSpriteSystem.js` — itself an unreferenced prototype that reached across the
+  package boundary for `model/game/initializeEditor.js` — deleted on the owner's call.
+  **No meep module imports `app/css/editor` any more, which closes §D2's styling goal.**
+  `app/css/editor/node-graph/**` stays: the node-graph harness imports it, and node-graph
+  is untouched by this rework.
+
+**Closed since this inventory was written:** `F` frames the selection from its world
+bounds instead of recentring on it (`editor/camera/camera_framing.js`; bounds are
+geometry unioned with the entity origin, distance fits the circumscribed sphere, and
+an entity with no geometry frames its symbolic-display helper rather than collapsing
+onto the pivot, and a terrain frames the extent of its grid rather than its corner), and
+a gesture released outside the viewport now ends — `PointerDevice` publishes its
+window-level release as `on.globalUp` and `ToolEngine` pairs releases with that instead
+of the element-scoped `up`.
+
+Also closed: **both P7 features.** The dock arrangement now survives a reload —
+`DockLayoutView.toJSON`/`fromJSON`, matched by `DockPanel#id` and tolerant of ids the
+running build no longer has (or never had), saved through `EditorLayoutStore` over
+`engine.storage` under a per-host key on a new `rearranged` signal, debounced. And a
+panel is docked by dragging its tab, with the per-tab menu kept for anyone who would
+rather not drag. Both verified in the harness, not only in jest: a divider dragged to 460
+reopens at 460 after a page reload, and the Scene tab dragged into the right zone lands
+there and is in storage 400ms later.
+
+> The first cut of the drag drew its feedback on the zones themselves, where their own
+> opaque content covered it; see the docking follow-up in the header for what replaced it.
+
+Also closed: **`GridPaintTool` could never paint.** Its `update()` gates on `isRunning()`
+while its `start()` override never called `super.start()`, so the state never left Ready
+and the paint branch was dead on every tick — a registered, toolbar-reachable tool that
+did nothing. `TerrainPaintTool` gates on the same predicate and worked only because its
+subclasses remembered the super call. Since two of five tools got it wrong, the missing
+calls were not added back: `Tool` now owns the transition and subclasses implement
+`handleStart`/`handleStop`, so the state cannot be stranded. Hook ordering is specced —
+`handleStart` runs already-Running (that is what makes the first tile land), `handleStop`
+runs still-Running (the marquee it commits belongs to the closing gesture), and `stop()`
+restores Ready from a `finally` so a failed commit cannot poison later gestures. Verified
+live as well as in jest: in the harness the marquee tool now reports Running only for the
+duration of its own gesture, including one released over a panel and one whose stop hook
+throws.
+
+Both camera/gesture fixes were verified against the running harness, not only in jest: framing the harness
+terrain targets its middle at the distance that fits its circumscribed sphere to the
+camera's field of view, framing a light lands on the light at symbol distance, and a
+marquee begun in the viewport and released over the scene-tree panel closes instead of
+staying open into the next press.
+
+**Not outstanding, recorded so it is not re-litigated:** the D9 deletion list is fully
+executed (`ComponentControlFactory` tree, `ViewManagementSystem.js`, `EditorView`/`ViewManager`,
+legacy `TransformTool` + vendored three controls, `PatchTerrainTextureAction`, and every
+committed `.d.ts`/`.d.ts.map`); the only `.module.scss` in meep is gone; no `requestAnimationFrame`
+survives in the editor outside `prototypeObjectEditor.js` (a standalone prototype);
+`populateEngineSerializationRegistry` is registered meep-side and `GameBinarySerializationRegistry.js:53`
+delegates to it; the dev-server PUT endpoint is in place and path-confined to `app/data/levels/**`.