@vgai/editor 0.2.0

package/src/components/Inspector.tsx

@@ -0,0 +1,671 @@
+/**
+ * `Inspector` — the ONE inspector shell (C2, docs/unified-world-editor/26-
+ * unified-editor-spec.md §4 C2). Renders straight from the active
+ * {@link AuthoringAdapter}'s providers (`hierarchy` / `selection` /
+ * `transforms` / `inspector`) — format-neutral `EditorNode`s and
+ * `PropertyDescriptor`s, NO `SceneEntity` — PLUS whatever
+ * `inspector-section-registry.ts` registrations match the current
+ * selection/adapter (`authoring/first-party-inspector/register.tsx` for the
+ * threejs adapter, `authoring/ui-inspector-sections.tsx` for the UI
+ * adapter). A matched registration may `suppresses` one or more of this
+ * file's own built-in blocks it fully replaces (e.g. the first-party
+ * `ComponentsSection` suppresses the generic `components` grid block below)
+ * so a matched selection never double-renders the same affordance — see
+ * `inspector-section-registry.ts`'s header comment for the full design.
+ *
+ * A2 (docs/unified-world-editor/26-unified-editor-spec.md §2 A2) deleted this
+ * file's HIERARCHY half (`IngestHierarchy`/`IngestRowView`/`IngestMoreRow`/
+ * `KIND_GLYPH`) — its row-rendering + context-menu logic moved into
+ * `components/GameHierarchy.tsx`, the one contract-only hierarchy panel that
+ * now serves every session shape (bare single-scene, ingested game,
+ * multi-world composite). This file keeps only the INSPECTOR half; C2 folded
+ * the former bespoke `InspectorPanel.tsx` into it as registered sections
+ * (deleting the A3 dispatch seam that used to choose between the two).
+ */
+
+import type { AuthoringAdapter, EditorNode, PropertyDescriptor, Transform } from '@engine/adapter';
+import { useSyncExternalStore } from 'react';
+import * as THREE from 'three';
+import { getActiveAuthoring } from '../authoring/active-adapter';
+import { CompositeAuthoringAdapter } from '../authoring/composite-authoring-adapter';
+import { ReactWorldAuthoringAdapter } from '../authoring/react-world-authoring-adapter';
+import { useEditorStore } from '../EditorContext';
+import { setActiveScope } from '../hotkeys';
+import { isIngestActiveReact } from '../ingest-mode';
+import type { InspectorBuiltin } from '../inspector-section-registry';
+import {
+  inspectorSectionRegistryVersion,
+  matchedInspectorSections,
+  subscribeInspectorSectionRegistry,
+} from '../inspector-section-registry';
+import { groupProperties } from './inspector-property-grouping';
+import { Panel } from './primitives/Panel';
+
+/**
+ * D4 (B2) — the CHILD adapter owning `nodeId`'s synthetic world-group row
+ * (`world:<id>`, `CompositeAuthoringAdapter`'s own manufactured node), or
+ * `null` when `adapter` isn't a composite or `nodeId` isn't one of its group
+ * nodes. Mirrors `GameHierarchy.tsx`'s (unexported) `compositeGroupBadge` —
+ * same "ask the public T0 query (`childAdapters()`/`groupNodeId()`), never
+ * decode the reserved id yourself" discipline, this file's own use of it.
+ * Used ONLY to gate the "Stories" section below: a world-group row whose
+ * owning child adapter itself advertises `stories` (a live react world) gets
+ * the section (dropdown or "no stories" disclosure); any other row (an
+ * ordinary entity, or a world-group row for a kind that never sets
+ * `stories` — threejs/pixi/an un-upgraded Boundary placeholder) gets none.
+ */
+function worldGroupChildAdapter(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): AuthoringAdapter | null {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return null;
+  for (const child of adapter.childAdapters()) {
+    if (adapter.groupNodeId(child.worldId) === nodeId) return child.adapter;
+  }
+  return null;
+}
+
+/**
+ * B3 (docs/unified-world-editor/26-unified-editor-spec.md §3 B3) — the CHILD
+ * adapter owning a `kind:'component'` CATALOG node (as opposed to
+ * `worldGroupChildAdapter`'s `world:<id>` GROUP row above). Resolved by
+ * ACTUAL ownership — `CompositeAuthoringAdapter.ownerOf`/`childAdapters()`,
+ * the same public T0 query `worldGroupChildAdapter` uses — never by decoding
+ * the catalog id's `catalog:` prefix here (Rule zero: this file stays
+ * format-neutral about adapter-minted ids; only `node?.kind === 'component'`
+ * is this file's own knowledge). `null` for anything that isn't a composite,
+ * or a component node the composite doesn't (yet) recognize.
+ */
+function catalogNodeOwnerAdapter(
+  adapter: AuthoringAdapter,
+  node: EditorNode | null,
+  nodeId: string,
+): AuthoringAdapter | null {
+  if (!node || node.kind !== 'component') return null;
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return null;
+  const worldId = adapter.ownerOf(nodeId);
+  if (!worldId) return null;
+  return adapter.childAdapters().find((c) => c.worldId === worldId)?.adapter ?? null;
+}
+
+/** B3 — `true` when `nodeId` (a catalog node) IS the owning react adapter's
+ *  currently-isolated node — the SAME "ask the owning child" discipline as
+ *  `worldGroupChildAdapter`'s `stories` read, never decoded from the id. */
+function isCatalogNodeIsolated(storiesOwner: AuthoringAdapter | null, nodeId: string): boolean {
+  return (
+    storiesOwner instanceof ReactWorldAuthoringAdapter && storiesOwner.isolatedNodeId === nodeId
+  );
+}
+
+/** B3 — the Isolate toggle's click handler: isolate the catalog node against
+ *  whichever story is currently selected (the SAME dropdown value the
+ *  `ingest-stories-select` reuses), or exit isolation back to the entry. */
+function toggleCatalogIsolation(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+  isIsolated: boolean,
+): void {
+  if (isIsolated) {
+    adapter.stories?.isolate?.(null);
+    return;
+  }
+  const storyId = adapter.stories?.active(nodeId) ?? undefined;
+  adapter.stories?.isolate?.(nodeId, storyId);
+}
+
+const NUM_STYLE: React.CSSProperties = {
+  width: 64,
+  background: '#1e1e1e',
+  color: '#c5c8ce',
+  border: '1px solid #333',
+  borderRadius: 2,
+  padding: '3px 5px',
+  fontSize: 12,
+};
+
+function AxisRow({
+  label,
+  values,
+  testidPrefix,
+  onCommit,
+}: {
+  label: string;
+  values: [number, number, number];
+  testidPrefix: string;
+  onCommit: (axis: 0 | 1 | 2, v: number) => void;
+}) {
+  const axes: Array<{ a: 0 | 1 | 2; n: string }> = [
+    { a: 0, n: 'x' },
+    { a: 1, n: 'y' },
+    { a: 2, n: 'z' },
+  ];
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 6, padding: '4px 8px' }}>
+      <span style={{ width: 56, fontSize: 12, color: '#9aa0a6' }}>{label}</span>
+      {axes.map(({ a, n }) => (
+        <input
+          key={n}
+          type="number"
+          data-testid={`${testidPrefix}-${n}`}
+          value={Number.isFinite(values[a]) ? Math.round(values[a] * 1000) / 1000 : 0}
+          onChange={(e) => onCommit(a, Number.parseFloat(e.target.value))}
+          style={NUM_STYLE}
+        />
+      ))}
+    </div>
+  );
+}
+
+export function Inspector() {
+  const store = useEditorStore();
+  useSyncExternalStore(store.subscribe, store.getSnapshot);
+  // Re-render when section registrations change (W3): project inspector
+  // TOOLS register asynchronously (folder scan) and re-register on HMR —
+  // possibly while a matching selection is already showing. First-party
+  // registrations are import-time side effects, so this never fired for them.
+  useSyncExternalStore(subscribeInspectorSectionRegistry, inspectorSectionRegistryVersion);
+  const adapter = getActiveAuthoring(store);
+  const id = [...store.selectedEntityIds][0] ?? null;
+
+  // No inspector surface: either an opaque prebuilt bundle (iframe floor) or an
+  // ingested native-React world (no-authoring by design, D-N8) — the honest copy
+  // differs, so branch on which session is active.
+  if (!adapter.capabilities.inspectorFields) {
+    return (
+      <Panel
+        name="Inspector (embed-only)"
+        data-testid="inspector-panel"
+        onPointerDown={() => setActiveScope('inspector')}
+      >
+        <div
+          data-testid="ingest-embed-note"
+          style={{ padding: 12, color: '#c9a227', fontSize: 12, lineHeight: 1.5 }}
+        >
+          {isIngestActiveReact() ? (
+            <>
+              <strong>Embed-only.</strong> This is an ingested native-React game: its components
+              render directly as a DOM layer under the host React — there is no scene graph or
+              renderer to introspect, and authoring is deliberately off for react ingests (the
+              editor never writes JSX back into an unmodified game). The game is hosted, sized, and
+              disposed; play it in the Game tab.
+            </>
+          ) : (
+            <>
+              <strong>Embed-only.</strong> This bundle runs its own renderer in a sandboxed iframe
+              the editor cannot reach into — it is hosted and sized, but its scene is not
+              introspectable. (This demo's payload is a self-contained canvas app; a real opaque
+              three.js bundle, whose realm-local <code>three</code> is unreachable, behaves
+              identically.) Source-available games run under the editor's bundler get full live
+              editing instead.
+            </>
+          )}
+        </div>
+      </Panel>
+    );
+  }
+
+  // Nothing selected → environment / scene-settings panel. A matched
+  // registration (e.g. the first-party adapter's rich scene Environment
+  // section) fully replaces the generic ingest-only background/fog note
+  // below (its `suppresses: ['environment']` is exactly why `matched.length
+  // > 0` here implies the built-in branch would have been suppressed anyway).
+  //
+  // `matched`/`suppressed`/`panelNameOverride` are resolved SEPARATELY per
+  // branch (here, and again below `id` is confirmed truthy) rather than
+  // once up front against a shared `node = id ? adapter.hierarchy.node(id)
+  // : null` — collapsing "nothing selected" and "a selected id the current
+  // adapter's hierarchy can't resolve" into the same `node === null` would
+  // let a first-party composite's null-selection Environment registration
+  // (see `authoring/first-party-inspector/register.tsx`'s
+  // `isFirstPartySelection` fallback) wrongly match while a (stale/foreign)
+  // id is still selected.
+  if (!id) {
+    const matched = matchedInspectorSections(null, adapter);
+    const panelNameOverride = matched.map((reg) => reg.panelName).find((n): n is string => !!n);
+    if (matched.length > 0) {
+      return (
+        <Panel
+          name={panelNameOverride ?? 'Environment (ingested game)'}
+          data-testid="inspector-panel"
+          onPointerDown={() => setActiveScope('inspector')}
+          style={{ overflowY: 'auto', scrollbarWidth: 'none' }}
+        >
+          {matched.map(({ Section }, i) => (
+            <Section key={i} adapter={adapter} nodeId={null} />
+          ))}
+        </Panel>
+      );
+    }
+    const scene = store.scene;
+    const bg =
+      scene?.background instanceof THREE.Color ? `#${scene.background.getHexString()}` : '#000000';
+    const hasFog = !!scene?.fog;
+    return (
+      <Panel
+        name="Environment (ingested game)"
+        data-testid="inspector-panel"
+        onPointerDown={() => setActiveScope('inspector')}
+      >
+        <div style={{ pointerEvents: 'auto', padding: 4 }}>
+          <div style={{ padding: 8, color: '#777', fontSize: 12 }}>
+            Scene settings — nothing selected.
+          </div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 6, padding: '6px 8px' }}>
+            <span style={{ width: 80, fontSize: 12, color: '#9aa0a6' }}>Background</span>
+            <input
+              type="color"
+              data-testid="ingest-env-background"
+              value={bg}
+              onChange={(e) => {
+                if (scene) {
+                  scene.background = new THREE.Color(e.target.value);
+                  store.notifyIngestEdit();
+                }
+              }}
+            />
+          </div>
+          <label
+            style={{
+              display: 'flex',
+              gap: 6,
+              alignItems: 'center',
+              padding: '6px 8px',
+              fontSize: 12,
+            }}
+          >
+            <input
+              type="checkbox"
+              data-testid="ingest-env-fog"
+              checked={hasFog}
+              onChange={(e) => {
+                if (!scene) return;
+                scene.fog = e.target.checked ? new THREE.Fog(0x8899aa, 1, 80) : null;
+                store.notifyIngestEdit();
+              }}
+            />
+            Fog
+          </label>
+        </div>
+      </Panel>
+    );
+  }
+
+  const node = adapter.hierarchy.node(id);
+  // A registered section only matches a REAL, resolved node — an id the
+  // current adapter's hierarchy can't resolve (`node === null` here, despite
+  // `id` being truthy) never matches (mirrors the deleted A3 dispatch's own
+  // `ownerOf(id) === null -> false`), so it renders the plain generic
+  // built-ins below exactly as it always has, never a first-party section.
+  const matched = node ? matchedInspectorSections(node, adapter) : [];
+  const suppressed = new Set<InspectorBuiltin>();
+  for (const reg of matched) {
+    for (const b of reg.suppresses ?? []) suppressed.add(b);
+  }
+  const panelNameOverride = matched.map((reg) => reg.panelName).find((n): n is string => !!n);
+  const t = adapter.transforms?.get(id) ?? {
+    position: [0, 0, 0],
+    rotation: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+  };
+  // The full property set is DRIVEN BY the adapter's InspectorProvider — a generic
+  // PropertyDescriptor list (name/visible/material/light/camera/mesh), not a
+  // hardcoded panel. 'name' is rendered at the header; the rest as a generic grid.
+  const props = (adapter.inspector?.properties(id) ?? []).filter((p) => p.path !== 'name');
+
+  // D4 (B2) — story picker gating: the section itself only appears for a
+  // world-group row whose owning child adapter has a `stories` provider at
+  // all (see `worldGroupChildAdapter`'s doc comment); WITHIN that, the
+  // dropdown is gated on `storiesFor(id).length > 0` — NEVER on
+  // `adapter.stories` truthiness alone, since the composite's OWN `stories`
+  // pass-through is always present regardless of what (if anything) the
+  // routed child actually offers.
+  //
+  // B3 — a `kind:'component'` catalog node ALSO gets this section (its own
+  // owner resolution, `catalogNodeOwnerAdapter`, since it isn't a `world:<id>`
+  // group row) — the SAME story dropdown (reused verbatim), plus an Isolate
+  // toggle that renders the component ALONE against whichever story is
+  // currently selected.
+  const isCatalogNode = node?.kind === 'component';
+  const storiesOwner =
+    worldGroupChildAdapter(adapter, id) ?? catalogNodeOwnerAdapter(adapter, node, id);
+  const storyRefs = storiesOwner?.stories ? (adapter.stories?.storiesFor(id) ?? []) : [];
+  const showStoriesSection = !!storiesOwner?.stories || isCatalogNode;
+  const isIsolated = isCatalogNode && isCatalogNodeIsolated(storiesOwner, id);
+
+  const commitTransform = (axis: 0 | 1 | 2, key: keyof Transform, v: number) => {
+    if (!Number.isFinite(v)) return;
+    const next: Transform = {
+      position: [...t.position] as [number, number, number],
+      rotation: [...t.rotation] as [number, number, number, number],
+      scale: [...t.scale] as [number, number, number],
+    };
+    (next[key] as number[])[axis] = v;
+    adapter.transforms?.beginEdit(id);
+    adapter.transforms?.apply(id, next);
+    adapter.transforms?.endEdit(id);
+    store.notifyIngestEdit();
+  };
+  const setProp = (path: string, value: unknown) => {
+    adapter.inspector?.set(id, path, value);
+    store.notifyIngestEdit();
+  };
+  // Stable testid: keep the legacy ones the e2e relies on.
+  const testidFor = (path: string) =>
+    path === 'visible' ? 'ingest-visible' : `ingest-prop-${path.replace(/\./g, '-')}`;
+
+  // Per-descriptor row renderer (T3.4 slice 2, docs/ADAPTER-AUTHORING-DESIGN.md
+  // §1.E) — extracted so BOTH the flat (ungrouped) list and each titled group
+  // sub-section below render a `PropertyDescriptor` identically. Behavior is
+  // unchanged from before `group` existed; this is a pure refactor of the
+  // same per-`p.type` switch.
+  const renderProperty = (p: PropertyDescriptor) => {
+    const v = adapter.inspector?.get(id, p.path);
+    if (p.type === 'boolean') {
+      return (
+        <label
+          key={p.path}
+          style={{
+            display: 'flex',
+            gap: 6,
+            alignItems: 'center',
+            padding: '6px 8px',
+            fontSize: 12,
+          }}
+        >
+          <input
+            type="checkbox"
+            data-testid={testidFor(p.path)}
+            checked={v !== false}
+            onChange={(e) => setProp(p.path, e.target.checked)}
+          />
+          {p.label}
+        </label>
+      );
+    }
+    return (
+      <div
+        key={p.path}
+        style={{ display: 'flex', alignItems: 'center', gap: 6, padding: '6px 8px' }}
+      >
+        <span style={{ width: 64, fontSize: 12, color: '#9aa0a6' }}>{p.label}</span>
+        {p.type === 'color' ? (
+          <input
+            type="color"
+            data-testid={p.path === 'material.color' ? 'ingest-color' : testidFor(p.path)}
+            value={(v as string) ?? '#ffffff'}
+            onChange={(e) => setProp(p.path, e.target.value)}
+          />
+        ) : p.type === 'number' ? (
+          <input
+            type="number"
+            data-testid={testidFor(p.path)}
+            disabled={p.readonly}
+            value={typeof v === 'number' ? Math.round(v * 1000) / 1000 : 0}
+            onChange={(e) => setProp(p.path, Number.parseFloat(e.target.value))}
+            style={NUM_STYLE}
+          />
+        ) : (
+          <input
+            type="text"
+            data-testid={testidFor(p.path)}
+            readOnly={p.readonly}
+            value={String(v ?? '')}
+            onChange={(e) => setProp(p.path, e.target.value)}
+            style={{ ...NUM_STYLE, width: 120 }}
+          />
+        )}
+      </div>
+    );
+  };
+
+  // Split into the flat (ungrouped, today's-behavior) list and named groups —
+  // grouped fields render together under a titled sub-section instead of the
+  // flat grid (§1.E: "the generic inspector panel renders grouped sections").
+  // Order preserved: ungrouped fields keep their original position/order
+  // (byte-stable when nothing is grouped); groups render in first-seen order
+  // AFTER the ungrouped fields. The split itself is a pure, unit-tested
+  // helper (`inspector-property-grouping.ts`) — this component only renders it.
+  const { ungrouped: ungroupedProps, groups } = groupProperties(props);
+
+  return (
+    <Panel
+      name={panelNameOverride ?? 'Inspector (ingested game)'}
+      data-testid="inspector-panel"
+      onPointerDown={() => setActiveScope('inspector')}
+    >
+      <div style={{ pointerEvents: 'auto' }}>
+        {!suppressed.has('header') && (
+          <div style={{ padding: 8, borderBottom: '1px solid #333' }}>
+            <input
+              data-testid="ingest-name"
+              value={node?.label ?? ''}
+              onChange={(e) => setProp('name', e.target.value)}
+              style={{ ...NUM_STYLE, width: '100%', fontWeight: 600 }}
+            />
+            <div style={{ marginTop: 6, fontSize: 11, color: '#777' }}>
+              {node?.kind} · runtime-only (ingested)
+            </div>
+          </div>
+        )}
+
+        {!suppressed.has('transform') && (
+          <>
+            <AxisRow
+              label="Position"
+              testidPrefix="ingest-position"
+              values={t.position}
+              onCommit={(a, v) => commitTransform(a, 'position', v)}
+            />
+            <AxisRow
+              label="Scale"
+              testidPrefix="ingest-scale"
+              values={t.scale}
+              onCommit={(a, v) => commitTransform(a, 'scale', v)}
+            />
+          </>
+        )}
+
+        {/* Generic InspectorProvider-driven property grid (per descriptor type) —
+            ungrouped fields first (byte-stable: identical to pre-`group` output
+            when no descriptor declares one), then each named group as a titled
+            sub-section (§1.E). */}
+        {!suppressed.has('properties') && (
+          <>
+            {ungroupedProps.map(renderProperty)}
+            {groups.map((group) => (
+              <div
+                key={group.name}
+                data-testid={`ingest-group-${group.groupId}`}
+                style={{ borderTop: '1px solid #333', marginTop: 4 }}
+              >
+                <div
+                  style={{
+                    fontSize: 11,
+                    fontWeight: 600,
+                    color: '#9aa0a6',
+                    padding: '6px 8px 2px',
+                    textTransform: 'uppercase',
+                    letterSpacing: 0.4,
+                  }}
+                >
+                  {group.name}
+                </div>
+                {group.properties.map(renderProperty)}
+              </div>
+            ))}
+          </>
+        )}
+
+        {/* Components section (C1, `docs/unified-world-editor/26-unified-editor-
+            spec.md` §C1) — driven by `adapter.components` (a `ComponentsProvider`,
+            absent on every ingest/pixi/react/world-group adapter reachable from
+            here today, so this renders the N/A fallback in practice until C2
+            routes first-party nodes through this generic panel). When the
+            provider exists AND has something to show, render its `list()` rows
+            (each removable) plus an "+ Add component…" select over `available()`.
+            Otherwise fall back to the ORIGINAL honest-N/A copy, under the SAME
+            `ingest-components-na` testid, byte-identical to before this section
+            existed (feat-inspector-components-na / `14-ingest-feature-matrix`). */}
+        {!suppressed.has('components') &&
+          (() => {
+            const compList = adapter.components?.list(id) ?? [];
+            const compAvailable = adapter.components?.available(id) ?? [];
+            if (!adapter.components || (compList.length === 0 && compAvailable.length === 0)) {
+              return (
+                <div
+                  data-testid="ingest-components-na"
+                  style={{ padding: '8px', borderTop: '1px solid #333', marginTop: 4 }}
+                >
+                  <div style={{ fontSize: 11, fontWeight: 600, color: '#9aa0a6', marginBottom: 4 }}>
+                    Components
+                  </div>
+                  <div style={{ fontSize: 11, color: '#777', fontStyle: 'italic' }}>
+                    No components — this object is owned by the unmodified game (no engine
+                    GameComponents).
+                  </div>
+                </div>
+              );
+            }
+            const componentsProvider = adapter.components;
+            return (
+              <div style={{ padding: '8px', borderTop: '1px solid #333', marginTop: 4 }}>
+                <div style={{ fontSize: 11, fontWeight: 600, color: '#9aa0a6', marginBottom: 4 }}>
+                  Components
+                </div>
+                {compList.map((c) => (
+                  <div
+                    key={c.type}
+                    data-testid="ingest-component-row"
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      justifyContent: 'space-between',
+                      padding: '2px 0',
+                    }}
+                  >
+                    <span style={{ fontSize: 11, color: '#c5c8ce' }}>{c.type}</span>
+                    <button
+                      type="button"
+                      data-testid="ingest-component-remove"
+                      title="Remove component"
+                      onClick={() => {
+                        componentsProvider.remove(id, c.type);
+                        store.notifyIngestEdit();
+                      }}
+                      style={{
+                        background: 'transparent',
+                        border: 'none',
+                        color: '#777',
+                        cursor: 'pointer',
+                        fontSize: 12,
+                        lineHeight: 1,
+                        padding: 0,
+                      }}
+                    >
+                      ×
+                    </button>
+                  </div>
+                ))}
+                {compAvailable.length > 0 && (
+                  <select
+                    data-testid="ingest-component-add"
+                    value=""
+                    onChange={(e) => {
+                      if (e.target.value) {
+                        componentsProvider.add(id, e.target.value);
+                        store.notifyIngestEdit();
+                      }
+                    }}
+                    style={{ ...NUM_STYLE, width: '100%', marginTop: 4, cursor: 'pointer' }}
+                  >
+                    <option value="">+ Add component…</option>
+                    {compAvailable.map((name) => (
+                      <option key={name} value={name}>
+                        {name}
+                      </option>
+                    ))}
+                  </select>
+                )}
+              </div>
+            );
+          })()}
+
+        {/* D4 (B2) — story picker: for a world:<id> group row whose owning
+            child adapter itself advertises `stories` (a react world, live or
+            not — see `worldGroupChildAdapter`'s doc comment), OR (B3) a
+            `kind:'component'` catalog node (`catalogNodeOwnerAdapter`). Any
+            other selection (an ordinary entity, or a world kind that never
+            sets `stories`) omits this section entirely. */}
+        {!suppressed.has('stories') && showStoriesSection && (
+          <div style={{ padding: '8px', borderTop: '1px solid #333', marginTop: 4 }}>
+            <div style={{ fontSize: 11, fontWeight: 600, color: '#9aa0a6', marginBottom: 4 }}>
+              Stories
+            </div>
+            {storyRefs.length > 0 ? (
+              <select
+                data-testid="ingest-stories-select"
+                value={adapter.stories?.active(id) ?? ''}
+                onChange={(e) => {
+                  const v = e.target.value;
+                  adapter.stories?.apply(id, v === '' ? null : v);
+                }}
+                style={{ ...NUM_STYLE, width: '100%' }}
+              >
+                <option value="">(none)</option>
+                {storyRefs.map((s) => (
+                  <option key={s.id} value={s.id}>
+                    {s.label}
+                  </option>
+                ))}
+              </select>
+            ) : (
+              <div
+                data-testid="ingest-stories-none"
+                style={{ fontSize: 11, color: '#777', fontStyle: 'italic' }}
+              >
+                No stories — this world defines no `src/ui/registry.ts` states/stories.
+              </div>
+            )}
+            {/* B3 — Isolate toggle: render ONLY this catalog component (alone,
+                against whichever story is currently selected in the dropdown
+                above) on the world's design-time layer; exiting restores the
+                entry (live preview). Session-only — mirrors the story-overlay
+                writes below, never persisted to the registry. */}
+            {isCatalogNode && (
+              <button
+                type="button"
+                data-testid="catalog-isolate"
+                onClick={() => {
+                  toggleCatalogIsolation(adapter, id, isIsolated);
+                  store.notifyIngestEdit();
+                }}
+                style={{
+                  marginTop: 6,
+                  width: '100%',
+                  padding: '6px 8px',
+                  fontSize: 12,
+                  background: isIsolated ? '#3a5' : '#2a2a2a',
+                  color: '#e6e6e6',
+                  border: '1px solid #444',
+                  borderRadius: 3,
+                  cursor: 'pointer',
+                }}
+              >
+                {isIsolated ? 'Exit isolation' : 'Isolate'}
+              </button>
+            )}
+          </div>
+        )}
+
+        {/* C2 — matched registered sections (the first-party threejs adapter's
+            rich Transform/Mesh/…/Components/AddSectionMenu, the UI adapter's
+            Layout/Style/Props/Events, or any future spec-27 contribution) —
+            rendered AFTER the generic grid above, as siblings, in
+            registration order. */}
+        {matched.map(({ Section }, i) => (
+          <Section key={i} adapter={adapter} nodeId={id} />
+        ))}
+      </div>
+    </Panel>
+  );
+}