@luziyang2026/dsh-question-nav 0.4.2 → 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/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.2",
+  "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
 }
 
@@ -113,11 +122,16 @@ 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)
     if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)
@@ -217,13 +231,29 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
       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
+        }
+        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) {
+      if (panel.style.top === top && panel.style.height === height
+        && panel.style.left === left && panel.style.right === '') {
         return false
       }
       panel.style.top = top
       panel.style.height = height
       panel.style.left = left
+      panel.style.right = ''
       return true
     }
 
@@ -257,7 +287,7 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
       observer?.disconnect()
       window.removeEventListener('resize', wake)
     }
-  }, [visible])
+  }, [visible, align])
 
   // Clear any pending hint timer on unmount.
   useEffect(() => () => {
@@ -278,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,
     })
   }
@@ -286,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 ? (
@@ -309,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

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

@@ -15,6 +15,12 @@
   pointer-events: none;
 }
 
+/* Right-anchored rail: release the CSS `left: 0` so the inline `right`
+   (written by the layout-correction loop) owns the position. */
+.railRight {
+  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). */
 .list {
@@ -118,3 +124,52 @@
   padding-top: 6px;
   border-top: 1px solid var(--dsw-alias-border-l1);
 }
+
+/* Settings page (settings.plugins.tab). */
+.settings {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 4px 0;
+}
+.settingsTitle {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+  margin: 0;
+}
+.settingsDesc {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-secondary);
+  margin: 0;
+}
+.segmented {
+  display: inline-flex;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 8px;
+  overflow: hidden;
+  align-self: flex-start;
+}
+.segment {
+  border: none;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 13px;
+  line-height: 1;
+  padding: 8px 16px;
+  cursor: pointer;
+  transition: background 120ms ease, color 120ms ease;
+}
+.segment + .segment {
+  border-left: 1px solid var(--dsw-alias-border-l1);
+}
+.segment:hover {
+  background: var(--dsw-alias-bg-layer-1);
+  color: var(--dsw-alias-label-primary);
+}
+.segmentActive,
+.segmentActive:hover {
+  background: var(--dsw-alias-brand-primary);
+  color: var(--dsw-alias-label-inverse);
+}

package/src/client/settings.ts

@@ -0,0 +1,105 @@
+/**
+ * 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, SettingsScopeSnapshot, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client'
+import {
+  ALIGN_FIELD, ALIGN_OPTIONS, DEFAULT_ALIGN, QUESTION_NAV_SETTINGS_NS,
+  type AlignPreference,
+} from '../core/align.ts'
+
+/** Narrow a raw section to the anchor field. */
+function isAlignPreference(value: unknown): value is AlignPreference {
+  return ALIGN_OPTIONS.some((option) => option === value)
+}
+
+/** 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>
+}
+
+/** Wire section this plugin owns (the Host schema's `align` field). */
+interface QuestionNavSection {
+  align?: unknown
+}
+
+/** 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 class QuestionNavSettingsController {
+  private scope: SettingsScope<QuestionNavSection> | undefined
+  private readonly listeners = new Set<() => void>()
+  private unsubscribe: () => void = () => {}
+  private state: QuestionNavSettingsState = { align: DEFAULT_ALIGN, overridden: false }
+
+  /**
+   * 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 {
+    if (this.scope !== undefined) return
+    this.scope = binder.bind<QuestionNavSection>({ namespace: QUESTION_NAV_SETTINGS_NS })
+    this.state = this.derive(this.scope.getSnapshot())
+    this.unsubscribe = this.scope.subscribe(() => {
+      if (this.scope === undefined) return
+      const next = this.derive(this.scope.getSnapshot())
+      if (next.align === this.state.align && next.overridden === this.state.overridden) return
+      this.state = next
+      for (const listener of this.listeners) listener()
+    })
+  }
+
+  private derive(snapshot: SettingsScopeSnapshot<QuestionNavSection>): QuestionNavSettingsState {
+    const user = snapshot.user as { align?: unknown } | undefined
+    return {
+      align: snapshot.status === 'ready' && isAlignPreference(snapshot.value?.align)
+        ? snapshot.value.align
+        : DEFAULT_ALIGN,
+      overridden: user !== undefined && user.align !== undefined,
+    }
+  }
+
+  /** Release the scope subscription (bound on the settings fiber's lifecycle). */
+  dispose(): void {
+    this.unsubscribe()
+    this.listeners.clear()
+  }
+
+  /** @returns the current state (stable reference until the next change). */
+  getSnapshot(): QuestionNavSettingsState {
+    return this.state
+  }
+
+  /** Observe state replacements; returns the disposer. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /** Route the user's anchor-edge choice to the Host document. */
+  setAlign(align: AlignPreference): void {
+    if (this.scope === undefined) return
+    void this.scope.set(ALIGN_FIELD, align)
+  }
+}