@scm-js/plugin-api 1.29.0 → 1.31.0

package/index.d.ts

@@ -1694,7 +1694,6 @@ export interface ChangeTilesetResult {
 	spritesDropped: number;
 	refilled: boolean;
 }
-export type SymmetryMode = "none" | "h" | "v" | "hv" | "rot180" | "rot90" | "diag" | "adiag";
 export interface DoodadChange {
 	index: number;
 	before: DoodadRecord | null;
@@ -1715,32 +1714,6 @@ export interface DoodadVerdict {
 	/** Cell indices (row-major) whose ground fails the check, for the ghost to mark red. */
 	bad: number[];
 }
-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[];
@@ -1780,6 +1753,128 @@ export interface HistoryEdit {
 	 */
 	createdMask?: Uint8Array;
 }
+export interface WireListChange<T> {
+	index: number;
+	before: T | null;
+	after: T | null;
+}
+export interface WireLocationChange {
+	index: number;
+	after: LocationRecord;
+	/** The name as text (`after.nameIndex` is resolved again where it lands); null for none. */
+	name: string | null;
+	/** The slot was empty before: a new location, which moves to a free slot if someone else took this one. */
+	created: boolean;
+}
+/**
+ * One undo step's worth of terrain and objects. The grids are flat number lists: terrain
+ * `[at, mtxm, tile, …]`, the others `[at, value, …]`. `reverse` marks the undo of an edit:
+ * its parts go in the reverse of the usual order, as undo walks them.
+ */
+export interface SyncEditOp {
+	kind: "edit";
+	label: string;
+	/** The map size the cells index; a grid part is skipped on a map of another size. */
+	width: number;
+	height: number;
+	reverse?: boolean;
+	terrain?: number[];
+	isom?: number[];
+	doodadTiles?: number[];
+	fog?: number[];
+	/** The whole ISOM lattice (base64 of the u16 cells) the edit gave the map, or null for taking it away. */
+	isomWhole?: string | null;
+	maskWhole?: string | null;
+	units?: WireListChange<UnitRecord>[];
+	doodads?: WireListChange<DoodadRecord>[];
+	sprites?: WireListChange<SpriteRecord>[];
+	locations?: WireLocationChange[];
+}
+declare const SYNC_FIELDS: readonly [
+	"type",
+	"fileVersion",
+	"nameIndex",
+	"descriptionIndex",
+	"playerTypes",
+	"editorPlayerTypes",
+	"playerRaces",
+	"playerColors",
+	"playerRgb",
+	"forces",
+	"unitSettings",
+	"unitAvailability",
+	"upgradeSettings",
+	"upgradeRestrictions",
+	"techSettings",
+	"techRestrictions",
+	"wavs",
+	"cuwp",
+	"cuwpUsed",
+	"triggers",
+	"briefing",
+	"switchNames"
+];
+export type SyncField = (typeof SYNC_FIELDS)[number];
+export interface SyncFieldsOp {
+	kind: "fields";
+	/** Each changed field's new value, packed (`pack`). */
+	set: Partial<Record<SyncField, unknown>>;
+	/** String slots that changed: `[index, before, after]`. */
+	strings?: [
+		number,
+		string | null,
+		string | null
+	][];
+	/** The table's length afterwards (trailing blank slots are dropped). */
+	stringsLength?: number;
+	/** The table's width and text encoding, when they changed. */
+	stringsFormat?: {
+		extended: boolean;
+		encoding: TextEncoding;
+	};
+}
+export interface SyncExtrasOp {
+	kind: "extras";
+	/** `[member name, base64 bytes]`, or null bytes for a member taken out. */
+	set: [
+		string,
+		string | null
+	][];
+}
+export interface SyncResetOp {
+	kind: "reset";
+	label: string;
+	/** The whole scenario, base64. */
+	chk: string;
+}
+export type SyncOp = SyncEditOp | SyncFieldsOp | SyncExtrasOp | SyncResetOp;
+export type SymmetryMode = "none" | "h" | "v" | "hv" | "rot180" | "rot90" | "diag" | "adiag";
+export type StartLayout = "ring" | "corners";
+export interface StartPlacementResult {
+	changes: UnitChange[];
+	/** 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;
+}
 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. */
@@ -1855,11 +1950,55 @@ export interface Preferences {
 	 * is replaced by the first map opened rather than kept beside it.
 	 */
 	multipleMaps: boolean;
-	/** What File ▸ New and the startup map start with. */
+	/**
+	 * What File ▸ New and the startup map start with. `version` is the file's revision:
+	 * Brood War (VER 205, what every build reads) or Remastered (206, 32-bit strings).
+	 */
 	newMap: {
 		tileset: TilesetId;
 		width: number;
 		height: number;
+		version: NewMapVersion;
+	};
+	/**
+	 * Startup: `reopenLast` opens the most recent file again in place of the blank map
+	 * (the desktop app straight away; a browser needs a click first, so it asks in a
+	 * notice), and `recents` is how many File ▸ Open Recent keeps.
+	 */
+	startup: {
+		reopenLast: boolean;
+		recents: number;
+	};
+	/**
+	 * What the Save dialog starts from: the options the file was opened with
+	 * (`"asOpened"`, the default), or one of its presets. `compression` is for a map with
+	 * no origin — new, or opened from a bare .chk — where there is nothing to follow;
+	 * `"asOpened"` there means StarEdit's PKWARE.
+	 */
+	save: {
+		start: "asOpened" | "everything" | "smallest";
+		compression: "asOpened" | ArchiveCompression;
+	};
+	/** How many edits Undo keeps per map (SCMDraft keeps 200). */
+	undoLevels: number;
+	/**
+	 * The mouse wheel over the map: scrolling, with Ctrl+wheel zooming (the default), or
+	 * zooming, with Shift+wheel scrolling sideways. `zoomToCursor` keeps the tile under the
+	 * pointer in place when the wheel zooms; the menu and keyboard keep the centre.
+	 */
+	view: {
+		wheel: "scroll" | "zoom";
+		zoomToCursor: boolean;
+	};
+	/**
+	 * What the palettes start on: the owner of placed units and sprites (0 = player 1),
+	 * the brush size (1–7), and the size of a location the Locations palette's New makes,
+	 * in tiles.
+	 */
+	placement: {
+		owner: number;
+		brushSize: number;
+		locationTiles: number;
 	};
 	/** Initial View ▸ Animate Water / Animate Units. */
 	animateWater: boolean;
@@ -1912,6 +2051,8 @@ export interface Preferences {
 }
 /** See `Preferences.plugins.updates`. */
 export type PluginUpdateMode = "notify" | "manual" | "auto";
+/** The revisions a new map can start on; the two older ones are for opening old files, not making new ones. */
+export type NewMapVersion = Extract<MapVersion, "broodwar" | "remastered">;
 /**
  * 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
@@ -2075,6 +2216,13 @@ export interface PluginApi {
 	/** The plugin's words in the editor's language: its own catalogues, and a `t` over them. */
 	readonly i18n: I18nApi;
 	readonly events: EventsApi;
+	/**
+	 * Editing the map in front together with other editors: every change to it is handed out
+	 * as an op for the plugin to carry to them, and theirs come back in, in the order a
+	 * server puts them. The scmjs.dev plugin's shared maps are built on it; the transport,
+	 * the server and who may join are the plugin's.
+	 */
+	readonly sync: SyncApi;
 	/**
 	 * A small key-value store of the plugin's own, kept in the browser's local storage under
 	 * the plugin's id and listed with everything else in Preferences ▸ Browser storage.
@@ -4077,6 +4225,40 @@ export interface DialogSlotHost {
 export interface DialogSlotSpec {
 	mount(body: HTMLElement, host: DialogSlotHost): void | (() => void);
 }
+/**
+ * A page of the plugin's own in Edit ▸ Preferences, listed under Plugins by the plugin's
+ * name — where a user looks for a setting, instead of a menu item per plugin. One page per
+ * plugin; registering again replaces it. `mount` runs the first time the page is shown
+ * while the dialog is open and the page then stays mounted until the dialog closes, so
+ * what the user changed is still there when OK or Apply calls `apply`; the cleanup runs
+ * on close. A page with no `apply` writes its settings as they change (`api.storage`),
+ * which is the simpler shape when nothing needs undoing on Cancel.
+ *
+ * @example
+ * api.ui.preferencesPage({
+ *   mount(body) {
+ *     const w = api.ui.widgets;
+ *     const dock = w.select([{ value: "float", label: "Floating" }, { value: "right", label: "Docked" }], { value: settings.dock });
+ *     body.append(w.form([{ label: "Panel", field: dock }]), w.hint("Where the panel opens."));
+ *     pending = () => save({ dock: dock.value });
+ *   },
+ *   apply: () => pending?.(),
+ * });
+ */
+export interface PreferencesPageSpec {
+	/** Fill `body` with the page's controls; return a cleanup if you need one. */
+	mount(body: HTMLElement, page: PreferencesPageHost): void | (() => void);
+	/** Called on OK and Apply while the dialog is open and the page has been shown. */
+	apply?(): void;
+	/** Called by Reset to defaults while the page is the one showing. */
+	reset?(): void;
+}
+/** What a preferences page's `mount` is handed. */
+export interface PreferencesPageHost {
+	readonly plugin: PluginInfo;
+	/** Close the Preferences dialog. */
+	close(): void;
+}
 /**
  * What `view.flash` highlights: a tile rect, or units / locations by index. The
  * highlight fades over `ms` (600 by default) and never blocks or takes the pointer; it is
@@ -4237,6 +4419,11 @@ export interface PickFilesOptions {
 	multiple?: boolean;
 }
 export interface UiApi {
+	/**
+	 * The dialogs open now, bottom to top, by id: the built-in ones by their `DialogId`, a
+	 * plugin's as `"pluginDialog"`. What a shared map shows others ("in Player Settings").
+	 */
+	openDialogs(): string[];
 	/** Set the status bar line. */
 	status(text: string): void;
 	/** The status bar line as it stands. */
@@ -4286,6 +4473,12 @@ export interface UiApi {
 	 * });
 	 */
 	dialogSlot(dialog: DialogSlotId, spec: DialogSlotSpec): Disposable;
+	/**
+	 * A page of the plugin's own in Edit ▸ Preferences, under Plugins — see
+	 * `PreferencesPageSpec`. `ui.open("preferences", { page: "plugin:<id>" })` opens it.
+	 * Returns the registration; it leaves with `dispose()` or the plugin.
+	 */
+	preferencesPage(spec: PreferencesPageSpec): Disposable;
 	/**
 	 * 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
@@ -4778,8 +4971,78 @@ export type PluginEvent =
  | "commands"
 /** A plugin provided or withdrew a service — `services.watch` is the usual way to hear this for one name. */
  | "services"
+/** A dialog opened or closed — `ui.openDialogs()` says which are open. */
+ | "dialogs"
 /** The game data source changed: installed, switched to another data set, or a copy removed. `gameData.source()` says what it is now. */
  | "gameData";
+/** Why other people's changes are waiting: a stroke under way on the map, a dialog that edits the map open, another map in front. */
+export type SyncHold = "stroke" | "dialog" | "behind";
+export interface SyncReport {
+	/** Other people's ops applied. */
+	ops: number;
+	/** Parts of them that could not be applied — the unit they moved was deleted, the map was resized… */
+	dropped: number;
+	/** Parts of this editor's unconfirmed changes that no longer applied on top of theirs. */
+	lost: number;
+}
+export interface SyncStartOptions {
+	/**
+	 * Every change made to the shared map, as a plain object JSON can carry, in the order
+	 * made: commits, undo and redo, the dialogs' writes, archive files, and a resize or a
+	 * tileset change (the whole scenario). Each must reach the server, and every other
+	 * editor, in this order.
+	 */
+	send(op: SyncOp): void;
+	/** The session ended: the shared map was closed or replaced by another, or `stop` was called. */
+	onEnd?(reason: "closed" | "stopped"): void;
+	/** Other people's changes were applied to the map. */
+	onApplied?(report: SyncReport): void;
+}
+/**
+ * One shared map. The server confirms each op this editor sent (`confirm`, in order) and
+ * relays everyone else's (`receive`, in the order it gave them); the session applies
+ * them to the map when nothing is in the way (`holding`) and rebases this editor's
+ * unconfirmed changes on top, so every editor that has seen the same ops has the same map.
+ *
+ * @example
+ * const session = api.sync.start({ send: (op) => socket.send(JSON.stringify({ type: "op", op })) });
+ * socket.onmessage = (m) => {
+ *   const msg = JSON.parse(m.data);
+ *   if (msg.type === "ack") session?.confirm();
+ *   if (msg.type === "op") session?.receive(msg.op);
+ * };
+ */
+export interface SyncSession {
+	/** The shared map's `document.id()`. */
+	readonly documentId: number;
+	/** Another editor's op, in the server's order. False, and nothing done, for a value that is not an op. */
+	receive(op: unknown): boolean;
+	/** The server confirmed the oldest op this editor sent. */
+	confirm(): void;
+	/** Ops sent and not yet confirmed. */
+	pending(): number;
+	/** Ops and confirmations received and not yet applied. */
+	waiting(): number;
+	/**
+	 * The shared map as a file (`.scx` / `.scm`, not built), copied at this moment — for a
+	 * server to hand people joining, labelled with the last op this editor applied. Null
+	 * while anything is pending or waiting (the copy would not match any point in the
+	 * server's order) or while another map is in front. The copy is taken before the first
+	 * `await`, so a change made while the file is written is not in it.
+	 */
+	snapshot(): Promise<Uint8Array | null>;
+	holding(): SyncHold | null;
+	stop(): void;
+}
+export interface SyncApi {
+	/**
+	 * Share the map in front. Null when no map is open or another session is running (one
+	 * at a time). A session a plugin started stops when the plugin is turned off.
+	 */
+	start(options: SyncStartOptions): SyncSession | null;
+	/** The running session, whichever plugin started it. */
+	current(): SyncSession | null;
+}
 /** Why the document changed. */
 export type DocumentChangeReason = 
 /** File ▸ Open, drag-and-drop, `document.open`: a file the user chose. */

package/package.json

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