@luziyang2026/dsh-question-nav 0.4.1 → 0.5.0

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

@@ -0,0 +1,14 @@
+/**
+ * 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
+ * `question-nav` settings namespace (registered by the host half); the strip
+ * re-anchors live when the snapshot changes.
+ *
+ * @module dsh-question-nav/client/settings-tab
+ */
+import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { QuestionNavInjected } from './QuestionNavStrip.tsx';
+type ComponentProps = PropsRuntime<'settings.plugins.tab'> & QuestionNavInjected & PropsLocale<'question-nav'>;
+export declare function QuestionNavSettingsTab(props: ComponentProps): React.JSX.Element | null;
+export {};

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

@@ -1,6 +1,7 @@
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
 import type { QuestionNode } from '../core/nodes.ts';
+import type { AlignPreference } from '../core/align.ts';
 /** Minimal observable shape of a session projection face. */
 export interface ObservableFace {
     /** Current projection value (unknown — validated structurally at read). */
@@ -20,6 +21,12 @@ export interface QuestionNavInjected {
     questionProjection: (sessionId: SessionId) => ObservableFace | undefined;
     /** Jump the chat to a question row (pages the window on demand). */
     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;
+    /** Persist a new anchor edge. */
+    setAlign: (align: AlignPreference) => void;
 }
 type ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>;
 export declare function QuestionNavStrip(props: ComponentProps): React.JSX.Element | null;

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

@@ -8,6 +8,11 @@ export declare const zh: {
     readonly 'jump.hidden': "目标无独立气泡，已定位到邻近内容";
     readonly 'jump.notfound': "目标未加载或不存在（可能已压缩）";
     readonly 'jump.timeout': "加载历史超时，可重试";
+    readonly 'settings.tab': "提问导航";
+    readonly 'settings.align.title': "导航条对齐";
+    readonly 'settings.align.desc': "选择圆点导航条锚定在对话栏的哪一侧。";
+    readonly 'settings.align.left': "左侧";
+    readonly 'settings.align.right': "右侧";
 };
 export declare const en: {
     readonly 'strip.empty': "No questions in this session yet";
@@ -15,5 +20,10 @@ export declare const en: {
     readonly 'jump.hidden': "No dedicated bubble; landed on nearby content";
     readonly 'jump.notfound': "Target not loaded or missing (maybe compacted)";
     readonly 'jump.timeout': "Timed out loading history; retry";
+    readonly 'settings.tab': "Question Nav";
+    readonly 'settings.align.title': "Rail alignment";
+    readonly 'settings.align.desc': "Choose which edge of the conversation column the dot rail anchors to.";
+    readonly 'settings.align.left': "Left";
+    readonly 'settings.align.right': "Right";
 };
 export type QuestionNavKey = keyof typeof zh;

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

@@ -0,0 +1,52 @@
+/**
+ * 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).
+ *
+ * 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.
+ *
+ * @module dsh-question-nav/client/settings
+ */
+import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client';
+import { type AlignPreference } from '../core/align.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. */
+export interface QuestionNavSettingsState {
+    /** Last accepted anchor edge (default while the scope is absent/loading). */
+    align: AlignPreference;
+    /** Whether the user layer overrides the composition default. */
+    overridden: boolean;
+}
+/** Reactive handle over the plugin's durable settings section. */
+export declare class QuestionNavSettingsController {
+    private scope;
+    private readonly listeners;
+    private unsubscribe;
+    private state;
+    /**
+     * Bind the namespace scope once the settings surface is present. Called
+     * from a fiber that injects `settingsScope`, so the scope subscription
+     * lives on that fiber and is released with it. A no-op after the first
+     * bind.
+     * @param binder - the settings scope service.
+     */
+    attach(binder: SettingsScopeBinderLike): void;
+    private derive;
+    /** Release the scope subscription (bound on the settings fiber's lifecycle). */
+    dispose(): void;
+    /** @returns the current state (stable reference until the next change). */
+    getSnapshot(): QuestionNavSettingsState;
+    /** Observe state replacements; returns the disposer. */
+    subscribe(listener: () => void): () => void;
+    /** Route the user's anchor-edge choice to the Host document. */
+    setAlign(align: AlignPreference): void;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Rail anchor-edge constants 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/align
+ */
+/** Supported rail anchor edges. */
+export declare const ALIGN_OPTIONS: readonly ["left", "right"];
+/** Rail anchor edge preference. */
+export type AlignPreference = typeof ALIGN_OPTIONS[number];
+/** Default anchor edge when the user-settings document has no override. */
+export declare const DEFAULT_ALIGN: AlignPreference;
+/** Settings namespace owned by this plugin (spelled here rather than
+ * imported: the client bundle must not depend on a Host package). */
+export declare const QUESTION_NAV_SETTINGS_NS = "question-nav";
+/** Field carrying the selected anchor edge. */
+export declare const ALIGN_FIELD = "align";

package/lib/types/core/turn-dots.d.ts

@@ -35,7 +35,9 @@ export interface TurnDot {
 /**
  * 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.
+ * anchor is the turn's first question. The input is expected to be sorted by
+ * seq; the defensive sort is skipped when it already is, so a long session
+ * never pays an O(n log n) sort on every content update.
  */
 export declare function groupQuestionsByTurn(entries: readonly QuestionEntry[]): TurnDot[];
 /**
@@ -44,5 +46,8 @@ export declare function groupQuestionsByTurn(entries: readonly QuestionEntry[]):
  * 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.
+ *
+ * Fast path: when nothing new arrives the SAME array is returned (no copy),
+ * so the caller can bail out of a re-render on identical reference.
  */
 export declare function mergeLiveQuestions(dots: readonly TurnDot[], live: readonly QuestionNode[]): TurnDot[];

package/lib/types/index.d.ts

@@ -11,10 +11,11 @@ import type { Context } from '@deepseek-ai/cordis';
 /** Cordis plugin name. */
 export declare 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.
+ * Register the `questionIndex` unit and the plugin's durable settings
+ * namespace. Both registries are optional capabilities (absent in headless
+ * compositions), so each registration rides `ctx.inject`: without them the
+ * host half simply contributes nothing and the browser strip falls back to
+ * live-window questions and the default rail alignment.
  * @param ctx - plugin context.
  */
 export declare function apply(ctx: Context): void;

package/lib/types/settings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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`.
+ *
+ * @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';
+/** Durable settings section shared by the Host schema and the browser scope. */
+export interface QuestionNavSettings {
+    /** Anchor edge of the rail. */
+    align: AlignPreference;
+}
+/** Durable settings schema; also the wire envelope the browser scope validates against. */
+export declare const QuestionNavSettingsSchema: z<QuestionNavSettings>;
+/** The settings namespace this plugin owns, branded for the Host registry.
+ * `question-nav` matches the registry pattern (`^[a-z][a-z0-9-]*$`), so the
+ * constant needs no runtime validator — keeping this module type-only on the
+ * settings package avoids inlining it (and cosmokit) into the host bundle. */
+export declare const questionNavSettingsNamespace: SettingsNamespace;

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.4.1",
+  "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 — hover enlarges and shows the full question text, click jumps to that message.",
+  "version": "0.5.0",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {
@@ -31,7 +31,8 @@
         "@deepseek-ai/dsh-client-ui-slots",
         "@deepseek-ai/dsh-client-ui-layout",
         "@deepseek-ai/dsh-client-ui-conversation",
-        "@deepseek-ai/dsh-client-locale"
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings"
       ],
       "platform": "web"
     }
@@ -55,9 +56,12 @@
     "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.1",
     "@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-settings": "^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",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.20.0",

package/src/client/QuestionNavSettingsTab.tsx

@@ -0,0 +1,53 @@
+/**
+ * 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
+ * `question-nav` settings namespace (registered by the host half); the strip
+ * re-anchors live when the snapshot changes.
+ *
+ * @module dsh-question-nav/client/settings-tab
+ */
+
+import { useEffect, useState } from 'react'
+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 type { QuestionNavInjected } from './QuestionNavStrip.tsx'
+import type { QuestionNavKey } from './locales.ts'
+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 {
+  const [, bump] = useState(0)
+  useEffect(() => subscribe(() => bump((n) => n + 1)), [subscribe])
+}
+
+export function QuestionNavSettingsTab(props: ComponentProps): React.JSX.Element | null {
+  useAlignTick(props.subscribeAlign)
+  const align = props.align()
+  const t = props.t
+
+  return (
+    <div className={styles.settings}>
+      <p className={styles.settingsTitle}>{t('settings.align.title')}</p>
+      <p className={styles.settingsDesc}>{t('settings.align.desc')}</p>
+      <div className={styles.segmented} role="radiogroup" aria-label={t('settings.align.title')}>
+        {ALIGN_OPTIONS.map((option) => (
+          <button
+            key={option}
+            type="button"
+            role="radio"
+            aria-checked={align === option}
+            className={align === option ? `${styles.segment} ${styles.segmentActive}` : styles.segment}
+            onClick={() => props.setAlign(option)}
+          >
+            {t(option === 'left' ? 'settings.align.left' : 'settings.align.right')}
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/client/QuestionNavStrip.tsx

@@ -28,6 +28,7 @@ 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 { AlignPreference } from '../core/align.ts'
 import type { JumpFailureCode } from '../core/jump.ts'
 import type { QuestionNavKey } from './locales.ts'
 import styles from './question-nav.module.css'
@@ -52,6 +53,12 @@ export interface QuestionNavInjected {
   questionProjection: (sessionId: SessionId) => ObservableFace | undefined
   /** Jump the chat to a question row (pages the window on demand). */
   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
+  /** Persist a new anchor edge. */
+  setAlign: (align: AlignPreference) => void
 }
 
 type ComponentProps = PropsRuntime<'shell.overlay'> & QuestionNavInjected & PropsLocale<'question-nav'>
@@ -69,7 +76,9 @@ interface TooltipState {
   title: string | null
   /** Question text lines (one per question folded into the dot). */
   lines: readonly string[]
-  left: number
+  /** Horizontal anchor — left edge (left-aligned rail) or right edge (right-aligned). */
+  left?: number
+  right?: number
   top: number
 }
 
@@ -88,6 +97,22 @@ function findConvRoot(): HTMLElement | null {
   return document.querySelector<HTMLElement>('[data-slot="conversation"] > div[data-phase]')
 }
 
+/** 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. */
+function sameDots(a: readonly TurnDot[], b: readonly TurnDot[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    const da = a[i]
+    const db = b[i]
+    if (da.key !== db.key || da.memberKeys.length !== db.memberKeys.length) return false
+    for (let j = 0; j < da.memberKeys.length; j++) {
+      if (da.memberKeys[j] !== db.memberKeys[j]) return false
+    }
+  }
+  return true
+}
+
 export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | null {
   const current = props.useSessions((s) => s.current)
   const summary = props.useSessions((s) => (s.current === undefined ? undefined : s.byId[s.current]))
@@ -97,8 +122,15 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   const [jumpingKey, setJumpingKey] = useState<string | null>(null)
   const [hint, setHint] = useState<string | null>(null)
   const [tooltip, setTooltip] = useState<TooltipState | null>(null)
+  const [align, setAlign] = useState<AlignPreference>(() => props.align())
   const panelRef = useRef<HTMLDivElement | null>(null)
   const hintTimerRef = useRef<number | null>(null)
+  // Last rendered dot list, for the change-detection bail-out below.
+  const lastDotsRef = useRef<TurnDot[]>([])
+
+  // 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])
 
   const showHint = (message: string): void => {
     setHint(message)
@@ -106,27 +138,38 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     hintTimerRef.current = window.setTimeout(() => setHint(null), 1800)
   }
 
-  // Recompute the dot list from the projection + live window; subscribe to
-  // the projection push frames, session content, and the session list.
+  // Recompute the dot list from the projection + live window. Subscribed to
+  // the projection push frames and the session's content only — session
+  // switches are covered by `current` below (the effect re-runs on change),
+  // so the session-list feed is not subscribed: it would re-run the full
+  // recompute for unrelated list churn.
   useEffect(() => {
     if (!visible || current === undefined) {
       setDots([])
+      lastDotsRef.current = []
       return
     }
     const sessionId = current
     const face = props.questionProjection(sessionId)
     const refresh = (): void => {
       const grouped = groupQuestionsByTurn(projectionEntries(face))
-      setDots(mergeLiveQuestions(grouped, props.readQuestions(sessionId)))
+      const next = mergeLiveQuestions(grouped, props.readQuestions(sessionId))
+      // Identical content (a streaming update that added no question): re-use
+      // the previous array reference so React bails out of re-rendering the
+      // strip — the common case during assistant streaming.
+      if (sameDots(next, lastDotsRef.current)) {
+        setDots(lastDotsRef.current)
+        return
+      }
+      lastDotsRef.current = next
+      setDots(next)
     }
     refresh()
     const unsubProjection = face?.subscribe(refresh) ?? (() => {})
     const unsubContent = props.subscribeContent(sessionId, refresh)
-    const unsubList = props.subscribeList(refresh)
     return () => {
       unsubProjection()
       unsubContent()
-      unsubList()
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [visible, current, props])
@@ -143,42 +186,108 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
 
   // Anchor the minimap to the conversation column: position it at the left
   // edge of the conversation root and reserve a thin rail with padding-left.
+  //
+  // A layout-correction loop keeps the rail pinned to the conversation even
+  // when an outside panel (e.g. a browser-extension sidebar like Doubao) moves
+  // or resizes the frame without resizing the browser window: `window resize`
+  // never fires for in-page panels, and a ResizeObserver on the conversation
+  // root alone misses remounts and the tail of the frame's grid-column
+  // transition, which used to leave the rail drifting into the session list.
+  // The loop runs while the layout is still moving, then parks itself after a
+  // few stable frames; observers re-wake it on the next change.
   useLayoutEffect(() => {
     if (!visible) return
     let raf = 0
-    let retries = 0
-    const applyLayout = (): void => {
+    let idle = 0
+    let stopped = false
+    let observer: ResizeObserver | null = null
+    const observed = { frame: null as Element | null, convRoot: null as Element | null }
+
+    const applyLayout = (): boolean => {
       const panel = panelRef.current
-      if (panel === null) return
+      if (panel === null) return false
       const frame = panel.closest('[data-shell-overlay]')?.parentElement ?? null
       const convRoot = findConvRoot()
-      if (frame === null || convRoot === null) return
+      // Keep looping while the anchors are not both present (conversation not
+      // mounted yet / mid-reflow), so a late mount still aligns.
+      if (frame === null || convRoot === null) return true
+      // Keep observing the live nodes: the conversation root may remount
+      // (e.g. after a panel-triggered reflow), which silently detaches an
+      // earlier ResizeObserver target.
+      if (observer !== null) {
+        if (observed.frame !== frame) {
+          observer.observe(frame, { box: 'border-box' })
+          observed.frame = frame
+        }
+        if (observed.convRoot !== convRoot) {
+          observer.observe(convRoot, { box: 'border-box' })
+          observed.convRoot = convRoot
+        }
+      }
       const frameRect = frame.getBoundingClientRect()
       const convRect = convRoot.getBoundingClientRect()
-      if (convRect.height <= 0) {
-        if (retries < 20) {
-          retries += 1
-          raf = requestAnimationFrame(applyLayout)
+      // Never snap onto a transient box: keep correcting until the
+      // conversation has a real footprint again.
+      if (convRect.height <= 0 || convRect.width <= 0) return true
+      const top = `${convRect.top - frameRect.top}px`
+      const height = `${convRect.height}px`
+      // Anchor to the configured edge: keep the other edge's inline style
+      // cleared so the CSS class (left: auto on .railRight) owns it.
+      if (align === 'right') {
+        const right = `${frameRect.right - convRect.right}px`
+        if (panel.style.top === top && panel.style.height === height
+          && panel.style.right === right && panel.style.left === '') {
+          return false
         }
-        return
+        panel.style.top = top
+        panel.style.height = height
+        panel.style.right = right
+        panel.style.left = ''
+        return true
+      }
+      const left = `${convRect.left - frameRect.left}px`
+      if (panel.style.top === top && panel.style.height === height
+        && panel.style.left === left && panel.style.right === '') {
+        return false
       }
-      retries = 0
-      panel.style.top = `${convRect.top - frameRect.top}px`
-      panel.style.height = `${convRect.height}px`
-      panel.style.left = `${convRect.left - frameRect.left}px`
+      panel.style.top = top
+      panel.style.height = height
+      panel.style.left = left
+      panel.style.right = ''
+      return true
+    }
+
+    const loop = (): void => {
+      if (stopped) return
+      raf = 0
+      idle = applyLayout() ? 0 : idle + 1
+      if (idle < 3) raf = requestAnimationFrame(loop)
+    }
+    const wake = (): void => {
+      if (stopped) return
+      idle = 0
+      if (raf === 0) raf = requestAnimationFrame(loop)
     }
-    applyLayout()
-    raf = requestAnimationFrame(applyLayout)
-    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(applyLayout)
-    const convRoot = findConvRoot()
-    observer?.observe(convRoot ?? document.body, { box: 'border-box' })
-    window.addEventListener('resize', applyLayout)
+
+    observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(wake)
+    if (observer !== null) {
+      const panel = panelRef.current
+      const frame = panel?.closest('[data-shell-overlay]')?.parentElement ?? null
+      const convRoot = findConvRoot()
+      if (frame !== null) { observer.observe(frame, { box: 'border-box' }); observed.frame = frame }
+      if (convRoot !== null) { observer.observe(convRoot, { box: 'border-box' }); observed.convRoot = convRoot }
+    }
+
+    // Initial alignment; the loop keeps correcting through layout transitions.
+    wake()
+    window.addEventListener('resize', wake)
     return () => {
+      stopped = true
       if (raf !== 0) cancelAnimationFrame(raf)
       observer?.disconnect()
-      window.removeEventListener('resize', applyLayout)
+      window.removeEventListener('resize', wake)
     }
-  }, [visible])
+  }, [visible, align])
 
   // Clear any pending hint timer on unmount.
   useEffect(() => () => {
@@ -199,7 +308,11 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     setTooltip({
       title: dot.turn === null ? null : `Turn ${dot.turn}`,
       lines: dot.texts,
-      left: r.right + 10,
+      // 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,
     })
   }
@@ -207,7 +320,11 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   const t = props.t
 
   return (
-    <div ref={panelRef} className={styles.rail} data-question-nav="rail">
+    <div
+      ref={panelRef}
+      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}>
         {dots.length === 0 ? (
@@ -230,7 +347,7 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
       </div>
       {tooltip !== null
         ? createPortal(
-            <div className={styles.tooltip} style={{ left: tooltip.left, top: tooltip.top }}>
+            <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>

package/src/client/index.ts

@@ -23,7 +23,13 @@ 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'
+// Type-only: pulls the settings shell's SlotMap merge ('settings.plugins.tab')
+// and the ctx.settingsScope Context merge.
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SettingsScopeBinder } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { QuestionNavStrip, type ObservableFace, type QuestionNavInjected } from './QuestionNavStrip.tsx'
+import { QuestionNavSettingsTab } from './QuestionNavSettingsTab.tsx'
+import { QuestionNavSettingsController } from './settings.ts'
 import { en, zh, type QuestionNavKey } from './locales.ts'
 import { extractQuestions } from '../core/nodes.ts'
 import { jumpToQuestion, type JumpFailureCode, type JumpPorts } from '../core/jump.ts'
@@ -103,7 +109,7 @@ function questionProjectionOf(ctx: ClientContext, sessionId: SessionId): Observa
   }
 }
 
-function createInject(ctx: ClientContext): QuestionNavInjected {
+function createInject(ctx: ClientContext, settings: QuestionNavSettingsController): QuestionNavInjected {
   return {
     readQuestions: (sessionId) => {
       const snap = ctx.sessions.binding(sessionId)?.session.getSnapshot()
@@ -126,6 +132,9 @@ function createInject(ctx: ClientContext): QuestionNavInjected {
       }
       void jumpToQuestion(ports, key)
     },
+    align: () => settings.getSnapshot().align,
+    subscribeAlign: (cb) => settings.subscribe(cb),
+    setAlign: (align) => settings.setAlign(align),
   }
 }
 
@@ -138,8 +147,10 @@ export function apply(ctx: ClientContext): void {
   ctx.effect(() => releaseApply, 'question-nav: apply claim')
 
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'question-nav: dictionaries')
+  const t = ctx.locale.bind(NS)
 
-  const injected = createInject(ctx)
+  const settings = new QuestionNavSettingsController()
+  const injected = createInject(ctx, settings)
 
   ctx.slots.inject('shell.overlay', () => ctx.slots.register({
     name: 'shell.overlay',
@@ -148,4 +159,19 @@ export function apply(ctx: ClientContext): void {
     locale: NS,
     inject: () => injected,
   }, QuestionNavStrip))
+
+  // The settings surface is optional and may apply after this plugin, so the
+  // namespace binds and the settings page mounts in a fiber that waits for
+  // it. Without it the strip simply keeps the default left alignment.
+  ctx.inject(['settingsScope'], (scopeCtx) => {
+    settings.attach(scopeCtx.get('settingsScope') as SettingsScopeBinder)
+    ctx.slots.inject('settings.plugins.tab', () => ctx.slots.register({
+      name: 'settings.plugins.tab',
+      id: 'question-nav',
+      order: 100,
+      label: () => t('settings.tab'),
+      locale: NS,
+      inject: () => injected,
+    }, QuestionNavSettingsTab))
+  })
 }

package/src/client/locales.ts

@@ -8,6 +8,11 @@ export const zh = {
   'jump.hidden': '目标无独立气泡，已定位到邻近内容',
   'jump.notfound': '目标未加载或不存在（可能已压缩）',
   'jump.timeout': '加载历史超时，可重试',
+  'settings.tab': '提问导航',
+  'settings.align.title': '导航条对齐',
+  'settings.align.desc': '选择圆点导航条锚定在对话栏的哪一侧。',
+  'settings.align.left': '左侧',
+  'settings.align.right': '右侧',
 } as const
 
 export const en = {
@@ -16,6 +21,11 @@ export const en = {
   'jump.hidden': 'No dedicated bubble; landed on nearby content',
   'jump.notfound': 'Target not loaded or missing (maybe compacted)',
   'jump.timeout': 'Timed out loading history; retry',
+  'settings.tab': 'Question Nav',
+  'settings.align.title': 'Rail alignment',
+  'settings.align.desc': 'Choose which edge of the conversation column the dot rail anchors to.',
+  'settings.align.left': 'Left',
+  'settings.align.right': 'Right',
 } as const
 
 export type QuestionNavKey = keyof typeof zh