@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/surface-keyboard.ts

@@ -0,0 +1,101 @@
+/**
+ * DOES OUR SURFACE HOLD THE KEYBOARD? — the term the play-input predicate was
+ * missing, and it was missing because until the Code-OSS frame there was
+ * nothing else on the page that could want a keystroke.
+ *
+ * The documented rule is "game input only fires while play is running AND the
+ * Game tab is active" (the repo's CLAUDE.md, §Play-mode input isolation), and
+ * standalone the editor's `edit` command those two clauses are the whole truth: the editor page
+ * IS the surface, so a keystroke that reaches it was meant for it. Under the
+ * frame (WORK.md §The core is Code-OSS, U2) the page is a VS Code workbench and
+ * our stage is ONE EDITOR PANE in it. A person typing into Monaco in the group
+ * beside a running game is typing into the same `document` the game's listeners
+ * are on, and both clauses above are still true — the game is playing and the
+ * Game document is still the active volter document, because activating another
+ * EDITOR did not close it. So the keystroke lands in the file AND moves the
+ * game. That is U6's incident (keys typed into Monaco reaching the volter
+ * viewport as hotkeys, twice measured) repeated one layer down, on the GAME's
+ * input rather than the editor's, and U6's fix does not cover it: keyboard
+ * OWNERSHIP decides which dispatcher owns a chord, while this decides whether a
+ * running game hears raw DOM events at all.
+ *
+ * ## Why this is a third TERM and not a correction to the second
+ *
+ * The obvious-looking fix — have the frame write `activeViewportTab = 'edit'`
+ * when the pane stops being the active editor — is a defect, and the code says
+ * so out loud: `syncCenterDocuments` (`components/CenterDocuments.tsx`) reads an
+ * `'edit'` tab with the GAME document active as a genuine disagreement and
+ * activates the SCENE document to correct it. Under the frame the layout host
+ * renders the ACTIVE document into the editor pane, so that correction would
+ * unmount the Game document, release the live document's container out from
+ * under the running runtime, and end the game. The tab is about WHICH DOCUMENT
+ * is open, the probe below is about WHO IS TYPING, and conflating them costs
+ * the game.
+ *
+ * ## The shape
+ *
+ * A single installed probe, default absent, and absent means TRUE. Standalone
+ * nothing installs one and every predicate reads exactly as it did before this
+ * module existed — the same "an unset value is upstream's own behaviour"
+ * discipline U9's core edit follows. The frame installs one from the workbench's
+ * own notion of the active editor (`ActiveEditorContext` over the volter pane's
+ * type id), which is the right question rather than DOM focus: clicking a game
+ * canvas that carries no `tabindex` moves focus to `body` while the pane stays
+ * the active editor, and gating on focus would have killed input on the first
+ * click into the game.
+ *
+ * ## Its reader
+ *
+ * `gated-globals.ts` covers every RAW `window`/`document` listener a project
+ * module registers — first-party games, ingest mounts and the module lane
+ * alike, since the dev server's lexical shadow is what they all go through. It
+ * reads this per event through play mode's `instanceInputActive`, so a change
+ * of answer needs no notification.
+ */
+
+type SurfaceKeyboardProbe = () => boolean;
+
+let probe: SurfaceKeyboardProbe | null = null;
+
+/**
+ * True while the surface a game is mounted in holds the keyboard.
+ *
+ * Absent probe = true, deliberately: the standalone editor page is the only
+ * surface there is, and a host that has not answered must never be read as a
+ * refusal — a silently dead keyboard is the worst failure this module could
+ * have.
+ */
+export function surfaceHoldsKeyboard(): boolean {
+  if (!probe) return true;
+  try {
+    return probe();
+  } catch {
+    // A probe that throws is a broken frame, not a person who stopped typing.
+    return true;
+  }
+}
+
+/** Raw play input belongs to the active surface, never to a text field. */
+export function surfaceAcceptsKey(event: KeyboardEvent): boolean {
+  const target = event.target;
+  return surfaceHoldsKeyboard() && !(target instanceof HTMLElement &&
+    (target.isContentEditable || target.closest('input, textarea, select') !== null));
+}
+
+/**
+ * Install the frame's answer. Returns the uninstall, which restores the
+ * always-true default rather than leaving the last answer pinned — a frame
+ * going away must not leave a game deaf.
+ */
+export function setSurfaceKeyboardProbe(next: SurfaceKeyboardProbe | null): () => void {
+  probe = next;
+  return () => {
+    if (probe !== next) return;
+    probe = null;
+  };
+}
+
+/** Test-only reset. */
+export function __resetSurfaceKeyboardForTest(): void {
+  probe = null;
+}

package/src/kit/surface-state.ts

@@ -0,0 +1,135 @@
+import type { MountFailureReport } from '@volter/sdk/kit/mount-failure-report';
+import type { RootReadiness } from '@volter/sdk/kit/readiness';
+
+export type SurfaceContentState = 'unknown' | 'present' | 'empty';
+export type SurfacePhase = 'loading' | 'ready';
+
+export interface SurfaceExplanation {
+  readonly tone: 'loading' | 'error' | 'neutral';
+  readonly title: string;
+  readonly description: string;
+}
+
+export interface ExplainSurfaceInput {
+  /** Human name of the surface, e.g. Scene, Game, or Story. */
+  readonly surface: string;
+  /** True when the surface's design mount is DELIBERATELY suspended because
+   *  the game is playing — the wait is not progress and must not read as one
+   *  (a human sat on "waiting for world to finish mounting" on an auto-played
+   *  example and reported the Scene tab broken — runhuman pass 37). */
+  readonly playSuspended?: boolean;
+  /** Exact root identities owned by this surface. Empty means not identified yet. */
+  readonly rootIds: readonly string[];
+  readonly phase: SurfacePhase;
+  readonly content: SurfaceContentState;
+  readonly readiness?: readonly RootReadiness[];
+  readonly failures?: readonly MountFailureReport[];
+  /** Why this surface has no editor for its root, when the editor has said so
+   *  (a Boundary's disclosure): the answer, not a wait. */
+  readonly disclosure?: string | null;
+}
+
+function quoted(ids: readonly string[]): string {
+  return ids.map((id) => `“${id}”`).join(', ');
+}
+
+function failureExplanation(
+  surface: string,
+  failures: readonly MountFailureReport[],
+): SurfaceExplanation {
+  const failedIds = failures.map((failure) => failure.worldId);
+  return {
+    tone: 'error',
+    title:
+      failedIds.length === 1
+        ? `${surface} root ${quoted(failedIds)} failed`
+        : `${failedIds.length} ${surface} roots failed`,
+    description: `${failures
+      .map(
+        (failure) =>
+          `${failure.worldId} (${failure.kind}, ${failure.identity}): ${failure.message}`,
+      )
+      .join(
+        '\n',
+      )}\nIf this followed an edit, Undo (Ctrl+Z) restores the previous source and remounts.`,
+  };
+}
+
+function loadingExplanation(surface: string, rootIds: readonly string[]): SurfaceExplanation {
+  const title =
+    rootIds.length === 0
+      ? `Loading ${surface}`
+      : rootIds.length === 1
+        ? `Loading ${surface} root ${quoted(rootIds)}`
+        : `Loading ${rootIds.length} ${surface} roots`;
+  return {
+    tone: 'loading',
+    title,
+    description:
+      rootIds.length === 0
+        ? 'Reading the project declaration to identify the root that belongs here.'
+        : `Waiting for ${quoted(rootIds)} to finish mounting.`,
+  };
+}
+
+function emptyExplanation(surface: string, rootIds: readonly string[]): SurfaceExplanation {
+  if (rootIds.length === 0) {
+    return {
+      tone: 'neutral',
+      title: `No ${surface} root`,
+      description: 'No declared root belongs to this surface.',
+    };
+  }
+  return {
+    tone: 'neutral',
+    title: 'No renderable content',
+    // The second sentence is load-bearing: a world whose content exists only
+    // under its game systems (the shipped shooters and strategy examples all
+    // do this) presents exactly this card the moment Play stops, and a human
+    // tester read it as breakage ("why did it stop? no renderable content" —
+    // runhuman pass 13, 2026-08-28). Name the way forward on the card itself.
+    description:
+      (rootIds.length === 1
+        ? `Root ${quoted(rootIds)} mounted successfully but currently produces no renderable content.`
+        : `Roots ${quoted(rootIds)} mounted successfully but currently produce no renderable content.`) +
+      ' If this world builds its content under its game systems, press Play (▶) to run it.',
+  };
+}
+
+/**
+ * The one precedence rule for a surface which otherwise has nothing to draw.
+ * A real rendered result always wins. When there is no result, a named failure
+ * wins over a named wait, which wins over the honest successful-empty state.
+ */
+export function explainSurface(input: ExplainSurfaceInput): SurfaceExplanation | null {
+  if (input.content === 'present') return null;
+
+  if (input.playSuspended) {
+    return {
+      tone: 'neutral',
+      title: 'Editing paused during Play',
+      description: `${quoted(input.rootIds)} is running in the Game tab. Press Stop (⏹) to edit it here.`,
+    };
+  }
+
+  const owned = new Set(input.rootIds);
+  const scopedFailures = (input.failures ?? []).filter((failure) => owned.has(failure.worldId));
+  if (scopedFailures.length > 0) return failureExplanation(input.surface, scopedFailures);
+
+  if (input.disclosure) {
+    return {
+      tone: 'neutral',
+      title: `No ${input.surface} editor for ${quoted(input.rootIds)}`,
+      description: input.disclosure,
+    };
+  }
+
+  const waitingIds = (input.readiness ?? [])
+    .filter((entry) => entry.state === 'waiting' && owned.has(entry.rootId))
+    .map((entry) => entry.rootId);
+  const loadingIds = waitingIds.length > 0 ? waitingIds : input.rootIds;
+  if (input.phase === 'loading' || waitingIds.length > 0 || input.content === 'unknown') {
+    return loadingExplanation(input.surface, loadingIds);
+  }
+  return emptyExplanation(input.surface, input.rootIds);
+}

package/src/kit/system-seam-evidence.ts

@@ -0,0 +1,72 @@
+/** Structural/operational evidence for one mounted SystemAdapters slot. */
+
+import {
+  displayKeyedPhysics,
+  gradeSeamCarrier,
+  inspectSeamShape,
+  PHYSICS_2D_ADAPTER_SHAPE,
+  PHYSICS_ADAPTER_SHAPE,
+  type SeamEvidenceReceipt,
+  type SeamEvidenceVerdict,
+  type SeamShape,
+  SYSTEM_ADAPTERS_SHAPE,
+  SYSTEM_PROVIDER_SHAPES,
+  type SystemAdapters,
+} from '@volter/project/adapter';
+import { liveSeamEvidence } from '@volter/sdk/kit/live-seam-evidence';
+
+const EPOCHS = new WeakMap<object, string>();
+let nextEpoch = 1;
+
+export function systemAdapterEpoch(value: object): string {
+  const found = EPOCHS.get(value);
+  if (found) return found;
+  const epoch = `system-${nextEpoch++}`;
+  EPOCHS.set(value, epoch);
+  return epoch;
+}
+
+export function inspectSystemAdapterSeam<K extends keyof SystemAdapters>(options: {
+  readonly slot: K;
+  readonly adapter: NonNullable<SystemAdapters[K]>;
+  readonly subject: string;
+  readonly epoch?: string | undefined;
+  readonly receipts?: readonly SeamEvidenceReceipt[] | undefined;
+}): SeamEvidenceVerdict {
+  const epoch = options.epoch ?? systemAdapterEpoch(options.adapter as object);
+  const seam = `system.${options.slot}`;
+  const bag = { [options.slot]: options.adapter } as Partial<SystemAdapters>;
+  const nestedShape =
+    options.slot === 'physics'
+      ? displayKeyedPhysics(options.adapter as SystemAdapters['physics'])
+        ? PHYSICS_2D_ADAPTER_SHAPE
+        : PHYSICS_ADAPTER_SHAPE
+      : SYSTEM_PROVIDER_SHAPES[options.slot as Exclude<keyof SystemAdapters, 'physics'>];
+  const receipts: SeamEvidenceReceipt[] = [
+    ...inspectSeamShape<SystemAdapters>({
+      prefix: 'system',
+      value: bag,
+      shape: SYSTEM_ADAPTERS_SHAPE,
+      subject: options.subject,
+      epoch,
+    }).filter((receipt) => receipt.seam === seam),
+    ...inspectSeamShape({
+      prefix: seam,
+      value: options.adapter,
+      shape: nestedShape as SeamShape<object>,
+      subject: options.subject,
+      epoch,
+    }),
+    ...liveSeamEvidence.receipts({ subject: options.subject, epoch }),
+    ...(options.receipts ?? []),
+  ];
+
+  return gradeSeamCarrier({
+    seam,
+    subject: options.subject,
+    epoch,
+    required: SYSTEM_ADAPTERS_SHAPE[options.slot].required,
+    receipts,
+    shape: nestedShape as SeamShape<object>,
+  });
+}

package/src/kit/tab-census.ts

@@ -0,0 +1,202 @@
+/**
+ * THE TAB RESOURCE CENSUS, page side — what this tab is holding, sampled
+ * cheaply and handed to the heartbeat worker to ride out on the next beat.
+ *
+ * WHY (measured 2026-08-10): a game tab's Chrome renderer process was killed
+ * repeatedly — WS close code 1006, no goodbye — deterministically on one user
+ * flow, with a 3840x2080 WebGL world and an HDR bloom chain resident and
+ * painting. JS heap stayed flat at ~190 MB the whole time, so the kill was
+ * GPU/compositor-side, at a per-process ceiling Chrome neither documents nor
+ * announces. The tab-presence system recovered perfectly and recorded NOTHING
+ * about why. This is the "why".
+ *
+ * The failure class is agent-native: an agent authors lush effects with zero
+ * cost feedback, because the quality loop grades looks and never cost.
+ *
+ * IT ALSO CARRIES THE LANES' WORKER CALLS. Each lane's worker call times and
+ * this thread's long-task stalls (`worker-call-metrics.ts`) ride the same
+ * sample, because the beat is the one channel that still moves while the page
+ * or a worker is blocked — which is exactly when those numbers are the whole
+ * story. Absent, not zeroed, in a tab where no lane published a meter.
+ *
+ * MEASUREMENT ONLY — nothing here enforces a budget. Budgets are a later
+ * decision, made from real profiles rather than from a guess about them.
+ *
+ * WHAT IT COSTS. One sample every five seconds on the main thread, skipped
+ * entirely while the tab is hidden: a `querySelectorAll('canvas')`, two
+ * property reads, a scan of the bounded Resource Timing buffer, and — only
+ * when a game is actually mounted — the render-debug adapter's existing
+ * memory snapshot, which the Profiler's Memory view already polls five times
+ * as often. Never per frame.
+ *
+ * WHAT IT DOES NOT DO. It adds no global, no new endpoint, and no second way
+ * to reach a renderer: the renderer counts come from `RenderDebugAdapter`
+ * (`authoring/active-systems.ts`), the one seam a mounted game already
+ * registers, and they are ABSENT — not zero — when nothing has registered one.
+ * A zero would read as "no textures", which is a different claim from "nobody
+ * measured".
+ */
+
+import { PROJECT_MOUNT_QUERY } from '@volter/sdk/session/project-module-url';
+import type { TabCensus, TabStallMetrics, WorkerCallTabMetrics } from '@volter/sdk/tab-census';
+import { getActiveRenderDebug } from './authoring/active-systems';
+import { tabStallMetrics, workerCallTabMetrics } from './worker-call-metrics';
+import { isJsHeapReading, type JsHeapReading, readJsHeap } from '@volter/sdk/kit/js-heap';
+
+/** How often the page samples itself. Slow on purpose — see the header. */
+export const TAB_CENSUS_INTERVAL_MS = 5_000;
+
+/** Bytes a canvas backing store holds per pixel (RGBA8). */
+const CANVAS_BYTES_PER_PIXEL = 4;
+
+const BYTES_PER_MB = 1024 * 1024;
+
+/**
+ * One resource profile — THIS module is its producer, and `@volter/sdk/tab-census`
+ * is where the shape is declared for every unit that speaks it (the node server
+ * that files it, the SDK status response, the journal line that prints it).
+ * Re-exported here because this file's own callers look for it here.
+ */
+export type { TabCensus };
+
+/** The three readings a sample is made of, injected so the sampler is pure. */
+export interface TabCensusSources {
+  /** Feature-detected JS heap (`readJsHeap`), or its unavailable-reason. */
+  heap(): JsHeapReading | { readonly unavailable: string };
+  /** Distinct `?volter-mount=<id>` generations in Resource Timing. */
+  mountEpochs(): number;
+  /** Every canvas in the document, in BACKING-BUFFER pixels (not CSS px). */
+  canvases(): readonly { readonly width: number; readonly height: number }[];
+  /** Renderer resource counts, or null when no render-debug adapter is up. */
+  rendererCounts(): {
+    readonly geometries: number;
+    readonly textures: number;
+    readonly programs: number | null;
+  } | null;
+  /** Each lane's worker call times, or null when no lane has published a meter
+   *  (`worker-call-metrics.ts`). Optional so a caller measuring only the
+   *  resource half omits it and gets no block, rather than fabricating one. */
+  workerCalls?(): Readonly<Record<string, WorkerCallTabMetrics>> | null;
+  /** The main thread's stalls, or null while nobody is watching them. */
+  stalls?(): TabStallMetrics | null;
+}
+
+/** Two decimals of an MB — enough to see a 4K framebuffer, short enough to read. */
+function mb(bytes: number): number {
+  return Math.round((bytes / BYTES_PER_MB) * 100) / 100;
+}
+
+/**
+ * Take one census. PURE: everything it reads comes from `sources`, so the test
+ * drives the absent-heap, absent-adapter and populated branches without a
+ * browser.
+ */
+export function sampleTabCensus(sources: TabCensusSources): TabCensus {
+  const heap = sources.heap();
+  const canvases = sources.canvases();
+  const counts = sources.rendererCounts();
+  const workerCalls = sources.workerCalls?.() ?? null;
+  const stalls = sources.stalls?.() ?? null;
+  let canvasBytes = 0;
+  for (const canvas of canvases) {
+    canvasBytes += canvas.width * canvas.height * CANVAS_BYTES_PER_PIXEL;
+  }
+  return {
+    heapUsedMB: isJsHeapReading(heap) ? mb(heap.usedBytes) : null,
+    heapLimitMB: isJsHeapReading(heap) && heap.limitBytes !== null ? mb(heap.limitBytes) : null,
+    mountEpochs: sources.mountEpochs(),
+    canvases: canvases.length,
+    canvasMB: mb(canvasBytes),
+    ...(workerCalls === null ? {} : { workerCalls }),
+    ...(stalls === null ? {} : { stalls }),
+    ...(counts === null
+      ? {}
+      : {
+          textures: counts.textures,
+          geometries: counts.geometries,
+          // `renderer.info.programs` is populated only after a first render,
+          // and a count nobody could read stays absent rather than becoming 0.
+          ...(counts.programs === null ? {} : { programs: counts.programs }),
+        }),
+  };
+}
+
+/**
+ * Count the project module generations this document has fetched.
+ *
+ * Resource Timing is the browser-visible population we can measure without
+ * instrumenting project modules or pretending the ES-module registry exposes
+ * an enumeration API. The entries live for the document lifetime (the same
+ * lifetime as its module registry), and the project mount split watch raises
+ * the resource buffer before imports begin. A reload resets both populations.
+ */
+export function countProjectMountEpochs(resources: readonly { readonly name: string }[]): number {
+  const epochs = new Set<string>();
+  for (const resource of resources) {
+    try {
+      const epoch = new URL(resource.name, 'http://volter.invalid').searchParams.get(
+        PROJECT_MOUNT_QUERY,
+      );
+      if (epoch !== null && epoch.length > 0) epochs.add(epoch);
+    } catch {
+      // Resource Timing normally supplies absolute URLs. A malformed entry is
+      // not evidence of a mount and must not sink the rest of the census.
+    }
+  }
+  return epochs.size;
+}
+
+/** The real readings: this document, this browser, whatever game is mounted. */
+export function documentCensusSources(): TabCensusSources {
+  return {
+    heap: () => readJsHeap(),
+    mountEpochs: () => countProjectMountEpochs(performance.getEntriesByType('resource')),
+    canvases: () => [...document.querySelectorAll('canvas')],
+    rendererCounts: () => getActiveRenderDebug()?.memorySnapshot?.().counts ?? null,
+    workerCalls: () => workerCallTabMetrics(),
+    stalls: () => tabStallMetrics(),
+  };
+}
+
+let latest: TabCensus | null = null;
+
+/** The newest census this page took, for the stats overlay to print. Null
+ *  until the first sample (and while the tab has only ever been hidden). */
+export function latestTabCensus(): TabCensus | null {
+  return latest;
+}
+
+export interface TabCensusLoopOptions {
+  /** Hand the profile to the heartbeat worker (`editor-presence.ts`). */
+  report(census: TabCensus): void;
+  sources?: TabCensusSources;
+  intervalMs?: number;
+  /** True while the tab is backgrounded — a hidden tab is not sampled. */
+  hidden?(): boolean;
+}
+
+/**
+ * Start sampling. Returns the stop function.
+ *
+ * A HIDDEN tab is skipped rather than throttled: it is painting nothing, so a
+ * sample would only re-report the moment it was backgrounded. Skipping is
+ * SAFE — and only safe — because the worker carries each profile on one beat
+ * and then drops it, so a tab that stops sampling stops sending and its
+ * profile's reported age climbs honestly. (When the worker echoed its cache
+ * instead, this skip is precisely what turned into the lie: a background tab
+ * killed under memory pressure — a mainline path for this feature — reported
+ * a half-second-old profile that was half an hour old.)
+ */
+export function startTabCensus(options: TabCensusLoopOptions): () => void {
+  const sources = options.sources ?? documentCensusSources();
+  const hidden = options.hidden ?? (() => document.visibilityState === 'hidden');
+  const tick = (): void => {
+    if (hidden()) return;
+    const census = sampleTabCensus(sources);
+    latest = census;
+    options.report(census);
+  };
+  tick();
+  const timer = setInterval(tick, options.intervalMs ?? TAB_CENSUS_INTERVAL_MS);
+  return () => clearInterval(timer);
+}