@luziyang2026/dsh-question-nav 0.4.2 → 0.6.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/focus.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 declare const FOCUS_RADIUS = 2;
+/** Magnification scale per tier, by distance from the selected dot
+ * (0 = selected, 1 = immediate neighbor, 2 = outer window edge). */
+export declare const FOCUS_SCALES: readonly [2, 1.55, 1.25];
+/**
+ * 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 declare function focusTier(distance: number): number | null;
+/** Magnification scale for a dot at `distance`; 1 (base) outside the window. */
+export declare function focusScale(distance: number): number;
+/** Presentation metrics for the question card of a dot at `distance` from the
+ *  selected one. Cards stay crisp (no blur): the selected card is the widest,
+ *  brightest and shows every text line; each of its two neighbors on each side
+ *  is a slightly narrower, dimmer card clamped to fewer lines. Null outside
+ *  the window (no card). */
+export interface FocusCardMetrics {
+    /** Card width in px (narrows away from the selected card). */
+    widthPx: number;
+    /** Text font size (px); cascade cards are slightly smaller. */
+    fontSize: number;
+    /** Max text lines before clamping (cascade cards). */
+    maxLines: number;
+    /** Brightness (1 = full, the selected card; dimmer away from it). */
+    brightness: number;
+}
+export declare function focusCardMetrics(distance: number): FocusCardMetrics | null;
+/**
+ * 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 declare function magnificationWindow(total: number, selected: number, radius?: number): number[];

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

@@ -0,0 +1,19 @@
+/**
+ * Question sent-time formatting for the question-nav surface. Pure: no DSH
+ * imports, deterministic for a given (time, now) pair — unit-testable in
+ * isolation and safe to inline into the client bundle.
+ *
+ * @module dsh-question-nav/time
+ */
+/** Whether `time` falls on the same calendar day as `now`. */
+export declare function isSameDay(time: number, now: number): boolean;
+/**
+ * Smart question sent-time, relative to `now`:
+ * - same calendar day → `HH:MM`
+ * - same calendar year → `MM-DD HH:MM`
+ * - otherwise → `YYYY-MM-DD HH:MM`
+ *
+ * Returns `''` for a missing/invalid timestamp (e.g. a live node that never
+ * reported one), so callers can hide the time line without branching.
+ */
+export declare function formatQuestionTime(time: number, now: number): string;

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 — 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.6.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>
+  )
+}