@changfenhuang/dsh-genui 0.9.1

package/src/client/index.tsx

@@ -0,0 +1,195 @@
+/**
+ * dsh-genui browser half: the ```dsh-ui fence renderer, the keyed toolview
+ * for the `render_ui` tool, and the session panel dock.
+ *
+ * Fence rendering is dual-mode, chosen at boot:
+ * - **Registry channel** (contract hosts): the host's MarkdownText resolves
+ *   ```dsh-ui fences through the fence-registry extension point; this package
+ *   registers `renderGenuiFence`. Action callbacks ride the host-installed
+ *   GenuiActionContext.
+ * - **DOM channel** (pristine hosts): no extension point exists, so
+ *   `dom-fence.ts` observes the conversation DOM, finds settled stock code
+ *   blocks labelled `dsh-ui`, and mounts the same render pipeline in its own
+ *   React roots — wrapped in the plugin-owned GenuiActionContext that relays
+ *   `[genui-action]` through the scoped conversation send. Either way the
+ *   deployment is the STOCK DSH snapshot plus this plugin.
+ *
+ * The renderer parses the fence body with the partial parser: while the reply
+ * streams, every FINISHED component appears the moment its JSON object
+ * closes, so the UI assembles top-down before the fence (or reply) completes.
+ * A body with no finished component yet falls back to a plain code block.
+ * @module @changfenhuang/dsh-genui/client
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
+import type { IConversation } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type { Key, ReactNode } from 'react'
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
+import { installDomFenceRenderer } from './dom-fence.tsx'
+import { renderGenuiFence, type GenuiFenceContext } from './fence-render.tsx'
+import { createPanelSlashSource } from './panel-command.ts'
+import { GenuiPanel, type GenuiPanelInjected } from './panel.tsx'
+import { GenuiToolView } from './toolview.tsx'
+import type { InputTriggerServiceContract } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
+import { assetUrl } from './asset-loader.ts'
+
+/** Host extension surface the registry channel needs (absent on pristine). */
+type HostFenceExt = {
+  registerFenceRenderer?: (lang: string, renderer: (raw: string, key: Key, context?: GenuiFenceContext) => ReactNode) => () => void
+}
+
+/** Add low-priority prefetch links for the lazy engine assets (mermaid/three).
+ * Browser-dependent: some engines ignore `<link rel=prefetch>`; harmless
+ * either way — the on-demand loader still covers a cache miss. Exported for
+ * tests. */
+export function prefetchGenuiAssets(): void {
+  if (typeof document === 'undefined') return
+  for (const file of ['mermaid.js', 'three.js']) {
+    if (document.head.querySelector(`link[rel="prefetch"][href="${assetUrl(file)}"]`) !== null) continue
+    const link = document.createElement('link')
+    link.rel = 'prefetch'
+    link.as = 'script'
+    link.href = assetUrl(file)
+    document.head.appendChild(link)
+  }
+}
+
+/** Session panel action loop: same [genui-action] contract as inline fences,
+ * routed through the scoped conversation send (queued user message). The
+ * prompt asks the model to re-run render_ui so the panel updates in place. */
+function panelActionSend(ctx: Context, sessionId: SessionId): GenuiPanelInjected {
+  const scoped = ctx.sessions.scope(sessionId)
+  const conversation = scoped?.get('conversation') as IConversation | undefined
+  return {
+    sessionId,
+    sendGenuiAction: (action, payload) => {
+      if (conversation === undefined) return
+      const payloadText = Object.keys(payload).length === 0
+        ? ''
+        : ` 组件数据: ${JSON.stringify(payload)}`
+      void conversation.send(`[genui-action] ${action}。用户刚刚在面板中触发了动作 "${action}"，请根据组件数据执行相应操作，只输出一个 panel:true 的 dsh-ui 围栏来更新面板，回复文本至多一行 10 字以内的确认（如"已刷新"），不要解释、不要普通围栏。${payloadText}`).catch((err: unknown) => {
+        // A failed prompt (session gone, agent busy) drops the action; the
+        // panel stays interactive — the component is not disabled. Log the
+        // failure WITHOUT the action payload or any secret values (the
+        // message may contain field content).
+        console.warn(`[genui] 面板动作 "${action}" 发送失败（session ${sessionId}）：`, err instanceof Error ? err.message : String(err))
+      })
+    },
+  }
+}
+
+/** Relay a `/panel <指令>` instruction to the model: the scoped conversation
+ * send with an explicit panel-only directive, so the model replaces the
+ * default panel with content tailored to the request. */
+function sendPanelInstruction(ctx: Context, sessionId: SessionId, instruction: string): void {
+  const scoped = ctx.sessions.scope(sessionId)
+  const conversation = scoped?.get('conversation') as IConversation | undefined
+  if (conversation === undefined) return
+  void conversation.send(`用户执行了 /panel 并请求：${instruction}。请只输出一个 panel:true 的 dsh-ui 围栏来更新会话面板，内容按请求定制；回复文本至多一行 10 字以内的确认（如"已更新"），不要解释、不要普通围栏。`).catch((err: unknown) => {
+    // A failed prompt drops the instruction; the default panel stays
+    // visible. Log without the instruction text (may contain secrets).
+    console.warn(`[genui] /panel 指令发送失败（session ${sessionId}）：`, err instanceof Error ? err.message : String(err))
+  })
+}
+
+/**
+ * Inline-fence action relay (DOM channel): the same message template the
+ * contract host's sendGenuiAction uses, so the model sees one identical
+ * [genui-action] contract on both channels.
+ */
+function sendInlineGenuiAction(ctx: Context, sessionId: SessionId, action: string, payload: Record<string, unknown>): void {
+  const scoped = ctx.sessions.scope(sessionId)
+  const conversation = scoped?.get('conversation') as IConversation | undefined
+  if (conversation === undefined) return
+  const payloadText = Object.keys(payload).length === 0
+    ? ''
+    : ` 组件数据: ${JSON.stringify(payload)}`
+  void conversation.send(`[genui-action] ${action}。用户刚刚在界面中触发了动作 "${action}"，请根据组件数据执行相应操作，并用 dsh-ui 输出更新后的界面。${payloadText}`).catch(() => {
+    // A failed prompt (session gone, agent busy) drops the action;
+    // the UI stays interactive — the component is not disabled.
+  })
+}
+
+/** Cordis client entry: register the fence renderer on boot, the keyed
+ * toolview for the render_ui tool, and the session panel dock; returning the
+ * disposers lets cordis tear all registrations down on plugin unload. */
+export function apply(ctx: Context): () => void {
+  // Fence channel selection: the registry extension point when the host
+  // ships it (contract line), the DOM observer otherwise (pristine line).
+  // One plugin build serves both deployments.
+  const registerFn = (primitives as unknown as HostFenceExt).registerFenceRenderer
+  const channel = typeof registerFn === 'function' ? 'registry' : 'dom'
+  console.info(`[genui] client active; fence-channel=${channel}`)
+  const disposers: Array<() => void> = typeof registerFn === 'function'
+    ? [registerFn('dsh-ui', renderGenuiFence)]
+    : [installDomFenceRenderer(ctx, (sessionId, action, payload) => sendInlineGenuiAction(ctx, sessionId, action, payload))]
+  // Idle prefetch of the lazy engine assets: the browser downloads them at
+  // LOW priority whenever the page is idle, so the first mermaid/3D node in
+  // a session usually hits a warm cache instead of paying the fetch on first
+  // use. Never blocks first paint; the loader still handles a miss.
+  prefetchGenuiAssets()
+  // Keyed toolview: the harness dispatches 'tool.call.toolview' by wire tool
+  // name; registering under 'render_ui' gives the tool's result card the
+  // GenUI renderer (reading the repaired spec from result meta). The toolview
+  // also publishes every settled spec to the session panel store.
+  disposers.push(ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
+    name: 'tool.call.toolview',
+    key: 'render_ui',
+  }, GenuiToolView)))
+  // Session panel dock: a session-scoped, always-present seat above the
+  // composer (TodoDock posture). Renders the session's latest render_ui
+  // spec in place; absent spec = no panel.
+  disposers.push(ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({
+    name: 'conversation.input.dock',
+    id: 'genui-panel',
+    order: 50,
+    inject: (sessionId: SessionId): GenuiPanelInjected => panelActionSend(ctx, sessionId),
+  }, GenuiPanel)))
+  // /panel slash command: a deterministic, client-side entry point that
+  // opens the panel dock (publishes the default spec + expand request),
+  // clears it (/panel clear), or relays an instruction to the model
+  // (/panel <指令>) so the panel gets tailored content.
+  //
+  // inputTriggers is subscribed via cordis OPTIONAL injection (ctx.inject),
+  // NOT a one-shot ctx.get() at apply time: the service is typically
+  // provided by a different bundle than slots/sessions, so it can arrive
+  // AFTER apply() runs — a one-shot lookup would silently disable /panel
+  // even on hosts that DO ship the service (service arrival order race).
+  // ctx.inject activates the callback only when the service arrives (any
+  // order) and disposes with the subscription fiber; hosts without the
+  // service simply never register /panel, and rendering is unaffected
+  // either way.
+  ctx.inject(['inputTriggers'], (scope) => {
+    const slash = scope.get('inputTriggers') as InputTriggerServiceContract | undefined
+    if (slash === undefined) return
+    scope.effect(() => slash.registerSource(
+      createPanelSlashSource((sessionId, instruction) => sendPanelInstruction(ctx, sessionId, instruction)),
+    ), 'genui: /panel')
+  })
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}
+
+// Browser services the client entry needs: the slots registry (toolview +
+// dock) and sessions (scoped conversation send behind actions). This
+// declaration is what the host's fiber inject waiting uses — without it
+// apply() runs before the services bind and the whole plugin tree fails the
+// boot sweep.
+//
+// inputTriggers (the /panel command source) is deliberately NOT declared:
+// cordis `inject` is a hard activation gate — a declared service that is
+// never provided (pristine DSH shells ship no inputTriggers provider) parks
+// the fiber in waiting forever and apply() never runs, silently killing all
+// GenUI rendering. Instead the apply() body subscribes via ctx.inject
+// (optional injection): hosts with the service get /panel registered in any
+// arrival order, hosts without it never register /panel — and the renderer
+// itself never depends on the service either way.
+export const inject = ['slots', 'sessions']
+
+// Re-export the registry renderer for the test suite (setup.ts registers it
+// exactly like apply() does on contract hosts).
+export { renderGenuiFence }
+export type { GenuiFenceContext } from './fence-render.tsx'

package/src/client/interaction-store.ts

@@ -0,0 +1,122 @@
+/**
+ * Interaction-state store: durable per-block GenUI interaction state
+ * (radio answers, submit lock, input/textarea values) in localStorage.
+ *
+ * LOCAL-FIRST persistence: a ```dsh-ui block's interactive state survives
+ * page refresh and session reopen because it is keyed by
+ * `session + block slot + content fingerprint` — replaying the same message
+ * (same content) restores the exact state, while NEW content (换题, edited
+ * spec) gets a fresh key and thus a clean slate. Different messages never
+ * share state because their content fingerprints differ.
+ *
+ * Bounded: at most MAX_BLOCKS entries, LRU-evicted on write; each block's
+ * payload is small (answers map + a few field values).
+ * @module @changfenhuang/dsh-genui/client/interaction-store
+ */
+
+/** Durable state of one UI block. */
+export interface BlockInteractionState {
+  /** group → chosen option label (radio aggregation answers). */
+  answers?: Record<string, string>
+  /** True after a local grading: the paper stays graded across refresh. */
+  locked?: boolean
+  /** field id → current value (input/textarea with an `id`). */
+  fields?: Record<string, string>
+}
+
+const STORE_KEY = 'dsh.genui.interaction'
+/** Max tracked blocks; LRU eviction keeps the store bounded. */
+const MAX_BLOCKS = 200
+
+interface StoreShape {
+  /** Block keys in most-recently-written order (index 0 = newest). */
+  order: string[]
+  blocks: Record<string, BlockInteractionState>
+}
+
+function emptyStore(): StoreShape {
+  return { order: [], blocks: {} }
+}
+
+function readStore(): StoreShape {
+  try {
+    const raw = localStorage.getItem(STORE_KEY)
+    if (raw === null) return emptyStore()
+    const parsed = JSON.parse(raw) as Partial<StoreShape>
+    if (!Array.isArray(parsed.order) || typeof parsed.blocks !== 'object' || parsed.blocks === null) {
+      return emptyStore()
+    }
+    return { order: parsed.order.filter(k => typeof k === 'string'), blocks: parsed.blocks as Record<string, BlockInteractionState> }
+  } catch {
+    return emptyStore()
+  }
+}
+
+function writeStore(store: StoreShape): void {
+  try {
+    localStorage.setItem(STORE_KEY, JSON.stringify(store))
+  } catch {
+    // Quota / privacy-mode failures are non-fatal: interaction stays live
+    // in memory, only the persistence is lost.
+  }
+}
+
+/** Load a block's durable state, or null when absent/corrupt. */
+export function loadBlockState(stateKey: string): BlockInteractionState | null {
+  if (stateKey === '') return null
+  const store = readStore()
+  return store.blocks[stateKey] ?? null
+}
+
+/** Save a block's durable state (LRU: touched keys move to the front). */
+export function saveBlockState(stateKey: string, state: BlockInteractionState): void {
+  if (stateKey === '') return
+  const store = readStore()
+  const order = store.order.filter(k => k !== stateKey)
+  order.unshift(stateKey)
+  const blocks = { ...store.blocks, [stateKey]: state }
+  while (order.length > MAX_BLOCKS) {
+    const evicted = order.pop()
+    if (evicted !== undefined) delete blocks[evicted]
+  }
+  writeStore({ order, blocks })
+}
+
+/** Forget a block's durable state (e.g. after a reset-to-empty). */
+export function clearBlockState(stateKey: string): void {
+  if (stateKey === '') return
+  const store = readStore()
+  if (!(stateKey in store.blocks)) return
+  const blocks = { ...store.blocks }
+  delete blocks[stateKey]
+  writeStore({ order: store.order.filter(k => k !== stateKey), blocks })
+}
+
+/**
+ * Deterministic content fingerprint (djb2) for a block's raw fence body.
+ * Two render passes of the SAME content share a fingerprint (state restores);
+ * edited content gets a new one (fresh state). Not a security hash — the
+ * store only uses it for equality/identity.
+ */
+export function fingerprint(raw: string): string {
+  let h = 5381
+  for (let i = 0; i < raw.length; i++) {
+    h = ((h << 5) + h + raw.charCodeAt(i)) >>> 0
+  }
+  return h.toString(36)
+}
+
+/** Build the durable state key for a fence block: session + fence slot + content fingerprint. */
+export function fenceStateKey(sessionId: string, fenceKey: number | string, raw: string): string {
+  return `f:${sessionId}:${String(fenceKey)}:${fingerprint(raw)}`
+}
+
+/** Build the durable state key for a panel publish (content-keyed). */
+export function panelStateKey(sessionId: string, raw: string): string {
+  return `p:${sessionId}:${fingerprint(raw)}`
+}
+
+/** Build the durable state key for a render_ui tool card (call-keyed). */
+export function toolStateKey(sessionId: string, callId: string): string {
+  return `t:${sessionId}:${callId}`
+}

package/src/client/mermaid-core.ts

@@ -0,0 +1,121 @@
+/**
+ * Mermaid render engine — the HEAVY half. This module imports mermaid and is
+ * bundled ONLY into the lazy asset bundle `lib/assets/mermaid.js`, loaded on
+ * demand by the mermaid-lazy loader when a spec contains a `mermaid` node;
+ * the main client bundle stays small.
+ *
+ * Whitelist: only a fixed set of diagram kinds render; anything else throws
+ * so the caller shows its fallback — except undeclared flowchart bodies
+ * (model-generated sources missing the `graph TD` header line), which get
+ * the declaration prepended via ensureFlowchartKind and render normally.
+ * mermaid runs client-side with its own sanitizer; we additionally refuse `securityLevel: 'loose'`-style inputs by
+ * only initializing with the strict default, AND we re-check the rendered SVG
+ * before it is injected (see `assertSafeSvg` in mermaid-safe): the injection
+ * point is the only place in GenUI that uses `dangerouslySetInnerHTML`, so
+ * the last line of defense lives here, not inside mermaid.
+ * @module @changfenhuang/dsh-genui/client/mermaid-core
+ */
+import { assertSafeSvg, ensureFlowchartKind, repairMermaidSource } from './mermaid-safe.ts'
+
+let mermaidPromise: Promise<typeof import('mermaid')> | null = null
+
+/** Monotonic render id (replaces Math.random): no collisions, no entropy. */
+let renderSeq = 0
+
+function loadMermaid(): Promise<typeof import('mermaid')> {
+  mermaidPromise ??= import('mermaid').then(async m => {
+    const api = m.default
+    // Follow the host theme: boot-theme sets colorScheme on <html>; a
+    // dark-forced diagram on a light chat looked broken.
+    const dark = typeof document !== 'undefined'
+      && document.documentElement.style.colorScheme === 'dark'
+    api.initialize({
+      startOnLoad: false,
+      // Strict default: mermaid escapes/sanitizes; we never enable htmlLabels.
+      securityLevel: 'strict',
+      theme: dark ? 'dark' : 'neutral',
+      // Fail loudly: with suppressErrorRendering false (the default) mermaid
+      // renders an "error" diagram on parse/draw failure — the caller then
+      // receives a normal-looking SVG whose text is the raw engine error
+      // ("Syntax error in text / mermaid version …"), which lands on the page
+      // with no exception ever thrown. Suppressing the error diagram makes
+      // every failure throw so the caller shows its own fallback instead.
+      suppressErrorRendering: true,
+    })
+    return m
+  })
+  return mermaidPromise
+}
+
+/** Diagram kinds allowed through to the renderer. */
+const ALLOWED_KINDS = [
+  'flowchart', 'graph', 'sequenceDiagram', 'classDiagram', 'stateDiagram',
+  'gantt', 'pie', 'erDiagram', 'journey', 'gitGraph',
+]
+
+/** One render attempt into a private container. mermaid ≥ 11.16 resolves the
+ * diagram element via `document.body` while drawing flowcharts
+ * (`getDiagramElement`), so a DETACHED container makes every flowchart/graph
+ * render throw on an empty d3 selection ("Cannot read properties of null").
+ * The container is therefore mounted off-screen for the duration of the
+ * render — NOT `display:none`, which zeroes label measurements and makes
+ * dagre fail with "Could not find a suitable point" — and removed when done. */
+async function renderInto(m: typeof import('mermaid'), id: string, code: string, container: HTMLDivElement): Promise<string> {
+  container.style.position = 'fixed'
+  container.style.left = '-100000px'
+  container.style.top = '0'
+  container.style.margin = '0'
+  document.body?.appendChild(container)
+  try {
+    const { svg } = await m.default.render(id, code, container)
+    assertSafeSvg(svg)
+    return svg
+  } finally {
+    container.remove()
+  }
+}
+
+/**
+ * Render mermaid source to an SVG string.
+ * @param code - the mermaid diagram source.
+ * @returns the rendered SVG markup (verified free of script/event handlers).
+ * @throws when the kind is not whitelisted, rendering fails, or the output
+ *   fails the sanitization check.
+ */
+export async function renderMermaid(code: string): Promise<string> {
+  let trimmed = code.trim()
+  const firstLine = trimmed.split('\n', 1)[0] ?? ''
+  let kind = /^([A-Za-z]+)/.exec(firstLine)?.[1] ?? ''
+  if (!ALLOWED_KINDS.includes(kind)) {
+    // Lenient: model-generated sources frequently omit the mandatory
+    // diagram-type declaration line (`A --> B` with no leading
+    // `graph TD`). Detect a flowchart body by its edge arrows and prepend
+    // the declaration instead of throwing straight to the raw-source
+    // fallback; genuinely unclassifiable input still fails as before.
+    const lenient = ensureFlowchartKind(trimmed)
+    if (lenient !== trimmed) {
+      trimmed = lenient
+      kind = 'graph'
+    }
+  }
+  if (!ALLOWED_KINDS.includes(kind)) {
+    throw new Error(`mermaid kind '${kind}' is not allowed`)
+  }
+  const m = await loadMermaid()
+  const container = document.createElement('div')
+  try {
+    try {
+      return await renderInto(m, `genui-mermaid-${renderSeq++}`, trimmed, container)
+    } catch (error) {
+      // Retry once with the label-repair pass; a repaired source rendering
+      // successfully beats a syntax-error fallback for the same content.
+      const repaired = repairMermaidSource(trimmed)
+      if (repaired !== trimmed) {
+        return await renderInto(m, `genui-mermaid-${renderSeq++}`, repaired, container)
+      }
+      throw error
+    }
+  } finally {
+    container.remove()
+  }
+}

package/src/client/mermaid-lazy.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime loader for the mermaid engine. The heavy mermaid bundle ships as a
+ * separate asset (`lib/assets/mermaid.js`, served by the plugin's own HTTP
+ * route) and is fetched ONLY when a spec contains a `mermaid` node — the
+ * main client bundle stays small and most conversations never download
+ * mermaid at all. On a host that does not serve the asset (older harness) the
+ * load rejects and the MermaidNode shows its plain-source fallback.
+ *
+ * The pure source utilities stay statically exported from mermaid-safe so
+ * tests (and any consumer) can use them without the engine.
+ * @module @changfenhuang/dsh-genui/client/mermaid-lazy
+ */
+import { loadGenuiAsset } from './asset-loader.ts'
+export { assertSafeSvg, ensureFlowchartKind, repairMermaidSource } from './mermaid-safe.ts'
+
+/** The engine surface registered by the mermaid asset bundle. */
+interface MermaidAssetApi {
+  renderMermaid: (code: string) => Promise<string>
+}
+
+/**
+ * Render mermaid source to an SVG string (engine loaded on demand).
+ * @param code - the mermaid diagram source.
+ * @returns the rendered SVG markup (verified free of script/event handlers).
+ * @throws when the asset cannot load, the kind is not whitelisted, rendering
+ *   fails, or the output fails the sanitization check.
+ */
+export async function renderMermaid(code: string): Promise<string> {
+  const api = await loadGenuiAsset<MermaidAssetApi>('mermaid')
+  return api.renderMermaid(code)
+}

package/src/client/mermaid-safe.ts

@@ -0,0 +1,122 @@
+/**
+ * Pure mermaid source utilities — no mermaid import, so this module can ship
+ * in the main client bundle while the heavy mermaid engine lives in a lazy
+ * asset bundle (`lib/assets/mermaid.js`, loaded on demand by mermaid-lazy).
+ * @module @changfenhuang/dsh-genui/client/mermaid-safe
+ */
+
+/** Reject any rendered SVG that carries script, event-handler attributes, or
+ * `javascript:` URIs. Under mermaid's strict security level a legitimate
+ * diagram never contains these, so a hit means the sanitizer failed (a
+ * mermaid regression or a bypass): throw and let the caller show the plain
+ * source fallback instead of injecting the markup. Cheap linear scan over
+ * the SVG string; happens once per diagram.
+ */
+const SVG_INJECTION = /<script|[\s"']on[a-z]+\s*=|javascript:/i
+
+/** Throws when `svg` carries script, event-handler attributes, or
+ * `javascript:` URIs. Exported for tests; `renderMermaid` is the only caller
+ * in production. */
+export function assertSafeSvg(svg: string): void {
+  if (SVG_INJECTION.test(svg)) {
+    throw new Error('mermaid output failed the sanitization check; refusing to render')
+  }
+}
+
+/**
+ * Best-effort repair of common model-authored label mistakes in graph /
+ * flowchart sources, used only when the original fails to render:
+ * - drop backticks — lexically illegal in mermaid labels (models embed
+ *   ```dsh-ui style fences, which break the parser with "Lexical error");
+ * - strip `<br/>` tags, which require htmlLabels (never enabled here);
+ * - quote unquoted node labels containing CJK, spaces, or other characters
+ *   mermaid's bare-label grammar rejects (observed live: `A[模型生成 spec]`).
+ * Conservative by design: already-quoted labels, plain ASCII labels without
+ * spaces, and non-flowchart kinds are left untouched (apart from the
+ * backtick/`<br/>` sanitation above, which is harmless everywhere in a
+ * flowchart).
+ *
+ * Labeled-edge spans (`-- 文本 -->`, `== 文本 ==>`, `-. 文本 .->`) are free
+ * text and must never be quoted: wrapping them breaks the parser
+ * ("Expecting 'LINK' … got 'STR'"), observed live with
+ * `H -- 否(流式中) --> J`. Each span is swapped for a bracket-free
+ * placeholder before quoting and restored verbatim afterwards, so the quote
+ * pass can neither corrupt it nor be thrown off by inserted quotes
+ * elsewhere on the line.
+ *
+ * Pipe-style edge labels (`-->|文本|`) are the opposite: an UNQUOTED pipe
+ * label containing `[` or `]` breaks the parser ("Parse error", observed
+ * live with `-->|6. 用户交互 → [genui-action]|`) because the brackets are
+ * node grammar. Quoting the label text is display-neutral (mermaid renders
+ * `-->|"文本"|` without the quotes) and parses. These spans are masked too,
+ * so the node-label quote pass below cannot reach inside them and produce
+ * nested quotes, and restored last.
+ */
+export function repairMermaidSource(code: string): string {
+  const kind = /^([A-Za-z]+)/.exec(code.trim())?.[1] ?? ''
+  if (kind !== 'graph' && kind !== 'flowchart') return code
+  const cleaned = code.replace(/`/g, '').replace(/<br\s*\/?>/gi, ' ')
+  // A labeled edge is `--`/`==`/`-.` (not immediately `-->`/`==>`), a label
+  // made of non-dash chars or single dashes (never `--`, which would start a
+  // new edge), then the arrow. `[ \t]*` — never newlines — keeps the span on
+  // one line.
+  const EDGE = /(--|==|-\.)(?!>)[ \t]*([^-\n]|-(?!--))*?[ \t]*(-->|==>|\.->)/g
+  const spans: string[] = []
+  const masked = cleaned.replace(EDGE, (span) => {
+    spans.push(span)
+    return `\uE000${spans.length - 1}\uE001`
+  })
+  // Pipe label spans whose text carries at least one bracket char. The
+  // bracket requirement keeps legitimate pipe characters inside node labels
+  // (e.g. `A[a | b | c]`) untouched. Already-quoted labels (any `"` in the
+  // text) are left alone. The placeholder must be bracket-free so the
+  // node-label quote pass below cannot match inside it.
+  const PIPE = /\|([^|\n]*[\[\]][^|\n]*)\|/g
+  const pipeSpans: string[] = []
+  const maskedPipes = masked.replace(PIPE, (whole, text: string) => {
+    const trimmed = text.trim()
+    if (trimmed.includes('"')) return whole
+    pipeSpans.push(trimmed)
+    return `\uE002${pipeSpans.length - 1}\uE003`
+  })
+  const quoted = maskedPipes.replace(
+    /([\[\(])([^\[\]\(\)\{\}"'\n]*)([\]\)])/g,
+    (whole, open: string, label: string, close: string) => {
+      const trimmed = label.trim()
+      if (trimmed === '') return whole
+      if (/[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/.test(trimmed) || /\s/.test(trimmed)) {
+        return `${open}"${trimmed}"${close}`
+      }
+      return whole
+    },
+  )
+  return quoted
+    .replace(/\uE000(\d+)\uE001/g, (whole, i: string) => spans[Number(i)] ?? whole)
+    .replace(/\uE002(\d+)\uE003/g, (whole, i: string) => {
+      const text = pipeSpans[Number(i)]
+      return text === undefined ? whole : `|"${text}"|`
+    })
+}
+
+/** Flowchart edge arrows. The negative lookahead on `-->(?!>)` keeps
+ * sequence-diagram message arrows (`-->>`) from matching. */
+const FLOWCHART_EDGE = /-->(?!>)|==>|-\.->/
+
+/**
+ * Lenient repair for sources that omit the mandatory diagram-type
+ * declaration line — the #1 failure mode of model-generated mermaid (chat
+ * assistants routinely emit `A --> B` without the leading `graph TD`).
+ *
+ * When the first token is not an already-declared `graph`/`flowchart` kind
+ * but the body contains flowchart edge arrows, prepend `graph TD` so the
+ * diagram renders instead of tripping the kind gate. Anything else — an
+ * explicitly declared kind, a sequence/gantt/pie body (no flowchart edges),
+ * or plain text — is returned unchanged: we never guess at the diagram type.
+ */
+export function ensureFlowchartKind(code: string): string {
+  const trimmed = code.trim()
+  const kind = /^([A-Za-z]+)/.exec(trimmed)?.[1] ?? ''
+  if (kind === 'graph' || kind === 'flowchart') return code
+  if (!FLOWCHART_EDGE.test(trimmed)) return code
+  return `graph TD\n${trimmed}`
+}