dsh-url-router 0.2.0 → 0.3.1

package/lib/client.js

@@ -90,6 +90,22 @@ window.__ModuleLoader__.load({
 		const TASK_BOARD_NEW_EVENT = 'dsh-taskboard-new-task'
 		/** Sidebar row key prefix for a workspace (the value is its id; the row text is its name). */
 		const WORKSPACE_ROW_PREFIX = 'workspace:'
+		/** Stable container the conversation header renders its view tabs into. */
+		const CONVERSATION_TABS_ATTRIBUTE = 'data-conversation-tabs'
+		/** Attribute each trajectory row carries: `<kind>%00<scope>%00<id>`. */
+		const TRAJECTORY_ROW_ATTRIBUTE = 'data-trajectory-row-key'
+		/** Attribute the family trajectory view puts on a row's turn cell. */
+		const TRAJECTORY_TURN_ATTRIBUTE = 'data-dshts-turn'
+		/** The right bar's own root: it carries the session the bar belongs to. */
+		const RIGHT_BAR_ATTRIBUTE = 'data-sidebar-right-session'
+		/** The right bar's tab strip: only *tabs* live here (the empty state has a bare pane). */
+		const RIGHT_BAR_STRIP_ATTRIBUTE = 'data-dockkit-strip-tabs'
+		/** Attribute the trajectory view puts on the first row of a turn. */
+		const TRAJECTORY_TURN_START_ATTRIBUTE = 'data-turn-start'
+		/** Inner segment that names one row inside a conversation view. */
+		const ROW_SEGMENT = 'row'
+		/** Inner segment that names which conversation view is showing. */
+		const VIEW_SEGMENT = 'view'
 		/** Inner segment that marks the conversation inside a workspace route. */
 		const WORKSPACE_SESSION_SEGMENT = 'session'
 		/** Attribute the chat view puts on every rendered turn node (the turn number). */
@@ -103,8 +119,51 @@ window.__ModuleLoader__.load({
 		/** Panel id of the official plugin manager, whose list rows and detail pages are routed. */
 		const PLUGINS_PANEL_ID = 'plugins'
 		/** Log prefix for every diagnostic. */
+		/**
+		 * 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.1'
+
 		const TAG = '[url-router]'
 
+		/**
+		 * The conversation view ids the registry publishes, in registration order — the same order
+		 * the header renders its tabs in, which is what lets a tab position map back to an id.
+		 * @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) {
+			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
+		}
+
+		/**
+		 * Read a value, or undefined when reading it throws.
+		 * @param {Function} read - the reader.
+		 * @returns {*} the value, or undefined.
+		 */
+		function attemptValue(read) {
+			try {
+				return read()
+			} catch {
+				return undefined
+			}
+		}
+
 		/**
 		 * The workspace a sidebar row belongs to: the nearest workspace row before it, read from the
 		 * row text. Returns undefined when the tree says nothing, so no caller has to guess.
@@ -129,6 +188,166 @@ window.__ModuleLoader__.load({
 			return undefined
 		}
 
+		/**
+		 * The kind inside a tab id: the bar builds one as `sidebar://<kind>` and appends a uuid for
+		 * kinds that may be opened more than once, so the kind is right there in the address.
+		 * @param {string} value - a tab id.
+		 * @returns {string|undefined} the kind, when the value is one of these addresses.
+		 */
+		/**
+		 * The right bar's registry, normalised: one row per page type with its kind, the label
+		 * the tab shows, whether more than one may be open, and its empty-state card (measured
+		 * live: `{kind, title(): () => string, multiple?: true, guide?: [{id, order}]}`).
+		 * @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
+			const out = []
+			for (const row of rows) {
+				if (row === null || typeof row !== 'object') continue
+				const kind = row.kind ?? row.options?.kind ?? row.id
+				if (typeof kind !== 'string' || kind === '') continue
+				const label = attemptValue(() => (typeof row.title === 'function' ? row.title() : row.title))
+				out.push({ kind, label: typeof label === 'string' && label !== '' ? label : undefined, multiple: row.multiple === true })
+			}
+			return out.length === 0 ? undefined : out
+		}
+
+		/**
+		 * A tab label compared without the noise a visible label can carry (padding, an underline
+		 * marker, a shortcut hint), so a registry label can be matched to what the tab shows.
+		 * @param {string} value - the text to flatten.
+		 * @returns {string} the flattened text.
+		 */
+		function flatLabel(value) {
+			return String(value).replace(/\s+/g, ' ').trim()
+		}
+
+		function kindOfTabId(value) {
+			if (typeof value !== 'string' || value === '') return undefined
+			const match = /^sidebar:\/\/([^/?#]+)/.exec(value)
+			return match === null ? undefined : decodeURIComponent(match[1])
+		}
+		
+		/**
+		 * The session the right bar belongs to: the bar is per session and says so on its own root.
+		 * @param {object} document - the document to read.
+		 * @returns {string|undefined} the session id.
+		 */
+		function rightBarSessionIdOf(document) {
+			const root = attemptValue(() => document?.querySelector?.(`[${RIGHT_BAR_ATTRIBUTE}]`))
+			const id = root === null || root === undefined ? null : attemptValue(() => root.getAttribute?.(RIGHT_BAR_ATTRIBUTE))
+			return typeof id === 'string' && id !== '' ? id : undefined
+		}
+
+		/**
+		 * The right bar's active tab kind, read from its *strip*: the empty state also renders a
+		 * `data-dockkit-pane`, so any pane-active marker would report a tab that is not there.
+		 * @param {object} document - the document to read.
+		 * @returns {string|undefined} the active kind.
+		 */
+		/**
+		 * Notes already said, across reconciles: a compatibility note is useful the first time, and
+		 * a plugin that repeats it every reconcile is a log spammer.
+		 */
+		const paneNotes = new Set()
+		/**
+		 * Say a pane diagnostic once.
+		 * @param {Function} warn - the host's warning sink.
+		 * @param {string} key - deduplication key.
+		 * @param {string} message - what to say.
+		 */
+		const notePaneShape = (warn, key, message) => {
+			if (paneNotes.has(key)) return
+			paneNotes.add(key)
+			warn(`${TAG} ${message}`)
+		}
+
+		function activePaneTabOf(document, registry) {
+			// Scoped to the right bar's own root: the same dockkit attributes dress the main area
+			// too, and reading them unscoped reports the main area's panes, not this bar's tabs.
+			const right = attemptValue(() => document?.querySelector?.(`[${RIGHT_BAR_ATTRIBUTE}]`))
+			const scope = right === null || right === undefined ? document : right
+			const strip = typeof scope?.querySelector === 'function' ? attemptValue(() => scope.querySelector(`[${RIGHT_BAR_STRIP_ATTRIBUTE}]`)) : undefined
+			if (strip === null || strip === undefined) return undefined
+			// A tab is `role="tab"` with its id in `data-dockkit-tab` — and that id *is* the page
+			// address, so the kind sits inside it. Pane markers belong to the content area.
+			// Remember what the strip holds, *before* trying to read it: this is what a compatibility
+			// note has to name when nothing can be read, so it must be recorded either way.
+			const described = attemptValue(() => {
+				const child = strip.children?.[0]
+				if (child === undefined) return undefined
+				// An Attr list and a Map both show up (the DOM makes the former, a stub the latter).
+				const pairs = [...child.attributes].map(attribute => Array.isArray(attribute) ? { name: attribute[0], value: attribute[1] } : attribute)
+				return pairs.map(attribute => `${attribute.name}="${String(attribute.value).slice(0, 24)}"`).join(' ')
+			})
+			if (typeof described === 'string') activePaneTabOf.observed = described
+			const tabs = typeof strip.querySelectorAll === 'function' ? attemptValue(() => [...strip.querySelectorAll('[role="tab"]')]) : undefined
+			if (!Array.isArray(tabs) || tabs.length === 0) return undefined
+			const chosen = tabs.find(tab => attemptValue(() => tab.getAttribute?.('aria-selected')) === 'true') ?? tabs[0]
+			// The tab's own name is the reliable source: measured live, `data-dockkit-tab` and
+			// `data-dockkit-content` both carry the strip's tab id (`tab3`), which says nothing about
+			// the kind — while the visible label *is* the kind's name (`Files`, `Start`, `Terminal`).
+			const nameOfTab = tab => {
+				const labelled = attemptValue(() => tab.getAttribute?.('aria-label')) ?? attemptValue(() => tab.getAttribute?.('title'))
+				if (typeof labelled === 'string' && labelled.trim() !== '') return labelled.trim()
+				const text = attemptValue(() => (tab.textContent ?? '').trim())
+				return typeof text === 'string' && text !== '' && text.length < 40 ? text : undefined
+			}
+			// 1) the tab's name, resolved to a kind through the registry whenever it can be: the
+			// registry publishes the very label each tab shows, so a link can carry the kind
+			// (`pane/files`) instead of a sentence in whatever language is on screen.
+			const named = nameOfTab(chosen)
+			if (named !== undefined) {
+				const wanted = flatLabel(named).toLowerCase()
+				const match = Array.isArray(registry) ? registry.find(row => typeof row.label === 'string' && flatLabel(row.label).toLowerCase() === wanted) : undefined
+				return match === undefined ? named : match.kind
+			}
+			// 2) an address-shaped id, for a future build that puts one there
+			const fromTab = kindOfTabId(attemptValue(() => chosen.getAttribute?.('data-dockkit-tab')))
+			if (fromTab !== undefined) return fromTab
+			// 3) the tab host section, likewise
+			const hosts = typeof scope.querySelectorAll === 'function' ? attemptValue(() => [...scope.querySelectorAll('[data-dockkit-content]')]) : []
+			for (const host of hosts) {
+				const kind = kindOfTabId(attemptValue(() => host.getAttribute?.('data-dockkit-content')))
+				if (kind !== undefined) return kind
+			}
+			return undefined
+		}
+
 		/**
 		 * Read a route out of a location fragment.
 		 * @param {string} hash - the raw `window.location.hash`, including the leading `#`.
@@ -142,6 +361,24 @@ window.__ModuleLoader__.load({
 			}
 		}
 
+		/**
+		 * The fragment, when it belongs to some other writer.
+		 *
+		 * A URL has exactly one fragment, so two plugins that both write it can only take turns:
+		 * whichever wrote last owns it, and the other one's link is gone. This router never
+		 * pretends otherwise — it names the fragment it did not write and leaves it alone.
+		 * @param {string} hash - the current fragment.
+		 * @returns {string|undefined} the foreign fragment, or undefined when it is ours (or empty).
+		 */
+		function foreignFragmentOf(hash) {
+			if (typeof hash !== 'string') return undefined
+			const trimmed = hash.trim()
+			if (trimmed === '' || trimmed === '#') return undefined
+			const match = ROUTE_PATTERN.exec(trimmed)
+			if (match !== null && ROUTE_ALIASES[match[1]] !== undefined) return undefined
+			return trimmed
+		}
+
 		function parseRoute(hash) {
 			const match = ROUTE_PATTERN.exec(hash)
 			if (match === null) return undefined
@@ -159,7 +396,19 @@ window.__ModuleLoader__.load({
 				if (rest.length < 2 || rest[0] !== WORKSPACE_SESSION_SEGMENT) return { unknown: `workspace/${match[2]}` }
 				const sessionId = rest[1].trim()
 				if (sessionId === '') return { unknown: `workspace/${match[2]}` }
-				return { kind: 'workspace', id: name, inner: innerPath([WORKSPACE_SESSION_SEGMENT, sessionId]) }
+				// 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]]) }
+				if (tail[0] === ROW_SEGMENT && tail.length >= 3) return { kind: 'workspace', id: name, inner: innerPath([WORKSPACE_SESSION_SEGMENT, sessionId, ...tail]) }
+				if (tail[0] === PANE_SEGMENT && tail.length === 2) return { kind: 'workspace', id: name, inner: innerPath([WORKSPACE_SESSION_SEGMENT, sessionId, PANE_SEGMENT, tail[1]]) }
+				return { unknown: `workspace/${match[2]}` }
 			}
 			const segments = match[2].replace(/\/+$/, '').split('/')
 			const head = segments.shift() ?? ''
@@ -307,6 +556,12 @@ window.__ModuleLoader__.load({
 			/** The package segment of the deepest panel page the address bar carried. */
 			let panelScope
 			/** The turn the user last clicked inside a conversation, with its session. */
+			/** What the report can say about this run: fragments it refused, kinds it left alone. */
+			const observed = { foreignFragment: undefined, ignored: [], warnings: [] }
+			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
@@ -328,6 +583,7 @@ window.__ModuleLoader__.load({
 				claimed = false
 				panelAttempts = 0
 				innerAttempts = 0
+				paneOpenedFor = undefined
 				dropTimer()
 			}
 			/**
@@ -363,17 +619,37 @@ window.__ModuleLoader__.load({
 					// The workspace is part of *where* the conversation lives, so it leads the route.
 					// Reading it from the sidebar keeps this honest: no sidebar (or no matching row)
 					// means the plain conversation route, never a guess.
+					// Which conversation view is showing, when it is not the default one: a plain
+					// conversation keeps its short route, any other view says which one it is.
+					// 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()
+					// 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.
+					const pane = host.activePaneKind()
+					const tail = pane === undefined ? [] : [PANE_SEGMENT, pane]
 					const workspaceName = host.workspaceNameOf(id)
 					if (workspaceName !== undefined) {
-						return { kind: 'workspace', id: workspaceName, inner: innerPath([WORKSPACE_SESSION_SEGMENT, id]) }
+						return { kind: 'workspace', id: workspaceName, inner: innerPath([WORKSPACE_SESSION_SEGMENT, id, ...position, ...tail]) }
 					}
-					const pane = host.activePaneKind()
-					if (pane !== undefined) return { kind: 'session', id, inner: innerPath([PANE_SEGMENT, pane]) }
-					// The turn the user last pointed at is a position inside this conversation;
+					if (tail.length === 0 && position.length > 0) return { kind: 'session', id, inner: innerPath(position) }
+					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
@@ -383,22 +659,78 @@ window.__ModuleLoader__.load({
 			// surface, so the link lands at once instead of sitting there until its window expires.
 			// A *named* section against a different named section is a real difference, so a section
 			// link still drives the overlay to the section it asks for.
-			const sameRoute = (left, right) => {
-				if (routeKey(left) === routeKey(right)) return true
-				// A workspace route is about the conversation it names; the workspace name is what the
-				// link *shows*, so a stale name must not keep the link from landing.
-				if (left?.kind === 'workspace' || right?.kind === 'workspace') {
-					if (left?.kind !== right?.kind) return false
-					return innerPath(left.inner)[1] === innerPath(right.inner)[1]
+			// Whether the view on screen already *is* what a link asked for.
+			//
+			// The rule is directional on purpose: a link may be less specific than the view (a bare
+			// `#/settings` is satisfied by any section, `#/session/<id>` by any view of it), but a view
+			// that is less specific than the link never satisfies it — otherwise a link naming a view
+			// would look "already there" and never be driven.
+			const sessionIdOfRoute = route => {
+				if (route?.kind === 'workspace') return innerPath(route.inner)[1]
+				if (route?.kind === 'session') return route.id
+				return undefined
+			}
+			const viewIdOfRoute = route => {
+				const parts = innerPath(route?.inner)
+				const at = parts.indexOf(VIEW_SEGMENT)
+				return at < 0 ? undefined : parts[at + 1]
+			}
+
+				const paneOf = route => {
+				const parts = innerPath(route?.inner)
+				const at = parts.indexOf(PANE_SEGMENT)
+				return at < 0 ? undefined : parts[at + 1]
 				}
-				if (left?.kind !== 'settings' || right?.kind !== 'settings') return false
-				if (left.id === '' || right.id === '') return true
-				// One level deeper: the same section is satisfied while a link names no tab, but a
-				// link that names a tab has to see that tab.
-				if (left.id !== right.id) return false
-				const leftTab = innerPath(left.inner)[0] ?? ''
-				const rightTab = innerPath(right.inner)[0] ?? ''
-				return leftTab === '' || rightTab === ''
+			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)
+				if (currentSession !== undefined && linkedSession !== undefined) {
+					if (currentSession !== linkedSession) return false
+					const linkedView = viewIdOfRoute(linked)
+					if (linkedView === undefined) {
+						// A row or turn link is a position inside the conversation, so it stays exact; any other
+						// 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)) {
+							// 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.
+						if (parts.includes(PANE_SEGMENT)) return paneOf(current) === paneOf(linked)
+						return true
+					}
+					// A link that names a view has to see that view.
+					return viewIdOfRoute(current) === linkedView
+				}
+				if (current?.kind !== 'settings' || linked?.kind !== 'settings') return false
+				if (linked.id === '') return true
+				if (current.id !== linked.id) return false
+				const linkedTab = innerPath(linked.inner)[0] ?? ''
+				return linkedTab === '' || innerPath(current.inner)[0] === linkedTab
 			}
 			/** Write the fragment for the current view, leaving path and query untouched. */
 			const reflect = route => {
@@ -407,6 +739,18 @@ window.__ModuleLoader__.load({
 				// path or the launch query, and comparing them made every call look like a change.
 				const wantedHash = route === undefined ? '' : routeHash(route.kind, route.id, route.inner)
 				if (hash === wantedHash) return
+				// Somebody else's fragment is on screen: taking it over would erase their link, so
+				// this router stays quiet and says why instead.
+				const foreign = foreignFragmentOf(hash)
+				if (foreign !== undefined) {
+					observed.foreignFragment = foreign
+					const known = observed.warnings.includes(`refused to write over: ${foreign}`)
+					if (!known) {
+						observed.warnings.push(`refused to write over: ${foreign}`)
+						host.warn(`${TAG} not writing a route while ${foreign} is in the address bar: that fragment belongs to another plugin`)
+					}
+					return
+				}
 				// Nothing to name and nothing named: leave the address bar exactly as it is
 				// (this also leaves a foreign fragment alone, which the caller never reaches).
 				if (route === undefined && hash === '') return
@@ -418,15 +762,30 @@ window.__ModuleLoader__.load({
 			 */
 			const reconcile = (source = 'boot') => {
 				if (disposed) return
+
 				const current = canonical()
 				const currentKey = routeKey(current)
 				const moved = currentKey !== seen
 				seen = currentKey
+					// The right bar holds a tab this build cannot name: say it once, with the tab's own
+					// attributes. A silent pane layer is the worst of both worlds — this is how the shape
+					// reaches a bug report instead of a guess.
+					const paneTabs = attemptValue(() => window.document?.querySelector?.(`[${RIGHT_BAR_STRIP_ATTRIBUTE}]`)?.querySelectorAll?.('[role="tab"]')?.length) ?? 0
+					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
@@ -435,17 +794,51 @@ 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())
 					return
 				}
-				if (linked.kind === 'workspace') {
+				// 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(link.inner)
+				const rowAt = rowParts.indexOf(ROW_SEGMENT)
+				const wantedTurn = rowParts.indexOf(TURN_SEGMENT)
+				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) {
+						panelAttempts += 1
+						host.openSession(rowSession)
+					} else if (shown === rowSession && innerAttempts < INNER_ATTEMPT_LIMIT) {
+						innerAttempts += 1
+						if (!host.revealPosition(rowParts.slice(rowAt)) && wantedTurn >= 0) host.revealPosition(rowParts.slice(wantedTurn, wantedTurn + 2), rowSession)
+					}
+					armRetry()
+					return
+				}
+				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.
+					const shown = host.mainViewSessionId()
+					if (shown !== wantedSession && panelAttempts < INNER_ATTEMPT_LIMIT) {
+						panelAttempts += 1
+						host.openSession(wantedSession)
+					} else if (shown === wantedSession && innerAttempts < INNER_ATTEMPT_LIMIT) {
+						innerAttempts += 1
+						host.openConversationView(wantedView)
+					}
+					armRetry()
+					return
+				}
+				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
@@ -454,35 +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 (source !== 'hash' && innerAttempts < INNER_ATTEMPT_LIMIT) {
+				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(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
-						host.openPane(innerPath(linked.inner)[1])
+						paneOpenedFor = wantedPane
+						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 (source !== 'hash' && innerAttempts < INNER_ATTEMPT_LIMIT) {
+				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])
+							host.openPane(innerPath(link.inner)[1], link.kind === 'panel' ? 'panel' : 'session', message => host.warn(message))
 						}
 						armRetry()
 						return
@@ -492,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
@@ -503,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
@@ -514,30 +939,44 @@ 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. */
 			const readLink = () => {
 				if (disposed) return
-				const parsed = parseRoute(host.readLocation().hash)
+				const hash = host.readLocation().hash
+				// Another writer owns the fragment: name it once and step aside. Overwriting it here
+				// is how two routers silently erase each other's links.
+				const foreign = foreignFragmentOf(hash)
+				if (foreign !== undefined) {
+					const known = observed.foreignFragment === foreign
+					observed.foreignFragment = foreign
+					dropLink()
+					if (!known) {
+						host.warn(`${TAG} ${foreign} was written by another plugin (for example a jump-to-message writer); a URL has one fragment, so this router leaves it alone — enable only one writer`)
+						observed.warnings.push(`foreign fragment: ${foreign}`)
+					}
+					return
+				}
+				const parsed = parseRoute(hash)
 				if (parsed === undefined) {
 					dropLink()
 					reconcile('hash')
@@ -546,6 +985,7 @@ window.__ModuleLoader__.load({
 				if (parsed.unknown !== undefined) {
 					// Another router's route (or a typo): leave the address bar alone and say so
 					// once, so a router owning more kinds can take over later.
+					if (!observed.ignored.includes(parsed.unknown)) observed.ignored.push(parsed.unknown)
 					if (linked === undefined) host.warn(`${TAG} ignoring unknown route kind "${parsed.unknown}"`)
 					return
 				}
@@ -615,27 +1055,91 @@ window.__ModuleLoader__.load({
 				if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
 				const target = event.target
 				if (typeof target?.closest !== 'function') return
-				const node = target.closest(`[${TURN_ATTRIBUTE}]`)
-				if (node === null) return
+				// A trajectory row names itself first: it carries its own identity (and is often a
+				// button), while a chat turn carries only a turn number. Both paths are pure observers
+				// — nothing is prevented, so clicks keep behaving exactly as the views expect.
+				const session = host.mainViewSessionId()
+				const rowOwner = attemptValue(() => host.rowIdentityOf(target))
+				if (rowOwner !== undefined) {
+					if (session !== undefined) {
+						if (rowOwner[0] === TURN_SEGMENT && rowOwner.length === 2) {
+							turnAnchor = { session, turn: rowOwner[1] }
+							rowAnchor = undefined
+						} else {
+							// The view's own key carries the turn for assistant nodes but not for tool
+							// calls; when the row sits between two rendered turn boundaries the turn is
+							// provable, so the link may say it. Otherwise it stays out of the route.
+							const turn = rowOwner.includes(TURN_SEGMENT) ? undefined : attemptValue(() => host.turnOfRow(target))
+							rowAnchor = turn === undefined || turn === '' ? { session, parts: rowOwner } : { session, turn, parts: rowOwner }
+							turnAnchor = undefined
+						}
+						safeReconcile('row')
+					}
+					return
+				}
 				// One selector at a time: a comma list is the kind of thing a small DOM stub (and a
 				// future minimal engine) may not implement, and the answer must be the same.
 				for (const interactive of ['button', 'a', 'input', 'textarea', 'select', '[role="button"]', '[contenteditable="true"]']) {
 					if (target.closest(interactive) !== null) return
 				}
+				const node = target.closest(`[${TURN_ATTRIBUTE}]`)
+				if (node === null) return
+				const id = session
+				if (id === undefined) return
 				const raw = node.getAttribute?.(TURN_ATTRIBUTE)
 				const turn = typeof raw === 'string' ? raw.trim() : ''
 				if (turn === '') return
-				const id = host.mainViewSessionId()
-				if (id === undefined) return
 				turnAnchor = { session: id, turn }
-				safeReconcile('turn')
-			}
+				rowAnchor = undefined
+				safeReconcile('turn')			}
 			try {
 				window.document?.addEventListener?.('click', onDocumentClick, true)
 			} catch {
 				// A composition without the DOM listener is still a working router.
 			}
 
+			/**
+			 * The route health report: every layer this router knows about, the shape it is in right
+			 * now, and everything it refused to touch. Reachable as `window.__dshUrlRouter.report()`
+			 * — a debug seam, so it never throws and never writes anything.
+			 * @returns {object} the report.
+			 */
+			const report = () => {
+				const current = attemptValue(() => canonical())
+				const document = window.document
+				const count = selector => attemptValue(() => document?.querySelectorAll?.(selector)?.length) ?? '\u2014'
+				return {
+					version: ROUTER_VERSION,
+					hash: attemptValue(() => host.readLocation().hash) ?? '',
+					canonical: current === undefined ? null : { kind: current.kind, id: current.id, inner: innerPath(current.inner) },
+					link: linked === undefined ? null : { hash: routeHash(linked.kind, linked.id, linked.inner), attempts: { panel: panelAttempts, inner: innerAttempts } },
+					surfaces: {
+						conversationRows: count(`[data-row-key^="${ROW_KEY_PREFIX}"]`),
+						workspaceRows: count(`[data-row-key^="${WORKSPACE_ROW_PREFIX}"]`),
+						viewTabs: count(`[${CONVERSATION_TABS_ATTRIBUTE}]`),
+						viewIds: attemptValue(() => host.conversationViewIds?.()) ?? [],
+						turns: count(`[${TURN_ATTRIBUTE}]`),
+						trajectoryRows: count(`[${TRAJECTORY_ROW_ATTRIBUTE}]`),
+						turnBoundaries: count(`[${TRAJECTORY_TURN_START_ATTRIBUTE}]`),
+						pluginPackages: count('[data-plugin-package]'),
+						officialItems: count('[data-plugin-item]'),
+						settingsOverlay: count(`[${SETTINGS_SURFACE_ATTRIBUTE}="${SETTINGS_SURFACE_VALUE}"]`),
+						settingsSection: attemptValue(() => host.activeSettingsSection()) ?? null,
+						taskBoardOpen: count(`[${TASK_BOARD_OPEN_ATTRIBUTE}]`),
+						taskBoardNew: count(`[${TASK_BOARD_NEW_ATTRIBUTE}]`),
+						paneActive: attemptValue(() => host.activePaneKind()) ?? null,
+						paneKinds: attemptValue(() => host.paneKinds?.()) ?? null,
+					},
+					compat: observed.compat,
+					foreignFragment: observed.foreignFragment,
+					ignoredKinds: observed.ignored,
+					warnings: observed.warnings,
+				}
+			}
+			guard(() => {
+				window.__dshUrlRouter = { version: ROUTER_VERSION, report, when: host.now() }
+			})
+
 			return () => {
 				disposed = true
 				try {
@@ -974,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.
@@ -987,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
@@ -1012,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,
@@ -1019,9 +1531,11 @@ window.__ModuleLoader__.load({
 					openSession: id => openSession.call(navigation, id),
 					selectPanel: selectPanel === undefined ? undefined : id => selectPanel(id),
 					beginNavigation: beginNavigation === undefined ? undefined : () => beginNavigation(),
-				openRightbar: openRightbar === undefined ? undefined : () => openRightbar(),
+				openRightbar: openRightbar === undefined ? undefined : track => openRightbar(track),
 				sidebarRightTabs,
 				sidebarRight,
+				uiConversation,
+				sessions,
 					panels,
 					slots,
 				},
@@ -1049,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.
@@ -1151,15 +1665,168 @@ window.__ModuleLoader__.load({
 				openSession: id => {
 					attempt(() => faces.openSession(id))
 				},
+				// A row's own identity, in the shape the trajectory views publish it. The value is a
+				// percent-encoded NUL-separated triple, so the route can read as a plain path.
+				rowIdentityOf: element => {
+					let node = element
+					for (let depth = 0; node !== null && node !== undefined && depth < 12; depth += 1, node = node.parentElement) {
+						if (typeof node.getAttribute !== 'function') break
+						const key = node.getAttribute(TRAJECTORY_ROW_ATTRIBUTE)
+						if (typeof key === 'string' && key !== '') {
+							const parts = key.split('%00').map(part => part.trim()).filter(part => part !== '')
+							if (parts.length >= 2) return parts
+						}
+						const turn = node.getAttribute(TRAJECTORY_TURN_ATTRIBUTE)
+						if (typeof turn === 'string' && turn.trim() !== '') return [TURN_SEGMENT, turn.trim()]
+					}
+					return undefined
+				},
+				// The turn a row belongs to, but only when it is *provable*: the trajectory view
+				// virtualizes, so the evidence is a turn boundary rendered before the row, and that is
+				// trustworthy exactly when the next boundary is also rendered after it. Otherwise the
+				// answer is undefined — never a guess.
+				turnOfRow: element => {
+					if (typeof element?.compareDocumentPosition !== 'function') return undefined
+					const boundaries = window.document?.querySelectorAll?.(`[${TRAJECTORY_TURN_START_ATTRIBUTE}]`)
+					if (boundaries === undefined || boundaries === null || boundaries.length === 0) return undefined
+					const following = window.Node?.DOCUMENT_POSITION_FOLLOWING ?? 4
+					const preceding = window.Node?.DOCUMENT_POSITION_PRECEDING ?? 2
+					let before
+					let after
+					for (const boundary of boundaries) {
+						const position = attemptValue(() => element.compareDocumentPosition(boundary)) ?? 0
+						const turn = (boundary.getAttribute?.(TRAJECTORY_TURN_START_ATTRIBUTE) ?? '').trim()
+						if (turn === '') continue
+						if ((position & following) !== 0) after ??= turn
+						if ((position & preceding) !== 0) before = turn
+					}
+					if (before === undefined || after === undefined || before === after) return undefined
+					return before
+				},
+				// Best effort: scroll to the named row when it is rendered.
+				/**
+				 * 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) {
+						const key = wanted.slice(1).join('%00')
+						for (const candidate of document?.querySelectorAll?.(`[${TRAJECTORY_ROW_ATTRIBUTE}]`) ?? []) {
+							if (candidate.getAttribute?.(TRAJECTORY_ROW_ATTRIBUTE) !== key) continue
+							attempt(() => candidate.scrollIntoView?.({ block: 'center' }))
+							return true
+						}
+						return false
+					}
+					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
+					}
+					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,
+				// and the active tab is the aria-selected one — so the position maps to an id.
+				activeConversationView: () => {
+					// One selector at a time: the container first, then its tabs inside it.
+					const row = window.document?.querySelector?.(`[${CONVERSATION_TABS_ATTRIBUTE}]`)
+					const tabs = typeof row?.querySelectorAll === 'function' ? row.querySelectorAll('[role="tab"]') : undefined
+					if (tabs === undefined || tabs === null || tabs.length === 0) return undefined
+					let index = -1
+					for (let position = 0; position < tabs.length; position += 1) {
+						const tab = tabs[position]
+						if (typeof tab.getAttribute !== 'function') continue
+						if (tab.getAttribute('aria-selected') !== 'true') continue
+						index = position
+						break
+					}
+					if (index < 0) return undefined
+					const ids = conversationViewIdsOf(faces)
+					if (ids === undefined || ids.length !== tabs.length) return undefined
+					return { id: ids[index], index, total: ids.length }
+				},
+				openConversationView: viewId => {
+					const row = window.document?.querySelector?.(`[${CONVERSATION_TABS_ATTRIBUTE}]`)
+					const tabs = typeof row?.querySelectorAll === 'function' ? row.querySelectorAll('[role="tab"]') : undefined
+					if (tabs === undefined || tabs === null) return
+					const ids = conversationViewIdsOf(faces)
+					if (ids === undefined) return
+					const index = ids.indexOf(viewId)
+					const tab = index < 0 ? undefined : tabs[index]
+					if (typeof tab?.click === 'function') attempt(() => tab.click())
+				},
 				// The right-hand pane names the tab in front. The service is the source of truth;
 				// the DOM marker is a fallback for a composition where the service is absent.
+				rightBarSessionId: () => rightBarSessionIdOf(window.document),
+				activePaneTab: () => activePaneTabOf(window.document),
 				activePaneKind: () => {
-					const face = faces.sidebarRightTabs
-					if (face !== undefined) {
-						const snapshot = attempt(() => (typeof face.getSnapshot === 'function' ? face.getSnapshot() : undefined))
-						const active = snapshot === undefined ? undefined : snapshot.activeTabId ?? snapshot.activeTab ?? snapshot.active
-						if (typeof active === 'string' && active !== '') return active
+					// Both services answer `active`; the controller is authoritative when it does, and
+					// `active` may be exposed as a value or as a method. Neither exposes `getSnapshot`.
+					// `active` can be a string, a tab descriptor or a method returning either, and the
+					// bar's own tab objects carry the kind under a few plausible names.
+					const kindOf = value => {
+						if (typeof value === 'string') return value === '' ? undefined : value
+						if (value === null || typeof value !== 'object') return undefined
+						const nested = value.tab ?? value.entry ?? value.options
+						const candidates = [value.kind, value.id, value.tabId, value.name, nested?.kind, nested?.id]
+						for (const candidate of candidates) {
+							if (typeof candidate === 'string' && candidate !== '' && candidate !== 'pane1') return candidate
+						}
+						return undefined
 					}
+					const read = owner => {
+						if (owner === undefined || owner === null) return undefined
+						const value = typeof owner.active === 'function' ? attemptValue(() => owner.active()) : owner.active
+						const direct = kindOf(value)
+						if (direct !== undefined) return direct
+						const snapshot = attemptValue(() => (typeof owner.getSnapshot === 'function' ? owner.getSnapshot() : undefined))
+						return snapshot === undefined ? undefined : kindOf(snapshot.activeTabId ?? snapshot.activeTab ?? snapshot.active)
+					}
+					const fromStrip = activePaneTabOf(window.document, paneRegistryOf(faces))
+					if (fromStrip !== undefined) return fromStrip
+					const fromController = read(faces.sidebarRight)
+					if (fromController !== undefined) return fromController
+					const fromRegistry = read(faces.sidebarRightTabs)
+					if (fromRegistry !== undefined) return fromRegistry
 					// DOM fallback, deliberately narrow: the active-pane marker is shared with the
 					// main dockkit, so it only counts when it really belongs to the right bar.
 					const active = window.document?.querySelector?.('[data-dockkit-pane-active]')
@@ -1236,15 +1903,83 @@ window.__ModuleLoader__.load({
 						: undefined
 					if (typeof labelled?.click === 'function') attempt(() => labelled.click())
 				},
-				openPane: kind => {
+				openPane: (kind, track, warn) => {
 					if (typeof kind !== 'string' || kind === '') return
-					const face = faces.sidebarRightTabs ?? faces.sidebarRight
-					if (face !== undefined && typeof face.openTab === 'function') {
-						attempt(() => face.openTab(kind))
+					// A pane link is a claim like any other, so it is checked before it is made: the
+					// registry names every kind the bar can show, and asking for one it does not know
+					// would leave the link sitting there doing nothing. (Measured live: guide,
+					// subagentchat, changes-review, plan, files, text, terminal.)
+					const known = attemptValue(() => paneRegistryOf(faces))?.map(row => row.kind)
+					if (Array.isArray(known) && !known.includes(kind)) {
+						warn(`${TAG} the right bar has no pane type "${kind}"; it knows: ${known.join(', ')}`)
 						return
 					}
-					attempt(() => faces.openRightbar?.())
+					// `openTab(kind, options)` belongs to the controller (`sidebarRight`); the registry
+					// only knows the kinds. Asking the registry to open one fails silently.
+					const controller = faces.sidebarRight
+					// Present the right column first: a session's store is adopted only once the bar is
+					// shown, and every open on an unadopted session is a silent no-op.
+					const expanded = attemptValue(() => (typeof controller?.isExpanded === 'function' ? controller.isExpanded() : undefined))
+					if (expanded === false) {
+						const wanted = typeof track === 'string' && track !== '' ? track : (attemptValue(() => faces.mainViewSessionId()) !== undefined ? 'session' : 'panel')
+						attempt(() => faces.openRightbar?.(wanted))
+					}
+					const session = rightBarSessionIdOf(window.document)
+					const expand = () => {
+						const expanded = attemptValue(() => (typeof controller?.isExpanded === 'function' ? controller.isExpanded() : true))
+						if (expanded === false) attempt(() => controller?.toggleExpanded?.())
+					}
+					if (controller !== undefined && controller !== null) {
+						// The controller a root plugin reaches is not "mounted" for a session, and `openTab(kind)`
+						// throws exactly then ("no session surface is mounted") — so the per-session path is the
+						// real one, and it takes the session **first**: `openTabIn(sessionId, kind, options)`.
+						// (Passed the other way round it looks up a session called "files" and does nothing.)
+						const opened = attemptValue(() => {
+							if (typeof controller.openTabIn === 'function' && typeof session === 'string' && session !== '') {
+								controller.openTabIn(session, kind, {})
+								return true
+							}
+							if (typeof controller.openTab === 'function') {
+								controller.openTab(kind, {})
+								return true
+							}
+							return false
+						})
+						if (opened === true) {
+							expand()
+							return
+						}
+
+					}
+					// Last resort: the same action the right bar's empty-state card runs. It is the
+					// bar's own "open this kind" entry, so using it is not a workaround.
+					const guides = attemptValue(() => {
+						const registry = faces.sidebarRightTabs
+						if (registry === undefined || registry === null) return undefined
+						const rows = typeof registry.guideEntries === 'function' ? registry.guideEntries() : registry.guideEntries
+						if (Array.isArray(rows)) return rows
+						const guide = typeof registry.guide === 'function' ? registry.guide() : registry.guide
+						return Array.isArray(guide) ? guide : undefined
+					})
+					if (!Array.isArray(guides)) return
+					for (const entry of guides) {
+						if (entry === null || typeof entry !== 'object') continue
+						const entryKind = entry.kind ?? entry.options?.kind ?? entry.id
+						if (typeof entryKind !== 'string' || entryKind !== kind) continue
+						const run = entry.onPick ?? entry.action ?? entry.select ?? entry.open ?? entry.run
+						if (typeof run === 'function') {
+							attempt(() => run())
+							expand()
+							return
+						}
+					}
 				},
+				// The kinds the bar can show: link targets are checked against this before claiming.
+				paneKinds: () => paneRegistryOf(faces)?.map(row => row.kind),
+				// The rows the registry publishes, for the report and for the drive's check.
+				paneRegistry: () => paneRegistryOf(faces),
+				// The conversation view ids the registry publishes, for the report.
+				conversationViewIds: () => conversationViewIdsOf(faces),
 				beginNavigation: () => {
 					if (faces.beginNavigation === undefined) return
 					attempt(() => faces.beginNavigation())
@@ -1311,6 +2046,7 @@ window.__ModuleLoader__.load({
 					}, () => {}),
 				warn: message => console.warn(message),
 			}
+			return host
 		}
 
 		/**
@@ -1330,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.