@scm-js/plugin-api 1.25.0 → 1.27.0

package/index.d.ts

@@ -1679,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;
@@ -2113,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 {
@@ -2126,6 +2139,77 @@ 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>;
+}
+/**
+ * Work a plugin does on the *document* before the map's bytes are produced for Save, Test
+ * Map or `export` — the place to bring generated content up to date, such as writing a
+ * script's triggers into the trigger list with `document.update`. It runs before any
+ * build step is asked whether it applies, so a step can rely on what it did.
+ */
+export interface BeforeBuildSpec {
+	/** Unique within the plugin. */
+	id: string;
+	/** What a failure notice names: "TrigScript". */
+	label: string;
+	/** Whether there is anything to do for the open map. Cheap and synchronous; every save asks. Always, when omitted. */
+	applies?(): boolean;
+	/**
+	 * 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
+	 * running anything.
+	 */
+	run(ctx: {
+		purpose: BuildPurpose;
+		signal: AbortSignal;
+	}): void | Promise<void>;
+}
+export interface BuildStepsApi {
+	add(spec: BuildStepSpec): Disposable;
+	/** Run `spec.run` before the map's bytes are produced, every time the map leaves the editor. */
+	before(spec: BeforeBuildSpec): 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
@@ -2347,6 +2431,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.25.0",
+  "version": "1.27.0",
   "description": "Type declarations for the scmJS plugin API",
   "license": "MIT",
   "types": "index.d.ts",