@volter/editor-core 0.5.57

package/src/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/editor-sdk/host';
+import type { DocumentEntry } from '@volter/editor-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.vgaiGame.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/scene-view-fog.ts

@@ -0,0 +1,89 @@
+import type * as THREE from 'three';
+
+/**
+ * Why the Scene viewport draws a world's fog OUT.
+ *
+ * ## The measured defect
+ *
+ * Fog is calibrated in metres from THE GAME'S OWN CAMERA. The racing-game
+ * mount declares `<fog args={['white', 0, 500]}>`, which is exactly right at
+ * its chase camera 20 units behind the car and meaningless anywhere else: its
+ * world is ~800 units across, so the editor framing that shows the whole track
+ * sits ~700 units back, and every visible surface is past the fog's far plane.
+ * Measured on that mount (2026-08-15): the framed Scene view is a featureless
+ * white blob — the track, the canyon and the horizon are all the same white.
+ *
+ * The Scene camera is not the game's camera. It is placed by framing, by a
+ * seed, or by the reader's own orbit, at whatever distance the world needs —
+ * so a distance-calibrated effect authored for another camera is not a look,
+ * it is an erasure.
+ *
+ * ## Why a view policy and not fog-aware framing
+ *
+ * The alternative was to have the framing respect the fog range — pick a
+ * distance inside it. It cannot work, and the numbers say so rather than an
+ * argument: this world's content diagonal is ~1,100 units against a fog far
+ * plane of 500, so no distance both shows the track and stays readable. Any
+ * fog-aware framing would have to stop showing the world to keep the fog,
+ * which is backwards — the first look exists to show the world.
+ *
+ * So the fog goes, as a VIEW POLICY, in the same class as the shading modes:
+ * presentation-only, restored before anything else can observe it, and applied
+ * only to the editor's own draw. This is also the established answer in the
+ * genre — Unity's Scene view renders fog OFF by default and offers it as a
+ * scene-view effect toggle, for exactly this reason.
+ *
+ * The game's own look is not touched anywhere it belongs: the Game tab, play
+ * mode and every exported build render the game's camera through the game's
+ * fog. Only the authoring camera is exempted, and there is deliberately no
+ * toggle for it — a Scene view that can be washed white by a setting is a
+ * fault the reader has to diagnose, and nothing here is worth that.
+ *
+ * ## Why the parameters and not `scene.fog = null`
+ *
+ * `!!scene.fog` is part of three's shader-program cache key, so nulling it for
+ * one draw and restoring it for the next compiles and keeps a SECOND program
+ * variant for every material in the world. Neutralising the fog's own numbers
+ * leaves the program identical and the fog term at zero.
+ */
+
+/** Far enough that no real depth reaches it; `near < far` keeps the linear
+ *  fog's `smoothstep(near, far, depth)` well-defined. */
+const NEUTRAL_FOG_NEAR = 1e20;
+const NEUTRAL_FOG_FAR = 2e20;
+
+type LinearFog = THREE.Fog & { isFog: true };
+type ExpFog = THREE.FogExp2 & { isFogExp2: true };
+
+/**
+ * Run `draw` with `scene`'s fog contributing nothing, then put it back exactly
+ * as it was — including when `draw` throws.
+ *
+ * A scene with no fog costs one property read.
+ */
+export function withSceneFogNeutralized(scene: THREE.Scene, draw: () => void): void {
+  const fog = scene.fog;
+  if (!fog) {
+    draw();
+    return;
+  }
+  const linear = (fog as LinearFog).isFog ? (fog as LinearFog) : null;
+  const exponential = (fog as ExpFog).isFogExp2 ? (fog as ExpFog) : null;
+  const near = linear?.near;
+  const far = linear?.far;
+  const density = exponential?.density;
+  if (linear) {
+    linear.near = NEUTRAL_FOG_NEAR;
+    linear.far = NEUTRAL_FOG_FAR;
+  }
+  if (exponential) exponential.density = 0;
+  try {
+    draw();
+  } finally {
+    if (linear && near !== undefined && far !== undefined) {
+      linear.near = near;
+      linear.far = far;
+    }
+    if (exponential && density !== undefined) exponential.density = density;
+  }
+}

package/src/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-vgai-game-styles])` by
+ * `server/scoped-game-css.ts`), 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 './editor-console';
+import { editorServerJson } from './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-vgai-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;
+}

package/src/session-orphan-record.ts

@@ -0,0 +1,193 @@
+/**
+ * THE NOTE A DYING TAB LEAVES FOR THE NEXT ONE.
+ *
+ * When an editor page decides its server is gone it raises an overlay — and
+ * that overlay is the only place the fact has ever existed. Close the tab, or
+ * let the browser discard it, and the entire episode is unrecoverable: the
+ * server it would have been reported to is precisely the thing that died, so
+ * no journal, no `vgai console` and no later session has any record that a
+ * window sat there orphaned. A human who steps away and comes back to a
+ * relaunched editor is left to reconstruct it from how slow things felt.
+ *
+ * Measured 2026-08-19: that reconstruction cost about an hour.
+ *
+ * So the page writes the fact somewhere its dead server cannot reach and
+ * cannot erase — `localStorage`, keyed by ORIGIN, which is exactly the scope of
+ * "the server that was serving this address". The next editor to boot on that
+ * address picks the note up, says it out loud once through the ordinary console
+ * door (so it reaches `vgai console` and the session journal like every other
+ * editor fact), and clears it.
+ *
+ * The split here is deliberate: everything that decides or formats is a pure
+ * function over plain data, and the two functions that touch `localStorage` do
+ * nothing else. That is what lets the whole behaviour be tested without a
+ * browser, and it is why the storage handle is a parameter rather than a
+ * global reach.
+ */
+
+/** Why the tab that wrote this note stopped being a live editor. Only the
+ *  UNGRACEFUL deaths are worth a note: a session the user closed on purpose is
+ *  not a mystery anybody needs solved later. */
+export type OrphanReason = 'server-gone';
+
+export interface SessionOrphanRecord {
+  /** When the page decided it, epoch ms. */
+  readonly at: number;
+  readonly reason: OrphanReason;
+  /** The project the dead session was serving, as the tab last knew it.
+   *  `null` when the tab never got a successful identity poll. */
+  readonly project: string | null;
+}
+
+/** One key, versioned, namespaced like the editor's other per-user state.
+ *  `localStorage` is already per-origin, so the key needs no port in it — and
+ *  must not have one, or a note would be invisible to the very session that
+ *  replaced the writer. */
+export const SESSION_ORPHAN_KEY = 'vgai.editor.orphaned-tab.v1';
+
+/**
+ * Parse a stored note, rejecting anything that is not one.
+ *
+ * Strict and silent: this reads a value any page on the origin could have
+ * written, and a boot path is the wrong place to throw. Unusable input is
+ * simply "no note" — the same answer as an empty slot, which is the honest one
+ * since a malformed note tells us nothing about any session.
+ */
+export function decodeSessionOrphanRecord(raw: string | null): SessionOrphanRecord | null {
+  if (!raw) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null;
+  const record = parsed as Partial<SessionOrphanRecord>;
+  if (typeof record.at !== 'number' || !Number.isFinite(record.at)) return null;
+  if (record.reason !== 'server-gone') return null;
+  const project = typeof record.project === 'string' ? record.project : null;
+  return { at: record.at, reason: record.reason, project };
+}
+
+export function encodeSessionOrphanRecord(record: SessionOrphanRecord): string {
+  return JSON.stringify(record);
+}
+
+/**
+ * The sentence the next session says.
+ *
+ * It names the three things a reader needs and cannot otherwise get: WHEN the
+ * previous window lost its server, WHICH project it was on, and — the part
+ * that closes the hour of misdiagnosis — that the stale window is still open
+ * and is not the one they are now looking at.
+ */
+export function describeSessionOrphan(record: SessionOrphanRecord, now: number): string {
+  const ageSeconds = Math.max(0, Math.round((now - record.at) / 1000));
+  const ago =
+    ageSeconds < 90
+      ? `${ageSeconds}s ago`
+      : ageSeconds < 5400
+        ? `${Math.round(ageSeconds / 60)}m ago`
+        : `${Math.round(ageSeconds / 3600)}h ago`;
+  const project = record.project ? ` on ${record.project}` : '';
+  return (
+    `A previous editor window at this address lost its server ${ago}${project} and was left ` +
+    'orphaned. If that window is still open it is a stale snapshot — nothing in it is saved and ' +
+    'every click in it hangs on retries. Close it; this window is the live one.'
+  );
+}
+
+/**
+ * How long a note stays worth saying, ms.
+ *
+ * A note is about the session the reader is replacing, so it goes stale fast:
+ * a day later it is archaeology, and reporting it would train people to ignore
+ * the message that matters. Twelve hours covers "I came back the next
+ * morning" without reaching into last week.
+ */
+export const SESSION_ORPHAN_MAX_AGE_MS = 12 * 60 * 60 * 1000;
+
+/** Whether a note is recent enough for the booting session to say out loud.
+ *  A note from the FUTURE (a clock the user moved) is not usable evidence
+ *  either, and is dropped by the same bar. */
+export function sessionOrphanIsWorthReporting(record: SessionOrphanRecord, now: number): boolean {
+  const age = now - record.at;
+  return age >= 0 && age <= SESSION_ORPHAN_MAX_AGE_MS;
+}
+
+/** The storage this module needs — narrowed to the three calls it makes so a
+ *  test can pass a plain object and so no caller is tempted to hand it the
+ *  whole `Window`. */
+export interface OrphanRecordStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/** The page's own `localStorage`, or `null` where there is none (SSR, jsdom
+ *  without storage, a browser refusing it in private mode). Every caller
+ *  tolerates `null`: a note is a diagnostic, never a precondition. */
+export function defaultOrphanRecordStorage(): OrphanRecordStorage | null {
+  try {
+    return typeof localStorage === 'undefined' ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Leave the note. Called at the moment the page raises its "server is gone"
+ * overlay, so the durable record and the visible one are the same event.
+ *
+ * A write failure is swallowed on purpose — a full or blocked `localStorage`
+ * must not stop the page from telling the user what happened, which is the
+ * half that actually matters.
+ */
+export function writeSessionOrphanRecord(
+  record: SessionOrphanRecord,
+  storage: OrphanRecordStorage | null = defaultOrphanRecordStorage(),
+): void {
+  try {
+    storage?.setItem(SESSION_ORPHAN_KEY, encodeSessionOrphanRecord(record));
+  } catch {
+    /* diagnostics never break the page — see above */
+  }
+}
+
+/**
+ * Read and CLEAR the note in one step.
+ *
+ * Taking rather than peeking is the whole contract: the note describes one
+ * episode, so it must be said once. A read that left it behind would have every
+ * subsequent boot repeating a stale warning until the user learned to ignore
+ * the channel.
+ */
+export function takeSessionOrphanRecord(
+  storage: OrphanRecordStorage | null = defaultOrphanRecordStorage(),
+): SessionOrphanRecord | null {
+  if (!storage) return null;
+  try {
+    const record = decodeSessionOrphanRecord(storage.getItem(SESSION_ORPHAN_KEY));
+    storage.removeItem(SESSION_ORPHAN_KEY);
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Drop the note without reporting it.
+ *
+ * The `resume` branch: the same process answered again, so the page was never
+ * orphaned and the note it wrote a moment ago is simply wrong. Retracting it
+ * here is what keeps the record trustworthy enough to act on.
+ */
+export function clearSessionOrphanRecord(
+  storage: OrphanRecordStorage | null = defaultOrphanRecordStorage(),
+): void {
+  try {
+    storage?.removeItem(SESSION_ORPHAN_KEY);
+  } catch {
+    /* see writeSessionOrphanRecord */
+  }
+}