@stenographers/markdown 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egildo Tagliareni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @stenographers/markdown
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write an edited document back into the Markdown it was read from, keeping the author's bytes. A *stenographer* is the writer of one kind of node with the old transcript in hand: it writes the node over its old slice in the author's style (the bullet character, the emphasis character, the indent, the fence), every node that still means what it meant keeps its bytes, and only typed text is escaped, for what its position could misread. It is not a serializer: `mdast-util-to-markdown` rewrites a document in its own style (measured on BelType's manual: 14.3 percent of the lines changed with the defaults), and a stenographer rewrites nothing it was not asked to.
+
+## Install
+
+```sh
+npm install @stenographers/markdown
+```
+
+## What it is made of
+
+Five entries (`exports`, no index):
+
+- `@stenographers/markdown/parse`: the plain parse, `parseMarkdown(text, markdown)`, `markdown` the venue's options in core's shape (`{ gfm: { autolinks, tables }, mark, supersub, figure, directives }`, `directives` the config's `directives:` bindings over core's built-ins, their `tag`, `className` and `defaultTitle`): mdast-util-from-markdown with BelType's four syntax extensions (frontmatter, math, directive, GFM's parts in the order BelType registers them) and nothing else, the only parse whose positions are exact.
+- `@stenographers/markdown/html`: what Markdown means in HTML, mdast-util-to-hast's translation written as markup and parsed by the browser (`hastOf`, `htmlOf`, `domOf`), and `means(node, mdast)`, the test that lets an unchanged node keep its bytes (a footnote reference's number, the document's count, is left out of it).
+- `@stenographers/markdown/write`: `writeNode(element, { text, column, defs, markdown })`, a node's new bytes over its old slice, for paragraph, heading, list (items inserted with their neighbour's marker, deleted with their gap, the list turned tight or loose, a task's box ticked), list item, figure, table (a cell rewritten alone, its padding kept where it fits; rows added from a neighbour's layout and deleted), blockquote (its `> ` prefixes taken off and put back), directive container (read as core renders it, its tag, class and title paragraph; its fences kept, its label, content and title written, the title inside its attribute's quotes, any other attribute changed, added or removed alone), fenced code and inline content (text, em, strong, del, code, link and reference link, break, image, footnote reference, text directive, and BelType's `==mark==`, `=k=mark==`, `~sub~` and `^sup^`); `writeFresh(element)` for a block with no old bytes; `escape`. A node is read as the HTML element it means, never by a type name. A stenographer that cannot write its node answers null and its parent writes it; the last step is the lane change, the node written as raw HTML. A paragraph's or a heading's bytes are read back before they are given.
+- `@stenographers/markdown/flow`: `writeFlow(blocks, old, file)`, a flow of blocks over its old bytes: the parent owns the gaps (the old gap before a block that follows the one it followed, a blank line otherwise; a deleted block's gap kept when it holds a definition or a comment; two lists that would read as one kept apart by an empty comment).
+- `@stenographers/markdown/writer`: Provenance's Markdown writer, by shape (`markdownWriter({ markdown })`: `claims`, `open` giving `locate`, `write`, `shifted`), with `outline` and `writeRun`. A path is a JSON Pointer over the heading outline addressing a section's own run (its heading line and the blocks after it, up to the next heading of any rank); the value is the run's blocks, each `[html, bytes at the base, unchanged, prior bytes, whether they stand]`; only `set`. Bytes are counted here and nowhere else.
+
+## What it does not do
+
+It holds no document, no file and no editor: what changed, and which old block a new one stands for, is the caller's (by node identity in an editor, by the bytes a block had in the writer). It imports no ProseMirror, no BelType and no Provenance: Provenance's writer is met by shape, as its spec asks. It needs a DOM (`document`, for `<template>` and element comparison): a page's, or in node one the caller installs. A table's columns and alignment do not change (the table changes lane) and a column is never re-padded; a directive binding's `render` hook is not run (its directive means the element core would give it without one), and a container's label is only its first paragraph after the title, told from the content by the content's count; a title holding markup changes lane; a parent's prefix is spaces only; a text run whose bytes are not its value (an escape, an entity) is written fresh once touched; a list's items pair with the old by meaning from both ends, so an item edited in the same change as an insertion beside it is written fresh, and an inserted item in an ordered list does not renumber the items below; a loose list turned tight keeps the blank lines inside its items, so it changes lane when they would keep it loose. The notations are read from values, as core reads them, so an escaped delimiter is a delimiter: typed text holding a pair of `^`, `~` or `==`, which no escape keeps text, makes its paragraph change lane.
+
+## Extracted from
+
+The studio, beltype-studio-experiment's `src/markdown/stenographers/` at commit `3a526b0` (branch `round/markdown-1`), as prosemirror-stores was: built and proved there against BelType's manual, the pages and Provenance, then moved when green. The plan is the studio's `notes/markdown-plan.md`, the record of its round `notes/markdown-results.md`. The studio keeps what is its own: the read into its schema, the file as a client of its authority, saving, the venue host and the Markdown pane.
+
+## Proved by
+
+`npm test`, under `node:test` with happy-dom as the DOM (a dev dependency only): 109 tests. Over BelType's manual (`fixtures/`, its nine files as they were on 2026-10-29, the manual's GFM options): every paragraph, heading, list and list item, written from its style alone, is its slice byte for byte, and every other top-level block keeps its bytes; a key typed at the end of every top-level paragraph and heading reads back as the edited node with only the typed bytes changed (after a colon, the colon escaped too). The writer: the outline's paths and their escapes and ordinals, `locate` in bytes over UTF-8, every run of a file written again from its own value equal to its bytes, one paragraph changed changing only it, a malformed value refused. The list (`test/list.test.js`): items inserted, deleted, ticked, a list turned tight and loose, each in exact bytes and read back, on small lists and on every tight list of the manual. The figure (`test/figure.test.js`): core's figure read, none in a tight list item, caption, alt, source and id each rewritten alone. The notations (`test/dialect.test.js`): core's elements and classes, positions through escapes, typing inside and beside them, what they cannot carry written as HTML. The containers (`test/table.test.js`, `test/quote.test.js`, `test/directive.test.js`): every table and directive of the manual with one cell or one paragraph changed writes only those bytes; directives read as core renders them, titles and attributes written alone; quotes on small cases, lazy lines and nesting; each with the element serialized without the line ends between its elements. `test/review.test.js`: the review's findings, one case each. `test/layers.test.js`: every import is a sibling or a package of the Markdown parse.

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@stenographers/markdown",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Write an edited document back into the Markdown it was read from, keeping the author's bytes: a stenographer per node writes over the node's old slice in the author's style, every node that still means what it meant keeps its bytes, and only typed text is escaped. With a Markdown writer for Provenance, by shape.",
+  "type": "module",
+  "exports": {
+    "./parse": "./src/parse.js",
+    "./html": "./src/html.js",
+    "./write": "./src/write.js",
+    "./flow": "./src/flow.js",
+    "./writer": "./src/writer.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "mdast-util-directive": "3.1.0",
+    "mdast-util-from-markdown": "2.0.2",
+    "mdast-util-frontmatter": "2.0.1",
+    "mdast-util-gfm-autolink-literal": "2.0.1",
+    "mdast-util-gfm-footnote": "2.1.0",
+    "mdast-util-gfm-strikethrough": "2.0.0",
+    "mdast-util-gfm-table": "2.0.0",
+    "mdast-util-gfm-task-list-item": "2.0.0",
+    "mdast-util-math": "3.0.0",
+    "mdast-util-to-hast": "13.2.1",
+    "micromark-extension-directive": "3.0.2",
+    "micromark-extension-frontmatter": "2.0.0",
+    "micromark-extension-gfm-autolink-literal": "2.1.0",
+    "micromark-extension-gfm-footnote": "2.1.0",
+    "micromark-extension-gfm-strikethrough": "2.1.0",
+    "micromark-extension-gfm-table": "2.1.1",
+    "micromark-extension-gfm-task-list-item": "2.1.0",
+    "micromark-extension-math": "3.1.0"
+  },
+  "devDependencies": {
+    "happy-dom": "20.14.6",
+    "@stenographers/stenography": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/egildo/stenographers.git",
+    "directory": "packages/markdown"
+  },
+  "author": "Egildo Tagliareni",
+  "license": "MIT",
+  "homepage": "https://codeberg.org/egildo/stenographers",
+  "bugs": "https://codeberg.org/egildo/stenographers/issues"
+}

package/src/dialect.js

@@ -0,0 +1,159 @@
+// BelType's notations on the plain parse (the studio's notes/markdown-round-3-orchestration.md, agent C): `==mark==` and `=k=mark==` (core's remark-flexible-markers 1.3.5), `~sub~` and `^sup^` (core's remark-supersub 1.0.0), found where core finds them, in text values, and positioned in the bytes through each text node's map from its value to its bytes; and their stenographers, which the inline stenographers of ./write.js ask first.
+import { inline, fresh, span, start, end } from './write.js';
+
+// core's letter table; a key letter gives `flexible-marker flexible-marker-<colour>`, no key `flexible-marker flexible-marker-default`.
+const COLOURS = { a: 'amber', b: 'blue', c: 'cyan', d: 'brown', e: 'espresso', f: 'fuchsia', g: 'green', h: 'hotpink', i: 'indigo', j: 'jade', k: 'kiwi', l: 'lime', m: 'magenta', n: 'navyblue', o: 'orange', p: 'purple', q: 'pink', r: 'red', s: 'silver', t: 'teal', u: 'umber', v: 'violet', w: 'white', x: 'gray', y: 'yellow', z: 'black' };
+const BASE = 'flexible-marker';
+const KEYS = Object.fromEntries(Object.entries(COLOURS).map(([k, v]) => [`${BASE}-${v}`, k]));
+// core's regexes: a mark in one text node; the opening and the closing of a mark across formatting.
+const MARK = /=([a-z]?)=(?![\s=])([\s\S]*?)(?<![\s=])==/g;
+const OPENING = /=([a-z]?)=(?![\s]|=+\s)/;
+const CLOSING = /(?<!\s|\s=|\s==|\s===|\s====)==/;
+
+// A text node's value against its bytes: where each character of the value stands in them (one past the last at the end), or null when they do not align. A byte the value does not hold is passed over: an escape's backslash (the character it escapes standing for itself), an entity's name (every character it decodes to standing at its `&`), a continuation line's prefix.
+function align(raw, value) {
+  const map = [];
+  let r = 0;
+  for (let v = 0; v < value.length; v++) {
+    for (;;) {
+      if (r >= raw.length) return null;
+      if (raw[r] === '\\' && raw[r + 1] === value[v] && /[!-/:-@[-`{-~]/.test(value[v])) { map.push(r); r += 2; break; }
+      if (raw[r] === value[v]) { map.push(r++); break; }
+      const e = raw[r] === '&' && /^&(?:#\d+|#x[\da-f]+|\w+);/i.exec(raw.slice(r));
+      if (e) {
+        const t = document.createElement('textarea');
+        t.innerHTML = e[0];
+        if (value.startsWith(t.value, v)) { for (let i = 0; i < t.value.length; i++) map.push(r); v += t.value.length - 1; r += e[0].length; break; }
+      }
+      r++;
+    }
+  }
+  map.push(r);
+  return map;
+}
+
+// Visits every parent's children in order; `f(parent, i)` answers whether it replaced child `i`, which is then looked at again.
+function walk(parent, f) {
+  for (let i = 0; i < parent.children.length; i++) {
+    if (f(parent, i)) { i--; continue; }
+    if (parent.children[i].children) walk(parent.children[i], f);
+  }
+}
+
+/**
+ * Finds the notations in a tree of the plain parse, in place: each becomes an mdast node of its own (`mark`, `subscript`, `superscript`) whose `data.hName` mdast-util-to-hast reads, positioned in `text`. Marks are found as core finds them, in one text node or from an opening in one text node to a closing in a later sibling (across emphasis, code, links); an empty mark (`====`) is left as text. They are found in values, as core finds them, so an escaped delimiter is a delimiter (`\^2\^` is a superscript in core too): what this package reads is what core renders, and typed text holding a pair of delimiters, which no escape can keep text, reads back as the notation and refuses (the paragraph changes lane). Like core, a text node with an odd number of carets (or tildes) holds no superscript (subscript).
+ * @param {object} tree the plain parse's mdast
+ * @param {string} text the text it was parsed from
+ * @param {import('./parse.js').Markdown} markdown `mark: false` and `supersub: false` switch them off
+ */
+export function dialect(tree, text, markdown) {
+  const lines = [0];
+  for (let i = text.indexOf('\n'); i >= 0; i = text.indexOf('\n', i + 1)) lines.push(i + 1);
+  const maps = new Map();
+  const mapOf = (t) => { if (!maps.has(t)) maps.set(t, t.type === 'text' && t.position ? align(text.slice(t.position.start.offset, t.position.end.offset), t.value) : null); return maps.get(t); };
+  const ok = (t) => mapOf(t) != null;
+  // The point `k` characters into a text node's value, in the text.
+  const point = (t, k) => {
+    const offset = t.position.start.offset + mapOf(t)[k];
+    let lo = 0, hi = lines.length - 1;
+    while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (lines[mid] <= offset) lo = mid; else hi = mid - 1; }
+    return { line: lo + 1, column: offset - lines[lo] + 1, offset };
+  };
+  // A new text node keeps a map of its own, the part of its parent's.
+  const piece = (t, a, b) => { if (a >= b) return null; const p = { type: 'text', value: t.value.slice(a, b), position: { start: point(t, a), end: point(t, b) } }; maps.set(p, mapOf(t).slice(a, b + 1).map((o) => o - mapOf(t)[a])); return p; };
+  const make = (type, hName, hProperties, t0, a, t1, b, children) => ({ type, data: { hName, hProperties }, children, position: { start: point(t0, a), end: point(t1, b) } });
+  const markOf = (key, ...at) => make('mark', 'mark', { className: [BASE, key ? `${BASE}-${COLOURS[key]}` : `${BASE}-default`] }, ...at);
+  const delim = (ch, type, name) => (parent, i) => {
+    const t = parent.children[i];
+    if (!ok(t)) return false;
+    const parts = t.value.split(ch);
+    if (parts.length < 3 || parts.length % 2 === 0 || parts.some((p, k) => k % 2 && !p)) return false;
+    let at = 0;
+    const out = parts.map((p, k) => {
+      if (k % 2 === 0) { at += p.length; return piece(t, at - p.length, at); }
+      at += p.length + 2;
+      return make(type, name, {}, t, at - p.length - 2, t, at, [piece(t, at - p.length - 1, at - 1)]);
+    });
+    parent.children.splice(i, 1, ...out.filter(Boolean));
+    return true;
+  };
+  if (markdown.mark !== false) {
+    walk(tree, (parent, i) => {
+      const t = parent.children[i];
+      if (!ok(t)) return false;
+      const ms = [...t.value.matchAll(MARK)];
+      if (!ms.length) return false;
+      let at = 0;
+      const out = [];
+      for (const m of ms) {
+        const open = m[0].length - m[2].length - 2, b = m.index + m[0].length;
+        out.push(piece(t, at, m.index), markOf(m[1], t, m.index, t, b, [piece(t, m.index + open, b - 2)]));
+        at = b;
+      }
+      out.push(piece(t, at, t.value.length));
+      parent.children.splice(i, 1, ...out.filter(Boolean));
+      return true;
+    });
+    walk(tree, (parent, i) => {
+      const t = parent.children[i];
+      if (!ok(t)) return false;
+      const o = OPENING.exec(t.value);
+      const j = o ? parent.children.findIndex((c, k) => k > i && c.type === 'text' && CLOSING.test(c.value)) : -1;
+      if (j < 0 || !ok(parent.children[j])) return false;
+      const c = parent.children[j], e = CLOSING.exec(c.value);
+      const kids = [piece(t, o.index + o[0].length, t.value.length), ...parent.children.slice(i + 1, j), piece(c, 0, e.index)].filter(Boolean);
+      if (!kids.length) return false;
+      parent.children.splice(i, j - i + 1, ...[piece(t, 0, o.index), markOf(o[1], t, o.index, c, e.index + 2, kids), piece(c, e.index + 2, c.value.length)].filter(Boolean));
+      return true;
+    });
+  }
+  if (markdown.supersub !== false) {
+    walk(tree, delim('^', 'superscript', 'sup'));
+    walk(tree, delim('~', 'subscript', 'sub'));
+  }
+}
+
+const KINDS = { mark: 'mark', sub: 'subscript', sup: 'superscript' };
+const texts = (n) => n.childNodes.length > 0 && [...n.childNodes].every((c) => c.nodeType === 3);
+// A mark element's key letter ('' for the default colour), or null when it is not exactly core's output (another class, any other attribute).
+function keyOf(n) {
+  const cls = (n.getAttribute('class') ?? '').split(/\s+/);
+  if (n.attributes.length !== 1 || cls.length !== 2 || cls[0] !== BASE) return null;
+  return cls[1] === `${BASE}-default` ? '' : (KEYS[cls[1]] ?? null);
+}
+const opening = (k) => (k ? `=${k}=` : '==');
+// What the notation cannot carry, so that its bytes would read back as something else: a mark with a space at an edge or `==` in it; a sub- or superscript holding an element, a space or either delimiter.
+const uncarried = (n) => (n.localName === 'mark' ? /^\s|\s$|==/.test(n.textContent) : !texts(n) || /[\s~^]/.test(n.textContent));
+
+/**
+ * An element over an old inline node, when it is a notation's: its bytes, or `undefined` when it is not this file's to write (./write.js's `pair` goes on). The delimiters keep their bytes and the content is written as an emphasis's is; a mark whose colour changed has its key rewritten, and a notation that is no longer exactly core's output, or holds what its notation cannot carry, is raw HTML (that element alone, the paragraph keeping its bytes).
+ * @param {Node} n the element (or text) as the HTML it means
+ * @param {object} o the old mdast node it is paired with
+ * @param {object} ctx the stenographers' context (./write.js)
+ * @returns {string | undefined}
+ */
+export function pairDialect(n, o, ctx) {
+  if (n.nodeType !== 1 || KINDS[n.localName] !== o.type || !o.children?.length) return undefined;
+  if (!n.childNodes.length || uncarried(n)) return n.outerHTML;
+  let open = span(ctx, start(o), start(o.children[0]));
+  if (n.localName === 'mark') {
+    const k = keyOf(n);
+    if (k == null) return n.outerHTML;
+    open = opening(k);
+  }
+  return open + inline([...n.childNodes], o.children, ctx) + span(ctx, end(o.children.at(-1)), end(o));
+}
+
+/**
+ * An inline element with no old bytes, when a notation writes it: its bytes, or `undefined` when it is not this file's (./write.js's `fresh` goes on). What the notation cannot carry is raw HTML: a mark with a class outside core's table, any other attribute, no content, or what the notation cannot carry.
+ * @param {Element} n
+ * @returns {string | undefined}
+ */
+export function freshDialect(n) {
+  if (!KINDS[n.localName]) return undefined;
+  const inner = [...n.childNodes].map(fresh).join('');
+  if (!n.childNodes.length || uncarried(n)) return n.outerHTML;
+  if (n.localName === 'mark') { const k = keyOf(n); return k == null ? n.outerHTML : `${opening(k)}${inner}==`; }
+  const ch = n.localName === 'sub' ? '~' : '^';
+  return ch + inner + ch;
+}

package/src/directive.js

@@ -0,0 +1,180 @@
+// The directive: core's rule (BelType's packages/core/src/plugins/directives.js) and the container's stenographer, which ./write.js's `block` asks for the element a container directive means. `directives` marks each container and leaf directive of a tree of the plain parse, in place, with the element core gives it (`data.hName`, `data.hProperties`): a built-in's or a binding's tag and class, any other name a `div` (a leaf a `span`) of class `directive directive-name`, the author's attributes over the class (an author's `.class` replaces it, as core's spread does). A binding's container takes its `title` attribute, or the binding's default title, as a first paragraph of class `directive-title` (`data.directiveTitle`, which ./html.js's `hastOf` draws), the attribute not written on the element. Its children and their positions are left as they are.
+//
+// The container's write: `:::name[label]{attributes}` … `:::` over its old bytes. Its first `p` after the title is the label when the directive has one (to-hast renders it as a paragraph flagged `directiveLabel`). The opening line and the closing fence keep their bytes; a label that changed is written inside its brackets; a title that changed is written inside its attribute's quotes, an attribute added or removed alone; the content is a flow (./flow.js) over the old blocks, paired with the new by meaning from both ends inward and in order in the middle when the counts match. A nested directive is one of those blocks, so writeNode routes it back here. The result is read back and refuses unless it means the element; an unclosed directive refuses.
+import { isBlock, span, start, end, inline } from './write.js';
+import { parseMarkdown } from './parse.js';
+import { domOf, means, bare } from './html.js';
+import { writeFlow } from './flow.js';
+
+/** Core's built-ins, as its directives plugin has them. */
+export const BUILT_IN = {
+  tip: { tag: 'div', className: 'alert alert-tip', defaultTitle: 'Tip' },
+  warning: { tag: 'div', className: 'alert alert-warning', defaultTitle: 'Warning' },
+  danger: { tag: 'div', className: 'alert alert-danger', defaultTitle: 'Danger' },
+  info: { tag: 'div', className: 'alert alert-info', defaultTitle: 'Info' },
+  aside: { tag: 'aside', className: 'sidebar' }
+};
+
+/**
+ * Marks each container and leaf directive of a tree, in place, with the element core gives it.
+ * @param {object} tree the plain parse's mdast
+ * @param {Record<string, { tag?: string, className?: string, defaultTitle?: string }>} [bound] the venue's `directives:` bindings, over the built-ins (a binding's `render` hook is not run here)
+ */
+export function directives(tree, bound = {}) {
+  const table = { ...BUILT_IN, ...bound };
+  (function walk(node) {
+    if (node.type === 'containerDirective' || node.type === 'leafDirective') {
+      const b = Object.hasOwn(table, node.name) ? table[node.name] : null;
+      const attributes = { ...node.attributes };
+      const own = { className: b ? b.className : `directive directive-${node.name}` };
+      if (b && node.type === 'containerDirective') {
+        const title = attributes.title || b.defaultTitle;
+        delete attributes.title;
+        if (title) own.title = title;
+        own.defaultTitle = b.defaultTitle;
+      }
+      node.data = { ...node.data, hName: b ? b.tag || 'div' : node.type === 'leafDirective' ? 'span' : 'div', hProperties: { ...node.data?.hProperties, class: own.className, ...attributes }, directive: own };
+      if (own.title) node.data.directiveTitle = own.title;
+    }
+    node.children?.forEach(walk);
+  })(tree);
+}
+
+// The attributes' tokens on the opening line: `#id`, `.class`, `key`, `key=value` quoted or not, each with its span.
+const TOKEN = /\s*(?:#([^\s#.{}"'=]+)|\.([^\s#.{}"'=]+)|([^\s#.{}"'=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`{}]+)))?)/y;
+function tokens(s, from) {
+  const out = [];
+  let to = from;
+  TOKEN.lastIndex = from;
+  for (let m; (m = TOKEN.exec(s)) && m[0].trim(); to = TOKEN.lastIndex) out.push({ key: m[1] != null ? 'id' : m[2] != null ? 'class' : m[3], short: m[1] != null || m[2] != null, quote: m[4] != null ? '"' : m[5] != null ? "'" : '', from: m.index, to: TOKEN.lastIndex });
+  return { list: out, to };
+}
+// A value as an attribute: quoted as the old one was, unquoted only when it was and still can be, a new one in double quotes; a character reference for the quote and for an ampersand that would start one.
+function attr(key, value, quote) {
+  const q = quote || (/^[^\s"'=<>`{}]+$/.test(value) ? '' : '"');
+  const v = value.replace(/&(?=#?\w+;)/g, '&amp;');
+  return q ? `${key}=${q}${q === '"' ? v.replace(/"/g, '&quot;') : v.replace(/'/g, '&#39;')}${q}` : `${key}=${v}`;
+}
+
+/**
+ * The opening line with the author's attributes made `want`, each attribute that kept its value keeping its bytes; null when the line's attributes cannot be read.
+ * @param {string} head the opening line
+ * @param {number} after where the attributes may start (past the name and label)
+ * @param {Record<string, string>} had the attributes as read
+ * @param {Record<string, string>} want
+ */
+function reattribute(head, after, had, want) {
+  const keys = new Set([...Object.keys(had), ...Object.keys(want)]);
+  const changed = [...keys].filter((k) => had[k] !== want[k]);
+  if (!changed.length) return head;
+  const open = head.slice(after).match(/^\s*\{/);
+  const fresh = (k) => (k === 'id' && /^[^\s#.{}"'=]+$/.test(want.id) ? `#${want.id}` : k === 'class' && /^[^#.{}"'=]+$/.test(want.class) ? want.class.trim().split(/\s+/).map((c) => `.${c}`).join(' ') : attr(k, want[k], '"'));
+  if (!open) {
+    if (!/^\s*$/.test(head.slice(after))) return null;
+    const added = changed.filter((k) => want[k] != null);
+    return `${head.slice(0, after)}{${added.map(fresh).join(' ')}}${head.slice(after)}`;
+  }
+  const { list, to } = tokens(head, after + open[0].length);
+  if (!/^\s*\}/.test(head.slice(to))) return null;
+  const close = to + head.slice(to).indexOf('}');
+  let out = '', at = after + open[0].length;
+  const done = new Set();
+  for (const t of list) {
+    out += head.slice(at, t.from);
+    at = t.to;
+    const k = t.key;
+    if (!changed.includes(k)) { out += head.slice(t.from, t.to); continue; }
+    // A changed attribute: its first token rewritten, quoted as it was (a class's tokens are one attribute, so the rest go), a removed one dropped with the space before it.
+    if (done.has(k) || want[k] == null) continue;
+    done.add(k);
+    const lead = head.slice(t.from, t.to).match(/^\s*/)[0];
+    out += lead + (t.short || k === 'class' || k === 'id' ? fresh(k) : attr(k, want[k], t.quote));
+  }
+  const added = changed.filter((k) => want[k] != null && !done.has(k) && !list.some((t) => t.key === k));
+  const tail = head.slice(at, close);
+  out += (added.length ? `${tail.replace(/\s+$/, '')}${list.length ? ' ' : ''}${added.map(fresh).join(' ')}${tail.match(/\s*$/)[0]}` : tail);
+  // Every attribute gone, the braces go.
+  return out.trim() ? `${head.slice(0, after + open[0].length)}${out}${head.slice(close)}` : `${head.slice(0, after)}${head.slice(close + 1)}`;
+}
+
+/**
+ * A directive container's bytes over its old slice, or null (the lane change).
+ * @param {Element} el the directive as the HTML it means
+ * @param {object} md the containerDirective's mdast
+ * @param {object} ctx the stenographers' context (./write.js)
+ * @returns {string | null}
+ */
+export function directive(el, md, ctx) {
+  const text = ctx.src, a = start(md), b = end(md);
+  const own = md.data?.directive ?? {};
+  if (el.localName !== (md.data?.hName ?? 'div')) return null;
+  // The closing fence is the last line of the slice (never the opening line); without one the directive runs to the end of its parent.
+  const lastNl = text.lastIndexOf('\n', b - 1);
+  if (lastNl < a || !/^ {0,3}:{3,}[ \t]*$/.test(text.slice(lastNl + 1, b))) return null;
+  const label = md.children[0]?.data?.directiveLabel ? md.children[0] : null;
+  const old = md.children.slice(label ? 1 : 0);
+  const nodes = [...el.childNodes];
+  if (nodes.some((n) => (n.nodeType === 3 ? /\S/.test(n.data) : !isBlock(n)))) return null;
+  const news = nodes.filter((n) => n.nodeType === 1);
+  // The title: a binding's first paragraph, plain text, the attribute's value; gone, the attribute goes.
+  const titleEl = 'defaultTitle' in own && news[0]?.localName === 'p' && news[0].getAttribute('class') === 'directive-title' ? news.shift() : null;
+  if (titleEl && [...titleEl.childNodes].some((n) => n.nodeType !== 3)) return null;
+  if (label && news[0]?.localName !== 'p') return null;
+  // A label is only the first `p` of the content, so a label deleted would make the first paragraph of the content the label: when the blocks are the old content's in number and the first is the old first, the label is what went.
+  const dropped = label && old.length && news.length === old.length && means(news[0], old[0]);
+  const labelEl = label && !dropped ? news.shift() : null;
+
+  // The opening line: up to the first line end after the label (the attributes follow the label on the same line).
+  const open = text.indexOf('\n', label ? end(label) : a);
+  if (open < 0 || open > lastNl) return null;
+  let head = text.slice(a, open);
+  const name = /^ {0,3}:{3,}[^\s[{]*/.exec(head)[0].length;
+  // The author's attributes: the element's, its class the author's only when it is not the one core gives, the title the paragraph's.
+  const had = { ...md.attributes };
+  const want = Object.fromEntries([...el.attributes].map((x) => [x.name, x.value]));
+  if (want.class === (had.class ?? own.className)) want.class = had.class;
+  if (want.class == null || want.class === own.className) delete want.class;
+  for (const k of Object.keys(want)) if (want[k] == null) delete want[k];
+  if ('defaultTitle' in own) {
+    const t = titleEl?.textContent;
+    if (t === own.title) { if (had.title != null) want.title = had.title; }
+    else if (t != null && t !== '') want.title = t;
+  }
+  for (const k of Object.keys(had)) if (had[k] == null) delete had[k];
+  const after = label ? end(label) - a : name;
+  if (dropped) head = head.slice(0, start(label) - a) + head.slice(end(label) - a);
+  else if (label && !means(labelEl, label)) {
+    const kids = label.children;
+    if (!kids.length) return null;
+    head = head.slice(0, start(label) - a) + span(ctx, start(label), start(kids[0])) + inline([...labelEl.childNodes], kids, ctx) + span(ctx, end(kids.at(-1)), end(label)) + head.slice(end(label) - a);
+  }
+  head = reattribute(head, after + head.length - (open - a), had, want);
+  if (head == null) return null;
+
+  const same = (i, j) => !ctx.force && means(news[i], old[j]);
+  const n = news.length, m = old.length;
+  let h = 0;
+  while (h < n && h < m && same(h, h)) h++;
+  let t = 0;
+  while (t < n - h && t < m - h && same(n - 1 - t, m - 1 - t)) t++;
+  const blocks = news.map((e, i) => {
+    const edge = i < h || i >= n - t;
+    return { el: e, j: edge ? (i < h ? i : m - n + i) : n === m ? i : -1, same: edge };
+  });
+  const file = { defs: ctx.defs, markdown: ctx.markdown };
+  // No new blocks: nothing between the fences. Old blocks: the flow over the lines between them. None old: the flow alone.
+  let body = '';
+  if (n) body = (m ? writeFlow(blocks, { text, spans: old.map((k) => [start(k), end(k)]), from: open + 1, to: lastNl + 1 }, file) : writeFlow(blocks, { text: '', spans: [] }, file)).text;
+  const out = `${head}\n${body}${text.slice(lastNl + 1, b)}`;
+
+  // Read back as a whole; a title deleted reads back as the default one, which is what core shows.
+  const back = parseMarkdown(ctx.defs ? `${out}\n\n${ctx.defs}` : out, ctx.markdown).children[0];
+  const dom = back?.type === 'containerDirective' && end(back) === out.length && domOf(back).find((d) => d.nodeType === 1);
+  if (!dom) return null;
+  const mine = bare(el);
+  if (!titleEl?.textContent) {
+    if (titleEl) mine.firstElementChild.remove();
+    if (own.defaultTitle && dom.firstElementChild?.getAttribute('class') === 'directive-title') dom.firstElementChild.remove();
+  }
+  return bare(dom).isEqualNode(mine) ? out : null;
+}

package/src/figure.js

@@ -0,0 +1,98 @@
+// The figure: core's rule (BelType's packages/core/src/plugins/figure.js), a paragraph whose only meaningful child is an image with a title is a `figure` holding the image (its title taken off) and a `figcaption` of the title, the title's trailing `{#id}` the figure's id and not part of the caption; and the figure's stenographer, which ./write.js's `block` asks for a `figure` over a paragraph. `figures` marks the paragraph for mdast-util-to-hast and leaves its children and positions as they are, so the figure is written over the paragraph's own bytes: the caption is the text inside the title's quotes, the alt the text inside the brackets, the source the destination, and each is rewritten alone, the rest kept.
+import { toHast } from 'mdast-util-to-hast';
+import { checked, span, start, end, sliceOf } from './write.js';
+import { domOf } from './html.js';
+
+const LABEL = /\s*\{#([^}]+)\}\s*$/;
+
+/**
+ * Marks each figure of a tree of the plain parse, in place, for mdast-util-to-hast (`data.hName`, `data.hProperties`, `data.hChildren` on the paragraph), leaving its children and their positions as they are.
+ * @param {object} tree the plain parse's mdast
+ */
+export function figures(tree) {
+  // A reference image takes its url and title from the definition, as to-hast gives them (the first definition of an identifier wins).
+  const defs = new Map();
+  (function find(node) {
+    if (node.type === 'definition' && !defs.has(node.identifier)) defs.set(node.identifier, node);
+    node.children?.forEach(find);
+  })(tree);
+  // A tight list's items hold their paragraphs unwrapped (mdast-util-to-hast's rule, the list's looseness), so core, which promotes a `p`, finds none there.
+  const loose = (list) => list.spread || list.children.some((i) => (i.spread == null ? i.children.length > 1 : i.spread));
+  (function walk(node, tight) {
+    if (node.type === 'paragraph' && !tight) {
+      const kids = node.children.filter((c) => !(c.type === 'text' && !c.value.trim()));
+      const k = kids.length === 1 ? kids[0] : null;
+      const def = k?.type === 'imageReference' ? defs.get(k.identifier) : null;
+      const img = k?.type === 'image' ? k : def ? { type: 'image', url: def.url, alt: k.alt, title: def.title } : null;
+      if (img?.title) {
+        const m = LABEL.exec(img.title);
+        const caption = m ? img.title.slice(0, m.index).trim() : img.title;
+        node.data = {
+          ...node.data,
+          hName: 'figure',
+          hProperties: m ? { id: m[1] } : {},
+          hChildren: [toHast({ ...img, title: null }), { type: 'element', tagName: 'figcaption', properties: {}, children: [{ type: 'text', value: caption }] }]
+        };
+      }
+    }
+    const items = node.type === 'list' && !loose(node);
+    node.children?.forEach((c) => walk(c, items ? 'item' : tight === 'item' && node.type === 'listItem'));
+  })(tree, false);
+}
+
+// Backslash and the characters that would close the title, as Markdown escapes them.
+const escTitle = (s, open) => s.replace(/\\/g, '\\\\').replace(open === '(' ? /[()]/g : new RegExp(open, 'g'), '\\$&').replace(/&(?=#?\w+;)/g, '\\&');
+const escAlt = (s) => s.replace(/[\\[\]]/g, '\\$&');
+// A source as the HTML has it (already percent-encoded but for whitespace).
+const dest = (s) => s.replace(/\s/g, encodeURIComponent).replace(/[()\\]/g, '\\$&');
+
+/**
+ * A figure's bytes over the paragraph it was read from, or null (the lane change).
+ * @param {Element} el the figure as the HTML it means
+ * @param {object} md the paragraph's mdast
+ * @param {object} ctx the stenographers' context (./write.js)
+ * @returns {string | null}
+ */
+export function figure(el, md, ctx) {
+  const img = md.children.find((c) => c.type === 'image');
+  const old = domOf(md)[0];
+  if (!img || old?.localName !== 'figure') return null;
+  // Exactly an img and a figcaption of plain text (spaces between allowed), the figure carrying nothing but an id.
+  const kids = [...el.childNodes].filter((n) => n.nodeType !== 3 || n.data.trim());
+  const [pic, cap] = kids;
+  if (kids.length !== 2 || pic.localName !== 'img' || cap.localName !== 'figcaption' || [...cap.childNodes].some((n) => n.nodeType !== 3)) return null;
+  if ([...el.attributes].some((a) => a.name !== 'id') || cap.attributes.length || [...pic.attributes].some((a) => a.name !== 'src' && a.name !== 'alt')) return null;
+  // Untrimmed, as the caption is read: a title with no `{#id}` keeps its edge spaces in the figcaption.
+  const caption = cap.textContent;
+  if (!caption.trim() || /\n\s*\n/.test(caption)) return null;
+  const raw = sliceOf(ctx, img);
+  // The image's parts in its bytes: the alt up to the `]` that closes it, then `(destination title)`.
+  if (raw.slice(0, 2) !== '![') return null;
+  let i = 2, depth = 0;
+  for (; i < raw.length; i++) {
+    if (raw[i] === '\\') i++;
+    else if (raw[i] === '[') depth++;
+    else if (raw[i] === ']' && !depth--) break;
+  }
+  // No inline title in the bytes (a reference image, whose title is a definition's) refuses here.
+  const m = /^\]\((\s*(?:<[^>\n]*>|\S*))(\s+(["'(]))([\s\S]*)([")'])(\s*)\)$/.exec(raw.slice(i));
+  if (!m) return null;
+  const [, to, gap, open, title, , tail] = m;
+  const alt = pic.getAttribute('alt') ?? '';
+  const src = pic.getAttribute('src') ?? '';
+  const oldImg = old.querySelector('img');
+  const label = LABEL.exec(img.title);
+  const oldCaption = label ? img.title.slice(0, label.index).trim() : img.title;
+  // The title's bytes: the caption's (kept when unchanged), then the label's, its spacing kept and only the id inside the braces rewritten.
+  const rawLabel = /\s*\{#[^}]*\}\s*$/.exec(title);
+  const id = el.getAttribute('id') ?? '';
+  const keptCaption = rawLabel ? title.slice(0, rawLabel.index) : title;
+  const suffix = !id ? '' : rawLabel ? rawLabel[0].replace(/\{#[^}]*\}/, () => `{#${id}}`) : ` {#${id}}`;
+  const titleBytes = (caption === oldCaption ? keptCaption : escTitle(caption, open)) + suffix;
+  const close = open === '(' ? ')' : open;
+  return checked(el, ctx, (c) => {
+    const altBytes = alt === (oldImg.getAttribute('alt') ?? '') ? raw.slice(2, i) : escAlt(alt);
+    const dst = src === oldImg.getAttribute('src') ? to : dest(src);
+    return `${span(c, start(md), start(img))}![${altBytes}](${dst}${gap}${titleBytes}${close}${tail})${span(c, end(img), end(md))}`;
+  });
+}

package/src/flow.js

@@ -0,0 +1,46 @@
+// A flow of blocks written over its old bytes (the studio's notes/markdown-plan.md, "Escalation": the parent owns the gaps). The caller says which old block each new one stands for, by identity (the file, the studio's src/markdown/file.js) or by meaning (Provenance's writer, ./writer.js); this writes them. A block that is its old one unchanged keeps its bytes, and so does one whose bytes the caller gives as they stand (what the Markdown pane typed); one that stands for an old block is written by its stenographer over that slice, or over the bytes the caller gives it, raw HTML if it refuses; one that stands for none is written fresh. The separator before a block is the old gap when it follows the block it followed, a blank line otherwise; an old block no new one stands for takes its bytes and the gap before it, unless that gap holds something of its own (a link definition, a comment), which stays. Two lists that were not neighbours and would read as one (the same kind, the same marker) are kept apart by an empty comment, as mdast-util-to-markdown does.
+import { writeFresh, writeNode } from './write.js';
+
+const marker = (bytes) => /^\s*(?:([-*+])|\d+([.)]))/.exec(bytes)?.slice(1).join('') ?? null;
+const merges = (a, aBytes, b, bBytes) => a.localName === b.localName && /^[uo]l$/.test(a.localName) && marker(aBytes) != null && marker(aBytes) === marker(bBytes);
+
+/**
+ * @param {{ el: Element, j: number, same: boolean, bytes?: string | null, over?: string | null }[]} blocks the new blocks in order: the HTML each means, the index of the old block it stands for (-1: none), whether it is that block unchanged; `bytes`, the block's bytes as they stand (written as they are); `over`, the bytes a changed block is written over (its old block's by default)
+ * @param {{ text: string, spans: [number, number][], from?: number, to?: number }} old the old text, its blocks' spans in it in order, and the stretch of it they lie in (all of it by default)
+ * @param {{ defs?: string, markdown?: import('./parse.js').Markdown }} [file] the file's definitions and Markdown options, for the stenographers' re-parse
+ * @returns {{ text: string, spans: [number, number][], report: { kept: number, written: number, fresh: number, deleted: number } }} the stretch's new bytes, and each new block's span in them
+ */
+export function writeFlow(blocks, old, file = {}) {
+  const { text, spans } = old;
+  const from = old.from ?? 0, to = old.to ?? text.length;
+  const report = { kept: 0, written: 0, fresh: 0, deleted: 0 };
+  const used = new Set(blocks.filter((b) => b.j >= 0).map((b) => b.j));
+  const slice = (k) => text.slice(...spans[k]);
+  // The bytes between old block k-1 and old block k; the lead holds what is before the first.
+  const gap = (k) => (k === 0 ? '' : text.slice(spans[k - 1][1], spans[k][0]));
+  // A held gap brings its own blank lines either side; where another gap follows it, its trailing ones give way, so a removed block leaves no blank line of its own behind.
+  const join = (h, g) => (h && /^\s/.test(g) ? h.trimEnd() + g : h + g);
+  const held = (a, b) => { let kept = ''; for (let k = a + 1; k < b; k++) if (!used.has(k) && /\S/.test(gap(k))) kept = join(kept, gap(k)); return kept; };
+  let out = text.slice(from, spans[0]?.[0] ?? to);
+  const next = [];
+  let prev = -1, last = '';
+  for (const [i, { el, j, same, bytes: given, over }] of blocks.entries()) {
+    let bytes;
+    if (given != null) { bytes = given; report.kept++; }
+    else if (same) { bytes = slice(j); report.kept++; }
+    else if (j < 0 && over == null) { bytes = writeFresh(el, file); report.fresh++; }
+    else { bytes = writeNode(el, { text: over ?? slice(j), column: 0, ...file }) ?? el.outerHTML; report.written++; }
+    const adjacent = i > 0 && j >= 0 && j === prev + 1 && blocks[i - 1].j === prev;
+    let sep = i === 0 ? (j >= 0 ? held(-1, j) : '') : j > prev ? join(held(prev, j), gap(j)) || '\n\n' : '\n\n';
+    if (i > 0 && !adjacent && !/\S/.test(sep) && merges(blocks[i - 1].el, last, el, bytes)) sep = '\n\n<!-- -->\n\n';
+    out += sep + bytes;
+    last = bytes;
+    next.push([out.length - bytes.length, out.length]);
+    if (j >= 0) prev = j;
+  }
+  out += join(held(prev, spans.length), spans.length ? text.slice(spans.at(-1)[1], to) : '');
+  // A stretch that had no blocks has no gap after them: the new ones are separated from what follows.
+  if (!spans.length && blocks.length) out += to < text.length ? '\n\n' : '\n';
+  report.deleted = spans.length - used.size;
+  return { text: out, spans: next, report };
+}