@memorysmithapp/markdown-renderer 0.4.0 → 0.6.0

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/index.d.ts

@@ -2,3 +2,4 @@ export { lineBreakOf, NoteEditor, type NoteEditorProps } from './NoteEditor.js';
 export { analyze, frontmatterSpan, type Analysis, type Construct, type Span } from './analyze.js';
 export { readTable, type Alignment, type Table, type TextChange } from './table.js';
 export { readFrontmatter, type Frontmatter, type FrontmatterEntry } from './frontmatter.js';
+export { isSaveNotice, type SaveAction, type SaveNotice, type SaveOutcome, type SaveRefusal } from './saves.js';

package/dist/edit/index.js

@@ -4,3 +4,4 @@ export { lineBreakOf, NoteEditor } from './NoteEditor.js';
 export { analyze, frontmatterSpan } from './analyze.js';
 export { readTable } from './table.js';
 export { readFrontmatter } from './frontmatter.js';
+export { isSaveNotice } from './saves.js';

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/edit/saves.d.ts

@@ -1,18 +1,48 @@
 /**
- * Where the save of the author's edits stands (#64).
+ * Where the save of the author's edits stands (#64, #86).
  *
  * The host saves each change it is handed. When `onChange` answers with a promise, the editor
  * follows it: saving while it is pending, saved once it resolves, not saved when it rejects. Only
  * the latest change counts: a save that settles after a later change was handed says nothing, so
  * "Saved" always means the last text the author wrote. A host that answers with nothing has no
  * status, and the editor shows none.
+ *
+ * A host may also say why (#86): a save that resolves with a `SaveOutcome` succeeded with
+ * something the author must decide, the alert; one rejected with a `SaveRefusal` was refused for
+ * a reason the host explains, the error. Either carries the actions the author chooses from, and
+ * an action the author runs is followed like a save.
  */
-export type EditSave = 'idle' | 'saving' | 'saved' | 'failed';
+/** One choice the host offers the author: its word, and what choosing it does. */
+export interface SaveAction {
+    /** The button's word, in the reader's language: the host words it. */
+    readonly label: string;
+    /** Runs the choice; a promise answered is followed like a save, and may end in another notice. */
+    readonly run: () => Promise<void | SaveOutcome> | void;
+}
+/** What the host has to say about a save, and the choices it gives the author. */
+export interface SaveNotice {
+    /** The dialog's title, and the status button's tooltip. */
+    readonly title: string;
+    /** The explanation in the dialog. */
+    readonly message: string;
+    readonly actions: readonly SaveAction[];
+}
+/** A save that succeeded with something the author must decide: what `onChange`'s promise resolves with. */
+export type SaveOutcome = SaveNotice;
+/** A save the host refused, with its reason and its choices: what `onChange`'s promise rejects with. */
+export type SaveRefusal = SaveNotice;
+export type EditSave = 'idle' | 'saving' | 'saved' | 'alert' | 'failed';
 export interface EditSaves {
     readonly state: EditSave;
+    /** What the host said of the save: present in `alert`, and in `failed` when it gave a reason. */
+    readonly notice: SaveNotice | null;
     /** Hands a change to the host and follows its save. */
     readonly hand: (markdown: string) => void;
     /** Hands the latest change to the host again, after a save failed. */
     readonly retry: () => void;
+    /** Runs one of the notice's actions and follows it like a save. */
+    readonly run: (action: SaveAction) => void;
 }
+/** Whether a value is a notice a host gave: a title, a message and its actions. */
+export declare function isSaveNotice(value: unknown): value is SaveNotice;
 export declare function useEditSaves(onChange: ((markdown: string) => unknown) | undefined): EditSaves;

package/dist/edit/saves.js

@@ -1,16 +1,31 @@
 /**
- * Where the save of the author's edits stands (#64).
+ * Where the save of the author's edits stands (#64, #86).
  *
  * The host saves each change it is handed. When `onChange` answers with a promise, the editor
  * follows it: saving while it is pending, saved once it resolves, not saved when it rejects. Only
  * the latest change counts: a save that settles after a later change was handed says nothing, so
  * "Saved" always means the last text the author wrote. A host that answers with nothing has no
  * status, and the editor shows none.
+ *
+ * A host may also say why (#86): a save that resolves with a `SaveOutcome` succeeded with
+ * something the author must decide, the alert; one rejected with a `SaveRefusal` was refused for
+ * a reason the host explains, the error. Either carries the actions the author chooses from, and
+ * an action the author runs is followed like a save.
  */
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { isThenable } from '../task-saves.js';
+/** Whether a value is a notice a host gave: a title, a message and its actions. */
+export function isSaveNotice(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const notice = value;
+    return (typeof notice.title === 'string' &&
+        typeof notice.message === 'string' &&
+        Array.isArray(notice.actions) &&
+        notice.actions.every((action) => typeof action === 'object' && action !== null && typeof action.label === 'string' && typeof action.run === 'function'));
+}
 export function useEditSaves(onChange) {
-    const [state, setState] = useState('idle');
+    const [status, setStatus] = useState({ state: 'idle', notice: null });
     const latest = useRef({ onChange, count: 0, text: null, alive: true });
     latest.current.onChange = onChange;
     useEffect(() => {
@@ -20,33 +35,39 @@ export function useEditSaves(onChange) {
             self.alive = false;
         };
     }, []);
-    const hand = useCallback((markdown) => {
+    /** Follows what the host answered, a change's save or an action; `done` is the state of an answer that is not a promise. */
+    const follow = useCallback((answer, done) => {
         const self = latest.current;
-        self.text = markdown;
         const count = ++self.count;
-        const settle = (next) => {
+        const settle = (state, notice = null) => {
             if (self.alive && count === self.count)
-                setState(next);
+                setStatus({ state, notice });
         };
         let result;
         try {
-            result = self.onChange?.(markdown);
+            result = answer();
         }
-        catch {
-            settle('failed');
+        catch (reason) {
+            settle('failed', isSaveNotice(reason) ? reason : null);
             return;
         }
         if (!isThenable(result)) {
-            settle('idle');
+            settle(done);
             return;
         }
         settle('saving');
-        result.then(() => settle('saved'), () => settle('failed'));
+        result.then((value) => (isSaveNotice(value) ? settle('alert', value) : settle('saved')), (reason) => settle('failed', isSaveNotice(reason) ? reason : null));
     }, []);
+    const hand = useCallback((markdown) => {
+        latest.current.text = markdown;
+        follow(() => latest.current.onChange?.(markdown), 'idle');
+    }, [follow]);
     const retry = useCallback(() => {
         const text = latest.current.text;
         if (text !== null)
             hand(text);
     }, [hand]);
-    return { state, hand, retry };
+    // An action that answers nothing has done what it does: the author decided, and nothing is left to say.
+    const run = useCallback((action) => follow(() => action.run(), 'saved'), [follow]);
+    return { state: status.state, notice: status.notice, hand, retry, run };
 }