@luziyang2026/dsh-question-nav 0.3.0 → 0.4.0

package/src/client/QuestionNavStrip.tsx

@@ -1,24 +1,23 @@
 /**
  * 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.
+ * `shell.overlay` floating layer), vertically centered: one dot per turn that
+ * claimed at least one user question — strictly aligned with the Trajectory
+ * view's turn numbering (turns without a question produce no dot). Hover
+ * enlarges a dot and shows an instant tooltip (portal-rendered, no native
+ * delay) with the turn label and the turn's question text(s); clicking jumps
+ * the chat to that turn's first question.
  *
- * Index strategy (no render-window expansion): the dots cover the WHOLE
- * session history. The index is built from the raw `session.history` RPC via
- * the injected `fetchQuestionIndex` — the conversation's paged window is
- * untouched, so DSH's memory economy is preserved. The loaded window's live
- * questions are merged on top (for new messages arriving after the index was
- * built). Clicking a dot jumps through the existing paging loop, which calls
- * `loadOlder()` only until that specific page is in the window. If the index
- * safety budget is exhausted, a dimmed dashed "load earlier" dot appears above
- * the oldest question and continues the index on click.
+ * Data source: the host-folded `questionIndex` session projection (whole
+ * history, persisted host-side, pushed live through session/projection
+ * frames) read through the injected `questionProjection` face, plus the live
+ * chat window's questions merged on top for the brief window before a
+ * just-sent question lands in the projection. No render-window expansion, no
+ * client-side history paging.
  *
- * Data arrives through the four props shares: the framework `useSessions`
- * hook (current session), the registrant inject face (read/subscribe/jump/
- * fetch-index), and the bound locale translator.
+ * Data arrives through the props shares: the framework `useSessions` hook
+ * (current session), the registrant inject face (read/subscribe/project/
+ * jump), and the bound locale translator.
  */
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
@@ -27,12 +26,20 @@ 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 { mergeQuestions } from '../core/nodes.ts'
+import type { QuestionEntry } from '../core/question-entry.ts'
+import { groupQuestionsByTurn, mergeLiveQuestions, type TurnDot } from '../core/turn-dots.ts'
 import type { JumpFailureCode } from '../core/jump.ts'
-import type { HistoryIndexOptions, HistoryIndexResult } from '../core/history-index.ts'
 import type { QuestionNavKey } from './locales.ts'
 import styles from './question-nav.module.css'
 
+/** Minimal observable shape of a session projection face. */
+export interface ObservableFace {
+  /** Current projection value (unknown — validated structurally at read). */
+  getSnapshot: () => unknown
+  /** Subscribe to value changes; returns an unsubscribe. */
+  subscribe: (listener: () => void) => () => void
+}
+
 /** Values the registrant inject face supplies (wired in src/client/index.ts). */
 export interface QuestionNavInjected {
   /** Extract the user questions of a session's currently loaded window. */
@@ -41,10 +48,10 @@ export interface QuestionNavInjected {
   subscribeList: (cb: () => void) => () => void
   /** Subscribe to a session's content; returns an unsubscribe. */
   subscribeContent: (sessionId: SessionId, cb: () => void) => () => void
+  /** The session's `questionIndex` projection face, when the host unit is registered. */
+  questionProjection: (sessionId: SessionId) => ObservableFace | undefined
   /** Jump the chat to a question row (pages the window on demand). */
   jump: (sessionId: SessionId, key: string) => void
-  /** Build the full-session question index from the raw history RPC. */
-  fetchQuestionIndex: (sessionId: SessionId, options?: HistoryIndexOptions) => Promise<HistoryIndexResult>
 }
 
 type ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>
@@ -58,11 +65,25 @@ const FAILURE_HINTS: Record<JumpFailureCode, QuestionNavKey> = {
 
 /** Live position of the instant hover tooltip. */
 interface TooltipState {
-  text: string
+  /** Turn label line (e.g. "Turn 32"); null for ungrouped live questions. */
+  title: string | null
+  /** Question text lines (one per question folded into the dot). */
+  lines: readonly string[]
   left: number
   top: number
 }
 
+/** Read the projection face value as a question-entry list (structural guard). */
+function projectionEntries(face: ObservableFace | undefined): QuestionEntry[] {
+  const value = face?.getSnapshot()
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is QuestionEntry =>
+    typeof item === 'object' && item !== null
+    && typeof (item as QuestionEntry).id === 'string'
+    && typeof (item as QuestionEntry).seq === 'number'
+    && typeof (item as QuestionEntry).turn === 'number')
+}
+
 function findConvRoot(): HTMLElement | null {
   return document.querySelector<HTMLElement>('[data-slot="conversation"] > div[data-phase]')
 }
@@ -72,22 +93,12 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   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 [dots, setDots] = useState<TurnDot[]>([])
   const [jumpingKey, setJumpingKey] = useState<string | null>(null)
   const [hint, setHint] = useState<string | null>(null)
   const [tooltip, setTooltip] = useState<TooltipState | null>(null)
-  const [loadingIndex, setLoadingIndex] = useState(false)
-  const [moreAvailable, setMoreAvailable] = useState(false)
   const panelRef = useRef<HTMLDivElement | null>(null)
   const hintTimerRef = useRef<number | null>(null)
-  /** Full-history index from the raw RPC (per current session). */
-  const indexRef = useRef<QuestionNode[]>([])
-  /** Next beforeSeq to resume from when the index budget was exhausted. */
-  const nextBeforeSeqRef = useRef<number | undefined>(undefined)
-  /** Abort controller for the in-flight index build. */
-  const indexAbortRef = useRef<AbortController | null>(null)
-  /** Session whose index build is in flight, to avoid duplicate loops. */
-  const buildingSessionRef = useRef<SessionId | null>(null)
 
   const showHint = (message: string): void => {
     setHint(message)
@@ -95,57 +106,25 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     hintTimerRef.current = window.setTimeout(() => setHint(null), 1800)
   }
 
-  // Build the full-history index on show; refresh the live window on content
-  // change and merge both into the dot list.
+  // Recompute the dot list from the projection + live window; subscribe to
+  // the projection push frames, session content, and the session list.
   useEffect(() => {
     if (!visible || current === undefined) {
-      indexRef.current = []
-      nextBeforeSeqRef.current = undefined
-      indexAbortRef.current?.abort()
-      indexAbortRef.current = null
-      buildingSessionRef.current = null
-      setQuestions([])
-      setLoadingIndex(false)
-      setMoreAvailable(false)
+      setDots([])
       return
     }
     const sessionId = current
-    // Reset the per-session index: this effect re-runs on session change.
-    indexRef.current = []
-    nextBeforeSeqRef.current = undefined
+    const face = props.questionProjection(sessionId)
     const refresh = (): void => {
-      const windowQuestions = props.readQuestions(sessionId)
-      setQuestions(mergeQuestions(indexRef.current, windowQuestions))
-    }
-    const startBuild = (options?: HistoryIndexOptions): void => {
-      buildingSessionRef.current = sessionId
-      const controller = new AbortController()
-      indexAbortRef.current = controller
-      setLoadingIndex(true)
-      setMoreAvailable(false)
-      props.fetchQuestionIndex(sessionId, { ...options, signal: controller.signal })
-        .then((result) => {
-          if (buildingSessionRef.current !== sessionId) return
-          indexRef.current = mergeQuestions(result.questions, indexRef.current)
-          nextBeforeSeqRef.current = result.nextBeforeSeq
-          setMoreAvailable(result.code === 'BUDGET' && result.nextBeforeSeq !== undefined)
-          refresh()
-        })
-        .finally(() => {
-          if (buildingSessionRef.current === sessionId) {
-            setLoadingIndex(false)
-            if (indexAbortRef.current === controller) indexAbortRef.current = null
-            buildingSessionRef.current = null
-          }
-        })
+      const grouped = groupQuestionsByTurn(projectionEntries(face))
+      setDots(mergeLiveQuestions(grouped, props.readQuestions(sessionId)))
     }
     refresh()
-    startBuild()
+    const unsubProjection = face?.subscribe(refresh) ?? (() => {})
     const unsubContent = props.subscribeContent(sessionId, refresh)
     const unsubList = props.subscribeList(refresh)
     return () => {
-      indexAbortRef.current?.abort()
-      indexAbortRef.current = null
+      unsubProjection()
       unsubContent()
       unsubList()
     }
@@ -208,26 +187,21 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
 
   if (!visible) return null
 
-  const onJump = (node: QuestionNode): void => {
+  const onJump = (dot: TurnDot): void => {
     if (current === undefined) return
-    setJumpingKey(node.key)
-    props.jump(current, node.key)
-    window.setTimeout(() => setJumpingKey((k) => (k === node.key ? null : k)), 600)
+    setJumpingKey(dot.key)
+    props.jump(current, dot.key)
+    window.setTimeout(() => setJumpingKey((k) => (k === dot.key ? null : k)), 600)
   }
 
-  const onLoadMore = (): void => {
-    if (current === undefined || nextBeforeSeqRef.current === undefined) return
-    setMoreAvailable(false)
-    setLoadingIndex(true)
-    props.fetchQuestionIndex(current, { startBeforeSeq: nextBeforeSeqRef.current })
-      .then((result) => {
-        if (current === undefined) return
-        indexRef.current = mergeQuestions(result.questions, indexRef.current)
-        nextBeforeSeqRef.current = result.nextBeforeSeq
-        setMoreAvailable(result.code === 'BUDGET' && result.nextBeforeSeq !== undefined)
-        setQuestions(mergeQuestions(indexRef.current, props.readQuestions(current)))
-      })
-      .finally(() => setLoadingIndex(false))
+  const openTooltip = (dot: TurnDot, target: HTMLElement): void => {
+    const r = target.getBoundingClientRect()
+    setTooltip({
+      title: dot.turn === null ? null : `Turn ${dot.turn}`,
+      lines: dot.texts,
+      left: r.right + 10,
+      top: r.top,
+    })
   }
 
   const t = props.t
@@ -236,38 +210,19 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     <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}>{loadingIndex ? t('strip.loadingAll') : t('strip.empty')}</div>
+        {dots.length === 0 ? (
+          <div className={styles.empty}>{t('strip.empty')}</div>
         ) : (
           <div className={styles.dots}>
-            <span className={styles.count}>
-              {questions.length}
-              {loadingIndex ? <span className={styles.countLoading}>{t('strip.loadingSuffix')}</span> : null}
-            </span>
-            {moreAvailable && !loadingIndex ? (
-              <button
-                className={`${styles.dot} ${styles.moreDot}`}
-                aria-label={t('strip.loadEarlier')}
-                title={t('strip.loadEarlier')}
-                onMouseEnter={(e) => {
-                  const r = e.currentTarget.getBoundingClientRect()
-                  setTooltip({ text: t('strip.loadEarlier'), left: r.right + 10, top: r.top })
-                }}
-                onMouseLeave={() => setTooltip(null)}
-                onClick={onLoadMore}
-              />
-            ) : null}
-            {questions.map((node) => (
+            <span className={styles.count}>{dots.length}</span>
+            {dots.map((dot) => (
               <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 })
-                }}
+                key={dot.key}
+                className={jumpingKey === dot.key ? `${styles.dot} ${styles.active}` : styles.dot}
+                aria-label={dot.texts[0] ?? ''}
+                onMouseEnter={(e) => openTooltip(dot, e.currentTarget)}
                 onMouseLeave={() => setTooltip(null)}
-                onClick={() => onJump(node)}
+                onClick={() => onJump(dot)}
               />
             ))}
           </div>
@@ -276,7 +231,10 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
       {tooltip !== null
         ? createPortal(
             <div className={styles.tooltip} style={{ left: tooltip.left, top: tooltip.top }}>
-              {tooltip.text}
+              {tooltip.title !== null ? <div className={styles.tooltipTitle}>{tooltip.title}</div> : null}
+              {tooltip.lines.map((line, index) => (
+                <div key={index} className={styles.tooltipLine}>{line}</div>
+              ))}
             </div>,
             document.body,
           )

package/src/client/index.ts

@@ -3,31 +3,30 @@
  *
  * 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.
+ * user question in the current session as a small button, one dot per turn.
+ * Clicking a button scrolls the chat to that turn's first 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.
+ * The dots are driven by the host-folded `questionIndex` session projection
+ * (registered by the plugin's host half): the projection registry folds the
+ * WHOLE event log without touching the chat's paged render window, the
+ * projection cache persists it, and the standard carriers (history tail-page
+ * baseline + session/projection push frames) keep it live. Live-window
+ * questions not yet recorded by the projection are merged on top so a
+ * just-sent question appears immediately.
  *
  * 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).
 import type {} from '@deepseek-ai/dsh-client-locale/client'
-import { QuestionNavStrip, type QuestionNavInjected } from './QuestionNavStrip.tsx'
+import { QuestionNavStrip, type ObservableFace, 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'
-import { buildQuestionIndex, type HistoryIndexOptions, type HistoryIndexResult, type RawEventLike } from '../core/history-index.ts'
 
 /** Locale namespace this plugin owns. */
 const NS = 'question-nav'
@@ -40,7 +39,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 }
 
 /** Services required by this plugin. */
-export const inject = ['slots', 'locale', 'sessions', 'connection']
+export const inject = ['slots', 'locale', 'sessions']
 
 /** Single-instance guard: a duplicated client injection must not mount twice. */
 declare global {
@@ -90,45 +89,20 @@ function jumpPortsFor(ctx: ClientContext, sessionId: SessionId): JumpPorts {
   }
 }
 
-/** Resolve the connection handle (shared API client) as other DSH plugins do. */
-function connectionOf(ctx: ClientContext): ConnectionHandle {
-  return ctx.get('connection') as ConnectionHandle
-}
-
 /**
- * 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).
+ * The session's `questionIndex` projection face (getSnapshot + subscribe).
+ * Undefined when the session is not bound or the host unit is not registered
+ * (e.g. a headless composition) — the strip then shows live-window dots only.
  */
-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
+function questionProjectionOf(ctx: ClientContext, sessionId: SessionId): ObservableFace | undefined {
+  const face = ctx.sessions.binding(sessionId)?.session.projections.faceOf('questionIndex')
+  if (face === undefined) return undefined
   return {
-    events: result.value.events.map((entry) => ({ event: entry.event as unknown as RawEventLike })),
-    hasMore: result.value.hasMore,
+    getSnapshot: () => face.getSnapshot(),
+    subscribe: (listener) => face.subscribe(listener),
   }
 }
 
-/** 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 {
   return {
     readQuestions: (sessionId) => {
@@ -142,6 +116,7 @@ function createInject(ctx: ClientContext): QuestionNavInjected {
       if (binding === undefined) return () => {}
       return binding.session.subscribe(cb)
     },
+    questionProjection: (sessionId) => questionProjectionOf(ctx, sessionId),
     jump: (sessionId, key) => {
       const ports = jumpPortsFor(ctx, sessionId)
       ports.report = (code: JumpFailureCode) => {
@@ -151,7 +126,6 @@ function createInject(ctx: ClientContext): QuestionNavInjected {
       }
       void jumpToQuestion(ports, key)
     },
-    fetchQuestionIndex: (sessionId, options) => buildIndexFor(ctx, sessionId, options),
   }
 }
 

package/src/client/locales.ts

@@ -4,9 +4,6 @@
  */
 export const zh = {
   'strip.empty': '本会话还没有提问',
-  'strip.loadingAll': '正在加载全部历史…',
-  'strip.loadingSuffix': '…',
-  'strip.loadEarlier': '加载更早的问题',
   'jump.inactive': '聊天视图未激活',
   'jump.hidden': '目标无独立气泡，已定位到邻近内容',
   'jump.notfound': '目标未加载或不存在（可能已压缩）',
@@ -15,9 +12,6 @@ export const zh = {
 
 export const en = {
   'strip.empty': 'No questions in this session yet',
-  'strip.loadingAll': 'Loading full history…',
-  'strip.loadingSuffix': '…',
-  'strip.loadEarlier': 'Load earlier questions',
   '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)',

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

@@ -58,17 +58,6 @@
   background: var(--dsw-alias-brand-primary);
 }
 
-/* Dimmed placeholder for unloaded older history (below the count, above the
-   oldest question): click to page in more history. */
-.moreDot {
-  background: transparent;
-  border: 1px dashed var(--dsw-alias-border-l3);
-}
-.moreDot:hover {
-  background: var(--dsw-alias-brand-primary);
-  border-color: var(--dsw-alias-brand-primary);
-}
-
 /* Question count, rendered just above the first dot (sits in the list gap). */
 .count {
   flex: none;
@@ -79,19 +68,6 @@
   user-select: none;
 }
 
-/* Ellipsis shown while the full history is being expanded. */
-.countLoading {
-  margin-left: 2px;
-  font-weight: 400;
-  color: var(--dsw-alias-brand-primary);
-  animation: qnPulse 1.2s ease-in-out infinite;
-}
-
-@keyframes qnPulse {
-  0%, 100% { opacity: 0.4; }
-  50% { opacity: 1; }
-}
-
 /* 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 {
@@ -127,3 +103,18 @@
   word-break: break-word;
   pointer-events: none;
 }
+
+/* Turn label line at the top of the tooltip ("Turn 32"). */
+.tooltipTitle {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-tertiary);
+  margin-bottom: 4px;
+}
+
+/* One question text line; consecutive lines (multi-question turns) separate. */
+.tooltipLine + .tooltipLine {
+  margin-top: 6px;
+  padding-top: 6px;
+  border-top: 1px solid var(--dsw-alias-border-l1);
+}

package/src/core/nodes.ts

@@ -96,17 +96,3 @@ 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/question-entry.ts

@@ -0,0 +1,17 @@
+/**
+ * One user question recorded by the `questionIndex` session projection.
+ * Shared by the host fold (src/projection.ts) and the browser strip — the
+ * wire value is an array of these entries, in seq order.
+ */
+export interface QuestionEntry {
+  /** Turn that claimed this question (turn/start the event followed). */
+  turn: number
+  /** UserMessage id; the client derives the chat anchor key from it. */
+  id: string
+  /** Event seq of the user/message event (ordering + jump anchor seq). */
+  seq: number
+  /** Unix ms timestamp of the question. */
+  time: number
+  /** First text block of the question (hover tooltip body). */
+  text: string
+}

package/src/core/turn-dots.ts

@@ -0,0 +1,98 @@
+/**
+ * Turn-aligned dot model for the question-nav strip. Pure transforms over the
+ * `questionIndex` projection value plus the live chat window — no React, no
+ * DOM — so the grouping and merging rules are unit-testable in isolation.
+ *
+ * One dot per turn that claimed at least one user question; turns without a
+ * question (retry, goal continuation, cancelled empty turns) produce no dot,
+ * so dot turn labels may skip numbers but always match the Trajectory view.
+ */
+
+import type { QuestionEntry } from './question-entry.ts'
+import type { QuestionNode } from './nodes.ts'
+
+/** 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 — mirrors
+ * `conversationContextKey('input-message', String(id))` from the DSH runtime
+ * (verified against that formula in the unit test).
+ */
+export function questionKey(id: unknown): string {
+  const kind = MESSAGE_DEFINITION_KIND
+  return `${kind.length}:${kind}${String(id)}`
+}
+
+/** One strip dot: a turn's questions (grouped) or one ungrouped live question. */
+export interface TurnDot {
+  /** Owning turn number; null for live questions the projection has not seen. */
+  readonly turn: number | null
+  /** Jump anchor: the chat key of the turn's FIRST question. */
+  readonly key: string
+  /** Anchor seq of the first question (ordering + jump target). */
+  readonly anchorSeq: number
+  /** Unix ms of the first question. */
+  readonly time: number
+  /** Every question text of this dot, in order (tooltip lists them all). */
+  readonly texts: readonly string[]
+  /** Chat keys of every question folded into this dot (live-merge dedupe). */
+  readonly memberKeys: readonly string[]
+}
+
+/**
+ * Fold the projection's question list into one dot per turn. Entries arrive
+ * in event order; consecutive same-turn entries merge into a single dot whose
+ * anchor is the turn's first question.
+ */
+export function groupQuestionsByTurn(entries: readonly QuestionEntry[]): TurnDot[] {
+  const sorted = [...entries].sort((a, b) => a.seq - b.seq)
+  const dots: TurnDot[] = []
+  for (const entry of sorted) {
+    const key = questionKey(entry.id)
+    const last = dots.at(-1)
+    if (last !== undefined && last.turn === entry.turn) {
+      dots[dots.length - 1] = {
+        ...last,
+        texts: [...last.texts, entry.text],
+        memberKeys: [...last.memberKeys, key],
+      }
+      continue
+    }
+    dots.push({
+      turn: entry.turn,
+      key,
+      anchorSeq: entry.seq,
+      time: entry.time,
+      texts: [entry.text],
+      memberKeys: [key],
+    })
+  }
+  return dots
+}
+
+/**
+ * Merge live-window questions the projection has not recorded yet (the brief
+ * window before the session/projection push frame lands). A live question
+ * whose key is already folded into a dot is dropped (the projected copy
+ * wins); the rest become single-question dots with `turn: null`, inserted in
+ * anchor-seq order so the strip stays strictly chronological.
+ */
+export function mergeLiveQuestions(
+  dots: readonly TurnDot[],
+  live: readonly QuestionNode[],
+): TurnDot[] {
+  const known = new Set(dots.flatMap(dot => dot.memberKeys))
+  const extras: TurnDot[] = live
+    .filter(question => !known.has(question.key))
+    .map(question => ({
+      turn: null,
+      key: question.key,
+      anchorSeq: question.anchorSeq,
+      time: question.time,
+      texts: [question.text],
+      memberKeys: [question.key],
+    }))
+  if (extras.length === 0) return [...dots]
+  return [...dots, ...extras].sort((a, b) => a.anchorSeq - b.anchorSeq)
+}

package/src/index.ts

@@ -1,10 +1,27 @@
 /**
- * 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).
+ * Host half of the dsh-question-nav plugin — runs in the DSH host process.
+ * Registers the `questionIndex` session projection unit: the ordered list of
+ * user questions (each tagged with its turn), folded from the session event
+ * log by the projection registry, persisted by the projection cache, and
+ * delivered to the browser through the standard projection carriers (history
+ * tail-page baseline + session/projection push frames). The navigation UI
+ * itself lives in the browser half (src/client).
  */
 import type { Context } from '@deepseek-ai/cordis'
+import { questionIndexProjectionDefinition } from './projection.ts'
 
-/** Apply the host half (no host behavior for this plugin). */
-export function apply(_ctx: Context): void {}
+/** Cordis plugin name. */
+export const name = 'dsh-question-nav'
+
+/**
+ * Register the `questionIndex` unit. The registry is an optional capability
+ * (absent in headless compositions), so registration rides `ctx.inject`:
+ * without it the host half simply contributes nothing and the browser strip
+ * falls back to live-window questions.
+ * @param ctx - plugin context.
+ */
+export function apply(ctx: Context): void {
+  ctx.inject(['sessionProjections'], (inner) => {
+    inner.sessionProjections.register(questionIndexProjectionDefinition)
+  })
+}