dsh-mega-chat-nav 0.1.1

package/lib/compat.js

@@ -0,0 +1,145 @@
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+/** 解析 dsh 版本串；非法返回 null（不支持 x.y / 纯数字 etc.）。 */
+export function parseDshVersion(v) {
+    const m = VERSION_RE.exec(v.trim());
+    if (!m)
+        return null;
+    const pre = m[4] !== undefined ? m[4].split('.') : null;
+    if (pre !== null && pre.some((s) => s === ''))
+        return null;
+    return { base: [Number(m[1]), Number(m[2]), Number(m[3])], pre };
+}
+function compareIdent(a, b) {
+    const na = /^\d+$/.test(a);
+    const nb = /^\d+$/.test(b);
+    if (na && nb) {
+        const x = Number(a);
+        const y = Number(b);
+        return x === y ? 0 : x < y ? -1 : 1;
+    }
+    if (na)
+        return -1; // 数字标识 < 字母标识
+    if (nb)
+        return 1;
+    return a === b ? 0 : a < b ? -1 : 1;
+}
+function comparePre(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const c = compareIdent(a[i], b[i]);
+        if (c !== 0)
+            return c;
+    }
+    return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;
+}
+/**
+ * 语义化比较：a < b → -1；相等 → 0；a > b → 1；任一无法解析 → NaN。
+ */
+export function compareDshVersions(a, b) {
+    const pa = parseDshVersion(a);
+    const pb = parseDshVersion(b);
+    if (pa === null || pb === null)
+        return NaN;
+    for (let i = 0; i < 3; i++) {
+        if (pa.base[i] !== pb.base[i])
+            return pa.base[i] < pb.base[i] ? -1 : 1;
+    }
+    if (pa.pre === null && pb.pre === null)
+        return 0;
+    if (pa.pre === null)
+        return 1; // 正式版高于同基线任意预发布
+    if (pb.pre === null)
+        return -1;
+    return comparePre(pa.pre, pb.pre);
+}
+/** 操作符比较（非法版本一律 false）。 */
+export function checkDshVersion(current, op, target) {
+    const c = compareDshVersions(current, target);
+    if (Number.isNaN(c))
+        return false;
+    switch (op) {
+        case '>':
+            return c > 0;
+        case '>=':
+            return c >= 0;
+        case '<':
+            return c < 0;
+        case '<=':
+            return c <= 0;
+        default:
+            return c === 0;
+    }
+}
+/** 标识段匹配：'*' 吞掉 ≥1 个剩余标识；静态段全等（全数字按数值比较）。 */
+function matchIdents(cur, pat) {
+    const f = (i, j) => {
+        if (i === cur.length && j === pat.length)
+            return true;
+        if (j === pat.length)
+            return false;
+        if (pat[j] === '*') {
+            if (i >= cur.length)
+                return false; // * 至少匹配 1 个
+            for (let k = i + 1; k <= cur.length; k++) {
+                if (f(k, j + 1))
+                    return true;
+            }
+            return false;
+        }
+        if (i >= cur.length)
+            return false;
+        if (compareIdent(pat[j], cur[i]) !== 0)
+            return false;
+        return f(i + 1, j + 1);
+    };
+    return f(0, 0);
+}
+/**
+ * 通配相等（仅配合 op='='）：pattern 形如 0.1.1-*（任意预发布）、0.1.1-rc.*、
+ * 0.1.*（任意小版本）等；'*' 匹配 ≥1 个标识。例：0.1.1-* 命中 0.1.1-rc.1 / 0.1.1-rc.2。
+ */
+export function wildcardEqual(version, pattern) {
+    const pv = parseDshVersion(version);
+    if (pv === null)
+        return false;
+    const dash = pattern.indexOf('-');
+    const basePat = (dash >= 0 ? pattern.slice(0, dash) : pattern).split('.');
+    const prePat = dash >= 0 ? pattern.slice(dash + 1).split('.') : null;
+    if (basePat.length !== 3)
+        return false;
+    const baseHasStar = basePat.some((t) => t === '*');
+    for (let i = 0; i < 3; i++) {
+        const t = basePat[i];
+        if (t === '*')
+            continue;
+        if (!/^\d+$/.test(t))
+            return false;
+        if (Number(t) !== pv.base[i])
+            return false;
+    }
+    if (prePat === null) {
+        // 无预发布子句：基线精确时要求同为正式版；基线含通配（0.1.*）则任意预发布也算命中
+        return baseHasStar || pv.pre === null;
+    }
+    if (pv.pre === null)
+        return false; // 模式含预发布通配：当前必须有预发布
+    return matchIdents(pv.pre, prePat);
+}
+/** 单项命中：target 含 '*' 时仅接受 op='=' 的通配比较，否则按操作符数值比较。 */
+function entryPasses(current, op, target) {
+    if (target.includes('*')) {
+        if (op !== '=')
+            return false;
+        return wildcardEqual(current, target);
+    }
+    return checkDshVersion(current, op, target);
+}
+/** 策略校验：target 为数组时命中任一即通过；通配（如 0.1.1-*）仅在 op='=' 时参与。 */
+export function checkDshPolicy(current, policy) {
+    const targets = Array.isArray(policy.target) ? policy.target : [policy.target];
+    return targets.some((t) => entryPasses(current, policy.op, t));
+}
+/** 不兼容时的控制台提示文案（xxx = 检测到的当前 dsh 版本）。 */
+export function dshCompatMessage(pluginName, currentDshVersion) {
+    return pluginName + ' 可能不适配 dsh ' + currentDshVersion + ' 版本，请慎重使用';
+}

package/lib/config.js

@@ -0,0 +1,37 @@
+// 导航条配置常量（纯数据）：host settings schema 与 client 设置面共用，避免硬编码
+// 每组：选项表 → 类型 → 默认值；键名常量集中在文件尾部
+/** 风格选项（当前仅「简约」；后续风格在组件层扩展） */
+export const StyleOptions = ['minimal'];
+export const DEFAULT_STYLE = 'minimal';
+/** 停靠侧选项与默认值 */
+export const AlignOptions = ['left', 'right'];
+export const DEFAULT_RAIL_ALIGN = 'left';
+/** 节点栏条带高度档位（决定当前可见节点数：≈10/15/20 个） */
+export const BandHeightOptions = ['compact', 'standard', 'tall'];
+export const DEFAULT_BAND = 'standard';
+/** 档位 → 条带最大高度（px）：节点行高 14px × 10/15/20 */
+export const BAND_HEIGHT_PX = { compact: 140, standard: 210, tall: 280 };
+/** 跳转动画方式 */
+export const ScrollModeOptions = ['smooth', 'instant'];
+export const DEFAULT_SCROLL_MODE = 'smooth';
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export const ShowModeOptions = ['show', 'peek', 'hide'];
+export const DEFAULT_SHOW = 'show';
+/** 悬停级联卡数量（1/3/5 张） */
+export const CardCountOptions = [1, 3, 5];
+export const DEFAULT_CARD_COUNT = 5;
+/** 风格 → 能力表 */
+export const STYLE_CAPABILITIES = {
+    minimal: { hoverCards: true },
+};
+/** 设置键名（嵌套 schema 字段名；client 桥写回与 host schema 共用） */
+export const STYLE_KEY = 'style';
+export const ALIGN_KEY = 'align';
+export const BAND_KEY = 'bandHeight';
+export const SCROLL_KEY = 'scrollBehavior';
+export const SHOW_COUNT_KEY = 'showCount';
+export const SHOW_SEARCH_KEY = 'showSearch';
+export const SHOW_QUICK_KEY = 'showQuickSettings';
+export const CARD_COUNT_KEY = 'cardCount';
+/** 本插件设置命名空间（拼写而非导入：client bundle 不得依赖宿主包） */
+export const MGS_NS = 'mega-chat-nav';

package/lib/core/active-dot.js

@@ -0,0 +1,17 @@
+/**
+ * 选取标记圆点：阅读线之上（含）的最后一行为当前回合；
+ * 阅读线在所有行之上（开场问答之前）时取第一行兜底；无渲染行返回 null。
+ * 行按圆点顺序输入；扫描保留最后一个满足项，单条乱序测量不回退标记。
+ */
+export function nearestReadDot(rows, readingLine) {
+    if (rows.length === 0)
+        return null;
+    let active = null;
+    for (const row of rows) {
+        if (row.top <= readingLine)
+            active = row.key;
+    }
+    return active ?? rows[0].key;
+}
+/** 阅读线固定为视口顶部（0） */
+export const READING_LINE_TOP = 0;

package/lib/core/align.js

@@ -0,0 +1,9 @@
+// 导航条停靠侧常量：host 设置 schema 与浏览器设置面共用（纯数据，无宿主依赖）
+/** 可选停靠侧 */
+export const AlignOptions = ['left', 'right'];
+/** 默认停靠侧（设置文档无覆盖时） */
+export const DEFAULT_RAIL_ALIGN = 'left';
+/** 本插件设置命名空间（此处拼写而非导入：client bundle 不得依赖宿主包） */
+export const MGS_NS = 'mega-chat-nav';
+/** 设置字段：停靠侧 */
+export const ALIGN_KEY = 'align';

package/lib/core/config.js

@@ -0,0 +1,37 @@
+// 导航条配置常量（纯数据）：host settings schema 与 client 设置面共用，避免硬编码
+// 每组：选项表 → 类型 → 默认值；键名常量集中在文件尾部
+/** 风格选项（当前仅「简约」；后续风格在组件层扩展） */
+export const StyleOptions = ['minimal'];
+export const DEFAULT_STYLE = 'minimal';
+/** 停靠侧选项与默认值 */
+export const AlignOptions = ['left', 'right'];
+export const DEFAULT_RAIL_ALIGN = 'left';
+/** 节点栏条带高度档位（决定当前可见节点数：≈10/15/20 个） */
+export const BandHeightOptions = ['compact', 'standard', 'tall'];
+export const DEFAULT_BAND = 'standard';
+/** 档位 → 条带最大高度（px）：节点行高 14px × 10/15/20 */
+export const BAND_HEIGHT_PX = { compact: 140, standard: 210, tall: 280 };
+/** 跳转动画方式 */
+export const ScrollModeOptions = ['smooth', 'instant'];
+export const DEFAULT_SCROLL_MODE = 'smooth';
+/** 显示策略：常显 / 悬停浮现 / 隐藏 */
+export const ShowModeOptions = ['show', 'peek', 'hide'];
+export const DEFAULT_SHOW = 'show';
+/** 悬停级联卡数量（1/3/5 张） */
+export const CardCountOptions = [1, 3, 5];
+export const DEFAULT_CARD_COUNT = 5;
+/** 风格 → 能力表 */
+export const STYLE_CAPABILITIES = {
+    minimal: { hoverCards: true },
+};
+/** 设置键名（嵌套 schema 字段名；client 桥写回与 host schema 共用） */
+export const STYLE_KEY = 'style';
+export const ALIGN_KEY = 'align';
+export const BAND_KEY = 'bandHeight';
+export const SCROLL_KEY = 'scrollBehavior';
+export const SHOW_COUNT_KEY = 'showCount';
+export const SHOW_SEARCH_KEY = 'showSearch';
+export const SHOW_QUICK_KEY = 'showQuickSettings';
+export const CARD_COUNT_KEY = 'cardCount';
+/** 本插件设置命名空间（拼写而非导入：client bundle 不得依赖宿主包） */
+export const MGS_NS = 'mega-chat-nav';

package/lib/core/focus.js

@@ -0,0 +1,38 @@
+// 聚焦模型：悬停圆点的邻域放大、级联卡尺寸与翻页步进（纯函数）
+/** 选中点两侧保持放大的圆点数 */
+export const FOCUS_RADIUS = 2;
+/** 悬停放大倍数：仅选中圆点放大（邻居不再有放大特效） */
+export const FOCUS_SCALES = [1.5];
+/** 距离 → 聚焦档（窗口内 0..RADIUS，窗口外 null；供级联卡窗口使用） */
+export function focusTier(distance) {
+    const d = Math.abs(distance);
+    return d > FOCUS_RADIUS ? null : d;
+}
+/** 距离 → 放大倍数：仅选中点（distance 0）放大，邻居/窗口外均为 1 */
+export function focusScale(distance) {
+    const d = Math.abs(distance);
+    return d === 0 ? FOCUS_SCALES[0] : 1;
+}
+export function focusCardMetrics(distance) {
+    const tier = focusTier(distance);
+    if (tier === null)
+        return null;
+    switch (tier) {
+        case 0: return { widthPx: 380, fontSize: 13, maxLines: 6 };
+        case 1: return { widthPx: 300, fontSize: 12.5, maxLines: 2 };
+        default: return { widthPx: 240, fontSize: 12, maxLines: 1 };
+    }
+}
+/** 基础圆点直径与间距（与轨样式一致，翻页步进按整行计） */
+export const DOT_SIZE = 8;
+export const DOT_GAP = 6;
+/** 一次翻页揭示的整行数 */
+export const DOT_PAGE_ROWS = 5;
+/** 一次翻页的滚动步长（px） */
+export function pageStep(dotSize = DOT_SIZE, gap = DOT_GAP, rows = DOT_PAGE_ROWS) {
+    return rows * (dotSize + gap);
+}
+/** 将目标滚动位置钳制到有效区间 */
+export function clampScrollTop(target, maxScroll) {
+    return Math.max(0, Math.min(target, Math.max(0, maxScroll)));
+}

package/lib/core/jump.js

@@ -0,0 +1,98 @@
+// 跳转编排：定位目标回合行，必要时按需向后扩窗（端口注入，可脱离浏览器测试）
+import { nearestRenderable } from "./nodes.js";
+const DEFAULT_LIMITS = {
+    totalTimeoutMs: 15_000,
+    maxPages: 100,
+    rowWaitMs: 8_000,
+    pollMs: 60,
+};
+function minAnchorSeq(rows) {
+    let min = null;
+    for (const row of rows) {
+        if (min === null || row.anchorSeq < min)
+            min = row.anchorSeq;
+    }
+    return min;
+}
+function renderableRows(rows) {
+    const out = [];
+    for (const row of rows) {
+        if (row.visibility === 'hidden')
+            continue;
+        out.push({ key: row.key, anchorSeq: row.anchorSeq });
+    }
+    return out;
+}
+/**
+ * 跳转到 key 对应行：先扩窗（预算内）直至目标入窗，再等待行渲染并滚动；
+ * 目标隐藏/缺失时回退最近可渲染行。各失败点返回结构化结果码。
+ */
+export async function jumpToTarget(ports, key, options = {}, mode = 'smooth') {
+    const limits = { ...DEFAULT_LIMITS, ...options };
+    const fail = (code, fallback = false) => {
+        ports.report?.(code, fallback);
+        return fallback ? { ok: false, code, fallback: true } : { ok: false, code };
+    };
+    if (!ports.isViewActive())
+        return fail('VIEW_INACTIVE');
+    const deadline = ports.now() + limits.totalTimeoutMs;
+    let pages = 0;
+    // 阶段一：向后扩窗直到目标出现在已加载窗口
+    for (;;) {
+        const snap = ports.snapshot();
+        if (snap === undefined)
+            return fail('VIEW_INACTIVE');
+        const rows = renderableRows(snap.rows);
+        if (rows.some((r) => r.key === key))
+            break;
+        if (snap.openState !== 'open') {
+            if (snap.openState === 'error' || ports.now() > deadline) {
+                return fail(snap.openState === 'error' ? 'VIEW_INACTIVE' : 'TIMEOUT');
+            }
+            await ports.sleep(limits.pollMs);
+            continue;
+        }
+        if (snap.hasMore !== true)
+            return fail('NOT_FOUND');
+        if (pages >= limits.maxPages || ports.now() > deadline)
+            return fail('TIMEOUT');
+        if (snap.loadingOlder) {
+            await ports.sleep(limits.pollMs);
+            continue;
+        }
+        const before = minAnchorSeq(rows);
+        await ports.loadOlder();
+        pages += 1;
+        const afterSnap = ports.snapshot();
+        const after = minAnchorSeq(afterSnap === undefined ? [] : afterSnap.rows);
+        if (after === null || (before !== null && after >= before))
+            return fail('NOT_FOUND');
+    }
+    // 阶段二：等待行渲染后滚动；隐藏则回退最近可渲染行
+    const waitRendered = async (rowKey) => {
+        for (let waited = 0; waited <= limits.rowWaitMs; waited += limits.pollMs) {
+            if (!ports.isViewActive())
+                return null;
+            const row = ports.findRow(rowKey);
+            if (row !== null)
+                return row;
+            await ports.sleep(limits.pollMs);
+        }
+        return null;
+    };
+    const row = await waitRendered(key);
+    if (row !== null) {
+        ports.scrollIntoView(row, mode);
+        return { ok: true };
+    }
+    const snap = ports.snapshot();
+    const fallback = nearestRenderable(snap === undefined ? [] : snap.rows, key);
+    if (fallback !== null) {
+        const fbRow = await waitRendered(fallback.key);
+        if (fbRow !== null) {
+            ports.scrollIntoView(fbRow, mode);
+            return fail('TARGET_HIDDEN', true);
+        }
+    }
+    return fail('TARGET_HIDDEN', false);
+}

package/lib/core/logic/active-dot.js

@@ -0,0 +1,16 @@
+/** 阅读线固定为视口顶部（0） */
+export const READING_LINE_TOP = 0;
+/**
+ * 选取标记圆点：阅读线之上（含）的最后一行为当前回合；
+ * 阅读线在所有行之上（开场问答之前）时取第一行兜底；无渲染行返回 null。
+ * 实现：自尾向首扫描第一个越过阅读线的行（等价于「最后一个满足项」）。
+ */
+export function nearestReadDot(rows, readingLine) {
+    if (rows.length === 0)
+        return null;
+    for (let i = rows.length - 1; i >= 0; i--) {
+        if (rows[i].top <= readingLine)
+            return rows[i].key;
+    }
+    return rows[0].key;
+}

package/lib/core/logic/focus.js

@@ -0,0 +1,34 @@
+// 聚焦模型（纯函数）：悬停圆点的邻域档位、放大倍数与级联卡尺寸
+/** 选中点两侧计入聚焦窗口的圆点数 */
+export const FOCUS_RADIUS = 2;
+/** 悬停放大倍数：仅选中圆点放大（邻居不再有放大特效） */
+export const FOCUS_SCALES = [1.5];
+/** 档位 → 卡尺寸表（档 0 选中卡 / 档 1 / 档 2 最窄） */
+const CARD_SIZE_TABLE = [
+    { widthPx: 380, fontSize: 13, maxLines: 6 },
+    { widthPx: 300, fontSize: 12.5, maxLines: 2 },
+    { widthPx: 240, fontSize: 12, maxLines: 1 },
+];
+/** 距离 → 聚焦度量（档位 + 放大倍数 + 卡尺寸）；聚焦窗口外返回 null */
+export function focusMetrics(distance) {
+    const magnitude = distance < 0 ? -distance : distance;
+    if (magnitude > FOCUS_RADIUS)
+        return null;
+    return {
+        tier: magnitude,
+        scale: magnitude === 0 ? FOCUS_SCALES[0] : 1,
+        card: CARD_SIZE_TABLE[magnitude] ?? CARD_SIZE_TABLE[CARD_SIZE_TABLE.length - 1],
+    };
+}
+/** 距离 → 聚焦档（窗口内 0..RADIUS，窗口外 null；供级联卡窗口使用） */
+export function focusTier(distance) {
+    return focusMetrics(distance)?.tier ?? null;
+}
+/** 距离 → 放大倍数：仅选中点（distance 0）放大，邻居/窗口外均为 1 */
+export function focusScale(distance) {
+    return focusMetrics(distance)?.scale ?? 1;
+}
+/** 距离 → 卡呈现参数；聚焦窗口外返回 null */
+export function focusCardMetrics(distance) {
+    return focusMetrics(distance)?.card ?? null;
+}

package/lib/core/logic/jump.js

@@ -0,0 +1,188 @@
+// 跳转编排：显式状态机驱动（阶段枚举 + 单步推进；端口注入，可脱离浏览器测试）
+import { NavNodes } from "./nodes.js";
+const DEFAULT_LIMITS = {
+    totalTimeoutMs: 15_000,
+    maxPages: 100,
+    rowWaitMs: 8_000,
+    pollMs: 60,
+};
+function createMachine(ports, key, mode, options) {
+    return {
+        stage: 'locate',
+        key,
+        mode,
+        deadline: ports.now() + (options.totalTimeoutMs ?? DEFAULT_LIMITS.totalTimeoutMs),
+        limits: {
+            totalTimeoutMs: options.totalTimeoutMs ?? DEFAULT_LIMITS.totalTimeoutMs,
+            maxPages: options.maxPages ?? DEFAULT_LIMITS.maxPages,
+            rowWaitMs: options.rowWaitMs ?? DEFAULT_LIMITS.rowWaitMs,
+            pollMs: options.pollMs ?? DEFAULT_LIMITS.pollMs,
+        },
+        pages: 0,
+        waited: 0,
+        rowKey: null,
+        onFallback: false,
+        result: null,
+    };
+}
+function settle(machine, ports, code, fallback = false) {
+    machine.stage = 'finished';
+    if (code === undefined) {
+        machine.result = { ok: true };
+    }
+    else if (fallback) {
+        machine.result = { ok: false, code, fallback: true };
+    }
+    else {
+        machine.result = { ok: false, code };
+    }
+    if (code !== undefined)
+        ports.report?.(code, fallback);
+}
+/** 快照的可渲染行中是否已含目标 */
+function containsTarget(rows, key) {
+    for (const row of rows) {
+        if (row.visibility !== 'hidden' && row.key === key)
+            return true;
+    }
+    return false;
+}
+/** 当前窗口最小锚点序号；空窗口返回 null */
+function smallestAnchor(rows) {
+    let smallest = null;
+    for (const row of rows) {
+        if (smallest === null || row.anchorSeq < smallest)
+            smallest = row.anchorSeq;
+    }
+    return smallest;
+}
+/** 推进一个状态步；返回驱动层下一步动作（wait=轮询、load=执行扩窗、next=立即再推） */
+function advance(machine, ports) {
+    switch (machine.stage) {
+        case 'locate': {
+            const snap = ports.snapshot();
+            if (snap === undefined) {
+                settle(machine, ports, 'VIEW_INACTIVE');
+                return { kind: 'next' };
+            }
+            if (containsTarget(snap.rows, machine.key)) {
+                machine.stage = 'wait-row';
+                machine.rowKey = machine.key;
+                machine.waited = 0;
+                return { kind: 'next' };
+            }
+            if (snap.openState !== 'open') {
+                if (snap.openState === 'error') {
+                    settle(machine, ports, 'VIEW_INACTIVE');
+                    return { kind: 'next' };
+                }
+                machine.stage = 'wait-open';
+                return { kind: 'wait' };
+            }
+            if (!snap.hasMore) {
+                settle(machine, ports, 'NOT_FOUND');
+                return { kind: 'next' };
+            }
+            machine.stage = 'page';
+            return { kind: 'next' };
+        }
+        case 'wait-open': {
+            if (ports.now() > machine.deadline) {
+                settle(machine, ports, 'TIMEOUT');
+                return { kind: 'next' };
+            }
+            const snap = ports.snapshot();
+            if (snap === undefined) {
+                settle(machine, ports, 'VIEW_INACTIVE');
+                return { kind: 'next' };
+            }
+            if (snap.openState === 'open') {
+                machine.stage = 'locate';
+                return { kind: 'next' };
+            }
+            if (snap.openState === 'error') {
+                settle(machine, ports, 'VIEW_INACTIVE');
+                return { kind: 'next' };
+            }
+            return { kind: 'wait' };
+        }
+        case 'page': {
+            if (machine.pages >= machine.limits.maxPages || ports.now() > machine.deadline) {
+                settle(machine, ports, 'TIMEOUT');
+                return { kind: 'next' };
+            }
+            const snap = ports.snapshot();
+            if (snap === undefined) {
+                settle(machine, ports, 'VIEW_INACTIVE');
+                return { kind: 'next' };
+            }
+            if (snap.loadingOlder)
+                return { kind: 'wait' };
+            return { kind: 'load', before: smallestAnchor(snap.rows) };
+        }
+        case 'wait-row': {
+            if (!ports.isViewActive()) {
+                settle(machine, ports, 'TARGET_HIDDEN');
+                return { kind: 'next' };
+            }
+            const row = machine.rowKey !== null ? ports.findRow(machine.rowKey) : null;
+            if (row !== null) {
+                ports.scrollIntoView(row, machine.mode);
+                settle(machine, ports, machine.onFallback ? 'TARGET_HIDDEN' : undefined, machine.onFallback);
+                return { kind: 'next' };
+            }
+            machine.waited += machine.limits.pollMs;
+            if (machine.waited > machine.limits.rowWaitMs) {
+                if (machine.onFallback) {
+                    settle(machine, ports, 'TARGET_HIDDEN');
+                    return { kind: 'next' };
+                }
+                const snap = ports.snapshot();
+                const nearest = NavNodes.nearest(snap === undefined ? [] : snap.rows, machine.key);
+                if (nearest === null) {
+                    settle(machine, ports, 'TARGET_HIDDEN');
+                    return { kind: 'next' };
+                }
+                machine.rowKey = nearest.key;
+                machine.onFallback = true;
+                machine.waited = 0;
+                return { kind: 'next' };
+            }
+            return { kind: 'wait' };
+        }
+        default:
+            return { kind: 'next' };
+    }
+}
+/**
+ * 跳转到 key 对应行：状态机驱动（定位 → 等就绪 → 扩窗 → 等渲染 → 回退）；
+ * 各失败点返回结构化结果码。
+ */
+export async function jumpToTarget(ports, key, options = {}, mode = 'smooth') {
+    const machine = createMachine(ports, key, mode, options);
+    if (!ports.isViewActive()) {
+        settle(machine, ports, 'VIEW_INACTIVE');
+        return machine.result;
+    }
+    for (;;) {
+        if (machine.result !== null)
+            return machine.result;
+        const step = advance(machine, ports);
+        if (machine.result !== null)
+            return machine.result;
+        if (step.kind === 'wait') {
+            await ports.sleep(machine.limits.pollMs);
+        }
+        else if (step.kind === 'load') {
+            await ports.loadOlder();
+            machine.pages += 1;
+            const afterSnap = ports.snapshot();
+            const after = smallestAnchor(afterSnap === undefined ? [] : afterSnap.rows);
+            if (after === null || (step.before !== null && after >= step.before)) {
+                settle(machine, ports, 'NOT_FOUND');
+                return machine.result;
+            }
+            machine.stage = 'locate';
+        }
+    }
+}