superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/layout-bridge/src/remeasure.d.ts

@@ -0,0 +1,75 @@
+import { ParagraphBlock, ParagraphMeasure } from '../../contracts/src/index.js';
+/** Drop cached text widths and the canvas context. Call when registered font faces may have changed. */
+export declare function clearRemeasureTextCaches(): void;
+/**
+ * Re-measure a paragraph block to fit within a specified maximum width.
+ *
+ * This function performs fast, canvas-based text measurement and line breaking for
+ * paragraphs that need to be reflowed due to column width changes (e.g., when a
+ * document transitions from single-column to multi-column layout, or when floating
+ * images reduce available width). It implements a greedy line-breaking algorithm
+ * with support for tab stops, indentation, and word wrapping.
+ *
+ * Why remeasurement is needed:
+ * - Paragraphs are initially measured at document load for the widest column width
+ * - When placed in narrower columns, text must reflow to fit the reduced width
+ * - Floating images can further reduce available width, requiring dynamic remeasurement
+ * - Remeasurement is expensive, so it's only performed when necessary (width changes)
+ *
+ * Measurement approach:
+ * - Uses HTML5 Canvas API for accurate text width measurement (same as initial measurement)
+ * - Performs greedy word-based line breaking (breaks at whitespace when text exceeds maxWidth)
+ * - Respects paragraph indents (left, right, firstLine, hanging)
+ * - Processes tab stops using OOXML tab stop resolution algorithm
+ * - Falls back to estimated widths if canvas context is unavailable (server-side rendering)
+ *
+ * Limitations:
+ * - Does NOT perform full typography measurement (ascent, descent, font metrics)
+ * - Line height is estimated from paragraph spacing and max font size.
+ * - Does NOT handle complex features like drop caps, justified alignment compression, or bidirectional text
+ * - Intended as a fast path for width-constrained remeasurement, not full initial measurement
+ *
+ * @param block - The paragraph block to measure, containing runs of text/tabs/images and formatting attributes.
+ *   Must have a valid runs array with text runs that have fontSize and fontFamily properties.
+ * @param maxWidth - Maximum available width in pixels for the paragraph content.
+ *   This should be the column width minus left and right indents, adjusted for any floating images.
+ *   Must be a positive number for meaningful line breaking.
+ * @param firstLineIndent - Additional indent to apply to the first line in pixels (default: 0).
+ *   Used for in-flow list markers in firstLineIndentMode where the marker consumes horizontal space
+ *   on the first line. For standard hanging indent lists, this should be 0 as the marker is positioned
+ *   absolutely outside the text flow.
+ * @returns A ParagraphMeasure object containing:
+ *   - kind: 'paragraph' (discriminator for measure type)
+ *   - lines: Array of Line objects with fromRun/toRun/fromChar/toChar boundaries, width, and lineHeight
+ *   - totalHeight: Sum of all line heights in pixels
+ *   Note: Does NOT include full typography metrics (ascent, descent) - these are computed by the full measurer
+ *
+ * @throws Does not throw exceptions, but will produce degraded output if:
+ *   - maxWidth is zero or negative (lines will be very narrow or degenerate)
+ *   - block.runs is empty or invalid (will produce empty or minimal measure)
+ *   - Canvas context is unavailable (will use fallback width estimation)
+ *
+ * @example
+ * ```typescript
+ * const block: ParagraphBlock = {
+ *   kind: 'paragraph',
+ *   id: 'p1',
+ *   runs: [
+ *     { text: 'Hello world', fontFamily: 'Arial', fontSize: 16 }
+ *   ],
+ *   attrs: {
+ *     indent: { left: 20, right: 20, firstLine: 0, hanging: 0 }
+ *   }
+ * };
+ *
+ * // Remeasure for a narrower column width
+ * const measure = remeasureParagraph(block, 200);
+ * // Returns: { kind: 'paragraph', lines: [...], totalHeight: 38.4 }
+ * // (text breaks into 2 lines of ~19.2px each)
+ *
+ * // Remeasure with first line indent for list marker
+ * const measureWithIndent = remeasureParagraph(block, 200, 30);
+ * // First line has only 170px available (200 - 30), subsequent lines have full 200px
+ * ```
+ */
+export declare function remeasureParagraph(block: ParagraphBlock, maxWidth: number, firstLineIndent?: number): ParagraphMeasure;

package/dist/layout-engine/layout-bridge/src/resolveHeaderFooterTokens.d.ts

@@ -0,0 +1,76 @@
+import { FlowBlock, PageNumberChapterSeparator, PageNumberFormat } from '../../contracts/src/index.js';
+/**
+ * Placeholder for a total-page-count field whose source document carries no
+ * cached result while pagination is still provisional. An em dash reads as
+ * "value not yet known" without committing to a wrong number.
+ */
+export declare const PROVISIONAL_PAGE_COUNT_PLACEHOLDER = "\u2014";
+/**
+ * Options for {@link resolveHeaderFooterTokens}.
+ */
+export interface ResolveHeaderFooterTokensOptions {
+    /**
+     * When `false`, document-total fields (`NUMPAGES` / `SECTIONPAGES`) are NOT
+     * substituted with the supplied totals: the run keeps its source-cached DOCX
+     * result text, falling back to {@link PROVISIONAL_PAGE_COUNT_PLACEHOLDER}
+     * when no cached result exists. `PAGE` always resolves — the physical page
+     * a header/footer paints on is known even under partial pagination.
+     * Defaults to `true` (exact totals), preserving existing caller behavior.
+     */
+    pageCountFieldsExact?: boolean;
+}
+/**
+ * Resolves page number tokens in a batch of header or footer blocks.
+ *
+ * Headers and footers can contain the same token types as body content
+ * (pageNumber, totalPageCount, sectionPageCount), but they need to be resolved to the specific
+ * page where the header/footer will appear. This function mutates the blocks
+ * in-place to replace token placeholders with actual values.
+ *
+ * The function processes all variants in the batch (default, first, even, odd),
+ * applying the same page context to all. This is correct because a single batch
+ * represents headers/footers for one specific page.
+ *
+ * IMPORTANT: This function modifies blocks in-place. The calling code should
+ * ensure that blocks are not shared between multiple page contexts, or should
+ * create copies before calling this function.
+ *
+ * @param blocks - Array of FlowBlocks for a single header/footer variant
+ * @param pageNumber - Current page number (1-indexed) where this header/footer appears
+ * @param totalPages - Total number of pages in the document
+ * @param pageNumberText - Optional preformatted page number string (e.g., "-1-")
+ *
+ * @example
+ * ```typescript
+ * // Resolve tokens for the header that will appear on page 3
+ * const headerBlocks = adapter.getBlocks('header', 'default');
+ * resolveHeaderFooterTokens(headerBlocks, 3, 10);
+ * // Now headerBlocks contain "3" instead of "0" for PAGE field
+ * // and "10" for NUMPAGES field
+ * ```
+ */
+export declare function resolveHeaderFooterTokens(blocks: FlowBlock[], pageNumber: number, totalPages: number, pageNumberText?: string, displayPageNumber?: number, sectionPageCount?: number, pageNumberFormat?: PageNumberFormat, chapterNumberText?: string, chapterSeparator?: PageNumberChapterSeparator, options?: ResolveHeaderFooterTokensOptions): void;
+/**
+ * Creates a deep copy of header/footer blocks to avoid mutating shared data.
+ *
+ * Since token resolution modifies blocks in-place, and the same header/footer
+ * content may be used across multiple pages (with different page numbers),
+ * we need to create independent copies for each page.
+ *
+ * This function performs a deep clone of the block structure, including runs
+ * and all nested properties, to ensure complete isolation.
+ *
+ * @param blocks - Original blocks to copy
+ * @returns Deep copy of the blocks
+ *
+ * @example
+ * ```typescript
+ * const originalBlocks = adapter.getBlocks('header', 'default');
+ * const blocksForPage1 = cloneHeaderFooterBlocks(originalBlocks);
+ * const blocksForPage2 = cloneHeaderFooterBlocks(originalBlocks);
+ * // Now we can resolve tokens differently for each page
+ * resolveHeaderFooterTokens(blocksForPage1, 1, 10);
+ * resolveHeaderFooterTokens(blocksForPage2, 2, 10);
+ * ```
+ */
+export declare function cloneHeaderFooterBlocks(blocks: FlowBlock[]): FlowBlock[];

package/dist/layout-engine/layout-bridge/src/rtl-text-geometry.d.ts

@@ -0,0 +1,34 @@
+import { NeutralTextDirection } from '../../contracts/src/index.js';
+/**
+ * Whether a measured line's visible text mixes content that breaks the
+ * single-level RTL reverse mapping.
+ *
+ * Returns `true` (→ caller fails closed with `unsupported-complex-bidi`) when
+ * the text contains either:
+ *   - any Unicode number (a weak-direction numeric run that the UBA can render
+ *     as a contiguous number, not where a pure reverse would place it), or
+ *   - a strong-LTR letter (any Unicode letter outside the strong-RTL ranges).
+ *
+ * Pure Hebrew/Arabic text with neutral punctuation, spaces, and RTL marks
+ * returns `false` and is safe to mirror. Conservative by design: when in doubt
+ * the caller fails closed rather than emit a mirrored-twice caret.
+ */
+export declare function lineHasComplexBidiContent(text: string): boolean;
+/**
+ * Container-space x for a logical advance (px measured from the logical line
+ * start, as returned by `measureCharacterX(..., 'left')`).
+ *
+ * LTR: `contentLeft + advance`. RTL: mirrored about the content box so the
+ * logical start sits at the visual right edge.
+ */
+export declare function logicalAdvanceToContainerX(direction: NeutralTextDirection, contentLeft: number, contentWidth: number, advance: number): number;
+/**
+ * Logical advance (px from the logical line start, clamped to
+ * `[0, contentWidth]`) for a container-space x.
+ *
+ * The exact inverse of {@link logicalAdvanceToContainerX}: feed the result to
+ * `findCharacterAtX(..., 'left')` to recover the logical character offset for
+ * either direction. For RTL the visual-left edge maps to the logical end and the
+ * visual-right edge maps to the logical start.
+ */
+export declare function containerXToLogicalAdvance(direction: NeutralTextDirection, contentLeft: number, contentWidth: number, containerX: number): number;

package/dist/layout-engine/layout-bridge/src/run-visual-marks.d.ts

@@ -0,0 +1,12 @@
+import { Run } from '../../contracts/src/index.js';
+/**
+ * Builds a deterministic substring for measure-cache keys and dirty-run comparison.
+ *
+ * Include every run property that affects text measurement or painted output but is not
+ * covered elsewhere (e.g. tracked-change / comment keys). When adding a new visual
+ * property, update this function only — `cache.ts` and `diff.ts` both depend on it.
+ *
+ * @param run - Flow run (text, tab, image, etc.); unknown fields are ignored safely.
+ * @returns Stable string encoding bold/italic/underline/strike/color/font/highlight/link.
+ */
+export declare const hashRunVisualMarks: (run: Run) => string;

package/dist/layout-engine/layout-bridge/src/safety-net.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Runtime Safety Net
+ *
+ * Automatic fallback system that monitors for errors and performance degradation.
+ * Triggers fallback to legacy behavior when issues are detected, then attempts
+ * recovery after a cooldown period.
+ *
+ * Fallback Triggers:
+ * - Consecutive errors exceeding threshold
+ * - Latency exceeding configured budgets
+ * - Manual fallback request
+ *
+ * Recovery Strategy:
+ * - Cooldown period after fallback
+ * - Automatic recovery attempt
+ * - Error count reset on successful operations
+ *
+ * @module safety-net
+ */
+/**
+ * Reason for triggering fallback to legacy behavior.
+ */
+export type FallbackReason = 'error' | 'latency' | 'budget_exceeded' | 'manual';
+/**
+ * Configuration for the safety net system.
+ */
+export interface SafetyConfig {
+    /** Maximum consecutive errors before triggering fallback */
+    maxConsecutiveErrors: number;
+    /** Maximum layout duration in ms before triggering fallback */
+    maxLayoutDuration: number;
+    /** Maximum cursor update latency in ms before triggering fallback */
+    maxCursorLatency: number;
+    /** Cooldown period in ms before attempting recovery */
+    cooldownPeriod: number;
+}
+/**
+ * Safety net for automatic fallback and recovery.
+ *
+ * Monitors system health and triggers fallback when performance degrades
+ * or errors accumulate. Attempts recovery after cooldown.
+ *
+ * @example
+ * ```typescript
+ * const safety = new SafetyNet({
+ *   maxConsecutiveErrors: 3,
+ *   maxLayoutDuration: 100,
+ *   cooldownPeriod: 5000,
+ * });
+ *
+ * // Set fallback handler
+ * safety.setFallbackHandler((reason) => {
+ *   console.warn(`Fallback triggered: ${reason}`);
+ *   // Disable optimizations
+ * });
+ *
+ * // Record errors
+ * try {
+ *   performOptimizedLayout();
+ *   safety.reset(); // Success - clear error count
+ * } catch (err) {
+ *   safety.recordError(err);
+ *   if (safety.isFallbackActive()) {
+ *     // Use legacy code path
+ *   }
+ * }
+ *
+ * // Record latency
+ * safety.recordLatency('layout', layoutDuration);
+ * ```
+ */
+export declare class SafetyNet {
+    private config;
+    private errorCount;
+    private fallbackActive;
+    private fallbackReason;
+    private cooldownTimer;
+    private onFallback;
+    private onRecovery;
+    /**
+     * Creates a new safety net instance.
+     *
+     * @param config - Safety configuration
+     */
+    constructor(config?: Partial<SafetyConfig>);
+    /**
+     * Records an error occurrence.
+     *
+     * Increments error count and triggers fallback if threshold exceeded.
+     *
+     * @param error - Error that occurred
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   dangerousOperation();
+     * } catch (err) {
+     *   safety.recordError(err);
+     * }
+     * ```
+     */
+    recordError(error: Error): void;
+    /**
+     * Records a latency measurement.
+     *
+     * Triggers fallback if latency exceeds configured budget.
+     *
+     * @param metric - Metric name ('layout' or 'cursor')
+     * @param value - Measured latency in ms
+     *
+     * @example
+     * ```typescript
+     * const duration = measureLayoutDuration();
+     * safety.recordLatency('layout', duration);
+     * ```
+     */
+    recordLatency(metric: string, value: number): void;
+    /**
+     * Checks if fallback mode is currently active.
+     *
+     * @returns True if system is in fallback mode
+     *
+     * @example
+     * ```typescript
+     * if (safety.isFallbackActive()) {
+     *   // Use legacy code path
+     * } else {
+     *   // Use optimized code path
+     * }
+     * ```
+     */
+    isFallbackActive(): boolean;
+    /**
+     * Gets the reason for current fallback state.
+     *
+     * @returns Fallback reason, or null if not in fallback
+     *
+     * @example
+     * ```typescript
+     * const reason = safety.getFallbackReason();
+     * if (reason) {
+     *   console.log(`System in fallback due to: ${reason}`);
+     * }
+     * ```
+     */
+    getFallbackReason(): FallbackReason | null;
+    /**
+     * Manually triggers fallback mode.
+     *
+     * Useful for testing or manual intervention.
+     *
+     * @param reason - Reason for manual fallback
+     *
+     * @example
+     * ```typescript
+     * // Force fallback for testing
+     * safety.triggerFallback('manual');
+     * ```
+     */
+    triggerFallback(reason: FallbackReason): void;
+    /**
+     * Attempts to recover from fallback state.
+     *
+     * Returns true if recovery successful, false if still in cooldown.
+     *
+     * @returns True if recovered, false if still in cooldown
+     *
+     * @example
+     * ```typescript
+     * if (safety.attemptRecovery()) {
+     *   console.log('Recovery successful');
+     * }
+     * ```
+     */
+    attemptRecovery(): boolean;
+    /**
+     * Sets the fallback handler callback.
+     *
+     * Called when fallback is triggered.
+     *
+     * @param handler - Callback function to handle fallback
+     *
+     * @example
+     * ```typescript
+     * safety.setFallbackHandler((reason) => {
+     *   // Disable optimizations and use legacy path
+     *   console.warn('Fallback triggered:', reason);
+     * });
+     * ```
+     */
+    setFallbackHandler(handler: (reason: FallbackReason) => void): void;
+    /**
+     * Sets the recovery handler callback.
+     *
+     * Called when recovery from fallback is attempted.
+     *
+     * @param handler - Callback function to handle recovery
+     *
+     * @example
+     * ```typescript
+     * safety.setRecoveryHandler(() => {
+     *   // Re-enable optimizations
+     *   console.log('Recovered from fallback');
+     * });
+     * ```
+     */
+    setRecoveryHandler(handler: () => void): void;
+    /**
+     * Resets the error count.
+     *
+     * Call this after successful operations to prevent false positives.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   performLayout();
+     *   safety.reset(); // Success - clear errors
+     * } catch (err) {
+     *   safety.recordError(err);
+     * }
+     * ```
+     */
+    reset(): void;
+    /**
+     * Schedules automatic recovery after cooldown period.
+     */
+    private scheduleRecovery;
+    /**
+     * Cleans up timers and resources.
+     *
+     * Call this when destroying the safety net.
+     */
+    destroy(): void;
+}

package/dist/layout-engine/layout-bridge/src/sectionAwareHeaderFooter.d.ts

@@ -0,0 +1,15 @@
+import { FlowBlock, SectionMetadata, SectionRefType } from '../../contracts/src/index.js';
+import { HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+export type HeaderFooterSectionKind = 'header' | 'footer';
+export type HeaderFooterRefs = Partial<Record<SectionRefType, string>>;
+export type SectionAwareHeaderFooterMeasurementGroup = {
+    rId: string;
+    sectionIndices: Set<number>;
+    sectionConstraints: HeaderFooterConstraints;
+    effectiveWidth: number;
+};
+export declare function buildSectionAwareHeaderFooterLayoutKey(rId: string, sectionIndex: number): string;
+export declare function buildSectionContentWidth(section: SectionMetadata, fallback: HeaderFooterConstraints): number;
+export declare function buildEffectiveHeaderFooterRefsBySection(sectionMetadata: SectionMetadata[], kind: HeaderFooterSectionKind): Map<number, HeaderFooterRefs>;
+export declare function collectReferencedHeaderFooterRIds(effectiveRefsBySection: Map<number, HeaderFooterRefs>): Set<string>;
+export declare function buildSectionAwareHeaderFooterMeasurementGroups(kind: HeaderFooterSectionKind, blocksByRId: Map<string, FlowBlock[]> | undefined, sectionMetadata: SectionMetadata[], fallbackConstraints: HeaderFooterConstraints): SectionAwareHeaderFooterMeasurementGroup[];

package/dist/layout-engine/layout-bridge/src/table-handler.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Table Handler
+ *
+ * Manages table-specific layout behavior during editing, including
+ * column width recalculation debouncing and cell edit tracking.
+ *
+ * Strategy:
+ * 1. Track table states (column widths, row heights)
+ * 2. Mark tables dirty on cell edits
+ * 3. Debounce column width recalculation
+ * 4. Provide table state for incremental layout
+ *
+ * @module table-handler
+ */
+/**
+ * Layout state for a single table.
+ */
+export interface TableLayoutState {
+    /** Table block index */
+    tableIndex: number;
+    /** Column widths in pixels */
+    columnWidths: number[];
+    /** Row heights in pixels */
+    rowHeights: number[];
+    /** Whether table needs recalculation */
+    dirty: boolean;
+}
+/**
+ * TableHandler manages table-specific layout optimizations.
+ */
+export declare class TableHandler {
+    private tableStates;
+    private columnRecalcDebounce;
+    private recalcTimers;
+    /**
+     * Handle edit within a table cell.
+     *
+     * @param tableIndex - Block index of the table
+     * @param cellIndex - Index of the edited cell
+     */
+    onCellEdit(tableIndex: number, _cellIndex: number): void;
+    /**
+     * Get table state for layout.
+     *
+     * @param tableIndex - Table block index
+     * @returns Table state if exists, undefined otherwise
+     */
+    getTableState(tableIndex: number): TableLayoutState | undefined;
+    /**
+     * Mark table columns for recalculation.
+     *
+     * @param tableIndex - Table block index
+     */
+    markColumnsDirty(tableIndex: number): void;
+    /**
+     * Should column width recalculation be deferred?
+     *
+     * @returns True if recalculation is pending
+     */
+    shouldDeferColumnRecalc(): boolean;
+    /**
+     * Update table layout state after recalculation.
+     *
+     * @param tableIndex - Table block index
+     * @param columnWidths - New column widths
+     * @param rowHeights - New row heights
+     */
+    updateTableState(tableIndex: number, columnWidths: number[], rowHeights: number[]): void;
+    /**
+     * Clear all table states.
+     */
+    clear(): void;
+    /**
+     * Get all dirty table indices.
+     *
+     * @returns Array of table indices needing recalculation
+     */
+    getDirtyTables(): number[];
+    /**
+     * Schedule column width recalculation with debouncing.
+     *
+     * @param tableIndex - Table block index
+     * @private
+     */
+    private scheduleColumnRecalc;
+}

package/dist/layout-engine/layout-bridge/src/text-boundaries.d.ts

@@ -0,0 +1,17 @@
+import { FlowBlock } from '../../contracts/src/index.js';
+/**
+ * Represents a boundary range with start and end positions
+ */
+export type BoundaryRange = {
+    from: number;
+    to: number;
+};
+/**
+ * Find word boundaries around a given position in a block
+ * Uses Unicode word boundary detection
+ */
+export declare function findWordBoundaries(blocks: FlowBlock[], pos: number): BoundaryRange | null;
+/**
+ * Find paragraph boundaries (entire block) around a given position
+ */
+export declare function findParagraphBoundaries(blocks: FlowBlock[], pos: number): BoundaryRange | null;

package/dist/layout-engine/layout-bridge/src/text-measurement.d.ts

@@ -0,0 +1,69 @@
+import { FlowBlock, Line, Run } from '../../contracts/src/index.js';
+import { FontMeasureContext } from '../../../shared/font-system/src/index.js';
+/**
+ * Generates a CSS font string from a run's formatting properties.
+ *
+ * @param run - The text or tab run to generate font string for
+ * @returns CSS font string (e.g., "italic bold 16px Arial")
+ */
+export declare function getRunFontString(run: Run, fontContext?: FontMeasureContext): string;
+/**
+ * Measure the X position for a specific character offset within a line.
+ * Uses Canvas measureText for pixel-perfect accuracy.
+ *
+ * @param block - The paragraph block containing the line
+ * @param line - The line to measure within
+ * @param charOffset - Character offset from the start of the line (0-based)
+ * @param availableWidthOverride - Optional override for available width
+ * @param alignmentOverride - Optional override for text alignment (e.g., 'left' for list items
+ *   which are always rendered left-aligned in the DOM regardless of paragraph alignment)
+ * @returns The X coordinate (in pixels) from the start of the line
+ */
+export declare function measureCharacterX(block: FlowBlock, line: Line, charOffset: number, availableWidthOverride?: number, alignmentOverride?: string, fontContext?: FontMeasureContext): number;
+/**
+ * Convert a character offset within a line back to a ProseMirror position.
+ *
+ * This function is the inverse of finding a character offset from a PM position.
+ * It accounts for PM position gaps that can occur between runs due to wrapper nodes
+ * (e.g., inline formatting marks, link nodes) that don't correspond to visible characters.
+ *
+ * Algorithm:
+ * 1. Iterate through runs in the line, tracking cumulative character offset
+ * 2. For each run, determine its character length (accounting for tabs as 1 character)
+ * 3. When the target charOffset falls within a run:
+ *    - Calculate the offset within that run
+ *    - Add to the run's pmStart to get the final PM position
+ * 4. If charOffset exceeds all runs, return the last known PM position
+ *
+ * Edge Cases:
+ * - **Character offset beyond line bounds**: Returns the last PM position in the line (clamped to end)
+ * - **Negative character offset**: Clamped to 0, returns fallbackPmStart
+ * - **Runs with missing PM data**: Falls back to fallbackPmStart + charOffset calculation
+ * - **Non-paragraph blocks**: Returns fallbackPmStart + charOffset (simple arithmetic fallback)
+ * - **Empty runs**: Skipped during iteration, don't contribute to character count
+ * - **Tab runs**: Counted as 1 character regardless of visual width
+ *
+ * @param block - The paragraph block containing the line
+ * @param line - The line to map within
+ * @param charOffset - Character offset from start of line (0-based)
+ * @param fallbackPmStart - PM position to use when run PM data is missing or invalid
+ * @returns ProseMirror position corresponding to the character offset
+ *
+ * @example
+ * ```typescript
+ * // Line with runs: "Hello" (PM 0-5) + "World" (PM 7-12), gap at 5-7
+ * const block = { kind: 'paragraph', runs: [...] };
+ * const line = { fromRun: 0, toRun: 1, ... };
+ *
+ * // Character 3 maps to PM position 3 (within "Hello")
+ * charOffsetToPm(block, line, 3, 0); // returns 3
+ *
+ * // Character 7 maps to PM position 9 (within "World", accounting for gap)
+ * charOffsetToPm(block, line, 7, 0); // returns 9
+ * ```
+ */
+export declare function charOffsetToPm(block: FlowBlock, line: Line, charOffset: number, fallbackPmStart: number): number;
+export declare function findCharacterAtX(block: FlowBlock, line: Line, x: number, pmStart: number, availableWidthOverride?: number, alignmentOverride?: string, fontContext?: FontMeasureContext): {
+    charOffset: number;
+    pmPosition: number;
+};