@mostra/react 0.0.0-stage → 0.1.0

package/src/router.ts

@@ -0,0 +1,84 @@
+"use client";
+
+/**
+ * `pages/` routing on React Router (D57): the generated entry hands the routes, and the entry's
+ * layout when it has one, to {@link mountRoutes}. The history follows the delivery target (D111):
+ * browser history behind Mostra's gateway (deep links work, D98), hash routing in a static export
+ * (any static host serves it), memory routing inside an MCP App (its frame has no URL of its own).
+ * Every navigation is reported to the shell, so comments record their page (WP-20).
+ *
+ * Artifact code navigates with React Router's own `<Link to>` and `useNavigate`.
+ */
+import type { DeliveryTarget } from "@mostra/protocol";
+import { type ComponentType, createElement, type ReactNode } from "react";
+import {
+  createBrowserRouter,
+  createHashRouter,
+  createMemoryRouter,
+  Outlet,
+  type RouteObject,
+} from "react-router";
+import { RouterProvider } from "react-router/dom";
+import { prepareArtifact, renderArtifact, reportPage } from "./mount.ts";
+
+/** One route of a `pages/` artifact: its React Router path and its page. */
+export interface PageRouteModule {
+  readonly path: string;
+  readonly page: ComponentType;
+}
+
+/** How a router keeps its location: in the address bar, in its hash, or in memory. */
+export type HistoryMode = "browser" | "hash" | "memory";
+
+/** The history mode for a delivery target (D57, D111). */
+export function historyMode(target: DeliveryTarget): HistoryMode {
+  if (target === "static") return "hash";
+  if (target === "mcp-app") return "memory";
+  return "browser";
+}
+
+/** The route tree: the pages, inside the layout when there is one. */
+export function routeTree(
+  routes: readonly PageRouteModule[],
+  layout?: ComponentType<{ children?: ReactNode }>,
+): RouteObject[] {
+  const pages: RouteObject[] = routes.map((route) => ({
+    path: route.path,
+    element: createElement(route.page),
+  }));
+  if (!layout) return pages;
+  return [{ element: createElement(layout, null, createElement(Outlet)), children: pages }];
+}
+
+/**
+ * Mounts a `pages/` artifact (D57). The generated entry calls it; artifact code doesn't need to.
+ */
+export async function mountRoutes(options: {
+  readonly routes: readonly PageRouteModule[];
+  readonly layout?: ComponentType<{ children?: ReactNode }>;
+}): Promise<void> {
+  const runtime = await prepareArtifact();
+  const tree = routeTree(options.routes, options.layout);
+  const mode = historyMode(runtime.target);
+  const router =
+    mode === "hash"
+      ? createHashRouter(tree)
+      : mode === "memory"
+        ? createMemoryRouter(tree)
+        : createBrowserRouter(tree);
+  const pathOf = (): string => {
+    const location = router.state.location;
+    return `${location.pathname}${location.search}${location.hash}`;
+  };
+  let last = "";
+  const report = (): void => {
+    const path = pathOf();
+    if (path === last) return;
+    last = path;
+    reportPage(runtime, path, document.title);
+  };
+  router.subscribe(report);
+  renderArtifact(runtime, createElement(RouterProvider, { router }));
+  report();
+  document.documentElement.dataset["mostraHistory"] = mode;
+}

package/src/runtime/boot.ts

@@ -0,0 +1,306 @@
+/**
+ * Starts the client runtime for the page (D111): reads the delivery target, connects to the shell
+ * and the gateway in live mode, opens the journal, and wires the page's lifecycle (blur,
+ * `visibilitychange`, `pagehide`) and the bridge (`mostra/fields`, `mostra/flush`,
+ * `mostra/field.focus`, `mostra/version.available`) to the store.
+ */
+import {
+  type DeliveryTarget,
+  type FieldsParams,
+  type FlushResult,
+  mostraFieldFocus,
+  mostraFields,
+  mostraFlush,
+  mostraVersionAvailable,
+  readViewContext,
+  type VersionAvailableParams,
+  type ViewContext,
+} from "@mostra/protocol";
+import { builtVersion, connectShell, listenShell, type ShellConnection } from "../shell-bridge.ts";
+import { blockersForShell, clip, firstThatMatter } from "./bridge-limits.ts";
+import { IndexedDbJournal, type Journal, MemoryJournal } from "./journal.ts";
+import { Store } from "./store.ts";
+import { HttpTransport } from "./transport.ts";
+import { installVerifyProbe } from "./verify-probe.ts";
+
+/** The page's runtime: its store, where it runs, and its shell connection. */
+export interface Runtime {
+  readonly store: Store;
+  /** The delivery target the page was built or exported for (D111): it chooses the history. */
+  readonly target: DeliveryTarget;
+  /**
+   * Where the page runs, as `useArtifact` reports it: the target, except that a live page opened
+   * outside Mostra's shell has no server features and reports `static`.
+   */
+  readonly mode: DeliveryTarget;
+  /** The shell connection, inside Mostra's shell. */
+  readonly shell: ShellConnection | undefined;
+}
+
+/** The delivery target the page was built or exported for: its `mostra-target` meta tag (D111). */
+export function deliveryTarget(): DeliveryTarget {
+  if (typeof document === "undefined") return "live";
+  const content = document
+    .querySelector('meta[name="mostra-target"]')
+    ?.getAttribute("content")
+    ?.trim();
+  return content === "static" || content === "mcp-app" || content === "verify" ? content : "live";
+}
+
+/** A random ID for this tab. */
+function tabId(): string {
+  const bytes = new Uint8Array(12);
+  globalThis.crypto.getRandomValues(bytes);
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+interface Locks {
+  request(name: string, callback: () => Promise<unknown>): Promise<unknown>;
+  request(
+    name: string,
+    options: { mode?: "exclusive" | "shared" },
+    callback: () => Promise<unknown>,
+  ): Promise<unknown>;
+  query(): Promise<{ held?: { name?: string }[] }>;
+}
+
+function locks(): Locks | undefined {
+  const navigatorLocks = (globalThis.navigator as { locks?: Locks } | undefined)?.locks;
+  return navigatorLocks;
+}
+
+const TAB_LOCK = "mostra-tab:";
+
+/** How long a tab waits for other tabs to say they are open, where Web Locks are missing. */
+const PRESENCE_WAIT_MS = 300;
+
+/**
+ * Where Web Locks are missing (they need a secure context, and an artifact served over plain
+ * HTTP on a LAN address isn't one), open tabs answer a roll call on a BroadcastChannel, which
+ * works everywhere: a tab that doesn't answer within {@link PRESENCE_WAIT_MS} is gone.
+ */
+function rollCall(
+  tab: string,
+): ((tabs: readonly string[]) => Promise<ReadonlySet<string>>) | undefined {
+  if (typeof BroadcastChannel === "undefined") return undefined;
+  const channel = new BroadcastChannel("mostra-tabs");
+  channel.onmessage = (event: MessageEvent<{ who?: true; here?: string }>) => {
+    if (event.data?.who) channel.postMessage({ here: tab });
+  };
+  return (tabs) =>
+    new Promise((resolve) => {
+      const open = new Set<string>();
+      const listen = new BroadcastChannel("mostra-tabs");
+      listen.onmessage = (event: MessageEvent<{ here?: string }>) => {
+        if (typeof event.data?.here === "string") open.add(event.data.here);
+      };
+      listen.postMessage({ who: true });
+      setTimeout(() => {
+        listen.close();
+        resolve(new Set(tabs.filter((other) => !open.has(other))));
+      }, PRESENCE_WAIT_MS);
+    });
+}
+
+/**
+ * Holds this tab's lock for as long as the page lives, so other pages know its journal entries
+ * belong to an open tab (Web Locks). Returns which of some tabs hold no lock: they are gone.
+ */
+function tabPresence(tab: string): (tabs: readonly string[]) => Promise<ReadonlySet<string>> {
+  const api = locks();
+  if (!api) return rollCall(tab) ?? (async (tabs) => new Set(tabs));
+  void api.request(`${TAB_LOCK}${tab}`, () => new Promise<never>(() => undefined));
+  return async (tabs) => {
+    const held = new Set(
+      ((await api.query()).held ?? [])
+        .map((lock) => lock.name)
+        .filter((name): name is string => name?.startsWith(TAB_LOCK) === true)
+        .map((name) => name.slice(TAB_LOCK.length)),
+    );
+    return new Set(tabs.filter((other) => !held.has(other)));
+  };
+}
+
+/** Runs `fn` while no other page of the artifact adopts journal entries. */
+function exclusive<T>(fn: () => Promise<T>): Promise<T> {
+  const api = locks();
+  if (!api) return fn();
+  return api.request("mostra-journal", fn) as Promise<T>;
+}
+
+/** The longest pause between two attempts at the shell's handshake. */
+const SHELL_RETRY_MAX_MS = 8_000;
+
+/**
+ * The shell's connection for a framed page. A page inside a frame is inside Mostra's shell (its
+ * origin is framed by the shell only): if the handshake fails (the daemon restarting during the
+ * frame's load, a slow shell), it tries again rather than run on its own, where its answers
+ * would stay in this browser while the shell said "Saved" (FAILURE_MODEL §1 rule 4; Claude review
+ * finding 4). A page opened on its own has no shell and runs locally.
+ */
+async function framedShell(): Promise<ShellConnection | undefined> {
+  if (typeof window === "undefined" || window.parent === window) return undefined;
+  for (let attempt = 0; ; attempt += 1) {
+    const shell = await connectShell();
+    if (shell) return shell;
+    if (attempt === 1)
+      console.warn("Mostra: waiting for the shell; the page connects when it can.");
+    await new Promise((resolve) =>
+      setTimeout(resolve, Math.min(500 * 2 ** attempt, SHELL_RETRY_MAX_MS)),
+    );
+  }
+}
+
+/**
+ * Starts the runtime: live behind the gateway inside Mostra's shell, local otherwise (a static
+ * export, an MCP App until its transport arrives, a page opened on its own).
+ */
+export async function startRuntime(): Promise<Runtime> {
+  const target = deliveryTarget();
+  const tab = tabId();
+  const shell = target === "live" || target === "verify" ? await framedShell() : undefined;
+  // Read the tolerant way: a later shell may send values this page doesn't know (Claude review
+  // finding 5), which never cost it its view.
+  const view: ViewContext | undefined = shell?.host.mostra
+    ? readViewContext(shell.host.mostra)
+    : undefined;
+  const built = builtVersion();
+  if (shell && view && built !== undefined && built !== view.version.id) {
+    // This page is another version than the view the shell opened: another tab moved the frame
+    // session on (D98 item 5). Nothing it shows may be saved as this view, nor kept: the shell,
+    // told the page's version in `ui/initialize`, loads the frame again at its own version.
+    const scratch = new Map<string, string>();
+    const store = new Store({
+      mode: "local",
+      journal: new MemoryJournal(),
+      tab,
+      local: {
+        getItem: (key) => scratch.get(key) ?? null,
+        setItem: (key, value) => void scratch.set(key, value),
+        removeItem: (key) => void scratch.delete(key),
+      },
+    });
+    store.start();
+    return { store, target, mode: view.target, shell };
+  }
+  if (!shell || !view) {
+    const store = new Store({ mode: "local", journal: new MemoryJournal(), tab });
+    store.start();
+    return { store, target, mode: target === "live" ? "static" : target, shell: undefined };
+  }
+  const journal: Journal = (await IndexedDbJournal.open()) ?? new MemoryJournal();
+  const store = new Store({
+    mode: "live",
+    transport: new HttpTransport(view.viewId, {
+      ...(shell.session.csrf !== "" ? { csrf: shell.session.csrf } : {}),
+    }),
+    journal,
+    view,
+    scopes: shell.session.scopes,
+    ...(shell.session.viewer ? { viewer: shell.session.viewer } : {}),
+    tab,
+    goneTabs: tabPresence(tab),
+    exclusive,
+    channel: (name) =>
+      typeof BroadcastChannel === "undefined" ? undefined : new BroadcastChannel(name),
+  });
+  // A verify run reads which fields the page mounts (D138); a viewer's page never records them.
+  if (target === "verify") installVerifyProbe(store);
+  store.start();
+  wireLifecycle(store);
+  wireShell(store, shell);
+  return { store, target, mode: view.target, shell };
+}
+
+/** Saves on blur, and when the page is hidden or closed (IN-02). */
+function wireLifecycle(store: Store): void {
+  if (typeof document === "undefined") return;
+  document.addEventListener("focusout", () => void store.flush(), true);
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") void store.flush({ keepalive: true });
+  });
+  window.addEventListener("pagehide", () => void store.flush({ keepalive: true }));
+}
+
+/** Focuses the element a field is bound to, when the viewer picks it in the shell. */
+function focusField(id: string): void {
+  const escaped = typeof CSS !== "undefined" && CSS.escape ? CSS.escape(id) : id;
+  const element = document.querySelector<HTMLElement>(
+    `[data-mostra-field="${escaped}"], [name="${escaped}"], #${escaped}`,
+  );
+  element?.scrollIntoView({ block: "center" });
+  element?.focus();
+}
+
+/** Reports fields and save state to the shell, and answers its requests. */
+function wireShell(store: Store, shell: ShellConnection): void {
+  let last = "";
+  let scheduled = false;
+  const report = (): void => {
+    scheduled = false;
+    const fields = store.registrations().map((registration) => ({
+      id: registration.id,
+      scope: registration.scope,
+      ...(registration.label !== undefined ? { label: clip(registration.label) } : {}),
+      ...(registration.required !== undefined ? { required: registration.required } : {}),
+      ...(registration.sensitive !== undefined ? { sensitive: registration.sensitive } : {}),
+      ...(registration.error !== undefined ? { error: clip(registration.error) } : {}),
+      ...(store.conflict(`${registration.scope}:${registration.id}`) ? { conflict: true } : {}),
+    }));
+    const params: FieldsParams = {
+      fields: firstThatMatter(fields, (field) =>
+        Boolean(field.required || field.error !== undefined || field.conflict),
+      ),
+      save: store.pageSave(),
+      unsaved: store.unsaved(),
+    };
+    const text = JSON.stringify(params);
+    if (text === last) return;
+    last = text;
+    try {
+      shell.bridge.notify(mostraFields, params);
+    } catch (error) {
+      // Never silently: the shell's rail would keep its last state (Claude review finding 11).
+      console.error("Mostra: the page's fields couldn't be reported to the shell.", error);
+    }
+  };
+  store.subscribe(() => {
+    if (scheduled) return;
+    scheduled = true;
+    queueMicrotask(report);
+  });
+  report();
+  listenShell({
+    request: async (message, params) => {
+      if (message !== mostraFlush) return undefined;
+      const reason = (params as { reason: "submit" | "switch" }).reason;
+      if (reason === "submit") {
+        const prepared = await store.prepareSubmit();
+        const result: FlushResult = {
+          revision: String(prepared.revision),
+          unsaved: prepared.unsaved,
+          blockers: blockersForShell(prepared.blockers),
+        };
+        return result;
+      }
+      const flushed = await store.flush();
+      const result: FlushResult = {
+        revision: String(flushed.revision),
+        unsaved: flushed.unsaved,
+        blockers: blockersForShell(store.blockers()),
+      };
+      return result;
+    },
+    notification: (message, params) => {
+      if (message === mostraFieldFocus) focusField((params as { id: string }).id);
+      if (message === mostraVersionAvailable) {
+        // The page may show its own notice; the shell's trusted banner always appears (§5).
+        window.dispatchEvent(
+          new CustomEvent<VersionAvailableParams>("mostra:version-available", {
+            detail: params as VersionAvailableParams,
+          }),
+        );
+      }
+    },
+  });
+}

package/src/runtime/bridge-limits.ts

@@ -0,0 +1,30 @@
+/**
+ * What the page sends the shell, fitted to the bridge's limits (Claude review finding 11): a long
+ * label or validation message is shortened, and a page with more fields than one message lists
+ * sends those that matter first. A report the bridge refuses would leave the shell's rail and its
+ * blocker list stale, and a refused flush answer would stop every trusted Submit.
+ */
+import { BRIDGE_FIELDS_MAX, BRIDGE_TEXT_MAX, type SubmitBlocker } from "@mostra/protocol";
+
+/** Text shortened to what the bridge carries. */
+export function clip(text: string): string {
+  return text.length <= BRIDGE_TEXT_MAX ? text : `${text.slice(0, BRIDGE_TEXT_MAX - 1)}…`;
+}
+
+/** At most {@link BRIDGE_FIELDS_MAX} items, those that matter first, in their order otherwise. */
+export function firstThatMatter<T>(items: readonly T[], matters: (item: T) => boolean): T[] {
+  if (items.length <= BRIDGE_FIELDS_MAX) return [...items];
+  return [...items.filter(matters), ...items.filter((item) => !matters(item))].slice(
+    0,
+    BRIDGE_FIELDS_MAX,
+  );
+}
+
+/** Blockers as the bridge carries them: labels shortened, at most {@link BRIDGE_FIELDS_MAX}. */
+export function blockersForShell(blockers: readonly SubmitBlocker[]): SubmitBlocker[] {
+  return blockers
+    .slice(0, BRIDGE_FIELDS_MAX)
+    .map((blocker) =>
+      blocker.label === undefined ? blocker : { ...blocker, label: clip(blocker.label) },
+    );
+}

package/src/runtime/errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Errors the client runtime throws: each carries the stable diagnostic code an artifact can switch
+ * on (INTERFACES §13), and the diagnostic itself when the gateway sent one.
+ */
+
+/** A diagnostic as the gateway sends it; only the fields the runtime reads. */
+export interface DiagnosticLike {
+  /** The stable diagnostic code, such as `MOSTRA_FIELD_TOO_LARGE`. */
+  readonly code: string;
+  /** What is wrong. */
+  readonly message: string;
+  /** What to do about it. */
+  readonly hint?: string;
+  /** The code's documentation page. */
+  readonly docs?: string;
+}
+
+/** An error with a Mostra diagnostic code, such as `MOSTRA_SUBMIT_CHANNEL_DENIED`. */
+export class MostraError extends Error {
+  /** The stable diagnostic code. */
+  readonly code: string;
+  /** The HTTP status the gateway answered with, when the error came from it. */
+  readonly status: number | undefined;
+  /** The diagnostic, when the gateway sent one. */
+  readonly diagnostic: DiagnosticLike | undefined;
+  /** Extra data the refusal carried, such as the existing submission of `MOSTRA_SUBMIT_ALREADY`. */
+  readonly body: Readonly<Record<string, unknown>> | undefined;
+
+  constructor(
+    code: string,
+    message: string,
+    options: {
+      readonly status?: number;
+      readonly diagnostic?: DiagnosticLike;
+      readonly body?: Readonly<Record<string, unknown>>;
+    } = {},
+  ) {
+    super(message);
+    this.name = "MostraError";
+    this.code = code;
+    this.status = options.status;
+    this.diagnostic = options.diagnostic;
+    this.body = options.body;
+  }
+}
+
+/** `MOSTRA_TARGET_UNAVAILABLE`: what the delivery target can't do (a static export, D111). */
+export function targetUnavailable(what: string): MostraError {
+  return new MostraError(
+    "MOSTRA_TARGET_UNAVAILABLE",
+    `${what} needs the artifact's Mostra link; this copy of the page has no Mostra server.`,
+  );
+}

package/src/runtime/journal.ts

@@ -0,0 +1,219 @@
+/**
+ * The offline journal (D22, IN-02, IN-04): every edit the gateway hasn't confirmed, kept in the
+ * artifact origin's IndexedDB so a closed tab, a crash or a lost connection loses nothing. Two
+ * kinds of entry: a field's pending edit (not sent yet; its newest value wins), and a mutation that
+ * was sent or is about to be, kept with its mutation ID so a replay is idempotent. Every entry
+ * names its viewer and the tab that wrote it: a page replays only its own viewer's entries, and
+ * adopts another tab's only once that tab is gone, so two open tabs never overwrite each other's
+ * unsent edits. Where IndexedDB can't be used the journal lives in memory and says so.
+ */
+import type { FieldOp } from "@mostra/protocol";
+
+/** A field's edit, not sent yet. */
+export interface PendingEntry {
+  readonly kind: "pending";
+  readonly viewerId: string;
+  /** The tab that made the edit. */
+  readonly tab: string;
+  readonly viewId: string;
+  readonly scope: "viewer" | "artifact";
+  readonly op: FieldOp;
+  /**
+   * The revision the edit was based on: the field was unchanged since it (D22). `null` while an
+   * earlier mutation of the same field is in flight; its answer sets it.
+   */
+  readonly base: number | null;
+  /** When the edit was made (ms since the epoch). */
+  readonly at: number;
+}
+
+/** A mutation, sent or about to be, replayed with its own ID. */
+export interface MutationEntry {
+  readonly kind: "mutation";
+  readonly viewerId: string;
+  readonly tab: string;
+  readonly viewId: string;
+  readonly scope: "viewer" | "artifact";
+  readonly mutationId: string;
+  readonly baseRevision: number;
+  readonly ops: readonly FieldOp[];
+  /** Its place in the journal: mutations replay in this order. */
+  readonly seq: number;
+}
+
+/** One entry. */
+export type JournalEntry = PendingEntry | MutationEntry;
+
+/** A viewer's entries, mutations in journal order. */
+export interface JournalContents {
+  readonly pending: PendingEntry[];
+  readonly mutations: MutationEntry[];
+}
+
+/** The journal's storage. */
+export interface Journal {
+  /** Whether entries survive the page (IndexedDB), or live only in memory. */
+  readonly durable: boolean;
+  /** Every entry of a viewer, mutations in order. */
+  load(viewerId: string): Promise<JournalContents>;
+  /** Records a pending edit, replacing the same tab's earlier one for the field. */
+  putPending(entry: PendingEntry): Promise<void>;
+  /** Turns pending edits into a mutation in one transaction. */
+  promote(mutation: MutationEntry, consumed: readonly PendingEntry[]): Promise<void>;
+  /** Forgets a mutation the gateway answered. */
+  remove(mutationId: string): Promise<void>;
+  /** Forgets a field's pending edit (taken back, or refused for good). */
+  dropPending(entry: PendingEntry): Promise<void>;
+  /** Moves entries of a tab that is gone to `tab`, in one transaction. */
+  adopt(entries: readonly JournalEntry[], tab: string): Promise<void>;
+}
+
+/** The key of a pending edit: one per viewer, tab, scope and field. */
+export const pendingKey = (
+  entry: Pick<PendingEntry, "viewerId" | "tab" | "scope" | "op">,
+): string => `p\u0000${entry.viewerId}\u0000${entry.tab}\u0000${entry.scope}\u0000${entry.op.id}`;
+
+const mutationKey = (mutationId: string): string => `m\u0000${mutationId}`;
+
+const keyOf = (entry: JournalEntry): string =>
+  entry.kind === "pending" ? pendingKey(entry) : mutationKey(entry.mutationId);
+
+function split(entries: readonly JournalEntry[], viewerId: string): JournalContents {
+  const mine = entries.filter((entry) => entry.viewerId === viewerId);
+  return {
+    pending: mine.filter((entry): entry is PendingEntry => entry.kind === "pending"),
+    mutations: mine
+      .filter((entry): entry is MutationEntry => entry.kind === "mutation")
+      .sort((a, b) => a.seq - b.seq),
+  };
+}
+
+/** The journal in memory: for targets without IndexedDB, and for tests. */
+export class MemoryJournal implements Journal {
+  readonly durable: boolean = false;
+  readonly #entries = new Map<string, JournalEntry>();
+
+  async load(viewerId: string): Promise<JournalContents> {
+    return split([...this.#entries.values()], viewerId);
+  }
+
+  async putPending(entry: PendingEntry): Promise<void> {
+    this.#entries.set(pendingKey(entry), entry);
+  }
+
+  async promote(mutation: MutationEntry, consumed: readonly PendingEntry[]): Promise<void> {
+    for (const entry of consumed) this.#entries.delete(pendingKey(entry));
+    this.#entries.set(mutationKey(mutation.mutationId), mutation);
+  }
+
+  async remove(mutationId: string): Promise<void> {
+    this.#entries.delete(mutationKey(mutationId));
+  }
+
+  async dropPending(entry: PendingEntry): Promise<void> {
+    this.#entries.delete(pendingKey(entry));
+  }
+
+  async adopt(entries: readonly JournalEntry[], tab: string): Promise<void> {
+    for (const entry of entries) {
+      this.#entries.delete(keyOf(entry));
+      const moved = { ...entry, tab };
+      const key = keyOf(moved);
+      // A tab's own newer edit of the same field wins over an adopted one.
+      if (!this.#entries.has(key)) this.#entries.set(key, moved);
+    }
+  }
+}
+
+const DB_NAME = "mostra";
+const STORE = "journal";
+
+function request<T>(req: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function done(transaction: IDBTransaction): Promise<void> {
+  return new Promise((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    transaction.onerror = () => reject(transaction.error);
+    transaction.onabort = () => reject(transaction.error ?? new Error("The transaction aborted."));
+  });
+}
+
+/**
+ * The journal in the artifact origin's IndexedDB: one database per origin, so per artifact (D38).
+ * Each write starts its transaction at once, so an edit made just before the page closes is in it.
+ */
+export class IndexedDbJournal implements Journal {
+  readonly durable: boolean = true;
+  readonly #db: IDBDatabase;
+
+  private constructor(db: IDBDatabase) {
+    this.#db = db;
+  }
+
+  /** Opens the journal; `undefined` where IndexedDB can't be used (a private mode, a sandbox). */
+  static async open(): Promise<IndexedDbJournal | undefined> {
+    if (typeof indexedDB === "undefined") return undefined;
+    try {
+      const open = indexedDB.open(DB_NAME, 1);
+      open.onupgradeneeded = () => {
+        if (!open.result.objectStoreNames.contains(STORE)) open.result.createObjectStore(STORE);
+      };
+      return new IndexedDbJournal(await request(open));
+    } catch {
+      return undefined;
+    }
+  }
+
+  #write(change: (store: IDBObjectStore) => void): Promise<void> {
+    const transaction = this.#db.transaction(STORE, "readwrite");
+    change(transaction.objectStore(STORE));
+    return done(transaction);
+  }
+
+  async load(viewerId: string): Promise<JournalContents> {
+    const all = (await request(
+      this.#db.transaction(STORE, "readonly").objectStore(STORE).getAll(),
+    )) as JournalEntry[];
+    return split(all, viewerId);
+  }
+
+  putPending(entry: PendingEntry): Promise<void> {
+    return this.#write((store) => store.put(entry, pendingKey(entry)));
+  }
+
+  promote(mutation: MutationEntry, consumed: readonly PendingEntry[]): Promise<void> {
+    return this.#write((store) => {
+      for (const entry of consumed) store.delete(pendingKey(entry));
+      store.put(mutation, mutationKey(mutation.mutationId));
+    });
+  }
+
+  remove(mutationId: string): Promise<void> {
+    return this.#write((store) => store.delete(mutationKey(mutationId)));
+  }
+
+  dropPending(entry: PendingEntry): Promise<void> {
+    return this.#write((store) => store.delete(pendingKey(entry)));
+  }
+
+  async adopt(entries: readonly JournalEntry[], tab: string): Promise<void> {
+    const transaction = this.#db.transaction(STORE, "readwrite");
+    const store = transaction.objectStore(STORE);
+    for (const entry of entries) {
+      store.delete(keyOf(entry));
+      const moved = { ...entry, tab };
+      // `add` fails on an existing key: a tab's own newer edit wins over an adopted one.
+      const added = store.add(moved, keyOf(moved));
+      added.onerror = (event) => {
+        event.preventDefault();
+        event.stopPropagation();
+      };
+    }
+    await done(transaction);
+  }
+}