@luziyang2026/dsh-question-nav 0.5.0 → 0.6.0

package/src/client/QuestionNavStrip.tsx

@@ -1,12 +1,18 @@
 /**
  * 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 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.
+ * `shell.overlay` floating layer): 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). The dot column is vertically
+ * centered and clamped to at most 60% of the conversation height, scrolling
+ * within that band when the session has more dots than fit.
+ *
+ * Hovering a dot "selects" it: the selected dot plus its two immediate
+ * neighbors on each side magnify (progressively smaller with distance), the
+ * selected dot reveals a frosted question card (turn label, full question
+ * text, sent time) with a decorative stack of blurred cards fanning out
+ * below it, and the rail auto-centers the selected dot. Clicking jumps the
+ * chat to that turn's first question.
  *
  * Data source: the host-folded `questionIndex` session projection (whole
  * history, persisted host-side, pushed live through session/projection
@@ -30,6 +36,8 @@ import type { QuestionEntry } from '../core/question-entry.ts'
 import { groupQuestionsByTurn, mergeLiveQuestions, type TurnDot } from '../core/turn-dots.ts'
 import type { AlignPreference } from '../core/align.ts'
 import type { JumpFailureCode } from '../core/jump.ts'
+import { FOCUS_RADIUS, focusCardMetrics, focusScale, focusTier } from '../core/focus.ts'
+import { formatQuestionTime } from '../core/time.ts'
 import type { QuestionNavKey } from './locales.ts'
 import styles from './question-nav.module.css'
 
@@ -70,16 +78,25 @@ const FAILURE_HINTS: Record<JumpFailureCode, QuestionNavKey> = {
   TIMEOUT: 'jump.timeout',
 }
 
-/** Live position of the instant hover tooltip. */
-interface TooltipState {
-  /** 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[]
+/** One card of the focus cascade: a dot inside the magnification window. */
+interface FocusWindowItem {
+  dot: TurnDot
+  /** Distance from the selected dot (0 = selected, 1/2 = cascade neighbors). */
+  distance: number
+}
+
+/** The focus cascade: a vertical column of one card per window dot,
+ *  non-overlapping, centered on the selected dot. */
+interface FocusState {
+  /** The selected (hovered) dot's key. */
+  key: string
+  /** Every dot of the focus window, in dot order. */
+  items: FocusWindowItem[]
+  /** Vertical center (viewport px) of the selected dot — the column centers on it. */
+  centerY: number
   /** Horizontal anchor — left edge (left-aligned rail) or right edge (right-aligned). */
   left?: number
   right?: number
-  top: number
 }
 
 /** Read the projection face value as a question-entry list (structural guard). */
@@ -98,8 +115,8 @@ function findConvRoot(): HTMLElement | null {
 }
 
 /** Structural equality of two dot lists (member keys fully capture a dot's
- * folded questions, so identical key sequences mean identical content).
- * Lets the strip skip a re-render when a refresh produced no change. */
+ *  folded questions, so identical key sequences mean identical content).
+ *  Lets the strip skip a re-render when a refresh produced no change. */
 function sameDots(a: readonly TurnDot[], b: readonly TurnDot[]): boolean {
   if (a.length !== b.length) return false
   for (let i = 0; i < a.length; i++) {
@@ -121,12 +138,32 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   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 [focus, setFocus] = useState<FocusState | null>(null)
   const [align, setAlign] = useState<AlignPreference>(() => props.align())
   const panelRef = useRef<HTMLDivElement | null>(null)
+  const listRef = useRef<HTMLDivElement | null>(null)
   const hintTimerRef = useRef<number | null>(null)
+  // Pending focus-clear timer: lets the mouse move from the rail onto a
+  // cascade card without dropping the cascade mid-flight.
+  const clearFocusTimerRef = useRef<number | null>(null)
   // Last rendered dot list, for the change-detection bail-out below.
   const lastDotsRef = useRef<TurnDot[]>([])
+  // Last focused dot key, so re-hovering the same dot after a gap re-centers it.
+  const lastFocusedKeyRef = useRef<string | null>(null)
+
+  // Focus persists briefly after leaving the rail, so the mouse can reach the
+  // clickable cascade cards; entering a card cancels the clear, leaving
+  // everything re-arms it.
+  const cancelClearFocus = (): void => {
+    if (clearFocusTimerRef.current !== null) {
+      window.clearTimeout(clearFocusTimerRef.current)
+      clearFocusTimerRef.current = null
+    }
+  }
+  const scheduleClearFocus = (): void => {
+    cancelClearFocus()
+    clearFocusTimerRef.current = window.setTimeout(() => setFocus(null), 240)
+  }
 
   // Follow the rail anchor edge from the settings scope (a change re-anchors
   // the rail through the layout effect below).
@@ -289,9 +326,27 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     }
   }, [visible, align])
 
-  // Clear any pending hint timer on unmount.
+  // Keep the focused dot centered in the (≤60% tall, scrollable) band so its
+  // two neighbors on each side stay visible. Re-centers only when the focused
+  // key changes; scrolls instantly to avoid chasing a fast-moving hover.
+  useLayoutEffect(() => {
+    const key = focus?.key ?? null
+    if (lastFocusedKeyRef.current === key) return
+    lastFocusedKeyRef.current = key
+    if (key === null) return
+    const list = listRef.current
+    if (list === null) return
+    const target = list.querySelector<HTMLElement>('[data-question-nav-focused="true"]')
+    if (target === null) return
+    const delta = target.offsetTop - list.offsetTop
+    const center = delta - (list.clientHeight - target.offsetHeight) / 2
+    list.scrollTop = Math.max(0, Math.min(center, list.scrollHeight - list.clientHeight))
+  }, [focus])
+
+  // Clear any pending timers on unmount.
   useEffect(() => () => {
     if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)
+    if (clearFocusTimerRef.current !== null) window.clearTimeout(clearFocusTimerRef.current)
   }, [])
 
   if (!visible) return null
@@ -303,21 +358,28 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     window.setTimeout(() => setJumpingKey((k) => (k === dot.key ? null : k)), 600)
   }
 
-  const openTooltip = (dot: TurnDot, target: HTMLElement): void => {
+  const openFocus = (dot: TurnDot, target: HTMLElement): void => {
+    const index = dots.findIndex((d) => d.key === dot.key)
+    if (index < 0) return
+    cancelClearFocus()
     const r = target.getBoundingClientRect()
-    setTooltip({
-      title: dot.turn === null ? null : `Turn ${dot.turn}`,
-      lines: dot.texts,
-      // The tooltip opens away from the rail: to the right of the dot on a
-      // left-anchored rail, to the left on a right-anchored one.
-      ...(align === 'right'
-        ? { right: window.innerWidth - r.left + 10 }
-        : { left: r.right + 10 }),
-      top: r.top,
-    })
+    // The cascade opens away from the rail: to the right of the dots on a
+    // left-anchored rail, to the left on a right-anchored one. The column is
+    // vertically centered on the selected dot (top: centerY + translateY(-50%)).
+    const horizontal = align === 'right'
+      ? { right: window.innerWidth - r.left + 10 }
+      : { left: r.right + 10 }
+    const lo = Math.max(0, index - FOCUS_RADIUS)
+    const hi = Math.min(dots.length - 1, index + FOCUS_RADIUS)
+    const items: FocusWindowItem[] = []
+    for (let i = lo; i <= hi; i++) {
+      items.push({ dot: dots[i], distance: Math.abs(i - index) })
+    }
+    setFocus({ key: dot.key, items, centerY: r.top + r.height / 2, ...horizontal })
   }
 
   const t = props.t
+  const selectedIndex = focus === null ? -1 : dots.findIndex((d) => d.key === focus.key)
 
   return (
     <div
@@ -325,33 +387,112 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
       className={align === 'right' ? `${styles.rail} ${styles.railRight}` : styles.rail}
       data-question-nav="rail"
     >
-      {hint !== null ? <div className={styles.hint} role="status">{hint}</div> : null}
-      <div className={styles.list}>
+      <div
+        ref={listRef}
+        className={styles.list}
+        onMouseLeave={scheduleClearFocus}
+      >
         {dots.length === 0 ? (
           <div className={styles.empty}>{t('strip.empty')}</div>
         ) : (
           <div className={styles.dots}>
             <span className={styles.count}>{dots.length}</span>
-            {dots.map((dot) => (
-              <button
-                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(dot)}
-              />
-            ))}
+            {dots.map((dot, index) => {
+              const isFocused = focus !== null && focus.key === dot.key
+              // Progressive magnification: selected largest, ±1 smaller, ±2
+              // smaller still, the rest base scale.
+              const tier = selectedIndex < 0 ? null : focusTier(index - selectedIndex)
+              const scale = jumpingKey === dot.key ? 1.6 : tier !== null ? focusScale(tier) : 1
+              const cls = [styles.dot]
+              if (isFocused) cls.push(styles.focused)
+              if (jumpingKey === dot.key) cls.push(styles.active)
+              return (
+                <button
+                  key={dot.key}
+                  className={cls.join(' ')}
+                  style={{ transform: `scale(${scale})` }}
+                  data-question-nav-focused={isFocused ? 'true' : undefined}
+                  data-question-nav-index={index}
+                  aria-label={dot.texts[0] ?? ''}
+                  onMouseEnter={(e) => openFocus(dot, e.currentTarget)}
+                  onClick={() => onJump(dot)}
+                />
+              )
+            })}
           </div>
         )}
       </div>
-      {tooltip !== null
+      {hint !== null
+        ? createPortal(
+            <div
+              className={styles.hint}
+              style={align === 'right' ? { right: 60, top: 20 } : { left: 60, top: 20 }}
+            >
+              {hint}
+            </div>,
+            document.body,
+          )
+        : null}
+      {focus !== null
         ? createPortal(
-            <div className={styles.tooltip} style={{ left: tooltip.left, right: tooltip.right, top: tooltip.top }}>
-              {tooltip.title !== null ? <div className={styles.tooltipTitle}>{tooltip.title}</div> : null}
-              {tooltip.lines.map((line, index) => (
-                <div key={index} className={styles.tooltipLine}>{line}</div>
-              ))}
+            /* The vertical cascade: one crisp card per window dot, stacked
+               non-overlapping, vertically centered on the selected dot.
+               Hovering the cascade keeps it alive (the rail only re-arms its
+               clear once the mouse leaves both). */
+            <div
+              className={styles.cascade}
+              style={{
+                ...(focus.left !== undefined ? { left: focus.left } : {}),
+                ...(focus.right !== undefined ? { right: focus.right } : {}),
+                top: focus.centerY,
+                transform: 'translateY(-50%)',
+              }}
+              onMouseEnter={cancelClearFocus}
+              onMouseLeave={scheduleClearFocus}
+            >
+              {focus.items.map((item) => {
+                const metrics = focusCardMetrics(item.distance)
+                if (metrics === null) return null
+                const isSelected = item.distance === 0
+                // Cascade cards join their dot's texts into one clamped line;
+                // the selected card keeps every line. Every card shows the
+                // question's sent time, and clicking any card jumps to its
+                // question exactly like clicking the dot.
+                const text = item.dot.texts.join(' · ')
+                const cls = isSelected ? `${styles.card} ${styles.cardSelected}` : styles.card
+                return (
+                  <div
+                    key={item.dot.key}
+                    className={cls}
+                    role="button"
+                    tabIndex={-1}
+                    style={{
+                      width: metrics.widthPx,
+                      filter: `brightness(${metrics.brightness})`,
+                    }}
+                    onClick={() => onJump(item.dot)}
+                  >
+                    {isSelected && item.dot.turn !== null ? (
+                      <div className={styles.cardTitle}>Turn {item.dot.turn}</div>
+                    ) : null}
+                    <div
+                      className={isSelected ? styles.cardBody : styles.cardClamp}
+                      style={
+                        isSelected
+                          ? undefined
+                          : ({ WebkitLineClamp: metrics.maxLines, fontSize: metrics.fontSize } as React.CSSProperties)
+                      }
+                    >
+                      {isSelected
+                        ? item.dot.texts.map((line, lineIndex) => (
+                            <div key={lineIndex} className={styles.cardLine}>{line}</div>
+                          ))
+                        : text}
+                    </div>
+                    <div className={styles.cardTime}>{formatQuestionTime(item.dot.time, Date.now())}</div>
+                  </div>
+                )
+              })}
             </div>,
             document.body,
           )

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

@@ -21,11 +21,16 @@
   left: auto;
 }
 
-/* Vertically center the dot column when it is short; scroll from the top when
-   it is tall (auto margins collapse to 0 on overflow, so nothing clips). */
+/* Vertically center the dot column when it is short; when it is tall it is
+   clamped to at most 60% of the conversation height (auto margins center the
+   band) and scrolls from the top (auto margins collapse to 0 on overflow).
+   The band itself is interactive so wheel-scrolling works over the gaps too
+   (the rail above is pointer-events:none). */
 .list {
-  flex: 1;
+  flex: 0 1 auto;
   min-height: 0;
+  max-height: 60%;
+  margin: auto 0;
   width: 100%;
   overflow-y: auto;
   overflow-x: hidden;
@@ -35,6 +40,7 @@
   gap: 6px;
   padding: 8px 0;
   scrollbar-width: thin;
+  pointer-events: auto;
 }
 .list > *:first-child {
   margin-top: auto;
@@ -55,12 +61,15 @@
   cursor: pointer;
   transition: transform 120ms ease, background 120ms ease;
 }
+/* Scale is driven by the focus model through an inline transform; this only
+   colors the hovered (selected) dot instantly, before React applies it. */
 .dot:hover {
-  transform: scale(2);
+  background: var(--dsw-alias-brand-primary);
+}
+.dot.focused {
   background: var(--dsw-alias-brand-primary);
 }
 .dot.active {
-  transform: scale(1.6);
   background: var(--dsw-alias-brand-primary);
 }
 
@@ -91,40 +100,107 @@
   word-break: break-word;
 }
 
-/* Instant hover tooltip (rendered in a portal to document.body, so it is never
-   clipped by the rail's scroll container). */
-.tooltip {
+/* Transient jump-failure hint (portal-rendered near the rail top, so it never
+   pushes the centered dot band or clips in the 44px-wide rail). */
+.hint {
+  position: fixed;
+  z-index: 30;
+  max-width: 260px;
+  background: var(--dsw-alias-bg-layer-2);
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 6px;
+  padding: 6px 10px;
+  font-size: 12px;
+  line-height: 16px;
+  color: var(--dsw-alias-label-secondary);
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.18);
+  pointer-events: none;
+}
+
+/* The vertical focus cascade: one crisp question card per window dot, stacked
+   top-to-bottom without overlap, centered on the selected dot. The container
+   stays pass-through; only the cards are interactive. */
+.cascade {
   position: fixed;
   z-index: 20;
-  max-width: 420px;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 6px;
+  pointer-events: none;
+}
+
+/* One focus question card (portal-rendered in the cascade). Solid, crisp —
+   no blur — with the width set per cascade tier. Clicking jumps to the
+   question, like the dot. */
+.card {
+  width: 380px;
   background: var(--dsw-alias-bg-layer-1);
   border: 1px solid var(--dsw-alias-border-l1);
-  border-radius: 8px;
-  padding: 8px 12px;
+  border-radius: 10px;
+  padding: 8px 12px 10px;
   font-size: 13px;
   line-height: 18px;
   color: var(--dsw-alias-label-primary);
-  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
+  box-shadow: 0 4px 14px rgba(0, 0, 0, 0.18);
   white-space: normal;
   word-break: break-word;
-  pointer-events: none;
+  pointer-events: auto;
+  cursor: pointer;
+  transition: border-color 120ms ease, box-shadow 120ms ease;
+}
+.card:hover {
+  border-color: var(--dsw-alias-brand-primary);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.26);
+}
+
+/* The selected (center) card: marked brighter with a brand edge, so the
+   center card is distinct from the four unselected cascade cards. */
+.cardSelected {
+  border-color: var(--dsw-alias-brand-primary);
 }
 
-/* Turn label line at the top of the tooltip ("Turn 32"). */
-.tooltipTitle {
+/* Turn label line at the top of the card ("Turn 32"). */
+.cardTitle {
   font-size: 11px;
   font-weight: 600;
   color: var(--dsw-alias-label-tertiary);
   margin-bottom: 4px;
 }
 
+/* Question body; long multi-question turns scroll inside the card. */
+.cardBody {
+  max-height: 96px;
+  overflow-y: auto;
+  scrollbar-width: thin;
+}
+
+/* Clamped cascade-card text (the two neighbors on each side): N lines with
+   ellipsis via -webkit-line-clamp (set inline). */
+.cardClamp {
+  font-size: 13px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-primary);
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  word-break: break-word;
+}
+
 /* One question text line; consecutive lines (multi-question turns) separate. */
-.tooltipLine + .tooltipLine {
+.cardLine + .cardLine {
   margin-top: 6px;
   padding-top: 6px;
   border-top: 1px solid var(--dsw-alias-border-l1);
 }
 
+/* Question sent-time line (HH:MM / MM-DD HH:MM / YYYY-MM-DD HH:MM). */
+.cardTime {
+  margin-top: 6px;
+  font-size: 11px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 /* Settings page (settings.plugins.tab). */
 .settings {
   display: flex;

package/src/core/focus.ts

@@ -0,0 +1,76 @@
+/**
+ * Focus-magnification model for the question-nav rail. Pure index/scale math
+ * for the hover-selected dot's neighborhood window, its progressive
+ * magnification tiers, and the vertical cascade of question cards (one per
+ * window dot, non-overlapping, sizes descending away from the selected one).
+ * No React, no DOM — every function here is unit-testable in isolation and
+ * safe to inline into the client bundle.
+ *
+ * @module dsh-question-nav/focus
+ */
+
+/** How many dots stay enlarged on each side of the selected dot. */
+export const FOCUS_RADIUS = 2
+
+/** Magnification scale per tier, by distance from the selected dot
+ * (0 = selected, 1 = immediate neighbor, 2 = outer window edge). */
+export const FOCUS_SCALES = [2.0, 1.55, 1.25] as const
+
+/**
+ * The focus tier of a dot at `distance` from the selected dot: 0..FOCUS_RADIUS
+ * while inside the magnification window, null beyond it (base scale).
+ */
+export function focusTier(distance: number): number | null {
+  const d = Math.abs(distance)
+  if (d > FOCUS_RADIUS) return null
+  return d
+}
+
+/** Magnification scale for a dot at `distance`; 1 (base) outside the window. */
+export function focusScale(distance: number): number {
+  const tier = focusTier(distance)
+  return tier === null ? 1 : FOCUS_SCALES[tier]
+}
+
+/** Presentation metrics for the question card of a dot at `distance` from the
+ *  selected one. Cards stay crisp (no blur): the selected card is the widest,
+ *  brightest and shows every text line; each of its two neighbors on each side
+ *  is a slightly narrower, dimmer card clamped to fewer lines. Null outside
+ *  the window (no card). */
+export interface FocusCardMetrics {
+  /** Card width in px (narrows away from the selected card). */
+  widthPx: number
+  /** Text font size (px); cascade cards are slightly smaller. */
+  fontSize: number
+  /** Max text lines before clamping (cascade cards). */
+  maxLines: number
+  /** Brightness (1 = full, the selected card; dimmer away from it). */
+  brightness: number
+}
+
+export function focusCardMetrics(distance: number): FocusCardMetrics | null {
+  const tier = focusTier(distance)
+  if (tier === null) return null
+  switch (tier) {
+    case 0:
+      return { widthPx: 380, fontSize: 13, maxLines: 6, brightness: 1 }
+    case 1:
+      return { widthPx: 300, fontSize: 12.5, maxLines: 2, brightness: 0.82 }
+    default:
+      return { widthPx: 240, fontSize: 12, maxLines: 1, brightness: 0.68 }
+  }
+}
+
+/**
+ * Indices of the focus window: the selected dot plus `radius` on each side,
+ * clipped to the dot list. Empty when the list is empty or `selected` is out
+ * of range.
+ */
+export function magnificationWindow(total: number, selected: number, radius: number = FOCUS_RADIUS): number[] {
+  if (total <= 0 || selected < 0 || selected >= total || radius < 0) return []
+  const out: number[] = []
+  const lo = Math.max(0, selected - radius)
+  const hi = Math.min(total - 1, selected + radius)
+  for (let i = lo; i <= hi; i++) out.push(i)
+  return out
+}

package/src/core/time.ts

@@ -0,0 +1,39 @@
+/**
+ * Question sent-time formatting for the question-nav surface. Pure: no DSH
+ * imports, deterministic for a given (time, now) pair — unit-testable in
+ * isolation and safe to inline into the client bundle.
+ *
+ * @module dsh-question-nav/time
+ */
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n)
+}
+
+/** Whether `time` falls on the same calendar day as `now`. */
+export function isSameDay(time: number, now: number): boolean {
+  const a = new Date(time)
+  const b = new Date(now)
+  return a.getFullYear() === b.getFullYear()
+    && a.getMonth() === b.getMonth()
+    && a.getDate() === b.getDate()
+}
+
+/**
+ * Smart question sent-time, relative to `now`:
+ * - same calendar day → `HH:MM`
+ * - same calendar year → `MM-DD HH:MM`
+ * - otherwise → `YYYY-MM-DD HH:MM`
+ *
+ * Returns `''` for a missing/invalid timestamp (e.g. a live node that never
+ * reported one), so callers can hide the time line without branching.
+ */
+export function formatQuestionTime(time: number, now: number): string {
+  if (!Number.isFinite(time) || time <= 0) return ''
+  const d = new Date(time)
+  const hm = `${pad2(d.getHours())}:${pad2(d.getMinutes())}`
+  if (isSameDay(time, now)) return hm
+  const md = `${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`
+  if (d.getFullYear() === new Date(now).getFullYear()) return `${md} ${hm}`
+  return `${d.getFullYear()}-${md} ${hm}`
+}