@pptx-glimpse/editor 0.1.0 → 0.2.0

package/README.md

@@ -1,66 +1,144 @@
 # @pptx-glimpse/editor
 
-UI framework に依存しない `PptxSourceModel` の編集層です。`@pptx-glimpse/document`
-で PPTX を読み書きし、この package で command の検証・適用、selection、undo / redo、
-warning の取得を行います。
+[![npm version](https://img.shields.io/npm/v/%40pptx-glimpse%2Feditor)](https://www.npmjs.com/package/@pptx-glimpse/editor)
+[![CI](https://github.com/hirokisakabe/pptx-glimpse/actions/workflows/ci.yml/badge.svg)](https://github.com/hirokisakabe/pptx-glimpse/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/hirokisakabe/pptx-glimpse/blob/main/LICENSE)
 
-`@pptx-glimpse/editor` は 0.x です。API は独立して利用できますが、command と結果型は
-1.0 までに変更される可能性があります。
+The public, headless editing layer for `PptxSourceModel`. It applies validated commands and manages
+selection and undo/redo history without depending on a DOM, UI framework, or renderer.
 
-## インストール
+This package is published on npm. Install it together with its document-layer dependency so both
+packages are direct dependencies of your application:
 
-```sh
+```bash
 npm install @pptx-glimpse/document @pptx-glimpse/editor
 ```
 
-## 最小例
+## Quick start
 
 ```ts
+import { readFile, writeFile } from "node:fs/promises";
 import { readPptx, writePptx } from "@pptx-glimpse/document";
 import { createEditorSession } from "@pptx-glimpse/editor";
 
-const source = readPptx(input);
-const run = source.slides[0]?.shapes
-  .find((shape) => shape.kind === "shape")
-  ?.textBody?.paragraphs[0]?.runs[0];
+const source = readPptx(await readFile("input.pptx"));
+const run = source.slides[0]?.shapes.find((shape) => shape.kind === "shape")?.textBody
+  ?.paragraphs[0]?.runs[0];
 
-if (run?.handle === undefined) {
-  throw new Error("editable text run not found");
+if (run === undefined) {
+  throw new Error("No editable text run found");
 }
 
 const session = createEditorSession(source);
-const result = session.apply({
-  kind: "replaceTextRunPlainText",
-  handle: run.handle,
-  text: "Edited",
-});
+const result = session.replaceTextRunPlainText(run, "Edited");
+
+if (!result.ok) {
+  throw new Error(`${result.code}: ${result.message}`, { cause: result.cause });
+}
+
+for (const warning of result.warnings ?? []) {
+  console.warn(warning.code, warning.message);
+}
+
+await writeFile("edited.pptx", writePptx(session.document));
+```
+
+## Source-node methods, commands, history, and selection
+
+For ordinary edits, pass source nodes directly to the corresponding `EditorSession` convenience
+method. Text-run and paragraph methods replace plain text or set/clear properties. Shape methods
+move, resize, transform, style, or delete a `SourceShapeNode`; `replaceImage()` accepts a
+`SourceImage`; slide topology methods accept a `SourceSlide`. `addTextBox()` and `addConnector()`
+also accept the target `SourceSlide`, so application code does not need to extract source handles.
+Nodes captured before earlier edits remain usable because the session resolves their stable handle
+against its current document.
+
+Every convenience method creates and applies the matching command through the same validation,
+warning, selection-reconciliation, and undo/redo-history path. A successful convenience-method
+call that changes the document creates one undo-history entry.
+
+Use `session.apply(command)` when commands need to be stored, logged, transported by UI code, or
+constructed independently of a source-node object. Use `session.applyAll(commands)` to apply
+multiple operations atomically as one undo-history entry; convenience methods are single-operation
+calls and cannot be grouped into one history entry by calling them sequentially. Failed validation
+returns an `invalid-command` result without changing the document.
+
+The released command set includes:
+
+- Text: `replaceTextRunPlainText`, `replaceParagraphPlainText`, `setTextRunProperties`,
+  `clearTextRunProperties`, `setParagraphProperties`, and `clearParagraphProperties`.
+- Shapes: `moveShape`, `resizeShape`, `setShapeTransform`, `setShapeFill`, `setShapeOutline`,
+  `addTextBox`, `addConnector`, and `deleteShape`.
+- Media: `replaceImage`.
+- Slides: `addEmptySlideFromLayout`, `duplicateSlide`, `moveSlide`, and `deleteSlide`.
+
+Use `undo()`, `redo()`, `canUndo`, `canRedo`, `undoDepth`, and `redoDepth` to integrate history.
+`selectShape(handle)` and `deselectShape()` manage a single shape selection. Selection is reconciled
+after commands and history changes, and is cleared if its shape no longer exists.
+
+## Operation failures and warnings
+
+Expected failures do not throw. `apply()` / `applyAll()`, `selectShape()`, `undo()`, and `redo()`
+return a discriminated result with the shared `EditorOperationFailure` shape:
+
+```ts
+const result = session.undo();
 if (!result.ok) {
-  throw new Error(result.message);
+  switch (result.code) {
+    case "empty-undo-stack":
+      // Disable or ignore the undo action.
+      break;
+    default:
+      console.error(result.message, result.cause);
+  }
 }
+```
 
-const output = writePptx(session.document);
+The operation codes are `invalid-command`, `invalid-selection`, `empty-undo-stack`, and
+`empty-redo-stack`. Unexpected programmer errors and invariant violations still throw.
+
+Warnings describe successful operations and remain on the success result:
+
+```ts
+const result = session.apply(replaceImageCommand);
+if (result.ok) {
+  for (const warning of result.warnings ?? []) {
+    if (warning.code === "shared-media-part") {
+      console.warn(warning.message);
+    }
+  }
+}
 ```
 
-複数 command は `session.applyAll(commands)` で一つの undo 履歴として適用できます。
-`selectShape()` / `deselectShape()`、`undo()` / `redo()`、`canUndo` / `canRedo` も
-session から利用できます。
-
-## 対応 command
-
-- text: `replaceTextRunPlainText`, `replaceParagraphPlainText`,
-  `setTextRunProperties`, `clearTextRunProperties`, `setParagraphProperties`,
-  `clearParagraphProperties`
-- shape: `moveShape`, `resizeShape`, `setShapeTransform`, `setShapeFill`,
-  `setShapeOutline`, `addTextBox`, `addConnector`, `deleteShape`
-- media: `replaceImage`
-- slide: `addEmptySlideFromLayout`, `duplicateSlide`, `moveSlide`, `deleteSlide`
-
-## 既知の制約
-
-- source handle がない要素や、document 層が安全に保持できない編集は
-  `invalid-command` として拒否されます。
-- table、chart、SmartArt の新規編集 command はありません。
-- `replaceImage` が共有 media part を更新する場合、参照する複数画像が同時に変わるため
-  `shared-media-part` warning を返します。
-- DOM、React、ProseMirror、renderer は含みません。描画を伴う browser editor facade は
-  `pptx-glimpse` の browser entry を利用してください。
+## Package boundary
+
+Use [`pptx-glimpse`](https://github.com/hirokisakabe/pptx-glimpse/blob/main/packages/core/README.md)
+when you want high-level rendering plus an edit/rerender/save session. Use
+[`@pptx-glimpse/document`](https://github.com/hirokisakabe/pptx-glimpse/blob/main/packages/document/README.md)
+directly for source/computed document semantics, authoring, immutable editing operations, and
+writing without session state.
+
+`@pptx-glimpse/editor` adds command validation, selection, warnings, and history to the document
+model. It does not include React, ProseMirror, a DOM UI, SVG/PNG rendering, or file I/O. Import
+supported APIs from the package root; deep source and `dist` paths are internal.
+
+## Runtime support, stability, and limitations
+
+- Node.js 22 or later is supported.
+- Browser bundlers can use the same byte- and model-oriented APIs; the package has no DOM or
+  Node.js filesystem dependency.
+- `@pptx-glimpse/editor` is a `0.x` package. Commands and result types may change before `1.0.0`.
+- Elements without source handles, and edits the document layer cannot safely preserve, are
+  rejected as `invalid-command`.
+- New table, chart, and SmartArt editing commands are not available.
+- Replacing a shared media part can change multiple image references and returns a
+  `shared-media-part` warning.
+- Expected operation rejection uses the exported `EditorOperationErrorCode` and
+  `EditorOperationFailure` contract.
+
+See the [project README](https://github.com/hirokisakabe/pptx-glimpse#readme) for package selection
+and the demo.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -66,50 +66,198 @@ var EditorSession = class {
   deselectShape() {
     this.#selection = void 0;
   }
+  replaceTextRunPlainText(run, text) {
+    return this.applyToSourceNode(
+      "replaceTextRunPlainText",
+      run,
+      isSourceTextRun,
+      import_document.findTextRunBySourceHandle,
+      (handle) => ({ kind: "replaceTextRunPlainText", handle, text })
+    );
+  }
+  replaceParagraphPlainText(paragraph, text) {
+    return this.applyToSourceNode(
+      "replaceParagraphPlainText",
+      paragraph,
+      isSourceParagraph,
+      import_document.findParagraphBySourceHandle,
+      (handle) => ({ kind: "replaceParagraphPlainText", handle, text })
+    );
+  }
+  setTextRunProperties(run, properties) {
+    return this.applyToSourceNode(
+      "setTextRunProperties",
+      run,
+      isSourceTextRun,
+      import_document.findTextRunBySourceHandle,
+      (handle) => ({ kind: "setTextRunProperties", handle, properties })
+    );
+  }
+  clearTextRunProperties(run, properties) {
+    return this.applyToSourceNode(
+      "clearTextRunProperties",
+      run,
+      isSourceTextRun,
+      import_document.findTextRunBySourceHandle,
+      (handle) => ({ kind: "clearTextRunProperties", handle, properties })
+    );
+  }
+  setParagraphProperties(paragraph, properties) {
+    return this.applyToSourceNode(
+      "setParagraphProperties",
+      paragraph,
+      isSourceParagraph,
+      import_document.findParagraphBySourceHandle,
+      (handle) => ({ kind: "setParagraphProperties", handle, properties })
+    );
+  }
+  clearParagraphProperties(paragraph, properties) {
+    return this.applyToSourceNode(
+      "clearParagraphProperties",
+      paragraph,
+      isSourceParagraph,
+      import_document.findParagraphBySourceHandle,
+      (handle) => ({ kind: "clearParagraphProperties", handle, properties })
+    );
+  }
+  moveShape(shape, offsetX, offsetY) {
+    return this.applyToShapeNode("moveShape", shape, (handle) => ({
+      kind: "moveShape",
+      handle,
+      offsetX,
+      offsetY
+    }));
+  }
+  resizeShape(shape, width, height) {
+    return this.applyToShapeNode("resizeShape", shape, (handle) => ({
+      kind: "resizeShape",
+      handle,
+      width,
+      height
+    }));
+  }
+  setShapeTransform(shape, transform) {
+    return this.applyToShapeNode("setShapeTransform", shape, (handle) => ({
+      kind: "setShapeTransform",
+      handle,
+      ...transform
+    }));
+  }
+  setShapeFill(shape, fill) {
+    return this.applyToShapeNode("setShapeFill", shape, (handle) => ({
+      kind: "setShapeFill",
+      handle,
+      fill
+    }));
+  }
+  setShapeOutline(shape, outline) {
+    return this.applyToShapeNode("setShapeOutline", shape, (handle) => ({
+      kind: "setShapeOutline",
+      handle,
+      outline
+    }));
+  }
+  addTextBox(slide, input) {
+    return this.applyToSlide("addTextBox", slide, (slideHandle) => ({
+      kind: "addTextBox",
+      slideHandle,
+      ...input
+    }));
+  }
+  addConnector(slide, input) {
+    return this.applyToSlide("addConnector", slide, (slideHandle) => ({
+      kind: "addConnector",
+      slideHandle,
+      ...input
+    }));
+  }
+  deleteShape(shape) {
+    return this.applyToShapeNode("deleteShape", shape, (handle) => ({
+      kind: "deleteShape",
+      handle
+    }));
+  }
+  replaceImage(image, bytes) {
+    return this.applyToSourceNode(
+      "replaceImage",
+      image,
+      isSourceImage,
+      (document, handle) => {
+        const shape = (0, import_document.findShapeNodeBySourceHandle)(document, handle);
+        return shape?.kind === "image" ? shape : void 0;
+      },
+      (handle) => ({ kind: "replaceImage", handle, bytes })
+    );
+  }
+  addEmptySlideFromLayout(input) {
+    return this.apply({ kind: "addEmptySlideFromLayout", ...input });
+  }
+  duplicateSlide(slide) {
+    return this.applyToSlide("duplicateSlide", slide, (handle) => ({
+      kind: "duplicateSlide",
+      handle
+    }));
+  }
+  moveSlide(slide, input) {
+    return this.applyToSlide("moveSlide", slide, (handle) => ({
+      kind: "moveSlide",
+      handle,
+      ...input
+    }));
+  }
+  deleteSlide(slide) {
+    return this.applyToSlide("deleteSlide", slide, (handle) => ({
+      kind: "deleteSlide",
+      handle
+    }));
+  }
   apply(command) {
     return this.applyAll([command]);
   }
   applyAll(commands) {
     const before = this.#document;
     if (commands.length === 0) return { ok: true, document: before };
+    let after = before;
+    const warnings = [];
+    for (const command of commands) {
+      const result = applyCommandToDocument(after, command);
+      if (!result.ok) return result;
+      after = result.document;
+      warnings.push(...collectCommandWarnings(after, [command]));
+    }
     try {
-      let after = before;
-      const warnings = [];
-      for (const command of commands) {
-        after = applyCommandToDocument(after, command);
-        warnings.push(...collectCommandWarnings(after, [command]));
-      }
       assertNoConflictingParagraphAndRunEdits(after.edits);
-      after = normalizeEditorEdits(after);
-      const dedupedWarnings = dedupeCommandWarnings(warnings);
-      if (after === before) {
-        return {
-          ok: true,
-          document: before,
-          ...dedupedWarnings.length > 0 ? { warnings: dedupedWarnings } : {}
-        };
-      }
-      this.#document = after;
-      this.reconcileSelectionAfterDocumentChange();
-      this.#undoStack.push({ before, after });
-      this.#redoStack.length = 0;
+    } catch (cause) {
+      return invalidCommandFailure(cause);
+    }
+    after = normalizeEditorEdits(after);
+    const dedupedWarnings = dedupeCommandWarnings(warnings);
+    if (after === before) {
       return {
         ok: true,
-        document: after,
+        document: before,
         ...dedupedWarnings.length > 0 ? { warnings: dedupedWarnings } : {}
       };
-    } catch (error) {
-      return {
-        ok: false,
-        code: "invalid-command",
-        message: error instanceof Error ? error.message : "Editor command was rejected.",
-        cause: error
-      };
     }
+    this.#document = after;
+    this.reconcileSelectionAfterDocumentChange();
+    this.#undoStack.push({ before, after });
+    this.#redoStack.length = 0;
+    return {
+      ok: true,
+      document: after,
+      ...dedupedWarnings.length > 0 ? { warnings: dedupedWarnings } : {}
+    };
   }
   undo() {
     const entry = this.#undoStack.pop();
-    if (entry === void 0) return { ok: false, reason: "empty-undo-stack" };
+    if (entry === void 0) {
+      return {
+        ok: false,
+        code: "empty-undo-stack",
+        message: "undo: undo history is empty"
+      };
+    }
     this.#document = entry.before;
     this.reconcileSelectionAfterDocumentChange();
     this.#redoStack.push(entry);
@@ -117,7 +265,13 @@ var EditorSession = class {
   }
   redo() {
     const entry = this.#redoStack.pop();
-    if (entry === void 0) return { ok: false, reason: "empty-redo-stack" };
+    if (entry === void 0) {
+      return {
+        ok: false,
+        code: "empty-redo-stack",
+        message: "redo: redo history is empty"
+      };
+    }
     this.#document = entry.after;
     this.reconcileSelectionAfterDocumentChange();
     this.#undoStack.push(entry);
@@ -129,11 +283,172 @@ var EditorSession = class {
       this.#selection = void 0;
     }
   }
+  applyToShapeNode(operation, shape, createCommand) {
+    return this.applyToSourceNode(
+      operation,
+      shape,
+      isSourceShapeNode,
+      import_document.findShapeNodeBySourceHandle,
+      createCommand
+    );
+  }
+  applyToSlide(operation, slide, createCommand) {
+    return this.applyToSourceNode(
+      operation,
+      slide,
+      isSourceSlide,
+      (document, handle) => document.slides.find((candidate) => sourceHandlesEqual(candidate.handle, handle)),
+      createCommand
+    );
+  }
+  applyToSourceNode(operation, node, isExpectedNode, findCurrentNode, createCommand) {
+    if (!isExpectedNode(node)) {
+      return invalidSourceNodeFailure(operation, "source node has the wrong target type");
+    }
+    if (node.handle === void 0) {
+      return invalidSourceNodeFailure(operation, "source node does not have a handle");
+    }
+    if (findCurrentNode(this.#document, node.handle) === void 0) {
+      return invalidSourceNodeFailure(
+        operation,
+        "source node handle was not found in the current EditorSession document"
+      );
+    }
+    return this.apply(createCommand(node.handle));
+  }
 };
 function createEditorSession(document) {
   return new EditorSession(document);
 }
+var EDITOR_COMMAND_KINDS = /* @__PURE__ */ new Set([
+  "replaceTextRunPlainText",
+  "replaceParagraphPlainText",
+  "setTextRunProperties",
+  "clearTextRunProperties",
+  "setParagraphProperties",
+  "clearParagraphProperties",
+  "moveShape",
+  "resizeShape",
+  "setShapeTransform",
+  "setShapeFill",
+  "setShapeOutline",
+  "addTextBox",
+  "addConnector",
+  "deleteShape",
+  "replaceImage",
+  "addEmptySlideFromLayout",
+  "duplicateSlide",
+  "moveSlide",
+  "deleteSlide"
+]);
+var EXPECTED_COMMAND_REJECTION_PREFIXES = [
+  "replaceTextRunPlainText:",
+  "replaceParagraphPlainText:",
+  "setTextRunProperties:",
+  "clearTextRunProperties:",
+  "setParagraphProperties:",
+  "clearParagraphProperties:",
+  "moveShape:",
+  "resizeShape:",
+  "setShapeTransform:",
+  "setShapeFill:",
+  "setShapeOutline:",
+  "addTextBox:",
+  "addConnector:",
+  "deleteShape:",
+  "replaceImageBytes:",
+  "addEmptySlideFromLayout:",
+  "duplicateSlide:",
+  "moveSlide:",
+  "deleteSlide:",
+  "updateTextRunProperties:",
+  "updateParagraphProperties:",
+  "updateShapeTransform:"
+];
 function applyCommandToDocument(document, command) {
+  if (!EDITOR_COMMAND_KINDS.has(command.kind)) {
+    throw new TypeError(`EditorSession: unsupported command kind '${String(command.kind)}'`);
+  }
+  switch (command.kind) {
+    case "replaceTextRunPlainText":
+    case "replaceParagraphPlainText":
+    case "setTextRunProperties":
+    case "clearTextRunProperties":
+    case "setParagraphProperties":
+    case "clearParagraphProperties":
+    case "moveShape":
+    case "resizeShape":
+    case "setShapeTransform":
+    case "setShapeFill":
+    case "setShapeOutline":
+    case "addTextBox":
+    case "addConnector":
+    case "deleteShape":
+    case "replaceImage":
+    case "addEmptySlideFromLayout":
+    case "duplicateSlide":
+    case "moveSlide":
+    case "deleteSlide":
+      return attemptCommand(() => executeCommand(document, command));
+  }
+}
+function attemptCommand(operation) {
+  try {
+    return { ok: true, document: operation() };
+  } catch (cause) {
+    return invalidCommandFailure(cause);
+  }
+}
+function invalidCommandFailure(cause) {
+  if (!(cause instanceof Error) || !EXPECTED_COMMAND_REJECTION_PREFIXES.some((prefix) => cause.message.startsWith(prefix))) {
+    throw cause;
+  }
+  return {
+    ok: false,
+    code: "invalid-command",
+    message: cause.message,
+    cause
+  };
+}
+function invalidSourceNodeFailure(operation, reason) {
+  return {
+    ok: false,
+    code: "invalid-command",
+    message: `${operation}: ${reason}`
+  };
+}
+function isSourceTextRun(value) {
+  return isObject(value) && value.kind === "textRun";
+}
+function isSourceParagraph(value) {
+  return isObject(value) && Array.isArray(value.runs);
+}
+var SOURCE_SHAPE_NODE_KINDS = /* @__PURE__ */ new Set([
+  "shape",
+  "connector",
+  "group",
+  "image",
+  "table",
+  "chart",
+  "smartArt",
+  "raw"
+]);
+function isSourceShapeNode(value) {
+  return isObject(value) && typeof value.kind === "string" && SOURCE_SHAPE_NODE_KINDS.has(value.kind);
+}
+function isSourceImage(value) {
+  return isObject(value) && value.kind === "image";
+}
+function isSourceSlide(value) {
+  return isObject(value) && typeof value.partPath === "string" && typeof value.layoutPartPath === "string" && Array.isArray(value.shapes);
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function sourceHandlesEqual(left, right) {
+  return left !== void 0 && left.partPath === right.partPath && left.nodeId === right.nodeId && left.relationshipId === right.relationshipId && left.orderingSlot === right.orderingSlot;
+}
+function executeCommand(document, command) {
   switch (command.kind) {
     case "replaceTextRunPlainText":
       return replaceTextRunPlainTextCommand(document, command);

package/dist/index.d.cts

@@ -1,4 +1,13 @@
-import { AddConnectorInput, SourceHandle, AddEmptySlideFromLayoutInput, AddTextBoxInput, EditableParagraphProperty, EditableTextRunProperty, PptxSourceModel, EditableTextRunProperties, EditableParagraphProperties, Emu, EditableShapeFill, EditableShapeOutline, MoveSlideInput } from '@pptx-glimpse/document';
+import { AddConnectorInput, SourceHandle, AddEmptySlideFromLayoutInput, AddTextBoxInput, EditableParagraphProperty, EditableTextRunProperty, PptxSourceModel, EditableTextRunProperties, EditableParagraphProperties, Emu, EditableShapeFill, EditableShapeOutline, MoveSlideInput, SourceTextRun, SourceParagraph, SourceShapeNode, SourceTransform, SourceSlide, SourceImage } from '@pptx-glimpse/document';
+
+/**
+ * Headless editor commands, selection, warnings, and history.
+ *
+ * Expected operation rejections use the shared discriminated failure contract exported
+ * by this module. Unexpected programmer errors and invariant violations must propagate.
+ * The repository-wide ownership, conversion, and catch rules are documented in
+ * [the editor error contract](../../../docs/editor-error-contract.md).
+ */
 
 interface ReplaceTextRunPlainTextCommand {
     readonly kind: "replaceTextRunPlainText";
@@ -93,16 +102,18 @@ interface DeleteSlideCommand {
     readonly handle: SourceHandle;
 }
 type EditorCommand = ReplaceTextRunPlainTextCommand | ReplaceParagraphPlainTextCommand | SetTextRunPropertiesCommand | ClearTextRunPropertiesCommand | SetParagraphPropertiesCommand | ClearParagraphPropertiesCommand | MoveShapeCommand | ResizeShapeCommand | SetShapeTransformCommand | SetShapeFillCommand | SetShapeOutlineCommand | AddTextBoxCommand | AddConnectorCommand | DeleteShapeCommand | ReplaceImageCommand | AddEmptySlideFromLayoutCommand | DuplicateSlideCommand | MoveSlideCommand | DeleteSlideCommand;
+type EditorOperationErrorCode = "invalid-command" | "invalid-selection" | "empty-undo-stack" | "empty-redo-stack";
+interface EditorOperationFailure<Code extends EditorOperationErrorCode = EditorOperationErrorCode> {
+    readonly ok: false;
+    readonly code: Code;
+    readonly message: string;
+    readonly cause?: unknown;
+}
 type EditorApplyCommandResult = {
     readonly ok: true;
     readonly document: PptxSourceModel;
     readonly warnings?: readonly EditorCommandWarning[];
-} | {
-    readonly ok: false;
-    readonly code: "invalid-command";
-    readonly message: string;
-    readonly cause?: unknown;
-};
+} | EditorOperationFailure<"invalid-command">;
 interface EditorCommandWarning {
     readonly code: "shared-media-part";
     readonly message: string;
@@ -112,21 +123,14 @@ interface EditorCommandWarning {
 type EditorHistoryResult = {
     readonly ok: true;
     readonly document: PptxSourceModel;
-} | {
-    readonly ok: false;
-    readonly reason: "empty-undo-stack" | "empty-redo-stack";
-};
+} | EditorOperationFailure<"empty-undo-stack" | "empty-redo-stack">;
 interface EditorSelection {
     readonly shapeHandle: SourceHandle;
 }
 type EditorSelectShapeResult = {
     readonly ok: true;
     readonly selection: EditorSelection;
-} | {
-    readonly ok: false;
-    readonly code: "invalid-selection";
-    readonly message: string;
-};
+} | EditorOperationFailure<"invalid-selection">;
 declare class EditorSession {
     #private;
     constructor(document: PptxSourceModel);
@@ -138,12 +142,34 @@ declare class EditorSession {
     get redoDepth(): number;
     selectShape(handle: SourceHandle): EditorSelectShapeResult;
     deselectShape(): void;
+    replaceTextRunPlainText(run: SourceTextRun, text: string): EditorApplyCommandResult;
+    replaceParagraphPlainText(paragraph: SourceParagraph, text: string): EditorApplyCommandResult;
+    setTextRunProperties(run: SourceTextRun, properties: EditableTextRunProperties): EditorApplyCommandResult;
+    clearTextRunProperties(run: SourceTextRun, properties: readonly EditableTextRunProperty[]): EditorApplyCommandResult;
+    setParagraphProperties(paragraph: SourceParagraph, properties: EditableParagraphProperties): EditorApplyCommandResult;
+    clearParagraphProperties(paragraph: SourceParagraph, properties: readonly EditableParagraphProperty[]): EditorApplyCommandResult;
+    moveShape(shape: SourceShapeNode, offsetX: Emu, offsetY: Emu): EditorApplyCommandResult;
+    resizeShape(shape: SourceShapeNode, width: Emu, height: Emu): EditorApplyCommandResult;
+    setShapeTransform(shape: SourceShapeNode, transform: Pick<SourceTransform, "offsetX" | "offsetY" | "width" | "height">): EditorApplyCommandResult;
+    setShapeFill(shape: SourceShapeNode, fill: EditableShapeFill): EditorApplyCommandResult;
+    setShapeOutline(shape: SourceShapeNode, outline: EditableShapeOutline): EditorApplyCommandResult;
+    addTextBox(slide: SourceSlide, input: AddTextBoxInput): EditorApplyCommandResult;
+    addConnector(slide: SourceSlide, input: AddConnectorInput): EditorApplyCommandResult;
+    deleteShape(shape: SourceShapeNode): EditorApplyCommandResult;
+    replaceImage(image: SourceImage, bytes: Uint8Array): EditorApplyCommandResult;
+    addEmptySlideFromLayout(input: AddEmptySlideFromLayoutInput): EditorApplyCommandResult;
+    duplicateSlide(slide: SourceSlide): EditorApplyCommandResult;
+    moveSlide(slide: SourceSlide, input: MoveSlideInput): EditorApplyCommandResult;
+    deleteSlide(slide: SourceSlide): EditorApplyCommandResult;
     apply(command: EditorCommand): EditorApplyCommandResult;
     applyAll(commands: readonly EditorCommand[]): EditorApplyCommandResult;
     undo(): EditorHistoryResult;
     redo(): EditorHistoryResult;
     private reconcileSelectionAfterDocumentChange;
+    private applyToShapeNode;
+    private applyToSlide;
+    private applyToSourceNode;
 }
 declare function createEditorSession(document: PptxSourceModel): EditorSession;
 
-export { type AddConnectorCommand, type AddEmptySlideFromLayoutCommand, type AddTextBoxCommand, type ClearParagraphPropertiesCommand, type ClearTextRunPropertiesCommand, type DeleteShapeCommand, type DeleteSlideCommand, type DuplicateSlideCommand, type EditorApplyCommandResult, type EditorCommand, type EditorCommandWarning, type EditorHistoryResult, type EditorSelectShapeResult, type EditorSelection, EditorSession, type MoveShapeCommand, type MoveSlideCommand, type ReplaceImageCommand, type ReplaceParagraphPlainTextCommand, type ReplaceTextRunPlainTextCommand, type ResizeShapeCommand, type SetParagraphPropertiesCommand, type SetShapeFillCommand, type SetShapeOutlineCommand, type SetShapeTransformCommand, type SetTextRunPropertiesCommand, createEditorSession };
+export { type AddConnectorCommand, type AddEmptySlideFromLayoutCommand, type AddTextBoxCommand, type ClearParagraphPropertiesCommand, type ClearTextRunPropertiesCommand, type DeleteShapeCommand, type DeleteSlideCommand, type DuplicateSlideCommand, type EditorApplyCommandResult, type EditorCommand, type EditorCommandWarning, type EditorHistoryResult, type EditorOperationErrorCode, type EditorOperationFailure, type EditorSelectShapeResult, type EditorSelection, EditorSession, type MoveShapeCommand, type MoveSlideCommand, type ReplaceImageCommand, type ReplaceParagraphPlainTextCommand, type ReplaceTextRunPlainTextCommand, type ResizeShapeCommand, type SetParagraphPropertiesCommand, type SetShapeFillCommand, type SetShapeOutlineCommand, type SetShapeTransformCommand, type SetTextRunPropertiesCommand, createEditorSession };

package/dist/index.d.ts

@@ -1,4 +1,13 @@
-import { AddConnectorInput, SourceHandle, AddEmptySlideFromLayoutInput, AddTextBoxInput, EditableParagraphProperty, EditableTextRunProperty, PptxSourceModel, EditableTextRunProperties, EditableParagraphProperties, Emu, EditableShapeFill, EditableShapeOutline, MoveSlideInput } from '@pptx-glimpse/document';
+import { AddConnectorInput, SourceHandle, AddEmptySlideFromLayoutInput, AddTextBoxInput, EditableParagraphProperty, EditableTextRunProperty, PptxSourceModel, EditableTextRunProperties, EditableParagraphProperties, Emu, EditableShapeFill, EditableShapeOutline, MoveSlideInput, SourceTextRun, SourceParagraph, SourceShapeNode, SourceTransform, SourceSlide, SourceImage } from '@pptx-glimpse/document';
+
+/**
+ * Headless editor commands, selection, warnings, and history.
+ *
+ * Expected operation rejections use the shared discriminated failure contract exported
+ * by this module. Unexpected programmer errors and invariant violations must propagate.
+ * The repository-wide ownership, conversion, and catch rules are documented in
+ * [the editor error contract](../../../docs/editor-error-contract.md).
+ */
 
 interface ReplaceTextRunPlainTextCommand {
     readonly kind: "replaceTextRunPlainText";
@@ -93,16 +102,18 @@ interface DeleteSlideCommand {
     readonly handle: SourceHandle;
 }
 type EditorCommand = ReplaceTextRunPlainTextCommand | ReplaceParagraphPlainTextCommand | SetTextRunPropertiesCommand | ClearTextRunPropertiesCommand | SetParagraphPropertiesCommand | ClearParagraphPropertiesCommand | MoveShapeCommand | ResizeShapeCommand | SetShapeTransformCommand | SetShapeFillCommand | SetShapeOutlineCommand | AddTextBoxCommand | AddConnectorCommand | DeleteShapeCommand | ReplaceImageCommand | AddEmptySlideFromLayoutCommand | DuplicateSlideCommand | MoveSlideCommand | DeleteSlideCommand;
+type EditorOperationErrorCode = "invalid-command" | "invalid-selection" | "empty-undo-stack" | "empty-redo-stack";
+interface EditorOperationFailure<Code extends EditorOperationErrorCode = EditorOperationErrorCode> {
+    readonly ok: false;
+    readonly code: Code;
+    readonly message: string;
+    readonly cause?: unknown;
+}
 type EditorApplyCommandResult = {
     readonly ok: true;
     readonly document: PptxSourceModel;
     readonly warnings?: readonly EditorCommandWarning[];
-} | {
-    readonly ok: false;
-    readonly code: "invalid-command";
-    readonly message: string;
-    readonly cause?: unknown;
-};
+} | EditorOperationFailure<"invalid-command">;
 interface EditorCommandWarning {
     readonly code: "shared-media-part";
     readonly message: string;
@@ -112,21 +123,14 @@ interface EditorCommandWarning {
 type EditorHistoryResult = {
     readonly ok: true;
     readonly document: PptxSourceModel;
-} | {
-    readonly ok: false;
-    readonly reason: "empty-undo-stack" | "empty-redo-stack";
-};
+} | EditorOperationFailure<"empty-undo-stack" | "empty-redo-stack">;
 interface EditorSelection {
     readonly shapeHandle: SourceHandle;
 }
 type EditorSelectShapeResult = {
     readonly ok: true;
     readonly selection: EditorSelection;
-} | {
-    readonly ok: false;
-    readonly code: "invalid-selection";
-    readonly message: string;
-};
+} | EditorOperationFailure<"invalid-selection">;
 declare class EditorSession {
     #private;
     constructor(document: PptxSourceModel);
@@ -138,12 +142,34 @@ declare class EditorSession {
     get redoDepth(): number;
     selectShape(handle: SourceHandle): EditorSelectShapeResult;
     deselectShape(): void;
+    replaceTextRunPlainText(run: SourceTextRun, text: string): EditorApplyCommandResult;
+    replaceParagraphPlainText(paragraph: SourceParagraph, text: string): EditorApplyCommandResult;
+    setTextRunProperties(run: SourceTextRun, properties: EditableTextRunProperties): EditorApplyCommandResult;
+    clearTextRunProperties(run: SourceTextRun, properties: readonly EditableTextRunProperty[]): EditorApplyCommandResult;
+    setParagraphProperties(paragraph: SourceParagraph, properties: EditableParagraphProperties): EditorApplyCommandResult;
+    clearParagraphProperties(paragraph: SourceParagraph, properties: readonly EditableParagraphProperty[]): EditorApplyCommandResult;
+    moveShape(shape: SourceShapeNode, offsetX: Emu, offsetY: Emu): EditorApplyCommandResult;
+    resizeShape(shape: SourceShapeNode, width: Emu, height: Emu): EditorApplyCommandResult;
+    setShapeTransform(shape: SourceShapeNode, transform: Pick<SourceTransform, "offsetX" | "offsetY" | "width" | "height">): EditorApplyCommandResult;
+    setShapeFill(shape: SourceShapeNode, fill: EditableShapeFill): EditorApplyCommandResult;
+    setShapeOutline(shape: SourceShapeNode, outline: EditableShapeOutline): EditorApplyCommandResult;
+    addTextBox(slide: SourceSlide, input: AddTextBoxInput): EditorApplyCommandResult;
+    addConnector(slide: SourceSlide, input: AddConnectorInput): EditorApplyCommandResult;
+    deleteShape(shape: SourceShapeNode): EditorApplyCommandResult;
+    replaceImage(image: SourceImage, bytes: Uint8Array): EditorApplyCommandResult;
+    addEmptySlideFromLayout(input: AddEmptySlideFromLayoutInput): EditorApplyCommandResult;
+    duplicateSlide(slide: SourceSlide): EditorApplyCommandResult;
+    moveSlide(slide: SourceSlide, input: MoveSlideInput): EditorApplyCommandResult;
+    deleteSlide(slide: SourceSlide): EditorApplyCommandResult;
     apply(command: EditorCommand): EditorApplyCommandResult;
     applyAll(commands: readonly EditorCommand[]): EditorApplyCommandResult;
     undo(): EditorHistoryResult;
     redo(): EditorHistoryResult;
     private reconcileSelectionAfterDocumentChange;
+    private applyToShapeNode;
+    private applyToSlide;
+    private applyToSourceNode;
 }
 declare function createEditorSession(document: PptxSourceModel): EditorSession;
 
-export { type AddConnectorCommand, type AddEmptySlideFromLayoutCommand, type AddTextBoxCommand, type ClearParagraphPropertiesCommand, type ClearTextRunPropertiesCommand, type DeleteShapeCommand, type DeleteSlideCommand, type DuplicateSlideCommand, type EditorApplyCommandResult, type EditorCommand, type EditorCommandWarning, type EditorHistoryResult, type EditorSelectShapeResult, type EditorSelection, EditorSession, type MoveShapeCommand, type MoveSlideCommand, type ReplaceImageCommand, type ReplaceParagraphPlainTextCommand, type ReplaceTextRunPlainTextCommand, type ResizeShapeCommand, type SetParagraphPropertiesCommand, type SetShapeFillCommand, type SetShapeOutlineCommand, type SetShapeTransformCommand, type SetTextRunPropertiesCommand, createEditorSession };
+export { type AddConnectorCommand, type AddEmptySlideFromLayoutCommand, type AddTextBoxCommand, type ClearParagraphPropertiesCommand, type ClearTextRunPropertiesCommand, type DeleteShapeCommand, type DeleteSlideCommand, type DuplicateSlideCommand, type EditorApplyCommandResult, type EditorCommand, type EditorCommandWarning, type EditorHistoryResult, type EditorOperationErrorCode, type EditorOperationFailure, type EditorSelectShapeResult, type EditorSelection, EditorSession, type MoveShapeCommand, type MoveSlideCommand, type ReplaceImageCommand, type ReplaceParagraphPlainTextCommand, type ReplaceTextRunPlainTextCommand, type ResizeShapeCommand, type SetParagraphPropertiesCommand, type SetShapeFillCommand, type SetShapeOutlineCommand, type SetShapeTransformCommand, type SetTextRunPropertiesCommand, createEditorSession };

package/dist/index.js

@@ -8,7 +8,9 @@ import {
   deleteShape,
   deleteSlide,
   duplicateSlide,
+  findParagraphBySourceHandle,
   findShapeNodeBySourceHandle,
+  findTextRunBySourceHandle,
   moveSlide,
   replaceImageBytes,
   replaceParagraphPlainText,
@@ -60,50 +62,198 @@ var EditorSession = class {
   deselectShape() {
     this.#selection = void 0;
   }
+  replaceTextRunPlainText(run, text) {
+    return this.applyToSourceNode(
+      "replaceTextRunPlainText",
+      run,
+      isSourceTextRun,
+      findTextRunBySourceHandle,
+      (handle) => ({ kind: "replaceTextRunPlainText", handle, text })
+    );
+  }
+  replaceParagraphPlainText(paragraph, text) {
+    return this.applyToSourceNode(
+      "replaceParagraphPlainText",
+      paragraph,
+      isSourceParagraph,
+      findParagraphBySourceHandle,
+      (handle) => ({ kind: "replaceParagraphPlainText", handle, text })
+    );
+  }
+  setTextRunProperties(run, properties) {
+    return this.applyToSourceNode(
+      "setTextRunProperties",
+      run,
+      isSourceTextRun,
+      findTextRunBySourceHandle,
+      (handle) => ({ kind: "setTextRunProperties", handle, properties })
+    );
+  }
+  clearTextRunProperties(run, properties) {
+    return this.applyToSourceNode(
+      "clearTextRunProperties",
+      run,
+      isSourceTextRun,
+      findTextRunBySourceHandle,
+      (handle) => ({ kind: "clearTextRunProperties", handle, properties })
+    );
+  }
+  setParagraphProperties(paragraph, properties) {
+    return this.applyToSourceNode(
+      "setParagraphProperties",
+      paragraph,
+      isSourceParagraph,
+      findParagraphBySourceHandle,
+      (handle) => ({ kind: "setParagraphProperties", handle, properties })
+    );
+  }
+  clearParagraphProperties(paragraph, properties) {
+    return this.applyToSourceNode(
+      "clearParagraphProperties",
+      paragraph,
+      isSourceParagraph,
+      findParagraphBySourceHandle,
+      (handle) => ({ kind: "clearParagraphProperties", handle, properties })
+    );
+  }
+  moveShape(shape, offsetX, offsetY) {
+    return this.applyToShapeNode("moveShape", shape, (handle) => ({
+      kind: "moveShape",
+      handle,
+      offsetX,
+      offsetY
+    }));
+  }
+  resizeShape(shape, width, height) {
+    return this.applyToShapeNode("resizeShape", shape, (handle) => ({
+      kind: "resizeShape",
+      handle,
+      width,
+      height
+    }));
+  }
+  setShapeTransform(shape, transform) {
+    return this.applyToShapeNode("setShapeTransform", shape, (handle) => ({
+      kind: "setShapeTransform",
+      handle,
+      ...transform
+    }));
+  }
+  setShapeFill(shape, fill) {
+    return this.applyToShapeNode("setShapeFill", shape, (handle) => ({
+      kind: "setShapeFill",
+      handle,
+      fill
+    }));
+  }
+  setShapeOutline(shape, outline) {
+    return this.applyToShapeNode("setShapeOutline", shape, (handle) => ({
+      kind: "setShapeOutline",
+      handle,
+      outline
+    }));
+  }
+  addTextBox(slide, input) {
+    return this.applyToSlide("addTextBox", slide, (slideHandle) => ({
+      kind: "addTextBox",
+      slideHandle,
+      ...input
+    }));
+  }
+  addConnector(slide, input) {
+    return this.applyToSlide("addConnector", slide, (slideHandle) => ({
+      kind: "addConnector",
+      slideHandle,
+      ...input
+    }));
+  }
+  deleteShape(shape) {
+    return this.applyToShapeNode("deleteShape", shape, (handle) => ({
+      kind: "deleteShape",
+      handle
+    }));
+  }
+  replaceImage(image, bytes) {
+    return this.applyToSourceNode(
+      "replaceImage",
+      image,
+      isSourceImage,
+      (document, handle) => {
+        const shape = findShapeNodeBySourceHandle(document, handle);
+        return shape?.kind === "image" ? shape : void 0;
+      },
+      (handle) => ({ kind: "replaceImage", handle, bytes })
+    );
+  }
+  addEmptySlideFromLayout(input) {
+    return this.apply({ kind: "addEmptySlideFromLayout", ...input });
+  }
+  duplicateSlide(slide) {
+    return this.applyToSlide("duplicateSlide", slide, (handle) => ({
+      kind: "duplicateSlide",
+      handle
+    }));
+  }
+  moveSlide(slide, input) {
+    return this.applyToSlide("moveSlide", slide, (handle) => ({
+      kind: "moveSlide",
+      handle,
+      ...input
+    }));
+  }
+  deleteSlide(slide) {
+    return this.applyToSlide("deleteSlide", slide, (handle) => ({
+      kind: "deleteSlide",
+      handle
+    }));
+  }
   apply(command) {
     return this.applyAll([command]);
   }
   applyAll(commands) {
     const before = this.#document;
     if (commands.length === 0) return { ok: true, document: before };
+    let after = before;
+    const warnings = [];
+    for (const command of commands) {
+      const result = applyCommandToDocument(after, command);
+      if (!result.ok) return result;
+      after = result.document;
+      warnings.push(...collectCommandWarnings(after, [command]));
+    }
     try {
-      let after = before;
-      const warnings = [];
-      for (const command of commands) {
-        after = applyCommandToDocument(after, command);
-        warnings.push(...collectCommandWarnings(after, [command]));
-      }
       assertNoConflictingParagraphAndRunEdits(after.edits);
-      after = normalizeEditorEdits(after);
-      const dedupedWarnings = dedupeCommandWarnings(warnings);
-      if (after === before) {
-        return {
-          ok: true,
-          document: before,
-          ...dedupedWarnings.length > 0 ? { warnings: dedupedWarnings } : {}
-        };
-      }
-      this.#document = after;
-      this.reconcileSelectionAfterDocumentChange();
-      this.#undoStack.push({ before, after });
-      this.#redoStack.length = 0;
+    } catch (cause) {
+      return invalidCommandFailure(cause);
+    }
+    after = normalizeEditorEdits(after);
+    const dedupedWarnings = dedupeCommandWarnings(warnings);
+    if (after === before) {
       return {
         ok: true,
-        document: after,
+        document: before,
         ...dedupedWarnings.length > 0 ? { warnings: dedupedWarnings } : {}
       };
-    } catch (error) {
-      return {
-        ok: false,
-        code: "invalid-command",
-        message: error instanceof Error ? error.message : "Editor command was rejected.",
-        cause: error
-      };
     }
+    this.#document = after;
+    this.reconcileSelectionAfterDocumentChange();
+    this.#undoStack.push({ before, after });
+    this.#redoStack.length = 0;
+    return {
+      ok: true,
+      document: after,
+      ...dedupedWarnings.length > 0 ? { warnings: dedupedWarnings } : {}
+    };
   }
   undo() {
     const entry = this.#undoStack.pop();
-    if (entry === void 0) return { ok: false, reason: "empty-undo-stack" };
+    if (entry === void 0) {
+      return {
+        ok: false,
+        code: "empty-undo-stack",
+        message: "undo: undo history is empty"
+      };
+    }
     this.#document = entry.before;
     this.reconcileSelectionAfterDocumentChange();
     this.#redoStack.push(entry);
@@ -111,7 +261,13 @@ var EditorSession = class {
   }
   redo() {
     const entry = this.#redoStack.pop();
-    if (entry === void 0) return { ok: false, reason: "empty-redo-stack" };
+    if (entry === void 0) {
+      return {
+        ok: false,
+        code: "empty-redo-stack",
+        message: "redo: redo history is empty"
+      };
+    }
     this.#document = entry.after;
     this.reconcileSelectionAfterDocumentChange();
     this.#undoStack.push(entry);
@@ -123,11 +279,172 @@ var EditorSession = class {
       this.#selection = void 0;
     }
   }
+  applyToShapeNode(operation, shape, createCommand) {
+    return this.applyToSourceNode(
+      operation,
+      shape,
+      isSourceShapeNode,
+      findShapeNodeBySourceHandle,
+      createCommand
+    );
+  }
+  applyToSlide(operation, slide, createCommand) {
+    return this.applyToSourceNode(
+      operation,
+      slide,
+      isSourceSlide,
+      (document, handle) => document.slides.find((candidate) => sourceHandlesEqual(candidate.handle, handle)),
+      createCommand
+    );
+  }
+  applyToSourceNode(operation, node, isExpectedNode, findCurrentNode, createCommand) {
+    if (!isExpectedNode(node)) {
+      return invalidSourceNodeFailure(operation, "source node has the wrong target type");
+    }
+    if (node.handle === void 0) {
+      return invalidSourceNodeFailure(operation, "source node does not have a handle");
+    }
+    if (findCurrentNode(this.#document, node.handle) === void 0) {
+      return invalidSourceNodeFailure(
+        operation,
+        "source node handle was not found in the current EditorSession document"
+      );
+    }
+    return this.apply(createCommand(node.handle));
+  }
 };
 function createEditorSession(document) {
   return new EditorSession(document);
 }
+var EDITOR_COMMAND_KINDS = /* @__PURE__ */ new Set([
+  "replaceTextRunPlainText",
+  "replaceParagraphPlainText",
+  "setTextRunProperties",
+  "clearTextRunProperties",
+  "setParagraphProperties",
+  "clearParagraphProperties",
+  "moveShape",
+  "resizeShape",
+  "setShapeTransform",
+  "setShapeFill",
+  "setShapeOutline",
+  "addTextBox",
+  "addConnector",
+  "deleteShape",
+  "replaceImage",
+  "addEmptySlideFromLayout",
+  "duplicateSlide",
+  "moveSlide",
+  "deleteSlide"
+]);
+var EXPECTED_COMMAND_REJECTION_PREFIXES = [
+  "replaceTextRunPlainText:",
+  "replaceParagraphPlainText:",
+  "setTextRunProperties:",
+  "clearTextRunProperties:",
+  "setParagraphProperties:",
+  "clearParagraphProperties:",
+  "moveShape:",
+  "resizeShape:",
+  "setShapeTransform:",
+  "setShapeFill:",
+  "setShapeOutline:",
+  "addTextBox:",
+  "addConnector:",
+  "deleteShape:",
+  "replaceImageBytes:",
+  "addEmptySlideFromLayout:",
+  "duplicateSlide:",
+  "moveSlide:",
+  "deleteSlide:",
+  "updateTextRunProperties:",
+  "updateParagraphProperties:",
+  "updateShapeTransform:"
+];
 function applyCommandToDocument(document, command) {
+  if (!EDITOR_COMMAND_KINDS.has(command.kind)) {
+    throw new TypeError(`EditorSession: unsupported command kind '${String(command.kind)}'`);
+  }
+  switch (command.kind) {
+    case "replaceTextRunPlainText":
+    case "replaceParagraphPlainText":
+    case "setTextRunProperties":
+    case "clearTextRunProperties":
+    case "setParagraphProperties":
+    case "clearParagraphProperties":
+    case "moveShape":
+    case "resizeShape":
+    case "setShapeTransform":
+    case "setShapeFill":
+    case "setShapeOutline":
+    case "addTextBox":
+    case "addConnector":
+    case "deleteShape":
+    case "replaceImage":
+    case "addEmptySlideFromLayout":
+    case "duplicateSlide":
+    case "moveSlide":
+    case "deleteSlide":
+      return attemptCommand(() => executeCommand(document, command));
+  }
+}
+function attemptCommand(operation) {
+  try {
+    return { ok: true, document: operation() };
+  } catch (cause) {
+    return invalidCommandFailure(cause);
+  }
+}
+function invalidCommandFailure(cause) {
+  if (!(cause instanceof Error) || !EXPECTED_COMMAND_REJECTION_PREFIXES.some((prefix) => cause.message.startsWith(prefix))) {
+    throw cause;
+  }
+  return {
+    ok: false,
+    code: "invalid-command",
+    message: cause.message,
+    cause
+  };
+}
+function invalidSourceNodeFailure(operation, reason) {
+  return {
+    ok: false,
+    code: "invalid-command",
+    message: `${operation}: ${reason}`
+  };
+}
+function isSourceTextRun(value) {
+  return isObject(value) && value.kind === "textRun";
+}
+function isSourceParagraph(value) {
+  return isObject(value) && Array.isArray(value.runs);
+}
+var SOURCE_SHAPE_NODE_KINDS = /* @__PURE__ */ new Set([
+  "shape",
+  "connector",
+  "group",
+  "image",
+  "table",
+  "chart",
+  "smartArt",
+  "raw"
+]);
+function isSourceShapeNode(value) {
+  return isObject(value) && typeof value.kind === "string" && SOURCE_SHAPE_NODE_KINDS.has(value.kind);
+}
+function isSourceImage(value) {
+  return isObject(value) && value.kind === "image";
+}
+function isSourceSlide(value) {
+  return isObject(value) && typeof value.partPath === "string" && typeof value.layoutPartPath === "string" && Array.isArray(value.shapes);
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function sourceHandlesEqual(left, right) {
+  return left !== void 0 && left.partPath === right.partPath && left.nodeId === right.nodeId && left.relationshipId === right.relationshipId && left.orderingSlot === right.orderingSlot;
+}
+function executeCommand(document, command) {
   switch (command.kind) {
     case "replaceTextRunPlainText":
       return replaceTextRunPlainTextCommand(document, command);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pptx-glimpse/editor",
-  "version": "0.1.0",
-  "description": "UI-independent commands, selection, history, and validation for PptxSourceModel.",
+  "version": "0.2.0",
+  "description": "Headless PPTX editing commands, validation, selection, and undo/redo history for PptxSourceModel.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -19,7 +19,7 @@
     }
   },
   "dependencies": {
-    "@pptx-glimpse/document": "^0.12.0"
+    "@pptx-glimpse/document": "^0.12.1"
   },
   "files": [
     "dist",
@@ -32,7 +32,11 @@
     "pptx",
     "powerpoint",
     "editor",
-    "headless"
+    "headless",
+    "commands",
+    "undo",
+    "redo",
+    "selection"
   ],
   "repository": {
     "type": "git",