@notectl/core 0.0.2 → 0.0.6

package/dist/index.d.ts

@@ -0,0 +1,1816 @@
+/**
+ * @notectl/core — State-first rich text editor Web Component.
+ * @packageDocumentation
+ */
+
+/**
+ * Branded (nominal) types for semantic string distinctions.
+ * Prevents accidental interchange of structurally identical IDs.
+ */
+declare const __brand: unique symbol;
+
+export declare interface AddMarkStep {
+    readonly type: 'addMark';
+    readonly blockId: BlockId;
+    readonly from: number;
+    readonly to: number;
+    readonly mark: Mark;
+    readonly path?: readonly BlockId[];
+}
+
+/** Applies a single step to a document and returns the new document. */
+export declare function applyStep(doc: Document_2, step: Step): Document_2;
+
+export declare interface AttrSpec {
+    readonly default?: string | number | boolean;
+}
+
+export declare interface BlockAttrs {
+    readonly [key: string]: string | number | boolean;
+}
+
+/** Unique identifier for a block node in the document tree. */
+export declare type BlockId = Brand<string, 'BlockId'>;
+
+export declare function blockId(id: string): BlockId;
+
+export declare interface BlockNode {
+    readonly id: BlockId;
+    readonly type: NodeTypeName;
+    readonly attrs?: BlockAttrs;
+    readonly children: readonly ChildNode_2[];
+}
+
+export declare interface BlockquoteConfig {
+    /** When true, a separator is rendered after the blockquote toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class BlockquotePlugin implements Plugin_2 {
+    readonly id = "blockquote";
+    readonly name = "Blockquote";
+    readonly priority = 35;
+    private readonly config;
+    constructor(config?: Partial<BlockquoteConfig>);
+    init(context: PluginContext): void;
+    private registerNodeSpec;
+    private registerCommands;
+    private registerKeymap;
+    private registerInputRule;
+    private registerToolbarItem;
+    /**
+     * Toggles between blockquote and paragraph.
+     * If the block is already a blockquote, resets to paragraph.
+     */
+    private toggleBlockquote;
+    private setBlockType;
+}
+
+export declare interface BoldMark extends Mark {
+    readonly type: MarkTypeName & 'bold';
+}
+
+declare type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+
+/**
+ * Checks if a parent node type can contain a child node type,
+ * using the content rules and group system from NodeSpec.
+ */
+export declare function canContain(registry: SchemaRegistry, parentType: string, childType: string): boolean;
+
+/** Rectangular range of cells within a table. */
+export declare interface CellRange {
+    readonly tableId: BlockId;
+    readonly fromRow: number;
+    readonly fromCol: number;
+    readonly toRow: number;
+    readonly toCol: number;
+}
+
+/** A child of a BlockNode: text, inline element, or nested block. */
+declare type ChildNode_2 = TextNode | InlineNode | BlockNode;
+export { ChildNode_2 as ChildNode }
+
+export declare interface CommandEntry {
+    readonly name: string;
+    readonly handler: CommandHandler;
+    readonly pluginId: string;
+}
+
+export declare type CommandHandler = () => boolean;
+
+/** Registered command name. */
+export declare type CommandName = Brand<string, 'CommandName'>;
+
+export declare function commandName(name: string): CommandName;
+
+/** Describes which children a node type is allowed to contain. */
+export declare interface ContentRule {
+    /** Allowed child types or group names. */
+    readonly allow: readonly string[];
+    readonly min?: number;
+    readonly max?: number;
+}
+
+/** A content segment: either text (with marks) or an inline node. */
+export declare type ContentSegment = {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly marks: readonly Mark[];
+} | {
+    readonly kind: 'inline';
+    readonly node: InlineNode;
+};
+
+/** Creates an HTMLElement with the required `data-block-id` attribute. */
+export declare function createBlockElement(tag: string, blockId: BlockId): HTMLElement;
+
+/** Creates a new {@link BlockNode}. */
+export declare function createBlockNode(type: NodeTypeName, children?: readonly ChildNode_2[], id?: BlockId, attrs?: BlockAttrs): BlockNode;
+
+/** Creates a collapsed selection (cursor) at the given position. */
+export declare function createCollapsedSelection(blockId: BlockId, offset: number): Selection_2;
+
+/** Creates a new empty {@link Document} with a single empty paragraph. */
+export declare function createDocument(children?: readonly BlockNode[]): Document_2;
+
+/** Factory function to create and configure a NotectlEditor instance. */
+export declare function createEditor(config?: NotectlEditorConfig): Promise<NotectlEditor>;
+
+/** Creates a new {@link InlineNode}. */
+export declare function createInlineNode(inlineType: InlineTypeName, attrs?: Readonly<Record<string, string | number | boolean>>): InlineNode;
+
+/** Creates a Position, optionally with a path. */
+export declare function createPosition(blockId: BlockId, offset: number, path?: readonly BlockId[]): Position;
+
+/** Creates a selection with distinct anchor and head. */
+export declare function createSelection(anchor: Position, head: Position): Selection_2;
+
+/** Creates a new {@link TextNode}. */
+export declare function createTextNode(text: string, marks?: readonly Mark[]): TextNode;
+
+export declare type Decoration = InlineDecoration | NodeDecoration | WidgetDecoration;
+
+export declare interface DecorationAttrs {
+    readonly class?: string;
+    readonly style?: string;
+    readonly nodeName?: string;
+    readonly [key: string]: string | undefined;
+}
+
+/**
+ * Immutable set of decorations indexed by block ID.
+ * Provides efficient lookup and merging of decoration collections.
+ */
+export declare class DecorationSet {
+    private readonly byBlock;
+    static readonly empty: DecorationSet;
+    private constructor();
+    /** Creates a DecorationSet from a flat array of decorations. */
+    static create(decorations: readonly Decoration[]): DecorationSet;
+    /** Returns all decorations for a given block. */
+    find(blockId: BlockId): readonly Decoration[];
+    /** Returns only inline decorations for a given block. */
+    findInline(blockId: BlockId): readonly InlineDecoration[];
+    /** Returns only node decorations for a given block. */
+    findNode(blockId: BlockId): readonly NodeDecoration[];
+    /** Returns only widget decorations for a given block. */
+    findWidget(blockId: BlockId): readonly WidgetDecoration[];
+    /** Returns a new DecorationSet with the given decorations added. */
+    add(decorations: readonly Decoration[]): DecorationSet;
+    /** Returns a new DecorationSet with decorations matching the predicate removed. */
+    remove(predicate: (d: Decoration) => boolean): DecorationSet;
+    /** Returns a new DecorationSet merging this set with another. */
+    merge(other: DecorationSet): DecorationSet;
+    /** Checks equality — reference first, then structural comparison. */
+    equals(other: DecorationSet): boolean;
+    /** True if the set contains no decorations. */
+    get isEmpty(): boolean;
+    /**
+     * Maps decorations through document changes described by a transaction.
+     * Decorations that become invalid (e.g. fully deleted range) are removed.
+     * Decorations that span a split point are split into two.
+     */
+    map(tr: Transaction): DecorationSet;
+}
+
+/** Creates the default schema with paragraph nodes and bold/italic/underline marks. */
+export declare function defaultSchema(): Schema;
+
+/** Handles backspace key. */
+export declare function deleteBackward(state: EditorState): Transaction | null;
+
+/** Handles delete key. */
+export declare function deleteForward(state: EditorState): Transaction | null;
+
+/** Deletes the current selection. */
+export declare function deleteSelectionCommand(state: EditorState): Transaction | null;
+
+export declare interface DeleteTextStep {
+    readonly type: 'deleteText';
+    readonly blockId: BlockId;
+    readonly from: number;
+    readonly to: number;
+    readonly deletedText: string;
+    readonly deletedMarks: readonly Mark[];
+    readonly deletedSegments: readonly TextSegment[];
+    readonly path?: readonly BlockId[];
+}
+
+declare interface Document_2 {
+    readonly children: readonly BlockNode[];
+}
+export { Document_2 as Document }
+
+export declare interface DropdownConfig {
+    readonly items: readonly {
+        label: string;
+        command: string;
+        icon?: string;
+    }[];
+}
+
+export declare class EditorState {
+    readonly doc: Document_2;
+    readonly selection: Selection_2;
+    readonly storedMarks: readonly Mark[] | null;
+    readonly schema: Schema;
+    private _blockMap;
+    private _blockOrder;
+    private constructor();
+    /** Creates a new EditorState with default document. */
+    static create(options?: {
+        doc?: Document_2;
+        selection?: Selection_2;
+        schema?: Schema;
+    }): EditorState;
+    /** Creates a TransactionBuilder from this state. */
+    transaction(origin?: 'input' | 'paste' | 'command' | 'history' | 'api'): TransactionBuilder;
+    /** Applies a transaction and returns a new EditorState. */
+    apply(tr: Transaction): EditorState;
+    /** Finds a block by its ID anywhere in the tree. Uses a lazy-built Map for O(1) lookup. */
+    getBlock(blockId: BlockId): BlockNode | undefined;
+    /** Returns leaf-block IDs in depth-first order. Cached after first call. */
+    getBlockOrder(): readonly BlockId[];
+    /** Returns the path (array of block IDs) to a node. */
+    getNodePath(nodeId: BlockId): BlockId[] | undefined;
+    /** Returns the parent BlockNode of a node, or undefined for top-level blocks. */
+    getParent(nodeId: BlockId): BlockNode | undefined;
+    /** Serializes the state to JSON. */
+    toJSON(): object;
+    /** Deserializes a state from JSON. */
+    static fromJSON(json: {
+        doc: Document_2;
+        selection: Selection_2;
+    }, schema?: Schema): EditorState;
+}
+
+export declare class EventBus {
+    private readonly listeners;
+    /** Emits an event to all registered listeners. Errors are caught per listener. */
+    emit<T>(key: EventKey<T>, payload: T): void;
+    /** Subscribes to an event. Returns an unsubscribe function. */
+    on<T>(key: EventKey<T>, callback: PluginEventCallback<T>): () => void;
+    /** Removes a specific listener from an event. */
+    off<T>(key: EventKey<T>, callback: PluginEventCallback<T>): void;
+    /** Removes all listeners for all events. */
+    clear(): void;
+}
+
+declare type EventCallback<T> = (payload: T) => void;
+
+/** Type-safe event key for compile-time payload checking. */
+export declare class EventKey<T> {
+    readonly id: string;
+    readonly _type: T;
+    constructor(id: string);
+}
+
+declare type EventMap = {
+    stateChange: StateChangeEvent;
+    selectionChange: {
+        selection: Selection_2;
+    };
+    focus: undefined;
+    blur: undefined;
+    ready: undefined;
+};
+
+export declare interface FeatureConfig {
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: boolean;
+}
+
+/**
+ * Finds a block node by ID anywhere in the document tree (recursive DFS).
+ */
+export declare function findNode(doc: Document_2, nodeId: string): BlockNode | undefined;
+
+/**
+ * Finds the path (array of block IDs) to a node by its ID.
+ * Performs recursive DFS through the document tree.
+ */
+export declare function findNodePath(doc: Document_2, nodeId: string): string[] | undefined;
+
+/**
+ * Finds a block node and returns it together with its path.
+ */
+export declare function findNodeWithPath(doc: Document_2, nodeId: string): {
+    node: BlockNode;
+    path: string[];
+} | undefined;
+
+/**
+ * Finds table context for a given block ID.
+ * Returns null if the block is not inside a table.
+ */
+export declare function findTableContext(state: EditorState, blockId: BlockId): TableContext | null;
+
+/** Fira Code — a monospace font with programming ligatures. */
+export declare const FIRA_CODE: FontDefinition;
+
+/** Fira Sans — a humanist sans-serif typeface. */
+export declare const FIRA_SANS: FontDefinition;
+
+export declare interface FontConfig {
+    /**
+     * Fonts available in the editor. System fonts require no `fontFaces`.
+     * Custom fonts with `fontFaces` get their `@font-face` rules auto-injected.
+     *
+     * Use `STARTER_FONTS` for a pre-configured set of fonts:
+     * ```ts
+     * new FontPlugin({ fonts: [...STARTER_FONTS] })
+     * ```
+     */
+    readonly fonts: readonly FontDefinition[];
+    /**
+     * Name of the font that acts as the editor's default.
+     * Selecting this font removes the mark (since the editor already uses it).
+     * Defaults to the first font in the list.
+     */
+    readonly defaultFont?: string;
+    /** When true, a separator is rendered after the font toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+/** Defines a font available in the editor. */
+export declare interface FontDefinition {
+    /** Display name shown in the toolbar dropdown. */
+    readonly name: string;
+    /** CSS `font-family` value, e.g. `"'Fira Code', monospace"`. */
+    readonly family: string;
+    /** Font category for grouping in the UI. */
+    readonly category?: 'serif' | 'sans-serif' | 'monospace' | 'display' | 'handwriting';
+    /**
+     * Optional `@font-face` descriptors. When provided, the plugin
+     * auto-injects the corresponding CSS rules into the document.
+     */
+    readonly fontFaces?: readonly FontFaceDescriptor[];
+}
+
+/** Describes a single @font-face source. */
+export declare interface FontFaceDescriptor {
+    /** CSS `src` value, e.g. `"url('/fonts/My.woff2') format('woff2')"`. */
+    readonly src: string;
+    /** Font weight, e.g. `'400'` or `'300 700'` for variable fonts. */
+    readonly weight?: string;
+    /** Font style, e.g. `'normal'` or `'italic'`. */
+    readonly style?: string;
+    /** Font display strategy. Defaults to `'swap'`. */
+    readonly display?: string;
+}
+
+export declare class FontPlugin implements Plugin_2 {
+    readonly id = "font";
+    readonly name = "Font";
+    readonly priority = 22;
+    private readonly config;
+    private injectedStyleElement;
+    private context;
+    private comboLabel;
+    constructor(config: FontConfig);
+    init(context: PluginContext): void;
+    destroy(): void;
+    onStateChange(_oldState: EditorState, newState: EditorState, _tr: Transaction): void;
+    private registerMarkSpec;
+    private registerCommands;
+    private get defaultFont();
+    private registerToolbarItem;
+    private updateComboLabel;
+    private resolveFontName;
+    private isFontActive;
+    getActiveFont(state: EditorState): string | null;
+    applyFont(context: PluginContext, state: EditorState, family: string): boolean;
+    private removeFont;
+    /** Finds the first font mark in a block's text range (for proper step inversion). */
+    private findFontMarkInRange;
+    private injectFontFaces;
+    private dismissPopup;
+    private renderFontPopup;
+    private createFontItem;
+}
+
+export declare interface FontSizeConfig {
+    /**
+     * Preset sizes shown in the font size dropdown.
+     * Must contain positive integers. Values are sorted and deduplicated automatically.
+     * Defaults to {@link DEFAULT_FONT_SIZES} when omitted or empty.
+     */
+    readonly sizes?: readonly number[];
+    /**
+     * The base font size that text has when no fontSize mark is applied.
+     * Shown as the initial value in the toolbar combo and used as the
+     * "neutral" size — selecting it removes the mark instead of applying one.
+     * Defaults to 16.
+     */
+    readonly defaultSize?: number;
+    /** When true, a separator is rendered after the fontSize toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class FontSizePlugin implements Plugin_2 {
+    readonly id = "fontSize";
+    readonly name = "Font Size";
+    readonly priority = 21;
+    private readonly config;
+    private readonly sizes;
+    private readonly defaultSize;
+    private context;
+    private comboLabel;
+    constructor(config?: Partial<FontSizeConfig>);
+    init(context: PluginContext): void;
+    destroy(): void;
+    onStateChange(_oldState: EditorState, newState: EditorState, _tr: Transaction): void;
+    private registerMarkSpec;
+    private registerCommands;
+    private registerKeymaps;
+    private registerToolbarItem;
+    private updateComboLabel;
+    private isFontSizeActive;
+    private getActiveSize;
+    private getActiveSizeNumeric;
+    private applyFontSize;
+    private removeFontSize;
+    private stepFontSize;
+    private getNextPresetSize;
+    private dismissPopup;
+    private renderFontSizePopup;
+    private selectSize;
+}
+
+/**
+ * Formats a keymap binding string into a human-readable shortcut,
+ * using platform-appropriate modifier symbols (⌘ on Mac, Ctrl on others).
+ *
+ * @example formatShortcut('Mod-B') → "Ctrl+B" or "⌘B"
+ * @example formatShortcut('Mod-Shift-X') → "Ctrl+Shift+X" or "⌘⇧X"
+ */
+export declare function formatShortcut(binding: string): string;
+
+/** Returns only the BlockNode children of a block. */
+export declare function getBlockChildren(node: BlockNode): readonly BlockNode[];
+
+/** Returns the length of a block's inline content (InlineNodes count as 1). */
+export declare function getBlockLength(block: BlockNode): number;
+
+/** Returns the marks active at the given offset (empty for InlineNode offsets). */
+export declare function getBlockMarksAtOffset(block: BlockNode, offset: number): readonly Mark[];
+
+/** Extracts plain text from a block (InlineNodes are skipped). */
+export declare function getBlockText(block: BlockNode): string;
+
+/** Returns the content at a specific offset: text char, inline node, or null. */
+export declare function getContentAtOffset(block: BlockNode, offset: number): {
+    readonly kind: 'text';
+    readonly char: string;
+    readonly marks: readonly Mark[];
+} | {
+    readonly kind: 'inline';
+    readonly node: InlineNode;
+} | null;
+
+/** Returns the inline content children (TextNode | InlineNode) of a block. */
+export declare function getInlineChildren(node: BlockNode): readonly (TextNode | InlineNode)[];
+
+/** Returns only the TextNode children of a block. */
+export declare function getTextChildren(node: BlockNode): readonly TextNode[];
+
+export declare interface GridPickerConfig {
+    readonly maxRows: number;
+    readonly maxCols: number;
+    onSelect(rows: number, cols: number): void;
+}
+
+/** Returns true if the mark set contains a mark of the given type. */
+export declare function hasMark(marks: readonly Mark[], markType: MarkTypeName): boolean;
+
+export declare interface HeadingConfig {
+    /** Which heading levels to enable. Defaults to [1, 2, 3, 4, 5, 6]. */
+    readonly levels: readonly HeadingLevel[];
+    /** When true, a separator is rendered after the heading toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export declare class HeadingPlugin implements Plugin_2 {
+    readonly id = "heading";
+    readonly name = "Heading";
+    readonly priority = 30;
+    private readonly config;
+    private context;
+    private comboLabel;
+    constructor(config?: Partial<HeadingConfig>);
+    init(context: PluginContext): void;
+    destroy(): void;
+    onStateChange(_oldState: EditorState, newState: EditorState, _tr: Transaction): void;
+    private registerNodeSpecs;
+    private registerCommands;
+    private registerKeymaps;
+    private registerInputRules;
+    private registerToolbarItem;
+    private updateComboLabel;
+    private getActiveLabel;
+    private dismissPopup;
+    private renderHeadingPopup;
+    private createPickerItem;
+    /**
+     * Toggles between a special block type (title/subtitle) and paragraph.
+     * If the block is already that type, resets to paragraph.
+     */
+    private toggleSpecialBlock;
+    /**
+     * Toggles between heading (at given level) and paragraph.
+     * If the block is already a heading at the same level, resets to paragraph.
+     */
+    private toggleHeading;
+    private setBlockType;
+}
+
+export declare interface HighlightConfig {
+    /**
+     * Restricts the color picker to a specific set of hex colors.
+     * Each value must be a valid hex color code (`#RGB` or `#RRGGBB`).
+     * Duplicates are removed automatically (case-insensitive).
+     * When omitted, the full default palette is shown.
+     */
+    readonly colors?: readonly string[];
+    /** When true, a separator is rendered after the highlight toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class HighlightPlugin implements Plugin_2 {
+    readonly id = "highlight";
+    readonly name = "Highlight";
+    readonly priority = 24;
+    private readonly config;
+    private readonly colors;
+    constructor(config?: Partial<HighlightConfig>);
+    init(context: PluginContext): void;
+    private registerMarkSpec;
+    private registerCommands;
+    private registerToolbarItem;
+    private isHighlightActive;
+    private getActiveColor;
+    private applyHighlight;
+    private removeHighlight;
+    private renderHighlightPopup;
+}
+
+export declare class HistoryManager {
+    private undoStack;
+    private redoStack;
+    private readonly groupTimeoutMs;
+    private readonly maxDepth;
+    private lastOrigin;
+    constructor(options?: {
+        groupTimeoutMs?: number;
+        maxDepth?: number;
+    });
+    /**
+     * Pushes a transaction onto the undo stack.
+     * Groups consecutive input transactions within the timeout window.
+     */
+    push(tr: Transaction): void;
+    /** Undoes the last group and returns the new state with transaction, or null if nothing to undo. */
+    undo(state: EditorState): HistoryResult | null;
+    /** Redoes the last undone group and returns the new state with transaction, or null if nothing to redo. */
+    redo(state: EditorState): HistoryResult | null;
+    /** Returns true if there are entries to undo. */
+    canUndo(): boolean;
+    /** Returns true if there are entries to redo. */
+    canRedo(): boolean;
+    /** Clears all history. */
+    clear(): void;
+    /**
+     * Checks if consecutive transactions are of the same "type" for grouping.
+     * Groups text insertion together, deletion together, but not mixed.
+     */
+    private isSameInputType;
+}
+
+export declare interface HistoryResult {
+    readonly state: EditorState;
+    readonly transaction: Transaction;
+}
+
+export declare interface HorizontalRuleConfig {
+    /** When true, a separator is rendered after the toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class HorizontalRulePlugin implements Plugin_2 {
+    readonly id = "horizontal-rule";
+    readonly name = "Horizontal Rule";
+    readonly priority = 40;
+    private readonly config;
+    constructor(config?: Partial<HorizontalRuleConfig>);
+    init(context: PluginContext): void;
+    private registerNodeSpec;
+    private registerCommands;
+    private registerInputRule;
+    private registerToolbarItem;
+    /**
+     * Inserts a horizontal rule after the current block,
+     * followed by a new paragraph for continued editing.
+     */
+    private insertHorizontalRule;
+}
+
+export declare interface InlineDecoration {
+    readonly type: 'inline';
+    readonly blockId: BlockId;
+    readonly from: number;
+    readonly to: number;
+    readonly attrs: DecorationAttrs;
+}
+
+/** Creates an inline decoration for a text range within a block. */
+export declare function inlineDecoration(blockId: BlockId, from: number, to: number, attrs: DecorationAttrs): InlineDecoration;
+
+/** Atomic inline element (width 1 in offset space). */
+export declare interface InlineNode {
+    readonly type: 'inline';
+    readonly inlineType: InlineTypeName;
+    readonly attrs: Readonly<Record<string, string | number | boolean>>;
+}
+
+/** Plugins augment this interface to register typed inline node attributes. */
+export declare interface InlineNodeAttrRegistry {
+}
+
+/** Resolves typed attributes for known inline node types, falls back for unknown. */
+export declare type InlineNodeAttrsFor<T extends string> = T extends keyof InlineNodeAttrRegistry ? InlineNodeAttrRegistry[T] : Record<string, string | number | boolean>;
+
+export declare interface InlineNodeSpec<T extends string = string> {
+    readonly type: T;
+    /** Renders the InlineNode as a DOM element (should set contentEditable="false"). */
+    toDOM(node: InlineNode): HTMLElement;
+    /** Allowed attributes with defaults. */
+    readonly attrs?: Readonly<Record<string, AttrSpec>>;
+    /** Group membership (default: 'inline'). For content rules. */
+    readonly group?: string;
+}
+
+export declare function inlineType(name: string): InlineTypeName;
+
+/** Semantic name for an inline node type (e.g. 'image', 'mention'). */
+export declare type InlineTypeName = Brand<string, 'InlineTypeName'>;
+
+export declare interface InputRule {
+    /** Must end with `$` — matched against the text before the cursor. */
+    readonly pattern: RegExp;
+    /** Returns a transaction to apply, or null to skip this rule. */
+    handler(state: EditorState, match: RegExpMatchArray, start: number, end: number): Transaction | null;
+}
+
+export declare interface InsertInlineNodeStep {
+    readonly type: 'insertInlineNode';
+    readonly blockId: BlockId;
+    readonly offset: number;
+    readonly node: InlineNode;
+    readonly path?: readonly BlockId[];
+}
+
+export declare interface InsertNodeStep {
+    readonly type: 'insertNode';
+    readonly parentPath: readonly BlockId[];
+    readonly index: number;
+    readonly node: BlockNode;
+}
+
+/** Inserts text at the current selection, replacing any selected range. */
+export declare function insertTextCommand(state: EditorState, text: string, origin?: 'input' | 'paste'): Transaction;
+
+export declare interface InsertTextStep {
+    readonly type: 'insertText';
+    readonly blockId: BlockId;
+    readonly offset: number;
+    readonly text: string;
+    readonly marks: readonly Mark[];
+    readonly segments?: readonly TextSegment[];
+    readonly path?: readonly BlockId[];
+}
+
+/** Inverts a single step for undo. */
+export declare function invertStep(step: Step): Step;
+
+/** Inverts an entire transaction (reverses step order and swaps selections). */
+export declare function invertTransaction(tr: Transaction): Transaction;
+
+/** Checks whether a value is a {@link BlockNode}. */
+export declare function isBlockNode(node: unknown): node is BlockNode;
+
+/** Returns true if the selection is collapsed (cursor with no range). */
+export declare function isCollapsed(sel: Selection_2): boolean;
+
+/**
+ * Returns true if the selection direction is forward (anchor before head).
+ * When anchor and head are in the same block, compares offsets.
+ * Cross-block ordering uses document order (not determinable here — caller provides block order).
+ */
+export declare function isForward(sel: Selection_2, blockOrder?: readonly BlockId[]): boolean;
+
+/** Checks whether a value is an {@link InlineNode}. */
+export declare function isInlineNode(node: unknown): node is InlineNode;
+
+/** Narrows an InlineNode to a typed variant with known attributes. */
+export declare function isInlineNodeOfType<T extends keyof InlineNodeAttrRegistry>(node: InlineNode, inlineNodeType: T): node is InlineNode & {
+    readonly inlineType: T;
+    readonly attrs: InlineNodeAttrRegistry[T];
+};
+
+/** Checks whether a block is inside an isolating node (e.g. table_cell). */
+export declare function isInsideIsolating(state: EditorState, blockId: BlockId): boolean;
+
+/** Checks whether a block is inside a table. */
+export declare function isInsideTable(state: EditorState, blockId: BlockId): boolean;
+
+/** Returns true if a block has only inline content (TextNodes and InlineNodes). */
+export declare function isLeafBlock(node: BlockNode): boolean;
+
+/** Checks if a mark is active at the current selection. */
+export declare function isMarkActive(state: EditorState, markType: MarkType): boolean;
+
+/** Checks whether the given mark type is allowed by the schema. */
+export declare function isMarkAllowed(schema: Schema, markType: string): boolean;
+
+/** Narrows a Mark to a typed variant with known attributes. */
+export declare function isMarkOfType<T extends keyof MarkAttrRegistry>(mark: Mark, type: T): mark is Mark & {
+    readonly type: T;
+    readonly attrs: MarkAttrRegistry[T];
+};
+
+/** Narrows a BlockNode to a typed variant with known attributes. */
+export declare function isNodeOfType<T extends keyof NodeAttrRegistry>(node: BlockNode, type: T): node is BlockNode & {
+    readonly type: T;
+    readonly attrs: NodeAttrRegistry[T];
+};
+
+/** Checks whether a value is a {@link TextNode}. */
+export declare function isTextNode(node: unknown): node is TextNode;
+
+export declare interface ItalicMark extends Mark {
+    readonly type: MarkTypeName & 'italic';
+}
+
+/**
+ * A mapping from key descriptors to handler functions.
+ * Key descriptor format: `"Mod-B"`, `"Mod-Shift-1"`, `"Tab"`, `"Enter"`.
+ * `Mod` resolves to Ctrl on Linux/Windows and Cmd on macOS.
+ */
+export declare type Keymap = Readonly<Record<string, KeymapHandler>>;
+
+/**
+ * Keymap types for plugin-registered keyboard shortcuts.
+ */
+export declare type KeymapHandler = () => boolean;
+
+export declare interface LinkConfig {
+    /** Whether to add rel="noopener noreferrer" and target="_blank" by default. */
+    readonly openInNewTab: boolean;
+    /** When true, a separator is rendered after the link toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class LinkPlugin implements Plugin_2 {
+    readonly id = "link";
+    readonly name = "Link";
+    readonly priority = 25;
+    private readonly config;
+    constructor(config?: Partial<LinkConfig>);
+    init(context: PluginContext): void;
+    private registerMarkSpec;
+    private registerCommands;
+    private registerKeymap;
+    private registerToolbarItem;
+    private isLinkActive;
+    private toggleLink;
+    private addLink;
+    private removeLink;
+    private renderLinkPopup;
+}
+
+export declare interface ListConfig {
+    /** Which list types to enable. Defaults to all. */
+    readonly types: readonly ListType[];
+    /** Maximum indent depth. Defaults to 4. */
+    readonly maxIndent: number;
+    /** When true, a separator is rendered after the last list toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class ListPlugin implements Plugin_2 {
+    readonly id = "list";
+    readonly name = "List";
+    readonly priority = 35;
+    private readonly config;
+    constructor(config?: Partial<ListConfig>);
+    init(context: PluginContext): void;
+    private registerNodeSpec;
+    private registerCommands;
+    private registerKeymaps;
+    private registerInputRules;
+    private registerToolbarItems;
+    private toggleList;
+    private indent;
+    private outdent;
+    private setIndent;
+    private toggleChecked;
+    /**
+     * Handles Backspace at the start of a list item.
+     * Converts the list item back to a paragraph, preserving text.
+     */
+    private handleBackspace;
+    /**
+     * Handles Enter inside a list item.
+     * Empty item → exit list (convert to paragraph).
+     * Non-empty item → split and create a new list item with the same type.
+     */
+    private handleEnter;
+    private isListActive;
+    private getEnabledTypes;
+}
+
+export declare type ListType = 'bullet' | 'ordered' | 'checklist';
+
+export declare interface Mark {
+    readonly type: MarkTypeName;
+    readonly attrs?: Readonly<Record<string, string | number | boolean>>;
+}
+
+/** Plugins augment this interface to register typed mark attributes. */
+export declare interface MarkAttrRegistry {
+    bold: Record<string, never>;
+    italic: Record<string, never>;
+    underline: Record<string, never>;
+}
+
+/** Resolves typed attributes for known mark types, falls back for unknown. */
+export declare type MarkAttrsFor<T extends string> = T extends keyof MarkAttrRegistry ? MarkAttrRegistry[T] : Record<string, string | number | boolean>;
+
+/** Checks whether two mark arrays contain the same marks (order-independent). */
+export declare function markSetsEqual(a: readonly Mark[], b: readonly Mark[]): boolean;
+
+export declare interface MarkSpec<T extends string = string> {
+    readonly type: T;
+    /** Wraps text content in a DOM element for this mark. */
+    toDOM(mark: Omit<Mark, 'attrs'> & {
+        readonly attrs: MarkAttrsFor<T>;
+    }): HTMLElement;
+    /** Nesting priority — lower rank renders closer to the text content. */
+    readonly rank?: number;
+    readonly attrs?: Readonly<Record<string, AttrSpec>>;
+}
+
+/** @deprecated Use {@link MarkTypeName} for new code. */
+export declare type MarkType = MarkTypeName;
+
+export declare function markType(name: string): MarkTypeName;
+
+/** Semantic name for a mark type (e.g. 'bold', 'link'). */
+export declare type MarkTypeName = Brand<string, 'MarkTypeName'>;
+
+/** Merges the current block with the previous block, respecting isolating boundaries. */
+export declare function mergeBlockBackward(state: EditorState): Transaction | null;
+
+export declare interface MergeBlocksStep {
+    readonly type: 'mergeBlocks';
+    readonly targetBlockId: BlockId;
+    readonly sourceBlockId: BlockId;
+    readonly targetLengthBefore: number;
+    readonly path?: readonly BlockId[];
+}
+
+export declare type MiddlewareNext = (tr: Transaction) => void;
+
+/** Plugins augment this interface to register typed node attributes. */
+export declare interface NodeAttrRegistry {
+    paragraph: {
+        textAlign?: TextAlignment;
+    };
+}
+
+/** Resolves typed attributes for known node types, falls back for unknown. */
+export declare type NodeAttrsFor<T extends string> = T extends keyof NodeAttrRegistry ? NodeAttrRegistry[T] : Record<string, string | number | boolean>;
+
+export declare interface NodeDecoration {
+    readonly type: 'node';
+    readonly blockId: BlockId;
+    readonly attrs: DecorationAttrs;
+}
+
+/** Creates a node decoration that applies to a whole block element. */
+export declare function nodeDecoration(blockId: BlockId, attrs: DecorationAttrs): NodeDecoration;
+
+/** A selection that selects an entire node (e.g. for table selection). */
+export declare interface NodeSelection {
+    readonly type: 'node';
+    readonly nodeId: BlockId;
+    readonly path: readonly BlockId[];
+}
+
+export declare interface NodeSpec<T extends string = string> {
+    readonly type: T;
+    /** Renders the block to a DOM element. Must set `data-block-id` on the root. */
+    toDOM(node: Omit<BlockNode, 'attrs'> & {
+        readonly attrs: NodeAttrsFor<T>;
+    }): HTMLElement;
+    readonly attrs?: Readonly<Record<string, AttrSpec>>;
+    /** If true, the node contains no editable text (e.g. Image, HR). */
+    readonly isVoid?: boolean;
+    /** Content model: which children this node can contain. */
+    readonly content?: ContentRule;
+    /** Group membership: 'block' | 'inline' | custom. */
+    readonly group?: string;
+    /** If true, selection cannot cross this node's boundary (e.g. table_cell). */
+    readonly isolating?: boolean;
+}
+
+/** @deprecated Use {@link NodeTypeName} for new code. */
+export declare type NodeType = NodeTypeName;
+
+export declare function nodeType(name: string): NodeTypeName;
+
+/** Semantic name for a node type (e.g. 'paragraph', 'heading'). */
+export declare type NodeTypeName = Brand<string, 'NodeTypeName'>;
+
+export declare interface NodeView {
+    /** Root DOM element. Must have `data-block-id` set. */
+    readonly dom: HTMLElement;
+    /** Where text children are rendered. Null for void nodes. */
+    readonly contentDOM: HTMLElement | null;
+    /** For nodes with multiple content areas (e.g. table cells), returns the DOM for a specific child. */
+    getContentDOM?(childId: string): HTMLElement | null;
+    /** Returns true if the update was handled, false to re-create the NodeView. */
+    update?(node: BlockNode): boolean;
+    destroy?(): void;
+    selectNode?(): void;
+    deselectNode?(): void;
+}
+
+export declare type NodeViewFactory = (node: BlockNode, getState: () => EditorState, dispatch: (tr: Transaction) => void) => NodeView;
+
+/**
+ * Normalizes a KeyboardEvent into a consistent key descriptor string.
+ * Format: `"Mod-Shift-Alt-Key"` where Mod = Ctrl/Cmd.
+ */
+export declare function normalizeKeyDescriptor(e: KeyboardEvent): string;
+
+export declare class NotectlEditor extends HTMLElement {
+    private view;
+    private pluginManager;
+    private contentElement;
+    private editorWrapper;
+    private topPluginContainer;
+    private bottomPluginContainer;
+    private announcer;
+    private config;
+    private eventListeners;
+    private readyPromiseResolve;
+    private readonly readyPromise;
+    private initialized;
+    private preInitPlugins;
+    constructor();
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    /** Registers a plugin before initialization. */
+    registerPlugin(plugin: Plugin_2): void;
+    /** Initializes the editor with the given config. */
+    init(config?: NotectlEditorConfig): Promise<void>;
+    /** Returns the document as JSON. */
+    getJSON(): Document_2;
+    /** Sets the document from JSON. */
+    setJSON(doc: Document_2): void;
+    /** Returns sanitized HTML representation of the document. */
+    getHTML(): string;
+    /** Sets content from HTML (sanitized). */
+    setHTML(html: string): void;
+    /** Returns plain text content. */
+    getText(): string;
+    /** Returns true if the editor is empty (single empty paragraph). */
+    isEmpty(): boolean;
+    readonly commands: {
+        toggleBold: () => boolean;
+        toggleItalic: () => boolean;
+        toggleUnderline: () => boolean;
+        undo: () => void | undefined;
+        redo: () => void | undefined;
+        selectAll: () => void;
+    };
+    /** Checks whether a command can be executed. */
+    can(): {
+        toggleBold: () => boolean;
+        toggleItalic: () => boolean;
+        toggleUnderline: () => boolean;
+        undo: () => boolean;
+        redo: () => boolean;
+    };
+    /** Executes a named command registered by a plugin. */
+    executeCommand(name: string): boolean;
+    /** Configures a plugin at runtime. */
+    configurePlugin(pluginId: string, config: PluginConfig): void;
+    /** Returns the current editor state. */
+    getState(): EditorState;
+    /** Dispatches a transaction (routed through middleware if any). */
+    dispatch(tr: Transaction): void;
+    /** Registers an event listener. */
+    on<K extends keyof EventMap>(event: K, callback: EventCallback<EventMap[K]>): void;
+    /** Removes an event listener. */
+    off<K extends keyof EventMap>(event: K, callback: EventCallback<EventMap[K]>): void;
+    /** Waits for the editor to be ready. */
+    whenReady(): Promise<void>;
+    /** Updates configuration at runtime. */
+    configure(config: Partial<NotectlEditorConfig>): void;
+    /** Cleans up the editor. Awaiting ensures async plugin teardown completes. */
+    destroy(): Promise<void>;
+    /**
+     * Processes the declarative `toolbar` config: registers a ToolbarPlugin
+     * with layout groups, then registers all plugins from the toolbar groups.
+     */
+    private processToolbarConfig;
+    /**
+     * Auto-registers TextFormattingPlugin if no plugin with id 'text-formatting'
+     * was explicitly registered. Uses the `features` config to determine which marks to enable.
+     */
+    private ensureTextFormattingPlugin;
+    private emit;
+    private onStateChange;
+    private updateEmptyState;
+    private announceFormatChange;
+    private replaceState;
+    private blockToHTML;
+    private textNodeToHTML;
+    private getMarkOrder;
+    private escapeHTML;
+    private parseHTMLToDocument;
+    private parseElementToTextNodes;
+    private walkElement;
+}
+
+export declare interface NotectlEditorConfig {
+    /** Controls which inline marks are enabled. Used to auto-configure TextFormattingPlugin. */
+    features?: Partial<TextFormattingConfig>;
+    plugins?: Plugin_2[];
+    /**
+     * Declarative toolbar layout. Each inner array is a visual group;
+     * separators are rendered between groups. Order = array order.
+     * When set, a ToolbarPlugin is created internally — do not add one to `plugins`.
+     */
+    toolbar?: ReadonlyArray<ReadonlyArray<Plugin_2>>;
+    placeholder?: string;
+    readonly?: boolean;
+    autofocus?: boolean;
+    maxHistoryDepth?: number;
+}
+
+declare interface Plugin_2<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+    readonly id: string;
+    readonly name: string;
+    readonly priority?: number;
+    readonly dependencies?: readonly string[];
+    init(context: PluginContext): void | Promise<void>;
+    destroy?(): void | Promise<void>;
+    onStateChange?(oldState: EditorState, newState: EditorState, tr: Transaction): void;
+    onConfigure?(config: TConfig): void;
+    /** Called after ALL plugins have been initialized. */
+    onReady?(): void | Promise<void>;
+    /**
+     * Returns decorations for the given state.
+     * Called after state.apply() but BEFORE reconciliation.
+     * Plugins should cache and only recompute when needed.
+     */
+    decorations?(state: EditorState, tr?: Transaction): DecorationSet;
+}
+export { Plugin_2 as Plugin }
+
+export declare type PluginConfig = Record<string, unknown>;
+
+export declare interface PluginContext {
+    getState(): EditorState;
+    dispatch(transaction: Transaction): void;
+    getContainer(): HTMLElement;
+    getPluginContainer(position: 'top' | 'bottom'): HTMLElement;
+    registerCommand(name: string, handler: CommandHandler): void;
+    executeCommand(name: string): boolean;
+    getEventBus(): PluginEventBus;
+    registerMiddleware(middleware: TransactionMiddleware, priority?: number): void;
+    registerService<T>(key: ServiceKey<T>, service: T): void;
+    getService<T>(key: ServiceKey<T>): T | undefined;
+    updateConfig(config: PluginConfig): void;
+    registerNodeSpec<T extends string>(spec: NodeSpec<T>): void;
+    registerMarkSpec<T extends string>(spec: MarkSpec<T>): void;
+    registerNodeView(type: string, factory: NodeViewFactory): void;
+    registerKeymap(keymap: Keymap): void;
+    registerInputRule(rule: InputRule): void;
+    registerToolbarItem(item: ToolbarItem): void;
+    registerInlineNodeSpec<T extends string>(spec: InlineNodeSpec<T>): void;
+    getSchemaRegistry(): SchemaRegistry;
+}
+
+export declare interface PluginEventBus {
+    emit<T>(key: EventKey<T>, payload: T): void;
+    on<T>(key: EventKey<T>, callback: PluginEventCallback<T>): () => void;
+    off<T>(key: EventKey<T>, callback: PluginEventCallback<T>): void;
+}
+
+export declare type PluginEventCallback<T = unknown> = (payload: T) => void;
+
+/** Unique identifier for a plugin. */
+export declare type PluginId = Brand<string, 'PluginId'>;
+
+export declare function pluginId(id: string): PluginId;
+
+export declare class PluginManager {
+    private readonly plugins;
+    private readonly commands;
+    private readonly services;
+    private readonly middlewares;
+    private readonly registrations;
+    private readonly eventBus;
+    readonly schemaRegistry: SchemaRegistry;
+    private middlewareSorted;
+    private initOrder;
+    private initialized;
+    private initializing;
+    /** Registers a plugin. Must be called before init(). */
+    register(plugin: Plugin_2): void;
+    /** Initializes all registered plugins in dependency/priority order. */
+    init(options: PluginManagerInitOptions): Promise<void>;
+    /** Notifies all plugins of a state change, in init order. */
+    notifyStateChange(oldState: EditorState, newState: EditorState, tr: Transaction): void;
+    /** Collects and merges decorations from all plugins. */
+    collectDecorations(state: EditorState, tr?: Transaction): DecorationSet;
+    /**
+     * Dispatches a transaction through the middleware chain, then calls the final dispatch.
+     * If no middleware is registered, calls finalDispatch directly.
+     */
+    dispatchWithMiddleware(tr: Transaction, state: EditorState, finalDispatch: (tr: Transaction) => void): void;
+    /** Executes a named command. Returns false if command not found. */
+    executeCommand(name: string): boolean;
+    /** Configures a plugin at runtime via onConfigure(). */
+    configurePlugin(pluginId: string, config: PluginConfig): void;
+    /** Returns all registered plugin IDs. */
+    getPluginIds(): string[];
+    /** Gets a plugin by ID. */
+    get(id: string): Plugin_2 | undefined;
+    /** Gets a registered service by typed key. */
+    getService<T>(key: ServiceKey<T>): T | undefined;
+    /** Destroys all plugins in reverse init order. */
+    destroy(): Promise<void>;
+    private destroyPlugin;
+    private cleanupRegistrations;
+    private getSortedMiddleware;
+    private createContext;
+    /**
+     * Resolves plugin initialization order via topological sort + priority.
+     * Throws on dependency cycles or missing dependencies.
+     */
+    private resolveOrder;
+}
+
+export declare interface PluginManagerInitOptions {
+    getState(): EditorState;
+    dispatch(transaction: Transaction): void;
+    getContainer(): HTMLElement;
+    getPluginContainer(position: 'top' | 'bottom'): HTMLElement;
+    /** Called after all plugin init() calls complete, before onReady(). */
+    onBeforeReady?(): void | Promise<void>;
+}
+
+export declare type PopupType = 'gridPicker' | 'dropdown' | 'custom';
+
+export declare interface Position {
+    readonly blockId: BlockId;
+    readonly offset: number;
+    /** Path from root block to leaf block (optional, for nested structures). */
+    readonly path?: readonly BlockId[];
+}
+
+/** Registers the built-in paragraph NodeSpec. */
+export declare function registerBuiltinSpecs(registry: SchemaRegistry): void;
+
+export declare interface RemoveInlineNodeStep {
+    readonly type: 'removeInlineNode';
+    readonly blockId: BlockId;
+    readonly offset: number;
+    readonly removedNode: InlineNode;
+    readonly path?: readonly BlockId[];
+}
+
+export declare interface RemoveMarkStep {
+    readonly type: 'removeMark';
+    readonly blockId: BlockId;
+    readonly from: number;
+    readonly to: number;
+    readonly mark: Mark;
+    readonly path?: readonly BlockId[];
+}
+
+export declare interface RemoveNodeStep {
+    readonly type: 'removeNode';
+    readonly parentPath: readonly BlockId[];
+    readonly index: number;
+    readonly removedNode: BlockNode;
+}
+
+/**
+ * Resolves a node in the document tree by its path (array of block IDs).
+ * The path traces the lineage from the root block down to the target.
+ */
+export declare function resolveNodeByPath(doc: Document_2, path: readonly string[]): BlockNode | undefined;
+
+/**
+ * Resolves the parent of a node at the given path.
+ * Returns the parent container (Document or BlockNode) and the child's index within it.
+ */
+export declare function resolveParentByPath(doc: Document_2, path: readonly string[]): {
+    parent: Document_2 | BlockNode;
+    index: number;
+} | undefined;
+
+export declare interface Schema {
+    readonly nodeTypes: readonly string[];
+    readonly markTypes: readonly string[];
+    /** Looks up the full NodeSpec for a given type. Available when created via schemaFromRegistry. */
+    readonly getNodeSpec?: (type: string) => NodeSpec | undefined;
+}
+
+/** Derives a Schema from a SchemaRegistry's registered specs. */
+export declare function schemaFromRegistry(registry: SchemaRegistry): Schema;
+
+export declare class SchemaRegistry {
+    private readonly _nodeSpecs;
+    private readonly _markSpecs;
+    private readonly _inlineNodeSpecs;
+    private readonly _nodeViews;
+    private readonly _keymaps;
+    private readonly _inputRules;
+    private readonly _toolbarItems;
+    private readonly _toolbarItemPluginMap;
+    registerNodeSpec<T extends string>(spec: NodeSpec<T>): void;
+    getNodeSpec(type: string): NodeSpec | undefined;
+    removeNodeSpec(type: string): void;
+    getNodeTypes(): string[];
+    registerMarkSpec<T extends string>(spec: MarkSpec<T>): void;
+    getMarkSpec(type: string): MarkSpec | undefined;
+    removeMarkSpec(type: string): void;
+    getMarkTypes(): string[];
+    registerInlineNodeSpec<T extends string>(spec: InlineNodeSpec<T>): void;
+    getInlineNodeSpec(type: string): InlineNodeSpec | undefined;
+    removeInlineNodeSpec(type: string): void;
+    getInlineNodeTypes(): string[];
+    registerNodeView(type: string, factory: NodeViewFactory): void;
+    getNodeViewFactory(type: string): NodeViewFactory | undefined;
+    removeNodeView(type: string): void;
+    registerKeymap(keymap: Keymap): void;
+    getKeymaps(): readonly Keymap[];
+    removeKeymap(keymap: Keymap): void;
+    registerInputRule(rule: InputRule): void;
+    getInputRules(): readonly InputRule[];
+    removeInputRule(rule: InputRule): void;
+    registerToolbarItem(item: ToolbarItem, pluginId?: string): void;
+    getToolbarItemsByPlugin(pluginId: string): ToolbarItem[];
+    getToolbarItem(id: string): ToolbarItem | undefined;
+    getToolbarItems(): ToolbarItem[];
+    removeToolbarItem(id: string): void;
+    clear(): void;
+}
+
+/** Selects all content in the editor. */
+export declare function selectAll(state: EditorState): Transaction;
+
+declare interface Selection_2 {
+    readonly anchor: Position;
+    readonly head: Position;
+}
+export { Selection_2 as Selection }
+
+export declare interface SelectionRange {
+    readonly from: Position;
+    readonly to: Position;
+}
+
+/**
+ * Returns a normalized range where `from` is always before `to`.
+ */
+export declare function selectionRange(sel: Selection_2, blockOrder?: readonly BlockId[]): SelectionRange;
+
+/** Type-safe service key for compile-time type checking. */
+export declare class ServiceKey<T> {
+    readonly id: string;
+    readonly _type: T;
+    constructor(id: string);
+}
+
+export declare interface SetBlockTypeStep {
+    readonly type: 'setBlockType';
+    readonly blockId: BlockId;
+    readonly nodeType: NodeTypeName;
+    readonly attrs?: BlockAttrs;
+    readonly previousNodeType: NodeTypeName;
+    readonly previousAttrs?: BlockAttrs;
+    readonly path?: readonly BlockId[];
+}
+
+export declare interface SetInlineNodeAttrStep {
+    readonly type: 'setInlineNodeAttr';
+    readonly blockId: BlockId;
+    readonly offset: number;
+    readonly attrs: Readonly<Record<string, string | number | boolean>>;
+    readonly previousAttrs: Readonly<Record<string, string | number | boolean>>;
+    readonly path?: readonly BlockId[];
+}
+
+export declare interface SetNodeAttrStep {
+    readonly type: 'setNodeAttr';
+    readonly path: readonly BlockId[];
+    readonly attrs: BlockAttrs | undefined;
+    readonly previousAttrs?: BlockAttrs;
+}
+
+declare interface SetStoredMarksStep {
+    readonly type: 'setStoredMarks';
+    readonly marks: readonly Mark[] | null;
+    readonly previousMarks: readonly Mark[] | null;
+}
+
+/** Checks whether two blocks share the same parent in the document tree. */
+export declare function sharesParent(state: EditorState, blockIdA: BlockId, blockIdB: BlockId): boolean;
+
+/** Splits the current block at the cursor position (Enter key). */
+export declare function splitBlockCommand(state: EditorState): Transaction | null;
+
+export declare interface SplitBlockStep {
+    readonly type: 'splitBlock';
+    readonly blockId: BlockId;
+    readonly offset: number;
+    readonly newBlockId: BlockId;
+    readonly path?: readonly BlockId[];
+}
+
+/** All starter fonts bundled with notectl. */
+export declare const STARTER_FONTS: readonly FontDefinition[];
+
+export declare interface StateChangeEvent {
+    oldState: EditorState;
+    newState: EditorState;
+    transaction: Transaction;
+}
+
+export declare type Step = InsertTextStep | DeleteTextStep | SplitBlockStep | MergeBlocksStep | AddMarkStep | RemoveMarkStep | SetStoredMarksStep | SetBlockTypeStep | InsertNodeStep | RemoveNodeStep | SetNodeAttrStep | InsertInlineNodeStep | RemoveInlineNodeStep | SetInlineNodeAttrStep;
+
+export declare interface StrikethroughConfig {
+    /** When true, a separator is rendered after the strikethrough toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class StrikethroughPlugin implements Plugin_2 {
+    readonly id = "strikethrough";
+    readonly name = "Strikethrough";
+    readonly priority = 22;
+    private readonly config;
+    constructor(config?: Partial<StrikethroughConfig>);
+    init(context: PluginContext): void;
+    private registerMarkSpec;
+    private registerCommand;
+    private registerKeymap;
+    private registerToolbarItem;
+}
+
+/** Controls which marks are enabled and which toolbar buttons are shown. */
+export declare interface SuperSubConfig {
+    readonly superscript: boolean;
+    readonly subscript: boolean;
+    readonly toolbar?: SuperSubToolbarConfig;
+    /** When true, a separator is rendered after the last toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class SuperSubPlugin implements Plugin_2 {
+    readonly id = "super-sub";
+    readonly name = "Superscript & Subscript";
+    readonly priority = 23;
+    private readonly config;
+    constructor(config?: Partial<SuperSubConfig>);
+    init(context: PluginContext): void;
+    private registerMark;
+    private registerKeymaps;
+    /**
+     * Ensures superscript and subscript are mutually exclusive.
+     * When an addMark step for one type is found, a removeMark step
+     * for the opposite type is injected. For stored marks, the opposite
+     * mark is filtered out.
+     */
+    private registerExclusivityMiddleware;
+    /**
+     * Registers disabled toolbar buttons for marks whose feature is disabled
+     * but whose toolbar button is explicitly requested.
+     */
+    private registerDisabledToolbarItems;
+    private isToolbarVisible;
+}
+
+/** Controls toolbar button visibility per mark. */
+export declare interface SuperSubToolbarConfig {
+    readonly superscript?: boolean;
+    readonly subscript?: boolean;
+}
+
+export declare interface TableConfig {
+    /** Maximum rows in grid picker. Defaults to 8. */
+    readonly maxPickerRows?: number;
+    /** Maximum columns in grid picker. Defaults to 8. */
+    readonly maxPickerCols?: number;
+    /** When true, a separator is rendered after the table toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+/** Context information about a cell within a table. */
+export declare interface TableContext {
+    readonly tableId: BlockId;
+    readonly tableIndex: number;
+    readonly rowId: BlockId;
+    readonly rowIndex: number;
+    readonly cellId: BlockId;
+    readonly colIndex: number;
+    readonly totalRows: number;
+    readonly totalCols: number;
+}
+
+export declare class TablePlugin implements Plugin_2 {
+    readonly id = "table";
+    readonly name = "Table";
+    readonly priority = 40;
+    private readonly config;
+    private selectionService;
+    private cleanupMouseSelection;
+    private context;
+    constructor(config?: Partial<TableConfig>);
+    init(context: PluginContext): void;
+    onReady(): void;
+    destroy(): void;
+    onStateChange(_oldState: EditorState, newState: EditorState, _tr: Transaction): void;
+    private registerNodeSpecs;
+    private registerNodeViews;
+    private registerToolbarItem;
+}
+
+/** Service for managing multi-cell selection. */
+export declare interface TableSelectionService {
+    getSelectedRange(): CellRange | null;
+    setSelectedRange(range: CellRange | null): void;
+    getSelectedCellIds(): readonly BlockId[];
+    isSelected(cellId: BlockId): boolean;
+}
+
+export declare const TableSelectionServiceKey: ServiceKey<TableSelectionService>;
+
+export declare type TextAlignment = 'left' | 'center' | 'right' | 'justify';
+
+export declare interface TextAlignmentConfig {
+    /** Which alignments to expose. Defaults to all four. */
+    readonly alignments: readonly TextAlignment[];
+    /** Block types that support alignment. Defaults to paragraph + heading. */
+    readonly alignableTypes: readonly string[];
+    /** When true, a separator is rendered after the toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class TextAlignmentPlugin implements Plugin_2 {
+    readonly id = "text-alignment";
+    readonly name = "Text Alignment";
+    readonly priority = 90;
+    private readonly config;
+    private alignableTypes;
+    constructor(config?: Partial<TextAlignmentConfig>);
+    init(context: PluginContext): void;
+    /**
+     * Patches existing NodeSpecs for alignable block types to support the
+     * `textAlign` attribute and render it as an inline style.
+     */
+    private patchNodeSpecs;
+    private registerCommands;
+    private registerKeymaps;
+    private registerToolbarItem;
+    /**
+     * Preserves the `textAlign` attribute when other plugins change the block
+     * type (e.g. paragraph → heading) via `setBlockType`, which replaces attrs.
+     */
+    private registerMiddleware;
+    private setAlignment;
+    private isNonDefaultAlignment;
+    private isAlignable;
+}
+
+export declare interface TextColorConfig {
+    /**
+     * Restricts the color picker to a specific set of hex colors.
+     * Each value must be a valid hex color code (`#RGB` or `#RRGGBB`).
+     * Duplicates are removed automatically (case-insensitive).
+     * When omitted, the full default palette is shown.
+     */
+    readonly colors?: readonly string[];
+    /** When true, a separator is rendered after the textColor toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class TextColorPlugin implements Plugin_2 {
+    readonly id = "textColor";
+    readonly name = "Text Color";
+    readonly priority = 23;
+    private readonly config;
+    private readonly colors;
+    constructor(config?: Partial<TextColorConfig>);
+    init(context: PluginContext): void;
+    private registerMarkSpec;
+    private registerCommands;
+    private registerToolbarItem;
+    private isTextColorActive;
+    private getActiveColor;
+    private applyColor;
+    private removeColor;
+    private renderColorPopup;
+}
+
+/** Controls which inline marks are enabled and which toolbar buttons are shown. */
+export declare interface TextFormattingConfig {
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: boolean;
+    readonly toolbar?: TextFormattingToolbarConfig;
+    /** When true, a separator is rendered after the last text-formatting toolbar item. */
+    readonly separatorAfter?: boolean;
+}
+
+export declare class TextFormattingPlugin implements Plugin_2 {
+    readonly id = "text-formatting";
+    readonly name = "Text Formatting";
+    readonly priority = 20;
+    private readonly config;
+    constructor(config?: Partial<TextFormattingConfig>);
+    init(context: PluginContext): void;
+    private registerMark;
+    private registerKeymaps;
+    /**
+     * Registers disabled toolbar buttons for marks whose feature is disabled
+     * but whose toolbar button is explicitly requested.
+     */
+    private registerDisabledToolbarItems;
+    /** Checks if a toolbar button should be visible for a given mark. */
+    private isToolbarVisible;
+}
+
+/** Controls toolbar button visibility per mark. */
+export declare interface TextFormattingToolbarConfig {
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+}
+
+export declare interface TextNode {
+    readonly type: 'text';
+    readonly text: string;
+    readonly marks: readonly Mark[];
+}
+
+export declare interface TextSegment {
+    readonly text: string;
+    readonly marks: readonly Mark[];
+}
+
+export declare function toggleBold(state: EditorState, features?: FeatureConfig): Transaction | null;
+
+export declare function toggleItalic(state: EditorState, features?: FeatureConfig): Transaction | null;
+
+/**
+ * Toggles a mark on the current selection.
+ * If collapsed, toggles stored marks. If range, applies/removes from text.
+ */
+export declare function toggleMark(state: EditorState, markType: MarkType, features?: FeatureConfig): Transaction | null;
+
+export declare function toggleUnderline(state: EditorState, features?: FeatureConfig): Transaction | null;
+
+export declare type ToolbarGroup = 'format' | 'block' | 'insert' | (string & {});
+
+export declare type ToolbarItem = ToolbarItemNoPopup | ToolbarItemGridPicker | ToolbarItemDropdown | ToolbarItemCustomPopup;
+
+declare interface ToolbarItemBase {
+    readonly id: string;
+    /** Grouping key: 'format' | 'insert' | 'block' or custom. */
+    readonly group: ToolbarGroup;
+    /** Icon content: inline SVG markup or plain text. Rendered via innerHTML. */
+    readonly icon: string;
+    readonly label: string;
+    /** Tooltip shown on hover, e.g. "Bold (Ctrl+B)". Falls back to label. */
+    readonly tooltip?: string;
+    /** Command name to execute on click. */
+    readonly command: string;
+    /**
+     * Lower priority renders further left.
+     * @deprecated Use the declarative `toolbar` config on `createEditor()` instead.
+     */
+    readonly priority?: number;
+    /**
+     * When true, a visual separator is rendered after this item.
+     * @deprecated Use the declarative `toolbar` config on `createEditor()` instead.
+     */
+    readonly separatorAfter?: boolean;
+    isActive?(state: EditorState): boolean;
+    isEnabled?(state: EditorState): boolean;
+}
+
+declare interface ToolbarItemCustomPopup extends ToolbarItemBase {
+    readonly popupType: 'custom';
+    renderPopup(container: HTMLElement, context: PluginContext): void;
+}
+
+declare interface ToolbarItemDropdown extends ToolbarItemBase {
+    readonly popupType: 'dropdown';
+    readonly popupConfig: DropdownConfig;
+}
+
+declare interface ToolbarItemGridPicker extends ToolbarItemBase {
+    readonly popupType: 'gridPicker';
+    readonly popupConfig: GridPickerConfig;
+}
+
+declare interface ToolbarItemNoPopup extends ToolbarItemBase {
+    readonly popupType?: undefined;
+}
+
+export declare interface ToolbarLayoutConfig {
+    readonly groups: ReadonlyArray<ReadonlyArray<string>>;
+}
+
+export declare class ToolbarPlugin implements Plugin_2 {
+    readonly id = "toolbar";
+    readonly name = "Toolbar";
+    readonly priority = 10;
+    private context;
+    private toolbarElement;
+    private buttons;
+    private activePopup;
+    private closePopupHandler;
+    private readonly hiddenItems;
+    private tooltipElement;
+    private tooltipTimer;
+    private readonly layoutConfig;
+    constructor(layoutConfig?: ToolbarLayoutConfig);
+    init(context: PluginContext): void;
+    onReady(): void;
+    destroy(): void;
+    onStateChange(_oldState: EditorState, newState: EditorState, _tr: Transaction): void;
+    onConfigure(config: PluginConfig): void;
+    private createTooltipElement;
+    private showTooltip;
+    private hideTooltip;
+    private createToolbarElement;
+    private renderItems;
+    private renderItemsByLayout;
+    private renderItemsByPriority;
+    private createButton;
+    private activePopupButton;
+    private togglePopup;
+    private closePopup;
+    private renderGridPicker;
+    private renderDropdown;
+    private updateButtonStates;
+}
+
+export declare interface ToolbarServiceAPI {
+    /** Re-reads isActive/isEnabled from state and updates all buttons. */
+    refresh(): void;
+}
+
+export declare const ToolbarServiceKey: ServiceKey<ToolbarServiceAPI>;
+
+export declare interface Transaction {
+    readonly steps: readonly Step[];
+    readonly selectionBefore: Selection_2;
+    readonly selectionAfter: Selection_2;
+    readonly storedMarksAfter: readonly Mark[] | null;
+    readonly metadata: TransactionMetadata;
+}
+
+/** Fluent API for building transactions. */
+export declare class TransactionBuilder {
+    private readonly steps;
+    private selection;
+    private storedMarks;
+    private readonly selectionBefore;
+    private readonly origin;
+    private workingDoc;
+    constructor(currentSelection: Selection_2, currentStoredMarks: readonly Mark[] | null, origin?: TransactionOrigin, doc?: Document_2);
+    /** Adds an insert-text step. Updates workingDoc if available. */
+    insertText(blockId: BlockId, offset: number, text: string, marks: readonly Mark[], segments?: readonly TextSegment[]): this;
+    /** Adds a delete-text step with explicit data. Updates workingDoc if available. */
+    deleteText(blockId: BlockId, from: number, to: number, deletedText: string, deletedMarks: readonly Mark[], deletedSegments?: readonly TextSegment[]): this;
+    /**
+     * Deletes text at the given range, auto-deriving deletedText, deletedMarks, and deletedSegments
+     * from the working document. Requires a document to be provided at construction.
+     */
+    deleteTextAt(blockId: BlockId, from: number, to: number): this;
+    /** Adds a split-block step. Updates workingDoc if available. */
+    splitBlock(blockId: BlockId, offset: number, newBlockId: BlockId): this;
+    /** Adds a merge-blocks step with explicit targetLengthBefore. Updates workingDoc if available. */
+    mergeBlocks(targetBlockId: BlockId, sourceBlockId: BlockId, targetLengthBefore: number): this;
+    /**
+     * Merges two blocks, auto-deriving targetLengthBefore from the working document.
+     * Requires a document to be provided at construction.
+     */
+    mergeBlocksAt(targetBlockId: BlockId, sourceBlockId: BlockId): this;
+    /** Adds an add-mark step. Updates workingDoc if available. */
+    addMark(blockId: BlockId, from: number, to: number, mark: Mark): this;
+    /** Adds a remove-mark step. Updates workingDoc if available. */
+    removeMark(blockId: BlockId, from: number, to: number, mark: Mark): this;
+    /** Adds a set-block-type step, changing a block's node type and optionally its attrs. */
+    setBlockType(blockId: BlockId, nodeType: NodeTypeName, attrs?: BlockAttrs): this;
+    /** Inserts a node as a child of the parent at the given path and index. */
+    insertNode(parentPath: readonly BlockId[], index: number, node: BlockNode): this;
+    /** Removes a node at the given index from the parent at the given path. */
+    removeNode(parentPath: readonly BlockId[], index: number): this;
+    /** Sets attributes on a node at the given path. */
+    setNodeAttr(path: readonly BlockId[], attrs: BlockAttrs): this;
+    /** Inserts an InlineNode at the given offset within a block. */
+    insertInlineNode(blockId: BlockId, offset: number, node: InlineNode): this;
+    /** Removes an InlineNode at the given offset, deriving removedNode from workingDoc. */
+    removeInlineNode(blockId: BlockId, offset: number): this;
+    /** Sets attributes on an InlineNode at the given offset. */
+    setInlineNodeAttr(blockId: BlockId, offset: number, attrs: Readonly<Record<string, string | number | boolean>>): this;
+    /** Sets the selection for the resulting state. */
+    setSelection(selection: Selection_2): this;
+    /** Sets stored marks for the resulting state. */
+    setStoredMarks(marks: readonly Mark[] | null, previousMarks: readonly Mark[] | null): this;
+    /** Builds the final transaction. */
+    build(): Transaction;
+    /** Advances the working document by applying a step. */
+    private advanceDoc;
+}
+
+export declare interface TransactionMetadata {
+    readonly origin: TransactionOrigin;
+    readonly timestamp: number;
+}
+
+export declare type TransactionMiddleware = (tr: Transaction, state: EditorState, next: MiddlewareNext) => void;
+
+export declare type TransactionOrigin = 'input' | 'paste' | 'command' | 'history' | 'api';
+
+export declare interface UnderlineMark extends Mark {
+    readonly type: MarkTypeName & 'underline';
+}
+
+/**
+ * Validates whether the given children types are valid for a parent node type.
+ * Checks allow list, min/max constraints.
+ */
+export declare function validateContent(registry: SchemaRegistry, parentType: string, childTypes: readonly string[]): boolean;
+
+/**
+ * Walks all block nodes in the document tree in depth-first order.
+ * Visits every BlockNode, including nested ones, with their full path.
+ */
+export declare function walkNodes(doc: Document_2, callback: (node: BlockNode, path: string[]) => void): void;
+
+export declare interface WidgetDecoration {
+    readonly type: 'widget';
+    readonly blockId: BlockId;
+    readonly offset: number;
+    readonly toDOM: () => HTMLElement;
+    readonly side: -1 | 1;
+    readonly key?: string;
+}
+
+/** Creates a widget decoration that inserts a DOM element at a position. */
+export declare function widgetDecoration(blockId: BlockId, offset: number, toDOM: () => HTMLElement, options?: {
+    readonly side?: -1 | 1;
+    readonly key?: string;
+}): WidgetDecoration;
+
+export { }