@kubuild/core 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,122 @@
+# @kubuild/core
+
+[![npm version](https://img.shields.io/npm/v/@kubuild/core.svg)](https://www.npmjs.com/package/@kubuild/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+
+Framework-agnostic engine for **KUBUILD**: document tree utilities, command engine, history stack (undo/redo), Action Pipeline Executor, Runtime State Store, Validation Engine, template interpolation, migration, and export/import.
+
+Core contains **zero UI/DOM dependencies** and runs seamlessly in Node.js, Cloudflare Workers, Electron, and the browser.
+
+---
+
+## 📦 Installation
+
+```bash
+# Using pnpm (recommended)
+pnpm add @kubuild/core @kubuild/schema
+
+# Using npm
+npm install @kubuild/core @kubuild/schema
+
+# Using yarn
+yarn add @kubuild/core @kubuild/schema
+```
+
+---
+
+## ✨ Features
+
+- **Document Tree Manipulation**: Safe operations for finding, inserting, moving, cloning, and removing nodes (`findNodeById`, `insertNode`, `removeNode`, `moveNode`).
+- **Command Engine & History**: Transactional command pattern with an undo/redo stack (`CommandEngine`, `InsertNodeCommand`, `UpdateNodePropsCommand`, `UpdateNodeStylesCommand`).
+- **Action Pipeline Executor**: Comprehensive runner for executing multi-step action flows (`ActionPipelineExecutor`), evaluating success/error branches and conditional expressions.
+- **Runtime State Store**: Lightweight reactive store (`RuntimeStateStore`) for managing form values, execution logs, response data, and runtime variables.
+- **Validation Engine**: Built-in validators for form fields and models (required, email, regex, min/max length, custom rules).
+- **Template Interpolation**: Powerful variable interpolation supporting syntax like `{{form.name}}`, `{{user.id}}`, or `{{response.data}}`.
+- **Portable Export & Import**: Pack page documents and assets into portable `.stora` archives (compressed zip via `fflate`) and unpack them back into memory.
+- **Security Defense**: Strict XSS prevention, safe URL sanitization, and style value validation.
+
+---
+
+## 🚀 Quick Usage
+
+### Command Engine & Undo/Redo
+
+```typescript
+import { CommandEngine, InsertNodeCommand } from '@kubuild/core';
+import type { PageDocument, Node } from '@kubuild/schema';
+
+const engine = new CommandEngine(initialPageDocument);
+
+// Execute a command to insert a new node
+const buttonNode: Node = {
+  id: 'btn-1',
+  type: 'button',
+  props: { label: 'Click Me' },
+  styles: { backgroundColor: '#3b82f6', color: '#ffffff' }
+};
+
+engine.execute(new InsertNodeCommand(engine.getDocument(), 'root-1', buttonNode));
+
+// Undo the insertion
+engine.undo();
+
+// Redo the insertion
+engine.redo();
+
+const currentDoc: PageDocument = engine.getDocument();
+```
+
+### Action Pipeline Execution & Interpolation
+
+```typescript
+import {
+  ActionPipelineExecutor,
+  RuntimeStateStore,
+  interpolateTemplate
+} from '@kubuild/core';
+import type { ActionPipeline } from '@kubuild/schema';
+
+// 1. Initialize State Store
+const stateStore = new RuntimeStateStore({
+  form: { email: 'user@example.com', name: 'Alex' },
+  user: { role: 'admin' }
+});
+
+// 2. Interpolate template string
+const greeting = interpolateTemplate('Hello {{form.name}}! Role: {{user.role}}', stateStore.getState());
+console.log(greeting); // "Hello Alex! Role: admin"
+
+// 3. Execute Pipeline
+const executor = new ActionPipelineExecutor({
+  stateStore,
+  runners: {
+    async apiRequest(step, context) {
+      const response = await fetch(step.config.url, { method: step.config.method });
+      return await response.json();
+    }
+  }
+});
+
+const result = await executor.execute(pipelineDefinition);
+```
+
+### Exporting & Importing `.stora` Files
+
+```typescript
+import { exportStoraArchive, importStoraArchive } from '@kubuild/core';
+
+// Export document to binary .stora buffer (zip)
+const storaBuffer: Uint8Array = await exportStoraArchive(pageDocument, {
+  includeAssets: true
+});
+
+// Import .stora buffer back into validated PageDocument
+const importedDocument = await importStoraArchive(storaBuffer);
+```
+
+---
+
+## 📄 License
+
+MIT © [KUBUILD](https://github.com/kustora/kubuild)

package/dist/document/artboards.d.ts

@@ -0,0 +1,113 @@
+import { Artboard, Node, PageDocument, ProjectDocument } from '@kubuild/schema';
+export type ArtboardChangeType = 'ARTBOARD_ADDED' | 'ARTBOARD_REMOVED' | 'ARTBOARD_RENAMED' | 'ACTIVE_ARTBOARD_CHANGED' | 'NODE_EXTRACTED_TO_ARTBOARD';
+export interface ArtboardChangeEvent {
+    type: ArtboardChangeType;
+    timestamp: string;
+    artboardId: string;
+    /** Source artboard, for operations that move content between artboards. */
+    sourceArtboardId?: string;
+    nodeId?: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * Mirrors CommandResult from commands.ts, but at the project (multi-artboard) level.
+ * Node-level commands keep returning CommandResult and keep operating on a single
+ * PageDocument, unchanged.
+ */
+export interface ProjectCommandResult {
+    project: ProjectDocument;
+    event: ArtboardChangeEvent;
+}
+export interface AddArtboardParams {
+    artboard: Artboard;
+    index?: number;
+    /** Make the newly added artboard active (default: true). */
+    activate?: boolean;
+}
+export interface RemoveArtboardParams {
+    artboardId: string;
+}
+export interface RenameArtboardParams {
+    artboardId: string;
+    name: string;
+}
+export interface SetActiveArtboardParams {
+    artboardId: string;
+}
+export interface ExtractNodeToArtboardParams {
+    /** Artboard currently holding the node. */
+    artboardId: string;
+    /** Node whose subtree becomes the new artboard's content. */
+    nodeId: string;
+    /** Optional explicit name for the new artboard (defaults to the node type). */
+    name?: string;
+    /** Optional explicit id for the new artboard. */
+    newArtboardId?: string;
+    /** Make the new artboard active (default: false — authors usually keep editing the page). */
+    activate?: boolean;
+}
+/**
+ * Collect every node id used anywhere in the project (across all artboards).
+ * Node ids must be unique project-wide so that content can move between artboards
+ * without silently colliding.
+ */
+export declare function collectProjectNodeIds(project: ProjectDocument): Set<string>;
+export declare function findArtboardById(project: ProjectDocument, artboardId: string): Artboard | undefined;
+/**
+ * Resolve the component artboard an `open_modal` / `close_modal` action targets.
+ * ModalManager keys off plain strings, so a trigger in one artboard can address
+ * content in another with no additional wiring.
+ */
+export declare function findArtboardByTriggerId(project: ProjectDocument, triggerId: string): Artboard | undefined;
+export declare function getActiveArtboard(project: ProjectDocument): Artboard | undefined;
+export declare function getPageArtboards(project: ProjectDocument): Artboard[];
+export declare function getComponentArtboards(project: ProjectDocument): Artboard[];
+export interface CreateArtboardOptions {
+    id?: string;
+    slug?: string;
+    triggerId?: string;
+    viewport?: Artboard['viewport'];
+    width?: number;
+}
+/**
+ * Build a page artboard around a fresh blank document.
+ */
+export declare function createPageArtboard(name?: string, options?: CreateArtboardOptions): Artboard;
+/**
+ * Wrap an existing node as the sole child of a synthetic `page` root and return it as a
+ * component artboard. The synthetic root exists so each artboard's `document` stays a
+ * fully valid PageDocument, meaning no existing command, validator, or history code
+ * needs to know that component artboards exist at all.
+ */
+export declare function createComponentArtboard(node: Node, options?: CreateArtboardOptions & {
+    name?: string;
+    rootId?: string;
+}): Artboard;
+/**
+ * Create a project containing a single blank page artboard.
+ */
+export declare function createBlankProject(title?: string): ProjectDocument;
+export declare function addArtboard(project: ProjectDocument, params: AddArtboardParams): ProjectCommandResult;
+export declare function removeArtboard(project: ProjectDocument, params: RemoveArtboardParams): ProjectCommandResult;
+export declare function renameArtboard(project: ProjectDocument, params: RenameArtboardParams): ProjectCommandResult;
+export declare function setActiveArtboard(project: ProjectDocument, params: SetActiveArtboardParams): ProjectCommandResult;
+/**
+ * Detach a node's subtree into its own component artboard, leaving an
+ * `artboard-reference` stub at the original position.
+ *
+ * The stub matters: selection, move/delete, copy/paste, the Layers panel, and history
+ * diffing all walk nodes that are physically present in the tree, so a bare deletion would
+ * leave the page with no visible, selectable anchor for "this surface opens artboard X"
+ * and would strand the trigger's id with nothing pointing back at it.
+ *
+ * Undo scoping caveat (Phase 1): the editor's history is per-document, so this operation —
+ * which spans two artboards — is applied as one atomic project-level step rather than being
+ * finely undoable inside each artboard's own stack.
+ */
+export declare function extractNodeToArtboard(project: ProjectDocument, params: ExtractNodeToArtboardParams): ProjectCommandResult;
+/**
+ * Replace one artboard's document wholesale. Used by the editor when committing the
+ * single active PageDocument it holds back into the project.
+ */
+export declare function updateArtboardDocument(project: ProjectDocument, artboardId: string, document: PageDocument): ProjectDocument;
+//# sourceMappingURL=artboards.d.ts.map

package/dist/document/artboards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artboards.d.ts","sourceRoot":"","sources":["../../src/document/artboards.ts"],"names":[],"mappings":"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"}

package/dist/document/command-tree-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-tree-utils.d.ts","sourceRoot":"","sources":["../../src/document/command-tree-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAkB,MAAM,iBAAiB,CAAC;AAEvD;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAEtC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAUlF;AA0BD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,OAAO,GAAG,kBAAkB,GAAG,cAAc,CAAC;AAE3F;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,mBAAmB,GAC7B,MAAM,GAAG,IAAI,CAkBf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAcvE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,CAgBrE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAgB5E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAenF;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,IAAI,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACvC,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,mBAAmB,CAyBrB"}

package/dist/{commands.d.ts → document/commands.d.ts}

@@ -1,5 +1,5 @@
-import { PageDocument, Node, ResponsiveStyles, StyleDefinition, AnimationConfig } from '@kubuild/schema';
-export type DocumentChangeType = 'NODE_INSERTED' | 'NODE_MOVED' | 'PROPS_UPDATED' | 'STYLE_UPDATED' | 'ANIMATION_UPDATED' | 'NODE_REMOVED' | 'NODE_DUPLICATED';
+import { PageDocument, Node, ResponsiveStyles, StyleDefinition, AnimationConfig, ActionPipeline, FormConfig } from '@kubuild/schema';
+export type DocumentChangeType = 'NODE_INSERTED' | 'NODE_MOVED' | 'PROPS_UPDATED' | 'STYLE_UPDATED' | 'ANIMATION_UPDATED' | 'ACTIONS_UPDATED' | 'FORM_CONFIG_UPDATED' | 'NODE_REMOVED' | 'NODE_DUPLICATED' | 'NODE_WRAPPED' | 'NODE_UNGROUPED' | 'NODE_REPLACED';
 export interface DocumentChangeEvent {
     type: DocumentChangeType;
     timestamp: string;
@@ -61,6 +61,28 @@ export interface DuplicateNodeParams {
     index?: number;
     idGenerator?: (oldId: string) => string;
 }
+export interface WrapNodeIntoFrameParams {
+    /** Single node ID to wrap into a frame. */
+    nodeId?: string;
+    /** Multiple node IDs to wrap into a frame. */
+    nodeIds?: string[] | string;
+    /** Optional custom ID for the created flex frame container. */
+    frameId?: string;
+    /** Optional custom props for the flex frame container. */
+    frameProps?: Record<string, unknown>;
+    /** Optional custom responsive styles for the flex frame container. */
+    frameStyles?: ResponsiveStyles;
+}
+export interface UngroupNodeFrameParams {
+    /** Node ID of the flex container to unwrap. */
+    nodeId: string;
+}
+export interface ReplaceNodeParams {
+    /** ID of the existing node to replace. */
+    nodeId: string;
+    /** Full replacement node — its `id` must match `nodeId` (identity is never silently changed). */
+    node: Node;
+}
 /**
  * 1. Insert a node into a target parent node.
  * Returns a new PageDocument and a NODE_INSERTED event.
@@ -111,4 +133,55 @@ export interface UpdateAnimationParams {
  * Returns a new PageDocument and an ANIMATION_UPDATED event.
  */
 export declare function updateAnimation(document: PageDocument, params: UpdateAnimationParams): CommandResult;
+export interface UpdateActionsParams {
+    nodeId: string;
+    actions: ActionPipeline[] | null;
+}
+/**
+ * 8. Update the action pipelines of an existing node.
+ * Returns a new PageDocument and an ACTIONS_UPDATED event.
+ */
+export declare function updateActions(document: PageDocument, params: UpdateActionsParams): CommandResult;
+export interface UpdateFormConfigParams {
+    nodeId: string;
+    formConfig: Partial<FormConfig> | null;
+    /**
+     * If true (default), shallow merges new formConfig properties with existing config.
+     * If false, replaces the formConfig with the provided object.
+     * If formConfig is null, removes the form configuration from the node.
+     */
+    merge?: boolean;
+}
+/**
+ * 9. Update the form configuration of an existing node.
+ * Returns a new PageDocument and a FORM_CONFIG_UPDATED event.
+ */
+export declare function updateFormConfig(document: PageDocument, params: UpdateFormConfigParams): CommandResult;
+/**
+ * 10. Wrap specified node(s) into a new flex container node at the same position in the parent.
+ * Preserves sibling ordering and returns a new PageDocument and a NODE_WRAPPED event.
+ * Full undo/redo compatibility with DocumentHistoryManager. (STORA-105)
+ */
+export declare function wrapNodeIntoFrame(document: PageDocument, params: WrapNodeIntoFrameParams): CommandResult;
+/**
+ * 11. Unwrap a flex frame container, moving all of its children to its parent at its position,
+ * and removing the container.
+ * Returns a new PageDocument and a NODE_UNGROUPED event.
+ * Full undo/redo compatibility with DocumentHistoryManager. (STORA-106)
+ */
+export declare function ungroupNodeFrame(document: PageDocument, params: UngroupNodeFrameParams): CommandResult;
+/**
+ * 12. Replace an existing node's entire subtree (props, styles, children, animation,
+ * actions, formConfig) in place, preserving its position in the parent.
+ *
+ * Used by AI "enhance" flows (STORA-514) when a validated candidate node differs
+ * structurally from the original (e.g. AI regenerated nested children) — a change
+ * `updateProps`/`updateStyle` alone can't express since they only ever touch one
+ * property bag at a time. The replacement node's `id` must match `nodeId`; this command
+ * never lets identity (id) drift, the same guarantee `@kubuild/ai`'s
+ * `normalizeAndValidateRefactoredNode` already enforces upstream on `type`/`id`.
+ *
+ * Returns a new PageDocument and a NODE_REPLACED event.
+ */
+export declare function replaceNode(document: PageDocument, params: ReplaceNodeParams): CommandResult;
 //# sourceMappingURL=commands.d.ts.map

package/dist/document/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/document/commands.ts"],"names":[],"mappings":"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"}

package/dist/{document-utils.d.ts → document/document-utils.d.ts}

@@ -1,7 +1,5 @@
 import { PageDocument, Node } from '@kubuild/schema';
-import type { ComponentRegistryLike } from './validator';
-export { validateDocument } from './validator';
-export type { DocumentValidationResult, DocumentValidationError, DocumentValidationErrorCode, ValidationOptions, ComponentDefinitionLike, ComponentRegistryLike, } from './validator';
+import type { ComponentRegistryLike } from '../validation/validator';
 export declare function createBlankDocument(title?: string): PageDocument;
 export declare function findNodeById(rootNode: Node, targetId: string): Node | null;
 export interface CollectedAssetReference {

package/dist/document/document-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-utils.d.ts","sourceRoot":"","sources":["../../src/document/document-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,IAAI,EAAe,MAAM,iBAAiB,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGrE,wBAAgB,mBAAmB,CAAC,KAAK,SAAkB,GAAG,YAAY,CAsBzE;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAQ1E;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE;QACT,IAAI,EAAE,OAAO,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,IAAI,GAAG,uBAAuB,EAAE,CAkDhF;AAED,MAAM,WAAW,gBAAgB;IAC/B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,IAAI,EACd,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,gBAAgB,CA8BlB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,IAAI,EACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAClD,MAAM,CA+CR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAClD,YAAY,CAKd;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,IAAI,EACd,QAAQ,CAAC,EAAE,qBAAqB,EAChC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,GAClC,wBAAwB,EAAE,CA6C5B"}

package/dist/{history.d.ts → document/history.d.ts}

@@ -30,6 +30,8 @@ export declare class HistoryEngine<T = PageDocument> {
     private current;
     private future;
     private readonly maxHistory;
+    private transactionDepth;
+    private transactionAnchor;
     constructor(initialState: T, options?: HistoryOptions);
     /**
      * Get the current active state (returns an immutable clone).
@@ -58,8 +60,40 @@ export declare class HistoryEngine<T = PageDocument> {
     /**
      * Push a new state.
      * Clears the redo stack and shifts oldest past entries if maxHistory is exceeded.
+     *
+     * STORA-510: while a transaction is active (see `beginTransaction`), pushes update
+     * `current` in place without creating an individual undo entry — the whole group
+     * collapses into one entry when `endTransaction()` is called.
      */
     push(nextState: T, event?: DocumentChangeEvent): void;
+    /**
+     * Begin a grouped-history transaction (STORA-510).
+     *
+     * Every `push()` made between `beginTransaction()` and the matching outermost
+     * `endTransaction()` updates the live state immediately (so `present`/`getState()`
+     * always reflect the latest change), but no individual undo entry is recorded until
+     * the transaction ends. This is how a multi-step action (e.g. one `streamPage`
+     * generation session inserting several sections) collapses into a single undo step.
+     *
+     * Transactions may be nested; only the outermost `beginTransaction`/`endTransaction`
+     * pair has any effect, so a batching caller can safely wrap calls that themselves
+     * might also start their own (nested) transaction.
+     */
+    beginTransaction(): void;
+    /**
+     * Ends the current transaction (see `beginTransaction`). Once the outermost
+     * transaction ends, the state as it was immediately before `beginTransaction()` is
+     * pushed as a single past entry (exactly as one `push()` would) and the redo stack
+     * is cleared — unless nothing actually changed during the transaction, in which case
+     * this is a no-op and no empty undo entry is created.
+     *
+     * Calling `endTransaction()` without a matching `beginTransaction()` is a no-op.
+     */
+    endTransaction(): void;
+    /**
+     * Whether a grouped-history transaction is currently active.
+     */
+    get inTransaction(): boolean;
     /**
      * Undo to the previous state.
      * Returns the restored state, or undefined if undo is not possible.
@@ -100,6 +134,18 @@ export declare class DocumentHistoryManager {
     execute(executor: (currentDoc: PageDocument) => CommandResult): CommandResult;
     undo(): PageDocument | undefined;
     redo(): PageDocument | undefined;
+    /**
+     * Begin a grouped-history transaction (STORA-510) — see `HistoryEngine.beginTransaction`.
+     * Every `execute()` call made until the matching `endTransaction()` updates
+     * `document` immediately but is collapsed into a single undo entry.
+     */
+    beginTransaction(): void;
+    /**
+     * Ends a grouped-history transaction started with `beginTransaction()` — see
+     * `HistoryEngine.endTransaction`.
+     */
+    endTransaction(): void;
+    get inTransaction(): boolean;
     reset(newDocument: PageDocument): void;
     clear(): void;
     getState(): HistoryState<PageDocument>;

package/dist/document/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/document/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhE,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;CACZ;AAED,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;GAIG;AACH,qBAAa,aAAa,CAAC,CAAC,GAAG,YAAY;IACzC,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAIpC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,iBAAiB,CAAgC;gBAE7C,YAAY,EAAE,CAAC,EAAE,OAAO,GAAE,cAAmB;IAiBzD;;OAEG;IACH,IAAI,OAAO,IAAI,CAAC,CAEf;IAED;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;OAOG;IACH,IAAI,CAAC,SAAS,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,mBAAmB,GAAG,IAAI;IAiCrD;;;;;;;;;;;;OAYG;IACH,gBAAgB,IAAI,IAAI;IAOxB;;;;;;;;OAQG;IACH,cAAc,IAAI,IAAI;IAgBtB;;OAEG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;;OAGG;IACH,IAAI,IAAI,CAAC,GAAG,SAAS;IAYrB;;;OAGG;IACH,IAAI,IAAI,CAAC,GAAG,SAAS;IAYrB;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,IAAI;IAaxB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC;CAS5B;AAED;;;GAGG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,OAAO,CAA8B;gBAEjC,eAAe,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc;IAInE,IAAI,QAAQ,IAAI,YAAY,CAE3B;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,YAAY,KAAK,aAAa,GAAG,aAAa;IAO7E,IAAI,IAAI,YAAY,GAAG,SAAS;IAIhC,IAAI,IAAI,YAAY,GAAG,SAAS;IAIhC;;;;OAIG;IACH,gBAAgB,IAAI,IAAI;IAIxB;;;OAGG;IACH,cAAc,IAAI,IAAI;IAItB,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,KAAK,CAAC,WAAW,EAAE,YAAY,GAAG,IAAI;IAItC,KAAK,IAAI,IAAI;IAIb,QAAQ,IAAI,YAAY,CAAC,YAAY,CAAC;CAGvC"}

package/dist/document/index.d.ts

@@ -0,0 +1,6 @@
+export * from './document-utils';
+export * from './command-tree-utils';
+export * from './commands';
+export * from './artboards';
+export * from './history';
+//# sourceMappingURL=index.d.ts.map

package/dist/document/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/document/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}