@scm-js/plugin-api 1.30.0 → 1.32.0

package/index.d.ts

@@ -816,74 +816,6 @@ export type TerrainPick = {
 	kind: "tile";
 	id: number;
 };
-export interface Diamond {
-	x: number;
-	y: number;
-}
-export interface IsomCheck {
-	/** Rects that have tiles under them. */
-	rects: number;
-	/** Rects whose tiles are not what their ISOM resolves to (doodad tiles are excused). */
-	mismatched: number;
-}
-/**
- * `checkIsom` with what a rebuild would do about it — the verdict the palette, Check Map
- * and the Repair plugin draw from.
- *
- * The two numbers measure opposite directions and are not inverses: `mismatched` is the
- * lattice failing to reproduce the tiles, while a rebuild votes a lattice out of the
- * tiles. A rebuild converges in one pass and leaves `inherent` behind for good, because
- * hand-placed tiles, blends and another editor's ground are not terrain any lattice
- * describes. Reporting `mismatched` alone therefore recommended a repair that could not
- * move the number, on every map with terrain like that.
- */
-export interface IsomReport extends IsomCheck {
-	/** Of `mismatched`, the rects a rebuild would leave: terrain no lattice describes. */
-	inherent: number;
-	/** A rebuild would bring more than `STALE_ISOM_SHARE` of the rects back in step. */
-	stale: boolean;
-}
-export interface LocationStringChange {
-	index: number;
-	before: string | null;
-	after: string | null;
-}
-export interface LocationChange {
-	index: number;
-	before: LocationRecord;
-	after: LocationRecord;
-	/** A string slot the edit adds (a name no existing string matched); removed again on undo. */
-	string?: LocationStringChange;
-}
-export interface Bounds {
-	left: number;
-	top: number;
-	right: number;
-	bottom: number;
-}
-export interface LocationPatch {
-	name?: string;
-	left?: number;
-	top?: number;
-	right?: number;
-	bottom?: number;
-	elevationFlags?: number;
-}
-export type FogMode = "fog" | "clear";
-export interface SpriteChange {
-	index: number;
-	before: SpriteRecord | null;
-	after: SpriteRecord | null;
-}
-export type SpriteKind = "pure" | "unit";
-/** Unit type catalogue: StarEdit names by units.dat id, and the palette's grouping of them. */
-export type RaceKey = "terran" | "zerg" | "protoss" | "neutral";
-export interface UnitGroup {
-	race: RaceKey;
-	label: string;
-	/** units.dat ids, in palette order. */
-	units: number[];
-}
 export interface UnitsDat {
 	/** flingy.dat index. */
 	flingy: Uint8Array;
@@ -975,6 +907,164 @@ export interface TechdataDat {
 	/** The technology's name: a 1-based `stat_txt.tbl` index, 0 for none. */
 	label: Uint16Array;
 }
+/**
+ * Unit edits as invertible change lists, in the same spirit as terrain's `TileChange`.
+ * `before`/`after` are whole records: null `before` is an insertion at `index`, null
+ * `after` a removal, both set a replacement. Removals are listed highest index first so
+ * that applying them in order keeps the remaining indices valid; undo walks the list
+ * backwards and so re-inserts lowest first.
+ */
+export interface UnitChange {
+	index: number;
+	before: UnitRecord | null;
+	after: UnitRecord | null;
+}
+export interface SpriteChange {
+	index: number;
+	before: SpriteRecord | null;
+	after: SpriteRecord | null;
+}
+export type SpriteKind = "pure" | "unit";
+export interface DoodadChange {
+	index: number;
+	before: DoodadRecord | null;
+	after: DoodadRecord | null;
+}
+export interface DoodadPlacementOptions {
+	/** Skip StarEdit's ground check: any doodad goes on any terrain, even over another doodad. */
+	placeAnywhere: boolean;
+	/** Keep the left column on an even tile, as StarEdit always does. */
+	snapToGrid: boolean;
+	/** Place as plain terrain: the tiles (both sections) and any overlay sprite, no DD2 record — a placement and a conversion in one. */
+	asTerrain: boolean;
+}
+export interface DoodadVerdict {
+	ok: boolean;
+	/** The footprint leaves the map (never allowed). */
+	outOfBounds: boolean;
+	/** Cell indices (row-major) whose ground fails the check, for the ghost to mark red. */
+	bad: number[];
+}
+export interface LocationStringChange {
+	index: number;
+	before: string | null;
+	after: string | null;
+}
+export interface LocationChange {
+	index: number;
+	before: LocationRecord;
+	after: LocationRecord;
+	/** A string slot the edit adds (a name no existing string matched); removed again on undo. */
+	string?: LocationStringChange;
+}
+export interface Bounds {
+	left: number;
+	top: number;
+	right: number;
+	bottom: number;
+}
+export interface LocationPatch {
+	name?: string;
+	left?: number;
+	top?: number;
+	right?: number;
+	bottom?: number;
+	elevationFlags?: number;
+}
+/** The change lists of one edit; `HistoryEntry` adds the label. */
+export interface HistoryEdit {
+	changes: TileChange[];
+	/** The isometric brush's changes to `scenario.isom`, undone together with the tiles. */
+	isom?: TileChange[];
+	/**
+	 * Set when the edit gave a map an ISOM section it did not have (Rebuild ISOM). Undo
+	 * removes the section again rather than leaving an all-zero one behind.
+	 */
+	createdIsom?: Uint16Array;
+	/**
+	 * Set when the edit rebuilt an existing lattice from the tiles, which is the one edit
+	 * to `isom` the ISOM health is re-measured after: a brush stroke keeps the two in step
+	 * by construction and is deliberately not measured (`useIsomStatus`), and measuring
+	 * costs a second rebuild.
+	 */
+	rebuiltIsom?: boolean;
+	/** Unit placements, moves and deletions (see editor/units.ts). */
+	units?: UnitChange[];
+	/**
+	 * Doodad tiles stamped into or lifted off MTXM alone — TILE keeps the ground beneath
+	 * (see editor/doodads.ts). Applied after `changes`, so a terrain stroke that removes
+	 * the doodads it painted over restores their remaining cells on top of its own edit.
+	 */
+	doodadTiles?: TileChange[];
+	/** DD2 record insertions, removals and replacements. */
+	doodads?: DoodadChange[];
+	/** THG2 record changes: the Sprites layer's edits, and a doodad's overlay sprite coming and going with it. */
+	sprites?: SpriteChange[];
+	/** MRGN slot replacements — create, move, resize, rename, delete (see editor/locations.ts); a rename may carry a string. */
+	locations?: LocationChange[];
+	/** Fog of war edits to `scenario.mask` (see editor/fog.ts); `at` indexes the MASK byte. */
+	fog?: TileChange[];
+	/**
+	 * Set when the edit gave a map a MASK section it did not have (the first fog stroke
+	 * on such a map). Undo removes the section again.
+	 */
+	createdMask?: Uint8Array;
+}
+/**
+ * Why the map changed: an edit recorded in the history, an undo or redo of one, a dialog
+ * writing its tables (settings, triggers, strings — outside the history), a change to the
+ * whole document (resize, tileset change, raw section edit), or other people's edits on a
+ * shared map.
+ */
+export type CommitReason = "edit" | "undo" | "redo" | "tables" | "whole" | "remote";
+/** Which parts of the map one commit touched. */
+export interface CommitParts {
+	terrain: boolean;
+	isom: boolean;
+	units: boolean;
+	doodads: boolean;
+	sprites: boolean;
+	locations: boolean;
+	fog: boolean;
+	settings: boolean;
+	triggers: boolean;
+}
+export interface Diamond {
+	x: number;
+	y: number;
+}
+export interface IsomCheck {
+	/** Rects that have tiles under them. */
+	rects: number;
+	/** Rects whose tiles are not what their ISOM resolves to (doodad tiles are excused). */
+	mismatched: number;
+}
+/**
+ * `checkIsom` with what a rebuild would do about it — the verdict the palette, Check Map
+ * and the Repair plugin draw from.
+ *
+ * The two numbers measure opposite directions and are not inverses: `mismatched` is the
+ * lattice failing to reproduce the tiles, while a rebuild votes a lattice out of the
+ * tiles. A rebuild converges in one pass and leaves `inherent` behind for good, because
+ * hand-placed tiles, blends and another editor's ground are not terrain any lattice
+ * describes. Reporting `mismatched` alone therefore recommended a repair that could not
+ * move the number, on every map with terrain like that.
+ */
+export interface IsomReport extends IsomCheck {
+	/** Of `mismatched`, the rects a rebuild would leave: terrain no lattice describes. */
+	inherent: number;
+	/** A rebuild would bring more than `STALE_ISOM_SHARE` of the rects back in step. */
+	stale: boolean;
+}
+export type FogMode = "fog" | "clear";
+/** Unit type catalogue: StarEdit names by units.dat id, and the palette's grouping of them. */
+export type RaceKey = "terran" | "zerg" | "protoss" | "neutral";
+export interface UnitGroup {
+	race: RaceKey;
+	label: string;
+	/** units.dat ids, in palette order. */
+	units: number[];
+}
 export interface SpriteGroup {
 	label: string;
 	ids: number[];
@@ -1349,18 +1439,6 @@ export interface StringUsage {
 	ref: number;
 	label: string;
 }
-/**
- * Unit edits as invertible change lists, in the same spirit as terrain's `TileChange`.
- * `before`/`after` are whole records: null `before` is an insertion at `index`, null
- * `after` a removal, both set a replacement. Removals are listed highest index first so
- * that applying them in order keeps the remaining indices valid; undo walks the list
- * backwards and so re-inserts lowest first.
- */
-export interface UnitChange {
-	index: number;
-	before: UnitRecord | null;
-	after: UnitRecord | null;
-}
 export interface PlacementOptions {
 	/** Refuse to put a unit on top of another (ground units and buildings only). */
 	checkCollision: boolean;
@@ -1694,27 +1772,102 @@ export interface ChangeTilesetResult {
 	spritesDropped: number;
 	refilled: boolean;
 }
-export type SymmetryMode = "none" | "h" | "v" | "hv" | "rot180" | "rot90" | "diag" | "adiag";
-export interface DoodadChange {
+export interface WireListChange<T> {
 	index: number;
-	before: DoodadRecord | null;
-	after: DoodadRecord | null;
+	before: T | null;
+	after: T | null;
 }
-export interface DoodadPlacementOptions {
-	/** Skip StarEdit's ground check: any doodad goes on any terrain, even over another doodad. */
-	placeAnywhere: boolean;
-	/** Keep the left column on an even tile, as StarEdit always does. */
-	snapToGrid: boolean;
-	/** Place as plain terrain: the tiles (both sections) and any overlay sprite, no DD2 record — a placement and a conversion in one. */
-	asTerrain: boolean;
+export interface WireLocationChange {
+	index: number;
+	after: LocationRecord;
+	/** The name as text (`after.nameIndex` is resolved again where it lands); null for none. */
+	name: string | null;
+	/** The slot was empty before: a new location, which moves to a free slot if someone else took this one. */
+	created: boolean;
 }
-export interface DoodadVerdict {
-	ok: boolean;
-	/** The footprint leaves the map (never allowed). */
-	outOfBounds: boolean;
-	/** Cell indices (row-major) whose ground fails the check, for the ghost to mark red. */
-	bad: number[];
+/**
+ * One undo step's worth of terrain and objects. The grids are flat number lists: terrain
+ * `[at, mtxm, tile, …]`, the others `[at, value, …]`. `reverse` marks the undo of an edit:
+ * its parts go in the reverse of the usual order, as undo walks them.
+ */
+export interface SyncEditOp {
+	kind: "edit";
+	label: string;
+	/** The map size the cells index; a grid part is skipped on a map of another size. */
+	width: number;
+	height: number;
+	reverse?: boolean;
+	terrain?: number[];
+	isom?: number[];
+	doodadTiles?: number[];
+	fog?: number[];
+	/** The whole ISOM lattice (base64 of the u16 cells) the edit gave the map, or null for taking it away. */
+	isomWhole?: string | null;
+	maskWhole?: string | null;
+	units?: WireListChange<UnitRecord>[];
+	doodads?: WireListChange<DoodadRecord>[];
+	sprites?: WireListChange<SpriteRecord>[];
+	locations?: WireLocationChange[];
+}
+declare const SYNC_FIELDS: readonly [
+	"type",
+	"fileVersion",
+	"nameIndex",
+	"descriptionIndex",
+	"playerTypes",
+	"editorPlayerTypes",
+	"playerRaces",
+	"playerColors",
+	"playerRgb",
+	"forces",
+	"unitSettings",
+	"unitAvailability",
+	"upgradeSettings",
+	"upgradeRestrictions",
+	"techSettings",
+	"techRestrictions",
+	"wavs",
+	"cuwp",
+	"cuwpUsed",
+	"triggers",
+	"briefing",
+	"switchNames"
+];
+export type SyncField = (typeof SYNC_FIELDS)[number];
+export interface SyncFieldsOp {
+	kind: "fields";
+	/** Each changed field's new value, packed (`pack`). */
+	set: Partial<Record<SyncField, unknown>>;
+	/** String slots that changed: `[index, before, after]`. */
+	strings?: [
+		number,
+		string | null,
+		string | null
+	][];
+	/** The table's length afterwards (trailing blank slots are dropped). */
+	stringsLength?: number;
+	/** The table's width and text encoding, when they changed. */
+	stringsFormat?: {
+		extended: boolean;
+		encoding: TextEncoding;
+	};
 }
+export interface SyncExtrasOp {
+	kind: "extras";
+	/** `[member name, base64 bytes]`, or null bytes for a member taken out. */
+	set: [
+		string,
+		string | null
+	][];
+}
+export interface SyncResetOp {
+	kind: "reset";
+	label: string;
+	/** The whole scenario, base64. */
+	chk: string;
+}
+export type SyncOp = SyncEditOp | SyncFieldsOp | SyncExtrasOp | SyncResetOp;
+export type SymmetryMode = "none" | "h" | "v" | "hv" | "rot180" | "rot90" | "diag" | "adiag";
 export type StartLayout = "ring" | "corners";
 export interface StartPlacementResult {
 	changes: UnitChange[];
@@ -1741,45 +1894,6 @@ export interface BlendOptions {
 	/** Optional filter over tile ids (the palette's group-kind dropdown). */
 	include?: (id: number) => boolean;
 }
-/** The change lists of one edit; `HistoryEntry` adds the label. */
-export interface HistoryEdit {
-	changes: TileChange[];
-	/** The isometric brush's changes to `scenario.isom`, undone together with the tiles. */
-	isom?: TileChange[];
-	/**
-	 * Set when the edit gave a map an ISOM section it did not have (Rebuild ISOM). Undo
-	 * removes the section again rather than leaving an all-zero one behind.
-	 */
-	createdIsom?: Uint16Array;
-	/**
-	 * Set when the edit rebuilt an existing lattice from the tiles, which is the one edit
-	 * to `isom` the ISOM health is re-measured after: a brush stroke keeps the two in step
-	 * by construction and is deliberately not measured (`useIsomStatus`), and measuring
-	 * costs a second rebuild.
-	 */
-	rebuiltIsom?: boolean;
-	/** Unit placements, moves and deletions (see editor/units.ts). */
-	units?: UnitChange[];
-	/**
-	 * Doodad tiles stamped into or lifted off MTXM alone — TILE keeps the ground beneath
-	 * (see editor/doodads.ts). Applied after `changes`, so a terrain stroke that removes
-	 * the doodads it painted over restores their remaining cells on top of its own edit.
-	 */
-	doodadTiles?: TileChange[];
-	/** DD2 record insertions, removals and replacements. */
-	doodads?: DoodadChange[];
-	/** THG2 record changes: the Sprites layer's edits, and a doodad's overlay sprite coming and going with it. */
-	sprites?: SpriteChange[];
-	/** MRGN slot replacements — create, move, resize, rename, delete (see editor/locations.ts); a rename may carry a string. */
-	locations?: LocationChange[];
-	/** Fog of war edits to `scenario.mask` (see editor/fog.ts); `at` indexes the MASK byte. */
-	fog?: TileChange[];
-	/**
-	 * Set when the edit gave a map a MASK section it did not have (the first fog stroke
-	 * on such a map). Undo removes the section again.
-	 */
-	createdMask?: Uint8Array;
-}
 export type ClipPart = "terrain" | "doodads" | "units" | "sprites" | "locations" | "fog";
 export type ClipParts = Record<ClipPart, boolean>;
 /** Whether a paste adds to what is in the target area or clears its objects first. */
@@ -2121,6 +2235,13 @@ export interface PluginApi {
 	/** The plugin's words in the editor's language: its own catalogues, and a `t` over them. */
 	readonly i18n: I18nApi;
 	readonly events: EventsApi;
+	/**
+	 * Editing the map in front together with other editors: every change to it is handed out
+	 * as an op for the plugin to carry to them, and theirs come back in, in the order a
+	 * server puts them. The scmjs.dev plugin's shared maps are built on it; the transport,
+	 * the server and who may join are the plugin's.
+	 */
+	readonly sync: SyncApi;
 	/**
 	 * A small key-value store of the plugin's own, kept in the browser's local storage under
 	 * the plugin's id and listed with everything else in Preferences ▸ Browser storage.
@@ -3308,8 +3429,9 @@ export interface GraphicsApi {
 	 * overlays with the viewport's own graphics, then location boxes — a thumbnail for a
 	 * list of clips, or the ghost under the pointer while a plugin stamps one. It is drawn
 	 * with the graphics of the clip's *own* tileset (`clip.era`), which are in memory for
-	 * the open map once loaded and otherwise not, so a clip from another tileset answers
-	 * null; so does a missing tileset or a page with no canvas. Synchronous and uncached:
+	 * the open map once loaded; a clip from another tileset answers null until
+	 * `tileset.load(id)` has fetched that one. So does a missing tileset or a page with no
+	 * canvas. Synchronous and uncached:
 	 * keep the result while the clip and the tileset stay the same.
 	 */
 	renderClip(clip: Clip, options?: RenderClipOptions): PluginImage | null;
@@ -3670,8 +3792,14 @@ export interface TilesetApi {
 	id(): TilesetId | null;
 	name(): string;
 	isLoaded(): boolean;
-	/** Fetch and decode the graphics; resolves false when they were never extracted. */
-	load(): Promise<boolean>;
+	/**
+	 * Fetch and decode the graphics — the open map's tileset's, or `tileset`'s — and keep
+	 * them in memory; resolves false when they were never extracted. Loading another
+	 * tileset changes nothing about the map: it is for `graphics.renderClip` drawing a clip
+	 * that came from a map on that tileset (a stamp, a recording), which answers null until
+	 * its tileset's graphics are loaded.
+	 */
+	load(tileset?: TilesetId): Promise<boolean>;
 	raw(): LoadedTileset | null;
 }
 export interface SelectionApi {
@@ -4317,6 +4445,11 @@ export interface PickFilesOptions {
 	multiple?: boolean;
 }
 export interface UiApi {
+	/**
+	 * The dialogs open now, bottom to top, by id: the built-in ones by their `DialogId`, a
+	 * plugin's as `"pluginDialog"`. What a shared map shows others ("in Player Settings").
+	 */
+	openDialogs(): string[];
 	/** Set the status bar line. */
 	status(text: string): void;
 	/** The status bar line as it stands. */
@@ -4840,6 +4973,8 @@ export interface HotkeyApi {
 export type PluginEvent = 
 /** A map was opened, closed or replaced. */
 "document"
+/** A change was committed to the map in front; the listener gets a `CommitEvent` saying what and where. */
+ | "commit"
 /** The editor's language changed (Preferences ▸ Display): re-label what is showing through `api.i18n.t`. */
  | "language"
 /** Any committed edit (every `document.edit`, stroke, undo and redo bumps it, terrain or not), and a fog edit. */
@@ -4864,8 +4999,113 @@ export type PluginEvent =
  | "commands"
 /** A plugin provided or withdrew a service — `services.watch` is the usual way to hear this for one name. */
  | "services"
+/** A dialog opened or closed — `ui.openDialogs()` says which are open. */
+ | "dialogs"
 /** The game data source changed: installed, switched to another data set, or a copy removed. `gameData.source()` says what it is now. */
  | "gameData";
+/**
+ * What the `"commit"` event hands its listeners: one change to the map in front, after it
+ * is in the scenario. Every stroke, `document.edit`, undo and redo is one commit; so is a
+ * dialog's OK or a `document.update` (reason `"tables"`), a resize, tileset change or raw
+ * section edit (`"whole"`), and a batch of other people's edits on a shared map
+ * (`"remote"`). A dialog that writes both settings and triggers may send two. Opening,
+ * closing and switching maps are not commits — the `"document"` event says those.
+ *
+ * @example
+ * api.events.on("commit", (e) => {
+ *   if (e.parts.terrain && e.area) redrawTiles(e.area);
+ *   else if (e.reason === "whole" || e.reason === "remote") redrawAll();
+ * });
+ */
+export interface CommitEvent {
+	/** `document.id()` of the map it happened to (always the one in front). */
+	id: number | null;
+	reason: CommitReason;
+	/**
+	 * The history label — the words Edit ▸ Undo shows, in the editor's language; for an undo
+	 * or redo, the label of the entry taken back or put back. The update's label for a
+	 * `document.update`, the operation's name for `"whole"`, and "" for a built-in dialog's
+	 * OK and for other people's edits.
+	 */
+	label: string;
+	/**
+	 * The tiles the change fell on, far edges exclusive: every changed tile, and the tile
+	 * under each moved, placed or removed object's position (its picture reaches further —
+	 * widen the rect by the largest picture you draw). Null when the change has no place on
+	 * the map (`"tables"`) or may have touched all of it (`"whole"`, `"remote"`).
+	 */
+	area: Rect | null;
+	/** Which parts changed. All of them for `"whole"` and `"remote"`, which do not say. */
+	parts: CommitParts;
+}
+/** Why other people's changes are waiting: a stroke under way on the map, a dialog that edits the map open, another map in front. */
+export type SyncHold = "stroke" | "dialog" | "behind";
+export interface SyncReport {
+	/** Other people's ops applied. */
+	ops: number;
+	/** Parts of them that could not be applied — the unit they moved was deleted, the map was resized… */
+	dropped: number;
+	/** Parts of this editor's unconfirmed changes that no longer applied on top of theirs. */
+	lost: number;
+}
+export interface SyncStartOptions {
+	/**
+	 * Every change made to the shared map, as a plain object JSON can carry, in the order
+	 * made: commits, undo and redo, the dialogs' writes, archive files, and a resize or a
+	 * tileset change (the whole scenario). Each must reach the server, and every other
+	 * editor, in this order.
+	 */
+	send(op: SyncOp): void;
+	/** The session ended: the shared map was closed or replaced by another, or `stop` was called. */
+	onEnd?(reason: "closed" | "stopped"): void;
+	/** Other people's changes were applied to the map. */
+	onApplied?(report: SyncReport): void;
+}
+/**
+ * One shared map. The server confirms each op this editor sent (`confirm`, in order) and
+ * relays everyone else's (`receive`, in the order it gave them); the session applies
+ * them to the map when nothing is in the way (`holding`) and rebases this editor's
+ * unconfirmed changes on top, so every editor that has seen the same ops has the same map.
+ *
+ * @example
+ * const session = api.sync.start({ send: (op) => socket.send(JSON.stringify({ type: "op", op })) });
+ * socket.onmessage = (m) => {
+ *   const msg = JSON.parse(m.data);
+ *   if (msg.type === "ack") session?.confirm();
+ *   if (msg.type === "op") session?.receive(msg.op);
+ * };
+ */
+export interface SyncSession {
+	/** The shared map's `document.id()`. */
+	readonly documentId: number;
+	/** Another editor's op, in the server's order. False, and nothing done, for a value that is not an op. */
+	receive(op: unknown): boolean;
+	/** The server confirmed the oldest op this editor sent. */
+	confirm(): void;
+	/** Ops sent and not yet confirmed. */
+	pending(): number;
+	/** Ops and confirmations received and not yet applied. */
+	waiting(): number;
+	/**
+	 * The shared map as a file (`.scx` / `.scm`, not built), copied at this moment — for a
+	 * server to hand people joining, labelled with the last op this editor applied. Null
+	 * while anything is pending or waiting (the copy would not match any point in the
+	 * server's order) or while another map is in front. The copy is taken before the first
+	 * `await`, so a change made while the file is written is not in it.
+	 */
+	snapshot(): Promise<Uint8Array | null>;
+	holding(): SyncHold | null;
+	stop(): void;
+}
+export interface SyncApi {
+	/**
+	 * Share the map in front. Null when no map is open or another session is running (one
+	 * at a time). A session a plugin started stops when the plugin is turned off.
+	 */
+	start(options: SyncStartOptions): SyncSession | null;
+	/** The running session, whichever plugin started it. */
+	current(): SyncSession | null;
+}
 /** Why the document changed. */
 export type DocumentChangeReason = 
 /** File ▸ Open, drag-and-drop, `document.open`: a file the user chose. */
@@ -4924,8 +5164,10 @@ export interface EventsApi {
 	 *   if (e.reason === "open") check(e.fileName);
 	 * });
 	 * api.events.on("terrain", () => redraw());
+	 * api.events.on("commit", (e) => console.log(e.reason, e.label, e.area));
 	 */
 	on(event: "document", listener: (event: DocumentEvent) => void): Disposable;
+	on(event: "commit", listener: (event: CommitEvent) => void): Disposable;
 	on(event: PluginEvent, listener: () => void): Disposable;
 }
 export interface StorageApi {

package/package.json

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