@migor/cli 0.10.8 → 0.10.10

package/dist/inspector/trace-view.css

@@ -218,6 +218,61 @@
   min-width: 0;
 }
 
+/* —— 时间轴（2026-11-13）：树行右侧一条按 run 总时长归一化的细轨 ——
+   结构视角看不出「谁和谁并行 / 8 秒被谁吃掉 / 首个 token 等了多久」，而每个 span 的
+   起止本来就在数据里。最小形态 = 同一套行右侧加一条轨道，不引入第二套布局（瀑布图那种
+   双栏会把已经够挤的树再压窄一半）。
+
+   `margin-left: auto` 让「读数 — 轨道」贴在一起：两者说的是同一件事（这个 span 花了多久）。
+   条本身用 span 的绝对几何（`left` / `width` 百分比），两端都在 JS 里 clamp 过。 */
+.tr-tl {
+  flex: none;
+  margin-left: auto;
+  width: 72px;
+  height: 5px;
+  position: relative;
+  background: #1b1b1f;
+  border-radius: 3px;
+}
+.tr-tl-bar {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  background: var(--ice);
+  opacity: 0.45;
+  border-radius: 3px;
+}
+.tr-row.error .tr-tl-bar {
+  background: #f7768e;
+  opacity: 0.6;
+}
+/* 有轨道的行：meta 不再吃 auto 边距（否则轨道被推到名字旁边、读数留在最右，两者脱节） */
+.tr-row[data-tl] .tr-meta {
+  margin-left: 0;
+  padding-left: 8px;
+}
+/* span 行的 caret 与事件行同一个字形，但行内没有 `.tr-io` 可以让位 ⇒ 行自己留一条槽 */
+.tr-row[data-expandable]:not(.tr-ev) {
+  padding-right: 14px;
+}
+/* 窄屏（面板退成单列时）把轨道收起来：72px 在那个宽度里是从名字里抢的 */
+@media (max-width: 860px) {
+  .tr-tl {
+    display: none;
+  }
+}
+
+/* —— 树内检索（2026-11-13）：**只标记，不改结构** ——
+   裁剪节点会让「谁挂在谁下面」这个事实失真（隐藏父节点后子节点看起来属于别人），
+   所以命中行只加底色；`-cur` 是「刚才跳到的那一处」，用来在连按 Enter 时不迷路。 */
+.tr-hit {
+  background: rgba(224, 175, 104, 0.13);
+}
+.tr-hit-cur {
+  background: rgba(224, 175, 104, 0.28);
+  box-shadow: inset 2px 0 0 var(--warn, #e0af68);
+}
+
 /* —— 结构化正文（2026-11-11）：`full` 是对象/数组时，展开行**下方**多一个兄弟块 ——
    此前只有一条展开路：整串无缩进的 JSON 塞进 `.tr-io` 再靠 `.tr-open` 换行，20 个键就在
    400px 宽的右栏里折成十几行连续文本（页面不报错、无溢出，只是人读不了）。
@@ -296,6 +351,17 @@
   padding: 0 4px;
   margin-right: 4px;
 }
+/* `md`：这段正文被 Markdown 渲染过（2026-11-12）。与 `str→json` 同一套外观 ——
+   两者都是「你看到的不是原样」的告示，样式分叉只会让人以为它们是不同性质的东西。 */
+.tr-full-md {
+  color: var(--faint);
+  font-size: 10px;
+  line-height: 1.4;
+  border: 1px solid #2c2c32;
+  border-radius: 3px;
+  padding: 0 4px;
+  margin-right: 4px;
+}
 /* `⧉` 复制路径：hover 才露。与 .tr-caret 的区别是**它暴露的是动作、不是信息** ——
    路径的内容（键名）始终写在行里，常显只会给每行多一个字形噪声。
    没有剪贴板实现时照样显示、点了不谎报成功（见 full-view.js 的 copyInto）。 */

package/dist/inspector/view.js

@@ -17,11 +17,14 @@
  * 宿主需提供的 CSS 变量：--ice --faint --text（见 trace-view.css）。
  */
 
-/* 展开态的正文有两种形状，由 `full` 的类型决定（2026-11-11，2026-11-12 扩了一档）：
+/* 展开态的正文有三种形状（2026-11-11，2026-11-12 扩了两档）：
  *   - 纯文本字符串 → 老路：`.tr-io` 里放原文，靠 `.tr-open` 换行（纯文本正文、官网模拟回放）；
  *   - 对象/数组 → 追加一个 `.tr-full` 结构化块（折叠 / 成表 / 路径复制），`.tr-io` 由 CSS 隐藏；
  *   - **装着 JSON 的字符串**（`content: "{\"rows\":[...]}"`，工具把结构序列化后塞回文本字段）
- *     → 同上一档，块头写明「string · N 字符 → object · M 项」并打 `str→json` 标记。
+ *     → 同上一档，块头写明「string · N 字符 → object · M 项」并打 `str→json` 标记；
+ *   - **一整篇 Markdown 的字符串**（工具出参就是一份 SKILL.md / 报告）→ 由宿主注入的
+ *     `opts.textBody(text)` 渲染成正文块，块头打 `md` 标记。注入是刻意的：本包是独立
+ *     发布单元，解析器只有一份（在宿主里），两边各带一份必然漂移。
  * 判据与块内完全同源（`hasStructuredBody`），「挂不挂块」与「块里画什么」因此不会跑偏。
  * 前两档并存是刻意的：纯文本那条路有 test/style.test.js 的两个不变量守着（最小宽度、caret 常显），
  * 全换成本件会让那两个守卫失去落点。 */
@@ -91,10 +94,31 @@ export function createTraceView(rootEl, opts = {}) {
   let price = opts.price ?? null;
   const onUsage = opts.onUsage ?? null;
   const usageEls = opts.usage ?? null;
+  /* 字符串正文的宿主渲染器（可选）：`(text) => Element | null`。返回 null = 「不是那种
+     正文，保持原文」。本包不自带 Markdown 解析器 —— 见文件头注。 */
+  const textBody = typeof opts.textBody === 'function' ? opts.textBody : null;
 
   let traceRoot = null;
   const spanMap = new Map();
   const usageAcc = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
+  /* 批量渲染（2026-11-13）。此前每来一条 span 动作就整树重建一次 ⇒ `playTrace` 是 O(N²)：
+     实测 50 span 触发 151 次全树重建、600 span 触发 1801 次（假 DOM 就 172ms），而在飞时
+     `renderLive` 每个 rAF 还会再调一次 `playTrace`。这不是「慢一点」，是长跑时面板直接卡死。
+     语义不变：**渲染仍是全量重建**（那是折叠态必须外部持有的原因），只是把「一批动作之间
+     的 N 次重建」压成「结束后一次」。
+     ⚠️ 嵌套是安全的（计数器），且批内抛错也会在 finally 里补画 —— 否则异常路径之后整棵树
+     停在中间状态，而下一条事件又会被 `dirty` 吞掉。 */
+  let batchDepth = 0;
+  let batchDirty = false;
+  /* 树内检索（2026-11-13）：**不改结构**，只给命中的行加类 + 提供「跳到下一处」。
+     为什么不裁剪节点：树形是「谁挂在谁下面」的事实，隐藏父节点会让子节点看起来属于别人；
+     而裁剪后「有多少条被藏起来了」又要另一处交代。高亮 + 跳转在不改事实的前提下解决
+     「一百个 span 里找那一条」。 */
+  let query = '';
+  let hitIndex = -1;
+  /* 时间轴开关（2026-11-13）：轨道占 72px，窄面板里是从名字里抢的 ⇒ 允许关掉。
+     默认开 —— 它是「谁和谁并行 / 8 秒被谁吃掉」唯一的落点，而那条信息此前完全没有。 */
+  let timeline = true;
   /* 展开态的行 key 集合 + 事件 key 发号器。两者都必须活在 renderTrace 之外：
      渲染是【全量重建】（rootEl.innerHTML = ''），状态放进 DOM 或渲染过程里就活不过下一次事件。 */
   const expanded = new Set();
@@ -118,8 +142,66 @@ export function createTraceView(rootEl, opts = {}) {
     renderTrace();
   }
 
+  /** 宿主渲染器包一层：**只在展开时调用**（折叠态每条事件都会重画，挂在那儿等于白解析
+   *  一遍所有历史正文）；宿主抛错也不许让整棵树白屏 —— 回落原文即可。 */
+  function textBodyOf(v) {
+    if (!textBody || typeof v !== 'string') return null;
+    try {
+      return textBody(v) || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** 把一批渲染动作压成一次重画（见 `batchDepth` 的头注）。没在批里就直接画。 */
   function renderTrace() {
+    if (batchDepth > 0) {
+      batchDirty = true;
+      return;
+    }
+    drawTree();
+  }
+
+  function batch(fn) {
+    batchDepth += 1;
+    try {
+      fn();
+    } finally {
+      batchDepth -= 1;
+      // 批内一次都没标脏（例如只读了状态）⇒ 不白画一遍
+      if (batchDepth === 0 && batchDirty) {
+        batchDirty = false;
+        drawTree();
+      }
+    }
+  }
+
+  /** 检索：这一行的文本是否命中。空查询恒 false（「没在搜」不等于「全都命中」） */
+  function hits(texts) {
+    if (!query) return false;
+    const q = query.toLowerCase();
+    for (const t of texts) if (t && String(t).toLowerCase().includes(q)) return true;
+    return false;
+  }
+
+  function drawTree() {
     rootEl.innerHTML = '';
+    hitIndex = -1;
+    // 还没 reset 过（视图刚建出来）：清空即返回。setTimeline / setQuery 可能先于第一棵树
+    // 被调用 —— 没有这一条，`traceRoot.order` 会抛，而调用方只是在设一个开关。
+    if (!traceRoot) return;
+    /* 时间轴的归一化基准：根 span 的起点与整棵树的终点。两者缺一就**不画条**
+       （手写 trace / 官网模拟回放没有时间戳 —— 画一条人人占满的条比不画更误导）。 */
+    const t0 = traceRoot && typeof traceRoot.startedAt === 'number' ? traceRoot.startedAt : null;
+    let tMax = t0;
+    if (t0 !== null) {
+      for (const n of spanMap.values()) {
+        const e = typeof n.endAt === 'number' ? n.endAt : n.startedAt;
+        if (typeof e === 'number' && e > tMax) tMax = e;
+      }
+    }
+    const total = t0 !== null && tMax !== null ? Math.max(0, tMax - t0) : 0;
+
     const rows = [];
     /* 每个节点下【事件】与【子 span】按发生顺序混排：tool.input 先于它触发的 capability span、
        tool.output 后于它，这个先后本身就是语义，不能拍平成一类。 */
@@ -142,6 +224,11 @@ export function createTraceView(rootEl, opts = {}) {
         const open = expanded.has(ev.key);
         const row = el('div', 'tr-row tr-ev' + (ev.ok === false ? ' error' : ''));
         row.dataset.ev = ev.type;
+        /* 检索只扫摘要与类型/工具名，**不扫完整正文**：`full` 常见 10KB 级，每帧每行
+             indexOf 一遍会让「搜索」本身成为掉帧的原因（600 行 × 10KB ≈ 6MB/帧）。
+             2000 字符以内才扫 —— 那个尺度上全文搜索才有意义（再长就是文档，不是一行）。 */
+        const fullShort = typeof ev.full === 'string' && ev.full.length <= 2000 ? ev.full : '';
+        if (hits([ev.type, ev.tool, ev.text, fullShort])) row.className += ' tr-hit';
         row.dataset.capability = capabilityTypeOf(ev.tool);
         row.appendChild(el('span', 'tr-pre', branch));
         row.appendChild(el('span', 'tr-evv', ev.type === 'tool.output' ? '◂' : '▸'));
@@ -150,11 +237,13 @@ export function createTraceView(rootEl, opts = {}) {
         // 这一格整个不渲染，别把「无工具」显示成假工具名（.tr-name 是 flex:none，.tr-io 自然占满）
         if (ev.tool) row.appendChild(el('span', 'tr-name', ev.tool));
         // 展开态用全文（ev.full），折叠态用摘要（ev.text）—— 折叠态因此与加展开之前逐字一致。
-        // `full` 是对象/数组、或**装着 JSON 的字符串**时（2026-11-11 / 2026-11-12）：`.tr-io`
-        // 仍放**原文**（结构化块挂在行后、由 CSS 隐藏本格），所以「展开拿到的是原文而不是
-        // 62 字符摘要」这条不变量原样成立。
+        // `full` 是对象/数组、装着 JSON 的字符串、或宿主认得的正文（Markdown）时
+        // （2026-11-11 / 2026-11-12）：`.tr-io` 仍放**原文**（结构化块挂在行后、由 CSS 隐藏本格），
+        // 所以「展开拿到的是原文而不是 62 字符摘要」这条不变量原样成立。
         const structured = hasStructuredBody(ev.full);
-        const fullText = structured ? rawArg(ev.full) : ev.full || '';
+        const mdBody = open && !structured ? textBodyOf(ev.full) : null;
+        const blocked = structured || mdBody !== null;
+        const fullText = blocked ? rawArg(ev.full) : ev.full || '';
         const io = el('span', 'tr-io', (open ? fullText : ev.text) || '');
         // 展开后正文已在行里，再挂一个占满整行的原生 tooltip 只会挡视线
         io.title = open ? '' : ev.text || '';
@@ -162,7 +251,7 @@ export function createTraceView(rootEl, opts = {}) {
         if (ev.full) {
           row.dataset.expandable = '1'; // 可展开标记：CSS 靠它出 caret / cursor，测试靠它找行
           row.appendChild(el('span', 'tr-caret', open ? '▾' : '▸'));
-          if (open) row.className += ' tr-open' + (structured ? ' tr-structured' : '');
+          if (open) row.className += ' tr-open' + (blocked ? ' tr-structured' : '');
           row.addEventListener('click', () => {
             if (!hasSelection()) toggleExpand(ev.key);
           });
@@ -171,13 +260,15 @@ export function createTraceView(rootEl, opts = {}) {
         // 结构化正文是**兄弟块**而不是 `.tr-io` 的子节点：行是 flex + nowrap，
         // 塞进去会把树的列对齐打乱；独立成块才能自己换行、自己缩进。
         // 折叠状态按事件键取一份带进去（2026-11-11 晚）：块每次重建都 new，状态不能放块里。
-        if (open && structured) {
+        // `body` 是宿主渲染好的正文（Markdown），交给同一条挂载路径：块头、复制、`.tr-io`
+        // 隐藏这些行为必须一致，否则「哪种正文」会从**外观**上分叉成两套。
+        if (open && blocked) {
           let fold = folds.get(ev.key);
           if (!fold) {
             fold = new Map();
             folds.set(ev.key, fold);
           }
-          rootEl.appendChild(createFullView(ev.full, { fold }));
+          rootEl.appendChild(createFullView(ev.full, { fold, body: mdBody }));
         }
         return;
       }
@@ -187,6 +278,18 @@ export function createTraceView(rootEl, opts = {}) {
       row.dataset.kind = node.kind;
       const ut = node.kind === 'capability' ? capabilityTypeOf(node.name) : '';
       if (ut) row.dataset.capability = ut;
+      const attrKeys = node.attributes ? Object.keys(node.attributes) : [];
+      const attrKey = 'sp:' + node.id;
+      const attrOpen = attrKeys.length > 0 && expanded.has(attrKey);
+      /* 命中面：名字 / 入参摘要 / 错误原文 / **已展开的**属性值。
+         属性只在展开时才算：折叠态那些值本来就没显示 —— 高亮一个看不见的东西只会让
+         「N 处匹配」对不上眼睛看到的。 */
+      const attrVals = attrOpen
+        ? Object.values(node.attributes).map((v) => (typeof v === 'string' ? v : String(v)))
+        : [];
+      if (hits([node.name, node.arg, bad ? node.error?.message : '', ...attrVals])) {
+        row.className += ' tr-hit';
+      }
       row.appendChild(el('span', 'tr-pre', branch));
       row.appendChild(el('span', 'tr-dot', node.done ? (bad ? '✕' : '●') : '◌'));
       if (ut) row.appendChild(el('span', 'tr-ico', CAP_ICO[ut]));
@@ -208,10 +311,46 @@ export function createTraceView(rootEl, opts = {}) {
         if (bad) parts.push(node.error?.type || 'error');
         meta = parts.join(' · ');
       } else meta = '…';
+      /* 时间轴条（2026-11-13）：按 run 的总时长归一化 —— 「8 秒被谁吃掉 / 谁和谁并行」
+         只有结构视角是看不见的。放在 meta **之前**并自己吃掉 `margin-left: auto`，
+         让「耗时读数 — 轨道」贴在一起（两者说的是同一件事）。根行不画：它恒占满全宽。 */
+      if (!isRoot && timeline && t0 !== null && total > 0 && typeof node.startedAt === 'number') {
+        const offset = node.startedAt - t0;
+        const left = Math.min(1, Math.max(0, offset / total));
+        const dur = node.done && node.ms > 0 ? node.ms : Math.max(total - offset, 0);
+        const width = Math.min(1 - left, dur / total);
+        const track = el('span', 'tr-tl');
+        const bar = el('span', 'tr-tl-bar');
+        // 几何只能走 style（宽度是**数据**，不是样式选择）；两端都 clamp 过 ⇒ 不会溢出轨道
+        bar.style.cssText = `left:${(left * 100).toFixed(2)}%;width:${Math.max(width * 100, 0.6).toFixed(2)}%`;
+        track.appendChild(bar);
+        track.title = `起点 ${Math.round(offset)}ms · 时长 ${Math.round(dur)}ms`;
+        row.dataset.tl = '1';
+        row.appendChild(track);
+      }
       const metaEl = el('span', 'tr-meta', meta);
       if (bad && node.error?.message) metaEl.title = node.error.message;
       row.appendChild(metaEl);
+      /* span 属性（2026-11-13）：`model` / `system.version` / `tools.names` / `retry.attempt` /
+         `handoff.*` / `guardrail.*` 全在 attributes 里，此前树上一格都不显示 ——
+         「这次是不是提示词版本没换」「是不是重试了三次」只能靠猜。
+         块体复用 `full-view.js`（纯 DOM 构造，不再写第二套渲染）。 */
+      if (attrKeys.length > 0) {
+        row.dataset.expandable = '1';
+        row.appendChild(el('span', 'tr-caret', attrOpen ? '▾' : '▸'));
+        row.addEventListener('click', () => {
+          if (!hasSelection()) toggleExpand(attrKey);
+        });
+      }
       rootEl.appendChild(row);
+      if (attrOpen) {
+        let fold = folds.get(attrKey);
+        if (!fold) {
+          fold = new Map();
+          folds.set(attrKey, fold);
+        }
+        rootEl.appendChild(createFullView(node.attributes, { fold }));
+      }
       // 失败原文必须**看得见** —— 只塞进 title（hover 才显）等于没显示。首次运行最常见的失败
       // （没配 API key）就靠这一行定位；单起一行，不去挤占 nowrap 的 span 行。
       if (bad && node.error?.message) {
@@ -237,10 +376,19 @@ export function createTraceView(rootEl, opts = {}) {
     usageEls.cost.textContent = '$' + cost.toFixed(4);
   }
 
-  /** 开树。rootName 为 run 根显示名（如 'run · 审查一份文档'） */
-  function reset(rootName) {
+  /**
+   * 开树。rootName 为 run 根显示名（如 'run · 审查一份文档'）。
+   *
+   * `rootId` = **框架给这个根 span 的真 `spanId`**（`fromTrace.js` 的 `playTrace` 会传）。
+   * 为什么必须传：根节点上的事件（`score` / `trace.truncated` / `approval.decided`）由
+   * `event(span.spanId, …)` 投递，而旧实现只把根登记在字面量 `'root'` 上 ⇒ `spanMap.get`
+   * 落空 ⇒ `event()` 静默 return。症状不是报错，是**评估结论与截断警告整类消失**，而子 span
+   * 的事件一切正常（排查时最容易被判成「框架没记」）。字面量 `'root'` 仍登记：官网
+   * playground 的模拟脚本用它当根 id，两个键指向同一节点，零成本。
+   */
+  function reset(rootName, rootId, startedAt, attributes) {
     traceRoot = {
-      id: 'root',
+      id: rootId || 'root',
       kind: 'run',
       name: rootName || 'run',
       children: [],
@@ -248,10 +396,23 @@ export function createTraceView(rootEl, opts = {}) {
       order: [],
       done: false,
       ms: 0,
+      /* 时间轴的基准（2026-11-13）：根 span 的起点。缺省 null ⇒ 整棵树不画条
+         （手写 trace / 官网模拟回放没有时间戳，画一条人人占满的条比不画更误导）。 */
+      startedAt: typeof startedAt === 'number' ? startedAt : null,
+      endAt: null,
+      /* 根 span 的属性（2026-11-13）：`model` / `system.version` / `tools.names` /
+         `prompts.versions` / `stop_reason` **只写在根上**。根行不经过 `start()`
+         （它由 reset 建），所以不在这里接一手，这些键在面板上就一格都看不到 ——
+         「这次是不是提示词版本没换」只能去翻 JSON。空对象当没有。 */
+      attributes:
+        attributes && typeof attributes === 'object' && Object.keys(attributes).length > 0
+          ? attributes
+          : null,
       usage: { input: 0, output: 0 },
     };
     spanMap.clear();
     spanMap.set('root', traceRoot);
+    if (rootId && rootId !== 'root') spanMap.set(rootId, traceRoot);
     expanded.clear(); // 展开态属于上一棵树：reset 开新树时一并清掉
     folds.clear(); // 块内折叠同理：留着只会在下一次点开时出现"莫名已折叠"的状态
     usageAcc.input = 0;
@@ -272,6 +433,9 @@ export function createTraceView(rootEl, opts = {}) {
       order: [],
       done: false,
       ms: 0,
+      startedAt: typeof s.startedAt === 'number' ? s.startedAt : null,
+      endAt: null,
+      attributes: s.attributes && typeof s.attributes === 'object' ? s.attributes : null,
       status: 'ok',
       error: null,
       usage: null,
@@ -311,6 +475,14 @@ export function createTraceView(rootEl, opts = {}) {
     if (!node) return;
     node.done = true;
     node.ms = s.ms || 0;
+    /* 终点优先取框架的真 `endedAt`（时间轴的右端）；没有就按起点 + 时长推。
+       两者都没有（手写 trace）⇒ 留 null，那一段不画条。 */
+    node.endAt =
+      typeof s.endedAt === 'number'
+        ? s.endedAt
+        : typeof node.startedAt === 'number'
+          ? node.startedAt + node.ms
+          : null;
     node.status = s.status || 'ok';
     node.error = s.error || null;
     if (s.arg) node.arg = s.arg;
@@ -337,6 +509,9 @@ export function createTraceView(rootEl, opts = {}) {
     if (!traceRoot) return;
     traceRoot.done = true;
     traceRoot.ms = ms;
+    if (typeof traceRoot.startedAt === 'number' && typeof ms === 'number') {
+      traceRoot.endAt = traceRoot.startedAt + ms;
+    }
     // run 失败时根 span 也要标红：原先 status 恒为 ok，错误只体现在子 span 上
     traceRoot.status = status || 'ok';
     traceRoot.error = error || null;
@@ -344,14 +519,76 @@ export function createTraceView(rootEl, opts = {}) {
     renderTrace();
   }
 
+  /** 当前命中行（`.tr-hit`）。宿主没有 `querySelectorAll`（stub / 极简 DOM）时返回空集 */
+  function hitRows() {
+    try {
+      if (typeof rootEl.querySelectorAll !== 'function') return [];
+      return Array.from(rootEl.querySelectorAll('.tr-hit'));
+    } catch {
+      return [];
+    }
+  }
+
+  /** 加/去一个类名（不依赖 classList：stub DOM 未必实现它） */
+  function setFlag(node, cls, on) {
+    const parts = String(node.className || '')
+      .split(/\s+/)
+      .filter((c) => c && c !== cls);
+    if (on) parts.push(cls);
+    node.className = parts.join(' ');
+  }
+
   return {
     reset,
     start,
     event,
     end,
     finish,
+    /** 把一批动作压成一次重画（`playTrace` 必用；宿主自己批量喂时也可以用） */
+    batch,
     render: renderTrace,
+    /**
+     * 树内检索：**只高亮 + 跳转，不改结构**（理由见 `query` 的头注）。返回命中行数。
+     * 空串 = 结束检索（清掉所有高亮）。
+     */
+    setQuery(q) {
+      const next = typeof q === 'string' ? q.trim() : '';
+      if (next === query) return hitRows().length;
+      query = next;
+      renderTrace();
+      return hitRows().length;
+    },
+    get hitCount() {
+      return hitRows().length;
+    },
+    /**
+     * 跳到下一处命中（`dir < 0` 向上），返回 **1 基序号**；没有命中返回 0。
+     * 越界绕回：搜索框里按 Enter 一路按到底再回到第一处，比「按不动了」更符合预期。
+     */
+    nextHit(dir = 1) {
+      const list = hitRows();
+      if (list.length === 0) return 0;
+      hitIndex = (hitIndex + (dir > 0 ? 1 : -1) + list.length) % list.length;
+      const cur = list[hitIndex];
+      for (const r of list) setFlag(r, 'tr-hit-cur', r === cur);
+      try {
+        cur.scrollIntoView?.({ block: 'center' });
+      } catch {
+        /* 没有滚动能力（stub / 老浏览器）：序号仍然对，只是没把行带进视野 */
+      }
+      return hitIndex + 1;
+    },
     setUsage: renderUsage,
+    /** 时间轴开关（默认开）。关掉只是不画轨道，数据与命中都不受影响 */
+    setTimeline(on) {
+      const next = on !== false;
+      if (next === timeline) return;
+      timeline = next;
+      renderTrace();
+    },
+    get timeline() {
+      return timeline;
+    },
     /** 换单价（如真实模式切服务商）：null 表示无公开单价 → 成本显示为 — */
     setPrice(p) {
       price = p ?? null;