@volter/editor-game 0.5.65

package/src/network/network-inspector-model.ts

@@ -0,0 +1,225 @@
+/**
+ * Pure data-path logic for the Network inspector (W3b) — no React/DOM, so the
+ * whole consumer side of the `NetworkingAdapter` inspector capabilities is
+ * headless-testable (`network-inspector.test.ts` drives it against a REAL
+ * loopback Colyseus server through the real arena adapter).
+ *
+ * The rendering component (`NetworkInspectorPanel.tsx`) owns only JSX; every
+ * behavior — capability detection, the seq-fenced message-log ring with
+ * pause/filter, the sparkline sample history, and the polyline geometry —
+ * lives here.
+ *
+ * Editor code never imports Colyseus (net-import-ban) — only the
+ * `NetworkingAdapter` interface.
+ */
+
+import type {
+  ConnectionState,
+  NetMessageEvent,
+  NetRates,
+  NetworkingAdapter,
+  ReplicationStats,
+  RoomInfo,
+} from '@volter/editor-project/adapter';
+
+/**
+ * The three headline readings the inspector's header shows.
+ *
+ * Every field is TRI-STATE, and the third state is the point: `undefined`
+ * means the adapter has no READER for it, which is not the same claim as the
+ * reader's own negative answer (`disconnected`, no room, zero counts). A row
+ * whose capability is absent is not rendered at all — never rendered as the
+ * negative, which would be a measurement the adapter never made.
+ */
+export interface NetworkView {
+  connectionState: ConnectionState | undefined;
+  roomInfo: RoomInfo | null | undefined;
+  stats: ReplicationStats | undefined;
+}
+
+/** Adapter -> header view model. Pure: no React, no DOM.
+ *
+ *  Overloaded so a caller that has already established it HAS an adapter (the
+ *  inspector panel returns the register-an-adapter notice before this point)
+ *  is not handed a `| null` it would have to re-narrow with a branch that can
+ *  never run. */
+export function deriveNetworkView(adapter: NetworkingAdapter): NetworkView;
+export function deriveNetworkView(
+  adapter: NetworkingAdapter | null | undefined,
+): NetworkView | null;
+export function deriveNetworkView(
+  adapter: NetworkingAdapter | null | undefined,
+): NetworkView | null {
+  if (!adapter) return null;
+  return {
+    connectionState: adapter.getConnectionState?.(),
+    roomInfo: adapter.getRoomInfo?.(),
+    stats: adapter.getReplicationStats?.(),
+  };
+}
+
+/** Which optional inspector capabilities the active adapter actually
+ *  provides — the degradation ladder's per-section verdict. `null` input
+ *  (no adapter registered) stays `null`: the panel renders the
+ *  register-an-adapter notice instead of a fabricated all-false map. */
+export interface NetworkCapabilityMap {
+  stateTree: boolean;
+  messageLog: boolean;
+  rates: boolean;
+  conditioning: boolean;
+  /** The adapter can read connection lifecycle state (`getConnectionState`).
+   *  Absent ⇒ the link row is unsupported, NOT "disconnected". */
+  connection: boolean;
+  /** The adapter can name the active room (`getRoomInfo`). Absent ⇒ the room
+   *  row is unsupported, NOT "connected to no room". */
+  room: boolean;
+  /** The adapter counts replication activity (`getReplicationStats`). Absent ⇒
+   *  the stats row is unsupported, NOT a measured-quiet link. */
+  stats: boolean;
+  /** The adapter reports a local player identity (`getPlayerIdentity`) — the
+   *  inspector shows the current name. */
+  identity: boolean;
+  /** The adapter can SET the local identity (`setPlayerIdentity`) — the
+   *  inspector shows an EDITABLE name field. Implies `identity`. */
+  identitySettable: boolean;
+}
+
+export function deriveNetworkCapabilities(
+  adapter: NetworkingAdapter | null | undefined,
+): NetworkCapabilityMap | null {
+  if (!adapter) return null;
+  return {
+    stateTree: typeof adapter.getStateSnapshot === 'function',
+    messageLog: typeof adapter.messageEvents === 'function',
+    rates: typeof adapter.getRates === 'function',
+    // A conditioner needs BOTH the read and the write to render controls
+    // honestly (write-only would show state it can't verify; read-only
+    // couldn't apply anything).
+    conditioning:
+      typeof adapter.getConditioning === 'function' &&
+      typeof adapter.setConditioning === 'function',
+    connection: typeof adapter.getConnectionState === 'function',
+    room: typeof adapter.getRoomInfo === 'function',
+    stats: typeof adapter.getReplicationStats === 'function',
+    identity: typeof adapter.getPlayerIdentity === 'function',
+    identitySettable: typeof adapter.setPlayerIdentity === 'function',
+  };
+}
+
+/**
+ * Consumer-side message log over `NetworkingAdapter.messageEvents`.
+ *
+ * Pulls seq-fenced events from the adapter's ring into its own bounded ring.
+ * PAUSE stops consuming — the fence stays where it was, so resuming picks up
+ * whatever the adapter's ring still holds (a long pause loses only what the
+ * adapter itself evicted; nothing is fabricated to fill the gap).
+ */
+export class MessageLogModel {
+  private entries: NetMessageEvent[] = [];
+  private lastSeq = 0;
+  paused = false;
+
+  constructor(private readonly capacity = 500) {}
+
+  /** Consume new events (`seq > fence`) from the adapter. Returns how many
+   *  were appended (0 while paused or when the capability is absent). */
+  pull(adapter: NetworkingAdapter | null | undefined): number {
+    if (this.paused || !adapter?.messageEvents) return 0;
+    const fresh = adapter.messageEvents(this.lastSeq);
+    if (fresh.length === 0) return 0;
+    for (const event of fresh) {
+      this.entries.push(event);
+      if (event.seq > this.lastSeq) this.lastSeq = event.seq;
+    }
+    if (this.entries.length > this.capacity) {
+      this.entries.splice(0, this.entries.length - this.capacity);
+    }
+    return fresh.length;
+  }
+
+  get all(): readonly NetMessageEvent[] {
+    return this.entries;
+  }
+
+  clear(): void {
+    // Deliberately NOT resetting the fence: clear empties the view; already-
+    // observed events don't come back.
+    this.entries = [];
+  }
+}
+
+/** Case-insensitive substring filter on `type` (the log's filter box). An
+ *  empty/whitespace filter passes everything. */
+export function filterMessages(
+  events: readonly NetMessageEvent[],
+  filter: string,
+): NetMessageEvent[] {
+  const needle = filter.trim().toLowerCase();
+  if (!needle) return [...events];
+  return events.filter((e) => e.type.toLowerCase().includes(needle));
+}
+
+/** Fixed-capacity rolling series feeding one sparkline. */
+export class RateSeries {
+  private values: number[] = [];
+
+  constructor(readonly capacity = 60) {}
+
+  push(value: number): void {
+    this.values.push(value);
+    if (this.values.length > this.capacity) this.values.shift();
+  }
+
+  get data(): readonly number[] {
+    return this.values;
+  }
+
+  get latest(): number | null {
+    return this.values.length > 0 ? (this.values[this.values.length - 1] as number) : null;
+  }
+}
+
+/**
+ * Rolling history of `getRates()` samples driving the sparklines. A byte
+ * field the adapter OMITS pushes nothing — its series stays empty and the
+ * panel marks that direction "n/a" instead of drawing a fabricated zero line
+ * (the arena adapter omits `bytesInPerSec`: Colyseus patch bytes aren't
+ * observable through the Callbacks API).
+ */
+export class RateHistory {
+  readonly msgsIn = new RateSeries();
+  readonly msgsOut = new RateSeries();
+  readonly bytesIn = new RateSeries();
+  readonly bytesOut = new RateSeries();
+
+  sample(rates: NetRates): void {
+    this.msgsIn.push(rates.msgsInPerSec);
+    this.msgsOut.push(rates.msgsOutPerSec);
+    if (rates.bytesInPerSec !== undefined) this.bytesIn.push(rates.bytesInPerSec);
+    if (rates.bytesOutPerSec !== undefined) this.bytesOut.push(rates.bytesOutPerSec);
+  }
+}
+
+/**
+ * SVG polyline `points` for a sparkline: newest sample at the right edge,
+ * y auto-scaled to the series max (min 1 so an all-zero series draws a flat
+ * baseline, not NaN). Fewer than 2 samples → `''` (nothing to draw yet).
+ */
+export function sparklinePoints(
+  values: readonly number[],
+  width: number,
+  height: number,
+  pad = 1,
+): string {
+  if (values.length < 2) return '';
+  const max = Math.max(1, ...values);
+  const innerH = height - pad * 2;
+  const stepX = width / (values.length - 1);
+  return values
+    .map((v, i) => {
+      const x = i * stepX;
+      const y = pad + innerH * (1 - v / max);
+      return `${x.toFixed(1)},${y.toFixed(1)}`;
+    })
+    .join(' ');
+}

package/src/play/play-boot-stall.ts

@@ -0,0 +1,118 @@
+/**
+ * The play boot's stall guard: a BACKGROUNDED editor tab must never turn a
+ * network-shaped play-start step into a silent timeout.
+ *
+ * ## The measurement this exists for
+ *
+ * Play start is frame-independent — it boots fine on a tab whose
+ * `requestAnimationFrame` never fires at all (measured: a hidden real-Chrome
+ * tab starts play in ~1s, and so does a tab with rAF stubbed dead). What is
+ * NOT independent is the network. A backgrounded tab's requests are
+ * deprioritized by the browser, so the fetch-shaped steps of
+ * `enterPlayMode` — the log-session POST, the manifest fetch, the dynamic
+ * imports that resolve each root's entry — queue behind whatever else that
+ * origin is loading. Measured in a hidden tab on a cold Vite graph:
+ *
+ *     post-logSession        @13125   (9.5s)
+ *     post-fetchManifest    @158274   (145s)
+ *     pre-resolveAllRootEntries       (still pending at 165s)
+ *
+ * The relay's own `play` budget is 120s (`server-utils.ts`'s
+ * `relayCommandTimeoutMs`), so the caller gets
+ * "Command timed out — editor connected but did not respond" — a message that
+ * names nothing, points at nothing, and hides the one remedy that works
+ * (foreground the tab; the very next `vgai play` then starts in seconds).
+ *
+ * ## What this does, and deliberately does not do
+ *
+ * A step that exceeds {@link PLAY_BOOT_STALL_MS} while `document.hidden` is
+ * reported as a NAMED failure that states the step, the elapsed budget, and
+ * the fix. A step that exceeds it while the tab is VISIBLE is not touched:
+ * a foregrounded tab is not being starved, so slow there means genuinely
+ * slow, and failing it would be a regression. The visibility is re-read when
+ * the timer fires, so a tab foregrounded mid-boot keeps its boot.
+ *
+ * Rejecting does not cancel the underlying request — it abandons it. Only
+ * steps whose abandoned result is inert (a fetch, a module import) are
+ * wrapped; the runtime MOUNT is not, because an abandoned mount would leak a
+ * live session.
+ *
+ * (`p-timeout` was considered and rejected: its contract is an unconditional
+ * deadline, and the whole point here is that the deadline applies only while
+ * the tab is hidden — plus the message is the deliverable.)
+ */
+
+/** How long one network-shaped play-boot step may sit while the tab is hidden.
+ *  Generous by design: every such step measures in TENS OF MILLISECONDS on a
+ *  healthy hidden tab, so this only fires on a genuinely starved one. */
+export const PLAY_BOOT_STALL_MS = 15_000;
+
+export interface PlayBootStallOptions {
+  /** Whether the editor tab is backgrounded right now. Re-read when the
+   *  timer fires, never captured up front. */
+  readonly isHidden: () => boolean;
+  /** The editor page's own URL, so the message can name the tab to open. */
+  readonly editorUrl?: string | undefined;
+  readonly stallMs?: number | undefined;
+  readonly setTimer?: ((fn: () => void, ms: number) => unknown) | undefined;
+  readonly clearTimer?: ((handle: unknown) => void) | undefined;
+}
+
+/** The one message. Names the step, the condition, and the remedy. */
+export function playBootStallMessage(step: string, stallMs: number, editorUrl?: string): string {
+  const open = editorUrl ? ` (open ${editorUrl})` : '';
+  return (
+    `Play start stalled at "${step}" for ${Math.round(stallMs / 1000)}s and the editor tab is ` +
+    'HIDDEN — a backgrounded tab has its network requests deprioritized by the browser, so this ' +
+    'step is queued rather than broken. Bring the editor tab to the foreground' +
+    `${open} and run play again; the engine loop itself is hidden-safe, only the boot's ` +
+    'fetches are starved.'
+  );
+}
+
+/**
+ * Run one network-shaped play-boot step under the hidden-tab stall guard.
+ *
+ * Resolves/rejects with `work`'s own outcome in every case except one: the
+ * step is still pending after the budget AND the tab is hidden, which
+ * rejects with {@link playBootStallMessage}.
+ */
+export function withPlayBootStallGuard<T>(
+  step: string,
+  work: Promise<T>,
+  options: PlayBootStallOptions,
+): Promise<T> {
+  const stallMs = options.stallMs ?? PLAY_BOOT_STALL_MS;
+  const setTimer =
+    options.setTimer ?? ((fn: () => void, ms: number) => setTimeout(fn, ms) as unknown);
+  const clearTimer =
+    options.clearTimer ??
+    ((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const handle = setTimer(() => {
+      if (settled) return;
+      // Re-read visibility HERE: a tab foregrounded during the wait is no
+      // longer starved, and must keep the boot it already has in flight.
+      if (!options.isHidden()) return;
+      settled = true;
+      reject(new Error(playBootStallMessage(step, stallMs, options.editorUrl)));
+    }, stallMs);
+
+    work.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        clearTimer(handle);
+        resolve(value);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        clearTimer(handle);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      },
+    );
+  });
+}

package/src/play/play-log-events.ts

@@ -0,0 +1,26 @@
+import type { LogEntry } from '@volter/editor-core/editor-api';
+import type { TickStampedEvent } from '@volter/editor-project/adapter/system-adapter';
+
+/** Convert newly observed game-authored debug events into persistent JSONL entries. */
+export function debugEventsToLogEntries(
+  events: readonly TickStampedEvent[],
+  sinceSeq: number,
+  wallTime = Date.now(),
+): { entries: LogEntry[]; lastSeq: number } {
+  const fresh = events.filter((event) => event.seq > sinceSeq).sort((a, b) => a.seq - b.seq);
+  return {
+    entries: fresh.map((event) => ({
+      t: wallTime,
+      level: 'info',
+      source: 'game-event',
+      msg: event.event,
+      tick: event.tick,
+      simT: event.simT,
+      meta: {
+        seq: event.seq,
+        ...(event.detail !== undefined ? { detail: event.detail } : {}),
+      },
+    })),
+    lastSeq: fresh.at(-1)?.seq ?? sinceSeq,
+  };
+}