@joystyk/storage 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# @joystyk/storage
+
+## 0.2.0
+
+### Patch Changes
+
+- bb095c7: Add shared real-time input, pause, pace records and ghost races, plus a WebGL 2 renderer
+  lifecycle with context recovery and adaptive quality. Launch daily fixed-step simulations
+  from published configs and retain their puzzle identity through saved games.
+- Updated dependencies [bb095c7]
+- Updated dependencies [bb095c7]
+  - @joystyk/contracts@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.
+
+### Patch Changes
+
+- Updated dependencies
+  - @joystyk/contracts@0.1.0

package/README.md

@@ -1,5 +1,169 @@
 # @joystyk/storage
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+Everything a player keeps on their device: save slots, stats, daily streaks, preferences and
+each game's own key-value data. It sits on IndexedDB in the browser and on memory in tests
+and server rendering, and it never trusts what it reads back.
 
-Source: https://github.com/joystyk-games/game-libraries
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/storage
+```
+
+Node consumers require Node 24.15 or later. Browser entry points require a modern
+browser and should be loaded in the browser.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/storage` | ES module and TypeScript declarations |
+| `@joystyk/storage/browser` | ES module and TypeScript declarations |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+The design comes from offline-and-updates.md (Joystyk host reference)
+(the Data tier, Rule 3 on saves) and game-contract.md (Joystyk host reference)
+(the save envelope, migrations and `PlatformApi.storage`).
+
+## Entry points
+
+| Import | Runs in | Contents |
+| --- | --- | --- |
+| `@joystyk/storage` | Anywhere (no DOM) | Record stores, the save, stats, streak and preference stores, the memory backend, schemas, the migration runner |
+| `@joystyk/storage/browser` | Browser | The IndexedDB backend, `openBrowserStorage`, the persistent-storage helpers, `systemEnvironment` |
+
+`tsconfig.core.json` type-checks the core without DOM types, so browser code can't leak into
+it: anything that needs `window`, `navigator` or `indexedDB` goes in `src/browser/`.
+
+## How it fits together
+
+```ts
+import { openBrowserStorage, requestPersistentStorage } from '@joystyk/storage/browser';
+
+const storage = await openBrowserStorage({ onNotice: (notice) => frame.show(notice.message) });
+const player = storage.player(profile.id); // from @joystyk/identity
+
+await player.saves.write('nim', 'auto', envelope);              // a contracts SaveEnvelope
+const resumed = await player.saves.load('nim', 'auto', {          // migrated and validated
+  saveVersion: manifest.versions.save,
+  migrations: module.migrations,
+  state: module.engine.schemas.state,
+});
+await player.stats.record('nim', outcome);                        // a contracts Outcome
+await player.streaks.set('daily-word', { current: 3, best: 5, lastDay: '2026-10-08' });
+await player.preferences.update({ singleKeyShortcuts: false });
+const platformStorage = player.gameStorage('nim');                // PlatformApi.storage
+
+await requestPersistentStorage(); // when the player pins a game, never on page load
+```
+
+In tests and on the server, use `openStorage({ backend: createMemoryBackend() })`.
+
+### The layers
+
+1. **Backend** (`StorageBackend`): raw get, put, delete, list-by-prefix and clear over named
+   object stores, with JSON values. `createMemoryBackend` and `openIndexedDbBackend`
+   implement it. Every operation resolves to a contracts `Result`; expected failures such as
+   a full quota never reject.
+2. **Record stores** (`RecordKind`, `createRecordStore`): every record is stored as
+   `{ version, writtenAt, value }`. On read, the store checks that shape, runs the kind's
+   migrations from the record's version to the current one (the contracts' `runMigrations`),
+   then validates the value with the kind's Standard Schema. On write, it validates first.
+3. **Player stores** (`storage.player(id)`): saves, stats, streaks, preferences and game data,
+   with keys that start with the player id (`<playerId>/<gameId>/<slot>`), never a device id.
+
+Other packages define their own record kinds on the same machinery: `@joystyk/identity` keeps
+its profile in the `identity` store with `storage.records(PROFILE_RECORD)`.
+
+### Ports for the session runner
+
+`SaveStore`, `StatsStore`, `StreakStore` and `PreferencesStore` are interfaces, keyed by game
+id and slot name, so `@joystyk/session` can declare narrower ports and pass these stores in.
+Every method returns `Promise<Result<…, StorageError>>`.
+
+## Never trusted
+
+A record that fails any step is never handed to the caller:
+
+| What went wrong | What happens |
+| --- | --- |
+| Not a record, not JSON, fails its schema, or a migration fails or is missing | Deleted, or for saves moved to the `archive` store, with a `RecordDiscarded` or `RecordArchived` notice. The read returns null (or the defaults). |
+| Written by a newer build (`version` above the current one) | Kept for that build, with a `RecordFromFuture` notice; the read returns null. |
+| A save's game state fails the game's migrations or `schemas.state` (`saves.load`) | Archived with a notice, or kept with `RecordFromFuture` when the game's save version is newer. |
+
+`saves.load` doesn't compare `rulesVersion`; the caller decides whether an old-rules game can
+continue (Rule 3).
+
+Notices carry a player-facing `message` and developer `issues`; show only the message.
+
+## Quota
+
+When a write fails with `QuotaExceeded`, the store clears the `archive` store, the least
+valuable data it keeps, and tries once more. If that fails too, the write returns a
+`QuotaExceeded` error and a notice. `estimateStorage()` reports usage, and
+`requestPersistentStorage()` asks the browser not to evict the site's data.
+
+A failed `PlatformApi.storage` write rejects with a `StorageFailure`, because the contract's
+`Promise<void>` has no other channel; reads resolve to null.
+
+## Versions
+
+- **Record shapes**: each `RecordKind` has a `version` and a migration chain. Bump the
+  version and add a `Migration` (from the contracts) when a shape changes; records upgrade on
+  their next read and are rewritten in the new shape.
+- **Object stores**: `DATABASE_UPGRADES` in `src/browser/indexeddb.ts`, numbered from 1 with
+  no gaps. Add a step only to create or remove an object store. When another tab opens a
+  newer version, this connection closes, calls `onVersionChange`, and later operations
+  return `Unavailable`.
+
+## Preferences
+
+`StoredPreferences` holds the player's choices, where `system` follows the operating system:
+reduced motion (`system`, `reduce`, `no-preference`), sound and volume, single-key
+shortcuts (WCAG 2.1.4) and theme (`system`, `light`, `dark`), plus an optional locale.
+`resolvePreferences(stored, systemEnvironment())` turns them into the contracts'
+`Preferences`, with `singleKeyShortcuts` added. `aiContentAccepted` records that the player
+accepted the AI-content notice (host policy); it is optional, so records written before it read as
+"not yet" without a migration.
+
+### Other tabs
+
+A preference set in one tab reaches every other open tab of the site (bead host integration work).
+`update` notifies this tab's subscribers, then publishes `{ kind: 'preferences', playerId }`
+on the storage's `ChangeFeed`. Each other tab parses the message, reads the preferences back
+from IndexedDB through their schema, and calls its subscribers with the source
+`other-tab`. The message carries no values, so nothing reaches a tab without passing the
+record's schema.
+
+`openBrowserStorage` builds the feed with `openChangeFeed()`: a `BroadcastChannel` named
+`joystyk-storage`, or, where the browser has none, a `storage` event fired by writing and at
+once removing a localStorage key of the same name. Where neither works, and when storage
+fell back to memory (which tabs don't share), changes stay in their tab. In tests,
+`createMemoryChangeHub()` gives each simulated tab a feed.
+
+## Writing only if absent
+
+`StorageBackend.putIfAbsent` writes a key only when it is empty, in one step. IndexedDB does
+the read and the `add` in one readwrite transaction, and it runs readwrite transactions on a
+store one at a time across every connection, so two tabs can't both find the key empty. The
+record stores expose it as `setIfAbsent`, which resolves to the record the key holds
+afterwards. `@joystyk/identity` creates the guest with it.
+
+## Tests
+
+- `src/*.test.ts` run in Node against the memory backend: decoding, migrations, archive and
+  discard, quota retry, saves, stats, streaks, preferences and game data.
+- `src/browser/*.browser.test.ts` run in real Chromium: opening and upgrading the database,
+  `versionchange` from another connection, corrupt and non-JSON records written behind the
+  store's back, quota errors and the persistent-storage request. `cross-tab.browser.test.ts`
+  stands two storages on one database for two tabs and checks that a preference change
+  reaches the other, over `BroadcastChannel` and over the `storage` event from a same-origin
+  iframe (Vitest's browser mode can't open a second page).
+
+Chromium's real quota can't be reached in these tests: Playwright's browser contexts are off
+the record, and `Storage.overrideQuotaForOrigin` over CDP leaves their quota unchanged. The
+quota tests make `IDBObjectStore.put` throw the browser's own `QuotaExceededError` instead,
+and everything around it runs for real.

package/dist/backend.d.ts

@@ -0,0 +1,64 @@
+import type { GameError, Json, Result } from '@joystyk/contracts';
+/**
+ * The object stores every backend provides. IndexedDB creates one object store per name;
+ * the memory backend keeps one map per name.
+ */
+export declare const STORE_NAMES: readonly ["saves", "stats", "streaks", "preferences", "game-data", "identity", "archive"];
+/** One of the backend's object stores. */
+export type StoreName = (typeof STORE_NAMES)[number];
+/** Why a storage operation failed. */
+export type StorageErrorCode = 
+/** The browser refused the write because the origin's storage is full. */
+'QuotaExceeded'
+/** Storage can't be opened: private browsing, blocked site data, or no IndexedDB at all. */
+ | 'Unavailable'
+/** The value isn't JSON or doesn't match its record's schema; nothing was written. */
+ | 'InvalidValue'
+/** A key part is empty, too long or contains characters keys may not use. */
+ | 'InvalidKey'
+/** Anything else the backend reported. */
+ | 'Failed';
+/** An expected storage failure, worded for players. Shaped like `GameError`. */
+export type StorageError = GameError & {
+    readonly code: StorageErrorCode;
+};
+/** Builds a `StorageError`, leaving out an absent `detail` so the error stays JSON. */
+export declare const storageError: (code: StorageErrorCode, message: string, detail?: Json) => StorageError;
+/** Player-facing wording for each failure. */
+export declare const MESSAGES: {
+    readonly QuotaExceeded: "Your browser's storage for this site is full, so this couldn't be saved.";
+    readonly Unavailable: "This browser isn't letting the site store data, so progress won't be kept.";
+    readonly InvalidValue: "This couldn't be saved because it isn't in a form the site can store.";
+    readonly InvalidKey: "This couldn't be saved because its name isn't valid.";
+    readonly Failed: "Something went wrong while saving or loading.";
+};
+/** What `putIfAbsent` found: `written`, or the value another write left at the key. */
+export type PutIfAbsent = {
+    readonly written: true;
+} | {
+    readonly written: false;
+    readonly value: unknown;
+};
+/**
+ * Raw key-value persistence: the only part that differs between IndexedDB and memory.
+ * Values are JSON. Every operation resolves to a `Result`; expected failures, such as a full
+ * quota, never reject. Keys are strings, ordered by code unit, and `keys` lists those that
+ * start with a prefix.
+ */
+export interface StorageBackend {
+    /** `undefined` when the key is absent. The value is untrusted: decode it before use. */
+    get(store: StoreName, key: string): Promise<Result<unknown, StorageError>>;
+    put(store: StoreName, key: string, value: Json): Promise<Result<void, StorageError>>;
+    /**
+     * Writes `value` only when `key` is absent, as one atomic step: of two callers racing, even
+     * in two tabs, exactly one writes. Resolves to whether this call wrote, and the value the
+     * key holds afterwards (untrusted when another caller wrote it).
+     */
+    putIfAbsent(store: StoreName, key: string, value: Json): Promise<Result<PutIfAbsent, StorageError>>;
+    delete(store: StoreName, key: string): Promise<Result<void, StorageError>>;
+    /** The keys that start with `prefix`, in ascending order. */
+    keys(store: StoreName, prefix: string): Promise<Result<readonly string[], StorageError>>;
+    clear(store: StoreName): Promise<Result<void, StorageError>>;
+    /** Releases the connection. Idempotent. */
+    close(): void;
+}

package/dist/backend.js

@@ -0,0 +1,35 @@
+//#region src/backend.ts
+/**
+* The object stores every backend provides. IndexedDB creates one object store per name;
+* the memory backend keeps one map per name.
+*/
+var STORE_NAMES = [
+	"saves",
+	"stats",
+	"streaks",
+	"preferences",
+	"game-data",
+	"identity",
+	"archive"
+];
+/** Builds a `StorageError`, leaving out an absent `detail` so the error stays JSON. */
+var storageError = (code, message, detail) => detail === void 0 ? {
+	code,
+	message
+} : {
+	code,
+	message,
+	detail
+};
+/** Player-facing wording for each failure. */
+var MESSAGES = {
+	QuotaExceeded: "Your browser's storage for this site is full, so this couldn't be saved.",
+	Unavailable: "This browser isn't letting the site store data, so progress won't be kept.",
+	InvalidValue: "This couldn't be saved because it isn't in a form the site can store.",
+	InvalidKey: "This couldn't be saved because its name isn't valid.",
+	Failed: "Something went wrong while saving or loading."
+};
+//#endregion
+export { MESSAGES, STORE_NAMES, storageError };
+
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","names":[],"sources":["../src/backend.ts"],"sourcesContent":["import type { GameError, Json, Result } from '@joystyk/contracts';\n\n/**\n * The object stores every backend provides. IndexedDB creates one object store per name;\n * the memory backend keeps one map per name.\n */\nexport const STORE_NAMES = ['saves', 'stats', 'streaks', 'preferences', 'game-data', 'identity', 'archive'] as const;\n\n/** One of the backend's object stores. */\nexport type StoreName = (typeof STORE_NAMES)[number];\n\n/** Why a storage operation failed. */\nexport type StorageErrorCode =\n  /** The browser refused the write because the origin's storage is full. */\n  | 'QuotaExceeded'\n  /** Storage can't be opened: private browsing, blocked site data, or no IndexedDB at all. */\n  | 'Unavailable'\n  /** The value isn't JSON or doesn't match its record's schema; nothing was written. */\n  | 'InvalidValue'\n  /** A key part is empty, too long or contains characters keys may not use. */\n  | 'InvalidKey'\n  /** Anything else the backend reported. */\n  | 'Failed';\n\n/** An expected storage failure, worded for players. Shaped like `GameError`. */\nexport type StorageError = GameError & { readonly code: StorageErrorCode };\n\n/** Builds a `StorageError`, leaving out an absent `detail` so the error stays JSON. */\nexport const storageError = (code: StorageErrorCode, message: string, detail?: Json): StorageError =>\n  detail === undefined ? { code, message } : { code, message, detail };\n\n/** Player-facing wording for each failure. */\nexport const MESSAGES = {\n  QuotaExceeded: \"Your browser's storage for this site is full, so this couldn't be saved.\",\n  Unavailable: \"This browser isn't letting the site store data, so progress won't be kept.\",\n  InvalidValue: \"This couldn't be saved because it isn't in a form the site can store.\",\n  InvalidKey: \"This couldn't be saved because its name isn't valid.\",\n  Failed: 'Something went wrong while saving or loading.',\n} as const satisfies Record<StorageErrorCode, string>;\n\n/** What `putIfAbsent` found: `written`, or the value another write left at the key. */\nexport type PutIfAbsent = { readonly written: true } | { readonly written: false; readonly value: unknown };\n\n/**\n * Raw key-value persistence: the only part that differs between IndexedDB and memory.\n * Values are JSON. Every operation resolves to a `Result`; expected failures, such as a full\n * quota, never reject. Keys are strings, ordered by code unit, and `keys` lists those that\n * start with a prefix.\n */\nexport interface StorageBackend {\n  /** `undefined` when the key is absent. The value is untrusted: decode it before use. */\n  get(store: StoreName, key: string): Promise<Result<unknown, StorageError>>;\n  put(store: StoreName, key: string, value: Json): Promise<Result<void, StorageError>>;\n  /**\n   * Writes `value` only when `key` is absent, as one atomic step: of two callers racing, even\n   * in two tabs, exactly one writes. Resolves to whether this call wrote, and the value the\n   * key holds afterwards (untrusted when another caller wrote it).\n   */\n  putIfAbsent(store: StoreName, key: string, value: Json): Promise<Result<PutIfAbsent, StorageError>>;\n  delete(store: StoreName, key: string): Promise<Result<void, StorageError>>;\n  /** The keys that start with `prefix`, in ascending order. */\n  keys(store: StoreName, prefix: string): Promise<Result<readonly string[], StorageError>>;\n  clear(store: StoreName): Promise<Result<void, StorageError>>;\n  /** Releases the connection. Idempotent. */\n  close(): void;\n}\n"],"mappings":";;;;;AAMA,IAAa,cAAc;CAAC;CAAS;CAAS;CAAW;CAAe;CAAa;CAAY;AAAS;;AAsB1G,IAAa,gBAAgB,MAAwB,SAAiB,WACpE,WAAW,KAAA,IAAY;CAAE;CAAM;AAAQ,IAAI;CAAE;CAAM;CAAS;AAAO;;AAGrE,IAAa,WAAW;CACtB,eAAe;CACf,aAAa;CACb,cAAc;CACd,YAAY;CACZ,QAAQ;AACV"}

package/dist/browser/changes.d.ts

@@ -0,0 +1,17 @@
+import type { ChangeFeed } from '../changes.js';
+/** The channel name, and the localStorage key the fallback writes. */
+export declare const CHANGE_CHANNEL = "joystyk-storage";
+/** What `openChangeFeed` needs from a window. */
+export type ChangeFeedHost = Pick<Window, 'localStorage' | 'addEventListener' | 'removeEventListener'> & {
+    readonly BroadcastChannel?: typeof BroadcastChannel;
+};
+/** A feed over BroadcastChannel, which delivers to every other channel of the same name. */
+export declare const broadcastChangeFeed: (Channel: typeof BroadcastChannel, name?: string) => ChangeFeed;
+/**
+ * The fallback: writing to localStorage fires a `storage` event in every other same-origin
+ * document. Each write is unique, so a repeated change still fires, and the key is removed
+ * at once, so nothing stays behind.
+ */
+export declare const storageEventChangeFeed: (host: Pick<ChangeFeedHost, "localStorage" | "addEventListener" | "removeEventListener">, key?: string) => ChangeFeed;
+/** BroadcastChannel when the browser has it, then the `storage` event, then nothing. */
+export declare const openChangeFeed: (host?: ChangeFeedHost) => ChangeFeed;

package/dist/browser/changes.js

@@ -0,0 +1,96 @@
+//#region src/browser/changes.ts
+/** The channel name, and the localStorage key the fallback writes. */
+var CHANGE_CHANNEL = "joystyk-storage";
+var listenerSet = () => {
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		deliver: (message) => {
+			for (const listener of [...listeners]) listener(message);
+		},
+		subscribe: (listener) => {
+			const entry = (message) => listener(message);
+			listeners.add(entry);
+			return () => {
+				listeners.delete(entry);
+			};
+		},
+		clear: () => listeners.clear()
+	};
+};
+/** A feed over BroadcastChannel, which delivers to every other channel of the same name. */
+var broadcastChangeFeed = (Channel, name = CHANGE_CHANNEL) => {
+	const listeners = listenerSet();
+	let channel = new Channel(name);
+	channel.onmessage = (event) => listeners.deliver(event.data);
+	return {
+		publish: (change) => {
+			try {
+				channel?.postMessage(change);
+			} catch {}
+		},
+		subscribe: listeners.subscribe,
+		close: () => {
+			listeners.clear();
+			channel?.close();
+			channel = null;
+		}
+	};
+};
+/**
+* The fallback: writing to localStorage fires a `storage` event in every other same-origin
+* document. Each write is unique, so a repeated change still fires, and the key is removed
+* at once, so nothing stays behind.
+*/
+var storageEventChangeFeed = (host, key = CHANGE_CHANNEL) => {
+	const listeners = listenerSet();
+	let sent = 0;
+	let open = true;
+	const onStorage = (event) => {
+		if (event.key !== key || event.newValue === null) return;
+		let message;
+		try {
+			message = JSON.parse(event.newValue)?.change;
+		} catch {
+			return;
+		}
+		listeners.deliver(message);
+	};
+	host.addEventListener("storage", onStorage);
+	return {
+		publish: (change) => {
+			if (!open) return;
+			try {
+				sent += 1;
+				host.localStorage.setItem(key, JSON.stringify({
+					change,
+					write: `${Date.now()}-${sent}-${Math.random()}`
+				}));
+				host.localStorage.removeItem(key);
+			} catch {}
+		},
+		subscribe: listeners.subscribe,
+		close: () => {
+			open = false;
+			listeners.clear();
+			host.removeEventListener("storage", onStorage);
+		}
+	};
+};
+/** A feed that tells nobody, where neither BroadcastChannel nor localStorage works. */
+var silentFeed = () => ({
+	publish: () => {},
+	subscribe: () => () => {},
+	close: () => {}
+});
+/** BroadcastChannel when the browser has it, then the `storage` event, then nothing. */
+var openChangeFeed = (host = window) => {
+	if (typeof host.BroadcastChannel === "function") return broadcastChangeFeed(host.BroadcastChannel);
+	try {
+		if (typeof host.localStorage?.setItem === "function") return storageEventChangeFeed(host);
+	} catch {}
+	return silentFeed();
+};
+//#endregion
+export { CHANGE_CHANNEL, broadcastChangeFeed, openChangeFeed, storageEventChangeFeed };
+
+//# sourceMappingURL=changes.js.map

package/dist/browser/changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.js","names":[],"sources":["../../src/browser/changes.ts"],"sourcesContent":["// The browser's change feeds (gp-d4v): BroadcastChannel where it exists, and the `storage`\n// event where it doesn't. Both reach every other same-origin tab and frame, never the sender.\nimport type { ChangeFeed, StorageChange } from '../changes.ts';\n\n/** The channel name, and the localStorage key the fallback writes. */\nexport const CHANGE_CHANNEL = 'joystyk-storage';\n\ntype Listener = (message: unknown) => void;\n\n/** What `openChangeFeed` needs from a window. */\nexport type ChangeFeedHost = Pick<Window, 'localStorage' | 'addEventListener' | 'removeEventListener'> & {\n  readonly BroadcastChannel?: typeof BroadcastChannel;\n};\n\nconst listenerSet = () => {\n  const listeners = new Set<Listener>();\n  return {\n    deliver: (message: unknown): void => {\n      for (const listener of [...listeners]) listener(message);\n    },\n    subscribe: (listener: Listener): (() => void) => {\n      const entry: Listener = (message) => listener(message);\n      listeners.add(entry);\n      return () => {\n        listeners.delete(entry);\n      };\n    },\n    clear: (): void => listeners.clear(),\n  };\n};\n\n/** A feed over BroadcastChannel, which delivers to every other channel of the same name. */\nexport const broadcastChangeFeed = (Channel: typeof BroadcastChannel, name: string = CHANGE_CHANNEL): ChangeFeed => {\n  const listeners = listenerSet();\n  let channel: BroadcastChannel | null = new Channel(name);\n  channel.onmessage = (event: MessageEvent) => listeners.deliver(event.data);\n  return {\n    publish: (change: StorageChange) => {\n      try {\n        channel?.postMessage(change);\n      } catch {\n        // A closed or broken channel: the other tabs aren't told.\n      }\n    },\n    subscribe: listeners.subscribe,\n    close: () => {\n      listeners.clear();\n      channel?.close();\n      channel = null;\n    },\n  };\n};\n\n/**\n * The fallback: writing to localStorage fires a `storage` event in every other same-origin\n * document. Each write is unique, so a repeated change still fires, and the key is removed\n * at once, so nothing stays behind.\n */\nexport const storageEventChangeFeed = (\n  host: Pick<ChangeFeedHost, 'localStorage' | 'addEventListener' | 'removeEventListener'>,\n  key: string = CHANGE_CHANNEL,\n): ChangeFeed => {\n  const listeners = listenerSet();\n  let sent = 0;\n  let open = true;\n  const onStorage = (event: StorageEvent): void => {\n    if (event.key !== key || event.newValue === null) return;\n    let message: unknown;\n    try {\n      message = (JSON.parse(event.newValue) as { readonly change?: unknown } | null)?.change;\n    } catch {\n      return;\n    }\n    listeners.deliver(message);\n  };\n  host.addEventListener('storage', onStorage);\n  return {\n    publish: (change: StorageChange) => {\n      if (!open) return;\n      try {\n        sent += 1;\n        host.localStorage.setItem(key, JSON.stringify({ change, write: `${Date.now()}-${sent}-${Math.random()}` }));\n        host.localStorage.removeItem(key);\n      } catch {\n        // localStorage is blocked or full: the other tabs aren't told.\n      }\n    },\n    subscribe: listeners.subscribe,\n    close: () => {\n      open = false;\n      listeners.clear();\n      host.removeEventListener('storage', onStorage);\n    },\n  };\n};\n\n/** A feed that tells nobody, where neither BroadcastChannel nor localStorage works. */\nconst silentFeed = (): ChangeFeed => ({ publish: () => {}, subscribe: () => () => {}, close: () => {} });\n\n/** BroadcastChannel when the browser has it, then the `storage` event, then nothing. */\nexport const openChangeFeed = (host: ChangeFeedHost = window): ChangeFeed => {\n  if (typeof host.BroadcastChannel === 'function') return broadcastChangeFeed(host.BroadcastChannel);\n  try {\n    // Reading localStorage throws where site data is blocked.\n    if (typeof host.localStorage?.setItem === 'function') return storageEventChangeFeed(host);\n  } catch {\n    // Fall through.\n  }\n  return silentFeed();\n};\n"],"mappings":";;AAKA,IAAa,iBAAiB;AAS9B,IAAM,oBAAoB;CACxB,MAAM,4BAAY,IAAI,IAAc;CACpC,OAAO;EACL,UAAU,YAA2B;GACnC,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GAAG,SAAS,OAAO;EACzD;EACA,YAAY,aAAqC;GAC/C,MAAM,SAAmB,YAAY,SAAS,OAAO;GACrD,UAAU,IAAI,KAAK;GACnB,aAAa;IACX,UAAU,OAAO,KAAK;GACxB;EACF;EACA,aAAmB,UAAU,MAAM;CACrC;AACF;;AAGA,IAAa,uBAAuB,SAAkC,OAAe,mBAA+B;CAClH,MAAM,YAAY,YAAY;CAC9B,IAAI,UAAmC,IAAI,QAAQ,IAAI;CACvD,QAAQ,aAAa,UAAwB,UAAU,QAAQ,MAAM,IAAI;CACzE,OAAO;EACL,UAAU,WAA0B;GAClC,IAAI;IACF,SAAS,YAAY,MAAM;GAC7B,QAAQ,CAER;EACF;EACA,WAAW,UAAU;EACrB,aAAa;GACX,UAAU,MAAM;GAChB,SAAS,MAAM;GACf,UAAU;EACZ;CACF;AACF;;;;;;AAOA,IAAa,0BACX,MACA,MAAc,mBACC;CACf,MAAM,YAAY,YAAY;CAC9B,IAAI,OAAO;CACX,IAAI,OAAO;CACX,MAAM,aAAa,UAA8B;EAC/C,IAAI,MAAM,QAAQ,OAAO,MAAM,aAAa,MAAM;EAClD,IAAI;EACJ,IAAI;GACF,UAAW,KAAK,MAAM,MAAM,QAAQ,CAAC,EAA2C;EAClF,QAAQ;GACN;EACF;EACA,UAAU,QAAQ,OAAO;CAC3B;CACA,KAAK,iBAAiB,WAAW,SAAS;CAC1C,OAAO;EACL,UAAU,WAA0B;GAClC,IAAI,CAAC,MAAM;GACX,IAAI;IACF,QAAQ;IACR,KAAK,aAAa,QAAQ,KAAK,KAAK,UAAU;KAAE;KAAQ,OAAO,GAAG,KAAK,IAAI,EAAE,GAAG,KAAK,GAAG,KAAK,OAAO;IAAI,CAAC,CAAC;IAC1G,KAAK,aAAa,WAAW,GAAG;GAClC,QAAQ,CAER;EACF;EACA,WAAW,UAAU;EACrB,aAAa;GACX,OAAO;GACP,UAAU,MAAM;GAChB,KAAK,oBAAoB,WAAW,SAAS;EAC/C;CACF;AACF;;AAGA,IAAM,oBAAgC;CAAE,eAAe,CAAC;CAAG,uBAAuB,CAAC;CAAG,aAAa,CAAC;AAAE;;AAGtG,IAAa,kBAAkB,OAAuB,WAAuB;CAC3E,IAAI,OAAO,KAAK,qBAAqB,YAAY,OAAO,oBAAoB,KAAK,gBAAgB;CACjG,IAAI;EAEF,IAAI,OAAO,KAAK,cAAc,YAAY,YAAY,OAAO,uBAAuB,IAAI;CAC1F,QAAQ,CAER;CACA,OAAO,WAAW;AACpB"}

package/dist/browser/index.d.ts

@@ -0,0 +1,18 @@
+import type { SystemEnvironment } from '../preferences.js';
+import { type Storage, type StorageOptions } from '../storage.js';
+import { type IndexedDbOptions } from './indexeddb.js';
+export { broadcastChangeFeed, CHANGE_CHANNEL, openChangeFeed, storageEventChangeFeed, type ChangeFeedHost, } from './changes.js';
+export { DATABASE_UPGRADES, openIndexedDbBackend, toStorageError, type DatabaseUpgrade, type IndexedDbOptions, } from './indexeddb.js';
+export { estimateStorage, isStoragePersisted, requestPersistentStorage, type PersistResult, type StorageManagerLike, } from './persist.js';
+/**
+ * Opens storage over IndexedDB, with a change feed (`openChangeFeed`) that keeps other tabs'
+ * preferences in step; pass `changes` to use another. Where IndexedDB is missing or refused
+ * (some private modes, blocked site data), it falls back to memory so the site still works,
+ * and sends an `Unavailable` notice: progress lasts only until the tab closes. Memory isn't
+ * shared between tabs, so that storage has no change feed.
+ */
+export declare const openBrowserStorage: (options?: Omit<StorageOptions, "backend"> & {
+    readonly indexedDb?: IndexedDbOptions;
+}) => Promise<Storage>;
+/** Reads the system settings that `resolvePreferences` falls back on. */
+export declare const systemEnvironment: (view?: Window) => SystemEnvironment;

package/dist/browser/index.js

@@ -0,0 +1,44 @@
+import { MESSAGES } from "../backend.js";
+import { CHANGE_CHANNEL, broadcastChangeFeed, openChangeFeed, storageEventChangeFeed } from "./changes.js";
+import { createMemoryBackend } from "../memory.js";
+import { openStorage } from "../storage.js";
+import { DATABASE_UPGRADES, openIndexedDbBackend, toStorageError } from "./indexeddb.js";
+import { estimateStorage, isStoragePersisted, requestPersistentStorage } from "./persist.js";
+//#region src/browser/index.ts
+/**
+* Opens storage over IndexedDB, with a change feed (`openChangeFeed`) that keeps other tabs'
+* preferences in step; pass `changes` to use another. Where IndexedDB is missing or refused
+* (some private modes, blocked site data), it falls back to memory so the site still works,
+* and sends an `Unavailable` notice: progress lasts only until the tab closes. Memory isn't
+* shared between tabs, so that storage has no change feed.
+*/
+var openBrowserStorage = async (options = {}) => {
+	const backend = await openIndexedDbBackend(options.indexedDb);
+	if (backend.ok) return openStorage({
+		...options,
+		backend: backend.value,
+		changes: options.changes ?? openChangeFeed()
+	});
+	options.onNotice?.({
+		code: "Unavailable",
+		message: MESSAGES.Unavailable,
+		store: null,
+		key: null,
+		issues: [`${backend.error.code}: ${String(backend.error.detail ?? backend.error.message)}`]
+	});
+	const { changes: _unshared, ...rest } = options;
+	return openStorage({
+		...rest,
+		backend: createMemoryBackend()
+	});
+};
+/** Reads the system settings that `resolvePreferences` falls back on. */
+var systemEnvironment = (view = window) => ({
+	prefersReducedMotion: view.matchMedia("(prefers-reduced-motion: reduce)").matches,
+	prefersDark: view.matchMedia("(prefers-color-scheme: dark)").matches,
+	locale: view.navigator.language
+});
+//#endregion
+export { CHANGE_CHANNEL, DATABASE_UPGRADES, broadcastChangeFeed, estimateStorage, isStoragePersisted, openBrowserStorage, openChangeFeed, openIndexedDbBackend, requestPersistentStorage, storageEventChangeFeed, systemEnvironment, toStorageError };
+
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/browser/index.ts"],"sourcesContent":["// @joystyk/storage/browser: the browser-only parts. IndexedDB, persistent storage, and the\n// system settings that preferences resolve against.\nimport { createMemoryBackend } from '../memory.ts';\nimport { MESSAGES } from '../backend.ts';\nimport type { SystemEnvironment } from '../preferences.ts';\nimport { openStorage, type Storage, type StorageOptions } from '../storage.ts';\nimport { openChangeFeed } from './changes.ts';\nimport { openIndexedDbBackend, type IndexedDbOptions } from './indexeddb.ts';\n\nexport {\n  broadcastChangeFeed,\n  CHANGE_CHANNEL,\n  openChangeFeed,\n  storageEventChangeFeed,\n  type ChangeFeedHost,\n} from './changes.ts';\nexport {\n  DATABASE_UPGRADES,\n  openIndexedDbBackend,\n  toStorageError,\n  type DatabaseUpgrade,\n  type IndexedDbOptions,\n} from './indexeddb.ts';\nexport {\n  estimateStorage,\n  isStoragePersisted,\n  requestPersistentStorage,\n  type PersistResult,\n  type StorageManagerLike,\n} from './persist.ts';\n\n/**\n * Opens storage over IndexedDB, with a change feed (`openChangeFeed`) that keeps other tabs'\n * preferences in step; pass `changes` to use another. Where IndexedDB is missing or refused\n * (some private modes, blocked site data), it falls back to memory so the site still works,\n * and sends an `Unavailable` notice: progress lasts only until the tab closes. Memory isn't\n * shared between tabs, so that storage has no change feed.\n */\nexport const openBrowserStorage = async (\n  options: Omit<StorageOptions, 'backend'> & { readonly indexedDb?: IndexedDbOptions } = {},\n): Promise<Storage> => {\n  const backend = await openIndexedDbBackend(options.indexedDb);\n  if (backend.ok)\n    return openStorage({ ...options, backend: backend.value, changes: options.changes ?? openChangeFeed() });\n  options.onNotice?.({\n    code: 'Unavailable',\n    message: MESSAGES.Unavailable,\n    store: null,\n    key: null,\n    issues: [`${backend.error.code}: ${String(backend.error.detail ?? backend.error.message)}`],\n  });\n  const { changes: _unshared, ...rest } = options;\n  return openStorage({ ...rest, backend: createMemoryBackend() });\n};\n\n/** Reads the system settings that `resolvePreferences` falls back on. */\nexport const systemEnvironment = (view: Window = window): SystemEnvironment => ({\n  prefersReducedMotion: view.matchMedia('(prefers-reduced-motion: reduce)').matches,\n  prefersDark: view.matchMedia('(prefers-color-scheme: dark)').matches,\n  locale: view.navigator.language,\n});\n"],"mappings":";;;;;;;;;;;;;;AAsCA,IAAa,qBAAqB,OAChC,UAAuF,CAAC,MACnE;CACrB,MAAM,UAAU,MAAM,qBAAqB,QAAQ,SAAS;CAC5D,IAAI,QAAQ,IACV,OAAO,YAAY;EAAE,GAAG;EAAS,SAAS,QAAQ;EAAO,SAAS,QAAQ,WAAW,eAAe;CAAE,CAAC;CACzG,QAAQ,WAAW;EACjB,MAAM;EACN,SAAS,SAAS;EAClB,OAAO;EACP,KAAK;EACL,QAAQ,CAAC,GAAG,QAAQ,MAAM,KAAK,IAAI,OAAO,QAAQ,MAAM,UAAU,QAAQ,MAAM,OAAO,GAAG;CAC5F,CAAC;CACD,MAAM,EAAE,SAAS,WAAW,GAAG,SAAS;CACxC,OAAO,YAAY;EAAE,GAAG;EAAM,SAAS,oBAAoB;CAAE,CAAC;AAChE;;AAGA,IAAa,qBAAqB,OAAe,YAA+B;CAC9E,sBAAsB,KAAK,WAAW,kCAAkC,CAAC,CAAC;CAC1E,aAAa,KAAK,WAAW,8BAA8B,CAAC,CAAC;CAC7D,QAAQ,KAAK,UAAU;AACzB"}

package/dist/browser/indexeddb.d.ts

@@ -0,0 +1,40 @@
+import { type Result } from '@joystyk/contracts';
+import { type StorageBackend, type StorageError } from '../backend.js';
+/** One step of the database's own schema: which object stores exist. */
+export type DatabaseUpgrade = {
+    /** The database version this step produces, from 1, with no gaps. */
+    readonly version: number;
+    /** Runs inside the `versionchange` transaction. Create or delete object stores here. */
+    upgrade(db: IDBDatabase, transaction: IDBTransaction): void;
+};
+/**
+ * The database schema, oldest first. Record shapes are versioned per record (see
+ * `RecordKind`); this list changes only when an object store is added or removed.
+ */
+export declare const DATABASE_UPGRADES: readonly DatabaseUpgrade[];
+export type IndexedDbOptions = {
+    /** Defaults to "joystyk". */
+    readonly name?: string;
+    /** Defaults to the global `indexedDB`. */
+    readonly factory?: IDBFactory;
+    /** Defaults to `DATABASE_UPGRADES`. */
+    readonly upgrades?: readonly DatabaseUpgrade[];
+    /**
+     * Another tab holds an older connection open, so the upgrade waits. The frame can ask the
+     * player to close other tabs of the site.
+     */
+    readonly onBlocked?: () => void;
+    /**
+     * Another tab needs a newer database version. This connection closes so that tab can
+     * upgrade, and later operations fail with `Unavailable`; the frame should offer a reload.
+     */
+    readonly onVersionChange?: () => void;
+};
+/** Maps a DOMException (or anything thrown) to a StorageError. */
+export declare const toStorageError: (cause: unknown) => StorageError;
+/**
+ * Opens (creating or upgrading) the database and returns a backend over it. Runs every
+ * upgrade step newer than the stored version, in order, inside one `versionchange`
+ * transaction. Resolves to `Unavailable` where IndexedDB is missing or refused.
+ */
+export declare const openIndexedDbBackend: (options?: IndexedDbOptions) => Promise<Result<StorageBackend, StorageError>>;