@scm-js/plugin-api 1.44.0 → 1.46.0

package/index.d.ts

@@ -2565,6 +2565,8 @@ export interface DocumentInfo {
 	version: number;
 	fileName: string | null;
 	modified: boolean;
+	/** Open to look at only (`OpenDocumentOptions.viewOnly`): every write throws and it is never saved. */
+	viewOnly: boolean;
 }
 /** What one `document.edit` changed, per list. */
 export interface EditResult {
@@ -2741,6 +2743,20 @@ export interface ResizeDocumentOptions {
 export type OpenInto = "new" | "current";
 export interface OpenDocumentOptions {
 	into?: OpenInto;
+	/**
+	 * Open the map to look at, not to change — a replay's map, a preview. It always opens
+	 * beside the open map (`into` is ignored), so nothing is replaced and nothing is asked.
+	 * Panning, zooming, the layers and selecting work; every tool, menu and dialog that
+	 * would change it is off, and every write throws — `edit`, `update`, `sections` (except
+	 * `replaceFile(…, { asOpened: true })`, a reading of the file rather than an edit), `resize`,
+	 * `changeTileset`, `extras`, the clipboard's `cut` and `paste`, `save` and `saveAs` unless
+	 * as a copy, `sync.start`. It is never kept in Open Recent, and closing it asks nothing. File ▸ Edit a Copy
+	 * opens an ordinary copy. `label` is what the tab and the status bar call it ("Replay");
+	 * `true` is the plain "View only".
+	 */
+	viewOnly?: boolean | {
+		label?: string;
+	};
 }
 /** One open map, as `document.list()` reports it. `active` marks the one in front — the one every other call reads and writes. */
 export interface OpenDocumentInfo {
@@ -2754,6 +2770,8 @@ export interface OpenDocumentInfo {
 	height: number;
 	modified: boolean;
 	active: boolean;
+	/** Open to look at only; see `OpenDocumentOptions.viewOnly`. */
+	viewOnly: boolean;
 }
 /** File ▸ New's form: size, tileset, and the two strings the dialog asks for. */
 export interface NewDocumentOptions {
@@ -2869,11 +2887,14 @@ export interface DocumentApi {
 	 * In place of a map with unsaved changes, when Preferences say to ask, the Close
 	 * Scenario dialog comes first and the user may cancel. Resolves true once the file is
 	 * the map in front, false when the user kept the current map or the file could not be
-	 * read (the status bar says why).
+	 * read (the status bar says why). `options.viewOnly` opens it to look at only.
 	 *
 	 * @example
 	 * const [file] = await api.ui.pickFiles({ accept: ".scx,.scm,.chk" });
 	 * if (file) await api.document.open(file, file.name, { into: "new" });
+	 * @example
+	 * // A replay's map, to draw over and not to change.
+	 * await api.document.open(chk, "Lost Temple.scx", { viewOnly: { label: "Replay" } });
 	 */
 	open(file: File | Blob | Uint8Array, fileName?: string, options?: OpenDocumentOptions): Promise<boolean>;
 	/**
@@ -2963,6 +2984,24 @@ export interface RawEditResult {
 	/** Warnings from parsing the edited file (a truncated section, no usable DIM, …); empty when it read cleanly. */
 	warnings: string[];
 }
+/** How `document.sections.replaceFile` installs the bytes. */
+export interface ReplaceFileOptions {
+	/**
+	 * Take the bytes as the file that was opened rather than as an edit: the map stays
+	 * unmodified, so closing it does not ask to save, while Save writes the bytes as given.
+	 * For a plugin that repairs a map as it opens — nothing the user did changed it. Use it
+	 * only right after an `"open"`, or to put back what was opened; anything else would
+	 * hide a change from the user. The history is dropped either way.
+	 *
+	 * @example
+	 * api.events.on("document", (e) => {
+	 *   if (e.reason !== "open") return;
+	 *   const fixed = repair(api.document.sections.file());
+	 *   if (fixed) api.document.sections.replaceFile(fixed, { asOpened: true });
+	 * });
+	 */
+	asOpened?: boolean;
+}
 /**
  * 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
@@ -3007,8 +3046,11 @@ export interface SectionsApi {
 	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;
+	/**
+	 * Replace the whole CHK, the way File ▸ Open reads one. The map is marked modified,
+	 * unless `asOpened` says the bytes are a reading of the file as it was opened.
+	 */
+	replaceFile(bytes: Uint8Array, options?: ReplaceFileOptions): RawEditResult;
 	/**
 	 * The CHK inside a map file — an `.scx` / `.scm` archive's `staredit\scenario.chk`, or
 	 * the bytes themselves for a bare CHK — the way File ▸ Open reads it, for `replaceFile`.

package/package.json

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