@luziyang2026/dsh-question-nav 0.4.1 → 0.5.0

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

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/turn-dots.ts

@@ -40,13 +40,24 @@ export interface TurnDot {
   readonly memberKeys: readonly string[]
 }
 
+/** True when entries are already in non-decreasing seq order (the projection
+ * appends in event order, so this is the common case and skips the sort). */
+function isSortedBySeq(entries: readonly QuestionEntry[]): boolean {
+  for (let i = 1; i < entries.length; i++) {
+    if (entries[i].seq < entries[i - 1].seq) return false
+  }
+  return true
+}
+
 /**
  * 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 function groupQuestionsByTurn(entries: readonly QuestionEntry[]): TurnDot[] {
-  const sorted = [...entries].sort((a, b) => a.seq - b.seq)
+  const sorted = isSortedBySeq(entries) ? entries : [...entries].sort((a, b) => a.seq - b.seq)
   const dots: TurnDot[] = []
   for (const entry of sorted) {
     const key = questionKey(entry.id)
@@ -77,22 +88,49 @@ export function groupQuestionsByTurn(entries: readonly QuestionEntry[]): TurnDot
  * 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 function mergeLiveQuestions(
   dots: readonly TurnDot[],
   live: readonly QuestionNode[],
 ): TurnDot[] {
-  const known = new Set(dots.flatMap(dot => dot.memberKeys))
-  const extras: TurnDot[] = live
-    .filter(question => !known.has(question.key))
-    .map(question => ({
+  if (live.length === 0) return dots as TurnDot[]
+  const known = new Set<string>()
+  for (const dot of dots) {
+    for (const key of dot.memberKeys) known.add(key)
+  }
+  const extras: TurnDot[] = []
+  for (const question of live) {
+    if (known.has(question.key)) continue
+    extras.push({
       turn: null,
       key: question.key,
       anchorSeq: question.anchorSeq,
       time: question.time,
       texts: [question.text],
       memberKeys: [question.key],
-    }))
-  if (extras.length === 0) return [...dots]
-  return [...dots, ...extras].sort((a, b) => a.anchorSeq - b.anchorSeq)
+    })
+  }
+  // Nothing new from the live window — reuse the input array unchanged.
+  if (extras.length === 0) return dots as TurnDot[]
+  // Both `dots` and `extras` are sorted by anchorSeq (dots from the projection
+  // order, extras from the live window order): merge linearly instead of
+  // re-sorting the whole list. Ties keep the projected dot first (stable
+  // sort semantics), matching the previous [...dots, ...extras].sort().
+  const out: TurnDot[] = []
+  let i = 0
+  for (const extra of extras) {
+    while (i < dots.length && dots[i].anchorSeq <= extra.anchorSeq) {
+      out.push(dots[i])
+      i += 1
+    }
+    out.push(extra)
+  }
+  while (i < dots.length) {
+    out.push(dots[i])
+    i += 1
+  }
+  return out
 }

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