@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/api/relay.ts

@@ -0,0 +1,270 @@
+/**
+ * What a TAB reports upstream: its state snapshot, that it picked a command
+ * up, that a command finished, which play-boot phase it is in — plus the
+ * gameplay recording sink.
+ *
+ * The editor-state reporter serializes and coalesces on purpose. One user
+ * action can change several things at once (a Play click changes both play
+ * state and the active viewport), so only the newest waiting snapshot is kept
+ * and sends are serialized — an older, slower report can never land after a
+ * newer one and roll `/__editor/state` back.
+ */
+
+import {
+  EDITOR_CLIENT_ID,
+  reportTabPhase,
+  sendCommandResultControl,
+  sendControl,
+} from '../editor-presence';
+import { assertEditorServerAnswered } from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+
+// State reports can be triggered by several browser-owned transitions at once
+// (a Play click changes both play state and the active viewport, for example).
+// Keep only the newest waiting snapshot and serialize sends so an older,
+// slower report can never land after a newer one and roll `/__editor/state`
+// back.
+let pendingEditorState: Record<string, unknown> | null = null;
+let editorStateReportDrain: Promise<void> | null = null;
+
+async function drainEditorStateReports(): Promise<void> {
+  while (pendingEditorState) {
+    const state = pendingEditorState;
+    pendingEditorState = null;
+    await sendControl('state', { ...state, _clientId: EDITOR_CLIENT_ID });
+  }
+  editorStateReportDrain = null;
+  // A caller cannot interleave with the synchronous block above, but keep
+  // this defensive restart so future refactors cannot strand a late report.
+  if (pendingEditorState) editorStateReportDrain = drainEditorStateReports();
+}
+
+/** Report the current editor state to the server (called by command-listener). */
+export function reportEditorState(state: Record<string, unknown>): Promise<void> {
+  pendingEditorState = state;
+  editorStateReportDrain ??= drainEditorStateReports();
+  return editorStateReportDrain;
+}
+
+/**
+ * Tell the server this tab PICKED UP a relayed command — sent before the work
+ * starts, so it says "my command listener is running", nothing about the
+ * outcome.
+ *
+ * Long-budget commands (`play` waits out a whole async `setup()`) used to give
+ * a tab that had stopped answering the control channel the same silence as a tab
+ * that was merely busy, and the caller waited the entire budget for a result
+ * that was never coming. This receipt is what separates the two — see
+ * `server/server-utils.ts`'s `RELAY_DELIVERY_ACK_MS`. Best-effort and
+ * deliberately not awaited by the caller: a lost receipt costs a fast, named
+ * refusal, never a wrong result.
+ */
+export async function reportCommandReceived(requestId: string): Promise<void> {
+  await sendControl('command-received', { _requestId: requestId, _clientId: EDITOR_CLIENT_ID });
+}
+
+/**
+ * Tell the server whether this page is RUNNING a command listener at all.
+ *
+ * The receipt above answers that question one command at a time, and only
+ * after somebody sends a command. This answers it standing, at the two moments
+ * that change the answer — `connectCommandListener` attaching, and its
+ * teardown running — so the editor's `status` command can name a dead page on the FIRST read
+ * instead of it being inferable only from a command that hangs.
+ *
+ * It is worth its own message because presence cannot carry it: the control
+ * channel is opened by the tiny pre-React entry
+ * (`early-editor-presence.ts`), long before the React graph that owns the
+ * listener finishes loading — so a page that dies in between connects,
+ * beats, and executes nothing.
+ */
+export async function reportCommandListener(attached: boolean): Promise<void> {
+  await sendControl('command-listener', { _clientId: EDITOR_CLIENT_ID, attached });
+}
+
+/**
+ * Tell the server which play-boot step this page is ENTERING.
+ *
+ * Sent before the step's work, never after it, so a step that never returns is
+ * still named — see `play-boot-phase.ts` for the 199.5-second block that made
+ * three consecutive commands time out against a session every reader called
+ * healthy. Not awaited by the caller: the phase is diagnostics, and diagnostics
+ * that can delay a boot are worse than none.
+ */
+let phaseSequence = 0;
+export function reportPlayBootPhase(state: {
+  phase: string | null;
+  at: number;
+  run: number;
+}): void {
+  // Two roads, because the control socket is the PAGE's: a phase announced
+  // right before a synchronous block sat in the page's send queue until the
+  // block ended (measured 2026-09-06: a 45 s build's phase arrived after the
+  // build). The heartbeat worker's socket keeps beating through the block,
+  // so the phase rides the next beat too; whichever lands first wins.
+  const sequence = ++phaseSequence;
+  reportTabPhase(state.phase, EDITOR_CLIENT_ID, sequence);
+  void sendControl('play-phase', { _clientId: EDITOR_CLIENT_ID, ...state, source: EDITOR_CLIENT_ID, sequence });
+}
+
+/** Report a command result back to the server so the SDK/CLI gets the response.
+ *  `data` carries an optional payload for commands that answer with data
+ *  (e.g. `capture-viewport`'s base64 PNG, the debug-seam reads)
+ *  forwarded verbatim through `/__editor/command-result` →
+ *  `commandResponseFor` → the SDK transports, on the failure path too (where
+ *  it carries structured `{ code: ... }` markers). */
+export async function reportCommandResult(
+  requestId: string,
+  ok: boolean,
+  error?: string,
+  data?: Record<string, unknown>,
+  waitForCaller = false,
+): Promise<void> {
+  const payload = {
+    _requestId: requestId,
+    _clientId: EDITOR_CLIENT_ID,
+    ok,
+    error,
+    data,
+  };
+  if (waitForCaller) await sendCommandResultControl(requestId, payload);
+  else await sendControl('command-result', payload);
+}
+
+export interface GameplayRecordingSink {
+  id: string;
+  path: string;
+  format: 'composite-webm' | 'canvas-dom';
+  /** Directory containing `manifest.json`, `events.json`, and interned assets
+   * for a canvas + DOM recording. Absent for a composite WebM. */
+  replayPath: string | null;
+  /** True when this sink is the ROTATING unnamed file — the next recording
+   *  overwrites it. False for a caller-named keepsake. */
+  rotates: boolean;
+  /** The `logs/play-*.jsonl` this project's live play run is writing, or
+   *  `null` when nothing is logging. Its event timestamps are what map an
+   *  event to an offset in the clip, so it travels WITH the clip's identity
+   *  rather than being looked up separately later. */
+  logFile: string | null;
+}
+
+async function recordingResponse<T>(response: Response, action: string): Promise<T> {
+  // `.json().catch(() => ({}))` under a page fallback produced an OK-looking
+  // empty sink: `start` handed back a sink with no id, and every chunk after it
+  // posted into nothing while the recorder showed a recording in progress.
+  assertEditorServerAnswered(response, `gameplay recording ${action} failed`);
+  const body = (await response.json().catch(() => ({}))) as { error?: unknown } & T;
+  if (!response.ok) {
+    throw new Error(
+      `gameplay recording ${action} failed: ${typeof body.error === 'string' ? body.error : `HTTP ${response.status}`}`,
+    );
+  }
+  return body;
+}
+
+/** Open the server-owned, project-scoped WebM sink. Video bytes never ride the
+ * JSON command relay: a long QA playthrough must not hit its 50 MiB ceiling. */
+export async function beginGameplayRecordingSink(
+  input: {
+    startedAt: string;
+    mimeType: string;
+    format?: 'composite-webm' | 'canvas-dom';
+    /** Fixed-step exports do not use the session's wall-clock playback timeline. */
+    purpose?: 'export';
+    /** During Play, `null` names the clip after the Gameplay Session; outside
+     *  one it falls back to `play-latest.webm`. A name takes a keepsake path. */
+    name?: string | null;
+  },
+  signal?: AbortSignal,
+): Promise<GameplayRecordingSink> {
+  const response = await fetch(`${BASE}/recording/start`, {
+    ...(signal ? { signal } : {}),
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+  return recordingResponse<GameplayRecordingSink>(response, 'start');
+}
+
+/** Append an ordered batch of standard rrweb events. */
+export async function appendGameplayRecordingDomEvents(
+  sink: GameplayRecordingSink,
+  sequence: number,
+  eventsJson: Blob,
+  signal?: AbortSignal,
+): Promise<void> {
+  const query = new URLSearchParams({ id: sink.id, sequence: String(sequence) });
+  const response = await fetch(`${BASE}/recording/dom?${query}`, {
+    ...(signal ? { signal } : {}),
+    method: 'POST',
+    // This is a streamed file body. Labeling it application/json lets the
+    // server's ordinary JSON middleware consume it before the route can apply
+    // its own byte bound, ordering, and append semantics.
+    headers: { 'content-type': 'application/octet-stream' },
+    body: eventsJson,
+  });
+  await recordingResponse<Record<string, never>>(response, 'DOM event upload');
+}
+
+/** Store one image interned out of the rrweb event stream. */
+export async function appendGameplayRecordingAsset(
+  sink: GameplayRecordingSink,
+  name: string,
+  asset: Blob,
+  signal?: AbortSignal,
+): Promise<void> {
+  const query = new URLSearchParams({ id: sink.id, name });
+  const response = await fetch(`${BASE}/recording/asset?${query}`, {
+    ...(signal ? { signal } : {}),
+    method: 'POST',
+    headers: { 'content-type': asset.type || 'application/octet-stream' },
+    body: asset,
+  });
+  await recordingResponse<Record<string, never>>(response, 'replay asset upload');
+}
+
+/** Append one ordered MediaRecorder chunk to the open WebM. */
+export async function appendGameplayRecordingChunk(
+  sink: GameplayRecordingSink,
+  sequence: number,
+  chunk: Blob,
+  signal?: AbortSignal,
+): Promise<void> {
+  const query = new URLSearchParams({ id: sink.id, sequence: String(sequence) });
+  const response = await fetch(`${BASE}/recording/chunk?${query}`, {
+    ...(signal ? { signal } : {}),
+    method: 'POST',
+    headers: { 'content-type': 'application/octet-stream' },
+    body: chunk,
+  });
+  await recordingResponse<Record<string, never>>(response, 'chunk upload');
+}
+
+export async function finishGameplayRecordingSink(
+  sink: GameplayRecordingSink,
+  /** What ended it — journalled verbatim beside the file it produced. */
+  reason?: string | null,
+  signal?: AbortSignal,
+  replay?: Record<string, unknown> | null,
+): Promise<void> {
+  const response = await fetch(`${BASE}/recording/finish`, {
+    ...(signal ? { signal } : {}),
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ id: sink.id, reason: reason ?? null, replay: replay ?? null }),
+  });
+  await recordingResponse<Record<string, never>>(response, 'finish');
+}
+
+/** Deliberately NOT read through `editor-server-response.ts`: this is the
+ *  teardown leg, called only when a recording is already being abandoned, and
+ *  its `.catch(() => undefined)` is the contract — there is no caller left to
+ *  report to, so asserting could only turn a silent no-op into a swallowed
+ *  throw. */
+export async function abortGameplayRecordingSink(sink: GameplayRecordingSink): Promise<void> {
+  await fetch(`${BASE}/recording/abort`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ id: sink.id }),
+  }).catch(() => undefined);
+}

package/src/kit/api/themes.ts

@@ -0,0 +1,45 @@
+/**
+ * Custom palette documents over the wire (`server/routes/themes.ts`): one
+ * JSON file per theme under `~/.volter/themes/` (user) and
+ * `<project>/.volter/themes/` (project) — both files the editor server owns.
+ */
+import { assertEditorServerResponse, editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+import type { SettingsLayer } from '@volter/sdk/kit/api-settings';
+
+export interface ThemeDocumentRead {
+  readonly id: string;
+  readonly path: string;
+  readonly document: unknown;
+}
+
+export interface ThemeLayerRead {
+  readonly documents: readonly ThemeDocumentRead[];
+  /** Files that could not be read as JSON, spelled by path. */
+  readonly issues: readonly string[];
+}
+
+export async function listThemeDocuments(layer: SettingsLayer): Promise<ThemeLayerRead> {
+  const res = await fetch(`${BASE}/themes/${layer}`);
+  return editorServerJson<ThemeLayerRead>(res, `Could not list ${layer} themes`);
+}
+
+export async function saveThemeDocument(
+  layer: SettingsLayer,
+  id: string,
+  document: unknown,
+): Promise<void> {
+  const res = await fetch(`${BASE}/themes/${layer}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id, document }),
+  });
+  assertEditorServerResponse(res, `Could not save the ${layer} theme ${id}`);
+}
+
+export async function deleteThemeDocument(layer: SettingsLayer, id: string): Promise<void> {
+  const res = await fetch(`${BASE}/themes/${layer}?id=${encodeURIComponent(id)}`, {
+    method: 'DELETE',
+  });
+  assertEditorServerResponse(res, `Could not delete the ${layer} theme ${id}`);
+}

package/src/kit/api-asset-library-wire.ts

@@ -0,0 +1,45 @@
+/**
+ * The asset-library wire — the shapes `/__editor/assets/*` answers with,
+ * declared ONCE in a leaf module both sides import (the browser client in
+ * `./assets.ts`, the producing routes in `../../server/asset-library-routes.ts`).
+ * Deliberately import-free so the server's tsconfig can reach it without
+ * dragging the client's whole module graph along.
+ */
+
+export interface OnlineAsset {
+  id: string;
+  source: 'polyhaven' | 'ambientcg' | 'local';
+  name: string;
+  type: 'model' | 'animation' | 'source' | 'hdri' | 'texture' | 'material';
+  thumbnailUrl: string;
+  categories: string[];
+  tags: string[];
+  downloadCount?: number;
+  license?: string;
+  author?: string;
+  sourceUrl?: string;
+  cloudHosted?: boolean;
+  variantId?: string;
+  variantCount?: number;
+  sizeBytes?: number;
+  animationCount?: number;
+  deliveryKinds?: ('local-ssd' | 'cloud' | 'remote')[];
+  addedAt?: string;
+  capabilities?: {
+    previewable: boolean;
+    importable: boolean;
+    runtimeReady: boolean;
+    animated: boolean;
+    deliveryAvailable: boolean;
+    health: 'healthy' | 'source-only' | 'unsupported';
+  };
+}
+
+export interface AssetFileOption {
+  label: string;
+  format: string;
+  url: string;
+  sizeBytes?: number;
+  /** Additional files that must be downloaded alongside the main URL (GLTF includes). */
+  includes?: { relativePath: string; url: string; size: number }[];
+}

package/src/kit/api-base.ts

@@ -0,0 +1,10 @@
+/**
+ * What every `api/<family>.ts` module shares: the route prefix every
+ * `/__editor/*` op is written against.
+ *
+ * The session serves the editor and answers these routes (ARCHITECTURE-CORE
+ * §The target shape rule 5), so a family module asks no question before
+ * touching the network.
+ */
+
+export const BASE = '/__editor';

package/src/kit/api-build.ts

@@ -0,0 +1,99 @@
+/**
+ * Producing a build, and the two catalogues the New Project screen starts one
+ * from: `/__editor/export`, `/__editor/examples`, `/__editor/templates`.
+ */
+
+import { editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+/** Start a build/export. Returns the raw Response for SSE streaming.
+ *
+ *  Deliberately NOT read through `editor-server-response.ts`: that reader's
+ *  rule is "the editor server answers JSON", and a successful export answers
+ *  `text/event-stream`, which it would reject. The stream's own consumer owns
+ *  the question here. */
+
+/** FT-5 learner-facing metadata — mirrors the manifest's `learn` block
+ *  (`LearnMetadataSchema`, @volter/project/manifest/schema); served merged into `GET
+ *  /__editor/examples`. */
+export interface ExampleLearnInfo {
+  kind: 'starter' | 'feature' | 'sample-game' | 'lesson-companion';
+  title: string;
+  summary: string;
+  difficulty: 'beginner' | 'intermediate' | 'advanced';
+  features: string[];
+  thumbnail?: string;
+  preview?: string;
+  lesson?: string;
+}
+
+export interface ExampleInfo {
+  id: string;
+  name: string;
+  /** The example's FT-5 `learn` block. REQUIRED: every shipped example
+   *  carries one and the server omits any example that doesn't (editor and
+   *  server ship from one repo, so there is no older server to be compatible
+   *  with). */
+  learn: ExampleLearnInfo;
+}
+
+/** List `examples/<id>/` projects (Track E3, §1.F). Server mode reads the
+ *  scaffold registry. Browser mode derives the list from what THIS build
+ *  actually stages: the runtime bundle's per-root dispatch keys name every
+ *  bundled example, and each one's manifest (with its FT-5 `learn` block) is
+ *  served at `/examples/<id>/volter.project.json` — so the gallery lists
+ *  exactly the projects `?project=<id>` can open, never a curated id that
+ *  drifted from the build (the dead `editor-tutorial` link, measured on
+ *  production 2026-08-27, was exactly that drift). */
+export async function listExamples(): Promise<ExampleInfo[]> {
+  try {
+    const res = await fetch(`${BASE}/examples`);
+    const data = await editorServerJson<{ examples: ExampleInfo[] }>(
+      res,
+      `GET ${BASE}/examples failed`,
+    );
+    return data.examples;
+  } catch {
+    return [];
+  }
+}
+
+/** One template-registry entry (G1, FT-3): mirrors `TemplateRegistryEntry` in
+ *  create-volter-project/templates, served by `GET /__editor/templates` from the
+ *  same `templates.json` the CLI reads. */
+export interface TemplateInfo {
+  id: string;
+  title: string;
+  description: string;
+  /** `template:<compositionId>` or `example:<exampleId>`. */
+  source: string;
+  thumbnail?: string;
+  /** Curated preview bullets for composition templates. Promoted examples
+   * derive their facts from the owning example's learn metadata. */
+  whatsInside?: string[];
+  /** A post-copy PRESENTATION of `source`'s tree. The gallery's
+   * "Blank" card carries `'blank'` beside the SAME `template:default` source
+   * the starter card uses — two cards, one template. */
+  presentation?: string;
+}
+
+/** Map an engine-repo-relative registry/learn thumbnail path to its server
+ * route without baking template or example directories into the client. */
+export function learnThumbnailUrl(repoRelativePath: string): string {
+  // Browser-mode example thumbnails are already staged ABSOLUTE paths
+  // (`/examples/<id>/learn/…`) — there is no server route to proxy them.
+  if (repoRelativePath.startsWith('/')) return repoRelativePath;
+  return `${BASE}/learn-thumbnail?file=${encodeURIComponent(repoRelativePath)}`;
+}
+
+/** List the template registry. */
+export async function listTemplates(): Promise<TemplateInfo[]> {
+  // No silent empty-list fallback and no hardcoded fallback entry in the
+  // wizard: editor and server ship from ONE repo, so an unreachable or
+  // failing `/templates` is a real defect, not version skew. Surface it.
+  const res = await fetch(`${BASE}/templates`);
+  const data = await editorServerJson<{ templates: TemplateInfo[] }>(
+    res,
+    `GET ${BASE}/templates failed`,
+  );
+  return data.templates;
+}

package/src/kit/api-git-wire.ts

@@ -0,0 +1,56 @@
+/**
+ * The git-workflow wire — the status shape `/__editor/git/*` answers with,
+ * declared ONCE in a leaf module both sides import (the browser client in
+ * `../share-control-client.ts`, the producing `../../server/git-workflow.ts`).
+ * Import-free so the server's tsconfig can reach it without the client's
+ * module graph. The share wire next door (`@volter/sdk/share`) had this
+ * fix applied first; the git wire in the same panel had been re-spelled
+ * inline, twenty lines below the header describing that fix.
+ */
+
+export interface GitChangedPath {
+  path: string;
+  index: string;
+  worktree: string;
+}
+
+export interface GitDiffHunk {
+  id: string;
+  path: string;
+  staged: boolean;
+  header: string;
+  additions: number;
+  deletions: number;
+}
+
+export interface GitHistoryCommit {
+  sha: string;
+  shortSha: string;
+  author: string;
+  authoredAt: string;
+  subject: string;
+}
+
+export interface GitWorkflowStatus {
+  available: boolean;
+  repositoryId: string;
+  worktreeId: string;
+  worktreeRoot: string;
+  projectRelativePath: string;
+  branch: string | null;
+  headCommit: string | null;
+  baseRef: string | null;
+  upstream: string | null;
+  remoteUrl: string | null;
+  dirty: boolean;
+  ahead: number | null;
+  behind: number | null;
+  baseAhead: number | null;
+  baseBehind: number | null;
+  changed: GitChangedPath[];
+  hunks: GitDiffHunk[];
+  history: GitHistoryCommit[];
+  conflicts: string[];
+  rebaseInProgress: boolean;
+  github: boolean;
+}

package/src/kit/api-logs.ts

@@ -0,0 +1,92 @@
+/**
+ * Play-mode console log persistence — agent/CLI-tooling introspection, so it
+ * is bucketed with the CLI control channel.
+ */
+
+import { assertEditorServerResponse, editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+// ---------------------------------------------------------------------------
+// Play-mode console log persistence
+// ---------------------------------------------------------------------------
+
+export interface LogEntry {
+  t: number;
+  level: string;
+  source?: string;
+  sub?: string;
+  msg: string;
+  meta?: Record<string, unknown>;
+  /** Engine fixed-step counter at write time —
+   *  present only while a live play session's debug seam can be read, so
+   *  entries correlate frame-exactly with `ctx.debug.emit` events. */
+  tick?: number;
+  /** Accumulated sim-seconds at write time — same source as `tick`. */
+  simT?: number;
+  /** The world this run was presenting when the entry was written. Present
+   *  only once the run's roots have mounted and a world is unambiguous (see
+   *  `play-mode.ts`'s `playLogRunStamp`) — entries written during boot, and
+   *  runs that present no world at all, honestly carry none. */
+  world?: string;
+  /** The loop's live time scale at write time (`game.loop.timeScale`) — 1 is
+   *  real time, 0 is paused, and an instrument can change it mid-run, which is
+   *  exactly why it is per-entry and not in the file's identity header. */
+  simSpeed?: number;
+}
+
+/** Start a new log session. Returns the filename, or null on failure.
+ *  Browser mode writes the SAME `logs/play-*.jsonl` record through the
+ *  StorageBackend (`play-log/browser-play-log.ts`) — the Analytics utility's
+ *  Gameplay Sessions read it, and a downloaded project carries its history —
+ *  while a staged example/ingest stays a no-op (no storage home). */
+export async function startLogSession(name?: string | null): Promise<string | null> {
+  try {
+    const res = await fetch(`${BASE}/log-session`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      // `name` (optional — the editor's `play --name <text>` command) is passed through RAW;
+      // the server owns the slugifier, so there is exactly one definition of
+      // what the run is called on disk and in the journal.
+      body: JSON.stringify({ action: 'start', ...(name ? { name } : {}) }),
+    });
+    const data = await editorServerJson<{ ok: boolean; file: string }>(
+      res,
+      'Could not start a play log session',
+    );
+    return data.file;
+  } catch {
+    return null;
+  }
+}
+
+/** End the current log session. Browser mode closes the storage-backed log. */
+export async function endLogSession(): Promise<void> {
+  try {
+    const res = await fetch(`${BASE}/log-session`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'end' }),
+    });
+    assertEditorServerResponse(res, 'Could not end the play log session');
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Flush a batch of log entries. Browser mode appends to the storage-backed
+ *  log (never a network call — this runs on a `setInterval` while Play is
+ *  running, and a dead endpoint here is the retry-loop anti-pattern A2's SSE
+ *  guards exist to avoid). */
+export async function flushLogEntries(entries: LogEntry[]): Promise<boolean> {
+  if (entries.length === 0) return true;
+  try {
+    const res = await fetch(`${BASE}/log-entries`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ entries }),
+    });
+    assertEditorServerResponse(res, 'Could not flush play log entries');
+    return true;
+  } catch {
+    return false;
+  }
+}