@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

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

@@ -15,15 +15,9 @@
  * 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.
+ * file does NOT invent a second source-writer. Every edit prepares complete next-file
+ * text and commits it through one checksum-guarded source history resource. Style,
+ * text, prop, and structural changes therefore share exact-byte undo/redo semantics.
  *
  * Persistence mirrors `UIAuthoringAdapter`'s de-stubbed pattern exactly: writes are
  * immediate (server-side, on commit), so `save()` is an honest no-op; `destination`
@@ -34,6 +28,7 @@
 import type {
   AuthoringAdapter,
   AuthoringCapabilities,
+  AuthoringProvenance,
   BoxEditProvider,
   ColorSampleProvider,
   DOMRectLike,
@@ -50,9 +45,9 @@ import type {
   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 { JsonHistoryResource } from '../history/json-history-resource';
+import { withProjectSourceHistory } from '../history/source-history-backend';
 import {
   browserOrInlineResolver,
   type ComputedStyleResolver,
@@ -70,7 +65,8 @@ 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';
+import type { UIComponentRegistry, UIStory } from './story-types';
+import { getWorldPan } from './world-pan-state';
 
 /**
  * The minimal structural shape this adapter needs from a live DOM element —
@@ -118,6 +114,16 @@ export interface OidElementLike {
   readonly textContent?: string | null;
 }
 
+const MAX_ELEMENT_LABEL_LENGTH = 64;
+
+/** Compact the browser's semantic text into a stable hierarchy-row label. */
+function normalizeElementText(value: string | null | undefined): string | null {
+  const text = value?.replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+  if (text.length <= MAX_ELEMENT_LABEL_LENGTH) return text;
+  return `${text.slice(0, MAX_ELEMENT_LABEL_LENGTH - 1).trimEnd()}…`;
+}
+
 /** 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 {
@@ -377,6 +383,14 @@ const STYLE_PROPERTIES: ReadonlyArray<{
   { 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' },
+  { prop: 'flexBasis', label: 'Basis', type: 'string', group: 'Position' },
+  {
+    prop: 'alignSelf',
+    label: 'Self Align',
+    type: 'enum',
+    group: 'Position',
+    options: ['auto', 'stretch', 'flex-start', 'center', 'flex-end', 'baseline'],
+  },
   // -- Spacing (per-side) --
   { prop: 'marginTop', label: 'Margin T', type: 'number', group: 'Spacing' },
   { prop: 'marginRight', label: 'Margin R', type: 'number', group: 'Spacing' },
@@ -441,7 +455,24 @@ const STYLE_PROPERTIES: ReadonlyArray<{
     label: 'Blend',
     type: 'enum',
     group: 'Effects',
-    options: ['normal', 'multiply', 'screen', 'overlay'],
+    options: [
+      'normal',
+      'multiply',
+      'screen',
+      'overlay',
+      'darken',
+      'lighten',
+      'color-dodge',
+      'color-burn',
+      'hard-light',
+      'soft-light',
+      'difference',
+      'exclusion',
+      'hue',
+      'saturation',
+      'color',
+      'luminosity',
+    ],
   },
   { prop: 'filter', label: 'Filter', type: 'string', group: 'Effects' },
   { prop: 'backdropFilter', label: 'Backdrop', type: 'string', group: 'Effects' },
@@ -451,7 +482,24 @@ const STYLE_PROPERTIES: ReadonlyArray<{
     label: 'Cursor',
     type: 'enum',
     group: 'Effects',
-    options: ['auto', 'default', 'pointer', 'text', 'move', 'grab', 'not-allowed'],
+    options: [
+      'auto',
+      'default',
+      'pointer',
+      'text',
+      'move',
+      'wait',
+      'help',
+      'crosshair',
+      'not-allowed',
+      'grab',
+      'grabbing',
+      'zoom-in',
+      'zoom-out',
+      'col-resize',
+      'row-resize',
+      'none',
+    ],
   },
   // -- Transform --
   { prop: 'transform', label: 'Transform', type: 'string', group: 'Transform' },
@@ -461,6 +509,7 @@ const STYLE_PATH_PREFIX = 'style.';
 const PROP_PATH_PREFIX = 'prop.';
 /** Cap 7: inspector path prefix for the document's design tokens (`token.<name>`). */
 const TOKEN_PATH_PREFIX = 'token.';
+const PORTABLE_STORY_ARG_PATH_PREFIX = 'story.arg.';
 /** 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
@@ -468,11 +517,14 @@ const TOKEN_PATH_PREFIX = 'token.';
  *  `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
+ *  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';
+/** D20 — fallback id for callers that supply portable stories without the
+ * richer per-CSF-document projection. Story ids remain Storybook-owned. */
+const PORTABLE_DOCUMENT_ID = 'portable-document';
 /** 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
@@ -523,10 +575,8 @@ const LONGHAND_TO_SHORTHAND: Readonly<Record<string, string>> = {
  * 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).
+ * subset, not a writer-enforced ceiling. A React root node's native kind is
+ * its literal HTML tag name.
  */
 const CREATABLE_KINDS: ReadonlyArray<{ kind: string; label: string }> = [
   { kind: 'div', label: 'Container' },
@@ -539,11 +589,6 @@ const CREATABLE_KINDS: ReadonlyArray<{ kind: string; label: string }> = [
   { 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
@@ -583,6 +628,33 @@ export interface ReactWorldAuthoringOptions {
    * tracks WHICH story is active and reports the change.
    */
   onStoryApplied?: ((story: (UIStory & { id: string }) | null) => void) | undefined;
+  /** D20 — portable Storybook CSF stories associated with this native React
+   * root. When present they are the canonical provider exposed to the shell;
+   * the legacy registry story sources remain a compatibility fallback only. */
+  portableStories?: ReadonlyArray<PortableStoryRef> | undefined;
+  /** Compatibility identity when all portable stories belong to one module. */
+  portableDocument?: { label: string; path?: string | undefined } | undefined;
+  /** Source documents projected above their own portable CSF stories. */
+  portableDocuments?:
+    | ReadonlyArray<{
+        id: string;
+        label: string;
+        path?: string | undefined;
+        storyIds: ReadonlyArray<string>;
+      }>
+    | undefined;
+  /** Initially mounted portable story id (normally the explicit/default CSF
+   * story selected by the design-time layer). */
+  activePortableStoryId?: string | undefined;
+  /** Re-render hook for a portable CSF selection. The design-time layer owns
+   * Storybook mounting; this adapter owns only selection/provider routing. */
+  onPortableStoryApplied?: ((storyId: string | null) => void) | undefined;
+  /** Session-scoped Storybook Controls write. The design-time layer remounts
+   * the same composed story with these args; CSF remains the canonical
+   * definition and Reset restores its composed defaults. */
+  onPortableStoryArgsChanged?:
+    | ((storyId: string, args: Record<string, unknown>) => void)
+    | undefined;
   /**
    * B3 — the react world's registered components (a project's
    * `src/ui/registry.ts` `components`, `SceneUI.tsx`'s flat
@@ -591,8 +663,8 @@ export interface ReactWorldAuthoringOptions {
    * (§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
+   * `kind:'component'` node per registered key, plus one `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).
    */
@@ -619,8 +691,18 @@ export interface ReactWorldAuthoringOptions {
   worldId?: string | undefined;
 }
 
+export interface PortableStoryRef extends StoryRef {
+  args?: Readonly<Record<string, unknown>>;
+}
+
 export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
   readonly capabilities: AuthoringCapabilities;
+
+  readonly provenance: AuthoringProvenance = {
+    source: 'source-code',
+    label: 'jsx',
+    detail: 'The JSX source is the document — edits write back to the component source file.',
+  };
   private readonly writeBackend: SourceWriteBackend | undefined;
   private readonly computedStyle: ComputedStyleResolver;
   private readonly matchedCssRules: (el: unknown) => CssRuleTarget[];
@@ -687,14 +769,8 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
    * 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
+   * a path with no `valueEcho` of its own: structural writes and `editText`.
+   * A successful text write flips `hasText`, itself a
    * `findEmptyContainers` hint-eligibility criterion — text populates no `valueEcho`,
    * so neither existing reconcile branch fired for it).
    *
@@ -720,10 +796,21 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
   /** 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;
+  private readonly portableStories: ReadonlyArray<PortableStoryRef>;
+  private readonly portableStoryArgs = new Map<string, Record<string, unknown>>();
+  private readonly portableDocuments: ReadonlyArray<{
+    id: string;
+    label: string;
+    path?: string | undefined;
+    storyIds: ReadonlyArray<string>;
+  }>;
+  private readonly portableDefaultStoryId: string | null;
+  private readonly onPortableStoryApplied: ((storyId: string | null) => void) | undefined;
+  private readonly onPortableStoryArgsChanged:
+    | ((storyId: string, args: Record<string, unknown>) => 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). */
@@ -736,6 +823,7 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     | ((v: { componentKey: string; story: (UIStory & { id: string }) | null } | null) => void)
     | undefined;
   private readonly worldId: string | undefined;
+  private readonly storyHistory: JsonHistoryResource<Record<string, UIStory>> | null;
   /** 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 =
@@ -759,12 +847,25 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     priorInline: Map<string, string>;
   } | null = null;
 
+  /**
+   * Serializes {@link commitBoxEdit} runs so two gestures never overlap.
+   *
+   * `boxEdit.end()` fire-and-forgets an ASYNC commit (it cannot await — the
+   * gesture API is synchronous, driven straight from pointer/key handlers), and
+   * `editor-hotkeys.ts` drives `apply()`+`end()` on EVERY keypress. Hold an
+   * arrow key, or align a multi-selection, and the second commit calls
+   * a second source-history gesture while the first is still awaiting its
+   * writes. Chaining here keeps adapter preview/echo updates ordered too; the
+   * scoped history backend independently serializes each complete callback.
+   */
+  private boxEditTail: Promise<void> = Promise.resolve();
+
   constructor(
     private readonly root: OidElementLike,
     private readonly store: EditorStore,
     opts: ReactWorldAuthoringOptions = {},
   ) {
-    this.writeBackend = opts.writeBackend;
+    this.writeBackend = withProjectSourceHistory(opts.writeBackend, store.projectHistory);
     this.computedStyle = opts.computedStyle ?? browserOrInlineResolver;
     this.matchedCssRules =
       opts.matchedCssRules ??
@@ -772,9 +873,77 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     this.designTokens = opts.designTokens ?? (() => getDesignTokens());
     this.storySources = opts.storySources ?? [];
     this.onStoryApplied = opts.onStoryApplied;
+    this.portableStories = opts.portableStories ?? [];
+    for (const story of this.portableStories) {
+      this.portableStoryArgs.set(story.id, { ...(story.args ?? {}) });
+    }
+    const declaredPortableDocuments =
+      opts.portableDocuments ??
+      (this.portableStories.length > 0
+        ? [
+            {
+              id: PORTABLE_DOCUMENT_ID,
+              label: opts.portableDocument?.label ?? 'React Preview',
+              ...(opts.portableDocument?.path ? { path: opts.portableDocument.path } : {}),
+              storyIds: this.portableStories.map((story) => story.id),
+            },
+          ]
+        : []);
+    const knownStoryIds = new Set(this.portableStories.map((story) => story.id));
+    const claimedStoryIds = new Set<string>();
+    const documentIds = new Set<string>();
+    const portableDocuments = declaredPortableDocuments.flatMap((document) => {
+      if (documentIds.has(document.id)) return [];
+      documentIds.add(document.id);
+      const storyIds = document.storyIds.filter((storyId) => {
+        if (!knownStoryIds.has(storyId) || claimedStoryIds.has(storyId)) return false;
+        claimedStoryIds.add(storyId);
+        return true;
+      });
+      return storyIds.length > 0 ? [{ ...document, storyIds }] : [];
+    });
+    const unassignedStoryIds = this.portableStories
+      .map((story) => story.id)
+      .filter((storyId) => !claimedStoryIds.has(storyId));
+    if (unassignedStoryIds.length > 0) {
+      portableDocuments.push({
+        id: documentIds.has(PORTABLE_DOCUMENT_ID)
+          ? `${PORTABLE_DOCUMENT_ID}:unassigned`
+          : PORTABLE_DOCUMENT_ID,
+        label: opts.portableDocument?.label ?? 'React Preview',
+        ...(opts.portableDocument?.path ? { path: opts.portableDocument.path } : {}),
+        storyIds: unassignedStoryIds,
+      });
+    }
+    this.portableDocuments = portableDocuments;
+    this.portableDefaultStoryId = this.portableStories.some(
+      (story) => story.id === opts.activePortableStoryId,
+    )
+      ? (opts.activePortableStoryId ?? null)
+      : (this.portableStories[0]?.id ?? null);
+    this.onPortableStoryApplied = opts.onPortableStoryApplied;
+    this.onPortableStoryArgsChanged = opts.onPortableStoryArgsChanged;
+    this.activeStoryId = this.portableDefaultStoryId;
     this.catalogComponents = opts.catalogComponents ?? {};
     this.onIsolate = opts.onIsolate;
     this.worldId = opts.worldId;
+    this.storyHistory =
+      store.projectHistory && this.worldId
+        ? new JsonHistoryResource({
+            history: store.projectHistory,
+            kind: 'overlay',
+            scope: 'session',
+            sessionId: `react-story-${this.worldId}-${crypto.randomUUID()}`,
+            displayName: `${this.worldId} Story Overlay`,
+            capture: () => structuredClone(getStoryOverlay(this.worldId!) ?? {}),
+            restore: (stories) => {
+              setStoryOverlay(this.worldId!, structuredClone(stories));
+              if (this.isolated?.storyId)
+                this.doIsolate(this.isolated.nodeId, this.isolated.storyId);
+              this.store.notifyIngestEdit();
+            },
+          })
+        : null;
     this.capabilities = {
       transform: false, // no 3D gizmo — DOM has no Object3D pose (§1.F)
       material: false,
@@ -784,11 +953,6 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       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
@@ -889,25 +1053,93 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
 
   /** A4 — release the `vite:afterUpdate` reconcile subscription. Idempotent; safe when no
    *  HMR context was present (the disposer is `undefined`). */
-  disposeReactWorldAdapter(): void {
+  disposeReactRootAdapter(): void {
     this.disposeReloadSignal?.();
+    this.storyHistory?.dispose();
   }
 
-  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.
+  private componentName(n: OidNode): string | null {
     const entry = this.oidIndex.get(n.oid);
-    const component = entry?.component ?? getReactComponentName(n.el);
-    const label = component ? `${component}:${n.tag}` : n.tag;
+    return entry?.component ?? getReactComponentName(n.el) ?? null;
+  }
+
+  private elementLabel(n: OidNode, tree: OidTree): string {
+    // Preserve the explicit escape hatch, but make ordinary DOM semantics
+    // sufficient by default. Authored React should not need component splits
+    // or `data-vgai-name` merely to produce a legible hierarchy.
+    const editorLabel = normalizeElementText(n.el.getAttribute('data-vgai-name'));
+    if (editorLabel) return editorLabel;
+
+    const labelledBy = n.el.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const labels = labelledBy
+        .split(/\s+/)
+        .map((id) =>
+          Array.from(tree.nodes.values()).find(
+            (candidate) => candidate.el.getAttribute('id') === id,
+          ),
+        )
+        .map((candidate) => normalizeElementText(candidate?.el.textContent))
+        .filter((label): label is string => label !== null);
+      const combinedLabel = normalizeElementText(labels.join(' '));
+      if (combinedLabel) return combinedLabel;
+    }
+
+    const accessibleLabel = normalizeElementText(n.el.getAttribute('aria-label'));
+    if (accessibleLabel) return accessibleLabel;
+
+    // A semantic section without explicit ARIA normally takes its identity
+    // from its heading. Restrict this to direct children so a large nested
+    // subtree cannot accidentally lend an unrelated heading to its parent.
+    if (['section', 'article', 'aside', 'nav', 'main', 'header', 'footer'].includes(n.tag)) {
+      const heading = n.childIds
+        .map((id) => tree.nodes.get(id))
+        .find((child) => child !== undefined && /^h[1-6]$/.test(child.tag));
+      const headingText = normalizeElementText(heading?.el.textContent);
+      if (headingText) return headingText;
+    }
+
+    // Text-bearing HTML elements are already named by their content in the
+    // browser/accessibility model. Use the same identity, with a short cap so
+    // a paragraph cannot turn into an unbounded hierarchy row.
+    if (
+      /^(h[1-6]|p|span|label|button|a|time|output|dt|dd|li|legend|caption|summary)$/.test(n.tag)
+    ) {
+      const text = normalizeElementText(n.el.textContent);
+      if (text) return text;
+    }
+
+    for (const attribute of ['alt', 'title', 'placeholder', 'name']) {
+      const value = normalizeElementText(n.el.getAttribute(attribute));
+      if (value) return value;
+    }
+
+    const id = n.el.getAttribute('id');
+    if (id) return `#${id}`;
+    return n.tag;
+  }
+
+  private toEditorNode(n: OidNode, tree: OidTree = this.snapshot()): EditorNode {
+    // A component name marks only the boundary where that component enters the
+    // native tree. Descendants owned by the same component use their own DOM
+    // identity, avoiding the old `Game2048Page:div` repeated on every row.
+    const component = this.componentName(n);
+    const parent = n.parentId ? tree.nodes.get(n.parentId) : null;
+    const parentComponent = parent ? this.componentName(parent) : null;
+    const isComponentBoundary = component !== null && component !== parentComponent;
     const node: EditorNode = {
       id: n.id,
-      label,
+      label: isComponentBoundary ? component : this.elementLabel(n, tree),
+      ...(isComponentBoundary ? { secondaryLabel: `<${n.tag}>` } : {}),
+      role: isComponentBoundary ? 'component' : 'element',
       kind: n.tag,
       parentId: n.parentId,
       childIds: n.childIds,
       flags: { runtimeOnly: true },
     };
+    if (this.portableStories.length > 0 && node.parentId === null) {
+      return { ...node, parentId: this.activeStoryId };
+    }
     // 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
@@ -931,6 +1163,7 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     return {
       id: `${CATALOG_ID_PREFIX}${key}`,
       label: key,
+      role: 'component',
       kind: 'component',
       parentId: null,
       childIds: [],
@@ -938,13 +1171,14 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     };
   }
 
-  /** B3 — the one `'entry (live preview)'` node; its children are the
+  /** B3 — the one 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)',
+      label: 'Live Preview',
+      role: 'document',
       kind: 'group',
       parentId: null,
       childIds: rootIds,
@@ -952,16 +1186,56 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     };
   }
 
+  private portableDocumentNode(document: (typeof this.portableDocuments)[number]): EditorNode {
+    return {
+      id: document.id,
+      label: document.label,
+      ...(document.path ? { secondaryLabel: document.path } : {}),
+      role: 'document',
+      kind: 'tsx',
+      parentId: null,
+      childIds: [...document.storyIds],
+      flags: { runtimeOnly: true },
+    };
+  }
+
+  private portableDocumentForStory(storyId: string) {
+    return this.portableDocuments.find((document) => document.storyIds.includes(storyId)) ?? null;
+  }
+
+  private portableStoryNode(story: StoryRef, rootIds: string[]): EditorNode {
+    const active = story.id === this.activeStoryId;
+    return {
+      id: story.id,
+      label: story.label,
+      role: 'story',
+      kind: 'story',
+      parentId: this.portableDocumentForStory(story.id)?.id ?? PORTABLE_DOCUMENT_ID,
+      childIds: active ? rootIds : [],
+      flags: { runtimeOnly: true, active },
+    };
+  }
+
   readonly hierarchy: HierarchyProvider = {
     roots: () => {
-      const { nodes, rootIds } = this.snapshot();
-      if (!this.catalogOn) return rootIds.map((id) => this.toEditorNode(nodes.get(id)!));
+      const tree = this.snapshot();
+      const { nodes, rootIds } = tree;
+      if (this.portableStories.length > 0) {
+        return this.portableDocuments.map((document) => this.portableDocumentNode(document));
+      }
+      if (!this.catalogOn) return rootIds.map((id) => this.toEditorNode(nodes.get(id)!, tree));
       return [
         ...Object.keys(this.catalogComponents).map((key) => this.catalogNode(key)),
         this.entryNode(rootIds),
       ];
     },
     node: (id) => {
+      if (this.portableStories.length > 0) {
+        const document = this.portableDocuments.find((candidate) => candidate.id === id);
+        if (document) return this.portableDocumentNode(document);
+        const story = this.portableStories.find((candidate) => candidate.id === id);
+        if (story) return this.portableStoryNode(story, this.snapshot().rootIds);
+      }
       if (this.catalogOn) {
         if (id === CATALOG_ENTRY_ID) return this.entryNode(this.snapshot().rootIds);
         if (id.startsWith(CATALOG_ID_PREFIX)) {
@@ -969,8 +1243,9 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
           return key in this.catalogComponents ? this.catalogNode(key) : null;
         }
       }
-      const n = this.snapshot().nodes.get(id);
-      return n ? this.toEditorNode(n) : null;
+      const tree = this.snapshot();
+      const n = tree.nodes.get(id);
+      return n ? this.toEditorNode(n, tree) : null;
     },
     object3D: () => null, // react entities are DOM, not Object3D — no 3D gizmo binding
     idForObject3D: () => null,
@@ -993,6 +1268,13 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
    * `OidNode`s already resolved by `walkOidTree`, not a live `querySelectorAll`
    * over a DOM attribute string.
    *
+   * An element that EXPLICITLY opts out with inline `pointer-events:none` is
+   * skipped. The design-time host itself is `pointer-events:none`, so checking
+   * computed style would incorrectly inherit that host policy into every
+   * authorable descendant. Reading the node's own declaration instead preserves
+   * click-to-author descendants while making an authored full-viewport
+   * click-through wrapper behave as click-through here too.
+   *
    * 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
@@ -1015,6 +1297,7 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
         // 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;
+        if (styleProp(node.el.style, 'pointerEvents') === 'none') continue;
         const rect = node.el.getBoundingClientRect?.();
         if (!rect) continue; // no live rect (test fixture, or unmounted) — never a candidate
         if (
@@ -1056,7 +1339,13 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     height: number;
   }): DOMRectLike {
     const host = this.hostRect();
-    return { x: r.left - host.left, y: r.top - host.top, width: r.width, height: r.height };
+    const zoom = getWorldPan().zoom;
+    return {
+      x: (r.left - host.left) / zoom,
+      y: (r.top - host.top) / zoom,
+      width: r.width / zoom,
+      height: r.height / zoom,
+    };
   }
 
   /**
@@ -1227,7 +1516,16 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       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);
+      // Queue behind any still-running commit — see `boxEditTail`. A failed
+      // commit must not poison the chain for every later gesture, so the tail
+      // absorbs the rejection (commitBoxEdit reports its own failures).
+      this.boxEditTail = this.boxEditTail.then(
+        () => this.commitBoxEdit(id, session.touched, session.priorInline),
+        () => this.commitBoxEdit(id, session.touched, session.priorInline),
+      );
+      void this.boxEditTail.catch((error) => {
+        console.error('[ReactWorldAuthoringAdapter] box edit failed and was not committed.', error);
+      });
     },
   };
 
@@ -1244,6 +1542,7 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     touched: Map<string, string | number>,
     priorInline: Map<string, string>,
   ): Promise<void> {
+    const wasDirty = this.dirty;
     // 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
@@ -1252,34 +1551,44 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     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);
+    const commit = async (backend: SourceWriteBackend | undefined): Promise<void> => {
+      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;
+        await this.writeStyleEntry(id, prop, writeValue, priorInline.get(prop), backend);
+      }
+    };
+    // The history-managed backend supplies an explicit scoped writer. Holding
+    // the callback as one queue entry makes the gesture failure-atomic and
+    // prevents unrelated inspector writes from being absorbed/interleaved.
+    try {
+      if (this.writeBackend?.runGesture) {
+        await this.writeBackend.runGesture(`Edit ${touched.size} Styles`, commit);
+      } else {
+        await commit(this.writeBackend);
+      }
+    } catch (error) {
+      const node = this.snapshot().nodes.get(id);
+      for (const [prop, prior] of priorInline) {
+        this.clearEcho(id, `${STYLE_PATH_PREFIX}${prop}`);
+        if (node?.el.style) (node.el.style as Record<string, unknown>)[prop] = prior;
+      }
+      this.dirty = wasDirty;
+      this.store.notifyIngestEdit();
+      throw error;
     }
-    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();
-      },
-    });
   }
 
   /**
@@ -1313,6 +1622,22 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
 
   readonly inspector: InspectorProvider = {
     properties: (id: string): PropertyDescriptor[] => {
+      const portableDocument = this.portableDocuments.find((document) => document.id === id);
+      if (portableDocument) {
+        return portableDocument.path
+          ? [
+              {
+                path: 'document.path',
+                label: 'Source',
+                type: 'string',
+                readonly: true,
+                group: 'Document',
+              },
+            ]
+          : [];
+      }
+      if (this.portableStories.some((story) => story.id === id))
+        return this.portableStoryArgDescriptors(id);
       // 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
@@ -1345,6 +1670,19 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       );
     },
     get: (id, path) => {
+      const portableDocument = this.portableDocuments.find((document) => document.id === id);
+      if (portableDocument) {
+        return path === 'document.path' ? portableDocument.path : undefined;
+      }
+      if (this.portableStories.some((story) => story.id === id)) {
+        if (path === 'story.active') return id === this.activeStoryId;
+        if (path.startsWith(PORTABLE_STORY_ARG_PATH_PREFIX)) {
+          return this.portableStoryArgs.get(id)?.[
+            path.slice(PORTABLE_STORY_ARG_PATH_PREFIX.length)
+          ];
+        }
+        return undefined;
+      }
       // 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);
@@ -1406,6 +1744,18 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       return raw || undefined; // an unset computed value reads '' — surface as blank
     },
     set: (id, path, value) => {
+      if (this.portableDocuments.some((document) => document.id === id)) return;
+      if (this.portableStories.some((story) => story.id === id)) {
+        if (!path.startsWith(PORTABLE_STORY_ARG_PATH_PREFIX)) return;
+        const name = path.slice(PORTABLE_STORY_ARG_PATH_PREFIX.length);
+        const current = this.portableStoryArgs.get(id);
+        if (!current || !(name in current)) return;
+        const next = { ...current, [name]: value };
+        this.portableStoryArgs.set(id, next);
+        this.onPortableStoryArgsChanged?.(id, { ...next });
+        this.store.notifyIngestEdit();
+        return;
+      }
       if (this.isCatalogId(id)) {
         if (path.startsWith(STORY_PROP_PATH_PREFIX)) {
           this.writeStoryProp(id, path.slice(STORY_PROP_PATH_PREFIX.length), value);
@@ -1464,6 +1814,52 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     },
   };
 
+  /** Storybook Controls descriptors for an ordinary CSF story node. Functions
+   * and other non-serializable implementation values stay out of the form;
+   * they remain present in the complete args object passed to the composed
+   * story. */
+  private portableStoryArgDescriptors(storyId: string): PropertyDescriptor[] {
+    const args = this.portableStoryArgs.get(storyId) ?? {};
+    return Object.entries(args).flatMap(([name, value]) => {
+      if (typeof value === 'function' || typeof value === 'symbol' || value === undefined)
+        return [];
+      const type: PropertyDescriptor['type'] =
+        typeof value === 'boolean'
+          ? 'boolean'
+          : typeof value === 'number'
+            ? 'number'
+            : typeof value === 'string'
+              ? 'string'
+              : 'json';
+      return [
+        {
+          path: `${PORTABLE_STORY_ARG_PATH_PREFIX}${name}`,
+          label: name,
+          type,
+          group: 'Args',
+        },
+      ];
+    });
+  }
+
+  /** Current complete args for a portable story, including callbacks omitted
+   * from the visual Controls list. Returned as a copy so inspector UI cannot
+   * mutate adapter state behind the provider contract. */
+  portableArgs(storyId: string): Record<string, unknown> | null {
+    const args = this.portableStoryArgs.get(storyId);
+    return args ? { ...args } : null;
+  }
+
+  /** Restore the selected story's composed CSF defaults. */
+  resetPortableArgs(storyId: string): void {
+    const story = this.portableStories.find((candidate) => candidate.id === storyId);
+    if (!story) return;
+    const next = { ...(story.args ?? {}) };
+    this.portableStoryArgs.set(storyId, next);
+    this.onPortableStoryArgsChanged?.(storyId, { ...next });
+    this.store.notifyIngestEdit();
+  }
+
   /** 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 {
@@ -1558,7 +1954,11 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       data: base?.data ?? {},
       props: { ...(base?.props ?? {}), [propName]: value },
     };
-    setStoryOverlay(this.worldId, { ...(getStoryOverlay(this.worldId) ?? {}), [storyId]: patched });
+    this.storyHistory?.assertCanMutate();
+    const before = structuredClone(getStoryOverlay(this.worldId) ?? {});
+    const after = { ...before, [storyId]: patched };
+    setStoryOverlay(this.worldId, after);
+    void this.storyHistory?.record(`Edit ${propName}`, before, structuredClone(after));
     this.doIsolate(nodeId, storyId); // re-render against the patched story
   }
 
@@ -1624,9 +2024,26 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
    */
   readonly stories: StoriesProvider = {
     storiesFor: (_nodeId): StoryRef[] =>
-      [...this.mergedStories().entries()].map(([id, story]) => ({ id, label: story.label })),
+      this.portableStories.length > 0
+        ? [...this.portableStories]
+        : [...this.mergedStories().entries()].map(([id, story]) => ({ id, label: story.label })),
     active: (_nodeId) => this.activeStoryId,
     apply: (_nodeId, storyId) => {
+      if (this.portableStories.length > 0) {
+        if (storyId !== null && !this.portableStories.some((story) => story.id === storyId)) {
+          console.warn(
+            `[ReactWorldAuthoringAdapter] stories.apply: unknown portable CSF story id "${storyId}" — ignoring.`,
+          );
+          return;
+        }
+        // Portable CSF always renders a design state. Clearing the picker
+        // means "restore the document's default", not "orphan the live DOM
+        // roots outside every story row".
+        this.activeStoryId = storyId ?? this.portableDefaultStoryId;
+        this.onPortableStoryApplied?.(storyId);
+        this.store.notifyIngestEdit();
+        return;
+      }
       if (storyId === null) {
         this.activeStoryId = null;
         this.onStoryApplied?.(null);
@@ -1701,14 +2118,8 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
   }
 
   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.)
+    // Every structural op journals complete next-file text. Undo never needs to
+    // address a moved or deleted element by an OID that may no longer exist.
     create: (kind, parentId) => {
       void this.structOp(parentId ?? '', 'create', { wrapperTag: kind });
       return '';
@@ -1862,6 +2273,21 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     return this.snapshot().nodes.get(id)?.oid;
   }
 
+  /**
+   * C4 (spec §9): map an entity id to its component/source location, when available —
+   * the read side of `oidIndex` (populated from `SourceWriteBackend.index()`, same as
+   * `toEditorNode`'s label lookup). Returns `undefined` when the id has no OID (e.g. a
+   * catalog node) or the index hasn't resolved (no dev-server backend, or the index
+   * fetch hasn't landed yet) — an honest "unavailable", never a guess. The editor UI
+   * (`react-inspector-section.tsx`'s `LaneDisclosure`) uses this to offer copy-path /
+   * go-to-line without ever exposing a write surface.
+   */
+  sourceLocation(id: string): OidEntry | undefined {
+    const oid = this.oidOf(id);
+    if (!oid) return undefined;
+    return this.oidIndex.get(oid);
+  }
+
   /** Run a structural op through the write backend (loud degradation without one). */
   private async structOp(
     id: string,
@@ -1885,9 +2311,6 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       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
@@ -1897,96 +2320,9 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
   }
 
   /**
-   * 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
+   * T0 (spec 27 §4, B1) — the write body extracted from {@link writeStyle}, returning
+   * whether source changed so a multi-property box gesture can reconcile once.
+   * `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
@@ -1999,7 +2335,8 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     prop: string,
     value: string | number,
     priorInlineOverride?: string,
-  ): Promise<PendingUndo | null> {
+    backend: SourceWriteBackend | undefined = this.writeBackend,
+  ): Promise<boolean> {
     // 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.
@@ -2007,37 +2344,29 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     const n = this.snapshot().nodes.get(id);
     if (!n) {
       this.clearEcho(id, echoPath);
-      return null;
+      return false;
     }
-    if (!this.writeBackend) {
+    if (!backend) {
       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;
+      return false;
     }
     // 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) {
+    if (backend.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),
-        );
+        const { rule } = cssTarget;
+        const res = await backend.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)),
-          };
+          return true;
         }
         if (!res.generated) {
           this.clearEcho(id, echoPath);
@@ -2045,18 +2374,12 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
             `[ReactWorldAuthoringAdapter] CSS write refused/no-op for selector ` +
               `"${rule.selectorText}" prop "${prop}": ${res.error ?? 'no change'}`,
           );
-          return null;
+          return false;
         }
         // 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));
+    const res = await backend.writeStyle(n.oid, prop, String(value));
     if (!res.changed) {
       this.clearEcho(id, echoPath);
       if (res.dynamic) this.markDynamic(id, echoPath);
@@ -2070,7 +2393,7 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
         `[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;
+      return false;
     }
     this.dirty = true;
     // D-A4 (wave 13, docs/WAVE13-JSX-SPREAD-UNDO-DESIGN.md): if this write took the
@@ -2080,7 +2403,6 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     // 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
@@ -2099,17 +2421,11 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       (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),
-    };
+    return true;
   }
 
   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);
+    await this.writeStyleEntry(id, prop, value);
   }
 
   /**
@@ -2125,38 +2441,11 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
   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();
   }
 
   /**
@@ -2191,11 +2480,6 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       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
@@ -2205,16 +2489,6 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
     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).
@@ -2247,7 +2521,6 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       );
       return;
     }
-    const prev = cp.props[prop] ?? '';
     const res = await this.writeBackend.writeProp(cp.callSiteOid, prop, value);
     if (!res.changed) {
       this.clearEcho(id, echoPath);
@@ -2262,16 +2535,6 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       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();
   }
 
@@ -2293,11 +2556,8 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       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);
+    // Whole-file source history restores deletion without fabricating an inverse
+    // element insertion from an OID that no longer exists.
     // 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.
@@ -2343,36 +2603,11 @@ export class ReactWorldAuthoringAdapter implements AuthoringAdapter {
       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);
+    // One prepared batch source write becomes one history transaction.
     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);
   }