@scm-js/plugin-api 1.64.0 → 1.66.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

@@ -1155,6 +1155,13 @@ export interface SyncFieldsOp {
 		extended: boolean;
 		encoding: TextEncoding;
 	};
+	/**
+	 * For each field in `set`, `fieldHash` of the value the change was made from — what the
+	 * sender's dialog showed. A receiver whose copy holds something else learns that the op
+	 * writes over a version its sender never saw (`Applied.overwritten`). Absent from ops
+	 * sent by older editors, which are then never reported as overwriting.
+	 */
+	from?: Partial<Record<SyncField, string>>;
 }
 export interface SyncExtrasOp {
 	kind: "extras";
@@ -1241,6 +1248,34 @@ export interface HistoryEdit {
 	 * redo atoms apply it with `applyTables`.
 	 */
 	tables?: TablesEdit;
+	/**
+	 * A change to the whole map — Resize / Crop, Change Tileset: the map as it stands on the
+	 * other side of the step (`WholeState`). Undo and redo swap it with the scenario's own and
+	 * keep what they took out here, so the entry always holds the side it is not on. An entry
+	 * with this part has no other: `applyEntry` leaves it alone, and the undo and redo atoms
+	 * apply it with `swapWholeState`.
+	 */
+	whole?: WholeState;
+}
+/**
+ * What a whole-map change replaces: the size, the tileset and every list or grid that is
+ * laid out by the map's size. Held by reference, not copied — Resize and Change Tileset
+ * build new arrays rather than writing into the old ones, and every later in-place edit is
+ * on the undo stack above the entry, so by the time the entry is undone the arrays it took
+ * out are exactly as it left them.
+ */
+export interface WholeState {
+	width: number;
+	height: number;
+	era: number;
+	tiles: Uint16Array;
+	editorTiles: Uint16Array;
+	isom: Uint16Array | null;
+	mask: Uint8Array | null;
+	units: Scenario["units"];
+	sprites: Scenario["sprites"];
+	doodads: Scenario["doodads"];
+	locations: Scenario["locations"];
 }
 /**
  * Why the map changed: an edit recorded in the history, an undo or redo of one, a dialog
@@ -2292,10 +2327,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
@@ -2991,8 +3030,8 @@ export interface DocumentApi {
 		launch?: boolean;
 	}): Promise<TestMapOutcome | null>;
 	/**
-	 * Scenario ▸ Resize / Crop Map: a transaction outside the undo model that drops both
-	 * history stacks (as the dialog does). Content keeps its place relative to `anchor`
+	 * Scenario ▸ Resize / Crop Map: one undo step, as the dialog is (on a shared map, where
+	 * it replaces everyone's map, both history stacks are dropped instead). Content keeps its place relative to `anchor`
 	 * (a 3 × 3 grid, row-major, 4 = centre, the default); the new ground is `terrainId`
 	 * (the tileset's default when omitted); objects outside the new bounds are dropped,
 	 * locations clamped unless `clampLocations` is false. Null with no map.
@@ -3002,7 +3041,7 @@ export interface DocumentApi {
 	 * Scenario ▸ Map Properties ▸ Tileset: change ERA and lay the terrain again with the
 	 * new tileset's terrain (tile numbers do not carry across tilesets; the doodads go with
 	 * them, everything else stays). Waits for the new graphics so the fill uses real tiles.
-	 * Like `resize`, a transaction outside the undo model. Null with no map.
+	 * Like `resize`, one undo step (on a shared map, the history is dropped instead). Null with no map.
 	 */
 	changeTileset(options: ChangeTilesetOptions): Promise<ChangeTilesetResult | null>;
 	readonly extras: ExtrasApi;
@@ -5429,6 +5468,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;
@@ -5723,6 +5806,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.64.0",
+  "version": "1.66.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",