@memorysmithapp/markdown-renderer 0.4.0 → 0.5.0

package/README.md

@@ -76,7 +76,7 @@ Import `structure.css` instead of `styles.css` for a theme that draws everything
 
 ## Edit
 
-A note the host makes `editable` carries a button at its top right that switches between reading and editing it on the same page. The author edits what they see: marks, headings, lists, tasks, links and the names of notes after `[[`, callouts, tables cell by cell, code, formulas and diagrams with their drawing live, the properties as a form, footnotes and comments. The note is the bytes you gave, and every change comes back whole through `onChange`, unchanged wherever the author did not touch it — the order and quoting of the frontmatter, a list's marker, a table's spacing, a comment, a line break. The package never saves. The toolbar grows out of the switch, which becomes its last control; its first tool undoes every change since editing began, and a right-click on the text opens a menu of the same tools where you are (Shift keeps the browser's); beside the switch, in both modes, Show Markdown opens the note's Markdown, as you have it or would receive it, in a dialog, and Copy Markdown copies it.
+A note the host makes `editable` carries a button at its top right that switches between reading and editing it on the same page. The author edits what they see: marks, headings, lists, tasks, links and the names of notes after `[[`, callouts, tables cell by cell, code, formulas and diagrams with their drawing live, the properties as a form, footnotes and comments. The note is the bytes you gave, and every change comes back whole through `onChange`, unchanged wherever the author did not touch it — the order and quoting of the frontmatter, a list's marker, a table's spacing, a comment, a line break. The package never saves. The toolbar grows out of the switch, which becomes its last control; its first tool undoes every change since editing began, and a right-click on the text opens a menu of the same tools where you are (Shift keeps the browser's); beside the switch, in both modes, Show Markdown opens the note's Markdown, as you have it or would receive it, in a dialog, and Copy Markdown copies it. Those two are reading, so a note that is not `editable` carries them too, without the switch; pass `actions={false}` to hide them, for a print, a preview or an embed.
 
 ```tsx
 <NoteBody
@@ -84,13 +84,31 @@ A note the host makes `editable` carries a button at its top right that switches
   editable                                        // the switch, at the top right
   onChange={(next) => save(next)}                 // after every change; return the save's promise
   suggest={(typed) => namesOfNotesLike(typed)}    // what [[ offers
-  attach={(file, { name, description }) => keepInNotebook(file, name, description)} // the name it is kept under
+  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
 />
 ```
 
-When `onChange` returns the promise of its save, the editor shows before the switch an icon for whether the last change is *Saving…*, *Saved* or *Not saved*, the last one's icon trying again when clicked, and going back to reading waits for the save, staying in edit when it failed. Return nothing and no status is shown. Pass the saved note back as `markdown` whenever you like: a text the editor already moved past is not applied over what the author typed since.
+When `onChange` returns the promise of its save, the editor shows before the switch an icon for whether the last change is *Saving…*, *Saved* or *Not saved*, the last one's icon trying again when clicked, and going back to reading waits for the save, staying in edit when it failed. Return nothing and no status is shown. When there is something to tell the author, resolve the promise with a `SaveOutcome` (the save went through, and they have a choice to make) or reject it with a `SaveRefusal` (it did not, and why): each is a `title`, a `message` and the `actions` to choose from, in your words. The icon then opens a dialog with them; an action's promise is followed like a save, and the author can close the dialog and come back to it:
+
+```tsx
+onChange={async (next) => {
+  const saved = await save(next);
+  if (saved.conflict) throw { title: 'Somebody else wrote this note', message: 'Your edit was not saved.', actions: [
+    { label: 'Discard my edit and reload', run: () => reload() },
+    { label: 'Save anyway', run: () => save(next, { force: true }) },
+  ] } satisfies SaveRefusal;
+  if (saved.renamed) return { title: 'Note renamed', message: `${saved.links} links reached the old name.`, actions: [
+    { label: 'Keep the links broken', run: () => undefined },
+    { label: 'Keep the old name as an alias', run: () => addAlias() },
+  ] } satisfies SaveOutcome;
+}}
+```
+
+While `attach` keeps a file, call `progress({ message, fraction })` with each step in your words — *Sending part 12 of 40*, and `0.3` — and the paperclip shows it, a bar filling when you give the fraction. Reject with `{ message }` (an `AttachRefusal`, not an `Error`) to tell the author why the file was refused; the paperclip says it until they open it again. An `Error` keeps the paperclip's own *The file was not attached*.
+
+Pass the saved note back as `markdown` whenever you like: a text the editor already moved past is not applied over what the author typed since.
 
 `mode` and `onModeChange` let you control the mode yourself, and the words come from `strings` (`edit`, `view` and `editor`). The editor is CodeMirror, loaded the first time a note is edited, so a page that only draws never loads it. To edit without the switch, import it from its own entry point:
 

package/dist/NoteBody.d.ts

@@ -7,7 +7,7 @@ export interface NoteBodyProps extends NoteHost {
     readonly markdown: string;
     /**
      * Whether the note offers the switch to edit it, at its top right (#51). Defaults to `false`:
-     * no switch, and the page is the one a reader always had.
+     * no switch, the note only read, with Show and Copy Markdown as `actions` says.
      */
     readonly editable?: boolean;
     /** The mode, for a host that controls it; left out, the note keeps its own, starting from `defaultMode`. */
@@ -19,11 +19,20 @@ export interface NoteBodyProps extends NoteHost {
     /**
      * The note after each change made in edit mode, byte for byte the original wherever it was not
      * edited. The package never saves it; a host that answers with the promise of its save has the
-     * editor say whether it was saved, and going back to reading wait for it (#64).
+     * editor say whether it was saved, and going back to reading wait for it (#64). The promise may
+     * resolve with a `SaveOutcome`, a save that succeeded with something the author must decide, or
+     * reject with a `SaveRefusal`, the reason it was refused: either opens, from the save's status,
+     * 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`. */
     readonly modeButton?: 'icon' | 'label';
+    /**
+     * Whether the note offers Show Markdown and Copy Markdown at its top right, editable or not:
+     * reading a note's Markdown and copying it are reading (#87). Defaults to `true`; `false` hides
+     * them, for a print, a preview or an embed.
+     */
+    readonly actions?: boolean;
 }
 /** Whether a note is read or edited. */
 export type NoteMode = 'view' | 'edit';
@@ -33,4 +42,4 @@ export type NoteMode = 'view' | 'edit';
  * 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 declare function NoteBody({ editable, mode, defaultMode, onModeChange, onChange, modeButton, ...rest }: NoteBodyProps): import("react").JSX.Element;
+export declare function NoteBody({ editable, mode, defaultMode, onModeChange, onChange, modeButton, actions, ...rest }: NoteBodyProps): import("react").JSX.Element;

package/dist/NoteBody.js

@@ -34,14 +34,14 @@ 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', ...rest }) {
+export function NoteBody({ editable = false, mode, defaultMode = 'view', onModeChange, onChange, modeButton = 'label', 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);
     // The last text handed to the host in edit mode, which Show and Copy Markdown give there (#76).
     const handed = useRef(null);
     const current = editable ? (mode ?? own) : 'view';
-    if (!editable)
+    if (!editable && !actions)
         return _jsx(NoteView, { ...rest });
     const go = (next) => {
         if (mode === undefined)
@@ -67,13 +67,14 @@ export function NoteBody({ editable = false, mode, defaultMode = 'view', onModeC
     };
     const { writable: _writable, onToggleTask: _toggle, ...host } = rest;
     return (_jsx(HostOnly, { host: rest, children: (resolved) => {
-            // The switch, with Show and Copy Markdown beside it in both modes (#76).
-            const corner = (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: "note-corner", children: [_jsx(NoteActions, { text: () => (current === 'edit' ? (handed.current ?? rest.markdown) : rest.markdown) }), _jsx(ModeSwitch, { mode: current, display: modeButton, toggle: toggle })] }) }));
+            // Show and Copy Markdown for whoever reads the note, in both modes (#76, #87), and the
+            // switch only where the note is editable.
+            const corner = (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: "note-corner", children: [actions && _jsx(NoteActions, { text: () => (current === 'edit' ? (handed.current ?? rest.markdown) : rest.markdown) }), editable && _jsx(ModeSwitch, { mode: current, display: modeButton, toggle: toggle })] }) }));
             if (current === 'view')
-                return _jsx(NoteView, { ...rest, corner: corner });
+                return _jsx(NoteView, { ...rest, corner: corner, switched: editable });
             return (
             // While the editor loads, the note stays on the page as it was.
-            _jsx(Suspense, { fallback: _jsx(NoteView, { ...rest, corner: corner }), children: _jsx(NoteEditor, { ...host, onChange: hand, corner: corner, autoFocus: true, leaving: leaving, onLeave: onLeave }) }));
+            _jsx(Suspense, { fallback: _jsx(NoteView, { ...rest, corner: corner, switched: true }), children: _jsx(NoteEditor, { ...host, onChange: hand, corner: corner, autoFocus: true, leaving: leaving, onLeave: onLeave }) }));
         } }));
 }
 /** The host resolved once, for what is drawn around the note. */
@@ -82,7 +83,7 @@ function HostOnly({ host, children }) {
     return _jsx(_Fragment, { children: children(resolved) });
 }
 /** The note drawn for reading: the page MemorySmith's reading page draws. */
-function NoteView({ markdown, writable = false, onToggleTask, corner, ...host }) {
+function NoteView({ markdown, writable = false, onToggleTask, corner, switched = false, ...host }) {
     const resolved = useMemo(() => resolveHost(host), 
     // Every member of the contract, so a host that passes the same functions keeps the same host.
     HOST_KEYS.map((key) => host[key]));
@@ -146,7 +147,7 @@ function NoteView({ markdown, writable = false, onToggleTask, corner, ...host })
     // The runs and whether an embed cut them are the whole input.
     [runs.join('\u0000'), runs.length < segments.length]);
     let run = 0;
-    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: `markdown markdown-theme-${resolved.theme.name}${corner ? ' has-mode-switch' : ''}`, "data-theme": resolved.scheme, style: rootStyle(resolved.theme, resolved.scheme), children: [corner, _jsx(Properties, { properties: properties }), segments.map((segment, index) => {
+    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: `markdown markdown-theme-${resolved.theme.name}${corner ? ' has-note-corner' : ''}${switched ? ' has-mode-switch' : ''}`, "data-theme": resolved.scheme, style: rootStyle(resolved.theme, resolved.scheme), children: [corner, _jsx(Properties, { properties: properties }), segments.map((segment, index) => {
                     if (!('rendered' in segment)) {
                         return _jsx(Transclusion, { target: segment.target, anchor: segment.anchor }, index);
                     }

package/dist/edit/AttachDialog.d.ts

@@ -11,7 +11,9 @@ export interface ChosenFile {
 }
 /** The Markdown of an image at a web address, its name the alternative text (§3.14). */
 export declare function webImage(name: string, address: string): string;
-export declare function AttachDialog({ onClose, onClosed, onAttach, onEmbed, onLink, }: {
+export declare function AttachDialog({ refusal, onClose, onClosed, onAttach, onEmbed, onLink, }: {
+    /** Why the host refused the last file, said at the top of the dialog the author opened after it (#88). */
+    refusal?: string | null;
     onClose: () => void;
     /** Once the dialog is closed: whether something was put in the note, which then has the focus. */
     onClosed: (inserted: boolean) => void;

package/dist/edit/AttachDialog.js

@@ -17,7 +17,7 @@ export function webImage(name, address) {
     const target = /[\s()<>]/.test(address) ? `<${address.replace(/[<>]/g, encodeURIComponent)}>` : address;
     return `![${alt}](${target})`;
 }
-export function AttachDialog({ onClose, onClosed, onAttach, onEmbed, onLink, }) {
+export function AttachDialog({ refusal = null, onClose, onClosed, onAttach, onEmbed, onLink, }) {
     const host = useHost();
     const words = host.strings.editor;
     const ways = [...(host.attach ? ['computer'] : []), ...(host.files ? ['notebook'] : []), 'web'];
@@ -51,7 +51,7 @@ export function AttachDialog({ onClose, onClosed, onAttach, onEmbed, onLink, })
     return (_jsx("dialog", { ref: dialog, className: "edit-source edit-attach", "aria-modal": "true", "aria-labelledby": `${id}-title`, onCancel: (event) => {
             event.preventDefault();
             onClose();
-        }, onClick: (event) => event.target === dialog.current && onClose(), children: _jsxs("div", { className: "edit-source-frame", children: [_jsxs("header", { className: "edit-source-header", children: [_jsx("h2", { id: `${id}-title`, className: "edit-source-title", children: words.attachTitle }), _jsx("button", { type: "button", className: "edit-control edit-source-close", "aria-label": host.strings.close, title: host.strings.close, onClick: onClose, children: ICONS.remove })] }), _jsx("div", { className: "edit-attach-ways", role: "tablist", "aria-label": words.attachTitle, children: ways.map((each) => (_jsx("button", { type: "button", role: "tab", id: `${id}-${each}`, "aria-selected": each === way, "aria-controls": `${id}-panel`, tabIndex: each === way ? 0 : -1, className: "edit-attach-way", onClick: () => setWay(each), onKeyDown: (event) => {
+        }, onClick: (event) => event.target === dialog.current && onClose(), children: _jsxs("div", { className: "edit-source-frame", children: [_jsxs("header", { className: "edit-source-header", children: [_jsx("h2", { id: `${id}-title`, className: "edit-source-title", children: words.attachTitle }), _jsx("button", { type: "button", className: "edit-control edit-source-close", "aria-label": host.strings.close, title: host.strings.close, onClick: onClose, children: ICONS.remove })] }), refusal && _jsx("p", { className: "edit-attach-error edit-attach-refusal", children: refusal }), _jsx("div", { className: "edit-attach-ways", role: "tablist", "aria-label": words.attachTitle, children: ways.map((each) => (_jsx("button", { type: "button", role: "tab", id: `${id}-${each}`, "aria-selected": each === way, "aria-controls": `${id}-panel`, tabIndex: each === way ? 0 : -1, className: "edit-attach-way", onClick: () => setWay(each), onKeyDown: (event) => {
                             const step = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0;
                             if (step === 0)
                                 return;

package/dist/edit/NoteEditor.d.ts

@@ -14,7 +14,8 @@ export interface NoteEditorProps extends Omit<NoteHost, 'writable' | 'onToggleTa
     readonly markdown: string;
     /**
      * The note after each change the author makes, byte for byte the original wherever it was not
-     * edited. A promise answered is the save of that change, which the editor reports (#64).
+     * edited. A promise answered is the save of that change, which the editor reports (#64); one that
+     * resolves with a `SaveOutcome` or rejects with a `SaveRefusal` has the host's words and actions (#86).
      */
     readonly onChange?: (markdown: string) => unknown;
     /** Whether the author may change the note. Defaults to `true`. */

package/dist/edit/NoteEditor.js

@@ -14,7 +14,7 @@ import { markdown, markdownKeymap } from '@codemirror/lang-markdown';
 import { Annotation, Compartment, EditorState } from '@codemirror/state';
 import { EditorView, keymap } from '@codemirror/view';
 import { useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } from 'react';
-import { HOST_KEYS, HostProvider, resolveHost } from '../host.js';
+import { HOST_KEYS, HostProvider, isAttachRefusal, resolveHost } from '../host.js';
 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';
@@ -24,6 +24,7 @@ import { AttachDialog, webImage } from './AttachDialog.js';
 import { ContextMenu } from './ContextMenu.js';
 import { chooseLanguageAt } from './LanguageControl.js';
 import { useEditSaves } from './saves.js';
+import { SaveNoticeDialog } from './SaveNoticeDialog.js';
 /**
  * The line break a note is written with, which the editor writes back: `\n` or `\r\n`. `null`
  * for a note that mixes them, or has a lone `\r`, which the editor cannot keep byte for byte.
@@ -110,8 +111,23 @@ function insertBlockCommand(name) {
         return true;
     };
 }
-/** How long the attach button says a file was not attached, in milliseconds. */
+const NOT_ATTACHING = { state: 'idle', message: null, fraction: null, queued: 0 };
+/** How long the attach button says a file was not attached, when the host did not say why, in milliseconds. */
 const ATTACH_FAILED_MS = 3000;
+/** A host's fraction, kept between 0 and 1, or none when it gave no number. */
+function fractionOf(report) {
+    const fraction = report?.fraction;
+    return typeof fraction === 'number' && Number.isFinite(fraction) ? Math.min(1, Math.max(0, fraction)) : null;
+}
+/** What the paperclip says: its word, the host's step and the files waiting, or why the last one failed. */
+function attachSays(attaching, words) {
+    if (attaching.state === 'failed')
+        return attaching.message ?? words.attachFailed;
+    if (attaching.state === 'idle')
+        return words.attach;
+    const step = attaching.message ?? words.attaching;
+    return attaching.queued > 0 ? `${step} (${words.attachQueued(attaching.queued)})` : step;
+}
 /** The toolbar of the editor: the marks, the blocks and the history, each a command. */
 function Toolbar({ view, host, end, opened, onAttach, attaching, attachButton, }) {
     const words = host.strings.editor;
@@ -120,21 +136,35 @@ function Toolbar({ view, host, end, opened, onAttach, attaching, attachButton, }
     const button = (name, action, shortcut) => (_jsx("button", { type: "button", className: "edit-control", title: shortcut ? `${words[name]} (${shortcut})` : words[name], "aria-label": words[name], disabled: disabled, onMouseDown: (event) => event.preventDefault(), onClick: run(action), children: ICONS[name] }, name));
     const block = (name) => button(name, insertBlockCommand(name));
     const level = view ? headingLevel(view.state) : 0;
-    return (_jsxs("div", { className: "edit-toolbar", role: "toolbar", "aria-label": words.toolbar, children: [_jsxs("div", { className: "edit-toolbar-tools", children: [_jsxs("span", { className: "edit-toolbar-group", children: [_jsx("button", { type: "button", className: "edit-control", title: words.revert, "aria-label": words.revert, disabled: !view || view.state.readOnly || view.state.doc.toString() === opened, onMouseDown: (event) => event.preventDefault(), onClick: run(command((state) => revert(state, opened))), children: ICONS.revert }), button('undo', undo, 'Mod-Z'), button('redo', redo, 'Mod-Shift-Z')] }), _jsx("span", { className: "edit-toolbar-group", children: _jsxs("select", { className: "edit-heading", "aria-label": words.heading, title: words.heading, value: level, disabled: disabled, onChange: (event) => view && command((state) => setHeading(state, Number(event.target.value)))(view), children: [_jsx("option", { value: 0, children: words.paragraph }), [1, 2, 3, 4, 5, 6].map((each) => (_jsx("option", { value: each, children: `${words.heading} ${each}` }, each)))] }) }), _jsxs("span", { className: "edit-toolbar-group", children: [button('bold', command((state) => toggleMark(state, '**')), 'Mod-B'), button('italic', command((state) => toggleMark(state, '_')), 'Mod-I'), button('strikethrough', command((state) => toggleMark(state, '~~')), 'Mod-Shift-X'), button('highlight', command((state) => toggleMark(state, '==')), 'Mod-Shift-H'), button('code', command((state) => toggleMark(state, '`')), 'Mod-E')] }), _jsxs("span", { className: "edit-toolbar-group", children: [button('link', command(insertLink), 'Mod-K'), button('wikilink', command(insertWikilink), 'Mod-Shift-K'), button('footnote', command(insertFootnote)), button('comment', command(toggleComment), 'Mod-/'), _jsx("button", { ref: attachButton, type: "button", className: "edit-control", title: attaching === 'busy' ? words.attaching : attaching === 'failed' ? words.attachFailed : words.attach, "aria-label": words.attach, "aria-busy": attaching === 'busy' ? true : undefined, "data-attach": attaching, disabled: disabled, onMouseDown: (event) => event.preventDefault(), onClick: onAttach, children: attaching === 'busy' ? ICONS.saving : attaching === 'failed' ? ICONS.notSaved : ICONS.attach })] }), _jsxs("span", { className: "edit-toolbar-group", children: [button('bulletList', command((state) => toggleList(state, 'bullet')), 'Mod-Shift-8'), button('orderedList', command((state) => toggleList(state, 'ordered')), 'Mod-Shift-7'), button('taskList', command((state) => toggleList(state, 'task')), 'Mod-Shift-9'), button('quote', command(toggleQuote), 'Mod-Shift-.')] }), _jsxs("span", { className: "edit-toolbar-group", children: [block('callout'), block('table'), block('codeBlock'), block('math'), block('diagram'), block('rule')] })] }), end] }));
+    return (_jsxs("div", { className: "edit-toolbar", role: "toolbar", "aria-label": words.toolbar, children: [_jsxs("div", { className: "edit-toolbar-tools", children: [_jsxs("span", { className: "edit-toolbar-group", children: [_jsx("button", { type: "button", className: "edit-control", title: words.revert, "aria-label": words.revert, disabled: !view || view.state.readOnly || view.state.doc.toString() === opened, onMouseDown: (event) => event.preventDefault(), onClick: run(command((state) => revert(state, opened))), children: ICONS.revert }), button('undo', undo, 'Mod-Z'), button('redo', redo, 'Mod-Shift-Z')] }), _jsx("span", { className: "edit-toolbar-group", children: _jsxs("select", { className: "edit-heading", "aria-label": words.heading, title: words.heading, value: level, disabled: disabled, onChange: (event) => view && command((state) => setHeading(state, Number(event.target.value)))(view), children: [_jsx("option", { value: 0, children: words.paragraph }), [1, 2, 3, 4, 5, 6].map((each) => (_jsx("option", { value: each, children: `${words.heading} ${each}` }, each)))] }) }), _jsxs("span", { className: "edit-toolbar-group", children: [button('bold', command((state) => toggleMark(state, '**')), 'Mod-B'), button('italic', command((state) => toggleMark(state, '_')), 'Mod-I'), button('strikethrough', command((state) => toggleMark(state, '~~')), 'Mod-Shift-X'), button('highlight', command((state) => toggleMark(state, '==')), 'Mod-Shift-H'), button('code', command((state) => toggleMark(state, '`')), 'Mod-E')] }), _jsxs("span", { className: "edit-toolbar-group", children: [button('link', command(insertLink), 'Mod-K'), button('wikilink', command(insertWikilink), 'Mod-Shift-K'), button('footnote', command(insertFootnote)), button('comment', command(toggleComment), 'Mod-/'), _jsxs("span", { className: "edit-attach-control", children: [_jsx("button", { ref: attachButton, type: "button", className: "edit-control", title: attachSays(attaching, words), "aria-label": words.attach, "aria-busy": attaching.state === 'busy' ? true : undefined, "data-attach": attaching.state, disabled: disabled, onMouseDown: (event) => event.preventDefault(), onClick: onAttach, children: attaching.state === 'busy' ? ICONS.saving : attaching.state === 'failed' ? ICONS.notSaved : ICONS.attach }), attaching.state === 'busy' && attaching.fraction !== null && (_jsx("span", { className: "edit-attach-progress", role: "progressbar", "aria-label": words.attach, "aria-valuemin": 0, "aria-valuemax": 100, "aria-valuenow": Math.round(attaching.fraction * 100), style: { ['--edit-attach-fraction']: attaching.fraction } })), _jsx("span", { className: "visually-hidden", role: "status", "aria-live": "polite", children: attaching.state === 'idle' ? '' : attachSays(attaching, words) })] })] }), _jsxs("span", { className: "edit-toolbar-group", children: [button('bulletList', command((state) => toggleList(state, 'bullet')), 'Mod-Shift-8'), button('orderedList', command((state) => toggleList(state, 'ordered')), 'Mod-Shift-7'), button('taskList', command((state) => toggleList(state, 'task')), 'Mod-Shift-9'), button('quote', command(toggleQuote), 'Mod-Shift-.')] }), _jsxs("span", { className: "edit-toolbar-group", children: [block('callout'), block('table'), block('codeBlock'), block('math'), block('diagram'), block('rule')] })] }), end] }));
 }
 /**
  * Where the save of the author's last change stands, in the toolbar before the switch: an icon for
  * each state, in a slot of one size, so the toolbar never moves as the author types; its word is
- * its title. A failed save's icon is the button that tries again (#66). Whoever hears the page is
- * told the whole of it, why the note stays in edit included.
+ * its title. A failed save's icon is the button that tries again (#66). When the host said why —
+ * an alert on a save that succeeded, or the reason for one it refused — the icon is the button that
+ * opens what it said, with the host's title as its tooltip, and the author's choices (#86). Whoever
+ * hears the page is told the whole of it, why the note stays in edit included.
  */
-function SaveStatus({ state, blocked, retry, host }) {
+function SaveStatus({ saves, blocked, host, onDecided }) {
+    const { state, notice } = saves;
     const words = host.strings.editor;
-    const shown = state === 'saving' ? words.saving : state === 'saved' ? host.strings.saved : state === 'failed' ? host.strings.notSaved : '';
-    const said = state === 'failed' && blocked ? words.stayInEdit : shown;
-    const icon = state === 'saving' ? ICONS.saving : state === 'saved' ? ICONS.saved : state === 'failed' ? ICONS.notSaved : null;
+    const [open, setOpen] = useState(false);
+    const button = useRef(null);
+    // A notice the save no longer carries has nothing left to show.
+    useEffect(() => {
+        if (!notice)
+            setOpen(false);
+    }, [notice]);
+    const base = state === 'saving' ? words.saving : state === 'saved' ? host.strings.saved : state === 'failed' ? host.strings.notSaved : '';
+    const shown = notice ? notice.title : base;
+    const said = state === 'failed' && blocked ? (notice ? `${words.stayInEdit}. ${notice.title}` : words.stayInEdit) : shown;
+    const icon = state === 'saving' ? ICONS.saving : state === 'saved' ? ICONS.saved : state === 'alert' ? ICONS.alert : state === 'failed' ? ICONS.notSaved : null;
     const retryLabel = `${said}. ${words.retry}`;
-    return (_jsxs("div", { className: "edit-save", "data-save": state, title: state === 'failed' ? undefined : said || undefined, children: [state === 'failed' ? (_jsx("button", { type: "button", className: "edit-save-icon edit-save-retry", title: retryLabel, "aria-label": retryLabel, onClick: retry, children: icon })) : (_jsx("span", { className: "edit-save-icon", children: icon })), _jsx("span", { className: "visually-hidden", role: "status", "aria-live": "polite", children: said })] }));
+    return (_jsxs("div", { className: "edit-save", "data-save": state, title: state === 'failed' || notice ? undefined : said || undefined, children: [notice ? (_jsx("button", { ref: button, type: "button", className: "edit-save-icon edit-save-notice", title: notice.title, "aria-label": notice.title, "aria-haspopup": "dialog", onClick: () => setOpen(true), children: icon })) : state === 'failed' ? (_jsx("button", { type: "button", className: "edit-save-icon edit-save-retry", title: retryLabel, "aria-label": retryLabel, onClick: saves.retry, children: icon })) : (_jsx("span", { className: "edit-save-icon", children: icon })), _jsx("span", { className: "visually-hidden", role: "status", "aria-live": "polite", children: said }), open && notice && (_jsx(SaveNoticeDialog, { notice: notice, onClose: () => setOpen(false), onClosed: (chosen) => (chosen ? onDecided() : button.current?.focus()), onAction: (action) => {
+                    setOpen(false);
+                    saves.run(action);
+                } }))] }));
 }
 /**
  * Edits a note on the page that draws it. Exported at `@memorysmithapp/markdown-renderer/edit`
@@ -162,11 +192,16 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
     const [blocked, setBlocked] = useState(false);
     const [refusals, setRefusals] = useState(0);
     const editorView = useRef(null);
-    const [attaching, setAttaching] = useState('idle');
+    const [attaching, setAttaching] = useState(NOT_ATTACHING);
+    // Each run of attaching, so that a run a later one replaced says nothing more.
+    const attachRun = useRef(0);
+    // The refusal the paperclip said, shown again at the top of the dialog it opens (#88).
+    const [refusal, setRefusal] = useState(null);
     /**
      * Hands each file to the host's `attach`, one after the other, and embeds it as `![[name]]` on a
      * line of its own where the cursor is once the host answered its name; a file the host could not
-     * keep writes nothing, and the button says so for a moment (#75).
+     * keep writes nothing, and the button says so for a moment (#75) — or, when the host said why,
+     * until the author opens it again. The host's steps are shown as they come (#88).
      */
     const attachFiles = useRef(() => undefined);
     attachFiles.current = (files, at) => {
@@ -176,20 +211,34 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
             return;
         if (at !== undefined)
             target.dispatch({ selection: { anchor: at } });
-        setAttaching('busy');
+        const run = ++attachRun.current;
+        const live = () => run === attachRun.current && editorView.current !== null;
         void (async () => {
             let failed = false;
-            for (const { file, name: wanted, description } of files) {
+            let reason = null;
+            for (const [index, { file, name: wanted, description }] of files.entries()) {
+                const queued = files.length - 1 - index;
+                let settled = false;
+                setAttaching({ state: 'busy', message: null, fraction: null, queued });
+                // A step the host reports after the file settled, or for a run since replaced, says nothing.
+                const progress = (report) => {
+                    if (settled || !live())
+                        return;
+                    setAttaching({ state: 'busy', message: typeof report?.message === 'string' && report.message ? report.message : null, fraction: fractionOf(report), queued });
+                };
                 try {
-                    const name = await attach(file, { name: wanted, description });
+                    const name = await attach(file, { name: wanted, description }, progress);
                     insertLine(`![[${name}]]`);
                 }
-                catch {
+                catch (rejection) {
                     failed = true;
+                    if (isAttachRefusal(rejection))
+                        reason = rejection.message;
                 }
+                settled = true;
             }
-            if (editorView.current)
-                setAttaching(failed ? 'failed' : 'idle');
+            if (live())
+                setAttaching(failed ? { ...NOT_ATTACHING, state: 'failed', message: reason } : NOT_ATTACHING);
         })();
     };
     /** A line of its own at the cursor: an embed, or an image of the web (#78). */
@@ -277,9 +326,10 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
     /** A pasted or dropped file, kept under its own name and with no description. */
     const asChosen = (files) => files.map((file) => ({ file, name: file.name, description: '' }));
     useEffect(() => {
-        if (attaching !== 'failed')
+        // A failure the host explained stays until the author acts; a bare one is said for a moment.
+        if (attaching.state !== 'failed' || attaching.message !== null)
             return;
-        const timer = setTimeout(() => setAttaching('idle'), ATTACH_FAILED_MS);
+        const timer = setTimeout(() => setAttaching(NOT_ATTACHING), ATTACH_FAILED_MS);
         return () => clearTimeout(timer);
     }, [attaching]);
     // The note as edit mode opened it, as the editor holds its text: lines joined by `\n`.
@@ -453,9 +503,18 @@ export function NoteEditor({ markdown: given, onChange, editable = true, corner,
             clearTimeout(timer);
         };
     }, [leaving, saves.state]);
-    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: `markdown markdown-theme-${resolved.theme.name} markdown-editing`, "data-theme": resolved.scheme, style: rootStyle(resolved.theme, resolved.scheme), children: [_jsx("div", { ref: bar, className: "edit-bar", "data-leaving": folding ? '' : undefined, children: _jsx(Toolbar, { view: view, host: resolved, opened: opened.current, onAttach: () => setAttachOpen(true), attaching: attaching, attachButton: attachButton, end: _jsxs("div", { className: "edit-corner", "aria-busy": leaving && saves.state === 'saving' ? true : undefined, "data-blocked": blocked ? '' : undefined, children: [_jsx(SaveStatus, { state: saves.state, blocked: blocked, retry: saves.retry, host: resolved }), corner ?? _jsx(NoteActions, { text: () => (view ? output(view.state) : given) })] }, blocked ? `blocked-${refusals}` : 'corner') }) }), menu && view && (_jsx(ContextMenu, { x: menu.x, y: menu.y, label: resolved.strings.editor.menu, groups: menuGroups(view), onClose: (back) => {
+    return (_jsx(HostProvider, { value: resolved, children: _jsxs("div", { className: `markdown markdown-theme-${resolved.theme.name} markdown-editing`, "data-theme": resolved.scheme, style: rootStyle(resolved.theme, resolved.scheme), children: [_jsx("div", { ref: bar, className: "edit-bar", "data-leaving": folding ? '' : undefined, children: _jsx(Toolbar, { view: view, host: resolved, opened: opened.current, onAttach: () => {
+                            // Opening the paperclip is the author acting on a refusal: the dialog says it once more.
+                            if (attaching.state === 'failed') {
+                                setRefusal(attaching.message);
+                                setAttaching(NOT_ATTACHING);
+                            }
+                            else
+                                setRefusal(null);
+                            setAttachOpen(true);
+                        }, attaching: attaching, attachButton: attachButton, end: _jsxs("div", { className: "edit-corner", "aria-busy": leaving && saves.state === 'saving' ? true : undefined, "data-blocked": blocked ? '' : undefined, children: [_jsx(SaveStatus, { saves: saves, blocked: blocked, host: resolved, onDecided: () => view?.focus() }), corner ?? _jsx(NoteActions, { text: () => (view ? output(view.state) : given) })] }, blocked ? `blocked-${refusals}` : 'corner') }) }), menu && view && (_jsx(ContextMenu, { x: menu.x, y: menu.y, label: resolved.strings.editor.menu, groups: menuGroups(view), onClose: (back) => {
                         setMenu(null);
                         if (back)
                             view.focus();
-                    } })), attachOpen && (_jsx(AttachDialog, { onClose: () => setAttachOpen(false), onClosed: (inserted) => !inserted && attachButton.current?.focus(), onAttach: (files) => attachFiles.current(files), onEmbed: (name) => insertLine(`![[${name}]]`), onLink: (name, address) => insertLine(webImage(name, address)) })), lineBreak === null && _jsx("p", { className: "edit-unavailable", children: resolved.strings.editUnavailable }), _jsx("div", { ref: parent, className: "markdown-editor" })] }) }));
+                    } })), attachOpen && (_jsx(AttachDialog, { refusal: refusal, onClose: () => setAttachOpen(false), onClosed: (inserted) => !inserted && attachButton.current?.focus(), onAttach: (files) => attachFiles.current(files), onEmbed: (name) => insertLine(`![[${name}]]`), onLink: (name, address) => insertLine(webImage(name, address)) })), lineBreak === null && _jsx("p", { className: "edit-unavailable", children: resolved.strings.editUnavailable }), _jsx("div", { ref: parent, className: "markdown-editor" })] }) }));
 }

package/dist/edit/SaveNoticeDialog.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What the host said of a save, and the author's choices (#86): a modal dialog with the host's
+ * title, its explanation and one button per action. It never closes by itself, since its job is to
+ * have the author decide; Escape or its × close it and leave the save where it stood, and running
+ * an action closes it before the action runs.
+ */
+import type { SaveAction, SaveNotice } from './saves.js';
+export declare function SaveNoticeDialog({ notice, onClose, onClosed, onAction, }: {
+    notice: SaveNotice;
+    /** Escape or the ×: the author did not choose. */
+    onClose: () => void;
+    /** Once the dialog is closed, whether an action was chosen, so the focus goes where it belongs. */
+    onClosed: (chosen: boolean) => void;
+    onAction: (action: SaveAction) => void;
+}): import("react").JSX.Element;

package/dist/edit/SaveNoticeDialog.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * What the host said of a save, and the author's choices (#86): a modal dialog with the host's
+ * title, its explanation and one button per action. It never closes by itself, since its job is to
+ * have the author decide; Escape or its × close it and leave the save where it stood, and running
+ * an action closes it before the action runs.
+ */
+import { useEffect, useId, useRef } from 'react';
+import { useHost } from '../host.js';
+import { ICON_CLOSE } from '../mode-icons.js';
+export function SaveNoticeDialog({ notice, onClose, onClosed, onAction, }) {
+    const host = useHost();
+    const dialog = useRef(null);
+    const chosen = useRef(false);
+    const closed = useRef(onClosed);
+    closed.current = onClosed;
+    const id = useId();
+    useEffect(() => {
+        const element = dialog.current;
+        if (!element)
+            return;
+        if (typeof element.showModal === 'function')
+            element.showModal();
+        else
+            element.setAttribute('open', '');
+        element.querySelector('.edit-notice-action')?.focus();
+        return () => {
+            if (element.open && typeof element.close === 'function')
+                element.close();
+            // Only once the dialog is closed may the page behind it take the focus.
+            closed.current(chosen.current);
+        };
+    }, []);
+    return (_jsx("dialog", { ref: dialog, className: "edit-source edit-notice", "aria-modal": "true", "aria-labelledby": `${id}-title`, "aria-describedby": `${id}-message`, onCancel: (event) => {
+            event.preventDefault();
+            onClose();
+        }, children: _jsxs("div", { className: "edit-source-frame", children: [_jsxs("header", { className: "edit-source-header", children: [_jsx("h2", { id: `${id}-title`, className: "edit-source-title", children: notice.title }), _jsx("button", { type: "button", className: "edit-control edit-source-close", "aria-label": host.strings.close, title: host.strings.close, onClick: onClose, children: ICON_CLOSE })] }), _jsx("p", { id: `${id}-message`, className: "edit-notice-message", children: notice.message }), _jsx("div", { className: "edit-notice-actions", children: notice.actions.map((action, index) => (_jsx("button", { type: "button", className: "edit-attach-button edit-notice-action", onClick: () => {
+                            chosen.current = true;
+                            onAction(action);
+                        }, children: action.label }, index))) })] }) }));
+}

package/dist/edit/blocks.d.ts

@@ -91,6 +91,7 @@ export declare const ICONS: {
     readonly saving: ReactNode;
     readonly saved: ReactNode;
     readonly notSaved: ReactNode;
+    readonly alert: ReactNode;
     readonly edit: ReactNode;
     readonly view: ReactNode;
 };

package/dist/edit/blocks.js

@@ -475,6 +475,7 @@ export const ICONS = {
     saving: icon('M21 12a9 9 0 1 1-6.219-8.56'),
     saved: icon('M20 6 9 17l-5-5'),
     notSaved: icon('M12 2a10 10 0 1 0 0 20 10 10 0 1 0 0-20z', 'M12 8v4', 'M12 16h.01'),
+    alert: icon('m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3', 'M12 9v4', 'M12 17h.01'),
     edit: icon('M21.17 6.81a1 1 0 0 0-3.99-3.99L3.84 16.17a2 2 0 0 0-.5.83l-1.32 4.35a.5.5 0 0 0 .62.62l4.35-1.32a2 2 0 0 0 .83-.5z', 'm15 5 4 4'),
     view: icon('M2.06 12.35a1 1 0 0 1 0-.7 10.75 10.75 0 0 1 19.88 0 1 1 0 0 1 0 .7 10.75 10.75 0 0 1-19.88 0', 'M12 9a3 3 0 1 0 0 6 3 3 0 0 0 0-6z'),
 };

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/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 };
 }

package/dist/host.d.ts

@@ -71,8 +71,13 @@ export interface NoteHost {
      * has its own name and none), and answers the name it is kept under, which the editor embeds as
      * `![[name]]` (#75, #78). The package never stores a file. Without it, the editor offers no file
      * from the computer.
+     *
+     * While it keeps the file, the host may report each step through `progress`, which the paperclip
+     * shows and announces; a promise rejected with an `AttachRefusal` has the paperclip say why until
+     * the author acts (#88). A host that ignores `progress` and rejects with an error keeps the
+     * paperclip's own words.
      */
-    readonly attach?: (file: File, attributes: AttachAttributes) => string | PromiseLike<string>;
+    readonly attach?: (file: File, attributes: AttachAttributes, progress: (report: AttachProgress) => void) => string | PromiseLike<string>;
     /**
      * The files the notebook keeps, with their names, which the attach dialog lists for the author to
      * embed one (#78). Without it, the dialog offers no file of the notebook.
@@ -155,6 +160,23 @@ export interface KeptFile {
 export interface KeptFileEntry extends KeptFile {
     readonly name: string;
 }
+/** A step of keeping a file, as the host words it (#88). */
+export interface AttachProgress {
+    /** What is happening, in the reader's language: "Sending part 12 of 40". */
+    readonly message: string;
+    /** How much is done, from 0 to 1, when the host knows it: drawn as a determinate indicator. */
+    readonly fraction?: number;
+}
+/**
+ * Why the host would not keep a file, what `attach` rejects with (#88): a plain object, so that an
+ * `Error`, whose message is meant for a developer, keeps the paperclip's own words.
+ */
+export interface AttachRefusal {
+    /** Why, in the reader's language: "An attached file goes up to 100 MB". */
+    readonly message: string;
+}
+/** Whether a rejection is a refusal the host worded for the author, and not an error. */
+export declare function isAttachRefusal(value: unknown): value is AttachRefusal;
 /** What the author said of a file they attach (#78). */
 export interface AttachAttributes {
     /** The name to keep it under; the host may answer another, when that one is taken. */
@@ -188,7 +210,7 @@ export interface ResolvedHost {
     readonly loadNote: ((name: string) => Promise<EmbeddedNote | null>) | null;
     readonly keeps: (name: string) => boolean;
     readonly suggest: ((query: string) => readonly string[] | PromiseLike<readonly string[]>) | null;
-    readonly attach: ((file: File, attributes: AttachAttributes) => string | PromiseLike<string>) | null;
+    readonly attach: ((file: File, attributes: AttachAttributes, progress: (report: AttachProgress) => void) => string | PromiseLike<string>) | null;
     readonly files: (() => readonly KeptFileEntry[] | PromiseLike<readonly KeptFileEntry[]>) | null;
     readonly fileOf: ((name: string) => KeptFile | null | PromiseLike<KeptFile | null>) | null;
     readonly renderAttachment: ((file: AttachmentRequest) => ReactNode) | null;

package/dist/host.js

@@ -2,6 +2,14 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from 'react';
 import { withDefaults } from './strings.js';
 import { DEFAULT_THEME, schemeOf } from './theme.js';
+/** Whether a rejection is a refusal the host worded for the author, and not an error. */
+export function isAttachRefusal(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !(value instanceof Error) &&
+        typeof value.message === 'string' &&
+        value.message.length > 0);
+}
 /**
  * Every member of the contract, by name. The `satisfies` is what makes it complete: a member added
  * to `NoteHost` and not listed here does not compile.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { NoteBody, type NoteBodyProps, type NoteMode } from './NoteBody.js';
-export type { AttachAttributes, AttachmentRequest, EmbeddedNote, KeptFile, KeptFileEntry, LinkChoiceNote, LinkChoices, LinkRequest, NoteHost } from './host.js';
+export type { SaveAction, SaveNotice, SaveOutcome, SaveRefusal } from './edit/saves.js';
+export { isAttachRefusal } from './host.js';
+export type { AttachAttributes, AttachmentRequest, AttachProgress, AttachRefusal, EmbeddedNote, KeptFile, KeptFileEntry, LinkChoiceNote, LinkChoices, LinkRequest, NoteHost } from './host.js';
 export { ENGLISH, type EditorWords, type NoteStrings, type NoteStringsInput } from './strings.js';
 export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, type BlockquoteSlotProps, type CalloutSlotProps, type CodeBlockSlotProps, type DiagramSlotProps, type EmbedSlotProps, type FootnotesSlotProps, type HeadingSlotProps, type InlineCodeSlotProps, type ModeSwitchSlotProps, type AttachmentSlotProps, type PropertiesSlotProps, type Scheme, type TableSlotProps, type TaskBoxSlotProps, type Theme, type ThemeComponents, type ThemeProperties, type WikilinkSlotProps, } from './theme.js';
 export { followable } from './address.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 // The entry point of @memorysmithapp/markdown-renderer.
 export { NoteBody } from './NoteBody.js';
+export { isAttachRefusal } from './host.js';
 export { ENGLISH } from './strings.js';
 export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, } from './theme.js';
 export { followable } from './address.js';

package/dist/strings.d.ts

@@ -107,6 +107,8 @@ export interface EditorWords {
     readonly attach: string;
     readonly attaching: string;
     readonly attachFailed: string;
+    /** Said after the host's step while more files wait their turn (#88). */
+    readonly attachQueued: (count: number) => string;
     /** A code block's language, chosen at its top right (#84). */
     readonly language: string;
     readonly plainText: string;

package/dist/strings.js

@@ -112,6 +112,7 @@ export const ENGLISH = {
         attach: 'Attach a file',
         attaching: 'Attaching…',
         attachFailed: 'The file was not attached',
+        attachQueued: (count) => (count === 1 ? '1 more file waiting' : `${count} more files waiting`),
         language: 'Language',
         plainText: 'Plain text',
         mermaidDiagram: 'Mermaid diagram',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memorysmithapp/markdown-renderer",
-  "version": "0.4.0",
+  "version": "0.5.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.4.0",
+    "@memorysmithapp/markdown-spec": "0.5.0",
     "@types/hast": "3.0.5",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",

package/structure.css

@@ -233,6 +233,17 @@
 /* The attach dialog (#78): its ways in as tabs, a panel that alone scrolls,
    and the files of the notebook as a list of buttons. */
 /* One height for every way in, so the dialog does not jump between them. */
+/* The paperclip and, under it, the bar of the host's fraction (#88). */
+.markdown .edit-attach-control {
+  position: relative;
+  display: inline-flex;
+}
+.markdown .edit-attach-progress {
+  position: absolute;
+  inset-inline: 0.2rem;
+  bottom: 0;
+  pointer-events: none;
+}
 .markdown .edit-attach .edit-source-frame {
   height: min(34rem, calc(100vh - 4rem));
 }
@@ -291,6 +302,19 @@
   display: flex;
   justify-content: flex-end;
 }
+/* What the host said of a save (#86): its title, its explanation, and its
+   choices in a row that wraps, as narrow as its words. */
+.markdown .edit-notice {
+  max-width: min(32rem, calc(100vw - 2rem));
+}
+.markdown .edit-notice-message {
+  margin: 0;
+}
+.markdown .edit-notice-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
 @media (max-width: 560px) {
   .markdown .edit-attach-file {
     grid-template-columns: 1fr auto;

package/theme-default.css

@@ -1298,6 +1298,9 @@
 .markdown .edit-save[data-save='failed'] {
   color: rgb(var(--ms-callout-stop));
 }
+.markdown .edit-save[data-save='alert'] {
+  color: rgb(var(--ms-callout-warn));
+}
 /* Asked to leave while the last save failed: the corner shakes once. */
 .markdown .edit-corner[data-blocked] {
   animation: markdown-corner-refuse 360ms ease-in-out;
@@ -1322,6 +1325,14 @@
 .markdown .edit-control[data-attach='failed'] {
   color: rgb(var(--ms-callout-stop));
 }
+.markdown .edit-attach-progress {
+  height: 2px;
+  border-radius: 1px;
+  background: linear-gradient(to right, var(--ms-accent) calc(var(--edit-attach-fraction, 0) * 100%), var(--ms-border) 0);
+}
+.markdown .edit-attach-refusal {
+  padding: 0.6rem 1rem 0;
+}
 @media (prefers-reduced-motion: reduce) {
   .markdown .edit-control[data-attach='busy'] > svg {
     animation: none;
@@ -1332,7 +1343,8 @@
     transform: rotate(360deg);
   }
 }
-.markdown .edit-save-retry {
+.markdown .edit-save-retry,
+.markdown .edit-save-notice {
   padding: 0;
   border: 0;
   border-radius: calc(var(--ms-radius) - 2px);
@@ -1340,10 +1352,12 @@
   color: inherit;
   cursor: pointer;
 }
-.markdown .edit-save-retry:hover {
+.markdown .edit-save-retry:hover,
+.markdown .edit-save-notice:hover {
   background: var(--ms-code-bg);
 }
-.markdown .edit-save-retry:focus-visible {
+.markdown .edit-save-retry:focus-visible,
+.markdown .edit-save-notice:focus-visible {
   outline: 2px solid var(--ms-accent);
   outline-offset: 2px;
 }
@@ -1637,6 +1651,19 @@
   font-size: 1rem;
   font-weight: 600;
 }
+/* What the host said of a save: the dialog's own size, whatever the toolbar it opens from. */
+.markdown .edit-notice {
+  font-family: var(--ms-font-sans);
+  font-size: 0.95rem;
+  line-height: 1.55;
+}
+.markdown .edit-notice-message {
+  padding: 1rem 1rem 0;
+}
+.markdown .edit-notice-actions {
+  gap: 0.5rem;
+  padding: 1rem;
+}
 .markdown .edit-source-copied {
   color: var(--ms-text-soft);
   font-size: 0.8rem;