@vectojs/markdown 0.22.0 → 0.23.1

package/README.md

@@ -1,243 +1,71 @@
 # @vectojs/markdown
 
-Canvas-native Markdown (with TeX math) rendering for [VectoJS](https://github.com/vectojs/vectojs).
-
-`Markdown` is a high-level entity that parses Markdown with
-[`marked`](https://marked.js.org/), renders TeX math to SVG with
-`@vectojs/tex`, and lays the result out using `@vectojs/ui` components
-(`RichText`, `Stack`, `Table`, `Text`, `Image`). It also exports `CodeBlock`.
-
-This package was split out of `@vectojs/ui` so that the heavy `marked` +
-`@vectojs/tex` dependencies are only pulled in by apps that actually render
-Markdown. Because it depends on `@vectojs/ui` components, it sits **above** `ui`
-in the dependency graph — install it alongside `@vectojs/ui` and `@vectojs/core`.
+`@vectojs/markdown` renders Markdown (with TeX math) as a canvas-native entity tree: the
+`Markdown` entity parses with `marked`, typesets math through `@vectojs/tex`, and lays the result
+out using `@vectojs/ui` components. It was split out of `@vectojs/ui` precisely so the heavy
+`marked` + `@vectojs/tex` dependencies load only for apps that render documents — it sits **above**
+`ui` in the dependency graph and takes `@vectojs/core` and `@vectojs/ui` as peer dependencies.
 
 ## Install
 
-```sh
+```bash
 bun add @vectojs/markdown @vectojs/ui @vectojs/core
 ```
 
-## Usage
-
-```ts
-import { Markdown } from "@vectojs/markdown";
-
-const md = new Markdown("# Hello\n\nInline math $E = mc^2$.");
-scene.add(md);
-```
-
-## Streaming
+Peers: `@vectojs/core >=1.34.0 <2`, `@vectojs/ui >=2.6.0 <3`.
 
-`createStream()` coalesces accepted chunks into at most one Markdown
-parse/layout commit per animation frame. `write()` applies backpressure when its
-bounded buffer is full; await it when consuming an async token source.
-
-```ts
-const md = new Markdown("");
-scene.add(md);
-
-const stream = md.createStream();
-for await (const token of tokens) {
-  await stream.write(token);
-}
-// Commits the final text, then waits for the parse to be applied — once this
-// resolves, the rendered document reflects everything written.
-await stream.close();
-```
-
-Add fixed-rate typewriter pacing without changing producer code:
-
-```ts
-const stream = md.createStream({
-  pacing: { graphemesPerSecond: 48 },
-  maxBufferedChars: 64 * 1024,
-  signal: abortController.signal,
-});
-```
-
-Pacing slices by grapheme cluster, so combining marks, emoji ZWJ sequences,
-flags, and surrogate pairs stay intact across ordinary chunk/frame boundaries.
-`abort()` discards uncommitted text; `Markdown.destroy()` does the same cleanup
-automatically. The existing `appendMarkdown()` API remains synchronous and
-flushes submitted controller text before a direct append.
-
-### Incomplete Markdown while streaming
-
-Mid-stream, the trailing text of a paragraph is often an unclosed inline
-construct — `**bo`, `` `cod ``, `[text](url`. `marked` has no signal that more
-characters are coming, so it lexes those as plain text. `incompleteMode` chooses
-what you show in the meantime:
+## Usage
 
 ```ts
-const stream = md.createStream({ incompleteMode: "optimistic" });
-```
-
-| Mode                  | Unclosed `**bo` renders as           |
-| --------------------- | ------------------------------------ |
-| `'literal'` (default) | `**bo` — the literal characters      |
-| `'optimistic'`        | **bo** — guessed bold, syntax hidden |
-
-`'optimistic'` covers strong, emphasis, and inline code. An unclosed link shows
-its label as plain text: with no closing `)` there is no URL yet, so nothing is
-made clickable. Only the document's **last paragraph** is ever guessed at, and
-only while the stream is open — headings, list items, table cells, and any
-earlier paragraph are always literal.
+import { Scene } from '@vectojs/core';
+import { Markdown } from '@vectojs/markdown';
 
-The guess is display-only. `Markdown.tokens` is never affected, and `close()`
-unwinds it, so a `'literal'` and an `'optimistic'` stream of the same source end
-at an identical document. `'literal'` remains the default: it is what every prior
-release rendered.
+const scene = new Scene(document.querySelector<HTMLCanvasElement>('canvas')!);
+scene.renderMode = 'onDemand';
 
-### Knowing when the document is final
-
-`onStable` fires once, after `close()` has committed the last chunk _and_ the
-parse has been applied. Use it for one-time work you do not want repeated against
-content still in flight:
-
-```ts
-const stream = md.createStream({
-  onStable: (blocks) => {
-    for (const block of blocks) fadeIn(block);
+const md = new Markdown('# Hello\n\nInline math $E = mc^2$.', {
+  maxWidth: 640,
+  theme: 'githubDark', // or a full MarkdownTheme object
+  onLinkClick(href) {
+    console.log('navigate', href);
   },
 });
-```
-
-It never fires on `flush()`, `abort()`, or `destroy()` — none of those mean the
-content stopped changing. It receives a snapshot array, not a live reference.
-Calling `appendMarkdown()` or `setContent()` from inside the callback throws; a
-throw from the callback rejects the `close()` promise. `onStable` is independent
-of `incompleteMode` and works with the `'literal'` default.
-
-### Streamed TeX math
-
-A fenced math block is typeset only once its closing fence arrives:
+scene.add(md.setPosition(24, 24));
 
-````md
-```math
-\int_0^1 x\,dx = \frac{1}{2}
+// Stream LLM output: chunks coalesce into one parse per frame.
+const stream = md.createStream({ incompleteMode: 'optimistic' });
+stream.write('# Ti');
+await stream.close(); // resolves after the final parse is applied
 ```
-````
-
-While the fence is still open the block renders as an ordinary code block showing
-the TeX source, then becomes the formula on the chunk that closes it. This is
-deliberate. `marked` lexes an unterminated fence as a _complete_ token as soon as
-it reads the info string, so a formula streamed a few characters at a time
-arrives as a long run of whole tokens, nearly all of them invalid TeX — typesetting
-each one spends the most expensive call in this package rendering an error glyph
-that is replaced by the next chunk. Showing the source is both cheaper and more
-honest: the formula genuinely is not finished.
-
-Converted formulas are cached (bounded, process-wide), so a repeated formula is
-converted once no matter how many documents or instances render it.
-
-Inline `$...$` math is a separate path: it is currently shown as styled source
-text, not typeset.
-
-#### The math engine is loaded on demand
-
-TeX math is typeset by `@vectojs/tex`, which is imported dynamically the first
-time a document actually has a formula. It is by far the heaviest thing this
-package can pull in — measured against a browser bundle of a consumer that renders
-only prose, built with code splitting and minification:
-
-| prose-only consumer    |       raw |    gzip | chunks |
-| ---------------------- | --------: | ------: | -----: |
-| `mathjax-full`         | 2,199,869 | 748,713 |     19 |
-| `@vectojs/tex` (now)   |   758,249 | 273,754 |      3 |
-| no math at all (floor) |   379,224 | 118,670 |      3 |
-
-Against that floor the math path itself is 630,043 gzip under `mathjax-full` and
-155,033 under `@vectojs/tex` — **4.06x smaller**. The eagerly-downloaded entry
-chunk a prose-only consumer actually pays for is 117,889 gzip, within 1 KB of the
-no-math floor.
-
-Your bundler needs code splitting enabled to see this; without it the bytes are
-still in the output, just not evaluated until first use.
-
-The tradeoff is that **the first formula on a page cannot be typeset
-synchronously.** It renders as a code block of TeX source — the same state an
-unclosed fence already shows — and is replaced once the module resolves. Every
-formula after that is synchronous again. (The engine itself is synchronous; the
-lazy import is what defers it, and it is kept for the bundle size above.)
-
-While streaming this is invisible: the load starts as soon as an _opening_ math
-fence appears, several chunks before the closing one, so the formula is typeset on
-the chunk that closes it. `await stream.close()` and `onStable` also wait for a
-pending load, so a "final" document never hands you an untypeset formula.
-
-If you need the very first formula typeset in the same tick — measuring layout
-immediately after construction, for instance — preload it:
-
-````ts
-import { Markdown, preloadMathJax } from "@vectojs/markdown";
-
-await preloadMathJax();
-const md = new Markdown("```math\n\\int_0^1 x\\,dx\n```"); // typeset synchronously
-````
-
-`preloadMathJax()` is idempotent and shared across every document, so calling it
-from several places starts one load. `isMathJaxReady()` reports whether formulas
-currently typeset without waiting. If the load fails, formulas keep rendering as
-TeX source rather than throwing.
-
-Both names are historical: they date from when `mathjax-full` was the engine and
-mean "the math engine", whichever one that is. They keep those names because they
-are public API and a rename would break every consumer for cosmetics.
-
-A formula containing a symbol outside the engine's shipped glyph corpus also
-renders as TeX source rather than being drawn with that symbol missing.
-
-## Images
-
-An image renders in one of two ways, decided by where it is written.
-
-**On its own, or in a paragraph, blockquote or list item**, the paragraph splits
-into blocks and the image becomes an `Image` entity at its natural size, capped
-to the available width. This is the ordinary `![alt](url)` case.
-
-**On a line it shares with text** — in a heading, or in a table cell — it renders
-as an inline box in the text run, so the prose flows around it and selection and
-the accessible name still work. Its height is a multiple of the run's font size
-(`theme.inlineImageScale`, default `1.15`) and its width follows the image's
-natural aspect ratio, so a badge stays wide and a square icon stays square:
-
-```ts
-const md = new Markdown("# Build ![passing](https://img.example/badge.svg)");
-```
-
-This is a deliberate departure from HTML, which would render an inline image at
-its intrinsic size. A 512px logo written into an `h1` would otherwise tower over
-its own heading, and an inline box has to be sized before the image has decoded.
-The height is fixed up front for the same reason: the line box never moves, and
-only the width settles once the aspect ratio is known.
-
-The `alt` text is the accessible name and the copied text — never painted as
-visible prose. If the image fails to load, the box is replaced by the alt text
-rather than left as an invisible gap.
-
-## Syntax coverage
-
-Everything in [CommonMark](https://spec.commonmark.org/) plus the
-[GFM](https://github.github.com/gfm/) extensions this renderer draws: tables,
-strikethrough, task lists, autolinks, plus `$…$` / `$$…$$` TeX math and
-` ```math ` fences.
-
-Two constructs are deliberately **not** supported, and both are pinned by tests
-so the behaviour cannot drift silently:
-
-- **Definition lists.** `Term` then `: definition` renders as the two literal
-  lines the source contains, colon included.
-- **Raw HTML blocks.** `<details>`, `<div>`, `<iframe>` and HTML comments render
-  nothing at all.
-
-Definition lists are neither CommonMark nor GFM; when they arrive it will be
-through the same syntax-extension mechanism footnotes need. Raw HTML blocks
-cannot work in a zero-DOM renderer — there is no DOM to hand markup to. `<svg>`
-is the one exception, because a self-contained SVG document can be rasterized.
-
-Footnotes (`[^1]`) are **not yet parsed** and currently render as literal source.
 
-> Migrating from `@vectojs/ui` ≤ 1.x? `Markdown` and `CodeBlock` used to be
-> exported from `@vectojs/ui`. As of `@vectojs/ui@2.0.0` they live here — change
-> `import { Markdown } from '@vectojs/ui'` to `from '@vectojs/markdown'`.
+## Highlights
+
+- CommonMark plus GFM tables, strikethrough, task lists, and autolinks; paragraphs become
+  `RichText`, fences become `CodeBlock`, GFM tables become `Table`.
+- Frame-coalesced streaming via `createStream()`: at most one parse/layout commit per animation
+  frame, grapheme-cluster-safe typewriter pacing (`graphemesPerSecond`), bounded-buffer
+  backpressure on `write()`, `onStable` firing once when the document is final, and an
+  `incompleteMode` of `'literal'` (default) or `'optimistic'` for unclosed markers mid-stream.
+- TeX math through `@vectojs/tex`, dynamically imported on the first formula so prose-only bundles
+  stay small; `preloadMathJax()` / `isMathJaxReady()` control the lazy load, converted formulas are
+  cached process-wide, and fenced math blocks typeset only once their closing fence arrives.
+- Themes: constructor accepts a preset name (`'githubDark' | 'githubLight' | 'dracula' |
+'solarizedDark' | 'solarizedLight'`) or a full theme object; post-construction changes go through
+  `setTheme()` — `theme` itself is getter-only (#657).
+- Selectable content: rendered text projects browser-native drag selection, copy, and find-in-page;
+  toggle at runtime with `setSelectable(false)`.
+- Block affordances: opt-in copy/download controls on code blocks and tables with injectable
+  `writeClipboard` / `saveFile`, per-kind overrides, and CSV export helpers (`tableToCsv`,
+  `tableToMarkdown`).
+- Front matter: `scanFrontMatter` / `parseFrontMatterFields` expose YAML-ish metadata before the
+  document body renders.
+- Large-document virtualization: pass `virtualize` and drive `setVisibleRange(scrollY, viewportHeight)`
+  to materialize only top-level blocks near the viewport.
+
+> Documents @vectojs/markdown@0.23.0.
+
+## Documentation
+
+- [Markdown reference](https://vectojs.org/reference/ui-markdown/)
+- [CodeBlock reference](https://vectojs.org/reference/ui-codeblock/)
+- [Streaming guide](https://vectojs.org/learn/streaming/)

package/dist/Markdown.d.ts

@@ -150,7 +150,38 @@ export interface MarkdownOptions {
 export declare class Markdown extends UIComponent {
     content: Stack;
     maxWidth: number;
-    theme: Required<MarkdownTheme>;
+    /**
+     * Resolved once in the constructor and never re-applied: entities capture
+     * colors, fonts and sizes at build time, so assigning this after construction
+     * would paint blocks built afterwards in the new palette while everything
+     * earlier kept the old one. Exposed read-only to keep that trap unreachable
+     * (#657); the supported post-construction path is {@link setTheme}, which
+     * re-renders instead of leaving blocks half-migrated.
+     *
+     * Backed by {@link currentTheme} rather than a `readonly` field because the
+     * blockquote arm legally swaps the render-time theme for its own subtree and
+     * restores it afterwards — an internal, exception-safe scope, not a re-theme.
+     */
+    get theme(): Required<MarkdownTheme>;
+    private currentTheme;
+    /**
+     * Swap the document theme and rebuild every rendered block.
+     *
+     * Accepts the same shapes as {@link MarkdownOptions.theme}: a preset name or
+     * a full/partial {@link MarkdownTheme}, resolved through
+     * {@link resolvePresetTheme}. This is the only supported way to change theme
+     * after construction — {@link theme} is a read-only view (#657) precisely so
+     * tokens cannot be swapped underneath already-built blocks without the
+     * rebuild performed here.
+     *
+     * The rebuild goes through {@link setContent} rather than an in-place
+     * repaint: entities capture colors and fonts at build time, so nothing short
+     * of re-rendering applies a palette, and an active stream needs the same
+     * teardown an explicit content replacement gets.
+     *
+     * @returns `this` for chaining.
+     */
+    setTheme(theme: MarkdownThemePresetName | MarkdownTheme): this;
     onLinkClick?: (url: string) => void;
     selectable: boolean;
     /**
@@ -535,12 +566,6 @@ export declare class Markdown extends UIComponent {
     private refitParagraphImage;
     /** Replace all markdown content (full rebuild). */
     setContent(markdown: string): this;
-    /**
-     * Tear down this Markdown block: drop any in-flight worker callbacks (each
-     * pins `this` via its closure, so a mid-stream destroy would otherwise keep
-     * the whole subtree alive until the worker replied), then recurse into the
-     * content subtree via `super.destroy()` so every block's resources are freed.
-     */
     /**
      * Repaint this document when an inline formula's raster finishes decoding.
      *
@@ -591,6 +616,12 @@ export declare class Markdown extends UIComponent {
      * this predicate.
      */
     private inlineImageBoxesStale;
+    /**
+     * Tear down this Markdown block: drop any in-flight worker callbacks (each
+     * pins `this` via its closure, so a mid-stream destroy would otherwise keep
+     * the whole subtree alive until the worker replied), then recurse into the
+     * content subtree via `super.destroy()` so every block's resources are freed.
+     */
     destroy(): void;
     /**
      * Streaming and parse state — the markdown streaming inspector.
@@ -643,30 +674,6 @@ export declare class Markdown extends UIComponent {
      * guess is unwound back to.
      */
     private literalParagraphSpans;
-    /**
-     * Update a reused blockquote's tail child in place, or report that it cannot be.
-     *
-     * The render arm builds `container[border, innerStack]` where every inner block
-     * sits in its own single-child `wrapper`, so the tail entity is
-     * `innerStack.children.at(-1).children[0]`. Only the LAST inner block may be
-     * updated: the inner token list is prefix-stable exactly like the top level (a
-     * growing quote keeps its earlier blocks byte-identical), so anything before the
-     * tail is untouched and anything more complicated than a changed tail falls back
-     * to the caller's rebuild.
-     *
-     * Returns `false` without mutating anything when the shape is not the simple
-     * grow-the-tail case, which is the signal for the caller to rebuild. Every early
-     * return has to leave the entity untouched, or a rejected reuse would leave a
-     * half-updated quote on screen.
-     */
-    /**
-     * Build one list item's spans: inline content plus its marker.
-     *
-     * Shared by the `list` render arm and the streamed-reuse path below, because
-     * the two must produce byte-identical spans — a reused list that disagreed with
-     * a rebuilt one about its marker or its entity decoding would make a streamed
-     * document differ from the same source pasted at once.
-     */
     /**
      * Inline spans for one table cell.
      *
@@ -697,6 +704,28 @@ export declare class Markdown extends UIComponent {
     private inlineRunSpans;
     /** One text run of an image-bearing paragraph, as both paths build it. */
     private inlineRunRichText;
+    /**
+     * Wraps a block in its copy / download controls, or returns it untouched.
+     *
+     * The controls are built lazily through `make` so a document with
+     * `blockAffordances` off pays nothing — not the closures, not the measurement
+     * `BlockAffordanceButton` does in its constructor.
+     */
+    private withBlockAffordances;
+    /** Copy and download controls for one fenced code block, per {@link affordanceConfig}. */
+    private codeBlockAffordances;
+    /** Copy (as Markdown) and download (as CSV) controls for one table, per {@link affordanceConfig}. */
+    private tableAffordances;
+    /**
+     * Button styling for the affordances, derived from the document theme.
+     *
+     * Themed rather than hardcoded so a light-theme document does not get the dark
+     * default palette. `focusColor` is set explicitly from the theme's accent
+     * because `Button`'s default cyan is tuned for the dark palette and reads as
+     * off-brand elsewhere — while a focus ring is the one affordance a keyboard
+     * user cannot do without.
+     */
+    private affordanceButtonOptions;
     /**
      * One image inside a paragraph, sized by a guess until its bitmap decodes.
      *
@@ -722,28 +751,6 @@ export declare class Markdown extends UIComponent {
      * policy for a zero-dimension source is a separate decision from notifying
      * the scene, which is the actual defect here.
      */
-    /**
-     * Wraps a block in its copy / download controls, or returns it untouched.
-     *
-     * The controls are built lazily through `make` so a document with
-     * `blockAffordances` off pays nothing — not the closures, not the measurement
-     * `BlockAffordanceButton` does in its constructor.
-     */
-    private withBlockAffordances;
-    /** Copy and download controls for one fenced code block, per {@link affordanceConfig}. */
-    private codeBlockAffordances;
-    /** Copy (as Markdown) and download (as CSV) controls for one table, per {@link affordanceConfig}. */
-    private tableAffordances;
-    /**
-     * Button styling for the affordances, derived from the document theme.
-     *
-     * Themed rather than hardcoded so a light-theme document does not get the dark
-     * default palette. `focusColor` is set explicitly from the theme's accent
-     * because `Button`'s default cyan is tuned for the dark palette and reads as
-     * off-brand elsewhere — while a focus ring is the one affordance a keyboard
-     * user cannot do without.
-     */
-    private affordanceButtonOptions;
     private paragraphImage;
     /**
      * Re-position every block after an image whose decode corrected its box.
@@ -859,6 +866,14 @@ export declare class Markdown extends UIComponent {
      * bullet or ordinal.
      */
     private listItemBlockStack;
+    /**
+     * Build one list item's spans: inline content plus its marker.
+     *
+     * Shared by the `list` render arm and the streamed-reuse path below, because
+     * the two must produce byte-identical spans — a reused list that disagreed with
+     * a rebuilt one about its marker or its entity decoding would make a streamed
+     * document differ from the same source pasted at once.
+     */
     private listItemSpans;
     /** Construct the `RichText` for one list item. */
     private listItemRichText;
@@ -950,6 +965,22 @@ export declare class Markdown extends UIComponent {
      * (its keys are `text`/`tokens`/`header`/`align`).
      */
     private updateStreamedTable;
+    /**
+     * Update a reused blockquote's tail child in place, or report that it cannot be.
+     *
+     * The render arm builds `container[border, innerStack]` where every inner block
+     * sits in its own single-child `wrapper`, so the tail entity is
+     * `innerStack.children.at(-1).children[0]`. Only the LAST inner block may be
+     * updated: the inner token list is prefix-stable exactly like the top level (a
+     * growing quote keeps its earlier blocks byte-identical), so anything before the
+     * tail is untouched and anything more complicated than a changed tail falls back
+     * to the caller's rebuild.
+     *
+     * Returns `false` without mutating anything when the shape is not the simple
+     * grow-the-tail case, which is the signal for the caller to rebuild. Every early
+     * return has to leave the entity untouched, or a rejected reuse would leave a
+     * half-updated quote on screen.
+     */
     private updateBlockquoteTail;
     /**
      * Spans for a heading being updated in place.
@@ -979,13 +1010,6 @@ export declare class Markdown extends UIComponent {
     private optimisticParagraphSpans;
     /** Display style for a guessed-closed construct. */
     private optimisticStyle;
-    /**
-     * Re-render the paragraph currently showing a guess from its own tokens, with
-     * no overlay, and forget it.
-     *
-     * Idempotent and free when no guess is live, which is what lets `close()`,
-     * `abort()`, and a mid-stream staleness check all call it unconditionally.
-     */
     /**
      * Start the MathJax load, and re-typeset this document once it resolves.
      *
@@ -1023,6 +1047,13 @@ export declare class Markdown extends UIComponent {
      * stream is still open the next chunk re-applies a guess.
      */
     private retypesetFromTokens;
+    /**
+     * Re-render the paragraph currently showing a guess from its own tokens, with
+     * no overlay, and forget it.
+     *
+     * Idempotent and free when no guess is live, which is what lets `close()`,
+     * `abort()`, and a mid-stream staleness check all call it unconditionally.
+     */
     private unwindOptimisticTail;
     /**
      * Drop a guess that is no longer on the document's trailing paragraph.