feat(record): export Trace v3 bundles with settled page states

apps/extension/src/content/__tests__/record-capture.test.ts

@@ -1,10 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
-import { RECORD_STOP, type RecordStepPayload } from "@/lib/record-bridge";
+import { RECORD_START, RECORD_STOP, type RecordStepPayload } from "@/lib/record-bridge";
 import { handleRecordContentMessage, startRecordCapture } from "../record-capture";
 
 vi.stubGlobal("chrome", {
   runtime: {
-    sendMessage: vi.fn(() => Promise.resolve()),
+    sendMessage: vi.fn((message: { sequence?: number }) =>
+      Promise.resolve({ ok: true, sequence: message.sequence }),
+    ),
   },
 });
 
@@ -96,6 +98,66 @@ describe("handleRecordContentMessage stop/cancel", () => {
     expect(dispose).not.toHaveBeenCalled();
     expect(onStop).not.toHaveBeenCalled();
   });
+
+  it("keeps a failed STOP retryable and redelivers its recorded step", async () => {
+    document.body.innerHTML = `<label for="retry">Draft</label><input id="retry" />`;
+    const sendMessage = vi.mocked(chrome.runtime.sendMessage);
+    sendMessage.mockReset();
+    sendMessage.mockRejectedValueOnce(new Error("service worker unavailable"));
+    sendMessage.mockRejectedValueOnce(new Error("service worker still unavailable"));
+    sendMessage.mockResolvedValueOnce({ ok: true, sequence: 1 });
+
+    let activeRequestId: string | null = null;
+    let capture: ReturnType<typeof startRecordCapture> | null = null;
+    const onStop = vi.fn();
+    const dispatch = (
+      message:
+        | { type: typeof RECORD_START; requestId: string; startedAtMs?: number }
+        | { type: typeof RECORD_STOP; requestId: string },
+      sendResponse?: (response: unknown) => void,
+    ) =>
+      handleRecordContentMessage(
+        message,
+        {
+          activeRequestId,
+          capture,
+          setActiveRequestId: (id) => {
+            activeRequestId = id;
+          },
+          setCapture: (next) => {
+            capture = next;
+          },
+          onStart: vi.fn(),
+          onStop,
+        },
+        sendResponse,
+      );
+
+    dispatch({ type: RECORD_START, requestId: "rec-retry" });
+    const input = document.querySelector("input")!;
+    input.dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+    input.value = "dirty final value";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+
+    const firstResponse = vi.fn();
+    expect(dispatch({ type: RECORD_STOP, requestId: "rec-retry" }, firstResponse)).toBe(true);
+    await vi.waitFor(() =>
+      expect(firstResponse).toHaveBeenCalledWith({
+        ok: false,
+        error: "failed to deliver one or more recorded steps",
+      }),
+    );
+    expect(activeRequestId).toBe("rec-retry");
+    expect(onStop).not.toHaveBeenCalled();
+
+    const retryResponse = vi.fn();
+    expect(dispatch({ type: RECORD_STOP, requestId: "rec-retry" }, retryResponse)).toBe(true);
+    await vi.waitFor(() => expect(retryResponse).toHaveBeenCalledWith({ ok: true }));
+
+    expect(sendMessage).toHaveBeenCalledTimes(3);
+    expect(activeRequestId).toBeNull();
+    expect(onStop).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe("record-capture semantic", () => {
@@ -228,6 +290,7 @@ describe("record-capture semantic", () => {
     expect(steps[0]).toMatchObject({
       op: "hover",
       target: { role: "button", name: "Open user navigation menu" },
+      geometry: { tag: "button", rect: { x: 900, y: 8, w: 32, h: 32 } },
     });
     expect(steps[1]).toMatchObject({
       op: "click",

apps/extension/src/content/__tests__/record-step-delivery.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it, vi } from "vitest";
+import type { RecordStepMessage } from "@/lib/record-bridge";
+import { RecordStepDelivery } from "../record-step-delivery";
+
+describe("RecordStepDelivery", () => {
+  it("retries from the first unacknowledged sequence before sending later steps", async () => {
+    const sent: RecordStepMessage[] = [];
+    const send = vi.fn(async (message: RecordStepMessage) => {
+      sent.push(message);
+      if (sent.length === 1) throw new Error("service worker unavailable");
+      return { ok: true, sequence: message.sequence };
+    });
+    const delivery = new RecordStepDelivery("rec-ordered", send, "document-1");
+
+    delivery.enqueue({ op: "click", target: { tag: "button", name: "First" } });
+    delivery.enqueue({ op: "click", target: { tag: "button", name: "Second" } });
+
+    await expect(delivery.flush()).resolves.toBe(true);
+    expect(sent.map((message) => message.sequence)).toEqual([1, 1, 2]);
+    expect(sent.map((message) => message.step.target?.name)).toEqual(["First", "First", "Second"]);
+  });
+
+  it("keeps unacknowledged steps pending for a later flush", async () => {
+    const send = vi
+      .fn<(message: RecordStepMessage) => Promise<unknown>>()
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockRejectedValueOnce(new Error("still offline"))
+      .mockImplementation(async (message) => ({ ok: true, sequence: message.sequence }));
+    const delivery = new RecordStepDelivery("rec-retry", send, "document-1");
+    delivery.enqueue({ op: "click", target: { tag: "button", name: "Save" } });
+
+    await expect(delivery.flush()).resolves.toBe(false);
+    await expect(delivery.flush()).resolves.toBe(true);
+    expect(send).toHaveBeenCalledTimes(3);
+  });
+});

apps/extension/src/content/record-capture.ts

@@ -36,27 +36,17 @@ import {
   isHoverSurfaceCandidateElement,
   isLikelyHoverSurfaceOwner,
 } from "./record-hover-surface";
+import { RecordStepDelivery } from "./record-step-delivery";
 
-const pendingStepSends = new Map<string, Set<Promise<boolean>>>();
-const failedStepDeliveries = new Set<string>();
-const knownRecordRequests = new Set<string>();
+const stepDeliveries = new Map<string, RecordStepDelivery>();
+const pendingStopFlushes = new Map<string, Promise<RecordStopAck>>();
 
-function sendRecordStep(requestId: string, step: RecordStepPayload): void {
-  const payload = { type: RECORD_STEP, requestId, step };
-  const pending = Promise.resolve(chrome.runtime.sendMessage(payload)).then(
-    () => true,
-    () => {
-      failedStepDeliveries.add(requestId);
-      return false;
-    },
-  );
-  const sends = pendingStepSends.get(requestId) ?? new Set<Promise<boolean>>();
-  sends.add(pending);
-  pendingStepSends.set(requestId, sends);
-  void pending.then(() => {
-    sends.delete(pending);
-    if (sends.size === 0) pendingStepSends.delete(requestId);
-  });
+function deliveryFor(requestId: string): RecordStepDelivery {
+  const existing = stepDeliveries.get(requestId);
+  if (existing) return existing;
+  const created = new RecordStepDelivery(requestId);
+  stepDeliveries.set(requestId, created);
+  return created;
 }
 
 export interface RecordCaptureController {
@@ -68,6 +58,7 @@ interface FillSession {
   target: CaptureTargetDescriptor;
   baselineValue: string;
   lastValue: string;
+  pendingCommit?: "enter" | "suggestion" | "blur";
 }
 
 interface HoverCandidate {
@@ -157,6 +148,24 @@ function nearbyFillableFromSearchChrome(target: Element): FillableElement | null
   return null;
 }
 
+function captureGeometry(el: Element): RecordStepPayload["geometry"] {
+  const rect = el.getBoundingClientRect();
+  return {
+    rect: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
+    tag: el.tagName.toLowerCase(),
+  };
+}
+
+function geometryForEventTarget(
+  target: EventTarget | null,
+): RecordStepPayload["geometry"] | undefined {
+  if (!(target instanceof Element)) return undefined;
+  const clickable = target.closest(
+    'a,button,input,select,textarea,[role="button"],[role="link"],[role="menuitem"],[contenteditable="true"]',
+  );
+  return captureGeometry(clickable ?? target);
+}
+
 function fillableValue(el: FillableElement): string {
   if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
     return el.value;
@@ -414,14 +423,17 @@ export function startRecordCapture(
     emitStep({
       op: "fill",
       target: session.target,
+      geometry: captureGeometry(session.element),
       value,
+      commit: session.pendingCommit ?? "blur",
       ...(isPassword ? { redacted: true } : {}),
     });
   };
 
-  const commitFillSession = () => {
+  const commitFillSession = (commit: "enter" | "suggestion" | "blur" = "blur") => {
     if (!fillSession || composing) return;
     const session = fillSession;
+    session.pendingCommit = commit;
     fillSession = null;
     emitFill(session);
     committedValues.set(session.element, session.lastValue);
@@ -627,6 +639,7 @@ export function startRecordCapture(
     emitStep({
       op: "hover",
       target: hover.target,
+      geometry: captureGeometry(hover.element),
     });
     emittedHoverElements.add(hover.element);
   };
@@ -681,6 +694,7 @@ export function startRecordCapture(
     emitStep({
       op: "click",
       target,
+      geometry: geometryForEventTarget(eventTarget(event)),
       expects_navigation: true,
     });
   };
@@ -782,7 +796,7 @@ export function startRecordCapture(
       scheduleInputCompletionCommit(
         sessionElement,
         syncFillSessionValue,
-        commitFillSession,
+        () => commitFillSession("suggestion"),
         (el) => fillSession?.element === el,
       );
       return;
@@ -842,6 +856,7 @@ export function startRecordCapture(
       emitStep({
         op: "select",
         target: desc,
+        geometry: captureGeometry(target),
         values,
         labels,
         expects_navigation: true,
@@ -882,7 +897,7 @@ export function startRecordCapture(
       };
     }
     if (fillable) {
-      commitFillSession();
+      commitFillSession(event.key === "Enter" ? "enter" : "blur");
     }
     const desc = describeEventTarget(target);
     if (!desc && !event.key) return;
@@ -890,7 +905,7 @@ export function startRecordCapture(
     emitStep({
       op: "press",
       key: event.key,
-      ...(desc ? { target: desc } : {}),
+      ...(desc ? { target: desc, geometry: geometryForEventTarget(target) } : {}),
       ...(modifiers.length ? { modifiers } : {}),
       expects_navigation: event.key === "Enter",
     });
@@ -909,9 +924,12 @@ export function startRecordCapture(
   const urlObserver = new MutationObserver(() => emitNavigateIfChanged());
   urlObserver.observe(document, { subtree: true, childList: true });
   const onUrlEvent = () => emitNavigateIfChanged();
+  // Wrap: passing commitFillSession directly would forward the DOM event as
+  // the `commit` argument and stamp it onto the recorded fill step.
+  const onPageHide = () => commitFillSession();
   window.addEventListener("hashchange", onUrlEvent);
   window.addEventListener("popstate", onUrlEvent);
-  window.addEventListener("pagehide", commitFillSession);
+  window.addEventListener("pagehide", onPageHide);
 
   const originalPushState = history.pushState;
   const originalReplaceState = history.replaceState;
@@ -939,7 +957,7 @@ export function startRecordCapture(
       urlObserver.disconnect();
       window.removeEventListener("hashchange", onUrlEvent);
       window.removeEventListener("popstate", onUrlEvent);
-      window.removeEventListener("pagehide", commitFillSession);
+      window.removeEventListener("pagehide", onPageHide);
       history.pushState = originalPushState;
       history.replaceState = originalReplaceState;
     },
@@ -965,14 +983,11 @@ export function handleRecordContentMessage(
   sendResponse?: (response: RecordStartAck | RecordStopAck) => void,
 ): boolean {
   if (isRecordStartMessage(message)) {
-    if (!knownRecordRequests.has(message.requestId)) {
-      knownRecordRequests.add(message.requestId);
-      failedStepDeliveries.delete(message.requestId);
-    }
+    const delivery = deliveryFor(message.requestId);
     state.capture?.dispose();
     state.setCapture(
       startRecordCapture(message.requestId, (step) => {
-        sendRecordStep(message.requestId, step);
+        delivery.enqueue(step);
       }),
     );
     state.setActiveRequestId(message.requestId);
@@ -995,28 +1010,37 @@ export function handleRecordContentMessage(
       state.setActiveRequestId(null);
     };
     if (isRecordStopMessage(message) && sendResponse) {
-      const pending = [...(pendingStepSends.get(message.requestId) ?? [])];
-      void Promise.all(pending).then((delivered) => {
-        finishStop();
-        const succeeded = delivered.every(Boolean) && !failedStepDeliveries.has(message.requestId);
-        if (succeeded) {
-          failedStepDeliveries.delete(message.requestId);
-          knownRecordRequests.delete(message.requestId);
-        }
-        sendResponse(
-          succeeded
+      const existingFlush = pendingStopFlushes.get(message.requestId);
+      if (existingFlush) {
+        void existingFlush.then(sendResponse);
+        return true;
+      }
+
+      const flush = deliveryFor(message.requestId)
+        .flush()
+        .then((succeeded): RecordStopAck => {
+          if (succeeded) {
+            stepDeliveries.delete(message.requestId);
+            finishStop();
+          }
+          return succeeded
             ? { ok: true }
             : {
                 ok: false,
                 error: "failed to deliver one or more recorded steps",
-              },
-        );
+              };
+        });
+      pendingStopFlushes.set(message.requestId, flush);
+      void flush.then(sendResponse).finally(() => {
+        if (pendingStopFlushes.get(message.requestId) === flush) {
+          pendingStopFlushes.delete(message.requestId);
+        }
       });
       return true;
     }
     if (isRecordCancelMessage(message)) {
-      failedStepDeliveries.delete(message.requestId);
-      knownRecordRequests.delete(message.requestId);
+      stepDeliveries.delete(message.requestId);
+      pendingStopFlushes.delete(message.requestId);
     }
     finishStop();
     return false;

apps/extension/src/content/record-step-delivery.ts

@@ -0,0 +1,65 @@
+import {
+  isAcceptedRecordStepAck,
+  RECORD_STEP,
+  type RecordStepMessage,
+  type RecordStepPayload,
+} from "@/lib/record-bridge";
+
+export type SendRecordStepMessage = (message: RecordStepMessage) => Promise<unknown>;
+
+export class RecordStepDelivery {
+  readonly #requestId: string;
+  readonly #producerId: string;
+  readonly #send: SendRecordStepMessage;
+  readonly #pending = new Map<number, RecordStepPayload>();
+  #nextSequence = 1;
+  #tail = Promise.resolve();
+
+  constructor(
+    requestId: string,
+    send: SendRecordStepMessage = (message) => chrome.runtime.sendMessage(message),
+    producerId: string = crypto.randomUUID(),
+  ) {
+    this.#requestId = requestId;
+    this.#producerId = producerId;
+    this.#send = send;
+  }
+
+  enqueue(step: RecordStepPayload): void {
+    const sequence = this.#nextSequence;
+    this.#nextSequence += 1;
+    this.#pending.set(sequence, step);
+    void this.#schedule();
+  }
+
+  async flush(): Promise<boolean> {
+    await this.#tail;
+    await this.#schedule();
+    return this.#pending.size === 0;
+  }
+
+  #schedule(): Promise<void> {
+    const drain = () => this.#drain();
+    this.#tail = this.#tail.then(drain, drain);
+    return this.#tail;
+  }
+
+  async #drain(): Promise<void> {
+    for (const [sequence, step] of this.#pending) {
+      const message: RecordStepMessage = {
+        type: RECORD_STEP,
+        requestId: this.#requestId,
+        producerId: this.#producerId,
+        sequence,
+        step,
+      };
+      try {
+        const response = await this.#send(message);
+        if (!isAcceptedRecordStepAck(response, sequence)) return;
+        this.#pending.delete(sequence);
+      } catch {
+        return;
+      }
+    }
+  }
+}

apps/extension/src/entrypoints/background.ts

@@ -172,6 +172,7 @@ export default defineBackground(() => {
   dispatcher.start();
   const recordDeps = {
     tabsApi: chrome.tabs,
+    cdp,
     sendToTab: (tabId: number, msg: Parameters<typeof chrome.tabs.sendMessage>[1]) =>
       chrome.tabs.sendMessage(tabId, msg),
     bypassOverlay: async (tabId: number, enabled: boolean) => {
@@ -188,7 +189,7 @@ export default defineBackground(() => {
   // Message listeners stay up (cheap; fire only for record message types).
   // Tab / webNavigation observation attaches lazily while a recording is
   // active — see ensureBrowserObservationListeners in tools/record.ts.
-  attachRecordStepListener();
+  attachRecordStepListener(recordDeps);
   attachRecordFinishListener(recordDeps);
   attachRecordQueryListener(recordDeps);
   if (typeof chrome.notifications?.onClicked?.addListener === "function") {

apps/extension/src/entrypoints/popup/App.test.tsx

@@ -200,6 +200,9 @@ describe("App", () => {
     expect(copied).toContain("--browser 03c3e47f");
     expect(copied).toContain('--purpose "发布 wiki 文档"');
     expect(copied).not.toMatch(/bsk record start[^\n]*--url/);
+    expect(copied).toContain("./trace");
+    expect(copied).toContain("trace.json");
+    expect(copied).toContain("states/");
     // Button label stays static; a transient toast confirms the copy.
     expect(copyButton.textContent).toContain("复制录制指令");
     await waitFor(() => expect(screen.getByRole("status").textContent).toContain("已复制"));

apps/extension/src/lib/__tests__/connection-controller.test.ts

@@ -26,20 +26,20 @@ function handshake(
 }
 
 describe("computeConnectedState (protocol-based compat)", () => {
-  it("returns connected when protocol strings match", () => {
-    expect(computeConnectedState(handshake("1.0", "1.0"), MIN_COMPATIBLE_PROTOCOL)).toEqual({
+  it("returns connected when daemon protocol equals extension protocol", () => {
+    expect(computeConnectedState(handshake("1.1", "1.0"), MIN_COMPATIBLE_PROTOCOL)).toEqual({
       kind: "connected",
     });
   });
 
   it("returns version_skew when daemon protocol minor is newer", () => {
-    expect(computeConnectedState(handshake("1.1", "1.0"))).toEqual({
+    expect(computeConnectedState(handshake("1.2", "1.0"))).toEqual({
       kind: "version_skew",
     });
   });
 
   it("returns version_skew when daemon protocol string differs but floor is satisfied", () => {
-    expect(computeConnectedState(handshake("1", "1.0"))).toEqual({
+    expect(computeConnectedState(handshake("1.1.0", "1.0"))).toEqual({
       kind: "version_skew",
     });
   });
@@ -53,7 +53,7 @@ describe("computeConnectedState (protocol-based compat)", () => {
   });
 
   it("rejects when extension is below daemon min_compatible_protocol", () => {
-    const result = computeConnectedState(handshake("1.0", "1.5"));
+    const result = computeConnectedState(handshake("1.1", "1.5"));
     expect(result.kind).toBe("rejected");
     if (result.kind === "rejected") {
       expect(result.reason).toContain("min_compatible_protocol");
@@ -65,7 +65,7 @@ describe("computeConnectedState (protocol-based compat)", () => {
     const result = computeConnectedState({
       server: "browser-skill-daemon",
       version: "0.1.0",
-      protocol_version: "1.0",
+      protocol_version: "1.1",
       min_compatible_peer: "0.1.0",
     });
     expect(result).toEqual({ kind: "connected" });
@@ -80,7 +80,7 @@ describe("computeConnectedState (protocol-based compat)", () => {
   });
 
   it("rejects malformed daemon min_compatible_protocol with a daemon-floor reason", () => {
-    const result = computeConnectedState(handshake("1.0", "not-a-protocol"));
+    const result = computeConnectedState(handshake("1.1", "not-a-protocol"));
     expect(result.kind).toBe("rejected");
     if (result.kind === "rejected") {
       expect(result.reason).toContain("daemon min_compatible_protocol");
@@ -242,11 +242,11 @@ describe("ConnectionController connectionEnabled", () => {
     const second = transport.send.mock.calls[1]?.[0] as { id: string };
     expect(second.id).not.toBe(first.id);
 
-    transport.emitMessage({ id: first.id, result: handshake("1.0", "1.0") });
+    transport.emitMessage({ id: first.id, result: handshake("1.1", "1.0") });
     await Promise.resolve();
     expect(controller.snapshot().state).not.toBe("connected");
 
-    transport.emitMessage({ id: second.id, result: handshake("1.0", "1.0") });
+    transport.emitMessage({ id: second.id, result: handshake("1.1", "1.0") });
     await vi.waitFor(() => expect(controller.snapshot().state).toBe("connected"));
   });
 });

apps/extension/src/lib/__tests__/record-bridge.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import {
+  isAcceptedRecordStepAck,
+  isRecordStepMessage,
+  RECORD_STEP,
+  type RecordStepMessage,
+} from "../record-bridge";
+
+const message: RecordStepMessage = {
+  type: RECORD_STEP,
+  requestId: "rec-1",
+  producerId: "document-1",
+  sequence: 1,
+  step: { op: "click", target: { tag: "button", name: "Submit" } },
+};
+
+describe("record step delivery protocol", () => {
+  it("requires a producer and a positive integer sequence", () => {
+    expect(isRecordStepMessage(message)).toBe(true);
+    expect(isRecordStepMessage({ ...message, producerId: "" })).toBe(false);
+    expect(isRecordStepMessage({ ...message, sequence: 0 })).toBe(false);
+    expect(isRecordStepMessage({ ...message, sequence: 1.5 })).toBe(false);
+  });
+
+  it("accepts only the acknowledgement for the sent sequence", () => {
+    expect(isAcceptedRecordStepAck({ ok: true, sequence: 2 }, 2)).toBe(true);
+    expect(isAcceptedRecordStepAck({ ok: true, sequence: 1 }, 2)).toBe(false);
+    expect(isAcceptedRecordStepAck({ ok: false, expectedSequence: 2, error: "gap" }, 2)).toBe(
+      false,
+    );
+  });
+});

apps/extension/src/lib/__tests__/recording-runtime.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
+
+const captureRecordingObservation = vi.hoisted(() => vi.fn());
+
+vi.mock("../recording/observation-capture", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../recording/observation-capture")>();
+  return { ...actual, captureRecordingObservation };
+});
+
+import { ObservationNodeIndex } from "../recording/observation-capture";
+import { RecordingObservationRuntime } from "../recording/recording-runtime";
+
+function observation() {
+  return {
+    rootFrameId: "root",
+    index: new ObservationNodeIndex({ rootFrameId: "root", frameDocuments: [], refs: [] }),
+    url: "https://example.com/",
+    title: "Example",
+    vomText: '@vom 1\nRootWebArea "Example"',
+    truncated: false,
+  };
+}
+
+function runtime(): RecordingObservationRuntime {
+  return new RecordingObservationRuntime({
+    cdp: { send: vi.fn() as unknown as CdpRunner["send"] },
+    tabsApi: { get: vi.fn(), query: vi.fn() } as unknown as ChromeTabsApi,
+  });
+}
+
+describe("RecordingObservationRuntime", () => {
+  afterEach(() => captureRecordingObservation.mockReset());
+
+  it("shares one initial capture and includes it in flush", async () => {
+    let release!: (value: ReturnType<typeof observation>) => void;
+    captureRecordingObservation.mockReturnValueOnce(
+      new Promise((resolve) => {
+        release = resolve;
+      }),
+    );
+    const recording = runtime();
+
+    const first = recording.captureInitial(7);
+    const second = recording.captureInitial(7);
+    const flushed = recording.flush();
+    let flushCompleted = false;
+    void flushed.then(() => {
+      flushCompleted = true;
+    });
+
+    await Promise.resolve();
+    expect(captureRecordingObservation).toHaveBeenCalledTimes(1);
+    expect(flushCompleted).toBe(false);
+
+    release(observation());
+    await Promise.all([first, second, flushed]);
+    expect(flushCompleted).toBe(true);
+  });
+
+  it("cancels an in-flight initial capture", async () => {
+    captureRecordingObservation.mockImplementationOnce(
+      (input: { signal?: AbortSignal }) =>
+        new Promise((_, reject) => {
+          input.signal?.addEventListener(
+            "abort",
+            () => reject(new DOMException("observation aborted", "AbortError")),
+            { once: true },
+          );
+        }),
+    );
+    const recording = runtime();
+
+    const pending = recording.captureInitial(7);
+    recording.cancel();
+
+    await expect(pending).rejects.toMatchObject({ name: "AbortError" });
+  });
+
+  it("retries a failed initial capture when the recording settles at stop", async () => {
+    captureRecordingObservation
+      .mockRejectedValueOnce(new Error("document swapped"))
+      .mockResolvedValueOnce(observation());
+    const recording = runtime();
+
+    await expect(recording.captureInitial(7)).rejects.toThrow("document swapped");
+    await recording.settleTrailing(7, []);
+    const trace = recording.buildTrace({
+      drafts: [],
+      startedAt: "2026-08-19T00:00:00.000Z",
+      stoppedBy: "user_finish",
+      bskVersion: "0.1.6",
+    });
+
+    expect(captureRecordingObservation).toHaveBeenCalledTimes(2);
+    expect(trace.states).toHaveLength(1);
+  });
+});

apps/extension/src/lib/__tests__/step-buffer.test.ts

@@ -18,6 +18,39 @@ describe("recording-step-buffer", () => {
     expect(buffer.pendingNavigation).toBe(true);
   });
 
+  it("keeps the hovered element description as a capture fallback", () => {
+    const buffer = { steps: [], pendingNavigation: false };
+    appendRecordedPayload(
+      buffer,
+      {
+        op: "hover",
+        target: { tag: "button", role: "button", name: "新建" },
+        geometry: {
+          rect: { x: 900, y: 8, w: 60, h: 32 },
+          tag: "button",
+        },
+      },
+      {
+        geometry: {
+          rect: { x: 900, y: 8, w: 60, h: 32 },
+          tag: "button",
+        },
+      },
+    );
+    expect(buffer.steps).toEqual([
+      {
+        op: "hover",
+        captureTarget: { tag: "button", role: "button", name: "新建" },
+        targetHint: {
+          geometry: {
+            rect: { x: 900, y: 8, w: 60, h: 32 },
+            tag: "button",
+          },
+        },
+      },
+    ]);
+  });
+
   it("annotates navigated_to on action-caused navigation instead of wait_for_navigation", () => {
     const buffer = {
       steps: [
@@ -71,10 +104,54 @@ describe("recording-step-buffer", () => {
       currentUrl: "https://example.com/a",
       pendingNavigation: false,
     };
-    observeRecordedNavigation(buffer, "https://example.com/b", false);
+    const result = observeRecordedNavigation(buffer, "https://example.com/b", false);
+    expect(result).toEqual({ kind: "appended", index: 0 });
     expect(buffer.steps[0]).toMatchObject({
       op: "navigate",
       url: "https://example.com/b",
     });
   });
+
+  it("asks the recorder to coalesce redirect hops instead of emitting each one", () => {
+    const buffer = {
+      steps: [],
+      currentUrl: "https://passport.example/login",
+      pendingNavigation: false,
+    };
+    const hop1 = observeRecordedNavigation(
+      buffer,
+      "https://passport.example/callback",
+      false,
+      "link",
+      ["server_redirect"],
+    );
+    expect(hop1).toEqual({
+      kind: "coalesce_redirect",
+      url: "https://passport.example/callback",
+    });
+    expect(buffer.steps).toEqual([]);
+
+    const hop2 = observeRecordedNavigation(buffer, "https://app.example/dashboard", false, "link", [
+      "client_redirect",
+    ]);
+    expect(hop2).toEqual({
+      kind: "coalesce_redirect",
+      url: "https://app.example/dashboard",
+    });
+    expect(buffer.steps).toEqual([]);
+    expect(buffer.currentUrl).toBe("https://app.example/dashboard");
+  });
+
+  it("does not reuse redirect metadata for a later content-observed URL change", () => {
+    const buffer = {
+      steps: [],
+      currentUrl: "https://example.com/redirect",
+      pendingNavigation: false,
+    };
+
+    const result = observeRecordedNavigation(buffer, "https://example.com/spa");
+
+    expect(result).toEqual({ kind: "appended", index: 0 });
+    expect(buffer.steps[0]).toMatchObject({ op: "navigate", url: "https://example.com/spa" });
+  });
 });

apps/extension/src/lib/record-bridge.ts

@@ -16,6 +16,10 @@ export interface RecordStartAck {
   ok: true;
 }
 
+export type RecordStepAck =
+  | { ok: true; sequence: number }
+  | { ok: false; expectedSequence: number; error: string };
+
 export type RecordStopAck = { ok: true } | { ok: false; error: string };
 
 export interface RecordQueryMessage {
@@ -50,17 +54,30 @@ export interface RecordStepPayload {
   labels?: string[];
   url?: string;
   redacted?: boolean;
+  commit?: "enter" | "suggestion" | "blur";
   /** Page URL when the step was captured. */
   page_url?: string;
+  /** Event-target bounds in the source frame's viewport coordinate space. */
+  geometry?: {
+    rect: { x: number; y: number; w: number; h: number };
+    tag: string;
+  };
   /** Capture-only hint; never persisted unless converted to navigated_to. */
   expects_navigation?: boolean;
   /** Whether an observed URL change was synchronously caused by the action. */
   navigation_caused_by_action?: boolean;
+  /** Raw webNavigation transition metadata for cause mapping. */
+  transitionType?: string;
+  transitionQualifiers?: string[];
 }
 
 export interface RecordStepMessage {
   type: typeof RECORD_STEP;
   requestId: string;
+  /** Stable for the lifetime of one content-script document. */
+  producerId: string;
+  /** Monotonic within one content-script producer and recording request. */
+  sequence: number;
   step: RecordStepPayload;
 }
 
@@ -112,8 +129,27 @@ export function isRecordQueryMessage(msg: unknown): msg is RecordQueryMessage {
 export function isRecordStepMessage(msg: unknown): msg is RecordStepMessage {
   if (typeof msg !== "object" || msg === null) return false;
   const m = msg as Record<string, unknown>;
-  if (m.type !== RECORD_STEP || typeof m.requestId !== "string") return false;
+  if (
+    m.type !== RECORD_STEP ||
+    typeof m.requestId !== "string" ||
+    typeof m.producerId !== "string" ||
+    m.producerId.length === 0 ||
+    typeof m.sequence !== "number" ||
+    !Number.isSafeInteger(m.sequence) ||
+    m.sequence < 1
+  ) {
+    return false;
+  }
   const step = m.step;
   if (typeof step !== "object" || step === null) return false;
   return typeof (step as RecordStepPayload).op === "string";
 }
+
+export function isAcceptedRecordStepAck(
+  value: unknown,
+  sequence: number,
+): value is Extract<RecordStepAck, { ok: true }> {
+  if (typeof value !== "object" || value === null) return false;
+  const ack = value as Partial<RecordStepAck>;
+  return ack.ok === true && ack.sequence === sequence;
+}

apps/extension/src/lib/recording/navigation-policy.ts

@@ -0,0 +1,5 @@
+const REDIRECT_QUALIFIERS = new Set(["client_redirect", "server_redirect"]);
+
+export function hasRedirectQualifier(qualifiers?: readonly string[]): boolean {
+  return (qualifiers ?? []).some((qualifier) => REDIRECT_QUALIFIERS.has(qualifier));
+}

apps/extension/src/lib/recording/recording-runtime.ts

@@ -0,0 +1,176 @@
+import type { CdpRunner, ChromeTabsApi } from "@/tools/shared";
+import type { StopReason, TraceV3 } from "@/transport/types";
+import type { DocumentSettleScope } from "./document-settle";
+import { RecordingObservationSession } from "./observation-session";
+import { inferMissingPostStates, SettleController } from "./settle-controller";
+import { RecordingStateRegistry } from "./state-registry";
+import { buildTraceV3 } from "./trace-builder-v3";
+import type { RecordingDraftStep, StepAnnotation } from "./types";
+
+interface TabRecordingContext {
+  session: RecordingObservationSession;
+  settle: SettleController;
+  initialCapture: PendingInitialCapture | null;
+}
+
+interface PendingInitialCapture {
+  promise: Promise<void>;
+  abort: AbortController;
+}
+
+export class RecordingObservationRuntime {
+  readonly #cdp: CdpRunner;
+  readonly #tabsApi: ChromeTabsApi;
+  readonly #registry = new RecordingStateRegistry();
+  readonly #annotations: StepAnnotation[] = [];
+  readonly #contexts = new Map<number, TabRecordingContext>();
+  readonly #maxTokens?: number;
+  readonly #redactValues: boolean;
+
+  constructor(input: {
+    cdp: CdpRunner;
+    tabsApi: ChromeTabsApi;
+    maxTokens?: number;
+    redactValues?: boolean;
+  }) {
+    this.#cdp = input.cdp;
+    this.#tabsApi = input.tabsApi;
+    this.#maxTokens = input.maxTokens;
+    this.#redactValues = input.redactValues ?? false;
+  }
+
+  #context(tabId: number): TabRecordingContext {
+    const existing = this.#contexts.get(tabId);
+    if (existing) return existing;
+    const session = new RecordingObservationSession({
+      registry: this.#registry,
+      annotations: this.#annotations,
+      maxTokens: this.#maxTokens,
+      redactValues: this.#redactValues,
+    });
+    const context: TabRecordingContext = {
+      session,
+      settle: new SettleController({
+        session,
+        cdp: this.#cdp,
+        tabsApi: this.#tabsApi,
+        tabId,
+      }),
+      initialCapture: null,
+    };
+    this.#contexts.set(tabId, context);
+    return context;
+  }
+
+  async captureInitial(tabId: number): Promise<void> {
+    const context = this.#context(tabId);
+    if (context.session.cursor.lastSettled) return;
+    if (context.initialCapture) return context.initialCapture.promise;
+
+    const abort = new AbortController();
+    let pending!: PendingInitialCapture;
+    const promise = context.session.capture(this.#cdp, this.#tabsApi, tabId, abort.signal);
+    pending = {
+      abort,
+      promise: promise
+        .then(() => {})
+        .finally(() => {
+          if (context.initialCapture === pending) context.initialCapture = null;
+        }),
+    };
+    context.initialCapture = pending;
+    return pending.promise;
+  }
+
+  async processDraft(
+    tabId: number,
+    drafts: RecordingDraftStep[],
+    draftIndex: number,
+    scope?: DocumentSettleScope,
+  ): Promise<void> {
+    const draft = drafts[draftIndex];
+    if (!draft) return;
+    const context = this.#context(tabId);
+    if (!context.session.cursor.lastSettled) {
+      try {
+        await this.captureInitial(tabId);
+      } catch {
+        // Post-action settle can still provide a usable state.
+      }
+    }
+    context.session.bindDraft(draft, draftIndex + 1, context.settle.hasPending);
+    context.settle.schedule(drafts, draftIndex, scope);
+  }
+
+  scheduleSettle(
+    tabId: number,
+    drafts: RecordingDraftStep[],
+    draftIndex: number,
+    scope?: DocumentSettleScope,
+  ): void {
+    this.#context(tabId).settle.schedule(drafts, draftIndex, scope);
+  }
+
+  clearRedirect(tabId: number): void {
+    this.#contexts.get(tabId)?.settle.clearRedirect();
+  }
+
+  scheduleRedirect(tabId: number, drafts: RecordingDraftStep[], url: string): void {
+    this.#context(tabId).settle.scheduleRedirect(drafts, url);
+  }
+
+  async flushRedirects(): Promise<void> {
+    for (const context of this.#contexts.values()) await context.settle.flushRedirects();
+  }
+
+  async flush(): Promise<void> {
+    await Promise.allSettled(
+      [...this.#contexts.values()].flatMap((context) =>
+        context.initialCapture ? [context.initialCapture.promise] : [],
+      ),
+    );
+    await this.flushRedirects();
+    for (const context of this.#contexts.values()) await context.settle.flush();
+  }
+
+  async settleTrailing(tabId: number, drafts: RecordingDraftStep[]): Promise<void> {
+    const context = this.#context(tabId);
+    if (context.initialCapture) await Promise.allSettled([context.initialCapture.promise]);
+    if (!context.session.cursor.lastSettled) {
+      try {
+        await this.captureInitial(tabId);
+      } catch {
+        // The trace may remain observation-free when CDP is unavailable.
+      }
+    }
+    await context.settle.settleTrailing(drafts);
+    inferMissingPostStates(drafts);
+  }
+
+  cancel(): void {
+    for (const context of this.#contexts.values()) {
+      context.initialCapture?.abort.abort();
+      context.settle.cancel();
+    }
+  }
+
+  buildTrace(input: {
+    drafts: RecordingDraftStep[];
+    startedAt: string;
+    purpose?: string;
+    startUrl?: string;
+    stoppedBy: StopReason;
+    bskVersion: string;
+  }): TraceV3 {
+    return buildTraceV3({
+      registry: this.#registry,
+      drafts: input.drafts,
+      annotations: this.#annotations,
+      startedAt: input.startedAt,
+      purpose: input.purpose,
+      startUrl: input.startUrl,
+      stoppedBy: input.stoppedBy,
+      bskVersion: input.bskVersion,
+    });
+  }
+}

apps/extension/src/lib/recording/settle-controller.ts

@@ -212,6 +212,7 @@ export class SettleController {
       url: finalUrl,
       pageUrl: finalUrl,
       cause: "browser",
+      transitionQualifiers: ["server_redirect"],
       preStateId: this.#session.cursor.lastSettled?.stateId,
     };
     drafts.push(draft);

apps/extension/src/lib/recording/step-buffer.ts

@@ -1,5 +1,6 @@
 import type { RecordStepPayload } from "../record-bridge";
-import type { RecordingDraftStep } from "./types";
+import { hasRedirectQualifier } from "./navigation-policy";
+import type { RecordingDraftStep, TargetMatchHint } from "./types";
 
 export interface RecordingStepBuffer {
   steps: RecordingDraftStep[];
@@ -10,33 +11,29 @@ export interface RecordingStepBuffer {
 
 const NAVIGATION_TRIGGER_WINDOW_MS = 3_000;
 
-function toDraftStep(payload: RecordStepPayload): RecordingDraftStep | null {
+function toDraftStep(
+  payload: RecordStepPayload,
+  targetHint?: TargetMatchHint,
+): RecordingDraftStep | null {
   const pageUrl = payload.page_url;
+  const common = {
+    ...(pageUrl ? { pageUrl } : {}),
+    ...(targetHint ? { targetHint } : {}),
+  };
   switch (payload.op) {
     case "click":
-      return payload.target
-        ? {
-            op: "click",
-            captureTarget: payload.target,
-            ...(pageUrl ? { pageUrl } : {}),
-          }
-        : null;
+      return payload.target ? { op: "click", captureTarget: payload.target, ...common } : null;
     case "hover":
-      return payload.target
-        ? {
-            op: "hover",
-            captureTarget: payload.target,
-            ...(pageUrl ? { pageUrl } : {}),
-          }
-        : null;
+      return payload.target ? { op: "hover", captureTarget: payload.target, ...common } : null;
     case "fill":
       return payload.target
         ? {
             op: "fill",
             captureTarget: payload.target,
             value: payload.value ?? "",
+            ...(payload.commit ? { commit: payload.commit } : {}),
             ...(payload.redacted ? { redacted: true } : {}),
-            ...(pageUrl ? { pageUrl } : {}),
+            ...common,
           }
         : null;
     case "press":
@@ -46,7 +43,7 @@ function toDraftStep(payload: RecordStepPayload): RecordingDraftStep | null {
             key: payload.key,
             ...(payload.target ? { captureTarget: payload.target } : {}),
             ...(payload.modifiers?.length ? { modifiers: payload.modifiers } : {}),
-            ...(pageUrl ? { pageUrl } : {}),
+            ...common,
           }
         : null;
     case "select":
@@ -56,7 +53,7 @@ function toDraftStep(payload: RecordStepPayload): RecordingDraftStep | null {
             captureTarget: payload.target,
             values: payload.values,
             ...(payload.labels?.length ? { labels: payload.labels } : {}),
-            ...(pageUrl ? { pageUrl } : {}),
+            ...common,
           }
         : null;
     case "navigate":
@@ -64,26 +61,35 @@ function toDraftStep(payload: RecordStepPayload): RecordingDraftStep | null {
   }
 }
 
-function annotateLastStepNavigation(buffer: RecordingStepBuffer, url: string): boolean {
-  for (let i = buffer.steps.length - 1; i >= 0; i -= 1) {
-    const step = buffer.steps[i];
+function annotateLastStepNavigation(buffer: RecordingStepBuffer, url: string): number {
+  for (let index = buffer.steps.length - 1; index >= 0; index -= 1) {
+    const step = buffer.steps[index];
     if (!step) continue;
-    if (step.op === "click" || step.op === "press" || step.op === "select") {
-      buffer.steps[i] = { ...step, navigatedTo: url };
-      return true;
+    if (step.op === "click" || step.op === "press" || step.op === "select" || step.op === "fill") {
+      step.navigatedTo = url;
+      return index;
     }
     break;
   }
-  return false;
+  return -1;
 }
 
+export type NavigationObserveResult =
+  | { kind: "noop" }
+  | { kind: "annotated"; index: number }
+  | { kind: "appended"; index: number }
+  | { kind: "coalesce_redirect"; url: string };
+
 export function observeRecordedNavigation(
   buffer: RecordingStepBuffer,
   url: string,
   causedByAction?: boolean,
-): void {
-  if (!url || url === buffer.currentUrl) return;
+  transitionType?: string,
+  transitionQualifiers?: string[],
+): NavigationObserveResult {
+  if (!url || url === buffer.currentUrl) return { kind: "noop" };
   buffer.currentUrl = url;
+
   const pendingIsCurrent =
     buffer.pendingNavigation &&
     (buffer.pendingNavigationDeadline === undefined ||
@@ -92,40 +98,47 @@ export function observeRecordedNavigation(
   if (causedByAction === true || (causedByAction === undefined && pendingIsCurrent)) {
     buffer.pendingNavigation = false;
     buffer.pendingNavigationDeadline = undefined;
-    if (!annotateLastStepNavigation(buffer, url)) {
-      buffer.steps.push({
-        op: "navigate",
-        url,
-        pageUrl: url,
-      });
-    }
-    return;
+    const annotatedIndex = annotateLastStepNavigation(buffer, url);
+    if (annotatedIndex >= 0) return { kind: "annotated", index: annotatedIndex };
+  } else {
+    buffer.pendingNavigation = false;
+    buffer.pendingNavigationDeadline = undefined;
   }
 
-  buffer.pendingNavigation = false;
-  buffer.pendingNavigationDeadline = undefined;
+  if (hasRedirectQualifier(transitionQualifiers)) {
+    return { kind: "coalesce_redirect", url };
+  }
   buffer.steps.push({
     op: "navigate",
     url,
     pageUrl: url,
+    transitionType,
+    transitionQualifiers,
   });
+  return { kind: "appended", index: buffer.steps.length - 1 };
 }
 
 export function appendRecordedPayload(
   buffer: RecordingStepBuffer,
   payload: RecordStepPayload,
-): void {
+  targetHint?: TargetMatchHint,
+): number | null {
   if (payload.op === "navigate") {
-    if (payload.url) {
-      observeRecordedNavigation(buffer, payload.url, payload.navigation_caused_by_action);
-    }
-    return;
+    if (!payload.url) return null;
+    const result = observeRecordedNavigation(
+      buffer,
+      payload.url,
+      payload.navigation_caused_by_action,
+      payload.transitionType,
+      payload.transitionQualifiers,
+    );
+    return result.kind === "appended" ? result.index : null;
   }
-  const step = toDraftStep({
-    ...payload,
-    page_url: payload.page_url ?? buffer.currentUrl,
-  });
-  if (!step) return;
+  const step = toDraftStep(
+    { ...payload, page_url: payload.page_url ?? buffer.currentUrl },
+    targetHint,
+  );
+  if (!step) return null;
   buffer.steps.push(step);
   if (step.op === "click" || step.op === "press" || step.op === "select" || step.op === "fill") {
     buffer.pendingNavigation = payload.expects_navigation === true;
@@ -133,4 +146,5 @@ export function appendRecordedPayload(
       ? Date.now() + NAVIGATION_TRIGGER_WINDOW_MS
       : undefined;
   }
+  return buffer.steps.length - 1;
 }

apps/extension/src/lib/recording/trace-reducer-v3.ts

@@ -1,5 +1,6 @@
 import type { NavigationCause, StepV3 } from "@/transport/types";
 import { shouldIncludeDraft } from "./draft-policy";
+import { hasRedirectQualifier } from "./navigation-policy";
 import { unmatchedTarget } from "./target-matcher";
 import type { RecordingDraftStep } from "./types";
 
@@ -8,7 +9,6 @@ interface CollapsedDraft {
   draftIds: number[];
 }
 
-const REDIRECT_QUALIFIERS = new Set(["client_redirect", "server_redirect"]);
 const TRANSITION_CAUSES: Record<string, NavigationCause> = {
   typed: "user_typed",
   generated: "user_typed",
@@ -22,7 +22,7 @@ const TRANSITION_CAUSES: Record<string, NavigationCause> = {
 };
 
 function isRedirect(step: Extract<RecordingDraftStep, { op: "navigate" }>): boolean {
-  return (step.transitionQualifiers ?? []).some((qualifier) => REDIRECT_QUALIFIERS.has(qualifier));
+  return hasRedirectQualifier(step.transitionQualifiers);
 }
 
 function collapseRedirects(steps: RecordingDraftStep[]): CollapsedDraft[] {

apps/extension/src/tools/record.ts

@@ -15,22 +15,27 @@ import {
   type RecordQueryResponse,
   type RecordStartAck,
   type RecordStartMessage,
+  type RecordStepAck,
   type RecordStopMessage,
 } from "@/lib/record-bridge";
+import { RecordingObservationRuntime } from "@/lib/recording/recording-runtime";
 import { appendRecordedPayload, observeRecordedNavigation } from "@/lib/recording/step-buffer";
 import { buildTraceV2 } from "@/lib/recording/trace-reducer-v2";
 import type { RecordingDraftStep } from "@/lib/recording/types";
 import type { SessionManager } from "@/session-manager/manager";
+import { EXTENSION_VERSION } from "@/transport/handshake";
 import type {
   RecordAwaitParams,
   RecordAwaitResult,
+  RecordedTrace,
   RecordStartParams,
   RecordStartResult,
   RecordStopParams,
   RecordStopResult,
   RpcError,
-  TraceV2,
+  StopReason,
 } from "@/transport/types";
+import { TRACE_VERSION_V3 } from "@/transport/types";
 import { handleNavigate } from "./navigation";
 import {
   type CdpRunner,
@@ -50,14 +55,32 @@ interface ActiveRecording {
   steps: RecordingDraftStep[];
   startedAt: string;
   startedAtMs: number;
-  finishPromise: Promise<TraceV2>;
-  resolveFinish: (trace: TraceV2) => void;
+  traceVersion: 2 | 3;
+  finishPromise: Promise<RecordedTrace>;
+  resolveFinish: (trace: RecordedTrace) => void;
   rejectFinish: (err: Error) => void;
   settled: boolean;
-  finishing: boolean;
+  finishAttempt: Promise<RecordedTrace | null> | null;
   currentUrl?: string;
   pendingNavigation: boolean;
   pendingNavigationDeadline?: number;
+  observation: RecordingObservationRuntime | null;
+  stoppedBy: StopReason;
+  /** Navigation callbacks tracked from event receipt through action enqueue. */
+  navigationCallbacks: Set<Promise<void>>;
+  /** Synchronous intake gate closed only after finish drains to stability. */
+  acceptingNavigation: boolean;
+  /**
+   * Serializes step appends with navigation observation so a click is always
+   * in `steps` before a same-turn `webNavigation` tries to annotate it.
+   */
+  actionQueue: Promise<void>;
+  /** Last accepted sequence for each content-script document producer. */
+  lastStepSequenceByProducer: Map<string, number>;
+}
+
+function enqueueRecordingAction(recording: ActiveRecording, task: () => Promise<void>): void {
+  recording.actionQueue = recording.actionQueue.then(task, task).catch(() => {});
 }
 
 const recordings = new Map<string, ActiveRecording>();
@@ -78,6 +101,9 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+/** Recording producer version mirrored into trace.recorder.bsk. */
+export const BSK_TRACE_VERSION = EXTENSION_VERSION;
+
 /** Injectable http(s) landing page when `tool.record_start` omits `url`. */
 export const RECORD_DEFAULT_START_URL = "https://example.com/";
 
@@ -154,7 +180,29 @@ async function sendRecordStartWithAck(
   throw lastError ?? new Error("failed to start recording in content script");
 }
 
-function buildTrace(recording: ActiveRecording): TraceV2 {
+function negotiatedTraceVersion(params: RecordStartParams): 2 | 3 | RpcError {
+  if (params.trace_version === undefined) return 2;
+  if (params.trace_version === TRACE_VERSION_V3) return 3;
+  return {
+    code: "invalid_params",
+    message: `unsupported trace_version ${params.trace_version}; supported values are omitted (v2) or ${TRACE_VERSION_V3} (v3)`,
+  };
+}
+
+function buildTrace(recording: ActiveRecording): RecordedTrace {
+  if (recording.traceVersion === 3 && recording.observation) {
+    return recording.observation.buildTrace({
+      drafts: recording.steps,
+      startedAt: recording.startedAt,
+      purpose: recording.purpose,
+      startUrl: recording.startUrl,
+      stoppedBy: recording.stoppedBy,
+      bskVersion: BSK_TRACE_VERSION,
+    });
+  }
+  if (recording.traceVersion === 3) {
+    throw new Error("trace v3 observation runtime is unavailable");
+  }
   return buildTraceV2({
     steps: recording.steps,
     startedAt: recording.startedAt,
@@ -163,6 +211,19 @@ function buildTrace(recording: ActiveRecording): TraceV2 {
   });
 }
 
+async function processRecordedStep(
+  recording: ActiveRecording,
+  draftIndex: number,
+  tabId: number,
+): Promise<void> {
+  if (!recording.observation) return;
+  try {
+    await recording.observation.processDraft(tabId, recording.steps, draftIndex);
+  } catch (err) {
+    console.warn(`[bsk record] observation failed for step ${draftIndex + 1}`, err);
+  }
+}
+
 export interface RecordDeps {
   tabsApi: ChromeTabsApi;
   sendToTab(
@@ -237,16 +298,41 @@ export function releaseBrowserObservationListenersIfIdle(): void {
   detachBrowserObservation = null;
 }
 
-export function attachRecordStepListener(): () => void {
+export function attachRecordStepListener(deps: RecordDeps = getDefaultDeps()): () => void {
   const listener = (
     message: unknown,
-    _sender: chrome.runtime.MessageSender,
-    _sendResponse: () => void,
+    sender: chrome.runtime.MessageSender,
+    sendResponse: (response: RecordStepAck) => void,
   ) => {
     if (!isRecordStepMessage(message)) return false;
     for (const recording of recordings.values()) {
       if (recording.requestId !== message.requestId) continue;
-      appendRecordedPayload(recording, message.step);
+      const sourceTabId = sender.tab?.id ?? recording.tabId;
+      const producerKey = `${sourceTabId}:${message.producerId}`;
+      const expectedSequence = (recording.lastStepSequenceByProducer.get(producerKey) ?? 0) + 1;
+      if (message.sequence < expectedSequence) {
+        sendResponse({ ok: true, sequence: message.sequence });
+        return false;
+      }
+      if (message.sequence > expectedSequence) {
+        sendResponse({
+          ok: false,
+          expectedSequence,
+          error: `out-of-order recorded step ${message.sequence}`,
+        });
+        return false;
+      }
+
+      recording.lastStepSequenceByProducer.set(producerKey, message.sequence);
+      enqueueRecordingAction(recording, async () => {
+        await recording.observation?.flushRedirects();
+        const targetHint = message.step.geometry ? { geometry: message.step.geometry } : undefined;
+        const draftIndex = appendRecordedPayload(recording, message.step, targetHint);
+        if (draftIndex !== null) {
+          await processRecordedStep(recording, draftIndex, sourceTabId);
+        }
+      });
+      sendResponse({ ok: true, sequence: message.sequence });
       return false;
     }
     return false;
@@ -428,11 +514,60 @@ export function attachRecordTabListener(deps: RecordDeps = getDefaultDeps()): ()
 }
 
 export function attachRecordNavigationListener(deps: RecordDeps = getDefaultDeps()): () => void {
-  const observeMainFrame = (tabId: number, url?: string, causedByAction?: boolean) => {
+  const observeMainFrame = (
+    tabId: number,
+    url?: string,
+    causedByAction?: boolean,
+    transitionType?: string,
+    transitionQualifiers?: string[],
+  ) => {
+    if (!url) return;
+    const direct = findRecordingByTabId(tabId);
+    const candidates = direct
+      ? direct.acceptingNavigation
+        ? [direct]
+        : []
+      : [...recordings.values()].filter(
+          (recording) => !recording.settled && recording.acceptingNavigation,
+        );
+    if (candidates.length === 0) return;
+
+    let resolveTracked!: () => void;
+    const tracked = new Promise<void>((resolve) => {
+      resolveTracked = resolve;
+    });
+    for (const candidate of candidates) candidate.navigationCallbacks.add(tracked);
+
     void (async () => {
-      const recording = await findRecordingForTab(tabId, deps);
-      if (recording && url) {
-        observeRecordedNavigation(recording, url, causedByAction);
+      try {
+        const recording = await findRecordingForTab(tabId, deps);
+        if (!recording || !recording.acceptingNavigation || !candidates.includes(recording)) {
+          return;
+        }
+        enqueueRecordingAction(recording, async () => {
+          const result = observeRecordedNavigation(
+            recording,
+            url,
+            causedByAction,
+            transitionType,
+            transitionQualifiers,
+          );
+          if (result.kind === "coalesce_redirect") {
+            recording.observation?.scheduleRedirect(tabId, recording.steps, result.url);
+            return;
+          }
+
+          if (result.kind === "noop") return;
+          recording.observation?.clearRedirect(tabId);
+          if (result.kind === "appended") {
+            await processRecordedStep(recording, result.index, tabId);
+          } else {
+            recording.observation?.scheduleSettle(tabId, recording.steps, result.index);
+          }
+        });
+      } finally {
+        for (const candidate of candidates) candidate.navigationCallbacks.delete(tracked);
+        resolveTracked();
       }
     })();
   };
@@ -454,18 +589,13 @@ export function attachRecordNavigationListener(deps: RecordDeps = getDefaultDeps
       details: chrome.webNavigation.WebNavigationTransitionCallbackDetails,
     ) => {
       if (details.frameId !== 0) return;
-      const causedByAction =
-        details.transitionType === "link" || details.transitionType === "form_submit"
-          ? true
-          : details.transitionType === "typed" ||
-              details.transitionType === "auto_bookmark" ||
-              details.transitionType === "generated" ||
-              details.transitionType === "keyword" ||
-              details.transitionType === "keyword_generated" ||
-              details.transitionType === "reload"
-            ? false
-            : undefined;
-      observeMainFrame(details.tabId, details.url, causedByAction);
+      observeMainFrame(
+        details.tabId,
+        details.url,
+        undefined,
+        details.transitionType,
+        details.transitionQualifiers,
+      );
     };
     chrome.webNavigation.onCompleted.addListener(completedListener);
     chrome.webNavigation.onCommitted?.addListener(committedListener);
@@ -483,6 +613,26 @@ export function attachRecordNavigationListener(deps: RecordDeps = getDefaultDeps
   return () => chrome.tabs.onUpdated.removeListener(listener);
 }
 
+const MAX_FINISH_DRAIN_ROUNDS = 10;
+
+async function drainRecordingToStability(recording: ActiveRecording): Promise<boolean> {
+  for (let round = 0; round < MAX_FINISH_DRAIN_ROUNDS; round += 1) {
+    await Promise.all([...recording.navigationCallbacks]);
+    const actionTail = recording.actionQueue;
+    await actionTail;
+    await recording.observation?.flush();
+
+    if (recording.navigationCallbacks.size === 0 && recording.actionQueue === actionTail) {
+      // No event or promise continuation can interleave with this synchronous
+      // check-and-close, so work accepted before the cutoff is fully drained.
+      recording.acceptingNavigation = false;
+      return true;
+    }
+  }
+  console.warn("[bsk record] navigation/action queues did not stabilize at stop");
+  return false;
+}
+
 export function attachRecordQueryListener(deps: RecordDeps = getDefaultDeps()): () => void {
   const listener = (
     message: unknown,
@@ -523,23 +673,50 @@ async function finishRecordingByRequest(
     if (recording.requestId !== requestId || recording.settled) continue;
     const match = await findRecordingForTab(tabId, deps);
     if (match !== recording) continue;
-    await finishRecording(sessionId, deps);
+    await finishRecording(sessionId, deps, "user_finish");
     return;
   }
 }
 
-async function finishRecording(sessionId: string, deps: RecordDeps): Promise<TraceV2 | null> {
+async function finishRecording(
+  sessionId: string,
+  deps: RecordDeps,
+  stoppedBy: StopReason,
+): Promise<RecordedTrace | null> {
   const recording = recordings.get(sessionId);
-  if (!recording || recording.settled || recording.finishing) return null;
-  recording.finishing = true;
+  if (!recording || recording.settled) return null;
+  if (recording.finishAttempt) return recording.finishAttempt;
+  recording.stoppedBy = stoppedBy;
 
+  const attempt = finishRecordingAttempt(sessionId, recording, deps);
+  recording.finishAttempt = attempt;
+  try {
+    return await attempt;
+  } finally {
+    if (!recording.settled) {
+      recording.finishAttempt = null;
+    }
+  }
+}
+
+async function finishRecordingAttempt(
+  sessionId: string,
+  recording: ActiveRecording,
+  deps: RecordDeps,
+): Promise<RecordedTrace | null> {
   await clearRearmTimersForRecording(recording, deps);
   try {
+    // Disposing content capture may commit a final dirty fill. Flush content
+    // first so all resulting RECORD_STEP messages enter actionQueue before it
+    // and the observation queues are drained.
     await stopRecordingOnAllAgentTabs(recording, deps);
   } catch {
-    recording.finishing = false;
     return null;
   }
+  if (!(await drainRecordingToStability(recording))) {
+    return null;
+  }
+  await recording.observation?.settleTrailing(recording.tabId, recording.steps);
 
   recording.settled = true;
   recordings.delete(sessionId);
@@ -554,6 +731,15 @@ export async function handleRecordStart(
   params: RecordStartParams,
   deps: RecordDeps = getDefaultDeps(),
 ): Promise<RecordStartResult | RpcError> {
+  const traceVersionOrErr = negotiatedTraceVersion(params);
+  if (typeof traceVersionOrErr !== "number") return traceVersionOrErr;
+  if (traceVersionOrErr === 3 && !deps.cdp) {
+    return {
+      code: "protocol_error",
+      message: "trace v3 recording requires an active CDP connection",
+    };
+  }
+
   const ctxOrErr = lookupSession(manager, params, "record_start");
   if (isRpcError(ctxOrErr)) return ctxOrErr;
   const ctx = ctxOrErr;
@@ -570,14 +756,16 @@ export async function handleRecordStart(
   // on the destination page can RECORD_QUERY → rearm → show RecordOverlay
   // instead of flashing ControlOverlay ("Agent 正在控制").
   const requestId = makeRequestId(target.tabId);
-  let resolveFinish!: (trace: TraceV2) => void;
+  let resolveFinish!: (trace: RecordedTrace) => void;
   let rejectFinish!: (err: Error) => void;
-  const finishPromise = new Promise<TraceV2>((resolve, reject) => {
+  const finishPromise = new Promise<RecordedTrace>((resolve, reject) => {
     resolveFinish = resolve;
     rejectFinish = reject;
   });
   const navigateUrl = params.url ?? RECORD_DEFAULT_START_URL;
   const startedAtMs = Date.now();
+  const maxPageTokens = params.max_page_tokens;
+  const redactValues = params.redact_values ?? false;
   recordings.set(params.session_id, {
     requestId,
     tabId: target.tabId,
@@ -587,20 +775,36 @@ export async function handleRecordStart(
     steps: [],
     startedAt: new Date(startedAtMs).toISOString(),
     startedAtMs,
+    traceVersion: traceVersionOrErr,
     finishPromise,
     resolveFinish,
     rejectFinish,
     settled: false,
-    finishing: false,
+    finishAttempt: null,
     currentUrl: navigateUrl,
     pendingNavigation: false,
     pendingNavigationDeadline: undefined,
+    observation:
+      traceVersionOrErr === 3 && deps.cdp
+        ? new RecordingObservationRuntime({
+            cdp: deps.cdp,
+            tabsApi: deps.tabsApi,
+            maxTokens: maxPageTokens,
+            redactValues,
+          })
+        : null,
+    stoppedBy: "user_finish",
+    navigationCallbacks: new Set(),
+    acceptingNavigation: true,
+    actionQueue: Promise.resolve(),
+    lastStepSequenceByProducer: new Map(),
   });
   // Observe navigations for the whole recording lifetime; attach before
   // optional navigate so the destination load can rearm capture.
   ensureBrowserObservationListeners(deps);
 
   const abortPending = async (notifyContent: boolean) => {
+    recordings.get(params.session_id)?.observation?.cancel();
     recordings.delete(params.session_id);
     releaseBrowserObservationListenersIfIdle();
     if (notifyContent) {
@@ -727,6 +931,17 @@ export async function handleRecordStart(
     };
   }
 
+  if (active.observation) {
+    const activeRecording = recordings.get(params.session_id);
+    if (activeRecording) {
+      try {
+        await activeRecording.observation?.captureInitial(target.tabId);
+      } catch {
+        // Proceed without initial observation; steps may be dropped by reducer.
+      }
+    }
+  }
+
   {
     const cancelled = await abortIfCancelled(true);
     if (cancelled) return cancelled;
@@ -751,7 +966,7 @@ export async function handleRecordStop(
     };
   }
 
-  const trace = await finishRecording(params.session_id, deps);
+  const trace = await finishRecording(params.session_id, deps, "cli_stop");
   if (!trace) {
     return {
       code: "protocol_error",
@@ -781,9 +996,9 @@ export async function handleRecordAwait(
     return { code: "cancelled", message: "record_await aborted" };
   }
 
-  const outcome = await new Promise<{ trace: TraceV2 } | { error: RpcError }>((resolve) => {
+  const outcome = await new Promise<{ trace: RecordedTrace } | { error: RpcError }>((resolve) => {
     let settled = false;
-    const finish = (result: { trace: TraceV2 } | { error: RpcError }) => {
+    const finish = (result: { trace: RecordedTrace } | { error: RpcError }) => {
       if (settled) return;
       settled = true;
       if (timer) clearTimeout(timer);
@@ -825,6 +1040,7 @@ export function clearRecordingForSession(sessionId: string): void {
   }
   void clearRearmTimersForRecording(recording, getDefaultDeps());
   if (!recording.settled) {
+    recording.observation?.cancel();
     recording.settled = true;
     recording.rejectFinish(new Error("recording cleared"));
   }

apps/extension/src/transport/__tests__/handshake.test.ts

@@ -65,6 +65,11 @@ function deferredFakeTransport(): { transport: Transport; emit: (frame: Protocol
 }
 
 describe("performHandshake", () => {
+  it("advertises the protocol compatibility boundary", () => {
+    expect(PROTOCOL_VERSION).toBe("1.1");
+    expect(MIN_COMPATIBLE_PROTOCOL).toBe("1.0");
+  });
+
   it("sends system.handshake with identity and both compat fields", async () => {
     let sentFrame: ProtocolFrame | null = null;
     const transport = fakeTransport((req) => {
@@ -74,7 +79,7 @@ describe("performHandshake", () => {
         result: {
           server: "browser-skill-daemon",
           version: "0.1.0",
-          protocol_version: "1.0",
+          protocol_version: "1.1",
           min_compatible_peer: "0.0.0",
           min_compatible_protocol: "1.0",
         },
@@ -129,8 +134,8 @@ describe("performHandshake", () => {
     const response = {
       server: "browser-skill-daemon",
       version: "0.1.0",
-      protocol_version: "1.0",
-      min_compatible_protocol: "1.0",
+      protocol_version: "1.1",
+      min_compatible_protocol: "1.1",
     } satisfies HandshakeResult;
     const transport = fakeTransport((req) => ({
       id: (req as { id: string }).id,
@@ -145,7 +150,7 @@ describe("performHandshake", () => {
     });
 
     expect(outcome.result.min_compatible_peer).toBeUndefined();
-    expect(outcome.result.min_compatible_protocol).toBe("1.0");
+    expect(outcome.result.min_compatible_protocol).toBe("1.1");
   });
 
   it("rejects when the daemon responds with an error", async () => {
@@ -178,9 +183,9 @@ describe("performHandshake", () => {
       result: {
         server: "browser-skill-daemon",
         version: "0.1.0",
-        protocol_version: "1.0",
+        protocol_version: "1.1",
         min_compatible_peer: "0.0.0",
-        min_compatible_protocol: "1.0",
+        min_compatible_protocol: "1.1",
       },
     });
     emit({
@@ -188,14 +193,14 @@ describe("performHandshake", () => {
       result: {
         server: "browser-skill-daemon",
         version: "0.1.0",
-        protocol_version: "1.0",
+        protocol_version: "1.1",
         min_compatible_peer: "0.0.0",
-        min_compatible_protocol: "1.0",
+        min_compatible_protocol: "1.1",
       },
     });
 
     await expect(pending).resolves.toMatchObject({
-      result: { server: "browser-skill-daemon", protocol_version: "1.0" },
+      result: { server: "browser-skill-daemon", protocol_version: "1.1" },
     });
   });
 

apps/extension/src/transport/handshake.ts

@@ -7,7 +7,7 @@ import type {
   ResponseFrame,
 } from "./types";
 
-export const PROTOCOL_VERSION = "1.0";
+export const PROTOCOL_VERSION = "1.1";
 /**
  * Extension semver, injected at build time from `package.json` via
  * Vite's `define` (see `wxt.config.ts` and `vitest.config.ts`).

apps/extension/src/transport/types.ts

@@ -819,6 +819,10 @@ export interface RecordStartParams {
   tab_id?: number;
   url?: string;
   purpose?: string;
+  max_page_tokens?: number;
+  redact_values?: boolean;
+  /** Omitted means v2; `3` requests a state-linked v3 trace. */
+  trace_version?: number;
 }
 
 export interface RecordStartResult {