@mathzetta/inlinemath 0.1.0 → 0.2.0

package/src/markdown.d.ts

@@ -1,3 +1,3 @@
 // '@mathzetta/inlinemath/markdown' — Markdown with maths. See types.d.ts.
-export type { MarkdownOptions } from './types.js';
-export { markdownToHTML, renderMarkdownInto, extractMath, renderMarkdown } from './types.js';
+export type { MarkdownOptions, VariableDefinition } from './types.js';
+export { markdownToHTML, renderMarkdownInto, extractMath, renderMarkdown, createVariables, variables, Variables } from './types.js';

package/src/markdown.js

@@ -7,8 +7,15 @@
  * Maths: $…$ inline, $$…$$ (or a ```math fence) on its own, \(…\) and \[…\] too.
  * Each is read by MathZetta (LaTeX, plain text or code all work) and drawn by
  * Inline Math; {{…}} inside is worked out first (MathZetta's calculator, or the CAS:
- * { blocks: casBlocks() } from '@mathzetta/inlinemath/cas'). A definition such as $r = 3$ or
- * $g := 9.81$ is remembered for the {{…}} after it ({ define: false } turns that off).
+ * { blocks: casBlocks() } from '@mathzetta/inlinemath/cas'). A definition such as $r = 3$ is
+ * remembered, as a number, for the {{…}} after it ({ define: false } turns that off).
+ *
+ * Saved variables: $A := 2+2$ saves A (and draws A ≔ 2 + 2); $_A := 2+2$ saves it without drawing.
+ * After it, A in any maths is drawn as its expression and {{A}} is its value: $A = {{A}}$ draws
+ * 2 + 2 = 4. $A := [[2+2]]$ is a textbox that sets A, [[2+2 | x^2]] a dropdown, [[1..10]] a slider
+ * ([[0..1 step 0.1 = 0.5]]). renderMarkdownInto keeps every part of a page in one store
+ * (`variables`), so a variable saved in one part is used in the others, and changing an input
+ * redraws everything that uses it.
  *
  * A $ is maths only when it looks like it (Pandoc's rule): the opening $ is not
  * followed by a space, the closing $ is not after a space or before a digit, so
@@ -21,8 +28,14 @@
  * the maths is taken out first and put back into its output.
  */
 
-import { toHTML } from './html.js';
+import { toHTML, treeOf } from './html.js';
 import { calculate } from './calculator.js';
+import { nameOf, bare, substitute, unexpand, inputOf, EXPRESSIONS, variables as pageVariables } from './variables.js';
+import { toPostfix } from './mathzetta.js';
+import { numberTree, select, pathOf, nodeAt } from './select.js';
+import { openEditor, replaceAt } from './edit.js';
+
+export { createVariables, variables, Variables } from './variables.js';
 
 // ---- finding the maths --------------------------------------------------------------------
 
@@ -34,7 +47,7 @@ const PLACEHOLDER = new RegExp(`${OPEN}(\\d+)${CLOSE}`, 'g');
 /**
  * The maths in a Markdown text, and the text with each piece replaced by a
  * placeholder (private-use characters, which no Markdown renderer touches).
- * @returns {{ text: string, math: Array<{ source, display, raw }> }}
+ * @returns {{ text: string, math: Array<{ source, display, raw, start, end }> }} (start, end: where the raw text is)
  */
 export function extractMath(markdown, { delimiters = ['$$', '$', '\\[', '\\('] } = {}) {
   const math = [];
@@ -43,7 +56,7 @@ export function extractMath(markdown, { delimiters = ['$$', '$', '\\[', '\\('] }
   const s = String(markdown);
   const atLineStart = (k) => k === 0 || s[k - 1] === '\n';
   const keep = (source, display, raw) => {
-    math.push({ source, display, raw });
+    math.push({ source, display, raw, start: i, end: i + raw.length });
     return placeholder(math.length - 1);
   };
   while (i < s.length) {
@@ -132,30 +145,194 @@ function closingDollar(s, from) {
 
 const escape = (t) => String(t).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 
-/** A definition: r = 3, g := 9.81 (a single name on the left). */
-const DEFINITION = /^\s*([A-Za-zͰ-Ͽ](?:_\{?\w+\}?)?)\s*(?::=|=)\s*([^=<>≤≥]+)$/;
+/** A definition: r = 3, g = 9.81 (a single name on the left) — remembered as a number for {{…}}. */
+const DEFINITION = /^\s*([A-Za-z\u0370-\u03ff](?:_\{?\w+\}?)?)\s*=\s*([^=<>≤≥]+)$/;
 
-function drawMath(item, options, scope) {
-  const { source, display } = item;
-  try {
-    const html = toHTML(source, { ...options.math, display, blocks: options.blocks, scope });
-    if (options.define !== false) define(source, scope);
-    return display ? `<span class="mv-md-display">${html}</span>` : `<span class="mv-md-math">${html}</span>`;
-  } catch (error) {
-    return `<span class="mv-md-error" title="${escape(error.message)}"><code>${escape(item.raw)}</code></span>`;
-  }
+/**
+ * Maths that saves a variable: `A := 2+2` (drawn), `_A := 2+2` or `_A = 2+2` (not drawn),
+ * `A := [[…]]` (an input). Else null; `{ error }` for a `$_…$` that saves nothing.
+ */
+function savingOf(source) {
+    let s = source.trim();
+    const hidden = s.startsWith('_');
+    if (hidden) s = s.slice(1).trimStart();
+    let at = s.indexOf(':=');
+    let width = 2;
+    if (at < 0 && hidden) {
+        at = s.search(/(?<![<>!≤≥=])=(?!=)/);
+        width = 1;
+    }
+    const nothing = hidden ? { error: 'a hidden $_…$ saves a variable: $_A := 2+2$' } : null;
+    if (at <= 0) return nothing;
+    const lhs = s.slice(0, at).trim();
+    const rhs = s.slice(at + width).trim();
+    let name = null;
+    try {
+        name = /\{\{/.test(lhs) ? null : nameOf(treeOf(lhs));
+    } catch {
+        // not a name
+    }
+    if (name === null || !rhs) return nothing;
+    return { hidden, lhs, name, rhs, input: inputOf(rhs) };
 }
 
-/** $r = 3$: remember r (exactly, as the calculator's text) for later {{…}}. */
-function define(source, scope) {
-  const m = DEFINITION.exec(source);
-  if (!m || /\{\{/.test(m[2])) return;
-  try {
-    const r = calculate(m[2], scope);
-    if (typeof r.value === 'number' || typeof r.value === 'bigint') scope[m[1].replace(/[{}]/g, '')] = r.exact ? r.text : r.value;
-  } catch {
-    // not a number (x = y + 1): nothing to remember
-  }
+/** `A = …` drawn as `A ≔ …`: the first relation is the definition's. */
+function asDefinition(html) {
+    return html
+        .replace('<span class="mv-rel">=</span>', '<span class="mv-rel mv-rel-def">≔</span>')
+        .replace(/(aria-label="[^"]*?) equals /, '$1 is defined as ')
+        .replace('<mo>=</mo>', '<mo>≔</mo>');
+}
+
+/** The input a definition's [[…]] asks for, holding `text`. */
+function controlHTML(def, text) {
+    const { input, name } = def;
+    const attrs = `class="mv-md-input mv-md-${input.kind}" data-mv-var="${escape(name)}" aria-label="${escape(name)}"`;
+    if (input.kind === 'dropdown') {
+        const options = input.options.map((o) => `<option value="${escape(o)}"${o === text ? ' selected' : ''}>${escape(o)}</option>`);
+        return `<select ${attrs}>${options.join('')}</select>`;
+    }
+    if (input.kind === 'slider') {
+        return `<input type="range" ${attrs} min="${input.min}" max="${input.max}" step="${input.step}" value="${escape(text)}">`
+            + `<output class="mv-md-output" data-mv-out="${escape(name)}">${escape(text)}</output>`;
+    }
+    return `<input type="text" ${attrs} value="${escape(text)}" size="${Math.max(4, text.length + 1)}" spellcheck="false" autocomplete="off">`;
+}
+
+/**
+ * Every piece of maths drawn, in reading order: a variable is known to the maths after it, and
+ * the variables already in `store` (the other parts of the page) to all of it.
+ */
+function drawAll(markdown, options, store, owner) {
+    const { text, math } = extractMath(markdown, options);
+    const defs = store ? store.definitions(owner) : new Map();
+    const textOf = (def) => (store ? store.textOf(def) : def.text);
+    const numbers = { ...(options.scope ?? {}) };   // options.scope and $r = 3$
+    const scope = {};                                // what {{…}} sees: those and the saved variables' values
+    const mine = new Map();
+    const inputs = new Set();
+    const trees = [];   // each piece's drawn tree, for finding what a double-click landed on
+    // the saved variables' values, for {{…}}: worked out until nothing more can be (B := 2A before A := 3)
+    const refresh = () => {
+        for (const k of Object.keys(scope)) delete scope[k];
+        Object.assign(scope, numbers);
+        for (const name of defs.keys()) delete scope[name];   // x^2 has no value: {{A}} draws A, drawn as x^2
+        let pending = [...defs.values()];
+        while (pending.length) {
+            const left = pending.filter((def) => {
+                try {
+                    const r = calculate(textOf(def), scope);
+                    // a number, or a matrix (or list): {{M^2}} works it out
+                    if (typeof r.value === 'number' || typeof r.value === 'bigint' || Array.isArray(r.value)) {
+                        scope[def.name] = r.exact ? r.text : r.value;
+                        return false;
+                    }
+                } catch {
+                    // not (yet) a number
+                }
+                return true;
+            });
+            if (left.length === pending.length) break;
+            pending = left;
+        }
+        // and their expressions, for a CAS block: {{diff(f, x)}} differentiates what f stands for
+        const expressions = {};
+        const plain = lookupFor({});
+        for (const name of defs.keys()) {
+            const tree = plain(name);
+            if (!tree) continue;
+            try {
+                expressions[name] = toPostfix(substitute(tree, (n) => (n === name ? null : plain(n))).tree);
+            } catch {
+                // an expression that can't be written as postfix: the CAS sees the name
+            }
+        }
+        scope[EXPRESSIONS] = expressions;
+    };
+    const lookupFor = (drawOpts) => {
+        const trees = new Map();
+        return (name) => {
+            const def = defs.get(name);
+            if (!def) return null;
+            if (!trees.has(name)) {
+                let tree = null;
+                try {
+                    tree = treeOf(textOf(def), drawOpts);
+                } catch {
+                    // an input holding something that doesn't read: A is drawn as A
+                }
+                trees.set(name, tree);
+            }
+            return trees.get(name);
+        };
+    };
+
+    refresh();
+
+    const drawItem = (item, i) => {
+        const { source, display } = item;
+        const cls = display ? 'mv-md-display' : 'mv-md-math';
+        const wrap = (html, extra = '') => `<span class="${cls}${extra}" data-mv-md="${i}">${html}</span>`;
+        try {
+            const drawOpts = { ...options.math, display, blocks: options.blocks, scope };
+            const save = savingOf(source);
+            if (save && save.error) throw new Error(save.error);
+            if (save) {
+                const { name, input, hidden } = save;
+                const def = input
+                    ? { name, text: input.default, input, key: `input:${JSON.stringify(input)}` }
+                    : { name, text: save.rhs, input: null, key: `expr:${save.rhs}`, start: item.start, end: item.end };
+                let html = '';
+                if (input) {
+                    const control = controlHTML(def, textOf(def));
+                    html = hidden ? control : `${toHTML(save.lhs, drawOpts)}<span class="mv-md-assign" aria-hidden="true">≔</span>${control}`;
+                    inputs.add(i);
+                } else {
+                    const rhs = substitute(treeOf(save.rhs, drawOpts), lookupFor(drawOpts)).tree;
+                    if (!hidden) {
+                        const tree = numberTree({ type: 'op', op: '=', args: [bare(treeOf(save.lhs)), rhs.id === undefined ? rhs : bare(rhs)] });
+                        trees[i] = tree;
+                        html = asDefinition(toHTML(tree, drawOpts));
+                    }
+                }
+                defs.delete(name);
+                defs.set(name, def);
+                mine.set(name, def);
+                refresh();
+                if (hidden && !input) return '';
+                return wrap(html, input ? ' mv-md-input-def' : '');
+            }
+            const { tree, changed } = substitute(treeOf(source, drawOpts), lookupFor(drawOpts));
+            if (changed) numberTree(tree);
+            trees[i] = tree;
+            const html = toHTML(tree, drawOpts);
+            if (!changed && options.define !== false && define(source, numbers, defs)) refresh();
+            return wrap(html);
+        } catch (error) {
+            return `<span class="mv-md-error" data-mv-md="${i}" title="${escape(error.message)}"><code>${escape(item.raw)}</code></span>`;
+        }
+    };
+    const drawn = math.map(drawItem);
+    return { text, math, drawn, defs: mine, inputs, trees };
+}
+
+/** $r = 3$ (or $A = \\begin{pmatrix}…$): remember r (exactly, as the calculator's text) for later {{…}} — unless r is a saved variable. */
+function define(source, numbers, saved) {
+    const m = DEFINITION.exec(source);
+    if (!m || /\{\{/.test(m[2])) return false;
+    const name = m[1].replace(/[{}]/g, '');
+    if (saved.has(name)) return false;
+    try {
+        const r = calculate(m[2], numbers);
+        // a number, or a matrix (or list), as for saved variables
+        if (typeof r.value === 'number' || typeof r.value === 'bigint' || Array.isArray(r.value)) {
+            numbers[name] = r.exact ? r.text : r.value;
+            return true;
+        }
+    } catch {
+        // not a number (x = y + 1): nothing to remember
+    }
+    return false;
 }
 
 // ---- the Markdown renderer ----------------------------------------------------------------
@@ -329,6 +506,18 @@ export function renderMarkdown(markdown, options = {}, sourceOf = (t) => t) {
 
 // ---- together ---------------------------------------------------------------------------
 
+/** The Markdown around the drawn maths. */
+function assemble({ text, math, drawn }, options) {
+    const sourceOf = (t) => t.replace(PLACEHOLDER, (_, n) => math[Number(n)].raw);
+    const html = options.render ? options.render(text) : renderMarkdown(text, options, sourceOf);
+    return html
+        // display maths alone in a paragraph is a block of its own
+        .replace(new RegExp(`<p>\\s*${OPEN}(\\d+)${CLOSE}\\s*</p>`, 'g'), (whole, n) => (math[Number(n)].display && drawn[Number(n)] ? `<div class="mv-md-block">${drawn[Number(n)]}</div>` : whole))
+        .replace(PLACEHOLDER, (_, n) => drawn[Number(n)])
+        // a paragraph that only saved variables ($_A := 2+2$) leaves nothing behind
+        .replace(/<p>\s*<\/p>\n?/g, '');
+}
+
 /**
  * Markdown with maths → HTML.
  * @param {string} markdown
@@ -337,25 +526,151 @@ export function renderMarkdown(markdown, options = {}, sourceOf = (t) => t) {
  * @param {Function} [options.blocks] the {{…}} handler (default the calculator; casBlocks() for the CAS)
  * @param {object} [options.scope] values for {{…}}: { r: 3 }
  * @param {boolean} [options.define] remember $r = 3$ for later {{…}} (default true)
+ * @param {object} [options.variables] a store (createVariables()) whose variables the maths may use
  * @param {boolean} [options.html] let raw HTML through (default false: it is shown as text)
  * @param {(markdown: string) => string} [options.render] another Markdown renderer
  * @param {string[]} [options.delimiters] which of '$$', '$', '\\[', '\\(' mark maths (default all)
  */
 export function markdownToHTML(markdown, options = {}) {
-  const { text, math } = extractMath(markdown, options);
-  const scope = { ...(options.scope ?? {}) };
-  // drawn in reading order, so a definition is known to the maths after it
-  const drawn = math.map((item) => drawMath(item, options, scope));
-  const sourceOf = (t) => t.replace(PLACEHOLDER, (_, n) => math[Number(n)].raw);
-  const html = options.render ? options.render(text) : renderMarkdown(text, options, sourceOf);
-  return html
-    // display maths alone in a paragraph is a block of its own
-    .replace(new RegExp(`<p>\\s*${OPEN}(\\d+)${CLOSE}\\s*</p>`, 'g'), (whole, n) => (math[Number(n)].display ? `<div class="mv-md-block">${drawn[Number(n)]}</div>` : whole))
-    .replace(PLACEHOLDER, (_, n) => drawn[Number(n)]);
+    return assemble(drawAll(markdown, options, options.variables || null), options);
 }
 
-/** Draw Markdown with maths into an element. */
+const bindings = new WeakMap();
+const live = new Set();   // every bound element's binding, to notice the ones taken off the page
+
+/** Parts taken off the page take their variables with them. */
+function sweep() {
+    for (const b of live) if (b.connected() && !b.element.isConnected) b.stop(true);
+}
+
+/**
+ * Draw Markdown with maths into an element, live: its variables join the page's store
+ * (options.variables, default `variables`; false for none), its inputs set them, and its maths is
+ * drawn again whenever a variable it can see changes. Drawing into the element again replaces it all.
+ * Double-clicking a part drawn from a textbox variable edits it ({ editable: { toText } }, toText
+ * from 'mathzetta/text'); any other part fires 'inlinemath:select' with where its maths is in the
+ * Markdown ({ index, start, end, raw }).
+ */
 export function renderMarkdownInto(element, markdown, options = {}) {
-  element.innerHTML = markdownToHTML(markdown, options);
-  return element;
+    const store = options.variables === undefined ? pageVariables : options.variables || null;
+    sweep();
+    const old = bindings.get(element);
+    if (old) old.stop(old.store !== store);
+    let result = drawAll(markdown, options, store, element);
+    element.innerHTML = assemble(result, options);
+    if (!store) {
+        bindings.delete(element);
+        return element;
+    }
+    store.own(element, result.defs);
+
+    let connected = element.isConnected;
+    const redraw = () => {
+        const next = drawAll(markdown, options, store, element);
+        next.drawn.forEach((html, i) => {
+            if (html === result.drawn[i] || next.inputs.has(i)) return;
+            const at = element.querySelector(`[data-mv-md="${i}"]`);
+            if (at) at.outerHTML = html;
+        });
+        // inputs for the same variable agree; a slider shows its value
+        for (const el of element.querySelectorAll('[data-mv-var], [data-mv-out]')) {
+            const def = next.defs.get(el.dataset.mvVar ?? el.dataset.mvOut);
+            if (!def) continue;
+            const text = store.textOf(def);
+            if (el.dataset.mvOut !== undefined) el.textContent = text;
+            else if (el.value !== text && el !== el.ownerDocument?.activeElement) el.value = text;
+        }
+        result = next;
+    };
+    const onInput = (event) => {
+        const el = event.target;
+        const name = el && el.dataset && el.dataset.mvVar;
+        if (name === undefined || !element.contains(el)) return;
+        if (el.type === 'text') {
+            try {
+                treeOf(el.value, { blocks: options.blocks, scope: {} });
+                el.removeAttribute('aria-invalid');
+            } catch {
+                el.setAttribute('aria-invalid', 'true');   // keeps what it held last
+                return;
+            }
+        }
+        store.set(name, el.value);
+    };
+    // double-click a part: a part that came from a textbox variable is edited there (in place,
+    // with options.editable = { toText }; else the textbox is focused); anything else tells the
+    // page where that maths is in the Markdown, as an 'inlinemath:select' event
+    const onDoubleClick = (event) => {
+        const part = event.target.closest?.('[data-node]');
+        const piece = part && part.closest('[data-mv-md]');
+        if (!piece || !element.contains(piece)) return;
+        const index = Number(piece.dataset.mvMd);
+        const tree = result.trees[index];
+        if (!tree) return;
+        const id = Number(part.dataset.node);
+        const path = pathOf(tree, id) || [];
+        // the innermost variable the part sits in
+        let at = null;
+        for (let k = path.length; k >= 0 && !at; k--) {
+            const n = nodeAt(tree, path.slice(0, k));
+            if (n && n.from !== undefined) at = { node: n, depth: k };
+        }
+        const def = at && store.definitions().get(at.node.from);
+        if (def && def.input && def.input.kind === 'textbox') {
+            event.preventDefault();
+            const name = def.name;
+            const box = element.ownerDocument.querySelector(`[data-mv-var="${CSS.escape(name)}"]`);
+            const toText = options.editable && options.editable.toText;
+            if (!toText) {
+                if (box) { box.focus(); box.select(); }
+                return;
+            }
+            const named = (n) => treeOf(n);
+            const node = nodeAt(tree, path);
+            openEditor(part, toText(unexpand(node, named)), {
+                label: `Edit ${name}`,
+                parse: (text) => treeOf(text, { blocks: options.blocks }),
+                commit: (typed) => {
+                    const whole = replaceAt(unexpand(at.node, named), path.slice(at.depth), typed);
+                    store.set(name, toText(whole));
+                },
+            });
+            return;
+        }
+        // a saved variable defined here: point at its definition rather than where it is used
+        const here = def && result.defs.get(def.name);
+        const item = here && here.key === def.key && here.start !== undefined
+            ? { ...result.math[index], start: here.start, end: here.end, raw: markdown.slice(here.start, here.end) }
+            : result.math[index];
+        element.dispatchEvent(new CustomEvent('inlinemath:select', {
+            bubbles: true,
+            detail: { index, start: item.start, end: item.end, raw: item.raw, source: item.source, id, path },
+        }));
+    };
+    element.addEventListener('input', onInput);
+    element.addEventListener('change', onInput);
+    element.addEventListener('dblclick', onDoubleClick);
+    const unsubscribe = store.subscribe((from) => {
+        if (from === element) return;
+        if (!element.isConnected) {
+            if (connected) stop(true);   // taken off the page: its variables go with it
+            return;
+        }
+        connected = true;
+        sweep();
+        redraw();
+    });
+    function stop(drop) {
+        unsubscribe();
+        element.removeEventListener('input', onInput);
+        element.removeEventListener('change', onInput);
+        element.removeEventListener('dblclick', onDoubleClick);
+        live.delete(binding);
+        bindings.delete(element);
+        if (drop) store.own(element, null);
+    }
+    const binding = { element, store, stop, connected: () => connected };
+    live.add(binding);
+    bindings.set(element, binding);
+    return element;
 }

package/src/mathzetta.js

@@ -13,5 +13,6 @@ export {
     operator, precedenceOf, isCustomFunction, VARIADIC,
     GREEK, needsBrackets, unaryNeedsBrackets, isMinusOneTimes, isImplicitProduct, isVariable,
     firstLeaf, customName, derivativeOrder, bracketedSides, bracketOp,
+    MATRICES, matrixRows,
 } from 'mathzetta';
-export { toSpeech, toSpeechSegments } from 'mathzetta/speech';
+export { toSpeech, toSpeechSegments, toAudioSpeech } from 'mathzetta/speech';

package/src/types.d.ts

@@ -30,6 +30,9 @@ export interface LayoutOptions {
     cases?: boolean;
     /** The accessible name: true = the spoken form, a string, a function of the tree, or false for none. */
     label?: boolean | string | ((tree: Node) => string);
+    /** MathZetta's toMathML (from 'mathzetta/mathml'): also write the expression as visually hidden MathML, which
+     *  screen readers can step through and show in math braille; it takes the place of the label. Off by default. */
+    mathml?: ((input: Node) => string) | null;
     /** Extra attributes for a node's element. */
     attributes?: ((node: Node) => Record<string, string>) | null;
     /** Inline style for a node's element. */
@@ -47,6 +50,13 @@ export interface DrawOptions extends LayoutOptions {
     blocks?: BlockHandler;
 }
 
+/** Options for a live view: everything toHTML takes, plus how steps reach a screen reader. */
+export interface ViewOptions extends DrawOptions {
+    /** Read each new step (every set() after the first) to a screen reader: true places a polite live
+     *  region after the element; or pass your own live-region element. Off by default. */
+    announce?: boolean | Element;
+}
+
 export const DEFAULTS: Required<LayoutOptions>;
 
 /** Anything MathZetta reads, as HTML (a string; works in Node). Needs inlinemath.css on the page. */
@@ -71,11 +81,16 @@ export interface ClickInfo { node: Node; id: number; path: number[] | null; elem
 
 /** A live drawing: highlight, colour, listen, step with animation. */
 export class View {
-    constructor(element: Element, input: Input, options?: DrawOptions);
+    constructor(element: Element, input: Input, options?: ViewOptions);
     readonly element: Element;
     readonly tree: Node;
-    /** Show a new expression; with animate, matching parts glide over and new ones fade in. */
-    set(input: Input, options?: { animate?: boolean; duration?: number; easing?: string }): this;
+    /** Show a new expression; with animate, matching parts glide over and new ones fade in. `true` is instant
+     *  when the reader's system asks for reduced motion; `'always'` animates regardless. */
+    set(input: Input, options?: { animate?: boolean | 'always'; duration?: number; easing?: string }): this;
+    /** The expression as a listener hears it (its accessible name, else MathZetta's audio speech). */
+    spoken(): string;
+    /** Say something through the live region ({ announce } must be set); steps are announced this way. */
+    announce(text: string): this;
     nodes(target: Target): Node[];
     elements(target: Target): Element[];
     elementOf(node: Node): Element | null;
@@ -83,13 +98,30 @@ export class View {
     unhighlight(target?: Target | null, className?: string): this;
     color(target: Target, colour: string): this;
     /** Listen for an event on a part; returns a function that stops listening. */
+    /** Listen for an event on the parts. A 'click' listener also makes the drawing work from the keyboard:
+     *  one tab stop, arrow keys walk the parts (each spoken), Enter or Space calls the listener for the
+     *  current part — `event` is then the KeyboardEvent. */
     on(type: string, fn: (info: ClickInfo) => void): () => void;
+    /**
+     * Let the reader edit a part at a time: double-click it (or F2 on the keyboard's part) and a
+     * text box opens over it; Enter puts the new text in its place, Escape leaves it.
+     * toText is MathZetta's (import { toText } from 'mathzetta/text'; InlineMath.toText in the <script> build).
+     */
+    editable(how: { toText: (input: Input) => string; onEdit?: (change: { tree: Node; text: string; path: number[]; part: string }) => void }): this;
+    /** Open the editing box over a part (editable() first). */
+    edit(target?: unknown, options?: { returnFocus?: boolean }): HTMLInputElement | null;
+    /** The part the arrow keys are on (null: the whole expression). */
+    readonly active: Node | null;
+    /** Put the keyboard on a part (null: the whole expression) and say it. */
+    focusPart(node: Node | null): this;
     /** The expression read aloud in pieces, each tagged with the node it describes. */
     segments(options?: SpeechOptions): { text: string; id?: number }[];
     showSegment(segment: { id?: number } | null, className?: string): this;
 }
 /** Draw into an element and return the live view. */
-export function render(element: Element, input: Input, options?: DrawOptions): View;
+export function render(element: Element, input: Input, options?: ViewOptions): View;
+/** Should a step animate: true honours prefers-reduced-motion, 'always' does not, false never. */
+export function shouldAnimate(animate?: boolean | 'always'): boolean;
 
 // ---- inlinemath/markdown --------------------------------------------------------------------
 
@@ -108,10 +140,48 @@ export interface MarkdownOptions {
     render?: (markdown: string) => string;
     /** Which of '$$', '$', '\\[', '\\(' mark maths (default all). */
     delimiters?: string[];
+    /**
+     * The saved variables ($A := 2+2$) the maths may use. markdownToHTML: none by default;
+     * renderMarkdownInto: the page's `variables` by default, false for none.
+     */
+    variables?: Variables | false | null;
+    /**
+     * renderMarkdownInto: double-clicking a part drawn from a textbox variable edits it in place
+     * (toText from 'mathzetta/text'); without it the textbox is focused. Any other part fires
+     * 'inlinemath:select' (detail { index, start, end, raw, source, id, path }) on the element.
+     */
+    editable?: { toText: (input: Input) => string };
+}
+/** What a saved variable is: its expression, or the input that sets it. */
+export interface VariableDefinition {
+    name: string;
+    text: string;
+    input: null | { kind: 'textbox'; default: string } | { kind: 'dropdown'; options: string[]; default: string } | { kind: 'slider'; min: number; max: number; step: number; default: string };
+    key: string;
+}
+/** A page's saved variables: every part drawn with renderMarkdownInto sees the others'. */
+export class Variables {
+    /** A variable's expression now (what its input holds, for an input), or undefined. */
+    get(name: string): string | undefined;
+    /** Set a variable: what its input holds, or (with no input) a definition for the whole page. */
+    set(name: string, text: string | number): this;
+    /** Forget a variable set with set(), or everything. */
+    clear(name?: string): this;
+    /** The saved names. */
+    names(): string[];
+    /** Called whenever a variable changes; returns a function that stops it. */
+    subscribe(fn: (owner: unknown, name?: string) => void): () => void;
+    definitions(except?: unknown): Map<string, VariableDefinition>;
+    textOf(def: VariableDefinition): string;
+    own(owner: unknown, defs: Map<string, VariableDefinition> | null): void;
 }
+/** A store of its own, for parts of a page that shouldn't share variables. */
+export function createVariables(): Variables;
+/** The page's store, renderMarkdownInto's default. */
+export const variables: Variables;
 export function markdownToHTML(markdown: string, options?: MarkdownOptions): string;
 export function renderMarkdownInto<E extends Element>(element: E, markdown: string, options?: MarkdownOptions): E;
-export function extractMath(markdown: string, options?: { delimiters?: string[] }): { text: string; math: Array<{ source: string; display: boolean; raw: string }> };
+export function extractMath(markdown: string, options?: { delimiters?: string[] }): { text: string; math: Array<{ source: string; display: boolean; raw: string; start: number; end: number }> };
 export function renderMarkdown(markdown: string, options?: MarkdownOptions): string;
 
 // ---- inlinemath/cas (needs @mathzetta/cas) --------------------------------------------------------
@@ -122,7 +192,8 @@ export interface CASStep { id: string; name: string; from: string; to: string; p
 export type CAS = Record<string, any>;
 export function mathCAS(options?: { rules?: unknown[]; names?: string[]; complex?: boolean; [option: string]: unknown }): CAS;
 /** A `{{…}}` handler: toHTML(input, { blocks: casBlocks() }). `last` holds the latest CAS result. */
-export function casBlocks(options?: { cas?: CAS }): BlockHandler & { last?: unknown };
+/** steps: how much working each call keeps (true: every step, 'brief': the ones that carry the idea, false: none). */
+export function casBlocks(options?: { cas?: CAS; steps?: boolean | 'brief' | Record<string, unknown> }): BlockHandler & { last?: { steps?: CASStep[]; text?: string; [k: string]: unknown } };
 /** Steps as an ordered list, each rewrite highlighted, with its explanation. */
 export function stepsHTML(steps: CASStep[], options?: DrawOptions): string;
 /** A CAS node → MathZetta postfix tokens. */