@reiwuzen/blocky 1.1.1 → 1.2.0

package/dist/index.d.cts

@@ -0,0 +1,306 @@
+import { Result } from '@reiwuzen/result';
+
+type BlockType = "paragraph" | "heading1" | "heading2" | "heading3" | "bullet" | "number" | "todo" | "equation" | "code";
+type Node = {
+    type: "text";
+    text: string;
+    highlighted?: "yellow" | "green";
+    color?: "red" | 'blue' | 'green';
+    bold?: true;
+    italic?: true;
+    underline?: true;
+    strikethrough?: true;
+    link?: string;
+} | {
+    type: "code";
+    text: string;
+} | {
+    type: "equation";
+    latex: string;
+};
+type BlockMeta<T extends BlockType> = T extends "todo" ? {
+    checked?: true;
+    depth: number;
+} : T extends "bullet" | "number" ? {
+    depth: number;
+} : T extends "code" ? {
+    language?: string;
+} : Record<string, never>;
+type BlockContent<T extends BlockType> = T extends "code" ? [Extract<Node, {
+    type: "code";
+}>] : T extends "equation" ? [Extract<Node, {
+    type: "equation";
+}>] : Node[];
+type Block<T extends BlockType = BlockType> = {
+    id: string;
+    type: T;
+    meta: BlockMeta<T>;
+    content: BlockContent<T>;
+};
+/**
+ * Discriminated Union of Block
+ */
+type AnyBlock = {
+    [K in BlockType]: Block<K>;
+}[BlockType];
+
+/**
+ * Insert a Node at a specific position within block content.
+ *
+ * - nodeIndex: which node to insert into
+ * - offset: char position within that node
+ *
+ * End-of-node (offset === length) naturally becomes an append —
+ * sliceNode produces no right half, incoming merges with left or gets pushed.
+ * No separate append function needed.
+ */
+declare function insertAt<T extends BlockType>(block: AnyBlock, nodeIndex: number, offset: number, incoming: Node): Result<BlockContent<T>>;
+declare function deleteLastChar(block: AnyBlock): Result<BlockContent<BlockType>>;
+/**
+ * Delete content across a selection.
+ * After deletion, left and right boundaries are merged if formats match.
+ *
+ * For code/equation blocks: deletes within the single tuple node's text/latex.
+ */
+declare function deleteRange<T extends BlockType>(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number): Result<BlockContent<T>>;
+/**
+ * Split a block at a given position into two blocks.
+ * The original block keeps content before the cursor.
+ * A new block gets content after the cursor — always of type "paragraph".
+ *
+ * Not supported for code/equation blocks — returns Err.
+ */
+declare function splitBlock(block: AnyBlock, nodeIndex: number, offset: number): Result<[AnyBlock, AnyBlock]>;
+/**
+ * Merge blockB into blockA — blockB's content is appended to blockA's content.
+ * blockA's type and meta are preserved.
+ *
+ * Not supported if either block is code or equation — returns Err.
+ */
+declare function mergeBlocks(blockA: AnyBlock, blockB: AnyBlock): Result<AnyBlock>;
+/**
+ * Replace a selected range with an incoming Node — atomic deleteRange + insertAt.
+ * This is what fires when the user has a selection and types a character.
+ *
+ * Internally chains:
+ *   1. deleteRange  — remove selected content
+ *   2. insertAt     — insert incoming at the start of the deleted range
+ */
+declare function replaceRange<T extends BlockType>(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number, incoming: Node): Result<BlockContent<T>>;
+
+type TextNode = Extract<Node, {
+    type: "text";
+}>;
+type TextFormat = Pick<TextNode, "bold" | "italic" | "underline" | "strikethrough" | "highlighted" | "color" | "link">;
+type NodeSelection = {
+    startIndex: number;
+    startOffset: number;
+    endIndex: number;
+    endOffset: number;
+};
+declare function formatNodes(nodes: Node[], sel: NodeSelection, format: keyof TextFormat, value?: unknown): Result<Node[]>;
+declare function mergeAdjacentNodes(nodes: Node[]): Node[];
+declare const toggleBold: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleItalic: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleUnderline: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleStrikethrough: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleHighlight: (nodes: Node[], sel: NodeSelection, color?: "yellow" | "green") => Result<Node[], string>;
+declare const toggleColor: (nodes: Node[], sel: NodeSelection, color: "red" | "blue" | "green") => Result<Node[], string>;
+declare const setLink: (nodes: Node[], sel: NodeSelection, href: string) => Result<Node[], string>;
+declare const removeLink: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+
+type TransformResult = {
+    block: AnyBlock;
+    converted: boolean;
+};
+/**
+ * Call this when a space is typed.
+ *
+ * Guards (returns converted=false if any fail):
+ *   1. block.type must be "paragraph"
+ *   2. cursorOffset must be ≤ trigger.length + 1
+ *      — ensures the space was typed right after the trigger at position 0
+ *      — blocks mid-text spaces like "hello - " from converting
+ *   3. text must start with a known trigger prefix
+ */
+declare function applyMarkdownTransform(block: AnyBlock, cursorOffset: number): Result<TransformResult>;
+/**
+ * Convert a block to a new type while preserving content as much as possible.
+ *
+ * rich → rich         keep content as-is, update type + meta
+ * rich → code         strip all formatting, concat all text → [CodeNode]
+ * rich → equation     strip all formatting, concat all text → [EquationNode]
+ * code → rich         single TextNode with code.text
+ * equation → rich     single TextNode with equation.latex
+ * code → equation     [EquationNode] with code.text as latex
+ * equation → code     [CodeNode] with equation.latex as text
+ */
+declare function changeBlockType<T extends BlockType>(block: AnyBlock, targetType: T): Result<Block<T>>;
+/**
+ * Toggle the checked state of a todo block.
+ * checked: undefined → checked: true → checked: undefined (cycle)
+ */
+declare function toggleTodo(block: AnyBlock): Result<Block<"todo">>;
+type IndentableBlock = Block<"bullet"> | Block<"number"> | Block<"todo">;
+/**
+ * Increase the depth of a bullet, number, or todo block by 1.
+ * Max depth is 6. Returns Err if block type is not indentable.
+ */
+declare function indentBlock(block: AnyBlock): Result<IndentableBlock>;
+/**
+ * Decrease the depth of a bullet, number, or todo block by 1.
+ * Min depth is 0. Returns Err if block type is not indentable or already at 0.
+ */
+declare function outdentBlock(block: AnyBlock): Result<IndentableBlock>;
+
+/**
+ * Serialize an array of blocks to a JSON string.
+ * Wraps JSON.stringify in Result.try so any circular ref or
+ * other stringify error surfaces as Err rather than throwing.
+ */
+declare function serialize(blocks: AnyBlock[]): Result<string, unknown>;
+/**
+ * Deserialize a JSON string back into AnyBlock[].
+ * Validates:
+ *   - valid JSON
+ *   - top level is an array
+ *   - each item has id (string), type (known BlockType), meta (object), content (array)
+ */
+declare function deserialize(json: string): Result<AnyBlock[], string>;
+/**
+ * Serialize a Node[] to a JSON string — for clipboard copy.
+ * Preserves all formatting.
+ */
+declare function serializeNodes(nodes: Node[]): Result<string, unknown>;
+/**
+ * Deserialize a JSON string back into Node[] — for clipboard paste.
+ * Validates each node shape before returning.
+ */
+declare function deserializeNodes(json: string): Result<Node[], string>;
+/**
+ * Extract plain text from a Node[] — strips all formatting.
+ * text   → text
+ * code   → text
+ * equation → latex
+ */
+declare function toPlainText(nodes: Node[]): string;
+/**
+ * Convert an array of blocks to a markdown string.
+ *
+ * paragraph    → plain inline
+ * heading1-3   → # / ## / ###
+ * bullet       → - (indented by depth)
+ * number       → 1. (indented by depth)
+ * todo         → - [ ] / - [x] (indented by depth)
+ * code         → ```language\n...\n```
+ * equation     → $$...$$ (block equation)
+ */
+declare function toMarkdown(blocks: AnyBlock[]): string;
+
+type CursorPosition = {
+    nodeIndex: number;
+    offset: number;
+};
+/**
+ * Convert a flat UI cursor offset to { nodeIndex, offset }.
+ *
+ * The browser gives a single number representing position in the
+ * concatenated text of the block. This function walks the node array
+ * and finds which node that position falls in and where within it.
+ *
+ * e.g. nodes = ["Hello"(5), " World"(6)]
+ *   flatOffset=0  → { nodeIndex: 0, offset: 0 }
+ *   flatOffset=5  → { nodeIndex: 0, offset: 5 }  (end of first node)
+ *   flatOffset=6  → { nodeIndex: 1, offset: 1 }
+ *   flatOffset=11 → { nodeIndex: 1, offset: 6 }  (end of last node)
+ */
+declare function flatToPosition(block: AnyBlock, flatOffset: number): Result<CursorPosition, string>;
+/**
+ * Convert a flat UI selection { start, end } to NodeSelection.
+ *
+ * The browser gives two flat offsets from window.getSelection().
+ * This calls flatToPosition twice and returns a NodeSelection
+ * ready to pass to toggleBold, formatNodes, deleteRange, etc.
+ *
+ * e.g. nodes = ["Hello"(bold), " World"]
+ *   { start: 3, end: 8 } → { startIndex:0, startOffset:3, endIndex:1, endOffset:3 }
+ */
+declare function flatToSelection(block: AnyBlock, start: number, end: number): Result<NodeSelection, string>;
+/**
+ * Inverse — convert { nodeIndex, offset } back to a flat offset.
+ * Useful after engine operations to restore cursor position in the DOM.
+ */
+declare function positionToFlat(block: AnyBlock, nodeIndex: number, offset: number): Result<number, string>;
+
+type HistoryEntry = {
+    blocks: AnyBlock[];
+    timestamp: number;
+};
+type History = {
+    past: HistoryEntry[];
+    present: HistoryEntry;
+    future: HistoryEntry[];
+};
+/**
+ * Create a new history instance with the given initial blocks.
+ */
+declare function createHistory(initialBlocks: AnyBlock[]): History;
+/**
+ * Push a new state onto the history stack.
+ * Clears the future — same as any editor after a new action post-undo.
+ * Optionally cap the max history size to avoid unbounded memory growth.
+ */
+declare function push(history: History, blocks: AnyBlock[], maxSize?: number): History;
+/**
+ * Move back one step in history.
+ * Returns Err if there is nothing to undo.
+ */
+declare function undo(history: History): Result<History, string>;
+/**
+ * Move forward one step in history.
+ * Returns Err if there is nothing to redo.
+ */
+declare function redo(history: History): Result<History, string>;
+declare const canUndo: (history: History) => boolean;
+declare const canRedo: (history: History) => boolean;
+declare const currentBlocks: (history: History) => AnyBlock[];
+
+/**
+ * Generate a unique block id.
+ * Pass a custom fn to override the default (uuid v7).
+ */
+declare function generateId(fn?: () => string): string;
+/**
+ * Create a new block of the given type with default content and meta.
+ * Optionally pass a custom id generator.
+ *
+ * @param type       - the block type to create
+ * @param idFn       - optional custom id generator (defaults to uuid v7)
+ */
+declare function createBlock<T extends BlockType>(type: T, idFn?: () => string): Result<Block<T>, unknown>;
+declare function insertBlockAfter<T extends BlockType>(blocks: AnyBlock[], afterId: string, type: T, idFn?: () => string): Result<{
+    blocks: AnyBlock[];
+    newId: string;
+}, unknown>;
+declare function deleteBlock(blocks: AnyBlock[], id: string): {
+    blocks: AnyBlock[];
+    prevId: string;
+};
+declare function duplicateBlock(incoming: AnyBlock, newId: string): AnyBlock;
+/**
+ * Move a block up or down by one position in the array.
+ * Returns the same array unchanged if block is already at the boundary.
+ * Returns Err if id not found.
+ */
+declare function moveBlock(blocks: AnyBlock[], id: string, direction: "up" | "down"): Result<AnyBlock[], string>;
+
+/**─── Wrappers ──────────────────────────────────────────────────────────────────
+* Each function runs the content engine operation and returns Result<AnyBlock>
+instead of Result<BlockContent<T>> — caller gets the full updated block back.
+*/
+declare function blockInsertAt(block: AnyBlock, nodeIndex: number, offset: number, incoming: Node): Result<AnyBlock>;
+declare function blockDeleteLastChar(block: AnyBlock): Result<AnyBlock>;
+declare function blockDeleteRange(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number): Result<AnyBlock>;
+declare function blockReplaceRange(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number, incoming: Node): Result<AnyBlock>;
+
+export { type AnyBlock, type Block, type BlockContent, type BlockMeta, type BlockType, type History, type HistoryEntry, type Node, type NodeSelection, applyMarkdownTransform, blockDeleteLastChar, blockDeleteRange, blockInsertAt, blockReplaceRange, canRedo, canUndo, changeBlockType, createBlock, createHistory, currentBlocks, deleteBlock, deleteLastChar, deleteRange, deserialize, deserializeNodes, duplicateBlock, flatToPosition, flatToSelection, formatNodes, generateId, indentBlock, insertAt, insertBlockAfter, mergeAdjacentNodes, mergeBlocks, moveBlock, outdentBlock, positionToFlat, push, redo, removeLink, replaceRange, serialize, serializeNodes, setLink, splitBlock, toMarkdown, toPlainText, toggleBold, toggleColor, toggleHighlight, toggleItalic, toggleStrikethrough, toggleTodo, toggleUnderline, undo };

package/dist/index.d.ts

@@ -1,11 +1,306 @@
-export { insertAt, deleteLastChar, deleteRange, replaceRange, splitBlock, mergeBlocks } from "./engine/content";
-export { formatNodes, toggleBold, toggleItalic, toggleUnderline, toggleStrikethrough, toggleHighlight, toggleColor, setLink, removeLink, mergeAdjacentNodes } from "./engine/format";
-export { applyMarkdownTransform, changeBlockType, toggleTodo, indentBlock, outdentBlock } from "./engine/transform";
-export { serialize, deserialize, serializeNodes, deserializeNodes, toPlainText, toMarkdown } from "./engine/serializer";
-export { flatToPosition, flatToSelection, positionToFlat, } from './engine/cursor';
-export { createHistory, push, undo, redo, canUndo, canRedo, currentBlocks } from "./engine/history";
-export type { History, HistoryEntry } from "./engine/history";
-export { generateId, createBlock, insertBlockAfter, deleteBlock, duplicateBlock, moveBlock } from "./utils/block";
-export type { Node, Block, BlockContent, BlockMeta, BlockType, AnyBlock } from "./types/block";
-export type { NodeSelection } from './engine/format';
-//# sourceMappingURL=index.d.ts.map
+import { Result } from '@reiwuzen/result';
+
+type BlockType = "paragraph" | "heading1" | "heading2" | "heading3" | "bullet" | "number" | "todo" | "equation" | "code";
+type Node = {
+    type: "text";
+    text: string;
+    highlighted?: "yellow" | "green";
+    color?: "red" | 'blue' | 'green';
+    bold?: true;
+    italic?: true;
+    underline?: true;
+    strikethrough?: true;
+    link?: string;
+} | {
+    type: "code";
+    text: string;
+} | {
+    type: "equation";
+    latex: string;
+};
+type BlockMeta<T extends BlockType> = T extends "todo" ? {
+    checked?: true;
+    depth: number;
+} : T extends "bullet" | "number" ? {
+    depth: number;
+} : T extends "code" ? {
+    language?: string;
+} : Record<string, never>;
+type BlockContent<T extends BlockType> = T extends "code" ? [Extract<Node, {
+    type: "code";
+}>] : T extends "equation" ? [Extract<Node, {
+    type: "equation";
+}>] : Node[];
+type Block<T extends BlockType = BlockType> = {
+    id: string;
+    type: T;
+    meta: BlockMeta<T>;
+    content: BlockContent<T>;
+};
+/**
+ * Discriminated Union of Block
+ */
+type AnyBlock = {
+    [K in BlockType]: Block<K>;
+}[BlockType];
+
+/**
+ * Insert a Node at a specific position within block content.
+ *
+ * - nodeIndex: which node to insert into
+ * - offset: char position within that node
+ *
+ * End-of-node (offset === length) naturally becomes an append —
+ * sliceNode produces no right half, incoming merges with left or gets pushed.
+ * No separate append function needed.
+ */
+declare function insertAt<T extends BlockType>(block: AnyBlock, nodeIndex: number, offset: number, incoming: Node): Result<BlockContent<T>>;
+declare function deleteLastChar(block: AnyBlock): Result<BlockContent<BlockType>>;
+/**
+ * Delete content across a selection.
+ * After deletion, left and right boundaries are merged if formats match.
+ *
+ * For code/equation blocks: deletes within the single tuple node's text/latex.
+ */
+declare function deleteRange<T extends BlockType>(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number): Result<BlockContent<T>>;
+/**
+ * Split a block at a given position into two blocks.
+ * The original block keeps content before the cursor.
+ * A new block gets content after the cursor — always of type "paragraph".
+ *
+ * Not supported for code/equation blocks — returns Err.
+ */
+declare function splitBlock(block: AnyBlock, nodeIndex: number, offset: number): Result<[AnyBlock, AnyBlock]>;
+/**
+ * Merge blockB into blockA — blockB's content is appended to blockA's content.
+ * blockA's type and meta are preserved.
+ *
+ * Not supported if either block is code or equation — returns Err.
+ */
+declare function mergeBlocks(blockA: AnyBlock, blockB: AnyBlock): Result<AnyBlock>;
+/**
+ * Replace a selected range with an incoming Node — atomic deleteRange + insertAt.
+ * This is what fires when the user has a selection and types a character.
+ *
+ * Internally chains:
+ *   1. deleteRange  — remove selected content
+ *   2. insertAt     — insert incoming at the start of the deleted range
+ */
+declare function replaceRange<T extends BlockType>(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number, incoming: Node): Result<BlockContent<T>>;
+
+type TextNode = Extract<Node, {
+    type: "text";
+}>;
+type TextFormat = Pick<TextNode, "bold" | "italic" | "underline" | "strikethrough" | "highlighted" | "color" | "link">;
+type NodeSelection = {
+    startIndex: number;
+    startOffset: number;
+    endIndex: number;
+    endOffset: number;
+};
+declare function formatNodes(nodes: Node[], sel: NodeSelection, format: keyof TextFormat, value?: unknown): Result<Node[]>;
+declare function mergeAdjacentNodes(nodes: Node[]): Node[];
+declare const toggleBold: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleItalic: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleUnderline: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleStrikethrough: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+declare const toggleHighlight: (nodes: Node[], sel: NodeSelection, color?: "yellow" | "green") => Result<Node[], string>;
+declare const toggleColor: (nodes: Node[], sel: NodeSelection, color: "red" | "blue" | "green") => Result<Node[], string>;
+declare const setLink: (nodes: Node[], sel: NodeSelection, href: string) => Result<Node[], string>;
+declare const removeLink: (nodes: Node[], sel: NodeSelection) => Result<Node[], string>;
+
+type TransformResult = {
+    block: AnyBlock;
+    converted: boolean;
+};
+/**
+ * Call this when a space is typed.
+ *
+ * Guards (returns converted=false if any fail):
+ *   1. block.type must be "paragraph"
+ *   2. cursorOffset must be ≤ trigger.length + 1
+ *      — ensures the space was typed right after the trigger at position 0
+ *      — blocks mid-text spaces like "hello - " from converting
+ *   3. text must start with a known trigger prefix
+ */
+declare function applyMarkdownTransform(block: AnyBlock, cursorOffset: number): Result<TransformResult>;
+/**
+ * Convert a block to a new type while preserving content as much as possible.
+ *
+ * rich → rich         keep content as-is, update type + meta
+ * rich → code         strip all formatting, concat all text → [CodeNode]
+ * rich → equation     strip all formatting, concat all text → [EquationNode]
+ * code → rich         single TextNode with code.text
+ * equation → rich     single TextNode with equation.latex
+ * code → equation     [EquationNode] with code.text as latex
+ * equation → code     [CodeNode] with equation.latex as text
+ */
+declare function changeBlockType<T extends BlockType>(block: AnyBlock, targetType: T): Result<Block<T>>;
+/**
+ * Toggle the checked state of a todo block.
+ * checked: undefined → checked: true → checked: undefined (cycle)
+ */
+declare function toggleTodo(block: AnyBlock): Result<Block<"todo">>;
+type IndentableBlock = Block<"bullet"> | Block<"number"> | Block<"todo">;
+/**
+ * Increase the depth of a bullet, number, or todo block by 1.
+ * Max depth is 6. Returns Err if block type is not indentable.
+ */
+declare function indentBlock(block: AnyBlock): Result<IndentableBlock>;
+/**
+ * Decrease the depth of a bullet, number, or todo block by 1.
+ * Min depth is 0. Returns Err if block type is not indentable or already at 0.
+ */
+declare function outdentBlock(block: AnyBlock): Result<IndentableBlock>;
+
+/**
+ * Serialize an array of blocks to a JSON string.
+ * Wraps JSON.stringify in Result.try so any circular ref or
+ * other stringify error surfaces as Err rather than throwing.
+ */
+declare function serialize(blocks: AnyBlock[]): Result<string, unknown>;
+/**
+ * Deserialize a JSON string back into AnyBlock[].
+ * Validates:
+ *   - valid JSON
+ *   - top level is an array
+ *   - each item has id (string), type (known BlockType), meta (object), content (array)
+ */
+declare function deserialize(json: string): Result<AnyBlock[], string>;
+/**
+ * Serialize a Node[] to a JSON string — for clipboard copy.
+ * Preserves all formatting.
+ */
+declare function serializeNodes(nodes: Node[]): Result<string, unknown>;
+/**
+ * Deserialize a JSON string back into Node[] — for clipboard paste.
+ * Validates each node shape before returning.
+ */
+declare function deserializeNodes(json: string): Result<Node[], string>;
+/**
+ * Extract plain text from a Node[] — strips all formatting.
+ * text   → text
+ * code   → text
+ * equation → latex
+ */
+declare function toPlainText(nodes: Node[]): string;
+/**
+ * Convert an array of blocks to a markdown string.
+ *
+ * paragraph    → plain inline
+ * heading1-3   → # / ## / ###
+ * bullet       → - (indented by depth)
+ * number       → 1. (indented by depth)
+ * todo         → - [ ] / - [x] (indented by depth)
+ * code         → ```language\n...\n```
+ * equation     → $$...$$ (block equation)
+ */
+declare function toMarkdown(blocks: AnyBlock[]): string;
+
+type CursorPosition = {
+    nodeIndex: number;
+    offset: number;
+};
+/**
+ * Convert a flat UI cursor offset to { nodeIndex, offset }.
+ *
+ * The browser gives a single number representing position in the
+ * concatenated text of the block. This function walks the node array
+ * and finds which node that position falls in and where within it.
+ *
+ * e.g. nodes = ["Hello"(5), " World"(6)]
+ *   flatOffset=0  → { nodeIndex: 0, offset: 0 }
+ *   flatOffset=5  → { nodeIndex: 0, offset: 5 }  (end of first node)
+ *   flatOffset=6  → { nodeIndex: 1, offset: 1 }
+ *   flatOffset=11 → { nodeIndex: 1, offset: 6 }  (end of last node)
+ */
+declare function flatToPosition(block: AnyBlock, flatOffset: number): Result<CursorPosition, string>;
+/**
+ * Convert a flat UI selection { start, end } to NodeSelection.
+ *
+ * The browser gives two flat offsets from window.getSelection().
+ * This calls flatToPosition twice and returns a NodeSelection
+ * ready to pass to toggleBold, formatNodes, deleteRange, etc.
+ *
+ * e.g. nodes = ["Hello"(bold), " World"]
+ *   { start: 3, end: 8 } → { startIndex:0, startOffset:3, endIndex:1, endOffset:3 }
+ */
+declare function flatToSelection(block: AnyBlock, start: number, end: number): Result<NodeSelection, string>;
+/**
+ * Inverse — convert { nodeIndex, offset } back to a flat offset.
+ * Useful after engine operations to restore cursor position in the DOM.
+ */
+declare function positionToFlat(block: AnyBlock, nodeIndex: number, offset: number): Result<number, string>;
+
+type HistoryEntry = {
+    blocks: AnyBlock[];
+    timestamp: number;
+};
+type History = {
+    past: HistoryEntry[];
+    present: HistoryEntry;
+    future: HistoryEntry[];
+};
+/**
+ * Create a new history instance with the given initial blocks.
+ */
+declare function createHistory(initialBlocks: AnyBlock[]): History;
+/**
+ * Push a new state onto the history stack.
+ * Clears the future — same as any editor after a new action post-undo.
+ * Optionally cap the max history size to avoid unbounded memory growth.
+ */
+declare function push(history: History, blocks: AnyBlock[], maxSize?: number): History;
+/**
+ * Move back one step in history.
+ * Returns Err if there is nothing to undo.
+ */
+declare function undo(history: History): Result<History, string>;
+/**
+ * Move forward one step in history.
+ * Returns Err if there is nothing to redo.
+ */
+declare function redo(history: History): Result<History, string>;
+declare const canUndo: (history: History) => boolean;
+declare const canRedo: (history: History) => boolean;
+declare const currentBlocks: (history: History) => AnyBlock[];
+
+/**
+ * Generate a unique block id.
+ * Pass a custom fn to override the default (uuid v7).
+ */
+declare function generateId(fn?: () => string): string;
+/**
+ * Create a new block of the given type with default content and meta.
+ * Optionally pass a custom id generator.
+ *
+ * @param type       - the block type to create
+ * @param idFn       - optional custom id generator (defaults to uuid v7)
+ */
+declare function createBlock<T extends BlockType>(type: T, idFn?: () => string): Result<Block<T>, unknown>;
+declare function insertBlockAfter<T extends BlockType>(blocks: AnyBlock[], afterId: string, type: T, idFn?: () => string): Result<{
+    blocks: AnyBlock[];
+    newId: string;
+}, unknown>;
+declare function deleteBlock(blocks: AnyBlock[], id: string): {
+    blocks: AnyBlock[];
+    prevId: string;
+};
+declare function duplicateBlock(incoming: AnyBlock, newId: string): AnyBlock;
+/**
+ * Move a block up or down by one position in the array.
+ * Returns the same array unchanged if block is already at the boundary.
+ * Returns Err if id not found.
+ */
+declare function moveBlock(blocks: AnyBlock[], id: string, direction: "up" | "down"): Result<AnyBlock[], string>;
+
+/**─── Wrappers ──────────────────────────────────────────────────────────────────
+* Each function runs the content engine operation and returns Result<AnyBlock>
+instead of Result<BlockContent<T>> — caller gets the full updated block back.
+*/
+declare function blockInsertAt(block: AnyBlock, nodeIndex: number, offset: number, incoming: Node): Result<AnyBlock>;
+declare function blockDeleteLastChar(block: AnyBlock): Result<AnyBlock>;
+declare function blockDeleteRange(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number): Result<AnyBlock>;
+declare function blockReplaceRange(block: AnyBlock, startNodeIndex: number, startOffset: number, endNodeIndex: number, endOffset: number, incoming: Node): Result<AnyBlock>;
+
+export { type AnyBlock, type Block, type BlockContent, type BlockMeta, type BlockType, type History, type HistoryEntry, type Node, type NodeSelection, applyMarkdownTransform, blockDeleteLastChar, blockDeleteRange, blockInsertAt, blockReplaceRange, canRedo, canUndo, changeBlockType, createBlock, createHistory, currentBlocks, deleteBlock, deleteLastChar, deleteRange, deserialize, deserializeNodes, duplicateBlock, flatToPosition, flatToSelection, formatNodes, generateId, indentBlock, insertAt, insertBlockAfter, mergeAdjacentNodes, mergeBlocks, moveBlock, outdentBlock, positionToFlat, push, redo, removeLink, replaceRange, serialize, serializeNodes, setLink, splitBlock, toMarkdown, toPlainText, toggleBold, toggleColor, toggleHighlight, toggleItalic, toggleStrikethrough, toggleTodo, toggleUnderline, undo };