@luziyang2026/dsh-question-nav 0.2.0 → 0.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.2.0",
+  "version": "0.4.0",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {
@@ -28,7 +28,6 @@
     "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",
@@ -38,12 +37,12 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsdown",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.build-client.json && tsdown",
     "prepare": "tsdown",
     "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build",
     "watch": "tsdown --watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.host.json"
   },
   "peerDependencies": {
     "react": "^18.2.0",
@@ -57,6 +56,8 @@
     "@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",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "0.1.1-rc.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",
@@ -84,5 +85,8 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/AbelKeithsun/dsh-question-nav.git"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
   }
 }

package/src/client/QuestionNavStrip.tsx

@@ -1,20 +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.
  *
- * Dots index the WHOLE session history, not just the currently loaded window:
- * on show, the strip auto-expands older pages (`loadAllOlder`) so questions
- * that still sit behind DSH's "load older" button are surfaced too. While the
- * expansion is running the count shows a "…" affordance; if the safety budget
- * is exhausted a dimmed "load earlier" dot appears above the oldest question.
+ * 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/
- * load-all), 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'
@@ -23,23 +26,32 @@ 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 { 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 { LoadAllOptions, LoadAllResult } from '../core/load-all.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 (current loaded window). */
+  /** Extract the user questions of a session's currently 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. */
+  /** 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
-  /** Expand the session history until every question is loaded. */
-  loadAllOlder: (sessionId: SessionId, options?: LoadAllOptions) => Promise<LoadAllResult>
 }
 
 type ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>
@@ -53,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]')
 }
@@ -67,18 +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 [loadingAll, setLoadingAll] = useState(false)
-  const [moreAvailable, setMoreAvailable] = useState(false)
   const panelRef = useRef<HTMLDivElement | null>(null)
   const hintTimerRef = useRef<number | null>(null)
-  /** Abort controller for the in-flight expansion (cancelled on session change). */
-  const loadAllAbortRef = useRef<AbortController | null>(null)
-  /** Session whose expansion is already running, to avoid duplicate loops. */
-  const loadingAllSessionRef = useRef<SessionId | null>(null)
 
   const showHint = (message: string): void => {
     setHint(message)
@@ -86,52 +106,29 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     hintTimerRef.current = window.setTimeout(() => setHint(null), 1800)
   }
 
-  // Refresh the question list whenever the current session or its content changes.
+  // 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) {
-      setQuestions([])
+      setDots([])
       return
     }
-    const refresh = (): void => setQuestions(props.readQuestions(current))
+    const sessionId = current
+    const face = props.questionProjection(sessionId)
+    const refresh = (): void => {
+      const grouped = groupQuestionsByTurn(projectionEntries(face))
+      setDots(mergeLiveQuestions(grouped, props.readQuestions(sessionId)))
+    }
     refresh()
-    const unsubContent = props.subscribeContent(current, refresh)
+    const unsubProjection = face?.subscribe(refresh) ?? (() => {})
+    const unsubContent = props.subscribeContent(sessionId, refresh)
     const unsubList = props.subscribeList(refresh)
     return () => {
+      unsubProjection()
       unsubContent()
       unsubList()
     }
-  }, [visible, current, props])
-
-  // Auto-expand the full history so collapsed older questions surface as dots.
-  // Runs once per session; the session notifier drives the list refresh above.
-  useEffect(() => {
-    if (!visible || current === undefined) {
-      loadAllAbortRef.current?.abort()
-      loadAllAbortRef.current = null
-      loadingAllSessionRef.current = null
-      setLoadingAll(false)
-      setMoreAvailable(false)
-      return
-    }
-    if (loadingAllSessionRef.current === current) return
-    loadingAllSessionRef.current = current
-    const controller = new AbortController()
-    loadAllAbortRef.current = controller
-    setLoadingAll(true)
-    setMoreAvailable(false)
-    props.loadAllOlder(current, { signal: controller.signal })
-      .then((result) => {
-        // Budget exhausted but more history still exists: offer "load earlier".
-        setMoreAvailable(result.code === 'BUDGET' && !result.ok)
-      })
-      .finally(() => {
-        setLoadingAll(false)
-        if (loadAllAbortRef.current === controller) loadAllAbortRef.current = null
-        loadingAllSessionRef.current = null
-      })
-    return () => {
-      controller.abort()
-    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [visible, current, props])
 
   // Listen for jump-failure events and surface the hint.
@@ -190,22 +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) return
-    setMoreAvailable(false)
-    setLoadingAll(true)
-    props.loadAllOlder(current)
-      .then((result) => {
-        setMoreAvailable(result.code === 'BUDGET' && !result.ok)
-      })
-      .finally(() => setLoadingAll(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
@@ -214,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}>{loadingAll ? 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}
-              {loadingAll ? <span className={styles.countLoading}>{t('strip.loadingSuffix')}</span> : null}
-            </span>
-            {moreAvailable && !loadingAll ? (
-              <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>
@@ -254,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,10 +3,16 @@
  *
  * 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.
+ * 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 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.
@@ -17,11 +23,10 @@ import type { SessionId } from '@deepseek-ai/dsh-client-connection/client'
 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 { loadAllOlder, type LoadAllOptions, type LoadAllResult } from '../core/load-all.ts'
 
 /** Locale namespace this plugin owns. */
 const NS = 'question-nav'
@@ -84,52 +89,20 @@ 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]')
-}
-
 /**
- * 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.
+ * 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 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] {
+function questionProjectionOf(ctx: ClientContext, sessionId: SessionId): ObservableFace | undefined {
+  const face = ctx.sessions.binding(sessionId)?.session.projections.faceOf('questionIndex')
+  if (face === undefined) 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)),
+    getSnapshot: () => face.getSnapshot(),
+    subscribe: (listener) => face.subscribe(listener),
   }
 }
 
-/** 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)
-}
-
 function createInject(ctx: ClientContext): QuestionNavInjected {
   return {
     readQuestions: (sessionId) => {
@@ -143,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) => {
@@ -152,7 +126,6 @@ function createInject(ctx: ClientContext): QuestionNavInjected {
       }
       void jumpToQuestion(ports, key)
     },
-    loadAllOlder: (sessionId, options) => loadAllFor(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/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)
+}