@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.1

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/footnotes.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Footnotes across the runs of a note (§7.12).
+ *
+ * `NoteBody` draws the text between two embeds as runs of their own, each
+ * through its own parser, and a footnote is resolved inside one parse: GFM
+ * reads `[^label]` as a reference only when the same document defines
+ * `label`. A reference above an embed and its definition below it therefore
+ * never met, and the reference reached the page as its characters. MemorySmith's
+ * reading page does the same; this renderer does not carry it.
+ *
+ * The runs stay runs — they are what keeps the task ordinals and the layout
+ * of every other note as MemorySmith draws them — and the note is drawn as one
+ * document would draw it:
+ *
+ * - every run is handed the definitions written in the OTHER runs, appended
+ *   after its own text, so its references parse; appending after the text
+ *   moves no offset the task boxes are counted from;
+ * - each run's own footnotes section is dropped, and each reference is
+ *   renumbered in the order of the note, with the id one document would give
+ *   its n-th use of a label;
+ * - one section is drawn at the end of the note, after its last embed too,
+ *   from every reference of the note in order and every definition, so its
+ *   numbers and its ways back are the ones a single document would have.
+ *
+ * Only a definition written at the top level of a run travels. A note with
+ * one inside a quote or a list, with no embed, or with no definition, is
+ * planned as nothing and drawn exactly as before.
+ */
+import { type PluggableList } from 'unified';
+/** The prefix remark-rehype gives every footnote id, set explicitly where `Markdown` draws. */
+export declare const CLOBBER_PREFIX = "user-content-";
+interface HastNode {
+    type: string;
+    tagName?: string;
+    value?: string;
+    properties?: Record<string, unknown>;
+    children?: HastNode[];
+}
+/** One reference as the note numbers it: its footnote's number, and which use of the label it is. */
+export interface FootnoteRef {
+    readonly number: number;
+    readonly occurrence: number;
+}
+export interface FootnotePlan {
+    /** For each run, in order: the text its parser reads, and its references in the order it draws them. */
+    readonly runs: readonly {
+        readonly text: string;
+        readonly refs: readonly FootnoteRef[];
+    }[];
+    /** The text the one footnotes section of the note is drawn from. */
+    readonly section: string;
+}
+/**
+ * How the runs of a note draw their footnotes, or null when nothing has to
+ * change: a note no embed cuts, or one with no footnote to carry. `cut` says
+ * whether an embed cut it — a note of one run followed by an embed is cut
+ * too, because its notes belong below the embed, at the end of the note.
+ *
+ * `plugins` are the remark plugins of `Markdown`, so a reference the reading
+ * surface would not draw — inside a comment, say — is not counted either.
+ */
+export declare function planFootnotes(runs: readonly string[], cut: boolean, plugins: PluggableList): FootnotePlan | null;
+/**
+ * The rehype side of a run: its own section dropped, and each reference given
+ * the number and the id the note gives it.
+ */
+export declare function rehypeFootnoteRun(options: {
+    refs: readonly FootnoteRef[];
+}): (tree: HastNode) => void;
+/** The rehype side of the section pass: the section and nothing else. */
+export declare function rehypeFootnoteSection(): (tree: HastNode) => void;
+export {};

package/dist/footnotes.js

@@ -0,0 +1,137 @@
+/**
+ * Footnotes across the runs of a note (§7.12).
+ *
+ * `NoteBody` draws the text between two embeds as runs of their own, each
+ * through its own parser, and a footnote is resolved inside one parse: GFM
+ * reads `[^label]` as a reference only when the same document defines
+ * `label`. A reference above an embed and its definition below it therefore
+ * never met, and the reference reached the page as its characters. MemorySmith's
+ * reading page does the same; this renderer does not carry it.
+ *
+ * The runs stay runs — they are what keeps the task ordinals and the layout
+ * of every other note as MemorySmith draws them — and the note is drawn as one
+ * document would draw it:
+ *
+ * - every run is handed the definitions written in the OTHER runs, appended
+ *   after its own text, so its references parse; appending after the text
+ *   moves no offset the task boxes are counted from;
+ * - each run's own footnotes section is dropped, and each reference is
+ *   renumbered in the order of the note, with the id one document would give
+ *   its n-th use of a label;
+ * - one section is drawn at the end of the note, after its last embed too,
+ *   from every reference of the note in order and every definition, so its
+ *   numbers and its ways back are the ones a single document would have.
+ *
+ * Only a definition written at the top level of a run travels. A note with
+ * one inside a quote or a list, with no embed, or with no definition, is
+ * planned as nothing and drawn exactly as before.
+ */
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+/** The prefix remark-rehype gives every footnote id, set explicitly where `Markdown` draws. */
+export const CLOBBER_PREFIX = 'user-content-';
+/** What one document would key a label by: remark-rehype's own normalisation. */
+const keyOf = (node) => String(node.identifier ?? '').toUpperCase();
+/**
+ * How the runs of a note draw their footnotes, or null when nothing has to
+ * change: a note no embed cuts, or one with no footnote to carry. `cut` says
+ * whether an embed cut it — a note of one run followed by an embed is cut
+ * too, because its notes belong below the embed, at the end of the note.
+ *
+ * `plugins` are the remark plugins of `Markdown`, so a reference the reading
+ * surface would not draw — inside a comment, say — is not counted either.
+ */
+export function planFootnotes(runs, cut, plugins) {
+    if (!cut || !runs.some((run) => run.includes('[^')))
+        return null;
+    const processor = unified().use(remarkParse).use(plugins);
+    const read = (text) => processor.runSync(processor.parse(text), text);
+    // The definitions, the first of each label winning, as in one document.
+    const definitions = new Map();
+    let nested = false;
+    runs.forEach((run, index) => {
+        const tree = processor.parse(run);
+        const below = (node) => (node.children ?? []).some((child) => child.type === 'footnoteDefinition' || below(child));
+        nested ||= (tree.children ?? []).some(below);
+        for (const child of tree.children ?? []) {
+            const start = child.position?.start?.offset;
+            const end = child.position?.end?.offset;
+            if (child.type !== 'footnoteDefinition' || start === undefined || end === undefined)
+                continue;
+            if (!definitions.has(keyOf(child)))
+                definitions.set(keyOf(child), { source: run.slice(start, end), run: index });
+        }
+    });
+    // A definition inside a quote or a list cannot be lifted into the section
+    // without its markers, so a note that has one is drawn as before.
+    if (definitions.size === 0 || nested)
+        return null;
+    const order = [];
+    const uses = new Map();
+    const labels = [];
+    const planned = runs.map((run, index) => {
+        const others = [...definitions.values()].filter((definition) => definition.run !== index);
+        const text = others.length === 0 ? run : `${run}\n\n${others.map((definition) => definition.source).join('\n\n')}\n`;
+        const refs = [];
+        const walk = (node) => {
+            // A reference inside a definition is drawn in the section, after every
+            // reference of the body, which is where the section pass meets it.
+            if (node.type === 'footnoteDefinition')
+                return;
+            if (node.type === 'footnoteReference') {
+                const key = keyOf(node);
+                if (!order.includes(key))
+                    order.push(key);
+                const occurrence = (uses.get(key) ?? 0) + 1;
+                uses.set(key, occurrence);
+                labels.push(node.label ?? node.identifier ?? '');
+                refs.push({ number: order.indexOf(key) + 1, occurrence });
+            }
+            for (const child of node.children ?? [])
+                walk(child);
+        };
+        walk(read(text));
+        return { text, refs };
+    });
+    if (order.length === 0)
+        return null;
+    const section = `${labels.map((label) => `[^${label}]`).join(' ')}\n\n${[...definitions.values()]
+        .map((definition) => definition.source)
+        .join('\n\n')}\n`;
+    return { runs: planned, section };
+}
+function isElement(node, tagName) {
+    return node.type === 'element' && node.tagName === tagName;
+}
+const isSection = (node) => isElement(node, 'section') && node.properties?.dataFootnotes !== undefined;
+/**
+ * The rehype side of a run: its own section dropped, and each reference given
+ * the number and the id the note gives it.
+ */
+export function rehypeFootnoteRun(options) {
+    return (tree) => {
+        tree.children = (tree.children ?? []).filter((child) => !isSection(child));
+        let index = 0;
+        const walk = (node) => {
+            if (isElement(node, 'a') && node.properties?.dataFootnoteRef !== undefined) {
+                const ref = options.refs[index++];
+                const href = String(node.properties.href ?? '');
+                if (ref && href.startsWith(`#${CLOBBER_PREFIX}fn-`)) {
+                    const safe = href.slice(`#${CLOBBER_PREFIX}fn-`.length);
+                    node.properties.id = `${CLOBBER_PREFIX}fnref-${safe}${ref.occurrence > 1 ? `-${ref.occurrence}` : ''}`;
+                    node.children = [{ type: 'text', value: String(ref.number) }];
+                }
+                return;
+            }
+            for (const child of node.children ?? [])
+                walk(child);
+        };
+        walk(tree);
+    };
+}
+/** The rehype side of the section pass: the section and nothing else. */
+export function rehypeFootnoteSection() {
+    return (tree) => {
+        tree.children = (tree.children ?? []).filter(isSection);
+    };
+}

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);
+}

package/dist/host.d.ts

@@ -0,0 +1,135 @@
+import { type ReactNode } from 'react';
+import { type NoteStrings } from './strings.js';
+/**
+ * The host contract: everything the renderer needs from the notebook a note lives in, given by
+ * whoever draws it.
+ *
+ * The package knows no API, no router, no i18n library and no query cache. What MemorySmith reads
+ * from those reaches the component as these props: functions that answer about the notebook, and
+ * the words the page shows. The host decides; the package draws.
+ *
+ * **Every default is the safe one.** With no `resolve`, every link is pending; with no `keeps`, no
+ * embed reaches a file; with no `renderLink`, an internal address is a plain anchor; with no
+ * `strings`, the words are MemorySmith's English.
+ */
+export interface NoteHost {
+    /**
+     * The address of the one note a link target names, compared after NFC, or `null` when no single
+     * note answers it. The target is a name, literal: never slugified, never stripped of an extension.
+     */
+    readonly resolve?: (name: string) => string | null;
+    /**
+     * How many notes a target reaches, by name or, when no name matches, by alias (§5.2). One is a
+     * link; more than one is a choice; none is pending. Defaults to one when `resolve` answers and
+     * none otherwise.
+     */
+    readonly reaches?: (name: string) => number;
+    /**
+     * The notes a target no single note answers may lead to, asked when its link is clicked. With it,
+     * such a link opens the choice in place — or goes straight to the note, when one answers by
+     * alias. Without it, the link is pending and asks nothing.
+     */
+    readonly choose?: (name: string) => Promise<LinkChoices>;
+    /** The address of the host's page about a target, which a choice link carries for a new tab. */
+    readonly targetAddress?: (name: string) => string | null;
+    /** Goes to an internal address, through the host's router. Defaults to `location.assign`. */
+    readonly navigate?: (address: string) => void;
+    /**
+     * The note a target names, for an embed to draw in place: its body as the host keeps it, its name
+     * and its address. Asked only for a target exactly one note reaches; `null` draws the embed as
+     * pending. Without it, every embed of a note is pending. The package never fetches.
+     */
+    readonly loadNote?: (name: string) => Promise<EmbeddedNote | null>;
+    /**
+     * Whether the reader may tick the task boxes of this note. Defaults to `false`: every box shows
+     * its state and none answers a click.
+     */
+    readonly writable?: boolean;
+    /**
+     * A task box was ticked. The ordinal counts the boxes of the note as the host gave it, frontmatter
+     * included; the host applies it with `toggleTaskAt`, a one-character change of its bytes. The
+     * package never writes the note.
+     */
+    readonly onToggleTask?: (ordinal: number) => void;
+    /** Whether the notebook keeps a file under that name. Only an embed reaches a file. */
+    readonly keeps?: (name: string) => boolean;
+    /**
+     * Draws a file the notebook keeps where a note embeds it: an image, audio, video, or a card. The
+     * dimensions are the ones the embed declared, in CSS pixels, or `null`.
+     */
+    readonly renderAttachment?: (file: AttachmentRequest) => ReactNode;
+    /** Draws a link to an internal address, through the host's router. */
+    readonly renderLink?: (link: LinkRequest) => ReactNode;
+    /** The words the page shows, in the reader's language; each one left out is MemorySmith's English. */
+    readonly strings?: Partial<NoteStrings>;
+    /** The theme the host draws in, which picks the theme of a Mermaid diagram. Defaults to `light`. */
+    readonly theme?: 'light' | 'dark';
+    /**
+     * Whether a note that fetched images from other sites says so, naming them, under the body
+     * (§7.10). Defaults to `true`: the specification forbids only silence. A host that discloses it
+     * elsewhere turns it off and reads the hosts with `remoteImageHosts`.
+     */
+    readonly remoteNotice?: boolean;
+}
+/** What a target that no single note answers may lead to. */
+export interface LinkChoices {
+    /** What matched: the names of notes, their aliases, or nothing. */
+    readonly by: 'name' | 'alias' | null;
+    readonly notes: readonly LinkChoiceNote[];
+}
+/** A note a choice offers. */
+export interface LinkChoiceNote {
+    /** Its name, or `null` for a note that has none. */
+    readonly name: string | null;
+    /** Its address, which the host follows. */
+    readonly address: string;
+    /** The folders from the root down to the one that holds it. */
+    readonly trail: readonly string[];
+    /** What the folder that holds it is for, in the notebook's words. */
+    readonly folderDescription: string;
+}
+/** A note an embed draws in place. */
+export interface EmbeddedNote {
+    /** The note as the host keeps it, frontmatter included. */
+    readonly markdown: string;
+    /** Its name, or `null` for a note that has none. */
+    readonly name: string | null;
+    /** Its address, which the caption under the embed links to, or `null`. */
+    readonly address: string | null;
+}
+/** A file to draw: its name, and the dimensions the embed declared. */
+export interface AttachmentRequest {
+    readonly name: string;
+    readonly width: number | null;
+    readonly height: number | null;
+}
+/** A link to draw through the host's router. */
+export interface LinkRequest {
+    readonly href: string;
+    readonly className?: string;
+    readonly children: ReactNode;
+}
+/**
+ * Every member of the contract, by name. The `satisfies` is what makes it complete: a member added
+ * to `NoteHost` and not listed here does not compile.
+ */
+export declare const HOST_KEYS: (keyof NoteHost)[];
+/** The host contract with every default applied. */
+export interface ResolvedHost {
+    readonly resolve: (name: string) => string | null;
+    readonly reaches: (name: string) => number;
+    readonly choose: ((name: string) => Promise<LinkChoices>) | null;
+    readonly targetAddress: (name: string) => string | null;
+    readonly navigate: (address: string) => void;
+    readonly remoteNotice: boolean;
+    readonly loadNote: ((name: string) => Promise<EmbeddedNote | null>) | null;
+    readonly keeps: (name: string) => boolean;
+    readonly renderAttachment: ((file: AttachmentRequest) => ReactNode) | null;
+    readonly renderLink: (link: LinkRequest) => ReactNode;
+    readonly strings: NoteStrings;
+    readonly theme: 'light' | 'dark';
+}
+export declare function resolveHost(host: NoteHost): ResolvedHost;
+export declare const HostProvider: import("react").Provider<ResolvedHost>;
+/** The host the note is drawn under, read by every part of the surface. */
+export declare function useHost(): ResolvedHost;