electron-snapora 1.0.1

package/README.zh-CN.md

@@ -0,0 +1,79 @@
+# electron-snapora — Electron 截图与标注工具
+
+[English](https://github.com/electron-tools/electron-snapora/blob/main/README.md) | 简体中文 | [日本語](https://github.com/electron-tools/electron-snapora/blob/main/README.ja.md) | [한국어](https://github.com/electron-tools/electron-snapora/blob/main/README.ko.md) | [Español](https://github.com/electron-tools/electron-snapora/blob/main/README.es.md)
+
+为 Electron 应用增加区域截图、交互式选区、图片标注、剪贴板复制和 PNG 保存能力。
+
+## 功能
+
+- 矩形区域截图和交互式截图层。
+- 矩形、椭圆、箭头、画笔、文字和马赛克标注。
+- 撤销、重做、剪贴板复制和原生 PNG 保存。
+- 支持 TypeScript、ESM 和 CommonJS。
+- 默认不依赖原生扩展，也不需要安装后编译。
+
+## 快速开始
+
+环境要求：Node.js 20 或更高版本、Electron `>=42 <44`。
+
+### 1. 安装
+
+```bash
+npm install electron-snapora
+```
+
+请将它保留在应用的生产环境 `dependencies` 中。
+
+### 2. 配置主进程
+
+```ts
+import { app, BrowserWindow, ipcMain } from 'electron';
+import { setupElectronSnapora } from 'electron-snapora/main';
+
+app.whenReady().then(() => {
+  const snapora = setupElectronSnapora({ ipcMain });
+  const mainWindow = new BrowserWindow({
+    webPreferences: {
+      preload: snapora.preloadPath,
+      contextIsolation: true,
+      sandbox: true,
+    },
+  });
+
+  mainWindow.loadFile('index.html');
+  app.once('before-quit', snapora.unregister);
+});
+```
+
+### 3. 在 Renderer 中截图
+
+```ts
+const result = await window.electronSnapora.capture({ display: 'cursor' });
+
+if (result.status === 'completed') {
+  console.log(result.data, result.bounds, result.output);
+}
+```
+
+`result.data` 是 PNG 字节数据。用户取消时返回 `cancelled`，处理失败时返回 `failed`。
+
+## 已有 Preload 的应用
+
+在应用自己的 Preload 中暴露 API，并保持该 Preload 由宿主构建工具打包：
+
+```ts
+import { contextBridge, ipcRenderer } from 'electron';
+import { exposeScreenshotApi } from 'electron-snapora/preload';
+
+exposeScreenshotApi({ contextBridge, ipcRenderer });
+```
+
+## 打包说明
+
+打包 Electron 主进程时，请将 `electron-snapora` 保持为 external，并确保它位于生产环境依赖中，这样 Overlay HTML、CSS 和 Preload 文件才会随应用一起安装。
+
+主题、本地化、IPC 来源校验、并发队列、诊断和各类打包器配置请参阅[英文完整文档](https://github.com/electron-tools/electron-snapora/blob/main/README.md)。
+
+仓库：[github.com/electron-tools/electron-snapora](https://github.com/electron-tools/electron-snapora)
+
+许可证：[MIT](https://github.com/electron-tools/electron-snapora/blob/main/LICENSE)

package/dist/core/index.cjs

@@ -0,0 +1,184 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core.ts
+var core_exports = {};
+__export(core_exports, {
+  AddElementCommand: () => AddElementCommand,
+  CommandStack: () => CommandStack,
+  RemoveElementCommand: () => RemoveElementCommand,
+  UpdateElementCommand: () => UpdateElementCommand,
+  clampRect: () => clampRect,
+  isRectValid: () => isRectValid,
+  normalizeRect: () => normalizeRect,
+  viewportPointToImagePoint: () => viewportPointToImagePoint
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/core/geometry/rect.ts
+function normalizeRect(start, end) {
+  return {
+    x: Math.min(start.x, end.x),
+    y: Math.min(start.y, end.y),
+    width: Math.abs(end.x - start.x),
+    height: Math.abs(end.y - start.y)
+  };
+}
+function clampRect(rect, bounds) {
+  const left = Math.max(bounds.x, rect.x);
+  const top = Math.max(bounds.y, rect.y);
+  const right = Math.min(bounds.x + bounds.width, rect.x + rect.width);
+  const bottom = Math.min(bounds.y + bounds.height, rect.y + rect.height);
+  return {
+    x: left,
+    y: top,
+    width: Math.max(0, right - left),
+    height: Math.max(0, bottom - top)
+  };
+}
+function isRectValid(rect, minimumSize = 1) {
+  return rect.width >= minimumSize && rect.height >= minimumSize;
+}
+function viewportPointToImagePoint(point, viewportSize, imageSize) {
+  if (viewportSize.width <= 0 || viewportSize.height <= 0) {
+    throw new RangeError("Viewport dimensions must be greater than zero.");
+  }
+  return {
+    x: point.x * (imageSize.width / viewportSize.width),
+    y: point.y * (imageSize.height / viewportSize.height)
+  };
+}
+
+// src/core/history/command-stack.ts
+var CommandStack = class {
+  #undoStack = [];
+  #redoStack = [];
+  execute(command, document) {
+    const nextDocument = command.execute(document);
+    this.#undoStack.push(command);
+    this.#redoStack.length = 0;
+    return nextDocument;
+  }
+  undo(document) {
+    const command = this.#undoStack.pop();
+    if (!command) return document;
+    const previousDocument = command.undo(document);
+    this.#redoStack.push(command);
+    return previousDocument;
+  }
+  redo(document) {
+    const command = this.#redoStack.pop();
+    if (!command) return document;
+    const nextDocument = command.execute(document);
+    this.#undoStack.push(command);
+    return nextDocument;
+  }
+  clear() {
+    this.#undoStack.length = 0;
+    this.#redoStack.length = 0;
+  }
+  get canUndo() {
+    return this.#undoStack.length > 0;
+  }
+  get canRedo() {
+    return this.#redoStack.length > 0;
+  }
+};
+
+// src/core/history/document-commands.ts
+var AddElementCommand = class {
+  #element;
+  constructor(element) {
+    this.#element = element;
+  }
+  execute(document) {
+    if (document.elements.some((element) => element.id === this.#element.id)) {
+      return document;
+    }
+    return { ...document, elements: [...document.elements, this.#element] };
+  }
+  undo(document) {
+    return {
+      ...document,
+      elements: document.elements.filter((element) => element.id !== this.#element.id)
+    };
+  }
+};
+var UpdateElementCommand = class {
+  #before;
+  #after;
+  constructor(before, after) {
+    if (before.id !== after.id) {
+      throw new Error("An annotation update must preserve the element id.");
+    }
+    this.#before = before;
+    this.#after = after;
+  }
+  execute(document) {
+    return replaceElement(document, this.#after);
+  }
+  undo(document) {
+    return replaceElement(document, this.#before);
+  }
+};
+var RemoveElementCommand = class {
+  #element;
+  #index;
+  constructor(element, index) {
+    this.#element = element;
+    this.#index = index;
+  }
+  execute(document) {
+    return {
+      ...document,
+      elements: document.elements.filter((element) => element.id !== this.#element.id)
+    };
+  }
+  undo(document) {
+    if (document.elements.some((element) => element.id === this.#element.id)) {
+      return document;
+    }
+    const elements = [...document.elements];
+    elements.splice(Math.min(this.#index, elements.length), 0, this.#element);
+    return { ...document, elements };
+  }
+};
+function replaceElement(document, replacement) {
+  let found = false;
+  const elements = document.elements.map((element) => {
+    if (element.id !== replacement.id) {
+      return element;
+    }
+    found = true;
+    return replacement;
+  });
+  return found ? { ...document, elements } : document;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AddElementCommand,
+  CommandStack,
+  RemoveElementCommand,
+  UpdateElementCommand,
+  clampRect,
+  isRectValid,
+  normalizeRect,
+  viewportPointToImagePoint
+});
+//# sourceMappingURL=index.cjs.map

package/dist/core/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core.ts","../../src/core/geometry/rect.ts","../../src/core/history/command-stack.ts","../../src/core/history/document-commands.ts"],"sourcesContent":["export * from './core/index.js';\n","export interface Point {\n  x: number;\n  y: number;\n}\n\nexport interface Size {\n  width: number;\n  height: number;\n}\n\nexport type Rect = Point & Size;\n\nexport function normalizeRect(start: Point, end: Point): Rect {\n  return {\n    x: Math.min(start.x, end.x),\n    y: Math.min(start.y, end.y),\n    width: Math.abs(end.x - start.x),\n    height: Math.abs(end.y - start.y),\n  };\n}\n\nexport function clampRect(rect: Rect, bounds: Rect): Rect {\n  const left = Math.max(bounds.x, rect.x);\n  const top = Math.max(bounds.y, rect.y);\n  const right = Math.min(bounds.x + bounds.width, rect.x + rect.width);\n  const bottom = Math.min(bounds.y + bounds.height, rect.y + rect.height);\n\n  return {\n    x: left,\n    y: top,\n    width: Math.max(0, right - left),\n    height: Math.max(0, bottom - top),\n  };\n}\n\nexport function isRectValid(rect: Rect, minimumSize = 1): boolean {\n  return rect.width >= minimumSize && rect.height >= minimumSize;\n}\n\nexport function viewportPointToImagePoint(\n  point: Point,\n  viewportSize: Size,\n  imageSize: Size\n): Point {\n  if (viewportSize.width <= 0 || viewportSize.height <= 0) {\n    throw new RangeError('Viewport dimensions must be greater than zero.');\n  }\n\n  return {\n    x: point.x * (imageSize.width / viewportSize.width),\n    y: point.y * (imageSize.height / viewportSize.height),\n  };\n}\n","export interface ScreenshotCommand<TDocument> {\n  execute(document: TDocument): TDocument;\n  undo(document: TDocument): TDocument;\n}\n\nexport class CommandStack<TDocument> {\n  readonly #undoStack: ScreenshotCommand<TDocument>[] = [];\n  readonly #redoStack: ScreenshotCommand<TDocument>[] = [];\n\n  execute(command: ScreenshotCommand<TDocument>, document: TDocument): TDocument {\n    const nextDocument = command.execute(document);\n    this.#undoStack.push(command);\n    this.#redoStack.length = 0;\n    return nextDocument;\n  }\n\n  undo(document: TDocument): TDocument {\n    const command = this.#undoStack.pop();\n    if (!command) return document;\n\n    const previousDocument = command.undo(document);\n    this.#redoStack.push(command);\n    return previousDocument;\n  }\n\n  redo(document: TDocument): TDocument {\n    const command = this.#redoStack.pop();\n    if (!command) return document;\n\n    const nextDocument = command.execute(document);\n    this.#undoStack.push(command);\n    return nextDocument;\n  }\n\n  clear(): void {\n    this.#undoStack.length = 0;\n    this.#redoStack.length = 0;\n  }\n\n  get canUndo(): boolean {\n    return this.#undoStack.length > 0;\n  }\n\n  get canRedo(): boolean {\n    return this.#redoStack.length > 0;\n  }\n}\n","import type { AnnotationElement, ScreenshotDocument } from '../model/document.js';\nimport type { ScreenshotCommand } from './command-stack.js';\n\nexport class AddElementCommand implements ScreenshotCommand<ScreenshotDocument> {\n  readonly #element: AnnotationElement;\n\n  constructor(element: AnnotationElement) {\n    this.#element = element;\n  }\n\n  execute(document: ScreenshotDocument): ScreenshotDocument {\n    if (document.elements.some((element) => element.id === this.#element.id)) {\n      return document;\n    }\n\n    return { ...document, elements: [...document.elements, this.#element] };\n  }\n\n  undo(document: ScreenshotDocument): ScreenshotDocument {\n    return {\n      ...document,\n      elements: document.elements.filter((element) => element.id !== this.#element.id),\n    };\n  }\n}\n\nexport class UpdateElementCommand implements ScreenshotCommand<ScreenshotDocument> {\n  readonly #before: AnnotationElement;\n  readonly #after: AnnotationElement;\n\n  constructor(before: AnnotationElement, after: AnnotationElement) {\n    if (before.id !== after.id) {\n      throw new Error('An annotation update must preserve the element id.');\n    }\n    this.#before = before;\n    this.#after = after;\n  }\n\n  execute(document: ScreenshotDocument): ScreenshotDocument {\n    return replaceElement(document, this.#after);\n  }\n\n  undo(document: ScreenshotDocument): ScreenshotDocument {\n    return replaceElement(document, this.#before);\n  }\n}\n\nexport class RemoveElementCommand implements ScreenshotCommand<ScreenshotDocument> {\n  readonly #element: AnnotationElement;\n  readonly #index: number;\n\n  constructor(element: AnnotationElement, index: number) {\n    this.#element = element;\n    this.#index = index;\n  }\n\n  execute(document: ScreenshotDocument): ScreenshotDocument {\n    return {\n      ...document,\n      elements: document.elements.filter((element) => element.id !== this.#element.id),\n    };\n  }\n\n  undo(document: ScreenshotDocument): ScreenshotDocument {\n    if (document.elements.some((element) => element.id === this.#element.id)) {\n      return document;\n    }\n\n    const elements = [...document.elements];\n    elements.splice(Math.min(this.#index, elements.length), 0, this.#element);\n    return { ...document, elements };\n  }\n}\n\nfunction replaceElement(\n  document: ScreenshotDocument,\n  replacement: AnnotationElement\n): ScreenshotDocument {\n  let found = false;\n  const elements = document.elements.map((element) => {\n    if (element.id !== replacement.id) {\n      return element;\n    }\n    found = true;\n    return replacement;\n  });\n\n  return found ? { ...document, elements } : document;\n}\n"],"mappings":"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","names":[]}

package/dist/core/index.d.cts

@@ -0,0 +1,97 @@
+interface Point {
+    x: number;
+    y: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+type Rect = Point & Size;
+declare function normalizeRect(start: Point, end: Point): Rect;
+declare function clampRect(rect: Rect, bounds: Rect): Rect;
+declare function isRectValid(rect: Rect, minimumSize?: number): boolean;
+declare function viewportPointToImagePoint(point: Point, viewportSize: Size, imageSize: Size): Point;
+
+interface AnnotationElementBase {
+    id: string;
+    zIndex: number;
+    createdAt: number;
+    color: string;
+}
+interface RectangleElement extends AnnotationElementBase {
+    type: 'rectangle';
+    bounds: Rect;
+    lineWidth: number;
+}
+interface EllipseElement extends AnnotationElementBase {
+    type: 'ellipse';
+    bounds: Rect;
+    lineWidth: number;
+}
+interface ArrowElement extends AnnotationElementBase {
+    type: 'arrow';
+    start: Point;
+    end: Point;
+    lineWidth: number;
+}
+interface BrushElement extends AnnotationElementBase {
+    type: 'brush';
+    points: Point[];
+    lineWidth: number;
+}
+interface TextLayoutMetrics {
+    width: number;
+    ascent: number;
+    descent: number;
+}
+interface TextElement extends AnnotationElementBase {
+    type: 'text';
+    position: Point;
+    value: string;
+    fontSize: number;
+    metrics: TextLayoutMetrics;
+}
+interface MosaicElement extends AnnotationElementBase {
+    type: 'mosaic';
+    bounds: Rect;
+}
+type AnnotationElement = RectangleElement | EllipseElement | ArrowElement | BrushElement | TextElement | MosaicElement;
+interface ScreenshotDocument {
+    selection: Rect;
+    elements: AnnotationElement[];
+}
+
+interface ScreenshotCommand<TDocument> {
+    execute(document: TDocument): TDocument;
+    undo(document: TDocument): TDocument;
+}
+declare class CommandStack<TDocument> {
+    #private;
+    execute(command: ScreenshotCommand<TDocument>, document: TDocument): TDocument;
+    undo(document: TDocument): TDocument;
+    redo(document: TDocument): TDocument;
+    clear(): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+}
+
+declare class AddElementCommand implements ScreenshotCommand<ScreenshotDocument> {
+    #private;
+    constructor(element: AnnotationElement);
+    execute(document: ScreenshotDocument): ScreenshotDocument;
+    undo(document: ScreenshotDocument): ScreenshotDocument;
+}
+declare class UpdateElementCommand implements ScreenshotCommand<ScreenshotDocument> {
+    #private;
+    constructor(before: AnnotationElement, after: AnnotationElement);
+    execute(document: ScreenshotDocument): ScreenshotDocument;
+    undo(document: ScreenshotDocument): ScreenshotDocument;
+}
+declare class RemoveElementCommand implements ScreenshotCommand<ScreenshotDocument> {
+    #private;
+    constructor(element: AnnotationElement, index: number);
+    execute(document: ScreenshotDocument): ScreenshotDocument;
+    undo(document: ScreenshotDocument): ScreenshotDocument;
+}
+
+export { AddElementCommand, type AnnotationElement, type ArrowElement, type BrushElement, CommandStack, type EllipseElement, type MosaicElement, type Point, type Rect, type RectangleElement, RemoveElementCommand, type ScreenshotCommand, type ScreenshotDocument, type Size, type TextElement, type TextLayoutMetrics, UpdateElementCommand, clampRect, isRectValid, normalizeRect, viewportPointToImagePoint };

package/dist/core/index.d.ts

@@ -0,0 +1,97 @@
+interface Point {
+    x: number;
+    y: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+type Rect = Point & Size;
+declare function normalizeRect(start: Point, end: Point): Rect;
+declare function clampRect(rect: Rect, bounds: Rect): Rect;
+declare function isRectValid(rect: Rect, minimumSize?: number): boolean;
+declare function viewportPointToImagePoint(point: Point, viewportSize: Size, imageSize: Size): Point;
+
+interface AnnotationElementBase {
+    id: string;
+    zIndex: number;
+    createdAt: number;
+    color: string;
+}
+interface RectangleElement extends AnnotationElementBase {
+    type: 'rectangle';
+    bounds: Rect;
+    lineWidth: number;
+}
+interface EllipseElement extends AnnotationElementBase {
+    type: 'ellipse';
+    bounds: Rect;
+    lineWidth: number;
+}
+interface ArrowElement extends AnnotationElementBase {
+    type: 'arrow';
+    start: Point;
+    end: Point;
+    lineWidth: number;
+}
+interface BrushElement extends AnnotationElementBase {
+    type: 'brush';
+    points: Point[];
+    lineWidth: number;
+}
+interface TextLayoutMetrics {
+    width: number;
+    ascent: number;
+    descent: number;
+}
+interface TextElement extends AnnotationElementBase {
+    type: 'text';
+    position: Point;
+    value: string;
+    fontSize: number;
+    metrics: TextLayoutMetrics;
+}
+interface MosaicElement extends AnnotationElementBase {
+    type: 'mosaic';
+    bounds: Rect;
+}
+type AnnotationElement = RectangleElement | EllipseElement | ArrowElement | BrushElement | TextElement | MosaicElement;
+interface ScreenshotDocument {
+    selection: Rect;
+    elements: AnnotationElement[];
+}
+
+interface ScreenshotCommand<TDocument> {
+    execute(document: TDocument): TDocument;
+    undo(document: TDocument): TDocument;
+}
+declare class CommandStack<TDocument> {
+    #private;
+    execute(command: ScreenshotCommand<TDocument>, document: TDocument): TDocument;
+    undo(document: TDocument): TDocument;
+    redo(document: TDocument): TDocument;
+    clear(): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+}
+
+declare class AddElementCommand implements ScreenshotCommand<ScreenshotDocument> {
+    #private;
+    constructor(element: AnnotationElement);
+    execute(document: ScreenshotDocument): ScreenshotDocument;
+    undo(document: ScreenshotDocument): ScreenshotDocument;
+}
+declare class UpdateElementCommand implements ScreenshotCommand<ScreenshotDocument> {
+    #private;
+    constructor(before: AnnotationElement, after: AnnotationElement);
+    execute(document: ScreenshotDocument): ScreenshotDocument;
+    undo(document: ScreenshotDocument): ScreenshotDocument;
+}
+declare class RemoveElementCommand implements ScreenshotCommand<ScreenshotDocument> {
+    #private;
+    constructor(element: AnnotationElement, index: number);
+    execute(document: ScreenshotDocument): ScreenshotDocument;
+    undo(document: ScreenshotDocument): ScreenshotDocument;
+}
+
+export { AddElementCommand, type AnnotationElement, type ArrowElement, type BrushElement, CommandStack, type EllipseElement, type MosaicElement, type Point, type Rect, type RectangleElement, RemoveElementCommand, type ScreenshotCommand, type ScreenshotDocument, type Size, type TextElement, type TextLayoutMetrics, UpdateElementCommand, clampRect, isRectValid, normalizeRect, viewportPointToImagePoint };

package/dist/core/index.mjs

@@ -0,0 +1,150 @@
+// src/core/geometry/rect.ts
+function normalizeRect(start, end) {
+  return {
+    x: Math.min(start.x, end.x),
+    y: Math.min(start.y, end.y),
+    width: Math.abs(end.x - start.x),
+    height: Math.abs(end.y - start.y)
+  };
+}
+function clampRect(rect, bounds) {
+  const left = Math.max(bounds.x, rect.x);
+  const top = Math.max(bounds.y, rect.y);
+  const right = Math.min(bounds.x + bounds.width, rect.x + rect.width);
+  const bottom = Math.min(bounds.y + bounds.height, rect.y + rect.height);
+  return {
+    x: left,
+    y: top,
+    width: Math.max(0, right - left),
+    height: Math.max(0, bottom - top)
+  };
+}
+function isRectValid(rect, minimumSize = 1) {
+  return rect.width >= minimumSize && rect.height >= minimumSize;
+}
+function viewportPointToImagePoint(point, viewportSize, imageSize) {
+  if (viewportSize.width <= 0 || viewportSize.height <= 0) {
+    throw new RangeError("Viewport dimensions must be greater than zero.");
+  }
+  return {
+    x: point.x * (imageSize.width / viewportSize.width),
+    y: point.y * (imageSize.height / viewportSize.height)
+  };
+}
+
+// src/core/history/command-stack.ts
+var CommandStack = class {
+  #undoStack = [];
+  #redoStack = [];
+  execute(command, document) {
+    const nextDocument = command.execute(document);
+    this.#undoStack.push(command);
+    this.#redoStack.length = 0;
+    return nextDocument;
+  }
+  undo(document) {
+    const command = this.#undoStack.pop();
+    if (!command) return document;
+    const previousDocument = command.undo(document);
+    this.#redoStack.push(command);
+    return previousDocument;
+  }
+  redo(document) {
+    const command = this.#redoStack.pop();
+    if (!command) return document;
+    const nextDocument = command.execute(document);
+    this.#undoStack.push(command);
+    return nextDocument;
+  }
+  clear() {
+    this.#undoStack.length = 0;
+    this.#redoStack.length = 0;
+  }
+  get canUndo() {
+    return this.#undoStack.length > 0;
+  }
+  get canRedo() {
+    return this.#redoStack.length > 0;
+  }
+};
+
+// src/core/history/document-commands.ts
+var AddElementCommand = class {
+  #element;
+  constructor(element) {
+    this.#element = element;
+  }
+  execute(document) {
+    if (document.elements.some((element) => element.id === this.#element.id)) {
+      return document;
+    }
+    return { ...document, elements: [...document.elements, this.#element] };
+  }
+  undo(document) {
+    return {
+      ...document,
+      elements: document.elements.filter((element) => element.id !== this.#element.id)
+    };
+  }
+};
+var UpdateElementCommand = class {
+  #before;
+  #after;
+  constructor(before, after) {
+    if (before.id !== after.id) {
+      throw new Error("An annotation update must preserve the element id.");
+    }
+    this.#before = before;
+    this.#after = after;
+  }
+  execute(document) {
+    return replaceElement(document, this.#after);
+  }
+  undo(document) {
+    return replaceElement(document, this.#before);
+  }
+};
+var RemoveElementCommand = class {
+  #element;
+  #index;
+  constructor(element, index) {
+    this.#element = element;
+    this.#index = index;
+  }
+  execute(document) {
+    return {
+      ...document,
+      elements: document.elements.filter((element) => element.id !== this.#element.id)
+    };
+  }
+  undo(document) {
+    if (document.elements.some((element) => element.id === this.#element.id)) {
+      return document;
+    }
+    const elements = [...document.elements];
+    elements.splice(Math.min(this.#index, elements.length), 0, this.#element);
+    return { ...document, elements };
+  }
+};
+function replaceElement(document, replacement) {
+  let found = false;
+  const elements = document.elements.map((element) => {
+    if (element.id !== replacement.id) {
+      return element;
+    }
+    found = true;
+    return replacement;
+  });
+  return found ? { ...document, elements } : document;
+}
+export {
+  AddElementCommand,
+  CommandStack,
+  RemoveElementCommand,
+  UpdateElementCommand,
+  clampRect,
+  isRectValid,
+  normalizeRect,
+  viewportPointToImagePoint
+};
+//# sourceMappingURL=index.mjs.map

package/dist/core/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/geometry/rect.ts","../../src/core/history/command-stack.ts","../../src/core/history/document-commands.ts"],"sourcesContent":["export interface Point {\n  x: number;\n  y: number;\n}\n\nexport interface Size {\n  width: number;\n  height: number;\n}\n\nexport type Rect = Point & Size;\n\nexport function normalizeRect(start: Point, end: Point): Rect {\n  return {\n    x: Math.min(start.x, end.x),\n    y: Math.min(start.y, end.y),\n    width: Math.abs(end.x - start.x),\n    height: Math.abs(end.y - start.y),\n  };\n}\n\nexport function clampRect(rect: Rect, bounds: Rect): Rect {\n  const left = Math.max(bounds.x, rect.x);\n  const top = Math.max(bounds.y, rect.y);\n  const right = Math.min(bounds.x + bounds.width, rect.x + rect.width);\n  const bottom = Math.min(bounds.y + bounds.height, rect.y + rect.height);\n\n  return {\n    x: left,\n    y: top,\n    width: Math.max(0, right - left),\n    height: Math.max(0, bottom - top),\n  };\n}\n\nexport function isRectValid(rect: Rect, minimumSize = 1): boolean {\n  return rect.width >= minimumSize && rect.height >= minimumSize;\n}\n\nexport function viewportPointToImagePoint(\n  point: Point,\n  viewportSize: Size,\n  imageSize: Size\n): Point {\n  if (viewportSize.width <= 0 || viewportSize.height <= 0) {\n    throw new RangeError('Viewport dimensions must be greater than zero.');\n  }\n\n  return {\n    x: point.x * (imageSize.width / viewportSize.width),\n    y: point.y * (imageSize.height / viewportSize.height),\n  };\n}\n","export interface ScreenshotCommand<TDocument> {\n  execute(document: TDocument): TDocument;\n  undo(document: TDocument): TDocument;\n}\n\nexport class CommandStack<TDocument> {\n  readonly #undoStack: ScreenshotCommand<TDocument>[] = [];\n  readonly #redoStack: ScreenshotCommand<TDocument>[] = [];\n\n  execute(command: ScreenshotCommand<TDocument>, document: TDocument): TDocument {\n    const nextDocument = command.execute(document);\n    this.#undoStack.push(command);\n    this.#redoStack.length = 0;\n    return nextDocument;\n  }\n\n  undo(document: TDocument): TDocument {\n    const command = this.#undoStack.pop();\n    if (!command) return document;\n\n    const previousDocument = command.undo(document);\n    this.#redoStack.push(command);\n    return previousDocument;\n  }\n\n  redo(document: TDocument): TDocument {\n    const command = this.#redoStack.pop();\n    if (!command) return document;\n\n    const nextDocument = command.execute(document);\n    this.#undoStack.push(command);\n    return nextDocument;\n  }\n\n  clear(): void {\n    this.#undoStack.length = 0;\n    this.#redoStack.length = 0;\n  }\n\n  get canUndo(): boolean {\n    return this.#undoStack.length > 0;\n  }\n\n  get canRedo(): boolean {\n    return this.#redoStack.length > 0;\n  }\n}\n","import type { AnnotationElement, ScreenshotDocument } from '../model/document.js';\nimport type { ScreenshotCommand } from './command-stack.js';\n\nexport class AddElementCommand implements ScreenshotCommand<ScreenshotDocument> {\n  readonly #element: AnnotationElement;\n\n  constructor(element: AnnotationElement) {\n    this.#element = element;\n  }\n\n  execute(document: ScreenshotDocument): ScreenshotDocument {\n    if (document.elements.some((element) => element.id === this.#element.id)) {\n      return document;\n    }\n\n    return { ...document, elements: [...document.elements, this.#element] };\n  }\n\n  undo(document: ScreenshotDocument): ScreenshotDocument {\n    return {\n      ...document,\n      elements: document.elements.filter((element) => element.id !== this.#element.id),\n    };\n  }\n}\n\nexport class UpdateElementCommand implements ScreenshotCommand<ScreenshotDocument> {\n  readonly #before: AnnotationElement;\n  readonly #after: AnnotationElement;\n\n  constructor(before: AnnotationElement, after: AnnotationElement) {\n    if (before.id !== after.id) {\n      throw new Error('An annotation update must preserve the element id.');\n    }\n    this.#before = before;\n    this.#after = after;\n  }\n\n  execute(document: ScreenshotDocument): ScreenshotDocument {\n    return replaceElement(document, this.#after);\n  }\n\n  undo(document: ScreenshotDocument): ScreenshotDocument {\n    return replaceElement(document, this.#before);\n  }\n}\n\nexport class RemoveElementCommand implements ScreenshotCommand<ScreenshotDocument> {\n  readonly #element: AnnotationElement;\n  readonly #index: number;\n\n  constructor(element: AnnotationElement, index: number) {\n    this.#element = element;\n    this.#index = index;\n  }\n\n  execute(document: ScreenshotDocument): ScreenshotDocument {\n    return {\n      ...document,\n      elements: document.elements.filter((element) => element.id !== this.#element.id),\n    };\n  }\n\n  undo(document: ScreenshotDocument): ScreenshotDocument {\n    if (document.elements.some((element) => element.id === this.#element.id)) {\n      return document;\n    }\n\n    const elements = [...document.elements];\n    elements.splice(Math.min(this.#index, elements.length), 0, this.#element);\n    return { ...document, elements };\n  }\n}\n\nfunction replaceElement(\n  document: ScreenshotDocument,\n  replacement: AnnotationElement\n): ScreenshotDocument {\n  let found = false;\n  const elements = document.elements.map((element) => {\n    if (element.id !== replacement.id) {\n      return element;\n    }\n    found = true;\n    return replacement;\n  });\n\n  return found ? { ...document, elements } : document;\n}\n"],"mappings":"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","names":[]}