@rtif-sdk/web 1.1.0 → 1.4.0

package/dist/spatial-index.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Spatial index for viewport virtualization.
+ *
+ * A prefix-sum array of block pixel heights, mirroring
+ * {@link ResolveIndex} from `@rtif-sdk/core` but for layout instead of
+ * character offsets. Provides O(1) `blockTop` / `totalHeight` and
+ * O(log n) `computeVisibleRange` for efficiently determining which
+ * blocks are visible within a scrollable viewport.
+ *
+ * @packageDocumentation
+ */
+import type { Document } from '@rtif-sdk/core';
+/**
+ * Default estimated pixel heights per block type.
+ *
+ * Used when no measured height is available for a block.
+ * Override via {@link SpatialIndexConfig.blockTypeHeights}.
+ *
+ * @example
+ * ```ts
+ * // Use defaults with a custom "callout" override
+ * createSpatialIndex(doc, {
+ *   blockTypeHeights: { ...DEFAULT_BLOCK_TYPE_HEIGHTS, callout: 64 },
+ * });
+ * ```
+ */
+export declare const DEFAULT_BLOCK_TYPE_HEIGHTS: Record<string, number>;
+/**
+ * Configuration for creating a {@link SpatialIndex}.
+ *
+ * @example
+ * ```ts
+ * const config: SpatialIndexConfig = {
+ *   estimatedBlockHeight: 32,
+ *   blockTypeHeights: { heading: 48, image: 250 },
+ * };
+ * ```
+ */
+export interface SpatialIndexConfig {
+    /**
+     * Default estimated pixel height for block types not listed in
+     * {@link blockTypeHeights} or {@link DEFAULT_BLOCK_TYPE_HEIGHTS}.
+     *
+     * Default: `24`.
+     */
+    readonly estimatedBlockHeight?: number;
+    /**
+     * Estimated pixel heights per block type string.
+     *
+     * Merged on top of {@link DEFAULT_BLOCK_TYPE_HEIGHTS} so you only
+     * need to specify overrides. Pass an empty object to use only the
+     * built-in defaults.
+     *
+     * @example
+     * ```ts
+     * { heading: 48, 'list-item': 28 }
+     * ```
+     */
+    readonly blockTypeHeights?: Record<string, number>;
+}
+/**
+ * A prefix-sum spatial index for O(1) block-top queries and O(log n)
+ * visible-range computation.
+ *
+ * Create with {@link createSpatialIndex}. The index is mutable --
+ * call {@link setBlockHeight} or {@link setBlockHeights} as measured
+ * heights become available, and {@link rebuild} when the document
+ * structure changes (blocks added/removed/reordered).
+ *
+ * @example
+ * ```ts
+ * const spatial = createSpatialIndex(doc);
+ * const range = spatial.computeVisibleRange(scrollTop, viewportHeight, 2);
+ * for (let i = range.start; i < range.end; i++) {
+ *   renderBlock(doc.blocks[i]);
+ * }
+ * ```
+ */
+export interface SpatialIndex {
+    /**
+     * Total height of all blocks in pixels.
+     *
+     * @returns Sum of all block heights (O(1))
+     */
+    totalHeight(): number;
+    /**
+     * Number of blocks in the index.
+     *
+     * @returns Block count (O(1))
+     */
+    blockCount(): number;
+    /**
+     * Pixel height of the block at the given index.
+     *
+     * @param index - 0-based block index
+     * @returns The block's height in pixels
+     * @throws {RangeError} If index is out of bounds
+     */
+    blockHeight(index: number): number;
+    /**
+     * The y-coordinate (top edge) of the block at the given index,
+     * measured from the top of the document.
+     *
+     * @param index - 0-based block index
+     * @returns Pixel offset from document top (O(1))
+     * @throws {RangeError} If index is out of bounds
+     */
+    blockTop(index: number): number;
+    /**
+     * Compute the range of block indices visible within a scrollable
+     * viewport, plus a configurable buffer of extra blocks on each side.
+     *
+     * Uses binary search on the prefix-sum array for O(log n) performance.
+     *
+     * @param scrollTop - The viewport's scroll offset from the top of the
+     *   document in pixels. Clamped to `[0, totalHeight]`.
+     * @param viewportHeight - The viewport height in pixels. Must be >= 0.
+     * @param buffer - Number of extra blocks to include before and after
+     *   the visible range (for smooth scrolling). Clamped to valid range.
+     * @returns An object with `start` (inclusive) and `end` (exclusive)
+     *   block indices. When there are no blocks, returns `{ start: 0, end: 0 }`.
+     *
+     * @example
+     * ```ts
+     * const { start, end } = spatial.computeVisibleRange(200, 600, 3);
+     * // Render blocks [start, end)
+     * ```
+     */
+    computeVisibleRange(scrollTop: number, viewportHeight: number, buffer: number): {
+        readonly start: number;
+        readonly end: number;
+    };
+    /**
+     * Update the measured pixel height of a single block and rebuild
+     * prefix sums from that index onward.
+     *
+     * @param index - 0-based block index
+     * @param height - New measured height in pixels
+     * @throws {RangeError} If index is out of bounds
+     */
+    setBlockHeight(index: number, height: number): void;
+    /**
+     * Batch-update measured pixel heights for multiple blocks and rebuild
+     * prefix sums once.
+     *
+     * More efficient than calling {@link setBlockHeight} in a loop because
+     * prefix sums are only rebuilt once, starting from the lowest changed index.
+     *
+     * @param updates - Array of `{ index, height }` pairs
+     * @throws {RangeError} If any index is out of bounds
+     */
+    setBlockHeights(updates: ReadonlyArray<{
+        readonly index: number;
+        readonly height: number;
+    }>): void;
+    /**
+     * Rebuild the index from a (potentially new) document.
+     *
+     * Creates a fresh prefix-sum array sized to the document's block count.
+     * If `preserveHeights` is provided (keyed by block ID), those measured
+     * heights are used; otherwise the estimate for the block's type is used.
+     *
+     * @param doc - The RTIF document to index
+     * @param preserveHeights - Optional map of block ID to measured pixel
+     *   height. Blocks whose IDs appear in this map use the measured value
+     *   instead of the type-based estimate.
+     */
+    rebuild(doc: Document, preserveHeights?: Map<string, number>): void;
+}
+/**
+ * Create a spatial index for viewport virtualization.
+ *
+ * Builds a prefix-sum array of estimated block heights in O(n). Subsequent
+ * `blockTop()` calls are O(1) and `computeVisibleRange()` calls are O(log n).
+ *
+ * As blocks are rendered and measured, call {@link SpatialIndex.setBlockHeight}
+ * or {@link SpatialIndex.setBlockHeights} to replace estimates with actual
+ * measured values. When the document structure changes (blocks added, removed,
+ * or reordered), call {@link SpatialIndex.rebuild}.
+ *
+ * @param doc - The RTIF document to index
+ * @param config - Optional configuration for height estimates
+ * @returns A new {@link SpatialIndex} instance
+ *
+ * @example
+ * ```ts
+ * import { createSpatialIndex } from '@rtif-sdk/web';
+ *
+ * const spatial = createSpatialIndex(doc);
+ * console.log(spatial.totalHeight());         // e.g. 2400
+ * console.log(spatial.blockTop(5));           // e.g. 120
+ *
+ * const { start, end } = spatial.computeVisibleRange(100, 600, 2);
+ * for (let i = start; i < end; i++) {
+ *   renderBlock(doc.blocks[i]);
+ * }
+ *
+ * // After measuring a block's actual height:
+ * spatial.setBlockHeight(5, 36);
+ * ```
+ */
+export declare function createSpatialIndex(doc: Document, config?: SpatialIndexConfig): SpatialIndex;
+//# sourceMappingURL=spatial-index.d.ts.map

package/dist/spatial-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-index.d.ts","sourceRoot":"","sources":["../src/spatial-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAM/C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAQ7D,CAAC;AAMF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAEvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,WAAW,IAAI,MAAM,CAAC;IAEtB;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAAC;IAErB;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAEnC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAEhC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAEpD;;;;;;;OAOG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpD;;;;;;;;;OASG;IACH,eAAe,CACb,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAC1E,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CACrE;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,QAAQ,EACb,MAAM,CAAC,EAAE,kBAAkB,GAC1B,YAAY,CAgJd"}

package/dist/spatial-index.js

@@ -0,0 +1,211 @@
+/**
+ * Spatial index for viewport virtualization.
+ *
+ * A prefix-sum array of block pixel heights, mirroring
+ * {@link ResolveIndex} from `@rtif-sdk/core` but for layout instead of
+ * character offsets. Provides O(1) `blockTop` / `totalHeight` and
+ * O(log n) `computeVisibleRange` for efficiently determining which
+ * blocks are visible within a scrollable viewport.
+ *
+ * @packageDocumentation
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Default estimated pixel heights per block type.
+ *
+ * Used when no measured height is available for a block.
+ * Override via {@link SpatialIndexConfig.blockTypeHeights}.
+ *
+ * @example
+ * ```ts
+ * // Use defaults with a custom "callout" override
+ * createSpatialIndex(doc, {
+ *   blockTypeHeights: { ...DEFAULT_BLOCK_TYPE_HEIGHTS, callout: 64 },
+ * });
+ * ```
+ */
+export const DEFAULT_BLOCK_TYPE_HEIGHTS = {
+    text: 24,
+    heading: 40,
+    code_block: 48,
+    blockquote: 32,
+    hr: 16,
+    image: 200,
+    embed: 300,
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Estimate the pixel height of a block based on its type.
+ */
+function estimateHeight(blockType, mergedHeights, fallback) {
+    const h = mergedHeights[blockType];
+    return h !== undefined ? h : fallback;
+}
+/**
+ * Rebuild prefix sums starting from `fromIndex`. Mutates `prefixSums` in place.
+ */
+function rebuildPrefixSums(heights, prefixSums, fromIndex) {
+    const n = heights.length;
+    for (let i = fromIndex; i < n; i++) {
+        prefixSums[i] = i === 0 ? 0 : prefixSums[i - 1] + heights[i - 1];
+    }
+}
+/**
+ * Validate that `index` is in `[0, count)`.
+ */
+function assertValidIndex(index, count) {
+    if (index < 0 || index >= count) {
+        throw new RangeError(`Block index ${index} out of range [0, ${count})`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a spatial index for viewport virtualization.
+ *
+ * Builds a prefix-sum array of estimated block heights in O(n). Subsequent
+ * `blockTop()` calls are O(1) and `computeVisibleRange()` calls are O(log n).
+ *
+ * As blocks are rendered and measured, call {@link SpatialIndex.setBlockHeight}
+ * or {@link SpatialIndex.setBlockHeights} to replace estimates with actual
+ * measured values. When the document structure changes (blocks added, removed,
+ * or reordered), call {@link SpatialIndex.rebuild}.
+ *
+ * @param doc - The RTIF document to index
+ * @param config - Optional configuration for height estimates
+ * @returns A new {@link SpatialIndex} instance
+ *
+ * @example
+ * ```ts
+ * import { createSpatialIndex } from '@rtif-sdk/web';
+ *
+ * const spatial = createSpatialIndex(doc);
+ * console.log(spatial.totalHeight());         // e.g. 2400
+ * console.log(spatial.blockTop(5));           // e.g. 120
+ *
+ * const { start, end } = spatial.computeVisibleRange(100, 600, 2);
+ * for (let i = start; i < end; i++) {
+ *   renderBlock(doc.blocks[i]);
+ * }
+ *
+ * // After measuring a block's actual height:
+ * spatial.setBlockHeight(5, 36);
+ * ```
+ */
+export function createSpatialIndex(doc, config) {
+    const fallbackHeight = config?.estimatedBlockHeight ?? 24;
+    const mergedHeights = {
+        ...DEFAULT_BLOCK_TYPE_HEIGHTS,
+        ...config?.blockTypeHeights,
+    };
+    // Mutable arrays — rebuilt on structural changes, updated on height changes
+    let heights = [];
+    let prefixSums = [];
+    let count = 0;
+    /**
+     * Build the arrays from a document, optionally preserving measured heights.
+     */
+    function buildFromDoc(d, preserveHeights) {
+        const n = d.blocks.length;
+        heights = new Array(n);
+        prefixSums = new Array(n);
+        count = n;
+        for (let i = 0; i < n; i++) {
+            const block = d.blocks[i];
+            const preserved = preserveHeights?.get(block.id);
+            heights[i] =
+                preserved !== undefined
+                    ? preserved
+                    : estimateHeight(block.type, mergedHeights, fallbackHeight);
+        }
+        rebuildPrefixSums(heights, prefixSums, 0);
+    }
+    // Initial build
+    buildFromDoc(doc);
+    const index = {
+        totalHeight() {
+            if (count === 0)
+                return 0;
+            return prefixSums[count - 1] + heights[count - 1];
+        },
+        blockCount() {
+            return count;
+        },
+        blockHeight(blockIndex) {
+            assertValidIndex(blockIndex, count);
+            return heights[blockIndex];
+        },
+        blockTop(blockIndex) {
+            assertValidIndex(blockIndex, count);
+            return prefixSums[blockIndex];
+        },
+        computeVisibleRange(scrollTop, viewportHeight, buffer) {
+            if (count === 0) {
+                return { start: 0, end: 0 };
+            }
+            // Clamp scrollTop to valid range
+            const total = index.totalHeight();
+            const clampedScrollTop = Math.max(0, Math.min(scrollTop, total));
+            const clampedViewportHeight = Math.max(0, viewportHeight);
+            const clampedBuffer = Math.max(0, Math.floor(buffer));
+            // Binary search for first block whose bottom edge > clampedScrollTop.
+            // A block's bottom edge = prefixSums[i] + heights[i].
+            // We want the smallest i such that prefixSums[i] + heights[i] > clampedScrollTop.
+            let lo = 0;
+            let hi = count - 1;
+            while (lo < hi) {
+                const mid = (lo + hi) >>> 1;
+                const bottomEdge = prefixSums[mid] + heights[mid];
+                if (bottomEdge <= clampedScrollTop) {
+                    lo = mid + 1;
+                }
+                else {
+                    hi = mid;
+                }
+            }
+            const firstVisible = lo;
+            // Linear scan forward to find last block within viewport.
+            // A block is visible if its top edge < clampedScrollTop + clampedViewportHeight.
+            const viewportBottom = clampedScrollTop + clampedViewportHeight;
+            let lastVisible = firstVisible;
+            for (let i = firstVisible; i < count; i++) {
+                if (prefixSums[i] >= viewportBottom) {
+                    break;
+                }
+                lastVisible = i;
+            }
+            // Apply buffer, clamped to valid range
+            const start = Math.max(0, firstVisible - clampedBuffer);
+            const end = Math.min(count, lastVisible + 1 + clampedBuffer);
+            return { start, end };
+        },
+        setBlockHeight(blockIndex, height) {
+            assertValidIndex(blockIndex, count);
+            heights[blockIndex] = height;
+            rebuildPrefixSums(heights, prefixSums, blockIndex);
+        },
+        setBlockHeights(updates) {
+            if (updates.length === 0)
+                return;
+            let minIndex = count;
+            for (const { index: idx, height } of updates) {
+                assertValidIndex(idx, count);
+                heights[idx] = height;
+                if (idx < minIndex) {
+                    minIndex = idx;
+                }
+            }
+            rebuildPrefixSums(heights, prefixSums, minIndex);
+        },
+        rebuild(d, preserveHeights) {
+            buildFromDoc(d, preserveHeights);
+        },
+    };
+    return index;
+}
+//# sourceMappingURL=spatial-index.js.map

package/dist/spatial-index.js.map

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

package/dist/types.d.ts

@@ -49,6 +49,19 @@ export interface WebEditorConfig {
      * Default: `true`.
      */
     readonly linkPopover?: boolean;
+    /**
+     * Register the built-in HTML paste handler (`@rtif-sdk/format-html`).
+     *
+     * When `true` (default), pasted HTML is deserialized into RTIF blocks
+     * preserving formatting. The handler is loaded lazily via dynamic
+     * `import()` so the `format-html` module is only bundled when used.
+     *
+     * Set to `false` to omit HTML paste support entirely (saves ~4.8 KB
+     * minified / ~1.5 KB gzipped).
+     *
+     * Default: `true`.
+     */
+    readonly htmlPaste?: boolean;
     /**
      * Custom web plugins to install.
      *
@@ -82,6 +95,70 @@ export interface WebEditorConfig {
      * Default: `false` (no instrumentation overhead).
      */
     readonly perf?: boolean | import('./perf.js').PerfObserver;
+    /**
+     * Enable block-level viewport virtualization for large documents.
+     *
+     * When enabled, only blocks visible in the viewport (plus a configurable
+     * buffer) are rendered to the DOM. Spacer elements maintain correct scroll
+     * height. Activates automatically when the document exceeds the
+     * `threshold` block count.
+     *
+     * - `true` or omitted — activate with default settings (threshold 100)
+     * - `false` — disable (render all blocks always)
+     * - `VirtualizationConfig` object — activate with custom settings
+     *
+     * Default: `true` (active when document exceeds threshold).
+     *
+     * @example
+     * ```ts
+     * createWebEditor({
+     *   ...,
+     *   virtualize: { threshold: 50, bufferSize: 20 },
+     * });
+     * ```
+     */
+    readonly virtualize?: boolean | VirtualizationConfig;
+}
+/**
+ * Configuration for block-level viewport virtualization.
+ *
+ * @example
+ * ```ts
+ * const config: VirtualizationConfig = {
+ *   threshold: 100,
+ *   bufferSize: 15,
+ *   estimatedBlockHeight: 28,
+ * };
+ * ```
+ */
+export interface VirtualizationConfig {
+    /**
+     * Minimum block count to activate virtualization.
+     * Documents with fewer blocks render all blocks to the DOM.
+     * Default: `100`.
+     */
+    readonly threshold?: number;
+    /**
+     * Number of extra blocks to render above and below the visible range.
+     * Higher values reduce flashing at the cost of more DOM nodes.
+     * Default: `10`.
+     */
+    readonly bufferSize?: number;
+    /**
+     * Default estimated pixel height for unknown block types.
+     * Default: `24`.
+     */
+    readonly estimatedBlockHeight?: number;
+    /**
+     * Estimated pixel heights per block type.
+     * Block types not listed here use `estimatedBlockHeight`.
+     */
+    readonly blockTypeHeights?: Readonly<Record<string, number>>;
+    /**
+     * The scrollable ancestor element, or `window`.
+     * When omitted, the nearest scrollable ancestor is auto-detected.
+     */
+    readonly scrollContainer?: HTMLElement | Window;
 }
 /**
  * The web editor instance returned by `createWebEditor`.
@@ -116,6 +193,11 @@ export interface WebEditor {
     readonly linkPopover: import('./link-popover.js').LinkPopoverHandle | null;
     /** Performance instrumentation handle, or null if perf is not enabled. */
     readonly perf: import('./perf.js').PerfInstrumentation | null;
+    /**
+     * Virtual viewport handle, or null if virtualization is not active.
+     * Only present when the document exceeds the virtualization threshold.
+     */
+    readonly viewport: import('./virtual-viewport.js').VirtualViewport | null;
     /**
      * Focus the editor's contenteditable element.
      * If the editor was destroyed, this is a no-op.

package/dist/types.d.ts.map

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