dsh-mega-chat-nav 0.1.1

package/lib/client/index.js

@@ -0,0 +1,312 @@
+import { RailDispatch } from "./components/RailDispatch.js";
+import { SettingsPage } from "./components/settings/SettingsPage.js";
+import { StandaloneSettings } from "./components/settings/StandaloneSettings.js";
+import { NavSettingsController } from "./settings.js";
+import { en, zh } from "./locales.js";
+import { goTo } from "./jump.js";
+/** Locale namespace this plugin owns. */
+const NS = 'mega-chat-nav';
+/** Services required by this plugin. */
+export const inject = ['slots', 'locale', 'sessions'];
+function sessionsOf(ctx) {
+    return ctx.sessions;
+}
+/** 提问行 kind */
+const QUESTION_KINDS = ['user', 'steering'];
+/** 消息首文本块；缺省空串 */
+function firstTextBlock(content) {
+    const block = content?.find((part) => typeof part?.text === 'string');
+    return block?.text ?? '';
+}
+/** 从节点窗口提取提问行（kind 过滤 + 首文本 + 按 anchorSeq 排序） */
+function extractQuestionRows(nodes) {
+    return [...nodes]
+        .filter((node) => QUESTION_KINDS.includes(node.kind ?? ''))
+        .map((node) => {
+        const payload = (typeof node.data === 'object' && node.data !== null ? node.data : {});
+        return {
+            key: node.key,
+            anchorSeq: node.anchorSeq,
+            seq: payload.seq ?? -1,
+            time: payload.time ?? 0,
+            text: firstTextBlock(payload.content),
+        };
+    })
+        .sort((a, b) => a.anchorSeq - b.anchorSeq);
+}
+function claimApply() {
+    if (globalThis.__dshMegaChatNavApplied === true)
+        return false;
+    globalThis.__dshMegaChatNavApplied = true;
+    return true;
+}
+function releaseApply() {
+    globalThis.__dshMegaChatNavApplied = undefined;
+}
+/** Map the session snapshot to the jump-loop port surface. */
+function jumpPortsFor(ctx, sessionId) {
+    const sessions = sessionsOf(ctx);
+    return {
+        snap: () => {
+            const binding = sessions.binding(sessionId);
+            const snap = binding?.session.getSnapshot();
+            if (snap === undefined)
+                return undefined;
+            return {
+                openState: snap.openState ?? '',
+                hasMore: snap.hasMore ?? false,
+                loadingOlder: snap.loadingOlder ?? false,
+                rows: (snap.chat?.nodes?.values() ?? []),
+            };
+        },
+        loadMore: async () => {
+            const binding = sessions.binding(sessionId);
+            if (binding === undefined)
+                throw new Error('session unavailable');
+            await binding.session.loadOlder();
+        },
+        active: () => document.querySelector('[data-chat-flow]') !== null,
+        locate: (key) => {
+            const rows = Array.from(document.querySelectorAll('[data-chat-anchor-key]'));
+            for (const row of rows) {
+                if (row.dataset.chatAnchorKey === key)
+                    return row;
+            }
+            // 包含兜底（key 为完整锚点串，唯一命中）
+            for (const row of rows) {
+                const k = row.dataset.chatAnchorKey;
+                if (k !== undefined && k.includes(key))
+                    return row;
+            }
+            // seq 兜底：取最后一个匹配（防误命中前一行）
+            if (key.startsWith('seq:')) {
+                const n = key.slice(4);
+                let found = null;
+                for (const row of rows) {
+                    const k = row.dataset.chatAnchorKey;
+                    if (k !== undefined && k.includes(n))
+                        found = row;
+                }
+                if (found !== null)
+                    return found;
+            }
+            return null;
+        },
+        reveal: (row, mode) => {
+            // 目标行顶部与视口顶留 12px 间距（不贴顶，视觉更舒适）
+            const scrollToRow = () => {
+                const port = document.querySelector('[data-conversation-scroll]');
+                if (port !== null) {
+                    const rowTop = row.getBoundingClientRect().top - port.getBoundingClientRect().top + port.scrollTop;
+                    port.scrollTo({ top: rowTop - 12, behavior: mode });
+                }
+                else {
+                    row.scrollIntoView({ behavior: mode, block: 'start' });
+                }
+            };
+            scrollToRow();
+            // 正文在 loadOlder prepend 落地后可能自动滚回底部（跟随滚动）：
+            // 校验式重滚——仅当目标行明显偏离视口顶（被正文回滚/未到位）才重滚，
+            // 用户主动滚动阅读时不干预
+            const ensure = () => {
+                const port = document.querySelector('[data-conversation-scroll]');
+                if (port === null)
+                    return;
+                const rowRect = row.getBoundingClientRect();
+                const portRect = port.getBoundingClientRect();
+                const offset = rowRect.top - portRect.top;
+                if (offset < -60 || offset > 120)
+                    scrollToRow();
+            };
+            window.setTimeout(ensure, 300);
+            window.setTimeout(ensure, 800);
+            // 跳转确认高亮：监听目标气泡**进入视口（可见）**后才开始闪烁；
+            // 背景经 transition 平滑渐变（非突兀切换），主题色两轮缓慢变化
+            const bubble = row.querySelector('[class*="bubble"]')
+                ?? row.querySelector('[class*="messageBody"], [class*="bubbleBody"]');
+            if (bubble !== null) {
+                const original = bubble.style.background;
+                const themeBg = 'color-mix(in srgb, var(--dsw-alias-brand-primary) 38%, transparent)';
+                bubble.style.transition = 'background 350ms ease';
+                const paint = (on) => {
+                    bubble.style.background = on ? themeBg : original;
+                };
+                // 轮询等待气泡可见（进入滚动容器视口）；4s 兜底后也执行
+                const waitVisible = () => new Promise((resolve) => {
+                    const port = document.querySelector('[data-conversation-scroll]');
+                    let tries = 0;
+                    const check = () => {
+                        const r = bubble.getBoundingClientRect();
+                        const portTop = port !== null ? port.getBoundingClientRect().top : 0;
+                        const portBottom = port !== null ? port.getBoundingClientRect().bottom : window.innerHeight;
+                        if ((r.bottom > portTop && r.top < portBottom) || tries > 40)
+                            resolve();
+                        else {
+                            tries += 1;
+                            window.setTimeout(check, 100);
+                        }
+                    };
+                    check();
+                });
+                void waitVisible().then(() => {
+                    // 两轮切换共约 1.5s：渐变到主题色 → 渐变回 → 再切 → 再回
+                    paint(true);
+                    window.setTimeout(() => paint(false), 400);
+                    window.setTimeout(() => paint(true), 800);
+                    window.setTimeout(() => paint(false), 1200);
+                    window.setTimeout(() => { bubble.style.transition = ''; }, 1500);
+                });
+            }
+        },
+        scrollport: () => document.querySelector('[data-conversation-scroll]'),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => window.setTimeout(resolve, ms)),
+    };
+}
+/**
+ * The session's `msgNavMessages` projection face (getSnapshot + subscribe).
+ * Undefined when the session is not bound or the host unit is not registered
+ * (e.g. a headless composition) — the strip then shows live-window dots only.
+ */
+function navProjectionOf(ctx, sessionId) {
+    const face = sessionsOf(ctx).binding(sessionId)?.session.projections.faceOf('msgNavMessages');
+    if (face === undefined)
+        return undefined;
+    return {
+        getSnapshot: () => face.getSnapshot(),
+        subscribe: (listener) => face.subscribe(listener),
+    };
+}
+function createInject(ctx, settings) {
+    const sessions = sessionsOf(ctx);
+    return {
+        readQuestions: (sessionId) => {
+            const snap = sessions.binding(sessionId)?.session.getSnapshot();
+            if (snap === undefined || snap.chat?.nodes === undefined)
+                return [];
+            return extractQuestionRows(snap.chat.nodes.values());
+        },
+        subscribeList: (cb) => sessions.list.subscribe(cb),
+        subscribeContent: (sessionId, cb) => {
+            const binding = sessions.binding(sessionId);
+            if (binding === undefined)
+                return () => { };
+            return binding.session.subscribe(cb);
+        },
+        questionProjection: (sessionId) => navProjectionOf(ctx, sessionId),
+        jump: (sessionId, key, seq, currentSeq) => {
+            const ports = jumpPortsFor(ctx, sessionId);
+            ports.report = (code) => {
+                // Surface the failure through the component via a DOM event the
+                // strip listens for; simplest reliable cross-boundary channel here.
+                window.dispatchEvent(new CustomEvent('mega-chat-nav:jump-failed', { detail: code }));
+            };
+            ports.onLoading = (loading, pages) => {
+                window.dispatchEvent(new CustomEvent('mega-chat-nav:jump-loading', { detail: { loading, pages } }));
+            };
+            void goTo(ports, key, {}, settings.getSnapshot().scrollBehavior, seq, currentSeq);
+        },
+        style: () => settings.getSnapshot().style,
+        setStyle: (style) => settings.setStyle(style),
+        align: () => settings.getSnapshot().align,
+        subscribeSettings: (cb) => settings.subscribe(cb),
+        setAlign: (align) => settings.setAlign(align),
+        bandHeight: () => settings.getSnapshot().bandHeight,
+        setBandHeight: (band) => settings.setBandHeight(band),
+        scrollBehavior: () => settings.getSnapshot().scrollBehavior,
+        setScrollMode: (mode) => settings.setScrollMode(mode),
+        showCount: () => settings.getSnapshot().showCount,
+        setShowCount: (mode) => settings.setShowCount(mode),
+        showSearch: () => settings.getSnapshot().showSearch,
+        setShowSearch: (mode) => settings.setShowSearch(mode),
+        showQuickSettings: () => settings.getSnapshot().showQuickSettings,
+        setShowQuickSettings: (mode) => settings.setShowQuickSettings(mode),
+        showFavorites: () => settings.getSnapshot().showFavorites,
+        setShowFavorites: (mode) => settings.setShowFavorites(mode),
+        showPaging: () => settings.getSnapshot().showPaging,
+        setShowPaging: (mode) => settings.setShowPaging(mode),
+        searchScopes: () => settings.getSnapshot().searchScopes,
+        setSearchScopes: (scopes) => settings.setSearchScopes(scopes),
+        railOffset: () => settings.getSnapshot().railOffset,
+        setRailOffset: (offset) => settings.setRailOffset(offset),
+        cardCount: () => settings.getSnapshot().cardCount,
+        setCardCount: (count) => settings.setCardCount(count),
+        cardItems: () => settings.getSnapshot().cardItems,
+        setCardItems: (items) => settings.setCardItems(items),
+        markTone: () => settings.getSnapshot().markTone,
+        setMarkTone: (tone) => settings.setMarkTone(tone),
+    };
+}
+/**
+ * Register the mega-chat-nav surface.
+ * @param ctx - client root context.
+ */
+export function apply(ctx) {
+    if (!claimApply())
+        return;
+    ctx.effect(() => releaseApply, 'mega-chat-nav: apply claim');
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'mega-chat-nav: dictionaries');
+    const t = ctx.locale.bind(NS);
+    const settings = new NavSettingsController();
+    const injected = createInject(ctx, settings);
+    ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+        name: 'shell.overlay',
+        id: 'mega-chat-nav',
+        order: 900,
+        locale: NS,
+        inject: () => ({ injected }),
+    }, RailDispatch));
+    // mega-settings 成员契约：元信息 seat + 页面 seat（宿主缺席 → 静默等待 → 自足）
+    ctx.slots.inject('mega.settings.member', () => ctx.slots.register({
+        name: 'mega.settings.member',
+        id: 'mega-chat-nav',
+        order: 10,
+        label: () => t('label'),
+        inject: () => ({ description: () => t('desc'), version: PKG_VERSION }),
+    }, ListRow));
+    ctx.slots.inject('mega.settings.member.page', () => ctx.slots.register({
+        name: 'mega.settings.member.page',
+        key: 'mega-chat-nav',
+        order: 10,
+        label: () => t('label'),
+        locale: NS,
+        inject: () => ({ injected }),
+    }, SettingsPage));
+    // 插件页配置入口：仅当未被 mega-settings 收纳时注册（收纳后注销，避免重复入口）。
+    // mega-settings 可能晚于本插件加载——注册后订阅 member 条目，宿主出现即注销。
+    {
+        let tabDispose = null;
+        const ensurePluginsTab = () => {
+            const hosted = (ctx.slots.entries?.('mega.settings.member')?.length ?? 0) > 0;
+            if (hosted) {
+                tabDispose?.();
+                tabDispose = null;
+            }
+            else if (tabDispose === null) {
+                tabDispose = ctx.slots.register({
+                    name: 'settings.plugins.tab',
+                    id: 'mega-chat-nav',
+                    order: 100,
+                    label: () => t('label'),
+                    locale: NS,
+                    inject: () => ({ injected, slots: ctx.slots }),
+                }, StandaloneSettings);
+            }
+        };
+        ensurePluginsTab();
+        const offMember = ctx.slots.subscribe?.('mega.settings.member', ensurePluginsTab);
+        ctx.effect(() => () => {
+            tabDispose?.();
+            tabDispose = null;
+            offMember?.();
+        }, 'mega-chat-nav: plugins tab ledger');
+    }
+    // 设置控制器挂载：settingsScope 服务就绪后绑定 scope（未就绪时配置读写走默认值降级）
+    ctx.inject(['settingsScope'], (scopeCtx) => {
+        settings.attach(scopeCtx.get('settingsScope'));
+    });
+}
+/** 成员列表行占位（元信息 seat 用；宿主自绘列表时不渲染） */
+function ListRow() {
+    return null;
+}

package/lib/client/jump.js

@@ -0,0 +1,255 @@
+// 跳转编排（client 装配层自研）：定位目标行——按方向分流（向下滚动 / 向上补历史），
+// 等待渲染并滚动；失败回退。结果码与词条绑定（jump-failed 事件契约）。
+//
+// 关键语义：chat.nodes 只是「虚拟渲染窗口」（DOM 渲染行），目标行在已加载范围内
+// 但未渲染时**不能**当作「需要加载更早历史」——必须按目标 seq 与渲染窗口的关系分流。
+const BUDGET = {
+    totalTimeoutMs: 30_000,
+    maxPages: 300,
+    rowWaitMs: 8_000,
+    pollMs: 60,
+};
+/** 行是否为可渲染锚点行 */
+function isVisibleRow(row) {
+    return row.visibility !== 'hidden';
+}
+/** 快照中是否已含目标行 */
+function hasTarget(rows, key) {
+    for (const row of rows) {
+        if (isVisibleRow(row) && row.key === key)
+            return true;
+    }
+    return false;
+}
+/** 渲染窗口的锚点序号极值；空窗口返回 null */
+function seqRange(rows) {
+    let min = null;
+    let max = null;
+    for (const row of rows) {
+        if (min === null || row.anchorSeq < min)
+            min = row.anchorSeq;
+        if (max === null || row.anchorSeq > max)
+            max = row.anchorSeq;
+    }
+    return min === null || max === null ? null : { min, max };
+}
+/** 当前窗口最小锚点序号；空窗口返回 null */
+function smallestSeq(rows) {
+    const range = seqRange(rows);
+    return range === null ? null : range.min;
+}
+/** 回退目标：排除指定 key 的最近可渲染行（取最新锚点序号） */
+function retreatTo(rows, excludeKey) {
+    let best = null;
+    for (const row of rows) {
+        if (row.visibility === 'hidden')
+            continue;
+        if (row.key === excludeKey)
+            continue;
+        if (best === null || row.anchorSeq > best.anchorSeq)
+            best = { key: row.key, anchorSeq: row.anchorSeq };
+    }
+    return best;
+}
+/** 等待某行渲染（预算内轮询）；视图失活返回 null */
+async function waitForRow(ports, rowKey, pollMs, rowWaitMs) {
+    for (let waited = 0; waited <= rowWaitMs; waited += pollMs) {
+        if (!ports.active())
+            return null;
+        const row = ports.locate(rowKey);
+        if (row !== null)
+            return row;
+        await ports.sleep(pollMs);
+    }
+    return null;
+}
+/**
+ * 滚动定位：按方向逐屏滚动（触发虚拟渲染）直至目标行出现或到达边界。
+ * 若快照渲染窗口已含目标但 DOM 尚未挂载（渲染延迟），放慢等待 DOM。
+ * 返回命中的行；未命中返回 null。
+ */
+async function scrollLocate(ports, key, dir, maxSteps, stepMs) {
+    const port = ports.scrollport();
+    if (port === null)
+        return null;
+    for (let i = 0; i < maxSteps; i++) {
+        const row = ports.locate(key);
+        if (row !== null)
+            return row;
+        const before = port.scrollTop;
+        const step = Math.max(200, Math.round(port.clientHeight * 0.4));
+        port.scrollBy({ top: dir * step });
+        await ports.sleep(stepMs);
+        const floor = Math.max(0, port.scrollHeight - port.clientHeight);
+        if (Math.abs(port.scrollTop - before) < 2) {
+            // 到边界：反向回扫若干步（虚拟渲染滞后可能已滚过头）
+            if (dir === 1) {
+                for (let i = 0; i < 10; i++) {
+                    const row = ports.locate(key);
+                    if (row !== null)
+                        return row;
+                    port.scrollBy({ top: -Math.round(port.clientHeight * 0.4) });
+                    await ports.sleep(stepMs);
+                }
+            }
+            return null;
+        }
+        // 滚动后：虚拟渲染窗口已覆盖目标（数据窗口含目标行）→ 放慢等待 DOM 挂载
+        const snap = ports.snap();
+        if (snap !== undefined && hasTarget(snap.rows, key)) {
+            const rendered = await waitForRow(ports, key, Math.max(100, stepMs), 2500);
+            if (rendered !== null)
+                return rendered;
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * 跳转到 key 对应行：
+ *   - 目标已在渲染窗口 → 等待 DOM 并滚动；
+ *   - 目标在下方/窗口内（targetSeq ≥ 渲染窗口最小值）→ 向下滚动定位（无需加载）；
+ *   - 目标更早（targetSeq < 渲染窗口最小值 或未知）→ 预算内 loadOlder 补历史，每页后向上滚动定位；
+ *   - 全部失败 → 回退最近可渲染行。
+ */
+export async function goTo(ports, key, options = {}, mode = 'smooth', targetSeq, currentSeq) {
+    const budget = { ...BUDGET, ...options };
+    const fail = (code, fallback = false) => {
+        ports.report?.(code, fallback);
+        return fallback ? { ok: false, code, fallback: true } : { ok: false, code };
+    };
+    if (!ports.active())
+        return fail('VIEW_INACTIVE');
+    const deadline = ports.now() + budget.totalTimeoutMs;
+    let pages = 0;
+    let lastNotified = -1;
+    const notifyLoading = (loading, count) => {
+        const key2 = loading ? count : -1;
+        if (key2 === lastNotified)
+            return;
+        lastNotified = key2;
+        ports.onLoading?.(loading, count);
+    };
+    // 阶段一：确保目标进入渲染窗口
+    for (;;) {
+        const snap = ports.snap();
+        if (snap === undefined) {
+            notifyLoading(false, 0);
+            return fail('VIEW_INACTIVE');
+        }
+        if (hasTarget(snap.rows, key)) {
+            notifyLoading(false, 0);
+            break;
+        }
+        if (ports.now() > deadline) {
+            notifyLoading(false, 0);
+            return fail('TIMEOUT');
+        }
+        // 明确在下方（目标比当前阅读位置晚）：向下滚动定位，绝不加载。
+        // 方向判定优先用当前阅读位置 seq（渲染窗口极值含虚拟缓冲，不可靠）
+        if (targetSeq !== undefined) {
+            const range = seqRange(snap.rows);
+            const below = currentSeq !== undefined
+                ? targetSeq > currentSeq
+                : range !== null && targetSeq > range.max;
+            if (below) {
+                const found = await scrollLocate(ports, key, 1, 500, budget.pollMs * 2);
+                if (found !== null) {
+                    ports.reveal(found, mode);
+                    return { ok: true };
+                }
+                notifyLoading(false, 0);
+                return fail('TARGET_HIDDEN');
+            }
+        }
+        // 其余情况：先向上滚动定位（目标可能已加载但位于虚拟缓冲/视口上方未渲染），
+        // 仅在目标距渲染窗口较近时尝试，避免无谓的大范围滚动
+        if (!snap.loadingOlder) {
+            const range = seqRange(snap.rows);
+            const closeEnough = targetSeq === undefined || range === null || targetSeq >= range.min - 40;
+            if (closeEnough) {
+                const up = await scrollLocate(ports, key, -1, 40, budget.pollMs * 2);
+                if (up !== null) {
+                    notifyLoading(false, 0);
+                    ports.reveal(up, mode);
+                    return { ok: true };
+                }
+            }
+        }
+        // 更早方向：补历史
+        if (snap.openState !== 'open') {
+            if (snap.openState === 'error') {
+                notifyLoading(false, 0);
+                return fail('VIEW_INACTIVE');
+            }
+            await ports.sleep(budget.pollMs);
+            continue;
+        }
+        if (snap.hasMore !== true) {
+            notifyLoading(false, 0);
+            return fail('NOT_FOUND');
+        }
+        if (pages >= budget.maxPages) {
+            notifyLoading(false, 0);
+            return fail('TIMEOUT');
+        }
+        notifyLoading(true, pages + 1);
+        if (snap.loadingOlder) {
+            await ports.sleep(budget.pollMs);
+            continue;
+        }
+        const before = smallestSeq(snap.rows);
+        await ports.loadMore();
+        pages += 1;
+        notifyLoading(true, pages);
+        // loadOlder 的 Promise resolve 可能早于数据落地：轮询等待窗口最小 seq 真正前移
+        let after = before;
+        for (let waited = 0; waited <= 5000; waited += budget.pollMs) {
+            const s2 = ports.snap();
+            const cur = smallestSeq(s2 === undefined ? [] : s2.rows);
+            if (cur !== null && (before === null || cur < before)) {
+                after = cur;
+                break;
+            }
+            await ports.sleep(budget.pollMs);
+        }
+        if (after === null || (before !== null && after >= before)) {
+            // 加载无进展：最后向上滚动定位一次再判失败
+            const up = await scrollLocate(ports, key, -1, 40, budget.pollMs * 2);
+            if (up !== null) {
+                notifyLoading(false, 0);
+                ports.reveal(up, mode);
+                return { ok: true };
+            }
+            notifyLoading(false, 0);
+            return fail('NOT_FOUND');
+        }
+        // 循环继续：新加载的行在视口上方，顶部迭代会再向上滚动定位
+    }
+    // 阶段二：等待渲染并滚动；隐藏则回退
+    const row = await waitForRow(ports, key, budget.pollMs, budget.rowWaitMs);
+    if (row !== null) {
+        ports.reveal(row, mode);
+        return { ok: true };
+    }
+    // 目标已入渲染窗口但 DOM 未挂载（虚拟渲染延迟）：双向滚动定位兜底
+    const snap0 = ports.snap();
+    if (snap0 !== undefined && hasTarget(snap0.rows, key)) {
+        const located = await scrollLocate(ports, key, -1, 60, budget.pollMs * 2)
+            ?? await scrollLocate(ports, key, 1, 60, budget.pollMs * 2);
+        if (located !== null) {
+            ports.reveal(located, mode);
+            return { ok: true };
+        }
+    }
+    const snap = ports.snap();
+    const fallback = retreatTo(snap === undefined ? [] : snap.rows, key);
+    if (fallback !== null) {
+        const fbRow = await waitForRow(ports, fallback.key, budget.pollMs, budget.rowWaitMs);
+        if (fbRow !== null) {
+            ports.reveal(fbRow, mode);
+            return fail('TARGET_HIDDEN', true);
+        }
+    }
+    return fail('TARGET_HIDDEN', false);
+}