dsh-url-router 0.3.0 → 0.3.1

package/AGENTS.md

@@ -44,7 +44,7 @@
 - **设置链接按"前缀"落地** ✓：裸 → 分区 → 页签逐级 ✓；命名了页签的链接必须看到那个页签 ✓，只命名到分区的链接被该分区任意页签满足 ✓。
 - **`aria-current` 必须在 DOM 观察者的 `attributeFilter` 里** ✓：切换分区只改这一个属性 ✓，漏了它地址栏就永远停在第一次看到的分区（历史 bug ✓）。
 - **裸 `#/settings` 立即可落地**（`sameRoute` 的定向例外 ✓）：分区是那个表面的细化、不是另一个表面 ✓；但**两个命名分区之间仍然算不同** ✓（否则分区链接就不驱动了 ✓）。
-- **轮次锚点是"位置"，只做反映**：点击聊天里的一轮（`[data-chat-turn]` ✓）把轮号写进地址栏 ✓；**绝不 preventDefault** ✗、**绝不碰交互元素**（button/a/input/textarea/select/[role=button]/[contenteditable] ✓ —— 逐个 `closest`，不用逗号选择器 ✓，因为小 DOM 桩可能不支持 ✓）。驱动侧只开会话 + 一条说明 ✓（官方没有对外跳转接缝 ✗）。
+- **轮次锚点是"位置"，反映 + 可跳转**：点击聊天里的一轮（`[data-chat-turn]` ✓）把轮号写进地址栏 ✓；**绝不 preventDefault** ✗、**绝不碰交互元素**（button/a/input/textarea/select/[role=button]/[contenteditable] ✓ —— 逐个 `closest`，不用逗号选择器 ✓，因为小 DOM 桩可能不支持 ✓）。驱动侧**全链路已闭环** ✓：开会话 → 翻页回那一轮 → 滚到它（契约见下 ✓）。会话还没上屏时**只开会话、不 drive** ✗（没有座位可滚 = 静默无操作 ✗，实测过 ✗）。
 - **右栏根上有 `data-sidebar-right-session="<会话 id>"`** ✓（右栏是**按会话**的 ✓，实测与路由里的会话 id 一致 ✓）；**页签只读 `[data-dockkit-strip-tabs]`** ✓ —— 空态那层也有 `data-dockkit-pane="pane1"` ✗，读"任意 pane-active"会把空态当页签 ✗（历史 bug ✓）。
 - **官方源码级契约（读 dsh-web-frontend / sidebar-right 得到）** ✓：页签是 `role="tab"` ✓，活动的是 `aria-selected="true"` ✓，身份在 **`data-dockkit-tab`** ✓ —— 而**该值就是 `pageAddress(kind)` = `sidebar://<kind>[/<uuid>]`** ✓（`multiple: true` 的 kind 才拼 uuid ✓），所以 **kind 直接含在 tabId 里** ✓（`kindOfTabId()` 解 ✓）。`data-dockkit-pane` 的值是 **paneId**（`pane1` ✗），而且**主区也有同一套属性** ✗ → 读必须**限定在 `[data-sidebar-right-session]` 根内** ✓（否则读成主区的 pane ✗）。
 - **控制器的两条路** ✓：`openTab(kind)` 要求**已挂载**（`require()` 抛 `no session surface is mounted` ✗）；**`openTabIn(sessionId, kind, options)`** 才是显式带会话的公开路径 ✓（**参数顺序是 session 优先** ✗ 传反就成了"查一个叫 files 的会话" ✗ 历史 bug ✓）。`actionsFor(sessionId)` = `adopted.get(sessionId)?.store.actions` ✓，而 **adopt 发生在右栏被呈现时** ✓（`layout.openRightbar(track, fullscreen)` ✓，track = `session` | `panel` ✓）→ 所以驱动**先呈现右栏** ✓ 再 `openTabIn` ✓。
@@ -68,7 +68,16 @@
 - **路由体检（#7）**：一个 `window.__dshUrlRouter.report()` ✓（无 UI 依赖 ✓，绝不抛错 ✓），列出：当前 canonical 路由 ✓、正在落地的链接与重试次数 ✓、每一层界面**读到多少个钩子** ✓（会话行 / 工作区行 / 视图 tab 与 id 列表 / 轮次 / 轨迹行 / 轮次边界 / 插件行 / 官方项 / 设置覆盖层与分区 / 任务看板 / 右栏 pane ✓）、已发出的告警 ✓、以及被"不碰"的段位 ✓。
 - **对外接缝（#8）**：`ctx.urlRouter`（服务）或同名窗口事件 ✓，让第三方把"当前界面"写成链接 ✓，并由本插件**统一裁决** fragment 所有权 ✓ —— 这同时也是 #4 的真正解法 ✓。
 - **面板内层页面（#5）**：技能中心 / SSH 需要各自发契约 ✓（`data-*` + 接受同名窗口事件 ✓）；任务看板是现成先例 ✓，可作为 PR 往上游推 ✓（需要各仓 owner 同意 ✓）。
-- **跳转到某一轮（官方）**：已发讨论 <https://github.com/deepseek-ai/deepseek-harness/discussions/9339> ✓（请求一个 `scrollToTurn(turn)` 服务或 `dsh-chat-scroll-to-turn` 窗口事件 ✓；退路是驱动 rail 刻度点击 ✗ 虚拟化下不可靠 ✓）。
+- **跳转到某一轮：已用官方公开契约打通，无需新接缝** ✓。链路：
+  `faces.sessions.retainScope(sessionId, SRC)` → `reference.binding.session` →
+  `session.projections.faceOf('turnOutline').getSnapshot()`（条目 `{turn, seq, prompt, response}` ✓ → 取目标轮的 `seq` ✓）→
+  `session.loadThrough(seq)` → `reference.release()` → 再 `scrollIntoView` ✓。
+  - **`sessions` 必须在 `inject` 里声明** ✗ 否则拿不到 ✗（与 `uiConversation` 同一规矩 ✓）；**`probeFaces` 必须把它读进 faces** ✗（曾漏读 → 真机 `retainScope` 恒 undefined → 白烧六轮 ✗）。
+  - **根插件拿不到 `sessions.binding()`** ✗（实测 undefined ✓）：会话作用域的控制器只能靠 `retainScope` 物化 ✓。
+  - **座位/视口判据用官方同款选择器** ✓：`[data-chat-turn]:not([hidden])` ✓，并自己排除 `closest('[hidden]')` ✓ —— **虚拟列表会把未载入的轮次也渲染进 DOM** ✗（只查"存在"会假报就位 ✗，实测 ✗）。
+  - **`sameRoute` 对 turn 的落地判据 = 目标真在视口** ✓（`routeKey` 比法会让 canonical 一带上 turn 就判等 → 链接永不驱动 ✗，死锁实测 ✓）。
+  - **drive 会重入 reconcile** ✓，重入可能已 `dropLink()` → **守门后立刻 `const link = linked`，体内一律用快照** ✗（否则 `reading 'inner'` ✓，实测 ✗）。
+  - `loadThrough` 是**公开 slot 契约** ✓（`session-controller` 1885 注释 "page backwards until the window covers seq" ✓）。官方 `uiChat.scrollToTurn(sessionId, turn)` 那条请求（讨论 #9339 ✓）**已降级为锦上添花** ✓（不阻塞 ✓）。
 
 ## 已实现：#4 外部 fragment 共存 / #7 路由体检（2026-10-11）
 

package/README.md

@@ -64,11 +64,11 @@ dsh plugin --profile web add "link:/path/to/dsh-url-router"
 
 ### 已知限制
 
-- **轮次链接是"位置"不是"界面"**：点某一轮，地址栏记下 `#/session/<id>/turn/<n>` ✓；但**粘贴它只会打开那个对话，不会滚到那一轮** ✗ —— 官方把"跳到某轮"（`scrollToTurn` / `JUMP_PAGE_OPTIONS`）留在 chat 包**内部**，没有对外接缝 ✗，逐页翻也不可靠 ✗（实测「Load earlier」按钮在两个会话上都没加载出更早的轮次 ✗）。要真跳转，需要官方开一个服务或槽位 ✓。
+- **轮次链接是"位置"，而且现在真能跳** ✓：点某一轮，地址栏记下 `#/session/<id>/turn/<n>` ✓；**粘贴它会打开那个对话、把历史翻页回那一轮、再滚到它** ✓（真机实测：贴 `/turn/118` → 窗口变成 118→121、目标在视口 true、最顶可见正是 118 ✓）。用的是**官方已有公开契约** ✓：`sessions.retainScope(id, source)` 拿到会话控制器 ✓ → `session.projections.faceOf('turnOutline')` 读到那一轮的 `seq` ✓ → `session.loadThrough(seq)` 翻页回去 ✓（完事 `reference.release()` ✓）→ 再按官方视口同款选择器 `[data-chat-turn]:not([hidden])` 滚到它 ✓。座位高度/相交都读不到时**不算到位** ✓，宁可继续重试也不假报 ✗。
 - **右栏 pane 已闭环** ✓：`#/session/<id>/pane/<kind>` 与 `#/panel/<面板>/pane/<kind>` ✓（真机验证：贴链接开出对应页签 ✓、地址栏跟着切换 ✓）。页签种类由右栏自己注册 ✓（实测 7 种：`guide` / `subagentchat` / `changes-review` / `plan` / `files` / `text` / `terminal` ✓）。
 - **设置面板已纳入**：`#/settings` ✓、**`#/settings/<分区>`** ✓、**`#/settings/<分区>/<页签>`** ✓（页签靠标准 `role="tab"` + `aria-selected` ✓，分区内任何页签都吃这一套 ✓）。分区**没有稳定 id** ✗（实测：导航项上只有 `aria-current="true"` ✓，父链是 `nav` ✓，右侧内容区一个 `data-*` 都没有 ✗；官方内部的 `openSection(id)` 也不对外 ✗）→ 所以**分区的身份就是它的显示名** ✓：反映读「`aria-current="true"` 且属于 `nav`」的那个按钮的**标签文字** ✓，驱动按标签点 ✓。含义：**换语言或官方改文案后，旧的分区链接会失效** ✗（但你重新点一次，地址栏就会写出新链接 ✓ —— 自洽、不过期 ✓）。裸 `#/settings` 只要面板开着就算落地 ✓，随后地址栏自动升级为具体分区 ✓。
 - **设置页分区暂未纳入（旧描述）**：设置包没有"打开某个分区"的接缝（它们是 keyed list slot），只能等它自己发布类似契约。
-- **会话内的轮次与行锚点已纳入** ✓：`#/session/<id>/turn/<n>` ✓（只做反映 ✓）、`#/session/<id>/row/<类>/<作用域>/<id>` ✓（反映 + 尽力滚动 ✓，含可证明时的轮次归属 ✓）。**跳转仍然做不到** ✗（官方把 `scrollToTurn` 留在包内部 ✓，已向官方提 <https://github.com/deepseek-ai/deepseek-harness/discussions/9339> ✓）。
+- **会话内的轮次与行锚点已纳入** ✓：`#/session/<id>/turn/<n>` ✓（**反映 + 翻页 + 滚动 ✓ 全链路已闭环**）、`#/session/<id>/row/<类>/<作用域>/<id>` ✓（反映 + 尽力滚动 ✓，含可证明时的轮次归属 ✓）。轮次跳转用的是官方公开 API ✓，**没有等待任何新接缝** ✓（`uiChat.scrollToTurn` 那条请求已降级为锦上添花 ✓，讨论见 <https://github.com/deepseek-ai/deepseek-harness/discussions/9339> ✓）。
 - **技能中心 / SSH 的内部页**：需要它们各自发布"当前实体 id + 按 id 打开"的契约（任务看板就是这么做的）。
 - **和别的 fragment 写者互斥**（例如写 `#msg=` 的"跳到消息"插件）：一个 URL 只有一个 fragment ✓，两个写者只能轮流拥有 ✗。本插件**不假装合并** ✓ —— 它认出外来 fragment ✓、**绝不覆盖** ✓，并明确说"只能启用一个写者" ✓（而不是互相静默擦掉对方的链接 ✗）。
 - 链接**同名不跨机**：会话 id 只在同一台机器、同一个 `DSH_HOME` 下有意义。
@@ -123,4 +123,4 @@ Conversation rows and both plugin-list groups carry a transparent full-row ancho
 
 ### Limits
 
-Still open: jumping to a named turn (the official chat keeps `scrollToTurn` inside its own package — asked for a seam in discussion #9339), the right-hand panes (wired, but the right bar starts empty in this composition so they are not verified end to end yet), and Skill Center / SSH inner pages, which need their own "publish the current id + accept an open request" contract the way the task board did. Session links are meaningful on the same machine and `DSH_HOME` only.
+Still open: Skill Center / SSH inner pages, which need their own "publish the current id + accept an open request" contract the way the task board did. Session links are meaningful on the same machine and `DSH_HOME` only.

package/lib/client.js

@@ -123,7 +123,7 @@ window.__ModuleLoader__.load({
 		 * The router's own version, for the report a human files. A test keeps it equal to the
 		 * package version, so a release cannot forget to bump it.
 		 */
-		const ROUTER_VERSION = '0.3.0'
+		const ROUTER_VERSION = '0.3.1'
 
 		const TAG = '[url-router]'
 
@@ -133,24 +133,22 @@ window.__ModuleLoader__.load({
 		 * @param {object} faces - the probed host faces.
 		 * @returns {string[]|undefined} the ids, or undefined when the registry is not readable.
 		 */
+		/**
+		 * The conversation view ids the registry publishes, in registration order.
+		 *
+		 * `uiConversation` is a **root** client service (measured: `new UiConversation(ctx)` with
+		 * `super(ctx, "uiConversation")`), and `views` is a public field on it — so the ids come
+		 * straight from the registry instead of being aligned to the slot by position.
+		 * @param {object} faces - the probed host faces.
+		 * @returns {string[]|undefined} the ids, or undefined when the registry is not readable.
+		 */
 		function conversationViewIdsOf(faces) {
-			// The conversation's own `uiConversation` registry is scoped to the conversation and is
-			// not visible from a root plugin (measured: undefined), but the view tabs are contributed
-			// through the `conversation.view` slot, and that *is* readable — with an id and an order.
-			const entries = attemptValue(() => faces.slots?.entries?.('conversation.view'))
-			if (!Array.isArray(entries)) return undefined
-			const rows = []
-			for (const entry of entries) {
-				if (entry === null || typeof entry !== 'object') continue
-				const options = entry.options ?? entry
-				const id = options.id ?? entry.id
-				if (typeof id !== 'string' || id === '') continue
-				const order = typeof options.order === 'number' ? options.order : 0
-				rows.push({ id, order })
-			}
-			if (rows.length === 0) return undefined
-			rows.sort((left, right) => left.order - right.order)
-			return rows.map(row => row.id)
+			const rows = attemptValue(() => faces.uiConversation?.views?.entries?.())
+			if (!Array.isArray(rows)) return undefined
+			const ids = rows
+				.map(row => (row === null || typeof row !== 'object' ? undefined : row.target ?? row.id))
+				.filter(id => typeof id === 'string' && id !== '')
+			return ids.length === 0 ? undefined : ids
 		}
 
 		/**
@@ -203,6 +201,37 @@ window.__ModuleLoader__.load({
 		 * @param {object} faces - the probed host faces.
 		 * @returns {{kind: string, label: string|undefined, multiple: boolean}[]|undefined} the rows.
 		 */
+		/**
+		 * The seq of a turn's start event, from the `turnOutline` projection.
+		 *
+		 * The projection is a public read on the session controller (the core reads it the same
+		 * way: `session.projections.faceOf("turnOutline").getSnapshot()`), and each entry carries
+		 * the `seq` of that turn's `turn/start` — which is exactly what `loadThrough` pages back
+		 * to. Reading it is what makes a turn link work for a turn that is not loaded yet.
+		 * @param {object} faces - the probed host faces.
+		 * @param {string|undefined} sessionId - the session the turn belongs to.
+		 * @param {string} turn - the turn number.
+		 * @returns {number|undefined} the seq, when the projection names that turn.
+		 */
+		function turnSeqOf(faces, sessionId, turn) {
+			if (typeof sessionId !== 'string' || sessionId === '') return undefined
+			// Reached by retaining the session's scope: `sessions.binding(id)` answers undefined
+			// for a session nobody materialised yet (measured), while `retainScope(id, source)`
+			// materialises it and returns a reference whose `binding` is the live one. Released here
+			// because only the projection is read.
+			const reference = attemptValue(() => faces.sessions?.retainScope?.(sessionId, 'url-router'))
+			const outline = attemptValue(() => session?.projections?.faceOf?.('turnOutline')?.getSnapshot?.())
+			attempt(() => reference?.release?.())
+			if (!Array.isArray(outline)) return undefined
+			const wanted = String(turn)
+			for (const entry of outline) {
+				if (entry === null || typeof entry !== 'object') continue
+				if (String(entry.turn) !== wanted) continue
+				return typeof entry.seq === 'number' ? entry.seq : undefined
+			}
+			return undefined
+		}
+
 		function paneRegistryOf(faces) {
 			const rows = attemptValue(() => faces.sidebarRightTabs?.entries?.())
 			if (!Array.isArray(rows)) return undefined
@@ -369,6 +398,11 @@ window.__ModuleLoader__.load({
 				if (sessionId === '') return { unknown: `workspace/${match[2]}` }
 				// The view a conversation is showing is part of the conversation, so it may follow.
 				const tail = rest.slice(2)
+				// `turn` is a position like `row` and `pane`, and it composes with `row`
+				// (`turn/<n>/row/…`): without this branch a workspace-shaped turn link lands in
+				// `unknown` and is never claimed at all.
+				const turnAt = tail.indexOf(TURN_SEGMENT)
+				if (turnAt >= 0 && tail.length > turnAt + 1 && tail[turnAt + 1].trim() !== '') return { kind: 'workspace', id: name, inner: innerPath([WORKSPACE_SESSION_SEGMENT, sessionId, ...tail]) }
 				if (tail.length === 0) return { kind: 'workspace', id: name, inner: innerPath([WORKSPACE_SESSION_SEGMENT, sessionId]) }
 				if (tail.length < 2 || tail[1].trim() === '') return { unknown: `workspace/${match[2]}` }
 				if (tail[0] === VIEW_SEGMENT && tail.length === 2) return { kind: 'workspace', id: name, inner: innerPath([WORKSPACE_SESSION_SEGMENT, sessionId, VIEW_SEGMENT, tail[1]]) }
@@ -527,6 +561,7 @@ window.__ModuleLoader__.load({
 			let rowAnchor
 			/** The pane kind this claim already opened (one drive per claim, see the pane branch). */
 			let paneOpenedFor
+			/** A position the previous step asked to bring into view, driven on the next reconcile. */
 			let turnAnchor
 			/** How many times the linked panel was selected (bounded, see below). */
 			let panelAttempts = 0
@@ -589,13 +624,19 @@ window.__ModuleLoader__.load({
 					// A pointed-at row is the most specific position there is, then the view, then the
 					// turn: they are all "where inside this conversation", so one of them is written.
 					const view = host.activeConversationView()
-					const position = rowAnchor !== undefined && rowAnchor.session === id
-						? rowAnchor.turn === undefined || rowAnchor.turn === ''
-							? [ROW_SEGMENT, ...rowAnchor.parts]
-							: [TURN_SEGMENT, rowAnchor.turn, ROW_SEGMENT, ...rowAnchor.parts]
-						: view !== undefined && view.index !== 0
-							? [VIEW_SEGMENT, view.id]
-							: []
+					// A pointed-at row is a position, then the view. A *turn* deliberately is not: while a
+					// turn link is in flight the address bar belongs to it, and once it lands the link hands
+					// the address bar back — naming the turn here as well is what made a link look "landed"
+					// before it had ever driven (a real bug, live-measured).
+					// A pointed-at row is a position, then the view, then the turn the user pointed at —
+					// but never while a turn link is in flight: that link owns the address bar until it lands,
+					// and naming the turn here too is what made it look "landed" before it ever drove.
+					const anchoredTurn = linked === undefined && turnAnchor !== undefined && turnAnchor.session === id && turnAnchor.turn !== undefined && turnAnchor.turn !== '' ? [TURN_SEGMENT, turnAnchor.turn] : []
+					const position = [
+						...(rowAnchor !== undefined && rowAnchor.session === id ? (rowAnchor.turn === undefined || rowAnchor.turn === '' ? [ROW_SEGMENT, ...rowAnchor.parts] : [TURN_SEGMENT, rowAnchor.turn, ROW_SEGMENT, ...rowAnchor.parts]) : []),
+						...(anchoredTurn.length > 0 && rowAnchor !== undefined && rowAnchor.session === id ? [] : anchoredTurn),
+						...(view !== undefined && view.index !== 0 ? [VIEW_SEGMENT, view.id] : []),
+					]
 					// The right-hand pane is its own layer, not a position inside the conversation:
 					// it is named next to whatever the main column shows, never instead of it — so it
 					// is read *before* the workspace branch, or the workspace would swallow it.
@@ -609,9 +650,6 @@ window.__ModuleLoader__.load({
 					if (tail.length > 0) return { kind: 'session', id, inner: innerPath([...position, ...tail]) }
 						// The turn the user last pointed at is a position inside this conversation;
 					// it is only named while the same conversation is the one on screen.
-					if (turnAnchor !== undefined && turnAnchor.session === id) {
-						return { kind: 'session', id, inner: innerPath([TURN_SEGMENT, turnAnchor.turn]) }
-					}
 					return { kind: 'session', id }
 				}
 				return undefined
@@ -644,6 +682,9 @@ window.__ModuleLoader__.load({
 				return at < 0 ? undefined : parts[at + 1]
 				}
 			const sameRoute = (current, linked) => {
+				// A drive re-enters this machine, and re-entry can find the link already dropped: a link
+				// that is no longer in flight is never "the same route" as anything.
+				if (linked === undefined || linked === null) return false
 				if (routeKey(current) === routeKey(linked)) return true
 				const currentSession = sessionIdOfRoute(current)
 				const linkedSession = sessionIdOfRoute(linked)
@@ -655,7 +696,27 @@ window.__ModuleLoader__.load({
 						// route that names the same conversation is satisfied by it being on screen —
 						// the workspace name is decoration, not a condition.
 						const parts = innerPath(linked.inner)
-						if (parts.includes(TURN_SEGMENT) || parts.includes(ROW_SEGMENT)) return routeKey(current) === routeKey(linked)
+						if (parts.includes(TURN_SEGMENT)) {
+							// A turn link lands when that turn is really in view. Comparing routes here called it
+							// landed while the seat was still outside the viewport (live-measured): the address bar
+							// is what the *link* already guarantees, so the route comparison proved nothing.
+							// Unknown geometry counts as "not in view" — the safe side: it keeps the drive alive
+							// rather than dropping a link that has not moved anything yet.
+							const turnWanted = parts[parts.indexOf(TURN_SEGMENT) + 1]
+							const seat = attemptValue(() => document?.querySelector?.(`[${TURN_ATTRIBUTE}="${turnWanted}"]`))
+							if (seat === null || seat === undefined) return false
+							// The official viewport reads exactly this: a seat that is hidden, or inside anything
+								// hidden, is not on screen — and the virtual list does render such rows (measured: the
+								// seat for the wanted turn existed while the turn was plainly not loaded).
+							if (seat.hidden === true) return false
+							if (attemptValue(() => seat.closest?.('[hidden]')) !== null && attemptValue(() => seat.closest?.('[hidden]')) !== undefined) return false
+							const rect = attemptValue(() => seat.getBoundingClientRect?.())
+							if (rect === null || rect === undefined) return false
+							const viewHeight = attemptValue(() => window.innerHeight)
+							if (typeof viewHeight !== 'number' || !(viewHeight > 0)) return false
+							return rect.height > 0 && rect.bottom > 0 && rect.top < viewHeight
+						}
+						if (parts.includes(ROW_SEGMENT)) return routeKey(current) === routeKey(linked)
 						// A pane is its own layer, named next to the conversation: the route *shape* (with or
 						// without the workspace) is decoration, exactly like the workspace name — what has to
 						// match is the pane kind itself.
@@ -701,6 +762,7 @@ window.__ModuleLoader__.load({
 			 */
 			const reconcile = (source = 'boot') => {
 				if (disposed) return
+
 				const current = canonical()
 				const currentKey = routeKey(current)
 				const moved = currentKey !== seen
@@ -712,11 +774,18 @@ window.__ModuleLoader__.load({
 					if (paneTabs > 0 && host.activePaneKind() === undefined) {
 						notePaneShape(message => host.warn(message), 'pane-shape', `the right bar shows ${paneTabs} tab(s) but this build cannot read the active one; the first tab is: ${activePaneTabOf.observed ?? 'no attributes read'}`)
 					}
+				// A position the previous step asked for: it is driven here, one step later, so the step
+				// that claimed it never drives while it is still running.
 				if (linked === undefined) {
 					reflect(current)
 					return
 				}
-				if (sameRoute(current, linked)) {
+				// Snapshot the link for the rest of this step. Driving a position re-enters this machine
+				// (and re-entry can drop the link), so every read below must use the snapshot: reading the
+				// live binding again is how a drive turned into "Cannot read properties of undefined".
+				const link = linked
+
+				if (sameRoute(current, link)) {
 					dropRetry()
 					// The link has landed: it stops being authoritative right here, so the user
 					// keeps owning the address bar afterwards (walking deeper inside a panel
@@ -725,8 +794,8 @@ window.__ModuleLoader__.load({
 					reflect(current)
 					return
 				}
-				if (host.now() >= linked.deadline) {
-					const hash = routeHash(linked.kind, linked.id, linked.inner)
+				if (host.now() >= link.deadline) {
+					const hash = routeHash(link.kind, link.id, link.inner)
 					host.warn(`${TAG} ${hash} did not become the shown view within ${LINK_ENFORCE_WINDOW_MS} ms; the link was ignored`)
 					dropLink()
 					reflect(canonical())
@@ -734,10 +803,10 @@ window.__ModuleLoader__.load({
 				}
 				// A conversation link may name which view it wants, on either route shape; the view is
 				// driven before the plain conversation/workspace branches, or they would swallow it.
-				const rowParts = innerPath(linked.inner)
+				const rowParts = innerPath(link.inner)
 				const rowAt = rowParts.indexOf(ROW_SEGMENT)
 				const wantedTurn = rowParts.indexOf(TURN_SEGMENT)
-				const rowSession = linked.kind === 'workspace' ? rowParts[1] : linked.kind === 'session' ? linked.id : undefined
+				const rowSession = link.kind === 'workspace' ? rowParts[1] : link.kind === 'session' ? link.id : undefined
 				if (rowSession !== undefined && rowAt >= 0 && rowParts.length > rowAt + 2) {
 					const shown = host.mainViewSessionId()
 					if (shown !== rowSession && panelAttempts < INNER_ATTEMPT_LIMIT) {
@@ -745,13 +814,13 @@ window.__ModuleLoader__.load({
 						host.openSession(rowSession)
 					} else if (shown === rowSession && innerAttempts < INNER_ATTEMPT_LIMIT) {
 						innerAttempts += 1
-						if (!host.revealRow(rowParts.slice(rowAt)) && wantedTurn >= 0) host.revealRow(rowParts.slice(wantedTurn, wantedTurn + 2))
+						if (!host.revealPosition(rowParts.slice(rowAt)) && wantedTurn >= 0) host.revealPosition(rowParts.slice(wantedTurn, wantedTurn + 2), rowSession)
 					}
 					armRetry()
 					return
 				}
-				const wantedView = linked.kind === 'session' || linked.kind === 'workspace' ? viewIdOfRoute(linked) : undefined
-				const wantedSession = linked.kind === 'workspace' ? innerPath(linked.inner)[1] : linked.kind === 'session' ? linked.id : undefined
+				const wantedView = link.kind === 'session' || link.kind === 'workspace' ? viewIdOfRoute(link) : undefined
+				const wantedSession = link.kind === 'workspace' ? innerPath(link.inner)[1] : link.kind === 'session' ? link.id : undefined
 				if (wantedView !== undefined && wantedSession !== undefined) {
 					// Unlike the boot restore, a named view is driven whatever brought the route in —
 					// a pasted view link exists precisely to switch the view, so it must not be skipped.
@@ -766,10 +835,10 @@ window.__ModuleLoader__.load({
 					armRetry()
 					return
 				}
-				if (linked.kind === 'workspace') {
+				if (link.kind === 'workspace') {
 					// The workspace is where the conversation lives, not a separate surface: the link
 					// is satisfied by that conversation being on screen, whatever the name says.
-					const target = innerPath(linked.inner)[1]
+					const target = innerPath(link.inner)[1]
 					const shown = host.mainViewSessionId()
 					if (shown !== target && source !== 'hash' && panelAttempts < INNER_ATTEMPT_LIMIT) {
 						panelAttempts += 1
@@ -778,42 +847,67 @@ window.__ModuleLoader__.load({
 					armRetry()
 					return
 				}
-				if (linked.kind === 'settings') {
+				if (link.kind === 'settings') {
 					if (source !== 'hash' && innerAttempts < INNER_ATTEMPT_LIMIT) {
 						innerAttempts += 1
-						host.openSettings(linked.id, innerPath(linked.inner)[0])
+						host.openSettings(link.id, innerPath(link.inner)[0])
 					}
 					armRetry()
 					return
 				}
-				if (linked.kind === 'session' && linked.inner !== undefined && innerPath(linked.inner)[0] === PANE_SEGMENT) {
+				if (link.kind === 'session' && link.inner !== undefined && innerPath(link.inner)[0] === PANE_SEGMENT) {
 					// A pasted pane link is exactly what this drive is for, so the source is not a filter
 					// here (the same lesson as the view branch); the attempt bound still limits it.
-					const wantedPane = innerPath(linked.inner)[1]
+					const wantedPane = innerPath(link.inner)[1]
 					// A page type that may be opened more than once (measured: `multiple: true`, the
 					// terminal) makes *every* attempt open another tab, so one claim drives once and the
 					// retry then only waits for the bar to report the tab it opened.
 					if (innerAttempts < INNER_ATTEMPT_LIMIT && paneOpenedFor !== wantedPane) {
 						innerAttempts += 1
 						paneOpenedFor = wantedPane
-						host.openPane(wantedPane, linked.kind === 'panel' ? 'panel' : 'session', message => host.warn(message))
+						host.openPane(wantedPane, link.kind === 'panel' ? 'panel' : 'session', message => host.warn(message))
 					}
 					armRetry()
 					return
 				}
-				if (linked.kind === 'session' && linked.inner !== undefined && innerPath(linked.inner)[0] === TURN_SEGMENT) {
-					// A turn link is a position, not a surface: the conversation is opened, and the
-					// view is told once that this build does not scroll to the turn (see README).
-					// Record the position so the canonical form keeps it, then fall through to the
-					// ordinary conversation branch: a turn link opens the conversation, and saying so
-					// in the console would only be noise.
-					turnAnchor = { session: linked.id, turn: innerPath(linked.inner)[1] }
+				if (link.kind === 'session' && link.inner !== undefined && innerPath(link.inner)[0] === TURN_SEGMENT) {
+					// A turn link is a position, and a drivable one: the conversation is opened and the turn
+					// is brought into view in the same step, because the link lands as soon as the address
+					// bar names it. A turn that is not loaded yet is paged back through its seq.
+					//
+					// The position is recorded only *after* the drive: recording it first would make the
+					// canonical form equal the link already, so a link that has not moved anything would
+					// look "landed" and never be driven (a real bug, live-measured).
+					const wantedTurn = innerPath(link.inner)[1]
+					const wantedSession = link.id
+					// Drive first, record second. Recording first would make the canonical form equal the
+					// link on the *next* reconcile — before the drive ever ran, so the link would look
+					// "landed" and the position would never be brought into view (live-measured). Driving
+					// first means the work is done by the time the form can match.
+					if (innerAttempts < INNER_ATTEMPT_LIMIT) {
+						innerAttempts += 1
+						// The conversation has to be on screen before anything inside it can be brought into
+						// view: driving a turn against a conversation that is not shown is a silent no-op, which
+						// is what a cold-opened turn link used to do. So navigate first, and drive only once the
+						// conversation is really the main view.
+						// Bring the conversation up *and* drive the position, the way a row link does: the drive is
+						// idempotent on a conversation that is not shown yet (no seats, nothing to scroll to, and
+						// the paging path is a no-op too), and waiting for the main-view counter to catch up is
+						// what left a cold-opened turn link doing nothing at all.
+						host.openSession(wantedSession)
+						host.revealPosition(innerPath([TURN_SEGMENT, wantedTurn]), wantedSession)
+						// A row may follow the turn (`turn/<n>/row/…`): reveal it after the turn.
+						const rowAt = innerPath(link.inner).indexOf(ROW_SEGMENT)
+						if (rowAt >= 0) host.revealPosition(innerPath(link.inner).slice(rowAt), wantedSession)
+					}
+					turnAnchor = { session: wantedSession, turn: wantedTurn }
+					return
 				}
-				if (linked.kind === 'panel') {
-					if (linked.inner !== undefined && innerPath(linked.inner)[0] === PANE_SEGMENT) {
+				if (link.kind === 'panel') {
+					if (link.inner !== undefined && innerPath(link.inner)[0] === PANE_SEGMENT) {
 						if (innerAttempts < INNER_ATTEMPT_LIMIT) {
 							innerAttempts += 1
-							host.openPane(innerPath(linked.inner)[1], linked.kind === 'panel' ? 'panel' : 'session', message => host.warn(message))
+							host.openPane(innerPath(link.inner)[1], link.kind === 'panel' ? 'panel' : 'session', message => host.warn(message))
 						}
 						armRetry()
 						return
@@ -823,7 +917,7 @@ window.__ModuleLoader__.load({
 					// panel store moves (a late-loading plugin), not on every catalog tick.
 					// `current` may be undefined when nothing is on screen yet; reading through it
 					// unconditionally would abort the whole step inside the guard.
-					const panelShown = current !== undefined && current.kind === 'panel' && current.id === linked.id
+					const panelShown = current !== undefined && current.kind === 'panel' && current.id === link.id
 					if (!panelShown) {
 						// Selecting a panel can be refused or swallowed while the shell is still
 						// settling, so the request is retried (on later notifications and on a
@@ -834,7 +928,7 @@ window.__ModuleLoader__.load({
 							// in flight first (the layout exposes exactly that pair), otherwise the
 							// selection can be swallowed by the boot restore.
 							host.beginNavigation()
-							host.selectPanel(linked.id)
+							host.selectPanel(link.id)
 						}
 						armRetry()
 						return
@@ -845,24 +939,24 @@ window.__ModuleLoader__.load({
 					// once that panel has rendered: the request is retried on every later
 					// notification (not on the hash read itself, to avoid a double request),
 					// with a bound so an unopenable page cannot turn into a click loop.
-					if (linked.inner !== undefined && routeKey(current) !== routeKey(linked) && source !== 'hash' && innerAttempts < INNER_ATTEMPT_LIMIT) {
+					if (link.inner !== undefined && routeKey(current) !== routeKey(link) && source !== 'hash' && innerAttempts < INNER_ATTEMPT_LIMIT) {
 						innerAttempts += 1
-						host.openPanelPage(linked.id, linked.inner)
+						host.openPanelPage(link.id, link.inner)
 					}
 					armRetry()
 					return
 				}
 				// A session link: refuse immediately when the conversation cannot be opened at
 				// all, otherwise hand the navigation over once and wait for the view to land.
-				if (host.isArchived(linked.id)) {
-					host.warn(`${TAG} ${routeHash(linked.kind, linked.id)} is archived; the link was ignored`)
+				if (host.isArchived(link.id)) {
+					host.warn(`${TAG} ${routeHash(link.kind, link.id)} is archived; the link was ignored`)
 					dropLink()
 					reflect(canonical())
 					return
 				}
-				if ((!claimed || moved) && host.isOpenable(linked.id)) {
+				if ((!claimed || moved) && host.isOpenable(link.id)) {
 					claimed = true
-					host.openSession(linked.id)
+					host.openSession(link.id)
 				}
 			}
 			/** Adopt the surface the address bar names, if it names one. */
@@ -1384,7 +1478,7 @@ window.__ModuleLoader__.load({
 		// browser wiring: probe the official faces, then drive the machine.
 		// ---------------------------------------------------------------------
 		/** Services this plugin needs before apply runs; `layout` is optional and read through `ctx.get`. */
-		const inject = ['sessions', 'workspaces', 'uiWorkspace', 'slots', 'sidebarRightTabs']
+		const inject = ['sessions', 'workspaces', 'uiWorkspace', 'slots', 'sidebarRightTabs', 'uiConversation']
 
 		/**
 		 * Probe the faces the router needs.
@@ -1397,6 +1491,11 @@ window.__ModuleLoader__.load({
 		 */
 		function probeFaces(scope) {
 			const list = scope.sessions?.list
+			// The session controller itself (not just its catalog): the turn drive needs
+			// `retainScope(id, source)` to reach a session that is not loaded yet. It lives in `inject`
+			// for the same reason `uiConversation` does — cordis only hands a service to a plugin that
+			// declared it — and reading it here is what makes the paging path reachable at all.
+			const sessions = scope.sessions
 			const registry = scope.workspaces?.list
 			const navigation = scope.uiWorkspace
 			if (typeof list !== 'object' || list === null) return null
@@ -1422,6 +1521,9 @@ window.__ModuleLoader__.load({
 			const openRightbar = typeof layout?.openRightbar === 'function' ? layout.openRightbar.bind(layout) : undefined
 			const sidebarRightTabs = typeof scope.get === 'function' ? scope.get('sidebarRightTabs') : undefined
 			const sidebarRight = typeof scope.get === 'function' ? scope.get('sidebarRight') : undefined
+			// `uiConversation` is a root service, but cordis only hands it to a plugin that
+			// declared it in `inject` — declaring it is what makes the view registry readable.
+			const uiConversation = typeof scope.get === 'function' ? scope.get('uiConversation') : undefined
 			return {
 				faces: {
 					catalog: list,
@@ -1432,6 +1534,8 @@ window.__ModuleLoader__.load({
 				openRightbar: openRightbar === undefined ? undefined : track => openRightbar(track),
 				sidebarRightTabs,
 				sidebarRight,
+				uiConversation,
+				sessions,
 					panels,
 					slots,
 				},
@@ -1459,7 +1563,7 @@ window.__ModuleLoader__.load({
 				const ids = attempt(() => faces.archivedSessionIds(), [])
 				return Array.isArray(ids) ? ids : []
 			}
-			return {
+			const host = {
 				mainViewSessionId: () => attempt(() => mainViewSessionId(faces.catalog.getSnapshot().byId), undefined),
 				// The sidebar lists workspaces and their sessions in one tree, in order, so the
 				// workspace a conversation belongs to is the nearest workspace row before it.
@@ -1600,7 +1704,19 @@ window.__ModuleLoader__.load({
 					return before
 				},
 				// Best effort: scroll to the named row when it is rendered.
-				revealRow: parts => {
+				/**
+				 * Bring the named position into view.
+				 *
+				 * A trajectory row is scrolled to when it is rendered. A *turn* needs history paged
+				 * back first, and that part is a public slot contract rather than a guess:
+				 * `session.loadThrough(seq)` pages backwards until the window covers the seq of that
+				 * turn's start event (measured in the core, and the same path the chat view uses). The
+				 * seq comes from the `turnOutline` projection, which is readable through the session
+				 * controller's projections face.
+				 * @param {Array} parts - the inner path segments.
+				 * @returns {boolean} whether the position was brought into view.
+				 */
+				revealPosition: (parts, wantedSession) => {
 					const wanted = innerPath(parts)
 					const document = window.document
 					if (wanted[0] === ROW_SEGMENT && wanted.length >= 3) {
@@ -1612,14 +1728,40 @@ window.__ModuleLoader__.load({
 						}
 						return false
 					}
-					if (wanted[0] === TURN_SEGMENT) {
-						for (const candidate of document?.querySelectorAll?.(`[${TRAJECTORY_TURN_ATTRIBUTE}]`) ?? []) {
-							if (candidate.getAttribute?.(TRAJECTORY_TURN_ATTRIBUTE) !== wanted[1]) continue
-							attempt(() => candidate.scrollIntoView?.({ block: 'center' }))
-							return true
-						}
+					if (wanted[0] !== TURN_SEGMENT) return false
+					const turn = wanted[1]
+					// 1) Already rendered: the chat seats carry `data-chat-turn` (what the official
+					//    ChatNodeSeat prints), so scroll to it and be done.
+					// Official viewport selector: a seat that is hidden, or inside anything hidden, is not on
+					// screen — and the virtual list renders such seats for turns that are plainly not loaded.
+					for (const candidate of document?.querySelectorAll?.(`[${TURN_ATTRIBUTE}]:not([hidden])`) ?? []) {
+							if (candidate.getAttribute?.(TURN_ATTRIBUTE) !== turn) continue
+						attempt(() => candidate.scrollIntoView?.({ block: 'center' }))
+						return true
+					}
+					// 2) Not loaded yet: page history back through that turn's seq, then its seat renders.
+					//
+					//    The session controller is reached by *retaining* its scope: `sessions.binding(id)`
+					//    answers undefined for a session nobody materialised yet (measured), while
+					//    `retainScope(id, source)` materialises it and returns a reference whose `binding`
+					//    is the live one. The reference is released as soon as the page-back is asked for, so
+					//    retaining costs nothing when the turn turns out to be unloadable.
+					// The session the position belongs to is passed in by the caller, because the turn that
+					// drove it may not be the main view *yet* (a link that just opened it): reading it back
+					// from the catalog here is how this step used to look up "no session".
+					const reference = attemptValue(() => faces.sessions?.retainScope?.(wantedSession, 'url-router'))
+					const session = attemptValue(() => reference?.binding?.session)
+					const loadThrough = attemptValue(() => (session === undefined || session === null ? undefined : session.loadThrough))
+					const outline = attemptValue(() => session?.projections?.faceOf?.('turnOutline')?.getSnapshot?.())
+					const seq = Array.isArray(outline) ? outline.find(entry => entry && String(entry.turn) === String(turn))?.seq : undefined
+					const usable = typeof loadThrough === 'function' && typeof reference?.release === 'function'
+					if (typeof seq !== 'number' || !usable) {
+						attemptValue(() => reference?.release?.())
+						return false
 					}
-					return false
+					attemptValue(() => loadThrough(seq))
+					attemptValue(() => reference.release())
+					return true
 				},
 				// Which conversation view is showing. The registry is the source of truth for ids
 				// (`ctx.uiConversation.views`), the header renders its tabs in registration order,
@@ -1904,6 +2046,7 @@ window.__ModuleLoader__.load({
 					}, () => {}),
 				warn: message => console.warn(message),
 			}
+			return host
 		}
 
 		/**
@@ -1923,6 +2066,17 @@ window.__ModuleLoader__.load({
 					console.warn(`${TAG} the layout service exposes no panel store; only conversation routes are routed`)
 				}
 				return startUrlRouting(browserHost(probed.faces))
+				// The session-scoped seat. A conversation's jump loader (`session.loadThrough(seq)`) lives
+				// on the session controller, and a root plugin only reaches a session by *contributing* to
+				// a session-scoped slot — the same seat the official chat and the family views use
+				// (`inject: (sessionId) => …`). The entry itself draws nothing: it exists so the callback
+				// runs with the session in hand. The entry itself is inert (it renders nothing and adds
+				// nothing to the tail), and it rides a `list` slot so it can never become the chosen view.
+				// (A session-scoped seat was tried here: contributing to a session-scoped slot is how a
+				// root plugin reaches a session controller. It did not fire — measured live — and the
+				// session-scoped slots that *would* fire (`conversation.view`) always add a visible tab,
+				// so the seat was withdrawn. `sessionFor` stays as the seam for when a seam exists.)
+				probed.faces.sessionFor = () => undefined
 			}, 'url-router: fragment routing')
 			// Row links: every conversation row is exposed as a real link to its route, so
 			// the browser's own link menu (open in new tab / copy link) works on it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-url-router",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "DSH Web GUI 地址栏路由插件：每个界面都有自己的链接（会话 / 主面板 / 插件页与组件页 / 任务看板），整行即真链接，只写 fragment。",
   "repository": {
     "type": "git",
@@ -30,7 +30,8 @@
         "@deepseek-ai/dsh-api-workspace-controller",
         "@deepseek-ai/dsh-client-ui-workspace",
         "@deepseek-ai/dsh-client-ui-layout",
-        "@deepseek-ai/dsh-client-ui-sidebar-right"
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-conversation"
       ]
     },
     "compatibility": {