@ai-matrx/rich-content 0.0.0 → 0.2.2

package/dist/display/markdown-classification/processors/utils/client-blocks.d.ts

@@ -0,0 +1,169 @@
+/**
+ * client-blocks.ts — the CLIENT-ONLY render-block vocabulary.
+ *
+ * OWNER: the markdown splitter (content-splitter-v2.ts, this directory).
+ * These block types are produced ONLY by the frontend splitter from streamed/
+ * persisted markdown — Python never emits them. If Python ever needs to send
+ * one, add it to the server vocabulary
+ * (aidream `matrx_connect/context/data_render_blocks.py` or
+ * `render_blocks.py`), regenerate stream-events.ts, and delete it here.
+ *
+ * This file is deliberately hand-maintained (there is no server source to
+ * generate it from) but it is NOT free-form: every type token here is
+ * classified by the content-vocab crosswalk
+ * (scripts/shape/content-vocab-crosswalk.json — regenerate with
+ * `pnpm check:shapes:crosswalk:refresh`). Adding a type without a crosswalk
+ * classification rule fails `pnpm check:shapes:crosswalk`.
+ *
+ * The server-synthesized twin vocabulary (audio_output, function_result, …)
+ * is GENERATED into @ai-matrx/agents/generated/stream-events
+ * (ServerOnlyRenderBlock / ServerOnlyBlockType) — both replaced the retired
+ * hand-maintained @ai-matrx/agents/generated/missing-types drift patch.
+ */
+/** A directory/file tree rendered from box-drawing or ASCII connectors. */
+export interface TreeRenderBlock {
+    type: "tree";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/** A styled accent divider (*** pattern). */
+export interface AccentDividerRenderBlock {
+    type: "accent-divider";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/** A styled heavy divider (#=== pattern). */
+export interface HeavyDividerRenderBlock {
+    type: "heavy-divider";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * An audio player parsed from a markdown audio link in streamed/persisted text
+ * (e.g. `[Audio URL: …]` or a standalone `….mp3` link). Mirrors the typed
+ * `image`/`video` render blocks: the URL travels on the splitter block's `src`
+ * field, not here. This is the streaming-text twin of the server-side
+ * `audio_output` block — see content-splitter-v2.ts `detectAudioMarkdown`.
+ */
+export interface AudioRenderBlock {
+    type: "audio";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A raw SVG illustration emitted by an agent in a ```svg fence — rendered
+ * sandboxed (no scripts) and responsively from its viewBox. Client-only for
+ * now; promote to Python's stream-events.ts when the server emits a typed svg
+ * block. See components/mardown-display/blocks/svg/SvgBlock.tsx.
+ */
+export interface SvgRenderBlock {
+    type: "svg";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A data chart emitted by an agent in a ```chart fence — a small JSON spec
+ * (type + data) rendered with recharts (loaded via next/dynamic ssr:false).
+ * Client-only for now. See components/mardown-display/blocks/chart/ChartBlock.tsx.
+ */
+export interface ChartRenderBlock {
+    type: "chart";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/** Interactive Leaflet map from a ```map JSON spec (markers/places). Client-only. */
+export interface MapRenderBlock {
+    type: "map";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/** KPI / headline-metric cards from a ```stats JSON spec. Client-only. */
+export interface StatsRenderBlock {
+    type: "stats";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/** Before/after diff from a ```diff JSON spec ({old,new}). Client-only. */
+export interface DiffRenderBlock {
+    type: "diff";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A clickable reference to a platform entity (agent, note, task, file, etc.).
+ * Emitted by an agent as a ```json fence keyed by `item_presentation`:
+ *   { "item_presentation": { "id": "...", "type": "agent", "name": "...", "about": "..." } }
+ * Client-only for now (detected by the splitter's JSON_BLOCK_PATTERNS). The
+ * renderer auto-enriches recognized types from the DB and opens the matching
+ * window panel on click. See features/item-presentation/.
+ */
+export interface ItemPresentationRenderBlock {
+    type: "item_presentation";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A playable YouTube embed parsed from a YouTube link in streamed/persisted
+ * text — a linked thumbnail `[![alt](thumb)](yt-url)`, a plain `[text](yt-url)`
+ * link, or a bare YouTube URL on its own line. The splitter extracts the video
+ * id + start offset onto `metadata` (videoId/start/title/poster) and keeps the
+ * original line on `content` so it survives the DB round-trip. The server twin
+ * is the `media_block(kind: "youtube")` render block — both render through the
+ * single `features/files/blocks/youtube/YouTubeEmbed` component. See
+ * content-splitter-v2.ts `detectYoutubeMarkdown`.
+ */
+export interface YoutubeRenderBlock {
+    type: "youtube";
+    content: string;
+    src?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A Matrx Envelope embedded in content via a ```matrx fence. The `content`
+ * is the raw envelope JSON `{ matrx_version, kind, type, items: [...] }`.
+ * In-content position only resolves `reference` / `secret` kinds (an action in
+ * prose is shown, never executed). Rendered by features/matrx-envelope/
+ * MatrxEnvelopeBlock — chips for references, a muted card otherwise.
+ * See docs/protocol/MATRX_ENVELOPE.md + MATRX_REFERENCES.md.
+ */
+export interface MatrxEnvelopeRenderBlock {
+    type: "matrx";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * An output-schema proposal emitted by the "JSON Schema Generator" agent as a
+ * ```json fence: `{ name: string, schema: object, strict?: boolean }`. The FE
+ * recognizes it (see content-splitter-v2 JSON_BLOCK_PATTERNS) and offers
+ * "Apply to an agent" (writes agx_agent.output_schema). Client-only.
+ * Classified PROTOCOL in the crosswalk (drives a side-effecting apply flow).
+ * See features/agents/components/schema-proposal/.
+ */
+export interface SchemaProposalRenderBlock {
+    type: "schema_proposal";
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A reference to one of OUR OWN files (a cld_files-backed signed S3 URL, a
+ * public CDN URL or a share-link byte endpoint)
+ * found as a plain markdown link / bare URL in streamed/persisted text. Unlike
+ * `image`/`audio`/`video` blocks this carries NO declared type — the renderer
+ * recovers a `file_id` (or other `FileSource`) via `recognizeOurFileUrl`,
+ * discovers the real file type (sniffed from the URL or by hydrating the
+ * cld_files row), and renders the universal inline previewer. Signed URLs
+ * auto-re-mint through the file handler. On any failure it degrades to the
+ * original markdown link. The original line stays on `content` so it survives
+ * the DB round-trip and re-detects on reload. Client-only — see
+ * content-splitter-v2.ts `detectMatrxFileMarkdown` +
+ * components/mardown-display/blocks/matrx-file/MatrxFileBlock.tsx.
+ */
+export interface MatrxFileRenderBlock {
+    type: "matrx_file";
+    content: string;
+    src?: string;
+    alt?: string;
+    metadata?: Record<string, unknown>;
+}
+export type ClientOnlyRenderBlock = TreeRenderBlock | AccentDividerRenderBlock | HeavyDividerRenderBlock | AudioRenderBlock | SvgRenderBlock | ChartRenderBlock | MapRenderBlock | StatsRenderBlock | DiffRenderBlock | ItemPresentationRenderBlock | YoutubeRenderBlock | MatrxEnvelopeRenderBlock | SchemaProposalRenderBlock | MatrxFileRenderBlock;
+export type ClientOnlyBlockType = ClientOnlyRenderBlock["type"];

package/dist/display/markdown-classification/processors/utils/content-splitter-core.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Content Splitter V2 - PRODUCTION Parser
+ *
+ * A streamlined, registry-based markdown parser optimized for streaming content.
+ * This is the current production parser used by MarkdownStream.
+ *
+ * Key improvements over V1:
+ * - Registry-based architecture for block types (easy to extend)
+ * - Clear separation: detection → extraction → validation
+ * - Organized by content type (JSON, XML, Markdown)
+ * - 38% code reduction (1253 → 781 lines)
+ * - Maintains all streaming logic and caching from V1
+ *
+ * Parsing order (deterministic):
+ * 1. MATRX patterns
+ * 2. Code blocks (with JSON special types)
+ * 3. XML tag blocks
+ * 4. Images
+ * 5. Videos
+ * 6. Tables
+ * 7. Text (fallback)
+ *
+ * Legacy V1 parser available in content-splitter.ts for rollback if needed.
+ *
+ * THIS module is the environment-neutral core (RC-B2b, 2026-09-24): it never
+ * imports the kind/component registries — those arrive as SplitterEnvelopes.
+ * Client code imports content-splitter-v2.ts (hooks bound); the server
+ * rich-content level calls splitContentIntoBlocksWith(src, NO_SPLITTER_ENVELOPES).
+ */
+import type { TypedRenderBlock, ServerOnlyBlockType } from "@ai-matrx/agents/generated/stream-events";
+import type { ClientOnlyBlockType } from "./client-blocks.js";
+import { type CanonicalBlockIR } from "@ai-matrx/content-ir";
+/**
+ * All block type strings this splitter can emit — the union of:
+ *   - TypedRenderBlock["type"]  : render_block wire types (generated stream-events.ts)
+ *   - ClientOnlyBlockType       : splitter-only types (client-blocks.ts, this directory)
+ *   - ServerOnlyBlockType       : FE-synthesized data-event wrappers (generated
+ *                                 stream-events.ts ServerOnlyRenderBlock)
+ */
+type SplitterBlockType = TypedRenderBlock["type"] | ClientOnlyBlockType | ServerOnlyBlockType;
+/**
+ * The three kind-envelope hooks the splitter calls. They attach the canonical
+ * content-IR envelope to a COMPLETED region's `metadata` — they never change a
+ * block's type, boundaries or content. The client entry
+ * (content-splitter-v2.ts) binds the registry-backed hooks; the server
+ * rich-content level passes NO_SPLITTER_ENVELOPES, so this module's graph
+ * stays free of the kind/component registries (which create React contexts
+ * at module scope and cannot load in a React Server Component).
+ */
+export interface SplitterEnvelopes {
+    withIrEnvelope(source: string, metadata: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+    fenceRegion(language: string, regionText: string): CanonicalBlockIR | null;
+    xmlRegion(tag: string, regionText: string): CanonicalBlockIR | null;
+}
+/** No envelopes: identical blocks, no kind metadata (server rendering). */
+export declare const NO_SPLITTER_ENVELOPES: SplitterEnvelopes;
+/**
+ * SplitterBlock — the output type of splitContentIntoBlocksWith / splitContentIntoBlocksV2.
+ *
+ * Structurally aligned with TypedRenderBlock so that the same type
+ * discriminant works across the splitter, Redux, server events, and renderer.
+ * Omits blockId/blockIndex/status/data (server/Redux concerns) and adds
+ * language/src/alt which are needed by BlockRenderer for code/image/video blocks.
+ *
+ * The bridge field `serverData` is NOT defined here — BlockRenderer adds it
+ * via its local `BlockWithServerData` extension when merging server-processed blocks.
+ */
+export interface SplitterBlock {
+    type: SplitterBlockType;
+    content: string;
+    language?: string;
+    src?: string;
+    alt?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * @deprecated Use SplitterBlock instead.
+ * Kept as an alias so existing imports continue to compile during migration.
+ */
+export type ContentBlock = SplitterBlock;
+/**
+ * Detection is recursive across arrival containers: a complete object that
+ * directly declares `__kind` becomes its own JSON/Content-IR block even when
+ * Markdown first captured it inside prose, a non-JSON fence, or XML. Every
+ * byte around recovered objects stays in document order as its original block
+ * type. Artifact wrappers already carry their body envelope for selectors and
+ * retain their identity/chrome; they are the one container that must not be
+ * exploded into anonymous fragments.
+ */
+export declare function recoverEmbeddedKindJsonBlocksWith(input: SplitterBlock[], envelopes: SplitterEnvelopes): SplitterBlock[];
+/**
+ * Code-fence languages that promote to a first-class block type (the fence
+ * language becomes the block type). Mirrors SPECIAL_CODE_LANGUAGES in
+ * aidream block_detector.py — keep the two in lockstep.
+ */
+export declare const SPECIAL_CODE_LANGUAGES: string[];
+/**
+ * Fence-language aliases that normalize to a canonical special language
+ * (e.g. ```mmd → mermaid). Mirrors CODE_LANGUAGE_ALIASES in block_detector.py.
+ */
+export declare const CODE_LANGUAGE_ALIASES: Record<string, string>;
+export declare function normalizeCodeLanguage(language: string | undefined): string | undefined;
+declare const JSON_BLOCK_PATTERNS: {
+    readonly quiz: {
+        readonly rootKey: "quiz_title";
+        readonly validate: (parsed: unknown) => "" | 0 | boolean | null | undefined;
+    };
+    readonly presentation: {
+        readonly rootKey: "presentation";
+        readonly validate: (parsed: unknown) => boolean;
+    };
+    readonly decision_tree: {
+        readonly rootKey: "decision_tree";
+        readonly validate: (parsed: unknown) => import("../../../../utils/json.js").JsonValue | undefined;
+    };
+    readonly comparison_table: {
+        readonly rootKey: "comparison";
+        readonly validate: (parsed: unknown) => "" | 0 | boolean | null | undefined;
+    };
+    readonly diagram: {
+        readonly rootKey: "diagram";
+        readonly validate: (parsed: unknown) => "" | 0 | boolean | null | undefined;
+    };
+    readonly math_problem: {
+        readonly rootKey: "math_problem";
+        readonly validate: (parsed: unknown) => "" | 0 | boolean | null | undefined;
+    };
+    readonly item_presentation: {
+        readonly rootKey: "item_presentation";
+        readonly validate: (parsed: unknown) => boolean;
+    };
+    readonly schema_proposal: {
+        readonly rootKey: "name";
+        readonly validate: (parsed: unknown) => boolean;
+    };
+};
+export type DetectedJsonBlockType = keyof typeof JSON_BLOCK_PATTERNS | "matrx";
+export declare function detectJsonBlockType(content: string): DetectedJsonBlockType | null;
+/** Extracts key="value" pairs from an XML opening tag string. */
+export declare function parseXmlAttributes(openingTag: string): Record<string, string>;
+/**
+ * Extracts a complete, unrecognized XML element so it can reuse the same
+ * enhanced XML renderer as a fenced ```xml block.
+ *
+ * This deliberately runs after every recognized XML detector. It also requires
+ * a line-leading, balanced root element (or a self-closing element), which keeps
+ * inline angle-bracket prose and incomplete streaming text on the markdown path.
+ * Curated raw HTML remains on its existing sanitized HTML path.
+ */
+export interface UnrecognizedXmlContainerTracker {
+    readonly rootTag: string;
+    consumeLine(line: string, startOffset?: number): number | null;
+}
+interface UnrecognizedXmlStart {
+    tracker: UnrecognizedXmlContainerTracker;
+    rootStart: number;
+}
+/** Protect tag attributes while an opening tag is still arriving. */
+export declare function isUnclosedGenericXmlOpening(source: string): boolean;
+/** Starts a line-leading generic XML container, after known/raw-HTML ownership. */
+export declare function startUnrecognizedXmlContainer(line: string): UnrecognizedXmlStart | null;
+/** Redux parity hook: classify a whole text block before kind recovery splits it. */
+export declare function isCompleteUnrecognizedXmlContainer(source: string): boolean;
+export declare function detectImageMarkdown(line: string): {
+    isImage: boolean;
+    src?: string;
+    alt?: string;
+};
+/**
+ * Count standalone (http/https) markdown images on a single line.
+ *
+ * Drives the standalone-block-vs-inline-flow decision: a line with exactly ONE
+ * image becomes a full-width `image` block (the deliberate "big incoming image"
+ * treatment); a line with 2+ images is intentionally LEFT as text so
+ * react-markdown renders them side by side. The rule is "respect line breaks" —
+ * no line break between images means the author wants them inline, a line break
+ * means stacked. Only the `![alt](url)` form is counted; the single custom
+ * `[Image URL: …]` form never yields more than one.
+ */
+export declare function countInlineImages(line: string): number;
+export declare function detectVideoMarkdown(line: string): {
+    isVideo: boolean;
+    src?: string;
+    alt?: string;
+};
+export declare const AUDIO_URL_EXT: RegExp;
+/**
+ * Extracts the audio URL + label from a single line that is an audio link, or
+ * returns null. Shared by the splitter, the streaming block accumulator, and
+ * the content prefilter so all three agree on what counts as an audio link.
+ * Three accepted shapes, all line-scoped:
+ *   1. `[Audio URL: https://…]`  — backend custom format, symmetric with
+ *      `[Image URL: …]` / `[Video URL: …]`.
+ *   2. `[label](https://…/clip.mp3)` or `![label](…)` — a standard markdown
+ *      link whose URL is an audio file AND which is the entire line (so inline
+ *      links inside a sentence are left as ordinary links).
+ *   3. A bare audio URL on its own line.
+ */
+export declare function extractAudioLink(line: string): {
+    src: string;
+    alt: string;
+} | null;
+/**
+ * Detect a link (or bare URL) to one of OUR OWN files anywhere in a line.
+ *
+ * Unlike image/video/audio detection, the URL carries no declared type — we
+ * only assert "this is ours" via `recognizeOurFileUrl`. The match can sit
+ * mid-line; we return the text BEFORE (`pre`) and AFTER (`post`) the file token
+ * so the renderer can render `markdown(pre) → inline file → markdown(post)` and
+ * handle the inline case gracefully without shattering the paragraph.
+ *
+ * Accepts both `[label](our-url)` (optionally `!`-prefixed) and a bare
+ * `our-url`. Returns the FIRST our-file match on the line.
+ */
+export declare function detectMatrxFileMarkdown(line: string): {
+    isMatrxFile: boolean;
+    url?: string;
+    label?: string;
+    pre?: string;
+    post?: string;
+};
+export declare const splitContentIntoBlocksWith: (mdContent: string, envelopes: SplitterEnvelopes) => SplitterBlock[];
+export {};