sfora-cli 0.9.0 → 0.11.0

package/dist/format/sheetSelection.js

@@ -0,0 +1,282 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+/**
+ * Keyboard-first selection for the sheet block.
+ *
+ * The shape is BlockSuite's data-view model, kept because it earns its keep: a
+ * selection is a plain serializable VALUE — a focus coordinate plus a rung —
+ * not a DOM range, not a set of element references. That is what lets the same
+ * selection survive a re-render, a re-parse of the block source, a round trip
+ * through JSON, and (later) a collaborative cursor. Reference:
+ * context/AFFiNE/blocksuite/affine/data-view/src/view-presets/table/selection.ts
+ * and .../table/pc/controller/hotkeys.ts.
+ *
+ * Three of their behaviours are deliberately NOT copied.
+ *
+ * 1. The inescapable Escape loop. In their hotkeys, Escape on a cell promotes
+ *    to row selection and Escape on a row selection converts the rows straight
+ *    back into an area selection — the two rungs trade places forever and the
+ *    table never lets go. Here Escape walks a strictly decreasing ladder
+ *    (editing → cell → row → none) and then reports `ignored` so the key
+ *    belongs to whatever encloses the block. `selectionRung` is the proof
+ *    obligation: every Escape lowers it, so the walk terminates.
+ *
+ * 2. Tab dead-ending. Theirs wraps to the next row and stops moving at the last
+ *    cell while still swallowing the key, so a keyboard user is trapped in the
+ *    grid with no way forward. Here Tab past the last cell RELEASES — the
+ *    caller lets the browser move focus on — and the selection value is left
+ *    intact so tabbing back in lands where you left.
+ *
+ * 3. Silent undefined. Their cell lookups go through a DOM query that returns
+ *    `undefined` and the handler simply does nothing, so a coordinate that has
+ *    drifted out of range is indistinguishable from a key that did nothing.
+ *    This reducer is total: coordinates are clamped against the shape on every
+ *    transition, and every call returns a named outcome.
+ */
+export const SHEET_SELECTION_NONE = { kind: "none" };
+/**
+ * The ladder rung. Escape lowers it by exactly one, which is the whole reason
+ * the Escape walk terminates rather than ping-ponging.
+ */
+export function selectionRung(selection) {
+    if (selection.kind === "none")
+        return 0;
+    if (selection.kind === "row")
+        return 1;
+    return selection.isEditing ? 3 : 2;
+}
+function clamp(value, max) {
+    if (!Number.isFinite(value))
+        return 0;
+    if (value < 0)
+        return 0;
+    if (value > max)
+        return max;
+    return value;
+}
+function inShape(shape) {
+    return shape.rows > 0 && shape.columns > 0;
+}
+/** Every coordinate that leaves this module has been pulled back in range. */
+function normalize(selection, shape) {
+    if (!inShape(shape))
+        return SHEET_SELECTION_NONE;
+    if (selection.kind === "row") {
+        return { kind: "row", rowIndex: clamp(selection.rowIndex, shape.rows - 1) };
+    }
+    if (selection.kind === "cell") {
+        return {
+            kind: "cell",
+            rowIndex: clamp(selection.rowIndex, shape.rows - 1),
+            columnIndex: clamp(selection.columnIndex, shape.columns - 1),
+            isEditing: selection.isEditing,
+        };
+    }
+    return selection;
+}
+/**
+ * Re-seat a selection against a new shape. The block source can change under
+ * the selection — an agent writes a row, a paste shortens one — and the value
+ * has to stay meaningful without being thrown away.
+ */
+export function reseatSelection(selection, shape) {
+    return normalize(selection, shape);
+}
+function stay(selection, outcome = "handled") {
+    return { selection, outcome, write: null, draft: null };
+}
+/** Linear cell index, so Tab is one arithmetic step and its edges are obvious. */
+function linearIndex(rowIndex, columnIndex, shape) {
+    return rowIndex * shape.columns + columnIndex;
+}
+export function sheetSelectionReducer(selection, action, context) {
+    const shape = context.shape;
+    if (!inShape(shape))
+        return stay(SHEET_SELECTION_NONE, "ignored");
+    const current = normalize(selection, shape);
+    switch (action.type) {
+        case "focusCell": {
+            const next = normalize({
+                kind: "cell",
+                rowIndex: action.rowIndex,
+                columnIndex: action.columnIndex,
+                isEditing: action.edit === true,
+            }, shape);
+            const draft = next.kind === "cell" && next.isEditing ? context.read(next.rowIndex, next.columnIndex) : null;
+            return { selection: next, outcome: "handled", write: null, draft };
+        }
+        case "release":
+            return stay(SHEET_SELECTION_NONE);
+        case "move": {
+            if (current.kind === "none") {
+                return {
+                    selection: { kind: "cell", rowIndex: 0, columnIndex: 0, isEditing: false },
+                    outcome: "handled",
+                    write: null,
+                    draft: null,
+                };
+            }
+            if (current.kind === "row") {
+                // A row is a whole-row rung: up and down walk rows, right steps back
+                // into the row's first cell. Left has nothing lower to go to.
+                if (action.direction === "up" || action.direction === "down") {
+                    const delta = action.direction === "up" ? -1 : 1;
+                    return stay(normalize({ kind: "row", rowIndex: current.rowIndex + delta }, shape));
+                }
+                if (action.direction === "right") {
+                    return stay(normalize({ kind: "cell", rowIndex: current.rowIndex, columnIndex: 0, isEditing: false }, shape));
+                }
+                return stay(current);
+            }
+            // Arrows inside an open editor belong to the caret, not to the grid.
+            if (current.isEditing)
+                return stay(current, "ignored");
+            const rowDelta = action.direction === "up" ? -1 : action.direction === "down" ? 1 : 0;
+            const columnDelta = action.direction === "left" ? -1 : action.direction === "right" ? 1 : 0;
+            // Arrows clamp at the edges rather than wrapping: an arrow key names a
+            // direction on the grid, and wrapping would make it name a different one.
+            return stay(normalize({
+                kind: "cell",
+                rowIndex: current.rowIndex + rowDelta,
+                columnIndex: current.columnIndex + columnDelta,
+                isEditing: false,
+            }, shape));
+        }
+        case "step": {
+            if (current.kind === "none") {
+                const first = action.direction === "forward"
+                    ? { rowIndex: 0, columnIndex: 0 }
+                    : { rowIndex: shape.rows - 1, columnIndex: shape.columns - 1 };
+                return stay({ kind: "cell", ...first, isEditing: false });
+            }
+            if (current.kind === "row") {
+                return stay(normalize({ kind: "cell", rowIndex: current.rowIndex, columnIndex: 0, isEditing: false }, shape));
+            }
+            const total = shape.rows * shape.columns;
+            const index = linearIndex(current.rowIndex, current.columnIndex, shape);
+            const nextIndex = action.direction === "forward" ? index + 1 : index - 1;
+            if (nextIndex < 0 || nextIndex >= total) {
+                // The grid is finished with the key. The coordinate is KEPT — tabbing
+                // back in returns to the cell you left, which is the whole reason not
+                // to dead-end here.
+                return stay({ kind: "cell", rowIndex: current.rowIndex, columnIndex: current.columnIndex, isEditing: false }, action.direction === "forward" ? "released-forward" : "released-back");
+            }
+            return stay({
+                kind: "cell",
+                rowIndex: Math.floor(nextIndex / shape.columns),
+                columnIndex: nextIndex % shape.columns,
+                isEditing: false,
+            });
+        }
+        case "enter": {
+            if (current.kind === "none") {
+                return stay({ kind: "cell", rowIndex: 0, columnIndex: 0, isEditing: false });
+            }
+            if (current.kind === "row") {
+                return stay(normalize({ kind: "cell", rowIndex: current.rowIndex, columnIndex: 0, isEditing: false }, shape));
+            }
+            if (current.isEditing) {
+                // Committing is the caller's job — it holds the draft. Enter only says
+                // where to land afterwards.
+                return stay(current, "handled");
+            }
+            return {
+                selection: { ...current, isEditing: true },
+                outcome: "handled",
+                write: null,
+                draft: context.read(current.rowIndex, current.columnIndex),
+            };
+        }
+        case "escape": {
+            if (current.kind === "none")
+                return stay(current, "ignored");
+            if (current.kind === "row")
+                return stay(SHEET_SELECTION_NONE);
+            if (current.isEditing) {
+                // Escape discards. No write leaves this branch, which is what makes
+                // "Escape returns to cell selection" safe to press on a typo.
+                return stay({ ...current, isEditing: false });
+            }
+            return stay({ kind: "row", rowIndex: current.rowIndex });
+        }
+        case "typeChar": {
+            if (current.kind !== "cell" || current.isEditing)
+                return stay(current, "ignored");
+            if (action.char.length !== 1)
+                return stay(current, "ignored");
+            // Typing REPLACES: the draft starts as the character, not as the cell.
+            return {
+                selection: { ...current, isEditing: true },
+                outcome: "handled",
+                write: null,
+                draft: action.char,
+            };
+        }
+        case "clear": {
+            if (current.kind !== "cell" || current.isEditing)
+                return stay(current, "ignored");
+            return {
+                selection: current,
+                outcome: "handled",
+                write: { rowIndex: current.rowIndex, columnIndex: current.columnIndex, value: "" },
+                draft: null,
+            };
+        }
+        case "commit": {
+            if (current.kind !== "cell")
+                return stay(current, "ignored");
+            const write = {
+                rowIndex: current.rowIndex,
+                columnIndex: current.columnIndex,
+                value: action.value,
+            };
+            if (action.then === "stay") {
+                return { selection: { ...current, isEditing: false }, outcome: "handled", write, draft: null };
+            }
+            if (action.then === "down") {
+                const next = normalize({ kind: "cell", rowIndex: current.rowIndex + 1, columnIndex: current.columnIndex, isEditing: false }, shape);
+                return { selection: next, outcome: "handled", write, draft: null };
+            }
+            const stepped = sheetSelectionReducer({ ...current, isEditing: false }, { type: "step", direction: action.then === "forward" ? "forward" : "back" }, context);
+            return { selection: stepped.selection, outcome: stepped.outcome, write, draft: null };
+        }
+    }
+}
+/**
+ * A keyboard event, read as an action. Split from the reducer so the key map
+ * is a table a test can walk without a DOM.
+ *
+ * Returns null for keys the block has no opinion about, which is the same
+ * statement as `ignored` — nothing here silently swallows a key.
+ */
+export function sheetKeyAction(event) {
+    const modified = event.metaKey === true || event.ctrlKey === true || event.altKey === true;
+    switch (event.key) {
+        case "ArrowUp":
+            return modified ? null : { type: "move", direction: "up" };
+        case "ArrowDown":
+            return modified ? null : { type: "move", direction: "down" };
+        case "ArrowLeft":
+            return modified ? null : { type: "move", direction: "left" };
+        case "ArrowRight":
+            return modified ? null : { type: "move", direction: "right" };
+        case "Tab":
+            return modified ? null : { type: "step", direction: event.shiftKey ? "back" : "forward" };
+        case "Enter":
+            return modified ? null : { type: "enter" };
+        case "Escape":
+            return { type: "escape" };
+        case "Backspace":
+        case "Delete":
+            return modified ? null : { type: "clear" };
+        default:
+            if (!modified && event.key.length === 1)
+                return { type: "typeChar", char: event.key };
+            return null;
+    }
+}
+/**
+ * Where Enter should land after committing an edit — down a row, matching
+ * every spreadsheet. Kept as a named function so the hook and its test agree.
+ */
+export const ENTER_COMMIT_LANDING = "down";

package/dist/format/taskUploadFilename.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The `task` verb creates work. Canonical board filenames begin with a card
+ * number, but carrying that prefix into a cloud PUT would target that existing
+ * card. Strip it here; explicit updates belong to the filesystem API.
+ */
+export declare function taskUploadFilename(filename: string): string;

package/dist/format/taskUploadFilename.js

@@ -0,0 +1,13 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+/**
+ * The `task` verb creates work. Canonical board filenames begin with a card
+ * number, but carrying that prefix into a cloud PUT would target that existing
+ * card. Strip it here; explicit updates belong to the filesystem API.
+ */
+export function taskUploadFilename(filename) {
+    const stem = filename
+        .replace(/\.md$/i, "")
+        .replace(/^\d+(?:[-_. ]+|$)/, "");
+    return `${stem || "task"}.md`;
+}

package/dist/format/textStats.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Document statistics for editor footers.
+ *
+ * Word counting splits with `Intl.Segmenter` where it exists: whitespace
+ * splitting reports one word for an entire Chinese or Japanese sentence, which
+ * is the bug open-knowledge's `selection-stats.ts` fixes the same way. The
+ * fallback keeps that property by counting CJK ideographs individually.
+ *
+ * Token count is a chars/4 heuristic, not a tokenizer — always render it with a
+ * leading `~` so it never reads as exact.
+ */
+/**
+ * Words in a chunk of Markdown. Punctuation-only segments (`#`, `*`, `|`) are
+ * not word-like, so Markdown syntax drops out without a stripping pass.
+ */
+export declare function countWords(text: string): number;
+/** Rough token count: ~4 characters per token, the usual English-prose ratio. */
+export declare function estimateTokens(text: string): number;
+export type DocumentStats = {
+    words: number;
+    tokens: number;
+};
+export declare function documentStats(text: string): DocumentStats;

package/dist/format/textStats.js

@@ -0,0 +1,80 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+/**
+ * Document statistics for editor footers.
+ *
+ * Word counting splits with `Intl.Segmenter` where it exists: whitespace
+ * splitting reports one word for an entire Chinese or Japanese sentence, which
+ * is the bug open-knowledge's `selection-stats.ts` fixes the same way. The
+ * fallback keeps that property by counting CJK ideographs individually.
+ *
+ * Token count is a chars/4 heuristic, not a tokenizer — always render it with a
+ * leading `~` so it never reads as exact.
+ */
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const CJK_GLOBAL = new RegExp(CJK.source, "gu");
+const LATIN_WORD = /[\p{L}\p{N}][\p{L}\p{N}'’_-]*/gu;
+const CHARS_PER_TOKEN = 4;
+let segmenter;
+function wordSegmenter() {
+    if (segmenter !== undefined)
+        return segmenter;
+    const ctor = Intl
+        .Segmenter;
+    segmenter = ctor ? new ctor(undefined, { granularity: "word" }) : null;
+    return segmenter;
+}
+/**
+ * Words in a chunk of Markdown. Punctuation-only segments (`#`, `*`, `|`) are
+ * not word-like, so Markdown syntax drops out without a stripping pass.
+ */
+export function countWords(text) {
+    if (text.trim().length === 0)
+        return 0;
+    const prose = withoutUrls(text);
+    const seg = wordSegmenter();
+    if (seg) {
+        let words = 0;
+        let previousWasWord = false;
+        let pendingJoiner = false;
+        for (const part of seg.segment(prose)) {
+            if (part.isWordLike) {
+                // UAX #29 breaks on a hyphen, so "well-known" arrives as two segments.
+                // Rejoin it: people read a hyphenated compound as one word.
+                if (!(pendingJoiner && previousWasWord))
+                    words++;
+                previousWasWord = true;
+                pendingJoiner = false;
+                continue;
+            }
+            pendingJoiner = part.segment === "-" || part.segment === "_";
+            if (!pendingJoiner)
+                previousWasWord = false;
+        }
+        return words;
+    }
+    const cjk = prose.match(CJK_GLOBAL)?.length ?? 0;
+    let latin = 0;
+    for (const match of prose.matchAll(LATIN_WORD)) {
+        if (!CJK.test(match[0]))
+            latin++;
+    }
+    return latin + cjk;
+}
+/**
+ * Link destinations are addresses, not prose — a document of links should not
+ * report a word count inflated by its own URLs.
+ */
+function withoutUrls(text) {
+    return text.replace(/\]\([^)\n]*\)/g, "]").replace(/<?\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, " ");
+}
+/** Rough token count: ~4 characters per token, the usual English-prose ratio. */
+export function estimateTokens(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 0;
+    return Math.max(1, Math.round(trimmed.length / CHARS_PER_TOKEN));
+}
+export function documentStats(text) {
+    return { words: countWords(text), tokens: estimateTokens(text) };
+}

package/dist/format/wayfinder.d.ts

@@ -0,0 +1,50 @@
+export declare const WAYFINDER_TICKET_TYPES: readonly ["grilling", "prototype", "research", "task"];
+export type WayfinderTicketType = (typeof WAYFINDER_TICKET_TYPES)[number];
+export type WayfinderTicketState = "open" | "claimed" | "decided" | "out-of-scope";
+export interface WayfinderTicket {
+    name: string;
+    type: WayfinderTicketType;
+    state: WayfinderTicketState;
+    /** Names of the tickets blocking this one. */
+    blockedBy: string[];
+    /**
+     * When set, the picture classes this node from it and skips frontierOf's
+     * name-resolution. A caller with server-side blocker buckets (the Plan) is
+     * the truth about blockedness: a DELETED blocker card is cleared there,
+     * while a dangling NAME in an authored map stays unresolved — without the
+     * override, a question whose blocker was deleted would render ghost-blocked
+     * in the very view whose data source already ruled it takeable.
+     */
+    onFrontier?: boolean;
+}
+export interface WayfinderMap {
+    /** What reaching the end of the map looks like. Drawn as the terminal node. */
+    destination?: string;
+    tickets: WayfinderTicket[];
+}
+/**
+ * Parse a ticket-list section (the lines between headings). Non-matching
+ * lines are ignored — the list can sit inside a larger map document. Returns
+ * an empty list rather than null: a map with no tickets yet is a real state
+ * (freshly charted, everything still in the fog), not a parse failure.
+ */
+export declare function parseWayfinderTickets(section: string): WayfinderTicket[];
+/**
+ * A ticket is on the FRONTIER when it is open and everything blocking it is
+ * closed (decided or out of scope). Blockers named but absent from the map
+ * count as unresolved — a dangling name is a map error the picture should
+ * make visible, not hide.
+ */
+export declare function frontierOf(tickets: WayfinderTicket[]): WayfinderTicket[];
+export declare function wayfinderNodeId(index: number): string;
+/**
+ * Draw a map as mermaid flowchart source the engine renders natively (the
+ * renderer honors classDef, so states carry color in both themes via the
+ * palette the diagram theme derives from --fg/--accent).
+ *
+ * Reading the picture: solid arrows are blocking edges pointing at what they
+ * unblock; the frontier is bold; decided tickets are quiet; out-of-scope
+ * tickets sit dashed at the edge; the destination, when named, is the
+ * terminal node every unblocked leaf feeds.
+ */
+export declare function wayfinderMapToMermaid(map: WayfinderMap): string;

package/dist/format/wayfinder.js

@@ -0,0 +1,203 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// Wayfinder maps — the shared vocabulary for charting a big effort as a map
+// of decision tickets, and the one place its textual form and its picture are
+// defined.
+//
+// The concepts come from mattpocock/skills' wayfinder (studied in
+// docs/research/wayfinder-sfora-map.md; repo vendored in context/): a MAP with
+// a destination, decision TICKETS of four types, BLOCKING edges between them,
+// and states — open on the frontier, claimed, decided, ruled out of scope,
+// with unspecifiable work waiting in the fog. sfora's Plan already carries the
+// same lifecycle (fuzzy / up-for-grabs / claimed / decided), so this module
+// speaks both dialects: wayfinder's names on the wire, the Plan's states
+// mappable one-to-one.
+//
+// Two exports matter:
+//   parseWayfinderTickets — read tickets from the map's markdown ticket list
+//   wayfinderMapToMermaid — draw the map as a flowchart the engine renders
+//
+// Pure string transforms — no React, no Convex, no Node.
+//
+// ── The ticket-list line grammar ───────────────────────────────────────────
+//
+//   - [ ] Pick the auth provider (grilling)
+//   - [~] Prototype the login screen (prototype) <- Pick the auth provider
+//   - [x] Name the destination
+//   - [-] Native mobile app
+//
+// State rides in the bracket: `[ ]` open, `[~]` claimed, `[x]` decided,
+// `[-]` out of scope. The type rides in a trailing parenthesis (grilling when
+// absent — wayfinder's default). `<- A, B` names the tickets blocking this
+// one, by title. Everything is referred to BY NAME, per wayfinder's rule that
+// a wall of ids is illegible.
+export const WAYFINDER_TICKET_TYPES = [
+    "grilling",
+    "prototype",
+    "research",
+    "task",
+];
+const STATE_BY_MARK = {
+    " ": "open",
+    "~": "claimed",
+    x: "decided",
+    X: "decided",
+    "-": "out-of-scope",
+};
+const TICKET_LINE = /^[-*]\s+\[([ ~xX-])\]\s+(.+)$/;
+/**
+ * Parse a ticket-list section (the lines between headings). Non-matching
+ * lines are ignored — the list can sit inside a larger map document. Returns
+ * an empty list rather than null: a map with no tickets yet is a real state
+ * (freshly charted, everything still in the fog), not a parse failure.
+ */
+export function parseWayfinderTickets(section) {
+    const tickets = [];
+    for (const raw of section.split(/\r?\n/)) {
+        const match = TICKET_LINE.exec(raw.trim());
+        if (!match)
+            continue;
+        let rest = match[2].trim();
+        let blockedBy = [];
+        const arrow = rest.indexOf("<-");
+        if (arrow >= 0) {
+            blockedBy = rest
+                .slice(arrow + 2)
+                .split(",")
+                .map((name) => name.trim())
+                .filter(Boolean);
+            rest = rest.slice(0, arrow).trim();
+        }
+        let type = "grilling";
+        const typed = /^(.*)\((grilling|prototype|research|task)\)$/.exec(rest);
+        if (typed) {
+            type = typed[2];
+            rest = typed[1].trim();
+        }
+        if (!rest)
+            continue;
+        tickets.push({
+            name: rest,
+            type,
+            state: STATE_BY_MARK[match[1]] ?? "open",
+            blockedBy,
+        });
+    }
+    return tickets;
+}
+// A blocker clears the way once it is CLOSED — decided or ruled out of scope.
+// Wayfinder's rule is that any terminal ticket unblocks; ruling a blocker out
+// of scope answers the question as surely as deciding it does.
+const TERMINAL_STATES = new Set([
+    "decided",
+    "out-of-scope",
+]);
+/**
+ * A ticket is on the FRONTIER when it is open and everything blocking it is
+ * closed (decided or out of scope). Blockers named but absent from the map
+ * count as unresolved — a dangling name is a map error the picture should
+ * make visible, not hide.
+ */
+export function frontierOf(tickets) {
+    const byName = new Map(tickets.map((ticket) => [ticket.name, ticket]));
+    return tickets.filter((ticket) => {
+        if (ticket.state !== "open")
+            return false;
+        return ticket.blockedBy.every((name) => {
+            const blocker = byName.get(name);
+            return blocker !== undefined && TERMINAL_STATES.has(blocker.state);
+        });
+    });
+}
+// Node ids must be word-safe for the flowchart grammar; the label carries the
+// real name. Stable across renders: derived from position, not content.
+// Exported so a consumer can join a rendered node's data-id back to the
+// ticket at the same index without re-implementing the scheme.
+export function wayfinderNodeId(index) {
+    return `t${index}`;
+}
+const TYPE_GLYPH = {
+    grilling: "", // the default carries no marker — most tickets are grilling
+    prototype: " ◇",
+    research: " ※",
+    task: " ⚙",
+};
+function escapeLabel(name) {
+    // Brackets and quotes would close the node's label early.
+    return name.replace(/["[\]]/g, " ").replace(/\s+/g, " ").trim();
+}
+/**
+ * Draw a map as mermaid flowchart source the engine renders natively (the
+ * renderer honors classDef, so states carry color in both themes via the
+ * palette the diagram theme derives from --fg/--accent).
+ *
+ * Reading the picture: solid arrows are blocking edges pointing at what they
+ * unblock; the frontier is bold; decided tickets are quiet; out-of-scope
+ * tickets sit dashed at the edge; the destination, when named, is the
+ * terminal node every unblocked leaf feeds.
+ */
+export function wayfinderMapToMermaid(map) {
+    const { tickets } = map;
+    const byName = new Map(tickets.map((ticket, index) => [ticket.name, index]));
+    const frontier = new Set(frontierOf(tickets).map((ticket) => ticket.name));
+    const lines = ["flowchart TD"];
+    for (const [index, ticket] of tickets.entries()) {
+        const label = escapeLabel(ticket.name) + TYPE_GLYPH[ticket.type];
+        // Shape says state at a glance even without color: decided closes into a
+        // stadium, out-of-scope stays a plain box, open work is a sharp rect.
+        const node = ticket.state === "decided"
+            ? `${wayfinderNodeId(index)}(["${label} ✓"])`
+            : `${wayfinderNodeId(index)}["${label}"]`;
+        lines.push(`  ${node}`);
+    }
+    for (const [index, ticket] of tickets.entries()) {
+        for (const blocker of ticket.blockedBy) {
+            const from = byName.get(blocker);
+            if (from === undefined) {
+                // A dangling blocker name gets its own node so the error is VISIBLE.
+                const ghost = `missing${lines.length}`;
+                lines.push(`  ${ghost}["${escapeLabel(blocker)} ?"]`);
+                lines.push(`  ${ghost} -.-> ${wayfinderNodeId(index)}`);
+                continue;
+            }
+            lines.push(`  ${wayfinderNodeId(from)} --> ${wayfinderNodeId(index)}`);
+        }
+    }
+    if (map.destination) {
+        const dest = `dest(["${escapeLabel(map.destination)}"])`;
+        lines.push(`  ${dest}`);
+        // Every ticket nothing depends on feeds the destination — the map's
+        // remaining route at a glance.
+        const blockedNames = new Set(tickets.flatMap((ticket) => ticket.blockedBy));
+        for (const [index, ticket] of tickets.entries()) {
+            if (ticket.state === "out-of-scope")
+                continue;
+            if (!blockedNames.has(ticket.name)) {
+                lines.push(`  ${wayfinderNodeId(index)} --> dest`);
+            }
+        }
+    }
+    // States as classes; the renderer resolves classDef props over its theme.
+    // Each state gets a DISTINCT stroke so the four read apart on screen — the
+    // same tones PlanHill assigns the same buckets, so hill and map speak one
+    // palette. Frontier and claimed differ by color, not only weight; decided
+    // is quiet but named; out of scope sits dashed.
+    lines.push("  classDef claimed stroke:var(--color-accent-amber),stroke-width:2px");
+    lines.push("  classDef frontier stroke:var(--color-brand-blue),stroke-width:2px");
+    lines.push("  classDef outofscope stroke:var(--color-text-tertiary),stroke-dasharray:4 3");
+    lines.push("  classDef decided stroke:var(--color-success)");
+    const byState = (predicate) => tickets.flatMap((ticket, index) => (predicate(ticket) ? [wayfinderNodeId(index)] : []));
+    const claimed = byState((t) => t.state === "claimed");
+    const front = byState((t) => t.onFrontier ?? frontier.has(t.name));
+    const out = byState((t) => t.state === "out-of-scope");
+    const done = byState((t) => t.state === "decided");
+    if (claimed.length > 0)
+        lines.push(`  class ${claimed.join(",")} claimed`);
+    if (front.length > 0)
+        lines.push(`  class ${front.join(",")} frontier`);
+    if (out.length > 0)
+        lines.push(`  class ${out.join(",")} outofscope`);
+    if (done.length > 0)
+        lines.push(`  class ${done.join(",")} decided`);
+    return lines.join("\n");
+}