@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/scene-document-plan.ts

@@ -0,0 +1,320 @@
+/**
+ * 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 { getProjectStoryModules } from '@volter/sdk/kit/stories/story-registry';
+import type { DocumentEntry, SceneSource } from '@volter/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, `@volter/editor-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;
+  /** Project story modules that did not load or compose: each one's prefab is missing from
+   *  the table with no entry of its own to say so. */
+  readonly storyFailures: 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,
+    storyFailures: getProjectStoryModules().filter((module_) => !module_.ok).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/kit/scene-live-open.ts

@@ -0,0 +1,210 @@
+/**
+ * THE SCENE TABLE'S SECOND CLIENT — `open()` against the RUNNING game.
+ *
+ * ARCHITECTURE-CORE §Editor: "the scene table … is ONE adapter declaration with
+ * two clients — the Edit tab row projects it as isolation documents … and
+ * Play's `open()` walks it as live navigation." `scene-document-plan.ts` +
+ * `components/scene-documents.tsx` are the first client; this module is the
+ * second, and both are reached through the ONE `open` verb in
+ * `command-listener.ts`, which asks this one first whenever a game is live.
+ *
+ * ZERO INFERENCE, twice over:
+ *
+ *  1. WHICH contract id an entry is, is the adapter's own declaration
+ *     (`reach: { kind: 'game-contract', sceneId }`). Nothing here matches
+ *     entry ids against contract ids, or assumes the two vocabularies coincide.
+ *  2. WHETHER that id is navigable is the GAME's answer, at the moment of use:
+ *     the switch goes through the bound scenes projection's own
+ *     `goToScene` (`authoring/contract-scenes-stories.ts`), which validates
+ *     membership against the game's own `list()` and carries the mount's
+ *     held-repaint seam. Calling the contract's `goTo` directly would route
+ *     around both.
+ *
+ * Every seam is injected ({@link LiveSceneSession}) so the whole matrix is
+ * decidable headlessly — no mounted game, no workspace, no browser.
+ */
+
+import type { LiveSceneTable } from '@volter/sdk/host';
+import type { DocumentEntry } from '@volter/project/adapter/adapter-module';
+
+/** What a live game session offers this verb. */
+export interface LiveSceneSession {
+  /**
+   * The running game's BOUND scenes projection, or `null` when the game
+   * publishes none.
+   *
+   * "Bound" is load-bearing: this is the object the mount installed on the
+   * game's own authoring adapter — the same one the inspector's scene picker
+   * drives — so a switch made here is the same switch a click makes, held
+   * repaint and all.
+   */
+  readonly scenes: () => LiveSceneTable | null;
+  /**
+   * Activate the document the running game is presented in; `false` when the
+   * session has none open. An ingested game's mount IS the running game, and
+   * it draws into the Game document — there is no second document a
+   * `root-mount` scene could name.
+   */
+  readonly activateGameDocument: () => boolean;
+  /** The Game document's id, for the answer. */
+  readonly gameDocumentId: string;
+  /**
+   * Host remount of a native swap-slot scene: stop this play run and start a
+   * new one with the entrypoint's selection const rewritten to `key`. Absent
+   * when this session has no serve-time rewrite (an ingest root), which is
+   * when `entrypoint-selection` still refuses `SCENE_NOT_OPENABLE_LIVE`.
+   */
+  readonly remountSelection?: (args: {
+    readonly selection: string;
+    readonly key: string;
+    readonly regionId: string;
+  }) => Promise<{ readonly ok: true } | { readonly ok: false; readonly error: string }>;
+}
+
+/** A coded refusal from the live half — the SDK matches `code`, never prose. */
+export interface LiveSceneOpenRefusal {
+  readonly ok: false;
+  readonly code:
+    | 'SCENE_CONTRACT_UNAVAILABLE'
+    | 'SCENE_NOT_IN_CONTRACT'
+    | 'SCENE_SWITCH_FAILED'
+    | 'SCENE_NOT_OPENABLE_LIVE'
+    | 'SCENE_DOCUMENT_NOT_MOUNTED';
+  readonly error: string;
+  /** The ids the game itself published, when the refusal is about membership. */
+  readonly known?: readonly string[];
+}
+
+export type LiveSceneOpenResult =
+  | {
+      readonly ok: true;
+      readonly documentId: string;
+      readonly title: string;
+      /** The game's own answer: what was asked for, and where it ended up. */
+      readonly scene?: { readonly requested: string; readonly current: string | null };
+      /**
+       * Present when this open restarted play rather than navigating a live
+       * contract — the swap slot is a module-level const, so the honest
+       * live path is remount-at-key.
+       */
+      readonly restart?: true;
+    }
+  | LiveSceneOpenRefusal;
+
+/**
+ * Open ONE scene-table entry against the running game, or answer `null` when
+ * this entry is not the live half's business — a `story` reach has a portable
+ * mount, and a `none` reach is the adapter's own declared dead end. Both are
+ * the Edit half's, unchanged, and answering `null` is how this module says so
+ * rather than duplicating those refusals.
+ */
+export async function openLiveSceneEntry(
+  entry: DocumentEntry,
+  session: LiveSceneSession,
+): Promise<LiveSceneOpenResult | null> {
+  switch (entry.reach.kind) {
+    case 'game-contract': {
+      const scenes = session.scenes();
+      if (!scenes) {
+        return {
+          ok: false,
+          code: 'SCENE_CONTRACT_UNAVAILABLE',
+          error:
+            `open: "${entry.id}" is reached through the running game's own scenes contract, ` +
+            'and the game running in this session publishes none (`window.volterGame.scenes`).',
+        };
+      }
+      const switched = scenes.goToScene(entry.reach.sceneId);
+      if (!switched.ok) {
+        // The projection's own membership refusal, passed through: the game's
+        // `list()` is the authority on what it can be sent to, and a host
+        // paraphrase would be the host claiming to know the game's screens.
+        return {
+          ok: false,
+          code: 'SCENE_NOT_IN_CONTRACT',
+          error: `open: "${entry.id}" — ${switched.error}`,
+          known: switched.known,
+        };
+      }
+      const settled = await switched.settled;
+      if (settled.error !== undefined) {
+        return {
+          ok: false,
+          code: 'SCENE_SWITCH_FAILED',
+          error: `open: "${entry.id}" — the game's own navigation failed: ${settled.error}`,
+        };
+      }
+      // Activation is best-effort AFTER the switch: the navigation is the
+      // gesture, and a session with no Game document open (headless control,
+      // a workspace the user rearranged) still navigated the game.
+      session.activateGameDocument();
+      return {
+        ok: true,
+        documentId: session.gameDocumentId,
+        title: entry.label,
+        scene: { requested: settled.requested, current: settled.current },
+      };
+    }
+    case 'root-mount': {
+      // The running game IS this scene — mounting the region opened it — so the
+      // whole gesture is showing the document it draws into. REACHED, so the
+      // planner carries it as `liveReach: 'root-mount'` and the Edit half
+      // grades a no-game session `SCENE_NAVIGATION_NOT_RUNNING`: start the
+      // game and this returns ok. babylon-space-truckers' `splashScreen` is
+      // the shipped instance (`authorable: false`, so it owns no Edit
+      // document — pressing ▶ is the whole answer, not a defect in its
+      // declaration).
+      if (!session.activateGameDocument()) {
+        return {
+          ok: false,
+          code: 'SCENE_DOCUMENT_NOT_MOUNTED',
+          error: `open: "${entry.id}" is the running game itself, and no game document is open in this session.`,
+        };
+      }
+      return { ok: true, documentId: session.gameDocumentId, title: entry.label };
+    }
+    case 'entrypoint-selection': {
+      // The slot is a module-level CONST — the running module cannot change
+      // scenes. The honest live path is a host remount: stop this play run and
+      // start a new one with the entrypoint served at `key`. That is REAL
+      // navigation (the next mount executes that key), stated as a restart.
+      // A session with no remount seam (hosted bundle, ingest) still refuses
+      // coded — never an in-place fake.
+      const remount = session.remountSelection;
+      const regionId = entry.region;
+      if (!remount || regionId === null) {
+        return {
+          ok: false,
+          code: 'SCENE_NOT_OPENABLE_LIVE',
+          error:
+            `open: "${entry.id}" sits at the entrypoint's \`${entry.reach.selection}\` swap slot, ` +
+            'and this session has no live remount for a native swap-slot scene — a running game ' +
+            'cannot be sent there in place. Stop the game and open it as a document instead.',
+        };
+      }
+      const remounted = await remount({
+        selection: entry.reach.selection,
+        key: entry.reach.key,
+        regionId,
+      });
+      if (!remounted.ok) {
+        return {
+          ok: false,
+          code: 'SCENE_SWITCH_FAILED',
+          error: `open: "${entry.id}" — remount at \`${entry.reach.selection}["${entry.reach.key}"]\` failed: ${remounted.error}`,
+        };
+      }
+      session.activateGameDocument();
+      return {
+        ok: true,
+        documentId: session.gameDocumentId,
+        title: entry.label,
+        scene: { requested: entry.reach.key, current: entry.reach.key },
+        restart: true,
+      };
+    }
+    case 'story':
+    case 'none':
+      return null;
+  }
+}

package/src/kit/scoped-game-css.ts

@@ -0,0 +1,152 @@
+/**
+ * The client half of SCOPED GAME CSS — fetch the open project's page-level
+ * stylesheet (already rewritten into `@scope ([data-volter-game-styles])` by
+ * `@volter/sdk/session/scoped-game-css`), install it ONCE, and report honestly when
+ * there is nothing to install.
+ *
+ * ONE `<style>` element per project, never one per surface. Every container
+ * that owns game DOM — each UI-board story card's content, each story
+ * document's preview, the ingest surface the game mounts into — becomes a
+ * scope root by wearing the attribute (`markGameCssScope`, `game-css-scope.ts`),
+ * and the single scoped sheet paints all of them. Duplicating the sheet per
+ * card would multiply a foreign game's whole stylesheet by the size of the
+ * board for no behavioural difference at all.
+ *
+ * ## The refusal path is the point
+ *
+ * A surface that shows a game's DOM with no page CSS looks BROKEN, not empty —
+ * the owner hit exactly that three times before this existed and read it as
+ * wreckage, because nothing on screen said what was missing. So this module's
+ * state is a value the surfaces read (`note`), not a silent side effect: a
+ * board card whose project declares no stylesheet, or whose stylesheet could
+ * not be read, or a browser with no `@scope`, says so on the card.
+ *
+ * `@scope` is the feature detection and it is deliberately a REFUSAL, not a
+ * fallback: without it the served sheet's `:scope` rules would not be
+ * contained, and installing it anyway would restyle the editor — the precise
+ * failure the whole feature exists to prevent.
+ */
+
+import { editorConsole } from '@volter/sdk/kit/editor-console';
+import { editorServerJson } from '@volter/sdk/kit/editor-server-response';
+
+/** What the open project's game CSS turned out to be. */
+export interface ScopedGameStylesState {
+  /** True once the project's scoped stylesheet is attached to the document. */
+  readonly installed: boolean;
+  /** The declared stylesheet paths that were served, in emission order. */
+  readonly sources: readonly string[];
+  /**
+   * Surface-facing sentence naming what is missing, or `null` when the host
+   * has no evidence of a gap. Rendered ON a story card rather than logged,
+   * because the card is where the missing styling is SEEN.
+   */
+  readonly note: string | null;
+}
+
+const NOTHING_DECLARED: ScopedGameStylesState = { installed: false, sources: [], note: null };
+
+/** `data-*` marker on the one installed element, so a re-install can find it. */
+const STYLE_ELEMENT_MARKER = 'data-volter-scoped-game-css';
+
+/** Per-project memo: the fetch+install runs once per open project, not per card. */
+let pending: { projectRoot: string; state: Promise<ScopedGameStylesState> } | null = null;
+
+/** Latest resolved state, for the synchronous readers (a board painting notes). */
+let resolved: ScopedGameStylesState = NOTHING_DECLARED;
+
+/** The installed sheet's own text — see {@link scopedGameStylesCssText}. */
+let installedCss: string | null = null;
+
+/**
+ * The installed stylesheet's text, or null when none is installed.
+ *
+ * Exists for ONE reader: the DOM capture leg (`composite-screenshot.ts`),
+ * which rasterizes a DETACHED clone of the surface through an SVG
+ * `foreignObject`. A detached fragment carries no document stylesheet, so
+ * without re-inlining this the look verb would photograph a correctly styled
+ * screen as unstyled — an instrument disagreeing with the product it is
+ * pointed at, which is worse than no instrument. (The same leg already
+ * re-inlines its motion freeze for the same structural reason.)
+ */
+export function scopedGameStylesCssText(): string | null {
+  return installedCss;
+}
+
+/**
+ * True when this browser implements CSS `@scope`. Without it the served sheet
+ * cannot be contained, so nothing is installed at all.
+ */
+function supportsCssScope(): boolean {
+  return typeof (globalThis as { CSSScopeRule?: unknown }).CSSScopeRule === 'function';
+}
+
+/**
+ * Fetch and install the open project's scoped game stylesheet, at most once per
+ * project. Safe to call from every surface that mounts game DOM — later calls
+ * await the same promise.
+ */
+export async function ensureScopedGameStyles(projectRoot: string): Promise<ScopedGameStylesState> {
+  if (pending?.projectRoot === projectRoot) return pending.state;
+  const state = loadScopedGameStyles(projectRoot);
+  pending = { projectRoot, state };
+  return state;
+}
+
+/**
+ * The most recent resolved state. Surfaces that paint a note read this
+ * synchronously AFTER awaiting {@link ensureScopedGameStyles} — it exists so a
+ * board does not have to thread the promise through its own layout pass.
+ */
+export function scopedGameStylesState(): ScopedGameStylesState {
+  return resolved;
+}
+
+async function loadScopedGameStyles(projectRoot: string): Promise<ScopedGameStylesState> {
+  const next = await fetchScopedGameStyles(projectRoot);
+  resolved = next;
+  return next;
+}
+
+async function fetchScopedGameStyles(projectRoot: string): Promise<ScopedGameStylesState> {
+  let payload: { css?: unknown; sources?: unknown; note?: unknown };
+  try {
+    const response = await fetch('/__editor/scoped-game-css');
+    // A page fallback in front of the route fails the reader below and lands
+    // in the same graceful no-op story discovery takes. Nothing is claimed
+    // about the project's styling.
+    payload = await editorServerJson<typeof payload>(
+      response,
+      'Could not read the project scoped game CSS',
+    );
+  } catch {
+    return NOTHING_DECLARED;
+  }
+
+  const css = typeof payload.css === 'string' ? payload.css : '';
+  const sources = Array.isArray(payload.sources) ? (payload.sources as string[]) : [];
+  const note = typeof payload.note === 'string' ? payload.note : null;
+
+  if (css.length === 0) return { installed: false, sources, note };
+
+  if (!supportsCssScope()) {
+    const refusal =
+      'unstyled — this browser has no CSS `@scope`, so the game stylesheet cannot be contained ' +
+      'to the game. Loading it anyway would restyle the editor.';
+    editorConsole.warn(`[scoped-game-css] ${refusal}`, 'authoring');
+    return { installed: false, sources, note: refusal };
+  }
+
+  installStyleElement(projectRoot, css);
+  return { installed: true, sources, note };
+}
+
+/** Attach (or replace) the ONE style element carrying the project's game CSS. */
+function installStyleElement(projectRoot: string, css: string): void {
+  const existing = document.head.querySelector(`style[${STYLE_ELEMENT_MARKER}]`);
+  const element = existing instanceof HTMLStyleElement ? existing : document.createElement('style');
+  element.setAttribute(STYLE_ELEMENT_MARKER, projectRoot);
+  element.textContent = css;
+  if (!element.isConnected) document.head.appendChild(element);
+  installedCss = css;
+}