@vectojs/markdown 0.20.2 → 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

@@ -1327,6 +1327,70 @@ function highlightLine(line, lang, theme, carry = null) {
   flush(theme.codeColor);
   return { segments, carry: null };
 }
+var HSCROLL_HIT_H = 12;
+var HSCROLL_THUMB_H = 4;
+var HSCROLL_THUMB_INSET = 4;
+var HSCROLL_THUMB_MIN = 24;
+var HSCROLL_TRACK_COLOR = "rgba(128, 128, 128, 0.14)";
+var HSCROLL_THUMB_COLOR = "rgba(128, 128, 128, 0.45)";
+var HSCROLL_THUMB_ACTIVE_COLOR = "rgba(128, 128, 128, 0.75)";
+function hScrollMetrics(trackW, maxScrollX) {
+  const content = trackW + maxScrollX;
+  const proportional = content > 0 ? trackW / content * trackW : trackW;
+  const thumbW = Math.min(trackW, Math.max(HSCROLL_THUMB_MIN, proportional));
+  return { thumbW, range: Math.max(1, trackW - thumbW) };
+}
+var HScrollTrack = class extends import_ui.UIComponent {
+  constructor(block) {
+    super();
+    this.block = block;
+    this.on("pointerdown", (e) => {
+      if (e.localX === void 0) return;
+      const maxSX = this.block.maxScrollX;
+      if (maxSX <= 0) return;
+      const { thumbW, range } = hScrollMetrics(this.width, maxSX);
+      const thumbX = this.block.scrollX / maxSX * range;
+      if (e.localX < thumbX || e.localX > thumbX + thumbW) {
+        this.block.setScrollX((e.localX - thumbW / 2) / range * maxSX);
+      }
+      this.dragging = true;
+      this.dragAnchorX = e.localX;
+      this.scrollAtDragStart = this.block.scrollX;
+      this.scene?.markDirty();
+    });
+    this.on("pointermove", (e) => {
+      if (!this.dragging || e.localX === void 0) return;
+      const maxSX = this.block.maxScrollX;
+      const { range } = hScrollMetrics(this.width, maxSX);
+      const dx = e.localX - this.dragAnchorX;
+      this.block.setScrollX(this.scrollAtDragStart + dx / range * maxSX);
+    });
+    const endDrag = () => {
+      if (!this.dragging) return;
+      this.dragging = false;
+      this.scene?.markDirty();
+    };
+    this.on("pointerup", endDrag);
+    this.on("pointerleave", endDrag);
+  }
+  block;
+  /** True while a drag owns the thumb; read by the block's painter for the active tint. */
+  dragging = false;
+  dragAnchorX = 0;
+  scrollAtDragStart = 0;
+  getA11yAttributes() {
+    return {
+      role: "scrollbar",
+      label: "Scroll code horizontally",
+      value: String(Math.round(this.block.scrollX)),
+      valuemin: "0",
+      valuemax: String(Math.round(this.block.maxScrollX))
+    };
+  }
+  /** Nothing to draw: the thumb is painted by the owning block, so both share one pass. */
+  render() {
+  }
+};
 var CodeBlock = class extends import_ui.UIComponent {
   lines;
   /**
@@ -1364,6 +1428,12 @@ var CodeBlock = class extends import_ui.UIComponent {
   /** Memoized widest prepared line, keyed by the grid identity it came from. */
   contentWidthGrid = null;
   contentWidthValue = 0;
+  /**
+   * The interactive horizontal scrollbar strip (#527), created lazily by
+   * {@link syncScrollTrack} the first time the block overflows. Kept, and merely
+   * disabled, when the overflow later disappears — see there for why.
+   */
+  hTrack = null;
   lang;
   theme;
   /**
@@ -1668,6 +1738,31 @@ var CodeBlock = class extends import_ui.UIComponent {
     }
     return this.grid;
   }
+  /**
+   * Fit the interactive scrollbar strip (#527) to the current overflow.
+   *
+   * Called from {@link render} rather than from `setWidth` or `buildLines`:
+   * `setWidth` is documented as costing nothing and `maxScrollX` costs a grid
+   * build, while `render` is about to pay for that grid anyway. Once created,
+   * the child is KEPT and merely de-`interactive`d when the overflow disappears
+   * — this runs inside the scene's tree walk, and removing a child mid-walk is
+   * how siblings get skipped.
+   */
+  syncScrollTrack() {
+    if (this.maxScrollX <= 0) {
+      if (this.hTrack) this.hTrack.interactive = false;
+      return;
+    }
+    if (!this.hTrack) {
+      this.hTrack = new HScrollTrack(this);
+      this.add(this.hTrack);
+    }
+    this.hTrack.interactive = true;
+    this.hTrack.x = this.pad;
+    this.hTrack.y = this.height - HSCROLL_HIT_H;
+    this.hTrack.width = Math.max(0, this.width - this.pad * 2);
+    this.hTrack.height = HSCROLL_HIT_H;
+  }
   /**
    * Not hit-testable, and deliberately still not `interactive`, even though the
    * block now consumes wheel events to scroll.
@@ -1676,11 +1771,16 @@ var CodeBlock = class extends import_ui.UIComponent {
    * hit-testing, so no a11y shadow node is needed. Creating one would place a
    * `pointer-events: auto` element above the transparent text mirror and swallow
    * the mousedown that starts a native drag-selection.
+   *
+   * Pointer-driven scrolling therefore lives on the {@link HScrollTrack} CHILD,
+   * whose shadow node covers only the bottom-padding strip below the last
+   * selectable carrier — never the text itself.
    */
   isPointInside() {
     return false;
   }
   render(r) {
+    this.syncScrollTrack();
     r.beginPath();
     r.roundRect(0, 0, this.width, this.height, this.theme.codeRadius);
     r.fill(this.theme.codeBgColor);
@@ -1750,6 +1850,24 @@ var CodeBlock = class extends import_ui.UIComponent {
       }
     }
     r.restore();
+    const maxSX = this.maxScrollX;
+    if (maxSX > 0) {
+      const trackW = Math.max(0, this.width - this.pad * 2);
+      const { thumbW, range } = hScrollMetrics(trackW, maxSX);
+      const trackY = this.height - HSCROLL_THUMB_H - HSCROLL_THUMB_INSET;
+      r.beginPath();
+      r.roundRect(this.pad, trackY, trackW, HSCROLL_THUMB_H, HSCROLL_THUMB_H / 2);
+      r.fill(HSCROLL_TRACK_COLOR);
+      r.beginPath();
+      r.roundRect(
+        this.pad + this.scrollX / maxSX * range,
+        trackY,
+        thumbW,
+        HSCROLL_THUMB_H,
+        HSCROLL_THUMB_H / 2
+      );
+      r.fill(this.hTrack?.dragging ? HSCROLL_THUMB_ACTIVE_COLOR : HSCROLL_THUMB_COLOR);
+    }
   }
 };
 var codeAtlases = /* @__PURE__ */ new Map();
@@ -3381,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
@@ -3666,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
@@ -3778,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) {
@@ -3787,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");
     }
@@ -3861,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) {
@@ -4395,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

@@ -1273,6 +1273,70 @@ function highlightLine(line, lang, theme, carry = null) {
   flush(theme.codeColor);
   return { segments, carry: null };
 }
+var HSCROLL_HIT_H = 12;
+var HSCROLL_THUMB_H = 4;
+var HSCROLL_THUMB_INSET = 4;
+var HSCROLL_THUMB_MIN = 24;
+var HSCROLL_TRACK_COLOR = "rgba(128, 128, 128, 0.14)";
+var HSCROLL_THUMB_COLOR = "rgba(128, 128, 128, 0.45)";
+var HSCROLL_THUMB_ACTIVE_COLOR = "rgba(128, 128, 128, 0.75)";
+function hScrollMetrics(trackW, maxScrollX) {
+  const content = trackW + maxScrollX;
+  const proportional = content > 0 ? trackW / content * trackW : trackW;
+  const thumbW = Math.min(trackW, Math.max(HSCROLL_THUMB_MIN, proportional));
+  return { thumbW, range: Math.max(1, trackW - thumbW) };
+}
+var HScrollTrack = class extends UIComponent {
+  constructor(block) {
+    super();
+    this.block = block;
+    this.on("pointerdown", (e) => {
+      if (e.localX === void 0) return;
+      const maxSX = this.block.maxScrollX;
+      if (maxSX <= 0) return;
+      const { thumbW, range } = hScrollMetrics(this.width, maxSX);
+      const thumbX = this.block.scrollX / maxSX * range;
+      if (e.localX < thumbX || e.localX > thumbX + thumbW) {
+        this.block.setScrollX((e.localX - thumbW / 2) / range * maxSX);
+      }
+      this.dragging = true;
+      this.dragAnchorX = e.localX;
+      this.scrollAtDragStart = this.block.scrollX;
+      this.scene?.markDirty();
+    });
+    this.on("pointermove", (e) => {
+      if (!this.dragging || e.localX === void 0) return;
+      const maxSX = this.block.maxScrollX;
+      const { range } = hScrollMetrics(this.width, maxSX);
+      const dx = e.localX - this.dragAnchorX;
+      this.block.setScrollX(this.scrollAtDragStart + dx / range * maxSX);
+    });
+    const endDrag = () => {
+      if (!this.dragging) return;
+      this.dragging = false;
+      this.scene?.markDirty();
+    };
+    this.on("pointerup", endDrag);
+    this.on("pointerleave", endDrag);
+  }
+  block;
+  /** True while a drag owns the thumb; read by the block's painter for the active tint. */
+  dragging = false;
+  dragAnchorX = 0;
+  scrollAtDragStart = 0;
+  getA11yAttributes() {
+    return {
+      role: "scrollbar",
+      label: "Scroll code horizontally",
+      value: String(Math.round(this.block.scrollX)),
+      valuemin: "0",
+      valuemax: String(Math.round(this.block.maxScrollX))
+    };
+  }
+  /** Nothing to draw: the thumb is painted by the owning block, so both share one pass. */
+  render() {
+  }
+};
 var CodeBlock = class extends UIComponent {
   lines;
   /**
@@ -1310,6 +1374,12 @@ var CodeBlock = class extends UIComponent {
   /** Memoized widest prepared line, keyed by the grid identity it came from. */
   contentWidthGrid = null;
   contentWidthValue = 0;
+  /**
+   * The interactive horizontal scrollbar strip (#527), created lazily by
+   * {@link syncScrollTrack} the first time the block overflows. Kept, and merely
+   * disabled, when the overflow later disappears — see there for why.
+   */
+  hTrack = null;
   lang;
   theme;
   /**
@@ -1614,6 +1684,31 @@ var CodeBlock = class extends UIComponent {
     }
     return this.grid;
   }
+  /**
+   * Fit the interactive scrollbar strip (#527) to the current overflow.
+   *
+   * Called from {@link render} rather than from `setWidth` or `buildLines`:
+   * `setWidth` is documented as costing nothing and `maxScrollX` costs a grid
+   * build, while `render` is about to pay for that grid anyway. Once created,
+   * the child is KEPT and merely de-`interactive`d when the overflow disappears
+   * — this runs inside the scene's tree walk, and removing a child mid-walk is
+   * how siblings get skipped.
+   */
+  syncScrollTrack() {
+    if (this.maxScrollX <= 0) {
+      if (this.hTrack) this.hTrack.interactive = false;
+      return;
+    }
+    if (!this.hTrack) {
+      this.hTrack = new HScrollTrack(this);
+      this.add(this.hTrack);
+    }
+    this.hTrack.interactive = true;
+    this.hTrack.x = this.pad;
+    this.hTrack.y = this.height - HSCROLL_HIT_H;
+    this.hTrack.width = Math.max(0, this.width - this.pad * 2);
+    this.hTrack.height = HSCROLL_HIT_H;
+  }
   /**
    * Not hit-testable, and deliberately still not `interactive`, even though the
    * block now consumes wheel events to scroll.
@@ -1622,11 +1717,16 @@ var CodeBlock = class extends UIComponent {
    * hit-testing, so no a11y shadow node is needed. Creating one would place a
    * `pointer-events: auto` element above the transparent text mirror and swallow
    * the mousedown that starts a native drag-selection.
+   *
+   * Pointer-driven scrolling therefore lives on the {@link HScrollTrack} CHILD,
+   * whose shadow node covers only the bottom-padding strip below the last
+   * selectable carrier — never the text itself.
    */
   isPointInside() {
     return false;
   }
   render(r) {
+    this.syncScrollTrack();
     r.beginPath();
     r.roundRect(0, 0, this.width, this.height, this.theme.codeRadius);
     r.fill(this.theme.codeBgColor);
@@ -1696,6 +1796,24 @@ var CodeBlock = class extends UIComponent {
       }
     }
     r.restore();
+    const maxSX = this.maxScrollX;
+    if (maxSX > 0) {
+      const trackW = Math.max(0, this.width - this.pad * 2);
+      const { thumbW, range } = hScrollMetrics(trackW, maxSX);
+      const trackY = this.height - HSCROLL_THUMB_H - HSCROLL_THUMB_INSET;
+      r.beginPath();
+      r.roundRect(this.pad, trackY, trackW, HSCROLL_THUMB_H, HSCROLL_THUMB_H / 2);
+      r.fill(HSCROLL_TRACK_COLOR);
+      r.beginPath();
+      r.roundRect(
+        this.pad + this.scrollX / maxSX * range,
+        trackY,
+        thumbW,
+        HSCROLL_THUMB_H,
+        HSCROLL_THUMB_H / 2
+      );
+      r.fill(this.hTrack?.dragging ? HSCROLL_THUMB_ACTIVE_COLOR : HSCROLL_THUMB_COLOR);
+    }
   }
 };
 var codeAtlases = /* @__PURE__ */ new Map();
@@ -2830,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";
@@ -3327,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
@@ -3612,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
@@ -3724,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) {
@@ -3733,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");
     }
@@ -3807,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) {
@@ -4341,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/dist/markdown-code.d.ts

@@ -71,6 +71,12 @@ export declare class CodeBlock extends UIComponent {
     /** Memoized widest prepared line, keyed by the grid identity it came from. */
     private contentWidthGrid;
     private contentWidthValue;
+    /**
+     * The interactive horizontal scrollbar strip (#527), created lazily by
+     * {@link syncScrollTrack} the first time the block overflows. Kept, and merely
+     * disabled, when the overflow later disappears — see there for why.
+     */
+    private hTrack;
     private lang;
     private theme;
     /**
@@ -203,6 +209,17 @@ export declare class CodeBlock extends UIComponent {
      */
     private buildLines;
     private ensureGrid;
+    /**
+     * Fit the interactive scrollbar strip (#527) to the current overflow.
+     *
+     * Called from {@link render} rather than from `setWidth` or `buildLines`:
+     * `setWidth` is documented as costing nothing and `maxScrollX` costs a grid
+     * build, while `render` is about to pay for that grid anyway. Once created,
+     * the child is KEPT and merely de-`interactive`d when the overflow disappears
+     * — this runs inside the scene's tree walk, and removing a child mid-walk is
+     * how siblings get skipped.
+     */
+    private syncScrollTrack;
     /**
      * Not hit-testable, and deliberately still not `interactive`, even though the
      * block now consumes wheel events to scroll.
@@ -211,6 +228,10 @@ export declare class CodeBlock extends UIComponent {
      * hit-testing, so no a11y shadow node is needed. Creating one would place a
      * `pointer-events: auto` element above the transparent text mirror and swallow
      * the mousedown that starts a native drag-selection.
+     *
+     * Pointer-driven scrolling therefore lives on the {@link HScrollTrack} CHILD,
+     * whose shadow node covers only the bottom-padding strip below the last
+     * selectable carrier — never the text itself.
      */
     isPointInside(): boolean;
     render(r: IRenderer): void;

package/package.json

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