@memorysmithapp/markdown-renderer 0.5.0 → 0.6.0

package/README.md

@@ -20,7 +20,7 @@ import 'katex/dist/katex.min.css';
   resolve={(name) => addressOfTheOneNoteNamed(name)} // or null: the link is pending
   keeps={(name) => notebookKeepsAFile(name)}       // only an embed reaches a file
   fileOf={(name) => describe(name)}               // { mimeType, bytes, url, description }: drawn by its type, as MemorySmith does
-  renderLink={({ href, className, children }) => <RouterLink to={href} className={className}>{children}</RouterLink>}
+  renderLink={({ href, className, children }) => <a href={href} className={className} onClick={follow(href)}>{children}</a>} // follow: your router's navigate, captured where it is
   loadNote={(name) => fetchTheBodyOf(name)}        // for an embedded note; the package never fetches
   writable
   onToggleTask={(ordinal) => save(toggleTaskAt(latest(), ordinal))} // a promise locks the item under "Updating…" until it settles
@@ -29,7 +29,7 @@ import 'katex/dist/katex.min.css';
 />;
 ```
 
-Every prop is optional, and every default is the safe one: with no `resolve` every link is pending, with no `keeps` no embed reaches a file. A file `fileOf` describes is drawn by its media type, never its name: an image, an audio or a video player, and anything else a card with its type, size, description, *Open* where a browser shows it and *Download*; give `renderAttachment` instead to draw files yourself. The stylesheet styles nothing outside `.markdown`. The faces of the default theme are Inter and Space Grotesk, which the page loads.
+Every prop is optional, and every default is the safe one: with no `resolve` every link is pending, with no `keeps` no embed reaches a file. A file `fileOf` describes is drawn by its media type, never its name: an image, an audio or a video player, and anything else a card with its type, size, description, *Open* where a browser shows it and *Download*; give `renderAttachment` instead to draw files yourself. In edit mode, `renderLink`, `renderAttachment` and a theme's slots may be drawn in a root of their own, outside your React tree, so what they return must not read your context: a router's `<Link>` throws there, and the block shows its Markdown under a notice instead. The stylesheet styles nothing outside `.markdown`. The faces of the default theme are Inter and Space Grotesk, which the page loads.
 
 ## Themes
 
@@ -86,7 +86,7 @@ A note the host makes `editable` carries a button at its top right that switches
   suggest={(typed) => namesOfNotesLike(typed)}    // what [[ offers
   attach={(file, { name, description }, progress) => keepInNotebook(file, name, description, progress)} // the name it is kept under
   files={() => filesOfTheNotebook()}              // what the attach dialog lists: { name, mimeType, bytes, url, description }
-  modeButton="icon"                               // or "label", the icon and its word
+  modeButton="label"                              // the icon and its word; "icon", the default, the icon alone
 />
 ```
 

package/dist/NoteBody.d.ts

@@ -25,7 +25,10 @@ export interface NoteBodyProps extends NoteHost {
      * a dialog with the host's words and its actions (#86).
      */
     readonly onChange?: (markdown: string) => unknown;
-    /** Whether the switch shows its icon alone or its icon and its word. Defaults to `label`. */
+    /**
+     * Whether the switch shows its icon alone or its icon and its word. Defaults to `icon`, like Show
+     * Markdown and Copy Markdown beside it, its word then its name and its title (#92).
+     */
     readonly modeButton?: 'icon' | 'label';
     /**
      * Whether the note offers Show Markdown and Copy Markdown at its top right, editable or not:

package/dist/NoteBody.js

@@ -34,7 +34,7 @@ function ModeSwitch({ mode, display, toggle }) {
  * It renders inside `.markdown`, so the stylesheet of the package applies, and asks the host for
  * every piece of notebook data through the props of `NoteHost`.
  */
-export function NoteBody({ editable = false, mode, defaultMode = 'view', onModeChange, onChange, modeButton = 'label', actions = true, ...rest }) {
+export function NoteBody({ editable = false, mode, defaultMode = 'view', onModeChange, onChange, modeButton = 'icon', actions = true, ...rest }) {
     const [own, setOwn] = useState(defaultMode);
     // The author asked to go back to reading, and the editor is finishing: a save, the toolbar folding.
     const [leaving, setLeaving] = useState(false);

package/dist/edit/NoteEditor.js

@@ -19,6 +19,7 @@ import { rootStyle } from '../theme.js';
 import { ICONS } from './blocks.js';
 import { BLOCKS, command, headingLevel, insertBlock, insertFootnote, insertLink, insertWikilink, setHeading, toggleComment, toggleList, toggleMark, toggleQuote, } from './commands.js';
 import { analysisField, editorEnvironment, livePage } from './live.js';
+import { measureMetrics } from './heights.js';
 import { NoteActions } from '../NoteActions.js';
 import { AttachDialog, webImage } from './AttachDialog.js';
 import { ContextMenu } from './ContextMenu.js';
@@ -358,7 +359,7 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
                     markdown(),
                     EditorView.lineWrapping,
                     EditorView.contentAttributes.of({ 'aria-multiline': 'true', spellcheck: 'true' }),
-                    livePage(),
+                    livePage(measureMetrics(parent.current)),
                     autocompletion({ override: [wikilinkCompletion(() => latest.current.host)], icons: false }),
                     shortcuts(() => created),
                     keymap.of([...markdownKeymap, ...historyKeymap, indentWithTab, ...defaultKeymap]),

package/dist/edit/heights.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How tall a drawn block will be before it is drawn (#91).
+ *
+ * CodeMirror lays out the blocks it has not drawn yet by the height their widget estimates, and
+ * reads that estimate once, when the block's decoration is made; a block drawn taller than its
+ * estimate grows the document under the scrollbar as the author scrolls to it. Each block
+ * estimates its height from what it draws — its lines wrapped at the editor's width, its rows, its
+ * properties — and a block drawn once at a width is remembered at its measured height, so the same
+ * block made again, moved by an edit above it or in the next edit of the note, starts right.
+ */
+/** What an estimate reads of the editor: its text column, its line height and its characters. */
+export interface BlockMetrics {
+    readonly width: number;
+    readonly lineHeight: number;
+    readonly charWidth: number;
+}
+/** What an estimate assumes before the editor has been measured, as in a test with no layout. */
+export declare const DEFAULT_METRICS: BlockMetrics;
+/**
+ * The metrics of a text column laid out in `parent`, read before the editor exists there, so the
+ * first estimates are made at the width the note is drawn at. Falls back to `DEFAULT_METRICS` where
+ * nothing is laid out.
+ */
+export declare function measureMetrics(parent: HTMLElement): BlockMetrics;
+/** Metrics as measured, any that could not be read replaced by the default. */
+export declare function withinReason(metrics: BlockMetrics): BlockMetrics;
+/** What a block is, for its estimate. */
+export type BlockKind = 'frontmatter' | 'callout' | 'table' | 'embed' | 'diagram' | 'preview' | 'add-properties';
+/** The height a block of this kind and these lines is drawn at, near enough to lay out the page. */
+export declare function estimateHeight(kind: BlockKind, source: string, metrics: BlockMetrics): number;
+/** The height a block of this content was drawn at at this width, if it was. */
+export declare function measuredHeight(identity: string, metrics: BlockMetrics): number | undefined;
+/** Remembers the height a block was drawn at. */
+export declare function rememberHeight(identity: string, metrics: BlockMetrics, height: number): void;

package/dist/edit/heights.js

@@ -0,0 +1,101 @@
+/**
+ * How tall a drawn block will be before it is drawn (#91).
+ *
+ * CodeMirror lays out the blocks it has not drawn yet by the height their widget estimates, and
+ * reads that estimate once, when the block's decoration is made; a block drawn taller than its
+ * estimate grows the document under the scrollbar as the author scrolls to it. Each block
+ * estimates its height from what it draws — its lines wrapped at the editor's width, its rows, its
+ * properties — and a block drawn once at a width is remembered at its measured height, so the same
+ * block made again, moved by an edit above it or in the next edit of the note, starts right.
+ */
+/** What an estimate assumes before the editor has been measured, as in a test with no layout. */
+export const DEFAULT_METRICS = { width: 700, lineHeight: 24, charWidth: 8 };
+/**
+ * The metrics of a text column laid out in `parent`, read before the editor exists there, so the
+ * first estimates are made at the width the note is drawn at. Falls back to `DEFAULT_METRICS` where
+ * nothing is laid out.
+ */
+export function measureMetrics(parent) {
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position: absolute; visibility: hidden; white-space: pre; pointer-events: none';
+    probe.textContent = 'abcdefghijklmnopqrstuvwxyz';
+    parent.appendChild(probe);
+    const box = probe.getBoundingClientRect();
+    const width = parent.clientWidth;
+    probe.remove();
+    return withinReason({ width, lineHeight: box.height, charWidth: box.width / 26 });
+}
+/** Metrics as measured, any that could not be read replaced by the default. */
+export function withinReason(metrics) {
+    const usable = (value, fallback) => (Number.isFinite(value) && value > 1 ? value : fallback);
+    return {
+        width: usable(metrics.width, DEFAULT_METRICS.width),
+        lineHeight: usable(metrics.lineHeight, DEFAULT_METRICS.lineHeight),
+        charWidth: usable(metrics.charWidth, DEFAULT_METRICS.charWidth),
+    };
+}
+/** The lines a text takes in a column `width` wide, each of its lines at least one. */
+function wrapped(lines, width, metrics) {
+    const perLine = Math.max(8, Math.floor(width / metrics.charWidth));
+    return lines.reduce((sum, line) => sum + Math.max(1, Math.ceil(line.length / perLine)), 0);
+}
+/**
+ * Below this width the default theme lays a property's value under its key, not beside it; it is
+ * the text column of its 560px breakpoint.
+ */
+const STACKED_PROPERTIES = 528;
+/** The height a block of this kind and these lines is drawn at, near enough to lay out the page. */
+export function estimateHeight(kind, source, metrics) {
+    const { lineHeight } = metrics;
+    const lines = source.split('\n');
+    switch (kind) {
+        case 'frontmatter': {
+            // The name's field, then a row per key of the top level, which a list's items share.
+            const keys = lines.filter((line) => /^[^\s#-][^:]*:/.test(line)).length;
+            const row = (metrics.width < STACKED_PROPERTIES ? 2.8 : 1.4) * lineHeight;
+            return Math.round(2.5 * lineHeight + keys * row);
+        }
+        case 'callout': {
+            // Its title and its body, as text inside its padding and its border.
+            const text = lines.map((line) => line.replace(/^(?:\s*>)+\s?/, ''));
+            return Math.round(lineHeight + wrapped(text, metrics.width - 32, metrics) * lineHeight);
+        }
+        case 'table': {
+            // A row per line but the delimiter row. The columns share the width by what they hold, so a
+            // row wraps as the text of all its cells would in the width their padding leaves.
+            const rows = lines.filter((line, index) => index !== 1 || !/^[\s|:-]+$/.test(line));
+            const cells = (row) => row.replace(/^\s*\|/, '').replace(/\|\s*$/, '').split('|').map((cell) => cell.trim());
+            const columns = Math.max(1, ...rows.map((row) => cells(row).length));
+            const width = metrics.width - 16 * columns;
+            const height = rows.reduce((sum, row) => sum + 9 + lineHeight * wrapped([cells(row).join('')], width, metrics), 0);
+            return Math.round(0.75 * lineHeight + height);
+        }
+        case 'embed':
+            // What a note or a file embeds is not known before it is drawn: a card's height.
+            return Math.round(8 * lineHeight);
+        case 'diagram':
+            return Math.round(12 * lineHeight);
+        case 'preview':
+            return Math.round(lineHeight + wrapped(lines, metrics.width, metrics) * lineHeight);
+        case 'add-properties':
+            return Math.round(1.5 * lineHeight);
+    }
+}
+/** The heights blocks were drawn at, by width and content; the oldest are let go past the limit. */
+const measured = new Map();
+const MEASURED_LIMIT = 2000;
+const measuredKey = (identity, metrics) => `${Math.round(metrics.width)}\u0000${identity}`;
+/** The height a block of this content was drawn at at this width, if it was. */
+export function measuredHeight(identity, metrics) {
+    return measured.get(measuredKey(identity, metrics));
+}
+/** Remembers the height a block was drawn at. */
+export function rememberHeight(identity, metrics, height) {
+    if (!(height > 0))
+        return;
+    const key = measuredKey(identity, metrics);
+    measured.delete(key);
+    measured.set(key, height);
+    if (measured.size > MEASURED_LIMIT)
+        measured.delete(measured.keys().next().value);
+}

package/dist/edit/live.d.ts

@@ -10,6 +10,7 @@ import { Facet, StateField, type EditorState, type Extension } from '@codemirror
 import { type DecorationSet } from '@codemirror/view';
 import { type ResolvedHost } from '../host.js';
 import { type Analysis } from './analyze.js';
+import { type BlockMetrics } from './heights.js';
 /** What the drawn blocks read: the host the note is edited under. */
 export interface EditorEnvironment {
     readonly host: ResolvedHost;
@@ -24,5 +25,9 @@ export declare const setFocused: import("@codemirror/state").StateEffectType<boo
 /** A grammar a code block names has arrived: its tokens can be coloured now (#84). */
 export declare const grammarArrived: import("@codemirror/state").StateEffectType<string>;
 export declare const decorationsField: StateField<DecorationSet>;
-/** The live page: the analysis, the decorations over it, and what the focus and a modifier-click do. */
-export declare function livePage(): Extension;
+/**
+ * The live page: the analysis, the decorations over it, and what the focus and a modifier-click do.
+ * `metrics` are the editor's text column measured before the editor is made, which the first drawn
+ * blocks estimate their height by; without them they assume `DEFAULT_METRICS` until it is measured.
+ */
+export declare function livePage(metrics?: BlockMetrics): Extension;

package/dist/edit/live.js

@@ -9,13 +9,15 @@
 import { EditorSelection, Facet, Prec, StateEffect, StateField } from '@codemirror/state';
 import { Decoration, EditorView, keymap, ViewPlugin, WidgetType } from '@codemirror/view';
 import katex from 'katex';
-import { createElement } from 'react';
+import { Component, createElement } from 'react';
 import { createRoot } from 'react-dom/client';
 import { followable } from '../address.js';
 import { highlightTree, languageToLoad, loadGrammar } from '../highlight.js';
 import { HostProvider, resolveHost } from '../host.js';
+import { readImageAlt } from '../image-dimensions.js';
 import { highlightLanguage } from '../highlight.js';
 import { analyze } from './analyze.js';
+import { DEFAULT_METRICS, estimateHeight, measuredHeight, rememberHeight, withinReason } from './heights.js';
 import { AddProperties, CalloutBlock, PropertiesBlock, reveal, Snippet, TableBlock } from './blocks.js';
 import { LanguageControl } from './LanguageControl.js';
 import { toggleTaskBox } from './commands.js';
@@ -35,6 +37,42 @@ export const analysisField = StateField.define({
 export const setFocused = StateEffect.define();
 /** A grammar a code block names has arrived: its tokens can be coloured now (#84). */
 export const grammarArrived = StateEffect.define();
+/** The editor's metrics changed: the blocks made from now on estimate their height by them (#91). */
+const setBlockMetrics = StateEffect.define();
+/** The metrics of the editor's text column, which a drawn block estimates its height by (#91). */
+const metricsField = StateField.define({
+    create: () => DEFAULT_METRICS,
+    update: (metrics, transaction) => {
+        for (const effect of transaction.effects)
+            if (effect.is(setBlockMetrics))
+                return effect.value;
+        return metrics;
+    },
+});
+/** Reads the editor's metrics again whenever its geometry changes, and keeps them when they moved. */
+const metricsWatcher = ViewPlugin.define((view) => {
+    let destroyed = false;
+    const check = () => view.requestMeasure({
+        read: () => withinReason({ width: view.contentDOM.clientWidth, lineHeight: view.defaultLineHeight, charWidth: view.defaultCharacterWidth }),
+        write: (next) => {
+            const now = view.state.field(metricsField);
+            const moved = Math.abs(next.width - now.width) >= 1 || Math.abs(next.lineHeight - now.lineHeight) >= 0.5 || Math.abs(next.charWidth - now.charWidth) >= 0.05;
+            // Not inside the measure, where CodeMirror takes no transaction.
+            if (moved)
+                queueMicrotask(() => destroyed || view.dispatch({ effects: setBlockMetrics.of(next) }));
+        },
+    });
+    check();
+    return {
+        update: (update) => {
+            if (update.geometryChanged)
+                check();
+        },
+        destroy: () => {
+            destroyed = true;
+        },
+    };
+});
 /** Whether the editor has the focus: a construct is shown as source only to an author who is in it. */
 const focusField = StateField.define({
     create: () => false,
@@ -46,17 +84,45 @@ const focusField = StateField.define({
     },
 });
 // ── Widgets ──────────────────────────────────────────────────────────────────
+/**
+ * What a drawn block shows when drawing it threw — a host's `renderLink` that needs the host's own
+ * context, which a block's root, outside the host's tree, does not carry (#90): its lines as written,
+ * under a notice, so a failure never hides a part of the note. A click on it shows its source.
+ */
+class BlockBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error, info) {
+        // React reports a caught error only in development; the host is told in every build.
+        console.error('A block of the note could not be drawn:', error, info.componentStack);
+    }
+    render() {
+        if (!this.state.failed)
+            return this.props.children;
+        const notice = this.props.host.strings.editor.blockFailed;
+        if (!this.props.source)
+            return createElement('span', { className: 'cm-ms-block-failed', title: notice });
+        return createElement('div', { className: 'cm-ms-block-failed', role: 'note' }, createElement('p', { className: 'cm-ms-block-failed-notice' }, notice), createElement('pre', null, this.props.source));
+    }
+}
 /** The React roots the widgets mounted, unmounted when CodeMirror lets the widget go. */
 const roots = new WeakMap();
-function mount(view, element, node) {
+function mount(view, element, node, source, measured) {
     const { host } = view.state.facet(editorEnvironment);
     const root = createRoot(element);
     // Drawn on React's own schedule: CodeMirror builds its widgets inside its update, which may run
     // inside a React commit, where React cannot be asked to render synchronously.
-    root.render(createElement(HostProvider, { value: host }, node));
+    root.render(createElement(HostProvider, { value: host }, createElement(BlockBoundary, { host, source }, node)));
     // A block whose content arrives later — an embed, a diagram — changes its height after it is
     // measured; the editor is told so, or the lines below it would be placed by the old height.
-    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(() => view.requestMeasure());
+    const observer = typeof ResizeObserver === 'undefined'
+        ? null
+        : new ResizeObserver(() => {
+            measured(element.getBoundingClientRect().height);
+            view.requestMeasure();
+        });
     observer?.observe(element);
     roots.set(element, { unmount: () => root.unmount(), observer });
 }
@@ -75,16 +141,24 @@ class BlockWidget extends WidgetType {
     host;
     draw;
     revealsOnClick;
+    options;
     inline;
+    source;
     constructor(key, host, draw, 
     /** Whether a click on it shows its source; a block with controls of its own handles its clicks. */
-    revealsOnClick, inline = false) {
+    revealsOnClick, options = {}) {
         super();
         this.key = key;
         this.host = host;
         this.draw = draw;
         this.revealsOnClick = revealsOnClick;
-        this.inline = inline;
+        this.options = options;
+        this.inline = options.inline ?? false;
+        this.source = options.source ?? '';
+    }
+    /** What it is remembered by once measured: what it draws, wherever in the note it stands. */
+    get identity() {
+        return `${this.options.kind ?? 'block'}\u0000${this.source}`;
     }
     eq(other) {
         return other.key === this.key && other.host === this.host;
@@ -92,7 +166,7 @@ class BlockWidget extends WidgetType {
     toDOM(view) {
         const element = document.createElement(this.inline ? 'span' : 'div');
         element.className = this.inline ? 'cm-ms-inline-block' : 'cm-ms-block';
-        mount(view, element, this.draw(view));
+        mount(view, element, this.draw(view), this.source, (height) => rememberHeight(this.identity, view.state.field(metricsField), height));
         element.addEventListener('mousedown', (event) => {
             const target = event.target;
             if (target.closest('[data-ms-control]'))
@@ -119,8 +193,16 @@ class BlockWidget extends WidgetType {
     ignoreEvent() {
         return true;
     }
+    /**
+     * The height CodeMirror lays the block out at until it is drawn, which it reads once, when the
+     * block is made: the height it was drawn at before at this width, or its estimate (#91).
+     */
     get estimatedHeight() {
-        return this.inline ? -1 : 48;
+        if (this.inline)
+            return -1;
+        const metrics = this.options.metrics ?? DEFAULT_METRICS;
+        const kind = this.options.kind;
+        return measuredHeight(this.identity, metrics) ?? (kind ? estimateHeight(kind, this.source, metrics) : 2 * metrics.lineHeight);
     }
 }
 /**
@@ -180,6 +262,10 @@ class TaskWidget extends WidgetType {
         return false;
     }
 }
+/** What a rule and a formula's row are drawn at by the default theme, before they are measured (#91). */
+const RULE_HEIGHT = 33;
+const MATH_ROW = 32;
+const MATH_MARGINS = 32;
 class RuleWidget extends WidgetType {
     eq() {
         return true;
@@ -190,6 +276,9 @@ class RuleWidget extends WidgetType {
         wrap.appendChild(document.createElement('hr'));
         return wrap;
     }
+    get estimatedHeight() {
+        return RULE_HEIGHT;
+    }
 }
 class MathWidget extends WidgetType {
     tex;
@@ -209,21 +298,31 @@ class MathWidget extends WidgetType {
         katex.render(this.tex, element, { throwOnError: false, displayMode: this.display, strict: 'ignore' });
         return element;
     }
+    /** A formula's rows, each a line of KaTeX's display, within its margins (#91). */
+    get estimatedHeight() {
+        return this.display ? MATH_MARGINS + MATH_ROW * this.tex.split('\\\\').length : -1;
+    }
     ignoreEvent() {
         return false;
     }
 }
+/** What an image declares no height for is drawn at before it loads, near enough (#91). */
+const UNDECLARED_IMAGE_HEIGHT = 200;
 class ImageWidget extends WidgetType {
     source;
+    match;
+    alt;
     constructor(source) {
         super();
         this.source = source;
+        this.match = /^!\[([^\]]*)\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)$/.exec(source);
+        this.alt = readImageAlt(this.match?.[1] ?? '');
     }
     eq(other) {
         return other.source === this.source;
     }
     toDOM() {
-        const match = /^!\[([^\]]*)\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)$/.exec(this.source);
+        const match = this.match;
         const address = match ? followable(match[2] ?? '') : '';
         if (!match || !address) {
             const text = document.createElement('span');
@@ -234,9 +333,22 @@ class ImageWidget extends WidgetType {
         const image = document.createElement('img');
         image.className = 'cm-ms-image';
         image.src = address;
-        image.alt = (match[1] ?? '').split('|')[0] ?? '';
+        // Its description and the dimensions it declares, as the page draws it (`SPEC.md` §3.14).
+        image.alt = this.alt.description;
+        if (this.alt.width !== null)
+            image.width = this.alt.width;
+        if (this.alt.height !== null)
+            image.height = this.alt.height;
         return image;
     }
+    /** The line it stands in is as tall as the image: the height it declares, or a guess (#91). */
+    get estimatedHeight() {
+        if (!this.match)
+            return -1;
+        if (this.alt.height !== null)
+            return this.alt.height;
+        return this.alt.width !== null ? Math.round(this.alt.width * 0.75) : UNDECLARED_IMAGE_HEIGHT;
+    }
     ignoreEvent() {
         return false;
     }
@@ -251,6 +363,7 @@ const BLOCK_KINDS = new Set(['frontmatter', 'callout', 'table', 'mathBlock', 'em
 function build(state) {
     const { constructs, bodyFrom } = state.field(analysisField);
     const { host } = state.facet(editorEnvironment);
+    const metrics = state.field(metricsField);
     const focused = state.field(focusField);
     const doc = state.doc;
     const text = textOf(state);
@@ -274,17 +387,18 @@ function build(state) {
         for (let at = doc.lineAt(lines.from).number; at <= doc.lineAt(lines.to).number; at++)
             out.push(line(className).range(doc.line(at).from));
     };
-    const block = (from, to, key, draw, revealsOnClick = true) => {
+    const block = (from, to, kind, key, draw, revealsOnClick = true) => {
         const lines = linesOf(from, to);
-        out.push(Decoration.replace({ widget: new BlockWidget(key, host, draw, revealsOnClick), block: true }).range(lines.from, lines.to));
+        const source = text.slice(lines.from, lines.to);
+        out.push(Decoration.replace({ widget: new BlockWidget(key, host, draw, revealsOnClick, { source, kind, metrics }), block: true }).range(lines.from, lines.to));
         covered.push(lines);
     };
-    const after = (to, key, draw) => {
+    const after = (to, key, draw, source) => {
         const lines = linesOf(to, to);
-        out.push(Decoration.widget({ widget: new BlockWidget(key, host, draw, false), block: true, side: 1 }).range(lines.to));
+        out.push(Decoration.widget({ widget: new BlockWidget(key, host, draw, false, { source, kind: 'preview', metrics }), block: true, side: 1 }).range(lines.to));
     };
     if (bodyFrom === 0) {
-        out.push(Decoration.widget({ widget: new BlockWidget('add-properties', host, (view) => createElement(AddProperties, { view }), false), block: true, side: -1 }).range(0));
+        out.push(Decoration.widget({ widget: new BlockWidget('add-properties', host, (view) => createElement(AddProperties, { view }), false, { kind: 'add-properties', metrics }), block: true, side: -1 }).range(0));
     }
     // Blocks first: what a drawn block covers is not decorated again.
     for (const construct of constructs) {
@@ -299,7 +413,7 @@ function build(state) {
                 if (open)
                     eachLine(from, to, 'cm-ms-yaml');
                 else
-                    block(from, to, `front:${source}`, (view) => createElement(PropertiesBlock, { view, to }), false);
+                    block(from, to, 'frontmatter', `front:${source}`, (view) => createElement(PropertiesBlock, { view, to }), false);
                 break;
             case 'callout':
                 if (!alone(from, to))
@@ -308,7 +422,7 @@ function build(state) {
                     eachLine(from, to, `cm-ms-callout-source`);
                 else {
                     const marker = { ...construct.marker, type: construct.type, fold: construct.fold };
-                    block(from, to, `callout:${from}:${source}`, (view) => createElement(CalloutBlock, { view, text: source, marker }));
+                    block(from, to, 'callout', `callout:${from}:${source}`, (view) => createElement(CalloutBlock, { view, text: source, marker }));
                 }
                 break;
             case 'table':
@@ -317,14 +431,15 @@ function build(state) {
                 if (open)
                     eachLine(from, to, 'cm-ms-table-source');
                 else
-                    block(from, to, `table:${from}:${source}`, (view) => createElement(TableBlock, { view, from, to }), false);
+                    block(from, to, 'table', `table:${from}:${source}`, (view) => createElement(TableBlock, { view, from, to }), false);
                 break;
             case 'mathBlock':
                 if (!alone(from, to))
                     break;
                 if (open) {
                     eachLine(from, to, 'cm-ms-code-line');
-                    after(to, `math-preview:${construct.tex}`, () => createElement(Snippet, { text: `$$\n${construct.tex}\n$$` }));
+                    const preview = `$$\n${construct.tex}\n$$`;
+                    after(to, `math-preview:${construct.tex}`, () => createElement(Snippet, { text: preview }), preview);
                 }
                 else {
                     out.push(Decoration.replace({ widget: new MathWidget(construct.tex, true), block: true }).range(lines.from, lines.to));
@@ -335,7 +450,7 @@ function build(state) {
                 if (open)
                     out.push(mark('cm-ms-wikilink').range(from, to));
                 else
-                    block(from, to, `embed:${source}`, () => createElement(Snippet, { text: source }));
+                    block(from, to, 'embed', `embed:${source}`, () => createElement(Snippet, { text: source }));
                 break;
             case 'rule':
                 if (!alone(from, to))
@@ -350,7 +465,7 @@ function build(state) {
             case 'code': {
                 const diagram = construct.language === 'mermaid' && construct.open !== null;
                 if (diagram && !open && alone(from, to)) {
-                    block(from, to, `diagram:${source}`, () => createElement(Snippet, { text: source }));
+                    block(from, to, 'diagram', `diagram:${source}`, () => createElement(Snippet, { text: source }));
                     break;
                 }
                 codeLines(construct, out, doc, text);
@@ -359,12 +474,14 @@ function build(state) {
                     const fence = construct.open.from;
                     const language = construct.language;
                     out.push(Decoration.widget({
-                        widget: new BlockWidget(`language:${fence}:${language ?? ''}`, host, (view) => createElement(LanguageControl, { view, from: fence, language }), false, true),
+                        widget: new BlockWidget(`language:${fence}:${language ?? ''}`, host, (view) => createElement(LanguageControl, { view, from: fence, language }), false, { inline: true }),
                         side: 1,
                     }).range(construct.open.to));
                 }
-                if (diagram)
-                    after(to, `diagram-preview:${construct.code}`, () => createElement(Snippet, { text: '```mermaid\n' + construct.code + '\n```' }));
+                if (diagram) {
+                    const preview = '```mermaid\n' + construct.code + '\n```';
+                    after(to, `diagram-preview:${construct.code}`, () => createElement(Snippet, { text: preview }), preview);
+                }
                 covered.push(lines);
                 break;
             }
@@ -420,7 +537,7 @@ function build(state) {
                 const pending = host.reaches(construct.target) === 0 && !host.keeps(construct.target);
                 if (construct.embed && host.keeps(construct.target) && !touches(from, to)) {
                     const source = text.slice(from, to);
-                    out.push(Decoration.replace({ widget: new BlockWidget(`attachment:${source}`, host, () => createElement(Snippet, { text: source }), true, true) }).range(from, to));
+                    out.push(Decoration.replace({ widget: new BlockWidget(`attachment:${source}`, host, () => createElement(Snippet, { text: source }), true, { inline: true, source }) }).range(from, to));
                     break;
                 }
                 out.push(mark(`cm-ms-wikilink${pending ? ' cm-ms-pending' : ''}`, { 'data-target': construct.target, title: construct.target }).range(construct.label.from, construct.label.to));
@@ -660,10 +777,16 @@ const grammarLoader = ViewPlugin.fromClass(class {
         }
     }
 });
-/** The live page: the analysis, the decorations over it, and what the focus and a modifier-click do. */
-export function livePage() {
+/**
+ * The live page: the analysis, the decorations over it, and what the focus and a modifier-click do.
+ * `metrics` are the editor's text column measured before the editor is made, which the first drawn
+ * blocks estimate their height by; without them they assume `DEFAULT_METRICS` until it is measured.
+ */
+export function livePage(metrics) {
     return [
         analysisField,
+        metricsField.init(() => metrics ?? DEFAULT_METRICS),
+        metricsWatcher,
         focusField,
         decorationsField,
         EditorView.focusChangeEffect.of((_state, focusing) => setFocused.of(focusing)),

package/dist/host.d.ts

@@ -92,9 +92,21 @@ export interface NoteHost {
     /**
      * Draws a file the notebook keeps where a note embeds it: an image, audio, video, or a card. The
      * dimensions are the ones the embed declared, in CSS pixels, or `null`.
+     *
+     * In edit mode the node may be drawn outside the host's React tree, in the root of a block the
+     * editor draws, so it must not depend on the host's context; a node that throws there leaves the
+     * block's Markdown in its place (#90).
      */
     readonly renderAttachment?: (file: AttachmentRequest) => ReactNode;
-    /** Draws a link to an internal address, through the host's router. */
+    /**
+     * Draws a link to an internal address, through the host's router.
+     *
+     * In edit mode the node may be drawn outside the host's React tree, in the root of a block the
+     * editor draws — a callout, a table, an embed, the properties — so it must not depend on the host's
+     * context: a router's `<Link>`, which reads its router from context, throws there. Hand it what it
+     * needs (a `navigate` captured where the router is) or draw an anchor whose click the host follows.
+     * A node that throws leaves the block's Markdown in its place (#90).
+     */
     readonly renderLink?: (link: LinkRequest) => ReactNode;
     /** The words the page shows, in the reader's language; each one left out is MemorySmith's English. */
     readonly strings?: NoteStringsInput;

package/dist/strings.d.ts

@@ -109,6 +109,8 @@ export interface EditorWords {
     readonly attachFailed: string;
     /** Said after the host's step while more files wait their turn (#88). */
     readonly attachQueued: (count: number) => string;
+    /** Said over a drawn block's lines when drawing it failed, so the block is never left empty (#90). */
+    readonly blockFailed: string;
     /** A code block's language, chosen at its top right (#84). */
     readonly language: string;
     readonly plainText: string;

package/dist/strings.js

@@ -113,6 +113,7 @@ export const ENGLISH = {
         attaching: 'Attaching…',
         attachFailed: 'The file was not attached',
         attachQueued: (count) => (count === 1 ? '1 more file waiting' : `${count} more files waiting`),
+        blockFailed: 'This block could not be drawn; its Markdown is below',
         language: 'Language',
         plainText: 'Plain text',
         mermaidDiagram: 'Mermaid diagram',

package/dist/theme.d.ts

@@ -315,7 +315,10 @@ export interface Theme {
     };
     /** An icon per callout kind, drawn in the title in place of the stylesheet's. */
     readonly icons?: Readonly<Record<string, ReactNode>>;
-    /** The slots the theme fills. */
+    /**
+     * The slots the theme fills. In edit mode a slot may be drawn outside the host's React tree, in
+     * the root of a block the editor draws, so it must not depend on the host's context (#90).
+     */
     readonly components?: Partial<ThemeComponents>;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorysmithapp/markdown-renderer",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A React component that draws a MemorySmith note exactly as MemorySmith's reading page does.",
   "keywords": [
     "markdown",
@@ -79,7 +79,7 @@
     "unified": "11.0.5"
   },
   "devDependencies": {
-    "@memorysmithapp/markdown-spec": "0.5.0",
+    "@memorysmithapp/markdown-spec": "0.6.0",
     "@types/hast": "3.0.5",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",

package/structure.css

@@ -15,6 +15,13 @@
   box-sizing: border-box;
 }
 
+/* What is laid out of the flow hangs from the note, never from the page: a
+   host that scrolls the note in a pane of its own keeps a page of its own
+   height (#93). */
+.markdown {
+  position: relative;
+}
+
 .markdown img {
   max-width: 100%;
 }
@@ -397,6 +404,12 @@
 .markdown .cm-ms-math-block {
   display: flow-root;
 }
+/* A block that could not be drawn shows its lines as they were written (#90). */
+.markdown .cm-ms-block-failed pre {
+  margin: 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
 /* A table's cell is where a click edits it: it fills its column and keeps a
    size of its own when it is empty, as every cell of a new table is, or it
    would be nothing wide and nothing could be clicked (#68). */

package/theme-default.css

@@ -1913,6 +1913,20 @@
 .markdown .cm-ms-block:hover {
   box-shadow: 0 0 0 1px var(--ms-border);
 }
+.markdown .cm-ms-block-failed {
+  padding: 0.5rem 0.75rem;
+  border: 1px dashed var(--ms-border);
+  border-radius: var(--ms-radius);
+}
+.markdown .cm-ms-block-failed-notice {
+  margin: 0 0 0.35rem;
+  color: var(--ms-text-soft);
+  font-size: 0.85em;
+}
+.markdown .cm-ms-block-failed pre {
+  font-family: var(--ms-font-mono);
+  font-size: 0.9em;
+}
 .markdown .edit-block-controls {
   opacity: 0;
   padding: 0.1rem;