设计

来源与状态

状态：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 放在一个文件中，用注释明确业务边界：

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 边界、组合/复用原则和公开交互合同不变。

7.7 KiB Raw Blame History Unescape Escape

设计