dsh-mega-chat-nav 0.1.1

package/src/client/locales.ts

@@ -0,0 +1,143 @@
+/**
+ * mega-chat-nav 词条字典（zh/en）。注册于 `mega-chat-nav` 命名空间；
+ * key 经绑定翻译函数消费。
+ */
+export const zh = {
+  'strip.empty': '本会话还没有提问',
+  'strip.up': '向上翻出更多提问圆点',
+  'strip.down': '向下翻出更多提问圆点',
+  'jump.inactive': '聊天视图未激活',
+  'jump.hidden': '目标无独立气泡，已定位到邻近内容',
+  'jump.notfound': '目标未加载或不存在（可能已压缩）',
+  'jump.timeout': '加载历史超时，可重试',
+  'jump.loading': '正在加载较早记录以定位（第 {n} 页）',
+  'search.historic': '另有 {n} 条来自更早历史',
+  'search.turnTitle': '第 {turn} 轮',
+  'search.tag.user': '用户',
+  'search.tag.assistant': '助手',
+  'search.tag.tool': '工具',
+  'settings.tab': '提问导航',
+  'label': 'mega 导航',
+  'config.align': '对齐方式',
+  'config.railOffset': '导航栏偏移',
+  'config.railOffset.desc': '导航条与对话列边缘的距离（0-32px，随左右对齐自适应）。',
+  'settings.align.desc': '选择圆点导航条锚定在对话栏的哪一侧。',
+  'settings.align.left': '左侧',
+  'settings.align.right': '右侧',
+  'settings.hosted': '配置已收纳至 mega 设置中心',
+  'config.bandHeight': '节点栏高度',
+  'config.bandHeight.desc': '节点栏的最大高度。',
+  'config.bandHeight.compact': '紧凑',
+  'config.bandHeight.standard': '标准',
+  'config.bandHeight.tall': '高',
+  'config.title': '导航条设置',
+  'config.settings': '设置',
+  'config.close': '关闭',
+  'config.scrollBehavior': '跳转动画',
+  'config.scrollBehavior.desc': '点击跳转时消息滚入的动画方式。',
+  'config.scrollBehavior.smooth': '平滑',
+  'config.scrollBehavior.instant': '瞬时',
+  'config.showCount': '轮次总数',
+  'config.showPaging': '翻页标记',
+  'config.showQuickSettings': '设置按钮',
+  'config.showFavorites': '收藏按钮',
+  'config.searchScopes': '搜索内容',
+  'config.searchScopes.desc': '搜索哪些消息类型（多选；用户必选）。',
+  'config.searchScopes.user': '用户',
+  'config.searchScopes.assistant': '助手',
+  'config.searchScopes.tool': '工具',
+  'config.style': '风格',
+  'config.style.minimal': '简约',
+  'config.style.codex': 'Codex',
+  'config.style.deepseek': 'Deepseek Chat',
+  'config.cardCount': '悬停卡片数',
+  'config.cardCount.desc': '悬停节点时弹出的卡片数量（1/3/5 张）。',
+  'config.cardItems': '悬浮卡功能',
+  'config.cardItems.desc': '勾选悬浮卡显示的内容块（多选）。',
+  'config.cardItems.turn': '轮次',
+  'config.cardItems.duration': '用时',
+  'config.cardItems.favorite': '收藏',
+  'config.markTone': '刻度色调',
+  'config.markTone.desc': 'codex 刻度条的明暗档：柔和低对比 / 深邃高对比（默认）。',
+  'config.markTone.soft': '柔和',
+  'config.markTone.deep': '深邃',
+  'fav.filter': '只看收藏',
+  'strip.noFavorites': '暂无收藏',
+  'config.showSearch': '搜索按钮',
+  'config.showMode.show': '显示',
+  'config.showMode.peek': '浮现',
+  'config.showMode.hide': '隐藏',
+  'search.placeholder': '搜索消息…',
+  'search.empty': '无匹配结果',
+  'search.loading': '正在搜索…',
+} as const
+
+export const en = {
+  'strip.empty': 'No questions in this session yet',
+  'strip.up': 'Reveal more question dots above',
+  'strip.down': 'Reveal more question dots below',
+  'jump.inactive': 'Chat view is not active',
+  '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',
+  'jump.loading': 'Loading earlier records to locate (page {n})',
+  'search.historic': '{n} more from earlier history',
+  'search.turnTitle': 'Turn {turn}',
+  'search.tag.user': 'User',
+  'search.tag.assistant': 'Assistant',
+  'search.tag.tool': 'Tool',
+  'settings.tab': 'Question Nav',
+  'label': 'Mega Nav',
+  'config.align': 'Alignment',
+  'config.railOffset': 'Rail offset',
+  'config.railOffset.desc': 'Distance between the rail and the conversation edge (0-32px, adapts to alignment).',
+  'settings.align.desc': 'Choose which edge of the conversation column the dot rail anchors to.',
+  'settings.align.left': 'Left',
+  'settings.align.right': 'Right',
+  'settings.hosted': 'Config is hosted in the mega settings center',
+  'config.bandHeight': 'Band height',
+  'config.bandHeight.desc': 'Max height of the dot band.',
+  'config.bandHeight.compact': 'Compact',
+  'config.bandHeight.standard': 'Standard',
+  'config.bandHeight.tall': 'Tall',
+  'config.title': 'Nav settings',
+  'config.settings': 'Settings',
+  'config.close': 'Close',
+  'config.scrollBehavior': 'Jump animation',
+  'config.scrollBehavior.desc': 'How the chat scrolls when jumping to a message.',
+  'config.scrollBehavior.smooth': 'Smooth',
+  'config.scrollBehavior.instant': 'Instant',
+  'config.showCount': 'Turn count',
+  'config.showPaging': 'Paging markers',
+  'config.showQuickSettings': 'Settings button',
+  'config.showFavorites': 'Favorite button',
+  'config.searchScopes': 'Search content',
+  'config.searchScopes.desc': 'Message types included in search (multi-select; user is required).',
+  'config.searchScopes.user': 'User',
+  'config.searchScopes.assistant': 'Assistant',
+  'config.searchScopes.tool': 'Tool',
+  'config.style': 'Style',
+  'config.style.minimal': 'Minimal',
+  'config.style.codex': 'Codex',
+  'config.style.deepseek': 'Deepseek Chat',
+  'config.cardCount': 'Card count',
+  'config.cardCount.desc': 'Cascade cards shown on hover (1/3/5).',
+  'config.cardItems': 'Card contents',
+  'config.cardItems.desc': 'Content blocks shown on hover cards (multi-select).',
+  'config.cardItems.turn': 'Turn',
+  'config.cardItems.duration': 'Duration',
+  'config.cardItems.favorite': 'Favorite',
+  'config.markTone': 'Mark tone',
+  'config.markTone.desc': 'Codex tick contrast: soft / deep (default).',
+  'config.markTone.soft': 'Soft',
+  'config.markTone.deep': 'Deep',
+  'fav.filter': 'Favorites only',
+  'strip.noFavorites': 'No favorites yet',
+  'config.showSearch': 'Search button',
+  'config.showMode.show': 'Show',
+  'config.showMode.peek': 'Peek',
+  'config.showMode.hide': 'Hide',
+  'search.placeholder': 'Search messages…',
+  'search.empty': 'No matches',
+  'search.loading': 'Searching…',
+} as const

package/src/client/settings.ts

@@ -0,0 +1,482 @@
+/**
+ * Browser mirror of the `mega-chat-nav` settings namespace: reads the rail
+ * settings from the settings scope (`ctx.settingsScope.bind`) and routes the
+ * user's choices back through the host bridge (POST /mega-chat-nav/settings).
+ *
+ * 配置选项为本插件自有定义：此处为 client 半持有的同值副本（与 host 半
+ * src/settings.ts 一致；client bundle 不得依赖宿主包）。
+ *
+ * The settings surface is optional and may apply after this plugin, so the
+ * controller starts unbound and degrades to the defaults until {@link attach}
+ * binds the scope.
+ *
+ * @module dsh-mega-chat-nav/client/settings
+ */
+
+import type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client'
+
+/** 风格选项：简约 / codex（时间线刻度）/ deepseek（用户消息面板，常态短横折叠） */
+export const STYLE_OPTIONS = ['minimal', 'codex', 'deepseek'] as const
+export type NavStyle = typeof STYLE_OPTIONS[number]
+
+/** 停靠侧选项 */
+export const ALIGN_OPTIONS = ['left', 'right'] as const
+export type RailAlign = typeof ALIGN_OPTIONS[number]
+
+/** 节点栏条带高度档位 */
+export const BAND_OPTIONS = ['compact', 'standard', 'tall'] as const
+export type BandHeight = typeof BAND_OPTIONS[number]
+
+/** 跳转动画方式 */
+export const SCROLL_OPTIONS = ['smooth', 'instant'] as const
+export type ScrollMode = typeof SCROLL_OPTIONS[number]
+
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export const SHOW_OPTIONS = ['show', 'peek', 'hide'] as const
+export type ShowMode = typeof SHOW_OPTIONS[number]
+
+/** 翻页标记显示策略（按风格独立默认）：minimal 常显 / codex 隐藏 / deepseek 浮现 */
+export const DEFAULT_PAGING: Record<NavStyle, ShowMode> = {
+  minimal: 'show',
+  codex: 'hide',
+  deepseek: 'peek',
+}
+
+/** 搜索内容范围（多选；用户必选） */
+export const SEARCH_SCOPE_OPTIONS = ['user', 'assistant', 'tool'] as const
+export type SearchScope = typeof SEARCH_SCOPE_OPTIONS[number]
+export const DEFAULT_SEARCH_SCOPES: SearchScope[] = ['user', 'assistant', 'tool']
+
+/** 悬停卡片数量 */
+export const CARD_OPTIONS = [1, 3, 5] as const
+export type CardCount = typeof CARD_OPTIONS[number]
+
+/** 悬浮卡默认数量（按风格独立）：minimal 3 张 / codex 1 张 / deepseek 1 张（无悬浮卡能力，占位） */
+export const DEFAULT_CARD_COUNT: Record<NavStyle, CardCount> = {
+  minimal: 3,
+  codex: 1,
+  deepseek: 1,
+}
+
+/** 悬浮卡内容块（多选） */
+export const CARD_ITEM_OPTIONS = ['turn', 'duration', 'favorite'] as const
+export type CardItem = typeof CARD_ITEM_OPTIONS[number]
+export const DEFAULT_CARD_ITEMS: CardItem[] = ['turn', 'duration', 'favorite']
+
+/** 刻度色调：柔和（低对比）/ 深邃（高对比、清晰） */
+export const MARK_TONE_OPTIONS = ['soft', 'deep'] as const
+export type MarkTone = typeof MARK_TONE_OPTIONS[number]
+export const DEFAULT_MARK_TONE: MarkTone = 'deep'
+
+export const DEFAULT_STYLE: NavStyle = 'minimal'
+export const DEFAULT_ALIGN: RailAlign = 'left'
+export const DEFAULT_BAND: BandHeight = 'standard'
+export const DEFAULT_SCROLL: ScrollMode = 'smooth'
+export const DEFAULT_SHOW: ShowMode = 'show'
+
+/** 条带高度档位 → 像素（minimal/codex 共用基础几何；deepseek 行高 30px 自成一档）
+ *  - minimal / codex：compact 140 / standard 210 / tall 280
+ *  - deepseek：compact 160 / standard 220 / tall 280 */
+export const BAND_HEIGHT_PX: Record<NavStyle, Record<BandHeight, number>> = {
+  minimal: { compact: 144, standard: 204, tall: 274 },
+  codex: { compact: 140, standard: 210, tall: 280 },
+  deepseek: { compact: 160, standard: 220, tall: 280 },
+}
+
+/** 风格能力：各风格声明自己的可选能力（组件与设置面据此取舍） */
+export interface StyleCapabilities {
+  /** 悬停悬浮卡片（级联预览）——deepseek 面板自带消息预览，不需要 */
+  hoverCards: boolean
+  /** ▲/▼ 翻页标志（deepseek 面板内滚动，不需要显式翻页按钮） */
+  paging: boolean
+}
+
+/** 风格 → 能力表 */
+export const STYLE_CAPABILITIES: Record<NavStyle, StyleCapabilities> = {
+  minimal: { hoverCards: true, paging: true },
+  codex: { hoverCards: true, paging: true },
+  deepseek: { hoverCards: false, paging: false },
+}
+
+/** 本插件设置命名空间 */
+export const MGCN_NS = 'mega-chat-nav'
+
+/** 导航栏偏移（px）范围与默认值 */
+export const RAIL_OFFSET_MIN = 0
+export const RAIL_OFFSET_MAX = 32
+export const DEFAULT_RAIL_OFFSET = 8
+
+/** Narrow a raw section value to the anchor field. */
+function isRailAlign(value: unknown): value is RailAlign {
+  return (ALIGN_OPTIONS as readonly unknown[]).includes(value)
+}
+
+/** Narrow a raw section value to the style field. */
+function isNavStyle(value: unknown): value is NavStyle {
+  return (STYLE_OPTIONS as readonly unknown[]).includes(value)
+}
+
+/** 兼容旧 boolean 配置：true → show，false → hide；新值走枚举校验 */
+function coerceShowMode(value: unknown): ShowMode {
+  if (typeof value === 'boolean') return value ? 'show' : 'hide'
+  return isShowMode(value) ? value : DEFAULT_SHOW
+}
+
+/** 翻页标记显示模式转换（默认按风格：minimal show / codex hide） */
+function coercePagingMode(value: unknown, fallback: ShowMode): ShowMode {
+  if (typeof value === 'boolean') return value ? 'show' : 'hide'
+  return isShowMode(value) ? value : fallback
+}
+
+function isShowMode(value: unknown): value is ShowMode {
+  return (SHOW_OPTIONS as readonly unknown[]).includes(value)
+}
+
+function isCardCount(value: unknown): value is CardCount {
+  return (CARD_OPTIONS as readonly unknown[]).includes(value)
+}
+
+function isBandHeight(value: unknown): value is BandHeight {
+  return (BAND_OPTIONS as readonly unknown[]).includes(value)
+}
+
+function isSearchScopes(value: unknown): value is SearchScope[] {
+  return Array.isArray(value)
+    && value.every((s) => (SEARCH_SCOPE_OPTIONS as readonly unknown[]).includes(s))
+}
+
+function isCardItems(value: unknown): value is CardItem[] {
+  return Array.isArray(value)
+    && value.every((item) => (CARD_ITEM_OPTIONS as readonly unknown[]).includes(item))
+}
+
+function isMarkTone(value: unknown): value is MarkTone {
+  return (MARK_TONE_OPTIONS as readonly unknown[]).includes(value)
+}
+
+function isScrollMode(value: unknown): value is ScrollMode {
+  return (SCROLL_OPTIONS as readonly unknown[]).includes(value)
+}
+
+/** The minimal face of the settings scope service this controller needs. */
+export interface SettingsScopeBinderLike {
+  bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>
+}
+
+/** 单风格 wire 段（每风格独立；字段同 host schema） */
+interface StyleWireSection {
+  bandHeight?: unknown
+  cardCount?: unknown
+  cardItems?: unknown
+  markTone?: unknown
+  showPaging?: unknown
+}
+
+/** Wire section this plugin owns (the Host schema's fields). */
+interface NavSettingsSection {
+  general?: {
+    style?: unknown
+    align?: unknown
+    scrollBehavior?: unknown
+    showCount?: unknown
+    showSearch?: unknown
+    showQuickSettings?: unknown
+    showFavorites?: unknown
+    searchScopes?: unknown
+    railOffset?: unknown
+  }
+  styles?: Partial<Record<NavStyle, StyleWireSection>>
+}
+
+/** Snapshot consumed by the strip and the settings rows. */
+export interface NavSettingsState {
+  /** Last accepted style. */
+  style: NavStyle
+  /** Last accepted anchor edge (default while the scope is absent/loading). */
+  align: RailAlign
+  /** Last accepted band height tier. */
+  bandHeight: BandHeight
+  /** Last accepted jump scroll mode. */
+  scrollBehavior: ScrollMode
+  /** Turn-count badge display mode. */
+  showCount: ShowMode
+  /** Search button display mode. */
+  showSearch: ShowMode
+  /** Quick settings gear display mode. */
+  showQuickSettings: ShowMode
+  /** Favorite filter button display mode. */
+  showFavorites: ShowMode
+  /** 翻页标记显示模式（show=常显 / peek=浮现 / hide=隐藏） */
+  showPaging: ShowMode
+  /** 搜索内容范围（多选；用户必选） */
+  searchScopes: SearchScope[]
+  /** 导航栏偏移距离（px，随左右对齐自适应） */
+  railOffset: number
+  /** Hover cascade card count. */
+  cardCount: CardCount
+  /** 悬浮卡内容块（多选：轮次 / 用时 / 收藏） */
+  cardItems: CardItem[]
+  /** 刻度色调（codex 刻度轨；minimal 忽略） */
+  markTone: MarkTone
+  /** Whether the user layer overrides the composition default. */
+  overridden: boolean
+}
+
+/** Reactive handle over the plugin's durable settings section. */
+export class NavSettingsController {
+  private scope: SettingsScope<NavSettingsSection> | undefined
+  private readonly listeners = new Set<() => void>()
+  private unsubscribe: () => void = () => {}
+  private state: NavSettingsState = {
+    style: DEFAULT_STYLE,
+    align: DEFAULT_ALIGN,
+    bandHeight: DEFAULT_BAND,
+    scrollBehavior: DEFAULT_SCROLL,
+    showCount: DEFAULT_SHOW,
+    showSearch: DEFAULT_SHOW,
+    showQuickSettings: DEFAULT_SHOW,
+    showFavorites: DEFAULT_SHOW,
+    showPaging: DEFAULT_PAGING.minimal,
+    searchScopes: [...DEFAULT_SEARCH_SCOPES],
+    railOffset: DEFAULT_RAIL_OFFSET,
+    cardCount: DEFAULT_CARD_COUNT[DEFAULT_STYLE],
+    cardItems: [...DEFAULT_CARD_ITEMS],
+    markTone: DEFAULT_MARK_TONE,
+    overridden: false,
+  }
+
+  /**
+   * Bind the namespace scope once the settings surface is present.
+   * A no-op after the first bind.
+   */
+  attach(binder: SettingsScopeBinderLike): void {
+    if (this.scope !== undefined) return
+    this.scope = binder.bind<NavSettingsSection>({ namespace: MGCN_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.style === this.state.style
+        && next.align === this.state.align && next.bandHeight === this.state.bandHeight
+        && next.cardCount === this.state.cardCount
+        && next.scrollBehavior === this.state.scrollBehavior
+        && next.showCount === this.state.showCount
+        && next.showSearch === this.state.showSearch
+        && next.showQuickSettings === this.state.showQuickSettings
+        && next.overridden === this.state.overridden) return
+      this.state = next
+      for (const listener of this.listeners) listener()
+    })
+  }
+
+  /** 当前生效风格的 styles.<style> 段（快照内读取，供逐风格独立取值） */
+  private styleSection(snapshot: SettingsScopeSnapshot<NavSettingsSection>, style: NavStyle): StyleWireSection | undefined {
+    return snapshot.value?.styles?.[style]
+  }
+
+  private derive(snapshot: SettingsScopeSnapshot<NavSettingsSection>): NavSettingsState {
+    const user = snapshot.user as NavSettingsSection | undefined
+    const general = snapshot.value?.general
+    const ready = snapshot.status === 'ready'
+    const style = ready && isNavStyle(general?.style) ? general.style : DEFAULT_STYLE
+    const active = this.styleSection(snapshot, style)
+    return {
+      style,
+      align: ready && isRailAlign(general?.align) ? general.align : DEFAULT_ALIGN,
+      bandHeight: ready && isBandHeight(active?.bandHeight) ? active.bandHeight : DEFAULT_BAND,
+      cardCount: ready && isCardCount(active?.cardCount) ? active.cardCount : DEFAULT_CARD_COUNT[style],
+      cardItems: ready && isCardItems(active?.cardItems) ? active.cardItems : [...DEFAULT_CARD_ITEMS],
+      markTone: ready && isMarkTone(active?.markTone) ? active.markTone : DEFAULT_MARK_TONE,
+      scrollBehavior: ready && isScrollMode(general?.scrollBehavior) ? general.scrollBehavior : DEFAULT_SCROLL,
+      showCount: ready ? coerceShowMode(general?.showCount) : DEFAULT_SHOW,
+      showSearch: ready ? coerceShowMode(general?.showSearch) : DEFAULT_SHOW,
+      showQuickSettings: ready ? coerceShowMode(general?.showQuickSettings) : DEFAULT_SHOW,
+      showFavorites: ready ? coerceShowMode(general?.showFavorites) : DEFAULT_SHOW,
+      showPaging: ready ? coercePagingMode(active?.showPaging, DEFAULT_PAGING[style]) : DEFAULT_PAGING[style],
+      searchScopes: ready && isSearchScopes(general?.searchScopes) ? general.searchScopes : [...DEFAULT_SEARCH_SCOPES],
+      railOffset: ready && typeof general?.railOffset === 'number' && general.railOffset >= 0 && general.railOffset <= 32
+        ? Math.round(general.railOffset)
+        : DEFAULT_RAIL_OFFSET,
+      overridden: user !== undefined && (user.general !== undefined || user.styles !== undefined),
+    }
+  }
+
+  /** Release the scope subscription. */
+  dispose(): void {
+    this.unsubscribe()
+    this.listeners.clear()
+  }
+
+  /** 乐观提交：更新状态并立即通知（UI 即时反映） */
+  private commit(next: NavSettingsState): void {
+    this.state = next
+    for (const listener of this.listeners) listener()
+  }
+
+  /** 当前 general 段（setter 整段写回用） */
+  private get general(): NavSettingsSection['general'] {
+    return {
+      style: this.state.style,
+      align: this.state.align,
+      scrollBehavior: this.state.scrollBehavior,
+      showCount: this.state.showCount,
+      showSearch: this.state.showSearch,
+      showQuickSettings: this.state.showQuickSettings,
+      showFavorites: this.state.showFavorites,
+      searchScopes: this.state.searchScopes,
+      railOffset: this.state.railOffset,
+    }
+  }
+
+  /** 当前风格段的完整值（setter 局部 patch 的基础） */
+  private get styleValues(): { bandHeight: BandHeight; cardCount: CardCount; cardItems: CardItem[]; markTone: MarkTone; showPaging: ShowMode } {
+    return {
+      bandHeight: this.state.bandHeight,
+      cardCount: this.state.cardCount,
+      cardItems: this.state.cardItems,
+      markTone: this.state.markTone,
+      showPaging: this.state.showPaging,
+    }
+  }
+
+  /** 按当前风格构造 write 的 styles 段（只含当前风格键，绝不染指其他风格段） */
+  private stylePatch(extra: Partial<StyleWireSection>): NavSettingsSection['styles'] {
+    const section = { ...this.styleValues, ...extra }
+    const patch: Partial<Record<NavStyle, StyleWireSection>> = {}
+    patch[this.state.style] = section
+    return patch
+  }
+
+  /** @returns the current state (stable reference until the next change). */
+  getSnapshot(): NavSettingsState {
+    return this.state
+  }
+
+  /** Observe state replacements; returns the disposer. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  /**
+   * 写回宿主：scope.set 契约只接受 section 内**标量**字段，嵌套 section
+   * （general/styles 对象）无法经它持久化，所以走 host 桥
+   * （POST /mega-chat-nav/settings → settings.update 深层 merge + revision 围栏）。
+   */
+  private write(patch: NavSettingsSection): void {
+    if (this.scope === undefined) return
+    const revision = this.scope.getSnapshot().revision
+    void fetch('/mega-chat-nav/settings', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ patch, revision: revision ?? undefined }),
+    })
+      .then((resp) => resp.json().catch(() => ({})) as Promise<{ ok?: boolean }>)
+      .then((data) => {
+        if (!data.ok) console.error('[mega-chat-nav] settings write rejected')
+      })
+      .catch((e: unknown) => console.error('[mega-chat-nav] settings write failed:', e))
+  }
+
+  /** Route the user's anchor-edge choice to the Host document. */
+  setAlign(align: RailAlign): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, align })
+    this.write({ general: { ...this.general, align } })
+  }
+
+  /** Route the user's style choice to the Host document（切换后随即载入该风格自己的独立配置） */
+  setStyle(style: NavStyle): void {
+    if (this.scope === undefined) return
+    const snapshot = this.scope.getSnapshot()
+    const next = this.derive({ ...snapshot, value: { ...snapshot.value, general: { ...snapshot.value?.general, style } } })
+    this.commit({ ...next, overridden: this.state.overridden })
+    this.write({ general: { ...this.general, style } })
+  }
+
+  /** Route the user's band-height choice to the Host document（写入当前风格的独立段） */
+  setBandHeight(band: BandHeight): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, bandHeight: band })
+    this.write({ styles: this.stylePatch({ bandHeight: band }) })
+  }
+
+  /** Route the user's scroll-mode choice to the Host document. */
+  setScrollMode(mode: ScrollMode): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, scrollBehavior: mode })
+    this.write({ general: { ...this.general, scrollBehavior: mode } })
+  }
+
+  /** Route the user's count-badge display mode to the Host document. */
+  setShowCount(mode: ShowMode): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, showCount: mode })
+    this.write({ general: { ...this.general, showCount: mode } })
+  }
+
+  /** Route the user's search-button display mode to the Host document. */
+  setShowSearch(mode: ShowMode): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, showSearch: mode })
+    this.write({ general: { ...this.general, showSearch: mode } })
+  }
+
+  /** Route the user's quick-settings display mode to the Host document. */
+  setShowQuickSettings(mode: ShowMode): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, showQuickSettings: mode })
+    this.write({ general: { ...this.general, showQuickSettings: mode } })
+  }
+
+  /** Route the user's favorite-button display mode to the Host document. */
+  setShowFavorites(mode: ShowMode): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, showFavorites: mode })
+    this.write({ general: { ...this.general, showFavorites: mode } })
+  }
+
+  /** Route the user's paging-marker display mode to the Host document（写入当前风格独立段） */
+  setShowPaging(mode: ShowMode): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, showPaging: mode })
+    this.write({ styles: this.stylePatch({ showPaging: mode }) })
+  }
+
+  /** Route the user's search-scope selection to the Host document（用户必选，强制保留且置于首位） */
+  setSearchScopes(scopes: SearchScope[]): void {
+    if (this.scope === undefined) return
+    const normalized = ['user' as SearchScope, ...scopes.filter((s) => s !== 'user')]
+    this.commit({ ...this.state, searchScopes: normalized })
+    this.write({ general: { ...this.general, searchScopes: normalized } })
+  }
+
+  /** Route the user's rail-offset choice to the Host document（0-32px 取整钳制） */
+  setRailOffset(offset: number): void {
+    if (this.scope === undefined) return
+    const clamped = Math.max(RAIL_OFFSET_MIN, Math.min(RAIL_OFFSET_MAX, Math.round(offset)))
+    this.commit({ ...this.state, railOffset: clamped })
+    this.write({ general: { ...this.general, railOffset: clamped } })
+  }
+
+  /** Route the user's cascade-card count to the Host document（写入当前风格的独立段） */
+  setCardCount(count: CardCount): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, cardCount: count })
+    this.write({ styles: this.stylePatch({ cardCount: count }) })
+  }
+
+  /** Route the user's card-content selection to the Host document（写入当前风格的独立段） */
+  setCardItems(items: CardItem[]): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, cardItems: items })
+    this.write({ styles: this.stylePatch({ cardItems: items }) })
+  }
+
+  /** Route the user's mark-tone choice to the Host document（codex 刻度色调；写入当前风格段） */
+  setMarkTone(tone: MarkTone): void {
+    if (this.scope === undefined) return
+    this.commit({ ...this.state, markTone: tone })
+    this.write({ styles: this.stylePatch({ markTone: tone }) })
+  }
+}