@volter/editor-core 0.5.57

package/src/authoring/instance-source-menu.ts

@@ -0,0 +1,135 @@
+/**
+ * H3 wiring — the instance row's two source actions, registered through the
+ * hierarchy contribution seam.
+ *
+ * This is the "adapter-module registration" half of the split
+ * `hierarchy-menu-registry.ts` describes: `GameHierarchy` stays contract-only
+ * and never learns that an R3F world has a callsite; THIS module is the one
+ * allowed to resolve the owning child adapter and probe it for source
+ * accessors. The sentences and the applicability rule are pure and live in
+ * `../instance-source-actions.ts`.
+ *
+ * ISOLATE IS DELIBERATELY ABSENT — see {@link enterInstanceRow}. The design
+ * record's "double-click = Isolate, reusing the catalog nodes' existing Isolate
+ * mount" is not reachable from a scene instance row, and faking it was
+ * explicitly out of scope.
+ */
+
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import type { EditorShellStore } from '../editor-shell-store';
+import { registerHierarchyMenuItems } from '../hierarchy-menu-registry';
+import {
+  INSTANCE_SOURCE_LABELS,
+  type InstanceSourceLocator,
+  type InstanceSourceTarget,
+  instanceSourceTargets,
+  runInstanceSourceAction,
+} from '../instance-source-actions';
+import { showTransientHint } from '../transient-hint';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { enterSelectionScope } from './selection-scope';
+
+/**
+ * The adapter whose source accessors answer for `nodeId`. Ownership is asked
+ * of the composite (`ownerOf`/`childAdapters`, the same public T0 query
+ * `GameHierarchy`'s own gates use) rather than decoded from the id — a
+ * composite's routers would otherwise answer for a row their owning child
+ * knows nothing about.
+ */
+export function instanceSourceLocatorFor(
+  adapter: AuthoringAdapter,
+  nodeId: string,
+): InstanceSourceLocator | null {
+  const owner =
+    adapter instanceof CompositeAuthoringAdapter
+      ? (adapter.childAdapters().find((c) => c.worldId === adapter.ownerOf(nodeId))?.adapter ??
+        adapter)
+      : adapter;
+  const locator = owner as unknown as InstanceSourceLocator;
+  return typeof locator.sourceLocation === 'function' ||
+    typeof locator.definitionLocation === 'function'
+    ? locator
+    : null;
+}
+
+/** Run one target and SAY what happened — every path returns a sentence
+ *  (copied / not in the index / clipboard refused), so no click is silent. */
+function runAndReport(
+  locator: InstanceSourceLocator | null,
+  nodeId: string,
+  target: InstanceSourceTarget,
+): void {
+  void runInstanceSourceAction(locator, nodeId, target).then(showTransientHint);
+}
+
+/**
+ * Double-click on an instance row.
+ *
+ * An instance row is already the native authoring subject; portable CSF
+ * selects complete design-time states and does not provide a second subtree
+ * isolation protocol. Double-click therefore ENTERS the instance's scope and
+ * falls back to its callsite when the row cannot be entered.
+ *
+ * That fallback is the COMMON case, not the corner one: `projectedChildren`
+ * collapses everything an instance rendered itself (same `authoringInstance`),
+ * so an instance row has children only when it contains a NESTED instance.
+ * Every other instance row is a hierarchy leaf, `enterSelectionScope` refuses
+ * it for having no children, and until now that double-click did nothing at
+ * all — the silent no-op this whole decision exists to kill.
+ *
+ * Rename is NOT in conflict: `Row`'s `onDoubleClick` already routes every
+ * `component`/`instance`/`boundary` row here BEFORE its rename branch, so an
+ * instance row has never started a rename on double-click; rename stays
+ * reachable on the context menu, where it is always offered for a non-group row.
+ */
+export function enterInstanceRow(adapter: AuthoringAdapter, nodeId: string): void {
+  if (enterSelectionScope(adapter, nodeId)) return;
+  runCallsite(adapter, nodeId);
+}
+
+function runCallsite(adapter: AuthoringAdapter, nodeId: string): void {
+  const node = adapter.hierarchy.node(nodeId);
+  const locator = instanceSourceLocatorFor(adapter, nodeId);
+  // Only a row that ADVERTISES a callsite falls through to the source action —
+  // a boundary/placeholder row with nothing to open keeps double-clicking to
+  // nothing, exactly as before, rather than raising a hint the user did not ask
+  // for by picking a source verb.
+  if (!instanceSourceTargets(node, locator, nodeId).includes('callsite')) return;
+  runAndReport(locator, nodeId, 'callsite');
+}
+
+let unregister: (() => void) | null = null;
+
+/** Idempotent install of the two H3 items (see the register module). */
+export function ensureInstanceSourceMenuRegistered(): void {
+  if (unregister) return;
+  unregister = registerHierarchyMenuItems(
+    ({ nodeId, store }) => targetsFor(store, nodeId).length > 0,
+    ({ nodeId, store }) => {
+      const adapter = getActiveAuthoring(store);
+      const locator = instanceSourceLocatorFor(adapter, nodeId);
+      return targetsFor(store, nodeId).map((target) => ({
+        label: INSTANCE_SOURCE_LABELS[target],
+        action: () => {
+          runAndReport(locator, nodeId, target);
+        },
+      }));
+    },
+  );
+}
+
+function targetsFor(store: EditorShellStore, nodeId: string): InstanceSourceTarget[] {
+  const adapter = getActiveAuthoring(store);
+  return instanceSourceTargets(
+    adapter.hierarchy.node(nodeId),
+    instanceSourceLocatorFor(adapter, nodeId),
+    nodeId,
+  );
+}
+
+/** Test-only: drop the registration so a suite can reset the shared registry. */
+export function __unregisterInstanceSourceMenuForTest(): void {
+  unregister?.();
+  unregister = null;
+}

package/src/authoring/layered-pick.ts

@@ -0,0 +1,183 @@
+/**
+ * Layered viewport picking (B4, D12) — "click anything you can see; topmost
+ * visible layer wins." Shell POLICY over the composite's public seams, kept a
+ * separate module (rather than living inline in `editor-viewport.ts`) so it
+ * stays lean AND unit-testable with plain fake adapters — no real DOM/canvas
+ * needed.
+ *
+ * This module speaks ONLY the public contract: `CompositeAuthoringAdapter
+ * .childAdapters()` (T0), the `AuthoringAdapter.pickable` provider (D12,
+ * `@volter/editor-project/adapter`), and `world-session-state.ts`'s session toggles. It never
+ * reaches into any one child adapter's own private, format-specific model (no
+ * concrete-world-shape vocabulary of any kind here) — `instanceof
+ * CompositeAuthoringAdapter` is the ONE sanctioned type check (that class's
+ * own doc comment blesses exactly this use, mirroring
+ * `authoring/first-party-inspector/is-first-party-selection.ts`'s identical
+ * precedent).
+ *
+ * Walk order: the composite's NON-threejs children (react/pixi design-time
+ * layers), topmost-first by (install-time) manifest zOrder — `stackOrder`
+ * sorts bottom-to-top, so `.reverse()` gives topmost-first while preserving
+ * its own tie-break rule. The Three world is appended LAST
+ * (canvas-bottom) regardless of its manifest zOrder — it always renders
+ * beneath every positioned design-time layer (`design-time-layers.ts`'s own
+ * doc comment: "the three canvas keeps its existing slot"), so it is
+ * correct for it to lose every pick to a layer that also claims the point.
+ *
+ * A layer that is eye-hidden or pick-locked (`world-session-state.ts`, B1) is
+ * skipped ENTIRELY — its `pickable.pick` is never even called. This is a
+ * SEPARATE mechanism from a layer's `interactive` toggle: an interactive
+ * layer's DOM has `pointer-events: auto`, so a real pointer event lands on the
+ * layer's own element and this walk (triggered only by the CANVAS's own
+ * `pointerup` listener) never runs at all for that event — mutually exclusive
+ * by construction, no code needed here for it.
+ *
+ * When the active adapter is NOT a composite (single-world project, or a
+ * non-composite override), this degrades to that one adapter's own
+ * `pickable.pick` (or `null` if it doesn't have one) — today's single-world
+ * behavior, unchanged.
+ */
+
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import { stackOrder } from '@volter/editor-project/adapter/root-stacking';
+import type { EditorShellStore } from '../editor-shell-store';
+import { SCENE_DOCUMENT_ID } from '../workspace-document-ids';
+import { activeWorkspaceDocumentId } from '../workspace-document-registry';
+import { getActiveAuthoring } from './active-adapter';
+import { CompositeAuthoringAdapter } from './composite-authoring-adapter';
+import { currentSelectionScopeId } from './selection-scope';
+import { isRootHidden, isRootPickLocked } from './world-session-state';
+
+export function resolveAdapterPick(
+  adapter: AuthoringAdapter,
+  clientX: number,
+  clientY: number,
+  intent: 'normal' | 'deep',
+): string | null {
+  const raw = adapter.pickable?.pick(clientX, clientY) ?? null;
+  if (!raw) return null;
+  return (
+    adapter.selection?.resolve?.(raw, {
+      intent,
+      scopeId: currentSelectionScopeId(),
+    })?.id ?? raw
+  );
+}
+
+function resolveAdapterCandidates(
+  adapter: AuthoringAdapter,
+  clientX: number,
+  clientY: number,
+  intent: 'normal' | 'deep',
+): string[] {
+  const raw = adapter.pickable?.candidates?.(clientX, clientY) ?? [];
+  const resolved: string[] = [];
+  const seen = new Set<string>();
+  for (const id of raw) {
+    const candidate =
+      adapter.selection?.resolve?.(id, {
+        intent,
+        scopeId: currentSelectionScopeId(),
+      })?.id ?? id;
+    if (!seen.has(candidate)) {
+      seen.add(candidate);
+      resolved.push(candidate);
+    }
+  }
+  return resolved;
+}
+
+/** Topmost-first pick across every visible, pick-unlocked layer of the active
+ *  (possibly composite) authoring adapter. Returns the winning node id, or
+ *  `null` when nothing under `(clientX, clientY)` claims the point. */
+export function pickTopmost(
+  store: EditorShellStore,
+  clientX: number,
+  clientY: number,
+  options: { intent?: 'normal' | 'deep' } = {},
+): string | null {
+  const intent = options.intent ?? 'normal';
+  const active = getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) {
+    return resolveAdapterPick(active, clientX, clientY, intent);
+  }
+
+  const children = active.childAdapters();
+  // The Game document stays mounted warm while Scene is active. Its DOM rects
+  // therefore still exist even though it is not painted. Document ownership,
+  // not mount lifetime, decides which layers may claim the pointer.
+  const sceneDocumentActive = activeWorkspaceDocumentId() === SCENE_DOCUMENT_ID;
+  const layered = sceneDocumentActive ? [] : children.filter((c) => c.kind !== 'three');
+  const three = children.filter((c) => c.kind === 'three');
+
+  // `stackOrder` wants `{id, zOrder}` (`ClaimEntry`) — reuse `worldId` as its
+  // `id` (this walk has no separate id vocabulary of its own).
+  const layeredClaims = layered.map((c) => ({
+    id: c.worldId,
+    zOrder: c.zOrder,
+    worldId: c.worldId,
+    adapter: c.adapter,
+  }));
+
+  // Topmost-first: `stackOrder` is bottom-to-top (ascending zOrder, ties by
+  // original array order) — `.reverse()` flips it without disturbing its own
+  // tie-break rule (a later-declared same-zOrder layer still wins the tie,
+  // now by being checked FIRST instead of sorting last).
+  const order: Array<{ worldId: string; adapter: AuthoringAdapter }> = [
+    ...stackOrder(layeredClaims).reverse(),
+    // The Three world paints/picks LAST — canvas-bottom, regardless
+    // of its own manifest zOrder (see module doc comment).
+    ...three,
+  ];
+
+  for (const { worldId, adapter } of order) {
+    if (isRootHidden(worldId) || isRootPickLocked(worldId)) continue;
+    const hit = resolveAdapterPick(adapter, clientX, clientY, intent);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/** Ordered overlap stack across the same visible layers as {@link pickTopmost}. */
+export function pickCandidates(
+  store: EditorShellStore,
+  clientX: number,
+  clientY: number,
+  options: { intent?: 'normal' | 'deep'; adapter?: AuthoringAdapter } = {},
+): string[] {
+  const intent = options.intent ?? 'normal';
+  const active = options.adapter ?? getActiveAuthoring(store);
+  if (!(active instanceof CompositeAuthoringAdapter)) {
+    const candidates = resolveAdapterCandidates(active, clientX, clientY, intent);
+    const fallback = resolveAdapterPick(active, clientX, clientY, intent);
+    return candidates.length > 0 ? candidates : fallback ? [fallback] : [];
+  }
+
+  const children = active.childAdapters();
+  const sceneDocumentActive = activeWorkspaceDocumentId() === SCENE_DOCUMENT_ID;
+  const layered = sceneDocumentActive ? [] : children.filter((child) => child.kind !== 'three');
+  const three = children.filter((child) => child.kind === 'three');
+  const layeredClaims = layered.map((child) => ({
+    id: child.worldId,
+    zOrder: child.zOrder,
+    worldId: child.worldId,
+    adapter: child.adapter,
+  }));
+  const order: Array<{ worldId: string; adapter: AuthoringAdapter }> = [
+    ...stackOrder(layeredClaims).reverse(),
+    ...three,
+  ];
+  const result: string[] = [];
+  const seen = new Set<string>();
+  for (const { worldId, adapter } of order) {
+    if (isRootHidden(worldId) || isRootPickLocked(worldId)) continue;
+    const candidates = resolveAdapterCandidates(adapter, clientX, clientY, intent);
+    const fallback = resolveAdapterPick(adapter, clientX, clientY, intent);
+    for (const id of candidates.length > 0 ? candidates : fallback ? [fallback] : []) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      result.push(id);
+    }
+  }
+  return result;
+}

package/src/authoring/live-gesture-lock.ts

@@ -0,0 +1,50 @@
+/**
+ * "A continuous viewport gesture is happening right now" — the one fact the
+ * absorb-by-remount cycle needs from the gizmo.
+ *
+ * A source write remounts the world; a drag that is STILL RUNNING when the
+ * swap lands moves old-scene objects, and the adopted scene snaps them back
+ * to the written values — a human moving a three-cube selection "bit by bit"
+ * watched one member stay behind on every quick successive drag (runhuman
+ * passes 49/54, both ranked it their #1 fix). The design session builds the
+ * new world in parallel but awaits {@link whenLiveGestureIdle} before the
+ * swap, so a drag always completes on the objects it started on.
+ *
+ * Deliberately module-scoped and frameworkless: the setter is the viewport's
+ * `dragging-changed` handler and the consumer is the design session — no
+ * React context reaches both.
+ */
+
+let active = 0;
+let waiters: Array<() => void> = [];
+
+export function beginLiveGesture(): void {
+  active += 1;
+}
+
+export function endLiveGesture(): void {
+  active = Math.max(0, active - 1);
+  if (active === 0) {
+    const resolved = waiters;
+    waiters = [];
+    for (const resolve of resolved) resolve();
+  }
+}
+
+/** Whether any gesture (a drag, or a gesture's still-landing write) holds
+ *  the lock right now — the swap's settle loop re-checks this after each
+ *  wait, because a lock taken in the same task that released the previous
+ *  one can race a waiter that already resolved. */
+export function liveGestureActive(): boolean {
+  return active > 0;
+}
+
+/** Resolves immediately when no gesture is running, else on the current
+ *  gesture's end. */
+export function whenLiveGestureIdle(): Promise<void> {
+  return active === 0
+    ? Promise.resolve()
+    : new Promise((resolve) => {
+        waiters.push(resolve);
+      });
+}

package/src/authoring/live-object-transform.ts

@@ -0,0 +1,62 @@
+/**
+ * Reading the transform of a LIVE `Object3D` the editor did not write.
+ *
+ * THE TRAP, measured on the racing-game ingest (2026-08-15). A physics library
+ * that drives a node writes the node's MATRIX and turns matrix composition off:
+ * `@react-three/cannon`'s frame handler is literally
+ * `object.matrixAutoUpdate = false; object.matrix.copy(m)`. Three never
+ * decomposes that back, so `object.position`/`.quaternion`/`.scale` keep
+ * whatever they held when the body was created — forever. Everything derived
+ * from `matrixWorld` (selection brackets, bounds, three's own
+ * `TransformControls`) tracks the truth, while everything derived from
+ * `.position` shows the spawn point. Measured side by side: the driven chassis
+ * reported `[-110, 0.75, 220]` in the Inspector while the game's own state
+ * provider put it at `(-24.5, 0.85, 186.2)`.
+ *
+ * That mismatch is worse than a wrong number: origin markers and gizmo anchors
+ * derived from `.position` sit somewhere the object is not, while the bounding
+ * box around them is correct, so the editor contradicts itself on screen.
+ *
+ * THE RULE: **when a node owns its own matrix (`matrixAutoUpdate === false`),
+ * the MATRIX is the transform.** Decompose it — through three's own
+ * `Matrix4.decompose`, never a re-derivation. Otherwise the vector fields are
+ * authoritative and are read directly: deliberately not "always decompose",
+ * because for an ordinary node `matrix` is one frame BEHIND a write the editor
+ * just made, and reading it back would make a gizmo drag stutter.
+ *
+ * Nothing here is library-specific: the predicate is three's own flag, so any
+ * driver following the same convention (cannon, a custom integrator, an
+ * animation system baking matrices) is covered without naming it.
+ */
+
+import * as THREE from 'three';
+
+export interface LocalTransformRead {
+  readonly position: [number, number, number];
+  readonly quaternion: [number, number, number, number];
+  readonly scale: [number, number, number];
+}
+
+const _position = new THREE.Vector3();
+const _quaternion = new THREE.Quaternion();
+const _scale = new THREE.Vector3();
+
+/**
+ * The node's LOCAL transform, from whichever of the two representations it
+ * actually maintains.
+ */
+export function localTransformOf(object: THREE.Object3D): LocalTransformRead {
+  if (object.matrixAutoUpdate === false) {
+    object.matrix.decompose(_position, _quaternion, _scale);
+    return {
+      position: _position.toArray() as [number, number, number],
+      quaternion: _quaternion.toArray() as [number, number, number, number],
+      scale: _scale.toArray() as [number, number, number],
+    };
+  }
+  return {
+    position: object.position.toArray() as [number, number, number],
+    quaternion: object.quaternion.toArray() as [number, number, number, number],
+    scale: object.scale.toArray() as [number, number, number],
+  };
+}

package/src/authoring/mount-failure-report.ts

@@ -0,0 +1,154 @@
+/**
+ * Mount-failure report — D-W3: every manifest world's auto-launch route
+ * degrades to exactly one `editorConsole.error` line today (§0.4 — ground
+ * truth: the default Untitled scene is already showing by the time a manifest
+ * route fails, so a broken world mounts to what LOOKS like a normal empty
+ * project). This module is the structured half of the fix: a global mount-
+ * failure slot every manifest-route catch block populates.
+ *
+ * WHERE IT SHOWS — there is ONE error home, the editor's bottom surface, and
+ * this slot rides it rather than owning a surface of its own:
+ *
+ *   1. the `editorConsole.error` line each route already writes (the full
+ *      trace lives there, and the status bar's `console-counts` counts it);
+ *   2. the status bar's `mount-failure` contribution
+ *      (`../components/status-contributions.tsx`) — a sticky, danger-toned
+ *      "N worlds failed to mount" item that names each world in its title and
+ *      opens the Console on click. Sticky is the point: a dead world stays
+ *      dead until it is fixed, so unlike a transient hint this item persists
+ *      until the slot clears;
+ *   3. the Console utility is REVEALED on the empty→failing edge
+ *      (`../workspace-utility-commands.ts`'s auto-open policy, the same one a
+ *      failed build uses) — that reveal is what makes a mount failure loud
+ *      without a second surface, and it is why the Console not being the
+ *      default bottom tab is no longer an argument for one.
+ *
+ * A separate top-of-shell banner used to render this slot. It was a SECOND
+ * error home — users had to learn two places to look — and it is gone.
+ *
+ * D-V5 (composite): a composite manifest (one ingest world + siblings,
+ * `ingest-siblings.ts`) can fail SEVERAL roots independently in one mount
+ * attempt (a `default-three` sibling, a throwing `default-react` sibling, …)
+ * — a single-slot "last failure wins" model would silently drop every failure
+ * but the latest, the exact F9 anti-pattern this module exists to close. The
+ * slot is an ORDERED LIST: `addMountFailureReport` (deduped by `worldId` — a
+ * re-attempt for the SAME world replaces that world's entry in place, keeping
+ * list order stable), `getMountFailureReports()`,
+ * `clearMountFailureReports()`.
+ *
+ * The slot owns its own `subscribe` (same shape as
+ * `../asset-workflow/asset-materialization-report.ts`) rather than
+ * piggybacking on `EditorShellStore.subscribe`: the readers are no longer
+ * mounted inside a store-subscribed panel, and the per-world clears
+ * (`clearMountFailureReport`) run from root-level lifecycles that do not all
+ * broadcast a store notification. `getMountFailureReports()` returns a frozen
+ * snapshot whose identity changes only when the list does, so it is a valid
+ * `useSyncExternalStore` getSnapshot.
+ */
+
+/** One manifest world's mount failure — the exact fields the status item shows. */
+export interface MountFailureReport {
+  /** The failing world's manifest id (`ResolvedAdapterRoot.id`), or the
+   *  vendored/fixture route's discovered game/folder id. */
+  readonly worldId: string;
+  /** The world's render substrate kind (`ResolvedAdapterRoot.kind`, e.g.
+   *  `'three'`/`'canvas'`/`'react'`) — or, for the URL-fallback route
+   *  (which has no `ResolvedAdapterRoot` to read a kind from), the same
+   *  vocabulary inferred from which fixture glob resolved the id. */
+  readonly kind: string;
+  /** The resolved adapter identity (`ResolvedAdapter['identity']` — e.g.
+   *  `'ingest-three'`/`'ingest-pixi'`/`'ingest-react'`/`'module'`). */
+  readonly identity: string;
+  /** The caught error's message — never the raw `Error` object (never
+   *  fabricated; empty only if the thrown value truly stringifies empty). */
+  readonly message: string;
+}
+
+/** D-V5: an ORDERED list now backs the slot (insertion order — the order
+ *  roots actually failed in, which for a composite's sibling loop is
+ *  manifest order). Every accessor below is a thin view over this same
+ *  array — never a second, parallel source of truth. Replaced wholesale
+ *  rather than mutated so the snapshot identity is a real change signal. */
+let _reports: readonly MountFailureReport[] = [];
+const _listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const listener of _listeners) listener();
+}
+
+/** `useSyncExternalStore`-compatible subscribe for the status contribution
+ *  and the Console auto-open policy. */
+export function subscribeToMountFailures(callback: () => void): () => void {
+  _listeners.add(callback);
+  return () => {
+    _listeners.delete(callback);
+  };
+}
+
+/**
+ * D-V5: append one world's failure, deduped by `worldId` — a re-attempt for
+ * a world that already has an entry REPLACES it in place (keeps list order
+ * stable: retrying world B in `[A, B]` yields `[A, B']`, never `[A, B]` moved
+ * to the end).
+ */
+export function addMountFailureReport(report: MountFailureReport): void {
+  const index = _reports.findIndex((r) => r.worldId === report.worldId);
+  if (index === -1) {
+    _reports = [..._reports, report];
+  } else {
+    const next = [..._reports];
+    next[index] = report;
+    _reports = next;
+  }
+  notify();
+}
+
+/** D-V5: every mount failure from the current attempt, oldest first. */
+export function getMountFailureReports(): readonly MountFailureReport[] {
+  return _reports;
+}
+
+/** Drop every recorded failure — what a successful mount (or a torn-down
+ *  session, which has nothing left to report) calls. */
+export function clearMountFailureReports(): void {
+  if (_reports.length === 0) return;
+  _reports = [];
+  notify();
+}
+
+/**
+ * PD-1: drop ONE world's recorded failure — what a route that mounts a single
+ * world calls after that world mounts successfully.
+ *
+ * `clearMountFailureReports()` above is the whole-attempt reset an ingest/
+ * module route can afford because it owns the entire mount. The R3F design
+ * session and the design-time layer loop do NOT: they mount roots
+ * independently, so a blanket clear on one root's success would erase a
+ * SIBLING root's still-true failure — the exact D-V5 drop the ordered list
+ * exists to prevent. Keyed by the same `worldId` `addMountFailureReport`
+ * dedupes on, and a no-op when that world has no entry.
+ *
+ * Not clearing at all is what PD-1 measured: an R3F world that failed to mount
+ * once kept reporting that failure through `vgai status`'s "MOUNT FAILED —
+ * THIS WORLD IS NOT RUNNING" line (and the in-editor surface) for the rest of
+ * the page's life, including while the very same world was mounted and
+ * PLAYING. A diagnostic that cannot go back to healthy is worse than none.
+ */
+export function clearMountFailureReport(worldId: string): void {
+  const index = _reports.findIndex((r) => r.worldId === worldId);
+  if (index === -1) return;
+  _reports = _reports.filter((_, i) => i !== index);
+  notify();
+}
+
+/**
+ * Build a `MountFailureReport['message']` from a caught value the same way
+ * every route's existing `editorConsole.error` line already stringifies it
+ * (`` `...failed: ${err}` `` — kept byte-for-byte at each call site so the
+ * console's full trace is unchanged) — an `Error`'s own `.message` reads
+ * better in a one-line summary than its `String(err)` form (`"Error: <msg>"`),
+ * so the report uses this instead of the console's template-literal form.
+ */
+export function formatMountFailureMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}