@volter/editor-core 0.5.57

package/src/api/project-source.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 { resolveUrl } from '@volter/editor-threejs/loader';
+import { base64ToBytes } from '../bytes-codec';
+import { getStorageBackend } from '../storage';
+/**
+ * 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(resolveUrl(path));
+    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
+ * `vgai.adapter.ts`):
+ *
+ *   curl -sI /vgai.adapter.ts   -> 200, Content-Type: text/html      (index.html)
+ *   curl -sI /vgai.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(resolveUrl(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/api/project-state.ts

@@ -0,0 +1,107 @@
+/**
+ * What the session currently IS, as the editor's own UI reads it: the server
+ * validation log, the editor lease identity, and the durable
+ * `.vgai/editor-state.json` view/tool state.
+ *
+ */
+
+import type { LeasePollResult } from '../editor-lease';
+import { assertEditorServerResponse, editorServerJson } from '../editor-server-response';
+import { BASE } from './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> {
+  // Browser mode has no Node server to lease from; the watchdog never mounts
+  // there, but guard anyway so a stray call can never false-void a page.
+  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 } | null;
+    }>(res, 'Editor lease poll failed');
+    return {
+      ok: true,
+      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 (.vgai/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 .vgai/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>): Promise<boolean> {
+  try {
+    const res = await fetch(`${BASE}/editor-state`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(state),
+    });
+    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;
+  }
+}

package/src/api/relay.ts

@@ -0,0 +1,268 @@
+/**
+ * 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 '../editor-server-response';
+import { BASE } from './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 `vgai status` 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.
+ */
+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.
+  reportTabPhase(state.phase);
+  void sendControl('play-phase', { _clientId: EDITOR_CLIENT_ID, ...state });
+}
+
+/** 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/api/settings.ts

@@ -0,0 +1,36 @@
+/**
+ * The two shared settings layers over the wire (`server/routes/settings.ts`):
+ * `~/.vgai/settings.json` (user) and `<project>/.vgai/settings.json`
+ * (project), both files the editor server owns.
+ */
+import type { EditorSettings } from '@volter/editor-project/settings/schema';
+import { assertEditorServerResponse, editorServerJson } from '../editor-server-response';
+import { BASE } from './base';
+
+export type SettingsLayer = 'user' | 'project';
+
+export interface SettingsLayerRead {
+  readonly settings: EditorSettings;
+  /** Problems with the stored document, spelled for the person who owns it. */
+  readonly issues: readonly string[];
+  /** Where the layer lives, for the issue report. */
+  readonly path: string | null;
+}
+
+export async function loadSettingsLayer(layer: SettingsLayer): Promise<SettingsLayerRead> {
+  const res = await fetch(`${BASE}/settings/${layer}`);
+  return editorServerJson<SettingsLayerRead>(res, `Could not read ${layer} settings`);
+}
+
+export async function saveSettingsLayer(
+  layer: SettingsLayer,
+  settings: EditorSettings,
+): Promise<void> {
+  const body = JSON.stringify(settings, null, 2);
+  const res = await fetch(`${BASE}/settings/${layer}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body,
+  });
+  assertEditorServerResponse(res, `Could not save ${layer} settings`);
+}

package/src/api/themes.ts

@@ -0,0 +1,45 @@
+/**
+ * Custom palette documents over the wire (`server/routes/themes.ts`): one
+ * JSON file per theme under `~/.vgai/themes/` (user) and
+ * `<project>/.vgai/themes/` (project) — both files the editor server owns.
+ */
+import { assertEditorServerResponse, editorServerJson } from '../editor-server-response';
+import { BASE } from './base';
+import type { SettingsLayer } from './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}`);
+}