@ai-matrx/content-ir 0.21.2 → 0.22.2

package/dist/surfaces.d.ts

@@ -0,0 +1,870 @@
+import { C as CanonicalBlockIR } from './ir-types-95bA2cXH.js';
+
+/**
+ * THE KIND SIGNAL of a JSON region's text — the one answer to "could this
+ * still be a kind?" (Arman, 2026-09-30):
+ *
+ *   1. The moment it COULD be a kind → display as a kind (its loader).
+ *   2. The moment we know WHICH kind → that kind (the parser's job).
+ *   3. The moment we know it is not a kind → it is JSON, and JSON is fine.
+ *
+ * "Could" is decided by the FIRST KEY. Until the first key has fully arrived
+ * the region is `undecided` and nothing raw is shown. A first key of `__kind`
+ * — or a `__kind` key anywhere in the text, at any depth, at any time — is
+ * `kind`. A complete first key that is anything else, with no `__kind` seen,
+ * is `not_kind`: the region streams live as JSON, and flips to `kind` the
+ * instant a `__kind` key shows up later.
+ *
+ * Pure and text-only on purpose: it must answer for every frame of every
+ * region, including ones whose parser never opened (an unlabelled fence, a
+ * reload, a plain markdown fence).
+ */
+type JsonKindSignal = "undecided" | "kind" | "not_kind";
+/**
+ * Options for the JSON-text readers: `json5` widens the key rule to JSON5's;
+ * `markdown` also reads the markdown-escaped key (`"\_\_kind"`, P8);
+ * `escaped` also reads the backslash-escaped key of a string-held kind
+ * (`\"__kind\"`, R3 round 6 — screen and search text only).
+ */
+interface KindTextOptions {
+    json5?: boolean;
+    markdown?: boolean;
+    escaped?: boolean;
+    /** Also read a Python-repr key (`{'__kind': 'flashcard_set'}`) — text contexts only (K4). */
+    python?: boolean;
+    /** Also read a typographic-quoted key (`“__kind”`, `‘__kind’`) — text contexts only (round 8). */
+    smart?: boolean;
+    /** Also read an HTML-entity key (`"__kind"`, `"__kind"`) — text contexts only (round 8). */
+    entity?: boolean;
+    /**
+     * Also read a JavaScript object-literal key (`{ __kind: 'flashcard_set' }` —
+     * what Node's console prints, a sandbox tool's output) — key position with a
+     * quoted value, text contexts only (L-2, round 9).
+     */
+    js?: boolean;
+}
+/**
+ * EVERY spelling of the key a reader still sees as `__kind` (owner ruling,
+ * round 8): literal, `\u005f`-escaped, markdown-escaped `\_\_kind`,
+ * backslash-escaped quotes `\"__kind\"`, zero-width characters anywhere in
+ * the key, Python repr `'__kind'`, typographic quotes `“__kind”` and HTML
+ * entities `"__kind"`. THE options every TEXT context (prose,
+ * titles, exports, previews, the screen scan) passes; JSON contexts keep the
+ * default, where those spellings are string VALUES (and `valueCarriesKind`
+ * reads the strings with this set).
+ */
+declare const ALL_KIND_SPELLINGS: Readonly<KindTextOptions>;
+/**
+ * THE CONVERSION BOUNDARY (owner ruling, round 10): only REAL JSON is ever
+ * converted — the literal key, its `\u005f` escapes, the markdown-escaped
+ * `"\_\_kind"` (markdown draws it as the literal key) and zero-width characters
+ * inside the key. Every other spelling in free text (backslash-escaped
+ * `\"__kind\"` in prose, Python repr, a JavaScript literal, typographic quotes,
+ * entities) is DETECTION ONLY: the leak sentinel reports it, every renderer,
+ * converter, label and export leaves it exactly as written. Real output emits
+ * JSON; guessing at free text dropped and reordered people's words (rounds 8–9).
+ * A kind held as a JSON STRING inside JSON is read by parsing (`textCarriesKind`).
+ */
+declare const JSON_KIND_SPELLINGS: Readonly<KindTextOptions>;
+/** Whether text holds the key spelled as real JSON (`JSON_KIND_SPELLINGS`). */
+declare function hasJsonKindKey(source: string): boolean;
+/**
+ * Whether text holds the key ONLY in a detection-only spelling (round 10):
+ * a spelling the sentinel reports and no renderer converts.
+ */
+declare function hasDetectionOnlyKindKey(source: string): boolean;
+/** The text without zero-width characters (unchanged — same string — when it has none). */
+declare function withoutZeroWidth(text: string): string;
+/** Whether a fence language is JSON5 (the one context that widens the key rule). */
+declare function isJson5Language(lang: string | null | undefined): boolean;
+declare function hasKindKey(source: string, options?: KindTextOptions): boolean;
+/**
+ * EXOTIC spellings (owner ruling, round 9): double HTML entities
+ * (`&amp;quot;`), `&#95;` underscores, upper-case / padded entities, fullwidth
+ * quotes, bidi marks, invisible operators and combining joiners inside the key.
+ * DETECTION ONLY — the leak sentinel and the frame judge report them; no
+ * renderer converts them (an adversarial spelling is a defect to see, not a
+ * shape to guess at).
+ */
+declare function hasExoticKindKey(text: string): boolean;
+/** Whether TEXT holds the key in ANY spelling a reader sees as `__kind` (round 8). */
+declare function hasKindKeyAnySpelling(source: string): boolean;
+/** Whether a `__kind` value is a readable slug (ruling (c): anything else is broken output). */
+declare function isKindSlug(value: unknown): value is string;
+/**
+ * The first complete `__kind` slug in the text, or null. For a LOADER only —
+ * which kind's skeleton to show while the region arrives. Never an identity:
+ * the parser owns which kind a region actually is.
+ */
+declare function firstKindSlug(source: string, options?: KindTextOptions): string | null;
+declare function endsInPartialKindKey(text: string): boolean;
+/**
+ * The text after any LEADING JSONC comments and whitespace (`// note`,
+ * `/* … *\/`) — a ```jsonc / ```json / unlabelled fence that opens with a
+ * comment still decides on its first key (X3). An unterminated leading
+ * comment (still arriving) leaves nothing: undecided, never raw.
+ */
+declare function withoutLeadingJsonComments(text: string): string;
+declare function jsonKindSignal(text: string | null | undefined, options?: KindTextOptions): JsonKindSignal;
+/**
+ * A ```json5 body as plain JSON, when the difference is only what JSON5 adds
+ * that models actually write: comments, unquoted identifier keys, single-quoted
+ * keys/strings and trailing commas. Null when the result still will not parse.
+ */
+declare function json5AsJson(text: string): string | null;
+/**
+ * A Python repr of a dict/list (`{'__kind': 'flashcard_set', 'ok': True}`) as
+ * JSON text, or null when it is not one. Strings may be single- or
+ * double-quoted; `True` / `False` / `None` become JSON literals.
+ */
+declare function pythonReprAsJson(text: string): string | null;
+/** Whether text holds a Python-repr `'__kind'` key (key position, quoted value). */
+declare function hasPythonKindKey(text: string): boolean;
+/** Where the Python-repr value opening at `start` (`{` or `[`) closes (exclusive), or null. */
+declare function pythonBalancedEnd(text: string, start: number): number | null;
+/**
+ * THE ONE SPELLING NORMALIZER (K4 round 7, widened round 8, rebuilt round 9).
+ * Every text detector, converter and label function runs it (directly, or
+ * through `hasKindKeyAnySpelling`) so a kind spelled any REALISTIC way the
+ * screen still reads as a kind converts like any other. Each spelled region —
+ * from the `{` that owns the key to where its own grammar ends — is rewritten
+ * as canonical JSON:
+ *
+ *   zero-width in the key · HTML entities · typographic quotes ·
+ *   backslash-escaped quotes (any depth) · markdown-escaped `\_` · Python repr ·
+ *   JavaScript object literal — and any combination of them in one key
+ *
+ * DO NO HARM (owner ruling, round 9): only characters INSIDE a matched region
+ * change (a zero-width character only inside the key itself), a region never
+ * reaches past the point where its grammar breaks (an unclosed region in prose
+ * ends there and the text after it stays), and the scan is one linear pass.
+ * Quoted source (inline code, non-JSON fences) stays as written, and a WHOLE
+ * JSON text is never rewritten (a spelling inside it is a string VALUE).
+ * Text with no non-canonical spelling comes back as the same string.
+ */
+declare function normalizeKindSpellings(source: string): string;
+/** How a kind key is spelled — which decoders turn its region into JSON. */
+type KindSpellingFamily = "lifted" | "escaped" | "markdown" | "python" | "smart" | "entity" | "js";
+/**
+ * A kind region in a REALISTIC spelling (round 9). `[start, end)` is the raw
+ * region (`{` to where its grammar ended); `[rewriteStart, rewriteEnd)` is what
+ * the normalizer replaces (the key alone for a literal key holding only a
+ * zero-width character). `status`: `complete` (balanced), `prefix` (still
+ * arriving — runs to the end of the text) or `broken` (its grammar failed at
+ * `end`; the text after it is NOT part of it). `decoded` is the region's text
+ * with its spelling undone (still Python / JS for those families).
+ */
+interface KindSpellingRegion {
+    start: number;
+    end: number;
+    rewriteStart: number;
+    rewriteEnd: number;
+    family: KindSpellingFamily;
+    status: "complete" | "prefix" | "broken";
+    decoded: string;
+    /** Whether the key carried the markdown `\_` (the region was markdown-decoded). */
+    markdown: boolean;
+    /** A literal key's canonical text (the normalizer's whole rewrite for that family). */
+    keyText?: string;
+}
+/**
+ * A cheap pre-check every scanner runs first: no key spelling can exist
+ * without `kind` (or a zero-width character splitting it). Linear, no regex
+ * restarts — the plain text of every frame pays only this.
+ */
+declare function mayHoldKindKey(text: string): boolean;
+/**
+ * THE ONE LINEAR SCAN for kind regions in a realistic spelling (round 9):
+ * every candidate is found from a `kind` occurrence, its owning `{` from a
+ * forward-only brace cursor, quoted source once, and each region is decoded
+ * and bounded by its own grammar in work proportional to its length. Regions
+ * are returned in order and never overlap; a region's inner keys belong to it.
+ * A key whose `{` grammar fails BEFORE the key is not a region (prose braces).
+ */
+declare function scanKindSpellingRegions(text: string, options?: {
+    families?: "json" | "all";
+    from?: number;
+}): KindSpellingRegion[];
+/**
+ * Past this many characters an open bare-JSON region is not re-read for a
+ * prose break (a hot-path budget: the check is linear in the region, run per
+ * line / fragment). A fragment that breaks into prose does so within its first
+ * lines; a long region is real JSON streaming.
+ */
+declare const BARE_REGION_GRAMMAR_BUDGET = 16384;
+/**
+ * Whether an open bare-JSON region's text has BROKEN INTO PROSE by its own JSON
+ * grammar (round 10, C1): `{"status": "ok", "items": [` then a line of words,
+ * `{\"__kind\":…} and the rest`, `{ some code`. Such a region was never JSON:
+ * it reads as text. THE one answer the live accumulator (per line, budgeted)
+ * and the reload splitter (whole region, `firstBudget` — the same first 16 KB
+ * the live check reads) share, so live ≡ reload (round 11, H1). A region still
+ * validly open (or complete) is not broken.
+ */
+declare function bareRegionBreaksIntoProse(text: string, options?: {
+    firstBudget?: boolean;
+}): boolean;
+/**
+ * Where a LITERAL kind object (`text` opens at its `{`) breaks into prose —
+ * `{"__kind":"note","title":"Hi" and then…` — after its key: the end of the
+ * region, or null (complete, still arriving, or merely malformed). THE one
+ * answer the converters, the prose leaf and the live accumulator share, so a
+ * settled unclosed object reads the same live and reloaded (L-4, round 9).
+ */
+declare function kindObjectProseBreak(text: string): number | null;
+/** Which JSON-like grammar bounds a region: strict JSON, Python repr, or a JavaScript literal. */
+type GrammarDialect = "json" | "python" | "js";
+type KindGrammarVerdict = {
+    status: "complete";
+    end: number;
+} | {
+    status: "prefix";
+} | {
+    status: "broken";
+    at: number;
+    cut: number;
+    prose: boolean;
+};
+/**
+ * Where a JSON-like value opening at 0 ends by its OWN grammar (H-1, round 9):
+ * `complete` at its balanced close, `prefix` when the text ends while it is
+ * still valid (arriving), or `broken` at the first character that cannot
+ * continue it — `cut` is the end of the last whole token before that (after a
+ * value, a `,`, or an opener), so the text after `cut` is never part of it.
+ * A raw newline inside a string breaks it (JSON strings never hold one), so an
+ * unclosed string never runs past its line. One pass, no allocation per char.
+ */
+declare function kindGrammar(s: string, dialect?: GrammarDialect, from?: number): KindGrammarVerdict;
+/** A complete region as JSON text (Python / JS converted), or null when it will not read. */
+declare function regionJson(region: Pick<KindSpellingRegion, "family" | "decoded">): string | null;
+/**
+ * A BROKEN (settled, unclosed) region closed where its grammar ended: a
+ * dangling `,` or `key:` dropped, every open container closed — the reading
+ * the label is drawn from. Null when even that will not read.
+ */
+declare function closedJson(region: Pick<KindSpellingRegion, "family" | "decoded">): string | null;
+/**
+ * The VALUE form of the same question, for renderers handed parsed data
+ * instead of text (the value grid, the JSON viewers): does this value carry a
+ * kind anywhere — an object with a string `__kind`, at any depth, or a string
+ * that holds a kind REGION (`textCarriesKind`: whole kind JSON, or prose with
+ * a kind in it — a ```json fence, inline JSON — outside quoted source)? A raw
+ * renderer that answers yes renders the value through the one value door
+ * (`AnswerValueView`) instead.
+ */
+declare function valueCarriesKind(value: unknown): boolean;
+/**
+ * A STRING value that holds a kind region (H1, round 5): text that is kind
+ * JSON, or prose with a kind region in it by THE markdown definition
+ * (`markdownCarriesKind` — outside quoted source, markdown-escaped key too).
+ * `{answer: "Here are your cards: ```json {…kind…}```"}` carries its kind.
+ */
+declare function textCarriesKind(text: string): boolean;
+/**
+ * Text that IS a JSON object/array carrying a `__kind` key (not prose
+ * mentioning one) — the gate before a `JSON.parse` of the whole text. For
+ * "does this string hold a kind anywhere", read `textCarriesKind`.
+ */
+declare function isKindJsonText(text: string): boolean;
+/** The kind slug a value claims for itself at its root, or null. */
+declare function rootKindSlug(value: unknown): string | null;
+/** Whether a fence's language makes its body a JSON region (any case; none counts). */
+declare function isJsonFenceLanguage(lang: string | null | undefined): boolean;
+/**
+ * Where a kind in markdown is the model QUOTING SOURCE, never data (the
+ * owner's ruling, 2026-09-30): inside an inline code span, or inside a fence
+ * whose language is not JSON (```ts, ```xml, ```markdown …). Everything else
+ * — prose, a blockquote, a list item, a table cell, a 4-space indented block,
+ * a JSON fence — is data. [start, end) spans, in order. THE one definition:
+ * the splitter, the live accumulator and the leaf gate all read it, so a leaf
+ * and the pipeline can never disagree about what is a kind region.
+ */
+declare function quotedSourceRanges(text: string): Array<[number, number]>;
+/**
+ * Whether an XML card SHOWS SOURCE (the owner's rulings, round 3): a ```xml
+ * FENCE is the model quoting source — a kind inside it stays as written (a).
+ * An XML TAG the model wraps content in (`<answer>`, `<output>`, any generic
+ * tag, closed or not) is STRUCTURE (b): the splitter and the accumulator mark
+ * every piece of it `genericXmlContainer`, and a kind inside its prose renders
+ * as the kind. THE one answer — XmlBlock's callers and the frame judge read it.
+ */
+declare function isQuotedSourceXmlBlock(block: {
+    metadata?: Record<string, unknown> | null;
+}): boolean;
+/**
+ * Where the front matter that opens `source` ends (0 when none): an optional
+ * byte-order mark, a first line that is exactly `---` or `+++`, through the
+ * same fence (YAML also `...`). Front matter is document properties, never
+ * content — a `{"__kind":…}` VALUE inside it is never a kind block, in the
+ * static splitter or the live accumulator (RC-B3r round 3, C1).
+ */
+declare function frontMatterEnd(source: string): number;
+/**
+ * The MARKDOWN form: does this prose hold a kind REGION — a `__kind` key
+ * anywhere outside quoted source (see `quotedSourceRanges`)? A leaf that
+ * answers yes hands the text to the pipeline (`MarkdownStream`), which lifts
+ * the region by the same definition — prose, table cell, indented block,
+ * blockquote, JSON fence, or the whole text being kind JSON.
+ */
+declare function markdownCarriesKind(source: string): boolean;
+
+/**
+ * Recover complete self-described kind objects from ANY containing text.
+ *
+ * Markdown, code fences, and XML are arrival containers, not type authority.
+ * Once a complete JSON object directly declares a non-empty `__kind`, that
+ * object is its own Content IR region even when an outer parser already
+ * classified the surrounding bytes as code, XML, or prose.
+ *
+ * Generic XML opts into literal-context exclusion so tag attributes, code,
+ * comments, and CDATA remain examples owned by their container. Otherwise the
+ * scanner is syntax-agnostic about the outer container. It only promotes candidates that independently pass JSON.parse and carry a
+ * direct string discriminator. Failed/malformed candidates remain untouched.
+ */
+interface EmbeddedKindJsonRegion {
+    start: number;
+    end: number;
+    content: string;
+    kind: string;
+}
+type EmbeddedKindJsonPiece = {
+    type: "container";
+    content: string;
+} | {
+    type: "kind";
+    content: string;
+    kind: string;
+}
+/**
+ * JSON punctuation that only held kinds together — the `[`, `,` and `]` of
+ * an array of kinds. Kept so the partition stays lossless; never rendered
+ * (a lone `[` drawn as a JSON card is noise, not content — A6).
+ */
+ | {
+    type: "chrome";
+    content: string;
+}
+/**
+ * The non-kind DATA of a JSON wrapper around kinds (`{"result":{…kind…},
+ * "note":"x"}`, A7): `content` is the source span it replaces (lossless),
+ * `json` is the wrapper's value with every kind removed — valid JSON, drawn
+ * as genuine JSON. A wrapper that holds only kinds has no residual piece.
+ */
+ | {
+    type: "residual";
+    content: string;
+    json: string;
+};
+/**
+ * For every `{` / `[` in `text`: the end (exclusive) of the string-aware
+ * balanced JSON value opening there, or -1 (never balances). Each opener's
+ * reading starts outside a string, exactly as if read alone; one right-to-left
+ * pass reuses each nested opener's own answer (its reading from inside an
+ * enclosing value is the same reading), so the whole table is linear — a
+ * reading per opener was quadratic on thousands of unclosed `{` (round 11, P5).
+ */
+declare function balancedEnds(text: string): Int32Array;
+
+interface EmbeddedKindSearchOptions {
+    /** Generic XML: code, comments, CDATA and tags are literal (the XML card shows them). */
+    excludeLiteralContexts?: boolean;
+    /**
+     * With `excludeLiteralContexts` (an XML TAG — structure, ruling (b) round 3):
+     * a ```json / ```jsonc / ```json5 / unlabelled fence is NOT literal. A kind
+     * that is its whole body leaves with the fence's own lines as chrome, so
+     * the XML pieces around it hold no orphan fence marker.
+     */
+    liftJsonFences?: boolean;
+    /**
+     * Markdown: inline code spans and non-JSON fences are the model quoting
+     * source (`quotedSourceRanges`, the owner's ruling 2026-09-30) — never lifted.
+     */
+    excludeQuotedSource?: boolean;
+}
+declare function findEmbeddedKindJsonRegions(source: string, options?: EmbeddedKindSearchOptions): EmbeddedKindJsonRegion[];
+/** Losslessly partition a container around every recovered kind region. */
+declare function splitAroundEmbeddedKindJson(source: string, options?: EmbeddedKindSearchOptions): EmbeddedKindJsonPiece[];
+/**
+ * A recovered PROSE piece, shaped exactly as the live stream shapes the same
+ * bytes (A5, 2026-09-30): the stream splits `Here: {"__kind":…} after` into
+ * three lines as it arrives, so its prose blocks are trimmed at the end (every
+ * text block is) and, after a kind, start where the next character does — the
+ * spaces after the object and the one line break that ended its line are the
+ * boundary, not content. Both hosts call this on every text piece, so a live
+ * message and its reload draw the same blocks.
+ */
+declare function normalizeRecoveredProsePiece(content: string, followsKind: boolean): string;
+/**
+ * Every recovered container piece, by its container's block type: prose by
+ * the rule above, code byte-verbatim, and a SECTION (`thinking`, `info`, …)
+ * trimmed — the live stream splits a kind out of a section as it arrives
+ * (A8) and each part is a section body, which is trimmed like a whole one.
+ */
+declare function normalizeRecoveredContainerPiece(content: string, containerType: string, followsKind: boolean): string;
+/**
+ * A complete JSON value (object or array) that holds at least one kind, as
+ * one region: a recovered kind region widened to the OUTERMOST complete,
+ * parseable JSON value that contains it — a kindless wrapper
+ * (`{"result":{…kind…},"note":…}`, A7) or an array of kinds and plain values.
+ * For DESTINATION transforms (export, copy, speech) that convert the value
+ * whole; the renderer partitions the same bytes with
+ * {@link splitAroundEmbeddedKindJson}. Built on THE region finder above.
+ */
+interface KindCarryingJsonRegion {
+    start: number;
+    end: number;
+    content: string;
+    value: unknown;
+}
+declare function findKindCarryingJsonValues(source: string, options?: {
+    excludeLiteralContexts?: boolean;
+}): KindCarryingJsonRegion[];
+/**
+ * A kind that can never complete as written: [start, end) and the text of
+ * its region. Two shapes, by the same ownership rule as the finder above:
+ *  - a CLOSED object whose root declares `__kind` but does not parse (the
+ *    finder's malformed owner) — bounded;
+ *  - an UNCLOSED JSON object or array at the tail (a stream cut off, a
+ *    truncated store) holding a `"__kind"` key anywhere — runs to the end,
+ *    from its outermost opener (a kindless wrapper is cut with its kind).
+ * For destinations that must say "<Kind> did not finish" instead of printing
+ * the fragment. Complete values (kind or not) are skipped whole.
+ */
+interface BrokenKindJsonRegion {
+    start: number;
+    end: number;
+    content: string;
+}
+/**
+ * Round 10 (C1): a broken region is bounded by its OWN JSON grammar. An opener
+ * owns a kind key only when its grammar reaches the key; it runs to the end of
+ * the text only while it is still validly open, else it ends at its cut. A
+ * stray `[[`, `{"`, `{{`, `["`, an unrelated earlier object or a pasted
+ * schema never extends a region over the prose after it. A balanced span that
+ * does not parse is a region only when it reads once trailing commas go.
+ * Linear: key positions once, each opener's grammar stops at its break.
+ */
+declare function findBrokenKindJsonRegions(source: string, options?: {
+    excludeLiteralContexts?: boolean;
+}): BrokenKindJsonRegion[];
+
+/**
+ * Answer TEXT → the readable markdown a person meant, for DISPLAY and EXPORT
+ * destinations only (a note, a task, a file, a print, a clipboard copy, the
+ * speaker, a plain-text slot). Rule (Arman, 2026-09-30): a kind is never shown
+ * as raw JSON — every `{"__kind":…}` region in the text (bare, or the whole
+ * body of a ```json / unlabelled fence) becomes that kind's markdown through
+ * the ONE kind → markdown converter (`kindValueToMarkdown`: the registry's
+ * `toMarkdown` facet, else `genericKindMarkdown`).
+ *
+ * 🚨 Never call this on data that is STORED or PASSED to a machine: `__kind`
+ * is part of the data. This is a destination transform, the same as
+ * `unwrapKindEnvelopes`. Kindless text returns byte for byte.
+ *
+ * Regions come from the one embedded-kind region finder
+ * (`findEmbeddedKindJsonRegions`); the signal is the one detector
+ * (`hasKindKey`). Nobody writes a second one.
+ */
+/**
+ * The one-line broken state of a kind that never completed (≤60 chars) — the
+ * SAME words the compact preview shows (`AnswerTextPreview`), so an export of
+ * a cut-off answer says what the screen said.
+ */
+declare function unfinishedKindLabel(kind: string | null): string;
+/** The one-line note for structured output whose `__kind` cannot name a kind. */
+declare const UNREADABLE_KIND_NOTE = "Structured output could not be read";
+/**
+ * The export transform. Kindless text returns byte for byte; every kind
+ * region becomes readable markdown, and a kind that can never complete (cut
+ * off, malformed) becomes its one-line "<Kind> did not finish" note — never
+ * the fragment.
+ */
+declare function kindTextToMarkdown(raw: string | null | undefined): string;
+interface KindTextPreview {
+    /** The readable text: complete kinds as markdown, an arriving kind cut off. */
+    text: string;
+    /** The slug of a kind still arriving at the end of the text (its loader), else null. */
+    pendingKind: string | null;
+    /** True when a kind is arriving but its slug has not been read yet. */
+    pendingUnnamed: boolean;
+}
+/**
+ * A COMPACT, possibly still-streaming preview of answer text (a toast, a
+ * hover card, a list row): complete kinds read as their markdown; a kind
+ * still arriving is cut from the text and named in `pendingKind` so the
+ * caller shows that kind's loader — the raw JSON never shows mid-stream.
+ */
+declare function kindTextPreview(raw: string | null | undefined): KindTextPreview;
+
+/**
+ * THE ONE-LINE FORM of a kind — what an INLINE surface shows where a kind
+ * region sits in its text (P6, round 4): a collapsed card preview, a
+ * notification body, an extraction cell, a table cell. An inline/preview level
+ * cannot mount a kind component, so a kind reads as its instance title and
+ * kind name (`**Cells** · Flashcard Set`), an unfinished one as its kind name
+ * alone, and an unreadable one as "Structured output". Never the JSON.
+ *
+ * LIGHT on purpose — the inline level must not pull the kind registry or the
+ * block pipeline: the region finder (`embedded-kind-json.ts`), the detector
+ * and the title derivation (`studio/instance-title.ts`) only.
+ */
+/**
+ * One line for a kind VALUE: `**Title** · Kind Name`, or the kind name alone.
+ * `plain` drops the markdown emphasis (`Title · Kind Name`) for slots that
+ * draw text as written — a tooltip, a `title` attribute, a clamped caption.
+ */
+declare function kindOneLine(value: unknown, options?: {
+    plain?: boolean;
+}): string;
+/**
+ * The text with every kind region (complete, unfinished or unreadable) in
+ * prose replaced by its one-line form. Quoted source (inline code, non-JSON
+ * fences) stays as written. Text with no kind key comes back unchanged.
+ */
+declare function inlineKindText(raw: string, options?: {
+    plain?: boolean;
+}): string;
+/**
+ * A complete JSON kind region whose `__kind` cannot name a kind (`{"__kind":
+ * ["x"], …}`, `{"__kind": 5}`) → the one-line unreadable note, the words the
+ * export writes (`UNREADABLE_KIND_NOTE`), instead of raw JSON (round 11, L2).
+ */
+declare function unreadableKindsAsNote(text: string): string;
+/**
+ * CATALOG PROSE as a person reads it (ruling (a), round 6): a skill / agent /
+ * tool description that shows an example kind JSON (`emit a
+ * {"__kind": "math_problem"} block`) is documentation — the example reads as
+ * its kind's one-line label, never the JSON. Plain text out, for text AND
+ * attribute slots (`title`, tooltips). Display transform only: the stored
+ * description is never rewritten.
+ */
+declare function catalogProseText(text: string | null | undefined): string;
+/**
+ * THE PROSE LEAF's kind reading (round 10 boundary): a REAL JSON kind region
+ * the pipeline cannot lift — a settled object whose grammar BROKE in prose
+ * (`{"__kind":"note","title":"Hi" and then…`), or a markdown-escaped key
+ * (`"\_\_kind"`) — reads as its one-line label, then every character after
+ * its cut as written. A complete literal kind is the pipeline's (lifted).
+ * Every NON-JSON spelling (`{\"__kind\":…}` in prose, repr, a JS literal,
+ * typographic quotes, entities) is left EXACTLY as written — detection only.
+ * Called by the one prose leaf live and reloaded text both pass through, so
+ * live ≡ reload. One linear pass, memoized per text; text with no such region
+ * comes back as the same string.
+ */
+declare function spelledKindsAsOneLine(text: string): string;
+/**
+ * Round 10, detection-only spellings drawn EXACTLY as written: a non-JSON
+ * kind spelling in prose (`{\"__kind\":…}`, repr, a JS literal, typographic
+ * quotes, entities) becomes an inline code span, so markdown neither eats its
+ * backslashes nor decodes its entities — the screen shows the source byte for
+ * byte, as quoted source. Nothing outside a region changes; text with no such
+ * region comes back as the same string. One linear pass, memoized per text.
+ * (A markdown-escaping pass did the same job and hung the renderer on nested
+ * escapes — never reintroduce it.)
+ */
+declare function nonJsonKindsAsCode(text: string): string;
+
+/**
+ * A JSON REGION INSIDE A BLOCKQUOTE leaves the quote (V1, the never-raw law).
+ *
+ * A model sometimes quotes its whole answer — `> ```json` / `> {"__kind":…}` —
+ * and every line then starts with `>`. Neither host could see the region: the
+ * live accumulator classifies a `>` line as prose, the static splitter keeps
+ * the quote as one text block, so the kind was drawn as raw JSON inside a
+ * blockquote in chat, on reload, on public shared pages and in tool results.
+ *
+ * THE RULE: a blockquote holds prose, never a data region. A JSON-family
+ * fence (```json / ```jsonc / ```json5 / unlabelled, any case, ``` or ~~~)
+ * opening on a quoted line, or a quoted line whose JSON could be a kind (the
+ * first-key rule, `jsonKindSignal`), is LIFTED: its quote prefix is removed
+ * from every line of the region, so the region becomes an ordinary top-level
+ * fence / bare JSON object between two quotes. The quote before it renders as
+ * a quote, the region as its kind, the quote after it as a new quote. Quoted
+ * text that is not a JSON region is never touched — and a fence of another
+ * language (```ts, ```xml, ```markdown, quoted or not) is the model quoting
+ * SOURCE, so nothing inside it is lifted (the owner's ruling, 2026-09-30).
+ *
+ * ONE transform, both hosts: the live accumulator pushes every delta through
+ * a `QuotedKindLift` before its line machine; the static splitter runs
+ * `liftQuotedKindRegions` on the whole text first. The transform is
+ * chunk-invariant (decisions are taken only at points every chunking reaches
+ * with the same bytes), so live = reload byte for byte.
+ */
+/**
+ * The streaming lift. `push` returns the bytes that are safe to hand on now;
+ * a line whose fate is not known yet (a quoted line that may open a JSON
+ * region) is held — never shown raw — until it is. `flush` releases what is
+ * held, as written, at the end of the stream (or a hard boundary).
+ */
+declare class QuotedKindLift {
+    private mode;
+    /** The current line's bytes not yet handed on (held while undecided). */
+    private held;
+    /** The current line's bytes so far (handed on or not), as received. */
+    private line;
+    /** Whether the rest of the current line passes straight through. */
+    private passing;
+    /** Prefix stripped from the current line's handed-on bytes (passing lines). */
+    private stripping;
+    push(text: string): string;
+    flush(): string;
+    private pushChar;
+    /** Try to decide the current line before it ends; returns bytes released. */
+    private decideMidLine;
+    /** Hand on `bytes` and let the rest of the line pass straight through. */
+    private release;
+    private endLine;
+    /**
+     * A complete line met with no region open. `held` is what was not handed
+     * on yet: the whole line when it was held to the end, otherwise "" (it was
+     * released mid-line as prose or as an unquoted line).
+     */
+    private lineFromNone;
+    /** A held quoted JSON start, re-judged after each complete line. */
+    private settleCandidate;
+}
+/** The whole-text form, for the static splitter (identical bytes to any streaming of `source`). */
+declare function liftQuotedKindRegions(source: string): string;
+
+/**
+ * THE MARKDOWN-ESCAPED KIND (P8, round 4). A model that escapes markdown in
+ * its whole answer writes `{"\_\_kind":"flashcard\_set",…}`. No JSON reader
+ * sees a kind there (`\_` is not even a JSON escape), but the markdown
+ * renderer un-escapes it, so the reader saw `{"__kind":…}` drawn raw.
+ *
+ * THE RULE: the key `"\_\_kind"` IS the key `"__kind"` (the detector reads it
+ * in text contexts, `hasKindKey(…, { markdown: true })`), and inside the JSON
+ * object that holds it every `\_` is `_`. ONE transform, both hosts: the live
+ * accumulator pushes every delta through a `MarkdownEscapedKindJson` before
+ * its line machine; the static splitter runs `unescapeMarkdownKindJson` on the
+ * whole text first. Character-driven and chunk-invariant, so live = reload.
+ *
+ * Also here (decided, round 4): a DOUBLE-ENCODED kind — the whole answer is a
+ * JSON string literal whose value is kind JSON (`"{\"__kind\":…}"`) — reads as
+ * that kind (`decodeDoubleEncodedKindText`, whole text, settled readers only).
+ */
+/**
+ * A ZERO-WIDTH character inside the key (`"__\u200Bkind"`, round 8): the
+ * screen reads `"__kind"`, so the key is rewritten as `"__kind"` before
+ * anything else reads the text, and the normal kind route (fence, standalone,
+ * prose) takes it. Only a complete key is rewritten — a zero-width character
+ * anywhere else stays. Character-driven and chunk-invariant (live = reload).
+ */
+declare class ZeroWidthKindKey {
+    /** Bytes that may still become the key — held, never shown. */
+    private pending;
+    push(text: string): string;
+    flush(): string;
+    private pushChar;
+}
+declare class MarkdownEscapedKindJson {
+    /** The zero-width key spelling is read first (round 8) — one transform, both hosts. */
+    private zeroWidth;
+    /** Bytes that may still become the escaped key — held, never shown. */
+    private pending;
+    /** Inside the object holding a rewritten key: bracket depth (0 = outside). */
+    private depth;
+    private inString;
+    /** A held backslash inside the object (its fate depends on the next char). */
+    private escape;
+    push(text: string): string;
+    private pushUnescape;
+    flush(): string;
+    private pushChar;
+    private insideObject;
+}
+/** The whole-text form, for the static splitter (identical bytes to any streaming of `source`). */
+declare function unescapeMarkdownKindJson(source: string): string;
+/**
+ * A whole answer that is a JSON STRING literal holding kind JSON → that kind
+ * JSON; anything else unchanged.
+ */
+declare function decodeDoubleEncodedKindText(source: string): string;
+
+/**
+ * A KIND AS AN IMAGE'S ALT TEXT (P9, round 4): `![{"__kind":…}](url)`. The
+ * prose split lifted the object out and left `!` and `(url)` behind as two
+ * stray prose blocks after reload (and live). The model meant the kind: the
+ * image wrapper is chrome — `![` before the object and `](url)` after it are
+ * dropped, the object stays where it was and renders as its kind. A kindless
+ * object in alt text (first key decided not `__kind`) is left as written.
+ *
+ * ONE transform, both hosts (like `quoted-kind-lift.ts`): the live accumulator
+ * pushes every delta through a `KindImageAltUnwrap`; the static splitter runs
+ * `unwrapKindImageAlt` on the whole text. Character-driven and chunk-invariant.
+ */
+declare class KindImageAltUnwrap {
+    private mode;
+    /** Held: `!` / `![` (scan), the object so far (head), `](…` (tail). */
+    private held;
+    private depth;
+    private inString;
+    private escape;
+    push(text: string): string;
+    flush(): string;
+    /** Track JSON structure; returns true when the object just closed. */
+    private track;
+    private pushChar;
+}
+/** The whole-text form, for the static splitter (identical bytes to any streaming of `source`). */
+declare function unwrapKindImageAlt(source: string): string;
+
+/**
+ * Answer TEXT → ONE readable line, for a person's compact label (a card
+ * subtitle, a rule name, a link-preview description, a list row). A kind is
+ * never shown as raw JSON (Arman, 2026-09-30): a kind answer reads as
+ * "<Kind> · <instance title>" (`deriveInstanceTitle`, the derivation saved
+ * instances use); prose with a kind in it reads as the prose's first line;
+ * a kind that never completed reads as its one-line broken note.
+ * Kindless text is whitespace-collapsed and clipped, nothing else.
+ *
+ * Destination transform only — never call it on stored or machine-bound text.
+ */
+/** One line, at most `max` characters, never containing a `__kind` key. */
+declare function kindTextLabel(raw: string | null | undefined, max?: number): string;
+/**
+ * A conversation TITLE as a person reads it (R4, round 6): a title that holds
+ * kind JSON reads as its one-line kind label; any other title — and null —
+ * comes back as it is. Read boundaries and title renderers call this; the
+ * stored title is never rewritten.
+ */
+declare function conversationTitleText(title: string | null | undefined): string | null;
+
+/**
+ * Shared plumbing for kind → markdown export facets (`toMarkdown`).
+ *
+ * The FORWARD leg of the artifact ⇄ markdown two-way layer: every facet
+ * turns a kind's ZERO-LOSS value object into clean human-readable markdown
+ * (headings / lists / bold — never a JSON dump), following two laws:
+ *
+ * 1. `__kind` discriminators are transport metadata — never rendered.
+ * 2. Nothing silently vanishes: keys a facet doesn't understand (plus the
+ *    declared `additionalDetails` bag every top-level kind schema carries)
+ *    are appended under a small "Additional details" key: value section via
+ *    `collectExtras` + `additionalDetailsSection`.
+ *
+ * `genericKindMarkdown` is the fallback for kinds WITHOUT a `toMarkdown`
+ * facet (and for unregistered kinds): readable markdown built from the value
+ * itself — headings, bold-label lists, tables — never a JSON dump.
+ */
+declare function isRecordValue(value: unknown): value is Record<string, unknown>;
+/**
+ * One-line rendering of an arbitrary value for key: value lists. Scalars
+ * render as text, scalar arrays join with ", ", anything structural falls
+ * back to inline JSON in a code span (zero loss, still one line).
+ */
+declare function formatInlineValue(value: unknown): string;
+/**
+ * Collect the keys a facet does NOT understand. Skips `__kind`,
+ * null/undefined, and the facet's known keys; merges the contents of a
+ * declared `additionalDetails` object bag (the schema-blessed extras
+ * channel) into the same flat map so both extra channels surface together.
+ */
+declare function collectExtras(value: Record<string, unknown>, knownKeys: Iterable<string>): Record<string, unknown>;
+/**
+ * A field's own name, as words — `violations_not_fixed` → "Violations not
+ * fixed", `wordCountAfter` → "Word count after".
+ *
+ * 🚨 WALK 18, DEFECT D. The finished Masterwork deliverable an Expert hands a
+ * customer carried `violations_not_fixed: []` — a key out of a schema we
+ * declared, printed at a person. A label is the one place a field name is
+ * GUARANTEED to reach a reader, so the resolution lives here, beside the
+ * extras plumbing, for every RENDERER that puts a structured field on a
+ * screen: underscores and camel humps become spaces, the first letter is
+ * capitalised, and nothing else changes.
+ *
+ * Deliberately NOT applied inside {@link extrasList}. That list is the
+ * markdown/EXPORT leg (`features/canvas/export/exportArtifactMarkdown.ts`
+ * writes a file somebody — or something — reads back), and a key spelled as
+ * prose cannot be read back as a key. A screen resolves; a file keeps the key.
+ */
+declare function plainFieldLabel(key: string): string;
+/** Render extras as a key: value bullet list (no heading). Null when empty. */
+declare function extrasList(extras: Record<string, unknown>): string | null;
+/**
+ * The canonical "Additional details" section — appended at the END of a
+ * kind's markdown so nothing silently vanishes. Null when there is nothing
+ * to say (callers filter with `joinBlocks`).
+ */
+declare function additionalDetailsSection(extras: Record<string, unknown>, headingLevel?: "##" | "###" | "####"): string | null;
+/** Join markdown blocks with blank lines, dropping empty/null ones. */
+declare function joinBlocks(blocks: Array<string | null | undefined>): string;
+/** "flashcard_set" → "Flashcard Set"; "Artifact" when there is nothing to say. */
+declare function humanizeKind(kind: string): string;
+/** Renders a nested kind value as markdown (the registry's converter). */
+type NestedKindMarkdown = (value: Record<string, unknown>) => string;
+/**
+ * Fallback markdown for kinds with no `toMarkdown` facet (or unregistered
+ * kinds): READABLE markdown built from the value itself (kind-never-raw,
+ * Arman 2026-09-30 — a kind is never shown as raw JSON, an export included).
+ * Heading = the instance title (`deriveInstanceTitle`), then the kind's
+ * name; scalar fields as a bold-label list; arrays of uniform scalar records
+ * as a table, other arrays as nested lists; nested plain objects as
+ * sections; nested KINDS through `nested` (the registry converter —
+ * `kindValueToMarkdown` passes itself; default: this function). Never the
+ * `__kind` key, never a JSON fence. Every field still appears (zero loss in
+ * content; the discriminator is named in words by the subtitle).
+ */
+declare function genericKindMarkdown(kind: string, value: Record<string, unknown>, nested?: NestedKindMarkdown): string;
+/**
+ * Readable markdown for a value that is NOT itself a kind — a kindless JSON
+ * wrapper around kinds, or a run of plain values beside kinds in an array —
+ * so a destination (export, copy) never prints it as JSON. Same rendering as
+ * a kind's body in {@link genericKindMarkdown} (bold-label scalars, tables for
+ * uniform records, nested lists, sections), nested kinds through `nested`.
+ */
+declare function plainValueMarkdown(value: unknown, nested?: NestedKindMarkdown): string;
+
+type KindValueToMarkdown = (value: Record<string, unknown>, fallbackKind?: string) => string;
+/** The host's registry-backed converter (matrx-frontend: `features/canvas/export/exportArtifactMarkdown`). */
+declare function registerKindValueMarkdown(impl: KindValueToMarkdown | null): void;
+declare function kindValueToMarkdown(value: Record<string, unknown>, fallbackKind?: string): string;
+
+/**
+ * Instance TITLE derivation — pure, importable from server and client code
+ * (no supabase import; `instance-service.ts` consumes it on the write path).
+ *
+ * CROSS-REPO MIRROR: aidream `kind_instance.py` (`_TITLE_KEYS` +
+ * `derive_title` + `kind_shared.kind_title_key`) implements the SAME
+ * derivation order — explicit title → the kind's `metadata.title_key` field
+ * (per-kind override, non-empty scalar) → the shared key list → null.
+ * Change BOTH sides together.
+ */
+/** Mirrors aidream `kind_instance._TITLE_KEYS` — keep the two in lockstep. */
+declare const INSTANCE_TITLE_KEYS: readonly ["title", "name", "label", "heading", "subject", "customer"];
+/**
+ * The kind's per-kind instance-title override —
+ * `kind_definition.metadata.title_key` (a single data key naming the title
+ * field, e.g. `wine_name`). Set by the creator agent via `kind_create`;
+ * null when absent/blank/non-string. Server parity: `kind_shared.kind_title_key`.
+ */
+declare function kindTitleKeyFromMetadata(metadata: unknown): string | null;
+/**
+ * Explicit title wins; else the kind's `metadata.title_key` field when it
+ * holds a non-empty scalar; else the first non-empty string under a shared
+ * title/name-ish key. The ORDER is a cross-repo contract — mirrored verbatim
+ * by aidream `kind_instance.derive_title`.
+ */
+declare function deriveInstanceTitle(data: Record<string, unknown>, explicit?: string | null, titleKey?: string | null): string | null;
+
+/** Mirror the server's legacy quiz adapter while keeping source aliases in IR residue. */
+declare function canonicalizeCompletedLegacyQuizEnvelope(envelope: CanonicalBlockIR, sourceText: string): CanonicalBlockIR;
+
+/**
+ * Pure envelope helpers the chat package needs (chat-package-move P14): the Phase-2 shadow
+ * parity check ("does the envelope, reconstructed, deep-equal what JSON.parse sees?").
+ *
+ * A COMPARISON, NEVER A TRANSFORM — the one lawful shape of `stripKindDeep` outside the two doors.
+ * Markers are removed from BOTH sides, symmetrically, inside this predicate, so a marker the parser
+ * INJECTED (speculation / expectedRootKind) is not reported as a mismatch against a source that did
+ * not carry one. Only a boolean leaves; neither input is mutated and neither reduced value is ever
+ * returned, stored, or rendered (KINDS_EVERYWHERE_PLAN §4.2).
+ */
+
+declare function envelopeMatchesParsedSource(envelope: CanonicalBlockIR, parsedSource: unknown): boolean;
+
+/** The decision-answers block's stable wire ids (render-block type and kind slug). */
+declare const DECISION_ANSWERS_KIND = "decision_answers";
+declare const DECISION_ANSWERS_BLOCK_TYPE = "decision_answers";
+
+export { ALL_KIND_SPELLINGS, BARE_REGION_GRAMMAR_BUDGET, type BrokenKindJsonRegion, DECISION_ANSWERS_BLOCK_TYPE, DECISION_ANSWERS_KIND, type EmbeddedKindJsonPiece, type EmbeddedKindJsonRegion, type EmbeddedKindSearchOptions, type GrammarDialect, INSTANCE_TITLE_KEYS, JSON_KIND_SPELLINGS, type JsonKindSignal, type KindCarryingJsonRegion, type KindGrammarVerdict, KindImageAltUnwrap, type KindSpellingFamily, type KindSpellingRegion, type KindTextOptions, type KindTextPreview, type KindValueToMarkdown, MarkdownEscapedKindJson, type NestedKindMarkdown, QuotedKindLift, UNREADABLE_KIND_NOTE, ZeroWidthKindKey, additionalDetailsSection, balancedEnds, bareRegionBreaksIntoProse, canonicalizeCompletedLegacyQuizEnvelope, catalogProseText, closedJson, collectExtras, conversationTitleText, decodeDoubleEncodedKindText, deriveInstanceTitle, endsInPartialKindKey, envelopeMatchesParsedSource, extrasList, findBrokenKindJsonRegions, findEmbeddedKindJsonRegions, findKindCarryingJsonValues, firstKindSlug, formatInlineValue, frontMatterEnd, genericKindMarkdown, hasDetectionOnlyKindKey, hasExoticKindKey, hasJsonKindKey, hasKindKey, hasKindKeyAnySpelling, hasPythonKindKey, humanizeKind, inlineKindText, isJson5Language, isJsonFenceLanguage, isKindJsonText, isKindSlug, isQuotedSourceXmlBlock, isRecordValue, joinBlocks, json5AsJson, jsonKindSignal, kindGrammar, kindObjectProseBreak, kindOneLine, kindTextLabel, kindTextPreview, kindTextToMarkdown, kindTitleKeyFromMetadata, kindValueToMarkdown, liftQuotedKindRegions, markdownCarriesKind, mayHoldKindKey, nonJsonKindsAsCode, normalizeKindSpellings, normalizeRecoveredContainerPiece, normalizeRecoveredProsePiece, plainFieldLabel, plainValueMarkdown, pythonBalancedEnd, pythonReprAsJson, quotedSourceRanges, regionJson, registerKindValueMarkdown, rootKindSlug, scanKindSpellingRegions, spelledKindsAsOneLine, splitAroundEmbeddedKindJson, textCarriesKind, unescapeMarkdownKindJson, unfinishedKindLabel, unreadableKindsAsNote, unwrapKindImageAlt, valueCarriesKind, withoutLeadingJsonComments, withoutZeroWidth };