@rse/ase 2.0.3 → 2.0.5

package/dst/ase-hook.js

@@ -462,7 +462,8 @@ export default class HookCommand {
             guaranteed to appear once in every non-headless session;
             Anthropic Claude Code CLI and OpenAI Codex CLI surface a top-level
             "systemMessage" field for this -- GitHub Copilot CLI has no equivalent);
-            the trailing help hint is emitted only if the guidance level asks for it  */
+            the trailing help hints are emitted only if the guidance level asks for them,
+            and the inline ones only for Anthropic Claude Code CLI, which alone runs the mods  */
         const banner = "\n" +
             `\n⧉ ASE: ⎈ version: ${version}${versionHint !== "" ? " " + versionHint.replace(/\*/g, "") : ""}` +
             `\n⧉ ASE: ※ user: ${userId}, ⚑ project: ${projectId}` +
@@ -470,8 +471,16 @@ export default class HookCommand {
             `\n⧉ ASE: ☯ persona: ${persona}, ▶ guidance: ${guidance}, ▢ boxing: ${boxing}` +
             (guidance === "normal" || guidance === "verbose" ?
                 "\n" +
-                    "\n⧉ ASE: ▷ hint: use \"/ase-help-intent <intent-description>\" for skill command proposals" +
-                    "\n⧉ ASE: ▷ hint: use \"/ase-help-skill [<skill-name>]\" for skill catalog or skill manpage" : "");
+                    "\n⧉ ASE: ▷ hint: use \"/ase-help-intent <intent>\" for conversational skill command proposals" +
+                    "\n⧉ ASE: ▷ hint: use \"/ase-help-skill [<skill>]\" for conversational skill catalog or manpage lookup" +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"<intent> !!\" for inline skill command proposals" : "") +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"/<skill> !!\" for inline skill command composition" : "") +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"/<skill> //\" for inline skill manpage lookup" : "") +
+                    (tool === "claude" ?
+                        "\n⧉ ASE: ▷ hint: use \"[<filter>] //\" for inline skill manpage browsing" : "") : "");
         /*  inject markdown into session context.
             Anthropic Claude Code CLI and OpenAI Codex CLI expect the context nested in
             "hookSpecificOutput"; GitHub Copilot CLI expects a flat top-level
@@ -601,7 +610,7 @@ export default class HookCommand {
     }
     /*  the edit-capable skills whose active state lets the pre-tool-use
         hook auto-approve subsequent "Edit" invocations  */
-    editCapableSkills = ["ase-code-lint", "ase-docs-shorten", "ase-docs-refine", "ase-docs-proofread"];
+    editCapableSkills = ["ase-code-lint", "ase-spec-lint", "ase-docs-shorten", "ase-docs-refine", "ase-docs-proofread"];
     /*  determine whether an ASE tool invocation described by the parsed
         hook input should be auto-approved, and (if so) the human-readable
         reason. The input field names and value shapes differ between

package/dst/ase-lib-version.js

@@ -13,18 +13,27 @@ export default class Version {
         return pkg.version;
     }
     /*  return latest ASE version known from the NPM registry
-        (cached background check, falling back to the current version)  */
-    static async latest() {
+        (cached background check or, if requested, immediate direct check,
+        both falling back to the current version)  */
+    static async latest(direct = false) {
         const notifier = updateNotifier({
             pkg,
             updateCheckInterval: 1000 * 60 * 60
         });
-        /*  re-persist the cached update information, as update-notifier consumes it on read,
+        /*  optionally query the NPM registry directly, where only
+            a successful query supersedes the cached update information  */
+        let update = notifier.update;
+        if (direct) {
+            const info = await Promise.resolve(notifier.fetchInfo()).catch(() => undefined);
+            if (info !== undefined)
+                update = info;
+        }
+        /*  re-persist the update information, as update-notifier consumes it on read,
             but only while it still denotes a newer version (it is never cleared otherwise)  */
-        const latest = notifier.update?.latest;
+        const latest = update?.latest;
         if (latest === undefined || !semver.valid(latest) || !semver.gt(latest, Version.current()))
             return Version.current();
-        notifier.config?.set("update", notifier.update);
+        notifier.config?.set("update", update);
         return latest;
     }
 }

package/dst/ase-man-catalog.js

@@ -0,0 +1,229 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { fuzzyMin, levenshtein, diceCoefficient } from "./ase-task-board-filter.js";
+/*  the grouping and ordering of the skills: a copy of the groups shown by the
+    catalog of the website ("skillPrefixGroups" of "pages/src/data/skills.ts",
+    in the column order of "Section-Usage.astro"), so keep both in sync, where
+    any skill not listed here is caught by a trailing "OTHER" group  */
+const skillGroups = [
+    ["HELP", ["ase-help-skill", "ase-help-intent"]],
+    ["META: CONFIG", ["ase-meta-config", "ase-meta-compat"]],
+    ["META: EXPLAIN", ["ase-meta-why", "ase-meta-eli5"]],
+    ["META: JUDGE", ["ase-meta-evaluate", "ase-meta-diaboli", "ase-meta-steelman"]],
+    ["META: RESEARCH", ["ase-meta-brainstorm", "ase-meta-search", "ase-meta-quorum",
+            "ase-meta-proximity", "ase-meta-chat", "ase-meta-quotes"]],
+    ["META: GENERATE", ["ase-meta-mint", "ase-meta-workflow"]],
+    ["ARCH", ["ase-arch-analyze", "ase-arch-discover"]],
+    ["DOCS", ["ase-docs-shorten", "ase-docs-refine", "ase-docs-proofread", "ase-docs-distill"]],
+    ["SPEC", ["ase-spec-lint", "ase-spec-edit", "ase-spec-activate"]],
+    ["CODE", ["ase-code-edit", "ase-code-analyze", "ase-code-insight", "ase-code-explain", "ase-code-lint"]],
+    ["REPO", ["ase-repo-review", "ase-repo-diff", "ase-repo-changelog", "ase-repo-commit",
+            "ase-repo-dissect", "ase-repo-merge", "ase-repo-resolve"]],
+    ["SYNC", ["ase-sync-reconcile", "ase-sync-import", "ase-sync-export"]],
+    ["TASK: MANAGE", ["ase-task-list", "ase-task-rename", "ase-task-delete"]],
+    ["TASK: HANDLE", ["ase-task-id", "ase-task-status", "ase-task-assign"]],
+    ["TASK: EDIT", ["ase-task-edit", "ase-task-view", "ase-task-grill", "ase-task-research",
+            "ase-task-estimate", "ase-task-reboot", "ase-task-condense", "ase-task-dissect"]],
+    ["TASK: EXECUTE", ["ase-task-implement", "ase-task-integrate"]]
+];
+/*  the order of the command groups: a copy of the column order of "manColumns"
+    of "pages/src/data/manpages.ts", so keep both in sync, where any group not
+    listed here (like the one of a newly added top-level command) is appended  */
+const commandGroups = ["Top-Level", "setup", "config", "service", "task", "spec", "util", "artifact", "agent", "hook"];
+/*  read the Markdown sources of the entries of a directory, by the page
+    names and the relative source paths derived from the entry names  */
+const readSources = (dir, pick) => {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch (err) {
+        throw new Error(`man: no manual pages found in "${dir}" (tool not completely built?)`, { cause: err });
+    }
+    const sources = new Map();
+    for (const entry of entries) {
+        const picked = pick(entry);
+        if (picked !== null && fs.existsSync(path.join(dir, picked[1])))
+            sources.set(picked[0], fs.readFileSync(path.join(dir, picked[1]), "utf8"));
+    }
+    return sources;
+};
+/*  create a manual page  */
+const makePage = (id, kind, label, title, md) => {
+    const text = md.toLowerCase();
+    return { id, kind, label, title, md, text, words: new Set(text.split(/[^a-z0-9]+/).filter((w) => w !== "")) };
+};
+/*  load the skill pages from the "help.md" files of the bundled plugin (see
+    the "build-plugin" build step), grouped like the catalog of the website  */
+const loadSkills = () => {
+    const pkgdir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    const dir = path.join(pkgdir, "plugin", "skills");
+    const sources = readSources(dir, (entry) => /^ase-[a-z0-9-]+$/.test(entry) ? [entry, path.join(entry, "help.md")] : null);
+    const page = (name) => {
+        const md = sources.get(name);
+        const m = /^#+\s+NAME\s*\n+\s*`?[\w-]+`?\s+-+\s+(.+)$/m.exec(md);
+        return makePage(name, "skill", name, m !== null ? m[1].trim() : name, md);
+    };
+    const listed = new Set(skillGroups.flatMap(([, names]) => names));
+    const other = [...sources.keys()].filter((name) => !listed.has(name)).sort();
+    return [...skillGroups, ["OTHER", other]]
+        .map(([label, names]) => ({ label, pages: names.filter((name) => sources.has(name)).map(page) }))
+        .filter((group) => group.pages.length > 0);
+};
+/*  load the command pages from the Markdown sources of the manual pages
+    (see the "build-man" build step), arranged into the command tree and
+    grouped like the catalog of the website ("pages/src/data/manpages.ts")  */
+const loadCommands = () => {
+    const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), "man");
+    const sources = readSources(dir, (entry) => /^ase(?:-[a-z0-9-]+)?\.md$/.test(entry) ? [entry.slice(0, -3), entry] : null);
+    const names = [...sources.keys()].sort();
+    /*  the parent of a page is the longest other page name it extends by a "-<suffix>"  */
+    const parentOf = (name) => names.filter((other) => name.startsWith(other + "-"))
+        .sort((a, b) => b.length - a.length)[0] ?? "";
+    /*  the children of a page, ordered by their first "`<name>`(1)" reference
+        within the COMMANDS section of the page (or the entire page), else alphabetically  */
+    const childrenOf = (parent) => {
+        const md = sources.get(parent);
+        const m = /^## COMMANDS\s*$([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(md);
+        const section = m !== null ? m[1] : md;
+        const pos = (name) => {
+            const idx = section.indexOf("`" + name + "`(1)");
+            return idx >= 0 ? idx : Infinity;
+        };
+        return names.filter((name) => parentOf(name) === parent)
+            .sort((a, b) => (pos(a) - pos(b)) || a.localeCompare(b));
+    };
+    /*  flatten the command tree depth-first  */
+    const tree = [];
+    const walk = (name, label, depth) => {
+        const md = sources.get(name);
+        const m = /^#\s+\S+\(1\)\s+--\s+(.+)$/m.exec(md);
+        tree.push({ page: makePage(`${name}.1`, "command", label, m !== null ? m[1].trim() : name, md), depth });
+        for (const child of childrenOf(name))
+            walk(child, label + " " + child.slice(name.length + 1), depth + 1);
+    };
+    for (const root of names.filter((name) => parentOf(name) === ""))
+        walk(root, root.replace(/-/g, " "), 0);
+    /*  group the command tree: "ase" itself and the top-level commands without
+        sub-commands form the "Top-Level" group, and every other top-level
+        command forms an own group with all of its deeper commands  */
+    const groups = [{ label: "Top-Level", pages: [] }];
+    for (const { page, depth } of tree) {
+        if (depth === 0)
+            groups[0].pages.push(page);
+        else if (depth === 1) {
+            if (tree.some((other) => other.depth > 1 && other.page.label.startsWith(page.label + " ")))
+                groups.push({ label: page.label.slice(page.label.lastIndexOf(" ") + 1), pages: [page] });
+            else
+                groups[0].pages.push(page);
+        }
+        else
+            groups[groups.length - 1].pages.push(page);
+    }
+    const rank = (group) => {
+        const idx = commandGroups.indexOf(group.label);
+        return idx >= 0 ? idx : commandGroups.length;
+    };
+    return groups
+        .filter((group) => group.pages.length > 0)
+        .sort((a, b) => rank(a) - rank(b))
+        .map((group) => ({ ...group, label: group.label.toUpperCase() }));
+};
+/*  load the catalog of all manual pages  */
+export const loadCatalog = () => {
+    const skills = loadSkills();
+    const commands = loadCommands();
+    const pages = new Map([...skills, ...commands].flatMap((group) => group.pages).map((page) => [page.id, page]));
+    const vocab = new Set([...pages.values()].flatMap((page) => [...page.words]));
+    return { skills, commands, pages, vocab };
+};
+/*  find the page fitting exactly onto the words of a page name or command path,
+    which are joined with dashes, where the "ase" prefix is optional, the name is
+    case-insensitive, and of a skill and a command of the same name, a page name
+    (e.g. "task-edit") prefers the skill, while a command path (e.g. "task edit")
+    prefers the command  */
+export const findPage = (catalog, words) => {
+    const parts = words.join(" ").trim().toLowerCase().split(/\s+/);
+    const name = parts.join("-");
+    const full = name === "ase" || name.startsWith("ase-") ? name : `ase-${name}`;
+    const skill = catalog.pages.get(full);
+    const command = catalog.pages.get(`${full}.1`);
+    return parts.length === 1 && name.includes("-") ? skill ?? command : command ?? skill;
+};
+/*  escape a string for its literal use within a regular expression  */
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/*  the regular expression of the matches of a search in a page: the
+    keywords as plain substrings, plus the fuzzy variants of the page as
+    whole words, with the longest alternative first, so a variant is never
+    cut short by a keyword nested inside it  */
+const matchRE = (keywords, variants) => {
+    const alts = keywords.map((k) => ({ len: k.length, src: escape(k) }))
+        .concat(variants.map((w) => ({ len: w.length, src: "(?<![a-z0-9])" + escape(w) + "(?![a-z0-9])" })));
+    alts.sort((a, b) => b.len - a.len);
+    return new RegExp(alts.map((a) => a.src).join("|"), "gi");
+};
+/*  search all pages for a query (as the website does): all whitespace-separated
+    keywords have to occur in a page (AND logic), in up to two passes, the
+    keywords as literal substrings first and, only if this matches no page at
+    all, as fuzzy variants of their words, as the edit-distance neighborhood of
+    a keyword would otherwise dilute a correctly spelled query; the result
+    maps the ids of the matching pages onto the regular expressions of their
+    matches, or is null for a query without any keywords  */
+export const searchPages = (catalog, query) => {
+    const keywords = query.toLowerCase().split(/\s+/).filter((word) => word !== "");
+    if (keywords.length === 0)
+        return null;
+    const pages = [...catalog.pages.values()];
+    const hits = new Map();
+    for (const page of pages)
+        if (keywords.every((k) => page.text.includes(k)))
+            hits.set(page.id, matchRE(keywords, []));
+    if (hits.size > 0)
+        return hits;
+    /*  the fuzzy-equivalent vocabulary words of a keyword, cached per keyword  */
+    const fuzzy = new Map();
+    const fuzzyWords = (word) => {
+        let result = fuzzy.get(word);
+        if (result === undefined) {
+            result = word.length < fuzzyMin ? [] : [...catalog.vocab].filter((given) => Math.abs(word.length - given.length) <= 1
+                && (diceCoefficient(word, given) >= 0.50 || levenshtein(word, given) <= 2));
+            fuzzy.set(word, result);
+        }
+        return result;
+    };
+    /*  the regular expression of the fuzzy variants of a compound keyword (like
+        "ase-task-edit"), with each of its words literally or fuzzily replaced
+        and its separators kept, cached per keyword (null for a single word)  */
+    const compound = new Map();
+    const compoundRE = (keyword) => {
+        let result = compound.get(keyword);
+        if (result === undefined) {
+            const parts = keyword.split(/([^a-z0-9]+)/);
+            result = parts.length < 2 ? null : new RegExp("(?<![a-z0-9])" + parts.map((part, i) => i % 2 === 1 ? escape(part) : part === "" ? "" :
+                "(?:" + [part, ...fuzzyWords(part)].map(escape).join("|") + ")").join("") + "(?![a-z0-9])", "g");
+            compound.set(keyword, result);
+        }
+        return result;
+    };
+    for (const page of pages) {
+        const variants = [];
+        const hit = keywords.every((k) => {
+            if (page.text.includes(k))
+                return true;
+            const re = compoundRE(k);
+            const near = re !== null ? [...new Set([...page.text.matchAll(re)].map((m) => m[0]))] :
+                fuzzyWords(k).filter((w) => page.words.has(w));
+            variants.push(...near);
+            return near.length > 0;
+        });
+        if (hit)
+            hits.set(page.id, matchRE(keywords, variants));
+    }
+    return hits;
+};

package/dst/ase-man-render.js

@@ -0,0 +1,278 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { marked } from "marked";
+/*  the syntax highlighter of the code blocks (via Shiki, with its JavaScript
+    regular expression engine, i.e. without WebAssembly, and with an empty
+    theme, as only the TextMate scopes of the tokens are used), loaded on
+    demand only once  */
+let highlighter = null;
+let loading = null;
+export const codeLoad = () => {
+    if (loading === null) {
+        loading = (async () => {
+            const [{ createHighlighterCore }, { createJavaScriptRegexEngine }, { bundledLanguages }] = await Promise.all([
+                import("shiki/core"), import("shiki/engine/javascript"), import("shiki/langs")
+            ]);
+            highlighter = await createHighlighterCore({
+                themes: [{ name: "ase", type: "dark", settings: [] }],
+                langs: [bundledLanguages.shellscript, bundledLanguages.yaml, bundledLanguages.json, bundledLanguages.typescript],
+                engine: createJavaScriptRegexEngine()
+            });
+        })();
+    }
+    return loading;
+};
+/*  the highlighted languages of the code blocks, by their fence info  */
+const codeLangs = {
+    sh: "shellscript", bash: "shellscript", shell: "shellscript", shellscript: "shellscript",
+    yaml: "yaml", yml: "yaml", json: "json", ts: "typescript", typescript: "typescript"
+};
+/*  the tones of the code tokens, by the prefixes of their TextMate scopes (first match wins)  */
+const codeScopes = [
+    ["cmt", ["comment"]],
+    ["str", ["string.quoted", "string.template", "string.unquoted.plain", "string.unquoted.block"]],
+    ["opt", ["constant.other.option"]],
+    ["var", ["variable.other.normal", "variable.other.special", "variable.other.positional"]],
+    ["num", ["constant.numeric", "constant.language"]],
+    ["key", ["entity.name.tag", "support.type.property-name"]],
+    ["cmd", ["entity.name.command", "entity.name.function", "support.function"]],
+    ["kw", ["keyword", "storage"]],
+    ["punct", ["punctuation"]]
+];
+/*  append a span to a line, merging it into the last span of equal attributes  */
+const append = (line, span) => {
+    const last = line[line.length - 1];
+    if (last !== undefined && last.tone === span.tone && last.ref === span.ref && last.match === span.match)
+        last.text += span.text;
+    else
+        line.push({ ...span });
+};
+/*  split the text of a code block into lines of syntax-highlighting spans
+    (all as plain text for an unknown language or while the highlighter is
+    not loaded yet, see "codeLoad")  */
+const codeLines = (text, lang) => {
+    const name = codeLangs[(lang ?? "").toLowerCase()];
+    if (highlighter === null || name === undefined)
+        return text.split(/\r?\n/).map((line) => [{ text: line, tone: "text" }]);
+    const { tokens } = highlighter.codeToTokens(text, { lang: name, theme: "ase", includeExplanation: "scopeName" });
+    return tokens.map((line) => {
+        const out = [];
+        for (const part of line.flatMap((token) => token.explanation ?? [{ content: token.content, scopes: [] }])) {
+            const scopes = part.scopes.map((scope) => scope.scopeName);
+            const tone = codeScopes.find(([, prefixes]) => scopes.some((scope) => prefixes.some((prefix) => scope === prefix || scope.startsWith(prefix + "."))))?.[0] ?? "text";
+            append(out, { text: part.content, tone });
+        }
+        return out;
+    });
+};
+/*  register a reference onto a page, if it is referable  */
+const refOf = (ctx, id) => {
+    if (!ctx.exists(id))
+        return undefined;
+    ctx.refs.push({ id, line: -1 });
+    return ctx.refs.length - 1;
+};
+/*  render inline tokens into spans of a base tone, where a code span naming
+    a page (a skill by its name, or a command by its name directly followed by
+    "(1)") and a link onto the "help.md" of a skill reference this page, and
+    a hard line break is a span of a single newline  */
+const inline = (tokens, tone, ctx) => {
+    const out = [];
+    tokens.forEach((token, i) => {
+        const next = tokens[i + 1];
+        if (token.type === "strong")
+            out.push(...inline(token.tokens, "bold", ctx));
+        else if (token.type === "em")
+            out.push(...inline(token.tokens, "italic", ctx));
+        else if (token.type === "del")
+            out.push(...inline(token.tokens, tone, ctx));
+        else if (token.type === "codespan") {
+            const text = token.text;
+            const man = next !== undefined && next.type === "text" && next.text.startsWith("(1)");
+            out.push({ text: text.replace(/\n/g, " "), tone: "code", ref: refOf(ctx, man ? `${text}.1` : text) });
+        }
+        else if (token.type === "link") {
+            const link = token;
+            const spans = inline(link.tokens, "link", ctx);
+            const m = /^(?:\.\.\/)?(ase-[a-z0-9-]+)\/help\.md$/.exec(link.href);
+            const ref = m !== null && !spans.some((span) => span.ref !== undefined) ? refOf(ctx, m[1]) : undefined;
+            out.push(...spans.map((span) => ({ ...span, ref: span.ref ?? ref })));
+        }
+        else if (token.type === "text") {
+            const text = token;
+            if (text.tokens !== undefined && text.tokens.length > 0)
+                out.push(...inline(text.tokens, tone, ctx));
+            else
+                out.push({ text: text.text.replace(/\n/g, " "), tone });
+        }
+        else if (token.type === "br")
+            out.push({ text: "\n", tone });
+        else if (token.type === "escape" || token.type === "html" || token.type === "image")
+            out.push({ text: token.text.replace(/\n/g, " "), tone });
+        else
+            out.push({ text: token.raw.replace(/\n/g, " "), tone });
+    });
+    return out;
+};
+/*  word-wrap spans onto lines of a width: the spans are split into words
+    (glued across adjacent spans, like a code span directly followed by its
+    punctuation), which are laid out with single spaces in between, where a
+    span of a single newline breaks the line and an overlong word is broken hard  */
+const wrap = (spans, width) => {
+    const atoms = [];
+    let atom = null;
+    let space = false;
+    for (const span of spans) {
+        if (span.text === "\n") {
+            atoms.push(null);
+            atom = null;
+            space = false;
+            continue;
+        }
+        for (const piece of span.text.split(/(\s+)/)) {
+            if (piece === "")
+                continue;
+            if (/^\s+$/.test(piece)) {
+                atom = null;
+                space = true;
+                continue;
+            }
+            if (atom === null) {
+                atom = { parts: [], len: 0, space };
+                space = false;
+                atoms.push(atom);
+            }
+            atom.parts.push({ ...span, text: piece });
+            atom.len += piece.length;
+        }
+    }
+    const lines = [];
+    let line = [];
+    let col = 0;
+    const newline = () => {
+        lines.push(line);
+        line = [];
+        col = 0;
+    };
+    for (const a of atoms) {
+        if (a === null) {
+            newline();
+            continue;
+        }
+        if (col > 0 && col + (a.space ? 1 : 0) + a.len > width)
+            newline();
+        if (col > 0 && a.space) {
+            const prev = line[line.length - 1];
+            const same = prev.tone === a.parts[0].tone && prev.ref === a.parts[0].ref;
+            append(line, same ? { ...prev, text: " " } : { text: " ", tone: "text" });
+            col++;
+        }
+        for (const part of a.parts) {
+            let text = part.text;
+            while (col + text.length > width) {
+                const n = width - col;
+                if (n > 0)
+                    append(line, { ...part, text: text.slice(0, n) });
+                text = text.slice(n);
+                newline();
+            }
+            if (text !== "") {
+                append(line, { ...part, text });
+                col += text.length;
+            }
+        }
+    }
+    if (line.length > 0 || lines.length === 0)
+        lines.push(line);
+    return lines;
+};
+/*  render block tokens into lines of a width, separated by empty lines
+    (unless tight, as within the items of a tight list), where list items,
+    code blocks, and block quotes are all indented by four columns  */
+const blocks = (tokens, width, ctx, tight = false) => {
+    const out = [];
+    const add = (lines) => {
+        if (lines.length === 0)
+            return;
+        if (out.length > 0 && !tight)
+            out.push([]);
+        out.push(...lines);
+    };
+    for (const token of tokens) {
+        if (token.type === "space" || token.type === "def")
+            continue;
+        else if (token.type === "heading") {
+            const head = token;
+            add(wrap(inline(head.tokens, head.depth === 1 ? "title" : head.depth === 2 ? "head" : "sub", ctx), width));
+        }
+        else if (token.type === "paragraph" || token.type === "text") {
+            const para = token;
+            add(wrap(para.tokens !== undefined ? inline(para.tokens, "text", ctx) : [{ text: para.text, tone: "text" }], width));
+        }
+        else if (token.type === "list") {
+            const list = token;
+            const lines = [];
+            list.items.forEach((item, k) => {
+                const bullet = list.ordered ? `${(list.start === "" ? 1 : list.start) + k}. `.padEnd(4) : "●   ";
+                const body = blocks(item.tokens, Math.max(10, width - bullet.length), ctx, !item.loose);
+                if (list.loose && k > 0)
+                    lines.push([]);
+                if (body.length === 0)
+                    body.push([]);
+                body.forEach((line, n) => {
+                    lines.push([{ text: n === 0 ? bullet : " ".repeat(bullet.length), tone: "bullet" }, ...line]);
+                });
+            });
+            add(lines);
+        }
+        else if (token.type === "code") {
+            const code = token;
+            add(codeLines(code.text, code.lang).map((line) => [{ text: "    ", tone: "text" }, ...line]));
+        }
+        else if (token.type === "blockquote")
+            add(blocks(token.tokens, Math.max(10, width - 4), ctx)
+                .map((line) => [{ text: "  │ ", tone: "dim" }, ...line]));
+        else if (token.type === "hr")
+            add([[{ text: "─".repeat(width), tone: "dim" }]]);
+        else
+            add(token.raw.replace(/\n+$/, "").split("\n").map((line) => [{ text: line, tone: "dim" }]));
+    }
+    return out;
+};
+/*  render the Markdown source of a page (with the id "self") into lines of
+    a width, where references onto the page itself are omitted  */
+export const renderPage = (md, width, self, exists) => {
+    const ctx = { refs: [], exists: (id) => id !== self && exists(id) };
+    const lines = blocks(marked.lexer(md.replace(/\t/g, "    ")), Math.max(10, width), ctx);
+    lines.forEach((line, n) => {
+        for (const span of line)
+            if (span.ref !== undefined && ctx.refs[span.ref].line < 0)
+                ctx.refs[span.ref].line = n;
+    });
+    return { lines, refs: ctx.refs };
+};
+/*  mark the matches of a (global) regular expression within a line  */
+export const markMatches = (line, re) => {
+    const text = line.map((span) => span.text).join("");
+    const marks = new Array(text.length).fill(false);
+    let found = false;
+    for (const m of text.matchAll(re)) {
+        if (m[0].length === 0)
+            continue;
+        marks.fill(true, m.index, m.index + m[0].length);
+        found = true;
+    }
+    if (!found)
+        return line;
+    const out = [];
+    let pos = 0;
+    for (const span of line) {
+        for (let i = 0; i < span.text.length; i++)
+            append(out, { ...span, text: span.text[i], match: marks[pos + i] });
+        pos += span.text.length;
+    }
+    return out;
+};