@luziyang2026/dsh-question-nav 0.1.0

package/src/client/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Browser-half entry for the dsh-client-ui-question-nav plugin.
+ *
+ * Registers one surface into the frame-wide floating layer (`shell.overlay`):
+ * a vertical strip on the right edge of the conversation column listing every
+ * user question in the current session as a small button. Clicking a button
+ * scrolls the chat to that question (paging older history when needed).
+ *
+ * Failure policy: nothing here throws at apply time — an external plugin must
+ * never take the GUI down.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+// Type-only: pulls ui-layout's SlotMap merge ('shell.overlay').
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+// Type-only: pulls the locale plugin's Context merge (ctx.locale).
+import type {} from '@deepseek-ai/dsh-client-locale/client'
+import { QuestionNavStrip, type QuestionNavInjected } from './QuestionNavStrip.tsx'
+import { en, zh, type QuestionNavKey } from './locales.ts'
+import { extractQuestions } from '../core/nodes.ts'
+import { jumpToQuestion, type JumpFailureCode, type JumpPorts } from '../core/jump.ts'
+
+/** Locale namespace this plugin owns. */
+const NS = 'question-nav'
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap {
+    /** question-nav surface copy. */
+    'question-nav': QuestionNavKey
+  }
+}
+
+/** Services required by this plugin. */
+export const inject = ['slots', 'locale', 'sessions']
+
+/** Single-instance guard: a duplicated client injection must not mount twice. */
+declare global {
+  // eslint-disable-next-line no-var
+  var __dshQuestionNavApplied: boolean | undefined
+}
+
+function claimApply(): boolean {
+  if (globalThis.__dshQuestionNavApplied === true) return false
+  globalThis.__dshQuestionNavApplied = true
+  return true
+}
+
+function releaseApply(): void {
+  globalThis.__dshQuestionNavApplied = undefined
+}
+
+/** Map the session snapshot to the jump-loop port surface. */
+function jumpPortsFor(ctx: ClientContext, sessionId: SessionId): JumpPorts {
+  return {
+    snapshot: () => {
+      const binding = ctx.sessions.binding(sessionId)
+      const snap = binding?.session.getSnapshot()
+      if (snap === undefined) return undefined
+      return {
+        openState: snap.openState,
+        hasMore: snap.hasMore,
+        loadingOlder: snap.loadingOlder,
+        rows: snap.chat.nodes.values(),
+      }
+    },
+    loadOlder: async () => {
+      const binding = ctx.sessions.binding(sessionId)
+      if (binding === undefined) throw new Error('session unavailable')
+      await binding.session.loadOlder()
+    },
+    isViewActive: () => document.querySelector('[data-chat-flow]') !== null,
+    findRow: (key: string) => {
+      for (const candidate of Array.from(document.querySelectorAll<HTMLElement>('[data-chat-anchor-key]'))) {
+        if (candidate.dataset.chatAnchorKey === key) return candidate
+      }
+      return null
+    },
+    scrollIntoView: (row) => row.scrollIntoView({ block: 'start' }),
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => window.setTimeout(resolve, ms)),
+  }
+}
+
+function createInject(ctx: ClientContext): QuestionNavInjected {
+  return {
+    readQuestions: (sessionId) => {
+      const snap = ctx.sessions.binding(sessionId)?.session.getSnapshot()
+      if (snap === undefined) return []
+      return extractQuestions(snap.chat.nodes.values())
+    },
+    subscribeList: (cb) => ctx.sessions.list.subscribe(cb),
+    subscribeContent: (sessionId, cb) => {
+      const binding = ctx.sessions.binding(sessionId)
+      if (binding === undefined) return () => {}
+      return binding.session.subscribe(cb)
+    },
+    jump: (sessionId, key) => {
+      const ports = jumpPortsFor(ctx, sessionId)
+      ports.report = (code: JumpFailureCode) => {
+        // Surface the failure through the component via a DOM event the
+        // strip listens for; simplest reliable cross-boundary channel here.
+        window.dispatchEvent(new CustomEvent('question-nav:jump-failed', { detail: code }))
+      }
+      void jumpToQuestion(ports, key)
+    },
+  }
+}
+
+/**
+ * Register the question-nav surface.
+ * @param ctx - client root context.
+ */
+export function apply(ctx: ClientContext): void {
+  if (!claimApply()) return
+  ctx.effect(() => releaseApply, 'question-nav: apply claim')
+
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'question-nav: dictionaries')
+
+  const injected = createInject(ctx)
+
+  ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+    name: 'shell.overlay',
+    id: 'question-nav',
+    order: 900,
+    locale: NS,
+    inject: () => injected,
+  }, QuestionNavStrip))
+}

package/src/client/locales.ts

@@ -0,0 +1,21 @@
+/**
+ * Locale dictionaries for the question-nav surface (zh/en). Registered under
+ * the `question-nav` namespace; keys are consumed through the bound translator.
+ */
+export const zh = {
+  'strip.empty': '本会话还没有提问',
+  'jump.inactive': '聊天视图未激活',
+  'jump.hidden': '目标无独立气泡，已定位到邻近内容',
+  'jump.notfound': '目标未加载或不存在（可能已压缩）',
+  'jump.timeout': '加载历史超时，可重试',
+} as const
+
+export const en = {
+  'strip.empty': 'No questions in this session yet',
+  'jump.inactive': 'Chat view is not active',
+  'jump.hidden': 'No dedicated bubble; landed on nearby content',
+  'jump.notfound': 'Target not loaded or missing (maybe compacted)',
+  'jump.timeout': 'Timed out loading history; retry',
+} as const
+
+export type QuestionNavKey = keyof typeof zh

package/src/client/question-nav.module.css

@@ -0,0 +1,105 @@
+.rail {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 1;
+  width: 44px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  box-sizing: border-box;
+  background: transparent;
+  /* Overlay: let pointer events pass through to the conversation beyond the
+     dots, so the embedded minimap never blocks the chat. */
+  pointer-events: none;
+}
+
+/* Vertically center the dot column when it is short; scroll from the top when
+   it is tall (auto margins collapse to 0 on overflow, so nothing clips). */
+.list {
+  flex: 1;
+  min-height: 0;
+  width: 100%;
+  overflow-y: auto;
+  overflow-x: hidden;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 0;
+  scrollbar-width: thin;
+}
+.list > *:first-child {
+  margin-top: auto;
+}
+.list > *:last-child {
+  margin-bottom: auto;
+}
+
+.dot {
+  flex: none;
+  pointer-events: auto;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  padding: 0;
+  border: none;
+  background: var(--dsw-alias-border-l3);
+  cursor: pointer;
+  transition: transform 120ms ease, background 120ms ease;
+}
+.dot:hover {
+  transform: scale(2);
+  background: var(--dsw-alias-brand-primary);
+}
+.dot.active {
+  transform: scale(1.6);
+  background: var(--dsw-alias-brand-primary);
+}
+
+/* Question count, rendered just above the first dot (sits in the list gap). */
+.count {
+  flex: none;
+  font-size: 10px;
+  line-height: 1;
+  font-weight: 600;
+  color: var(--dsw-alias-label-tertiary);
+  user-select: none;
+}
+
+/* The centered group: count + dot column, centered together (the list's auto
+   margins center it when short; it scrolls as a unit when tall). */
+.dots {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+
+.empty {
+  padding: 10px 4px;
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary);
+  text-align: center;
+  word-break: break-word;
+}
+
+/* Instant hover tooltip (rendered in a portal to document.body, so it is never
+   clipped by the rail's scroll container). */
+.tooltip {
+  position: fixed;
+  z-index: 20;
+  max-width: 420px;
+  background: var(--dsw-alias-bg-layer-1);
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 13px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-primary);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
+  white-space: normal;
+  word-break: break-word;
+  pointer-events: none;
+}

package/src/core/jump.ts

@@ -0,0 +1,153 @@
+/**
+ * Jump-to-question orchestration. Pure-ish: takes injected ports (snapshot
+ * read, loadOlder, DOM row lookup, view liveness, scroll, timers) so the
+ * paging/timeout/fallback loop is unit-testable without a real browser or
+ * session. The browser half wires these ports to ctx.sessions + the DOM.
+ */
+
+import { nearestRenderable } from './nodes.ts'
+
+/** The bits of a session snapshot the jump loop needs. */
+export interface JumpSnapshot {
+  openState: string
+  hasMore: boolean
+  loadingOlder: boolean
+  /** Renderable chat rows as a key->renderable map (or iterable of rows). */
+  rows: Iterable<{ key: string; anchorSeq: number; visibility?: string }>
+}
+
+export interface JumpPorts {
+  /** Read the current snapshot; undefined when the session/view is unavailable. */
+  snapshot: () => JumpSnapshot | undefined
+  /** Expand the window backwards; rejects/throws on failure. */
+  loadOlder: () => Promise<void>
+  /** True while the chat view is active (a `[data-chat-flow]` is mounted). */
+  isViewActive: () => boolean
+  /** Find the DOM row for a chat anchor key; null when not rendered. */
+  findRow: (key: string) => HTMLElement | null
+  /** Scroll a row into view at the top. */
+  scrollIntoView: (row: HTMLElement) => void
+  /** Monotonic ms clock. */
+  now: () => number
+  /** Async sleep. */
+  sleep: (ms: number) => Promise<void>
+  /** Report a terminal failure to the caller (for a hint). */
+  report?: (code: JumpFailureCode, fallback?: boolean) => void
+}
+
+export type JumpFailureCode = 'VIEW_INACTIVE' | 'TARGET_HIDDEN' | 'NOT_FOUND' | 'TIMEOUT'
+
+export interface JumpResult {
+  ok: boolean
+  code?: JumpFailureCode
+  /** True when we landed on a fallback row rather than the exact target. */
+  fallback?: boolean
+}
+
+export interface JumpOptions {
+  /** Total wall-clock budget for loadOlder paging. */
+  totalTimeoutMs?: number
+  /** Max loadOlder pages before giving up. */
+  maxPages?: number
+  /** Poll interval for the row to render after it is known to be in the window. */
+  rowWaitMs?: number
+  /** Poll interval for state transitions (loadingOlder / openState). */
+  pollMs?: number
+}
+
+const DEFAULTS = {
+  totalTimeoutMs: 15_000,
+  maxPages: 100,
+  rowWaitMs: 8_000,
+  pollMs: 60,
+}
+
+function minAnchorSeq(rows: Iterable<{ anchorSeq: number }>): number | null {
+  let min: number | null = null
+  for (const row of rows) {
+    if (min === null || row.anchorSeq < min) min = row.anchorSeq
+  }
+  return min
+}
+
+function renderable(rows: Iterable<{ key: string; anchorSeq: number; visibility?: string }>): { key: string; anchorSeq: number }[] {
+  const out: { key: string; anchorSeq: number }[] = []
+  for (const row of rows) {
+    if (row.visibility === 'hidden') continue
+    out.push({ key: row.key, anchorSeq: row.anchorSeq })
+  }
+  return out
+}
+
+/**
+ * Jump to the row for `key`, paging older content until it is rendered (or the
+ * budget is exhausted). Falls back to the nearest renderable row when the
+ * exact row is hidden/absent.
+ */
+export async function jumpToQuestion(ports: JumpPorts, key: string, options: JumpOptions = {}): Promise<JumpResult> {
+  const cfg = { ...DEFAULTS, ...options }
+  const fail = (code: JumpFailureCode, fallback = false): JumpResult => {
+    ports.report?.(code, fallback)
+    return fallback ? { ok: false, code, fallback: true } : { ok: false, code }
+  }
+
+  if (!ports.isViewActive()) return fail('VIEW_INACTIVE')
+
+  const deadline = ports.now() + cfg.totalTimeoutMs
+  let pages = 0
+
+  // Phase 1: page older until the key appears in the loaded window.
+  while (true) {
+    const snap = ports.snapshot()
+    if (snap === undefined) return fail('VIEW_INACTIVE')
+    const rows = renderable(snap.rows)
+    if (rows.some((r) => r.key === key)) break
+    if (snap.openState !== 'open') {
+      if (snap.openState === 'error' || ports.now() > deadline) {
+        return fail(snap.openState === 'error' ? 'VIEW_INACTIVE' : 'TIMEOUT')
+      }
+      await ports.sleep(cfg.pollMs)
+      continue
+    }
+    if (snap.hasMore !== true) return fail('NOT_FOUND')
+    if (pages >= cfg.maxPages || ports.now() > deadline) return fail('TIMEOUT')
+    if (snap.loadingOlder) {
+      await ports.sleep(cfg.pollMs)
+      continue
+    }
+    const before = minAnchorSeq(rows)
+    await ports.loadOlder()
+    pages += 1
+    const afterSnap = ports.snapshot()
+    const after = minAnchorSeq(afterSnap === undefined ? [] : afterSnap.rows)
+    if (after === null || (before !== null && after >= before)) return fail('NOT_FOUND')
+  }
+
+  // Phase 2: wait for the row to render, then scroll. Fall back if hidden.
+  const waitedFor = async (rowKey: string): Promise<HTMLElement | null> => {
+    for (let waited = 0; waited <= cfg.rowWaitMs; waited += cfg.pollMs) {
+      if (!ports.isViewActive()) return null
+      const row = ports.findRow(rowKey)
+      if (row !== null) return row
+      await ports.sleep(cfg.pollMs)
+    }
+    return null
+  }
+
+  const row = await waitedFor(key)
+  if (row !== null) {
+    ports.scrollIntoView(row)
+    return { ok: true }
+  }
+
+  const snap = ports.snapshot()
+  const fallback = nearestRenderable(snap === undefined ? [] : snap.rows, key)
+  if (fallback !== null) {
+    const fbRow = await waitedFor(fallback.key)
+    if (fbRow !== null) {
+      ports.scrollIntoView(fbRow)
+      return fail('TARGET_HIDDEN', true)
+    }
+  }
+  return fail('TARGET_HIDDEN', false)
+}

package/src/core/nodes.ts

@@ -0,0 +1,98 @@
+/**
+ * Pure node-indexing logic for the question-nav plugin. No React, no DOM, no
+ * Cordis — every function here is a pure transform over chat-node data so it
+ * can be unit-tested in isolation (and reused by the browser half).
+ */
+
+/** One user question as shown in the strip and targeted by a jump. */
+export interface QuestionNode {
+  /** Chat anchor key, matches a `[data-chat-anchor-key]` row in the scrollport. */
+  key: string
+  /** Monotone anchor sequence for ordering and window-min detection. */
+  anchorSeq: number
+  /** Event seq of the user message. */
+  seq: number
+  /** Unix ms timestamp. */
+  time: number
+  /** Full question text — shown in the hover tooltip (not truncated). */
+  text: string
+}
+
+/** Minimal shape a chat node must expose for indexing (structural, not SDK-bound). */
+export interface ChatNodeLike {
+  key: string
+  anchorSeq: number
+  visibility?: string
+  kind?: string
+  /** Kind-specific payload (a UserMessageNode for `user`/`steering`). */
+  data?: unknown
+}
+
+/** Kinds counted as a user question (turn-opening and steering admissions). */
+export const QUESTION_KINDS = ['user', 'steering'] as const
+
+/** Narrow `node.data` to the user-message payload we read. */
+interface UserDataLike {
+  content?: readonly { type?: string; text?: string }[]
+  seq?: number
+  time?: number
+}
+
+function userData(data: unknown): UserDataLike | undefined {
+  if (typeof data !== 'object' || data === null) return undefined
+  return data as UserDataLike
+}
+
+/** First text block of a user message; falls back to the raw first block. */
+export function messageText(content: readonly { type?: string; text?: string }[] | undefined): string {
+  if (content === undefined || content.length === 0) return ''
+  const first = content[0]
+  if (typeof first?.text === 'string') return first.text
+  return ''
+}
+
+/** Extract the user questions from a chat-node window, ordered by anchorSeq. */
+export function extractQuestions(nodes: Iterable<ChatNodeLike>): QuestionNode[] {
+  const out: QuestionNode[] = []
+  for (const node of nodes) {
+    if (!QUESTION_KINDS.includes(node.kind as (typeof QUESTION_KINDS)[number])) continue
+    const payload = userData(node.data)
+    out.push({
+      key: node.key,
+      anchorSeq: node.anchorSeq,
+      seq: payload?.seq ?? -1,
+      time: payload?.time ?? 0,
+      // Full question text: shown in the hover tooltip (not truncated).
+      text: messageText(payload?.content),
+    })
+  }
+  out.sort((a, b) => a.anchorSeq - b.anchorSeq)
+  return out
+}
+
+/** Whether a node is actually rendered (visible rows only are scroll targets). */
+export function isRenderable(node: ChatNodeLike): boolean {
+  return node.visibility !== 'hidden'
+}
+
+/** The row of the window that renders the given key (exact match). */
+export function findQuestionRow(nodes: Iterable<ChatNodeLike>, key: string): ChatNodeLike | null {
+  for (const node of nodes) {
+    if (node.key === key) return node
+  }
+  return null
+}
+
+/** Nearest renderable row for a key that is absent or hidden (compaction, windowing). */
+export function nearestRenderable(
+  nodes: Iterable<{ key: string; anchorSeq: number; visibility?: string }>,
+  excludeKey: string | undefined,
+): { key: string; anchorSeq: number } | null {
+  let best: { key: string; anchorSeq: number } | null = null
+  for (const node of nodes) {
+    if (node.visibility === 'hidden') continue
+    if (node.key === excludeKey) continue
+    if (best === null || node.anchorSeq < best.anchorSeq) best = { key: node.key, anchorSeq: node.anchorSeq }
+  }
+  return best
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Host loader entry for the dsh-client-ui-question-nav plugin — runs in the
+ * DSH host process. The plugin is browser-only: the row in cordis.patch.yml
+ * mounts this no-op half so the loader sees a real cordis plugin, while the
+ * actual UI lives in the browser half (src/client).
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Apply the host half (no host behavior for this plugin). */
+export function apply(_ctx: Context): void {}