feat: render rich tauri agent replies

Author: Jacobinwwey

docs/diataxis/en/explanation/agent-conversation-focus-mode-plan.md

@@ -13,43 +13,31 @@ This is the current product-facing priority because it connects the existing lea
 single, discoverable interaction loop instead of leaving tutor, path, and focus behaviors split
 across separate UI surfaces.
 
-## 2026-05-27 Tauri-First Reply Direction
+## 2026-05-27 Tauri-First Reply Delivery
 
-Current branch reality is now asymmetric:
+The Tauri-first reply-rendering baseline is now implemented.
 
-- the conversation contract is real,
-- the knowledge-point/action shell is real,
-- Tauri reader hardening is real,
-- scoped knowledge-workspace hydration is real,
-- but assistant reply rendering is still not real in the same sense.
+Delivered now:
 
-If Tauri is temporarily allowed to lead and Godot is treated as a later adaptation target, the
-correct architecture center shifts:
-
-- Tauri becomes the rich-render baseline,
-- the Reader markdown/math/mermaid pipeline becomes the render substrate,
-- Godot later consumes downgraded/materialized output instead of constraining Tauri-first UX now.
-
-### Current code gap
-
-The current backend/frontend contract is only partially product-complete:
-
-- `src/learning/KnowledgeLearningPlatform.ts` returns `assistantMessage`, `citations`, `knowledgePoints`, memory signals, and trace data.
-- `src/frontend/agent_workspace.js` still consumes `assistantMessage` as a flat string.
-- `src/frontend/workspace_panes.js` still mounts conversation messages through plain `textContent`.
+- `src/learning/types.ts` and `src/learning/KnowledgeLearningPlatform.ts` now expose backward-compatible `assistantBlocks` beside legacy `assistantMessage`,
+- `src/frontend/markdown_runtime.js` now provides a shared markdown/math/mermaid runtime extracted from the Reader-side logic,
+- `src/frontend/workspace_panes.js` now mounts structured assistant replies through typed blocks instead of only plain text when structured payloads are present,
+- `src/frontend/agent_workspace.js` keeps the legacy fallback path so older `assistantMessage`-only responses still work,
+- `html_artifact` rendering now has a sandboxed preview path instead of requiring arbitrary full-HTML injection into the main chat DOM.
 
-That means:
+If Tauri is temporarily allowed to lead and Godot is treated as a later adaptation target, the
+architecture center is now aligned as intended:
 
-- grounded retrieval works,
-- action orchestration works,
-- but markdown, KaTeX, Mermaid, and structured HTML do not yet reach the agent reply surface.
+- Tauri is the rich-render baseline,
+- the Reader markdown/math/mermaid pipeline is the render substrate,
+- Godot can later consume downgraded/materialized output instead of constraining Tauri-first UX now.
 
-### Tauri-first implementation program
+### Delivered implementation program
 
 1. **Response contract evolution**
-   - Keep `assistantMessage` as a compatibility fallback.
-   - Add an `assistantBlocks` shape for typed reply rendering.
-   - Start with:
+   - `assistantMessage` remains as a compatibility fallback.
+   - `assistantBlocks` is now present for typed reply rendering.
+   - Current block baseline:
      - `main_markdown`
      - `citations`
      - `knowledge_actions`
@@ -62,34 +50,39 @@ That means:
      - `src/server.ts`
 
 2. **Shared render runtime extraction**
-   - Reuse the mature Reader pipeline instead of creating a fourth markdown path.
-   - Extract the reusable markdown/math/mermaid runtime from:
+   - The mature Reader pipeline is now reused instead of creating a fourth markdown path.
+   - The reusable markdown/math/mermaid runtime is extracted from:
      - `src/frontend/reader.js`
      - `src/frontend/app.js`
      - `src/reader_renderer.ts`
      - `src/routes/render.ts`
-   - The shared runtime should remain browser/Tauri-friendly and later support Godot materialization without being designed around it now.
+   - The shared runtime remains browser/Tauri-friendly and preserves a later Godot materialization boundary.
 
 3. **Message block renderer in the agent workspace**
-   - Replace plain message mounting with a typed block renderer.
-   - Keep conversation-card/result-presentation registries intact.
-   - Introduce a dedicated assistant-reply renderer in:
+   - Plain message mounting is now replaced by a typed block renderer where structured payloads are present.
+   - Conversation-card/result-presentation registries remain intact.
+   - Assistant-reply rendering now lives in:
      - `src/frontend/agent_workspace.js`
      - `src/frontend/workspace_panes.js`
      - `src/frontend/index.html`
      - `src/frontend/styles.css`
 
 4. **HTML artifact path**
-   - Do not inject arbitrary full HTML into the main chat DOM.
-   - Treat large HTML payloads as artifacts with a sandboxed preview flow.
-   - This should mirror the existing product direction already proven in external references like Cherry Studio, while staying stack-native to NoteConnection.
+   - Arbitrary full HTML is not injected into the main chat DOM.
+   - Large HTML payloads are treated as artifacts with a sandboxed preview flow.
 
 5. **Streaming and transition safety**
-   - Keep current SSE + sync fallback behavior.
-   - Stream into `main_markdown` blocks rather than directly mutating plain-text message nodes.
-   - Preserve current `knowledgePoints` and capability execution behavior during the transition so the upgrade is forward-compatible rather than a rewrite.
+   - SSE + sync fallback behavior is preserved.
+   - Structured replies now flow through `main_markdown` blocks while legacy replies still fall back cleanly.
+   - Current `knowledgePoints` and capability execution behavior stays forward-compatible.
+
+### Remaining follow-up
+
+- expand block usage where future endpoints emit richer assistant payloads,
+- keep the new render substrate honest through real browser/Tauri verification,
+- decide later whether Reader itself should delegate more of its internal rendering helpers to the shared runtime rather than only sharing extracted logic.
 
-### Acceptance criteria for this next slice
+### Acceptance criteria for this delivered slice
 
 1. Tauri agent replies can render markdown headings, lists, tables, KaTeX, and Mermaid without leaving persistent error overlays in the visible chat surface.
 2. The reply surface still works when only legacy `assistantMessage` is present.

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -33,12 +33,18 @@ Implemented now at current HEAD:
 - Debug and evidence tooling:
   - the repository now ships runtime/webview/window capture helpers plus Mermaid stage/export tooling under `scripts/`, so live Tauri failures can be inspected with first-party evidence commands instead of one-off manual probing.
 
-Current Tauri product gap:
+Tauri-first reply rendering baseline delivered:
 
-- The agent reply area is still plain-text oriented.
-- `src/frontend/agent_workspace.js` still consumes `assistantMessage` as a flat string, and `src/frontend/workspace_panes.js` still mounts conversation messages via `node.textContent = message`.
-- This means the current Tauri chat shell can issue grounded requests and action cards, but it still does not reuse the mature Reader markdown/math/mermaid rendering path for assistant replies.
-- The next delivery step is therefore not another generic shell expansion. It is a Tauri-first reply-rendering upgrade that preserves the current contract while introducing a richer message model.
+- `src/learning/types.ts` and `src/learning/KnowledgeLearningPlatform.ts` now expose backward-compatible `assistantBlocks` alongside legacy `assistantMessage`,
+- `src/frontend/markdown_runtime.js` now carries a shared markdown/math/mermaid runtime extracted from the Reader-side logic,
+- `src/frontend/workspace_panes.js` now mounts assistant replies through typed blocks instead of only plain text when structured payloads are present,
+- `src/frontend/agent_workspace.js` keeps legacy fallback behavior intact, so older `assistantMessage`-only flows still render.
+
+The next gap is narrower now:
+
+- broaden block coverage where future endpoints emit richer assistant payloads,
+- keep the new render substrate honest under real browser/Tauri runtime verification,
+- preserve a clean downgrade/materialization boundary for later Godot reuse.
 
 Code-vs-plan reality for this slice:
 
@@ -48,7 +54,7 @@ Code-vs-plan reality for this slice:
 | Tauri markdown reader parity | markdown, math, and Mermaid should survive real runtime conditions without persistent error overlays | reader/runtime paths now render Mermaid with frontend-first + backend-PNG fallback and suppress leaked error artifacts | Operational |
 | Provider settings | provider/model/API-key controls should be isolated and write durable TOML configuration | dedicated agent/provider settings surface plus preset/TOML template helpers are now present | Operational |
 | Conversation retry transport | turn/replay headers should survive browser/Tauri preflight | CORS now allows both conversation turn headers | Closed |
-| Tauri agent reply rendering | assistant replies should render rich markdown instead of plain text | reply area still uses `assistantMessage` + `textContent` and therefore remains rendering-incomplete | Open |
+| Tauri agent reply rendering | assistant replies should render rich markdown instead of plain text | backward-compatible `assistantBlocks` plus shared markdown runtime now power rich assistant replies, while legacy `assistantMessage` remains supported | Operational |
 
 ## 2026-05-26 Program F Closure
 
@@ -169,8 +175,8 @@ Current branch status for this slice:
 - graph-focus fullscreen now promotes the real graph workspace instead of only enlarging a metadata card (`src/frontend/workspace_panes.js`, `src/frontend/styles.css`),
 - the scoped-knowledge conversation flow is now materially more honest about corpus readiness: active folder target flows into the request contract, the server selectively hydrates likely title-matching documents into the workspace, and conversation traces now include readiness + miss diagnostics instead of only returning an empty top-k result (`src/frontend/source_manager.js`, `src/frontend/agent_workspace.js`, `src/server.ts`, `src/routes/data.ts`, `src/learning/KnowledgeLearningPlatform.ts`),
 - the new agent workspace shell now has i18n coverage for static shell strings plus runtime button/empty-state messaging, existing knowledge-card actions / localized system messages now re-render on language change instead of staying in the previous locale, conversation card rerender is now centralized through a card-kind renderer registry, and a source-level parity guard now checks append-kind vs registry alignment (`src/frontend/index.html`, `src/frontend/locales/en.json`, `src/frontend/locales/zh.json`, `src/frontend/workspace_panes.js`, `src/frontend/agent_workspace.js`, `src/agent_workspace.frontend.test.ts`),
-- provider/model/API-key settings are now isolated into a dedicated agent settings page with preset-template and TOML-template flows, but reply rendering in that same workspace still remains plain-text and is therefore the next obvious Tauri-first closure item (`src/frontend/index.html`, `src/frontend/settings.js`, `src/notemd/AppConfigToml.ts`, `src/notemd/providerTemplates.ts`),
-- the reader/runtime render stack is now substantially more robust for Tauri markdown usage: raw markdown, KaTeX, Mermaid frontend render, Mermaid backend PNG fallback, and leaked Mermaid error suppression are all present; the missing step is to reuse that stack inside the agent reply surface instead of keeping it isolated to the Reader (`src/frontend/reader.js`, `src/frontend/app.js`, `src/reader_renderer.ts`, `src/routes/render.ts`, `src/notemd/MermaidProcessor.ts`),
+- provider/model/API-key settings are now isolated into a dedicated agent settings page with preset-template and TOML-template flows, and the same agent workspace now also has a typed rich-reply baseline instead of staying plain-text-only (`src/frontend/index.html`, `src/frontend/settings.js`, `src/notemd/AppConfigToml.ts`, `src/notemd/providerTemplates.ts`, `src/frontend/markdown_runtime.js`, `src/frontend/workspace_panes.js`, `src/frontend/agent_workspace.js`),
+- the reader/runtime render stack is now substantially more robust for Tauri markdown usage: raw markdown, KaTeX, Mermaid frontend render, Mermaid backend PNG fallback, leaked Mermaid error suppression, and a shared markdown runtime for agent replies are all present (`src/frontend/reader.js`, `src/frontend/app.js`, `src/frontend/markdown_runtime.js`, `src/reader_renderer.ts`, `src/routes/render.ts`, `src/notemd/MermaidProcessor.ts`),
 - locale governance now includes backend-to-frontend capability label-key parity blocking: emitted conversation capability `labelKey` values must resolve to non-empty bilingual `agentWorkspace.actions.*` entries (`src/learning/KnowledgeLearningPlatform.ts`, `src/frontend/locales/en.json`, `src/frontend/locales/zh.json`, `src/agent_workspace.locale.contract.test.ts`),
 - modular knowledge-route closure now includes live browser strict proof instead of snapshot-only recovery: conversation response wiring, capability-triggered request routes, card-title localization, and graph-focus compatibility now pass `STRICT`, `UI_STRICT`, and `UI_DYNAMIC_STRICT` against real browser/network traces (`src/routes/knowledge.ts`, `src/learning/KnowledgeLearningPlatform.ts`, `src/frontend/app.js`, `src/frontend/locales/en.json`, `src/frontend/locales/zh.json`, `scripts/verify-agent-workspace-browser.js`),
 - locale governance now also blocks capability failure-message drift: emitted `failure.messageKey` values must resolve to bilingual `agentWorkspace.messages.*` entries with aligned interpolation placeholders and stable fallback placeholder sets (`src/learning/KnowledgeLearningPlatform.ts`, `src/frontend/locales/en.json`, `src/frontend/locales/zh.json`, `src/agent_workspace.locale.contract.test.ts`),

docs/diataxis/zh/explanation/agent-conversation-focus-mode-plan.md

@@ -9,42 +9,30 @@
 - `focus mode` 与 `学习路径` 两个 pane 可以并排共存，
 - 两个 pane 都支持各自独立提升为全屏。
 
-## 2026-05-27 Tauri-first 回复渲染方向
+## 2026-05-27 Tauri-first 回复渲染交付
 
-当前分支现实已经出现明显不对称：
+Tauri-first reply-rendering baseline 现已实现。
 
-- conversation contract 已经是真实的，
-- knowledge-point / action shell 已经是真实的，
-- Tauri Reader 渲染加固已经是真实的，
-- scoped knowledge workspace hydration 已经是真实的，
-- 但 assistant reply rendering 还没有以同样强度变成“真实产品能力”。
+当前已交付：
 
-如果暂时允许 Tauri 优先、把 Godot 视为后续适配目标，那么正确的架构重心应调整为：
+- `src/learning/types.ts` 与 `src/learning/KnowledgeLearningPlatform.ts` 现已在保留 legacy `assistantMessage` 的同时返回向前兼容的 `assistantBlocks`，
+- `src/frontend/markdown_runtime.js` 现已提供一套从 Reader 侧逻辑抽取出来的共享 markdown / math / mermaid runtime，
+- `src/frontend/workspace_panes.js` 现已在结构化载荷存在时通过 typed blocks 挂载 assistant reply，而不再只走纯文本，
+- `src/frontend/agent_workspace.js` 继续保留 legacy fallback，因此旧的 `assistantMessage`-only 响应仍可显示，
+- `html_artifact` 现已具备 sandboxed preview 路径，而不再需要把任意完整 HTML 直接注入主聊天 DOM。
 
-- 以 Tauri 作为 rich-render baseline，
-- 以 Reader 的 markdown / math / mermaid 渲染链作为主渲染 substrate，
-- Godot 未来消费的是降级 / 物化后的输出，而不是反过来在当前阶段约束 Tauri 的交互体验。
+如果暂时允许 Tauri 优先、把 Godot 视为后续适配目标，那么架构重心现在已经按预期对齐：
 
-### 当前代码缺口
+- Tauri 是 rich-render baseline，
+- Reader 的 markdown / math / mermaid 管线是主渲染 substrate，
+- Godot 未来消费的是降级 / 物化后的输出，而不是继续反向约束当前 Tauri UX。
 
-目前后端 / 前端契约只完成了一半：
-
-- `src/learning/KnowledgeLearningPlatform.ts` 已返回 `assistantMessage`、`citations`、`knowledgePoints`、memory signals 与 trace data，
-- `src/frontend/agent_workspace.js` 仍把 `assistantMessage` 当作平铺字符串消费，
-- `src/frontend/workspace_panes.js` 仍通过普通 `textContent` 挂载 conversation 消息。
-
-这意味着：
-
-- grounded retrieval 已经成立，
-- action orchestration 已经成立，
-- 但 markdown、KaTeX、Mermaid 与结构化 HTML 还没有真正进入 agent reply surface。
-
-### Tauri-first 实施方案
+### 已交付实施方案
 
 1. **响应契约演进**
-   - 保留 `assistantMessage` 作为兼容回退字段，
-   - 增加 `assistantBlocks` 作为 typed reply rendering 载体，
-   - 第一批 block 类型建议至少包含：
+   - `assistantMessage` 继续作为兼容回退字段保留，
+   - `assistantBlocks` 已作为 typed reply rendering 载体落地，
+   - 当前 block 基线包含：
      - `main_markdown`
      - `citations`
      - `knowledge_actions`
@@ -57,32 +45,37 @@
      - `src/server.ts`
 
 2. **共享渲染运行时抽取**
-   - 直接复用 Reader 成熟链路，而不是再造第四套 markdown 路径，
-   - 从以下位置抽取可复用的 markdown / math / mermaid runtime：
+   - 已直接复用 Reader 成熟链路，而不是再造第四套 markdown 路径，
+   - 可复用的 markdown / math / mermaid runtime 已从以下位置抽取：
      - `src/frontend/reader.js`
      - `src/frontend/app.js`
      - `src/reader_renderer.ts`
      - `src/routes/render.ts`
-   - 该共享 runtime 需要首先服务 browser/Tauri，同时保留未来为 Godot 做物化输出的能力，但当前不应被 Godot-first 设计反向约束。
+   - 这套共享 runtime 现已首先服务 browser/Tauri，同时保留未来为 Godot 做物化输出的边界。
 
 3. **agent workspace 中的消息块渲染器**
-   - 用 typed block renderer 替换当前的 plain message mounting，
-   - 保持现有 conversation-card / result-presentation registry 继续可用，
-   - 在以下文件中引入专用 assistant-reply renderer：
+   - 结构化载荷存在时，已用 typed block renderer 替换当前的 plain message mounting，
+   - 现有 conversation-card / result-presentation registry 继续保持可用，
+   - assistant-reply renderer 现已落在以下文件中：
      - `src/frontend/agent_workspace.js`
      - `src/frontend/workspace_panes.js`
      - `src/frontend/index.html`
      - `src/frontend/styles.css`
 
 4. **HTML artifact 路径**
-   - 不要把任意完整 HTML 直接注入主聊天 DOM，
-   - 对较大 HTML 结果采用 artifact 语义，并通过 sandboxed preview 路径展示，
-   - 这条产品方向可以参考 Cherry Studio 的思路，但实现必须保持 NoteConnection 当前栈内生，而不是复制外部架构。
+   - 任意完整 HTML 不会直接注入主聊天 DOM，
+   - 较大 HTML 输出会通过 artifact 语义与 sandboxed preview 路径展示。
 
 5. **流式输出与迁移安全**
-   - 保留当前 SSE + sync fallback 行为，
-   - 将流式内容写入 `main_markdown` block，而不是直接操作纯文本消息节点，
-   - 在迁移期间保持现有 `knowledgePoints` 与 capability execution 行为不变，使这次升级成为 forward-compatible 演进，而不是推倒重来。
+   - 当前 SSE + sync fallback 行为已保留，
+   - 结构化回复现已通过 `main_markdown` block 进入渲染链，而 legacy 回复仍能平滑回退，
+   - 现有 `knowledgePoints` 与 capability execution 行为保持向前兼容。
+
+### 剩余跟进项
+
+- 当更多端点开始返回 richer assistant payload 时，继续扩充 block 覆盖面，
+- 让新的共享 render substrate 在真实 browser/Tauri 运行时下持续经受验证，
+- 后续再决定是否让 Reader 本体进一步委托更多内部 helper 给这套共享 runtime，而不是只共享已抽取逻辑。
 
 ### 本阶段验收标准