opencode-session-turns 0.0.0-stage → 0.1.0

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,85 @@
-# 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.
+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 the rail
+to reveal the turns; click one to jump straight to that message.
+
+> Works on OpenCode Desktop 2.2.6. The rail is a GUI plugin, loaded from the
+> prebuilt `./gui-experimental` bundle.
+
+```
+┌─ Session turns (12) ────────┐
+│ 09:14  #1  Fix this error…  │
+│ 09:22  #2  What about async?│
+│ 09:35  #3  Continue         │
+│ ...                         │
+└─────────────────────────────┘
+```
+
+## Features
+
+- Lists every user turn of the current session (paged from the session API).
+- Hover the right-edge rail to expand; move away to collapse.
+- Click a turn to jump to its message — including turns far back in history.
+- Highlights the turn currently in view.
+- `/turns` slash command and `⌘⌥R` (`Ctrl+Alt+R`) to reveal the rail.
+
+## Install
+
+Add the package name to the `plugins` list in your `opencode.json`; OpenCode
+installs it from npm on startup:
+
+```json
+{
+  "plugins": ["opencode-session-turns"]
+}
+```
+
+Restart OpenCode Desktop (the GUI bundle is loaded at window startup).
+
+## Usage
+
+- Move the mouse to the thin rail on the right edge of the conversation.
+- Or press `⌘⌥R` / run `/turns` to reveal it.
+- Click a turn to jump to that message.
+
+## How it works (and why it is not trivial)
+
+OpenCode Desktop 2.2.6 has some sharp edges that a GUI plugin has to respect:
+
+- The timeline is **virtualized**: only rows near the viewport are mounted, so
+  distant turns are not in the DOM.
+- The desktop app uses a **memory history** for routing. `window.location`
+  stays at `oc://renderer/index.html` and is decoupled from the real route.
+  Writing `#message-<id>` to `window.location` (or firing `popstate`) makes the
+  host parse `/index.html` as a route and throw a fatal `Unrecognised route!`.
+- The GUI SDK exposes **no** `scrollToMessage()` / `navigate()` API
+  (`ctx.router` is read-only).
+
+So this plugin:
+
+1. Picks the real route from `ctx.router.path()` (a valid
+   `/server/…/session/…` path).
+2. Fakes a click on an `<a href="<route>#message-<id>">`. The host's own
+   document-level link interceptor turns that into a **memory-router navigate**,
+   which drives the host's cursor machine to page in history and seek to the
+   row — without touching `window.location`.
+3. The host only pages in about **one history page (~5 turns) per seek**, so the
+   plugin keeps toggling the hash to an already-loaded turn and back to the
+   target, pulling one page at a time until the target row mounts.
+
+Rows that are already mounted are scrolled locally for an instant jump.
+
+## Build
+
+```sh
+npm install
+npm run build      # -> dist/gui-experimental.cjs
+```
+
+After changing the source, rebuild and reload the plugin in OpenCode Desktop
+(Settings → Extensions → Plugins → Reload) or restart the app.
+
+## License
+
+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.0",
+  "description": "OpenCode Desktop plugin: a right-edge rail listing every user turn of the current session; click a turn 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))
+      },
+    }))
+  },
+})