@luziyang2026/dsh-question-nav 0.5.0 → 0.7.0

package/src/client/QuestionNavStrip.tsx

@@ -1,12 +1,19 @@
 /**
  * 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), and a
+ * vertical cascade of question cards opens — the selected (center) card is the
+ * focus (brand accent, elevated, full question text), the four neighbors are
+ * narrower context cards clamped to fewer lines. Every card is clickable and
+ * jumps to its question, exactly like clicking the dot; the rail auto-centers
+ * the selected dot.
  *
  * Data source: the host-folded `questionIndex` session projection (whole
  * history, persisted host-side, pushed live through session/projection
@@ -30,6 +37,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 { EDGE_SCROLL_ZONE, FOCUS_RADIUS, edgeScrollSpeed, 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 +79,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 +116,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 +139,88 @@ 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)
+  // Whether the dot band overflows its 60% clamp (drives the edge-fade mask
+  // and the hover auto-scroll).
+  const [scrollable, setScrollable] = useState(false)
+  // Edge auto-scroll state: the fade zones at the band's top/bottom edges are
+  // scroll affordances — hovering them scrolls the band so the faded dots
+  // flow into the clear area. Speed follows how deep the pointer is inside
+  // the zone; a rAF loop applies it smoothly while it is non-zero.
+  const edgeScrollRef = useRef<{ speed: number; raf: number; last: number }>({ speed: 0, raf: 0, last: 0 })
+
+  const stopEdgeScroll = (): void => {
+    edgeScrollRef.current.speed = 0
+    if (edgeScrollRef.current.raf !== 0) {
+      cancelAnimationFrame(edgeScrollRef.current.raf)
+      edgeScrollRef.current.raf = 0
+    }
+  }
+
+  const edgeTick = (now: number): void => {
+    const list = listRef.current
+    const state = edgeScrollRef.current
+    state.raf = 0
+    if (list === null || state.speed === 0) return
+    const dt = Math.min(64, now - state.last) / 1000
+    state.last = now
+    const before = list.scrollTop
+    list.scrollTop = before + state.speed * dt
+    // Stop at the scroll bounds — there is nothing more to reveal.
+    const atTop = list.scrollTop <= 0 && state.speed < 0
+    const atBottom = list.scrollTop >= list.scrollHeight - list.clientHeight - 1 && state.speed > 0
+    if (atTop || atBottom) {
+      state.speed = 0
+      return
+    }
+    state.raf = requestAnimationFrame(edgeTick)
+  }
+
+  const onListMouseMove = (e: React.MouseEvent<HTMLDivElement>): void => {
+    const list = listRef.current
+    if (list === null) return
+    const rect = list.getBoundingClientRect()
+    const y = e.clientY - rect.top
+    const depthTop = EDGE_SCROLL_ZONE - y
+    const depthBottom = y - (rect.height - EDGE_SCROLL_ZONE)
+    let speed = 0
+    if (depthTop > 0 && list.scrollTop > 0) {
+      speed = -edgeScrollSpeed(depthTop / EDGE_SCROLL_ZONE)
+    } else if (depthBottom > 0 && list.scrollTop < list.scrollHeight - list.clientHeight - 1) {
+      speed = edgeScrollSpeed(depthBottom / EDGE_SCROLL_ZONE)
+    }
+    const state = edgeScrollRef.current
+    state.speed = speed
+    if (speed !== 0 && state.raf === 0) {
+      state.last = performance.now()
+      state.raf = requestAnimationFrame(edgeTick)
+    }
+  }
+
+  // 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 +383,43 @@ 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])
+
+  // Detect band overflow: drives the edge-fade mask + hover auto-scroll.
+  // Re-checked when the dots change and whenever the band itself resizes
+  // (the layout loop above clamps it to the conversation height).
+  useLayoutEffect(() => {
+    const list = listRef.current
+    if (list === null) return
+    const check = (): void => setScrollable(list.scrollHeight > list.clientHeight + 1)
+    check()
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(check)
+    observer.observe(list)
+    return () => observer.disconnect()
+  }, [dots, align])
+
+  // Clear any pending timers and the edge auto-scroll on unmount.
   useEffect(() => () => {
     if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)
+    if (clearFocusTimerRef.current !== null) window.clearTimeout(clearFocusTimerRef.current)
+    stopEdgeScroll()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
   if (!visible) return null
@@ -303,21 +431,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 +460,113 @@ 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={scrollable ? `${styles.list} ${styles.listScrollable}` : styles.list}
+        onMouseMove={scrollable ? onListMouseMove : undefined}
+        onMouseLeave={() => {
+          stopEdgeScroll()
+          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 }}
+                    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,18 @@
   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). The native scrollbar is always
+   hidden: this is a minimap scrolled by wheel/trackpad and by hovering the
+   fade zones, and overflow is signalled by the edge fade below. */
 .list {
-  flex: 1;
+  flex: 0 1 auto;
   min-height: 0;
+  max-height: 60%;
+  margin: auto 0;
   width: 100%;
   overflow-y: auto;
   overflow-x: hidden;
@@ -34,7 +41,20 @@
   align-items: center;
   gap: 6px;
   padding: 8px 0;
-  scrollbar-width: thin;
+  scrollbar-width: none;
+  pointer-events: auto;
+}
+.list::-webkit-scrollbar {
+  width: 0;
+  height: 0;
+  display: none;
+}
+/* Overflowing band (applied from JS when scrollHeight > clientHeight): dots
+   fade out towards both edges, signalling "more beyond" without a scrollbar.
+   The fade zones double as hover auto-scroll areas (see QuestionNavStrip). */
+.listScrollable {
+  -webkit-mask-image: linear-gradient(to bottom, transparent, black 22px, black calc(100% - 22px), transparent);
+  mask-image: linear-gradient(to bottom, transparent, black 22px, black calc(100% - 22px), transparent);
 }
 .list > *:first-child {
   margin-top: auto;
@@ -55,12 +75,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 +114,121 @@
   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). The four context
+   cards use the base style: a clean solid surface, a quiet neutral border and
+   a low shadow — crisp and readable, one visual step behind the focus card.
+   Clicking jumps to the question, like the dot; hover raises the border to
+   signal the card is interactive. */
+.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: 1px solid var(--dsw-alias-border-l2);
+  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);
+  color: var(--dsw-alias-label-secondary);
+  box-shadow: 0 1px 6px rgba(0, 0, 0, 0.10);
   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 3px 12px rgba(0, 0, 0, 0.18);
+  color: var(--dsw-alias-label-primary);
+}
+
+/* The selected (center) card — the focus of the cascade: full-contrast text,
+   a brand left accent bar (inset, so it follows the rounded corners) and a
+   raised shadow lift it above the four context cards. */
+.cardSelected {
+  border-color: var(--dsw-alias-border-l1);
+  color: var(--dsw-alias-label-primary);
+  box-shadow:
+    inset 3px 0 0 0 var(--dsw-alias-brand-primary),
+    0 6px 20px rgba(0, 0, 0, 0.22);
+}
+.cardSelected:hover {
+  border-color: var(--dsw-alias-brand-primary);
+  box-shadow:
+    inset 3px 0 0 0 var(--dsw-alias-brand-primary),
+    0 6px 22px rgba(0, 0, 0, 0.26);
 }
 
-/* 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). Inherits the card's text
+   color (secondary on context cards, primary on the focus card). */
+.cardClamp {
+  font-size: 13px;
+  line-height: 18px;
+  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,96 @@
+/**
+ * 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. The hierarchy is two-tier: the selected card is the focus
+ *  (widest, full text, brand accent — styled via the selected CSS class), the
+ *  four neighbors are context cards (same clean surface, narrower, clamped to
+ *  fewer lines). Cards are never dimmed or blurred: context must stay crisp
+ *  and readable so it can be recognized — and clicked. 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
+}
+
+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 }
+    case 1:
+      return { widthPx: 300, fontSize: 12.5, maxLines: 2 }
+    default:
+      return { widthPx: 240, fontSize: 12, maxLines: 1 }
+  }
+}
+
+/**
+ * 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
+}
+
+/** Height (px) of the dot band's top/bottom fade zones, which double as hover
+ *  auto-scroll areas (slightly larger than the 22px CSS mask fade). */
+export const EDGE_SCROLL_ZONE = 26
+
+/** Edge auto-scroll speed range (px/s): MIN at the zone boundary, MAX at the
+ *  very edge of the band. */
+export const EDGE_SCROLL_MIN_SPEED = 90
+export const EDGE_SCROLL_MAX_SPEED = 420
+
+/**
+ * Auto-scroll speed (px/s) for a pointer at `ratio` depth into an edge fade
+ * zone (0 = at the zone boundary, 1 = at the band's very edge): eases
+ * linearly from MIN to MAX so a shallow probe scrolls gently and pushing
+ * into the edge moves fast. The sign (direction) is applied by the caller.
+ */
+export function edgeScrollSpeed(ratio: number): number {
+  const r = Math.max(0, Math.min(1, ratio))
+  return EDGE_SCROLL_MIN_SPEED + (EDGE_SCROLL_MAX_SPEED - EDGE_SCROLL_MIN_SPEED) * r
+}