# 兰台前端 · 设计规格书（v1 · 落地前置）

> 本文是 `holo-paper.html` 原型锁定的设计决策，供 `src-ui` 工程落地对照。
> **「已锁定」是契约，落地时不许回退；未列出的像素细节（字号/间距/图标形状/hover 态）可在真环境再磨。**

---

## 0. 一句话定位

**兰台＝汉代皇家档案典籍库。** 产品不再是「聊天窗」，而是**一部正在被编纂的案卷**——人在纸边批注、AI 居中撰文、机器贴底注记。核心是把「等权消息流」换成「注疏层级」。

---

## 1. 版式范式（已锁定）

**注疏横排**。文字全程横排（代码、英文、URL 不折行），但骨架是古籍注疏的层级，不是聊天气泡：

- **正文**（答 / 策）居中，是案卷的「经文」，正文位、大一号（17px 起，行距 2.0）；
- **来文**（问）是人的批注，手迹位 + 朱砂深 16px/1.9（B4 环1 定稿），左侧 2px 红批线；
- **夹注**（思）缩进列边（约 86% 宽），石墨铅笔，小一号，虚线勾边；
- **脚注**（器）贴底小字，上方一道 44px 石青注线引出；
- **抄录**（码）栏内图版（3px 硬左线 + 上下规线 + 米黄底）；
- **卷首**：**版心天头**（**2026-09-16 用户拍板 B 案重排**）——玉徽（亭台图标 `#icon-lantai` 26px）· 机读眉行（卷次「案卷 Nº 12」）· 题字（36px）· 机读档行（**立卷日「二〇二六年八月廿二日」· N 块**）四行**同轴居中于版心**（2026-10-08 起版心 = 流区宽一半「墨占纸半」，默认 1440 纸下仍 720——原封顶 720 随拉宽流区退役），底部硬规线 + 左缘朱砂短横（**2026-09-02 改档只挂活跃卷**——整屏至多一处红（浸墨③），红在哪卷即活卷；对原型 `.folio-head` 的主动偏离——原型先于真纸材质批与一纸多卷定案）；规线与版口钮同样只画版心宽。卷号在卷首**恰出现一次**（有名卷在眉行、无名卷在题字 fallback，眉行退为「兰台 · 案卷」文类行）；**卷名真源 = 卷快照 `label`（空 = 未命名）**——「有名/无名」判据、首条来文派生、显示兜底「案卷 N」（一律取**档号**）的单一真源 = `src-ui/src/state/volume-name.ts`（2026-09-18 命名收口：起卷不写数字名，日志头行不再带卷名）；立卷日真源 = 卷日志头行 `createdAt`，旧卷无此字段 = 档行只显块数（不编造）。**重排前的病灶**（实测）：玉徽居中于整张纸（默认 1440 宽流区的中轴）、眉行/题字/档行却左齐于纸缘内距 16px，而正文块居中于 720 版心——题字比正文左缘还左 344px。原型的「钤印居中于天头」手势保留，改居中于版心；
- **界栏**：正文列左右各 1px 栏线（`--rule-strong`），页边注在左栏外（**2026-09-02 翻案**：08-30 把界栏落成「流区四边版框双线框」的读法判死——纸缘交还材料、改物理包边（见 §10 纸层次·流区真纸）；版框＝「印在纸上的墨」，流区这张「叶」不印框——WebGL 探针 `prototype/webgl-paper.html` 判读定案）；
- **划词**（2026-09-02 视觉迭代）：流区选区＝手写朱笔下划线（`src/paper/sel-ink.ts` 纯函数——主笔朱砂实线 1.7px＋淡墨 echo 第二笔，种子取选区文本 hash、同选区恒同线；跨块选区也画线）；原生 ::selection 洗底在流区退役（输入面照旧）——纸不动、只落墨，被人手划过的字落朱线；
- **选区政策**（**2026-09-17 全局化，用户报「太多不该触发文字选中的地方」触发**）：**全应用默认不可选，正文自证可选**。`foundation.css` 在 `html` 上落 `user-select: none`——**界面是界面，不是可复制的文档**；放开面只有两处：① **输入面**（`input / textarea / select / [contenteditable]` 一条，Chromium 下祖先 none 会连坐表单件的拖选）；② **正文容器自持** `user-select: text`（纸壳 `.pp-block` 即范式，块内结构件/交互件再各自撤回 none）。**判定**：新增产品面若确有可复制正文照 ② 自行放开，界面件一律不写。**旧账的病灶**：此前没人管这件事，谁出事谁补一条（坞拖动期 / 纸条 / 小地图 / 书脊行 / 插件窗题条各写一次）——补一处漏一处，拖动扫选、双击选词、Ctrl+A 把整壳收进选区在其余面上照旧发生；而纸上挂着 document 级 `selectionchange`（选中浮钮 + 划词朱线），任何一次扫选都可能唤醒画布上的划词动作；
- **划词的第二道守卫**（2026-09-17）：`user-select: none` 只挡「从该面起选」，挡不住「按住家具再扫进纸面」——浏览器把选区锚点**夹到最近的可选内容**（块内文字），于是家具起手的拖拽在锚点上与真划词无法区分，浮钮照弹（同族实测见 paper-minimap 的 `preventDefault` 注：拖小地图会选中画布文字）。故两个选区消费面（浮钮 / 划词朱线）共用**起手面判据**：按下那一刻记下是否落在 `.pp-block` 内，本次按住期间的选区按起手面算；块内输入件（准奏卡意见框）另由 `isEditableSurface` 挡（在自己输入框里选一段不该弹抽纸条浮钮）。**代价（明账）**：纯键盘造出的选区沿用「上一次按下的面」——先在块里点过即照常认，冷启动直接 Ctrl+A 不认（全选不是划词）；
- **印章**：朱砂「蘭臺」二字竖排印，作品牌签名。

---

## 2. 字体系统（2026-09-10 三体换代拍板重锁；2026-09-24 机读位复原）

| 角色 | 值层 | 装载 | 备注 |
|---|---|---|---|
| 正文位 `--f-song`（原宋体） | MiSans | `src/app/fonts.css` @font-face（`src/assets/fonts/MiSans-VF.ttf`，VF 单文件 100-900 全字重） | 原宋体/衬线正文 |
| 手迹位 `--f-kai`（原楷书） | MiSans | 同上 | 只用于「人的」来文——文类语义保留，手写感随三体退役 |
| 机读位 `--f-mono`（原等宽） | Noto Sans Mono CJK SC（OFL 1.1，随包自托管） | 同上 @font-face（`src/assets/fonts/NotoSansMonoCJKsc-Regular.otf`，只带 Regular——粗体走合成） | 代码/命令输出/引文——**中文也等宽**（2026-09-24 复原：09-10 的「非等宽对齐」代价翻案） |

字体栈（CSS 直抄，文类语义键保留）：

```css
--f-song: "MiSans", "PingFang SC", "Microsoft YaHei", sans-serif;
--f-kai:  "MiSans", "PingFang SC", "Microsoft YaHei", sans-serif;
--f-mono: "Noto Sans Mono CJK SC", "MiSans", "PingFang SC", "Microsoft YaHei", monospace;
```

**装载**：`src/app/fonts.ts` 只 `import './fonts.css'`（本地 @font-face，打包进应用不依赖系统安装）；fontsource 四包（eb-garamond / ma-shan-zheng / ibm-plex-mono / noto-serif-sc）已卸载。

> 关键纪律：**斜体走合成伪斜**（MiSans 无 italic 字形，`font-style: italic` 由渲染器合成——拍板接受）；canvas 侧字面量栈（type-tokens `FONT_STACKS`、InkLayer `LABEL_FONT_STACK`）与 tokens.css 同步改——`--f-mono` 与 `FONT_STACKS.mono` **逐字同值**由 `tests/paper-visual-decisions.test.ts` 守卫。
>
> **`pre > code` 纪律**（2026-09-24 补）：UA 样式表对 `<code>` 有直接规则 `font-family: monospace`，**直接规则压继承**——`<pre class="…">` 上声明的 `var(--f-mono)` 到不了真正画字的 `<code>`。故 `foundation.css` 收一条全局口径 **`pre code { font: inherit }`**；新增任何「pre 里套 code」的机器文本面照此写，别在父层声明了事。

---

## 3. 墨色系统（已锁定 · 矿物颜料）

| token | 值 | 语义 | 用在哪 |
|---|---|---|---|
| `--ink-1` | `#26221C` | 松烟墨（正文） | 答 / 策 / 码正文 |
| `--ink-2` | `#55503F` | 次级墨 | 规线 / 次级文字 |
| `--ink-3` | `#8A8172` | 三级墨 | 注记 / 页码 |
| `--ink-4` | `#B5AC9A` | 弱规线 | 分隔 |
| `--seal` | `#A63A2E` | 朱砂（人的批改） | 印章 / 来文 / 圈点 / 朱批 |
| `--seal-deep` | `#8C2F26` | 朱砂深 | 来文文字 |
| `--indigo` | `#3A5B7A` | 石青（机器/仪表） | 脚注 / 拟策策面（左线·淡底·文类签）/ diff 新增 |
| `--graphite` | `#6F6E68` | 石墨（铅笔灰） | 夹注 / 擦改 / diff 删除 |
| `--paper` | `#F6F1E7` | 纸面 | 画布 / 页面底 |
| `--paper-deep` | `#EFE8DA` | 深纸 | 输入条 / 图版底 |
| `--paper-margin` | `#EDE5D5` | 页边 | 舞台底色 |

语义状态（保留原 `--pass/--warn/--fail` 语义，降饱和到矿物色）：`--pass #5E7A55`、`--warn #B0782E`、`--fail #A9443F`。

**一条铁律：朱砂 = 人，石青 = 机，石墨 = 夹注，墨 = 正文。** 不许换义。
> 2026-09-16 口径订正：原写「石墨 = 草稿」与值层不符——`--graphite (#6F6E68)` 实挂夹注 / 擦改 / diff 删除。
> **「草稿」语义由虚线（`--rule-dashed`）表达，不占颜色位。**
唯一豁免（2026-08-23 B5 环2 用户拍板）：**抄录（diff）加删色走红绿墨色化**——add=松绿（`--pass`），del=朱砂深+删除线。del 的朱砂深不表「人的声音」，读作擦改/勘误红笔；加删红绿对是代码块的视觉直觉，纯红纯绿不入纸面，必须落在矿物色族。

---

## 4. 块类型映射（已锁定）

现有 `paper/block-model.ts` 的 `BlockKind` 无需改动，只改渲染层视觉：

| BlockKind | 文类签 | 字体 | 墨色 | 视觉 |
|---|---|---|---|---|
| `user` | 来文 | `--f-kai` | `--seal-deep` | 左 2px 红批线 + 圈点关键词；16px / 行距 1.9（B4 环1 拍板：字号收到正文 17 之下，朱砂深保持——问仍是唯一彩色声音）；附图缩略行（2026-09-09 multimodal-image B4）：64px 方界 tile 规线细框 + wrap 居中多行 + 点击放大浮层，几何 token `--pp-ch-userImages-*`（measure 镜像 `userImagesRowHeight` wrap 行数整除推得）；未命中预览/读失败降级 mono 占位盒 |
| `markdown` | 正文 | `--f-song` | `--ink-1` | 17px / 行距 2.0，居中主角 |
| `reasoning` | 夹注 | `--f-song`（英文走 Garamond） | `--graphite` | 86% 宽、虚线勾边、擦改痕迹 |
| `diff` | 抄录 | `--f-mono` | `--ink-1` | 3px 硬左线 + 米黄底图版，add 松绿（--pass）/ del 朱砂深+删除线（B5 环2 红绿墨色化定稿——铁律在 diff 语境豁免：删行读作擦改非人语）；**顶层 markdown 围栏一律落本类**（2026-09-23）：语言标记留在 `.pp-lang` 语言签，块体按语言分流——真差分（diff/patch）走 +/- 着色，其余语言与裸围栏走 hljs 代码体（几何同源，测高不因分流漂） |
| `tool` | 脚注 | `--f-mono` | `--indigo` | 44px 注线 + 11–11.5px 小字；卡内载荷 = 语义投影（见 §4.1a），不再是协议 JSON |
| `plan` | 拟策 | `--f-song` | `--ink-1` | 石青策面（2026-09-10 拟策卡渲染专项，用户拍板）：顶硬线 + 底软线保留 + 3px 石青硬左线 + 石青淡底（indigo 4% 兑纸面）+ 横向内距 16——与来文的朱砂左线对仗（人声朱 / 机策青）；内容走完整 markdown 体（`.pp-pc-body` + `.pp-md` 族共享，正文位 17px/2.0），行号机制（01/02/… 石青序号）退役；方案区 + 钤印三钮不变 |
| `notice` | 贴黄 | `--f-song` 小字 | `--warn` | 系统通知（建议作「贴黄」纸条） |

> `notice`（系统通知）原型未覆盖，建议按「贴黄」（古代奏章上贴的黄纸条）处理：小字、土黄底、一条弱规线，与正文明确区分。

### 4.1 正文（markdown）子元素版式与折叠机制（2026-08-30 补记）

正文块（`markdown`）不再是纯文本平铺——子元素按注疏版式降级渲染；结构模型 = `paper/markdown.ts` 单一解析（渲染与测量共用，块高镜像 `measure.ts` 的 `MD_*` 常量，CSS 镜像 `.pp-md-*`，改版式三处同步）：

| 子元素 | 版式 |
|---|---|
| 段落 | 17px/2.0，段间 14px（旧 10px 段距小于行距、段落黏连，专项提到 14） |
| 标题 h1–h4 | 20/18/16.5/15.5px 正文位加粗，padding 承担上下距（首元素 margin 逃逸会破坏测高，禁 margin-top） |
| 列表 | 标记列等宽小字绝对定位（ul `·` / ol `n.`），条目缩进 26、嵌套再缩进 22 |
| 引用 | 石墨左线 + 缩进 + ink-2 |
| 图码 | 石青左线 + 深纸底（**列表/引用内**嵌套围栏 + mermaid 回落的兜底面——顶层围栏 2026-09-23 起升格为独立抄录块，见上表 `diff` 行） |
| 正文图（2026-09-09 远端 B4；2026-10 本地路径扩展 + 点击放大） | 独立行 `![alt](…)` 固定盒 160px（`--pp-md-imgBoxH`，chem 先例同族——加载/失败态都不改版面，measure 静态镜像即精确）；图源分类过在解析层（`imageSrcRef` 单一真源）：http/https 远端由浏览器直载；**本地绝对路径（盘符/UNC/POSIX 与 `file://` URI 归一）仅图片扩展名（`VIEWER_IMAGE_EXTS`）放行**，渲染期经 `fs_cap read_base64`（用户路径，8MiB 上限）回读成 data URI（块只携路径）；非白名单（data:/相对路径/非图扩展名）降级 alt 文本，空 alt 整行不产块——data: 巨串不灌纸面；周框 `--rule-soft` + 深纸底；失败换 mono 弱墨行（远端=alt 文本、本地=「图片不可读：文件名」带原因 title——盒界常在，错误不静默）；**点击看大图**：盒内图为按钮（`.pp-md-img-zoom` 无装饰重置 + 光标 zoom-in + title/aria 提示）→ 用户气泡/资产卡同款全局浮层（`.pp-media-preview-overlay`，Esc/遮罩点关） |
| 表格 | 等宽 11.5px + 弱规线（`.pp-grid-table` 同族） |
| 行内 | 加粗 600 / 斜体 / 删除线石墨 / 行内码等宽小号 chip / 链接石青下划线 |

**块体白空格纪律**：`.pp-body` 恒 `white-space: pre-wrap`——measure.ts 的 canvas 测量一律按 pre-wrap 计行，渲染端折叠换行会产生「测得多、渲染少」的幻影块间距（2026-08-30 间距根因之一，已修）。

**折叠机制**（`paper/fold.ts`；规则态 + 用户覆盖态）：夹注（reasoning）恒折叠——流内只留一行预览；脚注（tool）/程文（code）按状态折叠——`running`/`error` 展开（过程与错误可见），`done`/`pending` 收起（完成即收）；折叠行 = 块顶等宽小字（单工具 `▸ 名字 判别摘要 · 读数` / `▾ 收起`），用户点击写入覆盖态（状态翻转自动收回不打架）。**读数** = 语义投影的 `summary`（`42 行` / `9 处 · 1 文件` / `17 个改动` / `exit 0 · 110s`，见 §4.1a；无 summary 回落「输出 N 字」），名字走领域显示名 `fs(read)`。**判别量**（stream-rhythm 刀4a，2026-09-03）：压缩的是重复不是信息——工具组折叠行露判别字段（`▸ 工具 ×3 · read_file src/a.ts / src/b.ts / src/c.ts`；shell 露命令；截断/同值去重补 ×N 总账；无判别字段回退名字计数），折叠行恒一行（10px mono，测高镜像零变化）；**版面契约（2026-10-29 实机回归）**：`.pp-fold` 必须 `width: 100%`（`<button>` 的 auto 宽度是 fit-content，长文本会把盒子撑出纸面——旧版靠文本短侥幸），另两道在 `displayToolName`（action 只收短标识符）与 `foldLabel`（出口 160 字符上限）。折叠态计高与渲染同步镜像：脚注折叠全收、程文折叠收程序体留输出/错误（执行结果一眼可见）。

### 4.1a 工具卡载荷 = 语义投影（2026-10-29）

脚注（`tool`）卡展开后的**内容**不再是协议面（用户原话：「除了 asset 类，几乎所有工具卡片的内容都不是给人看的，更接近原始的格式化输入输出直接渲染到聊天流」）。真源 = `paper/tool-present.ts` 的 `presentTool(payload)`：按语义名（`agent/tools/domains.ts` 的 `DOMAIN_SPECS` 反查，`resolveSemanticToolName`）把一次调用投影成「人话段」——

- **参数面去协议键**：`$ <command>` 而不是 `{"action":"run","command":…}`；`fs(edit)` 只报「改哪儿 + 行数变化」（不再倾出 oldString/newString 全文）、`fs(write)` 只报「写哪儿 + 多少行/字符」、`git(status)` 一类纯协议动作**不展示**参数段。
- **结果面按域读成事**：检索 = ripgrep 形态（`13: 命中行` 实墨 / `12· 上下文行` 注记墨 + `N 处 · M 文件` 头）、目录 = 缩进树（`adr/ 2 项`）、`git(status)` = `main · 领先 2 · 17 个改动` + porcelain 行（` M` / `M ` / `??`）、差分 = 拆掉字面围栏 + 增/删/块头三档着色（`.pp-add/.pp-del/.pp-hunk`）。
- **三面同源**：渲染（`ToolBody`）/ 测高与墨迹（`measure.ts` 两处）/ 折叠行读数（`foldLabel`）消费**同一个** `sections` 数组与 `text`；投影不改测量模型（仍按文本行计高，`cappedH` + 字体档不变）。
- **已覆盖的语义名**（表在 `tool-present.ts` 的 `PRESENTERS`）：shell 族 / fs 族（read·write·edit·list·glob）/ search / git 族（status·log·diff·commit）/ web（fetch·search）/ 任务板 `/ browser（目标页）。未登记者走兜底。
- **纪律**：模型面零改动（只读 payload 串，不碰工具返回值）；形状不认识 ⇒ 该段回落通用结构化打印（原文照旧读得到，远端 MCP / 插件动态名面零风险）；presenter 未消费的参数键收成「其余：k=v」一行（不静默丢）。

守护：`tests/paper-tool-present.test.ts`（真机载荷 → 用户可见文本）；渲染/测高同源见 `tests/paper-tool-payload.test.tsx`、墨迹见 `tests/paper-ink.test.ts`。

### 4.1b 程文卡 = 程序语义（`code`，P2-A；2026-10-30 P5 结构化完成值）

程序执行卡（`code`）与脚注卡的分离点：**卡片是程序语义（体 / 出），不是调用语义（参 / 果）**。三段式——
程序体（等宽，石青左线 + 深纸底，320 封顶）→ 日志 / 完成值 / 错误（信封 `── logs ──` / `── result ──` / `── code run failed (kind) ──`
由 `paper/tool-text.ts` 的 `codeSections` 解析成真段，段头走 `.pp-sec-head` 同一套）；折叠态收程序体、
留输出/错误（执行结果一眼可见）。

**结构化完成值（P5）**：程序 `return {__view:'table', columns?, rows, caption?}` / `{__view:'diff', diff}`
时，**完成值段换体**——表格渲成真 `<table>`（与正文表格同族视觉：等宽 11.5 + 弱规线，列宽均分由
`table-layout: fixed` 钉死）、差分渲成三档墨文本（`.pp-add/.pp-del/.pp-hunk` 与抄录块同判据）。
纪律：① 视图从**完成值段文本**投影（`paper/code-view.ts`），**模型面一字不动**（工具返回值照旧 JSON）；
② 上限 200 行 / 12 列 / 单元格 200 字符，超出**出注记行**（不静默丢）；③ 解析不了 ⇒ 照旧渲染 JSON 文本；
④ 折叠行读数换成「表格 4×3」/「差分 +3 −2」；⑤ 测高与正文表格同一把尺子（`tableRowH`）+ RO 实测收口
（`needsObservedHeight(…, hasView)`——无视图的程文照旧不挂）。

守护：`tests/paper-code-view.test.tsx`（解析/归一/上限/渲染/测高/墨迹/折叠读数）+ `tests/paper-code-output.test.tsx`（信封分段）。

**文类签（页边注）**：来文 / 正文 / 夹注 / 脚注 / 抄录 / 拟策（贴黄），配机读码 `USER / AGENT / THINK / TOOL / CODE / PLAN`。

### 4.2 会话流节奏（2026-09-03 stream-rhythm 立法 · D1 试值待真机终审）

会话流不是等距块栈：事件按语义关系组成**工作单元**（tool / toolgroup / code / subagent 连续运行 + 挂靠夹注；error 块起「恢复单元」），单元内紧、单元间松、阶段完成换气。规则真源 = `paper/group.ts`（单元封套）+ `paper/canvas-math.ts`（间距档 ANCHOR 表），钉值 `tests/paper-stream-rhythm.test.ts`。

| 档 | 值 | 语义 |
|---|---|---|
| 单元内 intra | 32 | 行为链紧密纵向连接（同一工作单元相邻块） |
| 块距（基线） | 48 | 无节奏信息的外部调用面兜底（B1 不动） |
| 单元间 unit | 64 | 同回合内工作单元切换 |
| 转折 recovery | 96 | Error 起的恢复单元 / 墓碑前置放空——打破正常节奏 |
| 阶段 stage | 96 + 弱线 | 来文开新阶段：留白 + 细线（`--rule-soft`，落间距中线） |

叠加律：上方是来文恒尾距 8（B1 反转：asterism 让位优先于节奏档）；B1 来文间距反转与阶段档共存。

两宪法（单元封套 pass 的结构保证）：**封口纪律**——已封口单元不可变（id 锚首成员、成员只增不减），活尾（streaming 消息）才许重排；**跨消息前瞻禁止**——挂靠（夹注吸入下一工作单元）只在同消息内发生，单元不跨消息（消息边界即收口）。阶段标题不自动生成（自动起名会撒谎）——plan 标题 / commit message 等显式信号由后续批次继承。

**刀3 布局保证（2026-09-03 补记）**：封口前缀 = **刚体**——追加事件只许整体平移，封口块的节奏档/间距/相对位置逐字段不变（布局级测试钉死，滚动锚定的数学面）；流式重排平滑 = `pp-stream-live` 下 transform 过渡 200ms（旧块被轻轻推开，绝不瞬移、绝不挂 left/top/height）。**组原子性**：折叠组 = 布局栈单条目（子卡摘除——虚拟化窗口对组只能整取整舍），展开组成员在栈内连续（窗口切不出交错序）；长流（千块级）全链回放有性能烟测预算。**目次带阶段导航（刀4）**：阶段锚消费工作单元（`buildStageAnchors`，阶段 = user 单元，与阶段间距/细线同真源），hover 兜底带阶段序（`阶段 N · 首句`）。

**Error 墨色家族（刀4c 确认，现状合规零改动）**：错误状态色 = `--fail`（#a9443f 墨浓红，非纯红非朱砂——B5 红绿墨色化延伸）；错因墓碑（turn-error）= 贴黄款——朱砂淡底只作纸晕（`--seal` 7% 混纸），墨身走 `--ink-2`；工具/程文错误输出与状态签走 `--fail` 单一真源。**朱砂 = 人铁律不挪用**：错误文字永不直用 `--seal`。钉值 `tests/paper-visual-decisions.test.ts`（Error 墨色家族三断言）。

**刀5 族节奏批（2026-09-03 补记——用户真机判「整个会话流还是瀑布」的根治批）**：节奏词汇的判据从块 kind 升级为**节律族**（读/写/验证/落款——`grammar.rhythmFamilyOfBlock`；other 不表态不断节奏，远端/未知名不破语法铁律的节奏层延伸）：**族边界切单元**——已知族切换（读→写、写→验证、验证→落款）即封口旧单元开新工作单元（errorish 转折优先于族界；recovery 同族重试续收、异族切出），WorkUnit 带 family；**折叠组按族切分**——连续工具族变即断组（「读 ×3」「写 ×2」「验 ×1」各自成行，判别量各露各的），unit 64 在族间开火、32 收在族内；**单元界短规线**——work 单元首成员上方 96px 短线（比阶段全宽线弱一档，落 unitGap 64 中线 top -32；叙述不碎、转折自宣告、来文后 B1 反转区无线位）——线语法三级：全宽 = 阶段界 / 短线 = 单元界 / 无线 = 同单元收紧；**验证链毕锚**——verify 工作单元链毕出「✓ 阶段完成」小字（ink-3 mono，链末块下方，不占块高），失败转折（后继 recovery）不发、流式在跑不发——✓ 不说谎；**组头族签**——折叠行前缀族字（`▸ 读 ×3 · read_file a.ts / b.ts / c.ts`，验/落同款，混族回退「工具」）。钉值 `tests/paper-stream-rhythm.test.ts`（族切组/族切单元/other 不表态/recovery 族续/链毕四态/单元线规则）+ `tests/paper-visual-decisions.test.ts`（刀5 四断言）。

**2026-09-06 尸检补记（用户真机报「渲染隐约不对、说不出病灶」）**：线语法两条隐蔽执行修正——①**单元线实现机制**：块级 ::before 与脚注族注线（`.pp-tool/.pp-toolgroup/.pp-code::before` 石青身份标记）同槽同特异性，源序落败被静默顶掉 → 单元线在工具族首块上整体消失；改实元素 `.pp-unit-rule`（壳层条件渲染，钉值不变），线语法三级语义不变；②**栈首无线位**：阶段线/单元线的负偏移对栈首块画进卷首头带（-48 落 head 底规线上方 ~18px 每卷必现错位线）——线标记「上方有界」，栈首之上只有卷首（天然界），`rhythmAssign` 以 `i > 0` 守卫两线发放（节奏档不动）。回归钉值：paper-visual-decisions「槽位独立性」+ paper-stream-rhythm「栈首不发线」。

---

## 5. 术语表（已锁定）

| 旧 | 新 |
|---|---|
| 会话 | 案卷 |
| 新建会话 | 新建案卷 |
| 发送 / 向 Agent 写字 | 拟文 |
| 星图 / 依赖图 | （退役，不再作为用户可见卖点） |
| 工作台 | 兰台 |
| 信号源 | 提供方（2026-08-24 补录：观测站时代旧词退役，对齐 DeepSeek Harness 官方中文定译） |

---

## 6. 交互（2026-09-05 起含手势修订）

无限画布 + 钉住 / 收回 + 小地图 + 抽纸条，已在 `PaperPanel.tsx` 与 `paper/` 内核实现。**2026-09-05 pin-strip-rework 批修订**（`docs/archive/pin-strip-rework-plan.md`）：拖块改**松手定夺**（拖动全程纯预览，带外松手落钉 / 带内取消回槽；眉批撕出保留首动建钉——instant 族例外）+ **拖选跨带成条退役**（拖选只做选择；抽纸条唯二入口 = 按住已有选区拖出 + 选中浮钮）+ **带显形**（拖拽中来源流区提落影 `--shadow-sheet-lift`——400px 窄带从暗判变可见边界，落点悬带内块影转「松手回流」态）+ 纸条销毁两击确认 + 可发现性一次性眉批（localStorage 旗标）。钉住手势本体（按住文类签拖出 = 钉、洞点击 / 悬停带内松手 = 收回）与已修过的手感（抓取偏移按实际渲染位反推、防跳变）不变。

**2026-10-29 抽纸条失灵批**（用户报「莫名其妙的失灵」）：三处确定性病灶一起收——① **命中带**：A 路的 mousedown 判据从「逐碎片矩形 ±4px」改成 `selection.ts::selectionHitBands`（按行合并 + 行间空距填满；横向仍只到该行**已选字节的起止**，在未选中的字上按下仍是起新选区）——浏览器 `getClientRects()` 给的是字面盒（16px/1.75 正文实测行盒 20、行距 8），旧判据在行距中段与行尾空白是死区；② **钉住的公共物**（含孤儿钉）不按流带判：拖出卡片即成条、浮钮落**选区右缘**（旧行为是浮钮照弹、点击时 `!sessionId` 直接 return——「看起来有入口、做了却什么都不发生」）；③ **失联即收**（`paper-shell/lost-focus.ts`）：窗口失焦 / 窗外松手之后 in-flight ref 不再永久挂在途（landmine-map V2 未修的另一半），否则下一次抽纸条会被「有手势在途」的守卫静默吞掉。

**拟策卡终态**（2026-10-29）：批准 / 修改 / 拒绝的决议**写回 `PlanPart.status`**（连同 selectedLabel / feedback，纯 JSON 随卷持久化），卡面终态行按它渲染（「已批准 · 选定方案：X」/「已提交修改意见」/「已拒绝此拟策」）——块被虚拟化卸挂、切卷重开、会话重建后**不再长回「待批准」**。审批窗口已过（tool 侧 `settled`）时回调返回 false，卡面如实说「审批已过期，此决定未生效」，不替 agent 记一个它没收到的决议。

**2026-09-18 出处引导批新增**（`docs/archive/render-paper-line/pin-provenance-plan.md`）：钉住块的**来路**成为一等件——病灶是「洞」这条唯一线索是**视口内**的（流自锚点向上生长 ⇒ 洞越漂越远；渲染窗口化 ⇒ 洞离屏时连 DOM 都没有）。三件：

| 件 | 形态 | 判据 |
|---|---|---|
| **出处行** `.pp-prov` | 页边注（文类签）第三行「摘自 卷名 · 状态字」，**常显** | 不依赖任何视口内目标；卷名权威链 = 活卷名 → 建钉冻结的 `pin.source.label` → 档号兜底；超长卷名纯层截断 10 字 |
| **引线** `.pp-tether` | hover 钉块 → 一丝**手绘朱笔**（**划词朱线同族**：微伏 + 定种子 + 手绘平滑 + **恒定墨宽**）从钉缘引到洞缘；起笔留白 6px、收笔朱点；**洞离屏时线照样出屏** | 一屏一线；选边净空优先（相叠取左缘，不横穿钉身）；层 = **屏幕坐标**（同 `.pp-sel-ink`，墨宽不随缩放变）；z 4（纸与块之上、坞与浮件之下） |
| **溯源** | 点出处行 → 飞到源洞（落洞中线）+ 洞点名一拍（1.6s 自散） | 四态：活钉 / 不在卷内 / 未摊开（点 = expand 摊开并定位）/ **已删（不可点）** |

墨阶：出处行 `--ink-3`（常显注记档）；引线与洞点名 `--seal`（朱砂 = 人；hover 瞬时态不占「每屏至多一处红」常驻名额，与文类签 hover 同族）。引线的笔墨语法见 `paper/sel-ink.ts` 判例（**手感来自微伏不来自粗细变化**——`PaperPanel.css` `.pp-tether` 头注与 plan §1.1 记了这次转录与三处弃案）。

**2026-09-19 便条批（用户拍板「甲+丙」）**：钉住块与纸条的**纸面语言**整体换装——手势与语义零改动，只有三层：

| 病灶 | 治法 | 落点 |
|---|---|---|
| 墨占 100%（流内 720 墨借 1440 纸的左右各 360 白边，钉到桌面上后那份白边不存在了，只剩 4px 裱边带顶着字） | **纸内白边**（钉块 34/44/38，纸条内距 10/12 → 18/20；墨占 100%→88%、95%→92%） | `CHROME_TOKENS.pin` / `.strip`（真源）→ `--pp-ch-pin-*` / `--pp-ch-strip-*`；钉块几何高的镜像 = `measure.ts` 的钉住态分支（白边 + 报头 + 按收窄测宽） |
| 常驻件全挂在纸外（文类签 + 出处行 `-128px`、竖排「钉住」签 `+36px`、收回钮 `-30px`） | **报头收进纸内**（方墨点 + 文类 + 序号 ……… 出处行，弱规线一行）；竖排「钉住」签**退役**——身份改常显方墨点（钉住是常驻状态，不该靠 hover 才现身）；收回钮留在纸外（hover 瞬时件，不占构图） | `.pp-block.pp-pinned .pp-kind`；`.pp-pin-hint` 与 JSX 一并删除 |
| 材料只有剂量差（钉块 = 流区同纹理 + 同四层配方缩水版，与桌面只差 11 阶色 ⇒ 只能靠影子读；纸条连纹理都没有） | **三分材质 + 贴平**：桌面（有纹）/ 流区（有纹的纸）/ 便条（`--paper-deep` 实色无纹）；纸内件**无投影**（§11 原表列，09-05 批曾越）；「拿起」的影只出现在拖拽携带态（压印族 `--elev-raise`） | `.pp-block.pp-pinned` / `.pp-strip` / `.pp-block.pp-dragging` |
| **2026-09-23 质感批翻案**：上一条治错了病——纹理不是干扰而是**质感来源**；而「贴平」让钉住块既不是排印件也不是物件（三轮台子实测：五案对比度全等 **1.11** ⇒ 物性来自线与结构、与明度无关；去掉桌面纹理后现状仍读不出边界 ⇒ 色差路线天花板只 **1.187**） | **纸片件配方**：sheet 细纹（900px；桌面走 fiber+grain 粗纹 ⇒ **两种纸，不是同一张纸的深浅**）+ 四层物理包边 + `--shadow-sheet` 硬偏移落影 + 单线框；报头规线由弱线档提到 `--ink-3`（有框之后同档会抢读） | `.pp-block.pp-pinned` / `.pp-strip`；判读件 `prototype/pin-texture-ab.html` / `pin-species-ab.html` / `pin-edge-ab.html` |

同批：纸条题签由常显朱砂回落墨阶（`--ink-3` + 方墨点——每多一张纸条就多一处常驻红，与 §10 法则 3 相抵；朱砂留给两击销毁确认态）；纸条补**来源行**（`.pp-strip-src`「摘自 卷名」，取抽取那一刻的 `source.label` **快照**——拷贝语义：源卷改名不追改，与块级钉的活卷名出处行是两套语义；旧存档无此字段则整行不渲染）。判读件 `prototype/pin-strip-ab.html`（真 CSS/真资源 A/B 台）。

**2026-09-20 动作行造型批（用户拍板「丙」，病灶 = 「这些按钮真的太丑了」）**：块 hover 出来的动作行从「四枚 hairline 方框」改隶**注记族**——诊断五条 / 四候选出图出数 / 明说的代价见 `prototype/msg-ops-style-ab.NOTES.md`（台架 `.html` + 走查脚本可复跑），纪律守护在 `tests/paper-msg-ops-hover.test.ts`。

| 病灶 | 治法 | 落点 |
|---|---|---|
| **方框用错了语法**：`border + paper 底` 是全产品**常驻件**的语法（文类签 `.pp-kind` / 眉批钉 `.pp-marginalia-pin`）；hover 瞬时件一律去框纯文字 + hover 朱砂（`.pp-fold` / `.pp-marginalia-toggle` / `.pp-tool-btn`——后者 CSS 里留着「盒→线」的先例注）。四枚方框随 hover 一起长出来 ⇒ 与「一方向至多两层框」的版框层级打架 | **去框素面行**：11px 纯文字 + `·` 分隔（落在 gap 正中）+ hover 一件转朱砂并带一丝朱砂底线；命中盒靠**隐形 padding** 撑到 26×24（旧写法 19px 已顶格，要加高只能把可见的框画大）。行盒自持纸色底 = 隐形遮罩（行越出块底时盖住被越过的字） | `.pp-msg-ops` / `.pp-msg-ops button` / `button + button::before` |
| **来文块的行是孤儿**：题签 / 正文 / 花押全在版心轴上，只有动作行 `left: 0`（实测行中心比块中心偏左 281px） | **来文块的行居中**（`left: 50%` + `translateX(-50%)`）；回复块保持左齐（与左齐正文同轴） | `.pp-block.pp-user .pp-msg-ops` |
| **一个动作两个入口**：行内「立枝」按钮 + 块右端独立「枝」方框——两种字形、两处落位、右端一枚孤框 | **握把并入行尾**成六点握把（`::before` 画的 2×3 点，字形无关、不吃字体回退）；块外落位与 2px 缝桥面两段**删除**（行盒之内没有缝）；键盘路径照旧 = 行内「立枝」按钮 | `.pp-branch-grip`；`.pp-block:not(.pp-user) .pp-branch-grip::before` 与 `.pp-block.pp-user .pp-branch-grip` 整段删 |
| **等级不分 + 节奏不齐**：改写/重发（撤轮，会丢东西）与抄录（无损）视觉全等；单字双字混排（29.2 / 40.4px） | 标签改**文言双字**（改写 / 重发 / 抄录 / 立枝）⇒ 四件等宽 37.3px；置灰降级由 JSX 内联 `style{opacity}` 收归 `:disabled` | `use-block-ops.ts`；`.pp-msg-ops button:disabled` |

代价（明说，不藏）：回复块那条悬空腿 19 → 24px（多出的 5px 是透明 padding，不显形，但命中区会盖住下一块顶部 5px）；握把不再靠「字」表意（语义落 `title`）；11px 小字的可读性押在 `--ink-3` 与纸色的对比上（与 `.pp-fold` 同档，真机偏淡就抬一档到 `--ink-2`）。

---

## 7. 锁 vs 放

**锁（契约，落地不许回退）**：注疏范式、字体栈、墨色语义、块类型映射、术语、钉住手势、界栏/印章/亭台图标。

**放（真环境再磨）**：精确字号与行距、图标形状、hover/focus 态、空态 / 加载 / 流式 / 错误态、擦改痕迹浓淡、界栏粗细、notice「贴黄」的具体样式。

---

## 8. 落地清单（前置工作）

- [ ] `src/app/tokens.css` 换成 `lantai-tokens.css`（`--obs-*` 退役或并行过渡）
- [ ] `src/app/fonts.ts` 换字体（见 §2）
- [ ] `src/app/panels/PaperPanel.css` 按 §4 重排七类块（灰框 → 注疏）
- [ ] 块体渲染器（`composition/renderer-service` 的 `resolveRenderer`）按文类换墨色/字体
- [ ] 新屏：案卷首页（SessionsHome）与设置（SettingsPanel）换兰台皮
- [ ] 亭台图标 `#icon-lantai` 落成 favicon / 应用图标
- [ ] 文案全局替换（§5 术语表）

---

*原型文件：`holo-paper.html`；token 文件：`lantai-tokens.css`。*

---

## 9. 创作坞 v2（2026-08-31 落地）

创作坞（composer dock）从「贴底输入条」升格为「案头」——纸墨身份不动，交互模型对齐书房隐喻。八件定案：

1. **度量纪律**：坞本体锁 880px 版心居中（`.pp-composer max-width`）；超宽屏全宽输入行退役。纸色坞底与顶边规线仍全幅。
2. **两态同位**（2026-09-02 拍板 C）：创作坞恒居中抬起 `var(--composer-rise)`（96px 固定——不再随窗口高度 12vh 浮动，不同窗口大小坞位恒同）。零摊开卷的**案头态**只再管形态：退匣直书（`.pp-composer-slot.pp-at-desk`——形态类刻意不叫 `pp-desk`，避免与世界层桌垫同名撞车）、空态题字上移 36% 让位、坞下方**出流悬挂**签条架（最近三卷「续 · 卷名」签条，手迹位、hover 朱砂，点击 `space.expand` 摊开——架出没不推坞位）。落笔发出首句（开口即开卷）后换装常驻匣（坞顶硬线 + 版口钮），位置不动。**（2026-09-17 浮动化：96px 坐底抬高 = 出厂默认位与吸附锚之一，坞可由用户拖离底带——见 §9.2。）**
3. **附着面**：`引`（工作区文件模糊引用：`list_directory` 递归摊平 + 子序列匹配，basename 加权）→ 夹签入卷；**拖文件入卷**（Tauri `onDragDropEvent` 原生通道——HTML5 drop 在 T2 WebView 永不触发，C10 尸检课的偿还），悬停坞体亮**界栏**（朱砂细线 + 纸色加深 +「松手入卷」批注），松手命中才入卷；`夹`（file picker）保留为兜底。贴图入卷**刻意不做**——agent 无读图链路，贴图路径是空头支票（C10 同款判断）。
4. **渐进披露**：占位符只留一句（`拟文…` / `落笔即另起一卷…`）；键位收进**律**册（设置行右端浮层，13 行键位总览）；历史导航提示改**一次性眉批**（有历史且首聚焦时浮现 6s 自散，localStorage 旗标）；流区拖拽语义以原生 title 就地提示。
5. **墨量线**：坞底 1px 墨线 = 本卷上下文占用占模型窗口比例（2026-09-07 分母接线：per-model 覆盖 ?? 目录声明，`modelContextWindow` 与运行时压缩阈值同链，网关命名空间 id 目录不中时由设置页覆盖兜底），近满（>80%）转朱砂；裸 `[0]` 徽标退役，读数进 hover。窗口未知（0）或零占用不显（不编造）。**2026-09-13 分子换轨**：旧口径把「最后一次请求的 `total_tokens`」当「本卷已用 token」（既含输出、又只是单次请求量，与「上下文占用」不是一回事）；现改读 token-meter 的**投影占用**（提供方 prompt 侧压力 + 采样后载荷增量），无回报时回落载荷估算并在 hover 标注「估算」——同一条线现在报告的就是压缩判定看的那把尺子。
6. **钤印拟文**：发送钮墨色实心方章（`.pp-send`），hover 翻朱砂——人=朱砂语义：发送是用户的动作。
    **钤印单钮三态（2026-09-03）**：两枚印同构（实心 + 硬偏移投影 `--shadow-anchor`），色相即语义——墨印=拟文 / 朱印=停。单一按钮位随状态翻转：
    - 空闲（任意输入）→ **拟文**（墨印）：发送新轮；
    - 运行中 + 输入框空 → **停**（朱印 `.pp-stop`）：中止回合；hover 加深一档，active 压印（`translateY(1px)` + 投影塌缩）；
    - 运行中 + 有输入 → **拟文**（墨印）：点击走 `sendMessage` 既有**插入路径**（`agent.insertMessage`，下轮生效 + toast 回音）——运行中打字 = 插话，停钮让位。
7. **翰**：命令面板入口钮（设置行右端）——斜杠命令不再只靠盲打 `/` 发现；与 `/` 触发词共用同一层面板，打字接管即散。
8. **运行呼吸线**：任一摊开卷在跑 → 画布底缘 2px **石青**细线呼吸（`.pp-stream-live`，机=石青铁律）；与书脊运行点、坞内停止钮、后台卷指示同源（exec 订阅）。

**2026-09-06 收口（行序 + 模型选择器弹层重做）+ 续批（三行制 + 设置行归堆）**：① **三行制**——书眉行（卷名左端 + 翰/律/后台卷指示右端）恒居坞顶，输入行居中，设置行（模型/权限/思考）垫底——三控件落位「下方一行」（DSH InputBar 排布：输入面在上、控件行在下），不占书眉行（续批打回初版「整组一起下沉」的两行制：卷名/翰/律是坞的书眉，不随三控件迁）；**设置行行内归堆（续批二）**——模型独居左端，权限+思考成对靠右（组内权限在左、思考收尾）：两件同属「运行策略」归堆，不与模型混排；直接合并成单控件暂缓（权限=工作区级 mode-store、思考=每会话 compose-store，两真相源硬合会搅浑状态归属）；② **设置行定宽**——模型 pill 容器 150px / 思考档词 min-width 5em（单字档与两字档同宽），开合、换模型、换思考档不再推挤同行件（卷名书眉行内 132px 定宽防换卷跳动）；③ **模型选择器 compact 形态**——触发器恒驻（打开时仍显示当前模型，不再被空搜索框顶替——「模型被清空」错觉根因），搜索进弹层（搜索行钉顶 + `.ms-listbox` 滚动区），document mousedown 外点关闭（画布空白 mousedown preventDefault 是平移手势，拦得掉 blur——react-aria 的 blur 关闭路永不触发，必须显式听），触发器 mousedown preventDefault 防「blur 抢先关 + click 重开」竞态，再点 = toggle，Escape 收起并回焦触发器；compact 下空选择键忽略——外点/Enter 无匹配的 commitCustomValue 半截查询不落库（自定义模型名提交仍属设置页字段形态）。门禁：tsc / biome(0-0) / vitest 全量（新增 `model-selector-popover` + `composer-dock-row-order` + `composer-dock-header` + `composer-dock-settings-pair` 四文件）。

门禁：tsc / biome(0-0) / vitest（创作坞 6 文件 37+16 用例，含新增 `composer-dock-desk.test.tsx`）/ build:builtin-plugins（23 插件自包含）/ vite build / verify:convergence 全绿。

### 9.1 墨量册（2026-09-13 落地）——坞内 token 计量装置

**来由**：坞是「配置 + 输入」的家，用量是落笔前最该看的读数（还能喂多少上下文）。DSH 同判——上下文表放在输入条旁（ContextMeter 环），不另开页。坞底墨量线继续做余光可见的环境指示，墨量册是它的展开面：**点开看账**。

**落位**：设置行最右端一枚「墨 NN%」触发器（`.pp-ink-sel`——读数件不是控件，不进「权限+思考」运行策略对，独立居行尾；与思考 pill 同语言：纯文字 + 小墨点，>80% 墨点与文字转朱砂）；面板向上开（坞贴屏底），并入浮层互斥（思考/翰/律/引/墨五层同屏只开一个）。

**册面（全出自 `src-ui/src/agent/token-meter/`，真源 = Agent 侧每卷账本）**：
- 书眉：卷名 + 来源徽记（`回报` / `估算`）；
- **读数**：占用百分比当**全册唯一题字**（26px/700），右陪小字距标签「上下文已用」，近满（>80%）转朱砂（句读点朱——全册唯一红字）；
- 副行（mono 小字）：`~已用 / 窗口 tok` + `下一请求预计 ~N`；
- **占用条**：总长 = 窗口占比，段宽 = 构成比——三段按**墨阶递减**（系统提示 `--ink-1` / 工具 schema `--ink-2` / 对话 `--ink-3`），纸墨体系只有墨，不引第三色（石青=运行态、朱砂=人的动作，均不占）；条下一行**构成图例**（色点 + 段名 + `~值`，与条同序同色相）；
- **账目**（段题「账目」）：四桶（未缓存输入 / 缓存读 / 缓存写 / 输出）+ 收口行「合计」（字重上提 + 上弱线）+ 缓存命中率；
- **本轮**（段题「本轮」）：请求次数 + 最新一轮用量；
- 页脚一句口径说明：`~ 本地分词估算 · 账目四桶来自服务商回报`。

**排印（同日二版，用户打回一版「不好看，文字排版搞一下」）**：一版是十三行等重小字竖排 = 设置表单面孔。定稿改为**册页四层**：① 一屏只许一处读数当题字（其余全部退到 10–12px）；② **段题复刻首页节题语言**（8px 实心方墨锚点 + 10px/600/字距 0.26em 题字，浸墨⑤ 完工动作）——两段之间用段题分隔，不用裸分隔线；③ **账目 = dt/dd 两列网格 + 数值右对齐**（账本竖排对齐，眼睛读竖列不读横排；`tabular-nums`）；④ 段内行高 24px、收口行 29px——节奏靠字重与线，不靠等距堆叠。踩坑留档：滚动 flex 列（`max-height` + `overflow-y: auto`）的子项必须 `flex: 0 0 auto`——默认 `flex-shrink: 1` 会把占用条挤成 0 高（肉眼只当「线画得细」，数字自查才逮到）。

**口径纪律**（沿 DSH，禁漂移）：① 分桶**互不重叠**且输入三桶加总恒等于提供方 `prompt_tokens`（残差法归一，不信任各家 miss 字段自洽）；② **压力只算 prompt 侧**（不含输出）——「占用」问的是下一次请求的提示词有多大，不是上一次账单有多大；③ **投影占用** = 压力 + 采样后载荷的带符号增量（流式期间水位站住、跨请求才前进；压缩把载荷削小时同步回落，夹零不出负数）；④ 构成是**估算构成**不是账单（本仓用 gpt-tokenizer 计数通道，与压缩预检同一把尺子）；⑤ 缓存命中率**部分命中绝不四舍五入成 100%**（DSH `formatCacheHitPercent` 的诚实舍入照搬）；⑥ 账本随卷落盘（`.lantai/sessions/{id}.json` 的 `tokens` 字段，旧卷无此字段 = 从空开始，不迁移不编造）。

**附图记账（2026-09-22 补）**：图为**对话内容**，其视觉 token 计入对话段（占用条仍是三阶墨、三段几何不变——不新开第四段）；口径 = **提供方发布的像素网格**（`token-meter/image-tokens.ts`，逐字移植 DSH `llm-deepseek`，单图封顶 1024），与文本分词器不是同一把尺子，但两者**加起来**才是 ④ 说的那把「与压缩预检共用的尺子」（`tokenCountWithEstimation` 同一处求和）。诊断行单列 `images: {tokens, count}` 与 `api_delta`（本地估算 − 提供方 `prompt_tokens`）：**差额持续非零 = 该换口径了**（例如换到非 DeepSeek 血统的视觉路由，网格系数不再成立），有图那几轮尤其要看它——这条差额就是「估算不是账单」的可观测面。

**归属铁律不变**：创作坞仍是「视图不是容器」——账本真源在 Agent（`getTokenStats/snapshotTokenLedger/restoreTokenLedger`），坞只读；卷级 `sessionTokens` 降为「总量投影 + 重算触发信号」。

**书眉卷名吃满余量（2026-09-13）**：`.pp-composer-target` 原 `flex: 0 0 132px` 定宽把卷名一律截在十来个字，而行内大半空间空着（右端只有翰/律两枚小钮）——改 `flex: 0 1 auto` + `max-width: 64%`：短名不虚占、长名吃到可读上限，换卷/改名仍不推挤右端（spacer `flex: 1` 吸收余量），超长仍 ellipsis。

### 9.2 创作坞浮动化（2026-09-17 拍板：全画布自由浮动 + 吸附边缘 + 双击复位，锚线跟随重算）

**来由**：坞自 2026-09-01 起就是浮在纸上的绝对定位层（不占布局流），但位置由 CSS 钉死（版心居中 + 坐底抬高 96）——坞压住要看的内容时，用户只能挪内容，不能挪坞。

**定案（同日二批修订见下）**：
- **抓手** = 坞的书眉行（卷名/空白处按住即拖；翰/律/停止钮/输入件自己接手势）；
- **拖动** = 自由到画布任意处（夹在顶部浮件带之下、屏缘之内——浮件带见 §14），全程**磁吸**四枚锚位（左右缘 / 版心中轴 / 经典底带 96 / 最底缘）；
- **双击坞头** = 复位到出厂位（撤覆盖、不写死坐标——窗口再变仍居中）；
- **坞位记忆** = localStorage `lantai.composer.pos`（视图偏好，同 `lantai.minimap.pref` 族）；只点不拖不落盘；
- **让位带 `--composer-band`** = 视口底 → 坞顶线（默认位 = 抬高 96 + 坞实测高，与旧 `--composer-h-live` 配对式**零漂移**）。消费面按它重算：小地图默认位（只影响未摆过的默认，用户摆过即尊重）、递牒卡宿主 `.psh-host`、插件 dock `.pw-dock`（后两家经 CSS 吃 `min(--composer-band, --composer-band-cap = 55vh)`）。

**2026-09-17 二批（用户三条实机反馈，逐条改）**：
1. **目次带不让位**（用户裁定「目次带似乎没必要做让位」）：目次带映射区/可见域**只按出厂底带**（`96 + 坞实测高`）算，坞被拖到哪都不压缩导航带——坞是用户自己摆的浮窗，导航带不该跟着缩；「内容尾不藏进坞后」那条 2026-09-01 整改在坞处出厂位时口径未变，照旧成立。消费面**口径分家**：`composerDock: { bottom, height }` 原样下发，让位带 = `bottom + height`（小地图/CSS 让位件），出厂底带 = `96 + height`（目次带）。
2. **拖动与划词打架**：坞上按下会带出**原生选区**，纸上挂着 document 级 `selectionchange`（`use-paper-strips` 的选中浮钮）→ 拖动坞 = 纸上划词 + 浮钮乱冒。修法两层：**锁定态**坞是普通 DOM（根本不接手势，冲突不可能发生）+ **解锁拖动期**清掉既有选区（`window.getSelection()?.removeAllRanges()`，`use-composer-float` 起拖时一次）。~~拖动期在 `<html>` 挂 `pp-composer-dragging` 全页禁选~~——**2026-09-17 收族：全应用默认不可选之后该规则成了空操作，已撤（类保留，服务抓手光标）；冲突的根治上移到 `foundation.css` 选区政策 + 纸壳起手面判据（见 §1 后两条）**。
3. **拖动锁（用户方案，桌面歌词式）**：**默认锁定**——坞对鼠标零响应（不改光标、不接管手势、划词照旧；这同时根治了「谁都不知道这东西能拖动」与误拖）；解锁后**整坞**（除交互件）成为抓手 + 全坞抓手光标。锁态落 localStorage `lantai.composer.unlocked`。
   **二版（同日，用户打回一版「太难看了 + hover 之后点不到」）**：一版把锁钮做成**槽里浮在坞顶外缘的 hover 小钮**——两个病灶：① 浮在坞外与坞之间有缝 ⇒ **揭示靠悬停、命中又要靠揭示（互为前提）** ⇒ 一离开坞体钮先消失，再挪过去什么都没有（用户原话「鼠标还没挪过去就消失了」）；② 浮方块与坞的语言不合（丑）。
   二版 = **归坞的书眉工具行**：`.pp-dock-tools` 里的第三枚 `.pp-tool-btn`（`移` ↔ `锁`，排在 翰/律 之前——那一对内容入口保持相邻），**常显可点、零悬停机制**，样式与 翰/律 同款（纯文字、hover 朱砂、选中态 `.open` 朱砂）；锁态与写面仍在槽主人手里，坞经 `PaperDockContext.composerLock` **能力位**渲染（宿主不给 ⇒ 整枚不出现，只重载单个产物的偏斜窗口不炸）。上夹紧随之回到「顶部浮件带 + 屏缘」（不再为浮钮预留 26px；2026-09-17 标题栏拆除后该值仍是 56，改称 `COMPOSER_CHROME_H`——浮件在右上，坞压上去会盖死窗口钮，见 §14）。
   **教训（入册）**：**控件的悬停揭示区必须与它的可见区同盒**——分离时两者互为前提，必然点不到；宁可常显，不做「脱盒浮现」。

**归属**：坞位/几何/手势/拖动锁全归**槽主人** paper-shell（`composer-float.ts` 纯函数 + `use-composer-float.ts` 机制域）；坞本体（compose-dock）**一字不知**——不给 `PaperDockContext` 加回调、不动宿主面 faceDeps 基线（事件从坞冒泡到槽，槽主人接手势）。旧 `--composer-h-live`（坞自报坞高）随之拆除：让位带是槽主人的几何，一处权威源，浮动态也正确。

**边界（刻意不做）**：让位件之间互不躲让，坞也不自动躲让位件——坞停在上半屏时让位件停在半屏（坞自己负责不遮）；坞不做边框吸附动画；拖动期**不** `preventDefault`（取消 pointerdown 会连带影响 dblclick 跨引擎互操作，复位手势优先）——防误选改由「拖动锁 + 全应用默认不可选（§1 选区政策）+ 划词起手面判据」三层承担。

**过渡期（产物 vs exe 偏斜，2026-09-17 立）**：外壳 CSS（`shell.css` 的 `.psh-host` / `plugin-windows.css` 的 `.pw-dock`）**内嵌在 exe 里、不能随产物热更**，故在「只换产物不重编 exe」的部署窗口内，旧 token `--composer-h-live` 由槽主人 `use-composer-float` 代发一版（新旧两代消费面同时正确）。**拆除条件 = 下一次 `cargo tauri build`**（内嵌 CSS 换成本仓库新式后），届时删该 effect 与 tokens.css 的过渡注。一般形态的教训：**删一个跨层 token 必须与消费它的那一层同批落地**。

**证据**：`tests/composer-float.test.ts`（几何/吸附/拖动面判据/锁记忆纯函数）+ `tests/paper-composer-float.test.tsx`（挂真实 PaperPanel 穿全层：默认锁定 → 点锁钮解锁 → 坞体任意处拖动 → 拖动期全页禁选 → 让位带重算并下发覆盖层消费面 → 松手落盘 → 双击复位 → 交互件不起拖）+ `tests/stage4-toc-top-band.test.tsx`（**坞浮起不让位**：坞位从出厂位挪到半屏，刻痕落点逐字不变；坞高变了才动。该文件 2026-09-17 由 `stage4-toc-titlebar-band` 改名——书眉退役，带体回屏顶，见 §14）。

### 9.3 匣脚引线（2026-09-22 落地）——多会话卷的激活态

**来由**：活卷的信号全在纸上（接触落影加深一档 + 卷首规线左端一枚朱砂短横，**只挂活跃卷**），坞这头只有书眉行的卷名——坞自 09-17 浮动化之后两边各自在屏上走，「坞报的卷名指哪一张纸」没有可见联系。用户提案「让创作坞带一个锚点，用引线连接当前选中的会话」，同日定案口径 = **两端扎实体 + 常显·淡**（落地时另挂的「可点」系 agent 自记，**2026-09-24 用户否认后整批摘除**——见本条定案 2/3 与 [taste-ledger](../plans/paper-shell/taste-ledger.md) 同日条）。

**定案（五条）**：
1. **坞端 = 版口钮，卷端 = 纸脚**：坞顶左端那枚**版口钮**（56×3 朱短横，全坞唯一暖色件）连到活卷的**纸脚**（版心左缘 × 卷底边）。卷端落点**二版改档**——一版接在卷首规线左端那枚钮上，用户当场打回：「你这个引线能挂在页尾吗……你挂在第一条用户输入那不是乱了套了」：**天头那枚钮是「哪一卷活跃」的标记，不是「这一卷在哪儿」的位置标记**，且它正压在标题与第一条来文的接缝上，线读起来像在指第一条来文。二版接纸脚：纸的材料缘（受光/背光缘与裱边带交汇处）、不落任何一块字，且它才是「这一卷写到哪儿」的那一端（人在读尾时它就在坞上方几十像素）。
2. **常显·淡**：结构不是瞬时手势（同枝边那条腿）——墨阶 .55（**无 hover 档**：线不是控件——2026-09-24 归因更正时连同受墨带一并摘除）；切卷 = 旧线撤、新线淡入（与「拿纸 + 朱笔划界」同一拍）。
3. **纯指示·不可点**（2026-09-24 归因更正；原文为「可点溯源：点线 = 飞到线的那一头」）：线不是控件——不吃指针、不进 Tab 序、整层 `aria-hidden`；受墨带（`role="button"` + `tabIndex` + 点线飞纸脚）与 hover/聚焦抬墨两档同批摘除，撤销理由 = 用户「我从来也没有拍板过引线本体要做成按钮」。
4. **笔**：两端**锚面外法向**（匣顶朝上 / 卷底边朝下，**按锚面定、不按相对方位现算**）+ 臂长下限 48（判例那条公式「只有下限没上限」的补全；下限必须大于**重力垂**上限才读得出来——实测下限 24 时净抬起只剩 2.6px）。
5. **空态诚实**：无活卷 / 案头态（匣退、钮本就不画）⇒ 不画线；活卷在屏外 ⇒ 线照样出屏（方向即来路，同出处引导那条判据）。

**归属**：线走屏幕坐标引线层（z 4；坞 z 6 在其上 ⇒ 线不盖家具），坞侧锚点是**槽主人**（paper-shell）的几何——坞本体一字不知（compose-dock 零改动）。

**边界（诚实栏）**：翻转档（纸脚落在匣顶线之上，即坞压在纸身上）出笔仍朝上、两端各按自己的锚面 ⇒ 中间成 S；近水平档（纸脚与匣顶线同高）由下限托住，不再贴成第二条规线；坞压在活卷上时线在匣后（被挡）；LOD 远档不渲染卷首而锚点不受影响（纸脚是流区盒底，恒在）。

**证据**：`tests/paper-dock-tether.test.tsx`（真 PaperPanel **六例**：两端扎实体且卷端在卷首之下 / 切卷改指 / 坞被拖走线随坞 / 无活卷 / 案头态 / 活卷在屏外线照样出屏；**首例兼钉「不可点」**——层内无 `[role="button"], [tabindex]`、整层 `aria-hidden`。**原第七例「点线溯源」于 2026-09-24 随行为退役同批删除**）+ `tests/paper-provenance.test.ts`（笔的法向与下限 + 本腿不得有受墨带规则与接线）+ `tests/composer-float.test.ts`（坞锚与 CSS 字面量对拍）；判例账本见 [`../plans/paper-shell/taste-ledger.md`](../plans/paper-shell/taste-ledger.md) 2026-09-22 条与 **2026-09-24 归因更正条**。

### 9.4 役册（2026-09-22 落地）——坞内后台工作监视装置

**来由**：用户报「每个会话如果跑后台任务，我没有一个能监控后台任务的地方……是往创作坞放，还是往标题栏放，还是直接放会话流区里面」。**落位三选一的裁定与理由**：

1. **标题栏排除**——它已经在 **2026-09-17 由用户自己拆掉**（§14：旧书眉 56px 布局行整条退役，控制件落成右上浮件 `.pp-chrome`）。浮件占位那段 x 区间的顶缘边缘滚动感应带随之失效，且坞顶被上夹紧 56px 以免盖死窗口钮（`decorations:false` 下唯一关闭入口）——往那儿长监视面＝重建刚拆的东西，并付两笔已记账的代价。
2. **会话流区排除**——流区块是消息的派生视图（`paper/translate.ts`），要落盘、有块序、有消息语义，且 `EventKind.Notice` 的 info 级根本没有入流通路（`ui/chat-stream.ts:198-209` 明写「info → 丢弃」）。监视面是**环境态**，写进会话记录＝把运行态混进历史。流区已经有它在上下文里的正确位置：`SubAgentPart`（「这次派生的记录」就地显示）——那是记录，不是监控台，该留不该扩。
3. **创作坞落位**——唯一同时满足「常显 + 跟活跃会话 + 已有同类先例」的位。§9.1 已为同类装置立法（墨量册：设置行行尾一枚读数件 + 坞内向上开的浮层 + 并入浮层互斥），且坞已有运行态一族（停钮 §9.6 / 后台卷指示 / 底缘呼吸线 §9.8）。役册是这一族的**展开面**，不是新族。

**定案**：

| 项 | 定案 |
|---|---|
| 名字 | **役**（使役/差役＝派出去替你干的活）。与「墨」并列成对：墨＝耗，役＝工 |
| 触发器 | 设置行行尾，**役内墨外**（`pp-work-sel` 紧邻墨量册内侧、`pp-ink-sel` 仍收最右）——§9.1 对墨「读数件居行最右＝拟文印正下方的读点」的判据逐字保留。有活跃卷才渲染（同墨量册的无主待命纪律）。读数：空档 `役 —`、有活 `役 N`、他卷另计 `N+M`；有活时墨点转**石青**并呼吸（机＝石青铁律；不点朱——朱砂是人的动作，这里的「有活」不是预警）。**读数恒活（2026-10-07 修）**：对账**不随册页开合**，触发器挂载即 3s 一轮快照——触发器恒驻设置行，它的读数就是「还有多少活在跑」，不能是「点开才补齐」；役点呼吸收编既有运行态动效族 `pp-ink-live`（CSS，与落笔点/行走秒/呼吸线同拍 1.6s，动效敏感用户经 `foundation.css` 全局豁免成静态），不再是 JS 翻转（旧法只在册页开着时喘，且绕过动效豁免） |
| 册页 | 向上开（坞贴屏底），几何与 `.pp-ink-panel` 逐字同源（`right:0` / `bottom: calc(100% + 6px)` / `z 85` / 宽 300 / `max-height: min(70vh,520px)`）。三段：**在役**（本卷，逐条带时长与旁注，shell 条目带「停」）→ **他卷**（条件段，标卷名不裸报号）→ **已了**（终态，按结束倒序，至多 8 条）。排印沿墨量册的册页语言（段题＝方墨锚点 + 字距题字；读数当全册唯一题字） |
| 互斥 | 并入坞的浮层互斥（原四层 → §9.1 墨量册五层 → 本批**六层**）；切卷清本地态照旧 |
| 归属 | 坞是视图不是容器（铁律不动）：台账真源在 `state/work-ledger-store`（由 Agent 侧观察点喂），本册只读 |

**数据面（为什么 UI 侧要自建一本账）**：Agent 侧三本账都读不出「按会话的在役清单」——① `SubAgentPool` 是**工作区级**单例，句柄无 session/parent 字段，`listRunning()` 只能给「本工作区全部子 Agent」；② `subagent-activity` 键＝子 Agent id、**终态即删**、无订阅，唯一读者是 `agent_status` 模型工具；③ Rust `BG_JOBS` 的 `bg_jobs_snapshot()` **只返回仍在跑的 job**（`try_wait()==Ok(None)`），已完成待读 / `try_wait` 出错 / 已移除三者同形，且 exit code 从未落进 `BgJob` 字段——而 `bg:note` 在 job **完成时**才发，那一刻它已查不到。故「记录」这半边只能由 UI 在**观察点**上自记：子 Agent 走 `AgentUINotifier` 的 `subAgentSpawn`/`subAgentFinished`（全仓唯一带 `sessionId` + `parentAgentId` 的派生观察点，`runtime.ts:957-968` 补的父身份），shell 走 `background_activity` 快照对账（在役集合）+ `bg:note`（终态时点，`workspace.ts` 的既有监听点里加一跳，且**先于** owner 守卫——`owner=null` 的用户任务也要落账）。

**对账恒跑（2026-10-07 修）**：快照对账是 shell 在役集合的**唯一**可靠来源，故它随触发器挂载恒跑，不再只在册页打开期间——会话侧没有「job 已启动」事件；唯一的终态事件 `bg:note` 也会漏（job 被 `bash_output`/`bash_wait`/`kill_bg` 提前移除时，`bg_jobs.rs` 监视线程下一拍 `jobs.get_mut` 拿到 `None` 直接 return，那一跳随 job 一起没了）⇒ 靠事件画不出在役清单。恒跑的代价由台账自己收口：**空转引用守卫**（快照与账上逐项一致 ⇒ 返回原 state 对象，zustand 的 `Object.is` 早退让订阅面整轮不重渲；既往的读取错误仍照清，不被空转吞掉）。

**口径纪律**：① **只读**——对账绝不调 `bash_output`（那个 action 的增量游标是所有读方共用的，且读到终态即 `jobs.remove()`，UI 读一次等于吃掉模型随后要用的输出并销毁 job，`bg_jobs.rs:474-479`）；② **终态不编造**——shell 的终态由「从在役集合消失」外推，只写中性「已了」+ 旁注「已结束」，**不报退出码、不外推成败**；③ **不落盘**——纯内存、按面板隔离、退出即空（与 `SubAgentPart` 同命运；要持久记录是 Agent 侧 TaskBoard 的事）；④ **失败可见**——账本读取失败写进册页页脚，停止动作失败走提示条（两件事两个面，互不抹除）。

**owner → 会话归属**：Rust 只给裸 owner 串（`main-<ts>-<rand>` / `sub-<ts>-<rand>` / null），没有会话字段。子 Agent 不入 `sessionOfAgent` 表（`agent-session-state.ts:99-101` 明写），故解析走 **bus 的 `parentId` 链上溯**到主 Agent 再查表——这条链对子 Agent 是通的（子 Agent 随 `setBus` 注册）。解析器由 `workspace` 在装配期注入（面板 runtime 才有 bus），teardown 对称解除；**不注入＝归属未知**，条目仍可见，落「他卷」档。

**边界（诚实栏）**：① **子代理条目无逐条停止**——池对 UI 不可达（`ChatAgentHandle` 只暴露 `runningSubAgentCount` / `stopAllSubAgents`），逐条停需另开只读/控制通道，本批不做；② **shell 终态无退出码**（账本不回流，见上）；③ `background_activity` 混着**前台**正在跑的命令（`BgJob` 无 fg/bg 字段，外部不可观测），故册页叫「役」不叫「后台任务」；④ 记录**不落盘**，重开即空；⑤ **「算不算在跑」= 用户裁定「不计入」**（**拍板日 2026-09-20**，留痕 `tests/async-return-delivery.test.ts` 头注；landmine L5 状态格当时漏记，2026-09-22 用户复述后补记）：**后台活体不计入**——本卷 Agent 就是空闲的、可继续交互，呼吸线 / 停钮 / 侧栏状态点 / 行卷中 / 退出守卫一律保持只读运行账。役册不是补在那个判据上，而是**另立一个面**：「Agent 忙不忙」读运行账，「还有什么在跑」读役册。**接受的代价**：在役后台任务不升起退出确认，关窗即被 lifecycle 终止。

**证据**：`tests/work-ledger-store.test.ts`（**24 例**（2026-10-07 加 3 例空转纪律：逐项一致⇒引用不变、真有变化照常换引用、既往错误照清）：spawn/finished 记账、未观察到的收尾 no-op、起算反推稳定、消失即结转中性终态、按面板×卷切分与排序、终态配额淘汰不吃在役、**只读纪律**（对账只打 `background_activity`）、形状坏/传输错都写 error 不静默、`bash_kill` 不带 owner＝用户路径）+ `tests/composer-dock-work-ledger.test.tsx`（**12 例**（2026-10-07 加 2 例**恒活**：册页关着时后台任务起来⇒触发器当轮自亮、停了⇒当轮自灭并结转终态）：触发器读数与空态、无活跃卷整枚不出现、册页三段与空态诚实、逐条停止只出 shell 条目、停止走 `bash_kill` 后立刻落「已了」、六层互斥、切卷清本地态）+ `tests/composer-dock-settings-pair.test.tsx`（**显式规格变更**：行尾由单枚仪表扩为「役 | 墨」两枚读数件，成对契约与「读数不插进策略对」不变）。

**部署面（诚实栏）**：本批**动了宿主面**——`faceDeps` 新增 5 键（`useWorkLedgerStore` / `selectSessionWork` / `pullShellWork` / `killShellWork` / `setOwnerSessionResolver`），且两个观察点接线（`ui/runtime-adapter.ts` 的 spawn/finished、`workspace.ts` 的归属解析注入与 `bg:note` 对账）都在宿主代码里 ⇒ **不能只换产物热更，须重建 exe**；`src-ui/src/plugins/host-surface.baseline.json` 已同批重生成（封印测试 `tests/host-surface-seal.test.ts` 是这条纪律的考官）。

### 9.5 图版架（2026-09-23 拍板：**丙 · 匣下横架**）——图版资产的收纳面

**来由**：用户报「Agent 产出的 kind 资产直接渲染到聊天流里，其实不好用」，并给出落位判断
（原话）：「**我觉得放在创作坞是对的，我觉得需要单独再设计一个收纳的地方，不然全部挤在右下角也不是很舒服**」；
看完三案原型后追加「**再做一版把横架放在坞下面的**」，同日拍板**丙案**。

**为什么不能挤右下角**：坞设置行右端已有两枚读数件（`役` / `墨`），各开一本 300px 册页
（`.pp-ink-panel` / `.pp-work-panel`，`right:0` + `bottom:calc(100%+6px)` 向上开）；再往那儿加第三枚触发器
= 三本册页共用一个向上开的角。**故收纳面不是"第三枚触发器"，是一件独立家具。**

**位置三案对照（真几何实测，见 `prototype/asset-rack-v2.NOTES.md`）**：

| 案 | 架占位 | 让位带 | 压在哪儿 | 认脸 | 软肋 |
|---|---|---|---|---|---|
| 甲 · 匣顶 | 880×38（匣的第一行） | 227 → **265** | 纸尾正文 38px | 签 + 题名 6 张 | 盖纸尾；免掉须动壳域流锚 margin |
| 乙 · 匣左 | 48×≤8×34（贴匣左缘外） | 227（不变） | 页边（版心之外） | 只出签，题名要 hover | 窄窗（880）架出屏 |
| **丙 · 匣下（拍板）** | 880×38（挂匣下缘外侧） | **227（不变）** | **锚下留白**（y 804→842，一个字不盖） | 签 + 题名 6 张 | 匣吸「最底缘」时架被屏缘切 |

**丙的几何（真读数）**：坞 `880×131` 坐底抬高 `96`（`--composer-rise`）；流锚 = 最新块底边 =
视口底 − 96（`ANCHOR.screenBottomMargin`）；锚以下到纸底缘（+72）是**空白页边**——架就吃这一段。
架挂 `.pp-composer` 的 `top:100%`（**绝对定位 ⇒ 不进 `.pp-composer-slot` 的量高盒 ⇒ 让位带恒 227**，
小地图/递牒卡/插件坞/目次带映射区零让位）。

**兜底（同批拍板）**：架在时「最底缘」吸附位**顺延架高**（`8 → 46`）——`snapComposerPos` 的 `bottoms`
按「架在否」取 `[46, 96]` / `[8, 96]`。**夹紧下限同一条尺子**（施工回执补记）：吸附阈 24 < 架高 38，
若下限仍在 8，用户拖到最底那一下既不吸附、又停得住（架照样被屏缘切）——故架在时下限一并取 46
（`clampComposerPos` 的 `floor`，判据同源 = `paper/asset-rack.ts` 的 `rackPresent`）。取此案而非
「翻到匣顶」的理由：架永在匣下（阅读位置一致），且翻上去会当场变成甲案（盖纸尾）。

**架面（签条语汇，禁"工具栏化"）**：单元 = **物类签**（`plateSignOf(kind)`，mono 9px 石青 + 发丝框）
+ **题名**（中墨）+ 状态（**更新 = 石青点**〔机＝石青，朱砂只留给人的动作〕）。
**签条不套方框**——一排灰边框按钮是工具栏的语言，不是"架上签条"的语言；hover = 题名转重墨 + 一条**朱砂底规线**
（坞内既有 hover 语言，同 `.pp-tool-btn`）。板面 = `color-mix(--paper-deep 58%, --paper)` + 上下发丝线 +
受光缘内侧高光（家具语言，不引新色）。**溢出 = 6 张 + 「… 另 N 张」，横向不滚**（架是家具，不是滚动条）。
序 = 流转序。

**架 = "还收着的图版"（2026-09-23 二次拍板：拿出来语义）**：用户原话「**拖出钉住的签条，就不要继续在横架里面了，
拖出来钉住就等于"拿出来"了**」。故：
- **入架判据 = 本卷有该资产 且 该块未钉**（块 id ∉ `canvas-store.pins`）——**一条判据，零新状态**：
  钉住的资产无论在架上拖出的还是从流内文类签拖出的，**一律离架**（钉 = 公共物，已属"案上"，不属"匣里"）；
- **拔钉收回 ⇒ 签条回架**（原位、顺序归位；收回语义与流内「已移出 · 点击恢复」同源）；
- 由「已钉」这条状态消失连带：**签条不再需要"已钉"记号**（它不在架上，记号无处可挂），
  架的读数因此变成一句诚实的话——**"本卷还有什么没摆出来"**；
- **空态判据 = 架内零张**（不是"本卷零资产"）：一张不剩（全钉出 / 本就没有）⇒ **整条退场**，
  与"空态零占位"同一条纪律；钉出去的东西在案上看得见，不存在"资产不见了"。

**手势三条（同一张签条）**：① **单击 = 飞到流里那一块**（`flyToPoint`，与目次带阶段锚同族；若该块处于
收起态则连展开）；② **拖出 = 钉到纸上，签条同时离架**（沿用既有钉手势语义；拖动期签条跟手，松手落钉后
从架内移除、后续签条递补）；③ **hover = 题名完整 + kind/时间**（认脸）。「点开就地浮出大图预览」**本批不做**，
留作后续按需加。

**归属与部署面**：架归**产物流**——`compose-dock` 内的新组件（与 `InkLedger` / `WorkLedger` 同族），
板面挂槽内 `.pp-composer` 的兄弟位；**吸附位顺延**落 `paper-shell` 的 `composer-float.ts`（槽主人持吸附表）。
**零 `faceDeps` 新增**：架只消费既有上下文（`usePaperRegion().regions` 取块与 `asset` 元数据、
`usePaperDock().flyToPoint` 跳转）⇒ **只换产物热更即可，不必重建 exe**。

**流内配套（2026-10-08 用户拍板：撤销默认收起）**：流里的图版卡**默认张开**——原文是「默认收成一行
签条（否则架上一份、流里一大坨 = 双份）」，用户原话「**默认折叠很奇怪**」，该理由随之作废：流里那张 =
**上下文原位的一份**，架上签条 = **本卷收纳读数**，两处并存即现行形态。变更面对 `paper/fold.ts`：
资产块**仍在折叠族内**（`isFoldable` 认 `asset` 元数据；用户点折叠行即可收起长卡），而
`defaultFolded` 对 `asset != null` 恒返 `false`；旧的两条豁免（**钉住态**张着 / **活确认卡**不可藏）
随默认态翻转**一并作废**——张开的卡无所谓"豁免折叠"，而"可操作卡不可被藏住"这条纪律由默认态自己兜住。
`foldLabel`（「签 + 题名」）与 measure 的资产折叠分支（`FOLD_ROW_H`）为**用户手动收起**这条路径原样保留。

**证据（本批施工判据）**：`tests/composer-dock-rack.test.tsx`（真 PaperPanel 挂载：架是 `.pp-composer` 的
兄弟且 `top:100%`／`.pp-composer-slot` 实测高**不含架**⇒让位带 227 不变／空态（架内零张）零渲染／6 张 + 「另 N 张」／
单击 → `flyToPoint` 到该块／更新广播出石青点／**钉出 ⇒ 该签条离架且「另 N 张」计数随之**／**拔钉 ⇒ 签条回架**／
**全钉出 ⇒ 整条退场**）+ `tests/composer-float.test.ts`（吸附表：架在 ⇒ `[46, 96]`，
架不在 ⇒ `[8, 96]`，逐值）+ `tests/asset-fold.test.ts`（资产在折叠族内且**默认张开**／可手动收起／foldLabel 出签与题名／
measure 折叠高 = `FOLD_ROW_H`）+ `prototype/asset-rack-v2.html`（真样式台，三案对照与诊断层）。

### 9.6 创作坞 P0 精修（2026-10-21）

**来由**：用户判「基本 UI/UX 已经不错，但停留在不精致」——逐状态实机体检（默认/多行/附件/六浮层/880 窄窗/坞拖上半屏）后，
先落五条**不涉及审美口径**的硬缺陷；视觉系统（字号下限/红色预算/左轴）留 P1。

1. **输入框原生滚动条根治**：`autoGrow` 在 `box-sizing: border-box` 下只写 `scrollHeight`，单行少 1px
   （实测 `scrollHeight 39 / clientHeight 38`）⇒ 滚动条常驻；同时 `foundation.css` 的 `* { scrollbar-width: thin }`
   在 Chromium 121+ 压过 `::-webkit-scrollbar`，全应用退回原生白条。修法 = `autoGrow` 补 `offsetHeight - clientHeight`
   （边框高）再夹 144；输入框 `scrollbar-width: none` + `::-webkit-scrollbar { display: none }`（长文仍可滚轮/键盘滚）；
   删全局 standard 属性侧，纸面自定义滚动条真正生效。
2. **空输入 = 未蘸墨的印**：旧态空输入时「拟文」仍是全坞最重黑块，`onSend` 却直接 return（假主动作）。
   现 `disabled={!inputText.trim()}`：空心描边（`--ink-4` 边 + `--ink-3` 字、无 `--shadow-anchor`）、`title` 改「先落笔，再拟文」；
   有字即回墨印。运行中空输入仍由停钮接管（三态不变）。
3. **浮层随坞位换向**：坞浮动化后可停上半屏，而八本浮层全部写死向上开（实测坞在 y=120 时墨量册 `top:-159px`）。
   槽主人按坞顶下发 `data-pop-side`（坞顶在上半屏 = `down`）与 `--dock-room-up/down`（两侧余量）；
   CSS 统一换向（原 4/6/8 间隙分组保留）+ `max-height: min(70vh, 原上限, 所选侧余量)`，面板自身 overflow 照常滚。
   **坞本体（compose-dock）一字不知**——判据与余量都在槽主人（`composerPopSide` 纯函数 + `useComposerFloat`）。
4. **模型菜单选中态归队**：`.ms-item.selected` 旧为 `--seal-soft` 粉洗（§11 明令退役的第三种选中语言），
   改 `--sel-wash` + `inset 2px 0 var(--seal)` 朱砂左脊；`selected:hover/active` 仍走 `--paper-deep` + 左脊（两层信号）。
5. **热区与无障碍名**：单字工具钮 21×23、读数件高 22 偏小——伪元素 `inset:-4px` 撑命中面（视觉尺寸不变；
   `.pp-dock-tools` gap 6→8，相邻盒边相接不叠压）；模型触发器 `min-height: 28px`；移/翰/律补 `aria-label`，
   墨/役触发器补读数型 `aria-label`（可见文本不变）。

**边界**：本批不动坞的版心/三行制/朱砂红预算/字号下限/左轴（P1 再议）；`composer-dock` 产物可热更，
`PaperPanel.css`/`foundation.css` 在壳 bundle ⇒ 真机看新样式须重建 exe。

**证据**：`tests/composer-p0-polish.test.ts`（CSS/接线钉值 9 例）+ `tests/composer-dock-rework.test.tsx`
（空印禁用/点空不发消息/有字即启用）+ `tests/paper-composer-float.test.tsx`（默认 up、上移后 down + 两侧余量）
+ `tests/composer-float.test.ts`（朝向纯函数 2 例）。

### 9.7 创作坞 P1 视觉系统（2026-10-22）

**来由**：P0 落完后用户真机重建验收「看起来没啥问题」，继续取 P1——「不精致」的视觉口径，不是缺陷。
五件定案（agent 自定，未再打断用户；两条曾预告需拍板的项按下述取舍落地）：

1. **字号下限 + 主次反转**：模型菜单旧态机器 id 10px > 人读名 9px（主次倒置，且 9px 是
   「瞎眼档」）。现 name **12/600/ink-1**、id **10/ink-3**、分组题 **11/600/ink-2**（去全大写
   mono，字体换 song）；「视」徽 8→9。律册键位 11→12/ink-2（去石青），引面板路径 10→11/ink-2，
   文件签 10→11、脚注/图例/账目副行 10→11。设置行（模型/权限/思考/墨/役）全部吃
   `--font-scale`（此前写死 px，字号缩放只作用于输入框/标题）。
2. **红色预算（厂商标记转纸）**：厂商 = 机器身份，不是人的动作。16px 实心朱砂方块改为
   **纸色底 + ink-2 字 + 1px ink-4 框**（分组头 14px 同款）——坞内最响的红回到「全放」底线 /
   拟文印 / 版口钮 / 匣脚引线。朱砂语义不再被品牌章稀释。
3. **左侧轴线（输入行重排）**：旧序 `引/夹 → 附件 → textarea` 把正文顶开 **88px**（标题/设置行
   x=911，正文 x=997——同一张坞三条左缘）。现序 = `textarea → 附件/附图 → 引/夹 → 拟文`：
   正文与书眉卷名、设置行共用一条左缘；引/夹/附件靠近拟文印（落笔前动作）。翰/引浮层仍
   **absolute 不参与这条轴**。
4. **模型触发器 150→215**：150px 把「DeepSeek V4.1 Flash (latest)」截成「DeepSeek V4.1 Fl...」；
   215px 给名称列 **173px**（实机 scrollWidth），整名读全；窄窗仍容得下整行
   （215+100+123+103+57+69+48=715 < 788 内容宽）。名称抬 600/ink-1。
5. **文件签 = 纸签（去装饰蓝）**：10px 石青框是「浏览器 tag」语汇；改 11px mono / ink-2 /
   1px ink-4 框 / 纸色底，hover 才转朱砂（取下 = 人的动作）。同理律册键位、翰快捷键去石青
   （石青只留「机器在跑 / 语义引注」），组合芯片只读态 ink-3→ink-2（只读不等于读不清）。
   透明文字控件（工具 / 引夹 / 模式 / 模型 / 组合 / 思考 / 墨 / 役）的 `:focus-visible` 改
   **朱砂底线**（`inset 0 -2px 0 var(--seal)`），不再画 2px 红框——200px 的模型触发器被红框
   圈住像报错；实心印（拟文/停）保留全局红框。

**边界**：不动坞的版心/三行制/设置行归堆/朱砂主动作；不重排翰/律/役的信息架构（P2）；
模型菜单 300px 宽与 260px 封高不动（内容变高后照常滚）。

**证据**：`tests/composer-p1-polish.test.ts`（字号/主次/红蓝/缩放/焦点钉值 8 例）+
`tests/composer-dock-row-order.test.tsx`（textarea 是输入行第一个布局件，引/夹在其右、拟文最右；
4 例含 P1 新增 1 例）+ `tests/model-selector-compact.test.tsx`（目录外 provider-scoped id 去前缀 1 例）
+ 真机 CDP：模型菜单 name 12/600 与 id 10/ink-3、厂商章 computed
`paper-deep + ink-2 + ink-4`、模型触发器 215、文本左缘与标题同 x。

**部署面**：模型菜单/组合芯片/ComposerDock 为 `compose-dock` 产物（可热更）；`PaperPanel.css`
在壳 bundle ⇒ 真机看字号/纸签/左轴/厂商章须重建 exe。

### 9.8 翰/律/役 信息架构（2026-10-22 P2）

**来由**：P1 后用户「开P2」——不动输入体验，只修三个面板的「读法」。

1. **翰 = 全局命令面板（Ctrl+K 同一份）**：旧翰在坞内维护第二份内联斜杠清单（无搜索框、无分组、
   只有 slash 命令），与 Ctrl+K 的全局面板（搜索 + 分组 + 动作/插件命令）重复。现翰只做一件事：
   `setPaletteOpen(true)`；`/` 触发词仍走内联 `.pp-slash`（查询词在正文里，只列 slash 命令）。
   坞内 `menuOpen` / `effectiveSlashQuery` 整组删除（翰不再是坞的本地浮层，不入「思考/律/引/墨/役」
   互斥族）。**全局面板同时回纸**：`--glass-hi` + `backdrop-filter` 退役（那是观测台材质），改
   `--paper` 不透明底 + `--rule-head` 头线；组题 11/600 去大写 mono，行 13，脚 11，kbd 11。
2. **律 = 四组**：13 行等权平铺 → **输入 / 附卷 / 画布 / 纸面**；组题复刻册页段题（6px 实心方墨 +
   10px/600/0.18em 题字），组间一条弱线。行数据原样保留（键位/释义逐字未动）。
3. **役 = 空态一句话**：旧空态把「在役」说了三遍（`0 在役 · 0 已了` / 大号 `0` + 在役 / 段题「在役」
   / 本卷无在役）。现零在役时**只出**「本卷无在役」+ 一行去处说明「子代理与后台命令会在这里出现」；
   大号读数、子代理/后台命令计数、段题「在役」全部只在 `running.length > 0` 时渲染。头部计数
   也只在「有在役或有已了」时出现（不全零空报）。

**边界**：`/` 内联面板的键盘/执行路径逐字未动；翰/律/役 的触发钮/热区/aria-label 不动；
全局面板的动作源（listActions + session commands + plugin contributions）不动。

**证据**：`tests/composer-dock-desk.test.tsx`（翰只开全局面板、不再生 `.pp-slash`；`/` 仍走内联面板并执行；
律四组题名；14 例）+ `tests/composer-dock-work-ledger.test.tsx`（空态一句 + 去处说明 + 无大号 0/无「在役」
段题；12 例）+ `tests/composer-p2-ia.test.ts`（pal-box 回纸/去 blur、组题/行/脚字号、翰接线、役空态接线；
5 例）+ `tests/composer-dock-keyboard.test.tsx`（斜杠键盘 6 例零改动）。

**部署面**：`ComposerDock` / `WorkLedger` 为 `compose-dock` 产物（可热更）；`shell.css` 的 `.pal-*`
与 `PaperPanel.css` 的 `.pp-help-*` / `.pp-work-*` 在壳 bundle ⇒ 真机看全量须重建 exe。

---

## 10. 浸墨法则（2026-08-31 全局视觉立宪 · 用户拍板 B）

**病灶定案**：全 UI「简陋感」根源 = 只有线框没有墨——古籍隐喻抄了线没抄墨（真古籍版框是粗黑双线 = 全页最重墨，印章是实心朱砂，题字是浓墨大字；产品把这些全做成了灰发丝 + 描边 + 中庸字重）。治法不是加装饰，是**上墨**：同内容同栅格，只改墨量即换血（prototype/ink-ab.html A/B 实证，用户拍板 B）。

**五法则**（token 见 tokens.css「浸墨法则」块）：

1. **墨阶锚点**：重墨全产品只许三处——① 页缘版框（`--rule-frame` 2px 墨线，古籍双栏线）；② 每屏唯一主动作（主钮/拟文印，墨底实色 + `--shadow-anchor` 硬偏移投影）；③ 屏级分区线（首页书眉底线/列表顶线/脚线/坞顶线，`--rule-hard`）。余处禁 2px 硬线。**画布视图的「书眉底线」已随 2026-09-17 标题栏拆除批退役**（画布铺满整窗，该视图的屏级分区线只剩坞顶线；顶部控制件改浮件，走弱线 + `--elev-raise`，见 §14）。
2. **字重极端**（2026-09-01 轻重批对齐拍板 B 钉值测试；2026-09-10 三体换代：MiSans VF 全字重已装载）：题字 `--weight-display` (900)，卷首 700（`.pp-folio-title`），卷名/条目名/动作钮 600，机读注记 400——四级之外禁盘（500 为审计实锤违例已清零）。张力全在两极差。
3. **句读点朱**：题字句号落 `--seal`——古籍句读遗意，每屏至多一处红字。
4. **纸层次**（2026-09-01 真纸化）：全局纹理层（**`body::after` 文档级**，z `--z-grain`；勿挂组件根——`.sh-root` 是首页自己的层叠上下文，纹理会被困在首页，画布/面板全无纹理，实机打回过一次）挂**真纸纹理资产**（`src/assets/paper/paper-grain.jpg` 高频肌理 × `paper-fiber.jpg` 低频纤维晕染，AI 平扫感生成 + 两段预处理：按通道异权提白 `k=R.55/G.40/B.25` 中和黄味（两层 multiply 复利，暖调由 `--paper` carry）→ 统一扩幅 `k=1.6` 放大振幅 ×2.6（提白后振幅只剩四成、画布上读不出纹理，实机打回重调）；`background-blend-mode: multiply` 相乘后随元素 `multiply` 浸入页面，`brightness(1.05)` 校暗度至 ~13%，顶层留 .05 SVG 微颗粒抗色带）+ `--light-fall` 顶部方向光 + `--vignette` 四边微沉 + `--laid-lines` 帘纹（`body::before`）——纸从「底色」变「材料」。印面/重墨受纹理同源于顶层 multiply（全局覆盖），局部禁再挂纹理层——**唯一例外＝印章 `.sh-seal` 挂印泥分材质**（印泥≠纸：`src/assets/paper/seal-paste.jpg` 朱砂膏体颗粒/纤维，同脚本两段预处理成色相中性灰后 `background-blend-mode: multiply` 乘在 `--seal` 实色上，160px 平铺，色随 token 走不锁死在图里）；换纸 = 替换 assets/paper/ 同名图片并跑 `scripts/normalize-paper-texture.ps1`，管道不变。
   - **墨迹洇边（同批）**：重墨大字墨渗——题字 900 加 1.5px 字晕、节题字 1px、节题墨锚 2px 柔晕（`text-shadow`/`box-shadow` + `color-mix(in oklch, var(--ink-solid) N%, transparent)`，同 folio-title 的 alpha 墨残影手法）；发丝线（版框/界栏 1-2px）**不加**——洇边会把细线糊成泥。
   - **流区真纸（材质批二）**：每卷流区＝一张不透明真纸——`src/assets/paper/paper-sheet.jpg`（fiber 线性扩幅回中派生：`a=1.63/b=-.555`——振幅 .031→.067 立得住、均值 .94 不动纸色；原 k=.7 提白档实机不可见；管道 `normalize-paper-texture.ps1 -Sheet`）乘印其上 + `src/paper/sheet.ts` 以卷 id 哈希出纸性三参 `--sheet-ox/oy/j`（同卷恒同纸、卷卷不重样；active 态只动 `background-color`——`background:` 简写会抹掉纸纹层）；流区挂接触落影 `--shadow-sheet`（两段硬偏移堆纸厚——同色纸放同色桌面全靠它读出「一张纸」，非 UI 海拔、是材质物理）。
   - **物理包边（2026-09-02 视觉迭代）**：流区纸缘＝材料不是墨——border/outline 全退役，box-shadow 四层堆出纸的物理四至（受光缘 `--sheet-lit` 左上一线 → 背光缘 `--sheet-shade` 右下 → 裱边带 `--sheet-band` 7px 一圈纸色深带 → 接触落影 `--shadow-sheet` 重校）；剂量 A/B 台 `prototype/edge-ab.html` 定档（亮 .75——米色桌会吃淡光、沉 .13、带 42%）。active 态洗底退役（「变色」判死）——只换落影一档 `--shadow-sheet-active`（手里正拿着的纸离桌面更高一点），活跃信号全走结构墨阶不动纸色；`background:` 简写禁令延续（会抹纸纹层）。
   - **贴纸纹理归属（2026-09-02 透明错觉根治）**：纹理必须随纸走——任何视口固定（fixed）的纹理/纹样层在画布上都是「不动之纹」，拖动时纸走纹不走，材质被大脑判属桌面，流区被读作「透」（实机白纸双盲实锤：纯白实心流区 + 固定横纹 = 仍读作透；流区一直在画，从无渲染故障）。归属三条：① 桌面纹 = `.pp-desk`（`.pp-world` 第一子，世界坐标系随拖动/缩放，四层配方「微颗粒×grain×fiber×帘纹」只混自身层不乘盖流区/纸条）；② 流区纹 = `.pp-region` 自带 paper-sheet 单层（帘纹不进流区——叠乘读作屏纹，实机过审移除）；③ 文档级 `body::after` 颗粒与 `body::before` 帘纹在画布态退役（`body:has(.pp-root)` / `body:not(:has(.pp-root))` 分治），首页/面板照旧（**模态豁免 2026-09-10**：设置面板（全屏模态，墨纱盖画布）在场时恢复文档级材质——工作区里开设置不再被 `.pp-root` 连坐剥光，两场景同观感；实现走「设置遮罩在场即恢复」选择器，画布裸露可交互时材质归属仍按画布态）；`body::before` 画布态只留顶光+边沉——光照类视口固定正当（灯在桌上、不在纸里）。顶眉/坞/目次带等固定家具在画布态无纹（家具与内容分层）。
5. **完工动作**：选中态墨底反白（禁灰底假选中）、浮层必挂投影（`--elev-raise`/`--elev-menu`）、节题前实心方墨锚点。

**转录位**（铺开批次）：首页（已落地）→ ~~画布卷首/流区界栏双线框~~（2026-09-02 翻案：界栏双线框退役，流区改物理包边——见 §10 纸层次）→ 创作坞（prototype/dock-v3.html 已同步浸墨）→ 案卷侧边栏（2026-09-02 落地，见 §12）→ 设置面板。法则改动只动 §10 与 tokens，不许散写。

## 12. 案卷侧边栏（2026-09-02 UX/浸墨批）

八件定案（用户拍板：选中 B 墨洗 / 可调宽 / 保持覆盖 / 缺口全做 / 互斥两态）：

1. **互斥两态**：书脊列 = 侧边栏的**收起态**——左缘任一时刻只留一个。侧栏展开（`left:0` 独占左缘，书脊整列退场）；收起（书脊回场：`@starting-style` 起手值 + `--m-ink` 过渡从左缘滑入）。canvas-nav 插件以**终态不变量**裁决（并陈 → 书脊退；纸开而两关 → 书脊回），对热替换遗留「双开」态自愈。书脊列**与侧栏同族**（纸底 + 右缘 `--rule-strong`）——两态是同一块板换宽度，不是换了个东西（2026-09-21 重做批补；此前书脊无底无边是散块）。**板面纹理同源（2026-09-21 纸面批）**：画布态把文档级纹理层整层退役（`foundation.css` 的 `body:has(.pp-root)::after`），固定家具随之只剩 flat `--paper`——而旁边桌垫（`.pp-desk`）是有纹的，用户判「纯色背景死气沉沉」。治法 = 两态各挂**同一套板面纹理层**（`.ss-sidebar::before` / `.sr-rack::before`，配方真源 = `tokens.css` 的 `--panel-tex-image/size/blend/bright`，与桌垫逐字同源、**固定 2048 平铺**不走 cover），纹理层 `z-index:-1` 落在面板底色之上、内容之下，`brightness` 只提纹理不连字提亮。**「家具无纹」的例外仅限不透明整块板**——浮在移动纸面上的层仍须无纹（否则以「不动之纹」出卖空间隐喻，2026-09-01 判例）。
2. **空间手势承接**：侧栏行拖放落位 = 书脊手势同族——摊开行拖 = 再落位；闭合行拖 = **先落位再摊开**（region 先写，装载即用落点位）+ expand 自带聚焦。
3. **选中语言**：行型选中（§11 分型）——`--sel-wash` 墨洗 + 朱砂左脊，当前卷与整理态勾选行**共用**同一语言（拍板 B：退役旧朱砂洗变体）。
4. **浸墨**：书眉/节头实心方墨锚（收起态换空心框）+ 字晕洇边；机读计数一律**朱字**（seal-deep）；「另起一卷」= 本屏唯一主动作，墨底实色 + `--shadow-anchor`（拟文印同款 hover 翻朱砂深）。
5. **已合卷分桶**：今天 / 7 天内 / 更早三桶（桶头仅多桶时立），**更早默认收起** = 归档语义——大卷量下老卷不删也出视野；节/桶头全可折叠，localStorage 持久。
6. **未存注记**：未落盘新卷行注记出「未存」段（显式标记比缺段诚实——自动存失败可据此发现）。
7. **键盘全席**：↑↓/Home/End 游标、Enter/Space 摊开定位、F2 改名、**C 合卷**、Delete 两击删除、Esc 解武 → 收侧栏回书脊。整理态内：Enter/Space = 勾选、**Shift 区间连选**、**X 勾选**、Ctrl+A 全选可见、Esc 解武 → 退出整理（F2 / C / Delete 退场——选择语境单一）。
8. **整理模式（2026-10-08 丙案，取代原「多选批量删除」）**：选择是模式不是散点——书眉「整理」进入（常态勾选格不显、状态点不让位、hover 零变形，根治「黑方块 hover 变中空框」变形感与「入口全藏」）；整理态整栏换装：勾选框全显并与状态点并排、点行 = 勾选、Shift 区间连选、单行动作让位（占位隐藏）、顶部整理条（替换「另起一卷」与视角两行）「删除所选」两击确认；完成 / Esc 退出；运行中卷跳过并报数。行操作钮热区 ≥24px。宽度右缘拖拽 240–420px（localStorage 持久，聚焦后 ←→ 微调 ±16px）。
9. **删除武装期的取消语义（2026-09-21 用户报「点了别处会把卷摊开，逻辑冲突」）**：行内「删」首击 = 武装（钮转朱砂深，连坐数写进行内注记行），再击才写墓碑；**武装期间点「其它处」= 取消，且那一击不许被读成摊开**——行内任何点击（本行「删」= 第二次确认、别的卷「删」= 改删目标两件除外）只作取消，不摊开 / 不切活跃卷 / 不飞视角（Enter/Space 同款：不走 click 事件，守卫落在 `onRowClick`）；本栏**非行件**（检索 / 新建 / 视角 / 节头 / 整理条）与**栏外**任何处照常执行、顺带撤武装；栏外**按下**即撤（`document` mousedown），红态不跨栏残留——否则去画布点一下再回来，下一击「删」就被读成第二次确认 = 一次点击直接删除；Esc 同解武（§12.7 撤退第一级）。实现 = `SessionSidebar` 的 `onArmedClickCapture`（捕获相位，必须早于行自身 onClick）+ `onRowClick` 键盘半边 + 落位/拖放解武。

### 12.1 书脊列（2026-09-21 四批 · 戊「墨缘题签脊」）

定题三条（三轮用户判词）：① **不够好看** + 标签多了**冲出屏幕**；② 对二批修法台的回应——**「并不是按着之前的那些方案改一改就能解决的……得重新设计」**；③ 对三批重设计的回应——**「之前是分块式的，每个卷独立一个标签……是有设计感的。包括『案卷』按钮，做的是一个虚线框按钮，也是有设计感的——现在看起来又平又简陋，设计不存在了」**。

**病灶（四批定位，对拍 git `c78b8c98`）**：判词属实，且不是「没改好」而是**归错档**——§11 海拔表把整列判成「面板架档 = 零投影」，二批据此按「禁框禁影」办，删掉三件语汇：「案卷」扣的 `border: var(--rule-dashed)`、脊块的 `--paper-deep` 底 + `--rule-soft` 框 + `3px --ink-4` 左脊、活跃态的 `--elev-raise` + 朱砂脊边。**脊块是纸片件（与便条/纸条同族），不是面板骨架** ⇒ 归位。

**尺度通则（四批复原台实测）**：照抄 `.pp-region` 的大面积物理包边（受光缘 3–4px / 背光缘 / 裱边带 / 接触落影）缩到 60px 的脊上**读成一片糊**——那套内距是给 720px 流区定的。**大尺寸用纸（渐变带宽），小尺寸用线（有方向的边）。**

九条契约：

1. **函套底**：`.sr-rack` = `--paper` 底 + 右缘 `--rule-strong`——**与 `.ss-sidebar` 逐字同色**（互斥两态真是同一块板换宽度；二批取 `--paper-deep` 实为另一块板）。
2. **脊块 = 纸片件 · 墨缘**：左脊 3px 厚边（常态 `--ink-3` / hover `--ink-1` / 活跃 `--seal`）+ 受光缘（上/左各一线）+ 背光缘（下/右各一线）+ 硬接触落影（`--shadow-sheet`，活跃 `--shadow-sheet-active`）；圆角恒 0，影一律取 token。
3. **整数行**：脊高 = 8px 内距 + N × 栏距；N = `spineWantRows`（3/4/5/6 档，按题名权重）× `allocSpineRows`（列高不够**按行降档**，下限 3 行，不是按比例压缩——旧案四档减内距后是 2.67/3.28/4.10/5.13 行，末行半空或半切）。书缝 6px（块块独立）；列内滚 + 右缘 2px 位置条。
4. **题签**：脊身上另贴一枚亮纸（`--paper` + 同一套受光/背光缘）——两种纸同屏，层次靠纸不靠框。题签宽 39px = 2 × 栏距（恰两栏；42px 会露半截第三栏，比截断更难看）。
5. **脊内三枚小标**（档号 / 枝 / 运行点）全走绝对层，不吃流水高度（档号进流水会在降档时先挤掉题名）。
6. **截字 + 省略号**由 `fitLabel` 给（容量 = 2 栏 × 行数；竖排溢出在块轴上，`text-overflow: ellipsis` 不产省略号）。「案卷」= **虚线扣**（`--rule-dashed`，hover 转石青）。
7. **书口档 = 默认形态（2026-09-21 用户拍板）**：`planSpines` 只做一件事——**活跃卷整脊**（自然 3–6 行），**其余全部 32px 书口**一条；一列装不下才交给列内滚。**书口写题名不写编号**（用户口径：「编号写了跟没写一样」）：横排两行 + 省略号（约 6 字，容量与旧 3 行档的竖排 2 栏 × 3 行**同为 6 格** ⇒ 认卷能力不降），运行点 / 枝 留在左标栏，活跃卷永不书口化。病史：四批曾是「自然档 → 降档档 → 书口档」三步（书口只在装不下时出现），用户实机看过后要求改成默认——他要的是「一列里只有正在读的那本整着」这个**稳定形态**；随之退役的是四批那套「列高够几行」分配器与 `.sr-list` 上的 ResizeObserver（判据从「装得下吗」变成「谁在活跃」）。`--thin-h` = 32 是 TS `SPINE_THIN_H` 的镜像，改必同改。
8. **热区 = 整块板**：`.sr-rack` 的 `pointer-events` 是 **`auto`**（旧值 `none` 是「无底散块」时代的遗物）。列已是不透明整块板 ⇒ 画布在它下面看不见，让事件穿过去只剩害处：书缝 6px 与四周内距带成了不可命中的真空，滚轮落在那儿不滚列、反去平移/缩放画布（实机读作「滚动失灵」；实测台 `prototype/_probe-wheel.mjs`：脊上滚 0→300 ✓、书缝上滚 0→0 ✗，改 `auto` 后三处皆滚）。
9. **左缘缘滚：列的板面算画布，脊块与小卡算瞄准面（2026-09-22 左缘批）**：契约 8 的连带代价——整块板可命中之后，贴屏最左命中的由**画布**变成了**列板面**，而左缘感应带（36px）整条压在列内（列 [0,72]）⇒ 左缘在用户视角里等于没有边缘滚动（用户报「边缘滚动的左侧边缘失灵了，估计是和新的书脊栏逻辑冲突了」）。判据落在 `edge-scroll.ts`：列进 `HOVER_ALLOW_DOCKS`（`.pp-toc, .sr-rack`），**脊块 `.sr-spine-main`（点=定位 / 拖=落位 / hover=出小卡）与 hover 小卡 `.sr-card` 进 `HOVER_EXCLUDE`**——即「**列的板面与书缝是地图，脊块与小卡是瞄准面**」（同目次带卡片口径）。最左 6px 内距带正是「指针甩到屏左」被屏缘钉住的落点，故它是这条契约的落点判据；展开态案卷侧栏是宽面板（240–420px），**不**在列（悬停其上照滚 = 跟随相机，见 §13）。实机取证：`prototype/_probe-edge-left.mjs --stim`（2560×1400、rAF 101fps、带外噪声地板恒 0）——修前 x=2/5（内距带）Δ=0，修后 Δ=+909/+1164；x=20/40（脊块/题签）两态恒 0（瞄准面口径）；同刻右缘跑道 Δ=−958、上缘 Δ=+1032（阳性对照）。

定值：栏宽 **72** = 左内距 6 + 脊宽 **63** + 右内距 3；脊宽 63 = 脊边 3 + 标栏 15 + 题签 39 + 右内距 6（改必同改 `SpineRack.tsx` 与 `tests/paper-c8-spine.test.tsx`）。走查记录：`prototype/spine-craft.NOTES.md`（三批：`spine-redesign.NOTES.md`、`spine-fix.NOTES.md`、`spine-ab.NOTES.md`）。

## 11. 层次法（2026-09-01 立法 · 三轴模型）

来源：全面审计批（生图 mockup 对照 + CDP 全面截图取证，`D:\tmp\ui-audit\`）。层次感的本质 = **让「上面」变得可信**。三根轴朝同一答案发力，只动其一皆塌：**海拔**（谁浮在上面→光影）、**包含**（谁属于谁→线）、**轻重**（谁重要→墨）。

**海拔轴**——梯子全产品四档，token 取值禁散写：

| 档 | 东西 | z-index（§8 立宪） | 影 | 要求 |
|---|---|---|---|---|
| 地面 | 画布/纸/首页 | — | 零投影 | 多数元素住这里 |
| 面板架 | 坞面板根/书脊架**容器**/案卷侧栏 | 280/281/282（`--z-paper-base/rack/sidebar`） | 零投影 | 面板级骨架，恒在地面上、浮起件下（2026-09-01 海拔批补立） |
| 纸内件（**流内排印件**） | 流内未钉住的块 | 纸内 10-60 | 无投影 | 靠遮挡+界栏线+选中线表达 |
| 纸片件（**离开流、躺在桌面上**） | **钉住块 / 纸条 / 签 / 书脊块** | 纸内 10-60 | `--shadow-sheet` 硬偏移族 | 一张纸压在另一张纸上；大尺寸（720px 级）另配纹 + 四层包边（见下尺度通则） |

> **纸内件无投影**一行是**回归**过的判例：2026-09-05 pin-strip-rework 批把钉住块/纸条当「小号的纸」做（流区四层包边的缩放版 + 接触落影），与本行冲突且实机读不出层次（同色纸放同色桌面，影成了唯一线索 = 「万物皆浮」）；**2026-09-19 便条批**把影收回给流区独占，纸内件改靠**纸色差 + 白边 + 规线**表达（三分材质：桌面有纹 / 流区有纹的纸 / 便条实色无纹）。
>
> **2026-09-23 质感批（用户拍板「图版 + 纹 + 包边 + 落影」）——本行二分**：09-19 的「实色无纹 + 贴平」被推翻，理由是它治错了病——纹理不是干扰而是**质感来源**，而「贴平」让钉住块既不是排印件也不是物件（三轮台子实测：五案对比度全等 1.11 ⇒ 物性来自线与结构、与明度无关；去掉桌面纹理后现状仍读不出边界 ⇒ 色差路线天花板只 1.187）。**钉住块/纸条/签/脊块 = 纸片件**（已离开流、躺在桌面上），适用 `--shadow-sheet` 硬偏移族 + 纹 + 包边；**流内未钉住的块仍是纸内件**，无投影。拖拽携带态照旧用 `--elev-raise` 压印族（§11 规则① 已列「拖拽幽灵」）。取证与判读件：`prototype/pin-texture-ab.html` / `pin-species-ab.html` / `pin-edge-ab.html`；决定记 `docs/plans/paper-shell/taste-ledger.md` 2026-09-23 条。
| 浮层 | 引/思考/斜杠/翰律/模型菜单/状态线下拉 | 45-90 | `--elev-menu` | 必须盖住内容 |
| 模态 | 设置/命令面板/媒体预览 | veil + 400/401/520 | `--elev-raise` + veil | veil 必配（媒体预览加墨幕） |

> **书脊块判例（2026-09-21 四批，勿再归档错）**：书脊**列容器**是面板架档（零投影），但**脊块本身是纸片件**。二批把整列一并按「面板架 = 禁框禁影」办，删掉虚线扣 / 脊块底与脊边 / 活跃影三件语汇，实机判「又平又简陋，设计不存在了」（§12.1）。另有一条**尺度通则**：纸片件在**小尺度**（<100px）上用「有方向的线」表达纸缘（受光缘上/左 + 背光缘下/右 + 硬接触落影 `--shadow-sheet` 族，配一条厚脊边）；`.pp-region` 那套大面积四层包边（3–7px 渐变带宽 + 裱边带）是给 720px 流区定的，缩到 60px 读成一片糊（同批台架实测）——**大尺寸用纸，小尺寸用线**。
>
> **720px 级补记（2026-09-23 质感批）**：钉住块与流区同宽（720px），所以它适用的是**大尺寸那套**——sheet 细纹 + 四层包边 + 单线框 + `--shadow-sheet` 落影（纸条 480px 同套）。这正是 09-19 那批取错档的地方：它按「便条」的隐喻给钉住块剥掉了纸的一切，而钉住块的尺寸从来就不是便条。

规则：① 影分两族按材质隐喻取用（2026-09-01 海拔批修法）——纸片件（模态体/主钮/浮钮/拖拽幽灵/Toast）用压印族 `--elev-raise`（letterpress `2px 3px`，左上光，方向乱则层次死），悬浮面板（下拉/菜单/命令面板）用漫射族 `--elev-menu`（离纸环境软影）；两族之外禁第三种影子 ② 浮层必须盖住内容才配海拔——什么都不盖的回地面 ③ 模态必配 veil（「下面还在但退后了」）④ 档间差必须可见（浮层与模态不可同脸），差在 veil/z/线，不靠影的大小。全局瞬时层（Toast/拖拽幽灵）住 `--z-dialog` 520 带、纹理层 `--z-grain` 之下。

**包含轴**——线是结构语言，分级使用禁倒挂：版框双线（`--rule-frame`，页缘/流区叶框）> 硬线（`--rule-hard`，浸墨③三处）> 强线（`--rule-strong`，界栏）> 弱线（`--rule-soft`，同层细分隔）> 虚线（`--rule-dashed`，草稿/占位）。小事绝不用重线。头线（`--rule-head`，2px ink-2 浮层菜单书眉顶缘——ms-dropdown/sl-log）与语义缘不入分级序列，属判例件。

**嵌套语法**（2026-09-01 包含批立）：① 线随包含级数递减——页面级容器版框/硬线，面板级强线，卡级弱线，行级发丝（`--line-soft`）；外框级数必须 ≥ 内框，外弱内强=倒挂。② 一个方向至多两层框，第三层用界栏/留白/墨洗表达，不立第三框。③ 语义缘不入线级——选中线（2px 朱砂底线/左脊）与警示缘（warn/fail/indigo/pass 左缘 2px）是状态语汇，每件至多一条。④ **泛选择器框禁令**：`XX button` 类泛框必泄漏进嵌套组件（实锤：`.pp-composer button` 强线泛框曾把模型菜单条目全框成卡中卡，特异性压过 `.ms-item` 三边 none）——按钮样式各钮自带，不立泛框。

**轻重轴**——墨阶四档（§3）+ 字重极端（§10 法则 2）+ 语义铁律（朱砂=人/石青=机/石墨=夹注）。上层全对比，下层降对比（veil 压暗、淡墨、发丝线）——印刷品的层次从来靠墨量不靠描边。

**选中语言分型**（2026-09-01 审计定案，细化 §10 法则 5）：锚点型选中（tab/分段主动作）= 墨底反白，或重墨 600 + 2px 朱砂底线；行型选中（列表行/菜单项）= `--sel-wash` 墨洗 + 朱砂左脊。全产品只许这两种，禁第三种。

**致死四动作**（审计实锤，见账本 2026-09-01）：万物皆框 / 万物皆浮 / 散写影子 / 混材质（玻璃≠纸）。

**四问清单**（新面板/组件过审用）：在哪一档？z/影/veil 从 token 取了吗？投影方向与光源一致吗？——它盖住了谁？什么都不盖的，回地面去。

## 13. 目次带 v3（2026-09-14 立法：从「滚动条」到「识别面 + 目次」）

**用途排序（用户拍板，优先级即此序）**：① 精确跳到某一轮/阶段 ② 当前滚动位置的连续控制（滚动条语义）③ 一眼扫出「哪里长、哪里有错、哪里是工具密集段」。

**病灶实测**（实机 CDP，2026-09-14；用户当卷 = 289 刻痕 / 带高 1096px）：289 枚刻痕全做成 button 命中盒（10×8）——tool 刻痕 255 枚把 18 枚阶段锚挤进**平均 3.8px 间距**，命中盒相互叠压、DOM 后渲染者胜：**点自己那枚的比例 7.3%**（268/289 被相邻刻痕盖住），用户读作「刻痕点不中」；289 个 tab 停靠点同样是键盘灾难。另一头：刻痕盒 `top = stripY − 4` 会顶进书眉（＝窗口标题栏，`-webkit-app-region: drag`）拖动带，那 4px 命中归标题栏＝拖窗口（**书眉已于 2026-09-17 整条退役，见 §14**）。

**四层职责分离**（甲，2026-09-14 落地 `b774f4c1`）：

| 层 | 是什么 | 鼠标语义 |
|---|---|---|
| 可点层 | **阶段锚**（朱砂横规；28px 命中盒 ≥ 热区纪律 24px；盒宽只占左缘栏 26px） | 带内**唯一可点目标**——点击 = 飞到该阶段首块；按下锚不启动 scrub |
| 装饰层 | 语义刻痕（tool/plan/error 全部 + 无阶段单元的用户块）：惰性 div + `aria-hidden` + `pointer-events:none` | **不可点**——点它 = 点带空白 = 按位置 scrub（纯扫读信号） |
| 控制层 | 滑块 + 带空白处（VSCode 语义：拖拽 scrub / 点外即跳对中心；夹紧域 = 可见视口） | 连续控制 |
| 识别层 | canvas 墨迹缩略（**乙，待定档**） | 不参与命中 |

两条硬约束：**命中盒与 hover 卡同源**（卡片所示即点击命中——① 锚盒内「阶段 N · 首句」② 贴着装饰刻痕读那枚并提墨一档 ③ 行盒原文）；**映射区永不与顶部家具重叠**——2026-09-14 二报「还是打架」后曾改**结构性修法**：带体 `top: var(--bar-h)` 从书眉下缘起（与标题栏零像素重叠）；**2026-09-17 书眉退役后该下移取消**——带体回到 `top: 0`（屏顶通栏，带体坐标 = 页面坐标），带内一切元素——刻痕盒 / 阶段锚盒（`anchorBoxTop` 贴顶夹紧）/ 滑块 / 未读区 / hover 卡（`cardAnchorFor` 贴顶翻转）——**恒 top ≥ 0**（不越出带体仍是自持纪律；映射区顶 = 刻痕半高 `STRIP_TOP = MARK_HALF`）。

**2026-09-19 加宽批 + 同日甲案（边缘滚动落地之后的误触根治）**：**病灶**——边缘滚动的**右缘感应带**（基准 36px，贴屏最右）正落在目次带上，而带体只 64px 宽 ⇒ 带内几乎处处是感应带：「用带导航」与「贴右缘缘滚」抢同一条带，互为误触（带上的 hover 卡与点带即跳都会在缘滚时被顺手触发）。**裁定（用户「由于边缘滚动的落地，我需要再次加宽我的目次带，因为会有误触的问题」）**：带体 **64 → 104px = 控制列 64 + 缘滚跑道 40**——**控制列**（`.pp-toc-col`，宽度与旧带体**逐字同 64px** ⇒ 刻痕 / 阶段锚 / 滑块 / hover 卡**零漂移**）承载**全部可交互面**；带体右 40px 是**缘滚跑道**（`TOC_RUNWAY_W` ≥ 基准带宽；灵敏度拉满时带宽 ≈51px，只吃掉控制列右缘的 scrub 余量——锚/刻痕只占左 26px，**任何档位都不在感应带内**）。**跑道本体惰性**：无 handler、光标默认、点击只被吞掉（不吞就点穿到纸上划词），而悬停照旧算画布 ⇒ 贴屏最右照旧缘滚（`edge-scroll.ts` 的 `HOVER_ALLOW_DOCKS`）。**同一判据的另一半在左缘**（2026-09-22 左缘批）：书脊列 [0,72] 压住左带 [0,36] ⇒ 列的板面与书缝照算画布、脊块与 hover 小卡豁免（§12.1 契约 9）。

**同日甲案（⚠ 2026-09-21 更正归因：此案系 agent 自提，用户从未拍板）**：首版把**识别层也钉在 64px**（图「零漂移」），实机像素量下来带体 105px、墨迹只到 48px ⇒ 右边 57px 读作「带子空了一半」；**改：识别层（墨迹 canvas / 未读区 / 活线）按带体满宽铺**——画布 `clientWidth` 104 ⇒ 剪影横向 ×1.625（48 → ~78px，扫读更清；三者都是 `pointer-events:none` 的纯识别面）。**识别层铺满保留（仍属待用户验收项）**；**该案原附的一道界栏线**（`.pp-toc::after`，`left` = 控制列宽、比带体左缘弱线再淡一档、不吃指针；当初理由 =「看着能点其实不能」是误触的另一面）**已于 2026-09-21 整条摘除**——用户「我从来也没拍板过界栏线」，且该线**零功能**（跑道惰性由组件 `insideCol` 判据决定，与线无关），届时的「用户拍板」措辞属记录失实（更正见 `../plans/paper-shell/taste-ledger.md` 2026-09-21 条）。

**连带与钉值**：顶部浮件右距 80 → **120px**（= 带宽 + 16）。`tests/stage4-toc-top-band.test.tsx` 加宽批两例（几何：组件常量 ↔ CSS ↔ 算术三处同源 + 跑道 ≥ 感应带 + 拉满灵敏度不碰控制件 + **CSS 里不得再有 `.pp-toc::after`**（2026-09-21 摘线后改为反向钉值）；行为：跑道按下不 scrub、不弹卡，控制列照旧）+ 结构断言（墨迹画布是带体子件、不在控制列里——甲案那半的考官）。

**标题栏交互（2026-09-14 三报立法：app-region 全面退役）**：顶部家具/首页顶栏不再声明 `-webkit-app-region`——Windows 下 WebView2 把拖动区**光栅化成一叠薄子窗且只在启动那一刻按当时页面算一次**（启动落在首页 → 按首页 ~88px 的顶栏算），进画布后既多出一条「幽灵标题栏」压在画布顶缘/目次带最上方（拖内容＝挪窗口），又按首页布局吃掉书眉按钮。现在**命中范围由元素自己判定**：`src/app/window-drag.ts`（单一真源）接 pointerdown → Tauri 原生 `start_dragging` / 双击 → `toggle_maximize`，交互件豁免；壳层另有兜底（`src-tauri/src/window_drag_band.rs`：caption 一律降为 client）。2026-09-17 起画布视图的热区 = 顶部浮件本身（书眉退役，见 §14）。**2026-09-18 双击判据修正**：`start_dragging` 是 OS 模态移动循环，第一下就把这一击的 mouseup 吃掉 ⇒ DOM `dblclick` 在 WebView2 上**一次都不产生**；双击改由 `pointerdown` 自数（同点位 ±6px + 450ms 窗口内的第二下，且第二下不进拖动循环），`onDoubleClick` 只作「页面收得到 dblclick 的平台」的同一对点击去重兜底。

**识别层（乙）的物理下限与四个正交通道**：带内缩放比常在 0.005–0.012（长卷 10 万世界 px → 528px 带），此比例下正文 15px 字 = **0.08–0.18px 高**——真字形必然不可辨（v2 退回 bar 的原始理由，见页面原型对照栏）。能携带信息的只有四个**正交**通道，各自的值由原型逐案实测（`prototype/toc-thumb-ab.html`，不入库）：

1. **形状**（行宽剪影）：空行率 0.39→0、墨覆盖 0.44→0.77，与基线 α 差 0.35；
2. **族色**（人=朱砂 / 正文最重 / 程文与工具=石青 / 图表最轻 / 错=`--fail`）：与形状案同形，rgb 差 0.086；
3. **族纹**（表=横纹 / 码=细横 / 图=点阵 / 工具=斜纹）：墨覆盖 0.77→0.68，α 差 0.21–0.32——**不靠色也分得出族**（灰度/打印成立）；
4. **墨量**（形 + 深浅双通道）：α 差 0.05–0.12——答「哪里长／哪里密」。

**淘汰案（同一把尺子判死，勿复活）**：*缩进剪影*——缩进 19 世界 px 在带内 0.2–0.6px，与形状案像素差 0.001（等于没画）；*阶段分带*——阶段界已由可点层承担，缩略里再画一遍与形状案差 0.003（纯重复）。**通则：凡小于带内 1px 的世界结构（缩进、块间留白、单行折行）一律不可辨**——识别层的设计尺度以此为准。

**现状**：甲已落地（`b774f4c1`）；**乙已落地（同日，用户拍板 F ＝ 形状 + 墨量 + 族色 + 错）**——纯层 `paper/toc-ink.ts`（`buildTocInkBuckets`：桶高 3px、alpha = 0.18 + 0.82×√(桶内墨面积/全带最大)、a 桶内最宽行定宽并定族色、错旗另立 `--fail` 4px 短规），组件只负责把桶画出来（族色走 `inkBarColorOf`、错走 `INK_FAIL`——canvas 取不到 CSS 变量，故 `--fail` 在 `paper/ink.ts` 有字面量镜像）。钉值 `tests/stage4-toc-ink-layer.test.ts`（8 例，含**差分断言**：同一份数据下 v2 规则覆盖 9%、新算法 ≥80%；算法退化即红）。**族纹（D）未采纳**——留作灰度/打印场景的后备通道；v2 的块级降级阈值（`DENSITY_BLOCKS`）随本批拆除。

**v4（2026-10-20 · agent 提案，待用户验收）**：用户一句「目次带还是太简陋」触发的观感迭代，三件：
① **两栏**：识别层从 104 收回**右 40**（= 缘滚跑道），左 64 全给目次栏。**这是对 2026-09-21「识别层铺满保留」的翻案**——铺满不是唯一解：长卷（90 屏）里 104px 满宽墨迹读作一堵墙，而空出来的左 64 没有信息；收回后由**编号**填那半，带体不再「空了一半」。
② **编号**：每枚阶段锚一枚 mono `9px × font-scale` 数字（x=36），自适应省号（与上一枚已显示编号落差 <12px 就省；当前阶段恒显示、朱砂加粗 + 脊上 3px 方点）；编号 `aria-hidden`（锚的 aria-label 已报阶段序）。
③ **纸捻**：不透明纸底（左 `--paper` → 右 `paper-deep 78%`）+ 左缘 `--rule-strong` 硬边 + 2px 受光/背光缘 + 10px 内影 + **自带纸纹**（`::before` 四层配方，同书脊列）；1px 竖脊（x=14）+ 上下端规；滑块 = 只留上下两条朱规的纸窗 + 右缘 2px 纸捻抓手（hover 24 / 拖动 28）；hover 卡 = **268px 定宽** + eyebrow（阶段 N / 工具 / 正文…）+ 2px 语色条 + 右缘缺口，翻转阈 96。
**同批修的 bug**：hover 卡旧规则 `max-width: 260` + `right: calc(100% + 10px)` 在 64px 控制列里算出**负可用宽**，shrink-to-fit 实测 **36.1×249.1**（一列竖排的字）——现定宽 268 + border-box。
**剪影画法（取代上一段参数）**：右对齐贴屏幕缘、参差朝向栏；族色染整桶但按族增益（人 1 / 工具程文 0.62 / 图表 0.42），墨量 = `0.2 + 0.8 × density`；错仍 4px `--fail` 短规；**不留页层缝**（2px 条 + 1px 缝在 1x 是扫描线噪声，原型实测）。
**刻意不做**：任何「控制列 / 跑道」分界线（2026-09-21 摘线判例照旧；墨影自己的左缘就是界）；hover 卡不越出带体左侧（仍左出，不盖编号）。
**钉值**：`tests/stage4-toc-v4.test.tsx` 6 例（卡定宽回归 / 两栏 / 编号自适应 + active / 卡片语色 / 纸窗抓手 / 骨架惰性）+ `stage4-toc-ink-layer` 的 `density` 例；`stage4-toc-top-band` 的加宽/跑道/摘线例**逐字未动**（几何与裸行为零漂移）。
**交付口径**：组件（`compose-dock`）可热更；CSS（`PaperPanel.css`）在壳 bundle ⇒ 真机见新样式须 `cargo tauri build --no-bundle`（landmine H2）。

**v4.1 实机修订（2026-10-20，用户真机测试三条反馈）**：
① **「墨影并不存在」**——canvas 是 **replaced element**：CSS `width: auto` 会用**固有宽**（canvas 默认 300），不是解 left/right；组件按 `clientWidth = 300` 右对齐画，墨影整条落到屏外。**修**：`.pp-toc-ink` 给死宽 `40px`（`TOC_W − TOC_COL_W`），不再用 `width:auto`。钉值：v4 用例断言 CSS 含 `width: 40px` 且**不含** `width: auto`。
② **「纸捻材质没生效，纯色底」**——canvas 态下 `foundation.css` 把文档级 grain 隐去（`body:has(.pp-root)`），首版只给了 48% 渐变 + 1px 缘，实机就是一块平色。**修**：纸口明度拉到 78% paper-deep + 2px 受光/背光 + 10px 内影 + **`::before` 四层纸纹**（与书脊列同一配方；`z-index:-1` 在底色之上、子件之下，不是界栏线）。
③ **「目次字样拿掉」+「顶部也留空隙」**——带脚竖排「目次」小签整条摘除（CSS/DOM 双删）；映射区顶 `STRIP_TOP` 由 4 抬到 **56**（= 顶部浮件带高 8+40+8），与底（坞顶线）对称留白；刻痕盒顶随之 = 52。钉值：v4 用例断言无 `.pp-toc-colophon`，`stage4-toc-top-band` 改钉 `STRIP_TOP === TOP_CHROME_BAND`（56）与 `STRIP_TOP − MARK_HALF === 52`。

## 14. 顶部浮件（2026-09-17 标题栏拆除批）

**病灶（用户实机，边缘滚动落地之后）**：「书眉整条是 56px **布局行**」——它把画布顶缘从窗口顶推开 ⇒ 边缘滚动最自然的动作（**把指针甩到屏顶**）永远落在书眉上：悬停档判据要求指针落在画布内（`hoverEdgeEligible`），屏顶那 56px 不是画布，一律否掉；拖块贴顶同此（越出画布封顶也只到 56）。**上缘在用户视角里等于没有边缘滚动**——这不是带宽/灵敏度问题，是布局问题。

**裁定（用户「按钮从标题栏挪出来，然后把标题栏删了」）**：书眉布局行**整条退役**，控制件落成右上**一枚浮件**（`.pp-chrome`）。

| 项 | 定案 |
|---|---|
| 画布 | 铺满整窗（`.pp-canvas` 独占 `.pp-root` 的 flex 列）——**顶缘 = 屏缘**，四缘感应带对称 |
| 浮件内容 | `画布`（抓手）+ 缩放 −/读数/＋ + 状态字（StatusLine）+ 设置 + 回首页 + 窗口钮（WinControls）——**搬家不是删除**，相对次序与旧书眉一致 |
| 落位 | `top: 8px; height: 40px; right: 120px`（= 目次带宽 104 + 16 呼吸；带宽 2026-09-19 由 64 加宽，见 §13）；**带高 56 = 8 + 40 + 8 呼吸**，坞上夹紧与小地图默认位同此值（TS 镜像 `COMPOSER_CHROME_H` / `TOP_CHROME_H`） |
| 宽度 | 随内容浮动（右对齐）——状态字在本批同批收窄（`.pp-chrome .sl-chip` 上限 320 → 220px，全文照旧可点开读）；典型宽约 470px，最长约 560px。**顶缘感应带只在浮件占位那段 x 区间失效**，其余整条可滚 |
| 语言 | 纸底 + `--rule-soft` + `--elev-raise`；**不透明**（半透明会让画布正文与浮件文字互相糊字，同 §10 纸层次与「坞底 / HUD 化」诊断）；**常显**，不做悬停揭示（揭示区与命中区一分开就互为前提，先例＝拖动锁一版） |
| 层级 | 覆盖件（`.pp-canvas` 的**兄弟**，不进布局流；**不是画布 DOM**——故悬停其上不滚，同目次带之外的覆盖件口径），z 30（旧书眉同档） |
| 窗口拖动 | 热区 = 浮件本身（非交互件即 `画布` 二字与件间空白），走 `app/window-drag.ts` 原生通道；画布视图**不再留整条拖动带**（否则又变成「屏顶不能滚」）。首页顶栏 `.sh-head` **保留**（首页不是画布，无「顶缘即屏缘」诉求） |

**连带（几何同一批收口）**：目次带 `top: var(--bar-h)` → `top: 0`（带体坐标 = 页面坐标，`TOC_TOP = 0`）；书脊架 `.sr-rack` / 案卷侧栏 `.ss-sidebar` 的 `top: var(--bar-h)` → `0`（左缘整列多出 56px）；一次性眉批 `.pp-hint-canvas` 从「书眉下缘 + 20」上提到「屏顶 + 20」；`tokens.css` 的 `--bar-h` **删除**（已无消费面）。**几何刻意留在产地域**（`.pp-chrome` / `.pp-toc` 的数值在插件 CSS 里）：tokens.css 属壳域（`main.ts` 打进 bundle），改它必须重建 exe，而本批要的是「只换产物热更」（`docs/dev-workflow.md`）。

**已知边界（刻意不做）**：① 浮件本体之上的悬停**不滚**（它是「别的面」）——故顶缘感应在浮件占位的那段 x 区间里不可用；若日后要「浮件背后照滚」，把 `.pp-chrome` 加进 `HOVER_ALLOW_DOCKS` 即可（三行，判据已就位）。② 目次带（右缘）与案卷侧栏（左缘）本就压着左右感应带，各自的口径见 §13 与 `edge-scroll.ts`。③ 坞顶仍不得进浮件带（上夹紧 56）——浮件在右上，坞压上去会把窗口钮（decorations:false 下唯一关闭入口）盖死。

**钉值**：`tests/stage4-toc-top-band.test.tsx`（带体从屏顶起 + 浮件几何四处同源：CSS `8/40/80/64` ↔ 两处 TS 镜像 56 ↔ 测试基准）；`tests/paper-viewport-ux.test.tsx` +3（结构：书眉不存 / 浮件是画布兄弟 / 控制件一件不少；行为：屏顶那 36px 落画布上滚 vs 同一姿态落浮件上不滚；浮件抓手拖窗口而按钮不吃拖窗口、双击最大化）；`tests/edge-scroll.test.ts`（判据树照真机结构加 `.pp-chrome` 兄弟项 + 新增「上缘感应带在屏顶」用例）；`tests/titlebar-drag-region.test.ts`（`pp-topbar` 零声明 + 浮件接共享实现）；`paper-visual-decisions`（墨阶锚点：画布书眉底线退役，浮件走弱线）。

## 15. 动效法（2026-10-15 立法 · 用户拍板烈度「乙 · 纸感」）

**病灶（用户：「整个软件的交互充斥着各种跳变」）**：动效词汇其实不少（225 处 transition/animation、13 组 keyframes），但它们是**逐案打补丁长出来的**——同一种动作（浮层递出）在六个文件里写成 0.14/0.15/0.16/0.18/0.24s 五个值；`--pp-grow-dur` / `--pp-grow-ease` **全仓从无声明**只剩 fallback 字面量；相机飞行的 240 在同一个文件里写了两遍。补一处漏十处。更根本的是词汇表**偏科**：只有「入场」没有「退场」，只有「墨」（显形）没有「纸」（让位）——而**最大的跳感来自让位**：让位过渡原只挂在 `.pp-stream-live`（任一卷在跑）上，于是 Agent 写字时块会滑，**用户自己**展开折叠行/摊开图版/改流区宽时，下方块一次性瞬移（一次点击整个下半屏跳一下）。

**两轴分家（禁混用）**：**态变轴** `--snap`(0.12s) = 同一物件换状态（hover/focus/选中/禁用），只换颜色与描边、零位移、短到读作「即时回执」——**它不是动效**，别拿它做过场。**动用轴** `--m-*` = 物件出现/消失/移动/换景，用户读得见的一段过程。

**三条物理律**（材料只有墨与纸，故律从材料来，不抄通用 UI 缓动）：

| 律 | 判据 | 先例 |
|---|---|---|
| **墨律**（显形） | 内容出现 = 墨落纸：淡入 + 微升 8px，**不回弹**（墨不弹） | `.pp-enter` / `.pp-ink-enter` |
| **纸律**（让位） | 物件移动 = 纸被推：**只动 transform，绝不动 left/top/height**；**不过冲**（过冲只留给「拿起」一个动作） | `.pp-region-active` 影三档 |
| **手律**（跟手） | **手指直接驱动的动作零缓动 1:1**；缓动只属「系统替用户做」的动作 | `paper/sel-ink.ts`「手感来自微伏不来自粗细」 |

**三档 + 两曲线**（真源 `tokens.css`，禁再散写时长/bezier）：

| token | 值 | 用在 | 距离律 |
|---|---|---|---|
| `--m-ink` | 0.16s | 显形/隐没：弹层、浮件、折叠、单件登场退场 | 位移 ≤8px 或单件显隐 |
| `--m-sheet` | 0.26s | 让位/开合：块被推开、容器涨缩、影换档 | 容器尺寸/位置变化 |
| `--m-scene` | 0.38s | 换景：首页↔画布 / 页签 / 侧栏↔书脊 | 整层替换 |
| `--m-ease-out` / `--m-ease-io` | 出相 / 对开 | 前者＝纸的惯性（快起慢收）；后者＝开合两端都交待 | — |

> **曲线选型的判据（2026-10-15 批 3 应用法时补）**：`--m-ease-io`（两端都交待）是给**两侧同时动**的过场备的——View Transition 的旧快照与新快照同框位移就属此类；**单侧登场**（一个模态/面板自己从无到有）要用 `--m-ease-out` 档（`--m-ink` / `--m-sheet` 已内含），io 曲线在入场开头会**钝住**。故「换景」不等于一律 `--m-scene`：看是一侧动还是两侧动。

**约束律**：① 一次动作至多一个动效主体；② 动效永不阻塞交互（动画只描述，不延迟可点）；③ **一切动效走 CSS animation/transition**——唯一豁免点 = `foundation.css` 的 `prefers-reduced-motion` 块；**JS 帧动画要么删、要么自觉读 `matchMedia`**（先例：相机飞行 `use-paper-focus.ts` 的 rAF 原本绕过该豁免——动效敏感用户唯一还在动的恰好是幅度最大的那个动作）。

**登记表（不受三档约束，但新增必须登记）**：**仪式** = 首页钤印 `sh-stamp` / 列表升起 `sh-rise` / 卷首朱笔划界 `pp-seal-draw`；**环境** = 画布呼吸线 `pp-breathe`、运行态呼吸 `pp-ink-live`、侧栏/书脊运行点 `ss-breathe` `sr-breathe`；**信号** = 探测中 `pp-pulse`、加载旋 `pp-spin` `ms-spin`、溯源一拍 `pp-trace-pulse`、更新条 `sp-upd-slide`；**存活期** = 一次性眉批 `pp-hint-fade`(6s)；**连续读数件** = 墨量线/进度段 `transition: width`、状态点纸晕 `transition: background`。

**本批落地（2026-10-15 批 1）**：① 三档立法 + `--glide` 退役（改名即删，不留双轨）——全仓**散写时长**收编为三档 token、**散写贝塞尔**收编为具名曲线（`--m-ease-out` 由此有了消费面）；② **让位过渡常驻**（落在 `.pp-block` 基座内，非另立高特异度规则——后者会触发 biome `noDescendingSpecificity`）；手驱动例外走新类 `pp-live-hand`（壳层按 `edgeDragPos || regionCornerPos` 发放）与既有 `.pp-dragging`；③ 悬空 token `--pp-grow-dur/ease` 清除；④ 相机飞行 240→`FOCUS_FLIGHT_MS`(260，镜像 `--m-sheet`) + reduced-motion 短路（两处 rAF 飞行都走）；⑤ `TOAST_FADE_MS` 400→260（与 CSS `--m-sheet` 段同值）。

**用户可见的行为变更（显式声明）**：块首见入场 0.24→0.16s；拿纸过冲 0.4→0.26s；流区影换档 320→260ms；空态入场 0.45→0.26s；贴黄淡出 0.4→0.26s；**让位过渡从「仅流式」扩到「常驻」**（用户自己展开/收起时下方块改为滑走）——这一条是本批的主目标。三条曲线由 CSS 关键字（`ease`/`ease-out`）统一到 `--m-ease-*`。

**批 2 落地（2026-10-15 同日）**：`transition: all` 全仓 19 处改具名属性表——判据是**同元素全部状态变体实际会变的属性并集**（hover / `:active` / `[disabled]` / 状态类如 `.selected` `.testing` `.used`），宁全勿简，故**零行为变化**；唯一例外是设置面板本体，其 `pointer-events` 属**离散**属性——旧写法下按离散动画规则在 50%（60ms）翻转（面板开头那 60ms 点不进去），具名 `opacity` 后立即生效（合 §15 约束律「可点即用」），是**变好**的一处副作用。守护：`motion-contract` 加「禁 `transition: all`」一条。

**批 3 落地（2026-10-15 同日，只做「能干净做对的那一半」）**：修一处**真缺陷**——设置面板 `panel-def` 标 `unmountOnClose`（关即卸载），而 `SettingsPanel.tsx` 首帧就带 `.sp-open` ⇒ 两条 `opacity: 0 → 1` 的过渡**从未运行过一次**（挂载即终态，没有前一个计算值可比）：全应用最大的模态（900×640）是「啪」地出现的。治法 = 起手式交还 **`@starting-style`**（正是为「首帧入场」设计的 API），基座只留唯一终态，`.sp-open` 整层退役（在本件上「开/关两态」是死抽象）；动效升级为开合档（幕布淡入 + 面板自下方 8px 托起归位，**不缩放**——900px 面板缩放要重栅格化其内全部文字）。**这不是一处孤例，是一类缺陷**：`transition` 挂在「随开合卸载/挂载」的元素上 = 声明永不生效；**keyframe 动画不受影响**（挂载即播），命令面板走 `veil-in`/`pop-down` 故一直是对的——两者别混。

**批 3b 落地（2026-10-15 同日）：退场窗 `animateExit`**。`unmountOnClose` 的面关即卸载，出场动画没有落点——故加一条壳层供钩、产物消费的机制：`PanelDef.animateExit` 声明后，`DockPanel` 的相位机（`open → leaving → closed`；**相位在渲染期收敛**，理由与判据见下方 2026-10-16 批）在关闭时先留 **`PANEL_LEAVE_MS`** 的窗，根元素收到 **`[data-panel-leaving]`**，窗满才真卸载——**「关即卸载、重开重置 dirty 态」语义不变**（只是晚一个出场时长）。**默认关**：留一个不播动画的空窗 = 「冻住一帧再消失」，比瞬删更糟。标记层用 `display: contents`（不生成盒子，对既有布局零影响）。三个面已接：**设置面板**（出场 = 入场逆写：幕布淡去 + 面板下沉 8px）、**书脊列 / 案卷侧栏**（出场 = 各自入场起手值的逆写：退到左缘外 12px / 20px 处淡去）——**互斥两态换态此前是「一边滑入、一边凭空消失」，现在两端对称**，这也是 ④换景 里「侧栏↔书脊」那一项的落地（纯 CSS、零 faceDeps）。

> **2026-10-16 补（真机报「侧栏收藏时会产生跳变」·同一法未走完的三处）**：
> **① 主犯 = 相位晚一趟推进 ⇒ 面被拆掉重挂。** `mounted = open || phase === 'leaving'` 在**渲染期**读相位，而相位原只在 `useEffect` 里推进 ⇒ 收面那一趟 `open` 已 false、相位还是 `'open'` ⇒ `return null` **把面拆掉**，effect 随即把它当**新元素**挂回来（入场在退场窗里重播 + 窗满按退场目标一帧到位；组件状态也被重建 = 「重开重置」语义提前执行）。治法 = 相位**渲染期收敛**（React 官方「渲染期修正 state」模式，同组件、幂等收敛），收面与 `[data-panel-leaving]` 落在**同一个 commit**。判据 `tests/dock-panel-leave.test.tsx`（DOM 节点身份 + 真挂载计数，与 CSS/绘制时机无关）。
> **② 入场由 keyframes 改为起手式 + 过渡。** 同一属性上 **keyframes 压过渡**：入场没播完就收（开→40ms→收）时收的请求起不来过渡，面继续滑到 `0/1`，动画一结束再一帧弹到退场目标（台架实测 Δx=−20px/帧）。过渡可被抢占（按**当下值**掉头），故侧栏/书脊的入场改走 `@starting-style`（起手值与旧 keyframes 的 from 帧逐字同值，观感零变化），两条 keyframes 删除。
> **③ 回场方向补过渡。** `transition` 原只写在退场规则里 ⇒ 退场窗内重开时属性摘掉、规则不再匹配 ⇒ 过渡随之消失，面从 `(−20px, 0)` 一帧跳回 `(0, 1)`（实测 Δx=+20px/帧）。现两向逐向写档：入场 `--m-ink` 在基座、出场 `--m-sheet` 在退场规则（`transition` 取**变更后样式**那张表，故两向档不同时必须逐向写）。
> **证据**：`prototype/sidebar-collapse-ab.html` + `sidebar-collapse.probe.mjs`（真 Chrome + 真产物 CSS + 真相位机逐帧）——A 常态收 0 处跳变（改前 2 处）/ B 退场窗内重开回场连续（改前 +20px 一帧）/ C 入场 40ms 处就收：半路掉头滑回（改前「滑到 0 → 弹到 −20」）。

> **一处工程细节记在案**：侧栏/书脊的入场是**起手式 + 过渡**（`@starting-style` 给首帧值 + 基座一条 `transition: … var(--m-ink)`），出场档 `--m-sheet` 写在**退场规则里**——CSS Transitions L1 的起手判据看的是「**变更后**样式」的 `transition-property`，故「加属性同时给 transition + 目标值」成局。设置面板两向同档（`--m-sheet`），transition 在基座一条即可，故它的退场规则只写目标值。
>
> **契约手续（已走完，勿漏）**：`animateExit` 加在 `PanelContribution` + `PanelDef` 两处形状上 ⇒ 触及**开放面契约面**，按 `composition/contract-version.ts` 四步流程**升版 v56 → v57**（同 commit：`PanelContribution` 字段 + 契约清单注释 v57 块 + `docs/agents/open-surface-contract.md` 变更记录一行 + `gen:contract-fingerprint` 新指纹 + `gen:doc-facts` 的 `open_surface_contract_version`）。纯可选字段故**零迁移**（不声明的第三方插件行为逐字不变）——但**手续不走 = `seam-contract-version` guard 红**（指纹粗粒度，注释改动也算）。

**批 3 剩余（有架构约束，先记不做）**：① **纸面折叠体做不了「收起」动画**——块高是 JS 测的（`measure.ts` 折叠态返 `FOLD_ROW_H`），若收起时把 body 留在 DOM 里做高度过渡，测高镜像与实际盒高会错开一整个动画时长，下方块会压上来。故折叠的连续性只能由**让位**表达（批 1 已给：下方块滑走），body 自身的消失仍是同帧；给它补「展开时淡入」是可选微增益，代价是 `ToolBody` 要套一层 wrapper（改 DOM 结构 → 有测高风险），暂不做。② **纸壳（paper 面板）未接 `animateExit`**：它的出场要淡出整张画布，会撞上 `body:has(.pp-root)::after` 的**纹理层瞬时翻转**（见下条坑 ①），故与「首页→画布」同一批处理。

**批 4 的前置约束（先钉清再动手）**：换景若走 View Transitions，helper 要跨产物共享（首页 / 画布 / 侧栏 / 页签分属四个产物）⇒ 必须新增 **faceDeps 宿主面键**。代价是硬的：宿主面是 exe 侧契约，loader 有**产物/exe 偏斜拒绝装载**的守卫（`plugins/loader.ts`）——**触及 faceDeps 的批次不能再「只换产物热更」，必须与 exe 同源重建**。
> **2026-10-15 批 3b 后的重新评估**：**VT 不是必需**。换景的四个case里「侧栏↔书脊」已用 `animateExit` + 纯 CSS 逆写解决（零 faceDeps）；「设置页签」与「首页↔画布」都是**单侧登场**（页签内容 `display:none` 互斥、画布/首页是覆盖关系），用 `@starting-style`（+ 需要退场时 `transition-behavior: allow-discrete`）即可，同样零 faceDeps。VT 独有的价值只剩「**同一元素跨状态 morph**」（侧栏那张板真的变成书脊那张板）与两侧同时位移——那是**锦上添花，不是治跳变**。故裁定：**换景先走纯 CSS 路线，VT 留作可选抛光**；真要用 VT 时再评估 faceDeps 的 exe 重建代价。

**「首页→画布」的候选做法与坑（**本轮实测后升级为「须先裁定再动手」，勿盲写**）**：该处现在是**硬切**——首页 `position: fixed; z 30` 永不卸载，纸壳 `z 280` 直接盖上去（`PaperPanel` 是 `unmountOnClose`，故纸壳确实**每次开都新挂载**，`@starting-style` 对它有效）。**载体只能选 `.pp-root`（或 `.pp-canvas`），不能选 `.pp-region`**：流区在虚拟化里会随视口卸载/重挂（`visibleRegionIds`），给它挂首帧入场 = 平移时纸面反复「凭空浮现」。坑：全屏元素的 `transform/scale` 会重栅格化纸纹与正文（位移要走独立 `translate` 属性，先例 `.pp-enter`）。

> ⚠ **为什么本轮没落（新证据，比上一轮记的更硬）**：难处**不是「纹理层翻转得不是时候」，而是那两层压根在纸壳之上**——`body::after`（颗粒×纤维）z = `--z-grain` = **9998**、`body::before`（顶光+边沉，非画布态还叠 `--laid-lines` 帘纹）z = 9997，**都盖在 `.pp-root`（280）上面**。推论：**它们的退役/复归在任何时刻都是可见变化**，与「等纸壳淡入完了再翻」的时序技巧无关（等完再翻 = 动画结束后整屏闪一下，比现在更糟）。所以两条都得**可淡入淡出**才行，而 `::before` 上的帘纹是写在 `background` 简写里的**整条列表切换**（非画布态 `--laid-lines, --light-fall, --vignette` ↔ 画布态 `--light-fall, --vignette`），`background` 列表之间不可插值 ⇒ 要淡就得**拆层**（把帘纹挪到第三个层，如 `html::before`）。而这两个选择器被 `paper-visual-decisions.test.ts` 用约 15 条断言钉着（含「画布态退役」「模态豁免两块」「同配方三处」），拆层 = 一次**大规格变更 + 视觉不变量重排**，而我在这里**看不到画面**。
>
> **下一轮的正确起步**：先裁定要不要动纹理层架构（这是**产品/架构取舍**，不是纯工程）——甲：按上面的拆层方案做（可淡出，代价 = 动 15 条钉值 + 平移期帧率须实测）；乙：不动纹理层，走**「纸落桌」**（`@starting-style` 给 `opacity: .6 + translate: 0 6px` 落定到 `1 / 0`；不从 0 淡入 ⇒ 首页被照亮的窗口极短、纹理翻转几不可见）；丙：维持硬切，把力气花在别处。**三案都要实机看，故本轮不做**——本条已是「可施工状态」，只差一个裁定。

**实机验收项（本批唯一带不确定性的改动，明说不藏）**：让位过渡常驻后，**非流式的布局重算**也会走 0.26s 滑移。其中一类是**块高实测回写**——`needsObservedHeight` 的块（markdown 含表 / 图版 / 拟策 / 引用）挂载后由 ResizeObserver 报真高、布局二次落定，在**冷启动 / 恢复卷的首屏**可能读作「块自己挪了一下」。旧案用 `--stream-live` 门把所有非流式场景一并挡掉，正是为避这个（原文注释「不闪」）。理论判断是安全：RO 回调在布局后、绘制前交付，纠正多半落在首帧内（首帧无过渡可言），且这些块首见带 `pp-enter` 淡入、滑移被淡入盖住。**若真机上冷启动能看出「块自己挪位」，正确改法是把门收窄为「首帧落定后」**（壳层加一次性 settled 类，届时只放行用户驱动的重排），**不是退回旧案**——旧案同时挡掉了用户自己展开/收起时的让位，那才是本批的目标。

**③ 收口（2026-10-15 逐类核明）：不立 `.pp-collapse` 统一类，因为它不是一个形制**。原目标是「补退场对称 + 统一 `.pp-collapse`」——机制已给（`@starting-style` 管入场、`transition-behavior: allow-discrete` 管出场、`animateExit` 管卸载面），但把「折叠」收成一个跨产物工具类是**错的形制**，两条证据：

| 折叠面 | 实际实现 | 正确表达 |
|---|---|---|
| 设置页签（八页互斥） | **显隐切换**（同一批 DOM，`display` 切） | ✅ `allow-discrete`（批 4a 已用）——这是唯一适配的形制 |
| 纸面折叠体（夹注/脚注/工具卡） | **测高驱动的条件渲染**（`folded → return null`；`measure.ts` 折叠态返 `FOLD_ROW_H`） | 收起时留 DOM 做高度过渡 = 测高镜像与实际盒高错开一整个动画时长 ⇒ 下方块压上来。连续性只能由**让位**表达（批 1 已给） |
| 案卷侧栏折叠面（节/桶/族/独卷组） | **数据层操作**——`flatRows` 记忆化过滤 + 虚拟化窗口 + 键盘游标 + `aria-*` 全套跟着行集走 | 让折起的行「留着但裁掉」会同时击穿游标与落位锚点。同上：由让位/列表重排承载 |
| 查看器（tree 节点 / TOC / `<details>`） | 各是**独立的树/滚动语义** | 不在本法的换景词汇内（树节点开合是「展开」，不是「纸的移动」） |

**第二条、也是更硬的一条**：若 `.pp-collapse` 是**功能性**类（决定「折不折得起来」而非只决定「好不好看」），它就必须住在**壳层 CSS**（产物 CSS 各自为政，跨产物共享只能靠壳层）——而壳层烧在 exe 里 ⇒ **热更的新产物 + 旧 exe 上，这个类不存在、内容永远展开**（功能静默失效，不是观感降级）。本法的其它器具全是**观感类**（没生效就是没有过场），安全边界正在此处。故 ③ 的结论是「**机制统一 + 形制分治**」，不是「一个类管所有折叠」。

**批 4a 落地（2026-10-15 同日）：设置页签换景（纯 CSS，零 faceDeps）**。病灶两段：① 八个 `.sp-tab-content` 用**内联** `style={{ display: activeTab===x ? '' : 'none' }}` 互斥切换——换页零过场，一页「啪」地换成另一页；② `.sp-content` 是**唯一**滚动容器而各页是它的兄弟子件，切页时 `scrollTop` 原地留着 ⇒ 从长页切到短页会落在中途，**这本身就是一次跳变**。治法：切换权从内联样式收到 CSS 类 `.is-on`；过场走 `--m-ink`（单侧登场档）+ **`transition-behavior: allow-discrete`**——该关键字对 `display` 有**特例语义**：`block → none` 时浏览器把元素**留到过渡结束才真正隐藏**，故**出场也真的播**（这正是批 3 记下的「退场对称」工具箱在非卸载面上的用法）；入场起手走 `@starting-style`。只淡入、**不动位**（页是长滚动面，位移会连带读成滚动）。切页时经 ref 复位 `.sp-content` 的 `scrollTop`（`void activeTab` 表态满足 biome 的 useExhaustiveDependencies，同 `use-paper-focus.ts` 先例）。引擎不认识该关键字 ⇒ 回落旧观感（瞬时切换），无破面。

> **新判据（跨层同选择器必须同层）**：`.sp-tab-content[data-tab="provider"]` 的 `display:flex` 原本在**壳层** CSS（`app/panels/dock-panels/provider-settings.css`，`main.ts` 直接 import ⇒ 烧进 exe）。它与产物侧新的 `.sp-tab-content.is-on` **同选择器特异度**，而产物 CSS 注入在后 ⇒ 壳层那条会被源序顶掉，provider 页错落成 `block`（双栏自适应垮掉）。故该规则**整条迁进产物**（`settings-panel.css` 的 `.sp-tab-content[data-tab="provider"].is-on`），壳层那条删除并留迁移注。**一般化**：凡与「切换权」同选择器的样式，必须与切换权同层——**跨层拆分的安全边界是「选择器不同」或「特异度不同」，同选择器同特异度 = 注定被源序判死**。守护见 `motion-contract`（壳层文件不得再出现 `.sp-tab-content`）。

**批 5 落地（2026-10-15 同日）：读数微动效（缩放读数）**。病灶：−/＋ 钮与键盘 +/−/0 是**离散步进**，读数从 `100%` 直接变成 `150%`——三字替换没有任何交代。治法：`state/canvas-view-store.ts` 加 `zoomTick` + `markZoomStep()`，**只由离散步进抬升**（`stepZoom` / `resetZoom` 各一处；滚轮平滚的连续缩放**不抬**——连续路径每帧都在改读数，给它挂入场动画只会变成抖动）；读数件的数字包一层 `<span key={zoomTick} className="pp-zoom-num">`，值一变即**重挂**、`pp-readout-tick` 随挂载自动重播一次（不用定时器、不用 JS 动画）。两处细节：**key 挂内层 span 而非按钮**（重挂按钮会丢焦点——键盘用户点它回 100%，焦点必须留在原处）；**两处端点守卫**（档位夹持返回同值、已在 100% 时不抬计数，否则读数「空跳一下」）。量纲刻意压到 **2px + .72 起墨**（读数是 10px mono 小字，位移一大会读成「字在跳」而不是「值更新了」；起墨档同 `.pp-ink-delta`，不从 0 全透以免闪烁）。走 `--m-ink`（单件显形档）。

**批 6 落地（2026-10-18）：卷开合（落纸 / 起纸）——用户拍板「甲 · 入场 + 退场对称」**。病灶（用户：「卷的展开收起……现在纯粹是闪现」）：**开卷** = 纸与字同一帧出现（`.pp-region` 基座只有 `box-shadow` 过渡，纸零入场；激活那两件——拿纸过冲 + 卷首朱笔划界——是**激活**的动效，不是纸的入场），**合卷** = 区域当帧卸载（`space.collapse → core.closeSession` → 卷从 sess 表消失 → `regions` 随即不含它）——零退场，没有落点可言。§15 的换景收口账收的是「侧栏↔书脊 / 设置页签 / 首页↔画布 / 会话换主」四项，**卷开合从来没立过项**。

**治法两半（`paper-shell/region-motion.ts` 两个窗 + `PaperPanel.css` 三条规则）**：① **入场（落纸）** = 纸淡入 `.pp-region.pp-spread`（`--m-sheet`）+ 墨微升 8px（既有 `.pp-block.pp-enter`，`--m-ink`；墨比纸快半拍——两件各按自己的距离律档，不是漏写）。摊开 = 摊上画布 **+ 设为活卷**，故 `.pp-spread.pp-region-active` 必须把 `pp-region-take` 与 `pp-spread-in` **两条动画都写上**（`animation` 是整表替换不是合并）。② **退场（起纸）** = 入场逆写：`.pp-region[data-leaving]` 淡出 + `.pp-block.pp-leaving` 墨随纸沉 8px（**独立 `translate` 属性**，不是 `transform`——块定位用内联 transform，任何一帧声明它会像 2026-09-03 那次事故一样把块钉到左上角），窗满（`REGION_MOTION_MS` = `--m-sheet`）才真卸载。③ **窗内重开 = 撤销退场**（元素同 key，属性摘掉、按当下值掉头——批 3b 的抢占语义）。

**三条纪律（都有判例）**：**渲染期收敛**（消失当帧就进窗——挪进 effect = 先拆一帧再挂回来、退场窗里重播入场，同 DockPanel 相位机 2026-10-16 那条实测）；**入场走「窗」而不是单帧按位发放**（摊开卷之后同帧还有好几趟重渲染——落位/焦点/测高回写——按帧发类 = 浏览器根本没见到那个类，「声明存在但不生效」那一族；本批实测踩到后才改成窗）；**离场卷只进渲染面、不进测量面**（`usePaperRegions` 的 `regions` 保持活跃卷语义不动 ⇒ 小地图包围盒 / 目次带 / 匣脚引线 / 让位带看不见一个正在消失的卷——同「不给块折叠做高度过渡」那条理由）。**刻意不用 `@starting-style`** 承载入场：流区随虚拟化卸载/重挂（`visibleRegionIds`），挂首帧入场 = 平移时纸面反复「凭空浮现」（§15「首页→画布」候选做法那条判据已钉死这条路）。**冷启动/恢复工作区**首帧整批算「已落纸」（满屏纸一起淡入会被读成一次闪）。

**力度定案（2026-10-18 同日，用户实机反馈「不太明显」→ 台架五案实测 → 用户拍板「丙 · io ＋ 墨 18px」）**：两层原因，都不是「幅度不够」。
① **发令枪打错**（代码层 bug，已修）：落纸窗原按「卷首次**活跃**」发放，而开卷 = 摊开 **+ 视角飞过去**（`focus` 260ms）——远卷落地时不在视口里，类在屏外就把 260ms 播完了，镜头到时纸已稳稳摊着。改为「首次真在**视口里**」（横向 `visibleRegionIds` ＋ 纵向 `regionOnScreen`），并让 `played` 记住已播过的卷（平移扫过旧卷不重放、合卷离开才允许重播）。
② **曲线把 80% 的变化压在头 30%**：`--m-ease-out` 在 t=.2 走完 65%、t=.45 走完 94% ⇒ 名义 260ms 的动效**实感只有 ~90ms**。台架 `prototype/region-open-close-ab.html`（真 tokens + 真 PaperPanel.css + 真纸纹，五案同帧）逐案量「与落定帧的平均可见变化」（0~255，取 t=.2/.45/.7）：**甲 ease-out + 墨 8px = 1.65**；**只换 io = 3.99（+142%）**；io + 墨 18px = 4.30；io + 墨 28px = 4.37；io + 墨 18px + 纸位移 14px = 4.77。⇒ **主因是曲线；落幅 8→28px 只再 +10%**。
**判据扩一条（同批立）**：`--m-ease-io` 的适用范围从「两侧同时动」扩到 **「卷开合」（纸的出现/抽走）**——它本来就是「对开」曲线；ease-out 的「快起慢收」把开合读成闪现（有上表实测）。配套：墨的落幅 8 → **18px**、档从 `--m-ink` 抬到 `--m-sheet`（与纸同档同曲线 = 一次动作），`.pp-block.pp-drop` 由壳层在落纸窗内发放并**取代** `pp-enter`（同一属性上两条动画是整表替换）。**「纸本体位移」那一案（戊）未取**：它要翻案「`.pp-region` 任何帧不得声明 transform」那条红线，用户本轮没点头。

**边界（勿混）**：本轮做的是**画布上的卷开合**。③ 收口表那两条裁定不变——**纸面折叠体**（夹注/脚注/工具卡）仍只能由让位表达、**案卷侧栏折叠面**（节/桶/族/独卷组）仍是数据层操作、查看器树开合仍不在本法词汇内。

**钉值**：`tests/region-motion.test.ts`（8 例：进窗时机 / 快照同一引用 / 窗内重开撤销 / 窗满摘除 / 多卷独立计时 / 首帧整批不落纸 / **落纸类不被同帧重渲染摘掉** / 两窗同长与 nextExpiry）+ `tests/paper-region-leave.test.tsx`（3 例，真挂 PaperPanel：合卷当帧 `data-leaving` + `inert` + 块 `pp-leaving` + **读数面当帧就看不见它**；窗内重开 = DOM 节点身份不变；重开卷重播 `pp-spread` / `pp-enter` 且窗满即摘）+ `motion-contract` 新增「卷开合两窗」一条（`REGION_MOTION_MS` ↔ `--m-sheet`；落纸 keyframes 只碰 opacity；退场规则含 `pointer-events: none`；离场块的 `transition` 带上 transform，且规则本体不得写 transform）。**交付口径**：改动全在**插件产物**（paper-shell）⇒ `build:builtin-plugins` 后应用自动重载即可见，**无需重建 exe**。

**收口（2026-10-15 竣工；2026-10-18 补批 6）**：本法五批 + 批 6 已落，两项**明示不做**（不是欠账）：

1. **首页↔画布换景 + 纸壳出场**——**用户 2026-10-15 拍板「丙 · 维持硬切，力气花别处」**。理由链完整记录在上条（那两层纹理在纸壳**之上** ⇒ 退役在任何时刻都可见；要淡须拆层 = 动约 15 条视觉钉值，而此处看不到画面）。纸壳出场受同一条约束，**一并关闭**。此处的硬切在产品语义上说得通：那是「翻开一个案卷」，不是「切一个视图」。
2. **纸面折叠体收起**——架构上只能由让位表达（见批 3 剩余与 ③ 收口表），不是待办。

> **④ 换景的四项收口账（2026-10-15 核）**：**侧栏↔书脊** ✅ 已落（批 3b 的 `animateExit` + 出场逆写，纯 CSS）；**设置页签** ✅ 已落（批 4a）；**首页↔画布** ⏳ 差一个裁定（上条）；**会话换主** ✅ **已核，无需动作**——换主时进场的流区走 `.pp-region-active`（影过冲 `pp-region-take` + 卷首朱笔划界 `pp-seal-draw`）、退场的流区走 `.pp-region` 的 `box-shadow` 过渡，**两端都已有过场**，批 1 只是把它们的时长收进了 `--m-sheet`；其余（坞内目标卷字样、侧栏选中行）是**态变**，走 `--snap` 即正确，不属换景。

**钉值**：`tests/motion-contract.test.ts`（15 例：三档在册且档间单调 / 退役 token 零引用 / 禁 `transition: all` / **首帧入场必须走 `@starting-style`**（含设置面板终态与起手式对拍）/ **退场对称**（`PANEL_LEAVE_MS` ↔ `--m-sheet` 镜像 + 三个面的声明与出场规则成对，含 `pointer-events: none` 与淡出；2026-10-16 补：侧栏/书脊**入场走起手式 + 过渡**（基座不得再挂 keyframes 动画）、出场档 `--m-sheet` 与起手值成对）/ **设置页签换景**（`.is-on` 切权 + `allow-discrete` + 起手式 + 切页复位滚动 + 八页都改了 + **壳层不得再有 `.sp-tab-content`**）/ **读数微动效**（只有离散步进抬计数 + 两处端点守卫 + key 挂内层 span + 2px/.72 量纲钉死）/ 散写贝塞尔零引用 / 让位常驻且只动 transform / 让位不被状态变体静默掐掉（`transition:` 整表替换）/ 手律豁免在册 + 壳层真发放 `pp-live-hand` / rAF 自觉读 matchMedia 两处 / 两条 TS↔CSS 镜像同值 / 全仓 CSS 带字面时长的声明只许落在登记表内 / 扫描器自证非永真；**相位机行为面**另有 `tests/dock-panel-leave.test.tsx`：DOM 节点身份 + 真挂载计数——收面时不拆不重挂、未声明 `animateExit` 仍即时卸载、退场窗内重开不被在途收尾定时器删掉）；规格变更同步改了 `paper-visual-decisions` 两处钉值（流区影过渡 `320ms cubic-bezier(…)` → `var(--m-sheet)`；卷首朱笔划界 `0.24s cubic-bezier(…)` → `0.24s var(--m-ease-out)`，时长按仪式档不变）。

## 16. 悬停提示（tooltip · 2026-10-30 立法 · 用户拍板「甲 · 纸片」）

**病灶**：全产品的说明层从来没被设计过——调用点一律用浏览器原生 `title`（延迟约 1s、样式不可改、触屏不出现、与纸壳材质完全脱节），且文案信息结构参差：同一排按钮里既有「发送本轮输入」四个字，也有「插入进行中的回合（Agent 运行中，下轮生效）」一整句，读起来像系统报错。

**机制（刻意的选择，别改回组件包装）**：`data-tip` 属性 + `App` 根单例宿主（`app/tip/`）做**事件委托**。调用点改动 = `title="…"` → `data-tip="…"`（可选 `data-tip-hint="…"` 次行）——纯属性替换 ⇒ **DOM 结构零变化、布局零风险**。`<Tip>` 包装会在每个位置各插一层 DOM，flex/grid 子元素、`> *` 选择器、绝对定位锚点都可能被那一层破坏，回归面远大于收益。

**形态（甲案 · 纸片，2026-10-30 二批按纸壳规格精修）**：纸底提亮一档（用户选定「再淡一点」——纯纸本色与背景融、纯白像贴上去的塑料片，取 `color-mix(--paper 75%, #fff)`）+ `var(--rule-strong)` 弱线 + `var(--elev-raise)` 落影，**刻意不透明**（半透明会让底下正文与提示文字互相糊字，同 §14 浮件判据）。**规格一律照纸壳既有标准件取、不自造**，对照件是同为悬停浮件的目次卡 `.pp-toc-card`：
- **字体** `var(--f-song)` —— 全站正式件都显式声明；不写 = 继承到非纸壳字体，一眼是外挂
- **字号** `calc(Npx × var(--font-scale))` —— 用户调字号时全站都跟，提示框不能不跟（初版写死 12px，是功能性缺陷）
- **圆角 0** —— 纸是方的，纸壳浮件一律无圆角（初版自作主张 2px）
- **边框** `--rule-strong`(ink-2) —— ink-4 在纸面上立不住
- **内距** 8/12/9 四边不等 —— 纸壳讲究件的呼吸，不是四边等值
- **字重层次** 主行 600、次行 400 且小一号淡下去 —— 两行同字重读不出层次
- **数字** `tabular-nums` —— 读数类提示（`墨量 500000 / 1000000 tok`）不留跳宽
- 箭头 9px 菱形只画朝外两边（对齐 `.pp-toc-card::after`）；限宽 260px、`white-space: pre-line` 保住多行提示的换行、`text-wrap: pretty` 避免末行孤字

**乙案「墨锭」（墨底反白）未取**——它与「重墨锚点全产品只许三处」的既有纪律打架（见 §10 浸墨法则），用户本轮选甲。

**动效（三档内消费，不新增时长与曲线；2026-10-30 三批精修）**：**入场与退场分档**，不是同一档逆写——
- **入场**：抬到 `--m-sheet`（0.26s）+ `--m-ease-io`（对开曲线），落幅 12px。判据同 §15 批 6：出相曲线在 t=.2 已走完 65%、t=.45 走完 94%，60fps 下**约两帧就动完**——眼睛读到的是「出现」而不是「浮现」。那批台架实测「只换 io = +142% 可感度」，本件同因同解
- **退场**：走 `--m-ink`（0.16s / 出相），退场逆写。人眼对「消失」比对「出现」宽容，退场拖长只挡视线
- 曲线用 **`transition-timing-function` longhand 覆盖** shorthand 里的 easing（`--m-sheet` 自带出相曲线，**叠加第二段 `var(--m-ease-io)` 无法解析**）——这样既拿到 0.26s 的时长、又换成 io 曲线，且不新增任何字面时长
- **方向随翻转**：`data-side='bottom'` 时起手 `-12px`（从上往下落），不再两个方向共用一个 `+12px`——初版在翻转后读起来像「从按钮里钻出来」，是真缺陷

宿主节点**常驻**、只切 `.is-on` ⇒ transition 有落点（同 §15 批 3 判例：transition 挂在随开合卸载的元素上 = 声明永不生效）。**相邻切换不重播入场**：从 A 移到相邻 B 时只换内容与坐标，不重走动画。

**交互判据（都有理由）**：悬停出场 **320ms** / 键盘聚焦 **150ms**（原生约 1000ms 太钝；<200ms 则扫过一排按钮每个都弹）/ 离开宽限 **80ms**（不留这一窗，两个按钮之间的 1px 间隙会让提示闪一下再重出——本批测试实测踩到）/ 定位 = 上方优先 → 空间不足翻下方 → 水平夹取进视口 8px / 拖拽中（`buttons !== 0`）不出 / 触屏不出（与原生行为一致，无退化）。层级 `--z-tip: 480`——**盖过插件窗与面板，但不得盖过牒卡(500)/命令面板(510)：提示永远不该压住一个正在等用户回答的浮层**。

**无障碍底线**：宿主渲染 `role="tooltip"` 并在显示期给锚点挂 `aria-describedby`；但**提示不得是唯一信息源**——纯图标按钮仍须自备 `aria-label`（替换 `title` 时逐个核，原生的读屏兜底被拿掉了）。

**钉值**：`tests/tip-host.test.tsx`（10 例：320ms 前不出 / 拖拽中不出 / 80ms 宽限后收 / 双层与无次行不留空行 / **相邻切换立即换内容**（本批唯一因实现缺陷从「即时收」改成「宽限收」的用例）/ 键盘 150ms / aria-describedby 挂摘 / 定位翻转 top↔bottom / 无 data-tip 不出）。文案纪律：主行 = 动作（4~8 字），次行 = 条件或后果。

**分批**：创作坞（`compose-dock` 五个文件）已全量切换；其余面（设置页 / 侧栏 / 渲染器 / 首页）按同法逐批替换——**未切换处的原生 `title` 仍可用**，两者并存无害（宿主只认 `data-tip`）。目次带 `.pp-toc-card` 有独立几何逻辑，另行收编。