@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.1

package/src/core/rest/rest-client.ts

@@ -1,152 +1,152 @@
-/**
- * The REST transport: a small fetch router over the contract's route table
- * (plan §12 A10). It splits one merged fields object into the path, query
- * and JSON body the way ayepi's client does, stamps `x-hub-client`, and turns
- * failures into {@link HubError}s. It carries no schemas: replies are typed
- * from the contract and trusted, as ayepi's zod-free client trusts them.
- */
-import { errorFor, HubError, readErrorFields, UNSUPPORTED_BY_HUB } from '../errors';
-import { isRecord } from '../storage/json-guards';
-import { HUB_CLIENT_VERSION } from '../version/client-version.gen';
-import type { EndpointFields, EndpointName, EndpointReply } from './endpoint-types';
-import { ROUTES } from './routes.gen';
-
-/** The header that tells the hub which client version is calling. */
-export const CLIENT_VERSION_HEADER = 'x-hub-client';
-
-/** What both hubs answer for a route they do not have. */
-const NO_SUCH_ENDPOINT = 'No such API endpoint.';
-
-/** How a {@link RestClient} reaches the hub. */
-export interface RestClientOptions {
-  /** The API's absolute base URL without a trailing slash, e.g. `https://diffenderfer.games/_api`. */
-  readonly apiBase: string;
-  /** The fetch to use. */
-  readonly fetch: typeof fetch;
-  /** Called whenever the hub answered at all (any status): the network is up. */
-  readonly onReachable?: () => void;
-}
-
-/** The arguments of a call: the fields, optional when the endpoint takes none that are required. */
-export type CallArguments<K extends EndpointName> = Partial<EndpointFields<K>> extends EndpointFields<K>
-  ? [fields?: EndpointFields<K>]
-  : [fields: EndpointFields<K>];
-
-/** Typed calls to the hub's public REST API. */
-export interface RestClient {
-  /** The API's absolute base URL. */
-  readonly apiBase: string;
-  /** Call an endpoint; resolves with its reply body, rejects with a {@link HubError}. */
-  call<K extends EndpointName>(name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
-}
-
-/** One field value as URL text. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a request field value of any contract type
-function urlText(fieldValue: unknown): string {
-  if (typeof fieldValue === 'string') {
-    return fieldValue;
-  }
-  if (typeof fieldValue === 'number' || typeof fieldValue === 'boolean') {
-    return String(fieldValue);
-  }
-  return JSON.stringify(fieldValue);
-}
-
-/** The request one call makes: its URL (under the API base), method and JSON body. */
-export interface PlannedRequest {
-  /** The path and query, e.g. `/games/pool/leaderboards/best?limit=50`. */
-  readonly pathAndQuery: string;
-  /** The HTTP method. */
-  readonly method: string;
-  /** The JSON body text, or `undefined` for none. */
-  readonly bodyText: string | undefined;
-}
-
-/**
- * Split merged fields into path, query and body for one endpoint: `:name`
- * segments take their field, query keys go to the query string, and the
- * rest is the JSON body. POST and PUT always send a body (`{}` when empty),
- * as the v1 client did; DELETE sends one only when it has fields.
- */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
-export function planRequest(name: EndpointName, fields: unknown): PlannedRequest {
-  const route = ROUTES[name];
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
-  const remaining = new Map<string, unknown>(Object.entries(isRecord(fields) ? fields : {}).filter(([, fieldValue]) => fieldValue !== undefined));
-  const path = route.path.replace(/:([A-Za-z]+)/g, (_segment, paramName: string) => {
-    const paramValue = remaining.get(paramName);
-    remaining.delete(paramName);
-    return encodeURIComponent(urlText(paramValue));
-  });
-  const queryKeys: readonly string[] = route.method === 'GET' ? [...remaining.keys()] : route.query;
-  const query = new URLSearchParams();
-  for (const key of queryKeys) {
-    const queryValue = remaining.get(key);
-    remaining.delete(key);
-    if (queryValue !== undefined && queryValue !== null) {
-      query.set(key, urlText(queryValue));
-    }
-  }
-  const queryText = query.toString();
-  const hasBody = route.method === 'POST' || route.method === 'PUT' || (route.method === 'DELETE' && remaining.size > 0);
-  return {
-    pathAndQuery: queryText === '' ? path : `${path}?${queryText}`,
-    method: route.method,
-    bodyText: hasBody ? JSON.stringify(Object.fromEntries(remaining)) : undefined,
-  };
-}
-
-/**
- * The reply body, typed by the contract. This is the client's one trust
- * boundary on replies: there is no zod in the browser bundle (plan D16).
- */
-async function readReply<Reply>(response: Response): Promise<Reply> {
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- trust boundary: the hub's JSON reply, typed by the contract (the zod-free client trusts the server, plan D16)
-    return await response.json();
-  } catch {
-    throw new HubError('The hub sent a reply that is not JSON.', response.status);
-  }
-}
-
-/** The error for a failed response. */
-async function failureOf(name: EndpointName, response: Response): Promise<HubError> {
-  let fields = readErrorFields(undefined);
-  try {
-    fields = readErrorFields(await response.json());
-  } catch {
-    // A non-JSON error body keeps the generic message.
-  }
-  if (response.status === 404 && fields.error === NO_SUCH_ENDPOINT) {
-    return new HubError(`This hub does not have "${name}" yet: deploy the hub first, or use an older client.`, 404, { code: UNSUPPORTED_BY_HUB });
-  }
-  return errorFor(fields.error ?? `Request failed (${response.status})`, response.status, fields);
-}
-
-/** A REST client for one API base. */
-export function createRestClient(options: RestClientOptions): RestClient {
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
-  async function send<Reply>(name: EndpointName, fields: unknown): Promise<Reply> {
-    const planned = planRequest(name, fields);
-    let response: Response;
-    try {
-      response = await options.fetch(options.apiBase + planned.pathAndQuery, {
-        method: planned.method,
-        credentials: 'same-origin',
-        headers: { 'content-type': 'application/json', [CLIENT_VERSION_HEADER]: HUB_CLIENT_VERSION },
-        ...(planned.bodyText === undefined ? {} : { body: planned.bodyText }),
-      });
-    } catch (failure) {
-      throw new HubError(`Hub unreachable: ${failure instanceof Error ? failure.message : String(failure)}`);
-    }
-    options.onReachable?.();
-    if (!response.ok) {
-      throw await failureOf(name, response);
-    }
-    return readReply<Reply>(response);
-  }
-  return {
-    apiBase: options.apiBase,
-    call: (name, ...fieldsArgument) => send(name, fieldsArgument[0]),
-  };
-}
+/**
+ * The REST transport: a small fetch router over the contract's route table
+ * (plan §12 A10). It splits one merged fields object into the path, query
+ * and JSON body the way ayepi's client does, stamps `x-hub-client`, and turns
+ * failures into {@link HubError}s. It carries no schemas: replies are typed
+ * from the contract and trusted, as ayepi's zod-free client trusts them.
+ */
+import { errorFor, HubError, readErrorFields, UNSUPPORTED_BY_HUB } from '../errors';
+import { isRecord } from '../storage/json-guards';
+import { HUB_CLIENT_VERSION } from '../version/client-version.gen';
+import type { EndpointFields, EndpointName, EndpointReply } from './endpoint-types';
+import { ROUTES } from './routes.gen';
+
+/** The header that tells the hub which client version is calling. */
+export const CLIENT_VERSION_HEADER = 'x-hub-client';
+
+/** What both hubs answer for a route they do not have. */
+const NO_SUCH_ENDPOINT = 'No such API endpoint.';
+
+/** How a {@link RestClient} reaches the hub. */
+export interface RestClientOptions {
+  /** The API's absolute base URL without a trailing slash, e.g. `https://diffenderfer.games/_api`. */
+  readonly apiBase: string;
+  /** The fetch to use. */
+  readonly fetch: typeof fetch;
+  /** Called whenever the hub answered at all (any status): the network is up. */
+  readonly onReachable?: () => void;
+}
+
+/** The arguments of a call: the fields, optional when the endpoint takes none that are required. */
+export type CallArguments<K extends EndpointName> = Partial<EndpointFields<K>> extends EndpointFields<K>
+  ? [fields?: EndpointFields<K>]
+  : [fields: EndpointFields<K>];
+
+/** Typed calls to the hub's public REST API. */
+export interface RestClient {
+  /** The API's absolute base URL. */
+  readonly apiBase: string;
+  /** Call an endpoint; resolves with its reply body, rejects with a {@link HubError}. */
+  call<K extends EndpointName>(name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
+}
+
+/** One field value as URL text. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a request field value of any contract type
+function urlText(fieldValue: unknown): string {
+  if (typeof fieldValue === 'string') {
+    return fieldValue;
+  }
+  if (typeof fieldValue === 'number' || typeof fieldValue === 'boolean') {
+    return String(fieldValue);
+  }
+  return JSON.stringify(fieldValue);
+}
+
+/** The request one call makes: its URL (under the API base), method and JSON body. */
+export interface PlannedRequest {
+  /** The path and query, e.g. `/games/pool/leaderboards/best?limit=50`. */
+  readonly pathAndQuery: string;
+  /** The HTTP method. */
+  readonly method: string;
+  /** The JSON body text, or `undefined` for none. */
+  readonly bodyText: string | undefined;
+}
+
+/**
+ * Split merged fields into path, query and body for one endpoint: `:name`
+ * segments take their field, query keys go to the query string, and the
+ * rest is the JSON body. POST and PUT always send a body (`{}` when empty),
+ * as the v1 client did; DELETE sends one only when it has fields.
+ */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+export function planRequest(name: EndpointName, fields: unknown): PlannedRequest {
+  const route = ROUTES[name];
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+  const remaining = new Map<string, unknown>(Object.entries(isRecord(fields) ? fields : {}).filter(([, fieldValue]) => fieldValue !== undefined));
+  const path = route.path.replace(/:([A-Za-z]+)/g, (_segment, paramName: string) => {
+    const paramValue = remaining.get(paramName);
+    remaining.delete(paramName);
+    return encodeURIComponent(urlText(paramValue));
+  });
+  const queryKeys: readonly string[] = route.method === 'GET' ? [...remaining.keys()] : route.query;
+  const query = new URLSearchParams();
+  for (const key of queryKeys) {
+    const queryValue = remaining.get(key);
+    remaining.delete(key);
+    if (queryValue !== undefined && queryValue !== null) {
+      query.set(key, urlText(queryValue));
+    }
+  }
+  const queryText = query.toString();
+  const hasBody = route.method === 'POST' || route.method === 'PUT' || (route.method === 'DELETE' && remaining.size > 0);
+  return {
+    pathAndQuery: queryText === '' ? path : `${path}?${queryText}`,
+    method: route.method,
+    bodyText: hasBody ? JSON.stringify(Object.fromEntries(remaining)) : undefined,
+  };
+}
+
+/**
+ * The reply body, typed by the contract. This is the client's one trust
+ * boundary on replies: there is no zod in the browser bundle (plan D16).
+ */
+async function readReply<Reply>(response: Response): Promise<Reply> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- trust boundary: the hub's JSON reply, typed by the contract (the zod-free client trusts the server, plan D16)
+    return await response.json();
+  } catch {
+    throw new HubError('The hub sent a reply that is not JSON.', response.status);
+  }
+}
+
+/** The error for a failed response. */
+async function failureOf(name: EndpointName, response: Response): Promise<HubError> {
+  let fields = readErrorFields(undefined);
+  try {
+    fields = readErrorFields(await response.json());
+  } catch {
+    // A non-JSON error body keeps the generic message.
+  }
+  if (response.status === 404 && fields.error === NO_SUCH_ENDPOINT) {
+    return new HubError(`This hub does not have "${name}" yet: deploy the hub first, or use an older client.`, 404, { code: UNSUPPORTED_BY_HUB });
+  }
+  return errorFor(fields.error ?? `Request failed (${response.status})`, response.status, fields);
+}
+
+/** A REST client for one API base. */
+export function createRestClient(options: RestClientOptions): RestClient {
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+  async function send<Reply>(name: EndpointName, fields: unknown): Promise<Reply> {
+    const planned = planRequest(name, fields);
+    let response: Response;
+    try {
+      response = await options.fetch(options.apiBase + planned.pathAndQuery, {
+        method: planned.method,
+        credentials: 'same-origin',
+        headers: { 'content-type': 'application/json', [CLIENT_VERSION_HEADER]: HUB_CLIENT_VERSION },
+        ...(planned.bodyText === undefined ? {} : { body: planned.bodyText }),
+      });
+    } catch (failure) {
+      throw new HubError(`Hub unreachable: ${failure instanceof Error ? failure.message : String(failure)}`);
+    }
+    options.onReachable?.();
+    if (!response.ok) {
+      throw await failureOf(name, response);
+    }
+    return readReply<Reply>(response);
+  }
+  return {
+    apiBase: options.apiBase,
+    call: (name, ...fieldsArgument) => send(name, fieldsArgument[0]),
+  };
+}

package/src/core/storage/json-guards.ts

@@ -1,74 +1,74 @@
-/**
- * Small type guards for values this client did not create: JSON read back
- * from `localStorage`, error bodies, objects from other bundles. The browser
- * client carries no zod (plan D16), so these replace schema parsing on the
- * few shapes it reads.
- */
-import type { Json } from '@diffenderfer-games/hub-contract';
-
-/** A plain object's fields, not yet checked. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the fields of a value read from storage or another bundle
-export type UncheckedRecord = Readonly<Record<string, unknown>>;
-
-/** Whether `candidate` is a non-null, non-array object. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage or another bundle
-export function isRecord(candidate: unknown): candidate is UncheckedRecord {
-  return typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate);
-}
-
-/** `candidate` when it is a string, else `undefined`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
-export function optionalString(candidate: unknown): string | undefined {
-  return typeof candidate === 'string' ? candidate : undefined;
-}
-
-/** `candidate` when it is a finite number, else `undefined`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
-export function optionalNumber(candidate: unknown): number | undefined {
-  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
-}
-
-/** Whether `candidate` is a string or `null`. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
-export function isNullableString(candidate: unknown): candidate is string | null {
-  return candidate === null || typeof candidate === 'string';
-}
-
-/** Whether `candidate` is a JSON value (what `JSON.parse` can return). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
-export function isJson(candidate: unknown): candidate is Json {
-  if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
-    return true;
-  }
-  if (typeof candidate === 'number') {
-    return Number.isFinite(candidate);
-  }
-  if (Array.isArray(candidate)) {
-    return candidate.every(isJson);
-  }
-  return isRecord(candidate) && Object.values(candidate).every(isJson);
-}
-
-/** Whether `candidate` is an object whose every value is a finite number. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
-export function isNumberRecord(candidate: unknown): candidate is Readonly<Record<string, number>> {
-  return isRecord(candidate) && Object.values(candidate).every((entry) => optionalNumber(entry) !== undefined);
-}
-
-/** The strings in `candidate`, or an empty list when it is not an array. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a list read from storage
-export function stringsIn(candidate: unknown): string[] {
-  return Array.isArray(candidate) ? candidate.filter((entry): entry is string => typeof entry === 'string') : [];
-}
-
-/** Parse JSON text without throwing: `undefined` when it is not JSON. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: text read from storage, checked by the caller's guard next
-export function parseJsonText(text: string): unknown {
-  try {
-    // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, checked by the caller's guard next
-    const parsed: unknown = JSON.parse(text);
-    return parsed;
-  } catch {
-    return undefined;
-  }
-}
+/**
+ * Small type guards for values this client did not create: JSON read back
+ * from `localStorage`, error bodies, objects from other bundles. The browser
+ * client carries no zod (plan D16), so these replace schema parsing on the
+ * few shapes it reads.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+
+/** A plain object's fields, not yet checked. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the fields of a value read from storage or another bundle
+export type UncheckedRecord = Readonly<Record<string, unknown>>;
+
+/** Whether `candidate` is a non-null, non-array object. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage or another bundle
+export function isRecord(candidate: unknown): candidate is UncheckedRecord {
+  return typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate);
+}
+
+/** `candidate` when it is a string, else `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function optionalString(candidate: unknown): string | undefined {
+  return typeof candidate === 'string' ? candidate : undefined;
+}
+
+/** `candidate` when it is a finite number, else `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function optionalNumber(candidate: unknown): number | undefined {
+  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
+}
+
+/** Whether `candidate` is a string or `null`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function isNullableString(candidate: unknown): candidate is string | null {
+  return candidate === null || typeof candidate === 'string';
+}
+
+/** Whether `candidate` is a JSON value (what `JSON.parse` can return). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isJson(candidate: unknown): candidate is Json {
+  if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
+    return true;
+  }
+  if (typeof candidate === 'number') {
+    return Number.isFinite(candidate);
+  }
+  if (Array.isArray(candidate)) {
+    return candidate.every(isJson);
+  }
+  return isRecord(candidate) && Object.values(candidate).every(isJson);
+}
+
+/** Whether `candidate` is an object whose every value is a finite number. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isNumberRecord(candidate: unknown): candidate is Readonly<Record<string, number>> {
+  return isRecord(candidate) && Object.values(candidate).every((entry) => optionalNumber(entry) !== undefined);
+}
+
+/** The strings in `candidate`, or an empty list when it is not an array. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a list read from storage
+export function stringsIn(candidate: unknown): string[] {
+  return Array.isArray(candidate) ? candidate.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/** Parse JSON text without throwing: `undefined` when it is not JSON. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: text read from storage, checked by the caller's guard next
+export function parseJsonText(text: string): unknown {
+  try {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, checked by the caller's guard next
+    const parsed: unknown = JSON.parse(text);
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}

package/src/core/storage/key-value.ts

@@ -1,66 +1,66 @@
-/**
- * The string store behind the offline cache and queues: `localStorage` when
- * the page has it, else an in-memory map (privacy mode, Node, tests). Every
- * key keeps the v1 client's name, so a page upgraded from a vendored copy
- * still reads the queue and cache that copy wrote.
- */
-
-/** A string key-value store with `localStorage`'s semantics. */
-export interface KeyValueStore {
-  /** The stored text, or `null`. */
-  read(key: string): string | null;
-  /** Store text; a full or blocked storage is ignored. */
-  write(key: string, text: string): void;
-  /** Forget a key. */
-  remove(key: string): void;
-  /** Every stored key. */
-  keys(): string[];
-}
-
-/** A store backed by a `Storage` (`localStorage`). */
-function storageBacked(storage: Storage): KeyValueStore {
-  return {
-    read: (key) => storage.getItem(key),
-    write: (key, text) => {
-      try {
-        storage.setItem(key, text);
-      } catch {
-        // A full or blocked storage loses the write, as in v1.
-      }
-    },
-    remove: (key) => {
-      storage.removeItem(key);
-    },
-    keys: () => Object.keys(storage),
-  };
-}
-
-/** A store held in memory for this page only. */
-export function createMemoryStore(): KeyValueStore {
-  const entries = new Map<string, string>();
-  return {
-    read: (key) => entries.get(key) ?? null,
-    write: (key, text) => {
-      entries.set(key, text);
-    },
-    remove: (key) => {
-      entries.delete(key);
-    },
-    keys: () => [...entries.keys()],
-  };
-}
-
-/** The page's `localStorage`, or `undefined` when it is missing or throws (privacy mode). */
-function pageStorage(): Storage | undefined {
-  try {
-    return typeof localStorage === 'undefined' ? undefined : localStorage;
-  } catch {
-    return undefined;
-  }
-}
-
-/** `localStorage` when available, else a fresh in-memory store. */
-export function createPageStore(): KeyValueStore {
-  const storage = pageStorage();
-  return storage === undefined ? createMemoryStore() : storageBacked(storage);
-}
+/**
+ * The string store behind the offline cache and queues: `localStorage` when
+ * the page has it, else an in-memory map (privacy mode, Node, tests). Every
+ * key keeps the v1 client's name, so a page upgraded from a vendored copy
+ * still reads the queue and cache that copy wrote.
+ */
+
+/** A string key-value store with `localStorage`'s semantics. */
+export interface KeyValueStore {
+  /** The stored text, or `null`. */
+  read(key: string): string | null;
+  /** Store text; a full or blocked storage is ignored. */
+  write(key: string, text: string): void;
+  /** Forget a key. */
+  remove(key: string): void;
+  /** Every stored key. */
+  keys(): string[];
+}
+
+/** A store backed by a `Storage` (`localStorage`). */
+function storageBacked(storage: Storage): KeyValueStore {
+  return {
+    read: (key) => storage.getItem(key),
+    write: (key, text) => {
+      try {
+        storage.setItem(key, text);
+      } catch {
+        // A full or blocked storage loses the write, as in v1.
+      }
+    },
+    remove: (key) => {
+      storage.removeItem(key);
+    },
+    keys: () => Object.keys(storage),
+  };
+}
+
+/** A store held in memory for this page only. */
+export function createMemoryStore(): KeyValueStore {
+  const entries = new Map<string, string>();
+  return {
+    read: (key) => entries.get(key) ?? null,
+    write: (key, text) => {
+      entries.set(key, text);
+    },
+    remove: (key) => {
+      entries.delete(key);
+    },
+    keys: () => [...entries.keys()],
+  };
+}
+
+/** The page's `localStorage`, or `undefined` when it is missing or throws (privacy mode). */
+function pageStorage(): Storage | undefined {
+  try {
+    return typeof localStorage === 'undefined' ? undefined : localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `localStorage` when available, else a fresh in-memory store. */
+export function createPageStore(): KeyValueStore {
+  const storage = pageStorage();
+  return storage === undefined ? createMemoryStore() : storageBacked(storage);
+}