@vgai/editor 0.2.0

package/src/authoring/react-dom-authoring-adapter.ts

@@ -0,0 +1,795 @@
+/**
+ * ReactDomAuthoringAdapter — the editor's {@link AuthoringAdapter} for an
+ * INGESTED (unmodified) native-React world, wave 10 Slice A
+ * (`docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md` §1, D-K1..D-K5).
+ *
+ * Unlike {@link ReactWorldAuthoringAdapter} (the first-party react-WORLD
+ * adapter, T6.2 slice 2), an ingested react game's JSX is NEVER `data-oid`-
+ * stamped (three independent guards — see the design doc's §0) and is never
+ * written back to (the never-modify-game-source rule, `CLAUDE.md`). So this
+ * adapter cannot reuse `walkOidTree` (it would see an EMPTY tree — nothing
+ * is stamped) and cannot reuse the JSX write-back seam at all. It is
+ * structurally independent:
+ *
+ *  - Hierarchy: an on-demand walk of every ELEMENT node under a live DOM
+ *    root (snapshot per call — the DOM is live and may re-render, exactly
+ *    like `walkOidTree`'s own "no cached/mirrored state" contract). Identity
+ *    is a STRUCTURAL path, not an authored id: `'rdom:' + '/'-joined
+ *    segments`, each segment `<tag>[k]` where `k` is the element's index
+ *    among preceding same-tag element SIBLINGS (the DOM analog of the
+ *    Object3D structural-path scheme other ingest adapters already use).
+ *    Deterministic and stable while structure is stable; disambiguates
+ *    same-tag siblings (`div[0]` vs `div[1]`). The root itself is not a
+ *    node — its element children are the hierarchy roots.
+ *  - Labels derive from real DOM only — tag, plus `#id` or the first CSS
+ *    class when present — never a fabricated/authored name (anti-shim).
+ *  - Persistence is overlay-only: edits write the live element's inline
+ *    `style` DIRECTLY (a runtime override, gone on reload unless saved) and
+ *    record the same write into a {@link ReactDomOverlay} document, which the
+ *    caller persists via `saveWorldOverlay`/`loadWorldOverlay`
+ *    (`./world-overlay.ts`) — the SAME `.vgai/overlays/<world-id>.json`
+ *    convention every other manifest-world overlay uses. There is NO
+ *    `SourceWriteBackend` import anywhere in this file and NO `/__ui-source`
+ *    traffic of any kind, ever — this is the one hard invariant the design
+ *    doc's §4 NOTs pin (AC-K7).
+ *  - `object3D()`/`idForObject3D()` return `null` — these entities are DOM,
+ *    not `Object3D` (no 3D gizmo binding, mirroring `ReactWorldAuthoringAdapter`).
+ *
+ * Inspector reads/writes reuse `ReactWorldAuthoringAdapter`'s pure style
+ * helpers (`styleProp`/`numericStyleValue`/`cssColorToHex` — exported for
+ * this purpose, D-K5) but declare their OWN `STYLE_PROPERTIES` list: this
+ * adapter's writes are not routed through the JSX writer's supported-property
+ * ceiling, so its list is free to diverge (kept identical today for
+ * predictability — nothing stops a later slice from growing it).
+ *
+ * Apply-on-mount (D-K3): a pre-loaded overlay's entries are applied to the
+ * live DOM right after construction. An id that no longer resolves (the
+ * mounted tree moved on since the overlay was authored) is NOT applied, is
+ * loudly `console.warn`-reported (the `overlay-report.ts` orphan spirit,
+ * without importing that Object3D-shaped apparatus), and is RETAINED in the
+ * document — user data is never silently dropped (AC-K4).
+ *
+ * Undo/redo (D-K3, AC-K6) is adapter-local (`PendingUndo`, mirroring
+ * `ReactWorldAuthoringAdapter`'s pattern) and self-registers with the
+ * editor-global undo timeline (`./undo-timeline.ts`) exactly like every
+ * other ingest/world adapter — so Ctrl+Z reaches it while it's the active
+ * session, and its entries are dropped (not misapplied) once the session
+ * ends (the route's teardown calls `unregisterUndoAdapter`).
+ */
+
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  BoxEditProvider,
+  ColorSampleProvider,
+  DOMRectLike,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  RectProvider,
+  SelectionProvider,
+} from '@engine/adapter';
+import type { EditorStore } from '../editor-store';
+import { browserOrInlineResolver, getComputedStyleValue } from '../ui-source/inspect';
+import {
+  cssColorToHex,
+  mapBoxEditPatchKey,
+  numericStyleValue,
+  styleProp,
+} from './react-world-authoring-adapter';
+import { notifyUndoableOp, registerUndoAdapter } from './undo-timeline';
+
+/**
+ * The minimal structural shape this adapter needs from a live DOM element —
+ * deliberately NOT `HTMLElement` (same testability reasoning as
+ * `OidElementLike` in `react-world-authoring-adapter.ts`: this repo's vitest
+ * environment for THIS adapter's own unit test is `node`, no real DOM). A
+ * real `Element`/`HTMLElement` satisfies this structurally (`style` is
+ * optional here for the same reason it is on `OidElementLike` — a plain
+ * `Element` has no `style` getter, only `HTMLElement`/`SVGElement` do, but
+ * TS treats an optional field as satisfied by its absence).
+ */
+export interface DomElementLike {
+  readonly tagName: string;
+  readonly children: ArrayLike<DomElementLike>;
+  readonly id: string;
+  readonly className: string;
+  readonly style?: unknown;
+  /**
+   * T0 (spec 27 §2) — the element's live viewport rect, for `rects.rect`'s
+   * host-relative geometry below (see `OidElementLike.getBoundingClientRect`'s
+   * identical doc comment in `react-world-authoring-adapter.ts`). Optional so
+   * existing plain-object test fixtures keep type-checking unchanged — a node
+   * with no `getBoundingClientRect` simply has no rect (never a fabricated 0×0).
+   */
+  getBoundingClientRect?(): {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+  };
+}
+
+/** One structural-path node resolved from a live-DOM walk. */
+interface DomNode {
+  /** `'rdom:' + '/'-joined <tag>[k] segments` — see the class doc comment. */
+  id: string;
+  tag: string;
+  el: DomElementLike;
+  parentId: string | null;
+  childIds: string[];
+}
+
+interface DomTree {
+  nodes: Map<string, DomNode>;
+  rootIds: string[];
+}
+
+const ID_PREFIX = 'rdom:';
+
+/** First whitespace-separated CSS class, or `undefined` if `className` is empty/absent. */
+function firstClassName(className: string): string | undefined {
+  const trimmed = className.trim();
+  if (!trimmed) return undefined;
+  return trimmed.split(/\s+/)[0];
+}
+
+/** Real-DOM-only label (anti-shim): tag, `#id` when present, else `.firstClass` when present. */
+function labelFor(el: DomElementLike, tag: string): string {
+  if (el.id) return `${tag}#${el.id}`;
+  const cls = firstClassName(el.className ?? '');
+  if (cls) return `${tag}.${cls}`;
+  return tag;
+}
+
+/**
+ * Walk a live DOM root's ELEMENT descendants into a {@link DomTree}, snapshot
+ * per call (D-K1: "the DOM is live and may re-render"). Structural-path id
+ * scheme: each segment is `<tag>[k]`, `k` = the element's index among
+ * preceding SAME-TAG element siblings under the SAME parent — computed with
+ * one `Map<tag, count>` per sibling group, reset at each recursion level.
+ */
+function walkDomTree(root: DomElementLike): DomTree {
+  const nodes = new Map<string, DomNode>();
+  const rootIds: string[] = [];
+
+  function visitChildren(
+    children: ArrayLike<DomElementLike>,
+    parentId: string | null,
+    parentPath: string,
+  ): void {
+    const tagCounts = new Map<string, number>();
+    for (const el of Array.from(children)) {
+      const tag = el.tagName.toLowerCase();
+      const k = tagCounts.get(tag) ?? 0;
+      tagCounts.set(tag, k + 1);
+      const path = parentPath ? `${parentPath}/${tag}[${k}]` : `${tag}[${k}]`;
+      const id = `${ID_PREFIX}${path}`;
+      const node: DomNode = { id, tag, el, parentId, childIds: [] };
+      nodes.set(id, node);
+      if (parentId) nodes.get(parentId)?.childIds.push(id);
+      else rootIds.push(id);
+      visitChildren(el.children, id, path);
+    }
+  }
+
+  visitChildren(root.children, null, '');
+  return { nodes, rootIds };
+}
+
+/** A reasonably useful, curated inline-style property list — this adapter's
+ *  OWN list (D-K2: not shared with `ReactWorldAuthoringAdapter`'s, though
+ *  kept identical in shape today — this one is not bounded by a JSX writer's
+ *  supported-property ceiling). */
+const STYLE_PROPERTIES: ReadonlyArray<{
+  prop: string;
+  label: string;
+  type: PropertyDescriptor['type'];
+  options?: string[];
+}> = [
+  { prop: 'color', label: 'Color', type: 'color' },
+  { prop: 'backgroundColor', label: 'Background', type: 'color' },
+  { prop: 'borderColor', label: 'Border Color', type: 'color' },
+  { prop: 'fontSize', label: 'Font Size', type: 'number' },
+  { prop: 'width', label: 'Width', type: 'number' },
+  { prop: 'height', label: 'Height', type: 'number' },
+  { prop: 'padding', label: 'Padding', type: 'number' },
+  { prop: 'margin', label: 'Margin', type: 'number' },
+  { prop: 'borderRadius', label: 'Border Radius', type: 'number' },
+  { prop: 'gap', label: 'Gap', type: 'number' },
+  { prop: 'display', label: 'Display', type: 'enum', options: ['flex', 'block', 'none', 'grid'] },
+  { prop: 'textAlign', label: 'Text Align', type: 'enum', options: ['left', 'center', 'right'] },
+  { prop: 'flexDirection', label: 'Flex Direction', type: 'enum', options: ['row', 'column'] },
+];
+const STYLE_PATH_PREFIX = 'style.';
+
+/** `prop -> declared type` — see `ReactWorldAuthoringAdapter`'s identical map
+ *  for why `inspector.get` needs this (a real CSSOM value is always a
+ *  unit-suffixed string / an `rgb(...)` string, never a bare number/hex). */
+const STYLE_PROPERTY_TYPE: ReadonlyMap<string, PropertyDescriptor['type']> = new Map(
+  STYLE_PROPERTIES.map(({ prop, type }) => [prop, type]),
+);
+
+/** structural id -> cssProp -> value (D-K3). Values are always strings — the
+ *  same literal an inline style write / a saved overlay round-trips. */
+export type ReactDomOverlay = Record<string, Record<string, string>>;
+
+export interface ReactDomAuthoringOptions {
+  /** Pre-loaded overlay (from `loadWorldOverlay<ReactDomOverlay>`) — applied
+   *  to the live DOM on construction (D-K3 apply-on-mount) and mutated
+   *  in-place by every subsequent `inspector.set` (so `serialize()`/a later
+   *  `save()` always reflects every write, including unresolved-at-mount-time
+   *  ones from BEFORE this session, and new ones from THIS session). */
+  overlay: ReactDomOverlay;
+  /** `save()` flushes the current document through this — routes pass
+   *  `(o) => saveWorldOverlay(worldId, o)`. */
+  persist: (overlay: ReactDomOverlay) => Promise<void>;
+  /** Human/agent-readable destination (`PersistenceProvider.destination`) —
+   *  routes pass `worldOverlayPath(worldId)`. */
+  destination: string;
+}
+
+interface PendingUndo {
+  undo: () => void;
+  redo: () => void;
+}
+
+export class ReactDomAuthoringAdapter implements AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities = {
+    transform: false, // no 3D gizmo — DOM has no Object3D pose
+    material: false,
+    inspectorFields: true,
+    create: false, // element insertion out of v1 scope
+    delete: false, // structural delete out of v1 scope (overlay-only, no structure provider)
+    reparent: false,
+    persist: true,
+  };
+
+  private readonly doc: ReactDomOverlay;
+  private readonly persistFn: (overlay: ReactDomOverlay) => Promise<void>;
+  private readonly destinationPath: string;
+  private dirty = false;
+  private readonly undoStack: PendingUndo[] = [];
+  private readonly redoStack: PendingUndo[] = [];
+  /** Synchronous-burst cache for `snapshot()` — see that method's doc. */
+  private snapCache: DomTree | null = null;
+  private snapInvalidationScheduled = false;
+  /**
+   * T0 (spec 27 §4, B1) — the currently-open `boxEdit` begin/apply×N/end gesture, or
+   * `null` between gestures. Mirrors `ReactWorldAuthoringAdapter.boxEditSession` (see
+   * its doc comment for why `priorInline` exists) — `touched` here maps prop → the
+   * FINAL CSS-STRING value to write (this adapter's overlay route always stores CSS
+   * strings, never bare numbers, unlike the react-world source-write route).
+   */
+  private boxEditSession: {
+    id: string;
+    touched: Map<string, string>;
+    priorInline: Map<string, string>;
+  } | null = null;
+  /** D4 (spec27 §6 D4, layer-tree "lock" toggle) — SESSION-LOCAL, never
+   *  written to the overlay JSON: an ingested game's DOM has no persisted
+   *  "locked" concept (its overlay only ever records style overrides). See
+   *  `ReactWorldAuthoringAdapter.lockedIds`'s doc comment for the same
+   *  reasoning, INCLUDING D4.R1 (now read by `pickable.pick` below and by
+   *  the overlay's marquee candidate pool; NOT by `hierarchy`/`selection` —
+   *  a locked node stays selectable/unlockable from the layer tree). */
+  private readonly lockedIds = new Set<string>();
+
+  constructor(
+    private readonly root: DomElementLike,
+    private readonly store: EditorStore,
+    opts: ReactDomAuthoringOptions,
+  ) {
+    this.doc = opts.overlay;
+    this.persistFn = opts.persist;
+    this.destinationPath = opts.destination;
+    // This adapter IS an undo/redo target the editor-global timeline
+    // dispatches to (mirrors `ReactWorldAuthoringAdapter`'s identical call) —
+    // the caller (the ingest route's teardown) unregisters it on session end.
+    registerUndoAdapter(this);
+    this.applyOverlayOnMount();
+  }
+
+  /**
+   * A live-DOM walk, memoized for the current SYNCHRONOUS burst only.
+   *
+   * `hierarchy.node(id)` is called once per node by the shell's row flattener
+   * (`flattenIngestRows`), and a large live react game (react-rpg's dungeon
+   * is ~1900 walked rows over a several-thousand-element DOM) turned that into
+   * an O(N²) re-walk-per-node — a ~9s synchronous block that hung the editor
+   * on selection (the hierarchy re-renders synchronously inside the click's
+   * discrete-event flush). JS is single-threaded, so the DOM cannot change
+   * mid-render: caching the walk for the current synchronous stack and
+   * invalidating it on the next microtask keeps the "the DOM is live, never
+   * stale across renders" contract (a subsequent render, after the game may
+   * have re-rendered, re-walks) while collapsing one render's N node() calls
+   * to ONE walk. Style READS stay live regardless — `inspector.get` reads
+   * `n.el.style` off the cached element ref, not a cached value. Structural
+   * mutations (none in v1 — this adapter has no `structure` provider) would
+   * land between ticks (the game's own re-render), which the microtask
+   * invalidation already covers.
+   */
+  private snapshot(): DomTree {
+    if (this.snapCache) return this.snapCache;
+    const tree = walkDomTree(this.root);
+    this.snapCache = tree;
+    if (!this.snapInvalidationScheduled) {
+      this.snapInvalidationScheduled = true;
+      queueMicrotask(() => {
+        this.snapCache = null;
+        this.snapInvalidationScheduled = false;
+      });
+    }
+    return tree;
+  }
+
+  /**
+   * D-L1 (wave 10 Slice B, docs/WAVE10-REACT-INGEST-DOM-AUTHORING-DESIGN.md
+   * §2) — total ELEMENT nodes currently walked under the root: a fresh
+   * snapshot every call (same "the DOM is live and may re-render, never
+   * cached" discipline as `hierarchy.roots()`/`hierarchy.node()` above), not
+   * a count taken once at construction. Backs
+   * `__vgaiIngestReact.domEvidence().hierarchyNodeCount` — one of the four
+   * legs `vgai doctor`'s react-ingest MOUNTED bar requires
+   * (`clearsReactIngestMountedBar`, `packages/editor/src/doctor/report.ts`).
+   */
+  nodeCount(): number {
+    return this.snapshot().nodes.size;
+  }
+
+  private toEditorNode(n: DomNode): EditorNode {
+    return {
+      id: n.id,
+      label: labelFor(n.el, n.tag),
+      kind: n.tag,
+      parentId: n.parentId,
+      childIds: n.childIds,
+      flags: { runtimeOnly: true },
+    };
+  }
+
+  /**
+   * D-K3 apply-on-mount: apply every resolvable overlay entry to the live
+   * DOM; an id that doesn't resolve is loudly reported and left untouched
+   * (and stays in `this.doc` — it is never deleted here).
+   */
+  private applyOverlayOnMount(): void {
+    const { nodes } = this.snapshot();
+    for (const [id, props] of Object.entries(this.doc)) {
+      const n = nodes.get(id);
+      if (!n) {
+        // biome-ignore lint/suspicious/noConsole: deliberate, greppable orphan report — mirrors overlay-report.ts's own console.warn
+        console.warn(
+          `[ReactDomAuthoringAdapter] overlay entry "${id}" does not resolve to any live ` +
+            'element on this mount — not applied, retained in the overlay document.',
+        );
+        continue;
+      }
+      for (const [prop, value] of Object.entries(props)) {
+        this.applyStyleToElement(n.el, prop, value);
+      }
+    }
+  }
+
+  private applyStyleToElement(el: DomElementLike, prop: string, value: string): void {
+    if (!el.style) return;
+    (el.style as Record<string, unknown>)[prop] = value;
+  }
+
+  private recordOverlayEntry(id: string, prop: string, value: string): void {
+    const entry = this.doc[id] ?? {};
+    entry[prop] = value;
+    this.doc[id] = entry;
+  }
+
+  private removeOverlayEntry(id: string, prop: string): void {
+    const entry = this.doc[id];
+    if (!entry) return;
+    delete entry[prop];
+    if (Object.keys(entry).length === 0) delete this.doc[id];
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    roots: () => {
+      const { nodes, rootIds } = this.snapshot();
+      return rootIds.map((id) => this.toEditorNode(nodes.get(id)!));
+    },
+    node: (id) => {
+      const n = this.snapshot().nodes.get(id);
+      return n ? this.toEditorNode(n) : null;
+    },
+    object3D: () => null, // DOM, not Object3D — no 3D gizmo binding
+    idForObject3D: () => null,
+  };
+
+  readonly selection: SelectionProvider = {
+    get: () => [...this.store.selectedEntityIds],
+    set: (ids) => this.store.selectMultiple(ids),
+  };
+
+  /**
+   * A2 gap close-out (spec 27 §2, spec:237-254/spec:251-254) — GEOMETRIC rect
+   * hit-test over the live DOM tree, symmetric with
+   * `ReactWorldAuthoringAdapter.pickable` (see that provider's doc comment
+   * for the full rationale, identical here): NOT `document.elementFromPoint`
+   * (which skips a `pointer-events:none` design-time wrapper), smallest-area
+   * element containing the point wins (the deepest/most-specific node), ties
+   * broken by later tree-walk order (the topmost). Without this, an ingested
+   * react world's `rdom:`-id nodes are never `pickable`, so the shell's
+   * `pickTopmost` (`layered-pick.ts`) always falls through to `null` for this
+   * adapter — click-to-select through the viewport never resolves any node,
+   * even though `hierarchy`/`selection` already work from the panel.
+   *
+   * The winning id is the SAME structural `rdom:<tag>[k]` id
+   * `hierarchy`/`selection` already use — a hit routes straight into
+   * `composite.selection.set([id])` with no translation.
+   */
+  readonly pickable: PickProvider = {
+    pick: (clientX, clientY) => {
+      const { nodes } = this.snapshot();
+      let bestId: string | null = null;
+      let bestArea = Number.POSITIVE_INFINITY;
+      let bestOrder = -1;
+      let order = -1;
+      for (const node of nodes.values()) {
+        order++;
+        // D4.R1 — a locked node is SKIPPED, not returned (falls through to
+        // whatever unlocked node is behind/around it) — mirrors
+        // `ReactWorldAuthoringAdapter.pickable`'s identical fix and the
+        // first-party `viewport-raycast.ts` locked-skip.
+        if (this.lockedIds.has(node.id)) continue;
+        const rect = node.el.getBoundingClientRect?.();
+        if (!rect) continue; // no live rect (test fixture, or unmounted) — never a candidate
+        if (
+          clientX < rect.left ||
+          clientX > rect.right ||
+          clientY < rect.top ||
+          clientY > rect.bottom
+        ) {
+          continue;
+        }
+        const area = rect.width * rect.height;
+        // smallest-area (deepest) wins; ties broken by later tree-order (topmost)
+        if (area < bestArea || (area === bestArea && order > bestOrder)) {
+          bestId = node.id;
+          bestArea = area;
+          bestOrder = order;
+        }
+      }
+      return bestId;
+    },
+  };
+
+  /** Host rect to subtract for {@link rects}' HOST-RELATIVE geometry — same
+   *  reasoning as `ReactWorldAuthoringAdapter.hostRect` (this adapter's own
+   *  `this.root` is symmetrically the ingested world's mounted DOM layer). */
+  private hostRect(): { left: number; top: number } {
+    const r = this.root.getBoundingClientRect?.();
+    return { left: r?.left ?? 0, top: r?.top ?? 0 };
+  }
+
+  private toHostRelative(r: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  }): DOMRectLike {
+    const host = this.hostRect();
+    return { x: r.left - host.left, y: r.top - host.top, width: r.width, height: r.height };
+  }
+
+  /**
+   * T0 (spec 27 §2) — per-node screen geometry, HOST-RELATIVE (see
+   * {@link hostRect}'s doc comment), symmetric with
+   * `ReactWorldAuthoringAdapter.rects` so the overlay this feeds (Phase A3)
+   * treats both react adapters identically.
+   */
+  readonly rects: RectProvider = {
+    rect: (id) => {
+      const n = this.snapshot().nodes.get(id);
+      const r = n?.el.getBoundingClientRect?.();
+      return r ? this.toHostRelative(r) : null;
+    },
+    contextRects: (id) => {
+      const { nodes } = this.snapshot();
+      const n = nodes.get(id);
+      if (!n) return {};
+      const parentNode = n.parentId ? nodes.get(n.parentId) : undefined;
+      const parentRect = parentNode?.el.getBoundingClientRect?.();
+      const siblingIds = (parentNode ? parentNode.childIds : this.snapshot().rootIds).filter(
+        (sid) => sid !== id,
+      );
+      const siblings = siblingIds
+        .map((sid) => nodes.get(sid)?.el.getBoundingClientRect?.())
+        .filter((r): r is NonNullable<typeof r> => r != null)
+        .map((r) => this.toHostRelative(r));
+      const el = n.el;
+      const rect = el.getBoundingClientRect?.();
+      let paddingBox: DOMRectLike | undefined;
+      if (rect) {
+        const bt =
+          numericStyleValue(getComputedStyleValue(el, 'borderTopWidth', browserOrInlineResolver)) ??
+          0;
+        const br =
+          numericStyleValue(
+            getComputedStyleValue(el, 'borderRightWidth', browserOrInlineResolver),
+          ) ?? 0;
+        const bb =
+          numericStyleValue(
+            getComputedStyleValue(el, 'borderBottomWidth', browserOrInlineResolver),
+          ) ?? 0;
+        const bl =
+          numericStyleValue(
+            getComputedStyleValue(el, 'borderLeftWidth', browserOrInlineResolver),
+          ) ?? 0;
+        paddingBox = this.toHostRelative({
+          left: rect.left + bl,
+          top: rect.top + bt,
+          width: Math.max(0, rect.width - bl - br),
+          height: Math.max(0, rect.height - bt - bb),
+        });
+      }
+      return {
+        ...(parentRect ? { parent: this.toHostRelative(parentRect) } : {}),
+        ...(siblings.length ? { siblings } : {}),
+        ...(paddingBox ? { paddingBox } : {}),
+      };
+    },
+  };
+
+  /**
+   * D3.d (spec 27 §6) — eyedropper FALLBACK color-sample path, symmetric with
+   * `ReactWorldAuthoringAdapter.colorSample` (see that provider's doc comment
+   * for the full rationale — raw/un-normalized values, hit-element first).
+   */
+  readonly colorSample: ColorSampleProvider = {
+    backgroundChainAt: (clientX, clientY) => {
+      const hitId = this.pickable.pick(clientX, clientY);
+      if (!hitId) return null;
+      const { nodes } = this.snapshot();
+      const chain: string[] = [];
+      let cur: DomNode | undefined = nodes.get(hitId);
+      while (cur) {
+        chain.push(getComputedStyleValue(cur.el, 'backgroundColor', browserOrInlineResolver));
+        cur = cur.parentId ? nodes.get(cur.parentId) : undefined;
+      }
+      return chain;
+    },
+  };
+
+  /**
+   * T0 (spec 27 §4, B1) — same interface as `ReactWorldAuthoringAdapter.boxEdit`,
+   * routed to the OVERLAY-JSON instead of source (spec:305 — "Ingested adapter routes
+   * to its overlay-JSON instead of source, same interface"). `apply` is LIVE PREVIEW
+   * ONLY — it mutates the live element's inline style via `applyStyleToElement`
+   * WITHOUT touching `this.doc`/`dirty` (no overlay traffic, no spam). `end` commits
+   * every touched prop ONCE through {@link writeStyleEntry} (preserving the
+   * restore-BOTH-halves undo invariant, D-K2), composed into exactly ONE undo entry
+   * for the whole gesture (acceptance:310) even across multiple touched props.
+   */
+  readonly boxEdit: BoxEditProvider = {
+    begin: (id) => {
+      this.boxEditSession = { id, touched: new Map(), priorInline: new Map() };
+    },
+    apply: (id, patch) => {
+      const session = this.boxEditSession;
+      if (!session || session.id !== id) return; // no open gesture for this id
+      const n = this.snapshot().nodes.get(id);
+      if (!n) return; // unresolved id — no-op (per contract)
+      const pos = getComputedStyleValue(n.el, 'position', browserOrInlineResolver);
+      const isPositioned = pos === 'absolute' || pos === 'fixed';
+      for (const [key, v] of Object.entries(patch)) {
+        const mapped = mapBoxEditPatchKey(key, isPositioned);
+        if (!mapped) {
+          console.warn(
+            `[ReactDomAuthoringAdapter] boxEdit: dropping patch key "${key}" for "${id}" — ` +
+              (key === 'x' || key === 'y'
+                ? `node is not absolutely/fixed positioned (computed position: "${pos}"), ` +
+                  'no left/top to move'
+                : 'unrecognized box-edit patch key'),
+          );
+          continue;
+        }
+        // Lazily snapshot the TRUE pre-gesture inline value the first time THIS
+        // prop is touched in this gesture — before mutating it (see
+        // `boxEditSession`'s doc comment, mirroring the react-world adapter).
+        if (!session.priorInline.has(mapped.prop)) {
+          const prevRaw = styleProp(n.el.style, mapped.prop);
+          session.priorInline.set(mapped.prop, prevRaw == null ? '' : String(prevRaw));
+        }
+        const cssValue = mapped.cssValue(v);
+        this.applyStyleToElement(n.el, mapped.prop, cssValue);
+        session.touched.set(mapped.prop, cssValue); // this route always commits CSS strings
+      }
+    },
+    end: (id) => {
+      const session = this.boxEditSession;
+      this.boxEditSession = null;
+      if (!session || session.id !== id || session.touched.size === 0) return;
+      this.commitBoxEdit(id, session.touched, session.priorInline);
+    },
+  };
+
+  /**
+   * T0 (spec 27 §4, B1) — commit every prop touched by one `boxEdit` gesture, each
+   * through {@link writeStyleEntry} (preserving the restore-BOTH-halves undo
+   * invariant per prop), composed into exactly ONE undo entry (acceptance:310) whose
+   * inverse runs in REVERSE order and whose redo runs in gesture order.
+   */
+  private commitBoxEdit(
+    id: string,
+    touched: Map<string, string>,
+    priorInline: Map<string, string>,
+  ): void {
+    const entries: PendingUndo[] = [];
+    for (const [prop, value] of touched) {
+      const entry = this.writeStyleEntry(id, prop, value, priorInline.get(prop));
+      if (entry) entries.push(entry);
+    }
+    if (entries.length === 0) return;
+    this.pushUndo({
+      undo: () => {
+        for (let i = entries.length - 1; i >= 0; i--) entries[i]!.undo();
+      },
+      redo: () => {
+        for (const entry of entries) entry.redo();
+      },
+    });
+  }
+
+  readonly inspector: InspectorProvider = {
+    properties: (): PropertyDescriptor[] =>
+      STYLE_PROPERTIES.map(({ prop, label, type, options }) => ({
+        path: `${STYLE_PATH_PREFIX}${prop}`,
+        label,
+        type,
+        ...(options ? { options } : {}),
+      })),
+    get: (id, path) => {
+      // D4 (spec27 §6 D4, layer-tree visibility/lock) — see
+      // `ReactWorldAuthoringAdapter`'s matching branch for the reasoning
+      // (`locked` session-local; `visible` sugar for the `visibility` inline
+      // style — this adapter writes synchronously, so no echo is needed).
+      if (path === 'locked') return this.lockedIds.has(id);
+      if (path === 'visible') {
+        const n = this.snapshot().nodes.get(id);
+        if (!n) return undefined;
+        return styleProp(n.el.style, 'visibility') !== 'hidden';
+      }
+      if (!path.startsWith(STYLE_PATH_PREFIX)) return undefined;
+      const prop = path.slice(STYLE_PATH_PREFIX.length);
+      const n = this.snapshot().nodes.get(id);
+      if (!n) return undefined;
+      const raw = styleProp(n.el.style, prop);
+      const declaredType = STYLE_PROPERTY_TYPE.get(prop);
+      if (declaredType === 'number') return numericStyleValue(raw);
+      if (declaredType === 'color') return cssColorToHex(raw);
+      return raw;
+    },
+    set: (id, path, value) => {
+      if (path === 'locked') {
+        if (value) this.lockedIds.add(id);
+        else this.lockedIds.delete(id);
+        this.store.notifyIngestEdit();
+        return;
+      }
+      if (path === 'visible') {
+        this.writeStyle(id, 'visibility', value ? 'visible' : 'hidden');
+        return;
+      }
+      if (!path.startsWith(STYLE_PATH_PREFIX)) return;
+      const prop = path.slice(STYLE_PATH_PREFIX.length);
+      this.writeStyle(id, prop, String(value));
+    },
+  };
+
+  /**
+   * T0 (spec 27 §4, B1) — the write body extracted from {@link writeStyle}, RETURNING
+   * the resulting {@link PendingUndo} entry instead of pushing it, so a caller that
+   * writes MULTIPLE props for one logical gesture ({@link commitBoxEdit}) can compose
+   * them into a single undo entry itself. `writeStyle` (below) is now a one-line
+   * wrapper — identical behavior for its existing single-prop caller (`inspector.set`).
+   * `priorInlineOverride`, when given, is used as the captured PRE-gesture inline value
+   * instead of re-reading `n.el.style` — needed because `boxEdit.apply` already mutated
+   * the live inline style for preview before `end` gets here (see `boxEditSession`'s
+   * doc comment). D-K2's restore-BOTH-halves invariant (inline AND overlay) is
+   * unchanged — only WHERE `prevInline` comes from differs when an override is given.
+   */
+  private writeStyleEntry(
+    id: string,
+    prop: string,
+    value: string,
+    priorInlineOverride?: string,
+  ): PendingUndo | null {
+    const n = this.snapshot().nodes.get(id);
+    if (!n) return null;
+    const prevRaw =
+      priorInlineOverride !== undefined ? priorInlineOverride : styleProp(n.el.style, prop);
+    const prevInline = prevRaw == null ? '' : String(prevRaw);
+    const existingEntry = this.doc[id];
+    const hadOverlayEntry = existingEntry ? Object.hasOwn(existingEntry, prop) : false;
+    const prevOverlayValue = existingEntry?.[prop];
+
+    this.applyStyleToElement(n.el, prop, value);
+    this.recordOverlayEntry(id, prop, value);
+    this.dirty = true;
+    this.store.notifyIngestEdit();
+
+    return {
+      undo: () => {
+        // Re-resolve rather than cache the element ref — the DOM is live and
+        // may have re-rendered since this entry was pushed (same discipline
+        // as `ReactWorldAuthoringAdapter.applyStyleWrite`).
+        const cur = this.snapshot().nodes.get(id);
+        if (cur) this.applyStyleToElement(cur.el, prop, prevInline);
+        if (hadOverlayEntry) this.recordOverlayEntry(id, prop, prevOverlayValue!);
+        else this.removeOverlayEntry(id, prop);
+        this.store.notifyIngestEdit();
+      },
+      redo: () => {
+        const cur = this.snapshot().nodes.get(id);
+        if (cur) this.applyStyleToElement(cur.el, prop, value);
+        this.recordOverlayEntry(id, prop, value);
+        this.store.notifyIngestEdit();
+      },
+    };
+  }
+
+  /**
+   * D-K2: mutate the live element's inline style AND the overlay document,
+   * mark dirty, push an adapter-local undo entry that restores BOTH the
+   * prior inline value and the prior overlay-entry state (present, absent,
+   * or a different value) — never just one half (AC-K6).
+   */
+  private writeStyle(id: string, prop: string, value: string): void {
+    const entry = this.writeStyleEntry(id, prop, value);
+    if (entry) this.pushUndo(entry);
+  }
+
+  private pushUndo(entry: PendingUndo): void {
+    this.undoStack.push(entry);
+    this.redoStack.length = 0;
+    notifyUndoableOp(this);
+  }
+
+  undo(): boolean {
+    const e = this.undoStack.pop();
+    if (!e) return false;
+    e.undo();
+    this.redoStack.push(e);
+    return true;
+  }
+
+  redo(): boolean {
+    const e = this.redoStack.pop();
+    if (!e) return false;
+    e.redo();
+    this.undoStack.push(e);
+    return true;
+  }
+
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener);
+  }
+
+  // A class GETTER, not a field initializer — same reason as every other
+  // adapter here (`ui-authoring-adapter.ts`/`vgai-scene-authoring-adapter.ts`):
+  // a field initializer runs before the constructor body assigns
+  // `this.destinationPath`/`this.persistFn`.
+  get persistence(): PersistenceProvider {
+    return {
+      isDirty: () => this.dirty,
+      save: async () => {
+        await this.persistFn(this.doc);
+        this.dirty = false;
+      },
+      serialize: () => this.doc,
+      destination: this.destinationPath,
+    };
+  }
+}