@volter/editor-core 0.5.57

package/src/console-sync.ts

@@ -0,0 +1,131 @@
+import { type ConsoleEntry, editorConsole, installEditorConsoleCapture } from './editor-console';
+import { EDITOR_CLIENT_ID, sendControl } from './editor-presence';
+
+/**
+ * Push every console ERROR and WARNING this page sees to the server's
+ * unresolved-console ledger (`server/console-ledger.ts`).
+ *
+ * This is the page's whole obligation under the loudness convention, and it is
+ * deliberately dumb: it reports OCCURRENCE DELTAS and keeps no opinion about
+ * what matters. The page cannot be the owner of that set — it dies with the
+ * tab, and a reload wipes it — so the page's job is only to say what it saw,
+ * and the server's job is to remember.
+ *
+ * Deltas, not totals: `editorConsole` collapses consecutive identical messages
+ * onto one entry by bumping its `count`, so the ONLY faithful report of a
+ * message that fired 400 times is "+397 since I last spoke". Sending totals
+ * would make two page-loads of the same condition race each other instead of
+ * summing, and sending one message per firing would put a flood on the wire.
+ *
+ * Info-level entries are not reported. The contract is errors and warnings —
+ * the two severities that must stop an agent — and `logs/play-*.jsonl` already
+ * carries the full narrative for a run.
+ *
+ * CAPTURE AND REPORTING ARE ONE ACT — {@link installEditorConsoleReporting} —
+ * and that is why this file installs the capture rather than merely consuming
+ * it. Measured 2026-09-19 (U6b's Model-workspace walk): a boot path that
+ * called `installEditorConsoleCapture()` WITHOUT the `installConsoleSync()`
+ * line that stood next to it. So 44 React duplicate-key
+ * errors filled the page console and the bottom bar's counter while
+ * `vgai console` reported a clean session — the one outcome the loudness
+ * convention exists to prevent, arrived at by a single omitted line in a
+ * two-line sequence. Two lines a caller must remember to write together are a
+ * defect in the door, not in the caller; there is now one door, and it cannot
+ * be half-called.
+ */
+
+/** Coalescing window. A render error cascade fires dozens of entries in one
+ *  frame; they must arrive as one batch, not one request each. */
+const FLUSH_MS = 250;
+
+/**
+ * THE ONE DOOR. Capture the session's console AND report it to the server's
+ * ledger — the editor's whole obligation under the loudness convention, in one
+ * call that cannot be half-made.
+ *
+ * Every host that boots the editor calls THIS: `main.tsx`, and the fork's
+ * bridge. `installEditorConsoleCapture` alone leaves a page whose errors are
+ * visible only to somebody LOOKING at the editor, which is exactly what the
+ * convention forbids.
+ */
+export function installEditorConsoleReporting(): () => void {
+  const stopCapture = installEditorConsoleCapture();
+  const stopSync = installConsoleSync();
+  return () => {
+    stopSync();
+    stopCapture();
+  };
+}
+
+export function installConsoleSync(): () => void {
+  /** Occurrences already reported, per `editorConsole` entry id. */
+  const reported = new Map<number, number>();
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let released = false;
+
+  function collect(): Array<{
+    severity: 'error' | 'warn';
+    message: string;
+    source: string | null;
+    occurrences: number;
+  }> {
+    const batch: Array<{
+      severity: 'error' | 'warn';
+      message: string;
+      source: string | null;
+      occurrences: number;
+    }> = [];
+    const live = new Set<number>();
+    for (const entry of editorConsole.getEntries() as readonly ConsoleEntry[]) {
+      live.add(entry.id);
+      if (entry.level !== 'error' && entry.level !== 'warn') continue;
+      const already = reported.get(entry.id) ?? 0;
+      if (entry.count <= already) continue;
+      reported.set(entry.id, entry.count);
+      batch.push({
+        severity: entry.level,
+        message: entry.message,
+        source: entry.source ?? null,
+        occurrences: entry.count - already,
+      });
+    }
+    // The store is a ring buffer; an evicted entry's id can never come back
+    // (ids are monotonic), so its bookkeeping goes with it.
+    for (const id of [...reported.keys()]) if (!live.has(id)) reported.delete(id);
+    return batch;
+  }
+
+  function flush(): void {
+    timer = null;
+    if (released) return;
+    const entries = collect();
+    if (entries.length === 0) return;
+    // `_clientId` IS the page-load id the ledger fences its clearing rule on.
+    // The socket path overwrites it with the connection's own id (a tab cannot
+    // speak for another); the POST fallback has only what the page declares.
+    void sendControl('console-entries', { entries, _clientId: EDITOR_CLIENT_ID });
+  }
+
+  const unsubscribe = editorConsole.subscribe(() => {
+    if (released || timer !== null) return;
+    timer = setTimeout(flush, FLUSH_MS);
+  });
+
+  // ANNOUNCE, even with nothing to say. An empty batch is how this page tells
+  // the server it has a reporter at all, which is the fact the server needs to
+  // tell "no errors" apart from "no reporter" — the two look identical from the
+  // ledger, and U6b spent a walk inside that ambiguity. See
+  // `routes/control-plane.ts`'s `armConsoleReporterWatch`.
+  void sendControl('console-entries', { entries: [], _clientId: EDITOR_CLIENT_ID });
+  // Whatever was already captured before this installed (boot-time errors from
+  // the pre-module bootstrap and from `installEditorConsoleCapture`) is part of
+  // the session too — report it immediately rather than waiting for the next
+  // one to arrive.
+  flush();
+
+  return () => {
+    released = true;
+    if (timer !== null) clearTimeout(timer);
+    unsubscribe();
+  };
+}

package/src/constraint-helper.ts

@@ -0,0 +1,338 @@
+import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
+import { type ConstraintMark, constraintsOf } from '@volter/editor-threejs/adapter/constraint';
+import { setUserData } from '@volter/editor-threejs/ecs/user-data';
+import * as THREE from 'three';
+
+const CHAIN = new THREE.Color(0x43c6ff);
+const TARGET = new THREE.Color(0xffb84a);
+const POLE = new THREE.Color(0xd875ff);
+const ERROR = new THREE.Color(0xff4d68);
+const HOVER = new THREE.Color(0xffffff);
+
+export type ConstraintControlKind = 'target' | 'pole';
+
+/** A pickable viewport effector backed by the constraint's real hierarchy
+ * object. The helper mesh is only its editor projection; selection and
+ * transforms always go through `object`. */
+export interface ConstraintControl {
+  readonly kind: ConstraintControlKind;
+  readonly label: string;
+  readonly object: THREE.Object3D;
+  readonly mesh: THREE.Mesh;
+}
+
+interface ConstraintVisual {
+  readonly mark: ConstraintMark;
+  readonly chain: THREE.Line;
+  readonly targetLine: THREE.Line;
+  readonly poleLine: THREE.Line;
+  readonly joints: THREE.Mesh[];
+  readonly target: THREE.Mesh;
+  readonly pole: THREE.Mesh;
+  readonly targetHit: THREE.Mesh;
+  readonly poleHit: THREE.Mesh;
+  readonly positions: THREE.Vector3[];
+  readonly targetPosition: THREE.Vector3;
+  readonly polePosition: THREE.Vector3;
+}
+
+function line(color: THREE.Color): THREE.Line {
+  return new THREE.Line(
+    new THREE.BufferGeometry(),
+    new THREE.LineBasicMaterial({
+      color,
+      depthTest: false,
+      depthWrite: false,
+      transparent: true,
+      toneMapped: false,
+    }),
+  );
+}
+
+function point(geometry: THREE.BufferGeometry, color: THREE.Color): THREE.Mesh {
+  return new THREE.Mesh(
+    geometry,
+    new THREE.MeshBasicMaterial({
+      color,
+      depthTest: false,
+      depthWrite: false,
+      transparent: true,
+      toneMapped: false,
+    }),
+  );
+}
+
+function setLinePoints(target: THREE.Line, points: readonly THREE.Vector3[]): void {
+  target.visible = points.length > 1;
+  if (!target.visible) return;
+  let position = target.geometry.getAttribute('position') as THREE.BufferAttribute | undefined;
+  if (!position || position.count !== points.length) {
+    position = new THREE.Float32BufferAttribute(points.length * 3, 3);
+    target.geometry.setAttribute('position', position);
+  }
+  for (let index = 0; index < points.length; index++) {
+    position.setXYZ(index, points[index]!.x, points[index]!.y, points[index]!.z);
+  }
+  position.needsUpdate = true;
+  target.geometry.computeBoundingSphere();
+}
+
+/**
+ * Editor-owned projection of project-owned spatial constraints. It uses the
+ * real live bones and ordinary target/pole Object3Ds, but every line and point
+ * it creates stays on EDITOR_LAYER and out of the authored hierarchy.
+ */
+export class ConstraintHelper extends THREE.Group {
+  private selected = false;
+  private hoveredControl: THREE.Mesh | null = null;
+  private selectedObjects: ReadonlySet<THREE.Object3D> = new Set();
+  private visuals: ConstraintVisual[] = [];
+
+  constructor(readonly source: THREE.Object3D) {
+    super();
+    this.name = 'Constraint Helper';
+    this.renderOrder = 999;
+    setUserData(this, 'editorHelper', true);
+    setUserData(this, 'editorHelperType', 'constraints');
+    this.layers.set(EDITOR_LAYER);
+    this.refreshStructure();
+  }
+
+  setSelected(selected: boolean): void {
+    this.selected = selected;
+  }
+
+  setSelectedObjects(objects: ReadonlySet<THREE.Object3D>): void {
+    this.selectedObjects = objects;
+  }
+
+  /** The orange target and purple pole are effectors, not decorative joints.
+   * Expose only those two meshes to the viewport's editor-helper picker. */
+  controlMeshes(): THREE.Mesh[] {
+    return this.visuals.flatMap((visual) =>
+      [visual.targetHit, visual.poleHit].filter((mesh) => mesh.visible),
+    );
+  }
+
+  /** True when this helper is already the native viewport presentation for
+   * the object. Such nodes must not also receive the legacy corner-bracket
+   * fallback: the constraint lines/handle are their visible representation. */
+  presents(object: THREE.Object3D): boolean {
+    if (object === this.source) return true;
+    return this.visuals.some((visual) => {
+      const snapshot = visual.mark.getSnapshot();
+      return object === snapshot.target || object === snapshot.pole;
+    });
+  }
+
+  controlFor(mesh: THREE.Object3D): ConstraintControl | null {
+    for (const visual of this.visuals) {
+      const snapshot = visual.mark.getSnapshot();
+      if ((mesh === visual.target || mesh === visual.targetHit) && snapshot.target) {
+        return {
+          kind: 'target',
+          label: snapshot.target.name || `${visual.mark.config.label} target`,
+          object: snapshot.target,
+          mesh: visual.target,
+        };
+      }
+      if ((mesh === visual.pole || mesh === visual.poleHit) && snapshot.pole) {
+        return {
+          kind: 'pole',
+          label: snapshot.pole.name || `${visual.mark.config.label} pole`,
+          object: snapshot.pole,
+          mesh: visual.pole,
+        };
+      }
+    }
+    return null;
+  }
+
+  setHoveredControl(mesh: THREE.Mesh | null): void {
+    this.hoveredControl = mesh;
+  }
+
+  update(camera: THREE.Camera): void {
+    this.refreshStructure();
+    for (const visual of this.visuals) this.updateVisual(visual, camera);
+  }
+
+  dispose(): void {
+    this.clearVisuals();
+    this.removeFromParent();
+  }
+
+  private refreshStructure(): void {
+    const marks = constraintsOf(this.source);
+    const unchanged =
+      marks.length === this.visuals.length &&
+      marks.every((mark, index) => {
+        const snapshot = mark.getSnapshot();
+        const pointCount =
+          snapshot.chain.length > 0 ? snapshot.chain.length : snapshot.constrained ? 1 : 0;
+        return (
+          this.visuals[index]?.mark === mark && this.visuals[index]?.positions.length === pointCount
+        );
+      });
+    if (unchanged) return;
+    this.clearVisuals();
+    this.visuals = marks.map((mark) => this.makeVisual(mark));
+  }
+
+  private makeVisual(mark: ConstraintMark): ConstraintVisual {
+    const snapshot = mark.getSnapshot();
+    const points =
+      snapshot.chain.length > 0
+        ? snapshot.chain
+        : snapshot.constrained
+          ? [snapshot.constrained]
+          : [];
+    const chain = line(CHAIN);
+    const targetLine = line(TARGET);
+    const poleLine = line(POLE);
+    const joints = points.map(() => point(new THREE.SphereGeometry(0.035, 10, 7), CHAIN));
+    const target = point(new THREE.OctahedronGeometry(0.085), TARGET);
+    const pole = point(new THREE.TetrahedronGeometry(0.075), POLE);
+    // Gizmos in established editors use a larger invisible picking volume
+    // than their painted handle. Preserve the compact octahedron/tetrahedron
+    // while giving each a forgiving screen hit target that wins before model
+    // geometry behind it.
+    const hitMaterial = new THREE.MeshBasicMaterial({
+      transparent: true,
+      opacity: 0,
+      depthTest: false,
+      depthWrite: false,
+      colorWrite: false,
+    });
+    const targetHit = new THREE.Mesh(new THREE.SphereGeometry(0.16, 10, 7), hitMaterial);
+    const poleHit = new THREE.Mesh(new THREE.SphereGeometry(0.15, 10, 7), hitMaterial.clone());
+    for (const object of [
+      chain,
+      targetLine,
+      poleLine,
+      ...joints,
+      target,
+      pole,
+      targetHit,
+      poleHit,
+    ]) {
+      object.renderOrder = this.renderOrder;
+      object.layers.set(EDITOR_LAYER);
+      this.add(object);
+    }
+    return {
+      mark,
+      chain,
+      targetLine,
+      poleLine,
+      joints,
+      target,
+      pole,
+      targetHit,
+      poleHit,
+      positions: points.map(() => new THREE.Vector3()),
+      targetPosition: new THREE.Vector3(),
+      polePosition: new THREE.Vector3(),
+    };
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: each branch updates one independent handle in a compact per-frame projection.
+  private updateVisual(visual: ConstraintVisual, camera: THREE.Camera): void {
+    const snapshot = visual.mark.getSnapshot();
+    const points =
+      snapshot.chain.length > 0
+        ? snapshot.chain
+        : snapshot.constrained
+          ? [snapshot.constrained]
+          : [];
+    for (let index = 0; index < points.length; index++) {
+      points[index]!.getWorldPosition(visual.positions[index]!);
+    }
+    setLinePoints(visual.chain, visual.positions);
+    for (let index = 0; index < visual.joints.length; index++) {
+      const joint = visual.joints[index]!;
+      const position = visual.positions[index];
+      joint.visible = Boolean(position);
+      if (position) {
+        joint.position.copy(position);
+        joint.scale.setScalar(this.handleScale(camera, position));
+      }
+    }
+
+    const tip = visual.positions.at(-1);
+    const targetPosition = snapshot.target?.getWorldPosition(visual.targetPosition) ?? null;
+    const polePosition = snapshot.pole?.getWorldPosition(visual.polePosition) ?? null;
+    setLinePoints(visual.targetLine, tip && targetPosition ? [tip, targetPosition] : []);
+    setLinePoints(
+      visual.poleLine,
+      visual.positions[0] && polePosition ? [visual.positions[0], polePosition] : [],
+    );
+    visual.target.visible = targetPosition !== null;
+    if (targetPosition) {
+      visual.target.position.copy(targetPosition);
+      visual.target.scale.setScalar(
+        this.handleScale(camera, targetPosition) *
+          (this.hoveredControl === visual.target ? 1.22 : 1),
+      );
+    }
+    visual.targetHit.visible = targetPosition !== null;
+    if (targetPosition) {
+      visual.targetHit.position.copy(targetPosition);
+      visual.targetHit.scale.copy(visual.target.scale);
+    }
+    visual.pole.visible = polePosition !== null;
+    if (polePosition) {
+      visual.pole.position.copy(polePosition);
+      visual.pole.scale.setScalar(
+        this.handleScale(camera, polePosition) * (this.hoveredControl === visual.pole ? 1.22 : 1),
+      );
+    }
+    visual.poleHit.visible = polePosition !== null;
+    if (polePosition) {
+      visual.poleHit.position.copy(polePosition);
+      visual.poleHit.scale.copy(visual.pole.scale);
+    }
+
+    const failed = snapshot.status === 'error' || snapshot.status === 'unresolved';
+    const opacity = this.selected ? 1 : 0.52;
+    for (const object of [visual.chain, ...visual.joints]) {
+      const material = object.material as THREE.LineBasicMaterial | THREE.MeshBasicMaterial;
+      material.color.copy(failed ? ERROR : CHAIN);
+      material.opacity = opacity;
+    }
+    const targetActive =
+      this.hoveredControl === visual.target ||
+      (snapshot.target !== null && this.selectedObjects.has(snapshot.target));
+    const poleActive =
+      this.hoveredControl === visual.pole ||
+      (snapshot.pole !== null && this.selectedObjects.has(snapshot.pole));
+    (visual.target.material as THREE.MeshBasicMaterial).color.copy(targetActive ? HOVER : TARGET);
+    (visual.pole.material as THREE.MeshBasicMaterial).color.copy(poleActive ? HOVER : POLE);
+    (visual.targetLine.material as THREE.LineBasicMaterial).color.copy(TARGET);
+    (visual.poleLine.material as THREE.LineBasicMaterial).color.copy(POLE);
+    (visual.targetLine.material as THREE.LineBasicMaterial).opacity = opacity;
+    (visual.poleLine.material as THREE.LineBasicMaterial).opacity = opacity;
+    (visual.target.material as THREE.MeshBasicMaterial).opacity = targetActive ? 1 : opacity;
+    (visual.pole.material as THREE.MeshBasicMaterial).opacity = poleActive ? 1 : opacity;
+  }
+
+  /** Keep control points legible like ordinary editor gizmos while retaining
+   * enough world-scale variation to read depth. */
+  private handleScale(camera: THREE.Camera, position: THREE.Vector3): number {
+    return THREE.MathUtils.clamp(camera.position.distanceTo(position) / 8, 0.65, 4);
+  }
+
+  private clearVisuals(): void {
+    for (const child of [...this.children]) {
+      child.removeFromParent();
+      const renderable = child as THREE.Line | THREE.Mesh;
+      renderable.geometry.dispose();
+      const materials = Array.isArray(renderable.material)
+        ? renderable.material
+        : [renderable.material];
+      for (const material of materials) material.dispose();
+    }
+    this.visuals = [];
+    this.hoveredControl = null;
+  }
+}

package/src/content-entry-source-registry.ts

@@ -0,0 +1,184 @@
+/**
+ * A CONTENT ENTRY IS SOURCED, NOT DERIVED — the fourth registry in the family
+ * of `workspace-document-restore.ts` (a kind owns its persisted state),
+ * `document-open-registry.ts` (a kind owns how it opens) and
+ * `chrome-slot-registry.ts` (the host owns the place, a package owns what sits
+ * there). Here: the host owns the Content SCOPE — the grid, the chips, the
+ * sort, the search, the selection and the drag — and a package owns WHY a
+ * project component is content at all, what it looks like, and what opening it
+ * means.
+ *
+ * WHY IT EXISTS. The Content scope of `components/AssetBrowser.tsx` already
+ * concatenates two sources it does not own: the active adapter facet's
+ * document entries and `liveAuthoringAssets(adapter)`. A THIRD was hard-wired
+ * — `pickComponentPreviewStory` decided which components were content and
+ * `StoryComponentThumbnail` painted them — which made the host's Content
+ * browser know what portable CSF is, and dragged the story registry (and
+ * therefore Storybook) into every editor boot, a `models` build that authors
+ * no stories included (WORK.md §Stories leave the host, edge 1 — the ONE new
+ * door that design mints). The shape is transcribed from
+ * `chrome-slot-registry.ts`: register / list / subscribe / version, with the
+ * same owner-replaces-owner rule for an HMR re-evaluation.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER. A build whose package list carries no
+ * content source lists documents and assets and no component tiles — the same
+ * honest emptiness a document kind with no registered opener gives.
+ *
+ * WHAT THE HOST STILL OWNS, and why it is not a leak: the COMPONENT INDEX
+ * (`services.listProjectComponents()`, the server's own scan) is the host's,
+ * and it is handed to every source as context. A source answers "which of
+ * these, and why" — it never rescans the project.
+ */
+
+import type { AdapterSurface } from '@volter/editor-project/adapter';
+import type { ComponentType } from 'react';
+import type { ProjectComponentEntry } from './asset-workflow/project-content';
+import type { WorkspaceStateStore } from './workspace-document-restore';
+
+/**
+ * A component as a SOURCE sees it: what it is called, where its module is,
+ * which surface it mounts on. Deliberately narrower than the host's own index
+ * row (`ProjectComponentEntry`, which is assignable to it), because the other
+ * caller of this registry has exactly these three facts and no index: the
+ * Inspector, asking for the picture of ONE component.
+ */
+export interface ContentComponentRef {
+  readonly name: string;
+  readonly path: string;
+  readonly surface: ProjectComponentEntry['surface'];
+}
+
+/** What a source is asked ABOUT: components, and the surface the question is
+ *  focused on (`null` = no active authoring surface, so nothing is filtered
+ *  out by surface). The Content scope passes its whole index; the Inspector
+ *  passes one. */
+export interface ContentEntrySourceContext {
+  readonly components: readonly ContentComponentRef[];
+  readonly surface: AdapterSurface | null;
+}
+
+/** One admitted component. `detail` is the source's own reason — opaque to the
+ *  host, handed back to the source's `Thumbnail` and `open`. */
+export interface ContentEntry {
+  /** Unique within the source; the host keys its row on `<source>:<id>`. */
+  readonly id: string;
+  /** The component this entry depicts — the very ref the source was given. */
+  readonly component: ContentComponentRef;
+  /** The source's own reason, opaque by construction: only the source that
+   *  minted the entry ever reads it, and it casts. */
+  readonly detail: unknown;
+}
+
+export interface ContentEntryThumbnailProps {
+  readonly entry: ContentEntry;
+  /** Bumped by the panel when a preview must be re-taken. */
+  readonly previewRevision: number;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+export interface ContentEntrySource {
+  /** The source's id, in its own vocabulary. Part of every row key. */
+  readonly id: string;
+  /** Which module registered it. Re-registering the same owner+id REPLACES,
+   *  so an HMR re-evaluation leaves one source, not two. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  readonly entries: (context: ContentEntrySourceContext) => readonly ContentEntry[];
+  /** The source's OWN change signal — its ledger settling, a discovery pass
+   *  finishing. The panel re-reads on it without knowing what moved. */
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Paints the tile. A stable component type (not a closure per entry), so
+   *  the grid re-renders rather than remounting every preview. */
+  readonly Thumbnail: ComponentType<ContentEntryThumbnailProps>;
+  /** Double-click: open whatever this entry's subject opens as. */
+  readonly open: (store: WorkspaceStateStore, entry: ContentEntry, title: string) => void;
+}
+
+const _sources: ContentEntrySource[] = [];
+const listeners = new Set<() => void>();
+/** Live teardowns for the per-source subscriptions the registry re-fans. */
+const sourceSubscriptions = new Map<ContentEntrySource, () => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a source. Returns the teardown. */
+export function registerContentEntrySource(source: ContentEntrySource): () => void {
+  const stale = _sources.findIndex((item) => item.owner === source.owner && item.id === source.id);
+  if (stale >= 0) {
+    const [removed] = _sources.splice(stale, 1);
+    if (removed) {
+      sourceSubscriptions.get(removed)?.();
+      sourceSubscriptions.delete(removed);
+    }
+  }
+  _sources.push(source);
+  _sources.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  sourceSubscriptions.set(source, source.subscribe(publish));
+  publish();
+  return () => {
+    const at = _sources.indexOf(source);
+    if (at < 0) return;
+    _sources.splice(at, 1);
+    sourceSubscriptions.get(source)?.();
+    sourceSubscriptions.delete(source);
+    publish();
+  };
+}
+
+const EMPTY: readonly ContentEntrySource[] = [];
+
+/** Everything registered, in order. A stable array per version, so it is a
+ *  safe `useSyncExternalStore` snapshot. */
+export function contentEntrySources(): readonly ContentEntrySource[] {
+  return _sources.length === 0 ? EMPTY : _sources;
+}
+
+/** ONE subscription for the panel: the registry's own changes AND every
+ *  registered source's. What changed is never the panel's question. */
+export function subscribeContentEntrySources(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function contentEntrySourceRegistryVersion(): number {
+  return version;
+}
+
+/**
+ * THE SAME QUESTION, ABOUT ONE COMPONENT: the first registered source that
+ * admits it, and the entry it minted — what the INSPECTOR asks when it wants a
+ * picture of a component it cannot photograph natively (a canvas entity with
+ * no Object3D, a selected component-backed asset).
+ *
+ * It is deliberately not a second door. "Is this component content, and what
+ * does it look like?" is one question; the Content grid asks it of the whole
+ * index and the Inspector of a single ref, and both take back the same
+ * `{ source, entry }` pair to paint with `source.Thumbnail`.
+ */
+export function contentEntryForComponent(
+  component: ContentComponentRef,
+): { readonly source: ContentEntrySource; readonly entry: ContentEntry } | null {
+  for (const source of _sources) {
+    // Surface `null`: the Inspector is asking about THIS component, not about
+    // what belongs on the surface currently in focus.
+    const entry = source.entries({ components: [component], surface: null })[0];
+    if (entry) return { source, entry };
+  }
+  return null;
+}
+
+/** Test-only reset (mirrors the restore, open and chrome-slot registries'). */
+export function __resetContentEntrySourcesForTest(): void {
+  for (const stop of sourceSubscriptions.values()) stop();
+  sourceSubscriptions.clear();
+  _sources.length = 0;
+  publish();
+}