@arcadekit/save 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Thevenet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @arcadekit/save
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A game's save: records by id (a level's best moves, a hero's best run) under one versioned storage key. Each write re-reads the stored save and merges, so another tab's record isn't lost. A corrupt save is backed up and read as empty, and storage failures are logged rather than raised, so play goes on. `BrowserSaveStorage` in `@arcadekit/save/browser` stores it in localStorage, or in memory if the browser refuses.
+
+Part of [arcadekit](https://github.com/lucasthevenet/arcadekit#readme). The root entry is DOM-free.
+
+## Install
+
+```bash
+pnpm add @arcadekit/save effect @effect/platform-browser
+```
+
+Peer dependencies: `effect` (~4.1), and `@effect/platform-browser` (~4.1) for `@arcadekit/save/browser` only.
+
+## Example
+
+Solved levels with their best move count (from the push-puzzle demo):
+
+```ts
+import { makeSaveStore } from "@arcadekit/save";
+import { BrowserSaveStorage } from "@arcadekit/save/browser";
+import { Effect, Schema } from "effect";
+
+const LevelRecord = Schema.Struct({
+  solved: Schema.Boolean,
+  bestMoves: Schema.Int,
+});
+type LevelRecord = typeof LevelRecord.Type;
+
+/** The best of both: solved if either says so, with the fewer moves. */
+const mergeRecord = (a: LevelRecord, b: LevelRecord): LevelRecord =>
+  !a.solved
+    ? b
+    : !b.solved
+      ? a
+      : { solved: true, bestMoves: Math.min(a.bestMoves, b.bestMoves) };
+
+export const recordSolve = (levelId: string, moves: number) =>
+  Effect.gen(function* () {
+    const store = yield* makeSaveStore({
+      key: "my-studio/my-game/save",
+      field: "levels",
+      record: LevelRecord,
+      mergeRecord,
+    });
+    // Neither call fails. `merge` returns the merged records.
+    return yield* store.merge({
+      [levelId]: { solved: true, bestMoves: moves },
+    });
+  }).pipe(Effect.provide(BrowserSaveStorage));
+```
+
+The store works over any Effect `KeyValueStore`, so tests use `KeyValueStore.layerMemory`. See [ADR-0009](https://github.com/lucasthevenet/arcadekit/blob/main/docs/adr/0009-a-save-package-is-earned.md).

package/dist/browser.d.ts

@@ -0,0 +1,8 @@
+import { Layer } from "effect";
+import { KeyValueStore } from "effect/persistence";
+/**
+ * The browser's localStorage. If the browser won't give access to it, the
+ * save lives in memory for this session instead, so the app still loads.
+ */
+export declare const BrowserSaveStorage: Layer.Layer<KeyValueStore.KeyValueStore>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","names":[],"sources":["../src/browser.ts"],"mappings":";;;;;;qBAWa,oBAAoB,MAAM,MAAM,cAAc"}

package/dist/browser.js

@@ -0,0 +1,12 @@
+import { Effect, Layer } from "effect";
+import { KeyValueStore } from "effect/persistence";
+import * as BrowserKeyValueStore from "@effect/platform-browser/BrowserKeyValueStore";
+// src/browser.ts
+/**
+* The browser's localStorage. If the browser won't give access to it, the
+* save lives in memory for this session instead, so the app still loads.
+*/
+const BrowserSaveStorage = BrowserKeyValueStore.layerLocalStorage.pipe(Layer.catchCause((cause) => Layer.merge(KeyValueStore.layerMemory, Layer.effectDiscard(Effect.logWarning("localStorage isn't available. Saved progress lasts this session only.", cause)))));
+export { BrowserSaveStorage };
+
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","names":[],"sources":["../src/browser.ts"],"sourcesContent":["import * as BrowserKeyValueStore from \"@effect/platform-browser/BrowserKeyValueStore\";\nimport { Effect, Layer } from \"effect\";\nimport { KeyValueStore } from \"effect/persistence\";\n\n// Storage that needs a browser. Kept out of the root entry so the save logic\n// can be checked and tested without DOM types.\n\n/**\n * The browser's localStorage. If the browser won't give access to it, the\n * save lives in memory for this session instead, so the app still loads.\n */\nexport const BrowserSaveStorage: Layer.Layer<KeyValueStore.KeyValueStore> =\n  BrowserKeyValueStore.layerLocalStorage.pipe(\n    Layer.catchCause((cause) =>\n      Layer.merge(\n        KeyValueStore.layerMemory,\n        Layer.effectDiscard(\n          Effect.logWarning(\n            \"localStorage isn't available. Saved progress lasts this session only.\",\n            cause\n          )\n        )\n      )\n    )\n  );\n"],"mappings":";;;;;;;;AAWA,MAAa,qBACX,qBAAqB,kBAAkB,KACrC,MAAM,YAAY,UAChB,MAAM,MACJ,cAAc,aACd,MAAM,cACJ,OAAO,WACL,yEACA,KACF,CACF,CACF,CACF,CACF"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { Effect, Schema } from "effect";
+import { KeyValueStore } from "effect/persistence";
+/** Records by id. Ids the content no longer has are kept. */
+type Records<R> = Readonly<Record<string, R>>;
+/** What a game passes in: where its save lives, what one record holds, and how two records merge. */
+interface SaveDefinition<R, E = R> {
+  /** The game's storage key, such as `my-studio/<game>/save`. A save that can't be read is copied to `<key>/corrupt`. */
+  readonly key: string;
+  /** The field of the stored save that holds the records, such as `levels` or `heroes`. */
+  readonly field: string;
+  /** One record's Schema. */
+  readonly record: Schema.Codec<R, E>;
+  /** Two records for the same id, as one. Usually the best of both. */
+  readonly mergeRecord: (a: R, b: R) => R;
+}
+/** A game's save over a `KeyValueStore`. Neither method fails: storage problems are logged and play goes on. */
+interface SaveStore<R> {
+  /** The stored records. A missing save is empty. A corrupt or unknown-version one is backed up, logged and read as empty. */
+  readonly load: Effect.Effect<Records<R>>;
+  /**
+   * Merges `records` into the save. Re-reads the stored save first, so a record
+   * another tab wrote isn't lost. Returns the merged records, even when the
+   * write fails (that is logged and dropped).
+   */
+  readonly merge: (records: Records<R>) => Effect.Effect<Records<R>>;
+}
+/**
+ * Merges two sets of records by id. Ids only one side has are kept; ids on
+ * both sides go through `mergeRecord(a, b)`.
+ */
+export declare const mergeRecords: <R>(mergeRecord: (a: R, b: R) => R) => (a: Records<R>, b: Records<R>) => Records<R>;
+/** Builds a game's save over the `KeyValueStore` in context. */
+export declare const makeSaveStore: <R, E>(definition: SaveDefinition<R, E>) => Effect.Effect<SaveStore<R>, never, KeyValueStore.KeyValueStore>;
+export type { Records, SaveDefinition, SaveStore };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/save.ts"],"mappings":";;;KAUY,QAAQ,KAAK,SAAS,eAAe;;UAGhC,eAAe,GAAG,IAAI;;WAE5B;;WAEA;;WAEA,QAAQ,OAAO,MAAM,GAAG;;WAExB,cAAc,GAAG,GAAG,GAAG,MAAM;;;UAIvB,UAAU;;WAEhB,MAAM,OAAO,OAAO,QAAQ;;;;;;WAM5B,QAAQ,SAAS,QAAQ,OAAO,OAAO,OAAO,QAAQ;;;;;;qBAUpD,eACV,GAAG,cAAc,GAAG,GAAG,GAAG,MAAM,OAChC,GAAG,QAAQ,IAAI,GAAG,QAAQ,OAAK,QAAQ;;qBA6B7B,gBAAiB,GAAG,GAC/B,YAAY,eAAe,GAAG,OAC7B,OAAO,OAAO,UAAU,WAAW,cAAc"}

package/dist/index.js

@@ -0,0 +1,51 @@
+import { Effect, Option, Schema } from "effect";
+import { KeyValueStore } from "effect/persistence";
+// src/save.ts
+/** Where a save that fails to decode (corrupt, or an unknown version) is copied before it is dropped. */
+const backupKey = (key) => `${key}/corrupt`;
+/**
+* Merges two sets of records by id. Ids only one side has are kept; ids on
+* both sides go through `mergeRecord(a, b)`.
+*/
+const mergeRecords = (mergeRecord) => (a, b) => Object.fromEntries([...Object.entries(a).filter(([id]) => !Object.hasOwn(b, id)), ...Object.entries(b).map(([id, record]) => {
+	const other = Object.hasOwn(a, id) ? a[id] : void 0;
+	return [id, other === void 0 ? record : mergeRecord(other, record)];
+})]);
+const storedSchema = (field, record) => Schema.Struct({
+	version: Schema.Literal(1),
+	records: Schema.Record(Schema.String, record)
+}).pipe(Schema.encodeKeys({ records: field }));
+/** Builds a game's save over the `KeyValueStore` in context. */
+const makeSaveStore = (definition) => Effect.gen(function* () {
+	const { key } = definition;
+	const backup = backupKey(key);
+	const empty = {};
+	const merge = mergeRecords(definition.mergeRecord);
+	const store = yield* KeyValueStore.KeyValueStore;
+	const saves = KeyValueStore.toSchemaStore(store, storedSchema(definition.field, definition.record));
+	const backUp = Effect.gen(function* () {
+		const raw = yield* store.get(key);
+		if (raw !== void 0) {
+			yield* store.set(backup, raw);
+			yield* store.remove(key);
+		}
+	});
+	const load = saves.get(key).pipe(Effect.map(Option.match({
+		onNone: () => empty,
+		onSome: (stored) => stored.records
+	})), Effect.catchTag("SchemaError", (error) => Effect.logWarning(`The save can't be read. It is copied to ${backup} and play starts from an empty save.`, error.message).pipe(Effect.andThen(backUp), Effect.as(empty))), Effect.catchTag("KeyValueStoreError", (error) => Effect.logWarning("The save can't be read. Play starts from an empty save.", error.message).pipe(Effect.as(empty))));
+	return {
+		load,
+		merge: (records) => Effect.gen(function* () {
+			const merged = merge(yield* load, records);
+			yield* saves.set(key, {
+				version: 1,
+				records: merged
+			}).pipe(Effect.catch((error) => Effect.logWarning("The save can't be written.", error.message)));
+			return merged;
+		})
+	};
+});
+export { makeSaveStore, mergeRecords };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/save.ts"],"sourcesContent":["import { Effect, Option, Schema } from \"effect\";\nimport { KeyValueStore } from \"effect/persistence\";\n\n// A save: what a game keeps between sessions, as records by id (a level's best\n// move count, a hero's best time). It is UI state, not simulation state. The\n// game says what one record holds and how two records for the same id merge;\n// this module keeps the stored shape, the keys, and what to do when storage\n// fails, so neither method fails.\n\n/** Records by id. Ids the content no longer has are kept. */\nexport type Records<R> = Readonly<Record<string, R>>;\n\n/** What a game passes in: where its save lives, what one record holds, and how two records merge. */\nexport interface SaveDefinition<R, E = R> {\n  /** The game's storage key, such as `my-studio/<game>/save`. A save that can't be read is copied to `<key>/corrupt`. */\n  readonly key: string;\n  /** The field of the stored save that holds the records, such as `levels` or `heroes`. */\n  readonly field: string;\n  /** One record's Schema. */\n  readonly record: Schema.Codec<R, E>;\n  /** Two records for the same id, as one. Usually the best of both. */\n  readonly mergeRecord: (a: R, b: R) => R;\n}\n\n/** A game's save over a `KeyValueStore`. Neither method fails: storage problems are logged and play goes on. */\nexport interface SaveStore<R> {\n  /** The stored records. A missing save is empty. A corrupt or unknown-version one is backed up, logged and read as empty. */\n  readonly load: Effect.Effect<Records<R>>;\n  /**\n   * Merges `records` into the save. Re-reads the stored save first, so a record\n   * another tab wrote isn't lost. Returns the merged records, even when the\n   * write fails (that is logged and dropped).\n   */\n  readonly merge: (records: Records<R>) => Effect.Effect<Records<R>>;\n}\n\n/** Where a save that fails to decode (corrupt, or an unknown version) is copied before it is dropped. */\nconst backupKey = (key: string): string => `${key}/corrupt`;\n\n/**\n * Merges two sets of records by id. Ids only one side has are kept; ids on\n * both sides go through `mergeRecord(a, b)`.\n */\nexport const mergeRecords =\n  <R>(mergeRecord: (a: R, b: R) => R) =>\n  (a: Records<R>, b: Records<R>): Records<R> =>\n    Object.fromEntries([\n      ...Object.entries(a).filter(([id]) => !Object.hasOwn(b, id)),\n      ...Object.entries(b).map(([id, record]): [string, R] => {\n        const other = Object.hasOwn(a, id) ? a[id] : undefined;\n        return [id, other === undefined ? record : mergeRecord(other, record)];\n      }),\n    ]);\n\n/**\n * The stored shape is `{ version: 1, [field]: records }`. Every save is at\n * version 1 so far. When a game first changes its record shape, add the new\n * version here as a Union member with a way to turn the old into the new.\n */\ninterface StoredSave<R> {\n  readonly version: 1;\n  readonly records: Records<R>;\n}\n\nconst storedSchema = <R, E>(\n  field: string,\n  record: Schema.Codec<R, E>\n): Schema.Codec<StoredSave<R>, unknown> =>\n  Schema.Struct({\n    version: Schema.Literal(1),\n    records: Schema.Record(Schema.String, record),\n  }).pipe(Schema.encodeKeys({ records: field }));\n\n/** Builds a game's save over the `KeyValueStore` in context. */\nexport const makeSaveStore = <R, E>(\n  definition: SaveDefinition<R, E>\n): Effect.Effect<SaveStore<R>, never, KeyValueStore.KeyValueStore> =>\n  Effect.gen(function* () {\n    const { key } = definition;\n    const backup = backupKey(key);\n    const empty: Records<R> = {};\n    const merge = mergeRecords(definition.mergeRecord);\n    const store = yield* KeyValueStore.KeyValueStore;\n    const saves = KeyValueStore.toSchemaStore(\n      store,\n      storedSchema(definition.field, definition.record)\n    );\n\n    // Copies the unreadable value to the backup key and removes it, so it is backed up once.\n    const backUp = Effect.gen(function* () {\n      const raw = yield* store.get(key);\n      if (raw !== undefined) {\n        yield* store.set(backup, raw);\n        yield* store.remove(key);\n      }\n    });\n\n    const load: Effect.Effect<Records<R>> = saves.get(key).pipe(\n      Effect.map(\n        Option.match({\n          onNone: () => empty,\n          onSome: (stored) => stored.records,\n        })\n      ),\n      Effect.catchTag(\"SchemaError\", (error) =>\n        Effect.logWarning(\n          `The save can't be read. It is copied to ${backup} and play starts from an empty save.`,\n          error.message\n        ).pipe(Effect.andThen(backUp), Effect.as(empty))\n      ),\n      Effect.catchTag(\"KeyValueStoreError\", (error) =>\n        Effect.logWarning(\n          \"The save can't be read. Play starts from an empty save.\",\n          error.message\n        ).pipe(Effect.as(empty))\n      )\n    );\n\n    return {\n      load,\n      merge: (records) =>\n        Effect.gen(function* () {\n          const merged = merge(yield* load, records);\n          yield* saves\n            .set(key, { version: 1, records: merged })\n            .pipe(\n              Effect.catch((error) =>\n                Effect.logWarning(\"The save can't be written.\", error.message)\n              )\n            );\n          return merged;\n        }),\n    };\n  });\n"],"mappings":";;;;AAqCA,MAAM,aAAa,QAAwB,GAAG,IAAI;;;;;AAMlD,MAAa,gBACP,iBACH,GAAe,MACd,OAAO,YAAY,CACjB,GAAG,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,OAAO,GAAG,EAAE,CAAC,GAC3D,GAAG,OAAO,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,YAAyB;CACtD,MAAM,QAAQ,OAAO,OAAO,GAAG,EAAE,IAAI,EAAE,MAAM,KAAA;CAC7C,OAAO,CAAC,IAAI,UAAU,KAAA,IAAY,SAAS,YAAY,OAAO,MAAM,CAAC;AACvE,CAAC,CACH,CAAC;AAYL,MAAM,gBACJ,OACA,WAEA,OAAO,OAAO;CACZ,SAAS,OAAO,QAAQ,CAAC;CACzB,SAAS,OAAO,OAAO,OAAO,QAAQ,MAAM;AAC9C,CAAC,CAAC,CAAC,KAAK,OAAO,WAAW,EAAE,SAAS,MAAM,CAAC,CAAC;;AAG/C,MAAa,iBACX,eAEA,OAAO,IAAI,aAAa;CACtB,MAAM,EAAE,QAAQ;CAChB,MAAM,SAAS,UAAU,GAAG;CAC5B,MAAM,QAAoB,CAAC;CAC3B,MAAM,QAAQ,aAAa,WAAW,WAAW;CACjD,MAAM,QAAQ,OAAO,cAAc;CACnC,MAAM,QAAQ,cAAc,cAC1B,OACA,aAAa,WAAW,OAAO,WAAW,MAAM,CAClD;CAGA,MAAM,SAAS,OAAO,IAAI,aAAa;EACrC,MAAM,MAAM,OAAO,MAAM,IAAI,GAAG;EAChC,IAAI,QAAQ,KAAA,GAAW;GACrB,OAAO,MAAM,IAAI,QAAQ,GAAG;GAC5B,OAAO,MAAM,OAAO,GAAG;EACzB;CACF,CAAC;CAED,MAAM,OAAkC,MAAM,IAAI,GAAG,CAAC,CAAC,KACrD,OAAO,IACL,OAAO,MAAM;EACX,cAAc;EACd,SAAS,WAAW,OAAO;CAC7B,CAAC,CACH,GACA,OAAO,SAAS,gBAAgB,UAC9B,OAAO,WACL,2CAA2C,OAAO,uCAClD,MAAM,OACR,CAAC,CAAC,KAAK,OAAO,QAAQ,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC,CACjD,GACA,OAAO,SAAS,uBAAuB,UACrC,OAAO,WACL,2DACA,MAAM,OACR,CAAC,CAAC,KAAK,OAAO,GAAG,KAAK,CAAC,CACzB,CACF;CAEA,OAAO;EACL;EACA,QAAQ,YACN,OAAO,IAAI,aAAa;GACtB,MAAM,SAAS,MAAM,OAAO,MAAM,OAAO;GACzC,OAAO,MACJ,IAAI,KAAK;IAAE,SAAS;IAAG,SAAS;GAAO,CAAC,CAAC,CACzC,KACC,OAAO,OAAO,UACZ,OAAO,WAAW,8BAA8B,MAAM,OAAO,CAC/D,CACF;GACF,OAAO;EACT,CAAC;CACL;AACF,CAAC"}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@arcadekit/save",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Keep a game's records between sessions in a versioned, merging KeyValueStore save",
+  "keywords": [
+    "arcadekit",
+    "effect",
+    "game",
+    "gamedev",
+    "localstorage",
+    "save-game"
+  ],
+  "homepage": "https://github.com/lucasthevenet/arcadekit/tree/main/packages/save#readme",
+  "bugs": "https://github.com/lucasthevenet/arcadekit/issues",
+  "license": "MIT",
+  "author": "Lucas Thevenet",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucasthevenet/arcadekit.git",
+    "directory": "packages/save"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "source": "./src/browser.ts",
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@effect/platform-browser": "~4.1.0",
+    "effect": "~4.1.2"
+  },
+  "peerDependencies": {
+    "@effect/platform-browser": "~4.1.0",
+    "effect": "~4.1.2"
+  },
+  "peerDependenciesMeta": {
+    "@effect/platform-browser": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p . && tsc -p tsconfig.root.json"
+  }
 }

package/src/browser.ts

@@ -0,0 +1,25 @@
+import * as BrowserKeyValueStore from "@effect/platform-browser/BrowserKeyValueStore";
+import { Effect, Layer } from "effect";
+import { KeyValueStore } from "effect/persistence";
+
+// Storage that needs a browser. Kept out of the root entry so the save logic
+// can be checked and tested without DOM types.
+
+/**
+ * The browser's localStorage. If the browser won't give access to it, the
+ * save lives in memory for this session instead, so the app still loads.
+ */
+export const BrowserSaveStorage: Layer.Layer<KeyValueStore.KeyValueStore> =
+  BrowserKeyValueStore.layerLocalStorage.pipe(
+    Layer.catchCause((cause) =>
+      Layer.merge(
+        KeyValueStore.layerMemory,
+        Layer.effectDiscard(
+          Effect.logWarning(
+            "localStorage isn't available. Saved progress lasts this session only.",
+            cause
+          )
+        )
+      )
+    )
+  );

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  makeSaveStore,
+  mergeRecords,
+  type Records,
+  type SaveDefinition,
+  type SaveStore,
+} from "./save";

package/src/save.ts

@@ -0,0 +1,134 @@
+import { Effect, Option, Schema } from "effect";
+import { KeyValueStore } from "effect/persistence";
+
+// A save: what a game keeps between sessions, as records by id (a level's best
+// move count, a hero's best time). It is UI state, not simulation state. The
+// game says what one record holds and how two records for the same id merge;
+// this module keeps the stored shape, the keys, and what to do when storage
+// fails, so neither method fails.
+
+/** Records by id. Ids the content no longer has are kept. */
+export type Records<R> = Readonly<Record<string, R>>;
+
+/** What a game passes in: where its save lives, what one record holds, and how two records merge. */
+export interface SaveDefinition<R, E = R> {
+  /** The game's storage key, such as `my-studio/<game>/save`. A save that can't be read is copied to `<key>/corrupt`. */
+  readonly key: string;
+  /** The field of the stored save that holds the records, such as `levels` or `heroes`. */
+  readonly field: string;
+  /** One record's Schema. */
+  readonly record: Schema.Codec<R, E>;
+  /** Two records for the same id, as one. Usually the best of both. */
+  readonly mergeRecord: (a: R, b: R) => R;
+}
+
+/** A game's save over a `KeyValueStore`. Neither method fails: storage problems are logged and play goes on. */
+export interface SaveStore<R> {
+  /** The stored records. A missing save is empty. A corrupt or unknown-version one is backed up, logged and read as empty. */
+  readonly load: Effect.Effect<Records<R>>;
+  /**
+   * Merges `records` into the save. Re-reads the stored save first, so a record
+   * another tab wrote isn't lost. Returns the merged records, even when the
+   * write fails (that is logged and dropped).
+   */
+  readonly merge: (records: Records<R>) => Effect.Effect<Records<R>>;
+}
+
+/** Where a save that fails to decode (corrupt, or an unknown version) is copied before it is dropped. */
+const backupKey = (key: string): string => `${key}/corrupt`;
+
+/**
+ * Merges two sets of records by id. Ids only one side has are kept; ids on
+ * both sides go through `mergeRecord(a, b)`.
+ */
+export const mergeRecords =
+  <R>(mergeRecord: (a: R, b: R) => R) =>
+  (a: Records<R>, b: Records<R>): Records<R> =>
+    Object.fromEntries([
+      ...Object.entries(a).filter(([id]) => !Object.hasOwn(b, id)),
+      ...Object.entries(b).map(([id, record]): [string, R] => {
+        const other = Object.hasOwn(a, id) ? a[id] : undefined;
+        return [id, other === undefined ? record : mergeRecord(other, record)];
+      }),
+    ]);
+
+/**
+ * The stored shape is `{ version: 1, [field]: records }`. Every save is at
+ * version 1 so far. When a game first changes its record shape, add the new
+ * version here as a Union member with a way to turn the old into the new.
+ */
+interface StoredSave<R> {
+  readonly version: 1;
+  readonly records: Records<R>;
+}
+
+const storedSchema = <R, E>(
+  field: string,
+  record: Schema.Codec<R, E>
+): Schema.Codec<StoredSave<R>, unknown> =>
+  Schema.Struct({
+    version: Schema.Literal(1),
+    records: Schema.Record(Schema.String, record),
+  }).pipe(Schema.encodeKeys({ records: field }));
+
+/** Builds a game's save over the `KeyValueStore` in context. */
+export const makeSaveStore = <R, E>(
+  definition: SaveDefinition<R, E>
+): Effect.Effect<SaveStore<R>, never, KeyValueStore.KeyValueStore> =>
+  Effect.gen(function* () {
+    const { key } = definition;
+    const backup = backupKey(key);
+    const empty: Records<R> = {};
+    const merge = mergeRecords(definition.mergeRecord);
+    const store = yield* KeyValueStore.KeyValueStore;
+    const saves = KeyValueStore.toSchemaStore(
+      store,
+      storedSchema(definition.field, definition.record)
+    );
+
+    // Copies the unreadable value to the backup key and removes it, so it is backed up once.
+    const backUp = Effect.gen(function* () {
+      const raw = yield* store.get(key);
+      if (raw !== undefined) {
+        yield* store.set(backup, raw);
+        yield* store.remove(key);
+      }
+    });
+
+    const load: Effect.Effect<Records<R>> = saves.get(key).pipe(
+      Effect.map(
+        Option.match({
+          onNone: () => empty,
+          onSome: (stored) => stored.records,
+        })
+      ),
+      Effect.catchTag("SchemaError", (error) =>
+        Effect.logWarning(
+          `The save can't be read. It is copied to ${backup} and play starts from an empty save.`,
+          error.message
+        ).pipe(Effect.andThen(backUp), Effect.as(empty))
+      ),
+      Effect.catchTag("KeyValueStoreError", (error) =>
+        Effect.logWarning(
+          "The save can't be read. Play starts from an empty save.",
+          error.message
+        ).pipe(Effect.as(empty))
+      )
+    );
+
+    return {
+      load,
+      merge: (records) =>
+        Effect.gen(function* () {
+          const merged = merge(yield* load, records);
+          yield* saves
+            .set(key, { version: 1, records: merged })
+            .pipe(
+              Effect.catch((error) =>
+                Effect.logWarning("The save can't be written.", error.message)
+              )
+            );
+          return merged;
+        }),
+    };
+  });