@vgai/editor 0.2.0

package/src/authoring/react-inspector-section.tsx

@@ -0,0 +1,1041 @@
+/**
+ * React-world inspector section (C2, spec 27 §5 C2,
+ * docs/unified-world-editor/27-visual-react-editing.md) — the "wire the
+ * widgets" half of Phase C. C1 (`components/inspector-widgets/`) built a
+ * PURE widget kit with no wiring; this module is the adapter-module
+ * contribution that plugs it into the ONE inspector shell
+ * (`components/Inspector.tsx`) via `inspector-section-registry.ts`, the SAME
+ * seam `authoring/first-party-inspector/register.tsx` (threejs) and
+ * `authoring/ui-inspector-sections.tsx` (scene-UI) already use — see those
+ * two files for the sanctioned pattern this one follows.
+ *
+ * Matches any node owned by a react/DOM adapter — `ReactWorldAuthoringAdapter`
+ * (Lane B, `data-oid` component-source writes, T6.2) or
+ * `ReactDomAuthoringAdapter` (the ingested/overlay DOM adapter, wave 10) —
+ * whether the active adapter IS one of those directly (a bare single-world
+ * session) or is a `CompositeAuthoringAdapter` routing to one as `id`'s
+ * owner (multi-world edit mode). Renders every `PropertyDescriptor` the
+ * adapter's `InspectorProvider.properties(id)` reports, GROUPED by
+ * `PropertyDescriptor.group` (falling back to one flat "Style" group for an
+ * adapter, like `ReactDomAuthoringAdapter`, whose descriptors declare none),
+ * mapping each descriptor to the right C1 widget instead of a generic
+ * `<input>` — see `widgetKindFor`'s doc comment for the exact mapping table.
+ * `suppresses: ['properties']` replaces the shell's generic property grid
+ * for a matched node (Rule zero: this section still talks to the node ONLY
+ * through `adapter.inspector`/`adapter.hierarchy`, never the DOM/fiber the
+ * adapter itself holds).
+ *
+ * `onChange` (every interaction tick) and `onChangeEnd` (the commit) both
+ * route through the SAME `adapter.inspector.set` call — unlike
+ * `BoxEditProvider`'s begin/apply/end split (a spatial-gesture concern,
+ * Phase B), `ReactWorldAuthoringAdapter.inspector.set` has exactly ONE write
+ * path (T0 §2/A4): it echoes the value into its optimistic cache
+ * synchronously (so the field never snaps back) and fires the async
+ * source-write itself. There is no separate "preview without writing" mode
+ * to route `onChange` through, so both handlers call `commit`, mirroring the
+ * shell's own pre-existing `setProp` helper (`components/Inspector.tsx`)
+ * which already does the same on every keystroke of the generic grid this
+ * section replaces.
+ */
+
+import type { AuthoringAdapter, EditorNode, PropertyDescriptor } from '@engine/adapter';
+import { useMemo } from 'react';
+import { groupProperties } from '../components/inspector-property-grouping';
+import {
+  AlignmentGrid,
+  type AlignmentValue,
+  BorderEditor,
+  BorderRadiusEditor,
+  type BorderRadiusValue,
+  type BorderSide,
+  type BorderValue,
+  ColorSwatch,
+  composeFilter,
+  composeGradient,
+  composeShadows,
+  FilterEditor,
+  type FilterFunc,
+  FONT_MONO,
+  FontPicker,
+  GradientEditor,
+  type GradientValue,
+  inputStyle,
+  isUniformBorder,
+  isUniformRadius,
+  parseFilterFunctions,
+  parseGradient,
+  parseShadows,
+  rowStyle,
+  ScrubbableInput,
+  ShadowEditor,
+  TextShadowEditor,
+  THEME,
+} from '../components/inspector-widgets';
+import { useEditorStore } from '../EditorContext';
+import {
+  type InspectorSectionProps,
+  registerInspectorSections,
+} from '../inspector-section-registry';
+import { effectiveColorFromChain, getAvailableFonts } from '../ui-source/inspect';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { beginEyedropperSession } from './eyedropper-session';
+import { ReactDomAuthoringAdapter } from './react-dom-authoring-adapter';
+import {
+  cssColorToHex,
+  numericStyleValue,
+  ReactWorldAuthoringAdapter,
+} from './react-world-authoring-adapter';
+
+/**
+ * The child adapter that actually owns `node.id` — a bare react/DOM adapter
+ * itself, or (via a `CompositeAuthoringAdapter`) whichever child's
+ * `ownerOf`/`childAdapters()` claims the id (the SAME public T0 query
+ * `components/Inspector.tsx`'s `worldGroupChildAdapter`/`catalogNodeOwnerAdapter`
+ * use — never decode a reserved id here). `null` for anything not owned by a
+ * react/DOM adapter (a threejs/scene-UI node, or an unresolved id).
+ */
+export function resolveReactOwner(
+  node: EditorNode | null,
+  adapter: AuthoringAdapter,
+): ReactWorldAuthoringAdapter | ReactDomAuthoringAdapter | null {
+  if (!node) return null;
+  const target: AuthoringAdapter | null = (() => {
+    if (!(adapter instanceof CompositeAuthoringAdapter)) return adapter;
+    const owner = adapter.ownerOf(node.id);
+    if (owner === null) return null;
+    return adapter.childAdapters().find((c) => c.worldId === owner)?.adapter ?? null;
+  })();
+  if (target instanceof ReactWorldAuthoringAdapter) return target;
+  if (target instanceof ReactDomAuthoringAdapter) return target;
+  return null;
+}
+
+/** The registry `match`: any real selection owned by a react/DOM adapter. */
+export const isReactDomSelection = (node: EditorNode | null, adapter: AuthoringAdapter): boolean =>
+  resolveReactOwner(node, adapter) !== null;
+
+// --- widget mapping (the C2 "map PropertyDescriptor.type/group -> widget" table) ---
+
+export type ReactPropertyWidgetKind =
+  | 'color'
+  | 'font'
+  | 'gradient'
+  | 'shadow'
+  | 'text-shadow'
+  | 'filter'
+  | 'backdrop-filter'
+  | 'radius'
+  | 'transform'
+  | 'scrub'
+  | 'select'
+  | 'checkbox'
+  | 'json'
+  | 'text';
+
+function propNameFromPath(path: string): string {
+  const idx = path.indexOf('.');
+  return idx === -1 ? path : path.slice(idx + 1);
+}
+
+/**
+ * A single `PropertyDescriptor` -> the C1 widget that renders it. Structured
+ * CSS values (gradient/shadow/filter/radius) are matched by their well-known
+ * style-prop NAME (the react adapters' `STYLE_PROPERTIES` tables are the
+ * only source of these paths today — `PropertyDescriptor.type` alone can't
+ * distinguish a plain string from a composable CSS function list); every
+ * other descriptor maps off its plain `type`.
+ */
+export function widgetKindFor(prop: PropertyDescriptor): ReactPropertyWidgetKind {
+  const name = propNameFromPath(prop.path);
+  if (prop.type === 'color') return 'color';
+  if (/^fontFamily$/i.test(name)) return 'font';
+  if (name === 'background' || name === 'backgroundImage') return 'gradient';
+  if (name === 'boxShadow') return 'shadow';
+  if (name === 'textShadow') return 'text-shadow';
+  if (name === 'filter') return 'filter';
+  if (name === 'backdropFilter') return 'backdrop-filter';
+  if (name === 'borderRadius') return 'radius';
+  // Scoped to `type: 'string'` (the react-world `style.transform` CSS-string
+  // descriptor) so an unrelated `transform` name of a DIFFERENT type — e.g. a
+  // threejs `vec3` position/transform prop — still falls through to its own
+  // generic widget instead of being misread as a CSS transform string.
+  if (prop.type === 'string' && name === 'transform') return 'transform';
+  if (prop.type === 'boolean') return 'checkbox';
+  if (prop.type === 'enum') return 'select';
+  if (prop.type === 'json') return 'json';
+  if (prop.type === 'number') return 'scrub';
+  // 'string' / 'vec3' / 'asset' — no dedicated widget in this task's mapping;
+  // falls through to a plain text input (see the report's "no widget" list).
+  return 'text';
+}
+
+/** A composed row: either one property, or a "combo" of several sibling
+ *  properties this section renders as ONE richer widget (per-side border,
+ *  3x3 flex alignment) instead of N separate fields. */
+export type PropertyRow =
+  | {
+      kind: 'border';
+      width: PropertyDescriptor;
+      style: PropertyDescriptor;
+      color: PropertyDescriptor;
+    }
+  | { kind: 'align'; justify: PropertyDescriptor; align: PropertyDescriptor }
+  | { kind: 'single'; prop: PropertyDescriptor };
+
+/**
+ * Groups the react-world adapter's separate `borderWidth`/`borderStyle`/
+ * `borderColor` scalars into one `BorderEditor` row, and `justifyContent`/
+ * `alignItems` into one `AlignmentGrid` row — order-preserving single pass
+ * (a combo is emitted at the position of its FIRST member; already-consumed
+ * members are skipped later in the pass). Any property list missing one or
+ * more combo members (e.g. `ReactDomAuthoringAdapter`'s flatter list) simply
+ * never forms that combo — every member renders as its own `single` row.
+ */
+/** Detects the `borderWidth`/`borderStyle`/`borderColor` trio starting at
+ *  `p` and, if all three are present, pushes ONE `border` combo row. Split
+ *  out of {@link buildPropertyRows} to keep its own cognitive complexity
+ *  under biome's ceiling (same discipline as `GradientEditor.tsx`'s helper
+ *  extraction). Returns `true` only when a combo row was actually formed (so
+ *  the caller can `continue` past all three consumed members); `false` when
+ *  `p` isn't a border-trio member, or is one but its siblings aren't present
+ *  (falls through to an ordinary `single` row instead). */
+function tryBorderCombo(
+  p: PropertyDescriptor,
+  byPath: ReadonlyMap<string, PropertyDescriptor>,
+  consumed: Set<string>,
+  rows: PropertyRow[],
+): boolean {
+  const isBorderProp =
+    p.path === 'style.borderWidth' ||
+    p.path === 'style.borderStyle' ||
+    p.path === 'style.borderColor';
+  if (!isBorderProp) return false;
+  const width = byPath.get('style.borderWidth');
+  const style = byPath.get('style.borderStyle');
+  const color = byPath.get('style.borderColor');
+  if (!width || !style || !color) return false;
+  rows.push({ kind: 'border', width, style, color });
+  consumed.add(width.path);
+  consumed.add(style.path);
+  consumed.add(color.path);
+  return true;
+}
+
+/** Detects the `justifyContent`/`alignItems` pair starting at `p` and, if
+ *  both are present, pushes ONE `align` combo row. See {@link tryBorderCombo}'s
+ *  doc comment for why this is its own function. */
+function tryAlignCombo(
+  p: PropertyDescriptor,
+  byPath: ReadonlyMap<string, PropertyDescriptor>,
+  consumed: Set<string>,
+  rows: PropertyRow[],
+): boolean {
+  const isAlignProp = p.path === 'style.justifyContent' || p.path === 'style.alignItems';
+  if (!isAlignProp) return false;
+  const justify = byPath.get('style.justifyContent');
+  const align = byPath.get('style.alignItems');
+  if (!justify || !align) return false;
+  rows.push({ kind: 'align', justify, align });
+  consumed.add(justify.path);
+  consumed.add(align.path);
+  return true;
+}
+
+export function buildPropertyRows(props: readonly PropertyDescriptor[]): PropertyRow[] {
+  const byPath = new Map(props.map((p) => [p.path, p] as const));
+  const consumed = new Set<string>();
+  const rows: PropertyRow[] = [];
+  for (const p of props) {
+    if (consumed.has(p.path)) continue;
+    if (tryBorderCombo(p, byPath, consumed, rows)) continue;
+    if (tryAlignCombo(p, byPath, consumed, rows)) continue;
+    rows.push({ kind: 'single', prop: p });
+  }
+  return rows;
+}
+
+const UNITLESS_NUMBER_PROPS = new Set(['opacity', 'zIndex', 'flexGrow', 'flexShrink']);
+
+function numericValue(v: unknown): number {
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+function testIdFor(path: string): string {
+  return `react-prop-${path.replace(/\./g, '-')}`;
+}
+
+const DEFAULT_GRADIENT: GradientValue = {
+  type: 'linear',
+  angle: 180,
+  stops: [
+    { color: '#ffffff', position: 0 },
+    { color: '#000000', position: 1 },
+  ],
+};
+
+/** A labeled row shell, matching `components/Inspector.tsx`'s own generic
+ *  property row layout (`NUM_STYLE`'s spacing/label conventions, ported to
+ *  this kit's `THEME`/`rowStyle`) so a react section slots in visually next
+ *  to the sections it replaces. The wrapper's own test id is the row's
+ *  `${testId}-row` — DISTINCT from the interactive control inside it (which
+ *  carries the bare `testId`), so a select/text/json control and its row
+ *  wrapper never collide (spec 27 §5 C2, S1). */
+function Field({
+  label,
+  testId,
+  children,
+}: {
+  label: string;
+  testId?: string | undefined;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <div
+      data-testid={testId ? `${testId}-row` : undefined}
+      style={{ ...rowStyle, padding: '4px 8px' }}
+    >
+      <span style={{ width: 76, flexShrink: 0, fontSize: 11, color: THEME.textMuted }}>
+        {label}
+      </span>
+      <div style={{ flex: 1, minWidth: 0 }}>{children}</div>
+    </div>
+  );
+}
+
+/** {@link PropertyRow}'s two combo variants — excludes `single` so
+ *  {@link ComboRow} (only ever called for a combo row, see `GroupBlock`)
+ *  narrows on `row.kind` without TS widening back to the full union. */
+type ComboPropertyRow = Extract<PropertyRow, { kind: 'border' } | { kind: 'align' }>;
+
+interface ComboRowProps {
+  adapter: AuthoringAdapter;
+  id: string;
+  row: ComboPropertyRow;
+}
+
+/** Every per-kind row renderer's shared inputs — `raw` is the CURRENT value
+ *  read off `adapter.inspector.get`, `commit` writes a (possibly different)
+ *  path through the SAME `adapter.inspector.set` + `notifyIngestEdit` pair
+ *  (see the file doc comment) so a combo write-back (border/align, above)
+ *  and a plain single-prop write share one code path. */
+interface KindRowProps {
+  prop: PropertyDescriptor;
+  raw: unknown;
+  disabled: boolean | undefined;
+  testId: string;
+  commit: (path: string, value: unknown) => void;
+  fonts: readonly string[];
+}
+
+function ColorRow({ prop, raw, disabled, testId, commit }: KindRowProps): React.ReactElement {
+  return (
+    <Field label={prop.label} testId={testId}>
+      <ColorSwatch
+        testId={testId}
+        value={String(raw ?? '#ffffff')}
+        disabled={disabled}
+        onChange={(c) => commit(prop.path, c)}
+        onChangeEnd={(c) => commit(prop.path, c)}
+        eyedropperFallback={() => effectiveColorFromChain([String(raw ?? '')])}
+        // D3.d (spec 27 §6) — no native EyeDropper: begin an interactive
+        // canvas-pick session (`WorldSelectionOverlay` renders the
+        // cursor-following swatch and resolves it) instead of the static
+        // synchronous fallback above, which this session-based path replaces
+        // whenever the host (this section, mounted inside the real editor)
+        // is present to wire it.
+        onEyedropperPick={(apply) => beginEyedropperSession(apply)}
+      />
+    </Field>
+  );
+}
+
+function FontRow({ prop, raw, disabled, fonts, testId, commit }: KindRowProps): React.ReactElement {
+  return (
+    <Field label={prop.label} testId={testId}>
+      <FontPicker
+        testId={testId}
+        value={String(raw ?? '')}
+        fonts={fonts}
+        disabled={disabled}
+        onChange={(f) => commit(prop.path, f)}
+      />
+    </Field>
+  );
+}
+
+function GradientRow({ prop, raw, disabled, testId, commit }: KindRowProps): React.ReactElement {
+  const parsed = parseGradient(String(raw ?? 'none'));
+  // S2 (anti-shim, CLAUDE.md "adapters never fabricate first-party data"): when
+  // the element has NO real gradient (`parseGradient` -> null), render an honest
+  // empty state — NOT a fabricated white→black `DEFAULT_GRADIENT` preview that
+  // misrepresents the source as already having a gradient. `DEFAULT_GRADIENT` is
+  // still the SEED for an explicit user "add" (a real, source-writing action),
+  // never a passive display value.
+  if (!parsed) {
+    return (
+      <Field label={prop.label} testId={testId}>
+        <button
+          type="button"
+          data-testid={testId}
+          disabled={disabled}
+          onClick={() => commit(prop.path, composeGradient(DEFAULT_GRADIENT))}
+          style={{
+            ...inputStyle(disabled),
+            width: '100%',
+            textAlign: 'left',
+            cursor: disabled ? 'not-allowed' : 'pointer',
+            color: THEME.textMuted,
+          }}
+        >
+          No gradient — click to add
+        </button>
+      </Field>
+    );
+  }
+  return (
+    <Field label={prop.label} testId={testId}>
+      <GradientEditor
+        testId={testId}
+        value={parsed}
+        disabled={disabled}
+        onChange={(g) => commit(prop.path, composeGradient(g))}
+        onChangeEnd={(g) => commit(prop.path, composeGradient(g))}
+      />
+    </Field>
+  );
+}
+
+function ShadowRow({
+  prop,
+  raw,
+  disabled,
+  testId,
+  commit,
+  withSpreadInset,
+}: KindRowProps & { withSpreadInset: boolean }): React.ReactElement {
+  const parsed = parseShadows(String(raw ?? 'none'), withSpreadInset);
+  const Widget = withSpreadInset ? ShadowEditor : TextShadowEditor;
+  return (
+    <Field label={prop.label} testId={testId}>
+      <Widget
+        value={parsed}
+        disabled={disabled}
+        onChange={(list) => commit(prop.path, composeShadows(list, withSpreadInset))}
+        onChangeEnd={(list) => commit(prop.path, composeShadows(list, withSpreadInset))}
+      />
+    </Field>
+  );
+}
+
+function FilterRow({
+  prop,
+  raw,
+  disabled,
+  testId,
+  commit,
+  label,
+}: KindRowProps & { label: string }): React.ReactElement {
+  const parsed = parseFilterFunctions(String(raw ?? 'none'));
+  return (
+    <Field label={prop.label} testId={testId}>
+      <FilterEditor
+        testId={testId}
+        label={label}
+        value={parsed}
+        disabled={disabled}
+        onChange={(f: FilterFunc[]) => commit(prop.path, composeFilter(f))}
+        onChangeEnd={(f: FilterFunc[]) => commit(prop.path, composeFilter(f))}
+      />
+    </Field>
+  );
+}
+
+/** Corner suffixes (`borderTopLeftRadius`, …) shared by {@link RadiusRow}'s
+ *  read + write-back — the per-corner longhand CSS the shorthand `borderRadius`
+ *  descriptor (`prop`/`raw`/`commit` above) never had a slot for. */
+const RADIUS_CORNERS: ReadonlyArray<{ key: keyof BorderRadiusValue; suffix: string }> = [
+  { key: 'topLeft', suffix: 'TopLeft' },
+  { key: 'topRight', suffix: 'TopRight' },
+  { key: 'bottomLeft', suffix: 'BottomLeft' },
+  { key: 'bottomRight', suffix: 'BottomRight' },
+];
+
+/** U2 (spec 27 §5 "Effects: radius per-corner") — true per-corner write-back.
+ *  Reads each corner's own `style.border<Corner>Radius` longhand through
+ *  `adapter.inspector.get` (falling back to the shorthand `raw` when a
+ *  corner's own computed value is unset/unparseable — the vitest `node` env
+ *  resolver falls back to inline `.style`, which has no implicit per-corner
+ *  values the way a REAL computed style always does) so the widget reflects
+ *  a PRIOR non-uniform edit instead of collapsing back to uniform on every
+ *  re-render. Write-back keeps the uniform shorthand fast-path (`commit`
+ *  the same `borderRadius` path this row already used) but writes the four
+ *  longhand corners when the widget reports a non-uniform value — removing
+ *  the documented `:397-409` limitation (per-corner UI, uniform-only write). */
+function RadiusRow({
+  adapter,
+  id,
+  prop,
+  raw,
+  disabled,
+  testId,
+  commit,
+  removeStyle,
+}: KindRowProps & {
+  adapter: AuthoringAdapter;
+  id: string;
+  removeStyle: (path: string) => void;
+}): React.ReactElement {
+  const fallback = numericValue(raw);
+  const value: BorderRadiusValue = RADIUS_CORNERS.reduce((acc, { key, suffix }) => {
+    const cornerRaw = adapter.inspector?.get(id, `style.border${suffix}Radius`);
+    acc[key] = numericStyleValue(cornerRaw) ?? fallback;
+    return acc;
+  }, {} as BorderRadiusValue);
+  const writeBack = (v: BorderRadiusValue): void => {
+    if (isUniformRadius(v)) {
+      commit(prop.path, v.topLeft);
+      // D1 — a uniform edit must also CLEAR any per-corner longhands a prior
+      // non-uniform edit wrote, or the stale longhand silently overrides the
+      // shorthand on reload. `removeStyle` no-ops when the longhand isn't
+      // authored, so this is safe on a clean element (never pollutes source).
+      for (const { suffix } of RADIUS_CORNERS) {
+        removeStyle(`style.border${suffix}Radius`);
+      }
+      return;
+    }
+    for (const { key, suffix } of RADIUS_CORNERS) {
+      commit(`style.border${suffix}Radius`, v[key]);
+    }
+  };
+  return (
+    <Field label={prop.label} testId={testId}>
+      <BorderRadiusEditor
+        value={value}
+        disabled={disabled}
+        onChange={writeBack}
+        onChangeEnd={writeBack}
+      />
+    </Field>
+  );
+}
+
+function ScrubRow({ prop, raw, disabled, testId, commit }: KindRowProps): React.ReactElement {
+  const unit = UNITLESS_NUMBER_PROPS.has(propNameFromPath(prop.path)) ? '' : 'px';
+  return (
+    <ScrubbableInput
+      testId={testId}
+      label={prop.label}
+      value={numericValue(raw)}
+      unit={unit}
+      disabled={disabled}
+      onChange={(v) => commit(prop.path, v)}
+      onChangeEnd={(v) => commit(prop.path, v)}
+      style={{ padding: '4px 8px' }}
+    />
+  );
+}
+
+function SelectRow({ prop, raw, disabled, testId, commit }: KindRowProps): React.ReactElement {
+  return (
+    <Field label={prop.label} testId={testId}>
+      <select
+        data-testid={testId}
+        value={String(raw ?? '')}
+        disabled={disabled}
+        onChange={(e) => commit(prop.path, e.target.value)}
+        style={{
+          ...inputStyle(disabled),
+          width: '100%',
+          cursor: disabled ? 'not-allowed' : 'pointer',
+        }}
+      >
+        {(prop.options ?? []).map((o) => (
+          <option key={String(o)} value={String(o)}>
+            {String(o)}
+          </option>
+        ))}
+      </select>
+    </Field>
+  );
+}
+
+function CheckboxRow({ prop, raw, disabled, testId, commit }: KindRowProps): React.ReactElement {
+  return (
+    <label
+      style={{ display: 'flex', gap: 6, alignItems: 'center', padding: '6px 8px', fontSize: 12 }}
+    >
+      <input
+        type="checkbox"
+        data-testid={testId}
+        checked={raw !== false}
+        disabled={disabled}
+        onChange={(e) => commit(prop.path, e.target.checked)}
+      />
+      {prop.label}
+    </label>
+  );
+}
+
+function JsonRow({ prop, raw, disabled, testId, commit }: KindRowProps): React.ReactElement {
+  return (
+    <Field label={prop.label} testId={testId}>
+      <textarea
+        data-testid={testId}
+        defaultValue={JSON.stringify(raw ?? null)}
+        disabled={disabled}
+        style={{ ...inputStyle(disabled), width: '100%', minHeight: 40, fontFamily: FONT_MONO }}
+        onBlur={(e) => {
+          try {
+            commit(prop.path, JSON.parse(e.target.value));
+          } catch {
+            // Invalid JSON — leave the field as typed, don't write garbage.
+          }
+        }}
+      />
+    </Field>
+  );
+}
+
+function TextRow({ prop, raw, disabled, testId, commit }: KindRowProps): React.ReactElement {
+  return (
+    <Field label={prop.label} testId={testId}>
+      <input
+        type="text"
+        data-testid={testId}
+        readOnly={disabled}
+        value={String(raw ?? '')}
+        onChange={(e) => commit(prop.path, e.target.value)}
+        style={{ ...inputStyle(disabled), width: '100%' }}
+      />
+    </Field>
+  );
+}
+
+/** U3 (spec 27 §5 "Transform: rotate/scale") — a structured `{rotateDeg, scale}`
+ *  pair, when `style.transform` is losslessly representable that way. */
+export interface TransformValue {
+  rotateDeg: number;
+  scale: number;
+}
+
+const TRANSFORM_ROTATE_SCALE_RE = /^rotate\(\s*(-?[\d.]+)deg\s*\)\s*scale\(\s*(-?[\d.]+)\s*\)$/i;
+const TRANSFORM_SCALE_ROTATE_RE = /^scale\(\s*(-?[\d.]+)\s*\)\s*rotate\(\s*(-?[\d.]+)deg\s*\)$/i;
+// S3 — single-function literals (a JSX-authored `rotate(45deg)` or `scale(1.5)`
+// alone, missing axis defaulted): computed style is always a matrix in the real
+// browser, but these are exactly what an author hand-writes, so give them the
+// structured row too rather than the raw TextRow.
+const TRANSFORM_ROTATE_ONLY_RE = /^rotate\(\s*(-?[\d.]+)deg\s*\)$/i;
+const TRANSFORM_SCALE_ONLY_RE = /^scale\(\s*(-?[\d.]+)\s*\)$/i;
+const TRANSFORM_MATRIX_RE =
+  /^matrix\(\s*(-?[\d.eE+-]+)\s*,\s*(-?[\d.eE+-]+)\s*,\s*(-?[\d.eE+-]+)\s*,\s*(-?[\d.eE+-]+)\s*,\s*(-?[\d.eE+-]+)\s*,\s*(-?[\d.eE+-]+)\s*\)$/;
+const TRANSFORM_EPS = 1e-4;
+
+/**
+ * Parse a `style.transform` value (either the author's literal
+ * `rotate(<deg>deg) scale(<n>)` — the exact form this row writes — or a
+ * REAL browser's computed 2x2 `matrix(a, b, c, d, e, f)`, since Chromium
+ * always normalizes an authored transform to matrix form, unlike this
+ * repo's headless/vitest fallback which echoes the literal string straight
+ * from inline style) into a structured `{rotateDeg, scale}` pair, or `null`
+ * when the value can't be represented that way LOSSLESSLY — a nonzero
+ * translate (`e`/`f`), a skew/non-uniform scale (`c !== -b` or `d !== a`),
+ * `matrix3d(...)`, or any other transform function list. `null` is the
+ * signal {@link TransformRow} uses to fall back to the plain `TextRow` —
+ * every value this doesn't understand stays editable as raw text, so no
+ * expressiveness is ever silently dropped.
+ */
+export function parseTransform(raw: string): TransformValue | null {
+  const v = raw.trim();
+  if (v === '' || v === 'none') return { rotateDeg: 0, scale: 1 };
+  const lit = TRANSFORM_ROTATE_SCALE_RE.exec(v);
+  if (lit) return { rotateDeg: Number(lit[1]), scale: Number(lit[2]) };
+  const swapped = TRANSFORM_SCALE_ROTATE_RE.exec(v);
+  if (swapped) return { rotateDeg: Number(swapped[2]), scale: Number(swapped[1]) };
+  const rotOnly = TRANSFORM_ROTATE_ONLY_RE.exec(v);
+  if (rotOnly) return { rotateDeg: Number(rotOnly[1]), scale: 1 }; // S3 — missing scale defaults 1
+  const scaleOnly = TRANSFORM_SCALE_ONLY_RE.exec(v);
+  if (scaleOnly) return { rotateDeg: 0, scale: Number(scaleOnly[1]) }; // S3 — missing rotate defaults 0
+  const m = TRANSFORM_MATRIX_RE.exec(v);
+  if (!m) return null; // matrix3d / translate / skew / any other function list
+  const [a, b, c, d, e, f] = m.slice(1, 7).map(Number) as [
+    number,
+    number,
+    number,
+    number,
+    number,
+    number,
+  ];
+  if (Math.abs(e) > TRANSFORM_EPS || Math.abs(f) > TRANSFORM_EPS) return null; // has a translate
+  if (Math.abs(c + b) > TRANSFORM_EPS || Math.abs(d - a) > TRANSFORM_EPS) return null; // skew / non-uniform scale
+  const scale = Math.hypot(a, b);
+  if (scale < TRANSFORM_EPS) return null; // degenerate (zero scale)
+  const rotateDeg = (Math.atan2(b, a) * 180) / Math.PI;
+  return {
+    rotateDeg: Math.round(rotateDeg * 100) / 100,
+    scale: Math.round(scale * 1000) / 1000,
+  };
+}
+
+/** The inverse of {@link parseTransform}'s literal fast-path — always
+ *  composes the readable `rotate()/scale()` form, never a matrix, so the
+ *  written source stays human-editable. */
+export function composeTransform(v: TransformValue): string {
+  return `rotate(${v.rotateDeg}deg) scale(${v.scale})`;
+}
+
+function TransformRow(props: KindRowProps): React.ReactElement {
+  const { prop, raw, disabled, testId, commit } = props;
+  const parsed = parseTransform(String(raw ?? 'none'));
+  if (!parsed) return <TextRow {...props} />; // safety net — no expressiveness lost
+  const writeBack = (next: TransformValue): void => commit(prop.path, composeTransform(next));
+  return (
+    <Field label={prop.label} testId={testId}>
+      <div style={{ display: 'flex', gap: 6 }}>
+        <ScrubbableInput
+          testId={`${testId}-rotate`}
+          label="Rotate"
+          value={parsed.rotateDeg}
+          unit="deg"
+          disabled={disabled}
+          onChange={(v) => writeBack({ ...parsed, rotateDeg: v })}
+          onChangeEnd={(v) => writeBack({ ...parsed, rotateDeg: v })}
+          style={{ flex: 1 }}
+        />
+        <ScrubbableInput
+          testId={`${testId}-scale`}
+          label="Scale"
+          value={parsed.scale}
+          unit="x"
+          step={0.1}
+          disabled={disabled}
+          onChange={(v) => writeBack({ ...parsed, scale: v })}
+          onChangeEnd={(v) => writeBack({ ...parsed, scale: v })}
+          style={{ flex: 1 }}
+        />
+      </div>
+    </Field>
+  );
+}
+
+/** One `single`-kind row: reads the current value, picks the widget via
+ *  {@link widgetKindFor}, and delegates to the matching `*Row` component
+ *  above — each extracted so this dispatcher's own branching stays well
+ *  under biome's complexity ceiling (same discipline `GradientEditor.tsx`/
+ *  `ShadowEditor.tsx` document for their own helper splits). Both
+ *  `onChange`/`onChangeEnd` route through the SAME `commit` (file doc
+ *  comment: this adapter has one write path, not a separate preview mode). */
+function SingleRow({
+  adapter,
+  id,
+  prop,
+  fonts,
+}: {
+  adapter: AuthoringAdapter;
+  id: string;
+  prop: PropertyDescriptor;
+  fonts: readonly string[];
+}): React.ReactElement {
+  const store = useEditorStore();
+  const commit = (path: string, value: unknown): void => {
+    adapter.inspector?.set(id, path, value);
+    store.notifyIngestEdit();
+  };
+  // D1 — remove a stale CSS longhand override (no-op when unauthored); optional
+  // on the inspector, so a non-react adapter simply skips the cleanup.
+  const removeStyle = (path: string): void => {
+    adapter.inspector?.remove?.(id, path);
+    store.notifyIngestEdit();
+  };
+  const rowProps: KindRowProps = {
+    prop,
+    raw: adapter.inspector?.get(id, prop.path),
+    disabled: prop.readonly,
+    testId: testIdFor(prop.path),
+    commit,
+    fonts,
+  };
+  switch (widgetKindFor(prop)) {
+    case 'color':
+      return <ColorRow {...rowProps} />;
+    case 'font':
+      return <FontRow {...rowProps} />;
+    case 'gradient':
+      return <GradientRow {...rowProps} />;
+    case 'shadow':
+      return <ShadowRow {...rowProps} withSpreadInset />;
+    case 'text-shadow':
+      return <ShadowRow {...rowProps} withSpreadInset={false} />;
+    case 'filter':
+      return <FilterRow {...rowProps} label="Filter" />;
+    case 'backdrop-filter':
+      return <FilterRow {...rowProps} label="Backdrop Filter" />;
+    case 'radius':
+      return <RadiusRow {...rowProps} adapter={adapter} id={id} removeStyle={removeStyle} />;
+    case 'transform':
+      return <TransformRow {...rowProps} />;
+    case 'scrub':
+      return <ScrubRow {...rowProps} />;
+    case 'select':
+      return <SelectRow {...rowProps} />;
+    case 'checkbox':
+      return <CheckboxRow {...rowProps} />;
+    case 'json':
+      return <JsonRow {...rowProps} />;
+    default:
+      return <TextRow {...rowProps} />;
+  }
+}
+
+/** A `border`/`align` combo row — reads all its member props, composes the
+ *  widget's structured value, and writes every member back on change. */
+function ComboRow({ adapter, id, row }: ComboRowProps): React.ReactElement | null {
+  const store = useEditorStore();
+  const commit = (path: string, value: unknown): void => {
+    adapter.inspector?.set(id, path, value);
+    store.notifyIngestEdit();
+  };
+  const removeStyle = (path: string): void => {
+    adapter.inspector?.remove?.(id, path);
+    store.notifyIngestEdit();
+  };
+  if (row.kind === 'border') {
+    // U2 (spec 27 §5 "Stroke: per-side border") — the shorthand descriptors
+    // (`row.width`/`row.style`/`row.color`) are the uniform fallback; each
+    // side's OWN longhand (`borderTopWidth`, …) is read through the same
+    // `adapter.inspector.get` and wins when present, so a prior per-side
+    // edit survives the next re-render instead of collapsing back to
+    // uniform (mirrors `RadiusRow`'s corner read, same fallback rationale:
+    // the vitest `node` env resolver has no implicit per-side computed
+    // values the way a real `CSSStyleDeclaration` always does).
+    const fallback: BorderSide = {
+      width: numericValue(adapter.inspector?.get(id, row.width.path)),
+      style: String(adapter.inspector?.get(id, row.style.path) ?? 'solid'),
+      color: String(adapter.inspector?.get(id, row.color.path) ?? '#000000'),
+    };
+    const readSide = (suffix: 'Top' | 'Right' | 'Bottom' | 'Left'): BorderSide => {
+      const w = numericStyleValue(adapter.inspector?.get(id, `style.border${suffix}Width`));
+      const st = adapter.inspector?.get(id, `style.border${suffix}Style`);
+      const c = adapter.inspector?.get(id, `style.border${suffix}Color`);
+      // D1 — normalize the per-side color longhand through `cssColorToHex`: it's
+      // not in `STYLE_PROPERTY_TYPE`, so `inspector.get` hands back the RAW
+      // computed value (`rgb(…)`), and letting that flow into a later uniform
+      // commit would rewrite the author's hex literal as an `rgb()` string.
+      const cHex = typeof c === 'string' ? cssColorToHex(c) : undefined;
+      return {
+        width: w ?? fallback.width,
+        style: typeof st === 'string' && st ? st : fallback.style,
+        color: cHex ?? fallback.color,
+      };
+    };
+    const value: BorderValue = {
+      top: readSide('Top'),
+      right: readSide('Right'),
+      bottom: readSide('Bottom'),
+      left: readSide('Left'),
+    };
+    // Uniform edits keep the pre-existing shorthand fast-path (3 commits to
+    // the `borderWidth`/`borderStyle`/`borderColor` descriptors this row
+    // always had); a non-uniform widget value now writes the 4 per-side
+    // CSS longhands instead of collapsing to `.top` — removing the
+    // documented limitation this file used to note here.
+    const sideSuffixes = ['Top', 'Right', 'Bottom', 'Left'] as const;
+    const writeBack = (v: BorderValue): void => {
+      if (isUniformBorder(v)) {
+        commit(row.width.path, v.top.width);
+        commit(row.style.path, v.top.style);
+        commit(row.color.path, v.top.color);
+        // D1 — clear any per-side longhands a prior non-uniform edit wrote, so
+        // the uniform shorthand actually wins on reload (removeStyle no-ops
+        // when a longhand isn't authored — safe on a clean element).
+        for (const suffix of sideSuffixes) {
+          removeStyle(`style.border${suffix}Width`);
+          removeStyle(`style.border${suffix}Style`);
+          removeStyle(`style.border${suffix}Color`);
+        }
+        return;
+      }
+      const sides: ReadonlyArray<{
+        suffix: 'Top' | 'Right' | 'Bottom' | 'Left';
+        side: BorderSide;
+      }> = sideSuffixes.map((suffix) => ({
+        suffix,
+        side: v[suffix.toLowerCase() as 'top' | 'right' | 'bottom' | 'left'],
+      }));
+      for (const { suffix, side } of sides) {
+        commit(`style.border${suffix}Width`, side.width);
+        commit(`style.border${suffix}Style`, side.style);
+        commit(`style.border${suffix}Color`, side.color);
+      }
+    };
+    return (
+      <Field label="Border" testId="react-prop-border">
+        <BorderEditor value={value} onChange={writeBack} onChangeEnd={writeBack} />
+      </Field>
+    );
+  }
+  const value: AlignmentValue = {
+    justify:
+      (adapter.inspector?.get(id, row.justify.path) as AlignmentValue['justify']) ?? 'flex-start',
+    align: (adapter.inspector?.get(id, row.align.path) as AlignmentValue['align']) ?? 'flex-start',
+  };
+  return (
+    <Field label="Align" testId="react-prop-align">
+      <AlignmentGrid
+        value={value}
+        onChange={(v) => {
+          commit(row.justify.path, v.justify);
+          commit(row.align.path, v.align);
+        }}
+      />
+    </Field>
+  );
+}
+
+function rowKey(row: PropertyRow): string {
+  if (row.kind === 'single') return row.prop.path;
+  if (row.kind === 'border') return `border:${row.width.path}`;
+  return `align:${row.justify.path}`;
+}
+
+function GroupBlock({
+  name,
+  groupId,
+  props,
+  adapter,
+  id,
+  fonts,
+}: {
+  name: string;
+  groupId: string;
+  props: readonly PropertyDescriptor[];
+  adapter: AuthoringAdapter;
+  id: string;
+  fonts: readonly string[];
+}): React.ReactElement {
+  const rows = buildPropertyRows(props);
+  return (
+    <div
+      data-testid={`react-inspector-group-${groupId}`}
+      style={{ borderTop: `1px solid ${THEME.border}`, marginTop: 4 }}
+    >
+      <div
+        style={{
+          fontSize: 11,
+          fontWeight: 600,
+          color: THEME.textMuted,
+          padding: '6px 8px 2px',
+          textTransform: 'uppercase',
+          letterSpacing: 0.4,
+        }}
+      >
+        {name}
+      </div>
+      {rows.map((row) =>
+        row.kind === 'single' ? (
+          <SingleRow key={rowKey(row)} adapter={adapter} id={id} prop={row.prop} fonts={fonts} />
+        ) : (
+          <ComboRow key={rowKey(row)} adapter={adapter} id={id} row={row} />
+        ),
+      )}
+    </div>
+  );
+}
+
+/** The Lane-B ("edits component source -> every instance") disclosure —
+ *  ports `ui-editor/source-edit-panel.tsx`'s header COPY, not the component
+ *  itself (that one is bound to `UIEditStore`/an ad hoc `/__ui-source/index`
+ *  fetch — Rule zero bans importing `UIEditStore` into this shell-registered
+ *  section). Shown only for a `ReactWorldAuthoringAdapter` (real Lane B,
+ *  `data-oid` component-source writes); a `ReactDomAuthoringAdapter`
+ *  (ingested, overlay-only — never touches source) gets its own honest note
+ *  instead, so neither lane's write model is ever misrepresented. */
+function LaneDisclosure({
+  owner,
+  node,
+}: {
+  owner: ReactWorldAuthoringAdapter | ReactDomAuthoringAdapter;
+  node: EditorNode | null;
+}): React.ReactElement {
+  const isLaneB = owner instanceof ReactWorldAuthoringAdapter;
+  return (
+    <div
+      data-testid={isLaneB ? 'react-lane-b-disclosure' : 'react-overlay-disclosure'}
+      style={{
+        padding: 8,
+        borderBottom: `1px solid ${THEME.border}`,
+        background: isLaneB ? 'rgba(59,130,246,0.08)' : 'rgba(255,255,255,0.04)',
+        color: THEME.text,
+        fontSize: 11,
+        lineHeight: 1.5,
+      }}
+    >
+      {isLaneB ? (
+        <>
+          <strong style={{ color: THEME.accent }}>Component source.</strong> Edits change{' '}
+          <code style={{ fontFamily: FONT_MONO }}>{node?.label ?? 'this component'}</code>'s source
+          — every rendered instance updates.
+        </>
+      ) : (
+        <>
+          <strong style={{ color: THEME.textMuted }}>Session overlay (ingested game).</strong> Edits
+          are NOT written to source — they persist as a per-project overlay only.
+        </>
+      )}
+    </div>
+  );
+}
+
+/** The registered section itself (C2). Renders every `PropertyDescriptor`
+ *  from `adapter.inspector.properties(nodeId)`, grouped and widget-mapped —
+ *  see the file doc comment for the write-routing contract. */
+function ReactPropertiesSection({
+  adapter,
+  nodeId,
+}: InspectorSectionProps): React.ReactElement | null {
+  // Re-render is driven by the shell's own `useSyncExternalStore` subscription
+  // (`components/Inspector.tsx`) — every `SingleRow`/`ComboRow` below calls
+  // `store.notifyIngestEdit()` itself on commit (its own `useEditorStore()`),
+  // which re-renders the whole Inspector tree including this section; no
+  // separate subscription is needed here.
+  const fonts = useMemo(() => getAvailableFonts(), []);
+  if (!nodeId) return null;
+  const node = adapter.hierarchy.node(nodeId);
+  const owner = resolveReactOwner(node, adapter);
+  if (!owner) return null;
+
+  const props = (adapter.inspector?.properties(nodeId) ?? []).filter((p) => p.path !== 'name');
+  const { ungrouped, groups } = groupProperties(props);
+
+  return (
+    <div data-testid="react-inspector-section">
+      <LaneDisclosure owner={owner} node={node} />
+      {ungrouped.length > 0 && (
+        <GroupBlock
+          name="Style"
+          groupId="style"
+          props={ungrouped}
+          adapter={adapter}
+          id={nodeId}
+          fonts={fonts}
+        />
+      )}
+      {groups.map((g) => (
+        <GroupBlock
+          key={g.groupId}
+          name={g.name}
+          groupId={g.groupId}
+          props={g.properties}
+          adapter={adapter}
+          id={nodeId}
+          fonts={fonts}
+        />
+      ))}
+    </div>
+  );
+}
+
+registerInspectorSections({
+  match: isReactDomSelection,
+  Section: ReactPropertiesSection,
+  suppresses: ['properties'],
+});