@memorysmithapp/markdown-renderer 0.0.0-stage → 0.1.1

package/dist/remark-callouts.js

@@ -0,0 +1,108 @@
+/**
+ * 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.
+ */
+/** `[!type]`, an optional fold marker, and whatever titles it. */
+const MARKER = /^\[!([A-Za-z][\w-]*)\][+-]?[ \t]*(.*)$/;
+export function remarkCallouts(options = {}) {
+    return (tree) => descend(tree, options);
+}
+function descend(node, options) {
+    for (const child of node.children ?? []) {
+        if (child.type === 'blockquote')
+            rewrite(child, options);
+        descend(child, options);
+    }
+}
+function rewrite(quote, options) {
+    const [head, ...blocks] = quote.children ?? [];
+    if (head?.type !== 'paragraph')
+        return;
+    const [lead, ...inline] = head.children ?? [];
+    if (lead?.type !== 'text' || typeof lead.value !== 'string')
+        return;
+    const broke = lead.value.indexOf('\n');
+    const marker = MARKER.exec(broke === -1 ? lead.value : lead.value.slice(0, broke));
+    if (!marker)
+        return;
+    const kind = (marker[1] ?? '').toLowerCase();
+    const { title, body } = split(marker[2] ?? '', broke === -1 ? null : lead.value.slice(broke + 1), inline);
+    quote.data = {
+        hName: 'div',
+        hProperties: { className: ['callout'], 'data-callout': kind },
+    };
+    quote.children = [
+        {
+            type: 'paragraph',
+            data: { hName: 'div', hProperties: { className: ['callout-title'] } },
+            // An untitled callout is titled by its own type, as the editors do, and
+            // in the locale of the reader rather than always in English.
+            children: title.length > 0
+                ? title
+                : [{ type: 'text', value: options.titleOf?.(kind) ?? capitalize(kind) }],
+        },
+        ...(body.length > 0 ? [{ type: 'paragraph', children: body }] : []),
+        ...blocks,
+    ];
+}
+/**
+ * Cuts the first paragraph at its first line break: what comes before titles
+ * the callout, what comes after opens its body. The break can fall inside any
+ * of the inline nodes, because a title that carries emphasis makes the
+ * paragraph three children and not one, so the split walks them instead of
+ * assuming the title ends where the first text node does.
+ */
+function split(titled, after, inline) {
+    const title = [{ type: 'text', value: titled }];
+    const body = [];
+    // The lead text already broke, so everything after it belongs to the body.
+    let titling = after === null;
+    if (after !== null)
+        body.push({ type: 'text', value: after });
+    for (const node of inline) {
+        if (!titling) {
+            body.push(node);
+            continue;
+        }
+        const breakAt = node.type === 'text' ? (node.value ?? '').indexOf('\n') : -1;
+        if (breakAt === -1) {
+            title.push(node);
+            continue;
+        }
+        title.push({ type: 'text', value: (node.value ?? '').slice(0, breakAt) });
+        body.push({ type: 'text', value: (node.value ?? '').slice(breakAt + 1) });
+        titling = false;
+    }
+    return { title: trimEdges(title), body: trimEdges(body) };
+}
+/** Drops the empty text nodes the cut leaves at either end. */
+function trimEdges(nodes) {
+    const kept = [...nodes];
+    while (kept.length > 0 && isBlank(kept[0]))
+        kept.shift();
+    while (kept.length > 0 && isBlank(kept[kept.length - 1]))
+        kept.pop();
+    return kept;
+}
+function isBlank(node) {
+    return node?.type === 'text' && (node.value ?? '').trim().length === 0;
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/dist/remark-ring.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+interface MdastNode {
+    type: string;
+    value?: string;
+    children?: MdastNode[];
+    data?: {
+        hName?: string;
+        hProperties?: Record<string, unknown>;
+    };
+}
+export declare function remarkHighlight(): (tree: MdastNode) => void;
+export declare function remarkComments(): (tree: MdastNode) => void;
+export declare function remarkBlockIds(): (tree: MdastNode) => void;
+/**
+ * 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 declare function remarkMathDollarRule(): (tree: MdastNode, file: {
+    value?: unknown;
+}) => void;
+export {};

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;