@scm-js/plugin-api 1.24.0 → 1.26.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;
@@ -1670,6 +1679,13 @@ export interface SaveOptions {
 	/** Drop bytes after the last section header the file could parse. */
 	dropTrailing: boolean;
 }
+/** A step as the manifest remembers it. */
+export interface BuiltBy {
+	/** `plugin id/step id`. */
+	id: string;
+	/** The step's label when it ran, for a notice about a step that is no longer there. */
+	label: string;
+}
 export interface ChangeTilesetResult {
 	from: number;
 	to: number;
@@ -2104,6 +2120,12 @@ export interface ExportOptions {
 	 * an opened one), so the bytes are what Save would write unless you say otherwise.
 	 */
 	saveOptions?: Partial<Omit<SaveOptions, "format">>;
+	/**
+	 * False gives the map without its build steps (`document.buildSteps`): the scenario as the
+	 * editor holds it. By default the file is the one Save would write, steps run — except
+	 * from inside a step, where it is always the map without them.
+	 */
+	built?: boolean;
 }
 /** `document.save` / `saveAs`. */
 export interface SaveDocumentOptions {
@@ -2117,6 +2139,51 @@ export interface ChangeTilesetOptions {
 	/** Keep the tile numbers and change only ERA (what SCMDraft's switch does). */
 	keepTiles?: boolean;
 }
+/** Why the map is leaving the editor: File ▸ Save (and its copies), Tools ▸ Test Map, or `document.export`. */
+export type BuildPurpose = "save" | "test" | "export";
+export interface BuildStepInput {
+	/**
+	 * The map as Save would write it without the steps, or the step before this one's
+	 * output: an `.scx` / `.scm` archive, the archive extras inside.
+	 */
+	map: Uint8Array;
+	fileName: string;
+	purpose: BuildPurpose;
+	/** Aborted when the user chooses to save without waiting. */
+	signal: AbortSignal;
+}
+/**
+ * A compiler that stands between the map and the disk. The editor keeps showing the map
+ * the user edits; whenever the map leaves — Save, Test Map, `export` — every step that
+ * `applies` is run over the bytes, in the order the plugins were activated, and what the
+ * last one returns is what is written. The editor stores the map as it was *before* the
+ * steps inside the same file and gives that back on open, so a step's output (generated
+ * triggers, a payload in the string table) never shows up in the editor.
+ *
+ * A step that throws, or that the user stops waiting for, does not stop a save: the map is
+ * written without the steps and a notice says why. Test Map stops instead, since a map
+ * without its built part is not the one to test. A bare `.chk` is never built.
+ */
+export interface BuildStepSpec {
+	/** Unique within the plugin; the file remembers `plugin id/id`. */
+	id: string;
+	/** What the notice says is running: "eudplib". */
+	label: string;
+	/** Whether the open map has anything for this step. Cheap and synchronous; false leaves Save exactly as it was. */
+	applies(): boolean;
+	/**
+	 * 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.
+	 */
+	run(input: BuildStepInput): Promise<Uint8Array>;
+}
+export interface BuildStepsApi {
+	add(spec: BuildStepSpec): Disposable;
+	/** The steps behind the file the open map came from or was last saved to; null for a plain map. */
+	builtBy(): BuiltBy[] | null;
+}
 /**
  * The files stored in the map archive next to `staredit\scenario.chk`: custom sounds,
  * graphics, and anything a plugin wants to keep with the map. Names are archive paths
@@ -2309,6 +2376,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`
@@ -2326,6 +2405,7 @@ export interface DocumentApi {
 	changeTileset(options: ChangeTilesetOptions): Promise<ChangeTilesetResult | null>;
 	readonly extras: ExtrasApi;
 	readonly sections: SectionsApi;
+	readonly buildSteps: BuildStepsApi;
 }
 /** What a raw section edit reported: the parser's remarks about the file it produced. */
 export interface RawEditResult {

package/package.json

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