@scm-js/plugin-api 1.0.0

package/index.d.ts

@@ -0,0 +1,3411 @@
+/**
+ * Type declarations for the scmJS plugin API — version 1.
+ *
+ * Generated by `npm run build:plugin-types` in github.com/scm-js/scm-js and published
+ * to github.com/scm-js/plugin-api. Do not edit: the contract is `src/plugins/api.ts`
+ * there, and `docs/plugins.md` is the guide.
+ */
+/**
+ * CHK is a flat stream of chunks: 4-byte name, int32 length, then that many bytes.
+ *
+ * StarCraft applies chunks *sequentially into fixed-size buffers*, so a section that
+ * appears twice is not "last one wins" — the later copy overwrites only as many bytes
+ * as it carries. Protected maps lean on this constantly, so the reader keeps every
+ * occurrence in file order and `layer()` reproduces the overwrite semantics.
+ */
+export interface ChkSection {
+	/** 4-character chunk name, latin1. May contain junk in protected maps. */
+	name: string;
+	/** Byte offset of the chunk's *name* within the CHK. */
+	offset: number;
+	/** Length field as written, which may disagree with `data.length` when truncated. */
+	declaredSize: number;
+	data: Uint8Array;
+	/** Set when the declared size ran past the end of the file. */
+	truncated?: boolean;
+}
+export interface ChkFile {
+	sections: ChkSection[];
+	/** Bytes after the last parseable chunk header, if any. */
+	trailing?: Uint8Array;
+}
+/**
+ * How the game combines repeated occurrences of a section. Which mode applies is a
+ * per-section fact (see sections/registry.ts), not something the container can infer.
+ */
+export type CombineMode = 
+/** Zeroed fixed buffer, each occurrence copied over the front in file order. */
+"overlay"
+/** Every occurrence's records are kept, in file order. */
+ | "append"
+/** Only the last occurrence is used. */
+ | "last"
+/** Only the first occurrence is used. */
+ | "first";
+/**
+ * STR/STRx string table.
+ *
+ * Index 0 means "no string" and is never stored. Indices are referenced from TRIG,
+ * MRGN, SPRP and friends — several of which we round-trip as raw bytes — so the table
+ * must keep its index space stable across a save. Entries are therefore addressed by
+ * position, never renumbered.
+ */
+export interface StringTable {
+	/** `strings[i]` is string index `i`; slot 0 is always null. */
+	strings: (string | null)[];
+	/** True when the source section was STRx (Remastered, 32-bit count and offsets). */
+	extended: boolean;
+}
+export interface UnitRecord {
+	serial: number;
+	x: number;
+	y: number;
+	unitId: number;
+	relationType: number;
+	/** Bit set of which "special properties" fields below are meaningful. */
+	validProperties: number;
+	validStates: number;
+	owner: number;
+	hitPointsPercent: number;
+	shieldPercent: number;
+	energyPercent: number;
+	resourceAmount: number;
+	hangarUnits: number;
+	stateFlags: number;
+	unused: number;
+	relatedSerial: number;
+}
+export interface SpriteRecord {
+	/** sprites.dat id for a pure sprite, units.dat id for a unit sprite (see `SpriteFlag.PureSprite`). */
+	spriteId: number;
+	x: number;
+	y: number;
+	owner: number;
+	unused: number;
+	/**
+	 * `SpriteFlag` bits. StarEdit writes a doodad's overlay sprite with the doodad's whole
+	 * CV5 flag word here, so real maps carry the terrain bits (0x80, 0x100, …) too.
+	 */
+	flags: number;
+}
+/**
+ * One placed doodad, as StarEdit records it (the game never reads this section: it sees
+ * only the doodad's tiles in MTXM and its overlay in THG2). `doodadId` is the index into
+ * the tileset's `dddata.bin`, not a CV5 group; `x`/`y` are the pixel centre of the
+ * footprint, so the top-left tile is `x / 32 - width / 2`.
+ */
+export interface DoodadRecord {
+	doodadId: number;
+	x: number;
+	y: number;
+	owner: number;
+	/** 0 = enabled (every doodad in Blizzard's maps), 1 = disabled. */
+	disabled: number;
+}
+export interface LocationRecord {
+	left: number;
+	top: number;
+	right: number;
+	bottom: number;
+	nameIndex: number;
+	/** Bit 0 low ground, 1 medium, 2 high, 3 low air, 4 medium air, 5 high air. */
+	elevationFlags: number;
+}
+export interface Forces {
+	/** Force index (0-3) each of the 8 playable slots belongs to. */
+	playerForce: number[];
+	/** String index of each force's name. */
+	nameIndex: number[];
+	/** Bit 0 random start, 1 allied, 2 allied victory, 3 shared vision. */
+	flags: number[];
+}
+export interface PlayerRgb {
+	/** `[r, g, b]` for each of the 8 playable slots; only read when `mode` is `Custom`. */
+	rgb: [
+		number,
+		number,
+		number
+	][];
+	/** A `ColorMode` per slot. */
+	mode: number[];
+}
+export interface UnitSettings {
+	/** 1 = the game uses units.dat / weapons.dat for this type and ignores the columns below. */
+	useDefault: Uint8Array;
+	/** Fixed point: hit points × 256, like units.dat. */
+	hitPoints: Uint32Array;
+	shields: Uint16Array;
+	armor: Uint8Array;
+	/** Game frames (15 per second at Fastest). */
+	buildTime: Uint16Array;
+	mineralCost: Uint16Array;
+	gasCost: Uint16Array;
+	/** String index of the custom name, 0 for the default one. */
+	nameIndex: Uint16Array;
+	/** Per weapons.dat id, always `WEAPONS_BW` long; UNIS only stores the first 100. */
+	weaponDamage: Uint16Array;
+	weaponBonus: Uint16Array;
+}
+/**
+ * Which players may build which unit types. Three tables, player-major (`puniIndex`):
+ * a per-player answer, the global default, and whether each player defers to it.
+ */
+export interface UnitAvailability {
+	/** 1 = the player can build the type; read only where `playerUsesDefault` is 0. */
+	playerAvailable: Uint8Array;
+	/** 1 = the type is available to every player that uses the default. */
+	defaultAvailable: Uint8Array;
+	/** 1 = the player takes `defaultAvailable` for the type. */
+	playerUsesDefault: Uint8Array;
+}
+/**
+ * Research cost per upgrade: a base and a per-level factor for minerals, gas and time.
+ * Struct of arrays over 61 upgrades; the original sections only store the first 46.
+ */
+export interface UpgradeSettings {
+	/** 1 = the game uses upgrades.dat for this upgrade and ignores the columns below. */
+	useDefault: Uint8Array;
+	mineralCost: Uint16Array;
+	mineralFactor: Uint16Array;
+	gasCost: Uint16Array;
+	gasFactor: Uint16Array;
+	/** Game frames. */
+	timeCost: Uint16Array;
+	timeFactor: Uint16Array;
+}
+/**
+ * How far each player may research each upgrade and where they start. Player-major
+ * tables (`upgradeIndex`), a global default pair, and a per-player "use the default" flag.
+ */
+export interface UpgradeRestrictions {
+	playerMax: Uint8Array;
+	playerStart: Uint8Array;
+	defaultMax: Uint8Array;
+	defaultStart: Uint8Array;
+	playerUsesDefault: Uint8Array;
+}
+export interface TechSettings {
+	/** 1 = the game uses techdata.dat for this ability. */
+	useDefault: Uint8Array;
+	mineralCost: Uint16Array;
+	gasCost: Uint16Array;
+	/** Game frames. */
+	researchTime: Uint16Array;
+	energyCost: Uint16Array;
+}
+/** Whether each player may research each ability and whether they start with it. Same shape as `UpgradeRestrictions`. */
+export interface TechRestrictions {
+	playerAvailable: Uint8Array;
+	playerResearched: Uint8Array;
+	defaultAvailable: Uint8Array;
+	defaultResearched: Uint8Array;
+	playerUsesDefault: Uint8Array;
+}
+export interface CuwpSlot {
+	/** `CuwpValid` bits. */
+	validProperties: number;
+	/** `CuwpField` bits. */
+	validFields: number;
+	/** Unused by the game; StarEdit writes 0. */
+	owner: number;
+	hitPointsPercent: number;
+	shieldsPercent: number;
+	energyPercent: number;
+	resources: number;
+	hangar: number;
+	/** `CuwpState` bits. */
+	stateFlags: number;
+	/** The record's last four bytes, kept for fidelity. */
+	unused: number;
+}
+export interface ConditionRecord {
+	/** 1-based location number, 0 = none. */
+	location: number;
+	/** `PlayerGroup`. */
+	player: number;
+	amount: number;
+	unitId: number;
+	/** `Comparison` for numeric conditions; `SwitchState` for Switch. */
+	comparison: number;
+	/** `ConditionType`. */
+	type: number;
+	/** `ResourceType` / `ScoreType` / switch number, per type. */
+	resource: number;
+	/** `ConditionFlag` bits. */
+	flags: number;
+	/** EUD mask word; 0 in ordinary maps. */
+	mask: number;
+}
+export interface ActionRecord {
+	/** 1-based source location, 0 = none. */
+	location: number;
+	/** String index for text / comment / leaderboard label, 0 = none. */
+	text: number;
+	/** String index of the WAV file name, 0 = none. */
+	wav: number;
+	/** Milliseconds for Wait / Transmission / Talking Portrait; WAV duration for Play WAV. */
+	time: number;
+	/** `PlayerGroup` (first). */
+	player: number;
+	/** Second player / destination location / amount / AI script code, per type. */
+	target: number;
+	/** Unit id / `ScoreType` / `ResourceType` / `AllianceStatus`, per type. */
+	unitId: number;
+	/** `ActionType` (or `BriefingActionType` in MBRF). */
+	type: number;
+	/** Unit count (0 = all) / `SetModifier` / `SwitchAction` / `Order` / `UnitState`, per type. */
+	modifier: number;
+	/** `ActionFlag` bits. */
+	flags: number;
+	padding: number;
+	/** EUD mask word; 0 in ordinary maps. */
+	mask: number;
+}
+export interface TriggerRecord {
+	conditions: ConditionRecord[];
+	actions: ActionRecord[];
+	/** `TriggerFlag` bits. */
+	flags: number;
+	/** 27 bytes, one per `PlayerGroup`; non-zero = the trigger runs for that group. */
+	players: number[];
+	/** The game's bookkeeping byte (offset 2399); StarEdit writes 0. */
+	currentAction: number;
+}
+/**
+ * A parsed scenario.
+ *
+ * `chk` holds every original section in file order and is the fidelity anchor: sections
+ * we do not model are re-emitted byte for byte, so opening and saving a map we only
+ * partly understand does not destroy the parts we don't. Only names listed in `dirty`
+ * are re-encoded on save.
+ */
+export interface Scenario {
+	chk: ChkFile;
+	dirty: Set<string>;
+	warnings: string[];
+	/** TYPE, e.g. "RAWB" for Brood War. */
+	type: string;
+	/** VER: 59 original, 63 hybrid, 205 Brood War, 206 Remastered. */
+	fileVersion: number;
+	width: number;
+	height: number;
+	/** ERA value as stored; the meaningful tileset is `tilesetId`. */
+	era: number;
+	strings: StringTable;
+	nameIndex: number;
+	descriptionIndex: number;
+	playerTypes: number[];
+	/**
+	 * IOWN: StarEdit's own copy of the player types — what its Player Settings dialog
+	 * shows, where the game reads OWNR. The editor keeps the two in step; a file where they
+	 * differ (another tool wrote one and not the other) is flagged by Check Map. Null when
+	 * the file has no section.
+	 */
+	editorPlayerTypes: number[] | null;
+	playerRaces: number[];
+	playerColors: number[];
+	/** CRGB, Remastered's per-slot colour choice; null when the file has none (every client then reads COLR). */
+	playerRgb: PlayerRgb | null;
+	forces: Forces;
+	/** UNIx if the file has one, else UNIS; null when it has neither (every type on its dat defaults). */
+	unitSettings: UnitSettings | null;
+	/** PUNI; null when the file has none (everything buildable by everyone). */
+	unitAvailability: UnitAvailability | null;
+	/** UPGx if the file has one, else UPGS; null when it has neither (every upgrade on its dat costs). */
+	upgradeSettings: UpgradeSettings | null;
+	/** PUPx else UPGR; null when absent (every player on the dat level caps, starting at 0). */
+	upgradeRestrictions: UpgradeRestrictions | null;
+	/** TECx else TECS; null when absent. */
+	techSettings: TechSettings | null;
+	/** PTEx else PTEC; null when absent (everything researchable, nothing researched). */
+	techRestrictions: TechRestrictions | null;
+	/** WAV: 512 string indices of the map's sound paths; null when the file has no section. */
+	wavs: number[] | null;
+	/** UPRP: the 64 Create Unit with Properties slots (the action names one 1-based); null when the file has no section. */
+	cuwp: CuwpSlot[] | null;
+	/** UPUS: StarEdit's "slot in use" byte per CUWP slot; null when the file has no section. */
+	cuwpUsed: boolean[] | null;
+	/** MTXM: what the game draws — terrain with the doodads stamped over it. */
+	tiles: Uint16Array;
+	/**
+	 * TILE: StarEdit's copy of the terrain *without* doodads (a doodad's cells hold the
+	 * ground it was placed on). Terrain brushes write both arrays; placing a doodad writes
+	 * only `tiles`, and removing one restores its cells from here. A file without TILE
+	 * starts with a copy of MTXM.
+	 */
+	editorTiles: Uint16Array;
+	isom: Uint16Array | null;
+	mask: Uint8Array | null;
+	units: UnitRecord[];
+	sprites: SpriteRecord[];
+	doodads: DoodadRecord[];
+	locations: LocationRecord[];
+	/** TRIG, in execution order. */
+	triggers: TriggerRecord[];
+	/** MBRF: mission briefings, same record layout with briefing action types. */
+	briefing: TriggerRecord[];
+	/** SWNM: string index per switch (0 = unnamed); null when the file has no section. */
+	switchNames: number[] | null;
+}
+export type MapVersion = "original" | "hybrid" | "broodwar" | "remastered";
+export interface Cv5Group {
+	/** Doodad groups store 1 here; terrain groups store a group type. */
+	index: number;
+	/** The full u16 flag word; see GroupFlag. */
+	flags: number;
+	/** Low byte of `flags`: walkability, creep and the unbuildable bit. */
+	buildability: number;
+	/** High byte of `flags`: view-blocking and the ground-height bits. */
+	groundHeight: number;
+	/**
+	 * ISOM link on each side: values up to 48 are "soft" links shared with whatever
+	 * terrain borders this piece, higher ones are "hard" links that pair pieces of the
+	 * same edge set. Flat ground has the same soft link on all four sides.
+	 */
+	edges: {
+		left: number;
+		top: number;
+		right: number;
+		bottom: number;
+	};
+	/**
+	 * How cliff pieces stack vertically: a group whose `top` equals the `bottom` of the
+	 * group above it continues that cliff face. Zero means nothing stacks that way.
+	 */
+	stack: {
+		left: number;
+		top: number;
+		right: number;
+		bottom: number;
+	};
+	/** VX4 megatile index for each of the 16 slots in the group. */
+	megatiles: Uint16Array;
+	/** Set on doodad groups (`index` 1), which store a different record in the edge/stack bytes. */
+	doodad?: Cv5Doodad;
+}
+/**
+ * What a doodad group stores where terrain groups keep their ISOM links. A doodad spans
+ * one group per row: row `r` of the doodad whose first group is `g` is group `g + r`,
+ * with column `c` in megatile slot `c` (so its MTXM id is `((g + r) << 4) | c`). Every
+ * group of the doodad repeats the same `ddData`, `width` and `height`.
+ */
+export interface Cv5Doodad {
+	/** sprites.dat id (DoodadFlag.SpriteOverlay) or units.dat id (DoodadFlag.UnitOverlay) drawn over the tiles. */
+	overlay: number;
+	/** 1-based `rez\stat_txt.tbl` index of the palette category ("Trees", "Cliff", …); 0 for the unlisted ones. */
+	nameIndex: number;
+	/** Index into `tileset\<name>\dddata.bin`, and what DD2 records store. */
+	ddData: number;
+	width: number;
+	height: number;
+}
+export interface Tileset {
+	/** 256 RGBA entries, 4 bytes each. */
+	palette: Uint8Array;
+	/** VR4: `minitiles[i * 64 + n]` is a palette index. */
+	minitiles: Uint8Array;
+	/** VX4 refs, 16 per megatile: bit 0 is horizontal flip, the rest is the minitile index. */
+	megatileRefs: Uint32Array;
+	megatileCount: number;
+	/** True when the source was .vx4ex (Remastered, 32-bit refs). */
+	extended: boolean;
+	/** VF4 flags, 16 per megatile. */
+	megatileFlags: Uint16Array;
+	groups: Cv5Group[];
+}
+/** One rotating run of palette entries, `min..max` inclusive. */
+export interface PaletteBand {
+	min: number;
+	max: number;
+}
+/**
+ * All of a tileset's megatiles rendered once into a single image, so the viewport can
+ * draw terrain with one `drawImage` per visible tile instead of decoding minitiles on
+ * every frame.
+ */
+export interface TilesetAtlas {
+	image: CanvasImageSource;
+	/** Megatiles per atlas row. */
+	columns: number;
+	tileSize: number;
+	count: number;
+	/** Packed 0xRRGGBB average of each megatile, for minimap and far-zoom drawing. */
+	averages: Uint32Array;
+	/** The cycling (water/lava) megatiles, or null when the tileset has none. */
+	animation: AtlasAnimation | null;
+}
+/**
+ * A second, small atlas holding only the megatiles that reference cycling palette
+ * entries. It is re-rasterised with the rotated palette on every step, while the main
+ * atlas stays at step 0; `atlasSource` picks the right one per megatile.
+ */
+export interface AtlasAnimation {
+	image: HTMLCanvasElement;
+	columns: number;
+	/** Megatile → slot in this atlas, or -1 for megatiles that do not cycle. */
+	slot: Int32Array;
+	megatiles: Uint32Array;
+	bands: readonly PaletteBand[];
+	/** Steps until the cycle repeats. */
+	length: number;
+	/** The step the image currently shows. */
+	step: number;
+	pixels: ImageData;
+	/** Scratch palette, rotated in place each step. */
+	palette: Uint8Array;
+}
+export interface DoodadDef {
+	/** The `dddata.bin` index, which DD2 records store. */
+	id: number;
+	/** First CV5 group; row `r` is group `group + r`, column `c` is slot `c`. */
+	group: number;
+	width: number;
+	height: number;
+	/** Palette category, from stat_txt.tbl; "Unlisted" for groups without a name. */
+	category: string;
+	/** The first group's CV5 flag word — copied onto the overlay's THG2 record, as StarEdit does. */
+	flags: number;
+	/** The sprite (or unit) drawn over the tiles, or null. */
+	overlay: DoodadOverlay | null;
+	/** MTXM id per cell, row-major; 0 where the doodad leaves the ground alone. */
+	tiles: Uint16Array;
+	/** CV5 group required under each cell, row-major; 0 = no requirement. */
+	required: Uint16Array;
+	/**
+	 * Whether any of its minitiles carries the VF4 ramp bit. StarEdit files ramps under the
+	 * cliff categories with no name of their own; this is the only way to tell them apart.
+	 */
+	ramp: boolean;
+}
+export interface DoodadOverlay {
+	kind: "sprite" | "unit";
+	/** sprites.dat or units.dat id. */
+	id: number;
+	flipped: boolean;
+}
+export interface DoodadCategory {
+	name: string;
+	doodads: DoodadDef[];
+}
+export interface DoodadCatalogue {
+	doodads: DoodadDef[];
+	byId: Map<number, DoodadDef>;
+	/** In first-appearance order, the way StarEdit's category drop-down lists them; "Unlisted" last. */
+	categories: DoodadCategory[];
+	/** Whether dddata.bin was available; without it nothing is ever refused for its ground. */
+	hasPlacementData: boolean;
+}
+declare const TILESET_FILENAMES: readonly [
+	"badlands",
+	"platform",
+	"install",
+	"ashworld",
+	"jungle",
+	"desert",
+	"ice",
+	"twilight"
+];
+export type TilesetFileName = (typeof TILESET_FILENAMES)[number];
+export interface LoadedTileset {
+	name: TilesetFileName;
+	tileset: Tileset;
+	atlas: TilesetAtlas;
+	/** The doodads the CV5 holds, with their placement rules when `<name>.dddata.bin` was extracted. */
+	doodads: DoodadCatalogue;
+}
+/** StarCraft tileset reference data. */
+export type TilesetId = "badlands" | "platform" | "install" | "ashworld" | "jungle" | "desert" | "ice" | "twilight";
+/**
+ * One ISOM terrain type: its id is the CV5 `index` of the flat left/right group pair
+ * that draws it, and the value the ISOM section stores for it.
+ */
+export interface TerrainName {
+	id: number;
+	name: string;
+}
+export interface TerrainType extends TerrainName {
+	/** Even CV5 group of the flat pair; odd columns use `group + 1`. */
+	group: number;
+	height: 0 | 1 | 2;
+	buildable: boolean;
+}
+export type GroupKind = "terrain" | "edge" | "doodad" | "other";
+export interface TileInfo {
+	id: number;
+	group: number;
+	slot: number;
+	/** VX4 megatile, or -1 when the id points at nothing drawable. */
+	megatile: number;
+	kind: GroupKind;
+	label: string;
+	height: 0 | 1 | 2;
+	buildable: boolean;
+	/** Walkable minitiles out of 16, from VF4. */
+	walkable: number;
+}
+export interface TileChange {
+	/** Flat index into `scenario.tiles`. */
+	at: number;
+	before: number;
+	after: number;
+	/**
+	 * What `scenario.editorTiles` (TILE) held before a terrain change, when that differs
+	 * from `before` (the cell was under a doodad). Filled in by `applyChanges` the first
+	 * time a change is applied, so undo can put the ground back rather than the doodad tile.
+	 */
+	under?: number;
+}
+export interface Rect {
+	x0: number;
+	y0: number;
+	/** Exclusive. */
+	x1: number;
+	y1: number;
+}
+/** What Replace Terrain matches or writes: a flat terrain type (by ISOM id) or one exact tile. */
+export type TerrainPick = {
+	kind: "terrain";
+	id: number;
+	variation?: number;
+} | {
+	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 the verdict the palette and Check Map draw from it. */
+export interface IsomReport extends IsomCheck {
+	/** More than `STALE_ISOM_SHARE` of the rects disagree with their tiles. */
+	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;
+	/** First subunit (turret), or NO_UNIT. */
+	subunit: Uint16Array;
+	/** Starting facing 0–31 (0 = up, 8 = right, 16 = down), or RANDOM_DIRECTION. */
+	direction: Uint8Array;
+	shieldEnable: Uint8Array;
+	shieldAmount: Uint16Array;
+	/** Fixed point: hit points × 256. */
+	hitPoints: Uint32Array;
+	elevation: Uint8Array;
+	/** UnitFlag bits. */
+	flags: Uint32Array;
+	/** StarEdit placement box, pixels. Buildings are placed on the tile grid by this box. */
+	placementWidth: Uint16Array;
+	placementHeight: Uint16Array;
+	/** Collision extents from the unit's centre, pixels. */
+	extentLeft: Uint16Array;
+	extentUp: Uint16Array;
+	extentRight: Uint16Array;
+	extentDown: Uint16Array;
+	mineralCost: Uint16Array;
+	vespeneCost: Uint16Array;
+	/** Game frames. */
+	buildTime: Uint16Array;
+	armor: Uint8Array;
+	/** weapons.dat ids, or NO_WEAPON. */
+	groundWeapon: Uint8Array;
+	airWeapon: Uint8Array;
+	/** Bit 0 Zerg, 1 Terran, 2 Protoss, 3 men, 4 building, 5 factory, 6 independent, 7 neutral. */
+	groupFlags: Uint8Array;
+	/** StarEdit availability flags; all zero for the legacy layout. */
+	availability: Uint16Array;
+}
+export interface FlingyDat {
+	/** sprites.dat index. */
+	sprite: Uint16Array;
+}
+export interface SpritesDat {
+	/** images.dat index. */
+	image: Uint16Array;
+}
+export interface ImagesDat {
+	/** 1-based images.tbl index of the GRP path, relative to `unit\`. */
+	grp: Uint32Array;
+	/** 1 when the GRP holds 17 frames per facing set (directions 0–16, the rest mirrored). */
+	graphicTurns: Uint8Array;
+	drawFunction: Uint8Array;
+	remapping: Uint8Array;
+	/** iscript.bin id of the image's animation script. */
+	iscript: Uint32Array;
+	/** 1-based images.tbl indices of the overlay position files (0 = none), in LO_KINDS order. */
+	lo: Uint32Array[];
+}
+export interface WeaponsDat {
+	damage: Uint16Array;
+	/** Added per upgrade level. */
+	bonus: Uint16Array;
+}
+export type Race = "zerg" | "terran" | "protoss" | null;
+/** The columns Upgrade Settings shows as defaults: base cost and per-level factor for minerals, gas and time, plus the level cap. */
+export interface UpgradesDat {
+	mineralCost: Uint16Array;
+	mineralFactor: Uint16Array;
+	vespeneCost: Uint16Array;
+	vespeneFactor: Uint16Array;
+	/** Game frames. */
+	timeCost: Uint16Array;
+	timeFactor: Uint16Array;
+	/** Highest level the upgrade goes to (3 for armour / weapons, 1 for the rest). */
+	maxRepeats: Uint8Array;
+	/** 1 for upgrades only Brood War has. */
+	broodWar: Uint8Array;
+}
+/** The columns Technology Settings shows as defaults. */
+export interface TechdataDat {
+	mineralCost: Uint16Array;
+	vespeneCost: Uint16Array;
+	/** Game frames. */
+	researchTime: Uint16Array;
+	energyCost: Uint16Array;
+	/** 1 for abilities only Brood War has. */
+	broodWar: Uint8Array;
+}
+export interface SpriteGroup {
+	label: string;
+	ids: number[];
+}
+/**
+ * Plain types the chrome and the plugin API share: what the editor's layers, terrain
+ * modes, View ticks and notices are called. No state lives here — the atoms in
+ * `atoms/editorAtoms.ts` and `atoms/uiAtoms.ts` hold that and re-export these — so the
+ * plugin typings (`npm run build:plugin-types`) can name them without dragging Jotai in.
+ */
+/** The classic SCMDraft layer combo; `"clipboard"` is Cut / Copy / Paste. */
+export type EditorLayer = "terrain" | "doodads" | "units" | "sprites" | "locations" | "fog" | "clipboard";
+export type TerrainMode = "isom" | "rect" | "tile" | "blend";
+export interface ViewFlags {
+	grid: boolean;
+	locations: boolean;
+	locationNames: boolean;
+	units: boolean;
+	sprites: boolean;
+	/** Off draws the ground under the doodads (TILE) instead of the picture (MTXM). */
+	doodads: boolean;
+	fog: boolean;
+	/** Ground height per minitile, tinted (mid amber, high red). */
+	elevation: boolean;
+	/** Unbuildable tile groups, hatched in blue. */
+	buildability: boolean;
+	startLocations: boolean;
+	/** Cycle the palette so water and lava animate as they do in game. */
+	animateWater: boolean;
+	/** Run the units' iscript idle animations (turrets, pulsing buildings, fires, smoke). */
+	animateUnits: boolean;
+}
+/**
+ * A short notice over the map that leaves by itself — what a save says when it is done,
+ * since the status bar line is easy to miss and the menubar dot only stops glowing.
+ */
+export interface Toast {
+	id: number;
+	kind: "ok" | "info" | "warn" | "error";
+	title: string;
+	detail?: string;
+	/** Milliseconds before it leaves on its own; 0 keeps it until dismissed. */
+	ttl: number;
+	/**
+	 * One button beside the text, for a notice that is really a question — the update
+	 * check's "Download". Pressing it dismisses the toast as well as running this.
+	 */
+	action?: {
+		label: string;
+		run: () => void;
+	};
+}
+/**
+ * The colour and layout codes StarCraft reads out of a string, and what a string looks
+ * like once the game has read them.
+ *
+ * Bytes 0x01–0x1F are control codes: most set the text colour, a few move the text or
+ * hide it, and 0x09 / 0x0A / 0x0D are the ordinary whitespace `escapeControls` leaves
+ * literal. The table is the one the community documents (wiki.staredit.net/wiki/Color,
+ * cross-checked against the reference tables mirrored on staredit-network.fandom.com) —
+ * the twelve player colours in it are the classic Brood War player palette, which is what
+ * confirms the numbering. **The editor's older table was wrong from 0x12 up**: it had the
+ * alignment codes one byte early and called 0x18 black, when 0x18 is player 9's green.
+ *
+ * `RGB` values are the palette entries the game draws with; they are constants here rather
+ * than read from game data because the font palette is not one of the files `npm run
+ * extract` pulls out (only `tunit.pcx` lands in `public/game/`), and a swatch needs a
+ * colour whether or not the archives are present.
+ *
+ * ## Remastered
+ *
+ * `runsOf` models **Remastered's** rule, not 1.16.1's: a colour set on one line carries
+ * onto the next line of the same string. In 1.16.1 every newline reset the text to the
+ * default colour, so a string written before the remaster can render differently now —
+ * `bleedingLines` finds exactly that case, and the Repair plugin turns it into a finding
+ * offering to write the reset the old game supplied for free.
+ */
+/** What a control byte does. Colours carry an `rgb`; the rest are layout or visibility. */
+export type CodeEffect = "color" | "mimic" | "invisible" | "align" | "clip" | "nothing" | "space";
+export interface TextCode {
+	byte: number;
+	/** `<0E>`, the way every StarCraft editor writes it. */
+	code: string;
+	label: string;
+	effect: CodeEffect;
+	/** `#rrggbb` for `effect: "color"`, else null. */
+	rgb: string | null;
+	/** Which player's colour this is, for the ones that are a player colour (1-based). */
+	player?: number;
+}
+export type Align = "left" | "right" | "center";
+/** One stretch of text in a single colour. */
+export interface TextRun {
+	text: string;
+	/** `#rrggbb`; the default colour until a code says otherwise. */
+	color: string;
+	/** After `<0B>` / `<14>`: the game draws nothing, but the text is still there. */
+	invisible: boolean;
+	/** After `<0C>` in the large font: the rest of the line is dropped. */
+	clipped: boolean;
+}
+export interface TextLine {
+	runs: TextRun[];
+	align: Align;
+}
+export interface RunOptions {
+	/**
+	 * Reset to `DEFAULT_TEXT_COLOR` at every newline, the way 1.16.1 did. Remastered
+	 * carries the colour across, which is the default here.
+	 */
+	resetPerLine?: boolean;
+	/** What `<01>` mimics and what the string starts in. */
+	initialColor?: string;
+}
+export interface BleedingLine {
+	/** 0-based index of the line that inherits a colour it did not set. */
+	line: number;
+	/** The code Remastered carries onto it — the whole entry, so a caller can name it. */
+	carried: TextCode;
+}
+/** 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" | "textTriggerEditor" | "missionBriefing" | "cuwpEditor" | "replaceTerrain" | "autoStarts" | "testMap" | "symmetry" | "gridSettings" | "preferences" | "shortcuts" | "validateMap" | "statistics" | "importTriggers" | "exportTriggers" | "importStrings" | "exportStrings" | "find" | "about" | "confirmClose" | "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;
+	units: boolean;
+	sprites: boolean;
+	locations: boolean;
+	locationNames: boolean;
+	startLocations: boolean;
+	fog: boolean;
+	/** Whose fog is drawn (0-based player), when `fog` is on. */
+	fogPlayer: number;
+	/** Grid spacing in map pixels (32 = one tile); 0 for no grid. */
+	grid: number;
+	/**
+	 * The part of the map to draw, in tiles (exclusive `x1` / `y1`). The whole map when
+	 * absent. Everything is drawn in map coordinates and the canvas is translated, so a
+	 * region looks exactly like that part of the full picture — a unit half outside the
+	 * region still leans in.
+	 */
+	rect?: Rect | null;
+}
+/** What the registry knows about a section name, sized for one map. */
+export interface SectionKnowledge {
+	name: string;
+	/** "Placed units", "String table", … */
+	what: string;
+	/** How the game combines repeated occurrences. */
+	mode: CombineMode;
+	/** The fixed buffer the game reads the section into, for this map's size; null when the length varies. */
+	size: number | null;
+	/** The record length of a list section, or null. */
+	stride: number | null;
+	/** Whether the editor decodes the section into its model and re-encodes it on save. */
+	modelled: boolean;
+}
+/** One occurrence of a section in the file, as Save would write it. */
+export interface SectionInfo {
+	/** Position in the file's section list — what the byte-level calls take. */
+	index: number;
+	/** The four characters as stored (`"VER "` keeps its space); junk in a protected map. */
+	name: string;
+	/** Byte offset of the eight-byte chunk header within the CHK. */
+	offset: number;
+	/** Payload length. */
+	size: number;
+	/** The length field as written; differs from `size` only when the file ended early. */
+	declaredSize: number;
+	truncated: boolean;
+	/** Which occurrence of this name it is, 0-based, and how many the file has. */
+	occurrence: number;
+	occurrences: number;
+	/** Whether the editor has unsaved changes it will encode into this section on save. */
+	dirty: boolean;
+	/** The registry entry, or null for a section the editor has never heard of. */
+	spec: SectionKnowledge | null;
+}
+/** What `rebuildSections` did: the parser's remarks and the sections actually re-encoded. */
+export interface RebuildResult {
+	warnings: string[];
+	rebuilt: string[];
+}
+export type ArgKind = "player" | "unit" | "location" | "switch" | "comparison" | "switchState" | "switchAction" | "modifier" | "unitState" | "order" | "alliance" | "resource" | "score" | "aiScript" | "textFlags" | "text" | "wav" | "number" | "amount" | "count" | "duration" | "percent" | "cuwp" | "slot";
+export type ConditionField = keyof ConditionRecord;
+export type ActionField = keyof ActionRecord;
+export interface ArgDef<F extends string> {
+	kind: ArgKind;
+	field: F;
+	label: string;
+}
+export interface ConditionDef {
+	type: number;
+	name: string;
+	args: ArgDef<ConditionField>[];
+}
+export interface ActionDef {
+	type: number;
+	name: string;
+	args: ArgDef<ActionField>[];
+	/** Text / Transmission: the `AlwaysDisplay` flag is an argument of its own. */
+	hasTextFlags?: boolean;
+}
+export interface Choice {
+	value: number;
+	label: string;
+	/** Extra spellings the text parser accepts. */
+	aliases?: string[];
+}
+/** How the text format names things it cannot know on its own. */
+export interface TriggerNames {
+	/** Text of a string-table entry, null when unset. */
+	string(index: number): string | null;
+	/** Index for `text` — an existing identical entry or a new one. Only called while parsing. */
+	intern(text: string): number;
+	/** Display name of a 1-based location number. */
+	location(number: number): string;
+	/** 1-based number for a location name (or `Location N` / `Anywhere`), undefined when unknown. */
+	locationByName(name: string): number | undefined;
+	unit(id: number): string;
+	unitByName(name: string): number | undefined;
+	/** Display name of a 0-based switch. */
+	switch(index: number): string;
+	switchByName(name: string): number | undefined;
+}
+export interface TextTrigger {
+	trigger: TriggerRecord;
+	/** 1-based line the `Trigger(` header starts on. */
+	line: number;
+}
+export type IssueLevel = "error" | "warn" | "info";
+export type IssueTarget = {
+	kind: "location";
+	index: number;
+} | {
+	kind: "unit";
+	index: number;
+} | {
+	kind: "trigger";
+	index: number;
+} | {
+	kind: "dialog";
+	id: DialogId;
+};
+export interface Issue {
+	level: IssueLevel;
+	text: string;
+	where: string;
+	target?: IssueTarget;
+}
+export interface PlayerStatistics {
+	slot: number;
+	type: string;
+	race: string;
+	units: number;
+	/** Null when units.dat is not loaded. */
+	buildings: number | null;
+	startLocations: number;
+}
+export interface MapStatistics {
+	width: number;
+	height: number;
+	tileset: string;
+	revision: string;
+	sections: number;
+	strings: {
+		slots: number;
+		set: number;
+		extended: boolean;
+	};
+	players: PlayerStatistics[];
+	/** Units whose owner byte is past the twelve slots. */
+	unownedUnits: number;
+	units: {
+		total: number;
+		buildings: number | null;
+		top: {
+			id: number;
+			name: string;
+			count: number;
+		}[];
+	};
+	resources: {
+		minerals: number;
+		gas: number;
+		fields: number;
+		geysers: number;
+	};
+	doodads: number;
+	sprites: {
+		pure: number;
+		unit: number;
+	};
+	locations: number;
+	triggers: {
+		count: number;
+		conditions: number;
+		actions: number;
+		preserved: number;
+		disabled: number;
+	};
+	/** MBRF: the briefing's records and the actions in them. */
+	briefings: {
+		count: number;
+		actions: number;
+	};
+	switchesNamed: number;
+	sounds: number;
+	/** Tiles per terrain type ("Edges and cliffs" for the unnamed edge sets), most common first; null without the tileset graphics. */
+	terrain: {
+		name: string;
+		tiles: number;
+	}[] | null;
+}
+export type FindKind = "units" | "locations" | "sprites" | "doodads" | "strings" | "triggers" | "briefing";
+export interface FindResult {
+	kind: FindKind;
+	/** Index into the list the kind names (unit / sprite / trigger index, location slot, string index). */
+	index: number;
+	label: string;
+	detail: string;
+	/** Tile coordinates to centre on, where the thing has a position. */
+	x?: number;
+	y?: number;
+}
+export interface FindOptions {
+	kind: FindKind;
+	query: string;
+	matchCase?: boolean;
+	/** Display name of a sprite record (needs the game data); the id when omitted. */
+	spriteName?: (r: SpriteRecord) => string;
+	/** Display name of a doodad record (needs the tileset); the id when omitted. */
+	doodadName?: (r: DoodadRecord) => string;
+	limit?: number;
+}
+export type StringUsageKind = "name" | "description" | "force" | "location" | "unit" | "switch" | "trigger" | "briefing" | "wav";
+export interface StringUsage {
+	kind: StringUsageKind;
+	/** What the kind indexes: force / slot / unit id / switch / trigger index / WAV slot; 0 for name and description. */
+	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;
+	/** Refuse unwalkable ground for units and unbuildable tiles for buildings. */
+	checkTerrain: boolean;
+	/** After a terrain edit, remove units the new terrain can no longer hold (the Terrain palette's toggle). */
+	removeStranded: boolean;
+	/** Buildings snap their placement box to the tile grid (StarEdit always does; SCMDraft lets you turn it off). */
+	snapToGrid: boolean;
+}
+export type PlacementProblem = "terrain" | "collision";
+export interface PlacementVerdict {
+	problem: PlacementProblem | null;
+	/** The unit in the way, for collision problems. */
+	blocker: number;
+	/** The problem as a sentence fragment — "the ground is unwalkable", "it overlaps Terran Marine" — null when it fits. */
+	reason: string | null;
+}
+export interface PlayerSlotView {
+	/** 0-based; the chrome shows it as `slot + 1`. */
+	slot: number;
+	type: number;
+	typeName: string;
+	race: number;
+	raceName: string;
+	/** COLR index; null for the four unplayable slots. */
+	color: number | null;
+	/** The colour the chrome shows for the slot (CRGB-aware). */
+	colorHex: string | null;
+	/** The CRGB custom triple when one is in effect. */
+	rgb: [
+		number,
+		number,
+		number
+	] | null;
+	/** 0-based force; null for the unplayable slots. */
+	force: number | null;
+	forceName: string | null;
+}
+export interface PlayerPatch {
+	type?: number;
+	race?: number;
+	/** COLR index 0–15 (playable slots). */
+	color?: number;
+	/** A CRGB custom colour, or null to go back to the palette colour (playable slots). */
+	rgb?: [
+		number,
+		number,
+		number
+	] | null;
+	/** 0-based force (playable slots). */
+	force?: number;
+}
+export interface ForceView {
+	/** 0-based. */
+	force: number;
+	name: string;
+	flags: number;
+	allied: boolean;
+	alliedVictory: boolean;
+	sharedVision: boolean;
+	randomStart: boolean;
+	/** 0-based playable slots in the force. */
+	players: number[];
+}
+export interface ForcePatch {
+	name?: string;
+	allied?: boolean;
+	alliedVictory?: boolean;
+	sharedVision?: boolean;
+	randomStart?: boolean;
+	/** The whole flag word, applied before the booleans. */
+	flags?: number;
+	/** 0-based playable slots the force should contain (others keep theirs); moves them from their forces. */
+	players?: number[];
+}
+export interface WeaponView {
+	id: number;
+	name: string;
+	damage: number;
+	bonus: number;
+}
+export interface UnitTypeView {
+	id: number;
+	/** The game's name (or the custom one when the map sets it). */
+	name: string;
+	/** The custom name the map sets, `""` for the default. */
+	customName: string;
+	useDefault: boolean;
+	/** Whole hit points. */
+	hitPoints: number;
+	shields: number;
+	armor: number;
+	/** Game frames. */
+	buildTime: number;
+	mineralCost: number;
+	gasCost: number;
+	/** The type's ground and air weapons (a turreted vehicle's are its turret's), with the effective damage. */
+	weapons: WeaponView[];
+	/** units.dat / weapons.dat, null without the game data. */
+	defaults: {
+		hitPoints: number;
+		shields: number;
+		armor: number;
+		buildTime: number;
+		mineralCost: number;
+		gasCost: number;
+		weapons: WeaponView[];
+	} | null;
+	/** PUNI: whether the type can be built by default, and per player (`"default"` where the player follows the default). */
+	availability: {
+		defaultAvailable: boolean;
+		players: (boolean | "default")[];
+	};
+}
+export interface UnitTypePatch {
+	/** Explicitly back to (or off) the dat defaults; setting any number below turns it off. */
+	useDefault?: boolean;
+	/** Custom name; `""` restores the default. */
+	name?: string;
+	hitPoints?: number;
+	shields?: number;
+	armor?: number;
+	buildTime?: number;
+	mineralCost?: number;
+	gasCost?: number;
+	weapons?: {
+		id: number;
+		damage?: number;
+		bonus?: number;
+	}[];
+	/** PUNI: `player` 0-based or `"default"` (the default column); `value` true / false, or `"default"` to follow the default column again. */
+	available?: {
+		player: number | "default";
+		value: boolean | "default";
+	}[];
+}
+export interface UpgradeLevelsView {
+	start: number;
+	max: number;
+	usesDefault: boolean;
+}
+export interface UpgradeView {
+	id: number;
+	name: string;
+	useDefault: boolean;
+	mineralCost: number;
+	mineralFactor: number;
+	gasCost: number;
+	gasFactor: number;
+	/** Game frames. */
+	timeCost: number;
+	timeFactor: number;
+	/** upgrades.dat, null without the game data. */
+	defaults: {
+		mineralCost: number;
+		mineralFactor: number;
+		gasCost: number;
+		gasFactor: number;
+		timeCost: number;
+		timeFactor: number;
+		maxLevel: number;
+	} | null;
+	/** UPGR / PUPx: the default start and cap, and each of the 12 players' (effective, with `usesDefault`). */
+	levels: {
+		defaultStart: number;
+		defaultMax: number;
+		players: UpgradeLevelsView[];
+	};
+}
+export interface UpgradePatch {
+	useDefault?: boolean;
+	mineralCost?: number;
+	mineralFactor?: number;
+	gasCost?: number;
+	gasFactor?: number;
+	timeCost?: number;
+	timeFactor?: number;
+	/** `player` 0-based or `"default"`; `useDefault: true` puts a player back on the default column. */
+	levels?: {
+		player: number | "default";
+		start?: number;
+		max?: number;
+		useDefault?: boolean;
+	}[];
+}
+export interface TechStateView {
+	available: boolean;
+	researched: boolean;
+	usesDefault: boolean;
+}
+export interface TechView {
+	id: number;
+	name: string;
+	useDefault: boolean;
+	mineralCost: number;
+	gasCost: number;
+	/** Game frames. */
+	researchTime: number;
+	energyCost: number;
+	defaults: {
+		mineralCost: number;
+		gasCost: number;
+		researchTime: number;
+		energyCost: number;
+	} | null;
+	/** PTEC / PTEx: the default column and each of the 12 players' effective state. */
+	state: {
+		defaultAvailable: boolean;
+		defaultResearched: boolean;
+		players: TechStateView[];
+	};
+}
+export interface TechPatch {
+	useDefault?: boolean;
+	mineralCost?: number;
+	gasCost?: number;
+	researchTime?: number;
+	energyCost?: number;
+	/** `player` 0-based or `"default"`; `useDefault: true` puts a player back on the default column. */
+	state?: {
+		player: number | "default";
+		available?: boolean;
+		researched?: boolean;
+		useDefault?: boolean;
+	}[];
+}
+export interface MapVersionView {
+	version: MapVersion;
+	label: string;
+	/** The VER word. */
+	fileVersion: number;
+	type: string;
+	/** Whether the string table is STRx. */
+	extendedStrings: boolean;
+	/** The file extension StarEdit would give it. */
+	extension: string;
+}
+export interface ResizeResult {
+	dx: number;
+	dy: number;
+	unitsDropped: number;
+	spritesDropped: number;
+	doodadsDropped: number;
+	locationsClamped: number;
+	/** True when ISOM was reconstructed from the tiles; false when it is the flat fill's lattice. */
+	isomRebuilt: boolean;
+}
+export interface SoundRow {
+	slot: number;
+	stringIndex: number;
+	/** The path as the string table has it. */
+	path: string;
+	/** Whether the archive carries a member at that path. */
+	present: boolean;
+	/** Bytes in the archive, 0 when absent. */
+	size: number;
+	/** The archive member's name as stored (case may differ from the path). */
+	member: string | null;
+	usedBy: string[];
+}
+/** A slot patch the way the dialog and the plugin API both apply one: only the named fields move. */
+export interface CuwpSlotPatch {
+	/** `null` leaves the field at the unit's default (clears its valid bit); a number sets it and the bit. */
+	hitPointsPercent?: number | null;
+	shieldsPercent?: number | null;
+	energyPercent?: number | null;
+	resources?: number | null;
+	hangar?: number | null;
+	/** `null` leaves the state alone; a boolean forces it. */
+	cloaked?: boolean | null;
+	burrowed?: boolean | null;
+	inTransit?: boolean | null;
+	hallucinated?: boolean | null;
+	invincible?: boolean | null;
+}
+/** The slot as a patch-shaped view: null where the unit's default applies. */
+export interface CuwpSlotView {
+	index: number;
+	used: boolean;
+	/** How many Create Unit with Properties actions name the slot. */
+	references: number;
+	hitPointsPercent: number | null;
+	shieldsPercent: number | null;
+	energyPercent: number | null;
+	resources: number | null;
+	hangar: number | null;
+	cloaked: boolean | null;
+	burrowed: boolean | null;
+	inTransit: boolean | null;
+	hallucinated: boolean | null;
+	invincible: boolean | null;
+	summary: string;
+}
+/** How the members of a map archive are compressed. */
+export type ArchiveCompression = "none" | "zlib" | "pkware";
+export type MapFormat = "scx" | "scm" | "chk";
+export interface SaveOptions {
+	format: MapFormat;
+	/** How every archive member is compressed; ignored for a bare .chk. */
+	compression: ArchiveCompression;
+	/** Encrypt the members as StarEdit does. Every StarCraft build reads it. */
+	encrypt: boolean;
+	/** Archive members left out of the file, by name. */
+	omitExtras: string[];
+	/** Leave out ISOM, TILE and DD2: the terrain-editing data the game never reads. */
+	stripTerrainEditing: boolean;
+	/** Leave out IVER, IVE2, IOWN, UPUS, SWNM and WAV: editor bookkeeping the game never reads. */
+	stripBookkeeping: boolean;
+	/** Leave out sections whose names the format reference does not know. */
+	stripUnknown: boolean;
+	/** Collapse a section that occurs more than once into the bytes the game would act on. */
+	mergeRepeats: boolean;
+	/** Drop bytes after the last section header the file could parse. */
+	dropTrailing: boolean;
+}
+export interface ChangeTilesetResult {
+	from: number;
+	to: number;
+	doodadsDropped: number;
+	/** Overlay sprites that belonged to the dropped doodads. */
+	spritesDropped: number;
+	refilled: boolean;
+}
+export type SymmetryMode = "none" | "h" | "v" | "hv" | "rot180" | "rot90" | "diag" | "adiag";
+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;
+}
+export type StartLayout = "ring" | "corners";
+export interface StartPlacementResult {
+	changes: UnitChange[];
+	/** Per player (0-based), where the start location landed, or null when nothing within reach fit. */
+	placed: ({
+		x: number;
+		y: number;
+	} | null)[];
+	removed: number;
+}
+export type Side = "left" | "top" | "right" | "bottom";
+export interface BlendCandidate {
+	/** MTXM tile id to place. */
+	id: number;
+	megatile: number;
+	/** `edgeDistance` between the anchor's side and this tile's opposite side. */
+	distance: number;
+}
+export interface BlendOptions {
+	/** Largest distance still listed. */
+	maxDistance: number;
+	/** Most candidates listed per side. */
+	limit: number;
+	/** 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;
+	/** 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. */
+export type PasteMode = "merge" | "replace";
+export interface ClipLocation {
+	/** Bounds in map pixels relative to the clip's origin (an inverted box keeps its inversion). */
+	left: number;
+	top: number;
+	right: number;
+	bottom: number;
+	elevationFlags: number;
+	name: string;
+}
+export interface Clip {
+	/** Size in tiles. */
+	width: number;
+	height: number;
+	/** ERA of the source map: tile ids mean nothing on another tileset. */
+	era: number;
+	/** MTXM ids, row-major, or null when terrain was not included. */
+	tiles: Uint16Array | null;
+	/** TILE ids (the ground under the doodads), alongside `tiles`. */
+	ground: Uint16Array | null;
+	/** Records with positions relative to the origin in map pixels. */
+	doodads: DoodadRecord[];
+	units: UnitRecord[];
+	sprites: SpriteRecord[];
+	locations: ClipLocation[];
+	/** MASK bytes, row-major, or null when fog was not included. */
+	fog: Uint8Array | null;
+}
+export interface PasteCounts {
+	tiles: number;
+	doodads: number;
+	units: number;
+	sprites: number;
+	locations: number;
+	fog: number;
+	/** Objects the paste cleared out of the way (replace mode) or that a new tile stranded. */
+	removed: number;
+}
+export interface PasteResult {
+	edit: HistoryEdit;
+	counts: PasteCounts;
+	/** Things that could not be pasted, in words. */
+	notes: string[];
+}
+export interface StringImport {
+	entries: {
+		index: number;
+		text: string;
+	}[];
+	/** Lines that were not `N<TAB>text`, with their 1-based line numbers. */
+	errors: {
+		line: number;
+		message: string;
+	}[];
+}
+export interface Preferences {
+	/** Show the splash while the game data loads; off starts straight on the editor. */
+	splash: boolean;
+	/** Ask before closing or replacing a map with unsaved changes. */
+	confirmClose: boolean;
+	/** What File ▸ New and the startup map start with. */
+	newMap: {
+		tileset: TilesetId;
+		width: number;
+		height: number;
+	};
+	/** Initial View ▸ Animate Water / Animate Units. */
+	animateWater: boolean;
+	animateUnits: boolean;
+	/**
+	 * How fast the two animations run, as a multiple of the game's own speed (1 = the
+	 * game's "Fastest"). One of `ANIMATION_SPEEDS`; applied live, not just at startup.
+	 */
+	animateWaterSpeed: number;
+	animateUnitsSpeed: number;
+	/**
+	 * Tools ▸ Test Map: whether to start the game after writing the map (desktop build), and
+	 * the game folder to use when the desktop build should not search ("" = search). The
+	 * browser's folder is a handle in IndexedDB (`services/handleStore.ts`), not here.
+	 */
+	testMap: {
+		launch: boolean;
+		dir: string;
+	};
+	/**
+	 * The desktop build's in-app updates (`editor/updates.ts`, `desktop/updater.ts`); the
+	 * browser build shows none of this, having nothing to update. `checkOnStart` asks GitHub
+	 * for a newer version a few seconds after launch and raises a toast when there is one.
+	 * `nightly` follows the nightly channel instead of the numbered releases — one-way in
+	 * practice, since going back to a stable release is a downgrade the updater will not
+	 * offer.
+	 */
+	updates: {
+		checkOnStart: boolean;
+		nightly: boolean;
+	};
+}
+/**
+ * The version a host provides; a manifest that asks for a newer one is refused. It stays
+ * at 1 while the API is only used by the plugins in the scm-js organisation and grows
+ * with them — the first incompatible change after outside plugins exist bumps it.
+ */
+export declare const PLUGIN_API_VERSION = 1;
+export interface Disposable {
+	dispose(): void;
+}
+/**
+ * A transaction builder's return type: whatever it likes, so long as it is not a promise.
+ *
+ * Everything asynchronous in this API is a promise — `await` it. The two transaction
+ * builders (`document.edit` and `document.update`) are the exception, and deliberately
+ * so: their operations apply as they are called and one commit closes the transaction
+ * when the builder returns, so an `async` builder would commit the part of its work that
+ * ran before the first `await` and leave the rest to land outside the entry, breaking
+ * undo without an error. Do the awaiting *before* the call:
+ *
+ * ```ts
+ * await api.tileset.load();                       // the async part, first
+ * api.document.edit("Fill", tx => tx.stampTerrain(rect, id));  // then the write
+ * ```
+ *
+ * TypeScript refuses an `async` builder because of this type; `runTransaction` and
+ * `runUpdate` also catch one at runtime, for a plugin written in plain JavaScript.
+ */
+export type Sync<T> = T extends PromiseLike<unknown> ? "a transaction builder must be synchronous: await before document.edit() / update(), not inside it" : T;
+/** `plugin.json`, next to the entry file. Only `name` is required. */
+export interface PluginManifest {
+	name: string;
+	/** Stable identifier (storage prefix, log prefix); derived from the name when absent. */
+	id?: string;
+	version?: string;
+	description?: string;
+	author?: string;
+	homepage?: string;
+	/** Entry file relative to the manifest; `plugin.ts` by default, then `plugin.js`. */
+	entry?: string;
+	/**
+	 * A built, self-contained JavaScript bundle of the plugin, relative to the manifest
+	 * (`"dist/plugin.js"`). When there is one the editor loads **it** and never `entry`:
+	 * one fetch, no TypeScript compiler, no import graph to walk — and the plugin may use
+	 * npm dependencies, which the source path cannot (`bundleModule` refuses a bare
+	 * specifier because it has no resolver).
+	 *
+	 * `entry` stays the source of truth and stays in the manifest: it is what a person
+	 * reads, what `npm run typecheck` checks, and what loads when there is no build. A
+	 * repository that publishes one builds it in CI at the tag it is loaded from — see
+	 * `docs/plugins.md`.
+	 */
+	build?: string;
+	/**
+	 * The plugin's face in Manage Plugins and on its own dialogs: an emoji (`"🗺️"`), a
+	 * `data:image/…` URI, an `https://…` image, or an image file beside the manifest
+	 * (`"icon.svg"`). Anything else is ignored — see `resolveIcon` in `loader.ts`.
+	 */
+	icon?: string;
+	/** The `PLUGIN_API_VERSION` the plugin was written against. */
+	api?: number;
+}
+/** What `activate` may hand back: nothing, a cleanup function, or a Disposable. */
+export type Deactivate = void | (() => void) | Disposable;
+export type PluginActivate = (api: PluginApi) => Deactivate | Promise<Deactivate>;
+/**
+ * The shape of the entry module: `export default function activate(api) {…}`, or
+ * `export default { activate }`, or `export function activate(api) {…}`.
+ */
+export interface PluginModule {
+	activate: PluginActivate;
+}
+/** A manifest `icon` after resolution: a glyph to print, or an image to show. */
+export type PluginIcon = {
+	kind: "text";
+	text: string;
+} | {
+	kind: "image";
+	url: string;
+};
+export interface PluginInfo {
+	/** Manifest id (or slug of the name). */
+	id: string;
+	name: string;
+	/** The spec the plugin was installed from (`builtin:…`, `github:…`, a URL). */
+	source: string;
+	version?: string;
+	/** The manifest's `icon`, resolved; absent when it declared none (or an unusable one). */
+	icon?: PluginIcon;
+}
+export interface PluginApi {
+	readonly apiVersion: number;
+	readonly plugin: PluginInfo;
+	readonly document: DocumentApi;
+	/** The settings dialogs' tables, read-only; `document.update` writes them. */
+	readonly settings: SettingsApi;
+	readonly triggers: TriggersApi;
+	readonly terrain: TerrainApi;
+	readonly tileset: TilesetApi;
+	readonly selection: SelectionApi;
+	/** Cut / Copy / Paste: the clip, its parts, and pasting — what the clipboard layer does. */
+	readonly clipboard: ClipboardApi;
+	/** The file formats behind File ▸ Import / Export: `.trg` and the strings text. */
+	readonly exchange: ExchangeApi;
+	readonly palette: PaletteApi;
+	readonly names: NamesApi;
+	/** StarCraft's `<XX>` text control codes: what they mean, and what a string looks like drawn. */
+	readonly text: TextApi;
+	readonly query: QueryApi;
+	readonly data: DataApi;
+	readonly graphics: GraphicsApi;
+	readonly view: ViewApi;
+	readonly ui: UiApi;
+	readonly menu: MenuApi;
+	readonly contextMenu: ContextMenuApi;
+	readonly hotkeys: HotkeyApi;
+	readonly commands: CommandsApi;
+	readonly events: EventsApi;
+	readonly storage: StorageApi;
+	/** `console.log` with the plugin's name in front. */
+	log(...args: unknown[]): void;
+}
+export interface DocumentInfo {
+	name: string;
+	description: string;
+	width: number;
+	height: number;
+	tileset: TilesetId;
+	/** ERA as stored (the tileset is `era & 7`). */
+	era: number;
+	/** CHK VER: 59 original, 63 hybrid, 205 Brood War, 206 Remastered. */
+	version: number;
+	fileName: string | null;
+	modified: boolean;
+}
+/** What one `document.edit` changed, per list. */
+export interface EditResult {
+	changed: boolean;
+	tiles: number;
+	isom: number;
+	units: number;
+	sprites: number;
+	doodads: number;
+	locations: number;
+	fog: number;
+	notes: string[];
+}
+export type MapFileFormat = "scx" | "scm" | "chk";
+export interface ExportOptions {
+	/** The container: the open file's (else `scx`) — `scx` / `scm` archives, `chk` the bare scenario. */
+	format?: MapFileFormat;
+	/** The file's name; defaults to the open file's, or the scenario name plus the format. */
+	fileName?: string;
+	/**
+	 * Compression, encryption and what is left out: over the options Save last used for this
+	 * map (or its defaults — PKWARE and encryption for a new map, the way it was opened for
+	 * an opened one), so the bytes are what Save would write unless you say otherwise.
+	 */
+	saveOptions?: Partial<Omit<SaveOptions, "format">>;
+}
+/** `document.save` / `saveAs`. */
+export interface SaveDocumentOptions {
+	/** Write a copy: the document keeps its own name, handle and clean state. */
+	copy?: boolean;
+}
+export interface ChangeTilesetOptions {
+	tileset: TilesetId;
+	/** ISOM id of the terrain the map is refilled with; the tileset's default when omitted. */
+	terrainId?: number;
+	/** Keep the tile numbers and change only ERA (what SCMDraft's switch does). */
+	keepTiles?: boolean;
+}
+/**
+ * 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
+ * with backslashes (`staredit\wav\hello.wav`). They are written on Save.
+ */
+export interface ExtrasApi {
+	list(): string[];
+	get(name: string): Uint8Array | null;
+	/** Add or replace a member; marks the map modified. */
+	set(name: string, bytes: Uint8Array): void;
+	/** Remove a member; true when there was one. */
+	remove(name: string): boolean;
+}
+/** What `document.history()` answers. */
+export interface DocumentHistory {
+	/** Label of the entry Undo would take back; null with nothing to undo. */
+	undo: string | null;
+	redo: string | null;
+	undoDepth: number;
+	redoDepth: number;
+}
+/** Scenario ▸ Resize / Crop Map's form. Width and height are clamped to 1…256, the anchor to 0…8. */
+export interface ResizeDocumentOptions {
+	width: number;
+	height: number;
+	/** 3 × 3 grid, row-major: 0 top-left … 4 centre … 8 bottom-right. Default 4. */
+	anchor?: number;
+	/** ISOM id of the terrain for the new area (a `TerrainType.id`); the tileset's default when omitted. */
+	terrainId?: number;
+	/** Pull locations that hang past the new edge back inside; default true. */
+	clampLocations?: boolean;
+}
+/** File ▸ New's form: size, tileset, and the two strings the dialog asks for. */
+export interface NewDocumentOptions {
+	width: number;
+	height: number;
+	tileset: TilesetId;
+	/** `Untitled Scenario` when omitted. */
+	name?: string;
+	description?: string;
+	/** ISOM id of the terrain to fill with; the tileset's default ground when omitted. */
+	terrainId?: number;
+}
+export interface DocumentApi {
+	isOpen(): boolean;
+	info(): DocumentInfo | null;
+	/**
+	 * The live scenario, for reading. Writing to it directly bypasses undo, dirty
+	 * tracking and repaints — use `edit`.
+	 */
+	scenario(): Scenario | null;
+	/**
+	 * Run `build` against a transaction and record what it did as one undo entry.
+	 * Operations apply as they are called, so later ones see earlier ones' results.
+	 * Returns an all-zero result with `changed: false` when no map is open.
+	 *
+	 * `build` is synchronous — see `Sync`. Await what you need (graphics, a pick, a
+	 * fetch) before the call, then write in one go.
+	 */
+	edit<R>(label: string, build: (tx: EditTransaction) => Sync<R>): EditResult;
+	/**
+	 * The second kind of write: the tables and settings that live outside the undo model
+	 * — triggers, the string table, switch names, the scenario's own properties — as one
+	 * transaction, the way a settings dialog's OK applies its whole form at once.
+	 * Operations apply as they are called; the commit marks the map modified and bumps
+	 * what the chrome reads. There is no undo entry: keep your own if you need one.
+	 * `build` is synchronous, as `edit`'s is.
+	 */
+	update<R>(label: string, build: (tx: UpdateTransaction) => Sync<R>): UpdateResult;
+	undo(): string | null;
+	redo(): string | null;
+	/** The undo and redo stacks' tops — the labels the Edit menu shows — and their depths, without moving anything. */
+	history(): DocumentHistory;
+	/**
+	 * Open a map file (`.scx` / `.scm` / `.chk`) in place of the current one, the way
+	 * File ▸ Open does: when the open map has unsaved changes and Preferences say to ask,
+	 * the Close Scenario dialog comes first and the user may cancel. Resolves true once
+	 * the file is the open document, false when the user kept the current map or the
+	 * file could not be read (the status bar says why).
+	 */
+	open(file: File | Blob | Uint8Array, fileName?: string): Promise<boolean>;
+	/**
+	 * A blank map in place of the current one, the way File ▸ New makes one: flat ground
+	 * of the tileset's default terrain (or `terrainId`), an ISOM lattice to match, every
+	 * section a fresh map needs. Goes through the same unsaved-changes gate as `open`.
+	 * Resolves true once the new map is the open document, false when the user kept the
+	 * current one.
+	 */
+	create(options: NewDocumentOptions): Promise<boolean>;
+	/**
+	 * The open map as a file, as Save would write it — the remembered save options, the
+	 * archive extras included — unless `saveOptions` says otherwise. Null when no map is open.
+	 */
+	export(options?: ExportOptions): Promise<File | null>;
+	/**
+	 * File ▸ Save: write the map back where it came from with the options last confirmed
+	 * for it — into the file when the browser gave a handle, else through the browser's
+	 * save dialog or as a download; a map with no file yet goes through the Save dialog.
+	 * Resolves true once written, false when the user dismissed a dialog or the write failed
+	 * (the status bar and a toast say so).
+	 */
+	save(options?: SaveDocumentOptions): Promise<boolean>;
+	/** File ▸ Save As (or Save Copy As with `copy`): the Save dialog, resolving as `save` does. */
+	saveAs(options?: SaveDocumentOptions): Promise<boolean>;
+	/**
+	 * File ▸ Close: through the same unsaved-changes gate as `open`. Resolves true once the
+	 * map is closed (`isOpen()` is then false), false when the user kept it.
+	 */
+	close(): Promise<boolean>;
+	/**
+	 * A picture of the map as File ▸ Export ▸ Image draws it, as a PNG. `pixelsPerTile`
+	 * is the one dial (32 is the game's art 1:1, 1 is a minimap); the other options
+	 * default as the dialog's do. Needs the tileset graphics — without them, or without
+	 * a map, null.
+	 */
+	renderImage(options?: Partial<MapImageOptions>): Promise<Blob | 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`
+	 * (a 3 × 3 grid, row-major, 4 = centre, the default); the new ground is `terrainId`
+	 * (the tileset's default when omitted); objects outside the new bounds are dropped,
+	 * locations clamped unless `clampLocations` is false. Null with no map.
+	 */
+	resize(options: ResizeDocumentOptions): ResizeResult | null;
+	/**
+	 * Scenario ▸ Map Properties ▸ Tileset: change ERA and lay the terrain again with the
+	 * new tileset's terrain (tile numbers do not carry across tilesets; the doodads go with
+	 * them, everything else stays). Waits for the new graphics so the fill uses real tiles.
+	 * Like `resize`, a transaction outside the undo model. Null with no map.
+	 */
+	changeTileset(options: ChangeTilesetOptions): Promise<ChangeTilesetResult | null>;
+	readonly extras: ExtrasApi;
+	readonly sections: SectionsApi;
+}
+/** What a raw section edit reported: the parser's remarks about the file it produced. */
+export interface RawEditResult {
+	/** Warnings from parsing the edited file (a truncated section, no usable DIM, …); empty when it read cleanly. */
+	warnings: string[];
+}
+/**
+ * The scenario file at the byte level: every section occurrence in the order Save would
+ * write them, with the bytes it would write — unsaved edits already encoded — and raw
+ * edits to any of them.
+ *
+ * A raw edit is a different kind of transaction from `document.edit`: the edited file is
+ * parsed again from scratch and installed as the open document, so the change reaches
+ * every part of the editor whether or not it models the section — and, as with Resize,
+ * the undo history is dropped and every selection cleared. The map is marked modified
+ * and the `"document"` event fires. Keep your own undo if you need one.
+ *
+ * Indices are positions in `list()` and shift when a section is inserted or removed
+ * before them; take a fresh `list()` after every edit.
+ */
+export interface SectionsApi {
+	/** Every occurrence in file order; empty without a map. */
+	list(): SectionInfo[];
+	/** A copy of one occurrence's payload. */
+	bytes(index: number): Uint8Array;
+	/**
+	 * The bytes the game acts on for a name — repeated occurrences combined the way the
+	 * game combines them (`SectionKnowledge.mode`) — or null when the file has none.
+	 */
+	combined(name: string): Uint8Array | null;
+	/** The whole CHK as Save would write it (the archive extras are `document.extras`). */
+	file(): Uint8Array;
+	/** What the editor knows about a section name, sized for the open map; null for an unknown name. */
+	spec(name: string): SectionKnowledge | null;
+	/** Every section the editor knows, sized for the open map. */
+	known(): SectionKnowledge[];
+	/** Replace one occurrence's payload. */
+	write(index: number, bytes: Uint8Array): RawEditResult;
+	/** Rename one occurrence (four characters; shorter names are padded with spaces). */
+	rename(index: number, name: string): RawEditResult;
+	/** Insert a section before `index` (`list().length` appends). */
+	insert(index: number, name: string, bytes: Uint8Array): RawEditResult;
+	remove(index: number): RawEditResult;
+	/** Move the occurrence at `from` so that it sits at `to`. */
+	move(from: number, to: number): RawEditResult;
+	/** Replace the whole CHK, the way File ▸ Open reads one. */
+	replaceFile(bytes: Uint8Array): RawEditResult;
+	/**
+	 * Bytes after the last chunk the reader could parse — what follows a chunk header with
+	 * a negative length, say. Save writes them back as they are; a `replaceFile` without
+	 * them drops them. Null when the file ends cleanly.
+	 */
+	trailing(): Uint8Array | null;
+	/** The sections a file of the open map's revision must carry to load, as Check Map tests them (`STRx` in place of `STR ` on a Remastered file). */
+	required(): string[];
+	/**
+	 * The bytes File ▸ New would write for a section on a map of this size, tileset and
+	 * revision — StarEdit's defaults for a settings table, the fixed VCOD, an empty list,
+	 * null terrain. Null for a section the editor cannot produce: one it does not model,
+	 * or an optional one a new map has no value for (CRGB, SWNM).
+	 */
+	defaults(name: string): Uint8Array | null;
+	/**
+	 * Re-encode sections from the editor's model, the way Save writes a dirty one, and
+	 * install the result like any other raw edit. This is what turns a protected file back
+	 * into a plain one: repeated occurrences collapse into one, a truncated or oversized
+	 * section comes back at the size the model encodes to, a string table whose offsets
+	 * point nowhere is rewritten with every string the editor could read. Names the editor
+	 * does not model, and modelled ones whose model is absent (no ISOM, no settings table),
+	 * are left as they are and missing from `rebuilt`; omit `names` for every modelled
+	 * section the map has a model for.
+	 */
+	rebuild(names?: string[]): RebuildResult;
+}
+/** What `tx.rebuildIsom` did. */
+export interface IsomRebuildResult {
+	/** The map had no usable ISOM, so one was created. */
+	created: boolean;
+	/** Lattice values that changed (every one of a created section). */
+	changed: number;
+	/** Diamonds the rebuild resolved from the tiles. */
+	diamonds: number;
+	/** Diamonds it had to guess — under doodads or off the edge. */
+	unresolved: number;
+}
+/** Cells for the bulk terrain operations: a tile rect, or cell indices (`y * width + x`). */
+export type Cells = Rect | Iterable<number>;
+export interface EditTransaction {
+	readonly scenario: Scenario;
+	readonly width: number;
+	readonly height: number;
+	/** MTXM (what the game draws) at a cell. */
+	tileAt(x: number, y: number): number;
+	/** TILE (the ground without doodads) at a cell. */
+	groundAt(x: number, y: number): number;
+	/** One tile into both sections. */
+	setTile(x: number, y: number, id: number): void;
+	/** Many tiles into both sections; returns how many changed. */
+	setTiles(cells: Cells, id: number): number;
+	/**
+	 * The Rect brush: flat left/right pairs by column parity, one random variation per
+	 * pair (`variation` pins it). Needs the tileset graphics; returns tiles changed.
+	 */
+	stampTerrain(cells: Cells, terrainId: number, variation?: number): number;
+	/** Lay terrain the way a new map is laid over `rect`, ISOM lattice included when the map has one. */
+	fillFlat(rect: Rect, terrainId: number): number;
+	/**
+	 * The isometric brush on one diamond: sets its ISOM value and regenerates the tiles
+	 * around it, cliffs and shores included. Needs ISOM and the tileset; returns whether
+	 * the terrain could be painted there.
+	 */
+	paintIsom(d: Diamond, terrainId: number, extent?: number): boolean;
+	/**
+	 * Reconstruct the ISOM section from the tiles — for a map that arrived without one, or
+	 * whose lattice no longer matches after Rect / Tile edits: exact for terrain that was
+	 * laid down isometrically, a best guess under doodads and for hand-placed tiles. A
+	 * missing or wrongly sized ISOM is created (undo removes it again); an existing one gets
+	 * only the diamonds that differ. Needs the tileset graphics; null without them.
+	 */
+	rebuildIsom(): IsomRebuildResult | null;
+	/** A StarEdit-style unit record (fresh serial, valid/used masks) centred on map pixels. */
+	makeUnit(unitId: number, owner: number, x: number, y: number): UnitRecord;
+	addUnits(records: UnitRecord[]): number[];
+	removeUnits(indices: number[]): number;
+	updateUnits(indices: number[], patch: (u: UnitRecord) => Partial<UnitRecord>): number;
+	/**
+	 * A unit the way the Units palette places one: a building snaps its placement box to
+	 * the tile grid (when the palette's *Snap to grid* is on), anything else lands where
+	 * you say, and nothing leaves the map. No placement checks — ask `canPlaceUnit` first
+	 * if you want them. Returns the record's index.
+	 */
+	placeUnit(unitId: number, owner: number, x: number, y: number): number;
+	/** Whether the Units palette's placement checks, with its current options, allow a unit of this type centred there. */
+	canPlaceUnit(unitId: number, x: number, y: number): boolean;
+	makeSprite(kind: SpriteKind, id: number, owner: number, x: number, y: number, opts?: {
+		flipped?: boolean;
+		disabled?: boolean;
+	}): SpriteRecord;
+	addSprites(records: SpriteRecord[]): number[];
+	removeSprites(indices: number[]): number;
+	/** `makeSprite` + `addSprites` in one, kept on the map; returns the record's index. */
+	placeSprite(kind: SpriteKind, id: number, owner: number, x: number, y: number, opts?: {
+		flipped?: boolean;
+		disabled?: boolean;
+	}): number;
+	/** Stamp a doodad (a `dddata.bin` id) at a tile; returns its record index, or -1 when unknown or off the map. */
+	placeDoodad(doodadId: number, tx: number, ty: number, owner?: number): number;
+	removeDoodads(indices: number[]): number;
+	/** A location in the lowest free slot (pixel bounds); returns the slot, or -1 when the table is full. */
+	addLocation(bounds: Bounds, name?: string, elevationFlags?: number): number;
+	editLocation(index: number, patch: LocationPatch): boolean;
+	removeLocations(indices: number[]): number;
+	/** Set (`"fog"`) or clear the `players` bits (bit n = player n + 1) over cells; creates MASK on first use. */
+	setFog(cells: Cells, players: number, mode: FogMode): number;
+	/**
+	 * Tools ▸ Replace Terrain: every tile matching `from` (a flat terrain by ISOM id, or
+	 * one exact tile) becomes `to`, over `rect` or the whole map; pairs are laid as the
+	 * Rect brush lays them. Returns tiles changed. Terrain picks need the graphics.
+	 */
+	replaceTerrain(from: TerrainPick, to: TerrainPick, rect?: Rect): number;
+	/**
+	 * The bucket fill: the 4-connected area around (x, y) of the same terrain type (`match:
+	 * "terrain"`, the Rect fill) or the same exact tile (`"tile"`), laid with `terrainId`
+	 * as the Rect brush would, or set to `tileId`. Returns tiles changed.
+	 */
+	fillArea(x: number, y: number, fill: {
+		terrainId: number;
+	} | {
+		tileId: number;
+	}, match?: "terrain" | "tile"): number;
+	/**
+	 * The Blend brush: `id` goes on the cell beside the anchor tile on `side`
+	 * (`terrain.blendCandidates` ranks what fits). Returns whether the cell was on the map.
+	 */
+	placeBlend(x: number, y: number, side: Side, id: number): boolean;
+	/**
+	 * What StarEdit does after an isometric edit: regenerate every tile from the ISOM
+	 * lattice (the reverse of `rebuildIsom`). Needs ISOM and the graphics; returns tiles
+	 * changed, or null without them.
+	 */
+	tilesFromIsom(): number | null;
+	/**
+	 * The cells and their images under the symmetry mode (Tools ▸ Symmetry…), each once —
+	 * what the built-in brushes paint over. With the mode off, the cells as given.
+	 */
+	mirror(cells: Cells): number[];
+	/** A map pixel and its images under the symmetry mode, the original first. */
+	mirrorPoint(px: number, py: number): {
+		x: number;
+		y: number;
+	}[];
+	/** Shift units by a pixel delta; buildings re-snap to the grid when `snap` (the palette's option when omitted). Returns records changed. */
+	moveUnits(indices: number[], dx: number, dy: number, snap?: boolean): number;
+	/**
+	 * Tools ▸ Auto-place Start Locations: one per player on a ring or in the corners, each
+	 * moved to the nearest spot the placement checks accept; `replace` removes the existing
+	 * ones first. Players count from 1.
+	 */
+	placeStartLocations(options: {
+		players: number;
+		layout?: StartLayout;
+		margin?: number;
+		replace?: boolean;
+	}): StartPlacementResult;
+	updateSprites(indices: number[], patch: (r: SpriteRecord) => Partial<SpriteRecord>): number;
+	/** Shift sprites by a pixel delta, clamped to the map. Returns records changed. */
+	moveSprites(indices: number[], dx: number, dy: number): number;
+	/** Change a doodad's owner or disabled flag (its tiles stay). Returns records changed. */
+	updateDoodads(indices: number[], patch: {
+		owner?: number;
+		disabled?: number;
+	}): number;
+	/** Put Anywhere (slot 63) back to the whole map; returns whether it had to move. */
+	restoreAnywhere(): boolean;
+	/** Flip every tile's fog bit for `players`; returns tiles changed. */
+	invertFog(players: number): number;
+	/** Copy one player's fog (0-based) onto the players in the `to` bit mask (bit n = player n + 1); returns tiles changed. */
+	copyFog(from: number, to: number): number;
+	/** Fog or clear the connected area around (x, y) that shares `player`'s fog state, for `players`; returns tiles changed. */
+	floodFog(x: number, y: number, player: number, players: number, mode: FogMode): number;
+	/** A line for the status bar, appended to the label. */
+	note(text: string): void;
+}
+/**
+ * What one `document.update` changed: every section it marked dirty, in the order the
+ * operations touched them, and `changed` false when they were all no-ops.
+ */
+export interface UpdateResult {
+	changed: boolean;
+	sections: string[];
+	notes: string[];
+}
+/** TRIG or MBRF as a list. Operations apply as they are called, like `document.edit`'s. */
+export interface TriggerListUpdate {
+	/** The list as it stands, cloned. */
+	list(): TriggerRecord[];
+	count(): number;
+	/** Replace the whole list. */
+	set(list: TriggerRecord[]): void;
+	/** Insert one (at the end without `at`); returns its index. */
+	add(trigger: TriggerRecord, at?: number): number;
+	/** Replace one record; false when there is none at `index`. */
+	replace(index: number, trigger: TriggerRecord): boolean;
+	remove(indices: number[]): number;
+	move(from: number, to: number): boolean;
+	/**
+	 * Parse the text format (`triggers.text.print`'s inverse) and append the result, or
+	 * replace the list with `replace: true`. Strings the text names are interned as it
+	 * parses. Throws with the line number when the text does not parse.
+	 */
+	fromText(source: string, options?: {
+		replace?: boolean;
+	}): number;
+}
+/**
+ * The string table. Nothing is ever renumbered: `set` overwrites a slot (every record
+ * pointing at it sees the new text) and `intern` appends rather than reusing a slot
+ * something else may share.
+ */
+export interface StringsUpdate {
+	list(): (string | null)[];
+	/** The index of `text`: an identical entry when there is one, else a new one. 0 for `""`. */
+	intern(text: string): number;
+	/** Overwrite one slot. */
+	set(index: number, text: string): void;
+	/** Install a whole table; unreferenced trailing blanks are dropped, other indices keep their place. */
+	apply(list: (string | null)[]): void;
+	/**
+	 * File ▸ Import ▸ Strings: `index<TAB>text` lines (`exchange.formatStrings` writes
+	 * them) set in place, indices past the end appended. Returns how many were replaced and added.
+	 */
+	import(text: string): {
+		replaced: number;
+		added: number;
+	};
+}
+export interface SwitchesUpdate {
+	names(): string[];
+	/** Name a switch (0-based); `""` clears the name. Creates SWNM on the first one. */
+	setName(index: number, name: string): void;
+}
+/**
+ * The second kind of write (see `document.update`): the tables and settings the editor's
+ * own dialogs edit. Operations apply to the scenario as they are called — a string
+ * interned on one line is there for the trigger added on the next — and the commit at
+ * the end marks the map modified and tells the chrome to re-read.
+ */
+export interface UpdateTransaction {
+	readonly scenario: Scenario;
+	/** TRIG. */
+	readonly triggers: TriggerListUpdate;
+	/** MBRF, the mission briefing's own list of the same records. */
+	readonly briefing: TriggerListUpdate;
+	readonly strings: StringsUpdate;
+	/** SWNM. */
+	readonly switches: SwitchesUpdate;
+	/** SPRP: the scenario's name and description (`""` restores the file-name default). */
+	properties(patch: {
+		name?: string;
+		description?: string;
+	}): void;
+	/** OWNR / SIDE / COLR / CRGB / FORC: the Player Settings and Player Colors dialogs. */
+	readonly players: PlayersUpdate;
+	/** FORC: the Force Settings dialog. */
+	readonly forces: ForcesUpdate;
+	/** UNIS / UNIx and PUNI: the Unit Settings dialog. */
+	readonly unitTypes: UnitTypesUpdate;
+	/** UPGS / UPGx and UPGR / PUPx: the Upgrade Settings dialog. */
+	readonly upgrades: UpgradesUpdate;
+	/** TECS / TECx and PTEC / PTEx: the Technology Settings dialog. */
+	readonly techs: TechsUpdate;
+	/** WAV and the archive's sound files: the Sound Editor. */
+	readonly sounds: SoundsUpdate;
+	/** UPRP / UPUS: the Create Unit with Properties slots (Triggers ▸ Unit Properties Slots…). */
+	readonly cuwp: CuwpUpdate;
+	/** Scenario ▸ Map Revision: VER / TYPE and, moving to or from Remastered, the string table's width. */
+	setVersion(version: MapVersion, extendedStrings?: boolean): void;
+	/** A line for the status bar, appended to the label. */
+	note(text: string): void;
+}
+export interface PlayersUpdate {
+	/** All 12 slots, 0-based, with the effective colour and force. */
+	list(): PlayerSlotView[];
+	/** Patch one slot; colours and forces apply to the eight playable slots only. */
+	set(slot: number, patch: PlayerPatch): boolean;
+}
+export interface ForcesUpdate {
+	list(): ForceView[];
+	set(force: number, patch: ForcePatch): boolean;
+}
+export interface UnitTypesUpdate {
+	/** The effective row for a units.dat id — the dat's numbers where the type is on "use default". */
+	get(unitId: number): UnitTypeView;
+	/**
+	 * Patch one type. Setting any number turns "use default" off for it (seeding the untouched
+	 * columns from the dat, as the dialog does); `useDefault: true` puts it back. Hit points are
+	 * whole points. `name` is the custom name (`""` restores the default); `available` edits PUNI.
+	 */
+	set(unitId: number, patch: UnitTypePatch): boolean;
+}
+export interface UpgradesUpdate {
+	get(upgradeId: number): UpgradeView;
+	set(upgradeId: number, patch: UpgradePatch): boolean;
+}
+export interface TechsUpdate {
+	get(techId: number): TechView;
+	set(techId: number, patch: TechPatch): boolean;
+}
+export interface SoundsUpdate {
+	/** The 512 WAV slots in use, joined with the archive (`present` says whether the file is there). */
+	list(): SoundRow[];
+	/**
+	 * Put `path` (`staredit\wav\name.wav`, or just `name.wav`) in the first free slot — the
+	 * existing slot when it is already listed — and, with `bytes`, store the file in the archive.
+	 * Returns the slot, or -1 when all 512 are taken.
+	 */
+	add(path: string, bytes?: Uint8Array): number;
+	/** Clear a slot; with `deleteFile`, remove the archive member too. */
+	remove(slot: number, deleteFile?: boolean): boolean;
+}
+/**
+ * The 64 Create Unit with Properties slots. A slot is addressed 0-based here; the action
+ * that uses one stores the number 1-based (`target` = slot + 1), as `CuwpSlotView.index`
+ * + 1. A view's field is `null` where the created units keep the type's default.
+ */
+export interface CuwpUpdate {
+	list(): CuwpSlotView[];
+	get(index: number): CuwpSlotView | null;
+	/**
+	 * Patch one slot: a number sets the field and its "applied" bit, `null` clears the bit;
+	 * a boolean forces a special state, `null` leaves it to the unit. `used` is StarEdit's
+	 * "in use" tick, on by itself once the slot sets anything.
+	 */
+	set(index: number, patch: CuwpSlotPatch, used?: boolean): boolean;
+	/** Back to an empty, unticked slot. */
+	clear(index: number): boolean;
+}
+/**
+ * What the settings dialogs show, read without a transaction: the same views
+ * `document.update`'s `tx.players` … `tx.techs` hand out. Every list is empty and every
+ * single read null when no map is open.
+ */
+export interface SettingsApi {
+	players(): PlayerSlotView[];
+	player(slot: number): PlayerSlotView | null;
+	forces(): ForceView[];
+	unitType(unitId: number): UnitTypeView | null;
+	/** Every type with a name, in id order. */
+	unitTypes(): UnitTypeView[];
+	upgrade(upgradeId: number): UpgradeView | null;
+	upgrades(): UpgradeView[];
+	tech(techId: number): TechView | null;
+	techs(): TechView[];
+	sounds(): SoundRow[];
+	/** Whether a player (0-based) may build a unit type — PUNI's per-player byte resolved against its global default. */
+	unitAvailable(player: number, unitId: number): boolean;
+	/** The Create Unit with Properties slots, 0-based, with how many actions name each. */
+	cuwpSlots(): CuwpSlotView[];
+	cuwpSlot(index: number): CuwpSlotView | null;
+	version(): MapVersionView | null;
+}
+/**
+ * What each condition and action type takes: the argument list in the order StarEdit's
+ * TrigEdit shows it, each naming the record field it lives in and the kind of value it
+ * is (a player group, a unit id, a location, a comparison, …). Everything that displays
+ * or edits a trigger reads this table, the editor's own dialogs included.
+ */
+export interface TriggerDefsApi {
+	conditions(): ConditionDef[];
+	condition(type: number): ConditionDef | undefined;
+	actions(briefing?: boolean): ActionDef[];
+	action(type: number, briefing?: boolean): ActionDef | undefined;
+	/** The values an enumerated argument kind can take, with their labels. */
+	choices(kind: ArgKind): Choice[];
+	choiceLabel(kind: ArgKind, value: number): string | undefined;
+	/** The value behind a label or one of its aliases, for parsing. */
+	choiceValue(kind: ArgKind, text: string): number | undefined;
+}
+/** Printing and parsing the text trigger format (File ▸ Import / Export ▸ Triggers). */
+export interface TriggerTextApi {
+	print(triggers: TriggerRecord[], options?: {
+		briefing?: boolean;
+	}): string;
+	/**
+	 * Parse text into records, resolving names against the open map (and interning the
+	 * strings it mentions). Throws a `TriggerTextError` carrying the line on bad input.
+	 */
+	parse(source: string, options?: {
+		briefing?: boolean;
+	}): TextTrigger[];
+	/** One trigger as its `Trigger(…)` block. */
+	one(trigger: TriggerRecord, options?: {
+		briefing?: boolean;
+	}): string;
+}
+/**
+ * Reading triggers, and the pure helpers that make them presentable. Writing goes
+ * through `document.update`.
+ */
+export interface TriggersApi {
+	/** TRIG, cloned. */
+	list(): TriggerRecord[];
+	/** MBRF, cloned. */
+	briefing(): TriggerRecord[];
+	/** SWNM as names, StarEdit's `Switch N` where there is none. */
+	switchNames(): string[];
+	/** How many conditions and actions mention each switch. */
+	switchUsage(): number[];
+	/** The name context the text format resolves against: the map's locations, units, switches and strings. */
+	names(): TriggerNames;
+	readonly defs: TriggerDefsApi;
+	readonly text: TriggerTextApi;
+	/** An empty trigger owned by the given player groups (All Players by default). */
+	newTrigger(players?: number[]): TriggerRecord;
+	/** A condition of a type, with StarEdit's defaults for its arguments. */
+	newCondition(type: number): ConditionRecord;
+	newAction(type: number, briefing?: boolean): ActionRecord;
+	isPreserved(trigger: TriggerRecord): boolean;
+	setPreserved(trigger: TriggerRecord, on: boolean): TriggerRecord;
+	/** The indices of the triggers any of these player groups own. */
+	triggersFor(list: TriggerRecord[], groups: number[]): number[];
+	/** The three lines the trigger list shows: players, conditions, actions. */
+	summarize(trigger: TriggerRecord, briefing?: boolean): {
+		players: string;
+		conditions: string;
+		actions: string;
+	};
+	/** A trigger's `Comment` action text, when it has one. */
+	comment(trigger: TriggerRecord): string | null;
+	/**
+	 * Tell the editor that a run of the trigger list is generated by this plugin. The
+	 * Trigger Editor badges those rows, locks them and offers the plugin's own editor in
+	 * place of the form; the Text Trigger Editor fences them in comments; Import Triggers
+	 * says what a replace would remove. The claim lives until `remove()` or the plugin's
+	 * deactivation; call `refresh()` after a rebuild so the editors ask `locate` again.
+	 */
+	claim(spec: TriggerClaimSpec): TriggerClaimHandle;
+}
+/**
+ * A run of triggers a plugin generates and owns. It is found by *content*: the
+ * editors work on copies of the list with their own unsaved inserts and removals, so
+ * `locate` is asked with whatever list an editor holds and answers where the run is
+ * in it — by a hash of the records, say — or null when the records are not there.
+ */
+export interface TriggerClaimSpec {
+	/** What generated the run, in words, as a sentence would use it: `"the trigger script"`. */
+	label: string;
+	/** The word on the badge the trigger list shows on each row; the plugin's id by default. */
+	badge?: string;
+	/** Where the run sits in `list`, or null when it is not there (edited by hand, or gone). */
+	locate(list: TriggerRecord[]): {
+		start: number;
+		count: number;
+	} | null;
+	/** A sentence about one trigger of the run (its index in `list`), shown in place of the editor's form. */
+	describe?(index: number, list: TriggerRecord[]): string;
+	/** Open the plugin's own editor on that trigger — the button under the sentence. */
+	open?(index: number, list: TriggerRecord[]): void;
+	/** That button's label; `Open <plugin name>` by default. */
+	openLabel?: string;
+}
+export interface TriggerClaimHandle extends Disposable {
+	/** The editors ask `locate` again (after a rebuild, or when the run moved). */
+	refresh(): void;
+	remove(): void;
+}
+/** A start location on the map: the record's index, its owner and where it sits. */
+export interface StartLocation {
+	index: number;
+	owner: number;
+	/** Map pixels. */
+	x: number;
+	y: number;
+	/** The tile it is centred on. */
+	tx: number;
+	ty: number;
+}
+/**
+ * Reading the open map: what is under a point, what lies in a rectangle, and the
+ * editor's own analyses — Check Map's issues, Tools ▸ Statistics, the Ctrl+F search and
+ * the string usage map the String Editor is built on.
+ *
+ * Everything here is a read: nothing changes the map, and nothing throws without one
+ * (an empty list, or null).
+ */
+export interface QueryApi {
+	/** The topmost unit whose sprite box covers a map pixel, or -1. */
+	unitAt(px: number, py: number): number;
+	/** Every unit whose centre lies in a tile rect. */
+	unitsIn(rect: Rect): number[];
+	/** Units owned by a player (0-based). */
+	unitsOf(owner: number): number[];
+	spriteAt(px: number, py: number): number;
+	spritesIn(rect: Rect): number[];
+	/** The doodad covering a tile, or -1. */
+	doodadAt(tx: number, ty: number): number;
+	/** The smallest location covering a map pixel (never Anywhere), or -1. */
+	locationAt(px: number, py: number): number;
+	/** Locations wholly inside a tile rect (never Anywhere). */
+	locationsIn(rect: Rect): number[];
+	/** The map's start locations, by player. */
+	startLocations(): StartLocation[];
+	/** Whether a unit type may be placed centred there, and what stops it; null with no map. */
+	placement(unitId: number, x: number, y: number): PlacementVerdict | null;
+	/** The MASK bits at a tile: bit n set = player n + 1 starts fogged there (every bit when the map has no MASK). */
+	fogAt(tx: number, ty: number): number;
+	/** The string table as it stands (index 0 is nothing); empty with no map. */
+	strings(): (string | null)[];
+	/** Check Map: every issue the editor knows how to spot, with a `target` to go to. */
+	validate(): Issue[];
+	/** Tools ▸ Statistics: tile, unit, resource and player counts. Null without a map. */
+	statistics(): MapStatistics | null;
+	/** The Ctrl+F search over units, locations, sprites, strings and triggers. */
+	find(options: FindOptions): FindResult[];
+	/** Every record that refers to each string index. */
+	stringUsage(): Map<number, StringUsage[]>;
+	/** String slots nothing refers to. */
+	unusedStrings(): number[];
+}
+/** Where `view.goTo` should take the user. Issues from `query.validate` carry one. */
+export type GoTo = {
+	kind: "tile";
+	x: number;
+	y: number;
+} | {
+	kind: "unit";
+	index: number;
+} | {
+	kind: "sprite";
+	index: number;
+} | {
+	kind: "location";
+	index: number;
+};
+/**
+ * The map view: where the viewport is looking, how far in, and what it draws over the
+ * terrain. A plugin that finds something needs this to show the user where it is.
+ */
+export interface ViewApi {
+	zoom(): number;
+	/** 0.25 … 8, as the zoom control's steps. */
+	setZoom(zoom: number): void;
+	/** The tiles on screen. */
+	visible(): Rect;
+	/** Scroll so a tile is in the middle of the viewport. */
+	center(x: number, y: number): void;
+	/** Scroll to an object (and select it, for a unit, sprite or location). */
+	goTo(target: GoTo): void;
+	/** The tile under the pointer, as the status bar shows it. */
+	cursorTile(): {
+		x: number;
+		y: number;
+	};
+	/** The View menu's ticks: grid, locations, units, sprites, doodads, fog, … */
+	flags(): ViewFlags;
+	setFlags(patch: Partial<ViewFlags>): void;
+	/** Grid spacing in map pixels (32 = one tile). */
+	gridSize(): number;
+	setGridSize(size: 8 | 16 | 32 | 64 | 128): void;
+}
+export interface CommandSpec {
+	/**
+	 * The command's id. One without a dot is namespaced under the plugin
+	 * (`"paint" → "paint-plugin.paint"`); one with a dot is taken as it is, so a plugin
+	 * can offer a stable name others call.
+	 */
+	id: string;
+	/** What a menu or a command list should call it. */
+	title: string;
+	enabled?: () => boolean;
+	run: (...args: unknown[]) => unknown;
+}
+export interface CommandInfo {
+	id: string;
+	title: string;
+	pluginId: string;
+	enabled: boolean;
+}
+/**
+ * Named things a plugin can do, so a menu item, a hotkey, a context entry and another
+ * plugin all reach the same one. `menu.add`, `contextMenu.add` and `hotkeys.add` take a
+ * `command` id in place of a `run`.
+ */
+export interface CommandsApi {
+	register(spec: CommandSpec): Disposable;
+	/** Run one, whoever registered it; the command's own return value, or undefined when there is no such command. */
+	run(id: string, ...args: unknown[]): unknown;
+	has(id: string): boolean;
+	/** Every command registered by every plugin. */
+	list(): CommandInfo[];
+}
+/** A picture the editor already has: the canvas it draws from, and its size in pixels. */
+export interface PluginImage {
+	image: HTMLCanvasElement;
+	width: number;
+	height: number;
+}
+/**
+ * The pictures the viewport draws, for a plugin's own lists and previews: the same
+ * cached canvases, so asking for one costs nothing after the first time. Everything is
+ * null when the graphics it needs were never extracted — a plugin shows a name instead.
+ */
+export interface GraphicsApi {
+	/** Whether the tileset graphics and the unit tables are in memory. */
+	ready(): {
+		tileset: boolean;
+		units: boolean;
+	};
+	/** Fetch both; resolves with what is available afterwards. */
+	load(): Promise<{
+		tileset: boolean;
+		units: boolean;
+	}>;
+	/** A unit type in its editor pose, in a player's colours (`owner` 0 by default). */
+	unitImage(unitId: number, options?: {
+		owner?: number;
+	}): PluginImage | null;
+	/** A THG2 sprite: a sprites.dat image for `"pure"`, a unit for `"unit"`. */
+	spriteImage(kind: SpriteKind, id: number, options?: {
+		owner?: number;
+		flipped?: boolean;
+	}): PluginImage | null;
+	/** One 32 × 32 megatile of the open map's tileset. */
+	tileImage(tileId: number): PluginImage | null;
+	/** A doodad drawn from its own tiles. */
+	doodadImage(doodadId: number): PluginImage | null;
+	/**
+	 * Part of the map as File ▸ Export ▸ Image draws it — the same render, cropped to a
+	 * tile rect. Everything it needs is loaded first; null without a map or a canvas.
+	 */
+	renderRect(rect: Rect, options?: Partial<MapImageOptions>): Promise<Blob | null>;
+	/** The colour a player's units are drawn in, `#rrggbb`. */
+	playerColor(owner: number): string;
+	/**
+	 * Start fetching the GRPs a unit type needs, and say whether they are already in
+	 * memory. Graphics load lazily, so the first `unitImage` for a type is often null —
+	 * ask for it here, redraw on `onImageLoaded`, and the list fills in.
+	 */
+	requestUnit(unitId: number): boolean;
+	requestSprite(kind: SpriteKind, id: number): boolean;
+	/** A GRP finished loading: anything drawn from one may look different now. */
+	onImageLoaded(listener: () => void): Disposable;
+}
+/**
+ * The game's own tables, as the editor decoded them: `units.dat` and its neighbours.
+ * `names` gives the labels, this gives the numbers — hit points, costs, build times,
+ * weapons, flags, the sprite and image each unit draws through.
+ *
+ * Everything is null until the tables are loaded (`load`), and stays null when the game
+ * data was never extracted.
+ */
+export interface DataApi {
+	ready(): boolean;
+	load(): Promise<boolean>;
+	units(): UnitsDat | null;
+	weapons(): WeaponsDat | null;
+	upgrades(): UpgradesDat | null;
+	techs(): TechdataDat | null;
+	sprites(): SpritesDat | null;
+	flingy(): FlingyDat | null;
+	images(): ImagesDat | null;
+	/** Which race a unit type belongs to, from its flags. */
+	race(unitId: number): Race;
+	/** The GRP path an image id draws from, relative to `unit\`. */
+	imagePath(imageId: number): string | null;
+}
+export interface ActiveBrush {
+	mode: TerrainMode;
+	/** The Rect / isometric brush's terrain id. */
+	terrain: number;
+	/** The Tile brush's MTXM id. */
+	tile: number;
+	brushSize: number;
+	/** The Rect brush's variation slot, or -1 for a random one per pair. */
+	variation: number;
+}
+export interface TerrainApi {
+	/** Paintable flat terrains of the open map's tileset (empty without the graphics). */
+	types(): TerrainType[];
+	/** Terrain ids the isometric brush can paint on this tileset. */
+	isomTypes(): number[];
+	/** Whether the open map carries an ISOM section the isometric brush can work on. */
+	hasIsom(): boolean;
+	/**
+	 * How well the ISOM describes the tiles — `rects` measured, `mismatched` among them,
+	 * and `stale` when the share is past what the palette warns at — or null when the map
+	 * has no ISOM (`hasIsom`) or no map is open. Waits for the tileset graphics to load
+	 * and rejects when they are missing.
+	 */
+	checkIsom(): Promise<IsomReport | null>;
+	tileInfo(id: number): TileInfo | null;
+	/**
+	 * The terrain a tile belongs to, as the id `types()` lists (a flat pair's CV5 index):
+	 * the tile's own group when it is flat ground, else — under a cliff, a shore or a
+	 * doodad — what the ISOM lattice says the diamond there is. Null off the map, without
+	 * the tileset graphics, or when neither tells.
+	 */
+	terrainAt(tx: number, ty: number): number | null;
+	/** The atlas average of a tile, packed `0xRRGGBB`, or null without graphics. */
+	color(tileId: number): number | null;
+	/** The mean colour of a terrain's common flat variations, packed `0xRRGGBB`. */
+	terrainColor(terrainId: number): number | null;
+	/** A flat terrain's height level (0 low, 1 high, 2 higher), or null when it is not one. */
+	heightOf(terrainId: number): 0 | 1 | 2 | null;
+	/** The lattice diamond under a map pixel. */
+	diamondAt(px: number, py: number): Diamond;
+	isDiamond(d: Diamond): boolean;
+	/** Every in-bounds diamond whose centre tile lies in `rect`, row by row. */
+	diamondsIn(rect: Rect): Diamond[];
+	/** The 4-connected area around a tile of the same terrain type (`"terrain"`, the Rect fill's reading) or the same exact tile (`"tile"`), as flat indices. */
+	floodRegion(x: number, y: number, match?: "terrain" | "tile"): number[];
+	/**
+	 * The Blend brush's list: drawable tiles whose opposite edge meets the anchor tile's
+	 * `side`, nearest first, with the pixel distance (`0..255`, designed pairs 0.2–8).
+	 * Empty without the graphics.
+	 */
+	blendCandidates(anchorTileId: number, side: Side, options?: Partial<BlendOptions>): BlendCandidate[];
+	/** The Rect brush's terrain, in the tileset's own terms: the even CV5 group of a flat pair, or -1. */
+	flatGroupOf(terrainId: number): number;
+	/** Tools ▸ Symmetry…: the mode the brushes paint and the palettes place under. */
+	symmetry(): SymmetryMode;
+	setSymmetry(mode: SymmetryMode): void;
+	/** Whether a mode can run on the open map (the rotations and diagonals need a square one). */
+	symmetryAvailable(mode: SymmetryMode): boolean;
+	/** Flat indices of `cells` and their images under the symmetry mode, each once. */
+	mirror(cells: Rect | Iterable<number>): number[];
+	/** A map pixel and its images under the symmetry mode, the original first. */
+	mirrorPoint(px: number, py: number): {
+		x: number;
+		y: number;
+	}[];
+	active(): ActiveBrush;
+	setActive(brush: Partial<ActiveBrush>): void;
+}
+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>;
+	raw(): LoadedTileset | null;
+}
+export interface SelectionApi {
+	/** The Cut / Copy / Paste layer's marked rectangle, in tiles. */
+	markedArea(): Rect | null;
+	markArea(rect: Rect | null): void;
+	units(): number[];
+	setUnits(indices: number[]): void;
+	sprites(): number[];
+	setSprites(indices: number[]): void;
+	doodads(): number[];
+	setDoodads(indices: number[]): void;
+	locations(): number[];
+	setLocations(indices: number[]): void;
+	layer(): EditorLayer;
+	setLayer(layer: EditorLayer): void;
+	/** Layers the Layers panel has locked: their tools refuse to change the map. */
+	lockedLayers(): EditorLayer[];
+	setLayerLocked(layer: EditorLayer, locked: boolean): void;
+}
+/** What `clipboard.copy` / `cut` take: the marked area (or any tile rect), or objects by index. */
+export type ClipSource = {
+	rect: Rect;
+} | {
+	units?: number[];
+	sprites?: number[];
+	doodads?: number[];
+	locations?: number[];
+};
+export interface PasteOptionsSpec {
+	/** Over what `clipboard.parts()` says. */
+	parts?: Partial<ClipParts>;
+	/** Over `clipboard.mode()`. */
+	mode?: PasteMode;
+}
+/**
+ * The Cut / Copy / Paste layer. The clip is self-contained (it outlives the map it came
+ * from and pastes into another) and shared with the user's own clipboard, so a plugin
+ * that copies here is copying for the user too.
+ */
+export interface ClipboardApi {
+	/** What is on the clipboard, or null. */
+	clip(): Clip | null;
+	/** Put a clip on the clipboard (one from `copy`, or built elsewhere); null clears it. */
+	setClip(clip: Clip | null): void;
+	/**
+	 * Copy a source — the marked area when omitted (or, on an object layer, that layer's
+	 * selection, as Ctrl+C does) — with the parts ticked in `parts()`. Null when there is
+	 * nothing to copy.
+	 */
+	copy(source?: ClipSource): Clip | null;
+	/** Copy, then remove the source's objects as one undo step (terrain and fog stay). Null when there was nothing. */
+	cut(source?: ClipSource): Clip | null;
+	/**
+	 * Stamp the clip with its top-left tile at (tx, ty), one undo step; the pasted area
+	 * becomes the marked one. Null when there is no clip or no map.
+	 */
+	paste(tx: number, ty: number, options?: PasteOptionsSpec): PasteResult | null;
+	parts(): ClipParts;
+	setParts(patch: Partial<ClipParts>): void;
+	mode(): PasteMode;
+	setMode(mode: PasteMode): void;
+	/** Whether the clipboard layer is armed: the next click on the map pastes. */
+	pasting(): boolean;
+	/** Arm pasting (switches to the clipboard layer) or stop. */
+	setPasting(on: boolean): void;
+	/** One line for a clip: `12 × 8 tiles · 3 units · 2 doodads`. */
+	summary(clip: Clip): string;
+}
+/**
+ * The file formats File ▸ Import / Export read and write, so a plugin can keep triggers
+ * or strings outside the map in a form the editor (and SCMDraft) take back.
+ */
+export interface ExchangeApi {
+	/** Raw 2400-byte TRIG records, SCMDraft's `.trg`; string indices are the map's own. */
+	encodeTrg(triggers: TriggerRecord[]): Uint8Array;
+	decodeTrg(bytes: Uint8Array): TriggerRecord[];
+	/** The whole string table as `index<TAB>text` lines, control bytes as `<XX>`. */
+	formatStrings(): string;
+	/** Parse that form (`errors` names the lines that were not `N<TAB>text`); `tx.strings.import` applies it. */
+	parseStrings(text: string): StringImport;
+}
+/**
+ * What the Units, Sprites, Doodads and Fog of War palettes have picked — the thing a
+ * click on the map would place or paint. (The Terrain palette's pick is
+ * `terrain.active()`.) Players are 0-based: `owner` 0 is Player 1.
+ */
+export interface PaletteChoice {
+	/** The player whose fog the Fog of War layer draws, 0-based. */
+	fogViewPlayer: number;
+	/** units.dat id the Units palette places. */
+	unit: number;
+	/** The player it places for, 0–11. */
+	owner: number;
+	spriteKind: SpriteKind;
+	/** sprites.dat id, placed when `spriteKind` is `"pure"`. */
+	sprite: number;
+	/** units.dat id, placed when `spriteKind` is `"unit"` (doors and traps). */
+	unitSprite: number;
+	spriteFlipped: boolean;
+	spriteDisabled: boolean;
+	/** The Doodads palette's doodad id, or -1 before one was picked. */
+	doodad: number;
+	/** Bit mask of the players the fog brush paints for (bit n = player n + 1). */
+	fogPlayers: number;
+	fogMode: FogMode;
+}
+/** A unit type's footprint, from units.dat; a one-tile box without the tables. */
+export interface UnitSize {
+	/** The placement box, in pixels. */
+	width: number;
+	height: number;
+	building: boolean;
+	flyer: boolean;
+}
+export interface DoodadInfo {
+	id: number;
+	/** "Trees #12" — the palette category and the id, which is the only name a doodad has. */
+	name: string;
+	category: string;
+	/** Footprint in tiles. */
+	width: number;
+	height: number;
+}
+export interface PaletteApi {
+	active(): PaletteChoice;
+	setActive(choice: Partial<PaletteChoice>): void;
+	/** The colour a player's units are shown in, `#rrggbb` (the same as `graphics.playerColor`). */
+	playerColor(owner: number): string;
+	/** The Units palette's placement checks and snapping — what `placeUnit`, `canPlaceUnit` and `query.placement` apply, and whether an edit removes stranded units. */
+	placementOptions(): PlacementOptions;
+	setPlacementOptions(patch: Partial<PlacementOptions>): void;
+	/** The Doodads palette's rules: place anywhere, snap to grid. */
+	doodadPlacement(): DoodadPlacementOptions;
+	setDoodadPlacement(patch: Partial<DoodadPlacementOptions>): void;
+	/** The Locations layer's snap step in pixels, 0 for off. */
+	locationSnap(): number;
+	setLocationSnap(step: 0 | 8 | 16 | 32 | 64): void;
+	/** Every unit type, grouped the way the Units palette lists them. */
+	unitGroups(): UnitGroup[];
+	unitName(unitId: number): string;
+	unitSize(unitId: number): UnitSize;
+	/** What the Sprites palette lists, by group; empty until the unit tables are loaded. */
+	spriteGroups(): SpriteGroup[];
+	/** "Terran Marine" for a unit sprite, the unit or GRP the pure sprite draws otherwise. */
+	spriteName(kind: SpriteKind, id: number): string;
+	/** The open map's doodads by palette category; empty without the tileset graphics. */
+	doodadCategories(): {
+		name: string;
+		doodads: DoodadInfo[];
+	}[];
+	doodadInfo(doodadId: number): DoodadInfo | null;
+}
+export interface NamedValue {
+	value: number;
+	label: string;
+}
+/**
+ * The names behind the numbers a map stores, so a plugin that shows raw values need not
+ * carry the game's tables itself. The per-map ones (`string`, `location`, `switch`,
+ * `player`) read the open scenario and answer a placeholder without one; the rest are
+ * the editor's own tables — the same names StarEdit shows.
+ */
+export interface NamesApi {
+	/** StarEdit's name for a units.dat id; `Any unit` / `Men` / `Buildings` / `Factories` for the trigger classes 228–231. */
+	unit(id: number): string;
+	units(): NamedValue[];
+	upgrade(id: number): string;
+	upgrades(): NamedValue[];
+	tech(id: number): string;
+	techs(): NamedValue[];
+	weapon(id: number): string;
+	weapons(): NamedValue[];
+	/** An OWNR / IOWN controller byte: `Human`, `Computer`, `Neutral`, … */
+	playerType(value: number): string;
+	playerTypes(): NamedValue[];
+	/** A SIDE race byte. */
+	race(value: number): string;
+	races(): NamedValue[];
+	/** One of the 27 trigger player groups (`Player 1` … `Non Allied Victory Players`). */
+	playerGroup(value: number): string;
+	playerGroups(): NamedValue[];
+	/** A TRIG condition type. */
+	condition(type: number): string;
+	conditions(): NamedValue[];
+	/** A TRIG action type, or an MBRF one with `briefing`. */
+	action(type: number, briefing?: boolean): string;
+	actions(briefing?: boolean): NamedValue[];
+	/** The script behind a Run AI Script code (the four characters as a little-endian u32); the code itself when unknown. */
+	aiScript(code: number): string;
+	/** The open map's string at an index; null for 0, out of range, or no map. */
+	string(index: number): string | null;
+	/** A location slot's name (0-based; 63 is Anywhere), or StarEdit's default for it. */
+	location(index: number): string;
+	/** A switch's name (0-based), or `Switch N`. */
+	switch(index: number): string;
+	/** `Player N` for a slot (0-based). */
+	player(slot: number): string;
+	/** The terrain a MTXM / TILE id belongs to (`Dirt`, `High Dirt`, a cliff, …), or null without the tileset graphics. */
+	tile(id: number): string | null;
+}
+/**
+ * Bytes 0x01–0x1F in a string are colour and layout codes. This is the editor's own table
+ * of what each one does — the same one the String Editor's buttons and preview are drawn
+ * from — plus the reading of a string that turns those bytes into what the game shows.
+ *
+ * A plugin that displays or rewrites map text should use this rather than carrying a copy:
+ * the numbering is easy to get wrong (the editor's own table was, from 0x12 up, until it
+ * was checked against the classic player palette).
+ *
+ * ## Remastered
+ *
+ * `runs` models Remastered's rule, where a colour set on one line carries onto the next.
+ * StarCraft 1.16.1 reset the colour at every line break, so a string written before the
+ * remaster can draw in colours its author never chose — `bleedingLines` finds exactly
+ * those lines and `fixBleeding` writes the reset the old game supplied. Pass
+ * `resetPerLine` to `runs` to see the old rendering.
+ */
+export interface TextApi {
+	/** Every byte the game gives a meaning, in order; `rgb` is set for the colours only. */
+	codes(): TextCode[];
+	/** One byte's meaning, or null for a byte the game ignores. */
+	code(byte: number): TextCode | null;
+	/** The codes worth offering as buttons: no tab, newlines or the do-nothing byte. */
+	insertable(): TextCode[];
+	/** `#rrggbb` — what the game starts a string in, and what 1.16.1 reset to at a line break. */
+	defaultColor(): string;
+	/** The string split into lines of coloured runs, the way the game draws it. */
+	runs(text: string, options?: RunOptions): TextLine[];
+	/** The text with every control byte removed — what the string actually says. */
+	plain(text: string): string;
+	/** `<0E>`, the way every StarCraft editor writes a control byte. */
+	escape(byte: number): string;
+	/**
+	 * The lines of `text` that Remastered draws in a colour 1.16.1 did not: a line that sets
+	 * no colour of its own, after one that left a colour set. Empty for a single-line string.
+	 */
+	bleedingLines(text: string): BleedingLine[];
+	/**
+	 * `text` with the default colour written at the head of every bleeding line, so both
+	 * games draw it alike. Idempotent, and never changes what the string says.
+	 */
+	fixBleeding(text: string): string;
+}
+export type DialogSize = "sm" | "md" | "lg" | "xl" | "full";
+export interface DialogButton {
+	label: string;
+	primary?: boolean;
+	/** Return `false` (or a promise of it) to keep the dialog open. */
+	run?: (dialog: DialogHandle) => void | boolean | Promise<void | boolean>;
+	/** Close after `run`; default true. */
+	closes?: boolean;
+}
+/** What a paste or a drop brought into a dialog. */
+export interface DialogTransfer {
+	files: File[];
+	text: string;
+}
+export interface DialogSpec {
+	title: string;
+	size?: DialogSize;
+	tall?: boolean;
+	/** Fill `body` (an empty `<div>` inside the dialog); return a cleanup if you need one. */
+	mount(body: HTMLElement, dialog: DialogHandle): void | (() => void);
+	/** Footer buttons, left to right; a single Close when omitted. */
+	buttons?: DialogButton[];
+	/**
+	 * Ctrl+V anywhere in the dialog (while it is the topmost one). Files come from the
+	 * clipboard's items — a screenshot pastes as one `image/png` file — and `text` is the
+	 * plain-text part, so a copied image URL arrives here too.
+	 */
+	onPaste?: (transfer: DialogTransfer, dialog: DialogHandle) => void;
+	/** Something dropped onto the dialog body. */
+	onDrop?: (transfer: DialogTransfer, dialog: DialogHandle) => void;
+	/**
+	 * Escape normally closes the dialog. Answer true to keep it open for this press —
+	 * when the key was meant for something inside the dialog that handles Escape itself
+	 * (a code editor dismissing its own popups), judged by the element it landed on.
+	 */
+	keepOpenOnEscape?: (target: EventTarget | null) => boolean;
+}
+export interface DialogHandle {
+	close(): void;
+	/** Whether the dialog is still on screen. */
+	isOpen(): boolean;
+	/** Change the title strip's text. */
+	setTitle(title: string): void;
+}
+/**
+ * A panel floats over the map and does not block it: the user keeps drawing, scrolling
+ * and using hotkeys while it is open (except while typing in one of its fields). It
+ * is dragged by its title bar and closed with the × or `close()`.
+ */
+export interface PanelSpec {
+	title: string;
+	/** In CSS pixels; 260 by default. The panel is as tall as its content, up to the map's height. */
+	width?: number;
+	/** Fill `body` (an empty `<div>` inside the panel); return a cleanup if you need one. */
+	mount(body: HTMLElement, panel: PanelHandle): void | (() => void);
+	/** The panel closed, whichever way. */
+	onClose?: () => void;
+}
+export interface PanelHandle {
+	close(): void;
+	isOpen(): boolean;
+	setTitle(title: string): void;
+}
+/** The pointer over the map, in the map's own units. A tile is 32 × 32 pixels. */
+export interface MapPointer {
+	/** Map pixels. Kept inside the map while a button is held, as the built-in brushes do. */
+	px: number;
+	py: number;
+	/** The tile under the pointer. */
+	tx: number;
+	ty: number;
+	/** False once the pointer has left the map with no button held. */
+	inMap: boolean;
+	/** Whether the primary button is held. */
+	down: boolean;
+	shift: boolean;
+	ctrl: boolean;
+	alt: boolean;
+}
+/** Map pixels to canvas pixels, for a tool's `draw`. */
+export interface MapView {
+	zoom: number;
+	/** Canvas pixels per tile. */
+	tilePx: number;
+	/** A map pixel's x on the canvas. */
+	x(px: number): number;
+	y(py: number): number;
+	/** The tiles on screen. */
+	visible: Rect;
+}
+export type MapToolStopReason = 
+/** `handle.stop()`. */
+"stopped"
+/** Esc or a right-click, and `onCancel` did not keep the tool. */
+ | "cancelled"
+/** The map was closed or replaced. */
+ | "document"
+/** Another tool started. */
+ | "replaced"
+/** The plugin was disabled. */
+ | "disabled";
+/**
+ * A tool owns the pointer over the map: the viewport hands it every press, move and
+ * release ahead of the active layer's own tools, hides the layer's brush ghost, and
+ * lets it draw an overlay. The map stays visible and scrollable, and a panel can stay
+ * open beside it — which is how a plugin gets a drawing mode of its own.
+ */
+export interface MapToolSpec {
+	/** Shown in the viewport's HUD and the status bar while the tool runs. */
+	name: string;
+	/** After the name: `"drag to draw a line"`. */
+	hint?: string;
+	/** CSS cursor over the map; `"crosshair"` by default. */
+	cursor?: string;
+	onDown?(p: MapPointer): void;
+	/** Every pointer move over the map, button held or not, and once with `inMap: false` when it leaves. */
+	onMove?(p: MapPointer): void;
+	onUp?(p: MapPointer): void;
+	/** Esc or a right-click. Return `true` to keep the tool running (you cancelled a gesture of your own); otherwise it stops. */
+	onCancel?(): boolean | void;
+	/** Draw over the map, after everything else, each time the viewport repaints. */
+	draw?(ctx: CanvasRenderingContext2D, view: MapView): void;
+	/** The tool is no longer running, for whatever reason (once). */
+	onStop?(reason: MapToolStopReason): void;
+}
+export interface MapToolHandle {
+	stop(): void;
+	isActive(): boolean;
+	/** Repaint the viewport — and so call `draw` — now. Cheap; call it from `onMove`. */
+	redraw(): void;
+}
+/** Where in the viewport's paint pass an overlay draws. */
+export type OverlayAbove = 
+/** Over the terrain and grid, under doodad footprints, units, sprites and locations (the default). */
+"terrain"
+/** Over units, sprites and locations, under fog of war. */
+ | "objects"
+/** Over everything but a running map tool's own drawing. */
+ | "everything";
+/**
+ * An overlay is a picture drawn over the map that the user can turn on and off: it
+ * is listed under View ▸ Overlays and in the Layers panel, stays while the user works
+ * on any layer, and never takes the pointer — clicks go to the active layer's tools
+ * as usual. It hears the pointer through `onHover`, which is how a readout follows the
+ * mouse while the user places units. Register one at activation and keep the handle;
+ * it goes away with the plugin.
+ */
+export interface OverlaySpec {
+	/** Shown in View ▸ Overlays and the Layers panel. Unique per plugin. */
+	name: string;
+	/** Start visible; true by default. What the user last set for this name wins for the session. */
+	visible?: boolean;
+	/** Where the picture goes in the paint pass; `"terrain"` by default. */
+	above?: OverlayAbove;
+	/** Draw in canvas pixels through `view`, each time the viewport repaints while visible. */
+	draw(ctx: CanvasRenderingContext2D, view: MapView): void;
+	/**
+	 * The pointer over the map while the overlay is visible, on every layer and while a
+	 * map tool runs; `null` once when it leaves. Call `handle.redraw()` here to move a
+	 * hover mark. A press sets `down` but is never captured for you.
+	 */
+	onHover?(p: MapPointer | null): void;
+	/** The overlay was shown or hidden, by the user in the chrome or by your handle. */
+	onToggle?(visible: boolean): void;
+}
+export interface OverlayHandle {
+	show(): void;
+	hide(): void;
+	toggle(): void;
+	isVisible(): boolean;
+	/** Repaint the viewport — and so call `draw` — now. */
+	redraw(): void;
+	/** Take the overlay out of the chrome for good; `isVisible` is false from then on. */
+	remove(): void;
+}
+export interface PickOptions {
+	/** Shown in the viewport's HUD while the user picks; also the status line. */
+	prompt?: string;
+}
+export interface PickFilesOptions {
+	/** `accept` for the file input, e.g. `"image/*"` or `".png,.jpg"`. */
+	accept?: string;
+	multiple?: boolean;
+}
+export interface UiApi {
+	/** Set the status bar line. */
+	status(text: string): void;
+	/** The status bar line as it stands. */
+	statusText(): string;
+	/** A short notice over the map that leaves by itself — how Save reports; `ttl` 0 keeps it until dismissed. */
+	toast(toast: {
+		kind?: Toast["kind"];
+		title: string;
+		detail?: string;
+		ttl?: number;
+	}): void;
+	/**
+	 * Write a file to disk the way the editor's own exports do: into the file the browser's
+	 * save dialog picks, or as a download where there is no dialog. Resolves with where it
+	 * went, or null when the user dismissed the dialog.
+	 */
+	saveFile(data: Blob | Uint8Array, fileName: string): Promise<{
+		route: "picker" | "download";
+		fileName: string;
+	} | null>;
+	dialog(spec: DialogSpec): DialogHandle;
+	/** Open a floating panel over the map. As many as you like; each closes with the plugin. */
+	panel(spec: PanelSpec): PanelHandle;
+	/**
+	 * Take over the pointer on the map until `stop()`, Esc, a right-click, a map change
+	 * or another tool. One tool runs at a time — starting one stops the previous — and a
+	 * `pickArea` / `pickTile` in progress is served first.
+	 */
+	mapTool(spec: MapToolSpec): MapToolHandle;
+	/**
+	 * A picture over the map the user can switch on and off (View ▸ Overlays, the Layers
+	 * panel) and that stays while they work on any layer. It draws at every repaint and
+	 * hears the pointer, but never takes it. As many as you like; they go with the plugin.
+	 */
+	overlay(spec: OverlaySpec): OverlayHandle;
+	/** The browser's file picker; resolves with an empty list on cancel. */
+	pickFiles(options?: PickFilesOptions): Promise<File[]>;
+	/**
+	 * Let the user drag a rectangle on the map. The viewport switches to a crosshair, draws
+	 * the marquee and takes the gesture ahead of the active layer's tools; resolves with
+	 * the tile rect (exclusive `x1` / `y1`), or null when the user pressed Esc or
+	 * right-clicked, no map is open, the map was replaced, or the plugin was disabled.
+	 * Only one pick runs at a time — a new one cancels the previous. A modal dialog
+	 * covers the map, so close yours first and reopen it with the result.
+	 */
+	pickArea(options?: PickOptions): Promise<Rect | null>;
+	/** As `pickArea`, for a single click: the tile under it. */
+	pickTile(options?: PickOptions): Promise<{
+		x: number;
+		y: number;
+	} | null>;
+	/**
+	 * Decode a picture: a `File` / `Blob`, a `data:` URL, or an `http(s)` URL (fetched, and
+	 * when the site refuses cross-origin reads, loaded through an `<img>` with
+	 * `crossOrigin` — a site that allows neither rejects with a message saying so).
+	 */
+	loadImage(source: Blob | string): Promise<ImageBitmap>;
+	/** The image on the system clipboard, if the browser lets the page read it (a permission prompt may appear); null otherwise. */
+	readClipboardImage(): Promise<Blob | null>;
+	/** Ask a yes/no question; resolves false on Cancel, Escape or the ×. */
+	confirm(message: string, options?: ConfirmOptions): Promise<boolean>;
+	/** Say something with a single OK. */
+	alert(message: string, options?: ConfirmOptions): Promise<void>;
+	/** Ask for a line of text; null when the user cancelled. */
+	prompt(message: string, options?: PromptOptions): Promise<string | null>;
+	/** A progress bar over the map for long work, with an optional Cancel. */
+	progress(label: string, options?: ProgressOptions): ProgressHandle;
+	/** `el("div", { className: "row" }, …)`: the DOM helper the widgets are built from. */
+	el<K extends keyof HTMLElementTagNameMap>(tag: K, props?: Record<string, unknown>, ...children: WidgetChild[]): HTMLElementTagNameMap[K];
+	/** Buttons, fields, forms and lists in the editor's own styles. */
+	readonly widgets: WidgetsApi;
+	/** Open a built-in dialog (fire and forget; `ask` waits for one that answers). */
+	open(dialog: DialogId, payload?: Record<string, unknown>): void;
+	/**
+	 * Open a built-in dialog that answers — `"saveAs"`, `"confirmClose"`, `"newMap"` — and
+	 * resolve true when it went through, false when it was dismissed.
+	 */
+	ask(dialog: DialogId, payload?: Record<string, unknown>): Promise<boolean>;
+	/** Ask the viewport to repaint (a transaction does this by itself). Raises no event. */
+	repaint(): void;
+}
+export interface ConfirmOptions {
+	title?: string;
+	/** The primary button; `OK` by default. */
+	confirmLabel?: string;
+	cancelLabel?: string;
+	/** Paint the primary button as a destructive action. */
+	danger?: boolean;
+}
+export interface PromptOptions extends ConfirmOptions {
+	value?: string;
+	placeholder?: string;
+	/** A multi-line field. */
+	multiline?: boolean;
+}
+export interface ProgressOptions {
+	title?: string;
+	/** Show a Cancel button; `cancelled()` answers true once it is pressed. */
+	cancellable?: boolean;
+}
+/**
+ * A progress panel over the map. It does not block the editor — the user can still
+ * scroll and look — so a plugin doing long work should report often and check
+ * `cancelled()` in its loop.
+ */
+export interface ProgressHandle {
+	/** How far along (0…1), and optionally a line under the bar. */
+	report(fraction: number, text?: string): void;
+	/** True once the user pressed Cancel or closed the panel. Poll it inside a loop. */
+	cancelled(): boolean;
+	/**
+	 * The same answer as a signal, for work that takes one: aborted when the user
+	 * cancels, so `fetch(url, { signal })` and anything built on `AbortSignal` stop
+	 * with the panel. Never aborted by `done()`.
+	 */
+	readonly signal: AbortSignal;
+	done(): void;
+	isOpen(): boolean;
+}
+/** Anything the widget builders accept as a child: a node, text, or nothing. */
+export type WidgetChild = Node | string | number | null | undefined | false;
+export interface WidgetOptions {
+	className?: string;
+	title?: string;
+	disabled?: boolean;
+}
+export interface ButtonOptions extends WidgetOptions {
+	primary?: boolean;
+	danger?: boolean;
+	ghost?: boolean;
+	onClick?: (event: MouseEvent) => void;
+}
+export interface CheckboxOptions extends WidgetOptions {
+	value?: boolean;
+	/** A radio button instead; give the group a `name`. */
+	radio?: boolean;
+	name?: string;
+	onChange?: (value: boolean) => void;
+}
+/** The `<label>` a checkbox is, with its `<input>` on it so you can read or set the value. */
+export type CheckboxElement = HTMLLabelElement & {
+	input: HTMLInputElement;
+};
+export interface TextFieldOptions extends WidgetOptions {
+	value?: string;
+	placeholder?: string;
+	password?: boolean;
+	onChange?: (value: string) => void;
+}
+export interface NumberFieldOptions extends WidgetOptions {
+	value?: number;
+	min?: number;
+	max?: number;
+	step?: number;
+	onChange?: (value: number) => void;
+}
+export interface SelectOption {
+	value: string | number;
+	label: string;
+	disabled?: boolean;
+}
+export interface SelectOptions extends WidgetOptions {
+	value?: string | number;
+	onChange?: (value: string) => void;
+}
+export interface FormRow {
+	label: string;
+	field: HTMLElement;
+}
+export interface ListItem<T> {
+	label: string;
+	value: T;
+	/** Dimmed text at the end of the row. */
+	hint?: string;
+	/** A number in the row's gutter, as the editor's own lists show indices. */
+	index?: number;
+	title?: string;
+}
+export interface ListOptions<T> {
+	/** Which row starts selected. */
+	selected?: number;
+	/** Maximum height in pixels; the list scrolls past it. */
+	height?: number;
+	className?: string;
+	onPick?: (value: T, index: number) => void;
+}
+/**
+ * Buttons, fields, forms and lists in the editor's own styles, as plain DOM. A plugin
+ * dialog built from these looks like a built-in one; `el` is the escape hatch for
+ * anything they do not cover.
+ */
+export interface WidgetsApi {
+	button(label: string, options?: ButtonOptions): HTMLButtonElement;
+	checkbox(label: string, options?: CheckboxOptions): CheckboxElement;
+	text(options?: TextFieldOptions): HTMLInputElement;
+	number(options?: NumberFieldOptions): HTMLInputElement;
+	select(items: SelectOption[], options?: SelectOptions): HTMLSelectElement;
+	/** A two-column grid of labelled fields. */
+	form(rows: (FormRow | null | undefined | false)[]): HTMLElement;
+	/** A titled box (a `fieldset` with a legend, as the dialogs use). */
+	group(title: string, ...children: WidgetChild[]): HTMLElement;
+	row(...children: WidgetChild[]): HTMLDivElement;
+	column(...children: WidgetChild[]): HTMLDivElement;
+	/** Small dimmed explanatory text. */
+	hint(text: string): HTMLElement;
+	separator(): HTMLElement;
+	list<T>(items: ListItem<T>[], options?: ListOptions<T>): HTMLElement;
+}
+export type TopMenu = "File" | "Edit" | "View" | "Layer" | "Scenario" | "Triggers" | "Tools" | "Plugins" | "Help";
+/**
+ * A top-level menu, or a submenu by label: `"File/Import"`. A last segment that names no
+ * submenu gets one of the plugin's own, at the end of the menu (`"Tools/AI"`).
+ */
+export type MenuPath = TopMenu | `${TopMenu}/${string}`;
+export interface MenuItemSpec {
+	label: string;
+	/** Display only — bind the key with `hotkeys.add`. */
+	shortcut?: string;
+	/**
+	 * A mark in front of the label: `"plugin"` for the plugin's own icon (the manifest's),
+	 * or any `PluginIcon`. Use it when the item does something a built-in never would —
+	 * reach a network, say — so the user can tell at a glance.
+	 */
+	icon?: "plugin" | PluginIcon;
+	/**
+	 * Where in the menu: the label of the built-in item or submenu to sit directly under
+	 * (`"Open Recent"`). Without it, or when nothing has that label, the item goes to the
+	 * end of the menu after a separator.
+	 */
+	after?: string;
+	/** A separator line above this item — for grouping the items of a submenu of your own. */
+	separator?: boolean;
+	enabled?: () => boolean;
+	/** What the item does. Give this or `command`. */
+	run?: () => void;
+	/** A registered command's id, instead of a `run` of its own. */
+	command?: string;
+}
+export interface MenuApi {
+	add(path: MenuPath, item: MenuItemSpec): Disposable;
+}
+export type ContextSurface = "viewport" | "terrainPalette";
+export interface ContextMenuContext {
+	surface: ContextSurface;
+	/** The tile under the pointer (viewport only). */
+	tile: {
+		x: number;
+		y: number;
+	} | null;
+	/** The map pixel under the pointer (viewport only). */
+	point: {
+		px: number;
+		py: number;
+	} | null;
+	layer: EditorLayer;
+	terrainMode: TerrainMode;
+	/** The palette's active terrain id. */
+	terrain: number;
+	markedArea: Rect | null;
+}
+export interface ContextItemSpec {
+	label: string | ((ctx: ContextMenuContext) => string);
+	enabled?: (ctx: ContextMenuContext) => boolean;
+	visible?: (ctx: ContextMenuContext) => boolean;
+	/** Give this or `command` (which is run with the context as its argument). */
+	run?: (ctx: ContextMenuContext) => void;
+	command?: string;
+}
+export interface ContextMenuApi {
+	add(surface: ContextSurface, item: ContextItemSpec): Disposable;
+}
+export interface HotkeyApi {
+	/** `"Ctrl+Shift+I"`, `"Alt+F9"`, `"F8"` — modifiers in any order, then a key name. */
+	add(combo: string, run: (() => void) | {
+		command: string;
+	}): Disposable;
+}
+export type PluginEvent = 
+/** A map was opened, closed or replaced. */
+"document"
+/** Any committed edit (every `document.edit`, stroke, undo and redo bumps it, terrain or not), and a fog edit. */
+ | "terrain" | "units" | "doodads" | "locations" | "settings" | "triggers" | "layer"
+/** THG2 sprites — the same bump doodad edits make. */
+ | "sprites" | "selection"
+/** The marked area or the clip on the clipboard changed. */
+ | "clipboard"
+/** The viewport scrolled, zoomed, or a View menu tick moved. */
+ | "view"
+/** A map tool or a map pick started or stopped. */
+ | "tool"
+/** The map's unsaved-changes flag changed. */
+ | "modified"
+/** A palette's pick changed: terrain brush, unit and owner, sprite, doodad, fog players. */
+ | "palette"
+/** An editing option moved: symmetry, placement rules, doodad rules, location snap, the fog view player, clip parts and paste mode, locked layers, the grid look, Preferences. */
+ | "options"
+/** The document's file changed: its name or handle after a Save, the save options, the archive extras, the recent list. */
+ | "file"
+/** A plugin registered or removed a command — how a plugin learns that one it calls by id has arrived. */
+ | "commands";
+/** Why the document changed. */
+export type DocumentChangeReason = 
+/** File ▸ Open, drag-and-drop, `document.open`: a file the user chose. */
+"open"
+/** File ▸ New (the startup map included). */
+ | "new"
+/** File ▸ Close: `document.isOpen()` is now false. */
+ | "close"
+/** The open map parsed again from edited bytes — a `document.sections` write, by any plugin. */
+ | "replace";
+export interface DocumentEvent {
+	reason: DocumentChangeReason;
+	fileName: string | null;
+}
+/**
+ * Listeners are notifications: they run after the change, in the order the plugins were
+ * activated, and cannot veto or reorder one another. A listener that rewrites the map in
+ * response (through `document.sections`) simply raises a fresh `"document"` event with
+ * reason `"replace"`, which every other listener sees in turn.
+ */
+export interface EventsApi {
+	on(event: "document", listener: (event: DocumentEvent) => void): Disposable;
+	on(event: PluginEvent, listener: () => void): Disposable;
+}
+export interface StorageApi {
+	get<T>(key: string, fallback: T): T;
+	set(key: string, value: unknown): void;
+	remove(key: string): void;
+}
+/** A slug for storage keys and log prefixes. */
+export declare function pluginIdOf(manifest: {
+	id?: string;
+	name: string;
+}): string;
+
+export {};