@scm-js/plugin-api 1.35.0 → 1.36.0

package/index.d.ts

@@ -2249,6 +2249,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 +2492,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 +3318,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;

package/package.json

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