@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.0

package/src/offline/sync/sync-root.ts

@@ -0,0 +1,336 @@
+import { EndpointCreator } from "../../core/endpoint/EndpointCreator";
+import { ApiRequestDataTypeInterface } from "../../core/interfaces/ApiRequestDataTypeInterface";
+import { Modules } from "../../core/registry/ModuleRegistry";
+import { JsonApiGet } from "../../unified/JsonApiRequest";
+import { getOfflineConfig, getOfflineStore, isOfflineConfigured, writeOfflineLastSync } from "../config";
+import { canReachApi, setOfflineState } from "../state";
+import type { DeviceStore, SkippedRecord, StoredRecord } from "../store/DeviceStore";
+import { cacheArtworkImage, imageUrlOf, removeArtworkImage } from "./artwork-cache";
+import { knownRootIds, refreshLockedRoots, rememberSyncRoots } from "./known-roots";
+import { ROOT_SYNC_ENDPOINT, RootSync } from "./models/RootSync";
+import { currentLocale } from "./session-refresh";
+import { recordKeyOf as keyOf, waitingRecordKeys } from "./waiting";
+
+class SyncInterruptedError extends Error {}
+
+function assertStillOnline(): void {
+  if (!canReachApi()) throw new SyncInterruptedError("The connection dropped during the sync");
+}
+
+/**
+ * A record the GM cannot read (403) or that is gone (404) is skipped by this sync (it never
+ * blocks the sync state). It is not stored; it is remembered with its `updatedAt` from the sync
+ * answer, and a later sync asks for it again only once that `updatedAt` is newer.
+ */
+const isSkippable = (status: number) => status === 403 || status === 404;
+
+async function fetchResources(
+  module: ApiRequestDataTypeInterface,
+  endpoint: string,
+  skipped: string[],
+  included: any[],
+): Promise<any[]> {
+  const response = await JsonApiGet({ classKey: module, endpoint, language: currentLocale() });
+  assertStillOnline();
+  if (!response.ok) {
+    if (isSkippable(response.response)) {
+      skipped.push(endpoint);
+      return [];
+    }
+    throw new Error(`[offline] GET ${endpoint} answered ${response.response}`);
+  }
+  included.push(...(response.raw?.included ?? []));
+  const data = response.raw?.data;
+  if (!data) return [];
+  return Array.isArray(data) ? data : [data];
+}
+
+async function imagesOfRoot(store: DeviceStore, rootId: string): Promise<{ type: string; id: string; url: string }[]> {
+  const images: { type: string; id: string; url: string }[] = [];
+  for (const typeConfig of getOfflineConfig().types) {
+    for (const record of await store.listRecords({ type: typeConfig.module.name, rootId })) {
+      const url = imageUrlOf(record.resource);
+      if (url) images.push({ type: record.type, id: record.id, url });
+    }
+  }
+  return images;
+}
+
+/**
+ * Removes a root record from the device (records, links, sync state, images) unless it has waiting
+ * changes. A shared record another root record still uses stays, with its image.
+ */
+async function removeRootIfIdle(store: DeviceStore, rootId: string): Promise<void> {
+  if ((await store.queue()).some((entry) => entry.rootId === rootId)) return;
+  const images = await imagesOfRoot(store, rootId);
+  await store.removeRoot(rootId);
+  for (const image of images) {
+    if (!(await store.getRecord(image.type, image.id))) await removeArtworkImage(image.url);
+  }
+}
+
+/**
+ * Brings one root record's device copy up to date with the sync answer (C2): records changed since
+ * the stored server time are fetched (C3), records gone from the root record are deleted, the links
+ * are replaced, and artwork images are downloaded. The sync state is stored only once every
+ * fetch succeeded (or answered 403/404). A record with a waiting change is never overwritten.
+ */
+export async function syncRoot(rootId: string): Promise<void> {
+  const config = getOfflineConfig();
+  const store = await getOfflineStore();
+  const previous = await store.getSyncState(rootId);
+
+  const syncEndpoint = new EndpointCreator({
+    endpoint: config.rootModule,
+    id: rootId,
+    childEndpoint: ROOT_SYNC_ENDPOINT,
+  }).generate();
+  const syncResponse = await JsonApiGet({
+    classKey: Modules.RootSync,
+    endpoint: syncEndpoint,
+    language: currentLocale(),
+  });
+  assertStillOnline();
+  if (!syncResponse.ok) {
+    // Deleted, or no longer the GM's: removed from the device unless changes still wait.
+    if (isSkippable(syncResponse.response)) {
+      await removeRootIfIdle(store, rootId);
+      return;
+    }
+    throw new Error(`[offline] GET ${syncEndpoint} answered ${syncResponse.response}`);
+  }
+
+  const sync = syncResponse.data as RootSync;
+  if (sync.locked) {
+    // Locked online, locked offline: nothing is downloaded, waiting changes are kept.
+    await store.setSyncState(rootId, {
+      serverTime: previous.serverTime,
+      locked: true,
+      lockedFrom: sync.lockedFrom ?? null,
+    });
+    await refreshLockedRoots();
+    return;
+  }
+
+  const typeNames = new Set(config.types.map((typeConfig) => typeConfig.module.name));
+  const entries = sync.entries.filter((entry) => typeNames.has(entry.type));
+  const entryUpdatedAt = new Map(entries.map((entry) => [keyOf(entry.type, entry.id), entry.updatedAt]));
+  const since = previous.serverTime;
+  /** Inside the `updatedSince` window: a list read with `updatedSince` brings it. */
+  const inWindow = (entry: { updatedAt: Date }) => !since || entry.updatedAt.getTime() > since.getTime();
+
+  // What the device holds for this root record now. A record is fetched when it changed since the
+  // last sync, and also when the device does not hold it or holds it as stale (updatedAt cleared
+  // while it had a waiting change, see below) — unless an earlier sync skipped it (403/404, or
+  // absent from the answer) and it has not changed on the server since.
+  const stored = new Map<string, StoredRecord>();
+  for (const typeConfig of config.types) {
+    for (const record of await store.listRecords({ type: typeConfig.module.name, rootId })) {
+      stored.set(keyOf(record.type, record.id), record);
+    }
+  }
+  const previouslySkipped = new Map(
+    (await store.skippedRecords(rootId)).map((record) => [keyOf(record.type, record.id), record.updatedAt]),
+  );
+  const isStale = (entry: { type: string; id: string; updatedAt: Date }) => {
+    const key = keyOf(entry.type, entry.id);
+    const record = stored.get(key);
+    if (record && record.updatedAt !== null) return false;
+    const skippedAt = previouslySkipped.get(key);
+    return !skippedAt || entry.updatedAt.getTime() > skippedAt.getTime();
+  };
+  const changed = entries.filter((entry) => inWindow(entry) || isStale(entry));
+
+  const skipped: string[] = [];
+  const fetched: any[] = [];
+  // Records the answers include whose type the device does not sync itself (the root record's
+  // owner): kept for display only, so a local answer can include them as the server does.
+  const included: any[] = [];
+  for (const typeConfig of config.types) {
+    const changedOfType = changed.filter((entry) => entry.type === typeConfig.module.name);
+    if (changedOfType.length === 0) continue;
+
+    if (typeConfig.fetch === "root-list") {
+      // One list read per type. With `updatedSince` when every changed record is inside the
+      // window; without it when a record older than the window is missing or stale on the
+      // device, so the whole list comes in the same single request (never one read per record).
+      const endpoint = new EndpointCreator({
+        endpoint: config.rootModule,
+        id: rootId,
+        childEndpoint: typeConfig.module,
+      }).addAdditionalParam("fetchAll", "true");
+      if (since && changedOfType.every(inWindow)) endpoint.addAdditionalParam("updatedSince", since.toISOString());
+      fetched.push(...(await fetchResources(typeConfig.module, endpoint.generate(), skipped, included)));
+    } else if (typeConfig.fetch === "linked-list") {
+      // Read only as a list per target: the targets are the other ends of the changed records'
+      // sync links of `linkKind`; each target's list is read once, and only the type's entries kept.
+      if (!typeConfig.linkedList) throw new Error(`[offline] ${typeConfig.module.name}: linked-list needs linkedList`);
+      const { linkKind, endpoint } = typeConfig.linkedList;
+      const changedIds = new Set(changedOfType.map((entry) => entry.id));
+      const targets = new Map<string, { type: string; id: string }>();
+      for (const link of sync.links) {
+        if (link.kind !== linkKind || link.fromType !== typeConfig.module.name || !changedIds.has(link.fromId))
+          continue;
+        targets.set(keyOf(link.toType, link.toId), { type: link.toType, id: link.toId });
+      }
+      for (const target of targets.values()) {
+        const resources = await fetchResources(typeConfig.module, endpoint(rootId, target), skipped, included);
+        fetched.push(
+          ...resources.filter((resource) => resource?.type === typeConfig.module.name && changedIds.has(resource.id)),
+        );
+      }
+    } else {
+      for (const entry of changedOfType) {
+        const endpoint = new EndpointCreator({ endpoint: typeConfig.module, id: entry.id }).generate();
+        fetched.push(...(await fetchResources(typeConfig.module, endpoint, skipped, included)));
+      }
+    }
+  }
+
+  const fetchedKeys = new Set(fetched.map((resource) => keyOf(resource?.type, resource?.id)));
+  const previousImageUrls = new Map<string, string>();
+  const removedImageUrls: string[] = [];
+
+  await store.transaction(async (tx) => {
+    // A record with a waiting change (pending, sending, in conflict or failed) is never
+    // overwritten nor deleted here. Read inside this transaction, so an edit queued while the
+    // records were being fetched is seen.
+    const waiting = waitingRecordKeys(await tx.queue(), typeNames);
+
+    for (const typeConfig of config.types) {
+      for (const record of await tx.listRecords({ type: typeConfig.module.name, rootId })) {
+        const key = keyOf(record.type, record.id);
+        if (waiting.has(key)) {
+          // Marked stale: once the change stops waiting (sent, resolved, discarded), the next
+          // sync fetches the record again, whatever its updatedAt.
+          if (record.updatedAt !== null) await tx.putRecord({ ...record, updatedAt: null });
+          continue;
+        }
+        if (entryUpdatedAt.has(key)) continue;
+        // Leaves this root record; deleted only when no other root record keeps it (a shared record).
+        await tx.removeRecordFromRoot(record.type, record.id, rootId);
+        const url = imageUrlOf(record.resource);
+        if (url && !(await tx.getRecord(record.type, record.id))) removedImageUrls.push(url);
+      }
+    }
+
+    for (const resource of fetched) {
+      const key = keyOf(resource?.type, resource?.id);
+      if (!entryUpdatedAt.has(key)) continue;
+      if (waiting.has(key)) continue;
+      const existing = await tx.getRecord(resource.type, resource.id);
+      const previousUrl = imageUrlOf(existing?.resource);
+      if (previousUrl) previousImageUrls.set(key, previousUrl);
+      await tx.putRecord({
+        type: resource.type,
+        id: resource.id,
+        rootId,
+        resource,
+        updatedAt: entryUpdatedAt.get(key) ?? null,
+        base: null,
+        localOnly: false,
+      });
+    }
+
+    for (const resource of included) {
+      if (!resource?.type || !resource?.id || typeNames.has(resource.type)) continue;
+      await tx.putRecord({
+        type: resource.type,
+        id: resource.id,
+        rootId,
+        resource,
+        updatedAt: null,
+        base: null,
+        localOnly: false,
+      });
+    }
+
+    // Remembered skips: a changed record no answer brought (403/404, or absent from the list), and
+    // an earlier skip still in the root record that was not asked for again.
+    const skippedRecords: SkippedRecord[] = [];
+    const changedKeys = new Set(changed.map((entry) => keyOf(entry.type, entry.id)));
+    for (const entry of entries) {
+      const key = keyOf(entry.type, entry.id);
+      if (waiting.has(key) || fetchedKeys.has(key)) continue;
+      if (changedKeys.has(key)) skippedRecords.push({ type: entry.type, id: entry.id, updatedAt: entry.updatedAt });
+      else {
+        const skippedAt = previouslySkipped.get(key);
+        if (skippedAt) skippedRecords.push({ type: entry.type, id: entry.id, updatedAt: skippedAt });
+      }
+    }
+    await tx.setSkippedRecords(rootId, skippedRecords);
+
+    await tx.replaceRootLinks(rootId, sync.links);
+    await tx.setSyncState(rootId, {
+      serverTime: sync.serverTime,
+      locked: false,
+      lockedFrom: sync.lockedFrom ?? null,
+    });
+  });
+
+  if (skipped.length > 0) {
+    console.warn(`[offline] root record ${rootId}: skipped records the GM cannot read:`, skipped.join(", "));
+  }
+
+  for (const url of removedImageUrls) await removeArtworkImage(url);
+  for (const typeConfig of config.types) {
+    for (const record of await store.listRecords({ type: typeConfig.module.name, rootId })) {
+      const url = imageUrlOf(record.resource);
+      if (url) await cacheArtworkImage(url, previousImageUrls.get(keyOf(record.type, record.id)));
+    }
+  }
+
+  await refreshLockedRoots();
+}
+
+/**
+ * Syncs every root record `listSyncRoots()` returns, then removes from the device the root records
+ * that are no longer roots (unless they still have waiting changes). Does nothing offline.
+ */
+export async function syncAll(): Promise<void> {
+  if (!isOfflineConfigured()) return;
+  const config = getOfflineConfig();
+  if (!config.getUserId() || !canReachApi()) return;
+
+  let roots: string[];
+  try {
+    roots = await config.listSyncRoots();
+  } catch (error) {
+    console.warn("[offline] could not list the root records to sync", error);
+    return;
+  }
+  if (!canReachApi()) return;
+  rememberSyncRoots(roots);
+
+  const total = roots.length;
+  setOfflineState({ syncProgress: { done: 0, total } });
+  try {
+    let done = 0;
+    for (const rootId of roots) {
+      try {
+        await syncRoot(rootId);
+      } catch (error) {
+        console.warn(`[offline] sync of root record ${rootId} failed`, error);
+        if (!canReachApi()) return;
+      } finally {
+        done += 1;
+        setOfflineState({ syncProgress: { done, total } });
+      }
+    }
+
+    // Every root record was tried: this counts as the device's last sync.
+    const finishedAt = Date.now();
+    const userId = config.getUserId();
+    if (userId) writeOfflineLastSync(userId, finishedAt);
+    setOfflineState({ lastSyncedAt: finishedAt, rootCount: total });
+
+    const store = await getOfflineStore();
+    const rootSet = new Set(roots);
+    for (const rootId of await knownRootIds(store)) {
+      if (!rootSet.has(rootId)) await removeRootIfIdle(store, rootId);
+    }
+    await refreshLockedRoots();
+  } finally {
+    setOfflineState({ syncProgress: null });
+  }
+}

package/src/offline/sync/waiting.ts

@@ -0,0 +1,40 @@
+import type { QueueEntry } from "../store/DeviceStore";
+
+export const recordKeyOf = (type: string, id: string) => `${type}:${id}`;
+
+/**
+ * The records a queue entry targets: its `recordType`/`recordId`, the `data.type`/`data.id` of
+ * its body (a record created on this device), and the `<type>/<id>` of its path (the last
+ * segment naming a synced type, when an id follows it: `npcs/n1`, `npcs/n1/merge`; a collection
+ * path such as `roots/C/npcs` targets no record).
+ */
+export function recordKeysOfEntry(entry: QueueEntry, typeNames: Set<string>): string[] {
+  const keys: string[] = [];
+  if (entry.recordType && entry.recordId) keys.push(recordKeyOf(entry.recordType, entry.recordId));
+
+  const data = entry.body?.data;
+  if (data && !Array.isArray(data) && typeof data.type === "string" && typeof data.id === "string") {
+    keys.push(recordKeyOf(data.type, data.id));
+  }
+
+  const segments = String(entry.path ?? "")
+    .split("?")[0]
+    .split("/")
+    .filter(Boolean);
+  for (let index = segments.length - 1; index >= 0; index--) {
+    if (!typeNames.has(segments[index])) continue;
+    if (index + 1 < segments.length) keys.push(recordKeyOf(segments[index], segments[index + 1]));
+    break;
+  }
+  return keys;
+}
+
+/**
+ * Every record with a waiting change: targeted by a queue entry that is pending, sending, in
+ * conflict or failed. Such a record is never overwritten or deleted by a sync or a write-through.
+ */
+export function waitingRecordKeys(queue: QueueEntry[], typeNames: Set<string>): Set<string> {
+  const keys = new Set<string>();
+  for (const entry of queue) for (const key of recordKeysOfEntry(entry, typeNames)) keys.add(key);
+  return keys;
+}

package/src/offline/types.ts

@@ -0,0 +1,115 @@
+import type { ApiRequestDataTypeInterface } from "../core/interfaces/ApiRequestDataTypeInterface";
+import type { DeviceStore } from "./store/DeviceStore";
+
+/** Header of a request the server runs as an offline replay. Never answered locally. */
+export const OFFLINE_REPLAY_HEADER = "x-offline-replay";
+
+export type OfflineMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/** A Module (matched by its endpoint), a ":param" capture, or a literal segment ("playing", "merge"). */
+export type PatternSegment = ApiRequestDataTypeInterface | string;
+
+/** `url` (beyond the contract, optional): the absolute URL the request was made to, for the `links` of a list. */
+export type OfflineRequest = { method: OfflineMethod; path: string; query: URLSearchParams; body?: any; url?: string };
+
+/** `body` is a JSON:API document, `undefined` for a 204. */
+export type OfflineAnswer = { status: number; body: any };
+
+export type LocalAnswerContext = { request: OfflineRequest; params: Record<string, string>; store: DeviceStore };
+
+export type LocalAnswer = (ctx: LocalAnswerContext) => Promise<OfflineAnswer>;
+
+export type OfflineRoute = { method: OfflineMethod; pattern: PatternSegment[]; answer: LocalAnswer; queue: boolean };
+
+/**
+ * A type the API reads only as a list per target record: each changed record's target is the
+ * other end of its sync link of `linkKind` (from the record to the target), and `endpoint`
+ * builds that target's list path with `EndpointCreator`.
+ */
+export type OfflineLinkedListFetch = {
+  linkKind: string;
+  endpoint: (rootId: string, target: { type: string; id: string }) => string;
+};
+
+export type OfflineTypeConfig = {
+  module: ApiRequestDataTypeInterface;
+  /**
+   * How the sync fetches the type's changed records: the root record's list (`root-list`), one
+   * GET per record (`by-id`), or (`linked-list`) the list of each record's target, found through
+   * the sync answer's links of `linkedList.linkKind` (e.g. player notes, read per target only).
+   */
+  fetch: "root-list" | "by-id" | "linked-list";
+  /** Required with `fetch: "linked-list"`. */
+  linkedList?: OfflineLinkedListFetch;
+  readOnly: boolean;
+  serverOwnedFields: string[];
+  /**
+   * Relationship name → Neo4j relationship type (`faction` → `MEMBER_OF`). A link the device
+   * writes from a request's relationships carries the mapped type, the kind synced links carry;
+   * an unmapped name is stored as the name itself.
+   */
+  relationshipKinds?: Record<string, string>;
+  /** The string attributes the server's fulltext index covers (default: every string attribute). */
+  searchFields?: string[];
+  /** The server's order with no `orderBy` (default `updatedAt DESC`). */
+  defaultOrderBy?: string;
+};
+
+export type OfflineConfig = {
+  getUserId: () => string | undefined;
+  /**
+   * Offline mode is off on each device until the user turns it on (`turnOnOffline`), stored per
+   * user per device. Default (undefined/false): always on, every device keeps the copy.
+   */
+  requireOptIn?: boolean;
+  /** The module whose records own every other record (in Wyrdli, Modules.Campaign). */
+  rootModule: ApiRequestDataTypeInterface;
+  types: OfflineTypeConfig[];
+  routes: OfflineRoute[];
+  /** Ids of the root records to keep on the device. */
+  listSyncRoots: () => Promise<string[]>;
+  shellPath: (locale: string) => string;
+  syncIntervalMs: number;
+  /**
+   * Where the device worker loads SQLite from at run time (default `/offline-sqlite/index.mjs`).
+   * SQLite is never bundled: its own helper worker uses a computed URL that app bundlers refuse.
+   * The app serves the files of `dist/offline/sqlite/` at this URL's folder.
+   */
+  sqliteModuleUrl?: string;
+  /**
+   * Where the device-copy worker is started from (default `/offline-sqlite/device-worker.mjs`).
+   * It is a standalone file in `dist/offline/sqlite/`, never bundled by the app.
+   */
+  deviceWorkerUrl?: string;
+};
+
+export const DEFAULT_SQLITE_MODULE_URL = "/offline-sqlite/index.mjs";
+export const DEVICE_WORKER_FILE = "device-worker.mjs";
+export const DEFAULT_DEVICE_WORKER_URL = `/offline-sqlite/${DEVICE_WORKER_FILE}`;
+
+/**
+ * The files of `dist/offline/sqlite/` the app serves: the device worker and the SQLite files
+ * copied from @sqlite.org/sqlite-wasm.
+ */
+export const OFFLINE_SQLITE_FILES = [
+  DEVICE_WORKER_FILE,
+  "index.mjs",
+  "sqlite3.wasm",
+  "sqlite3-opfs-async-proxy.js",
+] as const;
+
+/** Thrown by a local answer for something that only the server can do. Answered as a 503 "needs-connection". */
+export class NeedsConnectionError extends Error {
+  readonly status = 503;
+  readonly code = "needs-connection";
+
+  constructor(message: string = "Needs a connection") {
+    super(message);
+    this.name = "NeedsConnectionError";
+  }
+}
+
+/** Segments joined with "/", modules by their endpoint. */
+export function patternToString(pattern: PatternSegment[]): string {
+  return pattern.map((segment) => (typeof segment === "string" ? segment : segment.name)).join("/");
+}

package/src/offline/write-through.ts

@@ -0,0 +1,189 @@
+import type { ApiData } from "../core/interfaces/ApiData";
+import { getOfflineConfig, getOfflineStore, OfflineUnavailableError } from "./config";
+import { rootIdForResource, linkKindFor, linkKindsOf, linksOfKind } from "./generic-answers";
+import { splitApiUrl } from "./local-transport";
+import { matchPattern } from "./router";
+import type { DeviceStore, StoredLink } from "./store/DeviceStore";
+import type { OfflineTypeConfig } from "./types";
+import { cacheArtworkImage, imageUrlOf } from "./sync/artwork-cache";
+import { knownRootIds } from "./sync/known-roots";
+import { recordKeyOf, waitingRecordKeys } from "./sync/waiting";
+
+export type WriteThroughRequest = { method: string; url: string };
+
+function updatedAtOf(resource: any): Date | null {
+  const value = resource?.attributes?.updatedAt;
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+type Identifier = { type: string; id: string };
+
+function identifiersOf(relationship: any): Identifier[] {
+  const data = relationship?.data;
+  if (!data) return [];
+  return (Array.isArray(data) ? data : [data]).filter((item: any) => item && item.type && item.id);
+}
+
+/**
+ * Brings the stored links of the written record in line with the relationships the answer
+ * carries (only those whose `data` it holds), as the local answers do: a link of the
+ * relationship (its name or mapped Neo4j type; any kind when the type is not mapped, for an
+ * identifier the record held before) to an identifier no longer there is removed, and a new
+ * identifier gets a link of `linkKindFor` the relationship.
+ */
+async function updateLinks(
+  store: DeviceStore,
+  typeConfig: OfflineTypeConfig | undefined,
+  record: Identifier,
+  before: any,
+  after: any,
+): Promise<void> {
+  const otherEnd = (link: StoredLink) => (link.fromId === record.id ? link.toId : link.fromId);
+  const allLinks = async (): Promise<StoredLink[]> => [
+    ...(await store.linksFrom(record.id)),
+    ...(await store.linksTo(record.id)),
+  ];
+
+  for (const [name, relationship] of Object.entries<any>(after ?? {})) {
+    if (!relationship || !("data" in relationship)) continue;
+    const next = new Map(identifiersOf(relationship).map((identifier) => [identifier.id, identifier]));
+    const previous = new Set(identifiersOf(before?.[name]).map((identifier) => identifier.id));
+    const kinds = linkKindsOf(typeConfig, name) ?? [name];
+    const ofRelationship = await linksOfKind(store, record.id, kinds, "both");
+    const mapped = linkKindsOf(typeConfig, name) !== undefined;
+
+    const stale = [
+      ...ofRelationship.filter((link) => !next.has(otherEnd(link))),
+      // Unmapped: the link to an identifier the record held before may carry any kind.
+      ...(mapped ? [] : (await allLinks()).filter((link) => previous.has(otherEnd(link)) && !next.has(otherEnd(link)))),
+    ];
+    for (const link of stale) await store.deleteLink({ fromId: link.fromId, toId: link.toId, kind: link.kind });
+
+    const linked = new Set(
+      (mapped ? await linksOfKind(store, record.id, kinds, "both") : await allLinks()).map(otherEnd),
+    );
+    for (const [id, identifier] of next) {
+      if (linked.has(id)) continue;
+      await store.putLink({
+        fromType: record.type,
+        fromId: record.id,
+        toType: identifier.type,
+        toId: id,
+        kind: linkKindFor(typeConfig, name),
+        props: {},
+      });
+    }
+  }
+}
+
+type ImageChange = { url: string; previousUrl?: string };
+
+async function storeResource(
+  store: DeviceStore,
+  resource: any,
+  pathRootId: string | undefined,
+  waiting: Set<string>,
+  kept: Set<string>,
+  primary: boolean,
+  images: ImageChange[],
+): Promise<void> {
+  const config = getOfflineConfig();
+  if (!resource?.type || !resource?.id) return;
+  if (!config.types.some((typeConfig) => typeConfig.module.name === resource.type)) return;
+  // A record with unsent local changes keeps them: the next sync, once they are sent, brings
+  // the server's version.
+  if (waiting.has(recordKeyOf(resource.type, resource.id))) return;
+
+  const existing = await store.getRecord(resource.type, resource.id);
+  if (existing && existing.base !== null) return;
+  const rootId = existing?.rootId ?? (await rootIdForResource(store, config, resource)) ?? pathRootId;
+  // A record that belongs to no root record on this device waits for the next sync.
+  if (!rootId) return;
+  // Only the root records the device keeps are written through (never a player's root record).
+  if (!kept.has(rootId)) return;
+
+  // An answer can carry a sparse resource (fields limited): it is merged onto what is stored.
+  const before = existing?.resource ?? {};
+  const merged = {
+    ...before,
+    ...resource,
+    attributes: { ...(before.attributes ?? {}), ...(resource.attributes ?? {}) },
+    relationships: { ...(before.relationships ?? {}), ...(resource.relationships ?? {}) },
+  };
+
+  await store.putRecord({
+    type: resource.type,
+    id: resource.id,
+    rootId,
+    resource: merged,
+    updatedAt: updatedAtOf(resource) ?? existing?.updatedAt ?? null,
+    base: null,
+    localOnly: false,
+  });
+  if (primary) {
+    const typeConfig = config.types.find((candidate) => candidate.module.name === resource.type);
+    await updateLinks(store, typeConfig, resource, before.relationships, resource.relationships);
+  }
+
+  const url = imageUrlOf(merged);
+  const previousUrl = imageUrlOf(existing?.resource);
+  if (url && url !== previousUrl) images.push({ url, previousUrl });
+}
+
+/**
+ * After a successful online write, copies the answer into the device copy so it is never behind
+ * the GM's own work: the resource and its `included` for POST/PUT/PATCH, the record removed for a
+ * DELETE. It never fails the request: a problem is logged and the next sync repairs the copy.
+ */
+export async function writeThrough(request: WriteThroughRequest, response: ApiData): Promise<void> {
+  const method = request.method.toUpperCase();
+  if (method === "GET" || !response.ok) return;
+
+  try {
+    const config = getOfflineConfig();
+    if (!config.getUserId()) return;
+    const { path } = splitApiUrl(request.url);
+    const store = await getOfflineStore();
+
+    if (method === "DELETE") {
+      for (const typeConfig of config.types) {
+        const params = matchPattern([typeConfig.module, ":id"], path);
+        if (params) {
+          await store.deleteRecord(typeConfig.module.name, params.id);
+          return;
+        }
+      }
+      return;
+    }
+
+    const rootParams = matchPattern([config.rootModule, ":rootId"], path.split("/").slice(0, 2).join("/"));
+    const pathRootId = rootParams?.rootId;
+
+    const document = response.data;
+    const primary = Array.isArray(document?.data) ? document.data : document?.data ? [document.data] : [];
+    const waiting = waitingRecordKeys(
+      await store.queue(),
+      new Set(config.types.map((typeConfig) => typeConfig.module.name)),
+    );
+    // The root records this device keeps for the signed-in user (stored roots, waiting changes, last
+    // sync roots): a write in any other root record (a player's) stores nothing.
+    const kept = new Set(await knownRootIds(store));
+    const images: ImageChange[] = [];
+    await store.transaction(async (transactionStore) => {
+      for (const resource of primary) {
+        await storeResource(transactionStore, resource, pathRootId, waiting, kept, true, images);
+      }
+      for (const resource of document?.included ?? []) {
+        await storeResource(transactionStore, resource, pathRootId, waiting, kept, false, images);
+      }
+    });
+    // A new image URL of an artwork: downloaded, the old cached image removed (as the sync does).
+    for (const image of images) await cacheArtworkImage(image.url, image.previousUrl);
+  } catch (error) {
+    // A browser that cannot keep the device copy was already warned about once.
+    if (error instanceof OfflineUnavailableError) return;
+    console.warn("[offline] could not copy the answer to the device", error);
+  }
+}