@oss-idle/addon-sdk 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/oss-idle/addon-sdk/HEAD/icon.svg" alt="" width="112">
+</p>
 
-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.
+<h1 align="center">oss!idle Addon SDK</h1>
+
+<p align="center">
+  Build <a href="https://github.com/oss-idle/oss-idle">oss!idle</a> add-ons in
+  TypeScript, with your dependencies bundled.
+</p>
+
+```sh
+npx @oss-idle/addon-sdk-create@latest my-addon
+cd my-addon
+npm install
+npm run build
+```
+
+That emits one self-contained ES module. Paste it into the in-game add-on editor
+(Options → Add-ons → Manage) and enable it.
+
+## The contract
+
+The game loads an add-on by importing its source as a Blob ES module and calling
+`mount` / `unmount`. Nothing is injected; add-ons run unsandboxed in the page
+realm and reach for what they need themselves.
+
+```ts
+import { Addon, defineAddon } from '@oss-idle/addon-sdk';
+
+class Hello extends Addon {
+	constructor() { super({ name: 'Hello' }); }
+
+	protected onMount() {
+		this.interval(() => this.log.info('tick'), 1000);
+	}
+}
+
+export const { mount, unmount } = defineAddon(() => new Hello());
+```
+
+Two things follow from that, and they shape the whole SDK:
+
+1. **A Blob module resolves nothing** - no base URL, no import map. React, CSS,
+   workers and any game code you use must already be inside the one emitted
+   file. That is what `oss-idle-addon build` produces.
+2. **`unmount` has to genuinely undo everything**, because add-ons are enabled,
+   disabled, updated and removed without a page reload. Anything you register
+   through `this.on`, `this.interval`, `this.timeout` or `this.own` is torn down
+   for you, in reverse order, even if one teardown throws.
+
+## React overlays
+
+```tsx
+import { ReactAddon } from '@oss-idle/addon-sdk/react';
+import styles from './styles.css';
+
+export class MyAddon extends ReactAddon {
+	private open = false;
+
+	constructor() { super({ name: 'My add-on', styles }); }
+
+	protected override onReady() {
+		this.own(this.hotkeys.register('Ctrl+Shift+K', () => {
+			this.open = !this.open;
+			this.refresh();
+		}, { allowInText: true }));
+	}
+
+	protected render() { return <Panel open={this.open} />; }
+}
+```
+
+`ReactAddon` renders into a **shadow root**, so the game's CSS cannot reach your
+overlay and yours cannot restyle the game. For another framework, subclass
+`Addon` and use `createOverlay` directly.
+
+Render your panel hidden rather than returning `null`: `null` unmounts the tree,
+discarding its state and running cleanup, so anything the overlay started dies
+the moment the player closes it.
+
+## Staying out of the game's way
+
+The client binds gameplay controls as **bubble-phase listeners on `window`**, and
+nothing in the capture phase - which is what lets an overlay coexist with it.
+
+- `isolateInput(root)`, applied for you by `createOverlay`, stops input events at
+  the overlay's root while they bubble. The event still reached its target, so a
+  text field types normally, but it never continues to `window` - typing "speed"
+  into a filter box cannot press four gameplay keys, and scrolling a list cannot
+  change the game's volume.
+- `HotkeyManager` listens in the **capture** phase, ahead of every game handler,
+  so a shortcut claims its combo before gameplay sees it.
+- Overlays default to `z-index: 50000` - above the game's UI, below its drawn
+  cursor. Stack above the cursor layer (99999+) and the player loses their
+  pointer entirely, because the game hides the system cursor with
+  `cursor: none`, which inherits through the shadow boundary.
+
+## Reading the game's state
+
+Add-ons cannot import the client's modules, so the SDK talks to what the page
+exposes:
+
+```ts
+import {
+	gameDb, gameCharacter, beatmapStore, playlists, recentPlayCounts,
+} from '@oss-idle/addon-sdk';
+
+await gameDb.ready();                            // the client opens it lazily
+const me = await gameCharacter.live();           // who is being played
+const maps = await beatmapStore.difficulties();  // downloaded charts
+const played = await recentPlayCounts(me.id);    // plays per map, last 24h
+await playlists.replace('My rotation', [101, 102]);
+```
+
+`gameDb` wraps the sql.js handle the client publishes on `window`. Reads go
+through its read path, **writes through its write path** - that is what persists
+the database back to IndexedDB; a write applied on the read handle lives only
+until reload.
+
+`gameCharacter.live()` resolves who is playing from the most recent stored score,
+because the client keeps that answer in module state an add-on cannot see. Note
+that `character.current = 1` marks the live **guest**, not the signed-in
+character - reading it directly is a quiet way to simulate the wrong player.
+
+`beatmapStore` opens the beatmap IndexedDB **without a version number**, on
+purpose: passing one could trigger an upgrade and take out the player's library.
+
+`playlists` reads and writes the client's own playlist tables. `replace()` keeps
+an existing playlist's id, so regenerating one does not orphan anything pointing
+at it. The client caches playlists behind a version counter it bumps itself and
+an add-on cannot reach, so **song select keeps showing the old list until it
+re-reads** - say so rather than leaving the player wondering.
+
+`playCountsSince` and `recentPlayCounts` count plays per map from the `score`
+table, in one query rather than per map. The 24h/50-play window
+`recentPlayCounts` uses is the one the server scores repetition over, so an
+add-on predicting what a play is worth has to read it the same way.
+
+## Remembering settings
+
+```ts
+import { createSettings } from '@oss-idle/addon-sdk';
+import { usePersistedSettings } from '@oss-idle/addon-sdk/react';
+
+const DEFAULTS = { skill: 'total', runs: 3 };
+const store = createSettings('my-addon', DEFAULTS);
+
+const [settings, update] = usePersistedSettings(store, DEFAULTS);
+```
+
+Keys live under `oss-idle-addon:<namespace>`, which matters: the client writes
+its own options under bare, unprefixed keys and parses them without a guard, so a
+collision would corrupt a game setting. Stored values merge over your defaults,
+so shipping a new setting does not invalidate what players saved, and every
+access is guarded - storage can be unavailable or full.
+
+Use it for settings, not data. localStorage is shared with the client, so filling
+it breaks the game and not just your add-on.
+
+## Building
+
+```sh
+oss-idle-addon build [--minify] [--watch] [--config addon.config.json]
+```
+
+```jsonc
+{
+  "name": "My Add-on",
+  "entry": "src/index.ts",
+  "outfile": "dist/my-addon.js"
+}
+```
+
+The version comes from `package.json`. The build stamps it into the banner and
+into the bundle, so `this.meta.version` reports the version that was built:
+
+```ts
+super({ name: 'My Add-on' });   // version filled in by the bundler
+this.meta.version               // "0.1.0"
+buildMeta().gameVersion         // the oss!idle release it was built against
+```
+
+The build fails if the output would not export `mount` - a bundle missing it
+loads without error and does nothing, which is miserable to debug from inside the
+game.
+
+Output is **not minified by default**: published add-ons are read by a human
+moderator before they go live.
+
+| Feature | Why it exists |
+|---|---|
+| Everything inlined into one ES module | A Blob module resolves nothing at load time. |
+| `import styles from './x.css'` → string | For injecting into the overlay's shadow root. |
+| `import make from 'worker:./x.worker'` | Workers must travel inside the same file. Heavy work belongs off the main thread - the game is a rhythm game sharing it. |
+| `import bytes from './x.wasm?base64'` | Same reason: a Blob module cannot fetch a sibling asset. |
+| `gameRoot` → resolves `@oss-idle/shared/*` | The game's package is unpublished, so its TypeScript is compiled from a checkout (`$OSS_IDLE_PATH`). |
+| `dedupe` | Your sources and the game's come from different checkouts, so shared packages would otherwise be bundled twice - which silently breaks prototype patches and `instanceof`. |
+| `stubModules` | Trims a heavy dependency a game module imports but your add-on never calls. Stubs **throw** if reached. |
+
+### Using the game's own code
+
+An add-on can bundle oss!idle's simulation, skills and helpers straight from a
+checkout:
+
+```jsonc
+{
+  "gameRoot": "/path/to/oss-idle",       // or set $OSS_IDLE_PATH
+  "dedupe": ["osu-classes", "osu-parsers", "osu-mania-stable"]
+}
+```
+
+```ts
+import { ManiaGame } from '@oss-idle/shared/sim/maniaGame';
+```
+
+Doing so makes your add-on a derivative work of oss!idle, which is **AGPL-3.0** -
+so it must be AGPL-3.0 too. Pin the game version you built against; the sources
+are internal and do move between releases.
+
+## Licence
+
+AGPL-3.0-only.

package/bin/cli.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * oss-idle-addon - the oss!idle Addon SDK command line.
+ *
+ *   oss-idle-addon init [dir] [--name "My Add-on"] [--template react|plain]
+ *   oss-idle-addon build [--config addon.config.json] [--minify] [--watch]
+ */
+import { readFile } from 'node:fs/promises';
+import { existsSync, watch } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { scaffold, TEMPLATE_NAMES } from './scaffold.mjs';
+
+const argv = process.argv.slice(2);
+const command = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'build';
+const args = argv.slice(argv[0] === command ? 1 : 0);
+
+const flag = (name) => args.includes(`--${name}`);
+const option = (name, fallback) => {
+	const i = args.indexOf(`--${name}`);
+	return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : fallback;
+};
+/** First argument that is not a flag or a flag's value. */
+const positional = () => {
+	for (let i = 0; i < args.length; i++) {
+		if (args[i].startsWith('--')) { i++; continue; }
+		return args[i];
+	}
+	return undefined;
+};
+
+const usage = `oss!idle Addon SDK
+
+  oss-idle-addon init [dir]        create a new add-on project
+    --name "My Add-on"             display name (default: the directory name)
+    --template ${TEMPLATE_NAMES.join('|').padEnd(20)}starting point (default: react)
+    --license <spdx>               default: AGPL-3.0-only
+    --force                        write into a non-empty directory
+
+  oss-idle-addon build             bundle the add-on into one ES module
+    --config <path>                default: addon.config.json
+    --minify                       smaller, but harder for a reviewer to read
+    --sourcemap                    inline source map
+    --watch                        rebuild on change
+`;
+
+const die = (message) => { console.error(message); process.exit(1); };
+
+if (flag('help') || flag('h') || command === 'help') {
+	console.log(usage);
+	process.exit(0);
+}
+
+if (command === 'init') {
+	const dir = positional() ?? '.';
+	const name = option('name', resolve(dir).split(/[\\/]/).pop());
+
+	const result = await scaffold({
+		dir,
+		name,
+		template: option('template', 'react'),
+		license: option('license', 'AGPL-3.0-only'),
+		force: flag('force'),
+	}).catch(e => die(e.message));
+
+	const where = relative(process.cwd(), result.target) || '.';
+	console.log(`Created ${name} in ${where}/  (${result.template} template)\n`);
+	console.log('Next:');
+	if (where !== '.') console.log(`  cd ${where}`);
+	console.log('  npm install');
+	console.log('  npm run build\n');
+	console.log(`Then paste ${result.outfile} into the in-game add-on editor.`);
+	process.exit(0);
+}
+
+if (command !== 'build') die(`Unknown command "${command}".\n\n${usage}`);
+
+// ---- build ---------------------------------------------------------------
+
+const { bundleAddon } = await import('../dist/build/index.js');
+
+const configPath = resolve(option('config', 'addon.config.json'));
+if (!existsSync(configPath)) {
+	die(`No config at ${configPath}.\nRun "oss-idle-addon init" to create a project, or pass --config.`);
+}
+
+const config = JSON.parse(await readFile(configPath, 'utf8'));
+const cwd = resolve(configPath, '..');
+
+if (!config.entry || !config.outfile) {
+	die(`${configPath} needs both "entry" and "outfile".`);
+}
+
+/**
+ * The add-on's version, from package.json - the one file that must carry one.
+ * Repeating it in addon.config.json is how a bundle ends up claiming a version
+ * it is not.
+ */
+const pkgVersion = await readFile(resolve(cwd, 'package.json'), 'utf8')
+	.then(raw => JSON.parse(raw).version)
+	.catch(() => undefined);
+
+const run = async () => {
+	const started = Date.now();
+	const { outfile, bytes } = await bundleAddon({
+		entry: resolve(cwd, config.entry),
+		outfile: resolve(cwd, config.outfile),
+		gameRoot: process.env.OSS_IDLE_PATH ?? config.gameRoot,
+		minify: flag('minify') || !!config.minify,
+		sourcemap: flag('sourcemap'),
+		stubModules: config.stubModules,
+		dedupe: config.dedupe,
+		dedupeFrom: cwd,
+		meta: {
+			name: config.name,
+			version: pkgVersion,
+			gameVersion: process.env.OSS_IDLE_GAME_VERSION ?? config.gameVersion,
+			license: config.license,
+		},
+	});
+	console.log(
+		`built ${relative(process.cwd(), outfile)} - ${(bytes / 1024).toFixed(1)} kB`
+		+ ` in ${Date.now() - started}ms`,
+	);
+};
+
+await run().catch(e => die(e.message ?? e));
+
+if (flag('watch')) {
+	const src = resolve(cwd, 'src');
+	console.log(`watching ${relative(process.cwd(), src)}/ ...`);
+	let queued;
+	watch(src, { recursive: true }, () => {
+		clearTimeout(queued);
+		queued = setTimeout(() => run().catch(e => console.error(e.message ?? e)), 120);
+	});
+}

package/bin/scaffold.mjs

@@ -0,0 +1,154 @@
+/**
+ * Scaffolding a new add-on.
+ *
+ * Shared by `oss-idle-addon init` and by `npx @oss-idle/addon-sdk-create`, so both
+ * entry points produce exactly the same project.
+ *
+ * Templates are plain files with `__TOKEN__` placeholders rather than a
+ * template language: they stay readable, and `templates/react/src/Addon.tsx` is
+ * a working reference for someone reading the SDK itself.
+ */
+import { cp, mkdir, readdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = resolve(here, '..', 'templates');
+
+/** SDK version to depend on, taken from the SDK actually doing the scaffolding. */
+const sdkVersion = async () => {
+	try {
+		const pkg = JSON.parse(await readFile(resolve(here, '..', 'package.json'), 'utf8'));
+		return `^${pkg.version}`;
+	} catch {
+		return 'latest';
+	}
+};
+
+/** `My Cool Add-on` -> `my-cool-add-on`. */
+export const slugify = (name) =>
+	name.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		|| 'my-addon';
+
+/** `my-cool-addon` -> `MyCoolAddon`, a usable class name. */
+export const classify = (slug) => {
+	const name = slug.split('-')
+		.filter(Boolean)
+		.map(part => part[0].toUpperCase() + part.slice(1))
+		.join('');
+	// A class name cannot start with a digit.
+	return /^[0-9]/.test(name) ? `Addon${name}` : (name || 'MyAddon');
+};
+
+const fill = (text, tokens) =>
+	Object.entries(tokens).reduce(
+		(out, [token, value]) => out.split(`__${token}__`).join(value),
+		text,
+	);
+
+/** Copy a template directory, substituting tokens in every text file. */
+const copyTemplate = async (from, to, tokens) => {
+	for (const entry of await readdir(from, { withFileTypes: true })) {
+		const source = join(from, entry.name);
+		const target = join(to, entry.name);
+
+		if (entry.isDirectory()) {
+			await mkdir(target, { recursive: true });
+			await copyTemplate(source, target, tokens);
+			continue;
+		}
+
+		// Anything not text is copied verbatim; templates are all text today,
+		// but this keeps a future binary asset from being corrupted.
+		if (/\.(png|jpg|gif|wasm|woff2?)$/.test(entry.name)) {
+			await cp(source, target);
+			continue;
+		}
+
+		// npm strips `.gitignore` from published tarballs, so the template ships
+		// it undotted and it is restored here - otherwise every scaffolded
+		// project would arrive without one and commit its node_modules.
+		const name = entry.name === 'gitignore' ? '.gitignore' : entry.name;
+		const dest = join(dirname(target), name);
+
+		await mkdir(dirname(dest), { recursive: true });
+		await writeFile(dest, fill(await readFile(source, 'utf8'), tokens), 'utf8');
+	}
+};
+
+export const TEMPLATE_NAMES = ['react', 'plain'];
+
+/**
+ * Create an add-on project in `dir`.
+ *
+ * Refuses to write into a directory that already holds files, unless `force` -
+ * scaffolding over someone's work is not recoverable.
+ */
+export const scaffold = async ({
+	dir,
+	name,
+	template = 'react',
+	license = 'AGPL-3.0-only',
+	force = false,
+}) => {
+	if (!TEMPLATE_NAMES.includes(template)) {
+		throw new Error(`Unknown template "${template}". Use one of: ${TEMPLATE_NAMES.join(', ')}`);
+	}
+
+	const target = resolve(dir);
+	if (existsSync(target)) {
+		const info = await stat(target);
+		if (!info.isDirectory()) throw new Error(`${target} exists and is not a directory`);
+		const existing = (await readdir(target)).filter(f => f !== '.git');
+		if (existing.length && !force) {
+			throw new Error(
+				`${target} is not empty (${existing.length} entries). `
+				+ 'Choose an empty directory, or pass --force.',
+			);
+		}
+	}
+	await mkdir(target, { recursive: true });
+
+	const slug = slugify(name);
+	const tokens = {
+		ADDON_NAME: name,
+		SLUG: slug,
+		CLASS: classify(slug),
+		LICENSE: license,
+		OUTFILE: `dist/${slug}.js`,
+		// A default hotkey letter that is unlikely to collide with the game's.
+		KEY: (slug.match(/[a-z]/)?.[0] ?? 'k').toUpperCase(),
+	};
+
+	await copyTemplate(join(TEMPLATES, 'common'), target, tokens);
+	await copyTemplate(join(TEMPLATES, template), target, tokens);
+
+	const react = template === 'react';
+	const pkg = {
+		name: slug,
+		version: '0.1.0',
+		private: true,
+		type: 'module',
+		license,
+		description: `${name} - an oss!idle add-on`,
+		scripts: {
+			build: 'oss-idle-addon build',
+			dev: 'oss-idle-addon build --watch',
+			typecheck: 'tsc -p tsconfig.json --noEmit',
+		},
+		dependencies: {
+			'@oss-idle/addon-sdk': await sdkVersion(),
+			...(react ? { react: '^18.3.1', 'react-dom': '^18.3.1' } : {}),
+		},
+		devDependencies: {
+			...(react ? { '@types/react': '^18.3.12', '@types/react-dom': '^18.3.1' } : {}),
+			typescript: '^5.6.3',
+		},
+	};
+	await writeFile(join(target, 'package.json'), JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+
+	return { target, slug, template, outfile: tokens.OUTFILE };
+};

package/dist/bridge/beatmaps.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Bridge to the game's stored beatmaps.
+ *
+ * Downloaded sets live in their own IndexedDB database (`beatmaps`), separate
+ * from the sql.js state database:
+ *
+ * - `meta`  - one record per set (`keyPath: 'id'`). The record **is** the set's
+ *             metadata, versions and all - the client's `.metadata` property
+ *             comes from the `LightBeatmapSet` wrapper it builds afterwards,
+ *             not from the stored shape.
+ * - `charts`- keyed by set id, holding `Record<beatmapId, osuFileText>`.
+ * - `files` - the set's assets (audio, backgrounds). Unused here.
+ *
+ * Only *downloaded* sets are present: the catalog lists far more than any
+ * player holds, and a chart is what the simulation needs, so the add-on's
+ * coverage is the player's own library.
+ *
+ * The database is opened **without a version**. Passing one would trigger an
+ * upgrade if the add-on's number ever drifted above the client's, and an
+ * upgrade here would wipe or block the player's whole library.
+ */
+export type StoredVersion = {
+    id: number;
+    version: string;
+    difficulty: number;
+    mode: number;
+    keys: number;
+    total_length: number;
+    bpm: number;
+    objects: number;
+    rice?: number;
+    ln?: number;
+    [key: string]: unknown;
+};
+export type StoredSetMeta = {
+    id: number;
+    title: string;
+    artist: string;
+    creator: string;
+    versions: StoredVersion[];
+    [key: string]: unknown;
+};
+/** The player's downloaded beatmaps. */
+export declare const beatmapStore: {
+    /** Metadata for every stored set. */
+    sets(): Promise<StoredSetMeta[]>;
+    /** Every stored difficulty, paired with the set it belongs to. */
+    difficulties(): Promise<{
+        set: StoredSetMeta;
+        version: StoredVersion;
+    }[]>;
+    /** Every chart in one set, keyed by difficulty id. */
+    charts(setId: number): Promise<Record<number, string>>;
+    /** One difficulty's `.osu` text, or `undefined` if the set is not stored. */
+    chart(setId: number, beatmapId: number): Promise<string | undefined>;
+};
+//# sourceMappingURL=beatmaps.d.ts.map

package/dist/bridge/beatmaps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beatmaps.d.ts","sourceRoot":"","sources":["../../src/bridge/beatmaps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,aAAa,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB,CAAC;AA8BF,wCAAwC;AACxC,eAAO,MAAM,YAAY;IAExB,qCAAqC;YACvB,OAAO,CAAC,aAAa,EAAE,CAAC;IAKtC,kEAAkE;oBAC5C,OAAO,CAAC;QAAE,GAAG,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAE,EAAE,CAAC;IAK/E,sDAAsD;kBAClC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAI5D,6EAA6E;iBAC1D,MAAM,aAAa,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;CAG1E,CAAC"}

package/dist/bridge/beatmaps.js

@@ -0,0 +1,65 @@
+/**
+ * Bridge to the game's stored beatmaps.
+ *
+ * Downloaded sets live in their own IndexedDB database (`beatmaps`), separate
+ * from the sql.js state database:
+ *
+ * - `meta`  - one record per set (`keyPath: 'id'`). The record **is** the set's
+ *             metadata, versions and all - the client's `.metadata` property
+ *             comes from the `LightBeatmapSet` wrapper it builds afterwards,
+ *             not from the stored shape.
+ * - `charts`- keyed by set id, holding `Record<beatmapId, osuFileText>`.
+ * - `files` - the set's assets (audio, backgrounds). Unused here.
+ *
+ * Only *downloaded* sets are present: the catalog lists far more than any
+ * player holds, and a chart is what the simulation needs, so the add-on's
+ * coverage is the player's own library.
+ *
+ * The database is opened **without a version**. Passing one would trigger an
+ * upgrade if the add-on's number ever drifted above the client's, and an
+ * upgrade here would wipe or block the player's whole library.
+ */
+const DB_NAME = 'beatmaps';
+let connection;
+const open = () => connection ??= new Promise((resolve, reject) => {
+    // No version argument - see the note above.
+    const request = indexedDB.open(DB_NAME);
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+    request.onblocked = () => reject(new Error('beatmap store blocked by another tab'));
+}).catch((e) => {
+    // Don't cache a failed open - the next call retries.
+    connection = undefined;
+    throw e;
+});
+const request = (store, fn) => open().then(db => new Promise((resolve, reject) => {
+    if (!db.objectStoreNames.contains(store)) {
+        resolve(undefined);
+        return;
+    }
+    const tx = db.transaction(store, 'readonly');
+    const req = fn(tx.objectStore(store));
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+}));
+/** The player's downloaded beatmaps. */
+export const beatmapStore = {
+    /** Metadata for every stored set. */
+    async sets() {
+        const records = await request('meta', s => s.getAll());
+        return (records ?? []).filter(record => Array.isArray(record?.versions));
+    },
+    /** Every stored difficulty, paired with the set it belongs to. */
+    async difficulties() {
+        const sets = await this.sets();
+        return sets.flatMap(set => (set.versions ?? []).map(version => ({ set, version })));
+    },
+    /** Every chart in one set, keyed by difficulty id. */
+    async charts(setId) {
+        return (await request('charts', s => s.get(setId))) ?? {};
+    },
+    /** One difficulty's `.osu` text, or `undefined` if the set is not stored. */
+    async chart(setId, beatmapId) {
+        return (await this.charts(setId))[beatmapId];
+    },
+};