# 设计

## 来源与状态

- 状态：active
- 更新日期：2026-08-23
- 主产品面：通用 `etaf-playground.el` 工作区，以及
  `examples/research-shelf.etaf` / `.el` / `.ecss` consumer 三件套
- HTML 视觉基线：`design/research-shelf.html`
- 已审查：ETAF View/Component/Data API、`etaf-ui` 的公开组件，以及
  `etaf-sqlite` 的 typed source 合同。

## 产品定位

Research Shelf 是一个真正有用的本地研究/阅读架：SQLite 保存书籍、论文、
文章和笔记，用户可以筛选、分页、选择一条记录、更新进度、完成、收藏和归档。
它不是把 API 名称堆成控制台，而是用一个连贯 workflow 验证 ETAF 的组合能力。
Playground 默认安装确定性的 256 条 fixture、每页 12 条，用于真实验证分页、DataGrid
增量更新和 SQLite 查询压力；fixture 数量和 page size 都可以配置。

## 结构与分层

- Shell：标题/副标题/主题切换 → 三列 workspace → 持久化状态栏。
- 三列 workspace：筛选栏 / SQLite reading list / selected-item detail inspector。
- `.etaf`：只保存经过 inert 校验的静态结构和文案（section、filter、label）。
- `.ecss`：可选的 inert `(styles ...)` 规则，由 companion 消费并应用到 ETAF
  Component style scope。
- 同名 `.el`：消费 `.etaf/.ecss`，组合公开 UI Components，创建 SQLite schema、Data
  Controller、refs、事件处理和生命周期清理。
- 现有可复用组件：`button`、`checkbox`、`label`、`panel`、`data-grid`、
  `pagination`；应用只负责把它们组合成产品，不复制一套 UI kit。

## Playground 框架边界（必须长期遵守）

`etaf-playground.el` 是通用的 source/preview 工作区，不是业务应用模块。它从同名
`.etaf`/`.el` 文件发现应用，并把可选的 `.ecss` 作为第三个 source tab；左侧是
源码会话，右侧是 ETAF 预览。

框架只负责：

- 惰性、inert 的 `.etaf`/`.ecss` 读取和 companion 注册覆盖；
- `.etaf`、`.el`、`.ecss` source buffer 的 tab 切换；
- 左右窗口布局、刷新、reset、close，以及 ETAF Runtime 生命周期。

框架绝不负责：业务 Component、数据库包或表结构、palette、业务 state、
handlers、resources 或应用 refs。它不能 `require etaf-sqlite`，也不能把业务
组件实现塞进 loader/helper。未来新增例子时，只增加一个同名 `.etaf`/`.el` pair，
必要时再加 `.ecss`，不改变框架语义。

组合和复用是默认设计：优先复用 ETAF/`etaf-ui` 的公开契约，优先拆出清晰的
Component 边界，避免新增 helper 层或抽象泄漏。

## Research Shelf 的 companion 边界

Research Shelf 目前足够小，完整的可执行 companion 放在一个文件中，用注释明确
业务边界：

```text
examples/research-shelf.etaf                inert 结构 source
examples/research-shelf.ecss                inert 样式 source
examples/research-shelf.el                  DATA / THEME / STATE / VIEW / ROOT
```

`.el` 文件是唯一的 Playground 注册点和 palette owner；它的 THEME 区域可以
通过可选的 `etaf-theme-tp` adapter 把 TP 的亮/暗 pair 转成 ETAF 语义 Theme plist，
其余应用代码不直接调用 TP，也不嵌入 renderer palette 名称。VIEW 区域在 shell
Component 内创建
Data Controller，因此 ETAF 会自动把它的 effect Scope 归 Component 所有，并在
Component 销毁时释放 SQLite source。详情和筛选 Component 通过 Context 消费依赖、
dispatch 命名 Action，不直接访问 SQLite，也不重复实现 selection 匹配。`.etaf`
负责静态结构，`.ecss` 负责 token。未来如果产品复杂度真的增长，再把这些注释区段
迁移到目录模块，而不改变 Playground 的同名三文件入口。

实现约束补充：有意热加载统一通过 `etaf-component-redefine-run`，应用代码不绑定
ETAF 私有 registry 变量；Component setup 中创建的 Controller 自动归当前 Scope
所有，选中项使用带明确 `:item-key` 的 `etaf-data-selected-item`。

## 视觉语言

- 气质：editorial、专注、温暖、安静而聪明；避免通用 admin dashboard、KPI
  墙、假图表、彩虹渐变和装饰性噪声。
- 色彩：ink `#172033`、paper `#F7F3EA`、cobalt `#3657D6`、mint `#3E9B8F`、
  coral `#D86B5D`、amber `#C58A3A`、muted `#6D7482`。
- 节奏：1 格外部节奏、2 格 panel padding、1 格 workspace gap，控件保持
  intrinsic 宽度；需要分配剩余空间或换行时统一使用 `flex`。
- 状态：文字和 Unicode 同时表达状态：`⌕`、`★`、`✓`、`◷`、`↗`、`⚠`、`·`。
- 动效：状态立即可见，不依赖 timer animation，默认支持 reduced motion。

## 交互合同

- 筛选：All、In progress、Unread、Finished、Starred。
- 列表：DataGrid 行单选，重复点击可以重新选择；分页按钮在边界处 disabled。
- 每页行数：激活 `Rows N ✎` 后使用 Emacs 原生 minibuffer 输入 1–100 的整数，
  应用后回到第一页。
- 详情：`+ 10%`、`✓ Finish`、`☆/★ Star`、`Archive`；完成或 100% 时正确禁用。
- 存储：成功显示 `✓ Saved locally`，失败保留当前可用内容并提供 Reload。
- 主题：Light/Dark 由 checkbox 控制；文字、对比度和布局都应保持可读。
- 键盘：Tab 顺序为筛选 → 行 → 详情动作 → 分页，RET 使用同一组公开 refs。

## 响应式与验证

- Wide/fullscreen：rail / list / detail 位于同一条 Flex line，呈现三栏。
- Medium：rail 与 list 保持同排，detail 自动换到下一行。
- Narrow：同一组三个 Component 按文档顺序自动变为纵向流。
- Shell 只使用一套带 basis/grow 权重的 wrapping Flex，不读取窗口宽度、不维护
  breakpoint 状态；`row` 只负责紧凑 intrinsic 控件，所有操作控件仍保持独立
  hover/focus 语义。
- 用 inert reader、source tab/session、未保存 source refresh 和 SQLite 临时文件
  测试 mount/remount、筛选、分页、重复选行、mutation、错误状态和 cleanup；GUI
  用干净 fullscreen 截图验证真实布局。
- 目标：一次 Data mutation 对应一次 Runtime generation/publication。Research Shelf
  的批处理延迟 lane 在固定 1413×62 几何下执行 5 次未计时 warmup 与 30 个计时 sample，
  每个场景的 p95 和 max 均须不超过 50ms；当前 GUI 验收还有下述独立要求。
  已接受的 105ms p50 是历史设计上下文，
  不是当前 evaluator gate；其正式处置仍由 M0b1 的 `DOC-PERF-001` 负责。
- 压测入口：`etaf-research-shelf-fixture-size` 默认 256，
  `etaf-research-shelf-page-size` 默认 12；已有本地记录保留，不足部分使用新 ID
  补齐 fixture。

## 性能 evidence lanes

批处理延迟 lane、追踪 lane 与 GUI lane 共享同一组仓库、环境、场景、fixture 和 build identity，
但保持为三种独立测量。批处理延迟 lane 负责 Research Shelf 1413×62 fixture 中
无 instrumentation 的 5/30、p95/max 50ms 回归检查。Batch verifier duration
不是 GUI first paint。追踪 lane 负责一次代表性 instrumented invocation 的 cost class、
work counters、turns、allocation 与 GC；GUI lane 负责真实 Emacs action sequence
与已审查的画面证据。当前 GUI 验收还要求三组独立的前台实测，每项操作从回调开始
到强制 redisplay 返回的 p95 和 max 均不超过 50ms；该门禁尚未通过。使用
`../etaf/scripts/README.md` 中的测量入口，保留预热、GC 记录和全部样本。
redisplay 返回不能证明操作系统已经呈现画面。任何一条 lane 都不能替另一条 lane 宣称通过。

## 待 review

- [ ] 用户可调整产品命名或 palette；pair 边界、组合/复用原则和公开交互合同不变。