import { CanonicalBlockIR } from './core.cjs'; /** * 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 — COULD * be a kind, so it is `kind` (the loader holds). 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. * * 🚨 A `__kind` KEY IS NOT A KIND (content-ir rule 28, Arman 2026-10-25). The * key only says "this could be one"; the value must name a registered kind. * When the host's registry has MEASURED that the named slug does not exist * (`setKindSlugOracle` → "absent"), the region is `not_kind` — plain JSON, never * drawn as a kind instance. A registry that has not answered yet ("unknown") * never publishes that negative: the loader keeps holding (the cold-verdict * rule). * * Text-only on purpose apart from that one injected answer: it must answer for * every frame of every region, including ones whose parser never opened (an * unlabelled fence, a reload, a plain markdown fence). */ /** * The host registry's MEASURED answer for a slug: `registered`, `absent` (a read * answered and no kind by that name exists), or `unknown` (not asked/answered * yet). Only `absent` changes a verdict. */ type KindSlugStatus = "registered" | "absent" | "unknown"; /** Install the host registry's answer (rich-content does this). `null` restores "unknown". */ declare function setKindSlugOracle(oracle: ((slug: string) => KindSlugStatus) | null): void; /** True only when the registry has measured that `slug` names no kind. */ declare function namesNoKind(slug: string): boolean; 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; /** * 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; /** 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 * (`&quot;`), `_` 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): 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): 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 (``, ``, 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 | 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 " 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 " 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 * " · " (`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; /** * 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, knownKeys: Iterable): Record; /** * 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 | 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, headingLevel?: "##" | "###" | "####"): string | null; /** Join markdown blocks with blank lines, dropping empty/null ones. */ declare function joinBlocks(blocks: Array): 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; /** * 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, 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, 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, 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, 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, DECISION_ANSWERS_BLOCK_TYPE, DECISION_ANSWERS_KIND, INSTANCE_TITLE_KEYS, JSON_KIND_SPELLINGS, KindImageAltUnwrap, MarkdownEscapedKindJson, 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, namesNoKind, nonJsonKindsAsCode, normalizeKindSpellings, normalizeRecoveredContainerPiece, normalizeRecoveredProsePiece, plainFieldLabel, plainValueMarkdown, pythonBalancedEnd, pythonReprAsJson, quotedSourceRanges, regionJson, registerKindValueMarkdown, rootKindSlug, scanKindSpellingRegions, setKindSlugOracle, spelledKindsAsOneLine, splitAroundEmbeddedKindJson, textCarriesKind, unescapeMarkdownKindJson, unfinishedKindLabel, unreadableKindsAsNote, unwrapKindImageAlt, valueCarriesKind, withoutLeadingJsonComments, withoutZeroWidth }; export type { BrokenKindJsonRegion, EmbeddedKindJsonPiece, EmbeddedKindJsonRegion, EmbeddedKindSearchOptions, GrammarDialect, JsonKindSignal, KindCarryingJsonRegion, KindGrammarVerdict, KindSlugStatus, KindSpellingFamily, KindSpellingRegion, KindTextOptions, KindTextPreview, KindValueToMarkdown, NestedKindMarkdown };