sfora-cli 0.10.0 → 0.12.0

package/dist/format/lint/severity.js

@@ -0,0 +1,50 @@
+// 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 four levels a sfora-law diagnostic can speak at, and what each one means.
+//
+// One level is not enough. Every rule in this directory answers the same
+// question — "will this byte sequence render as the author obviously meant it
+// to?" — but the ANSWERS differ in kind, and flattening them made the gutter
+// lie in both directions: an unclosed frontmatter fence, which costs a document
+// every field it claims to have, wore the same amber as a checkbox that renders
+// perfectly and is merely uncounted.
+//
+// The ladder is ordered by WHAT IS LOST, not by how loud the rule feels:
+//
+//   error    the document as a whole stops meaning what it says. Everything
+//            downstream of the mark is read as something else entirely.
+//   warning  something the author wrote will not render as they meant it. The
+//            bytes are there; the reading is wrong.
+//   info     something the author wrote is silently dropped. The render is not
+//            wrong, it is missing a piece, and nothing on screen says so.
+//   hint     the render is exactly right. Only a derived number — a progress
+//            count, an index — comes out different than the author expects.
+//
+// Every level has at least one rule standing on it (asserted in
+// `__tests__/lint.test.ts`), because a severity nothing emits is a severity
+// nobody has thought about.
+//
+// The names match LSP's `DiagnosticSeverity` and CodeMirror's `Severity`, in
+// that order, so the editor adapter is a lookup rather than a translation.
+/** Most severe first. The order IS the rank. */
+export const LINT_SEVERITIES = ["error", "warning", "info", "hint"];
+/** 0 for `error`, 3 for `hint`. Lower is more severe. */
+export function severityRank(severity) {
+    const index = LINT_SEVERITIES.indexOf(severity);
+    // An unknown string is treated as the quietest thing we have rather than as
+    // a crash: a diagnostic that arrived from an older copy of the package must
+    // still sort somewhere.
+    return index === -1 ? LINT_SEVERITIES.length : index;
+}
+/** Negative when `a` is more severe than `b`. Sorts most-severe-first. */
+export function compareSeverity(a, b) {
+    return severityRank(a) - severityRank(b);
+}
+/** True when `severity` is at least as severe as `floor`. */
+export function atLeastAsSevere(severity, floor) {
+    return severityRank(severity) <= severityRank(floor);
+}
+export function isLintSeverity(value) {
+    return (typeof value === "string" &&
+        LINT_SEVERITIES.includes(value));
+}

package/dist/format/lint/textEdits.d.ts

@@ -0,0 +1,86 @@
+import type { LintEdit, LintFix } from "./types.js";
+/** Why a list of edits cannot be applied as one atomic change. */
+export type LintEditRejection = {
+    reason: "inverted";
+    edit: LintEdit;
+} | {
+    reason: "out-of-range";
+    edit: LintEdit;
+} | {
+    reason: "overlap";
+    edit: LintEdit;
+    conflictsWith: LintEdit;
+};
+export type LintEditResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    rejection: LintEditRejection;
+};
+/**
+ * True when two edits cannot both be applied to the same document state.
+ *
+ * Proper overlap is the obvious case. The second clause is the one that bites:
+ * two pure INSERTIONS at the same offset do not overlap by any interval test,
+ * yet the text they produce depends entirely on which goes first, and a fix
+ * whose output depends on sort stability is not a fix. Adjacency
+ * (`a.to === b.from`) is fine and stays allowed — that is two rules repairing
+ * neighbouring spans, which is exactly what fix-all is for.
+ */
+export declare function editsConflict(a: LintEdit, b: LintEdit): boolean;
+/**
+ * The application order. Descending by start, then by end, so an edit that
+ * starts later lands first and leaves every earlier offset untouched.
+ *
+ * This function is the reason the offsets in a fix mean anything. Sorting it
+ * the other way still "works" for a single-edit fix — which is most of them,
+ * which is how a bug here would hide — and quietly corrupts every multi-edit
+ * one.
+ */
+export declare function sortEditsForApply(edits: readonly LintEdit[]): LintEdit[];
+/**
+ * Can these edits compose over `source`? Returns the first reason they cannot,
+ * or null. Checked against the source the edits were DERIVED from — an edit
+ * checked against a document that has moved on is meaningless.
+ */
+export declare function checkEdits(source: string, edits: readonly LintEdit[]): LintEditRejection | null;
+/**
+ * Apply `edits` to `source` as one atomic change, or say why not.
+ *
+ * Never throws and never half-applies: on any rejection the caller gets the
+ * reason and the original text is untouched. Lint is a background nicety in a
+ * text editor; it is never allowed to be the reason a document is damaged.
+ */
+export declare function tryApplyEdits(source: string, edits: readonly LintEdit[]): LintEditResult;
+/**
+ * `tryApplyEdits` for callers that have already validated, or that would
+ * rather lose the fix than reason about a rejection. Returns `source`
+ * unchanged when the edits do not compose.
+ */
+export declare function applyEdits(source: string, edits: readonly LintEdit[]): string;
+/**
+ * True when every edit still describes the bytes it was computed against.
+ *
+ * The staleness question, factored out of the editor adapter. A fix's offsets
+ * point into the source a rule read; applying them to a document that has been
+ * typed into since is not a repair, it is corruption at a plausible-looking
+ * offset. Both the CodeMirror action and the batch path ask this before they
+ * commit.
+ */
+export declare function editsMatch(source: string, edits: readonly LintEdit[], expected: string): boolean;
+/** LSP's `Position`: zero-based line, zero-based UTF-16 offset within it. */
+export interface LintPosition {
+    line: number;
+    character: number;
+}
+/** LSP's `TextEdit`, for anything that talks over a wire instead of a buffer. */
+export interface LintTextEdit {
+    range: {
+        start: LintPosition;
+        end: LintPosition;
+    };
+    newText: string;
+}
+/** One fix's edits in LSP wire form, in the order LSP wants them (any). */
+export declare function fixToTextEdits(source: string, fix: LintFix): LintTextEdit[];

package/dist/format/lint/textEdits.js

@@ -0,0 +1,162 @@
+// 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 edit mechanics every quick fix rides on.
+//
+// A fix is a LIST of replacements over ONE document state, not a sequence of
+// steps. That distinction is the whole of this file. Each edit's offsets are
+// absolute into the PRE-fix source, so applying them in document order is
+// wrong by construction: the first edit moves every offset after it, and the
+// second one then cuts the wrong bytes out of a string that no longer matches
+// the one the rule read. Applying them last-one-first is the fix — an edit at a
+// LOWER offset cannot disturb an edit at a higher one that has already landed.
+//
+// (`applyLintFix` in lintSource.ts has always reverse-sorted. What it did not
+// do was check that the edits could compose at all: it skipped an
+// out-of-range edit and applied the rest, which is a HALF-applied fix — the
+// one outcome worse than no fix, because the author accepted a repair and got
+// a different broken document. Everything here exists so the answer is "all of
+// it or none of it".)
+//
+// Two edits that overlap have no correct order in either direction, so they
+// are rejected rather than resolved: whichever one is applied second is
+// reading bytes the first one already replaced. That is the shape of the guard
+// `fixAll` needs when it composes fixes from different rules over one
+// document.
+//
+// Offsets, not `{line, character}`. LSP's `TextEdit` carries positions because
+// its wire protocol has no shared buffer; here the source string is right
+// there, CodeMirror's `changes` spec wants offsets, and a line/character pair
+// would be converted twice for no one's benefit. The SHAPE is LSP's — a fix is
+// a list of ranged replacements applied reverse-sorted — and `lintEditToLsp`
+// below converts on the way out for anything that wants the wire form.
+/**
+ * True when two edits cannot both be applied to the same document state.
+ *
+ * Proper overlap is the obvious case. The second clause is the one that bites:
+ * two pure INSERTIONS at the same offset do not overlap by any interval test,
+ * yet the text they produce depends entirely on which goes first, and a fix
+ * whose output depends on sort stability is not a fix. Adjacency
+ * (`a.to === b.from`) is fine and stays allowed — that is two rules repairing
+ * neighbouring spans, which is exactly what fix-all is for.
+ */
+export function editsConflict(a, b) {
+    if (a.from < b.to && b.from < a.to)
+        return true;
+    return a.from === a.to && b.from === b.to && a.from === b.from;
+}
+/**
+ * The application order. Descending by start, then by end, so an edit that
+ * starts later lands first and leaves every earlier offset untouched.
+ *
+ * This function is the reason the offsets in a fix mean anything. Sorting it
+ * the other way still "works" for a single-edit fix — which is most of them,
+ * which is how a bug here would hide — and quietly corrupts every multi-edit
+ * one.
+ */
+export function sortEditsForApply(edits) {
+    return [...edits].sort((a, b) => b.from - a.from || b.to - a.to);
+}
+/**
+ * Can these edits compose over `source`? Returns the first reason they cannot,
+ * or null. Checked against the source the edits were DERIVED from — an edit
+ * checked against a document that has moved on is meaningless.
+ */
+export function checkEdits(source, edits) {
+    for (const edit of edits) {
+        if (edit.from > edit.to)
+            return { reason: "inverted", edit };
+        if (edit.from < 0 || edit.to > source.length) {
+            return { reason: "out-of-range", edit };
+        }
+    }
+    // O(n²) over the edits of one fix, which is at most a handful. `fixAll`
+    // pays the same price across a document's worth of fixes and it is still
+    // nothing next to the parse that produced them.
+    for (let i = 0; i < edits.length; i++) {
+        for (let j = i + 1; j < edits.length; j++) {
+            const a = edits[i];
+            const b = edits[j];
+            if (editsConflict(a, b)) {
+                return { reason: "overlap", edit: b, conflictsWith: a };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Apply `edits` to `source` as one atomic change, or say why not.
+ *
+ * Never throws and never half-applies: on any rejection the caller gets the
+ * reason and the original text is untouched. Lint is a background nicety in a
+ * text editor; it is never allowed to be the reason a document is damaged.
+ */
+export function tryApplyEdits(source, edits) {
+    const rejection = checkEdits(source, edits);
+    if (rejection)
+        return { ok: false, rejection };
+    let out = source;
+    for (const edit of sortEditsForApply(edits)) {
+        out = out.slice(0, edit.from) + edit.insert + out.slice(edit.to);
+    }
+    return { ok: true, text: out };
+}
+/**
+ * `tryApplyEdits` for callers that have already validated, or that would
+ * rather lose the fix than reason about a rejection. Returns `source`
+ * unchanged when the edits do not compose.
+ */
+export function applyEdits(source, edits) {
+    const result = tryApplyEdits(source, edits);
+    return result.ok ? result.text : source;
+}
+/**
+ * True when every edit still describes the bytes it was computed against.
+ *
+ * The staleness question, factored out of the editor adapter. A fix's offsets
+ * point into the source a rule read; applying them to a document that has been
+ * typed into since is not a repair, it is corruption at a plausible-looking
+ * offset. Both the CodeMirror action and the batch path ask this before they
+ * commit.
+ */
+export function editsMatch(source, edits, expected) {
+    if (checkEdits(expected, edits) !== null)
+        return false;
+    return edits.every((edit) => edit.to <= source.length &&
+        source.slice(edit.from, edit.to) === expected.slice(edit.from, edit.to));
+}
+/**
+ * Offsets → line/character, for one document. Built once per conversion so a
+ * fix with several edits does not rescan the source per edit.
+ */
+function lineStartsOf(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === "\n")
+            starts.push(i + 1);
+    }
+    return starts;
+}
+function positionAt(lineStarts, offset) {
+    // Binary search for the last line start at or before `offset`.
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineStarts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo, character: offset - lineStarts[lo] };
+}
+/** One fix's edits in LSP wire form, in the order LSP wants them (any). */
+export function fixToTextEdits(source, fix) {
+    const lineStarts = lineStartsOf(source);
+    return fix.edits.map((edit) => ({
+        range: {
+            start: positionAt(lineStarts, edit.from),
+            end: positionAt(lineStarts, edit.to),
+        },
+        newText: edit.insert,
+    }));
+}

package/dist/format/lint/types.d.ts

@@ -1,10 +1,8 @@
 import type { Root } from "mdast";
-/**
- * Nothing in sfora-law is an "error". A rule that is not sure stays silent,
- * and a rule that is sure still only says "this will not render the way you
- * think" — the bytes on disk are always the user's to keep.
- */
-export type LintSeverity = "error" | "warning" | "info";
+import type { LintConfig } from "./config.js";
+import type { SelectedFrontmatterSchema } from "./frontmatterSchema.js";
+import type { LintSeverity } from "./severity.js";
+export type { LintSeverity };
 /** A replacement over the PRE-fix document. Offsets are absolute. */
 export interface LintEdit {
     from: number;
@@ -12,8 +10,15 @@ export interface LintEdit {
     insert: string;
 }
 /**
- * One quick fix. Its edits compose atomically — they are all applied against
- * the same document state, so they must not overlap.
+ * One quick fix, LSP-shaped: a LIST of ranged replacements over ONE document
+ * state, not a script of steps. All the edits are computed against the same
+ * pre-fix source, so they compose atomically and must not overlap — see
+ * ./textEdits, which owns the ordering, the overlap check and the application.
+ *
+ * A fix with several edits is the normal case, not an exotic one: repairing a
+ * fenced block's opening and closing delimiter together, or removing a dead
+ * frontmatter line while rewriting the live one, is two edits far apart in the
+ * file that only mean anything if they land as a unit.
  */
 export interface LintFix {
     label: string;
@@ -48,6 +53,14 @@ export interface LintContext {
      * Rules never fire inside a fence: the bytes there are not markdown.
      */
     inFence: (lineIndex: number) => boolean;
+    /**
+     * True for a line that holds bytes, none of which render — inside an HTML
+     * comment, or wholly inside an inline code span. The wider judgement behind
+     * `inFence`, from the same shared mask every other scanner in the package
+     * reads, so a rule cannot decide that a line is markdown when the reader has
+     * already decided it is not.
+     */
+    nonRendering: (lineIndex: number) => boolean;
     /** True for the frontmatter fences and everything between them. */
     inFrontmatter: (lineIndex: number) => boolean;
     /** Line extents of the frontmatter block, or null when there is none. */
@@ -55,6 +68,16 @@ export interface LintContext {
         open: number;
         close: number;
     } | null;
+    /**
+     * The frontmatter schemas the workspace declared for THIS document's path,
+     * scope already applied. Absent or empty on every document until a workspace
+     * writes one down — see ./frontmatterSchema, which owns the selection.
+     *
+     * Selected here rather than in the rule for the same reason the fence mask
+     * is: the runner knows the document's path and the rule does not, and a rule
+     * that re-derived the scope would be a second place for the two to disagree.
+     */
+    frontmatterSchemas?: readonly SelectedFrontmatterSchema[];
     /** Present only when a parser was injected AND it succeeded. */
     ast?: Root;
     /**
@@ -77,4 +100,17 @@ export interface LintSourceOptions {
     /** Injected mdast parser — `parseMarkdownAst(source).root`. */
     parseAst?: (source: string) => Root;
     resolveLink?: LintContext["resolveLink"];
+    /**
+     * What the workspace says about these rules: which are off, which report at
+     * another level, which are scoped to a set of paths. Absent means every rule
+     * runs at the severity it declares, which is what every caller got before
+     * the config existed.
+     */
+    config?: LintConfig;
+    /**
+     * The document's path, for `appliesTo` scoping —
+     * `projects/sfora/docs/plan.md`. A scoped rule runs anyway when this is
+     * missing; see `scopeAdmits` for why silence is the worse failure.
+     */
+    path?: string;
 }

package/dist/format/markdown/slug.d.ts

@@ -1,2 +1,30 @@
 export declare function slugify(title: string): string;
+/**
+ * The slug of one heading's text, and the anchor half of `[[target#anchor]]`.
+ *
+ * THE WHOLE POINT is that one function serves both sides: the read path stamps
+ * `id={toAnchorSlug(headingText)}` on the rendered heading, and a wiki link's
+ * anchor resolves through `toAnchorSlug(anchor)`. Two spellings of this rule
+ * would mean `[[page#my-heading]]` scrolls to nothing, and nothing would say
+ * so — which is why `anchorSlugAgreement` in the tests mutates one caller and
+ * asserts the other fails.
+ *
+ * Returns "" for text with no letters or numbers in it at all. That is not a
+ * fallback: a heading of "***" has no name to be linked by, and inventing one
+ * ("untitled") would hand two such headings the same anchor.
+ */
+export declare function toAnchorSlug(text: string): string;
+/**
+ * Suffix a repeated slug so every id in one document is unique: the first
+ * `## Notes` is `notes`, the second `notes-1`, the third `notes-2`.
+ *
+ * `counts` is the caller's ledger for ONE document, mutated in place — pass a
+ * fresh `Map` per render. The suffix is a positional fact, so a link written
+ * as `[[page#notes-1]]` means "the second heading called Notes" and moves when
+ * a third one is inserted above it. That is the same bargain every heading-
+ * anchor scheme makes; there is no stable name for a name used twice.
+ */
+export declare function disambiguateSlug(baseSlug: string, counts: Map<string, number>): string;
+/** `toAnchorSlug` + dedupe. The id a rendered heading carries. */
+export declare function headingSlug(text: string, counts: Map<string, number>): string;
 export declare function slugFromFilename(filename: string): string;

package/dist/format/markdown/slug.js

@@ -14,6 +14,69 @@ export function slugify(title) {
         .replace(/^-+|-+$/g, "");
     return s || "untitled";
 }
+// ─── heading anchors ──────────────────────────────────────────────────
+//
+// A DIFFERENT slug from `slugify` above, and the difference is the point.
+// `slugify` names FILES, so it is ASCII-only on purpose: a filename crosses a
+// filesystem, a URL path, and a tarball, and `café.md` is three different byte
+// strings depending on which one wrote it. A heading anchor never leaves the
+// document — it is an `id` on an `<h2>` and a `#fragment` pointing at it — so
+// throwing away every non-ASCII letter there would collapse `## Café` and
+// `## 咖啡` to the same empty slug and make both unlinkable.
+//
+// The two must not be merged. Widening `slugify` to Unicode would rename every
+// file the fs API has ever written.
+//
+// Rules follow open-knowledge's `toWikiLinkSlug`
+// (context/open-knowledge/packages/core/src/utils/slug.ts): trim, NFKD, drop
+// combining marks, lowercase, any run of non-letter/non-number to one hyphen,
+// strip edge hyphens.
+const COMBINING_MARK_RE = /\p{M}+/gu;
+const NON_LETTER_OR_NUMBER_RE = /[^\p{L}\p{N}]+/gu;
+const EDGE_HYPHENS_RE = /^-+|-+$/g;
+/**
+ * The slug of one heading's text, and the anchor half of `[[target#anchor]]`.
+ *
+ * THE WHOLE POINT is that one function serves both sides: the read path stamps
+ * `id={toAnchorSlug(headingText)}` on the rendered heading, and a wiki link's
+ * anchor resolves through `toAnchorSlug(anchor)`. Two spellings of this rule
+ * would mean `[[page#my-heading]]` scrolls to nothing, and nothing would say
+ * so — which is why `anchorSlugAgreement` in the tests mutates one caller and
+ * asserts the other fails.
+ *
+ * Returns "" for text with no letters or numbers in it at all. That is not a
+ * fallback: a heading of "***" has no name to be linked by, and inventing one
+ * ("untitled") would hand two such headings the same anchor.
+ */
+export function toAnchorSlug(text) {
+    return text
+        .trim()
+        .normalize("NFKD")
+        .replace(COMBINING_MARK_RE, "")
+        .toLowerCase()
+        .replace(NON_LETTER_OR_NUMBER_RE, "-")
+        .replace(EDGE_HYPHENS_RE, "");
+}
+/**
+ * Suffix a repeated slug so every id in one document is unique: the first
+ * `## Notes` is `notes`, the second `notes-1`, the third `notes-2`.
+ *
+ * `counts` is the caller's ledger for ONE document, mutated in place — pass a
+ * fresh `Map` per render. The suffix is a positional fact, so a link written
+ * as `[[page#notes-1]]` means "the second heading called Notes" and moves when
+ * a third one is inserted above it. That is the same bargain every heading-
+ * anchor scheme makes; there is no stable name for a name used twice.
+ */
+export function disambiguateSlug(baseSlug, counts) {
+    const count = counts.get(baseSlug) ?? 0;
+    counts.set(baseSlug, count + 1);
+    return count === 0 ? baseSlug : `${baseSlug}-${count}`;
+}
+/** `toAnchorSlug` + dedupe. The id a rendered heading carries. */
+export function headingSlug(text, counts) {
+    const base = toAnchorSlug(text);
+    return base ? disambiguateSlug(base, counts) : "";
+}
 // Pull the slug back out of a filename: drop the .md and an optional leading
 // YYYY-MM-DD- date prefix. Used to match a requested filename to an entity.
 export function slugFromFilename(filename) {

package/dist/format/plaintext.js

@@ -23,9 +23,19 @@ export function stripToPlainText(body, options = {}) {
         .replace(/<[^>]+>/g, " ") // raw HTML tags
         .replace(/!\[([^\]]*)\]\([^)]*\)/g, images === "alt" ? "$1" : " ")
         .replace(/@\[([^\]]+)\]\([^)]*\)/g, "@$1") // mention → @Name
-        .replace(/\[\[[^\]|]*\|([^\]]*)\]\]/g, "$1"); // [[target|Label]] → Label
-    // Label-less tokens.
-    out = out.replace(wikiLinkPattern(), wikiTokens === "keep" ? "$1" : " ");
+        // `[[target|Label]]` → Label, and `![[target|Label]]` with it. The optional
+        // bang is the embed marker (card #298) and it has to be eaten HERE: left
+        // out of the pattern, every embed in every excerpt turns into a stray
+        // exclamation mark in front of its label. An embed flattens to the same
+        // words a link does — a one-line preview has nowhere to put a card.
+        .replace(/!?\[\[[^\]|]*\|([^\]]*)\]\]/g, "$1");
+    // Label-less tokens. `wikiLinkPattern()` matches the brackets only, so the
+    // bang is stripped separately rather than by widening the grammar's own
+    // pattern — that pattern's span is what `canonicalizeReferences` rewrites,
+    // and a span that swallowed the bang would rewrite embeds into links.
+    out = out
+        .replace(/!\[\[([^\]]+)\]\]/g, wikiTokens === "keep" ? "$1" : " ")
+        .replace(wikiLinkPattern(), wikiTokens === "keep" ? "$1" : " ");
     return out
         .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) → text
         .replace(/^\s*\|(?:\s*:?-+:?\s*\|)+\s*$/gm, " ") // table separator rows

package/dist/format/sheetCellSpans.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Where every sheet cell lives in the authored bytes.
+ *
+ * `parseSheet` hands the reader a grid of DECODED strings — trimmed, escapes
+ * resolved, short rows padded. That is the right shape to draw and the wrong
+ * shape to write back through: re-serializing the whole grid from it would
+ * rewrite the author's column padding, their outer pipes, their delimiter row,
+ * every byte they lined up by hand.
+ *
+ * So an edit is a splice, not a re-serialization. This module answers "which
+ * byte range is that cell?" and writes a single cell in place. Everything the
+ * author wrote outside the edited cell survives untouched, which is what makes
+ * the no-op case byte-identical by construction rather than by luck:
+ * `writeSheetCell(source, r, c, currentText)` returns the same string back.
+ *
+ * The escape rules here are a second reading of the same grammar `sheetCells`
+ * in `blocks/parsers.ts` reads, and a second reading is only trustworthy if
+ * something checks it against the first. `sheetCellSpans.test.ts` does: every
+ * span's slice is fed back through `parseSheet` and must equal the cell the
+ * parser reports. A divergence is a test failure, never a silent misalignment.
+ *
+ * The CODE-SPAN half is no longer a second reading at all. While this module
+ * lived in `src/components/editor/` it could not reach the engine's private
+ * helpers, so it carried a hand-rolled `codeSpanMask` that closed a backtick
+ * run with `indexOf` — which lets a longer run close a shorter one, where
+ * CommonMark (and `lineGeometry.codeSpanMask`, which `sheetCells` uses) wants
+ * the closing run to be exactly as long as the opening one. Moving the file
+ * into the engine (board card #278) retires the copy: both readings of "where
+ * are the code spans" are now the one function, so the two cannot drift.
+ */
+/** One cell's trimmed content, addressed in the block source. */
+export type SheetCellSpan = {
+    /** Offset of the first byte of trimmed content. */
+    start: number;
+    /** Offset just past the last byte. `start === end` for an empty cell. */
+    end: number;
+    /** The text the reader shows — the same string `parseSheet` reports. */
+    text: string;
+};
+/** One source line's cells, plus where a missing trailing cell would go. */
+export type SheetRowSpan = {
+    /** Cells present in the source. May be shorter than the column count. */
+    cells: SheetCellSpan[];
+    /** End-of-line offset, where a short row grows. */
+    appendAt: number;
+    /** Whether the line closes with a pipe, which decides the append shape. */
+    trailingPipe: boolean;
+};
+export type SheetCellGrid = {
+    columns: number;
+    header: SheetRowSpan;
+    rows: SheetRowSpan[];
+};
+/**
+ * Build the source-anchored grid, or null when the source is not a sheet the
+ * reader would draw — the same null the renderer already falls back on.
+ *
+ * The cell TEXTS come from `parseSheet`, never from this file's own decoding:
+ * one reader of the grammar owns what a cell says, and this module only owns
+ * where it sits. When the two disagree about how many cells the header has,
+ * the grid degrades to null instead of handing back a misaligned map.
+ */
+export declare function sheetCellGrid(source: string): SheetCellGrid | null;
+/**
+ * Encode a value for a table cell.
+ *
+ * The inverse of the engine's decoding over the alphabet that decoding
+ * touches: `\` and `|`. Everything else is left as the author typed it —
+ * the sheet renders cell text literally, so nothing else needs a spelling.
+ * A row cannot hold a line break, so whitespace runs collapse to one space.
+ */
+export declare function encodeSheetCell(value: string): string;
+export type SheetWriteResult = {
+    ok: true;
+    source: string;
+    /** The value as the reader will now show it, after normalization. */
+    value: string;
+    /** False when the write was a no-op — `source` is then the input string. */
+    changed: boolean;
+    /** True when a line break or padding was collapsed to fit a row. */
+    normalized: boolean;
+} | {
+    ok: false;
+    reason: "no-grid" | "row-out-of-range" | "column-out-of-range";
+    /** Always the untouched input, so a caller can assign unconditionally. */
+    source: string;
+};
+/**
+ * Write one cell and return the whole block source back.
+ *
+ * Total by construction: every refusal names itself, nothing returns
+ * `undefined`, and the unchanged source always comes back on the result so a
+ * caller cannot accidentally drop the document by not checking `ok`.
+ */
+export declare function writeSheetCell(source: string, rowIndex: number, columnIndex: number, value: string): SheetWriteResult;