sfora-cli 0.10.0 → 0.12.0

package/dist/format/blockSplice.d.ts

@@ -0,0 +1,135 @@
+/**
+ * One block of a source string: its byte range, and its identity.
+ *
+ * `key` is what "unchanged" means. Two blocks with the same key are the same
+ * block for splice purposes and the old one's bytes win. A caller that keys by
+ * raw text gets a byte-exact diff (and no canonicalization softening at all);
+ * a caller that keys by a position-stripped parse gets the semantic diff this
+ * module exists to serve.
+ */
+export interface SourceBlock {
+    /** Byte offset of the block's first byte. */
+    start: number;
+    /** One past the block's last byte. */
+    end: number;
+    /** Identity under whatever equality the caller decided on. */
+    key: string;
+}
+/** Why a splice gave up and handed back the new source whole. */
+export type BlockSpliceFallback = "none"
+/** One side has no blocks at all — there is nothing to preserve or to keep. */
+ | "no-blocks"
+/** A block list was out of order, overlapping, or out of bounds. */
+ | "unusable-blocks";
+export interface BlockSpliceResult {
+    /** The bytes to store. */
+    source: string;
+    /** Old blocks that kept their bytes. */
+    kept: number;
+    /** Blocks written from the new source. */
+    rewritten: number;
+    /** Set when the result is just `newSource`. */
+    fallback: BlockSpliceFallback;
+}
+/**
+ * Above this many DP cells the middle region is treated as one changed run
+ * instead of being aligned properly.
+ *
+ * The prefix/suffix trim below already handles the shape a real edit has — one
+ * changed region, everything before and after it identical — in linear time,
+ * so the quadratic pass only ever runs on a genuinely scattered diff. 250k
+ * cells is a 500-block-by-500-block middle, which is a document nobody has;
+ * past it the splice degrades to exactly what open-knowledge's
+ * `map-driven-splice.ts` does at every size (one over-wide contiguous splice),
+ * which is correct, merely less preserving.
+ *
+ * Exported so the test that pins the boundary can build the block lists either
+ * side of it from this number rather than from a second copy of it: a budget
+ * quietly raised past a hard-coded 500×500 would leave a test that still
+ * passes while asserting nothing about the fallback.
+ */
+export declare const ALIGNMENT_CELL_BUDGET = 250000;
+/**
+ * A run of blocks that is either kept from old or written from new.
+ *
+ * `kept: true` means every block in the range keyed identically on both sides,
+ * one for one, so `oldTo - oldFrom === newTo - newFrom` and the i-th old block
+ * IS the i-th new block. `kept: false` means the two ranges are the region the
+ * alignment could not explain: they may be different lengths, and nothing here
+ * says which old block became which new one — that judgement belongs to the
+ * consumer, because the splice does not need it and a rebinding ledger does.
+ */
+export interface BlockRun {
+    kept: boolean;
+    /** Half-open index range into the old block list. */
+    oldFrom: number;
+    oldTo: number;
+    /** Half-open index range into the new block list. */
+    newFrom: number;
+    newTo: number;
+}
+/**
+ * How much of the correspondence was actually computed.
+ *
+ * `"exact"` is a real alignment: every block that survives unchanged is inside
+ * a kept run. `"budget"` says the middle region was past
+ * `ALIGNMENT_CELL_BUDGET` and was handed back as one changed run without being
+ * looked at, so blocks that did survive are sitting inside it unrecognised.
+ * The splice does not care — an over-wide changed run is merely less
+ * preserving — but a consumer that reads a changed run as "these blocks were
+ * edited" would be stating something the alignment never checked, so the
+ * degradation is reported rather than inferred from the run shapes.
+ */
+export type BlockAlignmentQuality = "exact" | "budget";
+/** The old↔new block correspondence, and how far it was actually worked out. */
+export interface BlockAlignment {
+    /**
+     * Alternating kept/changed runs covering both lists end to end: every index
+     * of `oldBlocks` appears in exactly one run's old range, every index of
+     * `newBlocks` in exactly one run's new range, both in ascending order.
+     */
+    runs: BlockRun[];
+    quality: BlockAlignmentQuality;
+}
+/**
+ * Assemble the bytes to store from `oldSource` and `newSource`.
+ *
+ * The contract, in order of how much it matters:
+ *
+ * 1. If every key matches, the result is `oldSource` byte-for-byte. Not
+ *    "equivalent to" — identical, including its trailing newline or lack of
+ *    one. A save that changed nothing must reach the store as no change at
+ *    all, or the whole exercise is decorative.
+ * 2. A block whose key changed contributes its NEW bytes, together with the
+ *    gap bytes on either side of it, because a new or deleted block has to be
+ *    able to bring its own blank lines.
+ * 3. A block whose key did not change contributes its OLD bytes, and so do
+ *    the gaps between two such blocks.
+ * 4. The bytes outside every block — leading whitespace, the trailing
+ *    newline — belong to no block, so they follow the block nearest them: old
+ *    if that first/last block was kept, new if it was rewritten. Kept-at-the-
+ *    edge is what makes rule 1 exact; rewritten-at-the-edge is what lets a
+ *    document that really was replaced arrive with its own final newline
+ *    instead of inheriting the absence of one.
+ */
+export declare function spliceBlocks(oldSource: string, newSource: string, oldBlocks: readonly SourceBlock[], newBlocks: readonly SourceBlock[]): BlockSpliceResult;
+/**
+ * Split both block lists into alternating kept/changed runs — the old↔new
+ * correspondence, on its own, with no bytes involved.
+ *
+ * Common prefix and suffix first — that is the entire diff for a normal edit
+ * and it costs one pass. What is left in the middle gets a longest-common-
+ * subsequence alignment so that two edits with untouched blocks between them
+ * keep those blocks' bytes; open-knowledge's version collapses that case into
+ * one over-wide splice, and it is the one thing here worth doing better than
+ * the reference, because "find and replace in three places" is an ordinary
+ * afternoon and it should not rewrite the paragraphs in between.
+ *
+ * Public because it is most of a rebinding ledger and it already runs on every
+ * write. `spliceBlocks` reads it for bytes; a caller that has derived an
+ * identity from the same keys reads it for what became what. Only `key` is
+ * consulted, so a caller holding keys and no offsets can ask this directly —
+ * the offset sanity `spliceBlocks` insists on is a slicing concern, not an
+ * alignment one.
+ */
+export declare function alignBlockRuns(oldBlocks: readonly SourceBlock[], newBlocks: readonly SourceBlock[]): BlockAlignment;

package/dist/format/blockSplice.js

@@ -0,0 +1,330 @@
+// 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 block-aligned splice: write only the blocks that changed.
+//
+// Every save in sfora goes through a serializer, and a serializer has
+// opinions — `*em*` becomes `_em_`, a setext heading becomes an ATX one, a
+// table's padding is re-laid. Those opinions are correct for the block the
+// author just edited and pure vandalism everywhere else: change one word in
+// paragraph nine and the naive write path hands the store a document in which
+// all forty blocks have been re-spelled. The author's diff is unreadable, the
+// activity trail lies about what changed, and every byte-form the serializer
+// cannot represent is gone for good.
+//
+// This module is the fix, and it is deliberately the dumbest possible one.
+// It knows nothing about serializers, editors or markdown syntax. It takes
+// two strings and two lists of BLOCKS — byte ranges plus an identity key —
+// and returns a third string assembled from old bytes wherever the keys agree
+// and new bytes wherever they do not. The key is where the intelligence
+// lives, and it lives in the caller: `blockSpliceMdast.ts` derives one by
+// parsing and stripping positions, so `*em*` and `_em_` key the same and the
+// OLD bytes survive. Nothing in this file can tell the difference, which is
+// exactly why it will survive the serializer swap wave 2 is heading for.
+//
+// There are two exits. `spliceBlocks` is the one the write paths call and
+// returns bytes. `alignBlockRuns` is the correspondence underneath it —
+// which old block became which new one — returned on its own, because that
+// question has a second consumer: a document's derived block ids change when
+// their blocks change, and the ledger that carries an anchor across an edit
+// needs exactly this answer and nothing else from this file. It was already
+// being computed on every save and thrown away.
+//
+// Zero dependencies, no parser, no I/O — it ships in the CLI.
+/**
+ * Above this many DP cells the middle region is treated as one changed run
+ * instead of being aligned properly.
+ *
+ * The prefix/suffix trim below already handles the shape a real edit has — one
+ * changed region, everything before and after it identical — in linear time,
+ * so the quadratic pass only ever runs on a genuinely scattered diff. 250k
+ * cells is a 500-block-by-500-block middle, which is a document nobody has;
+ * past it the splice degrades to exactly what open-knowledge's
+ * `map-driven-splice.ts` does at every size (one over-wide contiguous splice),
+ * which is correct, merely less preserving.
+ *
+ * Exported so the test that pins the boundary can build the block lists either
+ * side of it from this number rather than from a second copy of it: a budget
+ * quietly raised past a hard-coded 500×500 would leave a test that still
+ * passes while asserting nothing about the fallback.
+ */
+export const ALIGNMENT_CELL_BUDGET = 250_000;
+/**
+ * Assemble the bytes to store from `oldSource` and `newSource`.
+ *
+ * The contract, in order of how much it matters:
+ *
+ * 1. If every key matches, the result is `oldSource` byte-for-byte. Not
+ *    "equivalent to" — identical, including its trailing newline or lack of
+ *    one. A save that changed nothing must reach the store as no change at
+ *    all, or the whole exercise is decorative.
+ * 2. A block whose key changed contributes its NEW bytes, together with the
+ *    gap bytes on either side of it, because a new or deleted block has to be
+ *    able to bring its own blank lines.
+ * 3. A block whose key did not change contributes its OLD bytes, and so do
+ *    the gaps between two such blocks.
+ * 4. The bytes outside every block — leading whitespace, the trailing
+ *    newline — belong to no block, so they follow the block nearest them: old
+ *    if that first/last block was kept, new if it was rewritten. Kept-at-the-
+ *    edge is what makes rule 1 exact; rewritten-at-the-edge is what lets a
+ *    document that really was replaced arrive with its own final newline
+ *    instead of inheriting the absence of one.
+ */
+export function spliceBlocks(oldSource, newSource, oldBlocks, newBlocks) {
+    if (oldBlocks.length === 0 || newBlocks.length === 0) {
+        return { source: newSource, kept: 0, rewritten: 0, fallback: "no-blocks" };
+    }
+    if (!blocksAreUsable(oldBlocks, oldSource.length) ||
+        !blocksAreUsable(newBlocks, newSource.length)) {
+        return {
+            source: newSource,
+            kept: 0,
+            rewritten: 0,
+            fallback: "unusable-blocks",
+        };
+    }
+    const { runs } = alignBlockRuns(oldBlocks, newBlocks);
+    const parts = [];
+    // The head: everything before the first block, from whichever side owns it.
+    parts.push(runs[0].kept
+        ? oldSource.slice(0, oldBlocks[0].start)
+        : newSource.slice(0, newBlocks[0].start));
+    let kept = 0;
+    let rewritten = 0;
+    for (const run of runs) {
+        if (run.kept) {
+            parts.push(oldSource.slice(oldBlocks[run.oldFrom].start, oldBlocks[run.oldTo - 1].end));
+            kept += run.oldTo - run.oldFrom;
+            continue;
+        }
+        // A changed run owns the gaps on both sides of it in the NEW source: the
+        // bytes from the end of the last kept new block to the start of the next
+        // one. At an edge of the document it stops at the edge block's own
+        // boundary; the head/tail beyond it is added once, outside this loop,
+        // under rule 4.
+        const from = run.newFrom > 0 ? newBlocks[run.newFrom - 1].end : newBlocks[0].start;
+        const to = run.newTo < newBlocks.length
+            ? newBlocks[run.newTo].start
+            : newBlocks[newBlocks.length - 1].end;
+        parts.push(newSource.slice(from, to));
+        rewritten += run.newTo - run.newFrom;
+    }
+    // The tail: everything after the last block, from whichever side owns it.
+    parts.push(runs[runs.length - 1].kept
+        ? oldSource.slice(oldBlocks[oldBlocks.length - 1].end)
+        : newSource.slice(newBlocks[newBlocks.length - 1].end));
+    return { source: parts.join(""), kept, rewritten, fallback: "none" };
+}
+/**
+ * Offsets have to be ascending, non-overlapping and inside the string, because
+ * the assembly above slices without re-checking and a bad list would silently
+ * produce scrambled bytes rather than an error. Callers feed these from a
+ * parser; a parser that ever emits a tree whose top-level children overlap is
+ * a bug we would rather see as a whole-document write than as a corrupted one.
+ */
+function blocksAreUsable(blocks, length) {
+    let previousEnd = 0;
+    for (const block of blocks) {
+        if (!Number.isInteger(block.start) || !Number.isInteger(block.end)) {
+            return false;
+        }
+        if (block.start < previousEnd)
+            return false;
+        if (block.end < block.start)
+            return false;
+        if (block.end > length)
+            return false;
+        previousEnd = block.end;
+    }
+    return true;
+}
+/**
+ * Split both block lists into alternating kept/changed runs — the old↔new
+ * correspondence, on its own, with no bytes involved.
+ *
+ * Common prefix and suffix first — that is the entire diff for a normal edit
+ * and it costs one pass. What is left in the middle gets a longest-common-
+ * subsequence alignment so that two edits with untouched blocks between them
+ * keep those blocks' bytes; open-knowledge's version collapses that case into
+ * one over-wide splice, and it is the one thing here worth doing better than
+ * the reference, because "find and replace in three places" is an ordinary
+ * afternoon and it should not rewrite the paragraphs in between.
+ *
+ * Public because it is most of a rebinding ledger and it already runs on every
+ * write. `spliceBlocks` reads it for bytes; a caller that has derived an
+ * identity from the same keys reads it for what became what. Only `key` is
+ * consulted, so a caller holding keys and no offsets can ask this directly —
+ * the offset sanity `spliceBlocks` insists on is a slicing concern, not an
+ * alignment one.
+ */
+export function alignBlockRuns(oldBlocks, newBlocks) {
+    const shorter = Math.min(oldBlocks.length, newBlocks.length);
+    let prefix = 0;
+    while (prefix < shorter && oldBlocks[prefix].key === newBlocks[prefix].key) {
+        prefix++;
+    }
+    let suffix = 0;
+    while (suffix < shorter - prefix &&
+        oldBlocks[oldBlocks.length - 1 - suffix].key ===
+            newBlocks[newBlocks.length - 1 - suffix].key) {
+        suffix++;
+    }
+    const runs = [];
+    if (prefix > 0) {
+        runs.push({ kept: true, oldFrom: 0, oldTo: prefix, newFrom: 0, newTo: prefix });
+    }
+    const oldMid = oldBlocks.slice(prefix, oldBlocks.length - suffix);
+    const newMid = newBlocks.slice(prefix, newBlocks.length - suffix);
+    const middle = alignMiddle(oldMid, newMid);
+    for (const run of middle.runs) {
+        runs.push({
+            kept: run.kept,
+            oldFrom: run.oldFrom + prefix,
+            oldTo: run.oldTo + prefix,
+            newFrom: run.newFrom + prefix,
+            newTo: run.newTo + prefix,
+        });
+    }
+    if (suffix > 0) {
+        runs.push({
+            kept: true,
+            oldFrom: oldBlocks.length - suffix,
+            oldTo: oldBlocks.length,
+            newFrom: newBlocks.length - suffix,
+            newTo: newBlocks.length,
+        });
+    }
+    return { runs: mergeAdjacent(runs), quality: middle.quality };
+}
+/** Runs for the region the prefix/suffix trim could not explain. */
+function alignMiddle(oldMid, newMid) {
+    if (oldMid.length === 0 && newMid.length === 0) {
+        return { runs: [], quality: "exact" };
+    }
+    const whole = [
+        {
+            kept: false,
+            oldFrom: 0,
+            oldTo: oldMid.length,
+            newFrom: 0,
+            newTo: newMid.length,
+        },
+    ];
+    // A pure insertion or deletion in the middle: one side is empty, so there is
+    // nothing to match against and the single changed run IS the exact answer.
+    if (oldMid.length === 0 || newMid.length === 0) {
+        return { runs: whole, quality: "exact" };
+    }
+    // Past the budget the same shape means something weaker — "not looked at" —
+    // and the quality field is the only place that difference is recorded.
+    if (oldMid.length * newMid.length > ALIGNMENT_CELL_BUDGET) {
+        return { runs: whole, quality: "budget" };
+    }
+    return {
+        runs: runsFromPairs(longestCommonSubsequence(oldMid, newMid), oldMid.length, newMid.length),
+        quality: "exact",
+    };
+}
+/**
+ * Index pairs of a longest common subsequence of the two key sequences,
+ * ascending. Plain O(n·m) DP over an Int32Array — the budget above is what
+ * keeps that honest, and the keys are interned to integers first so the inner
+ * loop compares numbers instead of strings.
+ */
+function longestCommonSubsequence(oldMid, newMid) {
+    const ids = new Map();
+    const intern = (key) => {
+        const seen = ids.get(key);
+        if (seen !== undefined)
+            return seen;
+        const id = ids.size;
+        ids.set(key, id);
+        return id;
+    };
+    const a = oldMid.map((block) => intern(block.key));
+    const b = newMid.map((block) => intern(block.key));
+    const width = b.length + 1;
+    const table = new Int32Array((a.length + 1) * width);
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            table[i * width + j] =
+                a[i] === b[j]
+                    ? table[(i + 1) * width + j + 1] + 1
+                    : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+        }
+    }
+    const pairs = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            pairs.push([i, j]);
+            i++;
+            j++;
+        }
+        else if (table[(i + 1) * width + j] >= table[i * width + j + 1]) {
+            i++;
+        }
+        else {
+            j++;
+        }
+    }
+    return pairs;
+}
+/** Turn matched index pairs into the alternating run list. */
+function runsFromPairs(pairs, oldLength, newLength) {
+    const runs = [];
+    let oldAt = 0;
+    let newAt = 0;
+    for (const [oldIndex, newIndex] of pairs) {
+        if (oldIndex > oldAt || newIndex > newAt) {
+            runs.push({
+                kept: false,
+                oldFrom: oldAt,
+                oldTo: oldIndex,
+                newFrom: newAt,
+                newTo: newIndex,
+            });
+        }
+        runs.push({
+            kept: true,
+            oldFrom: oldIndex,
+            oldTo: oldIndex + 1,
+            newFrom: newIndex,
+            newTo: newIndex + 1,
+        });
+        oldAt = oldIndex + 1;
+        newAt = newIndex + 1;
+    }
+    if (oldAt < oldLength || newAt < newLength) {
+        runs.push({
+            kept: false,
+            oldFrom: oldAt,
+            oldTo: oldLength,
+            newFrom: newAt,
+            newTo: newLength,
+        });
+    }
+    return runs;
+}
+/**
+ * Fuse touching runs of the same kind.
+ *
+ * The LCS emits one run per matched block, and the prefix/suffix trim adds its
+ * own on both sides. Left as-is, two adjacent kept runs would each slice from
+ * their own first block's start, which DROPS the gap bytes between them —
+ * blank lines between untouched paragraphs would vanish on every save. Merging
+ * is not tidying; it is what makes rule 3 true.
+ */
+function mergeAdjacent(runs) {
+    const merged = [];
+    for (const run of runs) {
+        const last = merged[merged.length - 1];
+        if (last && last.kept === run.kept) {
+            last.oldTo = run.oldTo;
+            last.newTo = run.newTo;
+            continue;
+        }
+        merged.push({ ...run });
+    }
+    return merged;
+}

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

@@ -1,3 +1,4 @@
+import type { FormatAxisId } from "../formatAxes.js";
 import type { StructuredBlockLanguage } from "./structured-block-schema.js";
 /**
  * Every reason a structured-block parser drops bytes. Adding a case here
@@ -21,7 +22,15 @@ export type DropAdjudication = {
     partial?: true;
 } | {
     kind: "format-dof-axis";
-    axisIds: readonly string[];
+    /**
+     * Ids from `../formatAxes`, not free text. Card #288 turned the axis
+     * vocabulary into a closed union precisely so this field cannot name a
+     * spelling nobody defined — before it, `format-dof-axis` was a verdict
+     * that pointed at a string, which is a shrug with a citation on it.
+     * `__tests__/formatAxes.test.ts` closes the reference the other way too:
+     * an axis no ledger entry spends is stale and fails.
+     */
+    axisIds: readonly FormatAxisId[];
     witness: DropWitness;
     rationale: string;
     partial?: true;

package/dist/format/blocks/dropClosure.js

@@ -15,7 +15,17 @@
 //
 //   structural-only     the bytes carry no content — a blank line, a container
 //   format-dof-axis     the bytes are one spelling of a thing we keep; the
-//                       axis id names where a serializer replays that spelling
+//                       axis id names WHICH degree of freedom, and it is an id
+//                       from `../formatAxes` rather than a phrase — that file
+//                       is the finite list, and it carries the DISCRIMINATION
+//                       witness that proves the two spellings mean one thing.
+//                       Not a round-trip witness, which is what this line used
+//                       to call it: a discrimination witness shows the two
+//                       spellings parse alike and that the capture layer can
+//                       tell them apart, and says nothing about whether either
+//                       survives a save. `formatAxes.ts`'s replay scoreboard is
+//                       where that question is answered, and for most axes the
+//                       answer today is no
 //   retained-by-capture the bytes are gone from the line but present in the
 //                       parsed data, and `retained` says exactly where
 //   documented-residual real loss, admitted, witnessed. These — and only

package/dist/format/callout.d.ts

@@ -9,28 +9,86 @@
  *     > [!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.
+ * Fifteen types. The first five are GitHub's alert set — note, tip, important,
+ * warning, caution — and the other ten are the Obsidian set every vault and
+ * every other markdown tool already writes, so a document pasted in from one of
+ * them keeps its tone instead of falling back to a plain quote. 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.
+ *
+ * Two things beyond the type sit on the marker line, and both are round-tripped
+ * rather than normalised away:
+ *
+ *   - an ALIAS. `[!WARN]`, `[!SUMMARY]`, `[!ERROR]` name a type by another
+ *     word. They resolve to the canonical type for rendering, and the word the
+ *     author actually typed is carried on `authoredAs` so the bytes come back
+ *     unchanged. Normalising the spelling would rewrite a line the author did
+ *     not touch, which is churn in a file two agents and a person share.
+ *   - a FOLD marker. Obsidian's `[!NOTE]+` and `[!NOTE]-` say the callout is
+ *     collapsible and whether it starts open. It is one character of grammar
+ *     and it is the whole difference between a callout and a details block.
  *
  * 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 declare const CALLOUT_TYPES: readonly ["note", "tip", "important", "warning", "caution", "abstract", "info", "todo", "success", "question", "failure", "danger", "bug", "example", "quote"];
 export type CalloutType = (typeof CALLOUT_TYPES)[number];
+/**
+ * The other words people write for a type that already exists. Ported from
+ * open-knowledge's `callout-transformer.ts:41-71`, which took them from
+ * Obsidian, so a vault's markdown lands here meaning what it meant there.
+ *
+ * An alias is a spelling, not a type: it never widens `CalloutType`, and the
+ * authored word survives on `Callout.authoredAs` rather than in the enum.
+ */
+export declare const CALLOUT_ALIASES: Readonly<Record<string, CalloutType>>;
+/** Obsidian's foldable marker: `+` starts open, `-` starts collapsed. */
+export type CalloutFold = "+" | "-";
 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 token exactly as authored, when it is not the canonical type name —
+     * `WARN` for a warning, `Summary` for an abstract. Absent when the author
+     * already wrote the canonical word in any case, which is what keeps
+     * `[!note]` canonicalizing to `[!NOTE]` as it always has.
+     */
+    authoredAs?: string;
+    /** Present when the marker carried `+` or `-`, which makes it collapsible. */
+    fold?: CalloutFold;
+}
+export interface CalloutMarkerOptions {
+    /** The authored spelling to write back instead of the canonical word. */
+    authoredAs?: string | null;
+    fold?: CalloutFold | null;
 }
-/** The marker as written: uppercase, so `[!NOTE]` is what lands on disk. */
-export declare function calloutMarker(type: CalloutType): string;
+/**
+ * The marker as written: uppercase, so `[!NOTE]` is what lands on disk — unless
+ * the author spelled the type another way, in which case their word goes back.
+ *
+ * `authoredAs` is checked, not trusted. It is an attribute by the time it gets
+ * here (the editor carries it on the node), and an attribute a paste or a
+ * command could have set to anything; a marker that no longer resolves to this
+ * callout's type would come back as a plain quote with a stray bracket. So a
+ * spelling that does not resolve to `type` is discarded and the canonical word
+ * is written instead — the tone is preserved and only the churn is paid.
+ */
+export declare function calloutMarker(type: CalloutType, options?: CalloutMarkerOptions): string;
+/** True for the fifteen canonical type names, in any case. Aliases are not types. */
 export declare function isCalloutType(value: string): value is CalloutType;
+/**
+ * The token on a marker line — canonical or alias — resolved to the type that
+ * renders it, or null when it names nothing. Every caller that has to decide
+ * "is this a callout?" asks this rather than `isCalloutType`, because an alias
+ * IS a callout and only differs in how it is spelled.
+ */
+export declare function resolveCalloutType(token: string): CalloutType | null;
 /**
  * Drop one level of `>` quoting. A single space after the marker is part of
  * the marker, not the content — `>  indented` keeps one space.
@@ -62,5 +120,9 @@ export declare function calloutBodyLine(blockquoteLines: readonly string[]): num
  * 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.
+ *
+ * The marker line is rebuilt from the three fields that spell it — type,
+ * authored word, fold — rather than kept as a string, so a callout the editor
+ * constructed by hand and one parsed off disk are written by the same code.
  */
 export declare function calloutToMarkdown(callout: Callout): string;