@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/live-session-registry.ts

@@ -0,0 +1,220 @@
+/**
+ * THE LIVE SESSIONS — what is running in this tab, registered by whoever
+ * mounts it (WORK.md §Play leaves the host, P1). The host never names Play,
+ * ingest or the module lane; it asks this registry "is anything live?",
+ * "is the editor playing?", "which element holds instance X?", and "stop
+ * everything" — the questions `editor-session-mode.ts`,
+ * `project-session-reset.ts`, `EditorLeaseGuard.tsx`,
+ * `RootSelectionOverlay.tsx` and `editor-view-presentation.ts` asked
+ * `play-mode.ts` by name until 2026-09-17. A package registers through
+ * `@volter/sdk/host`'s `live` member; the host's own lanes register
+ * here directly until they move.
+ */
+
+import type {
+  LiveCommand,
+  LiveCommandResult,
+  LiveCoverageReport,
+  LiveRemountArgs,
+  LiveRunWindow,
+  LiveSceneTable,
+  LiveSession,
+} from '@volter/sdk/host';
+
+interface Registered {
+  readonly session: LiveSession;
+  readonly seq: number;
+}
+let registered: Registered[] = [];
+let seq = 0;
+let version = 0;
+const listeners = new Set<() => void>();
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** A lane's own state moved (restart-required, its run window). */
+export function notifyLiveSessionsChanged(): void {
+  notify();
+}
+
+/** Every registered lane, in `stop` order. */
+export function liveSessions(): readonly LiveSession[] {
+  return ordered();
+}
+
+/** The newest run across lanes: the greatest `startedAt` any lane reports. */
+export function liveRunWindow(): LiveRunWindow | null {
+  let newest: LiveRunWindow | null = null;
+  for (const { session } of registered) {
+    const startedAt = session.startedAt?.() ?? null;
+    if (startedAt === null) continue;
+    if (!newest || startedAt > newest.startedAt)
+      newest = { startedAt, endedAt: session.endedAt?.() ?? null };
+  }
+  return newest;
+}
+
+export function liveRestartRequired(): string | null {
+  for (const { session } of registered) {
+    const reason = session.restartRequired?.() ?? null;
+    if (reason !== null) return reason;
+  }
+  return null;
+}
+
+/** Re-enter the lane that reports a restart is required, else the first
+ *  running lane that can restart. */
+export function restartLiveSession(): void {
+  const stale = ordered().find((session) => (session.restartRequired?.() ?? null) !== null);
+  const target = stale ?? ordered().find((session) => session.mounted() && session.restart);
+  target?.restart?.();
+}
+
+/** The canvas a mounted lane's own render pass draws, or null. */
+export function liveFrameCanvas(): HTMLCanvasElement | null {
+  for (const session of ordered()) {
+    if (!session.mounted()) continue;
+    const canvas = session.frameCanvas?.() ?? null;
+    if (canvas) return canvas;
+  }
+  return null;
+}
+
+/** The pixels of `canvas` from the lane whose render pass owns it; null when
+ *  no mounted lane claims that canvas. */
+export function snapshotLiveFrame(
+  canvas: HTMLCanvasElement,
+): Promise<CanvasImageSource | null> | null {
+  for (const session of ordered()) {
+    if (!session.mounted() || !session.snapshotFrame) continue;
+    if (session.frameCanvas?.() === canvas) return session.snapshotFrame();
+  }
+  return null;
+}
+
+/** The first mounted lane's own answer to `cmd`, or null when none claims it. */
+export function dispatchLiveCommand(cmd: LiveCommand): LiveCommandResult | null {
+  for (const session of ordered()) {
+    if (!session.mounted() || !session.command) continue;
+    const answered = session.command(cmd);
+    if (answered) return answered;
+  }
+  return null;
+}
+
+/**
+ * The running lane's scene entries, or null.
+ *
+ * The shape check is STRUCTURAL and stays here rather than importing a lane's
+ * own type guard (it imported the ingest lane's `isContractScenesStories`,
+ * by name, until 2026-09-18, and with it the whole `window.volterGame` contract
+ * — an INGEST vocabulary inside the registry every lane registers through).
+ * `LiveSceneTable` is a declaration, and a lane is foreign code: the
+ * host checks that the declaration is honoured before handing the table to the
+ * `open` verb, and names no lane doing it.
+ */
+export function liveScenes(): LiveSceneTable | null {
+  for (const session of ordered()) {
+    if (!session.mounted()) continue;
+    const scenes = session.scenes?.() ?? null;
+    if (scenes && typeof scenes.goToScene === 'function') return scenes;
+  }
+  return null;
+}
+
+/** The native surface the mounted lane's content draws on, or null. */
+export function liveSurface(): 'three' | 'canvas' | 'dom' | null {
+  for (const session of ordered()) {
+    if (!session.mounted()) continue;
+    const surface = session.surface?.() ?? null;
+    if (surface) return surface;
+  }
+  return null;
+}
+
+/** The mounted lane's own coverage report, or null when none grades itself. */
+export function liveCoverage(): LiveCoverageReport | null {
+  for (const session of ordered()) {
+    if (!session.mounted()) continue;
+    const report = session.coverage?.() ?? null;
+    if (report) return report;
+  }
+  return null;
+}
+
+/** Why authoring is off for the mounted lane's content, or null. */
+export function liveAuthoringRefusal(): string | null {
+  for (const session of ordered()) {
+    if (!session.mounted()) continue;
+    const reason = session.authoringRefusal?.() ?? null;
+    if (reason !== null) return reason;
+  }
+  return null;
+}
+
+/** Ask the running lane to re-mount with an authored selection; null when
+ *  no running lane can. */
+export function remountLiveSelection(
+  args: LiveRemountArgs,
+): Promise<{ ok: true } | { ok: false; error: string }> | null {
+  const target = ordered().find((session) => session.mounted() && session.remount);
+  return target?.remount?.(args) ?? null;
+}
+
+/** Register a lane. `stop` order follows `priority` (low first), then
+ *  registration: a normal stop tears down Play before ingest. */
+export function registerLiveSession(session: LiveSession): () => void {
+  if (registered.some((entry) => entry.session.id === session.id))
+    throw new Error(`live session "${session.id}" is already registered.`);
+  const entry: Registered = { session, seq: seq++ };
+  registered = [...registered, entry];
+  notify();
+  return () => {
+    registered = registered.filter((other) => other !== entry);
+    notify();
+  };
+}
+
+function ordered(): readonly LiveSession[] {
+  return [...registered]
+    .sort((a, b) => (a.session.priority ?? 0) - (b.session.priority ?? 0) || a.seq - b.seq)
+    .map((entry) => entry.session);
+}
+
+/** A real game owns a canvas: Play, an ingested game, an auto-mounted module world. */
+export function anyLiveSessionMounted(): boolean {
+  return ordered().some((session) => session.mounted());
+}
+
+/** The editor is in PLAY: somebody asked the host to run content. A held
+ *  (paused-at-design-time) mount is not playing. */
+export function anyLiveSessionPlaying(): boolean {
+  return ordered().some((session) => session.playing());
+}
+
+/** Stop every lane, in priority order; each stop is idempotent and a no-op
+ *  when its lane runs nothing. */
+export function stopAllLiveSessions(): void {
+  for (const session of ordered()) session.stop();
+}
+
+/** The element holding a live instance — the primary when `id` is omitted —
+ *  from whichever lane holds it. */
+export function liveInstanceContainer(id?: string): HTMLElement | null {
+  for (const session of ordered()) {
+    const container = session.instanceContainer(id);
+    if (container) return container;
+  }
+  return null;
+}
+
+export function subscribeLiveSessions(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function liveSessionsVersion(): number {
+  return version;
+}

package/src/kit/live-transition.ts

@@ -0,0 +1,391 @@
+/**
+ * THE LIVE TRANSITION — the immersive Liquid Glass hand-off between
+ * authoring chrome and the running game, the host's side of
+ * `host.viewport.transition` (WORK.md §Play leaves the host, P3). A lane
+ * says when it starts (`beginLiveTransition`), when it is ready and when it
+ * ends; the host decides whether the presentation is immersive and resolves
+ * the flight target from the authored scene.
+ *
+ * On Play: the chrome dissolves, the editor viewport camera flies along a
+ * Catmull-Rom spline from the preview pose to the AUTHORED game camera's
+ * pose, and when both the flight has landed and the game runtime is ready the
+ * Scene document cross-fades into the Game document. On Stop everything
+ * reverses: camera snaps back to the pre-play preview pose and the chrome
+ * re-materializes. `prefers-reduced-motion` collapses the whole choreography
+ * to instant state changes with the same end state.
+ *
+ * Layering: this module owns TIMING, and it touches no layout at all. The
+ * camera flight is the Three integration's (`@volter/sdk/kit/play-camera-flight`,
+ * registered by `@volter/editor-threejs`'s `play-camera-flight.ts`). The LAYOUT HOST registers `hideChrome`/`showChrome` through
+ * {@link installPlayTransitionDock} — under the Code-OSS frame those are the
+ * workbench's own parts going away and coming back (`frame/bridge.tsx`'s
+ * `setImmersive`), which is the same inversion `workspace-host-commands.ts`
+ * uses for semantic commands. Workspace persistence is suppressed for the
+ * whole immersive play session (`setWorkspacePersistenceSuppressed`) so a
+ * play-time open set can never overwrite the user's own. A non-immersive play
+ * never enters this controller: it keeps the ordinary workspace visible.
+ *
+ * The pure parts — the durations, the phase reducer — are plain functions
+ * with no DOM.
+ */
+
+import { layoutPolicy } from './layout-policy';
+import { effectiveSettings } from '@volter/sdk/kit/settings-store';
+import { type LiveCameraLookup, playCameraFlight } from '@volter/sdk/kit/play-camera-flight';
+import { setWorkspacePersistenceSuppressed } from './workspace-persistence-gate';
+
+/** Full-bleed play is the MOUNTED LAYOUT's own declaration
+ *  (`WorkspaceLayoutPolicy.immersivePlay` — `GameLayout` is the shipped
+ *  instance); no appearance axis implies it. */
+export function usesImmersivePlayPresentation(): boolean {
+  return (layoutPolicy()?.immersivePlay ?? false) && !effectiveSettings().play?.keepPanelsVisible;
+}
+
+
+
+
+
+// ---------------------------------------------------------------------------
+// Pure transition phase reducer
+// ---------------------------------------------------------------------------
+
+export type PlayTransitionPhase =
+  | 'idle'
+  /** Dissolve + flight running concurrently. */
+  | 'entering'
+  /** Flight landed but the game runtime is still booting — hold the pose. */
+  | 'holding'
+  /** Both done — Scene → Game opacity cross-fade in progress. */
+  | 'crossfade'
+  /** Hand-off complete; game owns the screen until stop. */
+  | 'playing';
+
+export type PlayTransitionEvent =
+  | 'start'
+  | 'start-reduced'
+  | 'flight-done'
+  | 'game-ready'
+  | 'crossfade-done'
+  | 'stop';
+
+export interface PlayTransitionState {
+  readonly phase: PlayTransitionPhase;
+  readonly flightDone: boolean;
+  readonly gameReady: boolean;
+}
+
+export const IDLE_TRANSITION_STATE: PlayTransitionState = {
+  phase: 'idle',
+  flightDone: false,
+  gameReady: false,
+};
+
+function reduceEnteringPhase(
+  state: PlayTransitionState,
+  event: PlayTransitionEvent,
+): PlayTransitionState {
+  const flightDone = state.flightDone || event === 'flight-done';
+  const gameReady = state.gameReady || event === 'game-ready';
+  if (flightDone && gameReady) return { phase: 'crossfade', flightDone, gameReady };
+  if (flightDone) return { phase: 'holding', flightDone, gameReady };
+  return { ...state, flightDone, gameReady };
+}
+
+/** Pure phase reducer — every timing side effect lives in the controller. */
+export function reducePlayTransition(
+  state: PlayTransitionState,
+  event: PlayTransitionEvent,
+): PlayTransitionState {
+  if (event === 'stop') return IDLE_TRANSITION_STATE;
+  switch (state.phase) {
+    case 'idle':
+      if (event === 'start') return { phase: 'entering', flightDone: false, gameReady: false };
+      if (event === 'start-reduced') return { phase: 'playing', flightDone: true, gameReady: true };
+      return state;
+    case 'entering':
+      return reduceEnteringPhase(state, event);
+    case 'holding':
+      if (event === 'game-ready') return { ...state, phase: 'crossfade', gameReady: true };
+      return state;
+    case 'crossfade':
+      if (event === 'crossfade-done') return { ...state, phase: 'playing' };
+      return state;
+    case 'playing':
+      return state;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Pure edge-reveal machine (macOS auto-hide semantics)
+//
+// GLOBAL reveal (owner decision, 2026-07-20): dwelling at ANY screen edge
+// reveals ALL the play chrome together — header, hierarchy, inspector,
+// assets, bottom bar — and it all retracts together once the pointer leaves
+// both the hot zones and every revealed surface. Per-edge independent
+// reveals (the original design) made the chrome feel unpredictable and
+// forced users to hunt each panel at its own edge.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Controller — DOM / viewport integration seams
+// ---------------------------------------------------------------------------
+
+/**
+ * THE TRANSITION'S DURATIONS, owned here and read by the stylesheet.
+ *
+ * Every one of these is a JS timer AND a CSS animation: the phase machine
+ * schedules the next step off the constant while `workspace-surfaces.css`
+ * animates the pixels, so a mismatch is not a cosmetic drift — it advances the machine
+ * before the frames land (a half-dissolved chrome snapped away mid-fade) or
+ * holds it after they do. They used to be typed twice, with three comments here
+ * saying "must match the CSS", which is a hand-maintained equality across two
+ * files and no checker.
+ *
+ * They are published as custom properties by
+ * {@link publishPlayTransitionDurations}, from {@link installPlayTransitionDock}
+ * — which is also what makes an unpublished property unreachable rather than a
+ * silent failure: nothing ever adds `volter-play-chrome-exit`,
+ * `volter-play-chrome-enter` or `volter-play-crossfade` except this module, and
+ * this module cannot act before the host is installed.
+ */
+
+/** Chrome dissolve. CSS: `--volter-play-dissolve-duration`. */
+export const PLAY_DISSOLVE_MS = 450;
+/** Fast, unstaggered re-materialization after a reveal request. CSS:
+ *  `--volter-play-materialize-duration`. */
+export const PLAY_MATERIALIZE_MS = 220;
+/** Per-element stagger step, published as `--volter-play-stagger`. */
+export const PLAY_DISSOLVE_STAGGER_MS = 50;
+/** Scene→Game opacity cross-fade. CSS: `--volter-play-crossfade-duration`. */
+export const PLAY_CROSSFADE_MS = 250;
+
+/**
+ * Hand the three durations above to the stylesheet. On the document element,
+ * so they inherit everywhere the play classes can land — a host may park a
+ * surface in a top-level overlay outside the root it handed us.
+ */
+function publishPlayTransitionDurations(root: HTMLElement): void {
+  root.style.setProperty('--volter-play-dissolve-duration', `${PLAY_DISSOLVE_MS}ms`);
+  root.style.setProperty('--volter-play-materialize-duration', `${PLAY_MATERIALIZE_MS}ms`);
+  root.style.setProperty('--volter-play-crossfade-duration', `${PLAY_CROSSFADE_MS}ms`);
+}
+
+/** What the LAYOUT HOST registers: chrome hide/show plus the root element the
+ *  flight/cross-fade CSS classes land on. Whatever draws the chrome stays
+ *  behind this seam — under the frame it is the workbench's own parts. */
+export interface PlayTransitionDockHooks {
+  root: HTMLElement;
+  hideChrome(animate: boolean): void;
+  showChrome(animate: boolean): void;
+}
+
+/** The narrow viewport surface the flight needs (the world root's stage registers the
+ *  real EditorViewport; unit tests pass a fake). */
+
+
+let _dock: PlayTransitionDockHooks | null = null;
+
+export function installPlayTransitionDock(hooks: PlayTransitionDockHooks): () => void {
+  _dock = hooks;
+  if (typeof document !== 'undefined') publishPlayTransitionDurations(document.documentElement);
+  return () => {
+    if (_dock === hooks) _dock = null;
+  };
+}
+
+export function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== 'undefined' &&
+    (window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false)
+  );
+}
+
+
+
+
+
+
+
+interface ActiveTransition {
+  state: PlayTransitionState;
+  reducedMotion: boolean;
+  /** The viewport is flying (`kit/play-camera-flight`): a viewport and an authored camera existed. */
+  flying: boolean;
+  timeouts: Set<ReturnType<typeof setTimeout>>;
+}
+
+let _active: ActiveTransition | null = null;
+
+/** Current phase (exported for tests/e2e via the debug handle below). */
+export function playTransitionPhase(): PlayTransitionPhase {
+  return _active?.state.phase ?? 'idle';
+}
+
+// --- Settle listeners --------------------------------------------------------
+
+const _settleListeners = new Set<() => void>();
+
+function flushSettleListeners(): void {
+  if (_settleListeners.size === 0) return;
+  const fns = [..._settleListeners];
+  _settleListeners.clear();
+  for (const fn of fns) fn();
+}
+
+/**
+ * Run `fn` once the play-entry transition SETTLES — the cross-fade completed
+ * (phase 'playing') or the transition tore down early (Stop/Escape/boot
+ * failure) — or immediately when no transition is in flight. One-shot.
+ *
+ * This is the hand-off point for work that must NOT happen while the flight
+ * still renders the editor viewport: the R3F design session keeps its adopted
+ * fiber scene alive under the flight (suspending at the playState flip made
+ * the whole screen flash the placeholder scene's clear color) and suspends
+ * here instead. Settle can mean "play never happened" as well as "play is
+ * fully on screen" — callbacks must re-check store state.
+ */
+export function onPlayTransitionSettled(fn: () => void): void {
+  if (!_active || _active.state.phase === 'playing') {
+    fn();
+    return;
+  }
+  _settleListeners.add(fn);
+}
+
+function later(active: ActiveTransition, ms: number, fn: () => void): void {
+  const handle = setTimeout(() => {
+    active.timeouts.delete(handle);
+    fn();
+  }, ms);
+  active.timeouts.add(handle);
+}
+
+
+function dispatch(event: PlayTransitionEvent): void {
+  const active = _active;
+  if (!active) return;
+  const prev = active.state;
+  const next = reducePlayTransition(prev, event);
+  if (next === prev) return;
+  active.state = next;
+  if (next.phase === 'crossfade' && prev.phase !== 'crossfade') {
+    _dock?.root.classList.add('volter-play-crossfade');
+    later(active, PLAY_CROSSFADE_MS + 30, () => dispatch('crossfade-done'));
+  }
+  if (next.phase === 'playing' && prev.phase !== 'playing') {
+    _dock?.root.classList.remove('volter-play-flight', 'volter-play-crossfade');
+    if (active.flying) playCameraFlight()?.settle();
+    flushSettleListeners();
+  }
+}
+
+
+/**
+ * Begin the play-entry transition. Called by `play-mode.ts` immediately
+ * before `setPlayState('playing')`. Never blocks play — all choreography is
+ * fire-and-forget alongside the runtime boot. Safe no-op degradation when no
+ * dock/viewport is registered (headless unit-test stores).
+ */
+export interface PlayEntryTransitionOptions {
+  readonly immersive: boolean;
+}
+
+/**
+ * A lane is starting: call BEFORE the session flips to playing. The mounted
+ * layout chooses immersive Play; when
+ * immersive, the authored camera MUST be resolved here, before playState
+ * changes — the R3F design session then suspends and removes its drei camera
+ * from the store. Every exit path funnels through `endPlayTransition`.
+ */
+export function beginLiveTransition(): void {
+  beginPlayEntryTransition({ immersive: usesImmersivePlayPresentation() });
+}
+
+export function beginPlayEntryTransition(options: PlayEntryTransitionOptions): void {
+  if (_active) endPlayTransition();
+  // Non-immersive play has no transition state, persistence gate, camera
+  // flight, or chrome mutation at all.
+  if (!options.immersive) return;
+  const reducedMotion = prefersReducedMotion();
+  setWorkspacePersistenceSuppressed(true);
+  const active: ActiveTransition = {
+    state: IDLE_TRANSITION_STATE,
+    reducedMotion,
+    flying: false,
+    timeouts: new Set(),
+  };
+  _active = active;
+  _dock?.hideChrome(!reducedMotion);
+
+  if (reducedMotion) {
+    dispatch('start-reduced');
+    return;
+  }
+  dispatch('start');
+
+  // The flight resolves the authored camera NOW, before playState changes (the R3F design
+  // session then suspends and removes its drei camera from the store).
+  active.flying = playCameraFlight()?.begin(() => { if (_active === active) dispatch('flight-done'); }) ?? false;
+  if (!active.flying) {
+    // No authored camera (or headless): dissolve still runs, no flight.
+    dispatch('flight-done');
+    return;
+  }
+  _dock?.root.classList.add('volter-play-flight');
+}
+
+/**
+ * Reconcile an already-running session with appearance-axis changes. Moving
+ * away from an immersive presentation must restore the chrome immediately;
+ * moving into one mid-session deliberately does not replay entry
+ * choreography.
+ */
+export function reconcilePlayPresentationPolicy(isPlaying: boolean, immersive: boolean): void {
+  if (!isPlaying || !immersive) endPlayTransition();
+}
+
+/**
+ * The game runtime finished its async boot (play-mode's ack point).
+ * `getLiveCamera` gives the flight its final convergence target — the game's
+ * actual render camera — so the cross-fade is pixel-continuous even when game
+ * code repositions the camera during boot.
+ */
+export function notifyPlayTransitionGameReady(getLiveCamera?: LiveCameraLookup): void {
+  const active = _active;
+  if (!active) return;
+  if (active.flying && getLiveCamera) playCameraFlight()?.track(getLiveCamera);
+  dispatch('game-ready');
+}
+
+
+
+
+/**
+ * Tear the transition down (Stop/Escape/boot failure — any exit path).
+ * Restores the pre-play camera pose, re-materializes the chrome, and
+ * re-enables layout persistence. Idempotent.
+ */
+export function endPlayTransition(): void {
+  const active = _active;
+  if (!active) return;
+  _active = null;
+  for (const handle of active.timeouts) clearTimeout(handle);
+  active.timeouts.clear();
+  // Early teardown is also "settled" — deferred hand-off work (see
+  // onPlayTransitionSettled) must run, and its store-state guards decide
+  // whether there is anything left to do.
+  flushSettleListeners();
+  _dock?.root.classList.remove('volter-play-flight', 'volter-play-crossfade');
+
+  if (active.flying) playCameraFlight()?.end();
+
+  _dock?.showChrome(!prefersReducedMotion());
+  setWorkspacePersistenceSuppressed(false);
+}
+
+// Dev/e2e handle: lets specs observe the transition phase deterministically.
+if (typeof window !== 'undefined' && (import.meta as ImportMeta & { env?: { DEV?: boolean } }).env?.DEV) {
+  (window as unknown as Record<string, unknown>)['__volterPlayTransition'] = {
+    phase: playTransitionPhase,
+  };
+}