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

package/README.i18n.yaml

@@ -0,0 +1,10 @@
+# Pairing record for the plugin README (docs/i18n.md contract).
+source: README.md
+target: README.zh.md
+sections:
+  - title
+  - intro
+  - requirements
+  - install
+  - notes
+  - license

package/README.md

@@ -0,0 +1,27 @@
+# dsh-client-ui-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.
+
+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.
+
+## Requirements
+
+- DSH `>=0.1.1-rc.1` (built and tested against `0.1.1-rc.2`).
+
+## Install
+
+```sh
+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.
+
+## 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.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,27 @@
+# dsh-client-ui-chat-timeline
+
+DSH Web GUI 插件：在会话区左缘加一条"问题导航时间线"——每个刻度对应一条你的提问，悬停时邻近刻度涟漪式变长，弹出该轮预览卡（用户消息 + 助手回复摘要），点击跳转，滚动时高亮当前回合。
+
+交互设计复刻自 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 `>=0.1.1-rc.1`（构建与测试基于 `0.1.1-rc.2`）。
+
+## 安装
+
+```sh
+dsh plugin --profile web add link:<本目录>
+```
+
+然后重启 `dsh web` 并刷新页面。会话中至少有两条你的提问且窗口足够宽时，轨道出现在会话区左缘。
+
+## 说明
+
+- 纯浏览器插件：host 半区为空 cordis 插件。
+- 数据全部走 client-runtime 公开契约（`ctx.sessions` + `ConversationSnapshot`）；跳转与滚动同步通过稳定的 `data-*` 钩子探测聊天 DOM，探测失败时降级为纯展示轨。
+- 颜色跟随页面配色（`Canvas`/`CanvasText`），不耦合主题 token。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# bundle patch for the chat-timeline plugin: inserts its plugin row into the web
+# profile roster. Applied as a profile bundle layer (the `dsh.bundle.patch`
+# manifest field); install with
+# `dsh plugin --profile web add link:<repo>/plugin`.
+- insert:
+    - id: ui-chat-timeline
+      name: '@lament_z/dsh-client-ui-chat-timeline'

package/lib/client.js

@@ -0,0 +1,767 @@
+window.__ModuleLoader__.load({
+	id: "@lament_z/dsh-client-ui-chat-timeline",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		let react_dom = require("react-dom");
+		let react_jsx_runtime = require("react/jsx-runtime");
+		/** Human node kinds that anchor a tick. */
+		const HUMAN_KINDS = /* @__PURE__ */ new Set(["user", "steering"]);
+		/** Extract concatenated text from a ContentBlock-like list.
+		*  dsh-llm content blocks switch on `type`; assistant blocks use `kind` — accept both. */
+		function blocksText(blocks) {
+			if (!Array.isArray(blocks)) return "";
+			const parts = [];
+			for (const block of blocks) if (block !== null && typeof block === "object") {
+				const record = block;
+				if (record.kind === "text" || record.type === "text") {
+					if (typeof record.text === "string" && record.text.length > 0) parts.push(record.text);
+				}
+			}
+			return parts.join("\n\n");
+		}
+		/** Collapse each paragraph's whitespace and drop empties (ZCode u5e parity). */
+		function collapseParagraphs(text, maxParagraphs) {
+			return text.trim().split(/\n\s*\n/u).map((paragraph) => paragraph.replace(/\s+/gu, " ").trim()).filter(Boolean).slice(0, Math.max(1, maxParagraphs));
+		}
+		/** Truncate to the budget with an ellipsis, never below the floor (ZCode d5e parity). */
+		function truncatePreview(text, maxChars, floor = 8) {
+			const budget = Math.max(floor, maxChars);
+			if (text.length <= budget) return text;
+			return `${text.slice(0, budget - 3).trimEnd()}...`;
+		}
+		/** Build one preview string from raw texts under the shared budget. */
+		function buildPreview(texts, fallback) {
+			const paragraphs = collapseParagraphs(texts.join("\n\n"), 2);
+			if (paragraphs.length === 0) return fallback;
+			return truncatePreview(paragraphs.join("\n"), 220);
+		}
+		/**
+		* Derive the tick directory from the snapshot's ordered node list.
+		* @param nodes - conversation snapshot nodes in seq order.
+		* @param running - whether the session currently has a running turn.
+		* @param labels - localized preview fallbacks.
+		* @returns one item per human input, in order.
+		*/
+		function buildTimelineItems(nodes, running, labels) {
+			const drafts = [];
+			for (const node of nodes) {
+				if (HUMAN_KINDS.has(node.kind)) {
+					const text = blocksText(node.content);
+					drafts.push({
+						key: `n${node.seq}`,
+						seq: node.seq,
+						time: typeof node.time === "number" ? node.time : 0,
+						userTexts: text === "" ? [] : [text],
+						hasUserText: text !== "",
+						assistantTexts: []
+					});
+					continue;
+				}
+				if (node.kind !== "assistant" || drafts.length === 0) continue;
+				const text = blocksText(node.blocks);
+				if (text !== "") drafts[drafts.length - 1].assistantTexts.push(text);
+			}
+			const last = drafts.length - 1;
+			return drafts.map((draft, index) => {
+				const isLive = running && index === last;
+				const assistantTexts = draft.assistantTexts;
+				const assistantKind = assistantTexts.length > 0 ? "text" : isLive ? "running" : "empty";
+				return {
+					key: draft.key,
+					seq: draft.seq,
+					time: draft.time,
+					userPreview: buildPreview(draft.userTexts, labels.userFallback),
+					userFallback: !draft.hasUserText,
+					assistantPreview: buildPreview(assistantTexts, isLive ? labels.assistantRunning : labels.assistantEmpty),
+					assistantKind,
+					running: isLive
+				};
+			});
+		}
+		//#endregion
+		//#region src/client/dom.ts
+		/**
+		* Find the chat scroll container with a candidate chain.
+		* 1. the explicit stable hook `[data-conversation-scroll]`;
+		* 2. the closest scrollable ancestor of the flow column `[data-chat-flow]`;
+		* 3. the largest scrollable element that contains human rows.
+		*/
+		function findChatContainer(doc) {
+			const direct = doc.querySelector("[data-conversation-scroll]");
+			if (direct !== null) return direct;
+			const flow = doc.querySelector("[data-chat-flow]");
+			const ancestor = flow !== null ? scrollableAncestor(flow) : null;
+			if (ancestor !== null) return ancestor;
+			let best = null;
+			let bestHeight = 0;
+			for (const element of Array.from(doc.querySelectorAll("*"))) {
+				if (!isScrollable(element)) continue;
+				if (element.querySelector("[data-chat-flow-kind=\"user\"]") === null) continue;
+				const height = element.clientHeight;
+				if (height > bestHeight) {
+					best = element;
+					bestHeight = height;
+				}
+			}
+			return best;
+		}
+		function isScrollable(element) {
+			const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+			if (style === void 0) return false;
+			if (!/(auto|scroll)/.test(style.overflowY)) return false;
+			return element.scrollHeight > element.clientHeight + 40 && element.clientHeight > 200;
+		}
+		function scrollableAncestor(element) {
+			let node = element;
+			while (node !== null) {
+				if (isScrollable(node)) return node;
+				node = node.parentElement;
+			}
+			return null;
+		}
+		/** Human-turn rows inside the container (falling back to a document-wide query). */
+		function findUserRows(container) {
+			const scope = container ?? document;
+			return Array.from(scope.querySelectorAll("[data-chat-flow-kind=\"user\"]"));
+		}
+		/**
+		* The active index: the last human row whose top edge sits above the
+		* container's reading line (40px below the top edge), matching the ZCode
+		* "unit at viewport top" rule; clamps to the last row at scroll bottom.
+		*/
+		function computeActiveIndex(container, rows) {
+			if (rows.length === 0) return -1;
+			const top = container.getBoundingClientRect().top + 40;
+			let active = 0;
+			for (let index = 0; index < rows.length; index += 1) if (rows[index].getBoundingClientRect().top <= top) active = index;
+			else break;
+			if (container.scrollHeight - container.scrollTop - container.clientHeight <= 4) return rows.length - 1;
+			return active;
+		}
+		/**
+		* Scroll the given human turn into view. Tries a smooth scroll first; DSH's
+		* windowed conversation list programs scrollTop on scroll events, which can
+		* cancel a smooth animation on the first frame — when nothing has moved after
+		* a short grace period the jump falls back to an instant scroll.
+		* @returns false when the container or row is unavailable.
+		*/
+		function jumpTo(index, behavior) {
+			const container = findChatContainer(document);
+			if (container === null) return false;
+			const row = findUserRows(container)[index];
+			if (row === void 0) return false;
+			const delta = row.getBoundingClientRect().top - container.getBoundingClientRect().top - 12;
+			const target = container.scrollTop + delta;
+			if (behavior === "auto") {
+				container.scrollTo({
+					top: target,
+					behavior: "auto"
+				});
+				return true;
+			}
+			const startedAt = container.scrollTop;
+			container.scrollTo({
+				top: target,
+				behavior: "smooth"
+			});
+			window.setTimeout(() => {
+				if (Math.abs(container.scrollTop - startedAt) < 4) container.scrollTo({
+					top: target,
+					behavior: "auto"
+				});
+			}, 700);
+			return true;
+		}
+		/** Create the probe against a document (injectable for tests). */
+		function probeChatDom(doc) {
+			return {
+				getContainer: () => findChatContainer(doc),
+				getUserRows: () => findUserRows(findChatContainer(doc)),
+				activeIndex: () => {
+					const container = findChatContainer(doc);
+					if (container === null) return -1;
+					return computeActiveIndex(container, findUserRows(container));
+				},
+				jumpTo: (index, behavior) => jumpTo(index, behavior)
+			};
+		}
+		//#endregion
+		//#region src/client/styles.ts
+		/**
+		* Stylesheet for the chat-timeline rail, injected once as a
+		* `<style data-plugin-css="chat-timeline">` tag. All classes carry the
+		* `dsh-tl-` prefix; colors use the CSS system colors Canvas/CanvasText so the
+		* rail follows the app's color-scheme without reaching into DSH theme tokens.
+		* Visual constants replicate the ZCode TurnNavigator (spec section 2.2).
+		*/
+		const TIMELINE_STYLES = `
+.dsh-tl-nav {
+  position: fixed;
+  z-index: 10;
+  width: 48px;
+  pointer-events: none;
+  opacity: 1;
+  transition: opacity 150ms ease-out;
+}
+.dsh-tl-nav[data-visible="false"] {
+  opacity: 0;
+  visibility: hidden;
+}
+.dsh-tl-scroll {
+  position: absolute;
+  left: 12px;
+  top: 50%;
+  transform: translateY(-50%);
+  width: 36px;
+  max-height: calc(100% - 96px);
+  overflow-x: hidden;
+  overflow-y: auto;
+  padding-block: 4px;
+  pointer-events: auto;
+  scrollbar-width: none;
+  color: CanvasText;
+}
+.dsh-tl-scroll::-webkit-scrollbar {
+  display: none;
+}
+.dsh-tl-track {
+  position: relative;
+  width: 36px;
+}
+.dsh-tl-slot {
+  position: absolute;
+  left: 0;
+  top: 0;
+  height: 10px;
+  width: 36px;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  border-radius: 2px;
+  cursor: pointer;
+}
+.dsh-tl-slot:focus-visible {
+  outline: 2px solid CanvasText;
+  outline-offset: 2px;
+}
+.dsh-tl-tick {
+  display: block;
+  height: 2px;
+  width: 12px;
+  border-radius: 999px;
+  background: currentColor;
+  transform-origin: left center;
+  transition: height 150ms ease-out, opacity 150ms ease-out, transform 150ms ease-out, background-color 150ms ease-out;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dsh-tl-nav,
+  .dsh-tl-tick {
+    transition: none;
+  }
+}
+.dsh-tl-tip {
+  position: fixed;
+  z-index: 60;
+  width: 320px;
+  max-width: calc(100vw - 2rem);
+  padding: 12px;
+  border-radius: 10px;
+  background: Canvas;
+  color: CanvasText;
+  border: 1px solid color-mix(in srgb, CanvasText 15%, transparent);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+  pointer-events: none;
+}
+.dsh-tl-tip-user {
+  margin: 0;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 2;
+  overflow: hidden;
+  white-space: pre-line;
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 500;
+}
+.dsh-tl-tip-assistant {
+  margin: 8px 0 0;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+  overflow: hidden;
+  white-space: pre-line;
+  font-size: 13px;
+  line-height: 20px;
+  opacity: 0.8;
+}
+.dsh-tl-tip-assistant[data-kind="running"],
+.dsh-tl-tip-assistant[data-kind="empty"] {
+  opacity: 0.55;
+}
+`;
+		/** Inject the stylesheet once per document. */
+		function ensureStyles(doc) {
+			const tagId = "chat-timeline";
+			if (doc.querySelector("style[data-plugin-css=\"chat-timeline\"]") !== null) return;
+			const tag = doc.createElement("style");
+			tag.dataset.plugin = "@lament_z/dsh-client-ui-chat-timeline";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = TIMELINE_STYLES;
+			doc.head.appendChild(tag);
+		}
+		//#endregion
+		//#region src/client/rail.tsx
+		/**
+		* TimelineRail — the shell.overlay entry: a left-edge tick rail over the
+		* conversation, one tick per human question. Visual and interaction constants
+		* replicate the ZCode TurnNavigator (see .scratch/chat-timeline/spec.md):
+		* hover ripple scaleX 2.6/1.7/1.25 with opacity 1/.86/.72/.58 over 150ms,
+		* 320px preview cards after a 120ms delay, >=2 questions to render, >=864px
+		* container width, prefers-reduced-motion fallback, full aria labelling.
+		*/
+		/** Slot height per tick (10px pitch, ZCode parity). */
+		const ITEM_PITCH = 10;
+		/** Container width below which the rail hides. ZCode uses 864px, but DSH's
+		*  three-pane layout leaves the conversation narrower — the rail overlays the
+		*  left edge without taking layout space, so only truly cramped panes hide. */
+		const MIN_CONTAINER_WIDTH = 560;
+		/** Preview-card hover delays (ms). */
+		const TIP_OPEN_DELAY = 120;
+		const TIP_CLOSE_DELAY = 80;
+		/** Ripple visual per distance from the hovered tick (ZCode _5e parity).
+		*  The ripple is interaction-only: at rest every tick is idle (scaleX 1),
+		*  and the current position is signalled by color/opacity, not length. */
+		function ripple(distance) {
+			if (distance === 0) return {
+				opacity: 1,
+				scaleX: 2.6,
+				tone: "peak"
+			};
+			if (distance === 1) return {
+				opacity: .86,
+				scaleX: 1.7,
+				tone: "near"
+			};
+			if (distance === 2) return {
+				opacity: .72,
+				scaleX: 1.25,
+				tone: "mid"
+			};
+			return {
+				opacity: .58,
+				scaleX: 1,
+				tone: "idle"
+			};
+		}
+		/** Tick colors: foreground for the hovered peak and the current turn at rest,
+		*  the subtlest text tone otherwise (ZCode bg-foreground / -subtlest parity
+		*  through system colors). */
+		const TICK_COLOR_FOREGROUND = "CanvasText";
+		const TICK_COLOR_SUBTLE = "color-mix(in srgb, CanvasText 42%, transparent)";
+		function useReducedMotion() {
+			const [reduced, setReduced] = (0, react.useState)(false);
+			(0, react.useEffect)(() => {
+				if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+				const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+				const update = () => setReduced(query.matches);
+				update();
+				query.addEventListener("change", update);
+				return () => query.removeEventListener("change", update);
+			}, []);
+			return reduced;
+		}
+		/**
+		* Render the question navigator rail.
+		* @param props - composed slot props.
+		* @returns the rail, or null when it should not render.
+		*/
+		function TimelineRail({ source, t }) {
+			const state = (0, react.useSyncExternalStore)(source.subscribe, source.getSnapshot);
+			const reducedMotion = useReducedMotion();
+			const probe = (0, react.useMemo)(() => typeof document === "undefined" ? null : probeChatDom(document), []);
+			const [containerVersion, setContainerVersion] = (0, react.useState)(0);
+			const [rect, setRect] = (0, react.useState)(null);
+			const [activeIndex, setActiveIndex] = (0, react.useState)(-1);
+			const [hoverIndex, setHoverIndex] = (0, react.useState)(void 0);
+			const [tipIndex, setTipIndex] = (0, react.useState)(void 0);
+			const timers = (0, react.useRef)({
+				open: void 0,
+				close: void 0
+			});
+			const frame = (0, react.useRef)(0);
+			const labels = (0, react.useMemo)(() => ({
+				userFallback: t("preview.userFallback"),
+				assistantEmpty: t("preview.assistantEmpty"),
+				assistantRunning: t("preview.assistantRunning")
+			}), [t]);
+			const snapshot = state.snapshot;
+			const items = (0, react.useMemo)(() => snapshot === null ? [] : buildTimelineItems(snapshot.nodes, snapshot.running, labels), [snapshot, labels]);
+			(0, react.useEffect)(() => {
+				if (typeof document === "undefined") return;
+				ensureStyles(document);
+			}, []);
+			(0, react.useEffect)(() => {
+				if (probe === null) return;
+				let attempts = 0;
+				let timer;
+				const tick = () => {
+					if (probe.getContainer() !== null || attempts >= 10) {
+						setContainerVersion((version) => version + 1);
+						return;
+					}
+					attempts += 1;
+					timer = setTimeout(tick, 300);
+				};
+				tick();
+				return () => {
+					if (timer !== void 0) clearTimeout(timer);
+				};
+			}, [probe, state.sessionId]);
+			(0, react.useEffect)(() => {
+				if (probe === null || containerVersion === 0) return;
+				const container = probe.getContainer();
+				if (container === null) {
+					setRect(null);
+					return;
+				}
+				const sync = () => {
+					if (frame.current !== 0) return;
+					frame.current = requestAnimationFrame(() => {
+						frame.current = 0;
+						const box = container.getBoundingClientRect();
+						setRect({
+							left: box.left,
+							top: box.top,
+							height: box.height,
+							width: box.width
+						});
+						setActiveIndex(probe.activeIndex());
+					});
+				};
+				sync();
+				container.addEventListener("scroll", sync, { passive: true });
+				const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(sync);
+				observer?.observe(container);
+				window.addEventListener("resize", sync);
+				return () => {
+					container.removeEventListener("scroll", sync);
+					observer?.disconnect();
+					window.removeEventListener("resize", sync);
+					if (frame.current !== 0) cancelAnimationFrame(frame.current);
+					frame.current = 0;
+				};
+			}, [probe, containerVersion]);
+			const visible = snapshot !== null && items.length >= 2 && rect !== null && rect.width >= MIN_CONTAINER_WIDTH;
+			const focusIndex = hoverIndex;
+			const scheduleTip = (0, react.useCallback)((index) => {
+				if (timers.current.open !== void 0) window.clearTimeout(timers.current.open);
+				if (timers.current.close !== void 0) window.clearTimeout(timers.current.close);
+				if (index === void 0) {
+					timers.current.close = window.setTimeout(() => setTipIndex(void 0), TIP_CLOSE_DELAY);
+					return;
+				}
+				timers.current.open = window.setTimeout(() => setTipIndex(index), TIP_OPEN_DELAY);
+			}, []);
+			(0, react.useEffect)(() => () => {
+				if (timers.current.open !== void 0) window.clearTimeout(timers.current.open);
+				if (timers.current.close !== void 0) window.clearTimeout(timers.current.close);
+			}, []);
+			const jump = (0, react.useCallback)((index) => {
+				probe?.jumpTo(index, reducedMotion ? "auto" : "smooth");
+			}, [probe, reducedMotion]);
+			if (!visible || probe === null || rect === null) return null;
+			const trackHeight = items.length * ITEM_PITCH;
+			const tip = tipIndex !== void 0 ? items[tipIndex] : void 0;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("nav", {
+				"aria-label": t("nav.label"),
+				className: "dsh-tl-nav",
+				"data-visible": visible ? "true" : "false",
+				"data-testid": "dsh-chat-timeline",
+				"data-item-count": items.length,
+				style: {
+					left: rect.left,
+					top: rect.top,
+					height: rect.height
+				},
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "dsh-tl-scroll",
+					onPointerLeave: () => {
+						setHoverIndex(void 0);
+						scheduleTip(void 0);
+					},
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "dsh-tl-track",
+						style: { height: `${trackHeight}px` },
+						children: items.map((item, index) => {
+							const isActive = index === activeIndex;
+							const look = ripple(focusIndex === void 0 ? 3 : Math.abs(index - focusIndex));
+							const activeAtRest = focusIndex === void 0 && isActive;
+							const foreground = look.tone === "peak" || activeAtRest;
+							const opacity = activeAtRest ? .9 : item.running ? Math.max(look.opacity, .72) : look.opacity;
+							return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "dsh-tl-slot",
+								style: { transform: `translateY(${index * ITEM_PITCH}px)` },
+								onMouseEnter: () => {
+									setHoverIndex(index);
+									scheduleTip(index);
+								},
+								onFocus: () => {
+									setHoverIndex(index);
+									scheduleTip(index);
+								},
+								onBlur: () => {
+									setHoverIndex(void 0);
+									scheduleTip(void 0);
+								},
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									"aria-current": isActive ? "location" : void 0,
+									"aria-label": t("nav.jumpToQuery", { index: String(index + 1) }),
+									"aria-posinset": index + 1,
+									"aria-setsize": items.length,
+									"data-testid": "dsh-chat-timeline-item",
+									"data-item-index": index,
+									"data-active": isActive ? "true" : "false",
+									"data-running": item.running ? "true" : "false",
+									onClick: () => jump(index),
+									className: "dsh-tl-slot-inner",
+									style: {
+										display: "flex",
+										alignItems: "center",
+										justifyContent: "flex-start",
+										width: "100%",
+										height: "100%",
+										padding: 0,
+										border: 0,
+										background: "transparent",
+										cursor: "pointer"
+									},
+									children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+										className: "dsh-tl-tick",
+										style: {
+											opacity,
+											transform: `scaleX(${look.scaleX})`,
+											backgroundColor: foreground ? TICK_COLOR_FOREGROUND : TICK_COLOR_SUBTLE
+										}
+									})
+								})
+							}, item.key);
+						})
+					})
+				})
+			}), tip !== void 0 && tipIndex !== void 0 ? (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TipCard, {
+				item: tip,
+				index: tipIndex,
+				rect,
+				t
+			}), document.body) : null] });
+		}
+		function TipCard({ item, index, rect, t }) {
+			const box = document.querySelector("[data-testid=\"dsh-chat-timeline-item\"][data-item-index=\"" + String(index) + "\"]")?.getBoundingClientRect();
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "dsh-tl-tip",
+				"data-testid": "dsh-chat-timeline-tip",
+				style: {
+					left: box === void 0 ? rect.left + 56 : Math.min(box.right + 8, window.innerWidth - 336),
+					top: box === void 0 ? rect.top + 100 : Math.max(8, Math.min(box.top - 4, window.innerHeight - 160))
+				},
+				role: "tooltip",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: "dsh-tl-tip-user",
+					children: item.userPreview
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: "dsh-tl-tip-assistant",
+					"data-kind": item.assistantKind,
+					children: item.assistantPreview
+				})]
+			});
+		}
+		//#endregion
+		//#region src/client/source.ts
+		const EMPTY_STATE = {
+			sessionId: void 0,
+			snapshot: null
+		};
+		/**
+		* Create the source. Subscribes to the sessions list, rebinds to the current
+		* session's snapshot feed on selection change, and republishes a stable state
+		* object whenever the underlying snapshot changes.
+		* @param sessions - the sessions service face (pass ctx.sessions).
+		* @returns the source face.
+		*/
+		function createTimelineSource(sessions) {
+			let state = EMPTY_STATE;
+			const listeners = /* @__PURE__ */ new Set();
+			let unbindSession = null;
+			let boundSessionId;
+			let retryTimer;
+			let retryAttempts = 0;
+			const emit = () => {
+				for (const listener of listeners) listener();
+			};
+			const rebind = () => {
+				if (retryTimer !== void 0) {
+					clearTimeout(retryTimer);
+					retryTimer = void 0;
+				}
+				let current;
+				try {
+					current = sessions.list.getSnapshot()?.current;
+				} catch {
+					current = void 0;
+				}
+				if (current === boundSessionId && retryAttempts === 0) return;
+				boundSessionId = current;
+				unbindSession?.();
+				unbindSession = null;
+				if (current === void 0) {
+					state = EMPTY_STATE;
+					emit();
+					return;
+				}
+				let session;
+				try {
+					session = sessions.binding(current)?.session;
+				} catch {
+					session = void 0;
+				}
+				if (!session) {
+					state = {
+						sessionId: current,
+						snapshot: null
+					};
+					if (retryAttempts < 10) {
+						retryAttempts += 1;
+						retryTimer = setTimeout(rebind, 500 * retryAttempts);
+					}
+					emit();
+					return;
+				}
+				retryAttempts = 0;
+				const push = () => {
+					try {
+						const snap = session.getSnapshot();
+						state = {
+							sessionId: current,
+							snapshot: {
+								sessionId: current,
+								nodes: Array.isArray(snap?.nodes) ? snap.nodes : [],
+								running: Boolean(snap?.running)
+							}
+						};
+					} catch {
+						state = {
+							sessionId: current,
+							snapshot: null
+						};
+					}
+					emit();
+				};
+				push();
+				try {
+					session.subscribe(push);
+					unbindSession = () => {};
+				} catch {
+					unbindSession = null;
+				}
+			};
+			return {
+				subscribe(listener) {
+					const first = listeners.size === 0;
+					listeners.add(listener);
+					if (first) {
+						try {
+							sessions.list.subscribe(rebind);
+						} catch {}
+						rebind();
+					}
+					return () => {
+						listeners.delete(listener);
+					};
+				},
+				getSnapshot() {
+					return state;
+				}
+			};
+		}
+		/** Build the source from the plugin client context. */
+		function timelineSourceFromContext(ctx) {
+			return createTimelineSource(ctx.sessions);
+		}
+		//#endregion
+		//#region src/client/locales.ts
+		/**
+		* Locale dictionaries for the chat-timeline plugin. `zh` is the key-set source
+		* of truth; `en` keeps a full key-for-key mirror. Registered through
+		* ctx.locale.register(NS, { zh, en }).
+		*/
+		/** Simplified Chinese dictionary (key-set source of truth). */
+		const zh = {
+			"nav.label": "对话问题导航",
+			"nav.jumpToQuery": "跳转到第 {index} 条问题",
+			"preview.userFallback": "用户输入",
+			"preview.assistantEmpty": "暂无助手正文",
+			"preview.assistantRunning": "助手仍在工作"
+		};
+		/** English dictionary, key-for-key complete against zh. */
+		const en = {
+			"nav.label": "Conversation question navigator",
+			"nav.jumpToQuery": "Jump to question {index}",
+			"preview.userFallback": "User input",
+			"preview.assistantEmpty": "No assistant text yet",
+			"preview.assistantRunning": "Assistant is still working"
+		};
+		//#endregion
+		//#region src/client/index.ts
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "chat-timeline";
+		/** Unique occupant id inside the shared shell.overlay list slot. */
+		const ENTRY_ID = "chat-timeline";
+		/** Services required by this plugin. */
+		const inject = [
+			"slots",
+			"locale",
+			"sessions"
+		];
+		/**
+		* Register the timeline surface.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => {
+				try {
+					return ctx.locale.register(NS, {
+						zh,
+						en
+					});
+				} catch {
+					return () => {};
+				}
+			}, "chat-timeline: dictionaries");
+			ctx.slots.inject("shell.overlay", () => {
+				try {
+					return ctx.slots.register({
+						name: "shell.overlay",
+						id: ENTRY_ID,
+						locale: NS,
+						inject: () => ({ source: timelineSourceFromContext(ctx) })
+					}, TimelineRail);
+				} catch {
+					return () => {};
+				}
+			});
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../src/client/directory.ts","../src/client/dom.ts","../src/client/styles.ts","../src/client/rail.tsx","../src/client/source.ts","../src/client/locales.ts","../src/client/index.ts"],"sourcesContent":["/**\n * Timeline directory derivation — the pure core of the plugin.\n *\n * Turns the conversation snapshot's ordered node list into one tick per human\n * input (`user` / `steering`), each carrying a trimmed user preview plus the\n * assistant reply preview in one of three states (text / running / empty).\n * Preview budgeting replicates the ZCode TurnNavigator: at most two\n * paragraphs, whitespace-collapsed, truncated to 220 characters.\n *\n * No DOM, no React, no dsh runtime imports — everything here is plain data so\n * vitest can cover it without fixtures beyond plain objects.\n */\n\n/** Minimal structural shape of a conversation node this module needs. */\nexport interface TimelineNodeLike {\n  kind: string\n  seq: number\n  /** Unix epoch ms when present. */\n  time?: number\n  /** User/steering content blocks (each `{ kind, text? }`-like). */\n  content?: readonly unknown[]\n  /** Assistant content blocks (each `{ kind, text? }`-like). */\n  blocks?: readonly unknown[]\n}\n\n/** One tick in the timeline directory. */\nexport interface TimelineItem {\n  /** Stable React key (`n<seq>`). */\n  readonly key: string\n  /** Seq of the anchoring human node. */\n  readonly seq: number\n  /** Anchor time (epoch ms); 0 when unknown. */\n  readonly time: number\n  /** Trimmed human input preview. */\n  readonly userPreview: string\n  /** True when the human node carried no extractable text. */\n  readonly userFallback: boolean\n  /** Trimmed assistant reply preview. */\n  readonly assistantPreview: string\n  /** Which assistant preview state applies. */\n  readonly assistantKind: 'text' | 'running' | 'empty'\n  /** True for the last tick while the session is still running. */\n  readonly running: boolean\n}\n\n/** Copy labels the derivation needs (kept out of the pure math for testability). */\nexport interface TimelineLabels {\n  readonly userFallback: string\n  readonly assistantEmpty: string\n  readonly assistantRunning: string\n}\n\n/** Preview budget: at most two paragraphs and 220 characters (ZCode parity). */\nexport const MAX_PREVIEW_CHARS = 220\nexport const MAX_PREVIEW_PARAGRAPHS = 2\n\n/** Human node kinds that anchor a tick. */\nconst HUMAN_KINDS = new Set(['user', 'steering'])\n\n/** Extract concatenated text from a ContentBlock-like list.\n *  dsh-llm content blocks switch on `type`; assistant blocks use `kind` — accept both. */\nexport function blocksText(blocks: readonly unknown[] | undefined): string {\n  if (!Array.isArray(blocks)) return ''\n  const parts: string[] = []\n  for (const block of blocks) {\n    if (block !== null && typeof block === 'object') {\n      const record = block as { kind?: unknown; type?: unknown; text?: unknown }\n      if (record.kind === 'text' || record.type === 'text') {\n        if (typeof record.text === 'string' && record.text.length > 0) parts.push(record.text)\n      }\n    }\n  }\n  return parts.join('\\n\\n')\n}\n\n/** Collapse each paragraph's whitespace and drop empties (ZCode u5e parity). */\nexport function collapseParagraphs(text: string, maxParagraphs: number): string[] {\n  return text\n    .trim()\n    .split(/\\n\\s*\\n/u)\n    .map((paragraph) => paragraph.replace(/\\s+/gu, ' ').trim())\n    .filter(Boolean)\n    .slice(0, Math.max(1, maxParagraphs))\n}\n\n/** Truncate to the budget with an ellipsis, never below the floor (ZCode d5e parity). */\nexport function truncatePreview(text: string, maxChars: number, floor = 8): string {\n  const budget = Math.max(floor, maxChars)\n  if (text.length <= budget) return text\n  return `${text.slice(0, budget - 3).trimEnd()}...`\n}\n\n/** Build one preview string from raw texts under the shared budget. */\nexport function buildPreview(texts: readonly string[], fallback: string): string {\n  const paragraphs = collapseParagraphs(texts.join('\\n\\n'), MAX_PREVIEW_PARAGRAPHS)\n  if (paragraphs.length === 0) return fallback\n  return truncatePreview(paragraphs.join('\\n'), MAX_PREVIEW_CHARS)\n}\n\n/**\n * Derive the tick directory from the snapshot's ordered node list.\n * @param nodes - conversation snapshot nodes in seq order.\n * @param running - whether the session currently has a running turn.\n * @param labels - localized preview fallbacks.\n * @returns one item per human input, in order.\n */\nexport function buildTimelineItems(\n  nodes: readonly TimelineNodeLike[],\n  running: boolean,\n  labels: TimelineLabels,\n): TimelineItem[] {\n  interface Draft {\n    key: string\n    seq: number\n    time: number\n    userTexts: string[]\n    hasUserText: boolean\n    assistantTexts: string[]\n  }\n  const drafts: Draft[] = []\n  for (const node of nodes) {\n    if (HUMAN_KINDS.has(node.kind)) {\n      const text = blocksText(node.content)\n      drafts.push({\n        key: `n${node.seq}`,\n        seq: node.seq,\n        time: typeof node.time === 'number' ? node.time : 0,\n        userTexts: text === '' ? [] : [text],\n        hasUserText: text !== '',\n        assistantTexts: [],\n      })\n      continue\n    }\n    if (node.kind !== 'assistant' || drafts.length === 0) continue\n    const text = blocksText(node.blocks)\n    if (text !== '') drafts[drafts.length - 1].assistantTexts.push(text)\n  }\n  const last = drafts.length - 1\n  return drafts.map((draft, index) => {\n    const isLive = running && index === last\n    const assistantTexts = draft.assistantTexts\n    const assistantKind: TimelineItem['assistantKind'] = assistantTexts.length > 0\n      ? 'text'\n      : isLive\n        ? 'running'\n        : 'empty'\n    return {\n      key: draft.key,\n      seq: draft.seq,\n      time: draft.time,\n      userPreview: buildPreview(draft.userTexts, labels.userFallback),\n      userFallback: !draft.hasUserText,\n      assistantPreview: buildPreview(assistantTexts, isLive ? labels.assistantRunning : labels.assistantEmpty),\n      assistantKind,\n      running: isLive,\n    }\n  })\n}\n","/**\n * Chat DOM probe — the only module allowed to know DSH's internal chat DOM.\n *\n * Contract measured on dsh 0.1.1-rc.2 (see .scratch/chat-timeline/issues/03):\n * the scroll container carries `data-conversation-scroll`; each flow row is a\n * `[data-chat-flow-kind]` element whose `user` kind marks a human turn, in the\n * same seq order as the snapshot's user nodes. Every access is defensive:\n * when detection fails the probe degrades to a no-op rail (no jump, no\n * highlight) instead of throwing.\n */\n\n/** Read-only view of the chat DOM the rail interacts with. */\nexport interface ChatDomProbe {\n  /** The chat scroll container, or null when not found. */\n  getContainer(): HTMLElement | null\n  /** Human-turn row elements in document order (user kind only). */\n  getUserRows(): HTMLElement[]\n  /** Index of the human turn nearest the viewport top, or -1. */\n  activeIndex(): number\n  /** Scroll the given human turn into view; false when unavailable. */\n  jumpTo(index: number, behavior: ScrollBehavior): boolean\n}\n\n/**\n * Find the chat scroll container with a candidate chain.\n * 1. the explicit stable hook `[data-conversation-scroll]`;\n * 2. the closest scrollable ancestor of the flow column `[data-chat-flow]`;\n * 3. the largest scrollable element that contains human rows.\n */\nexport function findChatContainer(doc: Document): HTMLElement | null {\n  const direct = doc.querySelector<HTMLElement>('[data-conversation-scroll]')\n  if (direct !== null) return direct\n  const flow = doc.querySelector<HTMLElement>('[data-chat-flow]')\n  const ancestor = flow !== null ? scrollableAncestor(flow) : null\n  if (ancestor !== null) return ancestor\n  let best: HTMLElement | null = null\n  let bestHeight = 0\n  for (const element of Array.from(doc.querySelectorAll<HTMLElement>('*'))) {\n    if (!isScrollable(element)) continue\n    if (element.querySelector('[data-chat-flow-kind=\"user\"]') === null) continue\n    const height = element.clientHeight\n    if (height > bestHeight) {\n      best = element\n      bestHeight = height\n    }\n  }\n  return best\n}\n\nfunction isScrollable(element: HTMLElement): boolean {\n  const style = element.ownerDocument.defaultView?.getComputedStyle(element)\n  if (style === undefined) return false\n  if (!/(auto|scroll)/.test(style.overflowY)) return false\n  return element.scrollHeight > element.clientHeight + 40 && element.clientHeight > 200\n}\n\nfunction scrollableAncestor(element: HTMLElement): HTMLElement | null {\n  let node: HTMLElement | null = element\n  while (node !== null) {\n    if (isScrollable(node)) return node\n    node = node.parentElement\n  }\n  return null\n}\n\n/** Human-turn rows inside the container (falling back to a document-wide query). */\nexport function findUserRows(container: HTMLElement | null): HTMLElement[] {\n  const scope: ParentNode = container ?? document\n  return Array.from(scope.querySelectorAll<HTMLElement>('[data-chat-flow-kind=\"user\"]'))\n}\n\n/**\n * The active index: the last human row whose top edge sits above the\n * container's reading line (40px below the top edge), matching the ZCode\n * \"unit at viewport top\" rule; clamps to the last row at scroll bottom.\n */\nexport function computeActiveIndex(container: HTMLElement, rows: readonly HTMLElement[]): number {\n  if (rows.length === 0) return -1\n  const top = container.getBoundingClientRect().top + 40\n  let active = 0\n  for (let index = 0; index < rows.length; index += 1) {\n    if (rows[index].getBoundingClientRect().top <= top) active = index\n    else break\n  }\n  const distanceToBottom = container.scrollHeight - container.scrollTop - container.clientHeight\n  if (distanceToBottom <= 4) return rows.length - 1\n  return active\n}\n\n/**\n * Scroll the given human turn into view. Tries a smooth scroll first; DSH's\n * windowed conversation list programs scrollTop on scroll events, which can\n * cancel a smooth animation on the first frame — when nothing has moved after\n * a short grace period the jump falls back to an instant scroll.\n * @returns false when the container or row is unavailable.\n */\nfunction jumpTo(index: number, behavior: ScrollBehavior): boolean {\n  const container = findChatContainer(document)\n  if (container === null) return false\n  const row = findUserRows(container)[index]\n  if (row === undefined) return false\n  const delta = row.getBoundingClientRect().top - container.getBoundingClientRect().top - 12\n  const target = container.scrollTop + delta\n  if (behavior === 'auto') {\n    container.scrollTo({ top: target, behavior: 'auto' })\n    return true\n  }\n  const startedAt = container.scrollTop\n  container.scrollTo({ top: target, behavior: 'smooth' })\n  window.setTimeout(() => {\n    // Still within a few pixels of the start after the grace period: the\n    // smooth animation was cancelled — land instantly instead.\n    if (Math.abs(container.scrollTop - startedAt) < 4) {\n      container.scrollTo({ top: target, behavior: 'auto' })\n    }\n  }, 700)\n  return true\n}\n\n/** Create the probe against a document (injectable for tests). */\nexport function probeChatDom(doc: Document): ChatDomProbe {\n  return {\n    getContainer: () => findChatContainer(doc),\n    getUserRows: () => findUserRows(findChatContainer(doc)),\n    activeIndex: () => {\n      const container = findChatContainer(doc)\n      if (container === null) return -1\n      return computeActiveIndex(container, findUserRows(container))\n    },\n    jumpTo: (index: number, behavior: ScrollBehavior) => jumpTo(index, behavior),\n  }\n}\n","/**\n * Stylesheet for the chat-timeline rail, injected once as a\n * `<style data-plugin-css=\"chat-timeline\">` tag. All classes carry the\n * `dsh-tl-` prefix; colors use the CSS system colors Canvas/CanvasText so the\n * rail follows the app's color-scheme without reaching into DSH theme tokens.\n * Visual constants replicate the ZCode TurnNavigator (spec section 2.2).\n */\nexport const TIMELINE_STYLES = `\n.dsh-tl-nav {\n  position: fixed;\n  z-index: 10;\n  width: 48px;\n  pointer-events: none;\n  opacity: 1;\n  transition: opacity 150ms ease-out;\n}\n.dsh-tl-nav[data-visible=\"false\"] {\n  opacity: 0;\n  visibility: hidden;\n}\n.dsh-tl-scroll {\n  position: absolute;\n  left: 12px;\n  top: 50%;\n  transform: translateY(-50%);\n  width: 36px;\n  max-height: calc(100% - 96px);\n  overflow-x: hidden;\n  overflow-y: auto;\n  padding-block: 4px;\n  pointer-events: auto;\n  scrollbar-width: none;\n  color: CanvasText;\n}\n.dsh-tl-scroll::-webkit-scrollbar {\n  display: none;\n}\n.dsh-tl-track {\n  position: relative;\n  width: 36px;\n}\n.dsh-tl-slot {\n  position: absolute;\n  left: 0;\n  top: 0;\n  height: 10px;\n  width: 36px;\n  padding: 0;\n  border: 0;\n  background: transparent;\n  display: flex;\n  align-items: center;\n  justify-content: flex-start;\n  border-radius: 2px;\n  cursor: pointer;\n}\n.dsh-tl-slot:focus-visible {\n  outline: 2px solid CanvasText;\n  outline-offset: 2px;\n}\n.dsh-tl-tick {\n  display: block;\n  height: 2px;\n  width: 12px;\n  border-radius: 999px;\n  background: currentColor;\n  transform-origin: left center;\n  transition: height 150ms ease-out, opacity 150ms ease-out, transform 150ms ease-out, background-color 150ms ease-out;\n}\n@media (prefers-reduced-motion: reduce) {\n  .dsh-tl-nav,\n  .dsh-tl-tick {\n    transition: none;\n  }\n}\n.dsh-tl-tip {\n  position: fixed;\n  z-index: 60;\n  width: 320px;\n  max-width: calc(100vw - 2rem);\n  padding: 12px;\n  border-radius: 10px;\n  background: Canvas;\n  color: CanvasText;\n  border: 1px solid color-mix(in srgb, CanvasText 15%, transparent);\n  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);\n  pointer-events: none;\n}\n.dsh-tl-tip-user {\n  margin: 0;\n  display: -webkit-box;\n  -webkit-box-orient: vertical;\n  -webkit-line-clamp: 2;\n  overflow: hidden;\n  white-space: pre-line;\n  font-size: 13px;\n  line-height: 20px;\n  font-weight: 500;\n}\n.dsh-tl-tip-assistant {\n  margin: 8px 0 0;\n  display: -webkit-box;\n  -webkit-box-orient: vertical;\n  -webkit-line-clamp: 3;\n  overflow: hidden;\n  white-space: pre-line;\n  font-size: 13px;\n  line-height: 20px;\n  opacity: 0.8;\n}\n.dsh-tl-tip-assistant[data-kind=\"running\"],\n.dsh-tl-tip-assistant[data-kind=\"empty\"] {\n  opacity: 0.55;\n}\n`\n\n/** Inject the stylesheet once per document. */\nexport function ensureStyles(doc: Document): void {\n  const tagId = 'chat-timeline'\n  if (doc.querySelector('style[data-plugin-css=\"chat-timeline\"]') !== null) return\n  const tag = doc.createElement('style')\n  tag.dataset.plugin = '@lament_z/dsh-client-ui-chat-timeline'\n  tag.dataset.pluginCss = tagId\n  tag.textContent = TIMELINE_STYLES\n  doc.head.appendChild(tag)\n}\n","/**\n * TimelineRail — the shell.overlay entry: a left-edge tick rail over the\n * conversation, one tick per human question. Visual and interaction constants\n * replicate the ZCode TurnNavigator (see .scratch/chat-timeline/spec.md):\n * hover ripple scaleX 2.6/1.7/1.25 with opacity 1/.86/.72/.58 over 150ms,\n * 320px preview cards after a 120ms delay, >=2 questions to render, >=864px\n * container width, prefers-reduced-motion fallback, full aria labelling.\n */\nimport { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'\nimport { createPortal } from 'react-dom'\nimport type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'\nimport { buildTimelineItems, type TimelineItem, type TimelineLabels } from './directory.ts'\nimport type { TimelineKey } from './locales.ts'\nimport { probeChatDom, type ChatDomProbe } from './dom.ts'\nimport { ensureStyles } from './styles.ts'\nimport type { TimelineSource } from './source.ts'\n\n/** Component props: the locale seat plus the injected session source. */\nexport type TimelineRailProps = PropsLocale<'chat-timeline'> & {\n  /** The current-session snapshot source (built from ctx.sessions). */\n  source: TimelineSource\n}\n\n/** Slot height per tick (10px pitch, ZCode parity). */\nconst ITEM_PITCH = 10\n/** Container width below which the rail hides. ZCode uses 864px, but DSH's\n *  three-pane layout leaves the conversation narrower — the rail overlays the\n *  left edge without taking layout space, so only truly cramped panes hide. */\nconst MIN_CONTAINER_WIDTH = 560\n/** Preview-card hover delays (ms). */\nconst TIP_OPEN_DELAY = 120\nconst TIP_CLOSE_DELAY = 80\n\ninterface Rect {\n  left: number\n  top: number\n  height: number\n  width: number\n}\n\n/** Ripple visual per distance from the hovered tick (ZCode _5e parity).\n *  The ripple is interaction-only: at rest every tick is idle (scaleX 1),\n *  and the current position is signalled by color/opacity, not length. */\nfunction ripple(distance: number): { opacity: number; scaleX: number; tone: 'peak' | 'near' | 'mid' | 'idle' } {\n  if (distance === 0) return { opacity: 1, scaleX: 2.6, tone: 'peak' }\n  if (distance === 1) return { opacity: 0.86, scaleX: 1.7, tone: 'near' }\n  if (distance === 2) return { opacity: 0.72, scaleX: 1.25, tone: 'mid' }\n  return { opacity: 0.58, scaleX: 1, tone: 'idle' }\n}\n\n/** Tick colors: foreground for the hovered peak and the current turn at rest,\n *  the subtlest text tone otherwise (ZCode bg-foreground / -subtlest parity\n *  through system colors). */\nconst TICK_COLOR_FOREGROUND = 'CanvasText'\nconst TICK_COLOR_SUBTLE = 'color-mix(in srgb, CanvasText 42%, transparent)'\n\nfunction useReducedMotion(): boolean {\n  const [reduced, setReduced] = useState(false)\n  useEffect(() => {\n    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return\n    const query = window.matchMedia('(prefers-reduced-motion: reduce)')\n    const update = () => setReduced(query.matches)\n    update()\n    query.addEventListener('change', update)\n    return () => query.removeEventListener('change', update)\n  }, [])\n  return reduced\n}\n\n/**\n * Render the question navigator rail.\n * @param props - composed slot props.\n * @returns the rail, or null when it should not render.\n */\nexport function TimelineRail({ source, t }: TimelineRailProps) {\n  const state = useSyncExternalStore(source.subscribe, source.getSnapshot)\n  const reducedMotion = useReducedMotion()\n  const probe = useMemo<ChatDomProbe | null>(() => (typeof document === 'undefined' ? null : probeChatDom(document)), [])\n  const [containerVersion, setContainerVersion] = useState(0)\n  const [rect, setRect] = useState<Rect | null>(null)\n  const [activeIndex, setActiveIndex] = useState(-1)\n  const [hoverIndex, setHoverIndex] = useState<number | undefined>(undefined)\n  const [tipIndex, setTipIndex] = useState<number | undefined>(undefined)\n  const timers = useRef<{ open: number | undefined; close: number | undefined }>({ open: undefined, close: undefined })\n  const frame = useRef(0)\n\n  const labels: TimelineLabels = useMemo(\n    () => ({\n      userFallback: t('preview.userFallback'),\n      assistantEmpty: t('preview.assistantEmpty'),\n      assistantRunning: t('preview.assistantRunning'),\n    }),\n    [t],\n  )\n\n  const snapshot = state.snapshot\n  const items = useMemo<TimelineItem[]>(\n    () => (snapshot === null ? [] : buildTimelineItems(snapshot.nodes as never[], snapshot.running, labels)),\n    [snapshot, labels],\n  )\n\n  useEffect(() => {\n    if (typeof document === 'undefined') return\n    ensureStyles(document)\n  }, [])\n\n  // Find the chat container: re-probe when the session changes and briefly\n  // afterwards (the conversation mounts a beat later than the selection).\n  useEffect(() => {\n    if (probe === null) return\n    let attempts = 0\n    let timer: ReturnType<typeof setTimeout> | undefined\n    const tick = () => {\n      const container = probe.getContainer()\n      if (container !== null || attempts >= 10) {\n        setContainerVersion((version) => version + 1)\n        return\n      }\n      attempts += 1\n      timer = setTimeout(tick, 300)\n    }\n    tick()\n    return () => {\n      if (timer !== undefined) clearTimeout(timer)\n    }\n  }, [probe, state.sessionId])\n\n  // Attach scroll/size watchers to the container once found.\n  useEffect(() => {\n    if (probe === null || containerVersion === 0) return\n    const container = probe.getContainer()\n    if (container === null) {\n      setRect(null)\n      return\n    }\n    const sync = () => {\n      if (frame.current !== 0) return\n      frame.current = requestAnimationFrame(() => {\n        frame.current = 0\n        const box = container.getBoundingClientRect()\n        setRect({ left: box.left, top: box.top, height: box.height, width: box.width })\n        setActiveIndex(probe.activeIndex())\n      })\n    }\n    sync()\n    container.addEventListener('scroll', sync, { passive: true })\n    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(sync)\n    observer?.observe(container)\n    window.addEventListener('resize', sync)\n    return () => {\n      container.removeEventListener('scroll', sync)\n      observer?.disconnect()\n      window.removeEventListener('resize', sync)\n      if (frame.current !== 0) cancelAnimationFrame(frame.current)\n      frame.current = 0\n    }\n  }, [probe, containerVersion])\n\n  const visible = snapshot !== null && items.length >= 2 && rect !== null && rect.width >= MIN_CONTAINER_WIDTH\n  // The ripple follows the pointer only (ZCode v5e parity): at rest every tick\n  // is equal length and the current turn stands out by color/opacity alone.\n  const focusIndex = hoverIndex\n\n  const scheduleTip = useCallback((index: number | undefined) => {\n    if (timers.current.open !== undefined) window.clearTimeout(timers.current.open)\n    if (timers.current.close !== undefined) window.clearTimeout(timers.current.close)\n    if (index === undefined) {\n      timers.current.close = window.setTimeout(() => setTipIndex(undefined), TIP_CLOSE_DELAY)\n      return\n    }\n    timers.current.open = window.setTimeout(() => setTipIndex(index), TIP_OPEN_DELAY)\n  }, [])\n\n  useEffect(() => () => {\n    if (timers.current.open !== undefined) window.clearTimeout(timers.current.open)\n    if (timers.current.close !== undefined) window.clearTimeout(timers.current.close)\n  }, [])\n\n  const jump = useCallback((index: number) => {\n    probe?.jumpTo(index, reducedMotion ? 'auto' : 'smooth')\n  }, [probe, reducedMotion])\n\n  if (!visible || probe === null || rect === null) return null\n\n  const trackHeight = items.length * ITEM_PITCH\n  const tip = tipIndex !== undefined ? items[tipIndex] : undefined\n\n  return (\n    <>\n      <nav\n        aria-label={t('nav.label')}\n        className=\"dsh-tl-nav\"\n        data-visible={visible ? 'true' : 'false'}\n        data-testid=\"dsh-chat-timeline\"\n        data-item-count={items.length}\n        style={{ left: rect.left, top: rect.top, height: rect.height }}\n      >\n        <div\n          className=\"dsh-tl-scroll\"\n          onPointerLeave={() => {\n            setHoverIndex(undefined)\n            scheduleTip(undefined)\n          }}\n        >\n          <div className=\"dsh-tl-track\" style={{ height: `${trackHeight}px` }}>\n            {items.map((item, index) => {\n              const isActive = index === activeIndex\n              const distance = focusIndex === undefined ? 3 : Math.abs(index - focusIndex)\n              const look = ripple(distance)\n              const activeAtRest = focusIndex === undefined && isActive\n              const foreground = look.tone === 'peak' || activeAtRest\n              const opacity = activeAtRest\n                ? 0.9\n                : item.running\n                  ? Math.max(look.opacity, 0.72)\n                  : look.opacity\n              return (\n                <div\n                  key={item.key}\n                  className=\"dsh-tl-slot\"\n                  style={{ transform: `translateY(${index * ITEM_PITCH}px)` }}\n                  onMouseEnter={() => {\n                    setHoverIndex(index)\n                    scheduleTip(index)\n                  }}\n                  onFocus={() => {\n                    setHoverIndex(index)\n                    scheduleTip(index)\n                  }}\n                  onBlur={() => {\n                    setHoverIndex(undefined)\n                    scheduleTip(undefined)\n                  }}\n                >\n                  <button\n                    type=\"button\"\n                    aria-current={isActive ? 'location' : undefined}\n                    aria-label={t('nav.jumpToQuery', { index: String(index + 1) })}\n                    aria-posinset={index + 1}\n                    aria-setsize={items.length}\n                    data-testid=\"dsh-chat-timeline-item\"\n                    data-item-index={index}\n                    data-active={isActive ? 'true' : 'false'}\n                    data-running={item.running ? 'true' : 'false'}\n                    onClick={() => jump(index)}\n                    className=\"dsh-tl-slot-inner\"\n                    style={{\n                      display: 'flex',\n                      alignItems: 'center',\n                      justifyContent: 'flex-start',\n                      width: '100%',\n                      height: '100%',\n                      padding: 0,\n                      border: 0,\n                      background: 'transparent',\n                      cursor: 'pointer',\n                    }}\n                  >\n                    <span\n                      className=\"dsh-tl-tick\"\n                      style={{\n                        opacity,\n                        transform: `scaleX(${look.scaleX})`,\n                        backgroundColor: foreground ? TICK_COLOR_FOREGROUND : TICK_COLOR_SUBTLE,\n                      }}\n                    />\n                  </button>\n                </div>\n              )\n            })}\n          </div>\n        </div>\n      </nav>\n      {tip !== undefined && tipIndex !== undefined\n        ? createPortal(\n            <TipCard item={tip} index={tipIndex} rect={rect} t={t} />,\n            document.body,\n          )\n        : null}\n    </>\n  )\n}\n\nfunction TipCard({ item, index, rect, t }: {\n  item: TimelineItem\n  index: number\n  rect: Rect\n  t: (key: TimelineKey, params?: Record<string, string | number>) => string\n}) {\n  const slot = document.querySelector<HTMLElement>('[data-testid=\"dsh-chat-timeline-item\"][data-item-index=\"' + String(index) + '\"]')\n  const box = slot?.getBoundingClientRect()\n  const left = box === undefined ? rect.left + 56 : Math.min(box.right + 8, window.innerWidth - 336)\n  const top = box === undefined ? rect.top + 100 : Math.max(8, Math.min(box.top - 4, window.innerHeight - 160))\n  return (\n    <div\n      className=\"dsh-tl-tip\"\n      data-testid=\"dsh-chat-timeline-tip\"\n      style={{ left, top }}\n      role=\"tooltip\"\n    >\n      <p className=\"dsh-tl-tip-user\">{item.userPreview}</p>\n      <p className=\"dsh-tl-tip-assistant\" data-kind={item.assistantKind}>{item.assistantPreview}</p>\n    </div>\n  )\n}\n","/**\n * Timeline source: follows the current session through the cordis services\n * face (ctx.sessions) and exposes a useSyncExternalStore-compatible read\n * face over its ConversationSnapshot. All dsh-client-runtime usage here is\n * type-only; at runtime everything is reached through the ctx services, so\n * the client bundle stays free of cross-package value imports.\n */\nimport type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'\n\n/** The slice of ConversationSnapshot the timeline consumes. */\nexport interface TimelineSnapshot {\n  readonly sessionId: string\n  /** Ordered conversation nodes (the snapshot's legacy compatibility field). */\n  readonly nodes: readonly unknown[]\n  /** Whether the session currently has a running turn. */\n  readonly running: boolean\n}\n\n/** State handed to React: null snapshot means \"no readable session right now\". */\nexport interface TimelineState {\n  readonly sessionId: string | undefined\n  readonly snapshot: TimelineSnapshot | null\n}\n\n/** useSyncExternalStore-compatible source face. */\nexport interface TimelineSource {\n  subscribe(listener: () => void): () => void\n  getSnapshot(): TimelineState\n}\n\ninterface ObservableLike<T> {\n  getSnapshot(): T\n  subscribe(listener: () => void): () => void\n}\n\n/** Structural face of ctx.sessions this module needs (kept narrow for tests). */\nexport interface SessionsLike {\n  readonly list: ObservableLike<{ current?: string }>\n  binding(id: string): { session: ObservableLike<{ nodes?: readonly unknown[]; running?: boolean }> } | undefined\n}\n\nconst EMPTY_STATE: TimelineState = { sessionId: undefined, snapshot: null }\n\n/**\n * Create the source. Subscribes to the sessions list, rebinds to the current\n * session's snapshot feed on selection change, and republishes a stable state\n * object whenever the underlying snapshot changes.\n * @param sessions - the sessions service face (pass ctx.sessions).\n * @returns the source face.\n */\nexport function createTimelineSource(sessions: SessionsLike): TimelineSource {\n  let state: TimelineState = EMPTY_STATE\n  const listeners = new Set<() => void>()\n  let unbindSession: (() => void) | null = null\n  let boundSessionId: string | undefined\n  let retryTimer: ReturnType<typeof setTimeout> | undefined\n  let retryAttempts = 0\n\n  const emit = () => {\n    for (const listener of listeners) listener()\n  }\n\n  const rebind = () => {\n    if (retryTimer !== undefined) {\n      clearTimeout(retryTimer)\n      retryTimer = undefined\n    }\n    let current: string | undefined\n    try {\n      current = sessions.list.getSnapshot()?.current\n    } catch {\n      current = undefined\n    }\n    if (current === boundSessionId && retryAttempts === 0) return\n    boundSessionId = current\n    unbindSession?.()\n    unbindSession = null\n    if (current === undefined) {\n      state = EMPTY_STATE\n      emit()\n      return\n    }\n    let session: ObservableLike<{ nodes?: readonly unknown[]; running?: boolean }> | undefined\n    try {\n      session = sessions.binding(current)?.session\n    } catch {\n      session = undefined\n    }\n    if (!session) {\n      // Listed but not yet scoped (cold boot): keep an empty state and retry\n      // with backoff so the rail appears once the binding lands.\n      state = { sessionId: current, snapshot: null }\n      if (retryAttempts < 10) {\n        retryAttempts += 1\n        retryTimer = setTimeout(rebind, 500 * retryAttempts)\n      }\n      emit()\n      return\n    }\n    retryAttempts = 0\n    const push = () => {\n      try {\n        const snap = session.getSnapshot()\n        state = {\n          sessionId: current,\n          snapshot: {\n            sessionId: current,\n            nodes: Array.isArray(snap?.nodes) ? snap.nodes : [],\n            running: Boolean(snap?.running),\n          },\n        }\n      } catch {\n        state = { sessionId: current, snapshot: null }\n      }\n      emit()\n    }\n    push()\n    try {\n      session.subscribe(push)\n      unbindSession = () => {\n        // Observable faces expose no unsubscribe disposer contract here; the\n        // subscription rides the plugin fiber and is torn down with it.\n      }\n    } catch {\n      unbindSession = null\n    }\n  }\n\n  return {\n    subscribe(listener: () => void): () => void {\n      const first = listeners.size === 0\n      listeners.add(listener)\n      if (first) {\n        try {\n          sessions.list.subscribe(rebind)\n        } catch {\n          // Service unavailable: the rail stays hidden, nothing throws.\n        }\n        rebind()\n      }\n      return () => {\n        listeners.delete(listener)\n      }\n    },\n    getSnapshot(): TimelineState {\n      return state\n    },\n  }\n}\n\n/** Build the source from the plugin client context. */\nexport function timelineSourceFromContext(ctx: ClientContext): TimelineSource {\n  return createTimelineSource(ctx.sessions as unknown as SessionsLike)\n}\n","/**\n * Locale dictionaries for the chat-timeline plugin. `zh` is the key-set source\n * of truth; `en` keeps a full key-for-key mirror. Registered through\n * ctx.locale.register(NS, { zh, en }).\n */\n\n/** Simplified Chinese dictionary (key-set source of truth). */\nexport const zh = {\n  'nav.label': '对话问题导航',\n  'nav.jumpToQuery': '跳转到第 {index} 条问题',\n  'preview.userFallback': '用户输入',\n  'preview.assistantEmpty': '暂无助手正文',\n  'preview.assistantRunning': '助手仍在工作',\n}\n\n/** The chat-timeline namespace key union. */\nexport type TimelineKey = keyof typeof zh\n\n/** English dictionary, key-for-key complete against zh. */\nexport const en: Record<TimelineKey, string> = {\n  'nav.label': 'Conversation question navigator',\n  'nav.jumpToQuery': 'Jump to question {index}',\n  'preview.userFallback': 'User input',\n  'preview.assistantEmpty': 'No assistant text yet',\n  'preview.assistantRunning': 'Assistant is still working',\n}\n","/**\n * Chat-timeline plugin — browser half. Registers the `chat-timeline` locale\n * dictionaries and a `shell.overlay` entry that renders the question\n * navigator rail beside the conversation. Export discipline: the /client\n * surface carries only what cordis loading needs plus types.\n */\nimport type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'\n// Type-only: pulls the locale plugin's Context merge (ctx.locale) and its\n// LocaleNamespaceMap merge table.\nimport type {} from '@deepseek-ai/dsh-client-locale/client'\n// Type-only: pulls the ui-layout SlotMap merge (the 'shell.overlay' hole).\nimport type {} from '@deepseek-ai/dsh-client-ui-layout/client'\nimport { TimelineRail } from './rail.tsx'\nimport { timelineSourceFromContext } from './source.ts'\nimport { en, zh, type TimelineKey } from './locales.ts'\n\ndeclare module '@deepseek-ai/dsh-client-ui-slots' {\n  interface LocaleNamespaceMap {\n    /** Chat-timeline surface copy. */\n    'chat-timeline': TimelineKey\n  }\n}\n\n/** Dictionary namespace owned by this plugin. */\nconst NS = 'chat-timeline'\n\n/** Unique occupant id inside the shared shell.overlay list slot. */\nconst ENTRY_ID = 'chat-timeline'\n\n/** Services required by this plugin. */\nexport const inject = ['slots', 'locale', 'sessions']\n\n/**\n * Register the timeline surface.\n * @param ctx - client root context.\n */\nexport function apply(ctx: ClientContext): void {\n  ctx.effect(() => {\n    try {\n      return ctx.locale.register(NS, { zh, en })\n    } catch {\n      return () => {}\n    }\n  }, 'chat-timeline: dictionaries')\n\n  // The rail floats over the conversation via the frame-wide additive seat.\n  // Registration is declaration-aware via slots.inject.\n  ctx.slots.inject('shell.overlay', () => {\n    try {\n      return ctx.slots.register({\n        name: 'shell.overlay',\n        id: ENTRY_ID,\n        locale: NS,\n        inject: () => ({ source: timelineSourceFromContext(ctx) }),\n      }, TimelineRail)\n    } catch {\n      return () => {}\n    }\n  })\n}\n\nexport type { TimelineRailProps } from './rail.tsx'\nexport type { TimelineKey } from './locales.ts'\nexport type { TimelineSource, TimelineSnapshot, TimelineState } from './source.ts'\n"],"mappings":"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"}

package/lib/index.js

@@ -0,0 +1,5 @@
+//#region src/index.ts
+/** Apply the host half. */
+function apply(ctx) {}
+//#endregion
+export { apply };

package/lib/types/client/directory.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Timeline directory derivation — the pure core of the plugin.
+ *
+ * Turns the conversation snapshot's ordered node list into one tick per human
+ * input (`user` / `steering`), each carrying a trimmed user preview plus the
+ * assistant reply preview in one of three states (text / running / empty).
+ * Preview budgeting replicates the ZCode TurnNavigator: at most two
+ * paragraphs, whitespace-collapsed, truncated to 220 characters.
+ *
+ * No DOM, no React, no dsh runtime imports — everything here is plain data so
+ * vitest can cover it without fixtures beyond plain objects.
+ */
+/** Minimal structural shape of a conversation node this module needs. */
+export interface TimelineNodeLike {
+    kind: string;
+    seq: number;
+    /** Unix epoch ms when present. */
+    time?: number;
+    /** User/steering content blocks (each `{ kind, text? }`-like). */
+    content?: readonly unknown[];
+    /** Assistant content blocks (each `{ kind, text? }`-like). */
+    blocks?: readonly unknown[];
+}
+/** One tick in the timeline directory. */
+export interface TimelineItem {
+    /** Stable React key (`n<seq>`). */
+    readonly key: string;
+    /** Seq of the anchoring human node. */
+    readonly seq: number;
+    /** Anchor time (epoch ms); 0 when unknown. */
+    readonly time: number;
+    /** Trimmed human input preview. */
+    readonly userPreview: string;
+    /** True when the human node carried no extractable text. */
+    readonly userFallback: boolean;
+    /** Trimmed assistant reply preview. */
+    readonly assistantPreview: string;
+    /** Which assistant preview state applies. */
+    readonly assistantKind: 'text' | 'running' | 'empty';
+    /** True for the last tick while the session is still running. */
+    readonly running: boolean;
+}
+/** Copy labels the derivation needs (kept out of the pure math for testability). */
+export interface TimelineLabels {
+    readonly userFallback: string;
+    readonly assistantEmpty: string;
+    readonly assistantRunning: string;
+}
+/** Preview budget: at most two paragraphs and 220 characters (ZCode parity). */
+export declare const MAX_PREVIEW_CHARS = 220;
+export declare const MAX_PREVIEW_PARAGRAPHS = 2;
+/** Extract concatenated text from a ContentBlock-like list.
+ *  dsh-llm content blocks switch on `type`; assistant blocks use `kind` — accept both. */
+export declare function blocksText(blocks: readonly unknown[] | undefined): string;
+/** Collapse each paragraph's whitespace and drop empties (ZCode u5e parity). */
+export declare function collapseParagraphs(text: string, maxParagraphs: number): string[];
+/** Truncate to the budget with an ellipsis, never below the floor (ZCode d5e parity). */
+export declare function truncatePreview(text: string, maxChars: number, floor?: number): string;
+/** Build one preview string from raw texts under the shared budget. */
+export declare function buildPreview(texts: readonly string[], fallback: string): string;
+/**
+ * Derive the tick directory from the snapshot's ordered node list.
+ * @param nodes - conversation snapshot nodes in seq order.
+ * @param running - whether the session currently has a running turn.
+ * @param labels - localized preview fallbacks.
+ * @returns one item per human input, in order.
+ */
+export declare function buildTimelineItems(nodes: readonly TimelineNodeLike[], running: boolean, labels: TimelineLabels): TimelineItem[];

package/lib/types/client/directory.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/client/dom.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Chat DOM probe — the only module allowed to know DSH's internal chat DOM.
+ *
+ * Contract measured on dsh 0.1.1-rc.2 (see .scratch/chat-timeline/issues/03):
+ * the scroll container carries `data-conversation-scroll`; each flow row is a
+ * `[data-chat-flow-kind]` element whose `user` kind marks a human turn, in the
+ * same seq order as the snapshot's user nodes. Every access is defensive:
+ * when detection fails the probe degrades to a no-op rail (no jump, no
+ * highlight) instead of throwing.
+ */
+/** Read-only view of the chat DOM the rail interacts with. */
+export interface ChatDomProbe {
+    /** The chat scroll container, or null when not found. */
+    getContainer(): HTMLElement | null;
+    /** Human-turn row elements in document order (user kind only). */
+    getUserRows(): HTMLElement[];
+    /** Index of the human turn nearest the viewport top, or -1. */
+    activeIndex(): number;
+    /** Scroll the given human turn into view; false when unavailable. */
+    jumpTo(index: number, behavior: ScrollBehavior): boolean;
+}
+/**
+ * Find the chat scroll container with a candidate chain.
+ * 1. the explicit stable hook `[data-conversation-scroll]`;
+ * 2. the closest scrollable ancestor of the flow column `[data-chat-flow]`;
+ * 3. the largest scrollable element that contains human rows.
+ */
+export declare function findChatContainer(doc: Document): HTMLElement | null;
+/** Human-turn rows inside the container (falling back to a document-wide query). */
+export declare function findUserRows(container: HTMLElement | null): HTMLElement[];
+/**
+ * The active index: the last human row whose top edge sits above the
+ * container's reading line (40px below the top edge), matching the ZCode
+ * "unit at viewport top" rule; clamps to the last row at scroll bottom.
+ */
+export declare function computeActiveIndex(container: HTMLElement, rows: readonly HTMLElement[]): number;
+/** Create the probe against a document (injectable for tests). */
+export declare function probeChatDom(doc: Document): ChatDomProbe;

package/lib/types/client/dom.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/client/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Chat-timeline plugin — browser half. Registers the `chat-timeline` locale
+ * dictionaries and a `shell.overlay` entry that renders the question
+ * navigator rail beside the conversation. Export discipline: the /client
+ * surface carries only what cordis loading needs plus types.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type TimelineKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Chat-timeline surface copy. */
+        'chat-timeline': TimelineKey;
+    }
+}
+/** Services required by this plugin. */
+export declare const inject: string[];
+/**
+ * Register the timeline surface.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+export type { TimelineRailProps } from './rail.tsx';
+export type { TimelineKey } from './locales.ts';
+export type { TimelineSource, TimelineSnapshot, TimelineState } from './source.ts';

package/lib/types/client/locales.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Locale dictionaries for the chat-timeline plugin. `zh` is the key-set source
+ * of truth; `en` keeps a full key-for-key mirror. Registered through
+ * ctx.locale.register(NS, { zh, en }).
+ */
+/** Simplified Chinese dictionary (key-set source of truth). */
+export declare const zh: {
+    'nav.label': string;
+    'nav.jumpToQuery': string;
+    'preview.userFallback': string;
+    'preview.assistantEmpty': string;
+    'preview.assistantRunning': string;
+};
+/** The chat-timeline namespace key union. */
+export type TimelineKey = keyof typeof zh;
+/** English dictionary, key-for-key complete against zh. */
+export declare const en: Record<TimelineKey, string>;

package/lib/types/client/rail.d.ts

@@ -0,0 +1,13 @@
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { TimelineSource } from './source.ts';
+/** Component props: the locale seat plus the injected session source. */
+export type TimelineRailProps = PropsLocale<'chat-timeline'> & {
+    /** The current-session snapshot source (built from ctx.sessions). */
+    source: TimelineSource;
+};
+/**
+ * Render the question navigator rail.
+ * @param props - composed slot props.
+ * @returns the rail, or null when it should not render.
+ */
+export declare function TimelineRail({ source, t }: TimelineRailProps): import("react").JSX.Element | null;

package/lib/types/client/source.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Timeline source: follows the current session through the cordis services
+ * face (ctx.sessions) and exposes a useSyncExternalStore-compatible read
+ * face over its ConversationSnapshot. All dsh-client-runtime usage here is
+ * type-only; at runtime everything is reached through the ctx services, so
+ * the client bundle stays free of cross-package value imports.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+/** The slice of ConversationSnapshot the timeline consumes. */
+export interface TimelineSnapshot {
+    readonly sessionId: string;
+    /** Ordered conversation nodes (the snapshot's legacy compatibility field). */
+    readonly nodes: readonly unknown[];
+    /** Whether the session currently has a running turn. */
+    readonly running: boolean;
+}
+/** State handed to React: null snapshot means "no readable session right now". */
+export interface TimelineState {
+    readonly sessionId: string | undefined;
+    readonly snapshot: TimelineSnapshot | null;
+}
+/** useSyncExternalStore-compatible source face. */
+export interface TimelineSource {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): TimelineState;
+}
+interface ObservableLike<T> {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}
+/** Structural face of ctx.sessions this module needs (kept narrow for tests). */
+export interface SessionsLike {
+    readonly list: ObservableLike<{
+        current?: string;
+    }>;
+    binding(id: string): {
+        session: ObservableLike<{
+            nodes?: readonly unknown[];
+            running?: boolean;
+        }>;
+    } | undefined;
+}
+/**
+ * Create the source. Subscribes to the sessions list, rebinds to the current
+ * session's snapshot feed on selection change, and republishes a stable state
+ * object whenever the underlying snapshot changes.
+ * @param sessions - the sessions service face (pass ctx.sessions).
+ * @returns the source face.
+ */
+export declare function createTimelineSource(sessions: SessionsLike): TimelineSource;
+/** Build the source from the plugin client context. */
+export declare function timelineSourceFromContext(ctx: ClientContext): TimelineSource;
+export {};

package/lib/types/client/styles.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Stylesheet for the chat-timeline rail, injected once as a
+ * `<style data-plugin-css="chat-timeline">` tag. All classes carry the
+ * `dsh-tl-` prefix; colors use the CSS system colors Canvas/CanvasText so the
+ * rail follows the app's color-scheme without reaching into DSH theme tokens.
+ * Visual constants replicate the ZCode TurnNavigator (spec section 2.2).
+ */
+export declare const TIMELINE_STYLES = "\n.dsh-tl-nav {\n  position: fixed;\n  z-index: 10;\n  width: 48px;\n  pointer-events: none;\n  opacity: 1;\n  transition: opacity 150ms ease-out;\n}\n.dsh-tl-nav[data-visible=\"false\"] {\n  opacity: 0;\n  visibility: hidden;\n}\n.dsh-tl-scroll {\n  position: absolute;\n  left: 12px;\n  top: 50%;\n  transform: translateY(-50%);\n  width: 36px;\n  max-height: calc(100% - 96px);\n  overflow-x: hidden;\n  overflow-y: auto;\n  padding-block: 4px;\n  pointer-events: auto;\n  scrollbar-width: none;\n  color: CanvasText;\n}\n.dsh-tl-scroll::-webkit-scrollbar {\n  display: none;\n}\n.dsh-tl-track {\n  position: relative;\n  width: 36px;\n}\n.dsh-tl-slot {\n  position: absolute;\n  left: 0;\n  top: 0;\n  height: 10px;\n  width: 36px;\n  padding: 0;\n  border: 0;\n  background: transparent;\n  display: flex;\n  align-items: center;\n  justify-content: flex-start;\n  border-radius: 2px;\n  cursor: pointer;\n}\n.dsh-tl-slot:focus-visible {\n  outline: 2px solid CanvasText;\n  outline-offset: 2px;\n}\n.dsh-tl-tick {\n  display: block;\n  height: 2px;\n  width: 12px;\n  border-radius: 999px;\n  background: currentColor;\n  transform-origin: left center;\n  transition: height 150ms ease-out, opacity 150ms ease-out, transform 150ms ease-out, background-color 150ms ease-out;\n}\n@media (prefers-reduced-motion: reduce) {\n  .dsh-tl-nav,\n  .dsh-tl-tick {\n    transition: none;\n  }\n}\n.dsh-tl-tip {\n  position: fixed;\n  z-index: 60;\n  width: 320px;\n  max-width: calc(100vw - 2rem);\n  padding: 12px;\n  border-radius: 10px;\n  background: Canvas;\n  color: CanvasText;\n  border: 1px solid color-mix(in srgb, CanvasText 15%, transparent);\n  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);\n  pointer-events: none;\n}\n.dsh-tl-tip-user {\n  margin: 0;\n  display: -webkit-box;\n  -webkit-box-orient: vertical;\n  -webkit-line-clamp: 2;\n  overflow: hidden;\n  white-space: pre-line;\n  font-size: 13px;\n  line-height: 20px;\n  font-weight: 500;\n}\n.dsh-tl-tip-assistant {\n  margin: 8px 0 0;\n  display: -webkit-box;\n  -webkit-box-orient: vertical;\n  -webkit-line-clamp: 3;\n  overflow: hidden;\n  white-space: pre-line;\n  font-size: 13px;\n  line-height: 20px;\n  opacity: 0.8;\n}\n.dsh-tl-tip-assistant[data-kind=\"running\"],\n.dsh-tl-tip-assistant[data-kind=\"empty\"] {\n  opacity: 0.55;\n}\n";
+/** Inject the stylesheet once per document. */
+export declare function ensureStyles(doc: Document): void;

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Host loader entry for the chat-timeline plugin — runs in the DSH host
+ * process. Pure browser plugin: the host half has no behavior beyond
+ * existing as the cordis bundle the profile composition imports; all UI
+ * logic lives in the browser half (src/client/index.ts).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Apply the host half. */
+export declare function apply(ctx: Context): void;

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@lament_z/dsh-client-ui-chat-timeline",
+  "displayName": "DSH Chat Timeline",
+  "description": "DSH Web 对话时间线插件：在左侧提供仿 ZCode TurnNavigator 的提问导航条，每个用户问题一个刻度，支持悬停波纹反馈、轮次预览卡片、点击跳转定位与滚动同步高亮，快速回溯长对话。",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.1.1-rc.1"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-layout": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^18.3.5",
+    "jsdom": "29.1.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsdown": "0.22.2",
+    "typescript": "~5.7.2",
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.i18n.yaml"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lament-z/dsh-client-ui-chat-timeline.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lament-z/dsh-client-ui-chat-timeline/issues"
+  },
+  "homepage": "https://github.com/lament-z/dsh-client-ui-chat-timeline",
+  "license": "MIT"
+}