@jarenjs/md 0.34.0

package/dist/types/scanner.d.ts

@@ -0,0 +1,240 @@
+/**
+ * @file Line-level scanners for the block parser.
+ *
+ * Pure, allocation-conscious functions that classify one (detabbed)
+ * line at a char-code level: does a construct start here, and where
+ * does its content begin? The parser in parser.js owns all state; this
+ * module owns none. Every regular expression is compiled once at
+ * module load — nothing in here builds a pattern per call.
+ */
+/**
+ * Thematic break: three or more `*`, `-` or `_` (same character),
+ * interleaved with spaces, nothing else on the line.
+ * @param {string} line
+ * @param {number} start first non-space offset
+ * @returns {boolean}
+ */
+export declare function scanThematicBreak(line: string, start: number): boolean;
+/**
+ * ATX heading: `#{1,6}` followed by space or end of line. Returns the
+ * depth and the heading text (closing `#` run stripped), or null.
+ * @param {string} line
+ * @param {number} start first non-space offset
+ * @returns {{ depth: number, text: string } | null}
+ */
+export declare function scanAtxHeading(line: string, start: number): {
+    depth: number;
+    text: string;
+} | null;
+/**
+ * Code fence opener: three or more backticks or tildes. A backtick
+ * fence's info string may not contain a backtick.
+ * @param {string} line
+ * @param {number} start first non-space offset
+ * @returns {{ marker: number, length: number, info: string } | null}
+ */
+export declare function scanFenceOpen(line: string, start: number): {
+    marker: number;
+    length: number;
+    info: string;
+} | null;
+/**
+ * Does this line close a fence opened with `marker` × `length`?
+ * @param {string} line
+ * @param {number} marker
+ * @param {number} length
+ * @returns {boolean}
+ */
+export declare function scanFenceClose(line: string, marker: number, length: number): boolean;
+/**
+ * Split a fence info string into `lang` (first word) and `meta` (the
+ * rest), resolving backslash escapes and character references in both.
+ * @param {string} info
+ * @returns {{ lang: string|null, meta: string|null }}
+ */
+export declare function splitFenceInfo(info: string): {
+    lang: string | null;
+    meta: string | null;
+};
+/**
+ * Blockquote marker at `offset`: `>` with an optional following space.
+ * Returns the content offset, or -1.
+ * @param {string} line
+ * @param {number} offset first non-space offset
+ * @returns {number}
+ */
+export declare function scanBlockquote(line: string, offset: number): number;
+/**
+ * List marker: `-`/`+`/`*` bullet or `1.`/`1)` ordered (start ≤ 9
+ * digits), followed by a space or line end. Returns the marker
+ * geometry the parser turns into a list container, or null.
+ * @param {string} line
+ * @param {number} start first non-space offset
+ * @returns {{ ordered: boolean, bullet: string, start: number,
+ *             delimiter: string, contentOffset: number } | null}
+ */
+export declare function scanListMarker(line: string, start: number): {
+    ordered: boolean;
+    bullet: string;
+    start: number;
+    delimiter: string;
+    contentOffset: number;
+} | null;
+/**
+ * Setext underline under an open paragraph: `=` run (depth 1) or `-`
+ * run (depth 2), possibly space-padded. Returns 0 when neither.
+ * @param {string} line
+ * @param {number} start first non-space offset
+ * @returns {number}
+ */
+export declare function scanSetextUnderline(line: string, start: number): number;
+/**
+ * GFM table delimiter row: cells of `---`, `:--`, `--:`, `:-:` split
+ * by pipes. Returns the alignment array, or null.
+ * @param {string} line
+ * @returns {(string|null)[] | null}
+ */
+export declare function scanTableDelimiter(line: string): (string | null)[] | null;
+/**
+ * Split a table row into raw cell strings on unescaped `|`, honoring
+ * `\|` and pipes inside backtick code spans. Leading and trailing
+ * empty cells from outer pipes are dropped. Returns null when the line
+ * contains no pipe at all.
+ * @param {string} line
+ * @returns {string[] | null}
+ */
+export declare function splitTableRow(line: string): string[] | null;
+/**
+ * Classify an HTML block opener at `start` (CommonMark types 1–7);
+ * 0 means no HTML block starts here. Type 7 is only valid when no
+ * paragraph is open — the caller passes `paragraphOpen`.
+ * @param {string} line
+ * @param {number} start first non-space offset
+ * @param {boolean} paragraphOpen
+ * @returns {number}
+ */
+export declare function scanHtmlBlockStart(line: string, start: number, paragraphOpen: boolean): number;
+/**
+ * Does this line end an HTML block of `kind`? Types 6/7 end on the
+ * following blank line (the parser checks that); types 1–5 end on a
+ * content condition, which may sit on the opening line itself.
+ * @param {number} kind
+ * @param {string} line
+ * @returns {boolean}
+ */
+export declare function scanHtmlBlockEnd(kind: number, line: string): boolean;
+/**
+ * Is this char code a space or tab?
+ * @param {number} c
+ * @returns {boolean}
+ */
+export declare function isSpaceCode(c: number): boolean;
+/**
+ * Link reference definition at the start of a closed paragraph's text:
+ * `[label]: destination "title"` (title optional, may be single-,
+ * double- or paren-quoted; destination may be `<>`-wrapped). Returns
+ * the definition and the offset after it, or null.
+ * @param {string} text the paragraph's raw text
+ * @param {number} pos
+ * @returns {{ label: string, url: string, title: string|null, end: number } | null}
+ */
+export declare function scanLinkDefinition(text: string, pos: number): {
+    label: string;
+    url: string;
+    title: string | null;
+    end: number;
+} | null;
+/**
+ * Scan a link destination at `pos`: `<...>` wrapped or a run of
+ * non-space characters with balanced parens.
+ * @param {string} text
+ * @param {number} pos
+ * @returns {{ url: string, end: number } | null}
+ */
+export declare function scanLinkDestination(text: string, pos: number): {
+    url: string;
+    end: number;
+} | null;
+/**
+ * Scan a link title at `pos`: `"..."`, `'...'` or `(...)`.
+ * @param {string} text
+ * @param {number} pos
+ * @returns {{ title: string, end: number } | null}
+ */
+export declare function scanLinkTitle(text: string, pos: number): {
+    title: string;
+    end: number;
+} | null;
+/** ASCII punctuation membership (emphasis flanking, backslash escapes). */
+export declare const ASCII_PUNCT: Uint8Array<ArrayBuffer>;
+/**
+ * Is this code point a whitespace character in the spec's sense?
+ * @param {number} point
+ * @returns {boolean}
+ */
+export declare function isUnicodeWhitespace(point: number): boolean;
+/**
+ * Is this code point a punctuation character in the spec's sense (P* or S*)?
+ * @param {number} point
+ * @returns {boolean}
+ */
+export declare function isUnicodePunctuation(point: number): boolean;
+/**
+ * The whole code point ending at `pos`, so a run preceded by an astral
+ * symbol classifies on the symbol and not on a surrogate half.
+ * @param {string} src @param {number} pos
+ * @returns {number}
+ */
+export declare function codePointBefore(src: string, pos: number): number;
+/**
+ * Normalize a link label for matching: trim, collapse internal
+ * whitespace runs to one space, and case fold.
+ *
+ * The fold is lower→upper→lower, not `toLowerCase()`: the spec asks for
+ * Unicode case folding, under which `ẞ` matches `SS`, while lower-casing
+ * alone maps `ẞ` to `ß` and never meets `ss`. The round trip routes both
+ * spellings through the same expansion (`ẞ`→`ß`→`SS`→`ss`, and `fi`→`fi`),
+ * which is as close to the full fold as a zero-dependency package gets
+ * without shipping the table.
+ * @param {string} label
+ * @returns {string}
+ */
+export declare function normalizeLabel(label: string): string;
+/**
+ * Footnote definition opener: `[^label]:` and the spaces after it.
+ * @param {string} line
+ * @param {number} start first non-space offset
+ * @returns {{ label: string, contentOffset: number } | null}
+ */
+export declare function scanFootnoteDefinition(line: string, start: number): {
+    label: string;
+    contentOffset: number;
+} | null;
+/**
+ * Footnote reference: `[^label]` in inline text.
+ * @param {string} text
+ * @param {number} start offset of the `[`
+ * @returns {{ label: string, end: number } | null}
+ */
+export declare function scanFootnoteReference(text: string, start: number): {
+    label: string;
+    end: number;
+} | null;
+/**
+ * Find every extended autolink in one text value (GFM §Autolinks): bare
+ * `www.…`, `http://…`, `https://…`, `ftp://…` and email addresses.
+ * Returns the matches in order, or `null` when there are none — the
+ * common answer, and the one that costs nothing.
+ *
+ * This works on a TEXT VALUE and not on the source, which is what makes
+ * the entity rule meaningful: `&copy;` has already become `©` by the
+ * time we look, so the only `&…;` left to exclude is one that was never
+ * an entity in the first place.
+ * @param {string} value
+ * @returns {{ start: number, end: number, url: string }[] | null}
+ */
+export declare function scanAutolinkLiterals(value: string): {
+    start: number;
+    end: number;
+    url: string;
+}[] | null;

package/dist/types/to-html.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @file AST → HTML string, directly.
+ *
+ * The package's second emitter, and deliberately not a wrapper around
+ * the first (ARCHITECTURE.md "Two emitters"). `mdToVnode` builds a
+ * PATCHABLE TREE — keyed, memoized, reference-stable — whose safety is
+ * structural: a vnode has no slot for unescaped author markup, which is
+ * why a lone `</div>` cannot survive it. `toHtml` builds BYTES, and a
+ * string can hold half an element, so the raw-HTML corner of CommonMark
+ * is reachable here and only here.
+ *
+ * What the two share is factored, not copied: the escapers are
+ * `@jarenjs/view`'s (the same ones its SSR renderer uses, which is what
+ * makes the two outputs byte-identical for markup a vnode can express),
+ * the URL policy is `@jarenjs/view/helpers`, heading slugs come from
+ * `@jarenjs/core/string` through `utils.js`, and plugin dispatch is the
+ * parser's own table.
+ *
+ * Escaping is the default and `html: 'raw'` is per-call: the default
+ * cannot emit unescaped author content, and no jaren surface passes
+ * `'raw'`.
+ */
+export type MdNode = import('./ast.js').MdNode;
+export type MdHtmlOptions = {
+    /**
+     * raw-HTML policy (default
+     * `'escape'`): show the markup as literal text, drop it (the vnode
+     * path's default), or pass it through verbatim. **`'raw'` emits author
+     * content as live markup and is for trusted input only** — a document
+     * from a user, a fetch or a model must never be rendered with it.
+     */
+    html?: 'escape' | 'skip' | 'raw';
+    /**
+     * link/image URL
+     * filter, replacing the default deny-list; return the URL to emit or
+     * `null` to drop the attribute. It applies in EVERY `html` mode,
+     * `'raw'` included: `'raw'` is a statement about HTML blocks, not a
+     * blanket trust, so a markdown `[x](javascript:…)` is still filtered.
+     */
+    sanitizeUrl?: (url: string) => (string | null);
+    /**
+     * plugin set (must match the parse set for
+     * claimed nodes); a plugin contributes `toHtml(node, ctx)` here the
+     * way it contributes `render` to the vnode path.
+     */
+    plugins?: any[];
+    /**
+     * GitHub-compatible `id` per heading
+     * (default `false`; see MD-FORMAT.md §4.5 for why it is opt-in).
+     */
+    headingIds?: boolean;
+    /**
+     * prepended to every heading id and
+     * anchor href (default `''`); set it for markdown you did not author.
+     */
+    slugPrefix?: string;
+    /**
+     * append a `#` permalink to each
+     * heading (default `false`). Requires `headingIds`.
+     */
+    headingAnchors?: boolean;
+    /**
+     * the accessible name of the
+     * appended footnotes section (default `'Footnotes'`); a localized page
+     * sets it, since it is the one string the emitter writes that a reader
+     * can hear.
+     */
+    footnotesLabel?: string;
+    /**
+     * wrapping element, written as it appears in
+     * the start tag (`'article class="md"'`). Default `null`: bare
+     * fragment HTML, which is what a consumer concatenating into a
+     * template wants.
+     */
+    wrap?: string;
+};
+export type HtmlCtx = {
+    tables: any;
+    html: 'escape' | 'skip' | 'raw';
+    sanitizeUrl: (url: string) => (string | null);
+    headingIds: boolean;
+    slugPrefix: string;
+    headingAnchors: boolean;
+    slugs: Map<string, number>;
+    options: MdHtmlOptions;
+    footnotes: import('./footnotes.js').Footnotes | null;
+    footnotePrefix: string;
+    footnotesLabel: string;
+};
+/**
+ * Render an MdDocument (or a CompiledMd, an AST array, a single node)
+ * to an HTML string.
+ *
+ * @example
+ * toHtml(parseMarkdown('# Hi'));                    // '<h1>Hi</h1>'
+ * toHtml(parseMarkdown('<b>x</b>'));                // '&lt;b&gt;x&lt;/b&gt;'
+ * toHtml(doc, { html: 'raw' });                     // trusted input only
+ * toHtml(doc, { wrap: 'article class="md"' });      // wrapped
+ *
+ * @param {any} docOrAst MdDocument, CompiledMd, MdNode[] or MdNode
+ * @param {MdHtmlOptions} [options]
+ * @returns {string}
+ */
+export declare function toHtml(docOrAst: any, options?: MdHtmlOptions): string;

package/dist/types/to-md.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Canonical Markdown printer: AST → text (MD-FORMAT.md §5).
+ *
+ * The printer is the round-trip half of the package: canonical output
+ * re-parses to a deep-equal AST. Canonical choices: ATX headings, `-`
+ * bullets, `1.`/`2.` ordered markers renumbered from `start`, backtick
+ * fences, `*`/`**` emphasis, inline links, backslash hard breaks and
+ * piped tables. Dispatch is one prebuilt table per node class — no
+ * per-node type chains.
+ */
+export type MdNode = import('./ast.js').MdNode;
+/**
+ * Print an MdDocument (or a bare AST array / single node) to canonical
+ * Markdown. Frontmatter re-emits as a `---json` block by default —
+ * exact, syntax-neutral round-trips (MD-FORMAT.md §5).
+ *
+ * @param {any} docOrAst
+ * @param {{ frontmatter?: boolean }} [options]
+ * @returns {string}
+ */
+export declare function toMarkdown(docOrAst: any, options?: {
+    frontmatter?: boolean;
+}): string;

package/dist/types/to-vnode.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @file AST → @jarenjs/view vnodes, and the hydrating renderer.
+ *
+ * The emitter is a prebuilt dispatch table keyed on node type; plugin
+ * `render` entries shadow the core entries (that is how the highlight
+ * plugin takes over `code` nodes). Two identity guarantees feed the
+ * view patcher's O(1) fast paths (VIEW-FORMAT.md §5.1):
+ *
+ *  - per-node memo: the same AST node reference emits the same vnode
+ *    reference, so unchanged subtrees of a JSLT-transformed document
+ *    patch in O(1);
+ *  - content-hash keys: block vnodes are keyed by a hash of their
+ *    content, so moved blocks reorder instead of rebuilding.
+ *
+ * Raw HTML nodes are dropped by default; `options.html: 'text'` shows
+ * them literally, and `'vnode'` PARSES them through an allow-list
+ * (`parseHtmlFragment`, or an injected `parseHtml`). The vnode format
+ * has no unescaped output in any of the three, which is what makes
+ * dropping the safe default for untrusted Markdown. Link and image URLs are
+ * filtered on the same principle: a destination whose scheme can execute
+ * (`javascript:`, `vbscript:`) or stand in for a document
+ * (`data:text/html`, `file:`) loses its attribute rather than reaching
+ * the page. The AST keeps the URL verbatim, so `toMarkdown` still
+ * round-trips what the author wrote — only the vnode is filtered.
+ */
+export type MdNode = import('./ast.js').MdNode;
+export type MdDocument = import('./ast.js').MdDocument;
+export type MdVnodeOptions = {
+    /**
+     * plugin set (must match the parse set for claimed nodes)
+     */
+    plugins?: any[];
+    /**
+     * raw HTML handling (default
+     * 'skip'): drop it, show it as literal text, or parse it to vnodes
+     */
+    html?: 'skip' | 'text' | 'vnode';
+    /**
+     * the parser `html: 'vnode'`
+     * uses (default `parseHtmlFragment` from `@jarenjs/md/html`) — the
+     * injection point for a host's own sanitizer. It returns a LIST of
+     * vnodes (empty or null when nothing survived); an array is always
+     * read as a list, because a vnode is an array too and the two would
+     * otherwise be indistinguishable.
+     */
+    parseHtml?: (html: string) => any;
+    /**
+     * link/image URL
+     * filter, replacing the default deny-list; return the URL to emit, or
+     * `null` to drop the attribute. Supply one only to widen the policy for
+     * trusted content (a custom scheme, say) — it is the whole guard.
+     */
+    sanitizeUrl?: (url: string) => (string | null);
+    /**
+     * give every heading a GitHub-compatible
+     * `id` so `[see below](#the-section)` lands (default `false`). The
+     * default is OFF ON PURPOSE and must stay that way: CommonMark
+     * specifies `<h1>Foo</h1>`, so an id emitted by default would fail
+     * every heading example in the conformance corpus and make the
+     * package's published score a lie. A host that wants anchors asks for
+     * them; the spec path stays honest.
+     */
+    headingIds?: boolean;
+    /**
+     * prepended to every heading id and
+     * anchor href (default `''`). A host rendering markdown it did not
+     * author into a page it owns sets this — GitHub's own answer is
+     * `user-content-` — so an author cannot mint an id that collides with
+     * the host's own DOM.
+     */
+    slugPrefix?: string;
+    /**
+     * append a `#` link to each heading
+     * so a reader can copy a link to the section (default `false`).
+     * Requires `headingIds`; without ids there is nothing to link to.
+     */
+    headingAnchors?: boolean;
+    /**
+     * the accessible name of the
+     * appended footnotes section (default `'Footnotes'`) — the one string
+     * this emitter writes that a reader can hear.
+     */
+    footnotesLabel?: string;
+    /**
+     * give each top-level block a content-hash
+     * `key` (default `true`).
+     *
+     * Keys are what let the view patcher REORDER blocks instead of
+     * rebuilding them, so any caller whose output will be patched needs
+     * them — and computing one means hashing the block's whole subtree,
+     * which is around a quarter of this emitter's cost. A caller that
+     * renders once and throws the tree away (SSR, a string, a snapshot)
+     * pays that for nothing and should pass `false`.
+     *
+     * It is deliberately NOT inferred. A renderer cannot know whether its
+     * output will be patched, and guessing wrong silently turns O(1)
+     * reconciliation into a rebuild — a correctness-shaped failure with no
+     * error message. The default is the safe answer; opting out is a
+     * statement about the caller, which is why every caller in this
+     * repository that passes `false` says why.
+     */
+    keyed?: boolean;
+};
+export type RenderCtx = {
+    tables: any;
+    html: 'skip' | 'text' | 'vnode';
+    options: MdVnodeOptions;
+    parseHtml: (html: string) => any;
+    sanitizeUrl: (url: string) => (string | null);
+    headingIds: boolean;
+    slugPrefix: string;
+    headingAnchors: boolean;
+    slugs: Map<string, number>;
+    footnotes: import('./footnotes.js').Footnotes | null;
+    footnotePrefix: string;
+    footnotesLabel: string;
+    hash: (str: string) => string;
+    counts: Map<string, number>;
+};
+/**
+ * Emit a whole document (or AST array) as one `article.md` vnode with
+ * content-hash-keyed block children.
+ *
+ * @example
+ * mdToVnode(parseMarkdown('# Hi'))
+ * // ['article', { class: 'md' }, [['h1', { key: '…' }, 'Hi']]]
+ *
+ * @param {any} docOrCompiled MdDocument, CompiledMd or MdNode[]
+ * @param {MdVnodeOptions} [options]
+ * @returns {any}
+ */
+export declare function mdToVnode(docOrCompiled: any, options?: MdVnodeOptions): any;
+/**
+ * Create a renderer over `@jarenjs/view`'s DOM patcher that also runs
+ * plugin `hydrate` hooks after mount (PLUGINS.md §5). Returns a
+ * `render(docOrCompiled)` function.
+ *
+ * @param {{
+ *   container: any,
+ *   plugins?: any[],
+ *   html?: 'skip'|'text',
+ *   headingIds?: boolean,
+ *   slugPrefix?: string,
+ *   headingAnchors?: boolean,
+ *   document?: any,
+ *   onEvent?: (binding: any, event: any) => void,
+ *   onHydrateError?: (err: any) => void,
+ * }} options
+ * @returns {(docOrCompiled: any) => void}
+ */
+export declare function createMdRenderer(options: {
+    container: any;
+    plugins?: any[];
+    html?: 'skip' | 'text';
+    headingIds?: boolean;
+    slugPrefix?: string;
+    headingAnchors?: boolean;
+    document?: any;
+    onEvent?: (binding: any, event: any) => void;
+    onHydrateError?: (err: any) => void;
+}): (docOrCompiled: any) => void;

package/dist/types/utils.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file Small shared helpers for the md package.
+ *
+ * The content hash is the package's identity primitive — block vnode
+ * keys, the document `meta.hash`, and the mermaid SVG cache are all keyed
+ * by it — so md re-exports the suite's single `hashContent` from
+ * `@jarenjs/core` rather than carrying its own copy; equal content hits
+ * O(1) fast paths everywhere downstream. `fnv1a` is that same mixing
+ * step, exposed for the two callers that fold a hash incrementally (the
+ * streaming parser's chunks, the structural block-key walk) and so must
+ * seed it themselves from `FNV1A_OFFSET_BASIS`. Heading slugs come from
+ * the same place for the same reason: `slugify` is a pure text→fragment
+ * transform with no Markdown knowledge, so the suite keeps exactly one
+ * of it. The remaining helpers are md's own allocation-light scanner
+ * utilities.
+ */
+export { hashContent, fnv1a, FNV1A_OFFSET_BASIS, slugify } from '@jarenjs/core/string';
+/**
+ * The `id` for one heading, unique within one emission.
+ *
+ * Both emitters mint ids, so the rule lives here once: slug the text,
+ * substitute `section` when nothing slug-worthy survives, number
+ * repeats the way GitHub numbers them (`setup`, `setup-1`, `setup-2`)
+ * and prefix the result. The COUNTER belongs to the caller — one map per
+ * emission, never shared with another numbering (a block key's hash and
+ * a slug share a namespace only by accident, and a collision there would
+ * shift an unrelated heading's number).
+ *
+ * @param {string} text the heading's plain text (`textOf`)
+ * @param {Map<string, number>} seen the emission's slug counter
+ * @param {string} prefix prepended to the result
+ * @returns {string}
+ */
+export declare function headingId(text: string, seen: Map<string, number>, prefix: string): string;
+/**
+ * The accessible name for a heading's permalink affordance — `#` alone
+ * names nothing, so the link says which section it points at.
+ * @param {string} text the heading's plain text (`textOf`)
+ * @returns {string}
+ */
+export declare function permalinkLabel(text: string): string;
+/**
+ * Count leading space characters (U+0020 only; the scanner expands no
+ * tabs here — callers pass detabbed text).
+ * @param {string} line
+ * @returns {number}
+ */
+export declare function countIndent(line: string): number;
+/**
+ * Is the line blank (empty or whitespace-only)?
+ * @param {string} line
+ * @returns {boolean}
+ */
+export declare function isBlankLine(line: string): boolean;
+/**
+ * Replace tabs with spaces to the next 4-column tab stop, counting
+ * columns from `startColumn`. Lines without tabs return the same
+ * string reference (the common case allocates nothing).
+ * @param {string} line
+ * @param {number} [startColumn]
+ * @returns {string}
+ */
+export declare function expandTabs(line: string, startColumn?: number): string;

package/docs/LOADER.md

@@ -0,0 +1,92 @@
+# The Jaren Markdown Loader
+
+**Version 0.1 — Specification**
+
+`loadMarkdown` turns any URL into a compiled Markdown document, with
+caching, cancellation and streaming as first-class citizens.
+
+## 1. API
+
+```js
+const compiled = await loadMarkdown(url, {
+  plugins: [],            // compiled into the parser, §PLUGINS.md
+  base: undefined,        // base URL for relative url arguments
+  signal: undefined,      // AbortSignal — rejects with the abort reason
+  cache: defaultMdCache,  // a cache instance, or false to bypass
+  fetch: globalThis.fetch,// injectable transport (tests, custom auth)
+  retainSource: true,     // false drops the source string after parsing
+  toml: undefined,        // injectable TOML frontmatter parser
+});
+```
+
+Accepted URL schemes are whatever the platform `fetch` accepts:
+`http(s):`, `data:`, `blob:`, and relative paths resolved against
+`options.base` (or as-is when already absolute). The resolved compiled
+document is the same closure bundle `compileMarkdown` returns, with
+`doc.meta.sourceUrl` set to the normalized URL.
+
+## 2. Caching
+
+The shared in-memory cache is keyed by **normalized URL**. Each entry
+remembers the response's `ETag` and `Last-Modified`; a cache hit
+resolves immediately with the cached compiled document, and a
+revalidating fetch (`If-None-Match`/`If-Modified-Since`) only replaces
+the entry when the origin answers with new content (`200` with a
+different validator). Entries also key on the compile-relevant options
+(plugin names), so the same URL compiled with different plugin sets
+does not alias.
+
+- `createMdCache(limit = 64)` — an LRU cache instance; the default
+  shared instance is exported as `defaultMdCache`.
+- `cache: false` — bypass entirely.
+- `cache.delete(url)` / `cache.clear()` — manual invalidation.
+
+Concurrent `loadMarkdown` calls for the same key share one in-flight
+fetch (the promise itself is cached), so a burst of loads costs one
+request.
+
+## 3. Cancellation
+
+`options.signal` is passed through to `fetch` and checked between
+parse steps; aborting rejects the promise with the signal's reason and
+leaves the cache untouched (an aborted in-flight entry is evicted so
+the next call retries).
+
+## 4. Streaming
+
+When the response body is a `ReadableStream`, the loader parses
+**block-by-block as chunks arrive** instead of buffering the full body:
+
+```js
+for await (const block of streamMarkdown(url, options)) {
+  render(block);            // top-level AST block nodes, in order
+}
+```
+
+`streamMarkdown(urlOrStream, options)` accepts a URL, a `Response`, a
+`ReadableStream`, or any async iterable of string/Uint8Array chunks,
+and yields completed top-level block nodes as soon as their end is
+certain (a construct boundary that no later chunk can reopen: a blank
+line at container depth zero outside an open fence). The generator's
+**return value** is the finished `MdDocument`; `loadMarkdown` itself is
+implemented over the same incremental core.
+
+The incremental core is exported for non-URL sources:
+
+```js
+const inc = createIncrementalParser(options);
+inc.feed(chunk);      // → MdNode[] — blocks completed by this chunk
+inc.end();            // → MdDocument — flushes the tail
+```
+
+Frontmatter is resolved as soon as its closing fence arrives, so
+`inc.frontmatter` (and the first yielded value's document) is available
+before the body finishes downloading.
+
+## 5. In an app document (non-normative)
+
+`loadMarkdown` fits `@jarenjs/app`'s effect registry as an ordinary
+async effect: an action dispatches `{ effect: 'md.load', with: url }`,
+the effect resolves the compiled document and dispatches a completion
+action whose payload is the plain `MdDocument` — from there the app's
+JSLT view stylesheet takes over (see the README's end-to-end example).