@memorysmithapp/markdown-renderer 0.2.0 → 0.3.1

package/README.md

@@ -74,6 +74,24 @@ const mine = defineTheme({ name: 'mine', components: { properties: () => null }
 
 Import `structure.css` instead of `styles.css` for a theme that draws everything itself. A theme names faces; your page loads them.
 
+## Diagnose
+
+Every note is valid, and nothing here refuses one. What `diagnose` tells a host is where the page will not show what was most likely typed, and what the note lacks that the specification reserves a place for: the notices of [`SPEC.md` §7.13](https://github.com/memorysmithapp/memorysmithapp-markdown/blob/main/packages/markdown-spec/SPEC.md#713-notices). It imports no React and needs no DOM, so it runs in an editor, on a server, or in a tool that writes a note.
+
+```ts
+import { diagnose } from '@memorysmithapp/markdown-renderer/diagnose';
+
+const notices = await diagnose(note, {
+  resolve: (name) => addressOfTheOneNoteNamed(name), // or reaches; leave both out and no link is pending
+  keeps: (name) => notebookKeepsAFile(name),
+});
+// [{ code: 'heading-skipped-level', severity: 'notice', section: '3.3',
+//    message: 'This heading skips a level below the heading before it.',
+//    line: 12, column: 1, endLine: 12, endColumn: 14 }, …]
+```
+
+A `notice` says the page will differ from the text — a fence never closed, a formula KaTeX cannot typeset, a diagram Mermaid cannot read, raw HTML, a footnote with no definition or no reference, a single-tilde strikethrough, a frontmatter never closed, a `name` that leaves the note unnamed or none at all, `aliases` or `tags` that are not a list, a body that does not start at `#` or skips a level. A `hint` says nothing is drawn wrong: no `aliases`, no `tags`, a link or an embed no note answers yet. Lines and columns count from 1 over the whole note, frontmatter included, and the `message` is English; a host words it in its own language from the `code`, which is stable. Mermaid is loaded only for a note that holds a diagram, and `diagrams: false` skips it.
+
 The host contract, the stylesheet's properties, the slots and the decisions behind them are in the repository's [`ARCHITECTURE.md`](https://github.com/memorysmithapp/memorysmithapp-markdown/blob/main/ARCHITECTURE.md).
 
 ## Licence

package/dist/Markdown.d.ts

@@ -1,5 +1,4 @@
 import { type AnchorHTMLAttributes, type ReactNode } from 'react';
-import type { PluggableList } from 'unified';
 import { type FootnoteRef } from './footnotes.js';
 /**
  * One run of a note, parsed and drawn: the pipeline of MemorySmith's reading page.
@@ -38,10 +37,5 @@ type WithNode<T> = T & {
     node?: unknown;
 };
 export declare function MarkdownAnchor({ href, children, node: _node, ...rest }: WithNode<AnchorHTMLAttributes<HTMLAnchorElement>>): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
-/**
- * The remark plugins of the reading surface, in their order. `planFootnotes` reads a note
- * through the same list, so it counts the references this surface draws and no other.
- */
-export declare function readingPlugins(titleOf: (kind: string) => string | undefined): PluggableList;
 export declare function Markdown({ children, source, onToggleTask, writable, footnotes }: MarkdownProps): import("react").JSX.Element;
 export {};

package/dist/Markdown.js

@@ -4,8 +4,6 @@ import { isValidElement, } from 'react';
 import { Fragment, jsx, jsxs } from 'react/jsx-runtime';
 import ReactMarkdown from 'react-markdown';
 import rehypeKatex from 'rehype-katex';
-import remarkGfm from 'remark-gfm';
-import remarkMath from 'remark-math';
 import { followable } from './address.js';
 import { CopyButton } from './CopyButton.js';
 import { highlightLanguage, highlightTree } from './highlight.js';
@@ -14,8 +12,7 @@ import { readDimensions, readImageAlt } from './image-dimensions.js';
 import { choiceTargetOf, LinkChoice } from './LinkChoice.js';
 import { toUnixNewlines } from './markdown.js';
 import { MermaidDiagram } from './MermaidDiagram.js';
-import { remarkCallouts } from './remark-callouts.js';
-import { remarkBlockIds, remarkComments, remarkHighlight, remarkMathDollarRule } from './remark-ring.js';
+import { readingPlugins } from './reading.js';
 import { CLOBBER_PREFIX, rehypeFootnoteRun, rehypeFootnoteSection } from './footnotes.js';
 import { drawSlot, headings, InBlock, MarkdownBlockquote, MarkdownDiv, MarkdownSection, MarkdownTable, useInBlock, useSlot } from './slots.js';
 import { ordinalAt } from './tasklist.js';
@@ -145,7 +142,7 @@ function MarkdownCode({ className, children, node: _node, ...rest }) {
     const inBlock = useInBlock();
     const inlineSlot = useSlot('inlineCode');
     if (className?.includes('language-mermaid')) {
-        return _jsx(MermaidDiagram, { code: String(children).trim(), scheme: scheme });
+        return _jsx(MermaidDiagram, { code: String(children ?? '').trim(), scheme: scheme });
     }
     if (!inBlock && inlineSlot)
         return drawSlot(inlineSlot, { children });
@@ -154,7 +151,8 @@ function MarkdownCode({ className, children, node: _node, ...rest }) {
         // The source is read and never rewritten: what is on the page is the
         // bytes, split into spans. React-markdown hands the children of a fence as
         // a single string ending in the newline before the closing fence.
-        const code = String(children).replace(/\n$/, '');
+        // An empty fence has no children at all, and is no code rather than the word `undefined`.
+        const code = String(children ?? '').replace(/\n$/, '');
         return (_jsx("code", { className: className, ...rest, children: toJsxRuntime(highlightTree(code, language), { Fragment, jsx, jsxs }) }));
     }
     return (_jsx("code", { className: className, ...rest, children: children }));
@@ -251,33 +249,6 @@ function dropBox(children) {
         return children;
     return children.filter((child) => !(isValidElement(child) && child.type === 'input'));
 }
-/**
- * The remark plugins of the reading surface, in their order. `planFootnotes` reads a note
- * through the same list, so it counts the references this surface draws and no other.
- */
-export function readingPlugins(titleOf) {
-    return [
-        /**
-         * `singleTilde: false` is a decision and not a default.
-         *
-         * GFM specifies strikethrough as `~~x~~`; GitHub also accepts a
-         * single tilde, outside its own specification. Here that extension
-         * actively misrenders a notation the specification leaves out:
-         * somebody writing `H~2~O` for a subscript would get `H` struck-out
-         * `2` `O`, which is a worse answer than nothing. With it off the
-         * characters stay on the page, and the author can see they got what
-         * the specification says they get, which is nothing.
-         */
-        [remarkGfm, { singleTilde: false }],
-        [remarkCallouts, { titleOf }],
-        remarkHighlight,
-        remarkComments,
-        remarkBlockIds,
-        remarkMath,
-        // After remark-math, and it gives back what was never a formula.
-        remarkMathDollarRule,
-    ];
-}
 export function Markdown({ children, source, onToggleTask, writable = false, footnotes }) {
     const text = toUnixNewlines(children);
     const { strings } = useHost();

package/dist/NoteBody.js

@@ -2,8 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
 import { HOST_KEYS, HostProvider, resolveHost } from './host.js';
 import { planFootnotes } from './footnotes.js';
-import { Markdown, readingPlugins } from './Markdown.js';
-import { bodyStart, remoteImageHosts, resolveWikilinks } from './markdown.js';
+import { Markdown } from './Markdown.js';
+import { readingPlugins } from './reading.js';
+import { bodyStart, hideComments, remoteImageHosts, resolveWikilinks } from './markdown.js';
 import { readProperties } from './properties.js';
 import { Properties } from './PropertiesBlock.js';
 import { taskBoxes } from './tasklist.js';
@@ -25,7 +26,8 @@ export function NoteBody({ markdown, writable = false, onToggleTask, ...host })
     // runs start after it. Everything below counts task items from there.
     const split = bodyStart(markdown);
     const properties = useMemo(() => readProperties(markdown), [markdown]);
-    const body = markdown.slice(split);
+    // What a comment holds is never read (§7.6): it leaves before the embeds and the links are found.
+    const body = hideComments(markdown.slice(split)).text;
     // The body is cut into runs of text and the embeds between them; each run
     // is parsed on its own, as on MemorySmith's reading page.
     const segments = splitEmbeds(body, resolved.keeps).map((segment) => segment.kind === 'text'

package/dist/Transclusion.js

@@ -3,7 +3,7 @@ import { useEffect, useState } from 'react';
 import { useHost } from './host.js';
 import { Markdown } from './Markdown.js';
 import { drawSlot, useSlot } from './slots.js';
-import { bodyStart, resolveWikilinks } from './markdown.js';
+import { bodyStart, hideComments, resolveWikilinks } from './markdown.js';
 import { blockOf, demoteEmbeds, isBlockAnchor, sectionOf } from './transclusion.js';
 import { wikilinkAddress } from './wikilink-address.js';
 /** The shape of what is coming, in the position it will occupy, while the host answers. */
@@ -49,7 +49,7 @@ export function Transclusion({ target, anchor }) {
         return slot ? drawSlot(slot, { state: 'loading', target, anchor, caption: null, children: skeleton }) : skeleton;
     }
     const { note } = loaded;
-    const whole = note.markdown.slice(bodyStart(note.markdown));
+    const whole = hideComments(note.markdown.slice(bodyStart(note.markdown))).text;
     // The caption names the note the content came from, and a note may have no
     // name.
     const sourceLabel = note.name ?? strings.unnamedNote;

package/dist/diagnose.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The notices of a note (§7.13): where what is drawn will not be what was most likely typed.
+ *
+ * There is no invalid note (§6.4), so nothing here accepts or refuses: it reads a note the way the
+ * reading surface reads it — the same frontmatter cut, its comments taken out (`hideComments`), the
+ * same parser and the same remark plugins (`reading.ts`) — and reports, by a stable code, the places where the page will differ from the
+ * text, or where the note lacks something the specification reserves a place for. A notice never
+ * blocks a save and never changes a byte.
+ *
+ * It runs with no DOM and no React, so a host can call it on a server, from a tool that writes a
+ * note, or beside an editor. KaTeX checks a formula as `rehype-katex` would typeset it, and Mermaid
+ * reads a diagram as the page would draw it, loaded only when a note carries one.
+ */
+import type { NoteHost } from './host.js';
+/** The codes of §7.13, which `spec.json` declares as `notices`. */
+export type NoticeCode = 'fence-unclosed' | 'math-unclosed' | 'formula-invalid' | 'diagram-invalid' | 'frontmatter-unclosed' | 'name-missing' | 'name-unusable' | 'reserved-not-a-list' | 'aliases-missing' | 'tags-missing' | 'heading-first-level' | 'heading-skipped-level' | 'footnote-undefined' | 'footnote-unreferenced' | 'raw-html' | 'strikethrough-single-tilde' | 'link-pending' | 'embed-pending';
+/** `notice`: the page will differ from what was typed. `hint`: nothing is drawn wrong. */
+export type NoticeSeverity = 'notice' | 'hint';
+/** One place in a note, by a code of §7.13. Lines and columns count from 1 over the whole note. */
+export interface Notice {
+    readonly code: NoticeCode;
+    readonly severity: NoticeSeverity;
+    /** The section of the specification that decides what happens there. */
+    readonly section: string;
+    /** What a reader gets, in English; a host words it in its own language from `code`. */
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+    readonly endLine: number;
+    readonly endColumn: number;
+}
+/**
+ * What the notebook answers, as `NoteBody` asks it. With neither `resolve` nor `reaches`, nothing
+ * is known about the notebook and no link is reported as pending.
+ */
+export interface DiagnoseOptions extends Pick<NoteHost, 'resolve' | 'reaches' | 'keeps'> {
+    /** Whether to read each `mermaid` block with Mermaid, which is loaded for it. Defaults to true. */
+    readonly diagrams?: boolean;
+}
+/** The table of §7.13, as `spec.json` carries it: a test holds the two equal. */
+export declare const NOTICES: Readonly<Record<NoticeCode, {
+    readonly severity: NoticeSeverity;
+    readonly section: string;
+    readonly message: string;
+}>>;
+/**
+ * The notices of a note, in the order of the note. `markdown` is the note as a host keeps it,
+ * frontmatter included; the positions are into it.
+ */
+export declare function diagnose(markdown: string, options?: DiagnoseOptions): Promise<Notice[]>;

package/dist/diagnose.js

@@ -0,0 +1,304 @@
+/**
+ * The notices of a note (§7.13): where what is drawn will not be what was most likely typed.
+ *
+ * There is no invalid note (§6.4), so nothing here accepts or refuses: it reads a note the way the
+ * reading surface reads it — the same frontmatter cut, its comments taken out (`hideComments`), the
+ * same parser and the same remark plugins (`reading.ts`) — and reports, by a stable code, the places where the page will differ from the
+ * text, or where the note lacks something the specification reserves a place for. A notice never
+ * blocks a save and never changes a byte.
+ *
+ * It runs with no DOM and no React, so a host can call it on a server, from a tool that writes a
+ * note, or beside an editor. KaTeX checks a formula as `rehype-katex` would typeset it, and Mermaid
+ * reads a diagram as the page would draw it, loaded only when a note carries one.
+ */
+import katex from 'katex';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { bodyStart, codeRegions, hideComments, insideCode, toUnixNewlines } from './markdown.js';
+import { readProperties } from './properties.js';
+import { readingPlugins } from './reading.js';
+/** The table of §7.13, as `spec.json` carries it: a test holds the two equal. */
+export const NOTICES = {
+    'fence-unclosed': { severity: 'notice', section: '3.7', message: 'This fence is never closed: it runs to the end of its block, and everything after it is code.' },
+    'math-unclosed': { severity: 'notice', section: '7.8', message: 'This $$ block is never closed: it runs to the end of its block, and everything after it is a formula.' },
+    'formula-invalid': { severity: 'notice', section: '7.8', message: 'This formula cannot be typeset, and is shown as its source.' },
+    'diagram-invalid': { severity: 'notice', section: '7.2', message: 'This diagram cannot be read, and is shown as its source or its error.' },
+    'frontmatter-unclosed': { severity: 'notice', section: '6.1', message: 'This frontmatter is never closed by a ---: the note has no properties, and its lines are body text.' },
+    'name-missing': { severity: 'notice', section: '6.5', message: 'The note has no name: a link reaches it only through an alias.' },
+    'name-unusable': { severity: 'notice', section: '6.5', message: 'This name is not a single text value, or carries one of #, [, ] and |, so the note is unnamed.' },
+    'reserved-not-a-list': { severity: 'notice', section: '6.4', message: 'This value is not a list, so it is an ordinary attribute.' },
+    'aliases-missing': { severity: 'hint', section: '6.4', message: 'The note has no aliases: only its name catches a link.' },
+    'tags-missing': { severity: 'hint', section: '6.4', message: 'The note has no tags: it has no subjects to be filtered by.' },
+    'heading-first-level': { severity: 'notice', section: '3.3', message: 'The first heading of the body is not level one.' },
+    'heading-skipped-level': { severity: 'notice', section: '3.3', message: 'This heading skips a level below the heading before it.' },
+    'footnote-undefined': { severity: 'notice', section: '7.12', message: 'This footnote has no definition, and is drawn as its characters.' },
+    'footnote-unreferenced': { severity: 'notice', section: '7.12', message: 'Nothing references this footnote, so it is not drawn.' },
+    'raw-html': { severity: 'notice', section: '7.9', message: 'Raw HTML is drawn as text, tags and all.' },
+    'strikethrough-single-tilde': { severity: 'notice', section: '4.3', message: 'One tilde strikes nothing: the tildes stay on the page. Strikethrough is ~~two~~.' },
+    'link-pending': { severity: 'hint', section: '7.4', message: 'No note answers this link yet, so it is drawn as pending.' },
+    'embed-pending': { severity: 'hint', section: '7.3', message: 'No note and no kept file answers this embed, so it is drawn as a pending link.' },
+};
+/** A footnote reference left as text, which is one with no definition (§7.12). */
+const UNDEFINED_REFERENCE = /\[\^[^\]\s]+\]/g;
+/** A run between single tildes, which GFM as read here leaves as characters (§4.3). */
+const SINGLE_TILDE = /(?<![~\\])~(?!~)(?=\S)[^~\n]*?\S~(?!~)/g;
+/** A wikilink, with the bang of an embed: the shape `resolveWikilinks` reads. */
+const WIKILINK = /(!)?\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]/g;
+/** A closing fence or `$$`, once the markers of its container are taken off. */
+const CONTAINER_PREFIX = /^[ \t>]*/;
+const KEY = /^([A-Za-z0-9_-]+)\s*:/;
+/**
+ * The notices of a note, in the order of the note. `markdown` is the note as a host keeps it,
+ * frontmatter included; the positions are into it.
+ */
+export async function diagnose(markdown, options = {}) {
+    const text = toUnixNewlines(markdown);
+    const lineStarts = [0];
+    for (let index = 0; index < text.length; index++)
+        if (text[index] === '\n')
+            lineStarts.push(index + 1);
+    const pointOf = (offset) => {
+        let low = 0;
+        let high = lineStarts.length - 1;
+        while (low < high) {
+            const middle = (low + high + 1) >> 1;
+            if ((lineStarts[middle] ?? 0) <= offset)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        return { line: low + 1, column: offset - (lineStarts[low] ?? 0) + 1 };
+    };
+    const found = [];
+    const report = (code, start, end = start, detail) => {
+        const from = pointOf(start);
+        const to = pointOf(end);
+        const { severity, section, message } = NOTICES[code];
+        found.push({
+            at: start,
+            notice: {
+                code,
+                severity,
+                section,
+                message: detail ? `${message} (${detail})` : message,
+                line: from.line,
+                column: from.column,
+                endLine: to.line,
+                endColumn: to.column,
+            },
+        });
+    };
+    const split = bodyStart(text);
+    frontmatter(text, split, report);
+    // A comment is never drawn, so nothing it holds raises a notice; positions are mapped back over it.
+    const hidden = hideComments(text.slice(split));
+    const body = hidden.text;
+    const processor = unified().use(remarkParse).use(readingPlugins(() => undefined));
+    const parsed = processor.parse(body);
+    // The text as the parser found it, before a plugin cut a run of it and dropped its position.
+    const read = structuredClone(parsed);
+    const tree = processor.runSync(parsed, body);
+    const span = (node) => {
+        const start = node.position?.start.offset;
+        const end = node.position?.end.offset;
+        return start === undefined || end === undefined ? null : [split + hidden.original(start), split + hidden.original(end, true)];
+    };
+    const diagrams = [];
+    const referenced = new Set();
+    const definitions = [];
+    walk(tree, (node) => {
+        const at = span(node);
+        if (!at)
+            return;
+        const source = text.slice(at[0], at[1]);
+        if (node.type === 'code' && /^\s*(`{3,}|~{3,})/.test(source)) {
+            if (!closes(source, /^(`{3,}|~{3,})/))
+                report('fence-unclosed', at[0], at[1]);
+            else if (node.lang === 'mermaid')
+                diagrams.push({ source: node.value ?? '', at });
+        }
+        else if (node.type === 'math') {
+            if (!closes(source, /^(\${2,})/))
+                report('math-unclosed', at[0], at[1]);
+            else if (!typesets(node.value ?? '', true))
+                report('formula-invalid', at[0], at[1]);
+        }
+        else if (node.type === 'inlineMath') {
+            if (!typesets(node.value ?? '', false))
+                report('formula-invalid', at[0], at[1]);
+        }
+        else if (node.type === 'html') {
+            report('raw-html', at[0], at[1]);
+        }
+        else if (node.type === 'footnoteReference') {
+            referenced.add(String(node.identifier ?? '').toUpperCase());
+        }
+        else if (node.type === 'footnoteDefinition') {
+            definitions.push(node);
+        }
+    });
+    for (const definition of definitions) {
+        const at = span(definition);
+        if (at && !referenced.has(String(definition.identifier ?? '').toUpperCase())) {
+            report('footnote-unreferenced', at[0], at[1]);
+        }
+    }
+    outline(tree, span, report);
+    // What stays characters on the page is found in the text the parser read.
+    walk(read, (node) => {
+        if (node.type !== 'text')
+            return;
+        const start = node.position?.start.offset;
+        const end = node.position?.end.offset;
+        if (start === undefined || end === undefined)
+            return;
+        const source = body.slice(start, end);
+        for (const [pattern, code] of [
+            [UNDEFINED_REFERENCE, 'footnote-undefined'],
+            [SINGLE_TILDE, 'strikethrough-single-tilde'],
+        ]) {
+            for (const match of source.matchAll(pattern)) {
+                const from = start + match.index;
+                report(code, split + hidden.original(from), split + hidden.original(from + match[0].length, true));
+            }
+        }
+    });
+    pending(hidden, split, options, report);
+    if (diagrams.length > 0 && options.diagrams !== false) {
+        const mermaid = (await import('mermaid')).default;
+        for (const diagram of diagrams) {
+            try {
+                await mermaid.parse(diagram.source);
+            }
+            catch (error) {
+                if (unreadable(error))
+                    report('diagram-invalid', diagram.at[0], diagram.at[1]);
+            }
+        }
+    }
+    return found.sort((a, b) => a.at - b.at).map(({ notice }) => notice);
+}
+function walk(node, visit) {
+    visit(node);
+    for (const child of node.children ?? [])
+        walk(child, visit);
+}
+/**
+ * Whether a fenced block or a `$$` block was closed: its last line, once its container's markers
+ * are off, is a run of the opening character at least as long as the opening one, and nothing else.
+ */
+function closes(source, opening) {
+    const lines = source.split('\n');
+    const run = opening.exec((lines[0] ?? '').replace(CONTAINER_PREFIX, ''))?.[1] ?? '';
+    if (lines.length < 2 || run.length === 0)
+        return false;
+    const last = (lines[lines.length - 1] ?? '').replace(CONTAINER_PREFIX, '').trimEnd();
+    const closing = new RegExp(`^\\${run[0]}{${run.length},}$`);
+    return closing.test(last);
+}
+/**
+ * Whether Mermaid refused a diagram for what it says, rather than for where it runs. Its parsers
+ * answer with a parse error, and an unknown diagram type with its own error; with no DOM, reading a
+ * label of some diagrams fails on the sanitiser instead, and that failure is no notice: a diagram
+ * Mermaid could not finish reading here may well be drawn on the page.
+ */
+function unreadable(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const failure = error;
+    return (typeof failure.hash === 'object' ||
+        failure.name === 'UnknownDiagramError' ||
+        failure.constructor?.name === 'MermaidParseError');
+}
+/** Whether KaTeX typesets a formula, as `rehype-katex` would. */
+function typesets(formula, display) {
+    try {
+        katex.renderToString(formula, { displayMode: display, throwOnError: true, strict: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The reserved keys of the frontmatter (§6.4, §6.5), and a block that never closes (§6.1). */
+function frontmatter(text, split, report) {
+    const opened = text.startsWith('---');
+    if (opened && text.indexOf('\n---', 3) === -1)
+        report('frontmatter-unclosed', 0, text.indexOf('\n') === -1 ? 3 : text.indexOf('\n'));
+    // Where each key was written, to place a notice on it.
+    const keys = new Map();
+    if (opened && split > 0) {
+        let at = text.indexOf('\n') + 1;
+        for (const line of text.slice(at, split).split('\n')) {
+            const key = KEY.exec(line)?.[1];
+            if (key && !keys.has(key))
+                keys.set(key, at);
+            at += line.length + 1;
+        }
+    }
+    const lineEnd = (at) => {
+        const end = text.indexOf('\n', at);
+        return end === -1 ? text.length : end;
+    };
+    const properties = readProperties(text);
+    const name = keys.get('name');
+    if (name === undefined)
+        report('name-missing', 0);
+    else if (properties.name === null)
+        report('name-unusable', name, lineEnd(name));
+    for (const [key, code] of [
+        ['aliases', 'aliases-missing'],
+        ['tags', 'tags-missing'],
+    ]) {
+        const at = keys.get(key);
+        const entry = properties.entries.find((candidate) => candidate.key === key);
+        if (at === undefined || !entry)
+            report(code, 0);
+        else if (entry.shape === 'empty')
+            report(code, at, lineEnd(at));
+        else if (entry.shape !== 'list')
+            report('reserved-not-a-list', at, lineEnd(at), key);
+    }
+}
+/** The outline of the body (§3.3): the headings at its top level, outside code. */
+function outline(tree, span, report) {
+    let previous = null;
+    for (const node of tree.children ?? []) {
+        if (node.type !== 'heading' || node.depth === undefined)
+            continue;
+        const at = span(node);
+        if (at) {
+            if (previous === null && node.depth > 1)
+                report('heading-first-level', at[0], at[1]);
+            else if (previous !== null && node.depth > previous + 1)
+                report('heading-skipped-level', at[0], at[1]);
+        }
+        previous = node.depth;
+    }
+}
+/**
+ * The wikilinks and embeds no note answers, when the host says which notes exist: a link reaches
+ * a note, and an embed a note or a kept file (§5.2, §5.8). Read on the body outside code, as
+ * `resolveWikilinks` reads it.
+ */
+function pending(hidden, split, options, report) {
+    const body = hidden.text;
+    const { resolve, reaches, keeps = () => false } = options;
+    if (!resolve && !reaches)
+        return;
+    const answered = (name) => reaches ? reaches(name.normalize('NFC')) > 0 : resolve(name.normalize('NFC')) !== null;
+    const code = codeRegions(body);
+    for (const match of body.matchAll(WIKILINK)) {
+        if (insideCode(code, match.index))
+            continue;
+        const name = (match[2] ?? '').split('#')[0]?.trim().replace(/\\$/, '').trim() ?? '';
+        // `[[#Section]]` is a link within the note itself.
+        if (!name)
+            continue;
+        const embed = match[1] !== undefined;
+        if (answered(name) || (embed && keeps(name)))
+            continue;
+        const end = match.index + match[0].length;
+        report(embed ? 'embed-pending' : 'link-pending', split + hidden.original(match.index), split + hidden.original(end, true), name);
+    }
+}

package/dist/markdown.d.ts

@@ -41,6 +41,26 @@ export declare function insideCode(regions: Array<[number, number]>, at: number)
 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;
+/**
+ * The comments of a text (§7.6), as half-open ranges: from a `%%` outside code to the next `%%`
+ * outside code, across inline markup and blank lines alike. A `%%` with no partner opens nothing.
+ *
+ * A comment that is all of its lines takes the line break after it too, so a comment written on
+ * lines of its own leaves no empty line behind to loosen a list or split a paragraph.
+ *
+ * MemorySmith's reading page hides a comment inside one run of text only, so one that holds a
+ * link, a tag, emphasis or a blank line reaches the page whole; this is found on the text, before
+ * anything is parsed, so nothing a comment holds is ever read.
+ */
+export declare function commentRegions(text: string): Array<[number, number]>;
+/** A text with its comments taken out, and where an offset into it falls in the text it came from. */
+export interface HiddenComments {
+    readonly text: string;
+    /** The offset in the original text of an offset into `text`; an `end` stays before a comment it meets. */
+    readonly original: (offset: number, end?: boolean) => number;
+}
+/** The text a reader is shown: its comments taken out (§7.6). The note itself is never changed. */
+export declare function hideComments(text: string): HiddenComments;
 /** 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, 

package/dist/markdown.js

@@ -254,6 +254,54 @@ export function tableRegions(body) {
 export function insideTable(regions, at) {
     return regions.some(([start, end]) => at >= start && at < end);
 }
+/**
+ * The comments of a text (§7.6), as half-open ranges: from a `%%` outside code to the next `%%`
+ * outside code, across inline markup and blank lines alike. A `%%` with no partner opens nothing.
+ *
+ * A comment that is all of its lines takes the line break after it too, so a comment written on
+ * lines of its own leaves no empty line behind to loosen a list or split a paragraph.
+ *
+ * MemorySmith's reading page hides a comment inside one run of text only, so one that holds a
+ * link, a tag, emphasis or a blank line reaches the page whole; this is found on the text, before
+ * anything is parsed, so nothing a comment holds is ever read.
+ */
+export function commentRegions(text) {
+    const code = codeRegions(text);
+    const markers = [...text.matchAll(/%%/g)].map((match) => match.index).filter((at) => !insideCode(code, at));
+    const regions = [];
+    for (let index = 0; index + 1 < markers.length; index += 2) {
+        let start = markers[index];
+        let end = markers[index + 1] + 2;
+        const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+        const lineEnd = text.indexOf('\n', end) === -1 ? text.length : text.indexOf('\n', end);
+        if (/^[ \t]*$/.test(text.slice(lineStart, start)) && /^[ \t]*$/.test(text.slice(end, lineEnd))) {
+            start = lineStart;
+            end = lineEnd === text.length ? lineEnd : lineEnd + 1;
+        }
+        regions.push([start, end]);
+    }
+    return regions;
+}
+/** The text a reader is shown: its comments taken out (§7.6). The note itself is never changed. */
+export function hideComments(text) {
+    const regions = commentRegions(text);
+    if (regions.length === 0)
+        return { text, original: (offset) => offset };
+    let shown = '';
+    let cursor = 0;
+    // Where each comment was, in the shown text, and how much of the original it took.
+    const cuts = [];
+    for (const [start, end] of regions) {
+        shown += text.slice(cursor, start);
+        cuts.push({ at: shown.length, length: end - start });
+        cursor = end;
+    }
+    shown += text.slice(cursor);
+    return {
+        text: shown,
+        original: (offset, end = false) => offset + cuts.filter((cut) => (end ? cut.at < offset : cut.at <= offset)).reduce((total, cut) => total + cut.length, 0),
+    };
+}
 /** Runs a rewrite over everything except code, which is copied through. */
 export function outsideCode(body, rewrite) {
     let out = '';

package/dist/properties.d.ts

@@ -29,7 +29,10 @@ export interface PropertyEntry {
 }
 /** The frontmatter, read. */
 export interface NoteProperties {
-    /** The name of the note: `name:` when it is a single text value (§6.5), else `null`. */
+    /**
+     * The name of the note: `name:` when it is a single text value (§6.5) that carries none of
+     * `#`, `[`, `]` and `|` (§5.3), else `null`.
+     */
     readonly name: string | null;
     /** Every other entry, in the order written. */
     readonly entries: readonly PropertyEntry[];

package/dist/properties.js

@@ -14,6 +14,8 @@
  * resolved by the host as a link of the body is. That is a decision of the
  * reading surface; it adds no edge, and what an Indexer reads is unchanged.
  */
+/** The four delimiters of the form that addresses a note: a name carrying one is no name (§5.3). */
+const UNADDRESSABLE = /[#[\]|]/;
 /** Above this a single value is prose rather than a category (§6.3). */
 const CATEGORY_CEILING = 40;
 const KEY = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/;
@@ -117,9 +119,11 @@ export function readProperties(markdown) {
     const read = [];
     for (const { key, raw, items } of entries) {
         if (key === 'name') {
-            // Only a single text value names a note; any other shape leaves it unnamed (§6.5).
+            // Only a single text value names a note; any other shape leaves it unnamed (§6.5), and so
+            // does one carrying a delimiter of the form that addresses it (§5.3). The subset has no
+            // comments (§6.2): `name: Incident #4711` is that whole value, and it carries a `#`.
             const value = items === null ? unquote(raw) : '';
-            name = value.length > 0 ? value : null;
+            name = value.length > 0 && !UNADDRESSABLE.test(value) ? value : null;
             continue;
         }
         // A list written with no item, `[]`, is an empty value, never a list (§6.3).

package/dist/reading.d.ts

@@ -0,0 +1,6 @@
+import type { PluggableList } from 'unified';
+/**
+ * The remark plugins of the reading surface, in their order. `planFootnotes` reads a note
+ * through the same list, so it counts the references this surface draws and no other.
+ */
+export declare function readingPlugins(titleOf: (kind: string) => string | undefined): PluggableList;

package/dist/reading.js

@@ -0,0 +1,32 @@
+// The remark plugins of the reading surface, apart from React: the drawing, the footnote plan
+// and the diagnostic read a note through the same list, so a notice never disagrees with the page.
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import { remarkCallouts } from './remark-callouts.js';
+import { remarkBlockIds, remarkHighlight, remarkMathDollarRule } from './remark-ring.js';
+/**
+ * The remark plugins of the reading surface, in their order. `planFootnotes` reads a note
+ * through the same list, so it counts the references this surface draws and no other.
+ */
+export function readingPlugins(titleOf) {
+    return [
+        /**
+         * `singleTilde: false` is a decision and not a default.
+         *
+         * GFM specifies strikethrough as `~~x~~`; GitHub also accepts a
+         * single tilde, outside its own specification. Here that extension
+         * actively misrenders a notation the specification leaves out:
+         * somebody writing `H~2~O` for a subscript would get `H` struck-out
+         * `2` `O`, which is a worse answer than nothing. With it off the
+         * characters stay on the page, and the author can see they got what
+         * the specification says they get, which is nothing.
+         */
+        [remarkGfm, { singleTilde: false }],
+        [remarkCallouts, { titleOf }],
+        remarkHighlight,
+        remarkBlockIds,
+        remarkMath,
+        // After remark-math, and it gives back what was never a formula.
+        remarkMathDollarRule,
+    ];
+}

package/dist/remark-callouts.js

@@ -18,8 +18,12 @@
  * 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]*(.*)$/;
+/**
+ * `[!type]`, an optional fold marker, and whatever titles it. The type is a word
+ * in any script (§7.1): it opens with a letter and goes on in letters, marks,
+ * digits, `_` and `-`, so `[!atenção]` is a type as much as `[!warning]` is.
+ */
+const MARKER = /^\[!(\p{L}[\p{L}\p{M}\p{N}_-]*)\]([+-]?)[ \t]*(.*)$/u;
 export function remarkCallouts(options = {}) {
     return (tree) => descend(tree, options);
 }
@@ -41,7 +45,7 @@ function rewrite(quote, options) {
     const marker = MARKER.exec(broke === -1 ? lead.value : lead.value.slice(0, broke));
     if (!marker)
         return;
-    const kind = (marker[1] ?? '').toLowerCase();
+    const kind = (marker[1] ?? '').normalize('NFC').toLowerCase();
     const { title, body } = split(marker[3] ?? '', broke === -1 ? null : lead.value.slice(broke + 1), inline);
     quote.data = {
         hName: 'div',

package/dist/remark-ring.d.ts

@@ -1,17 +1,20 @@
 /**
  * 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).
+ * block identifiers (§7.5, §7.7) and the dollar rule of mathematics (§7.8).
  *
- * All three are remark plugins rather than passes over the string, for the
+ * They 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.
  *
+ * Comments (§7.6) are the one exception, and they are taken out before the
+ * parser by `hideComments` (`markdown.ts`), which finds code first: a comment
+ * may hold markup and blank lines, and once parsed it is spread over nodes no
+ * plugin on a run of text can see whole.
+ *
  * 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.
+ * unaffected by everything here.
  */
 interface MdastNode {
     type: string;
@@ -23,7 +26,6 @@ interface MdastNode {
     };
 }
 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).

package/dist/remark-ring.js

@@ -1,17 +1,20 @@
 /**
  * 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).
+ * block identifiers (§7.5, §7.7) and the dollar rule of mathematics (§7.8).
  *
- * All three are remark plugins rather than passes over the string, for the
+ * They 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.
  *
+ * Comments (§7.6) are the one exception, and they are taken out before the
+ * parser by `hideComments` (`markdown.ts`), which finds code first: a comment
+ * may hold markup and blank lines, and once parsed it is spread over nodes no
+ * plugin on a run of text can see whole.
+ *
  * 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.
+ * unaffected by everything here.
  */
 /** Walks every node, letting the visitor rewrite a parent's children. */
 function walk(node, visit) {
@@ -45,37 +48,21 @@ export function remarkHighlight() {
         });
     });
 }
-/**
- * `%%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]*$/;
+/**
+ * The nodes a block ends in. The last text of a link, an emphasis or any other
+ * inline is not the end of a block: `[[Note#^id]]` keeps its `^id` on the label.
+ */
+const BLOCKS = new Set(['paragraph', 'heading', 'tableCell']);
 export function remarkBlockIds() {
     return (tree) => walk(tree, (parent) => {
+        if (!BLOCKS.has(parent.type))
+            return;
         const children = parent.children ?? [];
         const last = children[children.length - 1];
         if (!last || !isText(last) || !last.value?.includes('^'))

package/dist/slots.js

@@ -21,9 +21,17 @@ export function drawSlot(slot, props) {
 /** Whether a code element sits in a fenced block, which is what tells a block from a span. */
 export const InBlock = createContext(false);
 // ── Callouts ─────────────────────────────────────────────────────────────────
+/**
+ * The words of a title, in one element: the title is laid out as a row beside
+ * its icon, and every text node and every `<strong>` of it would otherwise be
+ * an item of that row of its own, drawn as columns. One run wraps as a sentence.
+ */
+function CalloutTitleText({ children }) {
+    return _jsx("span", { className: "callout-title-text", children: children });
+}
 /** The title `remarkCallouts` built, carried to the callout that holds it. */
 function CalloutTitle({ children }) {
-    return _jsx("div", { className: "callout-title", children: children });
+    return (_jsx("div", { className: "callout-title", children: _jsx(CalloutTitleText, { children: children }) }));
 }
 function Callout({ kind, fold, children }) {
     const { theme } = useHost();
@@ -42,7 +50,7 @@ function Callout({ kind, fold, children }) {
     const title = at === -1 ? null : parts[at].props.children;
     const titled = icon === null ? (_jsx(CalloutTitle, { children: title })) : (
     // An icon of the theme's takes the place of the one the stylesheet draws.
-    _jsxs("div", { className: "callout-title has-icon", children: [_jsx("span", { className: "callout-icon", "aria-hidden": "true", children: icon }), title] }));
+    _jsxs("div", { className: "callout-title has-icon", children: [_jsx("span", { className: "callout-icon", "aria-hidden": "true", children: icon }), _jsx(CalloutTitleText, { children: title })] }));
     if (slot) {
         const body = parts.filter((_, index) => index !== at);
         return drawSlot(slot, { kind, fold, title, icon, children: body });

package/dist/tasklist.js

@@ -11,7 +11,7 @@
  * 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';
+import { commentRegions, 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
@@ -25,7 +25,7 @@ import { fenceRegions } from './markdown.js';
  */
 const TASK = /^(?:[ \t]*>[ \t]?)*[ \t]*(?:[-*+]|\d+[.)])[ \t]+\[([ xX])\]/gm;
 /**
- * Blanks out fenced blocks while keeping every offset intact. A task item
+ * Blanks out fenced blocks and comments 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.
@@ -37,7 +37,11 @@ const TASK = /^(?:[ \t]*>[ \t]?)*[ \t]*(?:[-*+]|\d+[.)])[ \t]+\[([ xX])\]/gm;
 function maskFences(text) {
     let masked = '';
     let cursor = 0;
-    for (const [start, end] of fenceRegions(text)) {
+    // A comment is never drawn (§7.6), so a box inside one is no box, on either side of the count.
+    const hidden = [...fenceRegions(text), ...commentRegions(text)].sort((a, b) => a[0] - b[0]);
+    for (const [start, end] of hidden) {
+        if (start < cursor)
+            continue;
         masked += text.slice(cursor, start) + text.slice(start, end).replace(/[^\n]/g, ' ');
         cursor = end;
     }

package/dist/transclusion.d.ts

@@ -72,5 +72,8 @@ 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.
+ *
+ * A line inside a fence is code and never a heading, so the `# Step 1` comment
+ * of a shell block neither opens a section nor ends one.
  */
 export declare function sectionOf(markdown: string, anchor: string): string | null;

package/dist/transclusion.js

@@ -16,7 +16,7 @@
  * 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';
+import { codeRegions, fenceRegions, headingKey, insideCode, insideTable, outsideCode, tableRegions } from './markdown.js';
 /** Same shape the link extractor matches, plus the leading `!`. */
 const EMBED = /!\[\[([^\]|#]+?)(?:#([^\]|]+?))?(?:\|[^\]]*?)?\]\]/g;
 /**
@@ -136,13 +136,22 @@ function escapeRegExp(value) {
  * 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.
+ *
+ * A line inside a fence is code and never a heading, so the `# Step 1` comment
+ * of a shell block neither opens a section nor ends one.
  */
 export function sectionOf(markdown, anchor) {
     const wanted = headingKey(anchor);
     const lines = markdown.split('\n');
+    const fences = fenceRegions(markdown);
     let start = -1;
     let level = 0;
+    let at = 0;
     for (let index = 0; index < lines.length; index++) {
+        const offset = at;
+        at += (lines[index] ?? '').length + 1;
+        if (insideCode(fences, offset))
+            continue;
         const heading = HEADING.exec(lines[index] ?? '');
         if (!heading)
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorysmithapp/markdown-renderer",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "A React component that draws a MemorySmith note exactly as MemorySmith's reading page does.",
   "keywords": [
     "markdown",
@@ -42,6 +42,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./diagnose": {
+      "types": "./dist/diagnose.d.ts",
+      "default": "./dist/diagnose.js"
+    },
     "./styles.css": "./styles.css",
     "./structure.css": "./structure.css",
     "./theme-default.css": "./theme-default.css"
@@ -63,7 +67,7 @@
     "unified": "11.0.5"
   },
   "devDependencies": {
-    "@memorysmithapp/markdown-spec": "0.2.0",
+    "@memorysmithapp/markdown-spec": "0.3.1",
     "@types/hast": "3.0.5",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",

package/structure.css

@@ -37,6 +37,13 @@
   border: 0;
 }
 
+/* The words of a callout's title are one item of its row, so a title that
+   carries emphasis wraps as one sentence beside the icon, never as columns. */
+.markdown .callout-title-text {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
 /* An icon a theme draws as an element takes the place of the one the
    stylesheet draws as a mask, at the size of the title it sits in. */
 .markdown .callout-title.has-icon::before {

package/theme-default.css

@@ -360,6 +360,10 @@
   /* Room for the button, so the first line is never under it. */
   padding-right: 6.5rem;
 }
+/* An empty block keeps the height of one line, so its button fits inside it. */
+.markdown .code-block > pre > code:empty::before {
+  content: '\200b';
+}
 .markdown pre code {
   background: none;
   color: var(--ms-text);