@luziyang2026/dsh-question-nav 0.1.0

package/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":["useState","useRef","styles","createPortal"],"sources":["../src/client/QuestionNavStrip.tsx","../src/client/locales.ts","../src/core/nodes.ts","../src/core/jump.ts","../src/client/index.ts"],"sourcesContent":["/**\n * Question-nav minimap. Renders a vertical column of small round dots overlaid\n * on the LEFT edge of the conversation column (via the frame-wide\n * `shell.overlay` floating layer), vertically centered: one dot per user\n * question, enlarge on hover. The instant tooltip (a portal-rendered overlay,\n * no native-title delay) shows the question's full text; clicking a dot scrolls\n * the chat to that question.\n *\n * Data arrives through the four props shares: the framework `useSessions`\n * hook (current session), the registrant inject face (read/subscribe/jump),\n * and the bound locale translator.\n */\nimport { useEffect, useLayoutEffect, useRef, useState } from 'react'\nimport { createPortal } from 'react-dom'\nimport type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'\nimport type { SessionId } from '@deepseek-ai/dsh-client-connection/client'\n// Type-only: pulls the ui-layout SlotMap merge ('shell.overlay').\nimport type {} from '@deepseek-ai/dsh-client-ui-layout/client'\nimport type { QuestionNode } from '../core/nodes.ts'\nimport type { JumpFailureCode } from '../core/jump.ts'\nimport type { QuestionNavKey } from './locales.ts'\nimport styles from './question-nav.module.css'\n\n/** Values the registrant inject face supplies (wired in src/client/index.ts). */\nexport interface QuestionNavInjected {\n  /** Extract the user questions of a session (current loaded window). */\n  readQuestions: (sessionId: SessionId) => QuestionNode[]\n  /** Subscribe to the session list; returns an unsubscribe. */\n  subscribeList: (cb: () => void) => () => void\n  /** Subscribe to a session's content; returns an unsubscribe. */\n  subscribeContent: (sessionId: SessionId, cb: () => void) => () => void\n  /** Jump the chat to a question row. */\n  jump: (sessionId: SessionId, key: string) => void\n}\n\ntype ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>\n\nconst FAILURE_HINTS: Record<JumpFailureCode, QuestionNavKey> = {\n  VIEW_INACTIVE: 'jump.inactive',\n  TARGET_HIDDEN: 'jump.hidden',\n  NOT_FOUND: 'jump.notfound',\n  TIMEOUT: 'jump.timeout',\n}\n\n/** Live position of the instant hover tooltip. */\ninterface TooltipState {\n  text: string\n  left: number\n  top: number\n}\n\nfunction findConvRoot(): HTMLElement | null {\n  return document.querySelector<HTMLElement>('[data-slot=\"conversation\"] > div[data-phase]')\n}\n\nexport function QuestionNavStrip(props: ComponentProps): React.JSX.Element | null {\n  const current = props.useSessions((s) => s.current)\n  const summary = props.useSessions((s) => (s.current === undefined ? undefined : s.byId[s.current]))\n  const visible = current !== undefined && summary !== undefined && summary.blank !== true\n\n  const [questions, setQuestions] = useState<QuestionNode[]>([])\n  const [jumpingKey, setJumpingKey] = useState<string | null>(null)\n  const [hint, setHint] = useState<string | null>(null)\n  const [tooltip, setTooltip] = useState<TooltipState | null>(null)\n  const panelRef = useRef<HTMLDivElement | null>(null)\n  const hintTimerRef = useRef<number | null>(null)\n\n  const showHint = (message: string): void => {\n    setHint(message)\n    if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)\n    hintTimerRef.current = window.setTimeout(() => setHint(null), 1800)\n  }\n\n  // Refresh the question list whenever the current session or its content changes.\n  useEffect(() => {\n    if (!visible || current === undefined) {\n      setQuestions([])\n      return\n    }\n    const refresh = (): void => setQuestions(props.readQuestions(current))\n    refresh()\n    const unsubContent = props.subscribeContent(current, refresh)\n    const unsubList = props.subscribeList(refresh)\n    return () => {\n      unsubContent()\n      unsubList()\n    }\n  }, [visible, current, props])\n\n  // Listen for jump-failure events and surface the hint.\n  useEffect(() => {\n    const onJumpFailed = (event: Event): void => {\n      const code = (event as CustomEvent<JumpFailureCode>).detail\n      showHint(props.t(FAILURE_HINTS[code] ?? 'jump.timeout'))\n    }\n    window.addEventListener('question-nav:jump-failed', onJumpFailed)\n    return () => window.removeEventListener('question-nav:jump-failed', onJumpFailed)\n  }, [props])\n\n  // Anchor the minimap to the conversation column: position it at the left\n  // edge of the conversation root and reserve a thin rail with padding-left.\n  useLayoutEffect(() => {\n    if (!visible) return\n    let raf = 0\n    let retries = 0\n    const applyLayout = (): void => {\n      const panel = panelRef.current\n      if (panel === null) return\n      const frame = panel.closest('[data-shell-overlay]')?.parentElement ?? null\n      const convRoot = findConvRoot()\n      if (frame === null || convRoot === null) return\n      const frameRect = frame.getBoundingClientRect()\n      const convRect = convRoot.getBoundingClientRect()\n      if (convRect.height <= 0) {\n        if (retries < 20) {\n          retries += 1\n          raf = requestAnimationFrame(applyLayout)\n        }\n        return\n      }\n      retries = 0\n      panel.style.top = `${convRect.top - frameRect.top}px`\n      panel.style.height = `${convRect.height}px`\n      panel.style.left = `${convRect.left - frameRect.left}px`\n    }\n    applyLayout()\n    raf = requestAnimationFrame(applyLayout)\n    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(applyLayout)\n    const convRoot = findConvRoot()\n    observer?.observe(convRoot ?? document.body, { box: 'border-box' })\n    window.addEventListener('resize', applyLayout)\n    return () => {\n      if (raf !== 0) cancelAnimationFrame(raf)\n      observer?.disconnect()\n      window.removeEventListener('resize', applyLayout)\n    }\n  }, [visible])\n\n  // Clear any pending hint timer on unmount.\n  useEffect(() => () => {\n    if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)\n  }, [])\n\n  if (!visible) return null\n\n  const onJump = (node: QuestionNode): void => {\n    if (current === undefined) return\n    setJumpingKey(node.key)\n    props.jump(current, node.key)\n    window.setTimeout(() => setJumpingKey((k) => (k === node.key ? null : k)), 600)\n  }\n\n  const t = props.t\n\n  return (\n    <div ref={panelRef} className={styles.rail} data-question-nav=\"rail\">\n      {hint !== null ? <div className={styles.hint} role=\"status\">{hint}</div> : null}\n      <div className={styles.list}>\n        {questions.length === 0 ? (\n          <div className={styles.empty}>{t('strip.empty')}</div>\n        ) : (\n          <div className={styles.dots}>\n            <span className={styles.count}>{questions.length}</span>\n            {questions.map((node) => (\n              <button\n                key={node.key}\n                className={jumpingKey === node.key ? `${styles.dot} ${styles.active}` : styles.dot}\n                aria-label={node.text}\n                onMouseEnter={(e) => {\n                  const r = e.currentTarget.getBoundingClientRect()\n                  setTooltip({ text: node.text, left: r.right + 10, top: r.top })\n                }}\n                onMouseLeave={() => setTooltip(null)}\n                onClick={() => onJump(node)}\n              />\n            ))}\n          </div>\n        )}\n      </div>\n      {tooltip !== null\n        ? createPortal(\n            <div className={styles.tooltip} style={{ left: tooltip.left, top: tooltip.top }}>\n              {tooltip.text}\n            </div>,\n            document.body,\n          )\n        : null}\n    </div>\n  )\n}\n","/**\n * Locale dictionaries for the question-nav surface (zh/en). Registered under\n * the `question-nav` namespace; keys are consumed through the bound translator.\n */\nexport const zh = {\n  'strip.empty': '本会话还没有提问',\n  'jump.inactive': '聊天视图未激活',\n  'jump.hidden': '目标无独立气泡，已定位到邻近内容',\n  'jump.notfound': '目标未加载或不存在（可能已压缩）',\n  'jump.timeout': '加载历史超时，可重试',\n} as const\n\nexport const en = {\n  'strip.empty': 'No questions in this session yet',\n  'jump.inactive': 'Chat view is not active',\n  'jump.hidden': 'No dedicated bubble; landed on nearby content',\n  'jump.notfound': 'Target not loaded or missing (maybe compacted)',\n  'jump.timeout': 'Timed out loading history; retry',\n} as const\n\nexport type QuestionNavKey = keyof typeof zh\n","/**\n * Pure node-indexing logic for the question-nav plugin. No React, no DOM, no\n * Cordis — every function here is a pure transform over chat-node data so it\n * can be unit-tested in isolation (and reused by the browser half).\n */\n\n/** One user question as shown in the strip and targeted by a jump. */\nexport interface QuestionNode {\n  /** Chat anchor key, matches a `[data-chat-anchor-key]` row in the scrollport. */\n  key: string\n  /** Monotone anchor sequence for ordering and window-min detection. */\n  anchorSeq: number\n  /** Event seq of the user message. */\n  seq: number\n  /** Unix ms timestamp. */\n  time: number\n  /** Full question text — shown in the hover tooltip (not truncated). */\n  text: string\n}\n\n/** Minimal shape a chat node must expose for indexing (structural, not SDK-bound). */\nexport interface ChatNodeLike {\n  key: string\n  anchorSeq: number\n  visibility?: string\n  kind?: string\n  /** Kind-specific payload (a UserMessageNode for `user`/`steering`). */\n  data?: unknown\n}\n\n/** Kinds counted as a user question (turn-opening and steering admissions). */\nexport const QUESTION_KINDS = ['user', 'steering'] as const\n\n/** Narrow `node.data` to the user-message payload we read. */\ninterface UserDataLike {\n  content?: readonly { type?: string; text?: string }[]\n  seq?: number\n  time?: number\n}\n\nfunction userData(data: unknown): UserDataLike | undefined {\n  if (typeof data !== 'object' || data === null) return undefined\n  return data as UserDataLike\n}\n\n/** First text block of a user message; falls back to the raw first block. */\nexport function messageText(content: readonly { type?: string; text?: string }[] | undefined): string {\n  if (content === undefined || content.length === 0) return ''\n  const first = content[0]\n  if (typeof first?.text === 'string') return first.text\n  return ''\n}\n\n/** Extract the user questions from a chat-node window, ordered by anchorSeq. */\nexport function extractQuestions(nodes: Iterable<ChatNodeLike>): QuestionNode[] {\n  const out: QuestionNode[] = []\n  for (const node of nodes) {\n    if (!QUESTION_KINDS.includes(node.kind as (typeof QUESTION_KINDS)[number])) continue\n    const payload = userData(node.data)\n    out.push({\n      key: node.key,\n      anchorSeq: node.anchorSeq,\n      seq: payload?.seq ?? -1,\n      time: payload?.time ?? 0,\n      // Full question text: shown in the hover tooltip (not truncated).\n      text: messageText(payload?.content),\n    })\n  }\n  out.sort((a, b) => a.anchorSeq - b.anchorSeq)\n  return out\n}\n\n/** Whether a node is actually rendered (visible rows only are scroll targets). */\nexport function isRenderable(node: ChatNodeLike): boolean {\n  return node.visibility !== 'hidden'\n}\n\n/** The row of the window that renders the given key (exact match). */\nexport function findQuestionRow(nodes: Iterable<ChatNodeLike>, key: string): ChatNodeLike | null {\n  for (const node of nodes) {\n    if (node.key === key) return node\n  }\n  return null\n}\n\n/** Nearest renderable row for a key that is absent or hidden (compaction, windowing). */\nexport function nearestRenderable(\n  nodes: Iterable<{ key: string; anchorSeq: number; visibility?: string }>,\n  excludeKey: string | undefined,\n): { key: string; anchorSeq: number } | null {\n  let best: { key: string; anchorSeq: number } | null = null\n  for (const node of nodes) {\n    if (node.visibility === 'hidden') continue\n    if (node.key === excludeKey) continue\n    if (best === null || node.anchorSeq < best.anchorSeq) best = { key: node.key, anchorSeq: node.anchorSeq }\n  }\n  return best\n}\n","/**\n * Jump-to-question orchestration. Pure-ish: takes injected ports (snapshot\n * read, loadOlder, DOM row lookup, view liveness, scroll, timers) so the\n * paging/timeout/fallback loop is unit-testable without a real browser or\n * session. The browser half wires these ports to ctx.sessions + the DOM.\n */\n\nimport { nearestRenderable } from './nodes.ts'\n\n/** The bits of a session snapshot the jump loop needs. */\nexport interface JumpSnapshot {\n  openState: string\n  hasMore: boolean\n  loadingOlder: boolean\n  /** Renderable chat rows as a key->renderable map (or iterable of rows). */\n  rows: Iterable<{ key: string; anchorSeq: number; visibility?: string }>\n}\n\nexport interface JumpPorts {\n  /** Read the current snapshot; undefined when the session/view is unavailable. */\n  snapshot: () => JumpSnapshot | undefined\n  /** Expand the window backwards; rejects/throws on failure. */\n  loadOlder: () => Promise<void>\n  /** True while the chat view is active (a `[data-chat-flow]` is mounted). */\n  isViewActive: () => boolean\n  /** Find the DOM row for a chat anchor key; null when not rendered. */\n  findRow: (key: string) => HTMLElement | null\n  /** Scroll a row into view at the top. */\n  scrollIntoView: (row: HTMLElement) => void\n  /** Monotonic ms clock. */\n  now: () => number\n  /** Async sleep. */\n  sleep: (ms: number) => Promise<void>\n  /** Report a terminal failure to the caller (for a hint). */\n  report?: (code: JumpFailureCode, fallback?: boolean) => void\n}\n\nexport type JumpFailureCode = 'VIEW_INACTIVE' | 'TARGET_HIDDEN' | 'NOT_FOUND' | 'TIMEOUT'\n\nexport interface JumpResult {\n  ok: boolean\n  code?: JumpFailureCode\n  /** True when we landed on a fallback row rather than the exact target. */\n  fallback?: boolean\n}\n\nexport interface JumpOptions {\n  /** Total wall-clock budget for loadOlder paging. */\n  totalTimeoutMs?: number\n  /** Max loadOlder pages before giving up. */\n  maxPages?: number\n  /** Poll interval for the row to render after it is known to be in the window. */\n  rowWaitMs?: number\n  /** Poll interval for state transitions (loadingOlder / openState). */\n  pollMs?: number\n}\n\nconst DEFAULTS = {\n  totalTimeoutMs: 15_000,\n  maxPages: 100,\n  rowWaitMs: 8_000,\n  pollMs: 60,\n}\n\nfunction minAnchorSeq(rows: Iterable<{ anchorSeq: number }>): number | null {\n  let min: number | null = null\n  for (const row of rows) {\n    if (min === null || row.anchorSeq < min) min = row.anchorSeq\n  }\n  return min\n}\n\nfunction renderable(rows: Iterable<{ key: string; anchorSeq: number; visibility?: string }>): { key: string; anchorSeq: number }[] {\n  const out: { key: string; anchorSeq: number }[] = []\n  for (const row of rows) {\n    if (row.visibility === 'hidden') continue\n    out.push({ key: row.key, anchorSeq: row.anchorSeq })\n  }\n  return out\n}\n\n/**\n * Jump to the row for `key`, paging older content until it is rendered (or the\n * budget is exhausted). Falls back to the nearest renderable row when the\n * exact row is hidden/absent.\n */\nexport async function jumpToQuestion(ports: JumpPorts, key: string, options: JumpOptions = {}): Promise<JumpResult> {\n  const cfg = { ...DEFAULTS, ...options }\n  const fail = (code: JumpFailureCode, fallback = false): JumpResult => {\n    ports.report?.(code, fallback)\n    return fallback ? { ok: false, code, fallback: true } : { ok: false, code }\n  }\n\n  if (!ports.isViewActive()) return fail('VIEW_INACTIVE')\n\n  const deadline = ports.now() + cfg.totalTimeoutMs\n  let pages = 0\n\n  // Phase 1: page older until the key appears in the loaded window.\n  while (true) {\n    const snap = ports.snapshot()\n    if (snap === undefined) return fail('VIEW_INACTIVE')\n    const rows = renderable(snap.rows)\n    if (rows.some((r) => r.key === key)) break\n    if (snap.openState !== 'open') {\n      if (snap.openState === 'error' || ports.now() > deadline) {\n        return fail(snap.openState === 'error' ? 'VIEW_INACTIVE' : 'TIMEOUT')\n      }\n      await ports.sleep(cfg.pollMs)\n      continue\n    }\n    if (snap.hasMore !== true) return fail('NOT_FOUND')\n    if (pages >= cfg.maxPages || ports.now() > deadline) return fail('TIMEOUT')\n    if (snap.loadingOlder) {\n      await ports.sleep(cfg.pollMs)\n      continue\n    }\n    const before = minAnchorSeq(rows)\n    await ports.loadOlder()\n    pages += 1\n    const afterSnap = ports.snapshot()\n    const after = minAnchorSeq(afterSnap === undefined ? [] : afterSnap.rows)\n    if (after === null || (before !== null && after >= before)) return fail('NOT_FOUND')\n  }\n\n  // Phase 2: wait for the row to render, then scroll. Fall back if hidden.\n  const waitedFor = async (rowKey: string): Promise<HTMLElement | null> => {\n    for (let waited = 0; waited <= cfg.rowWaitMs; waited += cfg.pollMs) {\n      if (!ports.isViewActive()) return null\n      const row = ports.findRow(rowKey)\n      if (row !== null) return row\n      await ports.sleep(cfg.pollMs)\n    }\n    return null\n  }\n\n  const row = await waitedFor(key)\n  if (row !== null) {\n    ports.scrollIntoView(row)\n    return { ok: true }\n  }\n\n  const snap = ports.snapshot()\n  const fallback = nearestRenderable(snap === undefined ? [] : snap.rows, key)\n  if (fallback !== null) {\n    const fbRow = await waitedFor(fallback.key)\n    if (fbRow !== null) {\n      ports.scrollIntoView(fbRow)\n      return fail('TARGET_HIDDEN', true)\n    }\n  }\n  return fail('TARGET_HIDDEN', false)\n}\n","/**\n * Browser-half entry for the dsh-client-ui-question-nav plugin.\n *\n * Registers one surface into the frame-wide floating layer (`shell.overlay`):\n * a vertical strip on the right edge of the conversation column listing every\n * user question in the current session as a small button. Clicking a button\n * scrolls the chat to that question (paging older history when needed).\n *\n * Failure policy: nothing here throws at apply time — an external plugin must\n * never take the GUI down.\n */\nimport type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'\nimport type { SessionId } from '@deepseek-ai/dsh-client-connection/client'\n// Type-only: pulls ui-layout's SlotMap merge ('shell.overlay').\nimport type {} from '@deepseek-ai/dsh-client-ui-layout/client'\n// Type-only: pulls the locale plugin's Context merge (ctx.locale).\nimport type {} from '@deepseek-ai/dsh-client-locale/client'\nimport { QuestionNavStrip, type QuestionNavInjected } from './QuestionNavStrip.tsx'\nimport { en, zh, type QuestionNavKey } from './locales.ts'\nimport { extractQuestions } from '../core/nodes.ts'\nimport { jumpToQuestion, type JumpFailureCode, type JumpPorts } from '../core/jump.ts'\n\n/** Locale namespace this plugin owns. */\nconst NS = 'question-nav'\n\ndeclare module '@deepseek-ai/dsh-client-ui-slots' {\n  interface LocaleNamespaceMap {\n    /** question-nav surface copy. */\n    'question-nav': QuestionNavKey\n  }\n}\n\n/** Services required by this plugin. */\nexport const inject = ['slots', 'locale', 'sessions']\n\n/** Single-instance guard: a duplicated client injection must not mount twice. */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __dshQuestionNavApplied: boolean | undefined\n}\n\nfunction claimApply(): boolean {\n  if (globalThis.__dshQuestionNavApplied === true) return false\n  globalThis.__dshQuestionNavApplied = true\n  return true\n}\n\nfunction releaseApply(): void {\n  globalThis.__dshQuestionNavApplied = undefined\n}\n\n/** Map the session snapshot to the jump-loop port surface. */\nfunction jumpPortsFor(ctx: ClientContext, sessionId: SessionId): JumpPorts {\n  return {\n    snapshot: () => {\n      const binding = ctx.sessions.binding(sessionId)\n      const snap = binding?.session.getSnapshot()\n      if (snap === undefined) return undefined\n      return {\n        openState: snap.openState,\n        hasMore: snap.hasMore,\n        loadingOlder: snap.loadingOlder,\n        rows: snap.chat.nodes.values(),\n      }\n    },\n    loadOlder: async () => {\n      const binding = ctx.sessions.binding(sessionId)\n      if (binding === undefined) throw new Error('session unavailable')\n      await binding.session.loadOlder()\n    },\n    isViewActive: () => document.querySelector('[data-chat-flow]') !== null,\n    findRow: (key: string) => {\n      for (const candidate of Array.from(document.querySelectorAll<HTMLElement>('[data-chat-anchor-key]'))) {\n        if (candidate.dataset.chatAnchorKey === key) return candidate\n      }\n      return null\n    },\n    scrollIntoView: (row) => row.scrollIntoView({ block: 'start' }),\n    now: () => Date.now(),\n    sleep: (ms) => new Promise((resolve) => window.setTimeout(resolve, ms)),\n  }\n}\n\nfunction createInject(ctx: ClientContext): QuestionNavInjected {\n  return {\n    readQuestions: (sessionId) => {\n      const snap = ctx.sessions.binding(sessionId)?.session.getSnapshot()\n      if (snap === undefined) return []\n      return extractQuestions(snap.chat.nodes.values())\n    },\n    subscribeList: (cb) => ctx.sessions.list.subscribe(cb),\n    subscribeContent: (sessionId, cb) => {\n      const binding = ctx.sessions.binding(sessionId)\n      if (binding === undefined) return () => {}\n      return binding.session.subscribe(cb)\n    },\n    jump: (sessionId, key) => {\n      const ports = jumpPortsFor(ctx, sessionId)\n      ports.report = (code: JumpFailureCode) => {\n        // Surface the failure through the component via a DOM event the\n        // strip listens for; simplest reliable cross-boundary channel here.\n        window.dispatchEvent(new CustomEvent('question-nav:jump-failed', { detail: code }))\n      }\n      void jumpToQuestion(ports, key)\n    },\n  }\n}\n\n/**\n * Register the question-nav surface.\n * @param ctx - client root context.\n */\nexport function apply(ctx: ClientContext): void {\n  if (!claimApply()) return\n  ctx.effect(() => releaseApply, 'question-nav: apply claim')\n\n  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'question-nav: dictionaries')\n\n  const injected = createInject(ctx)\n\n  ctx.slots.inject('shell.overlay', () => ctx.slots.register({\n    name: 'shell.overlay',\n    id: 'question-nav',\n    order: 900,\n    locale: NS,\n    inject: () => injected,\n  }, QuestionNavStrip))\n}\n"],"mappings":"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"}

package/lib/index.js

@@ -0,0 +1,5 @@
+//#region src/index.ts
+/** Apply the host half (no host behavior for this plugin). */
+function apply(_ctx) {}
+//#endregion
+export { apply };

package/lib/types/client/QuestionNavStrip.d.ts

@@ -0,0 +1,17 @@
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import type { QuestionNode } from '../core/nodes.ts';
+/** Values the registrant inject face supplies (wired in src/client/index.ts). */
+export interface QuestionNavInjected {
+    /** Extract the user questions of a session (current loaded window). */
+    readQuestions: (sessionId: SessionId) => QuestionNode[];
+    /** Subscribe to the session list; returns an unsubscribe. */
+    subscribeList: (cb: () => void) => () => void;
+    /** Subscribe to a session's content; returns an unsubscribe. */
+    subscribeContent: (sessionId: SessionId, cb: () => void) => () => void;
+    /** Jump the chat to a question row. */
+    jump: (sessionId: SessionId, key: string) => void;
+}
+type ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>;
+export declare function QuestionNavStrip(props: ComponentProps): React.JSX.Element | null;
+export {};

package/lib/types/client/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 QuestionNavKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** question-nav surface copy. */
+        'question-nav': QuestionNavKey;
+    }
+}
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Single-instance guard: a duplicated client injection must not mount twice. */
+declare global {
+    var __dshQuestionNavApplied: boolean | undefined;
+}
+/**
+ * Register the question-nav surface.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

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

package/lib/types/core/jump.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+/** 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;
+}
+/**
+ * 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 declare function jumpToQuestion(ports: JumpPorts, key: string, options?: JumpOptions): Promise<JumpResult>;

package/lib/types/core/nodes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare const QUESTION_KINDS: readonly ["user", "steering"];
+/** First text block of a user message; falls back to the raw first block. */
+export declare function messageText(content: readonly {
+    type?: string;
+    text?: string;
+}[] | undefined): string;
+/** Extract the user questions from a chat-node window, ordered by anchorSeq. */
+export declare function extractQuestions(nodes: Iterable<ChatNodeLike>): QuestionNode[];
+/** Whether a node is actually rendered (visible rows only are scroll targets). */
+export declare function isRenderable(node: ChatNodeLike): boolean;
+/** The row of the window that renders the given key (exact match). */
+export declare function findQuestionRow(nodes: Iterable<ChatNodeLike>, key: string): ChatNodeLike | null;
+/** Nearest renderable row for a key that is absent or hidden (compaction, windowing). */
+export declare function nearestRenderable(nodes: Iterable<{
+    key: string;
+    anchorSeq: number;
+    visibility?: string;
+}>, excludeKey: string | undefined): {
+    key: string;
+    anchorSeq: number;
+} | null;

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function apply(_ctx: Context): void;

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@luziyang2026/dsh-question-nav",
+  "description": "In-session question navigator for the DSH web GUI: a vertical minimap of round dots overlaid on the left edge of the conversation column, one dot per user question — hover enlarges and shows the full question text, click jumps to that message.",
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "pnpm@11.7.0",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsdown",
+    "prepare": "tsdown",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22.20.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "jsdom": "29.1.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vite-tsconfig-paths": "^6.1.1",
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "LICENSE",
+    "README.md",
+    "README.zh.md",
+    "README.i18n.yaml"
+  ],
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AbelKeithsun/dsh-question-nav.git"
+  }
+}

package/src/client/QuestionNavStrip.tsx

@@ -0,0 +1,190 @@
+/**
+ * Question-nav minimap. Renders a vertical column of small round dots overlaid
+ * on the LEFT edge of the conversation column (via the frame-wide
+ * `shell.overlay` floating layer), vertically centered: one dot per user
+ * question, enlarge on hover. The instant tooltip (a portal-rendered overlay,
+ * no native-title delay) shows the question's full text; clicking a dot scrolls
+ * the chat to that question.
+ *
+ * Data arrives through the four props shares: the framework `useSessions`
+ * hook (current session), the registrant inject face (read/subscribe/jump),
+ * and the bound locale translator.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
+// Type-only: pulls the ui-layout SlotMap merge ('shell.overlay').
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type { QuestionNode } from '../core/nodes.ts'
+import type { JumpFailureCode } from '../core/jump.ts'
+import type { QuestionNavKey } from './locales.ts'
+import styles from './question-nav.module.css'
+
+/** Values the registrant inject face supplies (wired in src/client/index.ts). */
+export interface QuestionNavInjected {
+  /** Extract the user questions of a session (current loaded window). */
+  readQuestions: (sessionId: SessionId) => QuestionNode[]
+  /** Subscribe to the session list; returns an unsubscribe. */
+  subscribeList: (cb: () => void) => () => void
+  /** Subscribe to a session's content; returns an unsubscribe. */
+  subscribeContent: (sessionId: SessionId, cb: () => void) => () => void
+  /** Jump the chat to a question row. */
+  jump: (sessionId: SessionId, key: string) => void
+}
+
+type ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>
+
+const FAILURE_HINTS: Record<JumpFailureCode, QuestionNavKey> = {
+  VIEW_INACTIVE: 'jump.inactive',
+  TARGET_HIDDEN: 'jump.hidden',
+  NOT_FOUND: 'jump.notfound',
+  TIMEOUT: 'jump.timeout',
+}
+
+/** Live position of the instant hover tooltip. */
+interface TooltipState {
+  text: string
+  left: number
+  top: number
+}
+
+function findConvRoot(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('[data-slot="conversation"] > div[data-phase]')
+}
+
+export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | null {
+  const current = props.useSessions((s) => s.current)
+  const summary = props.useSessions((s) => (s.current === undefined ? undefined : s.byId[s.current]))
+  const visible = current !== undefined && summary !== undefined && summary.blank !== true
+
+  const [questions, setQuestions] = useState<QuestionNode[]>([])
+  const [jumpingKey, setJumpingKey] = useState<string | null>(null)
+  const [hint, setHint] = useState<string | null>(null)
+  const [tooltip, setTooltip] = useState<TooltipState | null>(null)
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const hintTimerRef = useRef<number | null>(null)
+
+  const showHint = (message: string): void => {
+    setHint(message)
+    if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)
+    hintTimerRef.current = window.setTimeout(() => setHint(null), 1800)
+  }
+
+  // Refresh the question list whenever the current session or its content changes.
+  useEffect(() => {
+    if (!visible || current === undefined) {
+      setQuestions([])
+      return
+    }
+    const refresh = (): void => setQuestions(props.readQuestions(current))
+    refresh()
+    const unsubContent = props.subscribeContent(current, refresh)
+    const unsubList = props.subscribeList(refresh)
+    return () => {
+      unsubContent()
+      unsubList()
+    }
+  }, [visible, current, props])
+
+  // Listen for jump-failure events and surface the hint.
+  useEffect(() => {
+    const onJumpFailed = (event: Event): void => {
+      const code = (event as CustomEvent<JumpFailureCode>).detail
+      showHint(props.t(FAILURE_HINTS[code] ?? 'jump.timeout'))
+    }
+    window.addEventListener('question-nav:jump-failed', onJumpFailed)
+    return () => window.removeEventListener('question-nav:jump-failed', onJumpFailed)
+  }, [props])
+
+  // Anchor the minimap to the conversation column: position it at the left
+  // edge of the conversation root and reserve a thin rail with padding-left.
+  useLayoutEffect(() => {
+    if (!visible) return
+    let raf = 0
+    let retries = 0
+    const applyLayout = (): void => {
+      const panel = panelRef.current
+      if (panel === null) return
+      const frame = panel.closest('[data-shell-overlay]')?.parentElement ?? null
+      const convRoot = findConvRoot()
+      if (frame === null || convRoot === null) return
+      const frameRect = frame.getBoundingClientRect()
+      const convRect = convRoot.getBoundingClientRect()
+      if (convRect.height <= 0) {
+        if (retries < 20) {
+          retries += 1
+          raf = requestAnimationFrame(applyLayout)
+        }
+        return
+      }
+      retries = 0
+      panel.style.top = `${convRect.top - frameRect.top}px`
+      panel.style.height = `${convRect.height}px`
+      panel.style.left = `${convRect.left - frameRect.left}px`
+    }
+    applyLayout()
+    raf = requestAnimationFrame(applyLayout)
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(applyLayout)
+    const convRoot = findConvRoot()
+    observer?.observe(convRoot ?? document.body, { box: 'border-box' })
+    window.addEventListener('resize', applyLayout)
+    return () => {
+      if (raf !== 0) cancelAnimationFrame(raf)
+      observer?.disconnect()
+      window.removeEventListener('resize', applyLayout)
+    }
+  }, [visible])
+
+  // Clear any pending hint timer on unmount.
+  useEffect(() => () => {
+    if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)
+  }, [])
+
+  if (!visible) return null
+
+  const onJump = (node: QuestionNode): void => {
+    if (current === undefined) return
+    setJumpingKey(node.key)
+    props.jump(current, node.key)
+    window.setTimeout(() => setJumpingKey((k) => (k === node.key ? null : k)), 600)
+  }
+
+  const t = props.t
+
+  return (
+    <div ref={panelRef} className={styles.rail} data-question-nav="rail">
+      {hint !== null ? <div className={styles.hint} role="status">{hint}</div> : null}
+      <div className={styles.list}>
+        {questions.length === 0 ? (
+          <div className={styles.empty}>{t('strip.empty')}</div>
+        ) : (
+          <div className={styles.dots}>
+            <span className={styles.count}>{questions.length}</span>
+            {questions.map((node) => (
+              <button
+                key={node.key}
+                className={jumpingKey === node.key ? `${styles.dot} ${styles.active}` : styles.dot}
+                aria-label={node.text}
+                onMouseEnter={(e) => {
+                  const r = e.currentTarget.getBoundingClientRect()
+                  setTooltip({ text: node.text, left: r.right + 10, top: r.top })
+                }}
+                onMouseLeave={() => setTooltip(null)}
+                onClick={() => onJump(node)}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+      {tooltip !== null
+        ? createPortal(
+            <div className={styles.tooltip} style={{ left: tooltip.left, top: tooltip.top }}>
+              {tooltip.text}
+            </div>,
+            document.body,
+          )
+        : null}
+    </div>
+  )
+}

package/src/client/css-modules.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}