@volter/editor-core 0.5.57

package/src/viewport-authoring-policy.ts

@@ -0,0 +1,186 @@
+/**
+ * WHAT THE GIZMO VIEWPORT ASKS THE SHELL — the one collaborator
+ * `editor-viewport.ts` declares and the shell installs at boot.
+ *
+ * ARCHITECTURE-CORE §Editor chrome, "The viewport stack is separable": a
+ * surface below the shell never imports the shell's transport, a world
+ * authoring adapter, or project discovery. The viewport was importing six
+ * `authoring/` modules to ask four questions —
+ *
+ *   · which adapter am I driving, and which one do the shared panels drive?
+ *   · what is under the pointer?
+ *   · which native root owns the current selection, and is it painted here?
+ *   · which three root is world-hidden, and how do I apply that?
+ *
+ * — and every one of those answers is a COMPOSITE fact. `layered-pick.ts`
+ * walks `CompositeAuthoringAdapter.childAdapters()` in manifest z-order;
+ * `panel-authoring.ts` reaches the workspace-document registry;
+ * `world-hidden-viewport.ts` and `viewport-tool-context.ts` resolve the
+ * composite's live three child. The viewport itself knows about none of that:
+ * it raycasts a scene and drags a gizmo. Measured, those six edges were 96 of
+ * its 193 files.
+ *
+ * ## The default is the NO-SHELL answer, and it is deliberate
+ *
+ * {@link DEFAULT_VIEWPORT_AUTHORING_POLICY} is what a viewport mounted with no
+ * shell above it (a bounded host; a fixture) gets: no composite exists,
+ * so there are no layers to walk, no other panel to agree with, no world-group
+ * eye to honour. Each default states that outright rather than half-answering.
+ * The ONE default that is real logic is {@link adapterOnlyToolOwner} — the
+ * structural single-adapter fallback `resolveViewportToolContext` already used
+ * for non-composite adapters, which lives here now and is imported BACK by
+ * `authoring/viewport-tool-context.ts` so there is one copy of it.
+ *
+ * In the editor the shell policy is installed once by `EditorProvider`
+ * (`EditorContext.tsx`), before any viewport mounts — including the Asset Lab
+ * document's own, which is why that document keeps today's behaviour exactly.
+ * The install site is the PROVIDER rather than `the world root's stage` because a
+ * workspace can have an Asset Lab document open with no scene the world root's stage
+ * mounted at all, and that document's viewport must not silently fall to the
+ * defaults.
+ */
+
+import type { AuthoringAdapter } from '@volter/editor-project/adapter';
+import type * as THREE from 'three';
+import { makeNoAuthoringAdapter } from './authoring/no-authoring-adapter';
+import type { EditorShellStore } from './editor-shell-store';
+
+/**
+ * The native root whose viewport tools may claim the current selection, as far
+ * as the viewport cares: its KIND (only `three` lets the 3D chrome claim the
+ * surface) and its manifest root id (`null` for a single-adapter session).
+ *
+ * `authoring/viewport-tool-context.ts`'s `ViewportToolContext` is this plus the
+ * adapter, and is structurally assignable to it.
+ */
+export interface ViewportToolOwner {
+  readonly worldId: string | null;
+  readonly kind: string;
+}
+
+export interface ViewportAuthoringPolicy {
+  /** The adapter this viewport drives when its host injected none. */
+  activeAuthoring(store: EditorShellStore): AuthoringAdapter;
+  /**
+   * The adapter a selection SCOPE is keyed on — the Hierarchy's own resolution,
+   * so a viewport drill-in and the panel breadcrumb name the same scope.
+   */
+  panelAuthoring(store: EditorShellStore): AuthoringAdapter;
+  /** Topmost-first hit test across every visible, pick-unlocked layer. */
+  pick(
+    store: EditorShellStore,
+    clientX: number,
+    clientY: number,
+    intent: 'normal' | 'deep',
+  ): string | null;
+  /** Which native root the selection resolves to, or `null` for empty,
+   *  organizational and cross-root selections. */
+  toolOwner(adapter: AuthoringAdapter, selectedIds: Iterable<string>): ViewportToolOwner | null;
+  /** Is that owner's surface actually PAINTED in this viewport right now? */
+  toolOwnerPainted(store: EditorShellStore, owner: ViewportToolOwner | null): boolean;
+  /** Is a THREE stage painted here at all, selection or not — the gate for
+   *  the grid and axis lines (Blender's floor is persistent; only the gizmos
+   *  need an owner). */
+  threeSurfaceShowing(store: EditorShellStore, adapter: AuthoringAdapter): boolean;
+  /** The one three world rendered here, for the world-hidden eye. */
+  threeViewportRootId(store: EditorShellStore): string | null;
+  /** Apply the eye to every entity object (a no-op unless that root is hidden). */
+  applyRootHiddenVisibility(
+    objectMap: ReadonlyMap<string, THREE.Object3D>,
+    threeRootId: string | null,
+  ): void;
+  /** The scene-level half of the eye: background, fog, IBL, env objects. */
+  suppressRootEnvironment(scene: THREE.Scene): void;
+}
+
+/**
+ * Viewport-tool ownership for a SINGLE adapter — no composite, no manifest kind
+ * metadata to read.
+ *
+ * Structural and conservative, unchanged from where it was written
+ * (`authoring/viewport-tool-context.ts`, which now imports it): a rect-capable
+ * selection is DOM; a selection whose every node resolves to an `Object3D` is
+ * three; anything else advertises no kind-specific chrome rather than guessing.
+ * It speaks only the adapter contract, which is why it can be the default here.
+ */
+export function adapterOnlyToolOwner(
+  adapter: AuthoringAdapter,
+  selectedIds: Iterable<string>,
+): ViewportToolOwner | null {
+  const ids = [...selectedIds];
+  if (ids.length === 0) return null;
+  if (ids.some((id) => adapter.hierarchy.node(id) === null)) return null;
+  if (adapter.rects) return { worldId: null, kind: 'dom' };
+  if (ids.every((id) => adapter.hierarchy.object3D?.(id) != null)) {
+    return { worldId: null, kind: 'three' };
+  }
+  return null;
+}
+
+/** Memoized per store, because the viewport calls `activeAuthoring` per gesture
+ *  and adapter IDENTITY keys the selection scope and the handle cache. Mirrors
+ *  `authoring/active-adapter.ts`'s own per-store memo. */
+const _noAuthoringByStore = new WeakMap<EditorShellStore, AuthoringAdapter>();
+
+export const DEFAULT_VIEWPORT_AUTHORING_POLICY: ViewportAuthoringPolicy = {
+  activeAuthoring(store) {
+    let adapter = _noAuthoringByStore.get(store);
+    if (!adapter) {
+      adapter = makeNoAuthoringAdapter(store, 'No authoring adapter');
+      _noAuthoringByStore.set(store, adapter);
+    }
+    return adapter;
+  },
+  panelAuthoring(store) {
+    // No shell means no shared panels to agree with.
+    return DEFAULT_VIEWPORT_AUTHORING_POLICY.activeAuthoring(store);
+  },
+  pick() {
+    // No shell means no layer stack to walk. A host that mounts this viewport
+    // for one document supplies its own hit test (`EditorViewportOptions.pick`),
+    // which is what the Asset Lab document does.
+    return null;
+  },
+  toolOwner: adapterOnlyToolOwner,
+  toolOwnerPainted() {
+    // No world-group eyes exist without a composite, so nothing can be hidden.
+    return true;
+  },
+  threeSurfaceShowing(_store, adapter) {
+    return !adapter.rects && typeof adapter.hierarchy.object3D === 'function';
+  },
+  threeViewportRootId() {
+    return null;
+  },
+  applyRootHiddenVisibility() {
+    // Unreachable while `threeViewportRootId` is null — stated rather than
+    // implemented, so the no-shell story is one story.
+  },
+  suppressRootEnvironment() {},
+};
+
+let _policy: ViewportAuthoringPolicy = DEFAULT_VIEWPORT_AUTHORING_POLICY;
+
+/**
+ * Install the shell's composition. One owner, same rule as the store's
+ * `attachHistory`/`attachStatePersistence`: re-installing the SAME policy is a
+ * no-op (React strict-mode double-invokes the provider body), a DIFFERENT one
+ * throws rather than letting two shells disagree about what is under a pointer.
+ */
+export function installViewportAuthoringPolicy(policy: ViewportAuthoringPolicy): void {
+  if (_policy === policy) return;
+  if (_policy !== DEFAULT_VIEWPORT_AUTHORING_POLICY) {
+    throw new Error('A viewport authoring policy is already installed.');
+  }
+  _policy = policy;
+}
+
+/** The installed policy, or the no-shell default. */
+export function viewportAuthoringPolicy(): ViewportAuthoringPolicy {
+  return _policy;
+}
+
+/** Test seam: drop the installed policy. */
+export function __resetViewportAuthoringPolicyForTest(): void {
+  _policy = DEFAULT_VIEWPORT_AUTHORING_POLICY;
+}

package/src/viewport-controls-hint.ts

@@ -0,0 +1,57 @@
+/**
+ * Whether this user has learned the editor camera — the fact the viewport's
+ * on-canvas controls hint keys on.
+ *
+ * A 30-minute human build session (2026-08-28) asked "how do I move the
+ * camera" six-plus times and never found right-drag, on a build where
+ * right-drag orbit measured working: the gap was teaching, not mechanics.
+ * The hint carries the bindings until the user has REALLY learned them —
+ * three distinct orbit gestures, not one: dismissing on the first orbit
+ * meant one accidental right-drag hid the teaching before it was read
+ * (three human passes looked for the hint and found it gone — runhuman
+ * 15/17/31). Persisted per-user in localStorage like the inspector
+ * presentation; how you learned the camera is not a property of any game.
+ */
+
+const STORAGE_KEY = 'vgai-viewport-orbit-gestures-v1';
+const LEGACY_LEARNED_KEY = 'vgai-viewport-orbit-learned-v1';
+const LEARNED_AFTER_GESTURES = 3;
+const listeners = new Set<() => void>();
+let gestures: number | null = null;
+
+function storage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function count(): number {
+  if (gestures === null) {
+    const store = storage();
+    // A user the one-gesture era already marked stays learned.
+    if (store?.getItem(LEGACY_LEARNED_KEY) === '1') gestures = LEARNED_AFTER_GESTURES;
+    else gestures = Number(store?.getItem(STORAGE_KEY) ?? 0) || 0;
+  }
+  return gestures;
+}
+
+export function orbitLearned(): boolean {
+  return count() >= LEARNED_AFTER_GESTURES;
+}
+
+/** One distinct orbit gesture (one pointer-down-to-up that moved the camera). */
+export function recordOrbitGesture(): void {
+  if (orbitLearned()) return;
+  gestures = count() + 1;
+  storage()?.setItem(STORAGE_KEY, String(gestures));
+  if (orbitLearned()) for (const listener of listeners) listener();
+}
+
+export function subscribeOrbitLearned(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/viewport-door.ts

@@ -0,0 +1,237 @@
+/**
+ * THE AUTHORED VIEWPORT'S DOOR — the host's side of `host.viewport` (WORK.md
+ * §Play leaves the host, P2). Every mounted 3D STAGE binds its rig and its
+ * presenter here under its own document id (ARCHITECTURE-CORE §One stage:
+ * there is one stage host, mounted once per 3D document, and the door is per
+ * stage) and drives its frame hook from its own RAF loop; the lanes that
+ * mount something (Play's adoption of the live scene, the play-entry camera
+ * flight) read here and never hold a panel.
+ *
+ * The SINGULAR members — `viewportRig`, `presentViewportRoots`,
+ * `setViewportHelper`, `onViewportFrame` — resolve THE PRIMARY STAGE at call
+ * time: the stage presenting live roots if one is, else the FOCUSED stage
+ * (`activeWorkspaceDocumentId()`'s), else the first bound. Focus and
+ * presentation are the two facts; nothing here is "the scene viewport" by
+ * name. `viewportStages()` is every stage, for the lane that must touch each
+ * one (a helper `Object3D` has one parent, so it is set per stage).
+ *
+ * Until the lanes move, the host's own lanes import this registry directly; a
+ * package reads `@volter/editor-sdk/host`'s `viewport` member, which is this.
+ */
+
+import type { EditorHostStage, ViewportPresentation, ViewportRig } from '@volter/editor-sdk/host';
+import type { ViewportRoot } from '@volter/editor-sdk/host';
+import type * as THREE from 'three';
+import { activeWorkspaceDocumentId } from './workspace-document-registry';
+
+type Presenter = (roots: readonly ViewportRoot[]) => ViewportPresentation | null;
+type HelperSink = (kind: string, object: THREE.Object3D | null) => void;
+
+interface Binding {
+  readonly documentId: string;
+  readonly rig: ViewportRig;
+  readonly present: Presenter;
+  readonly setHelper: HelperSink;
+  readonly frameListeners: Set<(dtSeconds: number) => void>;
+  /** Helpers set on THIS stage by kind, so a re-bind restores them. */
+  readonly helpers: Map<string, THREE.Object3D | null>;
+  /** A presentation of live roots is alive on this stage right now. */
+  presenting: boolean;
+}
+
+/** Every bound stage, keyed by the document it draws; insertion-ordered, so
+ *  "the first bound" is a real answer. */
+const bound = new Map<string, Binding>();
+/**
+ * What belongs to the STAGE rather than to its current canvas, held by
+ * document id so it OUTLIVES a binding: its frame subscribers and its
+ * helpers. A stage's viewport remounts (a dock re-layout, HMR) without its
+ * baked navmesh having to be re-baked — the `setHelper` contract the SDK
+ * states — and without a lane's `onFrame` going quiet.
+ */
+const stageStateByDocument = new Map<
+  string,
+  {
+    readonly frameListeners: Set<(dtSeconds: number) => void>;
+    readonly helpers: Map<string, THREE.Object3D | null>;
+  }
+>();
+
+function stageStateFor(documentId: string): {
+  readonly frameListeners: Set<(dtSeconds: number) => void>;
+  readonly helpers: Map<string, THREE.Object3D | null>;
+} {
+  let state = stageStateByDocument.get(documentId);
+  if (!state) {
+    state = { frameListeners: new Set(), helpers: new Map() };
+    stageStateByDocument.set(documentId, state);
+  }
+  return state;
+}
+/** Listeners on the singular `onViewportFrame`: they follow the PRIMARY
+ *  stage, so they are held here and fanned in rather than added to a
+ *  binding's own set, which would strand them on a stage that stops being
+ *  primary (or unmounts). */
+const primaryFrameListeners = new Set<(dtSeconds: number) => void>();
+const stageListeners = new Set<(stages: readonly EditorHostStage[]) => void>();
+
+/** THE PRIMARY STAGE: presenting live roots > focused > first bound. */
+function primary(): Binding | null {
+  for (const binding of bound.values()) if (binding.presenting) return binding;
+  const focused = activeWorkspaceDocumentId();
+  if (focused !== null) {
+    const match = bound.get(focused);
+    if (match) return match;
+  }
+  return bound.values().next().value ?? null;
+}
+
+let stagesCache: readonly EditorHostStage[] | null = null;
+
+function notifyStages(): void {
+  stagesCache = null;
+  const snapshot = viewportStages();
+  for (const fn of stageListeners) fn(snapshot);
+}
+
+/** A stage door resolves its binding BY ID on every call, so a door held
+ *  across that stage's remount keeps driving the live canvas rather than the
+ *  disposed one. */
+function stageDoor(documentId: string, rig: ViewportRig): EditorHostStage {
+  const state = stageStateFor(documentId);
+  return {
+    documentId,
+    rig: () => bound.get(documentId)?.rig ?? rig,
+    setHelper: (kind, object) => {
+      state.helpers.set(kind, object);
+      bound.get(documentId)?.setHelper(kind, object);
+    },
+    onFrame: (fn) => {
+      state.frameListeners.add(fn);
+      return () => {
+        state.frameListeners.delete(fn);
+      };
+    },
+  };
+}
+
+/** A mounted stage binds its rig, how it presents live roots and how it shows
+ *  a helper, under the id of the document it draws; the return unbinds (a
+ *  re-bind for the same id REPLACES, and a stale binding's unbind never
+ *  removes its successor). Helpers set through the singular door before the
+ *  bind are applied now, the way they always were — but "before the bind" is
+ *  now per stage: a helper shown on THIS document's stage returns to it, and
+ *  a helper set while nothing is bound anywhere is dropped rather than
+ *  appearing on whichever stage happens to mount next. */
+export function bindViewportRig(
+  rig: ViewportRig,
+  present: Presenter,
+  setHelper: HelperSink,
+  options: { readonly documentId: string },
+): () => void {
+  const state = stageStateFor(options.documentId);
+  const next: Binding = {
+    documentId: options.documentId,
+    rig,
+    present,
+    setHelper,
+    frameListeners: state.frameListeners,
+    helpers: state.helpers,
+    presenting: false,
+  };
+  bound.set(options.documentId, next);
+  for (const [kind, object] of next.helpers) setHelper(kind, object);
+  notifyStages();
+  return () => {
+    if (bound.get(options.documentId) !== next) return;
+    bound.delete(options.documentId);
+    notifyStages();
+  };
+}
+
+/** Show (or clear with null) the editor-only helper of `kind` on the PRIMARY
+ *  stage. A helper wanted on every stage is set per stage through
+ *  {@link viewportStages} — an `Object3D` has one parent. */
+export function setViewportHelper(kind: string, object: THREE.Object3D | null): void {
+  const stage = primary();
+  if (!stage) return;
+  stage.helpers.set(kind, object);
+  stage.setHelper(kind, object);
+}
+
+export function viewportRig(): ViewportRig | null {
+  return primary()?.rig ?? null;
+}
+
+export function presentViewportRoots(roots: readonly ViewportRoot[]): ViewportPresentation | null {
+  const stage = primary();
+  if (!stage) return null;
+  const presentation = stage.present(roots);
+  if (!presentation) return null;
+  // The stage stays PRIMARY for as long as it is showing live roots — that is
+  // what makes Play's own camera flight and frame hook keep finding it while
+  // focus moves to the live document.
+  stage.presenting = true;
+  let released = false;
+  return {
+    worldId: presentation.worldId,
+    dispose: () => {
+      if (!released) {
+        released = true;
+        stage.presenting = false;
+      }
+      presentation.dispose();
+    },
+  };
+}
+
+/** Runs after the PRIMARY stage's own per-frame update, and RE-TARGETS: the
+ *  listener follows whichever stage is primary, not the one that was primary
+ *  when it subscribed. */
+export function onViewportFrame(fn: (dtSeconds: number) => void): () => void {
+  primaryFrameListeners.add(fn);
+  return () => {
+    primaryFrameListeners.delete(fn);
+  };
+}
+
+/** Every bound stage, in bind order. */
+export function viewportStages(): readonly EditorHostStage[] {
+  if (!stagesCache)
+    stagesCache = [...bound.values()].map((binding) => stageDoor(binding.documentId, binding.rig));
+  return stagesCache;
+}
+
+/**
+ * WHICH HELPER KINDS A STAGE IS HOLDING — the kinds something has actually
+ * shown on it through `setHelper` (`@volter/editor-sdk/host`,
+ * `EditorHostStage.setHelper`), cleared ones excluded.
+ *
+ * It exists because a 3D document's own OVERLAYS MENU must follow what the
+ * document put there and nothing else (`Object3DDocumentToolbar`): Blender's
+ * viewport overlay popover lists Bones, and ours may not list a Bones row over
+ * a document that has no bones to show. Same rule as the Outliner's restriction
+ * columns — a control follows what the thing behind it ANSWERS, never a knob.
+ */
+export function viewportStageHelperKinds(documentId: string): readonly string[] {
+  const state = stageStateByDocument.get(documentId);
+  if (!state) return [];
+  return [...state.helpers].filter(([, object]) => object !== null).map(([kind]) => kind);
+}
+
+export function onViewportStages(fn: (stages: readonly EditorHostStage[]) => void): () => void {
+  stageListeners.add(fn);
+  return () => {
+    stageListeners.delete(fn);
+  };
+}
+
+/** A stage's RAF loop calls this after its own update each frame. The stage's
+ *  own listeners always run; the primary-stage listeners run here only when
+ *  this stage IS the primary. */
+export function runViewportFrame(documentId: string, dtSeconds: number): void {
+  const binding = bound.get(documentId);
+  if (!binding) return;
+  for (const fn of binding.frameListeners) fn(dtSeconds);
+  if (primary() === binding) for (const fn of primaryFrameListeners) fn(dtSeconds);
+}

package/src/viewport-shading-boundary.ts

@@ -0,0 +1,12 @@
+import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
+import type { ViewportShadingRenderer } from '@volter/editor-threejs/render/viewport-shading';
+import type * as THREE from 'three';
+
+/**
+ * Scene diagnostic shading targets authored/runtime meshes only. Editor
+ * infrastructure shares the native scene for authoring, but its custom
+ * gizmo materials are part of the editor implementation and must stay native.
+ */
+export const isEditorViewportShadingTarget: Parameters<ViewportShadingRenderer['render']>[3] = (
+  mesh: THREE.Mesh,
+) => !isEditorOwnedObject(mesh);

package/src/vite-error-surface.ts

@@ -0,0 +1,141 @@
+/**
+ * A Vite transform/build failure is REPORTED, never rendered over the app.
+ *
+ * The editor and the game it is authoring share one page, one Vite instance
+ * and one HMR client, so Vite's stock error overlay — fixed, full-screen,
+ * z-index 99999 — made a syntax error in the USER'S GAME SOURCE brick the
+ * whole editor: nothing behind it clickable, no way out but editing the file
+ * blind. Owner, watching it happen: "this error needs to be surfaced but while
+ * this error is up, the rest of the app cannot be used which is a problem."
+ * The overlay is therefore off (`server.hmr.overlay: false` in
+ * `server/dev.ts` and `server/packaged.ts`) and this module is what the
+ * payload goes to instead.
+ *
+ * WHERE IT GOES: the editor's ONE error home — a console line, the
+ * `console-counts` status item that counts it, and, for an EDITOR/engine-owned
+ * failure, the auto-revealed Console (the same non-blocking "in your face"
+ * move a mount failure already makes). No banner, no second surface: see
+ * `components/status-contributions.tsx` on why the shell's error banners were
+ * deleted.
+ *
+ * WHY CLASSIFY AT ALL: the two owners deserve different volume. A game that
+ * does not compile is ordinary authoring — say so precisely and get out of the
+ * way. Our own engine/editor code failing to compile is a defect in the tool
+ * the user is holding, so it also pulls the Console open.
+ *
+ * Vite ALSO logs its own `[vite] Internal Server Error` line to `console.error`
+ * whenever the overlay is off, and `installEditorConsoleCapture()` puts that in
+ * the console too. That raw line is the trace; the line this module writes is
+ * the classified summary — the same trace/summary split
+ * `authoring/mount-failure-report.ts` documents, not a second channel.
+ *
+ * The SAVE-TIME half of the same story is louder and lives on the server:
+ * `server/project-validation.ts` parses every `src/` write, and
+ * `server/editor-server.ts` prints `✖ Invalid project file`, broadcasts it to
+ * every tab, and holds it in `/__editor/state`'s `projectValidation` (what
+ * `vgai status` reads) until the file saves clean again. Recovery therefore
+ * needs nothing here: this module holds no state to clear.
+ */
+
+import { editorConsole } from './editor-console';
+import { showConsoleUtility } from './workspace-utility-commands';
+
+/** The `err` half of Vite's `vite:error` HMR payload — only the fields read
+ *  here, so a Vite version that adds more does not need this type updated. */
+export interface ViteErrorLike {
+  readonly message?: string;
+  readonly frame?: string;
+  /** Vite's module id: an absolute path, possibly `/@fs`-prefixed and
+   *  possibly carrying the `?vgai-mount=N` query `project-module-url.ts`
+   *  minted. */
+  readonly id?: string;
+  readonly loc?: { readonly file?: string; readonly line?: number; readonly column?: number };
+}
+
+export type ViteErrorOwner = 'project' | 'editor';
+
+/**
+ * The absolute filesystem path a payload blames, or `null` when it blames
+ * nothing identifiable.
+ *
+ * Both forms are normalized here because BOTH occur: `loc.file` is a plain
+ * absolute path, while `id` is the URL the browser asked for — which for a
+ * project module outside the Vite root is the `/@fs`-prefixed, query-carrying
+ * string `project-module-url.ts` builds (`fsImportPath` + `?vgai-mount=N`).
+ * Undoing exactly that construction is why the two `/@fs` shapes below mirror
+ * `fsImportPath`'s own posix/Windows split.
+ */
+export function viteErrorFile(err: ViteErrorLike): string | null {
+  const raw = err.loc?.file ?? err.id ?? null;
+  if (!raw) return null;
+  const bare = raw.split('?')[0]!.split('#')[0]!;
+  if (!bare) return null;
+  if (!bare.startsWith('/@fs/')) return bare;
+  const unprefixed = bare.slice('/@fs'.length);
+  // `/@fs` + a posix root gives `/@fs/abs/path`; `/@fs/` + a Windows root
+  // gives `/@fs/C:/path`, whose leading slash is the separator, not the root.
+  return /^\/[A-Za-z]:/.test(unprefixed) ? unprefixed.slice(1) : unprefixed;
+}
+
+/**
+ * Whose code failed: the OPEN PROJECT's, or ours.
+ *
+ * "The project's own module" is the same question
+ * `server/game-globals-shadow.ts`'s `shouldShadowGameGlobals` answers on the
+ * server (a prefix test against the canonical project root) — asked here on
+ * the client, where the payload arrives as a URL rather than a path, hence the
+ * normalization above. An unattributable failure, or one with no project open,
+ * counts as ours: over-reporting our own breakage is the safe direction.
+ */
+export function viteErrorOwner(err: ViteErrorLike, projectRoot: string): ViteErrorOwner {
+  const file = viteErrorFile(err);
+  if (!file || !projectRoot) return 'editor';
+  const root = projectRoot.endsWith('/') ? projectRoot.slice(0, -1) : projectRoot;
+  return file === root || file.startsWith(`${root}/`) ? 'project' : 'editor';
+}
+
+/** `file:line:col — message`, plus the code frame when the payload carries one
+ *  (Babel/esbuild both do, and the frame is the part the deleted overlay was
+ *  genuinely good at showing). */
+export function formatViteError(err: ViteErrorLike): string {
+  const file = viteErrorFile(err);
+  const line = err.loc?.line;
+  const column = err.loc?.column;
+  const where = file
+    ? `${file}${line === undefined ? '' : `:${line}${column === undefined ? '' : `:${column}`}`}`
+    : null;
+  const head = err.message?.trim() || 'Vite could not build this module.';
+  const frame = err.frame?.replace(/\s+$/, '');
+  return [where ? `${where} — ${head}` : head, frame || null].filter(Boolean).join('\n');
+}
+
+/** The minimal slice of `import.meta.hot` this module needs — narrower than
+ *  Vite's `ViteHotContext` so the unit test can call it with a fake. */
+export interface ViteErrorHotContext {
+  on(event: 'vite:error', cb: (payload: { err?: ViteErrorLike }) => void): void;
+}
+
+/**
+ * Subscribe the editor's error home to `vite:error`. Called once from
+ * `main.tsx`; `getProjectRoot` is read per-event because a project can be
+ * opened, switched, or closed long after boot.
+ */
+export function installViteErrorSurface(
+  hot: ViteErrorHotContext,
+  getProjectRoot: () => string,
+): void {
+  hot.on('vite:error', (payload) => {
+    const err = payload?.err;
+    if (!err) return;
+    const owner = viteErrorOwner(err, getProjectRoot());
+    if (owner === 'project') {
+      editorConsole.error(`This game's source did not build.\n${formatViteError(err)}`, 'game');
+      return;
+    }
+    editorConsole.error(
+      `The editor's own source did not build.\n${formatViteError(err)}`,
+      'editor',
+    );
+    showConsoleUtility();
+  });
+}

package/src/wait-until.ts

@@ -0,0 +1,37 @@
+/**
+ * POLL UNTIL A LIVE PREDICATE HOLDS — the one wait the editor's async doors
+ * share, and the one place its cadence is spelled.
+ *
+ * It lived private in `editor-view-presentation.ts` while the presenter was
+ * the only module that addressed a document. Now that each document family
+ * answers its own address (`document-open-registry.ts`), the families do the
+ * waiting their own addresses need — a table entry that arrives on a later
+ * adapter resolution, a contribution that registers after the first
+ * discovery pass — so the helper is shared rather than duplicated four times.
+ *
+ * NOT a general scheduling utility: it polls, which is what a registry with no
+ * per-entry subscription leaves you. Where a seam DOES publish changes
+ * (`subscribeToolContributions`, `subscribeProjectAdapter`), subscribe to it.
+ */
+
+/**
+ * How long an EXPLICIT address waits for the thing it names. A view link, a
+ * restored layout and an agent's `present` are all durable intent, so a
+ * document that is merely late must still land; the window is bounded because
+ * "it is not coming" has to be sayable.
+ */
+export const DOCUMENT_REGISTRATION_TIMEOUT_MS = 10_000;
+
+/** `true` once `predicate()` holds, `false` if `timeoutMs` elapses first. */
+export async function waitUntil(predicate: () => boolean, timeoutMs = 4000): Promise<boolean> {
+  if (predicate()) return true;
+  const started = performance.now();
+  return new Promise((resolve) => {
+    const tick = () => {
+      if (predicate()) resolve(true);
+      else if (performance.now() - started >= timeoutMs) resolve(false);
+      else setTimeout(tick, 25);
+    };
+    setTimeout(tick, 0);
+  });
+}