origin-snapshot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rogo
+
+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

@@ -0,0 +1,99 @@
+# origin-snapshot
+
+Export and restore everything portable about a browser **origin** — `localStorage`,
+`sessionStorage`, `IndexedDB`, and `OPFS` — as a single, compact file.
+
+The output is a gzip-compressed binary container (`.galaxy`), **not** JSON.
+Binary payloads (IndexedDB blobs, OPFS game/emulator saves) are stored as raw
+bytes and the whole thing is gzipped, so there's no base64 inflation and gzip
+de-duplicates across files. That makes it the smallest practical representation
+you can build in the browser with zero dependencies. (Brotli would be a touch
+smaller, but `CompressionStream` only ships `gzip`/`deflate`.)
+
+## What's included
+
+| Included                                | Skipped (and why)                                         |
+| --------------------------------------- | --------------------------------------------------------- |
+| `localStorage`                          | Cache API — huge, regenerable proxied assets              |
+| `sessionStorage` (opt-in)               | Service-worker registrations — re-register automatically  |
+| `IndexedDB` (schema + records)          | Real/HttpOnly cookies — invisible to JS                   |
+| `OPFS` (full file tree)                 | Push subscriptions / background sync — device-bound       |
+| Proxied cookies (ride along in storage) | Permissions / WebAuthn / passkeys — origin + device bound |
+
+## Install
+
+```sh
+npm install origin-snapshot
+```
+
+Browser-only (it needs `localStorage`, `indexedDB`, OPFS, and `CompressionStream`).
+Ships as ESM source — no build step.
+
+## Usage
+
+```js
+import {
+  downloadSnapshot,
+  exportOrigin,
+  importOrigin,
+  readManifest,
+} from "origin-snapshot";
+
+// One-liner: build the snapshot and trigger a download.
+await downloadSnapshot(); // example.com-2026-06-28.galaxy
+
+// Or get the Blob yourself (upload it, store it, etc.).
+const blob = await exportOrigin({ sessionStorage: true });
+
+// Later — on the same origin — restore it.
+const file = await pickFile(); // <input type="file">
+await importOrigin(file); // wipes + restores each section by default
+
+// Peek at metadata without restoring.
+const manifest = await readManifest(file);
+console.log(manifest.origin, manifest.createdAt);
+```
+
+## API
+
+### `exportOrigin(options?) => Promise<Blob>`
+
+| option           | default | description                                                           |
+| ---------------- | ------- | --------------------------------------------------------------------- |
+| `localStorage`   | `true`  | include `localStorage`                                                |
+| `sessionStorage` | `false` | include `sessionStorage` (clears on tab close)                        |
+| `indexedDB`      | `true`  | include all IndexedDB databases                                       |
+| `opfs`           | `true`  | include the OPFS file tree                                            |
+| `databases`      | —       | explicit IndexedDB names for browsers without `indexedDB.databases()` |
+
+### `importOrigin(source, options?) => Promise<manifest>`
+
+`source` may be a `Blob`/`File`, `ArrayBuffer`, or `Uint8Array`.
+
+| option  | default | description                                          |
+| ------- | ------- | ---------------------------------------------------- |
+| `clear` | `true`  | wipe each section before restoring (`false` = merge) |
+
+### `downloadSnapshot(options?) => Promise<Blob>`
+
+`exportOrigin` plus a browser download. Accepts every `exportOrigin` option, plus
+`filename`.
+
+### `readManifest(source) => Promise<manifest>`
+
+Returns the snapshot metadata (`format`, `version`, `createdAt`, `origin`,
+`sections`) without touching local storage.
+
+## Notes & limits
+
+- **Same-origin restore.** IndexedDB and OPFS are origin-scoped; restore on the
+  origin the snapshot came from.
+- **Close other tabs before restoring.** Recreating an IndexedDB database needs
+  an exclusive connection; another open tab can block it.
+- **Round-trips structured-clone types** — `Date`, `Blob`, `File`, `ArrayBuffer`,
+  typed arrays, `Map`, `Set`, `RegExp`, `bigint`, `undefined`, `NaN`/`Infinity`.
+  Circular references are rejected with a clear error.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+	"name": "origin-snapshot",
+	"version": "0.1.0",
+	"description": "Export and restore a browser origin's localStorage, sessionStorage, IndexedDB, and OPFS as a single gzip-compressed snapshot file.",
+	"keywords": [
+		"localstorage",
+		"sessionstorage",
+		"indexeddb",
+		"opfs",
+		"origin",
+		"export",
+		"import",
+		"backup",
+		"snapshot",
+		"migration"
+	],
+	"license": "MIT",
+	"author": "rogo",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./src/index.d.ts",
+			"import": "./src/index.js"
+		}
+	},
+	"main": "./src/index.js",
+	"types": "./src/index.d.ts",
+	"files": [
+		"src"
+	],
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"module": "./src/index.js",
+	"sideEffects": false
+}

package/src/container.js

@@ -0,0 +1,97 @@
+const MAGIC = 'GLXYSNAP';
+const CONTAINER_VERSION = 1;
+const FLAG_GZIP = 1;
+const HEADER_SIZE = 10;
+
+/**
+ * @param {object} manifest
+ * @param {Array<Blob | Uint8Array>} bin
+ * @returns {Promise<Blob>}
+ */
+export async function encodeContainer(manifest, bin) {
+	const manifestBytes = new TextEncoder().encode(JSON.stringify(manifest));
+	checkLength(manifestBytes.length, 'manifest');
+
+	const parts = [u32le(manifestBytes.length), manifestBytes];
+	for (const part of bin) {
+		const size = part instanceof Blob ? part.size : part.byteLength;
+		checkLength(size, 'payload');
+		parts.push(u32le(size), part);
+	}
+	const body = new Blob(parts);
+
+	let flags = 0;
+	let payload = body;
+	if (typeof CompressionStream !== 'undefined') {
+		payload = await new Response(body.stream().pipeThrough(new CompressionStream('gzip'))).blob();
+		flags |= FLAG_GZIP;
+	}
+
+	const header = new Uint8Array(HEADER_SIZE);
+	for (let i = 0; i < 8; i++) header[i] = MAGIC.charCodeAt(i);
+	header[8] = CONTAINER_VERSION;
+	header[9] = flags;
+
+	return new Blob([header, payload], { type: 'application/octet-stream' });
+}
+
+/**
+ * @param {Blob} blob
+ * @returns {Promise<{ manifest: object, bin: Uint8Array[], containerVersion: number }>}
+ */
+export async function decodeContainer(blob) {
+	const header = new Uint8Array(await blob.slice(0, HEADER_SIZE).arrayBuffer());
+	if (header.byteLength < HEADER_SIZE) throw new Error('Not a Galaxy origin snapshot (truncated)');
+	for (let i = 0; i < 8; i++) {
+		if (header[i] !== MAGIC.charCodeAt(i))
+			throw new Error('Not a Galaxy origin snapshot (bad magic)');
+	}
+	const containerVersion = header[8];
+	const flags = header[9];
+
+	let bodyBlob = blob.slice(HEADER_SIZE);
+	if (flags & FLAG_GZIP) {
+		bodyBlob = await new Response(
+			bodyBlob.stream().pipeThrough(new DecompressionStream('gzip'))
+		).blob();
+	}
+
+	const buf = await bodyBlob.arrayBuffer();
+	const view = new DataView(buf);
+	let off = 0;
+
+	const manifestLen = view.getUint32(off, true);
+	off += 4;
+	const manifest = JSON.parse(new TextDecoder().decode(new Uint8Array(buf, off, manifestLen)));
+	off += manifestLen;
+
+	/** @type {Uint8Array[]} */
+	const bin = [];
+	while (off < buf.byteLength) {
+		const len = view.getUint32(off, true);
+		off += 4;
+		bin.push(new Uint8Array(buf, off, len)); // view — no copy
+		off += len;
+	}
+
+	return { manifest, bin, containerVersion };
+}
+
+const MAX_U32 = 0xffffffff;
+
+/**
+ * @param {number} length
+ * @param {string} what
+ */
+function checkLength(length, what) {
+	if (length > MAX_U32) {
+		throw new RangeError(`${what} is ${length} bytes, over the 4 GiB per-entry container limit`);
+	}
+}
+
+/** @param {number} n */
+function u32le(n) {
+	const b = new Uint8Array(4);
+	new DataView(b.buffer).setUint32(0, n, true);
+	return b;
+}

package/src/index.d.ts

@@ -0,0 +1,41 @@
+export interface ExportOptions {
+  localStorage?: boolean;
+  sessionStorage?: boolean;
+  indexedDB?: boolean;
+  opfs?: boolean;
+  /**
+   */
+  databases?: string[];
+}
+
+export interface ImportOptions {
+  clear?: boolean;
+}
+
+export interface SnapshotManifest {
+  format: "origin-snapshot";
+  version: number;
+  createdAt: string;
+  origin: string | null;
+  sections: {
+    localStorage?: Record<string, string>;
+    sessionStorage?: Record<string, string>;
+    indexedDB?: unknown[];
+    opfs?: unknown[];
+  };
+}
+
+export function exportOrigin(options?: ExportOptions): Promise<Blob>;
+
+export function importOrigin(
+  source: Blob | ArrayBuffer | Uint8Array,
+  options?: ImportOptions,
+): Promise<SnapshotManifest>;
+
+export function readManifest(
+  source: Blob | ArrayBuffer | Uint8Array,
+): Promise<SnapshotManifest>;
+
+export function downloadSnapshot(
+  options?: ExportOptions & { filename?: string },
+): Promise<Blob>;

package/src/index.js

@@ -0,0 +1,146 @@
+import { encodeContainer, decodeContainer } from "./container.js";
+import { dumpWebStorage, restoreWebStorage } from "./storage/webstorage.js";
+import { dumpDatabases, restoreDatabases } from "./storage/indexeddb.js";
+import { dumpOPFS, restoreOPFS } from "./storage/opfs.js";
+
+const FORMAT = "origin-snapshot";
+const SNAPSHOT_VERSION = 1;
+
+/**
+ * @typedef {object} ExportOptions
+ * @property {boolean} [localStorage=true]
+ * @property {boolean} [sessionStorage=false]
+ * @property {boolean} [indexedDB=true]
+ * @property {boolean} [opfs=true]
+ * @property {string[]} [databases]
+ *
+ */
+
+/**
+ *
+ *
+ * @param {ExportOptions} [options]
+ * @returns {Promise<Blob>}
+ */
+export async function exportOrigin(options = {}) {
+  const {
+    localStorage: doLocal = true,
+    sessionStorage: doSession = false,
+    indexedDB: doIDB = true,
+    opfs: doOPFS = true,
+    databases,
+  } = options;
+
+  /** @type {Array<Blob | Uint8Array>} */
+  const bin = [];
+  const sections = {};
+
+  if (doLocal && typeof localStorage !== "undefined") {
+    sections.localStorage = dumpWebStorage(localStorage);
+  }
+  if (doSession && typeof sessionStorage !== "undefined") {
+    sections.sessionStorage = dumpWebStorage(sessionStorage);
+  }
+  if (doIDB && typeof indexedDB !== "undefined") {
+    sections.indexedDB = await dumpDatabases(bin, databases);
+  }
+  if (doOPFS) {
+    const opfs = await dumpOPFS(bin);
+    if (opfs) sections.opfs = opfs;
+  }
+
+  const manifest = {
+    format: FORMAT,
+    version: SNAPSHOT_VERSION,
+    createdAt: new Date().toISOString(),
+    origin: typeof location !== "undefined" ? location.origin : null,
+    sections,
+  };
+
+  return encodeContainer(manifest, bin);
+}
+
+/**
+ * @typedef {object} ImportOptions
+ * @property {boolean} [clear=true]
+ */
+
+/**
+ * @param {Blob | ArrayBuffer | Uint8Array} source
+ * @param {ImportOptions} [options]
+ * @returns {Promise<object>} the snapshot manifest (metadata)
+ */
+
+export async function importOrigin(source, options = {}) {
+  const { clear = true } = options;
+  const blob = toBlob(source);
+  const { manifest, bin } = await decodeContainer(blob);
+
+  if (manifest.format !== FORMAT) {
+    throw new Error(`Unsupported snapshot format "${manifest.format}"`);
+  }
+  if (manifest.version > SNAPSHOT_VERSION) {
+    throw new Error(
+      `Snapshot version ${manifest.version} is newer than this library supports (${SNAPSHOT_VERSION})`,
+    );
+  }
+
+  const s = manifest.sections || {};
+  if (s.localStorage && typeof localStorage !== "undefined") {
+    restoreWebStorage(localStorage, s.localStorage, { clear });
+  }
+  if (s.sessionStorage && typeof sessionStorage !== "undefined") {
+    restoreWebStorage(sessionStorage, s.sessionStorage, { clear });
+  }
+  if (s.indexedDB && typeof indexedDB !== "undefined") {
+    await restoreDatabases(s.indexedDB, bin, { clear });
+  }
+  if (s.opfs) {
+    await restoreOPFS(s.opfs, bin, { clear });
+  }
+
+  return manifest;
+}
+
+/**
+ *
+ * @param {Blob | ArrayBuffer | Uint8Array} source
+ * @returns {Promise<object>}
+ */
+export async function readManifest(source) {
+  const { manifest } = await decodeContainer(toBlob(source));
+  return manifest;
+}
+
+/**
+ *
+ * @param {ExportOptions & { filename?: string }} [options]
+ * @returns {Promise<Blob>}
+ */
+export async function downloadSnapshot(options = {}) {
+  const { filename, ...exportOptions } = options;
+  const blob = await exportOrigin(exportOptions);
+  const name = filename || defaultFilename();
+
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = name;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 10_000);
+
+  return blob;
+}
+
+function defaultFilename() {
+  const date = new Date().toISOString().slice(0, 10);
+  const host = typeof location !== "undefined" ? location.hostname : "origin";
+  return `${host || "origin"}-${date}.galaxy`;
+}
+
+/** @param {Blob | ArrayBuffer | Uint8Array} source */
+function toBlob(source) {
+  return source instanceof Blob ? source : new Blob([source]);
+}

package/src/serialize.js

@@ -0,0 +1,165 @@
+const TAG = '~gsnap~';
+
+/**
+ * @param {*} value
+ * @param {Array<Blob | Uint8Array>} bin
+ * @param {WeakSet<object>} [seen] 
+ * @returns {*}
+ */
+export function serializeValue(value, bin, seen = new WeakSet()) {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === 'string' || type === 'boolean') return value;
+	if (type === 'number') {
+		if (Number.isNaN(value)) return tag('num', { v: 'NaN' });
+		if (value === Infinity) return tag('num', { v: 'Infinity' });
+		if (value === -Infinity) return tag('num', { v: '-Infinity' });
+		return value;
+	}
+	if (type === 'undefined') return tag('undef');
+	if (type === 'bigint') return tag('bigint', { v: value.toString() });
+
+	// Structured-clone object types.
+	if (value instanceof Date) return tag('date', { v: value.getTime() });
+	if (value instanceof RegExp) return tag('regexp', { src: value.source, flags: value.flags });
+
+	if (value instanceof ArrayBuffer) {
+		return tag('arraybuffer', { b: push(bin, new Uint8Array(value)) });
+	}
+	if (ArrayBuffer.isView(value)) {
+		const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+		return tag('view', { k: value.constructor.name, b: push(bin, bytes) });
+	}
+	if (typeof File !== 'undefined' && value instanceof File) {
+		return tag('file', {
+			b: push(bin, value),
+			name: value.name,
+			type: value.type,
+			lastModified: value.lastModified
+		});
+	}
+	if (typeof Blob !== 'undefined' && value instanceof Blob) {
+		return tag('blob', { b: push(bin, value), type: value.type });
+	}
+	if (type === 'object') {
+		if (seen.has(value)) {
+			throw new TypeError('Cannot serialize a value with a circular reference');
+		}
+		seen.add(value);
+		try {
+			if (value instanceof Map) {
+				return tag('map', {
+					v: [...value].map(([k, v]) => [
+						serializeValue(k, bin, seen),
+						serializeValue(v, bin, seen)
+					])
+				});
+			}
+			if (value instanceof Set) {
+				return tag('set', { v: [...value].map((v) => serializeValue(v, bin, seen)) });
+			}
+			if (Array.isArray(value)) {
+				return value.map((v) => serializeValue(v, bin, seen));
+			}
+			if (Object.prototype.hasOwnProperty.call(value, TAG)) {
+				return tag('object', {
+					e: Object.keys(value).map((k) => [k, serializeValue(value[k], bin, seen)])
+				});
+			}
+			const out = {};
+			for (const k of Object.keys(value)) out[k] = serializeValue(value[k], bin, seen);
+			return out;
+		} finally {
+			seen.delete(value);
+		}
+	}
+	throw new TypeError(`Cannot serialize value of type "${type}"`);
+}
+
+/**
+ * Inverse of {@link serializeValue}.
+ *
+ * @param {*} node
+ * @param {Array<Uint8Array>} bin
+ * @returns {*}
+ */
+export function deserializeValue(node, bin) {
+	if (node === null || typeof node !== 'object') return node;
+	if (Array.isArray(node)) return node.map((n) => deserializeValue(n, bin));
+
+	const t = node[TAG];
+	if (t === undefined) {
+		const out = {};
+		for (const k of Object.keys(node)) out[k] = deserializeValue(node[k], bin);
+		return out;
+	}
+
+	switch (t) {
+		case 'undef':
+			return undefined;
+		case 'num':
+			return Number(node.v);
+		case 'bigint':
+			return BigInt(node.v);
+		case 'date':
+			return new Date(node.v);
+		case 'regexp':
+			return new RegExp(node.src, node.flags);
+		case 'arraybuffer':
+			return copyBytes(bin[node.b]).buffer;
+		case 'view': {
+			const bytes = copyBytes(bin[node.b]);
+			if (node.k === 'DataView') return new DataView(bytes.buffer);
+			const Ctor = globalThis[node.k];
+			if (!Ctor) throw new Error(`Unknown typed-array constructor "${node.k}"`);
+			return new Ctor(bytes.buffer);
+		}
+		case 'blob':
+			return new Blob([bin[node.b]], { type: node.type });
+		case 'file':
+			return new File([bin[node.b]], node.name, {
+				type: node.type,
+				lastModified: node.lastModified
+			});
+		case 'map': {
+			const m = new Map();
+			for (const [k, v] of node.v) m.set(deserializeValue(k, bin), deserializeValue(v, bin));
+			return m;
+		}
+		case 'set': {
+			const s = new Set();
+			for (const v of node.v) s.add(deserializeValue(v, bin));
+			return s;
+		}
+		case 'object': {
+			const out = {};
+			for (const [k, v] of node.e) out[k] = deserializeValue(v, bin);
+			return out;
+		}
+		default:
+			throw new Error(`Unknown serialization tag "${t}"`);
+	}
+}
+
+/**
+ * @param {string} type
+ * @param {object} [extra]
+ */
+function tag(type, extra) {
+	return { [TAG]: type, ...extra };
+}
+
+/**
+ * @param {Array<Blob | Uint8Array>} bin
+ * @param {Blob | Uint8Array} part
+ * @returns {number}
+ */
+function push(bin, part) {
+	bin.push(part);
+	return bin.length - 1;
+}
+
+/** @param {Uint8Array} view */
+function copyBytes(view) {
+	return view.slice();
+}

package/src/storage/indexeddb.js

@@ -0,0 +1,211 @@
+import { serializeValue, deserializeValue } from '../serialize.js';
+
+/**
+ * @param {Array<Blob | Uint8Array>} bin
+ * @param {string[]} [names]
+ * @returns {Promise<object[]>}
+ */
+export async function dumpDatabases(bin, names) {
+	let list = names;
+	if (!list) {
+		list =
+			typeof indexedDB.databases === 'function'
+				? (await indexedDB.databases()).map((d) => d.name).filter(Boolean)
+				: [];
+	}
+
+	const dump = [];
+	for (const name of list) {
+		const db = await openExisting(name);
+		try {
+			const stores = [];
+			for (const storeName of [...db.objectStoreNames]) {
+				stores.push(await dumpStore(db, storeName, bin));
+			}
+			dump.push({ name: db.name, version: db.version, stores });
+		} finally {
+			db.close();
+		}
+	}
+	return dump;
+}
+
+/**
+ * @param {IDBDatabase} db
+ * @param {string} storeName
+ * @param {Array<Blob | Uint8Array>} bin
+ */
+async function dumpStore(db, storeName, bin) {
+	const tx = db.transaction(storeName, 'readonly');
+	const store = tx.objectStore(storeName);
+
+	const schema = {
+		name: storeName,
+		keyPath: store.keyPath, 
+		autoIncrement: store.autoIncrement,
+		indexes: [...store.indexNames].map((iname) => {
+			const ix = store.index(iname);
+			return { name: iname, keyPath: ix.keyPath, unique: ix.unique, multiEntry: ix.multiEntry };
+		})
+	};
+
+	const outOfLine = store.keyPath === null;
+	const values = await request(store.getAll());
+	const keys = outOfLine ? await request(store.getAllKeys()) : null;
+
+	const records = values.map((value, i) => {
+		const rec = { value: serializeValue(value, bin) };
+		if (outOfLine) rec.key = serializeValue(keys[i], bin);
+		return rec;
+	});
+
+	await transactionDone(tx);
+	return { ...schema, records };
+}
+
+/**
+ * @param {object[]} dump
+ * @param {Uint8Array[]} bin
+ * @param {{ clear?: boolean }} [options]
+ */
+export async function restoreDatabases(dump, bin, { clear = true } = {}) {
+	for (const dbInfo of dump) {
+		if (clear) await deleteDatabase(dbInfo.name);
+		const db = await openForRestore(dbInfo, clear);
+		try {
+			for (const storeInfo of dbInfo.stores) {
+				await restoreStore(db, storeInfo, bin);
+			}
+		} finally {
+			db.close();
+		}
+	}
+}
+
+/**
+ * @param {IDBDatabase} db
+ * @param {any} storeInfo
+ * @param {Uint8Array[]} bin
+ */
+async function restoreStore(db, storeInfo, bin) {
+	const tx = db.transaction(storeInfo.name, 'readwrite');
+	const store = tx.objectStore(storeInfo.name);
+	const inline = storeInfo.keyPath !== null;
+
+	for (const rec of storeInfo.records) {
+		const value = deserializeValue(rec.value, bin);
+		if (inline) store.put(value);
+		else store.put(value, deserializeValue(rec.key, bin));
+	}
+
+	await transactionDone(tx);
+}
+
+/** @param {string} name */
+function openExisting(name) {
+	return new Promise((resolve, reject) => {
+		const open = indexedDB.open(name);
+		open.onsuccess = () => {
+			const db = open.result;
+			db.onversionchange = () => db.close();
+			resolve(db);
+		};
+		open.onerror = () => reject(open.error);
+	});
+}
+
+/**
+ *
+ * @param {any} dbInfo
+ * @param {boolean} wasCleared 
+ * @returns {Promise<IDBDatabase>}
+ */
+async function openForRestore(dbInfo, wasCleared) {
+	if (wasCleared) {
+		return openAndUpgrade(dbInfo.name, dbInfo.version || 1, dbInfo.stores);
+	}
+
+	const current = await openExisting(dbInfo.name);
+	const needsUpgrade = dbInfo.stores.some((s) => !hasSchema(current, s));
+	if (!needsUpgrade) return current;
+
+	const targetVersion = Math.max(current.version + 1, dbInfo.version || 1);
+	current.close();
+	return openAndUpgrade(dbInfo.name, targetVersion, dbInfo.stores);
+}
+
+/**
+ * @param {IDBDatabase} db
+ * @param {any} storeInfo
+ */
+function hasSchema(db, storeInfo) {
+	if (!db.objectStoreNames.contains(storeInfo.name)) return false;
+	if (storeInfo.indexes.length === 0) return true;
+	const store = db.transaction(storeInfo.name, 'readonly').objectStore(storeInfo.name);
+	return storeInfo.indexes.every((ix) => store.indexNames.contains(ix.name));
+}
+
+/**
+ * @param {string} name
+ * @param {number} version
+ * @param {any[]} stores
+ * @returns {Promise<IDBDatabase>}
+ */
+function openAndUpgrade(name, version, stores) {
+	return new Promise((resolve, reject) => {
+		const open = indexedDB.open(name, version);
+		open.onupgradeneeded = () => {
+			const db = open.result;
+			const tx = open.transaction; 
+			for (const s of stores) {
+				const store = db.objectStoreNames.contains(s.name)
+					? tx.objectStore(s.name)
+					: db.createObjectStore(s.name, { keyPath: s.keyPath, autoIncrement: s.autoIncrement });
+				for (const ix of s.indexes) {
+					if (!store.indexNames.contains(ix.name)) {
+						store.createIndex(ix.name, ix.keyPath, {
+							unique: ix.unique,
+							multiEntry: ix.multiEntry
+						});
+					}
+				}
+			}
+		};
+		open.onsuccess = () => resolve(open.result);
+		open.onerror = () => reject(open.er		open.onblocked = () => reject(blockedError(name));
+	});
+}
+
+/** @param {string} name */
+function deleteDatabase(name) {
+	return new Promise((resolve, reject) => {
+		const req = indexedDB.deleteDatabase(name);
+		req.onsuccess = () => resolve(undefined);
+		req.onerror = () => reject(req.error);
+		req.onblocked = () => reject(blockedError(name));
+	});
+}
+
+/** @param {string} name */
+function blockedError(name) {
+	return new DOMException(
+		`IndexedDB "${name}" is blocked by another open connection — close other tabs on this origin and retry`,
+		'InvalidStateError'
+	);
+}
+
+/** @param {IDBRequest} req */
+function request(req) {
+	return new Promise((resolve, reject) => {
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => reject(req.error);
+	});
+}
+
+/** @param {IDBTransaction} tx */
+function transactionDone(tx) {
+	return new Promise((resolve, reject) => {
+		tx.oncomplete = () => resolve(undefined);
+		tx.onabort = tx.onerror = () => reject(tx.error);
+	});
+}

package/src/storage/opfs.js

@@ -0,0 +1,80 @@
+/**
+ * @param {Array<Blob | Uint8Array>} bin
+ * @returns {Promise<object[] | null>} 
+ */
+export async function dumpOPFS(bin) {
+	const root = await getRoot();
+	if (!root) return null;
+	return dumpDir(root, bin);
+}
+
+/**
+ * @param {FileSystemDirectoryHandle} dir
+ * @param {Array<Blob | Uint8Array>} bin
+ */
+async function dumpDir(dir, bin) {
+	const entries = [];
+	for await (const [name, handle] of dir.entries()) {
+		if (handle.kind === 'file') {
+			const file = await handle.getFile();
+			bin.push(file);
+			entries.push({
+				name,
+				kind: 'file',
+				b: bin.length - 1,
+				type: file.type,
+				lastModified: file.lastModified
+			});
+		} else {
+			entries.push({ name, kind: 'directory', children: await dumpDir(handle, bin) });
+		}
+	}
+	return entries;
+}
+
+/**
+ * @param {object[] | null | undefined} tree
+ * @param {Uint8Array[]} bin
+ * @param {{ clear?: boolean }} [options]
+ */
+export async function restoreOPFS(tree, bin, { clear = true } = {}) {
+	if (!tree) return;
+	const root = await getRoot();
+	if (!root) return;
+
+	if (clear) {
+		const names = [];
+		for await (const name of root.keys()) names.push(name);
+		for (const name of names) await root.removeEntry(name, { recursive: true });
+	}
+
+	await restoreDir(root, tree, bin);
+}
+
+/**
+ * @param {FileSystemDirectoryHandle} dir
+ * @param {object[]} entries
+ * @param {Uint8Array[]} bin
+ */
+async function restoreDir(dir, entries, bin) {
+	for (const entry of entries) {
+		if (entry.kind === 'file') {
+			const handle = await dir.getFileHandle(entry.name, { create: true });
+			const writable = await handle.createWritable();
+			await writable.write(bin[entry.b]);
+			await writable.close();
+		} else {
+			const sub = await dir.getDirectoryHandle(entry.name, { create: true });
+			await restoreDir(sub, entry.children, bin);
+		}
+	}
+}
+
+async function getRoot() {
+	if (typeof navigator === 'undefined' || !navigator.storage?.getDirectory) return null;
+	try {
+		return await navigator.storage.getDirectory();
+	} catch {
+		return null;
+	}
+}

package/src/storage/webstorage.js

@@ -0,0 +1,23 @@
+/**
+ * @param {Storage} storage
+ * @returns {Record<string, string>}
+ */
+export function dumpWebStorage(storage) {
+	/** @type {Record<string, string>} */
+	const out = {};
+	for (let i = 0; i < storage.length; i++) {
+		const key = storage.key(i);
+		if (key !== null) out[key] = storage.getItem(key) ?? '';
+	}
+	return out;
+}
+
+/**
+ * @param {Storage} storage
+ * @param {Record<string, string>} data
+ * @param {{ clear?: boolean }} [options]
+ */
+export function restoreWebStorage(storage, data, { clear = false } = {}) {
+	if (clear) storage.clear();
+	for (const [key, value] of Object.entries(data)) storage.setItem(key, value);
+}