opencode-session-turns 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 meiyx7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# opencode-session-turns
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**OpenCode Desktop 插件：在会话右缘列出每一轮的「用户提问」，悬停展开，点击即刻跳转到那一条消息。**
+
+An OpenCode Desktop plugin that adds a slim rail on the right edge of the
+conversation, listing every user turn of the current session. Hover to expand;
+click a turn to jump straight to that message.
+
+适用 OpenCode Desktop 2.2.6（以预构建的 `./gui-experimental` 包形式加载）。
+
+```
+┌─ 会话轮次 (12) ─────────────┐
+│ 09:14  #1  帮我看看这个报错… │
+│ 09:22  #2  那改成异步呢？     │
+│ 09:35  #3  继续              │
+│ ...                         │
+└─────────────────────────────┘
+```
+
+## 功能
+
+- 列出当前会话的每一轮用户提问（从会话消息接口分页拉取，`type=user`）。
+- 鼠标移到窗口右缘的细条上自动展开，移开自动收起。
+- 点击任意一轮，**跳转到对应消息**——包括很久以前、尚未渲染的历史轮次。
+- 自动高亮当前视口所在的轮次。
+- 斜杠命令 `/turns`、快捷键 `⌘⌥R`（Windows/Linux 为 `Ctrl+Alt+R`）展开轮次条。
+
+## 安装
+
+把包名加入 `opencode.json` 的 `plugins` 列表，OpenCode 启动时会自动从 npm 安装：
+
+```json
+{
+  "plugins": ["opencode-session-turns"]
+}
+```
+
+然后重启 OpenCode Desktop（GUI bundle 在窗口启动时加载）。
+
+## 使用
+
+- 把鼠标移到会话右侧的细条上展开；
+- 或按 `⌘⌥R` / 输入 `/turns` 展开；
+- 点击某一轮即可跳到那条消息。
+
+## 实现原理（为什么并不简单）
+
+OpenCode Desktop 2.2.6 有几个必须绕开的陷阱：
+
+- 时间线是**虚拟渲染**的：只有视口附近的行动态挂载，远端轮次不在 DOM 里。
+- 桌面端使用**内存路由**：`window.location` 始终停在 `oc://renderer/index.html`，
+  与真实路由解耦。直接往 `window.location` 写 `#message-<id>` 或派发 `popstate`，
+  会让宿主把 `/index.html` 当成路由解析并抛出致命的 `Unrecognised route!`（会崩）。
+- GUI SDK **没有** `scrollToMessage()` / `navigate()` 这类公开 API（`ctx.router` 只读）。
+
+因此本插件的做法是：
+
+1. 用 `ctx.router.path()` 取到真实路由（合法的 `/server/…/session/…` 路径）；
+2. 伪造一个 `<a href="<路由>#message-<id>">` 并派发冒泡 click。宿主在 `document`
+   上注册的链接拦截器（Solid Router 的 `create` 钩子）会把它交给**内存 router 的
+   navigate()**，从而驱动宿主自己的游标状态机加载历史并定位到该行——全程不碰
+   `window.location`。
+3. 宿主每次 seek 只向前加载**约一页（~5 轮）**历史，所以插件会交替把 hash 指向
+   「已加载的最早一轮」和目标，逐页把历史翻出来，直到目标行挂载。
+
+已挂载的行则直接用本地滚动，瞬时定位。
+
+## 构建
+
+```sh
+npm install
+npm run build      # -> dist/gui-experimental.cjs
+```
+
+改完源码后重新构建，并在 OpenCode Desktop 里 Reload 插件
+（Settings → Extensions → Plugins → Reload）或重启应用。
+
+## 许可证
+
+MIT © meiyx7

package/dist/gui-experimental.cjs

@@ -0,0 +1,95 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const s=require("solid-js/web"),h=require("@opencode/plugin/gui"),a=require("solid-js");var Z=s.template("<div class=sr-status>"),tt=s.template("<div class=sr-rail>"),et=s.template("<div class=sr-note>"),nt=s.template("<button type=button class=sr-turn><span class=sr-text> </span><span class=sr-dash>");const C="v10",B="message-",_="session-turns:diag",A="session-turns:open";let F=0,j="",I="";const rt=n=>{const e=String(n?.text??"").split(`
+`).map(d=>d.trim()).find(d=>d.length>0);if(e)return e;const o=n?.files?.length??0;return o>0?`[附件 ×${o}]`:"(空消息)"},N=n=>String(n).padStart(2,"0"),st=n=>{const e=new Date(n??0);return`${N(e.getHours())}:${N(e.getMinutes())}`},z=n=>new Promise(e=>setTimeout(e,n)),x=()=>document.querySelector('[data-slot="session-timeline-scroll"] > .scroll-view__viewport')??document.querySelector('[data-slot="session-timeline-scroll"] [data-scrollable]')??(()=>{let e=document.querySelector("[data-message-id]")?.parentElement;for(;e;){const o=getComputedStyle(e);if(/(auto|scroll)/.test(o.overflowY)&&e.scrollHeight>e.clientHeight+1)return e;e=e.parentElement}})(),y=n=>document.getElementById(`${B}${n}`)??[...document.querySelectorAll("[data-message-id]")].find(e=>e.getAttribute("data-message-id")===n),T=n=>{const e=x(),o=[...document.querySelectorAll("[data-message-id]")],d=o[0]?.getAttribute("data-message-id")??"",$=I?` · 目标 ${y(I)?"在":"不在"} DOM`:"",v=d?` · 行ID ${d.slice(0,20)}`:"";let w="(空)";try{w=n.router.path()||"(空)"}catch{}return`轮次 ${F} · 容器 ${e?"OK":"缺失"} · DOM ${o.length} 行${$}${v} · 路由 ${w} · hash ${window.location.hash||"(空)"}${j?` · ${j}`:""}`},V=(n,e)=>{e.scrollIntoView({block:"start"});const o=n.querySelector("[data-session-title]"),d=o instanceof HTMLElement?o.offsetHeight:0;d&&(n.scrollTop-=d+12)},ot=n=>{let e="";try{e=n.router.path()||""}catch{}return e.startsWith("/")?e:""},at=n=>{const e=document.createElement("a");e.setAttribute("href",n),e.setAttribute("replace",""),e.setAttribute("noscroll",""),e.style.display="none",document.body.appendChild(e);try{e.dispatchEvent(new MouseEvent("click",{bubbles:!0,cancelable:!0,button:0,view:window}))}finally{e.remove()}},it=`
+.sr-rail {
+  position: fixed;
+  top: 50%;
+  transform: translateY(-50%);
+  right: 10px;
+  max-height: 60vh;
+  width: 14px;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  justify-content: center;
+  gap: 2px;
+  padding: 8px 4px;
+  overflow-y: auto;
+  overflow-x: hidden;
+  scrollbar-width: none;
+  z-index: 400;
+  border-radius: 10px;
+  color: var(--text-base, currentColor);
+  background: transparent;
+  transition: width .18s ease;
+}
+.sr-rail::-webkit-scrollbar { display: none; }
+.sr-rail[data-open="true"] { width: 360px; background: transparent; }
+.sr-turn {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  width: 100%;
+  min-height: 14px;
+  flex-shrink: 0;
+  cursor: pointer;
+  background: transparent;
+  border: 0;
+  padding: 0;
+  color: inherit;
+  font: inherit;
+  border-radius: 4px;
+}
+.sr-dash {
+  display: block;
+  width: 10px;
+  height: 2px;
+  border-radius: 1px;
+  background: currentColor;
+  opacity: .28;
+  flex-shrink: 0;
+  transition: opacity .12s ease, width .12s ease;
+}
+.sr-turn:hover .sr-dash,
+.sr-turn[data-active="true"] .sr-dash { opacity: .95; width: 18px; }
+.sr-text {
+  display: none;
+  margin-right: 10px;
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-size: 12px;
+  line-height: 1.5;
+  text-align: right;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 300px;
+  opacity: .45;
+  background: transparent;
+}
+.sr-rail[data-open="true"] .sr-text { display: block; }
+.sr-turn:hover .sr-text {
+  opacity: 1;
+  background: var(--surface-base-hover, rgba(127,127,127,.14));
+}
+.sr-turn[data-active="true"] .sr-text {
+  opacity: 1;
+  font-weight: 600;
+  background: var(--surface-base-hover, rgba(127,127,127,.14));
+}
+.sr-status {
+  position: fixed;
+  right: 30px;
+  bottom: 150px;
+  z-index: 401;
+  font-size: 11px;
+  padding: 3px 8px;
+  border-radius: 6px;
+  background: var(--background-strong, rgba(0,0,0,.75));
+  color: var(--text-base, #fff);
+  opacity: .9;
+  pointer-events: none;
+  white-space: pre-wrap;
+  max-width: min(720px, 90vw);
+}
+.sr-note { font-size: 11px; opacity: .4; padding: 2px; }
+`;function lt(n){const e=h.usePlugin(),[o,d]=a.createSignal([]),[$,v]=a.createSignal(""),[w,b]=a.createSignal(!1),[J,Y]=a.createSignal(""),[q,L]=a.createSignal("");let S=!1,M="",k,E="";const R=async t=>{if(!t||S)return;S=!0;const r=new Map;let l,i="";try{for(let u=0;u<40;u++){const g=l?{sessionID:t,type:"user",limit:200,cursor:l}:{sessionID:t,type:"user",limit:200,order:"desc"};let f;try{f=await e.client.message.list(g)}catch(p){i=String(p?.message??p);break}const U=f?.data??[];let D=0;for(const p of U)r.has(p.id)||(r.set(p.id,{id:p.id,created:p.time?.created??0,text:rt(p)}),D++);const H=f?.cursor?.next;if(!H||D===0)break;l=H}}finally{S=!1}const c=[...r.values()].sort((u,g)=>u.created-g.created);d(c),F=c.length,j=i,Y(c.length===0?i||"暂无用户消息":""),M=t},O=()=>n.session()?.id;a.createEffect(()=>{const t=O();t&&a.untrack(()=>{M!==t&&(d([]),v(""),E="",R(t))})});const G=setInterval(()=>{const t=O();t&&R(t)},5e3);a.onCleanup(()=>clearInterval(G));const K=setInterval(()=>{const t=x();if(!t)return;const r=[...t.querySelectorAll("[data-message-id]")];if(r.length===0)return;const l=t.getBoundingClientRect().top+40;for(const i of r)if(i.getBoundingClientRect().bottom>=l){const c=i.getAttribute("data-message-id");c&&v(c);break}},400);a.onCleanup(()=>clearInterval(K));const m=t=>{L(t),setTimeout(()=>L(r=>r===t?"":r),3e3)};a.onMount(()=>{const t=()=>m(`${C} · ${T(e)}`),r=()=>{b(!0),clearTimeout(k),k=setTimeout(()=>b(!1),4e3)};window.addEventListener(_,t),window.addEventListener(A,r),a.onCleanup(()=>{window.removeEventListener(_,t),window.removeEventListener(A,r),clearTimeout(k)}),m(`会话轮次 ${C} 已加载`)});const W=()=>{for(const t of o())if(y(t.id))return t},P=(t,r)=>{at(`${t}#${B}${r}`),E=r},X=async t=>{I=t.id;const r=x(),l=y(t.id);if(l&&r){V(r,l),m("已定位");return}const i=ot(e);if(!i){m(`无法读取当前路由，无法定位 · ${T(e)}`);return}for(let c=0;c<30;c++){if(m(c===0?"定位中…":`加载历史… ${c}`),E===t.id){const u=W()??o()[0];u&&(P(i,u.id),await z(120))}P(i,t.id);for(let u=0;u<6;u++){await z(80);const g=y(t.id);if(!g)continue;const f=x()??r;f&&V(f,g),m("已定位");return}}m(`未能定位 · ${T(e)}`)},Q=[s.createComponent(a.Show,{get when(){return q()},get children(){var t=Z();return s.insert(t,q),t}}),(()=>{var t=tt();return t.addEventListener("mouseleave",()=>b(!1)),t.addEventListener("mouseenter",()=>b(!0)),s.insert(t,s.createComponent(a.Show,{get when(){return o().length>0},get fallback(){return(()=>{var r=et();return s.insert(r,()=>J()||`… ${C}`),r})()},get children(){return s.createComponent(a.For,{get each(){return o()},children:r=>(()=>{var l=nt(),i=l.firstChild,c=i.firstChild;return l.$$click=()=>{X(r)},s.insert(i,()=>st(r.created),c),s.insert(i,()=>r.text,null),s.effect(()=>s.setAttribute(l,"data-active",$()===r.id?"true":"false")),l})()})}})),s.effect(()=>s.setAttribute(t,"data-open",w()?"true":"false")),t})()];return s.createComponent(s.Portal,{get mount(){return document.body},children:Q})}const ct=h.Plugin.define({i18n:{en:{"command.jump":"Session turns: show / jump","command.jump.description":"Reveal the turn rail; click a turn to jump to that message"}},setup(n){n.add(h.Style,it),n.add(h.Slot,{at:"window.bottom",render:()=>s.createComponent(a.Show,{get when(){return n.sessions.current()},get children(){return s.createComponent(lt,{session:()=>n.sessions.current()})}})}),n.add(h.Command,()=>({id:"jump",title:n.t("command.jump"),description:n.t("command.jump.description"),group:n.t("command.jump"),section:"navigation",bind:"mod+alt+r",slash:{name:"turns"},run:()=>{window.dispatchEvent(new Event(A)),window.dispatchEvent(new Event(_))}}))}});s.delegateEvents(["click"]);exports.default=ct;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "opencode-session-turns",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "OpenCode Desktop 插件：在会话右缘列出每一轮用户提问，点击即可跳转到对应消息。A right-edge rail of user turns; click one to jump to that message.",
+  "type": "module",
+  "license": "MIT",
+  "author": "meiyx7",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meiyx7/opencode-session-turns.git"
+  },
+  "homepage": "https://github.com/meiyx7/opencode-session-turns#readme",
+  "bugs": {
+    "url": "https://github.com/meiyx7/opencode-session-turns/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "session",
+    "turns",
+    "timeline",
+    "navigation",
+    "jump",
+    "message"
+  ],
+  "exports": {
+    "./gui-experimental": "./dist/gui-experimental.cjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.2.6",
+    "solid-js": "^1.9.0",
+    "vite": "^7.0.0",
+    "vite-plugin-solid": "^2.11.0"
+  }
+}

package/src/gui.tsx

@@ -0,0 +1,493 @@
+import { Command, Plugin, Slot, Style, usePlugin } from "@opencode/plugin/gui"
+import { For, Show, createEffect, createSignal, onCleanup, onMount, untrack } from "solid-js"
+import { Portal } from "solid-js/web"
+
+// ---------------------------------------------------------------------------
+// constants / helpers
+// ---------------------------------------------------------------------------
+
+const VERSION = "v10"
+const HASH_PREFIX = "message-"
+const DIAG_EVENT = "session-turns:diag"
+const OPEN_EVENT = "session-turns:open"
+
+// Filled by Rail.load()/jump() so the command palette can report diagnostics.
+let lastTurnCount = 0
+let lastNote = ""
+let lastJumpID = ""
+
+const firstLine = (message) => {
+  const line = String(message?.text ?? "")
+    .split("\n")
+    .map((item) => item.trim())
+    .find((item) => item.length > 0)
+  if (line) return line
+  const files = message?.files?.length ?? 0
+  if (files > 0) return `[附件 ×${files}]`
+  return "(空消息)"
+}
+
+const pad = (value) => String(value).padStart(2, "0")
+
+const formatTime = (created) => {
+  const date = new Date(created ?? 0)
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}`
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+// The app's own code reads this exact selector. The data-slot sits on the
+// outer .scroll-view (overflow: hidden); only .scroll-view__viewport scrolls.
+const findScroller = () =>
+  document.querySelector('[data-slot="session-timeline-scroll"] > .scroll-view__viewport') ??
+  document.querySelector('[data-slot="session-timeline-scroll"] [data-scrollable]') ??
+  (() => {
+    const row = document.querySelector("[data-message-id]")
+    let node = row?.parentElement
+    while (node) {
+      const style = getComputedStyle(node)
+      if (/(auto|scroll)/.test(style.overflowY) && node.scrollHeight > node.clientHeight + 1) return node
+      node = node.parentElement
+    }
+    return undefined
+  })()
+
+// The app sets id="message-<id>" on every timeline row. Prefer that over the
+// data attribute: Solid Router's own scrollToHash() uses getElementById too.
+const findRow = (messageID) =>
+  document.getElementById(`${HASH_PREFIX}${messageID}`) ??
+  [...document.querySelectorAll("[data-message-id]")].find(
+    (node) => node.getAttribute("data-message-id") === messageID,
+  )
+
+const diagnostics = (ctx) => {
+  const scroller = findScroller()
+  const nodes = [...document.querySelectorAll("[data-message-id]")]
+  const sample = nodes[0]?.getAttribute("data-message-id") ?? ""
+  const target = lastJumpID ? ` · 目标 ${findRow(lastJumpID) ? "在" : "不在"} DOM` : ""
+  const id = sample ? ` · 行ID ${sample.slice(0, 20)}` : ""
+  let route = "(空)"
+  try {
+    route = ctx.router.path() || "(空)"
+  } catch {}
+  return `轮次 ${lastTurnCount} · 容器 ${scroller ? "OK" : "缺失"} · DOM ${nodes.length} 行${target}${id} · 路由 ${route} · hash ${window.location.hash || "(空)"}${lastNote ? ` · ${lastNote}` : ""}`
+}
+
+const scrollToRow = (scroller, row) => {
+  // Native scrolling reaches the real scroll ancestor without depending on
+  // the viewport selector; then compensate for the sticky session title.
+  row.scrollIntoView({ block: "start" })
+  const title = scroller.querySelector("[data-session-title]")
+  const inset = title instanceof HTMLElement ? title.offsetHeight : 0
+  if (inset) scroller.scrollTop -= inset + 12
+}
+
+// The desktop app (2.2.6) routes through a memory history, so window.location is
+// stuck at the asset path `oc://renderer/index.html` and is decoupled from the
+// real route. Writing `#message-<id>` + firing popstate made the host parse
+// `/index.html` as a route and throw a fatal "Unrecognised route!".
+//
+// The one safe path into the host router is its document-level link interceptor
+// (Solid Router's `create` hook): a bubbling click on an <a> whose href is an
+// internal route makes it call the memory router's navigate(). We build an <a>
+// from the *real* route (ctx.router.path(), a valid /server/…/session/… path)
+// plus `#message-<id>` and click it. The route parses fine, the location hash
+// changes, and the host's own cursor machine pages in the history and seeks to
+// the row. window.location is never touched, so nothing crashes.
+const routePath = (ctx) => {
+  let path = ""
+  try {
+    path = ctx.router.path() || ""
+  } catch {}
+  return path.startsWith("/") ? path : ""
+}
+
+// Clicks an internal route link; the host's link interceptor turns it into
+// memory-router navigate(). `href` is a path, optionally with a #message-<id>.
+const clickRoute = (href) => {
+  const anchor = document.createElement("a")
+  anchor.setAttribute("href", href)
+  // Match the host's own hash jumps: replace instead of push, and skip the
+  // router's window.scrollTo(0,0) while the row is still unmounted.
+  anchor.setAttribute("replace", "")
+  anchor.setAttribute("noscroll", "")
+  anchor.style.display = "none"
+  document.body.appendChild(anchor)
+  try {
+    anchor.dispatchEvent(
+      new MouseEvent("click", { bubbles: true, cancelable: true, button: 0, view: window }),
+    )
+  } finally {
+    anchor.remove()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// styles
+// ---------------------------------------------------------------------------
+
+const CSS = `
+.sr-rail {
+  position: fixed;
+  top: 50%;
+  transform: translateY(-50%);
+  right: 10px;
+  max-height: 60vh;
+  width: 14px;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  justify-content: center;
+  gap: 2px;
+  padding: 8px 4px;
+  overflow-y: auto;
+  overflow-x: hidden;
+  scrollbar-width: none;
+  z-index: 400;
+  border-radius: 10px;
+  color: var(--text-base, currentColor);
+  background: transparent;
+  transition: width .18s ease;
+}
+.sr-rail::-webkit-scrollbar { display: none; }
+.sr-rail[data-open="true"] { width: 360px; background: transparent; }
+.sr-turn {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  width: 100%;
+  min-height: 14px;
+  flex-shrink: 0;
+  cursor: pointer;
+  background: transparent;
+  border: 0;
+  padding: 0;
+  color: inherit;
+  font: inherit;
+  border-radius: 4px;
+}
+.sr-dash {
+  display: block;
+  width: 10px;
+  height: 2px;
+  border-radius: 1px;
+  background: currentColor;
+  opacity: .28;
+  flex-shrink: 0;
+  transition: opacity .12s ease, width .12s ease;
+}
+.sr-turn:hover .sr-dash,
+.sr-turn[data-active="true"] .sr-dash { opacity: .95; width: 18px; }
+.sr-text {
+  display: none;
+  margin-right: 10px;
+  padding: 1px 6px;
+  border-radius: 4px;
+  font-size: 12px;
+  line-height: 1.5;
+  text-align: right;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 300px;
+  opacity: .45;
+  background: transparent;
+}
+.sr-rail[data-open="true"] .sr-text { display: block; }
+.sr-turn:hover .sr-text {
+  opacity: 1;
+  background: var(--surface-base-hover, rgba(127,127,127,.14));
+}
+.sr-turn[data-active="true"] .sr-text {
+  opacity: 1;
+  font-weight: 600;
+  background: var(--surface-base-hover, rgba(127,127,127,.14));
+}
+.sr-status {
+  position: fixed;
+  right: 30px;
+  bottom: 150px;
+  z-index: 401;
+  font-size: 11px;
+  padding: 3px 8px;
+  border-radius: 6px;
+  background: var(--background-strong, rgba(0,0,0,.75));
+  color: var(--text-base, #fff);
+  opacity: .9;
+  pointer-events: none;
+  white-space: pre-wrap;
+  max-width: min(720px, 90vw);
+}
+.sr-note { font-size: 11px; opacity: .4; padding: 2px; }
+`
+
+// ---------------------------------------------------------------------------
+// rail
+// ---------------------------------------------------------------------------
+
+function Rail(props) {
+  const ctx = usePlugin()
+  const [turns, setTurns] = createSignal([])
+  const [active, setActive] = createSignal("")
+  const [open, setOpen] = createSignal(false)
+  const [note, setNote] = createSignal("")
+  const [status, setStatus] = createSignal("")
+
+  let loading = false
+  let loadedFor = ""
+  let closeTimer
+  // The memory router's hash is invisible to us (window.location is stale), so
+  // track the last id we navigated to in order to force a hash change each round.
+  let lastNavID = ""
+
+  const load = async (sessionID) => {
+    if (!sessionID || loading) return
+    loading = true
+    const collected = new Map()
+    let cursor
+    let error = ""
+    try {
+      for (let page = 0; page < 40; page++) {
+        // The server rejects `cursor` together with `order`
+        // (InvalidCursorError: "Cursor cannot be combined with order").
+        // The cursor itself already encodes the original order/direction,
+        // so only the first page declares order: "desc".
+        const params = cursor
+          ? { sessionID, type: "user", limit: 200, cursor }
+          : { sessionID, type: "user", limit: 200, order: "desc" }
+
+        let response
+        try {
+          response = await ctx.client.message.list(params)
+        } catch (cause) {
+          error = String(cause?.message ?? cause)
+          break
+        }
+
+        const data = response?.data ?? []
+        let fresh = 0
+        for (const message of data) {
+          if (collected.has(message.id)) continue
+          collected.set(message.id, {
+            id: message.id,
+            created: message.time?.created ?? 0,
+            text: firstLine(message),
+          })
+          fresh++
+        }
+        const next = response?.cursor?.next
+        if (!next || fresh === 0) break
+        cursor = next
+      }
+    } finally {
+      loading = false
+    }
+
+    // Publish whatever was collected even if a later page failed — a paging
+    // error must never blank out the whole rail again.
+    const list = [...collected.values()].sort((a, b) => a.created - b.created)
+    setTurns(list)
+    lastTurnCount = list.length
+    lastNote = error
+    setNote(list.length === 0 ? error || "暂无用户消息" : "")
+    loadedFor = sessionID
+  }
+
+  const sessionID = () => props.session()?.id
+
+  createEffect(() => {
+    const id = sessionID()
+    if (!id) return
+    untrack(() => {
+      if (loadedFor !== id) {
+        setTurns([])
+        setActive("")
+        lastNavID = ""
+        void load(id)
+      }
+    })
+  })
+
+  const poll = setInterval(() => {
+    const id = sessionID()
+    if (id) void load(id)
+  }, 5000)
+  onCleanup(() => clearInterval(poll))
+
+  const trackActive = () => {
+    const scroller = findScroller()
+    if (!scroller) return
+    const rows = [...scroller.querySelectorAll("[data-message-id]")]
+    if (rows.length === 0) return
+    const top = scroller.getBoundingClientRect().top + 40
+    for (const row of rows) {
+      if (row.getBoundingClientRect().bottom >= top) {
+        const id = row.getAttribute("data-message-id")
+        if (id) setActive(id)
+        break
+      }
+    }
+  }
+  const track = setInterval(trackActive, 400)
+  onCleanup(() => clearInterval(track))
+
+  const flash = (text) => {
+    setStatus(text)
+    setTimeout(() => setStatus((current) => (current === text ? "" : current)), 3000)
+  }
+
+  onMount(() => {
+    const onDiag = () => flash(`${VERSION} · ${diagnostics(ctx)}`)
+    const onOpen = () => {
+      setOpen(true)
+      clearTimeout(closeTimer)
+      closeTimer = setTimeout(() => setOpen(false), 4000)
+    }
+    window.addEventListener(DIAG_EVENT, onDiag)
+    window.addEventListener(OPEN_EVENT, onOpen)
+    onCleanup(() => {
+      window.removeEventListener(DIAG_EVENT, onDiag)
+      window.removeEventListener(OPEN_EVENT, onOpen)
+      clearTimeout(closeTimer)
+    })
+    // One-shot confirmation that this window actually runs the rebuilt bundle.
+    flash(`会话轮次 ${VERSION} 已加载`)
+  })
+
+  // Oldest turn that is currently mounted (i.e. already paged in), used as a
+  // safe "different id" to toggle the router hash so it re-runs its seek.
+  const oldestLoadedTurn = () => {
+    for (const t of turns()) if (findRow(t.id)) return t
+    return undefined
+  }
+
+  const navTo = (path, id) => {
+    clickRoute(`${path}#${HASH_PREFIX}${id}`)
+    lastNavID = id
+  }
+
+  const jump = async (turn) => {
+    lastJumpID = turn.id
+    const scroller = findScroller()
+    const row = findRow(turn.id)
+
+    // Fast path: the row is mounted, scroll locally.
+    if (row && scroller) {
+      scrollToRow(scroller, row)
+      flash("已定位")
+      return
+    }
+
+    const path = routePath(ctx)
+    if (!path) {
+      flash(`无法读取当前路由，无法定位 · ${diagnostics(ctx)}`)
+      return
+    }
+
+    // The host only pages in ~one history page (~5 turns) per seek and then goes
+    // idle. Drive it: each round toggles the hash to an already-loaded turn and
+    // back to the target, so the cursor machine runs another seek/page.
+    for (let round = 0; round < 30; round++) {
+      flash(round === 0 ? "定位中…" : `加载历史… ${round}`)
+
+      if (lastNavID === turn.id) {
+        const other = oldestLoadedTurn() ?? turns()[0]
+        if (other) {
+          navTo(path, other.id)
+          await sleep(120)
+        }
+      }
+      navTo(path, turn.id)
+
+      for (let k = 0; k < 6; k++) {
+        await sleep(80)
+        const landed = findRow(turn.id)
+        if (!landed) continue
+        const live = findScroller() ?? scroller
+        if (live) scrollToRow(live, landed)
+        flash("已定位")
+        return
+      }
+    }
+
+    flash(`未能定位 · ${diagnostics(ctx)}`)
+  }
+
+  const rail = (
+    <>
+      <Show when={status()}>
+        <div class="sr-status">{status()}</div>
+      </Show>
+      <div
+        class="sr-rail"
+        data-open={open() ? "true" : "false"}
+        onMouseEnter={() => setOpen(true)}
+        onMouseLeave={() => setOpen(false)}
+      >
+        <Show when={turns().length > 0} fallback={<div class="sr-note">{note() || `… ${VERSION}`}</div>}>
+          <For each={turns()}>
+            {(turn) => (
+              <button
+                type="button"
+                class="sr-turn"
+                data-active={active() === turn.id ? "true" : "false"}
+                onClick={() => void jump(turn)}
+              >
+                <span class="sr-text">
+                  {formatTime(turn.created)} {turn.text}
+                </span>
+                <span class="sr-dash" />
+              </button>
+            )}
+          </For>
+        </Show>
+      </div>
+    </>
+  )
+
+  // Portal to <body>: window.bottom is a bottom strip with its own stacking
+  // context, which can clip or re-anchor position:fixed children.
+  return <Portal mount={document.body}>{rail}</Portal>
+}
+
+// ---------------------------------------------------------------------------
+// plugin
+// ---------------------------------------------------------------------------
+
+export default Plugin.define({
+  i18n: {
+    en: {
+      "command.jump": "Session turns: show / jump",
+      "command.jump.description": "Reveal the turn rail; click a turn to jump to that message",
+    },
+  },
+  setup(ctx) {
+    ctx.add(Style, CSS)
+
+    // NOTE: never clear an existing #message-<id> hash here. The desktop app
+    // uses it as a deep link and its cursor machine owns that state.
+
+    ctx.add(Slot, {
+      at: "window.bottom",
+      render: () => (
+        <Show when={ctx.sessions.current()}>
+          <Rail session={() => ctx.sessions.current()} />
+        </Show>
+      ),
+    })
+
+    ctx.add(Command, () => ({
+      id: "jump",
+      title: ctx.t("command.jump"),
+      description: ctx.t("command.jump.description"),
+      group: ctx.t("command.jump"),
+      section: "navigation",
+      bind: "mod+alt+r",
+      slash: { name: "turns" },
+      run: () => {
+        window.dispatchEvent(new Event(OPEN_EVENT))
+        window.dispatchEvent(new Event(DIAG_EVENT))
+      },
+    }))
+  },
+})