dsh-mosaic 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+> 版本规则：插件版本与**最近一次验证通过的 DeepSeek Harness 版本**保持一致。当前对齐 `0.2.1`（实测 rc.3 与 rc.5）。
+> 同一 Harness 版本下的插件自身修复按补丁号递增（`0.2.1` → `0.2.2` ……）；一旦换到新的 Harness 版本验证通过，版本号立即改成该 Harness 版本。
+
+## 0.2.1
+
+
+- Prompt 注册的生命周期修正：更新或读取覆盖之后，插件卸载会撤销**当前**的 section（此前留下的是第一个）；异步读取在卸载后不再注册。
+- Prompt 读取接口也做同源校验；响应不再包含 Host 绝对路径；并发保存串行化，磁盘与状态不会再分叉。
+- 覆盖文件改为原子写入：同目录独占临时文件 + `fsync` + `rename` + 目录同步，权限 `0600`；失败时旧文件保持原样，临时文件清理。
+- 读取覆盖时区分「文件不存在」「内容损坏」「不可读」：后两种会在设置页提示并按内置内容运行，原文件保留以便修复。
+- Widget 动作三重限制：默认要求真实用户手势（`navigator.userActivation`）、每分钟最多 10 次、单次 payload 不超过 16 KB；需要自动提交时在节点上显式写 `actions: "programmatic"`。
+- `SKILL.md` 的 frontmatter 描述加上引号，成为合法 YAML。
+- 删除仅被测试引用的 `lib/widget.js`（与客户端沙箱文档重复且已分叉）。
+- 新增诊断日志：`$DSH_HOME/logs/dsh-mosaic/<日期>.jsonl`，一行一个结构化事件（激活/停用、Prompt 生命周期、工具执行、路由、技能、浏览器侧失败），按天分文件、2 MB 滚动、保留 7 天、权限 `0600`；用户内容只记长度不记正文；`config.logLevel` 可调级别。
+
+## 0.4.1
+
+- Mermaid now ships as the unmodified official 12.2.0 distribution
+  (`lib/assets/mermaid.min.js`, MIT) instead of a wrapper derived from another
+  plugin. Rendering, theme mapping and SVG sanitizing are this package's own code.
+- The lazy asset URL is versioned (`?v=…`) and answered with an immutable cache entry;
+  the client asks the Host for the URL first and keeps one literal fallback.
+- `THIRD_PARTY_NOTICES.md` lists every dependency bundled inside the Mermaid build with
+  its license, and the license texts ship under `lib/assets/licenses/`.
+- The bundle patch no longer disables another plugin: it only inserts this package's
+  row.
+
+## 0.4.0
+
+- One visual style: the three-theme system (编辑 / 卡片 / 玻璃), its picker, tokens and
+  stored keys are removed.
+- The model prompt is editable again, this time properly: the settings page shows the
+  effective text (the built-in prompt by default), saves an override, and restores the
+  default. Precedence is user override > `config.prompt` > built-in; the override lives
+  in the Host data directory, and the write route accepts same-origin JSON only.
+- Visible UI copy moved to the Client locale service with `en` and `zh` dictionaries.
+- Styles are tagged with this package's identity so the client module system can reclaim
+  them; resources register through named effects.
+- The fullscreen surface renders through a portal inside its own component instead of a
+  second React root on `document.body`.
+- The lazy Mermaid asset moved to the package-private `/dsh-mosaic/assets` route and
+  registers on `window.__MosaicAssets__`.
+- Theme values come from host tokens only; the plugin no longer guesses light/dark.
+- The settings page is a localized explanation of the config key; copying a block's JSON
+  moved into the block header.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-mosaic contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# dsh-mosaic
+
+Mosaic 是一个轻量的 DeepSeek Harness 可视化回答插件。它把模型的回答从纯文本升级为**紧凑的原生 React 组件**，并保留一个受控的**沙箱 HTML/JS 逃生舱**，用来承载固定组件做不了的游戏、模拟器、音频、地图或自定义画布。
+
+它是**可选增强**，不强制每个回答都带 UI：当指标、对比、流程或交互用组件更容易扫读时，模型可以输出 `dsh-view`；纯文字回答同样有效，不需要为了“用插件”而加组件。
+
+它刻意不追求“什么都能画”：
+
+- 主包没有 ECharts / Three.js；flowchart / sequence 用官方 Mermaid 发行包，作为懒加载资产，只在出现 diagram 时下载（原始 5.5 MB，gzip 后约 1.3 MB，带版本号可长期缓存）。
+- 每个 diagram 卡片右上角有 `drawio` 按钮，可导出标准 mxGraph XML，在 draw.io 里继续编辑。
+- 组件目录保持精简，字段、校验、提示词来自同一份定义。
+- 普通文件/Office 只给链接，不在聊天里硬解。
+- 交互默认在本地完成；只有声明了 `action` 的组件才回模型。
+
+## 预览
+
+实际 DSH Web 页面渲染：
+
+![Mosaic 预览](https://raw.githubusercontent.com/imwhatiam/dsh-mosaic/main/assets/screenshots/preview.jpg)
+
+## 两个通道
+
+**正文围栏**：在回答里写 `dsh-view` JSON。围栏标记必须正好是 `dsh-view`；如果模型误用 `json`，客户端在 assistant 行内有一层兼容识别，但不要依赖它。
+
+````text
+```dsh-view
+{"title":"Ops snapshot","items":[
+  {"type":"stat","label":"Uptime","value":"99.96%","delta":"+0.02%"},
+  {"type":"callout","content":"No incidents in the last 7 days."}
+]}
+```
+````
+
+**工具卡片**：模型调用 `render_view`，适合独立面板、表格、图表或小组件。另有 `validate_view` 做发出前校验。
+
+## 一套视觉风格 + 可覆盖的模型 Prompt
+
+界面只有一套轻卡片风格，颜色全部取自主题令牌（`--dsw-alias-*`），因此自动跟随 DSH 的浅色/深色与字号，不再有主题切换器。
+
+插件向模型贡献一段说明可视化能力的 Prompt，默认是包内文本。
+
+**Settings → Mosaic** 就是这段文本的编辑页：打开即显示当前生效的内容（默认就是内置文案），可以直接改、点「保存」，随时点「恢复默认」回到插件自带文案。保存后从下一轮模型请求开始生效，所有浏览器看到的是同一份，重启也在。
+
+生效顺序是「你保存的覆盖 > 配置文件里的 `config.prompt` > 内置文本」。想在 profile 里批量固定一份基线，仍然可以在 `cordis.patch.yml` 给 mosaic 行加 `config.prompt`；留空、类型不对或超过 128 KB 会回落。
+
+覆盖内容存在 Host 数据目录的 `mosaic/prompt.json`，不进 profile 的组合文件，所以升级、换浏览器都不丢。写入是原子的（临时文件 + fsync + rename，权限 `0600`），失败时旧内容保持原样；写不进去时页面会明确提示「本次仅在进程内生效」。文件如果损坏或读不出来，页面同样会提示，并按内置内容运行、保留原文件供你修复。
+
+读写接口都只接受**同源**请求（核对浏览器的 `Sec-Fetch-Site` 与 `Origin`），写请求还要求 `content-type: application/json`；响应里不带 Host 的绝对路径。跨站页面既读不到也改不了这段文本。渲染出的卡片右上角另有「复制 JSON」，用于取回该块的围栏文本。
+
+## 组件
+
+- 布局：`text` `row` `col` `grid` `card` `divider` `spacer`
+- 展示：`stat` `badge` `progress` `list` `table` `keyvalue` `steps` `callout` `code` `diff` `chart` `diagram`
+- 媒体：`image` `video` `audio` `pdf` `link`
+- 交互：`button` `input` `select` `slider` `tabs` `quiz`
+- 高级：`widget`
+
+`diff` 带行号和 `-`/`+` gutter，长行自动换行。
+
+完整字段见 [`SKILL.md`](./SKILL.md)。
+
+## 日志
+
+插件会把自己的运行情况写进一个 JSONL 文件，出问题时优先看它：
+
+```
+$DSH_HOME/logs/dsh-mosaic/YYYY-MM-DD.jsonl   # 未设置 DSH_HOME 时是 ~/.dsh/logs/dsh-mosaic/
+```
+
+- 一行一个 JSON 对象，字段固定：`ts`、`level`（debug/info/warn/error）、`event`，其余按事件附带（如 `tool`、`ms`、`status`、`route`、`source`、`reason`）。
+- 记录什么：激活/停用、Prompt 的读取与保存（来源、字符数、是否落盘）、工具执行（名称、结果状态、耗时）、路由请求（方法、状态码、耗时）、技能被读取、以及浏览器侧上报的失败（`client.` 前缀：围栏解析失败、Mermaid 失败、Prompt 读写失败、Widget 动作被限流/超限丢弃）。
+- 不记录什么：Prompt 正文、组件 JSON、任何文本字段的内容。字段名为 `prompt`/`text`/`code`/`content`/`secret`/`token`/`password`/`apiKey` 时只写字符数；其它字符串超过 300 字符会被截断。
+- 体积：单文件超过 2 MB 滚动为 `<日期>.1.jsonl`；超过 7 天的文件在下次启动时删除；文件权限 `0600`。写不进去时不会影响插件，只在宿主日志里告警一次。
+- 浏览器侧的失败通过同源 `POST /dsh-mosaic/log` 上报（请求体上限 4 KB，跨站 403，客户端每分钟最多 20 条）。
+- 默认级别 `info`；想要更细可以给 mosaic 行加 `config.logLevel: debug`（或 `warn` 减少噪音）。
+
+排查示例：
+
+```bash
+# 只看错误
+grep -h '"level":"error"' "$DSH_HOME"/logs/dsh-mosaic/*.jsonl
+# 看最近一次激活和 Prompt 来源
+grep -h '"event":"plugin.activate"\|"event":"prompt.hydrate"' "$DSH_HOME"/logs/dsh-mosaic/*.jsonl | tail -5
+# 统计工具失败次数
+grep -c '"event":"tool.failed"' "$DSH_HOME"/logs/dsh-mosaic/*.jsonl
+```
+
+## 已知边界
+
+- 版本号跟随「最近一次验证通过的 DeepSeek Harness 版本」：当前是 `0.2.1`（实测 rc.3、rc.5）。同一 Harness 版本下的插件修复递增补丁号；换到新 Harness 版本验证后再把版本号对齐过去。
+- 围栏渲染靠扫描页面里的代码块实现：0.2.1 全系列（实测 rc.3 与 rc.5，master 同样）都没有给插件开放「渲染 fenced code block」的扩展点。工具通道 `render_view` + `tool.call.toolview` 是原生做法，围栏是它的补充。
+- 从 0.2.1 起代码块由 Shiki 渲染，`<code>` 上**没有** `language-*` 类；识别靠「代码块位于 assistant 行内 + 正文能解析成合法视图 spec」这条路径，用户消息、工具结果、推理块里的代码块都被排除。
+- `widget` 里调用 `window.mosaic.action()` 只有**真实用户手势**之后才会把动作发回模型（用浏览器的 `navigator.userActivation` 判断，Widget 自己伪造不了）；确实需要自行提交的 Widget 要在节点上写 `actions: "programmatic"`，并且仍受「每分钟 10 次、单次 16 KB」的限制。
+- `widget` 是 iframe，拿不到宿主的 `ctx.locale`，因此内部文案由调用方自己写；主题靠宿主令牌值传入。围栏是独立的 React root，切换外观不会触发它重渲染，所以 widget 会观察 `body[data-ds-dark-theme]` 这一个外观属性并在变化时重发令牌——这是插件唯一读取的宿主属性。
+- Mermaid 资产走包内私有路由 `/dsh-mosaic/assets`；没有 Web 服务时 diagram 回落到内置 SVG 布局。
+- bundle patch 只插入 Mosaic 自己这一行，不改动任何其他插件。若你还装了别的围栏类插件，两者可以对同一段围栏各显一套，按需在 profile 里关掉其中一个即可。
+- 持久化只用「Host 数据目录里的一个 JSON 文件」，没有走 DSH 的 storageDomain。实测（rc.5）：`storageDomain` 可用，但记录校验只在**重新打开**时执行（`put` 不校验）；`single` 布局遇到版本变化会直接拒绝打开，`compatibleVersions` 也不适用。对一份 Prompt 来说这些能力换不来收益，反而多一个依赖和三条失败分支。
+- Prompt 编辑页是对平台形态的**补充，不是平台标准做法**。DSH 把 Prompt 视为 composition 配置（system-prompt 的 README 明确写着没有终端用户编辑 Prompt 的 API），标准平面是 `Config` + `cordis.patch.yml`，客户端改值应走 `@Remote`，插件自有数据应走存储服务。这里为了「只装一个包、不引入 peer 依赖」，写入用了自建的同源校验路由、持久化用了自建的 `mosaic/prompt.json`。将来宿主提供多行配置表单或标准 Remote 时，这块应当迁移过去。
+
+## 本地优先
+
+表格排序/筛选/导出、tabs、quiz 判题、输入值、slider 拖动都在浏览器内完成。`button` 的 `local` 支持 `reset`、`copy`、`open`、`fullscreen`；只有 `action` 会把一条 `[mosaic-action]` 用户消息发回模型。
+
+状态按「会话 + 槽位 + 内容指纹」写入 `localStorage`，最多保留 100 块，刷新或重开会话时恢复。界面文案（按钮、提示、诊断）走 DSH 的 Client locale 服务，内置 `en` 与 `zh` 两套。
+
+## 沙箱 widget
+
+`widget.code` 是 HTML 片段或完整文档，渲染在：
+
+```html
+<iframe sandbox="allow-scripts allow-forms allow-popups" srcDoc="..."></iframe>
+```
+
+- 不透明源（没有 `allow-same-origin`），读不到宿主页面、cookie、storage。
+- CSP：没有网络；脚本仅内联/eval/blob；图片和媒体只允许 `data:`/`blob:`。
+- 宿主校验 `event.source` 和每次挂载的 nonce。
+- 主题通过 `--mosaic-*` CSS 变量注入；widget 用 `window.mosaic.action(name, payload)` 回传动作，用 `window.mosaic.resize()` 主动报高度。
+- 外部 CDN 脚本会被 CSP 拦掉；需要库时把代码内联进 widget。
+
+## 安装
+
+在 DSH Plugin Manager 中安装本插件，或使用命令行：
+
+```bash
+# 发布到 npm 后（普通 dsh web profile）
+dsh plugin --profile web add dsh-mosaic
+
+# 本地开发目录
+dsh plugin --profile desktop add link:/absolute/path/to/dsh-mosaic
+```
+
+安装后重启或刷新 DSH Web，新会话即可使用。bundle patch 只插入本插件一行，不会关闭或覆盖别人的插件。
+
+## 限制
+
+- 80 节点、6 层嵌套、表格 40×8、图表 40 点、diagram 12 节点/20 边、widget 代码 20k。
+- 不读本地文件、不渲染 docx/pptx/xlsx；这些用 `link` 卡片交给宿主打开。
+- 不内置数学公式排版；公式可以放在 `code` 或普通文本里。
+- 围栏渲染依赖 DSH 当前的代码块 DOM；宿主结构变化时可能需要适配。
+
+## 开发
+
+```bash
+node --test test/*.test.mjs
+node --check lib/index.js
+node --check lib/client.js
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: mosaic
+description: "Use Mosaic when a visual component makes a DeepSeek Harness answer easier to scan: dsh-view components, local-first interactions, diagrams, and sandboxed HTML/JS widgets. It is optional; prose is fine when no component helps."
+---
+
+# Mosaic — compact visual answers
+
+Mosaic is optional. Use it when a component makes the answer easier to scan; plain prose is fine. Do not add UI just because the answer has structure or numbers.
+
+Mosaic renders a small declarative component tree inside a `dsh-view` fence, or as a `render_view` tool card. Use the smallest format that fits; do not decorate an answer that a sentence already explains.
+
+## Fence
+
+````text
+```dsh-view
+{"title":"Ops snapshot","gap":12,"items":[
+  {"type":"stat","label":"Uptime","value":"99.96%","delta":"+0.02%"},
+  {"type":"callout","content":"No incidents in the last 7 days."}
+]}
+```
+````
+
+Rules:
+
+- Put the fence in the reply body, never in reasoning. The opening tag must be exactly `dsh-view`; a `json`/`text`/unlabelled fence normally stays a code block. The client has a narrow legacy fallback for a complete spec in an assistant row, but never rely on it.
+- Keep the JSON strict; no comments, trailing commas, or Markdown inside text fields.
+- Prefer one focal component; do not repeat the same data as both a table and a chart.
+- For files or Office documents, use a `link` card. Mosaic does not read local files or render Office; those open in the host app.
+- Media (`image`, `video`, `audio`, `pdf`) accepts an `http(s)` URL or a root-relative path.
+- `validate_view` is available for a preflight check on complex specs. For a flowchart longer than 6 nodes, prefer `direction: "TB"`; a long `LR` diagram scrolls horizontally.
+
+## Components
+
+### Layout
+
+- `text`: `{content, size?: "display|h1|h2|h3|body|muted|caption", align?: "left|center|right", tone?: "danger|success|warning|info|muted", mono?: true}`
+- `row`: `{items, gap?, align?: "start|center|end|between", wrap?}`
+- `col`: `{items, gap?, width?: 1-100}`
+- `grid`: `{cols: 1-6, items, gap?}`; a child can carry `"span": 2` for a bento layout
+- `card`: `{items, title?, eyebrow?, tone?: "info|success|warning|danger", flat?}`
+- `divider`: `{label?}`
+- `spacer`: `{}`
+
+### Display
+
+- `stat`: `{label, value, delta?, spark?: [number, ...]}` — delta starting with `+` is green, `-` is red; spark is a micro trend line (2–20 points).
+- `badge`: `{label, tone?: "success|warn|danger|accent"}`
+- `progress`: `{value: 0-100, label?, valueLabel?, variant?: "bar|ring", target?}`
+- `table`: `{columns: string[], rows: (string|number)[][], types?: ("text|num|delta|bar|badge")[], total?, export?, filter?: field-id, sort?: field-id}`
+  - Header click sorts locally (asc → desc → off). `types` controls right alignment, signed colors, bars, badges.
+  - `filter` binds to an `input`/`select` with that `id`; typing filters rows locally.
+  - `sort` binds a `select` whose value is a column name.
+  - `export:true` adds copy-as-Markdown / copy-as-CSV chips.
+  - `total:true` appends a numeric total row.
+- `list`: `{items: string[] | {title, desc}[] | nodes[], filter?: field-id}`
+- `keyvalue`: `{pairs: [{key, value}]}`
+- `steps`: `{steps: [{title, desc?}], current?: number}`
+- `callout`: `{content, title?, tone?: "info|success|warning|error"}`
+- `code`: `{code, lang?}`
+- `diff`: `{diffs: [{path, newText, oldText?}]}`
+- `chart`: `{kind: "bars|line|donut", data?: [{label, value}], series?: [{label, data: [{label, value}]}], stacked?, title?}`
+  - `donut` is single-series; use `data` only.
+  - For grouped bars or multi-line, use `series`.
+  - Keep it to 40 points and 8 series.
+- `diagram`: `{kind: "flowchart|sequence|timeline|layers", title?, direction?: "TB|LR", ...}` — see the section below.
+
+### Diagram
+
+When you show a flow, sequence, timeline, or layered architecture, use `diagram`. It is plain JSON; do not hand-write Mermaid markup for these unless the content needs a real Mermaid engine inside a widget. Flowchart and sequence nodes are rendered through a lazy-loaded Mermaid engine; timeline and layers use the built-in renderer. Every diagram card also has a `drawio` download button.
+
+- `flowchart`: `nodes: [{id, label, sub?, tone?: "accent|success|warning|danger|muted", shape?: "box|round|diamond"}], edges: [{from, to, label?, kind?: "solid|dashed|accent"}], direction?: "TB|LR"`
+- `sequence`: `participants: [{id, label}], messages: [{from, to, label, kind?: "sync|return|async"}]`
+- `timeline`: `items: [{title, desc?, time?}]`
+- `layers`: `layers: [{title, items: string[]}]`
+
+A single `diagram` node fragment (this is not a complete fence; wrap it in `{"items":[…]}` under a `dsh-view` tag):
+
+```text
+{"type":"diagram","kind":"flowchart","direction":"TB","nodes":[
+  {"id":"start","label":"收到请求","tone":"accent"},
+  {"id":"check","label":"缓存命中？","shape":"diamond"},
+  {"id":"hit","label":"返回缓存","tone":"success"},
+  {"id":"miss","label":"回源计算","tone":"warning"}
+],"edges":[
+  {"from":"start","to":"check"},
+  {"from":"check","to":"hit","label":"是","kind":"accent"},
+  {"from":"check","to":"miss","label":"否"}
+]}
+```
+
+Keep a flowchart to 12 nodes / 20 edges; sequence to 8 participants / 20 messages; timeline to 12 items; layers to 8 layers.
+
+### Media and links
+
+- `image`: `{src, alt?, caption?}`
+- `video`: `{src, poster?, aspect?: "16:9|4:3|1:1|9:16", caption?}`
+- `audio`: `{src, caption?}`
+- `pdf`: `{src, title?}`
+- `link`: `{label, href, description?}` — `http(s)` or `mailto`; for a local file/Office document, point at the host URL or describe where to open it.
+
+Images can be expanded to a full-screen lightbox; video/audio use the browser's native controls.
+
+### Interactive
+
+- `button`: `{label, action?, local?, text?, url?, tone?: "primary|danger|success|ghost", full?}`
+  - `action` sends `[mosaic-action]` to the model.
+  - `local` runs in the browser: `reset`, `copy` (needs `text`), `open` (needs `url`), `fullscreen`.
+  - No `action` and no `local` renders a disabled control.
+- `input`: `{id?, label?, placeholder?, value?, action?}` — Enter or blur sends when `action` is set; `id` makes the value available to a sibling table/list filter and to a submit-style action.
+- `select`: `{options: string[], id?, label?, selected?, action?}`
+- `slider`: `{min?, max?, value?, step?, id?, label?, action?}` — drag is debounced; local value updates immediately.
+- `tabs`: `{tabs: [{label, items}]}`
+- `quiz`: `{question, options: [{label, correct?, feedback?}], explanation?}` — local grading, no model round trip; retry is built in.
+
+### Sandboxed widget
+
+`widget`: `{code, height?: 80-900, title?, caption?, actions?}`
+
+A widget is for content the fixed components cannot express: a game, a physics/math simulator, a Web Audio instrument, a map, or a custom canvas. `code` is an HTML fragment or a complete document. It runs in an iframe with:
+
+- `sandbox="allow-scripts allow-forms allow-popups"` (opaque origin; no `allow-same-origin`)
+- CSP: no network; inline scripts/styles and `data:`/`blob:` images or media only
+- no access to the host page, cookies, or local storage
+
+`window.mosaic.action(name, payload)` reaches the model only after a real user gesture inside the widget; set `actions: "programmatic"` when the widget must submit on its own (still capped at 10 calls a minute and 16 KB per payload).
+
+Inside the widget:
+
+```js
+window.mosaic.action('apply', { value: 42 })
+window.mosaic.resize()
+```
+
+The parent passes theme variables as CSS custom properties: `--mosaic-bg`, `--mosaic-text`, `--mosaic-muted`, `--mosaic-border`, `--mosaic-accent`, `--mosaic-success`, `--mosaic-warn`, `--mosaic-danger`, `--mosaic-card`. Use these instead of hard-coded colors.
+
+A visible title and a short caption make the widget easier to scan. Prefer fixed components when a table, chart, or callout expresses the content.
+
+## Actions
+
+A component action sends one user message:
+
+```text
+[mosaic-action] refresh。用户刚刚在界面中触发了动作 "refresh"，请根据组件数据更新回答，并用 dsh-view 输出更新后的界面。 组件数据: {...}
+```
+
+After an action, update the existing view instead of restating the whole answer. Only send an action for work that needs the model or a tool. Sorting, filtering, tabs, quiz grading, copy, and full-screen are local.
+
+## Presentation guidance (optional)
+
+- Use Mosaic when a component makes the answer easier to scan; prose is fine when it does not.
+- Choose the smallest component that carries the structure; avoid decorative cards, repeated summaries, and nested scrolling.
+- Keep the tree under 80 nodes and 6 levels.
+- A malformed fence falls back to the original code block; a widget that fails to boot shows its source and an error strip.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,79 @@
+# Third-party notices
+
+dsh-mosaic itself is released under the MIT License; see [`LICENSE`](./LICENSE).
+
+## Mermaid
+
+`lib/assets/mermaid.min.js` is the **unmodified** official distribution build of
+[Mermaid](https://github.com/mermaid-js/mermaid) **12.2.0**, taken from the npm
+package `mermaid@12.2.0`, file `dist/mermaid.min.js`.
+
+| | |
+| --- | --- |
+| Upstream | https://github.com/mermaid-js/mermaid |
+| Package | https://www.npmjs.com/package/mermaid/v/12.2.0 |
+| License | MIT |
+| SHA-256 | `a8a6a6f805b074a8261a2825c86f99c8054acb3b35f50bb7e24a4f9f2c3c3b9f` |
+| Local changes | none (byte-identical to the published file) |
+
+The MIT text shipped with that release is in
+[`lib/assets/licenses/mermaid.LICENSE`](./lib/assets/licenses/mermaid.LICENSE).
+
+Mosaic only calls the public `globalThis.mermaid` API (`initialize`, `render`) and
+sanitizes the returned SVG before it enters the page; the rendering adapter is this
+package's own source, not part of the bundled file.
+
+## Dependencies bundled inside that Mermaid build
+
+The official build embeds Mermaid's runtime dependencies. All of them are permissive
+except the three marked below; the license text of each ships under
+`lib/assets/licenses/`, so a redistribution carries every required notice.
+
+| Package | Version | License |
+| --- | --- | --- |
+| @braintree/sanitize-url | 7.1.2 | MIT |
+| @iconify/utils | 3.1.7 | MIT |
+| @mermaid-js/parser | 2.0.1 | MIT |
+| @types/d3 | 7.4.3 | MIT |
+| @upsetjs/venn.js | 2.0.0 | MIT |
+| chevrotain | 13.2.0 | **Apache-2.0** |
+| cytoscape | 3.34.4 | MIT |
+| cytoscape-cose-bilkent | 4.1.0 | MIT |
+| cytoscape-fcose | 2.2.0 | MIT |
+| d3 | 7.9.0 | ISC |
+| d3-sankey | 0.12.3 | BSD-3-Clause |
+| dagre-d3-es | 7.0.14 | MIT |
+| dayjs | 1.11.23 | MIT |
+| dompurify | 3.4.17 | **MPL-2.0 OR Apache-2.0** (used as Apache-2.0) |
+| elkjs | 0.12.1 | **EPL-2.0 OR GPL-3.0-or-later** (used as EPL-2.0) |
+| es-toolkit | 1.53.0 | MIT |
+| katex | 0.19.1 | MIT |
+| khroma | 2.1.0 | MIT |
+| marked | 18.1.2 | MIT |
+| roughjs | 4.6.6 | MIT |
+| stylis | 4.4.0 | MIT |
+| ts-dedent | 2.3.0 | MIT |
+| uuid | 14.0.3 | MIT |
+
+What those three obligations mean here:
+
+- **chevrotain (Apache-2.0)** — the Apache text ships and the file is redistributed
+  unmodified, so the NOTICE requirement is met by that text plus the attribution above.
+- **dompurify (MPL-2.0 OR Apache-2.0)** — the Apache-2.0 option is taken; its text ships.
+- **elkjs (EPL-2.0)** — weak, file-level copyleft. The bundled copy is unmodified and
+  its source is available upstream (https://github.com/kieler/elkjs); the EPL text
+  ships. Nothing in this repository incorporates elkjs source, so the MIT license of
+  dsh-mosaic is unaffected.
+
+## Icons and screenshots
+
+`assets/icon.svg`, `assets/icon-180.png` and `assets/screenshots/preview.jpg` were made
+for this project and ship under the same MIT license as the package. The preview image
+is a screenshot of this plugin running in DeepSeek Harness and contains no third-party
+artwork.
+
+## draw.io / maxGraph
+
+No draw.io or maxGraph runtime is bundled. The optional `.drawio` export writes the
+standard mxGraph XML format, so the file opens in [draw.io](https://www.drawio.com/)
+(Apache-2.0). Nothing from those projects is required for the export to work.

package/assets/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Mosaic">
+  <defs>
+    <linearGradient id="m-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1d4ed8"/>
+      <stop offset="1" stop-color="#0f766e"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="url(#m-bg)"/>
+  <rect x="10" y="10" width="20" height="20" rx="5" fill="#ffffff" fill-opacity="0.94"/>
+  <rect x="34" y="10" width="20" height="20" rx="5" fill="#ffffff" fill-opacity="0.72"/>
+  <rect x="10" y="34" width="20" height="20" rx="5" fill="#ffffff" fill-opacity="0.72"/>
+  <rect x="34" y="34" width="20" height="20" rx="5" fill="#ffffff" fill-opacity="0.46"/>
+</svg>

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-mosaic bundle patch: insert this package's own row.
+# It touches no other entry, so a user composition decides which plugins run.
+- insert:
+    - id: mosaic
+      name: dsh-mosaic
+      config: {}
+      # Override the contributed model prompt here, e.g.:
+      #   config:
+      #     prompt: 'Only render a dsh-view fence when a table or chart helps.'
+      #      logLevel: debug   # debug | info | warn | error (diagnostic JSONL verbosity)

package/docs/catalog-entry.example.yml

@@ -0,0 +1,9 @@
+# Submit this file to https://github.com/awesome-dsh-plugin/awesome-dsh-plugin
+# as data/plugins/imwhatiam__dsh-mosaic.yml after the GitHub repo exists.
+url: https://github.com/imwhatiam/dsh-mosaic
+name: imwhatiam/dsh-mosaic
+category: ui
+description:
+  en: 'Renders structured visual answers in DeepSeek Harness: metrics, charts, tables, diagrams, media and interactive widgets, with one compact visual style, an editable model prompt, and local-first interactions.'
+  zh: '为 DeepSeek Harness 渲染结构化可视化回答：指标、图表、表格、流程图、媒体和交互组件；提供一套紧凑视觉风格、可编辑的模型 Prompt，交互默认在浏览器本地完成。'
+icon: https://raw.githubusercontent.com/imwhatiam/dsh-mosaic/main/assets/icon-180.png

package/docs/publishing.md

@@ -0,0 +1,29 @@
+# Publishing dsh-mosaic
+
+## Before the first public release
+
+1. Create the GitHub repository. Add the topic `dsh-plugin`; the catalog's automated check looks for it.
+2. Fill `repository`, `homepage`, and `bugs` in `package.json` after the repository URL exists.
+3. Keep at least one version published on npm before submitting to the catalog. The package version tracks the most recently verified DeepSeek Harness version (`0.2.1` today); plugin-only fixes bump the patch number until the next Harness verification realigns it. `npm pack --dry-run` must include `lib/assets/mermaid.min.js`, `screenshots.json`, and `assets/screenshots/`.
+4. Add the repository to the catalog with `docs/catalog-entry.example.yml` copied to `data/plugins/imwhatiam__dsh-mosaic.yml` in `awesome-dsh-plugin/awesome-dsh-plugin`. One entry per PR; the repo must be at least one day old.
+5. Add real screenshots under `assets/screenshots/` and list them in `screenshots.json`. Verified against installed DSH 0.2.1-rc.5: the Plugins page reads only `meta.title`, `meta.description` and the icon, so `screenshots.json` is a **catalog/community** convention, not a DSH one. Keep the paths inside the package and in sync with the filenames.
+6. The catalog `icon` must be a GitHub-hosted raster image. This repo ships `assets/icon-180.png`; SVG is rejected by the catalog.
+7. Do not edit the generated catalog README by hand. Change only your YAML entry.
+8. The README preview uses an absolute `raw.githubusercontent.com` URL because npm does not resolve relative images. In-app detail documents (`meta.detail` + `docs/DETAIL.md`) are a newer-host feature and are deliberately not declared for 0.2.1-rc.3.
+
+## Repository hygiene
+
+- Do not commit `node_modules/`, `.pnpm-store/`, `tests/`, `.DS_Store`, or build/tarball artifacts. `.gitignore` covers the usual cases.
+- Keep `LICENSE`, `THIRD_PARTY_NOTICES.md`, and the Mermaid asset attribution in the repository.
+- The bundle patch only inserts the plugin's own row; it never disables or patches another package. If a user runs two fence renderers, that is their composition to resolve.
+- The Mermaid asset is a lazy 3.2 MB JavaScript file. It is included in the npm tarball but not requested until a flowchart or sequence appears.
+- The widget is an opaque-origin sandbox with no network. Do not add a network-backed script to it.
+
+## Release checks
+
+```sh
+npm test
+npm pack --dry-run
+```
+
+The package is unscoped `dsh-mosaic`; npm returned 404 for that name on 2026-10-29, but recheck before publishing. If it is taken, use your npm scope and update the install command in the README and the catalog entry.

package/lib/assets/licenses/braintree-sanitize-url.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Braintree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.