docs: update roadmap and migrate gallery docs

- update realtime-preview roadmap with 2026-05-21 status updates
- move and restructure tweakcn design docs into gallery subfolder
- migrate gallery standard docs into gallery subfolder
- add gallery roadmap documentation
- delete old standalone docs files for gallery and tweakcn design

Author: Sayhi-bzb

docs/spec/gallery.md docs/spec/gallery/gallery.mddocs/spec/gallery.md renamed to docs/spec/gallery/gallery.md

@@ -0,0 +1,212 @@
+# Gallery Roadmap
+
+本文记录这轮 `gallery` 规范化重构与治理清理的开发节奏，以及当前实现已经落到哪一阶段。  
+它不重复 `gallery` 的顶层产品定义；产品定义以 `docs/spec/gallery/gallery.md` 为准，runtime 层统一约束以 `docs/spec/runtime/index.md` 为准。
+
+本路线图解决的是同一件事：
+
+- 把 `gallery` 收敛为 runtime 内的受管 mode，而不是独立前端工程
+- 把 gallery 的实现从大体量 feature 单体，持续收敛为 orchestrator + modules
+- 把 gallery 的样式、组件来源和 layout/token 使用方式，持续收敛到 runtime 统一治理标准
+
+## 本轮固定约束
+
+- `gallery` 是 `runtime` 的一个 mode，不是独立的前端脚手架或第二套 runtime shell
+- `gallery` 继续服务于 artifact profile 的选择、编辑、保存与预览，不扩展成语义 authoring 入口
+- runtime 的目标标准保持为：
+  - 一套顶层 CSS
+  - 默认直接消费 shadcn 基线组件
+  - 页面与布局统一消费 token
+- `runtime-host/components/ui/*` 只允许保留显式 managed override，不再承载 baseline 镜像副本
+- `gallery` 的大文件应持续收敛为 orchestrator，具体 tab / scene / shared 实现下沉到子模块
+
+## 当前实现快照（2026-05-21）
+
+- `packages/ahtml/src/cli/runtime-host/app.tsx` 仍是统一 runtime 入口，根据 `mode` 在 `GalleryApp` 与 `DocumentApp` 之间切换
+- `gallery` 当前已经形成明确的 feature 子目录：
+  - `controls/`
+  - `preview/`
+  - `shared/`
+  - `styles/`
+- `preview.tsx` 已收敛为 orchestrator，具体 preview scene 已下沉到 `preview/*`
+- `controls.tsx` 已收敛为 orchestrator，具体 control tab 已下沉到 `controls/*`
+- 原先单体 `shared.tsx` 已移除，改为 `shared/index.tsx` 作为 export surface，具体实现下沉到 `shared/*`
+- runtime managed UI 已切成两层来源：
+  - shadcn 基线组件来源：`scripts/verify-pack/shadcn-test-fixtures/components/ui/*`
+  - runtime override 来源：`packages/ahtml/src/cli/runtime-host/components/ui/*`
+- 当前 runtime 只保留一个显式 managed override：`slider.tsx`
+- `host-styles.tsx` 已接管大量 gallery shell、toolbar、panel 与部分 grid / spacing token
+- `gallery/styles.ts` 及 `styles/*` 仍保留 preview scene 级样式装配，不再是单一巨型字符串文件
+- `gallery/app.tsx` 仍然过重，仍混合 state、derived selectors、mutation actions、fullscreen effect、inspector effect 与最终 render shell，是当前最大的未收口点
+
+## Phase 1: Runtime Surface Governance
+
+### Phase 1 目标
+
+- 收口 runtime UI 基线来源和 override 策略
+
+### Phase 1 关键改动
+
+- 将 runtime UI baseline 改为来自受管的 shadcn fixtures
+- 将 runtime UI override 收口为显式注册表，而不是目录即 override
+- 让 runtime-host 源码侧默认回落到 shared shadcn 基线，而不是优先消费本地镜像副本
+
+### Phase 1 不做什么
+
+- 不把 gallery 变成独立 shadcn project
+- 不把视觉偏好当作 override 理由
+- 不恢复 runtime-host 内的 baseline 组件镜像副本
+
+### Phase 1 完成标准
+
+- baseline 与 override 来源明确分离
+- 每个 override 都有显式登记与理由
+- runtime-host 默认消费 shared shadcn 基线组件
+
+### Phase 1 当前状态
+
+- 状态：已完成
+- 已落地实现：
+  - `runtime-managed-ui.mjs` 已改为显式 managed override 注册表
+  - shadcn baseline 已切到 `scripts/verify-pack/shadcn-test-fixtures/components/ui/*`
+  - `runtime-host/components/ui/*` 当前只保留 `slider.tsx`
+  - runtime-host type-check 已默认回落到 shadcn fixture 基线
+
+## Phase 2: Gallery Module Decomposition
+
+### Phase 2 目标
+
+- 把 gallery 的 preview、controls、shared 从单体文件拆成受控模块
+
+### Phase 2 关键改动
+
+- `preview.tsx` 只保留 preview shell、mode bar 与 scene orchestration
+- `controls.tsx` 只保留 control shell、tab routing 与 state handoff
+- `shared/index.tsx` 只保留 shared export surface
+- consumer 改为依赖具体 `shared/*` 模块，而不是继续消费 shared monolith
+
+### Phase 2 不做什么
+
+- 不把 gallery 的所有状态与行为继续堆回 orchestrator 文件
+- 不恢复 `shared.tsx` 这种大一统 shared monolith
+- 不在 orchestrator 文件里重新内联大块 tab / scene JSX 实现
+
+### Phase 2 完成标准
+
+- preview、controls、shared 都有清晰的模块边界
+- orchestrator 文件不再内嵌大段 tab / scene / shared 实现
+- 治理测试能够阻止 monolith import 与结构回退
+
+### Phase 2 当前状态
+
+- 状态：已完成
+- 已落地实现：
+  - `preview.tsx -> preview/*`
+  - `controls.tsx -> controls/*`
+  - `shared.tsx -> shared/index.tsx + shared/*`
+  - `governance-sync.test.ts` 已覆盖 orchestrator 约束与 shared import 约束
+
+## Phase 3: Host Style And Token Centralization
+
+### Phase 3 目标
+
+- 把 gallery 的页面壳层、toolbar、panel、micro spacing 持续上收至 shared host token 与 shared shell
+
+### Phase 3 关键改动
+
+- 将 header、mobile tabs、sidebar、divider、preview toolbar、stage toolbar 等 shell selector 上收至 `host-styles.tsx`
+- 将高频 micro spacing、surface padding 与部分 column policy 提升为 shared runtime token
+- 将 feature CSS 收敛到 scene-specific 样式，而不是继续扩张页面壳层体系
+
+### Phase 3 不做什么
+
+- 不让 feature 继续维持并列的 page shell 标准
+- 不把已上收的 spacing / padding / grid policy 退回为字面量
+- 不把无法复用的 feature 样式伪装成 shared shell
+
+### Phase 3 完成标准
+
+- page shell 与 editor shell 主要由 `host-styles.tsx` 持有
+- feature CSS 只保留 preview scene 或确实无法上收的例外样式
+- 治理测试能够阻止 micro spacing 与 surface padding 回退成字面量
+
+### Phase 3 当前状态
+
+- 状态：进行中
+- 已落地部分：
+  - `host-styles.tsx` 已接管大量 gallery shell selector 与 frame ownership
+  - 多组 micro spacing 与 surface padding 已提升为 shared token
+  - 部分 grid column policy 已由治理测试锁定
+- 尚未收口部分：
+  - `gallery/styles.ts` 与 `styles/*` 仍保有较多 feature-local layout 常量
+  - gallery workbench 还没有完全达到单一顶层 CSS + token-first 的状态
+
+## Phase 4: GalleryApp State And Effect Decomposition
+
+### Phase 4 目标
+
+- 把 `gallery/app.tsx` 收敛成真正的 orchestrator，而不是继续承载完整工作台状态机
+
+### Phase 4 关键改动
+
+- 将 initial editor state factory、filtered preset/token selectors、active profile summary 等纯状态逻辑下沉到 state/selectors 模块
+- 将 draft update、token update、preset select/create/save/delete/reset、clipboard copy、focus/open-tab helpers 下沉到 actions 模块
+- 将 fullscreen state sync 与 toggle handler 下沉到独立 effect/hook 模块
+- 将 inspector hover / pin / esc / scroll 行为与 inspector state 组装下沉到独立 effect/hook 模块
+- `app.tsx` 最终只保留：
+  - refs
+  - state wiring
+  - hook composition
+  - final JSX shell
+
+### Phase 4 不做什么
+
+- 不再向 `app.tsx` 回填新的大块 `useCallback` 与 `useEffect`
+- 不把 inspector 与 fullscreen 行为继续和 render shell 紧耦合
+- 不用“文件仍然可运行”替代 orchestrator 收口
+
+### Phase 4 完成标准
+
+- `app.tsx` 不再混合大段 state、actions 与 effect 实现
+- gallery 的核心行为有独立模块边界，可被治理测试约束
+- `GalleryApp` 的职责收敛到 runtime shell 组装与 feature 组合
+
+### Phase 4 当前状态
+
+- 状态：未完成
+- 当前阻塞点：
+  - `gallery/app.tsx` 仍同时承担 state、selectors、actions、fullscreen、inspector 与最终 render shell
+  - 当前结构虽可工作，但还不满足“app.tsx = orchestrator”这一治理目标
+
+## 总体验收
+
+当下面五件事同时成立时，这轮 gallery 规范化主线才算完成：
+
+- gallery 已稳定收敛为 runtime 内的受管 mode
+- runtime UI 已默认消费 shadcn 基线，override 仅保留必要例外
+- gallery 的 preview、controls、shared 已具备受控模块边界
+- gallery 的页面壳层与 layout/token 已主要收敛到 shared host standard
+- `gallery/app.tsx` 已从 feature 单体收敛为 orchestrator
+
+## 当前验收判断（2026-05-21）
+
+- 已满足：
+  - gallery 已稳定作为 runtime mode 挂在统一入口之下
+  - runtime UI baseline / override 治理已显式化
+  - preview、controls、shared 三块模块拆分已完成
+- 基本满足但仍需继续收口：
+  - host style / token centralization 已有明显进展，但 gallery workbench 仍未完全收敛
+- 尚未满足：
+  - `gallery/app.tsx` 仍未完成 orchestrator 化
+
+## 当前验证快照（2026-05-21）
+
+当前状态至少已由下面这些验证覆盖：
+
+- `npx vitest run packages/ahtml/src/cli/governance-sync.test.ts packages/ahtml/src/cli/gallery-alignment.test.ts packages/ahtml/src/cli/runtime-surface.test.ts packages/ahtml/src/cli/runtime-bootstrap.test.ts`
+- `npm run build`
+
+## 备注
+
+- 本文只记录 gallery 规范化主线的阶段推进，不重复 `gallery.md` 的产品信息架构与交互定义
+- 若后续 gallery 的治理目标改变，应先更新本路线图，再更新实现与治理测试

docs/spec/gallery/roadmap.md

@@ -1,6 +1,6 @@
 # Realtime Preview Roadmap
 
-本文只记录这轮 `realtime preview` 重构主线的开发节奏。  
+本文记录这轮 `realtime preview` 重构主线的开发节奏，以及当前实现已经落到哪一阶段。  
 它不重复顶层架构背景；顶层边界以 `blueprint/*` 和 `docs/spec/runtime/index.md` 为准。
 
 本路线图解决的是同一件事：
@@ -17,6 +17,24 @@
 - 本轮不设计 agent 回流动作协议
 - 本轮不扩展成通用前端交互系统
 
+## 当前实现快照（2026-05-21）
+
+- `preview` 已不再走 `buildArtifact(...) -> serveDirectory(...)`；CLI 主路径已切到 `runRuntimePreviewSession(...)`。
+- `build` 仍保留导出职责，但其前置准备已拆成共享的 `prepareDocumentRuntime(...)`，供 preview 与 build 共同消费。
+- preview session 现为长驻 runtime：
+  - 启动 managed runtime
+  - 写入当前 document / runtime state
+  - 监听 `.agent.html` 文件变化
+  - 在文档变化后刷新 runtime state
+  - 在文档非法时保持 preview 进程存活并展示 diagnostics
+- runtime host 已支持 `mode: "document" | "gallery" | "diagnostics"`，document preview 以 runtime state 中的 document 为主输入。
+- 当前 live update 依赖 managed runtime 下的 generated runtime files 与 Vite dev reload，不是单独设计的一套浏览器端 preview-state 订阅协议。
+- 仍未完全收口的部分主要在 Phase 4：
+  - `README.md`
+  - `docs-web/content/docs/index.mdx`
+  - `.agents/skills/ahtml/references/*`
+  这些位置仍残留旧的 static-preview 口径。
+
 ## Phase 1: Preview Path Decoupling
 
 ### Phase 1 目标
@@ -43,6 +61,14 @@
 - `build` 与 `preview` 的职责边界在 CLI 和 workflow 中明确分开
 - preview 主路径已经能消费统一的 prepared document 结果
 
+### Phase 1 当前状态
+
+- 状态：已完成
+- 已落地实现：
+  - `packages/ahtml/src/cli/artifact-workflow.mjs` 已将 document prepare / validate / renderability 路径与 artifact materialize 路径拆开。
+  - `packages/ahtml/src/cli/index.mjs` 的 `previewCommand` 已改为直接调用 `runRuntimePreviewSession(...)`。
+  - `buildArtifact(...)` 现在消费 `prepareDocumentRuntime(...)` 的结果，再进入导出物化流程。
+
 ## Phase 2: Runtime State Driven Preview
 
 ### Phase 2 目标
@@ -67,6 +93,16 @@
 - runtime host 的 preview 输入不再依赖构建期静态 import
 - document mode 与 build mode 继续共用同一 renderer path
 
+### Phase 2 当前状态
+
+- 状态：主目标已完成
+- 已落地实现：
+  - `packages/ahtml/src/cli/runtime-host/app.tsx` 已支持读取 `runtimeState.document`，并支持 `diagnostics` mode。
+  - `packages/ahtml/src/cli/runtime-preview.mjs` 会在每次刷新时写入 document、artifact profile、diagnostics 与 inputPath。
+  - build 与 preview 仍共用同一条 runtime host / renderer path，没有重新分叉第二套 renderer。
+- 当前保留：
+  - `document.generated.json` 仍在 runtime host 中保留为 fallback / 共享输入的一部分，但 preview 主输入已切到 runtime state。
+
 ## Phase 3: Live Update Loop
 
 ### Phase 3 目标
@@ -91,6 +127,17 @@
 - 文档非法时 preview 进程保持存活，并向页面展示 diagnostics
 - 文档修复后，preview 可自动恢复正常渲染
 
+### Phase 3 当前状态
+
+- 状态：当前主线已落地
+- 已落地实现：
+  - `packages/ahtml/src/cli/runtime-preview.mjs` 已建立文件监听、去抖刷新与长驻 preview server。
+  - 非法文档时 preview 不再退出，而是进入 diagnostics mode。
+  - 文档修复后，preview 会自动恢复到 document mode。
+- 当前实现方式：
+  - 浏览器更新依赖 runtime generated files 的变化与 Vite dev server 的重载能力。
+  - 这满足当前 realtime preview 主线，但并未额外设计一套独立的浏览器端状态订阅协议。
+
 ## Phase 4: Build As Export
 
 ### Phase 4 目标
@@ -117,6 +164,19 @@
 - preview-first 口径在 CLI、runtime、tests 和 docs 中一致
 - static artifact 成为明确的交付形态，而不是默认工作形态
 
+### Phase 4 当前状态
+
+- 状态：进行中
+- 已落地部分：
+  - CLI runtime 与测试主路径已经切到 preview-first。
+  - `packages/ahtml/src/cli/command-contract.mjs` 已把 `preview` 描述为 realtime preview session。
+  - `build` 在实现层面已收口为 export / materialize。
+- 尚未收口部分：
+  - `README.md` 仍是旧口径。
+  - `docs-web/content/docs/index.mdx` 仍写着 “Preview serves the same static output produced by build.”
+  - 用户侧 skill 文档中的 build / preview 描述仍需改成 preview-first。
+  - `preview --out` 目前仍保留兼容参数；它已不再参与 preview 物化输出，但口径还需在文档中完全统一。
+
 ## 总体验收
 
 当下面五件事同时成立时，这轮主线才算完成：
@@ -127,6 +187,27 @@
 - preview 与 build 仍共用同一条语义到渲染链路
 - build 已收口为交付、分享和归档能力
 
+## 当前验收判断（2026-05-21）
+
+- 已满足：
+  - preview 不再依赖完整 static artifact 目录生成
+  - runtime host 已由运行时 state 驱动 preview
+  - preview 与 build 仍共用同一条语义到渲染链路
+- 基本满足但仍需口径收口：
+  - preview 已在实现层面成为默认工作模式，但 README / docs-web / skill docs 还未完全同步
+  - build 已在实现层面收口为交付能力，但用户侧文档口径还未完全改完
+
+## 当前验证快照（2026-05-21）
+
+当前状态至少已由下面这些验证覆盖：
+
+- `npm run build`
+- `npx vitest run packages/ahtml/src/cli/command-contract.test.ts`
+- `npx vitest run packages/ahtml/src/cli/cli-surface.test.ts`
+- `npx vitest run packages/ahtml/src/cli/runtime-bootstrap.test.ts`
+- `npx vitest run packages/ahtml/src/cli/runtime-surface.test.ts`
+- `npm run test:run:cli-heavy:preview`
+
 ## 备注
 
 - 零散修复、临时阻塞和子任务拆分不放在本文；后续应放到对应 `todo` 文档