effing-use 0.1.1 → 0.2.0

package/src/browser/engine.ts

@@ -2,7 +2,35 @@ import type { Page, BrowserContext } from "playwright";
 import type { Config } from "../config.js";
 import { EngineError, resolveLocator } from "./refs.js";
 import { cap, saveText, stamp } from "./output.js";
-import { getConsoleLogs, getNetworkLogs, closeSession } from "./session.js";
+import {
+  getConsoleLogs,
+  getNetworkLogs,
+  closeSession,
+  getMustObserve,
+  setMustObserve,
+  clearMustObserve,
+} from "./session.js";
+import { collectEffect, evaluateExpect, parseExpect } from "./evidence.js";
+import {
+  getBaseline,
+  setBaseline,
+  computeDelta,
+  injectDirtyObserver,
+  checkDirty,
+  clearDirtyFlag,
+  ensureState as ensureDeltaState,
+} from "./delta.js";
+import { appendAction, appendNote, readState } from "./state.js";
+import {
+  isRecording,
+  captureStep,
+  saveRecording,
+  loadRecording,
+  startRecording,
+  stopRecording,
+} from "./record.js";
+import { compileMacro, isIrreversible } from "./macro.js";
+import { registerFingerprints, clearRegistry } from "./identity.js";
 
 export type ActAction =
   | "open"
@@ -31,26 +59,32 @@ export type ActAction =
   | "tab_new"
   | "tab_select"
   | "tab_close"
-  | "resize";
+  | "resize"
+  | "note"
+  | "record_start"
+  | "record_stop"
+  | "compile"
+  | "replay";
 
 export interface ActOpts {
   context?: BrowserContext;
   sessionId?: string;
+  expect?: string;
+  approve?: boolean;
 }
-
 export interface ObserveOpts {
   context?: BrowserContext;
   sessionId?: string;
+  mode?: "full" | "delta";
+  scope?: string;
 }
 
 function timeoutOf(config: Config): number {
   return config.timeoutMs;
 }
-
 async function liteState(page: Page): Promise<{ url: string; title: string }> {
   return { url: page.url(), title: await page.title().catch(() => "") };
 }
-
 function toEngineError(e: unknown, fallbackHint: string): EngineError {
   if (e instanceof EngineError) return e;
   const msg = e instanceof Error ? e.message : String(e);
@@ -63,9 +97,34 @@ function toEngineError(e: unknown, fallbackHint: string): EngineError {
     fallbackHint,
   );
 }
+const MUTATING = new Set<string>([
+  "click",
+  "dblclick",
+  "fill",
+  "type",
+  "press",
+  "select",
+  "check",
+  "uncheck",
+  "hover",
+  "drag",
+  "upload",
+  "scroll",
+  "back",
+  "forward",
+  "reload",
+  "open",
+  "goto",
+  "resize",
+  "tab_new",
+  "tab_select",
+  "tab_close",
+]);
+function isMutating(a: string): boolean {
+  return MUTATING.has(a);
+}
 
 // ---------------------------------------------------------------- act
-
 export async function doAct(
   page: Page,
   config: Config,
@@ -75,6 +134,158 @@ export async function doAct(
   opts?: ActOpts,
 ): Promise<Record<string, unknown>> {
   const timeout = timeoutOf(config);
+  const sid = opts?.sessionId ?? "default";
+
+  // Non-page meta actions (no mustObserve guard, no evidence)
+  if (action === "note") {
+    if (!value && !target)
+      throw new EngineError(
+        "E_BAD_INPUT",
+        "Missing note text.",
+        "Pass value with the note.",
+      );
+    const note = value ?? target ?? "";
+    await appendNote(config, sid, note);
+    return { noted: true, note: note.slice(0, 300) };
+  }
+  if (action === "record_start") {
+    const name = (value ?? target ?? "recording").trim() || "recording";
+    startRecording(sid, name);
+    return { recording: true, name };
+  }
+  if (action === "record_stop") {
+    const rec = stopRecording(sid);
+    if (!rec)
+      throw new EngineError(
+        "E_BAD_INPUT",
+        "No active recording.",
+        "Call record_start first.",
+      );
+    const path = await saveRecording(config, rec.name, rec.steps as any);
+    return { recording: false, name: rec.name, steps: rec.steps.length, path };
+  }
+  if (action === "compile") {
+    const name = (value ?? target ?? "").trim();
+    if (!name)
+      throw new EngineError(
+        "E_BAD_INPUT",
+        "Missing macro name.",
+        "Pass value with the recording name.",
+      );
+    const rec = await loadRecording(config, name).catch(() => {
+      throw new EngineError(
+        "E_NOT_FOUND",
+        `No recording "${name}".`,
+        "Call record_start/stop first.",
+      );
+    });
+    const { tsPath, mdPath, warnings } = await compileMacro(
+      config,
+      name,
+      rec.steps as any,
+    );
+    return {
+      compiled: true,
+      name,
+      steps: rec.steps.length,
+      tsPath,
+      mdPath,
+      warnings,
+    };
+  }
+  if (action === "replay") {
+    const name = (value ?? target ?? "").trim();
+    if (!name)
+      throw new EngineError(
+        "E_BAD_INPUT",
+        "Missing macro name.",
+        "Pass value with the macro name.",
+      );
+    const rec = await loadRecording(config, name).catch(() => {
+      throw new EngineError(
+        "E_NOT_FOUND",
+        `No recording "${name}".`,
+        "Compile first or check name.",
+      );
+    });
+    const approve = opts?.approve === true;
+    // Check approval gate
+    const needsApproval = (rec.steps as any[]).filter((s: any) =>
+      isIrreversible(s),
+    );
+    if (needsApproval.length > 0 && !approve) {
+      const first = needsApproval[0];
+      return {
+        ok: false,
+        code: "E_APPROVAL_REQUIRED",
+        message: `Step ${first.seq} requires approval (${first.op}).`,
+        hint: "Re-run with approve:true.",
+        step: first.seq,
+        description: `${first.op} ${first.target ?? ""}`,
+      } as any;
+    }
+    // Deterministic replay
+    const results: any[] = [];
+    for (const s of rec.steps as any[]) {
+      try {
+        const r = await doAct(
+          page,
+          config,
+          s.op as ActAction,
+          s.target,
+          s.value === "«redacted»" ? undefined : s.value,
+          { ...opts, expect: s.expect },
+        );
+        results.push({ ok: true, seq: s.seq, ...r });
+      } catch (e) {
+        const err = toEngineError(e, "Replay failed.");
+        results.push({
+          ok: false,
+          seq: s.seq,
+          code: err.code,
+          message: err.message,
+        });
+        return { replayed: false, name, failSeq: s.seq, results } as any;
+      }
+    }
+    return { replayed: true, name, steps: results.length, results } as any;
+  }
+
+  // Failure contract guard
+  if (isMutating(action) && getMustObserve(sid)) {
+    throw new EngineError(
+      "E_MUST_OBSERVE",
+      "Must observe before next mutation.",
+      "Call browser_observe kind=snapshot first.",
+      { mustObserve: true } as any,
+    );
+  }
+
+  // Validate expect syntax early
+  if (opts?.expect) {
+    const parsed = parseExpect(opts.expect);
+    if (!parsed)
+      throw new EngineError(
+        "E_BAD_EXPECT",
+        `Bad expect "${opts.expect}".`,
+        "Use url~<regex> | text~<regex> | visible=<css> | gone=<css>",
+      );
+  }
+
+  const urlBefore = page.url();
+  let domBefore: string | null = null;
+  try {
+    domBefore = await page.evaluate(
+      () => document.body?.innerText?.slice(0, 200) ?? "",
+    );
+  } catch {
+    domBefore = null;
+  }
+  const consoleBefore = getConsoleLogs(sid).length;
+  const networkBefore = getNetworkLogs(sid).length;
+
+  let result: Record<string, unknown>;
+  let isTimeout = false;
   try {
     switch (action) {
       case "open":
@@ -87,7 +298,8 @@ export async function doAct(
             "Pass the URL in value (or target).",
           );
         await page.goto(url, { waitUntil: "domcontentloaded", timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "click": {
         if (!target)
@@ -96,11 +308,16 @@ export async function doAct(
             "Missing target.",
             "Pass an e-ref, role= selector, or CSS.",
           );
-        const loc = await resolveLocator(page, target);
+        const loc = await resolveLocator(page, target, sid);
         const button =
           (value as "left" | "middle" | "right" | undefined) ?? "left";
         await loc.click({ button, timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        if ((page as any).__rebound) {
+          (result as any).rebound = true;
+          delete (page as any).__rebound;
+        }
+        break;
       }
       case "dblclick": {
         if (!target)
@@ -109,9 +326,10 @@ export async function doAct(
             "Missing target.",
             "Pass an e-ref, role= selector, or CSS.",
           );
-        const loc = await resolveLocator(page, target);
+        const loc = await resolveLocator(page, target, sid);
         await loc.dblclick({ timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "fill": {
         if (!target)
@@ -120,13 +338,15 @@ export async function doAct(
             "Missing target.",
             "Pass an e-ref, role= selector, or CSS.",
           );
-        const loc = await resolveLocator(page, target);
+        const loc = await resolveLocator(page, target, sid);
         await loc.fill(value ?? "", { timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "type": {
         await page.keyboard.type(value ?? "", { delay: 0 });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "press": {
         if (!value)
@@ -136,7 +356,8 @@ export async function doAct(
             "Pass a key like Enter, Tab, Escape in value.",
           );
         await page.keyboard.press(value);
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "select": {
         if (!target)
@@ -145,9 +366,10 @@ export async function doAct(
             "Missing target.",
             "Pass a select element ref in target.",
           );
-        const loc = await resolveLocator(page, target);
+        const loc = await resolveLocator(page, target, sid);
         await loc.selectOption(value ?? "", { timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "check": {
         if (!target)
@@ -156,9 +378,10 @@ export async function doAct(
             "Missing target.",
             "Pass a checkbox ref in target.",
           );
-        const loc = await resolveLocator(page, target);
+        const loc = await resolveLocator(page, target, sid);
         await loc.check({ timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "uncheck": {
         if (!target)
@@ -167,9 +390,10 @@ export async function doAct(
             "Missing target.",
             "Pass a checkbox ref in target.",
           );
-        const loc = await resolveLocator(page, target);
+        const loc = await resolveLocator(page, target, sid);
         await loc.uncheck({ timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "hover": {
         if (!target)
@@ -178,9 +402,10 @@ export async function doAct(
             "Missing target.",
             "Pass an e-ref, role= selector, or CSS.",
           );
-        const loc = await resolveLocator(page, target);
+        const loc = await resolveLocator(page, target, sid);
         await loc.hover({ timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "drag": {
         if (!target || !value)
@@ -189,10 +414,11 @@ export async function doAct(
             "Missing drag endpoints.",
             "Pass start ref in target and end ref in value.",
           );
-        const start = await resolveLocator(page, target);
-        const end = await resolveLocator(page, value);
+        const start = await resolveLocator(page, target, sid);
+        const end = await resolveLocator(page, value, sid);
         await start.dragTo(end, { timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "upload": {
         const files = (value ?? "")
@@ -206,7 +432,8 @@ export async function doAct(
             "Pass comma-separated file paths in value.",
           );
         await page.setInputFiles("input[type=file]", files, { timeout });
-        return { ...(await liteState(page)), files };
+        result = { ...(await liteState(page)), files };
+        break;
       }
       case "scroll": {
         const dir = (target ?? "").toLowerCase();
@@ -219,52 +446,60 @@ export async function doAct(
             window.scrollTo(0, document.body.scrollHeight),
           );
         else if (target) {
-          const loc = await resolveLocator(page, target);
+          const loc = await resolveLocator(page, target, sid);
           await loc.scrollIntoViewIfNeeded({ timeout });
-        } else {
-          await page.mouse.wheel(0, 500);
-        }
-        return { ...(await liteState(page)) };
+        } else await page.mouse.wheel(0, 500);
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "back":
         await page
           .goBack({ waitUntil: "domcontentloaded", timeout })
           .catch(() => null);
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       case "forward":
         await page
           .goForward({ waitUntil: "domcontentloaded", timeout })
           .catch(() => null);
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       case "reload":
         await page.reload({ waitUntil: "domcontentloaded", timeout });
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       case "wait": {
         const t = target ?? "";
         const msMatch = /^ms:(\d+)$/.exec(t);
         if (msMatch) {
           await page.waitForTimeout(Number(msMatch[1]));
-          return { ...(await liteState(page)), waited: t };
+          result = { ...(await liteState(page)), waited: t };
+          break;
         }
         const textMatch = /^text:(.+)$/.exec(t);
         if (textMatch) {
           await page.getByText(textMatch[1]).first().waitFor({ timeout });
-          return { ...(await liteState(page)), waited: t };
+          result = { ...(await liteState(page)), waited: t };
+          break;
         }
         if (t) {
-          const loc = await resolveLocator(page, t);
+          const loc = await resolveLocator(page, t, sid);
           await loc.waitFor({ timeout });
-          return { ...(await liteState(page)), waited: t };
+          result = { ...(await liteState(page)), waited: t };
+          break;
         }
         await page.waitForTimeout(500);
-        return { ...(await liteState(page)) };
+        result = { ...(await liteState(page)) };
+        break;
       }
       case "dialog_accept":
         page.once("dialog", (d) => void d.accept(value));
-        return { armed: true };
+        result = { armed: true };
+        break;
       case "dialog_dismiss":
         page.once("dialog", (d) => void d.dismiss());
-        return { armed: true };
+        result = { armed: true };
+        break;
       case "resize": {
         const m = /^(\d+)x(\d+)$/.exec(value ?? "");
         if (!m)
@@ -277,7 +512,8 @@ export async function doAct(
           width: Number(m[1]),
           height: Number(m[2]),
         });
-        return { ...(await liteState(page)), viewport: value };
+        result = { ...(await liteState(page)), viewport: value };
+        break;
       }
       case "tab_new": {
         if (!opts?.context)
@@ -292,7 +528,11 @@ export async function doAct(
             waitUntil: "domcontentloaded",
             timeout,
           });
-        return { url: p.url(), tabs: opts.context.pages().map((x) => x.url()) };
+        result = {
+          url: p.url(),
+          tabs: opts.context.pages().map((x) => x.url()),
+        };
+        break;
       }
       case "tab_select": {
         if (!opts?.context)
@@ -310,7 +550,8 @@ export async function doAct(
             "Call browser_observe kind=tabs for the tab list.",
           );
         await pages[i].bringToFront();
-        return { url: pages[i].url() };
+        result = { url: pages[i].url() };
+        break;
       }
       case "tab_close": {
         if (!opts?.context)
@@ -329,11 +570,14 @@ export async function doAct(
             "Call browser_observe kind=tabs for the tab list.",
           );
         await pages[i].close();
-        return { closed: i, tabs: opts.context.pages().map((x) => x.url()) };
+        result = { closed: i, tabs: opts.context.pages().map((x) => x.url()) };
+        break;
       }
       case "close":
-        await closeSession(opts?.sessionId ?? "default");
-        return { closed: true };
+        await closeSession(sid);
+        clearRegistry(sid);
+        result = { closed: true };
+        break;
       case "goal":
         return doGoal(page, config, value ?? target ?? "", opts);
       case "batch":
@@ -350,11 +594,85 @@ export async function doAct(
         );
     }
   } catch (e) {
-    throw toEngineError(
+    const err = toEngineError(
       e,
       "Retry with a fresh snapshot ref, or re-observe state.",
     );
+    if (err.code === "E_TIMEOUT") {
+      isTimeout = true;
+      setMustObserve(sid, true);
+    }
+    throw err;
   }
+
+  // Post-action: evidence, expect, state, dirty, recording
+  let effect: any = undefined;
+  if (isMutating(action)) {
+    effect = await collectEffect(
+      page,
+      sid,
+      urlBefore,
+      domBefore,
+      consoleBefore,
+      networkBefore,
+      config.effectMaxChars,
+    );
+    // Failure contract: timeout with no DOM/URL change => mustObserve
+    if (isTimeout && !effect.urlChanged && effect.domChanged.length === 0)
+      setMustObserve(sid, true);
+    // Expect evaluation
+    if (opts?.expect) {
+      const ev = await evaluateExpect(page, opts.expect);
+      if (!ev.ok) {
+        effect.mustObserve = false;
+        throw new EngineError(
+          "E_EXPECT",
+          ev.message ?? "Expect failed.",
+          "Check effect and re-plan.",
+          { effect, expect: opts.expect } as any,
+        );
+      }
+      (result as any).expect = "pass";
+    }
+    if (effect) {
+      (result as any).effect = effect;
+      if (effect.mustObserve) (result as any).mustObserve = true;
+    }
+    // Mark dirty for delta
+    ensureDeltaState(sid).dirty = true;
+    try {
+      await page.evaluate(() => {
+        (window as any).__effDirty = true;
+      });
+    } catch {}
+  }
+
+  // Append to state ring
+  const actionLine = `${action} ${target ?? ""} ${value ?? ""}`
+    .trim()
+    .slice(0, 120);
+  await appendAction(
+    config,
+    sid,
+    `${actionLine} -> ${effect ? JSON.stringify(effect).slice(0, 80) : "ok"}`,
+  );
+
+  // Recording capture
+  if (isRecording(sid) && isMutating(action)) {
+    captureStep(
+      sid,
+      {
+        op: action,
+        target,
+        value,
+        expect: opts?.expect,
+        resolvedSelector: target,
+      },
+      config,
+    );
+  }
+
+  return result;
 }
 
 // ---------------------------------------------------------------- goal
@@ -473,15 +791,109 @@ export async function doObserve(
     case "title":
       return { title: await page.title().catch(() => ""), url: page.url() };
     case "snapshot": {
-      const yaml = await buildSnapshot(page);
+      const mode = (opts?.mode ?? (config.deltaDefault ? "delta" : "full")) as
+        | "full"
+        | "delta";
+      const scope = opts?.scope;
+      // Scoped snapshot: only within selector
+      let yaml: string;
+      if (scope) {
+        yaml = await buildSnapshot(page, scope);
+        const path = await saveText(config, stamp("snapshot", "yaml"), yaml);
+        const { text, truncated } = cap(yaml, config.outputMaxChars);
+        clearMustObserve(sessionId);
+        return {
+          path,
+          summary: text,
+          truncated,
+          url: page.url(),
+          title: await page.title().catch(() => ""),
+          scope,
+          mode: "scoped",
+        };
+      }
+      // Delta path
+      if (mode === "delta") {
+        const baseline = getBaseline(sessionId);
+        // If no baseline, do full
+        if (!baseline) {
+          yaml = await buildSnapshot(page);
+          setBaseline(sessionId, yaml, page.url());
+          await injectDirtyObserver(page, sessionId);
+          // register fingerprints
+          const fps = await collectFingerprints(page);
+          registerFingerprints(sessionId, fps);
+          const path = await saveText(config, stamp("snapshot", "yaml"), yaml);
+          const { text, truncated } = cap(yaml, config.outputMaxChars);
+          clearMustObserve(sessionId);
+          return {
+            path,
+            summary: text,
+            truncated,
+            url: page.url(),
+            title: await page.title().catch(() => ""),
+            mode: "full",
+          };
+        }
+        // Check dirty flag
+        const dirty = await checkDirty(page).catch(() => true);
+        if (!dirty) {
+          clearMustObserve(sessionId);
+          return {
+            unchanged: true,
+            url: page.url(),
+            title: await page.title().catch(() => ""),
+            hint: "last snapshot still valid",
+            mode: "delta",
+          };
+        }
+        yaml = await buildSnapshot(page);
+        const { delta, unchanged } = computeDelta(baseline, yaml);
+        if (unchanged) {
+          await clearDirtyFlag(page);
+          clearMustObserve(sessionId);
+          return {
+            unchanged: true,
+            url: page.url(),
+            title: await page.title().catch(() => ""),
+            hint: "no changes",
+            mode: "delta",
+          };
+        }
+        setBaseline(sessionId, yaml, page.url());
+        await clearDirtyFlag(page);
+        await injectDirtyObserver(page, sessionId);
+        const fps = await collectFingerprints(page);
+        registerFingerprints(sessionId, fps);
+        const path = await saveText(config, stamp("snapshot", "yaml"), yaml);
+        const { text: dtext, truncated } = cap(delta, config.outputMaxChars);
+        clearMustObserve(sessionId);
+        return {
+          path,
+          delta: dtext,
+          truncated,
+          url: page.url(),
+          title: await page.title().catch(() => ""),
+          mode: "delta",
+          fullPath: path,
+        };
+      }
+      // Full mode
+      yaml = await buildSnapshot(page);
+      setBaseline(sessionId, yaml, page.url());
+      await injectDirtyObserver(page, sessionId);
+      const fps2 = await collectFingerprints(page);
+      registerFingerprints(sessionId, fps2);
       const path = await saveText(config, stamp("snapshot", "yaml"), yaml);
       const { text, truncated } = cap(yaml, config.outputMaxChars);
+      clearMustObserve(sessionId);
       return {
         path,
         summary: text,
         truncated,
         url: page.url(),
         title: await page.title().catch(() => ""),
+        mode: "full",
       };
     }
     case "screenshot": {
@@ -524,17 +936,28 @@ export async function doObserve(
   }
 }
 
-async function buildSnapshot(page: Page): Promise<string> {
+async function buildSnapshot(page: Page, scope?: string): Promise<string> {
   const header = [
     "# Snapshot — refs are nth-match: eN = Nth match of (button, a, input, select, textarea, [role=button], [tabindex]) in DOM order.",
     `# url: ${page.url()}`,
   ].join("\n");
-  const items = await page.evaluate(() => {
+  const items = await page.evaluate((scopeSel) => {
+    const root = scopeSel ? document.querySelector(scopeSel) : document;
+    if (!root) return [] as string[];
     const els = [
-      ...document.querySelectorAll(
+      ...(root as Element).querySelectorAll(
         "button, a, input, select, textarea, [role=button], [tabindex]",
       ),
     ];
+    // also include root itself if it matches
+    if (
+      scopeSel &&
+      (root as Element).matches?.(
+        "button, a, input, select, textarea, [role=button], [tabindex]",
+      )
+    ) {
+      els.unshift(root as Element);
+    }
     return els.slice(0, 200).map((el) => {
       const tag = el.tagName.toLowerCase();
       const text = (el.textContent ?? "")
@@ -553,11 +976,62 @@ async function buildSnapshot(page: Page): Promise<string> {
         .join(" ");
       return `${tag} "${text}"${extra ? " " + extra : ""}`;
     });
-  });
+  }, scope ?? null);
   const lines = items.map((line, i) => `[e${i}] ${line}`);
   return `${header}\n${lines.join("\n") || "(no interactive elements)"}`;
 }
 
+async function collectFingerprints(
+  page: Page,
+): Promise<Array<{ ref: string; fp: import("./identity.js").Fingerprint }>> {
+  const raw = await page
+    .evaluate(() => {
+      const els = [
+        ...document.querySelectorAll(
+          "button, a, input, select, textarea, [role=button], [tabindex]",
+        ),
+      ].slice(0, 200);
+      return els.map((el) => {
+        const text = (el.textContent ?? "")
+          .trim()
+          .replace(/\s+/g, " ")
+          .slice(0, 80);
+        const aria = el.getAttribute("aria-label") ?? "";
+        const role = el.getAttribute("role") ?? el.tagName.toLowerCase();
+        let cur: Element | null = el;
+        const parts: string[] = [];
+        while (cur && parts.length < 6) {
+          parts.push(cur.tagName.toLowerCase());
+          cur = cur.parentElement;
+        }
+        const rect = el.getBoundingClientRect();
+        return {
+          role,
+          accessibleName: aria,
+          text,
+          pathHash: parts.join(">"),
+          box: { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
+        };
+      });
+    })
+    .catch(() => [] as any[]);
+  return raw.map((r: any, i: number) => ({
+    ref: `e${i}`,
+    fp: {
+      role: r.role || "generic",
+      accessibleName: (r.accessibleName || "").trim().slice(0, 80),
+      textHash: (r.text || "").trim().replace(/\s+/g, " ").slice(0, 80),
+      box: {
+        x: Math.round(r.box.x),
+        y: Math.round(r.box.y),
+        w: Math.round(r.box.w),
+        h: Math.round(r.box.h),
+      },
+      pathHash: r.pathHash || "",
+    },
+  }));
+}
+
 // ---------------------------------------------------------------- extract
 
 export async function doExtract(
@@ -657,11 +1131,23 @@ export async function doExtract(
       await ctx.tracing.stop({ path: saved });
       return { path: saved };
     }
+    case "state": {
+      const sid = opts?.sessionId ?? "default";
+      const st = await readState(config, sid);
+      const dirty = await checkDirty(page).catch(() => false);
+      return {
+        notes: st.notes,
+        lastActions: st.lastActions,
+        path: st.path,
+        url: page.url(),
+        dirty,
+      };
+    }
     default:
       throw new EngineError(
         "E_BAD_INPUT",
         `Unknown extract kind "${kind}".`,
-        "Valid: text, html, table, query, pdf, trace_start, trace_stop.",
+        "Valid: text, html, table, query, pdf, trace_start, trace_stop, state.",
       );
   }
 }