# 部署与资源

保留本地引擎资源，区分服务端模型和浏览器渲染，并验证生产策略。

## 浏览器与 SSR

`@quirekit/text-diagram` 根入口是纯模型与模板。SVG / PNG 渲染、CodeMirror 和弹窗运行在浏览器，不能在 Nuxt 服务端 setup 中执行。工作台放在 `ClientOnly` 或 `.client.vue` 边界，服务端可使用已保存 PNG 显示占位图。Nuxt 的 [ClientOnly 文档](https://nuxt.com/docs/4.x/api/components/client-only)说明了客户端挂载边界。

本站使用 docs-kit 的客户端示例边界，静态构建依然输出教程和 API 正文，不把整个文档站退化成空白 SPA。

## 引擎资源必须一起部署

Mermaid 按需加载。PlantUML 官方 JavaScript 核心和 Graphviz WASM 打包在 `@quirekit/text-diagram` 的 `dist/diagram-frame.iife.js` 中，由包内 `new URL(..., import.meta.url)` 引用。

让打包器处理并发布该文件；不能只复制 `browser.mjs` 而丢掉资源，也不要把资源路径替换成一个远程渲染服务。Vite / Nuxt 构建后检查静态目录含有该资源，并从最终静态产物实际打开 PlantUML、DOT 各一张图。首次使用需要加载站点脚本，本地渲染不等于网站自动具备离线缓存。

## CSP 与图片

PlantUML / DOT 运行在只开放脚本的 `srcdoc` sandbox frame 中，没有 `allow-same-origin`。frame 内策略只允许打包引擎所在源、WASM 执行和所需内联样式，禁止连接网络；应用更严格的父级策略仍可能阻止加载。

部署时逐项验证宿主的 frame、脚本源、WASM 与样式策略；工作台的 SVG 预览需要 Blob 图片，PNG 为 `data:image/png`。不要直接复制一条宽泛的 CSP 来放开整个应用。若策略不允许这些能力，保留源码/已保存预览，提示编辑不可用。

## 许可产物

两个 QuireKit 包为 MIT。分发打包资源时保留包附带的 `LICENSE.md`、`THIRD_PARTY_NOTICES.md` 和绘图库的 `ENGINE_LICENSES.txt`；第三方引擎仍适用其各自许可。本站从包内原文自动生成 `/licenses/engines.txt`、`/licenses/text-diagram.txt` 与 `/licenses/third-party-notices.txt`，随静态产物一起分发。

## 本站开发与静态预览

在仓库根目录使用 Node 22 和 pnpm：

```sh
pnpm --filter @quirekit/text-diagram-docs dev
pnpm --filter @quirekit/text-diagram-docs typecheck
pnpm --filter @quirekit/text-diagram-docs build
pnpm --filter @quirekit/text-diagram-docs test:browser
```

固定预览为 `http://127.0.0.1:3260/`，端口占用时直接失败。`build` 输出 `apps/text-diagram-docs/.output/public`，包括双语页面、raw Markdown、`llms.txt`、完整示例源码和引擎资源。规划域名为 `text-diagram.quirekit.com`，当前交付不代表域名或 npm 已上线。