nuvra 0.1.0

package/dist/core/engine/engine.d.ts

@@ -0,0 +1,319 @@
+import { type EditorUiState } from '../ui-state';
+import { type HeadingTag, type TextAlign, type TextDirection } from './blocks';
+import { EditorHistory } from './history';
+import { type ListKind } from './lists';
+import { type MarkName, type StyleName } from './marks';
+import { SearchController, type SearchState } from './search';
+import { type TableCell } from './tables';
+/** Settings the host component passes when it creates the engine. */
+interface DocumentEngineOptions {
+    /** Initial HTML; it is sanitised before it reaches the DOM. */
+    content: string;
+    /** Whether the user may change the document. */
+    editable: boolean;
+    /** Maximum number of characters in the document, or `0` for no limit. */
+    maxLength: number;
+    /** Returns the placeholder shown while the document is empty; called on every refresh so it follows the locale. */
+    placeholder: () => string;
+    /** Receives image files pasted or dropped into the document; the selection is already at the target. */
+    onImageFiles: (files: File[]) => void;
+}
+/** Events emitted by the engine, mapped to their payloads. */
+interface EngineEvents {
+    /** The document content changed. */
+    update: undefined;
+    /** The selection, pending formatting or anything else shown by the toolbar may have changed. */
+    selection: undefined;
+    /** The editable root received focus. */
+    focus: undefined;
+    /** The editable root lost focus. */
+    blur: undefined;
+    /** An IME composition started (`true`) or ended (`false`). */
+    composition: boolean;
+    /** The find results or the current match changed. */
+    search: SearchState;
+}
+/** Table operations offered by the table menu. */
+export type TableCommand = 'addRowBefore' | 'addRowAfter' | 'deleteRow' | 'addColumnBefore' | 'addColumnAfter' | 'deleteColumn' | 'mergeCells' | 'splitCell' | 'toggleHeaderRow' | 'deleteTable';
+/** Image attributes that can change after insertion; `null` or an empty value removes the attribute. */
+interface ImageAttributes {
+    /** Horizontal placement, stored as `data-align`. */
+    align?: 'left' | 'center' | 'right';
+    /** Alternative text for screen readers. */
+    alt?: string | null;
+    /** Rendered width in CSS pixels. */
+    width?: number | null;
+    /** Rendered height in CSS pixels. */
+    height?: number | null;
+}
+/** Callback registered with {@link DocumentEngine.on}. */
+type Listener<T> = (payload: T) => void;
+/**
+ * Framework-free rich text engine on top of a `contenteditable` element. It owns the browser events, keeps the
+ * document well-formed, records undo history and exposes every editing command the toolbar and menus need.
+ */
+export declare class DocumentEngine {
+    readonly root: HTMLElement;
+    private readonly options;
+    /** Undo and redo stacks of document snapshots. */
+    readonly history: EditorHistory;
+    /** Find and replace over the document text. */
+    readonly search: SearchController;
+    /** Registered listeners per event. */
+    private readonly listeners;
+    /** Removes every DOM listener added by the engine. */
+    private readonly disposers;
+    /** Whether the user may change the document. */
+    private editable;
+    /** Whether an IME composition is in progress. */
+    private composingText;
+    /** Last selection inside the document, used when focus is in a toolbar popover. */
+    private lastRange;
+    /** Formatting chosen at a collapsed caret, applied to the next typed text. */
+    private pending;
+    /** Time until which selection changes are attributed to the engine itself. */
+    private internalSelectionUntil;
+    /** Cell where a mouse drag for a cell selection started. */
+    private cellAnchor;
+    /** Rectangle of selected table cells, when several cells are selected. */
+    private cellRect;
+    /** Selection being dragged, so a drop inside the document can move instead of copy. */
+    private dragRange;
+    /** Image selected by a click, shown with resize handles. */
+    private selectedImageElement;
+    /**
+     * Takes over `root` as the editable document, loads the initial content and starts listening to its events.
+     *
+     * @param root Element that becomes the editable document.
+     * @param options Initial content, limits and callbacks.
+     */
+    constructor(root: HTMLElement, options: DocumentEngineOptions);
+    /**
+     * Subscribes to an engine event.
+     *
+     * @returns Function that removes the listener again.
+     */
+    on<K extends keyof EngineEvents>(event: K, listener: Listener<EngineEvents[K]>): () => void;
+    /** Removes all DOM listeners, event subscriptions and search highlights. The root element is left in place. */
+    destroy(): void;
+    /** Calls every listener of an event with its payload. */
+    private emit;
+    /** Adds a DOM listener that {@link destroy} removes again. */
+    private listen;
+    /** Whether the document holds nothing but one empty paragraph. */
+    get isEmpty(): boolean;
+    /** Whether the user may change the document. */
+    get isEditable(): boolean;
+    /** Whether an IME composition is in progress; layout work should wait until it ends. */
+    get composing(): boolean;
+    /** Image currently selected by a click, if it is still in the document. */
+    get selectedImage(): HTMLImageElement | null;
+    /** Whether several table cells are selected with the mouse. */
+    get hasCellSelection(): boolean;
+    /** Clean HTML of the document, without caret placeholders or other editor-only markup. */
+    getHTML(): string;
+    /**
+     * Replaces the whole document with sanitised HTML.
+     *
+     * @param html New content; scripts, handlers and unsupported markup are dropped.
+     * @param options.addToHistory Record the replacement as an undo step instead of clearing the history.
+     * @param options.emitUpdate Emit `update` so the host saves the new content.
+     */
+    setContent(html: string, { addToHistory, emitUpdate }?: {
+        addToHistory?: boolean | undefined;
+        emitUpdate?: boolean | undefined;
+    }): void;
+    /** Switches between editing and read-only mode. */
+    setEditable(editable: boolean): void;
+    /** Word and character counts of the document text. */
+    getStats(): {
+        words: number;
+        characters: number;
+    };
+    /** Snapshot of the formatting at the selection, for the toolbar. */
+    getState(): EditorUiState;
+    /** Plain text of the current selection. */
+    getSelectedText(): string;
+    /**
+     * Focuses the document.
+     *
+     * @param position Place the caret at the start or end; without it the last selection is restored.
+     */
+    focus(position?: 'start' | 'end'): void;
+    /** Marks the next selection changes as caused by the engine, so they keep pending formatting and typing groups. */
+    private expectInternalSelection;
+    /** Live selection inside the document, or a copy of the last one while focus is elsewhere (e.g. in a popover). */
+    private currentRange;
+    /** Captures the document markup and selection for the undo history. */
+    private snapshot;
+    /** Updates the placeholder state and search results, then notifies listeners. */
+    private refresh;
+    /**
+     * Runs one edit as an undo step, then normalises the document and restores the selection by text position.
+     *
+     * @param edit Changes the document at the given range and describes the resulting selection.
+     * @param kind `typing` edits join the running typing group instead of always starting a new undo step.
+     * @returns Whether the edit ran and changed something.
+     */
+    private exec;
+    /** Normalises the document after an edit, restores the selection and notifies listeners. */
+    private finishEdit;
+    /** Records an undo step for a change that does not depend on the selection (checkboxes, image attributes). */
+    private mutate;
+    /** Deletes the selected content, if any, and returns a collapsed range where it started. */
+    private collapsedAfterDelete;
+    /** Deletes the selection as one undo step and leaves a collapsed caret where it started. */
+    private deleteSelection;
+    /** Number of characters in the document text. */
+    private characterCount;
+    /** Whether adding `extra` characters would exceed the configured maximum length. */
+    private exceedsLimit;
+    /** Remembers the selection; a selection moved by the user drops pending formatting and ends the typing group. */
+    private onSelectionChange;
+    /** Decides for every input whether the browser may apply it natively or the engine performs it instead. */
+    private onBeforeInput;
+    /**
+     * Lets the browser type plain characters itself (fast and IME friendly) and takes over when a selection has to be
+     * replaced, pending formatting applies or the caret sits outside a text block.
+     */
+    private handleTextInput;
+    /** Deletes selections and joins blocks at their edges itself; single characters are deleted natively. */
+    private handleDeleteInput;
+    /** Repairs the structure after a native edit and applies Markdown and typography rules to typed text. */
+    private onInput;
+    /** Browsers occasionally leave text outside paragraphs or a <div> after native edits; fix it in place. */
+    private repairStructure;
+    /** Applies the input rule completed by the typed character as its own undo step. */
+    private applyInputRule;
+    /** Runs keyboard shortcuts and handles Delete, Tab and Escape for images, cell selections, tables and lists. */
+    private onKeyDown;
+    /**
+     * Tab moves between table cells (appending a row after the last one), nests list items, indents a paragraph at its
+     * start and types a tab stop inside a line. Shift+Tab reverses each of these.
+     */
+    private handleTab;
+    /** Moves the caret to the next or previous cell; moving past the last cell appends a row as an undo step. */
+    private moveToSiblingCell;
+    /** Runs the command bound to a keyboard shortcut. */
+    private runKeyCommand;
+    /** Pastes sanitised content; lone images go to the host for upload and a URL over a selection becomes a link. */
+    private onPaste;
+    /** Inserts clipboard content at the selection; inside a code block only its plain text is used. */
+    private insertTransfer;
+    /** Puts clean HTML and plain text of the selection on the clipboard. */
+    private onCopy;
+    /** Copies the selection like {@link onCopy} and deletes it as an undo step. */
+    private onCut;
+    /** Starts dragging the selection with clean clipboard data and remembers it for a move on drop. */
+    private onDragStart;
+    /** Forgets the dragged selection once the drag ends anywhere. */
+    private onDragEnd;
+    /** Allows dropping into an editable document. */
+    private onDragOver;
+    /**
+     * Inserts dropped content at the pointer. A selection dragged within the document is moved (copied with Ctrl) in a
+     * single undo step; dropped image files go to the host for upload.
+     */
+    private onDrop;
+    /** Selects a clicked image, clears a previous cell selection and remembers the cell where a drag may start. */
+    private onMouseDown;
+    /** Extends a rectangular cell selection while the mouse is dragged across table cells. */
+    private onMouseMove;
+    /** Toggles task list checkboxes as undo steps and opens links on Ctrl/Cmd+click. */
+    private onClick;
+    /** Deletes a selection before an IME replaces it and pauses layout work while composing. */
+    private onCompositionStart;
+    /** Repairs the structure once the IME has committed its text. */
+    private onCompositionEnd;
+    /** Reverts the last undo step. */
+    undo(): void;
+    /** Re-applies the last reverted undo step. */
+    redo(): void;
+    /** Puts a history snapshot back into the document and restores its selection. */
+    private restoreSnapshot;
+    /** Inserts plain text at the selection, replacing selected content and applying pending formatting. */
+    insertText(text: string): void;
+    /** Formatting at the start of a range, or `null` when the text there is unformatted. */
+    private captureFormat;
+    /**
+     * Enter splits the block (or leaves an empty list item or quote), Shift+Enter inserts a line break. An empty new
+     * line keeps the formatting of the text before it, as in office editors.
+     */
+    private splitLine;
+    /** Toggles bold, italic and the other marks; at a collapsed caret it applies to the next typed text. */
+    toggleMark(mark: MarkName): void;
+    /** Sets or removes (`null`) text colour, font family or font size; at a collapsed caret for the next text. */
+    setTextStyle(name: StyleName, value: string | null): void;
+    /** Sets or removes (`null`) the highlight colour; at a collapsed caret for the next text. */
+    setHighlight(color: string | null): void;
+    /** Merges a formatting change into the pending format and keeps focus in the document. */
+    private setPending;
+    /** Removes marks from the selection and turns its blocks into plain paragraphs outside lists and quotes. */
+    clearFormatting(): void;
+    /** Turns the selected blocks into paragraphs or headings. */
+    setBlockType(tag: 'P' | HeadingTag): void;
+    /** Wraps the selected blocks in a quote, or unwraps them when they are all quoted already. */
+    toggleBlockquote(): void;
+    /** Turns the selected blocks into code blocks, or back into paragraphs. */
+    toggleCodeBlock(): void;
+    /** Aligns the selected paragraphs. */
+    setTextAlign(align: TextAlign): void;
+    /** Sets or removes (`null`) the line spacing of the selected paragraphs. */
+    setLineHeight(lineHeight: string | null): void;
+    /** Sets the writing direction of the selected paragraphs. */
+    setTextDirection(direction: TextDirection): void;
+    /** Turns the selected blocks into a list of the given kind, converts another list kind, or lifts them out. */
+    toggleList(kind: ListKind): void;
+    /** List items are nested or lifted; other paragraphs get indentation steps. */
+    indent(direction: 1 | -1): void;
+    /**
+     * Inserts a block element at the caret and places the caret after it, or inside it when `caretInside` finds a
+     * target (e.g. the first cell of a new table).
+     */
+    private insertBlock;
+    /** Inserts a horizontal rule. */
+    insertHorizontalRule(): void;
+    /** Inserts a manual page break. */
+    insertPageBreak(): void;
+    /** Link that contains the start of the selection. */
+    getActiveLink(): HTMLAnchorElement | null;
+    /**
+     * Links the selection, edits the link under a collapsed caret, or inserts a new linked text. Unsafe URLs are ignored.
+     *
+     * @param href Link address.
+     * @param target `_blank` to open in a new tab, `null` for the same tab.
+     * @param text Label inserted when nothing is selected; defaults to the URL.
+     */
+    setLink(href: string, target: string | null, text?: string): void;
+    /** Removes links from the selection, or the whole link under a collapsed caret. */
+    unsetLink(): void;
+    /** Inserts a centred image at the caret; unsafe sources are ignored. */
+    insertImage(src: string, alt?: string): void;
+    /** Selects an image for the resize handles and image menu, or clears the selection with `null`. */
+    selectImage(image: HTMLImageElement | null): void;
+    /** Changes image attributes as an undo step. */
+    updateImage(image: HTMLImageElement, attributes: ImageAttributes): void;
+    /** Deletes an image and places the caret in the neighbouring text. */
+    removeImage(image: HTMLImageElement): void;
+    /** Table cell that contains the start of the selection. */
+    getActiveCell(): TableCell | null;
+    /** Whether the selected cells form a rectangle that can be merged. */
+    canMergeCells(): boolean;
+    /** Whether the active cell spans several rows or columns. */
+    canSplitCell(): boolean;
+    /** Sets a column width in pixels as an undo step, e.g. after dragging a column border. */
+    resizeColumn(table: HTMLTableElement, index: number, width: number): void;
+    /** Inserts a table and places the caret in its first cell. */
+    insertTable(rows: number, cols: number, withHeaderRow: boolean): void;
+    /** Runs a table operation on the active cell or the selected cells. */
+    tableCommand(command: TableCommand): void;
+    /** Ends a rectangular cell selection. */
+    private clearCellSelection;
+    /** Empties every selected cell as one undo step. */
+    private clearSelectedCells;
+    /** Replaces the current search match as an undo step. */
+    replaceMatch(replacement: string): void;
+    /** Replaces every search match as one undo step. */
+    replaceAllMatches(replacement: string): void;
+}
+export {};

package/dist/core/engine/history.d.ts

@@ -0,0 +1,43 @@
+import type { TextBookmark } from './selection';
+/** The document and selection at one point in time. */
+export interface Snapshot {
+    /** outerHTML of each top-level block; unchanged blocks share the same string with earlier snapshots. */
+    blocks: string[];
+    /** Selection to restore together with the blocks, or `null` when the editor had no selection. */
+    bookmark: TextBookmark | null;
+}
+/** How a change was made: consecutive typing is grouped into one undo step, commands never are. */
+type ChangeKind = 'typing' | 'command';
+/** Undo/redo stacks of document snapshots with typing grouping and memory sharing between snapshots. */
+export declare class EditorHistory {
+    private readonly limit;
+    /** States before each change, newest last. */
+    private readonly undoStack;
+    /** States replaced by undo, newest last; cleared by any new change. */
+    private readonly redoStack;
+    /** Kind of the last recorded change, `null` when the next keystroke must start a new step. */
+    private lastKind;
+    /** Time of the last recorded change, used to group typing. */
+    private lastTime;
+    /** @param limit Maximum number of steps kept on each stack. */
+    constructor(limit?: number);
+    /** Whether there is a step to undo. */
+    get canUndo(): boolean;
+    /** Whether there is an undone step to redo. */
+    get canRedo(): boolean;
+    /** Records the state before a change; `take` runs only when a new undo step actually starts. */
+    record(take: () => Snapshot, kind: ChangeKind): void;
+    /** Starts a new undo step for the next keystroke, e.g. after the caret was moved. */
+    breakGroup(): void;
+    /** Moves one step back: stores `current` for redo and returns the state to restore, or `null` when empty. */
+    undo(current: Snapshot): Snapshot | null;
+    /** Moves one step forward: stores `current` for undo and returns the state to restore, or `null` when empty. */
+    redo(current: Snapshot): Snapshot | null;
+    /** Forgets every step, e.g. after the content was replaced from outside. */
+    clear(): void;
+    /** Adds a snapshot to a stack and drops the oldest one when the limit is exceeded. */
+    private push;
+    /** Reuses identical block strings from the latest snapshot so large documents do not multiply in memory. */
+    private share;
+}
+export {};

package/dist/core/engine/input-rules.d.ts

@@ -0,0 +1,17 @@
+import { type Caret } from './editing';
+import { type PendingFormat } from './marks';
+/** What an applied rule leaves behind for the engine. */
+interface InputRuleResult {
+    /** New caret position, or `null` to restore the caret by text position. */
+    caret: Caret | null;
+    /** Formatting for the next typed characters, so text after `**bold**` is not bold. */
+    pending?: PendingFormat;
+}
+/** A matched rule; calling it performs the document change. */
+type InputRule = () => InputRuleResult;
+/**
+ * Looks for a rule completed by the character that was just typed. The returned function performs the change,
+ * so the caller can record an undo step first. Rules never apply inside code.
+ */
+export declare const matchInputRule: (root: HTMLElement, range: Range, typed: string) => InputRule | null;
+export {};

package/dist/core/engine/keymap.d.ts

@@ -0,0 +1,7 @@
+/** Editor commands reachable through keyboard shortcuts. */
+export type KeyCommand = 'undo' | 'redo' | 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'subscript' | 'superscript' | 'highlight' | 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading5' | 'heading6' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignJustify' | 'bulletList' | 'orderedList' | 'taskList' | 'blockquote' | 'codeBlock' | 'pageBreak';
+/**
+ * Returns the editor command for a key press, or `null` when it is not a shortcut. Physical key codes are used so
+ * shortcuts keep working with Cyrillic and other keyboard layouts; AltGr combinations are left to text input.
+ */
+export declare const matchKeyCommand: (event: KeyboardEvent) => KeyCommand | null;

package/dist/core/engine/lists.d.ts

@@ -0,0 +1,29 @@
+/** The three list types; the names match the toolbar state keys. */
+export type ListKind = 'bulletList' | 'orderedList' | 'taskList';
+/** Kind of a `<ul>`/`<ol>` element; task lists are `<ul data-type="taskList">`. */
+export declare const listKind: (list: Element) => ListKind;
+/** List item containing `node`. */
+export declare const closestListItem: (node: Node, root: HTMLElement) => HTMLElement | null;
+/** Kind of the list the node is in, or `null` outside lists. */
+export declare const activeListKind: (root: HTMLElement, node: Node) => ListKind | null;
+/**
+ * Moves an item one level up. From a nested list it becomes an item of the outer list, taking the following
+ * siblings as its own sub-list; from a top-level list its content becomes plain blocks between two list halves.
+ */
+export declare const liftListItem: (root: HTMLElement, item: HTMLElement) => void;
+/**
+ * Tab / Shift+Tab inside lists: nests or lifts every selected item.
+ * @returns whether any item changed level.
+ */
+export declare const changeListIndent: (root: HTMLElement, range: Range, delta: 1 | -1) => boolean;
+/** Lifts the block out of every list it is nested in ("clear formatting"). */
+export declare const liftOutOfLists: (root: HTMLElement, block: HTMLElement) => void;
+/**
+ * Toolbar list button: lifts the selection out when it is already in lists of this kind, converts lists of other
+ * kinds, and otherwise wraps the selected blocks in a new list joined with same-kind neighbours.
+ */
+export declare const toggleList: (root: HTMLElement, range: Range, kind: ListKind) => void;
+/** Moves `rightBlock` and everything after it in the item body into a new item placed after `item`. */
+export declare const splitListItem: (item: HTMLElement, rightBlock: HTMLElement) => HTMLElement;
+/** Flips a task item's checked state in both the `data-checked` attribute and its checkbox. */
+export declare const toggleTaskItem: (item: HTMLElement) => void;

package/dist/core/engine/marks.d.ts

@@ -0,0 +1,50 @@
+/** Toggleable inline formatting, each rendered as its own element. */
+export type MarkName = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'subscript' | 'superscript';
+/** Inline formatting stored as CSS properties on a `<span>`. */
+export type StyleName = 'color' | 'fontFamily' | 'fontSize';
+/** Formatting chosen while the caret is collapsed; applied to the next typed text. */
+export interface PendingFormat {
+    /** Marks forced on (`true`) or off (`false`); missing marks follow the surrounding text. */
+    marks: Partial<Record<MarkName, boolean>>;
+    /** Span styles to apply; `null` removes the style, missing styles follow the surrounding text. */
+    styles: Partial<Record<StyleName, string | null>>;
+    /** Highlight colour; `null` removes the highlight, `undefined` follows the surrounding text. */
+    highlight?: string | null;
+}
+/** Colour used when a highlight is applied without choosing one, e.g. by `==text==` or Mod+Shift+H. */
+export declare const DEFAULT_HIGHLIGHT_COLOR = "#fef08a";
+/** Link containing `node`; links may span several blocks' worth of inline markup, so the search stops at `root`. */
+export declare const linkAncestor: (node: Node, root: HTMLElement) => HTMLAnchorElement | null;
+/** Text nodes with at least one selected character, skipping code blocks and text outside blocks. */
+export declare const selectedTextNodes: (root: HTMLElement, range: Range) => Text[];
+/** Whether the mark applies at the caret, or to every selected character of a non-collapsed range. */
+export declare const isMarkActive: (root: HTMLElement, range: Range, mark: MarkName) => boolean;
+/**
+ * Removes the mark when the whole selection already has it, otherwise adds it to every selected character.
+ * Subscript and superscript exclude each other.
+ */
+export declare const toggleMark: (root: HTMLElement, range: Range, mark: MarkName) => void;
+/** Sets (or with `null` removes) a span style on the selected text, reusing spans that already carry it. */
+export declare const setTextStyle: (root: HTMLElement, range: Range, name: StyleName, value: string | null) => void;
+/** Highlights the selected text with a colour, or removes the highlight with `null`. */
+export declare const setHighlight: (root: HTMLElement, range: Range, color: string | null) => void;
+/**
+ * Turns the selected text into a link, replacing any link it was part of.
+ * @returns whether any text was selected.
+ */
+export declare const setLink: (root: HTMLElement, range: Range, href: string, target: string | null) => boolean;
+/** Removes links from the selected text, keeping the text itself. */
+export declare const unsetLink: (root: HTMLElement, range: Range) => void;
+/** Removes every mark, span style, highlight and link from the selected text. */
+export declare const clearMarks: (root: HTMLElement, range: Range) => void;
+/** Which marks apply to `node`. */
+export declare const readMarks: (root: HTMLElement, node: Node) => Record<MarkName, boolean>;
+/** Value of a span style at `node`, or an empty string when none is set. */
+export declare const readStyle: (root: HTMLElement, node: Node, name: StyleName) => string;
+/** Highlight colour at `node`, the default colour for a `<mark>` without one, or an empty string. */
+export declare const readHighlight: (root: HTMLElement, node: Node) => string;
+/**
+ * Inserts text at a collapsed caret with formatting that differs from its surroundings: the inline elements
+ * around the caret are split and the text is wrapped in exactly the requested marks.
+ */
+export declare const insertFormattedText: (root: HTMLElement, range: Range, text: string, format: PendingFormat) => void;

package/dist/core/engine/schema.d.ts

@@ -0,0 +1,37 @@
+/** Attribute pagination writes on blocks it moved to the next sheet; editor-only. */
+export declare const GAP_ATTRIBUTE = "data-doc-gap";
+/** Class marking table cells in a drag selection; editor-only. */
+export declare const SELECTED_CELL_CLASS = "doc-cell-selected";
+/** Whether the node is a block in the editor model. */
+export declare const isBlockNode: (node: Node | null | undefined) => node is HTMLElement;
+/** Sets a paragraph's indentation level as `data-indent` plus the matching left margin, removing both at level 0. */
+export declare const setIndent: (block: HTMLElement, indent: number) => void;
+/**
+ * Returns the trimmed URL when it is safe to put in a link (`http(s)`, `mailto`, `tel` or relative) or an image
+ * (`http(s)`, `data:image`, `blob` or relative), otherwise `null`.
+ */
+export declare const sanitizeUrl: (value: string | null, image?: boolean) => string | null;
+/** The element holding a list item's blocks: the `<div>` of a task item, the `<li>` itself otherwise. */
+export declare const listItemBody: (item: HTMLElement) => HTMLElement;
+/**
+ * Gives a list item the task structure (non-editable checkbox label plus `<div>` body) with the checkbox mirroring
+ * `data-checked`, moves any stray content into the body and returns the body.
+ */
+export declare const ensureTaskItem: (item: HTMLElement) => HTMLElement;
+/**
+ * Makes a block container (document, quote, list item body, table cell) hold only well-formed blocks: stray wrappers
+ * are unwrapped, runs of inline content become paragraphs and every block is normalised. The document root also
+ * always ends with a paragraph, so the caret can be placed after tables, images and rules.
+ */
+export declare const normalizeContainer: (container: ParentNode & Node, isRoot?: boolean) => void;
+/** Parses untrusted HTML without executing it and returns editor-ready blocks. */
+export declare const sanitizeHtml: (html: string) => DocumentFragment;
+/**
+ * Removes editor-only markup (pagination gaps, cell selection). With `forExport` it also drops caret placeholders
+ * and editing attributes, which history snapshots keep so the restored DOM is immediately editable.
+ */
+export declare const cleanEditorArtifacts: (scope: Element | DocumentFragment, forExport: boolean) => void;
+/** Clean HTML of the editor content, as stored in the model and exported. */
+export declare const serialize: (root: HTMLElement) => string;
+/** Whether the document is a single unformatted, empty paragraph. */
+export declare const isEmptyDocument: (root: HTMLElement) => boolean;

package/dist/core/engine/search.d.ts

@@ -0,0 +1,65 @@
+/** Matching options of the find bar. */
+interface SearchOptions {
+    /** Match letter case exactly. */
+    caseSensitive: boolean;
+    /** Only match whole words. */
+    wholeWord: boolean;
+}
+/** Match counter shown in the find bar. */
+export interface SearchState {
+    /** Number of matches in the document. */
+    total: number;
+    /** 1-based index of the current match, 0 when there is none. */
+    current: number;
+}
+/** Find and replace without touching the document markup: matches are painted with CSS highlights. */
+export declare class SearchController {
+    private readonly root;
+    private readonly onChange;
+    /** Current search term; empty when the search is inactive. */
+    private term;
+    /** Current matching options. */
+    private options;
+    /** Live ranges of all matches in document order. */
+    private results;
+    /** Index of the current match, -1 when there is none. */
+    private index;
+    /**
+     * @param root the editable document element.
+     * @param onChange called with the match counter whenever it may have changed.
+     */
+    constructor(root: HTMLElement, onChange: (state: SearchState) => void);
+    /** Current match counter. */
+    get state(): SearchState;
+    /** Whether a search term is set, so the results must follow document edits. */
+    get active(): boolean;
+    /** Starts a new search; options not passed keep their previous value. */
+    setQuery(term: string, options?: Partial<SearchOptions>): void;
+    /** Re-runs the search, e.g. after the document changed, keeping the current match position unless `reset`. */
+    refresh(reset?: boolean): void;
+    /** Moves to the next match, wrapping around, and scrolls it into view. */
+    next(): void;
+    /** Moves to the previous match, wrapping around, and scrolls it into view. */
+    previous(): void;
+    /**
+     * Replaces the current match; the caller records history and tidies the markup.
+     * @returns whether a match was replaced.
+     */
+    replaceCurrent(replacement: string): boolean;
+    /**
+     * Replaces every match, last first so earlier ranges stay valid.
+     * @returns the number of replaced matches.
+     */
+    replaceAll(replacement: string): number;
+    /** Ends the search and removes the highlights. */
+    clear(): void;
+    /** Finds all matches block by block; line breaks count as newlines so matches never span them. */
+    private find;
+    /** Paints all matches and, separately, the current one. */
+    private paint;
+    /** Repaints, scrolls the current match into the middle of the view and reports the counter. */
+    private reveal;
+    /** Replaces the content of one match with plain text (an empty replacement deletes the match). */
+    private replaceRange;
+}
+export {};

package/dist/core/engine/selection.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Selection positions expressed as character offsets through the document. Unlike DOM ranges they stay valid when
+ * the markup around the text is rebuilt (marks merged, blocks renamed, history restored).
+ */
+export interface TextBookmark {
+    /** Offset where the selection starts (for a saved selection: where the user started selecting). */
+    anchor: number;
+    /** Offset where the selection ends (for a saved selection: where the caret currently is). */
+    focus: number;
+}
+/** Index of a node among its parent's child nodes, or -1 when it has no parent. */
+export declare const indexOf: (node: Node) => number;
+/** The current selection range when it lies entirely inside `root`, otherwise `null`. */
+export declare const getRangeWithin: (root: HTMLElement) => Range | null;
+/** Replaces the document selection with `range`. */
+export declare const selectRange: (range: Range) => void;
+/** Places the caret before the first character of `element`. */
+export declare const placeCaretAtStart: (element: HTMLElement) => Range;
+/** Places the caret after the last character of `element`, in front of its placeholder break if it has one. */
+export declare const placeCaretAtEnd: (element: HTMLElement) => Range;
+/** Stores a range as document offsets; `anchor` is the start and `focus` the end. */
+export declare const rangeToBookmark: (root: HTMLElement, range: Range) => TextBookmark;
+/** Rebuilds a forward DOM range from a bookmark. */
+export declare const bookmarkToRange: (root: HTMLElement, bookmark: TextBookmark) => Range;
+/** Stores the current selection, keeping its direction, or returns `null` when it is outside `root`. */
+export declare const saveBookmark: (root: HTMLElement) => TextBookmark | null;
+/** Restores a selection saved with {@link saveBookmark}, including its direction. */
+export declare const restoreBookmark: (root: HTMLElement, bookmark: TextBookmark) => void;
+/** Scrolls the caret line into view inside the nearest scroll container. */
+export declare const scrollSelectionIntoView: (root: HTMLElement) => void;