@kubuild/core 0.8.1 → 0.8.2

package/dist/document/artboards.d.cts

@@ -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.cts.map

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

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

package/dist/document/command-tree-utils.d.cts

@@ -0,0 +1,81 @@
+import { Node } from '@kubuild/schema';
+/**
+ * Deep clone an object immutably (JSON-safe).
+ */
+export declare function deepClone<T>(val: T): T;
+export interface NodeLocation {
+    node: Node;
+    parent: Node | null;
+    index: number;
+}
+/**
+ * Find a node, its parent, and index within the parent's children array.
+ */
+export declare function findNodeLocation(root: Node, targetId: string): NodeLocation | null;
+export type NavigationDirection = 'parent' | 'child' | 'previous-sibling' | 'next-sibling';
+/**
+ * Resolve the node id reached by moving from `nodeId` in a tree-navigation direction.
+ * Returns null when there is nowhere to go (e.g. root has no parent, a leaf has no child,
+ * or the node sits at the start/end of its sibling list).
+ */
+export declare function getNavigationTarget(root: Node, nodeId: string, direction: NavigationDirection): string | null;
+/**
+ * Returns the chain of ancestor node ids from the root down to (but excluding)
+ * `targetId`, root first. Returns [] if targetId is the root or is not found.
+ */
+export declare function getAncestorChain(root: Node, targetId: string): string[];
+/**
+ * STORA-232: Find the direct parent node of `targetId` in a single O(N) traversal.
+ * Returns null when the target is the root or is not found in the tree.
+ */
+export declare function getParentNodeId(root: Node, targetId: string): string | null;
+/**
+ * STORA-232: Return the full ancestor path of `targetId` as an array of nodes,
+ * ordered from the root down to (and including) the target node itself.
+ * Single O(N) traversal: the path is tracked during descent, so no re-walks.
+ * Returns [] when the target is not found.
+ */
+export declare function getNodeAncestors(root: Node, targetId: string): Node[];
+/**
+ * Check whether `targetId` is a descendant of `ancestorNode` (or equal to ancestorNode.id).
+ */
+export declare function isDescendantOf(ancestorNode: Node, targetId: string): boolean;
+/**
+ * Collect all node IDs present in a node subtree as a Set.
+ */
+export declare function collectNodeIdSet(root: Node): Set<string>;
+/**
+ * Default unique ID generator function for node duplication.
+ */
+export declare function defaultIdGenerator(oldId: string, existingIds?: Set<string>): string;
+export interface ClonedSubtreeResult {
+    clonedNode: Node;
+    idMap: Map<string, string>;
+}
+/**
+ * Keys (in step payloads, legacy `props.action.payload`, and node props) whose string value
+ * is a reference to another node's id. When a subtree is cloned with fresh ids, references
+ * that point at a node *inside* that subtree are rewritten to the clone's new id; references
+ * to nodes outside the subtree are left untouched.
+ */
+export declare const NODE_ID_REFERENCE_KEYS: ReadonlySet<string>;
+/**
+ * Rewrites node-id references inside a single (already cloned) node so they follow `idMap`.
+ * Covers action pipeline step payloads (incl. onSuccess/onError branches), `formConfig.formId`,
+ * id-reference props (e.g. `modalId`, `formId`), `#anchor` hrefs, and the legacy `props.action`
+ * payload. Mutates the node in place; callers must pass a clone they own.
+ */
+export declare function remapNodeReferences(node: Node, idMap: ReadonlyMap<string, string>): void;
+/**
+ * Deep-clones a node subtree assigning every node a fresh id via `idGen`, preserving every
+ * other `Node` field (props, styles, animation, actions, formConfig, and any future field),
+ * then rewrites intra-subtree node-id references (see {@link remapNodeReferences}).
+ */
+export declare function cloneNodeTreeWithFreshIds(root: Node, idGen: (oldId: string, node: Node) => string): ClonedSubtreeResult;
+/**
+ * Recursively clone a node and its entire subtree, generating fresh unique IDs
+ * for every node while preserving every other node field (props, styles, animation,
+ * actions, formConfig) and remapping intra-subtree node-id references.
+ */
+export declare function cloneTreeWithNewIds(root: Node, idGenerator?: (oldId: string) => string, existingIds?: Set<string>): ClonedSubtreeResult;
+//# sourceMappingURL=command-tree-utils.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command-tree-utils.d.cts","sourceRoot":"","sources":["../../src/document/command-tree-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmC,MAAM,iBAAiB,CAAC;AAExE;;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;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAQrD,CAAC;AAsCH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAsBxF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK,MAAM,GAC3C,mBAAmB,CAuBrB;AAED;;;;GAIG;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,CAGrB"}

package/dist/document/commands.d.cts

@@ -0,0 +1,204 @@
+import { PageDocument, Node, ResponsiveStyles, StyleDefinition, AnimationConfig, ActionPipeline, FormConfig, Theme } 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' | 'THEME_UPDATED';
+export interface DocumentChangeEvent {
+    type: DocumentChangeType;
+    timestamp: string;
+    nodeId: string;
+    parentId?: string;
+    previousParentId?: string;
+    index?: number;
+    previousIndex?: number;
+    payload?: Record<string, unknown>;
+}
+export interface CommandResult {
+    document: PageDocument;
+    event: DocumentChangeEvent;
+}
+export interface InsertNodeParams {
+    parentId: string;
+    node: Node;
+    index?: number;
+}
+export interface MoveNodeParams {
+    nodeId: string;
+    targetParentId: string;
+    index?: number;
+}
+export interface UpdatePropsParams {
+    nodeId: string;
+    props: Record<string, unknown>;
+    /**
+     * If true (default), shallow merges new props with existing props.
+     * If false, replaces the entire props object.
+     */
+    merge?: boolean;
+}
+export interface UpdateStyleParams {
+    nodeId: string;
+    styles: ResponsiveStyles | StyleDefinition;
+    /**
+     * Target breakpoint to update directly, or if omitted, applies to whole ResponsiveStyles structure.
+     */
+    breakpoint?: 'base' | 'desktop' | 'tablet' | 'mobile';
+    /**
+     * Target pseudo-state layer (e.g. ':hover', ':active', ':focus') — STORA-221.
+     * When set, `styles` is written to `node.styles.states[state]` instead of a
+     * breakpoint layer, leaving default (breakpoint) values untouched.
+     */
+    state?: string;
+    /**
+     * If true (default), shallow merges style definitions at target breakpoint.
+     * If false, replaces the style definition object.
+     */
+    merge?: boolean;
+}
+export interface RemoveNodeParams {
+    nodeId: string;
+}
+export interface DuplicateNodeParams {
+    nodeId: string;
+    targetParentId?: string;
+    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.
+ */
+export declare function insertNode(document: PageDocument, params: InsertNodeParams): CommandResult;
+/**
+ * 2. Move a node from its current location to a new parent location.
+ * Prevents moving the root node or moving a node into its own descendant tree.
+ * Returns a new PageDocument and a NODE_MOVED event.
+ */
+export declare function moveNode(document: PageDocument, params: MoveNodeParams): CommandResult;
+/**
+ * 3. Update the props of an existing node.
+ * Returns a new PageDocument and a PROPS_UPDATED event.
+ */
+export declare function updateProps(document: PageDocument, params: UpdatePropsParams): CommandResult;
+/**
+ * 4. Update the responsive styles of an existing node.
+ * Supports updating a specific breakpoint ('base', 'desktop', etc.) or the whole ResponsiveStyles object.
+ * Returns a new PageDocument and a STYLE_UPDATED event.
+ */
+export declare function updateStyle(document: PageDocument, params: UpdateStyleParams): CommandResult;
+/**
+ * 5. Remove a node from the document tree.
+ * Prevents removing the root page node.
+ * Returns a new PageDocument and a NODE_REMOVED event.
+ */
+export declare function removeNode(document: PageDocument, params: RemoveNodeParams): CommandResult;
+/**
+ * 6. Duplicate a node and its entire subtree.
+ * Generates fresh unique IDs for all cloned nodes in the subtree, preserves props/styles,
+ * and inserts the duplicate right after the original node (or at specified targetParentId/index).
+ * Returns a new PageDocument and a NODE_DUPLICATED event.
+ */
+export declare function duplicateNode(document: PageDocument, params: DuplicateNodeParams): CommandResult;
+export interface UpdateAnimationParams {
+    nodeId: string;
+    animation: Partial<AnimationConfig> | null;
+    /**
+     * If true (default), shallow merges new animation properties with existing animation config.
+     * If false, replaces the animation config with the provided object.
+     * If animation is null, removes the animation configuration from the node.
+     */
+    merge?: boolean;
+}
+/**
+ * 7. Update the animation configuration of an existing node.
+ * 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;
+export interface UpdateThemeParams {
+    /**
+     * Token changes. With `merge` (default) each group is merged token-by-token and a token
+     * set to `null` is removed; without `merge` the theme is replaced. `null` removes the
+     * whole theme.
+     */
+    theme: {
+        [G in keyof Theme]?: Record<string, string | number | null> | null;
+    } | null;
+    merge?: boolean;
+}
+/**
+ * Update the document-level design tokens (`PageDocument.theme`, STORA-551).
+ * The result is validated with `ThemeSchema`, so unsafe keys/values (CSS injection) throw.
+ * Returns a new PageDocument and a THEME_UPDATED event keyed to the root node.
+ */
+export declare function updateTheme(document: PageDocument, params: UpdateThemeParams): CommandResult;
+//# sourceMappingURL=commands.d.cts.map

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

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

package/dist/document/document-utils.d.cts

@@ -0,0 +1,49 @@
+import { PageDocument, Node } from '@kubuild/schema';
+import type { ComponentRegistryLike } from '../validation/validator.cjs';
+export declare function createBlankDocument(title?: string): PageDocument;
+export declare function findNodeById(rootNode: Node, targetId: string): Node | null;
+export interface CollectedAssetReference {
+    assetId: string;
+    reference: {
+        type: 'asset';
+        assetId: string;
+        filename?: string;
+        mimeType?: string;
+        fallbackUrl?: string;
+    };
+    nodeId: string;
+    propPath: string;
+}
+/**
+ * Collect all AssetReference objects throughout a document tree.
+ */
+export declare function collectAssetReferences(rootNode: Node): CollectedAssetReference[];
+export interface TreeRequirements {
+    requiredComponents: string[];
+    requiredCapabilities: string[];
+}
+/**
+ * Extracts custom component types and capabilities required by a node tree.
+ */
+export declare function extractRequirementsFromTree(rootNode: Node, registry?: ComponentRegistryLike): TreeRequirements;
+/**
+ * Remap asset references in a node tree based on an ID mapping dictionary.
+ * Mutates the node props in place and returns the number of references updated.
+ */
+export declare function remapAssetReferences(rootNode: Node, idMap: Record<string, string> | Map<string, string>): number;
+/**
+ * Remaps all asset references throughout a PageDocument.
+ */
+export declare function remapDocumentAssetReferences(doc: PageDocument, idMap: Record<string, string> | Map<string, string>): PageDocument;
+export interface MissingComponentNodeInfo {
+    nodeId: string;
+    componentType: string;
+    props: Record<string, unknown>;
+    node: Node;
+}
+/**
+ * Finds all nodes in a node tree that reference component types not registered in the host.
+ * This is useful in placeholder mode to inspect missing nodes and their preserved props.
+ */
+export declare function findMissingComponentNodes(rootNode: Node, registry?: ComponentRegistryLike, knownTypes?: string[] | Set<string>): MissingComponentNodeInfo[];
+//# sourceMappingURL=document-utils.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-utils.d.cts","sourceRoot":"","sources":["../../src/document/document-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,IAAI,EAAuC,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,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/document/document-utils.d.ts

@@ -1,5 +1,5 @@
 import { PageDocument, Node } from '@kubuild/schema';
-import type { ComponentRegistryLike } from '../validation/validator';
+import type { ComponentRegistryLike } from '../validation/validator.js';
 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

@@ -1 +1 @@
-{"version":3,"file":"document-utils.d.ts","sourceRoot":"","sources":["../../src/document/document-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,IAAI,EAAuC,MAAM,iBAAiB,CAAC;AAC1F,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"}
+{"version":3,"file":"document-utils.d.ts","sourceRoot":"","sources":["../../src/document/document-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,IAAI,EAAuC,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,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/document/history.d.cts

@@ -0,0 +1,153 @@
+import { PageDocument } from '@kubuild/schema';
+import { DocumentChangeEvent, CommandResult } from './commands.cjs';
+export interface HistoryOptions {
+    /**
+     * Maximum number of historical states stored in the undo stack.
+     * Defaults to 50.
+     */
+    maxHistory?: number;
+}
+export interface HistoryEntry<T> {
+    state: T;
+    event?: DocumentChangeEvent;
+    timestamp: string;
+}
+export interface HistoryState<T> {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoCount: number;
+    redoCount: number;
+    present: T;
+}
+export declare const DEFAULT_MAX_HISTORY = 50;
+/**
+ * Generic History Engine for immutable state transitions.
+ * Maintains undo/redo stacks, enforces maximum history limit,
+ * clears redo stack on new actions, and supports resetting state.
+ */
+export declare class HistoryEngine<T = PageDocument> {
+    private past;
+    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).
+     */
+    get present(): T;
+    /**
+     * Check if undo is available.
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(): boolean;
+    /**
+     * Get total number of states in undo stack.
+     */
+    get undoCount(): number;
+    /**
+     * Get total number of states in redo stack.
+     */
+    get redoCount(): number;
+    /**
+     * Get max history limit.
+     */
+    get limit(): number;
+    /**
+     * 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.
+     */
+    undo(): T | undefined;
+    /**
+     * Redo to the next state in future stack.
+     * Returns the restored state, or undefined if redo is not possible.
+     */
+    redo(): T | undefined;
+    /**
+     * Reset the history engine with a new initial state.
+     * Clears both undo and redo stacks (e.g. when loading a new document).
+     */
+    reset(newState: T): void;
+    /**
+     * Clear both past and future stacks without changing the current state.
+     */
+    clear(): void;
+    /**
+     * Get a snapshot of current history status.
+     */
+    getState(): HistoryState<T>;
+}
+/**
+ * Document History Manager for PageDocument.
+ * Connects HistoryEngine with core command execution.
+ */
+export declare class DocumentHistoryManager {
+    private history;
+    constructor(initialDocument: PageDocument, options?: HistoryOptions);
+    get document(): PageDocument;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /**
+     * Execute a mutation command immutably and record the resulting state and change event in history.
+     */
+    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>;
+}
+//# sourceMappingURL=history.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.cts","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,eAAe,CAAC;AAGnE,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/history.d.ts

@@ -1,5 +1,5 @@
 import { PageDocument } from '@kubuild/schema';
-import { DocumentChangeEvent, CommandResult } from './commands';
+import { DocumentChangeEvent, CommandResult } from './commands.js';
 export interface HistoryOptions {
     /**
      * Maximum number of historical states stored in the undo stack.