@vgai/editor 0.2.0

package/src/authoring/ui-authoring-adapter.ts

@@ -0,0 +1,325 @@
+/**
+ * UIAuthoringAdapter — drives the UI editor through the SAME format-neutral
+ * {@link AuthoringAdapter} contract the 3D editor uses (K6). It wraps a
+ * {@link UIEditStore} (the .vscn `ui` tree) and exposes hierarchy / selection /
+ * inspector / LAYOUT (K7, NOT transform — UI has no 3D gizmo) / structure /
+ * persistence / undo. `object3D` is always null (UI nodes are DOM, not Object3D);
+ * the editor's UI selection surface is the DOM overlay, parallel to the 3D viewport
+ * (architectural_decision §C).
+ *
+ * It is registered via `setActiveAuthoring` directly by the standalone harness
+ * (`ui-editor/harness.tsx`), and — as a `kind: 'scene-ui'` child of the edit-mode
+ * `CompositeAuthoringAdapter` — by `authoring/edit-mode-authoring.ts` (C3,
+ * docs/unified-world-editor/26-unified-editor-spec.md §4 C3): the panel-swap into
+ * the main editor this doc comment used to call "the remaining integration" has
+ * landed — a UI node is now a layer node under its owning world in the ONE
+ * hierarchy, and this adapter's `pickable` (below) drives B4 click-select for it.
+ */
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  LayoutProvider,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  SelectionProvider,
+  StructureProvider,
+} from '@engine/adapter';
+import type { UINode } from '@engine/scene/schema';
+import { UIAnimationController } from '@vgai/scene-ui/animation';
+import { findNode, getNodePath, walk } from '../ui-editor/node-ops';
+import { hitTest } from '../ui-editor/react-store';
+import type { UIEditStore } from '../ui-editor/ui-edit-store';
+import type { SourceWriteBackend } from '../ui-source/source-write-backend';
+
+/** C3 — the shell's generic "Create ▸" kind list (`structure.creatableKinds`
+ *  below): every kind `defaultNodeForKind` (`ui-edit-store.ts`) seeds a
+ *  sensible default for. Containers (`box`/`panel`/`grid`) can themselves be
+ *  a `create` target; kept intentionally smaller than the harness palette's
+ *  full set (`ui-editor/palette.tsx`) — that richer picker stays harness-only. */
+const CREATABLE_KINDS: ReadonlyArray<{ kind: string; label: string }> = [
+  { kind: 'box', label: 'Box' },
+  { kind: 'panel', label: 'Panel' },
+  { kind: 'grid', label: 'Grid' },
+  { kind: 'text', label: 'Text' },
+  { kind: 'button', label: 'Button' },
+  { kind: 'image', label: 'Image' },
+  { kind: 'input', label: 'Input' },
+  { kind: 'toggle', label: 'Toggle' },
+  { kind: 'slider', label: 'Slider' },
+  { kind: 'progress', label: 'Progress' },
+];
+
+function toEditorNode(node: UINode, parentId: string | null): EditorNode {
+  return {
+    id: node.id as string,
+    label: node.name,
+    kind: node.kind,
+    parentId,
+    childIds: (node.children ?? []).map((c) => c.id as string),
+    flags: { locked: node.locked ?? false },
+  };
+}
+
+export class UIAuthoringAdapter implements AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities;
+  /**
+   * T3.2 slice 3: the source-write flush seam (design §4). Absent ⇒ no dev-server
+   * backend in this session (a hosted/browser build) — see `../ui-source/source-write-backend.ts`.
+   *
+   * NOT folded into `capabilities.persist` (deliberately — reported as a premise
+   * mismatch in the T3.2 slice 3 report): `EditorStore._activePersistence()` gates
+   * ALL autosave for whichever adapter is active on `capabilities.persist`,
+   * including the SEPARATE, already-real ui-tree persistence path (`onCommit` →
+   * `EditorStore.setSceneUI` → the normal `.vscn` autosave, unconditional today).
+   * Flipping `capabilities.persist` off when no source-write backend exists would
+   * silently disable THAT working path too, in every hosted/no-dev-server build —
+   * not the intended effect. `capabilities.persist` therefore stays `true`
+   * (matching pre-slice-3 behavior); backend absence is instead surfaced honestly
+   * through `persistence.destination` below.
+   */
+  private readonly writeBackend: SourceWriteBackend | undefined;
+
+  /**
+   * C3 (D12/B4) — the live viewport DOM element to hit-test against,
+   * attached once the unified editor's scene-UI design-time layer mounts
+   * (`authoring/scene-ui-layer.ts`) and detached on its teardown. `null` in
+   * the standalone harness (which never attaches one) and briefly between
+   * composite-install and layer-mount — `pickable.pick` degrades to `null`
+   * either way, never throws.
+   */
+  private _pickSurface: HTMLElement | null = null;
+
+  /**
+   * D4 (spec27 §6 D4, layer-tree "lock" toggle) — SESSION-LOCAL, never
+   * persisted: `UINode` dropped its `locked` schema field as a dead field
+   * with no runtime reader (CLAUDE.md, `ui.ts` — same fate as `tags`), so a
+   * scene-UI node's lock state can't round-trip through `.vscn` either. See
+   * `ReactWorldAuthoringAdapter.lockedIds`'s doc comment for the identical
+   * reasoning. D4.R1 — now also read by `pickable.pick` below, so a locked
+   * node is skipped by canvas click/marquee pick, matching the first-party
+   * threejs raycast's own locked-skip behavior (`viewport-raycast.ts`).
+   */
+  private readonly lockedIds = new Set<string>();
+
+  /**
+   * E1.b (spec-27 §7 E1) — the ONE `UIAnimationController` shared by every
+   * consumer of this child's timeline: the design-time stage
+   * (`scene-ui-layer.ts`'s `SceneUILayerRoot`, live preview) AND the unified
+   * editor's keyframe timeline panel (`scene-ui-mode/scene-ui-timeline-tab.tsx`,
+   * playback/scrub controls). Owned here (not `useMemo`'d separately in each
+   * mount) so scrubbing the timeline moves the SAME preview the stage renders
+   * — the harness's `UIEditor.tsx` got this for free by constructing both in
+   * one component; the unified editor mounts the stage and the timeline as
+   * two independent React roots, so the shared instance has to live on the
+   * adapter both already hold a reference to.
+   */
+  readonly anim = new UIAnimationController();
+
+  constructor(
+    private readonly store: UIEditStore,
+    opts: { writeBackend?: SourceWriteBackend } = {},
+  ) {
+    this.writeBackend = opts.writeBackend;
+    this.capabilities = {
+      transform: false,
+      material: false,
+      inspectorFields: true,
+      create: true,
+      delete: true,
+      reparent: true,
+      persist: true,
+      layout: true,
+    };
+  }
+
+  /** C3 (D12) — geometric hit-test over the attached pick surface, reusing
+   *  the SAME `hitTest` primitive the harness's `SelectionOverlay` already
+   *  uses for in-realm hover/click (`ui-editor/react-store.ts`) — the B4-
+   *  blessed geometric `data-ui-id` rect test, not `elementFromPoint`.
+   *
+   *  D4.R1 — a `lockedIds` member is SKIPPED by the hit-test (falls through
+   *  to whatever unlocked element is behind it, or `null`), closing the gap
+   *  where the layer-tree/overlay lock toggle gated undo/round-trip but
+   *  nothing on the pick path — see `lockedIds`'s doc comment. */
+  readonly pickable: PickProvider = {
+    pick: (clientX, clientY) =>
+      this._pickSurface
+        ? hitTest(this._pickSurface, clientX, clientY, (id) => this.lockedIds.has(id))
+        : null,
+  };
+
+  /** Attach/detach the live stage element `pickable.pick` hit-tests against
+   *  (`scene-ui-layer.ts`'s mount/dispose). */
+  attachPickSurface(el: HTMLElement): void {
+    this._pickSurface = el;
+  }
+  detachPickSurface(): void {
+    this._pickSurface = null;
+  }
+
+  // --- hierarchy ---
+  readonly hierarchy: HierarchyProvider = {
+    roots: () => this.store.roots.map((r) => toEditorNode(r, null)),
+    node: (id) => {
+      const loc = findNode(this.store.roots, id);
+      return loc ? toEditorNode(loc.node, loc.parent?.id ?? null) : null;
+    },
+    object3D: () => null, // UI nodes are DOM, not Object3D
+    idForObject3D: () => null,
+  };
+
+  // --- selection ---
+  readonly selection: SelectionProvider = {
+    get: () => this.store.selection,
+    set: (ids) => this.store.select(ids),
+  };
+
+  // --- inspector (schema-driven property descriptors) ---
+  readonly inspector: InspectorProvider = {
+    properties: (id) => this.describe(id),
+    get: (id, path) => {
+      // D4 — see `lockedIds`'s doc comment; `visible` is a real `UINode`
+      // field already reached generically via `getNodePath` below, so it
+      // needs no special case here.
+      if (path === 'locked') return this.lockedIds.has(id);
+      const loc = findNode(this.store.roots, id);
+      return loc ? getNodePath(loc.node, path) : undefined;
+    },
+    set: (id, path, value) => {
+      if (path === 'locked') {
+        if (value) this.lockedIds.add(id);
+        else this.lockedIds.delete(id);
+        return;
+      }
+      this.store.setProp(id, path, value);
+    },
+  };
+
+  // --- layout (K7) ---
+  readonly layout: LayoutProvider = {
+    get: (id) => {
+      const loc = findNode(this.store.roots, id);
+      return (loc?.node.layout as Record<string, unknown> | undefined) ?? null;
+    },
+    beginEdit: () => this.store.beginEdit(),
+    apply: (id, patch) => {
+      for (const [k, v] of Object.entries(patch)) this.store.previewSetProp(id, `layout.${k}`, v);
+    },
+    endEdit: () => this.store.endEdit(),
+  };
+
+  // --- structure ---
+  readonly structure: StructureProvider = {
+    create: (kind, parentId) =>
+      this.store.addNode(parentId ?? (this.store.roots[0]?.id as string), kind as UINode['kind']),
+    remove: (id) => this.store.remove(id),
+    // D4.R2 — batch a multi-node delete into the store's ONE-commit
+    // `removeMany` (a single undo step for the whole selection) instead of
+    // this shell looping `remove(id)` N times (N undo steps). Cheap here:
+    // `UIEditStore`'s undo is an in-memory JSON-tree snapshot per commit, no
+    // async/network round trip to sequence — unlike the react-world
+    // adapter's whole-file source writes, there's no race to guard against.
+    removeMany: (ids) => this.store.removeMany(ids),
+    duplicate: (id) => this.store.duplicate(id) ?? id,
+    reparent: (id, newParentId) => {
+      if (newParentId) this.store.reparent(id, newParentId);
+    },
+    // C3 — drives the shell's generic "Create ▸" hierarchy-menu submenu
+    // (`GameHierarchy.tsx`), the SAME contract-only affordance every other
+    // adapter's rows already get; the richer drag/drop palette (K1) stays
+    // harness-only (`ui-editor/palette.tsx`, spec-27 E1 scope). Every kind
+    // `defaultNodeForKind` (`ui-edit-store.ts`) actually knows how to seed.
+    creatableKinds: () => [...CREATABLE_KINDS],
+  };
+
+  // --- persistence ---
+  // De-stubbed (T3.2 slice 3, design §4) over the `SourceWriteBackend` seam. A class
+  // GETTER, not a field initializer — a field initializer runs before the
+  // constructor body assigns `this.writeBackend` (the slice-1 ordering bug; see
+  // `vgai-scene-authoring-adapter.ts` for the pattern).
+  //
+  // What "de-stubbed" means here, concretely: `SourceEditPanel` writes every source
+  // edit to disk IMMEDIATELY via fetch the instant it is committed (Enter/blur) —
+  // there is NO pending-write queue anywhere in this architecture. `save()`
+  // therefore has nothing to flush, backend or not; its honest implementation is a
+  // no-op (see `../ui-source/source-write-backend.ts`'s doc comment for the
+  // investigation). The real de-stub delivered here is `destination` truthfully
+  // reporting whether a backend even EXISTS in this session, instead of the old
+  // hard-coded "save() not yet wired" stub text.
+  get persistence(): PersistenceProvider {
+    const backend = this.writeBackend;
+    const store = this.store;
+    return {
+      isDirty: () => store.canUndo,
+      save: async () => {
+        // Nothing pending to flush (immediate-write architecture) — see doc
+        // comment above. The ui-tree's OWN persistence (layout/prop edits → the
+        // open scene) is a separate, unconditional path (`onCommit` →
+        // `EditorStore.setSceneUI`) that does not route through this method.
+      },
+      serialize: () => store.serialize(),
+      destination: backend
+        ? 'component source (JSX, via /__ui-source — writes are immediate; nothing pending to flush)'
+        : 'component source (JSX) — no source-write backend in this session (hosted/no dev server)',
+    };
+  }
+
+  undo(): void {
+    this.store.undo();
+  }
+  redo(): void {
+    this.store.redo();
+  }
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener);
+  }
+
+  /** Build property descriptors for a node (inspector schema). */
+  private describe(id: string): PropertyDescriptor[] {
+    const loc = findNode(this.store.roots, id);
+    if (!loc) return [];
+    const node = loc.node;
+    const out: PropertyDescriptor[] = [
+      { path: 'name', label: 'name', type: 'string' },
+      { path: 'visible', label: 'visible', type: 'boolean' },
+      { path: 'layout.width', label: 'width', type: 'number' },
+      { path: 'layout.height', label: 'height', type: 'number' },
+      { path: 'layout.gap', label: 'gap', type: 'number' },
+      { path: 'style.backgroundColor', label: 'background', type: 'color' },
+      { path: 'style.color', label: 'color', type: 'color' },
+      { path: 'style.fontSize', label: 'fontSize', type: 'number' },
+    ];
+    for (const k of Object.keys(node.props ?? {})) {
+      out.push({ path: `props.${k}`, label: k, type: 'json' });
+    }
+    return out;
+  }
+
+  /** Every node id (for select-all). */
+  allIds(): string[] {
+    const ids: string[] = [];
+    walk(this.store.roots, (n) => ids.push(n.id as string));
+    return ids;
+  }
+
+  /**
+   * C2 (docs/unified-world-editor/26-unified-editor-spec.md §4 C2) — the
+   * wrapped {@link UIEditStore}, exposed for this adapter's OWN inspector-
+   * section registrations (`authoring/ui-inspector-sections.tsx`) to read/
+   * write UI-tree state the narrow `AuthoringAdapter` contract can't express
+   * (multi-select batch writes via `setMany`, K9 mixed-value detection) — the
+   * same "adapter-owned module privilege" the first-party threejs sections
+   * use via `EditorContext`'s `useEditorStore()` (there is no equivalent
+   * React context here — a bare `UIAuthoringAdapter` is never wrapped in one).
+   * NOT part of the `AuthoringAdapter` interface — a
+   * concrete-class-only escape hatch, consumed only by that registration
+   * module (which already does `instanceof UIAuthoringAdapter` to match).
+   */
+  get uiStore(): UIEditStore {
+    return this.store;
+  }
+}

package/src/authoring/ui-hierarchy-menu.ts

@@ -0,0 +1,40 @@
+/**
+ * "Add UI Canvas" hierarchy context-menu item (C3, docs/unified-world-editor/
+ * 26-unified-editor-spec.md §4 C3) — the first-canvas affordance that
+ * replaces the retired standalone UI-edit mode's demo-absent
+ * `defaultCanvasRoot()` seeding (no shim — Q3). Shown on a first-party
+ * scene-ROOT row while the open scene has no `ui` roots yet; seeds ONE empty
+ * canvas (design/24-scene-ui.md D10 — the same schema-minimal empty canvas
+ * project mode already seeds) and asks `ViewportPanel.tsx` to rebuild the
+ * edit-mode composite so the new `scene-ui` child appears (§3.1's install
+ * gate — `getSceneUI().length > 0` — flips the instant this commits).
+ *
+ * Registered through `hierarchy-menu-registry.ts`'s permanent adapter-module
+ * escape hatch (C2), the same seam `first-party-hierarchy-menu.ts` uses.
+ * Imported once for its side effect at boot (`main.tsx`) — NOT loaded by the
+ * standalone harness (`ui-editor/harness.tsx`), which has no `EditorStore`
+ * to seed and no composite to rebuild.
+ */
+
+import { registerHierarchyMenuItems } from '../hierarchy-menu-registry';
+import { defaultCanvasRoot } from '../ui-editor/ui-edit-store';
+import { EDIT_MODE_REBUILD_EVENT } from './edit-mode-authoring';
+
+registerHierarchyMenuItems(
+  (ctx) => {
+    if (ctx.store.getSceneUI().length > 0) return false;
+    // A first-party scene ROOT row only (not every entity row) — one of the
+    // open document's own top-level entities (`store.entities` is the
+    // top-level `SceneEntity[]` tree, `EditorStore`'s own doc comment).
+    return ctx.store.entities.some((e) => e.id === ctx.nodeId);
+  },
+  (ctx) => [
+    {
+      label: 'Add UI Canvas',
+      action: () => {
+        ctx.store.setSceneUI([defaultCanvasRoot()]);
+        window.dispatchEvent(new CustomEvent(EDIT_MODE_REBUILD_EVENT));
+      },
+    },
+  ],
+);

package/src/authoring/ui-inspector-sections.tsx

@@ -0,0 +1,156 @@
+/**
+ * UI adapter inspector-section registrations (C2/C3, docs/unified-world-
+ * editor/26-unified-editor-spec.md §4 C2/C3) — the UI adapter module's
+ * contribution to the shared `inspector-section-registry.ts` seam, the
+ * sibling of `authoring/first-party-inspector/register.tsx`. Wraps `ui-editor/
+ * inspector.tsx`'s extracted `LayoutSection`/`StyleSection`/`PropsSection`/
+ * `EventsSection` (moved out of the monolithic `UIInspector` body, testids
+ * unchanged) so `UIInspector` itself becomes a thin shell that renders
+ * whatever matches via `matchedInspectorSections` (see that file's own doc
+ * comment).
+ *
+ * Matched for a real UI node (`node !== null`) reachable through a
+ * `UIAuthoringAdapter` — {@link resolveUIAdapter} below resolves that EITHER
+ * WAY the adapter can present it: the ACTIVE adapter is the bare
+ * `UIAuthoringAdapter` itself (the pre-C3 `setActiveAuthoring(adapter)` shape
+ * — no live construction site remains post-E2's harness retirement, but the
+ * branch stays as the defensive fallback), OR — since C3 — the edit-mode
+ * `CompositeAuthoringAdapter`, whose `ownerOf(node.id)` names the UI CHILD
+ * that actually owns the node (mirrors `first-party-inspector/
+ * is-first-party-selection.ts`'s identical composite-resolution precedent).
+ * The naive pre-C3 `adapter instanceof UIAuthoringAdapter` check ALWAYS
+ * fails once the composite is installed (`Inspector.tsx` passes the
+ * COMPOSITE, never the child, as its `adapter` prop) — this is the fix.
+ *
+ * Props/Events additionally require a SINGLE selection, mirroring the
+ * pre-C2 `!multi` gate in `UIInspector`. The Layout registration carries
+ * `suppresses`/`panelName` (C3): under the ONE shell (`Inspector.tsx`), the
+ * generic `UIAuthoringAdapter.inspector.properties()` grid would otherwise
+ * render NEXT TO this richer Layout/Style pair — the bare-adapter path
+ * (`UIInspector`, which has no such built-ins) ignores both.
+ *
+ * Imported once for its side effect, by `main.tsx` (so `UIInspector`
+ * renders correctly for the unified editor's scene-UI child, C3).
+ */
+
+import type { AuthoringAdapter, EditorNode } from '@engine/adapter';
+import type { UINode } from '@engine/scene/schema';
+import {
+  type InspectorSectionProps,
+  registerInspectorSections,
+} from '../inspector-section-registry';
+import {
+  EventsSection,
+  LayoutSection,
+  mixedValue,
+  PropsSection,
+  StyleSection,
+} from '../ui-editor/inspector';
+import { findNode } from '../ui-editor/node-ops';
+import type { UIEditStore } from '../ui-editor/ui-edit-store';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { UIAuthoringAdapter } from './ui-authoring-adapter';
+
+/**
+ * C3 — resolve the `UIAuthoringAdapter` that actually owns `nodeId`, whether
+ * `adapter` IS one (bare/harness path) or is the edit-mode composite wrapping
+ * one as a `kind: 'scene-ui'` child (unified-editor path). `null` when
+ * neither applies (a non-UI selection, or a composite with no UI child).
+ */
+function resolveUIAdapter(
+  nodeId: string | null,
+  adapter: AuthoringAdapter,
+): UIAuthoringAdapter | null {
+  if (adapter instanceof UIAuthoringAdapter) return adapter;
+  if (adapter instanceof CompositeAuthoringAdapter && nodeId) {
+    const owner = adapter.ownerOf(nodeId);
+    const child = owner ? adapter.childAdapters().find((c) => c.worldId === owner) : undefined;
+    return child?.adapter instanceof UIAuthoringAdapter ? child.adapter : null;
+  }
+  return null;
+}
+
+const isUISelection = (node: EditorNode | null, adapter: AuthoringAdapter): boolean =>
+  node !== null && resolveUIAdapter(node.id, adapter) !== null;
+
+const isSingleUISelection = (node: EditorNode | null, adapter: AuthoringAdapter): boolean => {
+  if (node === null) return false;
+  const ui = resolveUIAdapter(node.id, adapter);
+  return ui !== null && ui.uiStore.selection.length <= 1;
+};
+
+/** Shared "resolve the live node" prelude every wrapped section below needs
+ *  — `null` when `nodeId` no longer resolves (selection changed mid-render;
+ *  the shell simply skips the section). */
+function resolveUINode(store: UIEditStore, nodeId: string | null): UINode | null {
+  const loc = nodeId ? findNode(store.roots, nodeId) : null;
+  return loc?.node ?? null;
+}
+
+function makeSetAndMixed(store: UIEditStore, ids: string[], nodeId: string) {
+  const set = (path: string, value: unknown): void => {
+    if (ids.length > 1) store.setPropMulti(ids, path, value);
+    else store.setProp(nodeId, path, value);
+  };
+  const mixed = (path: string): boolean => mixedValue(store, ids, path);
+  return { set, mixed };
+}
+
+registerInspectorSections({
+  match: isUISelection,
+  Section: function WrappedLayoutSection({ adapter, nodeId }: InspectorSectionProps) {
+    const ui = resolveUIAdapter(nodeId, adapter);
+    if (!ui) return null;
+    const store = ui.uiStore;
+    const ids = store.selection;
+    const node = resolveUINode(store, nodeId);
+    if (!node) return null;
+    const { set, mixed } = makeSetAndMixed(store, ids, nodeId!);
+    return <LayoutSection store={store} ids={ids} node={node} set={set} mixed={mixed} />;
+  },
+  // C3 — under the unified editor's ONE inspector shell, suppress the
+  // generic descriptor grid `UIAuthoringAdapter.inspector.properties()`
+  // would otherwise render alongside this richer pair (§4 C3/R4). The
+  // bare-adapter (harness) path never renders the shell's generic grid at
+  // all, so `suppresses`/`panelName` are no-ops there.
+  suppresses: ['header', 'transform', 'properties'],
+  panelName: 'Inspector',
+});
+
+registerInspectorSections({
+  match: isUISelection,
+  Section: function WrappedStyleSection({ adapter, nodeId }: InspectorSectionProps) {
+    const ui = resolveUIAdapter(nodeId, adapter);
+    if (!ui) return null;
+    const store = ui.uiStore;
+    const ids = store.selection;
+    const node = resolveUINode(store, nodeId);
+    if (!node) return null;
+    const { set, mixed } = makeSetAndMixed(store, ids, nodeId!);
+    return <StyleSection node={node} set={set} mixed={mixed} />;
+  },
+});
+
+registerInspectorSections({
+  match: isSingleUISelection,
+  Section: function WrappedPropsSection({ adapter, nodeId }: InspectorSectionProps) {
+    const ui = resolveUIAdapter(nodeId, adapter);
+    if (!ui) return null;
+    const store = ui.uiStore;
+    const node = resolveUINode(store, nodeId);
+    if (!node) return null;
+    return <PropsSection store={store} node={node} id={nodeId!} />;
+  },
+});
+
+registerInspectorSections({
+  match: isSingleUISelection,
+  Section: function WrappedEventsSection({ adapter, nodeId }: InspectorSectionProps) {
+    const ui = resolveUIAdapter(nodeId, adapter);
+    if (!ui) return null;
+    const store = ui.uiStore;
+    const node = resolveUINode(store, nodeId);
+    if (!node) return null;
+    return <EventsSection store={store} node={node} id={nodeId!} />;
+  },
+});

package/src/authoring/undo-timeline.ts

@@ -0,0 +1,145 @@
+/**
+ * The editor-global undo TIMELINE (T3.2 slice 2 — design
+ * `docs/PERSISTENCE-PROVIDER-DESIGN.md` §3/§7 slice 2).
+ *
+ * Today there are THREE independent undo stacks (the first-party `EditorStore`'s
+ * whole-doc snapshots, an `IngestAuthoringAdapter`'s overlay-backed closures, a
+ * `UIEditStore`'s tree snapshots) and nothing orders them against each other: a
+ * Ctrl+Z after "first-party edit → enter ingest → ingest edit" only ever undoes
+ * within whichever stack happens to be active. This module is the ONE shared
+ * timeline that fixes that: a bounded stack of `{ adapter }` ENTRIES — tags, not
+ * state. Each participating store keeps recording into its OWN stack exactly as
+ * it always has (this file never touches `_undoStack`/`undoStack`/`_undo`
+ * directly) and calls {@link notifyUndoableOp} with itself right after it pushes,
+ * so the entry's only job is to say "the next undo of THIS one goes here."
+ *
+ * Ctrl+Z pops the timeline and calls `entry.adapter.undo()`; Ctrl+Shift+Z /
+ * Cmd+Shift+Z / Ctrl+Y mirror with `redo()`. A brand-new op recorded ANYWHERE
+ * clears the global redo mirror (standard undo semantics), on top of whatever
+ * per-adapter redo-clearing each store already does for its own stack.
+ *
+ * Adapter identity — the choice this file makes and why: an entry holds the LIVE
+ * OBJECT REFERENCE that recorded it (the `EditorStore` instance for first-party,
+ * an `IngestAuthoringAdapter` instance, a `UIEditStore` instance — all three
+ * already expose `undo()`/`redo()` so no wrapper type is needed), checked against
+ * a `Set` of currently-registered instances at dispatch time. A synthesized
+ * string id (`'ingest'`, `'ui'`) was considered and rejected: a SECOND ingest/UI
+ * session reuses the same string, so a stale entry from a first, since-uninstalled
+ * session would resolve against the WRONG (new) live adapter instead of being
+ * dropped. Keying on the object itself sidesteps that — a new session is a new
+ * object, so an old entry can only ever match its OWN (registered) instance or
+ * fail the liveness check and get dropped, which is exactly the disposed-adapter
+ * rule below. (A `WeakRef` was the other option raised; rejected because
+ * "disposed" here is a LOGICAL state — the instance can still be strongly
+ * reachable elsewhere when its session ends — so liveness must be tracked by an
+ * explicit unregister call, not by GC.)
+ *
+ * Session lifetime: `registerUndoAdapter`/`unregisterUndoAdapter` are called at
+ * each store's construction/teardown (see `EditorStore`, `IngestAuthoringAdapter`,
+ * `UIEditStore`, `ingest-mode.ts`'s `exitIngestMode`, `edit-mode-authoring.ts`'s
+ * `exitEditModeAuthoring` for a scene-UI child's `UIEditStore`). An entry
+ * whose adapter has been unregistered since it was
+ * recorded is dropped (with a console warning) when popped; popping continues
+ * past dropped entries until a live one is found or the stack is empty — a
+ * session-scoped stack dies with its session, same rule the per-adapter stacks
+ * already had on their own.
+ *
+ * Cross-adapter transactions are OUT of scope (design §6): a gesture spanning two
+ * adapters records two entries and undoes in two Ctrl+Z presses.
+ */
+
+/** Anything with its own undo/redo the timeline can dispatch to — `EditorStore`,
+ *  `IngestAuthoringAdapter`, and `UIEditStore` all satisfy this structurally.
+ *  A strict `false` return means "I could not perform this right now" (blocked
+ *  during play, empty local stack, no scene bound) — the timeline then puts the
+ *  entry BACK instead of consuming it, so a blocked Ctrl+Z doesn't silently eat
+ *  an undo level. `void`/`true` both count as performed. */
+export interface UndoAdapter {
+  // biome-ignore lint/suspicious/noConfusingVoidType: deliberate contract (see doc comment) — legacy adapters return void ("performed"), refusal-aware ones return false; `boolean | undefined` would reject `(): void` implementers
+  undo(): boolean | void;
+  // biome-ignore lint/suspicious/noConfusingVoidType: same contract as undo()
+  redo(): boolean | void;
+}
+
+/** Matches the 50-deep bound every per-adapter stack already uses. */
+const MAX_TIMELINE = 50;
+
+/** Currently-registered (not disposed/uninstalled) adapters — see doc comment above. */
+const live = new Set<UndoAdapter>();
+
+let undoStack: UndoAdapter[] = [];
+let redoStack: UndoAdapter[] = [];
+
+/** Register a store/adapter as a valid dispatch target for entries tagging it. */
+export function registerUndoAdapter(adapter: UndoAdapter): void {
+  live.add(adapter);
+}
+
+/**
+ * Uninstall a store/adapter (session end). Any timeline entries already recorded
+ * for it are NOT removed from the stacks — they are simply dropped (with a warn)
+ * the next time they would be popped, per the disposed-adapter rule.
+ */
+export function unregisterUndoAdapter(adapter: UndoAdapter): void {
+  live.delete(adapter);
+}
+
+/**
+ * Record a new undoable op that `adapter` just pushed onto its OWN stack. Clears
+ * the GLOBAL redo mirror (in addition to whatever per-adapter redo-clearing the
+ * caller already does for its own stack) — a new op anywhere invalidates redo.
+ */
+export function notifyUndoableOp(adapter: UndoAdapter): void {
+  undoStack.push(adapter);
+  if (undoStack.length > MAX_TIMELINE) undoStack.shift();
+  redoStack = [];
+}
+
+function dispatch(from: UndoAdapter[], to: UndoAdapter[], op: 'undo' | 'redo'): void {
+  while (from.length > 0) {
+    const adapter = from.pop()!;
+    if (!live.has(adapter)) {
+      console.warn(
+        `[undo-timeline] dropping ${op} entry for a disposed/uninstalled adapter — ` +
+          'its session ended before this entry was reached',
+      );
+      continue;
+    }
+    if (adapter[op]() === false) {
+      // The adapter is live but couldn't act (e.g. first-party undo blocked
+      // during play). Put the entry back and stop — falling through to an OLDER
+      // entry from another adapter would undo out of global order.
+      from.push(adapter);
+      return;
+    }
+    to.push(adapter);
+    return;
+  }
+}
+
+/** Ctrl+Z / Cmd+Z. */
+export function timelineUndo(): void {
+  dispatch(undoStack, redoStack, 'undo');
+}
+
+/** Ctrl+Shift+Z / Cmd+Shift+Z / Ctrl+Y. */
+export function timelineRedo(): void {
+  dispatch(redoStack, undoStack, 'redo');
+}
+
+/** True when the next Ctrl+Z has at least one (possibly dead) entry to try. */
+export function timelineCanUndo(): boolean {
+  return undoStack.length > 0;
+}
+
+/** True when the next redo has at least one (possibly dead) entry to try. */
+export function timelineCanRedo(): boolean {
+  return redoStack.length > 0;
+}
+
+/** Test-only: wipe all registrations + stacks so test files don't bleed into each other. */
+export function __resetUndoTimelineForTest(): void {
+  live.clear();
+  undoStack = [];
+  redoStack = [];
+}