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

package/dist/build/index.js

@@ -0,0 +1,126 @@
+/**
+ * The add-on bundler.
+ *
+ * oss!idle stores an add-on as one `source` string and loads it with
+ * `import(URL.createObjectURL(new Blob([source])))`. A Blob module has no base
+ * URL and no import map, so **nothing** resolves at load time: React, the
+ * game's simulation, workers and CSS must all already be inside that one file,
+ * and it must be an ES module exporting `mount` and `unmount`.
+ *
+ * That is what this produces.
+ *
+ * Output is **not minified by default**. Published add-ons are read by a human
+ * moderator before they go live, and a single minified line is a poor thing to
+ * ask anyone to review.
+ */
+import { build as esbuild } from 'esbuild';
+import { createRequire } from 'node:module';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { assetQueryPlugin, cssTextPlugin, dedupePlugin, hostReactPlugin, inlineWorkerPlugin, sharedSourcePlugin, stubModulePlugin, tsExtensionPlugin, } from './plugins.js';
+/**
+ * The individual esbuild plugins, for a build that needs to assemble its own
+ * pipeline rather than call {@link bundleAddon} - compiling a slice of an add-on
+ * for a test, say, or bundling a worker on its own.
+ */
+export { assetQueryPlugin, cssTextPlugin, dedupePlugin, hostReactPlugin, inlineWorkerPlugin, sharedSourcePlugin, stubModulePlugin, tsExtensionPlugin, } from './plugins.js';
+const sharedSrcOf = (gameRoot) => resolve(gameRoot, 'packages/shared/src');
+/** esbuild settings shared by the add-on bundle and any inlined worker. */
+const baseOptions = (gameRoot, minify, stubModules = {}, dedupe = [], dedupeFrom = process.cwd(), plugins = []) => ({
+    bundle: true,
+    format: 'esm',
+    platform: 'browser',
+    target: 'es2022',
+    // The add-on runs inside the shipped client, which is a production React build.
+    define: { 'process.env.NODE_ENV': '"production"' },
+    jsx: 'automatic',
+    legalComments: 'inline',
+    // A Blob-loaded module cannot fetch a sibling asset, so a WebAssembly
+    // binary has to travel inside the bundle. Imported as base64, it is decoded
+    // at runtime and handed to the module's init as a BufferSource. Costs about
+    // a third more bytes than the binary itself.
+    loader: { '.wasm': 'base64' },
+    minify,
+    plugins: [
+        ...plugins,
+        // Strip asset suffixes before anything tries to resolve them as modules.
+        assetQueryPlugin(),
+        // Dedupe first: it must see a bare package name before anything else
+        // resolves it out of the game's checkout.
+        dedupePlugin(dedupe, dedupeFrom),
+        ...(gameRoot ? [sharedSourcePlugin(sharedSrcOf(gameRoot))] : []),
+        tsExtensionPlugin(),
+        stubModulePlugin(stubModules),
+        cssTextPlugin(),
+    ],
+});
+/** Build one worker entry to a self-contained string for inlining. */
+const buildWorkerSource = async (entry, gameRoot, minify, stubModules, dedupe, dedupeFrom, plugins) => {
+    const result = await esbuild({
+        ...baseOptions(gameRoot, minify, stubModules, dedupe, dedupeFrom, plugins),
+        entryPoints: [entry],
+        write: false,
+        // A worker built as ESM would need `type: 'module'` support *and* would
+        // keep top-level await; IIFE keeps the inlined string self-contained.
+        format: 'iife',
+    });
+    return result.outputFiles?.[0]?.text ?? '';
+};
+/**
+ * This SDK's own version, for the banner and the stamped meta - the two places
+ * a reader asks what built a bundle they are holding.
+ */
+const sdkVersion = createRequire(import.meta.url)('@oss-idle/addon-sdk/package.json').version;
+/** Bundle an add-on into the single ES module the runtime loads. */
+export const bundleAddon = async (options) => {
+    const { entry, outfile, gameRoot, meta, minify = false, sourcemap = false, stubModules = {}, dedupe = [], dedupeFrom = dirname(resolve(entry)), plugins = [], sharedReact = false, } = options;
+    // The SDK's React modules are imported from wherever npm put the SDK, so
+    // `react` resolves from there unless it is pointed back at the add-on that
+    // installed it - and two Reacts in one bundle break hooks outright. With the
+    // game's React there is none to bundle.
+    const names = [...new Set([...sharedReact ? [] : ['react', 'react-dom'], ...dedupe])];
+    const ownPlugins = sharedReact ? [hostReactPlugin(dedupeFrom), ...plugins] : plugins;
+    const base = baseOptions(gameRoot, minify, stubModules, names, dedupeFrom, ownPlugins);
+    const result = await esbuild({
+        ...base,
+        // Read back at runtime by `buildMeta()`.
+        define: { ...base.define, __OSS_IDLE_ADDON__: JSON.stringify({ ...meta, sdkVersion }) },
+        entryPoints: [entry],
+        write: false,
+        sourcemap: sourcemap ? 'inline' : false,
+        plugins: [
+            inlineWorkerPlugin(workerEntry => buildWorkerSource(workerEntry, gameRoot, minify, stubModules, dedupe, dedupeFrom, plugins)),
+            ...(base.plugins ?? []),
+        ],
+    });
+    const code = result.outputFiles?.[0]?.text ?? '';
+    // The trailing blank line is not optional: without it the last banner comment
+    // would swallow the first line of generated code.
+    const banner = meta
+        ? [
+            '// ' + [meta.name, meta.version && `v${meta.version}`].filter(Boolean).join(' '),
+            meta.gameVersion && `// built against oss!idle ${meta.gameVersion}`,
+            meta.license && `// ${meta.license}`,
+            `// Bundled with @oss-idle/addon-sdk v${sdkVersion}. Paste this file into the add-on editor.`,
+        ].filter(Boolean).join('\n') + '\n\n'
+        : '';
+    const source = banner + code;
+    await mkdir(dirname(resolve(outfile)), { recursive: true });
+    await writeFile(outfile, source, 'utf8');
+    await assertAddonShape(outfile, source);
+    return { outfile, bytes: Buffer.byteLength(source, 'utf8') };
+};
+/**
+ * Fail the build if the output would not satisfy the runtime contract.
+ *
+ * A bundle missing `mount` loads without error and simply does nothing, which
+ * is a miserable thing to debug from inside the game - much better to catch it
+ * here.
+ */
+const assertAddonShape = async (outfile, source) => {
+    const code = source || await readFile(outfile, 'utf8');
+    if (!/export\s*\{[^}]*\bmount\b/.test(code) && !/export\s+(const|function)\s+mount\b/.test(code)) {
+        throw new Error(`${outfile} does not export "mount" - the add-on runtime would load it and call nothing. ` +
+            'Export it from your entry, e.g. `export const { mount, unmount } = defineAddon(...)`.');
+    }
+};

package/dist/build/plugins.d.ts

@@ -0,0 +1,95 @@
+import type { Plugin } from 'esbuild';
+/**
+ * Resolve `@oss-idle/shared/*` against a checkout of the game.
+ *
+ * The package is `private: true` and never published, so there is nothing to
+ * install - the add-on compiles the game's TypeScript sources into its own
+ * bundle instead. Its `exports` map points at `dist/`, which a plain checkout
+ * has not built, so this resolves to `src/` directly.
+ *
+ * The sources are written for NodeNext, where a relative import of a TypeScript
+ * file spells its *output* extension (`'../skills.js'` for `skills.ts`). esbuild
+ * takes that literally and would fail to find the file, so both this plugin and
+ * {@link tsExtensionPlugin} map `.js` back onto the `.ts` that produced it.
+ */
+export declare const sharedSourcePlugin: (sharedSrc: string) => Plugin;
+/**
+ * Map a relative `./x.js` import onto the `./x.ts` beside it.
+ *
+ * Only applies when the `.js` file does not exist and a `.ts` does, so a
+ * genuine JavaScript dependency is never hijacked.
+ */
+export declare const tsExtensionPlugin: () => Plugin;
+/**
+ * `import worker from 'worker:./sim.worker'` - build that entry as its own
+ * bundle and inline it as a source string, plus a factory that spawns it from a
+ * Blob URL.
+ *
+ * An add-on is itself loaded from a Blob, so it has no URL to resolve a worker
+ * file against; the worker has to travel inside the same file. Workers matter
+ * here because the game is a rhythm game sharing this thread - a simulation
+ * sweep run on the main thread would stutter gameplay.
+ */
+export declare const inlineWorkerPlugin: (buildWorker: (entry: string) => Promise<string>) => Plugin;
+/** Load `.css` imports as strings, for injection into the overlay's shadow root. */
+export declare const cssTextPlugin: () => Plugin;
+/**
+ * Replace a module the add-on never actually calls.
+ *
+ * The game's modules are written for an app that ships everything, so a small
+ * helper can sit in a file that also pulls in something large - importing
+ * `hasUnlock` from `shared/rebirth` drags in the whole of zod, half a megabyte,
+ * for three lines of logic that never touch it. esbuild cannot drop that on its
+ * own: building a zod schema at module scope is a side effect, so the import is
+ * kept even though nothing uses its exports.
+ *
+ * Stubbing lets the add-on keep importing the game's real helper - so the logic
+ * stays the game's, not a copy - while the unused dependency is left out.
+ *
+ * The stub **throws** if anything ever reaches it, so a wrong guess about what
+ * is unused fails loudly at the call instead of silently misbehaving.
+ *
+ * `stubs` maps a path suffix (e.g. `shared/src/onboarding.ts`) to the names to
+ * export from the replacement.
+ */
+export declare const stubModulePlugin: (stubs: Record<string, readonly string[]>) => Plugin;
+/**
+ * Force a package to resolve to one copy.
+ *
+ * An add-on bundles its own sources *and* the game's, which live in a different
+ * checkout with its own `node_modules`. esbuild resolves each import from the
+ * importing file, so a package both sides use - `osu-classes`, say - gets
+ * bundled **twice**: the game's sim ends up holding different class objects from
+ * the ones the add-on's decoder produces.
+ *
+ * That is not just wasted bytes. Prototype patches apply to one copy while the
+ * other is the one actually used (the game's control-point decode patch fails
+ * exactly this way), and `instanceof` across the boundary silently returns
+ * false.
+ *
+ * Resolving these names from a single directory collapses them to one copy.
+ * The versions must be compatible, which is why the add-on pins the same ones
+ * the game does.
+ */
+export declare const dedupePlugin: (names: readonly string[], fromDir: string) => Plugin;
+/**
+ * Explicit asset imports: `import bytes from './thing.wasm?base64'`.
+ *
+ * The suffix does two jobs. It says at the import site how the file arrives -
+ * mirroring the `?url` convention the client uses under Vite - and it keeps
+ * TypeScript off a shipped `.wasm.d.ts`, which would otherwise win over the
+ * add-on's own `declare module` and report the import as having no default
+ * export.
+ *
+ * Resolution strips the suffix, so esbuild's loader for the real extension
+ * (`.wasm` -> base64) applies as normal.
+ */
+export declare const assetQueryPlugin: () => Plugin;
+/**
+ * React from the game instead of a bundled copy: each React import becomes a small
+ * module reading the game's own React off `globalThis.ossIdle.react`, which the game
+ * sets before it loads any add-on. Its named exports are the installed React's, read
+ * here at build time, so `import { useState } from 'react'` keeps working.
+ */
+export declare const hostReactPlugin: (fromDir: string) => Plugin;
+//# sourceMappingURL=plugins.d.ts.map

package/dist/build/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/build/plugins.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,KAAG,MAgBrD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAO,MAanC,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,aAAa,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,KAAG,MA0BnF,CAAC;AAEH,oFAAoF;AACpF,eAAO,MAAM,aAAa,QAAO,MAQ/B,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,KAAG,MAsB1E,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,SAAS,MAAM,EAAE,EAAE,SAAS,MAAM,KAAG,MAmBvE,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,QAAO,MAgBlC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAmBhD,CAAC"}

package/dist/build/plugins.js

@@ -0,0 +1,240 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+/**
+ * Resolve `@oss-idle/shared/*` against a checkout of the game.
+ *
+ * The package is `private: true` and never published, so there is nothing to
+ * install - the add-on compiles the game's TypeScript sources into its own
+ * bundle instead. Its `exports` map points at `dist/`, which a plain checkout
+ * has not built, so this resolves to `src/` directly.
+ *
+ * The sources are written for NodeNext, where a relative import of a TypeScript
+ * file spells its *output* extension (`'../skills.js'` for `skills.ts`). esbuild
+ * takes that literally and would fail to find the file, so both this plugin and
+ * {@link tsExtensionPlugin} map `.js` back onto the `.ts` that produced it.
+ */
+export const sharedSourcePlugin = (sharedSrc) => ({
+    name: 'oss-idle-shared-source',
+    setup(build) {
+        build.onResolve({ filter: /^@oss-idle\/shared(\/.*)?$/ }, args => {
+            const subpath = args.path.replace(/^@oss-idle\/shared\/?/, '') || 'index';
+            const base = resolve(sharedSrc, subpath.replace(/\.js$/, ''));
+            for (const candidate of [`${base}.ts`, `${base}.tsx`, resolve(base, 'index.ts')]) {
+                if (existsSync(candidate))
+                    return { path: candidate };
+            }
+            return {
+                errors: [{
+                        text: `Cannot resolve "${args.path}" in the oss!idle checkout (looked under ${sharedSrc})`,
+                    }],
+            };
+        });
+    },
+});
+/**
+ * Map a relative `./x.js` import onto the `./x.ts` beside it.
+ *
+ * Only applies when the `.js` file does not exist and a `.ts` does, so a
+ * genuine JavaScript dependency is never hijacked.
+ */
+export const tsExtensionPlugin = () => ({
+    name: 'ts-extension',
+    setup(build) {
+        build.onResolve({ filter: /^\.{1,2}\/.*\.js$/ }, args => {
+            if (!args.importer.match(/\.tsx?$/))
+                return undefined;
+            const js = resolve(dirname(args.importer), args.path);
+            if (existsSync(js))
+                return undefined;
+            for (const candidate of [js.replace(/\.js$/, '.ts'), js.replace(/\.js$/, '.tsx')]) {
+                if (existsSync(candidate))
+                    return { path: candidate };
+            }
+            return undefined;
+        });
+    },
+});
+/**
+ * `import worker from 'worker:./sim.worker'` - build that entry as its own
+ * bundle and inline it as a source string, plus a factory that spawns it from a
+ * Blob URL.
+ *
+ * An add-on is itself loaded from a Blob, so it has no URL to resolve a worker
+ * file against; the worker has to travel inside the same file. Workers matter
+ * here because the game is a rhythm game sharing this thread - a simulation
+ * sweep run on the main thread would stutter gameplay.
+ */
+export const inlineWorkerPlugin = (buildWorker) => ({
+    name: 'inline-worker',
+    setup(build) {
+        build.onResolve({ filter: /^worker:/ }, args => {
+            const target = args.path.slice('worker:'.length);
+            const base = resolve(dirname(args.importer), target);
+            for (const candidate of [base, `${base}.ts`, `${base}.js`]) {
+                if (existsSync(candidate))
+                    return { path: candidate, namespace: 'inline-worker' };
+            }
+            return { errors: [{ text: `Worker entry not found: ${args.path}` }] };
+        });
+        build.onLoad({ filter: /.*/, namespace: 'inline-worker' }, async (args) => ({
+            contents: `
+const source = ${JSON.stringify(await buildWorker(args.path))};
+let url;
+/** Spawn the inlined worker. The Blob URL is created once and reused. */
+export default function createWorker() {
+	url ??= URL.createObjectURL(new Blob([source], { type: 'text/javascript' }));
+	return new Worker(url, { type: 'module' });
+}
+`,
+            loader: 'js',
+            resolveDir: dirname(args.path),
+        }));
+    },
+});
+/** Load `.css` imports as strings, for injection into the overlay's shadow root. */
+export const cssTextPlugin = () => ({
+    name: 'css-text',
+    setup(build) {
+        build.onLoad({ filter: /\.css$/ }, async (args) => ({
+            contents: `export default ${JSON.stringify(await readFile(args.path, 'utf8'))};`,
+            loader: 'js',
+        }));
+    },
+});
+/**
+ * Replace a module the add-on never actually calls.
+ *
+ * The game's modules are written for an app that ships everything, so a small
+ * helper can sit in a file that also pulls in something large - importing
+ * `hasUnlock` from `shared/rebirth` drags in the whole of zod, half a megabyte,
+ * for three lines of logic that never touch it. esbuild cannot drop that on its
+ * own: building a zod schema at module scope is a side effect, so the import is
+ * kept even though nothing uses its exports.
+ *
+ * Stubbing lets the add-on keep importing the game's real helper - so the logic
+ * stays the game's, not a copy - while the unused dependency is left out.
+ *
+ * The stub **throws** if anything ever reaches it, so a wrong guess about what
+ * is unused fails loudly at the call instead of silently misbehaving.
+ *
+ * `stubs` maps a path suffix (e.g. `shared/src/onboarding.ts`) to the names to
+ * export from the replacement.
+ */
+export const stubModulePlugin = (stubs) => ({
+    name: 'stub-module',
+    setup(build) {
+        const suffixes = Object.keys(stubs);
+        if (!suffixes.length)
+            return;
+        build.onLoad({ filter: /\.tsx?$/ }, args => {
+            const normalized = args.path.split('\\').join('/');
+            const match = suffixes.find(suffix => normalized.endsWith(suffix));
+            if (!match)
+                return undefined;
+            const names = stubs[match] ?? [];
+            const contents = names.map(name => `export const ${name} = new Proxy(function () {}, {\n` +
+                `	get() { throw new Error('${name} was stubbed out of this add-on bundle but is being used'); },\n` +
+                `	apply() { throw new Error('${name} was stubbed out of this add-on bundle but is being called'); },\n` +
+                '});').join('\n');
+            return { contents, loader: 'js' };
+        });
+    },
+});
+/**
+ * Force a package to resolve to one copy.
+ *
+ * An add-on bundles its own sources *and* the game's, which live in a different
+ * checkout with its own `node_modules`. esbuild resolves each import from the
+ * importing file, so a package both sides use - `osu-classes`, say - gets
+ * bundled **twice**: the game's sim ends up holding different class objects from
+ * the ones the add-on's decoder produces.
+ *
+ * That is not just wasted bytes. Prototype patches apply to one copy while the
+ * other is the one actually used (the game's control-point decode patch fails
+ * exactly this way), and `instanceof` across the boundary silently returns
+ * false.
+ *
+ * Resolving these names from a single directory collapses them to one copy.
+ * The versions must be compatible, which is why the add-on pins the same ones
+ * the game does.
+ */
+export const dedupePlugin = (names, fromDir) => ({
+    name: 'dedupe',
+    setup(build) {
+        if (!names.length)
+            return;
+        const pattern = new RegExp(`^(${names.map(n => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})(\\/.*)?$`);
+        build.onResolve({ filter: pattern }, async (args) => {
+            // Skip our own re-resolution, or we recurse forever.
+            if (args.pluginData === 'dedupe')
+                return undefined;
+            const result = await build.resolve(args.path, {
+                kind: args.kind,
+                resolveDir: fromDir,
+                pluginData: 'dedupe',
+            });
+            if (result.errors.length)
+                return undefined;
+            return { path: result.path, external: result.external };
+        });
+    },
+});
+/**
+ * Explicit asset imports: `import bytes from './thing.wasm?base64'`.
+ *
+ * The suffix does two jobs. It says at the import site how the file arrives -
+ * mirroring the `?url` convention the client uses under Vite - and it keeps
+ * TypeScript off a shipped `.wasm.d.ts`, which would otherwise win over the
+ * add-on's own `declare module` and report the import as having no default
+ * export.
+ *
+ * Resolution strips the suffix, so esbuild's loader for the real extension
+ * (`.wasm` -> base64) applies as normal.
+ */
+export const assetQueryPlugin = () => ({
+    name: 'asset-query',
+    setup(build) {
+        build.onResolve({ filter: /\?(base64|text)$/ }, async (args) => {
+            if (args.pluginData === 'asset-query')
+                return undefined;
+            const path = args.path.replace(/\?(base64|text)$/, '');
+            const result = await build.resolve(path, {
+                kind: args.kind,
+                resolveDir: args.resolveDir,
+                importer: args.importer,
+                pluginData: 'asset-query',
+            });
+            if (result.errors.length)
+                return { errors: result.errors };
+            return { path: result.path, external: result.external };
+        });
+    },
+});
+/**
+ * React from the game instead of a bundled copy: each React import becomes a small
+ * module reading the game's own React off `globalThis.ossIdle.react`, which the game
+ * sets before it loads any add-on. Its named exports are the installed React's, read
+ * here at build time, so `import { useState } from 'react'` keeps working.
+ */
+export const hostReactPlugin = (fromDir) => ({
+    name: 'host-react',
+    setup(build) {
+        const requireFrom = createRequire(resolve(fromDir, 'package.json'));
+        build.onResolve({ filter: /^react(-dom)?(\/(client|jsx-runtime))?$/ }, args => ({
+            path: args.path, namespace: 'oss-idle-react',
+        }));
+        build.onLoad({ filter: /.*/, namespace: 'oss-idle-react' }, args => {
+            const names = Object.keys(requireFrom(args.path))
+                .filter(name => name !== 'default' && /^[A-Za-z_$][\w$]*$/.test(name));
+            const contents = [
+                `const m = globalThis.ossIdle?.react?.[${JSON.stringify(args.path)}];`,
+                'if (!m) throw new Error("This add-on uses the game\'s React: update oss!idle to run it");',
+                'export default m;',
+                ...names.map(name => `export const ${name} = m.${name};`),
+            ].join('\n');
+            return { contents, loader: 'js' };
+        });
+    },
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { Addon, type AddonMeta, type Disposer } from './runtime/addon.js';
+export { defineAddon, type AddonModule } from './runtime/define.js';
+export { gameHost, type AddonHost, type EditorApi, type EditorMetadata, type EditorNote, type EditorRender, type EditorTimingPoint, } from './runtime/host.js';
+export { buildMeta, type BuildMeta } from './runtime/buildMeta.js';
+export { HotkeyManager, isolateInput, parseHotkey, type Hotkey, } from './runtime/input.js';
+export { createSettings, type SettingsStore } from './runtime/settings.js';
+export { gameDb, type SqlValue } from './bridge/db.js';
+export { beatmapStore, type StoredSetMeta, type StoredVersion, } from './bridge/beatmaps.js';
+export { gameCharacter, type CharacterRow } from './bridge/character.js';
+export { playlists, type PlaylistRow } from './bridge/playlists.js';
+export { playCountsSince, recentPlayCounts } from './bridge/scores.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EACN,QAAQ,EACR,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EACN,aAAa,EACb,YAAY,EACZ,WAAW,EACX,KAAK,MAAM,GACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EACN,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,aAAa,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { Addon } from './runtime/addon.js';
+export { defineAddon } from './runtime/define.js';
+export { gameHost, } from './runtime/host.js';
+export { buildMeta } from './runtime/buildMeta.js';
+export { HotkeyManager, isolateInput, parseHotkey, } from './runtime/input.js';
+export { createSettings } from './runtime/settings.js';
+export { gameDb } from './bridge/db.js';
+export { beatmapStore, } from './bridge/beatmaps.js';
+export { gameCharacter } from './bridge/character.js';
+export { playlists } from './bridge/playlists.js';
+export { playCountsSince, recentPlayCounts } from './bridge/scores.js';

package/dist/react/index.d.ts

@@ -0,0 +1,4 @@
+export { createOverlay, OVERLAY_Z_INDEX, type Overlay, type OverlayOptions, } from './overlay.js';
+export { ReactAddon, type ReactAddonMeta } from './reactAddon.js';
+export { usePersistedSettings, type SettingsHandle } from './useSettings.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,aAAa,EACb,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,cAAc,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,3 @@
+export { createOverlay, OVERLAY_Z_INDEX, } from './overlay.js';
+export { ReactAddon } from './reactAddon.js';
+export { usePersistedSettings } from './useSettings.js';

package/dist/react/overlay.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The overlay host.
+ *
+ * An add-on shares one document with the whole game, so a naive `<div>` on
+ * `document.body` inherits the client's styles and leaks its own back. The host
+ * therefore attaches a **shadow root** and renders inside it: the game's CSS
+ * stops at the boundary, and the add-on's stylesheet cannot restyle the game.
+ *
+ * Input is isolated at the host element, where events from inside the shadow
+ * tree bubble through - see `runtime/input.ts` for why bubble phase is the
+ * right place for that.
+ */
+import type { Disposer } from '../runtime/addon.js';
+/**
+ * Default stacking order: above every piece of game UI, below the cursor.
+ *
+ * The client draws its own osu! cursor as a DOM element (`.cursor`, z-index
+ * 100000, with `.cursor-trail` at 99999) and hides the system one with
+ * `html.custom-cursor * { cursor: none !important }`. An overlay stacked above
+ * that layer breaks the pointer twice over: it covers the drawn cursor, and -
+ * because `cursor` is an inherited property - the `cursor: none` on the host
+ * inherits through the shadow boundary, so the system cursor stays hidden too.
+ * The player is left with no pointer at all, flickering into view only over
+ * translucent parts of the overlay.
+ *
+ * Sitting below the cursor layer instead means the osu! cursor draws over the
+ * overlay exactly as it does over the rest of the game. The game's own UI tops
+ * out around 20000, so this clears it comfortably.
+ */
+export declare const OVERLAY_Z_INDEX = 50000;
+export type OverlayOptions = {
+    /** Element id, so a stale host from a failed unmount can be reclaimed. */
+    id: string;
+    /** CSS for the shadow tree. The bundler inlines `.css` imports into a string. */
+    styles?: string;
+    /**
+     * Stacking order against the game's own layers. Defaults to
+     * {@link OVERLAY_Z_INDEX}; raising it above 99999 will hide the player's
+     * cursor.
+     */
+    zIndex?: number;
+};
+export type Overlay = {
+    /** The element in the page. Input isolation is bound here. */
+    host: HTMLElement;
+    /** The shadow root React renders into. */
+    container: HTMLElement;
+    dispose: Disposer;
+};
+/**
+ * Create the overlay host. Idempotent by `id`: a host left behind by a crashed
+ * unmount is removed rather than duplicated, so enable/disable cycles cannot
+ * stack overlays.
+ */
+export declare const createOverlay: ({ id, styles, zIndex }: OverlayOptions) => Overlay;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/react/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/react/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,MAAM,MAAM,cAAc,GAAG;IAC5B,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACrB,8DAA8D;IAC9D,IAAI,EAAE,WAAW,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,WAAW,CAAC;IACvB,OAAO,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,wBAA0C,cAAc,KAAG,OAkCxF,CAAC"}

package/dist/react/overlay.js

@@ -0,0 +1,63 @@
+/**
+ * The overlay host.
+ *
+ * An add-on shares one document with the whole game, so a naive `<div>` on
+ * `document.body` inherits the client's styles and leaks its own back. The host
+ * therefore attaches a **shadow root** and renders inside it: the game's CSS
+ * stops at the boundary, and the add-on's stylesheet cannot restyle the game.
+ *
+ * Input is isolated at the host element, where events from inside the shadow
+ * tree bubble through - see `runtime/input.ts` for why bubble phase is the
+ * right place for that.
+ */
+import { isolateInput } from '../runtime/input.js';
+/**
+ * Default stacking order: above every piece of game UI, below the cursor.
+ *
+ * The client draws its own osu! cursor as a DOM element (`.cursor`, z-index
+ * 100000, with `.cursor-trail` at 99999) and hides the system one with
+ * `html.custom-cursor * { cursor: none !important }`. An overlay stacked above
+ * that layer breaks the pointer twice over: it covers the drawn cursor, and -
+ * because `cursor` is an inherited property - the `cursor: none` on the host
+ * inherits through the shadow boundary, so the system cursor stays hidden too.
+ * The player is left with no pointer at all, flickering into view only over
+ * translucent parts of the overlay.
+ *
+ * Sitting below the cursor layer instead means the osu! cursor draws over the
+ * overlay exactly as it does over the rest of the game. The game's own UI tops
+ * out around 20000, so this clears it comfortably.
+ */
+export const OVERLAY_Z_INDEX = 50_000;
+/**
+ * Create the overlay host. Idempotent by `id`: a host left behind by a crashed
+ * unmount is removed rather than duplicated, so enable/disable cycles cannot
+ * stack overlays.
+ */
+export const createOverlay = ({ id, styles, zIndex = OVERLAY_Z_INDEX }) => {
+    document.getElementById(id)?.remove();
+    const host = document.createElement('div');
+    host.id = id;
+    // `pointer-events: none` keeps the (full-screen) host from swallowing clicks
+    // meant for the game; the rendered panels turn it back on for themselves.
+    host.style.cssText =
+        `position:fixed;inset:0;z-index:${zIndex};pointer-events:none;`;
+    const shadow = host.attachShadow({ mode: 'open' });
+    if (styles) {
+        const sheet = document.createElement('style');
+        sheet.textContent = styles;
+        shadow.append(sheet);
+    }
+    const container = document.createElement('div');
+    container.style.cssText = 'position:absolute;inset:0;pointer-events:none;';
+    shadow.append(container);
+    document.body.append(host);
+    const releaseInput = isolateInput(host);
+    return {
+        host,
+        container,
+        dispose: () => {
+            releaseInput();
+            host.remove();
+        },
+    };
+};