dsh-mega-chat-nav 0.1.1

package/lib/client/locales.js

@@ -0,0 +1,142 @@
+/**
+ * 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': '正在搜索…',
+};
+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…',
+};

package/lib/client/pure.js

@@ -0,0 +1,61 @@
+/** TabGate：chat 视图可见（R-10）——滚动容器存在且几何 >0 */
+export function isChatViewVisible(doc) {
+    const el = doc.querySelector('[data-conversation-scroll]');
+    if (!el)
+        return false;
+    const r = el.getBoundingClientRect();
+    return r.width > 0 && r.height > 0;
+}
+/** TabGate：Trajectory（轨迹）视图在场时 nav 停用 */
+export function hasTrajectoryView(doc) {
+    return !!doc.querySelector('[data-trajectory-scroll]');
+}
+/** 锚点规则 → 阅读线 Y（视口坐标系） */
+export function readingLineY(viewport, rule) {
+    switch (rule) {
+        case 'top': return viewport.top;
+        case 'center': return viewport.top + viewport.height * 0.5;
+        case 'line40':
+        default: return viewport.top + viewport.height * 0.4;
+    }
+}
+/** 距阅读线最近条目索引（40% 线主流判据；无条目返回 -1） */
+export function nearestIndex(total, line, yOf) {
+    if (total <= 0)
+        return -1;
+    let best = 0;
+    let bestDist = Infinity;
+    for (let i = 0; i < total; i++) {
+        const d = Math.abs(yOf(i) - line);
+        if (d < bestDist) {
+            bestDist = d;
+            best = i;
+        }
+    }
+    return best;
+}
+/** 虚拟滚动窗口（可见 + 前后缓冲；hover/current 由调用方钉住） */
+export function virtualWindow(total, scrollTop, viewportH, itemH, buffer = 24) {
+    if (total <= 0 || itemH <= 0)
+        return { start: 0, end: 0 };
+    const start = Math.max(0, Math.floor(scrollTop / itemH) - buffer);
+    const end = Math.min(total, Math.ceil((scrollTop + viewportH) / itemH) + buffer);
+    return { start, end };
+}
+/** 相对时间（秒/分钟/小时/天） */
+export function formatTime(ts, now = Date.now()) {
+    const d = Math.max(0, now - ts);
+    if (d < 60_000)
+        return `${Math.floor(d / 1000)}s`;
+    if (d < 3_600_000)
+        return `${Math.floor(d / 60_000)}m`;
+    if (d < 86_400_000)
+        return `${Math.floor(d / 3_600_000)}h`;
+    return `${Math.floor(d / 86_400_000)}d`;
+}
+/** 截断到 n 字符并加省略号 */
+export function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, Math.max(0, n - 1)) + '…';
+}

package/lib/client/settings.js

@@ -0,0 +1,369 @@
+/**
+ * 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
+ */
+/** 风格选项：简约 / codex（时间线刻度）/ deepseek（用户消息面板，常态短横折叠） */
+export const STYLE_OPTIONS = ['minimal', 'codex', 'deepseek'];
+/** 停靠侧选项 */
+export const ALIGN_OPTIONS = ['left', 'right'];
+/** 节点栏条带高度档位 */
+export const BAND_OPTIONS = ['compact', 'standard', 'tall'];
+/** 跳转动画方式 */
+export const SCROLL_OPTIONS = ['smooth', 'instant'];
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export const SHOW_OPTIONS = ['show', 'peek', 'hide'];
+/** 翻页标记显示策略（按风格独立默认）：minimal 常显 / codex 隐藏 / deepseek 浮现 */
+export const DEFAULT_PAGING = {
+    minimal: 'show',
+    codex: 'hide',
+    deepseek: 'peek',
+};
+/** 搜索内容范围（多选；用户必选） */
+export const SEARCH_SCOPE_OPTIONS = ['user', 'assistant', 'tool'];
+export const DEFAULT_SEARCH_SCOPES = ['user', 'assistant', 'tool'];
+/** 悬停卡片数量 */
+export const CARD_OPTIONS = [1, 3, 5];
+/** 悬浮卡默认数量（按风格独立）：minimal 3 张 / codex 1 张 / deepseek 1 张（无悬浮卡能力，占位） */
+export const DEFAULT_CARD_COUNT = {
+    minimal: 3,
+    codex: 1,
+    deepseek: 1,
+};
+/** 悬浮卡内容块（多选） */
+export const CARD_ITEM_OPTIONS = ['turn', 'duration', 'favorite'];
+export const DEFAULT_CARD_ITEMS = ['turn', 'duration', 'favorite'];
+/** 刻度色调：柔和（低对比）/ 深邃（高对比、清晰） */
+export const MARK_TONE_OPTIONS = ['soft', 'deep'];
+export const DEFAULT_MARK_TONE = 'deep';
+export const DEFAULT_STYLE = 'minimal';
+export const DEFAULT_ALIGN = 'left';
+export const DEFAULT_BAND = 'standard';
+export const DEFAULT_SCROLL = 'smooth';
+export const DEFAULT_SHOW = '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 = {
+    minimal: { compact: 144, standard: 204, tall: 274 },
+    codex: { compact: 140, standard: 210, tall: 280 },
+    deepseek: { compact: 160, standard: 220, tall: 280 },
+};
+/** 风格 → 能力表 */
+export const STYLE_CAPABILITIES = {
+    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) {
+    return ALIGN_OPTIONS.includes(value);
+}
+/** Narrow a raw section value to the style field. */
+function isNavStyle(value) {
+    return STYLE_OPTIONS.includes(value);
+}
+/** 兼容旧 boolean 配置：true → show，false → hide；新值走枚举校验 */
+function coerceShowMode(value) {
+    if (typeof value === 'boolean')
+        return value ? 'show' : 'hide';
+    return isShowMode(value) ? value : DEFAULT_SHOW;
+}
+/** 翻页标记显示模式转换（默认按风格：minimal show / codex hide） */
+function coercePagingMode(value, fallback) {
+    if (typeof value === 'boolean')
+        return value ? 'show' : 'hide';
+    return isShowMode(value) ? value : fallback;
+}
+function isShowMode(value) {
+    return SHOW_OPTIONS.includes(value);
+}
+function isCardCount(value) {
+    return CARD_OPTIONS.includes(value);
+}
+function isBandHeight(value) {
+    return BAND_OPTIONS.includes(value);
+}
+function isSearchScopes(value) {
+    return Array.isArray(value)
+        && value.every((s) => SEARCH_SCOPE_OPTIONS.includes(s));
+}
+function isCardItems(value) {
+    return Array.isArray(value)
+        && value.every((item) => CARD_ITEM_OPTIONS.includes(item));
+}
+function isMarkTone(value) {
+    return MARK_TONE_OPTIONS.includes(value);
+}
+function isScrollMode(value) {
+    return SCROLL_OPTIONS.includes(value);
+}
+/** Reactive handle over the plugin's durable settings section. */
+export class NavSettingsController {
+    scope;
+    listeners = new Set();
+    unsubscribe = () => { };
+    state = {
+        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) {
+        if (this.scope !== undefined)
+            return;
+        this.scope = binder.bind({ 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> 段（快照内读取，供逐风格独立取值） */
+    styleSection(snapshot, style) {
+        return snapshot.value?.styles?.[style];
+    }
+    derive(snapshot) {
+        const user = snapshot.user;
+        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() {
+        this.unsubscribe();
+        this.listeners.clear();
+    }
+    /** 乐观提交：更新状态并立即通知（UI 即时反映） */
+    commit(next) {
+        this.state = next;
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** 当前 general 段（setter 整段写回用） */
+    get 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 的基础） */
+    get styleValues() {
+        return {
+            bandHeight: this.state.bandHeight,
+            cardCount: this.state.cardCount,
+            cardItems: this.state.cardItems,
+            markTone: this.state.markTone,
+            showPaging: this.state.showPaging,
+        };
+    }
+    /** 按当前风格构造 write 的 styles 段（只含当前风格键，绝不染指其他风格段） */
+    stylePatch(extra) {
+        const section = { ...this.styleValues, ...extra };
+        const patch = {};
+        patch[this.state.style] = section;
+        return patch;
+    }
+    /** @returns the current state (stable reference until the next change). */
+    getSnapshot() {
+        return this.state;
+    }
+    /** Observe state replacements; returns the disposer. */
+    subscribe(listener) {
+        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 围栏）。
+     */
+    write(patch) {
+        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(() => ({})))
+            .then((data) => {
+            if (!data.ok)
+                console.error('[mega-chat-nav] settings write rejected');
+        })
+            .catch((e) => console.error('[mega-chat-nav] settings write failed:', e));
+    }
+    /** Route the user's anchor-edge choice to the Host document. */
+    setAlign(align) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        if (this.scope === undefined)
+            return;
+        const normalized = ['user', ...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) {
+        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) {
+        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) {
+        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) {
+        if (this.scope === undefined)
+            return;
+        this.commit({ ...this.state, markTone: tone });
+        this.write({ styles: this.stylePatch({ markTone: tone }) });
+    }
+}

package/lib/client/virtual/VirtualList.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 共享虚拟滚动列表：可见窗口 ≤50 + 前后缓冲 24，hover/current 钉住（C-5）
+import { useMemo } from 'react';
+import { virtualWindow } from "../pure.js";
+export function VirtualList(props) {
+    const { items, itemHeight, viewportHeight, scrollTop, pinned, overscan = 24 } = props;
+    const win = useMemo(() => virtualWindow(items.length, scrollTop, viewportHeight, itemHeight, overscan), [items.length, scrollTop, viewportHeight, itemHeight, overscan]);
+    const rows = [];
+    for (let i = win.start; i < win.end; i++) {
+        const item = items[i];
+        const k = props.keyOf(item, i);
+        // hover/current 钉住：若在窗口外仍渲染（固定位置）
+        const isPinned = pinned?.has(k) ?? false;
+        if (i < win.start || i >= win.end) {
+            if (!isPinned)
+                continue;
+        }
+        rows.push(_jsx("div", { className: "mgs-vitem", style: { position: 'absolute', top: i * itemHeight, height: itemHeight, left: 0, right: 0 }, children: props.renderItem(item, i) }, k));
+    }
+    return (_jsx("div", { className: "mgs-vlist", ref: props.listRef, tabIndex: 0, role: "listbox", "aria-label": "messages", style: { position: 'relative', height: viewportHeight, overflowY: 'auto' }, onScroll: (e) => props.onScrollTopChange(e.target.scrollTop), onKeyDown: props.onKeyDown, children: _jsx("div", { style: { position: 'relative', height: items.length * itemHeight }, children: rows }) }));
+}