@rtif-sdk/web 1.0.0

package/dist/renderer.js

@@ -0,0 +1,415 @@
+/**
+ * Determine the container element where span children should be placed
+ * for a given block element.
+ *
+ * For composite blocks (e.g., callout) whose renderer defines
+ * `getContentContainer`, spans are rendered inside a nested content
+ * element rather than directly in the block element. For all other
+ * block types the block element itself is the span container.
+ *
+ * @param blockEl - The block DOM element
+ * @param blockType - The RTIF block type string
+ * @param blockRenderers - Optional registry of block renderers
+ * @returns The element that should contain span children
+ *
+ * @example
+ * ```ts
+ * const container = getSpanContainer(blockEl, 'callout', registry);
+ * // For callout: returns the .rtif-callout-content div
+ * // For text:    returns blockEl itself
+ * ```
+ */
+function getSpanContainer(blockEl, blockType, blockRenderers) {
+    if (!blockRenderers)
+        return blockEl;
+    const renderer = blockRenderers.get(blockType);
+    if (renderer?.getContentContainer) {
+        return renderer.getContentContainer(blockEl) ?? blockEl;
+    }
+    return blockEl;
+}
+/**
+ * Create a DOM element for an RTIF span.
+ *
+ * When a `markRenderers` registry is provided and the span has a mark with a
+ * registered {@link SpanReplacer}, the replacer's `createElement()` is called
+ * to produce a fully custom element. Otherwise, a default `<span>` is created
+ * with mark renderers applied.
+ *
+ * Non-empty spans contain a single Text node. Empty spans (text === '')
+ * contain a `<br>` element so the block has layout height in the browser.
+ *
+ * @param span - The RTIF span to render
+ * @param markRenderers - Optional registry of mark renderers for visual styling
+ * @returns An `HTMLElement` with `data-rtif-span` attribute and appropriate child node
+ *
+ * @example
+ * ```ts
+ * const el = createSpanElement({ text: 'hello' });
+ * // <span data-rtif-span>hello</span>
+ *
+ * const boldEl = createSpanElement(
+ *   { text: 'bold', marks: { bold: true } },
+ *   markRegistry,
+ * );
+ * // <span data-rtif-span class="rtif-bold">bold</span>
+ * ```
+ */
+export function createSpanElement(span, markRenderers) {
+    // Check for span replacer before creating default element
+    if (markRenderers && span.marks) {
+        for (const markType of Object.keys(span.marks)) {
+            if (span.marks[markType] == null)
+                continue;
+            const replacer = markRenderers.getReplacer(markType);
+            if (replacer) {
+                const el = replacer.createElement(span.text, span.marks);
+                el.setAttribute('data-rtif-span', '');
+                return el;
+            }
+        }
+    }
+    const el = document.createElement('span');
+    el.setAttribute('data-rtif-span', '');
+    // Apply mark rendering
+    if (markRenderers) {
+        markRenderers.applyAll(el, span.marks);
+    }
+    if (span.text === '') {
+        el.appendChild(document.createElement('br'));
+    }
+    else {
+        el.appendChild(document.createTextNode(span.text));
+    }
+    return el;
+}
+/**
+ * Create a DOM block element for an RTIF block.
+ *
+ * Each block renders as a `<div>` with `data-rtif-block` set to the block ID
+ * and `data-block-type` set to the block type. Child span elements are created
+ * for each span in the block.
+ *
+ * When a `blockRenderers` registry is provided, the renderer for the block's
+ * type is applied to the element (adding CSS classes, ARIA roles, etc.).
+ *
+ * @param block - The RTIF block to render
+ * @param markRenderers - Optional registry of mark renderers for visual styling
+ * @param blockRenderers - Optional registry of block renderers for block-type styling
+ * @returns A `<div data-rtif-block="{id}" data-block-type="{type}">` element
+ *
+ * @example
+ * ```ts
+ * const el = createBlockElement({
+ *   id: 'b1',
+ *   type: 'text',
+ *   spans: [{ text: 'Hello world' }],
+ * });
+ * // <div data-rtif-block="b1" data-block-type="text">
+ * //   <span data-rtif-span>Hello world</span>
+ * // </div>
+ * ```
+ */
+export function createBlockElement(block, markRenderers, blockRenderers) {
+    const el = document.createElement('div');
+    el.setAttribute('data-rtif-block', block.id);
+    el.setAttribute('data-block-type', block.type);
+    if (blockRenderers) {
+        blockRenderers.applyToElement(el, block);
+    }
+    const container = getSpanContainer(el, block.type, blockRenderers);
+    for (const span of block.spans) {
+        container.appendChild(createSpanElement(span, markRenderers));
+    }
+    return el;
+}
+/**
+ * Find a block DOM element within a root by its RTIF block ID.
+ *
+ * @param root - The root element to search within
+ * @param blockId - The block ID to find (matches `data-rtif-block` attribute)
+ * @returns The matching element, or `null` if not found
+ *
+ * @example
+ * ```ts
+ * const blockEl = findBlockElement(root, 'b1');
+ * if (blockEl) {
+ *   console.log(blockEl.textContent);
+ * }
+ * ```
+ */
+export function findBlockElement(root, blockId) {
+    return root.querySelector(`[data-rtif-block="${blockId}"]`);
+}
+/**
+ * Perform a full initial render of an RTIF document into a root element.
+ *
+ * Clears all existing content in the root, then creates block and span
+ * elements for the entire document. Use this for the first render; use
+ * {@link reconcile} for subsequent updates.
+ *
+ * @param root - The root DOM element (typically `contenteditable`)
+ * @param doc - The RTIF document to render
+ * @param markRenderers - Optional registry of mark renderers for visual styling
+ * @param blockRenderers - Optional registry of block renderers for block-type styling
+ *
+ * @example
+ * ```ts
+ * const root = document.getElementById('editor')!;
+ * renderInitial(root, {
+ *   version: 1,
+ *   blocks: [{ id: 'b1', type: 'text', spans: [{ text: 'Hello' }] }],
+ * });
+ * ```
+ */
+export function renderInitial(root, doc, markRenderers, blockRenderers) {
+    // Clear all existing content without using innerHTML
+    while (root.firstChild) {
+        root.removeChild(root.firstChild);
+    }
+    for (const block of doc.blocks) {
+        root.appendChild(createBlockElement(block, markRenderers, blockRenderers));
+    }
+}
+/**
+ * Update the content of a span DOM element to match an RTIF span.
+ *
+ * Handles the transition between empty spans (`<br>`) and text spans
+ * (Text node) efficiently by reusing existing Text nodes when possible.
+ *
+ * @param spanEl - The existing span DOM element
+ * @param span - The RTIF span with the desired content
+ */
+function reconcileSpanContent(spanEl, span) {
+    if (span.text === '') {
+        // Empty span: must contain a <br>
+        while (spanEl.firstChild) {
+            spanEl.removeChild(spanEl.firstChild);
+        }
+        spanEl.appendChild(document.createElement('br'));
+    }
+    else {
+        // Non-empty span: must contain a Text node
+        const firstChild = spanEl.firstChild;
+        if (firstChild && firstChild.nodeType === Node.TEXT_NODE) {
+            // Reuse existing text node, just update value
+            firstChild.nodeValue = span.text;
+            // Remove any extra children (shouldn't happen, but be safe)
+            while (spanEl.childNodes.length > 1) {
+                spanEl.removeChild(spanEl.lastChild);
+            }
+        }
+        else {
+            // Replace all children with a text node
+            while (spanEl.firstChild) {
+                spanEl.removeChild(spanEl.firstChild);
+            }
+            spanEl.appendChild(document.createTextNode(span.text));
+        }
+    }
+}
+/**
+ * Reconcile the span children of a block element to match an RTIF block.
+ *
+ * Compares spans by reference identity to skip unchanged spans. When a span
+ * has changed, checks whether marks also changed — if so, replaces the
+ * entire span element to reflect new mark styling; otherwise, updates only
+ * the text content.
+ *
+ * @param container - The DOM element containing span children (may be the
+ *   block element itself or a content container for composite blocks)
+ * @param prevBlock - The previous RTIF block state
+ * @param nextBlock - The new RTIF block state
+ * @param markRenderers - Optional registry of mark renderers
+ */
+function reconcileBlockSpans(container, prevBlock, nextBlock, markRenderers) {
+    const prevSpans = prevBlock.spans;
+    const nextSpans = nextBlock.spans;
+    const spanElements = container.children;
+    // Update or replace existing spans
+    const minLen = Math.min(prevSpans.length, nextSpans.length);
+    for (let i = 0; i < minLen; i++) {
+        const prevSpan = prevSpans[i];
+        const nextSpan = nextSpans[i];
+        // Skip if same reference
+        if (prevSpan === nextSpan) {
+            continue;
+        }
+        const spanEl = spanElements[i];
+        if (spanEl) {
+            // If marks changed, try replacer update() before full replacement
+            if (prevSpan.marks !== nextSpan.marks) {
+                let handled = false;
+                if (markRenderers && nextSpan.marks) {
+                    for (const markType of Object.keys(nextSpan.marks)) {
+                        if (nextSpan.marks[markType] == null)
+                            continue;
+                        const replacer = markRenderers.getReplacer(markType);
+                        if (replacer?.update) {
+                            handled = replacer.update(spanEl, nextSpan.text, nextSpan.marks);
+                            break;
+                        }
+                    }
+                }
+                if (!handled) {
+                    const newSpanEl = createSpanElement(nextSpan, markRenderers);
+                    container.replaceChild(newSpanEl, spanEl);
+                }
+            }
+            else {
+                // Only text changed — check replacer update() for text-only changes too
+                let handled = false;
+                if (markRenderers && nextSpan.marks) {
+                    for (const markType of Object.keys(nextSpan.marks)) {
+                        if (nextSpan.marks[markType] == null)
+                            continue;
+                        const replacer = markRenderers.getReplacer(markType);
+                        if (replacer?.update) {
+                            handled = replacer.update(spanEl, nextSpan.text, nextSpan.marks);
+                            break;
+                        }
+                    }
+                }
+                if (!handled) {
+                    reconcileSpanContent(spanEl, nextSpan);
+                }
+            }
+        }
+    }
+    // Remove extra spans (next has fewer)
+    while (spanElements.length > nextSpans.length) {
+        container.removeChild(container.lastElementChild);
+    }
+    // Add new spans (next has more)
+    for (let i = prevSpans.length; i < nextSpans.length; i++) {
+        const nextSpan = nextSpans[i];
+        container.appendChild(createSpanElement(nextSpan, markRenderers));
+    }
+}
+/**
+ * Efficiently reconcile the DOM to match a new RTIF document state.
+ *
+ * Only touches blocks that have changed (detected by object reference
+ * comparison). Handles block additions, removals, reordering, and
+ * span-level content updates within changed blocks. When a block's type
+ * or attrs change (by reference), the entire block element is replaced
+ * to ensure block-renderer styling is re-applied cleanly.
+ *
+ * **Critical**: When `composingBlockId` is set (IME composition active),
+ * the block with that ID is skipped entirely to avoid disrupting the
+ * browser's native composition rendering.
+ *
+ * @param root - The root DOM element containing block elements
+ * @param prevDoc - The previous RTIF document state
+ * @param nextDoc - The new RTIF document state to reconcile toward
+ * @param composingBlockId - Block ID currently under IME composition, or `null`
+ * @param markRenderers - Optional registry of mark renderers for visual styling
+ * @param blockRenderers - Optional registry of block renderers for block-type styling
+ *
+ * @example
+ * ```ts
+ * // After an engine dispatch produces a new document:
+ * reconcile(root, prevDoc, nextDoc, composingBlockId, markRenderers, blockRenderers);
+ * ```
+ */
+export function reconcile(root, prevDoc, nextDoc, composingBlockId, markRenderers, blockRenderers) {
+    // Fast path: identical document reference
+    if (prevDoc === nextDoc) {
+        return;
+    }
+    // Build a lookup of previous blocks by ID for reference comparison
+    const prevBlockMap = new Map();
+    for (const block of prevDoc.blocks) {
+        prevBlockMap.set(block.id, block);
+    }
+    // Build a map of existing DOM block elements by ID
+    const existingElements = new Map();
+    for (let i = 0; i < root.children.length; i++) {
+        const child = root.children[i];
+        const blockId = child.getAttribute('data-rtif-block');
+        if (blockId) {
+            existingElements.set(blockId, child);
+        }
+    }
+    // Track which block IDs are in the next document
+    const nextBlockIds = new Set();
+    // Walk next blocks in order, using a reference node cursor to minimize moves
+    let referenceNode = root.firstChild;
+    for (const nextBlock of nextDoc.blocks) {
+        nextBlockIds.add(nextBlock.id);
+        let blockEl = existingElements.get(nextBlock.id) ?? null;
+        if (blockEl) {
+            // Block element already exists in the DOM
+            const prevBlock = prevBlockMap.get(nextBlock.id);
+            // Skip composing block entirely
+            if (nextBlock.id === composingBlockId) {
+                // Just make sure it's in the right position
+                if (blockEl !== referenceNode) {
+                    root.insertBefore(blockEl, referenceNode);
+                }
+                else {
+                    referenceNode = referenceNode.nextSibling;
+                }
+                continue;
+            }
+            // Check if block changed by reference
+            if (prevBlock !== nextBlock) {
+                // If block type or attrs changed, replace entire block element
+                // to ensure block-renderer styling is re-applied cleanly.
+                // This mirrors how mark changes replace span elements.
+                if (prevBlock && (prevBlock.type !== nextBlock.type || prevBlock.attrs !== nextBlock.attrs)) {
+                    const newBlockEl = createBlockElement(nextBlock, markRenderers, blockRenderers);
+                    root.replaceChild(newBlockEl, blockEl);
+                    // Update our reference so position tracking remains correct
+                    existingElements.set(nextBlock.id, newBlockEl);
+                    blockEl = newBlockEl;
+                    // replaceChild keeps position; advance referenceNode past replaced element
+                    referenceNode = newBlockEl.nextSibling;
+                    continue;
+                }
+                // Update block-type attribute if changed
+                if (blockEl.getAttribute('data-block-type') !== nextBlock.type) {
+                    blockEl.setAttribute('data-block-type', nextBlock.type);
+                }
+                // Reconcile spans within this block
+                if (prevBlock) {
+                    const container = getSpanContainer(blockEl, nextBlock.type, blockRenderers);
+                    reconcileBlockSpans(container, prevBlock, nextBlock, markRenderers);
+                }
+                else {
+                    // No previous block data — full re-render of span content
+                    const container = getSpanContainer(blockEl, nextBlock.type, blockRenderers);
+                    while (container.firstChild) {
+                        container.removeChild(container.firstChild);
+                    }
+                    for (const span of nextBlock.spans) {
+                        container.appendChild(createSpanElement(span, markRenderers));
+                    }
+                }
+            }
+            // Ensure correct position
+            if (blockEl !== referenceNode) {
+                root.insertBefore(blockEl, referenceNode);
+            }
+            else {
+                referenceNode = referenceNode.nextSibling;
+            }
+        }
+        else {
+            // New block — create element and insert at correct position
+            blockEl = createBlockElement(nextBlock, markRenderers, blockRenderers);
+            root.insertBefore(blockEl, referenceNode);
+        }
+    }
+    // Remove any block elements that are no longer in the document
+    const toRemove = [];
+    for (const [blockId, el] of existingElements) {
+        if (!nextBlockIds.has(blockId)) {
+            toRemove.push(el);
+        }
+    }
+    for (const el of toRemove) {
+        root.removeChild(el);
+    }
+}
+//# sourceMappingURL=renderer.js.map

package/dist/renderer.js.map

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

package/dist/scroll-to-cursor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Scroll-to-cursor utility.
+ *
+ * After every operation that moves the cursor (typing, Enter, paste, undo),
+ * the implementation MUST ensure the cursor is visible within the scrollable
+ * viewport (platform-requirements §12.1).
+ *
+ * @module
+ */
+/**
+ * Scroll the viewport so the current cursor (DOM focus point) is visible.
+ *
+ * Uses the browser's native `scrollIntoView` on the element nearest the
+ * caret. Gracefully no-ops when there is no selection, the focus is outside
+ * the editor root, or layout information is unavailable (e.g. jsdom).
+ *
+ * @param root - The contenteditable root element
+ *
+ * @example
+ * ```ts
+ * scrollToCursor(editorRoot);
+ * ```
+ */
+export declare function scrollToCursor(root: HTMLElement): void;
+//# sourceMappingURL=scroll-to-cursor.d.ts.map

package/dist/scroll-to-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-to-cursor.d.ts","sourceRoot":"","sources":["../src/scroll-to-cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAqCtD"}

package/dist/scroll-to-cursor.js

@@ -0,0 +1,59 @@
+/**
+ * Scroll-to-cursor utility.
+ *
+ * After every operation that moves the cursor (typing, Enter, paste, undo),
+ * the implementation MUST ensure the cursor is visible within the scrollable
+ * viewport (platform-requirements §12.1).
+ *
+ * @module
+ */
+/**
+ * Scroll the viewport so the current cursor (DOM focus point) is visible.
+ *
+ * Uses the browser's native `scrollIntoView` on the element nearest the
+ * caret. Gracefully no-ops when there is no selection, the focus is outside
+ * the editor root, or layout information is unavailable (e.g. jsdom).
+ *
+ * @param root - The contenteditable root element
+ *
+ * @example
+ * ```ts
+ * scrollToCursor(editorRoot);
+ * ```
+ */
+export function scrollToCursor(root) {
+    const sel = root.ownerDocument.defaultView?.getSelection();
+    if (!sel || sel.rangeCount === 0)
+        return;
+    const { focusNode, focusOffset } = sel;
+    if (!focusNode)
+        return;
+    // Ensure the focus is inside the editor root
+    if (!root.contains(focusNode))
+        return;
+    // Create a collapsed range at the focus point
+    const range = root.ownerDocument.createRange();
+    try {
+        range.setStart(focusNode, focusOffset);
+        range.collapse(true);
+    }
+    catch {
+        // Invalid offset — bail
+        return;
+    }
+    // getBoundingClientRect may not exist in non-browser environments (jsdom)
+    if (typeof range.getBoundingClientRect !== 'function')
+        return;
+    const rect = range.getBoundingClientRect();
+    // Zero-dimension rect means no layout (jsdom, detached element, etc.)
+    if (rect.width === 0 && rect.height === 0)
+        return;
+    // Find the nearest element ancestor to call scrollIntoView on
+    const element = focusNode.nodeType === Node.ELEMENT_NODE
+        ? focusNode
+        : focusNode.parentElement;
+    if (!element)
+        return;
+    element.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+}
+//# sourceMappingURL=scroll-to-cursor.js.map

package/dist/scroll-to-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-to-cursor.js","sourceRoot":"","sources":["../src/scroll-to-cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,IAAiB;IAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,YAAY,EAAE,CAAC;IAC3D,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,KAAK,CAAC;QAAE,OAAO;IAEzC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC;IACvC,IAAI,CAAC,SAAS;QAAE,OAAO;IAEvB,6CAA6C;IAC7C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO;IAEtC,8CAA8C;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,CAAC;IAC/C,IAAI,CAAC;QACH,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QACvC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,wBAAwB;QACxB,OAAO;IACT,CAAC;IAED,0EAA0E;IAC1E,IAAI,OAAO,KAAK,CAAC,qBAAqB,KAAK,UAAU;QAAE,OAAO;IAE9D,MAAM,IAAI,GAAG,KAAK,CAAC,qBAAqB,EAAE,CAAC;IAE3C,sEAAsE;IACtE,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAElD,8DAA8D;IAC9D,MAAM,OAAO,GACX,SAAS,CAAC,QAAQ,KAAK,IAAI,CAAC,YAAY;QACtC,CAAC,CAAE,SAAqB;QACxB,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC;IAE9B,IAAI,CAAC,OAAO;QAAE,OAAO;IAErB,OAAO,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AAClE,CAAC"}

package/dist/selection-sync.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Bidirectional DOM Selection <-> RTIF Selection synchronization.
+ *
+ * Converts between the browser's Selection API (anchorNode/offset,
+ * focusNode/offset) and RTIF's absolute integer offset Selection
+ * ({anchor: {offset}, focus: {offset}}).
+ *
+ * Relies on the DOM structure produced by the renderer:
+ * - Root: `[data-rtif-root]` contenteditable div
+ * - Blocks: `div[data-rtif-block="{id}"]`
+ * - Spans: `span[data-rtif-span]` with Text node or `<br>` children
+ */
+import type { Document, Selection } from '@rtif-sdk/core';
+import type { BlockOffsetEntry, DomPoint } from './types.js';
+/**
+ * Build an array of block offset entries for fast DOM <-> RTIF conversion.
+ *
+ * Each entry records the block's ID, its absolute start offset in the
+ * document, and its text length. Block N+1 starts at
+ * `block[N].startOffset + block[N].length + 1` (the +1 is the virtual `\n`
+ * separator between consecutive blocks).
+ *
+ * @param doc - The RTIF document
+ * @returns Array of offset entries, one per block, in document order
+ *
+ * @example
+ * ```ts
+ * const doc = { version: 1, blocks: [
+ *   { id: 'b1', type: 'text', spans: [{ text: 'hello' }] },
+ *   { id: 'b2', type: 'text', spans: [{ text: 'world' }] },
+ * ]};
+ * buildBlockOffsetCache(doc);
+ * // => [
+ * //   { blockId: 'b1', startOffset: 0, length: 5 },
+ * //   { blockId: 'b2', startOffset: 6, length: 5 },
+ * // ]
+ * ```
+ */
+export declare function buildBlockOffsetCache(doc: Document): BlockOffsetEntry[];
+/**
+ * Convert a DOM position (node + offset) to an absolute RTIF document offset.
+ *
+ * Walks up from the given node to find the containing block element
+ * (`[data-rtif-block]`), then walks the block's span children to compute the
+ * local character offset. Adds the block's start offset from the cache.
+ *
+ * @param root - The editor's root element (`[data-rtif-root]`)
+ * @param node - The DOM node containing the position
+ * @param domOffset - The offset within the node (character offset for Text nodes,
+ *                    child index for Element nodes)
+ * @param cache - Pre-built block offset cache from `buildBlockOffsetCache`
+ * @returns The absolute RTIF offset, or `null` if the node is outside the
+ *          editor or not inside a recognized block
+ *
+ * @example
+ * ```ts
+ * const textNode = blockEl.querySelector('[data-rtif-span]')!.firstChild!;
+ * const rtifOffset = domPointToRtifOffset(root, textNode, 3, cache);
+ * ```
+ */
+export declare function domPointToRtifOffset(root: HTMLElement, node: Node, domOffset: number, cache: BlockOffsetEntry[]): number | null;
+/**
+ * Convert an absolute RTIF document offset to a DOM point (node + offset).
+ *
+ * Uses `resolve()` from `@rtif-sdk/core` to find the block index and local offset,
+ * then walks the block's span elements in the DOM to locate the correct text
+ * node and character position.
+ *
+ * @param root - The editor's root element (`[data-rtif-root]`)
+ * @param doc - The current RTIF document (must match the DOM structure)
+ * @param offset - The absolute RTIF document offset
+ * @returns A DOM point, or `null` if the DOM is out of sync with the document
+ *
+ * @example
+ * ```ts
+ * const point = rtifOffsetToDomPoint(root, doc, 5);
+ * if (point) {
+ *   console.log(point.node, point.offset);
+ * }
+ * ```
+ */
+export declare function rtifOffsetToDomPoint(root: HTMLElement, doc: Document, offset: number): DomPoint | null;
+/**
+ * Read the browser's current DOM selection and convert it to an RTIF Selection.
+ *
+ * Returns `null` if:
+ * - There is no selection or no ranges
+ * - The selection is outside the editor root
+ * - Either anchor or focus cannot be resolved to an RTIF offset
+ *
+ * @param root - The editor's root element (`[data-rtif-root]`)
+ * @param cache - Pre-built block offset cache from `buildBlockOffsetCache`
+ * @returns The RTIF Selection, or `null` if the selection cannot be resolved
+ *
+ * @example
+ * ```ts
+ * const sel = readDomSelection(root, cache);
+ * if (sel) {
+ *   engine.dispatch({ type: 'set_selection', selection: sel });
+ * }
+ * ```
+ */
+export declare function readDomSelection(root: HTMLElement, cache: BlockOffsetEntry[]): Selection | null;
+/**
+ * Set the browser's DOM selection to match an RTIF Selection.
+ *
+ * Converts the RTIF anchor and focus offsets to DOM points, then calls
+ * `setBaseAndExtent()` on the window's Selection object.
+ *
+ * Sets the suppression flag to `true` before modifying the selection, to
+ * prevent the `selectionchange` event handler from triggering a feedback
+ * loop. The flag is reset via `requestAnimationFrame`.
+ *
+ * If either offset cannot be resolved to a DOM point (e.g., DOM is out of
+ * sync), the function is a no-op.
+ *
+ * @param root - The editor's root element (`[data-rtif-root]`)
+ * @param doc - The current RTIF document
+ * @param selection - The RTIF selection to apply to the DOM
+ *
+ * @example
+ * ```ts
+ * setDomSelection(root, doc, { anchor: { offset: 0 }, focus: { offset: 5 } });
+ * ```
+ */
+export declare function setDomSelection(root: HTMLElement, doc: Document, selection: Selection): void;
+/**
+ * Returns `true` if the selection-sync layer is currently suppressing
+ * `selectionchange` events to avoid feedback loops.
+ *
+ * The `selectionchange` handler in the input bridge should check this flag
+ * and skip processing when it returns `true`.
+ *
+ * @returns Whether selectionchange events should be suppressed
+ *
+ * @example
+ * ```ts
+ * document.addEventListener('selectionchange', () => {
+ *   if (isSuppressed()) return;
+ *   handleUserSelectionChange();
+ * });
+ * ```
+ */
+export declare function isSuppressed(): boolean;
+/**
+ * Manually reset the suppression flag to `false`.
+ *
+ * Primarily useful for testing, where `requestAnimationFrame` may not run.
+ * Production code should not need to call this.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   resetSuppression();
+ * });
+ * ```
+ */
+export declare function resetSuppression(): void;
+//# sourceMappingURL=selection-sync.d.ts.map