@luziyang2026/dsh-question-nav 0.2.0 → 0.4.0

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)
+  })
+}

package/src/projection.ts

@@ -0,0 +1,98 @@
+/**
+ * The `questionIndex` session projection unit: a pure fold of the session
+ * event log into the ordered list of user questions, each tagged with the
+ * turn that claimed it. Registered on `ctx.sessionProjections` by the host
+ * half (src/index.ts); persistence, replay, and client delivery are the
+ * projection seam's (session-projection-cache checkpoints the state, the
+ * api-proxy carriers seed + push the wire view).
+ *
+ * Fold rules mirror the chat messageDefinition classification: an
+ * append-origin `user/message` with a human (`user`) source is a question;
+ * replacement copies (compaction checkpoints) and injected context are not.
+ * Turns come from `turn/start` boundaries, so retry/goal-continuation turns
+ * without a question simply produce no entry — dots may skip turn numbers,
+ * staying exactly aligned with the Trajectory view's turn labels.
+ *
+ * @module dsh-question-nav/projection
+ */
+
+import { z } from 'zod'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import type { QuestionEntry } from './core/question-entry.ts'
+
+/** Fold state: the last opened turn plus every question recorded so far. */
+export interface QuestionIndexState {
+  /** Turn of the last `turn/start` (0 before any; turns are 1-based). */
+  turn: number
+  /** Every recorded question, in event order. */
+  questions: QuestionEntry[]
+}
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    questionIndex: QuestionEntry[]
+  }
+  interface SessionProjectionStateMap {
+    questionIndex: QuestionIndexState
+  }
+}
+
+const questionEntrySchema = z.object({
+  turn: z.number().int().nonnegative(),
+  id: z.string(),
+  seq: z.number().int().nonnegative(),
+  time: z.number().nonnegative(),
+  text: z.string(),
+}).strict()
+
+/** Validates persisted rows after their `ver` gate (the unit's input boundary). */
+const questionIndexStateSchema = z.object({
+  turn: z.number().int().nonnegative(),
+  questions: z.array(questionEntrySchema),
+}).strict()
+
+/** Validates the wire payload before it leaves the host. */
+const questionIndexViewSchema = z.array(questionEntrySchema)
+
+/** First text block of a user message; empty string when absent. */
+function messageText(content: readonly { type?: string; text?: string }[] | undefined): string {
+  if (content === undefined || content.length === 0) return ''
+  const first = content[0]
+  return typeof first?.text === 'string' ? first.text : ''
+}
+
+/** The `questionIndex` unit registered on `ctx.sessionProjections`. */
+export const questionIndexProjectionDefinition: Omit<ProjectionDefinition<'questionIndex', QuestionIndexState>, 'wire'> & {
+  wire: NonNullable<ProjectionDefinition<'questionIndex', QuestionIndexState>['wire']>
+} = {
+  key: 'questionIndex',
+  stateVersion: 1,
+  stateSchema: questionIndexStateSchema,
+  init: () => ({ turn: 0, questions: [] }),
+  apply: (state, event) => {
+    // Every uninteresting event returns the same reference (Object.is gates
+    // the change feed and the persisted-cache dirty check).
+    switch (event.type) {
+      case 'turn/start':
+        return event.data.turn === state.turn ? state : { ...state, turn: event.data.turn }
+      case 'user/message': {
+        if (event.surfaceOp !== 'append') return state
+        if (event.data.source?.kind !== 'user') return state
+        const entry: QuestionEntry = {
+          turn: state.turn,
+          id: String(event.data.id),
+          seq: event.seq,
+          time: event.time,
+          text: messageText(event.data.content),
+        }
+        return { ...state, questions: [...state.questions, entry] }
+      }
+      default:
+        return state
+    }
+  },
+  wire: {
+    viewSchema: questionIndexViewSchema,
+    view: state => state.questions,
+  },
+}

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
-  }
-}