@scm-js/plugin-api 1.35.0 → 1.37.0

package/index.d.ts

@@ -1209,7 +1209,7 @@ export interface StackedLine {
 	pieces: number;
 }
 /** Every built-in dialog, by the id `openDialogAtom` takes; `DialogHost` maps each to its component. */
-export type DialogId = "newMap" | "openMap" | "saveAs" | "exportImage" | "mapProperties" | "resizeMap" | "mapRevision" | "playerSettings" | "forceSettings" | "playerColors" | "unitSettings" | "upgradeSettings" | "techSettings" | "stringEditor" | "soundEditor" | "switches" | "locationList" | "unitProperties" | "locationProperties" | "spriteProperties" | "triggerEditor" | "missionBriefing" | "cuwpEditor" | "replaceTerrain" | "autoStarts" | "testMap" | "symmetry" | "gridSettings" | "preferences" | "shortcuts" | "validateMap" | "statistics" | "importTriggers" | "exportTriggers" | "importStrings" | "exportStrings" | "find" | "about" | "confirmClose" | "plugins" | "confirmPlugin" | "pluginDialog" | "gameData" | "update";
+export type DialogId = "newMap" | "openMap" | "saveAs" | "exportImage" | "mapProperties" | "resizeMap" | "mapRevision" | "playerSettings" | "forceSettings" | "playerColors" | "unitSettings" | "upgradeSettings" | "techSettings" | "stringEditor" | "soundEditor" | "switches" | "locationList" | "unitProperties" | "locationProperties" | "spriteProperties" | "triggerEditor" | "missionBriefing" | "cuwpEditor" | "replaceTerrain" | "autoStarts" | "testMap" | "symmetry" | "gridSettings" | "preferences" | "shortcuts" | "validateMap" | "statistics" | "importTriggers" | "exportTriggers" | "importStrings" | "exportStrings" | "find" | "about" | "confirmClose" | "recovery" | "previousVersions" | "plugins" | "confirmPlugin" | "pluginDialog" | "gameData" | "update";
 export interface MapImageOptions {
 	/** Output pixels per map tile. 32 matches the game's art 1:1; 1 is a minimap. */
 	pixelsPerTile: number;
@@ -1992,11 +1992,25 @@ export interface Preferences {
 	 * What the Save dialog starts from: the options the file was opened with
 	 * (`"asOpened"`, the default), or one of its presets. `compression` is for a map with
 	 * no origin — new, or opened from a bare .chk — where there is nothing to follow;
-	 * `"asOpened"` there means StarEdit's PKWARE.
+	 * `"asOpened"` there means StarEdit's PKWARE. `backup` keeps the file a save writes
+	 * over: `<name>.bak` beside it in the desktop app, the browser's storage otherwise
+	 * (`services/previousVersions.ts`).
 	 */
 	save: {
 		start: "asOpened" | "everything" | "smallest";
 		compression: "asOpened" | ArchiveCompression;
+		backup: boolean;
+	};
+	/**
+	 * Recovery copies (`hooks/useRecovery.ts`): while a map has unsaved changes, a copy of
+	 * it is kept in the browser's storage every `minutes` and when the editor goes to the
+	 * background, and dropped when the map is saved or closed. What a session that ended
+	 * without saving left behind is offered back at the next start. Off stops the copies
+	 * and drops this session's; copies left by earlier sessions are still offered.
+	 */
+	recovery: {
+		enabled: boolean;
+		minutes: number;
 	};
 	/** How many edits Undo keeps per map (SCMDraft keeps 200). */
 	undoLevels: number;
@@ -2249,6 +2263,25 @@ export interface PluginApi {
 	readonly storage: StorageApi;
 	/** `console.log` with the plugin's name in front. */
 	log(...args: unknown[]): void;
+	/**
+	 * A child of this API with a lifetime of its own. Everything registered through
+	 * `scope.api` — menu items, hotkeys, event listeners, panels, dialogs, overlays, map
+	 * tools, commands, services, trigger claims — goes when `scope.dispose()` is called, and
+	 * with the plugin if it is turned off first. After the dispose, the child's document
+	 * writes are refused as a turned-off plugin's are, so a timer or a fetch that outlives
+	 * the scope cannot change the map. Scopes nest.
+	 *
+	 * It is for a plugin that runs other code for a while and then takes it all back: the
+	 * API Playground runs each snippet in one. The child speaks as the same plugin — same
+	 * id, storage and log name.
+	 */
+	scope(): PluginScope;
+}
+/** A child API that can be taken back as a whole (`PluginApi.scope`). */
+export interface PluginScope extends Disposable {
+	readonly api: PluginApi;
+	/** True once `dispose` has run, or once the plugin that made the scope was turned off. */
+	readonly disposed: boolean;
 }
 export interface DocumentInfo {
 	name: string;
@@ -2473,8 +2506,9 @@ export interface DocumentApi {
 	 *
 	 * @example
 	 * // One undo entry called "Fill", however many operations it takes.
+	 * const ground = api.terrain.types()[1].id; // the tileset's second flat terrain
 	 * const result = api.document.edit("Fill", (tx) => {
-	 *   tx.stampTerrain({ x0: 0, y0: 0, x1: 8, y1: 8 }, terrainId);
+	 *   tx.stampTerrain({ x0: 0, y0: 0, x1: 8, y1: 8 }, ground);
 	 *   tx.placeUnit(api.consts.unit.startLocation, 0, 4 * api.consts.tile, 4 * api.consts.tile);
 	 * });
 	 * api.ui.status(`${result.tiles} tiles, ${result.units} units`);
@@ -3298,7 +3332,8 @@ export interface ViewApi {
 	 * clean up.
 	 *
 	 * @example
-	 * const r = api.document.edit("Fill", (tx) => tx.fillFlat(rect, terrain));
+	 * const rect = { x0: 4, y0: 4, x1: 12, y1: 12 };
+	 * const r = api.document.edit("Fill", (tx) => tx.fillFlat(rect, api.terrain.types()[1].id));
 	 * if (r.changed) api.view.flash({ rect });
 	 */
 	flash(target: FlashTarget): void;
@@ -3558,6 +3593,13 @@ export interface GameDataApi {
 	select(id: string): Promise<GameDataSource>;
 	/** Remove a data set's copy (never the game's bundled files). True when there was one. */
 	remove(id: string): Promise<boolean>;
+	/**
+	 * One file of the data set in use, by its path in the extracted copy: the archive path in
+	 * lower case with forward slashes (`arr/units.dat`, `tileset/jungle.cv5`,
+	 * `unit/zerg/drone.grp`). `tileset/manifest.json` and `unit/manifest.json` list what was
+	 * extracted. Null when the copy has no such file, or there is no game data.
+	 */
+	read(path: string): Promise<Uint8Array | null>;
 }
 /**
  * The constants a plugin needs to *write* a record rather than read one: the bit masks in

package/package.json

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