@scm-js/plugin-api 1.23.0 → 1.25.0

package/index.d.ts

@@ -1141,6 +1141,15 @@ export interface MapImageOptions {
 	 */
 	rect?: Rect | null;
 }
+export type TestRoute = "desktop" | "folder" | "download";
+export interface TestMapOutcome {
+	route: TestRoute;
+	/** The file's name, or its full path when the desktop wrote it. */
+	path: string;
+	launched: boolean;
+	/** Why the game did not start, when it was asked to. */
+	message?: string;
+}
 /** What the registry knows about a section name, sized for one map. */
 export interface SectionKnowledge {
 	name: string;
@@ -1957,6 +1966,20 @@ export interface PluginManifest {
 	icon?: string;
 	/** The `PLUGIN_API_VERSION` the plugin was written against. */
 	api?: number;
+	/**
+	 * Plugins this one needs running, as the specs Manage Plugins takes
+	 * (`"github:owner/repo"`, `"github:owner/repo@v1.2.0"`, a URL to a `plugin.json`,
+	 * `"builtin:name"`). Adding this plugin installs them first, enabling it enables them,
+	 * and the editor starts them before it; a required plugin cannot be turned off or
+	 * removed while something enabled needs it.
+	 *
+	 * Which *version* of the required plugin is enough is not said here. The two plugins
+	 * meet through `api.services`: the required one provides a service with a `version`
+	 * (`ServiceOptions`), and this one checks `ServiceInfo.version` in its `watch` and says
+	 * so in its own words when it is too old. A version range in the manifest would have
+	 * the editor arbitrate a contract it never reads.
+	 */
+	requires?: string[];
 }
 /** What `activate` may hand back: nothing, a cleanup function, or a Disposable. */
 export type Deactivate = void | (() => void) | Disposable;
@@ -2295,6 +2318,18 @@ export interface DocumentApi {
 	 * a map, null.
 	 */
 	renderImage(options?: Partial<MapImageOptions>): Promise<Blob | null>;
+	/**
+	 * Tools ▸ Test Map for bytes of the plugin's own — a built map that is not the open
+	 * one. On the desktop the file is written into the game's `Maps\scmJS` folder and, with
+	 * `launch` (the preference when omitted), the game is started; in a browser it is
+	 * written into the test folder the user picked once. It never downloads: a browser
+	 * with no folder answers null, so a plugin that has already saved the file says "open
+	 * it with Test Map" instead of handing out a second copy. `fileName` gets an archive's
+	 * extension if it lacks one.
+	 */
+	test(bytes: Uint8Array, fileName: string, options?: {
+		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`

package/package.json

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