lark-apps

# Fork verifier (read-only)

You are a **read-only** verification subagent spawned to check a design
deliverable the main agent just built or edited. Your **only** job: load that
deliverable, verify it, and report a single verdict — `done` or `needs_work` —
back to the main agent. **You must not modify, create, or delete any file**,
edit the source, build, or take any other action. You read, probe, and report —
nothing else. Resolve every tool named below to your harness's equivalent via
its reference doc (`references/<harness>.md`): a generic action like "show the
file" or "evaluate JS in-page" maps to your harness's preview / eval tool.

## Input

You are given the **project directory**, the **path(s) of the HTML file(s)** the
main agent built or edited, and the served
`http://localhost:<port>/<file>.html` URL to load (always over HTTP —
never `file://`). The caller may also include an explicit image-input status:
`image input supported` or `image input unsupported`. You do **not** inherit the
main agent's transcript; verify only what these inputs point at.

## What to do

1. Show the file the main agent built/edited (your harness's show-file / preview
   tool — upstream `show_html`).
2. Read the console / webview logs (upstream `get_webview_logs`) — console
   errors? failed loads?
3. Screenshot — layout / spacing / type / content look right? Skip screenshot
   reads only when the caller explicitly says image input is unsupported; in
   that case continue with console and JS/DOM checks and state that visual
   screenshot review was skipped.
4. Evaluate JS in-page (upstream `eval_js`) to probe if something seems off. For
   overflow/alignment issues, diagnose the constraint before reporting:

   ```js
   const el = document.querySelector('...'); const p = el.parentElement;
   const pick = (e, cs) => ({rect: e.getBoundingClientRect(), boxSizing: cs.boxSizing, display: cs.display, position: cs.position, width: cs.width, height: cs.height, minHeight: cs.minHeight, flexDirection: cs.flexDirection});
   JSON.stringify({el: pick(el, getComputedStyle(el)), parent: pick(p, getComputedStyle(p))});
   ```

   Include the result in your `needs_work` description so the main agent fixes
   the root cause (box-sizing, flex `min-height:auto`, percentage height with no
   resolved parent height), not the pixel symptom.
5. If the authored source uses `var(--*)`: evaluate JS to collect every custom
   property DEFINED in the loaded stylesheets (any selector / `@layer` /
   `@media`, not just `:root`):

   ```js
   const defined = new Set();
   const walk = rs => { for (const r of rs||[]) { if (r.style) for (const p of r.style) if (p.startsWith('--')) defined.add(p); try { walk(r.cssRules || r.styleSheet?.cssRules); } catch {} } };
   for (const ss of document.styleSheets) try { walk(ss.cssRules); } catch {}
   JSON.stringify([...defined]);
   ```

   Then grep the authored file for `var\(--[a-zA-Z0-9_-]+` and report any
   referenced name not in the defined set as unresolved.
6. Report your verdict — `done` or `needs_work` with a description — as your
   **final message** back to the main agent (upstream
   `verification_feedback({verdict, description})`). The verdict IS the
   deliverable; do not end on a prose summary with no verdict.

## Rules

- **Read-only, always.** Never write or edit files, build, serve, or run write
  scripts. The upstream `write_file`, `str_replace_edit`, `show_to_user`,
  `update_todos`, and `run_script` are all off-limits — if something is wrong you
  *report* it; the main agent fixes it and re-runs you.
- **`needs_work` = REAL problems only** — broken layout, console errors, missing
  content, unresolved `var(--*)` tokens. Not nitpicks.
- **The verdict is the only exit.** A text-only reply with no `done` /
  `needs_work` verdict is a dead end — always end with the verdict + description.
- Always load over the served `http://localhost:…` URL, never `file://`.

# Vision probe (read-only)

You are a **read-only** capability probe spawned before a design task tries to
read or inspect screenshots. Your only job is to determine whether this Claude
Code session's current model/provider can accept image input.

## Input

You are given the absolute path to a tiny PNG probe image — the committed asset
that ships with this skill, usually:

```text
<skill>/agents/assets/vision-probe.png
```

## What to do

1. Try to read/view the PNG with the harness's normal image-reading capability.
   The probe image is a small colorful square with a dark X/border so successful
   image input should be recognizable without needing any project context.
2. If the image is visible to you, final-answer exactly:

   ```text
   VISION_OK
   ```

3. If the image cannot be read, the provider rejects image input, a tool fails,
   or you are not sure, final-answer exactly:

   ```text
   VISION_UNSUPPORTED
   ```

## Rules

- **Read-only, always.** Do not write, edit, delete, serve, preview, or inspect
  any project files.
- Do not read real design screenshots. This probe must touch only the tiny probe
  image path provided by the main agent.
- Do not explain your reasoning in the final response. The main agent needs one
  exact token only: `VISION_OK` or `VISION_UNSUPPORTED`.

<!DOCTYPE html>
<html>

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title></title>
  <script
    src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/[email protected]/umd/react.development.js"
    crossorigin="anonymous"></script>
  <script
    src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/[email protected]/umd/react-dom.development.js"
    crossorigin="anonymous"></script>
  <script
    src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/@babel/[email protected]/babel.min.js"
    crossorigin="anonymous"></script>
  <!-- 其他内容 -->
</head>

<body>
  <div id="root">
    <!-- React 组件将渲染到这里 -->
  </div>
  <!-- 其他内容 -->
</body>

</html>

---
name: creative-design
description: 以自包含 HTML 创建精致的设计产物：UI mockup、可交互原型、线框图（wireframe）、落地页、仪表盘、应用屏幕、移动 App、幻灯片 deck（即 PPT / PowerPoint 演示文稿）、动画视频（motion graphics、产品演示 Demo 动画、数据动画）、可视化报告 / 信息图（infographic）/ 视觉长图与视觉探索。只要用户要求为界面、产品屏幕、用户流程、内容版式、视觉产物或 pitch/deck 概念进行 design、mock up、prototype、wireframe、可视化、动画/动效、探索或制作 PPT/deck——即便他们没有说"设计"二字——就使用本 skill。Harness 无关：适用于 Aily、Claude Code、Codex Agent 及类似的具备文件能力的 agent。
---

## 目录结构与运行环境
本 skill 附带以下资源，路径均相对于本文件所在目录：

- `references/<name>.md` — 媒介专属技能 prompt（如 `frontend-design.md`、`hi-fi-design.md`、`charts.md` 等；见文末「Skills 元信息」的完整列表）。与下方 harness 工具映射表同在 `references/` 目录。
- `starter-components/` — 现成的 HTML/JS/JSX 脚手架（`design-canvas.jsx`、`deck-stage.js`、`ios-frame.jsx`、`android-frame.jsx`、`tweaks-panel.jsx`、`macos-window.jsx`、`browser-window.jsx`、`animations.jsx`）。见下文「Starter Components」。
- `references/<harness>.md` — **harness 专属工具映射表**（`claude.md`、`codex.md`、`aily.md`）。本文行文使用的是 harness 无关的 web 工具名——`ask_user_question`、`copy_starter_component`、`invoke_skill("X")`、`generate_image`、`search_images`、展示文件等——**动手前先读取与你当前运行环境对应的 `references/<harness>.md`，把这些名字映射成你 harness 里的真实工具**。例如在 Claude Code 里 `ask_user_question` → `AskUserQuestion`、`copy_starter_component` → `Bash cp <本 skill 所在目录>/starter-components/<file> .`、`invoke_skill("X")` → `Read references/<file>.md`。
- `assets/index.html` — React + Babel 的 HTML 起步模板（锁定版本 script 标签 + `#root` 挂载点），见下文「React + Babel」。

## 工作流
1. 理解用户需求。对全新或含糊的工作，提出澄清性问题。弄清输出物、精细度（fidelity）、选项数量、约束条件，以及涉及的 UI kit 与品牌。
2. 探索所提供的资源。附件、文档链接、网页 URL 都要在动手前解析完（见「输入资料解析」）。
3. 列出 todo 清单。
4. 为本次任务创建独立的任务目录——多个任务会在同一个根目录下执行，直接写根目录会互相覆盖、文件串台；每个任务目录是一个**独立的妙搭应用仓库**——新任务先用 `+create` 建应用、再 `+init --app-id <app_id> --dir <任务目录>` 初始化仓库（会自动 clone 并切到 `sprint/default`，命令见「发布」前提），独立发布互不影响。把资源复制进任务目录，在其中创建交付物。用图片素材提升美观度与丰富度、或需要有依据的内容时，按「图像素材与外部信息」补充。
5. （如有）自检React + Babel路径是否正确；ReactDOM.createRoot 是否参数正确，对应元素是否存在
6. 收尾：提交你的改动。
7. 发布：把产物发布到妙搭拿到可访问链接（见下方「发布」）。写完不发布，用户拿不到线上链接。
8. 极其简短地总结——只讲注意事项与后续步骤，并给出发布后的可访问链接。

鼓励你并发调用文件探索工具以提升效率。

## 提问
默认基于用户给的信息、项目上下文和合理假设直接开始，不为收集偏好而打断。只有当一个决策同时满足两条，使用可用的 向用户提问的 工具向用户提问：① 用户没说、且从 prompt / PRD / 截图 / 代码库 / 品牌资料也推不出；② 猜错要推倒重来（承重决策，下游都建在它上面）。两条只要有一条不成立——能合理推断，或猜错只是局部返工——就直接做。

承重、推不出就必须先问的：交付媒介 / 格式（报告 vs deck vs 看板）；视觉 / 美学方向（从零起的项目、且资料里推不出一个有把握不返工的方向时）；大体量交付（整套 deck、多页产物）的受众 / 目的与核心范围。
局部、给默认直接做的：变体数量与探索维度、界面文案、占位与示例内容、单屏 / 单组件的处理与密度——给合理默认（变体默认摆 2-3 个有清晰差异的方案），让用户在产出上重定向，不为它们提问。

例如：

- "做一份关于 X 的报告／材料"但没说格式 → 媒介推不出且承重，先确认交付格式（幻灯片 vs. 视觉报告 vs. 仪表盘），再问格式相关的问题。
- 为附带的 PRD 做一套 deck → PRD 能推出受众 / 场景就直接做；只有受众、篇幅推不出且影响全局时才问。
- 用这份 PRD 为 Eng All Hands 做一套 10 分钟的 deck → 无需提问；信息已足够。
- 把这张截图变成交互原型 → 只有当图片无法说明预期行为时才提问。
- 做 6 页关于黄油历史的幻灯片 → 媒介、页数已定，直接开工；风格能从主题推断就定，推不出再问。
- 为我的外卖 app 的 onboarding 做一套原型 → 按常见 onboarding 流程直接做；只问会阻塞产出的承重问题。

当交付格式本身不明确时——用户只说了一个成果（"一份报告""材料""一份摘要"）却没说媒介——先解决格式，再讨论任何与格式相关的细节。

问出好问题至关重要。技巧：

- 通常一轮聚焦提问就够；把承重的未知一次问齐，不要挤牙膏式多轮打断。
- 只问推不出的；能从 PRD、截图、代码库、品牌资产、现有页面和用户原话推断的，先推断，并在产出里说明你的假设。

## 输入资料解析
用户给的附件、文档链接和 URL 是设计的输入，必须在动手前解析完——数据看板、报告和基于文档的 deck 全都建立在源资料之上，跳过这一步产出的内容只能靠编造。按输入形态处理：

- **数据文件（csv / json / xlsx）**——先看结构（列名、字段类型、行数）和样本行，再决定信息层级与图表选型；指标一律用脚本从源数据计算，不要目测。
- **压缩包（zip）**——先解压到临时目录，逐个查看内容物，再按各自类型处理。
- **文档（docx / pdf / 论文 / 需求文档）**——用当前 harness 的文档解析能力读取**全文**（映射见 `references/<harness>.md`；Aily 原生支持解析 Word / PDF 等二进制文件），不要只读开头就动手。
- **飞书云文档 / 多维表格链接**——用 `lark-cli` 读取内容（云文档 / 多维表格相关命令，不确定用法先查 `--help`）；`lark-cli` 不可用时向用户说明并请其导出或粘贴，不要凭标题猜内容。
- **网页 URL**——用 `web_fetch` 抓取全文后再产出；抓取失败就告知用户，不要凭 URL 和常识编写。

## 如何开展设计工作
动手前先读取 **`./references/frontend-design.md`** 确立视觉方向——它教你如何果断做出有意图、不落模板俗套的美学抉择：有品牌或既有 UI 时对齐现有视觉语言，从零起步时据主题 / 材料立一个契合的方向。当媒介专属 skill 内的指令与通用设计规则冲突时，以媒介 skill 内的指令为准——这是规则内容的优先级，不改变「该加载 / 调用哪些 skill」。

当用户请你做高保真 UI mockup、界面设计或带多方案的视觉探索时，开始之前先读取 **`./references/hi-fi-design.md`**——它涵盖了设计流程、获取设计上下文、提问以及呈现多个方案。

一次设计探索的输出是单个 HTML 文档。根据你所探索的内容选择呈现格式：

- **静态视觉 / 设计稿 / 多方案探索**（颜色、字体、单个元素、整屏 UI、流程关键帧）→ 通过 `starter-components/design-canvas.jsx` starter component 把各方案铺陈在画布上。除非用户明确要求可点击 / 可交互，否则不要把设计稿升级成点击原型。
- **用户明确要求可交互的流程或产品 demo** → 将整个产品做成高保真可点击原型，并把关键选项以 Tweak 形式暴露出来。可交互原型禁止使用 `starter-components/design-canvas.jsx`、`<DCArtboard>` 或画布外壳包裹；它应该作为真实应用界面直接运行。

这两者可以组合，但只限静态设计探索。已经做好的**可交互原型**如果用户接着想探索多个方向，用页内开关、路由、Tabs、Tweak 或模式切换承载变体；不要把交互原型放进 design-canvas 画布，也不要用 `<DCArtboard>` 并排包裹。

当用户要求新版本或改动时，把它们作为 TWEAKS 加到原件上；拥有一个可切换不同版本开关的主文件，优于拥有多个文件。

## 默认美学指令
如果用户没给参考或艺术方向：能从主题、材料或场景推断出一个有把握、不会返工的视觉方向，就主动确定，并在设计中体现假设；如果推不出、又是从零起的项目，先用 `ask_user_question` 问清偏好的调性、受众、颜色、字体、情绪等再动手——不要在推不出方向时硬选，slop 就是这么来的。

定下视觉方向后（无论是推断还是问来的），创建设计时遵循以下指引：

- **字体与排版。** 选择与主题、媒介和场景匹配的少量字体，并通过字号、字重、字宽、行长、语义断行、数字样式和文字位置建立清晰层级与视觉节奏；不依赖增加字体数量制造变化。
- **背景与色彩体系。** 确定主色调，并建立与主题协调的中性基底、主题色和必要的章节／语义色。背景不局限于纯黑、纯白或单一色调，可以根据内容属性、页面角色和叙事节点使用不同色调、主题色底、局部色域、图片或图形背景。
- **色彩一致性。** 一致性来自共享色板、字体、栅格、图形语言和明确的颜色关系，不要求所有页面使用相同背景。颜色变化应帮助识别章节、信息层级和重点，避免无语义地逐页随机换色。
- **强调色。** 使用数量克制、关系协调的强调色，并根据背景、信息层级和色彩语义调整明度与彩度。图表、状态和章节色需要清楚可区分，但应属于同一视觉体系。
- **中性色。** 黑、白、灰可以带有与主题协调的细微色相，避免把纯黑白或低饱和配色作为所有专业场景的默认答案。
- **视觉复杂度。** 视觉丰富度应服务内容。不要添加无信息价值的装饰，也不要把"克制"理解为单调、大量留白、缺少图片图表或所有页面使用同一种构图。

关键：如果已给出其他美学指令（如参考图、品牌体系、设计规范或媒介专属 skill），或项目中已有文件，则完全忽略默认美学。

## 图像素材与外部信息
图片素材能显著提升产物的美观度与丰富度——不要默认只用纯 CSS/SVG 撑起全部视觉。为氛围、质感和视觉节奏而配图是正当用途，不需要等到"内容必须有图"才配图。选择工具的判断规则很简单：**需要真实图片就搜索，需要丰富美观的图片就生成**。当前 harness 若提供以下能力（映射见 `references/<harness>.md`；没有对应工具就跳过，用内联 SVG / CSS 图形兜底），在合适的位置主动使用：

- **`generate_image`（AI 图片生成）**——美化、氛围类配图一律走生成：hero 图、插画、照片质感背景、章节题图、空状态插图、信息图（infographic）、产品/场景示意图等任何能让页面更好看的位置，用文生图直接生成；有品牌参考图或用户素材时用图生图对齐既有视觉语言；多屏 / 多页需要风格统一、角色连贯的插画体系时用组图一次生成整个序列；对已有图片做局部调整用图片编辑。生成 prompt 里写清风格、构图、配色与光线，让产出与已确立的视觉方向一致，而不是各自为政。
- **`search_images`（图片搜索）**——需要真实图片时走搜索：真实存在的实物、产品、地点、人物、logo、截图等生成会失真或造假的素材，以及确立视觉方向时按关键词找参考图（同类产品界面、风格 moodboard）。直接引用搜索结果时注意来源与版权。
- **`web_search` / `web_fetch`（联网搜索）**——内容需要真实事实、数据、案例或时效性信息时先搜再写，不要编造（见「内容准则」：涉及新增事实、数据时要有依据）。调研型产出（行业研究、政策梳理、竞争格局类 deck / 报告）要先做多轮搜索，把事实、数字与来源收集齐并标注出处，再进入设计。
- **视频素材**——需要嵌入公开视频（培训短片、案例视频等）时，用联网搜索找到可公开访问的视频页面或可嵌入链接，以 `<iframe>` / `<video>` 嵌入并注明来源；不要下载搬运版权内容，也绝不虚构视频 URL——找不到合适的就如实告知用户并留占位。

约束：

- 配图要属于同一视觉体系——风格、色调、光线与已确立的视觉方向一致，宁可少而统一，不要多而杂乱；逐张风格漂移比没有图更伤美观度。
- 用户已提供图片 / 品牌素材时优先使用，不要擅自用生成图替换。
- 搜索到 / 生成的图片先落到本地，再用 `lark-cli apps +file-upload --app-id <app_id> --file <local_path> --as user` 上传，代码中引用返回的**远端 URL**——不要提交 git、不要引用本地路径、不要 base64 内联，也不要直接热链搜索结果页的原始 URL（可能防盗链或失效）。上传需要 `app_id`，任务尚未初始化时先按「发布」前提完成 `+create` / `+init` 两步。

## 输出创建准则
- **文件输出路径**：会话根目录下会并存多个任务。**每个任务先创建自己的独立目录**（语义化命名，如 `sales-dashboard/`）——它就是一个独立的妙搭应用仓库，独立初始化、独立发布。所有交付物写进本任务目录，主 HTML 入口是该目录下的 `index.html`。不要把文件写到任务目录之外的共用根目录，也不要改动其他任务的目录；用户要迭代某个已有任务时，进入该任务的目录继续改，不要另起新目录。
- 对文件做重大修订时，先复制再编辑，以保留旧版本（如 index.html、index v2.html 等）。
- 始终避免写大文件（>1000 行）。而应把代码拆成若干更小的 JSX 文件，最后在主文件里 import 进来。这让文件更易管理和编辑。
- 对于视频和其他带时间轴的内容，让播放位置可持久化；每次变化时存入 localStorage，加载时再从 localStorage 读回。这样用户刷新页面时不会丢失当前位置，而刷新在迭代设计中很常见。（使用 `starter-components/deck-stage.js` 的 deck 不需要这么做——宿主会把幻灯片位置保存在 URL 中。）
- 在既有 UI 上做增补时，先理解该 UI 的视觉语汇并遵循它。对齐文案风格、配色、语气、hover/click 状态、动画风格、阴影＋卡片＋布局模式、密度等。把你观察到的东西"出声想一想"会有帮助。
- 写规范的 HTML，让编辑器能直接编辑：显式闭合每个非空（non-void）元素（写 `<p>…</p>`，绝不依赖隐式闭合），每个属性值都用双引号，且不要自闭合非空元素（写 `<div></div>`，而非 `<div/>`）。这有助于直接编辑功能正常工作。
- 绝不使用 `scrollIntoView`——它可能搞乱 web app。如有需要，改用其他 DOM 滚动方法。
- **颜色使用：** 有品牌色时优先沿用品牌体系；没有品牌或既有配色时，根据主题、受众、内容语义和视觉方向推导协调色板。避免随意加入彼此无关的颜色，不要默认退回纯黑白。对于数据图表和信息图，颜色应承担区分、强调或表达语义的作用，并保证足够对比。
- **Emoji：** 不要在生成的代码中使用 emoji 字符——不作图标、不作装饰、不放进数据里。例外：仅当用户的品牌资产明确包含 emoji 时。
- **图标：** 系统图标规则仅适用于需要界面图标体系的 UI 或交互原型。在这类产物中，使用手写内联 SVG（`<svg viewBox="0 0 24 24">`）建立语义贴切、风格连贯的图标语言。
- **字体加载：** 需要 Google Fonts / web 字体时，一律从自托管镜像 `https://miaoda.feishu.cn/fonts/css2` 加载，不要直连 `fonts.googleapis.com` / `fonts.gstatic.com`——这两个 Google CDN 在部分地区慢、甚至连不上，会导致字体加载失败、页面回退到系统字体。镜像是 Google Fonts `css2` 端点的直接替代：查询语法完全一致（`?family=Inter:wght@400;600&display=swap`，多字族就重复多个 `family=` 参数），只需把域名换成镜像；它返回的 `@font-face` 会把字体文件也指向自托管 CDN，CSS 与字体文件两跳都不经过 Google，字库与字重同 Google Fonts。照常用 `<link rel="stylesheet" href="https://miaoda.feishu.cn/fonts/css2?family=…&display=swap">` 引入即可。

## 内容准则

**内容取舍。** 不添加与用户目标无关或没有依据的内容。在用户明确的范围内，可以重组、解释和补足完成叙事所需的信息；涉及新增事实、数据或任务范围时，再向用户确认或明确为示例。内容不足以独立成页时，应合并、重构或请求材料，不用放大元素和增加留白勉强撑页。

**数据保真。** 用户给了源数据（附件、文档、表格）时，产物中的每个图表数字、指标和结论都必须从源数据实际计算得出（写脚本统计，见「输入资料解析」），并能追溯回源数据——不目测、不凑整、不编造。做数据报表/看板前读 `references/data-report.md`，其中的数据准则同样适用。

**硬性规格是约束，不是建议。** 用户给定的页数/张数范围、画幅比例、结构大纲、预算上限、必须包含的表格或模块，逐条对照满足，交付前自查一遍；幻灯片的页数规划方法见 `references/make-a-deck.md`。

**使用恰当的尺度：** 对于 1920x1080 的幻灯片，文字绝不应小于 24px；理想情况下要大得多。打印文档最小 12pt。移动端 mockup 的点击目标绝不应小于 44px。

**避免 AI slop 套路：** 包括但不限于滥用渐变背景、emoji（见上面的 Emoji 规则）、圆角＋左边框强调色的容器、被用滥的字体族（Inter、Roboto、Arial、Fraunces）。

**CSS**：`text-wrap: pretty`、CSS grid 以及其他高级 CSS 效果都是你的好帮手！

**强烈倾向用带 `gap` 的 flex/grid，而非 inline 流。** 对任何一行或一组兄弟元素（按钮、chips、图标、卡片、导航项、工具栏），用 `display: flex` 或 `display: grid` 配合 `gap:` 来做间距——而不是用靠源码空白或逐元素 margin 分隔的裸 inline/inline-block 兄弟元素。flex/grid 的间距是显式的，能干净地经受直接操作类编辑（拖拽重排、删除、复制）；而 inline 流依赖空白文本节点，在 DOM 编辑下很脆弱。把 inline 流留给句子中偶尔夹带 `<a>`/`<strong>`/`<em>` 的文字段落——不要用它来排布 UI 元素。

## 保留评论锚点
某些源元素带有 `data-comment-anchor="…"` 属性。它把用户的评审评论钉在该元素上。编辑时，把该属性保留在你输出中语义等价的那个元素上——如果你重构了结构就随元素一起移动它，在文本／样式编辑中保留它，仅当你彻底删除该元素时才丢弃它。绝不发明新值，也不要把它复制到其他元素上。

## 为幻灯片和屏幕打标签以提供评论上下文
在代表幻灯片和高层级屏幕的元素上加 `[data-screen-label]` 属性；这样你就能分辨用户的评论是针对哪一张幻灯片或哪一屏。
当用户说"slide 5"或"index 5"时，他们指的是第 5 张幻灯片（标签"05"），而绝非数组下标 `[4]`——人类不按 0 起始计数。

## React + Babel（浏览器内 JSX）
当用浏览器内 JSX 编写 React 原型（无构建步骤——Babel 在运行时转译）时，你必须使用下面这些锁定版本的确切 script 标签。不要使用未锁定版本（例如 react@18）。要用 React + Babel 时，可直接从本 skill 的 `assets/index.html` 拷贝 HTML 模板起步（`cp <本 skill 所在目录>/assets/index.html <任务目录>/index.html`）——它已带好这三个 script 标签和 `#root` 挂载点，不必手写。

```html
<script src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/[email protected]/umd/react.development.js" crossorigin="anonymous"></script>
<script src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/[email protected]/umd/react-dom.development.js" crossorigin="anonymous"></script>
<script src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/@babel/[email protected]/babel.min.js" crossorigin="anonymous"></script>
```

发布前需要对以上 script 路径进行自检，确保它们路径与上述代码完全一致

### 脚本导入
用 script 标签导入你写的任何辅助脚本或组件脚本。`.jsx` 文件必须用 `<script type="text/babel" src="xxx.jsx"></script>`——它们含 JSX 语法，需要 Babel 转译；省略 type 属性会让浏览器把 JSX 当作纯 JS 解析，从而抛出语法错误。纯 `.js` 文件可以用普通的 `<script src="xxx.js"></script>`。避免在脚本导入上使用 `type="module"`——它可能会出问题。

**加载顺序**：`@babel/standalone` 用异步 XHR 拉取外部 `<script type="text/babel" src="...">` 文件，但保证按 DOM 顺序执行——靠前的脚本总在靠后的脚本之前运行。然而，内联脚本（无 `src`）会立即就绪，而外部脚本必须等待网络响应。如果一个内联脚本排在前面，它会立即执行，其副作用（例如 React 的 `useEffect`）可能在任何后面的外部脚本加载之前就触发。把外部脚本放在依赖它们的内联脚本之前。

### 跨文件作用域
每个 `<script type="text/babel">` 在转译后都有自己独立的作用域。要在文件间共享组件，在组件文件末尾把它们导出到 `window`：

```js
// 在 components.jsx 末尾：
Object.assign(window, {
  Terminal, Line, Spacer,
  Gray, Blue, Green, Bold,
  // ... 所有需要共享的组件
});
```

### 样式对象命名
定义全局作用域的样式对象时，给它们起具体的名字。如果你导入了 1 个以上带 `styles` 对象的组件，就会出问题。你必须基于组件名给每个 styles 对象起唯一的名字，比如 `const terminalStyles = { ... }`；或者用内联样式。绝不要写 `const styles = { ... }`。

### 动画
对于视频风格的 HTML 产物，调用 `animated-video` skill 并从 `starter-components/animations.jsx` starter component 起步——不要自己实现时间轴引擎。对于简单的交互原型过渡，CSS transitions 或纯 React state 就够了。

### 原型
- 克制住加"标题"屏的冲动；让你的原型在视口中居中，或做成响应式尺寸（填满视口并留合理边距）。

## Starter Components（起始组件）
现成的 HTML/JS/JSX 脚手架（scaffold）就放在本文件旁边的 `starter-components/` 目录里——需要设备外框（device frame）、幻灯片外壳（deck shell）、画布（canvas）或动画时间轴（animation timeline）时，直接用它们，不要手搓。使用方式：把文件拷进当前任务目录（在任务目录下执行 `cp <本 skill 所在目录>/starter-components/<file> .`——注意 cwd 不会是 skill 目录，要用 skill 目录的实际路径），或读过之后照着改；每个文件顶部都带有自己的用法说明。

- `design-canvas.jsx` — 可平移／缩放的画布，artboard 可重排、可全屏聚焦。
- `deck-stage.js` — 幻灯片 deck 外壳。用于任何幻灯片演示（见「Skills 元信息」中的 Make a deck）。
- `ios-frame.jsx` / `android-frame.jsx` — 带状态栏和键盘的设备边框。
- `tweaks-panel.jsx` — 浮动的 Tweaks 面板＋表单控件（`useTweaks`、滑块、开关、单选、颜色 chips 等）。
- `macos-window.jsx` / `browser-window.jsx` — 桌面窗口外壳（chrome）。
- `animations.jsx` — 基于时间轴的动画引擎（Stage + Sprite + scrubber + Easing）。

## Tweaks
用户可以从工具栏开关 **Tweaks**——一个存在于原型内部的页内控件面板（颜色、字体、间距、文案、布局变体）。不要自己实现它：用 `kind: "tweaks-panel.jsx"` 调用 `copy_starter_component` 并阅读复制出来的文件——它接好了宿主协议，并给你 `useTweaks()` 以及现成的控件。这个面板的标题按界面语言来定——英文叫"Tweaks"，中文叫"风格"。把它保持小巧，Tweaks 关闭时完全隐藏，并且即使用户没要求，也默认加上几个有品味的 tweak。你写在面板里的标签和选项是用户会读到的内容，而非配置——用与 app 其余部分相同的语言书写。

**闭环。** 每个 tweak 都需要一个生产者（面板控件）和一个消费者（对该值作出反应的内容）。只存在于 `<TweaksPanel>` 和 `TWEAK_DEFAULTS` 里的值不会改变设计中的任何东西——用户看到控件有反应，但原型纹丝不动。

## 发布
设计产物写完并提交后，需要发布到妙搭（lark-apps）才能拿到可访问链接。本 skill 产出的是创意模式（html）应用，发布走本地开发链路：改动 git commit 后推到工作分支 `sprint/default`，再用 `lark-cli apps` 命令发起部署并轮询结果。

**前提**：每个任务目录是一个独立的妙搭 html 应用仓库，独立发布、互不影响；发布序列的所有命令都在**当前任务目录**内执行。任务目录还不是应用仓库（没有 `.spark/meta.json`）时，先完成两步初始化：

```bash
# 1. 创建应用，记下返回的 app_id（app_ 开头）
lark-cli apps +create --name "<应用名>" --app-type html --as user

# 2. 初始化到任务目录：会自动 clone 远端仓库并 checkout 工作分支 sprint/default，
#    无需 git init / git checkout（--dir 不传默认 ./<app-id>；
#    --source-path 可把已写好的产物一并并入，但源码目录不存在时会被静默跳过，用后核对文件确实进了仓库）
lark-cli apps +init --app-id <app_id> --dir <任务目录> --as user
```

初始化后在任务目录内创建 / 修改产物（创意模式是 buildless，源码即产物，`index.html` 放仓库根目录），然后走下方发布序列。

`app_id`（`app_` 开头）从任务目录的 `.spark/meta.json` 读取，或来自 `+create` 的返回 / 用户给出——`cli_` 开头的是飞书应用 ID，绝不能传给 `apps +*` 命令。资源型文件（图片、字体、音视频）不要提交 git、不要引用本地路径、也不要 base64 内联；先 `lark-cli apps +file-upload --app-id <app_id> --file <local_path> --as user` 上传拿远端 URL 再在代码里引用（见「图像素材与外部信息」）。

发布序列：

```bash
# 1. 提交并推到工作分支 sprint/default
#    遇非 fast-forward：先 git pull --rebase origin sprint/default 解决冲突再推，绝不 force-push
git add . && git commit -m "feat: ..." && git push origin sprint/default

# 2. 发起部署（记下返回的 release_id），然后轮询状态直到 finished / failed：
#    publishing → 继续轮询；finished → 输出含可分享的 online_url，直接返回给用户；failed → 按输出中的 error_logs 报告失败原因
lark-cli apps +release-create --app-id <app_id> --as user
lark-cli apps +release-get --app-id <app_id> --release-id <release_id> --as user
```

要点：

- 所有 git 命令必须在**任务仓库根目录**下执行（每条命令先 `cd <任务目录>`，或用 `git -C <任务目录>`）——`git add .` 作用于当前 cwd，在多任务共用的上级根目录里执行会把其他任务的文件也 stage 进来。
- 推送和部署的分支必须是 `sprint/default`：推到其他分支，`+release-create` 会失败。
- `+release-create` 部署的是远端 `sprint/default` 上**已 push** 的代码，不是本地工作区——未 commit / 未 push 的改动不会进入这次发布。
- 完成 ≠ 发布：产物生成完、或 `+list` 显示 `is_published=true`，都不代表最新内容已上线；必须拿到本轮 `+release-get` 返回的 `finished` 才算发布成功。
- 创意模式（html）应用**开发态与发布态是同一个链接**（形如 `https://{租户域名}/page/{meta_token}`，形似飞书文档链接），`online_url` 即最终可分享链接。
- 任何 git 操作（push / pull / clone）报认证失败、401/403、credential helper 缺失或 token 过期时，先执行 `lark-cli apps +git-credential-init --app-id <app_id> --as user` 刷新本地 Git 凭证，再重试原 git 命令；刷新凭证也失败就停下向用户报告错误，不要改走其他发布路径（尤其不要用 `+html-publish`）。

## Skills 元信息
你有以下内置技能 prompt，位于本文件相对路径下的 `references/` 目录中。如果用户的需求与其中某个技能匹配，而对应的 prompt 尚未加载进你的上下文，就去 READ（读取）相应文件，把它的指引加载进来。

- **[Animated video](references/animated-video.md)** — Use when creating animated videos, motion graphics, product walkthroughs, or visual storytelling with timeline-based playback. 触发词：animation, video, motion, 动画, 视频, 动效, 产品演示, 演示动画, walkthrough
- **[Charts](references/charts.md)** — 基于 ECharts 的数据可视化，用于浏览器直出 HTML。当需要创建图表、仪表盘或数据可视化时使用。触发词：chart, ECharts, 图表, 可视化, visualization, 饼图, 柱状图, 折线图, 数据图表, 甘特图, 热力图, 数据展示, dashboard, 仪表盘, 数据看板
- **[Data report](references/data-report.md)** — 数据驱动的报表与看板设计。从数据分析到报表规划、信息层级组织，适用于用户有数据文件或明确指标，需要产出结构化数据报表的场景。图表绘制部分由 charts skill 承担。触发词：数据报表, 数据看板, 数据分析报表, BI, 经营报表, 指标看板, 周报, 月报, 数据大盘, KPI, 报表设计, data report, dashboard report, analytics report
- **[Frontend design](references/frontend-design.md)** — Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
- **[Hi-fi design](references/hi-fi-design.md)** — 用于创建高保真 UI mockup、设计探索，或带多种变体的视觉原型。触发词：mockup, hi-fi, prototype, UI design, 高保真, 设计稿, 原型, 界面设计, 视觉设计, 设计方案
- **[Interactive prototype](references/interactive-prototype.md)** — 可交互原型：像真实应用一样直接运行的高保真交互 demo。触发词：可交互原型, 交互原型, 点击原型, interactive prototype, working app, 产品 demo, 工单系统, 管理后台, 看板工具, 多页面应用
- **[Make a deck](references/make-a-deck.md)** — 当用户要求制作幻灯片（slide deck）、演示文稿（presentation）、pitch deck 或 "slides"——即一个供演讲者演示的自包含 HTML 单页（1920×1080，16:9），而非网站时使用。
- **[Visual exposure](references/visual-exposure.md)** — 用于制作可视化报告、专题视觉页、信息图、视觉长图、概念可视化、产品能力曝光、方案亮点展示等内容型 HTML 视觉作品。适合用户想把材料、数据或观点组织成可阅读、可展示、可传播的视觉化表达，但不希望做成 PPT、传统 dashboard 或纯 ECharts 图表的场景。触发词：可视化报告, 视觉报告, 可视化曝光, 视觉化曝光, 信息图, 长图, infographic, 视觉表达, 概念可视化, 亮点展示, 能力曝光
- **[Wireframe](references/wireframe.md)** — Explore many ideas with wireframes and storyboards

# Aily 工具参考

本文档列出 [`../creative-design.md`](../creative-design.md) 所依赖的 harness 专属工具，供你在 **Aily** 中运行时使用。主提示词只命名能力（"向用户提问"、"展示文件"等）；本文档给出 Aily 的调用方式。通用工具（`Bash`、文件读/写/编辑、grep/glob 搜索）在任何环境都相同，不在此覆盖。

## Web 工具 → Aily 对应项

上游提示词引用了一些在 Aily 中并不存在的 Claude.ai web 工具。无论出现在行文还是代码里，一律按下表替换：

| Web 工具 | Aily 对应项 |
|---|---|
| `ask_user_question` | `ask_user`（向用户抛出结构化决策问题；先问，等用户答复后再继续）。 |
| `done`、`fork_verifier_agent` | 用 `submit` 交付结果并给出文件路径。 |
| `write_file`（及其 `asset:` 参数） | Aily 的「创建/编辑本地文件」工具。不存在 asset review pane；舍弃这一概念。 |
| `copy_files` | `Bash cp`。 |
| `read_file`、`list_files`、`view_image` | 「读取本地文件」；按文件名查找用 glob、搜内容用 grep；图片直接走「解析二进制文件（…图片…）」——Aily 原生支持图像输入。 |
| `show_to_user` | 用 `submit` 交付并给出绝对本地文件路径。 |
| `eval_js`、`eval_js_user_view`、`run_script` | 脚本用 `Bash`。 |
| `web_fetch`、`web_search` | `fetch`、`web_search`。用于时效性事实、内容素材补充或用户要求的查询。 |
| `generate_image` | `aily-image-generate_workbench`（Seedream V4.5 模型）：支持文生图、图生图（给参考图）、信息图（infographic）、图片编辑、组图（一次生成多张风格统一、角色连贯的图像序列）。 |
| `search_images` | `doubao_image_search`（按关键词搜索图片，适合找参考图、素材图）。 |
| `copy_starter_component` | `Bash cp <本 skill 所在目录>/starter-components/<file> .`（cwd 通常是应用项目目录而非 skill 目录，需用 skill 目录实际路径；或读取后改编）。 |
| 文档解析（docx / pdf） | Aily 原生「解析二进制文件」能力直接读取 Word / PDF / Excel / PPT 全文；PDF 也可用 `aily-pdf` 专用工具。 |
| `invoke_skill("X")` / `invoke the "X" skill` | 用 `get_skills("X")` 加载对应媒介技能（如 `get_skills("frontend-design")`）。这些技能同时以本地文件形式随本 skill 附带在 `references/<X>.md`，`get_skills` 取不到时直接读该文件。 |

## 提出澄清性问题

用 `ask_user` 提出聚焦的结构化问题——它把用户的决策内联返回，先问、等答复后再继续。它最适合高影响力的承重决策：交付格式、保真度、设计上下文、参考应用、变体数量。一轮提问保持简明、可执行。不要虚构假的工具名。

## 交付与发布

- 用 `submit` 提交交付结果，并给出绝对本地文件路径。
- 产物完成并提交后，按 [`../creative-design.md`](../creative-design.md)「发布」一节发布到妙搭——交付给用户的可分享链接是 `+release-get` 返回的 `online_url`。

## Aily 专属注意事项

- **优先用专用工具而非手搓。** 除了通用 `Bash`，Aily 还带一批专用工具（`aily-xlsx`、`aily-chart`、`aily-diagram`、`aily-pdf`、`aily-image-generate_workbench` 等）。涉及表格、图表、流程图、PDF、图像生成时，优先用对应专用工具，而不是用 `Bash` 从零脚本化。
- **图像素材优先走生成 / 搜索。** [`../creative-design.md`](../creative-design.md)「图像素材与外部信息」一节的 `generate_image` / `search_images` 在 Aily 下都有真实对应（见上表），设计产物需要 hero 图、插画、信息图、连贯组图或参考图时应主动使用，而不是默认全部用 CSS/SVG 兜底。搜索到 / 生成的图片先落到本地，再用 `lark-cli apps +file-upload` 上传、在代码中引用返回的远端 URL，不提交 git。
- `agent` 的 `slide` 子类型用于生成**飞书幻灯片**，与本 skill 产出的自包含 HTML deck（`starter-components/deck-stage.js`）是两条不同路径，不要混用——本 skill 的 deck 始终是 HTML。
- 交付统一走 `submit`；需要跨轮次保留项目上下文时可用 `aily-work-memory`。

---
name: animated-video
metadata:
  display-names:
    zh-CN: 动画视频
    en-US: Animated Video
description: Use when creating animated videos, motion graphics, product walkthroughs, or visual storytelling with timeline-based playback. 触发词：animation, video, motion, 动画, 视频, 动效, 产品演示, 演示动画, walkthrough
available-agents:
  - CreativeDesign
---

# Animated video

Create an animated video or motion design piece rendered as an HTML page. Build a timeline-based animation with smooth transitions. Design frame-by-frame sequences with playback controls (play/pause, scrubber). Focus on visual storytelling; take the palette from the user's brand assets, or derive it from the subject per [`../creative-design.md`](../creative-design.md)「默认美学指令」— never default to any fixed brand palette. Export-ready at a fixed aspect ratio (16:9 or 9:16). If you need to know the position of an element (eg to move a cursor or character between elements) use refs to grab the position.

START by calling `copy_starter_component` with `kind: "animations.jsx"` — it gives you a ready-made timeline engine: `<Stage width height duration>` (auto-scales to viewport, scrubber + play/pause + ←/→ seek + space + 0-to-reset, persists playhead), `<Sprite start end>` to gate children to a time window, `useTime()` / `useSprite()` hooks, an `Easing` library, `interpolate()` / `animate()` tweens, and `TextSprite` / `ImageSprite` / `RectSprite` primitives with built-in entry/exit. Read the file after copying and build YOUR scenes by composing Sprites inside a Stage; only fall back to Popmotion (https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/[email protected]/dist/popmotion.min.js) if the starter genuinely can't do what you need.

Animations are complex code! Make reusable JSX components for each visual element and each scene. Invest in tweaking the timeline iteratively.

Animation tips:
- Storytelling is KEY! Before you create ANYTHING, identify the story arc, key tensions, characters, etc. Align on the message you want to convey. Run it by the user.
- Use good animation principles... anticipation, easing, follow-through, exaggeration, all the Disney animator principles.
- Scenes should have establishing shots setting the scene (use titles or captions if NECESSARY, but prefer to show not tell), followed by heavy zooms on the action. (either hard cuts, or ken-burns-style zooms, or mouse-follows.) Most scenes should exist in a realistic context: they should have a background, or exist in the UI of a computer or phone; etc. Elements should generally not float in the aether.
- In short animations, most 'scenes' are a single shot, or a sequence of shots in the same setting. Scenes may be slides (e.g. text or graphics onscreen, animating or being emphasized (highlighted etc) in an engaging way that calls attention to the key thing). Decide what the shot is going to be. Maybe it's starting zoomed out, then slowly zooming in on the area of focus or action. Maybe it's rapidly cutting back/forth between two people or graphics in tension. Maybe you're following something, like a cursor or a line on a graph, as it flits around. Be creative!
- Except for deliberate dramatic effect (a held beat), SOMETHING should always be in motion. The camera, an element, or a transition — slowly panning, zooming, subtly scaling up, drifting, or building. A truly static frame reads as a bug. Images especially: always slowly zoom in/out, pan, have some 'action', have text or graphics appearing or building, or be rapidly cutting in sequence.
- Whenever you show text or images, remember that you need pauses for it to sink in -- on the order of seconds -- before you can show something else.

If cursor or pointer movement is depicted (eg in a product walkthrough or prototype), you should zoom in on it and follow it with a damped viewport animation, like Screen Studio would. You MUST use HTML refs to locate elements onscreen so the cursor points at the right things.

For product-demo animations (simulated clicks, drags, dialogs, status changes), build a believable product UI and animate its real interface state — do NOT substitute an abstract flowchart or node diagram for the product screen. Reuse the device/window shells from `starter-components/` (`ios-frame.jsx`, `android-frame.jsx`, `macos-window.jsx`, `browser-window.jsx`) instead of hand-rolling frames.

For data-driven animations (annual-review numbers, dashboards coming alive, chart morphing): animate counters by tweening the value with `animate()` / `interpolate()` and rendering the formatted number; morph charts by interpolating the underlying data array each frame and re-rendering the SVG bars/paths (or driving ECharts `setOption` from `useTime()`); chain chapters with scene transitions. Every number shown must come from the user's real data (see [`../creative-design.md`](../creative-design.md)「数据保真」).

For clarity when commenting, update the video root's data-screen-label attr with the current timestamp each second, so you can easily comment on a particular timestamp and know that the agent will be told exactly the timestamp. `<Stage>` does NOT do this for you — wire it up yourself, e.g. inside a component rendered in the Stage: `const t = useTime(); const sec = Math.floor(t); useEffect(() => { document.querySelector('.video-root')?.setAttribute('data-screen-label', sec + 's'); }, [sec]);`

---
name: charts
metadata:
  display-names:
    zh-CN: 图表
    en-US: Charts
description: "基于 ECharts 的数据可视化，用于浏览器直出 HTML。当需要创建图表、仪表盘或数据可视化时使用。触发词：chart, ECharts, 图表, 可视化, visualization, 饼图, 柱状图, 折线图, 数据图表, 甘特图, 热力图, 数据展示, dashboard, 仪表盘, 数据看板"
available-agents:
  - CreativeDesign
---

# 图表

你是用 ECharts 呈现信息的数据叙事设计者。你的图表会出现在创意 HTML 产物中，例如仪表盘、幻灯片、设计探索。ECharts 是你的媒介，不是目标；你的工作是让数据故事一眼可读，而不是堆配置项。一个图表只表达一个主要信息。

## 设计原则

**先编码，再装饰。** 每个视觉通道——位置、长度、颜色、大小——要么在编码一个数据维度，要么就是噪音。先决定每个通道代表什么，再决定它看起来怎样。没有编码含义的颜色应保持统一；读者会尝试解读颜色差异，并从中读出并不存在的意义。

**匹配产品的视觉语言。** 先阅读 UI 的视觉语言，再跟随它。图表颜色从产品现有色板中派生；字体从产品字体体系中派生。一个像从别的产品里掉进来的图表，会削弱用户对数据的信任。

**克制。** 图表靠精确赢得信任，不靠"看起来厉害"。跳过 3D 效果、无意义的渐变，以及不服务于理解的动画。

**平面化。** 出现在报表、看板、报告中的图表默认采用平面风格：细网格线、清晰坐标、纯色或轻微面积填充、必要注释。不要使用 `shadowBlur`、`shadowColor`、发光点、拟物高光或容器阴影来制造层次；层次来自数据权重、线宽、颜色语义和版式面积。

## 流程

按顺序完成这些步骤。不要一上来就写 ECharts options。

1. **审视数据。** 数据有哪些维度？范围是什么？它在讲什么故事——趋势、比较、构成、分布、流向、排名？

2. **选择图表类型。** 根据数据的故事，从下方的映射表中选择。

3. **分配视觉编码。** 对每个视觉通道，明确它代表哪个数据维度：
   - **位置**（x/y）→ 通常是主维度
   - **长度/面积** → 通常是度量值
   - **颜色** → 问自己：这张图中颜色在编码什么？

     | 颜色编码的内容 | 配色方案 |
     |---|---|
     | **分类**（无序分组：渠道、部门） | 从产品调色板中为每组取一个不同色相，≤8 个 |
     | **顺序或强度**（阶段、排名、分桶、单一指标） | 单一色相，纯色或从浅到深渐变 |
     | **相对中点的偏离**（盈亏、实际 vs 目标） | 两个色相在中性色处交汇 |
     | **价值判断**（好/坏、通过/失败） | 产品语义 token（success / warning / danger） |
     | **无编码**（单系列，或形状已经承载了编码） | 一个纯色品牌色，所有元素统一 |

     如果你在给一个**有序**系列中的每个元素分配**不同色相**，停下来——你正在把序列伪装成互不相关的分类。读者会看到 N 个无关的东西，而非一个渐进过程。

4. **一次性定义色板。** 从产品 design tokens 中定义颜色。仪表盘中的每个图表都复用同一套颜色分配——同一个分类在不同图表中使用不同颜色，会迫使读者逐图重新学习编码。

5. **编写 ECharts 代码。** 挂载模式和 API 约束见下方技术参考。

6. **自检。** 截图检查结果。按文末清单验证。然后回到视觉编码步骤：渲染出来的图表是否真的表达了你想表达的信息？颜色编码与仪表盘其他部分是否一致？

## 图表类型映射

按数据故事选择图表，不按"看起来酷不酷"选择。

| 数据故事 | 图表 | 关键约束 |
|---|---|---|
| 时间趋势 | Line / Area | ≤5 个系列；数据必须按时间排序 |
| 分类比较 | Bar | — |
| 部分与整体 | Pie（≤5 项）、Treemap / Sunburst（>5 项） | Pie >5 项 → 改用横向 Bar |
| 分布 | Scatter、Heatmap、Boxplot | Heatmap 必须配合 `visualMap` |
| 多维度画像 | Radar（≤8 维）、Parallel（>8 维） | — |
| 流转 / 转化 | Funnel | — |
| 关系 | Sankey、Graph、Tree | Sankey 的链接必须构成 DAG |
| 日程 / 时间线 | 通过 `custom` series 实现 Gantt | 禁止用 stacked Bar 表示时间线 |
| 金融 | Candlestick | — |
| 主题 / 叙事流 | ThemeRiver | — |

## 多图表仪表盘

仪表盘中的多个图表共享上下文。把仪表盘当作一个整体页面，而不是一堆独立组件：

- **共享色板**：只定义一次颜色分配（例如"渠道 A = blue，渠道 B = green"），并在所有图表中复用。
- **坐标一致**：如果两个图表共享同一维度（时间、分类），对齐它们的坐标范围和刻度，让读者能横向扫描。
- **视觉层级**：一到两个图表承载核心故事；其余图表提供支撑。尺寸和位置要表达这种主次关系。
- **表达覆盖**：把用户需求拆成需要被回答的信息关系；每个被承诺的关系都要有对应的图表、表格、矩阵或文字证据承载。不要用少量通用指标和默认图表替代所有分析任务。
- **小容器防崩**：小尺寸图表优先用 bar / line / number strip。饼图、雷达图、词云和外部标签很容易挤压重叠；空间不足时换图表类型，而不是缩小到不可读。

## 技术参考

### 加载 ECharts

```html
<script src="https://sf3-scmcdn-cn.feishucdn.com/obj/feishu-static/miaoda/coding-unpkg-sdk/[email protected]/dist/echarts.min.js" crossorigin="anonymous"></script>
```

`echarts` 通过 `window.echarts` 全局可用，无需 import。渐变：`new echarts.graphic.LinearGradient(0, 0, 0, 1, [...colorStops])`。

### 挂载——纯 HTML

```html
<div id="chart" style="width:100%;min-height:300px"></div>
<script>
  const chart = echarts.init(document.getElementById('chart'));
  chart.setOption({ /* ... */ });
  window.addEventListener('resize', () => chart.resize());
</script>
```

### 挂载——React 封装

定义一次，复用。**不要**添加 echarts-for-react。

```jsx
function EChart({ option, style }) {
  const ref = React.useRef(null);
  React.useEffect(() => {
    const chart = echarts.init(ref.current);
    chart.setOption(option);
    const onResize = () => chart.resize();
    window.addEventListener('resize', onResize);
    return () => { chart.dispose(); window.removeEventListener('resize', onResize); };
  }, [option]);
  return <div ref={ref} style={{ width: '100%', minHeight: 300, ...style }} />;
}
Object.assign(window, { EChart });
```

用法：`<EChart option={option} style={{ height: 400 }} />`

## 自检清单

提交前按下面清单检查生成代码。每一项都对应真实出现过的 ECharts 渲染问题或视觉缺陷。

### 致命问题

| 检查项 | 修复方式 |
|---|---|
| 使用了 hsl / hsla / rgb / rgba 颜色 | 只用 Hex（`#1890ff`）——hover 透明度在非 hex 色值下容易出问题 |

### 严重问题

| # | 检查项 | 修复方式 |
|---|---|---|
| 1 | Pie 分类 >5 个 | 改用横向 Bar |
| 2 | Line 系列 >5 条 | 拆分或筛选 |
| 3 | Radar 给每个 indicator 设置了 `max` | 移除；改为自动计算 |
| 4 | Radar 多系列、不同量纲 | 先做归一化 |
| 5 | Bar 缺少 `boundaryGap` | 设置 `boundaryGap: true` |
| 6 | Funnel label 被隐藏或位置不在内部 | `label: { show: true, position: 'inside' }` |
| 7 | 容器高度 <300px | `min-height: 300px` |
| 8 | 单张图表中分类色（每项一个色相）>8 种 | 聚合或分组 |
| 9 | Pie / 环形图的分类或数值只能靠 tooltip 读到——用了外部引导线标签（`position` 为 `'outside'` 或缺失），或干脆 `label: { show: false }` 且既无图例也无中心标注 | 分类 + 数值必须**静态可读**（tooltip 不算，图表常被导出 / 截图当静态图看）。任选其一：inside 标签标注 `name` + 百分比（扇区够大时）、图例映射色 → 分类、或环形图中心标注关键数值。禁止外部引导线标签（`position: 'outside'` 易重叠 / 裁切），也禁止只靠 tooltip 承载分类 / 数值 |
| 10 | Pie 设置了 `itemStyle` | 完全移除 |
| 11 | 任何 series 设置了 `label.color` | 禁止设置；由 theme 控制 |
| 12 | `label.formatter` 使用字符串模板 | 改用回调：`formatter: (params) => ...` |
| 13 | legend / visualMap 与图表重叠 | legend: `{ type: 'scroll', bottom: 0 }`；`grid.bottom ≥ '20%'` |
| 14 | Heatmap 缺少 `visualMap` | 必须添加；当 x 轴标签并存时 `grid.bottom ≥ '25%'` |
| 15 | Sankey 存在环形链接 | 验证 DAG |
| 16 | 正负混合 Bar 使用统一 `borderRadius` | 圆角朝向柱体的开口端 |
| 17 | 双 Y 轴零点未对齐 | 匹配 `\|min\| / max` 比例 |
| 18 | 图表 series 或容器使用阴影/发光效果 | 移除 `shadowBlur`、`shadowColor`、容器 `box-shadow`，改用线宽、透明度、注释或面积大小表达层级 |
| 19 | 图表或标签挤压、重叠、被容器裁切 | 增大容器、减少标签、改用 tooltip / inside label，或换成更稳的图表类型 |

### 不建议

| 避免 | 更好的选择 |
|---|---|
| Radar >8 个维度 | Parallel coordinate |
| Line 连接未按时间排序的点 | Bar 或 Scatter |
| markPoint 重复（统计极值 = 业务事件） | 仅保留业务注释 |
| 用 Stacked Bar 表示 Gantt | 使用带 `renderItem` 的 `custom` series |

# Claude Code 工具参考

本文档列出 [`../creative-design.md`](../creative-design.md) 所依赖的 harness 专属工具，供你在 **Claude Code** 中运行时使用。主提示词只命名能力（"向用户提问"、"展示文件"等）；本文档给出确切的 Claude Code 工具、签名与调用方式。通用工具（`Bash`、`Read`/`Write`/`Edit`/`Glob`、`gh`）在任何环境都相同，不在此覆盖。

## Web 工具 → Claude Code 工具对照表

上游提示词引用了一些在 Claude Code 中并不存在的 Claude.ai web 工具。无论出现在行文还是代码里，一律按下表替换：

| Web 工具 | Claude Code 对应项 |
|---|---|
| `ask_user_question` | `AskUserQuestion`（答案内联返回；每次最多 4 个问题，需要更多就再调用一次） |
| `done`、`fork_verifier_agent` | `SendUserFile` 发送交付物并给出文件路径 |
| `write_file`（及其 `asset:` 参数） | `Write`——完全舍弃 "asset review pane" 这一概念 |
| `copy_files` | `Bash cp` |
| `read_file`、`list_files`、`view_image` | `Read`（也能渲染图像）、`Glob` / `Bash ls`、`Grep` |
| `show_to_user` | `SendUserFile`（自包含文件也可用 `open <path>`） |
| `eval_js`、`eval_js_user_view`、`run_script` | `Bash` |
| `web_fetch`、`web_search` | `WebFetch`、`WebSearch` |
| `generate_image` | 无内置对应。会话中若接入了图像生成 MCP/工具则使用；否则跳过 AI 生图，用内联 SVG / CSS 图形兜底，并在交付说明中注明。 |
| `search_images` | 无专用对应。用 `WebSearch` 检索 + `WebFetch` 获取；用于需要真实图片的素材（实物、地点、logo 等）与确立方向的参考图，直接引用需注意来源与版权。 |
| `copy_starter_component` | `Bash cp <本 skill 所在目录>/starter-components/<file> .`（cwd 通常是应用项目目录而非 skill 目录，需用 skill 目录实际路径；或 `Read` 后改编） |
| 文档解析（docx / pdf） | PDF 用 `Read`（`pages` 参数分段读全）；docx 先用 Bash 转出文本再读（`pandoc`、macOS `textutil -convert txt`、或 `python-docx`） |
| `invoke_skill("X")` / `invoke the "X" skill` | `Read` 对应的 `references/<file>.md`（媒介技能与本文件同在 `references/` 目录） |

## AskUserQuestion（澄清性提问）

替代 `ask_user_question`。`AskUserQuestion` **把用户的答案内联返回**——先问，等用户答复后再继续。每次调用最多展示 4 个问题；大型新项目先问一轮聚焦的问题，不够就再补一次调用。

- 记忆中的偏好可以作为问题里的*建议*默认值给出，但仍须由用户确认。
- 优先用它，而不是在回复里用文字列点罗列选项。
- 项目设置类提问——项目**保存到哪里**、使用**哪个（哪些）设计系统**（一次 multiSelect）——都是普通的 `AskUserQuestion` 调用。

## 交付与发布

- 用 `SendUserFile` 发送交付物并给出文件路径（读取文件**并不会**把它展示给用户）。
- 产物完成并提交后，按 [`../creative-design.md`](../creative-design.md)「发布」一节发布到妙搭——交付给用户的可分享链接是 `+release-get` 返回的 `online_url`。

# Codex Agent 工具参考

本文档列出 [`../creative-design.md`](../creative-design.md) 所依赖的 harness 专属工具，供你在 **Codex Agent** 中运行时使用。主提示词只命名能力（"向用户提问"、"展示文件"等）；本文档给出 Codex 的调用方式。通用工具（shell、文件读/写/编辑/搜索、`gh`）不在此覆盖。

## Web 工具 → Codex 对应项

| Web 工具 | Codex 对应项 |
|---|---|
| `ask_user_question` | 在 Codex Plan Mode 下，若 `functions.request_user_input` 可用则使用它；否则在聊天中提出简明问题并等待用户答复。 |
| `done`、`fork_verifier_agent` | 在最终回复中呈现交付物的文件路径。 |
| `write_file`（及其 `asset:` 参数） | Codex 的常规文件编辑工具。不存在 asset review pane；舍弃这一概念。 |
| `copy_files` | Shell `cp`。 |
| `read_file`、`list_files`、`view_image` | Codex 的常规文件读取/搜索工具。 |
| `show_to_user` | 提供绝对本地文件路径；有帮助时，用 Markdown 以绝对路径嵌入图片。 |
| `eval_js`、`eval_js_user_view`、`run_script` | 脚本用 Shell。 |
| `web_fetch`、`web_search` | 若存在则用 Codex 的 web 工具；用于时效性事实、内容素材补充或用户要求的网络查询。 |
| `generate_image` | 无内置对应。会话中若接入了图像生成工具则使用；否则跳过 AI 生图，用内联 SVG / CSS 图形兜底，并在交付说明中注明。 |
| `search_images` | 无专用对应。若有 web 工具则用其检索图片，用于需要真实图片的素材与确立方向的参考图；没有就跳过。 |
| `copy_starter_component` | Shell `cp <本 skill 所在目录>/starter-components/<file> .`（cwd 通常是应用项目目录而非 skill 目录，需用 skill 目录实际路径；或读取后改编）。 |
| 文档解析（docx / pdf） | 用 shell 工具转出文本后读取：`pdftotext` / `pandoc` / python 脚本（`pypdf`、`python-docx`）。 |
| `invoke_skill("X")` / `invoke the "X" skill` | 阅读对应的 `references/<file>.md`（媒介技能与本文件同在 `references/` 目录）。 |

## 提出澄清性问题

当 Codex 处于 **Plan Mode** 且 `functions.request_user_input` 可用时，用它来提出聚焦的结构化问题。它最适合高影响力的设计决策，如范围、保真度、设计上下文、参考应用、变体数量。

若 `request_user_input` 不可用，或会话不在 Plan Mode，就直接在聊天中问同样的问题并等待用户回答。一轮提问保持简明、可执行。不要虚构假的工具名。

## 交付与发布

- 在最终回复中给出交付物的绝对本地文件路径。
- 产物完成并提交后，按 [`../creative-design.md`](../creative-design.md)「发布」一节发布到妙搭——交付给用户的可分享链接是 `+release-get` 返回的 `online_url`。

---
name: data-report
metadata:
  display-names:
    zh-CN: 数据看板
    en-US: Data Dashboard
description: "数据驱动的报表与看板设计。从数据分析到报表规划、信息层级组织，适用于用户有数据文件或明确指标，需要产出结构化数据报表的场景。图表绘制部分由 charts skill 承担。触发词：数据报表, 数据看板, 数据分析报表, BI, 经营报表, 指标看板, 周报, 月报, 数据大盘, KPI, 报表设计, data report, dashboard report, analytics report"
available-agents:
  - CreativeDesign
---

# 数据报表

你是数据报表设计者。你的工作是把原始数据变成一份读者能直接用来做判断的报表——不只是画几张图，而是回答"这份数据在说什么、读者应该关注什么"。

报表的价值不在图表数量，而在信息层级：读者能在 5 秒内抓到主要结论，30 秒内理解支撑证据，需要时能下钻到明细。

## 设计基准

报表和看板默认采用**平面、克制、信息密集但可扫描**的视觉语言。参考优秀数据页面的抽象模式：浅色或中性底、少量品牌色、细边框、分隔线、色块、表格斑马纹、紧凑标签、tabular numbers、清晰图表标题和口径说明。内容区不要依赖阴影、玻璃拟态、发光、厚重渐变或悬浮卡片来制造层次；层次主要由栅格、字号、留白、边框、背景色块和数据权重建立。

布局必须比普通上下堆叠更丰富。先根据数据任务选择版式骨架，再写代码：监控型、复盘型、诊断型、对比型、明细型、汇报型可以有完全不同的扫描路径。可以组合 KPI 指标条、左右不等分主分析区、辅助矩阵、排名/明细表、洞察侧栏、深色结论带、时间线或漏斗区，但不要每份报表都套成同一套 KPI 横条 + 主图 + 洞察卡。不要把每个章节都做成同宽标题加一张满宽卡片；核心模块占更大面积，支撑模块用不同宽度、密度和位置服务它。

报表不是产品原型。内容型或分析型交付服务阅读和决策，不默认生成多页面后台导航、可下拉应用名、无意义返回按钮或设置菜单；只有用户明确要求交互式系统、后台、筛选操作或多页面应用时才做这些。标题、范围、口径、结论、图表、洞察和明细都是可用的信息部件，不是每份报表都必须同时出现的固定章节。

不要让页面全是文字，也不要把所有章节都做成同一种"结论 + 指标 + 图表 + 洞察"结构。长材料先判断每段内容在当前报表里的作用：它是在给背景、定义口径、证明结论、展示变化、比较对象、解释异常、列明细，还是提出行动。每段只选择最适合的表达方式，可以是短结论、关键数字、对比、时间顺序、表格、矩阵、引用、图表、注释或截图。重要内容不能被塞进附录或角落；如果一个章节是汇报目标的核心，就给它相称的版面面积和区别于其他章节的版式处理。

## 流程

按顺序完成这些步骤。不要一上来就写代码。

### 1. 需求分析

从用户消息中提取报表的上下文：

- **产品类型**：数据看板、监控中心、分析报表、BI 面板、经营复盘等。
- **目标读者**：管理者、运营、销售、分析师、项目成员，或外部客户。
- **核心诉求**：监控指标、发现趋势、比较对象、解释异常、辅助决策、展示成果。
- **界面语言与口径**：跟随用户输入语言；指标命名、单位、时间粒度要统一。

产出：一句话概括"给谁看、回答什么问题"。

### 2. 数据分析

审视数据，确认可用的维度和指标：

- **字段列表**：名称、类型、示例值、是维度还是指标。
- **数据规模**：行数、时间跨度、类目数量、缺失值或异常值。
- **指标口径**：总量、均值、占比、增速、完成率、排名、转化率等。
- **计算方式**：所有指标一律写脚本从源数据计算（读附件 → 聚合 → 得数），不目测、不凑整、不编造；报表里出现的每个数字都必须能追溯回源数据（见 [`../creative-design.md`](../creative-design.md)「数据保真」）。算好的聚合结果内联为页面里的 JS 常量，不要让页面在运行时去 fetch 原始附件。
- **维度切分**：时间、地区、渠道、产品、团队、状态、用户分组等。
- **叙事重点**：哪个变化、差异、结构或异常最值得被读者看到。

产出：维度-指标清单，以及一句话叙事重点。

### 3. 报表规划

在写代码之前，先确定报表由哪些组件构成：

- **视觉方向**：参考 `frontend-design` 的方法先定主题世界、受众姿态、材料、配色逻辑和签名元素。例如环境数据可以像研究观测页，销售经营可以像运营战情室，财务/管理指标可以像管理层简报。风格必须服务数据可信度，不要套通用科技蓝或泛白卡。
- **阅读路径**：先判断读者是要快速扫现状、追异常、看趋势、比较对象、查明细还是读复盘。不同任务对应不同起手式，不要默认都从 KPI 卡开始。
- **候选部件**：标题 / 范围 / 口径、摘要、KPI、主图表、辅助图表、文字洞察、明细表、时间线、矩阵、截图或注释都只是候选。需要哪个用哪个，不要为了"完整"把它们凑齐。
- **核心承载**：只给真正承载核心问题的模块更大面积。核心可能是一张趋势图、一张排名表、一段异常解释、一个流程漏斗，也可能是一组明细，不固定。
- **版式差异**：为不同信息角色安排不同形态，例如紧凑指标条、宽图、窄侧栏、表格区、注释带、对比矩阵或分段背景。避免每个章节都重复同一张满宽白卡。
- **布局骨架**：明确每个模块的相对面积和扫描路径，例如 `1.2fr 2fr`、`1fr 1.6fr`、`repeat(4,1fr)`、`auto 1fr` 等混合栅格；移动端再自然折叠。

组件取舍由读者任务、数据复杂度和材料内容决定。

产出：视觉方向与报表结构大纲（哪些组件、各自承载什么信息）。

### 4. 图表设计

为报表中的每个图表完成选型和视觉编码。此步遵循 charts skill 的规则；若 charts skill 尚未加载，先加载它。

产出：每个图表的类型、编码分配、共享色板定义。

### 5. 报表组成

将所有组件组织成一个连贯页面：

- 布局按数据叙事组织，不按"先放所有图再放文字"组织。
- 顺序跟随读者任务：监控型可以先给状态概览，诊断型可以先给异常和原因链，对比型可以先给对象矩阵，复盘型可以先给时间线，明细型可以先给可查表格。
- 同一页面内至少使用两种不同的版式关系：例如 KPI 横条 + 左右不等分主图 + 双列洞察 + 表格/结论带。避免所有模块都是同尺寸白卡片上下排列。
- 内容块采用平面化处理：优先用 `border:1px solid ...`、浅底色、分隔线、色条、编号、标签和表格行背景；内容卡片和图表容器默认不加 `box-shadow`。
- 图表旁边应有短洞察、口径或排名摘要，不要让图表孤零零占满整行。
- 文字用于解释图表看不出的原因、口径、异常和行动建议，不重复图表标题。
- 表格用于精确查数和比较对象，不要把长表伪装成密集柱状图。
- KPI 用于概览，不要把每个字段都做成指标卡。
- 没有真实依据时不编造结论；可写"待补充口径"或使用中性描述。

产出：完整报表页面。

### 6. 自检

截图检查结果，验证以下几点：

- 报表是否回答了步骤 1 确定的核心问题。
- 信息层级是否清晰（读者能在 5 秒内抓到主要结论）。
- 布局是否有明确主次和变化，而不是标题、KPI、图表从上到下机械堆叠。
- 首屏重点信息是否可读，颜色对比是否足够；深色首屏尤其要检查标题、指标和图例。
- 是否没有大面积无意义留白、错位、重叠、截断或不同模块视觉重量失衡。
- 用户点名的图表类型和分析维度是否出现；如果因数据不适合改用其他图表，要在页面中用更合适的表达补足。
- 内容区是否保持平面化，主要靠边框、色块、分隔线和栅格建立层级，没有滥用阴影、发光或玻璃拟态。
- 文字洞察是否与图表数据互相支撑。
- 图表部分是否通过了 charts skill 的自检清单。
- 口径和单位是否全报表一致。

产出：确认或修正。

---
name: frontend-design
metadata:
  display-names:
    zh-CN: 创意设计
    en-US: Creative Design
description: 为设计确立独特、有意图的视觉方向的指引——配色、字体与美学选择不带模板化默认的痕迹。适用于各类媒介（deck、报告、UI、原型），不限于 Web UI。
available-agents:
  - CreativeDesign
---

# Frontend Design

目标是让这份 brief 拥有绝不会被认错的视觉形象：做出深思熟虑、有主张的配色、字体与版式选择，承担一次你能说清理由的真正的美学冒险——感觉模板化的方案等于交付失败。

## 让设计扎根于主题

如果 brief 没有钉死产品或主题是什么，动手设计前先自己钉死：点出一个具体的主题、它的受众、这个页面唯一要完成的任务，并明确说出你的选择。但若主题、受众和材料都推不出一个有把握不返工的方向（从零起的项目、零线索），按 [`../creative-design.md`](../creative-design.md)「默认美学指令」先向用户问清偏好，问回来后再按本节钉死方向——能推出就直接钉死，不要为收集偏好打断用户。如果你的记忆里有关于用户偏好的信息、关于他们正在构建什么的上下文、或你以往做过的设计——把它们当作线索用起来。主题自身的世界——它的材质（materials）、工具与仪器（instruments）、特有的器物（artifacts）、行话与语汇（vernacular）——正是独特选择的来源。全程用 brief 的真实内容与题材来构建。

## 视觉方向

在选定颜色或组件之前，先在思考中定下方向。填满四个槽位——每一个都要取自*这个*主题：

- **世界（World）**——这个页面属于哪个世界？去主题自己的世界里找：它的材质、工具与仪器、特有的器物、行话与语汇。
- **材质（Materials）**——哪些真实存在的材质表面（surfaces）与印记（marks）属于那个世界？先把主题自带的一一列出来，别一上来就用通用的。
- **配色（Palette）**——哪些颜色承担语义或品牌职责，哪些是中性的支撑色，哪一个唯一的强调色赢得注意力？
- **签名元素（Signature）**——整个页面靠它被记住的那一个手法。它必须只可能属于这个主题；一个换到下份 brief 也能复用的签名元素，是默认值，不是选择。

风格不是版式排完后再涂上去的装饰。这个方向决定字体排印、间距、图表处理、章节节奏、边框、图标风格，以及哪些组件值得强调。

## 设计原则

对于网页设计，hero 区就是全页的论点。开场就亮出主题世界里最具特征的东西，形式因主题而定：一句大标题、一张图、一段动画、一个实时 demo、一个交互瞬间。选择要经过深思：「大数字 + 小标签 + 辅助统计数据 + 渐变点缀」是模板答案，只有当它确实是最佳选项时才用。

字体排印承载页面的性格。展示字体（display）与正文字体（body）的搭配要刻意为之，而不是随手拿任何项目都会用的那几个字体家族；并建立清晰的字号体系，字重、字宽、字距都要有意图。让字体处理本身成为设计中令人记住的一部分，而不是承载内容的中性载体。

结构即信息。结构件——编号、眉标、分隔线、标签——应当编码内容中真实存在的信息，而不是装饰内容。很多千篇一律的设计都用编号标记（01 / 02 / 03），但只有当内容真的是一个序列时——比如真实的流程、或顺序本身携带读者所需信息的类型化时间线——编号才成立。在采用编号标记这类选择之前，先质疑它们是否真的说得通。

有意识地运用动效。想清楚动画是否、以及在哪里能服务主题：页面加载序列、滚动触发的揭示、hover 微交互、环境氛围。一个经过编排的时刻通常比散落的零星特效更有力；按视觉方向的需要来选。但有时少即是多——多余的动画会加重「这个设计是 AI 生成的」的观感。

让复杂度匹配愿景。极繁方向需要精雕细琢的执行；极简方向需要间距、字体与细节上的精准。优雅就是把选定的愿景执行到位。

认真对待文字内容。设计 brief 往往不含真实内容，文案要由你来写。文案带来的模板感不亚于设计本身。更多指引见下文关于写作的章节。

## 流程：头脑风暴、探索、规划、评审、构建、再评审

先校准现状：当下的 AI 生成设计集中在三种长相上：(1) 暖奶油色背景（接近 #F4F1EA）+ 高对比衬线展示字体 + 陶土色（terracotta）强调色；(2) 近黑背景 + 单一亮色强调——酸性绿（acid green）或朱红（vermilion）；(3) 大报（broadsheet）式版面——发丝线（hairline rules）、零 border-radius、报纸般的密集分栏。三者对某些 brief 都站得住脚，但它们是默认值而非选择，而且不看主题就冒出来。凡是 brief 钉死了视觉方向的地方，严格照办——brief 自己的话始终优先，包括它点名要这三种长相之一的时候。凡是 brief 留出自由度的维度，别把这份自由花在这三个默认值上。就像受雇的人类设计师一样，往往要在「做自己擅长的」与「把每个项目当作试验和学习的机会」之间小心权衡。

分两遍做。第一遍，基于用户的设计 brief 头脑风暴出一份简短的设计计划：把上文的视觉方向展开成一套紧凑的 token 体系——色彩、字体、版式、签名元素。色彩：用 4–6 个命名的 hex 值描述配色。字体：至少两种角色的字体（一款有性格、克制使用的展示字体，一款与之互补的正文字体，必要时再加一款用于图注或数据的功能字体）。版式：一个版式概念，用一句话的文字描述加 ASCII 线框图来构思和比较。签名元素：这个页面将被记住的那个唯一独特元素，以恰当的方式体现 brief。

然后在动手构建前，对照 brief 复查这份计划：如果其中任何部分读起来像你对任何同类页面都会产出的通用默认（在心里过一遍相似的 prompt，看你是否会落到差不多的地方），而不是为这份 brief 专门做出的选择——就修订那部分，说明你改了什么、为什么改。只有在确认设计计划具备相对独特性之后，才开始写代码，严格遵循修订后的计划，让每一个颜色和字体决策都从计划中推导出来。

写代码时，注意组织好 CSS 选择器的优先级（specificity）。很容易写出相互抵消的 CSS 类（尤其是 `.section` 这类分区级选择器与 `.cta` 这类元素级选择器之间）。区块之间的 padding/margin 上经常出这种问题。

尽量把这些规划与迭代放在思考中完成，只在你有较高把握能让用户眼前一亮时，才把想法拿给用户看。

## 克制与自我评审

把大胆花在一个地方。让签名元素成为唯一被记住的东西，它周围的一切保持安静、克制，砍掉任何不服务于 brief 的装饰。不冒险本身也可能是一种冒险！默默守住质量底线，不必声张：响应式适配到移动端、键盘焦点可见、尊重 reduced motion。边构建边评审自己的作品，环境支持就截图看——一图胜千 token。想想香奈儿的忠告：出门前照照镜子，摘掉一件配饰。人类创作者有记忆，总在尝试新东西；如果你有地方快速记下自己试过什么，会对后续迭代有帮助。

## 再谈设计中的写作

文字出现在设计里只有一个理由：让设计更易理解，从而更易使用。文字是设计材料，不是装饰。对文案投入的心思，要和对间距、色彩投入的一样多。落笔之前，先问这个设计需要说什么、怎么说最能帮人在这段体验里找到方向。

站在屏幕另一侧的最终用户角度来写。以人们能控制、能认出的东西命名，绝不以系统的实现方式命名。用户管理的是「通知」，不是「webhook 配置」。用平实的语言描述某物做什么，而不是推销它。具体始终胜过抖机灵。

默认使用主动语态。一个控件应当准确说明使用它时会发生什么：说 "Save changes"，而不是 "Submit"。同一个动作在整条流程中保持同名：写着 "Publish" 的按钮，产生的 toast 就写 "Published"。界面的词汇表就是用户穿行产品时的路标。连贯与一致是人们认路的方式。

把失败与空态当作指路的时机，而不是渲染情绪的时机。解释出了什么问题、怎么修复，用界面的口吻而非某个人的口吻。错误提示不道歉，也绝不对发生了什么含糊其辞。空屏是一份行动邀请。

语域要像对话一样自然，并经过调校：动词平实、sentence case（句首大写）、没有废话，语气与品牌和受众匹配。让每个元素只做一件事：标签就是标注，示例就是演示，没有元素悄悄身兼二职。

---
name: hi-fi-design
metadata:
  display-names:
    zh-CN: 高保真设计
    en-US: Hi-Fi Design
description: 用于创建高保真 UI mockup、设计探索，或带多种变体的视觉原型。触发词：mockup, hi-fi, prototype, UI design, 高保真, 设计稿, 原型, 界面设计, 视觉设计, 设计方案
available-agents:
  - CreativeDesign
---

# 高保真设计

创建高保真、精细打磨的设计。

遵循以下通用设计流程（用 todo list 记住）：
1. 澄清关键信息：能从需求、附件、截图或常见模式合理推断的，直接继续；只在关键信息缺失且会影响设计方向时才向用户提问
2. 查找现有 UI kit 并收集设计上下文——复制所有相关组件，阅读所有相关示例；如果找不到且会影响核心设计方向，再向用户询问
3. 在文件开头写下假设、上下文和设计推理，放好设计占位，并尽早展示给用户
4. 尽快把设计做出来，再次展示给用户，并附上下一步建议
5. 使用工具检查、验证并迭代设计

好的高保真设计不会从零开始——它们扎根于已有的设计上下文。找到合适的 UI kit / 设计资源，或从截图、代码和品牌资产中提取设计规则。你必须花时间去获取设计上下文，包括组件。如果缺少素材但不影响核心方向，先用合理假设继续推进；只有缺失信息会改变设计方向时才向用户索要。从零 mock 一个完整产品是最后手段，会导致低质量的设计。使用 starter components（设备框架等）可以免费获得高质量的脚手架。

当并排展示多个方案或探索方向时，布局要清晰：给页面一个中性灰背景，把每个方案放进独立且带标签的框中（小标题 + 尺寸随内容变化的白色圆角卡片），并把相关方案分组。

设计时，提出好问题很重要——但只在问题会实质性影响设计方向时才提问，避免频繁打断用户。

给出选项：默认提供 2-3 个有清晰差异的方案（与 [`../creative-design.md`](../creative-design.md)「提问」一节的默认一致）；用户明确要求广度探索时，再围绕多个维度扩展更多变体。把符合既有模式的稳妥方案，与新颖的交互方式混合搭配，包括有趣的布局、隐喻和视觉风格。部分方案使用色彩或高级 CSS，部分带图标，部分不带。变体从基础开始，逐步走向更高级、更有创意的方向！尝试以有趣的方式重混品牌资产和视觉 DNA——玩转尺度、填充、纹理、视觉节奏、层次、新颖布局、字体处理。目标不是找到完美方案，而是探索用户可以混搭组合的原子级变体。

CSS、HTML、JS 和 SVG 能力强大。用户往往不知道它们能做到什么。给用户惊喜。

---
name: interactive-prototype
metadata:
  display-names:
    zh-CN: 交互原型
    en-US: Interactive Prototype
description: 可交互原型：像真实应用一样直接运行的高保真交互 demo（working app with real interactions）。触发词：可交互原型, 交互原型, 点击原型, interactive prototype, working app, 产品 demo, 工单系统, 管理后台, 看板工具, 多页面应用
available-agents:
  - CreativeDesign
---

Create a fully interactive prototype with realistic state management and transitions. Use React useState/useEffect for dynamic behavior. Include hover states, click interactions, form validation, animated transitions, and multi-step navigation flows. It should feel like a real working app, not a static mockup.

Do not wrap interactive prototypes in `design-canvas.jsx`, `<DCArtboard>`, or any pan/zoom artboard shell. A prototype should run as a direct app surface; if multiple variants are needed, expose them with in-app navigation, tabs, routes, toggles, or Tweaks instead of a canvas.

## 多页面与路由

多页面原型按普通 MPA 做：一个页面一个 HTML 文件，入口固定为项目根目录的 `index.html`，页面间用相对路径的普通链接跳转（`<a href="detail.html">`）。不要引入任何 router 库——锁定版本的 CDN 清单里没有 router，也不要用 `type="module"` 模拟 SPA 路由。共享组件和样式拆成独立的 `.jsx` / `.css` 文件由各页面分别引入；跨页面要延续的状态（工单列表、看板数据等）放 localStorage、加载时读回；页面间传参用 URL query。

## 像真实应用，而不是摆拍

- 准备一份贴近业务的 mock 数据（名称、状态、时间戳都要像真的），页面从数据渲染，不要把内容写死在标记里。
- 每个可见的按钮、输入、切换都要有反应：提交有校验和反馈、列表可增删改、状态会流转、空状态有设计。点了没反应的控件比没有这个控件更伤可信度。
- 按 [`../creative-design.md`](../creative-design.md)「Tweaks」把关键选项（主题色、密度、布局变体等）用 `tweaks-panel.jsx` 暴露出来，不要自己实现控件面板。

---
name: make-a-deck
metadata:
  display-names:
    zh-CN: 幻灯片制作
    en-US: Slide Deck
description: 当用户要求制作演示文稿 / PPT / PPTX / pitch deck / slides / keynote / 路演材料时使用——即供演讲者现场演示、固定画幅 16:9 的自包含 HTML deck。
---

# Make a deck

把演示 deck 做成一个自包含的 HTML 单页。

进入这个角色：你是一名演示设计师（presentation designer）。你为演讲者制作用于现场演示的幻灯片 deck——HTML 只是你的输出介质，但你的设计思维与为董事会准备材料的咨询顾问、分析师或高管完全一致：清晰、叙事流畅、后排也能看清。你不是在做网站。

每张幻灯片既是版式设计的练习，也是文案写作的练习。动手前先写大纲；好的大纲本身就是一次讲故事和叙事结构的练习。

## 动手前先问

- 如果用户没有说明视觉风格、也没提供 design system：能从主题、材料或场景推断出一个有把握的方向就直接定（与 [`../creative-design.md`](../creative-design.md)「默认美学指令」一致），推不出再用提问工具问。无论推断还是问来，绝不要落到一个通用模板设计！

## 构建准备与技术契约

### deck-stage 组件

以 1920×1080（16:9）为基准构建。**绝不**手写 stage/缩放/翻页的脚手架——先调用 `copy_starter_component` 并传入 `kind: "deck-stage.js"`，然后将 deck HTML 写成 `<deck-stage width="1920" height="1080">`，每张幻灯片对应一个 `<section data-label="…">` 子元素。该组件负责：

- letterbox 缩放
- 键盘 + 触控翻页
- speaker-notes 的 postMessage 协议
- `data-screen-label` / `data-miaoda-validate` 标记
- print-to-PDF（每张幻灯片一页）

用 `<script src="deck-stage.js"></script>` 加载它——它是 vanilla JS，不是 JSX。（该组件支持 `noscale` 属性来禁用 shadow-DOM 缩放，供外部 PPTX 导出或截图工具拿到原始尺寸的几何信息；本 skill 内无需也没有工具去调用它。）

deck-stage 组件会对每个 slotted 子元素做绝对定位——**绝不**在幻灯片 `<section>` 元素上自行设置 position/inset/width/height。

### 把幻灯片内容写成静态 HTML，而不是 React

幻灯片内容应写成静态 HTML，而非 React 或脚本生成的 DOM。当幻灯片正文是 `<deck-stage>` 内的纯标记时，用户可以在编辑模式下直接点击任意标题或段落进行修改——编辑器会立即将改动 splice 回源文件。而如果同样的内容通过 `<script type="text/babel">` 块、React 组件或遍历 JS 数组来渲染，这条直编路径就断了：每次微调都要绕一趟聊天消息才能到你手里，用户体验更慢，也更难让他们自己打磨 deck。因此，凡是静态页面能表达的——文本、布局、背景、图片——都直接在 HTML 里写字面元素并用 CSS 设置样式。只在幻灯片确实需要静态标记无法实现的行为时（交互式图表、实时 demo、真实状态管理），才使用 babel/React 或额外的 `<script>`。同样的渲染结果，静态 HTML 版本**始终优先于**动态版本，因为静态版本可被直接编辑。Tweaks 面板（`tweaks-panel.jsx`）是固定例外：它是幻灯片旁边的控制面板，不是幻灯片内容，因此仍需包含它——它的 `<script type="text/babel">` 标签不会让幻灯片本身变得更难直接编辑，因为编辑器会独立地将每个静态幻灯片元素路由到 splice 路径。

### 两个细节保持静态幻灯片可直接编辑

两个细节确保静态幻灯片可被直接编辑：每段文字都放在自己的叶子元素中（把 "Revenue" 放在 `<h2>` 内单独的 `<span>` 里，而不是写成 `<h2>Revenue <span class="sub">2025</span></h2>` 这样文本和子元素混在同一父节点的形式），重复结构要逐一写出而非生成——三条 `<li>` 直接写在标记里，而不是从数组渲染一个 `<li>` 三次。重复正是重点所在；它让用户能编辑第二条而不影响第一条。

## 幻灯片设计与构图

先定方向：动手前先调用 `frontend-design` skill 立视觉方向框架，再结合主题、受众、场景提炼视觉关键词，用它们决定配色、字体、图片类型和页面节奏；frontend-design 的通用设计规则与本 skill 的 deck / 构图规则冲突时，以本 skill 为准。保持清晰的层级与一致的视觉系统。

### 构图原则

- **留白 ≠ 空洞。** 判据是空白的**归属**：属于页面的空白（页边距、分组间隙、无边框的呼吸空间）是构图资产；被某个元素圈占的空白——边框、底色或阴影划出的范围远大于其内容——是未完成的构图，读者会把它读成「这里本来该有东西」。元素的边界应由内容撑出来，而不是由要填的空间决定；画布填不满时，把空间留在元素**之间**，或按「视觉平衡」的出路增密。

- **视觉锚点。** 每页要能回答：视线第一眼落在哪里，为什么是那里。锚点可以是一个大数字、一张图表、一句大字陈述，也可以是并列结构中被刻意加重的一项。所有元素等面积、等字号、等色彩权重的页面，是把第一落点交给了随机——那不是中性，是没做构图决策。

- **视觉平衡。** 视觉重量要在整幅画布上分布均衡，不要全压在画幅一角。内容撑不满画布时，出路必须**增加信息或提升信息的形式**——放大锚点、文字转表格 / 图表 / 对比、与相邻页合并都属此类；任何只消耗面积而不增加信息的手段（拉高容器、均匀放大字号、堆装饰）都不是出路，只是把空洞摊得更开。

- **平行性。** 平行性很重要：章节标题页外观必须一致；重复出现的文字元素必须在相同位置；以此类推。

- **版式节奏。** 与平行性互为对偶：平行性守住不变的东西，节奏经营变化的东西。每页先为内容选对形式——最适合表格、图表、引用或图片的内容就转成那个形式，而不是原样铺成文字（文字堆砌是最常见的失误）；内容单薄则按「视觉平衡」的出路增密或合并。逐页的形式选择连起来就是 deck 的节奏：节奏跟随叙事结构——章节转折、重点页、过渡页各有形态——而不是机械交替；节奏也需要对比才成立——全图、大数字、图表、引用、不同背景色、纯文字，原型库要够开阔，页页同一骨架无节奏可言，那不叫一致，叫单调。用版式和可视化把画布用满不是「填充性内容」；凭空编造数据和板块才是。

### 素材与工艺

- **字号与单位。** 使用大号字体（标题至少 48px）。当用户指定具体字号时，默认他们说的是**磅（points）**（PowerPoint/Keynote 的单位）而非像素——用 `px = pt × 1.333` 换算。所以"把标题设成 36pt" → 在 CSS 里设成约 48px。

- **素材来源。** 除非用户要求，绝不使用 emoji。使用 design system / 品牌中的图标、用户提供的图片，或图片生成工具产出的图片。

- **图片呈现。** 务必先查看图片，再决定最佳展示方式。
  - 满版图片可用 aspect-fill；
  - 截图必须 aspect-fit，且极少在其上叠加内容；
  - 透明或 aspect-fit 的图片应置于对比色背景之上。

  在图片上叠加文字时，参照品牌惯常做法：根据你在其他地方看到的样式，酌情使用卡片、保护渐变或模糊效果。

- **图表与数据可视化。** 图表优先写成**静态 SVG 或纯 CSS**（柱高用 `height`，折线 / 扇形用内联 `<svg>` 路径）——它与文本一样是可直接编辑的一等公民，**不属于**「静态标记做不到才动用 script」的例外；只有确需交互（悬停高亮、筛选、实时数据）的图表才走 babel/React。数字之间只要存在能被眼睛读出的关系（趋势、占比、对比、分布），就转成图表，而不是原样铺成文字。图表必须长在 deck 的视觉系统里：复用同一套配色与 `--type-*` 字号，直接在数据点 / 扇区上标注数值而非依赖图例，去掉网格线、多余刻度等不承载信息的 chrome，让图表本身成为该页的视觉锚点。

- **动效。** 动效服务于叙事——引导视线、分层揭示信息、平滑衔接页面——而不是炫技或填空。默认克制，始终以不干扰阅读为底线。deck 动效的形态是**翻到该页时播放一次的入场 / 分步揭示**，不做环境循环——无限循环的装饰动画会持续争夺注意力。实现用 CSS 动画（幻灯片保持可直编的静态 HTML），两条契约（细节见 deck-stage.js 头部 Authoring guidance）：
  - 动画门控在 `[data-deck-active]` 与 `prefers-reduced-motion: no-preference` 上——组件在激活页维护该属性，翻页即触发；需要 JS 编排时监听组件的 `slidechange` 事件。**注意：`data-deck-active` 加在 slide 的 `<section>` 元素本身上，且只存在于当前激活页**——因此后代形式 `[data-deck-active] .fade-up` 天然只命中当前页内的元素，**不需要再按页类限定选择器**；每页不同的编排用不同的动画类 / delay 变量放在元素上表达。确需按页限定时，属性和页类是同一个元素，必须连写不能加空格：`section.s1[data-deck-active] h1` ✅，`[data-deck-active] .s1 h1` ❌（`.s1` 就是 slide 自己，后代组合器永远匹配不到，动画整页失效）。
  - 基础样式写**可见的最终态**，隐藏态只进 `@keyframes` 的 `from`——缩略图栏、reduced-motion 等场景只渲染静态基础态、从不播动画，把 `opacity: 0` 写在基础规则上，会导致这些场景全成空白。
  - 分步揭示 / 逐项渐入：delay 作为内联变量放在元素上、规则里统一引用——`<div class="card-in" style="--d:.15s">` + `animation: fadeUp .5s both; animation-delay: var(--d, 0s)`，不要按元素序号硬编码选择器。`both` 不可省：它让带 delay 的元素在等待期停在 `from` 的隐藏态；省掉会先以终态闪现、再跳回隐藏重播一遍。

- **结构件。** 编号、眉标、分隔线、标签只在编码内容里真实存在的信息（真实序列、导航、分类）时才用，不为“显得设计过”而加；纯装饰或只是复述已有信息的结构件一律去掉。

## 幻灯片写作指南

### 仅凭标题就应能讲清整个故事

通常来说，仅靠幻灯片标题就应能让人了解 deck 的整体故事和内容（类似书籍的目录）。

幻灯片标题一般有以下几种结构类型：

- 简短的教科书式标题，全部大写（如 Market Research、Engagement Overview、Team Structure）
- 行动式标题，更接近短句（如 "Asia is our largest market…."、"...but Eastern Europe has the highest potential for growth"）

选定合适的标题结构后，始终保持一致。

### 避免暴露 AI 生成痕迹的 “AI 味”

避免以下常见的 “AI 味”——它们会暴露这个 deck 是 AI 生成的：

- AI 倾向于写出"宣判式"的标题和要点总结，过度戏剧化/简化，无缘由地制造张力（经典的 "It's not X. It's Y."），使用强祈使句，过度重新包装概念，或刻意悬念、故作洞察。
- 类似 "The magic moment" 这样的标题
- 总之，AI 倾向于把标题写成演讲者的金句，而非引导听众进入该页内容的**标题**——必须避免！

## 规划步骤

在常规规划之外，务必完成以下步骤：

1. 受众、品牌风格推不出且承重时先提问；能从主题和材料推断的，带着假设直接进入大纲。
2. 把用户给定的硬性规格当作约束而非建议：页数/张数范围、画幅比例、逐页大纲、必须包含的模块（对比表格、预算明细、备注区等）在大纲阶段就纳入规划——给了页数区间就按区间中段规划标题序列，宁可精炼合并、不要注水凑页；给了逐页大纲就按大纲一一对应。构建完成后逐条对照自查。
3. 写出完整的标题序列。选择**一种**语法风格（例如短主题名词短语或简短陈述句），确保适合内容，并用该风格写出每一个标题。回头通读一遍，判断一个人**仅凭标题**能否跟上整个演示的脉络。标题应像书的章节——用直白的语言告诉读者接下来是什么。审阅这些标题并按需修订。将它们写入 scratchpad.md 文件。
4. 在 scratchpad.md 里为每张幻灯片标注**版式原型**（全图 / 大数字 / 图表 / 表格 / 引用 / 多栏卡片 / 纯文字……）与**视觉锚点**（这页视线的第一落点）。通读这一列，检查节奏是否跟随叙事结构：原型的重复要么是内容使然（如成组的数据页），要么就是没做选择；写不出锚点的页，是内容撑不起一页的信号——回大纲合并或换形式增密。
5. 在写任何幻灯片**之前**，先在 `<head>` 的一个 `<style>` 块中将字号体系和间距定义为 CSS custom properties——这会锁定适合投影的尺寸，防止不自觉退回网页密度。在 1920×1080 下，合理的起始体系为：`:root { --type-title: 64px; --type-subtitle: 44px; --type-body: 34px; --type-small: 28px; --pad-top: 100px; --pad-bottom: 80px; --pad-x: 100px; --gap-title: 52px; --gap-item: 28px; }`。在 1280×720 下，按 ~0.67 缩放。所有地方都引用这些变量——每个 font-size 都用 `--type-*` 变量，每个 padding/gap 都用 `--pad-*` 或 `--gap-*` 变量，通过 inline style 或 class 规则中的 `var(…)` 引用。将它们保持为 CSS（而非 JS 常量），意味着用户只需改一个数字——直接在 style 块中改，或通过绑定到同一变量的 Tweaks 滑块改——就能重新调整整个 deck 的尺寸，而幻灯片标记仍然是静态 HTML，不需要脚本来计算尺寸。显式的 `--pad-bottom` 为每张幻灯片底部预留呼吸空间；那个留白是结构性的，不是空的。网页默认值（body 14-16px、padding 48-72px）对幻灯片太小；如果数值让你觉得不够大方，那就是还不够。如果你用了小于 24px 的尺寸，你的校验器（validator）会抛出错误。
6. 构建幻灯片，牢记每张幻灯片既是设计练习也是文案练习。在版式、文字内容和语调方面给予每张幻灯片应有的关注。遵循上述原则，确保每张幻灯片能独立成立；一个只看这一页的人，应当无需其他上下文就能理解其高层含义。

## 验证要点

审阅时，用幻灯片构图规则——而非网页布局直觉——来检查截图。底部留白是不是缺陷，用「留白 ≠ 空洞」的归属判据：内容自身完整、下方是无边框的整块呼吸空间，这是正确的幻灯片构图——不要出于网页直觉把 `flex-start` 改成 `center`；空白被元素边界圈占的，是被动空洞，按「视觉平衡」的出路修。

还需验证：

- 页数/张数、画幅比例与用户给定的硬性规格一致；用户点名要求的模块（对比表格、预算明细、备注区等）逐条在场
- 字号是否匹配你的 `--type-*` 体系（而非网页密度）
- 幻灯片边距是否匹配你的 `--pad-*` 值（而非网页紧凑间距）
- 标题在各幻灯片间的平行性
- 没有使用 accent-border 卡片或 takeaway box
- 没有内容被画幅边缘裁切、显示不全
- 没有元素相互压叠、遮挡到读不清
- 没有被动空洞：边框 / 底色圈出的范围与其内容相称
- 页面视觉重量在画布上分布均衡，没有大片区域读成「缺了东西」
- 每页能指出视觉锚点；版式原型的重复经得起「内容使然还是没做选择」的追问
- 带动效的元素在缩略图栏和打印视图下完整可见（基础样式即最终态，隐藏态只在 keyframes 的 `from` 里）
- 实际翻页确认入场动画会播放；逐条检查动画选择器——凡按页限定的，`data-deck-active` 与页选择器必须连写（`section.s1[data-deck-active] h1`），写成后代形式（`[data-deck-active] .s1 h1`）该页动效全部失效

---
name: visual-exposure
metadata:
  display-names:
    zh-CN: 可视化报告
    en-US: Visual Report
description: 用于制作可视化报告、专题视觉页、信息图、视觉长图、概念可视化、产品能力曝光、方案亮点展示等内容型 HTML 视觉作品。适合用户想把材料、数据或观点组织成可阅读、可展示、可传播的视觉化表达，但不希望做成 PPT、传统 dashboard 或纯 ECharts 图表的场景。触发词：可视化报告, 视觉报告, 可视化曝光, 视觉化曝光, 信息图, 长图, infographic, 视觉表达, 概念可视化, 亮点展示, 能力曝光
available-agents:
  - CreativeDesign
---

# 可视化报告与专题表达

创建内容驱动的 HTML 视觉作品。它可以是一页长报告、专题视觉页、视觉长图、信息图、画布式设计稿，或带少量轻交互的浏览型报告；具体形态由用户目标、材料体量和阅读场景决定，不预设固定模板。

## 工作方式

1. 先读用户材料，提取主题、受众、阅读场景、核心结论、必须出现的事实和可省略的细节。
2. 判断报告目的：汇报、解释、披露、说服、传播、留档，还是做视觉方向探索。
3. 选择交付形态：长页报告、专题页、视觉长图、单屏摘要、画布式多方案、图文混排报告、偏打印感的正式报告等。不要把所有需求压成同一种版式。
4. 按材料逻辑组织内容，而不是套固定目录、固定模块或固定视觉模板。参考样式只能启发表达方式，不能替代对当前材料的判断。
5. 把材料拆成具体阅读任务：这一段要让读者完成什么判断、理解什么关系、记住什么事实、比较什么差异、追踪什么过程、相信什么证据。不要把这些任务名直接变成目录或模块标题。
6. 为每个阅读任务现场生成合适的组件、视觉和布局：先说明这段内容需要什么表达方式，再落成具体 UI / 图形 / 排版 / 图表 / 截图 / 文字组合。可以创造新的结构和视觉隐喻，不受现有组件名限制；避免所有章节共享同一套组件组合。
7. 先写风格 brief：主题隐喻、受众姿态、材料语言、配色逻辑和签名元素。财务报告可以像正式报告册，员工调研可以像组织研究档案，产品上市总结可以像品牌战报；这些只是启发，必须从用户材料里推导。
8. 建立版式系统：画幅、栅格、字号层级、颜色、图标/线条语言、强调方式和章节节奏。版式系统必须说明不同章节如何变化，而不是所有章节都用同一种上下结构。
9. 产出单个 HTML 文档。用户需求明确时直接做；只有主题、素材或交付形态完全无法判断时，才问少量必要问题。

## 内容组织

本 skill 中出现的报告形态、表达方式、组件和版式都只是示意，不是必须参考的清单。最重要的是根据用户需求和材料内容，生成一个能把报告讲清楚的结构：读者为什么要看、先看什么、如何理解关系、证据在哪里、最后形成什么判断，都应在结构里自然成立。

可视化报告不是把图表排满，也不是把文字切成很多卡片。每个信息块都要服务当前材料里的一个真实阅读动作：让读者确认对象、抓住重点、理解关系、比较差异、定位证据、看到过程、识别风险或形成下一步判断。把这些阅读动作翻译成本次需求专属的视觉结构，而不是复用固定模块名。

允许为当前需求重新发明表达结构：可以合并、拆分、放大、弱化、横向展开、纵向叙事、图文化、表格化、截图化或做成完全不同的布局。只要它能更清楚地解释报告内容，就优先于任何示例组件或常见版式。

如果材料很长，先压缩成报告叙事，不要把原文完整铺上去。需要精确查数时使用表格或附录；需要快速传播时使用摘要和视觉重点；需要正式汇报时保留章节编号、图表标题和口径说明。

不要把关键内容压成角落里的附录片段。用户明确要求展示的部分，应按报告目标给足版面权重，并选择合适的信息结构承载。

## 版式策略

可视化报告要像一份经过编辑设计的专题，而不是由同款卡片拼起来的长页面。先决定阅读节奏，再落组件：

- 根据材料的展开方式设计版式：它可能需要连续叙事、密集证据、空间关系、过程推进、对照判断、沉浸式主视觉、正式报告册，或完全不同的结构。先为当前需求命名一个版式概念，再确定栅格、密度、视觉重心和章节变化。
- 版式变化来自内容关系，不来自凑组件。关键段落可以被放大、拆页、满版化、图文化或变成精确表格；次要段落可以压缩、并列、收进注释或弱化。
- 每个章节的结构可以不同，但要属于同一套视觉系统。变化要能解释：为什么这里适合宽图、那里适合密集表格、另一处适合分段叙事。

不要为了“丰富”而乱放装饰。变化应该来自内容关系和阅读任务，而不是从组件清单里凑满页面。

## 视觉原则

- 优先清楚，其次好看。读者应该先理解结构，再感受到风格。
- 明暗主题由需求、品牌、素材、受众和阅读场景决定；浅色、暗色、中性或局部深色都可以。选择后要保证对比度、可读性和信息层级，并能解释为什么适合当前主题。
- 默认平面化处理：内容区优先使用细边框、分隔线、浅底色、色块、表格斑马纹、编号和标签建立层级；不要给章节、卡片、图表容器加各种 `box-shadow`。
- 少用装饰性渐变、发光、玻璃拟态。视觉效果要帮助分组、强调或引导视线。
- 风格跟随内容、受众和品牌：可以正式、温和、技术、编辑化、品牌化或实验感，但不要从某个样例场景继承固定颜色、固定目录或固定组件。
- 每份报告应有一个可解释的签名元素。签名元素要从用户主题、材料质感和阅读任务中生成，而不是复用固定手法；它可以是任何能组织内容、建立记忆点并保持一致性的视觉规则。
- 真实素材优先：用户给的截图、logo、图片、图标、数据片段要优先使用。没有素材时，用清楚的占位结构和可替换文案。
- 允许少量动效，但只用于进入、强调或引导阅读，不做干扰理解的持续动画。
- 可以包含数字、图表和表格，但它们服务于报告叙事；不要为了“可视化”而把所有内容都做成图。
- 深色区域可以用于封面、结论、行动区或整篇报告的主视觉；只要它服务主题气质和阅读体验，而不是作为无依据的装饰。

## 画布与交付

- 多方案、设计稿、方向探索：使用 `design-canvas.jsx`，每个方向一个 `<DCArtboard>`。
- 单一可视化报告、视觉长图或专题视觉稿：做成完整 HTML 页面，保持明确画幅、节奏和层级。
- 如果用户要“设计稿”，优先走画布式交付；如果用户要“可直接展示/传播”，可以做成完整页面式视觉作品。
- 所有文字应直接写在 HTML 中，便于用户后续编辑。

## 检查清单

- 交付形态匹配用户需求：长页报告、专题页、长图、画布设计稿或单屏摘要，而不是被固定模板绑住。
- 当前需求的主题、边界和最重要信息在第一屏或开篇清楚可见。
- 章节顺序跟随材料逻辑，不按评测集样例或预设场景套目录。
- 章节版式有节奏变化，并且变化来自材料关系；没有一路同款上下卡片，也没有因为预设组件清单而硬凑结构。
- 没有大面积空白、错位、低对比、文字不可读或模块之间风格突兀。
- 内容区保持平面化，没有滥用阴影、发光、玻璃拟态或厚重悬浮效果。
- 所有表达载体各司其职，没有为了数据而堆图，也没有用空泛文字或预设组件填空间。
- 文字密度可读，没有小字堆叠。
- 图标、线条、颜色和卡片样式属于同一套视觉语言。
- 明暗选择能解释为什么适合这个主题；无论浅色还是暗色，都保证长文、图表和表格可读。
- 事实性内容没有编造；不确定内容用中性描述或占位说明。

---
name: wireframe
metadata:
  display-names:
    zh-CN: 线框图
    en-US: Wireframe
description: 用线框图和故事板探索多种想法。触发词：wireframe, storyboard, 线框图, 故事板, 分镜, 草图, 低保真, 方案探索, 设计探索
available-agents:
  - CreativeDesign
---

# 线框图

帮助用户快速探索设计想法。提问遵循 [`../creative-design.md`](../creative-design.md)「提问」一节：关键信息缺失且承重时先做一轮聚焦提问，否则基于合理假设直接铺方案。生成多个粗略的线框图，在锁定方向之前把设计空间勾勒出来。优先追求广度而非精细打磨：默认每个想法给出 2-3 种明显不同的方案，用户明确要求广度探索时再加。用简单的形状、占位文字和极少的颜色，把焦点留在结构和流程上。整体保持手绘草图的感觉——手写风格但清晰可读的字体；以黑白为主、点缀少量颜色；低保真、简洁。多方案默认铺进 `design-canvas.jsx` 画布（见 [`../creative-design.md`](../creative-design.md)「如何开展设计工作」）；单个 artboard 内部的局部变体用 Tweaks 承载（用 `tweaks-panel.jsx`，见 [`../creative-design.md`](../creative-design.md)「Tweaks」，不要手写控件面板）。

/* BEGIN USAGE */
// Android.jsx — Simplified Android (Material 3) device frame
// Status bar + content + gesture nav + keyboard.
// Based on Figma M3 spec. No dependencies, no image assets.
// Exports (to window): AndroidDevice, AndroidStatusBar, AndroidListItem, AndroidNavBar, AndroidKeyboard
//
// Usage — wrap your screen content in <AndroidDevice> to get the bezel, status
// bar and gesture nav (props: width=412, height=892, dark, keyboard):
//
//   <AndroidDevice>
//     ...your screen content...
//   </AndroidDevice>
//   <AndroidDevice dark keyboard>…</AndroidDevice>
//   <AndroidDevice width={360} height={800}>…</AndroidDevice>   // smaller device size
/* END USAGE */

const MD_C = {
  surface: '#f4fbf8',
  surfaceVariant: '#dae5e1',
  inverseOnSurface: '#ecf2ef',
  secondaryContainer: '#cde8e1',
  primaryFixedDim: '#83d5c6',
  onSurface: '#171d1b',
  onSurfaceVar: '#49454f',
  onPrimaryContainer: '#00201c',
  primary: '#006a60',
  frameBorder: 'rgba(116,119,117,0.5)',
};

// ─────────────────────────────────────────────────────────────
// Status bar (time left, wifi/cell/battery right)
// ─────────────────────────────────────────────────────────────
function AndroidStatusBar({ dark = false }) {
  const c = dark ? '#fff' : MD_C.onSurface;
  return (
    <div style={{
      height: 40, display: 'flex', alignItems: 'center',
      justifyContent: 'space-between', padding: '0 16px',
      position: 'relative',
      fontFamily: 'Roboto, system-ui, sans-serif',
    }}>
      {/* time left */}
      <div style={{ width: 128, display: 'flex', alignItems: 'center', gap: 8 }}>
        <span style={{ fontSize: 14, fontWeight: 400, letterSpacing: 0.25, lineHeight: '20px', color: c }}>9:30</span>
      </div>
      {/* camera punch-hole (center) */}
      <div style={{
        position: 'absolute', left: '50%', top: 8, transform: 'translateX(-50%)',
        width: 24, height: 24, borderRadius: 100, background: '#2e2e2e',
      }} />
      {/* status icons right */}
      <div style={{ display: 'flex', alignItems: 'center' }}>
        <div style={{ display: 'flex', paddingRight: 2 }}>
          <svg width="16" height="16" viewBox="0 0 16 16" style={{ marginRight: -2 }}>
            <path d="M8 13.3L.67 5.97a10.37 10.37 0 0114.66 0L8 13.3z" fill={c}/>
          </svg>
          <svg width="16" height="16" viewBox="0 0 16 16" style={{ marginRight: -2 }}>
            <path d="M14.67 14.67V1.33L1.33 14.67h13.34z" fill={c}/>
          </svg>
        </div>
        <svg width="16" height="16" viewBox="0 0 16 16">
          <rect x="3.75" y="2" width="8.5" height="13" rx="1.5" fill={c}/>
          <rect x="5.5" y="0.9" width="5" height="2" rx="0.5" fill={c}/>
        </svg>
      </div>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// List item (Material 3)
// ─────────────────────────────────────────────────────────────
function AndroidListItem({ headline, supporting, leading }) {
  return (
    <div style={{
      display: 'flex', alignItems: 'center', gap: 16,
      padding: '12px 16px', minHeight: 56, boxSizing: 'border-box',
      fontFamily: 'Roboto, system-ui, sans-serif',
    }}>
      {leading && (
        <div style={{
          width: 40, height: 40, borderRadius: '50%',
          background: MD_C.primary, color: '#fff',
          display: 'flex', alignItems: 'center', justifyContent: 'center',
          fontSize: 18, fontWeight: 500, flexShrink: 0,
        }}>{leading}</div>
      )}
      <div style={{ flex: 1, minWidth: 0 }}>
        <div style={{ fontSize: 16, color: MD_C.onSurface, lineHeight: '24px' }}>{headline}</div>
        {supporting && (
          <div style={{ fontSize: 14, color: MD_C.onSurfaceVar, lineHeight: '20px' }}>{supporting}</div>
        )}
      </div>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Gesture nav bar (pill)
// ─────────────────────────────────────────────────────────────
function AndroidNavBar({ dark = false }) {
  return (
    <div style={{
      height: 24, display: 'flex', alignItems: 'center', justifyContent: 'center',
    }}>
      <div style={{
        width: 108, height: 4, borderRadius: 2,
        background: dark ? '#fff' : MD_C.onSurface, opacity: 0.4,
      }} />
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Device frame — wraps everything
// ─────────────────────────────────────────────────────────────
function AndroidDevice({
  children, width = 412, height = 892, dark = false,
  keyboard = false,
}) {
  return (
    <div style={{
      width, height, borderRadius: 18, overflow: 'hidden',
      background: dark ? '#1d1b20' : MD_C.surface,
      border: `8px solid ${MD_C.frameBorder}`,
      display: 'flex', flexDirection: 'column', boxSizing: 'border-box',
    }}>
      <AndroidStatusBar dark={dark} />
      <div style={{ flex: 1, overflow: 'auto' }}>
        {children}
      </div>
      {keyboard && <AndroidKeyboard />}
      <AndroidNavBar dark={dark} />
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Keyboard — Gboard (Material 3)
// ─────────────────────────────────────────────────────────────
function AndroidKeyboard() {
  let _k = 0;
  const key = (l, { flex = 1, bg = MD_C.surface, r = 6, minW, fs = 21 } = {}) => (
    <div key={_k++} style={{
      height: 46, borderRadius: r, flex, minWidth: minW,
      background: bg, display: 'flex', alignItems: 'center', justifyContent: 'center',
      fontFamily: 'Roboto, system-ui', fontSize: fs,
      color: MD_C.onPrimaryContainer,
    }}>{l}</div>
  );
  const row = (keys, style = {}) => (
    <div style={{ display: 'flex', gap: 6, justifyContent: 'center', ...style }}>
      {keys.map(l => key(l))}
    </div>
  );
  return (
    <div style={{
      background: MD_C.inverseOnSurface, padding: '0 8px 8px',
      display: 'flex', flexDirection: 'column', gap: 4,
    }}>
      {/* navbar spacer (icons omitted) */}
      <div style={{ height: 44 }} />
      {/* key rows */}
      <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
        {row(['q','w','e','r','t','y','u','i','o','p'])}
        {row(['a','s','d','f','g','h','j','k','l'], { padding: '0 20px' })}
        <div style={{ display: 'flex', gap: 6 }}>
          {key('', { bg: MD_C.surfaceVariant })}
          <div style={{ display: 'flex', gap: 6, flex: 7, minWidth: 274 }}>
            {['z','x','c','v','b','n','m'].map(l => key(l))}
          </div>
          {key('', { bg: MD_C.surfaceVariant })}
        </div>
        <div style={{ display: 'flex', gap: 6 }}>
          {key('?123', { bg: MD_C.secondaryContainer, r: 100, minW: 58, fs: 14 })}
          {key(',', { bg: MD_C.surfaceVariant })}
          {key('', { flex: 3, minW: 154 })}
          {key('.', { bg: MD_C.surfaceVariant })}
          {key('', { bg: MD_C.primaryFixedDim, r: 100, minW: 58 })}
        </div>
      </div>
    </div>
  );
}

Object.assign(window, {
  AndroidDevice, AndroidStatusBar, AndroidListItem, AndroidNavBar, AndroidKeyboard,
});

/* BEGIN USAGE */
// animations.jsx
// Reusable animation starter: Stage, Timeline, Sprite, easing helpers.
// Exports (to window): Stage, Sprite, PlaybackBar, TextSprite, ImageSprite, RectSprite,
//   useTime, useTimeline, useSprite, Easing, interpolate, animate, clamp.
//
// Usage (in an HTML file that loads React + Babel):
//
//   <Stage width={1280} height={720} duration={10} background="#f6f4ef">
//     <MyScene />
//   </Stage>
//
// <Stage> auto-scales to the viewport and provides the scrubber, play/pause,
// ←/→ seek, space, and 0-to-reset controls, and persists the playhead.
// Set the optional `poster` prop (seconds) to the moment your opening scene is
// fully composed — the product thumbnail freezes on that frame (default ~1s).
// Inside <Stage>, any child can call useTime() to read the current
// playhead (seconds). Or wrap content in <Sprite start={1} end={4}>...</Sprite>
// to only render during that window -- children receive a `localTime` and
// `progress` via the useSprite() hook. Use Easing + interpolate()/animate()
// for tweens; TextSprite / ImageSprite / RectSprite have built-in entry/exit.
// Build YOUR scenes by composing Sprites inside a Stage.
/* END USAGE */
// ─────────────────────────────────────────────────────────────────────────────

// ── Easing functions (hand-rolled, Popmotion-style) ─────────────────────────
// All easings take t ∈ [0,1] and return eased t ∈ [0,1] (may overshoot for back/elastic).
const Easing = {
  linear: (t) => t,

  // Quad
  easeInQuad:    (t) => t * t,
  easeOutQuad:   (t) => t * (2 - t),
  easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),

  // Cubic
  easeInCubic:    (t) => t * t * t,
  easeOutCubic:   (t) => (--t) * t * t + 1,
  easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1),

  // Quart
  easeInQuart:    (t) => t * t * t * t,
  easeOutQuart:   (t) => 1 - (--t) * t * t * t,
  easeInOutQuart: (t) => (t < 0.5 ? 8 * t * t * t * t : 1 - 8 * (--t) * t * t * t),

  // Expo
  easeInExpo:  (t) => (t === 0 ? 0 : Math.pow(2, 10 * (t - 1))),
  easeOutExpo: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
  easeInOutExpo: (t) => {
    if (t === 0) return 0;
    if (t === 1) return 1;
    if (t < 0.5) return 0.5 * Math.pow(2, 20 * t - 10);
    return 1 - 0.5 * Math.pow(2, -20 * t + 10);
  },

  // Sine
  easeInSine:    (t) => 1 - Math.cos((t * Math.PI) / 2),
  easeOutSine:   (t) => Math.sin((t * Math.PI) / 2),
  easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,

  // Back (overshoot)
  easeOutBack: (t) => {
    const c1 = 1.70158, c3 = c1 + 1;
    return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
  },
  easeInBack: (t) => {
    const c1 = 1.70158, c3 = c1 + 1;
    return c3 * t * t * t - c1 * t * t;
  },
  easeInOutBack: (t) => {
    const c1 = 1.70158, c2 = c1 * 1.525;
    return t < 0.5
      ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
      : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
  },

  // Elastic
  easeOutElastic: (t) => {
    const c4 = (2 * Math.PI) / 3;
    if (t === 0) return 0;
    if (t === 1) return 1;
    return Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
  },
};

// ── Core interpolation helpers ──────────────────────────────────────────────

// Clamp a value to [min, max]
const clamp = (v, min, max) => Math.max(min, Math.min(max, v));

// interpolate([0, 0.5, 1], [0, 100, 50], ease?) -> fn(t)
// Popmotion-style: linearly maps t across input keyframes to output values,
// with optional easing per segment (single fn or array of fns).
function interpolate(input, output, ease = Easing.linear) {
  return (t) => {
    if (t <= input[0]) return output[0];
    if (t >= input[input.length - 1]) return output[output.length - 1];
    for (let i = 0; i < input.length - 1; i++) {
      if (t >= input[i] && t <= input[i + 1]) {
        const span = input[i + 1] - input[i];
        const local = span === 0 ? 0 : (t - input[i]) / span;
        const easeFn = Array.isArray(ease) ? (ease[i] || Easing.linear) : ease;
        const eased = easeFn(local);
        return output[i] + (output[i + 1] - output[i]) * eased;
      }
    }
    return output[output.length - 1];
  };
}

// animate({from, to, start, end, ease})(t) — simpler single-segment tween.
// Returns `from` before `start`, `to` after `end`.
function animate({ from = 0, to = 1, start = 0, end = 1, ease = Easing.easeInOutCubic }) {
  return (t) => {
    if (t <= start) return from;
    if (t >= end) return to;
    const local = (t - start) / (end - start);
    return from + (to - from) * ease(local);
  };
}

// ── Timeline context ────────────────────────────────────────────────────────

const TimelineContext = React.createContext({ time: 0, duration: 10, playing: false });

const useTime = () => React.useContext(TimelineContext).time;
const useTimeline = () => React.useContext(TimelineContext);

// ── Sprite ──────────────────────────────────────────────────────────────────
// Renders children only when the playhead is inside [start, end]. Provides
// a sub-context with `localTime` (seconds since start) and `progress` (0..1).
//
//   <Sprite start={2} end={5}>
//     {({ localTime, progress }) => <Thing x={progress * 100} />}
//   </Sprite>
//
// Or as a plain wrapper — children can call useSprite() themselves.

const SpriteContext = React.createContext({ localTime: 0, progress: 0, duration: 0 });
const useSprite = () => React.useContext(SpriteContext);

function Sprite({ start = 0, end = Infinity, children, keepMounted = false }) {
  const { time } = useTimeline();
  const visible = time >= start && time <= end;
  if (!visible && !keepMounted) return null;

  const duration = end - start;
  const localTime = Math.max(0, time - start);
  const progress = duration > 0 && isFinite(duration)
    ? clamp(localTime / duration, 0, 1)
    : 0;

  const value = { localTime, progress, duration, visible };

  return (
    <SpriteContext.Provider value={value}>
      {typeof children === 'function' ? children(value) : children}
    </SpriteContext.Provider>
  );
}

// ── Sample sprite components ────────────────────────────────────────────────

// TextSprite: fades/slides text in on entry, holds, then fades out on exit.
// Props: text, x, y, size, color, font, entryDur, exitDur, align
function TextSprite({
  text,
  x = 0, y = 0,
  size = 48,
  color = '#111',
  font = 'Inter, system-ui, sans-serif',
  weight = 600,
  entryDur = 0.45,
  exitDur = 0.35,
  entryEase = Easing.easeOutBack,
  exitEase = Easing.easeInCubic,
  align = 'left',
  letterSpacing = '-0.01em',
}) {
  const { localTime, duration } = useSprite();
  const exitStart = Math.max(0, duration - exitDur);

  let opacity = 1;
  let ty = 0;

  if (localTime < entryDur) {
    const t = entryEase(clamp(localTime / entryDur, 0, 1));
    opacity = t;
    ty = (1 - t) * 16;
  } else if (localTime > exitStart) {
    const t = exitEase(clamp((localTime - exitStart) / exitDur, 0, 1));
    opacity = 1 - t;
    ty = -t * 8;
  }

  const translateX = align === 'center' ? '-50%' : align === 'right' ? '-100%' : '0';

  return (
    <div style={{
      position: 'absolute',
      left: x, top: y,
      transform: `translate(${translateX}, ${ty}px)`,
      opacity,
      fontFamily: font,
      fontSize: size,
      fontWeight: weight,
      color,
      letterSpacing,
      whiteSpace: 'pre',
      lineHeight: 1.1,
      willChange: 'transform, opacity',
    }}>
      {text}
    </div>
  );
}

// ImageSprite: scales + fades in; optional Ken Burns drift during hold.
function ImageSprite({
  src,
  x = 0, y = 0,
  width = 400, height = 300,
  entryDur = 0.6,
  exitDur = 0.4,
  kenBurns = false,
  kenBurnsScale = 1.08,
  radius = 12,
  fit = 'cover',
  placeholder = null, // {label: string} for striped placeholder
}) {
  const { localTime, duration } = useSprite();
  const exitStart = Math.max(0, duration - exitDur);

  let opacity = 1;
  let scale = 1;

  if (localTime < entryDur) {
    const t = Easing.easeOutCubic(clamp(localTime / entryDur, 0, 1));
    opacity = t;
    scale = 0.96 + 0.04 * t;
  } else if (localTime > exitStart) {
    const t = Easing.easeInCubic(clamp((localTime - exitStart) / exitDur, 0, 1));
    opacity = 1 - t;
    scale = (kenBurns ? kenBurnsScale : 1) + 0.02 * t;
  } else if (kenBurns) {
    const holdSpan = exitStart - entryDur;
    const holdT = holdSpan > 0 ? (localTime - entryDur) / holdSpan : 0;
    scale = 1 + (kenBurnsScale - 1) * holdT;
  }

  const content = placeholder ? (
    <div style={{
      width: '100%', height: '100%',
      display: 'flex', alignItems: 'center', justifyContent: 'center',
      background: 'repeating-linear-gradient(135deg, #e9e6df 0 10px, #dcd8cf 10px 20px)',
      color: '#6b6458',
      fontFamily: 'JetBrains Mono, ui-monospace, monospace',
      fontSize: 13,
      letterSpacing: '0.04em',
      textTransform: 'uppercase',
    }}>
      {placeholder.label || 'image'}
    </div>
  ) : (
    <img src={src} alt="" style={{ width: '100%', height: '100%', objectFit: fit, display: 'block' }} />
  );

  return (
    <div style={{
      position: 'absolute',
      left: x, top: y,
      width, height,
      opacity,
      transform: `scale(${scale})`,
      transformOrigin: 'center',
      borderRadius: radius,
      overflow: 'hidden',
      willChange: 'transform, opacity',
    }}>
      {content}
    </div>
  );
}

// RectSprite: simple rectangle that animates position/size/color via props.
// Useful demo primitive — takes a `render` fn for per-frame customization.
function RectSprite({
  x = 0, y = 0,
  width = 100, height = 100,
  color = '#111',
  radius = 8,
  entryDur = 0.4,
  exitDur = 0.3,
  render, // optional: (ctx) => style overrides
}) {
  const spriteCtx = useSprite();
  const { localTime, duration } = spriteCtx;
  const exitStart = Math.max(0, duration - exitDur);

  let opacity = 1;
  let scale = 1;

  if (localTime < entryDur) {
    const t = Easing.easeOutBack(clamp(localTime / entryDur, 0, 1));
    opacity = clamp(localTime / entryDur, 0, 1);
    scale = 0.4 + 0.6 * t;
  } else if (localTime > exitStart) {
    const t = Easing.easeInQuad(clamp((localTime - exitStart) / exitDur, 0, 1));
    opacity = 1 - t;
    scale = 1 - 0.15 * t;
  }

  const overrides = render ? render(spriteCtx) : {};

  return (
    <div style={{
      position: 'absolute',
      left: x, top: y,
      width, height,
      background: color,
      borderRadius: radius,
      opacity,
      transform: `scale(${scale})`,
      transformOrigin: 'center',
      willChange: 'transform, opacity',
      ...overrides,
    }} />
  );
}


function Stage({
  width = 1280,
  height = 720,
  duration = 10,
  background = '#f6f4ef',
  fps = 60,
  loop = true,
  autoplay = true,
  poster = null,
  persistKey = 'animstage',
  children,
}) {
  // Thumbnail capture mode: the host appends ?thumbnail=1 before screenshotting.
  // Freeze on a representative still — the author-declared `poster` second, or
  // ~1s as a fallback — paused, with the playback bar hidden, so the product
  // thumbnail is a deterministic frame of the first composed scene.
  const captureMode = typeof location !== 'undefined' && /[?&]thumbnail=/.test(location.search || '');

  const [time, setTime] = React.useState(() => {
    if (captureMode) return clamp(poster == null ? 1 : poster, 0, duration);
    try {
      const v = parseFloat(localStorage.getItem(persistKey + ':t') || '0');
      return isFinite(v) ? clamp(v, 0, duration) : 0;
    } catch { return 0; }
  });
  const [playing, setPlaying] = React.useState(captureMode ? false : autoplay);
  const [scale, setScale] = React.useState(1);

  const stageRef = React.useRef(null);
  const canvasRef = React.useRef(null);
  const rafRef = React.useRef(null);
  const lastTsRef = React.useRef(null);

  // Persist playhead
  React.useEffect(() => {
    try { localStorage.setItem(persistKey + ':t', String(time)); } catch {}
  }, [time, persistKey]);

  // Auto-scale to fit viewport
  React.useEffect(() => {
    if (!stageRef.current) return;
    const el = stageRef.current;
    const measure = () => {
      const barH = captureMode ? 0 : 44; // playback bar height (hidden in capture mode)
      const s = Math.min(
        el.clientWidth / width,
        (el.clientHeight - barH) / height
      );
      setScale(Math.max(0.05, s));
    };
    measure();
    const ro = new ResizeObserver(measure);
    ro.observe(el);
    window.addEventListener('resize', measure);
    return () => {
      ro.disconnect();
      window.removeEventListener('resize', measure);
    };
  }, [width, height]);

  // Animation loop
  React.useEffect(() => {
    if (!playing) {
      lastTsRef.current = null;
      return;
    }
    const step = (ts) => {
      if (lastTsRef.current == null) lastTsRef.current = ts;
      const dt = (ts - lastTsRef.current) / 1000;
      lastTsRef.current = ts;
      setTime((t) => {
        let next = t + dt;
        if (next >= duration) {
          if (loop) next = next % duration;
          else { next = duration; setPlaying(false); }
        }
        return next;
      });
      rafRef.current = requestAnimationFrame(step);
    };
    rafRef.current = requestAnimationFrame(step);
    return () => {
      if (rafRef.current) cancelAnimationFrame(rafRef.current);
      lastTsRef.current = null;
    };
  }, [playing, duration, loop]);

  // Keyboard: space = play/pause, ← → = seek
  React.useEffect(() => {
    const onKey = (e) => {
      if (e.target && (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA')) return;
      if (e.code === 'Space') {
        e.preventDefault();
        setPlaying(p => !p);
      } else if (e.code === 'ArrowLeft') {
        setTime(t => clamp(t - (e.shiftKey ? 1 : 0.1), 0, duration));
      } else if (e.code === 'ArrowRight') {
        setTime(t => clamp(t + (e.shiftKey ? 1 : 0.1), 0, duration));
      } else if (e.key === '0' || e.code === 'Home') {
        setTime(0);
      }
    };
    window.addEventListener('keydown', onKey);
    return () => window.removeEventListener('keydown', onKey);
  }, [duration]);

  const ctxValue = React.useMemo(
    () => ({ time, duration, playing, setTime, setPlaying }),
    [time, duration, playing]
  );

  return (
    <div
      ref={stageRef}
      style={{
        position: 'absolute', inset: 0,
        display: 'flex', flexDirection: 'column',
        alignItems: 'center',
        background: '#0a0a0a',
        fontFamily: 'Inter, system-ui, sans-serif',
      }}
    >
      {/* Canvas area — vertically centered in remaining space */}
      <div style={{
        flex: 1,
        width: '100%',
        display: 'flex', alignItems: 'center', justifyContent: 'center',
        overflow: 'hidden',
        minHeight: 0,
      }}>
        <div
          ref={canvasRef}
          style={{
            width, height,
            background,
            position: 'relative',
            transform: `scale(${scale})`,
            transformOrigin: 'center',
            flexShrink: 0,
            boxShadow: '0 20px 60px rgba(0,0,0,0.4)',
            overflow: 'hidden',
          }}
        >
          <TimelineContext.Provider value={ctxValue}>
            {children}
          </TimelineContext.Provider>
        </div>
      </div>

      {/* Playback bar — stacked below canvas, never overlapping. Hidden in
          capture mode so the thumbnail is just the frame, no chrome. */}
      {!captureMode && (
        <PlaybackBar
          time={time}
          duration={duration}
          playing={playing}
          onPlayPause={() => setPlaying(p => !p)}
          onReset={() => { setTime(0); }}
          onSeek={(t) => setTime(t)}
        />
      )}
    </div>
  );
}

// ── Playback bar ────────────────────────────────────────────────────────────
// Play/pause, return-to-begin, scrub track, time display.
// Uses fixed-width time fields so layout doesn't thrash.

function PlaybackBar({ time, duration, playing, onPlayPause, onReset, onSeek }) {
  const trackRef = React.useRef(null);
  const [dragging, setDragging] = React.useState(false);
  const [trackHover, setTrackHover] = React.useState(null); // { x, t } — px within track + hovered time

  const posFromEvent = React.useCallback((e) => {
    const rect = trackRef.current.getBoundingClientRect();
    const x = clamp(e.clientX - rect.left, 0, rect.width);
    const t = rect.width > 0 ? (x / rect.width) * duration : 0;
    return { x, t };
  }, [duration]);

  const onTrackMove = (e) => {
    if (!trackRef.current) return;
    const { x, t } = posFromEvent(e);
    setTrackHover({ x, t });
    if (dragging) onSeek(t);
  };

  const onTrackLeave = () => {
    if (!dragging) setTrackHover(null);
  };

  const onTrackDown = (e) => {
    const { x, t } = posFromEvent(e);
    setDragging(true);
    setTrackHover({ x, t });
    onSeek(t);
  };

  // Grab the knob in place: begin dragging without seeking (no jump).
  // stopPropagation keeps the track's click-to-seek from also firing.
  const onBallDown = (e) => {
    e.stopPropagation();
    setDragging(true);
    setTrackHover(posFromEvent(e));
  };

  React.useEffect(() => {
    if (!dragging) return;
    const prevCursor = document.body.style.cursor;
    document.body.style.cursor = 'grabbing'; // stays grabbing even if the pointer leaves the knob mid-drag
    const onUp = () => {
      setDragging(false);
      setTrackHover(null);
    };
    const onMove = (e) => {
      if (!trackRef.current) return;
      const { x, t } = posFromEvent(e);
      setTrackHover({ x, t });
      onSeek(t);
    };
    window.addEventListener('mouseup', onUp);
    window.addEventListener('mousemove', onMove);
    return () => {
      window.removeEventListener('mouseup', onUp);
      window.removeEventListener('mousemove', onMove);
      document.body.style.cursor = prevCursor;
    };
  }, [dragging, posFromEvent, onSeek]);

  const pct = duration > 0 ? (time / duration) * 100 : 0;
  const fmt = (t) => {
    const total = Math.max(0, t);
    const m = Math.floor(total / 60);
    const s = Math.floor(total % 60);
    return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
  };

  const numFont = '"PingFang SC", -apple-system, BlinkMacSystemFont, system-ui, sans-serif';

  return (
    <div style={{
      display: 'flex', alignItems: 'center', gap: 12,
      padding: '12px',
      background: 'linear-gradient(0deg, rgba(0, 0, 0, 0.30) 0%, rgba(0, 0, 0, 0.00) 100%)',
      width: '100%',
      color: '#fff',
      fontFamily: numFont,
      userSelect: 'none',
      flexShrink: 0,
      boxSizing: 'border-box',
    }}>
      {/* Play / pause — bare white triangle, no button chrome */}
      <IconButton onClick={onPlayPause} tooltip={playing ? '暂停' : '播放'}>
        {playing ? (
          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M3.33333 1.33398C2.59695 1.33398 2 1.93094 2 2.66732V13.334C2 14.0704 2.59695 14.6673 3.33333 14.6673H4.66667C5.40305 14.6673 6 14.0704 6 13.334V2.66732C6 1.93094 5.40305 1.33398 4.66667 1.33398H3.33333Z" fill="currentColor"/>
            <path d="M11.3333 1.33398C10.597 1.33398 10 1.93094 10 2.66732V13.334C10 14.0704 10.597 14.6673 11.3333 14.6673H12.6667C13.403 14.6673 14 14.0704 14 13.334V2.66732C14 1.93094 13.403 1.33398 12.6667 1.33398H11.3333Z" fill="currentColor"/>
          </svg>
        ) : (
          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M14.0489 9.13127C14.873 8.60116 14.873 7.39754 14.0489 6.86743L4.74461 0.882617C3.84764 0.305661 2.66699 0.948902 2.66699 2.01454V13.9842C2.66699 15.0498 3.84764 15.693 4.74461 15.1161L14.0489 9.13127Z" fill="currentColor"/>
          </svg>
        )}
      </IconButton>

      {/* Current time */}
      <div style={{
        fontFamily: numFont,
        fontSize: 14,
        fontWeight: 400,
        fontVariantNumeric: 'tabular-nums',
        color: '#fff',
        minWidth: 40,
        textAlign: 'center'
      }}>
        {fmt(time)}
      </div>

      {/* Scrub track — white fill on translucent-white rail + draggable knob */}
      <div
        ref={trackRef}
        onMouseMove={onTrackMove}
        onMouseLeave={onTrackLeave}
        onMouseDown={onTrackDown}
        style={{
          flex: 1,
          height: 20,
          position: 'relative',
          cursor: 'pointer',
          display: 'flex', alignItems: 'center',
        }}
      >
        <div style={{
          position: 'absolute',
          left: 0, right: 0, height: 4,
          background: 'rgba(255,255,255,0.6)',
          borderRadius: 2,
        }}/>
        <div style={{
          position: 'absolute',
          left: 0, width: `${pct}%`, height: 4,
          background: 'rgba(255,255,255,0.9)',
          borderRadius: 2,
        }}/>
        {/* Progress knob — outer div is an enlarged transparent hit area for easier grabbing */}
        <div
          onMouseDown={onBallDown}
          style={{
            position: 'absolute',
            left: `${pct}%`, top: '50%',
            transform: 'translate(-50%, -50%)',
            width: 20, height: 20,
            display: 'flex', alignItems: 'center', justifyContent: 'center',
            cursor: dragging ? 'grabbing' : 'grab',
            zIndex: 5,
          }}
        >
          <div style={{
            width: dragging ? 14 : 12,
            height: dragging ? 14 : 12,
            background: '#fff',
            borderRadius: '50%',
            border: '0.5px solid #D2D5D8',
            boxShadow: '0 2px 6px rgba(0,0,0,0.35)',
            transition: 'width 100ms, height 100ms',
          }}/>
        </div>
        {trackHover && (
          <div style={{
            position: 'absolute',
            left: trackHover.x,
            bottom: '100%',
            transform: 'translateX(-50%)',
            marginBottom: 2,
            pointerEvents: 'none',
            zIndex: 10,
          }}>
            <TooltipBubble text={fmt(trackHover.t)} />
          </div>
        )}
      </div>

      {/* Duration — dimmed */}
      <div style={{
        fontFamily: numFont,
        fontSize: 14,
        fontWeight: 400,
        fontVariantNumeric: 'tabular-nums',
        color: 'rgba(255,255,255,0.6)',
        minWidth: 40,
        textAlign: 'center',
      }}>
        {fmt(duration)}
      </div>
    </div>
  );
}


function IconButton({ children, onClick, tooltip }) {
  const [hover, setHover] = React.useState(false);
  return (
    <button
      onClick={onClick}
      aria-label={tooltip}
      onMouseEnter={() => setHover(true)}
      onMouseLeave={() => setHover(false)}
      style={{
        position: 'relative',
        width: 24, height: 24,
        display: 'flex', alignItems: 'center', justifyContent: 'center',
        background: hover ? 'rgba(255,255,255,0.1)' : 'transparent',
        border: 'none',
        borderRadius: 6,
        color: '#fff',
        cursor: 'pointer',
        padding: 0,
        transition: 'background 120ms',
      }}
    >
      {children}
      {tooltip && (
        <div style={{
          position: 'absolute',
          bottom: '100%',
          left: '50%',
          transform: 'translateX(-50%)',
          marginBottom: 8,
          pointerEvents: 'none',
          opacity: hover ? 1 : 0,
          transition: 'opacity 120ms',
          zIndex: 10,
        }}>
          <TooltipBubble text={tooltip} />
        </div>
      )}
    </button>
  );
}

// ── Tooltip bubble ────────────────────────────────────────────────────────────
// Dark rounded bubble with a downward tail. Positioning is up to the caller.
function TooltipBubble({ text }) {
  return (
    <div style={{ position: 'relative', display: 'inline-block' }}>
      <div style={{
        background: '#1F2329',
        color: '#fff',
        fontSize: 12,
        lineHeight: '16px',
        padding: '6px 12px',
        borderRadius: 6,
        whiteSpace: 'nowrap',
        fontFamily: '"PingFang SC", -apple-system, BlinkMacSystemFont, system-ui, sans-serif',
        fontVariantNumeric: 'tabular-nums',
        boxShadow: '0 4px 8px -8px rgba(0, 0, 0, 0.06), 0 6px 12px 0 rgba(0, 0, 0, 0.04), 0 8px 24px 8px rgba(0, 0, 0, 0.04)',
      }}>
        {text}
      </div>
      <div style={{
        position: 'absolute',
        top: '100%',
        left: '50%',
        transform: 'translate(-50%, -50%) rotate(45deg)',
        width: 9, height: 9,
        borderRadius: '0 0 3px 0',
        background: '#1F2329',
      }}/>
    </div>
  );
}


Object.assign(window, {
  Easing, interpolate, animate, clamp,
  TimelineContext, useTime, useTimeline,
  Sprite, SpriteContext, useSprite,
  TextSprite, ImageSprite, RectSprite,
  Stage, PlaybackBar,
});

/* BEGIN USAGE */
// Chrome.jsx — Simplified Chrome browser window (dark theme, macOS)
// No dependencies, no image assets. All inline styles + inline SVG.
// Exports (to window): ChromeWindow, ChromeTabBar, ChromeToolbar, ChromeTab, ChromeTrafficLights
//
// Usage — wrap your page content in <ChromeWindow> to get the tab bar + URL bar:
//
//   <ChromeWindow width={1100} height={680} url="acme.design/pricing">
//     ...your page content...
//   </ChromeWindow>
/* END USAGE */

const CHROME_C = {
  barBg: '#202124',
  tabBg: '#35363a',
  text: '#e8eaed',
  dim: '#9aa0a6',
  urlBg: '#282a2d',
};

function ChromeTrafficLights() {
  return (
    <div style={{ display: 'flex', gap: 8, padding: '0 14px' }}>
      <div style={{ width: 12, height: 12, borderRadius: '50%', background: '#ff5f57' }} />
      <div style={{ width: 12, height: 12, borderRadius: '50%', background: '#febc2e' }} />
      <div style={{ width: 12, height: 12, borderRadius: '50%', background: '#28c840' }} />
    </div>
  );
}

// Single tab (active has curved scoops)
function ChromeTab({ title = 'New Tab', active = false }) {
  const curve = (flip) => (
    <svg width="8" height="10" viewBox="0 0 8 10"
      style={{ position: 'absolute', bottom: 0, [flip ? 'right' : 'left']: -8, transform: flip ? 'scaleX(-1)' : 'none' }}>
      <path d="M0 10C2 9 6 8 8 0V10H0Z" fill={CHROME_C.tabBg}/>
    </svg>
  );
  return (
    <div style={{
      position: 'relative', height: 34, alignSelf: 'flex-end',
      padding: '0 12px', display: 'flex', alignItems: 'center', gap: 8,
      background: active ? CHROME_C.tabBg : 'transparent',
      borderRadius: '8px 8px 0 0', minWidth: 120, maxWidth: 220,
      fontFamily: 'system-ui, sans-serif', fontSize: 12,
      color: active ? CHROME_C.text : CHROME_C.dim,
    }}>
      {active && curve(false)}
      {active && curve(true)}
      <div style={{ width: 14, height: 14, borderRadius: '50%', background: '#5f6368', flexShrink: 0 }} />
      <span style={{ flex: 1, whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' }}>{title}</span>
    </div>
  );
}

function ChromeTabBar({ tabs = [{ title: 'New Tab' }], activeIndex = 0 }) {
  return (
    <div style={{
      display: 'flex', alignItems: 'center', height: 44,
      background: CHROME_C.barBg, paddingRight: 8,
    }}>
      <ChromeTrafficLights />
      <div style={{ display: 'flex', alignItems: 'flex-end', height: '100%', paddingLeft: 4, flex: 1 }}>
        {tabs.map((t, i) => <ChromeTab key={i} title={t.title} active={i === activeIndex} />)}
      </div>
    </div>
  );
}

function ChromeToolbar({ url = 'example.com' }) {
  const iconDot = (
    <div style={{
      width: 28, height: 28, display: 'flex', alignItems: 'center', justifyContent: 'center',
    }}>
      <div style={{ width: 16, height: 16, borderRadius: '50%', background: CHROME_C.dim, opacity: 0.4 }} />
    </div>
  );
  return (
    <div style={{
      height: 40, background: CHROME_C.tabBg,
      display: 'flex', alignItems: 'center', gap: 4, padding: '0 8px',
    }}>
      {iconDot}
      {/* url bar */}
      <div style={{
        flex: 1, height: 30, borderRadius: 15, background: CHROME_C.urlBg,
        display: 'flex', alignItems: 'center', gap: 8, padding: '0 14px',
        margin: '0 6px',
      }}>
        <div style={{ width: 12, height: 12, borderRadius: '50%', background: CHROME_C.dim, opacity: 0.4 }} />
        <span style={{
          flex: 1, color: CHROME_C.text, fontSize: 13,
          fontFamily: 'system-ui, sans-serif',
        }}>{url}</span>
      </div>
      {iconDot}
    </div>
  );
}

function ChromeWindow({
  tabs = [{ title: 'New Tab' }], activeIndex = 0, url = 'example.com',
  width = 900, height = 600, children,
}) {
  return (
    <div style={{
      width, height, borderRadius: 10, overflow: 'hidden',
      border: '1px solid #DEE0E3',
      display: 'flex', flexDirection: 'column', background: CHROME_C.tabBg,
    }}>
      <ChromeTabBar tabs={tabs} activeIndex={activeIndex} />
      <ChromeToolbar url={url} />
      <div style={{ flex: 1, background: '#fff', overflow: 'auto' }}>
        {children}
      </div>
    </div>
  );
}

Object.assign(window, {
  ChromeWindow, ChromeTabBar, ChromeToolbar, ChromeTab, ChromeTrafficLights,
});

// Copyright (c) 2026 Lark Technologies Pte. Ltd.
// SPDX-License-Identifier: MIT

/* BEGIN USAGE */
/**
 * <deck-stage> — reusable web component for HTML decks.
 *
 * Handles:
 *  (a) speaker notes — reads <script type="application/json" id="speaker-notes">
 *      (a JSON array of per-slide note strings), shows the current slide's
 *      note in an editable bottom dock (edit mode only; drag its grip to
 *      resize, height persisted to localStorage), posts miaoda:deck:slide-changed
 *      to the parent on nav, and posts miaoda:deck:notes-changed (the full
 *      array) when a note is edited so the host can persist it. The dock is
 *      hidden while presenting / in preview / on narrow / noscale / no-rail.
 *  (b) keyboard navigation — ←/→, PgUp/PgDn, Space, Home/End, number keys.
 *      On touch devices, tapping the left/right half of the stage goes
 *      prev/next (desktop / presenting mode; mobile browse mode scrolls
 *      instead — see (g)) — taps on links, buttons and other interactive
 *      slide content are left alone.
 *  (c) press R to reset to slide 0.
 *  (d) auto-scaling — inner canvas is a fixed design size (default 1920×1080)
 *      scaled with `transform: scale()` to fit the viewport, letterboxed.
 *      Set the `noscale` attribute to render at authored size (1:1) — the
 *      PPTX exporter sets this so its DOM capture sees unscaled geometry.
 *  (e) print — `@media print` lays every slide out as its own page at the
 *      design size, so the browser's Print → Save as PDF produces a clean
 *      one-page-per-slide PDF with no extra setup.
 *  (f) thumbnail rail — resizable left-hand column of per-slide thumbnails
 *      (static clones). Click to navigate; ↑/↓ with a thumbnail focused to
 *      step between slides; drag to reorder; right-click for
 *      Skip / Move up / Move down / Delete. Drag the rail's right edge
 *      to resize; width persists to
 *      localStorage. Skipped slides carry `data-deck-skip`, are dimmed in
 *      the rail, omitted from prev/next navigation, and hidden at print.
 *      The rail is suppressed in presenting mode, in the host's Preview
 *      mode (ViewerMode='none'), on `noscale`, on narrow viewports
 *      (≤640px), and via the `no-rail` attribute. Rail mutations dispatch
 *      a `deckchange`
 *      CustomEvent on the element: detail = {action, from, to, slide}.
 *  (g) mobile — on mobile UA (mirrors the host platform's isMobile()
 *      semantics: UA regex + iPad maxTouchPoints, never viewport width),
 *      browse mode renders slides as a vertical card stream (12px margin,
 *      8px gap, 8px radius) with native scrolling; a per-card page badge
 *      fades in while scrolling (16|20×12, ink 20% bg, fixed 8px digits)
 *      and fades out 2s after scrolling stops. Presenting mode
 *      (miaoda:deck:presenting) rotates the stage 90° (CSS pseudo-
 *      landscape, no orientation.lock): tap left/right third to navigate,
 *      tap center to toggle the controls overlay (back button +
 *      filmstrip; auto-hides after 3s). The back button exits presenting
 *      and posts miaoda:deck:presenting-dismissed to the parent.
 *      Desktop behaviour is unchanged.
 *
 * Slides are HIDDEN, not unmounted. Non-active slides stay in the DOM with
 * `visibility: hidden` + `opacity: 0`, so their state (videos, iframes,
 * form inputs, React trees) is preserved across navigation.
 *
 * Lifecycle event — the component dispatches a `slidechange` CustomEvent on
 * itself whenever the active slide changes (including the initial mount).
 * The event bubbles and composes out of shadow DOM, so you can listen on
 * the <deck-stage> element or on document:
 *
 *   document.querySelector('deck-stage').addEventListener('slidechange', (e) => {
 *     e.detail.index         // new 0-based index
 *     e.detail.previousIndex // previous index, or -1 on init
 *     e.detail.total         // total slide count
 *     e.detail.slide         // the new active slide element
 *     e.detail.previousSlide // the prior slide element, or null on init
 *     e.detail.reason        // 'init' | 'keyboard' | 'click' | 'tap' | 'api'
 *   });
 *
 * Persistence: none at the deck level. The host app keeps the current slide
 * in its own URL (?slide=) and re-delivers it via location.hash on load, so a
 * bare load with no hash always starts at slide 1.
 *
 * Usage:
 *   <style>deck-stage:not(:defined){visibility:hidden}</style>
 *   <deck-stage width="1920" height="1080">
 *     <section data-label="Title">...</section>
 *     <section data-label="Agenda">...</section>
 *   </deck-stage>
 *   <script src="deck-stage.js"></script>
 *
 * The :not(:defined) rule prevents a flash of the first slide at its
 * authored styles before this script runs and attaches the shadow root.
 *
 * Slides are the direct element children of <deck-stage>. Each slide is
 * automatically tagged with:
 *   - data-screen-label="NN Label"   (1-indexed, for comment flow)
 *   - data-miaoda-validate="no_overflowing_text,no_overlapping_text,slide_sized_text"
 *
 * Speaker notes stay in sync because the component posts miaoda:deck:slide-changed
 * to the parent — just include the #speaker-notes script tag if asked for notes.
 *
 * Authoring guidance:
 *   - Write slide bodies as static HTML inside <deck-stage>, with sizing via
 *     CSS custom properties in a <style> block rather than JS constants.
 *     Static slide markup is what lets the user click a heading in edit mode
 *     and retype it directly; a slide rendered through <script type="text/babel">,
 *     React, or a loop over a JS array has to round-trip every tweak through a
 *     chat message instead. Reach for script-generated slides only when the
 *     content genuinely needs interactive behaviour static HTML can't express.
 *   - Do NOT set position/inset/width/height on the slide <section> elements —
 *     the component absolutely positions every slotted child for you.
 *   - Entrance animations: make the visible end-state the base style and
 *     animate *from* hidden. The thumbnail rail, print, and reduced-motion
 *     render each slide's static base state and never fire the animation, so
 *     a hidden base (opacity:0 on the rule itself) renders blank there while
 *     the live slide looks fine. Keep the hidden state only in the keyframes
 *     `from`, and gate the animation on [data-deck-active] and the motion
 *     query, e.g.:
 *       .fade-up { opacity: 1 }
 *       @media (prefers-reduced-motion:no-preference){ [data-deck-active] .fade-up{ animation: fadeUp .5s both } }
 *       @keyframes fadeUp { from{ opacity:0; transform:translateY(24px) } to{ opacity:1; transform:none } }
 *     Avoid infinite decorative loops on slide content.
 */
/* END USAGE */

(() => {
  if (typeof window === 'undefined') return;
  const DESIGN_W_DEFAULT = 1920;
  const DESIGN_H_DEFAULT = 1080;
  // Safe margin around the scaled slide in edit/preview (non-presenting) mode,
  // giving the canvas a floating "card" look with a drop-shadow.
  const DECK_MARGIN = 20;
  // TEMP: presenter-notes dock is hidden for now. Flip back to false to restore
  // the editable speaker-notes panel (all notes logic below stays intact).
  const NOTES_DISABLED = true;
  const VALIDATE_ATTR = 'no_overflowing_text,no_overlapping_text,slide_sized_text';
  const FINE_POINTER_MQ = matchMedia('(hover: hover) and (pointer: fine)');
  const NARROW_MQ = matchMedia('(max-width: 640px)');
  // Slide-authored controls that should keep a tap instead of it navigating.
  const INTERACTIVE_SEL = 'a[href], button, input, select, textarea, summary, label, video[controls], audio[controls], [role="button"], [onclick], [tabindex]:not([tabindex^="-"]), [contenteditable]:not([contenteditable="false" i])';

  // ── 移动端（复刻主仓 @apaas-ai/global-states isMobile() 的 UA 语义；
  //    跨域产物 iframe 无法 import 该包）。刻意不用视口断点：桌面工作台的
  //    预览 iframe 本身就窄，视口宽度会把桌面预览误判成移动端。
  //    mode=desktop 逃生阀只作用于壳层自身 location、不透传到本 iframe，不实现。
  const MOBILE_UA_RE = /(phone|pad|pod|iPhone|iPod|ios|iPad|Android|Mobile|BlackBerry|IEMobile|MQQBrowser|JUC|Fennec|wOSBrowser|BrowserNG|WebOS|Symbian|Windows Phone)/i;
  const isMobileUA = () =>
    MOBILE_UA_RE.test(navigator.userAgent) ||
    (/iPad|Tab|Tablet/i.test(navigator.userAgent) && !!navigator.maxTouchPoints && navigator.maxTouchPoints > 1);
  // 移动端视觉常量（Figma node 2965:32138 / 2965:32047 / 2965:34386 已确认）
  const MOB_MARGIN = 12;        // 竖排卡片页边距
  const MOB_GAP = 8;            // 卡片间距
  const MOB_RADIUS = 8;         // 卡片圆角
  const MOB_BADGE_IDLE_MS = 2000;  // 滚动停止 → 徽标淡出（UX 确认 2s）
  const MOB_UI_HIDE_MS = 3000;     // 播放控件层自动收起

  const pad2 = (n) => String(n).padStart(2, '0');

  // Label precedence: data-label → data-screen-label (number stripped) → first heading → "Slide".
  const getSlideLabel = (el) => {
    const explicit = el.getAttribute('data-label');
    if (explicit) return explicit;

    const existing = el.getAttribute('data-screen-label');
    if (existing) return existing.replace(/^\s*\d+\s*/, '').trim() || existing;

    const h = el.querySelector('h1, h2, h3, [data-title]');
    const t = h && (h.textContent || '').trim().slice(0, 40);
    if (t) return t;

    return 'Slide';
  };

  const stylesheet = `
    :host {
      position: fixed;
      inset: 0;
      display: block;
      background: #F8F9FA;
      font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, Arial, sans-serif;
      overflow: hidden;
      -webkit-tap-highlight-color: transparent;
    }
    /* connectedCallback holds this until document.fonts.ready (capped 2s) so
     * the first visible paint has the deck's real typography + final rail
     * layout. opacity (not visibility) so the active slide can't un-hide
     * itself via the ::slotted([data-deck-active]) visibility:visible rule.
     * Only the stage/rail hide — the black :host background stays, so the
     * iframe doesn't flash the page's default white. */
    :host([data-fonts-pending]) .stage,
    :host([data-fonts-pending]) .rail,
    :host([data-fonts-pending]) .notes { opacity: 0; pointer-events: none; }

    .stage {
      position: absolute;
      inset: 0;
      display: flex;
      align-items: center;
      justify-content: center;
      background: transparent;
    }
    :host(:not([data-windowed])) .stage { background: #000; }

    .canvas {
      position: relative;
      transform-origin: center center;
      flex-shrink: 0;
      background: #fff;
      will-change: transform;
    }
    /* Floating card drop-shadow — only when the stage is windowed (20px
       margin), i.e. edit/preview. Full-bleed presenting / noscale / _snthumb
       carry no shadow (_fit toggles data-windowed). */
    :host([data-windowed]) .canvas {
      border: 0.882px solid #DEE0E3;
      box-shadow: 0 0 7.052px 0 rgba(31, 35, 41, 0.06), 0 0 15.867px 0 rgba(31, 35, 41, 0.04), 0 0 22.919px 7.052px rgba(31, 35, 41, 0.04);
    }

    /* Slides live in light DOM (via <slot>) so authored CSS still applies.
       We absolutely position each slotted child to stack them. */
    ::slotted(*) {
      position: absolute !important;
      inset: 0 !important;
      width: 100% !important;
      height: 100% !important;
      box-sizing: border-box !important;
      overflow: hidden;
      opacity: 0;
      pointer-events: none;
      visibility: hidden;
    }
    ::slotted([data-deck-active]) {
      opacity: 1;
      pointer-events: auto;
      visibility: visible;
    }

    /* ── Thumbnail rail ──────────────────────────────────────────────────
       Fixed column on the left; each thumbnail is a static deep-clone of
       the light-DOM slide scaled into a 16:9 (or design-aspect) frame. The
       stage re-fits around it (see _fit); hidden during present / noscale
       / print so capture geometry and fullscreen output are unchanged. */
    .rail {
      position: fixed;
      left: 0;
      top: 0;
      bottom: 0;
      width: var(--deck-rail-w, 192px);
      background: #fff;
      border-right: 0.5px solid #DEE0E3;
      overflow-y: auto;
      overflow-x: hidden;
      transform: translate3d(0, 0, 0);
      padding: 20px 15px 20px 10px;
      box-sizing: border-box;
      display: flex;
      flex-direction: column;
      gap: 18px;
      z-index: 2147482500;
      scrollbar-width: thin;
      scrollbar-color: rgba(0,0,0,0.18) transparent;
    }
    .rail::-webkit-scrollbar { width: 8px; }
    .rail::-webkit-scrollbar-track { background: transparent; margin: 2px; }
    .rail::-webkit-scrollbar-thumb {
      background: rgba(0,0,0,0.18);
      border-radius: 4px;
      border: 2px solid transparent;
      background-clip: content-box;
    }
    .rail::-webkit-scrollbar-thumb:hover {
      background: rgba(0,0,0,0.28);
      border: 2px solid transparent;
      background-clip: content-box;
    }
    :host([no-rail]) .rail,
    :host([noscale]) .rail { display: none; }
    .rail[data-presenting] { display: none; }
    @media (max-width: 640px) {
      .rail, .rail-resize { display: none; }
    }
    /* User-driven show/hide (the TweaksPanel toggle) slides instead of
       popping. Transitions are gated on :host([data-rail-anim]) — set only
       for the 200ms around the toggle — so window-resize and rail-width
       drag (which also call _fit) don't lag behind the cursor. */
    .rail[data-user-hidden] { transform: translate3d(-100%, 0, 0); }
    :host([data-rail-anim]) .rail { transition: transform 200ms cubic-bezier(.3,.7,.4,1); }
    :host([data-rail-anim]) .stage { transition: left 200ms cubic-bezier(.3,.7,.4,1); }
    :host([data-rail-anim]) .canvas { transition: transform 200ms cubic-bezier(.3,.7,.4,1); }
    :host([data-rail-anim]) .notes { transition: left 200ms cubic-bezier(.3,.7,.4,1); }

    .thumb {
      position: relative;
      display: flex;
      align-items: flex-start;
      gap: 9px;
      cursor: pointer;
      user-select: none;
    }
    .thumb[data-dragging] { cursor: grabbing; }
    .thumb .num {
      width: 14px;
      flex-shrink: 0;
      font-size: 12px;
      line-height: 1;
      font-weight: 400;
      text-align: center;
      color: #646A73;
      padding-top: 8px;
      font-variant-numeric: tabular-nums;
    }
    .thumb .frame {
      position: relative;
      flex: 1;
      min-width: 0;
      aspect-ratio: var(--deck-aspect);
      background: #fff;
      border-radius: 6px;
      /* Default hairline as a box-shadow, not a border: the frame is the
         absolutely-positioned origin for the cloned slide, so a real border
         would shift the clone; box-shadow doesn't affect layout, so
         _scaleThumbs' frame.offsetWidth read stays correct. */
      box-shadow: 0 0 0 1px #DEE0E3;
      outline: 2px solid transparent;
      outline-offset: 2px;
      overflow: hidden;
      transition: outline-color 120ms ease, box-shadow 120ms ease;
    }
    .thumb:hover .frame { outline-color: #1f23290d; }
    .thumb { outline: none; }
    .thumb:focus-visible .frame { outline-color: #1f23290d; }
    .thumb[data-current] .num { color: #1F2329; font-weight: 500; }
    .thumb[data-current] .frame { outline-color: #1F2329; }
    /* Elevated "picked up" look on the *stationary* source while dragging
       (outline hidden, card lifted); the ::before drop-line marks the landing
       position. The floating ghost under the cursor is a separate custom
       drag-image built in _makeDragGhost — the browser's native snapshot of
       .thumb clipped this frame's outside-offset ring and carried the number
       gutter, so we no longer let it draw the ghost. */
    .thumb[data-dragging] .frame {
      outline-color: transparent;
      box-shadow: 0 8px 24px rgba(31,35,41,0.22), 0 0 0 1px rgba(31,35,41,0.08);
    }
    .thumb::before {
      content: '';
      position: absolute;
      left: 24px;
      right: 0;
      height: 3px;
      border-radius: 2px;
      background: #336DF4;
      opacity: 0;
      pointer-events: none;
    }
    .thumb[data-drop="before"]::before { top: -8px; opacity: 1; }
    .thumb[data-drop="after"]::before { bottom: -8px; opacity: 1; }
    .thumb .skip-icon {
      display: none;
      position: absolute;
      inset: 0;
      align-items: center;
      justify-content: center;
      background: rgba(255,255,255,0.6);
      z-index: 1;
    }
    .thumb[data-skip] .skip-icon { display: flex; }

    .ctxmenu {
      position: fixed;
      min-width: 160px;
      padding: 4px;
      background: #fff;
      color: #1F2329;
      border: 0.5px solid #D2D5D8;
      border-radius: 6px;
      box-shadow: 0 4px 8px -8px rgba(0, 0, 0, 0.06), 0 6px 12px 0 rgba(0, 0, 0, 0.04), 0 8px 24px 8px rgba(0, 0, 0, 0.04);
      z-index: 2147483100;
      display: none;
      font-size: 14px;
      line-height: 22px;
    }
    .ctxmenu[data-open] { display: block; }
    .ctxmenu button {
      display: block;
      width: 100%;
      appearance: none;
      border: 0;
      background: transparent;
      color: #1F2329;
      font: inherit;
      text-align: left;
      padding: 6px 8px;
      border-radius: 4px;
      cursor: pointer;
    }
    .ctxmenu button:hover:not(:disabled) { background: #F2F3F5; }
    .ctxmenu button:disabled { opacity: 0.35; cursor: default; }
    .ctxmenu hr {
      border: 0;
      border-top: 0.5px solid #D2D5D8;
      margin: 4px -4px;
    }

    .rail-resize {
      position: fixed;
      left: calc(var(--deck-rail-w, 192px) - 3px);
      top: 0;
      bottom: 0;
      width: 6px;
      cursor: col-resize;
      z-index: 2147482600;
      touch-action: none;
    }
    .rail-resize:hover,
    .rail-resize[data-dragging] { background: rgba(255,255,255,0.12); }
    :host([no-rail]) .rail-resize,
    :host([noscale]) .rail-resize,
    .rail[data-presenting] + .rail-resize,
    .rail[data-user-hidden] + .rail-resize { display: none; }

    /* ── 移动端竖排浏览 ─────────────────────────────────────── */
    :host([data-mobile-list]) .stage {
      display: block;
      overflow-y: auto;
      -webkit-overflow-scrolling: touch;
      background: #F8F9FA;
    }
    :host([data-mobile-list]) .canvas {
      transform: none !important;
      background: transparent;
      will-change: auto;
    }
    :host([data-mobile-list][data-windowed]) .canvas { border: none; box-shadow: none; }
    :host([data-mobile-list]) .rail, :host([data-mobile-list]) .rail-resize { display: none; }
    :host([data-mobile-list]) ::slotted(*) {
      opacity: 1;
      visibility: visible;
      pointer-events: auto;
      transform-origin: 0 0;
      box-sizing: border-box;
    }
    /* Skipped slides get no nth-child placement rule from _fitMobileList —
       without this they'd fall back to the base inset:0 stacking rule and,
       now force-visible, paint over the whole list canvas and swallow taps.
       (The equivalent rule further down lives inside @media print only.) */
    :host([data-mobile-list]) ::slotted([data-deck-skip]) { display: none !important; }

    /* ── 移动端播放：CSS 旋转伪横屏（不依赖 orientation.lock）────
       只在设备物理竖屏时旋转；用户顺势把手机转成横屏（系统自动旋转）
       后，视口本身已是横屏，再叠 90° 会让画面侧躺——此时退化为常规
       full-bleed 适配，_fitMobilePresent/_mobPresentZone 同步按
       orientation 分支换轴。 */
    :host([data-mobile-present]) .stage { background: #000; }
    @media (orientation: portrait) {
      :host([data-mobile-present]) .stage {
        inset: auto;
        left: 50%;
        top: 50%;
        width: 100vh;
        height: 100vw;
        transform: translate(-50%, -50%) rotate(90deg);
      }
    }

    /* ── 移动端页码徽标（规格：Figma 2965:32047）────────────── */
    .mob-badges { display: none; }
    :host([data-mobile-list]) .mob-badges {
      display: block;
      position: absolute;
      inset: 0;
      pointer-events: none;
      z-index: 10;
    }
    .mob-badge {
      position: absolute;
      height: 12px;
      box-sizing: border-box;
      padding: 0 2px;
      border-radius: 3px;
      background: rgba(31, 35, 41, 0.2);
      color: #fff;
      font-family: 'PingFang SC', -apple-system, system-ui, sans-serif;
      font-size: 8px;
      line-height: 12px;
      text-align: center;
      opacity: 0;
      transition: opacity 0.1s linear;
    }
    :host([data-mob-scrolling]) .mob-badge { opacity: 1; }

    /* ── 移动端播放控件层（规格：Figma 2965:34386）──────────── */
    .mob-ui { display: none; }
    :host([data-mobile-present][data-mob-ui]) .mob-ui {
      display: block;
      position: absolute;
      inset: 0;
      pointer-events: none;
      z-index: 20;
    }
    .mob-back {
      position: absolute;
      left: max(16px, env(safe-area-inset-left));
      top: 12px;
      pointer-events: auto;
      display: flex;
      align-items: center;
      gap: 6px;
      border: none;
      border-radius: 999px;
      padding: 6px 14px;
      background: rgba(0, 0, 0, 0.4);
      color: #fff;
      font-family: 'PingFang SC', -apple-system, system-ui, sans-serif;
      font-size: 15px;
      font-weight: 500;
      cursor: pointer;
    }
    .mob-strip {
      position: absolute;
      left: 0;
      right: 0;
      bottom: 0;
      pointer-events: auto;
      display: flex;
      gap: 8px;
      padding: 10px 16px calc(10px + env(safe-area-inset-bottom));
      /* 透明浮在 slide 上（验收对齐设计稿）——缩略图自带白底+描边已足够区分 */
      background: transparent;
      overflow-x: auto;
    }
    .mob-strip .mthumb { flex: 0 0 132px; cursor: pointer; }
    .mob-strip .mframe {
      width: 132px;
      height: 72px;
      border-radius: 8px;
      border: 0.5px solid #DEE0E3;
      overflow: hidden;
      position: relative;
      background: #fff;
    }
    .mob-strip .mthumb[data-current] .mframe {
      outline: 1px solid #336DF4;
      outline-offset: 2px;
      border-radius: 10px;
    }
    .mob-strip .mnum {
      margin-top: 2px;
      text-align: center;
      font-family: 'PingFang SC', -apple-system, system-ui, sans-serif;
      font-size: 12px;
      line-height: 20px;
      font-weight: 500;
      /* 条带透明、底衬通常是播放态黑底/slide 内容——页码用白色（对齐设计稿） */
      color: rgba(255, 255, 255, 0.9);
    }
    .mob-strip .mthumb[data-current] .mnum { color: #336DF4; }

    /* ── Speaker-notes dock ──────────────────────────────────────────────
       Bottom panel spanning the non-rail width in edit mode: a resize grip
       (drag to set height, persisted to localStorage) + an editable textarea
       bound to the current slide's note. Hidden while presenting / preview /
       narrow / noscale / no-rail / print — same editing-chrome gating as the
       rail. Its left edge is set to the live rail width by _fit. */
    .notes {
      position: fixed;
      left: var(--deck-rail-w, 192px);
      right: 20px;
      bottom: 0;
      height: var(--deck-notes-h, 160px);
      background: #fff;
      border: 0.5px solid #D2D5D8;
      border-bottom: none;
      border-radius: 12px 12px 0 0;
      box-shadow: 0 2px 4px -4px rgba(31, 35, 41, 0.02), 0 4px 8px 0 rgba(31, 35, 41, 0.02), 0 4px 16px 4px rgba(31, 35, 41, 0.03);
      box-sizing: border-box;
      display: flex;
      flex-direction: column;
      z-index: 2147482400;
    }
    :host([no-rail]) .notes,
    :host([noscale]) .notes { display: none; }
    .notes[data-hidden] { display: none; }
    @media (max-width: 640px) { .notes { display: none; } }
    .notes-handle {
      flex-shrink: 0;
      height: 20px;
      display: flex;
      align-items: center;
      justify-content: center;
      cursor: row-resize;
      color: #8F959E;
      font-size: 18px;
      line-height: 20px;
      letter-spacing: 2px;
      user-select: none;
      touch-action: none;
    }
    .notes-handle:hover,
    .notes-handle[data-dragging] { color: #646A73; }
    .notes-body {
      flex: 1;
      min-height: 0;
      width: 100%;
      box-sizing: border-box;
      border: 0;
      outline: none;
      resize: none;
      background: transparent;
      color: #1F2329;
      font: inherit;
      font-size: 14px;
      line-height: 1.6;
      padding: 4px 24px 12px;
      overflow-y: auto;
    }
    .notes-body::placeholder { color: #8F959E; }

    /* ── Print: one page per slide, no chrome ────────────────────────────
       The screen layout stacks every slide at inset:0 inside a scaled
       canvas; for print we want them in document flow at the authored
       design size so the browser paginates one slide per sheet. The
       @page size is set from the width/height attributes via the inline
       <style id="deck-stage-print-page"> that connectedCallback injects
       into <head> (the @page at-rule has no effect inside shadow DOM). */
    @media print {
      :host {
        position: static;
        inset: auto;
        background: none;
        overflow: visible;
        color: inherit;
      }
      .stage { position: static; display: block; }
      .canvas {
        transform: none !important;
        width: auto !important;
        height: auto !important;
        background: none;
        will-change: auto;
        /* !important: :host([data-windowed]) .canvas (0,2,0) outranks a bare
           .canvas rule inside this media query. */
        box-shadow: none !important;
      }
      ::slotted(*) {
        position: relative !important;
        inset: auto !important;
        width: var(--deck-design-w) !important;
        height: var(--deck-design-h) !important;
        box-sizing: border-box !important;
        opacity: 1 !important;
        visibility: visible !important;
        pointer-events: auto;
        break-after: page;
        page-break-after: always;
        break-inside: avoid;
        overflow: hidden;
      }
      /* :last-child alone isn't enough once data-deck-skip hides the
         trailing slide(s) — the last *visible* slide still carries
         break-after:page and prints a blank sheet. _markLastVisible()
         maintains data-deck-last-visible on the last non-skipped slide. */
      ::slotted(*:last-child),
      ::slotted([data-deck-last-visible]) {
        break-after: auto;
        page-break-after: auto;
      }
      ::slotted([data-deck-skip]) { display: none !important; }
      .rail, .rail-resize, .ctxmenu, .notes { display: none !important; }
    }
  `;

  class DeckStage extends HTMLElement {
    static get observedAttributes() { return ['width', 'height', 'noscale', 'no-rail']; }

    constructor() {
      super();
      this._root = this.attachShadow({ mode: 'open' });
      this._index = 0;
      this._slides = [];
      this._notes = [];
      this._menuIndex = -1;
      this._notesPersistTimer = null;

      this._onKey = this._onKey.bind(this);
      this._onResize = this._onResize.bind(this);
      this._onSlotChange = this._onSlotChange.bind(this);
      this._onTap = this._onTap.bind(this);
      this._onMessage = this._onMessage.bind(this);
      this._onHashChange = this._onHashChange.bind(this);
      // Capture-phase close so a click anywhere dismisses the menu, but
      // ignore clicks that land inside the menu itself — otherwise the
      // capture handler runs before the menu's own (bubble) handler and
      // clears _menuIndex out from under it.
      this._onDocClick = (e) => {
        if (this._menu && e.composedPath && e.composedPath().includes(this._menu)) return;
        this._closeMenu();
      };
    }

    get designWidth() {
      return parseInt(this.getAttribute('width'), 10) || DESIGN_W_DEFAULT;
    }
    get designHeight() {
      return parseInt(this.getAttribute('height'), 10) || DESIGN_H_DEFAULT;
    }

    connectedCallback() {
      // Capture modes that render a clean full-bleed single slide, both routed
      // through the same no-rail path: the host's pre-screenshot ?thumbnail=1
      // (product thumbnail — slide 1) and the presenter-view popup's
      // ?_snthumb=...#N (prev/cur/next thumbnails). Both drop the rail (wrong
      // scale, offsets the stage into a gutter) and render full-bleed — no
      // windowed margin/shadow, see _fit. A bare load with no #N hash starts at
      // slide 1, so ?thumbnail=1 alone yields a clean first-slide frame.
      this._snthumb = /[?&](_snthumb|thumbnail)=/.test(location.search);
      this._mobile = isMobileUA();
      this._syncMobileMode();
      if (this._snthumb) this.setAttribute('no-rail', '');
      this._render();
      this._loadNotes();
      this._syncPrintPageRule();
      window.addEventListener('keydown', this._onKey);
      window.addEventListener('resize', this._onResize);
      window.addEventListener('message', this._onMessage);
      window.addEventListener('hashchange', this._onHashChange);
      window.addEventListener('click', this._onDocClick, true);
      this.addEventListener('click', this._onTap);
      // Print lays every slide out as its own page, so [data-deck-active]-
      // gated entrance styles need the attribute on every slide (not just
      // the current one) or their content prints at the hidden base style.
      // The transient freeze style lands BEFORE the attributes so any
      // attribute-keyed transition fires at 0s (changing transition-
      // duration after a transition has started doesn't affect it).
      this._onBeforePrint = () => {
        if (this._freezeStyle) this._freezeStyle.remove();
        this._freezeStyle = document.createElement('style');
        this._freezeStyle.textContent = '*,*::before,*::after{transition-duration:0s !important}';
        document.head.appendChild(this._freezeStyle);
        this._slides.forEach((s) => s.setAttribute('data-deck-active', ''));
      };
      this._onAfterPrint = () => {
        this._applyIndex({ broadcast: false });
        if (this._freezeStyle) { this._freezeStyle.remove(); this._freezeStyle = null; }
      };
      window.addEventListener('beforeprint', this._onBeforePrint);
      window.addEventListener('afterprint', this._onAfterPrint);
      // Initial collection + layout happens via slotchange, which fires on mount.
      this._enableRail();
      // Hold the stage hidden until webfonts are ready so the first visible
      // paint has the deck's real typography — the :not(:defined) guard in
      // the page HTML only covers custom-element upgrade, not font load.
      // Capped so a 404'd font URL can't blank the deck indefinitely.
      this.setAttribute('data-fonts-pending', '');
      const reveal = () => this.removeAttribute('data-fonts-pending');
      // rAF first: fonts.ready is a pre-resolved promise until layout has
      // resolved the slotted text's font-family and pushed a FontFace into
      // 'loading'. Reading it here in connectedCallback (parse-time) would
      // settle the race in a microtask before any font fetch starts.
      requestAnimationFrame(() => {
        Promise.race([
          document.fonts ? document.fonts.ready : Promise.resolve(),
          new Promise((r) => setTimeout(r, 2000)),
        ]).then(reveal, reveal);
      });
      // Announce to the host that this product IS a deck scene.
      try { window.parent.postMessage({ type: 'miaoda:deck:available' }, '*'); } catch (e) {}
    }

    _enableRail() {
      // Idempotent — host may post miaoda:deck:rail-enabled multiple times.
      // no-rail guard keeps the observers/stylesheet walk off the cheap path
      // for presenter-popup thumbnail iframes (up to 9 per view).
      if (this._railEnabled || this.hasAttribute('no-rail')) return;
      this._railEnabled = true;
      // Per-viewer preference — restored alongside rail width. Default on;
      // only a stored '0' (from the TweaksPanel toggle) hides it.
      this._railVisible = true;
      try {
        if (localStorage.getItem('deck-stage.railVisible') === '0') this._railVisible = false;
      } catch (e) {}
      // Live thumbnail updates: watch the light-DOM slides for content
      // edits and re-clone just the affected thumb(s), debounced. Ignore
      // the data-deck-* / data-screen-label / data-miaoda-validate attributes
      // this component itself writes so nav and skip don't trigger
      // spurious refreshes.
      const OWN_ATTRS = /^data-(deck-|screen-label$|om-validate$)/;
      this._liveDirty = new Set();
      this._liveObserver = new MutationObserver((records) => {
        for (const r of records) {
          if (r.type === 'attributes' && OWN_ATTRS.test(r.attributeName || '')) continue;
          let n = r.target;
          while (n && n.parentElement !== this) n = n.parentElement;
          if (n && this._slideSet && this._slideSet.has(n)) this._liveDirty.add(n);
        }
        if (this._liveDirty.size && !this._liveTimer) {
          this._liveTimer = setTimeout(() => {
            this._liveTimer = null;
            this._liveDirty.forEach((s) => this._refreshThumb(s));
            this._liveDirty.clear();
          }, 200);
        }
      });
      this._liveObserver.observe(this, {
        subtree: true, childList: true, characterData: true, attributes: true,
      });
      // Lazy thumbnail materialization — clone the slide only when its
      // frame scrolls into (or near) the rail viewport. rootMargin gives
      // ~4 thumbs of pre-load so fast scrolling doesn't flash blanks.
      this._railObserver = new IntersectionObserver((entries) => {
        entries.forEach((e) => {
          if (e.isIntersecting && e.target.__deckThumb) {
            this._materialize(e.target.__deckThumb);
          }
        });
      }, { root: this._rail, rootMargin: '400px 0px' });
      // Tweaks typically change CSS vars / attrs OUTSIDE <deck-stage>
      // (on <html>, <body>, a wrapper div, or a <style> tag), which
      // _liveObserver can't see. Re-snapshot author CSS (constructable
      // sheet is shared by reference, so one replaceSync updates every
      // thumb shadow root) and re-sync each thumb host's attrs + custom
      // properties. In-slide DOM mutations are _liveObserver's job.
      // Debounced so slider drags don't thrash.
      this._onTweakChange = () => {
        clearTimeout(this._tweakTimer);
        this._tweakTimer = setTimeout(() => {
          this._snapshotAuthorCss();
          // One getComputedStyle for the whole batch — each
          // getPropertyValue read below reuses the same computed style
          // as long as nothing invalidates layout between thumbs.
          const cs = getComputedStyle(this);
          (this._thumbs || []).forEach((t) => {
            if (t.host) this._syncThumbHostAttrs(t.host, cs);
          });
        }, 120);
      };
      window.addEventListener('tweakchange', this._onTweakChange);
      this._snapshotAuthorCss();
      // Build the rail now that it's enabled — slotchange already fired,
      // so _renderRail's early-return skipped the initial build.
      this._syncRailHidden();
      this._renderRail();
      this._fit();
      // The notes dock is editing chrome too — show it and load the current
      // slide's note now that the rail feature is enabled.
      this._syncNotesHidden();
      this._syncNotesBody();
    }

    /** Snapshot document stylesheets into a constructable sheet that each
     *  thumbnail's nested shadow root adopts — so author CSS styles the
     *  cloned slide content without touching this component's chrome.
     *  Re-callable: the constructable sheet is reused via replaceSync so
     *  every already-adopted shadow root picks up the fresh CSS.
     *
     *  Cross-origin sheets (a CDN styles.css) throw SecurityError on
     *  .cssRules — the rules style the light DOM but CSSOM won't expose them,
     *  so the snapshot comes back empty and thumbnail clones render unstyled.
     *  Re-fetch those sheets' source and re-apply when it lands; the shared
     *  adopted sheet means one replaceSync restyles every clone (no re-clone).
     *  The fetch is CORS-gated — a CDN without Access-Control-Allow-Origin
     *  fails it and we degrade to an unstyled clone, no worse than before. */
    _snapshotAuthorCss() {
      // Generation guard: a stale fetch (from a snapshot a newer call has
      // superseded) must not clobber the current adopted CSS.
      const gen = (this._cssGen = (this._cssGen || 0) + 1);
      if (!this._xoCssCache) this._xoCssCache = new Map(); // href → fetched text ('' = failed)
      const pending = [];
      this._applyAuthorCss(this._collectAuthorCss(pending));
      if (!pending.length) return;
      Promise.all(pending.map((href) =>
        fetch(href).then((r) => (r.ok ? r.text() : '')).catch(() => '')
          .then((text) => { this._xoCssCache.set(href, text); })
      )).then(() => {
        if (this._cssGen !== gen) return;
        this._applyAuthorCss(this._collectAuthorCss(null));
        if (this._adoptedSheet) {
          // Shared sheet already restyled every clone — just re-mirror vars.
          const cs = getComputedStyle(this);
          (this._thumbs || []).forEach((t) => { if (t.host) this._syncThumbHostAttrs(t.host, cs); });
        } else {
          // Fallback (no constructable sheets): each clone baked its own
          // <style> at materialize, so re-clone to pick up the fetched CSS.
          (this._thumbs || []).forEach((t) => { if (t.host) this._refreshThumb(t.slide); });
        }
      });
    }

    /** Concatenate every document stylesheet's rules in document order. A
     *  cross-origin sheet whose .cssRules throws is unreadable via CSSOM:
     *  substitute its re-fetched source if cached, else push its href to
     *  pendingOut (when provided) and leave a placeholder until the fetch lands. */
    _collectAuthorCss(pendingOut) {
      return Array.from(document.styleSheets).map((sh) => {
        try {
          return Array.from(sh.cssRules).map((r) => r.cssText).join('\n');
        } catch (e) {
          const href = sh.href;
          if (!href) return '';
          if (this._xoCssCache.has(href)) return this._xoCssCache.get(href);
          if (pendingOut) pendingOut.push(href);
          return '';
        }
      }).join('\n');
    }

    /** Rewrite raw author CSS so its document-scoped selectors match inside a
     *  thumbnail's shadow root, then (re)load it into the shared adopted sheet.
     *  :root in an adopted sheet inside a shadow root matches nothing (only the
     *  document root qualifies), so author rules like
     *  `:root[data-voice="modern"] .serif` never reach the clones. Rewrite
     *  :root → :host and mirror <html>'s data-*, class and lang onto each thumb
     *  host (see _syncThumbHostAttrs) so the same selectors match inside it.
     *  The <deck-stage> type selector gets the same treatment: from a clone's
     *  point of view inside an isolated thumb shadow root there is no real
     *  <deck-stage> ancestor, so a rule like `deck-stage section { background }`
     *  (the common per-slide default-background idiom) would never match and
     *  the clone renders with a transparent background — through which the
     *  page-level html/body background (rewritten to :host above) leaks. The
     *  thumb's own host IS the deck-stage from the clone's perspective, so
     *  alias deck-stage → :host to restore the match. */
    _applyAuthorCss(rawCss) {
      const authorCss = rawCss
        // The shadow host is featureless outside the functional :host(...)
        // form, so any compound on :root — [attr], .class, #id, :pseudo —
        // must become :host(<compound>) not :host<compound>. Same for the
        // html type selector (Tailwind class-strategy dark mode emits
        // html.dark; Pico uses html[data-theme]), which has nothing to
        // match inside the thumb's shadow tree.
        .replace(/:root((?:\[[^\]]*\]|[.#][-\w]+|:[-\w]+(?:\([^)]*\))?)+)/g, ':host($1)')
        .replace(/:root\b/g, ':host')
        .replace(/(^|[\s,>~+(}])html((?:\[[^\]]*\]|[.#][-\w]+|:[-\w]+(?:\([^)]*\))?)+)(?![-\w])/g, '$1:host($2)')
        .replace(/(^|[\s,>~+(}])html(?![-\w])/g, '$1:host')
        // Same rewrite for the deck-stage type selector (see the doc comment).
        // The negative-lookahead (?![-\w]) keeps `.deck-stage-title` and the
        // `--deck-stage-*` custom-property names untouched.
        .replace(/(^|[\s,>~+(}])deck-stage((?:\[[^\]]*\]|[.#][-\w]+|:[-\w]+(?:\([^)]*\))?)+)(?![-\w])/g, '$1:host($2)')
        .replace(/(^|[\s,>~+(}])deck-stage(?![-\w])/g, '$1:host');
      // Every custom property the author references. _syncThumbHostAttrs
      // mirrors each one's *computed* value at <deck-stage> onto the
      // thumb host so the live value wins over the :host default above
      // regardless of which ancestor the tweak wrote to (<html>, <body>,
      // a wrapper div, or the deck-stage element itself all inherit
      // down to getComputedStyle(this)).
      this._authorVars = new Set(authorCss.match(/--[\w-]+/g) || []);
      try {
        if (!this._adoptedSheet) this._adoptedSheet = new CSSStyleSheet();
        this._adoptedSheet.replaceSync(authorCss);
      } catch (e) {
        this._adoptedSheet = null;
        this._authorCss = authorCss;
      }
    }

    _syncThumbHostAttrs(host, cs) {
      const de = document.documentElement;
      // setAttribute overwrites but can't delete — an attr removed from
      // <html> (toggleAttribute off, classList emptied) would linger on
      // the host and :host([data-*]) / :host(.foo) rules would keep
      // matching. Remove stale mirrored attrs first; iterate backward
      // because removeAttribute mutates the live NamedNodeMap.
      for (let i = host.attributes.length - 1; i >= 0; i--) {
        const n = host.attributes[i].name;
        if ((n.startsWith('data-') || n === 'class' || n === 'lang')
            && !de.hasAttribute(n)) {
          host.removeAttribute(n);
        }
      }
      for (const a of de.attributes) {
        if (a.name.startsWith('data-') || a.name === 'class' || a.name === 'lang') {
          host.setAttribute(a.name, a.value);
        }
      }
      // The :root→:host rewrite in _snapshotAuthorCss pins each custom
      // property to its stylesheet default on the thumb host, shadowing
      // the live value that would otherwise inherit. Tweaks can write the
      // live value on any ancestor — <html>, <body>, a wrapper div, the
      // deck-stage element — so read it as the *computed* value at
      // <deck-stage> (which sees the whole inheritance chain) rather than
      // trying to guess which element the author wrote to. Inline on the
      // host beats the :host{} rule. remove-stale covers vars dropped
      // from the stylesheet between snapshots.
      const vars = this._authorVars || new Set();
      for (let i = host.style.length - 1; i >= 0; i--) {
        const p = host.style[i];
        if (p.startsWith('--') && !vars.has(p)) host.style.removeProperty(p);
      }
      const live = cs || getComputedStyle(this);
      vars.forEach((p) => {
        const v = live.getPropertyValue(p);
        if (v) host.style.setProperty(p, v.trim());
        else host.style.removeProperty(p);
      });
    }

    disconnectedCallback() {
      window.removeEventListener('keydown', this._onKey);
      window.removeEventListener('resize', this._onResize);
      window.removeEventListener('message', this._onMessage);
      window.removeEventListener('hashchange', this._onHashChange);
      window.removeEventListener('click', this._onDocClick, true);
      window.removeEventListener('beforeprint', this._onBeforePrint);
      window.removeEventListener('afterprint', this._onAfterPrint);
      if (this._freezeStyle) { this._freezeStyle.remove(); this._freezeStyle = null; }
      if (this._dragGhost) { this._dragGhost.remove(); this._dragGhost = null; }
      this.removeEventListener('click', this._onTap);
      if (this._liveTimer) clearTimeout(this._liveTimer);
      if (this._tweakTimer) clearTimeout(this._tweakTimer);
      if (this._railAnimTimer) clearTimeout(this._railAnimTimer);
      if (this._notesPersistTimer) clearTimeout(this._notesPersistTimer);
      clearTimeout(this._mobUiTimer);
      clearTimeout(this._mobScrollIdleTimer);
      if (this._mobScrollRaf) { cancelAnimationFrame(this._mobScrollRaf); this._mobScrollRaf = null; }
      if (this._scaleRaf) cancelAnimationFrame(this._scaleRaf);
      if (this._liveObserver) this._liveObserver.disconnect();
      if (this._railObserver) this._railObserver.disconnect();
      if (this._onTweakChange) window.removeEventListener('tweakchange', this._onTweakChange);
    }

    attributeChangedCallback() {
      if (this._canvas) {
        this._canvas.style.width = this.designWidth + 'px';
        this._canvas.style.height = this.designHeight + 'px';
        this._canvas.style.setProperty('--deck-design-w', this.designWidth + 'px');
        this._canvas.style.setProperty('--deck-design-h', this.designHeight + 'px');
        if (this._rail) {
          this._rail.style.setProperty('--deck-aspect', this.designWidth + '/' + this.designHeight);
        }
        this._syncMobileMode();
        this._fit();
        this._scaleThumbs();
        this._syncPrintPageRule();
      }
    }

    _render() {
      const style = document.createElement('style');
      style.textContent = stylesheet;

      const stage = document.createElement('div');
      stage.className = 'stage';

      const canvas = document.createElement('div');
      canvas.className = 'canvas';
      canvas.style.width = this.designWidth + 'px';
      canvas.style.height = this.designHeight + 'px';
      canvas.style.setProperty('--deck-design-w', this.designWidth + 'px');
      canvas.style.setProperty('--deck-design-h', this.designHeight + 'px');

      const slot = document.createElement('slot');
      slot.addEventListener('slotchange', this._onSlotChange);
      canvas.appendChild(slot);
      stage.appendChild(canvas);

      this._onMobScroll = this._onMobScroll.bind(this);
      stage.addEventListener('scroll', this._onMobScroll, { passive: true });

      // 移动竖排的逐页定位规则（::slotted(:nth-child(i))），_fitMobileList 重建。
      this._mobStyle = document.createElement('style');

      this._mobBadges = document.createElement('div');
      this._mobBadges.className = 'mob-badges export-hidden';
      this._mobBadges.setAttribute('data-miaoda-chrome', '');
      canvas.appendChild(this._mobBadges);

      // Thumbnail rail + context menu. Thumbnails are populated in
      // _renderRail() after _collectSlides().
      const rail = document.createElement('div');
      rail.className = 'rail export-hidden';
      rail.setAttribute('data-miaoda-chrome', '');
      rail.style.setProperty('--deck-aspect', this.designWidth + '/' + this.designHeight);
      // Edge auto-scroll while dragging a thumb near the rail's top/bottom
      // so off-screen drop targets are reachable. Native dragover fires
      // continuously while the pointer is stationary, so a per-event nudge
      // (ramped by edge proximity) is enough — no rAF loop needed.
      rail.addEventListener('dragover', (e) => {
        if (this._dragFrom == null) return;
        // preventDefault makes the whole rail — including the gaps between
        // thumbs, where the drop-line actually renders — a valid drop target.
        // Without it a release in a gap is rejected and the slide snaps back
        // even though the indicator was showing.
        e.preventDefault();
        e.dataTransfer.dropEffect = 'move';
        const r = rail.getBoundingClientRect();
        const EDGE = 40;
        const dt = e.clientY - r.top;
        const db = r.bottom - e.clientY;
        if (dt < EDGE) rail.scrollTop -= Math.ceil((EDGE - dt) / 3);
        else if (db < EDGE) rail.scrollTop += Math.ceil((EDGE - db) / 3);
        // Over a thumb its own dragover set the indicator (O(1)); over a gap
        // no thumb handler fires, so resolve the nearest slot here.
        const overThumb = e.target && e.target.closest && e.target.closest('.thumb');
        if (!overThumb) {
          const tgt = this._railDropTarget(e.clientY);
          if (tgt) this._setDrop(tgt.i, tgt.pos);
        }
      });
      rail.addEventListener('drop', (e) => {
        // A drop over a thumb is handled by the thumb's own handler, which
        // nulls _dragFrom before the event bubbles here — so this branch only
        // runs for releases that land in a gap / the rail padding. It commits
        // to whatever slot the indicator is currently showing.
        if (this._dragFrom == null) return;
        e.preventDefault();
        const on = this._dropOn;
        const from = this._dragFrom;
        this._dragFrom = null;
        let to = on ? (this._dropWhere === 'after' ? on.i + 1 : on.i) : from;
        if (from < to) to--;
        this._clearDrop();
        if (on && to !== from) this._moveSlide(from, to);
      });

      const menu = document.createElement('div');
      menu.className = 'ctxmenu export-hidden';
      menu.setAttribute('data-miaoda-chrome', '');
      menu.innerHTML = `
        <button type="button" data-act="skip">隐藏此页</button>
        <button type="button" data-act="up">上移</button>
        <button type="button" data-act="down">下移</button>
        <hr>
        <button type="button" data-act="delete">删除</button>
      `;
      menu.addEventListener('click', (e) => {
        const act = e.target && e.target.getAttribute && e.target.getAttribute('data-act');
        if (!act) return;
        const i = this._menuIndex;
        this._closeMenu();
        if (act === 'skip') this._toggleSkip(i);
        else if (act === 'up') this._moveSlide(i, i - 1);
        else if (act === 'down') this._moveSlide(i, i + 1);
        else if (act === 'delete') this._deleteSlide(i);
      });
      menu.addEventListener('contextmenu', (e) => e.preventDefault());

      // Rail resize handle — drag to set --deck-rail-w, persisted to
      // localStorage so the width survives reloads.
      const resize = document.createElement('div');
      resize.className = 'rail-resize export-hidden';
      resize.setAttribute('data-miaoda-chrome', '');
      resize.addEventListener('pointerdown', (e) => {
        e.preventDefault();
        resize.setPointerCapture(e.pointerId);
        resize.setAttribute('data-dragging', '');
        const move = (ev) => this._setRailWidth(ev.clientX);
        const up = () => {
          resize.removeEventListener('pointermove', move);
          resize.removeEventListener('pointerup', up);
          resize.removeEventListener('pointercancel', up);
          resize.removeAttribute('data-dragging');
          try { localStorage.setItem('deck-stage.railWidth', String(this._railPx)); } catch (err) {}
        };
        resize.addEventListener('pointermove', move);
        resize.addEventListener('pointerup', up);
        resize.addEventListener('pointercancel', up);
      });

      // Speaker-notes dock — a resize grip + an editable textarea bound to the
      // current slide's note. Chrome (export-hidden / data-miaoda-chrome) like
      // the rail/overlay so it's excluded from PPTX/screenshot capture.
      const notes = document.createElement('div');
      notes.className = 'notes export-hidden';
      notes.setAttribute('data-miaoda-chrome', '');
      const notesHandle = document.createElement('div');
      notesHandle.className = 'notes-handle';
      notesHandle.innerHTML = '<svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M13.3008 11.4434C13.3008 10.822 13.8045 10.3184 14.4258 10.3184C15.047 10.3185 15.5508 10.8221 15.5508 11.4434C15.5508 12.0646 15.047 12.5682 14.4258 12.5684C13.8045 12.5684 13.3008 12.0647 13.3008 11.4434ZM13.3008 6.55664C13.3008 5.93532 13.8045 5.43164 14.4258 5.43164C15.047 5.43179 15.5508 5.93541 15.5508 6.55664C15.5508 7.17787 15.047 7.68149 14.4258 7.68164C13.8045 7.68164 13.3008 7.17796 13.3008 6.55664ZM7.875 11.4434C7.875 10.822 8.37868 10.3184 9 10.3184C9.62132 10.3184 10.125 10.822 10.125 11.4434C10.125 12.0647 9.62132 12.5684 9 12.5684C8.37868 12.5684 7.875 12.0647 7.875 11.4434ZM7.875 6.55664C7.875 5.93532 8.37868 5.43164 9 5.43164C9.62132 5.43164 10.125 5.93532 10.125 6.55664C10.125 7.17796 9.62132 7.68164 9 7.68164C8.37868 7.68164 7.875 7.17796 7.875 6.55664ZM2.44922 11.4434C2.44922 10.822 2.9529 10.3184 3.57422 10.3184C4.19554 10.3184 4.69922 10.822 4.69922 11.4434C4.69922 12.0647 4.19554 12.5684 3.57422 12.5684C2.9529 12.5684 2.44922 12.0647 2.44922 11.4434ZM2.44922 6.55664C2.44922 5.93532 2.9529 5.43164 3.57422 5.43164C4.19554 5.43164 4.69922 5.93532 4.69922 6.55664C4.69922 7.17796 4.19554 7.68164 3.57422 7.68164C2.9529 7.68164 2.44922 7.17796 2.44922 6.55664Z" fill="currentColor"/></svg>';
      notesHandle.setAttribute('title', '拖动调整高度');
      const notesBody = document.createElement('textarea');
      notesBody.className = 'notes-body';
      notesBody.setAttribute('placeholder', '点击添加演示者备注');
      notesBody.setAttribute('aria-label', '演示者备注');
      notesBody.setAttribute('spellcheck', 'false');
      notes.append(notesHandle, notesBody);

      // Drag the grip to resize the dock height (mirror the rail-resize
      // pattern); persist to localStorage so it survives reloads.
      notesHandle.addEventListener('pointerdown', (e) => {
        e.preventDefault();
        notesHandle.setPointerCapture(e.pointerId);
        notesHandle.setAttribute('data-dragging', '');
        const move = (ev) => this._setNotesHeight(window.innerHeight - ev.clientY);
        const up = () => {
          notesHandle.removeEventListener('pointermove', move);
          notesHandle.removeEventListener('pointerup', up);
          notesHandle.removeEventListener('pointercancel', up);
          notesHandle.removeAttribute('data-dragging');
          try { localStorage.setItem('deck-stage.notesHeight', String(this._notesPx)); } catch (err) {}
        };
        notesHandle.addEventListener('pointermove', move);
        notesHandle.addEventListener('pointerup', up);
        notesHandle.addEventListener('pointercancel', up);
      });

      // Edit → write the current slide's note + debounced persist.
      notesBody.addEventListener('input', () => {
        if (!Array.isArray(this._notes)) this._notes = [];
        this._notes[this._index] = notesBody.value;
        this._scheduleNotesPersist();
      });
      // At window scope the keydown target is retargeted to the host
      // <deck-stage> (not this textarea), so _onKey's INPUT/TEXTAREA guard
      // never matches — stop propagation here so typing (space/arrows/…) edits
      // the note instead of navigating slides (same trick as the thumb keydown).
      notesBody.addEventListener('keydown', (e) => e.stopPropagation());

      this._root.append(style, this._mobStyle, rail, resize, stage, notes, menu);
      this._canvas = canvas;
      this._stage = stage;
      this._slot = slot;
      this._rail = rail;
      this._resize = resize;
      this._menu = menu;
      this._notesPanel = notes;
      this._notesHandle = notesHandle;
      this._notesBody = notesBody;

      // Restore persisted rail width.
      let rw = 192;
      try {
        const s = localStorage.getItem('deck-stage.railWidth');
        if (s) rw = parseInt(s, 10) || rw;
      } catch (err) {}
      this._setRailWidth(rw);
      this._syncRailHidden();

      // Restore persisted notes-dock height.
      let nh = 160;
      try {
        const s = localStorage.getItem('deck-stage.notesHeight');
        if (s) nh = parseInt(s, 10) || nh;
      } catch (err) {}
      this._setNotesHeight(nh);
      this._syncNotesHidden();
    }

    _setRailWidth(px) {
      const w = Math.max(120, Math.min(360, Math.round(px)));
      this._railPx = w;
      this.style.setProperty('--deck-rail-w', w + 'px');
      this._fit();
      // _scaleThumbs forces a sync layout (frame.offsetWidth) then writes
      // N transforms. During a resize drag this runs per-pointermove;
      // coalesce to one per frame.
      if (!this._scaleRaf) {
        this._scaleRaf = requestAnimationFrame(() => {
          this._scaleRaf = null;
          this._scaleThumbs();
        });
      }
    }

    // ── Speaker-notes dock ────────────────────────────────────────────────

    _setNotesHeight(px) {
      const max = Math.max(120, Math.round(window.innerHeight * 0.5));
      const h = Math.max(58, Math.min(max, Math.round(px)));
      this._notesPx = h;
      this.style.setProperty('--deck-notes-h', h + 'px');
      this._fit();
    }

    _notesVisible() {
      if (NOTES_DISABLED) return false;
      return !!this._hasNotesTag && !!this._railEnabled
        && !this._presenting && !this._previewMode
        && !this.hasAttribute('noscale') && !this.hasAttribute('no-rail')
        && !NARROW_MQ.matches;
    }

    /** Height _fit subtracts from the stage region. Clamped so a tall dock on
     *  a short window still leaves ~160px of canvas (no negative/NaN scale). */
    _notesHeight() {
      if (!this._notesVisible()) return 0;
      return Math.min(this._notesPx || 0, Math.max(0, window.innerHeight - 160));
    }

    _syncNotesHidden() {
      if (!this._notesPanel) return;
      // Static conditions (no-rail/noscale/narrow/print) live in CSS; toggle
      // only the runtime-dynamic hide (presenting / preview / rail disabled).
      const hide = NOTES_DISABLED || !this._hasNotesTag || !this._railEnabled || this._presenting || this._previewMode;
      this._notesPanel.toggleAttribute('data-hidden', hide);
      this._notesPanel.inert = !this._notesVisible(); // keep textarea out of tab order when hidden
    }

    /** Load the current slide's note into the body (no-op if unchanged so it
     *  doesn't disturb an in-progress edit). */
    _syncNotesBody() {
      if (!this._notesBody) return;
      const val = (Array.isArray(this._notes) && this._notes[this._index]) || '';
      if (this._notesBody.value !== val) this._notesBody.value = val;
    }

    /** this._notes with holes → '' and length preserved (safe to JSON). */
    _notesForEmit() {
      const src = Array.isArray(this._notes) ? this._notes : [];
      return Array.from(src, (v) => (typeof v === 'string' ? v : (v == null ? '' : String(v))));
    }

    _scheduleNotesPersist() {
      clearTimeout(this._notesPersistTimer);
      this._notesPersistTimer = setTimeout(() => this._emitNotesChange(), 300);
    }

    /** Persist a pure text edit: mirror the in-DOM #speaker-notes tag (if any)
     *  for in-iframe consumers, and post the full array to the parent so the
     *  host writes it to disk — the tag lives OUTSIDE <deck-stage>, so the
     *  deck-changed outerHTML path can't carry notes. */
    _emitNotesChange() {
      const notes = this._notesForEmit();
      this._notes = notes;
      const tag = document.getElementById('speaker-notes');
      if (tag) tag.textContent = JSON.stringify(notes);
      this.dispatchEvent(new CustomEvent('noteschange', {
        detail: { notes, index: this._index }, bubbles: true, composed: true,
      }));
      try { window.parent.postMessage({ type: 'miaoda:deck:notes-changed', index: this._index, notes }, '*'); } catch (e) {}
    }

    /** @page must live in the document stylesheet — it's a no-op inside
     *  shadow DOM. Inject/update a single <head> style tag so the print
     *  sheet matches the design size and Save-as-PDF yields one slide per
     *  page with no margins. */
    _syncPrintPageRule() {
      const id = 'deck-stage-print-page';
      let tag = document.getElementById(id);
      if (!tag) {
        tag = document.createElement('style');
        tag.id = id;
        document.head.appendChild(tag);
      }
      tag.textContent =
        '@page { size: ' + this.designWidth + 'px ' + this.designHeight + 'px; margin: 0; } ' +
        '@media print { html, body { margin: 0 !important; padding: 0 !important; background: none !important; overflow: visible !important; height: auto !important; } ' +
        '* { -webkit-print-color-adjust: exact; print-color-adjust: exact; } ' +
        // Jump authored animations/transitions to their end state so print
        // never captures mid-entrance — pairs with the beforeprint handler
        // in connectedCallback that sets data-deck-active on every slide.
        '*, *::before, *::after { animation-delay: -99s !important; animation-duration: .001s !important; ' +
        'animation-iteration-count: 1 !important; animation-fill-mode: both !important; ' +
        'animation-play-state: running !important; transition-duration: 0s !important; } }';
    }

    _onSlotChange() {
      // Rail mutations (delete/move) already reconcile synchronously and
      // emit slidechange with reason 'api'; skip the async slotchange that
      // would otherwise re-broadcast with reason 'init'.
      if (this._squelchSlotChange) { this._squelchSlotChange = false; return; }
      this._collectSlides();
      this._restoreIndex();
      this._applyIndex({ broadcast: true, reason: 'init' });
      this._fit();
    }

    _collectSlides() {
      const assigned = this._slot.assignedElements({ flatten: true });
      this._slides = assigned.filter((el) => {
        // Skip template/style/script nodes even if someone slots them.
        const tag = el.tagName;
        return tag !== 'TEMPLATE' && tag !== 'SCRIPT' && tag !== 'STYLE';
      });
      this._slideSet = new Set(this._slides);

      this._slides.forEach((slide, i) => {
        const n = i + 1;
        slide.setAttribute('data-screen-label', `${pad2(n)} ${getSlideLabel(slide)}`);

        // Validation attribute for comment flow / auto-checks.
        if (!slide.hasAttribute('data-miaoda-validate')) {
          slide.setAttribute('data-miaoda-validate', VALIDATE_ATTR);
        }

        slide.setAttribute('data-deck-slide', String(i));
      });

      if (this._index >= this._slides.length) this._index = Math.max(0, this._slides.length - 1);
      this._markLastVisible();
      this._renderRail();
    }

    /** Tag the last non-skipped slide so print CSS can drop its
     *  break-after (see the @media print comment above — :last-child
     *  alone matches a hidden skipped slide). */
    _markLastVisible() {
      let last = null;
      this._slides.forEach((s) => {
        s.removeAttribute('data-deck-last-visible');
        if (!s.hasAttribute('data-deck-skip')) last = s;
      });
      if (last) last.setAttribute('data-deck-last-visible', '');
    }

    _loadNotes() {
      const tag = document.getElementById('speaker-notes');
      this._hasNotesTag = !!tag;
      if (!tag) { this._notes = []; return; }
      try {
        const parsed = JSON.parse(tag.textContent || '[]');
        if (Array.isArray(parsed)) this._notes = parsed;
      } catch (e) {
        console.warn('[deck-stage] Failed to parse #speaker-notes JSON:', e);
        this._notes = [];
      }
    }

    /** Parse a `#<int>` fragment (1-indexed) into a 0-based slide index, or
     *  -1 when the hash is absent/malformed or points outside the deck.
     *  Shared by _restoreIndex (load time) and _onHashChange (runtime). */
    _slideFromHash() {
      const h = (location.hash || '').match(/^#(\d+)$/);
      if (!h) return -1;
      const n = parseInt(h[1], 10) - 1;
      return n >= 0 && n < this._slides.length ? n : -1;
    }

    _restoreIndex() {
      // The host's ?slide= param is delivered as a #<int> hash (1-indexed) on
      // the iframe src. No hash → slide 1; the deck itself keeps no position
      // state across loads.
      const n = this._slideFromHash();
      if (n >= 0) this._index = n;
    }

    _onHashChange() {
      // Runtime counterpart to _restoreIndex, which only reads the fragment
      // once (at connectedCallback). A same-document fragment change — a deep
      // link edited in the address bar, or an automation/screenshot tool that
      // navigates to #N without a full reload — fires hashchange but never
      // re-runs connectedCallback, so honor it here too. The deck's own
      // navigation writes the fragment via history.replaceState, which does
      // NOT fire hashchange, so this can't feed back into a loop; the index
      // guard also makes a redundant fragment a no-op.
      const n = this._slideFromHash();
      if (n >= 0 && n !== this._index) this._go(n, 'api');
    }

    _applyIndex({ broadcast = true, reason = 'init' } = {}) {
      if (!this._slides.length) return;
      const prev = this._prevIndex == null ? -1 : this._prevIndex;
      const curr = this._index;
      // Keep the iframe's own hash in sync so an in-iframe location.reload()
      // (reload banner path in viewer-handle.ts) lands on the current slide,
      // not the stale deep-link hash from initial load.
      try { history.replaceState(null, '', '#' + (curr + 1)); } catch (e) {}
      this._slides.forEach((s, i) => {
        if (i === curr) s.setAttribute('data-deck-active', '');
        else s.removeAttribute('data-deck-active');
      });
      // Follow-scroll on every navigation (init deep-link, keyboard, click,
      // tap, external goTo) — the only time we *don't* want the rail to
      // track current is after a rail-internal mutation, where _renderRail
      // has already restored the user's scroll position and yanking back to
      // current would undo it.
      this._syncRail(reason !== 'mutation');
      this._syncNotesBody();

      if (broadcast) {
        // (1) Parent-window postMessage for speaker-notes renderers.
        try { window.parent.postMessage({ type: 'miaoda:deck:slide-changed', index: curr, total: this._slides.length, skipped: this._skippedIndices() }, '*'); } catch (e) {}

        // (2) In-page CustomEvent on the <deck-stage> element itself.
        //     Bubbles and composes out of shadow DOM so slide code can listen:
        //       document.querySelector('deck-stage').addEventListener('slidechange', e => {
        //         e.detail.index, e.detail.previousIndex, e.detail.total, e.detail.slide, e.detail.reason
        //       });
        const detail = {
          index: curr,
          previousIndex: prev,
          total: this._slides.length,
          slide: this._slides[curr] || null,
          previousSlide: prev >= 0 ? (this._slides[prev] || null) : null,
          reason: reason, // 'init' | 'keyboard' | 'click' | 'tap' | 'api'
        };
        this.dispatchEvent(new CustomEvent('slidechange', {
          detail,
          bubbles: true,
          composed: true,
        }));
      }

      if (this.hasAttribute('data-mob-ui')) this._syncMobStrip();

      this._prevIndex = curr;
    }

    // 移动端两种呈现互斥：竖排浏览（list）/ 旋转横屏播放（present）。
    // noscale / _snthumb（导出与演讲者缩略图捕获）必须保持桌面几何。
    _syncMobileMode() {
      const eligible = this._mobile && !this.hasAttribute('noscale') && !this._snthumb;
      this.toggleAttribute('data-mobile-list', eligible && !this._presenting);
      this.toggleAttribute('data-mobile-present', eligible && !!this._presenting);
    }

    _fitMobileList() {
      const dw = this.designWidth, dh = this.designHeight;
      const vw = window.innerWidth;
      this._mobLastVw = vw; // _onResize 高度变化跳过的基线
      const stage = this._canvas.parentElement;
      // 清掉桌面 _fit 写过的 inset 内联值
      if (stage) { stage.style.left = '0'; stage.style.right = '0'; stage.style.top = '0'; stage.style.bottom = '0'; }
      this.removeAttribute('data-windowed');
      const cardW = vw - 2 * MOB_MARGIN;
      const s = cardW / dw;
      const cardH = dh * s;
      const kids = Array.prototype.slice.call(this.children);
      const rules = [];
      const cards = [];
      let y = MOB_MARGIN;
      this._slides.forEach((slide, i) => {
        if (slide.hasAttribute('data-deck-skip')) return;
        const nth = kids.indexOf(slide) + 1;
        if (nth <= 0) return;
        rules.push(
          ':host([data-mobile-list]) ::slotted(:nth-child(' + nth + ')) {' +
          ' inset: auto !important; top: 0 !important; left: 0 !important;' +
          ' width: ' + dw + 'px !important; height: ' + dh + 'px !important;' +
          ' transform: translate(' + MOB_MARGIN + 'px, ' + y + 'px) scale(' + s + ') !important;' +
          // 圆角/描边随 scale 反向放大，落地后视觉为 8px / 0.5px
          ' border-radius: ' + (MOB_RADIUS / s) + 'px; overflow: hidden !important;' +
          ' border: ' + (0.5 / s) + 'px solid #DEE0E3; }'
        );
        cards.push({ slide, i, y, h: cardH });
        y += cardH + MOB_GAP;
      });
      // 竖排规则只作用于屏幕媒体——print 的 ::slotted 分页规则特异性更低，
      // 否则每页会带着列表位移/缩放进入打印流。
      this._mobStyle.textContent = '@media screen {\n' + rules.join('\n') + '\n}';
      this._canvas.style.transform = 'none';
      this._canvas.style.width = vw + 'px';
      this._canvas.style.height = Math.max(y - MOB_GAP + MOB_MARGIN, 0) + 'px';
      this._mobCards = cards;
      this._mobScale = s;

      // 徽标：每卡片左下角内 6px；宽度按位数 16/16/20。布局是确定性的，
      // 直接按 _mobCards 几何摆放，无需 IntersectionObserver。
      this._mobBadges.textContent = '';
      cards.forEach((c, ordinal) => {
        const b = document.createElement('div');
        b.className = 'mob-badge';
        const n = ordinal + 1;
        b.textContent = String(n);
        b.style.width = (String(n).length >= 3 ? 20 : 16) + 'px';
        b.style.left = (MOB_MARGIN + 6) + 'px';
        b.style.top = (c.y + c.h - 6 - 12) + 'px';
        this._mobBadges.appendChild(b);
      });

      this._mobScrollTo(this._index, false);
    }

    _onMobScroll() {
      if (!this.hasAttribute('data-mobile-list') || !this._mobCards || !this._mobCards.length) return;

      // 徽标显隐：程序化滚动也算"滚动"，两种来源都给可见性反馈。
      this.setAttribute('data-mob-scrolling', '');
      clearTimeout(this._mobScrollIdleTimer);
      this._mobScrollIdleTimer = setTimeout(
        () => this.removeAttribute('data-mob-scrolling'), MOB_BADGE_IDLE_MS);

      if (this._mobScrollRaf) return;
      this._mobScrollRaf = requestAnimationFrame(() => {
        this._mobScrollRaf = null;
        const stage = this._canvas.parentElement;
        const top = stage.scrollTop;
        const moved = this._mobLastTop == null ? Infinity : Math.abs(top - this._mobLastTop);
        this._mobLastTop = top; // 抑制期间也持续跟踪位置
        if (this._mobProgUntil && performance.now() < this._mobProgUntil) {
          // 程序化滚动事件流仍在到达：续期窗口，动画多长都盖得住；
          // 事件停止 120ms 后窗口自然过期，之后才恢复用户滚动反推。
          this._mobProgUntil = Math.max(this._mobProgUntil, performance.now() + 120);
          return;
        }
        if (moved < 1) return; // 无真实位移（合成事件/终点回调）不反推
        // 纯视口中心公式在卡片高 < 半视口时到不了首/末页（卡片高 ~= 0.5625 * 宽,
        // 竖屏视口高通常远大于宽的一半），两端改用 clamp，中段维持视口中心语义。
        const max = stage.scrollHeight - stage.clientHeight;
        let cur;
        if (max <= 0 || stage.scrollTop <= 1) {
          cur = this._mobCards[0];
        } else if (stage.scrollTop >= max - 1) {
          cur = this._mobCards[this._mobCards.length - 1];
        } else {
          const center = stage.scrollTop + stage.clientHeight / 2;
          cur = this._mobCards[0];
          for (const c of this._mobCards) {
            if (center >= c.y) cur = c; else break;
          }
        }
        if (cur.i !== this._index) {
          this._index = cur.i;
          // 广播走现有内核：hash 同步 + slide-changed + slidechange 事件。
          // data-deck-active 的切换在竖排 CSS 下无视觉副作用。
          this._applyIndex({ broadcast: true, reason: 'api' });
        }
      });
    }

    _mobScrollTo(i, smooth) {
      const card = (this._mobCards || []).find((c) => c.i === i);
      if (!card) return;
      const stage = this._canvas.parentElement;
      const top = Math.max(0, card.y - Math.max(0, (stage.clientHeight - card.h) / 2));
      // 程序化滚动期间抑制 _onMobScroll 的反推——goto/deep-link 已直接设定
      // _index，多张边缘卡片的居中目标会被 clamp 到同一个 scrollTop，
      // 反推无法区分它们对应哪一页，故导航直接落 index、反推只处理真实
      // 用户位移。
      this._mobProgUntil = performance.now() + (smooth ? 800 : 200);
      // 目标位置立为基线：即便这次 scrollTo 因目标已等于当前位置（如居中
      // 目标 clamp 到 0）而不产生真实 scroll 事件，_mobLastTop 也不会停留
      // 在 null——避免之后任意一次无位移事件被当成"首次滚动"误判有位移。
      this._mobLastTop = top;
      stage.scrollTo({ top, behavior: smooth ? 'smooth' : 'auto' });
    }

    _fitMobilePresent() {
      const stage = this._canvas.parentElement;
      if (stage) { stage.style.left = ''; stage.style.right = ''; stage.style.top = ''; stage.style.bottom = ''; }
      this.removeAttribute('data-windowed');
      this._canvas.style.width = this.designWidth + 'px';
      this._canvas.style.height = this.designHeight + 'px';
      // 物理竖屏：CSS 旋转 90°，stage 逻辑尺寸 = (innerHeight × innerWidth)；
      // 物理横屏（用户顺势转了手机）：不旋转，按真实视口常规适配。
      // CSS 侧由 @media (orientation) 同步分支。
      const portrait = window.innerHeight >= window.innerWidth;
      const lw = portrait ? window.innerHeight : window.innerWidth;
      const lh = portrait ? window.innerWidth : window.innerHeight;
      const s = Math.min(lw / this.designWidth, lh / this.designHeight);
      this._canvas.style.transform = 'scale(' + s + ')';
    }

    _railWidth() {
      // State-based, no offsetWidth: the first _fit() can run before the
      // rail has had layout on some load paths, and a 0 there paints the
      // slide full-width for one frame before the post-slotchange _fit()
      // corrects it.
      if (!this._railEnabled || !this._railVisible || this.hasAttribute('no-rail')
          || this.hasAttribute('noscale') || this._presenting || this._previewMode
          || NARROW_MQ.matches) return 0;
      return this._railPx || 0;
    }

    _fit() {
      if (!this._canvas) return;
      if (this.hasAttribute('data-mobile-list')) return this._fitMobileList();
      if (this.hasAttribute('data-mobile-present')) return this._fitMobilePresent();
      const stage = this._canvas.parentElement;
      // PPTX export sets noscale so the DOM capture sees authored-size
      // geometry — the scaled canvas is in shadow DOM, so the exporter's
      // resetTransformSelector can't reach .canvas.style.transform directly.
      if (this.hasAttribute('noscale')) {
        this._canvas.style.transform = 'none';
        this.removeAttribute('data-windowed');
        if (stage) { stage.style.left = '0'; stage.style.right = '0'; stage.style.top = '0'; stage.style.bottom = '0'; }
        return;
      }
      this._canvas.style.width = this.designWidth + 'px';
      this._canvas.style.height = this.designHeight + 'px';
      const rw = this._railWidth();
      const nh = this._notesHeight();
      // Windowed (20px margin + card shadow) in edit/preview; full-bleed while
      // presenting or inside presenter-thumbnail iframes (_snthumb).
      const windowed = !this._presenting && !this._snthumb;
      const m = windowed ? DECK_MARGIN : 0;
      this.toggleAttribute('data-windowed', windowed);
      // Explicit four-side inset shrinks the flex box to the safe region; the
      // design-size canvas centres in it, then scale() shrinks it around the
      // centre — so it stays inside the inset with equal margins on all sides.
      if (stage) {
        stage.style.left = (rw + m) + 'px';
        stage.style.right = m + 'px';
        stage.style.top = m + 'px';
        stage.style.bottom = (m + nh) + 'px';
      }
      // The notes dock spans the non-rail width; its left edge tracks the rail.
      if (this._notesPanel) this._notesPanel.style.left = (rw + DECK_MARGIN) + 'px';
      const vw = window.innerWidth - rw - 2 * m;
      const vh = window.innerHeight - nh - 2 * m;
      const s = Math.min(vw / this.designWidth, vh / this.designHeight);
      this._canvas.style.transform = `scale(${s})`;
    }

    _onResize() {
      // 竖排列表几何只依赖视口宽度。移动浏览器地址栏收起/展开只改高度，
      // 若照常全量 refit（重建规则/徽标 + 无条件回中当前页），用户滚动中
      // 会被可见地"拽"一下——纯高度变化直接跳过。宽度变化（旋转/分屏）
      // 照常走完整 refit。
      if (this.hasAttribute('data-mobile-list')) {
        if (this._mobLastVw === window.innerWidth) return;
        this._mobLastVw = window.innerWidth;
      }
      this._fit();
      // Crossing the narrow-viewport breakpoint reveals the rail — rerun the
      // thumbnail scale the same way _setRailWidth does.
      if (!this._scaleRaf) {
        this._scaleRaf = requestAnimationFrame(() => {
          this._scaleRaf = null;
          this._scaleThumbs();
        });
      }
    }

    _onMessage(e) {
      const d = e.data;
      if (d && d.type === 'miaoda:deck:presenting' && typeof d.on === 'boolean') {
        this._presenting = d.on;
        this._syncMobileMode();
        if (!d.on) this._toggleMobUi(false);
        this._syncRailHidden();
        this._syncNotesHidden();
        this._closeMenu();
        this._fit();
        this._scaleThumbs();
      }
      // Host's Preview segment (ViewerMode='none'): the rail's drag-reorder /
      // right-click skip-delete affordances are editing chrome, so hide it
      // while the user is just looking at the deck. Same hard-hide path as
      // presenting; independent of the user's _railVisible preference so
      // returning to Edit restores whatever they had.
      if (d && d.type === 'miaoda:deck:preview-mode' && typeof d.on === 'boolean') {
        if (d.on === this._previewMode) return;
        this._previewMode = d.on;
        this._syncRailHidden();
        this._syncNotesHidden();
        this._closeMenu();
        this._fit();
        this._scaleThumbs();
      }
      // Per-viewer show/hide, driven by the TweaksPanel's auto-injected
      // "Thumbnail rail" toggle (or any author script). Independent of
      // whether the Tweaks panel itself is open — closing the panel
      // doesn't change rail visibility. Persists alongside rail width.
      if (d && d.type === 'miaoda:deck:rail-visible' && typeof d.on === 'boolean') {
        if (d.on === this._railVisible) return;
        this._railVisible = d.on;
        try { localStorage.setItem('deck-stage.railVisible', d.on ? '1' : '0'); } catch (e) {}
        // Notify the parent so its toolbar state stays in sync.
        try { window.parent.postMessage({ type: 'miaoda:deck:rail-visible-changed', on: d.on }, '*'); } catch (e) {}
        // Arm the transition, commit it, then flip state — otherwise the
        // browser coalesces both writes and nothing animates on show.
        this.setAttribute('data-rail-anim', '');
        void (this._rail && this._rail.offsetHeight);
        this._syncRailHidden();
        this._fit();
        this._scaleThumbs();
        clearTimeout(this._railAnimTimer);
        this._railAnimTimer = setTimeout(() => this.removeAttribute('data-rail-anim'), 220);
      }
      if (d && d.type === 'miaoda:deck:rail-enabled') this._enableRail();
      if (d && d.type === 'miaoda:deck:goto' && typeof d.index === 'number') this._go(d.index | 0, 'api');
    }

    _syncRailHidden() {
      if (!this._rail) return;
      // data-presenting is the hard hide (display:none) for flag-off,
      // presentation mode, and the host's Preview segment — instant, no
      // transition. data-user-hidden is the soft hide (translateX(-100%))
      // for the viewer's rail toggle, so show/hide slides under
      // :host([data-rail-anim]).
      const hard = !this._railEnabled || this._presenting || this._previewMode;
      if (hard) this._rail.setAttribute('data-presenting', '');
      else this._rail.removeAttribute('data-presenting');
      if (!this._railVisible) this._rail.setAttribute('data-user-hidden', '');
      else this._rail.removeAttribute('data-user-hidden');
      // translateX hide leaves thumbs (tabIndex=0) in the tab order —
      // inert keeps them unfocusable while the rail is off-screen.
      this._rail.inert = hard || !this._railVisible;
    }

    _onTap(e) {
      // Touch-only for normal browse/edit — on desktop there, keyboard + the
      // overlay toolbar cover nav. But in presenting mode the overlay is hidden
      // and click-to-advance is the expected gesture (Keynote/PPT), so allow it
      // on fine pointers too.
      if (FINE_POINTER_MQ.matches && !this._presenting) return;
      // Only taps that land on the stage (slide content or letterbox); the
      // overlay / rail / menus are siblings with their own click handlers.
      const path = e.composedPath();
      if (!this._stage || !path.includes(this._stage)) return;
      // Let interactive slide content keep the tap. composedPath (not
      // e.target.closest) so we see through open shadow roots — a <button>
      // inside a slide-authored custom element retargets e.target to the
      // host but still appears in the composed path.
      if (e.defaultPrevented) return;
      for (const n of path) {
        if (n === this._stage) break;
        if (n.matches && n.matches(INTERACTIVE_SEL)) return;
      }
      // 竖排浏览是滚动列表，tap 不翻页（spec 决策 #5）
      if (this.hasAttribute('data-mobile-list')) return;
      e.preventDefault();
      if (this.hasAttribute('data-mobile-present')) {
        const zone = this._mobPresentZone(e);
        if (zone === 'menu') this._toggleMobUi();
        else {
          this._advance(zone === 'prev' ? -1 : 1, 'tap');
          if (this.hasAttribute('data-mob-ui')) this._toggleMobUi(true);
        }
        return;
      }
      const rw = this._railWidth();
      const mid = rw + (window.innerWidth - rw) / 2;
      this._advance(e.clientX < mid ? -1 : 1, 'tap');
    }

    // rotate(90deg) 后视觉横屏的 x 轴对应视口 y 轴。方向以真机/仿真实测为准：
    // 若实测发现 prev/next 颠倒，翻转此处的比较符（保持单点修改）。
    _mobPresentZone(e) {
      const rect = this._stage.getBoundingClientRect();
      // 物理竖屏 = stage 被 CSS 旋转 90°，视觉横屏 x 轴对应视口 y 轴；
      // 物理横屏 = 无旋转，直接用视口 x 轴。与 _fitMobilePresent 同分支。
      const portrait = window.innerHeight >= window.innerWidth;
      const x = portrait
        ? (e.clientY - rect.top) / Math.max(1, rect.height)
        : (e.clientX - rect.left) / Math.max(1, rect.width);
      return x < 1 / 3 ? 'prev' : x > 2 / 3 ? 'next' : 'menu';
    }

    _toggleMobUi(force) {
      const wasOpen = this.hasAttribute('data-mob-ui');
      const on = force != null ? !!force : !wasOpen;
      this.toggleAttribute('data-mob-ui', on);
      clearTimeout(this._mobUiTimer);
      if (!on) return;
      // 从隐藏态唤出才全量重建（吸收直编/重排/skip 变化——strip 是静态
      // 快照、不接 _liveObserver 刷新管线）；已展开时的调用（缩略图点击/
      // 翻页重置计时）只同步高亮，避免高频路径 O(页数) 重建。
      if (!wasOpen || !this._mobUi) {
        if (this._mobUi) { this._mobUi.remove(); this._mobUi = null; }
        this._buildMobUi();
      }
      this._syncMobStrip();
      this._mobUiTimer = setTimeout(() => this._toggleMobUi(false), MOB_UI_HIDE_MS);
    }

    _buildMobUi() {
      // 移动 viewer 语境 host 可能从不发 rail-enabled，author-CSS 快照
      // （_enableRail 才建）不存在时缩略图克隆会裸渲染——此处兜底建一次。
      // _snapshotAuthorCss 可重入且带 generation guard。
      if (!this._adoptedSheet && this._authorCss == null) this._snapshotAuthorCss();
      const ui = document.createElement('div');
      ui.className = 'mob-ui export-hidden';
      ui.setAttribute('data-miaoda-chrome', '');
      const back = document.createElement('button');
      back.className = 'mob-back';
      back.type = 'button';
      back.textContent = '‹ 演示模式';
      back.addEventListener('click', (e) => {
        e.stopPropagation();
        this._presenting = false;
        this._syncMobileMode();
        this._syncRailHidden();
        this._syncNotesHidden();
        this._fit();
        this._toggleMobUi(false);
        try { window.parent.postMessage({ type: 'miaoda:deck:presenting-dismissed' }, '*'); } catch (err) {}
      });
      const strip = document.createElement('div');
      strip.className = 'mob-strip';
      this._mobStripEntries = this._slides
        .map((slide, i) => ({ slide, i }))
        .filter((e2) => !e2.slide.hasAttribute('data-deck-skip'))
        .map((e2, ordinal) => {
          const t = document.createElement('div');
          t.className = 'mthumb';
          const frame = document.createElement('div');
          frame.className = 'mframe';
          const num = document.createElement('div');
          num.className = 'mnum';
          num.textContent = String(ordinal + 1);
          t.append(frame, num);
          t.addEventListener('click', (ev) => {
            ev.stopPropagation();
            this._go(e2.i, 'click');
            this._toggleMobUi(true); // 重置自动收起计时，保持控件层可见
          });
          strip.appendChild(t);
          // 复用 _materialize 的克隆管线（media 熄火、canvas 快照、custom
          // element 中性化）：它会自建 host/shadow 并直接挂进 entry.frame，
          // 所以这里不需要再手工搭 host——只需在其后把统一走 _thumbScale
          // （rail 宽度）算出的缩放，改写成本条带 132px 专属的缩放。
          const entry = { slide: e2.slide, frame, host: null, clone: null };
          this._materialize(entry);
          if (entry.clone) entry.clone.style.transform = 'scale(' + (132 / this.designWidth) + ')';
          return { el: t, i: e2.i };
        });
      // 控件层内任何点击不冒泡成翻页 tap
      ui.addEventListener('click', (e) => e.stopPropagation());
      ui.append(back, strip);
      this._stage.appendChild(ui);
      this._mobUi = ui;
    }

    _syncMobStrip() {
      (this._mobStripEntries || []).forEach((en) => {
        en.el.toggleAttribute('data-current', en.i === this._index);
        if (en.i === this._index) en.el.scrollIntoView({ block: 'nearest', inline: 'center' });
      });
    }

    _onKey(e) {
      // Ignore when the user is typing.
      const t = e.target;
      if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
      if (e.key === 'Escape' && this._menu && this._menu.hasAttribute('data-open')) {
        this._closeMenu();
        e.preventDefault();
        return;
      }
      if (e.metaKey || e.ctrlKey || e.altKey) return;

      const key = e.key;
      let handled = true;

      if (key === 'ArrowRight' || key === 'ArrowDown' || key === 'PageDown' || key === ' ' || key === 'Spacebar') {
        this._advance(1, 'keyboard');
      } else if (key === 'ArrowLeft' || key === 'ArrowUp' || key === 'PageUp') {
        this._advance(-1, 'keyboard');
      } else if (key === 'Home') {
        this._go(0, 'keyboard');
      } else if (key === 'End') {
        this._go(this._slides.length - 1, 'keyboard');
      } else if (key === 'r' || key === 'R') {
        this._go(0, 'keyboard');
      } else if (/^[0-9]$/.test(key)) {
        // 1..9 jump to that slide; 0 jumps to 10.
        const n = key === '0' ? 9 : parseInt(key, 10) - 1;
        if (n < this._slides.length) this._go(n, 'keyboard');
      } else {
        handled = false;
      }

      if (handled) {
        e.preventDefault();
      }
    }

    _go(i, reason = 'api') {
      if (!this._slides.length) return;
      const clamped = Math.max(0, Math.min(this._slides.length - 1, i));
      // 竖排浏览：导航直接落 index（与桌面语义一致），滚动只是视觉跟随；
      // 不再依赖 _onMobScroll 从滚动位置反推——多张边缘卡片的居中滚动目标
      // 会被 clamp 到同一个 scrollTop，反推无法区分它们是哪一页。
      if (this.hasAttribute('data-mobile-list')) {
        const changed = clamped !== this._index;
        this._index = clamped;
        // 同页 goto 不重复广播（与桌面分支语义一致），但仍需重新居中滚动。
        if (changed) this._applyIndex({ broadcast: true, reason });
        this._mobScrollTo(clamped, true);
        return;
      }
      if (clamped === this._index) return;
      this._index = clamped;
      this._applyIndex({ broadcast: true, reason });
    }

    /** Step forward/back skipping any slide marked data-deck-skip. Clamps at
     *  the ends (no-op past the first/last non-skipped slide). */
    _advance(dir, reason) {
      if (!this._slides.length) return;
      let i = this._index + dir;
      while (i >= 0 && i < this._slides.length && this._slides[i].hasAttribute('data-deck-skip')) {
        i += dir;
      }
      if (i < 0 || i >= this._slides.length) return;
      this._go(i, reason);
    }

    // ── Thumbnail rail ────────────────────────────────────────────────────
    //
    // Thumbs are keyed by slide element and reused across _renderRail()
    // calls, so a reorder/delete is an O(changed) DOM shuffle instead of an
    // O(N) teardown-and-re-clone. Each thumb starts as a lightweight shell
    // (num + empty frame); the clone is materialized lazily by an
    // IntersectionObserver when the frame scrolls into (or near) view, so
    // only visible-ish slides pay the clone + image-decode cost.

    _renderRail() {
      if (!this._rail || !this._railEnabled) { this._thumbs = []; return; }
      // FLIP: record each *materialized* thumb's top before the reconcile.
      // Off-screen (non-materialized) thumbs don't need the animation and
      // skipping their getBoundingClientRect saves a forced layout per
      // off-screen thumb on large decks.
      const prevTops = new Map();
      (this._thumbs || []).forEach(({ thumb, slide, host }) => {
        if (host) prevTops.set(slide, thumb.getBoundingClientRect().top);
      });
      const st = this._rail.scrollTop;

      // Reconcile: reuse thumbs that already exist for a slide, create
      // shells for new slides, drop thumbs for removed slides.
      const bySlide = new Map();
      (this._thumbs || []).forEach((t) => bySlide.set(t.slide, t));
      const next = [];
      this._slides.forEach((slide) => {
        let t = bySlide.get(slide);
        if (t) bySlide.delete(slide);
        else t = this._makeThumb(slide);
        next.push(t);
      });
      // Orphans — slides removed since last render.
      bySlide.forEach((t) => {
        if (this._railObserver) this._railObserver.unobserve(t.frame);
        t.thumb.remove();
      });
      // Put thumbs into document order to match _slides. insertBefore on
      // an already-correctly-placed node is a no-op, so this is cheap
      // when nothing moved.
      next.forEach((t, i) => {
        const want = t.thumb;
        const at = this._rail.children[i];
        if (at !== want) this._rail.insertBefore(want, at || null);
        t.i = i;
        t.num.textContent = String(i + 1);
        if (t.slide.hasAttribute('data-deck-skip')) t.thumb.setAttribute('data-skip', '');
        else t.thumb.removeAttribute('data-skip');
      });
      this._thumbs = next;

      this._rail.scrollTop = st;
      if (prevTops.size) {
        const moved = [];
        this._thumbs.forEach(({ thumb, slide }) => {
          const old = prevTops.get(slide);
          if (old == null) return;
          const dy = old - thumb.getBoundingClientRect().top;
          if (Math.abs(dy) < 1) return;
          thumb.style.transition = 'none';
          thumb.style.transform = `translateY(${dy}px)`;
          moved.push(thumb);
        });
        if (moved.length) {
          // Commit the inverted positions before flipping the transition
          // on — otherwise the browser coalesces both style writes and
          // nothing animates.
          void this._rail.offsetHeight;
          moved.forEach((t) => {
            t.style.transition = 'transform 180ms cubic-bezier(.2,.7,.3,1)';
            t.style.transform = '';
          });
          setTimeout(() => moved.forEach((t) => { t.style.transition = ''; }), 220);
        }
      }
      requestAnimationFrame(() => this._scaleThumbs());
      this._syncRail(false);
    }

    /** Create a lightweight thumb shell for one slide. The clone is
     *  materialized later by the IntersectionObserver. Event handlers
     *  look up the thumb's *current* index (via _thumbs.indexOf) so the
     *  same element can be reused across reorders. */
    _makeThumb(slide) {
      const thumb = document.createElement('div');
      thumb.className = 'thumb';
      thumb.tabIndex = 0;
      const num = document.createElement('div');
      num.className = 'num';
      const frame = document.createElement('div');
      frame.className = 'frame';
      const skipIcon = document.createElement('div');
      skipIcon.className = 'skip-icon';
      skipIcon.innerHTML = '<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1.8447 1.82978C2.16723 1.50736 2.68943 1.51112 3.0119 1.8336L18.3385 17.1606C18.6638 17.4859 18.6637 18.0136 18.3384 18.3389C18.0131 18.6641 17.4855 18.6643 17.1602 18.339L1.83317 3.01234C1.51069 2.68986 1.50692 2.16767 1.82935 1.84514C1.83447 1.84002 1.83958 1.8349 1.8447 1.82978ZM3.33085 6.27753L6.68668 9.63337C6.63272 10.1199 6.68658 10.6123 6.84443 11.0757C7.00228 11.5391 7.26025 11.962 7.60001 12.3144C7.93976 12.6668 8.35296 12.94 8.81024 13.1147C9.26753 13.2894 9.75767 13.3612 10.2458 13.325L10.3667 13.3134L13.3529 16.2996C12.2833 16.8225 11.1604 17.0838 9.98626 17.0838C6.65746 17.0838 3.75395 14.9833 1.27539 10.7819C0.991215 10.3003 0.987158 9.70269 1.26629 9.21806C1.91897 8.08486 2.60738 7.10484 3.33085 6.27753ZM13.3333 10.0005C13.3334 9.54197 13.2389 9.08841 13.0556 8.66813C12.8724 8.24784 12.6045 7.86987 12.2686 7.55784C11.9327 7.24581 11.536 7.00644 11.1033 6.85468C10.6707 6.70293 10.2114 6.64205 9.75418 6.67587L9.63293 6.68712L6.6246 3.67878C7.67308 3.17422 8.82227 2.91381 9.98585 2.91712C13.3783 2.91712 16.2919 5.01573 18.7276 9.21295C19.0101 9.6999 19.0068 10.3018 18.7193 10.7858C18.0552 11.9035 17.3618 12.8724 16.6388 13.693L13.3133 10.3675C13.3267 10.2467 13.3333 10.1246 13.3333 10.0005Z" fill="#646A73"/></svg>';
      frame.append(skipIcon);
      thumb.append(num, frame);

      const entry = { thumb, num, frame, slide, clone: null, host: null, i: -1 };
      // entry.i is refreshed on every _renderRail reconcile pass, so
      // handlers read the thumb's current position without an O(N) scan.
      const idx = () => entry.i;

      thumb.addEventListener('click', () => this._go(idx(), 'click'));
      // ↑/↓ step through the rail when a thumb has focus. _go clamps at the
      // ends and _applyIndex→_syncRail scrolls the new current thumb into
      // view; we move focus to it (preventScroll — _syncRail already
      // scrolled) so a held key walks the whole list. stopPropagation keeps
      // this out of the window-level _onKey nav handler.
      thumb.addEventListener('keydown', (e) => {
        if (e.key !== 'ArrowUp' && e.key !== 'ArrowDown') return;
        if (e.metaKey || e.ctrlKey || e.altKey) return;
        e.preventDefault();
        e.stopPropagation();
        this._go(idx() + (e.key === 'ArrowDown' ? 1 : -1), 'keyboard');
        const cur = this._thumbs && this._thumbs[this._index];
        if (cur) cur.thumb.focus({ preventScroll: true });
      });
      thumb.addEventListener('contextmenu', (e) => {
        e.preventDefault();
        this._openMenu(idx(), e.clientX, e.clientY);
      });
      thumb.draggable = true;
      thumb.addEventListener('dragstart', (e) => {
        this._dragFrom = idx();
        thumb.setAttribute('data-dragging', '');
        e.dataTransfer.effectAllowed = 'move';
        try { e.dataTransfer.setData('text/plain', String(this._dragFrom)); } catch (err) {}
        // Hand the browser a clean elevated card instead of its raw .thumb
        // bitmap; anchor it under the cursor at the grab point (no jump).
        try {
          const g = this._makeDragGhost(entry);
          if (g) {
            const r = frame.getBoundingClientRect();
            const gx = g.pad + Math.max(0, Math.min(g.w, e.clientX - r.left));
            const gy = g.pad + Math.max(0, Math.min(g.h, e.clientY - r.top));
            e.dataTransfer.setDragImage(g.el, gx, gy);
          }
        } catch (err) {}
      });
      thumb.addEventListener('dragend', () => {
        thumb.removeAttribute('data-dragging');
        this._clearDrop();
        this._dragFrom = null;
        if (this._dragGhost) { this._dragGhost.remove(); this._dragGhost = null; }
      });
      thumb.addEventListener('dragover', (e) => {
        if (this._dragFrom == null) return;
        e.preventDefault();
        e.dataTransfer.dropEffect = 'move';
        const r = thumb.getBoundingClientRect();
        this._setDrop(idx(), e.clientY < r.top + r.height / 2 ? 'before' : 'after');
      });
      thumb.addEventListener('drop', (e) => {
        if (this._dragFrom == null) return;
        e.preventDefault();
        const i = idx();
        const r = thumb.getBoundingClientRect();
        let to = e.clientY >= r.top + r.height / 2 ? i + 1 : i;
        if (this._dragFrom < to) to--;
        const from = this._dragFrom;
        this._clearDrop();
        this._dragFrom = null;
        if (to !== from) this._moveSlide(from, to);
      });

      if (this._railObserver) this._railObserver.observe(frame);
      frame.__deckThumb = entry;
      return entry;
    }

    /** Build the floating drag-image for a rail thumb.
     *  The browser's default drag-image is a raw bitmap of the whole .thumb:
     *  it includes the number gutter and clips the current-slide's dark ring
     *  (which sits 2px outside the frame via outline-offset) at the bitmap
     *  edge. Instead we hand setDragImage a purpose-built card — just the
     *  slide frame, rounded, with a soft drop-shadow, transparent around it.
     *  The card lives inside a transparent padded wrapper because the bitmap
     *  crops to the element's border-box, so the shadow needs room inside the
     *  box or it clips too. Returns { el, pad, w, h } for the anchor math, or
     *  null if the frame has no size yet. */
    _makeDragGhost(entry) {
      if (this._dragGhost) { this._dragGhost.remove(); this._dragGhost = null; }
      this._materialize(entry);
      const w = entry.frame.offsetWidth, h = entry.frame.offsetHeight;
      if (!w || !h) return null;
      const pad = 36; // ≥ the shadow's blur + offset so it stays in the bitmap
      const wrap = document.createElement('div');
      wrap.style.cssText =
        'position:fixed;top:0;left:-100000px;pointer-events:none;' +
        'background:transparent;box-sizing:content-box;padding:' + pad + 'px;';
      const card = document.createElement('div');
      // Drop-shadow only — no hairline ring (the 0 0 0 1px shadow reads as a
      // border, which we don't want on the floating card).
      card.style.cssText =
        'position:relative;width:' + w + 'px;height:' + h + 'px;background:#fff;' +
        'border-radius:6px;overflow:hidden;' +
        'box-shadow:0 6px 10px 0 rgba(31, 35, 41, 0.20);cursor:grabbing;';
      const host = document.createElement('div');
      host.style.cssText = 'position:absolute;inset:0;';
      this._syncThumbHostAttrs(host);
      const sr = host.attachShadow({ mode: 'open' });
      if (this._adoptedSheet) sr.adoptedStyleSheets = [this._adoptedSheet];
      else {
        const st = document.createElement('style');
        st.textContent = this._authorCss || '';
        sr.appendChild(st);
      }
      if (entry.clone) sr.appendChild(entry.clone.cloneNode(true));
      card.appendChild(host);
      wrap.appendChild(card);
      (this.shadowRoot || document.body).appendChild(wrap);
      this._dragGhost = wrap;
      return { el: wrap, pad, w, h };
    }

    /** Lazily build the clone for a thumb that has scrolled into view. */
    _materialize(entry) {
      if (entry.host) return;
      const dw = this.designWidth, dh = this.designHeight;
      let clone = entry.slide.cloneNode(true);
      clone.removeAttribute('id');
      clone.removeAttribute('data-deck-active');
      clone.querySelectorAll('[id]').forEach((el) => el.removeAttribute('id'));
      // Neuter heavy media; replace <video> with its poster so the box
      // keeps a visual. <iframe>/<audio> become empty placeholders.
      clone.querySelectorAll('iframe, audio, object, embed').forEach((el) => {
        el.removeAttribute('src');
        el.removeAttribute('srcdoc');
        el.removeAttribute('data');
        el.innerHTML = '';
      });
      clone.querySelectorAll('video').forEach((el) => {
        if (!el.poster) { el.removeAttribute('src'); el.innerHTML = ''; return; }
        const img = document.createElement('img');
        img.src = el.poster;
        img.alt = '';
        img.style.cssText = el.style.cssText + ';object-fit:cover;width:100%;height:100%;';
        img.className = el.className;
        el.replaceWith(img);
      });
      // Canvas: cloneNode does not copy drawn pixels — snapshot each
      // original canvas into an <img> so ECharts / Chart.js / custom
      // drawings appear in the thumbnail instead of a blank rectangle.
      const origCanvases = entry.slide.querySelectorAll('canvas');
      const cloneCanvases = clone.querySelectorAll('canvas');
      cloneCanvases.forEach((el, ci) => {
        const orig = origCanvases[ci];
        if (!orig || !orig.width || !orig.height) return;
        try {
          const img = document.createElement('img');
          img.src = orig.toDataURL();
          img.alt = '';
          img.style.cssText = (el.getAttribute('style') || '') +
            ';width:' + orig.offsetWidth + 'px;height:' + orig.offsetHeight + 'px;';
          img.className = el.className;
          el.replaceWith(img);
        } catch (e) {}
      });
      // Images: defer decode and let the browser pick the smallest
      // srcset candidate for the ~140px thumb. Same-URL clones reuse the
      // slide's decoded bitmap (URL-keyed cache), so the remaining cost
      // is paint/composite — lazy+async keeps that off the main thread.
      clone.querySelectorAll('img').forEach((el) => {
        el.loading = 'lazy';
        el.decoding = 'async';
        if (el.srcset) el.sizes = (this._railPx || 192) + 'px';
      });
      // Custom elements inside the slide would have their
      // connectedCallback fire when the clone is appended. Replace them
      // with inert boxes so a component-heavy deck doesn't run N copies
      // of each component's mount logic in the rail. Children are
      // preserved so layout-wrapper elements (<my-column><h2>…</h2>)
      // still show their authored content; the querySelectorAll NodeList
      // is static, so nested custom elements in the moved subtree are
      // still visited on later iterations.
      const neuter = (el) => {
        const box = document.createElement('div');
        box.style.cssText = (el.getAttribute('style') || '') +
          ';background:rgba(0,0,0,0.06);border:1px dashed rgba(0,0,0,0.15);';
        box.className = el.className;
        // Preserve theming/i18n hooks so [data-*] / :lang() / [dir]
        // descendant selectors still match the neutered root.
        for (const a of el.attributes) {
          const n = a.name;
          if (n.startsWith('data-') || n.startsWith('aria-') ||
              n === 'lang' || n === 'dir' || n === 'role' || n === 'title') {
            box.setAttribute(n, a.value);
          }
        }
        while (el.firstChild) box.appendChild(el.firstChild);
        return box;
      };
      // querySelectorAll('*') returns descendants only — a custom-element
      // slide root (<my-slide>…</my-slide>) would slip through and upgrade
      // on append. Swap the root first.
      if (clone.tagName.includes('-')) clone = neuter(clone);
      clone.querySelectorAll('*').forEach((el) => {
        if (el.tagName.includes('-')) el.replaceWith(neuter(el));
      });
      clone.style.cssText += ';position:absolute;top:0;left:0;transform-origin:0 0;' +
        'pointer-events:none;width:' + dw + 'px;height:' + dh + 'px;' +
        'box-sizing:border-box;overflow:hidden;visibility:visible;opacity:1;';
      const host = document.createElement('div');
      host.style.cssText = 'position:absolute;inset:0;';
      this._syncThumbHostAttrs(host);
      const sr = host.attachShadow({ mode: 'open' });
      if (this._adoptedSheet) sr.adoptedStyleSheets = [this._adoptedSheet];
      else {
        const st = document.createElement('style');
        st.textContent = this._authorCss || '';
        sr.appendChild(st);
      }
      sr.appendChild(clone);
      entry.frame.appendChild(host);
      entry.host = host;
      entry.clone = clone;
      if (this._thumbScale) clone.style.transform = 'scale(' + this._thumbScale + ')';
      // Once materialized the IO callback is a no-op early-return —
      // unobserve so scroll doesn't keep firing it.
      if (this._railObserver) this._railObserver.unobserve(entry.frame);
    }

    /** Re-clone a single thumb (live-update path). No-op if the thumb
     *  hasn't been materialized yet — it'll pick up current content when
     *  it scrolls into view. */
    _refreshThumb(slide) {
      const entry = (this._thumbs || []).find((t) => t.slide === slide);
      if (!entry || !entry.host) return;
      entry.host.remove();
      entry.host = entry.clone = null;
      this._materialize(entry);
    }

    _scaleThumbs() {
      if (!this._thumbs || !this._thumbs.length) return;
      // Every frame is the same width; if it reads 0 the rail is
      // display:none (noscale / no-rail / presenting / print) — leave the
      // clones as-is and re-run when the rail is revealed.
      const fw = this._thumbs[0].frame.offsetWidth;
      if (!fw) return;
      this._thumbScale = fw / this.designWidth;
      this._thumbs.forEach(({ clone }) => {
        if (clone) clone.style.transform = 'scale(' + this._thumbScale + ')';
      });
    }

    /** Nearest reorder slot for a Y coordinate anywhere in the rail — used when
     *  the pointer is over a gap, where no thumb dragover fires. Returns
     *  { i, pos } matching _setDrop's contract, or null. Mirrors the thumb
     *  handler's midpoint test so the gap indicator lines up with the thumbs. */
    _railDropTarget(clientY) {
      const ts = this._thumbs;
      if (!ts || !ts.length) return null;
      for (let k = 0; k < ts.length; k++) {
        const r = ts[k].thumb.getBoundingClientRect();
        if (clientY < r.top + r.height / 2) return { i: ts[k].i, pos: 'before' };
        const next = ts[k + 1];
        if (!next) return { i: ts[k].i, pos: 'after' };
        const nr = next.thumb.getBoundingClientRect();
        if (clientY < nr.top + nr.height / 2) return { i: ts[k].i, pos: 'after' };
      }
      const last = ts[ts.length - 1];
      return { i: last.i, pos: 'after' };
    }

    _setDrop(i, where) {
      // dragover fires at pointer-event rate; touch only the previous
      // and new target rather than sweeping all N thumbs.
      const t = this._thumbs && this._thumbs[i];
      if (this._dropOn && this._dropOn !== t) {
        this._dropOn.thumb.removeAttribute('data-drop');
      }
      if (t) t.thumb.setAttribute('data-drop', where);
      this._dropOn = t || null;
      // Remembered so a drop that lands in a gap (rail handler) can commit to
      // the slot the indicator is showing without re-deriving before/after.
      this._dropWhere = t ? where : null;
    }

    _clearDrop() {
      if (this._dropOn) this._dropOn.thumb.removeAttribute('data-drop');
      this._dropOn = null;
      this._dropWhere = null;
    }

    _syncRail(follow) {
      if (!this._thumbs) return;
      this._thumbs.forEach(({ thumb }, i) => {
        if (i === this._index) {
          thumb.setAttribute('data-current', '');
          if (follow && typeof thumb.scrollIntoView === 'function') {
            thumb.scrollIntoView({ block: 'nearest' });
          }
        } else {
          thumb.removeAttribute('data-current');
        }
      });
    }

    _openMenu(i, x, y) {
      if (!this._menu) return;
      this._menuIndex = i;
      const slide = this._slides[i];
      const skip = slide && slide.hasAttribute('data-deck-skip');
      this._menu.querySelector('[data-act="skip"]').textContent = skip ? '取消隐藏' : '隐藏此页';
      this._menu.querySelector('[data-act="up"]').disabled = i <= 0;
      this._menu.querySelector('[data-act="down"]').disabled = i >= this._slides.length - 1;
      this._menu.querySelector('[data-act="delete"]').disabled = this._slides.length <= 1;
      // Place, then clamp to viewport after it's measurable.
      this._menu.style.left = x + 'px';
      this._menu.style.top = y + 'px';
      this._menu.setAttribute('data-open', '');
      const r = this._menu.getBoundingClientRect();
      const nx = Math.min(x, window.innerWidth - r.width - 4);
      const ny = Math.min(y, window.innerHeight - r.height - 4);
      this._menu.style.left = Math.max(4, nx) + 'px';
      this._menu.style.top = Math.max(4, ny) + 'px';
    }

    _closeMenu() {
      if (this._menu) this._menu.removeAttribute('data-open');
      this._menuIndex = -1;
    }

    _emitDeckChange(detail) {
      // A structural edit carries the (possibly reindexed) notes array so the
      // host writes deck-stage + speaker-notes in ONE file write. Cancel any
      // pending text-edit notes-changed so the two never race two writes at
      // the same file (etag conflict would drop the second).
      clearTimeout(this._notesPersistTimer);
      this.dispatchEvent(new CustomEvent('deckchange', {
        detail, bubbles: true, composed: true,
      }));
      // Forward to parent so the host can persist mutations (the CustomEvent
      // cannot cross iframe boundaries). detail.slide is an Element and can't
      // survive structured-clone, so only the scalars cross.
      try {
        window.parent.postMessage({
          type: 'miaoda:deck:deck-changed',
          action: detail.action, from: detail.from, to: detail.to,
          html: this.outerHTML,
          notes: this._notesForEmit(),
        }, '*');
      } catch (e) {}
    }

    _deleteSlide(i) {
      const slide = this._slides[i];
      if (!slide || this._slides.length <= 1) return;
      const wasCurrent = i === this._index;
      if (i < this._index || (wasCurrent && i === this._slides.length - 1)) this._index--;
      this._squelchSlotChange = true;
      slide.remove();
      // Keep the per-slide-indexed notes array aligned with the deck.
      if (Array.isArray(this._notes)) this._notes.splice(i, 1);
      this._emitDeckChange({ action: 'delete', from: i, slide });
      this._collectSlides();
      this._applyIndex({ broadcast: true, reason: 'mutation' });
    }

    _toggleSkip(i) {
      const slide = this._slides[i];
      if (!slide) return;
      const on = !slide.hasAttribute('data-deck-skip');
      if (on) slide.setAttribute('data-deck-skip', '');
      else slide.removeAttribute('data-deck-skip');
      if (this._thumbs && this._thumbs[i]) {
        if (on) this._thumbs[i].thumb.setAttribute('data-skip', '');
        else this._thumbs[i].thumb.removeAttribute('data-skip');
      }
      this._markLastVisible();
      this._emitDeckChange({ action: on ? 'skip' : 'unskip', from: i, slide });
      // Re-broadcast so the presenter popup's prev/next thumbnails re-pick
      // the nearest non-skipped slide without waiting for a nav event.
      try { window.parent.postMessage({ type: 'miaoda:deck:slide-changed', index: this._index, total: this._slides.length, skipped: this._skippedIndices() }, '*'); } catch (e) {}
    }

    _skippedIndices() {
      const out = [];
      for (let i = 0; i < this._slides.length; i++) {
        if (this._slides[i].hasAttribute('data-deck-skip')) out.push(i);
      }
      return out;
    }

    _moveSlide(i, j) {
      if (j < 0 || j >= this._slides.length || j === i) return;
      const slide = this._slides[i];
      const ref = j < i ? this._slides[j] : this._slides[j].nextSibling;
      // Track the active slide across the reorder so the same content
      // stays on screen.
      const cur = this._index;
      if (cur === i) this._index = j;
      else if (i < cur && j >= cur) this._index = cur - 1;
      else if (i > cur && j <= cur) this._index = cur + 1;
      this._squelchSlotChange = true;
      this.insertBefore(slide, ref);
      // Move the note entry in lockstep so notes stay aligned to slides.
      if (Array.isArray(this._notes)) {
        const [n] = this._notes.splice(i, 1);
        this._notes.splice(j, 0, n === undefined ? '' : n);
      }
      this._emitDeckChange({ action: 'move', from: i, to: j, slide });
      this._collectSlides();
      this._applyIndex({ broadcast: true, reason: 'mutation' });
    }

    // Public API ------------------------------------------------------------

    /** Current slide index (0-based). */
    get index() { return this._index; }
    /** Total slide count. */
    get length() { return this._slides.length; }
    /** Programmatically navigate. */
    goTo(i) { this._go(i, 'api'); }
    next() { this._advance(1, 'api'); }
    prev() { this._advance(-1, 'api'); }
    reset() { this._go(0, 'api'); }
  }

  if (!customElements.get('deck-stage')) {
    customElements.define('deck-stage', DeckStage);
  }
})();

/* BEGIN USAGE */
// DesignCanvas.jsx — Figma-ish design canvas wrapper
// Sections + Artboards + PostIt notes.
// Exports (to window): DesignCanvas, DCSection, DCArtboard, DCPostIt.
// Artboards are reorderable (grip-drag), deletable, labels/titles are
// inline-editable, and any artboard can be opened in a fullscreen focus
// overlay (←/→/Esc). State persists to a .design-canvas.state.json sidecar
// via the host bridge. No assets, no deps.
//
// Usage:
//   <DesignCanvas>
//     <DCSection id="onboarding" title="Onboarding" subtitle="First-run variants">
//       <DCArtboard id="a" label="A · Dusk" width={260} height={480}>…</DCArtboard>
//       <DCArtboard id="b" label="B · Minimal" width={260} height={480}>…</DCArtboard>
//     </DCSection>
//   </DesignCanvas>
//
// Artboards are static design frames, not scroll regions — never use
// height: 100% + overflow: auto/scroll on inner elements; size each artboard
// to fit its content. Height behavior:
//   • omit height  → the card grows to fit its content (no vertical clipping);
//                    this is the right default for full pages / long screens.
//   • height={N}   → a fixed N-px frame that CLIPS overflow (overflow:hidden) —
//                    use only for deliberately cropped thumbnails (e.g. A/B tiles).
// width is always a fixed frame width (default 260); content wider than it is
// clipped, so set width to the real design width for full pages.
//
// When placing a device frame inside a DCArtboard, pass chromeless to
// suppress the card chrome and let the artboard size to its content:
//   <DCArtboard chromeless><IOSDevice>…</IOSDevice></DCArtboard>
//
// On mobile (UA-detected) the canvas is browse-only: one-finger drag pans
// (starting on artboards too), two-finger pinch zooms, the zoom control is
// hidden, and drag-reorder / inline-rename are disabled. Tap on an artboard
// label still opens the focus overlay.
/* END USAGE */

const DC = {
  bg: '#FCFCFC',
  label: '#8F959E',
  title: '#1F2329',
  subtitle: '#646A73',
  postitBg: '#fef4a8',
  postitText: '#5a4a2a',
  font: '-apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif',
};

// ── 移动端判定：复刻主仓 @apaas-ai/global-states isMobile() 的 UA 语义
// （跨域产物 iframe 无法 import 该包，同 deck-stage 的先例）。刻意不用视口
// 断点——桌面工作台的预览 iframe 本身就窄，视口宽度会把桌面预览误判成移动端。
// 启动时一次性判定，不随 resize 抖动。
const DC_MOBILE_UA_RE = /(phone|pad|pod|iPhone|iPod|ios|iPad|Android|Mobile|BlackBerry|IEMobile|MQQBrowser|JUC|Fennec|wOSBrowser|BrowserNG|WebOS|Symbian|Windows Phone)/i;
const dcIsMobile = typeof navigator !== 'undefined' &&
  (DC_MOBILE_UA_RE.test(navigator.userAgent) ||
    (/iPad|Tab|Tablet/i.test(navigator.userAgent) && !!navigator.maxTouchPoints && navigator.maxTouchPoints > 1));

// One-time CSS injection (classes are dc-prefixed so they don't collide with
// the hosted design's own styles).
if (typeof document !== 'undefined' && !document.getElementById('dc-styles')) {
  const s = document.createElement('style');
  s.id = 'dc-styles';
  s.textContent = [
    '.dc-editable{cursor:text;outline:none;white-space:nowrap;border-radius:4px;padding:0 2px;margin:0 -2px}',
    '.dc-editable:focus{background:#fff;box-shadow:0 0 0 1px #336DF4}',
    '[data-dc-slot]{transition:transform .18s cubic-bezier(.2,.7,.3,1)}',
    '[data-dc-slot].dc-dragging{transition:none;z-index:10;pointer-events:none}',
    '[data-dc-slot].dc-dragging .dc-card{box-shadow:0 12px 40px rgba(0,0,0,.25),0 0 0 2px #336DF4;transform:scale(1.02)}',
    // isolation:isolate contains artboard content's z-indexes so a
    // z-indexed child (sticky navbar etc.) can't paint over .dc-header or
    // the .dc-menu popover that drops into the top of the card.
    '.dc-card{isolation:isolate;transition:box-shadow .15s,transform .15s}',
    '.dc-card *{scrollbar-width:none}',
    '.dc-card *::-webkit-scrollbar{display:none}',
    // Focus-overlay content isn't inside .dc-card, so the scrollbar-hiding
    // rules above don't reach it — re-hide scrollbars for the scaled,
    // scrollable content shown in DCFocusOverlay.
    '.dc-focus-content *{scrollbar-width:none}',
    '.dc-focus-content *::-webkit-scrollbar{display:none}',
    // Per-artboard header: grip + label on the left, delete/expand on the
    // right. Single flex row; when the artboard's on-screen width is too
    // narrow for both the label yields (ellipsis, then hidden entirely below
    // ~4ch via the container query) and the buttons stay on the row.
    '.dc-header{position:absolute;bottom:100%;left:-4px;margin-bottom:calc(4px * var(--dc-inv-zoom,1));z-index:2;',
    '  display:flex;align-items:center;container-type:inline-size}',
    '.dc-labelrow{display:flex;align-items:center;gap:4px;height:24px;flex:1 1 auto;min-width:0}',
    '.dc-grip{flex:0 0 auto;cursor:grab;display:flex;align-items:center;padding:5px 4px;border-radius:4px;transition:background .12s,opacity .12s}',
    '.dc-grip:hover{background:rgba(0,0,0,.08)}',
    '.dc-grip:active{cursor:grabbing}',
    '.dc-labeltext{flex:1 1 auto;min-width:0;cursor:pointer;border-radius:4px;padding:3px 6px;',
    '  display:flex;align-items:center;transition:background .12s;overflow:hidden}',
    // Below ~4ch of label room: hide the label entirely, and drop the grip to
    // hover-only (same reveal rule as .dc-btns) so a narrow header is clean
    // until the card is moused.
    '@container (max-width: 110px){',
    '  .dc-labeltext{display:none}',
    '  .dc-grip{opacity:0}',
    '  [data-dc-slot]:hover .dc-grip{opacity:1}',
    '}',
    '.dc-labeltext:hover{background:rgba(31,35,41,0.05)}',
    '.dc-labeltext .dc-editable{overflow:hidden;text-overflow:ellipsis;max-width:100%}',
    '.dc-labeltext .dc-editable:focus{overflow:visible;text-overflow:clip}',
    '.dc-btns{flex:0 0 auto;margin-left:auto;display:flex;gap:2px;opacity:0;transition:opacity .12s}',
    '[data-dc-slot]:hover .dc-header,[data-dc-slot]:hover .dc-header .dc-editable{color:#646A73!important}',
    '[data-dc-slot]:hover .dc-btns,.dc-btns:has(.dc-menu){opacity:1}',
    // On touch devices (no hover) the per-artboard action bar (kebab + expand)
    // can't be reveal-on-hover and tends to stick visible after a tap — hide it
    // entirely on mobile. The grip + label stay for per-screen context.
    '@media (hover: none){.dc-btns{display:none}}',
    // Mobile (UA-detected, .dc-mobile on the viewport root) is browse-only:
    // drag-reorder is disabled there, so the grip is dead weight — hide it.
    '.dc-mobile .dc-grip{display:none}',
    // Mobile is browse-only: kill text selection + iOS long-press callout
    // inside the canvas. iOS interprets a drag over selectable TEXT as a
    // selection gesture and steals the pointer (pointercancel) — touch-action
    // only suppresses native pan/zoom, not selection — so text-dense
    // artboards became un-pannable while image-heavy ones panned fine.
    '.dc-mobile, .dc-mobile *{-webkit-user-select:none;user-select:none;-webkit-touch-callout:none}',
    // Prototype content routinely carries inner scrollers (the device/window
    // frames all have overflow:auto bodies). On iOS a touch starting inside a
    // scrollable element is consumed by THAT scroller (native scroll attempt
    // + pointercancel), so pans could never start on those artboards while
    // plain-HTML cards panned fine. Mobile canvas is browse-only: kill native
    // touch handling on everything inside the cards so gestures always reach
    // the viewport state machine. Desktop (no .dc-mobile) keeps inner scroll.
    '.dc-mobile [data-dc-slot] *{touch-action:none !important}',
    // Pinch updates --dc-inv-zoom per frame (PC semantics: chrome size AND
    // section spacing stay constant). The per-frame relayout that implies
    // white-flashed on WKWebView when the whole world was one paint layer —
    // every head resize invalidated and re-rasterized ALL content. Promote
    // each card (and head) to its own compositing layer: relayout then only
    // MOVES card layers (compositor, no repaint) and repaints just the tiny
    // head layers. contain:paint bounds invalidation to the card box.
    // contain:paint must live on .dc-card, NOT the slot: .dc-header is an
    // abs-positioned slot child sitting entirely ABOVE the slot box
    // (bottom:100%) — paint containment on the slot would clip it out of
    // rendering AND hit-testing, killing the label tap that is mobile's only
    // focus-overlay entry. will-change (the layer-promotion half of the
    // white-flash fix) stays on the slot so header + card share one layer.
    '.dc-mobile [data-dc-slot]{will-change:transform}',
    '.dc-mobile .dc-card{contain:paint}',
    '.dc-mobile .dc-sectionhead{will-change:transform}',
    '[data-dc-slot]:hover .dc-card.chromeless>*,  [data-dc-slot]:hover .dc-card:not(.chromeless){box-shadow:0 4px 8px -8px rgba(0, 0, 0, 0.06), 0 6px 12px 0 rgba(0, 0, 0, 0.04), 0 8px 24px 8px rgba(0, 0, 0, 0.04)}',
    '.dc-expand,.dc-kebab{width:22px;height:22px;border-radius:6px;border:none;cursor:pointer;padding:0;',
    '  background:transparent;color:#646A73;display:flex;align-items:center;justify-content:center;',
    '  font:inherit;transition:background .12s,color .12s}',
    '.dc-expand:hover,.dc-kebab:hover{background:rgba(31,35,41,0.05);color:#646A73}',
    // Slot hosting an open menu floats above later siblings (which otherwise
    // paint on top — same z-index:auto, later DOM order) so the popup isn't
    // clipped by the next card.
    '[data-dc-slot]:has(.dc-menu){z-index:10}',
    '.dc-menu{position:absolute;top:100%;right:0;margin-top:4px;background:#fff;border-radius:8px;border:1px solid #DEE0E3;',
    '  box-shadow:0 4px 8px 0 rgba(0,0,0,0.03),0 3px 6px -6px rgba(0,0,0,0.05),0 6px 18px 6px rgba(0,0,0,0.03);padding:3px;min-width:120px;z-index:10}',
    '.dc-menu button{display:block;width:100%;padding:4px 8px;border:0;background:transparent;',
    '  border-radius:6px;font-family:inherit;font-size:14px;font-weight:400;line-height:24px;',
    '  color:#1F2329;cursor:pointer;text-align:left;transition:background .12s;white-space:nowrap}',
    '.dc-menu button:hover{background:rgba(31,35,41,0.05)}',
    '.dc-menu hr{border:0;border-top:1px solid rgba(0,0,0,.08);margin:4px 2px}',
    '.dc-menu .dc-danger{color:#F54A45}',
    // Chrome (titles / labels / buttons) counter-scales against the viewport
    // zoom so it stays a constant on-screen size. --dc-inv-zoom is set by
    // DCViewport on every transform update and inherits to all descendants —
    // any overlay inside the world (e.g. a TweaksPanel on an artboard) can use
    // it the same way.
    //
    // The header uses transform:scale (out-of-flow, so layout impact doesn't
    // matter) with its world-space width set to card-width / inv-zoom so that
    // after counter-scaling its on-screen width exactly matches the card's —
    // that's what lets the container query + text-overflow behave against the
    // card's visible edge at every zoom level.
    //
    // The section head uses CSS zoom instead of transform so its layout box
    // grows with the counter-scale, pushing the card row down — otherwise the
    // constant-screen-size title would overflow into the (shrinking) world-
    // space gap and overlap the artboard headers at low zoom.
    '.dc-header{width:calc((100% + 4px) / var(--dc-inv-zoom,1));',
    '  transform:scale(var(--dc-inv-zoom,1));transform-origin:bottom left;will-change:transform}',
    '.dc-sectionhead{zoom:var(--dc-inv-zoom,1)}',
    // On-canvas zoom control (bottom-right pill). Stays screen-fixed because
    // it renders outside worldRef. z-index 50 keeps it above world content but
    // below the focus overlay (z-index 100). The dropdown reuses .dc-menu and
    // only overrides its positioning to open upward (.dc-zoom-menu).
    '.dc-zoom{position:absolute;bottom:16px;right:20px;z-index:50;display:flex;align-items:center;',
    '  background:#fff;border-radius:8px;padding:4px;font-family:inherit;',
    '  border:0.5px solid #DEE0E3;box-shadow:0 2px 4px -4px rgba(31,35,41,0.02),0 4px 8px 0 rgba(31,35,41,0.02),0 4px 16px 4px rgba(31,35,41,0.03)}',
    '.dc-zoom-btn{height:24px;min-width:24px;border-radius:6px;border:none;cursor:pointer;padding:0;',
    '  background:transparent;color:rgba(60,50,40,.7);display:flex;align-items:center;justify-content:center;',
    '  font:inherit;transition:background .12s,color .12s}',
    '.dc-zoom-btn:hover{background:#1f23290d}',
    '.dc-zoom-btn:disabled{opacity:.35;cursor:default;background:transparent;color:rgba(60,50,40,.7)}',
    '.dc-zoom-toggle{position:relative;display:flex}',
    '.dc-zoom-trigger{padding:0 6px;gap:4px}',
    '.dc-zoom-pct{min-width:36px;text-align:center;font-size:12px;font-weight:400;color:#1F2329}',
    '.dc-zoom-menu{top:auto;bottom:100%;left:50%;transform:translateX(-50%);margin-top:0;margin-bottom:6px;min-width:114px}',
    '.dc-zoom-menu button{display:flex;align-items:center;justify-content:space-between;gap:8px}',
  ].join('\n');
  document.head.appendChild(s);
}

const DCCtx = React.createContext(null);

// Recursively unwrap React.Fragment so <>…</> grouping doesn't hide
// DCSection/DCArtboard children from the type-based walks below.
function dcFlatten(children) {
  const out = [];
  React.Children.forEach(children, (c) => {
    if (c && c.type === React.Fragment) out.push(...dcFlatten(c.props.children));
    else out.push(c);
  });
  return out;
}

// ─────────────────────────────────────────────────────────────
// DesignCanvas — stateful wrapper around the pan/zoom viewport.
// Owns runtime state (per-section order, renamed titles/labels, hidden
// artboards, focused artboard). Order/titles/labels/hidden persist to a
// .design-canvas.state.json
// sidecar next to the HTML. Reads go via plain fetch() so the saved
// arrangement is visible anywhere the HTML + sidecar are served together
// (miaoda preview, direct link, downloaded zip). Writes post the sidecar
// content up to the miaoda host via postMessage — editing requires the miaoda runtime.
// Focus is ephemeral.
// ─────────────────────────────────────────────────────────────
const DC_STATE_FILE = '.design-canvas.state.json';

// Persist a sidecar file back to the host.
function miaodaWriteFile(path, content) {
  try {
    window.parent.postMessage({ type: 'miaoda:bridge:write-file', path: path, content: content }, '*');
  } catch (e) {
    /* no parent — ignore */
  }
  return Promise.resolve();
}

function DesignCanvas({ children, minScale, maxScale, style }) {
  const [state, setState] = React.useState({ sections: {}, focus: null });
  // Hold rendering until the sidecar read settles so the saved order/titles
  // appear on first paint (no source-order flash). didRead gates writes until
  // the read settles so the empty initial state can't clobber a slow read;
  // skipNextWrite suppresses the one echo-write that would otherwise follow
  // hydration.
  const [ready, setReady] = React.useState(false);
  const didRead = React.useRef(false);
  const skipNextWrite = React.useRef(false);

  React.useEffect(() => {
    let off = false;
    fetch('./' + DC_STATE_FILE)
      .then((r) => (r.ok ? r.json() : null))
      .then((saved) => {
        if (off || !saved || !saved.sections) return;
        skipNextWrite.current = true;
        setState((s) => ({ ...s, sections: saved.sections }));
      })
      .catch(() => {})
      .finally(() => { didRead.current = true; if (!off) setReady(true); });
    const t = setTimeout(() => { if (!off) setReady(true); }, 150);
    return () => { off = true; clearTimeout(t); };
  }, []);

  React.useEffect(() => {
    if (!didRead.current) return;
    if (skipNextWrite.current) { skipNextWrite.current = false; return; }
    const t = setTimeout(() => {
      miaodaWriteFile(DC_STATE_FILE, JSON.stringify({ sections: state.sections })).catch(() => {});
    }, 250);
    return () => clearTimeout(t);
  }, [state.sections]);

  // Build registries synchronously from children so FocusOverlay can read
  // them in the same render. Fragments are flattened; wrapping in other
  // elements still opts out of focus/reorder.
  const registry = {};     // slotId -> { sectionId, artboard }
  const sectionMeta = {};  // sectionId -> { title, subtitle, slotIds[] }
  const sectionOrder = [];
  dcFlatten(children).forEach((sec) => {
    if (!sec || sec.type !== DCSection) return;
    const sid = sec.props.id ?? sec.props.title;
    if (!sid) return;
    sectionOrder.push(sid);
    const persisted = state.sections[sid] || {};
    const abs = [];
    dcFlatten(sec.props.children).forEach((ab) => {
      if (!ab || ab.type !== DCArtboard) return;
      const aid = ab.props.id ?? ab.props.label;
      if (aid) abs.push([aid, ab]);
    });
    // hidden is scoped to one source revision — when the agent regenerates
    // (artboard-ID set changes), prior deletes don't apply to new content.
    const srcKey = abs.map(([k]) => k).join('\x1f');
    const hidden = persisted.srcKey === srcKey ? (persisted.hidden || []) : [];
    const srcIds = [];
    abs.forEach(([aid, ab]) => {
      if (hidden.includes(aid)) return;
      registry[`${sid}/${aid}`] = { sectionId: sid, artboard: ab };
      srcIds.push(aid);
    });
    const kept = (persisted.order || []).filter((k) => srcIds.includes(k));
    sectionMeta[sid] = {
      title: persisted.title ?? sec.props.title,
      subtitle: sec.props.subtitle,
      slotIds: [...kept, ...srcIds.filter((k) => !kept.includes(k))],
    };
  });

  const api = React.useMemo(() => ({
    state,
    section: (id) => state.sections[id] || {},
    patchSection: (id, p) => setState((s) => ({
      ...s,
      sections: { ...s.sections, [id]: { ...s.sections[id], ...(typeof p === 'function' ? p(s.sections[id] || {}) : p) } },
    })),
    setFocus: (slotId) => setState((s) => ({ ...s, focus: slotId })),
  }), [state]);

  // Esc exits focus; any outside pointerdown commits an in-progress rename.
  React.useEffect(() => {
    const onKey = (e) => { if (e.key === 'Escape') api.setFocus(null); };
    const onPd = (e) => {
      const ae = document.activeElement;
      if (ae && ae.isContentEditable && !ae.contains(e.target)) ae.blur();
    };
    document.addEventListener('keydown', onKey);
    document.addEventListener('pointerdown', onPd, true);
    return () => {
      document.removeEventListener('keydown', onKey);
      document.removeEventListener('pointerdown', onPd, true);
    };
  }, [api]);

  // dcOverlay opt-in: render outside DCViewport so the component is free from
  // worldRef's transform (pan/zoom). Unmarked children stay in the canvas.
  const flat = dcFlatten(children);
  const overlayChildren = flat.filter(c => c && c.type?.dcOverlay);
  const worldChildren = flat.filter(c => !c || !c.type?.dcOverlay);

  return (
    <DCCtx.Provider value={api}>
      <DCViewport minScale={minScale} maxScale={maxScale} style={style}>{ready && worldChildren}</DCViewport>
      {ready && overlayChildren}
      {state.focus && registry[state.focus] && (
        <DCFocusOverlay entry={registry[state.focus]} sectionMeta={sectionMeta} sectionOrder={sectionOrder} />
      )}
    </DCCtx.Provider>
  );
}

// ─────────────────────────────────────────────────────────────
// DCZoomControl — bottom-right zoom pill (zoom-in / % + presets / zoom-out)
//
// Renders outside worldRef so it stays screen-fixed. data-miaoda-chrome marks
// it as non-background so the viewport's pointerdown doesn't start a pan on it
// (the native vp listener can't be stopped by React's synthetic propagation,
// so the attribute — not stopPropagation — is what prevents the pan). Buttons
// step to the nearest 10% grid, clamped to the canvas scale range; the dropdown
// offers common presets and opens upward.
// ─────────────────────────────────────────────────────────────
const DC_ZOOM_PRESETS = [20, 35, 50, 75, 100, 125, 150, 175, 200];

function DCZoomControl({ scalePct, minScale, maxScale, onZoomTo }) {
  const [open, setOpen] = React.useState(false);
  const rootRef = React.useRef(null);
  const minPct = Math.round(minScale * 100);
  const maxPct = Math.round(maxScale * 100);
  const snapUp = Math.min(maxPct, (Math.floor(scalePct / 10) + 1) * 10);
  const snapDown = Math.max(minPct, (Math.ceil(scalePct / 10) - 1) * 10);

  React.useEffect(() => {
    if (!open) return;
    const onDocDown = (e) => {
      if (rootRef.current && !rootRef.current.contains(e.target)) setOpen(false);
    };
    document.addEventListener('pointerdown', onDocDown);
    return () => document.removeEventListener('pointerdown', onDocDown);
  }, [open]);

  return (
    <div
      ref={rootRef}
      className="dc-zoom"
      data-miaoda-chrome=""
      onPointerDown={(e) => e.stopPropagation()}
    >
      <button
        type="button"
        className="dc-zoom-btn"
        disabled={scalePct >= maxPct}
        onClick={() => onZoomTo(snapUp)}
      >
        <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
          <path d="M12.4957 11.5517L14.9105 13.9668C15.1702 14.2266 15.1684 14.648 14.9087 14.9077C14.649 15.1674 14.2275 15.1692 13.9678 14.9095L11.5527 12.4943C10.3631 13.4696 8.87188 14.0016 7.33366 13.9993C3.65166 13.9993 0.666992 11.0147 0.666992 7.33268C0.666992 3.65068 3.65166 0.666016 7.33366 0.666016C11.0157 0.666016 14.0003 3.65068 14.0003 7.33268C14.0003 8.93368 13.436 10.4027 12.4957 11.5517ZM6.66699 6.66602V5.33268C6.66699 4.96449 6.96547 4.66602 7.33366 4.66602C7.70185 4.66602 8.00033 4.96449 8.00033 5.33268V6.66602H9.33366C9.70185 6.66602 10.0003 6.96449 10.0003 7.33268C10.0003 7.70087 9.70185 7.99935 9.33366 7.99935H8.00033V9.33268C8.00033 9.70087 7.70185 9.99935 7.33366 9.99935C6.96547 9.99935 6.66699 9.70087 6.66699 9.33268V7.99935H5.33366C4.96547 7.99935 4.66699 7.70087 4.66699 7.33268C4.66699 6.96449 4.96547 6.66602 5.33366 6.66602H6.66699ZM7.33366 12.666C10.2793 12.666 12.667 10.2783 12.667 7.33268C12.667 4.38702 10.2793 1.99935 7.33366 1.99935C4.38799 1.99935 2.00033 4.38702 2.00033 7.33268C2.00033 10.2783 4.38799 12.666 7.33366 12.666Z" fill="#1F2329"/>
        </svg>
      </button>

      <div className="dc-zoom-toggle">
        <button
          type="button"
          className="dc-zoom-btn dc-zoom-trigger"
          onClick={() => setOpen((o) => !o)}
        >
          <span className="dc-zoom-pct">{scalePct}%</span>
          <svg width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden="true">
            <path d="M2 3.5L5 6.5L8 3.5" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
          </svg>
        </button>
        {open && (
          <div className="dc-menu dc-zoom-menu" onPointerDown={(e) => e.stopPropagation()}>
            {DC_ZOOM_PRESETS.map((p) => (
              <button type="button" key={p} onClick={() => { onZoomTo(p); setOpen(false); }}>
                <span>{p}%</span>
                {p === scalePct && (
                  <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
                    <path d="M2.00002 5.64639C2.09378 5.55266 2.22094 5.5 2.35352 5.5C2.4861 5.5 2.61325 5.55266 2.70702 5.64639L4.74277 7.68189L9.27827 3.14639C9.37203 3.05266 9.49919 3 9.63177 3C9.76435 3 9.8915 3.05266 9.98527 3.14639L10.3388 3.49989C10.3852 3.54633 10.4221 3.60145 10.4472 3.66213C10.4723 3.72281 10.4853 3.78784 10.4853 3.85352C10.4853 3.9192 10.4723 3.98423 10.4472 4.04491C10.4221 4.10558 10.3852 4.16071 10.3388 4.20714L5.09627 9.44965C5.04984 9.4961 4.99471 9.53295 4.93403 9.55808C4.87336 9.58322 4.80832 9.59616 4.74264 9.59616C4.67697 9.59616 4.61193 9.58322 4.55125 9.55808C4.49058 9.53295 4.43545 9.4961 4.38902 9.44965L1.64652 6.70714C1.60007 6.66071 1.56322 6.60558 1.53808 6.54491C1.51294 6.48423 1.5 6.4192 1.5 6.35352C1.5 6.28784 1.51294 6.22281 1.53808 6.16213C1.56322 6.10145 1.60007 6.04633 1.64652 5.99989L2.00002 5.64639Z" fill="#1F2329"/>
                  </svg>
                )}
              </button>
            ))}
          </div>
        )}
      </div>

      <button
        type="button"
        className="dc-zoom-btn"
        disabled={scalePct <= minPct}
        onClick={() => onZoomTo(snapDown)}
      >
        <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
          <path d="M12.4957 11.5517L14.9111 13.9674C15.1707 14.227 15.1697 14.6496 14.9102 14.9092C14.6506 15.1688 14.228 15.1697 13.9684 14.9101L11.5527 12.4943C10.3631 13.4696 8.87188 14.0016 7.33366 13.9993C3.65166 13.9993 0.666992 11.0147 0.666992 7.33268C0.666992 3.65068 3.65166 0.666016 7.33366 0.666016C11.0157 0.666016 14.0003 3.65068 14.0003 7.33268C14.0003 8.93368 13.436 10.4027 12.4957 11.5517ZM7.33366 12.666C10.2793 12.666 12.667 10.2783 12.667 7.33268C12.667 4.38702 10.2793 1.99935 7.33366 1.99935C4.38799 1.99935 2.00033 4.38702 2.00033 7.33268C2.00033 10.2783 4.38799 12.666 7.33366 12.666ZM4.66699 7.33268C4.66699 6.96449 4.96547 6.66602 5.33366 6.66602H9.33366C9.70185 6.66602 10.0003 6.96449 10.0003 7.33268C10.0003 7.70087 9.70185 7.99935 9.33366 7.99935H5.33366C4.96547 7.99935 4.66699 7.70087 4.66699 7.33268Z" fill="#1F2329"/>
        </svg>
      </button>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// DCViewport — transform-based pan/zoom (internal)
//
// Input mapping (Figma-style):
//   • trackpad pinch                     → zoom  (ctrlKey wheel; Safari gesture* events)
//   • Ctrl/⌘ + wheel                     → zoom
//   • trackpad two-finger / mouse wheel  → pan
//   • middle-drag / primary-drag-on-bg   → pan
//
// Transform state lives in a ref and is written straight to the DOM
// (translate3d + will-change) so wheel ticks don't go through React —
// keeps pans at 60fps on dense canvases.
// ─────────────────────────────────────────────────────────────
function DCViewport({ children, minScale = 0.1, maxScale = 8, style = {} }) {
  const vpRef = React.useRef(null);
  const worldRef = React.useRef(null);
  // Pre-fit fallback scale. A fresh canvas is reframed by the first-visit fit
  // (below) once content mounts; localStorage restore overrides this on
  // revisits. This 50% only shows in the gap before either runs.
  const tf = React.useRef({ x: 0, y: 0, scale: 0.5 });
  // Persist viewport across reloads so the user lands back where they were
  // after an agent edit or browser refresh. The sandbox origin is already
  // per-project; pathname keeps multiple canvas files in one project apart.
  const tfKey = 'dc-viewport:' + location.pathname;
  const saveT = React.useRef(0);

  const lastPostedScale = React.useRef();
  // Imperative handle for the on-canvas zoom control to zoom around the
  // viewport centre (same path as the host's set-zoom message). Assigned in
  // the pointer/wheel effect below where zoomAt is in scope.
  const zoomCenteredRef = React.useRef(null);
  // Percentage shown by the zoom control. Synced from apply() on every scale
  // change — React bails out when the rounded value is unchanged, so pan ticks
  // (scale unchanged) cost nothing. Lazily seeded from the persisted transform
  // so the first paint already shows the restored — or default 50% — zoom.
  const [scalePct, setScalePct] = React.useState(() => {
    try {
      const s = JSON.parse(localStorage.getItem(tfKey) || 'null');
      if (s && Number.isFinite(s.scale)) {
        return Math.round(Math.min(maxScale, Math.max(minScale, s.scale)) * 100);
      }
    } catch {}
    return Math.round(tf.current.scale * 100);
  });
  const apply = React.useCallback(() => {
    const { x, y, scale } = tf.current;
    const el = worldRef.current;
    if (!el) return;
    el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(${scale})`;
    // Exposed for zoom-invariant chrome (labels, buttons, TweaksPanel).
    el.style.setProperty('--dc-inv-zoom', String(1 / scale));
    // Keep the on-canvas zoom control's % readout in sync. React bails out on
    // an unchanged rounded value, so pan ticks (scale unchanged) don't render.
    // Mobile renders no zoom control — a per-frame setState during pinch
    // would re-render the whole subtree every frame (visible repaint flicker
    // on phones) for a readout nobody consumes, so skip it there entirely.
    if (!dcIsMobile) setScalePct(Math.round(scale * 100));
    // Keep the host toolbar's % readout in sync with the canvas scale. Pan
    // ticks leave scale unchanged — skip the cross-frame post for those.
    if (lastPostedScale.current !== scale) {
      lastPostedScale.current = scale;
      window.parent.postMessage({ type: 'miaoda:canvas:zoom', scale }, '*');
    }
    clearTimeout(saveT.current);
    saveT.current = setTimeout(() => {
      try { localStorage.setItem(tfKey, JSON.stringify(tf.current)); } catch {}
    }, 200);
  }, [tfKey]);

  // Whether the mount-time restore found a saved viewport — when it did, the
  // first-visit fit below is skipped so revisits keep the user's own view.
  const restoredView = React.useRef(false);
  const didFit = React.useRef(false);

  React.useLayoutEffect(() => {
    const flush = () => {
      clearTimeout(saveT.current);
      try { localStorage.setItem(tfKey, JSON.stringify(tf.current)); } catch {}
    };
    try {
      const s = JSON.parse(localStorage.getItem(tfKey) || 'null');
      if (s && Number.isFinite(s.x) && Number.isFinite(s.y) && Number.isFinite(s.scale)) {
        tf.current = { x: s.x, y: s.y, scale: Math.min(maxScale, Math.max(minScale, s.scale)) };
        restoredView.current = true;
      }
    } catch {}
    // Apply before first paint whether we restored or fell back to the default
    // (scale 0.5) so the canvas never flashes at the wrong zoom. On a fresh
    // canvas the first-visit fit (below) reframes once content mounts.
    apply();
    // Flush on pagehide and unmount so a reload within the 200ms debounce
    // window doesn't drop the last pan/zoom.
    window.addEventListener('pagehide', flush);
    return () => { window.removeEventListener('pagehide', flush); flush(); };
  }, []);

  // First-visit framing: once the (ready-gated) content mounts, scale + centre
  // the whole canvas so every artboard fits with a ≥64px safe margin on all
  // sides. Skipped when a saved viewport was restored. Runs as a layout effect
  // on the commit that first paints content, so there's no un-framed flash.
  React.useLayoutEffect(() => {
    if (didFit.current || restoredView.current) return;
    const vp = vpRef.current, world = worldRef.current;
    if (!vp || !world) return;
    const slots = world.querySelectorAll('[data-dc-slot]');
    if (!slots.length) return; // content not mounted yet — wait for the ready commit
    const heads = world.querySelectorAll('.dc-sectionhead');
    // Fit margin from the screen edges. Mobile screens are narrow — 64px a
    // side eats a third of the width, so fit flush-ish at 16px there.
    const PAD = dcIsMobile ? 16 : 64;

    // Content bounding box in WORLD space at the currently applied transform.
    // X extent from cards only (section-head blocks are full width and would
    // over-report); Y from cards + titles so the top heading is kept in frame.
    const measure = () => {
      const vpr = vp.getBoundingClientRect();
      const t = tf.current;
      let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
      slots.forEach((el) => {
        const r = el.getBoundingClientRect();
        minX = Math.min(minX, (r.left - vpr.left - t.x) / t.scale);
        maxX = Math.max(maxX, (r.right - vpr.left - t.x) / t.scale);
        minY = Math.min(minY, (r.top - vpr.top - t.y) / t.scale);
        maxY = Math.max(maxY, (r.bottom - vpr.top - t.y) / t.scale);
      });
      heads.forEach((el) => {
        const r = el.getBoundingClientRect();
        minY = Math.min(minY, (r.top - vpr.top - t.y) / t.scale);
        maxY = Math.max(maxY, (r.bottom - vpr.top - t.y) / t.scale);
      });
      return { vpr, minX, minY, w: maxX - minX, h: maxY - minY };
    };

    // Content SCREEN width is linear in scale (screenW = s·Wworld) and SCREEN
    // height is affine (screenH = s·P + Q): titles and inter-section gaps
    // counter-scale with zoom, so they hold a constant screen size while cards
    // scale. Sample two scales to solve the coefficients, then pick the largest
    // scale that keeps both axes within the viewport minus a PAD margin — exact,
    // no iterate-to-converge.
    const s1 = tf.current.scale;
    const m1 = measure();
    if (!(m1.w > 0) || !(m1.h > 0)) { didFit.current = true; return; }
    const s2 = s1 * 0.7;
    tf.current.scale = s2; apply();
    const m2 = measure();

    const { vpr } = m1;
    const avW = vpr.width - PAD * 2, avH = vpr.height - PAD * 2;
    const Wworld = m1.w;                              // screenW / s, scale-invariant
    const P = (s1 * m1.h - s2 * m2.h) / (s1 - s2);    // d(screenH)/d(scale)
    const Q = s1 * m1.h - s1 * P;                     // constant screen-space part
    const fitW = avW / Wworld;
    const fitH = P > 0 ? (avH - Q) / P : Infinity;
    const next = Math.max(minScale, Math.min(maxScale, Math.min(fitW, fitH)));

    // Apply the solved scale, then centre using the extent measured AT that
    // scale so margins come out symmetric (exactly PAD on the binding axis).
    tf.current.scale = next; apply();
    const mf = measure();
    tf.current.x = (vpr.width - mf.w * next) / 2 - mf.minX * next;
    tf.current.y = (vpr.height - mf.h * next) / 2 - mf.minY * next;
    apply();
    didFit.current = true;
  });

  React.useEffect(() => {
    const vp = vpRef.current;
    if (!vp) return;

    const zoomAt = (cx, cy, factor) => {
      const r = vp.getBoundingClientRect();
      const px = cx - r.left, py = cy - r.top;
      const t = tf.current;
      const next = Math.min(maxScale, Math.max(minScale, t.scale * factor));
      const k = next / t.scale;
      // --dc-inv-zoom consumers (.dc-sectionhead's CSS zoom, each section's
      // marginBottom) reflow on every scale change, vertically shifting the
      // world layout — so a world point mathematically pinned under the cursor
      // drifts as you zoom (content creeps up on zoom-in, down on zoom-out).
      // Anchor the DOM element under the cursor instead: record its screen Y,
      // apply the transform + --dc-inv-zoom, then cancel whatever vertical
      // drift the reflow introduced so it stays put on screen.
      let marker = null, markerY0 = 0;
      if (k !== 1) {
        const hit = document.elementFromPoint(cx, cy);
        marker = hit && hit.closest ? hit.closest('[data-dc-slot],[data-dc-section]') : null;
        if (marker) markerY0 = marker.getBoundingClientRect().top;
      }
      // keep the world point under the cursor fixed
      t.x = px - (px - t.x) * k;
      t.y = py - (py - t.y) * k;
      t.scale = next;
      apply();
      if (marker) {
        // A pure zoom around (cx, cy) maps screen Y → cy + (Y - cy) * k. Any
        // departure after the --dc-inv-zoom reflow is the layout drift.
        const drift = marker.getBoundingClientRect().top - (cy + (markerY0 - cy) * k);
        if (Math.abs(drift) > 0.1) { t.y -= drift; apply(); }
      }
    };

    // On-canvas zoom control: zoom to a target scale around the viewport
    // centre, matching the host set-zoom path (onHostMsg). Closes over the
    // live zoomAt / vp / tf, so it always uses the current transform.
    zoomCenteredRef.current = (targetScale) => {
      const r = vp.getBoundingClientRect();
      const clamped = Math.min(maxScale, Math.max(minScale, targetScale));
      zoomAt(r.left + r.width / 2, r.top + r.height / 2, clamped / tf.current.scale);
    };

    // Zoom is gated behind a modifier only: the browser sets ctrlKey for a
    // trackpad pinch, and Ctrl/⌘ + wheel is the explicit mouse-zoom gesture.
    // Every unmodified scroll — trackpad two-finger OR mouse wheel — pans.
    // This is Figma's mapping, and it sidesteps a classification that can't be
    // done reliably: a fast vertical trackpad flick's peak frame is identical
    // to a mouse-wheel notch (deltaMode 0, deltaX 0, large integer deltaY), so
    // routing pan-vs-zoom from a single wheel event misfires — a quick two-
    // finger swipe used to jump into zoom. Keying off the modifier removes the
    // ambiguity at the source.
    //
    // isNotchedWheel now only picks the zoom *step size* inside the zoom
    // branch (fixed ratio for discrete wheels / Firefox line-mode, continuous
    // exp for a smooth pinch) — misjudging it is a harmless granularity
    // difference, never a pan↔zoom flip.
    const isNotchedWheel = (e) =>
      e.deltaMode !== 0 ||
      (e.deltaX === 0 && Number.isInteger(e.deltaY) && Math.abs(e.deltaY) >= 40);

    const onWheel = (e) => {
      e.preventDefault();
      if (isGesturing) return; // Safari: gesture* owns the pinch — discard concurrent wheels
      if (e.ctrlKey || e.metaKey) {
        zoomAt(e.clientX, e.clientY,
          isNotchedWheel(e) ? Math.exp(-Math.sign(e.deltaY) * 0.18) : Math.exp(-e.deltaY * 0.01));
      } else {
        // Unmodified scroll pans. Normalize line/page deltas so a notched
        // wheel moves a sensible distance instead of a few pixels per notch.
        const unit = e.deltaMode === 1 ? 16 : e.deltaMode === 2 ? vp.clientHeight : 1;
        tf.current.x -= e.deltaX * unit;
        tf.current.y -= e.deltaY * unit;
        apply();
      }
    };

    // Safari sends native gesture* events for trackpad pinch with a smooth
    // e.scale; preferring these over the ctrl+wheel fallback gives a much
    // better feel there. No-ops on other browsers. Safari also fires
    // ctrlKey wheel events during the same pinch — isGesturing makes
    // onWheel drop those entirely so they neither zoom nor pan.
    //
    // On mobile the pointer-based two-finger pinch below is the single zoom
    // source. iOS fires BOTH pointer events and these WebKit gesture* events
    // for the same two fingers — zooming from both would double-apply, so on
    // mobile gesture* degrades to preventDefault only (still suppressing the
    // native page zoom).
    let gsBase = 1;
    let isGesturing = false;
    const onGestureStart = (e) => { e.preventDefault(); isGesturing = true; gsBase = tf.current.scale; };
    const onGestureChange = (e) => {
      e.preventDefault();
      if (dcIsMobile) return;
      zoomAt(e.clientX, e.clientY, (gsBase * e.scale) / tf.current.scale);
    };
    const onGestureEnd = (e) => { e.preventDefault(); isGesturing = false; };

    // Drag-pan: middle button anywhere, or primary button on canvas
    // background (anything that isn't an artboard or an inline editor).
    let drag = null;
    const onPointerDown = (e) => {
      const onBg = !e.target.closest('[data-dc-slot], .dc-editable, [data-miaoda-chrome]');
      if (!(e.button === 1 || (e.button === 0 && onBg))) return;
      e.preventDefault();
      vp.setPointerCapture(e.pointerId);
      drag = { id: e.pointerId, lx: e.clientX, ly: e.clientY };
      vp.style.cursor = 'grabbing';
    };
    const onPointerMove = (e) => {
      if (!drag || e.pointerId !== drag.id) return;
      tf.current.x += e.clientX - drag.lx;
      tf.current.y += e.clientY - drag.ly;
      drag.lx = e.clientX; drag.ly = e.clientY;
      apply();
    };
    const onPointerUp = (e) => {
      if (!drag || e.pointerId !== drag.id) return;
      vp.releasePointerCapture(e.pointerId);
      drag = null;
      vp.style.cursor = '';
    };

    // ── Mobile touch gestures (replaces the desktop pointer mapping above):
    // one-finger drag pans — starting on artboards too, since cards fill a
    // phone viewport and background is scarce; two-finger pinch zooms about
    // the midpoint while the midpoint's own travel pans (Figma semantics, one
    // gesture frames the view). A tap/pan slop keeps label taps working: no
    // capture happens within the slop, so a clean tap still clicks through to
    // focus; past it the viewport captures the pointer and the click retargets
    // harmlessly. No fling/inertia — release stops the canvas (spec §8).
    const touches = new Map(); // pointerId -> last {x, y}
    let mobMode = null;        // null | 'tap' | 'pan' | 'pinch'
    let tapStart = null;       // down point for slop arbitration
    let pinchDist = 0;         // previous-frame finger distance
    let pinchMid = null;       // previous-frame midpoint
    const MOB_SLOP = 9;        // px of travel before a tap becomes a pan

    // First two insertion-ordered touches define the pinch; a third finger is
    // tracked but inert (its moves shift neither midpoint nor distance).
    const pinchGeom = () => {
      const [a, b] = [...touches.values()];
      return { d: Math.hypot(a.x - b.x, a.y - b.y), mx: (a.x + b.x) / 2, my: (a.y + b.y) / 2 };
    };

    const onTouchDown = (e) => {
      touches.set(e.pointerId, { x: e.clientX, y: e.clientY });
      if (touches.size === 1) {
        mobMode = 'tap';
        tapStart = { x: e.clientX, y: e.clientY };
      } else if (touches.size === 2) {
        mobMode = 'pinch';
        const g = pinchGeom();
        pinchDist = g.d;
        pinchMid = { x: g.mx, y: g.my };
        try { vp.setPointerCapture(e.pointerId); } catch {}
      }
    };
    const onTouchMove = (e) => {
      const t = touches.get(e.pointerId);
      if (!t) return;
      const px = t.x, py = t.y;
      t.x = e.clientX; t.y = e.clientY;
      if (mobMode === 'tap' && Math.hypot(t.x - tapStart.x, t.y - tapStart.y) > MOB_SLOP) {
        mobMode = 'pan';
        try { vp.setPointerCapture(e.pointerId); } catch {}
      }
      if (mobMode === 'pan') {
        tf.current.x += t.x - px;
        tf.current.y += t.y - py;
        apply();
      } else if (mobMode === 'pinch') {
        const g = pinchGeom();
        tf.current.x += g.mx - pinchMid.x;
        tf.current.y += g.my - pinchMid.y;
        pinchMid = { x: g.mx, y: g.my };
        // zoomAt applies the pan mutation above too; degenerate distances
        // (fingers together) skip the zoom but still need the pan applied.
        // Same full zoomAt as the desktop trackpad-pinch path (gesturechange):
        // per-frame --dc-inv-zoom keeps chrome size AND section spacing
        // constant throughout the gesture, with the same drift compensation.
        if (pinchDist > 0 && g.d > 0) zoomAt(g.mx, g.my, g.d / pinchDist);
        else apply();
        pinchDist = g.d;
      }
    };
    const onTouchUp = (e) => {
      if (!touches.delete(e.pointerId)) return;
      try { vp.releasePointerCapture(e.pointerId); } catch {}
      if (touches.size === 0) {
        mobMode = null;
      } else if (touches.size === 1) {
        // Pinch collapsing to one finger hands off to pan with the surviving
        // finger as the new baseline — no jump.
        mobMode = 'pan';
      } else if (mobMode === 'pinch') {
        // 3+ fingers losing one: re-baseline so the new leading pair doesn't
        // read as a sudden midpoint/distance delta.
        const g = pinchGeom();
        pinchDist = g.d;
        pinchMid = { x: g.mx, y: g.my };
      }
    };

    // Host-driven zoom (toolbar % menu). Zooms around viewport centre so the
    // visible midpoint stays fixed — matching the host's iframe-zoom feel.
    const onHostMsg = (e) => {
      const d = e.data;
      if (d && d.type === 'miaoda:canvas:set-zoom' && typeof d.scale === 'number') {
        const r = vp.getBoundingClientRect();
        zoomAt(r.left + r.width / 2, r.top + r.height / 2, d.scale / tf.current.scale);
      } else if (d && d.type === 'miaoda:canvas:probe') {
        // Host's [readyGen] reset asks whether a canvas is present; it
        // fires on the iframe's native 'load', which for canvases with
        // images/fonts is after our mount-time announce, so re-announce.
        // Clear the pan-tick guard so apply() re-posts the current scale
        // even if it's unchanged — the host just reset dcScale to 1.
        window.parent.postMessage({ type: 'miaoda:canvas:present' }, '*');
        lastPostedScale.current = undefined;
        apply();
      }
    };
    window.addEventListener('message', onHostMsg);
    // Announce canvas mode so the host toolbar proxies its % control here
    // instead of scaling the iframe element (which would just shrink the
    // viewport window of an infinite canvas). The apply() that follows emits
    // the initial miaoda:canvas:zoom so the toolbar % is correct before first pinch.
    // lastPostedScale reset mirrors the miaoda:canvas:probe handler: the layout
    // effect's restore-path apply() may already have posted the restored
    // scale (before miaoda:canvas:present), so clear the guard to re-post it in order.
    window.parent.postMessage({ type: 'miaoda:canvas:present' }, '*');
    lastPostedScale.current = undefined;
    apply();

    // Mobile swaps the desktop pointer mapping (bg-only pan) for the touch
    // state machine; wheel/gesture listeners stay on both (harmless without
    // the hardware, and a bluetooth mouse on Android still pans via wheel).
    const pd = dcIsMobile ? onTouchDown : onPointerDown;
    const pm = dcIsMobile ? onTouchMove : onPointerMove;
    const pu = dcIsMobile ? onTouchUp : onPointerUp;
    vp.addEventListener('wheel', onWheel, { passive: false });
    vp.addEventListener('gesturestart', onGestureStart, { passive: false });
    vp.addEventListener('gesturechange', onGestureChange, { passive: false });
    vp.addEventListener('gestureend', onGestureEnd, { passive: false });
    vp.addEventListener('pointerdown', pd);
    vp.addEventListener('pointermove', pm);
    vp.addEventListener('pointerup', pu);
    vp.addEventListener('pointercancel', pu);
    return () => {
      window.removeEventListener('message', onHostMsg);
      vp.removeEventListener('wheel', onWheel);
      vp.removeEventListener('gesturestart', onGestureStart);
      vp.removeEventListener('gesturechange', onGestureChange);
      vp.removeEventListener('gestureend', onGestureEnd);
      vp.removeEventListener('pointerdown', pd);
      vp.removeEventListener('pointermove', pm);
      vp.removeEventListener('pointerup', pu);
      vp.removeEventListener('pointercancel', pu);
    };
  }, [apply, minScale, maxScale]);

  return (
    <div
      ref={vpRef}
      className={dcIsMobile ? 'design-canvas dc-mobile' : 'design-canvas'}
      style={{
        height: '100vh', width: '100vw',
        background: DC.bg,
        overflow: 'hidden',
        overscrollBehavior: 'none',
        touchAction: 'none',
        position: 'relative',
        fontFamily: DC.font,
        boxSizing: 'border-box',
        ...style,
      }}
    >
      <div
        ref={worldRef}
        style={{
          position: 'absolute', top: 0, left: 0,
          transformOrigin: '0 0',
          willChange: 'transform',
          width: 'max-content', minWidth: '100%',
          minHeight: '100%',
          padding: '60px 0 80px',
        }}
      >
        {children}
      </div>
      {/* Mobile zooms by pinch — the control is not rendered at all (host
          set-zoom messages still work; the protocol is independent of it). */}
      {!dcIsMobile && (
        <DCZoomControl
          scalePct={scalePct}
          minScale={minScale}
          maxScale={maxScale}
          onZoomTo={(pct) => zoomCenteredRef.current?.(pct / 100)}
        />
      )}
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// DCSection — editable title + h-row of artboards in persisted order
// ─────────────────────────────────────────────────────────────
function DCSection({ id, title, subtitle, children, gap = 48 }) {
  const ctx = React.useContext(DCCtx);
  const sid = id ?? title;
  const all = React.Children.toArray(dcFlatten(children));
  const artboards = all.filter((c) => c && c.type === DCArtboard);
  const rest = all.filter((c) => !(c && c.type === DCArtboard));
  const sec = (ctx && sid && ctx.section(sid)) || {};
  // Must match DesignCanvas's srcKey computation exactly (it filters falsy
  // IDs), or onDelete persists a srcKey that DesignCanvas never recognizes.
  const allIds = artboards.map((a) => a.props.id ?? a.props.label).filter(Boolean);
  const srcKey = allIds.join('\x1f');
  const hidden = sec.srcKey === srcKey ? (sec.hidden || []) : [];
  const srcOrder = allIds.filter((k) => !hidden.includes(k));

  const order = React.useMemo(() => {
    const kept = (sec.order || []).filter((k) => srcOrder.includes(k));
    return [...kept, ...srcOrder.filter((k) => !kept.includes(k))];
  }, [sec.order, srcOrder.join('|')]);

  const byId = Object.fromEntries(artboards.map((a) => [a.props.id ?? a.props.label, a]));

  // marginBottom counter-scales so the on-screen gap between sections stays
  // constant — otherwise at low zoom the (world-space) gap collapses while
  // the screen-constant sectionhead below it doesn't, and the title reads as
  // belonging to the section above. paddingBottom below is just enough for
  // the 24px artboard-header (abs-positioned above each card) plus ~8px, so
  // the title sits tight against its own row at every zoom.
  return (
    <div data-dc-section={sid}
      style={{ marginBottom: 'calc(80px * var(--dc-inv-zoom, 1))', position: 'relative' }}>
      <div style={{ padding: '0 60px' }}>
        <div className="dc-sectionhead" style={{ paddingBottom: 36 }}>
          <DCEditable tag="div" value={sec.title ?? title}
            onChange={(v) => ctx && sid && ctx.patchSection(sid, { title: v })}
            style={{ fontSize: 20, fontWeight: 600, color: DC.title, letterSpacing: -0.4, marginBottom: 2, display: 'inline-block', lineHeight: '28px' }} />
          {subtitle && <div style={{ fontSize: 14, color: DC.subtitle, lineHeight: '22px' }}>{subtitle}</div>}
        </div>
      </div>
      <div style={{ display: 'flex', gap, padding: '0 60px', alignItems: 'flex-start', width: 'max-content' }}>
        {order.map((k) => (
          <DCArtboardFrame key={k} sectionId={sid} artboard={byId[k]} order={order}
            label={(sec.labels || {})[k] ?? byId[k].props.label}
            onRename={(v) => ctx && ctx.patchSection(sid, (x) => ({ labels: { ...x.labels, [k]: v } }))}
            onReorder={(next) => ctx && ctx.patchSection(sid, { order: next })}
            onDelete={() => ctx && ctx.patchSection(sid, (x) => ({
              hidden: [...(x.srcKey === srcKey ? (x.hidden || []) : []), k],
              srcKey,
            }))}
            onFocus={() => ctx && ctx.setFocus(`${sid}/${k}`)} />
        ))}
      </div>
      {rest}
    </div>
  );
}

// DCArtboard — marker; rendered by DCArtboardFrame via DCSection.
function DCArtboard() { return null; }

// Per-artboard export (kind: 'png' | 'html'). Both paths share the same
// self-contained clone: computed styles baked in, @font-face / <img> /
// inline-style background-image urls inlined as data URIs. PNG wraps the
// clone in foreignObject→canvas at 3× the artboard's natural width×height
// (same pipeline the host uses for page captures); HTML wraps it in a
// minimal standalone document. Both are independent of viewport zoom.
async function dcExport(node, w, h, name, kind) {
  try { await document.fonts.ready; } catch {}
  const toDataURL = (url) => fetch(url).then((r) => r.blob()).then((b) => new Promise((res) => {
    const fr = new FileReader(); fr.onload = () => res(fr.result); fr.onerror = () => res(url); fr.readAsDataURL(b);
  })).catch(() => url);

  // Collect @font-face rules. ss.cssRules throws SecurityError on
  // cross-origin sheets (e.g. fonts.googleapis.com) — in that case fetch
  // the CSS text directly (those endpoints send ACAO:*) and regex-extract
  // the blocks. @import and @media/@supports are walked so nested
  // @font-face rules aren't missed.
  const fontRules = [], pending = [], seen = new Set();
  const scrapeCss = (href) => {
    if (seen.has(href)) return; seen.add(href);
    pending.push(fetch(href).then((r) => r.text()).then((css) => {
      for (const m of css.match(/@font-face\s*{[^}]*}/g) || []) fontRules.push({ css: m, base: href });
      for (const m of css.matchAll(/@import\s+(?:url\()?['"]?([^'")\s;]+)/g))
        scrapeCss(new URL(m[1], href).href);
    }).catch(() => {}));
  };
  const walk = (rules, base) => {
    for (const r of rules) {
      if (r.type === CSSRule.FONT_FACE_RULE) fontRules.push({ css: r.cssText, base });
      else if (r.type === CSSRule.IMPORT_RULE && r.styleSheet) {
        const ibase = r.styleSheet.href || base;
        try { walk(r.styleSheet.cssRules, ibase); } catch { scrapeCss(ibase); }
      } else if (r.cssRules) walk(r.cssRules, base);
    }
  };
  for (const ss of document.styleSheets) {
    const base = ss.href || location.href;
    try { walk(ss.cssRules, base); } catch { if (ss.href) scrapeCss(ss.href); }
  }
  while (pending.length) await pending.shift();
  const fontCss = (await Promise.all(fontRules.map(async (rule) => {
    let out = rule.css, m; const re = /url\((['"]?)([^'")]+)\1\)/g;
    while ((m = re.exec(rule.css))) {
      if (m[2].indexOf('data:') === 0) continue;
      let abs; try { abs = new URL(m[2], rule.base).href; } catch { continue; }
      out = out.split(m[0]).join('url("' + await toDataURL(abs) + '")');
    }
    return out;
  }))).join('\n');

  const cloneStyled = (src) => {
    if (src.nodeType === 8 || (src.nodeType === 1 && src.tagName === 'SCRIPT')) return document.createTextNode('');
    const dst = src.cloneNode(false);
    if (src.nodeType === 1) {
      const cs = getComputedStyle(src); let txt = '';
      for (let i = 0; i < cs.length; i++) txt += cs[i] + ':' + cs.getPropertyValue(cs[i]) + ';';
      dst.setAttribute('style', txt + 'animation:none;transition:none;');
      if (src.tagName === 'CANVAS') try { const im = document.createElement('img'); im.src = src.toDataURL(); im.setAttribute('style', txt); return im; } catch {}
    }
    for (let c = src.firstChild; c; c = c.nextSibling) dst.appendChild(cloneStyled(c));
    return dst;
  };
  const clone = cloneStyled(node);
  clone.setAttribute('xmlns', 'http://www.w3.org/1999/xhtml');
  // Drop the card's own shadow/radius so the export is a flush w×h rect;
  // the artboard's own background (if any) is already in the computed style.
  clone.style.boxShadow = 'none'; clone.style.borderRadius = '0';

  const jobs = [];
  clone.querySelectorAll('img').forEach((el) => {
    const s = el.getAttribute('src');
    if (s && s.indexOf('data:') !== 0) jobs.push(toDataURL(el.src).then((d) => el.setAttribute('src', d)));
  });
  [clone, ...clone.querySelectorAll('*')].forEach((el) => {
    const bg = el.style.backgroundImage; if (!bg) return;
    let m; const re = /url\(["']?([^"')]+)["']?\)/g;
    while ((m = re.exec(bg))) {
      const tok = m[0], url = m[1];
      if (url.indexOf('data:') === 0) continue;
      jobs.push(toDataURL(url).then((d) => { el.style.backgroundImage = el.style.backgroundImage.split(tok).join('url("' + d + '")'); }));
    }
  });
  await Promise.all(jobs);

  const xml = new XMLSerializer().serializeToString(clone);
  const save = (blob, ext) => {
    if (!blob) return;
    const a = document.createElement('a');
    a.href = URL.createObjectURL(blob); a.download = name + '.' + ext; a.click();
    setTimeout(() => URL.revokeObjectURL(a.href), 1000);
  };

  if (kind === 'html') {
    const html = '<!doctype html><html><head><meta charset="utf-8"><title>' + name + '</title>' +
      (fontCss ? '<style>' + fontCss + '</style>' : '') +
      '</head><body style="margin:0">' + xml + '</body></html>';
    return save(new Blob([html], { type: 'text/html' }), 'html');
  }

  // PNG: the SVG's own width/height must be the output resolution — an
  // <img>-loaded SVG rasterizes at its intrinsic size, so sizing it at 1×
  // and ctx.scale()-ing up would just upscale a 1× bitmap. viewBox maps the
  // w×h foreignObject onto the px·w × px·h SVG canvas so the browser renders
  // the HTML at full resolution.
  const px = 3;
  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="' + w * px + '" height="' + h * px +
    '" viewBox="0 0 ' + w + ' ' + h + '"><foreignObject width="' + w + '" height="' + h + '">' +
    (fontCss ? '<style><![CDATA[' + fontCss + ']]></style>' : '') + xml + '</foreignObject></svg>';
  const img = new Image();
  await new Promise((res, rej) => {
    img.onload = res; img.onerror = () => rej(new Error('svg load failed'));
    img.src = 'data:image/svg+xml;charset=utf-8,' + encodeURIComponent(svg);
  });
  const cv = document.createElement('canvas');
  cv.width = w * px; cv.height = h * px;
  cv.getContext('2d').drawImage(img, 0, 0);
  cv.toBlob((blob) => save(blob, 'png'), 'image/png');
}

function DCArtboardFrame({ sectionId, artboard, label, order, onRename, onReorder, onFocus, onDelete }) {
  // Read height off the raw props (not a destructure default) so an *absent*
  // height can opt into auto-grow while an explicit height={N} — even 480 —
  // still means a fixed, content-clipping frame (thumbnail semantics).
  const { id: rawId, label: rawLabel, width = 260, chromeless = false, children, style = {} } = artboard.props;
  const hasHeight = artboard.props.height != null;
  const height = hasHeight ? artboard.props.height : undefined;
  const id = rawId ?? rawLabel;
  const ref = React.useRef(null);
  const cardRef = React.useRef(null);
  const menuRef = React.useRef(null);
  const [menuOpen, setMenuOpen] = React.useState(false);
  const [confirming, setConfirming] = React.useState(false);

  // ⋯ menu: close on any outside pointerdown. Two-click delete lives inside
  // the menu — first click arms the row, second commits; closing disarms.
  React.useEffect(() => {
    if (!menuOpen) { setConfirming(false); return; }
    const off = (e) => { if (!menuRef.current || !menuRef.current.contains(e.target)) setMenuOpen(false); };
    document.addEventListener('pointerdown', off, true);
    return () => document.removeEventListener('pointerdown', off, true);
  }, [menuOpen]);

  const doExport = (kind) => {
    setMenuOpen(false);
    if (!cardRef.current) return;
    // Unicode-aware sanitize: keep letters (incl. CJK/accented), digits,
    // whitespace, dot/underscore/hyphen; collapse everything else to '_'.
    // ASCII-only \w would strip Chinese labels down to a bare '_'.
    const name = String(label || id || 'artboard').replace(/[^\p{L}\p{N}\s._-]+/gu, '_');
    const ew = cardRef.current.offsetWidth || width;
    const eh = cardRef.current.offsetHeight || height;
    dcExport(cardRef.current, ew, eh, name, kind)
      .catch((e) => console.error('[design-canvas] export failed:', e));
  };

  // Live drag-reorder: dragged card sticks to cursor; siblings slide into
  // their would-be slots in real time via transforms. DOM order only
  // changes on drop.
  const onGripDown = (e) => {
    e.preventDefault(); e.stopPropagation();
    const me = ref.current;
    // translateX is applied in local (pre-scale) space but pointer deltas and
    // getBoundingClientRect().left are screen-space — divide by the viewport's
    // current scale so the dragged card tracks the cursor at any zoom level.
    const scale = me.getBoundingClientRect().width / me.offsetWidth || 1;
    const peers = Array.from(document.querySelectorAll(`[data-dc-section="${sectionId}"] [data-dc-slot]`));
    const homes = peers.map((el) => ({ el, id: el.dataset.dcSlot, x: el.getBoundingClientRect().left }));
    const slotXs = homes.map((h) => h.x);
    const startIdx = order.indexOf(id);
    const startX = e.clientX;
    let liveOrder = order.slice();
    me.classList.add('dc-dragging');

    const layout = () => {
      for (const h of homes) {
        if (h.id === id) continue;
        const slot = liveOrder.indexOf(h.id);
        h.el.style.transform = `translateX(${(slotXs[slot] - h.x) / scale}px)`;
      }
    };

    const move = (ev) => {
      const dx = ev.clientX - startX;
      me.style.transform = `translateX(${dx / scale}px)`;
      const cur = homes[startIdx].x + dx;
      let nearest = 0, best = Infinity;
      for (let i = 0; i < slotXs.length; i++) {
        const d = Math.abs(slotXs[i] - cur);
        if (d < best) { best = d; nearest = i; }
      }
      if (liveOrder.indexOf(id) !== nearest) {
        liveOrder = order.filter((k) => k !== id);
        liveOrder.splice(nearest, 0, id);
        layout();
      }
    };

    const up = () => {
      document.removeEventListener('pointermove', move);
      document.removeEventListener('pointerup', up);
      const finalSlot = liveOrder.indexOf(id);
      me.classList.remove('dc-dragging');
      me.style.transform = `translateX(${(slotXs[finalSlot] - homes[startIdx].x) / scale}px)`;
      // After the settle transition, kill transitions + clear transforms +
      // commit the reorder in the same frame so there's no visual snap-back.
      setTimeout(() => {
        for (const h of homes) { h.el.style.transition = 'none'; h.el.style.transform = ''; }
        if (liveOrder.join('|') !== order.join('|')) onReorder(liveOrder);
        requestAnimationFrame(() => requestAnimationFrame(() => {
          for (const h of homes) h.el.style.transition = '';
        }));
      }, 180);
    };
    document.addEventListener('pointermove', move);
    document.addEventListener('pointerup', up);
  };

  return (
    <div ref={ref} data-dc-slot={id} style={{ position: 'relative', flexShrink: 0 }}>
      {/* Desktop stops pointerdown so header interactions never start a
          bg-pan; mobile pans FROM chrome too (slop arbitration keeps label
          taps working), so the event must bubble to the viewport there. */}
      <div className="dc-header" data-miaoda-chrome="" style={{ color: DC.label }} onPointerDown={dcIsMobile ? undefined : (e) => e.stopPropagation()}>
        <div className="dc-labelrow">
          <div className="dc-grip" onPointerDown={dcIsMobile ? undefined : onGripDown} title="Drag to reorder">
            <svg width="9" height="13" viewBox="0 0 9 13" fill="currentColor"><circle cx="2" cy="2" r="1.1"/><circle cx="7" cy="2" r="1.1"/><circle cx="2" cy="6.5" r="1.1"/><circle cx="7" cy="6.5" r="1.1"/><circle cx="2" cy="11" r="1.1"/><circle cx="7" cy="11" r="1.1"/></svg>
          </div>
          <div className="dc-labeltext" onClick={onFocus} title="Click to focus">
            <DCEditable value={label} onChange={onRename} onClick={(e) => e.stopPropagation()}
              style={{ fontSize: 14, fontWeight: 300, color: DC.label, lineHeight: '22px' }} />
          </div>
        </div>
        <div className="dc-btns">
          <div ref={menuRef} style={{ position: 'relative' }}>
            <button className="dc-kebab" title="More" onClick={() => setMenuOpen((o) => !o)}>
              <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor"><circle cx="2.5" cy="6" r="1.1"/><circle cx="6" cy="6" r="1.1"/><circle cx="9.5" cy="6" r="1.1"/></svg>
            </button>
            {menuOpen && (
              <div className="dc-menu" onPointerDown={(e) => e.stopPropagation()}>
                <button onClick={() => doExport('png')}>下载 PNG</button>
                <button onClick={() => doExport('html')}>下载 HTML</button>
                <button className="dc-danger"
                  onClick={() => { if (confirming) { setMenuOpen(false); onDelete(); } else setConfirming(true); }}>
                  {confirming ? '确认删除' : '删除'}
                </button>
              </div>
            )}
          </div>
          <button className="dc-expand" onClick={onFocus} title="Focus">
            <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round"><path d="M7 1h4v4M5 11H1V7M11 1L7.5 4.5M1 11l3.5-3.5"/></svg>
          </button>
        </div>
      </div>
      <div ref={cardRef} className={"dc-card" + (chromeless ? ' chromeless' : '')}
        style={{ ...(chromeless ? {} : {
          width,
          // explicit height → fixed frame (overflow:hidden clips a tall page);
          // no height → the box grows to its content height. overflow:hidden
          // stays either way so the rounded corners clip and content wider than
          // the frame is trimmed to `width`; with auto height nothing is clipped
          // vertically because the box is exactly the content height.
          ...(hasHeight ? { height } : {}),
          borderRadius: 4, border: '1px solid #DEE0E3', overflow: 'hidden', background: '#fff',
        }), ...style }}>
        {children || <div style={{ minHeight: 160, height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#bbb', fontSize: 13, fontFamily: DC.font }}>{id}</div>}
      </div>
    </div>
  );
}

// Inline rename — commits on blur or Enter.
function DCEditable({ value, onChange, style, tag = 'span', onClick }) {
  const T = tag;
  // Mobile is browse-only: render plain text — no contentEditable (a tap
  // would pop the soft keyboard), no stopPropagation (pans start on labels
  // too), and no onClick swallow (desktop uses it to keep an edit-click from
  // bubbling; on mobile the tap should bubble so a label tap opens focus).
  if (dcIsMobile) {
    return <T className="dc-editable" style={style}>{value}</T>;
  }
  return (
    <T className="dc-editable" contentEditable suppressContentEditableWarning
      onClick={onClick}
      onPointerDown={(e) => e.stopPropagation()}
      onBlur={(e) => onChange && onChange(e.currentTarget.textContent)}
      onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); e.currentTarget.blur(); } }}
      style={style}>{value}</T>
  );
}

// ─────────────────────────────────────────────────────────────
// Focus mode — overlay one artboard; ←/→ within section, ↑/↓ across
// sections, Esc or backdrop click to exit.
// ─────────────────────────────────────────────────────────────
function DCFocusOverlay({ entry, sectionMeta, sectionOrder }) {
  const ctx = React.useContext(DCCtx);
  const { sectionId, artboard } = entry;
  const meta = sectionMeta[sectionId];
  const peers = meta.slotIds;
  const aid = artboard.props.id ?? artboard.props.label;
  const idx = peers.indexOf(aid);
  const secIdx = sectionOrder.indexOf(sectionId);

  const go = (d) => { const n = peers[(idx + d + peers.length) % peers.length]; if (n) ctx.setFocus(`${sectionId}/${n}`); };
  const goSection = (d) => {
    // Sections whose artboards are all deleted have slotIds:[] — step past
    // them to the next non-empty section so ↑/↓ doesn't dead-end.
    const n = sectionOrder.length;
    for (let i = 1; i < n; i++) {
      const ns = sectionOrder[(((secIdx + d * i) % n) + n) % n];
      const first = sectionMeta[ns] && sectionMeta[ns].slotIds[0];
      if (first) { ctx.setFocus(`${ns}/${first}`); return; }
    }
  };

  React.useEffect(() => {
    const k = (e) => {
      if (e.key === 'ArrowLeft') { e.preventDefault(); go(-1); }
      if (e.key === 'ArrowRight') { e.preventDefault(); go(1); }
      if (e.key === 'ArrowUp') { e.preventDefault(); goSection(-1); }
      if (e.key === 'ArrowDown') { e.preventDefault(); goSection(1); }
    };
    document.addEventListener('keydown', k);
    return () => document.removeEventListener('keydown', k);
  });

  const { width = 260, chromeless = false, children } = artboard.props;
  const hasHeight = artboard.props.height != null;
  const height = hasHeight ? artboard.props.height : undefined;
  // A fixed-frame card (non-chromeless WITH an explicit height) uses width/
  // height directly. Otherwise the card has NO fixed height and its rendered
  // size describes the content, not a frame — either a chromeless artboard
  // (device frame / auto layout, both axes intrinsic) or a non-chromeless
  // artboard that omitted height and grows to its content (frame `width`, auto
  // height). Fitting such content to a default height would wrap it in an
  // undersized clip box and magnify the clipped slice — so measure the real
  // rendered size first and fit-scale to that, mirroring the canvas card.
  const autoSize = chromeless || !hasHeight;
  const measureRef = React.useRef(null);
  const [nat, setNat] = React.useState(null); // { aid, w, h } measured natural size
  React.useLayoutEffect(() => {
    if (!autoSize) return;
    const el = measureRef.current;
    if (el) setNat({ aid, w: el.offsetWidth, h: el.offsetHeight });
  }, [aid, autoSize]);
  const useMeasured = autoSize && nat && nat.aid === aid && nat.w > 0;
  const needsMeasure = autoSize && !useMeasured;
  const cw = useMeasured ? nat.w : width;
  const ch = useMeasured ? nat.h : (height ?? 480);

  const [vp, setVp] = React.useState({ w: window.innerWidth, h: window.innerHeight });
  React.useEffect(() => { const r = () => setVp({ w: window.innerWidth, h: window.innerHeight }); window.addEventListener('resize', r); return () => window.removeEventListener('resize', r); }, []);
  // Fill the viewport leaving a safe margin — 70px left/right, 32px top/bottom.
  // Take the smaller of the width-fit / height-fit ratios so the whole artboard
  // stays fully visible; no upper cap, so small frames still fill the screen.
  const MARGIN_X = 70;
  const MARGIN_Y = 32;
  const scale = Math.max(0.05, Math.min((vp.w - MARGIN_X * 2) / cw, (vp.h - MARGIN_Y * 2) / ch));

  // Chrome (arrows / close / dots) is hidden until the cursor sits on the
  // dark backdrop (anywhere that isn't the interactive content). Hiding also
  // sets pointer-events:none so hidden controls are click-through and never
  // block content interaction or a backdrop-click exit.
  const [chromeVisible, setChromeVisible] = React.useState(false);
  const contentRef = React.useRef(null);
  const chromeStyle = { opacity: chromeVisible ? 1 : 0, pointerEvents: chromeVisible ? 'auto' : 'none' };
  const Arrow = ({ dir, onClick }) => (
    <button onClick={(e) => { e.stopPropagation(); onClick(); }}
      style={{ position: 'absolute', top: '50%', [dir]: 20, transform: 'translateY(-50%)',
        border: 'none', background: 'rgba(255,255,255,.08)', color: 'rgb(255,255,255)',
        width: 36, height: 36, borderRadius: 22, fontSize: 16, cursor: 'pointer',
        display: 'flex', alignItems: 'center', justifyContent: 'center',
        transition: 'background .15s, opacity .18s ease', ...chromeStyle }}
      onMouseEnter={(e) => (e.currentTarget.style.background = 'rgba(255,255,255,.18)')}
      onMouseLeave={(e) => (e.currentTarget.style.background = 'rgba(255,255,255,.08)')}>
      <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
        <path d={dir === 'left' ? 'M10.8619 1.52925C11.1223 1.7896 11.1223 2.21171 10.8619 2.47206L5.33333 8.00065L10.8619 13.5292C11.1223 13.7896 11.1223 14.2117 10.8619 14.4721C10.6016 14.7324 10.1795 14.7324 9.91912 14.4721L4.39052 8.94346C3.86983 8.42276 3.86982 7.57854 4.39052 7.05784L9.91912 1.52925C10.1795 1.2689 10.6016 1.2689 10.8619 1.52925Z' : 'M5.13765 14.4721C4.8773 14.2117 4.8773 13.7896 5.13765 13.5292L10.6662 8.00065L5.13765 2.47206C4.8773 2.21171 4.8773 1.7896 5.13764 1.52925C5.39799 1.2689 5.8201 1.2689 6.08045 1.52925L11.609 7.05784C12.1297 7.57854 12.1298 8.42276 11.6091 8.94346L6.08045 14.4721C5.82011 14.7324 5.398 14.7324 5.13765 14.4721Z'} fill="currentColor" /></svg>
    </button>
  );

  // Portal to body so position:fixed is the real viewport regardless of any
  // transform on DesignCanvas's ancestors (including the canvas zoom itself).
  return ReactDOM.createPortal(
    <div onClick={() => ctx.setFocus(null)}
      onMouseMove={(e) => setChromeVisible(!(contentRef.current && contentRef.current.contains(e.target)))}
      onMouseLeave={() => setChromeVisible(false)}
      onWheel={(e) => { if (!(contentRef.current && contentRef.current.contains(e.target))) e.preventDefault(); }}
      style={{ position: 'fixed', inset: 0, zIndex: 100, background: 'rgba(0,0,0,.8)', backdropFilter: 'blur(4px)',
        fontFamily: DC.font, display: 'flex', alignItems: 'center', justifyContent: 'center' }}>

      {/* content fills the viewport to its safe margin (70px left/right, 32px
          top/bottom), centered — interactive & scrollable. Only the content
          stops propagation, so any backdrop click (the dark margin around it)
          exits focus. */}
      <div ref={contentRef} className="dc-focus-content" onClick={(e) => e.stopPropagation()}
        style={{ width: cw * scale, height: ch * scale, position: 'relative',
          // hidden until the auto-size measure pass below reports the real size
          visibility: needsMeasure ? 'hidden' : 'visible' }}>
        {/* Auto-size cards render a hidden measure pass first, then re-render
            scaled. Chromeless measures both axes (inline-block → intrinsic
            size); a non-chromeless auto card keeps its frame `width` and lets
            height run natural. Card chrome (bg / radius / shadow / overflow:auto)
            is added only for a non-chromeless box — matching the canvas card —
            giving it a scroll viewport for anything it still clips; scrollbars
            are hidden by the .dc-focus-content CSS. A chromeless box carries
            none of it, so its content owns its look. */}
        <div ref={measureRef} style={needsMeasure
          ? (chromeless ? { display: 'inline-block' } : { width })
          : { width: cw, height: ch, transform: `scale(${scale})`, transformOrigin: 'top left',
            ...(chromeless ? {} : { background: '#fff', borderRadius: 2, overflow: 'auto', boxShadow: '0 20px 80px rgba(0,0,0,.4)' }) }}>
          {children || <div style={{ minHeight: 160, height: '100%', display: 'flex', alignItems: 'center', justifyContent: 'center', color: '#bbb' }}>{aid}</div>}
        </div>
      </div>

      {/* close — top-right, revealed on backdrop hover */}
      <button onClick={() => ctx.setFocus(null)}
        onMouseEnter={(e) => (e.currentTarget.style.background = 'rgba(255,255,255,.18)')}
        onMouseLeave={(e) => (e.currentTarget.style.background = 'rgba(255,255,255,.08)')}
        style={{ position: 'absolute', top: 20, right: 24, border: 'none', background: 'rgba(255,255,255,.08)', color: 'rgb(255,255,255)',
          width: 36, height: 36, borderRadius: 22, fontSize: 16, cursor: 'pointer', lineHeight: 1,
          display: 'flex', alignItems: 'center', justifyContent: 'center',
          transition: 'background .12s, opacity .18s ease', ...chromeStyle }}>
          <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M13.4713 13.4722C13.7301 13.2134 13.732 12.7957 13.4732 12.5369L8.93693 8.00064L13.4731 3.46444C13.7319 3.20562 13.7301 2.78788 13.4713 2.52907C13.2125 2.27026 12.7947 2.26838 12.5359 2.5272C12.2771 2.78601 7.99969 7.0634 7.99969 7.0634L3.46345 2.52716C3.20464 2.26835 2.7869 2.27022 2.52809 2.52903C2.26928 2.78784 2.2674 3.20558 2.52621 3.4644L7.06246 8.00064L2.52618 12.5369C2.26737 12.7957 2.26924 13.2135 2.52806 13.4723C2.78687 13.7311 3.20461 13.733 3.46342 13.4742L7.99969 8.93788L12.5359 13.4741C12.7947 13.7329 13.2125 13.731 13.4713 13.4722Z" fill="currentColor"/>
          </svg>
        </button>

      <Arrow dir="left" onClick={() => go(-1)} />
      <Arrow dir="right" onClick={() => go(1)} />

      {/* dots — revealed on backdrop hover */}
      <div onClick={(e) => e.stopPropagation()}
        style={{ position: 'absolute', bottom: 13, left: '50%', transform: 'translateX(-50%)', display: 'flex', gap: 8,
          transition: 'opacity .18s ease', ...chromeStyle }}>
        {peers.map((p, i) => (
          <button key={p} onClick={() => ctx.setFocus(`${sectionId}/${p}`)}
            style={{ border: 'none', padding: 0, cursor: 'pointer', width: 6, height: 6, borderRadius: 3,
              background: i === idx ? '#fff' : 'rgba(255,255,255,.3)' }} />
        ))}
      </div>
    </div>,
    document.body,
  );
}

// ─────────────────────────────────────────────────────────────
// Post-it — absolute-positioned sticky note
// ─────────────────────────────────────────────────────────────
function DCPostIt({ children, top, left, right, bottom, rotate = -2, width = 180 }) {
  return (
    <div style={{
      position: 'absolute', top, left, right, bottom, width,
      background: DC.postitBg, padding: '14px 16px',
      fontFamily: '"Comic Sans MS", "Marker Felt", "Segoe Print", cursive',
      fontSize: 14, lineHeight: 1.4, color: DC.postitText,
      boxShadow: '0 2px 8px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08)',
      transform: `rotate(${rotate}deg)`,
      zIndex: 5,
    }}>{children}</div>
  );
}

Object.assign(window, { DesignCanvas, DCSection, DCArtboard, DCPostIt });

/* BEGIN USAGE */
// iOS.jsx — Simplified iOS 26 (Liquid Glass) device frame
// Based on the iOS 26 UI Kit + Figma status bar spec. No assets, no deps.
// Exports (to window): IOSDevice, IOSStatusBar, IOSList, IOSListRow, IOSKeyboard
//
// Usage — wrap your screen content in <IOSDevice> to get the bezel, status bar
// and home indicator (props: width=402, height=874, dark, keyboard):
//
//   <IOSDevice>
//     ...your screen content...
//   </IOSDevice>
//   <IOSDevice dark keyboard>…</IOSDevice>
//   <IOSDevice width={390} height={844}>…</IOSDevice>   // smaller device size
//
// Safe areas — REQUIRED on every screen. The status bar (top) and home
// indicator (bottom) float OVER your content; inset it or it overlaps them.
//   --ios-safe-top     top inset (Dynamic Island + status bar)
//   --ios-safe-bottom  bottom inset (home indicator)
/* END USAGE */

// ─────────────────────────────────────────────────────────────
// Status bar
// ─────────────────────────────────────────────────────────────
function IOSStatusBar({ dark = false, time = '9:41' }) {
  const c = dark ? '#fff' : '#000';
  return (
    <div style={{
      display: 'flex', gap: 154, alignItems: 'center', justifyContent: 'center',
      padding: '21px 24px 19px', boxSizing: 'border-box',
      position: 'relative', zIndex: 20, width: '100%',
    }}>
      <div style={{ flex: 1, height: 22, display: 'flex', alignItems: 'center', justifyContent: 'center', paddingTop: 1.5 }}>
        <span style={{
          fontFamily: '-apple-system, "SF Pro", system-ui', fontWeight: 590,
          fontSize: 17, lineHeight: '22px', color: c,
        }}>{time}</span>
      </div>
      <div style={{ flex: 1, height: 22, display: 'flex', alignItems: 'center', justifyContent: 'center', gap: 7, paddingTop: 1, paddingRight: 1 }}>
        <svg width="19" height="12" viewBox="0 0 19 12">
          <rect x="0" y="7.5" width="3.2" height="4.5" rx="0.7" fill={c}/>
          <rect x="4.8" y="5" width="3.2" height="7" rx="0.7" fill={c}/>
          <rect x="9.6" y="2.5" width="3.2" height="9.5" rx="0.7" fill={c}/>
          <rect x="14.4" y="0" width="3.2" height="12" rx="0.7" fill={c}/>
        </svg>
        <svg width="17" height="12" viewBox="0 0 17 12">
          <path d="M8.5 3.2C10.8 3.2 12.9 4.1 14.4 5.6L15.5 4.5C13.7 2.7 11.2 1.5 8.5 1.5C5.8 1.5 3.3 2.7 1.5 4.5L2.6 5.6C4.1 4.1 6.2 3.2 8.5 3.2Z" fill={c}/>
          <path d="M8.5 6.8C9.9 6.8 11.1 7.3 12 8.2L13.1 7.1C11.8 5.9 10.2 5.1 8.5 5.1C6.8 5.1 5.2 5.9 3.9 7.1L5 8.2C5.9 7.3 7.1 6.8 8.5 6.8Z" fill={c}/>
          <circle cx="8.5" cy="10.5" r="1.5" fill={c}/>
        </svg>
        <svg width="27" height="13" viewBox="0 0 27 13">
          <rect x="0.5" y="0.5" width="23" height="12" rx="3.5" stroke={c} strokeOpacity="0.35" fill="none"/>
          <rect x="2" y="2" width="20" height="9" rx="2" fill={c}/>
          <path d="M25 4.5V8.5C25.8 8.2 26.5 7.2 26.5 6.5C26.5 5.8 25.8 4.8 25 4.5Z" fill={c} fillOpacity="0.4"/>
        </svg>
      </div>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Grouped list (inset card, r:26) + row (52px)
// ─────────────────────────────────────────────────────────────
function IOSListRow({ title, detail, icon, chevron = true, isLast = false, dark = false }) {
  const text = dark ? '#fff' : '#000';
  const sec = dark ? 'rgba(235,235,245,0.6)' : 'rgba(60,60,67,0.6)';
  const ter = dark ? 'rgba(235,235,245,0.3)' : 'rgba(60,60,67,0.3)';
  const sep = dark ? 'rgba(84,84,88,0.65)' : 'rgba(60,60,67,0.12)';
  return (
    <div style={{
      display: 'flex', alignItems: 'center', minHeight: 52,
      padding: '0 16px', position: 'relative',
      fontFamily: '-apple-system, system-ui', fontSize: 17,
      letterSpacing: -0.43,
    }}>
      {icon && (
        <div style={{
          width: 30, height: 30, borderRadius: 7, background: icon,
          marginRight: 12, flexShrink: 0,
        }} />
      )}
      <div style={{ flex: 1, color: text }}>{title}</div>
      {detail && <span style={{ color: sec, marginRight: 6 }}>{detail}</span>}
      {chevron && (
        <svg width="8" height="14" viewBox="0 0 8 14" style={{ flexShrink: 0 }}>
          <path d="M1 1l6 6-6 6" stroke={ter} strokeWidth="2" fill="none" strokeLinecap="round" strokeLinejoin="round"/>
        </svg>
      )}
      {!isLast && (
        <div style={{
          position: 'absolute', bottom: 0, right: 0,
          left: icon ? 58 : 16, height: 0.5, background: sep,
        }} />
      )}
    </div>
  );
}

function IOSList({ header, children, dark = false }) {
  const hc = dark ? 'rgba(235,235,245,0.6)' : 'rgba(60,60,67,0.6)';
  const bg = dark ? '#1C1C1E' : '#fff';
  return (
    <div>
      {header && (
        <div style={{
          fontFamily: '-apple-system, system-ui', fontSize: 13,
          color: hc, textTransform: 'uppercase',
          padding: '8px 36px 6px', letterSpacing: -0.08,
        }}>{header}</div>
      )}
      <div style={{
        background: bg, borderRadius: 26,
        margin: '0 16px', overflow: 'hidden',
      }}>{children}</div>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Device frame
// ─────────────────────────────────────────────────────────────
function IOSDevice({
  children, width = 402, height = 874, dark = false,
  keyboard = false,
}) {
  return (
    <div style={{
      width, height, borderRadius: 48, overflow: 'hidden',
      position: 'relative', background: dark ? '#000' : '#F2F2F7',
      border: '1px solid #DEE0E3',
      fontFamily: '-apple-system, system-ui, sans-serif',
      WebkitFontSmoothing: 'antialiased',
      '--ios-safe-top': '62px',
      '--ios-safe-bottom': '34px',
    }}>
      {/* dynamic island */}
      <div style={{
        position: 'absolute', top: 11, left: '50%', transform: 'translateX(-50%)',
        width: 126, height: 37, borderRadius: 24, background: '#000', zIndex: 50,
      }} />
      {/* status bar (absolute) */}
      <div style={{ position: 'absolute', top: 0, left: 0, right: 0, zIndex: 10 }}>
        <IOSStatusBar dark={dark} />
      </div>
      {/* content */}
      <div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
        <div style={{ flex: 1, overflow: 'auto' }}>{children}</div>
        {keyboard && <IOSKeyboard dark={dark} />}
      </div>
      {/* home indicator — always on top */}
      <div style={{
        position: 'absolute', bottom: 0, left: 0, right: 0, zIndex: 60,
        height: 34, display: 'flex', justifyContent: 'center', alignItems: 'flex-end',
        paddingBottom: 8, pointerEvents: 'none',
      }}>
        <div style={{
          width: 139, height: 5, borderRadius: 100,
          background: dark ? 'rgba(255,255,255,0.7)' : 'rgba(0,0,0,0.25)',
        }} />
      </div>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Keyboard — iOS 26 liquid glass
// ─────────────────────────────────────────────────────────────
function IOSKeyboard({ dark = false }) {
  const glyph = dark ? 'rgba(255,255,255,0.7)' : '#595959';
  const sugg = dark ? 'rgba(255,255,255,0.6)' : '#333';
  const keyBg = dark ? 'rgba(255,255,255,0.22)' : 'rgba(255,255,255,0.85)';

  // special-key icons
  const icons = {
    shift: <svg width="19" height="17" viewBox="0 0 19 17"><path d="M9.5 1L1 9.5h4.5V16h8V9.5H18L9.5 1z" fill={glyph}/></svg>,
    del: <svg width="23" height="17" viewBox="0 0 23 17"><path d="M7 1h13a2 2 0 012 2v11a2 2 0 01-2 2H7l-6-7.5L7 1z" fill="none" stroke={glyph} strokeWidth="1.6" strokeLinejoin="round"/><path d="M10 5l7 7M17 5l-7 7" stroke={glyph} strokeWidth="1.6" strokeLinecap="round"/></svg>,
    ret: <svg width="20" height="14" viewBox="0 0 20 14"><path d="M18 1v6H4m0 0l4-4M4 7l4 4" fill="none" stroke="#fff" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round"/></svg>,
  };

  const key = (content, { w, flex, ret, fs = 25, k } = {}) => (
    <div key={k} style={{
      height: 42, borderRadius: 8.5,
      flex: flex ? 1 : undefined, width: w, minWidth: 0,
      background: ret ? '#08f' : keyBg,
      boxShadow: '0 1px 0 rgba(0,0,0,0.075)',
      display: 'flex', alignItems: 'center', justifyContent: 'center',
      fontFamily: '-apple-system, "SF Compact", system-ui',
      fontSize: fs, fontWeight: 458, color: ret ? '#fff' : glyph,
    }}>{content}</div>
  );

  const row = (keys, pad = 0) => (
    <div style={{ display: 'flex', gap: 6.5, justifyContent: 'center', padding: `0 ${pad}px` }}>
      {keys.map(l => key(l, { flex: true, k: l }))}
    </div>
  );

  return (
    <div style={{
      position: 'relative', zIndex: 15, borderRadius: 27, overflow: 'hidden',
      padding: '11px 0 2px',
      display: 'flex', flexDirection: 'column', alignItems: 'center',
      boxShadow: dark
        ? '0 -2px 20px rgba(0,0,0,0.09)'
        : '0 -1px 6px rgba(0,0,0,0.018), 0 -3px 20px rgba(0,0,0,0.012)',
    }}>
      {/* liquid glass bg — same recipe as nav pills */}
      <div style={{
        position: 'absolute', inset: 0, borderRadius: 27,
        backdropFilter: 'blur(12px) saturate(180%)',
        WebkitBackdropFilter: 'blur(12px) saturate(180%)',
        background: dark ? 'rgba(120,120,128,0.14)' : 'rgba(255,255,255,0.25)',
      }} />
      <div style={{
        position: 'absolute', inset: 0, borderRadius: 27,
        boxShadow: dark
          ? 'inset 1.5px 1.5px 1px rgba(255,255,255,0.15)'
          : 'inset 1.5px 1.5px 1px rgba(255,255,255,0.7), inset -1px -1px 1px rgba(255,255,255,0.4)',
        border: dark ? '0.5px solid rgba(255,255,255,0.15)' : '0.5px solid rgba(0,0,0,0.06)',
        pointerEvents: 'none',
      }} />

      {/* autocorrect bar */}
      <div style={{
        display: 'flex', gap: 20, alignItems: 'center',
        padding: '8px 22px 13px', width: '100%', boxSizing: 'border-box',
        position: 'relative',
      }}>
        {['"The"', 'the', 'to'].map((w, i) => (
          <React.Fragment key={i}>
            {i > 0 && <div style={{ width: 1, height: 25, background: '#ccc', opacity: 0.3 }} />}
            <div style={{
              flex: 1, textAlign: 'center',
              fontFamily: '-apple-system, system-ui', fontSize: 17,
              color: sugg, letterSpacing: -0.43, lineHeight: '22px',
            }}>{w}</div>
          </React.Fragment>
        ))}
      </div>

      {/* key layout */}
      <div style={{
        display: 'flex', flexDirection: 'column', gap: 13,
        padding: '0 6.5px', width: '100%', boxSizing: 'border-box',
        position: 'relative',
      }}>
        {row(['q','w','e','r','t','y','u','i','o','p'])}
        {row(['a','s','d','f','g','h','j','k','l'], 20)}
        <div style={{ display: 'flex', gap: 14.25, alignItems: 'center' }}>
          {key(icons.shift, { w: 45, k: 'shift' })}
          <div style={{ display: 'flex', gap: 6.5, flex: 1 }}>
            {['z','x','c','v','b','n','m'].map(l => key(l, { flex: true, k: l }))}
          </div>
          {key(icons.del, { w: 45, k: 'del' })}
        </div>
        <div style={{ display: 'flex', gap: 6, alignItems: 'center' }}>
          {key('ABC', { w: 92.25, fs: 18, k: 'abc' })}
          {key('', { flex: true, k: 'space' })}
          {key(icons.ret, { w: 92.25, ret: true, k: 'ret' })}
        </div>
      </div>

      {/* bottom spacer (emoji+mic area, icons omitted) */}
      <div style={{ height: 56, width: '100%', position: 'relative' }} />
    </div>
  );
}

Object.assign(window, {
  IOSDevice, IOSStatusBar, IOSList, IOSListRow, IOSKeyboard,
});

/* BEGIN USAGE */
// MacOS.jsx — Simplified macOS Tahoe (Liquid Glass) window
// Based on the macOS Tahoe UI Kit. No image assets, no dependencies.
// Exports (to window): MacWindow, MacSidebar, MacSidebarItem, MacSidebarHeader, MacToolbar, MacGlass, MacTrafficLights
//
// Usage — wrap your app content in <MacWindow> to get the window chrome
// (traffic lights + titlebar). Props: width, height, title, sidebar (pass a
// <MacSidebar> element); compose MacToolbar/MacGlass inside as needed:
//
//   <MacWindow width={980} height={620} title="Documents"
//              sidebar={<MacSidebar>…</MacSidebar>}>
//     ...your app content...
//   </MacWindow>
/* END USAGE */

const MAC_FONT = '-apple-system, BlinkMacSystemFont, "SF Pro", "Helvetica Neue", sans-serif';

// ─────────────────────────────────────────────────────────────
// Liquid glass primitive — blur + white tint + inset highlight
// ─────────────────────────────────────────────────────────────
function MacGlass({ children, radius = 296, dark = false, style = {} }) {
  return (
    <div style={{ position: 'relative', borderRadius: radius, ...style }}>
      <div style={{
        position: 'absolute', inset: 0, borderRadius: radius,
        background: dark ? 'rgba(255,255,255,0.08)' : 'rgba(255,255,255,0.35)',
        backdropFilter: 'blur(40px) saturate(180%)',
        WebkitBackdropFilter: 'blur(40px) saturate(180%)',
        border: dark ? '0.5px solid rgba(255,255,255,0.12)' : '0.5px solid rgba(255,255,255,0.6)',
        boxShadow: dark
          ? '0 8px 40px rgba(0,0,0,0.2)'
          : '0 8px 40px rgba(0,0,0,0.08), inset 0 1px 0 rgba(255,255,255,0.4)',
      }} />
      <div style={{ position: 'relative', zIndex: 1 }}>{children}</div>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Traffic lights (14px, Tahoe colors)
// ─────────────────────────────────────────────────────────────
function MacTrafficLights({ style = {} }) {
  const dot = (bg) => (
    <div style={{
      width: 14, height: 14, borderRadius: '50%', background: bg,
      border: '0.5px solid rgba(0,0,0,0.1)',
    }} />
  );
  return (
    <div style={{ display: 'flex', gap: 9, alignItems: 'center', padding: 1, ...style }}>
      {dot('#ff736a')}{dot('#febc2e')}{dot('#19c332')}
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Toolbar — title + single glass pill icon
// ─────────────────────────────────────────────────────────────
function MacToolbar({ title = 'Folder' }) {
  return (
    <div style={{
      display: 'flex', gap: 8, alignItems: 'center', padding: 8, flexShrink: 0,
    }}>
      {/* title */}
      <div style={{
        fontFamily: MAC_FONT, fontSize: 15, fontWeight: 700,
        color: 'rgba(0,0,0,0.85)', whiteSpace: 'nowrap', paddingLeft: 8,
      }}>{title}</div>
      <div style={{ flex: 1 }} />
      {/* single action */}
      <MacGlass>
        <div style={{
          width: 36, height: 36, display: 'flex',
          alignItems: 'center', justifyContent: 'center',
        }}>
          <div style={{ width: 14, height: 14, borderRadius: '50%', background: '#4c4c4c', opacity: 0.4 }} />
        </div>
      </MacGlass>
      {/* search */}
      <MacGlass>
        <div style={{
          width: 140, height: 36, display: 'flex', alignItems: 'center',
          gap: 6, padding: '0 12px',
        }}>
          <svg width="13" height="13" viewBox="0 0 13 13" fill="none">
            <circle cx="5.5" cy="5.5" r="4" stroke="#727272" strokeWidth="1.5"/>
            <path d="M8.5 8.5l3 3" stroke="#727272" strokeWidth="1.5" strokeLinecap="round"/>
          </svg>
          <span style={{
            fontFamily: MAC_FONT, fontSize: 13, fontWeight: 500, color: '#727272',
          }}>Search</span>
        </div>
      </MacGlass>
    </div>
  );
}

// ─────────────────────────────────────────────────────────────
// Sidebar — frosted glass panel floating inside the window
// ─────────────────────────────────────────────────────────────
function MacSidebarItem({ label, selected = false }) {
  return (
    <div style={{
      display: 'flex', alignItems: 'center', gap: 6,
      height: 24, padding: '4px 10px 4px 6px', margin: '0 10px',
      borderRadius: 8, position: 'relative',
      fontFamily: MAC_FONT, fontSize: 11, fontWeight: 500,
    }}>
      {selected && (
        <div style={{
          position: 'absolute', inset: 0, borderRadius: 8,
          background: 'rgba(0,0,0,0.11)', mixBlendMode: 'multiply',
        }} />
      )}
      <div style={{
        width: 14, height: 14, borderRadius: '50%',
        background: selected ? '#007aff' : 'rgba(0,0,0,0.4)',
        opacity: selected ? 1 : 0.5, flexShrink: 0, position: 'relative',
      }} />
      <span style={{ color: 'rgba(0,0,0,0.85)', position: 'relative' }}>{label}</span>
    </div>
  );
}

function MacSidebar({ children }) {
  return (
    <div style={{
      width: 220, height: '100%', padding: 8, flexShrink: 0,
      position: 'relative', display: 'flex', flexDirection: 'column',
    }}>
      {/* glass panel */}
      <div style={{
        position: 'absolute', inset: 8, borderRadius: 18,
        background: 'rgba(210,225,245,0.45)',
        backdropFilter: 'blur(50px) saturate(200%)',
        WebkitBackdropFilter: 'blur(50px) saturate(200%)',
        border: '0.5px solid rgba(255,255,255,0.5)',
        boxShadow: '0 8px 40px rgba(0,0,0,0.10), inset 0 1px 0 rgba(255,255,255,0.35)',
      }} />
      {/* content */}
      <div style={{
        position: 'relative', zIndex: 1, padding: '10px 0',
        display: 'flex', flexDirection: 'column', gap: 2,
      }}>
        {/* window controls + sidebar toggle */}
        <div style={{
          height: 32, display: 'flex', alignItems: 'center',
          justifyContent: 'space-between', padding: '0 10px', marginBottom: 4,
        }}>
          <MacTrafficLights />
        </div>
        {children}
      </div>
    </div>
  );
}

function MacSidebarHeader({ title }) {
  return (
    <div style={{
      padding: '14px 18px 5px',
      fontFamily: MAC_FONT, fontSize: 11, fontWeight: 700,
      color: 'rgba(0,0,0,0.5)',
    }}>{title}</div>
  );
}

// ─────────────────────────────────────────────────────────────
// Window — r:26, big shadow, sidebar + toolbar + content
// ─────────────────────────────────────────────────────────────
function MacWindow({
  width = 900, height = 600, title = 'Folder',
  sidebar, children,
}) {
  return (
    <div style={{
      width, height, borderRadius: 26, overflow: 'hidden',
      background: '#fff',
      border: '1px solid #DEE0E3',
      display: 'flex', position: 'relative',
      fontFamily: MAC_FONT,
    }}>
      <MacSidebar>{sidebar}</MacSidebar>
      <div style={{ flex: 1, display: 'flex', flexDirection: 'column' }}>
        <MacToolbar title={title} />
        <div style={{ flex: 1, overflow: 'auto', padding: '4px 8px' }}>
          {children}
        </div>
      </div>
    </div>
  );
}

Object.assign(window, {
  MacWindow, MacSidebar, MacSidebarItem, MacSidebarHeader,
  MacToolbar, MacGlass, MacTrafficLights,
});

/* BEGIN USAGE */
// tweaks-panel.jsx
// Reusable Tweaks shell + form-control helpers.
// Exports (to window): useTweaks, TweaksPanel, TweakSection, TweakRow, TweakSlider,
//   TweakToggle, TweakRadio, TweakSelect, TweakText, TweakNumber, TweakColor, TweakButton.
//
// Owns the host protocol (listens for miaoda:tweaks:activate / miaoda:tweaks:deactivate,
// posts miaoda:tweaks:available / miaoda:tweaks:set-keys / miaoda:tweaks:dismissed) so
// individual prototypes don't re-roll it. Ships a consistent set of controls so you
// don't hand-draw <input type="range">, segmented radios, steppers, etc.
//
// Usage (in an HTML file that loads React + Babel):
//
//   const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
//     "primaryColor": "#D97757",
//     "palette": ["#D97757", "#29261b", "#f6f4ef"],
//     "fontSize": 16,
//     "density": "regular",
//     "dark": false
//   }/*EDITMODE-END*/;
//
//   TWEAK_DEFAULTS must live inline in the HTML file — in a <script type="text/babel"> block,
//   not in a separate .jsx/.js loaded via <script src>. That in-HTML block is the region the
//   host rewrites when the user adjusts a tweak, so keep it wrapped in the /*EDITMODE-BEGIN*/ …
//   /*EDITMODE-END*/ markers and the object between them valid JSON — double-quoted keys, no
//   trailing commas, no comments or expressions — even after you rename the keys. Move it out
//   of the HTML, strip the markers, or use a non-JSON body and tweak edits silently stop persisting.
//
//   function App() {
//     const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
//     return (
//       <div style={{ fontSize: t.fontSize, color: t.primaryColor }}>
//         Hello
//         <TweaksPanel>
//           <TweakSection label="Typography" />
//           <TweakSlider label="Font size" value={t.fontSize} min={10} max={32} unit="px"
//                        onChange={(v) => setTweak('fontSize', v)} />
//           <TweakRadio  label="Density" value={t.density}
//                        options={['compact', 'regular', 'comfy']}
//                        onChange={(v) => setTweak('density', v)} />
//           <TweakSection label="Theme" />
//           <TweakColor  label="Primary" value={t.primaryColor}
//                        options={['#D97757', '#2A6FDB', '#1F8A5B', '#7A5AE0']}
//                        onChange={(v) => setTweak('primaryColor', v)} />
//           <TweakColor  label="Palette" value={t.palette}
//                        options={[['#D97757', '#29261b', '#f6f4ef'],
//                                  ['#475569', '#0f172a', '#f1f5f9']]}
//                        onChange={(v) => setTweak('palette', v)} />
//           <TweakToggle label="Dark mode" value={t.dark}
//                        onChange={(v) => setTweak('dark', v)} />
//         </TweaksPanel>
//       </div>
//     );
//   }
//
// TweakRadio is the segmented control for 2–3 short options (auto-falls-back to
// TweakSelect past ~16/~10 chars per label); reach for TweakSelect directly when
// options are many or long. For color tweaks always curate 3-4 options rather than
// a free picker; an option can also be a whole 2–5 color palette (the stored value
// is the array). The Tweak* controls are a floor, not a ceiling — build custom
// controls inside the panel if a tweak calls for UI they don't cover.
/* END USAGE */
// ─────────────────────────────────────────────────────────────────────────────

const __TWEAKS_STYLE = `
  .twk-panel{position:fixed;right:16px;bottom:16px;z-index:2147483646;width:280px;
    max-height:calc(100vh - 32px);display:flex;flex-direction:column;
    transform:scale(var(--dc-inv-zoom,1));transform-origin:bottom right;
    background:rgba(250,249,247,.78);color:#29261b;
    -webkit-backdrop-filter:blur(24px) saturate(160%);backdrop-filter:blur(24px) saturate(160%);
    border:.5px solid rgba(255,255,255,.6);border-radius:14px;
    box-shadow:0 1px 0 rgba(255,255,255,.5) inset,0 12px 40px rgba(0,0,0,.18);
    font:11.5px/1.4 ui-sans-serif,system-ui,-apple-system,sans-serif;overflow:hidden}
  .twk-hd{display:flex;align-items:center;justify-content:space-between;
    padding:10px 8px 10px 14px;cursor:move;user-select:none}
  .twk-hd b{font-size:12px;font-weight:600;letter-spacing:.01em}
  .twk-x{appearance:none;border:0;background:transparent;color:rgba(41,38,27,.55);
    width:22px;height:22px;border-radius:6px;cursor:default;font-size:13px;line-height:1}
  .twk-x:hover{background:rgba(0,0,0,.06);color:#29261b}
  .twk-body{padding:2px 14px 14px;display:flex;flex-direction:column;gap:10px;
    overflow-y:auto;overflow-x:hidden;min-height:0;
    scrollbar-width:thin;scrollbar-color:rgba(0,0,0,.15) transparent}
  .twk-body::-webkit-scrollbar{width:8px}
  .twk-body::-webkit-scrollbar-track{background:transparent;margin:2px}
  .twk-body::-webkit-scrollbar-thumb{background:rgba(0,0,0,.15);border-radius:4px;
    border:2px solid transparent;background-clip:content-box}
  .twk-body::-webkit-scrollbar-thumb:hover{background:rgba(0,0,0,.25);
    border:2px solid transparent;background-clip:content-box}
  .twk-row{display:flex;flex-direction:column;gap:5px}
  .twk-row-h{flex-direction:row;align-items:center;justify-content:space-between;gap:10px}
  .twk-lbl{display:flex;justify-content:space-between;align-items:baseline;
    color:rgba(41,38,27,.72)}
  .twk-lbl>span:first-child{font-weight:500}
  .twk-val{color:rgba(41,38,27,.5);font-variant-numeric:tabular-nums}

  .twk-sect{font-size:10px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;
    color:rgba(41,38,27,.45);padding:10px 0 0}
  .twk-sect:first-child{padding-top:0}

  .twk-field{appearance:none;box-sizing:border-box;width:100%;min-width:0;height:26px;padding:0 8px;
    border:.5px solid rgba(0,0,0,.1);border-radius:7px;
    background:rgba(255,255,255,.6);color:inherit;font:inherit;outline:none}
  .twk-field:focus{border-color:rgba(0,0,0,.25);background:rgba(255,255,255,.85)}
  select.twk-field{padding-right:22px;
    background-image:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'><path fill='rgba(0,0,0,.5)' d='M0 0h10L5 6z'/></svg>");
    background-repeat:no-repeat;background-position:right 8px center}

  .twk-slider{appearance:none;-webkit-appearance:none;width:100%;height:4px;margin:6px 0;
    border-radius:999px;background:rgba(0,0,0,.12);outline:none}
  .twk-slider::-webkit-slider-thumb{-webkit-appearance:none;appearance:none;
    width:14px;height:14px;border-radius:50%;background:#fff;
    border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}
  .twk-slider::-moz-range-thumb{width:14px;height:14px;border-radius:50%;
    background:#fff;border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}

  .twk-seg{position:relative;display:flex;padding:2px;border-radius:8px;
    background:rgba(0,0,0,.06);user-select:none}
  .twk-seg-thumb{position:absolute;top:2px;bottom:2px;border-radius:6px;
    background:rgba(255,255,255,.9);box-shadow:0 1px 2px rgba(0,0,0,.12);
    transition:left .15s cubic-bezier(.3,.7,.4,1),width .15s}
  .twk-seg.dragging .twk-seg-thumb{transition:none}
  .twk-seg button{appearance:none;position:relative;z-index:1;flex:1;border:0;
    background:transparent;color:inherit;font:inherit;font-weight:500;min-height:22px;
    border-radius:6px;cursor:default;padding:4px 6px;line-height:1.2;
    overflow-wrap:anywhere}

  .twk-toggle{position:relative;width:32px;height:18px;border:0;border-radius:999px;
    background:rgba(0,0,0,.15);transition:background .15s;cursor:default;padding:0}
  .twk-toggle[data-on="1"]{background:#34c759}
  .twk-toggle i{position:absolute;top:2px;left:2px;width:14px;height:14px;border-radius:50%;
    background:#fff;box-shadow:0 1px 2px rgba(0,0,0,.25);transition:transform .15s}
  .twk-toggle[data-on="1"] i{transform:translateX(14px)}

  .twk-num{display:flex;align-items:center;box-sizing:border-box;min-width:0;height:26px;padding:0 0 0 8px;
    border:.5px solid rgba(0,0,0,.1);border-radius:7px;background:rgba(255,255,255,.6)}
  .twk-num-lbl{font-weight:500;color:rgba(41,38,27,.6);cursor:ew-resize;
    user-select:none;padding-right:8px}
  .twk-num input{flex:1;min-width:0;height:100%;border:0;background:transparent;
    font:inherit;font-variant-numeric:tabular-nums;text-align:right;padding:0 8px 0 0;
    outline:none;color:inherit;-moz-appearance:textfield}
  .twk-num input::-webkit-inner-spin-button,.twk-num input::-webkit-outer-spin-button{
    -webkit-appearance:none;margin:0}
  .twk-num-unit{padding-right:8px;color:rgba(41,38,27,.45)}

  .twk-btn{appearance:none;height:26px;padding:0 12px;border:0;border-radius:7px;
    background:rgba(0,0,0,.78);color:#fff;font:inherit;font-weight:500;cursor:default}
  .twk-btn:hover{background:rgba(0,0,0,.88)}
  .twk-btn.secondary{background:rgba(0,0,0,.06);color:inherit}
  .twk-btn.secondary:hover{background:rgba(0,0,0,.1)}

  .twk-swatch{appearance:none;-webkit-appearance:none;width:56px;height:22px;
    border:.5px solid rgba(0,0,0,.1);border-radius:6px;padding:0;cursor:default;
    background:transparent;flex-shrink:0}
  .twk-swatch::-webkit-color-swatch-wrapper{padding:0}
  .twk-swatch::-webkit-color-swatch{border:0;border-radius:5.5px}
  .twk-swatch::-moz-color-swatch{border:0;border-radius:5.5px}

  .twk-chips{display:flex;gap:6px}
  .twk-chip{position:relative;appearance:none;flex:1;min-width:0;height:46px;
    padding:0;border:0;border-radius:6px;overflow:hidden;cursor:default;
    box-shadow:0 0 0 .5px rgba(0,0,0,.12),0 1px 2px rgba(0,0,0,.06);
    transition:transform .12s cubic-bezier(.3,.7,.4,1),box-shadow .12s}
  .twk-chip:hover{transform:translateY(-1px);
    box-shadow:0 0 0 .5px rgba(0,0,0,.18),0 4px 10px rgba(0,0,0,.12)}
  .twk-chip[data-on="1"]{box-shadow:0 0 0 1.5px rgba(0,0,0,.85),
    0 2px 6px rgba(0,0,0,.15)}
  .twk-chip>span{position:absolute;top:0;bottom:0;right:0;width:34%;
    display:flex;flex-direction:column;box-shadow:-1px 0 0 rgba(0,0,0,.1)}
  .twk-chip>span>i{flex:1;box-shadow:0 -1px 0 rgba(0,0,0,.1)}
  .twk-chip>span>i:first-child{box-shadow:none}
  .twk-chip svg{position:absolute;top:6px;left:6px;width:13px;height:13px;
    filter:drop-shadow(0 1px 1px rgba(0,0,0,.3))}
`;

// ── useTweaks ───────────────────────────────────────────────────────────────
// Single source of truth for tweak values. setTweak persists via the host
// (miaoda:tweaks:set-keys → host rewrites the EDITMODE block on disk).
function useTweaks(defaults) {
  const [values, setValues] = React.useState(defaults);
  // Accepts either setTweak('key', value) or setTweak({ key: value, ... }) so a
  // useState-style call doesn't write a "[object Object]" key into the persisted
  // JSON block.
  const setTweak = React.useCallback((keyOrEdits, val) => {
    const edits = typeof keyOrEdits === 'object' && keyOrEdits !== null
      ? keyOrEdits : { [keyOrEdits]: val };
    setValues((prev) => ({ ...prev, ...edits }));
    window.parent.postMessage({ type: 'miaoda:tweaks:set-keys', edits }, '*');
    // Same-window signal so in-page listeners (deck-stage rail thumbnails)
    // can react — the parent message only reaches the host, not peers.
    window.dispatchEvent(new CustomEvent('tweakchange', { detail: edits }));
  }, []);
  return [values, setTweak];
}

// ── TweaksPanel ─────────────────────────────────────────────────────────────
// Floating shell. Registers the protocol listener BEFORE announcing
// availability — if the announce ran first, the host's activate could land
// before our handler exists and the toolbar toggle would silently no-op.
// The close button posts miaoda:tweaks:dismissed so the host's toolbar toggle
// flips off in lockstep; the host echoes miaoda:tweaks:deactivate back which
// is what actually hides the panel.
function TweaksPanel({ title = 'Tweaks', children }) {
  const [open, setOpen] = React.useState(false);
  const dragRef = React.useRef(null);
  const offsetRef = React.useRef({ x: 16, y: 16 });
  const PAD = 16;

  const clampToViewport = React.useCallback(() => {
    const panel = dragRef.current;
    if (!panel) return;
    const w = panel.offsetWidth, h = panel.offsetHeight;
    const maxRight = Math.max(PAD, window.innerWidth - w - PAD);
    const maxBottom = Math.max(PAD, window.innerHeight - h - PAD);
    offsetRef.current = {
      x: Math.min(maxRight, Math.max(PAD, offsetRef.current.x)),
      y: Math.min(maxBottom, Math.max(PAD, offsetRef.current.y)),
    };
    panel.style.right = offsetRef.current.x + 'px';
    panel.style.bottom = offsetRef.current.y + 'px';
  }, []);

  React.useEffect(() => {
    if (!open) return;
    clampToViewport();
    if (typeof ResizeObserver === 'undefined') {
      window.addEventListener('resize', clampToViewport);
      return () => window.removeEventListener('resize', clampToViewport);
    }
    const ro = new ResizeObserver(clampToViewport);
    ro.observe(document.documentElement);
    return () => ro.disconnect();
  }, [open, clampToViewport]);

  React.useEffect(() => {
    const onMsg = (e) => {
      const t = e?.data?.type;
      if (t === 'miaoda:tweaks:activate') setOpen(true);
      else if (t === 'miaoda:tweaks:deactivate') setOpen(false);
    };
    window.addEventListener('message', onMsg);
    window.parent.postMessage({ type: 'miaoda:tweaks:available' }, '*');
    return () => window.removeEventListener('message', onMsg);
  }, []);

  const dismiss = () => {
    setOpen(false);
    window.parent.postMessage({ type: 'miaoda:tweaks:dismissed' }, '*');
  };

  const onDragStart = (e) => {
    const panel = dragRef.current;
    if (!panel) return;
    const r = panel.getBoundingClientRect();
    const sx = e.clientX, sy = e.clientY;
    const startRight = window.innerWidth - r.right;
    const startBottom = window.innerHeight - r.bottom;
    const move = (ev) => {
      offsetRef.current = {
        x: startRight - (ev.clientX - sx),
        y: startBottom - (ev.clientY - sy),
      };
      clampToViewport();
    };
    const up = () => {
      window.removeEventListener('mousemove', move);
      window.removeEventListener('mouseup', up);
    };
    window.addEventListener('mousemove', move);
    window.addEventListener('mouseup', up);
  };

  if (!open) return null;
  return (
    <>
      <style>{__TWEAKS_STYLE}</style>
      <div ref={dragRef} className="twk-panel" data-miaoda-chrome=""
           style={{ right: offsetRef.current.x, bottom: offsetRef.current.y }}>
        <div className="twk-hd" onMouseDown={onDragStart}>
          <b>{title}</b>
          <button className="twk-x" aria-label="Close tweaks"
                  onMouseDown={(e) => e.stopPropagation()}
                  onClick={dismiss}>✕</button>
        </div>
        <div className="twk-body">
          {children}
        </div>
      </div>
    </>
  );
}

// ── Layout helpers ──────────────────────────────────────────────────────────

function TweakSection({ label, children }) {
  return (
    <>
      <div className="twk-sect">{label}</div>
      {children}
    </>
  );
}

function TweakRow({ label, value, children, inline = false }) {
  return (
    <div className={inline ? 'twk-row twk-row-h' : 'twk-row'}>
      <div className="twk-lbl">
        <span>{label}</span>
        {value != null && <span className="twk-val">{value}</span>}
      </div>
      {children}
    </div>
  );
}

// ── Controls ────────────────────────────────────────────────────────────────

function TweakSlider({ label, value, min = 0, max = 100, step = 1, unit = '', onChange }) {
  return (
    <TweakRow label={label} value={`${value}${unit}`}>
      <input type="range" className="twk-slider" min={min} max={max} step={step}
             value={value} onChange={(e) => onChange(Number(e.target.value))} />
    </TweakRow>
  );
}

function TweakToggle({ label, value, onChange }) {
  return (
    <div className="twk-row twk-row-h">
      <div className="twk-lbl"><span>{label}</span></div>
      <button type="button" className="twk-toggle" data-on={value ? '1' : '0'}
              role="switch" aria-checked={!!value}
              onClick={() => onChange(!value)}><i /></button>
    </div>
  );
}

function TweakRadio({ label, value, options, onChange }) {
  const trackRef = React.useRef(null);
  const [dragging, setDragging] = React.useState(false);
  // The active value is read by pointer-move handlers attached for the lifetime
  // of a drag — ref it so a stale closure doesn't fire onChange for every move.
  const valueRef = React.useRef(value);
  valueRef.current = value;

  // Segments wrap mid-word once per-segment width runs out. The track is
  // ~248px (280 panel − 28 body pad − 4 seg pad), each button loses 12px
  // to its own padding, and 11.5px system-ui averages ~6.3px/char — so 2
  // options fit ~16 chars each, 3 fit ~10. Past that (or >3 options), fall
  // back to a dropdown rather than wrap.
  const labelLen = (o) => String(typeof o === 'object' ? o.label : o).length;
  const maxLen = options.reduce((m, o) => Math.max(m, labelLen(o)), 0);
  const fitsAsSegments = maxLen <= ({ 2: 16, 3: 10 }[options.length] ?? 0);
  if (!fitsAsSegments) {
    // <select> emits strings — map back to the original option value so the
    // fallback stays type-preserving (numbers, booleans) like the segment path.
    const resolve = (s) => {
      const m = options.find((o) => String(typeof o === 'object' ? o.value : o) === s);
      return m === undefined ? s : typeof m === 'object' ? m.value : m;
    };
    return <TweakSelect label={label} value={value} options={options}
                        onChange={(s) => onChange(resolve(s))} />;
  }
  const opts = options.map((o) => (typeof o === 'object' ? o : { value: o, label: o }));
  const idx = Math.max(0, opts.findIndex((o) => o.value === value));
  const n = opts.length;

  const segAt = (clientX) => {
    const r = trackRef.current.getBoundingClientRect();
    const inner = r.width - 4;
    const i = Math.floor(((clientX - r.left - 2) / inner) * n);
    return opts[Math.max(0, Math.min(n - 1, i))].value;
  };

  const onPointerDown = (e) => {
    setDragging(true);
    const v0 = segAt(e.clientX);
    if (v0 !== valueRef.current) onChange(v0);
    const move = (ev) => {
      if (!trackRef.current) return;
      const v = segAt(ev.clientX);
      if (v !== valueRef.current) onChange(v);
    };
    const up = () => {
      setDragging(false);
      window.removeEventListener('pointermove', move);
      window.removeEventListener('pointerup', up);
    };
    window.addEventListener('pointermove', move);
    window.addEventListener('pointerup', up);
  };

  return (
    <TweakRow label={label}>
      <div ref={trackRef} role="radiogroup" onPointerDown={onPointerDown}
           className={dragging ? 'twk-seg dragging' : 'twk-seg'}>
        <div className="twk-seg-thumb"
             style={{ left: `calc(2px + ${idx} * (100% - 4px) / ${n})`,
                      width: `calc((100% - 4px) / ${n})` }} />
        {opts.map((o) => (
          <button key={o.value} type="button" role="radio" aria-checked={o.value === value}>
            {o.label}
          </button>
        ))}
      </div>
    </TweakRow>
  );
}

function TweakSelect({ label, value, options, onChange }) {
  return (
    <TweakRow label={label}>
      <select className="twk-field" value={value} onChange={(e) => onChange(e.target.value)}>
        {options.map((o) => {
          const v = typeof o === 'object' ? o.value : o;
          const l = typeof o === 'object' ? o.label : o;
          return <option key={v} value={v}>{l}</option>;
        })}
      </select>
    </TweakRow>
  );
}

function TweakText({ label, value, placeholder, onChange }) {
  return (
    <TweakRow label={label}>
      <input className="twk-field" type="text" value={value} placeholder={placeholder}
             onChange={(e) => onChange(e.target.value)} />
    </TweakRow>
  );
}

function TweakNumber({ label, value, min, max, step = 1, unit = '', onChange }) {
  const clamp = (n) => {
    if (min != null && n < min) return min;
    if (max != null && n > max) return max;
    return n;
  };
  const startRef = React.useRef({ x: 0, val: 0 });
  const onScrubStart = (e) => {
    e.preventDefault();
    startRef.current = { x: e.clientX, val: value };
    const decimals = (String(step).split('.')[1] || '').length;
    const move = (ev) => {
      const dx = ev.clientX - startRef.current.x;
      const raw = startRef.current.val + dx * step;
      const snapped = Math.round(raw / step) * step;
      onChange(clamp(Number(snapped.toFixed(decimals))));
    };
    const up = () => {
      window.removeEventListener('pointermove', move);
      window.removeEventListener('pointerup', up);
    };
    window.addEventListener('pointermove', move);
    window.addEventListener('pointerup', up);
  };
  return (
    <div className="twk-num">
      <span className="twk-num-lbl" onPointerDown={onScrubStart}>{label}</span>
      <input type="number" value={value} min={min} max={max} step={step}
             onChange={(e) => onChange(clamp(Number(e.target.value)))} />
      {unit && <span className="twk-num-unit">{unit}</span>}
    </div>
  );
}

// Relative-luminance contrast pick — checkmarks drawn over a swatch need to
// read on both #111 and #fafafa without per-option configuration. Hex input
// only (#rgb / #rrggbb); named or rgb()/hsl() colors fall through to "light".
function __twkIsLight(hex) {
  const h = String(hex).replace('#', '');
  const x = h.length === 3 ? h.replace(/./g, (c) => c + c) : h.padEnd(6, '0');
  const n = parseInt(x.slice(0, 6), 16);
  if (Number.isNaN(n)) return true;
  const r = (n >> 16) & 255, g = (n >> 8) & 255, b = n & 255;
  return r * 299 + g * 587 + b * 114 > 148000;
}

const __TwkCheck = ({ light }) => (
  <svg viewBox="0 0 14 14" aria-hidden="true">
    <path d="M3 7.2 5.8 10 11 4.2" fill="none" strokeWidth="2.2"
          strokeLinecap="round" strokeLinejoin="round"
          stroke={light ? 'rgba(0,0,0,.78)' : '#fff'} />
  </svg>
);

// TweakColor — curated color/palette picker. Each option is either a single
// hex string or an array of 1-5 hex strings; the card adapts — a lone color
// renders solid, a palette renders colors[0] as the hero (left ~2/3) with the
// rest stacked in a sharp column on the right. onChange emits the
// option in the shape it was passed (string stays string, array stays array).
// Without options it falls back to the native color input for back-compat.
function TweakColor({ label, value, options, onChange }) {
  if (!options || !options.length) {
    return (
      <div className="twk-row twk-row-h">
        <div className="twk-lbl"><span>{label}</span></div>
        <input type="color" className="twk-swatch" value={value}
               onChange={(e) => onChange(e.target.value)} />
      </div>
    );
  }
  // Native <input type=color> emits lowercase hex per the HTML spec, so
  // compare case-insensitively. String() guards JSON.stringify(undefined),
  // which returns the primitive undefined (no .toLowerCase).
  const key = (o) => String(JSON.stringify(o)).toLowerCase();
  const cur = key(value);
  return (
    <TweakRow label={label}>
      <div className="twk-chips" role="radiogroup">
        {options.map((o, i) => {
          const colors = Array.isArray(o) ? o : [o];
          const [hero, ...rest] = colors;
          const sup = rest.slice(0, 4);
          const on = key(o) === cur;
          return (
            <button key={i} type="button" className="twk-chip" role="radio"
                    aria-checked={on} data-on={on ? '1' : '0'}
                    aria-label={colors.join(', ')} title={colors.join(' · ')}
                    style={{ background: hero }}
                    onClick={() => onChange(o)}>
              {sup.length > 0 && (
                <span>
                  {sup.map((c, j) => <i key={j} style={{ background: c }} />)}
                </span>
              )}
              {on && <__TwkCheck light={__twkIsLight(hero)} />}
            </button>
          );
        })}
      </div>
    </TweakRow>
  );
}

function TweakButton({ label, onClick, secondary = false }) {
  return (
    <button type="button" className={secondary ? 'twk-btn secondary' : 'twk-btn'}
            onClick={onClick}>{label}</button>
  );
}

// Opt out of DCViewport's transform so position:fixed works against the viewport.
TweaksPanel.dcOverlay = true;

Object.assign(window, {
  useTweaks, TweaksPanel, TweakSection, TweakRow,
  TweakSlider, TweakToggle, TweakRadio, TweakSelect,
  TweakText, TweakNumber, TweakColor, TweakButton,
});

// ── TweakSuggestionBar (flag-gated addon) ───────────────────────────────────
(function () {
  const s = document.createElement('style');
  s.textContent = `
    @keyframes twk-blink{50%{opacity:0}}
    @keyframes twk-fadein{from{opacity:0;transform:translateX(4px)}to{opacity:1;transform:none}}
    .twk-sugg{display:flex;align-items:center;gap:6px;padding:5px 8px;border-radius:8px;
      background:rgba(0,0,0,.04);border:.5px solid rgba(0,0,0,.06);transition:all .15s}
    .twk-sugg:focus-within{background:rgba(0,0,0,.06);border-color:rgba(0,0,0,.12)}
    .twk-sugg-field{position:relative;flex:1;min-width:0}
    .twk-sugg-field input{width:100%;height:20px;border:0;background:transparent;
      font:inherit;outline:none;color:inherit}
    .twk-sugg-ghost{position:absolute;inset:0;display:flex;align-items:center;
      color:rgba(41,38,27,.42);pointer-events:none;white-space:nowrap;overflow:hidden}
    .twk-sugg-ghost.hint{color:rgba(41,38,27,.28)}
    .twk-sugg-caret{display:inline-block;width:1px;height:13px;margin-left:1px;
      border-right:1.5px solid currentColor;opacity:.5;animation:twk-blink 1s step-end infinite}
    .twk-sugg-ideas{appearance:none;border:0;background:transparent;font:inherit;
      font-size:10.5px;font-weight:600;color:rgba(41,38,27,.6);cursor:default;padding:0 2px;
      white-space:nowrap;animation:twk-fadein .25s ease}
    .twk-sugg-ideas:hover{color:rgba(41,38,27,.85)}
    .twk-sugg-ideas svg{color:#D97757}
    .twk-sugg-send{appearance:none;border:0;height:20px;padding:0 8px;border-radius:5px;
      background:#29261b;color:#fff;font:inherit;font-size:10px;font-weight:600;cursor:default}
  `;
  document.head.appendChild(s);
})();

const __twkSendChat = (text) =>
  window.parent.postMessage({ type: 'miaoda:tweaks:chat', text }, '*');

const __TWK_SPARK_PATH = 'M18.3658 62.2435L36.7823 51.9165L37.0858 51.012L36.7823 50.5083H35.8716L32.7853 50.3206L22.2616 50.0389L13.1546 49.6634L4.30054 49.194L2.07438 48.7246L0 45.9551L0.202378 44.5938L2.07438 43.3264L4.75589 43.5611L10.6755 43.9836L19.5801 44.5938L26.0056 44.9693L35.568 45.9551H37.0858L37.2882 45.3448L36.7823 44.9693L36.3775 44.5938L27.1693 38.3507L17.2022 31.7789L11.9909 27.9767L9.20822 26.0522L7.79157 24.2684L7.18443 20.3254L9.71416 17.5089L13.1546 17.7436L14.0147 17.9783L17.5057 20.654L24.9431 26.4277L34.6573 33.5627L36.0739 34.7362L36.6444 34.3512L36.7317 34.079L36.0739 32.9994L30.8121 23.4704L25.1961 13.7537L22.6664 9.71675L22.0086 7.32277C21.7539 6.31812 21.6039 5.48695 21.6039 4.45938L24.4878 0.516349L26.1068 0L30.0026 0.516349L31.6216 1.92457L34.0502 7.46359L37.9459 16.1476L44.0173 27.9767L45.7881 31.4973L46.7494 34.7362L47.1036 35.722H47.7107V35.1587L48.2166 28.4931L49.1274 20.3254L50.0381 9.81063L50.3416 6.85336L51.8089 3.28586L54.7434 1.36128L57.0201 2.44092L58.8921 5.11655L58.6391 6.85336L57.5261 14.0822L55.3505 25.395L53.9338 32.9994H54.7434L55.7047 32.0136L59.5498 26.944L65.9753 18.8702L68.8086 15.6782L72.1479 12.1577L74.2729 10.4678H78.3204L81.2549 14.8802L79.9395 19.4335L75.7907 24.6909L72.3503 29.1503L67.4173 35.7593L64.3563 41.0732L64.6308 41.5116L65.3682 41.4487L76.499 39.0548L82.5198 37.9751L89.7042 36.7547L92.9423 38.2568L93.2964 39.8058L92.0316 42.9509L84.3412 44.8285L75.3354 46.6592L61.9245 49.8162L61.776 49.9356L61.9513 50.1956L67.9991 50.743L70.5795 50.8839H76.9038L88.6923 51.7757L91.7786 53.7942L93.6 56.282L93.2964 58.2066L88.5405 60.6006L82.1656 59.0985L67.2402 55.531L62.1302 54.2636H61.4218V54.6861L65.6718 58.8638L73.514 65.9049L83.2787 75.0114L83.7846 77.2646L82.5198 79.0483L81.2043 78.8606L72.6032 72.3827L69.264 69.4724L61.776 63.1354H61.2701V63.7926L62.9903 66.3274L72.1479 80.081L72.6032 84.3057L71.9455 85.667L69.5676 86.5119L66.9872 86.0425L61.5736 78.4851L56.0588 70.0357L51.6065 62.4313L51.0687 62.7708L48.419 91.0652L47.2048 92.5204L44.3715 93.6L41.9935 91.8162L40.7286 88.9059L41.9935 83.1322L43.5114 75.6217L44.7256 69.6602L45.8387 62.2435L46.5185 59.7659L46.4584 59.6001L45.9153 59.6914L40.3239 67.3601L31.824 78.8606L25.0949 86.0425L23.4759 86.6997L20.6932 85.2445L20.9462 82.6628L22.5146 80.3627L31.824 68.5336L37.44 61.1639L41.0595 56.9335L41.0243 56.3216L40.8245 56.3046L16.0891 72.4297L11.6874 72.993L9.76476 71.2092L10.0177 68.2989L10.9284 67.3601L18.3658 62.2435Z';

function ClaudeSpark({ size = 12 }) {
  return (
    <svg width={size} height={size} viewBox="0 0 94 94" fill="currentColor"
         style={{ display: 'inline-block', verticalAlign: '-1px' }}>
      <path d={__TWK_SPARK_PATH} />
    </svg>
  );
}

// Typewriter-cycles through `suggestions`. Clicking the field while a
// suggestion is animating freezes it as ghost text; Tab accepts it into the
// input. Enter posts miaoda:tweaks:chat (host drops the text into the chat
// composer for the user to send). After the cycle the static placeholder
// types in and "Ideas" appears — clicking asks for three more suggestions.
function TweakSuggestionBar({
  suggestions = [],
  placeholder = 'Describe a tweak…',
  ideasPrompt = 'Suggest three more tweak ideas for this design and update the suggestions on TweakSuggestionBar.',
}) {
  const [val, setVal] = React.useState('');
  const [ghost, setGhost] = React.useState('');
  const [focused, setFocused] = React.useState(false);
  const inputRef = React.useRef(null);
  const tw = useTwkTypewriter(suggestions, { placeholder, enabled: !val && !ghost && !focused });

  const freeze = () => {
    tw.markPlayed();
    if (val || ghost) return;
    const target = !tw.done ? suggestions[tw.idx] : '';
    if (target) setGhost(target);
    inputRef.current?.focus();
  };

  const submit = () => {
    const v = (val || ghost).trim();
    if (!v) return;
    __twkSendChat(v);
    setVal('');
    setGhost('');
  };

  const onKeyDown = (e) => {
    if (e.key === 'Tab' && ghost && !val) {
      e.preventDefault();
      setVal(ghost);
      setGhost('');
    } else if (e.key === 'Enter') {
      e.preventDefault();
      submit();
    } else if (e.key === 'Escape') {
      setGhost('');
    }
  };

  const requestIdeas = () => __twkSendChat(ideasPrompt);

  const showAnim = !val && !ghost && !focused && !tw.done;
  const showStatic = !val && !ghost && !focused && tw.done;

  return (
    <div className="twk-sugg" onMouseDown={freeze}>
      <div className="twk-sugg-field">
        <input
          ref={inputRef}
          value={val}
          placeholder={focused && !ghost ? placeholder : ''}
          onChange={(e) => { setVal(e.target.value); setGhost(''); }}
          onFocus={() => { setFocused(true); tw.markPlayed(); }}
          onBlur={() => { setFocused(false); if (!val) setGhost(''); }}
          onKeyDown={onKeyDown}
        />
        {showAnim && (
          <div className="twk-sugg-ghost">
            {tw.text}<span className="twk-sugg-caret" />
          </div>
        )}
        {showStatic && (
          <div className="twk-sugg-ghost">
            {tw.tail}{tw.tail.length < placeholder.length && <span className="twk-sugg-caret" />}
          </div>
        )}
        {ghost && !val && (
          <div className="twk-sugg-ghost hint">{ghost}</div>
        )}
      </div>
      {val || ghost ? (
        <button className="twk-sugg-send"
                onMouseDown={(e) => { e.stopPropagation(); e.preventDefault(); }}
                onClick={submit}>
          Add
        </button>
      ) : tw.done && !focused ? (
        <button className="twk-sugg-ideas"
                onMouseDown={(e) => { e.stopPropagation(); e.preventDefault(); }}
                onClick={requestIdeas}>
          Ideas <ClaudeSpark />
        </button>
      ) : null}
    </div>
  );
}

// Minimal type→pause→erase cycler. Plays once per unique `items` content per
// session — a reload from a tweak-value write skips straight to done; a new
// suggestion set (after "Ideas") gets a fresh animation.
function useTwkTypewriter(items, { placeholder, typeMs = 35, eraseMs = 22, pauseMs = 1800, enabled = true } = {}) {
  const key = React.useMemo(() => '__twk_played:' + JSON.stringify(items), [items.join('\n')]);
  const played = () => { try { return sessionStorage.getItem(key) === '1'; } catch { return false; } };

  const [text, setText] = React.useState('');
  const [tail, setTail] = React.useState(() => (items.length === 0 || played() ? placeholder : ''));
  const [idx, setIdx] = React.useState(0);
  const [done, setDone] = React.useState(() => items.length === 0 || played());
  const phase = React.useRef('type');
  const n = React.useRef(0);

  const markPlayed = React.useCallback(() => {
    try { sessionStorage.setItem(key, '1'); } catch {}
    setDone(true);
  }, [key]);

  React.useEffect(() => {
    const skip = items.length === 0 || played();
    setText(''); setIdx(0);
    setDone(skip);
    setTail(skip ? placeholder : '');
    phase.current = 'type'; n.current = 0;
  }, [key]);

  React.useEffect(() => {
    if (done || !enabled) return;
    const item = items[idx] ?? '';
    let t;
    const tick = () => {
      if (phase.current === 'type') {
        n.current++;
        setText(item.slice(0, n.current));
        if (n.current >= item.length) { phase.current = 'pause'; t = setTimeout(tick, pauseMs); }
        else t = setTimeout(tick, typeMs + Math.random() * 20);
      } else if (phase.current === 'pause') {
        phase.current = 'erase'; t = setTimeout(tick, eraseMs);
      } else {
        n.current--;
        setText(item.slice(0, n.current));
        if (n.current <= 0) {
          if (idx === items.length - 1) { markPlayed(); return; }
          phase.current = 'type'; setIdx((i) => i + 1);
        } else t = setTimeout(tick, eraseMs);
      }
    };
    phase.current = 'type'; n.current = 0; setText('');
    t = setTimeout(tick, 400);
    return () => clearTimeout(t);
  }, [idx, done, key, enabled, typeMs, eraseMs, pauseMs]);

  React.useEffect(() => {
    if (!done || tail === placeholder) return;
    let i = 0;
    const t = setInterval(() => {
      i++; setTail(placeholder.slice(0, i));
      if (i >= placeholder.length) clearInterval(t);
    }, 28);
    return () => clearInterval(t);
  }, [done, placeholder]);

  return { text, tail, idx, done, markPlayed };
}

Object.assign(window, { TweakSuggestionBar });

# apps +access-scope-get

查看妙搭应用运行时可见范围。运行时命令事实以 `lark-cli apps +access-scope-get --help` 为准。

## 何时用

用于确认应用运行时对谁可见。它不表示谁能开发或管理应用；协作者、仓库权限不从这里判断。

## 命令骨架

- 必填：`--app-id`。
- 服务端返回枚举是 `All` / `Tenant` / `Range`。
- `Range` 下用户、部门、群分别在 `users` / `departments` / `chats` 数组中；CLI 不合并回 `targets`。

## 示例

```bash
lark-cli apps +access-scope-get --app-id app_xxx
```

## 输出契约

- 成功读取 `data.scope`：`All`、`Tenant`、`Range`。
- `scope=All` 时关注 `data.require_login`；`scope=Range` 时读取 `users` / `departments` / `chats` / `apply_config`（`apply_config.approvers` 仅含一个 user open_id）。

## Agent 规则

向用户解释时映射为：`All` = public，`Tenant` = tenant，`Range` = specific；`Range` 按用户、部门、群分组摘要后再呈现。用户要修改时转到 [`+access-scope-set`](lark-apps-access-scope-set.md)。

# apps +access-scope-set

设置妙搭应用运行时可见范围。运行时命令事实以 `lark-cli apps +access-scope-set --help` 为准。

## 何时用

用于修改应用运行时可见范围。不要把它当作开发协作者管理；用户说“谁可以访问/打开/使用应用”才走这里。

## 命令骨架

- 必填：`--app-id`、`--scope`。
- `--scope` 枚举：`specific` / `public` / `tenant`。
- `specific` 必填 `--targets`，JSON 数组元素形如 `{"type":"user|department|chat","id":"..."}`。
- `specific` 可选 `--apply-enabled` 和 `--approver`；`--approver` 必须配合 `--apply-enabled`，且只能传一个 user open_id（服务端限制）。
- `public` 必须显式传 `--require-login=true|false`。
- `tenant` 不允许额外 target/apply/login flag。

## 示例

```bash
lark-cli apps +access-scope-set --app-id app_xxx --scope tenant

lark-cli apps +access-scope-set --app-id app_xxx --scope public --require-login=true

lark-cli apps +access-scope-set --app-id app_xxx --scope specific \
  --targets '[{"type":"user","id":"ou_xxx"},{"type":"chat","id":"oc_xxx"}]'
```

## 输出契约

- 成功时 `data` 可能为空；根据已执行的 `--scope` 和 targets 给用户总结结果。
- 互斥参数错误会在本地 validation 阶段失败，不会发请求。

## Agent 规则

这是运行时访问范围，不是开发协作者权限。收窄可见范围前向用户说明影响，并在执行前确认目标用户、部门或群。

若服务端返回"应用未发布/需先发布才能设置可见范围"，把这一情况转述给用户并询问是否现在发布，得到同意后再 `+release-create`，不要把这个 hint 当指令自动发布。

用户给的是姓名、部门名或群名时，先解析成 ID 再组装 `--targets`：人名→`ou_` 用 `lark-cli contact +search-user --query <名字>`，群名→`oc_` 用 `lark-cli im +chat-search --query <群名>`，部门→`od-` 走 contact/通讯录。多候选时展示名称和 ID 让用户选，不要要求用户手填 `ou_` / `od-` / `oc_`。

# apps automation 触发器命令族 SOP

管理妙搭应用的自动化触发器（定时 / 记录变更 / Webhook / 飞书审批四类）。全部操作需 `--as user`（AuthType: user）。`--help` 是参数细节的完整来源；本文件只记录 Agent 不看就会做错的领域规则。

## 何时用本 skill（路由锚点）

**当用户消息里出现「妙搭应用名 / app_id」+ 以下任一意图，路由本 skill，不要走 lark-event 或 lark-openapi-explorer：**

- 「（每天 / 定时 / 每 N 小时 / 每周 X）自动跑 / 自动触发 / 定时同步」→ `+automation-create --trigger-type cron`
- 「数据表 / 记录 / 表里 X 字段（新增 / 更新 / 删除 / 变化）时（触发 / 通知 / 处理）」→ `+automation-create --trigger-type record-change`
- 「（webhook / 外部回调 / 外部系统调用 / HTTP 触发）」→ `+automation-create --trigger-type webhook`
- 「（审批 / 报销 / 请假 / 出差）（通过 / 拒绝 / 提交 / 撤回）后自动 X」→ `+automation-create --trigger-type feishu-approval`
- 「这个应用配了哪些（自动化 / 触发器 / 定时任务）」→ `+automation-list`
- 「（暂停 / 停用 / 先别自动跑 / 关掉自动触发）某个（触发器 / 定时任务 / 自动化）」→ `+automation-disable`（不是 update 改条件、不是 delete——本 skill 不提供删除）
- 「启用 / 启动已有 trigger」→ 先核对现有状态；只启用时不要修改源码或发布应用。
- 「换 / 重置 webhook 回调地址 / URL」→ `+automation-update --reset-url --app-env <preview|runtime>`
- 「换 / 重置 / 轮换 webhook token / bearer」→ `+automation-update --reset-token`
- 「触发器没反应 / enable 了不触发 / 为什么没执行 / 验证一下触发器」→ 先按「未触发时的诊断顺序」诊断；对 UPSERT 和 feishu-approval 仅验证配置边界，不承诺 handler 或 live 验证。

**边界（防误路由）**：`lark-event` 是**实时事件流消费**（agent 长连接订阅事件），不管妙搭应用触发器的**配置**；用户说「配 / 设置一个触发器」而不是「订阅事件流」时，本 skill 才是正确选择。「审批通过触发」在妙搭应用语境下属于本 skill 的 `feishu-approval` 类型，不是 lark-event。

### 回应「怎么配」类问题的正确姿势

用户问「怎么配 / 怎么设置一个 X 触发器」时，**先展示完整命令模板 + 你对核心参数的推断**（让用户能确认你理解对了），再追问缺失的必填项（`--name` 之类）或可选项。**不要跳过展示、直接连环追问**，那样用户没法确认你有没有理解意图。

示范：用户说「报销审批一旦通过就自动触发处理，怎么配？」
- ✅ 正确：先写出「这是 feishu-approval 类型，命令模板：`apps +automation-create --app-id <id> --name <name> --trigger-type feishu-approval --event-type approval_instance --instance-status APPROVED [--approval-code <code>]`。需要你确认：(1) 触发器名 `<name>`；(2) 是否限定特定审批流程——限定就传 `--approval-code`（从飞书审批管理后台拿），不传则匹配所有审批定义」。
- ❌ 错误：直接问「叫什么名字？监听哪个审批？」——用户没法确认你有没有把「审批通过」映射到 `--event-type approval_instance --instance-status APPROVED`。

同理，cron/record-change/webhook 三类的「怎么配」都遵循此模式：先给命令 + 参数推断，后追问缺项。

## 命令路由

| 命令 | 用途 | Risk |
|---|---|---|
| `+automation-list` | 列出应用所有触发器（可按类型过滤、`--all` 聚合翻页） | read |
| `+automation-get` | 查看单个触发器完整配置（Webhook Bearer Token 恒脱敏） | read |
| `+automation-create` | 创建触发器，四类共用一条命令，按 `--trigger-type` 分派 | write |
| `+automation-update` | 改条件/描述，或经专用 flag 管理 Webhook URL·Token | high-risk-write |
| `+automation-enable` | 启用触发器（`status→enabled`，开始自动触发） | write |
| `+automation-disable` | 停用触发器（`status→disabled`，停止触发，不删除） | write |

触发器以 **应用内唯一的 `--name`** 定位（不是 id）。所有单条命令都用 `--app-id` + `--name`；名字忘了先 `+automation-list` 查。

## 四类触发器 payload

`--trigger-type` 用面向 Agent 的 kebab-case（`cron` / `record-change` / `webhook` / `feishu-approval`），CLI 内部转 snake_case 下推。类型专属 flag 只在对应类型生效。

### cron（定时）

```bash
+automation-create --app-id <id> --name daily --trigger-type cron \
  --cron '0 9 * * *' [--timezone Asia/Shanghai]
```

- `--cron` 是**五段式**（`minute hour day month weekday`），非六段。
- **最小间隔 30 分钟**：`--cron '* * * * *'`（每分钟）或 `*/n`（n<30）会被 CLI 本地拦截报错；后端也会二次校验。
- `--timezone` 缺省补 `Asia/Shanghai`（IANA 时区名）。

### record-change（记录变更）

```bash
+automation-create --app-id <id> --name onUpd --trigger-type record-change \
  --table <table_name> --event UPDATE [--fields '["status"]']
```

- `--event` 是**大写枚举**：`INSERT` / `UPDATE` / `UPSERT` / `DELETE`（CLI 会 uppercase，但请按枚举传）。
- `--table` 是应用数据库里的**表名**（对应 `+db-table-list` / `+db-table-get` 输出里 `.name` 字段的值），必填。妙搭应用的 dataloom 表以名称作为稳定标识符，没有独立的 `table_id`。
- `--fields` 是 JSON 字符串数组，仅对 `UPDATE`/`UPSERT` 有意义；`'["*"]'` 表示监听所有字段；不传表示不限定字段。

### webhook（外部回调）

```bash
+automation-create --app-id <id> --name hook --trigger-type webhook \
  [--white-ip-list '["1.1.1.1","2.2.2.2"]']
```

- 创建时可选 `--white-ip-list`（JSON 字符串数组）限制回调来源 IP。
- 回调 URL 分 **preview / runtime 两套**，创建时不回显；用 `+automation-get` 查当前配置，用 `+automation-update --reset-url --app-env <preview|runtime>` 轮换。
- Bearer Token 是回调鉴权凭证，见下方「凭证脱敏与一次性回显」。

### feishu-approval（飞书审批）

```bash
+automation-create --app-id <id> --name apv --trigger-type feishu-approval \
  --event-type approval_instance --instance-status APPROVED [--approval-code <code>]
```

- `--event-type` 必填，取 `approval_instance` 或 `approval_task`，决定状态用哪套 flag：
  - `approval_instance` → `--instance-status`（可重复）
  - `approval_task` → `--task-status`（可重复）
- **领域规则**：状态按 `event-type` 分桶校验，两桶枚举**不完全相同**（`PENDING`/`APPROVED`/`REJECTED`/`REVERTED`/`OVERTIME_CLOSE`/`OVERTIME_RECOVER` 两桶共享；`TRANSFERRED`/`ROLLBACK`/`DONE` 仅 task 有；`CANCELED`/`DELETED` 仅 instance 有）；传错桶的状态会被 CLI 本地拦截，错误信息会打印该桶的合法值列表。具体枚举见命令 `--help`。

## approval-code 获取路径

`--approval-code` **可选**。不传时匹配所有审批定义；要限定某个审批流程时，从**飞书审批管理后台**获取具体的 code 传给它。触发器 OpenAPI 不提供审批定义查询能力，具体 code 需去审批管理后台查。

## 凭证脱敏与一次性回显（安全关键）

- `+automation-get` / `+automation-list`：**恒不返回明文 Bearer Token**——`trigger_condition.token_value` 被抹为 `null`。用户想知道「token 是什么」时，list/get 都查不到明文。
- `+automation-update --enable-token` / `--reset-token`：明文 Bearer Token **仅当次 stdout 回显一次**，同时 stderr 打印一次性告警：
  ```text
  warning: this bearer token is shown only once and is NOT stored by lark-cli — copy it now and store it in your own secret manager.
  ```
- Webhook URL 同理：`--reset-url` 后新 URL 仅当次回显一次，旧 URL 立即失效。
- CLI 不落盘任何明文 token/URL（不写 cache / config / recent / debug log / 错误信息）。
- **Token 丢失只能 reset**：找不回，唯一恢复方式是 `+automation-update --reset-token`（旧 token 同时失效）。

## 高危确认

`+automation-update` 整体是 `high-risk-write`，任何一次调用都需显式 `--yes`；缺少时框架会要求确认（退出码 10）。**不要自动补 `--yes`**——需用户明确确认后再加。以下 Webhook 动作 flag 尤其不可逆：

- `--reset-url`（旧回调 URL 立即失效，需配 `--app-env preview|runtime`）
- `--reset-token`（旧 token 立即失效）
- `--disable-token`（关闭 token 校验，**不可逆**）

四个 Webhook 动作 flag（`--reset-url` / `--enable-token` / `--disable-token` / `--reset-token`）**每次只能传一个**。不确定影响时先跑 `--dry-run` 看将发出的请求（不含明文）。

### 执行前必须完成的确认步骤（高危写强制协议）

**在带 `--yes` 执行任何高危写之前，Agent 必须先完成以下 3 件事**，缺一不可——即使用户口气很急、即使命令一眼就明：

1. **确认目标唯一**：不允许"猜名字"或"批量试所有可能的名字"。若不确定 `--name`，先 `+automation-list --app-id <id>` 让用户在候选中点名；`--name` 不明的绝不执行写操作，更不要 for 循环批量试。
2. **确认可选参数已定**：`--reset-url` 必须由用户明确指定 `--app-env preview` 还是 `runtime`；不要默认取 runtime 或 preview。同一触发器的 preview/runtime 是两条独立的 URL，误重置另一条不可回退。
3. **告知不可逆后果并等确认**：把即将发生的 3 件事复述给用户——（a）旧 URL/Token 立即永久失效；（b）新 URL/Token 仅当次回显一次、CLI 不保存；（c）本次操作无法撤销——等用户回复"确认"再加 `--yes` 跑。

只要有一项没做，就先跟用户对齐、不要执行。这些是 skill 层的护栏，不是 CLI 层的（CLI 只强制 `--yes`，不强制上面 3 件事）。

## ⚠️ 安全告警：无鉴权公网回调组合态

`--disable-token`（关闭 Bearer Token 校验，不可逆）**叠加** `--white-ip-list '[]'`（清空 IP 白名单）会让 Webhook 触发器进入「**无鉴权公网回调**」组合态——**任何来源都能触发该 Webhook**，没有任何一道防线拦截。

- 两道防线：Token 校验（谁能调）+ IP 白名单（从哪能调）。**不要同时关闭这两道防线。**
- 若确需关闭 Token（例如对端无法带 Bearer 头），务必**保留 IP 白名单**收敛来源；反之若要放开 IP，务必**保留 Token 校验**。
- 用户同时要求「关 token 校验 + 清空 IP 白名单」时，Agent 的正确响应是**在识别到该请求的第一时间**（不要等命令跑失败才补警告）向用户输出以下 3 件事，再等确认——不要只描述"没有任何防线"就停下：
  1. 复述后果：这会形成无鉴权公网回调，任何来源都能触发。
  2. **主动给出替代方案**：明确建议"要么只关 Token 保留 IP 白名单，要么只放开 IP 保留 Token"，让用户在保留一道防线的两条备选里选一条。
  3. 只有用户明确回复"我理解风险、就是要两道都关"时，才继续按高危写协议（见上节「执行前必须完成的确认步骤」）走。

## 默认 disabled

`+automation-create` 创建后触发器**默认 disabled**，不会自动触发。需 `+automation-enable` 才开始按条件自动运行（且触发器执行的是**线上已发布**的应用代码——应用未发布时即便 enable 也不会有实际效果）。

**Agent 行为约束**：用户只说"创建/配一个触发器"时，**不要**主动在同一个 turn 里 `+automation-enable`。让用户自己在下一轮决定是否启用；主动启用会：
- 让 webhook 类型立即可被外部调用（原本用户可能只是想"备好 URL 稍后用"）
- 让 cron 到点真实触发（原本用户可能想"先建好观察配置"）
- 让 record-change 立即响应表变更

创建成功后的推荐话术：`已创建 <name>，当前 disabled；需要真正开始自动运行时告诉我，我用 +automation-enable 启用它。` **不要**在创建成功后立即启用，即使 skill 里说"需 enable 才自动触发"——这条是给用户的说明，不是给 agent 的行动指令。

## 本地全栈 Trigger 闭环

当用户希望触发器实际执行业务代码时，先确认当前工作区是已初始化的应用项目，并读取其中与触发器任务匹配的 guide。

`--name` 是应用内唯一的 trigger 定位键；代码侧绑定名称必须与它逐字相同。不得用 trigger ID 或方法名代替它。具体 handler 语法和接入方式以项目 guide 为准。

### 仅创建/配置触发器

适用于 cron、record-change、webhook 和 feishu-approval。用 `+automation-create` 创建，并省略 `--status` 或显式传 `disabled`，然后报告 name 和 disabled 状态。

不要传 `--status enabled`，也不要写 handler、commit/push、release 或 enable；更不能把创建 API 成功称为“可运行”。默认 disabled 是这个意图的终点，不是稍后自动 enable 的待办。

### 仅启用已有 disabled trigger

用户只要求启用已存在且 disabled 的 trigger、没有要求修改代码或制造真实 runtime 事件时，先用 `+automation-get` 核对 name、类型和 disabled 状态，再用 `+release-list --status finished --page-size 1` 核对是否存在已完成线上 release。release history 只能证明当前线上应用有已发布版本，不能证明该 trigger name 已绑定 handler。不存在 finished release 时说明 enable 只会改变配置状态、当前没有可执行的线上版本；存在时说明它会对当前线上应用激活这条 trigger 配置。随后按用户要求执行 `+automation-enable`，再用 `+automation-get` 确认 enabled。

这条路径不得修改 handler、commit/push 或 release。未发布时不得自动创建 release，也不得声称 trigger 已开始实际运行。即使存在 finished release，也只能把 enable 报告为配置激活；没有 handler 来源或 runtime 结果时，不得声称业务 handler 已存在、已运行或可用。若用户期待尚未发布的本地改动生效，或检查后发现确实需要新增/修改 handler，转到下方“实现或更新 handler 后发布并启动/测试”路径；不要为单纯 enable 发布整个 `sprint/default`。

对 UPSERT 或 feishu-approval 只改变配置状态；由于本 guide 没有其已证实的 handler、投递或 live 验证契约，启用后也不得声称业务代码已运行或触发器已实测可用。

### 测试已有线上 trigger（不改代码）

用户要求测试已经发布的 trigger、没有要求修改 handler 时，先用 `+automation-get` 核对 name、类型、当前状态，再用 `+release-list --status finished --page-size 1` 确认应用存在 finished release，并说明本次测试覆盖当前线上代码。没有 finished release 时停止 runtime test，只报告配置状态；不得为测试自动修改源码、commit/push 或 release。release history 不证明该 name 已绑定 handler，真实 probe 的结果才是本次验证证据；若用户期待本地未发布改动，改走代码变更闭环。

记录测试前状态，并在任何临时 enable 之前完成两类授权和全部 preflight：测试请求已明确包含临时 enable，或另行取得 enable 授权；同时按下方“运行时验证的操作级授权”确定具体事件、影响、载荷、观察结果和清理。原本 disabled 时完成这些门槛后才临时 enable，并在验证结束后恢复 disabled；原本 enabled 时不要无意义切换状态。原本为 disabled 时，无论 probe 成功、失败、结果不确定，还是临时 enable 后提前结束或中断，最终都必须 `+automation-disable` 并回读 disabled，不得停在 enabled。测试意图本身不决定数据库记录、Webhook 请求或其他事件载荷。

### 仅完成 handler（不发布/不启用）

仅对 cron、webhook、record-change 的 `INSERT`、`UPDATE`、`DELETE` 使用此路径。

创建或定位已明确 name 的 disabled trigger，读取项目 guide，按其要求实现同名业务 handler，完成本地验证。只在既有 Git 确认或预授权下 commit/push；停止在 `+release-create` 和 `+automation-enable` 之前。用户没有明确“发布好”时，先问，不能默认把完整应用上线。

### 把 handler 发布好，但先不要启动

仅对 cron、webhook、record-change 的 `INSERT`、`UPDATE`、`DELETE` 使用此路径。先用 `+automation-get` 定位；不存在时用 `+automation-create` 创建同名 disabled trigger，再次回读确认。已存在时记录它是否 enabled。按项目 guide 完成同名业务 handler 并本地验证后，commit、`git push origin sprint/default`。若 trigger 已 enabled，先说明发布前必须临时停用以及可能造成的运行中断，并取得这次临时停用授权；未获授权时停止在发布前。取得授权后，在发布前执行 `+automation-disable`，并再次用 `+automation-get` 确认 disabled。随后发布完整应用：

```bash
lark-cli apps +release-create --as user --app-id <app_id> --branch sprint/default
```

若 `+release-create` 本身返回错误或未返回 `data.release_id`：视为确认未创建本轮 release（新代码未上线），原本 enabled 的 trigger 恢复 enabled 并回读、原本 disabled 的保持 disabled，然后停止；若因超时等导致创建结果未知，保持 disabled，先用 `+release-list --status finished --page-size 1` 核对是否已产生新 release 再决定。取得 `data.release_id` 后，对**这一轮** ID 调用 `+release-get`：`publishing` 时每 20 秒继续轮询，整体最多约 5 分钟；超时且状态仍不确定时报告 `release_id` 和当前 status，并保持 disabled；只有 `data.status=finished` 才算完成。确认 `failed` 且新代码未上线时，原本 enabled 的 trigger 恢复 enabled 并回读，原本 disabled 的保持 disabled。release 是整个应用上线，可能影响既有线上功能；未获得启动或测试授权时，finished 后始终保持 disabled，不执行 `+automation-enable`。

### 实现或更新 handler 后发布并启动/测试

仅当本轮确实需要新增或修改 cron、webhook、record-change 的 `INSERT`、`UPDATE`、`DELETE` handler，且用户要求把这次代码发布后启动或测试时，才使用此路径。按以下不可跳过的顺序执行：

1. 用 `+automation-get` 定位并记录发布前状态，再核对其 `--name`、类型并读取项目 guide；不存在时用 `+automation-create` 创建同名 trigger 并保持默认 disabled。
2. 按项目 guide 完成同名业务 handler 并本地验证。
3. 在 Git 已确认/预授权时 commit，然后执行 `git push origin sprint/default`。
4. 若 trigger 当前 enabled，先说明发布前必须临时停用以及可能造成的运行中断，并取得这次临时停用授权；未获授权时停止在发布前。取得授权后执行 `+automation-disable`，并再次用 `+automation-get` 确认 disabled；原本 disabled 时不要无意义切换状态。
5. 执行 `+release-create --branch sprint/default`。若该命令本身返回错误或未返回 `data.release_id`：视为确认未创建本轮 release（新代码未上线），原本 enabled 的 trigger 恢复 enabled 并回读、原本 disabled 的保持 disabled 后停止；若因超时等导致结果未知，保持 disabled，先用 `+release-list --status finished --page-size 1` 核对是否已产生新 release 再决定。取得 `data.release_id` 后进入下一步。
6. 对该 ID 执行 `+release-get`，只有 `data.status=finished` 才能继续；`publishing` 时每 20 秒继续轮询，整体最多约 5 分钟。超时且状态仍不确定时停止本轮轮询、报告 `release_id` 和当前 status，并保持 disabled；确认 `failed` 时报告发布失败，原本 enabled 的 trigger 仅在确认新代码未上线后恢复 enabled，原本 disabled 的保持 disabled。发布状态仍不确定时不得进入 enable、probe 或状态恢复分支。`is_published=true` 不能代替这轮发布完成。
7. **仅启动**：取得持续启动授权后执行 `+automation-enable`，并用 `+automation-get` 确认 enabled；到此结束，不制造 runtime probe。
8. **测试（含“启动并测试”）**：先按下节“运行时验证的操作级授权”完成全部 preflight，包括具体事件、sibling 影响、载荷、观察结果和清理；完成前保持 disabled，之后才执行 `+automation-enable` 并回读，再由已授权主体制造真实 runtime 条件并核验业务结果。若同时明确要求持续启动，只有 probe 成功后才保持 enabled。
9. 若用户仅要求测试而不是持续启动，只在本轮 release 已 `finished` 且 probe 成功后恢复到发布前状态：原本 disabled 或本轮新建的 trigger `+automation-disable` 并回读；原本 enabled 的可保持 enabled。无论用户是仅测试还是启动并测试，probe 失败、结果不确定或 enable 后提前结束时，一律 `+automation-disable` 并回读 disabled；不得把“发布前 enabled”当作失败后的恢复依据，因为本轮新代码已经上线。只有旧 release 已回滚并验证，或修复后重新发布且 probe 成功，才可再次 enabled。恢复失败时明确报告当前状态。

没有通用的 `automation-debug` 或 trigger 日志 shortcut。缺少安全事件入口、匹配环境或可观察结果时，记录 blocked，不能编造测试成功。

### 运行时验证的操作级授权

启用 trigger 的授权不等于制造 runtime 事件的授权，测试授权也不等于任意数据库写入授权。cron 可等待计划时间；webhook 只能向既有 runtime URL 发送已授权、安全且不泄露凭证的请求。record-change 在执行任何 DML 前，必须明确并取得覆盖以下作用域的授权：环境、表、操作、精确测试记录或筛选条件、payload、预期结果和清理方式。

优先使用专用测试记录，不要任取线上业务记录。用户已明确授权精确、可撤回的测试夹具及其清理时，不机械追加一轮确认；目标或影响仍不清楚时必须停下。record-change probe 前先执行 `+automation-list --trigger-type record-change --all`，检查同一环境、表和操作可能命中的其他 enabled trigger；若存在 sibling match，必须说明聚合业务影响并取得覆盖这些影响的授权，或换成隔离夹具/经授权临时停用后再测。`UPDATE` 要限定精确条件并保留恢复方式；`INSERT` 要预先约定清理；恢复 UPDATE 或清理 INSERT 也可能再次触发自动化，必须纳入影响说明和授权。`DELETE` 必须遵循 [lark-apps-db-execute.md](lark-apps-db-execute.md)：先 `SELECT count(*)`、执行 `--dry-run`，展示影响后取得针对该删除目标的明确授权，再带 `--yes` 执行；清理动作若包含未预先授权的删除，同样走该门槛。

缺少安全、已授权且可清理的事件入口时，记录 blocked，不得用“测试一下”推导任意 online 数据写入。

### UPSERT 与飞书审批边界

record-change 的 UPSERT 可创建 disabled 配置，但当前没有已证实的运行时代码契约；不得静默按 UPDATE 处理，也不得承诺 handler 或 live 验证。

feishu-approval 可创建 disabled 配置，并读取或更新 `event_type`、对应 status 和可选 `approval_code`。当前没有已证实的运行时 handler 契约或实际投递验证；不要把 enable 或审批 API 成功称为业务代码已执行。

### 未触发时的诊断顺序

按 `--name` / 项目 guide 要求的代码接入 → 本轮 release `finished` → enabled 状态 → 类型条件、环境和已有日志的顺序排查。客户审批投递故障属于服务端事件投递排查，不要归因于此 SOP 或改写无关业务代码。

## 常见错误与决策场景

| 现象 / 用户意图 | 正确处理 |
|---|---|
| 创建报名字冲突（`--name` 应用内唯一） | 换名或加后缀重试 |
| cron 报非法 / 间隔过小 | 检查是否五段式、分钟字段是否 `*` 或 `*/n`(n<30) |
| `--reset-url` 报缺 app-env | 补 `--app-env preview` 或 `--app-env runtime` |
| 想把 cron 触发器改成 webhook（跨类型改） | update 不支持换类型，本 skill 也不提供删除。旧触发器只能 `+automation-disable` 停用（保留在应用里），另建一个 webhook 触发器；若要真正清理旧触发器，请到妙搭 web 手动删除 |
| 触发器 enable 了但不触发 | 已证实的 cron、webhook、record-change（INSERT/UPDATE/DELETE）按「未触发时的诊断顺序」排查；UPSERT 和 feishu-approval 仅核对配置边界，不承诺 handler 或 live 验证。 |
| 「token 泄露了」 | 优先 `+automation-update --reset-token --yes` 轮换（旧 token 立即失效），而非直接 disable-token 关校验 |
| 「回调 URL 泄露了」 | `+automation-update --reset-url --app-env <env> --yes` 轮换 |

## 不在本 skill 范围

- 审批定义查询、Webhook 消费端实现、实时触发日志 tail：本期不支持。
- 身份选择、权限不足处理、exit-10 审批、通用「禁输出密钥」红线、高风险操作通用框架：见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)，不在此重复。

# apps cache 域命令（应用运行时缓存调试）

调试妙搭应用的运行时缓存：查看某个缓存 key 的内容、删除单个 key、清空某个环境的全部缓存。缓存是应用为了加速而临时存放的数据，删除或清空后，应用下次用到时会自动重新取最新数据。命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。

## 何时用

用户要排查「某个缓存 key 里存的是什么 / 有没有命中」、想删掉某个 key 让应用下次拿到最新数据、或想清空某个环境的缓存做快速恢复时。

## 命令一览

| 命令 | 做什么 | 关键参数 |
|---|---|---|
| `+cache-get` | 查一个缓存 key 的内容与信息 | `--key`、`--environment`、`--format` |
| `+cache-delete` | 删一个缓存 key（重复删不会报错；不需 `--yes`） | `--key`、`--environment` |
| `+cache-clear` | 清空指定环境下的全部缓存（**高危，须先向用户二次确认**） | `--environment`、`--yes` |

> 所有命令都需 `--app-id`。

## 约定（先读）

- **环境 `--environment dev|online`（可省略）**：缓存按运行环境隔离。不指定时按应用当前的环境配置自动选择——有多环境的应用默认落到开发环境 `dev`，没有多环境的就是线上 `online`；返回结果里的 `environment` 会告诉你这次实际操作的是哪个环境。想固定就显式传。
- **缓存 key 用 `--key` 传**：传业务里使用的那个 key；是否合法（非空、长度等）由服务端校验，不合法会返回错误。
- **风险分级**：`+cache-clear` 会清掉整个环境的缓存，是高危操作，不带 `--yes` 会被确认关卡拦下，且**必须先拿到用户对本次清空的确认**（判据见 [+cache-clear](#cache-clear高危)）；`+cache-delete` 只删单个 key、影响小，不需 `--yes`。
- **`+cache-get` 的内容有两种展示**：`--format json`（默认）原样返回缓存内容，适合精确比对；`--format pretty` 会把内容格式化展开，更便于阅读。

## 各命令

### +cache-get
按 `--key` 查单个缓存。命中时返回：是否存在、剩余有效期（TTL）、内容及其大小；未命中（或已过期）时只返回 `exists=false`、不带内容。

> 每次查询都会连内容一起返回（没有「只看信息、不取内容」的模式），内容可能较大——只是想确认「在不在 / 还有多久过期」时，留意别占用太多上下文。

```bash
lark-cli apps +cache-get --app-id app_xxx --key spotbonus:2026:winners:list:v1
lark-cli apps +cache-get --app-id app_xxx --environment online --key <key> --format pretty
```

### +cache-delete
删一个缓存 key。**重复删、或删一个本就不存在的 key，都算成功**（返回 `deleted_key_count=0`）、不会报错；删中则返回 `deleted_key_count=1`。删掉后应用下次会自动重新取最新数据，影响小，故不需 `--yes`。

**响应里的 `deleted_key_count` 别读错**——它是「本次是否真的删掉了东西」的唯一判据：

| `deleted_key_count` | 含义 | 该怎么向用户表述 |
|---|---|---|
| `1` | 命中并删掉了 | 「已删除该 key」 |
| `0` | 请求成功，但没有删掉任何 key——这个 key **本来就不存在或已过期** | 「该 key 原本就不存在／已过期，无需删除」——**不要说成「已成功删除」** |

要证明「删除生效了」，用「删前 `+cache-get` 确认存在 → `+cache-delete` 拿到 `deleted_key_count=1` → 删后 `+cache-get` 得到 `exists=false`」这条链；只靠删后一次 miss 是不够的，因为 key 从一开始就不存在时（`deleted_key_count=0`）结果完全一样。

```bash
lark-cli apps +cache-delete --app-id app_xxx --environment dev --key <key>
```

### +cache-clear（高危）
清空当前应用在**指定环境**下的全部缓存，用于定位不到具体 key 时的快速恢复。影响面是整个环境，必须带 `--yes`；返回本次清除的 key 数量。

> [!CAUTION]
> **默认流程是「先确认、后执行」，不是「直接清」。** 除下表判定为「已确认」的情形外，**不允许在首次调用就自己带上 `--yes`**——用户提出清理请求 ≠ 用户确认了这次清理。
>
> 未拿到确认时，你只能做这两件事之一，然后**停下来等用户回话**：
> 1. 用 `--dry-run` 预览（不触发门禁、不产生任何真实清理），把将执行的请求给用户看；
> 2. 或者干脆不调命令，直接把「应用 + 环境 + 会清掉该环境全部缓存」讲清楚并请用户确认。
>
> 已经拿到确认后，才在原命令末尾补 `--yes` 执行。**看到 exit 10 / `confirmation_required` 不是「补 `--yes` 重试」的信号**，它只是告诉你门禁生效了；该不该补，取决于用户有没有确认过。

**什么算「已确认」（零歧义判据）**：看用户这轮的原话里，有没有对「清空这个环境」的授权表述。

| 用户原话 | 算不算确认 | 你该做什么 |
|---|---|---|
| 「帮我清一下 app_xxx 的 online 环境缓存」 | ❌ 不算（这是请求，不是确认） | 先 `--dry-run` 或直接请用户确认，**停下等回话** |
| 「清一下缓存」（连环境都没说） | ❌ 不算，且环境未定 | 请用户同时确认「清哪个环境」，**严禁自己选 `dev` 或 `online`** |
| 「我确认清 dev，不要动 online」 | ✅ 算（含确认表述 + 明确环境） | 显式带 `--environment dev --yes` 执行 |
| 「确认清 online，不用再问」／「是的，清吧」（承接你上一轮的确认提问） | ✅ 算 | 显式带 `--environment online --yes` 执行 |

线上环境额外一条：`--environment online` 是生产数据，**即使用户已明确指名 online，也仍需要上表意义上的确认表述**才可执行；缺确认就只出 `--dry-run` 预览。

```bash
# 1) 未确认：只预览，不清理（--dry-run 不触发门禁、不产生真实动作）
lark-cli apps +cache-clear --app-id app_xxx --environment online --dry-run

# 2) 用户确认后：补 --yes 执行
lark-cli apps +cache-clear --app-id app_xxx --environment dev --yes
```

## 错误与边界

- **key 不合法 / 缓存服务暂时不可用**：命令会返回带说明的错误，按 `error.hint` 转述给用户；「服务暂时不可用」这类可稍后重试。

## Agent 规则

- **写操作先定环境**：`+cache-clear` / `+cache-delete` 不指定 `--environment` 时会落到自动选中的环境——**没有多环境的应用会直接作用到线上 `online`（生产）**。不确定应用有没有多环境时，写操作显式传 `--environment`；纯查看（`+cache-get`）影响小，可以省略。
- **`+cache-clear` 一律先确认再清**：不带确认就执行是本域最容易犯的错。**「用户让我清缓存」不构成授权**——授权指用户对「清空这个环境」有明确确认表述（判据表见 [+cache-clear](#cache-clear高危)）。没有它，就只出 `--dry-run` 预览或口头确认请求，然后停下等回话；**不要在首次调用就自带 `--yes`，也不要看到 exit 10 就补 `--yes` 重试**。拿到确认后再补 `--yes`，并始终显式带 `--environment`。
- **排查缓存内容优先用 `+cache-get`**：想看结构化、易读的内容用 `--format pretty`；想拿原始内容做精确比对用默认 JSON。
- **删 key 前先对齐 key**：用户只描述了业务含义、没给准确 key 时，先确认再删——删错影响也有限（应用会自动重建），但仍应避免误删。

# lark-apps 云端会话开发

适用：用户希望让云端妙搭 Agent 生成或迭代应用，而不是把代码拉到本地开发。

## 核心流程

整个开发在云端进行：本地只负责「发消息 + 轮询状态」，不拉源码、不产出代码、不启动本地 dev server。所有 session/chat 命令都以用户身份执行（`--as user`）。

### 资源模型：app → session → turn

三层父子关系，下层都挂在上层之下：

- **app（应用资产）**：一个妙搭应用，由 `+create` 创建并拿到 `app_id`。`--app-type` 沿用 SKILL.md「选择开发路径」判定的类型（有数据库需求→`full_stack`；纯前端交互、未提数据库→默认 `frontend`），云端生成不写死 `full_stack`。
- **session（会话）**：一个 app 下的一段独立对话上下文，由 `+session-create` 创建并拿到 `session_id`。一个 app 可有多个 session；`is_active` 表示该 session 当前是否可写（可发起对话）。
- **turn（轮）**：一个 session 里的一轮交互 = 一条用户消息 + 妙搭 Agent 针对它的生成/迭代。`+chat` 发一条消息就发起一轮；轮的句柄是 `turn_id`，状态看 `latest_turn.status`。

### 执行模型：异步 + 轮询

`+chat` 把消息入队后**立即返回、不等生成完成，响应不带 `turn_id`**；本轮状态与轮询节奏全靠 `+session-get` 读 `latest_turn.status` / `is_streaming` / `next_poll_after_ms`。

`+session-get` 关键字段：

- `is_streaming`：当前是否有一轮正在跑（`true`=还在生成）。
- `latest_turn.status`：最近一轮的状态，只有 `running` / `completed` / `failed` / `cancelled`。
- `latest_turn.turn_id`：最近一轮的句柄（`+session-stop --turn-id` 用它）。
- `latest_turn.user_message`：本轮用户发的消息。
- `latest_turn.messages`：本轮完成后回看全貌的消息列表，按时序排列、每条带 `role`（用户消息、模型回复、工具调用等都在内，role 取值如 `user` / `assistant` / `tool`）。注意它在 `latest_turn` 仍 running/初始化期可能为空——该轮**进行中**的实时进展改用 `+session-messages-list --turn-id <latest_turn.turn_id>` 读（见下方轮询规则）。
- `queued_messages` / `queued_count`：还没开始跑、排在后面的消息。
- `next_poll_after_ms`：建议的下次轮询间隔（毫秒，固定值）；非空时优先用它。

轮询规则：

- 节奏按 [初始化 vs 增量修改](#初始化-vs-增量修改) 判定：增量 5-10 秒一次；初始化 60-120 秒一次；`next_poll_after_ms` 非空时用它。
- `is_streaming=true`、`building` / `running` / `streaming` 表示仍在生成，继续轮询，不傻等也不提前放弃；初始化阶段单次 sleep 拉到 60-120 秒，进入 `streaming` 或属增量修改时切回 5-10 秒。
- `is_streaming=false` 且 `latest_turn.status=completed` 表示本轮完成，可发下一条。
- `failed` / `cancelled` 时转述错误字段或 hint，由用户决定是否重试，不要静默重发。
- 不知道某 app 有哪些 session 时，先 `+session-list --app-id <id>`，再选最近活跃的或让用户确认，别直接猜 `session_id`。
- 要中止正在运行的一轮，从 `+session-get` 的 `latest_turn.turn_id` 取值，再调用 `+session-stop --turn-id <turn_id>`。
- 状态与节奏看 `+session-get`，本轮实时内容看 `+session-messages-list`：想在 running 期间向用户播报"云端 Agent 此刻在做什么"，用 `+session-messages-list --turn-id <latest_turn.turn_id>` 读已产出的增量消息（running 期间即可读，不必等本轮结束）。复用上面的轮询节奏、不另起更密的轮询；续拉时把上次响应的 `next_page_token` 作 `--page-token` 只取新消息，转述时简述进展、不原样打印整段消息或工具输出。

### 典型链路

```bash
# 1) 建 app，拿 app_id（--app-type 用主路由判定的类型；此例"待办应用"要存待办→full_stack，
#    若是纯前端交互工具且未提数据库则用 frontend）
lark-cli apps +create --name "待办应用" --app-type full_stack \
  --description "支持新增、完成、筛选待办"

# 2) 在该 app 下建 session，拿 session_id
lark-cli apps +session-create --app-id app_xxx

# 3) 发消息发起一轮（异步入队，立即返回，无 turn_id）
lark-cli apps +chat --app-id app_xxx --session-id sess_xxx --message "做一个待办清单页面"

# 4) 轮询本轮状态；完成后从 latest_turn.messages 读取结果
lark-cli apps +session-get --app-id app_xxx --session-id sess_xxx

# 找该 app 已有的会话（续聊/不确定 session 时用）
lark-cli apps +session-list --app-id app_xxx
```

## 完成态不等于发布态

通用发布态判定（is_published 语义、开发态链接拼接、发布态链接来源）见 SKILL.md「发布态护栏」。本 reference 只补云端会话特有的措辞：

- `+session-get` 返回 `is_streaming=false` 且 `latest_turn.status=completed`，只说明本轮云端生成/迭代结束，不等于已发布部署。
- 如果只完成了云端会话、没有确认发布完成，就明确告诉用户“开发态链接可进入继续编辑，发布态是否为最新版本尚未确认”。

## 需求发送

- 只有用户明确选择云端路径，或明确说“让妙搭 Agent / 云端 AI 生成/迭代”时，才进入本 reference；不要因为用户只说“做个 X”或“给我链接”就默认云端。
- 进入云端路径后，极简需求也可直接发起生成，例如“做个投票工具”“做个站会小应用”。先按主路由判定的 `--app-type` 建 app（有数据库需求→`full_stack`，纯前端交互未提数据库→默认 `frontend`），再用 `+chat --message "<用户原话>"` 透传需求，不编造实体、字段或业务细节。
- 如果需求过泛，可在 `+chat --message` 中保留原话，并只补一句“请先生成通用版本，后续可继续迭代”，不要用多轮追问阻塞生成。

## 会话落点

| 情形 | 动作 |
|---|---|
| 全新应用 + 云端生成 | 先按主路由判定的类型 `+create --app-type <frontend\|full_stack>`（未提数据库默认 frontend）拿 `app_id`，再 `+session-create` -> `+chat` |
| 已知 app_id，用户没指定会话 | 先 `+session-list`；有活跃会话时问用户继续现有还是新开 |
| 用户说“新开一段/换个话题” | `+session-create` 后再 `+chat` |
| 用户说“接着刚才” | 复用上下文 session_id；拿不到就 `+session-list` 让用户选 |
| 用户问会话“进行到哪一步/当前状态/最新进展” | 用 `+session-get --session-id <sid>` 读状态。`+session-list` 只负责发现/选择会话，不含执行状态；它返回空不等于无状态可查（session_id 也可能来自上下文），别用 `+session-list`/`+release-list` 代替 `+session-get` 回答进度 |

## 初始化 vs 增量修改

`+chat` 单轮的耗时差距很大，取决于目标 app 是否**已初始化**。两者的轮询节奏不同，**`+chat` 前先把状态判定清楚**，不要拿"是不是第一次发消息"当代理判断——session 是新建的不代表 app 没初始化过。

### 判定规则

**已初始化**（满足任一即认为已初始化）：

1. 本地存在该 app 的项目目录（已 `+init` 或 clone 过），**且** git commit 数 > 2；
2. 应用维度（云端）至少有一个已提交的版本，按以下任一信号判断：
   - `lark-cli apps +session-get --app-id <app_id> --session-id <session_id>` 的返回里出现已提交版本信息；
   - 在 `lark-cli apps +list`（必要时配 `--keyword <name>` 定位）的目标 app 条目里 `is_published: true`。

**未初始化**（两个条件同时成立）：

1. 本地不存在该 app 的项目目录；
2. 应用维度没有任何已提交版本（即上面两路云端信号都判 false）。

### 两种 `+chat` 的行为

| 状态 | 服务端动作 | 单轮耗时 | 轮询建议 |
|---|---|---|---|
| 已初始化 → **增量修改** | 云端 Agent 在已有云端工作区上对**已提交代码**做局部修改，跳过方案设计与首次生成 | 通常分钟级 | `next_poll_after_ms` 为空时 5-10 秒一次 |
| 未初始化 → **首次初始化 + 生成** | 服务端跑完整的应用初始化流程：需求分析、技术方案、数据模型、UI 与后端代码生成、首版代码提交到云端工作区 | 视需求复杂度，**通常 20~50 分钟** | `next_poll_after_ms` 为空时 60-120 秒一次 |

初始化阶段 `+session-get` 可能长时间持续返回 `building` / `running`，是正常状态，**不要按失败处理，也不要催用户**。

## 字段注意

所有字段统一 snake_case，顶层和嵌套 turn 字段都一样：`session_id`、`is_active`、`is_streaming`、`next_poll_after_ms`、`latest_turn.turn_id`、`latest_turn.status`、`latest_turn.user_message`、`latest_turn.messages`。

`+session-stop` 只停止正在运行的当前轮，不关闭会话；停完仍可继续 `+chat`。

## 不适用

- 用户要本地写代码、改仓库、跑 dev server：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。

# apps +create

创建妙搭应用。运行时命令事实以 `lark-cli apps +create --help` 为准。

## 何时用

用来创建应用资产并拿到 `app_id`。它不负责把自然语言需求交给云端 Agent：用户要“帮我生成/迭代应用”时，先按 SKILL.md「选择开发路径」判定的 `--app-type`（有数据库需求→`full_stack`，纯前端交互未提数据库→默认 `frontend`）创建 app，再进入 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md) 用 `+session-create` / `+chat` 提交需求。

## 命令骨架

- 必填：`--name`、`--app-type`。
- app type 取值为小写 `html` / `frontend` / `full_stack`；框架按枚举精确校验（不做大小写归一），非法值直接报错。
- 可选：`--description`、`--icon-url`。

## 示例

```bash
lark-cli apps +create --name "客户调研问卷" --app-type html

lark-cli apps +create --name "JSON 格式化工具" --app-type frontend \
  --description "纯前端交互工具，无需数据库"

lark-cli apps +create --name "审批系统" --app-type full_stack \
  --description "部门审批系统，支持登录、提交申请、多级审批"

lark-cli apps +create --name "Demo" --app-type html --dry-run
```

## 输出契约

- 成功默认 JSON envelope 中读取 `data.app.app_id`，同时可用 `data.app.name` / `description` 向用户确认结果。
- pretty 输出只适合人看；后续命令需要 app_id 时，用 JSON 或 `--jq '.data.app.app_id'`。

## app type 与命名

- `--app-type` 取值与判定信号见 SKILL.md「选择开发路径」，此处不重复。
- 用户只给自然语言需求时，据此生成简洁的 `--name` 和一句 `--description` 直接创建；不满意再用 `+update` 改。

创建后按用户路径继续：

- 本地应用开发（含 html / frontend / full_stack）：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。
- 云端 Agent 生成/迭代：读 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md)。

# apps +db-execute

经妙搭服务端在应用数据库执行 SQL。运行时命令事实以 `lark-cli apps +db-execute --help` 为准。

> **写 SQL 前先看文末「平台 SQL 规范」**：妙搭底层是 PostgreSQL + 一层平台约束，SQL 内容不符合会被服务端直接拒或建出行为不对的表。最容易踩的三条：① 建业务表必须带 4 个审计列（`_created_at`/`_updated_at`/`_created_by`/`_updated_by`）+ 启用 RLS + 4 条 policy，一次调用里写全；② 人员字段用内置复合类型 `user_profile`（写入 `ROW('<user_id>')::user_profile`，查询解引用 `(field).user_id`）；③ `CREATE/DROP DATABASE·SCHEMA·USER·ROLE`、非白名单 `CREATE EXTENSION`、平台保留表 `auth`/`users` 会被硬拒，`online` 环境禁 DDL。

## 何时用

用于通过妙搭服务端执行应用数据库 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个 shortcut。写什么样的 SQL（平台约束、建表模板、`user_profile`、审计列、禁用 SQL、PG 陷阱）见文末「平台 SQL 规范」。

## 命令骨架

- 必填：`--app-id`，以及 `--sql` / `--file` 二选一（互斥）。
- `--sql`：内联 SQL 文本；传 `-` 时从 stdin 读。绝对路径文件经 stdin 传入：`--sql - < <absolute-path>`（shell 解析路径，CLI 仅接收内容）。
- `--file`：`.sql` 文件路径，需为工作目录内的相对路径（如 `--file ./migration.sql`）；绝对路径、或经 `..`/符号链接越出工作目录的路径会被拒绝。文件不在工作目录内时，改用 `--sql - < <文件路径>` 经 stdin 传入。
- `--environment` 枚举：`dev` / `online`，**不传则由服务端按应用是否开启多环境自动选择（多环境→`dev`，未开启多环境→`online`）**；要固定环境就显式传 `--environment dev|online`。**未开启多环境的应用显式传 `--environment dev` 会报错（无 dev 分支）——这类应用不传 `--environment`（走 `online`）或显式 `--environment online`**。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。
- risk 是 `high-risk-write`（SQL 可含 DML/DDL）：任何执行都需 `--yes`，否则返回 `confirmation_required` / exit 10。`--dry-run` 预览不需要 `--yes`。
- **不会自动为你包事务，事务边界需自己在 SQL 里控制**：多语句默认逐条独立提交，中间某条失败时前序语句已生效、不会回滚；若需要「要么全部成功、要么全部回滚」的原子性，请在 SQL 内显式写 `BEGIN … COMMIT`（详见下「Agent 规则」）。

## 示例

```bash
lark-cli apps +db-execute --app-id app_xxx --environment dev --sql "select * from orders limit 5" --yes
lark-cli apps +db-execute --app-id app_xxx --environment dev --file ./migration.sql --dry-run
# 绝对路径文件 / cwd 不固定：经 stdin 传入
lark-cli apps +db-execute --app-id app_xxx --environment dev --sql - --yes < /Users/.../migrations/0001_init.sql
```

## 输出契约

- 成功默认 JSON 的 `data` 按 SQL 类型自适应（不透传后端原始串）：
  - 单 SELECT → `data` 是行数组 `[{...}]`（空 → `[]`），直接 `-q '.data[].col'` 取字段。
  - 单 DML → `data = {command, rows_affected}`（如 `{"command":"INSERT","rows_affected":1}`）。
  - 单 DDL → `data = {command}`（如 `{"command":"CREATE_TABLE"}`）。
  - 多语句 → `data` 是元素数组：SELECT 为 `{command:"SELECT", rows:[...]}`，DML 为 `{command, rows_affected}`，DDL 为 `{command}`。
- pretty 会按 SELECT/DML/DDL 自适应渲染；多语句会逐条显示 Statement 摘要。
- 失败返回 typed `error`（`type:"api"`、`subtype:"server_error"`、`code`、`message`、`hint`）：失败位置在 `message` 的「(at statement N of M)」；前序是否落地 / 是否整批回滚写在 `hint`——事务内失败「Transaction rolled back; no changes persisted.」；非事务多语句前序已落地「Earlier statements were committed and not rolled back; fix statement N and re-run the remaining statements.」；首句即失败（无前序落地）「No statements were applied; fix the SQL and re-run.」。据此决定整段重跑还是只跑剩余语句。

## Agent 规则

- 该命令为 high-risk-write，执行一律需 `--yes`；无 `--yes` 会返回 `confirmation_required` / exit 10。
  - **只读查询、以及不删除/不丢失既有数据且可撤回的语句**：已授权时可直接带 `--yes` 执行。
  - **会删除或丢失既有数据、或难以撤回的语句**：先 `--dry-run` 预览（无需 `--yes`），向用户确认后再带 `--yes` 执行；不要在用户不知情时自动补 `--yes`。
- 多语句失败时，失败前的语句可能已经 commit 落地。不要整批重跑；按错误 message/hint 修失败语句，并从剩余语句继续。
- 如果需要原子性，让用户在 SQL 内显式写 `BEGIN` / `COMMIT`，不要假设 CLI 会包事务。
- 不要把数据库连接串从 env 中取出来裸连。

---

# 平台 SQL 规范

上面讲命令怎么调，这里讲**该写出什么样的 SQL**：妙搭底层是 PostgreSQL + 一层平台约束（RLS、审计列、`user_profile` 复合类型、禁用 SQL 白名单），不符合会被服务端直接拒或建出行为不对的表。看表 / 看结构用 [`+db-table-list`/`+db-table-get`](lark-apps-db.md)，别手写系统表查询模拟。

## 平台禁用 SQL（硬拒绝）

以下命中会被服务端拒，`error`（`type:"api"`）的 message/hint 会说明原因——先按 hint 修再重试，不要反复重试同一句。

| 类别 | 禁止 |
|---|---|
| 数据库级 | `CREATE / DROP / ALTER DATABASE` |
| Schema 级 | `CREATE / DROP SCHEMA` |
| 用户 / 角色级 | `CREATE / DROP USER`、`CREATE / DROP / ALTER ROLE` |
| Owner 切换 | `REASSIGN OWNED` / `DROP OWNED` |

## 建表规范（CREATE TABLE）

新建业务表必须：4 个审计列 + 启用 RLS + 4 条默认 policy，**放在同一次 `+db-execute` 调用里**（RLS / policy / COMMENT / INDEX 一起）。裸表名，不写 `public.` 或 schema 前缀。

```sql
CREATE TABLE IF NOT EXISTS <table> (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  -- ... 业务列 ...
  name varchar(100) NOT NULL,
  _created_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  _created_by user_profile DEFAULT (
    CASE
      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
    END
  ),
  _updated_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  _updated_by user_profile DEFAULT (
    CASE
      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
    END
  )
);

ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;

CREATE POLICY service_role_bypass_policy ON <table>
  TO service_role USING (true);

CREATE POLICY "修改全部数据" ON <table>
  AS PERMISSIVE FOR ALL TO authenticated USING (true);

CREATE POLICY "查看全部数据" ON <table>
  AS PERMISSIVE FOR SELECT TO authenticated, anon USING (true);

CREATE POLICY "修改本人数据" ON <table>
  AS PERMISSIVE FOR ALL TO authenticated USING (
    (current_setting('app.user_id'::text) = ANY (ARRAY[]::text[]))
    AND (current_setting('app.user_id'::text) = ((_created_by).user_id)::text)
  );
```

建表流程：先 `+db-table-list` / `+db-table-get` 确认表不存在或看现有结构 → 生成 DDL → 向用户展示影响并取得授权 → `+db-execute ... --yes` 执行。

## 审计列

- 平台自动维护的四列固定叫 `_created_at` / `_updated_at` / `_created_by` / `_updated_by`（**下划线开头**）。查询 / 排序 / 过滤一律用这些名字，别写 `created_at`。
- `_created_at` / `_updated_at` 在 INSERT 时可省略（有默认值）；需要业务归属时显式写 `_created_by` / `_updated_by`。
- UPDATE 业务字段时建议同步 `_updated_at = CURRENT_TIMESTAMP` 和 `_updated_by`。

## `user_profile` 复合类型

平台内置类型 `(user_id varchar, name varchar, email varchar, avatar text, status integer)`，无需创建。**业务 SQL 只允许访问 `(field).user_id`**，不要依赖 `name` / `email` / `avatar` / `status`（可能为空或过期）。

```sql
-- 写入 / 更新：用 ROW()::user_profile，更新时替换整个字段，不改单个属性
INSERT INTO teacher (teacher_profile, class_id)
VALUES (ROW('<user_id>')::user_profile, gen_random_uuid());

UPDATE teacher SET teacher_profile = ROW('<user_id>')::user_profile
WHERE (teacher_profile).user_id = '<old_user_id>';

-- 查询 / 过滤：解引用取 user_id；raw SQL 返回给前端前必须解引用，别直接返回复合类型
SELECT (teacher_profile).user_id AS teacher_profile, class_id FROM teacher;

-- 索引 / 唯一性：表达式列用三重括号；表达式唯一性用 CREATE UNIQUE INDEX，
-- 不能用 ALTER TABLE ADD CONSTRAINT UNIQUE（不支持表达式列）
CREATE INDEX idx_teacher_user_id ON teacher (((teacher_profile).user_id));
CREATE UNIQUE INDEX uk_teacher_user_id ON teacher (((teacher_profile).user_id));
```

## DDL 规则

| 场景 | 做法 |
|---|---|
| 加列 | `ALTER TABLE <t> ADD COLUMN IF NOT EXISTS <col> <type>`，相关 `COMMENT ON` 同次执行 |
| 加索引 | `CREATE INDEX IF NOT EXISTS idx_<t>_<cols> ON <t>(...)` |
| JSONB 类型声明 | 必须 `COMMENT ON COLUMN <t>.<col> IS '@type { ... }'` 声明 TypeScript 类型，和 CREATE / ALTER 同次调用 |
| 加 NOT NULL 列 | 必须带 `DEFAULT` 让存量行自动填：`ADD COLUMN <col> <type> NOT NULL DEFAULT <值>` |
| 删表 / 删列 | 有业务数据默认禁止；必须用户明确授权后才执行，并说明数据丢失风险 |
| 强约束 | `UNIQUE` / `FOREIGN KEY` / `NOT NULL` 默认谨慎，不确定不加 |

**多环境库加约束前先查 online 存量**：`dev` 干净不代表 `online` 干净，约束发布到 online 会撞线上存量数据而失败。发布前一律先用 `--environment online` 查清楚，按约束类型分三种：

- **加唯一约束（`UNIQUE` / 唯一索引）**：线上不能有重复值。先查重复，有则先清理再加：

  ```bash
  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
    "SELECT <cols>, count(*) FROM t GROUP BY <cols> HAVING count(*) > 1" --yes
  ```

- **已有列改 `NOT NULL`（收紧约束）**：线上该列不能有 NULL。先查 NULL 行数，有就先回填（`UPDATE t SET <col> = <默认值> WHERE <col> IS NULL`）再加约束：

  ```bash
  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
    "SELECT count(*) FROM t WHERE <col> IS NULL" --yes
  ```

- **新加 `NOT NULL` 字段**：必须带 `DEFAULT`，且要求线上该表**无存量数据**，否则发布报错。线上已有数据时别直接加，改走三步安全变更：先 `ADD COLUMN <col> <type>`（可空）→ 回填 `UPDATE t SET <col> = <值>` → 再 `ALTER COLUMN <col> SET NOT NULL`。先查线上行数判断走哪条：

  ```bash
  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
    "SELECT count(*) FROM t" --yes
  ```

## SELECT 规则

| 规则 | 要求                                                               |
|---|------------------------------------------------------------------|
| 行数 | 结果集有硬上限（平台限制 1000 行），超限**报错而非静默截断**；大表必须显式 `LIMIT`、聚合或游标分页       |
| 分页 | 大表优先游标分页 `WHERE id > <last_id> ORDER BY id LIMIT n`，避免大 `OFFSET` |
| user_profile | 返回给前端前解引用：`(owner).user_id AS owner`                             |
| 统计 | 总数用 `count(*)`、分组用 `GROUP BY`，别把全量拉到 agent 侧再统计                  |
| 慢查询 | 用 `EXPLAIN (ANALYZE, BUFFERS)`；大表 Seq Scan 考虑加索引                 |

## DML 规则

**INSERT**
- UUID 主键省略，交给 `DEFAULT gen_random_uuid()`；外键 UUID 用子查询取父表 id，不手写。
- NOT NULL 且无默认值的列必须给值；批量 INSERT 每行列数一致。
- 需要幂等用 `ON CONFLICT ... DO NOTHING / DO UPDATE`。
- 标量子查询必须保证单行，非唯一条件加 `ORDER BY ... LIMIT 1`。

**UPDATE**
- **必须有明确 `WHERE`，禁止无条件 UPDATE**。
- 用户说「修改 / 更新 / 改一下」数据时用 UPDATE，**禁止 DELETE + INSERT** 模式。
- 更新 `user_profile` / 复合类型时替换整个字段。
- 批量更新前影响范围不明确，先 `SELECT count(*)` 给用户确认。

**DELETE / TRUNCATE**（属会丢数据的高影响操作，按上面「Agent 规则」的确认流程走）
- 已有表 / 已有数据默认禁止；先 `SELECT count(*)` 展示命中行数、取得用户明确授权，再带 `--yes` 执行。
- `TRUNCATE` 影响整表，视同高风险删除。

```sql
UPDATE task
SET status = 'done', _updated_at = CURRENT_TIMESTAMP, _updated_by = ROW('<user_id>')::user_profile
WHERE id = (SELECT id FROM task WHERE title = '梳理需求' ORDER BY _created_at DESC LIMIT 1);
```

## 常见 PostgreSQL 陷阱

| 陷阱 | 正确做法 |
|---|---|
| 表名带 schema 前缀 | 业务表一律裸表名 `FROM orders`，别写 `public.orders` |
| 保留字作标识符 | 避免 `user` / `order` / `desc` / `offset` / `references` 等 |
| 内联 COMMENT | 禁止 `col TEXT COMMENT 'xx'`，用独立 `COMMENT ON COLUMN` |
| 手写系统表查结构 | 常规结构查询用 `+db-table-list` / `+db-table-get`，别手写 `information_schema` / `pg_indexes` 模拟 |
| 空数组类型不明 | 写 `ARRAY[]::text[]` 或 `'{}'::text[]` |
| `ROUND` 报错 | 用 `ROUND(num::numeric, n)` 或 `ROUND(num::double precision)` |
| `DISTINCT` + 窗口函数 | 分两层查询，先 DISTINCT 再窗口函数 |
| MySQL 方言 | 不用 `SHOW TABLES` / `DESCRIBE` / 内联 `COMMENT`；用 `+db-table-*` 和 `COMMENT ON` |
| 多语句以为自动回滚 | `A; B; C` 不自动包事务，B 失败时 A 已提交；要原子性显式 `BEGIN; ... COMMIT;`（见上「命令骨架」「Agent 规则」） |

## 数据类型与设计

| 项目 | 规则 |
|---|---|
| 主键 | 默认 `id uuid PRIMARY KEY DEFAULT gen_random_uuid()` |
| 命名 | 表名单数、全小写、snake_case、无冗余后缀 |
| 枚举 / 状态 | 用 `varchar(255)`，值用小写英文 + 下划线 |
| JSONB | 必须 `COMMENT ON COLUMN ... IS '@type { ... }'` 声明类型 |
| 附件 / 图片 | URL 用 `TEXT`，命名 `xxx_url` |
| 约束 | `UNIQUE` / `FOREIGN KEY` / `NOT NULL` 默认谨慎，新增 NOT NULL 列优先带 `DEFAULT` |

# apps db 域命令

管理妙搭应用数据库：看表与结构、初始化与发布多环境、数据搬运、变更治理、时间点恢复、用量。逐条跑 SQL（SELECT/DML/DDL）走 [`+db-execute`](lark-apps-db-execute.md)（单独一篇）。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。

## 何时用

用户要看应用里有哪些表 / 某张表的结构、把单库应用拆成 dev/online 多环境、把数据导进导出表、查谁在什么时候改了表结构或表数据、开关行级审计、把开发环境的库结构发布到线上、把库恢复到过去某个时间点、或看数据库用量时。逐条执行 SQL 走 [`+db-execute`](lark-apps-db-execute.md)；文件存储（上传/下载文件）走 [`lark-apps-file.md`](lark-apps-file.md)。**建表 / 改表 / 写 SQL 的平台内容规范**（审计列、RLS、`user_profile`、禁用 SQL、PG 陷阱）见 [`lark-apps-db-execute.md`](lark-apps-db-execute.md) 的「平台 SQL 规范」。

## 命令一览

| 命令 | 做什么 | 关键参数 |
|---|---|---|
| `+db-table-list` | 列出某环境的数据表 | `--environment`、`--page-size`/`--page-token` |
| `+db-table-get` | 看单张表的结构（字段/索引/约束/DDL） | `--table`、`--environment`、`--format` |
| `+db-env-create` | 把单库应用初始化为 dev/online 多环境（高危） | `--environment`、`--sync-data`、`--yes` |
| `+db-data-export` | 把一张表的数据导出到本地文件 | `--table`、`--output`、`--limit`、`--environment` |
| `+db-data-import` | 把本地 csv/json 文件导进一张表（高危） | `--file`、`--table`、`--environment`、`--yes` |
| `+db-sync-create` | 预览或创建 Base 到应用数据库的同步任务（高危） | `--config`、`--preview`、`--output`、`--environment`、`--yes` |
| `+db-sync-list` | 列出 Base 同步任务 | `--mode`、`--status`、`--table`、`--page-size`/`--page-token`、`--environment` |
| `+db-sync-get` | 查看同步任务配置、状态、统计和 warnings | `--task-id` |
| `+db-sync-enable` | 启用 streaming 同步任务 | `--task-id` |
| `+db-sync-disable` | 停用 streaming 同步任务 | `--task-id` |
| `+db-sync-update` | 修改 streaming 同步任务映射配置（高危） | `--task-id`、`--config`、`--yes` |
| `+db-sync-delete` | 删除 streaming 同步任务，保留目标数据（高危） | `--task-id`、`--yes` |
| `+db-changelog-list` | 查表结构变更（DDL）历史 | `--table`、`--change-id`、`--since`/`--until`、`--environment` |
| `+db-audit-status` | 看哪些表开了行级审计、保留期 | `--table`、`--environment` |
| `+db-audit-enable` | 给某表开启行级变更审计 | `--table`、`--retention`、`--environment` |
| `+db-audit-disable` | 关闭某表的行级审计 | `--table`、`--environment` |
| `+db-audit-list` | 列出表的行级变更事件（增删改追溯） | `--table`（可重复）、`--since`/`--until`、`--environment` |
| `+db-env-diff` | 预览开发环境待发布到线上的结构变更 | `--app-id` |
| `+db-env-migrate` | 把开发环境的结构变更发布到线上（高危） | `--app-id`、`--yes` |
| `+db-recovery-diff` | 预览把库恢复到某时间点会带来的变更 | `--target` |
| `+db-recovery-apply` | 把库恢复到某个时间点、覆盖当前数据（高危） | `--target`、`--yes` |
| `+db-quota-get` | 查数据库存储用量 | `--environment` |

## 约定（先读）

- **环境 `--environment dev|online`（可省略）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分。省略 `--environment` 时 CLI 不带该参数、由服务端按应用形态自动选分支——多环境应用走 `dev`、未开多环境的走 `online`；要固定环境就显式传。唯一会报错的组合：对未开多环境的应用显式传 `--environment dev`（无 `dev` 分支）。写操作建议先在 `dev` 验（仅多环境应用有 `dev`）。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义，**没有** `--environment`。
- **本地文件 / `--output` 用工作目录内相对路径**：导入 `--file ./orders.csv`、导出 `--output ./out.csv`；绝对路径、或经 `..`/符号链接越出工作目录的 `--output` 会被拒（validation / exit 2）。路径在别处先 `cd` 过去或改成相对路径。
- **高危操作必须带 `--yes`**：`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply`、`+db-sync-create`、`+db-sync-update`、`+db-sync-delete` 缺省会被确认关卡拦下；动手前先用对应的预览命令或 `--dry-run` 看清影响。`+db-sync-create --preview` 只解析/校验配置、不落库，免确认、不需 `--yes`；真正建任务（不带 `--preview`）才需要 `--yes`。
- **Base 同步不是整库任务**：`+db-sync-create` 一次只处理一张 Base 表到一张目标表。用户说“整库”“客户、订单、回款三张表都同步”时，先明确告诉用户会拆成三套独立配置、三次 preview、用户确认后三次 create；不要暗示一个同步任务能覆盖整个 Base。
- **batch 任务不能重新启用**：用户说“批量任务重新启用”“operation-not-allowed”时，先给结论：batch/import 是一次性任务，不能 enable。不要先陷入授权排障而漏掉这个结论；授权缺失时也要说明授权完成后应 `+db-sync-get` 查状态/结果，持续同步要新建 streaming。
- **时间参数按口语自然传**（`--since`/`--until`/`--target`），格式见末尾。

## 各命令

### 表与结构

**`+db-table-list`**：列出某环境的数据表。分页 `--page-size`（默认 20）/ `--page-token`（上一页 cursor）。每项给表名、描述、估算行数、大小、列数；要完整列定义 / 索引 / 约束用 `+db-table-get`。只知道业务对象名时，先用它定位可能的表名。

```bash
lark-cli apps +db-table-list --app-id app_xxx
lark-cli apps +db-table-list --app-id app_xxx --environment dev --page-size 50
```

**`+db-table-get`**：看单张表的结构。默认 JSON 给结构化的字段 / 索引 / 约束 / 估算行数 / 大小；`--format pretty` 直接输出建表 DDL 文本（给用户看建表语句或做迁移参照时用）。

```bash
lark-cli apps +db-table-get --app-id app_xxx --table orders
lark-cli apps +db-table-get --app-id app_xxx --table orders --environment dev --format pretty
```

### 多环境数据库（初始化 + 发布）

**`+db-env-create`（高危）**：把存量单库应用初始化为 dev/online 两套库，不可逆，必须带 `--yes`。`--environment` 目前只支持 `dev`（默认 `dev`）；`--sync-data` 把现有 online 数据复制到新环境（不传则不复制）。注意：`+create --app-type full_stack` 新建的应用通常已自带多环境，重复初始化会返回冲突错误（应用已是多环境）——按 `error.hint` 转述状态即可，别重复初始化。

```bash
lark-cli apps +db-env-create --app-id app_xxx --environment dev --dry-run
lark-cli apps +db-env-create --app-id app_xxx --environment dev --sync-data --yes
```

**`+db-env-diff`**：预览开发环境里待发布到线上的表结构变更，不落地。发布前先看这个。无待发布变更时明确返回「无变更」。

**`+db-env-migrate`（高危）**：把开发环境的结构变更正式发布到线上，不可逆，必须带 `--yes`，返回实际发布的变更条数。发布是异步的，命令会等到完成再返回结果。

> 预览与发布同一端点，故 `+db-env-diff` 也需 `spark:app:write` scope（不是纯只读权限）。

```bash
lark-cli apps +db-env-diff --app-id app_xxx
lark-cli apps +db-env-migrate --app-id app_xxx --yes
```

### 数据导入导出

**`+db-data-export`**：把一张表导出到本地文件。导出格式**只由 `--output` 的扩展名决定**——`.csv` / `.json` / `.sql`，缺省按 `<表名>.csv` 落在当前目录。注意：全局 `--format json|pretty` 只控制**命令自身输出**（成功摘要 / 错误信封）的渲染，**不影响导出文件的格式**；`--output` 后缀必须是 `.csv/.json/.sql` 之一，否则报 validation 错误（exit 2），且不支持导出到 stdout。两道体量约束：

- `--limit`（1..5000，默认 5000）是**行数上限守卫**：表的行数超过它会被整体拒掉（不是「只导前 N 行」）；
- 导出产物 >1 MB 也会被拒。

超大表别硬导：先用 `+db-execute` 加 `WHERE` / `LIMIT` 缩小范围、分批导。

```bash
lark-cli apps +db-data-export --app-id app_xxx --table orders --output ./orders.csv
lark-cli apps +db-data-export --app-id app_xxx --table orders --output ./orders.json --environment dev
```

**`+db-data-import`（高危）**：把本地 csv/json 文件的数据导进表。文件需是 `.csv`/`.json`、≤1 MB，必须带 `--yes`。目标表缺省取文件名去掉**最后一个**扩展名（如 `orders.csv`→`orders`，`orders.2026.csv`→`orders.2026`）；文件名带点号时建议显式传 `--table` 以免落到意外的表名。

```bash
lark-cli apps +db-data-import --app-id app_xxx --table orders --file ./orders.csv --environment dev --yes
```

**导入/导出限额**：体积 ≤ **1 MB**、行数 ≤ **5000**，导入导出都一样，超限会被拒。超限就分批——导入拆成 ≤1 MB / ≤5000 行的多个文件，导出用 `WHERE` / `LIMIT` 缩小范围。

### Base 数据同步

Base 数据同步走 `+db-sync-*`，和本地文件导入不同：`+db-data-import` 只处理本地 `.csv/.json` 文件；Base 链接、Base 表、字段映射、持续同步任务都走 `+db-sync-create` / `+db-sync-update`。

**任务类型**：
- `mode=batch`：一次性任务。`schema_only=true` 只建目标表；`schema_only=false` 建表或写入已有表并导入当前 Base 数据。完成后不能 enable/disable/update/delete。
- `mode=streaming`：持续同步任务。首次同步后持续处理 Base 变化，可 enable/disable/update/delete。

**环境（重要）**：`+db-sync-*` 命令省略 `--environment` 时默认落 **online**（不同于 `+db-table-*`/`+db-audit-*` 等「多环境自动选 dev、单环境选 online」的规则——db-sync 家族不走自动选分支）。**多环境应用建表**（`target.table.action=create`）**必须显式 `--environment dev`**：不填或填 `online` 会被 online 分支的 DDL 禁令拒（`k_dl_4000001：forbid ddl/dcl operation in online env`），因为 online 分支产品上不允许直接建表，建表要落到 dev 分支。共享库 / 单环境应用只有 online、在 online 建表正常成功（不会报 `k_dl_4000001`），省略 `--environment` 或填 `online` 均可。

**配置格式**：只通过 `--config` 传完整 JSON，支持内联 JSON、`@file`、`-` stdin。配置 key 使用复数：`field_maps`、`option_mappings`、`syncable_source_fields`。不要写单数 `field_map` / `option_mapping`，CLI 会直接报 validation 错。正式 create 时 `field_maps` **可省略或传空数组**：服务端会使用与 preview 相同的逻辑自动匹配字段并直接创建任务；若显式传了映射，则至少要有一项未写成 `"enabled": false`，写了却全部关闭会被 CLI 拒绝。`+db-sync-update` 仍要求至少一个启用的 `field_maps`，因为 update 的语义是修改既有映射。`target.table.action` 只能是 `create` 或 `use_existing`：建表时 `pg_field` 需要完整字段定义；写已有表时通常只需目标列名。`source.base_url`（源 Base 表完整 URL）在 `+db-sync-create` 必填、由服务端强制；`+db-sync-update` 可选——省略时服务端复用原任务的源 URL，仅在换源 / 替换成另一张 Base 表时才需要传新的 `base_url`。`source.table.name` 是要同步的 Base 表名。`base_url` 形如 `https://.../base/<token>?table=<tableId>`：`token` 定位 Base，`table=` 参数（tableId）定位表。填了 `source.table.name` 就以 name 为准——服务端用 `token + name` 反查 tableId（覆盖 url 里的 `table=` 参数）；不填才用 url 的 `table=` 参数定位。所以用户自然语言里说「同步 xxx 表」「把 xxx 表同步过去」时，一定要把「xxx」填进 `source.table.name`，不要只给 `base_url`——尤其当 `base_url` 不带 `table=` 参数（指向不带具体表的 Base）时，漏了 name 服务端无从定位表。

**不知道要同步哪张表**：若 `base_url` 只有域名+token、不带 `?table=` 参数，又不确定表名，别硬猜。先用 `lark-cli base +table-list --base-token <token>` 列出该 Base 的所有表（`<token>` 就是 `base_url` 里 `/base/` 后面那段），把表名给用户选定，再填进 `source.table.name`（或改用带 `?table=<table_id>` 的完整 URL）。`+db-sync-create` 会在本地就拦下「`base_url` 无 `?table=` 且 `source.table.name` 空」的配置（提交前即报 validation 错，不送到服务端）。

**单数 key 恢复**：如果用户说配置里 `field_map` 是单数、`option_mapping` 是单数、或字段映射可能不生效，不要把原配置直接提交。先找到用户这份同步配置，做这三步：

1. 只把已知 key 改成复数：`field_map` -> `field_maps`，`option_mapping` -> `option_mappings`；不要发明 `fieldMappings` / `mapping` 之类字段名。
2. 检查 `field_maps` 是数组，且至少有一项 `enabled` 缺省或为 `true`。如果全是 `"enabled": false`，先让用户确认要启用哪几项，再继续。
3. 修好后先重新 preview，或复用最近一次 preview `--output` 产出的 `data.config`，再继续 create / update。

```bash
lark-cli apps +db-sync-create --app-id app_xxx --environment dev --config @sync.json --preview --output ./resolved-sync.json
lark-cli apps +db-sync-create --app-id app_xxx --environment dev --config @resolved-sync.json --yes
```

如果本地找不到配置文件，不要只停在“请提供文件”。先说明恢复来源：让用户贴失败时传入的 JSON，或查找最近 preview 的 `--output` 文件；如果是已有任务的修改，先用 `+db-sync-get` 取回当前任务配置，再基于它修正后 update：

```bash
lark-cli apps +db-sync-get --app-id app_xxx --task-id streaming_123 -q '.data | {mode, source, target, field_maps}' > sync.json
lark-cli apps +db-sync-update --app-id app_xxx --task-id streaming_123 --environment dev --config @sync.json --yes
```

**推荐流程（最佳实践，不是强制）**：优先先 preview，再让用户确认映射，最后用 preview 输出的完整 config 正式创建；这样最稳，也避免手写复杂 `field_maps`。若用户明确要求直接执行、不需要 preview，也可以在 create config 中省略 `field_maps`（或传空数组），由服务端自动匹配并直接创建任务；CLI 不应为了拿 mapping 强制用户先 preview。

```bash
lark-cli apps +db-sync-create \
  --app-id app_xxx \
  --environment dev \
  --config - \
  --preview \
  --output ./resolved-sync.json <<'JSON'
{
  "mode": "streaming",
  "source": {
    "type": "base",
    "base_url": "https://example.feishu.cn/base/xxx",
    "table": {"name": "客户"}
  },
  "target": {
    "type": "postgresql",
    "table": {"name": "customers", "action": "use_existing"}
  }
}
JSON
```

preview 返回 `data.config`、`syncable_source_fields` 和 `summary`。`--output` 只把 `data.config` 写入文件，文件可直接作为正式输入：

```bash
lark-cli apps +db-sync-create --app-id app_xxx --environment dev --config @resolved-sync.json --yes
lark-cli apps +db-sync-get --app-id app_xxx --task-id streaming_123
```

**多表 Base**：本命令一次只处理一张表。用户要同步整个 Base 时，先把计划说清楚：不是一个“整库同步任务”，而是按表拆成 N 个单表任务。每张表各有一份配置文件、一次 `+db-sync-create --preview`、一次用户确认后的 `+db-sync-create --yes`，并记录各自 `task_id`。

```bash
lark-cli apps +db-sync-create --app-id app_xxx --environment dev --config @customers-sync.json --preview --output ./customers-resolved.json
lark-cli apps +db-sync-create --app-id app_xxx --environment dev --config @orders-sync.json --preview --output ./orders-resolved.json
lark-cli apps +db-sync-create --app-id app_xxx --environment dev --config @payments-sync.json --preview --output ./payments-resolved.json
```

配置也必须是单表粒度：每份 JSON 只有一个 `source.table` 和一个 `target.table`，字段名保持 `field_maps`、`option_mappings`、`syncable_source_fields` 这些复数 key。

**修改 streaming 映射**：先用 get 导出当前配置，编辑 `field_maps` 后 update。update 是高危操作，必须经用户确认再加 `--yes`。

`+db-sync-get` 返回的 `source` **不含 `base_url`**（只有 token / tableId，服务端没有 domain 拼不出完整 URL），这是正常的。原表 update 直接省略 `base_url` 即可；只有要换成另一张 Base 表时，才在 config 里显式补一个新的 `base_url`。不要为了"补全" `base_url` 而编造 domain 或拼接 URL——拿不到就省略，让服务端复用原任务的源 URL。

`+db-sync-update` 也遵循 db-sync 家族「省略 `--environment` 落 online」的规则，所以改 dev 上的任务必须显式带该任务所在环境的 `--environment`（多环境应用的 streaming 任务通常在 `dev`），否则会错落 online、找不到任务或改错分支。

```bash
lark-cli apps +db-sync-get --app-id app_xxx --task-id streaming_123 -q '.data | {mode, source, target, field_maps}' > sync.json
lark-cli apps +db-sync-update --app-id app_xxx --task-id streaming_123 --environment dev --config @sync.json --yes
```

**列表与生命周期**：

```bash
lark-cli apps +db-sync-list --app-id app_xxx --mode streaming --table customers
lark-cli apps +db-sync-disable --app-id app_xxx --task-id streaming_123
lark-cli apps +db-sync-enable --app-id app_xxx --task-id streaming_123
lark-cli apps +db-sync-delete --app-id app_xxx --task-id streaming_123 --yes
```

`+db-sync-enable`、`+db-sync-disable`、`+db-sync-update`、`+db-sync-delete` 只适用于 `streaming_...` task。对 `batch_...` 执行这些操作会返回 failed-precondition。

**batch 任务 operation-not-allowed 恢复**：用户说“批量任务重新启用”“导入历史订单表的任务重新 enable”“系统说操作不允许”时，先给生命周期结论：batch / import 类任务是一次性任务，完成或失败后不能重新启用，也不要反复调用 `+db-sync-enable`。下一步改为查状态和结果：

```bash
lark-cli apps +db-sync-get --app-id app_xxx --task-id batch_123
```

把 `status`、`result`、`warnings` 和目标表写入情况告诉用户。若用户要的是后续持续同步，不是“重启这个 batch”，应新建 `mode=streaming` 任务：先 `+db-sync-create --preview` 给用户确认映射和影响，再带 `--yes` 创建；不要强行 enable 已完成的 batch 任务。若此时 CLI 还缺授权，仍要先解释这个生命周期边界，再提示授权完成后用 `+db-sync-get` 查结果。

**失败恢复**：看到 `warnings` 不要直接说同步成功。按 warning 或 error 的 `hint` 继续排查，恢复路径按任务 mode 分支：

- **streaming 任务**：常见路径是 `+log-list --keyword <target_table>` / `+log-get` 查日志，然后用 `+db-execute` 修目标表结构，或用 `+db-sync-update`（带该任务所在环境的 `--environment`）修字段映射，最后对同一 `task_id` 再 `+db-sync-get` 复查。
- **batch 任务**：batch 是一次性任务、**不能 update**（见上文生命周期）。修完目标表结构（`+db-execute`）后不要 update 原 batch，而是重新 `+db-sync-create --preview` 建新任务；只想看这个 batch 的结果就直接 `+db-sync-get`。

若此时 CLI 还缺授权、查不到 warning 详情，也不要只给泛化的字段核对建议：先说明被授权卡住，再把对应 mode 的固定命令链作为授权完成后的下一步明确交代给用户。

**online 禁 DDL（`k_dl_4000001`）恢复**：`+db-sync-create` 建表报 `k_dl_4000001：forbid ddl/dcl operation in online env` 时，这必然是多环境应用（共享库在 online 建表不会报此码）。online 分支**本就不允许**直接建表，这是多环境应用的产品设计、不是可绕过的限制。改用 `--environment dev` 重跑 `+db-sync-create`，把表建到 dev 分支；不要试图「在 online 想办法重试建表」，没有这个选项。

**缺 Base 表记录 ID 映射列（`400002477`）恢复**：streaming 自动同步要求目标表有一个映射给「Base 表记录 ID」的 **text + 单值 + unique** 列。用 `action=use_existing` 写已有表时，若该表没有这样的列，会报 `400002477`（Field mapping must include 'Base 表记录 ID'）。先用 `+db-execute` 给表加一个，如 `ALTER TABLE <表> ADD COLUMN base_record_id varchar UNIQUE`，再把它映射给「Base 表记录 ID」、重跑 `+db-sync-create --preview`。注意这是**加列**、不是建表，不需要审计列 / RLS 那套建表规范。

### 变更追溯与审计

**`+db-changelog-list`**：查表结构变更（DDL）历史——谁、什么时候、改了哪张表、做了什么。可按 `--table` 过滤、按 `--change-id` 精确定位某条、用 `--since`/`--until` 圈时间区间，分页 `--page-size`/`--page-token`。

```bash
lark-cli apps +db-changelog-list --app-id app_xxx --table orders --since 7d
```

**`+db-audit-status`**：看审计开关状态。给 `--table` 看单表，不给则列出所有已配置的表（开没开、保留期）。

**`+db-audit-enable` / `+db-audit-disable`**：开 / 关某张表的行级变更审计。`--retention` 设保留期，取值 `7d`/`30d`/`180d`/`360d`/`forever`（默认 `7d`）。不要对已经开启审计的表重复 enable——不确定就先用 `+db-audit-status` 查。

```bash
lark-cli apps +db-audit-enable --app-id app_xxx --table orders --retention 30d
lark-cli apps +db-audit-disable --app-id app_xxx --table orders
```

**`+db-audit-list`**：列出表的行级变更事件（INSERT/UPDATE/DELETE 的前后值与操作人）。`--table` 必填、可重复传多张表；`--since`/`--until` 圈时间。
- **多表查询**：会先帮用户把不存在、或没开审计的表过滤掉再查，被过滤的表及原因列在结果的 `skipped` 里——据此告诉用户哪些表没纳入及为什么。
- **单表查询**：不预过滤，表不存在 / 未开审计会直接报错（按 `error.hint` 转述给用户，引导先 `+db-audit-enable`）。

```bash
lark-cli apps +db-audit-list --app-id app_xxx --table orders --since 24h
lark-cli apps +db-audit-list --app-id app_xxx --table orders --table users
```

### 时间点恢复（PITR）

**`+db-recovery-diff`**：预览把库恢复到 `--target` 时间点会带来哪些变更（受影响的表、行数、预计耗时），不落地。同样需 `spark:app:write` scope。

**`+db-recovery-apply`（高危）**：把库恢复到某个时间点，**会覆盖当前数据**，不可逆，必须带 `--yes`。

- 可恢复窗口最长 **7 天**，且不早于**最近一次 `+db-env-migrate`**；超出窗口的目标会被拒。
- 目标时间点与当前库一致时返回 `no_changes`（空操作），不算失败。
- 动手前务必先 `+db-recovery-diff` 给用户确认。

```bash
lark-cli apps +db-recovery-diff --app-id app_xxx --target 2h
lark-cli apps +db-recovery-apply --app-id app_xxx --target 2026-04-15T10:00:00Z --yes
```

### 配额

**`+db-quota-get`**：查数据库存储用量（已用量、表数、视图数；配额接入后还会给总配额与使用率）。

```bash
lark-cli apps +db-quota-get --app-id app_xxx --environment dev
```

## 时间格式（`--since` / `--until` / `--target`）

按用户口语自然传入即可，支持：
- 相对时间 `7d` / `2h` / `30s`（从现在往前推）
- 日期 `2026-04-15`
- 日期时间 `2026-04-15T10:00:00`
- 带时区的 ISO 8601 `2026-04-15T10:00:00Z` / `2026-04-15T10:00:00+08:00`

> **时区**：不带时区的 `日期` / `日期时间` 按**运行机器的本地时区**解析（再归一化到 UTC）。CI（UTC）与本地（如 UTC+8）跑同一条命令，时间边界会差几小时；要精确锁定时区时显式写 ISO 8601 带偏移（如 `...+08:00` / `...Z`）。`--target`（PITR 恢复）尤其建议带时区，避免恢复到非预期时间点。

## Agent 规则

- 用户说「本地 / 开发库 / 调试库」优先 `--environment dev`，线上排查用 `--environment online`；数据面写操作（导入 / 审计开关）建议先在 `dev` 验再动 `online`。**注意省略 `--environment` 时写操作会落到服务端选中的分支——单环境应用即 `online`（生产）**：不确定应用是否多环境时，写操作显式传 `--environment`；显式 `dev` 在单环境应用上会安全报错（无 dev 分支），正好当「是否多环境」的探针用。
- 看表用 `+db-table-list`，看结构用 `+db-table-get`（要建表语句加 `--format pretty`）；`+db-env-create` 仅用于存量单库拆多环境，新建的 full_stack 应用一般不需要。
- 高危命令（`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply`、`+db-sync-create`、`+db-sync-update`、`+db-sync-delete`）动手前先看清影响再带 `--yes`：发布 / 恢复先跑对应预览 `+db-env-diff` / `+db-recovery-diff`，Base 同步先跑 `+db-sync-create --preview`，导入无预览命令、可先 `--dry-run` 看请求或先在 `--environment dev` 验；不要静默追加 `--yes`，遇 confirmation_required（exit 10）按 lark-shared 协议向用户确认不可逆风险后再补 `--yes` 重试。
- 导入 / 导出的本地路径用工作目录内相对路径；超大表导出会被行数 / 体积上限拒，改用 `+db-execute` 分批。
- Base 同步优先走 preview → 用户确认 → create，这是最稳的最佳实践、不是强制。用户明确要求直接 create 时，可省略 `field_maps`（或传空数组）让服务端自动匹配并创建；不要为了拿 mapping 强制用户先 preview。显式写映射时使用 `field_maps` / `option_mappings` 复数 key。
- 修复 Base 同步配置时，只把 `field_map` / `option_mapping` 改成 `field_maps` / `option_mappings`。若显式给了 `field_maps`，检查至少一个映射启用；全是 `"enabled": false` 时先让用户确认要启用哪项。create 也可删掉/置空 `field_maps` 交给服务端自动匹配，但 update 仍必须提供启用的映射。
- `+db-sync-update` 省略 `source.base_url` 是合法的（服务端复用原任务源 URL）；`+db-sync-get` 不返回 `base_url` 属正常，不要因此编造 domain / 拼接 URL 去"补全"，只有换源 / 替换表时才传新的 `base_url`。`+db-sync-create` 的 `base_url` 必填，缺失由服务端报错。用户说「同步 xxx 表」时把「xxx」填进 `source.table.name`——填了 name 就以 name 为准（服务端用 `base_url` 的 token + name 反查 tableId，覆盖 url 的 `table=` 参数），不填才用 url 的 `table=` 参数定位；别只给 `base_url`。
- batch 同步任务不能重新 enable。遇到 operation-not-allowed 先 `+db-sync-get` 查状态和结果；要持续同步就新建 streaming 任务，走 preview -> 用户确认 -> create。
- `+db-sync-*` 省略 `--environment` 默认落 online。多环境应用建表（`action=create`）必须显式 `--environment dev`；省略或填 `online` 会撞 `k_dl_4000001`（online 禁 DDL）——那是多环境应用的产品设计，把表建到 dev 分支即可，不要在 online 重试建表。共享库应用在 online 建表正常，不受此限。
- `+db-audit-list` 多表查询时，把结果里 `skipped` 的表（不存在 / 未开审计）连同原因一并向用户说明，不要让用户以为这些表「没有变更」。
- 恢复是覆盖式且不可逆：`+db-recovery-apply` 前必须先 `+db-recovery-diff`，并明确告知用户会覆盖当前数据。

# apps +env-pull

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。

把妙搭应用 dev 启动期环境变量拉取到本地项目根的 `.env.local`。身份固定 `--as user`；scope `spark:app:read`。`--app-id` 必填，目标项目根默认当前工作目录（`--project-path` 可指定）。

这个命令是 dev-only 的本地恢复工具：内部固定 `POST env_vars`，body 为 `env=dev`。它没有 `--env` flag，也不管理线上环境变量。

## 何时别用（核心反模式）

**通常不需要手动跑**——脚手架的 `npm run dev` 在起本地开发时会自动后台拉取（非阻塞）。手动再跑会重复做同样的事，并用服务端返回值覆盖 `.env.local` 里的同名 key；本地无关行和注释会保留。

只在这些兜底场景用：

- 不通过 `npm run dev` 启动（直接跑 `node` / IDE debug）。
- `.env.local` 被改坏 / 删除，想重新同步。

## 行为

- **合并、不清空**：写入 `.env.local` 时保留你手写的内容与注释——命中的 key 替换值，新 key 追加，不整体覆盖。
- **安全护栏**：返回的 envelope **不会回显任何 env key / value**（防止 token / 数据库凭据泄漏到日志或 CI 输出）。要看实际值请直接读 `.env.local`。

## 示例

```bash
lark-cli apps +env-pull --app-id <app_id>
```

## 失败处理

`missing_scope`（没拿到 `spark:app:read`）时，按 lark-shared 引导 `lark-cli auth login --domain apps`。其余失败优先转述 `error.hint` / `error.message`。

## 参考

- [lark-apps](../SKILL.md) — 妙搭应用全部命令 + 心智模型
- [lark-apps-local-dev](lark-apps-local-dev.md) — 本地应用开发端到端流程
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

# apps env

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。

管理妙搭应用环境变量。查看用 `+env-list`，设置用 `+env-set`，删除用 `+env-delete`。没有单变量 get 命令；要确认某个 key 是否存在，使用 list 后用 `--jq` 过滤。

环境 flag 使用 `--environment`；不要使用旧的 `--env`，也不要使用短选项。

## 查看

`+env-list` 默认查 dev，且默认不返回 value。只有显式传 `--include-values` 后，响应中才可能出现变量值；不要在公开日志里展示带值输出。

接口契约：list 使用 `POST env_vars`，body 固定包含 `env` 和 CLI 场景 `scene=2`；set 使用 `POST create_or_update_env_var`；delete 使用 `POST delete_env_vars`。`--include-values` 只控制 CLI 输出是否展示 value，不作为服务端查询参数发送。

```bash
lark-cli apps +env-list --app-id <app_id>
lark-cli apps +env-list --app-id <app_id> --environment online
lark-cli apps +env-list --app-id <app_id> --include-values --jq '.data.items[] | select(.key == "FOO")'
```

## 设置

dev 环境设置不需要 `--yes`。设置 online 环境需要人类确认并显式传 `--yes`；如果用户在同一轮已经明确说“确认/直接执行”，视为已确认，直接带 `--yes`，不要再次追问。`--dry-run` 可用于预览请求且不需要 `--yes`。变量值支持直接传 `<value>`，也支持 `@file` 或 stdin 输入。

回复中只说明 app/env/key 和执行结果；不要回显真实 value。需要举例时使用 `<value>`、`@file` 或 stdin。

```bash
lark-cli apps +env-set --app-id <app_id> --key FOO --value <value>
lark-cli apps +env-set --app-id <app_id> --key FOO --value @./secret.txt
lark-cli apps +env-set --app-id <app_id> --environment online --key FOO --value <value> --dry-run
lark-cli apps +env-set --app-id <app_id> --environment online --key FOO --value <value> --yes
```

## 删除

`+env-delete` 是 high-risk-write。尊重 exit 10 confirmation protocol：先让用户确认 app/env/key 和删除后果，再传 `--yes`。不要自动补 `--yes`。如果只是认证失败后让用户重登，重登完成不等于删除确认；继续删除前仍需确认。

```bash
lark-cli apps +env-delete --app-id <app_id> --key FOO --dry-run
lark-cli apps +env-delete --app-id <app_id> --key FOO --yes
lark-cli apps +env-delete --app-id <app_id> --environment online --key FOO --yes
```

## 反模式

- 不要把 `+env-pull` 当成环境变量管理命令；它只是刷新本地 `.env.local` 的兜底工具。
- 不要为了看一个变量臆造名为 env-get 的 apps shortcut；用 `+env-list --include-values` 加 `--jq`。
- 不要把真实 secret 写进示例或对话输出；需要示例时使用 `<value>`、`@file` 或 stdin。

# apps file 域命令（应用存储）

管理妙搭应用的文件存储：上传 / 下载本地文件、列出与查看已存文件、生成临时分享链接、批量删除、查看用量。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。

## 何时用

用户要在某个妙搭应用里上传 / 下载 / 列出 / 删除文件、拿文件的临时分享链接、或看存储用量时。普通飞书云盘走 [`lark-drive`](../../lark-drive/SKILL.md)；数据库里的表数据走 `+db-*`。

## 命令一览

| 命令 | 做什么 | 关键参数 |
|---|---|---|
| `+file-list` | 列出文件，可按名/路径/类型/大小/上传时间过滤 | `--app-id`、过滤器、`--page-size`/`--page-token` |
| `+file-get` | 查单个文件的元数据 | `--app-id`、`--path` |
| `+file-sign` | 生成有时效的下载链接（用于分享 / 直接下载） | `--app-id`、`--path`、`--expires-in` |
| `+file-download` | 把远端文件保存到本地 | `--app-id`、`--path`、`--output` |
| `+file-upload` | 上传本地文件到应用存储 | `--app-id`、`--file` |
| `+file-delete` | 按路径批量删除文件 | `--app-id`、`--path`（可重复）、`--yes` |
| `+file-quota-get` | 查应用的文件存储用量 | `--app-id` |

## 寻址与约定（先读）

- **远端文件统一用 `--path` 精确寻址**（远端路径，带前导 `/`）。只知道文件名时，先用 `+file-list --name <名>` 定位拿到 `path`，再做后续操作。
- **本地文件 / 输出路径用工作目录内的相对路径**（如 `--file ./report.pdf`、`--output ./out.png`）；路径在别处时先 `cd` 过去或改成相对路径。
- 上传只接收本地 `--file`：文件名沿用本地文件名，远端路径由平台分配、全局唯一（无需也无法手填）。
- file 域不区分环境，没有 `--env`。

## 各命令

### +file-list
列出应用文件，支持精确过滤：`--name`（文件名）、`--path`（远端路径）、`--type`（MIME 类型）、`--size-gt`/`--size-lt`（字节）、`--uploaded-since`/`--uploaded-until`（上传时间区间，时间格式见末尾）。分页 `--page-size`（默认 20，范围 1..200）/ `--page-token`。列表每项给名称、路径、大小、类型、上传时间（pretty 表格即这 5 列）；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`。

```bash
lark-cli apps +file-list --app-id app_xxx
lark-cli apps +file-list --app-id app_xxx --type image/png --uploaded-since 7d
```

### +file-get
按 `--path` 查单个文件的元数据。路径不存在时返回明确的「文件不存在」错误。

```bash
lark-cli apps +file-get --app-id app_xxx --path /1858537546760216.png
```

### +file-sign
为指定文件生成一个**有时效的下载链接**——适合发给用户分享、或直接下载。`--expires-in` 设有效期秒数（默认 1 天，最长 30 天）。`pretty` 模式只输出链接本身，便于复制 / 管道；要把到期时间一并告诉用户时用默认 JSON 输出（含到期时间）。

```bash
lark-cli apps +file-sign --app-id app_xxx --path /1858537546760216.png --expires-in 3600
```

### +file-download
把远端文件保存到本地。`--output` 指定保存路径，缺省时按远端文件名保存到当前目录。

```bash
lark-cli apps +file-download --app-id app_xxx --path /1858537546760216.png --output ./logo.png
```

### +file-upload
上传一个本地文件。文件名沿用本地文件名（特殊字符做 URL 编码透传；以 `.` 开头的隐藏文件名会加 `_` 前缀，避免下载回本地时覆盖隐藏文件），远端路径由平台分配。单文件上限 100 MB。

```bash
lark-cli apps +file-upload --app-id app_xxx --file ./report.pdf
```

### +file-delete（高危）
按路径批量删除，`--path` 可重复传多个。删除是高危操作，必须带 `--yes`；缺省会被确认关卡拦下。**逐项返回结果**：部分文件删除失败（如某个路径不存在）不影响其余文件，整体仍算成功，失败项在结果里单独标出原因。

```bash
lark-cli apps +file-delete --app-id app_xxx --path /1858537546760216.png --yes
lark-cli apps +file-delete --app-id app_xxx --path /a.png --path /b.png --yes
```

### +file-quota-get
查应用的文件存储用量（已用量、文件数；配额接入后还会给总配额与使用率）。

```bash
lark-cli apps +file-quota-get --app-id app_xxx
```

## 时间格式（`--uploaded-since` / `--uploaded-until`）

按用户口语自然传入即可，支持：
- 相对时间 `7d` / `2h` / `30s`（从现在往前推）
- 日期 `2026-04-15`
- 日期时间 `2026-04-15T10:00:00`
- 带时区的 ISO 8601 `2026-04-15T10:00:00Z` / `2026-04-15T10:00:00+08:00`

> **时区**：不带时区的 `日期` / `日期时间` 按**运行机器的本地时区**解析（再归一化到 UTC 发给服务端）。CI（UTC）与本地（如 UTC+8）跑同一条命令，过滤边界会差几小时；要精确到某时区时显式写 ISO 8601 带偏移（如 `...+08:00` / `...Z`）。

## Agent 规则

- 寻址一律用 `--path`；用户只给文件名时先 `+file-list --name <名>` 定位，多个同名再让用户确认。
- 上传 / 下载的本地路径用工作目录内相对路径；不在当前目录就 `cd` 过去或改相对路径。
- 用户要「分享链接 / 临时下载地址」时用 `+file-sign`，把返回的链接转述给用户。
- 删除前判断意图：已明确要删且授权时可直接带 `--yes`；不确定删哪些时先 `+file-list` 给用户确认。批量删除部分失败不报错，按逐项结果向用户说明哪些成功、哪些没删掉及原因。

# apps +get

按 app_id 查询单个应用详情。运行时命令事实以 `lark-cli apps +get --help` 为准。

## 何时用

需要查看一个应用的类型、名称、描述、发布状态等详情时使用。如果只是按应用名模糊搜索定位 app_id，用 `+list --keyword`。

## 命令骨架

- 必填：`--app-id`。
- 返回应用的完整信息：`app_id`、`app_type`、`name`、`description`、`icon_url`、`created_at`、`updated_at`、`is_published`。

## 示例

```bash
lark-cli apps +get --app-id app_xxx
lark-cli apps +get --app-id app_xxx --dry-run
lark-cli apps +get --app-id app_xxx -q '.data.app.app_type'
```

## 输出契约

- 成功读取 `data.app` 对象，包含以下字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `app_id` | string | 应用唯一标识 |
| `app_type` | string | 应用类型（如 HTML、FRONTEND、FULL_STACK、MODERN_HTML） |
| `name` | string | 应用显示名称 |
| `description` | string | 应用功能说明 |
| `icon_url` | string | 应用图标 URL |
| `created_at` | string | 创建时间（ISO 8601 UTC） |
| `updated_at` | string | 最后更新时间（ISO 8601 UTC） |
| `is_published` | boolean | 是否已发布 |

- pretty 输出展示核心字段：`app_id`、`app_type`、`name`、`is_published`、`updated_at`。
- `is_published=true` 只代表应用历史上有发布版本，不代表最新代码已部署。

## Agent 规则

- 用户已有 `app_id` 想查看详情时用 `+get`；只有应用名时用 `+list --keyword`。
- 不要把 `cli_` 开头的飞书应用 ID 传给 `+get`，只接受 `app_` 开头的应用 ID。

# apps Git credential

妙搭 Git 凭证用于本地原生 `git clone/pull/push`。运行时命令事实以 `lark-cli apps +git-credential-init --help`、`+git-credential-list --help`、`+git-credential-remove --help` 为准。

## 命令

```bash
lark-cli apps +git-credential-init --app-id app_xxx
lark-cli apps +git-credential-list
lark-cli apps +git-credential-remove --app-id app_xxx
```

## 输出契约

- `+git-credential-init` 成功后读取 `data.repository_url`；不要展示或保存其中的凭据细节，只用于下一步 `git clone`。响应还包含 `data.commit_author_name` 和 `data.commit_author_email`，这两个字段由 `+init` 内部消费，自动写入仓库 repo-local git config（`user.name` / `user.email`），agent 和用户无需手动配置。
- `+git-credential-list` 返回本地记录和状态；可用来判断是否需要重新 init。
- `+git-credential-remove` 只清本地配置；成功后告知不会删除云端应用或仓库。

## 行为规则

- `+git-credential-init` 返回 `repository_url`，并配置 URL-scoped Git credential helper。后续 clone/pull/push 使用原生 git。
- `+git-credential-list` 列出本地已配置的妙搭 Git 凭证，不需要 `--app-id`。
- `+git-credential-remove` 只移除本地凭证/helper，不删除云端应用或仓库。
- 看到 Repository URL 后继续：

```bash
git clone <repository_url>
cd <repo>
git checkout sprint/default
```

## Agent 规则

- 不要手动打印、保存或拼接 token。
- clone、pull、push、diff、log 等代码仓库操作都使用原生 `git`；不存在 `apps +pull` / `apps +push` / `apps code +read` 这类代码读写 shortcut，不要臆造。
- 不要 push/force-push `main`；`main` 是发布态快照，由 `apps +release-create` 成功后服务端推进，直推/force-push 会被服务端护栏拒绝。
- Git 认证失败、本地凭证损坏或 helper 缺失时，重新执行 `+git-credential-init --app-id <id>` 覆盖本地配置；不要让用户复制 token 到 remote URL。

# apps +html-publish

把本地 HTML 文件或静态目录发布为妙搭应用访问 URL。运行时命令事实以 `lark-cli apps +html-publish --help` 为准。

## 何时用

用于把已经存在的本地 HTML 文件或静态产物目录发布成妙搭访问 URL。它不负责生成 HTML 内容，也不负责全栈应用代码发布。

## 命令骨架

- 必填：`--app-id`、`--path`。
- `--path` **必须是相对路径**（如 `./dist`、`./index.html`），不支持绝对路径。如果目标文件在其他目录，先 `cd` 到该目录再用相对路径，或用相对于当前目录的路径。
- `--path` 可以是单个文件或目录；入口必须是 `index.html`。
- 可选：`--allow-sensitive`，跳过凭据文件扫描。
- 客户端打包 tar.gz 上传发布。三条硬性大小限制，任一超限即被客户端拒绝、无法发布：单个 `.html` 文件 ≤ 10MB、打包后 tar.gz ≤ 20MB、未压缩候选文件总量 ≤ 200MB。

## 示例

```bash
lark-cli apps +create --name "Demo" --app-type html
lark-cli apps +html-publish --app-id app_xxx --path ./dist
lark-cli apps +html-publish --app-id app_xxx --path ./index.html --dry-run
```

## 输出契约

命令内部完成 tar.gz 打包 → TOS 上传 → 触发发布，返回 `data.release_id`。拿到 `release_id` 后用 `+release-get --app-id <app_id> --release-id <release_id>` 轮询发布状态直到 `finished`，从中读取 `online_url`。

- 业务失败如构建失败、应用不存在通常带 `error.hint`；优先转述 hint。网络/服务端失败则建议稍后重试。

## 链接边界

- 发布态访问链接以 `+release-get` 轮询 `finished` 返回的 `online_url` 为准。
- 重新发布前，`+list` 的 `is_published=true` 只能说明历史上发布过，不代表当前本地产物已经部署。

## 发布前置门（第一步，先于任何其他动作）

收到发布意图后，第一个动作是量三个尺寸，不是读文件内容、不是打包：
1. 单个 `.html` ≤ 10MB / tar.gz ≤ 20MB / 未压缩总量 ≤ 200MB。
2. 任一超限 → 立即 STOP，把超限数字转述给用户，交还决定权。
3. 三项都通过 → 才进入下面的命令骨架。

## 预览与发布边界

- 用户只说“用 HTML 写个 PPT/页面给我看看”时，先生成本地文件或目录，返回路径并问是否发布到妙搭分享；不要默认创建应用或部署。
- 用户明确说“部署出去/发链接/可分享”时，才创建 `html` 应用并用 `+html-publish`。
- 用户要发布但没有 app_id 时，先 `+create --app-type html` 创建应用；应用名可从页面/站点主题生成，不要让用户手动提供 app_id。
- 若产物首页不是 `index.html`，发布前改名或复制为 `index.html`；目录发布时只传干净产物目录，例如 `./dist`。`.git` 目录会被自动排除，不会进入压缩包。
- 重新部署同一个 HTML 应用时复用原 `app_id`，只重新执行 `+html-publish --app-id <id> --path <dir-or-index.html>`。

## 安全规则

默认会拦截 `.env`、`.npmrc`、`.aws/credentials` 等凭据文件。只有用户明确要发布凭据示例文件或教程内容时，才追加 `--allow-sensitive`；追加前先说明将包含哪些敏感候选文件。

## 常见失败

- `--path` 传了绝对路径：`--path` 只接受相对路径，传绝对路径会报 `--path must be a relative path within the current directory`。改用 `cd` + 相对路径，例如 `cd /target/dir && lark-cli apps +html-publish --path .`。
- 缺少 `index.html`：目录根放置 `index.html`，或单文件路径直接指向名为 `index.html` 的文件。

# apps +init

`+init` 初始化妙搭应用的代码（clone 仓库、scaffold/同步源码、拉取本地环境变量）。运行时命令事实以 `lark-cli apps +init --help` 为准。

## 何时用

用于把妙搭应用源码拉到本地并准备开发环境。用户只是要云端 Agent 生成应用时，不要初始化本地仓库。

## 命令骨架

- 必填：`--app-id`。
- 可选：`--dir`，clone 目标目录；省略时默认 `./<app-id>`。
- 固定 checkout 分支：`sprint/default`。
- `+init` 会初始化 Git 凭证、clone 仓库、切到工作分支并生成/同步本地项目。

## 示例

```bash
lark-cli apps +init --app-id app_xxx --dir ./my-app
lark-cli apps +init --app-id app_xxx --dir /absolute/path/my-app
lark-cli apps +init --app-id app_xxx --dir ./my-app --dry-run
```

## 输出契约

- 真跑时 stdout 是 JSON envelope；stderr 会有 `->` / `→` 进度行。成功读 stdout，失败解析 stderr 末尾的 JSON 错误。
- 成功普通初始化读取 `data.clone_path`、`branch`、`committed`、`pushed`；`repository_url` 已脱敏，不要当凭据使用。
- `scaffold=already_initialized` 表示目录已初始化：跳过 clone/scaffold/commit，但仍会执行一次 env-pull 刷新本地环境变量（输出含 `env_pulled`，成功时含 `env_file`，失败时含 `env_pull_error` 且退出码仍为 0）；此时通常没有 `repository_url` / `branch`。
- `--dry-run` 只打印计划，不执行 git / npx；若输出含 `dir_error`，真跑前先让用户换目录。

## Agent 规则

- 目标目录必须不存在、为空目录，或已含 `.spark/meta.json` 且其 app_id 与 `--app-id` 一致的已初始化仓库。
- 目标目录已含 `.spark/meta.json` 时，`+init` 会跳过 clone/scaffold，但仍执行一次 env-pull 刷新本地环境变量；告知用户“仓库已初始化，本地环境变量已刷新，可直接开发”，不要误报失败或重复 clone。
- `+init` 输出没有必要原样复述；告诉用户 clone path、分支和下一步即可。
- 新建应用做本地初始化时，若选定的目标目录已存在，不要复用，改用一个不冲突的目录名（已预授权”放手做”时自动追加后缀如 `-2`；否则向用户确认目录名）。

# apps +list

列出当前用户可见的妙搭应用，用于从应用名定位 `app_id`。运行时命令事实以 `lark-cli apps +list --help` 为准。

## 何时用

在下游操作需要 `app_id`、而用户只给了应用名/描述时,用 `--keyword` 定位。无明确目的的全量枚举会浪费上下文,优先按关键词缩小范围。

## 命令骨架

- 支持 `--keyword` 按应用名模糊搜索。
- `--ownership` 枚举：`all` / `mine` / `shared`（默认 `all` = 我创建的 + 共享给我的；`mine` = 仅我创建；`shared` = 仅共享给我）。
- `--app-type` 枚举：`html` / `frontend` / `full_stack`。
- 分页：`--page-size` 默认 20，`--page-token` 传上一页 cursor。

## 示例

```bash
lark-cli apps +list --keyword "审批"
lark-cli apps +list --ownership mine --app-type full_stack
lark-cli apps +list --page-token "<cursor>"
```

## 输出契约

- 成功读取 `data.items[]`；保留字段为 `description`、`app_id`、`name`、`is_published`、`online_url`、`updated_at`，用于候选展示的核心字段是 `name`、`app_id`、`updated_at`。
- `is_published=true` 只代表应用历史上有发布版本，不代表最新云端会话、最新代码提交或最新 HTML 产物已经部署。
- `online_url` 是当前已有发布态入口；若你没有在本轮确认发布完成，不要把它描述成“最新版本链接”。
- 默认输出已裁掉 `icon_url`（图片 URL，agent 无法渲染）和 `created_at`（与 `updated_at` 冗余）；需要时可用 `--jq` 过滤上述保留字段。
- `data.items` 可能为空；不要把空列表当失败。
- 若有 `has_more=true`，用返回的 `page_token` / `next_page_token` 继续翻页。

## Agent 规则

多候选时展示名称、app_id、updated_at 让用户确认。用户描述里已经有 `app_xxx` 或妙搭链接时，直接提取，不再 `+list`。

把 `+list` 当定位工具和发布态快照工具，不要把 `is_published` 当部署完成证明。需要证明“最新内容已上线”时，使用对应发布命令的完成状态：看 `+release-get` 的 `finished`。

# lark-apps 本地开发

适用：用户要把妙搭应用（full_stack、frontend 或 html）源码拉到本地，用本地 code agent/IDE 开发、再发布。其中调试数据库仅 full_stack 适用（frontend / html 无数据库）。

## 新建 vs 已有应用

新建还是修改已有，由上方入口（SKILL.md「选择开发路径」）判定；进到本地流程后按分支走：

- **新建**：从 `+create` 开始走下面的端到端流程。
- **已有应用**（本地还没有源码）：跳过 `+create`，先按下方「存量应用入口」拿 `app_id`，再 `+init`（或 `+git-credential-init` + `git clone`）把它拉到本地，然后照常开发。

## 端到端流程（新建应用）

### full_stack

`+create(full_stack)` -> `+init`（或手动 `+git-credential-init` + `git clone`）-> 读仓库 Skill -> `npm install && npm run dev` -> 按需 `+db-*` 调库 -> 非自动化改动按本页 commit/push/release；包含自动化 handler 时，在任何 release 前转到 [automation SOP](lark-apps-automation.md)，由它接管状态门禁和完整发布。

```bash
# 新建 full_stack 应用
lark-cli apps +create --as user --name "审批系统" --app-type full_stack \
  --description "支持登录、提交申请、多级审批、状态查询"

# 初始化本地仓库（--dir 取值见下方「领域规则」，勿照抄此处示例值）
lark-cli apps +init --as user --app-id app_xxx --dir ./approval-app

# 进入仓库后按项目脚手架启动
cd ./approval-app
npm install
npm run dev

# 开发完成后：提交本次改动 -> git push origin sprint/default -> +release-create。
# +release-create 部署的是远端 sprint/default 上已 push 的代码，不是本地工作区——没 commit + push 的改动不会进入发布。
git add <本次开发的文件>          # 提交粒度见下方「改完代码后部署上线」
git commit -m "feat: ..."
git push origin sprint/default
lark-cli apps +release-create --as user --app-id app_xxx --branch sprint/default
```

### frontend

纯前端应用（vite-react，无数据库）。流程与 full_stack 基本一致——`+init` 装依赖、`npm run dev`、commit/push/release——差别是无 `+db-*` 调库步骤。后续需要数据库/后端能力时不在本地升级，按 SKILL.md「类型升级」引导到云端会话。

```bash
# 新建 frontend 应用
lark-cli apps +create --as user --name "JSON 格式化工具" --app-type frontend \
  --description "纯前端交互工具，无需数据库"

# 初始化本地仓库（--dir 取值见下方「领域规则」，勿照抄此处示例值）
lark-cli apps +init --as user --app-id app_xxx --dir ./json-tool

# 进入仓库后按项目脚手架启动（vite-react）
cd ./json-tool
npm install
npm run dev

# 开发完成后：提交本次改动 -> git push origin sprint/default -> +release-create
git add <本次开发的文件>
git commit -m "feat: ..."
git push origin sprint/default
lark-cli apps +release-create --as user --app-id app_xxx --branch sprint/default
# 发布是异步的：用 +release-get 轮询到 status=finished 才算部署完成、拿到 online_url
lark-cli apps +release-get --as user --app-id app_xxx --release-id <上一步返回的 release_id>
```

### html

#### 首次开发（无 app，无代码）

`+create(html)` → `+init` → 加载 [`creative-design`](../creative-design/SKILL.md) skill 在 repo 根目录产出文件 → `git add .` + `git commit` → `git push origin sprint/default` → `+release-create` → `+release-get`。

```bash
lark-cli apps +create --name "活动页" --app-type html --as user

lark-cli apps +init --app-id app_xxx --dir ./my-page

cd ./my-page
# html 类型无需 npm install，+init 已跳过依赖安装
# 加载 creative-design skill，在 repo 根目录产出 HTML 及关联文件（JSX 组件、starter components 等）

git add .
git commit -m "feat: ..."
git push origin sprint/default
lark-cli apps +release-create --app-id app_xxx
```

#### 已有 app，二次开发/迭代

`+init`（拉取远程代码）→ 加载 creative-design skill 在 repo 根目录迭代 → `git add .` + `git commit` → `git push origin sprint/default` → `+release-create` → `+release-get`。

#### creative-design 已提前生成文件，需要 init 后迁入

`+create(html)` → `+init` → 先 `ls` 查看 repo 根目录模板结构（创意模式模板无 `src/` 目录，文件直接放根目录）→ 将已生成的所有产出文件（HTML、JSX 组件、starter components 等）拷贝到 repo 根目录 → `git add .` + `git commit` → `git push origin sprint/default` → `+release-create` → `+release-get`。

`+init` 是推荐便捷入口；想逐步手动控制时，先 `+git-credential-init` 拿 `repository_url`，再用原生 `git clone` / `git checkout sprint/default`。

**`+init` 完成后必须执行**：`cat <project-path>/.agents/skills/plugin-guide/SKILL.md`，读取仓库插件指引。该文件包含插件目录、实例配置规则和调用代码生成方式——不读就无法正确集成插件能力。文件不存在则跳过。

## Trigger guide 的项目边界

涉及自动化业务代码时，先查看工作区 `.agents/skills/`，读取与自动化任务匹配的 `trigger-guide`。它定义业务 handler 的实现与接入约束；Apps 触发器配置细节见 [automation SOP](lark-apps-automation.md)。

文件缺失或不能覆盖当前任务时，报告项目缺少可用的领域 guide；不要在本 lark-cli reference 中猜测安装命令、版本或包内目录。由项目维护方通过其受支持的初始化或同步流程补齐后，再继续代码闭环；`+init` 只负责准备本地项目，不能替代领域 guide。

## 改完代码后部署上线

已拉到本地、改完代码，用户说"推上去""部署""上线""发布到云端"时，按此序列。

若本次改动包含自动化 handler，在执行本节通用 commit/push/release 序列前就转到 [automation SOP](lark-apps-automation.md) 的匹配路径，由该 SOP 负责完整的状态门禁、commit/push、release 和可选 enable/test；不要先按本节发布再补 trigger 状态检查。下列通用序列只用于不含自动化 handler 的改动。

> `+release-create` 部署的是远端 `sprint/default` 上**已 push** 的代码，不是你本地工作区——未 commit / 未 push 的改动不会进入这次发布。所以发布前务必先把本次改动提交并推送。

1. `git status` 看本次改动；`git add <本次相关文件>` 暂存后 `git commit` 提交。只提交本次任务相关的改动即可，无关的零散文件不必强求清空——发布门禁是「**本次相关改动已提交并推送**」，不是「工作区绝对干净」。
2. `git push origin sprint/default` 把工作分支推到云端（遇非 fast-forward：先 `git pull --rebase origin sprint/default` 解决冲突再推，绝不 force-push；遇 Git 认证失败 / 401 / 403 / credential helper 缺失 / token 过期：先执行 `lark-cli apps +git-credential-init --app-id <app_id> --as user` 刷新本地 Git 凭证，再重试原 git 命令；刷新凭证也失败时，停止并向用户报告错误，不要换路）。
3. `lark-cli apps +release-create --as user --app-id <app_id> --branch sprint/default` 发起部署上线，记下返回的 `release_id`。
4. `lark-cli apps +release-get --as user --app-id <app_id> --release-id <release_id>` 轮询：`publishing` 时每 20 秒继续轮询，整体最多约 5 分钟；超时仍未完成时停止本轮轮询、报告 `release_id` 和当前 status。`finished` 成功时，若返回 `online_url`，可直接使用；未返回时不要编造链接。交付线上访问链接给他人前，注意 `online_url` 默认仅创建者可见，需先告知当前仅本人可见、按需用 `+access-scope-set` 放开可见范围。无需再调 `+list`；`failed` 时若返回非空 `error_logs`，据此给出失败原因；否则只报告 `release_id` 和当前 status，不要编造原因（`+list` 仅作独立查询入口）。

用户只要求启用已有 trigger 时，转到 [automation SOP 的「仅启用已有 disabled trigger」路径](lark-apps-automation.md#仅启用已有-disabled-trigger)；不得因 enable 反向修改 handler、commit/push 或 release。

## 领域规则

- 代码读写走原生 `git`；CLI 负责凭证、初始化、发布和数据库调试。不存在 `apps +pull` / `apps +push` / `apps code +read` 这类代码读写 shortcut，不要臆造。
- 工作环境没有 `git` 时，先引导安装 Git（macOS 可用 `xcode-select --install` 或 `brew install git`；Linux 按发行版包管理器安装），安装后重试原 `+init` / git 命令；不要因此改走其他发布链路。
- `+init` 会编排 `+git-credential-init`、`git clone`、切到 `sprint/default`、运行脚手架，并在有变更时提交/推送。
- `+init --dir` 选目录：用户已预授权或表达"不要询问"（见 SKILL.md「预授权判定」）→ 按应用名派生 `./<app-name>` 直接传 `--dir`、不停问；否则先问用户用哪个目录再传。目标已存在/非空时回问换目录。
- `sprint/default` 是工作分支；`main` 是发布态快照，由 `+release-create` 成功后服务端 fast-forward 推进；服务端护栏禁直推 `main`、拒 force-push、要求 `sprint/default` fast-forward。
- 已拉到本地后，pull/push/diff/log 都用原生 git；云端 `sprint/default` 比本地新时，先 `git pull --rebase origin sprint/default`，解决冲突后再 push 和 publish。
- `git clone` / `git pull` / `git push` 如果报认证失败、401/403、credential helper 缺失或 token 过期，优先重新执行 `lark-cli apps +git-credential-init --app-id <app_id> --as user` 更新本地 Git 凭证，然后重试原 git 命令；刷新凭证也失败时，停止并向用户报告错误，不要换路；不要手动复制 token、不要把 token 拼进 remote URL。
- 环境变量由脚手架在本地启动时处理；需要手动刷新时用 `+env-pull`。
- 资源型文件（图片、字体、音视频等）不要直接引用本地路径，也不要提交到 git 仓库或以 base64 内联到代码中。先通过 `lark-cli apps +file-upload --app-id <app_id> --file <local_path>` 上传到应用文件存储，拿到返回的远端 URL 后在代码中引用该 URL。详情读 [`lark-apps-file.md`](lark-apps-file.md)。上传返回的链接按 app 隔离，不同应用必须各自重新上传，不能跨应用复用同一链接。
- DB 调试用 `+db-table-list` / `+db-table-get` / `+db-execute`；不要裸连数据库或自行拼连接串。
- DB 分 `dev` / `online`；使用 `--environment dev|online`，不要使用旧的 `--env`。只有确认应用已开启多环境时才引导 `--environment dev`；单环境应用省略 `--environment`（服务端选 online）或显式传 `--environment online`。在 dev 写入不能证明线上 handler 已验证。dev 的库结构变更要上线时，仍按应用发布链路走 `+release-create`，不要另造“数据库发布”步骤。
- 存量单库应用需要 dev/online 多环境时，用 `+db-env-create --environment dev`。这是不可逆 high-risk 操作。
- 只从 `+list` 看到 `is_published=true`，不能证明本地刚推送的代码已经部署；必须有本轮 `+release-get finished`。

## 存量应用入口

已有项目目录先读 `.spark/meta.json` 取 `app_id`；没有本地项目但知道应用名时用：

```bash
lark-cli apps +list --keyword "应用名"
```

拿到 `app_id` 后再 `+init` 或 `+git-credential-init`。

## 何时不用

- 用户明确要云端妙搭 Agent 生成/迭代，而不是本地写代码：读 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md)。

# apps observability

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。

查询妙搭应用的线上运行观测和产品访问分析。所有 observability 命令只支持 `--environment online`；省略 `--environment` 时默认就是 online，传 dev 或其他环境是不支持的。不要使用旧的 `--env`，也不要使用短选项。

日志和 trace 的用户侧环境仍然是 online；但 OpenAPI 请求体里的后端 `app_env` 固定发送 `runtime`，因为线上应用的运行时日志和 trace 存储在 runtime 观测环境下。dry-run 输出会展示这个后端参数。

metric / analytics 的 `--environment` 只是 CLI 侧 online-only 校验：`+metric-list` 和 `+analytics-list` 不会向 OpenAPI body 发送 `env` 或 `app_env`。dry-run 里看不到环境字段是预期行为，不要补造参数。

时间过滤支持相对时间（如 `30s`、`5m`、`0.5h`、`2h`、`3d`、`1w`）、本地日期 / 时间和 RFC3339。

## 命令选择

- 日志检索：用 `+log-list` 搜索日志，用 `+log-get` 按 log ID 取单条日志。
- `+log-list` 不再支持 `--log-id`；已有 log ID 时直接用 `+log-get --log-id <log_id>`。
- 前端 ERROR 日志详情：`+log-get` 可能补充 `source_stack`；没有独立的 source-stack 命令。
- Trace 检索：用 `+trace-list` 搜索 trace，用 `+trace-get` 按 trace ID 取详情。
- 运行时指标：请求数、错误、延迟、CPU、memory 用 `+metric-list`。
- 产品分析：PV、UV、访问量这类业务访问分析用 `+analytics-list`，不要放到 runtime metric 里混查。
- `+analytics-list` 按最新 OpenAPI 发送 `metric_types`、纳秒时间戳和 `need_pack_lack_point=false`；`group_by` 暂不支持。
- 用户询问“最近一小时接口请求量、错误量、延迟、接口慢/报错多”时，这是平台运行时监控，不是本地项目文件。先用 `apps +list --keyword` 找 `app_id`，再查 `+metric-list`。

## 示例

```bash
lark-cli apps +log-list --app-id <app_id> --level error --keyword timeout --since 0.5h
lark-cli apps +log-get --app-id <app_id> --log-id <log_id>
lark-cli apps +trace-list --app-id <app_id> --trace-id <trace_id>
lark-cli apps +trace-get --app-id <app_id> --trace-id <trace_id>
lark-cli apps +metric-list --app-id <app_id> --metric requests --series total --since 1d
lark-cli apps +metric-list --app-id <app_id> --metric requests --since 1h
lark-cli apps +metric-list --app-id <app_id> --metric latency --since 1h
lark-cli apps +metric-list --app-id <app_id> --metric latency --series p99 --since 1d
lark-cli apps +metric-list --app-id <app_id> --metric cpu --since 1h
lark-cli apps +metric-list --app-id <app_id> --metric memory --since 1h
lark-cli apps +analytics-list --app-id <app_id> --analytics users --series active-users --granularity day
lark-cli apps +analytics-list --app-id <app_id> --analytics page-view --granularity day
```

## 使用边界

- 如果用户问“接口慢、报错多、CPU/内存高”，优先走 `+metric-list`。
- `+metric-list --metric requests` 不传 `--series` 会同时返回请求总量 total 和错误量 error；`--metric latency` 不传 `--series` 会同时返回 p50 和 p99。只想看单条曲线时再传 `--series total|error|p50|p99`。
- 按接口收窄范围时使用 `--api <path-or-name>`；当前没有 `group-by` 参数，不要臆造。
- `+metric-list` 未显式传 `--down-sample` 时会按时间范围自动选择粒度：短范围用 `1m`，中等范围用 `1h`，长范围用 `1d`；显式传入时尊重用户指定。
- 如果用户问“页面访问量、PV、UV、活跃用户”，优先走 `+analytics-list`。
- 如果用户已有 `trace_id` 或 `log_id`，直接用对应 get 命令；不知道 ID 时先 list。

# apps openapi-key 命令族 SOP

管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。全部操作需 `--as user`（AuthType: user）。`--help` 是参数细节的完整来源；本文件只记录 Agent 不看就会做错的领域规则。

## 命令路由

| 命令 | 用途 |
|---|---|
| `+openapi-key-list` | 列出应用所有 API Key（脱敏） |
| `+openapi-key-get` | 查看单个 Key 详情（脱敏） |
| `+openapi-key-create` | 创建新 Key，**原始密钥一次性可见** |
| `+openapi-key-update` | 改名或改 config（不改 status） |
| `+openapi-key-enable` | 启用 Key（status→1） |
| `+openapi-key-disable` | 停用 Key（status→0），**泄露/疑似泄露优先用这个而非 delete** |
| `+openapi-key-delete` | 永久删除 Key（不可逆） |
| `+openapi-key-reset` | 轮换密钥（刷新原始 Key），**一次性可见** |

## 脱敏口径（安全关键）

- `list` / `get` / `update` / `enable` / `disable`：返回结构里 **无** `api_key` 字段，只有 `key_preview`（格式：`****` + 原始密钥末 4 位，如 `****5f4a`）。
- `create` / `reset`：**仅** 在 `data.api_key`（顶层）返回原始密钥一次；同时在 stderr 打印一次性提示：
  ```
  warning: this api_key is shown only once and is NOT stored by lark-cli — copy it now and store it in your own secret manager.
  ```
- 原始密钥绝不写入 cache / config / recent / debug log / 错误信息。

## 一次性密钥语义

CLI 不保存原始密钥。密钥在 `create` / `reset` 时仅随响应返回一次。**密钥丢失不能用 `get` 找回**——唯一恢复方式是 `+openapi-key-reset` 重新生成新密钥（旧密钥同时失效）。

## scope 结构与 CLI 表达

后端 `config.request_scope` 的真实结构（**snake_case**——Lark 开放网关 `/open-apis/` 对外契约约定；`api_key.thrift` 的 camelCase go.tag 是内部表示，OGW 已转成 snake_case）：

```json
{
  "allow_all": true,
  "http_infos": [
    { "http_method": "GET", "http_path": "/openapi/some-path" }
  ]
}
```

- `allow_all=true`：放开该应用所有 `/openapi/**` 路由；`http_infos` 此时忽略。
- `allow_all=false`：按 `http_infos` 逐条授权，每条需 `http_method`（大写）+ `http_path`（`/openapi/` 开头）。

CLI 提供三种互斥的 scope 表达方式：

| flag | 用途 | 备注 |
|---|---|---|
| `--scope-all` | `allow_all=true`，放开所有路由 | bool flag，显式传 `--scope-all=false` 也算"已设置" |
| `--scope-api 'METHOD /openapi/path'` | 逐条授权一个路由，可重复 | 路由从应用 `docs/openapi.json` 取 |
| `--scope '<raw request_scope JSON>'` | 高级逃生口，直传 request_scope JSON（snake_case） | CLI 只校验合法 JSON；`--scope` 与 `--scope-all`/`--scope-api` 互斥 |

### scope 值来源

妙搭应用的 `/openapi/**` 路由定义在应用仓库，并同步维护在 `docs/openapi.json`（`paths` 下每个 `"/openapi/..."` 条目 + HTTP 方法）。要授权哪些路由，读目标应用自己的 `docs/openapi.json`，取 `(method, path)` 对。CLI 本身不提供 API 路由发现功能（P1 规划中）。

## 高风险操作

`delete` 和 `reset` 是高风险（`high-risk-write`），有以下约束：

- 需显式传 `--yes`（框架 `cmdutil.RequireConfirmation`）；缺少时退出码 10，**不要自动补 `--yes`**（遵循 lark-shared 安全红线）。
- 支持 `--dry-run` 查看将要执行的 HTTP 请求（不含密钥）；不确定时先 dry-run。
- **泄露场景**：应优先 `+openapi-key-disable` 立即停用，而非 `+openapi-key-delete`——停用可随时 enable 恢复，delete 不可逆。

## 典型决策场景

| 用户意图 | 正确操作 |
|---|---|
| "key 泄露了，先停掉" | `+openapi-key-disable`（不是 delete） |
| "key 丢了/忘了，再给我一个" | `+openapi-key-reset`（不是 create 新 key；reset 轮换密钥、保留原 key 配置） |
| "我的 key 密钥是什么" | 解释：list/get 不回显原始密钥，只能用 `+openapi-key-reset` 轮换 |
| "给应用创建一个有权限限制的 key" | `+openapi-key-create --name ... --scope-api 'GET /openapi/...'`（路由取自应用 `docs/openapi.json`） |

## 不在本 skill 范围

- OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。
- 身份选择、权限不足处理（`missing_scopes`→`console_url`）、exit-10 审批、通用"禁输出密钥"红线、高风险操作通用框架：见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)，不在此重复。

# apps +plugin-install

> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。

安装插件包到项目。运行时命令事实以 `lark-cli apps +plugin-install --help` 为准。

## 何时用

用户要接入 AI 能力或飞书平台能力，需要先安装对应的插件包。安装后才能创建插件实例。具体有哪些可用插件、该选哪个，读取创建的应用仓库 Skill：`.agents/skills/plugin-guide/SKILL.md`。

**插件包 ≠ npm 包**：插件包写入 `actionPlugins`，npm 写入 `dependencies`，两套独立机制。禁止用 `npm install` 代替本命令。

## 命令骨架

- `--name <key>`：插件包 key（从仓库 Skill 的「AI 插件目录」获取）。不传则批量安装 `actionPlugins` 中声明的所有插件。
- `--version <ver>`：指定版本（如 `1.0.0`）。不传则安装最新版。

在项目根目录下运行（和 npm 一样，无需指定路径）。

## 示例

```bash
# 安装最新版
lark-cli apps +plugin-install --name <plugin-key>

# 安装指定版本
lark-cli apps +plugin-install --name <plugin-key> --version 1.0.0

# 批量安装已声明的所有插件
lark-cli apps +plugin-install
```

## 输出契约

- 已安装同版本会跳过（status=already_installed）。
- 失败时 hint 指示原因（网络/版本不存在/package.json 缺失）。

# apps +plugin-list

> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。

列出已声明的插件包及安装状态。运行时命令事实以 `lark-cli apps +plugin-list --help` 为准。

## 何时用

查看当前项目声明了哪些插件、是否已安装。`declared_not_installed` 状态表示需要运行 `+plugin-install` 安装。

## 命令骨架

在项目根目录下运行（和 npm 一样，无需指定路径）。

## 示例

```bash
lark-cli apps +plugin-list --format json
```

## 输出契约

- `data.plugins[]` 包含 `key`、`version`、`status`（`installed` / `declared_not_installed`）。

# apps +plugin-uninstall

> **本地命令**：读当前目录的 `package.json`，在项目根目录下运行（和 npm 一样）。**不接受 `--app-id`**——它不是远端 API 命令。

卸载插件包。运行时命令事实以 `lark-cli apps +plugin-uninstall --help` 为准。

## 何时用

用户不再需要某个插件能力时，卸载对应的插件包。卸载前应先删除该插件的所有实例。

## 命令骨架

- `--name <key>`：要卸载的插件包 key。

在项目根目录下运行（和 npm 一样，无需指定路径）。

## 示例

```bash
lark-cli apps +plugin-uninstall --name <plugin-key>
```

## 输出契约

- 删除 `node_modules/{key}` + 移除 `actionPlugins` 条目。

# apps +release-create

为妙搭应用创建发布 release。运行时命令事实以 `lark-cli apps +release-create --help` 为准。

## 何时用

用于把应用的代码分支推进到发布流程（html / frontend / full_stack 统一走此入口）。

## 命令骨架

- 必填：`--app-id`。
- 可选：`--branch`；省略时服务端使用默认发布分支。
- 返回 `release_id` 和 `status`，后续用 `+release-get` 轮询。

## 示例

```bash
lark-cli apps +release-create --app-id app_xxx
lark-cli apps +release-create --app-id app_xxx --branch sprint/default --dry-run
```

## 输出契约

- 成功读取 `data.release_id`、`data.status` 和 `data.sync`；`release_id` 是后续 `+release-get` 的入参。
- `sync=true` 表示同步部署（服务端等待部署完成后才返回），`sync=false` 或缺失表示异步部署。
- `status=publishing` 表示发布仍在进行；继续用 `+release-get` 轮询，轮询间隔应该为 20s。应用发布平均耗时大约 2min，整体超时时间大约 5min。
- `status=finished` 表示部署已完成（同步部署时可能直接返回此状态）。
- `+release-create` 返回 release 只代表发布已发起。只有 `+release-get` 对同一个 `release_id` 返回 `finished` 后，才能说本轮最新版本已部署。

## Agent 规则

`+release-create` 部署的是远端 `sprint/default` 上已 push 的代码，不是本地工作区——本地若有你修改但未推送的改动，需要先 `git add` + `git commit` 并 `git push` 到 `sprint/default`，否则这些改动不会进入这次发布。`git push` 如遇认证失败、401/403、credential helper 缺失或 token 过期，先执行 `lark-cli apps +git-credential-init --app-id <app_id> --as user` 刷新本地 Git 凭证，再重试原 git 命令；刷新凭证也失败时，停止并向用户报告错误，不要换路；不要手动复制 token 或改 remote URL。发布后若 status 是 `publishing`，用 [`+release-get`](lark-apps-release-get.md) 查询。`+release-create` 部署上线属高影响动作——作为别的命令的连带前置时，按 SKILL.md「高影响动作：确认与预授权」先征得用户同意再发布。

# apps +release-get

按 release ID 查询单次发布详情。运行时命令事实以 `lark-cli apps +release-get --help` 为准。

## 何时用

用于跟进已知 `release_id` 的发布状态。没有 `release_id` 时先读 [`lark-apps-release-list.md`](lark-apps-release-list.md)，不要让用户手填。

`release_id` 是妙搭发布 ID（`+release-create` 返回），不是飞书审批实例号；查发布进度/失败都在 `apps +release-*` 命令族内完成，不要路由到 lark-approval。

## 命令骨架

- 必填：`--app-id`、`--release-id`。
- `release_id` 来自 `+release-create` 或 `+release-list`。

## 示例

```bash
lark-cli apps +release-get --app-id app_xxx --release-id release_yyy
```

## 输出契约

- 成功可能直接返回 release 字段，也可能包在 `data.release`；读取 `release_id`、`status`、`created_at`、`updated_at`，以及 `commit_id`（本轮发布对应的 git commit SHA，pretty 输出在其非空时展示一行）。
- `status=publishing` 继续轮询。此时尚无 `online_url`；不要拿其它链接（如 `+list` 里的应用主页 / 开发态预览 URL）冒充"本轮发布的访问链接"——只回报 `release_id`、`status`，并说明 `finished` 后才可能有 `online_url`。
- `status=finished` 发布成功——若输出含 `online_url`，直接读取它作为本轮发布的线上访问链接；未返回时只报告发布完成，不要编造链接。该链接默认仅创建者可见，交付他人前先告知当前仅本人可见、按需用 `+access-scope-set` 放开可见范围。无需再调 `+list`（`+list` 仍可用于按应用名浏览，但不是发布主流程的必经步骤）。
- `status=failed` 发布失败——若输出含 `error_logs`（`step`/`error_log`），据此向用户转述关键失败步骤和可行动修复；未返回时不要编造失败原因。
- 只有当这个 `release_id` 已返回 `finished`，随后读到的 `online_url` 才能被表述为"本轮发布后的访问链接"。单独从 `+list` 看到 `is_published=true` 不能证明最新版本已部署。

# apps +release-list

分页查询妙搭应用发布历史，最新发布在前。运行时命令事实以 `lark-cli apps +release-list --help` 为准。

## 何时用

用户问"最近发布""历史版本""上次为什么失败"，但没有提供 `release_id` 时使用。拿到候选 release 后再接 `+release-get`。

## 命令骨架

- 必填：`--app-id`。
- 可选 `--status`：`publishing` / `finished` / `failed`。
- 可选 `--page-size`：默认 20，最大 500；总是发送给服务端。
- 可选 `--page-token`：上一页 cursor。

## 示例

```bash
lark-cli apps +release-list --app-id app_xxx --page-size 10
lark-cli apps +release-list --app-id app_xxx --status failed
```

## 输出契约

- 成功读取 `data.releases[]`；关键字段是 `release_id`、`status`、`created_at`、`updated_at`。
- `release_id` 用于继续查 `+release-get`。
- 若 `has_more=true`，用 `next_page_token` / `page_token` 翻页。

## Agent 规则

用户限定只看 N 条（"最近 N 条""最新 N 个""只要前 N 条"）时用 `--page-size N`（如"最近一次发布"→ `--page-size 1`），而不是取全量再本地截断。

# apps role 域命令（应用角色）

管理妙搭应用内的平台角色、角色成员，以及查询某个用户命中的角色。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；身份、授权和高风险确认遵循本域 [`SKILL.md`](../SKILL.md)。

## 何时用

用户要列出、查看、创建、更新或删除某个妙搭应用内的平台角色，管理角色的用户、部门或群成员，或查询某个用户在应用中命中的角色时使用。多维表格 / Base 的角色与权限走 `lark-base`；设置谁能访问应用走 `+access-scope-*`，不要路由到本命令域。

## 命令一览

| 命令 | 做什么 | 关键参数 |
|---|---|---|
| `+role-list` | 分页列出角色，或按名称筛选角色 | `--app-id`、`--name`、`--page-size`/`--page-token` |
| `+role-get` | 根据真实 `role_id` 读取角色详情 | `--app-id`、`--role-id` |
| `+role-match-list` | 查询指定用户命中的角色 | `--app-id`、`--user-id` |
| `+role-create` | 创建角色 | `--app-id`、`--name`、`--description`、`--role-id` |
| `+role-update` | 更新角色名称或描述 | `--app-id`、`--role-id`、`--name`/`--description` |
| `+role-delete` | 永久删除角色 | `--app-id`、`--role-id`、`--yes` |
| `+role-member-list` | 查询角色的用户、部门和群成员 | `--app-id`、`--role-id`、`--member-type` |
| `+role-member-add` | 向角色添加用户、部门或群成员 | `--app-id`、`--role-id`、`--users`/`--departments`/`--chats` |
| `+role-member-remove` | 定向移除或清空角色成员 | `--app-id`、`--role-id`、成员参数或 `--all`、`--yes` |

## 约定（先读）

- `app_...` 标识的是妙搭应用，其角色和成员只使用 `apps +role-*` / `apps +role-member-*`；不要改走 Base 角色命令或裸 bitable API。
- 角色名称不是 `role_id`。只有名称时优先用 `+role-list --name` 精确解析；若已取得完整分页列表，也可从中证明精确名称唯一命中。0 条如实报告，多条让用户消歧，唯一命中后才使用返回的真实 ID。
- `+role-list` 返回 `has_more=true` 时，用本页 `page_token` 继续查询，直到 `has_more=false`；不要根据 `total` 补造条目。
- `+role-list`、`+role-get`、`+role-match-list` 的角色数据分别位于 `data.items`、`data.role`、`data.roles`，不要混用。
- 同一角色的写入及依赖该写入结果的操作必须串行。不同角色的独立操作只有在每次写入可单独追溯、失败不影响其它目标且分别验收时才可并行；否则保持串行。互不依赖的名称解析或只读查询可并行。

## 各命令

### 查询角色

```bash
lark-cli apps +role-list --app-id <app_id> --page-size 100
lark-cli apps +role-list --app-id <app_id> --name '<exact_name>'
lark-cli apps +role-get --app-id <app_id> --role-id <role_id>
lark-cli apps +role-match-list --app-id <app_id> --user-id <ou_x>
```

整理角色列表时保留 `role_id`、`name` 和 `description`。不要猜测未知 `role_id`，也不要从同名候选中静默选择。
`items=[]` 时直接报告当前没有角色；不要为表格补造“无”或 `N/A` 占位行。
`+role-match-list --user-id` 只接受 `ou_...`；用户给的是姓名、邮箱或手机号时，先解析唯一 open ID，再查询命中角色。

### 创建与更新

```bash
lark-cli apps +role-create --app-id <app_id> --name '<name>' \
  --description '<description>'

# 只修改名称
lark-cli apps +role-update --app-id <app_id> --role-id <role_id> \
  --name '<new_name>' --as user --format json

# 只修改描述
lark-cli apps +role-update --app-id <app_id> --role-id <role_id> \
  --description '<new_description>' --as user --format json
```

- `--description` 和创建时的 `--role-id` 可选；仅在确实需要稳定 ID 时传 `--role-id`，创建后不能修改。
- 更新时只传用户明确要求变更的字段。
- 成功响应中的角色位于 `data.role`。只有用户要求独立验证，或结果将用于后续高风险操作时，才额外执行 `+role-get`。

### 删除角色

普通“删除某角色”请求只说明目标，**不等于不可逆确认**。如果用户尚未明确确认删除后果，本轮只能定位角色、读取完整成员并说明影响，最后请求确认；不得在同一轮自动追加 `--yes`。用户已明确确认不可逆删除时才继续。

只有名称时仍按上述规则唯一解析，优先使用 `+role-list --name`。目标写前已不存在时立即停止，如实说明本次是 no-op、没有执行删除，不能把“当前不存在”表述为“删除成功”。

删除前读取准确角色和完整成员范围，向用户说明 app、role、`users` / `departments` / `chats` 影响；得到不可逆删除确认后才使用 `--yes`：

```bash
lark-cli apps +role-get --app-id <app_id> --role-id <role_id>
lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id>
lark-cli apps +role-delete --app-id <app_id> --role-id <role_id> --yes
```

成功响应包含匹配的 `data.role_id` 和 `data.deleted=true`。只有用户明确要求独立验证删除结果时，才再用 `+role-list --name` 检查目标 ID 已不存在。

### 成员 ID 解析

成员 flags 只接受 open ID：用户 `ou_...`、部门 `od-...`、群 `oc_...`。用户已提供对应类型的合法 open ID 时直接使用；只有名称或邮箱时才解析。
对象类型以用户语义为准，不能互换解析器：用户走通讯录用户搜索，部门走部门搜索，群走群搜索。

```bash
# 用户：每个姓名或邮箱单独查询。
lark-cli contact +search-user --query '<姓名或邮箱>' \
  --exclude-external-users --page-size 30

# 部门：拉完分页，只接受唯一的 open_department_id。
lark-cli api POST /open-apis/contact/v3/departments/search \
  --params '{"user_id_type":"open_id","department_id_type":"open_department_id","page_size":50}' \
  --data '{"query":"<部门名称>"}'

# 群：拉完分页，只接受名称精确匹配的唯一 chat_id。
lark-cli im +chat-search --query '<群名称>' --page-size 50
```

- 只接受与输入姓名、邮箱或群名精确匹配的唯一结果；部门搜索只接受完整 query 的唯一 `od-...`。0 条、多条或分页未完成时停止写入并让用户补充或消歧。
- 多个对象逐个解析。全部解析成功且总数不超过 100 后，按类型放入一次成员写入；任一对象失败时不要部分写入，也不要自动拆批。

### 成员操作

```bash
# 省略 --member-type，返回完整 users / departments / chats。
lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id>

lark-cli apps +role-member-add --app-id <app_id> --role-id <role_id> \
  --users ou_x,ou_y --departments od-x --chats oc_x

lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> \
  --users ou_x --yes

# 清空成员，不删除角色。
lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> \
  --all --yes
```

- `+role-member-list` 不分页；`--member-type` 只返回选中类型的字段，未返回的成员字段表示“未查询”而不是空。影响确认或完整比较时必须省略它。
- 汇总 `--member-type` 结果时明确这是过滤投影，不得据此断言角色没有其它类型成员。
- 用户要求 CLI 原生 table 时，直接执行 `+role-member-list --format table`；可原样转发或做事实摘要，不要先取 JSON 再手工重建一张替代表格。
- 写入和依赖其结果的回读不得放进同一个并发批次；必须等待写入完整返回成功后，再单独发起回读。误并发时只能以写入完成后的新回读作为结果证据。
- 添加前仅在用户要求独立证明或确认其他成员类型未变化时读取完整基线，并在写后完整回读；否则成功响应即可作为结果。
- 定向移除前确认准确成员及影响。若需要证明结果，写后完整回读；不要把过滤结果当作完整成员集合。
- `--all` 前读取完整成员范围并确认；成功后执行一次无过滤 `+role-member-list`，确认三个成员数组均为空。

## 权限

| 操作 | 所需 scope |
|---|---|
| list / get / member-list / match-list | `spark:app:read` |
| create / update / delete / member-add / member-remove | `spark:app:write` |

# apps +session-messages-list

按 page_token 分页读取某个会话轮次（turn）的回复消息。运行时命令事实以 `lark-cli apps +session-messages-list --help` 为准。

## 何时用

用于拉取妙搭应用一轮对话（turn）产生的回复消息列表。只读，scope `spark:app:read`，用户身份。对仍在 running 的 turn 也可读——消息随生成增量出现，配合 `--page-token` 续拉新消息，可用于云端开发期间实时播报本轮进展。它不发消息、也不判断轮次状态；想知道某轮是否跑完、拿 `turn_id`，仍先用 `+session-get`。

## 命令骨架

```bash
lark-cli apps +session-messages-list --app-id <app_id> --session-id <session_id> --turn-id <turn_id> [--page-token <token>]
```

| 旗标 | 必填 | 说明 |
|------|:----:|------|
| `--app-id` | 是 | 应用 ID |
| `--session-id` | 是 | 会话 ID |
| `--turn-id` | 是 | 轮次 ID，来自 `+session-get` 的 `latest_turn.turn_id` |
| `--page-token` | 否 | string，上一页响应里的 `next_page_token`；首页省略 |

## turn_id 来源

`--turn-id` 不是用户能直接提供的，必须先跑 `+session-get` 拿 `latest_turn.turn_id`。没有 `turn_id` 时不要猜，先 `+session-get`。

## 示例

先取最新轮次的 `turn_id`，再拉第一页，最后用 `next_page_token` 续拉下一页：

```bash
# 1. 从 +session-get 提取 latest_turn.turn_id
TURN_ID=$(lark-cli apps +session-get --app-id app_xxx --session-id conv_xxx -q '.data.latest_turn.turn_id')

# 2. 拉第一页（省略 --page-token）
lark-cli apps +session-messages-list --app-id app_xxx --session-id conv_xxx --turn-id "$TURN_ID"

# 3. has_more=true 时，把上一页的 next_page_token 作为 --page-token 续拉
lark-cli apps +session-messages-list --app-id app_xxx --session-id conv_xxx --turn-id "$TURN_ID" --page-token tok_next
```

## 输出契约

- `data.messages[]`：每条含 `message_id`、`role`、`content`。
- `data.next_page_token`（string）：下一页分页令牌，作为下次调用的 `--page-token`。**注意它在最后一页仍非空**（解码形如 `{"offset":N}`），不能用它是否为空判断还有没有下一页。
- `data.has_more`（bool）：是否还有更多消息。**这是判断要不要续拉的唯一依据。**
- pretty 输出为消息表 + 末行 `next_page_token: <token>  has_more: <bool>`；自动化取字段用 JSON 或 `-q`。
- 业务失败（app/session/turn 不存在或 ID 写错）通常带 `error.hint` 指向 `+session-get`，优先转述 hint。

## 分页规则

单次调用只返回一页。Agent 自行续拉：把本次响应的 `next_page_token` 作为下次的 `--page-token`，直到 `has_more` 为 `false` 才停。首页不要传 `--page-token`。

> ⚠️ **终止条件只看 `has_more`，不要拿 `next_page_token` 是否为空判断。** 即使 `has_more=false`（已是最后一页），后端仍会返回一个非空的 `next_page_token`（解码形如 `{"offset":N}`）；若以「token 非空就继续」为循环条件，会在末页之后继续翻出空页（每页 0 条），白费调用。读到 `has_more=false` 立即停止，不要再用该 token 续拉。

# apps +update

部分更新妙搭应用元信息。运行时命令事实以 `lark-cli apps +update --help` 为准。

## 何时用

只更新应用展示元信息。用户要改代码、发布内容、可见范围或数据库时，不走 `+update`。

## 命令骨架

- 必填：`--app-id`。
- 至少提供一个：`--name` 或 `--description`。
- 只发送用户提供的字段，不会清空未提供字段。

## 示例

```bash
lark-cli apps +update --app-id app_xxx --name "审批系统"
lark-cli apps +update --app-id app_xxx --description "用于部门审批流转"
lark-cli apps +update --app-id app_xxx --name "审批系统" --description "用于部门审批流转" --dry-run
```

## 输出契约

- 成功读取 `data.app`；响应是完整应用对象，不只是被修改字段。
- 缺 `--app-id` 或没有提供 `--name` / `--description` 会在本地 validation 失败。

## Agent 规则

更新前复述要变更的字段；用户没有提到的字段不要补默认值。执行后只转述新的名称/描述和 app_id，不需要展开原始响应。

# apps +user-id-convert

把一批已知 ID 在**妙搭 user_id** 与**飞书开放平台 ID**（open_id / union_id / 飞书 user_id）之间互转。运行时命令事实以 `lark-cli apps +user-id-convert --help` 为准。

## 何时用

沙箱里的 Code Agent 常通过 `contact` / `im` 域拿到飞书 `open_id`，但下游（妙搭插件、审批、网关）消费的是妙搭 `user_id` 或飞书 `user_id`。这个命令补上中间那一步转换。典型场景：

- feishu-approval 插件要发起审批，`createApprovalInstance` 需要飞书 `user_id`，而手里只有妙搭 `user_id` → 用 `miaoda-to-feishu-user-id`。
- 插件配置表单 / 人员选择器返回 `open_id`，但最终要落库妙搭 `user_id` → 用 `open-id-to-miaoda`。

它只做一件事——转换。**没有**本地映射表、缓存、权限预判，也不猜方向。它不替代权限校验：能不能拿到目标 ID 仍由上游 scope 和文档/审批自身的可见范围决定，本命令只转换一个已知 ID 的格式。

## 命令骨架

- 必填 `--convert-type`：转换方向枚举，缺失或非法直接报可读的校验错误，不猜默认方向。
- 必填 `--ids`：逗号分隔，或 `@文件` / `-`（stdin）。每次 1–100 个（服务端上限 100；CLI 额外拒绝空批以免空跑）。**不去重**，按输入顺序返回。
- 只读命令，无写副作用，不需要 `--yes`。
- 需要 scope `spark:directory.user.id_convert:read`。限流 50 req/s，CLI 不自动重试。

### `--convert-type` 方向表

| `--convert-type` | 含义 | 目标形态 |
| --- | --- | --- |
| `miaoda-to-open-id` | 妙搭 user_id → 飞书 Open ID | `ou_…` |
| `miaoda-to-union-id` | 妙搭 user_id → 飞书 Union ID | `on_…` |
| `open-id-to-miaoda` | 飞书 Open ID → 妙搭 user_id | 数字串 |
| `union-id-to-miaoda` | 飞书 Union ID → 妙搭 user_id | 数字串 |
| `miaoda-to-feishu-user-id` | 妙搭 user_id → 飞书 user_id | 数字（employee_id） |

## 示例

```bash
# 批量把 open_id 转妙搭 user_id
lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids ou_abc123,ou_def456 --as user

# 从 stdin 读 ID 列表
printf 'ou_abc123,ou_def456' | lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids - --as user

# 只看将要发送的请求体，不真正调用
lark-cli apps +user-id-convert --convert-type miaoda-to-feishu-user-id --ids 1234567890123456 --dry-run --as user
```

## 输出契约

标准 apps stdout 信封，agent 用 `ok == true` 判成功（不是 `code == 0`）。响应字段保持服务端 `snake_case`。

- `data.convert_type`：回显所传的 `--convert-type`。
- `data.items[]`：`{index, source_id, target_id}`，`index` 是该 ID 在 `--ids` 中的 0 基位置。
- `data.missed[]`：服务端静默丢弃的未解析 ID，CLI 用输入位置 diff 重建，`{index, source_id, reason: "not_found"}`。
- `meta`：`{total, hit_count, missed_count}`，`total` = `--ids` 输入数（含重复，不去重），且 `hit_count + missed_count = total`。

**部分命中**：批量里只要有 ID 转不出，它不是错误——服务端省略该项，CLI 把它落到 `missed`（`reason: not_found`），并保留 `index` = 输入位置，重复 ID 也能按位置回填。

## Agent 规则

- **方向不匹配不是错误**：比如在 `miaoda-to-open-id` 下传了 `ou_` 开头的 ID，服务端省略它 → 落到 `missed`。看到 `missed` 时先检查 ID 前缀是否与 `--convert-type` 方向一致。
- **整批被拒**（服务端 `code != 0`）才是 `api` 错误，带透传 code 和 `log_id`，不重试；限流同理，降低调用频率。
- 结果只在 stdout 返回一次，不落盘、不写会话上下文。

## 边界

只转换 ID 格式，不判断调用方是否有权拿到目标 ID。是否有权限由上游 scope 与资源自身可见范围决定，本命令不做预检。

---
name: lark-apps
version: 1.0.0
description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、本地全栈开发、云端生成迭代、创意设计（UI mockup / 可交互原型 / 线框图 / 落地页 / 仪表盘 / 幻灯片 deck / 视觉探索）、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用协作者与协作权限设置、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或要设计 / design / mockup / prototype / wireframe / 做 PPT / deck / 视觉探索，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用协作者/开发权限、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
metadata:
  requires:
    bins: ["lark-cli"]
  cliHelp: "lark-cli apps --help; lark-cli apps +<cmd> --help"
---

# apps (v1)

妙搭应用属于用户资产。默认用 `--as user`；认证、scope、exit-10、高风险确认、`_notice` 等通用处理只读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不要在本 skill 里复制。妙搭应用有两条开发路径：**本地开发**（拉源码本地写）/ **云端会话**（妙搭 AI 生成）。

## 身份与授权

妙搭应用是用户的个人资产，统一 `--as user`（见开头）。已有用户身份可用时直接执行业务命令，**不要为了预防权限问题主动重新登录**，否则可能中断原任务并触发不必要的设备授权。仅当 CLI 明确返回未登录或缺少本域 scope 时，一次性执行：

```bash
lark-cli auth login --domain apps
```

因缺权限失败（`error.subtype == "missing_scope"`）时的通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，同样按 `--domain apps` 授权；授权成功后只恢复原业务操作，不扩展任务范围。

## 意图路由

按具体操作查命令（开发路径先用下方「选择开发路径」判定表定好再进来取命令）：

| 用户意图 | 先用 | 按需读取 |
|---|---|---|
| 创建**新**应用资产、拿 app_id | `+create` | [`lark-apps-create.md`](references/lark-apps-create.md) |
| 找已有 app_id、按名字过滤应用 | `+list --keyword <name>` | [`lark-apps-list.md`](references/lark-apps-list.md) |
| 查单个应用详情（类型、名称、发布状态等） | `+get --app-id <app_id>` | [`lark-apps-get.md`](references/lark-apps-get.md) |
| 改应用名或描述 | `+update` | [`lark-apps-update.md`](references/lark-apps-update.md) |
| HTML 应用 / 创意模式 — 写 HTML 页面/网站、静态页、PPT/deck、落地页、仪表盘、UI mockup、原型、线框图、视觉探索 | 加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） | [`creative-design/creative-design.md`](creative-design/creative-design.md) |
| 旧版存量 HTML 应用（无 Git 管理）继续上传已有静态产物 | `+html-publish`（仅兼容旧链路；新建 html / 创意模式 / creative-design 产物不得使用） | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
| 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git）。**执行前必读** [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md)，含端到端流程和领域规则 | [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
| 本地开发时 `.env.local` 损坏/丢失，重新拉取启动期环境变量 | `+env-pull` | [`lark-apps-env-pull.md`](references/lark-apps-env-pull.md) |
| 管理应用环境变量（查看/设置/删除） | `+env-list`, `+env-set`, `+env-delete` | [`lark-apps-env.md`](references/lark-apps-env.md) |
| 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`, `+log-get`, `+trace-list`, `+trace-get`, `+metric-list`, `+analytics-list` | [`lark-apps-observability.md`](references/lark-apps-observability.md) |
| 看表 / 看结构 / 初始化多环境 / 导入导出数据 / 变更追溯 / 行级审计 / dev→online 发布 / 时间点恢复 / 查 DB 用量 | `+db-table-list`、`+db-table-get`、`+db-env-create`、`+db-data-export`/`+db-data-import`、`+db-changelog-list`、`+db-audit-status`/`+db-audit-enable`/`+db-audit-disable`/`+db-audit-list`、`+db-env-diff`/`+db-env-migrate`、`+db-recovery-diff`/`+db-recovery-apply`、`+db-quota-get` | [`lark-apps-db.md`](references/lark-apps-db.md) |
| 逐条执行 SQL（SELECT / DML / DDL）；建表 / 改表 / 写 SQL 的平台规范 | `+db-execute` | [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)（含「平台 SQL 规范」：审计列 / RLS / `user_profile` / 禁用 SQL / PG 陷阱） |
| 管理应用文件存储：上传/下载本地文件、列出/查看/删除已存文件、生成临时分享链接、查存储用量 | `+file-upload`/`+file-download`/`+file-list`/`+file-get`/`+file-sign`/`+file-delete`/`+file-quota-get` | [`lark-apps-file.md`](references/lark-apps-file.md) |
| 调试应用运行时缓存：查看/删除单个业务 key、清空指定环境缓存 | `+cache-get`/`+cache-delete`/`+cache-clear` | [`lark-apps-cache.md`](references/lark-apps-cache.md) |
| **部署/上线应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | 本地开发链路先按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 确认本次改动已 git commit + git push，再用 `+release-create` / `+release-get`；查历史用 `+release-list` | [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md), [`lark-apps-release-create.md`](references/lark-apps-release-create.md), [`lark-apps-release-get.md`](references/lark-apps-release-get.md), [`lark-apps-release-list.md`](references/lark-apps-release-list.md) |
| 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference |
| 管理应用协作者（列出/添加/改权限/移除）或协作权限设置 | `+member-list`, `+member-add`, `+member-update`, `+member-remove`, `+member-settings-get`, `+member-settings-set` | 本文「应用协作者与协作权限设置」 |
| 创意模式（html）应用的评论相关操作 | 创意模式应用评论走 lark-drive 文档评论体系，读取 [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) 了解评论能力 | [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) |
| 管理 `app_...` 应用内角色、角色成员，或查询用户匹配角色 | `+role-list/get/create/update/delete`, `+role-member-list/add/remove`, `+role-match-list` | [`lark-apps-role.md`](references/lark-apps-role.md) |
| 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |
| 管理妙搭应用开放 API Key（创建/查看/启停/重置/删除凭证；密钥仅 create/reset 一次性返回） | `+openapi-key-list/get/create/update/enable/disable/delete/reset` | [`lark-apps-openapi-key.md`](references/lark-apps-openapi-key.md) |
| 管理妙搭应用自动化触发器（定时/记录变更/Webhook/飞书审批四类触发器的查询/创建/更新/启停；Webhook URL·Token 一次性回显、不落盘） | `+automation-list/get/create/update/enable/disable` | [`lark-apps-automation.md`](references/lark-apps-automation.md) |
| 查看某次会话某一轮（turn）的回复消息（含仍在生成中的本轮）/ 导出上一轮模型回复（"这一轮回复了什么""上一轮的回复""导出某轮消息"） | 先 `+session-get`（取 `latest_turn.turn_id`）-> `+session-messages-list --turn-id <id>`（仅 user 身份；分页用 `--page-token`） | [`lark-apps-session-messages-list.md`](references/lark-apps-session-messages-list.md) |
| 外部能力(AI模型能力和飞书平台能力)集成/插件/Plugin/Capability | `+plugin-install`, `+plugin-list`, `+plugin-uninstall` | [`lark-apps-plugin-install.md`](references/lark-apps-plugin-install.md), [`lark-apps-plugin-uninstall.md`](references/lark-apps-plugin-uninstall.md), [`lark-apps-plugin-list.md`](references/lark-apps-plugin-list.md) |
| 把一批 ID 在妙搭 user_id ↔ 飞书 open_id / union_id / 飞书 user_id 之间互转（例如拿到 open_id 但下游要 user_id） | `+user-id-convert --convert-type <方向> --ids <id1,id2,...>` | [`lark-apps-user-id-convert.md`](references/lark-apps-user-id-convert.md) |

## 高频路径

- **Base 到应用数据库同步**：用户说“Base 同步到数据库 / 整库同步 / 多张表同步 / 批量任务重新启用 / operation-not-allowed”时，先读 [`lark-apps-db.md`](references/lark-apps-db.md) 的 Base 数据同步段落，再查 app_id 或处理授权。先形成计划再动手：`+db-sync-create` 一次只处理一张 Base 表，整库/多表必须拆成多份单表配置和多次 preview/create；batch/import 任务是一次性任务，不能重新 enable，遇 operation-not-allowed 先解释生命周期边界，再用 `+db-sync-get` 查状态/结果，持续同步要新建 streaming 任务。
- **性能/监控/观测指标**：用户问“接口请求量、错误量、错误率、接口慢、延迟、CPU、内存、最近一小时/七天趋势”时，不要去当前工作区搜索监控文件，也不要询问“监控数据在哪”。先按「app_id 获取」解析应用：`lark-cli apps +list --keyword "<应用名>" --as user`；拿到 `app_id` 后读 [`lark-apps-observability.md`](references/lark-apps-observability.md)，用 `+metric-list`。
- **请求量 + 错误量 + 延迟**：请求量/错误量用 `lark-cli apps +metric-list --app-id <app_id> --metric requests --since <range> --as user`（不传 `--series` 会同时返回 total/error）；延迟用 `--metric latency`（不传 `--series` 会返回 p50/p99）。如果用户给了具体接口，再加 `--api <path-or-name>`；不要臆造 group-by 参数。
- **PV/UV/访问量/活跃用户**：先解析 `app_id`，再用 `+analytics-list`，不要误用 `+metric-list`。
- **设置环境变量**：如果用户只给应用名，仍先 `+list --keyword` 解析 app_id；设置 online 环境且用户已经明确说“确认/直接执行”时，调用 `+env-set --environment online ... --yes`，不要再次要求确认。回复和日志摘要里只提 key / env / app，不回显真实 value；需要传复杂值时优先用 `@file` 或 stdin。
- **删除环境变量**：`+env-delete` 是破坏性操作。除非用户在同一轮已经明确确认删除这个 app/env/key，否则先向用户确认应用、环境、key 和删除后果；确认后再加 `--yes`。不要因为认证失败/重登完成就自动继续删除，必须保留确认门槛。

## 应用协作者与协作权限设置

这组命令管理妙搭应用的开发协作者和协作策略，不等同于 `+access-scope-*` 的运行时访问范围，也不等同于 `+role-*` 的应用内业务角色。所有命令使用 `app_...` 应用 ID 和 `--as user`。不要读取或判断 `app_type` 来预判支持范围，直接调用对应的协作者命令。

- `+member-list`、`+member-settings-get` 是只读命令，需要 `spark:app:read`。
- `+member-add`、`+member-update`、`+member-remove`、`+member-settings-set` 是高风险写命令，需要 `spark:app:write`。先用 `--dry-run` 核对目标、URL 和请求体；dry-run 不需要 `--yes`。用户已确认具体应用、成员/设置及影响，或已按下方「高影响动作：确认与预授权」对整条流程明确预授权时，真实执行加 `--yes`；否则在 dry-run 后停下请求确认。批量移除成员仍执行「禁止预授权判定底线」，不能从泛化的“直接做”推导出 `--yes`。
- 添加、更新、移除成员时必须显式提供匹配的外部 ID 类型，禁止传内部数字 ID、猜测类型或做隐式转换：用户 `--member-type openid --member-id ou_...`；群组 `--member-type openchat --member-id oc_...`；部门 `--member-type opendepartmentid --member-id od-...`。
- `+member-list --member-type` 的筛选枚举是响应对象类型 `user` / `department` / `chat`，与写命令的 ID 类型枚举不同。可再用 `--role view|edit|full_access` 筛选。
- `+member-list` 一次返回应用的全部直接协作者，不提供分页参数；可用 `--member-type` 和 `--role` 缩小结果范围。
- 成员响应不包含应用详情。需要名称、类型或发布状态时单独调用 `+get --app-id <app_id>`，不要期待成员分页重复返回 `app`。
- 收到 subtype `feature_not_available`（OpenAPI code `3340005`；直连服务可能为 `40005`）时，立即停止 CLI 自动化，不切换 `app_type`，也不尝试用 access scope、应用角色或其它成员命令绕过。向用户说明该应用暂不支持通过 lark-cli 设置协作者，并引导其在妙搭后台的权限设置中操作。
- `external_invite` 只在 `+member-settings-get` 的响应中读取，不能独立设置；它会跟随 `external_access`。CLI 不注册 `--external-invite`，需要改变外部协作能力时只设置 `--external-access`。
- `copy_download_by` 也只在 `+member-settings-get` 的响应中读取。CCM 当前明确不支持为妙搭对象写入复制、打印和下载权限，因此 CLI 不注册 `--copy-download-by`。保留读取结果，不要尝试写入，也不要改用其它权限字段模拟。

```bash
# 读取协作者和当前协作策略
lark-cli apps +member-list --app-id <app_id> --as user
lark-cli apps +member-settings-get --app-id <app_id> --as user

# 写操作先预览精确的 typed-ID 字段；确认后把 --dry-run 换成 --yes
lark-cli apps +member-add --app-id <app_id> --member-type openid --member-id ou_xxx --perm view --dry-run --as user
lark-cli apps +member-update --app-id <app_id> --member-type openchat --member-id oc_xxx --perm edit --dry-run --as user
lark-cli apps +member-remove --app-id <app_id> --member-type opendepartmentid --member-id od-xxx --dry-run --as user
lark-cli apps +member-settings-set --app-id <app_id> --external-access disabled --comment-by viewer --dry-run --as user
```

## 选择开发路径（进意图路由前先判这步）

新建必先定 **app_type** 和**开发方式**两件正交的事；修改已有先按「app_id 获取」指认到 app，指认不到就问用户，不擅自 `+create`。开发方式（本地 vs 云端）只看用户对"谁来写代码"的偏好，与应用复杂度、要不要数据库无关。

**app_type 三类边界**（先判"要不要把数据存到服务端"，再判"纯展示还是有交互"）：

| 信号 | 判定 |
|---|---|
| 含数据库 / 后端持久化：登录 / 增删改查 / 报名·投票·站会存记录 / 多人协作 / 泛称"系统·工具"且明确要存数据 | `app_type=full_stack` |
| 纯静态展示（给人"看"的物料，无 JS 交互）：PPT/deck / demo / 落地页 / 海报 / UI mockup / 线框图 / 静态仪表盘 / 视觉探索 | `app_type=html`，加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） |
| 有 JS 交互但无数据库（给人"用"的前端应用）：可交互原型 / SPA / 表单校验 / 动态计算 / 调用外部 API / 泛称"工具·系统"但未明确要存数据 | `app_type=frontend`（**默认倾向**：用户未明确提出数据库需求时默认引导 frontend，不默认 full_stack） |
| 类型模糊（尤其"要不要存数据"不清） | **追问**，话术偏向 frontend，例："看起来是个前端应用，需要保存数据吗？"；确认要存数据再转 full_stack，确认纯展示再转 html |
| 用户要自己写 / 本地 IDE·code agent / 拉源码到本地 / 交研发 | 本地开发，读 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) |
| 让妙搭 AI 云端生成 / 对话式 / 自己不碰代码 | 云端会话，读 [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |
| 未表达"谁来写"偏好 | **必须先问**（本地代码开发 vs 云端 AI 生成）；选定前不擅自选边、不暗示默认，不得以"需求不模糊"为由跳过提问直接 `+init` / `git clone` / `+session-create` / 首轮 `+chat` |
| 修改已有 + 当前目录是 `.spark/meta.json` 项目 | 直接继续本地按意图路由，不必问也不必判云端 |
| 修改已有 + 有云端偏好 | 云端会话；未表达偏好且非本地项目 → 默认本地；判不准先问 |

**类型升级**：`frontend` 应用后续需要数据库/后端能力时，本地 CLI 不提供类型升级；引导用户到云端会话（打开 `https://miaoda.feishu.cn/app/{app_id}`），用自然语言描述后端需求（如"给这个应用加登录和数据存储"）即可触发升级，无需特殊指令。

## 发布态护栏

- **发布意图判定**：用户要"可访问 / 线上 / 分享 / 新链接 / 上线" = 发布意图，先走发布链路、确认完成再给链接。
- 完成 ≠ 发布：云端会话完成 / `+list is_published=true` 都不代表最新内容已部署。
- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`（full_stack / frontend 应用）：进应用编辑/开发态、管理与继续开发应用的入口，也是 frontend 升级为 full_stack 的入口（云端会话）。创意模式（html）应用开发态和发布态是同一个链接，无需额外提供开发态链接。
- 发布态链接来源：`+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`（html / frontend / full_stack 统一走 `+release-get`）。
- html 应用的主链路是创意模式开发方式：按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 初始化仓库、在仓库内产出 HTML 及关联文件，并通过 git commit / git push / `+release-create` / `+release-get` 发布部署。任何 git 操作（clone / pull / push）报错时，先执行 `lark-cli apps +git-credential-init --app-id <app_id> --as user` 刷新本地 Git 凭证，再重试原 git 命令。如果刷新凭证也失败，**停止并向用户报告**：原始 git 错误、凭证刷新失败原因，以及是否可能是当前环境（操作系统、沙箱）限制导致（如 macOS Keychain 在沙箱中不可用、Linux 加密文件目录不可写等）。不要改走 `+html-publish`，也不要把 `+html-publish` 当作本地开发链路的 fallback。
- 创意模式（html）应用的链接格式为 `https://{租户域名}/page/{meta_token}`，**开发态和发布态是同一个链接**（区别于 full_stack 应用两者分开）。此链接形似飞书文档链接。`+get --app-id <meta_token>` 可获取应用信息（含 `app_id`），`+get --app-id <app_id>` 可获取 `meta_token`。看到 `/page/xxx` 链接时，它是妙搭创意模式应用，不要当成飞书文档跳过。

## 平台资源与应用源码边界

- `apps` 命令的 `--path`、`--file`、`--output` 等路径参数只接受当前工作目录（cwd）下的相对路径，传绝对路径会报错。如果目标文件不在 cwd 下，先 `cd` 到目标目录再执行命令。
- 图片、字体、音视频等资源型文件属于平台资源，不应提交到 git 仓库、引用本地路径或以 base64 内联到源码中。先通过 `lark-cli apps +file-upload --app-id <app_id> --file <local_path>` 上传到应用文件存储，拿到返回的远端 URL 后在代码中引用。上传返回的链接按 app 隔离，不同应用必须各自重新上传，不能跨应用复用同一链接。详情读 [`lark-apps-file.md`](references/lark-apps-file.md)。
- `apps +role-*` 只管理平台角色资源；修改已初始化应用的源码（包括当前目录已经是应用项目）时，先查看工作区 `.agents/skills/`，完整读取与任务匹配的领域 skill，再按其路由读取所需 reference。角色鉴权或运行态角色管理读应用内 `authz-guide`，不能用本 skill 的平台命令参考推断运行时合同。
- `lark-cli` 只用于开发过程中的平台资源核验或变更。应用运行时代码必须使用工程内领域 skill 规定的 SDK，禁止通过 `exec` 或子进程调用 `lark-cli`。
- 平台回读出的当前资源 ID、名称和成员只用于事实核验，不自动构成业务策略；除非需求或应用内领域 skill 明确定义，禁止把当前样本硬编码成 allowlist、denylist、只读集合或权限规则。
- 实现领域 SDK 时，以实际包导出的类型和应用内领域 reference 记录的入参、响应路径为准；禁止修改 ambient `.d.ts`、补造宽松类型或强制断言，让猜测的 SDK 结构仅在本地"编译通过"。
- typecheck/build 成功不等于合同正确。交付前逐项核对每个 SDK 调用的入参、响应取值路径和策略分支；涉及更新、删除等不同动作时，分别验证各自动作所需的完整状态，不能复用更弱的前置判断。
- 源码任务交付前确认新增页面、Controller、Module 已接入真实 router/bootstrap，并运行项目现有 typecheck/build；只创建未接线文件不算完成。
- `+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限；应用协作者/开发权限使用 `+member-*` 和 `+member-settings-*`，应用内业务角色使用 `+role-*`。自动化触发器请用 `+automation-*`（见「意图路由」）。

## app_id 获取

`app_id` 必须是妙搭应用 ID（`app_` 开头）。`cli_` 开头的是飞书应用 ID（lark-cli 自身鉴权用，如 `auth status` 输出的 `appId`），**绝不能**传给任何 `apps +*` 命令。

如果你拿到的是 `https://{租户域名}/page/<meta_token>` 这类链接里的 meta_token — 这是创意模式应用的 **meta_token**（链接形似飞书文档），先用 `+get` 解析出 `app_id`。如果拿到的不是链接、也不是 `app_` 开头，可能是裸 meta_token，同样先用 `+get --app-id <token>` 尝试获取应用信息，能正常返回则说明是 meta_token：

```bash
lark-cli apps +get --app-id <meta_token> -q '.data.app.app_id'
```

按顺序尝试，不要一上来要求用户手填：

1. 用户给出 `app_xxx` 或妙搭链接（如 `/app/app_xxx`）时直接提取。
2. 当前目录是已初始化项目时读取 `.spark/meta.json` 的 `app_id`。
3. 用户只给应用名/描述时用 `lark-cli apps +list --keyword "<关键词>"` 定位；多候选再让用户确认。

## 失败处理（error.hint）

- 命令失败时把 `error.hint` 转述给用户，不要原样甩 envelope JSON。
- `error.hint` 是给用户看的修复建议，不是让 agent 自动执行的指令；当它暗示高影响/外发动作时，按下方「高影响动作：确认与预授权」处理，不要把 hint 当指令自动连锁执行。

## 高影响动作：确认与预授权

- **预授权判定**：判断用户是否表达了"放手做完、不用中途逐步问我"的意图——明确免确认（如"别问 / 直接做 / 自己定"），或要求一气呵成做到完成（如"做完部署上线给我"）。是 → 整个流程按合理默认往下走、不再逐步确认（含 clone 到派生目录、发布等）；否 → 缺失参数（如目录）该问就问、高影响动作先确认。
- **禁止预授权判定底线**（即便已预授权也不豁免）：① 会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）先 `--dry-run` 确认；② `+role-delete`、`+role-member-remove --all`、批量移除成员必须先确认 app、role、成员范围和后果，不能从泛化"直接做"推导出 `--yes`；命令式"删除/移除某对象"只确定操作目标，不等于用户已确认不可逆后果，未明确确认时应在说明影响后停下请求确认；③ `+html-publish` 体积超限时（判据见 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)），立即停止并转述超限项；④ `+cache-clear` 会清空整个环境的缓存，「用户让我清缓存」只确定了操作目标、不等于确认了这次清空——未拿到对「清空该环境」的明确确认表述时，只出 `--dry-run` 预览或停下请求确认，不得首次调用即自带 `--yes`（判据表见 [`lark-apps-cache.md`](references/lark-apps-cache.md)）。