@lament_z/dsh-client-ui-chat-timeline 0.1.0 → 0.2.0

package/README.i18n.yaml

@@ -4,6 +4,8 @@ target: README.zh.md
 sections:
   - title
   - intro
+  - features
+  - mount
   - requirements
   - install
   - notes

package/README.md

@@ -1,26 +1,50 @@
-# dsh-client-ui-chat-timeline
+# DSH Chat Timeline
 
-A DSH web GUI plugin that adds a left-edge question navigator rail to the conversation: one tick per human question, a hover ripple that lengthens nearby ticks, a preview card per turn (user message plus assistant reply excerpt), click to jump, and a scroll-synced highlight of the current turn.
+English | [简体中文](./README.zh.md)
 
-The interaction design replicates the ZCode desktop client's TurnNavigator (reverse-engineered from its 3.10.1 renderer bundle; see the workspace spec `.scratch/chat-timeline/spec.md`): 10px tick pitch, ripple `scaleX 2.6/1.7/1.25` at opacity `1/.86/.72/.58` over 150ms, 320px preview cards after a 120ms delay (80ms close), hidden below 2 questions or a 864px conversation width, `prefers-reduced-motion` turns jumps instant, full `aria` labelling.
+A DSH web plugin that adds a **question navigator rail** beside the conversation: one tick per human question, hover ripples, a per-turn preview card, click-to-jump, and a scroll-synced highlight of the current turn. The interaction design replicates the ZCode desktop client's TurnNavigator; the jump mechanics reuse the DSH host's own turn-navigation implementation, so jumping behaves exactly like the built-in rail — including across the paged event window.
+
+## Features
+
+- **One tick per question, whole history.** Ticks come from the host's official `turnOutline` projection (session-turn-outline domain): the full-log turn index computed host-side, so every question of the session is navigable without paging the event window in first.
+- **Click to jump, native mechanics.** Landing replicates the host ChatView's `navigateToTurn`/`landOnRow`: the turn's row is located by its native `data-chat-turn` anchor, scrolled instantly to sit 24px below the viewport top; turns outside the loaded window are paged in through the official `session.loadThrough(turn/start seq)` verb first.
+- **Scroll-synced highlight.** The active tick follows the host's own reading-line rule (hit-test at `top + min(96, height * 0.2)`, last tick wins within 25px of the bottom), so the rail and the content never disagree.
+- **Hover ripple and preview cards.** ZCode TurnNavigator parity: ripple `scaleX 2.6/1.7/1.25` at opacity `1/.86/.72/.58` over 150ms, 320px preview card after a 120ms delay (80ms close) showing the user prompt plus the assistant reply excerpt, styled with the host's native tooltip tokens (gray card, white text, follows light/dark theme).
+- **Takes over the native rail, cleanly.** While the plugin is active, the host's built-in right-side Turn navigator is hidden; unloading the plugin restores it immediately. The plugin rail sets no question-count or width gate of its own.
+- **Native band geometry, computed in CSS.** The rail's vertical position is the host's own band rule — viewport height minus composer height, halved — expressed as a single CSS `calc()` over the host's `--dsh-conversation-viewport-height` / `--dsh-composer-height` variables. No JavaScript measures it, and the rail no longer needs the native navigator to exist in the DOM in order to locate its band.
+
+## How it mounts
+
+The rail registers on the host's session-scoped `conversation.input.overlay` seat, and that choice is load-bearing. Since DSH 0.1.7 the open session is no longer discoverable from the sessions service — the list snapshot dropped its `current` field and `binding(id)` only borrows an already-retained scope — so a session-scoped seat is the only supported channel: the host passes the scope's session id into the registration's `inject`. Registering there also places the rail inside the conversation scroller, which is where the band variables are defined and therefore inherited from.
+
+Vertical geometry consequently needs no measurement at all. The horizontal left edge is the one measured value: the conversation column is a grid track that the right sidebar shrinks, so it is not derivable from a window-edge offset.
 
 ## Requirements
 
-- DSH `>=0.1.1-rc.1` (built and tested against `0.1.1-rc.2`).
+- DSH `>=0.1.1-rc.1`. This revision is built and tested against `0.1.7-rc.2`; the seat it registers on and that seat's session-scoped `inject` are verified on `0.1.5-rc.2` as well.
+- Pure browser plugin: the host half is an empty cordis plugin; nothing to configure.
 
 ## Install
 
 ```sh
+# Preferred: install straight from GitHub (prebuilt lib is committed)
+dsh plugin --profile web add github:lament-z/dsh-client-ui-chat-timeline
+
+# Alternative: from npm
+dsh plugin --profile web add @lament_z/dsh-client-ui-chat-timeline
+
+# From a local clone / working copy
 dsh plugin --profile web add link:<this directory>
 ```
 
-Then restart `dsh web` and reload the page. The rail appears beside any conversation with at least two of your questions once the window is wide enough.
+Then restart `dsh web` and reload the page. The rail appears beside any conversation; the host's own right-side navigator is hidden while the plugin is active and comes back the moment you remove the plugin.
 
 ## Notes
 
-- Pure browser plugin: the host half is an empty cordis plugin.
-- Data comes from the public client-runtime contracts (`ctx.sessions` + `ConversationSnapshot`); jump and scroll-sync probe the chat DOM through stable `data-*` hooks and degrade to a display-only rail when detection fails.
-- Colors follow the page color scheme (`Canvas`/`CanvasText`), no theme token coupling.
+- Jump and highlight reuse the host's stable contracts: `data-chat-turn` row anchors, `[data-conversation-scroll]` scrollport, `session.loadThrough`, and the `turnOutline` projection. When detection fails, the rail degrades to display-only instead of throwing.
+- The rail is `position: fixed` and positioned from the host's layout variables, so it assumes no ancestor of the conversation establishes a containing block (`transform` / `filter` / `contain`). That holds in every layout this revision was verified against.
+- The preview card is the only deliberately theme-coupled surface: it uses the host's tooltip tokens for the native gray look; the rail itself sticks to system `Canvas`/`CanvasText` colors.
+- Failure mode is a display-only rail (or no rail), never a broken page.
 
 ## License
 

package/README.zh.md

@@ -1,26 +1,50 @@
-# dsh-client-ui-chat-timeline
+# DSH Chat Timeline
 
-DSH Web GUI 插件：在会话区左缘加一条"问题导航时间线"——每个刻度对应一条你的提问，悬停时邻近刻度涟漪式变长，弹出该轮预览卡（用户消息 + 助手回复摘要），点击跳转，滚动时高亮当前回合。
+[English](./README.md) | 简体中文
 
-交互设计复刻自 ZCode 桌面客户端的 TurnNavigator（从其 3.10.1 渲染层 bundle 逆向；见工作区 spec `.scratch/chat-timeline/spec.md`）：10px 刻度间距、涟漪 `scaleX 2.6/1.7/1.25`、不透明度 `1/.86/.72/.58`、150ms 过渡、预览卡 320px（120ms 开 / 80ms 关）、少于 2 条提问或会话区窄于 864px 时隐藏、`prefers-reduced-motion` 时跳转改为瞬时、完整 `aria` 标注。
+DSH Web 插件：在会话区旁加一条**问题导航刻度条**——每个刻度对应一条你的提问，悬停涟漪反馈、逐轮预览卡、点击跳转、滚动同步高亮当前轮次。交互设计复刻 ZCode 桌面客户端的 TurnNavigator；跳转机制直接复用 DSH 宿主自己的轮次导航实现，跳转行为与原生完全一致——包括跨事件翻页窗口的跳转。
+
+## 功能
+
+- **一问一刻度，全史可导航。** 刻度来自宿主官方 `turnOutline` 投影（session-turn-outline 域）：宿主对整份日志 fold 出的全史轮次索引，无需先把事件窗口翻页进来，会话里每条提问都可直达。
+- **点击跳转，原生机制。** 落位复刻宿主 ChatView 的 `navigateToTurn`/`landOnRow`：按原生 `data-chat-turn` 锚点找到轮次行，瞬时滚动到行顶距视口顶 24px 处；轮次不在已加载窗口时，先走官方 `session.loadThrough(turn/start seq)` 翻页再落位。
+- **滚动同步高亮。** 当前刻度跟随宿主自己的阅读线规则（`top + min(96, 高度*0.2)` 处命中测试，距底部 25px 内最后一刻度胜出），刻度条与内容永远一致。
+- **悬停涟漪与预览卡。** 与 ZCode TurnNavigator 对齐：涟漪 `scaleX 2.6/1.7/1.25`、不透明度 `1/.86/.72/.58`、150ms 过渡；320px 预览卡延迟 120ms 弹出（80ms 关闭），展示用户提问 + 助手回复摘要；配色使用宿主原生 tooltip 令牌（灰底白字，跟随亮/暗主题）。
+- **干净地接管原生导航条。** 插件存活期间，宿主内置的右侧 Turn 导航条被隐藏；卸载插件立即恢复。本刻度条自身不设条数或宽度门槛。
+- **原生 band 几何，纯 CSS 计算。** 刻度条的纵向位置就是宿主自己的 band 规则——视口高减输入框高再取半——写成一条 CSS `calc()`，直接读宿主 `--dsh-conversation-viewport-height` / `--dsh-composer-height` 变量。没有任何 JavaScript 测量，也不再依赖原生导航条存在于 DOM 才能定位自己的 band。
+
+## 挂载方式
+
+刻度条注册在宿主的 **session 作用域** seat `conversation.input.overlay` 上，这个选择是承重的。DSH 0.1.7 起，打开的会话不再能从 sessions 服务里查到——list 快照删掉了 `current` 字段，`binding(id)` 也只借已保留的 scope——因此 session 作用域 seat 是唯一受支持的通道：宿主会把该作用域的 session id 传进注册的 `inject`。注册在这里同时让刻度条落在会话滚动容器内部，而 band 变量正是在该容器上定义、因而能被继承。
+
+于是纵向几何完全不需要测量。唯一保留的测量值是横向左沿：会话列是一条 grid 轨道，右侧栏打开时会把它挤窄，因此无法由窗口边缘偏移推导。
 
 ## 要求
 
-- DSH `>=0.1.1-rc.1`（构建与测试基于 `0.1.1-rc.2`）。
+- DSH `>=0.1.1-rc.1`。本版基于 `0.1.7-rc.2` 构建与实测；它注册的 seat 及该 seat 的 session 作用域 `inject` 在 `0.1.5-rc.2` 上同样验证过。
+- 纯浏览器插件：host 半区为空 cordis 插件，无需任何配置。
 
 ## 安装
 
 ```sh
+# 推荐：直接从 GitHub 安装（lib 预构建产物已入库）
+dsh plugin --profile web add github:lament-z/dsh-client-ui-chat-timeline
+
+# 备选：从 npm 安装
+dsh plugin --profile web add @lament_z/dsh-client-ui-chat-timeline
+
+# 从本地 clone / 工作副本安装
 dsh plugin --profile web add link:<本目录>
 ```
 
-然后重启 `dsh web` 并刷新页面。会话中至少有两条你的提问且窗口足够宽时，轨道出现在会话区左缘。
+然后重启 `dsh web` 并刷新页面。刻度条出现在任意会话旁；插件存活期间宿主右侧导航条隐藏，移除插件的瞬间原样恢复。
 
 ## 说明
 
-- 纯浏览器插件：host 半区为空 cordis 插件。
-- 数据全部走 client-runtime 公开契约（`ctx.sessions` + `ConversationSnapshot`）；跳转与滚动同步通过稳定的 `data-*` 钩子探测聊天 DOM，探测失败时降级为纯展示轨。
-- 颜色跟随页面配色（`Canvas`/`CanvasText`），不耦合主题 token。
+- 跳转与高亮复用宿主稳定契约：`data-chat-turn` 行锚点、`[data-conversation-scroll]` 滚动容器、`session.loadThrough` 与 `turnOutline` 投影。探测失败时降级为纯展示轨（或无轨），绝不做坏页面。
+- 刻度条为 `position: fixed` 且按宿主布局变量定位，因此前提是会话的祖先链上没有元素建立 containing block（`transform` / `filter` / `contain`）。本版验证过的所有布局均满足该前提。
+- 预览卡是有意耦合主题的唯一表面：使用宿主 tooltip 令牌实现原生灰；刻度条本体坚持系统 `Canvas`/`CanvasText` 配色。
+- 失败形态是纯展示轨（或无轨），绝不会是坏页面。
 
 ## 许可