@oss-idle/addon-sdk 0.5.0 → 0.6.0

package/README.md

@@ -22,8 +22,11 @@ That emits one self-contained ES module. Paste it into the in-game add-on editor
 ## 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.
+`mount` / `unmount`. `mount` is handed the game's host (`this.host` in an
+`Addon`): its version, its React, and the editor for add-ons of the Editor type.
+Add-ons run unsandboxed in the page realm and reach for the rest themselves. The
+full guide, the editor API included, is at
+https://oss.idle.rhythmgamers.net/web/docs/addons.
 
 ```ts
 import { Addon, defineAddon } from '@oss-idle/addon-sdk';
@@ -49,6 +52,35 @@ Two things follow from that, and they shape the whole SDK:
    through `this.on`, `this.interval`, `this.timeout` or `this.own` is torn down
    for you, in reverse order, even if one teardown throws.
 
+## Editor add-ons
+
+An add-on of the Editor type (picked when you make it in game) reaches the map
+editor while it is open. Everything registered through the editor's API goes when
+the editor closes or the add-on unmounts.
+
+```ts
+class Mirror extends Addon {
+	constructor() { super({ name: 'Mirror' }); }
+
+	protected onMount() {
+		this.editor(editor => {
+			editor.addAction({
+				id: 'mirror-selection', label: 'Mirror the selected notes', keys: ['Alt+M'],
+				run: () => {
+					const picked = new Set(editor.selection());
+					editor.edit({
+						notes: editor.notes().map(note => picked.has(note)
+							? { ...note, column: editor.keys - 1 - note.column } : note),
+					});
+				},
+			});
+		});
+	}
+}
+```
+
+`EditorApi` and the other host types are exported from the package.
+
 ## React overlays
 
 ```tsx
@@ -197,6 +229,7 @@ moderator before they go live.
 | `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. |
+| `plugins` | Extra esbuild plugins for the add-on and its workers, run before the SDK's own - e.g. to redirect one of the game's imports to your own module. |
 
 ### Using the game's own code
 
@@ -218,6 +251,13 @@ 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.
 
+### The game's React
+
+Set `"sharedReact": true` in `addon.config.json` (the template does) and the
+bundle reads React from the game instead of shipping its own: one React on the
+page, and a smaller add-on. A game too old to hand out its React refuses the
+add-on with a message; leave the option off to support those.
+
 ## Licence
 
 AGPL-3.0-only.

package/bin/cli.mjs

@@ -110,6 +110,7 @@ const run = async () => {
 		stubModules: config.stubModules,
 		dedupe: config.dedupe,
 		dedupeFrom: cwd,
+		sharedReact: !!config.sharedReact,
 		meta: {
 			name: config.name,
 			version: pkgVersion,

package/bin/scaffold.mjs

@@ -138,6 +138,7 @@ export const scaffold = async ({
 			build: 'oss-idle-addon build',
 			dev: 'oss-idle-addon build --watch',
 			typecheck: 'tsc -p tsconfig.json --noEmit',
+			lint: 'eslint .',
 		},
 		dependencies: {
 			'@oss-idle/addon-sdk': await sdkVersion(),
@@ -145,7 +146,9 @@ export const scaffold = async ({
 		},
 		devDependencies: {
 			...(react ? { '@types/react': '^18.3.12', '@types/react-dom': '^18.3.1' } : {}),
+			eslint: '^10.13.0',
 			typescript: '^5.6.3',
+			'typescript-eslint': '^8.72.0',
 		},
 	};
 	await writeFile(join(target, 'package.json'), JSON.stringify(pkg, null, 2) + '\n', 'utf8');

package/dist/build/index.d.ts

@@ -13,12 +13,13 @@
  * moderator before they go live, and a single minified line is a poor thing to
  * ask anyone to review.
  */
+import { type Plugin } from 'esbuild';
 /**
  * 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, inlineWorkerPlugin, sharedSourcePlugin, stubModulePlugin, tsExtensionPlugin, } from './plugins.js';
+export { assetQueryPlugin, cssTextPlugin, dedupePlugin, hostReactPlugin, inlineWorkerPlugin, sharedSourcePlugin, stubModulePlugin, tsExtensionPlugin, } from './plugins.js';
 export type BundleOptions = {
     /** Entry module, exporting `mount` / `unmount` (usually via `defineAddon`). */
     entry: string;
@@ -49,6 +50,18 @@ export type BundleOptions = {
     dedupe?: readonly string[];
     /** Directory the deduped packages resolve from. Defaults to the entry's directory. */
     dedupeFrom?: string;
+    /**
+     * Extra esbuild plugins, for the add-on and every inlined worker. They run
+     * before the SDK's own, so an `onResolve` here can redirect an import -
+     * one of the game's own modules, say - before the SDK resolves it.
+     */
+    plugins?: readonly Plugin[];
+    /**
+     * Use the game's React (`globalThis.ossIdle.react`) instead of bundling one:
+     * a much smaller add-on, and one React on the page. Needs an oss!idle that
+     * hands its React to add-ons; an older one refuses the add-on with a message.
+     */
+    sharedReact?: boolean;
 };
 export type BundleResult = {
     outfile: string;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH;;;;GAIG;AACH,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GACjB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,aAAa,GAAG;IAC3B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAChD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA2DF,MAAM,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AASF,oEAAoE;AACpE,eAAO,MAAM,WAAW,GAAU,SAAS,aAAa,KAAG,OAAO,CAAC,YAAY,CA+C9E,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAuC,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAe3E;;;;GAIG;AACH,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GACjB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,aAAa,GAAG;IAC3B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAChD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AA8DF,MAAM,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AASF,oEAAoE;AACpE,eAAO,MAAM,WAAW,GAAU,SAAS,aAAa,KAAG,OAAO,CAAC,YAAY,CAiD9E,CAAC"}

package/dist/build/index.js

@@ -17,16 +17,16 @@ 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, inlineWorkerPlugin, sharedSourcePlugin, stubModulePlugin, tsExtensionPlugin, } from './plugins.js';
+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, inlineWorkerPlugin, sharedSourcePlugin, stubModulePlugin, tsExtensionPlugin, } from './plugins.js';
+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()) => ({
+const baseOptions = (gameRoot, minify, stubModules = {}, dedupe = [], dedupeFrom = process.cwd(), plugins = []) => ({
     bundle: true,
     format: 'esm',
     platform: 'browser',
@@ -42,6 +42,7 @@ const baseOptions = (gameRoot, minify, stubModules = {}, dedupe = [], dedupeFrom
     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
@@ -54,9 +55,9 @@ const baseOptions = (gameRoot, minify, stubModules = {}, dedupe = [], dedupeFrom
     ],
 });
 /** Build one worker entry to a self-contained string for inlining. */
-const buildWorkerSource = async (entry, gameRoot, minify, stubModules, dedupe, dedupeFrom) => {
+const buildWorkerSource = async (entry, gameRoot, minify, stubModules, dedupe, dedupeFrom, plugins) => {
     const result = await esbuild({
-        ...baseOptions(gameRoot, minify, stubModules, dedupe, dedupeFrom),
+        ...baseOptions(gameRoot, minify, stubModules, dedupe, dedupeFrom, plugins),
         entryPoints: [entry],
         write: false,
         // A worker built as ESM would need `type: 'module'` support *and* would
@@ -72,12 +73,14 @@ const buildWorkerSource = async (entry, gameRoot, minify, stubModules, dedupe, d
 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)), } = 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.
-    const names = [...new Set(['react', 'react-dom', ...dedupe])];
-    const base = baseOptions(gameRoot, minify, stubModules, names, dedupeFrom);
+    // 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()`.
@@ -86,7 +89,7 @@ export const bundleAddon = async (options) => {
         write: false,
         sourcemap: sourcemap ? 'inline' : false,
         plugins: [
-            inlineWorkerPlugin(workerEntry => buildWorkerSource(workerEntry, gameRoot, minify, stubModules, dedupe, dedupeFrom)),
+            inlineWorkerPlugin(workerEntry => buildWorkerSource(workerEntry, gameRoot, minify, stubModules, dedupe, dedupeFrom, plugins)),
             ...(base.plugins ?? []),
         ],
     });

package/dist/build/plugins.d.ts

@@ -85,4 +85,11 @@ export declare const dedupePlugin: (names: readonly string[], fromDir: string) =
  * (`.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

@@ -1 +1 @@
-{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/build/plugins.ts"],"names":[],"mappings":"AAGA,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"}
+{"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

@@ -1,5 +1,6 @@
 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.
@@ -211,3 +212,29 @@ export const assetQueryPlugin = () => ({
         });
     },
 });
+/**
+ * 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

@@ -1,5 +1,6 @@
 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';

package/dist/index.d.ts.map

@@ -1 +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,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"}
+{"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

@@ -1,5 +1,6 @@
 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';

package/dist/runtime/addon.d.ts

@@ -3,9 +3,10 @@
  *
  * oss!idle loads an add-on by turning its `source` into a Blob URL and
  * `import()`ing it in the page realm, then calling the module's `mount` /
- * `unmount` exports - that pair *is* the contract, and nothing else is passed
- * in. Everything a useful add-on needs (the game's database, its beatmap store,
- * the DOM) it reaches for itself, because it runs unsandboxed on the page.
+ * `unmount` exports - that pair *is* the contract. `mount` is handed the game's
+ * host (its React, the editor for add-ons of the Editor type: {@link host});
+ * the rest (the game's database, its beatmap store, the DOM) an add-on reaches
+ * for itself, because it runs unsandboxed on the page.
  *
  * Two consequences shape this class:
  *
@@ -18,6 +19,7 @@
  *   hands out registration helpers that record their own teardown, and reverses
  *   them for you.
  */
+import { type AddonHost, type EditorApi } from './host.js';
 /** A teardown returned by a registration; running it undoes that registration. */
 export type Disposer = () => void;
 export type AddonMeta = {
@@ -70,7 +72,16 @@ export declare abstract class Addon {
      * Public only because `defineAddon` lives outside the class and TypeScript
      * has no package-private visibility; the underscore marks it as off-limits.
      */
-    _mount(): Promise<void>;
+    _mount(host?: AddonHost): Promise<void>;
+    private handed?;
+    /** The game's host: React, the editor. Undefined on a game too old to hand one. */
+    protected get host(): AddonHost | undefined;
+    /**
+     * Work with the editor while it is open (an add-on of the Editor type):
+     * `onOpen` runs each time it opens, with its API. What is registered through
+     * that API goes when the editor closes or this add-on unmounts.
+     */
+    protected editor(onOpen: (editor: EditorApi) => void, onClose?: () => void): void;
     /**
      * Internal: called by {@link defineAddon}, not by add-on code.
      *

package/dist/runtime/addon.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"addon.d.ts","sourceRoot":"","sources":["../../src/runtime/addon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC;AAElC,MAAM,MAAM,SAAS,GAAG;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,8BAAsB,KAAK;IAE1B,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEnC,mEAAmE;IACnE,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,SAAS;IAI3B,8EAA8E;IAC9E,SAAS,CAAC,QAAQ,CAAC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD,6EAA6E;IAC7E,SAAS,CAAC,SAAS,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3C,oFAAoF;IACpF,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,QAAQ,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC;IAKhD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EAC3C,OAAO,CAAC,EAAE,uBAAuB,GAC/B,QAAQ;IACX,SAAS,CAAC,EAAE,CACX,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kCAAkC,EAC3C,OAAO,CAAC,EAAE,uBAAuB,GAC/B,QAAQ;IAWX,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ;IAK7D,uEAAuE;IACvE,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ;IAK5D,8EAA8E;IAC9E,SAAS,KAAK,GAAG;wBAGC,OAAO,EAAE;wBACT,OAAO,EAAE;yBACR,OAAO,EAAE;MAE3B;IAED;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAkB/B"}
+{"version":3,"file":"addon.d.ts","sourceRoot":"","sources":["../../src/runtime/addon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAEN,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,WAAW,CAAC;AAEnB,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC;AAElC,MAAM,MAAM,SAAS,GAAG;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,8BAAsB,KAAK;IAE1B,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEnC,mEAAmE;IACnE,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,SAAS;IAI3B,8EAA8E;IAC9E,SAAS,CAAC,QAAQ,CAAC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD,6EAA6E;IAC7E,SAAS,CAAC,SAAS,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3C,oFAAoF;IACpF,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,QAAQ,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC;IAKhD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EAC3C,OAAO,CAAC,EAAE,uBAAuB,GAC/B,QAAQ;IACX,SAAS,CAAC,EAAE,CACX,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kCAAkC,EAC3C,OAAO,CAAC,EAAE,uBAAuB,GAC/B,QAAQ;IAWX,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ;IAK7D,uEAAuE;IACvE,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ;IAK5D,8EAA8E;IAC9E,SAAS,KAAK,GAAG;wBAGC,OAAO,EAAE;wBACT,OAAO,EAAE;yBACR,OAAO,EAAE;MAE3B;IAED;;;;;OAKG;IACG,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,OAAO,CAAC,MAAM,CAAC,CAAY;IAE3B,mFAAmF;IACnF,SAAS,KAAK,IAAI,IAAI,SAAS,GAAG,SAAS,CAE1C;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI;IASjF;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAkB/B"}

package/dist/runtime/addon.js

@@ -3,9 +3,10 @@
  *
  * oss!idle loads an add-on by turning its `source` into a Blob URL and
  * `import()`ing it in the page realm, then calling the module's `mount` /
- * `unmount` exports - that pair *is* the contract, and nothing else is passed
- * in. Everything a useful add-on needs (the game's database, its beatmap store,
- * the DOM) it reaches for itself, because it runs unsandboxed on the page.
+ * `unmount` exports - that pair *is* the contract. `mount` is handed the game's
+ * host (its React, the editor for add-ons of the Editor type: {@link host});
+ * the rest (the game's database, its beatmap store, the DOM) an add-on reaches
+ * for itself, because it runs unsandboxed on the page.
  *
  * Two consequences shape this class:
  *
@@ -19,6 +20,7 @@
  *   them for you.
  */
 import { buildMeta } from './buildMeta.js';
+import { gameHost, } from './host.js';
 /**
  * Base class for an add-on. Subclass it, implement {@link onMount}, and export
  * the pair the runtime wants with {@link defineAddon}.
@@ -71,12 +73,31 @@ export class Addon {
      * Public only because `defineAddon` lives outside the class and TypeScript
      * has no package-private visibility; the underscore marks it as off-limits.
      */
-    async _mount() {
+    async _mount(host) {
         if (this.mounted)
             return;
         this.mounted = true;
+        this.handed = host;
         await this.onMount();
     }
+    handed;
+    /** The game's host: React, the editor. Undefined on a game too old to hand one. */
+    get host() {
+        return this.handed ?? gameHost();
+    }
+    /**
+     * Work with the editor while it is open (an add-on of the Editor type):
+     * `onOpen` runs each time it opens, with its API. What is registered through
+     * that API goes when the editor closes or this add-on unmounts.
+     */
+    editor(onOpen, onClose) {
+        const host = this.host;
+        if (!host) {
+            this.log.warn('this game hands add-ons no editor: update oss!idle');
+            return;
+        }
+        this.own(host.editor.watch(onOpen, onClose));
+    }
     /**
      * Internal: called by {@link defineAddon}, not by add-on code.
      *

package/dist/runtime/define.d.ts

@@ -1,8 +1,9 @@
 import { Addon } from './addon.js';
+import type { AddonHost } from './host.js';
 /** The module shape oss!idle's add-on runtime imports and drives. */
 export type AddonModule = {
-    mount: () => void;
-    unmount: () => void;
+    mount: (meta?: unknown, host?: AddonHost) => void;
+    unmount: () => Promise<void>;
 };
 /**
  * Turn an {@link Addon} subclass into the `mount` / `unmount` pair the runtime
@@ -12,9 +13,11 @@ export type AddonModule = {
  * export const { mount, unmount } = defineAddon(() => new MyAddon());
  * ```
  *
- * The runtime calls both synchronously and ignores what they return, so an
+ * The runtime calls `mount` synchronously and ignores what it returns, so an
  * async `onMount` is started and left to run - its failure is reported here
  * rather than surfacing as an unhandled rejection in the player's console.
+ * `unmount` returns its teardown, which the runtime awaits before mounting an
+ * updated version.
  *
  * A mount still settling when `unmount` arrives (disable clicked mid-boot) is
  * awaited first, so teardown never races a half-built overlay.

package/dist/runtime/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/runtime/define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG;IACzB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAK,KAAG,WAqBjD,CAAC"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/runtime/define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG;IACzB,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;IAClD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAK,KAAG,WAsBjD,CAAC"}

package/dist/runtime/define.js

@@ -6,9 +6,11 @@
  * export const { mount, unmount } = defineAddon(() => new MyAddon());
  * ```
  *
- * The runtime calls both synchronously and ignores what they return, so an
+ * The runtime calls `mount` synchronously and ignores what it returns, so an
  * async `onMount` is started and left to run - its failure is reported here
  * rather than surfacing as an unhandled rejection in the player's console.
+ * `unmount` returns its teardown, which the runtime awaits before mounting an
+ * updated version.
  *
  * A mount still settling when `unmount` arrives (disable clicked mid-boot) is
  * awaited first, so teardown never races a half-built overlay.
@@ -17,21 +19,22 @@ export const defineAddon = (create) => {
     let instance;
     let settling = Promise.resolve();
     return {
-        mount: () => {
+        mount: (_meta, host) => {
             instance = create();
             const addon = instance;
-            settling = addon._mount().catch((e) => {
+            settling = addon._mount(host).catch((e) => {
                 console.error('[addon] mount failed', e);
             });
         },
         unmount: () => {
             const addon = instance;
             if (!addon)
-                return;
+                return settling;
             instance = undefined;
             settling = settling
                 .then(() => addon._unmount())
                 .catch((e) => console.error('[addon] unmount failed', e));
+            return settling;
         },
     };
 };

package/dist/runtime/host.d.ts

@@ -0,0 +1,113 @@
+/**
+ * What the game hands an add-on: `mount(meta, host)`, and the same object on
+ * `globalThis.ossIdle` for code that runs before `mount` (the `sharedReact`
+ * build reads React there). Mirrors the game's `addons/host.ts` and
+ * `editor/editorApi.ts`; an older game hands none.
+ */
+/** A teardown; running it undoes what returned it. */
+type Disposer = () => void;
+/** A note as the editor holds it; `end` makes it a long note. */
+export type EditorNote = {
+    time: number;
+    column: number;
+    end?: number;
+    /** the .osu hitSound bits, as written */
+    hitSound: string;
+    /** the .osu sample fields, as written */
+    sample: string;
+};
+export type EditorTimingPoint = {
+    time: number;
+    /** ms per beat for a BPM point; -100 / the multiplier for a scroll speed one */
+    beatLength: number;
+    meter: number;
+    sound: string;
+    effects: string;
+};
+export type EditorMetadata = {
+    title: string;
+    titleUnicode: string;
+    artist: string;
+    artistUnicode: string;
+    creator: string;
+    version: string;
+    source: string;
+    tags: string;
+    previewTime: number;
+};
+/** Draws into `container`; what it returns runs when it goes. */
+export type EditorRender = (container: HTMLElement) => void | (() => void);
+/**
+ * The open editor. Notes and points are the editor's own objects: read them,
+ * never change them, and hand new ones to `edit`. Everything registered here
+ * goes when the editor closes or the add-on stops.
+ */
+export type EditorApi = {
+    readonly keys: number;
+    notes(): readonly EditorNote[];
+    timing(): readonly EditorTimingPoint[];
+    scroll(): readonly EditorTimingPoint[];
+    metadata(): Readonly<EditorMetadata>;
+    bookmarks(): readonly number[];
+    text(): string;
+    edit(change: {
+        notes?: EditorNote[];
+        timing?: EditorTimingPoint[];
+        scroll?: EditorTimingPoint[];
+        bookmarks?: number[];
+        metadata?: Partial<EditorMetadata>;
+    }, select?: EditorNote[]): void;
+    undo(): void;
+    redo(): void;
+    save(): void;
+    selection(): EditorNote[];
+    select(notes: EditorNote[]): void;
+    now(): number;
+    seek(ms: number): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    snap(ms: number): number;
+    divisor(): number;
+    setDivisor(divisor: number): void;
+    onChange(callback: () => void): Disposer;
+    addAction(action: {
+        id: string;
+        label: string;
+        keys?: string[];
+        run: () => void;
+    }): Disposer;
+    addTab(tab: {
+        id: string;
+        label: string;
+        render: EditorRender;
+    }): Disposer;
+    addPanel(panel: {
+        id: string;
+        title?: string;
+        render: EditorRender;
+    }): Disposer;
+    openWindow(window: {
+        title: string;
+        width?: number;
+        height?: number;
+        render: EditorRender;
+        onClose?: () => void;
+    }): {
+        close(): void;
+    };
+};
+export type AddonHost = {
+    /** the game's version */
+    version: string;
+    /** the game's React modules by import path */
+    react: Record<string, unknown>;
+    editor: {
+        /** `onOpen` runs whenever the editor opens (now, if it is open), `onClose` when it closes. */
+        watch(onOpen: (editor: EditorApi) => void, onClose?: () => void): Disposer;
+    };
+};
+/** The game's host, if it hands one out (older games do not). */
+export declare const gameHost: () => AddonHost | undefined;
+export {};
+//# sourceMappingURL=host.d.ts.map

package/dist/runtime/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/runtime/host.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sDAAsD;AACtD,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAE3B,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,WAAW,KAAK,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,KAAK,IAAI,SAAS,UAAU,EAAE,CAAC;IAC/B,MAAM,IAAI,SAAS,iBAAiB,EAAE,CAAC;IACvC,MAAM,IAAI,SAAS,iBAAiB,EAAE,CAAC;IACvC,QAAQ,IAAI,QAAQ,CAAC,cAAc,CAAC,CAAC;IACrC,SAAS,IAAI,SAAS,MAAM,EAAE,CAAC;IAC/B,IAAI,IAAI,MAAM,CAAC;IACf,IAAI,CAAC,MAAM,EAAE;QACZ,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;QACrB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;QAC7B,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;QAC7B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;KACnC,EAAE,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAChC,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,IAAI,IAAI,CAAC;IACb,IAAI,IAAI,IAAI,CAAC;IACb,SAAS,IAAI,UAAU,EAAE,CAAC;IAC1B,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IAClC,GAAG,IAAI,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,SAAS,IAAI,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,OAAO,IAAI,MAAM,CAAC;IAClB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,QAAQ,CAAC;IACzC,SAAS,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG,QAAQ,CAAC;IAC7F,MAAM,CAAC,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,GAAG,QAAQ,CAAC;IAC3E,QAAQ,CAAC,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,GAAG,QAAQ,CAAC;IAChF,UAAU,CAAC,MAAM,EAAE;QAClB,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;KAC3F,GAAG;QAAE,KAAK,IAAI,IAAI,CAAA;KAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACvB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,EAAE;QACP,8FAA8F;QAC9F,KAAK,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,QAAQ,CAAC;KAC3E,CAAC;CACF,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,QAAQ,QAAO,SAAS,GAAG,SACQ,CAAC"}

package/dist/runtime/host.js

@@ -0,0 +1,8 @@
+/**
+ * What the game hands an add-on: `mount(meta, host)`, and the same object on
+ * `globalThis.ossIdle` for code that runs before `mount` (the `sharedReact`
+ * build reads React there). Mirrors the game's `addons/host.ts` and
+ * `editor/editorApi.ts`; an older game hands none.
+ */
+/** The game's host, if it hands one out (older games do not). */
+export const gameHost = () => globalThis.ossIdle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-idle/addon-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "oss!idle Addon SDK - build oss!idle add-ons in TypeScript. An Addon base class with automatic teardown, shadow-root React overlays, bridges to the game's database and beatmap store, and a bundler that emits the single-file ES module the add-on runtime loads.",

package/templates/common/README.md

@@ -15,6 +15,25 @@ into the in-game add-on editor (Options → Add-ons → Manage) and enable it.
 
 `npm run dev` rebuilds on save; re-paste to see changes.
 
+## Publish from a repository
+
+Instead of pasting, oss!idle can build your add-on from a public git repository
+(any host: GitHub, GitLab, Codeberg...):
+
+1. Push this folder with its `package-lock.json` (`dist/` stays out of git).
+2. In game, create an add-on, choose **Built from a git repository** and give the
+   repository's https address.
+3. Add the webhook address it shows to your repository as a push webhook.
+4. Release by tagging: `npm version patch && git push --follow-tags`.
+
+oss!idle refuses a built file that can run code nobody reviewed: `eval`, `new Function`,
+`import()`, imports from an address, script elements, string timers and the like.
+`npm run lint` flags them in your own code before you push.
+
+Each new version tag is built by oss!idle itself (`npm ci`, then `npm run build`,
+offline, with install scripts skipped) and goes to review; the moderator reads the
+repository's changes, never the bundle.
+
 ## How an add-on runs
 
 The game imports your built file as an ES module from a Blob URL and calls its

package/templates/common/addon.config.json

@@ -2,5 +2,6 @@
   "name": "__ADDON_NAME__",
   "license": "__LICENSE__",
   "entry": "src/index.ts",
-  "outfile": "dist/__SLUG__.js"
+  "outfile": "dist/__SLUG__.js",
+  "sharedReact": true
 }

package/templates/common/eslint.config.js

@@ -0,0 +1,54 @@
+import tseslint from 'typescript-eslint';
+
+// oss!idle refuses an add-on whose built file can run code nobody reviewed: text turned
+// into code, or code loaded from elsewhere. It checks the bundle when you publish;
+// `npm run lint` tells you sooner, in your own code.
+const NOT_REVIEWED = 'oss!idle refuses code that runs what was not reviewed';
+
+export default tseslint.config(
+	{ ignores: ['dist/', 'node_modules/'] },
+	{
+		files: ['**/*.{js,jsx,mjs,ts,tsx,mts}'],
+		languageOptions: {
+			parser: tseslint.parser,
+			// no-implied-eval only knows the timers as globals
+			globals: Object.fromEntries(['window', 'self', 'globalThis', 'setTimeout', 'setInterval']
+				.map(name => [name, 'readonly'])),
+		},
+		rules: {
+			'no-eval': 'error',
+			'no-implied-eval': 'error',
+			'no-new-func': 'error',
+			'no-script-url': 'error',
+			'no-restricted-globals': ['error', 'eval', 'Function', 'importScripts'],
+			'no-restricted-properties': ['error',
+				{ object: 'document', property: 'write', message: NOT_REVIEWED },
+				{ object: 'document', property: 'writeln', message: NOT_REVIEWED },
+				{ property: 'eval', message: NOT_REVIEWED },
+				{ property: 'Function', message: NOT_REVIEWED },
+				{ property: 'srcdoc', message: NOT_REVIEWED },
+				{ property: 'createContextualFragment', message: NOT_REVIEWED },
+				{ property: 'serviceWorker', message: NOT_REVIEWED },
+			],
+			'no-restricted-syntax': ['error',
+				{ selector: 'ImportExpression', message: `import() loads code from elsewhere: ${NOT_REVIEWED}` },
+				{
+					selector: 'ImportDeclaration[source.value=/^([a-z]+:|\\/\\/)/i]',
+					message: `Imports from an address load code from elsewhere: ${NOT_REVIEWED}`,
+				},
+				{
+					selector: 'CallExpression[callee.property.name=/^createElement(NS)?$/] > Literal[value=/^\\s*script\\s*$/i]',
+					message: `A script element loads or runs code: ${NOT_REVIEWED}`,
+				},
+				{
+					selector: 'CallExpression[callee.property.name=/^setAttribute(NS)?$/] > Literal[value=/^on/i]',
+					message: `An on… attribute runs its text as code: use addEventListener. ${NOT_REVIEWED}`,
+				},
+				{
+					selector: 'CallExpression[callee.property.name="constructor"], NewExpression[callee.property.name="constructor"]',
+					message: `A function's constructor builds code from text: ${NOT_REVIEWED}`,
+				},
+			],
+		},
+	},
+);