superdoc 2.2.0 → 2.3.0

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

@@ -0,0 +1,245 @@
+import { MeasureCacheStats } from './cache.js';
+/**
+ * Performance metrics for page token resolution.
+ * Tracks timing and iteration counts for monitoring rollout health.
+ */
+export interface PageTokenMetrics {
+    /** Total time spent in token resolution (milliseconds) */
+    totalTimeMs: number;
+    /** Number of convergence iterations (0 = no tokens, 1+ = resolution occurred) */
+    iterations: number;
+    /** Number of blocks affected by token resolution */
+    affectedBlocks: number;
+    /** Time spent re-measuring blocks (milliseconds) */
+    remeasureTimeMs: number;
+    /** Time spent re-running layout (milliseconds) */
+    relayoutTimeMs: number;
+    /** Whether convergence was achieved within max iterations */
+    converged: boolean;
+}
+/**
+ * Header/footer cache metrics.
+ * Tracks cache performance for optimization and capacity planning.
+ */
+export interface HeaderFooterCacheMetrics {
+    /** Cache hit count for this operation */
+    hits: number;
+    /** Cache miss count for this operation */
+    misses: number;
+    /** Hit rate percentage (0-100) */
+    hitRate: number;
+    /** Current cache size (number of entries) */
+    cacheSize: number;
+    /** Estimated memory usage (bytes) */
+    memoryEstimate: number;
+    /** Number of evictions due to LRU policy */
+    evictions: number;
+}
+/**
+ * Layout performance metrics.
+ * High-level timing for the entire layout operation.
+ */
+export interface LayoutMetrics {
+    /** Total layout time including all phases (milliseconds) */
+    totalTimeMs: number;
+    /** Measurement phase time (milliseconds) */
+    measureTimeMs: number;
+    /** Initial pagination time (milliseconds) */
+    paginationTimeMs: number;
+    /** Token resolution phase time (milliseconds) */
+    tokenResolutionTimeMs: number;
+    /** Header/footer layout time (milliseconds) */
+    headerFooterTimeMs: number;
+}
+/**
+ * Debug logger for page token resolution.
+ * Only logs when SD_DEBUG_PAGE_TOKENS is enabled.
+ */
+export declare const PageTokenLogger: {
+    /**
+     * Logs the start of token resolution.
+     *
+     * @param iteration - Current iteration number (0-based)
+     * @param totalPages - Total number of pages in the document
+     */
+    logIterationStart(iteration: number, totalPages: number): void;
+    /**
+     * Logs affected blocks during token resolution.
+     *
+     * @param iteration - Current iteration number (0-based)
+     * @param affectedBlockIds - Set of affected block IDs
+     * @param blockSamples - Sample block IDs for debugging (first 5)
+     */
+    logAffectedBlocks(iteration: number, affectedBlockIds: Set<string>, blockSamples?: string[]): void;
+    /**
+     * Logs convergence status.
+     *
+     * @param iteration - Final iteration number
+     * @param converged - Whether convergence was achieved
+     * @param totalTimeMs - Total time spent in token resolution
+     */
+    logConvergence(iteration: number, converged: boolean, totalTimeMs: number): void;
+    /**
+     * Logs token resolution error.
+     *
+     * @param blockId - Block ID where error occurred
+     * @param error - Error object
+     */
+    logError(blockId: string, error: unknown): void;
+    /**
+     * Logs re-measurement details.
+     *
+     * @param blockCount - Number of blocks being re-measured
+     * @param timeMs - Time spent re-measuring
+     */
+    logRemeasure(blockCount: number, timeMs: number): void;
+};
+/**
+ * Debug logger for header/footer cache operations.
+ * Only logs when SD_DEBUG_HF_CACHE is enabled.
+ */
+export declare const HeaderFooterCacheLogger: {
+    /**
+     * Logs cache hit for a header/footer variant.
+     *
+     * @param variantType - Variant type (default, first, even, odd)
+     * @param pageNumber - Page number being cached
+     * @param bucket - Digit bucket (d1, d2, d3, d4) or 'exact'
+     */
+    logCacheHit(variantType: string, pageNumber: number, bucket: string): void;
+    /**
+     * Logs cache miss for a header/footer variant.
+     *
+     * @param variantType - Variant type (default, first, even, odd)
+     * @param pageNumber - Page number being cached
+     * @param bucket - Digit bucket (d1, d2, d3, d4) or 'exact'
+     */
+    logCacheMiss(variantType: string, pageNumber: number, bucket: string): void;
+    /**
+     * Logs cache invalidation.
+     *
+     * @param reason - Reason for invalidation
+     * @param affectedBlockIds - Block IDs being invalidated
+     */
+    logInvalidation(reason: string, affectedBlockIds: string[]): void;
+    /**
+     * Logs cache statistics.
+     *
+     * @param stats - Cache statistics object
+     */
+    logStats(stats: MeasureCacheStats): void;
+    /**
+     * Logs bucketing decision for large documents.
+     *
+     * @param totalPages - Total number of pages
+     * @param useBucketing - Whether bucketing is being used
+     * @param buckets - Buckets needed (if bucketing enabled)
+     */
+    logBucketingDecision(totalPages: number, useBucketing: boolean, buckets?: string[]): void;
+};
+/**
+ * Metrics collector for performance monitoring.
+ * Collects metrics even when debug logging is disabled, for production monitoring.
+ */
+export declare class MetricsCollector {
+    private pageTokenMetrics;
+    private headerFooterCacheMetrics;
+    private layoutMetrics;
+    /**
+     * Records page token resolution metrics.
+     *
+     * @param metrics - Page token metrics
+     */
+    recordPageTokenMetrics(metrics: PageTokenMetrics): void;
+    /**
+     * Records header/footer cache metrics.
+     *
+     * @param stats - Cache statistics
+     */
+    recordHeaderFooterCacheMetrics(stats: MeasureCacheStats): void;
+    /**
+     * Records overall layout metrics.
+     *
+     * @param metrics - Layout metrics
+     */
+    recordLayoutMetrics(metrics: LayoutMetrics): void;
+    /**
+     * Gets all collected metrics.
+     *
+     * @returns Object with all metrics or null if not collected
+     */
+    getMetrics(): {
+        pageTokens: PageTokenMetrics | null;
+        headerFooterCache: HeaderFooterCacheMetrics | null;
+        layout: LayoutMetrics | null;
+    };
+    /**
+     * Resets all collected metrics.
+     */
+    reset(): void;
+    /**
+     * Checks for page token rollback triggers and logs warnings.
+     *
+     * Rollback triggers (from plan):
+     * - Convergence > 2 iterations
+     * - Token resolution time > 100ms per layout run
+     *
+     * @param metrics - Page token metrics
+     */
+    private checkPageTokenRollbackTriggers;
+    /**
+     * Checks for cache rollback triggers and logs warnings.
+     *
+     * Rollback triggers (from plan):
+     * - Cache thrash (hit rate below 30%)
+     * - Excessive memory usage (>1MB per 100 pages)
+     *
+     * @param metrics - Header/footer cache metrics
+     */
+    private checkCacheRollbackTriggers;
+}
+/**
+ * Global metrics collector instance.
+ * Can be accessed for monitoring and debugging.
+ */
+export declare const globalMetrics: MetricsCollector;
+/**
+ * Logger for layout version events.
+ * Guards all logging behind SD_DEBUG_LAYOUT_VERSION flag for zero overhead in production.
+ */
+export declare const LayoutVersionLogger: {
+    /**
+     * Log when selection overlay attempts to use stale layout.
+     *
+     * @param versionGap - Number of PM versions ahead of layout
+     * @param stalenessDuration - How long layout has been stale (ms)
+     */
+    logStaleLayoutRead(versionGap: number, stalenessDuration: number): void;
+    /**
+     * Log when geometry fallback is used due to missing pmStart/pmEnd.
+     *
+     * @param reason - Why fallback was needed
+     * @param pos - PM position that failed
+     */
+    logGeometryFallback(reason: string, pos: number): void;
+    /**
+     * Log when layout catches up to current PM state.
+     *
+     * @param versionGap - How many versions layout was behind
+     * @param stalenessDuration - Total duration layout was stale (ms)
+     */
+    logLayoutCaughtUp(versionGap: number, stalenessDuration: number): void;
+    /**
+     * Log PM transaction that increments version.
+     *
+     * @param newVersion - New PM version after transaction
+     */
+    logPmTransaction(newVersion: number): void;
+    /**
+     * Log layout completion.
+     *
+     * @param version - Version of the completed layout
+     * @param isStale - Whether layout is still stale after this completion
+     */
+    logLayoutComplete(version: number, isStale: boolean): void;
+};

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

@@ -0,0 +1,123 @@
+import { FlowBlock, HeaderFooterLayout, Measure, PageNumberChapterSeparator, PageNumberFormat, ParagraphBlock, ParagraphMeasure } from '../../contracts/src/index.js';
+import { HeaderFooterConstraints } from '../../layout-engine/src/index.js';
+import { MeasureCache } from './cache.js';
+import { ResolveHeaderFooterTokensOptions } from './resolveHeaderFooterTokens.js';
+export type HeaderFooterBatch = Partial<Record<'default' | 'first' | 'even' | 'odd', FlowBlock[]>>;
+export type MeasureResolver = (block: FlowBlock, constraints: {
+    maxWidth: number;
+    maxHeight: number;
+}) => Promise<Measure>;
+export type HeaderFooterBatchResult = Partial<Record<'default' | 'first' | 'even' | 'odd', {
+    blocks: FlowBlock[];
+    measures: Measure[];
+    layout: HeaderFooterLayout;
+}>>;
+/**
+ * Page resolver callback for header/footer token resolution.
+ * Provides display page information for a specific physical page number.
+ *
+ * @param pageNumber - Physical page number (1-indexed)
+ * @returns Display page information including formatted text and total pages
+ */
+export type PageResolver = (pageNumber: number) => {
+    displayText: string;
+    displayNumber?: number;
+    totalPages: number;
+    sectionPageCount?: number;
+    pageFormat?: PageNumberFormat;
+    chapterNumberText?: string;
+    chapterSeparator?: PageNumberChapterSeparator;
+};
+/**
+ * Digit bucket for page number caching strategy.
+ * Different digit lengths require different measurements due to width changes.
+ */
+export type DigitBucket = 'd1' | 'd2' | 'd3' | 'd4';
+/**
+ * Determines the digit bucket for a given page number.
+ *
+ * Bucket strategy:
+ * - d1: 1-9 (single digit)
+ * - d2: 10-99 (two digits)
+ * - d3: 100-999 (three digits)
+ * - d4: 1000+ (four or more digits)
+ *
+ * This bucketing allows us to cache header/footer layouts by digit width,
+ * reducing the number of unique layouts we need to measure and store.
+ *
+ * @param pageNumber - Page number to bucket (1-indexed)
+ * @returns Digit bucket identifier
+ *
+ * @example
+ * ```typescript
+ * getBucketForPageNumber(5);    // 'd1'
+ * getBucketForPageNumber(42);   // 'd2'
+ * getBucketForPageNumber(123);  // 'd3'
+ * getBucketForPageNumber(1000); // 'd4'
+ * ```
+ */
+export declare function getBucketForPageNumber(pageNumber: number): DigitBucket;
+/**
+ * Gets a representative page number for a digit bucket.
+ *
+ * The representative page is used for measurement and layout.
+ * We choose mid-range values to get realistic measurements:
+ * - d1: 5 (middle of 1-9)
+ * - d2: 50 (middle of 10-99)
+ * - d3: 500 (middle of 100-999)
+ * - d4: 5000 (representative of 1000+)
+ *
+ * @param bucket - Digit bucket identifier
+ * @returns Representative page number for the bucket
+ *
+ * @example
+ * ```typescript
+ * getBucketRepresentative('d1'); // 5
+ * getBucketRepresentative('d2'); // 50
+ * getBucketRepresentative('d3'); // 500
+ * ```
+ */
+export declare function getBucketRepresentative(bucket: DigitBucket): number;
+export declare class HeaderFooterLayoutCache {
+    private readonly cache;
+    /** Drop every cached header/footer measure (equivalence-oracle cold start). */
+    clear(): void;
+    measureBlocks(blocks: FlowBlock[], constraints: {
+        width: number;
+        height: number;
+    }, measureBlock: MeasureResolver, fontSignature?: string): Promise<Measure[]>;
+    invalidate(blockIds: string[]): void;
+    /**
+     * Gets cache statistics for monitoring and debugging.
+     *
+     * @returns Cache statistics object
+     */
+    getStats(): ReturnType<MeasureCache<Measure>['getStats']>;
+}
+/** Invalidate header/footer measure cache entries for the given block IDs. */
+export declare function invalidateHeaderFooterMeasureCache(blockIds: string[]): void;
+/**
+ * Layouts header/footer variants with intelligent caching and page number resolution.
+ *
+ * Features:
+ * - Resolves page tokens using section-aware display page numbers
+ * - Uses digit bucketing to optimize caching for large documents
+ * - Clones blocks per page/bucket to avoid mutating shared source data
+ * - Produces HeaderFooterLayout with per-page fragments
+ *
+ * Key behaviors:
+ * 1. If no pageResolver provided: falls back to simple single-page layout (backward compatibility)
+ * 2. If variant has no tokens: creates one layout reused across all pages (fast path)
+ * 3. For small docs (<100 pages): creates per-page layouts
+ * 4. For large docs (>=100 pages): uses digit bucketing (d1, d2, d3, d4)
+ *    unless PAGE tokens use non-decimal field formatting
+ *
+ * @param sections - Header/footer variants (default, first, even, odd)
+ * @param constraints - Layout constraints (width, height, margins)
+ * @param measureBlock - Function to measure individual blocks
+ * @param cache - Measurement cache instance (optional, uses shared cache by default)
+ * @param totalPages - Total page count for backward compatibility (deprecated, use pageResolver)
+ * @param pageResolver - Callback to resolve display page info for a physical page number
+ * @returns Batch result with layouts, blocks, and measures for each variant
+ */
+export declare function layoutHeaderFooterWithCache(sections: HeaderFooterBatch, constraints: HeaderFooterConstraints, measureBlock: MeasureResolver, cache?: HeaderFooterLayoutCache, totalPages?: number, pageResolver?: PageResolver, kind?: 'header' | 'footer', fontSignature?: string, remeasureParagraph?: (block: ParagraphBlock, maxWidth: number, firstLineIndent?: number) => ParagraphMeasure, options?: ResolveHeaderFooterTokensOptions): Promise<HeaderFooterBatchResult>;

package/dist/layout-engine/layout-bridge/src/list-indent-utils.d.ts

@@ -0,0 +1,205 @@
+import { ParagraphBlock, ParagraphIndent, WordLayoutConfig } from '../../contracts/src/index.js';
+/**
+ * Utilities for list item detection and text indent calculation.
+ *
+ * These functions provide consistent logic for determining whether a block is a list item
+ * and calculating the correct text start position based on list type (standard hanging indent
+ * vs. firstLineIndentMode).
+ *
+ * **Background:**
+ * SuperDoc supports two distinct list rendering modes:
+ * 1. **Standard hanging indent lists**: Marker sits in the hanging indent area, text starts at paraIndentLeft
+ * 2. **First-line indent mode lists**: Marker is positioned at paraIndentLeft + firstLine, text starts at textStartPx
+ *
+ * The first-line indent mode is used by input-rule-created lists (e.g., typing "1. " or "- ") and requires
+ * special handling to match Word's rendering behavior.
+ */
+/**
+ * Extracts word layout configuration from paragraph attributes with type safety.
+ *
+ * @param block - The paragraph block to extract configuration from
+ * @returns Typed word layout configuration, or undefined if not present
+ *
+ * @example
+ * ```typescript
+ * const config = getWordLayoutConfig(paragraphBlock);
+ * if (config?.firstLineIndentMode) {
+ *   const textStart = config.textStartPx ?? 0;
+ * }
+ * ```
+ */
+export declare function getWordLayoutConfig(block: ParagraphBlock | undefined): WordLayoutConfig | undefined;
+/**
+ * Determines if a block is a list item based on multiple detection signals.
+ *
+ * This function uses explicit list signals:
+ * 1. **Marker width**: Primary signal - lists always have markers
+ * 2. **List attributes**: Explicit list metadata from ProseMirror
+ *
+ * Paragraph indentation alone is not a list signal: ordinary Word paragraphs
+ * can use the same left + hanging-indent geometry without a marker.
+ *
+ * @param markerWidth - The measured width of the list marker in pixels (0 for non-lists)
+ * @param block - The paragraph block to check (may be undefined for defensive coding)
+ * @returns True if the block is a list item, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const markerWidth = fragment.markerWidth ?? measure.marker?.markerWidth ?? 0;
+ * if (isListItem(markerWidth, block)) {
+ *   // Apply list-specific text positioning
+ * }
+ * ```
+ */
+export declare function isListItem(markerWidth: number, block: ParagraphBlock | undefined): boolean;
+/**
+ * Configuration for calculating text start indent.
+ *
+ * This type defines all the parameters needed to calculate where text content
+ * starts horizontally within a paragraph fragment. It supports both standard
+ * paragraphs and list items (with standard hanging indent or first-line indent mode).
+ *
+ * All measurements are in pixels.
+ *
+ * @example
+ * ```typescript
+ * // Standard list item (hanging indent mode)
+ * const standardListParams: TextIndentCalculationParams = {
+ *   isFirstLine: true,
+ *   isListItem: true,
+ *   markerWidth: 18,
+ *   paraIndentLeft: 36,
+ *   firstLineIndent: 0,
+ *   hangingIndent: 18,
+ *   wordLayout: undefined
+ * };
+ * const indent = calculateTextStartIndent(standardListParams);
+ * // Returns: 36 (text starts at paraIndentLeft)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // First-line indent mode list item (input-rule created)
+ * const firstLineIndentParams: TextIndentCalculationParams = {
+ *   isFirstLine: true,
+ *   isListItem: true,
+ *   markerWidth: 20,
+ *   paraIndentLeft: 36,
+ *   firstLineIndent: 0,
+ *   hangingIndent: 18,
+ *   wordLayout: {
+ *     firstLineIndentMode: true,
+ *     textStartPx: 56  // Pre-calculated position after marker + tab
+ *   }
+ * };
+ * const indent = calculateTextStartIndent(firstLineIndentParams);
+ * // Returns: 56 (from textStartPx)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Non-list paragraph with first-line indent
+ * const paragraphParams: TextIndentCalculationParams = {
+ *   isFirstLine: true,
+ *   isListItem: false,
+ *   markerWidth: 0,
+ *   paraIndentLeft: 36,
+ *   firstLineIndent: 18,
+ *   hangingIndent: 0,
+ *   wordLayout: undefined
+ * };
+ * const indent = calculateTextStartIndent(paragraphParams);
+ * // Returns: 54 (paraIndentLeft + firstLineIndent)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Second line of a list item (no first-line indent applied)
+ * const secondLineParams: TextIndentCalculationParams = {
+ *   isFirstLine: false,
+ *   isListItem: true,
+ *   markerWidth: 20,
+ *   paraIndentLeft: 36,
+ *   firstLineIndent: 0,
+ *   hangingIndent: 18,
+ *   wordLayout: { firstLineIndentMode: true, textStartPx: 56 }
+ * };
+ * const indent = calculateTextStartIndent(secondLineParams);
+ * // Returns: 36 (paraIndentLeft only, no special handling on non-first lines)
+ * ```
+ */
+export type TextIndentCalculationParams = {
+    /** Whether this is the first line of the paragraph fragment */
+    isFirstLine: boolean;
+    /** Whether the block is a list item (from isListItem) */
+    isListItem: boolean;
+    /** Measured marker width in pixels */
+    markerWidth: number;
+    /** Measured marker text width in pixels (optional, falls back to markerWidth) */
+    markerTextWidth?: number;
+    /** Left paragraph indent in pixels */
+    paraIndentLeft: number;
+    /** First-line indent in pixels (positive pushes first line right, negative pulls it left) */
+    firstLineIndent: number;
+    /** Hanging indent in pixels (creates space for markers) */
+    hangingIndent: number;
+    /** Word layout configuration (if present) */
+    wordLayout?: WordLayoutConfig;
+};
+/**
+ * Calculates the horizontal text indent adjustment for a line.
+ *
+ * This function implements the complex logic for determining where text content
+ * starts on a line, accounting for:
+ * - List markers (standard hanging indent vs. first-line indent mode)
+ * - Paragraph indents (left, first-line, hanging)
+ * - Non-list paragraphs with first-line indents
+ *
+ * **Algorithm:**
+ * 1. For list items on the first line:
+ *    - Use shared `resolveListTextStartPx` as the canonical source
+ *    - Fall back to explicit producer-provided `textStart` values only
+ * 2. For non-list paragraphs on the first line:
+ *    - Add first-line offset (firstLineIndent - hangingIndent)
+ * 3. For all other lines:
+ *    - Use paraIndentLeft only
+ *
+ * @param params - Text indent calculation parameters
+ * @returns Horizontal indent adjustment in pixels from fragment.x
+ *
+ * @example
+ * ```typescript
+ * const indent = calculateTextStartIndent({
+ *   isFirstLine: true,
+ *   isListItem: true,
+ *   markerWidth: 20,
+ *   paraIndentLeft: 36,
+ *   firstLineIndent: 0,
+ *   hangingIndent: 18,
+ *   wordLayout: { firstLineIndentMode: true, textStartPx: 56 }
+ * });
+ * // Returns: 56 (from textStartPx)
+ * ```
+ */
+export declare function calculateTextStartIndent(params: TextIndentCalculationParams): number;
+/**
+ * Safely extracts paragraph indent values with type validation.
+ *
+ * This helper function ensures all indent values are valid numbers, preventing
+ * runtime errors from malformed or missing data.
+ *
+ * @param indent - Paragraph indent object (may be undefined)
+ * @returns Object with validated numeric indent values (defaults to 0)
+ *
+ * @example
+ * ```typescript
+ * const { left, firstLine, hanging } = extractParagraphIndent(block.attrs?.indent);
+ * const textStart = left + firstLine - hanging;
+ * ```
+ */
+export declare function extractParagraphIndent(indent: ParagraphIndent | undefined): {
+    left: number;
+    right: number;
+    firstLine: number;
+    hanging: number;
+};

package/dist/layout-engine/layout-bridge/src/local-paragraph-layout.d.ts

@@ -0,0 +1,93 @@
+import { FontMetricsCache } from './font-metrics-cache.js';
+import { LineInfo } from './paragraph-line-cache.js';
+/**
+ * Result of local paragraph layout calculation.
+ */
+export interface LocalLayoutResult {
+    /** Array of lines with local offsets */
+    lines: LineInfo[];
+    /** Total height of all lines in pixels */
+    totalHeight: number;
+    /** Maximum line width in pixels */
+    width: number;
+}
+/**
+ * A text run with formatting information.
+ */
+export interface TextRun {
+    /** Text content of the run */
+    text: string;
+    /** Font key for this run */
+    fontKey: string;
+}
+/**
+ * LocalParagraphLayout calculates line breaks for paragraphs using
+ * cached font metrics in a synchronous, fast manner.
+ *
+ * This is the P0 layout path used when:
+ * - Full layout is stale
+ * - Need immediate cursor positioning
+ * - Progressive enhancement before full layout completes
+ *
+ * Performance target: <5ms for typical paragraphs
+ *
+ * Usage:
+ * ```typescript
+ * const layoutEngine = new LocalParagraphLayout(fontMetricsCache);
+ *
+ * // Single-format paragraph
+ * const result = layoutEngine.layout(text, fontKey, maxWidth);
+ *
+ * // Multi-format paragraph
+ * const runs = [
+ *   { text: 'Bold', fontKey: 'Arial|16|bold|normal' },
+ *   { text: ' normal', fontKey: 'Arial|16|normal|normal' }
+ * ];
+ * const result = layoutEngine.layoutRuns(runs, maxWidth);
+ * ```
+ */
+export declare class LocalParagraphLayout {
+    private fontMetricsCache;
+    /**
+     * Creates a new LocalParagraphLayout instance.
+     *
+     * @param fontMetricsCache - Font metrics cache for character width lookup
+     */
+    constructor(fontMetricsCache: FontMetricsCache);
+    /**
+     * Calculate line breaks for a paragraph using cached font metrics.
+     * This is the P0 (sync, <5ms) layout path.
+     *
+     * Uses greedy line breaking: add words until line width exceeds maxWidth,
+     * then break to next line.
+     *
+     * @param text - Paragraph text content
+     * @param fontKey - Font key for the entire paragraph
+     * @param maxWidth - Maximum line width in pixels
+     * @returns Layout result with line information
+     */
+    layout(text: string, fontKey: string, maxWidth: number): LocalLayoutResult;
+    /**
+     * Layout a paragraph with mixed formatting (multiple text runs).
+     *
+     * Each run can have different font properties. Line breaks are calculated
+     * considering the varying character widths across runs.
+     *
+     * @param runs - Array of text runs with formatting
+     * @param maxWidth - Maximum line width in pixels
+     * @returns Layout result with line information
+     */
+    layoutRuns(runs: TextRun[], maxWidth: number): LocalLayoutResult;
+    /**
+     * Estimate paragraph height without full layout.
+     *
+     * Uses average character width and line height to quickly estimate
+     * how tall a paragraph will be. Useful for scroll calculations.
+     *
+     * @param textLength - Number of characters in paragraph
+     * @param fontKey - Font key for the paragraph
+     * @param maxWidth - Maximum line width in pixels
+     * @returns Estimated height in pixels
+     */
+    estimateHeight(textLength: number, fontKey: string, maxWidth: number): number;
+}