@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/api/project-open.ts

@@ -0,0 +1,355 @@
+/**
+ * Choosing, creating and OPENING a project — the New Project screen's client
+ * half, plus the runtime project switch.
+ *
+ * The user-triggered actions with no browser equivalent throw a clear, honest
+ * `Error` rather than doing a doomed fetch (`createProject`, `browseFolder`,
+ * `openProjectOnServer`, `revealInFinder`); the browser-mode UI either hides
+ * the affordance or catches the throw into an existing error banner.
+ */
+
+import {
+  assertProjectCompatibility,
+  editorServerUnavailableError,
+  isStartupRecovery,
+  ProjectCompatibilityError,
+} from '@volter/sdk/session/editor-compatibility';
+import type { ProjectInspection } from '@volter/project/inspection';
+import {
+  assertEditorServerAnswered,
+  assertEditorServerResponse,
+  editorServerJson,
+} from '@volter/sdk/kit/editor-server-response';
+import { BASE } from '@volter/sdk/kit/api-base';
+import { requireEditorCompatibility } from '@volter/sdk/kit/api-project-identity';
+
+/** One row of the launcher's recent-projects list. */
+export interface RecentProject {
+  name: string;
+  path: string;
+  lastOpened: string;
+  thumbnail?: string;
+}
+/** List recently opened projects — the folders this machine's sessions have
+ *  opened, tracked by the editor server. */
+export async function listRecentProjects(): Promise<RecentProject[]> {
+  try {
+    const res = await fetch(`${BASE}/recent-projects`);
+    const data = await editorServerJson<{ projects: RecentProject[] }>(
+      res,
+      'Could not list recent projects',
+    );
+    return data.projects;
+  } catch {
+    return [];
+  }
+}
+
+/** Forget one launcher entry without touching the project folder. */
+export async function removeRecentProject(path: string): Promise<void> {
+  const response = await fetch(`${BASE}/recent-projects`, {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path }),
+  });
+  assertEditorServerResponse(response, 'Could not remove recent project');
+}
+
+/** User-global launcher preferences (G5). */
+export interface LauncherSettings {
+  reopenLastProject: boolean;
+}
+
+const DEFAULT_LAUNCHER_SETTINGS: LauncherSettings = { reopenLastProject: false };
+
+/** Read the launcher preferences. Any failure degrades to the documented
+ *  defaults — a preferences read must never be able to block boot. */
+export async function getLauncherSettings(): Promise<LauncherSettings> {
+  try {
+    const res = await fetch(`${BASE}/launcher-settings`);
+    const data = await editorServerJson<Partial<LauncherSettings>>(
+      res,
+      'Could not read launcher settings',
+    );
+    return {
+      reopenLastProject:
+        typeof data.reopenLastProject === 'boolean'
+          ? data.reopenLastProject
+          : DEFAULT_LAUNCHER_SETTINGS.reopenLastProject,
+    };
+  } catch {
+    return { ...DEFAULT_LAUNCHER_SETTINGS };
+  }
+}
+
+/** Persist a launcher preference. Unlike the read above this throws on
+ *  failure: a toggle that silently does nothing would leave the checkbox
+ *  lying about what happens at the next launch. */
+export async function updateLauncherSettings(
+  update: Partial<LauncherSettings>,
+): Promise<LauncherSettings> {
+  const res = await fetch(`${BASE}/launcher-settings`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(update),
+  });
+  return await editorServerJson<LauncherSettings>(res, 'Could not save launcher settings');
+}
+
+/** Create a project from a registry source. The server validates the plain
+ * string against the scaffolder's live capability tuple. */
+export async function createProject(
+  name: string,
+  location: string,
+  template: string,
+  exampleId?: string,
+  presentation?: string,
+  additions: readonly string[] = [],
+): Promise<{ ok: boolean; path?: string; config?: { name: string }; error?: string }> {
+  const res = await fetch(`${BASE}/create-project`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name,
+      location,
+      template,
+      ...(exampleId ? { exampleId } : {}),
+      ...(presentation ? { presentation } : {}),
+      ...(additions.length > 0 ? { additions } : {}),
+    }),
+  });
+  // The route reports its own refusals in `{ ok: false, error }` with a non-2xx
+  // status, and the New Project form renders that string — so only the "did the
+  // editor server answer at all" half applies here.
+  assertEditorServerAnswered(res, 'Could not create the project');
+  return (await res.json()) as {
+    ok: boolean;
+    path?: string;
+    config?: { name: string };
+    error?: string;
+  };
+}
+
+/** Open a native folder picker dialog. Returns the selected path, or null if cancelled. */
+export async function browseFolder(title?: string): Promise<string | null> {
+  try {
+    const res = await fetch(`${BASE}/browse-folder`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title }),
+    });
+    const data = await editorServerJson<{ path: string | null }>(
+      res,
+      'Could not open the folder picker',
+    );
+    return data.path;
+  } catch {
+    return null;
+  }
+}
+
+/** Inspect an arbitrary local folder without opening it or writing Volter files. */
+export async function inspectProjectFolder(
+  path: string,
+): Promise<{ path: string; report: ProjectInspection }> {
+  const res = await fetch(`${BASE}/inspect-project`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path }),
+  });
+  assertEditorServerAnswered(res, `Could not inspect ${path}`);
+  const payload = (await res.json()) as {
+    ok?: boolean;
+    path?: string;
+    report?: ProjectInspection;
+    error?: string;
+  };
+  if (!res.ok || !payload.path || !payload.report) {
+    throw new Error(payload.error ?? `Could not inspect ${path}.`);
+  }
+  return { path: payload.path, report: payload.report };
+}
+
+/** Add the one-file Volter metadata bridge after the user approves an inspection. */
+export async function adaptProjectFolder(
+  path: string,
+  selection?: { surface?: ProjectInspection['suggestedSurface']; entry?: string },
+): Promise<{ path: string; writes: string[] }> {
+  const res = await fetch(`${BASE}/adapt-project`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path, ...selection }),
+  });
+  assertEditorServerAnswered(res, `Could not add Volter Editor metadata to ${path}`);
+  const payload = (await res.json()) as { path?: string; writes?: string[]; error?: string };
+  if (!res.ok || !payload.path || !payload.writes) {
+    throw new Error(payload.error ?? `Could not add Volter Editor metadata to ${path}.`);
+  }
+  return { path: payload.path, writes: payload.writes };
+}
+
+/** Reveal a file or folder in the OS file manager. */
+export async function revealInFinder(targetPath: string): Promise<void> {
+  const res = await fetch(`${BASE}/reveal`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path: targetPath }),
+  });
+  // Every caller is a fire-and-forget menu action, so this rejection reaches
+  // the editor console through the page's `unhandledrejection` capture
+  // (`editor-console.ts`) — which is still a report, where the unread response
+  // was a file manager that never opened and nothing said so.
+  assertEditorServerResponse(res, `Could not reveal ${targetPath}`);
+}
+
+/** Save a viewport thumbnail for the current project — background bookkeeping
+ *  for the recent-projects list, not a user-facing promise. */
+export async function saveThumbnail(dataUrl: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${BASE}/save-thumbnail`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ dataUrl }),
+    });
+    assertEditorServerResponse(res, 'Could not save the project thumbnail');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface ServerProject {
+  path: string;
+  config: {
+    manifestVersion: 2;
+    name: string;
+    version: string;
+    engine: { version: string };
+    [key: string]: unknown;
+  };
+  /** Whether the project ships src/ui/registry.ts (scene-UI project mode, D9). */
+  hasUiRegistry?: boolean;
+  /** Whether this server is the no-monorepo-checkout packaged runtime
+   *  (`packages/editor-core/server/packaged.ts`) — see `binding-resolver.ts`'s
+   *  `isPackagedRuntime` for why a react world's mount needs this. */
+  packaged?: boolean;
+  /** The engine package resolved from this project's own node_modules graph. */
+  enginePackage?: {
+    name: '@volter/game-runtime';
+    version: string | null;
+    path: string;
+    installPath: string;
+    linked: boolean;
+  } | null;
+}
+
+/**
+ * What the server says it is serving — with the failures kept apart from the
+ * answer "nothing".
+ *
+ * `getCurrentServerProject` (below) flattens all three negatives to `null`,
+ * which is fine for a background read that only wants the happy path. It is
+ * NOT fine at boot: `null` there routes to the launcher, so a lost request or
+ * an unreadable manifest silently claimed the server had no project while it
+ * was serving one. See `boot-routing.ts`'s `decideServerProjectBoot`.
+ */
+export type ServerProjectProbe =
+  | { status: 'project'; project: ServerProject }
+  | { status: 'none' }
+  /** Serving `path`, but the server could not describe it (broken manifest). */
+  | { status: 'unreadable'; path: string; error: string }
+  /** The ask itself failed — server down, mid-restart, malformed answer. */
+  | { status: 'unknown'; error: string };
+
+interface ServerProjectResponse {
+  project: ServerProject | null;
+  serving?: { path?: unknown; error?: unknown } | null;
+}
+
+/** Ask the server what it serves, keeping the reason when it cannot say. */
+export async function probeCurrentServerProject(): Promise<ServerProjectProbe> {
+  // Browser mode has no Node dev server to ask — same honest no-fetch
+  // degrade as the other background reads in this file.
+  let data: ServerProjectResponse;
+  try {
+    const res = await fetch(`${BASE}/project`);
+    data = await editorServerJson<ServerProjectResponse>(res, `No answer from ${BASE}/project`);
+  } catch (error) {
+    return {
+      status: 'unknown',
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+  if (data.project) return { status: 'project', project: data.project };
+  const serving = data.serving;
+  if (serving && typeof serving.path === 'string') {
+    return {
+      status: 'unreadable',
+      path: serving.path,
+      error: typeof serving.error === 'string' ? serving.error : 'unknown error',
+    };
+  }
+  if (data.project === null) return { status: 'none' };
+  return { status: 'unknown', error: `Unrecognized ${BASE}/project response` };
+}
+
+/** Query the server for the currently active project (if any). Every failure
+ *  reads as "no project" — see `probeCurrentServerProject` for the callers
+ *  (boot) that must not make that trade. */
+export async function getCurrentServerProject(): Promise<ServerProject | null> {
+  const probe = await probeCurrentServerProject();
+  return probe.status === 'project' ? probe.project : null;
+}
+
+/** Open/switch to a project by its filesystem path. */
+export async function openProjectOnServer(projectPath: string): Promise<{
+  ok: boolean;
+  config?: {
+    manifestVersion: 2;
+    name: string;
+    version: string;
+    engine: { version: string };
+    [key: string]: unknown;
+  };
+}> {
+  const compatibility = await requireEditorCompatibility();
+  const res = await fetch(`${BASE}/open-project`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path: projectPath }),
+  });
+  let payload: unknown;
+  try {
+    // The fallback check goes INSIDE this try so a page-fallback answer reaches
+    // the same startup-recovery error class the parse failure already used —
+    // now naming the cause instead of "invalid response".
+    assertEditorServerAnswered(res, `Could not open project at ${projectPath}`);
+    payload = await res.json();
+  } catch (cause) {
+    throw editorServerUnavailableError(
+      cause instanceof Error ? cause.message : `HTTP ${res.status} returned an invalid response`,
+    );
+  }
+  if (!res.ok) {
+    if (payload && typeof payload === 'object') {
+      const failure = payload as Record<string, unknown>;
+      if (typeof failure['error'] === 'string' && isStartupRecovery(failure['recovery'])) {
+        throw new ProjectCompatibilityError(failure['error'], failure['recovery']);
+      }
+      if (typeof failure['error'] === 'string') throw new Error(failure['error']);
+    }
+    throw new Error(`Could not open project at ${projectPath}: HTTP ${res.status}`);
+  }
+  const result = payload as {
+    ok: boolean;
+    config?: {
+      manifestVersion: 2;
+      name: string;
+      version: string;
+      engine: { version: string };
+      [key: string]: unknown;
+    };
+  };
+  if (result.config) assertProjectCompatibility(result.config, compatibility);
+  return result;
+}

package/src/kit/api/project-source.ts

@@ -0,0 +1,180 @@
+/**
+ * Reading and writing the project's own files.
+ *
+ * `public/` operations route through the backend-agnostic `StorageBackend`
+ * (`../storage`): `HttpStorage` over the same `/__editor/*` routes, wrapped by
+ * the frame's file door once its provider lands.
+ *
+ * The SPA-fallback check here is load-bearing: a dev server answers 200 with
+ * the editor's own `index.html` for a missing file, so "did I get the file"
+ * cannot be asked of the status code alone.
+ */
+
+import { base64ToBytes } from '@volter/sdk/kit/bytes-codec';
+import { servedUrl } from '../served-url';
+import { getStorageBackend } from '../storage/index';
+
+/**
+ * Read a project text file from the session that owns the project namespace.
+ *
+ * The storage backend is NOT the door here: `HttpStorage` is rooted at
+ * `public/`, not at the project root, so asking it for `src/...` produces a
+ * known-false asset-list 404 before the real Vite read. This goes directly to
+ * HTTP. Returns null when the file is not served.
+ */
+export async function readProjectTextFile(path: string): Promise<string | null> {
+  try {
+    const res = await fetch(servedUrl(path));
+    if (res.ok) return await res.text();
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+/**
+ * A project source file as written, or null when it is absent or unreadable.
+ * The dev server serves `src/...` TRANSFORMED (imports rewritten to served
+ * paths), so a reader of the author's source asks `/__editor/source-file`.
+ */
+export async function readProjectSourceText(path: string): Promise<string | null> {
+  try {
+    const res = await fetch(`/__editor/source-file?path=${encodeURIComponent(path.replace(/^\.?\//, ''))}`, {
+      cache: 'no-store',
+    });
+    if (res.ok) return await res.text();
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+/**
+ * What a probe can honestly conclude about a project file. THREE answers,
+ * because "no" and "I could not tell" are different facts and a boolean has
+ * to spend one of them.
+ */
+export type ProjectFilePresence = 'present' | 'absent' | 'unreachable';
+
+/**
+ * A 200 that is really the SPA FALLBACK, not the file.
+ *
+ * MEASURED, dev server, project root `public/ingest/cuberun/` (which owns no
+ * `editor/volter.adapter.ts`):
+ *
+ *   curl -sI /editor/volter.adapter.ts   -> 200, Content-Type: text/html      (index.html)
+ *   curl -sI /volter.project.json -> 200, Content-Type: application/json; charset=utf-8
+ *
+ * The fallback serves the editor's own `index.html`, so it is identifiable by
+ * the one thing it cannot hide: it is an HTML DOCUMENT. Nothing this probe is
+ * ever pointed at — a module, a manifest, an asset — is served as `text/html`,
+ * and the storage backend answers first for anything that could be.
+ *
+ * This shape is not dev-only: `docs/DEPLOY.md` §Surface 3 specifies serving
+ * `dist/` with an index.html fallback, i.e. "a missing asset returns
+ * `index.html`". Both shipped surfaces answer the same way.
+ */
+function isSpaFallbackDocument(response: Response): boolean {
+  return (response.headers.get('content-type') ?? '').toLowerCase().includes('text/html');
+}
+
+/**
+ * Does this project file exist? — CONTENT-DISCRIMINATED, because on both
+ * surfaces this product ships an existence probe that trusts `res.ok` is a
+ * constant `true`.
+ *
+ * `HttpStorage` is deliberately rooted at
+ * `public/`, while this probe accepts project-root paths such as
+ * `src/prefabs/Player.tsx`; asking that backend first turns an ordinary source
+ * probe into a noisy `/__editor/assets?dir=src` 404. This therefore
+ * asks Vite directly with HEAD. Both routes remain existence-only — neither
+ * downloads the file body.
+ *
+ * The HTTP probe classifies rather than trusting `res.ok`:
+ *
+ *   - not ok            -> `absent` (a real 404 from a real route);
+ *   - ok + `text/html`  -> `absent`  — {@link isSpaFallbackDocument}, the
+ *     measured false positive;
+ *   - ok, anything else -> `present` (a real file answering with its own
+ *     content type);
+ *   - the fetch throws  -> `unreachable`. NOT `absent`: an unanswered probe is
+ *     a fact about the transport, and a caller that must not act on a guess
+ *     (see `project-adapter.ts`, which chooses a BINDING TABLE off this) is
+ *     entitled to know the difference.
+ *
+ * This function's earlier docblock already recorded the false positive —
+ * "the dev server's SPA fallback also answers a HEAD/GET for a MISSING path
+ * with 200 (it serves `index.html` rather than 404), so `res.ok` alone cannot
+ * fully distinguish 'exists' from 'missing'" — and dismissed it as harmless
+ * because "a false positive here just means a subsequent real open attempt
+ * fails through its own error path". That held for the then-only caller
+ * (`workspace-state-persistence`, probing `public/`-rooted asset paths the
+ * storage backend answers authoritatively). It stopped holding the moment a
+ * project-ROOT path was probed AHEAD of a branch that would otherwise have
+ * succeeded: the "own error path" then reports a load failure for a file the
+ * project never had, and the real binding is never reached. The discrimination
+ * lives HERE, inside the probe, so the next caller cannot re-inherit the blind
+ * question.
+ */
+export async function probeProjectFile(path: string): Promise<ProjectFilePresence> {
+  // Ask the origin; the fallback detector below keeps a SPA 200 from counting
+  // as the file.
+  try {
+    const res = await fetch(servedUrl(path), { method: 'HEAD' });
+    if (!res.ok) return 'absent';
+    return isSpaFallbackDocument(res) ? 'absent' : 'present';
+  } catch {
+    return 'unreachable';
+  }
+}
+
+/**
+ * Check whether a project file exists WITHOUT reading its content — the
+ * boolean face of {@link probeProjectFile}, for callers with nothing to do
+ * about the difference between "no" and "could not tell". Prefer this over
+ * `readProjectTextFile(...) !== null` when only existence is needed, since
+ * that reads and discards the whole body.
+ */
+export async function projectFileExists(path: string): Promise<boolean> {
+  return (await probeProjectFile(path)) === 'present';
+}
+
+/** Save a file to public/. Returns true on success. */
+export async function saveFile(
+  path: string,
+  content: string,
+  encoding?: 'base64',
+): Promise<boolean> {
+  try {
+    // base64 content → raw bytes; the backend re-encodes per its transport.
+    // `base64ToBytes` is a LOOP; `Uint8Array.from(atob(…), (c) => …)` calls the
+    // mapping callback once per CHARACTER (measured 27.7x slower at 3MB).
+    const data: string | Uint8Array = encoding === 'base64' ? base64ToBytes(content) : content;
+    await getStorageBackend().write(path, data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Project-relative source files matching `globs` (`src/models/**\/*.ts`; `*`
+ * within a segment, `**` across segments) — what a finder's `include`
+ * reads through (`FinderInput.sources`), answered by the session's
+ * `/__editor/source-files` route.
+ */
+export async function listProjectSourceFiles(
+  globs: readonly string[],
+  options: { readonly order?: 'name' | 'mtime' } = {},
+): Promise<string[]> {
+  if (globs.length === 0) return [];
+  const res = await fetch(
+    `/__editor/source-files?${new URLSearchParams([
+      ...globs.map((g): [string, string] => ['include', g]),
+      ...(options.order === 'mtime' ? [['order', 'mtime'] as [string, string]] : []),
+    ])}`,
+  );
+  if (!res.ok) return [];
+  const body = (await res.json()) as { files?: string[] };
+  return body.files ?? [];
+}

package/src/kit/api/project-state.ts

@@ -0,0 +1,110 @@
+/**
+ * What the session currently IS, as the editor's own UI reads it: the server
+ * validation log, the editor lease identity, and the durable
+ * `.volter/editor-state.json` view/tool state.
+ *
+ */
+
+import type { LeasePollResult } from '../editor-lease';
+import { assertEditorServerResponse, editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { postJson } from '@volter/sdk/kit/user-local-state';
+import { BASE } from '@volter/sdk/kit/api-base';
+/**
+ * PD-13: the validation failures and authoring warnings the dev server knows
+ * about RIGHT NOW, pre-formatted as `server-log` payloads. `editor-console.ts`
+ * pulls this once per connection to render what the live broadcast could not
+ * deliver — see `connectServerLogs` for why a pull rather than a push. THROWS
+ * on any failure, including a server that predates the endpoint and an origin
+ * whose page fallback answered instead; the one caller treats a failed replay
+ * as "nothing to replay" and says why.
+ */
+export async function getServerValidationLog(): Promise<{ level: string; message: string }[]> {
+  const res = await fetch(`${BASE}/validation-log`);
+  const data = await editorServerJson<{ entries?: { level: string; message: string }[] }>(
+    res,
+    'Could not read the server validation log',
+  );
+  return data.entries ?? [];
+}
+
+/**
+ * One liveness poll for the editor-lease watchdog (editor-lease.ts): ask the
+ * server on THIS tab's origin who it is. Reuses the same `/__editor/project`
+ * identity endpoint the CLI probes (`session.pid` + the served project path) —
+ * a replaced server on the same port answers with a new pid, which is how the
+ * watchdog detects a takeover.
+ *
+ * `ok: false` is any reason the reading is unusable — connection refused (the
+ * server is gone), a non-OK status, a timeout, or a malformed body — folded
+ * into one "failed poll" the reducer counts toward `server-gone`. The timeout
+ * is short: this runs every few seconds and a hung request should read as a
+ * failure, not stall the poll.
+ */
+export async function pollEditorLeaseIdentity(timeoutMs = 3000): Promise<LeasePollResult> {
+  // Static transports report a page-owned lease; process-backed sessions keep
+  // reporting their server identity, including older servers without a lease field.
+  if (typeof fetch === 'undefined') return { ok: false };
+  try {
+    const res = await fetch(`${BASE}/project`, { signal: AbortSignal.timeout(timeoutMs) });
+    const body = await editorServerJson<{
+      project?: { path?: unknown } | null;
+      session?: { pid?: unknown; lease?: unknown } | null;
+    }>(res, 'Editor lease poll failed');
+    return {
+      ok: true,
+      ...(body.session?.lease === 'page' ? { lease: 'page' as const } : {}),
+      identity: {
+        project: typeof body.project?.path === 'string' ? body.project.path : null,
+        pid: typeof body.session?.pid === 'number' ? body.session.pid : null,
+      },
+    };
+  } catch {
+    return { ok: false };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Persistent editor state (.volter/editor-state.json)
+// ---------------------------------------------------------------------------
+
+/** Load persisted editor state (remembered transform mode/snap/last
+ *  scene/camera). Returns {} if none exists. */
+export async function loadEditorState(): Promise<Record<string, unknown>> {
+  try {
+    const res = await fetch(`${BASE}/editor-state`);
+    return await editorServerJson<Record<string, unknown>>(res, 'Could not read editor state');
+  } catch {
+    return {};
+  }
+}
+
+/** Set once the write below has reported a failure, so an autosave that fires
+ *  on every viewport change reports a permanently broken origin ONCE. */
+let reportedEditorStateWriteFailure = false;
+
+/** Save editor state (persisted in .volter/editor-state.json — see
+ *  `loadEditorState`'s doc comment for the browser-mode routing).
+ *
+ *  The boolean is this function's only channel and its one caller
+ *  (`editor-shell-store.savePersistentState`) discards it, so the failure is
+ *  ALSO logged: `res.ok` used to read a page fallback as a completed write,
+ *  and a silent false would be the same lie one indirection later. */
+export async function saveEditorState(
+  state: Record<string, unknown>,
+  options: { readonly leaving?: boolean } = {},
+): Promise<boolean> {
+  try {
+    // A page going away cancels its requests unless they are kept alive (`postJson` says within
+    // what bound).
+    const res = await postJson(`${BASE}/editor-state`, JSON.stringify(state), options.leaving === true);
+    assertEditorServerResponse(res, 'Could not save editor state');
+    return true;
+  } catch (cause) {
+    if (!reportedEditorStateWriteFailure) {
+      reportedEditorStateWriteFailure = true;
+      // biome-ignore lint/suspicious/noConsole: the editor console captures console.error session-wide — this IS the report channel for a caller that discards the boolean.
+      console.error(cause instanceof Error ? cause.message : String(cause));
+    }
+    return false;
+  }
+}