@xpert-ai/plugin-live-dashboard 0.3.1 → 0.4.1

package/docs/docs.json

@@ -16,6 +16,13 @@
             "group": "接入与验证",
             "pages": [
               "index",
+              "quick-start",
+              "superstore",
+              "visual-styles",
+              "visual-styles-acceptance",
+              "trend-workspace",
+              "trend-workspace-acceptance",
+              "quick-start-acceptance",
               "html-mode",
               "frontend-libraries",
               "frontend-libraries-acceptance",

package/docs/frontend-libraries.mdx

@@ -1,16 +1,16 @@
 ---
 title: "固定前端图库"
-description: "ECharts、Three.js 的受控注入、版本快照和 Binding 边界。"
+description: "ECharts、Three.js 与三种可选视觉主题的受控注入、版本快照和 Binding 边界。"
 ---
 
 ## Agent 使用方式
 
 调用 `dashboard_libraries` 读取可用库的精确版本、全局名称、摘要和能力说明。
-当前打包 ECharts 5.6.0（`window.echarts`）与 Three.js 0.185.1（`window.THREE`）。
+当前打包 ECharts 5.6.0（`window.echarts`）、Three.js 0.185.1（`window.THREE`），以及三个 1.0.0 主题：Trend Workspace（`window.TrendWorkspace`）、Profit Atlas（`window.ProfitAtlas`）和 Customer Brief（`window.CustomerBrief`）。
 创建 HTML 看板时传入 `libraries: ["echarts"]`；不使用库时省略。
 已有看板先 `dashboard_open`，读取原 HTML，再 `dashboard_update`。
 修改工具省略 `libraries` 会保留原依赖；显式传入完整列表表示增加、移除或升级依赖。
-打包库在作者代码执行前已加载，不要重复加载相同库或复制库源码。在线依赖可使用 script/link 标签，来源须在 dashboard_libraries.online 的对应资源类型白名单内；Tailwind CDN 可使用 https://cdn.tailwindcss.com/3.4.17。在线资源不填写到 libraries 数组中。
+打包库在作者代码执行前已加载，不要重复加载相同库或复制库源码。在线依赖可使用 script/link 标签，当前验收阶段不限制域名，策略见 dashboard_libraries.online；Tailwind CDN 可使用 https://cdn.tailwindcss.com/3.4.17。在线资源不填写到 libraries 数组中。
 
 ```javascript
 const chart = echarts.init(document.querySelector('#chart'), null, { renderer: 'svg' })
@@ -50,8 +50,16 @@ WebGLRenderer 需要浏览器提供 WebGL2，必须处理 GPU 不可用并释放
 未知库、缺失的依赖锁或被篡改的源码会被拒绝，运行时异常会阻止保存。
 包中附带 ECharts 的 LICENSE/NOTICE 和 Three.js LICENSE。
 
+## 可复用企业主题
+
+使用 `libraries:["echarts","trend-workspace"]` 可复用浅蓝 KPI 侧栏、精致筛选器和图表主题。`window.TrendWorkspace.enhanceSelect(select)` 提供键盘可用的双层标签下拉，`window.TrendWorkspace.charts` 提供趋势、排名和散点图配方。布局类名和字段参数见技能的 `themes/trend-workspace/README.md`。
+
+盈利分析可选 `libraries:["echarts","profit-atlas"]`；客户报告可选 `libraries:["echarts","customer-brief"]`。每个文档只使用一个主题库，重复或混合主题请求会被拒绝。三套主题共享筛选与查询契约，布局与色彩各自独立，详见[视觉风格](/visual-styles)。
+
+主题只提供样式和展示组件，不提供业务数据或替代 SDK 查询。Agent 仍负责业务 HTML、指标口径、Binding 与筛选联动。主题代码随 Artifact 固定，旧看板不会因插件升级自行变样；图标的 Lucide ISC 许可也随包保留。
+
 ## 查询权限
 
 图库只处理已返回的 Dataset。页面仍只能通过 `xpertLiveArtifact` 指定已保存的 Binding ID 和控件值。
-在线脚本、样式和字体使用独立的 HTTPS CDN 白名单，预检和实际页面规则一致。在线资源必须在保存和查看时可访问，内容不会随 Artifact 冻结。数据网络请求、Provider 覆盖、SQL、宿主存储或其他 View Actions 仍不开放。
+当前验收阶段开放在线脚本、样式、字体、图片及 fetch/XHR，不限制域名；预检和实际页面规则一致，浏览器 CORS 和混合内容规则仍然适用。在线资源必须在保存和查看时可访问，内容不会随 Artifact 冻结。平台业务数据仍通过 Binding 查询；页面不能覆盖 Provider、提交 SQL、读取宿主存储或调用未授权的 View Actions。
 服务端继续按当前用户授权查询，旧版本不能恢复已撤销的数据访问权限。

package/docs/html-mode.md

@@ -39,7 +39,7 @@ HTML 字节、数据 Binding 和 Controls 处于同一内容哈希和版本中
 
 ## Agent 与浏览器
 
-HTML 模式复用标准看板的 discovery/preview 证据，不允许通过编写 HTML 绕开预览或最终 Provider 策略。`sandbox_write_file` / `sandbox_edit_file` 只编辑文件；已有看板通过 `dashboard_update` 保存草稿，新看板的 `dashboard_create_html` 读取真实文件、验证格式及大小并保存。所有文件访问通过平台 WorkspaceFiles 能力。保存前由 `HtmlDashboardValidation` 检查 Browser Action 与后台执行池健康，将真实默认查询结果和 HTML 放入私有临时文件；队列只携带验证任务 ID。插件 Action 在平台 Browser Runtime 中执行相同的页面宿主，使用同一 HTTPS CDN 资源白名单，检测初始查询、未声明 Binding、脚本异常和空页面。失败结果返回 Agent，当轮修复后可重试，Artifact 创建发生在校验通过之后。标准 JSON 看板不经过此步骤。
+HTML 模式复用标准看板的 discovery/preview 证据，不允许通过编写 HTML 绕开预览或最终 Provider 策略。`sandbox_write_file` / `sandbox_edit_file` 只编辑文件；已有看板通过 `dashboard_update` 保存草稿，新看板的 `dashboard_create_html` 读取真实文件、验证格式及大小并保存。所有文件访问通过平台 WorkspaceFiles 能力。保存前由 `HtmlDashboardValidation` 检查 Browser Action 与后台执行池健康，将真实默认查询结果和 HTML 放入私有临时文件；队列只携带验证任务 ID。插件 Action 在平台 Browser Runtime 中执行相同的页面宿主，使用同一临时开放网络策略，检测初始查询、未声明 Binding、脚本异常和空页面。失败结果返回 Agent，当轮修复后可重试，Artifact 创建发生在校验通过之后。标准 JSON 看板不经过此步骤。
 
 验证任务在 `sandbox-browser` 池执行，使用平台资源限制、超时、取消和销毁。短期任务引用与小型报告存于插件独立 Redis 键（5 分钟 TTL），HTML/数据不进入队列；输入/输出临时文件在完成后删除。保存版本的 metadata 保留 Sandbox Job ID 和已请求 Binding ID。真实数据权限仍由保存/查询时的 Analytics Runtime 重新检查。
 
@@ -55,7 +55,7 @@ await live.ready()
 await live.query('sales', { region: null })
 ```
 
-页面可以使用任意内联 HTML/CSS/JS、DOM/SVG/Canvas。字段、精度、粒度、单位和完整性来自 Dataset；业务事实不能硬编码在页面里。允许的在线脚本、样式和字体来源见 dashboard_libraries.online，包括 Tailwind CDN。fetch/WebSocket、外部图片、eval、宿主 DOM、Web Storage、嵌套 iframe 和自导航仍不开放。在线资源加载失败会阻止保存；建议固定版本，在线资源内容不纳入 Artifact 的不可变快照。宿主的查询权限检查独立于前端限制。
+页面可以使用任意内联 HTML/CSS/JS、DOM/SVG/Canvas。字段、精度、粒度、单位和完整性来自 Dataset；业务事实不能硬编码在页面里。当前验收阶段开放网络资源，策略见 dashboard_libraries.online，包括 Tailwind CDN、字体、图片和 fetch/XHR。浏览器 CORS 和混合内容规则仍适用；eval、宿主 DOM、Web Storage 和自导航仍不开放。在线资源加载失败会阻止保存；建议固定版本，在线资源内容不纳入 Artifact 的不可变快照。宿主的查询权限检查独立于前端限制。
 
 页面滤镜触发带控件值的新查询；宿主刷新沿用各 Binding 最近的值，订阅重绘并保留页面状态。同一 Binding 的过期响应不覆盖新响应。保存重开使用固定页面版本并执行最新数据查询。
 
@@ -68,7 +68,7 @@ await live.query('sales', { region: null })
 ## 当前范围
 
 - 单文件 HTML（300 KB）、含依赖的版本包最大 9 MB；8 个 Binding、24 个控件。
-- 支持原生绘图与插件打包的 ECharts、Three.js 核心库；在线资源仅允许声明的 HTTPS CDN。
+- 支持原生绘图与插件打包的 ECharts、Three.js 核心库；当前验收阶段在线资源不限制域名。
 - 刷新为查询最新来源，未提供服务端推送/定时轮询。
 - Artifact 当前仍为 owner-only；没有扩大分享权限。
 - 保存预检覆盖初始渲染与查询协议；不证明任意图表业务口径、延迟执行分支或所有交互都正确，仍需真实浏览器验收。

package/docs/quick-start-acceptance.mdx

@@ -0,0 +1,50 @@
+---
+title: 快速上手验收
+description: 2026-11-01 应用初始化、配方制作和真实项目内看板验收记录。
+---
+
+## 范围与环境
+
+2026-11-01，在本地源码平台、当前组织和隔离验收项目内验证。相关仓库先拉取当前分支并按锁文件安装依赖，重启 API、Cloud 和 ChatKit，确认服务健康后测试。数据全部为配方中明确标注的合成演示文件，不代表客户业务。
+
+## 应用与入口
+
+- 在 Explore 实际初始化应用，生成私有配置工作空间和制作助理；重复初始化复用原实例。
+- 模板及技能更新通过平台应用更新流程发布；Live Dashboard 和 Analytics Files 已加载。
+- 实际 ChatKit 展示四个开场提示，空白 Live Dashboard 展示三个样例和真实数据入口；左右两侧项目一致。
+- 修正助理目录 DTO 遗漏开场配置与项目类型的问题，只传递公开展示字段，内部提示词、模型配置和工作空间成员仍被过滤。
+
+## 真实助理与数据验收
+
+区域销售、销售总览通过真实助理执行；生产质量从 Live Dashboard 的“体验样例”按钮实际发起。流程包含技能读取、项目文件、注册或复用授权 file.table 定义、发现、预览、两个筛选验证及草稿保存。三个最终会话均正常结束，草稿修订为 1，正式版本列表为空。
+
+| 配方 | 全部 | 筛选 A | 筛选 B |
+| --- | --- | --- | --- |
+| 区域销售 | 销售额 50,000 | East 12,000 | West 18,000 |
+| 销售总览 | 销售额 76,000；订单 380 | East 44,000；220 | West 32,000；160 |
+| 生产质量 | 产量 720；良品 690；不良品 30；良品率 95.83% | Line A：330 / 317 / 13；96.06% | Line B：390 / 373 / 17；95.64% |
+
+对三个已保存 Artifact 通过有项目范围的 View API 重查“全部 → A → B → 全部”，结果完整且与上表一致。生产质量另在实际 Chrome 页面操作相同筛选，核对指标、趋势、对比图、明细与刷新后的筛选保持，保存界面截图。单独的截图和回执保存在本地验收证据中，不随插件发布私有环境标识。
+
+## 发现与修复
+
+首次制作暴露执行步数不足，已为制作模板配置有限的 300 步和 48 次模型调用预算。配方明确成功保存即结束，避免无意义的再次打开和保存；权限、预览和保存回执保护保持有效。
+
+首次短提示的生产质量试跑误用了项目中既有销售数据，该结果判定失败并移入回收站。入口已明确指定完整配方、随附数据和业务指标，禁止替换为其他看板。更新后重新从按钮发起，使用正确生产质量数据并通过上述验收。模型中间曾提交不合法文件路径，路径保护拒绝后由助理纠正；最终成功不代表取消工具输入校验。
+
+## 自动化与包验证
+
+- Live Dashboard：190 项测试通过，包括入口发送、目标清空、模板依赖、保存保护及有界调用预算。
+- 平台助理目录：3 项范围测试通过，确认展示字段可用且内部字段不泄露；同一修复同步到社区版与本地验收版。
+- 三个样例使用真实文件查询实现和 Chromium 验证；HTML 样例还验证文档 SDK、预检、刷新、空结果、不完整结果、查询错误清空与 390px 窄屏。
+- 元数据检查、插件生命周期加载和实际打包后的 Sandbox Action / 前端库校验通过。
+
+本次未进行新的企业 SSO、真实 Data Xpert 本体数据或生产部署验收；这些不能由合成文件场景推定。正式发布、跨项目分享和定时巡检不属于本次快速上手验收。
+
+## 开场入口分级与短名称复验（2026-11-01）
+
+通过应用更新流程原位更新已安装助理。在 ChatKit 当前项目的新对话中，开场提示依次为区域销售、销售总览、生产质量（均标注“入门”）、Superstore 企业分析（标注“进阶”），以及使用我的数据。空白看板页按相同顺序展示样例。
+
+实际点击聊天中的“区域销售 · 入门”，已持久化的用户消息与模板原有 144 字制作指令逐字一致，保留完整配方、演示数据、两个筛选验证、只保存草稿及不发布等要求。真实助理完成制作并返回新草稿；打开结果卡片后，在界面验证 West 为 18,000、East 为 12,000，刷新及清空筛选恢复四个区域正常。
+
+本轮插件 194 项测试通过，平台开场映射、设置保存、缓存及公开目录共 52 项相关测试通过；Angular 编译、API 构建、插件生命周期及包内容检查通过。本轮只重新生成区域销售草稿，未重新制作 Superstore 或另外两个入门样例；它们的既有验收记录保持上述范围。

package/docs/quick-start.mdx

@@ -0,0 +1,64 @@
+---
+title: 快速开始与样例
+description: 初始化实时看板应用，在当前项目使用演示数据或真实来源制作看板。
+---
+
+## 初始化应用
+
+在 Explore 中选择实时看板应用，按平台引导配置主模型并初始化。应用使用 `live-dashboard-assistant` 制作模板，创建专用的私有配置工作空间并发布助理。默认不创建知识库，不要求嵌入模型。
+
+制作模板依赖 Live Dashboard、Analytics Files 插件及 `live-dashboard` 技能，启用 SandboxFile 和 Sandbox。平台会检查依赖与模型就绪状态；浏览器 Sandbox 不可用时，HTML 看板预检不能完成。看板巡检模板仍是单独的可选模板，不在首次制作引导中安装。
+
+进入 ChatKit 后选择或创建实时看板项目。项目选择与 Live Dashboard 视图保持双向同步，文件和看板均归属当前项目。初始化应用不授予项目、文件、数据库或本体资源的额外访问权限。
+
+## 从样例制作
+
+### 在哪里预览
+
+- **先看效果图**：打开 Explore → 实时看板 → 应用详情。首图为应用封面，随后展示 Trend Workspace、Profit Atlas、Customer Brief 三种进阶风格的原型预览；这三张图对应 Superstore 企业分析的设计方向。
+- **体验筛选和刷新**：进入实时看板助理，选择或创建项目，在开场提示或空白看板页点击对应的“体验样例”。助理生成并保存草稿后，打开结果卡片即可操作筛选、查看明细和刷新数据。
+- **再次打开已有样例**：在 Live Dashboard 顶部的项目／看板级联选择器中，选择制作时使用的项目及对应看板，并进入工作草稿。无需重新生成。
+
+详情页图片是静态预览；可交互看板在所选项目内生成。HTML 样例依赖平台提供的数据 Binding 和文档 SDK，不能通过直接双击 `dashboard.html` 获得相同运行效果。
+
+### 选择样例
+
+助理开场提示和空白看板页提供以下入口；级联选择器中的“新建看板”也会进入同一空白页。
+
+| 样例 | 形式 | 学习内容 |
+| --- | --- | --- |
+| 区域销售 · 入门 | 标准图表 | 区域筛选、柱状图、明细表 |
+| 销售总览 · 入门 | HTML / ECharts | 销售额、订单数、日趋势、区域对比 |
+| 生产质量 · 入门 | HTML / ECharts | 产量、加权良品率、不良品与产线筛选 |
+
+| Superstore 企业分析 · 进阶 | 三种 HTML / ECharts 风格 | 经营总览、商品盈利、客户与退货；需已授权的 Data Xpert 发布模型 |
+
+三个入门样例优先显示。聊天开场仅显示上述简短业务名称，点击后仍发送完整制作指令，包括配方、数据要求、筛选验收、保存草稿和不发布约束；编辑开场提示时可分别维护显示名称和完整指令。
+
+“体验样例”向当前项目的助理发送明确的演示制作请求。助理按需读取技能中的配方，复制标注为演示数据的 CSV 或 JSON，通过 Analytics Files 注册和预览真实文件查询，然后沿用现有创建工具保存草稿。它不是直接导入一个带旧数据源 ID 的 Artifact。
+
+三个入门配方位于 `skills/live-dashboard/examples/<key>/`，含预览图、业务说明、源码、字段定义、查询要求、CSV/JSON 和预期结果。数据为人为构造，预览不代表用户业务数据。
+
+样例版本更新不会覆盖用户已经创建的文件或看板。相同路径存在不同内容时应使用新文件名。修改已有看板继续使用精确 Artifact 与草稿修订校验。
+
+## 使用真实数据
+
+选择“使用我的数据”，由助理检查当前项目已授权的文件、数据库或 Data Xpert 本体资源。先确认指标口径、粒度、单位和字段映射，再预览、绑定和制作。缺少字段、权限不足或查询失败时不得以演示数据补齐。
+
+演示页只有在所有绑定及可见数值均已替换为验证过的真实来源后才能移除演示标识。生产良品率按良品数合计除以产量合计计算；零分母显示无值。金额样例使用整元，适配小数或高精度货币时需要相应的精确计算策略。
+
+## 验证和发布
+
+制作完成后核对当前项目、默认结果、两个筛选项、恢复全部及工具栏刷新。图表、指标与明细须一致；空结果、不完整结果和查询失败应清晰显示，不能将旧值当作当前结果。
+
+保存回执表示草稿已经持久化。正式发布继续由项目管理者在现有 Workbench 流程中确认。
+
+## 维护样例
+
+样例目录由 `examples/catalog.json` 管理。新增配方须提供独立 key、版本、完整源码、预览、字段与指标说明、演示文件和预期结果。示例按业务语义匹配；生产质量不能用销售数据或改名后的销售看板替代。
+
+HTML 源码按可读行组织，避免文件工具截断长行。业务查询、筛选和明细使用同一完整 Dataset，数据访问继续通过声明式 Binding；浏览器不直接访问数据库。演示数据刷新意味着重新读取项目文件，并非自动推送更新。
+
+运行 `corepack pnpm test` 检查模板、依赖、入口与原有权限和保存流程。构建 Analytics Files 后，在 Live Dashboard 包目录运行 `node tests/example-browser.mjs <platform-root>`，通过实际文件查询实现、文档 SDK 和 Chromium 验证数据、图表、筛选、刷新、空结果、异常和窄屏；`--screenshots` 更新配方预览。该受控测试不能替代部署后的助理与界面验收。
+
+制作模板为读取配方、准备数据源和筛选检查预留有限执行预算；模型调用上限为 64，图执行步数上限为 300。其他未配置的 LiveDashboard 中间件仍采用 24 次模型调用上限，保存回执、预览和 HTML 预检要求不变。成功保存后结束制作，不为确认同一次保存而再次打开和更新未改动的看板。

package/docs/superstore.mdx

@@ -0,0 +1,38 @@
+---
+title: Superstore 企业 BI 样例
+description: 使用官方零售教学数据，在项目中制作经营总览、商品盈利和客户退货分析。
+---
+
+Superstore 企业 BI 提供一个完整的零售分析案例。数据来自 Tableau 官方教学工作簿，包含 2021–2024 年的 10,194 个订单行、5,111 个订单与 804 个客户，属于虚构演示数据。
+
+## 查看效果
+
+在 Live Dashboard 的样例入口选择 **Superstore 企业分析**。管理员完成下述数据准备后，助理会在当前 ChatKit 项目保存三个草稿；通过聊天回执卡片或顶部项目/看板级联选择器打开：
+
+- **零售经营总览**：经营 KPI、月度趋势、区域销售贡献和品类明细。
+- **商品盈利分析**：子品类利润排序、销售与利润关系以及亏损标识。
+- **客户与退货分析**：客户分群、客单价、退货订单占比与关联销售额。
+
+年份、区域、品类筛选会更新当前看板全部图表与指标。三个草稿的筛选状态独立，项目归属与 ChatKit 同步。原来的三个入门样例继续保留。
+
+三张企业看板采用[不同视觉风格](/visual-styles)：总览使用 Trend Workspace 浅蓝指标侧栏，盈利页使用 Profit Atlas 深色分析台，客户页使用 Customer Brief 暖色报告；共同保留双层标签筛选器。通用 CSS、选择器、图表组件和组合说明随技能安装，Agent 可据此制作同风格的其他业务看板。已有草稿需要明确要求 Agent 升级样式；更新助理模板不会自动覆盖它们。
+
+## 管理员准备数据
+
+安装 Data Xpert analytics provider，并为工作空间绑定有权限的 PostgreSQL 数据源。使用插件技能目录 `examples/superstore/orders.csv` 及 `import.json` 导入一个新表，再按 `semantic-model.json` 建立、验证并发布 SQL 语义模型。
+
+发布模型需要一个可访问的业务域；为实时看板助理绑定发布后的本体资源及只读查询权限。安装 App 本身不会授予数据权限。完整步骤、动态 Binding 查询计划与预期结果位于该目录的 README。
+
+数据通过 Data Xpert 已发布本体资源实时查询，页面内不包含业务数据快照。当前环境未准备模型时，助理会说明缺少的数据接入，不替换为少量演示行。
+
+## 指标口径
+
+订单数与客户数由后端在当前筛选范围内去重，不能跨月份/品类相加。利润率使用合计利润除以合计销售额。金额单位 USD，保留源数据精度后再格式化展示。
+
+退货原表的 800 行对应 296 个不同订单；导入前去重，避免销售额被关联放大。退货关联销售额并非退款金额，也不是收入损失。页面不展示样例无法支持的预算、库存、净退款或客户流失指标。
+
+## 来源与复现
+
+数据来源为 [Tableau 官方 Data App 示例](https://tableau.github.io/extensions-api/docs/dataapps/trex_dataapp_examples/)，固定版本哈希和 Apache-2.0 许可随样例保留。视觉信息层次参考 [phData 的企业经营看板案例](https://www.phdata.io/blog/building-an-executive-dashboard-in-tableau/)，页面代码为独立实现。
+
+数据重建程序校验原工作簿哈希，产生 CSV、语义模型模板和筛选基准。页面构建程序生成三个自包含 HTML，按 Live Dashboard 技能正常预览与保存。配方升级不会覆盖用户已有看板。

package/docs/team-sharing.mdx

@@ -29,9 +29,13 @@ description: 分享已发布版本，保持数据访问权限、草稿和编辑
 
 分享只授予正式定义的读取权。PostgreSQL/MySQL/Doris 继续使用平台受控查询，data-xpert 继续使用访问者的授权和本体策略；不会使用创建者身份代查。组织成员缺少数据源权限时仍查询失败。
 
-来源插件可在 Provider descriptor 的 `sharing` 声明 `owner_only` 及原因码。Workspace 脚本当前依赖私有定义、脚本和文件 Artifact，因此会阻止开启团队分享。后续应先提供这些依赖的显式协作授权，不能在看板层绕过文件 ACL。
+来源插件可在 Provider descriptor 的 `sharing` 声明 `owner_only` 及原因码。`workspace_script.query` 仍依赖私有定义、脚本和文件 Artifact，因此阻止直接分享。需要分享时，先显式准备固定代码与声明文件的发布包，再由创建者在「设置 → 分析」审阅内容并选择组织可见；用 `workspace_script.published_query` 发现、预览并更新看板绑定，人工发布看板后才可分享。上游查询仍使用当前访问者权限。
 
-独立页只接受已发布的 Artifact/version 目标。刷新仅重查已声明 Binding；前端不能提交 SQL、替换 provider/dataSource、读取草稿或调用发布。HTML 仍运行在隔离环境中；在线脚本、样式和字体仅可从 dashboard_libraries.online 的 HTTPS 白名单加载，数据查询仍须经过 Binding。
+分析定义的可见范围适用于所有历史版本。改回私有后，其他成员后续读取与查询均被拒绝，包括已打开页面中的缓存文件访问；已显示的数据无法收回。私有文件夹不会被共享。
+
+旧看板曾使用通用 file 类型时，创建者重新开启分享会触发受控修复：平台锁定 Artifact，验证所有版本与草稿的摘要、来源身份及现有链接策略，只绑定对应的已注册看板类型，不扩大受众。未注册类型、内容不匹配或权限不足会拒绝修复。需部署包含类型修复钩子的新版平台与插件；仅升级插件不提供历史修复。已授权用户遇到展示能力未加载时，独立页提示能力暂不可用，不再误报为内容不存在。
+
+独立页只接受已发布的 Artifact/version 目标。刷新仅重查已声明 Binding；前端不能提交 SQL、替换 provider/dataSource、读取草稿或调用发布。HTML 仍运行在隔离环境中；当前验收阶段在线资源不限制域名，受浏览器 CORS 和混合内容规则约束，数据查询仍须经过 Binding。
 
 跟随最新版本的链接在重新打开时读取当前正式版本；若页面打开后发布了新版本，旧目标查询会返回冲突，提示重新打开，避免旧 HTML 与新 Binding 混用。筛选值属于当前页面状态，刷新保留，重开恢复定义默认值。刷新仍是主动查询或定义中已配置的轮询，不是服务端推送。
 

package/docs/trend-workspace-acceptance.mdx

@@ -0,0 +1,43 @@
+---
+title: "Trend Workspace 验收"
+description: "共享文档库、技能复现与实际项目看板的验证记录"
+---
+
+## 实现与自动回归
+
+2026-11-01，按用户选定的图 2 和优化后的选择器落地。主题 CSS、图标、选择器、图表实现与 Agent 指南随技能安装，并打包为 `trend-workspace@1.0.0` 受控文档库。三个 Superstore 配方保留业务布局与查询逻辑，不重复输出公共组件。
+
+- 193 项插件测试通过，覆盖依赖库白名单、哈希校验、旧内容锁定、权限和草稿生命周期。
+- 三页生产文档 SDK 浏览器回归通过：初始查询、所有 Binding 共同筛选、刷新、空结果、截断、失败恢复、390px 窄屏及深色模式。
+- 自定义选择器的选中状态、键盘导航、输入定位、确认、Escape、Tab、外部关闭及菜单边界通过。
+- 包构建、产物一致性检查和插件加载 harness 通过。Nx 工作区扫描被其他项目中缺少名称的目录阻断，本包使用现有 package build 命令构建；未修改无关项目。
+
+## Agent 复现路径
+
+在原实时看板助理上从来源模板更新并发布，保持 ID、slug、模型与项目绑定。已安装主题源文件与仓库逐一比对。
+
+首次真实制作发现模型一次输出长 HTML 会产生无效工具参数，未保存草稿。因此将共享主题改成受控文档库，并在技能加入有界精确编辑与分段写入规则。Agent 后续使用正常的读取、SandboxFile 编辑与 `dashboard_update` 保存流程；保存经过宿主预检，开发者没有通过数据接口直接写入业务看板。
+
+第二次实际模型执行完成，三个原 Artifact 均保存为草稿 r2，未新增副本：
+
+| 看板 | 保存结果 | 内容核对 |
+| --- | --- | --- |
+| 零售经营总览 | r2 | 与完整配方逐字一致 |
+| 商品盈利分析 | r2 | 与完整配方逐字一致 |
+| 客户与退货分析 | r2 | 与完整配方逐字一致 |
+
+只读验收重新读取三个保存结果，核对 Artifact ID、标题、全部 Binding 和筛选契约与原 r1 一致。三页使用固定版本的 ECharts 与 Trend Workspace 文档库。验收脚本对全部 Binding 在六个有效筛选范围执行 54 项真实查询比较，与独立数据基准逐行一致。
+
+## 实际 ChatKit 界面
+
+- 通过项目/看板级联选择器逐张打开 r2：浅蓝 KPI 侧栏、分析区、两行选择器、图表和明细正常；原项目联动保留。
+- 总览全量销售额为 2,326,534.35 USD、利润 292,296.81 USD。键盘 End/Enter 选择 West 后，销售额变为 739,813.61 USD、订单 1,635，刷新保留筛选；Home/Enter 恢复全量。
+- 盈利页显示 Tables 负利润 -17,753.21 USD；选择 Furniture 后，销售额 754,747.76 USD，排序图、散点图和明细同时收敛到四个子品类；随后恢复全量。
+- 客户页显示退货订单 296、占比 5.79%；下拉输入定位 East 后变为 44、2.98%，恢复全量后回到原值。
+- 实际截图保存于本地 `.xpert-local-environment/dashboard-style-20261101/actual-*.jpg`，包含菜单展开、West 刷新、三张看板和总览底部。保存结果、54 项查询和 Agent 工具回执存于同一验收目录，不进入发布包。
+
+最终结果：通过。新业务数据的任意布局生成不属于本次验收范围；已验证的是实际 Agent 从已安装技能读取材料、编辑并保存三张既有业务看板，以及组件在完整配方中的运行。
+
+## 验收边界
+
+桌面真实安装验收与生产 SDK 的模拟数据回归分别记录。没有浏览器能力的 Agent 必须说明视觉检查待人工完成，不能只读源码就声称通过截图验收。正式发布看板和提交代码仍由用户决定。

package/docs/trend-workspace.mdx

@@ -0,0 +1,30 @@
+---
+title: "Trend Workspace 视觉主题"
+description: "让 Agent 使用同一套主题和组件制作可查询的企业看板"
+---
+
+Trend Workspace 随 `live-dashboard` 技能安装。它提供浅蓝指标侧栏、独立刻度趋势、排名和明细布局，以及带键盘操作的双层标签选择器。Superstore 经营总览采用这一主题；盈利与客户页采用另外两个[可选视觉风格](/visual-styles)。
+
+## 交给 Agent 制作
+
+在实时看板助理中选择项目，描述业务目标并要求：
+
+> 请读取 live-dashboard 技能的 themes/trend-workspace/README.md，使用该主题制作我的经营分析看板。先发现当前授权数据及指标口径，再组合主题布局、筛选器和图表；使用 echarts 和 trend-workspace 受控文档库，查询真实 Binding，校验全量和筛选结果后保存草稿。
+
+技能包包括 `theme.css`、`icons.js`、`select.js`、`charts.js` 和 `layout.html`。它们是可供 Agent 阅读、组合的源文件；主题同时作为 `trend-workspace` 文档库注入并随 Artifact 固定版本、哈希和内容，不依赖开发者手写每张看板或运行本地 Python 构建器。完整 Superstore HTML 是已组合的参考；用于其他业务时必须重新匹配字段、粒度、单位、筛选允许值和 Binding。
+
+## 已有看板的视觉升级
+
+先明确目标看板，让 Agent 读取当前定义、草稿修订与 Binding，再按主题调整布局。保留 Artifact ID、组件 ID、数据源、筛选参数及权限，使用当前修订保存更新。模板更新只更新助理技能和说明，不自动覆盖已有看板。
+
+## 交互与数据边界
+
+- 筛选器支持鼠标、方向键、Home/End、输入定位、Enter、Esc 和 Tab；移动高亮不发起查询，确认选项才应用。
+- 选择器保留原有 `data-dashboard-control` 和类型化值；一个筛选共同更新指标、图表与明细。
+- 主题提供浅色、深色、窄屏、加载、空结果与失败状态；失败或不完整数据清空旧结果。
+- 销售额与利润分开绘图，使用相同时间轴和各自金额刻度。负利润使用红色和明确数值，不依赖颜色单独表达。
+- 金额、时间、业务口径来自查询和元数据。主题不提供虚构增幅、目标或结论。
+
+## 维护方式
+
+修改通用主题后，开发者重建受控文档库并验证三个 Superstore 配方。Agent 不必反复输出通用 CSS/JS；长业务页面必须分段写入或使用有界精确编辑，避免模型输出截断。Agent 面向用户制作时直接读取已安装资源；技能、助理模板和配方作为一个版本发布。

package/docs/verification.mdx

@@ -37,11 +37,13 @@ node tests/html-preflight-browser.mjs /absolute/path/to/platform
 node tests/workbench-browser.mjs /absolute/path/to/platform /private/screenshot.png
 ```
 
-开发依赖固定使用已发布的 SDK/contracts 3.27.0，构建无需本地平台链接或 SDK 补丁。
+当前工作区与 Live Dashboard 使用已发布的 SDK/Contracts 3.30.0，直接使用其文档联网策略和 Artifact Content 能力，不再需要 SDK 补丁或本地平台类型映射。
 升级 SDK 后须重新构建页面和 HTML 预检资源，运行 `verify:dist`，并用
-`tests/html-online-browser.mjs` 验证真实 CDN 加载、样式、刷新及离线失败诊断。
+`tests/html-online-browser.mjs` 验证真实 CDN 加载、样式、刷新及断网诊断。临时开放策略由 `tests/html-resources.test.cjs` 覆盖；网络策略后续单独设计。
 分批提交审核在临时快照构建和测试，不覆盖运行中的 dist，也不重新部署或重跑 SSO。
 
+临时在线验收还需在本地平台 `.env` 设置 `XPERT_BROWSER_ACCEPTANCE_NETWORK=unrestricted` 并重启 API/Worker。该开关只在 development/test 对通用 Browser Runtime 生效，Docker 预检使用 bridge 网络；生产环境和其他 Runtime 不变。移除此开关并重启可恢复预检默认断网策略。浏览器与容器必须都能访问资源 URL；容器中的 localhost 指向容器自身。页面 CORS、混合内容和项目/数据源权限校验继续适用。
+
 真实验收使用 `verify-installed-dashboard.mjs` / `verify-installed-html.mjs`，
 传入私有上下文与独立业务 oracle。固定日期的历史模型、SSO 与页面交互结果
 保留在历史验收文档中，不应当作本次暂存代码的重新部署证明。

package/docs/visual-styles-acceptance.mdx

@@ -0,0 +1,40 @@
+---
+title: "视觉风格验收"
+description: "Profit Atlas 与 Customer Brief 的构建、SDK、实际 Agent 和界面验收记录。"
+---
+
+## 2026-11-01 — 通过
+
+用户确认两张独立原型后，新增 Profit Atlas 与 Customer Brief；经营总览保持 Trend Workspace。以下为本轮结果，不替代历史验收记录。
+
+## 构建与生产 SDK
+
+- Nx 构建、插件 metadata、插件加载 harness 和 `verify:dist` 通过；194 项自动化测试、5 项数据基准检查通过。
+- 生产 Artifact Document SDK 的三页浏览器回归通过：完整 HTML 预检、区域/年份/品类筛选、所有 Binding 更新、刷新、空结果、截断、失败与恢复、键盘、390px 窄屏、深色模式与菜单边界。页面错误记录为空。
+- 对照用户原型和 1440px 实现，检查字体、布局、颜色、图形与业务内容。修复散点标签靠近横轴和客户页初稿字号偏小的问题，重验通过。
+- 实际打包后的 45 个主题、配方、截图和文档文件与源码匹配；包内 Sandbox Action 与文档库通过内容校验。
+- 总览 HTML、已有 ECharts/Three.js/Trend Workspace 库的原始内容未改变。新增主题可选，每个文档最多选择一种主题；混合主题请求被校验拒绝。
+
+这一层使用独立数据基准提供查询响应，证明渲染与生命周期；真实安装验收见下文。
+
+## 安装与实际 Agent
+
+- 拉取当前分支、安装冻结依赖、重启对应本地服务后验收；插件通过平台部署流程刷新，API 重启后健康检查和实际 View 通过。
+- 在原实时看板助手画布执行“从模版更新”，复核后发布同一助手版本。助手身份、模型、工作空间与 API/App 访问设置不变。安装后的主题指南、组件与完整配方逐字匹配源码。
+- 平台真实 Agent 阅读技能与完整配方，分别打开两张原看板、编辑当前 HTML 副本并执行 `dashboard_update`。本轮 16 次工具调用无错误，两个保存回执均成功；没有由开发者直接写入业务 Artifact。
+- 商品盈利分析更新到草稿 r3，使用 ECharts + Profit Atlas；客户与退货分析更新到草稿 r3，使用 ECharts + Customer Brief。二者最终 HTML 与对应配方一致。
+- 经营总览保持草稿 r2，保存定义整体与原记录一致；没有创建重复看板或发布正式版。
+
+## 真实数据与界面
+
+- 三张看板、六组全量/区域/年份/品类及组合筛选，共 54 次真实 Binding 查询逐行匹配独立数据基准，未发生截断。
+- 原 Artifact ID、标题、所有 Binding、控件、Data Xpert 定义版本及项目归属保持一致。
+- 实际 ChatKit 中通过项目/看板级联切换两页。盈利页验证键盘选择 West：销售额 739,813.61、利润 110,798.82、订单 1,635、客户 686；刷新保留筛选，随后恢复全量。
+- 客户页验证 East：客户 685、订单 1,475、退货订单 44、退货占比 2.98%；图表与明细共同更新。恢复全量后客户 804、退货订单 296、退货占比 5.79%。
+- 检查已安装页面的配色、字体、菜单、KPI、图表及明细并保存截图。实际数据查询没有改写授权策略。
+
+## 范围与后续
+
+三套主题的可读指南、布局骨架、图表与选择器组件均随技能提供；本轮验证了 Agent 读取已安装资源并升级这两个实际看板。尚未把任意新数据集上的自主设计都列为已验收。
+
+ChatKit 展开视图底部保留既有浮动输入框，页面可滚动浏览完整内容。本次没有修改宿主交互。代码和 changeset 留在工作区供审核，未提交或推送。

package/docs/visual-styles.mdx

@@ -0,0 +1,46 @@
+---
+title: "三种可选视觉风格"
+description: "按分析场景选择主题，让 Agent 复用布局、筛选与图表配方。"
+---
+
+Live Dashboard 的主题是可组合的展示能力。业务数据仍来自当前项目授权的 Binding，主题不提供数据、结论或权限。
+
+| 风格 | 适合场景 | 结构与色彩 | 文档库 |
+| --- | --- | --- | --- |
+| Trend Workspace | 经营总览、时间趋势 | 浅蓝 KPI 侧栏、独立刻度趋势、下方比较与明细 | `trend-workspace` |
+| Profit Atlas | 贡献、利润与亏损分析 | 深石墨底色、横向指标、大散点图、带正负号的排名、亏损优先明细 | `profit-atlas` |
+| Customer Brief | 客户、退货与管理报告 | 暖纸底色、衬线标题、横向指标、分组退货区域、编号比较章节 | `customer-brief` |
+
+Superstore 三页分别展示上述风格，属于同一个案例的三个独立看板。其他业务可选择其中一种，不能仅替换标题而沿用不适用的指标或筛选。
+
+## 在应用详情中预览
+
+打开 Explore 的 Live Dashboard 应用详情，预览区仅展示封面与 Trend Workspace、Profit Atlas、Customer Brief 三张风格原型，可纵向滚动查看。原型展示设计方向；已保存看板通过真实 Binding 渲染数据。
+
+三张原型随插件的 `assets/previews/` 打包，并由 `appConfig.presentation.screenshots` 与 bundle manifest 共同声明。应用卡片继续使用首张封面。
+
+## 交给 Agent 复用
+
+在实时看板助理中选择项目和目标看板，例如：
+
+> 请读取 live-dashboard 技能的 themes/README.md 和 themes/profit-atlas/README.md，使用 Profit Atlas 风格优化当前盈利分析。保留 Artifact、全部 Binding、控件和组件 ID。先读取当前定义与编辑副本，使用 echarts 和 profit-atlas 文档库，验证全量和区域筛选后保存草稿，不发布。
+
+客户报告将指南与主题库换为 `customer-brief`。总览继续使用 `trend-workspace`。没有请求重设计时，Agent 保留当前看板的主题。
+
+每个主题目录包含 CSS、图表组件、布局骨架和使用说明；完整 Superstore 配方展示其组合方法。公共选择器和图标随文档库打包，Agent 不需要复制组件实现或运行开发者构建程序。
+
+调用 `dashboard_libraries` 发现精确版本，再选择 ECharts 和一个主题。保存后，主题代码、版本及摘要随 Artifact 固定；插件升级不会自行改变历史看板。更新已有看板时显式传入新的完整库列表，省略列表则继承原快照。
+
+## 表达与交互
+
+- 三种风格共享类型化选择器：键盘方向键、高亮、确认、关闭、焦点恢复和窄屏边界保持一致。
+- Profit Atlas 始终采用深色画布，正利润为薄荷色，负利润为珊瑚色；金额、负号和零线提供额外信息，不依赖颜色判断。
+- Customer Brief 使用本地衬线字体栈，无外部字体请求；退货占比与订单数放在一起，退货关联销售额不表述为退款或损失。
+- 图表由查询数据绘制。完整明细保留在可滚动区域，不为匹配原型截图而删除数据行。
+- 窄屏重新排列指标与图表；无数据、失败或不完整结果会清除旧值并显示状态。
+
+## 制作边界
+
+助手模板提供主题选择规则和样例入口，不自动更新用户已有草稿。视觉升级通过正常 `dashboard_open` / `dashboard_update` 流程完成，保留项目归属、原 Artifact 与数据契约；保存草稿不等于发布正式版。
+
+模板、技能资源和文档库一同打包。开发者验证构建、生产 Document SDK 和安装后的实际 Agent/UI 工作流；不同层次的验收结果见[视觉风格验收](/visual-styles-acceptance)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-live-dashboard",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Versioned live dashboards using platform analytics and Data Analytics renderer",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",
@@ -16,6 +16,7 @@
     "dist",
     "index.cjs",
     "README.md",
+    "assets",
     "docs",
     "examples",
     ".xpertai-plugin",
@@ -31,33 +32,35 @@
     }
   },
   "peerDependencies": {
-    "@xpert-ai/plugin-sdk": "^3.28.0",
-    "@xpert-ai/contracts": "^3.28.0",
+    "@langchain/core": ">=0.3.0",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
+    "@xpert-ai/contracts": "^3.30.0",
+    "@xpert-ai/plugin-sdk": "^3.30.0",
     "zod": "3.25.67",
-    "@langchain/core": ">=0.3.0"
+    "@langchain/langgraph": "^0.4.7"
   },
   "devDependencies": {
-    "echarts": "5.6.0",
-    "three": "0.185.1",
-    "@xpert-ai/plugin-sdk": "3.28.0",
-    "@xpert-ai/contracts": "3.28.0",
+    "@langchain/core": "0.3.72",
+    "@langchain/langgraph": "^0.4.7",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
-    "zod": "3.25.67",
-    "typescript": "^5.9.2",
+    "@tailwindcss/vite": "^4.3.2",
     "@types/node": "^20.19.9",
-    "reflect-metadata": "^0.2.2",
-    "@langchain/core": "0.3.72",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
     "@types/react": "^18.3.24",
     "@types/react-dom": "^18.3.7",
-    "vite": "^7.3.0",
-    "@tailwindcss/vite": "^4.3.2",
-    "tailwindcss": "^4.3.2",
     "@xpert-ai/community-data-analytics": "0.1.35",
+    "@xpert-ai/contracts": "^3.30.0",
+    "@xpert-ai/plugin-sdk": "^3.30.0",
+    "echarts": "5.6.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "reflect-metadata": "^0.2.2",
+    "tailwindcss": "^4.3.2",
+    "three": "0.185.1",
+    "typescript": "^5.9.2",
+    "vite": "^7.3.0",
+    "zod": "3.25.67",
     "@xpert-ai/plugin-shadcn-ui": "0.2.1"
   },
   "repository": {
@@ -68,6 +71,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "parse5": "7.2.1"
+  },
   "scripts": {
     "verify:dist": "node scripts/verify-dist.mjs && node scripts/build-action.mjs --verify && node scripts/build-libraries.mjs --verify",
     "build": "pnpm --filter @xpert-ai/plugin-shadcn-ui build && node scripts/build-libraries.mjs && tsc -p tsconfig.json && tsc -p tsconfig.remote.json --noEmit && node scripts/build-remote.mjs && node scripts/build-action.mjs",

package/skills/live-dashboard/SKILL.md

@@ -7,9 +7,18 @@ description: Create and continuously edit saved live dashboards, including free-
 
 Use the platform SandboxFile tools to author source files. Use the dashboard tools to validate and save the business document. This skill belongs to the Live Dashboard plugin; data-source-specific query formats remain owned by each provider.
 
+## Quick start and examples
+
+For a first dashboard or a request for examples, read [examples/catalog.json](examples/catalog.json), [the shared workflow](examples/README.md), and only the selected recipe. Offer regional-sales (standard chart), sales-overview (HTML/ECharts), or production-quality (HTML/ECharts). Keep all files and drafts in the currently selected ChatKit Project. Explicit demo requests use labeled synthetic fixtures through a real registered file.table source; otherwise establish demo versus real data before writing. Never silently fill real-data gaps with sample values. Reuse existing authoring and draft tools; sample updates never overwrite existing dashboards.
+
+For enterprise BI, offer [Superstore](examples/superstore/README.md): three full dashboards over the authorized **published Data Xpert SuperstoreOrders model**. This recipe uses `data-xpert.ontology`, not the file workflow above. Keep its fictional teaching-data label. Do not read the entire orders.csv into model context; follow its administrator setup and source discovery. Missing authorization/model is a setup gap, never permission to substitute another sample. Preserve its independent backend totals for distinct orders/customers.
+
+When `dashboard_open` or `dashboard_history` returns `selection_required`, display its message and wait for the user to select a dashboard. This is a normal empty-selection state: do not retry, restore a target from conversation history, or create a replacement.
+
 ## Avoid preventable retries
 
 - New independent dashboards use an unused source-file path. Inspect the target directory when needed; do not overwrite an existing candidate or switch to editing a historical Artifact merely because its title or filename matches.
+- Continue the selected or checkpointed Artifact across turns. Explicit Workbench selection and New override the checkpoint; never infer identity from title or recency. If a target exists, new/copy creation requires the user's explicit request and `creationIntent: "new"` or `"copy"`.
 - A successful save receipt already confirms persistence. Opening or reading the saved dashboard only prepares an unchanged copy; it does not require another save. Update only for an actual requested change or an observed defect. Never save an unchanged copy merely to verify that the previous save worked.
 
 - After preview, execute every `validation.checks[].suggestedCall` before writing HTML. These suggestions use observed rows; only a successful `dashboard_test_filter` is evidence. If no value is suggested, inspect the source for a real value. A changed Binding needs fresh evidence.
@@ -28,10 +37,25 @@ Use the installed SKILL.md path shown in the skill catalog with `read_skill_file
 
 Read [data-validation.md](references/data-validation.md) when creating a dashboard or changing its data/Binding. Read [html-runtime.md](references/html-runtime.md) and its lifecycle example when authoring or changing HTML/JavaScript. Style-only edits preserve the saved Bindings and do not need to reconstruct upstream queries.
 
+## Reusable visual themes
+
+Read the [style selection guide](themes/README.md) before choosing a visual system.
+Trend Workspace is the pale-blue trend overview; Profit Atlas is the dark
+profitability desk; Customer Brief is the warm editorial customer report. They
+have different layouts and chart emphasis, not just different colors. Honor the
+user's choice and preserve an existing theme unless redesign is requested.
+Read the selected theme's guide and complete example, then author and save the
+business page yourself using its installed components and exactly one pinned theme
+library with ECharts. Do not depend on a developer, repository checkout, screenshot
+or an already-created Artifact.
+Use the complete Superstore pages as worked examples, not as a substitute for
+discovering another dataset's fields and validating its metrics. For style-only
+upgrades, follow the theme's existing-Artifact procedure and keep saved bindings.
+
 ## One file editing interface
 
 - Create a new file with `sandbox_write_file({"file_path":"dashboards/sales.html","content":"<!doctype html>..."})`.
-- Read an existing file with `sandbox_read_file({"file_path":"..."})`.
+- Read an existing file with `sandbox_read_file({"file_path":"..."})`. If a long HTML line is truncated, use `dashboard_read_html` with the opened `editId` and follow `nextOffset` until `null` to inspect the saved source; do not repeat the same truncated read or overwrite the editing file with its preview. Apply exact replacements to the existing `htmlPath`.
 - Change existing text with `sandbox_edit_file({"file_path":"...","old_string":"exact old text","new_string":"replacement"})`; use `sandbox_multi_edit_file` for multiple changes.
 - `sandbox_write_file` does not overwrite existing files. Repair the current candidate with edits. If replacing an unsaved creation candidate with a new named file, include the earlier exact path in `supersedesPaths` on `dashboard_create_html` (or `dashboard_create` when choosing standard charts instead); only a successful save abandons that candidate, and files remain in Workspace. Do not abandon editing copies from `dashboard_open`. For a long new document, append subsequent complete segments with `sandbox_append_file` before saving the dashboard.
 - Paths are relative to the current sandbox working directory. Use a real filename (`dashboards/sales.html`), never `.html`, whitespace-only names, absolute paths or guessed host paths. Copy returned paths exactly.
@@ -40,7 +64,7 @@ Read [data-validation.md](references/data-validation.md) when creating a dashboa
 ## Create a new dashboard
 
 1. Call `dashboard_list_sources` before searching raw files, reading old scripts or creating transformations. For a named governed source, inspect that source/provider contract first; file-backed sources do not automatically require a script. Discover the authorized source and business schema. Validate the metric, period, grain, units and filters through real preview results; follow the data-validation reference.
-2. For HTML mode, read the HTML runtime reference and call `dashboard_libraries` before using ECharts, Three.js or online dependencies such as Tailwind CDN. Use only its allowed HTTPS resource origins; online URLs are not entries in the packaged `libraries` array. Write a complete HTML page using SandboxFile. First declare `const live = window.xpertLiveArtifact` inside the page script; `live` is not a host global. Then register `live.subscribe(bindingId, renderDataset)`, await `live.ready()`, then call `live.query(bindingId, typedControls)`. There is no `window.subscribe` or `window.__datasets`. Shared filters must query every affected Binding, not just call `bindSelect` for the first one.
+2. For HTML mode, read the HTML runtime reference and call `dashboard_libraries` before using ECharts, Three.js or online dependencies such as Tailwind CDN. Network access is temporarily unrestricted for functional acceptance, including CDN scripts/styles/fonts, images and fetch/XHR. Browser CORS and mixed-content rules still apply. Online URLs are not entries in the packaged `libraries` array; business data must still use saved Bindings and credentials must never be embedded in HTML. Write a complete HTML page using SandboxFile. First declare `const live = window.xpertLiveArtifact` inside the page script; `live` is not a host global. Then register `live.subscribe(bindingId, renderDataset)`, await `live.ready()`, then call `live.query(bindingId, typedControls)`. There is no `window.subscribe` or `window.__datasets`. Shared filters must query every affected Binding, not just call `bindSelect` for the first one.
 3. Call `dashboard_create_html` with `title`, the relative `path`, verified `previewIds`, matching `controls` and the complete required `libraries` list. Standard charts instead use `dashboard_create`.
 4. Correct validation errors and retry the domain save. A file write, screenshot or `present_files` receipt does not save a live dashboard. Do not present the HTML as a static deliverable.
 5. Check the returned `dashboard.artifactId`, `dashboard.status: "draft"` and `dashboard.draftRevision`. The successful domain receipt opens/refreshes the Workbench preview.
@@ -49,7 +73,7 @@ Read [data-validation.md](references/data-validation.md) when creating a dashboa
 
 1. Call `dashboard_open({})` for the selected Workbench dashboard, or provide an exact Artifact ID from `dashboard_list`. Do not choose the most recent dashboard by guesswork or create a replacement Artifact.
 2. Inspect `presentation.type`. For a standard dashboard, update definition fields directly; a rename needs only `title`, `editId`, `expectedRevision` and `expectedCurrentVersionId`. No HTML file exists: omit `htmlPath` and `libraries`. For a current HTML dashboard, the result includes a new `htmlPath` editing copy of the latest saved draft, plus `editId`, `expectedRevision` and `expectedCurrentVersionId`. Read this copy with SandboxFile before editing. Each open prepares a separate copy, preserving any uncommitted earlier files.
-3. For HTML pages, apply requested changes with SandboxFile edits. Preserve data semantics, controls, query/subscription lifecycle and library locks unless the request changes them.
+3. For HTML pages, apply requested changes with SandboxFile edits. Preserve data semantics, controls, query/subscription lifecycle, existing element IDs and library locks unless the request changes them. Assign stable IDs to new KPI/chart/table/filter components. Standard arrays and preview Bindings upsert by stable ID: omitted components remain. Use `removals` with exact binding/control/view/HTML element IDs only for user-requested deletions. HTML ID preservation checks deletion, not arbitrary semantic equivalence.
 4. Automatically call `dashboard_update({"editId":"<returned ID>","expectedRevision":<returned revision>,"expectedCurrentVersionId":<returned UUID or null>,"title":"<new title if requested>"})` with the changed definition fields. When saving edited HTML, also supply the exact `htmlPath` of the editing file. Omit unchanged fields. Updating the visible heading does not rename the saved dashboard; pass `title` as well when renaming.
 5. Check the saved draft receipt; for HTML file updates also check its `sourceFile` path/hash. For another batch, reopen the latest draft and use its new revisions. If the save fails, correct the definition or editing file and retry; do not claim success. If a revision conflict occurs, keep the edited file, open/read the latest state and reconcile before saving.
 6. Historical `versionId` reads do not prepare an editable copy. Use `dashboard_read_html` to inspect historical source, then open the current draft to apply an intentional change.