@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.1

package/dist/host.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+import { withDefaults } from './strings.js';
+/**
+ * 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 const HOST_KEYS = Object.keys({
+    resolve: 1,
+    reaches: 1,
+    choose: 1,
+    targetAddress: 1,
+    navigate: 1,
+    loadNote: 1,
+    writable: 1,
+    onToggleTask: 1,
+    keeps: 1,
+    renderAttachment: 1,
+    renderLink: 1,
+    strings: 1,
+    theme: 1,
+    remoteNotice: 1,
+});
+const nothing = () => null;
+const never = () => false;
+const plainLink = ({ href, className, children }) => (_jsx("a", { className: className, href: href, children: children }));
+export function resolveHost(host) {
+    const resolve = host.resolve ?? nothing;
+    return {
+        resolve,
+        reaches: host.reaches ?? ((name) => (resolve(name) === null ? 0 : 1)),
+        choose: host.choose ?? null,
+        targetAddress: host.targetAddress ?? nothing,
+        navigate: host.navigate ?? ((address) => window.location.assign(address)),
+        remoteNotice: host.remoteNotice ?? true,
+        loadNote: host.loadNote ?? null,
+        keeps: host.keeps ?? never,
+        renderAttachment: host.renderAttachment ?? null,
+        renderLink: host.renderLink ?? plainLink,
+        strings: withDefaults(host.strings),
+        theme: host.theme ?? 'light',
+    };
+}
+const HostContext = createContext(resolveHost({}));
+export const HostProvider = HostContext.Provider;
+/** The host the note is drawn under, read by every part of the surface. */
+export function useHost() {
+    return useContext(HostContext);
+}

package/dist/image-dimensions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The pipe inside the alt text of an image, which separates the description
+ * from the dimensions (`SPEC.md` §3.14).
+ *
+ * `![Engelbart|100x145](engelbart.jpg)` is 100 by 145 CSS pixels and
+ * `![Engelbart|100](…)` is 100 wide with the aspect ratio kept. What precedes
+ * the pipe is the **description** and is never dropped — it is what a person
+ * gets when the image does not load, and it is what a screen reader says.
+ *
+ * **A value that is neither form is not a dimension.** `![Engelbart|large](…)`
+ * keeps `Engelbart|large` as the whole description, because deleting what an
+ * author wrote into an accessibility label is the worse of the two failures.
+ * Until the specification declared this form, an imported note displayed the
+ * pipe and the digits on screen and mandated the whole string as the label.
+ */
+export interface ImageAlt {
+    /** What a reader hears, and sees when the image does not load. */
+    readonly description: string;
+    readonly width: number | null;
+    readonly height: number | null;
+}
+/**
+ * What follows a pipe, when it is a dimension and not text.
+ *
+ * The wikilink embed of an attachment carries the same thing the alt text of a
+ * Markdown image does — `![[engelbart.jpg|100x145]]` and
+ * `![Engelbart|100x145](…)` mean one thing — so both read it here.
+ */
+export declare function readDimensions(value: string): {
+    width: number;
+    height: number | null;
+} | null;
+export declare function readImageAlt(alt: string): ImageAlt;

package/dist/image-dimensions.js

@@ -0,0 +1,42 @@
+/**
+ * The pipe inside the alt text of an image, which separates the description
+ * from the dimensions (`SPEC.md` §3.14).
+ *
+ * `![Engelbart|100x145](engelbart.jpg)` is 100 by 145 CSS pixels and
+ * `![Engelbart|100](…)` is 100 wide with the aspect ratio kept. What precedes
+ * the pipe is the **description** and is never dropped — it is what a person
+ * gets when the image does not load, and it is what a screen reader says.
+ *
+ * **A value that is neither form is not a dimension.** `![Engelbart|large](…)`
+ * keeps `Engelbart|large` as the whole description, because deleting what an
+ * author wrote into an accessibility label is the worse of the two failures.
+ * Until the specification declared this form, an imported note displayed the
+ * pipe and the digits on screen and mandated the whole string as the label.
+ */
+/** `100` or `100x145`, and nothing else. */
+const DIMENSIONS = /^(\d{1,5})(?:x(\d{1,5}))?$/;
+/**
+ * What follows a pipe, when it is a dimension and not text.
+ *
+ * The wikilink embed of an attachment carries the same thing the alt text of a
+ * Markdown image does — `![[engelbart.jpg|100x145]]` and
+ * `![Engelbart|100x145](…)` mean one thing — so both read it here.
+ */
+export function readDimensions(value) {
+    const measured = DIMENSIONS.exec(value.trim());
+    if (!measured)
+        return null;
+    return {
+        width: Number(measured[1]),
+        height: measured[2] === undefined ? null : Number(measured[2]),
+    };
+}
+export function readImageAlt(alt) {
+    const at = alt.lastIndexOf('|');
+    if (at === -1)
+        return { description: alt, width: null, height: null };
+    const measured = readDimensions(alt.slice(at + 1));
+    if (!measured)
+        return { description: alt, width: null, height: null };
+    return { description: alt.slice(0, at).trim(), width: measured.width, height: measured.height };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { NoteBody, type NoteBodyProps } from './NoteBody.js';
+export type { AttachmentRequest, EmbeddedNote, LinkChoiceNote, LinkChoices, LinkRequest, NoteHost } from './host.js';
+export { ENGLISH, type NoteStrings } from './strings.js';
+export { followable } from './address.js';
+export { readDimensions, readImageAlt, type ImageAlt } from './image-dimensions.js';
+export { codeRegions, fenceRegions, headingKey, remoteImageHosts, resolveWikilinks, splitFrontmatter, tableRegions, toUnixNewlines, type SplitDocument, } from './markdown.js';
+export { ordinalAt, taskBoxes, taskCheckedAt, toggleTaskAt } from './tasklist.js';
+export { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+// The entry point of @memorysmithapp/markdown-renderer.
+export { NoteBody } from './NoteBody.js';
+export { ENGLISH } from './strings.js';
+export { followable } from './address.js';
+export { readDimensions, readImageAlt } from './image-dimensions.js';
+export { codeRegions, fenceRegions, headingKey, remoteImageHosts, resolveWikilinks, splitFrontmatter, tableRegions, toUnixNewlines, } from './markdown.js';
+export { ordinalAt, taskBoxes, taskCheckedAt, toggleTaskAt } from './tasklist.js';
+export { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';

package/dist/markdown.d.ts

@@ -0,0 +1,68 @@
+export interface SplitDocument {
+    frontmatter: Record<string, string>;
+    /**
+     * Which of those keys the notebook wrote as a list, whether in a dash block or
+     * inline. The values are flattened to one comma-separated string so the
+     * table can print them, and that flattening is lossy: `tags: a, b` and a
+     * two-item list read the same afterwards. The set keeps the difference,
+     * because a list is drawn as chips and a sentence is not, and guessing from
+     * the commas would turn a prose value that happens to have one into chips.
+     */
+    lists: Set<string>;
+    body: string;
+}
+/**
+ * A note is bytes the notebook wrote, and a notebook written on Windows, or in a
+ * desktop editor, or pasted from anywhere, carries CRLF. Every reader in this
+ * module starts here, because a carriage return left at the end of a line is
+ * invisible in the source and fatal to a regex: `.` does not match one, so
+ * `(.*)$` fails on exactly the lines that have a value.
+ */
+export declare function toUnixNewlines(raw: string): string;
+/**
+ * Where the body of a note starts: after its frontmatter, which a host shows as properties and
+ * not as prose. The cut is the one MemorySmith's reading page makes, so the ordinals of the task
+ * boxes below it are counted over the whole note, as the host stores it.
+ */
+export declare function bodyStart(text: string): number;
+/**
+ * The frontmatter block, read the way MemorySmith's reading page reads it to show a note's
+ * properties. The package does not draw it — `NoteBody` starts after it — and exports this so a
+ * host that draws the properties reads the same values MemorySmith does.
+ */
+export declare function splitFrontmatter(input: string): SplitDocument;
+/** The half-open ranges of `body` that are fenced blocks. */
+export declare function fenceRegions(body: string): Array<[number, number]>;
+/** The half-open ranges of `body` that are code, fenced or inline, in order. */
+export declare function codeRegions(body: string): Array<[number, number]>;
+/** Whether an offset falls inside one of them. */
+export declare function insideCode(regions: Array<[number, number]>, at: number): boolean;
+export declare function tableRegions(body: string): Array<[number, number]>;
+/** Whether an offset falls inside one of them. */
+export declare function insideTable(regions: Array<[number, number]>, at: number): boolean;
+/** Runs a rewrite over everything except code, which is copied through. */
+export declare function outsideCode(body: string, rewrite: (text: string) => string): string;
+export declare function resolveWikilinks(body: string, resolve: (name: string) => string | null, 
+/**
+ * Whether the notebook keeps a FILE under that name. The extension of a
+ * name decides nothing, so what a target is cannot be read off it: it is
+ * read off what the notebook holds, which is the host's to answer.
+ */
+keeps?: (name: string) => boolean): string;
+/**
+ * The key a **heading** is matched by, which is how an anchor finds the
+ * section it names inside a note.
+ *
+ * **It is not the key of a note, and there is no longer one of those.** A link
+ * resolves against the name, literally and case-exact (§5.2), so the
+ * slug this file used to compute — the second implementation of a rule the
+ * kernel also implemented, and the one that drifted — is gone. What is
+ * left is this: an anchor and a heading are two spellings of the same phrase,
+ * written by the same person minutes apart, and folding case and punctuation
+ * between them is what makes `#Artigo 75` find `## Artigo 75`.
+ *
+ * Nothing outside this comparison reads it, and nothing else in the renderer
+ * computes a key from a name: the address of a note is the host's to give.
+ */
+export declare function headingKey(name: string): string;
+export declare function remoteImageHosts(body: string): string[];

package/dist/markdown.js

@@ -0,0 +1,395 @@
+// The text helpers of the reading surface: what a note becomes before the parser reads it.
+// Nothing here rewrites the note a host keeps; each function returns a new string for display.
+import { readDimensions } from './image-dimensions.js';
+/**
+ * A note is bytes the notebook wrote, and a notebook written on Windows, or in a
+ * desktop editor, or pasted from anywhere, carries CRLF. Every reader in this
+ * module starts here, because a carriage return left at the end of a line is
+ * invisible in the source and fatal to a regex: `.` does not match one, so
+ * `(.*)$` fails on exactly the lines that have a value.
+ */
+export function toUnixNewlines(raw) {
+    return raw.replace(/\r\n?/g, '\n');
+}
+/**
+ * Where the body of a note starts: after its frontmatter, which a host shows as properties and
+ * not as prose. The cut is the one MemorySmith's reading page makes, so the ordinals of the task
+ * boxes below it are counted over the whole note, as the host stores it.
+ */
+export function bodyStart(text) {
+    return text.startsWith('---') ? text.indexOf('\n---', 3) + 4 : 0;
+}
+/**
+ * Strips one layer of matching quotes, as the facet projector does. The trim
+ * comes first: an item of an inline list arrives with the space that followed
+ * the comma, and a quote that is not at position zero is not stripped.
+ */
+function unquote(value) {
+    return value
+        .trim()
+        .replace(/^["']|["']$/g, '')
+        .trim();
+}
+/**
+ * The frontmatter block, read the way MemorySmith's reading page reads it to show a note's
+ * properties. The package does not draw it — `NoteBody` starts after it — and exports this so a
+ * host that draws the properties reads the same values MemorySmith does.
+ */
+export function splitFrontmatter(input) {
+    const raw = toUnixNewlines(input);
+    const bare = { frontmatter: {}, lists: new Set(), body: raw };
+    if (!raw.startsWith('---'))
+        return bare;
+    const end = raw.indexOf('\n---', 3);
+    if (end === -1)
+        return bare;
+    const head = raw.slice(raw.indexOf('\n') + 1, end);
+    const body = raw.slice(raw.indexOf('\n', end + 1) + 1);
+    const frontmatter = {};
+    const lists = new Set();
+    let lastKey = null;
+    for (const line of head.split('\n')) {
+        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+        if (kv && kv[1]) {
+            lastKey = kv[1];
+            const value = (kv[2] ?? '').trim();
+            // An inline list becomes the same comma-separated string a dash list
+            // produces, so `tags: [a, b]` and a `tags:` block read alike from here.
+            const inlineList = value.startsWith('[') && value.endsWith(']');
+            if (inlineList)
+                lists.add(lastKey);
+            frontmatter[lastKey] = inlineList
+                ? value
+                    .slice(1, -1)
+                    .split(',')
+                    .map(unquote)
+                    .filter((item) => item.length > 0)
+                    .join(', ')
+                : unquote(value);
+        }
+        else if (lastKey && /^\s+-\s+/.test(line)) {
+            const item = unquote(line.replace(/^\s+-\s+/, ''));
+            lists.add(lastKey);
+            frontmatter[lastKey] = frontmatter[lastKey] ? `${frontmatter[lastKey]}, ${item}` : item;
+        }
+    }
+    return { frontmatter, lists, body };
+}
+/**
+ * A wikilink, with the `!` in front of it when it is an embed.
+ *
+ * The bang is captured and not assumed away, because it is what tells a
+ * **link** from an **embed**, and the two reach different things: a link
+ * addresses a note and nothing else (§5.2), while an embed may also name a
+ * file the notebook keeps (§5.8). By the time this pass runs, the bang of a
+ * note embed has been taken off by `demoteEmbeds` — an embed that could not be
+ * expanded is a reference — so what still carries one is an embed of a file.
+ */
+const WIKILINK = /(!)?\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]/g;
+/**
+ * Code, where notation is characters and nothing else.
+ *
+ * A fenced block parses nothing inside it and a code span is where an author
+ * writes notation without invoking it — both stated by the specification, in the
+ * `code-fenced` and `code-span` entries of `spec.json`. The rewrites below
+ * run over the raw text BEFORE the parser sees it, so they are the one place
+ * in the renderer that has to know that on its own: every other reading of
+ * the notation is a remark plugin, working on a tree where a code node is
+ * already a code node.
+ *
+ * Code is found by the rules the specification states and never by a pattern of
+ * backticks: a fence opens on a line whose first thing is a run of
+ * three or more backticks or tildes, closes on a line holding a run of the
+ * same character, at least as long, and nothing else, and otherwise runs to
+ * the end of the note; a code span closes on a run of exactly its own length.
+ * A pattern pairing any two runs of three backticks read a span SHOWING three
+ * backticks as an opening fence, and every block after it out of phase. The
+ * link extractor of MemorySmith reads code by the same rules, and both are held
+ * to the `link-in-code` cases of the conformance suite.
+ *
+ * The indented form is deliberately NOT here, and the reason is the cost of
+ * being wrong. Telling four spaces of code from four spaces of a nested list
+ * item needs the block context only a parser has; guessing it wrong turns a
+ * real link into text, and the same guess in the link extractor would drop a
+ * real edge. A wikilink written inside an indented code block is therefore
+ * still read, in both readers, and that is declared rather than discovered
+ * in MemorySmith's architecture. For the same reason a fence is accepted
+ * after whatever its list item or block quote puts in front of it, and a code
+ * span is not followed across a line break.
+ */
+const CONTAINER = String.raw `(?:[ \t]*(?:>[ \t]?|(?:[-*+]|\d{1,9}[.)])[ \t]+))*[ \t]*`;
+const OPENING_FENCE = new RegExp(`^(${CONTAINER})(\`{3,}|~{3,})(.*?)\r?$`);
+const CLOSING_FENCE = new RegExp(`^${CONTAINER}(\`{3,}|~{3,})[ \t]*\r?$`);
+/**
+ * The fenced blocks of `body`, as half-open ranges from the opening run to the
+ * end of the closing line, and the lines no fence holds, which are where code
+ * spans may be.
+ */
+function scanFences(body) {
+    const fences = [];
+    const prose = [];
+    let open = null;
+    let at = 0;
+    for (const line of body.split('\n')) {
+        const end = at + line.length;
+        if (open) {
+            const run = CLOSING_FENCE.exec(line)?.[1];
+            if (run && run[0] === open.char && run.length >= open.length) {
+                fences.push([open.start, end]);
+                open = null;
+            }
+        }
+        else {
+            const fence = OPENING_FENCE.exec(line);
+            const run = fence?.[2] ?? '';
+            // A backtick fence may not carry a backtick in its info string: such a
+            // line is a paragraph, and what looks like a fence in it is a span.
+            if (fence && !(run[0] === '`' && (fence[3] ?? '').includes('`'))) {
+                open = { char: run[0] ?? '`', length: run.length, start: at + (fence[1] ?? '').length };
+            }
+            else {
+                prose.push({ line, at });
+            }
+        }
+        at = end + 1;
+    }
+    if (open)
+        fences.push([open.start, body.length]);
+    return { fences, prose };
+}
+/**
+ * The code spans of one line: a run of backticks closes on the next run of
+ * exactly its length, a run with no partner is text, and a backtick escaped by
+ * a backslash opens nothing.
+ */
+function codeSpans(line, offset) {
+    const runs = [...line.matchAll(/`+/g)].map((match) => ({
+        index: match.index ?? 0,
+        length: match[0].length,
+    }));
+    const spans = [];
+    for (let i = 0; i < runs.length; i++) {
+        const run = runs[i];
+        if (!run)
+            continue;
+        const escaped = /(^|[^\\])(\\\\)*\\$/.test(line.slice(0, run.index));
+        const start = escaped ? run.index + 1 : run.index;
+        const length = escaped ? run.length - 1 : run.length;
+        if (length === 0)
+            continue;
+        const close = runs.findIndex((other, j) => j > i && other.length === length);
+        const closing = runs[close];
+        if (close === -1 || !closing)
+            continue;
+        spans.push([offset + start, offset + closing.index + closing.length]);
+        i = close;
+    }
+    return spans;
+}
+/** The half-open ranges of `body` that are fenced blocks. */
+export function fenceRegions(body) {
+    return scanFences(body).fences;
+}
+/** The half-open ranges of `body` that are code, fenced or inline, in order. */
+export function codeRegions(body) {
+    const { fences, prose } = scanFences(body);
+    const spans = prose.flatMap(({ line, at }) => codeSpans(line, at));
+    return [...fences, ...spans].sort((a, b) => a[0] - b[0]);
+}
+/** Whether an offset falls inside one of them. */
+export function insideCode(regions, at) {
+    return regions.some(([start, end]) => at >= start && at < end);
+}
+/**
+ * A GFM table, which is the third place an embed cannot expand (§7.3).
+ *
+ * A cell holds inlines and never blocks (§4.1), so an embed of a note in a
+ * cell is drawn as a link, the same answer the one-level rule and the embed
+ * ceiling already give. What made this its own case is that the expansion is
+ * decided on the raw string, by cutting the body into runs around each
+ * `![[…]]`, and a cut inside a table row does not merely fail to expand: it
+ * ends the run mid-row, so the parser that reads it has an unterminated table
+ * and the closing pipe becomes a paragraph of its own.
+ *
+ * Detected here rather than in a plugin for the reason the code regions
+ * already are: the split happens before anything is parsed, so this is the one
+ * place in the renderer that has to recognise the block on its own.
+ *
+ * A table is a line containing a pipe, followed by a delimiter row of dashes,
+ * and it runs to the first blank line. The outer pipes are optional, which is
+ * why the delimiter row is what identifies the block. A shape this misses
+ * costs nothing new — it is the behaviour of before — so the pattern is
+ * deliberately the conservative one.
+ */
+const DELIMITER_ROW = /^ {0,3}\|?[ \t]*:?-{1,}:?[ \t]*(\|[ \t]*:?-{1,}:?[ \t]*)*\|?[ \t]*$/;
+export function tableRegions(body) {
+    const regions = [];
+    const code = codeRegions(body);
+    const lines = body.split('\n');
+    const offsets = [];
+    let at = 0;
+    for (const line of lines) {
+        offsets.push(at);
+        at += line.length + 1;
+    }
+    for (let index = 0; index + 1 < lines.length; index++) {
+        const header = lines[index] ?? '';
+        const delimiter = lines[index + 1] ?? '';
+        if (!header.includes('|') || !delimiter.includes('|'))
+            continue;
+        if (!DELIMITER_ROW.test(delimiter))
+            continue;
+        if (insideCode(code, offsets[index] ?? 0))
+            continue;
+        let last = index + 1;
+        while (last + 1 < lines.length && (lines[last + 1] ?? '').trim().length > 0)
+            last++;
+        regions.push([offsets[index] ?? 0, (offsets[last] ?? 0) + (lines[last] ?? '').length]);
+        index = last;
+    }
+    return regions;
+}
+/** Whether an offset falls inside one of them. */
+export function insideTable(regions, at) {
+    return regions.some(([start, end]) => at >= start && at < end);
+}
+/** Runs a rewrite over everything except code, which is copied through. */
+export function outsideCode(body, rewrite) {
+    let out = '';
+    let cursor = 0;
+    for (const [start, end] of codeRegions(body)) {
+        out += rewrite(body.slice(cursor, start)) + body.slice(start, end);
+        cursor = end;
+    }
+    return out + rewrite(body.slice(cursor));
+}
+// Replaces [[wikilinks]] with markdown links. Resolved targets point at the
+// note route; unresolved ones become pending: links styled by the renderer.
+export function resolveWikilinks(body, resolve, 
+/**
+ * Whether the notebook keeps a FILE under that name. The extension of a
+ * name decides nothing, so what a target is cannot be read off it: it is
+ * read off what the notebook holds, which is the host's to answer.
+ */
+keeps = () => false) {
+    return outsideCode(body, (text) => resolveWikilinksIn(text, resolve, keeps));
+}
+/**
+ * The target of a wikilink is a NAME, and it is literal: nothing in it is
+ * decoded, no extension is removed and no path segment is discarded
+ * (§5.2). It used to be slugified here, which is what made a link differ
+ * from its note over an accent or a capital.
+ */
+function resolveWikilinksIn(body, resolve, keeps) {
+    return body.replace(WIKILINK, (_all, bang, target, label) => {
+        const clean = target.split('#')[0]?.trim().replace(/\\$/, '').trim() ?? '';
+        const embed = bang !== undefined;
+        const text = displayText(clean, label, target, (name) => embed && keeps(name));
+        if (!clean)
+            return `[${text}](pending:)`;
+        // The pipe is read by WHAT THE TARGET IS: a note takes the alias, an
+        // attachment takes the dimensions, and a target that resolves to neither
+        // takes the alias — because reading it as a dimension would discard text
+        // an author wrote.
+        //
+        // **Only an embed reaches a file**. A `[[name]]` is resolved against
+        // the notes of the notebook and their aliases, and against nothing else:
+        // §5.2 lists the whole of resolution and an attachment is in none of its
+        // steps, so a name only a file carries is a pending link like any other.
+        if (embed && keeps(clean)) {
+            // The dimension travels with the address, because the name is already
+            // percent-encoded and a bare `|` after it cannot be part of it.
+            // Dropping it here is what made `![[picture|120]]` render at full size:
+            // the notation was read and then thrown away one line before it was used.
+            const measured = label === undefined ? null : readDimensions(label);
+            const sized = measured
+                ? `|${measured.width}${measured.height === null ? '' : `x${measured.height}`}`
+                : '';
+            return `[${text}](attachment:${encodeURIComponent(clean)}${sized})`;
+        }
+        const url = resolve(clean.normalize('NFC'));
+        return url ? `[${text}](${url})` : `[${text}](pending:${encodeURIComponent(clean)})`;
+    });
+}
+/**
+ * What the link shows. The pipe of an attachment carries dimensions and is
+ * never rendered as text, so what is left to show is the name of the file.
+ */
+function displayText(clean, label, target, keeps) {
+    if (clean && keeps(clean))
+        return clean;
+    return (label ?? target).trim();
+}
+/** The longest a heading key may be, which is what an anchor is matched on. */
+const MAX_KEY_LENGTH = 80;
+/**
+ * The key a **heading** is matched by, which is how an anchor finds the
+ * section it names inside a note.
+ *
+ * **It is not the key of a note, and there is no longer one of those.** A link
+ * resolves against the name, literally and case-exact (§5.2), so the
+ * slug this file used to compute — the second implementation of a rule the
+ * kernel also implemented, and the one that drifted — is gone. What is
+ * left is this: an anchor and a heading are two spellings of the same phrase,
+ * written by the same person minutes apart, and folding case and punctuation
+ * between them is what makes `#Artigo 75` find `## Artigo 75`.
+ *
+ * Nothing outside this comparison reads it, and nothing else in the renderer
+ * computes a key from a name: the address of a note is the host's to give.
+ */
+export function headingKey(name) {
+    return name
+        .normalize('NFD')
+        .replace(/(\d)[.,](\d)/g, '$1$2')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, MAX_KEY_LENGTH)
+        .replace(/-+$/g, '');
+}
+/**
+ * The hosts a note asks the reader's browser to talk to (§7.10).
+ *
+ * An image whose destination names a host is a **request to that host**, made
+ * when the note is opened, by whoever opens it — and the trigger was written
+ * by whoever wrote the note, which is the same sentence §7.9 uses about raw
+ * HTML. What travels with it is the reader's address, their user-agent and the
+ * moment they read it.
+ *
+ * The specification admits three answers and forbids only silence: never fetching,
+ * fetching on the reader's action, or fetching and saying so. MemorySmith,
+ * and this renderer with it, gives the third, so this is the half that says so. It is the image of §3.14
+ * and nothing else: a diagram and a formula render locally, and a link —
+ * bracketed, bare or autolinked — is a navigation the person initiates rather
+ * than a request the page makes.
+ *
+ * Code is excluded, because an image written inside a fence is an example of
+ * the notation and fetches nothing.
+ */
+const IMAGE_DESTINATION = /!\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+export function remoteImageHosts(body) {
+    const regions = codeRegions(body);
+    const hosts = new Set();
+    for (const match of body.matchAll(IMAGE_DESTINATION)) {
+        if (insideCode(regions, match.index ?? 0))
+            continue;
+        const destination = (match[1] ?? '').trim();
+        // A path, a relative target or an anchor names no host and asks nobody
+        // for anything. Only a scheme or a leading `//` reaches outside.
+        const authority = /^[a-z][a-z0-9+.-]*:\/\//i.test(destination)
+            ? destination.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '')
+            : destination.startsWith('//')
+                ? destination.slice(2)
+                : '';
+        if (authority === '')
+            continue;
+        // The authority, minus any credentials, port and path: what a person needs
+        // in order to recognise who they just talked to.
+        const host = (authority.split('/')[0] ?? '').split('@').pop() ?? '';
+        const named = host.split(':')[0] ?? '';
+        if (named !== '')
+            hosts.add(named.toLowerCase());
+    }
+    return [...hosts];
+}

package/dist/remark-callouts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Notebook callouts, rendered as callouts.
+ *
+ * A callout is a blockquote whose first line is a type marker:
+ *
+ *     > [!warning] O que pode dar errado
+ *     > O corpo do aviso.
+ *
+ * It is a notebook convention and not universal Markdown (§7.1). What
+ * MemorySmith's reading page once did was a pass over the
+ * string that swapped the marker for an emoji and left the blockquote behind,
+ * which reads as a quotation with a picture in front of it. This turns it into
+ * the element the vault editors draw, and the type travels to the DOM as an
+ * attribute so the stylesheet can colour and ice it without a class per type.
+ *
+ * It is a remark plugin rather than another pass over the string because the
+ * marker has to leave the tree the renderer walks, not the text the parser
+ * reads: a `[!note]` inside a code fence is not a callout, and only the parser
+ * can tell the difference.
+ */
+interface MdastNode {
+    type: string;
+    value?: string;
+    children?: MdastNode[];
+    data?: {
+        hName?: string;
+        hProperties?: Record<string, unknown>;
+    };
+}
+export interface CalloutOptions {
+    /**
+     * The title of a callout written without one, in the language of whoever
+     * reads it. It answers `undefined` for a type it has no word for,
+     * and that type titles itself, capitalised, as the editors do: the
+     * vocabulary is open (§7.1) and a word nobody translated is still a word.
+     */
+    readonly titleOf?: (kind: string) => string | undefined;
+}
+export declare function remarkCallouts(options?: CalloutOptions): (tree: MdastNode) => void;
+export {};