@luziyang2026/dsh-question-nav 0.2.0 → 0.3.0

package/src/client/index.ts

@@ -4,15 +4,21 @@
  * Registers one surface into the frame-wide floating layer (`shell.overlay`):
  * a vertical strip on the LEFT 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). The
- * strip auto-expands the whole session history so even collapsed older
- * questions are surfaced as dots.
+ * scrolls the chat to that question.
+ *
+ * The strip indexes the WHOLE session history WITHOUT expanding DSH's paged
+ * render window: it pages the raw `session.history` RPC (read-only, no render
+ * cost) and derives each question's chat anchor key from the event. Only when
+ * a dot is clicked does the jump loop call `loadOlder()` to bring that
+ * specific page into the window — so the conversation's memory economy is
+ * preserved.
  *
  * 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'
+import type { ConnectionHandle } 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).
@@ -21,7 +27,7 @@ import { QuestionNavStrip, type QuestionNavInjected } from './QuestionNavStrip.t
 import { en, zh, type QuestionNavKey } from './locales.ts'
 import { extractQuestions } from '../core/nodes.ts'
 import { jumpToQuestion, type JumpFailureCode, type JumpPorts } from '../core/jump.ts'
-import { loadAllOlder, type LoadAllOptions, type LoadAllResult } from '../core/load-all.ts'
+import { buildQuestionIndex, type HistoryIndexOptions, type HistoryIndexResult, type RawEventLike } from '../core/history-index.ts'
 
 /** Locale namespace this plugin owns. */
 const NS = 'question-nav'
@@ -34,7 +40,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Services required by this plugin. */
-export const inject = ['slots', 'locale', 'sessions']
+export const inject = ['slots', 'locale', 'sessions', 'connection']
 
 /** Single-instance guard: a duplicated client injection must not mount twice. */
 declare global {
@@ -84,50 +90,43 @@ function jumpPortsFor(ctx: ClientContext, sessionId: SessionId): JumpPorts {
   }
 }
 
-/** Resolve the active conversation scrollport (or null when not mounted). */
-function scrollport(): HTMLElement | null {
-  return document.querySelector<HTMLElement>('[data-conversation-scroll]')
+/** Resolve the connection handle (shared API client) as other DSH plugins do. */
+function connectionOf(ctx: ClientContext): ConnectionHandle {
+  return ctx.get('connection') as ConnectionHandle
 }
 
 /**
- * One backward page that preserves the reader's scroll position. DSH's own
- * "load older" button arms a paging anchor; a programmatic `loadOlder()` does
- * not, so without this compensation prepended content would push the visible
- * rows down. We restore by the exact growth of the scrollHeight.
+ * One raw history page, mapped to the pure `buildQuestionIndex` port shape.
+ * `beforeSeq` is exclusive; `undefined` reads the newest page. Returns
+ * undefined when the page is unavailable so the builder stops cleanly. The
+ * SDK's `SessionEvent` is cast to the structural `RawEventLike` at this
+ * boundary (the index reader only touches type/seq/time/surfaceOp/data).
  */
-async function pagedLoadOlder(ctx: ClientContext, sessionId: SessionId): Promise<void> {
-  const binding = ctx.sessions.binding(sessionId)
-  if (binding === undefined) return
-  const port = scrollport()
-  const beforeHeight = port?.scrollHeight ?? 0
-  const beforeTop = port?.scrollTop ?? 0
-  await binding.session.loadOlder()
-  if (port === null) return
-  // Let React commit the prepend before measuring the new height.
-  await new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())))
-  const delta = port.scrollHeight - beforeHeight
-  if (delta > 0) port.scrollTop = beforeTop + delta
-}
-
-/** Map the session to the load-all port surface. */
-function loadAllPortsFor(ctx: ClientContext, sessionId: SessionId): Parameters<typeof loadAllOlder>[0] {
+async function rawHistoryPage(
+  ctx: ClientContext,
+  sessionId: SessionId,
+  beforeSeq: number | undefined,
+  maxMessages: number,
+): Promise<{ events: readonly { event: RawEventLike }[]; hasMore: boolean } | undefined> {
+  const { api } = connectionOf(ctx)
+  const { result } = await api.sessions.history({ sessionId, beforeSeq, maxMessages })
+  if (!result.ok) return undefined
   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 }
-    },
-    loadOlder: () => pagedLoadOlder(ctx, sessionId),
-    isViewActive: () => document.querySelector('[data-chat-flow]') !== null,
-    now: () => Date.now(),
-    sleep: (ms) => new Promise((resolve) => window.setTimeout(resolve, ms)),
+    events: result.value.events.map((entry) => ({ event: entry.event as unknown as RawEventLike })),
+    hasMore: result.value.hasMore,
   }
 }
 
-/** Expand the whole session history so every question becomes a dot. */
-function loadAllFor(ctx: ClientContext, sessionId: SessionId, options: LoadAllOptions = {}): Promise<LoadAllResult> {
-  return loadAllOlder(loadAllPortsFor(ctx, sessionId), options)
+/** Build the full-session question index from the raw history RPC (no render). */
+function buildIndexFor(
+  ctx: ClientContext,
+  sessionId: SessionId,
+  options: HistoryIndexOptions = {},
+): Promise<HistoryIndexResult> {
+  return buildQuestionIndex({
+    history: (beforeSeq, maxMessages) => rawHistoryPage(ctx, sessionId, beforeSeq, maxMessages),
+    now: () => Date.now(),
+  }, options)
 }
 
 function createInject(ctx: ClientContext): QuestionNavInjected {
@@ -152,7 +151,7 @@ function createInject(ctx: ClientContext): QuestionNavInjected {
       }
       void jumpToQuestion(ports, key)
     },
-    loadAllOlder: (sessionId, options) => loadAllFor(ctx, sessionId, options),
+    fetchQuestionIndex: (sessionId, options) => buildIndexFor(ctx, sessionId, options),
   }
 }
 

package/src/core/history-index.ts

@@ -0,0 +1,176 @@
+/**
+ * Question-index builder over the raw session history RPC.
+ *
+ * DSH pages the rendered conversation window on purpose (memory economy):
+ * `chat.nodes` only ever holds the loaded window, and force-expanding it
+ * (repeated `loadOlder()`) materializes + renders the whole log — the exact
+ * cost DSH's paging exists to avoid. This module instead builds a lightweight
+ * index of every user question by paging the RAW history RPC (`session.history`
+ * with `beforeSeq`), which reads the host log without touching the render
+ * window at all. Only `{key, seq, time, text}` per question is retained.
+ *
+ * The chat anchor key is derived deterministically from the event — it equals
+ * `conversationContextKey('input-message', String(event.data.id))` — so the
+ * dots can target rows that are not loaded yet, and a click then pages the
+ * window on demand (see `jump.ts`).
+ *
+ * Pure-ish: takes injected ports (one raw history page read, clocks) so it is
+ * unit-testable without a browser or a live session.
+ */
+
+import type { QuestionNode } from './nodes.ts'
+import { messageText } from './nodes.ts'
+
+/** Minimal shape of a raw history event (structural, not SDK-bound). */
+export interface RawEventLike {
+  type: string
+  seq: number
+  time: number
+  surfaceOp?: unknown
+  data?: {
+    id?: unknown
+    source?: { kind?: string; plugin?: string }
+    content?: readonly { type?: string; text?: string }[]
+  }
+}
+
+/** The conversation Definition kind whose key a user question node uses. */
+export const MESSAGE_DEFINITION_KIND = 'input-message'
+
+/**
+ * The engine-owned stable chat key for a user question event — mirrors
+ * `conversationContextKey('input-message', String(id))` from the DSH runtime
+ * (verified against it in the unit test).
+ */
+export function questionKey(id: unknown): string {
+  const kind = MESSAGE_DEFINITION_KIND
+  return `${kind.length}:${kind}${String(id)}`
+}
+
+/**
+ * Whether a raw event is one user question the strip should index.
+ * Mirrors the DSH `messageDefinition` match + `start` classification:
+ * an append-origin `user/message` with a human (`user`) source. Replacement
+ * copies (compaction checkpoints, `source.kind === 'plugin'`) and injected
+ * context (`source.kind !== 'user'`) are excluded.
+ */
+export function isQuestionEvent(event: RawEventLike): boolean {
+  if (event.type !== 'user/message') return false
+  if (event.surfaceOp !== 'append') return false
+  return event.data?.source?.kind === 'user'
+}
+
+/** Map one raw question event to a strip question node, or null when not one. */
+export function questionFromEvent(event: RawEventLike): QuestionNode | null {
+  if (!isQuestionEvent(event)) return null
+  return {
+    key: questionKey(event.data?.id),
+    anchorSeq: event.seq,
+    seq: event.seq,
+    time: event.time,
+    text: messageText(event.data?.content),
+  }
+}
+
+export interface HistoryIndexPorts {
+  /**
+   * Read one raw history page. `beforeSeq` is exclusive (events with seq <
+   * beforeSeq); `undefined` reads the newest page. Resolves undefined when
+   * the page is unavailable (session gone / transport error).
+   */
+  history: (
+    beforeSeq: number | undefined,
+    maxMessages: number,
+  ) => Promise<{ events: readonly { event: RawEventLike }[]; hasMore: boolean } | undefined>
+  /** Monotonic ms clock. */
+  now: () => number
+}
+
+export interface HistoryIndexOptions {
+  /** Raw messages per page (default 100). */
+  maxMessages?: number
+  /** Max pages before giving up (default 200 => 20k messages). */
+  maxPages?: number
+  /** Total wall-clock budget (default 30s). */
+  totalTimeoutMs?: number
+  /** Abort the build; checked every iteration. */
+  signal?: AbortSignal
+  /** Resume from a previous `nextBeforeSeq` instead of the newest page. */
+  startBeforeSeq?: number
+}
+
+export type HistoryIndexCode = 'COMPLETE' | 'BUDGET' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELLED'
+
+export interface HistoryIndexResult {
+  ok: boolean
+  code: HistoryIndexCode
+  /** Questions collected so far, ascending by anchorSeq. */
+  questions: QuestionNode[]
+  /** Page count actually read. */
+  pages: number
+  /** Where to continue (exclusive) when stopped early; undefined when COMPLETE. */
+  nextBeforeSeq: number | undefined
+}
+
+const DEFAULTS = {
+  maxMessages: 100,
+  maxPages: 200,
+  totalTimeoutMs: 30_000,
+}
+
+function minSeq(events: readonly { event: RawEventLike }[]): number | undefined {
+  let min: number | undefined
+  for (const { event } of events) {
+    if (min === undefined || event.seq < min) min = event.seq
+  }
+  return min
+}
+
+/**
+ * Page the raw session history backward, collecting every user question into a
+ * lightweight index. Never touches the render window.
+ */
+export async function buildQuestionIndex(
+  ports: HistoryIndexPorts,
+  options: HistoryIndexOptions = {},
+): Promise<HistoryIndexResult> {
+  const cfg = { ...DEFAULTS, ...options }
+  const deadline = ports.now() + cfg.totalTimeoutMs
+  const questions: QuestionNode[] = []
+  let beforeSeq: number | undefined = cfg.startBeforeSeq
+  let pages = 0
+
+  const cancelled = (): boolean => cfg.signal?.aborted === true
+
+  while (true) {
+    if (cancelled()) return { ok: false, code: 'CANCELLED', questions, pages, nextBeforeSeq: beforeSeq }
+    if (ports.now() > deadline) return { ok: false, code: 'TIMEOUT', questions, pages, nextBeforeSeq: beforeSeq }
+    if (pages >= cfg.maxPages) return { ok: false, code: 'BUDGET', questions, pages, nextBeforeSeq: beforeSeq }
+
+    const page = await ports.history(beforeSeq, cfg.maxMessages)
+    if (page === undefined) {
+      // Transient: retry a little, then give up with what we have.
+      if (pages === 0) return { ok: false, code: 'UNAVAILABLE', questions, pages, nextBeforeSeq: beforeSeq }
+      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
+    }
+
+    for (const { event } of page.events) {
+      const question = questionFromEvent(event)
+      if (question !== null) questions.push(question)
+    }
+
+    if (!page.hasMore) {
+      questions.sort((a, b) => a.anchorSeq - b.anchorSeq)
+      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
+    }
+
+    const next = minSeq(page.events)
+    if (next === undefined) {
+      // Empty page with hasMore true is anomalous; stop cleanly.
+      questions.sort((a, b) => a.anchorSeq - b.anchorSeq)
+      return { ok: true, code: 'COMPLETE', questions, pages, nextBeforeSeq: undefined }
+    }
+    beforeSeq = next
+    pages += 1
+  }
+}

package/src/core/nodes.ts

@@ -96,3 +96,17 @@ export function nearestRenderable(
   }
   return best
 }
+
+/**
+ * Merge two question sets (full-history index + live loaded window) into one
+ * deduplicated, anchorSeq-ascending list. The window may hold questions that
+ * arrived after the index was built; the index may hold questions the window
+ * has not loaded yet — union on `key`, newest live copy wins per key.
+ */
+export function mergeQuestions(...sources: readonly (readonly QuestionNode[])[]): QuestionNode[] {
+  const byKey = new Map<string, QuestionNode>()
+  for (const source of sources) {
+    for (const node of source) byKey.set(node.key, node)
+  }
+  return [...byKey.values()].sort((a, b) => a.anchorSeq - b.anchorSeq)
+}

package/src/core/load-all.ts

@@ -1,97 +0,0 @@
-/**
- * Load-all orchestration for the question-nav strip.
- *
- * DSH sessions page history in fixed-size chunks: `chat.nodes` only ever holds
- * the currently loaded window, and questions that still sit behind the "load
- * older" button are invisible to the strip until the window is expanded
- * backwards. This loop pages `loadOlder()` until `hasMore` is false (the whole
- * history is materialized), so every user question becomes a dot.
- *
- * Pure-ish: takes injected ports (snapshot read, one paged loadOlder, view
- * liveness, clocks) so it is unit-testable without a browser or session.
- */
-
-export interface LoadAllSnapshot {
-  openState: string
-  hasMore: boolean
-  loadingOlder: boolean
-}
-
-export interface LoadAllPorts {
-  /** Read the current session snapshot; undefined when unavailable. */
-  snapshot: () => LoadAllSnapshot | undefined
-  /** Expand the window backwards by one page (may preserve scroll). */
-  loadOlder: () => Promise<void>
-  /** True while the chat view is active (a `[data-chat-flow]` is mounted). */
-  isViewActive: () => boolean
-  /** Monotonic ms clock. */
-  now: () => number
-  /** Async sleep. */
-  sleep: (ms: number) => Promise<void>
-}
-
-export interface LoadAllOptions {
-  /** Max older pages to fetch before giving up (default 400). */
-  maxPages?: number
-  /** Total wall-clock budget for the whole expansion (default 60s). */
-  totalTimeoutMs?: number
-  /** Poll interval for open/loading transitions (default 60ms). */
-  pollMs?: number
-  /** Abort the expansion; checked every iteration. */
-  signal?: AbortSignal
-}
-
-export type LoadAllCode =
-  | 'COMPLETE'
-  | 'VIEW_INACTIVE'
-  | 'NOT_OPEN'
-  | 'BUDGET'
-  | 'TIMEOUT'
-  | 'CANCELLED'
-
-export interface LoadAllResult {
-  ok: boolean
-  code: LoadAllCode
-  /** Number of `loadOlder` pages actually fetched. */
-  pages: number
-}
-
-const DEFAULTS = {
-  maxPages: 400,
-  totalTimeoutMs: 60_000,
-  pollMs: 60,
-}
-
-/**
- * Expand the session window backwards until the earliest history is loaded.
- * Waits while the session is still opening; aborts on cancellation, budget or
- * timeout. Safe to re-enter: once `hasMore` is false the loop returns
- * immediately with `COMPLETE`.
- */
-export async function loadAllOlder(ports: LoadAllPorts, options: LoadAllOptions = {}): Promise<LoadAllResult> {
-  const cfg = { ...DEFAULTS, ...options }
-  const deadline = ports.now() + cfg.totalTimeoutMs
-  let pages = 0
-
-  const cancelled = (): boolean => cfg.signal?.aborted === true
-
-  while (true) {
-    if (cancelled()) return { ok: false, code: 'CANCELLED', pages }
-    if (!ports.isViewActive()) return { ok: false, code: 'VIEW_INACTIVE', pages }
-    const snap = ports.snapshot()
-    if (snap === undefined) return { ok: false, code: 'VIEW_INACTIVE', pages }
-    if (snap.openState === 'error') return { ok: false, code: 'NOT_OPEN', pages }
-    // Nothing older left: the whole history is in the window.
-    if (snap.hasMore !== true) return { ok: true, code: 'COMPLETE', pages }
-    if (pages >= cfg.maxPages) return { ok: false, code: 'BUDGET', pages }
-    if (ports.now() > deadline) return { ok: false, code: 'TIMEOUT', pages }
-    // Wait while the session is still opening or a page is already in flight
-    // (a user-initiated "load older" click shares this same gate).
-    if (snap.openState !== 'open' || snap.loadingOlder) {
-      await ports.sleep(cfg.pollMs)
-      continue
-    }
-    await ports.loadOlder()
-    pages += 1
-  }
-}