@qilin-agent/client-ui-primitives 0.0.0-stage → 3.1.3

package/lib/types/input-modality.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Document-wide input tracking shared by tooltips and focus-ring styles.
+ * Tooltips follow the last input; rings follow navigation or a key followed by
+ * focus on a different control. Modifiers and refocusing alone keep rings silent.
+ * Module-level listeners live for the document lifetime; Node imports are inert.
+ */
+/** Modality values published on the document element. */
+export declare const INPUT_MODALITY: {
+    readonly pointer: "pointer";
+    readonly keyboard: "keyboard";
+};
+/** Attribute carrying whether focus navigation last owned focus. */
+export declare const INPUT_MODALITY_ATTRIBUTE = "data-input-modality";
+/**
+ * Whether the last input came from a pointer, independently of ring visibility.
+ * @returns True after pointer input; false after any key.
+ */
+export declare function pointerModality(): boolean;
+//# sourceMappingURL=input-modality.d.ts.map

package/lib/types/keyboard-composition.d.ts

@@ -0,0 +1,11 @@
+/** Composition lifetime for local keyboard handlers, including a late closing keydown. */
+/**
+ * Observe composition until its closing key is released or consumed.
+ * @param document - document whose input events belong to the caller.
+ * @returns an event guard and a disposer for all listeners.
+ */
+export declare function observeComposition(document: Document): {
+    guards(event: KeyboardEvent): boolean;
+    dispose(): void;
+};
+//# sourceMappingURL=keyboard-composition.d.ts.map

package/lib/types/markdown/CodeBlock.d.ts

@@ -0,0 +1,30 @@
+import type { Ref } from 'react';
+export interface CodeBlockProps {
+    /** The source text, rendered verbatim (trailing newline trimmed for display). */
+    code: string;
+    /** Grammar hint (markdown fence info string or a fixed caller id); unknown = plain. */
+    lang?: string | undefined;
+    /**
+     * The code is still growing (a streaming markdown fence): highlight through
+     * a per-instance {@link StreamingHighlightSession}, which re-tokenizes only
+     * appended text and keeps completed line groups (and DOM) untouched. The
+     * caller must keep the component instance stable across growth (a
+     * stream-stable React key); an unchanged streamed fence also retains that
+     * tree when it settles. Cold settled callers get shiki's HTML.
+     */
+    streaming?: boolean | undefined;
+    /** Extra class merged onto the wrapper (callers position; this component draws). */
+    className?: string | undefined;
+    /** Ref for the stable source-content wrapper, for owners that use it as a scrollport. */
+    contentRef?: Ref<HTMLDivElement> | undefined;
+    /** Show a numbered gutter without adding numbers to copied source. Defaults to false. */
+    lineNumbers?: boolean | undefined;
+    /** Show the language and copy header; false when the caller supplies a toolbar. Defaults to true. */
+    showHeader?: boolean | undefined;
+    /** Copy-button idle label; the owner passes localized copy (this package is cordis-free, so copy arrives via props). */
+    copyLabel: string;
+    /** Copy-button label during the post-copy confirmation window. */
+    copiedLabel: string;
+}
+export declare function CodeBlock({ code, lang, streaming, className, contentRef, lineNumbers, showHeader, copyLabel, copiedLabel, }: CodeBlockProps): import("react").JSX.Element;
+//# sourceMappingURL=CodeBlock.d.ts.map

package/lib/types/markdown/JsonBlock.d.ts

@@ -0,0 +1,8 @@
+export declare function JsonBlock({ label, payload, defaultOpen, truncatedLabel }: {
+    label: string;
+    payload: unknown;
+    defaultOpen?: boolean;
+    /** Footer appended when the body exceeds the char cap, given the full length (this package is cordis-free, so copy arrives via props). */
+    truncatedLabel: (total: number) => string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=JsonBlock.d.ts.map

package/lib/types/markdown/MarkdownDelegate.d.ts

@@ -0,0 +1,46 @@
+import type { ReactNode } from 'react';
+import type { ImageLightboxLabels } from '../ImageLightbox.tsx';
+/**
+ * Handle one sanitized absolute HTTP(S) URL selected from Markdown.
+ * @param href - destination URL.
+ */
+export type MarkdownExternalLinkHandler = (href: string) => void;
+/** Navigation capabilities supplied by the nearest Markdown owner. */
+export interface MarkdownDelegate {
+    /** Image previews for decoded local paths in this owner's workspace. */
+    readonly fileImages?: {
+        resolve: (path: string) => string | undefined;
+        labels: ImageLightboxLabels & {
+            open: string;
+            loading: string;
+            failed: string;
+        };
+    } | undefined;
+    /** Ordinary HTTP(S) activation; absent handlers retain native anchor behavior. */
+    readonly openExternalLink?: MarkdownExternalLinkHandler | undefined;
+    /**
+     * Open a decoded local destination from settled Markdown; absent handlers leave plain text.
+     * @param path - Absolute or workspace-relative file path.
+     * @param options - First line to reveal when the destination specifies a line or range.
+     */
+    readonly openFile?: ((path: string, options?: {
+        line?: number;
+    }) => void) | undefined;
+}
+/** Props for one Markdown navigation scope. */
+export interface MarkdownDelegateProviderProps extends MarkdownDelegate {
+    readonly children: ReactNode;
+}
+/**
+ * Scope Markdown navigation without threading callbacks through renderers.
+ * Nested providers replace the enclosing capabilities. Handler changes reach cached links.
+ * @param props - Child tree and its file and HTTP(S) link handlers.
+ * @returns the scoped child tree.
+ */
+export declare function MarkdownDelegateProvider({ children, openExternalLink, openFile, fileImages, }: MarkdownDelegateProviderProps): ReactNode;
+/**
+ * Read the nearest Markdown navigation capabilities.
+ * @returns Owner callbacks, or an empty delegate outside a provider.
+ */
+export declare function useMarkdownDelegate(): MarkdownDelegate;
+//# sourceMappingURL=MarkdownDelegate.d.ts.map

package/lib/types/markdown/MarkdownText.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Untrusted assistant-Markdown renderer over the direct mdast pipeline:
+ * `parse.ts` grammars, the incremental streaming parser, and `render.tsx`.
+ * While a message streams, all but the trailing two blocks freeze as cached
+ * React elements and only the source tail behind them re-parses per chunk,
+ * so per-chunk work tracks the tail size instead of the whole reply. Frozen
+ * blocks keep their source-offset keys when they cross the freeze boundary,
+ * so React reconciles instead of remounting. Known deviation while
+ * streaming: a reference-style link or footnote whose definition sits on the
+ * other side of the freeze boundary renders literally until the settled
+ * full parse self-heals it.
+ */
+import type { MarkdownFileMentions, MarkdownHtmlRenderer, MarkdownLabels, MarkdownPathImages } from './render.tsx';
+import 'katex/dist/katex.min.css';
+export type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownHtmlRenderer, MarkdownLabels, MarkdownPathImages } from './render.tsx';
+/**
+ * Render untrusted assistant-authored Markdown as semantic React elements.
+ * @param props - Markdown source text preserved by the session projection;
+ * `streaming` parses incrementally across chunks and highlights fences as
+ * they grow (each fence re-tokenizes only appended text; TeX stays literal
+ * until the finalize swap so incomplete formulae never flash errors);
+ * `labels` forwards localized fence and footnote chrome — pass a
+ * reference-stable object (memoized per locale revision), because a new
+ * identity discards the streaming render cache mid-message. `fileMentions`
+ * links inline-code tokens its resolver recognizes as real files, and
+ * `pathImages` rewrites image destinations that are local file paths into
+ * displayable URLs its resolver vouches for. Those two vocabularies are the
+ * single streaming gate — they apply to settled renders only, because a
+ * streaming message's vocabulary is not final and frozen cached elements
+ * must not bake in handlers that could go stale. `html` renders authored raw
+ * HTML through the owner's own sanitizer; without it the runs stay literal
+ * text, and it joins `labels` in the streaming cache identity because frozen
+ * elements bake it in. A surrounding
+ * `MarkdownDelegateProvider` can delegate ordinary HTTP(S) activation while
+ * modified clicks retain native behavior. `variant="compact"` uses secondary
+ * text sizing, uniform bold headings, and tight block spacing; the default
+ * `body` variant uses the full document typography.
+ * The provider's `openFile` enables local Markdown links in settled messages,
+ * including `#L24` and `#L24-L30` destinations (ranges open at their first line).
+ * @returns A GFM document with TeX math rendered through KaTeX; raw HTML
+ * stays literal unless `html` supplies a renderer, and unsafe protocols are
+ * disabled. Local links without an opener remain text; absolute HTTP(S)
+ * images render directly.
+ */
+export declare const MarkdownText: import("react").MemoExoticComponent<({ text, streaming, labels, fileMentions, pathImages, html, variant, }: {
+    text: string;
+    streaming?: boolean;
+    labels: MarkdownLabels;
+    fileMentions?: MarkdownFileMentions | undefined;
+    pathImages?: MarkdownPathImages | undefined;
+    html?: MarkdownHtmlRenderer | undefined;
+    variant?: "body" | "compact";
+}) => import("react").JSX.Element>;
+//# sourceMappingURL=MarkdownText.d.ts.map

package/lib/types/markdown/cjkFriendlyStrong.d.ts

@@ -0,0 +1,9 @@
+/** Let asterisk strong emphasis close after punctuation when CJK prose continues without whitespace. */
+import type { Extension } from 'micromark-util-types';
+/**
+ * Extend CommonMark asterisk strong emphasis for punctuation-delimited CJK
+ * prose, as a micromark syntax extension for `fromMarkdown`.
+ * @returns The micromark syntax extension.
+ */
+export declare function cjkFriendlyStrong(): Extension;
+//# sourceMappingURL=cjkFriendlyStrong.d.ts.map

package/lib/types/markdown/file-link.d.ts

@@ -0,0 +1,13 @@
+/** Local Markdown destinations accepted by the file-preview callback. */
+/**
+ * Decode a file destination and its optional GitHub-style line fragment.
+ * Literal `?` and `#` in filenames must be percent-encoded.
+ * @param value - Parsed Markdown link destination.
+ * @returns A local path and optional first line, or undefined for URLs,
+ * fragment-only links, queries, malformed escapes, or invalid line ranges.
+ */
+export declare function parseFileLink(value: string): {
+    path: string;
+    line?: number;
+} | undefined;
+//# sourceMappingURL=file-link.d.ts.map

package/lib/types/markdown/highlight.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The client's ONE syntax highlighter: a synchronous fine-grained shiki core
+ * (JavaScript regex engine — no oniguruma WASM, bundle-friendly) with an
+ * explicit grammar allowlist and a CSS-variables theme. Colors live in the
+ * theme package's token sheets as `--shiki-*` custom properties (light and
+ * dark blocks), never here — the repo's tokens-only styling rule.
+ *
+ * Only the three markdown-fence and `run_code` grammars (TypeScript, shell,
+ * JSON) load into the singleton at boot — the set every session renders. The
+ * read card's wider extension set (the file-extension language hints the read
+ * tool's `langFromPath` emits — `packages/fs/tool-fs`: python, rust, yaml,
+ * markup, …) is imported lazily and registered the first time such a language
+ * is requested, so a session that never opens a read card in one of those
+ * languages pays neither the ~1.6 MB of grammar modules nor their synchronous
+ * init. The first render of a lazy language falls back to plain text while its
+ * grammar loads, then {@link onGrammarLoaded} notifies subscribers to re-render
+ * with highlighting. An unknown or absent language falls back to plain text (no
+ * highlighting, still monospace) — never an error.
+ */
+import type { CSSProperties } from 'react';
+/**
+ * Whether a language hint can use the shared syntax highlighter.
+ * @param lang - Language hint from a code surface.
+ * @returns Whether the hint resolves to a supported grammar.
+ */
+export declare function supportsHighlighting(lang: string | undefined): boolean;
+/**
+ * Subscribe to lazy-grammar load completions; `listener` fires after a
+ * {@link LAZY_GRAMMARS} grammar finishes registering on the singleton, so a
+ * caller that rendered its plain fallback while the grammar loaded can
+ * re-highlight. Uses the `useSyncExternalStore` subscribe signature; pair it with
+ * {@link grammarLoadCount} as the snapshot. Returns an unsubscribe function.
+ * @param listener - invoked (no args) on each grammar-load completion.
+ * @returns a disposer that removes the listener.
+ */
+export declare function subscribeGrammarLoaded(listener: () => void): () => void;
+/**
+ * The lazy-grammar load counter — a value that changes on every load, so a
+ * `useSyncExternalStore` snapshot re-renders the subscriber when a grammar
+ * registers. Opaque: only its identity across renders matters.
+ * @returns the current load count.
+ */
+export declare function grammarLoadCount(): number;
+/**
+ * Highlight `code` into shiki's HTML (a single `<pre class="shiki">` tree)
+ * when `lang` maps to a registered grammar; `undefined` means the caller
+ * renders its plain fallback. A lazy grammar not yet loaded returns `undefined`
+ * for this call and loads in the background; subscribe with
+ * {@link onGrammarLoaded} to re-highlight once it registers.
+ * @param code - the source text.
+ * @param lang - the language hint (a markdown fence info string or a fixed caller id).
+ * @returns the highlighted HTML, or `undefined` for unknown or not-yet-loaded languages.
+ */
+export declare function highlightToHtml(code: string, lang: string | undefined): string | undefined;
+/**
+ * One highlighted run of a line: the text and the inline style shiki assigned
+ * it. The css-variables theme colors every run through a `--shiki-*` custom
+ * property, so `style.color` is always present; it is held as a style object
+ * rather than a bare color so a run spreads onto a `<span style>` uniformly.
+ */
+export interface HighlightSpan {
+    text: string;
+    style: CSSProperties;
+}
+/**
+ * Incremental highlighter for one growing streaming fence. TextMate
+ * tokenization is line-based and forward-only — a line's tokens depend only on
+ * its own text and the grammar state entering it — so appended text never
+ * changes a completed line's tokens. The session caches the spans of every
+ * completed line together with the grammar state after them;
+ * {@link updateFrame} reports only newly completed lines plus the still-growing
+ * last line, while {@link update} materializes the complete compatibility
+ * result. Per-call tokenization cost therefore excludes the completed prefix,
+ * and the result equals a from-scratch tokenization of the same code.
+ * Non-append input and a change of resolved grammar reset the cache and
+ * re-tokenize fully, so any input stays correct.
+ */
+export declare class StreamingHighlightSession {
+    /** Grammar id the cache was built with; a different resolution resets it. */
+    private resolved;
+    /** Newline-terminated source prefix covered by {@link spans}. */
+    private prefix;
+    /** Cached spans, one entry per completed line of {@link prefix}. */
+    private spans;
+    /** Grammar state after {@link prefix}; undefined = the grammar's initial state. */
+    private state;
+    private lastCode;
+    private lastLang;
+    private lastResult;
+    private generation;
+    private lastFrame;
+    private reset;
+    /** Tokenize `text` with `resolved`, resuming from the cached grammar state when one exists. */
+    private tokenize;
+    /**
+     * Tokenize one update as a delta for a retained renderer.
+     * @param code - the fence text accumulated so far.
+     * @param lang - the language hint.
+     * @returns Newly completed lines plus the current tail, or `undefined` for the plain arm.
+     */
+    updateFrame(code: string, lang: string | undefined): StreamingHighlightFrame | undefined;
+    /**
+     * Tokenize the fence's current text into per-line highlighted runs;
+     * `undefined` means the caller renders its plain fallback. Idempotent per
+     * (`code`, `lang`) input — repeated calls return the identical result array —
+     * and a retained line keeps its span-array identity across growing calls, so
+     * a React caller can reuse cached line elements. A lazy grammar not yet
+     * loaded returns `undefined` and loads in the background exactly as
+     * {@link highlightToHtml} does; the next call after it registers highlights.
+     * @param code - the fence text accumulated so far (display-trimmed, no synthetic trailing newline).
+     * @param lang - the language hint (a markdown fence info string).
+     * @returns one entry per line of `code` (each an array of runs), or `undefined` for unknown or not-yet-loaded languages.
+     */
+    update(code: string, lang: string | undefined): readonly HighlightSpan[][] | undefined;
+}
+/** One retained-renderer update from {@link StreamingHighlightSession.updateFrame}. */
+export interface StreamingHighlightFrame {
+    /** Changes whenever prior completed lines must be discarded. */
+    readonly generation: number;
+    /** Completed lines added since the preceding frame in this generation. */
+    readonly appended: readonly HighlightSpan[][];
+    /** The still-growing final line or lines, replaced by the next frame. */
+    readonly tail: readonly HighlightSpan[][];
+}
+/**
+ * Tokenize `code` into per-line highlighted runs when `lang` maps to a
+ * registered grammar; `undefined` means the caller renders its plain fallback.
+ * A line-numbered view needs the token runs split per line (one gutter number
+ * per line), which the single-`<pre>` {@link highlightToHtml} does not expose,
+ * so this returns shiki's own 2D line/token structure narrowed to what a run
+ * renders. Each run's color is a `--shiki-*` custom property, keeping token
+ * colors on the theme package's sheets exactly as the HTML path does; the
+ * markup font-style bits the theme lets through (bold/italic/underline in
+ * markdown scopes) are dropped — the line-numbered file view renders
+ * color-only runs. The trailing newline shiki appends as a final empty line
+ * is dropped so the run count matches the caller's own line array.
+ * @param code - the source text.
+ * @param lang - the language hint (a file-extension-derived language id).
+ * @returns one entry per source line (each an array of runs), or `undefined` for unknown or not-yet-loaded languages.
+ */
+export declare function highlightLines(code: string, lang: string | undefined): HighlightSpan[][] | undefined;
+//# sourceMappingURL=highlight.d.ts.map

package/lib/types/markdown/incremental.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Incremental block-level markdown parsing for an append-only text stream.
+ *
+ * Re-parsing the whole accumulated document on every streaming chunk is
+ * quadratic in the final reply length. CommonMark block parsing is line-based
+ * and appended text can only reshape the parse frontier — the last top-level
+ * block (a paragraph becoming a setext heading or a table, or a list
+ * continuing after a blank line) — so earlier blocks are final. This parser
+ * therefore freezes all but the trailing {@link UNSTABLE_TAIL_BLOCKS} blocks
+ * and re-parses only the source tail behind them. A final unclosed top-level
+ * fence cannot freeze as a block, so its completed content lines use a second
+ * frontier: only the last completed line and current partial line return
+ * through the caller's grammar. Each source region is therefore parsed a
+ * bounded number of times over the stream instead of once per chunk.
+ *
+ * The block freeze boundary comes from the parser's own `position` offsets.
+ * The cut sits at the *end offset* of the last frozen block (not the next
+ * block's start): a following block's start offset excludes up to three spaces
+ * of insignificant leading indentation, which is harmless to drop, but
+ * cutting at the previous end also keeps the inter-block blank lines in the
+ * tail so the sliced source stays verbatim. Fence scanning only recognizes a
+ * parser-confirmed code node and closing delimiter; ambiguous input returns to
+ * the normal tail parse.
+ *
+ * Known deviation, shared with any prefix-freeze scheme: micromark resolves
+ * reference-style links and footnotes document-wide at parse time, so a
+ * reference whose definition lands on the other side of the freeze boundary
+ * renders literally until the settled full parse self-heals it.
+ */
+import type { Root, RootContent } from 'mdast';
+/** A top-level mdast block plus a render key that is stable across chunks. */
+export interface PositionedBlock {
+    /** The parsed block. Positions inside it are relative to its parse slice. */
+    readonly node: RootContent;
+    /**
+     * The block's start offset in the full source text. Stable from the frame
+     * a block first appears through freezing, so React reconciles rather than
+     * remounts when a block crosses the freeze boundary.
+     */
+    readonly key: number;
+}
+/** One {@link IncrementalMarkdownParser.update} result. */
+export interface IncrementalBlocks {
+    /** Blocks that can no longer change; grows monotonically per generation. */
+    readonly frozen: readonly PositionedBlock[];
+    /** The re-parsed unstable tail (at most {@link UNSTABLE_TAIL_BLOCKS} blocks plus growth). */
+    readonly tail: readonly PositionedBlock[];
+    /** Bumped whenever non-append input discards the frozen prefix; callers drop caches keyed on it. */
+    readonly generation: number;
+}
+/**
+ * Append-only incremental parser over a caller-supplied grammar. One instance
+ * accumulates one streaming document; non-append input resets it.
+ */
+export declare class IncrementalMarkdownParser {
+    private readonly parse;
+    private prevText;
+    private tailStart;
+    private frozen;
+    private generation;
+    private cached;
+    private openFence;
+    /** @param parse - Grammar shared with whatever renders the blocks, so boundaries agree. */
+    constructor(parse: (text: string) => Root);
+    /** Parse one unclosed-fence content slice through the caller's grammar. */
+    private fenceValue;
+    /** Recognize the parsed tail's final unclosed fence and prepare its incremental content frontier. */
+    private openFenceState;
+    /** Extend a recognized unclosed fence without parsing its completed content prefix again. */
+    private updateOpenFence;
+    /**
+     * Fold the current accumulated text and return the frozen/tail split.
+     * Idempotent for identical input (the previous result is returned as-is),
+     * so callers may invoke it from render paths that re-execute.
+     * @param text - The full accumulated markdown source.
+     * @returns Frozen and tail blocks with stream-stable render keys.
+     */
+    update(text: string): IncrementalBlocks;
+}
+//# sourceMappingURL=incremental.d.ts.map

package/lib/types/markdown/katex.d.ts

@@ -0,0 +1,27 @@
+/**
+ * TeX-to-React via KaTeX, replicating the rehype-katex pipeline this renderer
+ * replaced: the same three-arm error chain (strict render, `strict: 'ignore'`
+ * retry, error span) and a DOM-identical element tree, so settled math keeps
+ * its exact markup. KaTeX emits an HTML string; the browser's own HTML parser
+ * (`DOMParser`, applying the spec's SVG/MathML foreign-content attribute
+ * adjustments KaTeX output relies on) turns it into a tree this module maps
+ * onto React elements — KaTeX output is a static span/MathML/SVG vocabulary
+ * with no raw user HTML, the same trust shiki's tree gets in CodeBlock.
+ *
+ * React 18 has no MathML support, so the `.katex-mathml` subtree's elements
+ * land in the HTML namespace — exactly as they did under the replaced
+ * hast-util-to-jsx-runtime pipeline. The visual arm is the `.katex-html`
+ * span tree; the MathML arm serves assistive technology, which reads it by
+ * tag name regardless of namespace.
+ */
+import type { ReactNode } from 'react';
+/**
+ * Render TeX source to React elements through KaTeX.
+ * @param value - The TeX source (math node value; fenced `math` blocks append
+ * their trailing newline to match the replaced pipeline's text extraction).
+ * @param displayMode - Display (block) versus inline rendering.
+ * @returns KaTeX's element tree, or the error span when the source does not
+ * parse (colored with KaTeX's stock `errorColor`, matching rehype-katex).
+ */
+export declare function renderTexToReact(value: string, displayMode: boolean): ReactNode;
+//# sourceMappingURL=katex.d.ts.map

package/lib/types/markdown/local-image-syntax.d.ts

@@ -0,0 +1,10 @@
+/** Recover standalone local image references with bare spaces without changing code or source offsets. */
+import type { Root } from 'mdast';
+/**
+ * Recover only unambiguous, unescaped image-only paragraphs containing a local path with spaces.
+ * @param root - Parsed Markdown tree, modified in place.
+ * @param source - Original source used to distinguish authored syntax from escaped examples.
+ * @returns The same root with recovered image nodes.
+ */
+export declare function recoverLocalImages(root: Root, source: string): Root;
+//# sourceMappingURL=local-image-syntax.d.ts.map

package/lib/types/markdown/mathCompatibility.d.ts

@@ -0,0 +1,11 @@
+/** Extend upstream dollar-only math syntax with TeX delimiters while reusing its token vocabulary. */
+import type { Extension } from 'micromark-util-types';
+/**
+ * TeX backslash delimiters and same-line display-dollar blocks as a micromark
+ * syntax extension reusing `micromark-extension-math`'s token vocabulary; the
+ * caller must also register `math()` on the same parse so the emitted tokens
+ * compile to standard math nodes.
+ * @returns The micromark syntax extension.
+ */
+export declare function mathCompatibility(): Extension;
+//# sourceMappingURL=mathCompatibility.d.ts.map

package/lib/types/markdown/mermaid.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Mermaid diagram rendering for markdown fences: a ```mermaid fence renders
+ * as a static SVG diagram through the `mermaid` library, loaded lazily on
+ * the first diagram (the library and its graph deps are heavy; the Vite
+ * build splits the dynamic import into its own chunk).
+ *
+ * Security posture (mirrors the vendored sidebar implementation this was
+ * absorbed from): `securityLevel: 'strict'` (labels escaped, no raw-HTML
+ * foreignObject), `htmlLabels: false` keeps node text as real SVG text,
+ * `bindFunctions` is never applied (static diagrams), the emitted SVG is
+ * sanitized (allowlist strip of scripts, event handlers, foreignObject,
+ * and external references) before it reaches `dangerouslySetInnerHTML`,
+ * and `suppressErrorRendering` keeps mermaid's error dump out of the
+ * document body. A failed render falls back to the fenced source block.
+ */
+import { type ReactNode } from 'react';
+/** Strip everything the diagram contract does not allow from an emitted SVG.
+ * @param svg - the library's emitted SVG document string.
+ * @returns the sanitized SVG string.
+ */
+export declare function sanitizeMermaidSvg(svg: string): string;
+/**
+ * Render one mermaid fence as a static sanitized SVG diagram.
+ * @param props - the fenced diagram source and the code-block labels for the fallback.
+ * @returns the diagram, its loading state, or the fenced source fallback.
+ */
+export interface MermaidDiagramProps {
+    /** The fenced diagram source between the fences (info string stripped). */
+    readonly code: string;
+    /** Copy-control labels for the fallback source block. */
+    readonly copyLabel: string;
+    readonly copiedLabel: string;
+    /** Alt text naming the on-page diagram stage. */
+    readonly diagramLabel: string;
+    /** Alt text naming the enlarged overlay copy. */
+    readonly enlargedLabel: string;
+}
+export declare function MermaidDiagram({ code, copyLabel, copiedLabel, diagramLabel, enlargedLabel }: MermaidDiagramProps): ReactNode;
+//# sourceMappingURL=mermaid.d.ts.map

package/lib/types/markdown/parse.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The markdown renderer's two mdast grammars, one per rendering arm. Each
+ * arm is internally consistent — the incremental tail parses, the one-shot
+ * parses, and the plain-text projection of a given grammar always agree on
+ * where blocks start and end — and the settled grammar is the streaming one
+ * plus the math extensions, so the arms differ only where TeX delimiters
+ * begin a math construct (a `$$` block is a paragraph while streaming and a
+ * math block once settled, by design).
+ */
+import type { Root } from 'mdast';
+/**
+ * Parse GFM markdown (the streaming arm's grammar: no math, so incomplete
+ * TeX never flashes KaTeX errors mid-stream).
+ * @param text - Markdown source.
+ * @returns The mdast root.
+ */
+export declare function parseGfm(text: string): Root;
+/**
+ * Parse GFM markdown plus TeX math with the compatibility delimiters
+ * (the settled arm's grammar).
+ * @param text - Markdown source.
+ * @returns The mdast root.
+ */
+export declare function parseGfmWithMath(text: string): Root;
+//# sourceMappingURL=parse.d.ts.map

package/lib/types/markdown/plain-text.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Markdown-to-plain-text projection for compact summaries and labels.
+ * Parsing shares the renderer's streaming GFM grammar ({@link parseGfm}), so
+ * the projection strips exactly the markup the renderer would draw; raw HTML
+ * stays literal, links keep their labels, images keep alt text, and code
+ * keeps its source text.
+ */
+/** Amount of parsed Markdown content returned by the extractor. */
+export type MarkdownPlainTextMode = 'all' | 'first-line' | 'first-paragraph';
+/** Options for {@link extractMarkdownPlainText}. */
+export interface MarkdownPlainTextOptions {
+    /** Projection boundary; defaults to the complete document. */
+    mode?: MarkdownPlainTextMode;
+}
+/**
+ * Parse GFM Markdown, remove its presentation markup, and preserve raw HTML literally.
+ * @param markdown - Markdown source.
+ * @param options - Optional extraction boundary.
+ * @returns Plain text for the whole document, first visible line, or first semantic paragraph.
+ */
+export declare function extractMarkdownPlainText(markdown: string, options?: MarkdownPlainTextOptions): string;
+//# sourceMappingURL=plain-text.d.ts.map