harnery 0.29.0 → 0.31.0

package/src/core/workflow/workspaces/lifecycle.ts

@@ -135,7 +135,7 @@ export interface WorkspaceLifecycleProjectionInput {
   binding?: WorkspaceBinding;
   provider_events?: readonly WorkspaceProviderEvent[];
   manifest?: WorkflowRunManifest;
-  workflow_journal?: readonly {
+  workflow_transcript?: readonly {
     event: string;
     ok?: boolean;
     status?: "blocked" | "lost" | WorkspaceCancellationResult["status"];
@@ -207,22 +207,22 @@ export function deriveWorkspaceLifecycle(
     transition(next);
   }
 
-  const journal = input.workflow_journal ?? [];
-  for (const event of journal) {
+  const transcript = input.workflow_transcript ?? [];
+  for (const event of transcript) {
     if (input.binding && (event.event === "run.start" || event.event === "run.resume")) {
       transition("running");
     }
     if (event.event === "run.parked") transition("parked");
   }
-  const failedReattachment = [...journal]
+  const failedReattachment = [...transcript]
     .reverse()
     .find((event) => event.event === "workspace.reattach.failed");
   if (failedReattachment) transition(failedReattachment.status === "blocked" ? "blocked" : "lost");
   let workflowOutcome = proofOutcome(input.proof, input.binding);
-  const terminalJournal = [...journal].reverse().find((event) => event.event === "run.end");
+  const terminalTranscript = [...transcript].reverse().find((event) => event.event === "run.end");
   if (input.proof && !failedReattachment) transition(workflowOutcome!);
-  if (terminalJournal && !input.proof && !failedReattachment) {
-    workflowOutcome = terminalJournal.ok === false ? "failed_retained" : null;
+  if (terminalTranscript && !input.proof && !failedReattachment) {
+    workflowOutcome = terminalTranscript.ok === false ? "failed_retained" : null;
     transition("blocked");
   }
   if (projectedIntegrationState !== "none") transition("integration_requested");
@@ -269,7 +269,7 @@ export function deriveWorkspaceLifecycle(
     ((input.cancellation_receipt?.status === "cancelled" &&
       input.cancellation_receipt.work_event_seq === latestGovernance.seq &&
       input.cancellation_receipt.work_event_sha256 === workEventSha256) ||
-      journal.some(
+      transcript.some(
         (event) =>
           event.event === "workspace.cancel" &&
           event.status === "cancelled" &&
@@ -459,8 +459,8 @@ function validateIntegrationAuthorization(
     !digest(authorization.policy_sha256) ||
     authorization.decision?.verdict !== "allow" ||
     authorization.decision_sha256 !== stableDigest(authorization.decision) ||
-    authorization.journal_anchor?.event !== "integration.plan" ||
-    authorization.journal_anchor.plan_sha256 !== planSha256 ||
+    authorization.transcript_anchor?.event !== "integration.plan" ||
+    authorization.transcript_anchor.plan_sha256 !== planSha256 ||
     !validTimestamp(authorization.authorized_at) ||
     (authorization.approval_id !== undefined &&
       (typeof authorization.approval_actor !== "string" || !digest(authorization.approval_sha256)))

package/src/core/workflow/workspaces/local-git.ts

@@ -1,6 +1,13 @@
 import { randomBytes } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { WorkspaceAttestationError } from "./attestation-error.ts";
 import {
   git,
@@ -68,6 +75,8 @@ import { isWorkspaceAttestation } from "./validate.ts";
 
 const PROVIDER_ID = "local-git-worktree";
 const PROVIDER_VERSION = "1";
+const WORKSPACE_PARENT_SEGMENT = ".harnery-workspaces";
+const LEGACY_WORKSPACE_PARENT_SEGMENT = "harnery-workspaces";
 const LOCK_STALE_MS = 5 * 60 * 1_000;
 const OBJECT_FORMAT = /^[a-f0-9]{40,64}$/;
 const REF_FORMAT = /^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]{0,180}$/;
@@ -221,7 +230,11 @@ async function allocate(
   );
   const authorityOutside = describeAuthorityOutsideRoot(repo, root.realpath);
   if (authorityOutside) throw new Error(authorityOutside);
-  const workspaceRoot = candidateUnderRoot(root, ["harnery-workspaces", bindingId]);
+  // Claims are immutable, so a retry must reproduce the path the first attempt
+  // froze. Only a genuinely new allocation picks the current parent.
+  const priorClaim = readWorkspaceClaim(coordRoot, PROVIDER_ID, bindingId);
+  const parentSegment = priorClaim ? claimedParentSegment(priorClaim) : WORKSPACE_PARENT_SEGMENT;
+  const workspaceRoot = candidateUnderRoot(root, [parentSegment, bindingId]);
   const activeRoot = resolve(workspaceRoot, repo.requestedRelativePath);
   if (!containsPath(workspaceRoot, activeRoot)) {
     throw new Error("requested working directory escapes the isolated workspace");
@@ -287,6 +300,33 @@ async function allocate(
   }
 }
 
+/**
+ * A claim freezes its workspace path at allocation time, so reconciliation must
+ * follow the parent recorded there rather than the parent this version would
+ * choose. Only the names this provider has ever allocated under are accepted, so
+ * a tampered claim cannot redirect creation into an unrelated directory.
+ */
+function claimedParentSegment(claim: WorkspaceClaim): string {
+  const segment = basename(dirname(claim.workspace_root));
+  if (segment !== WORKSPACE_PARENT_SEGMENT && segment !== LEGACY_WORKSPACE_PARENT_SEGMENT) {
+    throw new Error("claimed workspace path is not under a provider-owned workspace parent");
+  }
+  return segment;
+}
+
+/**
+ * The parent holds real checkouts that would otherwise surface as untracked
+ * content in the surrounding repository. A directory whose every entry is
+ * ignored, including the ignore file itself, does not appear in `git status` at
+ * all, which keeps the guarantee with the provider instead of asking each
+ * consumer to maintain a rule.
+ */
+function hideWorkspaceParentFromGit(parent: string): void {
+  const ignoreFile = join(parent, ".gitignore");
+  if (existsSync(ignoreFile)) return;
+  writeFileSync(ignoreFile, "*\n", { mode: 0o600 });
+}
+
 function reconcileAllocation(
   coordRoot: string,
   claim: WorkspaceClaim,
@@ -328,7 +368,9 @@ function reconcileAllocation(
     throw new Error("provider-owned workspace branch no longer matches its frozen base");
   }
 
-  const workspaceParent = createContainedDirectories(root, ["harnery-workspaces"]);
+  const parentSegment = claimedParentSegment(claim);
+  const workspaceParent = createContainedDirectories(root, [parentSegment]);
+  hideWorkspaceParentFromGit(workspaceParent);
   const workspaceParentIdentity = filesystemIdentity(workspaceParent);
   const registered = worktreeInventory(claim.repository.source_root.realpath);
   const exact = registered.find((item) => resolve(item.path) === claim.workspace_root);
@@ -385,7 +427,7 @@ function reconcileAllocation(
         parent_identity: workspaceParentIdentity,
       });
     }
-    const openedWorkspace = openContainedDirectory(root, ["harnery-workspaces", claim.binding_id]);
+    const openedWorkspace = openContainedDirectory(root, [parentSegment, claim.binding_id]);
     if (openedWorkspace.path !== claim.workspace_root) {
       openedWorkspace.close();
       throw new Error("descriptor-backed workspace directory differs from the claim");

package/src/core/workflow/workspaces/recovery.ts

@@ -16,11 +16,11 @@ export function readWorkflowLiveness(coordRoot: string, runId: string): Workflow
     }
   }
 
-  const journalPath = join(root, ".harnery", "workflows", runId, "journal.jsonl");
-  if (!existsSync(journalPath)) return "unknown";
+  const transcriptPath = join(root, ".harnery", "workflows", runId, "transcript.jsonl");
+  if (!existsSync(transcriptPath)) return "unknown";
   let events: Array<{ event?: string; run_id?: string; ok?: unknown; status?: unknown }>;
   try {
-    events = readFileSync(journalPath, "utf8")
+    events = readFileSync(transcriptPath, "utf8")
       .split("\n")
       .filter(Boolean)
       .map(

package/src/core/workflow/workspaces/state.ts

@@ -18,7 +18,7 @@ import {
   writeImmutableJson,
 } from "../durable-record.ts";
 
-export { appendWorkflowJournalEvent } from "../journal.ts";
+export { appendWorkflowTranscriptEvent } from "../transcript.ts";
 
 import type {
   GitRepositoryBinding,
@@ -232,7 +232,8 @@ export function readWorkspaceEvents(
 ): WorkspaceProviderEvent[] {
   const path = workspaceEventsPath(coordRoot, providerId, bindingId);
   if (!existsSync(path)) return [];
-  if (statSync(path).size > JSON_LIMIT * 4) throw new Error("workspace event journal is too large");
+  if (statSync(path).size > JSON_LIMIT * 4)
+    throw new Error("workspace event transcript is too large");
   const claim = readWorkspaceClaim(coordRoot, providerId, bindingId);
   if (!claim) throw new Error("workspace event authority claim is missing");
   const records = readFileSync(path, "utf8")
@@ -391,7 +392,7 @@ function readChainedRecords<
 >(path: string, label: string): T[] {
   if (!existsSync(path)) return [];
   if (statSync(path).size > JSON_LIMIT * 4) {
-    throw new Error(`${label} journal is too large`);
+    throw new Error(`${label} transcript is too large`);
   }
   const records = readFileSync(path, "utf8")
     .split("\n")

package/src/core/workflow/workspaces/types.ts

@@ -353,7 +353,7 @@ export interface IntegrationAuthorization {
   approval_id?: string;
   approval_actor?: string;
   approval_sha256?: string;
-  journal_anchor: {
+  transcript_anchor: {
     event: "integration.plan";
     plan_sha256: string;
   };

package/src/lib/browser/asserts.ts

@@ -0,0 +1,177 @@
+// Value assertions for `harn browse --assert`.
+//
+// The layout + content checks answer "does the page look right"; asserts answer
+// "does the page SAY the right thing" — the h1 text, a price, how many cards
+// rendered, whether an error banner is absent. It lets an agent confirm the
+// values it expects without a human reading the page back.
+//
+// One repeatable flag with a small grammar:
+//   --assert 'text h1 => Welcome'          first match's trimmed text equals
+//   --assert 'contains .total => $49'      first match's text contains
+//   --assert 'matches .sku => ^BN-\d+$'    first match's text matches a regex
+//   --assert 'count .card => >=3'          match count vs a number or comparator
+//   --assert 'exists .cta'                 at least one match
+//   --assert 'absent .error'               zero matches
+//
+// `op selector => expected`; `exists`/`absent` take no `=> expected`.
+
+export type AssertOp = "text" | "contains" | "matches" | "count" | "exists" | "absent";
+
+export interface AssertSpec {
+  raw: string;
+  op: AssertOp;
+  selector: string;
+  expected: string;
+}
+
+export interface AssertResult {
+  raw: string;
+  op: AssertOp;
+  selector: string;
+  expected: string;
+  /** Observed value: the text, or the match count as a string. */
+  actual: string;
+  found: boolean;
+  outcome: "pass" | "fail";
+  /** Populated when the spec itself was malformed (e.g. bad regex, bad count). */
+  error?: string;
+}
+
+const OPS: readonly AssertOp[] = ["text", "contains", "matches", "count", "exists", "absent"];
+
+/** Parse one `--assert` expression. Throws with a clear message on malformed input. */
+export function parseAssertSpec(raw: string): AssertSpec {
+  const trimmed = raw.trim();
+  const spaceIdx = trimmed.indexOf(" ");
+  if (spaceIdx < 0) {
+    throw new Error(`--assert needs '<op> <selector> [=> expected]' (got: '${raw}')`);
+  }
+  const op = trimmed.slice(0, spaceIdx).toLowerCase() as AssertOp;
+  if (!OPS.includes(op)) {
+    throw new Error(`--assert op must be one of ${OPS.join(", ")} (got: '${op}')`);
+  }
+  const rest = trimmed.slice(spaceIdx + 1).trim();
+  const sep = rest.indexOf("=>");
+  if (op === "exists" || op === "absent") {
+    return { raw, op, selector: (sep < 0 ? rest : rest.slice(0, sep)).trim(), expected: "" };
+  }
+  if (sep < 0) {
+    throw new Error(`--assert '${op}' needs 'selector => expected' (got: '${raw}')`);
+  }
+  return {
+    raw,
+    op,
+    selector: rest.slice(0, sep).trim(),
+    expected: rest.slice(sep + 2).trim(),
+  };
+}
+
+/**
+ * Build the page evaluator. Serialized into the page by Playwright, so helpers
+ * are nested. Comparison logic that does not touch the DOM (count comparators,
+ * regex) also runs in-page to keep it one round trip.
+ */
+export function buildAssertCheck(): (specs: AssertSpec[]) => AssertResult[] {
+  return (specs) => {
+    const textOf = (el: Element): string => (el.textContent ?? "").replace(/\s+/g, " ").trim();
+
+    const compareCount = (count: number, expected: string): { ok: boolean; error?: string } => {
+      const m = /^(>=|<=|>|<|=)?\s*(\d+)$/.exec(expected.trim());
+      if (!m) return { ok: false, error: `bad count expected '${expected}'` };
+      const op = m[1] || "=";
+      const n = Number.parseInt(m[2]!, 10);
+      switch (op) {
+        case ">=":
+          return { ok: count >= n };
+        case "<=":
+          return { ok: count <= n };
+        case ">":
+          return { ok: count > n };
+        case "<":
+          return { ok: count < n };
+        default:
+          return { ok: count === n };
+      }
+    };
+
+    return specs.map((spec): AssertResult => {
+      const base = {
+        raw: spec.raw,
+        op: spec.op,
+        selector: spec.selector,
+        expected: spec.expected,
+      };
+      let nodes: Element[];
+      try {
+        nodes = Array.from(document.querySelectorAll(spec.selector));
+      } catch {
+        return { ...base, actual: "", found: false, outcome: "fail", error: "invalid selector" };
+      }
+      const first = nodes[0] ?? null;
+      const firstText = first ? textOf(first) : "";
+
+      switch (spec.op) {
+        case "exists":
+          return {
+            ...base,
+            actual: String(nodes.length),
+            found: nodes.length > 0,
+            outcome: nodes.length > 0 ? "pass" : "fail",
+          };
+        case "absent":
+          return {
+            ...base,
+            actual: String(nodes.length),
+            found: nodes.length > 0,
+            outcome: nodes.length === 0 ? "pass" : "fail",
+          };
+        case "count": {
+          const { ok, error } = compareCount(nodes.length, spec.expected);
+          return {
+            ...base,
+            actual: String(nodes.length),
+            found: true,
+            outcome: ok ? "pass" : "fail",
+            ...(error ? { error } : {}),
+          };
+        }
+        case "text":
+          return {
+            ...base,
+            actual: firstText,
+            found: !!first,
+            outcome: first && firstText === spec.expected ? "pass" : "fail",
+          };
+        case "contains":
+          return {
+            ...base,
+            actual: firstText,
+            found: !!first,
+            outcome: first && firstText.includes(spec.expected) ? "pass" : "fail",
+          };
+        case "matches": {
+          let re: RegExp;
+          try {
+            re = new RegExp(spec.expected);
+          } catch {
+            return {
+              ...base,
+              actual: firstText,
+              found: !!first,
+              outcome: "fail",
+              error: `invalid regex '${spec.expected}'`,
+            };
+          }
+          return {
+            ...base,
+            actual: firstText,
+            found: !!first,
+            outcome: first && re.test(firstText) ? "pass" : "fail",
+          };
+        }
+        default:
+          return { ...base, actual: "", found: false, outcome: "fail", error: "unknown op" };
+      }
+    });
+  };
+}

package/src/lib/browser/client.ts

@@ -11,6 +11,15 @@ import {
   type Request,
 } from "playwright";
 import type { CookieJar, Cookie as JarCookie } from "../cookies/index.ts";
+import { type AssertResult, type AssertSpec, buildAssertCheck } from "./asserts.js";
+import {
+  buildClearContentAnnotationsScript,
+  buildContentAnnotateScript,
+  buildContentChecks,
+  type ContentAnnotationBox,
+  type ContentChecksRequest,
+  type ContentChecksResult,
+} from "./content-checks.js";
 import {
   buildClearLayoutLintAnnotationsScript,
   buildLayoutLintAnnotateScript,
@@ -141,6 +150,38 @@ export interface Diagnostics {
 
 const DEFAULT_PROFILE = resolve(homedir(), ".cache", "harnery", "browser-profile");
 
+// Bound how many Chromium processes SPAWN at the same moment. When many Browser
+// instances open at once — a full test suite, a fan-out of browse calls — the
+// simultaneous `child_process.spawn`s exhaust the OS's stdio-pipe/socket
+// resources and Chromium launch dies with an unhandled ENOENT that a per-call
+// retry can't catch. Serializing only the brief launch phase (never the
+// browser's lifetime, so N browsers still run concurrently) removes the burst
+// that causes it. Overridable via HARNERY_MAX_BROWSER_LAUNCHES.
+const MAX_CONCURRENT_LAUNCHES = Math.max(
+  1,
+  Number.parseInt(process.env.HARNERY_MAX_BROWSER_LAUNCHES ?? "3", 10) || 3,
+);
+let activeLaunches = 0;
+const launchWaiters: Array<() => void> = [];
+
+async function acquireLaunchSlot(): Promise<void> {
+  if (activeLaunches < MAX_CONCURRENT_LAUNCHES) {
+    activeLaunches++;
+    return;
+  }
+  // Queue; the releaser transfers its slot to us (activeLaunches unchanged).
+  await new Promise<void>((resolve) => launchWaiters.push(resolve));
+}
+
+function releaseLaunchSlot(): void {
+  const next = launchWaiters.shift();
+  if (next) {
+    next();
+  } else {
+    activeLaunches = Math.max(0, activeLaunches - 1);
+  }
+}
+
 export class Browser {
   private context: BrowserContext | null = null;
   private page: Page | null = null;
@@ -161,20 +202,27 @@ export class Browser {
     return this.page;
   }
 
-  async open(): Promise<void> {
-    if (this.context) return;
-    mkdirSync(this.profileDir, { recursive: true });
-
-    this.context = await chromium.launchPersistentContext(this.profileDir, {
-      headless: !this.opts.headed,
-      viewport: this.opts.viewport ?? { width: 1280, height: 800 },
-      ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
-        ? { args: this.opts.launchArgs }
-        : {}),
-      ...(this.opts.recordHarPath
-        ? { recordHar: { path: this.opts.recordHarPath, mode: "full" as const } }
-        : {}),
-    });
+  /**
+   * Launch the context and wire up the first page. Factored out of `open()` so
+   * the whole sequence — not just the launch — can be retried as a unit.
+   */
+  private async openOnce(): Promise<void> {
+    // Hold a launch slot only across the spawn itself, not the browser's life.
+    await acquireLaunchSlot();
+    try {
+      this.context = await chromium.launchPersistentContext(this.profileDir, {
+        headless: !this.opts.headed,
+        viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+        ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
+          ? { args: this.opts.launchArgs }
+          : {}),
+        ...(this.opts.recordHarPath
+          ? { recordHar: { path: this.opts.recordHarPath, mode: "full" as const } }
+          : {}),
+      });
+    } finally {
+      releaseLaunchSlot();
+    }
     this.context.setDefaultNavigationTimeout(this.opts.navigationTimeout ?? 30_000);
 
     if (this.opts.jar) {
@@ -202,6 +250,54 @@ export class Browser {
     this.attachDiagnosticListeners(this.page);
   }
 
+  /**
+   * Open the browser, retrying a few times on a transient startup failure.
+   * Chromium occasionally fails to hand off its CDP port ("Failed to connect",
+   * "Target closed") when many instances launch at once — a busy CI box or a
+   * full test suite — and the failure can surface on the launch OR on a
+   * follow-up call (addCookies, newPage) when the process dies right after
+   * spawning. So the entire open sequence retries as a unit, tearing down any
+   * half-built context between attempts. A genuinely broken config fails every
+   * attempt and throws with the underlying message.
+   */
+  async open(): Promise<void> {
+    if (this.context) return;
+    mkdirSync(this.profileDir, { recursive: true });
+
+    const maxAttempts = 3;
+    let lastErr: unknown;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        await this.openOnce();
+        return;
+      } catch (err) {
+        lastErr = err;
+        // Tear down a partial context + reset diagnostics collected on the
+        // failed attempt, so the retry starts clean. (openOnce() reassigns
+        // this.context, which TS can't see across the call, so re-widen.)
+        const partial = this.context as BrowserContext | null;
+        if (partial) {
+          try {
+            await partial.close();
+          } catch {
+            // ignore — the process is likely already gone
+          }
+        }
+        this.context = null;
+        this.page = null;
+        this.consoleEvents = [];
+        this.pageErrors = [];
+        this.failedRequests = [];
+        if (attempt < maxAttempts) {
+          await new Promise((resolve) => setTimeout(resolve, attempt * 250));
+        }
+      }
+    }
+    throw new Error(
+      `Failed to open browser after ${maxAttempts} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`,
+    );
+  }
+
   /**
    * Hook console + pageerror + requestfailed events. Called on `open()`
    * before any navigation so we don't miss early-fired events.
@@ -295,6 +391,65 @@ export class Browser {
     return buf.length;
   }
 
+  /** Full document + viewport dimensions, for tiling a page into bands. */
+  async pageMetrics(): Promise<{
+    scrollWidth: number;
+    scrollHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+  }> {
+    return await this.currentPage.evaluate(() => ({
+      scrollWidth: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0),
+      scrollHeight: Math.max(
+        document.documentElement.scrollHeight,
+        document.body?.scrollHeight ?? 0,
+      ),
+      viewportWidth: window.innerWidth,
+      viewportHeight: window.innerHeight,
+    }));
+  }
+
+  /** Full-page PNG as a Buffer, for cropping critique tiles in pixel space. */
+  async fullPageScreenshotBuffer(): Promise<Buffer> {
+    return await this.currentPage.screenshot({ type: "png", fullPage: true });
+  }
+
+  /** Base64 PNG of a document-space clip rect. Used to capture one critique tile. */
+  async screenshotClipBase64(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }): Promise<string> {
+    const buf = await this.currentPage.screenshot({ type: "png", clip: rect });
+    return buf.toString("base64");
+  }
+
+  /** Document-space rects + labels for each element matching `selector` (semantic tiling). */
+  async elementTiles(
+    selector: string,
+  ): Promise<Array<{ label: string; x: number; y: number; width: number; height: number }>> {
+    return await this.currentPage.evaluate((sel) => {
+      const out: Array<{ label: string; x: number; y: number; width: number; height: number }> = [];
+      const sx = window.scrollX;
+      const sy = window.scrollY;
+      for (const el of Array.from(document.querySelectorAll(sel))) {
+        const r = el.getBoundingClientRect();
+        if (r.width <= 0 || r.height <= 0) continue;
+        const tag = el.tagName.toLowerCase();
+        const cls = typeof el.className === "string" ? el.className.trim().split(/\s+/)[0] : "";
+        out.push({
+          label: el.id ? `${tag}#${el.id}` : cls ? `${tag}.${cls}` : tag,
+          x: Math.max(0, r.x + sx),
+          y: Math.max(0, r.y + sy),
+          width: r.width,
+          height: r.height,
+        });
+      }
+      return out;
+    }, selector);
+  }
+
   /**
    * Capture a full-page screenshot from an explicit capture viewport and
    * evaluate the caller's final evidence expression immediately before the
@@ -600,6 +755,26 @@ export class Browser {
     await this.currentPage.evaluate(buildClearLayoutLintAnnotationsScript());
   }
 
+  /** Run the requested content checks (placeholder/image/truncation/contrast) in one evaluation. */
+  async checkContent(request: ContentChecksRequest): Promise<ContentChecksResult> {
+    return await this.currentPage.evaluate(buildContentChecks(), request);
+  }
+
+  /** Evaluate value assertions (text/contains/matches/count/exists/absent) against the page. */
+  async checkAsserts(specs: AssertSpec[]): Promise<AssertResult[]> {
+    return await this.currentPage.evaluate(buildAssertCheck(), specs);
+  }
+
+  /** Draw one document-space annotation layer for content-check hits. */
+  async annotateContent(boxes: ContentAnnotationBox[]): Promise<void> {
+    await this.currentPage.evaluate(buildContentAnnotateScript(), { boxes });
+  }
+
+  /** Remove content-check annotations. */
+  async clearContentAnnotations(): Promise<void> {
+    await this.currentPage.evaluate(buildClearContentAnnotationsScript());
+  }
+
   /**
    * Run the target-size rule against the page or explicit scopes. The
    * dependency's browser bundle is evaluated directly in the page context so