@luziyang2026/dsh-question-nav 0.7.2 → 0.7.4

package/lib/types/client/settings.d.ts

@@ -1,28 +1,32 @@
 /**
  * Browser mirror of the `question-nav` settings namespace: reads the rail
- * anchor edge from the settings scope (`ctx.settingsScope.bind`) and routes
- * the user's choice back through `scope.set`. The namespace itself is
- * registered by the host half (src/settings.ts).
+ * anchor edge and the ▲/▼ page size from the settings scope
+ * (`ctx.settingsScope.bind`) and routes the user's choices back through
+ * `scope.set`. The namespace itself is registered by the host half
+ * (src/settings.ts).
  *
  * The settings surface is optional and may apply after this plugin, so the
- * controller starts unbound and degrades to the default alignment until
- * {@link attach} binds the scope (called from a fiber that injects
- * `settingsScope`). The plugin keeps working everywhere it already did.
+ * controller starts unbound and degrades to the defaults until {@link attach}
+ * binds the scope (called from a fiber that injects `settingsScope`). The
+ * plugin keeps working everywhere it already did.
  *
  * @module dsh-question-nav/client/settings
  */
 import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client';
 import { type AlignPreference } from '../core/align.ts';
+import { type PageSize } from '../core/page-size.ts';
 /** The minimal face of the settings scope service this controller needs.
  * Kept structural (bind only) so the controller stays decoupled from the
  * full service and is unit-testable with a stub binder. */
 export interface SettingsScopeBinderLike {
     bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>;
 }
-/** Snapshot consumed by the strip and the settings row. */
+/** Snapshot consumed by the strip and the settings rows. */
 export interface QuestionNavSettingsState {
     /** Last accepted anchor edge (default while the scope is absent/loading). */
     align: AlignPreference;
+    /** Last accepted page size (default while the scope is absent/loading). */
+    pageSize: PageSize;
     /** Whether the user layer overrides the composition default. */
     overridden: boolean;
 }
@@ -49,4 +53,6 @@ export declare class QuestionNavSettingsController {
     subscribe(listener: () => void): () => void;
     /** Route the user's anchor-edge choice to the Host document. */
     setAlign(align: AlignPreference): void;
+    /** Route the user's page-size choice to the Host document. */
+    setPageSize(pageSize: PageSize): void;
 }

package/lib/types/core/focus.d.ts

@@ -42,24 +42,11 @@ export declare function focusCardMetrics(distance: number): FocusCardMetrics | n
  * of range.
  */
 export declare function magnificationWindow(total: number, selected: number, radius?: number): number[];
-/** Clearance (px) kept around the focused dot when scrolling it into view, so
- *  its two magnified neighbors on each side stay inside the band's clear area
- *  (2 dot rows ≈ 28px + the 22px fade zone). */
-export declare const FOCUS_NEIGHBOR_CLEARANCE = 50;
-/**
- * Minimal "scroll into view" for the focused dot, in the spirit of
- * scrollIntoView({ block: 'nearest' }): returns the scrollTop that brings the
- * dot — plus `clearance` room for its magnified neighbors — inside the
- * visible band with the smallest possible movement, or null when the dot is
- * already fully visible. Unlike unconditional centering this never shifts the
- * band while the user browses dot-by-dot: only a clipped dot is scrolled.
- */
-export declare function minimalScrollIntoView(scrollTop: number, clientHeight: number, scrollHeight: number, dotTop: number, dotHeight: number, clearance?: number): number | null;
 /**
  * Paging model for the dot band. Overflowing dots are not auto-scrolled by
- * hovering the edges: instead the user pages them with two triangle buttons
- * (▲ above the dot queue, ▼ below it), each click revealing `DOT_PAGE_ROWS`
- * hidden dots. Pure arithmetic — no React, no DOM.
+ * hovering the edges or hovering a clipped dot: instead the user pages them
+ * with two triangle buttons (▲ above the dot queue, ▼ below it), each click
+ * revealing `DOT_PAGE_ROWS` hidden dots. Pure arithmetic — no React, no DOM.
  */
 /** How many hidden dots one click of a paging triangle reveals. */
 export declare const DOT_PAGE_ROWS = 5;

package/lib/types/core/page-size.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Page-size constants for the ▲/▼ paging buttons, shared by the host schema
+ * and the browser settings scope. Pure data: no DSH imports, so the client
+ * bundle may inline this module (a Host import here would leak into the
+ * browser half).
+ *
+ * @module dsh-question-nav/page-size
+ */
+/** Selectable page sizes: how many hidden dots one ▲/▼ click reveals. */
+export declare const PAGE_SIZE_OPTIONS: readonly [3, 5, 8, 10];
+/** Page-size preference (dots revealed per paging-button click). */
+export type PageSize = typeof PAGE_SIZE_OPTIONS[number];
+/** Default page size when the user-settings document has no override. */
+export declare const DEFAULT_PAGE_SIZE: PageSize;
+/** Field carrying the selected page size. */
+export declare const PAGE_SIZE_FIELD = "pageSize";

package/lib/types/settings.d.ts

@@ -1,19 +1,23 @@
 /**
  * Host-side durable settings for the question-nav plugin, registered into the
- * DSH user-settings document. Currently one field: which edge of the
- * conversation column the rail anchors to (`align`). The browser half reads
- * the same namespace through the settings scope (`ctx.settingsScope.bind`)
- * and routes the user's choice back through `scope.set`.
+ * DSH user-settings document. Two fields: which edge of the conversation
+ * column the rail anchors to (`align`) and how many hidden dots one ▲/▼
+ * paging-button click reveals (`pageSize`). The browser half reads the same
+ * namespace through the settings scope (`ctx.settingsScope.bind`) and routes
+ * the user's choice back through `scope.set`.
  *
  * @module dsh-question-nav/settings
  */
 import z from '@deepseek-ai/schemastery';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import { type AlignPreference } from './core/align.ts';
+import { type PageSize } from './core/page-size.ts';
 /** Durable settings section shared by the Host schema and the browser scope. */
 export interface QuestionNavSettings {
     /** Anchor edge of the rail. */
     align: AlignPreference;
+    /** Dots revealed per ▲/▼ paging-button click. */
+    pageSize: PageSize;
 }
 /** Durable settings schema; also the wire envelope the browser scope validates against. */
 export declare const QuestionNavSettingsSchema: z<QuestionNavSettings>;

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 edge of the conversation column (left or right, configurable in settings), one dot per user question — hovering focuses a magnified window and a vertical cascade of crisp question cards showing the full text and sent time of each (any card is clickable), click jumps to that message.",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {

package/src/client/QuestionNavSettingsTab.tsx

@@ -1,9 +1,10 @@
 /**
  * The plugin's settings page inside the shell's Plugins section
- * (`settings.plugins.tab`): a segmented control choosing which edge of the
- * conversation column the dot rail anchors to. The choice is written to the
+ * (`settings.plugins.tab`): two segmented controls — which edge of the
+ * conversation column the dot rail anchors to, and how many hidden dots one
+ * ▲/▼ paging-button click reveals. The choices are written to the
  * `question-nav` settings namespace (registered by the host half); the strip
- * re-anchors live when the snapshot changes.
+ * re-anchors and re-steps live when the snapshot changes.
  *
  * @module dsh-question-nav/client/settings-tab
  */
@@ -13,6 +14,7 @@ import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots
 // Type-only: pulls the settings shell's SlotMap merge ('settings.plugins.tab').
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 import { ALIGN_OPTIONS } from '../core/align.ts'
+import { PAGE_SIZE_OPTIONS } from '../core/page-size.ts'
 import type { QuestionNavInjected } from './QuestionNavStrip.tsx'
 import type { QuestionNavKey } from './locales.ts'
 import styles from './question-nav.module.css'
@@ -20,14 +22,15 @@ import styles from './question-nav.module.css'
 type ComponentProps = PropsRuntime<'settings.plugins.tab'> & QuestionNavInjected & PropsLocale<'question-nav'>
 
 /** Re-render on settings snapshot changes (the register inject face is static). */
-function useAlignTick(subscribe: QuestionNavInjected['subscribeAlign']): void {
+function useSettingsTick(subscribe: QuestionNavInjected['subscribeSettings']): void {
   const [, bump] = useState(0)
   useEffect(() => subscribe(() => bump((n) => n + 1)), [subscribe])
 }
 
 export function QuestionNavSettingsTab(props: ComponentProps): React.JSX.Element | null {
-  useAlignTick(props.subscribeAlign)
+  useSettingsTick(props.subscribeSettings)
   const align = props.align()
+  const pageSize = props.pageSize()
   const t = props.t
 
   return (
@@ -48,6 +51,22 @@ export function QuestionNavSettingsTab(props: ComponentProps): React.JSX.Element
           </button>
         ))}
       </div>
+      <p className={styles.settingsTitle}>{t('settings.pagesize.title')}</p>
+      <p className={styles.settingsDesc}>{t('settings.pagesize.desc')}</p>
+      <div className={styles.segmented} role="radiogroup" aria-label={t('settings.pagesize.title')}>
+        {PAGE_SIZE_OPTIONS.map((option) => (
+          <button
+            key={option}
+            type="button"
+            role="radio"
+            aria-checked={pageSize === option}
+            className={pageSize === option ? `${styles.segment} ${styles.segmentActive}` : styles.segment}
+            onClick={() => props.setPageSize(option)}
+          >
+            {option}
+          </button>
+        ))}
+      </div>
     </div>
   )
 }

package/src/client/QuestionNavStrip.tsx

@@ -12,13 +12,16 @@
  * 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 scrolls the
- * selected dot into view only when it is clipped by the band's edges.
+ * jumps to its question, exactly like clicking the dot. Hovering never scrolls
+ * the band — the dot column stays put while you browse.
  *
  * Overflow is paged, not auto-scrolled: two small triangle buttons in the dot
- * style sit above and below the dot queue (▲ / ▼), each click revealing five
- * hidden dots. The native scrollbar stays hidden and the column fades at its
- * edges as a pure visual cue — no hover auto-scroll.
+ * style sit above and below the dot queue (▲ / ▼), each click revealing one
+ * page of hidden dots (the page size is configurable in the plugin settings,
+ * default 5) with a staggered pop-in animation as click feedback. The native
+ * scrollbar stays hidden; the triangles themselves are the overflow cue (each
+ * appears only while its direction has more to reveal) — no hover auto-scroll
+ * of any kind.
  *
  * Data source: the host-folded `questionIndex` session projection (whole
  * history, persisted host-side, pushed live through session/projection
@@ -41,8 +44,9 @@ 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 { AlignPreference } from '../core/align.ts'
+import type { PageSize } from '../core/page-size.ts'
 import type { JumpFailureCode } from '../core/jump.ts'
-import { FOCUS_RADIUS, clampScrollTop, focusCardMetrics, focusScale, focusTier, minimalScrollIntoView, pageStep } from '../core/focus.ts'
+import { DOT_GAP, DOT_SIZE, FOCUS_RADIUS, clampScrollTop, focusCardMetrics, focusScale, focusTier, pageStep } from '../core/focus.ts'
 import { formatQuestionTime } from '../core/time.ts'
 import type { QuestionNavKey } from './locales.ts'
 import styles from './question-nav.module.css'
@@ -69,10 +73,14 @@ export interface QuestionNavInjected {
   jump: (sessionId: SessionId, key: string) => void
   /** Current rail anchor edge (defaults to 'left' before the settings section is ready). */
   align: () => AlignPreference
-  /** Observe anchor-edge changes; returns an unsubscribe. */
-  subscribeAlign: (cb: () => void) => () => void
+  /** Observe plugin-settings changes (align, page size); returns an unsubscribe. */
+  subscribeSettings: (cb: () => void) => () => void
   /** Persist a new anchor edge. */
   setAlign: (align: AlignPreference) => void
+  /** Current ▲/▼ page size (defaults to DEFAULT_PAGE_SIZE before the settings section is ready). */
+  pageSize: () => PageSize
+  /** Persist a new page size. */
+  setPageSize: (pageSize: PageSize) => void
 }
 
 type ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>
@@ -146,6 +154,8 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   const [hint, setHint] = useState<string | null>(null)
   const [focus, setFocus] = useState<FocusState | null>(null)
   const [align, setAlign] = useState<AlignPreference>(() => props.align())
+  // Dots revealed per ▲/▼ click (settings scope; drives pageBy's step).
+  const [pageSize, setPageSize] = useState<PageSize>(() => props.pageSize())
   const panelRef = useRef<HTMLDivElement | null>(null)
   const listRef = useRef<HTMLDivElement | null>(null)
   const hintTimerRef = useRef<number | null>(null)
@@ -154,14 +164,17 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   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 ▲/▼ paging buttons).
+  // Whether the dot band overflows its 60% clamp (drives the ▲/▼ paging
+  // buttons).
   const [scrollable, setScrollable] = useState(false)
   // Scroll offset of the band + its max offset: drives the ▲/▼ visibility
   // (each direction hides once there is nothing more to reveal).
   const [scrollPos, setScrollPos] = useState<{ top: number; max: number }>({ top: 0, max: 0 })
+  // Dots revealed by the latest ▲/▼ click: key → stagger order + travel
+  // direction. Drives a short staggered pop-in animation so the click has a
+  // visible effect; cleared by a timer once the animation has played out.
+  const [revealed, setRevealed] = useState<ReadonlyMap<string, { dir: 1 | -1; order: number }> | null>(null)
+  const revealTimerRef = useRef<number | null>(null)
 
   const syncScroll = (): void => {
     const list = listRef.current
@@ -170,13 +183,45 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     setScrollPos({ top: list.scrollTop, max })
   }
 
-  // Page the band by one DOT_PAGE_ROWS click in the given direction.
+  // Page the band by one DOT_PAGE_ROWS click in the given direction, then mark
+  // the dots the page just brought into view so they play a staggered pop-in
+  // animation in the direction of travel (▼ → rise from below, ▲ → drop from
+  // above) — the visual confirmation that the click revealed new dots.
   const pageBy = (dir: 1 | -1): void => {
     const list = listRef.current
     if (list === null) return
     const max = Math.max(0, list.scrollHeight - list.clientHeight)
-    list.scrollTop = clampScrollTop(list.scrollTop + dir * pageStep(), max)
+    const target = clampScrollTop(list.scrollTop + dir * pageStep(DOT_SIZE, DOT_GAP, pageSize), max)
+    if (target === list.scrollTop) return
+    // Snapshot which dots are geometrically inside the band before the jump
+    // (the container rect does not move when its content scrolls).
+    const band = list.getBoundingClientRect()
+    const els = Array.from(list.querySelectorAll<HTMLElement>('[data-question-nav-key]'))
+    const wasVisible = els.map((el) => {
+      const r = el.getBoundingClientRect()
+      return r.bottom > band.top && r.top < band.bottom
+    })
+    list.scrollTop = target
     syncScroll()
+    const next = new Map<string, { dir: 1 | -1; order: number }>()
+    const fresh: string[] = []
+    els.forEach((el, i) => {
+      if (wasVisible[i]) return
+      const r = el.getBoundingClientRect()
+      const key = el.dataset.questionNavKey
+      if (key !== undefined && r.bottom > band.top && r.top < band.bottom) {
+        fresh.push(key)
+      }
+    })
+    // Stagger radiates from the clicked triangle: paging down (▼) starts at
+    // the bottom of the fresh batch, paging up (▲) at the top.
+    if (dir === 1) fresh.reverse()
+    fresh.forEach((key, order) => next.set(key, { dir, order }))
+    if (next.size === 0) return
+    setRevealed(next)
+    if (revealTimerRef.current !== null) window.clearTimeout(revealTimerRef.current)
+    // Animation (320ms) + per-dot stagger (35ms each) + slack.
+    revealTimerRef.current = window.setTimeout(() => setRevealed(null), 320 + next.size * 35 + 120)
   }
 
   const canPageUp = scrollable && scrollPos.top > 0
@@ -196,9 +241,13 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     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).
-  useEffect(() => props.subscribeAlign(() => setAlign(props.align())), [props])
+  // Follow the plugin settings from the settings scope (an align change
+  // re-anchors the rail through the layout effect below; a page-size change
+  // steps the ▲/▼ paging).
+  useEffect(() => props.subscribeSettings(() => {
+    setAlign(props.align())
+    setPageSize(props.pageSize())
+  }), [props])
 
   const showHint = (message: string): void => {
     setHint(message)
@@ -357,34 +406,9 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     }
   }, [visible, align])
 
-  // Keep the focused dot visible inside the (≤60% tall, scrollable) band:
-  // scroll only when the dot (plus room for its two magnified neighbors) is
-  // clipped by the band edges, and then only by the minimal amount — never
-  // re-center an already-visible dot, so browsing dot-by-dot doesn't shift
-  // the band under the pointer.
-  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 next = minimalScrollIntoView(
-      list.scrollTop,
-      list.clientHeight,
-      list.scrollHeight,
-      target.offsetTop - list.offsetTop,
-      target.offsetHeight,
-    )
-    if (next !== null) list.scrollTop = next
-    syncScroll()
-  }, [focus])
-
-  // Detect band overflow: drives the edge-fade mask + the ▲/▼ paging buttons.
-  // Re-checked when the dots change and whenever the band itself resizes
-  // (the layout loop above clamps it to the conversation height).
+  // Detect band overflow: drives the ▲/▼ paging buttons. 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
@@ -403,6 +427,7 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   useEffect(() => () => {
     if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)
     if (clearFocusTimerRef.current !== null) window.clearTimeout(clearFocusTimerRef.current)
+    if (revealTimerRef.current !== null) window.clearTimeout(revealTimerRef.current)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
@@ -463,7 +488,7 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
             ) : null}
             <div
               ref={listRef}
-              className={scrollable ? `${styles.list} ${styles.listScrollable}` : styles.list}
+              className={styles.list}
               onScroll={syncScroll}
               onMouseLeave={scheduleClearFocus}
             >
@@ -474,16 +499,26 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
                   // 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
+                  // Click-paging feedback: dots just paged into view play a
+                  // staggered pop-in, traveling in the paging direction.
+                  const reveal = revealed?.get(dot.key)
                   const cls = [styles.dot]
                   if (isFocused) cls.push(styles.focused)
                   if (jumpingKey === dot.key) cls.push(styles.active)
+                  if (reveal !== undefined) {
+                    cls.push(reveal.dir === 1 ? styles.dotEnterFromBottom : styles.dotEnterFromTop)
+                  }
                   return (
                     <button
                       key={dot.key}
                       className={cls.join(' ')}
-                      style={{ transform: `scale(${scale})` }}
+                      style={{
+                        transform: `scale(${scale})`,
+                        ...(reveal !== undefined ? { animationDelay: `${reveal.order * 35}ms` } : {}),
+                      }}
                       data-question-nav-focused={isFocused ? 'true' : undefined}
                       data-question-nav-index={index}
+                      data-question-nav-key={dot.key}
                       aria-label={dot.texts[0] ?? ''}
                       onMouseEnter={(e) => openFocus(dot, e.currentTarget)}
                       onClick={() => onJump(dot)}

package/src/client/index.ts

@@ -133,8 +133,10 @@ function createInject(ctx: ClientContext, settings: QuestionNavSettingsControlle
       void jumpToQuestion(ports, key)
     },
     align: () => settings.getSnapshot().align,
-    subscribeAlign: (cb) => settings.subscribe(cb),
+    subscribeSettings: (cb) => settings.subscribe(cb),
     setAlign: (align) => settings.setAlign(align),
+    pageSize: () => settings.getSnapshot().pageSize,
+    setPageSize: (pageSize) => settings.setPageSize(pageSize),
   }
 }
 

package/src/client/locales.ts

@@ -4,8 +4,8 @@
  */
 export const zh = {
   'strip.empty': '本会话还没有提问',
-  'strip.up': '向上翻出 5 个提问圆点',
-  'strip.down': '向下翻出 5 个提问圆点',
+  'strip.up': '向上翻出更多提问圆点',
+  'strip.down': '向下翻出更多提问圆点',
   'jump.inactive': '聊天视图未激活',
   'jump.hidden': '目标无独立气泡，已定位到邻近内容',
   'jump.notfound': '目标未加载或不存在（可能已压缩）',
@@ -15,12 +15,14 @@ export const zh = {
   'settings.align.desc': '选择圆点导航条锚定在对话栏的哪一侧。',
   'settings.align.left': '左侧',
   'settings.align.right': '右侧',
+  'settings.pagesize.title': '每次翻出数量',
+  'settings.pagesize.desc': '点击 ▲/▼ 三角按钮时，每次翻出的隐藏圆点数量。',
 } as const
 
 export const en = {
   'strip.empty': 'No questions in this session yet',
-  'strip.up': 'Reveal 5 question dots above',
-  'strip.down': 'Reveal 5 question dots below',
+  'strip.up': 'Reveal more question dots above',
+  'strip.down': 'Reveal more question dots below',
   '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)',
@@ -30,6 +32,8 @@ export const en = {
   'settings.align.desc': 'Choose which edge of the conversation column the dot rail anchors to.',
   'settings.align.left': 'Left',
   'settings.align.right': 'Right',
+  'settings.pagesize.title': 'Dots per page',
+  'settings.pagesize.desc': 'How many hidden dots one click of the ▲/▼ paging buttons reveals.',
 } as const
 
 export type QuestionNavKey = keyof typeof zh

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

@@ -22,11 +22,10 @@
 }
 
 /* The paging queue: the fixed column (count + ▲, then the scrollable dot band,
-   then ▼) that replaces the edge-fade auto-scroll. Clamped to 60% of the
-   conversation height and vertically centered (auto margins); when the queue
-   overflows, only the middle dot band scrolls — the count and triangles stay
-   pinned. The wrapper stays pass-through; the band and triangles re-enable
-   pointer events. */
+   then ▼). Clamped to 60% of the conversation height and vertically centered
+   (auto margins); when the queue overflows, only the middle dot band scrolls
+   — the count and triangles stay pinned. The wrapper stays pass-through; the
+   band and triangles re-enable pointer events. */
 .queue {
   flex: 0 1 auto;
   min-height: 0;
@@ -44,7 +43,8 @@
 /* The middle dot band: the only scrollable part of the queue. Scrolls from the
    top (overflow collapses the auto margins to 0). The native scrollbar is
    always hidden: this is a minimap paged by the ▲/▼ buttons and by
-   wheel/trackpad, and overflow is signalled by the edge fade below. */
+   wheel/trackpad, and overflow is signalled by the ▲/▼ triangles themselves
+   (each appears only while its direction has more dots to reveal). */
 .list {
   flex: 1 1 auto;
   min-height: 0;
@@ -64,13 +64,6 @@
   height: 0;
   display: none;
 }
-/* Overflowing band (applied from JS when scrollHeight > clientHeight): dots
-   fade out towards both edges — a pure visual cue for "more beyond" (the
-   paging triangles do the actual scrolling). */
-.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);
-}
 
 .dot {
   flex: none;
@@ -96,6 +89,50 @@
   background: var(--dsw-alias-brand-primary);
 }
 
+/* Click-paging feedback: dots revealed by a ▲/▼ click pop in with a staggered
+   fade + rise/drop (per-dot animation-delay is set inline, stagger order *
+   35ms), traveling in the paging direction so the newly revealed batch reads
+   as "the click brought these in". `both` fill holds the hidden `from` state
+   during each dot's delay. */
+@keyframes dotEnterFromBottom {
+  from {
+    opacity: 0;
+    transform: translateY(7px) scale(0.4);
+  }
+  60% {
+    opacity: 1;
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+@keyframes dotEnterFromTop {
+  from {
+    opacity: 0;
+    transform: translateY(-7px) scale(0.4);
+  }
+  60% {
+    opacity: 1;
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+.dotEnterFromBottom {
+  animation: dotEnterFromBottom 320ms cubic-bezier(0.2, 0.9, 0.3, 1.2) both;
+}
+.dotEnterFromTop {
+  animation: dotEnterFromTop 320ms cubic-bezier(0.2, 0.9, 0.3, 1.2) both;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dotEnterFromBottom,
+  .dotEnterFromTop {
+    animation: none;
+  }
+}
+
 /* Question count, rendered just above the first dot (sits in the list gap). */
 .count {
   flex: none;
@@ -169,7 +206,7 @@
   position: fixed;
   z-index: 30;
   max-width: 260px;
-  background: var(--dsw-alias-bg-layer-2);
+  background: var(--dsw-alias-bg-layer-3);
   border: 1px solid var(--dsw-alias-border-l1);
   border-radius: 6px;
   padding: 6px 10px;
@@ -196,11 +233,14 @@
 /* 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. */
+   The surface is the theme's TOP elevation layer (bg-layer-3, the same token
+   DSH menus and popups use): these cards float above the conversation, and in
+   dark themes the layer ramp gives them the raised-surface tint. 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);
+  background: var(--dsw-alias-bg-layer-3);
   border: 1px solid var(--dsw-alias-border-l2);
   border-radius: 10px;
   padding: 8px 12px 10px;
@@ -291,6 +331,10 @@
   color: var(--dsw-alias-label-primary);
   margin: 0;
 }
+/* Separate consecutive setting groups (align, then page size). */
+.segmented + .settingsTitle {
+  margin-top: 12px;
+}
 .settingsDesc {
   font-size: 12px;
   line-height: 18px;