@vectojs/markdown 0.14.0 → 0.15.0

package/README.md

@@ -4,12 +4,11 @@ Canvas-native Markdown (with TeX math) rendering for [VectoJS](https://github.co
 
 `Markdown` is a high-level entity that parses Markdown with
 [`marked`](https://marked.js.org/), renders TeX math to SVG with
-[MathJax](https://www.mathjax.org/), and lays the result out using
-`@vectojs/ui` components (`RichText`, `Stack`, `Table`, `Text`, `Image`). It also
-exports `CodeBlock`.
+`@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` +
-`mathjax-full` dependencies are only pulled in by apps that actually render
+`@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`.
 
@@ -135,26 +134,32 @@ 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.
 
-#### MathJax is loaded on demand
+#### The math engine is loaded on demand
 
-MathJax is imported dynamically, the first time a document actually has a formula
-to typeset. It is by far the heaviest thing this package can pull in — measured
-against a browser bundle of a consumer that renders only prose:
+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 |
-| ------------------------- | --------: | ------: |
-| eagerly imported (before) | 2,157,295 | 725,012 |
-| lazily imported (now)     |   339,767 | 106,095 |
+| 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 |
 
-That is 85% of the bundle a document with no formulas used to carry, plus roughly
-150 ms of module evaluation at startup. Your bundler needs code splitting enabled
-to see this; without it the bytes are still in the output, just not evaluated
-until first use.
+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.
+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
@@ -176,6 +181,63 @@ 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'`.

package/dist/Markdown.d.ts

@@ -1,159 +1,11 @@
-import { type ContentProjectionHint, Entity, type DevtoolsDescriptor, GlyphRasterAtlas, type GlyphRasterAtlasStats, IRenderer, type ContentProjection } from '@vectojs/core';
+import { Entity, type DevtoolsDescriptor, IRenderer } from '@vectojs/core';
 import { type Token } from 'marked';
 import { type StreamController, type StreamControllerOptions } from './StreamController';
+export { isMathJaxReady, MathBlock, preloadMathJax } from './markdown-math';
+export { CodeBlock, codeAtlas, codeAtlasStats } from './markdown-code';
+import { type MarkdownTheme } from './theme';
+export type { MarkdownTheme } from './theme';
 import { Stack, UIComponent } from '@vectojs/ui';
-export declare function preloadMathJax(): Promise<void>;
-/** Whether formulas can be typeset without waiting. Exposed for tests. */
-export declare function isMathJaxReady(): boolean;
-/** Color and typography theme for Markdown rendering. */
-export interface MarkdownTheme {
-    /** Body text color. */
-    textColor?: string;
-    /** Heading text color. */
-    headingColor?: string;
-    /** Code text color (inline + block). */
-    codeColor?: string;
-    /** Code block background color. */
-    codeBgColor?: string;
-    /** Blockquote border/accent color. */
-    quoteBorderColor?: string;
-    /** Blockquote text color. */
-    quoteTextColor?: string;
-    /** Horizontal-rule color. */
-    hrColor?: string;
-    /** Table background color. */
-    tableBgColor?: string;
-    /** Table header background color. */
-    tableHeaderBgColor?: string;
-    /** Body font. */
-    bodyFont?: string;
-    /** Monospace font for code. */
-    codeFont?: string;
-    /** Base font size in px. */
-    fontSize?: number;
-}
-/** A simple concrete container entity for nested layouts. */
-declare class MarkdownContainer extends Entity {
-    isPointInside(_globalX: number, _globalY: number): boolean;
-    render(_r: any): void;
-}
-/**
- * One display formula: a `$$..$$` block or a closed ```` ```math ```` fence.
- *
- * A named class rather than a bare {@link MarkdownContainer} because the formula
- * needs a stable handle, and after the switch to an inline object it has none:
- * the typeset raster lives in a `paint` closure captured by the span, so removing
- * the `Image` entity left nothing exposing either the source or the SVG bytes.
- * Devtools, tests, and anything auditing what a formula actually rendered all
- * want that. `markstream-vue` reaches the same conclusion from the DOM side and
- * publishes `data-markstream-mode` on its math node for the same reason.
- *
- * Deliberately carries no typeset-vs-source flag. A formula MathJax has not
- * converted yet renders as a bare {@link CodeBlock} of its TeX, which this class
- * does not wrap — wrapping it would put a container between `content` and a
- * `CodeBlock` that the streamed `setCode` path locates by type. So a flag would
- * have exactly one reachable value, which is the dead-API trap that cost CTX-0208
- * a debugging pass. Add it together with wrapping the fallback, or not at all.
- */
-export declare class MathBlock extends MarkdownContainer {
-    /**
-     * The TeX source, exactly as written between the delimiters.
-     *
-     * Also the projected text and the accessible name, so this is the one string a
-     * reader can find, select, and copy.
-     */
-    readonly formula: string;
-    /** The `data:image/svg+xml` URI of the typeset glyphs. */
-    readonly svgUri: string;
-    constructor(formula: string, svgUri: string);
-    getDevtoolsDescriptor(): DevtoolsDescriptor;
-}
-/**
- * A single self-rendering entity for fenced code blocks.
- *
- * Replaces the old N×M child-entity explosion (Container → Stack → Text per
- * segment per line) with a flat leaf that draws its own background + text.
- */
-export declare class CodeBlock extends UIComponent {
-    private lines;
-    private grid;
-    /** Raw (unhighlighted) lines of the last build, for prefix reuse in buildLines. */
-    private rawLines;
-    private cellWidth;
-    private source;
-    /** Bumped by {@link buildLines} and {@link setSelectable}; read by `Scene`. */
-    private contentEpoch;
-    private lang;
-    private theme;
-    private lineH;
-    private pad;
-    private codeFont;
-    selectable: boolean;
-    constructor(code: string, lang: string, maxWidth: number, theme: Required<MarkdownTheme>, selectable?: boolean);
-    /** Re-parse code content (e.g. for live editing). */
-    setCode(code: string, lang?: string): this;
-    /** Enable or disable browser-native selection for this code block. */
-    setSelectable(selectable: boolean): this;
-    getContentEpoch(): number;
-    /**
-     * Change the block's box width.
-     *
-     * Deliberately does **not** rebuild the grid or the highlight, because code does
-     * not reflow: lines are placed on a fixed monospace grid at `col × cellWidth` and
-     * a long line overflows rather than wrapping, so `height` is a function of line
-     * *count* alone. The width only sizes the rounded background. Anything that would
-     * change the glyph geometry — the source, the language, the font — goes through
-     * {@link setCode} and invalidates the grid there.
-     *
-     * @returns `this` for chaining.
-     */
-    setWidth(width: number): this;
-    getContentProjection(hint?: ContentProjectionHint): ContentProjection | null;
-    /**
-     * Re-highlight the code, reusing the highlight of any unchanged line prefix.
-     *
-     * Streaming appends to the END of a block, so all but the last line or two are
-     * byte-identical to the previous call — yet this used to re-highlight every
-     * line on every chunk, making a streamed block O(N) per append and O(N^2)
-     * overall. Reusing the stable prefix makes an append proportional to what
-     * actually changed.
-     *
-     * The last previously-seen line is deliberately NOT reused: a chunk usually
-     * lands mid-line, so that line's text (and therefore its tokenization) changes.
-     */
-    private buildLines;
-    private ensureGrid;
-    /** Code blocks are decorative — not interactive. */
-    isPointInside(): boolean;
-    render(r: IRenderer): void;
-}
-/**
- * Instrumentation for the code-block glyph atlas in use, 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.
- *
- * Reports the *most recently used* atlas, which after a zoom is the one now being
- * blitted — see {@link codeAtlas}.
- */
-export declare function codeAtlasStats(): GlyphRasterAtlasStats | null;
-/**
- * The code-block atlas most recently blitted from, 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.
- *
- * "Most recently used" rather than "the one" because atlases are pooled per DPR:
- * a caller resolving a traced blit wants the atlas that produced it, which is the
- * one the last render selected. Compare its {@link GlyphRasterAtlas.pixelRatio}
- * against {@link IRenderer.pixelRatio} to assert the blit is 1:1.
- */
-export declare function codeAtlas(): GlyphRasterAtlas | null;
 export interface MarkdownOptions {
     maxWidth?: number;
     theme?: MarkdownTheme;
@@ -300,6 +152,20 @@ export declare class Markdown extends UIComponent {
      * field only so {@link destroy} can remove the exact closure it added.
      */
     private inlineMathRepaint?;
+    /**
+     * This instance's entry in the inline-image decode waiters, or `undefined` if it
+     * has never rendered an image. Held as a field only so {@link destroy} can remove
+     * the exact closure it added.
+     */
+    private inlineImageRemeasure?;
+    /**
+     * URLs whose decoded aspect ratio this document has already reserved a box for.
+     *
+     * The guard that makes the re-measure fire once per image rather than once per
+     * decode-notification-per-image: the waiter set is module-level, so a page of
+     * many documents tells all of them about all decodes.
+     */
+    private readonly inlineImagesMeasured;
     /**
      * True while this document is waiting on the lazy MathJax load.
      *
@@ -487,6 +353,45 @@ export declare class Markdown extends UIComponent {
      * one closure per instance.
      */
     private subscribeInlineMathRepaint;
+    /**
+     * Re-measure this document when an inline image's raster finishes decoding.
+     *
+     * Inline images differ from inline formulas in one way that matters: a formula's
+     * box is known synchronously the moment it typesets, while an image's aspect
+     * ratio arrives only with the decode. The span reserved a square until then, so a
+     * decode that reports anything else has invalidated a WIDTH, and a repaint into
+     * the old box would letterbox or stretch the picture.
+     *
+     * So this rebuilds through {@link retypesetFromTokens} — the same late-arrival
+     * path MathJax uses — but only when a reserved width actually changed. Every live
+     * document is notified for every decode, including images it does not contain, so
+     * an unconditional rebuild here would be O(documents x images) full re-renders
+     * for a page of many blocks.
+     *
+     * Subscribed lazily and held as a field for the same two reasons as its math
+     * counterpart: a document with no images costs nothing, and `destroy` must remove
+     * the exact closure it added.
+     */
+    private subscribeInlineImageRemeasure;
+    /**
+     * Whether any inline image in this document has just learned it is not square.
+     *
+     * An inline image's span reserves a square box before its raster decodes, because
+     * that is the only shape available without a natural size. The decode supplies the
+     * real aspect ratio, so a non-square image needs one rebuild to reserve the right
+     * width — and exactly one. Every live document is notified of every decode on the
+     * page, including images it does not contain, so this has to answer "did MY
+     * geometry just change" and not merely "did something decode".
+     *
+     * Walks the tokens rather than the entity tree: the reserved box is a function of
+     * the raster's aspect ratio, which is available here, and a token walk cannot be
+     * confused by an entity a previous rebuild already corrected.
+     *
+     * Only headings and table cells are inspected. Every other context splits an image
+     * into its own block whose `Image` entity resizes itself in `onLoad`, so a rebuild
+     * for one of those would be pure cost.
+     */
+    private inlineImageBoxesStale;
     destroy(): void;
     /**
      * Streaming and parse state — the markdown streaming inspector.
@@ -949,4 +854,3 @@ export declare class Markdown extends UIComponent {
     /** Structural — children draw themselves. */
     render(_r: IRenderer): void;
 }
-export {};