@volter/editor-core 0.5.57

package/src/tab-census.ts

@@ -0,0 +1,198 @@
+/**
+ * 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 BLENDER BLOCK. The Blender worker's call times and this
+ * thread's long-task stalls (`blender-tab-metrics.ts`) ride the same sample,
+ * because the beat is the one channel that still moves while the page or the
+ * worker is blocked — which is exactly when those numbers are the whole story.
+ * Absent, not zeroed, in a tab with no Blender session.
+ *
+ * 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/editor-sdk/session/project-module-url';
+import type { BlenderTabMetrics, TabCensus } from '@volter/editor-sdk/tab-census';
+import { getActiveRenderDebug } from './authoring/active-systems';
+import { blenderTabMetrics } from './blender-tab-metrics';
+import { isJsHeapReading, type JsHeapReading, readJsHeap } from './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/editor-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 `?vgai-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;
+  /** The Blender worker's call times and the main thread's stalls, or null when
+   *  this tab has no Blender session (`blender-tab-metrics.ts`). Optional so a
+   *  caller measuring only the resource half omits it and gets no block, rather
+   *  than having to fabricate one. */
+  blender?(): BlenderTabMetrics | 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 blender = sources.blender?.() ?? 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),
+    ...(blender === null ? {} : { blender }),
+    ...(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://vgai.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,
+    blender: () => blenderTabMetrics(),
+  };
+}
+
+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);
+}

package/src/tab-lifecycle-client.ts

@@ -0,0 +1,196 @@
+/**
+ * Client half of the tab bijection (server: server/tab-lifecycle.ts) — the
+ * page-lifetime handlers for the tab-maintenance SSE events. The inline boot
+ * queues these events from the moment it creates the shared EventSource;
+ * editor-presence.ts installs these typed handlers and replays that queue.
+ *
+ * - `tab-refocus` — this is the session's one blessed tab: focus it, and
+ *   navigate only if the server says the URL should change.
+ * - `tab-yield` — another tab is blessed. Try `window.close()` (script/CLI
+ *   opened tabs with a single history entry close); otherwise leave the app
+ *   for the server's static "open in another tab — Use here instead" page.
+ *   Navigation tears the whole editor app down, so the editor never RUNS in
+ *   two tabs for one session.
+ * - `tab-close` — the session ended. Run every terminator, TELL THE SERVER
+ *   they ran, then try to close; a user-opened tab that refuses shows a
+ *   minimal inline "session ended" state instead (the server is exiting, so
+ *   there is no page left to navigate to).
+ * - `tab-adopt` — this tab is the session's one tab but it is showing the
+ *   launcher/startup-failure surface. Focus it and re-run project detection
+ *   so it lands on the project the server serves, instead of the server
+ *   opening a SECOND tab beside it. The app registers the handler
+ *   (`onTabAdopt`, AppRoot); with none registered — the yield page, or a
+ *   teardown window — a reload is the same convergence by a blunter route.
+ */
+
+import { editorAppIconSvg, editorDocumentTitle } from '@volter/editor-sdk/session/editor-brand';
+import { markSessionEnded } from './session-tombstone';
+
+/** How long `window.close()` gets to take effect before the fallback runs. */
+const CLOSE_FALLBACK_DELAY_MS = 300;
+
+function closeOrFallback(fallback: () => void): void {
+  window.close();
+  // If close() was refused (user-opened tab), the timer still runs.
+  window.setTimeout(fallback, CLOSE_FALLBACK_DELAY_MS);
+}
+
+function handleRefocus(event: MessageEvent): void {
+  try {
+    window.focus();
+    const data = JSON.parse(event.data as string) as { url?: unknown };
+    if (typeof data.url !== 'string') return;
+    const target = new URL(data.url, window.location.href);
+    if (
+      target.origin === window.location.origin &&
+      target.pathname + target.search !== window.location.pathname + window.location.search
+    ) {
+      window.location.assign(target.href);
+    }
+  } catch {
+    /* a malformed maintenance event must never break the editor */
+  }
+}
+
+function handleYield(base: string, event: MessageEvent): void {
+  let participantId: string | null = null;
+  try {
+    const data = JSON.parse(event.data as string) as { participantId?: unknown };
+    if (typeof data.participantId === 'string') participantId = data.participantId;
+  } catch {
+    // The unscoped legacy route remains a safe fallback.
+  }
+  closeOrFallback(() => {
+    const query = participantId ? `?participantId=${encodeURIComponent(participantId)}` : '';
+    window.location.replace(`${base}/tab-yielded${query}`);
+  });
+}
+
+// Session end now reaches EVERY connected tab, not just the blessed one (an
+// extra tab that only learned of the shutdown by its socket dying fell
+// through to the generic "Editor disconnected" overlay). A tab can therefore
+// see more than one `tab-close`; acting twice would re-run `window.close()`
+// and repaint the notice under itself.
+let sessionEndHandled = false;
+
+/**
+ * THE PAGE'S ACKNOWLEDGEMENT — "I got `tab-close`, and everything it turns off
+ * is already off."
+ *
+ * The same beacon route and the same transport as index.html's `pagehide`
+ * goodbye (`server/tab-presence.ts`'s `TabCloseBeacon`), with `reason` telling
+ * the two apart; `sendBeacon` and not `fetch` because `window.close()` runs a
+ * line later and this must survive the document going away.
+ *
+ * Sent AFTER `markSessionEnded` returns, never before: its listeners run
+ * synchronously, so by the time it comes back every terminator — the Blender
+ * engine worker's included — has run, and that is precisely what this sentence
+ * claims. Sending it first would make it a lie the server then waits on.
+ */
+function acknowledgeSessionEnd(base: string, identity: TabIdentity): void {
+  if (identity.tabId === undefined || identity.epoch === undefined) return;
+  try {
+    navigator.sendBeacon?.(
+      `${base}/tab/close`,
+      new Blob(
+        [
+          JSON.stringify({
+            tabId: identity.tabId,
+            epoch: identity.epoch,
+            persisted: false,
+            reason: 'session-ended',
+          }),
+        ],
+        { type: 'application/json' },
+      ),
+    );
+  } catch {
+    /* an ack that cannot be sent degrades to the unacked line the server
+       journals — which is the truth about this page either way */
+  }
+}
+
+function handleSessionEnded(base: string, identity: TabIdentity): void {
+  if (sessionEndHandled) return;
+  sessionEndHandled = true;
+  // The latch FIRST, and unconditionally: `window.close()` is refused for a
+  // user-opened tab, so the page below may well keep running. Everything that
+  // would let it go on impersonating a live editor reads this
+  // (`session-tombstone.ts`).
+  markSessionEnded('session-closed');
+  acknowledgeSessionEnd(base, identity);
+  closeOrFallback(() => {
+    document.title = editorDocumentTitle('Session ended');
+    document.body.innerHTML = `<style>
+      :root{color-scheme:dark;background:#101318;color:#e8edf3;font-family:Inter,ui-sans-serif,system-ui,sans-serif}
+      body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px;background:radial-gradient(circle at 50% 30%,#1c2a3a 0,#101318 52%,#0b0e13 100%)}
+      main{width:min(440px,100%);box-sizing:border-box;padding:34px;text-align:center;border:1px solid rgba(255,255,255,.1);border-radius:20px;background:rgba(23,28,35,.92);box-shadow:0 22px 60px rgba(0,0,0,.38)}
+      .brand-mark{width:68px;height:68px;margin:0 auto 20px}.brand-mark svg{display:block;width:100%;height:100%}h1{margin:0 0 10px;font-size:22px}p{margin:0;color:#aeb9c6;font-size:14px;line-height:1.6}
+    </style><main><div class="brand-mark">${editorAppIconSvg()}</div><h1>Session ended</h1><p>This editor session has ended. You can close this tab.</p></main>`;
+  });
+}
+
+/**
+ * Which surface this tab is showing, as the server's tab bijection accounts
+ * for it (`POST /__editor/tab/route`; server vocabulary:
+ * server/tab-lifecycle.ts `TabRoute`). `'no-project'` covers BOTH the
+ * launcher and the startup-failure surface — from the bijection's side they
+ * are the same fact: a live tab that is not on the served project and can be
+ * adopted into it.
+ */
+export type EditorTabRoute = 'project' | 'no-project';
+
+const adoptHandlers = new Set<() => void>();
+
+/**
+ * Register the app's response to `tab-adopt` (AppRoot: re-run detection).
+ * Returns an unsubscribe. Kept as a registry rather than an import from the
+ * component so this module stays free of React and of the editor's graph.
+ */
+export function onTabAdopt(handler: () => void): () => void {
+  adoptHandlers.add(handler);
+  return () => {
+    adoptHandlers.delete(handler);
+  };
+}
+
+function handleAdopt(): void {
+  try {
+    window.focus();
+  } catch {
+    /* focus is a nicety; adoption is the point */
+  }
+  if (adoptHandlers.size === 0) {
+    window.location.reload();
+    return;
+  }
+  for (const handler of [...adoptHandlers]) handler();
+}
+
+/**
+ * This tab's identity as the inline bootstrap minted it — passed in rather
+ * than read here, because `editor-presence.ts` owns the one read of
+ * `__VGAI_EDITOR_PRESENCE_BOOTSTRAP__` and a second reader would be a second
+ * opinion about who this tab is. Both fields are absent wherever there is no
+ * inline bootstrap at all (browser-mode builds, jsdom): such a page is not in
+ * the server's tab table and has nothing to acknowledge with.
+ */
+export interface TabIdentity {
+  readonly tabId?: string | undefined;
+  readonly epoch?: string | undefined;
+}
+
+/**
+ * Install the tab-maintenance listeners on the (one) real EventSource.
+ * `base` is the editor API prefix (`/__editor`).
+ */
+export function installTabLifecycleListeners(
+  source: Pick<EventSource, 'addEventListener'>,
+  base: string,
+  identity: TabIdentity = {},
+): void {
+  source.addEventListener('tab-refocus', (event) => handleRefocus(event as MessageEvent));
+  source.addEventListener('tab-yield', (event) => handleYield(base, event as MessageEvent));
+  source.addEventListener('tab-close', () => handleSessionEnded(base, identity));
+  source.addEventListener('tab-adopt', () => handleAdopt());
+}