@djangocfg/widget-code 0.1.1

package/src/markdown-message/components.tsx

@@ -0,0 +1,224 @@
+import React from 'react';
+import type { Components } from 'react-markdown';
+import Mermaid from '@djangocfg/widget-diagram';
+import { ANCHOR } from '../role-tokens';
+import { CodeBlock, CodeBlockFallback } from './CodeBlock';
+import { extractTextFromChildren } from './plainText';
+
+/** Body / heading size classes per `size` level. */
+const SIZE_CLASSES: Record<'xs' | 'sm' | 'base', {
+  text: string;
+  headingBase: string;
+  headingSm: string;
+}> = {
+  xs: { text: 'text-xs', headingBase: 'text-sm', headingSm: 'text-xs' },
+  sm: { text: 'text-sm', headingBase: 'text-base', headingSm: 'text-sm' },
+  base: { text: 'text-base', headingBase: 'text-lg', headingSm: 'text-base' },
+};
+
+/**
+ * Build the chat-tuned markdown component map.
+ *
+ * Body text size follows `size` (xs/sm/base → 12/14/16px). Heading
+ * sizes are scaled a notch above the body so inline-in-chat headings
+ * stand out without dominating.
+ */
+export function createMarkdownComponents(
+  isUser: boolean = false,
+  size: 'xs' | 'sm' | 'base' = 'sm',
+  codeTheme: 'dark' | 'light' | 'auto' = 'auto',
+): Components {
+  const { text: textSize, headingBase, headingSm } = SIZE_CLASSES[size];
+  // Code blocks / diagrams only have a binary compact mode — treat the
+  // smallest text level as compact, larger ones as roomy.
+  const isCompact = size === 'xs';
+
+  return {
+    h1: ({ children }) => (
+      <h1 className={`${headingBase} font-semibold mb-2 mt-3 first:mt-0`}>{children}</h1>
+    ),
+    h2: ({ children }) => (
+      <h2 className={`${headingSm} font-semibold mb-2 mt-3 first:mt-0`}>{children}</h2>
+    ),
+    h3: ({ children }) => (
+      <h3 className={`${headingSm} font-semibold mb-1 mt-2 first:mt-0`}>{children}</h3>
+    ),
+    h4: ({ children }) => (
+      <h4 className={`${headingSm} font-semibold mb-1 mt-2 first:mt-0`}>{children}</h4>
+    ),
+    h5: ({ children }) => (
+      <h5 className={`${headingSm} font-medium mb-1 mt-2 first:mt-0`}>{children}</h5>
+    ),
+    h6: ({ children }) => (
+      <h6 className={`${headingSm} font-medium mb-1 mt-2 first:mt-0`}>{children}</h6>
+    ),
+
+    p: ({ children }) => (
+      <p className={`${textSize} mb-4 last:mb-0 leading-relaxed break-words`}>{children}</p>
+    ),
+
+    ul: ({ children }) => (
+      <ul className={`list-disc list-inside mb-2 space-y-1 ${textSize}`}>{children}</ul>
+    ),
+    ol: ({ children }) => (
+      <ol className={`list-decimal list-inside mb-2 space-y-1 ${textSize}`}>{children}</ol>
+    ),
+    li: ({ children }) => <li className="break-words">{children}</li>,
+
+    // `target` / `rel` for external links are NOT set here — the
+    // rehype-external-links plugin tags them on the rehype side, so
+    // every `<a>` that sanitize let through gets the same security
+    // treatment regardless of which renderer (default vs linkRules
+    // override) emitted it. Doing it twice here would just duplicate
+    // attributes; doing it only here would miss the linkRules path.
+    a: ({ href, children, ...rest }) => (
+      <a
+        {...rest}
+        href={href}
+        className={`${textSize} ${isUser ? ANCHOR.user : ANCHOR.assistant}`}
+      >
+        {children}
+      </a>
+    ),
+
+    pre: ({ children }) => {
+      let codeContent = '';
+      let language = 'plaintext';
+
+      if (React.isValidElement(children)) {
+        const child = children;
+        if (
+          child.type === 'code'
+          || (typeof child.type === 'function' && child.type.name === 'code')
+        ) {
+          const codeProps = child.props as {
+            className?: string;
+            children?: React.ReactNode;
+          };
+          const rawClassName = codeProps.className;
+          language = rawClassName?.replace(/language-/, '').trim() || 'plaintext';
+          codeContent = extractTextFromChildren(codeProps.children).trim();
+        } else {
+          codeContent = extractTextFromChildren(children).trim();
+        }
+      } else {
+        codeContent = extractTextFromChildren(children).trim();
+      }
+
+      if (!codeContent) {
+        return (
+          <div className="my-3 p-3 bg-muted rounded text-sm text-muted-foreground">
+            No content available
+          </div>
+        );
+      }
+
+      if (language === 'mermaid') {
+        // Inline render fits the bubble width; the Mermaid component
+        // owns its own click-to-fullscreen modal which sizes against
+        // the viewport, so we don't cap it here. A previous version
+        // hardcoded `max-w-[600px]` and that constraint leaked into
+        // the fullscreen modal too — diagram rendered at 600px in the
+        // middle of an empty viewport.
+        return (
+          <div className="my-3 w-full">
+            <Mermaid chart={codeContent} isCompact={isCompact} />
+          </div>
+        );
+      }
+
+      try {
+        return <CodeBlock code={codeContent} language={language} isUser={isUser} isCompact={isCompact} codeTheme={codeTheme} />;
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn('CodeBlock failed, using fallback:', error);
+        return <CodeBlockFallback code={codeContent} language={language} isUser={isUser} isCompact={isCompact} codeTheme={codeTheme} />;
+      }
+    },
+
+    code: ({ children, className }) => {
+      // Inside <pre>: let pre handle styling.
+      if (className?.includes('language-')) {
+        return <code className={className}>{children}</code>;
+      }
+      // Inline `<code>` uses the design system's `--code-inline`
+      // token. One semantic chip surface across both themes; on a
+      // user bubble we still palette-switch with `text-primary-
+      // foreground` because the inline chip blends INTO the bubble
+      // — there's no panel boundary like a fence has. We trade a
+      // perfect "code surface" tone here for legible body inheritance,
+      // matching ChatGPT's behaviour in coloured user bubbles.
+      const inlineCodeClass = isUser
+        ? 'bg-primary-foreground/15 text-primary-foreground'
+        : 'bg-code-inline text-code-inline-foreground';
+      return (
+        <code className={`px-1 py-0.5 rounded font-mono text-[0.875em] ${inlineCodeClass} break-all`}>
+          {extractTextFromChildren(children)}
+        </code>
+      );
+    },
+
+    // Modern chat convention drops italic on blockquotes — italic +
+    // tight bubble = hard to read. Border-left at 2px (4px reads
+    // heavy in a 320–480px bubble). On the saturated user bubble we
+    // use a primary-foreground tint; on the assistant bubble we use
+    // the muted-foreground role for de-emphasis.
+    blockquote: ({ children }) => {
+      const cls = isUser
+        ? 'border-primary-foreground/40 text-primary-foreground/80'
+        : 'border-border text-muted-foreground';
+      return (
+        <blockquote className={`${textSize} border-l-2 pl-3 my-3 break-words ${cls}`}>
+          {children}
+        </blockquote>
+      );
+    },
+
+    // Tables: outer wrapper handles overflow, inner `<table>`
+    // inherits the chat-density text size. Borders / header use
+    // semantic tokens — `border-code-border` for the assistant
+    // (matches the code-fence panel for visual cohesion when both
+    // appear in the same reply); primary-foreground/N for the user
+    // bubble so lines read against the saturated `bg-primary`.
+    table: ({ children }) => (
+      <div className="overflow-x-auto my-3">
+        <table className={`min-w-full ${textSize} border-collapse`}>{children}</table>
+      </div>
+    ),
+    thead: ({ children }) => (
+      <thead className={isUser ? 'bg-primary-foreground/10' : 'bg-muted/40'}>
+        {children}
+      </thead>
+    ),
+    tbody: ({ children }) => <tbody>{children}</tbody>,
+    tr: ({ children }) => (
+      <tr className={isUser ? 'border-b border-primary-foreground/15' : 'border-b border-border'}>
+        {children}
+      </tr>
+    ),
+    th: ({ children }) => {
+      const borderCls = isUser ? 'border-primary-foreground/25' : 'border-border';
+      return (
+        <th className={`px-2 py-1.5 text-left font-semibold border-b ${borderCls} break-words`}>
+          {children}
+        </th>
+      );
+    },
+    td: ({ children }) => <td className="px-2 py-1.5 break-words">{children}</td>,
+
+    // Soft separator. ChatGPT / Slack / Linear strip the visible
+    // line, Claude.ai keeps a hairline. We follow Claude — present
+    // but quiet. Palette switches by role so the hairline reads on
+    // both surfaces.
+    hr: () => (
+      <hr
+        className={`my-4 border-0 h-px ${
+          isUser ? 'bg-primary-foreground/20' : 'bg-border'
+        }`}
+      />
+    ),
+
+    strong: ({ children }) => <strong className="font-semibold">{children}</strong>,
+    em: ({ children }) => <em className="italic">{children}</em>,
+  };
+}

package/src/markdown-message/index.ts

@@ -0,0 +1,22 @@
+/**
+ * MarkdownMessage — chat-tuned markdown renderer.
+ *
+ * Public API:
+ *   - `MarkdownMessage` (default + named) — the React component.
+ *   - `MarkdownMessageProps` — its full prop shape.
+ *   - `LinkRule` — the declarative link-handling primitive.
+ *   - `extractTextFromChildren` — utility for callers that build their
+ *     own custom `a` renderers and need a string label.
+ *   - `urlChipRule` — opt-in built-in `LinkRule` that renders a bare
+ *     web URL as a compact `<UrlChip>` (favicon + middle-ellipsis).
+ *   - `ActionRow` — dumb action row (copy button), takes `visible`
+ *     from its owner.
+ *   - `ChatMessageRow` — opinionated bubble + action-row wrapper
+ *     with state-driven hover, close-delay and touch handling.
+ */
+export { MarkdownMessage, default } from './MarkdownMessage';
+export type { MarkdownMessageProps, LinkRule } from './types';
+export { extractTextFromChildren } from './plainText';
+export { urlChipRule } from './builtinRules';
+export { ActionRow } from './ActionRow';
+export { ChatMessageRow } from './ChatMessageRow';

package/src/markdown-message/linkRules.ts

@@ -0,0 +1,83 @@
+import React from 'react';
+import type { ComponentProps, ComponentType } from 'react';
+import type { Components } from 'react-markdown';
+import type { LinkRule } from './types';
+
+// react-markdown's `Components['a']` is `keyof IntrinsicElements | ComponentType<…>`,
+// so it isn't necessarily a function we can directly call. This is the
+// component-shaped variant — what callers practically pass when they
+// override `a`.
+type AComponent = ComponentType<ComponentProps<'a'>>;
+
+/** Run every rule's `preprocess` hook in order. Errors in a single
+ *  rule are logged and skipped — the other rules still run. */
+export function applyPreprocess(
+  source: string,
+  rules: readonly LinkRule[] | undefined,
+): string {
+  if (!rules || rules.length === 0) return source;
+  let s = source;
+  for (const rule of rules) {
+    if (!rule.preprocess) continue;
+    try {
+      s = rule.preprocess(s);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[MarkdownMessage] linkRule "${rule.name ?? '(anonymous)'}" preprocess threw; skipping`,
+        err,
+      );
+    }
+  }
+  return s;
+}
+
+/** Union of `extraHrefProtocols` and any `protocols` declared by rules. */
+export function collectProtocols(
+  extraHrefProtocols: readonly string[] | undefined,
+  rules: readonly LinkRule[] | undefined,
+): readonly string[] | undefined {
+  const set = new Set<string>();
+  if (extraHrefProtocols) for (const p of extraHrefProtocols) set.add(p);
+  if (rules) {
+    for (const r of rules) {
+      if (r.protocols) for (const p of r.protocols) set.add(p);
+    }
+  }
+  return set.size === 0 ? undefined : Array.from(set);
+}
+
+/** Build a custom `a` renderer that dispatches to the first matching
+ *  rule, falling through to `callerA` (or the built-in chat anchor)
+ *  for anything no rule claims. */
+export function buildLinkRulesComponent(
+  rules: readonly LinkRule[],
+  isUser: boolean,
+  callerA: NonNullable<Components['a']> | undefined,
+): NonNullable<Components['a']> {
+  const Renderer: AComponent = (props) => {
+    const { href, children } = props;
+    if (typeof href === 'string') {
+      for (const rule of rules) {
+        if (rule.match(href)) {
+          return React.createElement(
+            React.Fragment,
+            null,
+            rule.render({ href, children, isUser }),
+          );
+        }
+      }
+    }
+    // Defer to the caller's `a` override if any. We only call it when
+    // it's a function/component — string-form intrinsic overrides
+    // (`'a' | 'span' | …`) aren't a thing react-markdown supports for
+    // tag overrides, but the type still admits the union, so guard.
+    if (callerA && typeof callerA === 'function') {
+      const Caller = callerA as AComponent;
+      return React.createElement(Caller, props);
+    }
+    // Fall through to the built-in anchor by rendering a plain `<a>`.
+    return React.createElement('a', props, children);
+  };
+  return Renderer as NonNullable<Components['a']>;
+}

package/src/markdown-message/plainText.ts

@@ -0,0 +1,83 @@
+import React from 'react';
+
+/** Recursively concatenate the text content of a React.ReactNode tree.
+ *  Used by the markdown renderers (e.g. `<pre>` extracting code) and
+ *  by consumers that need a plain-string label out of link children. */
+export function extractTextFromChildren(children: React.ReactNode): string {
+  if (typeof children === 'string') return children;
+  if (typeof children === 'number') return String(children);
+  if (React.isValidElement(children)) {
+    const props = children.props as { children?: React.ReactNode };
+    return extractTextFromChildren(props.children);
+  }
+  if (Array.isArray(children)) {
+    return children.map(extractTextFromChildren).join('');
+  }
+  return '';
+}
+
+/**
+ * Auto-detect whether `text` should bypass ReactMarkdown and render as
+ * a flat `<div whitespace-pre-wrap>`. Used as the *fallback* when the
+ * caller doesn't pass `plainText` explicitly to `MarkdownMessage`.
+ *
+ * The signal we trust: short, single-paragraph, no markdown markers.
+ * Anything longer / multi-paragraph / structurally suggestive falls
+ * through to the markdown pipeline — false negatives there are cheap
+ * (markdown renders prose correctly), false positives in the prose
+ * branch surface as escaped `*` / `#` / etc. so we err markdown-ward.
+ *
+ * Thresholds were picked from chat-bubble UX research (see ChatGPT,
+ * Claude.ai, WhatsApp): roughly "would a person have written this in
+ * one keystroke without thinking about formatting?". If you find them
+ * too tight or too loose, tune here — every consumer goes through
+ * `MarkdownMessage` so the change is universal.
+ */
+export function looksLikePlainProse(text: string): boolean {
+  const trimmed = text.trim();
+  // Empty / whitespace-only — render as plain (cheap path, nothing to parse).
+  if (trimmed.length === 0) return true;
+  // Long enough that it's likely a structured assistant reply.
+  if (trimmed.length > 500) return false;
+  // Paragraph break → almost certainly markdown territory.
+  if (/\n\s*\n/.test(trimmed)) return false;
+  // Many single-line breaks → probably a list or stanza.
+  const newlineCount = (trimmed.match(/\n/g) || []).length;
+  if (newlineCount > 4) return false;
+  // Any markdown marker → defer to ReactMarkdown.
+  if (hasMarkdownSyntax(trimmed)) return false;
+  return true;
+}
+
+/** Affordance test: does this string look like markdown? Used to skip
+ *  the (heavier) ReactMarkdown pipeline when the content is pure
+ *  prose. NOT a validator — false negatives are fine; false positives
+ *  cost a render but render correctly. */
+export function hasMarkdownSyntax(text: string): boolean {
+  // Newlines after trim → render as markdown so paragraphs work.
+  if (text.trim().includes('\n')) return true;
+
+  // Inline HTML tags (`<br>`, `<b>`, `<code>`, …) — common in OpenAPI
+  // descriptions. Without this branch the fast path would escape them
+  // and the user sees literal angle brackets.
+  if (/<\/?[a-zA-Z][a-zA-Z0-9-]*(\s[^>]*)?\/?>/.test(text)) return true;
+
+  const patterns = [
+    /^#{1,6}\s/m,           // Headers
+    /\*\*[^*]+\*\*/,        // Bold
+    /\*[^*]+\*/,            // Italic
+    /__[^_]+__/,            // Bold (underscore)
+    /_[^_]+_/,              // Italic (underscore)
+    /\[.+\]\(.+\)/,         // Links
+    /!\[.*\]\(.+\)/,        // Images
+    /```[\s\S]*```/,        // Code blocks
+    /`[^`]+`/,              // Inline code
+    /^\s*[-*+]\s/m,         // Unordered lists
+    /^\s*\d+\.\s/m,         // Ordered lists
+    /^\s*>/m,               // Blockquotes
+    /\|.+\|/,               // Tables
+    /^---+$/m,              // Horizontal rules
+    /~~[^~]+~~/,            // Strikethrough
+  ];
+  return patterns.some((p) => p.test(text));
+}

package/src/markdown-message/sanitize.ts

@@ -0,0 +1,88 @@
+import { defaultSchema } from 'rehype-sanitize';
+
+/** Sanitize schema. Typed loosely (`Record<string, unknown>`) so this
+ *  package's published types don't try to re-export
+ *  `hast-util-sanitize`'s internal Schema type — that breaks consumers
+ *  whose TS doesn't have the transitive dependency in scope. */
+export type SanitizeSchema = Record<string, unknown>;
+
+// Allow-list HTML that OpenAPI descriptions commonly use — we want
+// `<b>`/`<code>`/`<br>` to render, not to appear as literal text.
+// Built on top of rehype-sanitize's default schema so we keep the
+// XSS protection (no `<script>`, no `on*` handlers, no `javascript:`
+// URLs); we just extend the tag allow-list with safe presentational
+// elements that are in wide use in API docs.
+export const HTML_SCHEMA_BASE: SanitizeSchema = {
+  ...defaultSchema,
+  tagNames: [
+    ...(defaultSchema.tagNames ?? []),
+    'br',
+    'b',
+    'i',
+    'u',
+    's',
+    'sub',
+    'sup',
+    'small',
+    'mark',
+    'kbd',
+    'code',
+    'pre',
+    'details',
+    'summary',
+  ],
+};
+
+/** Build a sanitize schema with extra href-URL protocols allowed on
+ *  `<a>`. Default whitelists `http(s)/mailto/xmpp/irc(s)` — pass extras
+ *  here (e.g. `'cmdop'`, `'obsidian'`) to opt them in. */
+export function buildSchema(extraProtocols: readonly string[] | undefined): SanitizeSchema {
+  if (!extraProtocols || extraProtocols.length === 0) return HTML_SCHEMA_BASE;
+  const baseProtocols =
+    (HTML_SCHEMA_BASE as { protocols?: Record<string, string[]> }).protocols
+    ?? (defaultSchema as { protocols?: Record<string, string[]> }).protocols
+    ?? {};
+  const baseHref = baseProtocols.href ?? ['http', 'https', 'mailto', 'xmpp', 'irc', 'ircs'];
+  return {
+    ...HTML_SCHEMA_BASE,
+    protocols: {
+      ...baseProtocols,
+      href: [...baseHref, ...extraProtocols],
+    },
+  };
+}
+
+/** Build a `urlTransform` for ReactMarkdown that lets opted-in schemes
+ *  pass through verbatim. react-markdown's default strips `href` for
+ *  unrecognised schemes BEFORE sanitize runs — even with our extended
+ *  sanitize schema, custom schemes would arrive with `href=""`. */
+export function buildUrlTransform(extraProtocols: readonly string[] | undefined) {
+  if (!extraProtocols || extraProtocols.length === 0) return undefined;
+  const lower = extraProtocols.map((p) => p.toLowerCase() + ':');
+  return (url: string): string => {
+    const u = url.trim().toLowerCase();
+    for (const p of lower) {
+      if (u.startsWith(p)) return url;
+    }
+    // Fallback: replicate react-markdown's defaults for safe schemes
+    // and relative paths. Anything else → empty string so the
+    // anchor's href is dropped (XSS guard).
+    //
+    // The bare-name branch must NOT contain `:`. It exists for a relative
+    // target like `intro.md`, and with a colon in the class the whole of
+    // `javascript:alert(1)` matched it — the guard returned the payload
+    // verbatim, which is the one thing this function exists to prevent.
+    // (rehype-sanitize's `protocols.href` allow-list caught it downstream, so
+    // nothing shipped exploitable; a layer of defence-in-depth that does not
+    // defend is still broken.) A scheme is what a colon before the first
+    // `/`, `?` or `#` means, so excluding it here leaves relative paths
+    // intact and rejects every scheme not named above.
+    if (
+      /^(https?:|mailto:|tel:|xmpp:|irc:|ircs:|#|\/|\.\/|\.\.\/|\?)/i.test(u)
+      || /^[a-z0-9._~!$&'()*+,;=@%-]+$/i.test(u)
+    ) {
+      return url;
+    }
+    return '';
+  };
+}

package/src/markdown-message/streamingBlocks.ts

@@ -0,0 +1,168 @@
+/**
+ * Streaming-markdown block splitter + boundary buffering.
+ *
+ * Purpose: render markdown LIVE during streaming without (a) re-parsing
+ * the whole document on every token (O(n²)) and (b) flashing raw syntax
+ * for half-written constructs. Approach (per plan105 §3.1 + §3.3):
+ *
+ *   1. Block-split: split accumulating markdown into top-level blocks at
+ *      blank-line boundaries, RESPECTING fenced code blocks (a blank line
+ *      inside ``` does NOT end the block). Each completed block has stable
+ *      `raw` source, so the consumer can memoize blocks 0..N-1 and only
+ *      re-parse the tail → ~O(n).
+ *   2. Boundary buffering: the trailing block — the one still receiving
+ *      tokens — is held back as RAW plain text until it reaches a safe
+ *      boundary (a trailing newline). This kills the "flash of incomplete
+ *      `**bold` / `[link](`" without any fragile syntax repair.
+ *   3. Fence awareness: if the stream ends INSIDE an unclosed ``` fence,
+ *      the tail is rendered as an in-progress code block (we virtually
+ *      close the fence for that render only) instead of as broken markdown
+ *      bleeding into the rest of the message.
+ *
+ * No `marked` / lexer dependency — a blank-line splitter that tracks fence
+ * state is sufficient for the safe-80% path and adds zero deps. The actual
+ * per-block rendering still goes through the full ReactMarkdown pipeline.
+ *
+ * This module is pure (no React) so it is trivially testable.
+ */
+
+/** A fenced-code-block opener: ``` or ~~~, optionally indented up to 3
+ *  spaces, with an optional info string. Per CommonMark the closing fence
+ *  must use the same char and be at least as long; we keep it simple and
+ *  match the char + length, which covers real LLM output. */
+const FENCE_RE = /^( {0,3})(`{3,}|~{3,})(.*)$/;
+
+interface FenceState {
+  open: boolean;
+  /** The exact fence marker that opened the current block (e.g. "```"). */
+  marker: string;
+}
+
+/** Does `line` open/close a fence given the current state? Returns the
+ *  next fence state. A line that closes uses the same char, >= length, and
+ *  no trailing info string. */
+function stepFence(line: string, state: FenceState): FenceState {
+  const m = FENCE_RE.exec(line);
+  if (!m) return state;
+  // Groups 2 and 3 are non-optional in FENCE_RE, so a match always fills them.
+  const marker = m[2] ?? '';
+  const info = (m[3] ?? '').trim();
+  if (!state.open) {
+    // Any fence line opens a block (info string allowed on open).
+    return { open: true, marker };
+  }
+  // Inside a fence: a bare fence of the same char and >= length closes it.
+  // Group 2 matches 3+ chars, so both markers are non-empty here; the `[0]`
+  // reads compare `undefined` only for a state that can't occur.
+  const sameChar = marker[0] === state.marker[0];
+  const longEnough = marker.length >= state.marker.length;
+  if (sameChar && longEnough && info === '') {
+    return { open: false, marker: '' };
+  }
+  return state;
+}
+
+export interface SplitResult {
+  /** Completed, stable top-level blocks (safe to memoize + parse). */
+  blocks: string[];
+  /** The trailing in-flight block, or '' if the content ended on a
+   *  clean boundary. Held back from `blocks` so it can be rendered raw
+   *  (boundary buffering) until it completes. */
+  tail: string;
+  /** True when `tail` is the body of an unterminated fenced code block —
+   *  the consumer should render it as an in-progress code block rather
+   *  than raw prose. */
+  tailInOpenFence: boolean;
+}
+
+/**
+ * Split `content` into stable blocks + a trailing in-flight block.
+ *
+ * Boundary rule: a block is "complete" once a blank line follows it AND
+ * we are not inside an open fence. The text after the last such boundary
+ * is the `tail`. If the whole content ends with a newline and no fence is
+ * open, the tail is empty (everything promoted to stable blocks).
+ *
+ * @param content raw accumulated markdown (never mutated)
+ */
+export function splitStreamingBlocks(content: string): SplitResult {
+  if (content.length === 0) {
+    return { blocks: [], tail: '', tailInOpenFence: false };
+  }
+
+  const lines = content.split('\n');
+  const blocks: string[] = [];
+  let current: string[] = [];
+  let fence: FenceState = { open: false, marker: '' };
+
+  // Track fence state at the START of the current accumulating block so we
+  // know, at the end, whether the tail is inside an open fence.
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    const wasOpen = fence.open;
+    fence = stepFence(line, fence);
+
+    const isBlank = line.trim() === '';
+    // A blank line outside any fence is a block boundary. We only cut when
+    // we have accumulated something — leading/again-blank lines collapse.
+    if (isBlank && !fence.open && !wasOpen) {
+      if (current.length > 0) {
+        blocks.push(current.join('\n'));
+        current = [];
+      }
+      // Drop the blank separator itself.
+      continue;
+    }
+    current.push(line);
+  }
+
+  // Whatever remains is the in-flight tail. If the original content ended
+  // with a trailing newline AND we're on a clean boundary (no open fence),
+  // the tail is genuinely complete prose — but we still keep it as `tail`
+  // unless it was already closed by a blank line above. To maximize stable
+  // blocks, promote the tail to a completed block when it ends on a clean
+  // newline boundary and no fence is open.
+  let tail = current.join('\n');
+  let tailInOpenFence = fence.open;
+
+  if (!tailInOpenFence && tail.length > 0 && content.endsWith('\n')) {
+    // Content ended on a newline and the tail isn't inside a fence — treat
+    // it as a finished block so it parses (and memoizes) immediately.
+    blocks.push(tail);
+    tail = '';
+  }
+
+  return { blocks, tail, tailInOpenFence };
+}
+
+/**
+ * Prepare the in-flight tail for rendering.
+ *
+ * - If the tail is inside an open fence, virtually close it so it renders
+ *   as an in-progress code block (not raw text bleeding downward). The
+ *   close is appended to a COPY — stored content is never mutated.
+ * - Otherwise return the tail untouched; the consumer renders it as plain
+ *   `whitespace-pre-wrap` text (boundary buffering — no syntax repair).
+ *
+ * NOTE: we deliberately do NOT auto-close dangling `**` / `[` / inline
+ * backticks here (plan105 §3.2, deferred / flag-gated). The only fence we
+ * close is the block code fence, because an unclosed block fence would
+ * otherwise swallow the rest of the message and the close is unambiguous.
+ */
+export function renderableTail(
+  tail: string,
+  tailInOpenFence: boolean,
+): { source: string; asCode: boolean } {
+  if (!tailInOpenFence) return { source: tail, asCode: false };
+  // Re-derive the opening fence marker so we close with a matching one.
+  const firstLine = tail.split('\n', 1)[0] ?? '';
+  const m = FENCE_RE.exec(firstLine);
+  const marker = m?.[2] ?? '```';
+  // Ensure the close sits on its own line.
+  const needsNewline = !tail.endsWith('\n');
+  return {
+    source: `${tail}${needsNewline ? '\n' : ''}${marker}`,
+    asCode: true,
+  };
+}