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

package/README.i18n.yaml

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

package/README.md

@@ -1,26 +1,43 @@
-# 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 renders whenever the native one would — no question-count or width gates.
+- **Aligned with the native geometry.** The rail's vertical position follows the host's own band formula (viewport height minus composer height, read from the host's `--dsh-conversation-viewport-height` / `--dsh-composer-height` variables), so it never drifts from where the built-in rail would sit.
 
 ## Requirements
 
-- DSH `>=0.1.1-rc.1` (built and tested against `0.1.1-rc.2`).
+- DSH `>=0.1.1-rc.1` (built and tested against `0.1.5-rc.2`).
+- 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 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,42 @@
-# 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 公式（视口高减输入框高，读宿主 `--dsh-conversation-viewport-height` / `--dsh-composer-height` 变量），永远不会偏离原生导航条该在的位置。
 
 ## 要求
 
-- DSH `>=0.1.1-rc.1`（构建与测试基于 `0.1.1-rc.2`）。
+- DSH `>=0.1.1-rc.1`（构建与测试基于 `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` 投影。探测失败时降级为纯展示轨（或无轨），绝不做坏页面。
+- 预览卡是有意耦合主题的唯一表面：使用宿主 tooltip 令牌实现原生灰；刻度条本体坚持系统 `Canvas`/`CanvasText` 配色。
 
 ## 许可