@vectojs/markdown 0.1.2 → 0.2.0

package/dist/Markdown.d.ts

@@ -1,4 +1,4 @@
-import { Entity, IRenderer, type ContentProjection } from '@vectojs/core';
+import { Entity, type DevtoolsDescriptor, GlyphRasterAtlas, type GlyphRasterAtlasStats, IRenderer, type ContentProjection } from '@vectojs/core';
 import { type Token } from 'marked';
 import { Stack, UIComponent } from '@vectojs/ui';
 /** Color and typography theme for Markdown rendering. */
@@ -71,6 +71,25 @@ export declare class CodeBlock extends UIComponent {
     isPointInside(): boolean;
     render(r: IRenderer): void;
 }
+/**
+ * Instrumentation for the shared code-block glyph atlas, or `null` before first
+ * use.
+ *
+ * Exposed so an app or benchmark can confirm the atlas is actually active and
+ * reusing slots. Watch `resets`: a steadily climbing count means the glyph set is
+ * unbounded for the atlas size, so every reset re-rasterizes everything and the
+ * atlas is doing net harm rather than saving work.
+ */
+export declare function codeAtlasStats(): GlyphRasterAtlasStats | null;
+/**
+ * The shared code-block atlas itself, or `null` before first use.
+ *
+ * For instrumentation that must map a traced `drawImage` back to the glyph it
+ * painted — a blit carries only a source rect, so `slotAt()` is the only way to
+ * recover the cluster and its metrics. Used by `e2e/text-projection.e2e.ts` to
+ * keep the code-grid positioning assertions working on the blit path.
+ */
+export declare function codeAtlas(): GlyphRasterAtlas | null;
 export interface MarkdownOptions {
     maxWidth?: number;
     theme?: MarkdownTheme;
@@ -105,6 +124,16 @@ export declare class Markdown extends UIComponent {
     private tokens;
     private appendInFlight;
     private appendPending;
+    /**
+     * Streaming counters for the DevTools inspector.
+     *
+     * Cheap enough to keep always-on (four integer increments per append) and the
+     * only way to see, from outside, whether incremental reuse is actually working:
+     * a stable-prefix ratio near 1 means the worker is matching almost everything
+     * and only the tail is re-lexed, while a ratio near 0 means every chunk is
+     * re-parsing the whole document.
+     */
+    private streamStats;
     private pendingWorkerIds;
     private readonly workerInstanceId;
     private tokenVersion;
@@ -130,6 +159,16 @@ export declare class Markdown extends UIComponent {
      * content subtree via `super.destroy()` so every block's resources are freed.
      */
     destroy(): void;
+    /**
+     * Streaming and parse state — the markdown streaming inspector.
+     *
+     * Source length, chunk count, worker in-flight state, and the stable-prefix
+     * versus re-lexed-tail split. That last ratio is the one worth watching: it is
+     * how you tell incremental reuse is working from outside, and nothing else
+     * surfaces it. A ratio near 1 means the worker matched almost the whole prefix
+     * and only re-lexed the tail; near 0 means every chunk re-parses the document.
+     */
+    getDevtoolsDescriptor(): DevtoolsDescriptor;
     /** Enable or disable native selection for existing and future Markdown text. */
     setSelectable(selectable: boolean): this;
     /** Append a markdown chunk incrementally. Reuses unchanged prefix entities. */

package/dist/index.js

@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CodeBlock: () => CodeBlock,
-  Markdown: () => Markdown
+  Markdown: () => Markdown,
+  codeAtlas: () => codeAtlas,
+  codeAtlasStats: () => codeAtlasStats
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -553,6 +555,9 @@ var CodeBlock = class extends import_ui.UIComponent {
     r.roundRect(0, 0, this.width, this.height, 8);
     r.fill(this.theme.codeBgColor);
     const grid = this.ensureGrid();
+    const atlas = codeGlyphAtlas(r);
+    const atlasSource = atlas?.source ?? null;
+    const blit = atlas ? r.drawImageRect : void 0;
     for (let row = 0; row < grid.lines.length; row++) {
       const yBaseline = this.pad + row * this.lineH + this.lineH * 0.75;
       const segments = this.lines[row];
@@ -567,17 +572,51 @@ var CodeBlock = class extends import_ui.UIComponent {
         }
         const sourceText = this.source.slice(cell.sourceStart, cell.sourceEnd);
         if (cell.advance <= 0 || sourceText === " " || sourceText === "	") continue;
-        r.fillText(
-          cell.glyph,
-          this.pad + cell.x,
-          yBaseline,
-          this.codeFont,
-          segments[segmentIndex]?.color ?? this.theme.codeColor
-        );
+        const color = segments[segmentIndex]?.color ?? this.theme.codeColor;
+        const x = this.pad + cell.x;
+        if (blit && atlas) {
+          const slot = atlas.get(this.codeFont, color, cell.glyph);
+          const src = atlasSource ?? atlas.source;
+          if (slot && src) {
+            blit.call(
+              r,
+              src,
+              slot.sx,
+              slot.sy,
+              slot.sw,
+              slot.sh,
+              x - slot.offsetX,
+              yBaseline - slot.offsetY,
+              slot.w,
+              slot.h
+            );
+            continue;
+          }
+        }
+        r.fillText(cell.glyph, x, yBaseline, this.codeFont, color);
       }
     }
   }
 };
+var sharedCodeAtlas = null;
+function codeGlyphAtlas(r) {
+  if (typeof r.drawImageRect !== "function") return void 0;
+  if (typeof document === "undefined") return void 0;
+  sharedCodeAtlas ??= new import_core.GlyphRasterAtlas({
+    // Match the display so a HiDPI blit stays crisp. Capped at 3 because atlas
+    // area grows with dpr² and a 4x display would otherwise blow the size cap
+    // with a few hundred glyphs.
+    dpr: typeof window !== "undefined" ? Math.min(window.devicePixelRatio || 1, 3) : 1,
+    maxSize: 2048
+  });
+  return sharedCodeAtlas;
+}
+function codeAtlasStats() {
+  return sharedCodeAtlas ? sharedCodeAtlas.stats : null;
+}
+function codeAtlas() {
+  return sharedCodeAtlas;
+}
 function decodeEntities(text) {
   return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
 }
@@ -717,6 +756,23 @@ var Markdown = class extends import_ui.UIComponent {
   // with the latest accumulated text once it resolves.
   appendInFlight = false;
   appendPending = false;
+  /**
+   * Streaming counters for the DevTools inspector.
+   *
+   * Cheap enough to keep always-on (four integer increments per append) and the
+   * only way to see, from outside, whether incremental reuse is actually working:
+   * a stable-prefix ratio near 1 means the worker is matching almost everything
+   * and only the tail is re-lexed, while a ratio near 0 means every chunk is
+   * re-parsing the whole document.
+   */
+  streamStats = {
+    appends: 0,
+    workerResponses: 0,
+    /** Sum of `matchLen` across responses, i.e. tokens reused rather than re-lexed. */
+    tokensReused: 0,
+    /** Sum of returned tail lengths, i.e. tokens the worker had to re-lex. */
+    tokensRelexed: 0
+  };
   // Worker request ids dispatched by *this* instance that haven't resolved yet.
   // The module-level `workerCallbacks` map holds a closure capturing `this`, so
   // destroying a Markdown mid-stream would pin the whole entity (and its subtree)
@@ -809,6 +865,81 @@ var Markdown = class extends import_ui.UIComponent {
     });
     super.destroy();
   }
+  /**
+   * Streaming and parse state — the markdown streaming inspector.
+   *
+   * Source length, chunk count, worker in-flight state, and the stable-prefix
+   * versus re-lexed-tail split. That last ratio is the one worth watching: it is
+   * how you tell incremental reuse is working from outside, and nothing else
+   * surfaces it. A ratio near 1 means the worker matched almost the whole prefix
+   * and only re-lexed the tail; near 0 means every chunk re-parses the document.
+   */
+  getDevtoolsDescriptor() {
+    const s = this.streamStats;
+    const lexed = s.tokensReused + s.tokensRelexed;
+    const reuseRatio = lexed > 0 ? s.tokensReused / lexed : 0;
+    return {
+      kind: "Markdown",
+      groups: [
+        {
+          label: "Source",
+          fields: [
+            { label: "sourceLength", value: this.rawMarkdown.length, readOnly: true },
+            { label: "topLevelTokens", value: this.tokens.length, readOnly: true },
+            { label: "childEntities", value: this.content.children.length, readOnly: true },
+            { label: "selectable", value: this.selectable }
+          ]
+        },
+        {
+          label: "Streaming",
+          fields: [
+            { label: "appends", value: s.appends, readOnly: true },
+            {
+              label: "workerResponses",
+              value: s.workerResponses,
+              hint: "Fewer than appends means chunks were coalesced while a request was in flight",
+              readOnly: true
+            },
+            {
+              label: "appendInFlight",
+              value: this.appendInFlight,
+              hint: "One lex request at a time; the delta protocol requires it",
+              readOnly: true
+            },
+            { label: "appendPending", value: this.appendPending, readOnly: true }
+          ]
+        },
+        {
+          label: "Incremental reuse",
+          fields: [
+            {
+              label: "tokensReused",
+              value: s.tokensReused,
+              hint: "Sum of matchLen: prefix tokens the worker matched and did not re-lex",
+              readOnly: true
+            },
+            {
+              label: "tokensRelexed",
+              value: s.tokensRelexed,
+              hint: "Sum of returned tail lengths: tokens the worker had to re-lex",
+              readOnly: true
+            },
+            {
+              label: "reuseRatio",
+              value: Math.round(reuseRatio * 1e3) / 1e3,
+              hint: "reused / (reused + relexed). Near 1 is healthy; near 0 means no reuse",
+              readOnly: true
+            }
+          ]
+        }
+      ],
+      notes: s.workerResponses === 0 && s.appends > 0 ? [
+        "No worker responses yet: either the worker is unavailable and parsing ran synchronously on the main thread, or the first request is still in flight."
+      ] : reuseRatio > 0 && reuseRatio < 0.5 ? [
+        `Only ${Math.round(reuseRatio * 100)}% of lexed tokens were reused, so most of the document is being re-lexed per chunk. Expect O(document) work per append.`
+      ] : void 0
+    };
+  }
   /** Enable or disable native selection for existing and future Markdown text. */
   setSelectable(selectable) {
     this.selectable = selectable;
@@ -824,6 +955,7 @@ var Markdown = class extends import_ui.UIComponent {
   /** Append a markdown chunk incrementally. Reuses unchanged prefix entities. */
   appendMarkdown(chunk) {
     this.rawMarkdown += chunk;
+    this.streamStats.appends++;
     if (!markdownWorker) {
       const newTokens = import_marked.marked.lexer(this.rawMarkdown);
       this.updateTokens(newTokens);
@@ -858,6 +990,9 @@ var Markdown = class extends import_ui.UIComponent {
     workerCallbacks.set(id, {
       cb: (matchLen, tail) => {
         this.pendingWorkerIds.delete(id);
+        this.streamStats.workerResponses++;
+        this.streamStats.tokensReused += matchLen;
+        this.streamStats.tokensRelexed += tail.length;
         this.appendInFlight = false;
         const newTokens = [...oldTokensSnapshot.slice(0, matchLen), ...tail];
         this.updateTokens(newTokens, matchLen);
@@ -1225,5 +1360,7 @@ var Markdown = class extends import_ui.UIComponent {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CodeBlock,
-  Markdown
+  Markdown,
+  codeAtlas,
+  codeAtlasStats
 });

package/dist/index.mjs

@@ -2,6 +2,7 @@
 import {
   BidiResolver,
   Entity,
+  GlyphRasterAtlas,
   prepareContentGrid,
   SVGEntity
 } from "@vectojs/core";
@@ -531,6 +532,9 @@ var CodeBlock = class extends UIComponent {
     r.roundRect(0, 0, this.width, this.height, 8);
     r.fill(this.theme.codeBgColor);
     const grid = this.ensureGrid();
+    const atlas = codeGlyphAtlas(r);
+    const atlasSource = atlas?.source ?? null;
+    const blit = atlas ? r.drawImageRect : void 0;
     for (let row = 0; row < grid.lines.length; row++) {
       const yBaseline = this.pad + row * this.lineH + this.lineH * 0.75;
       const segments = this.lines[row];
@@ -545,17 +549,51 @@ var CodeBlock = class extends UIComponent {
         }
         const sourceText = this.source.slice(cell.sourceStart, cell.sourceEnd);
         if (cell.advance <= 0 || sourceText === " " || sourceText === "	") continue;
-        r.fillText(
-          cell.glyph,
-          this.pad + cell.x,
-          yBaseline,
-          this.codeFont,
-          segments[segmentIndex]?.color ?? this.theme.codeColor
-        );
+        const color = segments[segmentIndex]?.color ?? this.theme.codeColor;
+        const x = this.pad + cell.x;
+        if (blit && atlas) {
+          const slot = atlas.get(this.codeFont, color, cell.glyph);
+          const src = atlasSource ?? atlas.source;
+          if (slot && src) {
+            blit.call(
+              r,
+              src,
+              slot.sx,
+              slot.sy,
+              slot.sw,
+              slot.sh,
+              x - slot.offsetX,
+              yBaseline - slot.offsetY,
+              slot.w,
+              slot.h
+            );
+            continue;
+          }
+        }
+        r.fillText(cell.glyph, x, yBaseline, this.codeFont, color);
       }
     }
   }
 };
+var sharedCodeAtlas = null;
+function codeGlyphAtlas(r) {
+  if (typeof r.drawImageRect !== "function") return void 0;
+  if (typeof document === "undefined") return void 0;
+  sharedCodeAtlas ??= new GlyphRasterAtlas({
+    // Match the display so a HiDPI blit stays crisp. Capped at 3 because atlas
+    // area grows with dpr² and a 4x display would otherwise blow the size cap
+    // with a few hundred glyphs.
+    dpr: typeof window !== "undefined" ? Math.min(window.devicePixelRatio || 1, 3) : 1,
+    maxSize: 2048
+  });
+  return sharedCodeAtlas;
+}
+function codeAtlasStats() {
+  return sharedCodeAtlas ? sharedCodeAtlas.stats : null;
+}
+function codeAtlas() {
+  return sharedCodeAtlas;
+}
 function decodeEntities(text) {
   return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
 }
@@ -695,6 +733,23 @@ var Markdown = class extends UIComponent {
   // with the latest accumulated text once it resolves.
   appendInFlight = false;
   appendPending = false;
+  /**
+   * Streaming counters for the DevTools inspector.
+   *
+   * Cheap enough to keep always-on (four integer increments per append) and the
+   * only way to see, from outside, whether incremental reuse is actually working:
+   * a stable-prefix ratio near 1 means the worker is matching almost everything
+   * and only the tail is re-lexed, while a ratio near 0 means every chunk is
+   * re-parsing the whole document.
+   */
+  streamStats = {
+    appends: 0,
+    workerResponses: 0,
+    /** Sum of `matchLen` across responses, i.e. tokens reused rather than re-lexed. */
+    tokensReused: 0,
+    /** Sum of returned tail lengths, i.e. tokens the worker had to re-lex. */
+    tokensRelexed: 0
+  };
   // Worker request ids dispatched by *this* instance that haven't resolved yet.
   // The module-level `workerCallbacks` map holds a closure capturing `this`, so
   // destroying a Markdown mid-stream would pin the whole entity (and its subtree)
@@ -787,6 +842,81 @@ var Markdown = class extends UIComponent {
     });
     super.destroy();
   }
+  /**
+   * Streaming and parse state — the markdown streaming inspector.
+   *
+   * Source length, chunk count, worker in-flight state, and the stable-prefix
+   * versus re-lexed-tail split. That last ratio is the one worth watching: it is
+   * how you tell incremental reuse is working from outside, and nothing else
+   * surfaces it. A ratio near 1 means the worker matched almost the whole prefix
+   * and only re-lexed the tail; near 0 means every chunk re-parses the document.
+   */
+  getDevtoolsDescriptor() {
+    const s = this.streamStats;
+    const lexed = s.tokensReused + s.tokensRelexed;
+    const reuseRatio = lexed > 0 ? s.tokensReused / lexed : 0;
+    return {
+      kind: "Markdown",
+      groups: [
+        {
+          label: "Source",
+          fields: [
+            { label: "sourceLength", value: this.rawMarkdown.length, readOnly: true },
+            { label: "topLevelTokens", value: this.tokens.length, readOnly: true },
+            { label: "childEntities", value: this.content.children.length, readOnly: true },
+            { label: "selectable", value: this.selectable }
+          ]
+        },
+        {
+          label: "Streaming",
+          fields: [
+            { label: "appends", value: s.appends, readOnly: true },
+            {
+              label: "workerResponses",
+              value: s.workerResponses,
+              hint: "Fewer than appends means chunks were coalesced while a request was in flight",
+              readOnly: true
+            },
+            {
+              label: "appendInFlight",
+              value: this.appendInFlight,
+              hint: "One lex request at a time; the delta protocol requires it",
+              readOnly: true
+            },
+            { label: "appendPending", value: this.appendPending, readOnly: true }
+          ]
+        },
+        {
+          label: "Incremental reuse",
+          fields: [
+            {
+              label: "tokensReused",
+              value: s.tokensReused,
+              hint: "Sum of matchLen: prefix tokens the worker matched and did not re-lex",
+              readOnly: true
+            },
+            {
+              label: "tokensRelexed",
+              value: s.tokensRelexed,
+              hint: "Sum of returned tail lengths: tokens the worker had to re-lex",
+              readOnly: true
+            },
+            {
+              label: "reuseRatio",
+              value: Math.round(reuseRatio * 1e3) / 1e3,
+              hint: "reused / (reused + relexed). Near 1 is healthy; near 0 means no reuse",
+              readOnly: true
+            }
+          ]
+        }
+      ],
+      notes: s.workerResponses === 0 && s.appends > 0 ? [
+        "No worker responses yet: either the worker is unavailable and parsing ran synchronously on the main thread, or the first request is still in flight."
+      ] : reuseRatio > 0 && reuseRatio < 0.5 ? [
+        `Only ${Math.round(reuseRatio * 100)}% of lexed tokens were reused, so most of the document is being re-lexed per chunk. Expect O(document) work per append.`
+      ] : void 0
+    };
+  }
   /** Enable or disable native selection for existing and future Markdown text. */
   setSelectable(selectable) {
     this.selectable = selectable;
@@ -802,6 +932,7 @@ var Markdown = class extends UIComponent {
   /** Append a markdown chunk incrementally. Reuses unchanged prefix entities. */
   appendMarkdown(chunk) {
     this.rawMarkdown += chunk;
+    this.streamStats.appends++;
     if (!markdownWorker) {
       const newTokens = marked.lexer(this.rawMarkdown);
       this.updateTokens(newTokens);
@@ -836,6 +967,9 @@ var Markdown = class extends UIComponent {
     workerCallbacks.set(id, {
       cb: (matchLen, tail) => {
         this.pendingWorkerIds.delete(id);
+        this.streamStats.workerResponses++;
+        this.streamStats.tokensReused += matchLen;
+        this.streamStats.tokensRelexed += tail.length;
         this.appendInFlight = false;
         const newTokens = [...oldTokensSnapshot.slice(0, matchLen), ...tail];
         this.updateTokens(newTokens, matchLen);
@@ -1202,5 +1336,7 @@ var Markdown = class extends UIComponent {
 };
 export {
   CodeBlock,
-  Markdown
+  Markdown,
+  codeAtlas,
+  codeAtlasStats
 };

package/package.json

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