effing-use 0.1.1 → 0.2.1

package/src/browser/engine.ts

@@ -1,8 +1,45 @@
 import type { Page, BrowserContext } from "playwright";
 import type { Config } from "../config.js";
-import { EngineError, resolveLocator } from "./refs.js";
+import { EngineError, resolveLocator, stableSelectorFor } 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,
+  getBaselineUrl,
+  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,
+  getReplayCursor,
+  setReplayCursor,
+  clearReplayCursor,
+} from "./record.js";
+import { compileMacro, isIrreversible } from "./macro.js";
+import {
+  registerFingerprints,
+  clearRegistry,
+  getFingerprint,
+  extractFingerprints as collectFingerprints,
+} from "./identity.js";
 
 export type ActAction =
   | "open"
@@ -31,26 +68,45 @@ 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(() => "") };
 }
 
+/**
+ * SPA navigations commit after the action returns (client router awaits data),
+ * so evidence collected immediately can report urlChanged:false for a click
+ * that DOES navigate (observed: kikitai "Try paste & read" → /read).
+ * Brief settle: one tick, then a second if the URL moved.
+ */
+async function settleSpa(page: Page, action: string): Promise<void> {
+  if (!["click", "dblclick", "press", "goal"].includes(action)) return;
+  const u0 = page.url();
+  await page.waitForTimeout(60);
+  if (page.url() !== u0) await page.waitForTimeout(60);
+}
 function toEngineError(e: unknown, fallbackHint: string): EngineError {
   if (e instanceof EngineError) return e;
   const msg = e instanceof Error ? e.message : String(e);
@@ -63,9 +119,35 @@ 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",
+  "goal",
+  "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 +157,176 @@ export async function doAct(
   opts?: ActOpts,
 ): Promise<Record<string, unknown>> {
   const timeout = timeoutOf(config);
+  const sid = opts?.sessionId ?? "default";
+
+  // Per-action stash must never leak from a previous (possibly failed) act
+  const pageBag = page as unknown as Record<string, unknown>;
+  delete pageBag.__rebound;
+
+  // 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;
+    // Plan §6.3: run benign steps, pause AT each approval-gated step, and keep
+    // a cursor so approve:true resumes here instead of re-running the prefix.
+    const stepsArr = rec.steps as any[];
+    const start = getReplayCursor(sid, name) ?? 0;
+    const results: any[] = [];
+    for (let i = start; i < stepsArr.length; i++) {
+      const s = stepsArr[i];
+      if (isIrreversible(s) && !approve) {
+        setReplayCursor(sid, name, i);
+        const ran = i - start;
+        return {
+          ok: false,
+          code: "E_APPROVAL_REQUIRED",
+          message:
+            `Step ${i + 1} requires approval (${s.op}).` +
+            (ran > 0 ? ` Ran ${ran} prior step(s).` : ""),
+          hint: "Re-run with approve:true to resume from this step.",
+          step: i + 1,
+          completed: results.length,
+          description: `${s.op} ${s.target ?? ""}`,
+        } 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) {
+        clearReplayCursor(sid, name);
+        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;
+      }
+    }
+    clearReplayCursor(sid, name);
+    return {
+      replayed: true,
+      name,
+      steps: results.length,
+      resumedFrom: start,
+      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 {
+    // Full innerText (50k cap) — evidence diffs need the whole page, not just
+    // the first 200 chars (v0.2: below-fold changes looked like no-ops).
+    domBefore = await page.evaluate(
+      () => document.body?.innerText?.slice(0, 50000) ?? "",
+    );
+  } 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 +339,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 +349,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 +367,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 +379,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 +397,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 +407,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 +419,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 +431,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 +443,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 +455,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 +473,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 +487,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 +553,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 +569,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 +591,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,13 +611,21 @@ 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);
+        // Route through the normal post-action pipeline (guard, evidence,
+        // dirty flag, recording) — v0.2 returned here and skipped all of it.
+        result = {
+          ...(await doGoal(page, config, value ?? target ?? "", opts)),
+        };
+        break;
       case "batch":
         throw new EngineError(
           "E_BAD_INPUT",
@@ -350,11 +640,94 @@ 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)) {
+    await settleSpa(page, 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 — resolve a portable selector (id → name → ARIA →
+  // data-* → placeholder → text) so compiled macros don't depend on e-refs.
+  if (isRecording(sid) && isMutating(action)) {
+    let resolved = target;
+    if (target) {
+      resolved =
+        (await stableSelectorFor(page, target, sid).catch(() => null)) ??
+        target;
+    }
+    captureStep(
+      sid,
+      {
+        op: action,
+        target,
+        value,
+        expect: opts?.expect,
+        resolvedSelector: resolved,
+        targetFingerprint: target ? getFingerprint(sid, target) : undefined,
+      },
+      config,
+    );
   }
+
+  return result;
 }
 
 // ---------------------------------------------------------------- goal
@@ -473,15 +846,124 @@ 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;
+      // Navigation forces a fresh full baseline (plan §5.1) and needs a settle
+      // beat: SPA routes hydrate after the URL changes — snapshots taken too
+      // early miss the header/nav entirely (observed on kikitai /read).
+      const prevUrl = getBaselineUrl(sessionId);
+      const urlChanged = prevUrl !== null && prevUrl !== page.url();
+      const settleHydration = async () => {
+        if (!urlChanged) return;
+        await page
+          .waitForLoadState("networkidle", { timeout: 1500 })
+          .catch(() => {});
+        await page.waitForTimeout(80);
+      };
+      // Scoped snapshot: only within selector
+      let yaml: string;
+      if (scope) {
+        await settleHydration();
+        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);
+        // No baseline, or the page navigated since the baseline → forced full
+        if (!baseline || urlChanged) {
+          await settleHydration();
+          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
+      await settleHydration();
+      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,23 +1006,52 @@ 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 ?? "")
+      let text = (el.textContent ?? "")
         .trim()
         .replace(/\s+/g, " ")
         .slice(0, 80);
+      // Form controls carry no text — surface placeholder/label so refs stop
+      // showing as `input ""`, and mark checked state (real state changes that
+      // delta should surface).
+      const input = el as HTMLInputElement;
+      if (!text) {
+        text = (
+          input.placeholder ||
+          (input.labels && input.labels[0]?.textContent) ||
+          ""
+        )
+          .trim()
+          .replace(/\s+/g, " ")
+          .slice(0, 80);
+      }
+      const checked =
+        (tag === "input" || tag === "select") && input.checked
+          ? " [checked]"
+          : "";
       const aria = el.getAttribute("aria-label") ?? "";
       const name = el.getAttribute("name") ?? "";
       const id = el.getAttribute("id") ?? "";
@@ -551,9 +1062,9 @@ async function buildSnapshot(page: Page): Promise<string> {
       ]
         .filter(Boolean)
         .join(" ");
-      return `${tag} "${text}"${extra ? " " + extra : ""}`;
+      return `${tag} "${text}"${extra ? " " + extra : ""}${checked}`;
     });
-  });
+  }, scope ?? null);
   const lines = items.map((line, i) => `[e${i}] ${line}`);
   return `${header}\n${lines.join("\n") || "(no interactive elements)"}`;
 }
@@ -657,11 +1168,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.",
       );
   }
 }