dsh-better-display 0.1.1

package/src/client/markdown/MarkdownText.tsx

@@ -0,0 +1,187 @@
+// Adapted from DeepSeek Harness b150a551b8d465e31e418e1b2eaf5e79bbb7d28e (MIT). See THIRD_PARTY_NOTICES.md.
+/**
+ * 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 { memo, useMemo, useRef } from 'react'
+import type { ReactNode } from 'react'
+import { IncrementalMarkdownParser } from './incremental.js'
+import { parseGfm, parseGfmWithMath } from './parse.js'
+import {
+  collectReferenceTargets, createReferenceTargets, renderBlocks, renderFootnoteSection,
+  wrapBlockChildren,
+} from './render.js'
+import type { MarkdownCodeLabels, MarkdownFileMentions, MarkdownRenderContext, ReferenceTargets } from './render.js'
+// KaTeX CSS is supplied once by the shared DSH UI-primitives client bundle.
+import css from './MarkdownText.module.css'
+
+export type { MarkdownCodeLabels, MarkdownFileMentions } from './render.js'
+
+/** One settled full render: parse with math, resolve references, append the footnote section. */
+function renderSettled(
+  text: string,
+  codeLabels: MarkdownCodeLabels | undefined,
+  fileMentions: MarkdownFileMentions | undefined,
+  renderText: MarkdownRenderContext['renderText'],
+  renderAtom: MarkdownRenderContext['renderAtom'],
+): ReactNode[] {
+  const root = parseGfmWithMath(text)
+  const targets = createReferenceTargets()
+  collectReferenceTargets(root.children, targets)
+  const context: MarkdownRenderContext = {
+    renderText,
+    renderAtom,
+    streaming: false,
+    codeLabels,
+    fileMentions,
+    targets,
+    footnoteOrder: [],
+    footnoteCounts: new Map(),
+  }
+  const blocks = wrapBlockChildren(
+    renderBlocks(root.children.map((node, index) => ({ node, key: node.position?.start.offset ?? -(index + 1) })), context),
+    false,
+  )
+  const section = renderFootnoteSection(context)
+  return section === null ? blocks : [...blocks, '\n', section]
+}
+
+/**
+ * Streaming render state for one growing message: the incremental parser,
+ * the frozen blocks' cached elements, and the reference/footnote state their
+ * rendering consumed (footnote numbering assigned to frozen references is
+ * final, so the tail continues from a copy of it each frame).
+ */
+class StreamingRenderer {
+  private readonly parser = new IncrementalMarkdownParser(parseGfm)
+  private generation = -1
+  private frozenCount = 0
+  private frozenElements: ReactNode[] = []
+  private frozenTargets: ReferenceTargets = createReferenceTargets()
+  private frozenFootnoteOrder: string[] = []
+  private frozenFootnoteCounts = new Map<string, number>()
+  private lastText: string | null = null
+  private lastRendered: ReactNode[] = []
+
+  /** @param codeLabels - Fence copy labels baked into cached elements; the owner replaces the renderer when they change. */
+  constructor(private readonly codeLabels: MarkdownCodeLabels | undefined, private readonly renderText: MarkdownRenderContext['renderText'], private readonly renderAtom: MarkdownRenderContext['renderAtom']) {}
+
+  /**
+   * Render the current accumulated text. Idempotent per text value, so React
+   * may re-execute the calling render freely.
+   * @param text - The full accumulated markdown source.
+   * @returns Frozen elements, re-rendered tail, and the footnote section.
+   */
+  render(text: string): ReactNode[] {
+    if (text === this.lastText) return this.lastRendered
+    const { frozen, tail, generation } = this.parser.update(text)
+    if (generation !== this.generation) {
+      this.generation = generation
+      this.frozenCount = 0
+      this.frozenElements = []
+      this.frozenTargets = createReferenceTargets()
+      this.frozenFootnoteOrder = []
+      this.frozenFootnoteCounts = new Map()
+    }
+    const newlyFrozen = frozen.slice(this.frozenCount)
+    collectReferenceTargets(newlyFrozen.map(block => block.node), this.frozenTargets)
+    // Targets visible this frame: everything frozen so far plus the current
+    // tail parse — a newly frozen block's references resolved against the
+    // same parse tree its definitions came from.
+    const frameTargets: ReferenceTargets = {
+      definitions: new Map(this.frozenTargets.definitions),
+      footnotes: new Map(this.frozenTargets.footnotes),
+    }
+    collectReferenceTargets(tail.map(block => block.node), frameTargets)
+    if (newlyFrozen.length > 0) {
+      const frozenContext: MarkdownRenderContext = {
+        renderText: this.renderText,
+        renderAtom: this.renderAtom,
+        streaming: true,
+        codeLabels: this.codeLabels,
+        fileMentions: undefined,
+        targets: frameTargets,
+        footnoteOrder: this.frozenFootnoteOrder,
+        footnoteCounts: this.frozenFootnoteCounts,
+      }
+      // Separator newlines are cached alongside the elements so the
+      // assembled children match the settled pipeline's block wrapping.
+      const batch = [...this.frozenElements]
+      for (const element of renderBlocks(newlyFrozen, frozenContext)) {
+        if (batch.length > 0) batch.push('\n')
+        batch.push(element)
+      }
+      this.frozenElements = batch
+      this.frozenCount = frozen.length
+    }
+    const tailContext: MarkdownRenderContext = {
+      renderText: this.renderText,
+      renderAtom: this.renderAtom,
+      streaming: true,
+      codeLabels: this.codeLabels,
+      fileMentions: undefined,
+      targets: frameTargets,
+      footnoteOrder: [...this.frozenFootnoteOrder],
+      footnoteCounts: new Map(this.frozenFootnoteCounts),
+    }
+    const children = [...this.frozenElements]
+    for (const element of renderBlocks(tail, tailContext)) {
+      if (children.length > 0) children.push('\n')
+      children.push(element)
+    }
+    const section = renderFootnoteSection(tailContext)
+    if (section !== null) children.push('\n', section)
+    this.lastText = text
+    this.lastRendered = children
+    return this.lastRendered
+  }
+}
+
+/**
+ * Render untrusted assistant-authored Markdown as semantic React elements.
+ * @param props - Markdown source text preserved by the session projection;
+ * `streaming` renders fences and TeX plain (highlighting and KaTeX land on
+ * the finalize swap) and parses incrementally across chunks; `codeLabels`
+ * forwards localized copy-button labels to fence CodeBlocks — 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; this is
+ * the single streaming gate — it applies 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.
+ * @returns A GFM document with TeX math rendered through KaTeX; raw HTML,
+ * relative links, and unsafe protocols are disabled, while absolute HTTP(S)
+ * images render directly.
+ */
+export const MarkdownText = memo(function MarkdownText({ text, streaming = false, codeLabels, fileMentions, renderText, renderAtom }: {
+  text: string
+  streaming?: boolean
+  codeLabels?: MarkdownCodeLabels | undefined
+  fileMentions?: MarkdownFileMentions | undefined
+  renderText?: MarkdownRenderContext['renderText']
+  renderAtom?: MarkdownRenderContext['renderAtom']
+}) {
+  const streamRef = useRef<StreamingRenderer | null>(null)
+  const streamLabelsRef = useRef<MarkdownCodeLabels | undefined>(codeLabels)
+  const children = useMemo(() => {
+    if (!streaming) {
+      streamRef.current = null
+      return renderSettled(text, codeLabels, fileMentions, renderText, renderAtom)
+    }
+    if (streamRef.current === null || streamLabelsRef.current !== codeLabels) {
+      streamRef.current = new StreamingRenderer(codeLabels, renderText, renderAtom)
+      streamLabelsRef.current = codeLabels
+    }
+    return streamRef.current.render(text)
+  }, [text, streaming, codeLabels, fileMentions, renderText, renderAtom])
+  return <div className={css.markdown}>{children}</div>
+})

package/src/client/markdown/cjkFriendlyStrong.ts

@@ -0,0 +1,84 @@
+// Adapted from DeepSeek Harness b150a551b8d465e31e418e1b2eaf5e79bbb7d28e (MIT). See THIRD_PARTY_NOTICES.md.
+/** Let asterisk strong emphasis close after punctuation when CJK prose continues without whitespace. */
+
+import { attention } from 'micromark-core-commonmark'
+import { unicodePunctuation } from 'micromark-util-character'
+import { classifyCharacter } from 'micromark-util-classify-character'
+import { codes, constants } from 'micromark-util-symbol'
+import type { Construct, Extension, State, Tokenizer } from 'micromark-util-types'
+
+const cjkCharacter = new RegExp([
+  '\\p{Script_Extensions=Han}',
+  '\\p{Script_Extensions=Hiragana}',
+  '\\p{Script_Extensions=Katakana}',
+  '\\p{Script_Extensions=Hangul}',
+  '\\p{Script_Extensions=Bopomofo}',
+].join('|'), 'u')
+
+function isCjkCharacter(code: number | null): boolean {
+  return code !== null && code >= 0 && cjkCharacter.test(String.fromCodePoint(code))
+}
+
+const tokenizeCjkFriendlyAttention: Tokenizer = function (effects, ok, nok) {
+  const configuredAttentionMarkers = this.parser.constructs.attentionMarkers.null
+  if (configuredAttentionMarkers === undefined) {
+    throw new Error('micromark CommonMark attention markers are unavailable')
+  }
+  const attentionMarkers = configuredAttentionMarkers
+  const previous = this.previous
+  const before = classifyCharacter(previous)
+  let marker: number | null = codes.eof
+
+  return start
+
+  function start(code: number | null): State | undefined {
+    /* v8 ignore next -- this text construct is dispatched only for an asterisk. */
+    if (code !== codes.asterisk) return nok(code)
+    marker = code
+    effects.enter('attentionSequence')
+    return inside(code)
+  }
+
+  function inside(code: number | null): State | undefined {
+    if (code === marker) {
+      effects.consume(code)
+      return inside
+    }
+
+    const token = effects.exit('attentionSequence')
+    const after = classifyCharacter(code)
+    const open = !after || (after === constants.characterGroupPunctuation && Boolean(before))
+      || attentionMarkers.includes(code)
+    const commonMarkClose = !before
+      || (before === constants.characterGroupPunctuation && Boolean(after))
+      || attentionMarkers.includes(previous)
+    const markerCount = token.end.offset - token.start.offset
+    const cjkStrongClose = markerCount >= 2
+      && unicodePunctuation(previous)
+      && isCjkCharacter(code)
+    const close = commonMarkClose || cjkStrongClose
+
+    token._open = open
+    token._close = close
+    return ok(code)
+  }
+}
+
+const cjkFriendlyAttention: Construct = {
+  name: 'cjkFriendlyAttention',
+  resolveAll: attention.resolveAll,
+  tokenize: tokenizeCjkFriendlyAttention,
+}
+
+const cjkFriendlyStrongExtension: Extension = {
+  text: { [codes.asterisk]: cjkFriendlyAttention },
+}
+
+/**
+ * Extend CommonMark asterisk strong emphasis for punctuation-delimited CJK
+ * prose, as a micromark syntax extension for `fromMarkdown`.
+ * @returns The micromark syntax extension.
+ */
+export function cjkFriendlyStrong(): Extension {
+  return cjkFriendlyStrongExtension
+}

package/src/client/markdown/incremental.ts

@@ -0,0 +1,131 @@
+// Adapted from DeepSeek Harness b150a551b8d465e31e418e1b2eaf5e79bbb7d28e (MIT). See THIRD_PARTY_NOTICES.md.
+/**
+ * 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, a list continuing
+ * after a blank line, an unclosed fence swallowing lines) — 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: each source region is parsed O(1) times over the stream
+ * instead of once per chunk.
+ *
+ * The freeze boundary comes from the parser's own `position` offsets, never
+ * from custom source scanning. 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.
+ *
+ * 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'
+
+/**
+ * Trailing blocks kept unstable. Appended text reshapes at most the last
+ * block; the second-to-last is retained as safety margin so a freeze decision
+ * never has to reason about the parse frontier.
+ */
+const UNSTABLE_TAIL_BLOCKS = 2
+
+/** 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
+}
+
+/**
+ * A block's render key: its absolute source start offset. A position-less
+ * node (a grammar is free to omit positions) falls back to a negative
+ * list-index key — unique within one update's tail, which is the only place
+ * the fallback can occur: freezing requires the cut block's position, so a
+ * position-less parse keeps every block in the tail (real grammars always
+ * stamp positions and never take this path).
+ */
+function blockKey(node: RootContent, base: number, index: number): number {
+  const offset = node.position?.start.offset
+  return offset === undefined ? -(index + 1) : base + offset
+}
+
+/**
+ * Append-only incremental parser over a caller-supplied grammar. One instance
+ * accumulates one streaming document; non-append input resets it.
+ */
+export class IncrementalMarkdownParser {
+  private prevText = ''
+  private tailStart = 0
+  private frozen: PositionedBlock[] = []
+  private generation = 0
+  private cached: IncrementalBlocks | null = null
+
+  /** @param parse - Grammar shared with whatever renders the blocks, so boundaries agree. */
+  constructor(private readonly parse: (text: string) => Root) {}
+
+  /**
+   * 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 {
+    if (this.cached !== null && text === this.prevText) return this.cached
+    // Deliberate O(prefix) memcmp per update: sound divergence detection has
+    // to verify the whole retained prefix, and startsWith compares bytes two
+    // orders of magnitude faster than parsing them — the cost this class
+    // exists to remove. Passing append/reset deltas instead would push
+    // append bookkeeping across the session-projection update boundary for a check
+    // that stays sub-millisecond at realistic reply sizes.
+    if (!text.startsWith(this.prevText)) {
+      this.prevText = ''
+      this.tailStart = 0
+      this.frozen = []
+      this.generation += 1
+    }
+    this.prevText = text
+    const base = this.tailStart
+    const blocks = this.parse(text.slice(base)).children
+    let firstUnstable = Math.max(0, blocks.length - UNSTABLE_TAIL_BLOCKS)
+    if (firstUnstable > 0) {
+      const cutEnd = blocks[firstUnstable - 1]?.position?.end.offset
+      if (cutEnd === undefined) {
+        // A grammar that omits positions leaves nothing to cut at; keep the
+        // whole parse in the tail rather than guessing a boundary.
+        firstUnstable = 0
+      } else {
+        for (const node of blocks.slice(0, firstUnstable)) {
+          this.frozen.push({ node, key: blockKey(node, base, this.frozen.length) })
+        }
+        this.tailStart = base + cutEnd
+      }
+    }
+    const tail = blocks.slice(firstUnstable).map((node, index) => ({
+      node,
+      key: blockKey(node, base, index),
+    }))
+    this.cached = { frozen: [...this.frozen], tail, generation: this.generation }
+    return this.cached
+  }
+}

package/src/client/markdown/katex.tsx

@@ -0,0 +1,91 @@
+// Adapted from DeepSeek Harness b150a551b8d465e31e418e1b2eaf5e79bbb7d28e (MIT). See THIRD_PARTY_NOTICES.md.
+/**
+ * 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 { createElement } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import katex from 'katex'
+
+/**
+ * Convert one inline `style` attribute string into React's style object.
+ * KaTeX emits only plain kebab-case declarations (no custom properties and no
+ * nameless declarations), so camel-casing the property is the whole mapping.
+ */
+function styleObject(css: string): CSSProperties {
+  const style: Record<string, string> = {}
+  for (const declaration of css.split(';')) {
+    const colon = declaration.indexOf(':')
+    if (colon === -1) continue
+    const name = declaration.slice(0, colon).trim()
+    const key = name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())
+    style[key] = declaration.slice(colon + 1).trim()
+  }
+  return style
+}
+
+/** Map one parsed DOM node onto a React element (text nodes pass through). */
+function domToReact(node: ChildNode, key: number): ReactNode {
+  if (node.nodeType === Node.TEXT_NODE) return node.textContent
+  /* v8 ignore next 2 -- KaTeX output holds only elements and text; other
+     node kinds cannot appear in its serialized vocabulary. */
+  if (node.nodeType !== Node.ELEMENT_NODE) return null
+  const element = node as Element
+  const props: Record<string, unknown> = { key }
+  for (const attribute of element.attributes) {
+    if (attribute.name === 'class') props['className'] = attribute.value
+    else if (attribute.name === 'style') props['style'] = styleObject(attribute.value)
+    else props[attribute.name] = attribute.value
+  }
+  const children = [...element.childNodes].map(domToReact)
+  return children.length === 0
+    ? createElement(element.localName, props)
+    : createElement(element.localName, props, ...children)
+}
+
+/**
+ * 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 function renderTexToReact(value: string, displayMode: boolean): ReactNode {
+  let html: string
+  try {
+    html = katex.renderToString(value, { displayMode, throwOnError: true })
+  } catch (error) {
+    try {
+      html = katex.renderToString(value, { displayMode, strict: 'ignore', throwOnError: false })
+    } catch {
+      // KaTeX renders ParseErrors itself under throwOnError: false; only its
+      // internal errors reach here, so mirror rehype-katex's manual span.
+      /* v8 ignore next 8 */
+      return (
+        <span
+          className="katex-error"
+          style={{ color: '#cc0000' }}
+          title={String(error)}
+        >
+          {value}
+        </span>
+      )
+    }
+  }
+  const parsed = new DOMParser().parseFromString(html, 'text/html')
+  return [...parsed.body.childNodes].map(domToReact)
+}