@scm-js/plugin-api 1.63.0 → 1.65.0

package/README.md

@@ -11,41 +11,49 @@ npm i -D @scm-js/plugin-api
 import type { PluginApi } from "@scm-js/plugin-api";
 
 export function activate(api: PluginApi) {
-  api.ui.toast("Hello from a plugin.");
+  api.ui.toast({ title: "Hello from a plugin." });
 }
 ```
 
-Types only. A plugin imports them with `import type`, which is erased before the editor's
-loader ever sees the specifier — which is what lets this be a normal npm dependency
-without breaking the rule that a plugin's *runtime* code cannot import packages by name.
+The package has types only. Import them with `import type`. TypeScript removes those imports
+before the editor's loader sees the plugin, so it can be an ordinary npm dependency. A
+plugin's run-time code cannot import packages by name, and everything it needs at run time
+arrives on `api`.
+
+## Where to start
+
+- [Plugins](https://docs.scmjs.dev/plugins/) is the author's guide: what a plugin can do and
+  how to write, load and publish one.
+- The [API reference](https://docs.scmjs.dev/api/) lists every call, generated from these
+  declarations.
+- [plugin-hello-world](https://github.com/scm-js/plugin-hello-world) is the smallest working
+  plugin.
 
 ## Versions
 
-The major **is** `PLUGIN_API_VERSION`, so `"^1"` is the range to write and it means what
-it says: the minor moves whenever the declarations change, and a change that would break a
-plugin moves the major and `PLUGIN_API_VERSION` together. The editor's own version is
-deliberately not in here — editor 0.1.0 to 0.2.0 is an ordinary release, and semver would
-read it as a break.
+The package's major version is `PLUGIN_API_VERSION`, which is 1 and has never changed. Write
+`"^1"` as the range. The minor version moves whenever the declarations change. A change that
+would break a plugin would move the major version and `PLUGIN_API_VERSION` together.
+
+The editor's own version is not used here. Going from editor 0.1.0 to 0.2.0 is an ordinary
+release, and semver would read it as a break.
 
-`PLUGIN_API_VERSION` is 1 and has never moved. Your manifest's `"api": 1` is the version
-your plugin *needs*; an editor providing an older one refuses to load it.
+Your manifest's `"api": 1` is the version your plugin needs. An editor that provides an
+older one will not load it.
 
 ## This repository
 
-**Nothing here is written by hand** except this README and the LICENSE. `index.d.ts` and
-`package.json` are generated from `src/plugins/api.ts` in the editor by
-`npm run build:plugin-types` and published from there, so the contract has one source and
-one copy of its declarations. `main` is the tip; each `v*` tag is a published version.
+Only this README and the LICENSE are written by hand. `index.d.ts` and `package.json` are
+generated from `src/plugins/api.ts` in the editor by `npm run build:plugin-types`, and
+published from there. `main` is the newest version, and each `v*` tag is a published one.
 
-It exists beside the registry as the audit trail behind the tarball, and as the way in for
-anyone whose registry the package is not on — `npm i -D github:scm-js/plugin-api#v1.0.0`
-works and installs exactly the same two files.
+The repository is the record behind each npm release. It is also a way to install the
+package without the npm registry:
 
-## What the API covers
+```sh
+npm i -D github:scm-js/plugin-api#v1.64.0
+```
 
-[`docs/plugins.md`](https://github.com/scm-js/scm-js/blob/main/docs/plugins.md) in the
-editor is the author's guide and the tour of what a plugin can do; this repository is only
-the typings for it. [`plugin-hello-world`](https://github.com/scm-js/plugin-hello-world) is
-the smallest working example.
+That installs the same files as the registry.
 
 MIT, like the editor.

package/index.d.ts

@@ -2292,10 +2292,14 @@ export interface Preferences {
 	 * Tools ▸ Test Map: whether to start the game after writing the map (desktop build), and
 	 * the game folder to use when the desktop build should not search ("" = search). The
 	 * browser's folder is a handle in IndexedDB (`services/handleStore.ts`), not here.
+	 * `target` is where Test Map, Ctrl+F5 and the toolbar send the map: `"starcraft"`, a
+	 * plugin's id for its `ui.testTarget`, or `""` — a plugin's target where there is one
+	 * (the browser at scmjs.dev), StarCraft otherwise (`services/testTargets.ts`).
 	 */
 	testMap: {
 		launch: boolean;
 		dir: string;
+		target: string;
 	};
 	/**
 	 * The desktop build's in-app updates (`editor/updates.ts`, `desktop/updater.ts`); the
@@ -2687,7 +2691,8 @@ export interface BuildStepSpec {
 	 * Build. Return an archive (or a bare scenario) — the editor takes the scenario and any
 	 * *new* members from it and lays the final file out with the user's save options; the
 	 * map's own members are written as they were. Throw an `Error` whose message says what
-	 * is wrong in the user's terms.
+	 * is wrong in the user's terms. A plain `Error` is logged as a warning, a refusal the step
+	 * meant; anything else thrown (a `TypeError`, a class of your own) is logged as an error.
 	 */
 	run(input: BuildStepInput): Promise<Uint8Array>;
 }
@@ -2707,7 +2712,8 @@ export interface BeforeBuildSpec {
 	/**
 	 * May be asynchronous and may write to the document. A throw does not stop the save:
 	 * the map is written as it stands and a notice shows the error's message, so word it
-	 * for the user. Inside it `document.export()` answers the map as it stands, without
+	 * for the user. As with a build step, a plain `Error` is logged as a warning and anything
+	 * else as an error. Inside it `document.export()` answers the map as it stands, without
 	 * running anything.
 	 */
 	run(ctx: {
@@ -5427,6 +5433,50 @@ export interface PreferencesPageSpec {
 	/** Called by Reset to defaults while the page is the one showing. */
 	reset?(): void;
 }
+/**
+ * Another place Tools ▸ Test Map can send the map — `ui.testTarget`. The editor's own
+ * target is StarCraft (the file written where the game lists it); a target of a plugin's
+ * is a choice beside it on Edit ▸ Preferences ▸ Testing, a Tools menu item of its own
+ * ("Test in …"), and, when the user picks it there, what Test Map, Ctrl+F5 and the
+ * toolbar's Test button do.
+ *
+ * @example
+ * api.ui.testTarget({
+ *   label: "This browser",
+ *   menuLabel: "Test in Browser",
+ *   description: "Plays the map in a tab of its own.",
+ *   run: (map) => { const tab = window.open("/play/"); void map.then((m) => m && send(tab, m)); },
+ * });
+ */
+export interface TestTargetSpec {
+	/** What the choice is called on Preferences ▸ Testing: "This browser". Translated through the plugin's catalogue. */
+	label: string;
+	/** The Tools menu item that tests here whatever the choice is: "Test in Browser". */
+	menuLabel: string;
+	/** A line under the choice saying what happens. */
+	description?: string;
+	/**
+	 * Test the map. It is called inside the click or key press itself, before the map is
+	 * built, so a target that opens a window can open it at once — a browser lets a click
+	 * open a tab, not what follows it later. `map` resolves with the file as Save would
+	 * write it (build steps run, always an archive), or null when there is none; it
+	 * rejects when the build fails. A promise this returns that rejects is shown to the
+	 * user as the reason the test did not start; what it resolves with is the status-bar
+	 * line (nothing is shown for none).
+	 */
+	run(map: Promise<TestMapFile | null>): void | Promise<string | void>;
+	/**
+	 * The target's own settings, drawn under its label on Preferences ▸ Testing — the same
+	 * `mount` / `apply` / `reset` as `PreferencesPageSpec`.
+	 */
+	settings?: PreferencesPageSpec;
+}
+/** The map a test target is handed. */
+export interface TestMapFile {
+	bytes: Uint8Array;
+	/** The file name the game would list, `.scx` or `.scm`. */
+	name: string;
+}
 /** What a preferences page's `mount` is handed. */
 export interface PreferencesPageHost {
 	readonly plugin: PluginInfo;
@@ -5721,6 +5771,12 @@ export interface UiApi {
 	 * Returns the registration; it leaves with `dispose()` or the plugin.
 	 */
 	preferencesPage(spec: PreferencesPageSpec): Disposable;
+	/**
+	 * A place Test Map can send the map besides StarCraft — see `TestTargetSpec`. One per
+	 * plugin: a second registration takes the first one's place. Returns the registration;
+	 * it leaves with `dispose()` or the plugin, and Test Map goes back to StarCraft.
+	 */
+	testTarget(spec: TestTargetSpec): Disposable;
 	/**
 	 * Take over the pointer on the map until `stop()`, Esc, a right-click, a map change
 	 * or another tool. One tool runs at a time — starting one stops the previous — and a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scm-js/plugin-api",
-  "version": "1.63.0",
+  "version": "1.65.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",