@vgai/editor 0.2.0

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

@@ -0,0 +1,2400 @@
+/**
+ * ReactWorldAuthoringAdapter — the editor's {@link AuthoringAdapter} for a react-kind
+ * world (T6.2 slice 2, `docs/REACT-WORLD-DESIGN.md` §1.D/§1.E/§3 slice 2).
+ *
+ * A react world has no GameComponents, no ticking, no mirror (D8) — its authoring
+ * entities ARE the `data-oid`-stamped elements of its rendered DOM (the OID
+ * instrumentation from the UI visual-edit program, `../ui-source/oid-transform.ts`,
+ * whose vite-plugin include this slice widens from the `editable-components` fixture
+ * dir to project scope — see `../../vite-plugin-ui-oid.ts`). This adapter derives its
+ * hierarchy by walking the world's live DOM root (`WorldInstance.reactRoot()`) for
+ * `data-oid`-carrying elements, tree-ordered; there is no cached/mirrored state to
+ * fall out of sync — every `hierarchy` call re-walks the live DOM.
+ *
+ * Writes (style/className/delete) reuse the EXISTING T3.2-slice-3 source-write seam
+ * verbatim (`../ui-source/source-write-backend.ts`'s `SourceWriteBackend`, the same
+ * `/__ui-source/write` + `/__ui-source/struct` dev-server endpoints
+ * `vite-plugin-ui-oid.ts` serves for `UIAuthoringAdapter`/`SourceEditPanel`) — this
+ * file does NOT invent a second source-writer. What IS new here (§1.E): edits enter
+ * the T3.2 global undo timeline as INVERSE-WRITE entries — the prior literal (read
+ * off the live DOM before the write) is captured and written back on undo. Structural
+ * ops (D-1, Phase D, spec27 §2) use a DIFFERENT inverse — a per-OID one is unsound for
+ * them (OIDs are content-signature keyed; `reorder`/`delete` reassign occurrence
+ * indices; `delete` has no inverse payload at all) — a checksum-guarded WHOLE-FILE
+ * snapshot restore instead (`pushStructUndo`/`restoreStructSnapshot`,
+ * `SourceWriteBackend.restoreSource`), so every structural op (including `delete`) now
+ * pushes exactly one undo entry.
+ *
+ * Persistence mirrors `UIAuthoringAdapter`'s de-stubbed pattern exactly: writes are
+ * immediate (server-side, on commit), so `save()` is an honest no-op; `destination`
+ * reports whether a source-write backend even exists in this session (absent in a
+ * hosted/no-dev-server build — selection/inspection still work, writes report
+ * unavailable via a loud console warning instead of silently no-op'ing).
+ */
+import type {
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  BoxEditProvider,
+  ColorSampleProvider,
+  DOMRectLike,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  RectProvider,
+  SelectionProvider,
+  StoriesProvider,
+  StoryRef,
+  StructureProvider,
+  TextProvider,
+} from '@engine/adapter';
+import type { UIStory } from '@vgai/scene-ui/registry';
+import type { UIComponentRegistry } from '@vgai/scene-ui/SceneUI';
+import type { EditorStore } from '../editor-store';
+import {
+  browserOrInlineResolver,
+  type ComputedStyleResolver,
+  type DesignToken,
+  type EmptyCandidate,
+  findEmptyContainers,
+  getComponentProps,
+  getComputedStyleValue,
+  getDesignTokens,
+  getMatchedCssRules,
+  getReactComponentName,
+  type MatchableElement,
+} from '../ui-source/inspect';
+import type { OidEntry } from '../ui-source/oid-transform';
+import type { SourceWriteBackend } from '../ui-source/source-write-backend';
+import { type CssRuleTarget, pickCssRuleTarget } from '../ui-source/writer';
+import { getStoryOverlay, setStoryOverlay } from './story-overlay';
+import { notifyUndoableOp, registerUndoAdapter } from './undo-timeline';
+
+/**
+ * The minimal structural shape this adapter needs from a live DOM element —
+ * deliberately NOT `HTMLElement` so it stays testable with a plain-object fixture
+ * headlessly (this repo's vitest environment is `node`, no jsdom — see
+ * `docs/REACT-WORLD-DESIGN.md`'s slice-2 dispatch: "use the repo's DOM-stub +
+ * fixture patterns"). A real `HTMLElement` satisfies this structurally: `tagName`
+ * (uppercase, per the DOM spec — lower-cased for labels/kind below), `children`
+ * (an `HTMLCollection`, `Array.from`-able), and `getAttribute` reading the REAL
+ * `data-oid="…"` attribute `transformSource` stamped into the JSX (a genuine DOM
+ * attribute at runtime, not a mirror).
+ */
+export interface OidElementLike {
+  readonly tagName: string;
+  readonly children: ArrayLike<OidElementLike>;
+  getAttribute(name: string): string | null;
+  /**
+   * `unknown` rather than a structural record — a real `CSSStyleDeclaration` has
+   * NO string index signature (TS models it as a fixed set of named properties
+   * plus methods), so it can't structurally satisfy `Record<string, unknown>`.
+   * Read through {@link styleProp} below, which handles both shapes.
+   */
+  readonly style?: unknown;
+  /**
+   * D12 (B4) — the element's live viewport rect, for `pickable.pick`'s
+   * geometric hit-test (see that provider's doc comment for why NOT
+   * `elementFromPoint`). Optional so existing plain-object test fixtures
+   * (which never provide one) keep type-checking unchanged — a node with no
+   * `getBoundingClientRect` simply never wins a pick (its rect is treated as
+   * absent, never a fabricated 0×0 that could win a tie).
+   */
+  getBoundingClientRect?(): {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+  };
+  /**
+   * T0 (spec 27 §2) — the element's rendered text, read for `TextProvider.get`'s
+   * "has child elements" gate below. Optional so pre-existing `OidElementLike`
+   * fixtures (none of which set it) keep satisfying the interface unchanged.
+   */
+  readonly textContent?: string | null;
+}
+
+/** Read one style property off an `OidElementLike.style` of either shape (a real
+ *  `CSSStyleDeclaration` or a plain-object test fixture). */
+export function styleProp(style: unknown, prop: string): unknown {
+  return style ? (style as Record<string, unknown>)[prop] : undefined;
+}
+
+/**
+ * Parse a real `CSSStyleDeclaration`'s length-property VALUE (always a
+ * unit-suffixed STRING, e.g. `"16px"` — CSSOM never hands back a bare
+ * number) into the plain number a `type: 'number'` {@link PropertyDescriptor}
+ * needs to render/edit correctly (`Inspector.tsx`'s generic renderer does
+ * `typeof v === 'number' ? … : 0` — without this parse, EVERY numeric style
+ * field would silently display `0` against a real browser DOM, even though
+ * the property test fixtures (`react-world-authoring-adapter.test.ts`'s
+ * plain-object `style: {}`) never caught it, because a hand-built fixture
+ * can hold a bare JS number directly). Strips a trailing CSS unit
+ * (`px`/`em`/`rem`/`%`/`vh`/`vw`, mirroring `writer.ts`'s own `LITERAL_RE`
+ * unit set); a value this repo's fixtures already hand over AS a number
+ * (or `undefined`/unset) passes through unchanged.
+ */
+export function numericStyleValue(raw: unknown): number | undefined {
+  if (typeof raw === 'number') return raw;
+  if (typeof raw !== 'string' || raw === '') return undefined;
+  const parsed = Number.parseFloat(raw);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+const RGB_RE = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+\s*)?\)$/;
+
+/**
+ * Normalize a CSS color VALUE into `#rrggbb` for a `type: 'color'`
+ * {@link PropertyDescriptor} (`<input type="color">` only accepts exactly
+ * that shape — an unparseable value makes the browser silently coerce the
+ * input to black). A real `CSSStyleDeclaration` always serializes an inline
+ * color property as `rgb(r, g, b)`/`rgba(r, g, b, a)` — EVEN WHEN the author
+ * wrote a hex literal in JSX (`el.style.color = '#3ddc65'` reads back as
+ * `"rgb(61, 220, 101)"`, verified empirically against a real Chromium page,
+ * not assumed) — never hex. Without this normalization every color-typed
+ * style field would show black regardless of its real value against a real
+ * browser DOM (the plain-object test fixtures never caught this: a
+ * hand-built fixture's `style` can hold the author's hex string directly,
+ * which real CSSOM never does). An already-hex value (a fixture, or a
+ * property this repo's CSSOM happens to serialize as hex) passes through
+ * unchanged; a value matching neither shape returns `undefined` (the
+ * generic inspector's own '#ffffff' fallback) rather than handing the input
+ * an invalid string.
+ */
+export function cssColorToHex(raw: unknown): string | undefined {
+  if (typeof raw !== 'string' || raw === '') return undefined;
+  if (raw.startsWith('#')) return raw;
+  const m = RGB_RE.exec(raw);
+  if (!m) return undefined;
+  const toHex = (n: string) => Number.parseInt(n, 10).toString(16).padStart(2, '0');
+  return `#${toHex(m[1]!)}${toHex(m[2]!)}${toHex(m[3]!)}`;
+}
+
+/** One resolved `BoxEditProvider` patch-key mapping (spec 27 §4, B1). */
+export interface BoxEditPropMapping {
+  /** The CSS style prop to write (already the target, e.g. `x` → `left`). */
+  prop: string;
+  /** Live-preview CSS VALUE for a raw patch number — always px-suffixed for
+   *  spatial/spacing props, the `rotate(<deg>deg)` transform string for `rotate`. */
+  cssValue: (v: number) => string;
+}
+
+/**
+ * `BoxEditProvider` patch-key → CSS-prop mapping (spec 27 B1), shared by BOTH
+ * authoring adapters' `boxEdit.apply/end` (`react-dom-authoring-adapter.ts`
+ * imports this rather than redefining it — same DRY reuse as
+ * {@link cssColorToHex}/{@link numericStyleValue}/{@link styleProp} below).
+ * `width`/`height`/`margin*`/`padding*` map 1:1 to their same-named style
+ * prop. `x`/`y` map to `left`/`top` ONLY when the node is
+ * absolutely/fixed-positioned (there is no `left`/`top` to move on a
+ * static/relative node) — `isPositioned` is a caller-resolved boolean (each
+ * adapter reads its own computed-style resolver) — a mismatched key returns
+ * `null` to mean "drop this key"; the CALLER does its own loud
+ * `console.warn` so the adapter's own name appears in the message. `rotate`
+ * (deg) maps to the `transform` prop as a `rotate(<deg>deg)` string.
+ */
+export function mapBoxEditPatchKey(key: string, isPositioned: boolean): BoxEditPropMapping | null {
+  switch (key) {
+    case 'width':
+    case 'height':
+    case 'marginTop':
+    case 'marginRight':
+    case 'marginBottom':
+    case 'marginLeft':
+    case 'paddingTop':
+    case 'paddingRight':
+    case 'paddingBottom':
+    case 'paddingLeft':
+      return { prop: key, cssValue: (v) => `${v}px` };
+    case 'x':
+      return isPositioned ? { prop: 'left', cssValue: (v) => `${v}px` } : null;
+    case 'y':
+      return isPositioned ? { prop: 'top', cssValue: (v) => `${v}px` } : null;
+    case 'rotate':
+      return { prop: 'transform', cssValue: (v) => `rotate(${v}deg)` };
+    default:
+      return null;
+  }
+}
+
+const OID_ATTR = 'data-oid';
+
+/** One OID-tagged DOM element resolved into the adapter's internal tree. */
+interface OidNode {
+  /** Disambiguated entity id — see {@link walkOidTree}'s doc comment. */
+  id: string;
+  /** The raw OID (may repeat across sibling `OidNode`s — see below). */
+  oid: string;
+  tag: string;
+  el: OidElementLike;
+  parentId: string | null;
+  childIds: string[];
+}
+
+export interface OidTree {
+  /** Every OID-tagged node, keyed by its (disambiguated) entity id. */
+  nodes: Map<string, OidNode>;
+  /** Top-level entity ids (no OID-tagged ancestor) in DOM/tree order. */
+  rootIds: string[];
+}
+
+/**
+ * Walk a react world's live DOM root for `data-oid`-carrying elements, tree-ordered
+ * (§1.D: "React entities = the OID tree; the live DOM carries it").
+ *
+ * OID → entity id disambiguation: the OID is a SOURCE-content signature
+ * (`component:tag:nthOccurrence` — see `oid-transform.ts`), not a per-DOM-instance
+ * id — a list rendered from ONE JSX line (`items.map(...)`) stamps the SAME `data-
+ * oid` on every rendered item. Since an `EditorNode.id` must be unique per
+ * SELECTABLE entity, repeats are disambiguated by DOM-order OCCURRENCE within this
+ * walk: the first element carrying a given oid keeps `id === oid`; the Nth repeat
+ * (0-based) gets `id === "${oid}#${n}"`. This is deliberately NOT persisted/hashed
+ * across renders beyond "same relative position, same id" — stable enough for
+ * selection/inspection within a session, honestly component-global (not
+ * per-instance) for writes, exactly like every other OID-keyed edit in this
+ * program (a style/delete write on ANY repeat edits the ONE shared JSX source).
+ *
+ * An element with no `data-oid` (e.g. DOM emitted by an un-instrumented library,
+ * or a plain intrinsic a Fragment wrapped) is transparently skipped — its own
+ * children attach to the nearest OID-tagged ANCESTOR, not to it, so a gap in
+ * instrumentation never breaks the tree into disconnected pieces.
+ */
+export function walkOidTree(root: OidElementLike): OidTree {
+  const nodes = new Map<string, OidNode>();
+  const rootIds: string[] = [];
+  const occurrence = new Map<string, number>();
+
+  function visit(el: OidElementLike, parentId: string | null): void {
+    const oid = el.getAttribute(OID_ATTR);
+    let effectiveParent = parentId;
+    if (oid) {
+      const n = occurrence.get(oid) ?? 0;
+      occurrence.set(oid, n + 1);
+      const id = n === 0 ? oid : `${oid}#${n}`;
+      const node: OidNode = {
+        id,
+        oid,
+        tag: el.tagName.toLowerCase(),
+        el,
+        parentId,
+        childIds: [],
+      };
+      nodes.set(id, node);
+      if (parentId) nodes.get(parentId)?.childIds.push(id);
+      else rootIds.push(id);
+      effectiveParent = id;
+    }
+    for (const child of Array.from(el.children)) visit(child, effectiveParent);
+  }
+
+  for (const child of Array.from(root.children)) visit(child, null);
+  return { nodes, rootIds };
+}
+
+/**
+ * Cap 6 (React visual-edit parity): the RICH GROUPED inspector model — the figma-style
+ * panels (Layout / Position / Spacing / Type / Fill / Stroke / Effects / Transform), each
+ * property tagged with a `group` the generic inspector renders as a titled sub-section
+ * (`PropertyDescriptor.group`). Every property here is covered by the writer's broadened
+ * `ARB_MAP`/`ENUM_UTILITIES` class routing (or inline style), so a set writes real source.
+ * (Bespoke widgets — HSV picker, scrub inputs, gradient/multi-shadow editors — are the
+ * one descoped part of Cap 6; the generic color/number/enum/string inputs render each of
+ * these functionally.)
+ */
+const STYLE_PROPERTIES: ReadonlyArray<{
+  prop: string;
+  label: string;
+  type: PropertyDescriptor['type'];
+  group: string;
+  options?: string[];
+}> = [
+  // -- Layout --
+  {
+    prop: 'display',
+    label: 'Display',
+    type: 'enum',
+    group: 'Layout',
+    options: ['block', 'flex', 'grid', 'inline', 'inline-block', 'inline-flex', 'none'],
+  },
+  {
+    prop: 'flexDirection',
+    label: 'Direction',
+    type: 'enum',
+    group: 'Layout',
+    options: ['row', 'column', 'row-reverse', 'column-reverse'],
+  },
+  {
+    prop: 'flexWrap',
+    label: 'Wrap',
+    type: 'enum',
+    group: 'Layout',
+    options: ['nowrap', 'wrap', 'wrap-reverse'],
+  },
+  {
+    prop: 'justifyContent',
+    label: 'Justify',
+    type: 'enum',
+    group: 'Layout',
+    options: ['flex-start', 'center', 'flex-end', 'space-between', 'space-around', 'space-evenly'],
+  },
+  {
+    prop: 'alignItems',
+    label: 'Align',
+    type: 'enum',
+    group: 'Layout',
+    options: ['stretch', 'flex-start', 'center', 'flex-end', 'baseline'],
+  },
+  { prop: 'gap', label: 'Gap', type: 'number', group: 'Layout' },
+  {
+    prop: 'overflow',
+    label: 'Overflow',
+    type: 'enum',
+    group: 'Layout',
+    options: ['visible', 'hidden', 'scroll', 'auto'],
+  },
+  { prop: 'width', label: 'Width', type: 'number', group: 'Layout' },
+  { prop: 'height', label: 'Height', type: 'number', group: 'Layout' },
+  { prop: 'minWidth', label: 'Min W', type: 'number', group: 'Layout' },
+  { prop: 'minHeight', label: 'Min H', type: 'number', group: 'Layout' },
+  { prop: 'maxWidth', label: 'Max W', type: 'number', group: 'Layout' },
+  { prop: 'maxHeight', label: 'Max H', type: 'number', group: 'Layout' },
+  // -- Position --
+  {
+    prop: 'position',
+    label: 'Position',
+    type: 'enum',
+    group: 'Position',
+    options: ['static', 'relative', 'absolute', 'fixed', 'sticky'],
+  },
+  { prop: 'top', label: 'Top', type: 'number', group: 'Position' },
+  { prop: 'right', label: 'Right', type: 'number', group: 'Position' },
+  { prop: 'bottom', label: 'Bottom', type: 'number', group: 'Position' },
+  { prop: 'left', label: 'Left', type: 'number', group: 'Position' },
+  { prop: 'zIndex', label: 'Z Index', type: 'number', group: 'Position' },
+  { prop: 'flexGrow', label: 'Grow', type: 'number', group: 'Position' },
+  { prop: 'flexShrink', label: 'Shrink', type: 'number', group: 'Position' },
+  // -- Spacing (per-side) --
+  { prop: 'marginTop', label: 'Margin T', type: 'number', group: 'Spacing' },
+  { prop: 'marginRight', label: 'Margin R', type: 'number', group: 'Spacing' },
+  { prop: 'marginBottom', label: 'Margin B', type: 'number', group: 'Spacing' },
+  { prop: 'marginLeft', label: 'Margin L', type: 'number', group: 'Spacing' },
+  { prop: 'paddingTop', label: 'Padding T', type: 'number', group: 'Spacing' },
+  { prop: 'paddingRight', label: 'Padding R', type: 'number', group: 'Spacing' },
+  { prop: 'paddingBottom', label: 'Padding B', type: 'number', group: 'Spacing' },
+  { prop: 'paddingLeft', label: 'Padding L', type: 'number', group: 'Spacing' },
+  // -- Type --
+  { prop: 'color', label: 'Color', type: 'color', group: 'Type' },
+  { prop: 'fontSize', label: 'Size', type: 'number', group: 'Type' },
+  { prop: 'fontWeight', label: 'Weight', type: 'string', group: 'Type' },
+  { prop: 'lineHeight', label: 'Line H', type: 'string', group: 'Type' },
+  { prop: 'letterSpacing', label: 'Spacing', type: 'string', group: 'Type' },
+  {
+    prop: 'textAlign',
+    label: 'Align',
+    type: 'enum',
+    group: 'Type',
+    options: ['left', 'center', 'right', 'justify'],
+  },
+  {
+    prop: 'textTransform',
+    label: 'Transform',
+    type: 'enum',
+    group: 'Type',
+    options: ['none', 'uppercase', 'lowercase', 'capitalize'],
+  },
+  { prop: 'fontStyle', label: 'Style', type: 'enum', group: 'Type', options: ['normal', 'italic'] },
+  { prop: 'fontFamily', label: 'Font', type: 'string', group: 'Type' },
+  {
+    prop: 'textDecoration',
+    label: 'Decoration',
+    type: 'enum',
+    group: 'Type',
+    options: ['none', 'underline', 'line-through', 'overline'],
+  },
+  // -- Fill --
+  { prop: 'backgroundColor', label: 'Background', type: 'color', group: 'Fill' },
+  // Cap 6 (§5 gap-fill): computed style never round-trips the `background`
+  // shorthand — `backgroundImage` is the prop that actually reads back
+  // (see `inspector.get`'s computed-style path below), so the gradient
+  // widget for a STYLE property must key off it, not `background`.
+  { prop: 'backgroundImage', label: 'Gradient', type: 'string', group: 'Fill' },
+  // -- Stroke --
+  { prop: 'borderColor', label: 'Border Color', type: 'color', group: 'Stroke' },
+  { prop: 'borderWidth', label: 'Border Width', type: 'number', group: 'Stroke' },
+  {
+    prop: 'borderStyle',
+    label: 'Border Style',
+    type: 'enum',
+    group: 'Stroke',
+    options: ['none', 'solid', 'dashed', 'dotted', 'double'],
+  },
+  { prop: 'borderRadius', label: 'Radius', type: 'number', group: 'Stroke' },
+  // -- Effects --
+  { prop: 'opacity', label: 'Opacity', type: 'number', group: 'Effects' },
+  { prop: 'boxShadow', label: 'Box Shadow', type: 'string', group: 'Effects' },
+  {
+    prop: 'mixBlendMode',
+    label: 'Blend',
+    type: 'enum',
+    group: 'Effects',
+    options: ['normal', 'multiply', 'screen', 'overlay'],
+  },
+  { prop: 'filter', label: 'Filter', type: 'string', group: 'Effects' },
+  { prop: 'backdropFilter', label: 'Backdrop', type: 'string', group: 'Effects' },
+  { prop: 'textShadow', label: 'Text Shadow', type: 'string', group: 'Effects' },
+  {
+    prop: 'cursor',
+    label: 'Cursor',
+    type: 'enum',
+    group: 'Effects',
+    options: ['auto', 'default', 'pointer', 'text', 'move', 'grab', 'not-allowed'],
+  },
+  // -- Transform --
+  { prop: 'transform', label: 'Transform', type: 'string', group: 'Transform' },
+];
+const STYLE_PATH_PREFIX = 'style.';
+/** Cap 4: inspector path prefix for a component's editable props (`prop.<name>`). */
+const PROP_PATH_PREFIX = 'prop.';
+/** Cap 7: inspector path prefix for the document's design tokens (`token.<name>`). */
+const TOKEN_PATH_PREFIX = 'token.';
+/** D3.R1 (spec 27 §2/§5 U4 precedent, reopen fix) — the `dynamicPaths` key for
+ *  Cap 3's text edit (`editText`), so a dynamic-body refusal is recorded and
+ *  surfaced through the SAME session-scoped after-touch mechanism the
+ *  style/prop U4 widgets use — not a real inspector path (text has no
+ *  `properties()` descriptor), just a stable key for `` `${id}|${TEXT_PATH}` ``. */
+const TEXT_PATH = 'text';
+/** B3 — catalog node id prefix (`catalog:<registryKey>`) and the one
+ *  `entry (live preview)` node id, collision-proof against OID-derived ids
+ *  (`o<counter36><hash36>`, never containing `:`) and composite ids
+ *  (`world:<id>`, only ever seen by the COMPOSITE, never by this adapter). */
+const CATALOG_ID_PREFIX = 'catalog:';
+const CATALOG_ENTRY_ID = 'catalog-entry';
+/** B3 — inspector path prefix for a catalog node's active-story props
+ *  (`storyProp.<name>`) — deliberately distinct from {@link PROP_PATH_PREFIX}
+ *  (a DOM node's live fiber props): a catalog node has no call site to read a
+ *  fiber from (see `inspector.properties`'s catalog branch doc comment). */
+const STORY_PROP_PATH_PREFIX = 'storyProp.';
+
+/** `prop -> declared type`, so `inspector.get()` knows when to run a style
+ *  value through {@link numericStyleValue} instead of handing it back raw
+ *  (a real CSSOM length value is always a unit-suffixed string). */
+const STYLE_PROPERTY_TYPE: ReadonlyMap<string, PropertyDescriptor['type']> = new Map(
+  STYLE_PROPERTIES.map(({ prop, type }) => [prop, type]),
+);
+
+/**
+ * U2 (spec 27 §5 C2) — a per-side/per-corner CSS LONGHAND → the SHORTHAND that
+ * governs it in the longhand's absence. Used by `inspector.remove` (below): when
+ * a uniform border/radius edit removes a stale longhand override, the removed
+ * longhand's optimistic echo is set to the shorthand's current (just-committed)
+ * value — so an `inspector.get(longhand)` right after removal reports the value
+ * the corner actually renders at (the shorthand), not a stale override or an
+ * empty computed read, and it stays consistent once HMR clears the echo (the
+ * longhand is gone from source, so the shorthand cascades to it). Purely the
+ * longhands the C2 combo rows can write — the shorthand set itself is uniform.
+ */
+const LONGHAND_TO_SHORTHAND: Readonly<Record<string, string>> = {
+  borderTopLeftRadius: 'borderRadius',
+  borderTopRightRadius: 'borderRadius',
+  borderBottomLeftRadius: 'borderRadius',
+  borderBottomRightRadius: 'borderRadius',
+  borderTopWidth: 'borderWidth',
+  borderRightWidth: 'borderWidth',
+  borderBottomWidth: 'borderWidth',
+  borderLeftWidth: 'borderWidth',
+  borderTopStyle: 'borderStyle',
+  borderRightStyle: 'borderStyle',
+  borderBottomStyle: 'borderStyle',
+  borderLeftStyle: 'borderStyle',
+  borderTopColor: 'borderColor',
+  borderRightColor: 'borderColor',
+  borderBottomColor: 'borderColor',
+  borderLeftColor: 'borderColor',
+};
+
+/**
+ * D3.e (spec 27 §2 T0 leftover, §6 D3 "Insert-child submenu") — the kinds
+ * `structure.create`'s `wrapperTag` genuinely inserts. `insertChildElement`
+ * (`ui-source/writer.ts:1036`) writes `<tag />` VERBATIM for whatever tag
+ * string it is given — it has no allow-list of its own, and no void/non-void
+ * element distinction (every insert is self-closing, syntactically valid
+ * JSX for every one of these real HTML element names). So this is a CURATED
+ * subset, not a writer-enforced ceiling — the same "small sensible palette,
+ * not the writer's full permissiveness" stance `ui-authoring-adapter.ts`'s
+ * own `CREATABLE_KINDS` doc comment takes (there for UINode kinds; here for
+ * literal HTML tag names, since a react-world node's "kind" IS its tag).
+ */
+const CREATABLE_KINDS: ReadonlyArray<{ kind: string; label: string }> = [
+  { kind: 'div', label: 'Container' },
+  { kind: 'span', label: 'Text' },
+  { kind: 'p', label: 'Paragraph' },
+  { kind: 'button', label: 'Button' },
+  { kind: 'a', label: 'Link' },
+  { kind: 'img', label: 'Image' },
+  { kind: 'ul', label: 'List' },
+  { kind: 'li', label: 'List Item' },
+];
+
+interface PendingUndo {
+  undo: () => void;
+  redo: () => void;
+}
+
+export interface ReactWorldAuthoringOptions {
+  /** T3.2 slice-3 write seam. Absent ⇒ no dev-server backend in this session (a
+   *  hosted/browser build) — selection/inspection still work; writes report
+   *  unavailable (see the class doc comment). */
+  writeBackend?: SourceWriteBackend | undefined;
+  /** Cap 1 (React visual-edit parity): resolves an element to its COMPUTED style so
+   *  `inspector.get` reflects class- and CSS-file-styled properties, not just inline
+   *  style. Defaults to `window.getComputedStyle` in a browser, or the element's inline
+   *  `.style` under vitest's `node` env (so headless fixtures work). Injectable for
+   *  headless tests that want to drive the real computed-value path. */
+  computedStyle?: ComputedStyleResolver | undefined;
+  /** Cap 2 (React visual-edit parity): resolves an element to the first-party CSS rules
+   *  that match it (source file + selector + declared properties), so a style edit whose
+   *  property lives in a CSS FILE routes to that file instead of inline/class. Defaults to
+   *  `inspect.ts`'s `getMatchedCssRules` against the live document. Injectable for headless
+   *  tests. */
+  matchedCssRules?: ((el: unknown) => CssRuleTarget[]) | undefined;
+  /** Cap 7 (React visual-edit parity): the document's design tokens (`:root` custom
+   *  properties). Defaults to `inspect.ts`'s `getDesignTokens` against the live `:root`
+   *  (empty under vitest's `node` env). Injectable for headless tests. */
+  designTokens?: (() => DesignToken[]) | undefined;
+  /**
+   * D4 — ordered stories sources (Q2 decoupling: the provider takes stories
+   * as a constructor input, a project's `src/ui/registry.ts` is merely the
+   * DEFAULT source — an editor-side overlay, `../authoring/story-overlay.ts`,
+   * plugs into the same parameter). Later sources win over earlier ones,
+   * per story id — see {@link ReactWorldAuthoringAdapter.stories}. Absent/
+   * empty ⇒ `storiesFor` returns `[]` for every node (today's B1 behavior,
+   * no registry case).
+   */
+  storySources?: ReadonlyArray<Record<string, UIStory>> | undefined;
+  /**
+   * D4 — invoked whenever `stories.apply` changes the active story
+   * (including clearing it to `null`). The caller (`design-time-layers.ts`'s
+   * `mountReactLayer`) re-renders the layer root against the story's `data`/
+   * `props` — this adapter never touches the DOM/React tree itself, it only
+   * tracks WHICH story is active and reports the change.
+   */
+  onStoryApplied?: ((story: (UIStory & { id: string }) | null) => void) | undefined;
+  /**
+   * B3 — the react world's registered components (a project's
+   * `src/ui/registry.ts` `components`, `SceneUI.tsx`'s flat
+   * `Record<string, ComponentType>`, NO metadata). Absent/EMPTY ⇒ this
+   * adapter's hierarchy is the plain DOM walk, byte-identical to pre-B3
+   * (§0's gate — `play-mode.ts`'s `installMultiWorldAuthoring` never passes
+   * this option, so PLAY mode's react-world hierarchy is untouched by B3's
+   * construction). Non-empty ⇒ `hierarchy.roots()` becomes the CATALOG: one
+   * `kind:'component'` node per registered key, plus one `'entry (live
+   * preview)'` node nesting the ordinary DOM-walk roots one level down (see
+   * the class doc comment's storybook-model rationale and
+   * `docs/unified-world-editor/26-unified-editor-spec.md` §3 B3).
+   */
+  catalogComponents?: UIComponentRegistry | undefined;
+  /**
+   * B3 — invoked whenever `stories.isolate` changes the isolated view
+   * (including clearing it to `null`, restoring the entry). The caller
+   * (`design-time-layers.ts`'s `mountReactLayer`) re-renders the layer root
+   * against the isolated component + story (or back to the entry) — this
+   * adapter never touches the DOM/React tree itself, it only tracks WHICH
+   * catalog node is isolated and reports the change.
+   */
+  onIsolate?:
+    | ((v: { componentKey: string; story: (UIStory & { id: string }) | null } | null) => void)
+    | undefined;
+  /**
+   * B3 — this world's manifest id. Needed ONLY to key a catalog node's
+   * writable story-prop edits into the B2 story-overlay
+   * (`../authoring/story-overlay.ts`'s per-worldId slot) — every OTHER
+   * option/method in this adapter is worldId-agnostic. Absent ⇒ catalog
+   * inspector prop writes report unavailable (there is no world to key the
+   * overlay by) rather than silently no-op'ing — see `writeStoryProp`.
+   */
+  worldId?: string | undefined;
+}
+
+export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities;
+  private readonly writeBackend: SourceWriteBackend | undefined;
+  private readonly computedStyle: ComputedStyleResolver;
+  private readonly matchedCssRules: (el: unknown) => CssRuleTarget[];
+  private readonly designTokens: () => DesignToken[];
+  /** OID → {component, tag, …} labels, fetched once (if a backend exists) from the
+   *  SAME `/__ui-source/index` the OID store already serves — see `index()` on
+   *  `SourceWriteBackend`. Absent/unresolved ⇒ nodes label from the DOM tag alone
+   *  (honest degradation, not a second index). */
+  private oidIndex: Map<string, OidEntry> = new Map();
+  private dirty = false;
+  /**
+   * A4 (spec 27 §3) — the optimistic value echo. `inspector.set` writes the just-committed
+   * value here BEFORE its async source-write returns; `inspector.get` reads THROUGH it (a
+   * hit wins over the live-DOM walk), so an edited field shows the NEW value within one
+   * frame of commit instead of snapping back to the old value until the source-write + Vite
+   * HMR re-render land (that timing WAS the desync bug). Keyed by OID-signature entity id
+   * (which survives the react remount — see {@link walkOidTree}) → full inspector path →
+   * value. Cleared per-entry the instant a write is refused/coerced-away (so it can't go
+   * stale showing a value the source never took), and wholesale once HMR actually lands
+   * ({@link reconcileEchoAfterReload}) so the now-updated live DOM is authoritative again.
+   */
+  private readonly valueEcho = new Map<string, Map<string, unknown>>();
+  /**
+   * U4 (spec 27 §5 "Widgets: dynamic-expression read-only indicator") — the
+   * smallest honest version of the indicator: no new backend literality
+   * PROBE (that's real new `SourceWriteBackend` surface, deferred to Phase-E
+   * scale). Instead this surfaces the write path's EXISTING refusal signal —
+   * `writeStyleEntry`/`writePropEdit` already set `res.dynamic` when the
+   * backend refuses because the target is a dynamic `{expression}`, clearing
+   * the optimistic echo and warning. Once THAT has happened for a given
+   * `id|path`, `properties()` marks its descriptor `readonly: true` on every
+   * subsequent call, so the widget disables itself (`KindRowProps.disabled`)
+   * instead of silently re-offering an edit the source will refuse again.
+   * This is PREDICTIVE-AFTER-TOUCH, not predictive-BEFORE-touch (the field is
+   * still editable — and will visibly refuse once — the very first time);
+   * a pre-touch indicator needs the backend probe noted above. Session-scoped
+   * (never persisted) — cleared for an id on `dispose()`-adjacent resets only
+   * via normal adapter lifetime, same scope as `valueEcho`.
+   */
+  private readonly dynamicPaths = new Set<string>();
+  /**
+   * D4 (spec27 §6 D4, layer-tree "lock" toggle) — SESSION-LOCAL node ids the
+   * layer tree/overlay has marked locked. Deliberately NOT persisted/written
+   * to source: unlike the first-party threejs adapter's `locked` (a real
+   * `SceneEntity.locked` field consumed by the viewport's raycaster), a react
+   * component has no equivalent schema field, and authoring one with no
+   * runtime reader would violate this repo's "no described field without a
+   * consumer" rule (CLAUDE.md; the SAME reason `ui.ts` dropped its dead
+   * `locked` field). Mirrors `world-session-state.ts`'s per-world pick-lock.
+   * D4.R1 — now READ by `pickable.pick` below (a locked node is skipped by
+   * canvas click/marquee pick, matching the first-party threejs raycast's
+   * own locked-skip in `viewport-raycast.ts`) and by
+   * `WorldSelectionOverlay.collectMarqueeCandidates` (via
+   * `inspector.get(id, 'locked')`, which reads this Set — see the
+   * `inspector.get`/`set` `'locked'` case below) for the marquee pool.
+   * Deliberately NOT consulted by `hierarchy`/`selection.set` — a locked
+   * node stays selectable/unlockable from the layer tree, mirroring the
+   * first-party adapter's own "locked blocks the raycast, not the
+   * hierarchy" behavior. Cleared only by adapter disposal (new Set per
+   * adapter instance/mount).
+   */
+  private readonly lockedIds = new Set<string>();
+  /**
+   * D3.R4 (reopen fix), widened by D3.R5 — a COUNTER (not a boolean) of source writes
+   * whose own pre-HMR `notifyIngestEdit()` carries no fresh DOM shape, still awaiting
+   * their post-HMR "reload landed" reconcile. Incremented by every SUCCESSFUL write on
+   * a path with no `valueEcho` of its own: `structOp`, `removeElement`,
+   * `restoreStructSnapshot` (the struct-undo/redo inverse — success only, never on a
+   * refused/sha-mismatched restore, which writes nothing and has no reload to await),
+   * `editText`'s success path, and `applyTextWrite` (the text-undo/redo inverse —
+   * again success only). D3.R4 originally covered only `structOp`/`removeElement`; the
+   * D3.R5 reopen found the SAME staleness, unflagged, at the struct-undo/redo closure
+   * (every `structOp`/`removeElement` undo routes through `restoreStructSnapshot`) and
+   * at a successful text write (`editText`/`applyTextWrite` flip `hasText`, itself a
+   * `findEmptyContainers` hint-eligibility criterion — text populates no `valueEcho`,
+   * so neither existing reconcile branch fired for it).
+   *
+   * A structural/text op's own `notifyIngestEdit()` (right after the write response
+   * lands) fires BEFORE the HMR remount that actually changes the DOM — so a memoized
+   * hover-render cache keyed on that notify's `storeVersion`
+   * (`WorldSelectionOverlay`'s `emptyHintsCacheRef`) pins the PRE-HMR tree shape.
+   * `reconcileEchoAfterReload` is the "HMR actually landed" signal; it used to no-op
+   * whenever `valueEcho` was empty — true for every one of the sites above, since only
+   * A4's value-echo path (style/prop) ever populates it.
+   *
+   * COUNTER, not boolean (the D3.R5 shape): a boolean cleared unconditionally on the
+   * FIRST reconcile after it was set, so two rapid writes each of whose OWN HMR fires a
+   * separate `vite:afterUpdate` would reconcile once and then no-op on the second
+   * reload-landed signal — the second write's hint delta going stale forever (a
+   * residual the boolean shape left undocumented). Each successful qualifying write
+   * increments this counter; `reconcileEchoAfterReload` notifies and decrements by
+   * exactly one whenever it is above zero (in addition to notifying whenever `valueEcho`
+   * is non-empty), so N pending writes need N reconciles to fully drain — matching N
+   * real `vite:afterUpdate` events in production.
+   */
+  private pendingSourceReconcile = 0;
+  /** A4 — unsubscribes this adapter's `vite:afterUpdate` reconcile hook (see the constructor);
+   *  `undefined` when there is no HMR context (hosted build / vitest `node` env). */
+  private readonly disposeReloadSignal: (() => void) | undefined;
+  private readonly undoStack: PendingUndo[] = [];
+  private readonly redoStack: PendingUndo[] = [];
+  private readonly storySources: ReadonlyArray<Record<string, UIStory>>;
+  private readonly onStoryApplied: ((story: (UIStory & { id: string }) | null) => void) | undefined;
+  /** D4 — the currently-applied story id for this world (world-level in B2,
+   *  not per-node — see {@link stories}'s doc comment); `null` = no story
+   *  applied (the layer mounts against empty data, today's B1 behavior). */
+  private activeStoryId: string | null = null;
+  /** B3 — the registered components catalog (see
+   *  {@link ReactWorldAuthoringOptions.catalogComponents}'s doc comment).
+   *  Empty ⇒ {@link catalogOn} is `false` ⇒ pure DOM-walk hierarchy. */
+  private readonly catalogComponents: UIComponentRegistry;
+  private readonly onIsolate:
+    | ((v: { componentKey: string; story: (UIStory & { id: string }) | null } | null) => void)
+    | undefined;
+  private readonly worldId: string | undefined;
+  /** B3 — the currently-isolated catalog node, or `null` (the entry preview
+   *  is rendered). See {@link stories}'s `isolate`. */
+  private isolated: { nodeId: string; componentKey: string; storyId: string | undefined } | null =
+    null;
+  /**
+   * T0 (spec 27 §4, B1) — the currently-open `boxEdit` begin/apply×N/end gesture (a
+   * drag), or `null` between gestures. `touched` maps the RESOLVED CSS prop (already
+   * patch-key-mapped, e.g. `x` → `left`) to the FINAL value `end` should commit — a
+   * `Map` so the last `apply` in the gesture wins, matching an in-flight drag's most
+   * recent pointer position. `priorInline` captures each touched prop's ORIGINAL inline
+   * value, LAZILY on the prop's first `apply` in this gesture (i.e. BEFORE `apply`
+   * mutates the live style) — `apply` writes the live DOM directly for zero-latency
+   * preview, which would otherwise corrupt `writeStyleEntry`'s own prior-value capture
+   * (it reads `n.el.style` fresh, and by `end` time that already holds the LAST applied
+   * preview value, not the true pre-gesture one) — this is why `writeStyleEntry` takes
+   * an explicit override rather than re-deriving `prev` itself for a box-edit commit.
+   */
+  private boxEditSession: {
+    id: string;
+    touched: Map<string, string | number>;
+    priorInline: Map<string, string>;
+  } | null = null;
+
+  constructor(
+    private readonly root: OidElementLike,
+    private readonly store: EditorStore,
+    opts: ReactWorldAuthoringOptions = {},
+  ) {
+    this.writeBackend = opts.writeBackend;
+    this.computedStyle = opts.computedStyle ?? browserOrInlineResolver;
+    this.matchedCssRules =
+      opts.matchedCssRules ??
+      ((el) => getMatchedCssRules(el as MatchableElement) as CssRuleTarget[]);
+    this.designTokens = opts.designTokens ?? (() => getDesignTokens());
+    this.storySources = opts.storySources ?? [];
+    this.onStoryApplied = opts.onStoryApplied;
+    this.catalogComponents = opts.catalogComponents ?? {};
+    this.onIsolate = opts.onIsolate;
+    this.worldId = opts.worldId;
+    this.capabilities = {
+      transform: false, // no 3D gizmo — DOM has no Object3D pose (§1.F)
+      material: false,
+      inspectorFields: true,
+      create: true, // Cap 5: insert-child / duplicate / wrap are real source ops
+      delete: true,
+      reparent: true, // Cap 5: real source reparent (drag-to-reparent)
+      persist: true,
+    };
+    // T3.2 slice 2: this adapter IS the undo/redo target the editor-global
+    // timeline dispatches to for entries it records (`pushUndo`). The caller
+    // (`play-mode.ts`'s `exitMultiWorldAuthoring`) unregisters it on teardown,
+    // mirroring `IngestAuthoringAdapter`.
+    registerUndoAdapter(this);
+    // A4 (spec 27 §3) — re-sync the optimistic echo once HMR has actually re-rendered the
+    // react tree. Vite fires `vite:afterUpdate` after it applies an HMR update — here, the
+    // dev-server source-write this adapter triggered (→ file watcher → react-refresh
+    // re-render) — so that event IS the "reload landed" signal (the adapter otherwise never
+    // learns about reloads; play-mode.ts owns the component-class HMR handler, not this
+    // per-world adapter). Absent under a hosted/no-dev-server build and under vitest's `node`
+    // env (no `import.meta.hot`), where the unit test drives `reconcileEchoAfterReload()`
+    // directly to simulate a landed reload.
+    const hot = import.meta.hot;
+    if (hot) {
+      const onAfterUpdate = (): void => this.reconcileEchoAfterReload();
+      hot.on('vite:afterUpdate', onAfterUpdate);
+      this.disposeReloadSignal = () => hot.off('vite:afterUpdate', onAfterUpdate);
+    }
+    if (this.writeBackend?.index) {
+      this.writeBackend
+        .index()
+        .then((idx) => {
+          this.oidIndex = new Map(Object.entries(idx));
+          this.store.notifyIngestEdit();
+        })
+        .catch(() => {
+          // Honest degradation: labels stay tag-only if the index can't be fetched.
+        });
+    }
+  }
+
+  private snapshot(): OidTree {
+    return walkOidTree(this.root);
+  }
+
+  // --- A4: optimistic value echo (see {@link valueEcho}) ---
+
+  /** Record the value just committed by `inspector.set`, so `inspector.get(id, path)`
+   *  returns it immediately (before the async source-write + HMR land). */
+  private setEcho(id: string, path: string, value: unknown): void {
+    let byPath = this.valueEcho.get(id);
+    if (!byPath) {
+      byPath = new Map();
+      this.valueEcho.set(id, byPath);
+    }
+    byPath.set(path, value);
+  }
+
+  /** Drop one echoed entry — used the instant a write is refused/no-op'd, so the field
+   *  reverts to the live-DOM (unchanged) value rather than sticking on a value the source
+   *  never took (the "stale in the other direction" guard for rejected writes). */
+  private clearEcho(id: string, path: string): void {
+    const byPath = this.valueEcho.get(id);
+    if (!byPath) return;
+    byPath.delete(path);
+    if (byPath.size === 0) this.valueEcho.delete(id);
+  }
+
+  /** U4 — record that `id`'s `path` was refused as a dynamic expression, so the
+   *  NEXT `properties()` call marks its descriptor `readonly`. */
+  private markDynamic(id: string, path: string): void {
+    this.dynamicPaths.add(`${id}|${path}`);
+  }
+
+  /** Read-through for `inspector.get`: `{hit:true}` when this id+path was optimistically
+   *  echoed and not yet reconciled; `{hit:false}` otherwise (fall back to the live DOM). A
+   *  distinct `hit` flag (not a sentinel value) so a legitimately-`undefined` echoed value
+   *  still wins over the live-DOM walk. */
+  private readEcho(id: string, path: string): { hit: boolean; value: unknown } {
+    const byPath = this.valueEcho.get(id);
+    if (byPath?.has(path)) return { hit: true, value: byPath.get(path) };
+    return { hit: false, value: undefined };
+  }
+
+  /**
+   * A4 — the "HMR reload landed" reconcile (fired by the constructor's `vite:afterUpdate`
+   * hook, or called directly to simulate a landed reload). The echo held the freshly-set
+   * values while the async source-write + HMR re-render were in flight; once HMR has
+   * re-rendered the react tree the LIVE DOM is authoritative again — including any
+   * server-side value coercion — so drop the whole echo and notify, and every open inspector
+   * re-reads the now-updated DOM. (An unrelated module's `afterUpdate` that fires before THIS
+   * edit's HMR is a benign race: the field momentarily re-reads the old DOM, then this
+   * edit's own `afterUpdate` reconciles it — the echo self-heals on the next tick.) Selection
+   * is untouched: it lives as OID-signature ids in the store, re-resolved by `walkOidTree`
+   * against the remounted tree, never as a cached element reference.
+   *
+   * D3.R4 (reopen fix), widened by D3.R5 — ALSO the "landed" signal for every pending
+   * source write counted by {@link pendingSourceReconcile} (see its doc comment for the
+   * full site list and the counter-vs-boolean rationale): each of those writes' own
+   * `notifyIngestEdit()` fires before the HMR remount lands, so it never carries fresh
+   * DOM shape on its own; this reconcile is what does, once the remount has actually
+   * happened. Decrements the counter by exactly one per call (never resets it to zero)
+   * so N pending writes drain over N reconciles, each one notifying — not just the
+   * first.
+   */
+  reconcileEchoAfterReload(): void {
+    if (this.valueEcho.size === 0 && this.pendingSourceReconcile === 0) return;
+    this.valueEcho.clear();
+    if (this.pendingSourceReconcile > 0) this.pendingSourceReconcile--;
+    this.store.notifyIngestEdit();
+  }
+
+  /** A4 — release the `vite:afterUpdate` reconcile subscription. Idempotent; safe when no
+   *  HMR context was present (the disposer is `undefined`). */
+  disposeReactWorldAdapter(): void {
+    this.disposeReloadSignal?.();
+  }
+
+  private toEditorNode(n: OidNode): EditorNode {
+    // Component label priority (Cap 1): the OID source index (`component:tag`), then the
+    // LIVE React fiber's component name (`getReactComponentName` — resolves for a
+    // component's root element even before/without the index fetch), then the DOM tag.
+    const entry = this.oidIndex.get(n.oid);
+    const component = entry?.component ?? getReactComponentName(n.el);
+    const label = component ? `${component}:${n.tag}` : n.tag;
+    const node: EditorNode = {
+      id: n.id,
+      label,
+      kind: n.tag,
+      parentId: n.parentId,
+      childIds: n.childIds,
+      flags: { runtimeOnly: true },
+    };
+    // B3 — a former DOM ROOT (`parentId === null`) nests one level under the
+    // catalog's entry-preview node when the catalog is on (§0's reconciliation:
+    // GameHierarchy's sibling/drag math keys off `parentId`, so a root that
+    // kept `parentId: null` while `roots()` stopped returning it would corrupt
+    // top-level DOM drag-reorder). Only ROOTS are remapped — a non-root node's
+    // `parentId` already points at its real DOM parent, untouched.
+    if (this.catalogOn && node.parentId === null) return { ...node, parentId: CATALOG_ENTRY_ID };
+    return node;
+  }
+
+  /** B3 gate (§0/§1): the catalog hierarchy is ON only when constructed with a
+   *  NON-EMPTY `catalogComponents` — absent/empty keeps today's plain DOM-walk
+   *  hierarchy byte-identical (play mode never passes this option at all). */
+  private get catalogOn(): boolean {
+    return Object.keys(this.catalogComponents).length > 0;
+  }
+
+  /** B3 — one `kind:'component'` node per registered key. `object3D`/
+   *  `idForObject3D` stay `null` for these ids (no DOM/Object3D backing). */
+  private catalogNode(key: string): EditorNode {
+    return {
+      id: `${CATALOG_ID_PREFIX}${key}`,
+      label: key,
+      kind: 'component',
+      parentId: null,
+      childIds: [],
+      flags: { runtimeOnly: true },
+    };
+  }
+
+  /** B3 — the one `'entry (live preview)'` node; its children are the
+   *  DOM-walk's OWN root ids (unchanged, still resolved by `hierarchy.node()`
+   *  through the ordinary DOM path — see {@link toEditorNode}'s remap). */
+  private entryNode(rootIds: string[]): EditorNode {
+    return {
+      id: CATALOG_ENTRY_ID,
+      label: 'entry (live preview)',
+      kind: 'group',
+      parentId: null,
+      childIds: rootIds,
+      flags: { runtimeOnly: true },
+    };
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    roots: () => {
+      const { nodes, rootIds } = this.snapshot();
+      if (!this.catalogOn) return rootIds.map((id) => this.toEditorNode(nodes.get(id)!));
+      return [
+        ...Object.keys(this.catalogComponents).map((key) => this.catalogNode(key)),
+        this.entryNode(rootIds),
+      ];
+    },
+    node: (id) => {
+      if (this.catalogOn) {
+        if (id === CATALOG_ENTRY_ID) return this.entryNode(this.snapshot().rootIds);
+        if (id.startsWith(CATALOG_ID_PREFIX)) {
+          const key = id.slice(CATALOG_ID_PREFIX.length);
+          return key in this.catalogComponents ? this.catalogNode(key) : null;
+        }
+      }
+      const n = this.snapshot().nodes.get(id);
+      return n ? this.toEditorNode(n) : null;
+    },
+    object3D: () => null, // react entities are DOM, not Object3D — no 3D gizmo binding
+    idForObject3D: () => null,
+  };
+
+  readonly selection: SelectionProvider = {
+    get: () => [...this.store.selectedEntityIds],
+    set: (ids) => this.store.selectMultiple(ids),
+  };
+
+  /**
+   * D12 (B4) — GEOMETRIC rect hit-test over the live OID tree, NOT
+   * `document.elementFromPoint` (which SKIPS a `pointer-events:none` wrapper —
+   * this layer's resting CSS state at design time, `design-time-layers.ts`'s
+   * `applySessionStyle`). Reuses `ui-editor/react-store.ts`'s established
+   * `hitTestAttr` ranking rule (smallest-area element containing the point
+   * wins — the deepest/most-specific node; ties broken by later tree-walk
+   * order — the topmost) over each OID node's own `getBoundingClientRect()`,
+   * inlined here rather than sharing that function directly since this walks
+   * `OidNode`s already resolved by `walkOidTree`, not a live `querySelectorAll`
+   * over a DOM attribute string.
+   *
+   * The winning id is the SAME disambiguated id `hierarchy`/`selection`
+   * already use (this IS `walkOidTree`'s own id space) — a hit routes
+   * straight into `composite.selection.set([id])` with no translation. A
+   * catalog node (`catalog:<key>`) has no DOM element behind it at all, so it
+   * can never be a candidate here — only ordinary OID nodes are walked
+   * (correct: nothing on screen corresponds to a bare catalog entry).
+   */
+  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: exactly the
+        // `viewport-raycast.ts` first-party semantics ("skip locked
+        // entities in viewport selection", falling through to whatever
+        // unlocked node is behind/around it). See `lockedIds`'s doc
+        // comment for why this Set, not a real inspector-backed field.
+        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 — `this.root`
+   *  IS the world's own mounted DOM layer (`world.reactRoot()` / the ingest
+   *  sibling's `layer`, see the constructor call sites), i.e. exactly the
+   *  `position:absolute; inset:0` per-world surface the overlay (Phase A3) is
+   *  itself hosted over. No new constructor option is needed — reusing the
+   *  proven `react-store.ts` `nodeRect` pattern (element rect minus stage/host
+   *  rect) against the field this adapter already holds. */
+  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 for the DOM visual editor's
+   * overlay/snap/measure math. `rect`/`contextRects` return HOST-RELATIVE
+   * coordinates (see {@link hostRect}'s doc comment) — the overlay this feeds
+   * (Phase A3, `WorldSelectionOverlay`) is itself mounted as a
+   * `position:absolute; inset:0` layer over the same per-world DOM host, so a
+   * host-relative rect is exactly what it can draw against with no further
+   * translation (matching the established `ui-editor/react-store.ts`
+   * `nodeRect` pattern this reuses).
+   */
+  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));
+      // Padding box (CSS box model, inside the border) — border widths read off
+      // the same computed-style resolver the inspector uses; absent/unparsable
+      // border widths degrade to 0 (padding box === border box), never thrown.
+      const el = n.el;
+      const rect = el.getBoundingClientRect?.();
+      let paddingBox: DOMRectLike | undefined;
+      if (rect) {
+        const bt =
+          numericStyleValue(getComputedStyleValue(el, 'borderTopWidth', this.computedStyle)) ?? 0;
+        const br =
+          numericStyleValue(getComputedStyleValue(el, 'borderRightWidth', this.computedStyle)) ?? 0;
+        const bb =
+          numericStyleValue(getComputedStyleValue(el, 'borderBottomWidth', this.computedStyle)) ??
+          0;
+        const bl =
+          numericStyleValue(getComputedStyleValue(el, 'borderLeftWidth', this.computedStyle)) ?? 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.c (spec 27 §6) — every currently-empty OID container: no visible
+    // (OID or non-OID) child ELEMENT, no text, feeding the pure
+    // `findEmptyContainers` math (`ui-source/inspect.ts:463`) unchanged. Rule
+    // zero stays intact — the DOM READ happens HERE, in the adapter; the
+    // overlay/shell only ever sees the already-filtered `{id, rect,
+    // displayName}` result.
+    emptyContainers: () => {
+      const { nodes } = this.snapshot();
+      const candidates: EmptyCandidate[] = [];
+      for (const n of nodes.values()) {
+        const r = n.el.getBoundingClientRect?.();
+        if (!r) continue;
+        candidates.push({
+          oid: n.id,
+          rect: this.toHostRelative(r),
+          displayName: n.tag,
+          hasVisibleChildren: n.el.children.length > 0,
+          hasText: (n.el.textContent ?? '').trim().length > 0,
+        });
+      }
+      return findEmptyContainers(candidates).map((c) => ({
+        id: c.oid,
+        rect: c.rect,
+        displayName: c.displayName,
+      }));
+    },
+  };
+
+  /**
+   * D3.d (spec 27 §6) — the eyedropper FALLBACK color-sample path: pick the
+   * topmost OID node at the point (reusing this adapter's OWN `pickable.pick`,
+   * never `elementFromPoint`), then walk its ancestor chain collecting each
+   * node's RAW (un-normalized) computed `background-color` — hit-element
+   * first, matching `effectiveColorFromChain`'s expected order. Raw, not
+   * `cssColorToHex`-normalized, so a `transparent`/`rgba(0,0,0,0)` background
+   * is recognizable as such by `isTransparentBackground` (the hex form would
+   * lose that signal — see the contract's own doc comment on
+   * `ColorSampleProvider`).
+   */
+  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: OidNode | undefined = nodes.get(hitId);
+      while (cur) {
+        chain.push(getComputedStyleValue(cur.el, 'backgroundColor', this.computedStyle));
+        cur = cur.parentId ? nodes.get(cur.parentId) : undefined;
+      }
+      return chain;
+    },
+  };
+
+  /**
+   * T0 (spec 27 §4, B1) — spatial drag-resize/move/spacing → source write, for
+   * non-Object3D (DOM) nodes. `apply` is LIVE PREVIEW ONLY: it mutates the live
+   * element's inline style directly, with ZERO backend traffic (acceptance:311 —
+   * a resize drag must not spam the dev server with a write per frame). `end`
+   * commits every touched prop ONCE through the existing {@link writeStyleEntry}
+   * write pipeline (CSS-file routing + append-aware undo preserved unchanged),
+   * composed into exactly ONE undo entry per gesture (acceptance:310) even when
+   * the gesture touched multiple props (e.g. a corner-resize writes both `width`
+   * and `height`). See {@link boxEditSession}'s doc comment for the
+   * `priorInline` capture this depends on for a correct undo inverse.
+   */
+  readonly boxEdit: BoxEditProvider = {
+    begin: (id) => {
+      // A stale, never-`end`ed session (caller bug) is simply replaced — its
+      // preview mutations are already live on the DOM either way.
+      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', this.computedStyle);
+      const isPositioned = pos === 'absolute' || pos === 'fixed';
+      for (const [key, v] of Object.entries(patch)) {
+        const mapped = mapBoxEditPatchKey(key, isPositioned);
+        if (!mapped) {
+          console.warn(
+            `[ReactWorldAuthoringAdapter] 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 for why this can't be re-derived later.
+        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);
+        if (n.el.style) (n.el.style as Record<string, unknown>)[mapped.prop] = cssValue;
+        // Commit numerics as plain numbers (matching every other numeric style
+        // write in this adapter — see `writeStyle`'s callers), transform as a
+        // string — NOT the px-suffixed preview string, which is preview-only.
+        session.touched.set(mapped.prop, mapped.prop === 'transform' ? cssValue : v);
+      }
+    },
+    end: (id) => {
+      const session = this.boxEditSession;
+      this.boxEditSession = null;
+      if (!session || session.id !== id || session.touched.size === 0) return;
+      void this.commitBoxEdit(id, session.touched, session.priorInline);
+    },
+  };
+
+  /**
+   * T0 (spec 27 §4, B1) — commit every prop touched by one `boxEdit` gesture, each
+   * through {@link writeStyleEntry} (so CSS-file routing / append-aware undo are
+   * unchanged), then compose all resulting entries into exactly ONE undo entry
+   * (acceptance:310) whose inverse runs in REVERSE order and whose redo runs in
+   * gesture order — mirroring how a multi-statement edit undoes as one unit
+   * elsewhere in this adapter.
+   */
+  private async commitBoxEdit(
+    id: string,
+    touched: Map<string, string | number>,
+    priorInline: Map<string, string>,
+  ): Promise<void> {
+    // A4 — echo every touched prop BEFORE any write, so the inspector field shows
+    // the dragged value at once (same discipline as `inspector.set`). The echo holds
+    // the BARE numeric (a `type:'number'` descriptor's `Inspector` field needs an
+    // actual number — see `inspector.get`'s `numericStyleValue` note), NOT the
+    // px-suffixed source form D1 writes below.
+    for (const [prop, value] of touched) {
+      this.setEcho(id, `${STYLE_PATH_PREFIX}${prop}`, value);
+    }
+    const entries: PendingUndo[] = [];
+    for (const [prop, value] of touched) {
+      // D1 (spec 27 §4 B2/B3 reload-safety) — a numeric length-prop value must
+      // persist to JSX SOURCE in a form React honors on REMOUNT. React 19 DROPS a
+      // bare UNITLESS numeric STRING (the writer quotes `String(152)` → `width:
+      // '152'`) on reload — the element collapses to content size (verified in real
+      // Chromium + React 19) — but HONORS a quoted CSS length (`width: '152px'`).
+      // `boxEdit.apply` stores length props as bare NUMBERS and CSS-string props
+      // (`transform` → `'rotate(90deg)'`) as strings, so a numeric value here is
+      // EXACTLY the set of length props (width/height/left/top/margin*/padding*)
+      // needing a `px` unit — suffix only those, leaving `transform` untouched.
+      // (The live-preview `el.style` path already applied a px-suffixed string via
+      // `mapBoxEditPatchKey.cssValue`; only the persisted-source form was unitless.)
+      // Localized to this box-edit commit — the color/`inspector.set` write path is
+      // deliberately NOT changed.
+      const writeValue = typeof value === 'number' ? `${value}px` : value;
+      const entry = await this.writeStyleEntry(id, prop, writeValue, 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();
+      },
+    });
+  }
+
+  /**
+   * T0 (spec 27 §2) — brings the react adapter's existing off-contract `editText`
+   * (below) onto the contract. `get` is a best-effort CLIENT-side read: the live
+   * DOM can only rule out "has child elements" (`el.children.length > 0`), not a
+   * dynamic `{expression}` body — that guard is source-side and already enforced
+   * at write time (`editText`'s `res.dynamic`, surfaced as a loud console warning
+   * on refusal). `set` fires the existing undo-tracked write path unchanged.
+   */
+  readonly text: TextProvider = {
+    get: (id) => {
+      // D3.R1 — a node already refused once as a dynamic-body text edit
+      // (`markDynamic(id, TEXT_PATH)`, set from `editText`'s `res.dynamic`
+      // refusal below) reports null from here on this session, mirroring
+      // U4's style/prop after-touch marker — so a SECOND double-click reports
+      // the refusal immediately instead of re-opening the textarea only to
+      // have the source refuse it again.
+      if (this.dynamicPaths.has(`${id}|${TEXT_PATH}`)) return null;
+      const n = this.snapshot().nodes.get(id);
+      if (!n || n.el.children.length > 0) return null;
+      const raw = n.el.textContent;
+      if (raw == null) return null;
+      const trimmed = raw.trim();
+      return trimmed ? trimmed : null;
+    },
+    set: (id, text) => {
+      void this.editText(id, text);
+    },
+  };
+
+  readonly inspector: InspectorProvider = {
+    properties: (id: string): PropertyDescriptor[] => {
+      // B3 — a catalog node (`catalog:<key>`) has no DOM element/fiber behind
+      // it at all (`object3D`/`idForObject3D` are null for these ids too) —
+      // style/Cap-4-props/tokens would be garbage for it. Its ONE inspector
+      // surface is the active isolation story's props (see
+      // `storyPropDescriptors`'s doc comment) — deliberately NOT routed
+      // through `getComponentProps`/`writePropEdit` (Cap 4), which reads a
+      // real call-site fiber that doesn't exist for a catalog entry.
+      if (this.isCatalogId(id)) return this.storyPropDescriptors(id);
+      const style = STYLE_PROPERTIES.map(({ prop, label, type, group, options }) => ({
+        path: `${STYLE_PATH_PREFIX}${prop}`,
+        label,
+        type,
+        group,
+        ...(options ? { options } : {}),
+      }));
+      // Cap 4 (React visual-edit parity): append a "Props" section for this node's component
+      // call site — its editable primitive props, read live off the React fiber
+      // (`getComponentProps`). A write is guarded server-side (a dynamic prop is refused),
+      // so surfacing every primitive prop here is safe. Cap 7 appends a read-only "Tokens"
+      // section — the document's design tokens (`:root` custom properties).
+      const all = [...style, ...this.propDescriptors(id), ...this.tokenDescriptors()];
+      // U4 — a path already refused once as a dynamic expression (`markDynamic`,
+      // set from `writeStyleEntry`/`writePropEdit`'s `res.dynamic` refusal) reports
+      // `readonly: true` from here on, so the widget disables itself instead of
+      // re-offering an edit the source will refuse again. See `dynamicPaths`'s
+      // doc comment for why this is after-touch, not a pre-touch predictor.
+      if (this.dynamicPaths.size === 0) return all;
+      return all.map((p) =>
+        this.dynamicPaths.has(`${id}|${p.path}`) ? { ...p, readonly: true } : p,
+      );
+    },
+    get: (id, path) => {
+      // A4 — read THROUGH the optimistic echo: a value just set (style/prop) wins over the
+      // live-DOM walk until the source-write + HMR land, so the field never snaps back.
+      const echoed = this.readEcho(id, path);
+      if (echoed.hit) return echoed.value;
+      if (this.isCatalogId(id)) {
+        if (!path.startsWith(STORY_PROP_PATH_PREFIX)) return undefined;
+        return this.activeIsolationStoryProps(id)?.[path.slice(STORY_PROP_PATH_PREFIX.length)];
+      }
+      // D4 (spec27 §6 D4, layer-tree visibility/lock) — the two reserved
+      // paths GameHierarchy's row reads generically off ANY adapter's
+      // `inspector`. `locked` is session-local (see `lockedIds`'s doc
+      // comment — no source-backed equivalent). `visible` IS source-backed:
+      // sugar for the `style.visibility` prop (read THROUGH that same prop's
+      // own optimistic echo, so the eye icon never snap-backs while the
+      // async write is in flight — same A4 discipline every other style
+      // path gets).
+      if (path === 'locked') return this.lockedIds.has(id);
+      if (path === 'visible') {
+        const echoedStyle = this.readEcho(id, `${STYLE_PATH_PREFIX}visibility`);
+        if (echoedStyle.hit) return echoedStyle.value !== 'hidden';
+        const n = this.snapshot().nodes.get(id);
+        if (!n) return undefined;
+        const raw = getComputedStyleValue(n.el, 'visibility', this.computedStyle);
+        return raw !== 'hidden';
+      }
+      if (path.startsWith(TOKEN_PATH_PREFIX)) {
+        const name = path.slice(TOKEN_PATH_PREFIX.length);
+        return this.designTokens().find((t) => t.name === name)?.value;
+      }
+      if (path.startsWith(PROP_PATH_PREFIX)) {
+        const n = this.snapshot().nodes.get(id);
+        const cp = n ? getComponentProps(n.el) : null;
+        return cp?.props[path.slice(PROP_PATH_PREFIX.length)];
+      }
+      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;
+      // Cap 1 (React visual-edit parity): read the COMPUTED value via the resolver, so a
+      // property styled through a className utility (F5's class routing) OR a CSS file
+      // resolves too — fixing the "class-styled props show blank" read-back gap. Under
+      // vitest's `node` env the default resolver falls back to the element's inline
+      // `.style`, so headless fixtures keep working unchanged.
+      const raw = getComputedStyleValue(n.el, prop, this.computedStyle);
+      const declaredType = STYLE_PROPERTY_TYPE.get(prop);
+      // A `type: 'number'` descriptor (fontSize/width/height/padding/margin/
+      // borderRadius/gap) needs an actual number for the generic numeric
+      // input to render/edit correctly — a REAL `CSSStyleDeclaration` always
+      // hands these back as a unit-suffixed STRING (e.g. `"16px"`, never a
+      // bare `16`), which `Inspector.tsx`'s `typeof v === 'number'` check
+      // would otherwise silently read as `0` (this repo's own
+      // `react-world-authoring-adapter.test.ts` fixtures never caught this —
+      // a hand-built plain-object `style: {}` can hold a bare JS number
+      // directly, which a real DOM element's `style` never does). A
+      // `type: 'color'` descriptor needs `#rrggbb` for the same reason —
+      // see `cssColorToHex`'s doc comment.
+      if (declaredType === 'number') return numericStyleValue(raw);
+      if (declaredType === 'color') return cssColorToHex(raw);
+      return raw || undefined; // an unset computed value reads '' — surface as blank
+    },
+    set: (id, path, value) => {
+      if (this.isCatalogId(id)) {
+        if (path.startsWith(STORY_PROP_PATH_PREFIX)) {
+          this.writeStoryProp(id, path.slice(STORY_PROP_PATH_PREFIX.length), value);
+        }
+        return;
+      }
+      // D4 — see the matching `get` branch's doc comment.
+      if (path === 'locked') {
+        if (value) this.lockedIds.add(id);
+        else this.lockedIds.delete(id);
+        this.store.notifyIngestEdit();
+        return;
+      }
+      if (path === 'visible') {
+        const cssValue = value ? 'visible' : 'hidden';
+        this.setEcho(id, `${STYLE_PATH_PREFIX}visibility`, cssValue);
+        void this.writeStyle(id, 'visibility', cssValue);
+        return;
+      }
+      if (path.startsWith(PROP_PATH_PREFIX)) {
+        // A4 — echo BEFORE the async write so `inspector.get` shows the new value at once.
+        this.setEcho(id, path, value);
+        void this.writePropEdit(id, path.slice(PROP_PATH_PREFIX.length), String(value));
+        return;
+      }
+      if (!path.startsWith(STYLE_PATH_PREFIX)) return;
+      const prop = path.slice(STYLE_PATH_PREFIX.length);
+      // A4 — echo BEFORE the async write (the desync fix): the field reflects the commit
+      // within one frame; the write path clears this echo if the write is refused, and HMR
+      // clears it once the re-render lands.
+      this.setEcho(id, path, value);
+      void this.writeStyle(id, prop, value as string | number);
+    },
+    remove: (id, path) => {
+      // U2 — remove a stale CSS longhand override so its shorthand actually
+      // wins (a uniform border/radius edit clears the per-side/per-corner
+      // longhands a prior non-uniform edit wrote; without this the longhand
+      // silently overrides the shorthand on reload — the D1 defect). Style
+      // paths only; a `prop.`/`token.`/catalog path has no removable-override
+      // meaning here (no-op). `removeStyle` is itself a source no-op when the
+      // longhand isn't authored, so calling this unconditionally for all four
+      // corners / twelve side-props is safe and never pollutes clean source.
+      if (this.isCatalogId(id)) return;
+      if (!path.startsWith(STYLE_PATH_PREFIX)) return;
+      const prop = path.slice(STYLE_PATH_PREFIX.length);
+      // Point the removed longhand's echo at the value it actually renders at
+      // once the override is gone — the shorthand's current (just-committed)
+      // value — so `inspector.get(longhand)` reports the resolved corner value,
+      // not a stale override or an empty computed read, and stays consistent
+      // after HMR clears the echo (the shorthand then cascades to it).
+      const shorthand = LONGHAND_TO_SHORTHAND[prop];
+      if (shorthand)
+        this.setEcho(id, path, this.inspector.get(id, `${STYLE_PATH_PREFIX}${shorthand}`));
+      else this.clearEcho(id, path);
+      void this.removeStyleProp(id, prop);
+    },
+  };
+
+  /** B3 — true for a catalog node id (`catalog:<key>`), never for the entry
+   *  node or an ordinary DOM node id. */
+  private isCatalogId(id: string): boolean {
+    return id.startsWith(CATALOG_ID_PREFIX);
+  }
+
+  /** B3 — the active isolation story's `props` for catalog node `id`, or
+   *  `null` when `id` isn't the CURRENTLY isolated node (no active story to
+   *  show props for — v1's inspector surface only has meaning once isolated,
+   *  see the class doc comment on `isolate`). An isolation with no story
+   *  picked (`storyId` undefined) or an unresolvable story both read as `{}`
+   *  (no props), not `null` — `null` means "not this node". */
+  private activeIsolationStoryProps(id: string): Record<string, unknown> | null {
+    if (!this.isolated || this.isolated.nodeId !== id) return null;
+    const storyId = this.isolated.storyId;
+    const story = storyId ? this.mergedStories().get(storyId) : undefined;
+    return story?.props ?? {};
+  }
+
+  /** B3 — PropertyDescriptors for the active isolation story's props (see
+   *  {@link activeIsolationStoryProps}), grouped under "Story Props". Every
+   *  code-authored prop the component receives is otherwise read-only (spec:
+   *  "there is nowhere to persist an edit to") — these ARE writable because
+   *  they resolve through the B2 story-overlay (`writeStoryProp`), a
+   *  session-scoped seam, not the component's JSX call site. */
+  private storyPropDescriptors(id: string): PropertyDescriptor[] {
+    const props = this.activeIsolationStoryProps(id);
+    if (!props) return [];
+    return Object.keys(props).map((name) => {
+      // Derive the descriptor type from the story value so the generic
+      // inspector renders the right widget: a boolean story prop (e.g. a
+      // modal's `open: true`) as a checkbox, a number as a number input, a
+      // nested object/array as JSON — NOT a text input that would stringify
+      // every edit (typing "false" into a text field writes the truthy string
+      // `'false'`, so a bool could never be toggled off from the UI).
+      const value = props[name];
+      const type: PropertyDescriptor['type'] =
+        typeof value === 'boolean'
+          ? 'boolean'
+          : typeof value === 'number'
+            ? 'number'
+            : value !== null && typeof value === 'object'
+              ? 'json'
+              : 'string';
+      return {
+        path: `${STORY_PROP_PATH_PREFIX}${name}`,
+        label: name,
+        type,
+        group: 'Story Props',
+      };
+    });
+  }
+
+  /**
+   * B3 — write a catalog node's active-isolation-story prop through the B2
+   * story-overlay (`../authoring/story-overlay.ts`'s `setStoryOverlay`) —
+   * the one write seam that doesn't require a JSX call site (a catalog
+   * component has none — see `inspector.properties`'s catalog branch doc
+   * comment). Clones the active story, patches ONE prop, writes the overlay
+   * for THIS world (keyed by the required `worldId` constructor option — no
+   * world id ⇒ nowhere to key the overlay, a loud warning, no silent no-op),
+   * then re-invokes `stories.isolate` with the SAME node/story so the layer
+   * re-renders against the patched props immediately (mirrors `stories.apply`'s
+   * "re-render in place" contract — never a remount).
+   */
+  private writeStoryProp(nodeId: string, propName: string, value: unknown): void {
+    if (!this.isolated || this.isolated.nodeId !== nodeId) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot write story prop "${propName}" on "${nodeId}": ` +
+          'not currently isolated.',
+      );
+      return;
+    }
+    if (!this.worldId) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot write story prop "${propName}" on "${nodeId}": ` +
+          'no world id configured for the story overlay (session-only writes unavailable).',
+      );
+      return;
+    }
+    const { storyId } = this.isolated;
+    if (!storyId) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot write story prop "${propName}" on "${nodeId}": ` +
+          'no story is currently applied to isolate against.',
+      );
+      return;
+    }
+    const base = this.mergedStories().get(storyId);
+    const patched: UIStory = {
+      label: base?.label ?? storyId,
+      data: base?.data ?? {},
+      props: { ...(base?.props ?? {}), [propName]: value },
+    };
+    setStoryOverlay(this.worldId, { ...(getStoryOverlay(this.worldId) ?? {}), [storyId]: patched });
+    this.doIsolate(nodeId, storyId); // re-render against the patched story
+  }
+
+  /** Cap 4: PropertyDescriptors for a node's editable component props (read off the fiber). */
+  private propDescriptors(id: string): PropertyDescriptor[] {
+    const n = this.snapshot().nodes.get(id);
+    const cp = n ? getComponentProps(n.el) : null;
+    if (!cp) return [];
+    return Object.keys(cp.props).map((name) => ({
+      path: `${PROP_PATH_PREFIX}${name}`,
+      label: name,
+      type: 'string' as const,
+      group: 'Props',
+    }));
+  }
+
+  /** Cap 7: read-only PropertyDescriptors for the document's design tokens (`:root` custom
+   *  properties, incl. Tailwind v4 @theme/oklch), shown under a "Tokens" section. */
+  private tokenDescriptors(): PropertyDescriptor[] {
+    return this.designTokens().map((t) => ({
+      path: `${TOKEN_PATH_PREFIX}${t.name}`,
+      label: t.name,
+      type: 'string' as const,
+      group: 'Tokens',
+      readonly: true,
+    }));
+  }
+
+  /**
+   * All configured story sources merged, later sources winning per id (see
+   * {@link ReactWorldAuthoringOptions.storySources}'s doc comment). B3 — the
+   * story-overlay slot (`../authoring/story-overlay.ts`) is ALSO re-read
+   * fresh here (not only whatever snapshot `design-time-layers.ts` baked
+   * into `storySources` at mount time) so a catalog node's story-prop write
+   * (`writeStoryProp`, which calls `setStoryOverlay`) is visible on the very
+   * next call — still LAST, so it wins on a collision, same precedence the
+   * constructor's `storySources` array already documents. A no-op when
+   * `worldId` wasn't configured (no overlay to key).
+   */
+  private mergedStories(): Map<string, UIStory> {
+    const out = new Map<string, UIStory>();
+    for (const source of this.storySources) {
+      for (const [id, story] of Object.entries(source)) out.set(id, story);
+    }
+    if (this.worldId) {
+      const overlay = getStoryOverlay(this.worldId);
+      if (overlay) for (const [id, story] of Object.entries(overlay)) out.set(id, story);
+    }
+    return out;
+  }
+
+  /**
+   * D4 — storybook stories (`docs/unified-world-editor/26-unified-editor-spec.md`
+   * §3 B2). B2 scope is WORLD-LEVEL: `storiesFor`/`active` ignore `nodeId`
+   * entirely (every node in this world reports the SAME merged story list —
+   * B3 is what differentiates a per-component catalog via `isolate`, which
+   * this slice deliberately OMITS). `apply` is the one write path: it
+   * validates the id (a loud console warning on an unknown id — never a
+   * silent no-op that leaves the picker looking like nothing happened),
+   * updates `activeStoryId`, invokes `onStoryApplied` (the design-time
+   * layer's re-render hook), and notifies the store so the inspector's
+   * dropdown re-reads `active()` immediately.
+   */
+  readonly stories: StoriesProvider = {
+    storiesFor: (_nodeId): StoryRef[] =>
+      [...this.mergedStories().entries()].map(([id, story]) => ({ id, label: story.label })),
+    active: (_nodeId) => this.activeStoryId,
+    apply: (_nodeId, storyId) => {
+      if (storyId === null) {
+        this.activeStoryId = null;
+        this.onStoryApplied?.(null);
+        this.store.notifyIngestEdit();
+        return;
+      }
+      const story = this.mergedStories().get(storyId);
+      if (!story) {
+        console.warn(
+          `[ReactWorldAuthoringAdapter] stories.apply: unknown story id "${storyId}" — ignoring.`,
+        );
+        return;
+      }
+      this.activeStoryId = storyId;
+      this.onStoryApplied?.({ id: storyId, ...story });
+      this.store.notifyIngestEdit();
+    },
+    // B3 — per-component catalog isolation (see `doIsolate`'s doc comment).
+    isolate: (nodeId, storyId) => this.doIsolate(nodeId, storyId),
+  };
+
+  /** B3 — the currently-isolated catalog node id, or `null` (the entry
+   *  preview is rendered). Read by `design-time-layers.ts`'s store
+   *  subscription (auto-exit when the selection no longer contains the
+   *  isolated node) and by `Inspector.tsx`'s catalog Isolate-toggle state
+   *  (same "ask the owning child adapter" discipline as `worldGroupChildAdapter`). */
+  get isolatedNodeId(): string | null {
+    return this.isolated?.nodeId ?? null;
+  }
+
+  /**
+   * B3 — `stories.isolate(nodeId, storyId?)`: render ONLY a catalog
+   * component against a story (the storybook canvas), or restore the entry
+   * preview.
+   *  - `nodeId === null` → clear the isolation, invoke `onIsolate(null)`
+   *    (the layer's re-render hook — see `design-time-layers.ts`), notify.
+   *  - a non-catalog id, or a catalog id whose key isn't actually registered
+   *    → a loud `console.warn`, no-op (never a silent no-op that leaves the
+   *    UI looking like nothing happened — house style, `stories.apply`'s
+   *    unknown-id case above).
+   *  - a valid catalog id → resolve the story from the merged sources (`{}`
+   *    props when no story/an unresolvable story id was given — isolating
+   *    with NO story is a valid "just show the component" state), invoke
+   *    `onIsolate`, notify the store so any open inspector re-reads state.
+   */
+  private doIsolate(nodeId: string | null, storyId?: string): void {
+    if (nodeId === null) {
+      this.isolated = null;
+      this.onIsolate?.(null);
+      this.store.notifyIngestEdit();
+      return;
+    }
+    if (!this.isCatalogId(nodeId)) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] stories.isolate: "${nodeId}" is not a catalog component ` +
+          'node — ignoring.',
+      );
+      return;
+    }
+    const key = nodeId.slice(CATALOG_ID_PREFIX.length);
+    if (!(key in this.catalogComponents)) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] stories.isolate: unknown catalog component "${key}" — ` +
+          'ignoring.',
+      );
+      return;
+    }
+    const story = storyId ? this.mergedStories().get(storyId) : undefined;
+    this.isolated = { nodeId, componentKey: key, storyId };
+    this.onIsolate?.({ componentKey: key, story: story ? { id: storyId!, ...story } : null });
+    this.store.notifyIngestEdit();
+  }
+
+  readonly structure: StructureProvider = {
+    // Cap 5 (React visual-edit parity): real source structural ops. D-1 (Phase D,
+    // spec27 §2): EVERY structural op — including `create`/`duplicate`, whose new
+    // element has no OID until the next transform/HMR — IS pushed to the undo
+    // timeline, via a checksum-guarded WHOLE-FILE snapshot inverse (`pushStructUndo`)
+    // rather than a per-OID one. That sidesteps the OID problem entirely: undo/redo
+    // never needs to address the new/moved element by OID, it just restores the
+    // file's prior/next full text. (Previously irreversible in this slice — see
+    // `pushStructUndo`'s doc comment for the full rationale and the delete case.)
+    create: (kind, parentId) => {
+      void this.structOp(parentId ?? '', 'create', { wrapperTag: kind });
+      return '';
+    },
+    // Returns `removeElement`'s own `Promise<void>` (not `void this....`) so
+    // `deleteSelection` (`editor-hotkeys.ts`) can `await` each id's write
+    // before firing the next — see the CORRECTNESS INVARIANT comment below
+    // for why that serialization (plus deletion ORDER) is what makes the
+    // per-id fallback loop sound for an adapter WITHOUT `removeMany` (any
+    // adapter override lacking `structure.removeMany` — `deleteSelection`
+    // always prefers a batched `removeMany` when present, see below).
+    remove: (id) => this.removeElement(id),
+    // delete-order-residual fix (bug-panel follow-up to the multi-delete
+    // corruption fix, 50f90a6d) — SOUND batched delete, ONE undo entry for
+    // the whole selection. D4.R2 originally investigated and REJECTED
+    // `removeMany` here as unsound because the OBVIOUS implementation is N
+    // separate `structOp`-style calls, each targeting its OID's `{file,
+    // line, col}` from the SERVER's `OidStore.index`
+    // (`vite-plugin-ui-oid.ts`'s `handleStruct`) — exactly the per-id
+    // `remove` loop's own stale-offset hazard (see the CORRECTNESS INVARIANT
+    // comment below), just without the ordering discipline that loop needs
+    // to stay sound. This implementation is NOT that: `removeManyElements`
+    // posts every id's raw oid in ONE request to `/__ui-source/struct-many`
+    // (`handleStructMany`, `vite-plugin-ui-oid.ts`), which resolves every
+    // oid's offset against a SINGLE shared `readFileSync` snapshot (never a
+    // per-id re-read, so no write-to-write staleness is even possible) and
+    // applies them highest-offset-first in one pass, one write. That is also
+    // why this is the fix for the DOM-reordered-vs-source residual the
+    // per-id fallback below still carries: this batch never consults
+    // `collectAllNodeIds`/hierarchy-walk order at all, so it is correct
+    // regardless of whether the live DOM's child order matches the .tsx
+    // source order. (Explicitly NOT a live re-transform/re-scan per id
+    // either — see `deleteElements`'s doc comment in `writer.ts` for why
+    // that would reopen a DIFFERENT unsoundness: occurrence-index-based oid
+    // identity churns when same-tag siblings are removed mid-batch.)
+    // Returns `removeManyElements`'s own `Promise<void>` (not `void
+    // this....`) so `deleteSelection` can `await` the whole batch's write
+    // landing before it returns, same reason `remove` above does.
+    removeMany: (ids) => this.removeManyElements(ids),
+    //
+    // CORRECTNESS INVARIANT for the per-id `remove` loop (bug-panel reopen,
+    // post-D4.R2) — `deleteSelection` (`editor-hotkeys.ts`) falls back to
+    // this loop only when `removeMany` is ABSENT (a different adapter
+    // override); for THIS adapter `removeMany` above is always preferred, so
+    // this loop is dead code for react-world today, kept sound and
+    // documented for any future override without a batched delete. It is
+    // safe ONLY under TWO conditions `deleteSelection` enforces together —
+    // neither held before the 50f90a6d fix (an unsorted, unawaited loop was
+    // a real source-corruption hazard, reachable by an ordinary top-first
+    // marquee/multi-select delete) — AND both assume the caller's walk order
+    // (`collectAllNodeIds`, DOM order for this adapter) matches true SOURCE
+    // order (the DOM-reordered-vs-source residual this file's `removeMany`
+    // fixes for THIS adapter specifically):
+    //   1. REVERSE (walk-)DOCUMENT ORDER — delete the bottom-most element
+    //      first, per the caller's own hierarchy walk. Every element's
+    //      `{line, col}` in `OidStore.index` is a snapshot from the LAST
+    //      real parse and is never refreshed between same-file writes (only
+    //      by a real Vite `transform()` re-run — the async HMR round trip
+    //      `pendingSourceReconcile` already tracks). Deleting bottom-up
+    //      means every write only ever removes source that sits BELOW every
+    //      id still queued — nothing ABOVE a queued id's own offset ever
+    //      shifts, so that offset stays valid no matter how many of its
+    //      later-walked siblings/descendants have already been removed. A
+    //      descendant is later in DFS pre-order than its ancestor, so this
+    //      same reverse-pre-order rule also deletes a selected descendant
+    //      before a selected ancestor — required, since deleting the
+    //      ancestor first would remove the descendant's own source out from
+    //      under it before its turn. This is sound ONLY when walk order ==
+    //      source order (true for ordinary JSX; false when a component's
+    //      live DOM child order is a runtime permutation of its JSX source,
+    //      e.g. `{[...els].reverse()}` over an array of DISTINCT element
+    //      values — see `test/delete-selection-dom-order-residual.test.ts`).
+    //   2. SERIALIZED WRITES — `deleteSelection` `await`s each `remove(id)`
+    //      (this method returns `removeElement`'s promise instead of firing
+    //      it `void`) before starting the next. `writeStruct` is a real
+    //      network POST in production (`source-write-backend.ts`); two
+    //      in-flight, un-awaited requests for the SAME file can each read it
+    //      BEFORE either has written back, so whichever write lands second
+    //      silently clobbers (loses) the first — a lost-update race
+    //      independent of ordering. Awaiting each id in turn guarantees
+    //      request N only starts once request N-1's write has landed.
+    // Together, every write in the sequence reads a file that already
+    // reflects every prior delete in the sequence, and targets an offset
+    // still valid against that file — the "safe" claim this comment used to
+    // make unconditionally, which was FALSE for the raw (unsorted, top-first)
+    // selection order `deleteSelection` used to iterate in
+    // (`test/react-world-struct-undo.test.ts`'s own "offset-staleness
+    // hazard" case, reachable through the real `deleteSelection` path, not
+    // just a hand-picked unsafe direct-adapter call).
+    duplicate: (id) => {
+      void this.structOp(id, 'duplicate');
+      return id;
+    },
+    reparent: (id, newParentId) => {
+      if (!newParentId) return;
+      const parentOid = this.oidOf(newParentId);
+      if (parentOid) void this.structOp(id, 'reparent', { parentOid });
+    },
+    // T0 (spec 27 §2): bring the pre-existing off-contract `reorder(id, beforeId,
+    // parentId)` method (below) onto the contract. D2.b (spec 27 §6) fix: a
+    // `null` `beforeSiblingId` means "move to the end of id's OWN current
+    // parent" (this contract method's own doc comment) — that needs a REAL
+    // `parentOid` to target (`reorder`'s own `parentStart != null` end-of-list
+    // branch), so resolve `id`'s CURRENT parent from the live snapshot for
+    // that case. A non-null `beforeSiblingId` already fully determines the
+    // target position via `targetOid` alone, so `parentId` stays `null` there
+    // (matching this method's pre-D2 behavior — no other caller of this
+    // contract method existed before D2.b's canvas drag-to-reorder, which is
+    // the first to actually exercise the null/"move to end" case).
+    reorder: (id, beforeSiblingId) => {
+      const parentId =
+        beforeSiblingId === null ? (this.snapshot().nodes.get(id)?.parentId ?? null) : null;
+      this.reorder(id, beforeSiblingId, parentId);
+    },
+    // D3.e (spec 27 §2 T0 leftover) — the generic HTML kinds `create`
+    // genuinely supports (see `CREATABLE_KINDS`'s doc comment below).
+    // `parentId` is ignored: every OID node accepts any of these as a plain
+    // child, mirroring `ui-authoring-adapter.ts`'s identically-parentId-
+    // agnostic `creatableKinds`.
+    creatableKinds: () => [...CREATABLE_KINDS],
+    // D3.a (spec 27 §6) — bring the pre-existing off-contract `wrap`/`unwrap`
+    // methods (below) onto the contract so the canvas context menu can reach
+    // them through the adapter interface alone (rule zero).
+    wrap: (id, wrapperTag) => this.wrap(id, wrapperTag),
+    unwrap: (id) => this.unwrap(id),
+  };
+
+  /** Wrap the element in a new container (Cap 5). */
+  wrap(id: string, wrapperTag = 'div'): void {
+    void this.structOp(id, 'wrap', { wrapperTag });
+  }
+
+  /** Replace the element with its children (Cap 5). */
+  unwrap(id: string): void {
+    void this.structOp(id, 'unwrap');
+  }
+
+  /** Reorder the element before a sibling (`beforeId`), or to the end of `parentId` when
+   *  `beforeId` is null (Cap 5, layer-tree drag-to-reorder). */
+  reorder(id: string, beforeId: string | null, parentId: string | null): void {
+    const opts: { targetOid?: string; parentOid?: string } = {};
+    const targetOid = beforeId ? this.oidOf(beforeId) : undefined;
+    const parentOid = parentId ? this.oidOf(parentId) : undefined;
+    if (targetOid) opts.targetOid = targetOid;
+    if (parentOid) opts.parentOid = parentOid;
+    void this.structOp(id, 'reorder', opts);
+  }
+
+  /** The underlying (component-global) OID for an entity id (strips the `#n` repeat tag). */
+  private oidOf(id: string): string | undefined {
+    return this.snapshot().nodes.get(id)?.oid;
+  }
+
+  /** Run a structural op through the write backend (loud degradation without one). */
+  private async structOp(
+    id: string,
+    op: string,
+    opts?: { targetOid?: string; parentOid?: string; wrapperTag?: string },
+  ): Promise<void> {
+    const oid = this.oidOf(id);
+    if (!oid) return;
+    if (!this.writeBackend) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot "${op}" on "${id}": no source-write backend in ` +
+          'this session (hosted/no dev server).',
+      );
+      return;
+    }
+    const res = await this.writeBackend.writeStruct(oid, op, opts);
+    if (!res.changed) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] struct "${op}" refused/no-op for oid "${oid}": ${res.error ?? 'no change'}`,
+      );
+      return;
+    }
+    this.dirty = true;
+    // D-1 (Phase D, spec27 §2): push the whole-file-snapshot undo/redo entry —
+    // see `pushStructUndo`'s doc comment.
+    this.pushStructUndo(op, res);
+    // D3.R4 (reopen fix) — this notify's `storeVersion` still reflects the PRE-HMR DOM (see
+    // `pendingSourceReconcile`'s doc comment); queue a pending reconcile so the upcoming
+    // `vite:afterUpdate` (or a test's direct `reconcileEchoAfterReload()` call) notifies AGAIN
+    // once the remount has actually happened.
+    this.pendingSourceReconcile++;
+    this.store.notifyIngestEdit();
+  }
+
+  /**
+   * D-1 (Phase D, spec27 §2 "known limitation to schedule, not hide"): push the
+   * checksum-guarded whole-file-snapshot undo/redo entry for a successful structural
+   * write — shared by {@link structOp} (create/duplicate/wrap/unwrap/reorder/reparent)
+   * and {@link removeElement} (delete). A naive per-OID inverse is UNSOUND for a
+   * structural op: OIDs are `file:component:tag:nthOccurrence` content signatures,
+   * `reorder`/`delete` reassign occurrence indices out from under any OID captured
+   * before the op, and `delete` has no inverse payload of its own (there is nothing
+   * left to re-target). Instead the inverse is the WHOLE touched file's prior/next
+   * text (`res.prevSource`/`res.newSource`, captured server-side by `handleStruct` —
+   * `vite-plugin-ui-oid.ts`) replayed through a checksum-guarded restore
+   * (`SourceWriteBackend.restoreSource`) — a plain overwrite the server refuses,
+   * WITHOUT writing, if the file's current sha256 doesn't match the hash the caller
+   * expects (an out-of-band change since, e.g. a hand-edit). Degrades to "not
+   * undoable" (console.warn, no entry pushed) when the backend lacks `restoreSource`
+   * or the write response is missing a snapshot field (an old/mocked backend) — an
+   * honest limitation, never a crash.
+   */
+  private pushStructUndo(
+    op: string,
+    res: {
+      file?: string;
+      prevSource?: string;
+      newSource?: string;
+      prevSha?: string;
+      newSha?: string;
+    },
+  ): void {
+    const { file, prevSource, newSource, prevSha, newSha } = res;
+    if (
+      !this.writeBackend?.restoreSource ||
+      file === undefined ||
+      prevSource === undefined ||
+      newSource === undefined ||
+      prevSha === undefined ||
+      newSha === undefined
+    ) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] struct "${op}" is not undoable: the write backend ` +
+          'does not support whole-file restore (missing restoreSource or a snapshot field).',
+      );
+      return;
+    }
+    this.pushUndo({
+      undo: () => void this.restoreStructSnapshot(file, prevSource, newSha),
+      redo: () => void this.restoreStructSnapshot(file, newSource, prevSha),
+    });
+  }
+
+  /**
+   * D-1 — the structural undo/redo inverse: POST the checksum-guarded whole-file
+   * restore. A refusal (`res.restored === false` — the file's CURRENT sha256 didn't
+   * match `ifMatchSha`, e.g. it changed out-of-band since this entry was recorded) is
+   * a LOUD no-op: `restoreSource` never writes on refusal, and this still notifies the
+   * store (same pattern as the D2 dynamic-write-refusal notify, `writeStyleEntry`/
+   * `writePropEdit`) so the UI ticks and can render the refusal instead of silently
+   * doing nothing.
+   *
+   * D3.R5 (reopen fix) — every `structOp`/`removeElement` undo/redo closure routes
+   * here (see `pushStructUndo`), so a SUCCESSFUL restore is itself a structural DOM
+   * change with the exact same pre-HMR-notify timing gap `structOp`/`removeElement`
+   * have (see `pendingSourceReconcile`'s doc comment) — queue a pending reconcile so
+   * hint-cache consumers reconcile once the restore's own remount actually lands. NOT
+   * queued on a refused restore: `restoreSource` never writes when refused, so there is
+   * no reload to await.
+   */
+  private async restoreStructSnapshot(
+    file: string,
+    source: string,
+    ifMatchSha: string,
+  ): Promise<void> {
+    if (!this.writeBackend?.restoreSource) return;
+    const res = await this.writeBackend.restoreSource(file, source, ifMatchSha);
+    if (!res.restored) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] structural undo/redo refused for "${file}": ` +
+          `${res.error ?? 'the file changed since this entry was recorded'}`,
+      );
+    } else {
+      this.pendingSourceReconcile++;
+    }
+    this.store.notifyIngestEdit();
+  }
+
+  /**
+   * 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 (`boxEdit`'s {@link commitBoxEdit})
+   * can compose them into a single undo entry itself. `writeStyle` (below) is now a
+   * one-line wrapper: identical behavior for every 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 live preview before
+   * `end` gets here, so a fresh DOM read would see the LAST previewed value, not the
+   * true original (see {@link boxEditSession}'s doc comment). Unused by the plain CSS
+   * cascade branch below (`pickCssRuleTarget`'s own `prevValue` comes from the matched
+   * rule's text, not inline style, and is unaffected either way).
+   */
+  private async writeStyleEntry(
+    id: string,
+    prop: string,
+    value: string | number,
+    priorInlineOverride?: string,
+  ): Promise<PendingUndo | null> {
+    // A4 — the echo key `inspector.set` populated for this write; cleared on any failure
+    // return below so a refused/unbacked write can't leave the field stuck on a value the
+    // source never took.
+    const echoPath = `${STYLE_PATH_PREFIX}${prop}`;
+    const n = this.snapshot().nodes.get(id);
+    if (!n) {
+      this.clearEcho(id, echoPath);
+      return null;
+    }
+    if (!this.writeBackend) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot write "${prop}" on "${id}": no source-write ` +
+          'backend in this session (hosted/no dev server) — selection/inspection still work.',
+      );
+      return null;
+    }
+    // Cap 2 (React visual-edit parity): if a first-party CSS RULE declares this property,
+    // edit that CSS FILE (cascade-correct: the last matched rule wins) instead of writing
+    // inline/class. A `generated: true` response means the selector isn't in source
+    // (Tailwind/styled-components) — fall through to the inline/class path below.
+    if (this.writeBackend.writeCss) {
+      const cssTarget = pickCssRuleTarget(this.matchedCssRules(n.el), prop);
+      if (cssTarget) {
+        const { rule, prevValue } = cssTarget;
+        const res = await this.writeBackend.writeCss(
+          rule.sourceFile,
+          rule.selectorText,
+          prop,
+          String(value),
+        );
+        if (res.changed) {
+          this.dirty = true;
+          this.store.notifyIngestEdit();
+          return {
+            undo: () => void this.applyCssWrite(rule, prop, prevValue),
+            redo: () => void this.applyCssWrite(rule, prop, String(value)),
+          };
+        }
+        if (!res.generated) {
+          this.clearEcho(id, echoPath);
+          console.warn(
+            `[ReactWorldAuthoringAdapter] CSS write refused/no-op for selector ` +
+              `"${rule.selectorText}" prop "${prop}": ${res.error ?? 'no change'}`,
+          );
+          return null;
+        }
+        // res.generated ⇒ selector is generated CSS — fall through to inline/class routing.
+      }
+    }
+    // Capture the prior literal from the LIVE DOM before writing — the inverse
+    // write for undo (§1.E: "store the prior literal, write it back on undo") —
+    // unless the caller already captured the TRUE pre-gesture value itself.
+    const prevRaw =
+      priorInlineOverride !== undefined ? priorInlineOverride : styleProp(n.el.style, prop);
+    const prev: string | number = typeof prevRaw === 'number' ? prevRaw : String(prevRaw ?? '');
+    const res = await this.writeBackend.writeStyle(n.oid, prop, String(value));
+    if (!res.changed) {
+      this.clearEcho(id, echoPath);
+      if (res.dynamic) this.markDynamic(id, echoPath);
+      // D2 — notify so the refusal actually RE-RENDERS: the cleared echo (field
+      // snaps back off the stale value) and, for a dynamic refusal, the now
+      // `readonly: true` descriptor only reach the UI on a store tick. Without
+      // this the widget keeps showing the refused value, enabled, until some
+      // unrelated event happens to re-render.
+      this.store.notifyIngestEdit();
+      console.warn(
+        `[ReactWorldAuthoringAdapter] style write refused/no-op for oid "${n.oid}" ` +
+          `prop "${prop}": ${res.dynamic ? 'value is a dynamic expression (guarded)' : (res.error ?? 'no change')}`,
+      );
+      return null;
+    }
+    this.dirty = true;
+    // D-A4 (wave 13, docs/WAVE13-JSX-SPREAD-UNDO-DESIGN.md): if this write took the
+    // writer's APPEND branch (no prior literal for `prop`, e.g. spread-derived
+    // `style={{ ...vars }}`), undo must REMOVE the appended prop rather than
+    // replay the write with `prev` — replaying would find the NOW-appended
+    // literal and REPLACE it with a hardcoded runtime value, baking a literal
+    // into a spot the source never had one. Redo is a plain write either way (a
+    // re-append is just a write).
+    const appended = res.appended === true;
+    // B1-parity live preview for single-prop inspector writes. The `boxEdit`
+    // gesture patches `n.el.style` live during the drag (see `boxEdit.apply`),
+    // but a plain single-prop write (a color / any inspector field) only wrote
+    // SOURCE — so the live element didn't repaint until HMR/reload, which never
+    // lands in-harness (27a-overlay.spec.ts:238: color edit's element stayed the
+    // old color forever). Optimistically apply the committed value to the live
+    // inline style here — mirroring `react-dom-authoring-adapter`'s own
+    // `applyStyleToElement` — so the edit is visible immediately; HMR then
+    // converges on the same value from source and the A4 echo re-syncs. Skipped
+    // for the box-edit caller (`priorInlineOverride` set), which already applied
+    // its own live preview and whose committed `value` can differ from the inline
+    // CSS (e.g. a unitless length vs the `px` string it painted). INLINE branch
+    // only — the CSS-cascade branch above returns early; patching inline there
+    // would shadow the rule and stick past later edits.
+    if (priorInlineOverride === undefined && n.el.style) {
+      (n.el.style as Record<string, unknown>)[prop] = String(value);
+    }
+    this.store.notifyIngestEdit();
+    return {
+      undo: appended
+        ? () => void this.applyStyleRemove(n.oid, prop)
+        : () => void this.applyStyleWrite(n.oid, prop, prev),
+      redo: () => void this.applyStyleWrite(n.oid, prop, value),
+    };
+  }
+
+  private async writeStyle(id: string, prop: string, value: string | number): Promise<void> {
+    const entry = await this.writeStyleEntry(id, prop, value);
+    if (entry) this.pushUndo(entry);
+  }
+
+  /**
+   * U2 (spec 27 §5 C2) — surgically REMOVE a style property's source override
+   * (`inspector.remove`'s style path). Captures the prior source literal first
+   * so the removal is undoable (undo re-writes it, redo re-removes); a source
+   * no-op (`changed: false`, e.g. the prop wasn't authored) pushes NO undo
+   * entry and touches nothing — which is what makes it safe to call for every
+   * corner/side unconditionally on a uniform edit. Also drops the live inline
+   * override so the element re-cascades to the shorthand immediately (mirrors
+   * `writeStyleEntry`'s inline live-preview, inverse direction).
+   */
+  private async removeStyleProp(id: string, prop: string): Promise<void> {
+    const n = this.snapshot().nodes.get(id);
+    if (!n || !this.writeBackend) return;
+    const prevRaw = styleProp(n.el.style, prop);
+    const prev: string | number = typeof prevRaw === 'number' ? prevRaw : String(prevRaw ?? '');
+    const res = await this.writeBackend.removeStyle(n.oid, prop);
+    if (!res.changed) return; // longhand wasn't authored — nothing removed, no undo
+    this.dirty = true;
+    if (n.el.style) delete (n.el.style as Record<string, unknown>)[prop];
+    this.store.notifyIngestEdit();
+    this.pushUndo({
+      undo: () => void this.applyStyleWrite(n.oid, prop, prev),
+      redo: () => void this.applyStyleRemove(n.oid, prop),
+    });
+  }
+
+  private async applyStyleWrite(oid: string, prop: string, value: string | number): Promise<void> {
+    if (!this.writeBackend) return;
+    await this.writeBackend.writeStyle(oid, prop, String(value));
+    this.store.notifyIngestEdit();
+  }
+
+  /** D-A4: the append-aware undo target — removes a prop that had no prior source
+   *  literal, instead of writing a captured runtime value back into it. */
+  private async applyStyleRemove(oid: string, prop: string): Promise<void> {
+    if (!this.writeBackend) return;
+    await this.writeBackend.removeStyle(oid, prop);
+    this.store.notifyIngestEdit();
+  }
+
+  /** Re-apply a CSS-file write (used by the undo/redo inverse for a Cap 2 CSS edit). */
+  private async applyCssWrite(rule: CssRuleTarget, prop: string, value: string): Promise<void> {
+    if (!this.writeBackend?.writeCss) return;
+    await this.writeBackend.writeCss(rule.sourceFile, rule.selectorText, prop, value);
+    this.store.notifyIngestEdit();
+  }
+
+  /**
+   * Cap 3 (React visual-edit parity): replace a leaf element's pure-text content in source
+   * (double-click-to-edit). Refused (guarded) when the body has an expression or child
+   * elements. Undoable: the prior text (returned by the backend) is written back on undo.
+   */
+  async editText(id: string, newText: string): Promise<void> {
+    const n = this.snapshot().nodes.get(id);
+    if (!n) return;
+    if (!this.writeBackend?.writeText) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot edit text on "${id}": no source-write backend ` +
+          'with text support in this session (hosted/no dev server).',
+      );
+      return;
+    }
+    const res = await this.writeBackend.writeText(n.oid, newText);
+    if (!res.changed) {
+      // D3.R1 (reopen fix) — a dynamic-body refusal marks this id readonly for
+      // text edits (U4's session-scoped `dynamicPaths`, read by `text.get`
+      // above) and — mirroring D2's style/prop precedent — notifies the store
+      // UNCONDITIONALLY so the refusal (and the overlay's refused indicator,
+      // which polls `text.get` off this same notify) renders at refusal time
+      // instead of silently vanishing until an unrelated event ticks the store.
+      if (res.dynamic) this.markDynamic(id, TEXT_PATH);
+      this.store.notifyIngestEdit();
+      console.warn(
+        `[ReactWorldAuthoringAdapter] text edit refused/no-op for oid "${n.oid}": ` +
+          `${res.dynamic ? 'body has an expression/children (guarded)' : (res.error ?? 'no change')}`,
+      );
+      return;
+    }
+    this.dirty = true;
+    const prev = res.prevText ?? '';
+    this.pushUndo({
+      undo: () => void this.applyTextWrite(n.oid, prev),
+      redo: () => void this.applyTextWrite(n.oid, newText),
+    });
+    // D3.R5 (reopen fix) — a successful text write flips `hasText`, itself a
+    // `findEmptyContainers` hint-eligibility criterion (`ui-source/inspect.ts`), yet
+    // populates no `valueEcho` (echo is only ever set by the inspector style/prop
+    // paths) — same pre-HMR-notify timing gap as a structural op (see
+    // `pendingSourceReconcile`'s doc comment): queue a pending reconcile.
+    this.pendingSourceReconcile++;
+    this.store.notifyIngestEdit();
+  }
+
+  private async applyTextWrite(oid: string, text: string): Promise<void> {
+    if (!this.writeBackend?.writeText) return;
+    const res = await this.writeBackend.writeText(oid, text);
+    // D3.R5 (reopen fix) — the text-undo/redo inverse is itself a text write with the
+    // same `hasText` reconcile need as `editText`'s success path above; queued on
+    // success only — a refused/no-op write never touches the counter.
+    if (res.changed) this.pendingSourceReconcile++;
+    this.store.notifyIngestEdit();
+  }
+
+  /**
+   * Cap 4 (React visual-edit parity): write a component prop at its CALL SITE (the
+   * `<Component …>` tag), resolved from the live fiber (`getComponentProps` → callSiteOid).
+   * Refused (guarded) when the prop is a dynamic expression. Undoable via the prior fiber
+   * value.
+   */
+  private async writePropEdit(id: string, prop: string, value: string): Promise<void> {
+    // A4 — the echo key `inspector.set` populated for this prop write; cleared on any
+    // failure return so a refused write can't leave the field stuck.
+    const echoPath = `${PROP_PATH_PREFIX}${prop}`;
+    const n = this.snapshot().nodes.get(id);
+    if (!n) {
+      this.clearEcho(id, echoPath);
+      return;
+    }
+    if (!this.writeBackend?.writeProp) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot write prop "${prop}" on "${id}": no source-write ` +
+          'backend with prop support in this session (hosted/no dev server).',
+      );
+      return;
+    }
+    const cp = getComponentProps(n.el);
+    if (!cp) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactWorldAuthoringAdapter] "${id}" is not a component call site with props — ` +
+          `cannot write prop "${prop}".`,
+      );
+      return;
+    }
+    const prev = cp.props[prop] ?? '';
+    const res = await this.writeBackend.writeProp(cp.callSiteOid, prop, value);
+    if (!res.changed) {
+      this.clearEcho(id, echoPath);
+      if (res.dynamic) this.markDynamic(id, echoPath);
+      // D2 — notify so the cleared echo + (dynamic) new `readonly: true`
+      // descriptor render at refusal time, not on the next unrelated event.
+      this.store.notifyIngestEdit();
+      console.warn(
+        `[ReactWorldAuthoringAdapter] prop write refused/no-op for oid "${cp.callSiteOid}" ` +
+          `prop "${prop}": ${res.dynamic ? 'value is a dynamic expression (guarded)' : (res.error ?? 'no change')}`,
+      );
+      return;
+    }
+    this.dirty = true;
+    this.pushUndo({
+      undo: () => void this.applyPropWrite(cp.callSiteOid, prop, prev),
+      redo: () => void this.applyPropWrite(cp.callSiteOid, prop, value),
+    });
+    this.store.notifyIngestEdit();
+  }
+
+  private async applyPropWrite(callSiteOid: string, prop: string, value: string): Promise<void> {
+    if (!this.writeBackend?.writeProp) return;
+    await this.writeBackend.writeProp(callSiteOid, prop, value);
+    this.store.notifyIngestEdit();
+  }
+
+  private async removeElement(id: string): Promise<void> {
+    const n = this.snapshot().nodes.get(id);
+    if (!n) return;
+    if (!this.writeBackend) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] cannot delete "${id}": no source-write backend in ` +
+          'this session (hosted/no dev server).',
+      );
+      return;
+    }
+    const res = await this.writeBackend.writeStruct(n.oid, 'delete');
+    if (!res.changed) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] delete refused/no-op for oid "${n.oid}": ${res.error ?? 'no change'}`,
+      );
+      return;
+    }
+    this.dirty = true;
+    // D-1 (Phase D, spec27 §2): delete IS undoable now, via the SAME checksum-guarded
+    // whole-file-snapshot inverse `structOp` uses (`pushStructUndo`) — it sidesteps
+    // "no element-insertion primitive" entirely by never re-inserting the deleted
+    // element from an OID; it replays the whole file's PRIOR text instead.
+    this.pushStructUndo('delete', res);
+    // D3.R4 (reopen fix) — same pre-HMR-notify timing gap `structOp` has (see
+    // `pendingSourceReconcile`'s doc comment); `delete` is one of the two triggering
+    // scenarios the reviewer's contrast probe reproduced.
+    this.pendingSourceReconcile++;
+    this.store.notifyIngestEdit();
+  }
+
+  /**
+   * delete-order-residual fix — the `structure.removeMany` backing. Resolves every
+   * `id` to its raw (non-disambiguated) oid, dedupes (a repeated-OID `.map` list's
+   * `#n` siblings share ONE raw oid — deleting it once is correct, per
+   * `walkOidTree`'s own disambiguation comment), and posts them ALL in ONE
+   * `writeStructMany` call — see that method's doc comment on `SourceWriteBackend`
+   * (`source-write-backend.ts`) and `handleStructMany`'s (`vite-plugin-ui-oid.ts`)
+   * for the soundness argument (one shared file snapshot, highest-offset-first,
+   * caller-order-independent). Degrades to a loud no-op — never a silent partial
+   * delete — when this session's backend hasn't implemented `writeStructMany` (a
+   * hosted/no-dev-server session, or a legacy test mock): `deleteSelection`
+   * (`editor-hotkeys.ts`) only reaches this method because `structure.removeMany`
+   * is present at all, so there is no further per-id fallback to drop into here.
+   */
+  private async removeManyElements(ids: readonly string[]): Promise<void> {
+    const snapshot = this.snapshot();
+    const oids = [
+      ...new Set(
+        ids.map((id) => snapshot.nodes.get(id)?.oid).filter((oid): oid is string => !!oid),
+      ),
+    ];
+    if (oids.length === 0) return;
+    if (!this.writeBackend?.writeStructMany) {
+      console.warn(
+        '[ReactWorldAuthoringAdapter] cannot batch-delete: no source-write backend in this ' +
+          'session supports writeStructMany (hosted/no dev server, or a legacy mock).',
+      );
+      return;
+    }
+    const res = await this.writeBackend.writeStructMany(oids, 'delete');
+    if (!res.changed) {
+      console.warn(
+        `[ReactWorldAuthoringAdapter] batch delete refused/no-op for oids [${oids.join(', ')}]: ` +
+          `${res.error ?? 'no change'}`,
+      );
+      return;
+    }
+    this.dirty = true;
+    // D-1 (Phase D, spec27 §2): same checksum-guarded whole-file-snapshot inverse
+    // `removeElement`/`structOp` use (`pushStructUndo`) — ONE entry for the whole
+    // batch (a bonus of batching, not the point of this fix).
+    this.pushStructUndo('delete-many', res);
+    this.pendingSourceReconcile++;
+    this.store.notifyIngestEdit();
+  }
+
+  private pushUndo(entry: PendingUndo): void {
+    this.undoStack.push(entry);
+    this.redoStack.length = 0;
+    notifyUndoableOp(this); // T3.2 slice 2 — tag this op on the global timeline
+  }
+
+  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 — see `ui-authoring-adapter.ts`/
+  // `vgai-scene-authoring-adapter.ts` for why (field initializers run before the
+  // constructor body assigns `this.writeBackend`).
+  get persistence(): PersistenceProvider {
+    const backend = this.writeBackend;
+    return {
+      isDirty: () => this.dirty,
+      save: async () => {
+        // Immediate-write architecture (same as UIAuthoringAdapter/
+        // SourceWriteBackend's doc comment) — every edit already landed on disk
+        // the instant it was made; nothing is pending to flush.
+      },
+      serialize: () => ({
+        note: 'react world edits write directly to JSX source — nothing is serialized here',
+      }),
+      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)',
+    };
+  }
+}