@vectojs/markdown 0.20.3 → 0.21.0

package/dist/Markdown.d.ts

@@ -83,6 +83,23 @@ export interface MarkdownOptions {
      * download behaviour to observe.
      */
     saveFile?: (filename: string, content: string, mimeType: string) => void;
+    /**
+     * Materialize only the top-level blocks near the viewport of a very large
+     * document, representing off-screen height as numeric offsets rather than
+     * entities. Off by default; pass `true` or `{ overscan }` to opt in.
+     *
+     * The host must drive it with {@link Markdown.setVisibleRange} each scroll
+     * frame (a `ScrollView` whose content is this `Markdown` does so
+     * automatically). Off-screen height is estimated from the token source and
+     * refined to the exact measured height when a block first mounts, so the
+     * scrollbar stays correct while only a window of blocks exists as entities.
+     *
+     * Not supported together with streaming (`createStream` / `appendMarkdown`):
+     * a document that virtualizes must be rendered whole.
+     */
+    virtualize?: boolean | {
+        overscan?: number;
+    };
 }
 /**
  * Renders Markdown content into a VectoJS entity tree using {@link marked}.
@@ -138,6 +155,19 @@ export declare class Markdown extends UIComponent {
     /** File saver used by the download controls. */
     saveFile: (filename: string, content: string, mimeType: string) => void;
     private activeBlockMetrics;
+    /** Whether `opts.virtualize` enabled viewport-culled block materialization. */
+    private readonly virtualizeBlocks;
+    /** Overscan margin (px) added above/below the visible window before mounting. */
+    private readonly virtualOverscan;
+    /** Top-level tokens that produce a child entity, in document order. */
+    private virtualTokens;
+    /** Fenwick tree over per-block strides (height + blockGap) when virtualizing. */
+    private virtualHeights;
+    /** token index → mounted entity, for blocks currently inside `content`. */
+    private readonly virtualMounted;
+    /** Visible window top (scroll offset) and height, last set via setVisibleRange. */
+    private virtualScrollY;
+    private virtualViewportH;
     /**
      * Called after this entity's own `width`/`height` changed because the document
      * was re-laid-out. **This is the hook to wire up when a host has to move or
@@ -388,6 +418,32 @@ export declare class Markdown extends UIComponent {
      */
     get frontMatterFields(): Readonly<Record<string, string>>;
     private renderMarkdown;
+    /**
+     * Drive the virtualized window from the host's scroll state.
+     *
+     * Only the blocks intersecting `[scrollY − overscan, scrollY + viewportHeight +
+     * overscan]` stay materialized; every other block is a numeric offset in the
+     * height tree, so the scrollbar still reports the full document height while
+     * only a window of blocks exists as entities. A no-op when `virtualize` was
+     * not enabled.
+     */
+    setVisibleRange(scrollY: number, viewportHeight: number): void;
+    /**
+     * Cheap per-block height estimate from the token source, refined to the exact
+     * measured height when the block first mounts. Coarse by design: the estimate
+     * only has to keep the scrollbar plausible before a block is first seen; the
+     * Fenwick tree corrects the rest.
+     */
+    private estimateBlockHeight;
+    /** Estimate a wrapped line count from raw character length against the max width. */
+    private estimateTextHeight;
+    /**
+     * Mount the blocks in the current window and unmount the rest. The `content`
+     * Stack lays the mounted window contiguously from y = 0; `content.y` is then
+     * set to the skipped prefix sum so the first mounted block lands at its true
+     * y — a numeric spacer, not a wrapper entity.
+     */
+    private reconcileVirtual;
     /** Create a frame-coalesced stream bound to this Markdown instance. */
     createStream(options?: StreamControllerOptions): StreamController;
     /**

package/dist/index.js

@@ -3499,6 +3499,19 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
   /** File saver used by the download controls. */
   saveFile;
   activeBlockMetrics = null;
+  /** Whether `opts.virtualize` enabled viewport-culled block materialization. */
+  virtualizeBlocks;
+  /** Overscan margin (px) added above/below the visible window before mounting. */
+  virtualOverscan;
+  /** Top-level tokens that produce a child entity, in document order. */
+  virtualTokens = null;
+  /** Fenwick tree over per-block strides (height + blockGap) when virtualizing. */
+  virtualHeights = null;
+  /** token index → mounted entity, for blocks currently inside `content`. */
+  virtualMounted = /* @__PURE__ */ new Map();
+  /** Visible window top (scroll offset) and height, last set via setVisibleRange. */
+  virtualScrollY = 0;
+  virtualViewportH = 0;
   /**
    * Called after this entity's own `width`/`height` changed because the document
    * was re-laid-out. **This is the hook to wire up when a host has to move or
@@ -3784,6 +3797,9 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     this.showCodeLanguage = opts.showCodeLanguage ?? false;
     this.writeClipboard = opts.writeClipboard ?? defaultWriteClipboard;
     this.saveFile = opts.saveFile ?? defaultSaveFile;
+    const virt = opts.virtualize;
+    this.virtualizeBlocks = virt === true || typeof virt === "object" && virt !== null;
+    this.virtualOverscan = typeof virt === "object" && virt !== null && typeof virt.overscan === "number" ? virt.overscan : 800;
     this.content = new import_ui4.Stack({
       direction: "vertical",
       gap: this.theme.blockGap
@@ -3896,6 +3912,20 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     const tokens = lexMarkdown(text, this._userTiming);
     this.setTokens(tokens);
     this.abbreviations = collectAbbreviations(tokens);
+    if (this.virtualizeBlocks) {
+      this.virtualTokens = tokens.filter((token) => this.producesEntity(token));
+      const n = this.virtualTokens.length;
+      this.virtualHeights = new import_ui4.RowHeights(n, 0);
+      for (let i = 0; i < n; i++) {
+        this.virtualHeights.set(
+          i,
+          this.estimateBlockHeight(this.virtualTokens[i]) + this.theme.blockGap
+        );
+      }
+      this.virtualMounted.clear();
+      this.reconcileVirtual();
+      return;
+    }
     for (const token of tokens) {
       const el = this.renderToken(token);
       if (el) {
@@ -3905,8 +3935,123 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     this.width = this.content.width;
     this.height = this.content.height;
   }
+  /**
+   * Drive the virtualized window from the host's scroll state.
+   *
+   * Only the blocks intersecting `[scrollY − overscan, scrollY + viewportHeight +
+   * overscan]` stay materialized; every other block is a numeric offset in the
+   * height tree, so the scrollbar still reports the full document height while
+   * only a window of blocks exists as entities. A no-op when `virtualize` was
+   * not enabled.
+   */
+  setVisibleRange(scrollY, viewportHeight) {
+    if (!this.virtualizeBlocks) return;
+    this.virtualScrollY = Math.max(0, scrollY);
+    this.virtualViewportH = Math.max(0, viewportHeight);
+    this.reconcileVirtual();
+  }
+  /**
+   * Cheap per-block height estimate from the token source, refined to the exact
+   * measured height when the block first mounts. Coarse by design: the estimate
+   * only has to keep the scrollbar plausible before a block is first seen; the
+   * Fenwick tree corrects the rest.
+   */
+  estimateBlockHeight(token) {
+    const t = this.theme;
+    switch (token.type) {
+      case "heading": {
+        const size = headingSize(t, token.depth);
+        return Math.ceil(size * 1.5) + 8;
+      }
+      case "paragraph":
+        return this.estimateTextHeight(token.text, t.bodyLineHeight);
+      case "code": {
+        const raw = token.text;
+        const lines = Math.max(1, raw.split("\n").length - (raw.endsWith("\n") ? 1 : 0));
+        let h = lines * t.codeLineHeight + t.codePadding * 2;
+        if (this.showCodeLanguage) h += t.codeLangFontSize + 8;
+        return h;
+      }
+      case "hr":
+        return 24;
+      case "blockquote":
+      case "container": {
+        const inner = token.tokens ?? [];
+        let sum = 0;
+        for (const tk of inner) sum += this.estimateBlockHeight(tk) + t.blockGap;
+        return sum + t.quoteInnerGap * 2 + 8;
+      }
+      case "list": {
+        const items = token.items ?? [];
+        let sum = 0;
+        for (const item of items) {
+          for (const tk of item.tokens ?? []) sum += this.estimateBlockHeight(tk) + t.listItemGap;
+        }
+        return sum + t.listGap;
+      }
+      case "table": {
+        const table = token;
+        const rows = (table.rows?.length ?? 0) + (table.header?.length ?? 0);
+        return rows * (t.tableFontSize + 16) + 16;
+      }
+      case "footnoteDef":
+        return this.estimateTextHeight(token.text ?? "", t.bodyLineHeight);
+      case "html":
+        return 200;
+      default:
+        return t.bodyLineHeight;
+    }
+  }
+  /** Estimate a wrapped line count from raw character length against the max width. */
+  estimateTextHeight(text, lineHeight) {
+    const charsPerLine = Math.max(20, Math.floor(this.maxWidth / (this.theme.fontSize * 0.5)));
+    const lines = Math.max(1, Math.ceil(text.length / charsPerLine));
+    return lines * lineHeight;
+  }
+  /**
+   * Mount the blocks in the current window and unmount the rest. The `content`
+   * Stack lays the mounted window contiguously from y = 0; `content.y` is then
+   * set to the skipped prefix sum so the first mounted block lands at its true
+   * y — a numeric spacer, not a wrapper entity.
+   */
+  reconcileVirtual() {
+    const tree = this.virtualHeights;
+    const tokens = this.virtualTokens;
+    if (!tree || !tokens) return;
+    const first = tree.indexAt(Math.max(0, this.virtualScrollY - this.virtualOverscan));
+    const last = tree.indexAt(
+      Math.max(0, this.virtualScrollY + this.virtualViewportH + this.virtualOverscan)
+    );
+    let changed = false;
+    for (const [idx, el] of this.virtualMounted) {
+      if (idx < first || idx > last) {
+        el.destroy();
+        this.virtualMounted.delete(idx);
+        changed = true;
+      }
+    }
+    for (let i = first; i <= last; i++) {
+      if (this.virtualMounted.has(i)) continue;
+      const el = this.renderToken(tokens[i]);
+      if (!el) continue;
+      this.content.add(el);
+      tree.set(i, el.height + this.theme.blockGap);
+      this.virtualMounted.set(i, el);
+      changed = true;
+    }
+    if (changed) this.content.layout();
+    this.content.y = tree.prefix(first);
+    const nextHeight = Math.max(0, tree.total() - this.theme.blockGap);
+    const heightChanged = nextHeight !== this.height;
+    this.width = this.content.width;
+    this.height = nextHeight;
+    if (heightChanged) this.notifyLayoutUpdated();
+  }
   /** Create a frame-coalesced stream bound to this Markdown instance. */
   createStream(options = {}) {
+    if (this.virtualizeBlocks) {
+      throw new Error("Markdown.createStream is not supported when virtualize is enabled");
+    }
     if (this.streamController) {
       throw new Error("Markdown already has an active StreamController");
     }
@@ -3979,6 +4124,18 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     const next = Math.max(0, maxWidth);
     if (next === this.maxWidth) return this;
     this.maxWidth = next;
+    if (this.virtualizeBlocks && this.virtualTokens && this.virtualHeights) {
+      const tokens = this.virtualTokens;
+      const tree = this.virtualHeights;
+      for (const el of this.virtualMounted.values()) el.destroy();
+      this.virtualMounted.clear();
+      for (let i = 0; i < tokens.length; i++) {
+        tree.set(i, this.estimateBlockHeight(tokens[i]) + this.theme.blockGap);
+      }
+      this.reconcileVirtual();
+      this.scene?.markDirty();
+      return this;
+    }
     let childIndex = 0;
     const children = this.content.children;
     for (const token of this.tokens) {
@@ -4513,6 +4670,9 @@ var Markdown = class _Markdown extends import_ui4.UIComponent {
     return this.appendMarkdownCore(chunk);
   }
   appendMarkdownCore(chunk) {
+    if (this.virtualizeBlocks) {
+      throw new Error("Markdown.appendMarkdown is not supported when virtualize is enabled");
+    }
     const before = this.rawMarkdown.length;
     this.consumeFrontMatter(chunk);
     this.streamStats.appends++;

package/dist/index.mjs

@@ -2948,7 +2948,15 @@ function renderFencedBlock(source, lang, options) {
 }
 
 // src/Markdown.ts
-import { RichText as RichText2, Stack, Table, Text, Image, UIComponent as UIComponent3 } from "@vectojs/ui";
+import {
+  RichText as RichText2,
+  RowHeights,
+  Stack,
+  Table,
+  Text,
+  Image,
+  UIComponent as UIComponent3
+} from "@vectojs/ui";
 
 // src/blockAffordances.ts
 import { Button, measureText as measureText2, UIComponent as UIComponent2 } from "@vectojs/ui";
@@ -3445,6 +3453,19 @@ var Markdown = class _Markdown extends UIComponent3 {
   /** File saver used by the download controls. */
   saveFile;
   activeBlockMetrics = null;
+  /** Whether `opts.virtualize` enabled viewport-culled block materialization. */
+  virtualizeBlocks;
+  /** Overscan margin (px) added above/below the visible window before mounting. */
+  virtualOverscan;
+  /** Top-level tokens that produce a child entity, in document order. */
+  virtualTokens = null;
+  /** Fenwick tree over per-block strides (height + blockGap) when virtualizing. */
+  virtualHeights = null;
+  /** token index → mounted entity, for blocks currently inside `content`. */
+  virtualMounted = /* @__PURE__ */ new Map();
+  /** Visible window top (scroll offset) and height, last set via setVisibleRange. */
+  virtualScrollY = 0;
+  virtualViewportH = 0;
   /**
    * Called after this entity's own `width`/`height` changed because the document
    * was re-laid-out. **This is the hook to wire up when a host has to move or
@@ -3730,6 +3751,9 @@ var Markdown = class _Markdown extends UIComponent3 {
     this.showCodeLanguage = opts.showCodeLanguage ?? false;
     this.writeClipboard = opts.writeClipboard ?? defaultWriteClipboard;
     this.saveFile = opts.saveFile ?? defaultSaveFile;
+    const virt = opts.virtualize;
+    this.virtualizeBlocks = virt === true || typeof virt === "object" && virt !== null;
+    this.virtualOverscan = typeof virt === "object" && virt !== null && typeof virt.overscan === "number" ? virt.overscan : 800;
     this.content = new Stack({
       direction: "vertical",
       gap: this.theme.blockGap
@@ -3842,6 +3866,20 @@ var Markdown = class _Markdown extends UIComponent3 {
     const tokens = lexMarkdown(text, this._userTiming);
     this.setTokens(tokens);
     this.abbreviations = collectAbbreviations(tokens);
+    if (this.virtualizeBlocks) {
+      this.virtualTokens = tokens.filter((token) => this.producesEntity(token));
+      const n = this.virtualTokens.length;
+      this.virtualHeights = new RowHeights(n, 0);
+      for (let i = 0; i < n; i++) {
+        this.virtualHeights.set(
+          i,
+          this.estimateBlockHeight(this.virtualTokens[i]) + this.theme.blockGap
+        );
+      }
+      this.virtualMounted.clear();
+      this.reconcileVirtual();
+      return;
+    }
     for (const token of tokens) {
       const el = this.renderToken(token);
       if (el) {
@@ -3851,8 +3889,123 @@ var Markdown = class _Markdown extends UIComponent3 {
     this.width = this.content.width;
     this.height = this.content.height;
   }
+  /**
+   * Drive the virtualized window from the host's scroll state.
+   *
+   * Only the blocks intersecting `[scrollY − overscan, scrollY + viewportHeight +
+   * overscan]` stay materialized; every other block is a numeric offset in the
+   * height tree, so the scrollbar still reports the full document height while
+   * only a window of blocks exists as entities. A no-op when `virtualize` was
+   * not enabled.
+   */
+  setVisibleRange(scrollY, viewportHeight) {
+    if (!this.virtualizeBlocks) return;
+    this.virtualScrollY = Math.max(0, scrollY);
+    this.virtualViewportH = Math.max(0, viewportHeight);
+    this.reconcileVirtual();
+  }
+  /**
+   * Cheap per-block height estimate from the token source, refined to the exact
+   * measured height when the block first mounts. Coarse by design: the estimate
+   * only has to keep the scrollbar plausible before a block is first seen; the
+   * Fenwick tree corrects the rest.
+   */
+  estimateBlockHeight(token) {
+    const t = this.theme;
+    switch (token.type) {
+      case "heading": {
+        const size = headingSize(t, token.depth);
+        return Math.ceil(size * 1.5) + 8;
+      }
+      case "paragraph":
+        return this.estimateTextHeight(token.text, t.bodyLineHeight);
+      case "code": {
+        const raw = token.text;
+        const lines = Math.max(1, raw.split("\n").length - (raw.endsWith("\n") ? 1 : 0));
+        let h = lines * t.codeLineHeight + t.codePadding * 2;
+        if (this.showCodeLanguage) h += t.codeLangFontSize + 8;
+        return h;
+      }
+      case "hr":
+        return 24;
+      case "blockquote":
+      case "container": {
+        const inner = token.tokens ?? [];
+        let sum = 0;
+        for (const tk of inner) sum += this.estimateBlockHeight(tk) + t.blockGap;
+        return sum + t.quoteInnerGap * 2 + 8;
+      }
+      case "list": {
+        const items = token.items ?? [];
+        let sum = 0;
+        for (const item of items) {
+          for (const tk of item.tokens ?? []) sum += this.estimateBlockHeight(tk) + t.listItemGap;
+        }
+        return sum + t.listGap;
+      }
+      case "table": {
+        const table = token;
+        const rows = (table.rows?.length ?? 0) + (table.header?.length ?? 0);
+        return rows * (t.tableFontSize + 16) + 16;
+      }
+      case "footnoteDef":
+        return this.estimateTextHeight(token.text ?? "", t.bodyLineHeight);
+      case "html":
+        return 200;
+      default:
+        return t.bodyLineHeight;
+    }
+  }
+  /** Estimate a wrapped line count from raw character length against the max width. */
+  estimateTextHeight(text, lineHeight) {
+    const charsPerLine = Math.max(20, Math.floor(this.maxWidth / (this.theme.fontSize * 0.5)));
+    const lines = Math.max(1, Math.ceil(text.length / charsPerLine));
+    return lines * lineHeight;
+  }
+  /**
+   * Mount the blocks in the current window and unmount the rest. The `content`
+   * Stack lays the mounted window contiguously from y = 0; `content.y` is then
+   * set to the skipped prefix sum so the first mounted block lands at its true
+   * y — a numeric spacer, not a wrapper entity.
+   */
+  reconcileVirtual() {
+    const tree = this.virtualHeights;
+    const tokens = this.virtualTokens;
+    if (!tree || !tokens) return;
+    const first = tree.indexAt(Math.max(0, this.virtualScrollY - this.virtualOverscan));
+    const last = tree.indexAt(
+      Math.max(0, this.virtualScrollY + this.virtualViewportH + this.virtualOverscan)
+    );
+    let changed = false;
+    for (const [idx, el] of this.virtualMounted) {
+      if (idx < first || idx > last) {
+        el.destroy();
+        this.virtualMounted.delete(idx);
+        changed = true;
+      }
+    }
+    for (let i = first; i <= last; i++) {
+      if (this.virtualMounted.has(i)) continue;
+      const el = this.renderToken(tokens[i]);
+      if (!el) continue;
+      this.content.add(el);
+      tree.set(i, el.height + this.theme.blockGap);
+      this.virtualMounted.set(i, el);
+      changed = true;
+    }
+    if (changed) this.content.layout();
+    this.content.y = tree.prefix(first);
+    const nextHeight = Math.max(0, tree.total() - this.theme.blockGap);
+    const heightChanged = nextHeight !== this.height;
+    this.width = this.content.width;
+    this.height = nextHeight;
+    if (heightChanged) this.notifyLayoutUpdated();
+  }
   /** Create a frame-coalesced stream bound to this Markdown instance. */
   createStream(options = {}) {
+    if (this.virtualizeBlocks) {
+      throw new Error("Markdown.createStream is not supported when virtualize is enabled");
+    }
     if (this.streamController) {
       throw new Error("Markdown already has an active StreamController");
     }
@@ -3925,6 +4078,18 @@ var Markdown = class _Markdown extends UIComponent3 {
     const next = Math.max(0, maxWidth);
     if (next === this.maxWidth) return this;
     this.maxWidth = next;
+    if (this.virtualizeBlocks && this.virtualTokens && this.virtualHeights) {
+      const tokens = this.virtualTokens;
+      const tree = this.virtualHeights;
+      for (const el of this.virtualMounted.values()) el.destroy();
+      this.virtualMounted.clear();
+      for (let i = 0; i < tokens.length; i++) {
+        tree.set(i, this.estimateBlockHeight(tokens[i]) + this.theme.blockGap);
+      }
+      this.reconcileVirtual();
+      this.scene?.markDirty();
+      return this;
+    }
     let childIndex = 0;
     const children = this.content.children;
     for (const token of this.tokens) {
@@ -4459,6 +4624,9 @@ var Markdown = class _Markdown extends UIComponent3 {
     return this.appendMarkdownCore(chunk);
   }
   appendMarkdownCore(chunk) {
+    if (this.virtualizeBlocks) {
+      throw new Error("Markdown.appendMarkdown is not supported when virtualize is enabled");
+    }
     const before = this.rawMarkdown.length;
     this.consumeFrontMatter(chunk);
     this.streamStats.appends++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/markdown",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "publishConfig": {
     "access": "public"
   },