[Enhancement] Record user interactions inside iframes / 录制无法捕获 iframe 内的页面报表筛选/搜索操作

[shnpd]

[Enhancement] Record user interactions inside iframes (bsk record)

Summary

bsk record does not capture clicks, fills, or selects that happen inside an iframe. On pages where the main workflow (e.g. report filters / search) lives in an embedded frame, the exported trace only contains top-frame actions (typically sidebar navigation), and the actual filter → search → query steps are missing.

This is a known limitation of the current recorder design (content script + overlay intentionally top-frame only), not a one-off regression. Scripted replay via session + snapshot/evaluate can still operate on iframe content; recording cannot.

Symptoms

• User records a flow like: open report page → set merchant filter → search → read results.
• Trace only shows top-frame steps (e.g. left-nav <span> clicks).
• Zero steps for dropdown selection, search input, or table actions inside the report iframe.
• Overlay / recording UI appears to be active, so users reasonably expect those interactions to be captured.

Evidence

Typical failing pattern:

Location	Example action	Recorded?
Top frame (sidebar / shell)	Click menu item	Yes
Report iframe	Select “Merchant” / option	No
Report iframe	Type into search box	No
Report iframe	Click search / query	No

Trace shape: a handful of top-frame click steps; no fill / iframe-target steps for the report UI.

Root cause

Recorder capture is installed only in the top-level frame.

1. Content script is top-frame only (apps/extension/src/entrypoints/content.ts):

   • defineContentScript({ allFrames: false })
   • Guard: if (window.top !== window) return;
   • Comment in code: avoid double-rendering overlays inside iframes.

2. Event listeners are bound to the top document (apps/extension/src/content/record-capture.ts):

   • click / input / change / focusin / etc. on document
   • An iframe is a separate document; DOM events do not bubble across frame boundaries.
   • Therefore the top-frame recorder never observes iframe interactions.

3. Contrast with observation / VOM: snapshot/observe already has iframe awareness (iframeNodes in capture/observation). Replay/script paths can target iframe controls; the recorder event path cannot.

Expected behavior

While recording is active, user interactions inside same-origin (and, where possible, accessible) iframes should produce the same semantic steps as top-frame interactions (click / fill / change, with correct targets), without duplicating the record overlay UI in each frame.

Current workaround

Do not rely on bsk record for iframe-heavy report flows. Use scripted replay instead:

• session + snapshot / observe (VOM already surfaces iframe controls)
• click / fill / evaluate (or equivalent) against iframe targets

Recording remains suitable for top-frame-only flows.

Proposed directions (for discussion)

1. Split concerns: inject a lightweight, overlay-free capture script into frames (allFrames: true for capture only; keep overlay top-frame-only).
2. Bridge steps: child-frame capture posts RECORD_STEP payloads to the top-frame / background recorder.
3. Same-origin first: start with same-origin iframes; document cross-origin limits explicitly.
4. UX: if iframe activity is detected during record but no steps arrive, surface a clear “interactions inside iframes are not recorded” warning.

Acceptance criteria

• Recording a same-origin iframe filter → search → submit flow yields corresponding fill/click (or equivalent) steps in the trace.
• Record overlay still renders only once (top frame).
• Top-frame-only pages behave unchanged.
• Docs / skill text state iframe recording support and remaining limitations (e.g. cross-origin).

Environment

• Feature: bsk record
• Affects: pages whose primary UI is in an iframe (common for internal report / BI shells)
• Related code:
  • apps/extension/src/entrypoints/content.ts
  • apps/extension/src/content/record-capture.ts

Priority / notes

• User-facing impact is high for report/dashboard automation (“I recorded it but the important steps are missing”).
• Fix is non-trivial (frame injection + step bridging + overlay separation).
• Until fixed, treat as a documented product limitation and steer users to scripted replay for iframe workflows.

---

【增强】录制无法捕获 iframe 内的页面报表筛选/搜索操作（bsk record）

概述

使用 bsk record 时，发生在 iframe 内的点击、输入、下拉选择等操作不会被写入 trace。若报表的筛选/搜索主流程都在嵌入帧里，导出结果往往只剩顶层壳子（如左侧导航）的步骤，真正的「筛选 → 搜索 → 取数」全部丢失。

这是当前录制器的已知设计限制（content script + overlay 刻意只挂在 top frame），不是偶发回归。session + snapshot/evaluate 的脚本化路径仍可操作 iframe；录制路径不行。

现象

• 用户录制：打开报表 → 选商户筛选 → 搜索 → 查看结果。
• Trace 只有顶层步骤（例如左侧导航 <span> 点击）。
• iframe 内的下拉、搜索框、查询按钮一步都没有。
• 录制 overlay 看起来在工作，用户会误以为 iframe 操作也被录到了。

证据

位置	示例操作	能否录到
Top frame（侧栏/壳）	点击菜单	能
报表 iframe	选择「商户」等筛选项	不能
报表 iframe	搜索框输入	不能
报表 iframe	点击查询	不能

典型 trace：少量顶层 click；没有任何对应报表 UI 的 fill / iframe 目标步骤。

根因

录制捕获只安装在 顶层 frame。

1. Content script 仅 top frame（apps/extension/src/entrypoints/content.ts）

   • allFrames: false
   • if (window.top !== window) return;
   • 注释写明：避免 overlay 在 iframe 里重复渲染。

2. 事件监听挂在顶层 document（apps/extension/src/content/record-capture.ts）

   • 监听 click / input / change 等
   • iframe 是独立 document，DOM 事件不会冒泡到父页面
   • 顶层录制器感知不到 iframe 内交互

3. 与观察/VOM 能力不对称：snapshot/observe 已有 iframeNodes，脚本回放可命中 iframe 控件；录制事件链路没有等价能力。

期望行为

录制开启时，同源（以及在可行范围内可访问的）iframe 内用户操作应产出与顶层一致的语义步骤（click / fill / change 等），且录制 overlay 不要在每个 frame 里重复出现。

当前规避方式

iframe 很重的报表流程不要走 bsk record，改用脚本化重放：

• session + snapshot / observe（VOM 已能暴露 iframe 控件）
• 对 iframe 目标执行 click / fill / evaluate 等

录制仍适用于纯顶层页面流程。

可选方案（供讨论）

1. 职责拆分：向子 frame 注入无 overlay 的轻量捕获脚本（捕获 allFrames，overlay 仍仅 top）。
2. 步骤桥接：子 frame 将 RECORD_STEP 回传到顶层/background。
3. 先做同源：优先支持 same-origin iframe，并文档化跨域限制。
4. 体验提示：检测到页面含 iframe 且录制无子帧步骤时，明确提示「iframe 内操作当前不会被录制」。

验收标准

• 同源 iframe 上「筛选 → 搜索 → 提交」能在 trace 中看到对应步骤
• 录制 overlay 仍只渲染一次（top frame）
• 纯顶层页面行为不变
• 文档/skill 写明 iframe 录制支持范围与剩余限制（如跨域）

环境与相关代码

• 功能：bsk record
• 场景：主 UI 在 iframe 内的报表/BI 壳页面
• 相关：
  • apps/extension/src/entrypoints/content.ts
  • apps/extension/src/content/record-capture.ts

优先级说明

• 对「录完却缺关键步骤」的报表自动化场景影响大。
• 修复成本不低（子帧注入 + 步骤桥接 + overlay 分离）。
• 修复前应作为产品限制文档化，并引导用户对 iframe 流程使用脚本化重放。