/**
 * THE OFFSET-PRESERVING SOURCE TOKENIZER (rich-content PLAN decision 6).
 *
 * Cuts stored markdown into blocks that cover the text EXACTLY: the
 * concatenation of every block's `raw` is the input, always, byte for byte.
 * Nothing is trimmed, normalized, or re-serialized here — the tokenizer only
 * draws boundaries. Every custom construct the platform stores (kinds and
 * `__kind` JSON, typed JSON blocks, special fences, XML sections including
 * attribute-bearing, mid-line and unknown containers, `{{variables}}`,
 * `<matrxcite/>`, math, raw HTML, code fences, HTML comments and pinned
 * anchors `<!--@a:…-->`) is an ISLAND: an atomic span no editor may parse
 * into its own model. Islands that sit inside running prose (a variable, a
 * citation, inline math) stay inside their paragraph as `inlines`, so a
 * visual editor keeps the paragraph whole and holds the island as an atom.
 *
 * Block kinds:
 *   - `prose`  — a markdown paragraph run (headings, lists, tables…): the only
 *                thing a visual editor may re-serialize, and only when edited.
 *   - `island` — a protected construct; `islandType` says which.
 *   - `gap`    — the line terminator(s) and blank lines between blocks. Never
 *                edited; they keep the document's exact spacing.
 *
 * Streaming-tolerant: never throws on partial input. A construct whose
 * closer has not arrived yet becomes an island running to the end of the text
 * with `complete: false` — the same ownership rule the renderer's splitter
 * applies, so a half-streamed fence or XML section is never reflowed.
 *
 * Boundaries follow matrx-frontend's renderer splitter (`content-splitter-v2.ts`)
 * wherever it decides where a construct ends, so the editor and the renderer
 * agree on what is locked. Offsets are UTF-16 (`start`/`end`) and code points
 * (`startCp`/`endCp`).
 */
type SourceBlockKind = "prose" | "island" | "gap";
/** Island types that own whole blocks. */
type BlockIslandType = 
/** ``` / ~~~ fenced code of any language (meta.lang, meta.special). */
"fence"
/** A bare JSON object block — typed JSON, `__kind` instances, directives. */
 | "json"
/** A known attribute-less XML region (`<thinking>`, `<flashcards>`, …). */
 | "xml_region"
/** An attribute-bearing XML element (`<artifact …>`, `<decision …>`, …). */
 | "xml_attr"
/** Any other line-leading, balanced XML element. */
 | "xml_container"
/** Allow-listed raw HTML block. */
 | "html_block"
/** `<!-- … -->` comment. */
 | "html_comment"
/** A pinned annotation anchor `<!--@a:id-->`. */
 | "anchor"
/** `$$ … $$` display math on its own lines. */
 | "math_block"
/** YAML (`---`) or TOML (`+++`) front matter at the start of the text (meta.format). */
 | "front_matter"
/** A box-drawing tree diagram. */
 | "tree"
/**
 * A generic-directive container `:::name[label]{attrs}` … `:::` (tabs,
 * columns, details, figures, callouts, TOC — meta.name), a leaf directive
 * `::name` on its own line (meta.leaf), or a MkDocs admonition
 * `!!! type "Title"` / `??? type` with its indented body (meta.syntax "mkdocs").
 */
 | "directive"
/** A GitHub alert / Obsidian callout: a blockquote opening `> [!TYPE]` (meta.name). */
 | "callout"
/** A footnote definition `[^id]: …` with its indented continuation lines (meta.id). */
 | "footnote_def";
/** Island types that live inside a prose block. */
type InlineIslandType = "variable" | "cite" | "math_inline" | "html_tag" | "xml_tag" | "xml_inline" | "html_comment" | "anchor" | "kind_json" | "media_ref"
/** `[[Page]]`, `[[Page|alias]]` (meta.target) — or `![[Page]]` (meta.embed). */
 | "wikilink";
type IslandType = BlockIslandType | InlineIslandType;
type IslandMeta = Readonly<Record<string, string | number | boolean>>;
interface SourceSpan {
    /** UTF-16 offset of the first code unit. */
    readonly start: number;
    /** UTF-16 offset just past the last code unit. */
    readonly end: number;
    /** Code-point offset of `start`. */
    readonly startCp: number;
    /** Code-point offset of `end`. */
    readonly endCp: number;
    /** Exactly `text.slice(start, end)`. */
    readonly raw: string;
}
interface SourceIsland extends SourceSpan {
    readonly islandType: IslandType;
    /** True when the island sits inside a prose block. */
    readonly inline: boolean;
    /** False when the construct's closer never arrived (streaming / malformed). */
    readonly complete: boolean;
    readonly meta: IslandMeta;
}
interface SourceBlock extends SourceSpan {
    readonly kind: SourceBlockKind;
    /** Set only on `island` blocks. */
    readonly islandType: BlockIslandType | null;
    readonly complete: boolean;
    readonly meta: IslandMeta;
    /** Inline islands of a `prose` block, in document order. Empty otherwise. */
    readonly inlines: readonly SourceIsland[];
}
/**
 * Every callout spelling the renderer resolves (matrx-frontend
 * components/markdown-core/syntax/callout-types.ts ALIASES — keep in step).
 */
declare const CALLOUT_NAMES: ReadonlySet<string>;
/**
 * Cut `text` into blocks whose raw concatenation is exactly `text`.
 * Never throws; unclosed constructs are islands with `complete: false`.
 */
interface TokenizeOptions {
    /**
     * The text is a prefix of a message still arriving. The final line (no
     * terminator yet) can still grow — a bare ``` there may become ```bash — so
     * it closes no fence until its newline arrives (verify-RC-B3 residual R2).
     * Omit for stored text: a complete document's last line is final.
     */
    readonly streaming?: boolean;
    /**
     * DIAGNOSTIC — complexity tests only. When given, every loop that walks the
     * text itself adds the characters it visits to `meter.work`, so a test can
     * assert the tokenizer's work grows linearly with its input (deterministic,
     * unlike wall-clock timing). Loops over a slice are not charged here: the
     * slice's own cost covers them. Omit in production.
     */
    readonly meter?: {
        work: number;
    };
}
declare function tokenizeSource(text: string, options?: TokenizeOptions): SourceBlock[];
/** The exact source the blocks were cut from. */
declare function joinSource(blocks: readonly SourceBlock[]): string;
/** Every island — block-level and inline — in document order. */
declare function listIslands(blocks: readonly SourceBlock[]): SourceIsland[];
/** The block containing UTF-16 offset `offset` (the later block at a boundary). */
declare function blockAt(blocks: readonly SourceBlock[], offset: number): SourceBlock | null;

/**
 * SAVE = SPLICE (rich-content PLAN decision 6).
 *
 * An editor never hands back a whole re-serialized document. It hands back
 * per-block replacements for exactly the blocks the person changed; every
 * other byte of the stored text is written back as it was. This module
 * applies those replacements and returns:
 *
 *   - the new text,
 *   - a change set (old range → new range, in UTF-16 AND code points,
 *     narrowed to the bytes that actually differ) that the annotation layer
 *     uses to carry every live anchor through the save
 *     (STORE-DESIGN §3.19 — the ProseMirror / Google Docs position-mapping
 *     model), and
 *   - an integrity guarantee: every island not explicitly replaced must still
 *     be the same island, at its mapped position, in the new text. An edit
 *     that opens an unclosed fence and swallows a kind below it is REFUSED.
 *
 * ISLANDS CHANGE ONLY THROUGH `islandEdit`. A prose/range edit must hand back
 * every island inside its range byte-identical and in order (a visual editor
 * holds them as atoms); if one is altered or dropped the save throws
 * `SourceSpliceError("island_edit")` naming the island. A kind editor or code
 * view changes an island with `islandEdit(island, newRaw)`.
 *
 * A no-edit save (or edits whose text equals the original block) returns the
 * original string itself — byte-identical, zero changes.
 */

/**
 * Replace `[start, end)` (UTF-16) of the original with `text`. A plain edit
 * starts and ends on block boundaries; an island edit (`island: true`, made by
 * `islandEdit`) names exactly one island's span.
 */
interface SourceEdit {
    readonly start: number;
    readonly end: number;
    readonly text: string;
    readonly island?: boolean;
}
interface SourceChange {
    /** The block-aligned range the edit named, in the ORIGINAL text. */
    readonly blockStart: number;
    readonly blockEnd: number;
    /** The narrowed range that actually differs: old text … */
    readonly oldStart: number;
    readonly oldEnd: number;
    /** … and where its replacement sits in the NEW text. */
    readonly newStart: number;
    readonly newEnd: number;
    readonly oldStartCp: number;
    readonly oldEndCp: number;
    readonly newStartCp: number;
    readonly newEndCp: number;
}
interface DisturbedIsland {
    readonly islandType: IslandType;
    readonly inline: boolean;
    /** Where the island was in the original (UTF-16). */
    readonly start: number;
    readonly end: number;
    /** Where it should have been in the new text. */
    readonly mappedStart: number;
}
interface SpliceIntegrity {
    /** True when every untouched island survived intact and outside bytes are identical. */
    readonly ok: boolean;
    /** Always true by construction; checked anyway because it is THE guarantee. */
    readonly bytesOutsideEditsIdentical: boolean;
    readonly disturbed: readonly DisturbedIsland[];
}
interface SpliceResult {
    readonly text: string;
    readonly changed: boolean;
    readonly changes: readonly SourceChange[];
    readonly integrity: SpliceIntegrity;
    /** Tokenization of the new text. */
    readonly blocks: readonly SourceBlock[];
}
type SourceSpliceErrorCode = "out_of_range" | "misaligned" | "overlap" | "stale_blocks" | "island_edit" | "integrity";
declare class SourceSpliceError extends Error {
    readonly code: SourceSpliceErrorCode;
    constructor(code: SourceSpliceErrorCode, message: string);
}
interface SpliceOptions {
    /** The tokenization of `original`, when the caller already holds it. */
    readonly blocks?: readonly SourceBlock[];
    /**
     * Default `true`: a save that disturbs any island it did not explicitly
     * replace throws `SourceSpliceError("integrity")`. `false` is for TOOLING
     * ONLY (diagnostic scripts that want the report instead of the refusal) —
     * no editor or persistence path may pass it.
     */
    readonly requireIntegrity?: boolean;
}
/** An edit that replaces one block's raw text. */
declare function blockEdit(block: SourceBlock, text: string): SourceEdit;
/** The one door that changes an island: replace exactly its span with `text`. */
declare function islandEdit(island: {
    readonly start: number;
    readonly end: number;
}, text: string): SourceEdit;
/** An edit that replaces a contiguous run of blocks `[first, last]`. */
declare function blockRangeEdit(first: SourceBlock, last: SourceBlock, text: string): SourceEdit;
/**
 * Apply block-aligned replacements to `original`. Bytes outside the edits are
 * copied, never rebuilt; an edit equal to its block changes nothing.
 */
declare function spliceSave(original: string, edits: readonly SourceEdit[], options?: SpliceOptions): SpliceResult;
interface MapOptions {
    /** -1 keeps a position at an insertion point before the inserted text; 1 (default) moves it after. */
    readonly assoc?: -1 | 1;
    /** Offset unit of `pos` and of the result. Default `utf16`. */
    readonly unit?: "utf16" | "codepoint";
}
interface MappedPosition {
    readonly pos: number;
    /** True when the position sat strictly inside replaced text. */
    readonly deleted: boolean;
}
/**
 * Carry a position in the old text through a change set (ProseMirror StepMap
 * semantics): positions before a change stay, positions after shift by the
 * size difference, a position strictly inside replaced text is `deleted` and
 * lands on the replacement's edge chosen by `assoc`.
 */
declare function mapPosition(changes: readonly SourceChange[], pos: number, options?: MapOptions): MappedPosition;
interface MappedRange {
    readonly start: number;
    readonly end: number;
    /** True when a change overlapped the range's interior. */
    readonly touched: boolean;
    /** True when the whole range was replaced away. */
    readonly collapsed: boolean;
}
/** Carry an anchor range through a change set; it stays inside its text when edits happen around it. */
declare function mapRange(changes: readonly SourceChange[], start: number, end: number, unit?: "utf16" | "codepoint"): MappedRange;

/**
 * THE `{{variable}}` detector — one rule for every place that looks for variables in prompt text.
 *
 * The author's escape (Arman, 2026-10-10): `{{!name}}` means "this is an EXAMPLE, not a variable".
 * The server turns `{{!` into `{{` once, on the first turn, so the model sees `{{name}}`; the
 * server does nothing else with braces. So in every editor, `{{!name}}` is plain text — never
 * colored as a variable, never reported undeclared, never counted as used. Real `{{name}}`
 * tokens behave exactly as before. Pure TS.
 */
/** The character right after `{{` that makes a token an example, not a variable. */
declare const EXAMPLE_VARIABLE_MARK = "!";
/** True for `{{!name}}` — the author's "this is an example" token (raw includes the braces). */
declare const isExampleVariableToken: (raw: string) => boolean;
/**
 * SECTIONS (Mustache): `{{#name}}…{{/name}}` stays only when the declared variable `name` is filled,
 * `{{^name}}…{{/name}}` only when it is empty. A section marker is NOT a variable called `#name`: it
 * is a reference to `name`, so `name` counts as used and `#name` / `/name` are never reported
 * undeclared. The server only acts on markers of declared names (matrx_ai template_substitution).
 */
type SectionMark = "open" | "inverse" | "close";
/** The section marker `{{#name}}` / `{{^name}}` / `{{/name}}` (exact, no spaces) as written, or null. */
declare function sectionMarkerOf(raw: string): {
    mark: SectionMark;
    name: string;
} | null;
/**
 * PROMPT BLOCKS (owner ruling, 2026-10-10): `{{<name>}}` places the library block `name` the agent
 * DECLARES (`agent.definition.prompt_blocks`); the server replaces it with `<name>…</name>` on the
 * first turn. It is never a variable. `{{!<name>}}` is the author's literal example.
 */
declare const PROMPT_BLOCK_NAME: RegExp;
/** True for `{{<name>}}` (raw includes the braces) with a valid block name. */
declare const isPromptBlockToken: (raw: string) => boolean;
interface PromptBlockToken {
    raw: string;
    name: string;
    start: number;
    end: number;
}
/** Every `{{<name>}}` prompt-block token in a text, in order (escaped `{{!<name>}}` skipped). */
declare function findPromptBlockTokens(text: string): PromptBlockToken[];
/** Unique prompt-block names placed in a text, in order of first appearance. */
declare function promptBlockReferencesIn(text: string): string[];
/** The exact token that places block `name`. */
declare const promptBlockToken: (name: string) => string;
interface VariableToken {
    /** The token as written, braces included. */
    raw: string;
    /** The name inside the braces, trimmed. For a section marker: the variable it is about. */
    name: string;
    /** Set when the token is a section marker, not a plain `{{name}}`. */
    section?: SectionMark;
    /** UTF-16 offsets of the token in the text. */
    start: number;
    end: number;
}
/** Every real `{{variable}}` token in a text, in order (repeats kept). `{{!example}}` is skipped. */
declare function findVariableTokens(text: string): VariableToken[];
/** Unique real variable names in a text, in order of first appearance, trimmed. */
declare function variableReferencesIn(text: string): string[];
type VariableSegment = {
    kind: "text";
    text: string;
} | {
    kind: "variable";
    text: string;
    name: string;
    section?: SectionMark;
};
/** The text split into plain runs and real variable tokens (`{{!example}}` stays inside the plain text). */
declare function splitVariableText(text: string): VariableSegment[];
interface VariableUsage {
    /** Declared names the text uses. */
    used: string[];
    /** Names the text uses that nobody declared. */
    undeclared: string[];
}
/** Which declared variables a text uses, and which names it uses that are not declared. */
declare function analyzeVariableUsage(text: string, declared: readonly string[]): VariableUsage;
/** One matched `{{#name}}…{{/name}}` (or `{{^name}}…{{/name}}`) pair. */
interface VariableSection {
    name: string;
    /** `open` keeps the text when filled, `inverse` when empty. */
    mode: "open" | "inverse";
    openToken: VariableToken;
    closeToken: VariableToken;
}
/**
 * The matched sections of a text, outer first, the way the server pairs them: each close pairs with
 * the nearest open of the same name; an unclosed or unmatched marker pairs with nothing (it renders as
 * written). `isDeclared` limits sections to declared names (the server's rule); omit it to take all.
 */
declare function findVariableSections(text: string, isDeclared?: (name: string) => boolean): VariableSection[];
/**
 * Wrap a selection so it is kept only when `name` is filled (`when: "filled"`) or empty. A selection
 * spanning lines (or ending in a newline) gets the markers on their own lines, so removing the section
 * leaves no blank line; a one-line selection is wrapped inline.
 */
declare function wrapInSection(selection: string, name: string, when: "filled" | "empty"): string;
/**
 * `wrapInSection` for a plain-text field: a selection that covers whole lines (it starts at a line
 * start and ends at a line end) gets the markers on their own lines even when it is one line long.
 */
declare function wrapSelectionInText(text: string, start: number, end: number, name: string, when: "filled" | "empty"): {
    text: string;
    selectionStart: number;
    selectionEnd: number;
};

/**
 * THE variable-name rule for `{{name}}`: what a declarable variable name looks like. Pure TS.
 * The agent variable editors, the context-policy key, and the rich editor's `{{token}}` states
 * all ask it (the token grammar itself is `source/variable-tokens.ts`).
 *
 *   - Trim whitespace, lowercase
 *   - Spaces and hyphens → underscores
 *   - Remove non-alphanumeric/underscore characters
 *   - Collapse consecutive underscores to one
 *   - Strip leading/trailing underscores
 */
declare const sanitizeVariableName: (input: string) => string;
/**
 * True when a `{{token}}` could ever name a real variable.
 *
 * Declared names always survive `sanitizeVariableName` unchanged, and the runtime substitutes by
 * exact name match against the declared set — so a token that isn't in that grammar
 * (`{{step_N.output.field}}`, `{{a b}}`) can NEVER be substituted and is literal text the model
 * receives verbatim. Use this to avoid flagging documentation of the syntax as an undeclared
 * variable. Names that ARE declared bypass this check entirely.
 */
declare const isDeclarableVariableName: (name: string) => boolean;

/**
 * THE code-language list: each language a person can pick for a code file or snippet (Monaco
 * language ids, so a pick maps 1:1 to the code editor's `language` prop) with its file
 * extensions, plus the two lookups every door asks — the extension a language saves under and
 * the language a file name implies. Pure TS. One list for the Save to Code window, a code
 * block's download/copy-as-file, and the host app (fence-language aliases live beside it in
 * `source/constants.ts`).
 */
interface LanguageOption {
    value: string;
    label: string;
    /** Common file extensions (no leading dot). */
    exts: string[];
}
declare const LANGUAGE_OPTIONS: LanguageOption[];
/** The extension (no dot) a language saves under; `txt` for a language not on the list. */
declare function extensionForLanguage(language: string): string;
/** The language a file name's extension implies; `plaintext` when it implies none. */
declare function languageFromName(name: string): string;

/** The thinking family — the only XML regions recognized mid-line and as orphan closers. */
declare const THINKING_FAMILY: readonly string[];
/**
 * THE raw-HTML tag allow-list: tags a model may emit as raw HTML that the renderer honors
 * (rich-content rehypeSafeRawHtml, the content splitter, the GFM table vectors and prose-prepare
 * all read this one set). Kept in sync with the pre-escape gate in BasicMarkdownContent — a tag
 * left un-escaped there must be allowed here, or it renders as literal text. Deliberately excludes
 * `div` (layout container) and any scripting or embedding tags (`script`, `style`, `iframe`,
 * `object`, `embed`, `form`…).
 */
declare const ALLOWED_RAW_HTML_TAGS: ReadonlySet<string>;
/**
 * `SPECIAL_CODE_LANGUAGES` — code-fence languages that promote to a first-class block type (the
 * fence language becomes the block type). Mirrors SPECIAL_CODE_LANGUAGES in aidream
 * block_detector.py — keep the two in lockstep. `html` and `react` are deliverables (a webpage, a
 * live component) that materialize into persistent artifacts; a ```matrx fence carries one Matrx
 * Envelope.
 */
declare const SPECIAL_CODE_LANGUAGES: ReadonlySet<string>;
/** `CODE_LANGUAGE_ALIASES` — fence-language aliases that normalize to a canonical special language (```mmd → mermaid; jsx/tsx render as a live React component). Mirrors block_detector.py. */
declare const CODE_LANGUAGE_ALIASES: Readonly<Record<string, string>>;

/**
 * THE HTML element list — the one place that says "this tag is real HTML".
 *
 * Why it exists (2026-10-21 production regression): the splitter, the source tokenizer and the
 * Python block detector claimed every line-leading tag that was not a Matrx tag and not on the
 * sanitizer's small raw-HTML allow-list (`ALLOWED_RAW_HTML_TAGS`) as a CUSTOM XML container. So
 * `<div>`, `<section>`, `<style>`, `<svg>` and a whole `<!DOCTYPE html>` page drew as a tag-named
 * XML section instead of as HTML. The allow-list answers "which tags may the markdown sanitizer
 * keep"; it was never "which tags are HTML". This list answers the second question.
 *
 * THE ORDER every reader applies to a line-leading `<…`:
 *   1. a code fence owns its bytes (nothing below runs inside one);
 *   2. HTML: a full document (`<!DOCTYPE html>`, `<html>`) → an `html` block (the page preview a
 *      ```html fence gets); `<svg>` → an `svg` block (a ```svg fence's image); any other element
 *      named here and NOT on the sanitizer allow-list → an `html` block; an allow-list tag stays in
 *      the text for the markdown renderer;
 *   3. a built-in Matrx tag (`KNOWN_XML_TAG_NAMES`) → its own block;
 *   4. only then an unknown tag (`<foo>`) → a custom XML section.
 * No name is in both this list and `KNOWN_XML_TAG_NAMES` (a test pins it), so 2 and 3 never fight.
 *
 * MARKUP, NOT A WORD: models also wrap answers in bare tags that happen to share an HTML name —
 * `<output>{…kind…}</output>`, `<source>…</source>`, `<title>…</title>` (SHAPES-BUGS 2.2 pins the
 * `<output>` wrapper). A browser draws such an element as its plain words, so it is not HTML that
 * needs rendering: it stays the custom section it always was. An element IS markup when its root is
 * one that is never a wrapper (`HTML_MARKUP_ROOTS`: a document, `<svg>`, `<style>`, `<script>`,
 * `<iframe>`, `<form>` …), when its opener carries attributes (`<div style="…">`), or when its
 * inside holds an HTML tag (`<div>\n<p>…</p>\n</div>`). `htmlElementIsMarkup` decides a closed
 * element; `htmlOpenerIsMarkup` decides from the opener alone while it is still arriving.
 *
 * Scope: every element of the WHATWG HTML standard, the obsolete ones browsers still parse and
 * models still write (`center`, `font`, `marquee`, …), and the two foreign ROOTS `svg` and `math`.
 * SVG and MathML child names (`rect`, `text`, `filter`, `mi`) are deliberately not here: inside
 * their root they are already claimed with it, and as a root of their own they are ordinary words
 * a custom section may use (`<text>`, `<filter>`, `<pattern>`).
 *
 * Twin: aidream `matrx_ai/processing/blocks/html_elements.py` — the shared html-root vectors pin
 * the two lists equal.
 */
declare const HTML_ELEMENT_NAMES: ReadonlySet<string>;
/** The tag is a real HTML element (or the `<svg>` / `<math>` root). Case-insensitive. */
declare function isHtmlElementName(name: string): boolean;
/** The trimmed line opens a full HTML document with its doctype (`<!DOCTYPE html>`). */
declare function isHtmlDoctypeLine(trimmed: string): boolean;
/** What a line-leading HTML root becomes. */
type HtmlRootKind = "document" | "svg" | "fragment";
/**
 * Which HTML root the trimmed line opens, or null when it opens none of them. `tag` is the root
 * element name as written (`html` for a doctype). An allow-list tag (`<details>`, `<table>`,
 * `<p>`, …) returns null: the markdown renderer draws it in place, as it always has.
 */
declare function htmlRootOf(trimmed: string, allowedRawHtml: ReadonlySet<string>): {
    kind: HtmlRootKind;
    tag: string;
} | null;
/**
 * Roots that are never a word a model wraps prose in: their content is code, media or a form, or
 * they are a document. Always HTML, attributes or not.
 */
declare const HTML_MARKUP_ROOTS: ReadonlySet<string>;
/** The trimmed opener alone already reads as HTML markup: a markup root, or a tag with attributes. */
declare function htmlOpenerIsMarkup(trimmed: string): boolean;
/**
 * A closed element (`element` runs from its opener through its closer) is HTML markup: its opener
 * reads as markup, or its inside holds a tag with an HTML element name. A bare HTML-named tag around
 * plain words, markdown or JSON (`<output>{…}</output>`) is a wrapper, not markup.
 */
declare function htmlElementIsMarkup(element: string): boolean;

/**
 * UTF-16 ⇄ code-point offset conversion.
 *
 * JavaScript strings are indexed in UTF-16 code units; Postgres `position()`,
 * `substring()` and `length()` count code points. Every offset this module
 * emits is given in BOTH units so an anchor captured on either side of the
 * wire can be mapped without re-deriving the text.
 */
/** Indexes the surrogate pairs of one text so conversion is O(log pairs). */
interface CodePointIndex {
    /** Code-point offset of a UTF-16 offset. */
    toCodePoint(utf16: number): number;
    /** UTF-16 offset of a code-point offset. */
    toUtf16(codePoint: number): number;
    /** Code-point length of the text. */
    readonly lengthCp: number;
}
/** True when `offset` sits between the two halves of a surrogate pair. */
declare function splitsSurrogatePair(text: string, offset: number): boolean;
declare function buildCodePointIndex(text: string): CodePointIndex;
/** One-shot conversion; build an index when converting many offsets. */
declare function toCodePointOffset(text: string, utf16: number): number;
/** One-shot conversion; build an index when converting many offsets. */
declare function toUtf16Offset(text: string, codePoint: number): number;

/**
 * THE single-dollar math rule — the one predicate that decides whether a
 * CLOSED `$…$` is inline math or currency, on screen, in every export and in
 * the editor's islands (the renderer's normalizer, the source tokenizer and
 * print all ask it).
 *
 * Pandoc's `tex_math_dollars` delimiters (what remark-math approximates, and
 * how ChatGPT and Claude render): the opening `$` is followed by a
 * non-space, the closing `$` is preceded by a non-space and not followed by a
 * digit — so `$5 and $10`, `$5-$10`, `$5/$10` stay currency while `$FC$`,
 * `$AB$`, `$5$` and `$(0, 0)$` are math. On top of that, content that reads as
 * something other than a formula is refused — each guard is a false positive
 * measured in stored answers (matrx-frontend
 * `scripts/measure-single-dollar-rule.ts`, 2026-09-25: over 85k assistant
 * messages and 4k notes the widening adds 128 spans, every one a formula
 * (`$FC$`, `$(0, 0)$`, `$3x + 6 = 15$`), and drops 22 the old rule drew as
 * math that were code, template literals, a printf or broken TeX):
 *   - an unescaped `%` — TeX's comment character, and a percentage
 *     (`$\ge$20% owners**…**$`, a printf `%1$s`);
 *   - a closing bracket or `/` first, or an opening bracket last
 *     (`[$X] plus [$Y]`, `($/SF/Yr) | High-Cost Market ($`, a regex
 *     `/…/, '').replace(/…$`), or a straight quote at either end (`["$", "$"]`
 *     in data);
 *   - `:` `;` `,` `/` last — a separator between two `$` words
 *     (`$HOME/.local/bin:$PATH`, `$AAPL/$TSLA`);
 *   - a number glued to a following letter (`$10$N9qo…`, a bcrypt cost);
 *   - a placeholder (`$...$`);
 *   - prose, unless a TeX command or operator says otherwise: two plain
 *     words (`$Tipping (fee)$`), a contraction (`$I'm$`, never `$X'Y$`), an
 *     abbreviation (`$e.g. (x)$`);
 *   - a shell or template variable chain (`$USER$HOSTNAME`, `$name.$ext`,
 *     `${a}${b}`) — {@link isVariableChain}.
 *
 * `after` is the text right after the closing `$` — {@link singleDollarAfter}
 * (up to {@link AFTER_WINDOW} characters; `\n` marks the end of the text). A single character still
 * applies the Pandoc digit rule, but the variable-chain guard needs the
 * whole following name.
 */
declare function isSingleDollarMath(content: string, after: string | undefined): boolean;
/**
 * Whether an UNCLOSED `$…` already reads as a formula — for a stream that
 * must decide before the closing `$` arrives (matrx-frontend `stream-heal`
 * holds such a tail back instead of printing raw TeX). Stricter than
 * {@link isSingleDollarMath} on purpose: with no closer there are no Pandoc
 * delimiter facts yet, so it needs a math SIGNAL — a TeX command or operator
 * (`\alpha`, `^`, `_`, `{`, `=`, …), a lone variable (`x`, `x'`), or a
 * single-letter math shape (`f(g(x))`, `u v`). Content that opens with a digit
 * needs a real TeX command, so `$35 per stop` keeps showing while it streams.
 */
declare function looksLikeOpenInlineMath(partial: string): boolean;
/**
 * Where a single-dollar math span opened at `open` (a lone `$`) closes, or -1.
 * Same scan the normalizer uses: same line, backslash-escapes skipped, the
 * closer is a `$` not followed by another `$`, and the content passes
 * {@link isSingleDollarMath}. Returns the offset just past the closing `$`.
 */
/** How much text after a closing `$` the rule reads (a glued suffix or the next variable name). */
declare const AFTER_WINDOW = 32;
/**
 * The `after` argument of {@link isSingleDollarMath} for the closing `$` at
 * `close`: the next {@link AFTER_WINDOW} characters, with a `\n` standing for
 * the end of the text (so `$A$B` at the very end reads the whole name `B`).
 */
declare function singleDollarAfter(text: string, close: number): string;
declare function singleDollarMathEnd(text: string, open: number, limit?: number): number;
/**
 * THE escaped-bracket rule — whether a closed `\[ … \]` is display math or
 * CommonMark's escaped brackets (literal `[ … ]`). The tokenizer, the
 * renderer's normalizer and the editor all ask it.
 *
 * Math only when the content is real TeX (BRACKET_TEX_SIGNAL) and the `\[`
 * is not an index on an identifier (`arr\[i+1\]`, `f(x)\[k\]`).
 * Everything a person writes with escaped brackets stays text: citations
 * `\[1\]`, dates `\[2026-09-25\]`, task boxes `- \[x\]`, editorial
 * insertions `\[was\]`, placeholders `\[site name\]` (verify-RC-B4 R3-2).
 * `before` is the character just before the `\[` (undefined at the start).
 */
declare function isEscapedBracketMath(content: string, before: string | undefined): boolean;

interface ReadXmlTag {
    tagName: string;
    raw: string;
    isClosing: boolean;
    isSelfClosing: boolean;
    attributes: Array<{
        name: string;
        value: string;
    }>;
}
/**
 * `find(needle, from)` must behave like `content.indexOf(needle, from)`; the
 * tokenizer passes a cached occurrence index so a text full of unclosed
 * attribute quotes stays linear. Behavior is identical either way.
 */
declare function readXmlTag(content: string, start: number, find?: (needle: string, from: number) => number): ReadXmlTag | null;
/**
 * Balances ONE unknown root tag line by line, ignoring lookalike tags inside
 * fenced code, inline code spans, comments and CDATA. `consumeLine` returns
 * the offset (within that line) just past the root's closing tag, or null.
 */
declare class XmlContainerTracker {
    readonly rootTag: string;
    private depth;
    private inComment;
    private inCdata;
    private inlineTicks;
    /** The open fence, read by THE one closer (source/code-ranges.ts). */
    private fence;
    constructor(rootTag: string);
    consumeLine(line: string, startOffset?: number): number | null;
}

/** Fence languages whose body is itself a markdown document. */
declare const NESTING_FENCE_LANGUAGES: ReadonlySet<string>;
/** True when a fence opened with this info-string language nests inner fences. */
declare function fenceNestsInnerFences(language: string | undefined | null): boolean;
type InnerFenceLine = 
/** Not a fence line — ordinary content of the outer fence. */
"content"
/** ```lang inside a markdown fence — content, and one level deeper. */
 | "open-nested"
/** Bare ``` that closes the innermost nested fence — content, one level up. */
 | "close-nested"
/** Bare ``` that closes the OUTER fence. */
 | "close-outer";
/**
 * Classify one line inside an open backtick fence, already trimmed with
 * {@link trimFenceLine} (never a language's own `trim()`).
 *
 * @param trimmed     the line with surrounding whitespace removed
 * @param openTicks   backtick count of the outer fence's opener
 * @param nests       whether the outer fence follows the nesting rule
 * @param nestedDepth how many nested fences are open right now
 */
/**
 * The whitespace a fence line may carry around its backticks and info string:
 * CommonMark's ASCII whitespace — space, tab, LF, CR, form feed, vertical tab.
 * Defined HERE, not by a language's `trim()`: JavaScript's `trim()` also strips
 * U+FEFF, U+00A0 and the Unicode spaces, while Python's `strip()` also strips
 * U+0085 and U+001C–U+001F — which made the two twins disagree on lines such
 * as ```` ```\uFEFF ```` (verify-RC-B3 residual R4). Every caller trims a line
 * with `trimFenceLine` before classifying it; the Python twin mirrors both.
 */
declare const FENCE_WHITESPACE = " \t\n\r\f\v";
/** Strip {@link FENCE_WHITESPACE} (and nothing else) from both ends of a line. */
declare function trimFenceLine(line: string): string;
/**
 * The whitespace around a fence OPENER and inside its info string. The
 * renderer finds openers with JavaScript's `String#trim()` and splits the info
 * string on `/\s/`; this set IS that definition, written out so the Python
 * twin can match it exactly — ECMAScript WhiteSpace + LineTerminator. It
 * differs from Python's `str.split()` on U+0085 and U+001C–U+001F (not JS
 * whitespace) and U+FEFF (JS whitespace) — verify-RC-B3 residual R4′.
 */
declare const FENCE_OPENER_WHITESPACE = "\t\n\v\f\r \u00A0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF";
/**
 * Parse a backtick fence OPENER line the way the renderer does: trim the line,
 * count the backtick run (3+), trim the rest, and take the first
 * whitespace-separated word as the language. null when the line opens nothing —
 * including when the info string holds a backtick (GFM / CommonMark 4.5:
 * "```` code ````" and "``` `x` | b" are code spans, never fences).
 */
declare function parseFenceOpener(line: string): {
    ticks: number;
    lang: string;
} | null;
declare function classifyInnerFenceLine(trimmed: string, openTicks: number, nests: boolean, nestedDepth: number): InnerFenceLine;

/** Box-drawing glyphs that mark a tree diagram line. */
declare const TREE_GLYPHS: RegExp;
/**
 * An ASCII connector after any run of rails: `+--`/`|--` (a dash right after the `+`/`|`),
 * or a last branch `` `-- `` (dashes then a space, so a line opening with `` `--flag` `` stays prose).
 * A bare `| ` is a table row's edge, never a connector. Spacing is `[ \t]`, never `\s`: the
 * languages' `\s` differ, and this rule must read the same in both.
 */
declare const ASCII_TREE_CONNECTOR: RegExp;
/** Fewer tree lines than this are prose, not a tree. */
declare const MIN_TREE_LINES = 3;
/** True when `line` is a tree diagram line (box glyphs, or an ASCII connector that is not a GFM delimiter row). */
declare function isTreeLine(line: string): boolean;

/**
 * THE link-reference rule (CommonMark 4.7 / 6.3) for surfaces that read one
 * piece of a document at a time — a table cell, a split chat block, a printed
 * row — and so cannot see the document's `[label]: url "title"` definitions.
 * `collectLinkDefinitions` reads them from the WHOLE text (never inside fenced
 * code); `resolveReferenceLinks` rewrites a fragment's full (`[text][label]`),
 * collapsed (`[label][]`) and shortcut (`[label]`) reference links into inline
 * links (`[text](url "title")`) so any renderer shows what GFM shows. Code spans,
 * images, inline links, footnote references and undefined labels are left as
 * they are. verify-RC-B4 round 9 (R9-4).
 *
 * Pure TS, no dependencies.
 */
interface LinkDefinition {
    url: string;
    title: string | null;
}
/** CommonMark label matching: case-folded, inner whitespace collapsed, trimmed. */
declare function normalizeLinkLabel(label: string): string;
/** Every link reference definition in `text` (first one wins, as in CommonMark); fenced code is skipped. */
declare function collectLinkDefinitions(text: string): Map<string, LinkDefinition>;
/** The line indices (text split on "\n") that ARE link reference definitions — GFM renders nothing for them. */
declare function findLinkDefinitionLines(text: string): number[];
/**
 * `fragment` with every reference link whose label is defined rewritten inline.
 * An image (`![alt][ref]`) resolves too. Nothing else changes.
 */
declare function resolveReferenceLinks(fragment: string, defs: ReadonlyMap<string, LinkDefinition>): string;

interface CodeRange {
    /** UTF-16 offset of the first character (the fence line start, or the opening backtick run). */
    start: number;
    /** Offset just past the closing fence line's content / closing backtick run (the fence's last line when unclosed). */
    end: number;
    kind: "fence" | "span";
}
interface FenceOpener {
    char: "`" | "~";
    /** Length of the opening run. */
    ticks: number;
    /** The info string's first word ("" when none). */
    lang: string;
}
/**
 * THE opener rule for one line's content (container prefixes already
 * removed; for a tilde fence, `content` starts at the container's column).
 */
declare function fenceOpenerOf(content: string): FenceOpener | null;
/** The lines a fence is read from. */
interface FenceLines {
    count: number;
    /** Line `k`'s content (no terminator), or null when the fence's container has ended before it. */
    line(k: number): string | null;
    /** Streaming: line `k` has not ended yet, so it closes nothing. */
    openTail?(k: number): boolean;
    /**
     * Streaming: more lines may still arrive. The strict-CommonMark retry
     * applies only while the nested reading ends inside a nested fence — a
     * later line can close that nested fence, so a retry's closer is
     * undecided and the fence stays open (verify-RC-B3 F3).
     */
    streaming?: boolean;
}
interface FenceEnd {
    /** The closing line when `closed`; otherwise the fence's last line (text end, or the line before its container ended). */
    line: number;
    closed: boolean;
}
declare class FenceReader {
    readonly opener: FenceOpener;
    private depth;
    /** A nested fence was opened at some point. */
    sawNested: boolean;
    private readonly isJson;
    private readonly nesting;
    private readonly tildeCloser;
    constructor(opener: FenceOpener, options?: {
        nesting?: boolean;
    });
    /** How many nested fences are open right now. */
    get nestedDepth(): number;
    feed(line: string): boolean;
}
/** Where the fence opened on line `open` ends. */
declare function closeFence(src: FenceLines, open: number, opener: FenceOpener): FenceEnd;
/**
 * THE code-span pairing table for one paragraph, text[from, to): a backtick
 * run closes at the first LATER run of exactly its length; a run with none is
 * literal text. `findCodeRanges` pairs runs in order; the tokenizer's inline
 * scanner asks `next` in the renderer's leftmost-first inline order.
 */
declare class BacktickRuns {
    /** Every run, in order: [start, length]. */
    readonly all: Array<[number, number]>;
    private readonly byLength;
    private readonly indexOf;
    constructor(text: string, from: number, to: number);
    /** Start of the first run of exactly `n` backticks at or after `after`, or -1. */
    next(n: number, after: number): number;
    /** Index of the run starting at `start` in `all`. */
    index(start: number): number;
}
/**
 * Every code range in the text — fences (by the renderer's rule above) and
 * inline code spans — sorted by start. Linear: one pass over lines, one over
 * each paragraph's backtick runs.
 */
declare function findCodeRanges(text: string): CodeRange[];
/**
 * Rewrite every code range (fences and spans, by THE rule) through `fn`; text
 * outside code is kept byte for byte. The one way to strip, replace or
 * placeholder code in markdown — never a private /```…```/ regex.
 */
declare function mapCodeRanges(text: string, fn: (range: CodeRange, raw: string) => string): string;
/**
 * The code SPANS in one piece of INLINE content — a table cell, a heading's
 * text, a link label — where no block structure exists, so a line opening with
 * three or more backticks is a code span, never a fence (```` `` code `` ```` in a
 * GFM cell). Same scanner and escape rules as `findCodeRanges`' span pass.
 */
declare function findInlineCodeSpans(text: string): CodeRange[];
/** Rewrite every code SPAN of inline content through `fn` (see `findInlineCodeSpans`); other text is kept byte for byte. */
declare function mapInlineCodeSpans(text: string, fn: (range: CodeRange, raw: string) => string): string;
/** A code span's text (CommonMark): the backtick runs off, then one padding space each side when both are there and the content is not all spaces. */
declare function codeSpanText(raw: string): string;
/**
 * A fence range's parts: its opener, its body (the lines between the opener
 * and the closer, blockquote prefixes kept), and whether it closed. Reads
 * `raw` exactly as `findCodeRanges` returned it.
 */
declare function fenceParts(raw: string): {
    opener: FenceOpener;
    body: string;
    closed: boolean;
} | null;
type FenceLineKind = "prose" | "open" | "body" | "close";
/**
 * Where each line (the text split on "\n") sits relative to the fences
 * `findCodeRanges` finds: its opener, its body, its closer, or prose. For a
 * line walker that must skip code — one rule, never a private `inFence` toggle.
 */
declare function fenceLineKinds(text: string): FenceLineKind[];
/**
 * STREAMING: where the last, still-growing paragraph (no blank line or fence
 * after it) holds a backtick run that a later run could still close — a run
 * with no later run of its length, or the run touching the end of the text
 * (it may still lengthen). Such a code span can yet swallow any `$$` after it,
 * so a streaming tokenizer treats text from there as provisional. -1 if none.
 */
declare function pendingCodeSpanStart(text: string): number;

/**
 * `$$...$$`, `$$…$$`, `$$ · $$`: a PLACEHOLDER — prose describing the syntax,
 * never a formula. The pair is consumed whole as literal text (neither `$$`
 * may open the next span).
 */
declare function isMathPlaceholder(inner: string): boolean;
/**
 * The guard's `looksLikeMath`. `flow` = the opener is alone on its line: a
 * flow block may span blank lines (like a fence); a `$$` with text beside it
 * never crosses one — TeX's rule, and what keeps a stray prose `$$` from
 * pairing with the next paragraph's formula.
 */
declare function looksLikeDisplayMath(inner: string, flow?: boolean): boolean;

/**
 * STREAMING: the last `$$` token that is still unpaired AND could still pair
 * with a `$$` not yet arrived — its span so far is short enough, carries no
 * markdown structure, not too many prose words, and (unless it opens a flow
 * block) no blank line. Everything after it may yet become math, so a
 * streaming tokenizer treats it as provisional. -1 when there is none.
 */
declare function pendingDisplayMathOpener(text: string): number;
/** Map of `$$` opener offset → closer offset for every pair the renderer shows as math. */
declare function pairDisplayMath(text: string): Map<number, number>;

/**
 * @ai-matrx/kit/delimiter-guard — stops ONE stray markdown delimiter from
 * swallowing a whole section of a streamed answer.
 *
 * THE FAILURE CLASS
 * -----------------
 * Markdown delimiters pair greedily and blindly. A single stray opener emitted
 * by a model (the common shape is a mangled citation:
 * `…/a-quicker-way-to-heal-prp-and-prf$$ .`) pairs with the next matching
 * delimiter anywhere later in the message, and everything in between —
 * headings, bold, links, whole sections — collapses into one node.
 *
 * Two delimiters cause this in a remark-math + CommonMark pipeline:
 *
 * 1. `$$` (remark-math). The swallowed prose becomes a math node, KaTeX fails
 *    to parse it, and `rehype-katex` falls back to its built-in error
 *    rendering: the raw source re-emitted inside `<span class="katex-error"
 *    style="color:#cc0000">`. The symptom is a huge block of BRIGHT RED
 *    unrendered markdown mid-answer. That red is KaTeX reporting a parse error
 *    on text that was never math — not a style of yours.
 * 2. `[` (CommonMark link label). The swallowed prose becomes the label of one
 *    enormous hyperlink — the same bug wearing blue instead of red.
 *
 * WHAT THIS DOES
 * --------------
 * Before the markdown pipeline runs, each candidate span is checked for
 * plausibility. A `$$…$$` span carrying markdown structure (links, URLs, bold,
 * headings, list markers) or reading as prose is not math; a link label that is
 * hundreds of characters long or contains block structure is not a label. The
 * offending OPENER is neutralized (`&#36;&#36;`, `&#91;`) and scanning resumes at the next
 * delimiter, so genuine math and genuine links later in the same message still
 * render. Real content is never touched.
 *
 * LOUD RECOVERY: every firing is a real upstream defect (a model emitting
 * malformed delimiters, or a producer mangling a citation). Callers report the
 * returned violations — see `reportDelimiterViolations`.
 *
 * Ported verbatim from matrx-frontend `lib/markdown/delimiter-guard.ts`, with
 * ONE coupling inversion: the app's `captureError` store import became the
 * injected `capture` sink on `reportDelimiterViolations`' context (payload
 * shape preserved exactly). No sink means console-only loud recovery.
 */
type DelimiterViolationReason = 
/** A `$$…$$` pair whose contents are prose/markdown, not math. */
"prose-span"
/** A `$$` with no closing partner in the content. */
 | "unpaired"
/** A `[…](…)` link whose label swallowed prose/structure. */
 | "runaway-link";
interface DelimiterViolation {
    reason: DelimiterViolationReason;
    /** Character offset of the offending delimiter in the input string. */
    index: number;
    /** Length of the span between the delimiters (0 for `unpaired`). */
    spanLength: number;
    /** Short excerpt of what would have been swallowed. */
    preview: string;
}
interface DelimiterGuardResult {
    /** Input with runaway openers escaped. */
    text: string;
    violations: DelimiterViolation[];
}
/**
 * Escapes `$$` delimiters that would make remark-math swallow non-math text.
 * Pure — safe to call on every render / stream chunk.
 */
declare function guardMathDelimiters(text: string): DelimiterGuardResult;
/**
 * Escapes the `[` of a markdown link whose label ran away — the link twin of
 * the stray-`$$` bug. An unclosed citation bracket pairs with a `]` hundreds of
 * characters later and turns an entire section into one hyperlink.
 *
 * Pure. Runs after the math guard so both share one escaping pass conceptually,
 * but each is independently usable.
 */
declare function guardRunawayLinks(text: string): DelimiterGuardResult;
/**
 * The front door: run every delimiter guard in order. Offsets in the returned
 * violations refer to each guard's own input, so they are for diagnostics only.
 */
declare function guardMarkdownDelimiters(text: string): DelimiterGuardResult;
/**
 * The payload handed to the injected capture sink — exactly the shape the
 * original passed to the Matrx `captureError` store. A Matrx host passes
 * `captureError` straight through; any host can log/report it its own way.
 */
interface DelimiterCaptureInput {
    source: "markdown-delimiters";
    message: string;
    relation: string;
    details: string;
    conversationId?: string | undefined;
    callSite: "guardMarkdownDelimiters";
    raw: {
        messageId?: string | undefined;
        violations: DelimiterViolation[];
    };
}
interface DelimiterReportContext {
    renderPath: string;
    messageId?: string | undefined;
    conversationId?: string | undefined;
    /**
     * Optional error-capture sink (a Matrx host passes its `captureError`).
     * Absent, the loud recovery is console-only. Must never be relied on to
     * throw — failures inside it are swallowed so capture can never break
     * rendering.
     */
    capture?: ((input: DelimiterCaptureInput) => void) | undefined;
}
/**
 * Loud recovery. A firing means malformed math delimiters reached the renderer
 * — the guard kept the message readable, but the producer is still emitting
 * broken content and must be found.
 */
declare function reportDelimiterViolations(violations: DelimiterViolation[], context: DelimiterReportContext): void;

declare function stripThinking(input: string): string;
declare function hasThinkingTags(input: string): boolean;
/**
 * Streaming-aware variant: handles partial `<thinking>` / `<reasoning>` blocks
 * whose closing tag hasn't arrived yet. Returns:
 *   - `visible`: text with all *closed* thinking/reasoning blocks removed AND
 *     any currently-open thinking block truncated (so the partial chain-of-
 *     thought never reaches the textarea or the clipboard).
 *   - `isThinking`: true when the stream is currently inside an unclosed
 *     `<thinking>` or `<reasoning>` tag — callers can render a "thinking..."
 *     animation while waiting for the close tag.
 * Tags inside code — including a fence or inline span still arriving — are
 * content, never an open block.
 */
declare function stripThinkingStreaming(input: string): {
    visible: string;
    isThinking: boolean;
};

/**
 * THE GFM table rule — one splitter, one cell-pipe rule, one "where does a
 * table start and run" — for every surface that reads a markdown table: the
 * chat splitter and live stream, the table renderers and editors, the rich
 * editor's writer, the print package, and (by shared vectors) the Python block
 * detector. verify-RC-B4 R4/R5/R6.
 *
 * - A `|` is a cell boundary unless an ODD run of backslashes precedes it
 *   (`\|` is a pipe inside the cell; `\\|` is an escaped backslash and then a
 *   boundary). Code spans get no special treatment: GFM splits rows before
 *   inline parsing, so an unescaped `|` inside backticks is a boundary too.
 * - A cell's `\|` shows as `|` — inside code spans too (spec example 200).
 * - A table starts at a header line whose NEXT line is a delimiter row (`--- |
 *   :-:`, edge pipes optional, never a list item such as `- | -`) of the SAME
 *   width; the header needs no pipe of its own (`Notes` over `|---|` is a
 *   one-column table), is not indented code, and is not a lazy continuation of a
 *   list item's or quote's paragraph. It runs to a blank line, a
 *   line that starts another block (`- x`, `> y`, `# z`, `1.`, a fence, a rule,
 *   an HTML block — CommonMark 4.6's seven start conditions), or a line indented
 *   four or more columns past the table's container (indented code); every other
 *   line is a row, with or without a pipe (spec example 202), a lone `|` included
 *   (an empty row).
 *
 * Pure TS, no dependencies.
 */
/** The row's bytes between boundaries (edge segments included). */
declare function splitRowSegments(line: string): string[];
/** A row's cell texts as GFM reads them (source bytes, trimmed; edge pipes dropped). */
declare function rowCells(line: string): string[];
/** GFM's table-level unescape: a cell's `\|` is a pipe, in code spans too. */
declare function unescapeCellPipes(cell: string): string;
/**
 * The trimmed line opens an HTML block whose element every sanitizer strips: the
 * block ends at this line (the one deliberate GFM deviation, above).
 */
declare function opensStrippedHtmlBlock(trimmed: string): boolean;
/**
 * A tag name CommonMark reads as an HTML BLOCK when it opens a line (conditions
 * 1 and 6: `div`, `details`, `section`, `script`, …; case-insensitive). A
 * line-leading tag with such a name is HTML — the markdown renderer's, ending
 * where GFM ends it — never a custom XML container that owns what follows.
 * verify-RC-B4 round 9. This is CommonMark's HTML-BLOCK set (where a table or paragraph
 * ends); "is this tag real HTML at all" is the superset `isHtmlElementName` (html-elements.ts),
 * which every never-a-custom-section check reads. A test pins this set inside that one.
 */
declare function isHtmlBlockTagName(name: string): boolean;
/** The trimmed line starts an HTML block (any of CommonMark 4.6's seven conditions). */
declare function startsHtmlBlock(trimmed: string): boolean;
/** The column a line's content starts at: spaces count 1, a tab runs to the next multiple of 4. */
declare function lineIndent(line: string): number;
/**
 * The content column of the container a table at `start` sits in: the list item
 * whose content the header line belongs to (the nearest list-marker line above,
 * past blank and continuation lines, whose content column is at or left of the
 * header's), or 0 at top level. Indentation past it by 4+ columns is indented
 * code, which ends the table.
 */
declare function tableContainerIndent(lines: readonly string[], start: number): number;
/** A GFM delimiter row: every cell `---`, `:--`, `--:` or `:-:`, with at least one pipe. */
declare function isGfmDelimiterRow(line: string): boolean;
/** A pipe-led row: `|` first, and another `|` after it. */
declare function isPipeLedRow(line: string): boolean;
/**
 * True when `header` + `delimiter` open a table whose header is NOT a pipe-led
 * row: `a | b` (no edge pipes), `| a` (one pipe), or even `Notes` (no pipe — a
 * one-column table over `|---|`). The delimiter must match the header's width.
 */
declare function startsPipelessTable(header: string, delimiter: string | undefined): boolean;
/**
 * A line that continues an open table — GFM's rule (spec example 202): the table
 * runs to the first blank line, the first line that starts another block (an
 * HTML block included), or the first line indented 4+ columns past the table's
 * container (`containerIndent`, from `tableContainerIndent`; indented code). Any
 * other line is a row, even one without a pipe (`bar` → a one-cell row) and a
 * lone `|` (an empty row). verify-RC-B4 R7-2 / round 9.
 */
declare function continuesTable(line: string, containerIndent?: number): boolean;
/** Line `index` opens a table: a pipe-led row, or a pipe-less GFM header over its delimiter row. */
declare function opensTable(lines: readonly string[], index: number): boolean;
/** A WHOLE table header at `index`: a table opens here AND its next line is a GFM delimiter row. */
declare function tableStartsAt(lines: readonly string[], index: number): boolean;
/** Index of the first line at or after `from` that opens a table; -1 when none. */
declare function findTableStart(lines: readonly string[], from?: number): number;
/** Index just past the table whose header is at `start` (header, delimiter, then continuation rows). */
declare function findTableEnd(lines: readonly string[], start: number): number;
/** A line that starts like a pipe-led row — even a lone `|` still growing. */
declare function startsLikeTableRow(line: string): boolean;
/** A delimiter row still arriving: only pipes, colons, dashes and spaces, with a dash so far. */
declare function isGrowingDelimiterRow(line: string): boolean;

/** Replace every inline code span with its text (`x` → x); fences untouched. */
declare function unwrapCodeSpans(text: string): string;
/** Remove every inline code span entirely; fences untouched. */
declare function removeCodeSpans(text: string): string;
/**
 * Rewrite every fenced code block. `fn` gets the fence's language ("" when
 * none), its body, and whether it closed; an unclosed fence (a stream still
 * arriving) runs to the end of the text. Code spans and prose are untouched.
 */
declare function replaceFences(text: string, fn: (fence: {
    lang: string;
    body: string;
    closed: boolean;
    raw: string;
}) => string): string;
/**
 * When the whole (trimmed) text is ONE fenced block — an LLM's ```json … ```
 * payload — its language and body; otherwise null. `allowUnclosed` accepts a
 * fence still streaming (no closer yet).
 */
declare function soleFence(text: string, options?: {
    allowUnclosed?: boolean;
}): {
    lang: string;
    body: string;
    closed: boolean;
} | null;

/**
 * Markdown → plain text, for places that must show WORDS rather than render a
 * document: table cells, tooltips, meta descriptions, chart labels, aria-labels,
 * exported slide text.
 *
 * This is NOT a renderer and never competes with one. When the surface can
 * afford real formatting, render the markdown through the canonical path
 * (`BasicMarkdownContent` / `MarkdownStream`) instead. Reach for this only when
 * a single line of text is the product — where a rendered `<strong>` cannot go
 * and raw `**asterisks**` would otherwise reach a user's eyes.
 *
 * Deliberately conservative: it unwraps the inline emphasis markers people
 * actually hit (bold, italic, inline code, strikethrough, links) and leaves
 * everything else alone. Stray, unpaired `*` and `_` survive untouched, because
 * a lone asterisk in prose is prose — mangling it would be worse than the
 * problem this solves.
 */
/** Make one math expression's INNER content readable as words. */
declare function mathToReadable(expression: string): string;
/**
 * Strip inline markdown emphasis so the text reads cleanly as prose.
 *
 * Returns "" for nullish input so callers can pass a possibly-absent DB column
 * straight in.
 */
declare function markdownToPlainText(value: string | null | undefined): string;
/**
 * THE markdown an artifact's body was written as, so text taken out of its home
 * is the same block again wherever it lands (live 2026-10-19: Copy as Markdown on a
 * chart answer wrote bare JSON, and a paste anywhere was a code block, not a chart).
 *
 * - A body that is already a fence or a known XML block, or a markdown type (a table), is kept.
 * - A fence-promoted type (chart, mermaid, svg, map, stats, diff, tasks, html, react …)
 *   gets its own fence: ```chart.
 * - An XML-tagged type (timeline, flashcards, cooking_recipe …) gets its tag back.
 * - A kind value (`__kind`) and any other JSON body (a quiz, a comparison) is a ```json
 *   fence: the splitter types those by their `__kind` or root key.
 * - Anything else is kept as written.
 */
declare function artifactBodyAsMarkdown(type: string | null | undefined, body: string): string;
/**
 * Stored content → the READABLE markdown a person meant, for places that take
 * the text OUT of its home (a flashcard back, a task description, a clipboard
 * copy). Kind envelopes are storage plumbing, not words: an
 * `<artifact …>body</artifact>` wrapper (a materialized table, a chart) is
 * replaced by its body written the way it renders (`artifactBodyAsMarkdown`):
 * a table stays a markdown table, a chart becomes its ```chart fence again, so a
 * reader never sees the raw tag and a paste anywhere is the same block. Everything
 * else is kept byte for byte — the offset-preserving source tokenizer draws the
 * boundaries, so a code fence that merely MENTIONS `<artifact>` is untouched.
 */
declare function unwrapKindEnvelopes(value: string | null | undefined): string;

declare const cleanMarkdown: (text: string) => string;

/** Where a code block carries its raw fence meta (block.metadata / stream block data). */
declare const FENCE_META_KEY = "fenceMeta";
interface FenceInfo {
    /** The language token alone (`ts`), or undefined for a bare fence. */
    language?: string;
    /** Everything after the language, verbatim; undefined when empty. */
    meta?: string;
}
interface FenceMeta {
    /** A filename or caption shown in the code block header. */
    title?: string;
    /** 1-based line numbers to highlight, ascending, deduplicated. */
    highlightLines: number[];
    /** Explicit line-number request (`showLineNumbers`). */
    showLineNumbers?: boolean;
    /** First line number when numbering starts somewhere other than 1. */
    startLine?: number;
}
/** Split `ts:app.tsx {1,3} title="x"` into the language token and its meta. */
declare function splitFenceInfo(info: string): FenceInfo;
/** Parse a fence's meta string (from splitFenceInfo) into render options. */
declare function parseFenceMeta(meta: string | undefined | null): FenceMeta;
/** `1,3-5, 9` → [1, 3, 4, 5, 9]. Malformed parts are skipped. */
declare function parseLineRanges(spec: string): number[];

/** A line that opens a container directive: 3+ colons, then a name. */
declare const DIRECTIVE_CONTAINER_OPEN: RegExp;
declare class DirectiveContainerTracker {
    private readonly stack;
    private fence;
    constructor(openingLine: string);
    /** Feed the next line (after the opener). True once the outermost container has closed on this line. */
    consume(line: string): boolean;
}

declare const TITLED_IMAGE_LINE: RegExp;

declare function isInsideInlineCode(line: string, at: number): boolean;
/** Index of the first `needle` in `line` at or after `from` that is not inside inline code. */
declare function indexOutsideInlineCode(line: string, needle: string, from?: number): number;
/**
 * Whether `text` (a line still arriving) holds a backtick run with no closing
 * run of the same length yet — a code span that may still close. A kind
 * after it may be inside that span (quoted source), so a live split waits
 * for the line to end, when the span rule above answers for certain.
 */
declare function hasUnclosedBacktickRun(text: string): boolean;

interface XmlBalanceState {
    /** Open same-name sections, counting the container itself (starts at 1). */
    depth: number;
    /** The fenced code block we are inside, read by THE one closer (@ai-matrx/content-ir/source). */
    fence: FenceReader | null;
}
declare function initialXmlBalance(): XmlBalanceState;
interface XmlBalanceOptions {
    /** Ignore tags inside ``` / ~~~ fenced code (default true). */
    trackFences?: boolean;
    /** Count nested same-name openers (default true). False = first closer wins. */
    nest?: boolean;
}
/**
 * Scan ONE line inside an open `<tagName>` section, in source order.
 *
 * Returns the character index where the container's own closing tag starts
 * (the closer that brings depth to zero), or -1 when the section is still
 * open after this line. Mutates `state` (depth and fence tracking).
 */
declare function findBalancedXmlClose(line: string, tagName: string, state: XmlBalanceState, { trackFences, nest }?: XmlBalanceOptions): number;

/**
 * Index of the first WHOLE table header at or after `from` (THE rule's
 * `tableStartsAt`: a same-width delimiter row under it, no lazy line, no indented
 * code); -1 when none. `findTableStart` is the streaming-lenient twin (a pipe-led
 * row opens before its delimiter arrives).
 */
declare function findWholeTableStart(lines: readonly string[], from?: number): number;
/**
 * The trailing lines of a streaming text that belong to a table being written
 * (pipe-led rows, even partial; pipe-less rows once a delimiter follows the
 * header): the start index, or `end` when the tail is not a table. A lone
 * pipe-less line is never claimed — it may be prose.
 */
declare function trailingTableStart(lines: readonly string[], end?: number): number;

export { AFTER_WINDOW, ALLOWED_RAW_HTML_TAGS, ASCII_TREE_CONNECTOR, BacktickRuns, CALLOUT_NAMES, CODE_LANGUAGE_ALIASES, DIRECTIVE_CONTAINER_OPEN, DirectiveContainerTracker, EXAMPLE_VARIABLE_MARK, FENCE_META_KEY, FENCE_OPENER_WHITESPACE, FENCE_WHITESPACE, FenceReader, HTML_ELEMENT_NAMES, HTML_MARKUP_ROOTS, LANGUAGE_OPTIONS, MIN_TREE_LINES, NESTING_FENCE_LANGUAGES, PROMPT_BLOCK_NAME, SPECIAL_CODE_LANGUAGES, SourceSpliceError, THINKING_FAMILY, TITLED_IMAGE_LINE, TREE_GLYPHS, XmlContainerTracker, analyzeVariableUsage, artifactBodyAsMarkdown, blockAt, blockEdit, blockRangeEdit, buildCodePointIndex, classifyInnerFenceLine, cleanMarkdown, closeFence, codeSpanText, collectLinkDefinitions, continuesTable, extensionForLanguage, fenceLineKinds, fenceNestsInnerFences, fenceOpenerOf, fenceParts, findBalancedXmlClose, findCodeRanges, findInlineCodeSpans, findLinkDefinitionLines, findPromptBlockTokens, findTableEnd, findTableStart, findVariableSections, findVariableTokens, findWholeTableStart, guardMarkdownDelimiters, guardMathDelimiters, guardRunawayLinks, hasThinkingTags, hasUnclosedBacktickRun, htmlElementIsMarkup, htmlOpenerIsMarkup, htmlRootOf, indexOutsideInlineCode, initialXmlBalance, isDeclarableVariableName, isEscapedBracketMath, isExampleVariableToken, isGfmDelimiterRow, isGrowingDelimiterRow, isHtmlBlockTagName, isHtmlDoctypeLine, isHtmlElementName, isInsideInlineCode, isMathPlaceholder, isPipeLedRow, isPromptBlockToken, isSingleDollarMath, isTreeLine, islandEdit, joinSource, languageFromName, lineIndent, listIslands, looksLikeDisplayMath, looksLikeOpenInlineMath, mapCodeRanges, mapInlineCodeSpans, mapPosition, mapRange, markdownToPlainText, mathToReadable, normalizeLinkLabel, opensStrippedHtmlBlock, opensTable, pairDisplayMath, parseFenceMeta, parseFenceOpener, parseLineRanges, pendingCodeSpanStart, pendingDisplayMathOpener, promptBlockReferencesIn, promptBlockToken, readXmlTag, removeCodeSpans, replaceFences, reportDelimiterViolations, resolveReferenceLinks, rowCells, sanitizeVariableName, sectionMarkerOf, singleDollarAfter, singleDollarMathEnd, soleFence, spliceSave, splitFenceInfo, splitRowSegments, splitVariableText, splitsSurrogatePair, startsHtmlBlock, startsLikeTableRow, startsPipelessTable, stripThinking, stripThinkingStreaming, tableContainerIndent, tableStartsAt, toCodePointOffset, toUtf16Offset, tokenizeSource, trailingTableStart, trimFenceLine, unescapeCellPipes, unwrapCodeSpans, unwrapKindEnvelopes, variableReferencesIn, wrapInSection, wrapSelectionInText };
export type { BlockIslandType, CodePointIndex, CodeRange, DelimiterCaptureInput, DelimiterGuardResult, DelimiterReportContext, DelimiterViolation, DelimiterViolationReason, DisturbedIsland, FenceEnd, FenceInfo, FenceLineKind, FenceLines, FenceMeta, FenceOpener, HtmlRootKind, InlineIslandType, InnerFenceLine, IslandMeta, IslandType, LanguageOption, LinkDefinition, MapOptions, MappedPosition, MappedRange, PromptBlockToken, ReadXmlTag, SectionMark, SourceBlock, SourceBlockKind, SourceChange, SourceEdit, SourceIsland, SourceSpan, SourceSpliceErrorCode, SpliceIntegrity, SpliceOptions, SpliceResult, TokenizeOptions, VariableSection, VariableSegment, VariableToken, VariableUsage, XmlBalanceOptions, XmlBalanceState };