@volter/editor-ui 0.5.211 → 0.5.212

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

@@ -0,0 +1,2602 @@
+/** Source authoring over mounted, data-oid-stamped React DOM. The shared
+ * projector supplies hierarchy and selection; source writes prepare complete
+ * next-file text and commit through checksum-guarded history. Backend absence
+ * leaves inspection available and makes writes report their unavailable destination. */
+
+import { editorHost } from '@volter/sdk/host';
+import { activeBreakpoint } from '@volter/sdk/breakpoint-state';
+import {
+  cssTextForStyleValue,
+  numericStyleValue,
+  preserveNumericStyleUnit,
+} from '@volter/sdk/css-numeric-style';
+import { WORLD_SCOPE_NODE_ID } from '@volter/sdk/stories-scope';
+import { createStructWritePipe, type StructOpOptions } from '../host/authoring/struct-write-pipe';
+import { getRootPan } from '@volter/sdk/world-pan-state';
+import {
+  resolvesLiveOnly,
+  runWritePipe,
+  type WriteAck,
+  type WriteResolution,
+} from '@volter/sdk/write-pipe';
+import { editorConsole } from '@volter/sdk/editor-console';
+import type { ShellStore } from '@volter/sdk/shell-store';
+import { withProjectSourceHistory } from '@volter/sdk/history/source-history-backend';
+import { projectOidDom } from '../host/projection/dom';
+import { storyArgPropertyDescriptors } from '../host/stories/story-arg-descriptors';
+import type { StoryPresentationIndex } from '../host/stories/story-presentation';
+import { showTransientHint } from '@volter/sdk/transient-hint';
+import {
+  camelToKebab,
+  type DesignToken,
+  type EmptyCandidate,
+  findClassRuleSource,
+  findEmptyContainers,
+  firstPartyStylesheetFiles,
+  getComponentProps,
+  getComputedStyleValue,
+  getDesignTokens,
+  getMatchedCssRules,
+  getReactComponentName,
+} from '@volter/sdk/ui-source/inspect';
+import type { ComponentPropSpec, OidEntry } from '@volter/editor-react/source/oid-transform';
+import { relativeImportSpecifier } from '@volter/editor-react/source/relative-import-specifier';
+import type { SourceWriteBackend } from '@volter/sdk/ui-source/source-write-backend';
+import { writeCsfStory, writeNamedStyle } from '@volter/sdk/ui-source/source-write-backend';
+import {
+  type CssRuleTarget,
+  namedStyleRuleFor,
+  pickCssRuleTarget,
+  tokenReferenceGuardText,
+} from '@volter/editor-react/source/writer';
+import { UI_COMPONENTS_DOCUMENT_ID } from '@volter/sdk/workspace-document-ids';
+import { activateWorkspaceDocument } from '@volter/sdk/workspace-document-registry';
+import type {
+  AssetDropContext,
+  AssetDropProvider,
+  AuthoringAdapter,
+  AuthoringCapabilities,
+  AuthoringProvenance,
+  BoxEditProvider,
+  ColorSampleProvider,
+  ComponentInstanceApplyResult,
+  ComponentInstancesProvider,
+  DOMRectLike,
+  EditorNode,
+  HierarchyProvider,
+  InspectorProvider,
+  NodeCreationSite,
+  PersistenceProvider,
+  PickProvider,
+  PropertyDescriptor,
+  RectProvider,
+  RelatedSubjectsProvider,
+  SelectionProvider,
+  StoriesProvider,
+  StoryRef,
+  StructureProvider,
+  TextProvider,
+  TruthProvider,
+  WriteAnchorKind,
+} from '@volter/project/adapter';
+
+/** Live DOM members shared by the mounted root and the focused-story proxy.
+ * The proxy exposes the layer's attributes, style and geometry with the focused
+ * story's children and text; descendants are the mounted DOM elements themselves. */
+export interface OidElementLike {
+  readonly tagName: string;
+  /** The focused-story proxy omits the namespace; live DOM descendants supply it. */
+  readonly namespaceURI?: string | null;
+  readonly children: ArrayLike<Element>;
+  getAttribute(name: string): string | null;
+  readonly style: CSSStyleDeclaration;
+  getBoundingClientRect(): DOMRect;
+  /** Rendered text for the client-side leaf check; dynamic bodies are guarded in source. */
+  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 a camelCase inline style property from its live declaration. */
+function styleProp(style: CSSStyleDeclaration, prop: string): string {
+  return style.getPropertyValue(camelToKebab(prop));
+}
+
+const RGB_RE = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+\s*)?\)$/;
+
+/** Normalize hex and rgb/rgba CSS colors into the #rrggbb shape accepted by
+ * color inputs. Unsupported values return undefined. */
+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]!)}`;
+}
+
+/** CSS property and preview-value mapping for a box-edit patch. */
+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;
+}
+
+/** Map spatial box-edit keys to CSS properties. x/y require positioned
+ * elements; rotate becomes a transform string. Unsupported keys return null. */
+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';
+const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
+const VOID_HTML_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+/** Empty-layout hints are for HTML elements that could receive content.
+ * SVG geometry (especially zero-width `line`/`path` bounds) and HTML void
+ * elements are leaves by definition, not collapsed layout containers. */
+function canContainDomChildren(el: OidElementLike, tag: string): boolean {
+  const namespace = el.namespaceURI;
+  if (namespace !== undefined && namespace !== null && namespace !== HTML_NAMESPACE) return false;
+  return !VOID_HTML_ELEMENTS.has(tag);
+}
+
+function projectSourcePath(path: string): string {
+  const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '');
+  const marker = normalized.lastIndexOf('/src/');
+  return marker >= 0 ? normalized.slice(marker + 1) : normalized;
+}
+
+/** One OID-tagged DOM element resolved into the adapter's internal tree. */
+interface OidNode {
+  /** Entity id assigned by the shared DOM projector, disambiguating repeated source OIDs. */
+  id: string;
+  /** Source OID, shared by repeated instances of the same authored element. */
+  oid: string;
+  tag: string;
+  el: OidElementLike;
+  parentId: string | null;
+  childIds: string[];
+}
+
+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[];
+}
+
+/** Derive source OIDs and labels from the projected live DOM. */
+function walkOidTree(root: OidElementLike): OidTree {
+  return oidTreeFromProjection(projectOidDom(root));
+}
+
+function oidTreeFromProjection(projection: {
+  readonly nodes: ReadonlyMap<
+    string,
+    { object: OidElementLike; parentId: string | null; childIds: readonly string[] }
+  >;
+  readonly rootIds: readonly string[];
+}): OidTree {
+  const nodes = new Map<string, OidNode>();
+  for (const [id, node] of projection.nodes) {
+    nodes.set(id, {
+      id,
+      oid: node.object.getAttribute(OID_ATTR) ?? id,
+      tag: node.object.tagName.toLowerCase(),
+      el: node.object,
+      parentId: node.parentId,
+      childIds: [...node.childIds],
+    });
+  }
+  return { nodes, rootIds: [...projection.rootIds] };
+}
+
+/** Grouped CSS inspector properties supported by the source writer. */
+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' },
+  // CSS Grid container and item properties retain their native value syntax.
+  { prop: 'gridTemplateColumns', label: 'Columns', type: 'string', group: 'Layout' },
+  { prop: 'gridTemplateRows', label: 'Rows', type: 'string', group: 'Layout' },
+  {
+    prop: 'gridAutoFlow',
+    label: 'Flow',
+    type: 'enum',
+    group: 'Layout',
+    options: ['row', 'column', 'row dense', 'column dense'],
+  },
+  { prop: 'rowGap', label: 'Row Gap', type: 'number', group: 'Layout' },
+  { prop: 'columnGap', label: 'Col Gap', type: 'number', group: 'Layout' },
+  { prop: 'gridColumn', label: 'Grid Col', type: 'string', group: 'Layout' },
+  { prop: 'gridRow', label: 'Grid Row', type: 'string', group: 'Layout' },
+  {
+    prop: 'justifySelf',
+    label: 'Justify Self',
+    type: 'enum',
+    group: 'Layout',
+    options: ['auto', 'start', 'center', 'end', 'stretch'],
+  },
+  {
+    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' },
+  { 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' },
+  { 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' },
+  // Background longhands keep computed reads consistent with the authored CSS model.
+  { prop: 'backgroundImage', label: 'Fills', type: 'string', group: 'Fill' },
+  // Image-layer companions apply to the complete background stack.
+  {
+    prop: 'backgroundSize',
+    label: 'Size',
+    type: 'enum',
+    group: 'Fill',
+    options: ['auto', 'cover', 'contain'],
+  },
+  { prop: 'backgroundPosition', label: 'Pos', type: 'string', group: 'Fill' },
+  {
+    prop: 'backgroundRepeat',
+    label: 'Repeat',
+    type: 'enum',
+    group: 'Fill',
+    options: ['repeat', 'no-repeat', 'repeat-x', 'repeat-y'],
+  },
+  // -- 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',
+      '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' },
+  { prop: 'textShadow', label: 'Text Shadow', type: 'string', group: 'Effects' },
+  {
+    prop: 'cursor',
+    label: 'Cursor',
+    type: 'enum',
+    group: 'Effects',
+    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' },
+];
+const STYLE_PATH_PREFIX = 'style.';
+/** Where this adapter's writes land — the ONE spelling, read by both the
+ *  save-status provider and the per-edit ack the pipe returns, so the two can
+ *  never name different places. */
+const JSX_SOURCE_DESTINATION =
+  'component source (JSX, via /__ui-source — writes are immediate; nothing pending to flush)';
+/** …and the honest floor when no writer is bound. */
+const NO_BACKEND_DESTINATION = 'component source (JSX) — no source-write backend in this session';
+/** Inspector path prefix for editable component props. */
+const PROP_PATH_PREFIX = 'prop.';
+/** Inspector path prefix for document design tokens. */
+const TOKEN_PATH_PREFIX = 'token.';
+const PORTABLE_STORY_ARG_PATH_PREFIX = 'story.arg.';
+/** Session guard key for text edits, which have no property descriptor. */
+const TEXT_PATH = 'text';
+/** Watch selection for 30 × 40ms (1.2s) after an HMR update. */
+const SELECTION_REPAIR_ATTEMPTS = 30;
+/** Report selection repair once per session while restoring resolvable IDs. */
+let reportedSelectionRepair = false;
+const SELECTION_REPAIR_INTERVAL_MS = 40;
+
+const DYNAMIC_EXPRESSION_GUARD =
+  'The source value is a dynamic expression, so replacing it with a literal is guarded.';
+
+/** CSS shorthand ownership. Per-side writes expand and remove governing
+ * shorthands so React receives one vocabulary for each property. Nested
+ * shorthands expand from outermost to innermost. */
+const SHORTHAND_LONGHANDS: Readonly<Record<string, readonly string[]>> = {
+  border: ['borderWidth', 'borderStyle', 'borderColor'],
+  borderWidth: ['borderTopWidth', 'borderRightWidth', 'borderBottomWidth', 'borderLeftWidth'],
+  borderStyle: ['borderTopStyle', 'borderRightStyle', 'borderBottomStyle', 'borderLeftStyle'],
+  borderColor: ['borderTopColor', 'borderRightColor', 'borderBottomColor', 'borderLeftColor'],
+  borderRadius: [
+    'borderTopLeftRadius',
+    'borderTopRightRadius',
+    'borderBottomRightRadius',
+    'borderBottomLeftRadius',
+  ],
+  padding: ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
+  margin: ['marginTop', 'marginRight', 'marginBottom', 'marginLeft'],
+  inset: ['top', 'right', 'bottom', 'left'],
+};
+
+/** Longhand -> its immediate shorthand, derived from the table above so the
+ *  two directions cannot disagree. */
+const SHORTHAND_OF: ReadonlyMap<string, string> = new Map(
+  Object.entries(SHORTHAND_LONGHANDS).flatMap(([shorthand, longhands]) =>
+    longhands.map((longhand) => [longhand, shorthand] as const),
+  ),
+);
+
+/** The shorthands covering `prop`, OUTERMOST FIRST — `borderTopWidth` gives
+ *  `['border', 'borderWidth']`. Empty for a property no shorthand owns. */
+function shorthandChain(prop: string): readonly string[] {
+  const chain: string[] = [];
+  for (let cursor = SHORTHAND_OF.get(prop); cursor; cursor = SHORTHAND_OF.get(cursor)) {
+    chain.unshift(cursor);
+  }
+  return chain;
+}
+
+/** `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]),
+);
+
+/** Map side and corner longhands to their controlling shorthand for echo
+ * updates after removing an override. */
+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',
+};
+
+/** Curated HTML kinds offered by structure.create. The source writer emits
+ * self-closing JSX tags for these names. */
+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' },
+];
+
+type DomAssetDropPlan =
+  | {
+      ok: true;
+      parentId: string;
+      snippet: string;
+      ensureImport: { name: string; module: string; kind: 'default' | 'named' };
+    }
+  | { ok: false; reason: string };
+
+function serializedComponentValue(value: unknown, spec: ComponentPropSpec): string {
+  if (spec.type === 'number') return String(Number(value));
+  if (spec.type === 'boolean') return value === true || value === 'true' ? 'true' : 'false';
+  if (spec.type === 'vec3' && Array.isArray(value)) {
+    return `[${value.map((entry) => Number(entry)).join(', ')}]`;
+  }
+  if (spec.type === 'json') return JSON.stringify(value);
+  return JSON.stringify(String(value));
+}
+
+interface ReactRootAuthoringOptions {
+  /** Source-write transport. Absent in sessions without source-write support. */
+  writeBackend?: SourceWriteBackend | undefined;
+  /** Design tokens visible in this root's CSS scope. */
+  designTokens?: (() => DesignToken[]) | undefined;
+  /** Portable CSF stories associated with this React root. */
+  portableStories?: ReadonlyArray<PortableStoryRef> | undefined;
+  /** Native Storybook Category → Folder → Component index. When present,
+   *  both the hierarchy and the board consume this same derived projection;
+   *  CSF remains the only authored data. */
+  portableHierarchy?: StoryPresentationIndex | 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;
+
+}
+
+interface PortableStoryRef extends StoryRef {
+  args: Readonly<Record<string, unknown>>;
+  /** CSF export name addressed by save-as, rename and delete. */
+  name: string;
+  /** Project-relative source path. */
+  modulePath: string;
+}
+
+/** The default: this adapter's own truth is the component's JSX source. */
+const JSX_SOURCE_PROVENANCE: AuthoringProvenance = {
+  source: 'source-code',
+  label: 'jsx',
+  detail: 'The JSX source is the document — edits write back to the component source file.',
+};
+
+/** The element's literal class tokens, off the live DOM `class` attribute. */
+function classTokensOf(el: OidElementLike): string[] {
+  const raw = el.getAttribute('class') ?? '';
+  return raw.split(/\s+/).filter(Boolean);
+}
+
+/** Does the LIVE inline style declare this property? Deliberately the live
+ *  read, not the source: a preview-patched inline value also wins the cascade,
+ *  so the conservative answer keeps a class-routed write from landing a
+ *  declaration that never paints. */
+function liveInlineDeclares(el: OidElementLike, prop: string): boolean {
+  return el.style.getPropertyValue(camelToKebab(prop)) !== '';
+}
+
+export class ReactRootAuthoringAdapter implements AuthoringAdapter {
+  readonly capabilities: AuthoringCapabilities;
+
+  readonly provenance = JSX_SOURCE_PROVENANCE;
+  private readonly writeBackend: SourceWriteBackend | undefined;
+  private hierarchySnapshotCache: OidTree | null = null;
+  private hierarchySnapshotClearQueued = false;
+  private readonly matchedCssRules = (el: unknown): CssRuleTarget[] =>
+    getMatchedCssRules(el as Element) as CssRuleTarget[];
+  private readonly designTokens: () => DesignToken[];
+  private readonly designTokenValue: (name: string) => string | undefined;
+  /** 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;
+  /** Optimistic inspector values, keyed by node and full property path.
+   * Writes populate them before awaiting source; refusals clear individual
+   * entries, and HMR reconciliation clears the remaining echo. */
+  private readonly valueEcho = new Map<string, Map<string, unknown>>();
+  /** Session-scoped source guard reasons. A refused dynamic write disables
+   * that field for subsequent edits; this does not predict source literality. */
+  private readonly guardedPaths = new Map<string, string>();
+  /** Session-local pick locks. Canvas click and marquee skip locked nodes,
+   * while hierarchy selection remains available for unlocking. */
+  private readonly lockedIds = new Set<string>();
+  /** Successful structural/text writes awaiting their post-HMR DOM refresh.
+   * Each landed update notifies the store and drains one pending reconcile. */
+  private pendingSourceReconcile = 0;
+  /**
+   * The last non-empty selection this adapter's tree served — the input to
+   * {@link repairSelectionAfterReprojection}.
+   */
+  private lastResolvedSelection: readonly string[] = [];
+  /** One repair watcher per re-projection; see {@link scheduleSelectionRepair}. */
+  private selectionRepairWatching = false;
+  /** Release the Vite HMR or hosted story-registry reconciliation subscription. */
+  private readonly disposeReloadSignal: () => void;
+  // Rename and delete update this list before discovery republishes it.
+  private readonly portableStories: PortableStoryRef[];
+  private readonly portableStoryArgs = new Map<string, Record<string, unknown>>();
+  private readonly portableHierarchy: StoryPresentationIndex | null;
+  private readonly portableDefaultStoryId: string | null;
+  private readonly onPortableStoryApplied: ((storyId: string | null) => void) | undefined;
+  private readonly onPortableStoryArgsChanged:
+    | ((storyId: string, args: Record<string, unknown>) => void)
+    | undefined;
+  /** The currently applied portable story, or `null` when this root has no
+   * portable CSF document. */
+  private activeStoryId: string | null = null;
+  /** Current box gesture. touched keeps the final value per CSS property;
+   * priorInline captures each property before its first live preview. */
+  private boxEditSession: {
+    id: string;
+    touched: Map<string, string | number>;
+    priorInline: Map<string, string>;
+    /** The one hint this gesture already showed for a move it cannot write. */
+    hinted?: boolean;
+  } | 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: ShellStore,
+    opts: ReactRootAuthoringOptions,
+  ) {
+    this.writeBackend = withProjectSourceHistory(opts.writeBackend, store.projectHistory);
+    // Read project custom properties within this root's scoped CSS container.
+    const tokenStyle = () => {
+      const root = this.root as unknown as Element;
+      // Custom properties inherit from the mounted CSS scope below this layer.
+      // Read that scope to include the authored token values.
+      const el = root.querySelector('[data-volter-mount-styles]') ??
+        root.closest('[data-volter-mount-styles]') ?? root;
+      return getComputedStyle(el);
+    };
+    this.designTokens = opts.designTokens ?? (() => getDesignTokens(tokenStyle()));
+    // Read one custom property per field so same-turn CSS edits stay visible.
+    this.designTokenValue = opts.designTokens
+      ? (name) => opts.designTokens!().find((token) => token.name === name)?.value
+      : (name) => tokenStyle().getPropertyValue(name).trim() || undefined;
+    this.portableStories = [...(opts.portableStories ?? [])];
+    for (const story of this.portableStories) {
+      this.portableStoryArgs.set(story.id, { ...story.args });
+    }
+    this.portableHierarchy = opts.portableHierarchy ?? null;
+    this.portableDefaultStoryId = opts.activePortableStoryId ?? null;
+    this.onPortableStoryApplied = opts.onPortableStoryApplied;
+    this.onPortableStoryArgsChanged = opts.onPortableStoryArgsChanged;
+    this.activeStoryId = this.portableDefaultStoryId;
+    this.capabilities = {
+      transform: false, // no 3D gizmo — DOM has no Object3D pose
+      inspectorFields: true,
+      persist: true,
+    };
+    // Reconcile optimistic values when HMR or the hosted story registry publishes the updated tree.
+    const hot = import.meta.hot;
+    if (hot) {
+      const onAfterUpdate = (): void => this.reconcileEchoAfterReload();
+      hot.on('vite:afterUpdate', onAfterUpdate);
+      this.disposeReloadSignal = () => hot.off('vite:afterUpdate', onAfterUpdate);
+    } else {
+      // Hosted writes refresh story modules; registry publication signals the
+      // resulting DOM projection for echo and selection reconciliation.
+      const unsubscribe = editorHost().stories.subscribe(() => this.reconcileEchoAfterReload());
+      this.disposeReloadSignal = unsubscribe;
+    }
+    if (this.writeBackend) {
+      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);
+  }
+
+  /**
+   * One coherent tree for a synchronous hierarchy consumer. Composite roots
+   * walk every child adapter by calling `node(id)` once per row; projecting the
+   * complete DOM on every lookup turns that ordinary walk into O(rows²).
+   * Inspector and write paths keep using {@link snapshot} directly, so only
+   * hierarchy reads share this task-bounded view and every later task sees the
+   * current DOM.
+   */
+  private hierarchySnapshot(): OidTree {
+    this.hierarchySnapshotCache ??= this.snapshot();
+    if (!this.hierarchySnapshotClearQueued) {
+      this.hierarchySnapshotClearQueued = true;
+      queueMicrotask(() => {
+        this.hierarchySnapshotCache = null;
+        this.hierarchySnapshotClearQueued = false;
+      });
+    }
+    return this.hierarchySnapshotCache;
+  }
+
+  private async refreshOidIndex(): Promise<void> {
+    const index = await this.writeBackend?.index();
+    if (!index) return;
+    this.oidIndex = new Map(Object.entries(index));
+    this.store.notifyIngestEdit();
+  }
+
+  // --- Optimistic inspector values ---
+  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);
+  }
+
+  /** Remember the source guard's reason for this node and property path. */
+  private markGuarded(id: string, path: string, reason: string): void {
+    this.guardedPaths.set(`${id}|${path}`, reason);
+  }
+
+  /** 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 };
+  }
+
+  /** Clear optimistic values after HMR, notify pending structural/text
+   * changes, and schedule bounded selection repair for the remounted tree. */
+  reconcileEchoAfterReload(): void {
+    // BEFORE the early return: a re-projection triggered by a source edit this
+    // adapter did NOT make (a hand edit, another lane's write) has neither an
+    // echo nor a pending reconcile, and it drops the selection exactly the
+    // same way.
+    this.scheduleSelectionRepair();
+    if (this.valueEcho.size === 0 && this.pendingSourceReconcile === 0) return;
+    this.valueEcho.clear();
+    if (this.pendingSourceReconcile > 0) this.pendingSourceReconcile--;
+    this.store.notifyIngestEdit();
+  }
+
+  /** Watch the remounted tree for lost selection during a bounded interval.
+   * Restore only IDs that still resolve and report once per watch. */
+  private scheduleSelectionRepair(): void {
+    if (this.selectionRepairWatching) return;
+    if (this.lastResolvedSelection.length === 0) return;
+    this.selectionRepairWatching = true;
+    let attempts = 0;
+    let reported = false;
+    const tick = (): void => {
+      attempts++;
+      // Cover every update in the window; repeated repairs share one report.
+      reported = this.repairSelectionAfterReprojection(reported) || reported;
+      if (attempts >= SELECTION_REPAIR_ATTEMPTS) {
+        this.selectionRepairWatching = false;
+        return;
+      }
+      setTimeout(tick, SELECTION_REPAIR_INTERVAL_MS);
+    };
+    setTimeout(tick, SELECTION_REPAIR_INTERVAL_MS);
+  }
+
+  /**
+   * One repair attempt. Returns whether it SAID something, so the watcher can
+   * report once and restore as many times as the re-projection needs.
+   *
+   * The remembered set is NOT consumed: `selection.get` overwrites it with
+   * every non-empty selection it serves, so it always names the last selection
+   * the author actually had, and a second drop inside the same window is
+   * repaired from the same truth.
+   */
+  private repairSelectionAfterReprojection(alreadyReported: boolean): boolean {
+    const remembered = this.lastResolvedSelection;
+    if (remembered.length === 0) return false;
+    if (this.store.selectedEntityIds.size > 0) return false; // not lost (yet)
+    const tree = this.snapshot();
+    const alive = remembered.filter((id) => tree.nodes.has(id));
+    if (alive.length === 0) {
+      if (!alreadyReported) {
+        console.warn(
+          '[ReactRootAuthoringAdapter] the re-projection dropped the selection ' +
+            `(${remembered.join(', ')}) and none of those ids resolve in the remounted tree, so ` +
+            'it cannot be restored. An inspector write issued now has no subject — re-select.',
+        );
+      }
+      this.lastResolvedSelection = [];
+      return true;
+    }
+    if (!alreadyReported && !reportedSelectionRepair) {
+      reportedSelectionRepair = true;
+      console.warn(
+        '[ReactRootAuthoringAdapter] OPEN DEFECT, repaired: an HMR re-projection drops this ' +
+          "root's selection, and the editor is putting it back — restoring " +
+          `${alive.length} of ${remembered.length} id(s) that still resolve in the remounted ` +
+          `tree (${alive.join(', ')}). A write issued in that window has no subject. Named once ` +
+          'per session; the repair runs on every re-projection.',
+      );
+    }
+    this.store.selectMultiple([...alive]);
+    return true;
+  }
+
+  /** Release the HMR or story-registry subscription. Safe to call repeatedly. */
+  disposeReactRootAdapter(): void {
+    this.disposeReloadSignal();
+  }
+
+  private componentName(n: OidNode): string | null {
+    const entry = this.oidIndex.get(n.oid);
+    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-volter-name` merely to produce a legible hierarchy.
+    const editorLabel = normalizeElementText(n.el.getAttribute('data-volter-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}`;
+    // Use the first CSS class to distinguish anonymous elements sharing a tag.
+    const firstClass = (n.el.getAttribute('class') ?? '').split(/\s+/).filter(Boolean)[0];
+    if (firstClass) return `${n.tag}.${firstClass}`;
+    return n.tag;
+  }
+
+  private toEditorNode(n: OidNode, tree: OidTree): 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, so a component name is not 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 crossSurfaceId = n.el.getAttribute('data-volter-hierarchy-id');
+    const crossSurfaceParentId = n.el.getAttribute('data-volter-hierarchy-parent-id');
+    const crossSurfaceOrderAttribute = n.el.getAttribute('data-volter-hierarchy-order');
+    const crossSurfaceGroupLabel = n.el.getAttribute('data-volter-hierarchy-group-label');
+    const crossSurfaceOrder =
+      crossSurfaceOrderAttribute === null ? undefined : Number(crossSurfaceOrderAttribute);
+    const node: EditorNode = {
+      id: n.id,
+      label: isComponentBoundary ? component : this.elementLabel(n, tree),
+      ...(isComponentBoundary ? { secondaryLabel: `<${n.tag}>` } : {}),
+      role: isComponentBoundary ? 'component' : 'element',
+      kind: n.tag,
+      parentId: n.parentId,
+      childIds: n.childIds,
+      ...(crossSurfaceId === null ? {} : { crossSurfaceId }),
+      ...(crossSurfaceParentId === null ? {} : { crossSurfaceParentId }),
+      ...(crossSurfaceOrder === undefined || !Number.isInteger(crossSurfaceOrder)
+        ? {}
+        : { crossSurfaceOrder }),
+      ...(crossSurfaceGroupLabel === null ? {} : { crossSurfaceGroupLabel }),
+    };
+    if (this.portableStories.length > 0 && node.parentId === null) {
+      return { ...node, parentId: this.activeStoryId };
+    }
+    return node;
+  }
+
+  /** Exact DOM-native input signature for the composite's semantic join.
+   * Shell notifications unrelated to this root leave it unchanged. The
+   * nearest semantic ancestor and traversal order are included because
+   * transparent DOM wrappers fold between explicitly identified rows. */
+  private crossSurfaceStructureSignature(): string | null {
+    const tree = this.hierarchySnapshot();
+    const semanticIds = new Set<string>();
+    for (const node of tree.nodes.values()) {
+      if (
+        node.el.getAttribute('data-volter-hierarchy-id') !== null ||
+        node.el.getAttribute('data-volter-hierarchy-parent-id') !== null ||
+        node.el.getAttribute('data-volter-hierarchy-order') !== null ||
+        node.el.getAttribute('data-volter-hierarchy-group-label') !== null
+      ) {
+        semanticIds.add(node.id);
+      }
+    }
+    if (semanticIds.size === 0) return null;
+    return JSON.stringify(
+      [...tree.nodes.values()].flatMap((node) => {
+        if (!semanticIds.has(node.id)) return [];
+        let parentId = node.parentId;
+        while (parentId !== null && !semanticIds.has(parentId)) {
+          parentId = tree.nodes.get(parentId)?.parentId ?? null;
+        }
+        return [
+          [
+            node.id,
+            parentId,
+            node.el.getAttribute('data-volter-hierarchy-id'),
+            node.el.getAttribute('data-volter-hierarchy-parent-id'),
+            node.el.getAttribute('data-volter-hierarchy-order'),
+            node.el.getAttribute('data-volter-hierarchy-group-label'),
+          ],
+        ];
+      }),
+    );
+  }
+
+  private portableHierarchyNode(id: string) {
+    return this.portableHierarchy?.nodes.find((node) => node.id === id) ?? null;
+  }
+
+  private portableStoriesForNode(nodeId: string): StoryRef[] {
+    // Story application remounts the whole root; the world scope lists all stories.
+    if (nodeId === WORLD_SCOPE_NODE_ID) return [...this.portableStories];
+    const hierarchy = this.portableHierarchy!;
+    const hierarchyNode = this.portableHierarchyNode(nodeId);
+    if (hierarchyNode && hierarchyNode.role !== 'component') return [];
+    const componentId =
+      hierarchyNode?.role === 'component'
+        ? hierarchyNode.id
+        : (hierarchy.storyParentIds.get(nodeId) ??
+          hierarchy.storyParentIds.get(this.activeStoryId ?? ''));
+    if (!componentId) return [];
+    const component = this.portableHierarchyNode(componentId);
+    const storyIds = new Set(component?.childIds ?? []);
+    return this.portableStories.filter((story) => storyIds.has(story.id));
+  }
+
+  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.portableHierarchy!.storyParentIds.get(story.id) ?? null,
+      childIds: active ? rootIds : [],
+    };
+  }
+
+  readonly hierarchy: HierarchyProvider = {
+    crossSurfaceStructureSignature: () => this.crossSurfaceStructureSignature(),
+    roots: () => {
+      const tree = this.hierarchySnapshot();
+      const { nodes, rootIds } = tree;
+      if (this.portableStories.length > 0) {
+        return this.portableHierarchy!.rootIds.flatMap((id) => {
+          const node = this.portableHierarchy!.nodes.find((candidate) => candidate.id === id);
+          return node ? [{ ...node, childIds: [...node.childIds] }] : [];
+        });
+      }
+      return rootIds.map((id) => this.toEditorNode(nodes.get(id)!, tree));
+    },
+    node: (id) => {
+      if (this.portableStories.length > 0) {
+        const hierarchyNode = this.portableHierarchy?.nodes.find(
+          (candidate) => candidate.id === id,
+        );
+        if (hierarchyNode) return { ...hierarchyNode, childIds: [...hierarchyNode.childIds] };
+        const story = this.portableStories.find((candidate) => candidate.id === id);
+        if (story) return this.portableStoryNode(story, this.hierarchySnapshot().rootIds);
+      }
+      const tree = this.hierarchySnapshot();
+      const n = tree.nodes.get(id);
+      return n ? this.toEditorNode(n, tree) : null;
+    },
+    // No `nativeObject`/`idForNativeObject`: react entities are DOM, not Object3D —
+    // the concept does not apply here (no 3D gizmo binding).
+  };
+
+  readonly selection: SelectionProvider = {
+    get: () => {
+      const ids = [...this.store.selectedEntityIds];
+      // Remember the last NON-EMPTY selection so a re-projection that drops it
+      // can be repaired — see `repairSelectionAfterReprojection`. Recorded on
+      // the read because that is the one call every projection of the
+      // selection already makes; the adapter has no store subscription of its
+      // own and adding one to observe a value it is handed anyway would be a
+      // second source of the same fact.
+      if (ids.length > 0) this.lastResolvedSelection = ids;
+      return ids;
+    },
+    set: (ids) => this.store.selectMultiple(ids),
+    resolve: (rawId, options) => {
+      const raw = this.hierarchy.node(rawId);
+      if (!raw) return null;
+
+      const innerToOuter: EditorNode[] = [];
+      let cursor: EditorNode | null = raw;
+      let guard = 0;
+      while (cursor && guard++ < 1000) {
+        if (
+          cursor.role === 'component' ||
+          cursor.role === 'instance' ||
+          cursor.role === 'boundary'
+        ) {
+          innerToOuter.push(cursor);
+        }
+        cursor = cursor.parentId ? this.hierarchy.node(cursor.parentId) : null;
+      }
+      const chain = innerToOuter.reverse();
+      if (chain.length === 0) {
+        return { id: rawId };
+      }
+
+      const scopeIndex = options?.scopeId
+        ? chain.findIndex((candidate) => candidate.id === options.scopeId)
+        : -1;
+      let resolvedIndex = scopeIndex >= 0 ? scopeIndex + 1 : 0;
+      if (options?.intent === 'deep') resolvedIndex += 1;
+
+      // Unlike the R3F projection, React keeps authored host elements in the
+      // hierarchy. Once every component boundary on the route is open, the
+      // exact DOM element becomes the honest selection subject.
+      const subject = chain[resolvedIndex] ?? raw;
+      return { id: subject.id };
+    },
+  };
+
+  readonly truth: TruthProvider = {
+    resolve: (id): { site: NodeCreationSite; writeAnchorKind: WriteAnchorKind | undefined } => {
+      const node = this.snapshot().nodes.get(id);
+      if (!node) {
+        return {
+          site: { anchored: false, reason: 'This row is a design document, not a JSX element.' },
+          writeAnchorKind: undefined,
+        };
+      }
+      const entry = this.oidIndex.get(node.oid);
+      const writeAnchorKind = this.writeBackend ? 'source-prop' : 'live-only';
+      if (!entry) {
+        return {
+          site: { anchored: false, reason: 'Source metadata is still loading or unavailable.' },
+          writeAnchorKind,
+        };
+      }
+      const file = projectSourcePath(entry.file);
+      return {
+        site: {
+          anchored: true,
+          kind: 'source',
+          file,
+          line: entry.line,
+          col: entry.col,
+          display: `${file}:${entry.line}`,
+        },
+        writeAnchorKind,
+      };
+    },
+  };
+
+  readonly related: RelatedSubjectsProvider = {
+    links: (id) => {
+      const node = this.hierarchy.node(id);
+      if (node?.role !== 'component' || this.stories.storiesFor(id).length === 0) return [];
+      return [
+        {
+          // `definition:` marks this as the subject's OPEN-FOR-EDIT target (the
+          // component's own UI Components document), so the inspector surfaces it
+          // as the labeled Edit button by kind, never by list position.
+          id: `definition:${UI_COMPONENTS_DOCUMENT_ID}`,
+          title: 'Open in UI Components',
+          open: () => {
+            void activateWorkspaceDocument(UI_COMPONENTS_DOCUMENT_ID);
+          },
+        },
+      ];
+    },
+  };
+
+  private instanceSource(id: string): {
+    node: OidNode;
+    callSiteOid: string;
+    callSite: OidEntry;
+    props: Record<string, string>;
+  } | null {
+    const node = this.snapshot().nodes.get(id);
+    if (!node || this.hierarchy.node(id)?.role !== 'component') return null;
+    const component = getComponentProps(node.el);
+    if (!component) return null;
+    const callSite = this.oidIndex.get(component.callSiteOid);
+    if (!callSite || !/^[A-Z]/.test(callSite.tag)) return null;
+    return {
+      node,
+      callSiteOid: component.callSiteOid,
+      callSite,
+      props: component.props,
+    };
+  }
+
+  private instanceProp(
+    id: string,
+    path: string,
+  ): {
+    source: NonNullable<ReturnType<ReactRootAuthoringAdapter['instanceSource']>>;
+    prop: string;
+    spec: ComponentPropSpec;
+    authored: NonNullable<OidEntry['authoredProps']>[number];
+  } | null {
+    if (!path.startsWith(PROP_PATH_PREFIX)) return null;
+    const source = this.instanceSource(id);
+    if (!source) return null;
+    const prop = path.slice(PROP_PATH_PREFIX.length);
+    const spec = source.callSite.props?.find((candidate) => candidate.name === prop);
+    const authored = source.callSite.authoredProps?.find((candidate) => candidate.name === prop);
+    return spec && authored ? { source, prop, spec, authored } : null;
+  }
+
+  private affectedInstances(id: string, prop: string): number {
+    const selected = this.instanceSource(id);
+    if (!selected) return 0;
+    let count = 0;
+    for (const candidate of this.snapshot().nodes.values()) {
+      const component = getComponentProps(candidate.el);
+      if (!component) continue;
+      const entry = this.oidIndex.get(component.callSiteOid);
+      if (!entry || entry.tag !== selected.callSite.tag) continue;
+      if (candidate.id === id || !entry.authoredProps?.some((item) => item.name === prop)) count++;
+    }
+    return Math.max(1, count);
+  }
+
+  readonly instances: ComponentInstancesProvider = {
+    openComponent: () => {
+      void activateWorkspaceDocument(UI_COMPONENTS_DOCUMENT_ID);
+    },
+    describe: (id) => {
+      const source = this.instanceSource(id);
+      if (!source || this.stories.storiesFor(id).length === 0) return null;
+      const overrides = Object.entries(source.props).flatMap(([prop, value]) => {
+        const path = `${PROP_PATH_PREFIX}${prop}`;
+        const detail = this.instanceProp(id, path);
+        if (!detail) return [];
+        const canApplyToComponent =
+          detail.authored.literal &&
+          detail.spec.defaultValue !== undefined &&
+          source.node.oid !== source.callSiteOid &&
+          !!this.writeBackend?.runGesture &&
+          !!this.writeBackend.writeComponentDefault;
+        return [
+          {
+            path,
+            label: prop,
+            value,
+            ...(detail.spec.defaultText === undefined
+              ? {}
+              : { defaultText: detail.spec.defaultText }),
+            canApplyToComponent,
+            affectedInstanceCount: this.affectedInstances(id, prop),
+            ...(canApplyToComponent
+              ? {}
+              : {
+                  applyUnavailableReason: !detail.authored.literal
+                    ? 'The callsite value is a dynamic expression, so it cannot become a component literal.'
+                    : detail.spec.defaultValue === undefined
+                      ? 'The component default is computed or absent, so source cannot be changed safely.'
+                      : 'This session cannot atomically update the component and its callsite.',
+                }),
+          },
+        ];
+      });
+      return {
+        componentName: source.callSite.tag,
+        sourcePath: projectSourcePath(source.callSite.file),
+        overrides,
+      };
+    },
+    revert: async (id, paths) => {
+      const source = this.instanceSource(id);
+      const backend = this.writeBackend;
+      if (!source || !backend) return;
+      const props = paths
+        .map((path) => this.instanceProp(id, path)?.prop)
+        .filter((prop): prop is string => !!prop);
+      let changed = false;
+      const remove = async (selected: SourceWriteBackend): Promise<void> => {
+        for (const prop of props) {
+          const result = await selected.removeProp(source.callSiteOid, prop);
+          changed ||= result.changed;
+        }
+      };
+      if (props.length > 1 && backend.runGesture) {
+        await backend.runGesture(`Revert ${props.length} Overrides`, remove);
+      } else {
+        await remove(backend);
+      }
+      if (!changed) return;
+      this.dirty = true;
+      this.pendingSourceReconcile++;
+      await this.refreshOidIndex();
+      return { destination: JSX_SOURCE_DESTINATION, persisted: true };
+    },
+    applyToComponent: async (id, path): Promise<ComponentInstanceApplyResult> => {
+      const detail = this.instanceProp(id, path);
+      const backend = this.writeBackend;
+      if (
+        !detail ||
+        !detail.authored.literal ||
+        detail.spec.defaultValue === undefined ||
+        detail.source.node.oid === detail.source.callSiteOid ||
+        !backend?.runGesture ||
+        !backend.writeComponentDefault
+      ) {
+        return {
+          changed: false,
+          message: 'Apply was refused because both literal source writes are not available.',
+        };
+      }
+      const value = detail.source.props[detail.prop];
+      await backend.runGesture(
+        `Apply ${detail.prop} to ${detail.source.callSite.tag}`,
+        async (scoped) => {
+          const applied = await scoped.writeComponentDefault?.(
+            detail.source.node.oid,
+            detail.prop,
+            serializedComponentValue(value, detail.spec),
+          );
+          if (!applied?.changed) {
+            throw new Error(applied?.error ?? 'The component default did not change.');
+          }
+          const reverted = await scoped.removeProp(detail.source.callSiteOid, detail.prop);
+          if (!reverted.changed) {
+            throw new Error(reverted.error ?? 'The callsite override was not removed.');
+          }
+        },
+      );
+      this.dirty = true;
+      this.pendingSourceReconcile++;
+      await this.refreshOidIndex();
+      return {
+        changed: true,
+        message: `${detail.prop} now defaults to ${String(value)} in ${detail.source.callSite.tag}.`,
+        write: { destination: JSX_SOURCE_DESTINATION, persisted: true },
+      };
+    },
+  };
+
+  /** Pick the smallest unlocked OID element containing the point, breaking
+   * ties by later tree order. Ignore inline pointer-events:none; the host
+   * wrapper's computed pointer policy does not hide authorable descendants. */
+  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++;
+        // Locked nodes do not compete for canvas selection.
+        if (this.lockedIds.has(node.id)) continue;
+        if (styleProp(node.el.style, 'pointerEvents') === 'none') continue;
+        const rect = node.el.getBoundingClientRect();
+        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;
+    },
+  };
+
+  /** Mounted layer origin used to express overlay rectangles in host coordinates. */
+  private hostRect(): { left: number; top: number } {
+    const r = this.root.getBoundingClientRect();
+    return { left: r.left, top: r.top };
+  }
+
+  private toHostRelative(r: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  }): DOMRectLike {
+    const host = this.hostRect();
+    const zoom = getRootPan().zoom;
+    return {
+      x: (r.left - host.left) / zoom,
+      y: (r.top - host.top) / zoom,
+      width: r.width / zoom,
+      height: r.height / zoom,
+    };
+  }
+
+  /** Host-relative node geometry for overlays, snapping, and marquee selection. */
+  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 styles the inspector uses; absent/unparsable
+      // border widths degrade to 0 (padding box === border box), never thrown.
+      const el = n.el;
+      const rect = el.getBoundingClientRect();
+      const bt =
+        numericStyleValue(getComputedStyleValue(el, 'borderTopWidth')) ?? 0;
+      const br =
+        numericStyleValue(getComputedStyleValue(el, 'borderRightWidth')) ?? 0;
+      const bb =
+        numericStyleValue(getComputedStyleValue(el, 'borderBottomWidth')) ??
+        0;
+      const bl =
+        numericStyleValue(getComputedStyleValue(el, 'borderLeftWidth')) ?? 0;
+      const 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),
+      });
+      // Persistent board guides (board-guides.ts), converted from client
+      // space into the same host-relative units as every rect above.
+      const guideClients = editorHost().documents.boardGuideEdges();
+      const host = this.hostRect();
+      const zoom = getRootPan().zoom;
+      const guideEdges =
+        guideClients.x.length > 0 || guideClients.y.length > 0
+          ? {
+              x: guideClients.x.map((cx) => (cx - host.left) / zoom),
+              y: guideClients.y.map((cy) => (cy - host.top) / zoom),
+            }
+          : undefined;
+      return {
+        ...(parentRect ? { parent: this.toHostRelative(parentRect) } : {}),
+        ...(siblings.length ? { siblings } : {}),
+        paddingBox,
+        ...(guideEdges ? { guideEdges } : {}),
+      };
+    },
+    // Empty containers have no visible element children or non-whitespace text.
+    emptyContainers: () => {
+      const { nodes } = this.snapshot();
+      const candidates: EmptyCandidate[] = [];
+      for (const n of nodes.values()) {
+        const r = n.el.getBoundingClientRect();
+        if (!canContainDomChildren(n.el, n.tag)) 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,
+      }));
+    },
+  };
+
+  /** Sample the topmost eligible node's computed color at the pointer. */
+  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'));
+        cur = cur.parentId ? nodes.get(cur.parentId) : undefined;
+      }
+      return chain;
+    },
+  };
+
+  /** Preview box gestures on live DOM, then persist touched properties at end. */
+  readonly boxEdit: BoxEditProvider = {
+    begin: (id) => {
+      // Starting a gesture replaces any uncommitted session; 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');
+      const isPositioned = pos === 'absolute' || pos === 'fixed';
+      for (const [key, v] of Object.entries(patch)) {
+        const mapped = mapBoxEditPatchKey(key, isPositioned);
+        if (!mapped) {
+          console.warn(
+            `[ReactRootAuthoringAdapter] 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'),
+          );
+          // Explain why a flow-positioned element cannot accept a spatial move.
+          if ((key === 'x' || key === 'y') && !session.hinted) {
+            session.hinted = true;
+            showTransientHint(
+              `${n.tag} flows in its layout (position: ${pos}), so a drag ` +
+                'cannot move it. Set Position to "abs" in the Inspector to place it freely; ' +
+                'drag a handle to resize.',
+            );
+          }
+          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);
+        }
+        // x/y arrive HOST-RELATIVE (the rect provider's space), but CSS
+        // left/top are OFFSET-PARENT-relative. They only coincide when the
+        // offset parent sits at the host origin — which a story-frame child
+        // never does, so writing them as-is would put BOARD coordinates into
+        // the element's source and move it outside its own frame.
+        // parentOrigin = rect − offsetLeft is constant through the gesture
+        // (both shift together as we mutate), and an element positioned via
+        // translate() cancels exactly: rect includes the transform, so the
+        // written left lands the VISUAL box at the requested position.
+        let write = v;
+        if ((key === 'x' || key === 'y') && typeof v === 'number') {
+          const el = n.el as unknown as {
+            getBoundingClientRect: () => {
+              left: number;
+              top: number;
+              width: number;
+              height: number;
+            };
+            offsetLeft?: number;
+            offsetTop?: number;
+          };
+          const rect = el.getBoundingClientRect();
+          if (typeof el.offsetLeft === 'number' && typeof el.offsetTop === 'number') {
+            const hostRel = this.toHostRelative(rect);
+            const parentOrigin = key === 'x' ? hostRel.x - el.offsetLeft : hostRel.y - el.offsetTop;
+            // Whole-pixel, like every other gesture write (see the spacing
+            // scrub's own doc comment): the patch is grid/edge-snapped, but
+            // edge targets and this origin are MEASURED (rect ÷ zoom), so
+            // without rounding a 65%-zoom drag authors `left:
+            // '215.00005607057415px'` — measurement noise, not intent.
+            write = Math.round(v - parentOrigin);
+          }
+        }
+        const cssValue = mapped.cssValue(write);
+        (n.el.style as unknown 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 : write);
+      }
+    },
+    end: (id) => {
+      const session = this.boxEditSession;
+      this.boxEditSession = null;
+      if (!session || session.id !== id || session.touched.size === 0) return;
+      // 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('[ReactRootAuthoringAdapter] box edit failed and was not committed.', error);
+      });
+    },
+  };
+
+  /** Commit touched properties as one gesture with one source-history transaction. */
+  private async commitBoxEdit(
+    id: string,
+    touched: Map<string, string | number>,
+    priorInline: Map<string, string>,
+  ): Promise<void> {
+    const wasDirty = this.dirty;
+    // Echo all touched values before awaiting source writes.
+    for (const [prop, value] of touched) {
+      this.setEcho(id, `${STYLE_PATH_PREFIX}${prop}`, value);
+    }
+    // Surface a refused gesture in the editor console and near the pointer.
+    let applied = 0;
+    this.lastStyleWriteRefusal = null;
+    const commit = async (backend: SourceWriteBackend | undefined): Promise<void> => {
+      for (const [prop, value] of touched) {
+        // Persist numeric length values as CSS lengths; transform values remain strings.
+        const writeValue = typeof value === 'number' ? `${value}px` : value;
+        if (await this.writeStyleEntry(id, prop, writeValue, priorInline.get(prop), backend)) {
+          applied += 1;
+        }
+      }
+      if (applied === 0 && touched.size > 0) {
+        const reason = this.lastStyleWriteRefusal ?? 'the write was refused without a reason';
+        editorConsole.error(`The last edit on this element was NOT saved — ${reason}`, 'authoring');
+        showTransientHint('Not saved: the edit could not be written to source — see the Console.');
+      }
+    };
+    // 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) (node.el.style as unknown as Record<string, unknown>)[prop] = prior;
+      }
+      this.dirty = wasDirty;
+      this.store.notifyIngestEdit();
+      throw error;
+    }
+  }
+
+  /** Read leaf text from DOM and write through the source-side dynamic-body guard. */
+  readonly text: TextProvider = {
+    get: (id) => {
+      // Do not reopen text editing for a body already refused by the source guard.
+      if (this.guardedPaths.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[] => {
+      const portableHierarchyNode = this.portableHierarchyNode(id);
+      if (portableHierarchyNode) {
+        return portableHierarchyNode.secondaryLabel
+          ? [
+              {
+                path: 'document.path',
+                label: 'Source',
+                type: 'string',
+                readonly: true,
+                group: 'Document',
+              },
+            ]
+          : [];
+      }
+      if (this.portableStories.some((story) => story.id === id))
+        return this.portableStoryArgDescriptors(id);
+      const style = STYLE_PROPERTIES.map(({ prop, label, type, group, options }) => ({
+        path: `${STYLE_PATH_PREFIX}${prop}`,
+        label,
+        type,
+        group,
+        ...(options ? { options } : {}),
+      }));
+      // Append component props from the selected node's source contract.
+      const all = [...style, ...this.propDescriptors(id), ...this.tokenDescriptors()];
+      // Return remembered source guards as read-only descriptors with their own reason.
+      if (this.guardedPaths.size === 0) return all;
+      return all.map((p) => {
+        const reason = this.guardedPaths.get(`${id}|${p.path}`);
+        return reason ? { ...p, readonly: true, readonlyReason: reason } : p;
+      });
+    },
+    get: (id, path) => {
+      const portableHierarchyNode = this.portableHierarchyNode(id);
+      if (portableHierarchyNode) {
+        return path === 'document.path' ? portableHierarchyNode.secondaryLabel : 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;
+      }
+      // A freshly committed echo takes precedence over the live DOM value.
+      const echoed = this.readEcho(id, path);
+      if (echoed.hit) return echoed.value;
+      // Lock state is session-local; visibility reads its source-backed style echo.
+      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');
+        return raw !== 'hidden';
+      }
+      if (path.startsWith(TOKEN_PATH_PREFIX)) {
+        const name = path.slice(TOKEN_PATH_PREFIX.length);
+        return this.designTokenValue(name);
+      }
+      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;
+      // Prefer authored inline values; computed style resolves class and stylesheet values.
+      const authored = styleProp(n.el.style, prop);
+      const raw = authored || getComputedStyleValue(n.el, prop);
+      const declaredType = STYLE_PROPERTY_TYPE.get(prop);
+      // Convert CSSStyleDeclaration's unit-suffixed strings to numbers for numeric inspector
+      // descriptors, and normalize color descriptors to #rrggbb through cssColorToHex.
+      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.portableHierarchyNode(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;
+      }
+      // Apply session lock and source-backed visibility changes through their own paths.
+      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);
+        return this.pipedSourceWrite(() => this.writeStyle(id, 'visibility', cssValue));
+      }
+      if (path.startsWith(PROP_PATH_PREFIX)) {
+        // Echo before awaiting the source write.
+        this.setEcho(id, path, value);
+        return this.pipedSourceWrite(() =>
+          this.writePropEdit(id, path.slice(PROP_PATH_PREFIX.length), String(value)),
+        );
+      }
+      if (path.startsWith(TOKEN_PATH_PREFIX)) {
+        // Tokens-as-noun: a token declared by a project stylesheet is EDITED
+        // AT ITS DECLARATION (`writeCss` on the traced rule) — the one write
+        // that moves every binding at once. Undeclared tokens (script-set)
+        // refuse with the pointer; their descriptor is read-only anyway.
+        this.setEcho(id, path, value);
+        return this.pipedSourceWrite(() =>
+          this.writeTokenValue(id, path.slice(TOKEN_PATH_PREFIX.length), String(value)),
+        );
+      }
+      if (!path.startsWith(STYLE_PATH_PREFIX)) return;
+      const prop = path.slice(STYLE_PATH_PREFIX.length);
+      // Echo BEFORE the async write: 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);
+      return this.pipedSourceWrite(() => this.writeStyle(id, prop, value as string | number));
+    },
+    remove: (id, path) => {
+      // Remove longhand overrides so a uniform shorthand controls the rendered value.
+      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);
+      // Through the SAME pipe `set` uses, so a removal answers for itself with
+      // an awaited per-edit ack instead of being fired into the void. It is the
+      // only door that can express byte-ABSENCE — `set` writes a value, and a
+      // longhand set back to the shorthand's value is still a longhand in the
+      // file.
+      return this.pipedSourceWrite(() => this.removeStyleProp(id, prop));
+    },
+  };
+
+  /** 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. Per-story documents share the rule in
+   * ../host/stories/story-arg-descriptors.ts. */
+  private portableStoryArgDescriptors(storyId: string): PropertyDescriptor[] {
+    return storyArgPropertyDescriptors(
+      this.portableStoryArgs.get(storyId) ?? {},
+      PORTABLE_STORY_ARG_PATH_PREFIX,
+    );
+  }
+
+  /** 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;
+  }
+
+  /** Classes on the element, their scope-local use counts, and any matching
+   * first-party rule that makes the class an editable named style. */
+  elementClasses(id: string): { name: string; count: number; styledIn: string | null }[] {
+    const n = this.snapshot().nodes.get(id);
+    const el = n?.el as unknown as Element | undefined;
+    if (!el) return [];
+    const tokens = (el.getAttribute('class') ?? '').split(/\s+/).filter(Boolean);
+    // Count class uses inside the element's mounted CSS scope, or its document.
+    const scope = el.closest('[data-volter-mount-styles]') ?? el.ownerDocument;
+    return tokens.map((name) => {
+      const count = scope.querySelectorAll(`.${CSS.escape(name)}`).length;
+      return { name, count, styledIn: findClassRuleSource(name)?.sourceFile ?? null };
+    });
+  }
+
+  /**
+   * The named-style write: APPLY when any first-party stylesheet already
+   * declares `.className` (the class is an existing style — adding the token
+   * is the whole gesture), else CREATE — mint the rule in the element's own
+   * stylesheet (the last matched first-party rule's file, else the first
+   * first-party stylesheet in the document), moving the element's literal
+   * inline declarations into it. `remove` strips the token. Refusals are
+   * returned AND logged, so the calling UI can show the sentence.
+   */
+  async writeNamedStyle(
+    id: string,
+    op: { kind: 'set' | 'remove'; className: string },
+  ): Promise<{ changed: boolean; created?: boolean; error?: string }> {
+    const n = this.snapshot().nodes.get(id);
+    if (!n) return { changed: false, error: `"${id}" no longer resolves in this root` };
+    const refuse = (error: string): { changed: false; error: string } => {
+      console.warn(`[ReactRootAuthoringAdapter] named-style ${op.kind} refused: ${error}`);
+      return { changed: false, error };
+    };
+    if (op.kind === 'remove') {
+      const res = await writeNamedStyle({ op: 'remove', oid: n.oid, className: op.className });
+      if (!res.changed) return refuse(res.error ?? 'no change');
+      this.dirty = true;
+      this.store.notifyIngestEdit();
+      return { changed: true };
+    }
+    const existing = findClassRuleSource(op.className);
+    if (existing) {
+      const res = await writeNamedStyle({ op: 'apply', oid: n.oid, className: op.className });
+      if (!res.changed) return refuse(res.error ?? 'the element already wears this class');
+      this.dirty = true;
+      this.store.notifyIngestEdit();
+      return { changed: true };
+    }
+    // The rule's home: the last matched first-party rule's own file, else any
+    // first-party stylesheet in the document — and with NEITHER, omit `file`
+    // and the server MINTS a stylesheet beside the element's module (adding
+    // the bare css import), so the first named style in a css-less project
+    // works instead of refusing.
+    // Candidate homes are the GAME's stylesheets. The dev-id enumeration also
+    // sees the editor's own vite-served CSS, and offering one of those as the
+    // home would (rightly) bounce off the server's scope guard — so mirror the
+    // guard's exclusions here and let a css-less project fall through to the
+    // server's minting path instead.
+    const gameCss = (f: string | undefined): boolean =>
+      f !== undefined &&
+      !f.includes('/packages/editor-ui/') &&
+      !f.includes('/node_modules/') &&
+      !f.includes('/vendor/');
+    const matched = this.matchedCssRules(n.el).filter((rule) => gameCss(rule.sourceFile));
+    const cssFile =
+      matched[matched.length - 1]?.sourceFile ?? firstPartyStylesheetFiles().find(gameCss);
+    const res = await writeNamedStyle({
+      op: 'create',
+      oid: n.oid,
+      className: op.className,
+      ...(cssFile !== undefined ? { file: cssFile } : {}),
+    });
+    if (!res.changed) return refuse(res.error ?? 'no change');
+    this.dirty = true;
+    this.store.notifyIngestEdit();
+    return { changed: true, created: true };
+  }
+
+  async writeStory(
+    storyId: string,
+    op:
+      | { kind: 'save-as'; name: string }
+      | { kind: 'rename'; newName: string }
+      | { kind: 'delete' },
+  ): Promise<{ changed: boolean; error?: string }> {
+    const story = this.portableStories.find((candidate) => candidate.id === storyId);
+    if (!story) return { changed: false, error: `unknown portable story '${storyId}'` };
+    const request =
+      op.kind === 'save-as'
+        ? {
+            op: 'save' as const,
+            file: story.modulePath,
+            name: op.name,
+            args: this.portableStoryArgs.get(storyId) ?? {},
+          }
+        : op.kind === 'rename'
+          ? { op: 'rename' as const, file: story.modulePath, name: story.name, newName: op.newName }
+          : { op: 'delete' as const, file: story.modulePath, name: story.name };
+    const result = await writeCsfStory(request);
+    if (!result.changed) {
+      console.warn(
+        `[ReactRootAuthoringAdapter] csf-story ${op.kind} refused for '${story.label}': ` +
+          `${result.error ?? 'no change'}`,
+      );
+      return { changed: false, ...(result.error !== undefined ? { error: result.error } : {}) };
+    }
+    // Update renamed and deleted entries immediately; save-as becomes visible
+    // when story discovery refreshes.
+    if (op.kind === 'rename') {
+      story.name = op.newName;
+      story.label = op.newName.replace(/([a-z])([A-Z])/g, '$1 $2');
+    } else if (op.kind === 'delete') {
+      const index = this.portableStories.indexOf(story);
+      if (index >= 0) this.portableStories.splice(index, 1);
+      if (this.activeStoryId === storyId) this.activeStoryId = null;
+    }
+    this.dirty = true;
+    this.store.notifyIngestEdit();
+    return { changed: true };
+  }
+
+  /** 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();
+  }
+
+  /** Editable component props read from the mounted React 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',
+    }));
+  }
+
+  /** Design-token descriptors. A traced project declaration is writable. */
+  private tokenDescriptors(): PropertyDescriptor[] {
+    // Tokens-as-noun: a token whose `:root` declaration traces to a project
+    // stylesheet is WRITABLE (the edit lands on that declaration through the
+    // css door and every binding moves at once); one set by script — a theme
+    // data module mirroring itself onto `:root`, or inherited host style —
+    // stays read-only, because its truth lives in that source, not in a rule
+    // the css writer can reach.
+    return this.designTokens().map((t) => ({
+      path: `${TOKEN_PATH_PREFIX}${t.name}`,
+      label: t.name,
+      type: 'string' as const,
+      group: 'Tokens',
+      readonly: !t.declaredIn,
+    }));
+  }
+
+  /**
+   * The token-edit write: `writeCss` on the token's TRACED `:root`
+   * declaration. Refusals are loud and name the remedy — an untraced token's
+   * edit door is its declaring source (plain data), not this path.
+   */
+  private async writeTokenValue(id: string, name: string, value: string): Promise<boolean> {
+    const echoPath = `${TOKEN_PATH_PREFIX}${name}`;
+    const token = this.designTokens().find((t) => t.name === name);
+    if (!token) {
+      this.clearEcho(id, echoPath);
+      console.warn(`[ReactRootAuthoringAdapter] unknown design token "${name}".`);
+      return false;
+    }
+    if (!token.declaredIn) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactRootAuthoringAdapter] token "${name}" has no stylesheet declaration to edit — ` +
+          'it is set by script (a theme data module mirroring itself onto :root, or host ' +
+          'style). Edit that source; it is plain data.',
+      );
+      return false;
+    }
+    const backend = this.writeBackend;
+    if (!backend) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactRootAuthoringAdapter] cannot write token "${name}": no ` +
+          'source-write backend in this session.',
+      );
+      return false;
+    }
+    const res = await backend.writeCss(
+      token.declaredIn.sourceFile,
+      token.declaredIn.selector,
+      name,
+      value,
+    );
+    if (!res.changed) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactRootAuthoringAdapter] token write refused/no-op for "${name}" at ` +
+          `${token.declaredIn.sourceFile} (${token.declaredIn.selector}): ${res.error ?? 'no change'}`,
+      );
+      return false;
+    }
+    this.dirty = true;
+    this.store.notifyIngestEdit();
+    return true;
+  }
+
+  /**
+   * Portable Storybook CSF stories. `active`/`apply` are world-level because
+   * applying a story remounts the whole React root. `storiesFor` narrows
+   * presentation to the stories of the node's own component
+   * (`portableStoriesForNode`) — but the world question, `WORLD_SCOPE_NODE_ID`,
+   * is still answered with the whole list, because that is the id the shell
+   * probes this provider's SCOPE with and the scope is world-level.
+   * `apply` validates the id, updates `activeStoryId`, asks the design-time
+   * layer to render that composed CSF story, and notifies the shell.
+   */
+  readonly stories: StoriesProvider = {
+    storiesFor: (nodeId): StoryRef[] =>
+      this.portableStories.length > 0 ? this.portableStoriesForNode(nodeId) : [],
+    active: () => this.activeStoryId,
+    apply: (_nodeId, storyId) => {
+      if (storyId !== null && !this.portableStories.some((story) => story.id === storyId)) {
+        console.warn(
+          `[ReactRootAuthoringAdapter] 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();
+    },
+    // Publish this provider's discovery state alongside its story list.
+    unavailable: () => editorHost().stories.discoveryUnavailable(),
+  };
+
+  readonly structure: StructureProvider = {
+    // 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.
+    // The new element's OID is minted by the server on the next index, so the
+    // id half is '' and the ack half is the write itself (`StructuralIdWrite`).
+    create: (kind, parentId) => ({
+      id: '',
+      ack: this.structOp(parentId ?? '', 'create', { wrapperTag: kind }),
+    }),
+    // Preserve the acknowledgement so callers can await the source write.
+    remove: (id) => this.removeElement(id),
+    // Delete the selection in one request against one source snapshot, independent of DOM order.
+    removeMany: (ids) => this.removeManyElements(ids),
+    // Serialize duplication writes so same-file edits do not read competing snapshots.
+    duplicate: (id) => ({ id, ack: this.structOp(id, 'duplicate') }),
+    reparent: (id, newParentId) => {
+      const parentOid = newParentId ? this.oidOf(newParentId) : undefined;
+      if (!parentOid) {
+        return this.structRefusal(
+          `reparent refused: "${newParentId ?? 'the document root'}" has no authored source element to move into.`,
+        );
+      }
+      return this.structOp(id, 'reparent', { parentOid });
+    },
+    // An absent before-sibling means append to the node's current parent.
+    reorder: (id, beforeSiblingId) => {
+      const parentId =
+        beforeSiblingId === null ? (this.snapshot().nodes.get(id)?.parentId ?? null) : null;
+      return this.reorder(id, beforeSiblingId, parentId);
+    },
+    // Every OID container accepts the curated HTML child kinds.
+    creatableKinds: () => [...CREATABLE_KINDS],
+    // Route wrapping through the same source-backed structure contract.
+    wrap: (id, wrapperTag) => this.wrap(id, wrapperTag),
+    unwrap: (id) => this.unwrap(id),
+  };
+
+  readonly assetDrop: AssetDropProvider = {
+    accepts: (nodeId, _assetPath, context) => this.assetDropPlan(nodeId, context).ok,
+    drop: (nodeId, _assetPath, context) => {
+      const plan = this.assetDropPlan(nodeId, context);
+      if (!plan.ok) return this.structRefusal(`asset drop refused — ${plan.reason}`);
+      return this.structOp(plan.parentId, 'create', {
+        snippet: plan.snippet,
+        ensureImport: plan.ensureImport,
+      });
+    },
+  };
+
+  private assetDropPlan(nodeId: string, context: AssetDropContext): DomAssetDropPlan {
+    if (!this.writeBackend) {
+      return { ok: false, reason: 'This session has no source writer, so nothing can be added.' };
+    }
+    const node = this.snapshot().nodes.get(nodeId);
+    if (!node) return { ok: false, reason: 'That row has no authored JSX element.' };
+    if (!canContainDomChildren(node.el, node.tag)) {
+      return { ok: false, reason: `<${node.tag}> cannot contain child elements.` };
+    }
+    const component = context.item;
+    if (component.surface !== 'dom') {
+      return {
+        ok: false,
+        reason: `${component.name} is a ${component.surface} component, not a React UI component.`,
+      };
+    }
+    const from = this.sourceLocation(nodeId)?.file;
+    if (!from) {
+      return { ok: false, reason: 'The target source location has not loaded yet.' };
+    }
+    return {
+      ok: true,
+      parentId: nodeId,
+      snippet: `<${component.name} />`,
+      ensureImport: {
+        name: component.name,
+        module: this.relativeProjectModule(from, component.sourcePath),
+        kind: component.exportKind,
+      },
+    };
+  }
+
+  private relativeProjectModule(fromFile: string, targetFile: string): string {
+    return relativeImportSpecifier(projectSourcePath(fromFile), projectSourcePath(targetFile));
+  }
+  /** Wrap the element in a new container. */
+  wrap(id: string, wrapperTag = 'div'): Promise<WriteAck> {
+    return this.structOp(id, 'wrap', { wrapperTag });
+  }
+
+  /** Replace the element with its children. */
+  unwrap(id: string): Promise<WriteAck> {
+    return this.structOp(id, 'unwrap');
+  }
+
+  /** Reorder the element before a sibling (`beforeId`), or to the end of `parentId` when
+   *  `beforeId` is null. */
+  reorder(id: string, beforeId: string | null, parentId: string | null): Promise<WriteAck> {
+    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;
+    return 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;
+  }
+
+  /** Indexed source location for an OID node, absent before the index resolves. */
+  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 persistence pipe (loud degradation without
+   *  a writer). */
+  private structOp(id: string, op: string, opts?: StructOpOptions): Promise<WriteAck> {
+    return this.structPipe.structOp(this.oidOf(id), id, op, opts, JSX_SOURCE_DESTINATION);
+  }
+
+  /** Most recent style refusal, surfaced when a gesture writes nothing. */
+  private lastStyleWriteRefusal: string | null = null;
+  private refuseStyleWrite(message: string): void {
+    this.lastStyleWriteRefusal = message;
+    console.warn(message);
+  }
+
+  private async writeStyleEntry(
+    id: string,
+    prop: string,
+    value: string | number,
+    priorInlineOverride?: string,
+    backend: SourceWriteBackend | undefined = this.writeBackend,
+  ): Promise<boolean> {
+    // Clear this write's echo on every refused or unavailable path.
+    const echoPath = `${STYLE_PATH_PREFIX}${prop}`;
+    const n = this.snapshot().nodes.get(id);
+    if (!n) {
+      this.clearEcho(id, echoPath);
+      // Report stale selection when the node disappeared before the source write.
+      this.refuseStyleWrite(
+        `[ReactRootAuthoringAdapter] cannot write "${prop}": "${id}" no longer resolves in this ` +
+          'root (the tree was re-projected — an HMR remount — between the selection and the ' +
+          'write). Nothing was written. Re-select and retry.',
+      );
+      return false;
+    }
+    if (!backend) {
+      this.clearEcho(id, echoPath);
+      this.refuseStyleWrite(
+        `[ReactRootAuthoringAdapter] cannot write "${prop}" on "${id}": no source-write ` +
+          'backend in this session (hosted/no dev server) — selection/inspection still work.',
+      );
+      return false;
+    }
+    // A per-side longhand cannot share a style object with the shorthand that
+    // owns it — React raises its own conflicting-property error and the winner
+    // becomes key-order dependent. Expand the shorthand first, so the element
+    // is authored in ONE vocabulary. A source no-op on a clean element.
+    await this.expandShorthandsFor(id, prop, backend);
+    // Route matching first-party declarations to their stylesheet.
+    const breakpoint = activeBreakpoint();
+    if (breakpoint !== null) {
+      const named = namedStyleRuleFor(this.matchedCssRules(n.el), classTokensOf(n.el));
+      if (!named) {
+        const guard =
+          'no style class carries this element — create one in the Style class row first ' +
+          '(inline styles cannot be responsive, so a breakpoint edit needs a class rule).';
+        this.clearEcho(id, echoPath);
+        this.markGuarded(id, echoPath, guard);
+        showTransientHint(guard);
+        this.store.notifyIngestEdit();
+        this.refuseStyleWrite(`[ReactRootAuthoringAdapter] breakpoint edit refused: ${guard}`);
+        return false;
+      }
+      const res = await backend.writeCss(
+        named.sourceFile,
+        named.selectorText,
+        prop,
+        cssTextForStyleValue(prop, value),
+        breakpoint,
+      );
+      if (!res.changed) {
+        this.clearEcho(id, echoPath);
+        this.refuseStyleWrite(
+          `[ReactRootAuthoringAdapter] breakpoint css write refused/no-op for ` +
+            `"${named.selectorText}" ${prop} at ${breakpoint}: ${res.error ?? 'no change'}`,
+        );
+        return false;
+      }
+      this.dirty = true;
+      this.store.notifyIngestEdit();
+      return true;
+    }
+    const matchedRules = this.matchedCssRules(n.el);
+    const cssTarget = pickCssRuleTarget(matchedRules, prop);
+    // Add undeclared properties to an existing named style unless inline CSS would shadow it.
+    const namedTarget =
+      !cssTarget && !liveInlineDeclares(n.el, prop)
+        ? namedStyleRuleFor(matchedRules, classTokensOf(n.el))
+        : null;
+    const routedRule = cssTarget ?? namedTarget;
+    if (routedRule) {
+      // A CSS FILE declaration is CSS TEXT, so a numeric value needs its unit
+      // spelled here (`300` -> `300px`) — unlike the JSX object below, where
+      // React does the px-ifying. `css-numeric-style.ts` owns that rule once.
+      const res = await backend.writeCss(
+        routedRule.sourceFile,
+        routedRule.selectorText,
+        prop,
+        cssTextForStyleValue(prop, value),
+      );
+      if (res.changed) {
+        this.dirty = true;
+        this.store.notifyIngestEdit();
+        return true;
+      }
+      if (!res.generated) {
+        this.clearEcho(id, echoPath);
+        this.refuseStyleWrite(
+          `[ReactRootAuthoringAdapter] CSS write refused/no-op for selector ` +
+            `"${routedRule.selectorText}" prop "${prop}": ${res.error ?? 'no change'}`,
+        );
+        return false;
+      }
+      // res.generated ⇒ selector is generated CSS — fall through to inline/class routing.
+    }
+    value = preserveNumericStyleUnit(value, styleProp(n.el.style, prop));
+    // NOT `String(value)`. A pixel-valued numeric descriptor must reach the writer as a
+    // NUMBER so the JSX carries a bare `300`, which React px-ifies at render;
+    // a quoted `'300'` is passed through verbatim by React
+    // and REJECTED by the CSSOM, which keeps the previous value — a source
+    // write with no rendered effect, acked `persisted: true`.
+    const res = await backend.writeStyle(n.oid, prop, value);
+    if (!res.changed) {
+      this.clearEcho(id, echoPath);
+      // Expression and token-reference refusals keep their distinct reasons.
+      const guard = res.tokenRef
+        ? tokenReferenceGuardText(prop, res.tokenRef)
+        : res.dynamic
+          ? DYNAMIC_EXPRESSION_GUARD
+          : null;
+      if (guard) this.markGuarded(id, echoPath, guard);
+      // Notify after clearing echo or marking the descriptor read-only.
+      this.store.notifyIngestEdit();
+      this.refuseStyleWrite(
+        `[ReactRootAuthoringAdapter] style write refused/no-op for oid "${n.oid}" ` +
+          `prop "${prop}": ${guard ?? res.error ?? 'no change'}`,
+      );
+      return false;
+    }
+    this.dirty = true;
+    // Apply successful inline writes immediately for inspector feedback. Box
+    // gestures already previewed their values; stylesheet writes return above
+    // so an inline patch cannot shadow their rule. Live CSS lengths need units.
+    if (priorInlineOverride === undefined) {
+      (n.el.style as unknown as Record<string, unknown>)[prop] = cssTextForStyleValue(prop, value);
+    }
+    this.store.notifyIngestEdit();
+    return true;
+  }
+
+  private async writeStyle(id: string, prop: string, value: string | number): Promise<boolean> {
+    return this.writeStyleEntry(id, prop, value);
+  }
+
+  /** Expand governing shorthands before writing a per-side property. */
+  private async expandShorthandsFor(
+    id: string,
+    prop: string,
+    backend: SourceWriteBackend | undefined,
+  ): Promise<void> {
+    const chain = shorthandChain(prop);
+    if (chain.length === 0) return;
+    const n = this.snapshot().nodes.get(id);
+    if (!n || !backend) return;
+    for (const shorthand of chain) {
+      const longhands = SHORTHAND_LONGHANDS[shorthand] ?? [];
+      // Read BEFORE the removal — the removal drops the live inline override,
+      // so a read afterwards would see the cascade without it.
+      const resolved = longhands.map((longhand) =>
+        getComputedStyleValue(n.el, longhand),
+      );
+      // The SAME backend the caller writes through — a box-edit commit hands
+      // in a scoped writer for atomicity, and an expansion that reached around
+      // it would split one gesture across two transactions.
+      if (!(await this.removeStyleProp(id, shorthand, backend))) continue; // not authored here
+      for (const [index, longhand] of longhands.entries()) {
+        if (longhand === prop) continue; // the caller writes this one itself
+        const value = resolved[index];
+        if (!value) continue;
+        await this.writeStyleEntry(id, longhand, value, undefined, backend);
+      }
+    }
+  }
+
+  /** Remove an authored style override through the source writer. */
+  private async removeStyleProp(
+    id: string,
+    prop: string,
+    backend: SourceWriteBackend | undefined = this.writeBackend,
+  ): Promise<boolean> {
+    const n = this.snapshot().nodes.get(id);
+    if (!n || !backend) return false;
+    const res = await backend.removeStyle(n.oid, prop);
+    if (!res.changed) return false; // longhand wasn't authored — nothing removed, no undo
+    this.dirty = true;
+    delete (n.el.style as unknown as Record<string, unknown>)[prop];
+    this.store.notifyIngestEdit();
+    return true;
+  }
+
+  /** Replace leaf text through the source-side expression/children guard. */
+  async editText(id: string, newText: string): Promise<void> {
+    const n = this.snapshot().nodes.get(id);
+    if (!n) return;
+    if (!this.writeBackend) {
+      console.warn(
+        `[ReactRootAuthoringAdapter] cannot edit text on "${id}": no source-write backend ` +
+          'in this session.',
+      );
+      return;
+    }
+    const res = await this.writeBackend.writeText(n.oid, newText);
+    if (!res.changed) {
+      // Remember dynamic-body refusal and notify its read-only indicator.
+      if (res.dynamic) {
+        this.markGuarded(
+          id,
+          TEXT_PATH,
+          'The body has an expression or child elements, so replacing it with text is guarded.',
+        );
+      }
+      this.store.notifyIngestEdit();
+      console.warn(
+        `[ReactRootAuthoringAdapter] 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;
+    // Reconcile text-derived layout hints after the HMR DOM update.
+    this.pendingSourceReconcile++;
+    this.store.notifyIngestEdit();
+  }
+
+  /** Write a component prop at the callsite through its source guard. */
+  private async writePropEdit(id: string, prop: string, value: string): Promise<boolean> {
+    // Clear this prop write's optimistic echo on refusal.
+    const echoPath = `${PROP_PATH_PREFIX}${prop}`;
+    const n = this.snapshot().nodes.get(id);
+    if (!n) {
+      this.clearEcho(id, echoPath);
+      return false;
+    }
+    if (!this.writeBackend) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactRootAuthoringAdapter] cannot write prop "${prop}" on "${id}": no source-write ` +
+          'backend in this session.',
+      );
+      return false;
+    }
+    const cp = getComponentProps(n.el);
+    if (!cp) {
+      this.clearEcho(id, echoPath);
+      console.warn(
+        `[ReactRootAuthoringAdapter] "${id}" is not a component call site with props — ` +
+          `cannot write prop "${prop}".`,
+      );
+      return false;
+    }
+    const res = await this.writeBackend.writeProp(cp.callSiteOid, prop, value);
+    if (!res.changed) {
+      this.clearEcho(id, echoPath);
+      if (res.dynamic) this.markGuarded(id, echoPath, DYNAMIC_EXPRESSION_GUARD);
+      // Notify the cleared echo and any newly read-only descriptor.
+      this.store.notifyIngestEdit();
+      console.warn(
+        `[ReactRootAuthoringAdapter] prop write refused/no-op for oid "${cp.callSiteOid}" ` +
+          `prop "${prop}": ${res.dynamic ? 'value is a dynamic expression (guarded)' : (res.error ?? 'no change')}`,
+      );
+      return false;
+    }
+    this.dirty = true;
+    this.store.notifyIngestEdit();
+    return true;
+  }
+
+  private removeElement(id: string): Promise<WriteAck> {
+    const n = this.snapshot().nodes.get(id);
+    if (!n) return this.structRefusal(`cannot delete "${id}": no such node in this world.`);
+    // Whole-file source history restores deletion without fabricating an inverse
+    // element insertion from an OID that no longer exists.
+    return this.structPipe.structOp(n.oid, id, 'delete', undefined, JSX_SOURCE_DESTINATION);
+  }
+
+  /** Resolve all selected OIDs and delete them against one source snapshot. */
+  private removeManyElements(ids: readonly string[]): Promise<WriteAck> {
+    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 this.structRefusal('batch delete reached no source-addressable element.');
+    }
+    // One prepared batch source write becomes one history transaction.
+    return this.structPipe.deleteMany(oids, JSX_SOURCE_DESTINATION);
+  }
+
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener);
+  }
+
+  // A class GETTER, not a field initializer: field initializers run before the
+  // constructor body assigns `this.writeBackend`.
+  get persistence(): PersistenceProvider {
+    const backend = this.writeBackend;
+    return {
+      isDirty: () => this.dirty,
+      save: async () => {
+        // Source writes persist immediately; save has no pending queue to flush.
+      },
+      destination: backend ? JSX_SOURCE_DESTINATION : NO_BACKEND_DESTINATION,
+    };
+  }
+
+  /** Value writes resolve through the shared persistence pipe. The backend
+   * owns whole-file history, so this layer records no second undo entry. */
+  private pipedSourceWrite(write: () => Promise<boolean>): Promise<WriteAck> {
+    return runWritePipe({
+      resolve: (): WriteResolution =>
+        this.writeBackend
+          ? {
+              reaches: 'writer',
+              destination: JSX_SOURCE_DESTINATION,
+              write,
+            }
+          : resolvesLiveOnly(NO_BACKEND_DESTINATION),
+      record: () => undefined,
+      // Report unavailable source writes at the pipe's resolution boundary.
+      report: (reason) =>
+        console.warn(`[ReactRootAuthoringAdapter] this edit stays live-only — ${reason}.`),
+    });
+  }
+
+  /** Structural writes use the shared pipe and queue a post-HMR notification.
+   * The backend owns their complete-file history transaction. */
+  private readonly structPipe = createStructWritePipe({
+    // biome-ignore lint/suspicious/noConsole: a refused source write must be visible
+    report: (message) => console.warn(`[ReactRootAuthoringAdapter] ${message}`),
+    noWriterReason: NO_BACKEND_DESTINATION,
+    backend: () => this.writeBackend,
+    onChanged: () => {
+      this.dirty = true;
+      this.pendingSourceReconcile++;
+      this.store.notifyIngestEdit();
+    },
+  });
+
+  /** The shared pipe's live-only floor, under this lane's own label. */
+  private structRefusal(reason: string): Promise<WriteAck> {
+    return this.structPipe.structRefusal(reason);
+  }
+}