@scm-js/plugin-api 1.8.0 → 1.10.0

package/index.d.ts

@@ -800,9 +800,21 @@ export interface IsomCheck {
 	/** Rects whose tiles are not what their ISOM resolves to (doodad tiles are excused). */
 	mismatched: number;
 }
-/** `checkIsom` with the verdict the palette and Check Map draw from it. */
+/**
+ * `checkIsom` with what a rebuild would do about it — the verdict the palette, Check Map
+ * and the Repair plugin draw from.
+ *
+ * The two numbers measure opposite directions and are not inverses: `mismatched` is the
+ * lattice failing to reproduce the tiles, while a rebuild votes a lattice out of the
+ * tiles. A rebuild converges in one pass and leaves `inherent` behind for good, because
+ * hand-placed tiles, blends and another editor's ground are not terrain any lattice
+ * describes. Reporting `mismatched` alone therefore recommended a repair that could not
+ * move the number, on every map with terrain like that.
+ */
 export interface IsomReport extends IsomCheck {
-	/** More than `STALE_ISOM_SHARE` of the rects disagree with their tiles. */
+	/** Of `mismatched`, the rects a rebuild would leave: terrain no lattice describes. */
+	inherent: number;
+	/** A rebuild would bring more than `STALE_ISOM_SHARE` of the rects back in step. */
 	stale: boolean;
 }
 export interface LocationStringChange {
@@ -1663,6 +1675,13 @@ export interface HistoryEdit {
 	 * removes the section again rather than leaving an all-zero one behind.
 	 */
 	createdIsom?: Uint16Array;
+	/**
+	 * Set when the edit rebuilt an existing lattice from the tiles, which is the one edit
+	 * to `isom` the ISOM health is re-measured after: a brush stroke keeps the two in step
+	 * by construction and is deliberately not measured (`useIsomStatus`), and measuring
+	 * costs a second rebuild.
+	 */
+	rebuiltIsom?: boolean;
 	/** Unit placements, moves and deletions (see editor/units.ts). */
 	units?: UnitChange[];
 	/**
@@ -1791,7 +1810,20 @@ export interface Preferences {
 		checkOnStart: boolean;
 		nightly: boolean;
 	};
+	/**
+	 * What to do when an installed plugin has a newer release than the one running
+	 * (`plugins/updates.ts`). `notify` looks a few seconds after the plugins start and
+	 * raises a notice with a button to the rows offering the update; `manual` asks nothing
+	 * until **Check for update** is pressed on a row; `auto` installs what it finds, for the
+	 * plugins the user added — a default moves with the editor's own releases and is only
+	 * ever named in the notice. Every mode leaves the confirmation on a row's button alone.
+	 */
+	plugins: {
+		updates: PluginUpdateMode;
+	};
 }
+/** See `Preferences.plugins.updates`. */
+export type PluginUpdateMode = "notify" | "manual" | "auto";
 /**
  * The version a host provides; a manifest that asks for a newer one is refused. It stays
  * at 1 while the API is only used by the plugins in the scm-js organisation and grows
@@ -1935,6 +1967,8 @@ export interface PluginApi {
 	/** Key combinations, tried before the editor's own and never while a text field has focus. */
 	readonly hotkeys: HotkeyApi;
 	readonly commands: CommandsApi;
+	/** Live objects one plugin holds out for others to use, found by name and watched for arriving. */
+	readonly services: ServicesApi;
 	readonly events: EventsApi;
 	/**
 	 * A small key-value store of the plugin's own, kept in the browser's local storage under
@@ -2787,6 +2821,46 @@ export interface CommandsApi {
 	/** Every command registered by every plugin. */
 	list(): CommandInfo[];
 }
+export interface ServiceInfo {
+	id: string;
+	pluginId: string;
+	version: number;
+}
+export interface ServiceOptions {
+	/** The provider's version of the contract, 1 by default; a consumer that needs a newer one checks `ServiceInfo.version`. */
+	version?: number;
+}
+/**
+ * A command is one thing to do; a service is a thing to *hold* — an account another
+ * plugin signs in through, a connection, a catalogue. A plugin provides one live object
+ * under a name and every other plugin reaches it by that name, whatever order they were
+ * activated in: `watch` answers at once with what is there and again whenever the
+ * provider arrives or goes.
+ *
+ * The object's shape is the provider's to publish (a `contract.d.ts` in its repository,
+ * taken as a dev dependency and imported with `import type`, which is erased before the
+ * loader sees it); the editor never reads it. A name without a dot is namespaced under
+ * the plugin (`"account"` → `"scmjs-dev.account"`); one with a dot is taken as it is.
+ *
+ * @example
+ * // The provider:
+ * api.services.provide("account", accountService);
+ * // A consumer:
+ * api.services.watch<AccountService>("scmjs-dev.account", (account) => {
+ *   if (account) useSessionFrom(account); else useOwnSignIn();
+ * });
+ */
+export interface ServicesApi {
+	/** Hold an object out under a name. Providing the same name again replaces it; the Disposable withdraws it. */
+	provide<T extends object>(id: string, service: T, options?: ServiceOptions): Disposable;
+	/** The object under a name, or null when no plugin provides it. */
+	get<T extends object>(id: string): T | null;
+	has(id: string): boolean;
+	/** Called at once with the current object (or null) and again on every change of provider. */
+	watch<T extends object>(id: string, listener: (service: T | null, info: ServiceInfo | null) => void): Disposable;
+	/** Every service provided by every plugin. */
+	list(): ServiceInfo[];
+}
 /** A picture the editor already has: the canvas it draws from, and its size in pixels. */
 export interface PluginImage {
 	image: HTMLCanvasElement;
@@ -3114,10 +3188,19 @@ export interface TerrainApi {
 	/** Whether the open map carries an ISOM section the isometric brush can work on. */
 	hasIsom(): boolean;
 	/**
-	 * How well the ISOM describes the tiles — `rects` measured, `mismatched` among them,
-	 * and `stale` when the share is past what the palette warns at — or null when the map
-	 * has no ISOM (`hasIsom`) or no map is open. Waits for the tileset graphics to load
-	 * and rejects when they are missing.
+	 * How well the ISOM describes the tiles, and what rebuilding it would do about that:
+	 * `rects` measured, `mismatched` among them, `inherent` of those a rebuild would leave
+	 * behind (terrain no lattice describes — hand-placed tiles, blends, another editor's
+	 * ground), and `stale` when a rebuild would bring more than the palette's threshold
+	 * back in step. Null when the map has no ISOM (`hasIsom`) or no map is open. Waits for
+	 * the tileset graphics to load and rejects when they are missing.
+	 *
+	 * Offer `tx.rebuildIsom` on `stale`, not on `mismatched`: the two measure opposite
+	 * directions, a rebuild converges in one pass, and `inherent` never goes away.
+	 *
+	 * @example
+	 * const r = await api.terrain.checkIsom();
+	 * if (r?.stale) await api.document.edit("Rebuild ISOM", (tx) => { tx.rebuildIsom(); });
 	 */
 	checkIsom(): Promise<IsomReport | null>;
 	tileInfo(id: number): TileInfo | null;
@@ -4040,9 +4123,11 @@ export interface WidgetsApi {
 export type TopMenu = "File" | "Edit" | "View" | "Layer" | "Scenario" | "Triggers" | "Tools" | "Plugins" | "Help";
 /**
  * A top-level menu, or a submenu by label: `"File/Import"`. A last segment that names no
- * submenu gets one of the plugin's own, at the end of the menu (`"Tools/AI"`).
+ * submenu gets one of the plugin's own, at the end of the menu (`"Tools/AI"`), and a
+ * first segment that names no top-level menu gets one made for the plugin, placed before
+ * Help (`"Account"`).
  */
-export type MenuPath = TopMenu | `${TopMenu}/${string}`;
+export type MenuPath = TopMenu | `${TopMenu}/${string}` | (string & {});
 export interface MenuItemSpec {
 	label: string;
 	/** Display only — bind the key with `hotkeys.add`. */
@@ -4146,6 +4231,8 @@ export type PluginEvent =
  | "file"
 /** A plugin registered or removed a command — how a plugin learns that one it calls by id has arrived. */
  | "commands"
+/** A plugin provided or withdrew a service — `services.watch` is the usual way to hear this for one name. */
+ | "services"
 /** The game data source changed: installed, switched to another data set, or a copy removed. `gameData.source()` says what it is now. */
  | "gameData";
 /** Why the document changed. */

package/package.json

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