@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.0

package/dist/remark-ring.js

@@ -0,0 +1,178 @@
+/**
+ * The rest of the MemorySmith notation, on the reading surface: marked text,
+ * comments, block identifiers (§7.5, §7.6, §7.7) and the dollar rule of
+ * mathematics (§7.8).
+ *
+ * All three are remark plugins rather than passes over the string, for the
+ * reason `remark-callouts.ts` already gives: a `==` inside a code fence is not
+ * a highlight, and only the parser can tell the difference. Rewriting the text
+ * before it is parsed is how a notation starts firing inside examples.
+ *
+ * None of them touches the bytes. The reading surface is a rendering of the
+ * note and never a rewriting of it, so what a host stores and returns is
+ * unaffected by everything here — which is the whole of what makes
+ * `%%comment%%` an asymmetry that has to be declared rather than a deletion.
+ */
+/** Walks every node, letting the visitor rewrite a parent's children. */
+function walk(node, visit) {
+    if (!node.children)
+        return;
+    visit(node);
+    for (const child of node.children)
+        walk(child, visit);
+}
+/** Text nodes carry the raw characters; nothing else is rewritten. */
+function isText(node) {
+    return node.type === 'text';
+}
+/**
+ * `==highlight==` becomes marked text (§7.5).
+ *
+ * It carries no meaning beyond emphasis: no edge, no attribute, no index
+ * entry. The `==` never reaches the screen.
+ */
+const HIGHLIGHT = /==([^=]+)==/g;
+export function remarkHighlight() {
+    return (tree) => walk(tree, (parent) => {
+        parent.children = (parent.children ?? []).flatMap((child) => {
+            if (!isText(child) || !child.value?.includes('=='))
+                return [child];
+            return split(child.value, HIGHLIGHT, (inner) => ({
+                type: 'emphasis',
+                data: { hName: 'mark' },
+                children: [{ type: 'text', value: inner }],
+            }));
+        });
+    });
+}
+/**
+ * `%%comment%%` leaves the page and stays in the file (§7.6).
+ *
+ * The asymmetry is the decision and it is declared, not discovered: the bytes
+ * are untouched, so whatever returns the note returns the comment, and an
+ * agent therefore sees what a person on the page does not. Text the
+ * author did not want *read on the page* is still text the author wrote, and
+ * deleting bytes to make a page tidier is not something this product does.
+ */
+const COMMENT = /%%([\s\S]*?)%%/g;
+export function remarkComments() {
+    return (tree) => walk(tree, (parent) => {
+        parent.children = (parent.children ?? []).flatMap((child) => {
+            if (!isText(child) || !child.value?.includes('%%'))
+                return [child];
+            const stripped = child.value.replace(COMMENT, '');
+            // A text that was nothing but a comment leaves no empty text node
+            // behind. The paragraph that held it stays, empty, as it does on
+            // MemorySmith's reading page.
+            return stripped.length === 0 ? [] : [{ ...child, value: stripped }];
+        });
+    });
+}
+/**
+ * `^identifier` at the end of a block names that block (§7.7), and is never
+ * rendered as text. What it names is resolved by the embed, not here: this
+ * plugin only keeps the marker off the page.
+ */
+const BLOCK_ID = /[ \t]*\^([A-Za-z0-9-]+)[ \t]*$/;
+export function remarkBlockIds() {
+    return (tree) => walk(tree, (parent) => {
+        const children = parent.children ?? [];
+        const last = children[children.length - 1];
+        if (!last || !isText(last) || !last.value?.includes('^'))
+            return;
+        const stripped = last.value.replace(BLOCK_ID, '');
+        if (stripped === last.value)
+            return;
+        if (stripped.length === 0)
+            children.pop();
+        else
+            last.value = stripped;
+    });
+}
+/**
+ * The `$` that is not math (§7.8).
+ *
+ * `remark-math` opens a formula at any `$` and closes it at the next one, so
+ * **two prices in one paragraph become a formula**: `costs $30 a month, and
+ * the plan $60` renders `30 a month, and the plan` as mathematics. That is not
+ * an exotic case, it is a sentence somebody writes on an ordinary day.
+ *
+ * The specification states four prohibitions, and **each one has an outside edge and
+ * an inside edge**. A `$` does not OPEN a formula when it is followed by
+ * whitespace, nor when it is immediately preceded by an alphanumeric; it does
+ * not CLOSE one when it is preceded by whitespace, nor when it is immediately
+ * followed by a digit.
+ *
+ * The inside edges arrived with specification v0.4.0, and they are what keeps a
+ * price whole. `R$ 100` is safe on the outside edge alone, because of the
+ * space. `R$100 e o frete R$200` is not: neither `$` sits next to a space, so
+ * with only the outside edge the sentence loses its middle — `100 e o frete R`
+ * typeset as mathematics, in italic serif, with the `R` and the `200` stranded
+ * either side of it. It is an ordinary sentence in pt-BR, where a price is
+ * written `R$`.
+ *
+ * **The cost is deliberate and the specification names it.** An inline formula
+ * written immediately after a word character no longer opens, so `2$x$` is
+ * text and `2 $x$` is the form that works. A `$` written for any other purpose
+ * belongs in a code span, which is opaque to everything — and for `$HOME` and
+ * `$PATH` in one sentence that is the only thing that protects them, because
+ * both delimiters look legal by every local rule.
+ *
+ * This runs after `remark-math` and gives back to the text any inline formula
+ * that breaks the rule, reading the source the parser read: the delimiters are
+ * gone from the node, and the position is what still knows where they were.
+ * The characters ON either side of the range are what the inside edges need,
+ * which is why the slice reaches one character past each end.
+ *
+ * Block math (`$$…$$`) is untouched: its delimiters are unambiguous.
+ */
+export function remarkMathDollarRule() {
+    return (tree, file) => {
+        const source = typeof file.value === 'string' ? file.value : String(file.value ?? '');
+        if (source.length === 0)
+            return;
+        walk(tree, (parent) => {
+            parent.children = (parent.children ?? []).map((child) => {
+                if (child.type !== 'inlineMath')
+                    return child;
+                const { start, end } = child.position ?? {};
+                if (start?.offset === undefined || end?.offset === undefined)
+                    return child;
+                const raw = source.slice(start.offset, end.offset);
+                const inner = raw.replace(/^\$+/, '').replace(/\$+$/, '');
+                if (inner.length === 0)
+                    return { type: 'text', value: raw };
+                // The outside edges: what sits just inside each delimiter.
+                if (/^\s/.test(inner) || /\s$/.test(inner))
+                    return { type: 'text', value: raw };
+                // The inside edges: what sits just OUTSIDE each delimiter, which is
+                // the half `R$100 e o frete R$200` is decided by.
+                const before = start.offset > 0 ? (source[start.offset - 1] ?? '') : '';
+                const after = source[end.offset] ?? '';
+                if (before !== '' && /[0-9A-Za-z]/.test(before))
+                    return { type: 'text', value: raw };
+                if (after !== '' && /[0-9]/.test(after))
+                    return { type: 'text', value: raw };
+                return child;
+            });
+        });
+    };
+}
+/** Cuts a text node on a pattern, keeping the parts between the matches. */
+function split(value, pattern, make) {
+    const parts = [];
+    let cursor = 0;
+    pattern.lastIndex = 0;
+    for (const match of value.matchAll(pattern)) {
+        const at = match.index ?? 0;
+        if (at > cursor)
+            parts.push({ type: 'text', value: value.slice(cursor, at) });
+        parts.push(make(match[1] ?? ''));
+        cursor = at + match[0].length;
+    }
+    if (parts.length === 0)
+        return [{ type: 'text', value }];
+    if (cursor < value.length)
+        parts.push({ type: 'text', value: value.slice(cursor) });
+    return parts;
+}

package/dist/strings.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The words the reading surface shows of its own, around what a note says.
+ *
+ * The package carries no i18n library: the host gives the words in the language of whoever
+ * reads, and every word it leaves out falls back to the English MemorySmith ships. A callout
+ * kind with no title in `callouts` titles itself, capitalised, as the vault editors do.
+ */
+export interface NoteStrings {
+    /** The title of an untitled callout, by kind (`note`, `warning`, …). */
+    readonly callouts: Readonly<Record<string, string>>;
+    /** The heading of the footnotes gathered at the end of a note. */
+    readonly footnotes: string;
+    /** The label of the way back from a footnote to its reference, counted from 1. */
+    readonly footnoteBack: (number: number) => string;
+    /** The title of a link no note answers yet. */
+    readonly pendingLink: string;
+    /** The title of an address the surface does not follow. */
+    readonly refusedLink: string;
+    /** The title of an embed naming a file the notebook does not keep. */
+    readonly attachmentMissing: string;
+    /** The verb of the button that copies a block of code. */
+    readonly copy: string;
+    /** What that button says once the block is copied. */
+    readonly copied: string;
+    /** The notice under a note that fetched images from other sites, naming them. */
+    readonly remoteImages: (hosts: readonly string[]) => string;
+    /** The accessible name of the choice a link opens. */
+    readonly linkChoice: (target: string) => string;
+    /** The heading of the choice when no note answers the target yet. */
+    readonly linkLeadsNowhere: string;
+    /** The heading of the choice when several notes answer it. */
+    readonly linkLeadsToSeveral: string;
+    /** What the choice says when no note answers the target. */
+    readonly targetPending: (target: string) => string;
+    /** What it says when notes are named the target. */
+    readonly targetNamed: (target: string, count: number) => string;
+    /** What it says when notes carry the target as an alias. */
+    readonly targetAliased: (target: string, count: number) => string;
+    /** What an embed says when the section or block it names is not in the note. */
+    readonly embedSectionMissing: (section: string) => string;
+    /** The caption of a note that has no name. */
+    readonly unnamedNote: string;
+    /** What a region says while it waits for the host. */
+    readonly loading: string;
+    /** What a region says when the host failed to answer. */
+    readonly failed: string;
+    /** The control that closes the choice. */
+    readonly close: string;
+    /** The button that dismisses the choice. */
+    readonly cancel: string;
+}
+/** The words MemorySmith shows in English, used for every word a host does not give. */
+export declare const ENGLISH: NoteStrings;
+/** The host's words over the English ones, key by key. */
+export declare function withDefaults(strings: Partial<NoteStrings> | undefined): NoteStrings;

package/dist/strings.js

@@ -0,0 +1,64 @@
+/** The callout titles of MemorySmith, in English. */
+const CALLOUTS = {
+    note: 'Note',
+    info: 'Info',
+    todo: 'To do',
+    abstract: 'Abstract',
+    summary: 'Summary',
+    tldr: 'TL;DR',
+    tip: 'Tip',
+    hint: 'Hint',
+    important: 'Important',
+    success: 'Success',
+    check: 'Check',
+    done: 'Done',
+    question: 'Question',
+    help: 'Help',
+    faq: 'FAQ',
+    warning: 'Warning',
+    caution: 'Caution',
+    attention: 'Attention',
+    failure: 'Failure',
+    fail: 'Fail',
+    missing: 'Missing',
+    danger: 'Danger',
+    error: 'Error',
+    bug: 'Bug',
+    example: 'Example',
+    quote: 'Quote',
+    cite: 'Cite',
+};
+/** The words MemorySmith shows in English, used for every word a host does not give. */
+export const ENGLISH = {
+    callouts: CALLOUTS,
+    footnotes: 'Notes',
+    footnoteBack: (number) => `Back to reference ${number}`,
+    pendingLink: 'Pending link: the target note does not exist yet.',
+    refusedLink: 'This address is not one the reading surface follows, so the text stays and the link does not.',
+    attachmentMissing: 'This notebook keeps no file under that name.',
+    copy: 'Copy',
+    copied: 'Copied',
+    remoteImages: (hosts) => hosts.length === 1
+        ? `Opening this note fetched an image from ${hosts.join(', ')}, so that site was told your address and the moment you read this.`
+        : `Opening this note fetched images from ${hosts.length} other sites — ${hosts.join(', ')} — so each of them was told your address and the moment you read this.`,
+    linkChoice: (target) => `The notes the link “${target}” may lead to`,
+    linkLeadsNowhere: 'This link leads nowhere yet',
+    linkLeadsToSeveral: 'This link leads to more than one note',
+    targetPending: (target) => `No note carries the name “${target}” yet. The link is kept and resolves on its own when one does.`,
+    targetNamed: (target, count) => count === 1
+        ? `“${target}” is the name of one note.`
+        : `“${target}” is the name of ${count} notes, each in its own folder. Choose which one to open.`,
+    targetAliased: (target, count) => count === 1
+        ? `No note is named “${target}”. One note carries it as an alias.`
+        : `No note is named “${target}”, so it matched ${count} notes that carry it as an alias — and one of them gives the link up the day somebody writes a note under this name.`,
+    embedSectionMissing: (section) => `The section "${section}" is not in this note.`,
+    unnamedNote: 'Unnamed note',
+    loading: 'Loading…',
+    failed: 'Something went wrong.',
+    close: 'Close',
+    cancel: 'Cancel',
+};
+/** The host's words over the English ones, key by key. */
+export function withDefaults(strings) {
+    return { ...ENGLISH, ...strings };
+}

package/dist/tasklist.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Clicking a task box, on the reading surface.
+ *
+ * The package never writes the note: a click reports the ordinal of the box,
+ * and the host applies it with `toggleTaskAt`, which these functions are
+ * exported for. The toggle is POSITIONAL over the original text, never a
+ * re-serialisation. Exactly one character between brackets changes, and
+ * everything else in the document reaches the host's store as the author
+ * wrote it: frontmatter, spacing, line breaks and the rest of the item line
+ * included. That is a requirement, not elegance: `splitFrontmatter` is lossy
+ * by design, because it flattens lists for display, and rebuilding the
+ * document from it would hand the notebook a file nobody typed.
+ */
+/** Offset of the `[` of every real task box, in document order. */
+export declare function taskBoxes(text: string): number[];
+/** How many task items start before this offset: the ordinal of that item. */
+export declare function ordinalAt(text: string, offset: number): number;
+/**
+ * Flips the n-th task box. Returns null when there is no such item, which is
+ * what a stale render looks like, and null is the honest answer: writing the
+ * wrong box would be worse than not writing.
+ */
+export declare function toggleTaskAt(raw: string, ordinal: number): string | null;
+/** Whether the n-th box is checked, for the optimistic state on the screen. */
+export declare function taskCheckedAt(raw: string, ordinal: number): boolean;

package/dist/tasklist.js

@@ -0,0 +1,80 @@
+/**
+ * Clicking a task box, on the reading surface.
+ *
+ * The package never writes the note: a click reports the ordinal of the box,
+ * and the host applies it with `toggleTaskAt`, which these functions are
+ * exported for. The toggle is POSITIONAL over the original text, never a
+ * re-serialisation. Exactly one character between brackets changes, and
+ * everything else in the document reaches the host's store as the author
+ * wrote it: frontmatter, spacing, line breaks and the rest of the item line
+ * included. That is a requirement, not elegance: `splitFrontmatter` is lossy
+ * by design, because it flattens lists for display, and rebuilding the
+ * document from it would hand the notebook a file nobody typed.
+ */
+import { fenceRegions } from './markdown.js';
+/**
+ * A task item, as GFM defines it, at the start of a list item — after any
+ * block quote markers in front of it, because a callout is a block quote and a
+ * checklist is what a `[!todo]` callout holds.
+ *
+ * MemorySmith's reading page counts without them, so a box inside a callout
+ * reported the ordinal of the next box outside it, and ticking it ticked that
+ * other box. Counting the quoted boxes on both sides — the text the parser saw
+ * and the text the host writes — is what keeps the ordinal of every box its
+ * own.
+ */
+const TASK = /^(?:[ \t]*>[ \t]?)*[ \t]*(?:[-*+]|\d+[.)])[ \t]+\[([ xX])\]/gm;
+/**
+ * Blanks out fenced blocks while keeping every offset intact. A task item
+ * inside a fence is an example, not a box, and counting it would shift the
+ * index and toggle a different item: the worst possible defect here, because
+ * it is silent and lands in the wrong place.
+ *
+ * The fences are the ones the reading surface finds, by the rules of the
+ * specification: a longer outer fence holds a shorter inner one, so a box
+ * written after the inner fence closes is still an example.
+ */
+function maskFences(text) {
+    let masked = '';
+    let cursor = 0;
+    for (const [start, end] of fenceRegions(text)) {
+        masked += text.slice(cursor, start) + text.slice(start, end).replace(/[^\n]/g, ' ');
+        cursor = end;
+    }
+    return masked + text.slice(cursor);
+}
+/** Offset of the `[` of every real task box, in document order. */
+export function taskBoxes(text) {
+    const masked = maskFences(text);
+    const found = [];
+    for (const match of masked.matchAll(TASK)) {
+        const at = match.index ?? 0;
+        found.push(at + match[0].length - 3);
+    }
+    return found;
+}
+/** How many task items start before this offset: the ordinal of that item. */
+export function ordinalAt(text, offset) {
+    return taskBoxes(text).filter((box) => box < offset).length;
+}
+/**
+ * Flips the n-th task box. Returns null when there is no such item, which is
+ * what a stale render looks like, and null is the honest answer: writing the
+ * wrong box would be worse than not writing.
+ */
+export function toggleTaskAt(raw, ordinal) {
+    const boxes = taskBoxes(raw);
+    const at = boxes[ordinal];
+    if (at === undefined)
+        return null;
+    // `[x]` lowercase on the way in. GFM reads both cases, and picking one keeps
+    // the diff of a revision about what changed, not about how it was typed.
+    const current = raw[at + 1];
+    const next = current === ' ' ? 'x' : ' ';
+    return `${raw.slice(0, at + 1)}${next}${raw.slice(at + 2)}`;
+}
+/** Whether the n-th box is checked, for the optimistic state on the screen. */
+export function taskCheckedAt(raw, ordinal) {
+    const at = taskBoxes(raw)[ordinal];
+    return at !== undefined && raw[at + 1] !== ' ';
+}

package/dist/transclusion.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Transclusion: `![[note]]` and `![[note#section]]`, expanded for reading.
+ *
+ * The expansion belongs to the reading surface. It is the same class of work
+ * the wikilink resolution already does here: interpreting the notation to
+ * display it. Nothing changes in what the host stores: the body of the
+ * embedded note comes from the host, and the package never fetches.
+ *
+ * ONE LEVEL, AND ONLY ONE. An embed found inside transcluded content is drawn
+ * as a link to its target, which is what keeps a pair of notes that embed each
+ * other from hanging the page.
+ *
+ * **Three places an embed cannot expand, and one answer for all of them.**
+ * Inside embedded content, past the ceiling this file sets, and — since
+ * specification v0.4.0 named it — inside a table cell, because a cell holds inlines
+ * and never blocks (§4.1). Wherever expansion cannot happen the embed becomes
+ * a link and is never dropped, which is what `demoteEmbeds` does.
+ */
+export type BodySegment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'embed';
+    target: string;
+    anchor: string | null;
+};
+/**
+ * How many embeds one page expands. Past it the rest stay as links: the cost
+ * of a page has to stay predictable, and a note with forty embeds is a note
+ * that wanted a different structure.
+ */
+export declare const EMBED_LIMIT = 10;
+/**
+ * Splits a body into what to render inline and what to transclude. Embeds past
+ * the ceiling are demoted to plain wikilinks instead of being dropped, because
+ * losing the reference would be worse than not expanding it.
+ */
+export declare function splitEmbeds(body: string, 
+/**
+ * Whether the notebook keeps a FILE under that name. An embed of one
+ * expands nothing here: it stays in the text run, where the wikilink pass
+ * turns it into the attachment the page draws by its type.
+ */
+keeps?: (name: string) => boolean, limit?: number): BodySegment[];
+/**
+ * `![[x]]` becomes `[[x]]`: a reference instead of an expansion.
+ *
+ * **An embed of a file keeps its `!`**. Demoting exists for an embed
+ * that cannot be expanded here — one inside a table cell, one inside embedded
+ * content — and an attachment is not one of those: the page draws it. Taking
+ * the bang off it was what made `[[picture]]` and `![[picture]]` arrive at the
+ * wikilink pass as the same three characters, so a **link** to a file drew the
+ * file. A link addresses a note (§5.2), and only the embed reaches a file.
+ */
+export declare function demoteEmbeds(body: string, keeps?: (name: string) => boolean): string;
+/**
+ * The block a `^identifier` names, or null when nothing names it (§7.7).
+ *
+ * A block is what the parser would call one: a run of lines up to a blank
+ * line. The identifier sits at the END of it, and the marker is left in the
+ * text on purpose — `remarkBlockIds` takes it off the page, and cutting it
+ * here would mean this function decides what the reader shows.
+ *
+ * An identifier that names nothing answers null, and the caller renders it the
+ * way it renders a pending link. It is never an error: a notebook is read most
+ * while it is being written.
+ */
+export declare function blockOf(markdown: string, identifier: string): string | null;
+/** An anchor written `^id` addresses a block; anything else, a section. */
+export declare function isBlockAnchor(anchor: string): boolean;
+/**
+ * The section of a document, cut syntactically: from the heading whose slug
+ * matches the anchor to the next heading of equal or higher level. No notebook
+ * convention takes part in this: the cut is syntactic.
+ */
+export declare function sectionOf(markdown: string, anchor: string): string | null;

package/dist/transclusion.js

@@ -0,0 +1,161 @@
+/**
+ * Transclusion: `![[note]]` and `![[note#section]]`, expanded for reading.
+ *
+ * The expansion belongs to the reading surface. It is the same class of work
+ * the wikilink resolution already does here: interpreting the notation to
+ * display it. Nothing changes in what the host stores: the body of the
+ * embedded note comes from the host, and the package never fetches.
+ *
+ * ONE LEVEL, AND ONLY ONE. An embed found inside transcluded content is drawn
+ * as a link to its target, which is what keeps a pair of notes that embed each
+ * other from hanging the page.
+ *
+ * **Three places an embed cannot expand, and one answer for all of them.**
+ * Inside embedded content, past the ceiling this file sets, and — since
+ * specification v0.4.0 named it — inside a table cell, because a cell holds inlines
+ * and never blocks (§4.1). Wherever expansion cannot happen the embed becomes
+ * a link and is never dropped, which is what `demoteEmbeds` does.
+ */
+import { codeRegions, headingKey, insideCode, insideTable, outsideCode, tableRegions } from './markdown.js';
+/** Same shape the link extractor matches, plus the leading `!`. */
+const EMBED = /!\[\[([^\]|#]+?)(?:#([^\]|]+?))?(?:\|[^\]]*?)?\]\]/g;
+/**
+ * How many embeds one page expands. Past it the rest stay as links: the cost
+ * of a page has to stay predictable, and a note with forty embeds is a note
+ * that wanted a different structure.
+ */
+export const EMBED_LIMIT = 10;
+/**
+ * Splits a body into what to render inline and what to transclude. Embeds past
+ * the ceiling are demoted to plain wikilinks instead of being dropped, because
+ * losing the reference would be worse than not expanding it.
+ */
+export function splitEmbeds(body, 
+/**
+ * Whether the notebook keeps a FILE under that name. An embed of one
+ * expands nothing here: it stays in the text run, where the wikilink pass
+ * turns it into the attachment the page draws by its type.
+ */
+keeps = () => false, limit = EMBED_LIMIT) {
+    const segments = [];
+    const code = codeRegions(body);
+    const tables = tableRegions(body);
+    let cursor = 0;
+    let expanded = 0;
+    for (const match of body.matchAll(EMBED)) {
+        const at = match.index ?? 0;
+        const target = (match[1] ?? '').trim();
+        if (!target)
+            continue;
+        // A file is not a note, so there is nothing to transclude: it is left in
+        // the text run, where the wikilink pass turns it into the attachment the
+        // page draws by its type.
+        if (keeps(target))
+            continue;
+        // An embed written inside code is an example of the notation, not a use of
+        // it: expanding it would replace the very text somebody was showing.
+        if (insideCode(code, at))
+            continue;
+        // An embed inside a table cell is drawn as a link (§7.3): no block
+        // fits in a cell. Skipping it here leaves it in the surrounding text run,
+        // where `demoteEmbeds` turns it into the wikilink the specification asks for —
+        // and, just as importantly, keeps the run from being cut mid-row, which
+        // used to empty the cell and leave the closing pipe as a paragraph.
+        if (insideTable(tables, at))
+            continue;
+        if (expanded >= limit)
+            break;
+        // Demoted like the tail is, and for the embeds this loop SKIPPED: one in
+        // a table cell lands in a run before an expanded one, and without this it
+        // would reach the page as the literal `![[…]]` — dropped notation, which
+        // is the one thing §7.3 forbids in every place expansion cannot happen.
+        // Code is untouched, because `demoteEmbeds` rewrites outside it.
+        const before = demoteEmbeds(body.slice(cursor, at), keeps);
+        if (before.length > 0)
+            segments.push({ kind: 'text', text: before });
+        segments.push({ kind: 'embed', target, anchor: match[2]?.trim() ?? null });
+        cursor = at + match[0].length;
+        expanded += 1;
+    }
+    const rest = body.slice(cursor);
+    if (rest.length > 0)
+        segments.push({ kind: 'text', text: demoteEmbeds(rest, keeps) });
+    return segments;
+}
+/**
+ * `![[x]]` becomes `[[x]]`: a reference instead of an expansion.
+ *
+ * **An embed of a file keeps its `!`**. Demoting exists for an embed
+ * that cannot be expanded here — one inside a table cell, one inside embedded
+ * content — and an attachment is not one of those: the page draws it. Taking
+ * the bang off it was what made `[[picture]]` and `![[picture]]` arrive at the
+ * wikilink pass as the same three characters, so a **link** to a file drew the
+ * file. A link addresses a note (§5.2), and only the embed reaches a file.
+ */
+export function demoteEmbeds(body, keeps = () => false) {
+    return outsideCode(body, (text) => text.replace(EMBED, (all, target) => (keeps(target.trim()) ? all : all.slice(1))));
+}
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+/**
+ * The block a `^identifier` names, or null when nothing names it (§7.7).
+ *
+ * A block is what the parser would call one: a run of lines up to a blank
+ * line. The identifier sits at the END of it, and the marker is left in the
+ * text on purpose — `remarkBlockIds` takes it off the page, and cutting it
+ * here would mean this function decides what the reader shows.
+ *
+ * An identifier that names nothing answers null, and the caller renders it the
+ * way it renders a pending link. It is never an error: a notebook is read most
+ * while it is being written.
+ */
+export function blockOf(markdown, identifier) {
+    const marker = new RegExp(`[ \\t]\\^${escapeRegExp(identifier)}[ \\t]*$`);
+    const lines = markdown.split('\n');
+    for (let index = 0; index < lines.length; index++) {
+        if (!marker.test(lines[index] ?? ''))
+            continue;
+        // Walk back to the top of the block: the first line after a blank one.
+        let start = index;
+        while (start > 0 && (lines[start - 1] ?? '').trim().length > 0)
+            start--;
+        return lines
+            .slice(start, index + 1)
+            .join('\n')
+            .trimEnd();
+    }
+    return null;
+}
+/** An anchor written `^id` addresses a block; anything else, a section. */
+export function isBlockAnchor(anchor) {
+    return anchor.startsWith('^');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * The section of a document, cut syntactically: from the heading whose slug
+ * matches the anchor to the next heading of equal or higher level. No notebook
+ * convention takes part in this: the cut is syntactic.
+ */
+export function sectionOf(markdown, anchor) {
+    const wanted = headingKey(anchor);
+    const lines = markdown.split('\n');
+    let start = -1;
+    let level = 0;
+    for (let index = 0; index < lines.length; index++) {
+        const heading = HEADING.exec(lines[index] ?? '');
+        if (!heading)
+            continue;
+        if (start === -1) {
+            if (headingKey(heading[2] ?? '') === wanted) {
+                start = index;
+                level = (heading[1] ?? '').length;
+            }
+            continue;
+        }
+        if ((heading[1] ?? '').length <= level) {
+            return lines.slice(start, index).join('\n').trimEnd();
+        }
+    }
+    return start === -1 ? null : lines.slice(start).join('\n').trimEnd();
+}

package/dist/wikilink-address.d.ts

@@ -0,0 +1,8 @@
+import type { ResolvedHost } from './host.js';
+/**
+ * Where a wikilink goes: the note when exactly one answers it, and the choice
+ * otherwise — several notes, or none, which is pending and still asks — when
+ * the host can say which notes a target may lead to. With no such host, a
+ * target no single note answers is pending.
+ */
+export declare function wikilinkAddress(host: ResolvedHost, name: string): string | null;

package/dist/wikilink-address.js

@@ -0,0 +1,13 @@
+import { CHOICE_SCHEME } from './LinkChoice.js';
+/**
+ * Where a wikilink goes: the note when exactly one answers it, and the choice
+ * otherwise — several notes, or none, which is pending and still asks — when
+ * the host can say which notes a target may lead to. With no such host, a
+ * target no single note answers is pending.
+ */
+export function wikilinkAddress(host, name) {
+    const address = host.resolve(name);
+    if (address !== null)
+        return address;
+    return host.choose ? `${CHOICE_SCHEME}${encodeURIComponent(name)}` : null;
+}