@luziyang2026/dsh-question-nav 0.4.2 → 0.6.0

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)
+  }
+}

package/src/core/align.ts

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

package/src/core/focus.ts

@@ -0,0 +1,76 @@
+/**
+ * Focus-magnification model for the question-nav rail. Pure index/scale math
+ * for the hover-selected dot's neighborhood window, its progressive
+ * magnification tiers, and the vertical cascade of question cards (one per
+ * window dot, non-overlapping, sizes descending away from the selected one).
+ * No React, no DOM — every function here is unit-testable in isolation and
+ * safe to inline into the client bundle.
+ *
+ * @module dsh-question-nav/focus
+ */
+
+/** How many dots stay enlarged on each side of the selected dot. */
+export const FOCUS_RADIUS = 2
+
+/** Magnification scale per tier, by distance from the selected dot
+ * (0 = selected, 1 = immediate neighbor, 2 = outer window edge). */
+export const FOCUS_SCALES = [2.0, 1.55, 1.25] as const
+
+/**
+ * The focus tier of a dot at `distance` from the selected dot: 0..FOCUS_RADIUS
+ * while inside the magnification window, null beyond it (base scale).
+ */
+export function focusTier(distance: number): number | null {
+  const d = Math.abs(distance)
+  if (d > FOCUS_RADIUS) return null
+  return d
+}
+
+/** Magnification scale for a dot at `distance`; 1 (base) outside the window. */
+export function focusScale(distance: number): number {
+  const tier = focusTier(distance)
+  return tier === null ? 1 : FOCUS_SCALES[tier]
+}
+
+/** Presentation metrics for the question card of a dot at `distance` from the
+ *  selected one. 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 function focusCardMetrics(distance: number): FocusCardMetrics | null {
+  const tier = focusTier(distance)
+  if (tier === null) return null
+  switch (tier) {
+    case 0:
+      return { widthPx: 380, fontSize: 13, maxLines: 6, brightness: 1 }
+    case 1:
+      return { widthPx: 300, fontSize: 12.5, maxLines: 2, brightness: 0.82 }
+    default:
+      return { widthPx: 240, fontSize: 12, maxLines: 1, brightness: 0.68 }
+  }
+}
+
+/**
+ * Indices of the focus window: the selected dot plus `radius` on each side,
+ * clipped to the dot list. Empty when the list is empty or `selected` is out
+ * of range.
+ */
+export function magnificationWindow(total: number, selected: number, radius: number = FOCUS_RADIUS): number[] {
+  if (total <= 0 || selected < 0 || selected >= total || radius < 0) return []
+  const out: number[] = []
+  const lo = Math.max(0, selected - radius)
+  const hi = Math.min(total - 1, selected + radius)
+  for (let i = lo; i <= hi; i++) out.push(i)
+  return out
+}

package/src/core/time.ts

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n)
+}
+
+/** Whether `time` falls on the same calendar day as `now`. */
+export function isSameDay(time: number, now: number): boolean {
+  const a = new Date(time)
+  const b = new Date(now)
+  return a.getFullYear() === b.getFullYear()
+    && a.getMonth() === b.getMonth()
+    && a.getDate() === b.getDate()
+}
+
+/**
+ * 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 function formatQuestionTime(time: number, now: number): string {
+  if (!Number.isFinite(time) || time <= 0) return ''
+  const d = new Date(time)
+  const hm = `${pad2(d.getHours())}:${pad2(d.getMinutes())}`
+  if (isSameDay(time, now)) return hm
+  const md = `${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`
+  if (d.getFullYear() === new Date(now).getFullYear()) return `${md} ${hm}`
+  return `${d.getFullYear()}-${md} ${hm}`
+}

package/src/index.ts

@@ -9,19 +9,24 @@
  */
 import type { Context } from '@deepseek-ai/cordis'
 import { questionIndexProjectionDefinition } from './projection.ts'
+import { questionNavSettingsNamespace, QuestionNavSettingsSchema } from './settings.ts'
 
 /** Cordis plugin name. */
 export 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 function apply(ctx: Context): void {
   ctx.inject(['sessionProjections'], (inner) => {
     inner.sessionProjections.register(questionIndexProjectionDefinition)
   })
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.register(questionNavSettingsNamespace, QuestionNavSettingsSchema)
+  })
 }

package/src/settings.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 {
+  ALIGN_FIELD, ALIGN_OPTIONS, DEFAULT_ALIGN, QUESTION_NAV_SETTINGS_NS,
+  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 const QuestionNavSettingsSchema: z<QuestionNavSettings> = z.object({
+  [ALIGN_FIELD]: z.union([...ALIGN_OPTIONS]).default(DEFAULT_ALIGN),
+})
+
+/** 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 const questionNavSettingsNamespace = QUESTION_NAV_SETTINGS_NS as SettingsNamespace