@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.0

package/dist/MermaidDiagram.d.ts

@@ -0,0 +1,16 @@
+interface MermaidDiagramProps {
+    readonly code: string;
+    /** The theme the host draws in, which picks Mermaid's own. */
+    readonly theme: 'light' | 'dark';
+}
+/**
+ * A mermaid code block drawn as an SVG diagram (§7.2). The library is heavy, so
+ * it is imported lazily, out of the bundle that draws the rest of the note; on
+ * any error the code is shown instead, and the error never leaves the diagram.
+ *
+ * The SVG is the one markup this surface injects, and it is Mermaid's own
+ * output, not note-derived HTML: Mermaid renders with its default `strict`
+ * security level, which encodes the text of the diagram.
+ */
+export declare function MermaidDiagram({ code, theme }: MermaidDiagramProps): import("react").JSX.Element;
+export {};

package/dist/MermaidDiagram.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useId, useState } from 'react';
+/**
+ * A mermaid code block drawn as an SVG diagram (§7.2). The library is heavy, so
+ * it is imported lazily, out of the bundle that draws the rest of the note; on
+ * any error the code is shown instead, and the error never leaves the diagram.
+ *
+ * The SVG is the one markup this surface injects, and it is Mermaid's own
+ * output, not note-derived HTML: Mermaid renders with its default `strict`
+ * security level, which encodes the text of the diagram.
+ */
+export function MermaidDiagram({ code, theme }) {
+    const id = useId().replace(/[^a-zA-Z0-9]/g, '');
+    const [svg, setSvg] = useState(null);
+    const [failed, setFailed] = useState(false);
+    useEffect(() => {
+        let alive = true;
+        let renderId = null;
+        setSvg(null);
+        setFailed(false);
+        void (async () => {
+            try {
+                const { default: mermaid } = await import('mermaid');
+                // Text metrics depend on the webfont; rendering before it loads
+                // truncates node labels.
+                await document.fonts?.ready;
+                mermaid.initialize({
+                    startOnLoad: false,
+                    theme: theme === 'dark' ? 'dark' : 'neutral',
+                    fontFamily: 'Inter, sans-serif',
+                    // SVG text labels measure reliably; HTML labels clip inside nodes
+                    // when the webfont metrics differ from the fallback.
+                    htmlLabels: false,
+                    flowchart: { htmlLabels: false },
+                });
+                /**
+                 * A diagram Mermaid cannot read is shown as its code without drawing
+                 * it. Drawing it anyway failed in the right place, the code, and left
+                 * the scratch container Mermaid draws into — its error bomb included —
+                 * at the end of <body>, under the whole page.
+                 */
+                if ((await mermaid.parse(code, { suppressErrors: true })) === false) {
+                    if (alive)
+                        setFailed(true);
+                    return;
+                }
+                renderId = `mmd-${id}-${Date.now()}`;
+                const rendered = await mermaid.render(renderId, code);
+                if (alive)
+                    setSvg(rendered.svg);
+            }
+            catch {
+                // And should drawing still fail, what it left behind goes with it.
+                if (renderId)
+                    document.getElementById(`d${renderId}`)?.remove();
+                if (alive)
+                    setFailed(true);
+            }
+        })();
+        return () => {
+            alive = false;
+        };
+    }, [code, id, theme]);
+    if (failed) {
+        return (_jsx("pre", { children: _jsx("code", { children: code }) }));
+    }
+    if (!svg)
+        return _jsx("div", { className: "mermaid-diagram mermaid-loading" });
+    return _jsx("div", { className: "mermaid-diagram", dangerouslySetInnerHTML: { __html: svg } });
+}

package/dist/NoteBody.d.ts

@@ -0,0 +1,15 @@
+import { type NoteHost } from './host.js';
+export interface NoteBodyProps extends NoteHost {
+    /**
+     * The note as the host keeps it, frontmatter included. It is drawn from these bytes and never
+     * rewritten; the frontmatter is not drawn, because a host shows it as properties.
+     */
+    readonly markdown: string;
+}
+/**
+ * The body of a note, drawn as MemorySmith's reading page draws it.
+ *
+ * It renders inside `.markdown`, so the stylesheet of the package applies, and asks the host for
+ * every piece of notebook data through the props of `NoteHost`.
+ */
+export declare function NoteBody({ markdown, writable, onToggleTask, ...host }: NoteBodyProps): import("react").JSX.Element;

package/dist/NoteBody.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { HOST_KEYS, HostProvider, resolveHost } from './host.js';
+import { Markdown } from './Markdown.js';
+import { bodyStart, remoteImageHosts, resolveWikilinks } from './markdown.js';
+import { taskBoxes } from './tasklist.js';
+import { Transclusion } from './Transclusion.js';
+import { splitEmbeds } from './transclusion.js';
+import { wikilinkAddress } from './wikilink-address.js';
+/**
+ * The body of a note, drawn as MemorySmith's reading page draws it.
+ *
+ * It renders inside `.markdown`, so the stylesheet of the package applies, and asks the host for
+ * every piece of notebook data through the props of `NoteHost`.
+ */
+export function NoteBody({ markdown, writable = false, onToggleTask, ...host }) {
+    const resolved = useMemo(() => resolveHost(host), 
+    // Every member of the contract, so a host that passes the same functions keeps the same host.
+    HOST_KEYS.map((key) => host[key]));
+    // Frontmatter is shown as properties, not as prose, so the reading surface
+    // starts after it. Everything below counts task items from there.
+    const split = bodyStart(markdown);
+    const body = markdown.slice(split);
+    // The body is cut into runs of text and the embeds between them; each run
+    // is parsed on its own, as on MemorySmith's reading page.
+    const segments = splitEmbeds(body, resolved.keeps).map((segment) => segment.kind === 'text'
+        ? {
+            ...segment,
+            // One resolver for every run: one note is a link, several are the
+            // choice, and none is pending and still asks.
+            rendered: resolveWikilinks(segment.text, (name) => wikilinkAddress(resolved, name), resolved.keeps),
+        }
+        : segment);
+    /**
+     * Whether a click can be mapped back to the bytes at all.
+     *
+     * The ordinal is counted over the text the PARSER saw, which is the one with
+     * the wikilinks already resolved, and it is applied to the text a write
+     * sends, which is the original. Those two agree on how many boxes there are
+     * and in what order, almost always — and `- [[x]]` is where they do not,
+     * because resolving it produces `- [x](/url)`, which is a task box to any
+     * GFM reader. Counting on one side and writing on the other would then
+     * toggle a different item, silently, which is the worst defect this surface
+     * can have. When the two disagree the boxes are read-only: not writing is
+     * always better than writing the wrong one.
+     */
+    const mappable = taskBoxes(body).length ===
+        segments.reduce((total, segment) => total + ('rendered' in segment ? taskBoxes(segment.rendered).length : 0), 0);
+    // The ordinal a click carries is of the WHOLE note, and each rendered run
+    // only knows its own. The count carried across the runs is what bridges
+    // the two, and it has to include anything above the body.
+    let seen = taskBoxes(markdown.slice(0, split)).length;
+    /**
+     * Whom this note asked the browser to talk to (§7.10).
+     *
+     * The specification admits three answers about a remote image and forbids
+     * only silence: never fetching, fetching on the reader's action, or fetching
+     * and saying so. This surface fetches — the destination reaches `<img src>`,
+     * and React even preloads it — so this line is the half that says so, and
+     * the reason it has to exist is that this is the one of the three answers a
+     * person cannot work out from the page.
+     *
+     * It appears only where it is true, naming the hosts, because a notice on
+     * every note would be a thing to scroll past rather than a thing to read.
+     */
+    const hosts = resolved.remoteNotice ? remoteImageHosts(body) : [];
+    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: "markdown", "data-theme": resolved.theme, children: [segments.map((segment, index) => {
+                    if (!('rendered' in segment)) {
+                        return _jsx(Transclusion, { target: segment.target, anchor: segment.anchor }, index);
+                    }
+                    const base = seen;
+                    seen += taskBoxes(segment.rendered).length;
+                    return (_jsx(Markdown, { 
+                        // The text the ordinal is counted over, stated rather than left to
+                        // a default: it is the one the parser reports offsets into, and
+                        // `mappable` above is what makes it safe to write back through.
+                        source: segment.rendered, onToggleTask: onToggleTask && ((ordinal) => onToggleTask(base + ordinal)), writable: writable && mappable, children: segment.rendered }, index));
+                }), hosts.length > 0 && _jsx("p", { className: "remote-notice", children: resolved.strings.remoteImages(hosts) })] }) }));
+}

package/dist/Transclusion.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One transcluded block: the content of another note, shown in place.
+ *
+ * It always says where it came from. A passage pasted without provenance is
+ * indistinguishable from what the author wrote, and a notebook rests on
+ * knowing who asserted what.
+ */
+export declare function Transclusion({ target, anchor }: {
+    target: string;
+    anchor: string | null;
+}): import("react").JSX.Element;

package/dist/Transclusion.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { useHost } from './host.js';
+import { Markdown } from './Markdown.js';
+import { bodyStart, resolveWikilinks } from './markdown.js';
+import { blockOf, demoteEmbeds, isBlockAnchor, sectionOf } from './transclusion.js';
+import { wikilinkAddress } from './wikilink-address.js';
+/** The shape of what is coming, in the position it will occupy, while the host answers. */
+function TransclusionSkeleton({ loading }) {
+    return (_jsxs("div", { className: "skeleton-region", "aria-busy": "true", "aria-live": "polite", children: [_jsx("span", { className: "visually-hidden", children: loading }), _jsxs("figure", { className: "embed embed-skeleton", children: [_jsx("div", { className: "embed-body", children: _jsxs("span", { className: "skeleton-text", children: [_jsx("span", { className: "skeleton", style: { width: '96%', height: '1rem' } }), _jsx("span", { className: "skeleton", style: { width: '58%', height: '1rem' } })] }) }), _jsx("figcaption", { className: "embed-source", children: _jsx("span", { className: "skeleton", style: { width: '8rem', height: '0.8rem' } }) })] })] }));
+}
+/**
+ * One transcluded block: the content of another note, shown in place.
+ *
+ * It always says where it came from. A passage pasted without provenance is
+ * indistinguishable from what the author wrote, and a notebook rests on
+ * knowing who asserted what.
+ */
+export function Transclusion({ target, anchor }) {
+    const host = useHost();
+    const { strings } = host;
+    const name = target.normalize('NFC');
+    // A transclusion expands ONE note, so it expands what a wikilink would
+    // navigate to: an ambiguous target is a choice a reader makes and not a
+    // passage the page can inline on their behalf.
+    const one = host.loadNote !== null && host.reaches(name) === 1;
+    const [loaded, setLoaded] = useState({ state: 'loading' });
+    useEffect(() => {
+        if (!one || !host.loadNote)
+            return;
+        let alive = true;
+        setLoaded({ state: 'loading' });
+        host.loadNote(name).then((note) => alive && setLoaded(note ? { state: 'ready', note } : { state: 'missing' }), () => alive && setLoaded({ state: 'missing' }));
+        return () => {
+            alive = false;
+        };
+    }, [one, host, name]);
+    // The same pending marker a wikilink uses. A notebook is read most while it
+    // is still being written, so a target that does not exist yet is an
+    // expected state and never an error that stops the page.
+    if (!one || loaded.state === 'missing') {
+        return (_jsx("p", { className: "embed-pending", children: _jsx("span", { className: "wikilink-pending", title: strings.pendingLink, children: target }) }));
+    }
+    if (loaded.state === 'loading')
+        return _jsx(TransclusionSkeleton, { loading: strings.loading });
+    const { note } = loaded;
+    const whole = note.markdown.slice(bodyStart(note.markdown));
+    // The caption names the note the content came from, and a note may have no
+    // name.
+    const sourceLabel = note.name ?? strings.unnamedNote;
+    // `#^id` addresses a BLOCK and `#Section` a heading. The two are told apart
+    // by the marker and not by trying one and falling back to the other, or a
+    // section named `^x` and a block called `x` would answer for each other.
+    const cut = !anchor ? whole : isBlockAnchor(anchor) ? blockOf(whole, anchor.slice(1)) : sectionOf(whole, anchor);
+    const caption = anchor ? `${sourceLabel} › ${anchor}` : sourceLabel;
+    return (_jsxs("figure", { className: "embed", children: [_jsx("div", { className: "embed-body", children: cut === null ? (_jsx("p", { className: "embed-missing", children: strings.embedSectionMissing(anchor ?? '') })) : (
+                /**
+                 * Resolved, like every other run of the note. Without this every
+                 * `[[link]]` inside transcluded content reached the page with its
+                 * brackets — and the sharpest case is the one the one-level rule
+                 * creates itself: `demoteEmbeds` turns an embed found in embedded
+                 * content into a wikilink, and that embed is drawn as A LINK to its
+                 * target. Raw text is not a link.
+                 */
+                _jsx(Markdown, { children: resolveWikilinks(demoteEmbeds(cut, host.keeps), (each) => wikilinkAddress(host, each), host.keeps) })) }), _jsx("figcaption", { className: "embed-source", children: note.address === null ? caption : host.renderLink({ href: note.address, children: caption }) })] }));
+}

package/dist/address.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which addresses the reading surface will follow.
+ *
+ * `react-markdown` normally passes every URL through a filter that keeps the
+ * safe schemes and drops the rest, and the reading page once had it **switched
+ * off** — `urlTransform={(url) => url}`. There was a reason: an unresolved
+ * wikilink is rendered as `[text](pending:target)`, and the stock filter does
+ * not know `pending:`, so it erased the pending link from the page. A whole
+ * protection was traded for one scheme.
+ *
+ * This is that trade undone. The list says what passes, never what is
+ * refused, because a notebook is written by several people and by agents, and a
+ * denylist is a promise to have thought of everything.
+ *
+ * **What passes, and why:**
+ *
+ * - `pending:` — ours, and the reason the filter was off in the first place;
+ *   and `attachment:` and `choice:`, ours too.
+ * - A path of the application (`/`), a relative one (`./`, `../`) and an
+ *   anchor of the page (`#`).
+ * - `http:` and `https:` — the web, which is what a note cites.
+ * - `mailto:` — a person, which is what a note cites next most often.
+ *
+ * **What does not, and why each one:**
+ *
+ * - **`obsidian://`, and any other scheme of an editor. Decided, not
+ *   overlooked.** It opens the notebook of whoever has that editor installed and
+ *   that notebook on that machine, so the link works for the person who wrote it
+ *   and does nothing at all for everybody else who opens the note — a promise
+ *   the host cannot keep on behalf of a tool it does not run. A notebook is
+ *   served to whoever reads it, and an address only its author can follow is
+ *   not an address.
+ * - `data:` — a whole page carried inside the address. `data:text/html` is a
+ *   script running in the reader's session, offered by whoever wrote the note.
+ * - `javascript:` and `vbscript:` — script written where an address goes.
+ *   React blocks the first one on its own; that it does is not a reason to
+ *   hand it the chance.
+ * - `file:` — the disk of whoever is reading, addressed by somebody else.
+ *
+ * A refused address is not silently swallowed: the text stays on the page and
+ * stops being clickable, which is what the anchor of the surface does with an
+ * empty href. An author sees they got nothing, the same answer the
+ * specification gives to a notation it does not implement.
+ */
+/**
+ * The address as it will be written, or the empty string when this surface
+ * will not follow it.
+ *
+ * An address with no scheme is a path, an anchor or a relative target, and it
+ * cannot reach outside the page on its own: those pass untouched, which is
+ * what keeps `./note.md`, `/v/a-notebook/note/x` and `#a-heading` working.
+ */
+export declare function followable(url: string): string;

package/dist/address.js

@@ -0,0 +1,69 @@
+/**
+ * Which addresses the reading surface will follow.
+ *
+ * `react-markdown` normally passes every URL through a filter that keeps the
+ * safe schemes and drops the rest, and the reading page once had it **switched
+ * off** — `urlTransform={(url) => url}`. There was a reason: an unresolved
+ * wikilink is rendered as `[text](pending:target)`, and the stock filter does
+ * not know `pending:`, so it erased the pending link from the page. A whole
+ * protection was traded for one scheme.
+ *
+ * This is that trade undone. The list says what passes, never what is
+ * refused, because a notebook is written by several people and by agents, and a
+ * denylist is a promise to have thought of everything.
+ *
+ * **What passes, and why:**
+ *
+ * - `pending:` — ours, and the reason the filter was off in the first place;
+ *   and `attachment:` and `choice:`, ours too.
+ * - A path of the application (`/`), a relative one (`./`, `../`) and an
+ *   anchor of the page (`#`).
+ * - `http:` and `https:` — the web, which is what a note cites.
+ * - `mailto:` — a person, which is what a note cites next most often.
+ *
+ * **What does not, and why each one:**
+ *
+ * - **`obsidian://`, and any other scheme of an editor. Decided, not
+ *   overlooked.** It opens the notebook of whoever has that editor installed and
+ *   that notebook on that machine, so the link works for the person who wrote it
+ *   and does nothing at all for everybody else who opens the note — a promise
+ *   the host cannot keep on behalf of a tool it does not run. A notebook is
+ *   served to whoever reads it, and an address only its author can follow is
+ *   not an address.
+ * - `data:` — a whole page carried inside the address. `data:text/html` is a
+ *   script running in the reader's session, offered by whoever wrote the note.
+ * - `javascript:` and `vbscript:` — script written where an address goes.
+ *   React blocks the first one on its own; that it does is not a reason to
+ *   hand it the chance.
+ * - `file:` — the disk of whoever is reading, addressed by somebody else.
+ *
+ * A refused address is not silently swallowed: the text stays on the page and
+ * stops being clickable, which is what the anchor of the surface does with an
+ * empty href. An author sees they got nothing, the same answer the
+ * specification gives to a notation it does not implement.
+ */
+/**
+ * `pending:`, `attachment:` and `choice:` are this surface's own: a wikilink
+ * that matched no note, a reference to a file the notebook keeps beside its
+ * notes, and a wikilink several notes may answer. None of them leaves the page
+ * — the anchor of the surface turns each into what it is — and they are listed
+ * here so the filter does not empty them into the refusal case, which says
+ * something else entirely.
+ */
+const ALLOWED_SCHEME = /^(https?|mailto|pending|attachment|choice):/i;
+/** Anything of the shape `word:`, which is what makes an address absolute. */
+const HAS_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/**
+ * The address as it will be written, or the empty string when this surface
+ * will not follow it.
+ *
+ * An address with no scheme is a path, an anchor or a relative target, and it
+ * cannot reach outside the page on its own: those pass untouched, which is
+ * what keeps `./note.md`, `/v/a-notebook/note/x` and `#a-heading` working.
+ */
+export function followable(url) {
+    const trimmed = url.trim();
+    if (!HAS_SCHEME.test(trimmed))
+        return url;
+    return ALLOWED_SCHEME.test(trimmed) ? url : '';
+}

package/dist/delegated.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The entries of the specification whose rendering this renderer does NOT
+ * assert, because the base parser is what produces them.
+ *
+ * **This list is the renderer's decision, and it used to be a field.** Until
+ * specification v0.4.0 every entry carried a `ring`, and the reading-surface
+ * expectations were scoped to everything outside the `base` one. The
+ * specification dropped the tier for a good reason: an implementation is asked
+ * for the notation the document lists and not for a specification in full. But
+ * the reason the guard was scoped did not go away with the field, so the scope
+ * is written here instead of being inferred from data that no longer says it.
+ *
+ * The reason: asserting that emphasis renders as `<em>` is a claim about
+ * react-markdown and not about this surface. CommonMark is the floor every
+ * renderer already stands on; what the conformance test proves is what the
+ * specification adds on top of it.
+ *
+ * **Two things this list is not.**
+ *
+ * It is not a claim that these forms are untested: the crossings — where the
+ * specification changes what a base form MEANS, such as a link inside a code
+ * span, an embed that looks like an image, or `---` under a paragraph — are
+ * asserted by hand in the conformance test.
+ *
+ * And it is not allowed to silently absorb a new entry. The conformance test
+ * asserts that every `reading-surface` entry is either expected there or listed
+ * here, so a form the specification adds in a later version fails the build
+ * until somebody classifies it.
+ */
+export declare const DELEGATED_TO_THE_BASE_PARSER: ReadonlySet<string>;
+/**
+ * The `reading-surface` entries of a specification that are neither asserted
+ * nor delegated: the ones a renderer would silently not implement. Empty is the
+ * only answer a conforming renderer gives.
+ */
+export declare function unclassified(notations: ReadonlyArray<{
+    readonly id: string;
+    readonly reader: string;
+}>, asserted: ReadonlySet<string>, delegated?: ReadonlySet<string>): string[];

package/dist/delegated.js

@@ -0,0 +1,63 @@
+/**
+ * The entries of the specification whose rendering this renderer does NOT
+ * assert, because the base parser is what produces them.
+ *
+ * **This list is the renderer's decision, and it used to be a field.** Until
+ * specification v0.4.0 every entry carried a `ring`, and the reading-surface
+ * expectations were scoped to everything outside the `base` one. The
+ * specification dropped the tier for a good reason: an implementation is asked
+ * for the notation the document lists and not for a specification in full. But
+ * the reason the guard was scoped did not go away with the field, so the scope
+ * is written here instead of being inferred from data that no longer says it.
+ *
+ * The reason: asserting that emphasis renders as `<em>` is a claim about
+ * react-markdown and not about this surface. CommonMark is the floor every
+ * renderer already stands on; what the conformance test proves is what the
+ * specification adds on top of it.
+ *
+ * **Two things this list is not.**
+ *
+ * It is not a claim that these forms are untested: the crossings — where the
+ * specification changes what a base form MEANS, such as a link inside a code
+ * span, an embed that looks like an image, or `---` under a paragraph — are
+ * asserted by hand in the conformance test.
+ *
+ * And it is not allowed to silently absorb a new entry. The conformance test
+ * asserts that every `reading-surface` entry is either expected there or listed
+ * here, so a form the specification adds in a later version fails the build
+ * until somebody classifies it.
+ */
+export const DELEGATED_TO_THE_BASE_PARSER = new Set([
+    'paragraph',
+    'backslash-escape',
+    'character-reference',
+    'heading-atx',
+    'heading-setext',
+    'thematic-break',
+    'block-quote',
+    'list-bullet',
+    'list-ordered',
+    'code-fenced',
+    'code-indented',
+    'link-reference-definition',
+    'code-span',
+    'emphasis',
+    'strong',
+    'strong-emphasis',
+    'link-inline',
+    'link-reference',
+    'image',
+    'autolink',
+    'hard-line-break',
+]);
+/**
+ * The `reading-surface` entries of a specification that are neither asserted
+ * nor delegated: the ones a renderer would silently not implement. Empty is the
+ * only answer a conforming renderer gives.
+ */
+export function unclassified(notations, asserted, delegated = DELEGATED_TO_THE_BASE_PARSER) {
+    return notations
+        .filter((entry) => entry.reader === 'reading-surface')
+        .map((entry) => entry.id)
+        .filter((id) => !asserted.has(id) && !delegated.has(id));
+}

package/dist/highlight.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Syntax highlighting for a fenced block that names its language.
+ *
+ * **This is presentation and nothing else.** The specification attaches a rendering
+ * rule to exactly one info string, `mermaid`, and says of every other one only
+ * that it names the language by convention. So highlighting is a product
+ * decision rather than a conformance obligation — §8 is explicit that an
+ * implementation MAY render an undescribed form however it likes — and the
+ * four rules below are the ones the specification *does* impose on anything sitting
+ * this close to the body of a note.
+ *
+ * **The bytes never change.** Highlighting is display. §7.6 sets the principle
+ * for comments — the bytes stay in the file and a tool that returns the note
+ * returns them — and §7.11 states it as behaviour, where a task toggle writes
+ * back exactly the one character that changed. Nothing here touches the
+ * source: the tokens are read from it and the string is not rewritten.
+ *
+ * **An unknown language renders as plain code, never as nothing.** The specification
+ * sets that pattern twice, for the diagram it cannot draw (§7.2) and for the
+ * mathematics it cannot typeset (§7.8): show the source, never hide it. A
+ * language `refractor` does not carry falls through to exactly what was
+ * rendered before this existed.
+ *
+ * **`mermaid` keeps its branch**, and it is checked before this is reached. It
+ * is the one info string with a rendering rule, and a highlighter installed in
+ * front of that check would swallow a diagram.
+ *
+ * **The markup arrives as elements and never as an HTML string.** §7.9 refuses
+ * raw HTML as a security boundary — a notebook is written by several people and
+ * by agents, and a page that renders arbitrary HTML out of one is a script
+ * injection whose trigger is written by whoever wrote the note. A highlighter
+ * returning HTML to be injected reopens that door with the note body as its
+ * input. `refractor` produces a hast tree, which is converted to React
+ * elements, so nothing is ever parsed as markup.
+ *
+ * **The languages are enumerated rather than bundled.** Prism carries close to
+ * three hundred grammars and a knowledge notebook writes in a handful. The list
+ * is what a notebook of MemorySmith plausibly holds — the languages of its own
+ * repository, the two query languages, the three configuration formats and the
+ * two shells — and adding one is a line, which is the point: a bundle nobody
+ * chose is a bundle nobody can defend. It is MemorySmith's list, unchanged, so
+ * a fence is highlighted here exactly when it is highlighted there.
+ */
+import type { Root } from 'hast';
+/**
+ * The language of a fenced block, from the class react-markdown puts on it.
+ *
+ * `null` for a block with no info string, for one whose language is not
+ * carried, and for `mermaid` — which never reaches here, and is refused
+ * explicitly so that a future caller cannot make it.
+ */
+export declare function highlightLanguage(className: string | undefined): string | null;
+/** The tokens of `code` in `language`, as a hast tree. Never an HTML string. */
+export declare function highlightTree(code: string, language: string): Root;

package/dist/highlight.js

@@ -0,0 +1,96 @@
+/**
+ * Syntax highlighting for a fenced block that names its language.
+ *
+ * **This is presentation and nothing else.** The specification attaches a rendering
+ * rule to exactly one info string, `mermaid`, and says of every other one only
+ * that it names the language by convention. So highlighting is a product
+ * decision rather than a conformance obligation — §8 is explicit that an
+ * implementation MAY render an undescribed form however it likes — and the
+ * four rules below are the ones the specification *does* impose on anything sitting
+ * this close to the body of a note.
+ *
+ * **The bytes never change.** Highlighting is display. §7.6 sets the principle
+ * for comments — the bytes stay in the file and a tool that returns the note
+ * returns them — and §7.11 states it as behaviour, where a task toggle writes
+ * back exactly the one character that changed. Nothing here touches the
+ * source: the tokens are read from it and the string is not rewritten.
+ *
+ * **An unknown language renders as plain code, never as nothing.** The specification
+ * sets that pattern twice, for the diagram it cannot draw (§7.2) and for the
+ * mathematics it cannot typeset (§7.8): show the source, never hide it. A
+ * language `refractor` does not carry falls through to exactly what was
+ * rendered before this existed.
+ *
+ * **`mermaid` keeps its branch**, and it is checked before this is reached. It
+ * is the one info string with a rendering rule, and a highlighter installed in
+ * front of that check would swallow a diagram.
+ *
+ * **The markup arrives as elements and never as an HTML string.** §7.9 refuses
+ * raw HTML as a security boundary — a notebook is written by several people and
+ * by agents, and a page that renders arbitrary HTML out of one is a script
+ * injection whose trigger is written by whoever wrote the note. A highlighter
+ * returning HTML to be injected reopens that door with the note body as its
+ * input. `refractor` produces a hast tree, which is converted to React
+ * elements, so nothing is ever parsed as markup.
+ *
+ * **The languages are enumerated rather than bundled.** Prism carries close to
+ * three hundred grammars and a knowledge notebook writes in a handful. The list
+ * is what a notebook of MemorySmith plausibly holds — the languages of its own
+ * repository, the two query languages, the three configuration formats and the
+ * two shells — and adding one is a line, which is the point: a bundle nobody
+ * chose is a bundle nobody can defend. It is MemorySmith's list, unchanged, so
+ * a fence is highlighted here exactly when it is highlighted there.
+ */
+import { refractor } from 'refractor/core';
+import bash from 'refractor/bash';
+import css from 'refractor/css';
+import diff from 'refractor/diff';
+import graphql from 'refractor/graphql';
+import ini from 'refractor/ini';
+import java from 'refractor/java';
+import javascript from 'refractor/javascript';
+import json from 'refractor/json';
+import markdown from 'refractor/markdown';
+import python from 'refractor/python';
+import sql from 'refractor/sql';
+import toml from 'refractor/toml';
+import tsx from 'refractor/tsx';
+import typescript from 'refractor/typescript';
+import yaml from 'refractor/yaml';
+for (const language of [
+    bash,
+    css,
+    diff,
+    graphql,
+    ini,
+    java,
+    javascript,
+    json,
+    markdown,
+    python,
+    sql,
+    toml,
+    tsx,
+    typescript,
+    yaml,
+]) {
+    refractor.register(language);
+}
+/**
+ * The language of a fenced block, from the class react-markdown puts on it.
+ *
+ * `null` for a block with no info string, for one whose language is not
+ * carried, and for `mermaid` — which never reaches here, and is refused
+ * explicitly so that a future caller cannot make it.
+ */
+export function highlightLanguage(className) {
+    const match = /(?:^|\s)language-([A-Za-z0-9#+._-]+)/.exec(className ?? '');
+    const named = match?.[1]?.toLowerCase();
+    if (!named || named === 'mermaid')
+        return null;
+    return refractor.registered(named) ? named : null;
+}
+/** The tokens of `code` in `language`, as a hast tree. Never an HTML string. */
+export function highlightTree(code, language) {
+    return refractor.highlight(code, language);
+}