@volter/editor-core 0.5.57

package/src/scene-document-plan.ts

@@ -0,0 +1,315 @@
+/**
+ * THE EDIT TAB ROW, as pure logic — what the adapter's scene table means for
+ * the workspace's open documents.
+ *
+ * ARCHITECTURE-CORE §Editor: "the scene table (entries, default, authorable
+ * flags, reach) is ONE adapter declaration with two clients — the Edit tab row
+ * projects it as isolation documents through the substrate family's piece
+ * mounts, and Play's `open()` walks it as live navigation." This module is the
+ * decision half of the FIRST client; `components/scene-documents.tsx` is the
+ * half that talks to the workspace registry, and `command-listener.ts`'s
+ * `open` verb resolves ONE entry through the very same table below — so the
+ * tab row and the verb can never disagree about what an entry is.
+ *
+ * ZERO INFERENCE. Every answer here is read off a DECLARED field of the
+ * entry — `authorable`, `reach`, `source`, `region`. Nothing is derived from a
+ * folder, a filename, a root, or the shape of the project: an entry the
+ * adapter did not declare simply is not here, and an entry it declared
+ * unreachable stays unreachable with the game's own reason attached.
+ */
+
+import type { DocumentEntry, SceneSource } from '@volter/editor-project/adapter/adapter-module';
+import type { ResolvedDocumentTable } from './project-adapter';
+
+/** Document-id namespace for a per-scene isolation document. Distinct from
+ *  `three-story:` ids (the story turntable, `@vgai/game`'s): a scene is
+ *  reached through the entrypoint's own selection table, not through a story,
+ *  and the two can legitimately name the same composition. */
+export const SCENE_DOCUMENT_PREFIX = 'scene:';
+
+/** The workspace document id for one entrypoint-selection scene entry. */
+export function sceneDocumentId(entryId: string): string {
+  return `${SCENE_DOCUMENT_PREFIX}${entryId}`;
+}
+
+/** A standing isolation tab — `scene:TitleScreen`, not `workspace:scene`. */
+export function isIsolationSceneDocumentId(id: string): boolean {
+  return id.startsWith(SCENE_DOCUMENT_PREFIX);
+}
+
+/**
+ * What the Edit workspace does with ONE scene-table entry.
+ *
+ * `no-document` is not a failure — a traversal entry and a declared-unreachable
+ * one are both honest table rows that simply own no Edit document. Its `reason`
+ * is the game's OWN sentence whenever the game supplied one (a `none` reach
+ * carries its `reason` verbatim), so a refusal quotes the adapter rather than
+ * paraphrasing it.
+ */
+export type SceneDocumentPlan =
+  /** Mounting the region IS opening this scene — it is the root's own standing
+   *  document, which this entry merely NAMES. No second document. */
+  | { readonly kind: 'root-document'; readonly regionId: string; readonly title: string }
+  /** A viewport document of its own, mounting `source` in isolation. */
+  | {
+      readonly kind: 'isolation-document';
+      readonly documentId: string;
+      readonly title: string;
+      /** Owning root, carried into the document so its declared region — not
+       *  its filename or export shape — decides the mounting surface. */
+      readonly regionId: string | null;
+      readonly source: SceneSource;
+      readonly isolationSetup?: SceneSource;
+      /** Present when this piece is also a running-game screen. Play's `open`
+       *  still navigates live; Edit mounts the source in isolation and never
+       *  holds the live host. */
+      readonly contractSceneId?: string;
+    }
+  /** A portable story mounts it — the existing story-document opener owns it. */
+  | { readonly kind: 'story-document'; readonly title: string; readonly storyId: string }
+  /**
+   * No Edit document, with the reason stated.
+   *
+   * `liveReach` separates "no document, and nothing else either" from "no
+   * document BECAUSE this scene is REACHED live" — the Edit workspace treats
+   * both the same (neither is a tab), while the `open` verb must route the
+   * second to the running game instead of refusing it, and must tell a caller
+   * with no game running to start one rather than that the scene is a dead end.
+   *
+   * Present means the live half REACHES this entry — it opens it and answers
+   * ok. Absent means it does not, which is two different things and
+   * deliberately one field: the live half may have no business with the entry
+   * at all (it answers `null` for `story`/`none`). A session that cannot
+   * remount still refuses `entrypoint-selection` coded; that is a session
+   * fact, not a reach fact — the intended path is remount-at-key and ends
+   * `ok: true`. {@link liveReachOf} is where that line is drawn.
+   *
+   * It is derived from REACH ALONE ({@link liveReachOf}), never from
+   * `authorable`, because the live half is the authority on this half of the
+   * question and it reads reach only (`scene-live-open.ts` switches on
+   * `entry.reach.kind`). A planner that also asked `authorable` here would call
+   * a screen the running game navigates to a dead end — the exact collapse this
+   * field exists to prevent.
+   */
+  | {
+      readonly kind: 'no-document';
+      readonly reason: string;
+      readonly liveReach?: 'game-contract' | 'root-mount' | 'entrypoint-selection';
+    };
+
+/**
+ * THE ONE DERIVATION of `liveReach`, from the entry's DECLARED reach and
+ * nothing else — never from `authorable`, so the two clients cannot disagree.
+ *
+ * It answers for exactly the reaches `openLiveSceneEntry` REACHES: it
+ * navigates a `game-contract` scene through the game's own contract, it
+ * shows the document a `root-mount` scene draws into, and it remounts play
+ * at an `entrypoint-selection` key. All three end `ok: true` when the
+ * session can honour them, so for all three the honest Edit-half refusal
+ * with nothing running is `SCENE_NAVIGATION_NOT_RUNNING` — start the game
+ * and ask again.
+ *
+ * A session that cannot remount still refuses `entrypoint-selection` with
+ * `SCENE_NOT_OPENABLE_LIVE` — that is the same shape as a `game-contract`
+ * scene whose running game publishes no contract (`SCENE_CONTRACT_UNAVAILABLE`).
+ * The field names the intended live path, not every session's ability to
+ * walk it.
+ *
+ * A spread rather than a value so `exactOptionalPropertyTypes` gets an ABSENT
+ * key for "no live reach", never an explicit `undefined`. Every `no-document`
+ * return below spreads it unconditionally — the two where it is currently
+ * provably empty included — so this function stays the SOLE decider and a
+ * later widening cannot leave a branch silently behind.
+ */
+function liveReachOf(entry: DocumentEntry): {
+  readonly liveReach?: 'game-contract' | 'root-mount' | 'entrypoint-selection';
+} {
+  const { kind } = entry.reach;
+  return kind === 'game-contract' || kind === 'root-mount' || kind === 'entrypoint-selection'
+    ? { liveReach: kind }
+    : {};
+}
+
+/**
+ * Plan ONE entry.
+ *
+ * Order matters: `authorable` is asked FIRST because a traversal entry
+ * (boot/loading choreography) earns no column whatever its reach — the flag is
+ * about what the entry IS, while reach is about how the running game gets
+ * there.
+ *
+ * That order decides the DOCUMENT, and only the document. `liveReach` is
+ * carried through it untouched: whether a running game can be sent to a screen
+ * is the game's contract's business, not the host's opinion of whether the
+ * screen is worth authoring, and the live half honours that by reading reach
+ * alone.
+ */
+export function planSceneDocument(entry: DocumentEntry): SceneDocumentPlan {
+  if (!entry.authorable) {
+    return {
+      kind: 'no-document',
+      ...liveReachOf(entry),
+      reason:
+        `"${entry.id}" is declared TRAVERSAL (boot/loading choreography), not an authorable ` +
+        'composition, so it has no Edit document.',
+    };
+  }
+  switch (entry.reach.kind) {
+    case 'none':
+      // VERBATIM. The adapter wrote this sentence about its own game; a host
+      // paraphrase would be the host claiming to know why.
+      return { kind: 'no-document', ...liveReachOf(entry), reason: entry.reach.reason };
+    case 'root-mount':
+      return entry.region === null
+        ? {
+            // Still LIVE-REACHED: `openLiveSceneEntry` shows the document the
+            // running game draws into and never looks at `region`, so the
+            // missing region costs this entry its Edit document and nothing
+            // else.
+            kind: 'no-document',
+            ...liveReachOf(entry),
+            reason:
+              `"${entry.id}" is reached by mounting a region, but the entry names no region, ` +
+              'so there is no standing document it could be.',
+          }
+        : { kind: 'root-document', regionId: entry.region, title: entry.label };
+    case 'entrypoint-selection':
+      // ACTIVE means the entrypoint indexes its selection table with THIS key,
+      // so the region's standing document already mounts this composition —
+      // opening a second document for it would show the same thing twice under
+      // two titles. The entry names the standing document instead, exactly as
+      // `root-mount` does. A region-less entry keeps the isolation document:
+      // there is no honest mapping from "active" to a document without one, and
+      // inventing a region is what zero-inference forbids.
+      if (entry.reach.active === true && entry.region !== null) {
+        return { kind: 'root-document', regionId: entry.region, title: entry.label };
+      }
+      return entry.source
+        ? {
+            kind: 'isolation-document',
+            documentId: sceneDocumentId(entry.id),
+            title: entry.label,
+            regionId: entry.region,
+            source: entry.source,
+            ...(entry.isolationSetup ? { isolationSetup: entry.isolationSetup } : {}),
+          }
+        : {
+            kind: 'no-document',
+            ...liveReachOf(entry),
+            reason:
+              `"${entry.id}" is selected at the entrypoint's \`${entry.reach.selection}\` slot, ` +
+              'but the finder could not resolve the module it names, so there is nothing to ' +
+              'mount in isolation.',
+          };
+    case 'game-contract':
+      // Authorable + a source module is an Edit piece: every authorable scene
+      // gets a tab (ARCHITECTURE-CORE §Editor). Play still navigates live
+      // through `liveReach`. Without a source there is nothing to isolate, so
+      // Edit stays silent and `open` asks the running game.
+      return entry.source
+        ? {
+            kind: 'isolation-document',
+            documentId: sceneDocumentId(entry.id),
+            title: entry.label,
+            regionId: entry.region,
+            source: entry.source,
+            ...(entry.isolationSetup ? { isolationSetup: entry.isolationSetup } : {}),
+            contractSceneId: entry.reach.sceneId,
+          }
+        : {
+            kind: 'no-document',
+            ...liveReachOf(entry),
+            reason:
+              `"${entry.id}" is reached only through the running game's own navigation ` +
+              `(its scenes contract calls it "${entry.reach.sceneId}"), and the entry names no ` +
+              'source module, so there is no Edit document — open it while the game is running.',
+          };
+    case 'story':
+      return { kind: 'story-document', title: entry.label, storyId: entry.reach.storyId };
+  }
+}
+
+/** One row of the Edit tab row. */
+export interface SceneTabRow {
+  readonly entry: DocumentEntry;
+  /** Never `no-document` — a row that owns no document is not a tab. */
+  readonly plan: Exclude<SceneDocumentPlan, { kind: 'no-document' }>;
+  /** The table's declared default entry. At most one row carries it. */
+  readonly isDefault: boolean;
+}
+
+/**
+ * The whole Edit tab row: every AUTHORABLE SCENE the table declares that owns
+ * a document, in the table's own order.
+ *
+ * Prefabs are excluded deliberately, and they are not second-class for it: a
+ * prefab already surfaces through the boards and Content, and it opens as a
+ * sibling document on demand through the same verb (`open`). What a standing
+ * TAB means is "this is one of the game's scenes", which is exactly the
+ * `kind: 'scene'` declaration.
+ */
+export function sceneTabRow(table: ResolvedDocumentTable): readonly SceneTabRow[] {
+  const rows: SceneTabRow[] = [];
+  for (const entry of table.entries) {
+    if (entry.kind !== 'scene') continue;
+    const plan = planSceneDocument(entry);
+    if (plan.kind === 'no-document') continue;
+    rows.push({ entry, plan, isDefault: table.default === entry.id });
+  }
+  return rows;
+}
+
+/** What Edit and Content actually present from one resolved scene table. */
+export function authoringSurfaceFromTable(
+  table: ResolvedDocumentTable,
+  openDocumentIds: readonly string[],
+  availableDocumentIds: readonly string[],
+): {
+  readonly sceneDocuments: number;
+  readonly isolationDocuments: number;
+  readonly openIsolationDocuments: number;
+  readonly availableIsolationDocuments: number;
+  readonly pieces: number;
+  /** Entries of kind `scene` — the surface prefabs are placed on; a table
+   *  with none (a models or website project) has no prefabs by design. */
+  readonly sceneEntries: number;
+} {
+  const tabs = sceneTabRow(table);
+  const isolationIds = tabs.flatMap((row) =>
+    row.plan.kind === 'isolation-document' ? [row.plan.documentId] : [],
+  );
+  const open = new Set(openDocumentIds);
+  const available = new Set(availableDocumentIds);
+  // A finder's OWN document kind (a `model` from `@volter/editor-blender`'s finder, a
+  // `page`, a `shot`) opens through that kind's document, never through the
+  // scene plan above — which answers `no-document` for it because it names
+  // no region. Those are documents Edit presents all the same; measured
+  // 2026-09-17, a models project reported "no authorable scene with a
+  // document to open" beside its open model document.
+  const kindDocuments = table.entries.filter(
+    (entry) => entry.authorable && entry.kind !== 'scene' && entry.kind !== 'prefab',
+  ).length;
+  return {
+    sceneDocuments: tabs.length + kindDocuments,
+    isolationDocuments: isolationIds.length,
+    openIsolationDocuments: isolationIds.filter((id) => open.has(id)).length,
+    availableIsolationDocuments: isolationIds.filter((id) => available.has(id)).length,
+    pieces: table.entries.filter((entry) => entry.kind === 'prefab').length,
+    sceneEntries: table.entries.filter((entry) => entry.kind === 'scene').length,
+  };
+}
+
+/**
+ * Isolation tabs ARE the Edit scene row. A generic Scene tab
+ * (`workspace:scene` / `workspace:canvas-scene`) would be a second surface
+ * for the same game — the live host, or an empty world — and only belongs
+ * when this table has no isolation documents (or also names a root document
+ * that Scene already is).
+ */
+export function isolationTabsReplaceGenericScene(table: ResolvedDocumentTable): boolean {
+  const rows = sceneTabRow(table);
+  return (
+    rows.some((row) => row.plan.kind === 'isolation-document') &&
+    !rows.some((row) => row.plan.kind === 'root-document')
+  );
+}

package/src/scene-framing.ts

@@ -0,0 +1,315 @@
+/**
+ * What the editor camera should look at when it adopts a world nobody authored
+ * here — the two answers behind `EditorViewport.focusOnScene`.
+ *
+ * ## The measured defect
+ *
+ * Auto-frame framed the game's ENTIRE content AABB. Measured on a Cuberun
+ * mount: a 2,000-radius BackSide skybox sphere, a sun mesh at `z = -2000` and a
+ * hyperspace prop at `z ≈ -5365` stretched that AABB to ~8,400 units deep, so
+ * the fit distance landed the camera 12,870 units away from a ~1,000-unit
+ * gameplay corridor. 93% of the Scene viewport was black, and the one visible
+ * thing was the OUTSIDE of the skybox. The same world framed at working
+ * distance is vivid and correct. (Descent measured the same looseness at a
+ * smaller scale: a camera at ~2,580 for an ~800-unit world.)
+ *
+ * The union is the wrong instrument because a backdrop is not content the
+ * reader is looking FOR — it is content that exists to be far away. One prop
+ * 5,000 units out costs the whole framing, and no amount of care in the fit
+ * math can recover it.
+ *
+ * ## The two answers, in order
+ *
+ * 1. {@link viewFromGameCamera} — a game's author already decided the
+ *    interesting view, so seeding the orbit camera from the world matrix of a
+ *    camera the game itself placed opens the Scene tab where the game looks.
+ *    {@link pickGameCamera} decides which camera that is.
+ * 2. {@link frameableContentBounds} — the fallback for a game whose camera we
+ *    cannot name. It trims outliers off the union before framing.
+ *
+ * ## Why gap-trimming and not a percentile
+ *
+ * A blanket percentile (frame the inner 90% of content) would tighten the
+ * framing of EVERY world, including the uniform ones that are framed correctly
+ * today. This trims only across a spatial GAP: a face of the bounding box moves
+ * inward only when a small share of boxes sits beyond a void spanning a large
+ * fraction of the current diagonal. A uniformly-filled world has no such gap,
+ * so it comes back byte-identical to the plain union — that identity is the
+ * first property the tests pin.
+ */
+
+import { isEditorOwnedObject } from '@volter/editor-threejs/viewport/editor-layers';
+import * as THREE from 'three';
+
+/** Tuning for {@link frameableContentBounds}. Defaults are the shipped values. */
+export interface FrameableBoundsOptions {
+  /** Largest share of the boxes all trimming together may discard. */
+  maxOutlierFraction?: number;
+  /** A gap must span this share of the current content diagonal to be a gap. */
+  minGapFraction?: number;
+  /** Below this many boxes there is no distribution to judge; nothing trims. */
+  minSampleSize?: number;
+  /** Cap on trim passes, so cost stays bounded on a huge world. */
+  maxPasses?: number;
+}
+
+const DEFAULTS: Required<FrameableBoundsOptions> = {
+  maxOutlierFraction: 0.1,
+  minGapFraction: 0.2,
+  minSampleSize: 8,
+  maxPasses: 8,
+};
+
+/** Orbit pivot distance when there is no content to measure one from. */
+const EMPTY_CONTENT_PIVOT_DISTANCE = 10;
+
+/** How far down the view axis the content must start for the pivot to mean
+ *  anything — as a share of the content's own radius. */
+const MIN_PIVOT_RADIUS_FRACTION = 0.01;
+
+type Axis = 'x' | 'y' | 'z';
+const AXES: readonly Axis[] = ['x', 'y', 'z'];
+
+function unionOf(boxes: readonly THREE.Box3[], indices: Iterable<number>): THREE.Box3 {
+  const out = new THREE.Box3();
+  for (const i of indices) out.union(boxes[i] as THREE.Box3);
+  return out;
+}
+
+/** One candidate trim: the boxes beyond the widest gap on one box face. */
+interface GapCut {
+  gap: number;
+  discard: number[];
+}
+
+/**
+ * The widest gap found scanning inward from any of the six faces, across at
+ * most `budget` boxes.
+ *
+ * Scanning from a FACE (rather than clustering centers) is what catches a
+ * skybox: its centre sits with the content, and only its extent is an outlier.
+ */
+function widestOuterGap(
+  boxes: readonly THREE.Box3[],
+  kept: ReadonlySet<number>,
+  budget: number,
+): GapCut | null {
+  let best: GapCut | null = null;
+  for (const axis of AXES) {
+    for (const side of ['min', 'max'] as const) {
+      const values: Array<{ i: number; v: number }> = [];
+      for (const i of kept) values.push({ i, v: (boxes[i] as THREE.Box3)[side][axis] });
+      // Outliers are the smallest values on a min face and the largest on a max
+      // face; sort so index 0 is always the outermost.
+      values.sort((a, b) => (side === 'min' ? a.v - b.v : b.v - a.v));
+      const reach = Math.min(budget, values.length - 1);
+      for (let k = 0; k < reach; k++) {
+        const gap = Math.abs((values[k + 1] as { v: number }).v - (values[k] as { v: number }).v);
+        if (best && gap <= best.gap) continue;
+        best = { gap, discard: values.slice(0, k + 1).map((e) => e.i) };
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * The box worth FRAMING, given one world-space box per content node.
+ *
+ * Returns the plain union whenever there is nothing defensible to trim: too few
+ * boxes to judge, no gap wide enough, or a budget of zero. Never returns an
+ * empty box for non-empty input.
+ */
+export function frameableContentBounds(
+  boxes: readonly THREE.Box3[],
+  options: FrameableBoundsOptions = {},
+): THREE.Box3 {
+  const opts = { ...DEFAULTS, ...options };
+  const content = boxes.filter((b) => !b.isEmpty());
+  const all = content.map((_, i) => i);
+  const full = unionOf(content, all);
+  if (content.length < opts.minSampleSize) return full;
+
+  let budget = Math.floor(content.length * opts.maxOutlierFraction);
+  if (budget < 1) return full;
+
+  const kept = new Set(all);
+  let bounds = full;
+  const size = new THREE.Vector3();
+  for (let pass = 0; pass < opts.maxPasses && budget > 0; pass++) {
+    const diagonal = bounds.getSize(size).length();
+    if (!(diagonal > 0)) break;
+    const cut = widestOuterGap(content, kept, budget);
+    if (!cut || cut.gap <= opts.minGapFraction * diagonal) break;
+    for (const i of cut.discard) kept.delete(i);
+    budget -= cut.discard.length;
+    bounds = unionOf(content, kept);
+  }
+  return bounds.isEmpty() ? full : bounds;
+}
+
+/** An orbit-camera pose: where the eye sits and what it orbits around. */
+export interface SeededView {
+  position: THREE.Vector3;
+  target: THREE.Vector3;
+}
+
+/**
+ * The editor orbit pose that reproduces `camera`'s own view.
+ *
+ * The eye is the game camera's world position and the view direction is its
+ * own; the only thing invented is the orbit PIVOT, which is placed at the depth
+ * of the content along that view direction — the point the reader is already
+ * looking at, so the first orbit drag turns around the world rather than
+ * around a point behind their head.
+ *
+ * Returns `null` when that pivot cannot be placed: the world sits BEHIND the
+ * camera (a view showing none of the game is not worth adopting), or it sits
+ * ON it, which leaves an orbit pivot at the eye — measured as a target
+ * 4.6e-14 units out, an orbit control that can only spin in place. Both fall
+ * back to {@link frameableContentBounds}.
+ */
+export function viewFromGameCamera(camera: THREE.Camera, content: THREE.Box3): SeededView | null {
+  const forward = camera.getWorldDirection(new THREE.Vector3());
+  const position = new THREE.Vector3().setFromMatrixPosition(camera.matrixWorld);
+  if (!Number.isFinite(position.lengthSq()) || forward.lengthSq() === 0) return null;
+  if (content.isEmpty()) {
+    return {
+      position,
+      target: position.clone().addScaledVector(forward, EMPTY_CONTENT_PIVOT_DISTANCE),
+    };
+  }
+  const sphere = content.getBoundingSphere(new THREE.Sphere());
+  const along = sphere.center.clone().sub(position).dot(forward);
+  if (!(along > sphere.radius * MIN_PIVOT_RADIUS_FRACTION)) return null;
+  return { position, target: position.clone().addScaledVector(forward, along) };
+}
+
+/**
+ * The NDC points a seeded view is sampled at: the centre plus a ring at 60% of
+ * the way to each edge/corner. Nine rays — enough that a view whose middle is
+ * blocked by one prop still reads as open, cheap enough to run on every seed
+ * attempt over a whole game graph.
+ */
+const OCCLUSION_SAMPLES: ReadonlyArray<readonly [number, number]> = [
+  [0, 0],
+  [-0.6, 0.6],
+  [0.6, 0.6],
+  [-0.6, -0.6],
+  [0.6, -0.6],
+  [0, 0.6],
+  [0, -0.6],
+  [-0.6, 0],
+  [0.6, 0],
+];
+
+/**
+ * How near a hit has to be, as a share of the view's own pivot distance, to
+ * count as "pressed against the lens" rather than "part of the world". At 2%,
+ * a camera looking 100 units into a world is blocked only by something inside
+ * 2 units of it.
+ */
+const NEAR_FIELD_FRACTION = 0.02;
+
+const _raycaster = new THREE.Raycaster();
+const _ndc = new THREE.Vector2();
+
+/** Three's raycast reports hits on invisible objects; a hidden collider proxy
+ *  in front of the lens blocks nothing a reader would see. */
+function isVisibleInWorld(object: THREE.Object3D): boolean {
+  for (let node: THREE.Object3D | null = object; node; node = node.parent) {
+    if (!node.visible) return false;
+  }
+  return true;
+}
+
+/**
+ * Does a view posed HERE show the world, or a surface pressed against the lens?
+ *
+ * The measured defect: a game's own camera is placed for the game's own moment
+ * — inside a cockpit, behind a wall it is about to drive through, under
+ * terrain that has not settled — and adopting it as the editor's opening view
+ * can hand the reader a full-bleed rectangle of rock. The view is a perfectly
+ * good gameplay camera and a useless first look, and nothing in the pose
+ * itself says which.
+ *
+ * The instrument is geometric, not pixels: nine rays through the frustum, and
+ * a view SHOWS THE WORLD when at least one of them either escapes (sky,
+ * backdrop, open space) or reaches something farther than
+ * {@link NEAR_FIELD_FRACTION} of what this view claims to be looking at. The
+ * threshold is relative to the view's own pivot distance, so it needs no
+ * world-scale constant and reads the same on a 10-unit room and a 10,000-unit
+ * canyon.
+ *
+ * Deliberately conservative: EVERY sample must be blocked in the near field
+ * before the view is refused, so an ordinary view with a prop in the middle or
+ * ground filling its lower half still passes. A refusal here costs the reader
+ * only the game's own camera — the caller falls back to
+ * {@link frameableContentBounds}, which always shows something.
+ *
+ * Three's raycast honours `material.side` exactly as the renderer does, and
+ * that alignment is the reason this instrument is honest rather than merely
+ * cheap: a camera sealed inside a front-faced solid is invisible to BOTH — the
+ * reader sees through the shell, the rays escape through it, and the view is
+ * correctly not called blocked. The failure this catches is the one that is
+ * actually on screen: front faces, filling the frame, right at the lens.
+ *
+ * (The screenshot lane measures the same failure from the other side, on
+ * PIXELS, in `composite-screenshot.ts`. That instrument needs a drawn frame
+ * and a GPU readback, and it cannot tell a legitimately flat picture from a
+ * blocked one — which is why the decision to adopt a pose is made here, before
+ * anything is drawn.)
+ */
+export function seededViewShowsWorld(
+  camera: THREE.Camera,
+  content: readonly THREE.Object3D[],
+  pivotDistance: number,
+): boolean {
+  if (!(pivotDistance > 0) || content.length === 0) return true;
+  const nearField = pivotDistance * NEAR_FIELD_FRACTION;
+  for (const [x, y] of OCCLUSION_SAMPLES) {
+    _ndc.set(x, y);
+    _raycaster.setFromCamera(_ndc, camera);
+    const hits = _raycaster.intersectObjects(content as THREE.Object3D[], true);
+    const blocker = hits.find((hit) => isVisibleInWorld(hit.object));
+    if (!blocker || blocker.distance > nearField) return true;
+  }
+  return false;
+}
+
+/** Every camera in the game's own scene, in scene order, editor furniture and
+ *  its subtrees excluded. */
+function gameCameras(node: THREE.Object3D, out: THREE.Camera[] = []): THREE.Camera[] {
+  if (isEditorOwnedObject(node)) return out;
+  if ((node as THREE.Camera).isCamera) out.push(node as THREE.Camera);
+  for (const child of node.children) gameCameras(child, out);
+  return out;
+}
+
+/**
+ * The camera whose view an ingest mount should adopt — one the game itself
+ * CREATED AND PLACED, which means one that is in the game's own scene graph.
+ *
+ * The capture's own camera (the one the first `render(scene, camera)` used) is
+ * preferred WHEN it is one of those, and is otherwise ignored, because on the
+ * first rendered frame it can be a reconciler's placeholder rather than the
+ * author's camera. Measured on Cuberun: the captured camera came back with an
+ * identity world matrix at the origin while the game's own
+ * `<PerspectiveCamera position={[0, 10, -10]}>` was sitting in the scene at
+ * (0, 8, 3.5) looking down the corridor — seeding from the capture opened on a
+ * flat wall of ground plane, seeding from the scene's camera opened on the
+ * game.
+ *
+ * Editor furniture is never adopted: the capture trap sits on the shared
+ * `WebGLRenderer.prototype`, so the editor's own cameras are the one thing
+ * that must never come back from here.
+ */
+export function pickGameCamera(
+  captured: THREE.Camera | null | undefined,
+  scene: THREE.Object3D,
+): THREE.Camera | null {
+  const cameras = gameCameras(scene);
+  if (cameras.length === 0) return null;
+  if (captured && cameras.includes(captured)) return captured;
+  return cameras[0] as THREE.Camera;
+}