sfora-cli 0.8.0 → 0.10.0

package/dist/format/blocks/parsers.d.ts

@@ -0,0 +1,105 @@
+import { type WayfinderMap } from "../wayfinder.js";
+import { type BlockDropReason } from "./dropClosure.js";
+import type { StructuredBlockLanguage } from "./structured-block-schema.js";
+export interface TimelineEntry {
+    time?: string;
+    actor: string;
+    message: string;
+    /**
+     * A `state:` line AFTER the header one: a state change, rendered as a
+     * marker row rather than a signed update. `actor` is empty for these.
+     */
+    kind?: "state";
+}
+export interface ChatEntry extends TimelineEntry {
+    role?: string;
+}
+export interface BoardColumn {
+    title: string;
+    items: Array<{
+        state: string;
+        text: string;
+    }>;
+}
+export type SheetAlignment = "left" | "center" | "right";
+export interface SheetData {
+    columns: Array<{
+        label: string;
+        alignment: SheetAlignment;
+    }>;
+    rows: string[][];
+}
+export interface TimelineData {
+    state?: string;
+    entries: TimelineEntry[];
+}
+export declare function cleanLines(source: string): string[];
+/** Bytes a parser did not keep. `line` indexes the block body, 0-based. */
+export interface BlockDrop {
+    line: number;
+    /** The dropped text, trimmed. Empty for a blank line. */
+    text: string;
+    reason: BlockDropReason;
+}
+/**
+ * What a parse produced and what it cost. `consumed` and the whole-line drops
+ * partition the body's lines exactly — that is the closure the fixture suite
+ * asserts, and the reason a parser can no longer quietly widen what it ignores.
+ */
+export interface BlockAccounting<T> {
+    data: T | null;
+    /** Body line indices that reached the rendered block, ascending. */
+    consumed: number[];
+    drops: BlockDrop[];
+}
+export declare function parseTimelineWithAccounting(source: string): BlockAccounting<TimelineData>;
+export declare function parseTimeline(source: string): TimelineData | null;
+/**
+ * True for a line parseBoard keeps: a column heading or a card. A convenience
+ * for callers holding one line — the parser's own accounting is what lint and
+ * the closure suite read, so this is never the second opinion.
+ */
+export declare function isBoardLine(line: string): boolean;
+export declare function parseBoardWithAccounting(source: string): BlockAccounting<BoardColumn[]>;
+export declare function parseBoard(source: string): BoardColumn[] | null;
+export declare function parseChatWithAccounting(source: string): BlockAccounting<ChatEntry[]>;
+export declare function parseChat(source: string): ChatEntry[] | null;
+/**
+ * True for a line parseSheet reads as a table row. GFM makes the outer pipes
+ * optional, so the test is "carries a pipe that would split it" — an escaped
+ * or code-spanned pipe is content, not structure.
+ */
+export declare function isSheetRow(line: string): boolean;
+export declare function parseSheetWithAccounting(source: string): BlockAccounting<SheetData>;
+export declare function parseSheet(source: string): SheetData | null;
+/**
+ * True for a line parseMapBlock keeps: the destination header or a ticket in
+ * the wayfinder line grammar. Same standing as {@link isBoardLine} — a
+ * convenience, not the authority.
+ */
+export declare function isMapLine(line: string): boolean;
+/**
+ * Parse a ```map block: an optional `destination:` header, then tickets in
+ * the wayfinder line grammar (`- [~] Name (type) <- Blocker`). Null when no
+ * ticket parses — the renderer's signal to fall back to a visible code fence,
+ * same contract as every other structured block.
+ */
+export declare function parseMapBlockWithAccounting(source: string): BlockAccounting<WayfinderMap>;
+/**
+ * Parse a ```map block: an optional `destination:` header, then tickets in
+ * the wayfinder line grammar (`- [~] Name (type) <- Blocker`). Null when no
+ * ticket parses — the renderer's signal to fall back to a visible code fence,
+ * same contract as every other structured block.
+ */
+export declare function parseMapBlock(source: string): WayfinderMap | null;
+/**
+ * Parse a fence body as the block its language names, with the ledger. The
+ * one door lint and the closure suite use, so neither carries its own table of
+ * which parser reads which language.
+ */
+export declare function parseStructuredBlock(language: StructuredBlockLanguage, source: string): BlockAccounting<unknown>;
+/**
+ * Body line indices whose bytes did not survive the parse at all. Partial
+ * drops are excluded by construction — their line rendered.
+ */
+export declare function droppedLineNumbers(accounting: BlockAccounting<unknown>): number[];

package/dist/format/blocks/parsers.js

@@ -0,0 +1,442 @@
+// 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).
+// Parsers for sfora's structured fenced blocks (```status / ```board / ```chat
+// / ```sheet). Pure string -> data: no React, no DOM, no Convex. The renderer
+// (src/components/editor/markdown-structured-block.tsx) imports these and only
+// owns the presentation; the CLI, the agent fs, and tests can read the same
+// blocks without pulling in the editor.
+//
+// Every parser returns `null` when the source doesn't look like its block, which
+// is the renderer's signal to fall back to a plain code fence. That contract is
+// load-bearing — a malformed block must stay visible and copyable, never vanish.
+//
+// Each parser also has a `…WithAccounting` twin that reports which lines it
+// read and which it dropped. Those are the real implementations; the plain
+// parsers are one-line wrappers that keep the data and discard the ledger, so
+// the accounting cannot drift from the parse — it IS the parse. `blocks/
+// dropClosure.ts` adjudicates every reason a drop can carry, and lint reads
+// the drops instead of re-deriving them from a second copy of the grammar.
+import { codeSpanMask } from "../lineGeometry.js";
+import { parseWayfinderTickets, } from "../wayfinder.js";
+import { isWholeLineDrop } from "./dropClosure.js";
+export function cleanLines(source) {
+    return source
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+/** Content lines, and the blank-line drops that sit between them. */
+function bodyLines(source) {
+    const lines = [];
+    const blanks = [];
+    source.split(/\r?\n/).forEach((raw, line) => {
+        const text = raw.trim();
+        if (text === "")
+            blanks.push({ line, text: "", reason: "blank-line" });
+        else
+            lines.push({ line, text });
+    });
+    return { lines, blanks };
+}
+const byLine = (a, b) => a.line - b.line;
+/**
+ * Close one parse's books.
+ *
+ * A parser that returned null rendered nothing, so nothing was consumed and
+ * every content line is a `block-unread` drop — the bytes are still on screen
+ * inside the fallback code fence, which is what that verdict says. Partial
+ * drops are discarded along with the parse that produced them: there is no
+ * half-lost line when the whole block was never read.
+ */
+function settle(lines, blanks, data, consumed, drops) {
+    if (data === null) {
+        const unread = lines.map((line) => ({
+            line: line.line,
+            text: line.text,
+            reason: "block-unread",
+        }));
+        return { data: null, consumed: [], drops: [...blanks, ...unread].sort(byLine) };
+    }
+    return {
+        data,
+        consumed: [...consumed].sort((a, b) => a - b),
+        drops: [...blanks, ...drops].sort(byLine),
+    };
+}
+/** The status block's header line. Only the first one is the block's state. */
+const STATE_LINE = /^state:\s*(\S.*)$/i;
+/** The `-` / `*` a status or chat entry may be written with. */
+const ENTRY_BULLET = /^([-*])\s+/;
+const TIMELINE_ENTRY = /^(?:(\d{1,2}:\d{2}|\d{4}-\d{2}-\d{2}T\S+)\s+)?@?([^:]+):\s*(.+)$/;
+export function parseTimelineWithAccounting(source) {
+    const { lines, blanks } = bodyLines(source);
+    const consumed = [];
+    const drops = [];
+    const entries = [];
+    const stateIndex = lines.findIndex((line) => STATE_LINE.test(line.text));
+    const stateLine = stateIndex >= 0 ? STATE_LINE.exec(lines[stateIndex].text) : null;
+    lines.forEach((line, index) => {
+        // The FIRST `state:` line is the block's header. Any later one is a
+        // state CHANGE and stays visible as a marker entry in the timeline —
+        // neither an update signed by an actor called "state" (the old bug)
+        // nor silently dropped (the old fix): the reader shows every line the
+        // author wrote.
+        const asState = STATE_LINE.exec(line.text);
+        if (asState) {
+            consumed.push(line.line);
+            if (index !== stateIndex) {
+                entries.push({ actor: "", message: asState[1].trim(), kind: "state" });
+            }
+            return;
+        }
+        const bullet = ENTRY_BULLET.exec(line.text);
+        const value = line.text.replace(ENTRY_BULLET, "");
+        const match = TIMELINE_ENTRY.exec(value);
+        if (!match) {
+            drops.push({
+                line: line.line,
+                text: line.text,
+                reason: "status:unsigned-line",
+            });
+            return;
+        }
+        consumed.push(line.line);
+        if (bullet) {
+            drops.push({
+                line: line.line,
+                text: bullet[1],
+                reason: "entry-bullet-marker",
+            });
+        }
+        entries.push({
+            time: match[1],
+            actor: match[2].trim(),
+            message: match[3].trim(),
+        });
+    });
+    const data = !stateLine && entries.length === 0
+        ? null
+        : { state: stateLine?.[1].trim(), entries };
+    return settle(lines, blanks, data, consumed, drops);
+}
+export function parseTimeline(source) {
+    return parseTimelineWithAccounting(source).data;
+}
+const BOARD_HEADING = /^#{1,6}\s+(.+)$/;
+const BOARD_ITEM = /^[-*]\s+(?:\[([^\]])\]\s+)?(.+)$/;
+/**
+ * True for a line parseBoard keeps: a column heading or a card. A convenience
+ * for callers holding one line — the parser's own accounting is what lint and
+ * the closure suite read, so this is never the second opinion.
+ */
+export function isBoardLine(line) {
+    const text = line.trim();
+    return BOARD_HEADING.test(text) || BOARD_ITEM.test(text);
+}
+export function parseBoardWithAccounting(source) {
+    const { lines, blanks } = bodyLines(source);
+    const consumed = [];
+    const drops = [];
+    const columns = [];
+    let current = null;
+    for (const line of lines) {
+        const heading = BOARD_HEADING.exec(line.text);
+        if (heading) {
+            consumed.push(line.line);
+            current = { title: heading[1].trim(), items: [] };
+            columns.push(current);
+            continue;
+        }
+        const item = BOARD_ITEM.exec(line.text);
+        if (item) {
+            consumed.push(line.line);
+            current ??= { title: "Items", items: [] };
+            if (!columns.includes(current))
+                columns.push(current);
+            current.items.push({
+                state: item[1]?.trim() ?? "",
+                text: item[2].trim(),
+            });
+            continue;
+        }
+        drops.push({
+            line: line.line,
+            text: line.text,
+            reason: "board:unparsed-line",
+        });
+    }
+    const data = columns.some((column) => column.items.length > 0)
+        ? columns
+        : null;
+    return settle(lines, blanks, data, consumed, drops);
+}
+export function parseBoard(source) {
+    return parseBoardWithAccounting(source).data;
+}
+// The clock-time alternative has to lead: without it the lazy actor group
+// stops at the hour's colon and "09:04 @mara: hi" is signed by "09".
+const CHAT_ENTRY = /^(?:(\d{1,2}:\d{2}|\d{4}-\d{2}-\d{2}T\S+)\s+)?@?(.+?)(?:\s+\(([^)]+)\))?\s*:\s*(.+)$/;
+export function parseChatWithAccounting(source) {
+    const { lines, blanks } = bodyLines(source);
+    const consumed = [];
+    const drops = [];
+    const entries = [];
+    for (const line of lines) {
+        const bullet = ENTRY_BULLET.exec(line.text);
+        const value = line.text.replace(ENTRY_BULLET, "");
+        const match = CHAT_ENTRY.exec(value);
+        if (!match?.[2].trim() || !match[4].trim()) {
+            drops.push({
+                line: line.line,
+                text: line.text,
+                reason: "chat:unparsed-line",
+            });
+            continue;
+        }
+        consumed.push(line.line);
+        if (bullet) {
+            drops.push({
+                line: line.line,
+                text: bullet[1],
+                reason: "entry-bullet-marker",
+            });
+        }
+        entries.push({
+            time: match[1],
+            actor: match[2].trim(),
+            role: match[3]?.trim(),
+            message: match[4].trim(),
+        });
+    }
+    return settle(lines, blanks, entries.length > 0 ? entries : null, consumed, drops);
+}
+export function parseChat(source) {
+    return parseChatWithAccounting(source).data;
+}
+// GFM's delimiter cell: optional colons around one or more dashes. Demanding
+// three would render `| - | - |` as a row of literal dashes.
+const SHEET_SEPARATOR_CELL = /^:?-+:?$/;
+// The escapable set, per CommonMark. A backslash before anything else is a
+// literal backslash — Windows paths and regexes must survive intact.
+const ASCII_PUNCTUATION = /[!-/:-@[-`{-~]/;
+/** True when the character at `index` is preceded by an odd run of backslashes. */
+function isEscapedAt(text, index) {
+    let slashes = 0;
+    for (let i = index - 1; i >= 0 && text[i] === "\\"; i--)
+        slashes++;
+    return slashes % 2 === 1;
+}
+/**
+ * True for a line parseSheet reads as a table row. GFM makes the outer pipes
+ * optional, so the test is "carries a pipe that would split it" — an escaped
+ * or code-spanned pipe is content, not structure.
+ */
+export function isSheetRow(line) {
+    const text = line.trim();
+    const inCode = codeSpanMask(text);
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "|" && !inCode[i] && !isEscapedAt(text, i))
+            return true;
+    }
+    return false;
+}
+function sheetCells(line) {
+    let content = line.trim();
+    if (content.startsWith("|"))
+        content = content.slice(1);
+    if (content.endsWith("|") && !isEscapedAt(content, content.length - 1)) {
+        content = content.slice(0, -1);
+    }
+    const inCode = codeSpanMask(content);
+    const result = [];
+    let cell = "";
+    for (let i = 0; i < content.length; i++) {
+        const character = content[i];
+        if (character === "\\") {
+            const next = content[i + 1];
+            // GFM resolves `\|` before inline parsing, so it is a literal pipe even
+            // inside a code span — that is the only way to write one there. Every
+            // other escape belongs to inline parsing and stops at a code span.
+            if (next === "|" ||
+                (next !== undefined && !inCode[i] && ASCII_PUNCTUATION.test(next))) {
+                cell += next;
+                i++;
+                continue;
+            }
+            cell += character;
+            continue;
+        }
+        if (character === "|" && !inCode[i]) {
+            result.push(cell.trim());
+            cell = "";
+            continue;
+        }
+        cell += character;
+    }
+    result.push(cell.trim());
+    return result;
+}
+export function parseSheetWithAccounting(source) {
+    const { lines, blanks } = bodyLines(source);
+    const consumed = [];
+    const drops = [];
+    const rowLines = [];
+    for (const line of lines) {
+        if (isSheetRow(line.text))
+            rowLines.push(line);
+        else {
+            drops.push({
+                line: line.line,
+                text: line.text,
+                reason: "sheet:non-row-line",
+            });
+        }
+    }
+    if (rowLines.length < 2)
+        return settle(lines, blanks, null, [], drops);
+    const headers = sheetCells(rowLines[0].text);
+    const separator = sheetCells(rowLines[1].text);
+    const hasSeparator = separator.length === headers.length &&
+        separator.every((cell) => SHEET_SEPARATOR_CELL.test(cell));
+    const dataLines = rowLines.slice(hasSeparator ? 2 : 1);
+    const rows = dataLines.map((line) => sheetCells(line.text));
+    if (headers.length === 0 || rows.length === 0) {
+        return settle(lines, blanks, null, [], drops);
+    }
+    consumed.push(rowLines[0].line);
+    if (hasSeparator) {
+        // The delimiter row is alignment, not data: read into every column below
+        // and gone from the grid, which is why it signs as retained-by-capture.
+        drops.push({
+            line: rowLines[1].line,
+            text: rowLines[1].text,
+            reason: "sheet:delimiter-row",
+        });
+    }
+    const normalizedRows = rows.map((row, index) => {
+        const line = dataLines[index];
+        consumed.push(line.line);
+        if (row.length > headers.length) {
+            drops.push({
+                line: line.line,
+                text: row.slice(headers.length).join(" | "),
+                reason: "sheet:excess-cells",
+            });
+        }
+        return headers.map((_, column) => row[column] ?? "");
+    });
+    const columns = headers.map((header, index) => {
+        const marker = hasSeparator ? separator[index] : "";
+        const authoredAlignment = marker.startsWith(":") && marker.endsWith(":")
+            ? "center"
+            : marker.endsWith(":")
+                ? "right"
+                : marker.startsWith(":")
+                    ? "left"
+                    : null;
+        const values = normalizedRows.map((row) => row[index]).filter(Boolean);
+        const numericValues = values.filter((value) => /^(?:[-+]?[$€£]?\s*\d[\d,.]*(?:%|[KMBT])?|N\/?A|—)$/i.test(value));
+        // First column is the row label, so it always reads left; elsewhere a
+        // majority of numeric cells wins right alignment when the source didn't say.
+        const inferredAlignment = index > 0 &&
+            numericValues.length > 0 &&
+            numericValues.length >= Math.ceil(values.length / 2)
+            ? "right"
+            : "left";
+        return {
+            label: header || `Column ${index + 1}`,
+            alignment: index === 0
+                ? "left"
+                : (authoredAlignment ?? inferredAlignment),
+        };
+    });
+    return settle(lines, blanks, { columns, rows: normalizedRows }, consumed, drops);
+}
+export function parseSheet(source) {
+    return parseSheetWithAccounting(source).data;
+}
+// ── The map block ───────────────────────────────────────────────────
+/** The map block's header line, mirroring the status block's `state:`. */
+const MAP_DESTINATION_LINE = /^destination:\s*(\S.*)$/i;
+/**
+ * True for a line parseMapBlock keeps: the destination header or a ticket in
+ * the wayfinder line grammar. Same standing as {@link isBoardLine} — a
+ * convenience, not the authority.
+ */
+export function isMapLine(line) {
+    const text = line.trim();
+    return (MAP_DESTINATION_LINE.test(text) ||
+        parseWayfinderTickets(text).length === 1);
+}
+/**
+ * Parse a ```map block: an optional `destination:` header, then tickets in
+ * the wayfinder line grammar (`- [~] Name (type) <- Blocker`). Null when no
+ * ticket parses — the renderer's signal to fall back to a visible code fence,
+ * same contract as every other structured block.
+ */
+export function parseMapBlockWithAccounting(source) {
+    const { lines, blanks } = bodyLines(source);
+    const consumed = [];
+    const drops = [];
+    const tickets = [];
+    let destination;
+    for (const line of lines) {
+        const header = MAP_DESTINATION_LINE.exec(line.text);
+        // Only the first destination line is the header; a second one is not a
+        // ticket either, so it falls through to the drop below.
+        if (header && destination === undefined) {
+            destination = header[1].trim();
+            consumed.push(line.line);
+            continue;
+        }
+        // The ticket grammar is line-local and stateless, so reading it a line at
+        // a time gives exactly the list a whole-section read would.
+        const parsed = parseWayfinderTickets(line.text);
+        if (parsed.length === 1) {
+            consumed.push(line.line);
+            tickets.push(parsed[0]);
+            continue;
+        }
+        drops.push({
+            line: line.line,
+            text: line.text,
+            reason: "map:unparsed-line",
+        });
+    }
+    const data = tickets.length === 0 ? null : { destination, tickets };
+    return settle(lines, blanks, data, consumed, drops);
+}
+/**
+ * Parse a ```map block: an optional `destination:` header, then tickets in
+ * the wayfinder line grammar (`- [~] Name (type) <- Blocker`). Null when no
+ * ticket parses — the renderer's signal to fall back to a visible code fence,
+ * same contract as every other structured block.
+ */
+export function parseMapBlock(source) {
+    return parseMapBlockWithAccounting(source).data;
+}
+/** Every structured block's parser, by language. */
+const ACCOUNTING_PARSERS = {
+    status: parseTimelineWithAccounting,
+    board: parseBoardWithAccounting,
+    chat: parseChatWithAccounting,
+    sheet: parseSheetWithAccounting,
+    map: parseMapBlockWithAccounting,
+};
+/**
+ * Parse a fence body as the block its language names, with the ledger. The
+ * one door lint and the closure suite use, so neither carries its own table of
+ * which parser reads which language.
+ */
+export function parseStructuredBlock(language, source) {
+    return ACCOUNTING_PARSERS[language](source);
+}
+/**
+ * Body line indices whose bytes did not survive the parse at all. Partial
+ * drops are excluded by construction — their line rendered.
+ */
+export function droppedLineNumbers(accounting) {
+    return accounting.drops
+        .filter((drop) => isWholeLineDrop(drop.reason))
+        .map((drop) => drop.line);
+}

package/dist/format/blocks/structured-block-schema.d.ts

@@ -0,0 +1,8 @@
+export declare const STRUCTURED_BLOCK_LANGUAGES: readonly ["status", "board", "chat", "sheet", "map"];
+export declare const RICH_BLOCK_LANGUAGES: readonly ["mermaid", "status", "board", "chat", "sheet", "map"];
+export type StructuredBlockLanguage = (typeof STRUCTURED_BLOCK_LANGUAGES)[number];
+export type RichBlockLanguage = (typeof RICH_BLOCK_LANGUAGES)[number];
+export declare const STRUCTURED_BLOCK_STARTERS: Record<StructuredBlockLanguage, string>;
+export declare const RICH_BLOCK_STARTERS: Record<RichBlockLanguage, string>;
+export declare function isStructuredMarkdownLanguage(language: string): language is StructuredBlockLanguage;
+export declare function isRichMarkdownLanguage(language: string): language is RichBlockLanguage;

package/dist/format/blocks/structured-block-schema.js

@@ -0,0 +1,30 @@
+// 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).
+export const STRUCTURED_BLOCK_LANGUAGES = [
+    "status",
+    "board",
+    "chat",
+    "sheet",
+    "map",
+];
+export const RICH_BLOCK_LANGUAGES = [
+    "mermaid",
+    ...STRUCTURED_BLOCK_LANGUAGES,
+];
+export const STRUCTURED_BLOCK_STARTERS = {
+    status: "state: building\n- @you: Add an update",
+    board: "## In progress\n- [ ] Describe the active work\n\n## Review\n- [ ] Add a review item\n\n## Done\n- [x] Capture completed work",
+    chat: "- @you: Add a message",
+    sheet: "| Field | Value |\n| --- | --- |\n| Status | Building |\n| Owner | You |",
+    map: "destination: What shipping looks like\n- [x] Name the destination\n- [ ] Chart the first question <- Name the destination",
+};
+export const RICH_BLOCK_STARTERS = {
+    mermaid: "flowchart LR\n  Source[Markdown] --> Result[Rendered block]",
+    ...STRUCTURED_BLOCK_STARTERS,
+};
+export function isStructuredMarkdownLanguage(language) {
+    return STRUCTURED_BLOCK_LANGUAGES.includes(language.toLowerCase());
+}
+export function isRichMarkdownLanguage(language) {
+    return RICH_BLOCK_LANGUAGES.includes(language.toLowerCase());
+}

package/dist/format/callout.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Callouts — the GFM alert grammar, `> [!NOTE]`.
+ *
+ * A callout is an ordinary blockquote whose first line is a type marker. That
+ * is the whole trick: every reader that does not know about callouts still
+ * sees quoted prose, and the bytes stay a blockquote on disk. There is no new
+ * fence, no new frontmatter key, nothing an agent has to learn.
+ *
+ *     > [!WARNING] Ship blocker
+ *     > The migration has to run before the deploy.
+ *
+ * Five types, matching GitHub: note, tip, important, warning, caution. The
+ * marker is written uppercase and read case-insensitively, because people type
+ * `[!note]` and pasted GitHub markdown says `[!NOTE]` — both are the same
+ * callout, and the first save canonicalizes.
+ *
+ * Pure functions over lines: no DOM, no ProseMirror, no React. The reader
+ * (`src/lib/utils/markdown.ts`), the Tiptap node
+ * (`src/components/editor/extensions/callout.ts`), and the CLI all read the
+ * grammar from here so they cannot disagree about what a callout is.
+ */
+export declare const CALLOUT_TYPES: readonly ["note", "tip", "important", "warning", "caution"];
+export type CalloutType = (typeof CALLOUT_TYPES)[number];
+export interface Callout {
+    type: CalloutType;
+    /** Custom heading on the marker line. Absent means "use the type's label". */
+    title?: string;
+    /** Everything below the marker line, quote markers already removed. */
+    body: string;
+}
+/** The marker as written: uppercase, so `[!NOTE]` is what lands on disk. */
+export declare function calloutMarker(type: CalloutType): string;
+export declare function isCalloutType(value: string): value is CalloutType;
+/**
+ * Drop one level of `>` quoting. A single space after the marker is part of
+ * the marker, not the content — `>  indented` keeps one space.
+ */
+export declare function stripQuoteMarkers(lines: readonly string[]): string[];
+/**
+ * Read a callout out of the lines of a blockquote.
+ *
+ * Accepts either raw source lines (`> [!NOTE]`) or lines whose quote markers a
+ * caller has already stripped (`[!NOTE]`) — the reader strips as it scans, the
+ * editor does not. The two are told apart by looking at the block as a whole:
+ * if every non-blank line is quoted, one level comes off. That way a callout
+ * whose body contains a nested quote survives either way round.
+ *
+ * Returns null for anything that is not a callout, which is the signal to
+ * render an ordinary blockquote.
+ */
+export declare function parseCallout(blockquoteLines: readonly string[]): Callout | null;
+/**
+ * Index, within the same lines, of the callout body's first line — or -1 when
+ * the block is not a callout. A caller that re-parses `body` as markdown needs
+ * it to map a node back to the document line it came from; the reader joins
+ * its checkboxes to the document's line scan that way. Kept off `Callout`
+ * itself because the type is a value the editor and CLI construct by hand.
+ */
+export declare function calloutBodyLine(blockquoteLines: readonly string[]): number;
+/**
+ * Write a callout back out. The inverse of `parseCallout` on the canonical
+ * form, and the only place the serialized shape is spelled: one blockquote,
+ * marker line first, body quoted line by line. A blank body line is a bare
+ * `>` — no trailing space, so the bytes survive editors that strip them.
+ */
+export declare function calloutToMarkdown(callout: Callout): string;