cairn-engine 1.0.0 → 1.1.0

package/README.md

@@ -55,6 +55,14 @@ Every layer is replaceable: bring your own `Driver` (e.g. Playwright), `Critic`,
 assertions / `actions` for what doesn't fit the built-ins. Nothing forces your product
 through only what we decided.
 
+**Browser or extension (no Node)?** `runScenario` and the default Chrome DevTools MCP driver
+need Node. Import the browser-safe core from `cairn-engine/browser` and compose `runHarness`
+with your own `Driver` (e.g. one over `chrome.debugger`) plus a fetch-based `LlmClient`:
+
+```ts
+import { runHarness, StaticPlanner, AssertionCritic, AnthropicLlmClient } from "cairn-engine/browser";
+```
+
 No API key needed if you have **Claude Code** installed (cairn shells out to it); set
 `ANTHROPIC_API_KEY` to use the Anthropic API instead.
 

package/dist/adapters/context/inline.d.ts

@@ -2,7 +2,5 @@
 import type { ContextProvider } from "../../core/ports.js";
 import type { Context } from "../../core/types.js";
 export declare class InlineContextProvider implements ContextProvider {
-    private readonly baseUrl?;
-    constructor(baseUrl?: string | undefined);
     provide(task: string): Promise<Context>;
 }

package/dist/adapters/context/inline.js

@@ -1,10 +1,6 @@
 export class InlineContextProvider {
-    baseUrl;
-    constructor(baseUrl) {
-        this.baseUrl = baseUrl;
-    }
     async provide(task) {
-        return { intent: task, baseUrl: this.baseUrl };
+        return { intent: task };
     }
 }
 //# sourceMappingURL=inline.js.map

package/dist/adapters/context/inline.js.map

@@ -1 +1 @@
-{"version":3,"file":"inline.js","sourceRoot":"","sources":["../../../src/adapters/context/inline.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,qBAAqB;IACH;IAA7B,YAA6B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;IAAG,CAAC;IAEjD,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IACjD,CAAC;CACF"}
+{"version":3,"file":"inline.js","sourceRoot":"","sources":["../../../src/adapters/context/inline.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,qBAAqB;IAChC,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;CACF"}

package/dist/adapters/critics/assertion.d.ts

@@ -1,6 +1,6 @@
 /** Deterministic Critic for the replay path — checks assertions against evidence, no LLM (invariant #4). */
-import type { Critic } from "../../core/ports.js";
-import type { Assertion, AssertionResult, Evidence, Verdict } from "../../core/types.js";
+import type { AssertionHandler, Critic } from "../../core/ports.js";
+import type { Assertion, AssertionResult, Context, Evidence, Verdict } from "../../core/types.js";
 /** A product-defined check for a `{ kind: "custom", name }` assertion — the host decides what success means. */
 export type CustomCheck = (params: Record<string, unknown>, evidence: Evidence) => boolean | {
     passed: boolean;
@@ -10,12 +10,26 @@ export type CustomCheck = (params: Record<string, unknown>, evidence: Evidence)
     detail?: string;
 }>;
 export type CustomChecks = Record<string, CustomCheck>;
-/** Resolve any assertion — a registered `custom` handler, else the built-in mechanical check. */
-export declare function resolveAssertion(assertion: Assertion, evidence: Evidence, custom?: CustomChecks): Promise<AssertionResult>;
 /** Evaluate one mechanical assertion. `expect` is not mechanical — returns unsupported (LlmCritic handles it). */
 export declare function checkAssertion(assertion: Assertion, evidence: Evidence): AssertionResult;
-export declare class AssertionCritic implements Critic {
+/** Built-in mechanical checks — every kind except product `custom` (`expect` yields its LlmCritic hint). */
+export declare class MechanicalAssertionHandler implements AssertionHandler {
+    supports(assertion: Assertion): boolean;
+    judge(assertion: Assertion, evidence: Evidence): AssertionResult;
+}
+/** Product-defined `{ kind: "custom", name }` checks via a name→check registry. */
+export declare class CustomAssertionHandler implements AssertionHandler {
     private readonly custom;
+    constructor(custom?: CustomChecks);
+    supports(assertion: Assertion): boolean;
+    judge(assertion: Assertion, evidence: Evidence): Promise<AssertionResult>;
+}
+/** Route one assertion to the first handler that supports it (mirror of the Execute-stage step dispatch). */
+export declare function judgeAssertion(handlers: AssertionHandler[], assertion: Assertion, evidence: Evidence, ctx?: Context): Promise<AssertionResult>;
+/** Resolve any assertion — a registered `custom` handler, else the built-in mechanical check. */
+export declare function resolveAssertion(assertion: Assertion, evidence: Evidence, custom?: CustomChecks): Promise<AssertionResult>;
+export declare class AssertionCritic implements Critic {
+    private readonly handlers;
     /** @param custom product-defined checks for `custom` assertions, keyed by name. */
     constructor(custom?: CustomChecks);
     judge(evidence: Evidence, assertions: Assertion[]): Promise<Verdict>;

package/dist/adapters/critics/assertion.js

@@ -1,14 +1,3 @@
-/** Resolve any assertion — a registered `custom` handler, else the built-in mechanical check. */
-export async function resolveAssertion(assertion, evidence, custom = {}) {
-    if (assertion.kind === "custom") {
-        const handler = custom[assertion.name];
-        if (!handler)
-            return { assertion, passed: false, detail: `no custom check registered for "${assertion.name}"` };
-        const r = await handler(assertion.params ?? {}, evidence);
-        return typeof r === "boolean" ? { assertion, passed: r } : { assertion, passed: r.passed, detail: r.detail };
-    }
-    return checkAssertion(assertion, evidence);
-}
 /** Requests whose failure is noise, not a regression — excluded from `no-failed-requests`. */
 function isBenignRequest(url) {
     return /\/favicon\.ico(\?|$)/i.test(url) || /\/robots\.txt(\?|$)/i.test(url);
@@ -52,14 +41,53 @@ export function checkAssertion(assertion, evidence) {
             return { assertion, passed: false, detail: `custom check "${assertion.name}" needs a registered handler` };
     }
 }
-export class AssertionCritic {
+/** Built-in mechanical checks — every kind except product `custom` (`expect` yields its LlmCritic hint). */
+export class MechanicalAssertionHandler {
+    supports(assertion) {
+        return assertion.kind !== "custom";
+    }
+    judge(assertion, evidence) {
+        return checkAssertion(assertion, evidence);
+    }
+}
+/** Product-defined `{ kind: "custom", name }` checks via a name→check registry. */
+export class CustomAssertionHandler {
     custom;
-    /** @param custom product-defined checks for `custom` assertions, keyed by name. */
     constructor(custom = {}) {
         this.custom = custom;
     }
+    supports(assertion) {
+        return assertion.kind === "custom";
+    }
+    async judge(assertion, evidence) {
+        if (assertion.kind !== "custom")
+            throw new Error(`custom handler received "${assertion.kind}" assertion`);
+        const check = this.custom[assertion.name];
+        if (!check)
+            return { assertion, passed: false, detail: `no custom check registered for "${assertion.name}"` };
+        const r = await check(assertion.params ?? {}, evidence);
+        return typeof r === "boolean" ? { assertion, passed: r } : { assertion, passed: r.passed, detail: r.detail };
+    }
+}
+/** Route one assertion to the first handler that supports it (mirror of the Execute-stage step dispatch). */
+export async function judgeAssertion(handlers, assertion, evidence, ctx) {
+    const handler = handlers.find((h) => h.supports(assertion));
+    if (!handler)
+        return { assertion, passed: false, detail: `no critic handles "${assertion.kind}"` };
+    return handler.judge(assertion, evidence, ctx);
+}
+/** Resolve any assertion — a registered `custom` handler, else the built-in mechanical check. */
+export function resolveAssertion(assertion, evidence, custom = {}) {
+    return judgeAssertion([new MechanicalAssertionHandler(), new CustomAssertionHandler(custom)], assertion, evidence);
+}
+export class AssertionCritic {
+    handlers;
+    /** @param custom product-defined checks for `custom` assertions, keyed by name. */
+    constructor(custom = {}) {
+        this.handlers = [new MechanicalAssertionHandler(), new CustomAssertionHandler(custom)];
+    }
     async judge(evidence, assertions) {
-        const results = await Promise.all(assertions.map((a) => resolveAssertion(a, evidence, this.custom)));
+        const results = await Promise.all(assertions.map((a) => judgeAssertion(this.handlers, a, evidence)));
         return { passed: results.every((r) => r.passed), results };
     }
 }

package/dist/adapters/critics/assertion.js.map

@@ -1 +1 @@
-{"version":3,"file":"assertion.js","sourceRoot":"","sources":["../../../src/adapters/critics/assertion.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"assertion.js","sourceRoot":"","sources":["../../../src/adapters/critics/assertion.ts"],"names":[],"mappings":"AAYA,8FAA8F;AAC9F,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/E,CAAC;AAED,kHAAkH;AAClH,MAAM,UAAU,cAAc,CAAC,SAAoB,EAAE,QAAkB;IACrE,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC;YACnD,IAAI,CAAC,SAAS;gBAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;YACtF,IAAI,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,QAAQ,qBAAqB,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC;YACxG,CAAC;YACD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QACvD,CAAC;QACD,KAAK,mBAAmB,CAAC,CAAC,CAAC;YACzB,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;YACxE,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC;gBACxB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;gBAC7B,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,sBAAsB,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;QACpG,CAAC;QACD,KAAK,oBAAoB,CAAC,CAAC,CAAC;YAC1B,sFAAsF;YACtF,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACjG,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC;gBACxB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;gBAC7B,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,uBAAuB,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;QACzH,CAAC;QACD,KAAK,gBAAgB,CAAC,CAAC,CAAC;YACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;YACzF,IAAI,CAAC,KAAK;gBAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC;YACxG,OAAO,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM;gBACtC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,EAAE,EAAE;gBACrE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,SAAS,CAAC,MAAM,SAAS,KAAK,CAAC,MAAM,QAAQ,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC;QACjH,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,+DAA+D,EAAE,CAAC;QAC/G,KAAK,QAAQ;YACX,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,SAAS,CAAC,IAAI,8BAA8B,EAAE,CAAC;IAC/G,CAAC;AACH,CAAC;AAED,4GAA4G;AAC5G,MAAM,OAAO,0BAA0B;IACrC,QAAQ,CAAC,SAAoB;QAC3B,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,SAAoB,EAAE,QAAkB;QAC5C,OAAO,cAAc,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;CACF;AAED,mFAAmF;AACnF,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,SAAuB,EAAE;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAE1D,QAAQ,CAAC,SAAoB;QAC3B,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,SAAoB,EAAE,QAAkB;QAClD,IAAI,SAAS,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,SAAS,CAAC,IAAI,aAAa,CAAC,CAAC;QAC1G,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,mCAAmC,SAAS,CAAC,IAAI,GAAG,EAAE,CAAC;QAC9G,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,EAAE,QAAQ,CAAC,CAAC;QACxD,OAAO,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/G,CAAC;CACF;AAED,6GAA6G;AAC7G,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAA4B,EAC5B,SAAoB,EACpB,QAAkB,EAClB,GAAa;IAEb,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAC5D,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,SAAS,CAAC,IAAI,GAAG,EAAE,CAAC;IACnG,OAAO,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;AACjD,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,gBAAgB,CAC9B,SAAoB,EACpB,QAAkB,EAClB,SAAuB,EAAE;IAEzB,OAAO,cAAc,CAAC,CAAC,IAAI,0BAA0B,EAAE,EAAE,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACrH,CAAC;AAED,MAAM,OAAO,eAAe;IACT,QAAQ,CAAqB;IAE9C,mFAAmF;IACnF,YAAY,SAAuB,EAAE;QACnC,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,0BAA0B,EAAE,EAAE,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC;IACzF,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,QAAkB,EAAE,UAAuB;QACrD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QACrG,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;IAC7D,CAAC;CACF"}

package/dist/adapters/critics/llm.d.ts

@@ -1,12 +1,17 @@
 import type { CustomChecks } from "./assertion.js";
-import type { Critic, LlmClient } from "../../core/ports.js";
-import type { Assertion, Evidence, Verdict } from "../../core/types.js";
+import type { AssertionHandler, Critic, LlmClient } from "../../core/ports.js";
+import type { Assertion, AssertionResult, Context, Evidence, Verdict } from "../../core/types.js";
 /** Compact, judge-friendly rendering of the three evidence layers. */
 export declare function summarizeEvidence(evidence: Evidence): string;
-export declare class LlmCritic implements Critic {
+/** Judges natural-language `expect` criteria with an LLM, grounded in the evidence and task intent. */
+export declare class ExpectAssertionHandler implements AssertionHandler {
     private readonly llm;
-    private readonly custom;
+    constructor(llm: LlmClient);
+    supports(assertion: Assertion): boolean;
+    judge(assertion: Assertion, evidence: Evidence, ctx?: Context): Promise<AssertionResult>;
+}
+export declare class LlmCritic implements Critic {
+    private readonly handlers;
     constructor(llm: LlmClient, custom?: CustomChecks);
-    private judgeExpect;
-    judge(evidence: Evidence, assertions: Assertion[]): Promise<Verdict>;
+    judge(evidence: Evidence, assertions: Assertion[], ctx?: Context): Promise<Verdict>;
 }

package/dist/adapters/critics/llm.js

@@ -2,9 +2,10 @@
  * Critic that judges natural-language `expect` criteria with an LLM and delegates mechanical
  * assertions to the deterministic checker. The LLM runs ONLY for `expect`, so a scenario with
  * none makes zero LLM calls and stays deterministic (invariant #4). Judgment is grounded in the
- * three-layer evidence (design §6), behind the LlmClient seam (invariant #5).
+ * three-layer evidence (design §6) and, when a ContextProvider supplied one, the task intent —
+ * behind the LlmClient seam (invariant #5).
  */
-import { resolveAssertion } from "./assertion.js";
+import { CustomAssertionHandler, MechanicalAssertionHandler, judgeAssertion } from "./assertion.js";
 const SYSTEM = "You are a QA critic. Given observed evidence from a browser run and a success " +
     "criterion, decide whether the criterion is satisfied. Judge only from the evidence; " +
     'do not assume. Respond with strict JSON, no prose, no code fences: {"passed":true|false,"detail":"<short reason>"}.';
@@ -35,22 +36,30 @@ function parseVerdict(text) {
     const obj = JSON.parse(s.slice(start, end + 1));
     return { passed: obj.passed === true, detail: typeof obj.detail === "string" ? obj.detail : undefined };
 }
-export class LlmCritic {
+/** Judges natural-language `expect` criteria with an LLM, grounded in the evidence and task intent. */
+export class ExpectAssertionHandler {
     llm;
-    custom;
-    constructor(llm, custom = {}) {
+    constructor(llm) {
         this.llm = llm;
-        this.custom = custom;
     }
-    async judgeExpect(criterion, evidence, assertion) {
-        const prompt = [
-            `Success criterion: ${criterion}`,
+    supports(assertion) {
+        return assertion.kind === "expect";
+    }
+    async judge(assertion, evidence, ctx) {
+        if (assertion.kind !== "expect")
+            throw new Error(`expect handler received "${assertion.kind}" assertion`);
+        const lines = [
+            `Success criterion: ${assertion.criterion}`,
             ``,
             `Evidence:`,
             summarizeEvidence(evidence),
             ``,
             `Is the criterion satisfied? Respond with JSON only.`,
-        ].join("\n");
+        ];
+        // Ground the judgment in the run's intent when a ContextProvider supplied one.
+        if (ctx?.intent)
+            lines.unshift(`Task intent: ${ctx.intent}`, ``);
+        const prompt = lines.join("\n");
         try {
             const reply = await this.llm.complete(prompt, { system: SYSTEM });
             const v = parseVerdict(reply);
@@ -60,10 +69,20 @@ export class LlmCritic {
             return { assertion, passed: false, detail: `LLM judgment failed: ${err instanceof Error ? err.message : String(err)}` };
         }
     }
-    async judge(evidence, assertions) {
-        const results = await Promise.all(assertions.map((a) => a.kind === "expect"
-            ? this.judgeExpect(a.criterion, evidence, a)
-            : resolveAssertion(a, evidence, this.custom)));
+}
+export class LlmCritic {
+    handlers;
+    constructor(llm, custom = {}) {
+        // `expect` → LLM (first, so it wins); everything else falls through to the same
+        // mechanical/custom handlers AssertionCritic uses. The two critics differ only here.
+        this.handlers = [
+            new ExpectAssertionHandler(llm),
+            new MechanicalAssertionHandler(),
+            new CustomAssertionHandler(custom),
+        ];
+    }
+    async judge(evidence, assertions, ctx) {
+        const results = await Promise.all(assertions.map((a) => judgeAssertion(this.handlers, a, evidence, ctx)));
         return { passed: results.every((r) => r.passed), results };
     }
 }

package/dist/adapters/critics/llm.js.map

@@ -1 +1 @@
-{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../src/adapters/critics/llm.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../src/adapters/critics/llm.ts"],"names":[],"mappings":"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"}

package/dist/adapters/planners/static.d.ts

@@ -4,5 +4,5 @@ import type { Context, Scenario } from "../../core/types.js";
 export declare class StaticPlanner implements Planner {
     private readonly scenario;
     constructor(scenario: Scenario);
-    plan(_ctx: Context): Promise<Scenario>;
+    plan(ctx: Context): Promise<Scenario>;
 }

package/dist/adapters/planners/static.js

@@ -3,8 +3,10 @@ export class StaticPlanner {
     constructor(scenario) {
         this.scenario = scenario;
     }
-    async plan(_ctx) {
-        return this.scenario;
+    async plan(ctx) {
+        // A custom ContextProvider can relabel the run through intent; on the default
+        // replay path the task is scenario.name, so intent === name and this is a no-op.
+        return { ...this.scenario, name: ctx.intent || this.scenario.name };
     }
 }
 //# sourceMappingURL=static.js.map

package/dist/adapters/planners/static.js.map

@@ -1 +1 @@
-{"version":3,"file":"static.js","sourceRoot":"","sources":["../../../src/adapters/planners/static.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,QAAkB;QAAlB,aAAQ,GAAR,QAAQ,CAAU;IAAG,CAAC;IAEnD,KAAK,CAAC,IAAI,CAAC,IAAa;QACtB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}
+{"version":3,"file":"static.js","sourceRoot":"","sources":["../../../src/adapters/planners/static.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,QAAkB;QAAlB,aAAQ,GAAR,QAAQ,CAAU;IAAG,CAAC;IAEnD,KAAK,CAAC,IAAI,CAAC,GAAY;QACrB,8EAA8E;QAC9E,iFAAiF;QACjF,OAAO,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;IACtE,CAAC;CACF"}

package/dist/browser.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Browser-safe surface of cairn-engine — the runtime-agnostic core plus the pure adapters,
+ * for environments without Node (a Chrome extension, a web app). Excludes the Node-only
+ * adapters (Chrome DevTools MCP driver, Claude CLI client, fs-based reporters / skill store)
+ * and `runScenario`, which statically wires them.
+ *
+ * Compose `runHarness` with your own `Driver` (e.g. a CDP/extension driver) and, for discover or
+ * `expect`, a fetch-based `LlmClient` (`AnthropicLlmClient`). Same core, different hands.
+ */
+export * from "./core/types.js";
+export * from "./core/ports.js";
+export { runHarness } from "./core/pipeline.js";
+export type { RunHarnessOptions } from "./core/pipeline.js";
+export { BuiltinStepHandler, CustomStepHandler, defaultStepHandlers } from "./core/steps.js";
+export { InlineContextProvider } from "./adapters/context/inline.js";
+export { StaticPlanner } from "./adapters/planners/static.js";
+export { AssertionCritic, checkAssertion, resolveAssertion, judgeAssertion, MechanicalAssertionHandler, CustomAssertionHandler, } from "./adapters/critics/assertion.js";
+export type { CustomCheck, CustomChecks } from "./adapters/critics/assertion.js";
+export { LlmCritic, ExpectAssertionHandler, summarizeEvidence } from "./adapters/critics/llm.js";
+export { ConsoleReporter } from "./adapters/reporters/console.js";
+export { FakeDriver } from "./adapters/drivers/fake.js";
+export { SelfHealingDriver, parseHealChoice } from "./adapters/drivers/self-heal.js";
+export type { Heal, SelfHealOptions } from "./adapters/drivers/self-heal.js";
+export { AnthropicLlmClient } from "./adapters/llm/anthropic.js";
+export { discover, parseDecision } from "./core/discover.js";
+export type { DiscoverOptions, Decision } from "./core/discover.js";

package/dist/browser.js

@@ -0,0 +1,23 @@
+/**
+ * Browser-safe surface of cairn-engine — the runtime-agnostic core plus the pure adapters,
+ * for environments without Node (a Chrome extension, a web app). Excludes the Node-only
+ * adapters (Chrome DevTools MCP driver, Claude CLI client, fs-based reporters / skill store)
+ * and `runScenario`, which statically wires them.
+ *
+ * Compose `runHarness` with your own `Driver` (e.g. a CDP/extension driver) and, for discover or
+ * `expect`, a fetch-based `LlmClient` (`AnthropicLlmClient`). Same core, different hands.
+ */
+export * from "./core/types.js";
+export * from "./core/ports.js";
+export { runHarness } from "./core/pipeline.js";
+export { BuiltinStepHandler, CustomStepHandler, defaultStepHandlers } from "./core/steps.js";
+export { InlineContextProvider } from "./adapters/context/inline.js";
+export { StaticPlanner } from "./adapters/planners/static.js";
+export { AssertionCritic, checkAssertion, resolveAssertion, judgeAssertion, MechanicalAssertionHandler, CustomAssertionHandler, } from "./adapters/critics/assertion.js";
+export { LlmCritic, ExpectAssertionHandler, summarizeEvidence } from "./adapters/critics/llm.js";
+export { ConsoleReporter } from "./adapters/reporters/console.js";
+export { FakeDriver } from "./adapters/drivers/fake.js";
+export { SelfHealingDriver, parseHealChoice } from "./adapters/drivers/self-heal.js";
+export { AnthropicLlmClient } from "./adapters/llm/anthropic.js";
+export { discover, parseDecision } from "./core/discover.js";
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE7F,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/core/pipeline.d.ts

@@ -3,10 +3,8 @@
  * is injected (invariant #2); with a fixed-scenario Planner + deterministic Critic, no LLM
  * runs (invariant #4).
  */
-import type { Driver, Harness } from "./ports.js";
+import type { CustomAction, Harness, StepHandler } from "./ports.js";
 import type { Result, StepProgress } from "./types.js";
-/** A product-defined interaction for a `{ kind: "custom", name }` step — composes the Driver. */
-export type CustomAction = (driver: Driver, params: Record<string, unknown>) => Promise<void>;
 /**
  * Seams a host (CLI, desktop app, CI) plugs into — the engine emits/accepts, the host
  * decides what to do. `onStep` for a live timeline, `captureScreenshots` for visual
@@ -17,6 +15,9 @@ export interface RunHarnessOptions {
     signal?: AbortSignal;
     onStep?: (progress: StepProgress) => void;
     captureScreenshots?: boolean;
+    /** Product-defined interactions for `{ kind: "custom", name }` steps, registered by name. */
     actions?: Record<string, CustomAction>;
+    /** Replace the Execute-stage dispatch chain entirely (advanced); defaults to built-ins + `actions`. */
+    stepHandlers?: StepHandler[];
 }
 export declare function runHarness(harness: Harness, task: string, opts?: RunHarnessOptions): Promise<Result>;

package/dist/core/pipeline.js

@@ -1,42 +1,11 @@
-async function executeStep(driver, step, actions) {
+import { defaultStepHandlers } from "./steps.js";
+/** Route one step to the first handler that supports it; record success/failure either way. */
+async function executeStep(handlers, step, driver) {
     try {
-        switch (step.kind) {
-            case "goto":
-                await driver.goto(step.url);
-                break;
-            case "click":
-                await driver.click(step.target);
-                break;
-            case "doubleClick":
-                await driver.doubleClick(step.target);
-                break;
-            case "hover":
-                await driver.hover(step.target);
-                break;
-            case "type":
-                await driver.type(step.target, step.text);
-                break;
-            case "select":
-                await driver.select(step.target, step.value);
-                break;
-            case "pressKey":
-                await driver.pressKey(step.key);
-                break;
-            case "scroll":
-                await driver.scroll(step.direction);
-                break;
-            case "custom": {
-                const handler = actions[step.name];
-                if (!handler)
-                    throw new Error(`no handler registered for custom action "${step.name}"`);
-                await handler(driver, step.params ?? {});
-                break;
-            }
-            default: {
-                const unhandled = step;
-                throw new Error(`unhandled step kind: ${JSON.stringify(unhandled)}`);
-            }
-        }
+        const handler = handlers.find((h) => h.supports(step));
+        if (!handler)
+            throw new Error(`no step handler for kind "${step.kind}"`);
+        await handler.execute(step, driver);
         return { step, ok: true };
     }
     catch (err) {
@@ -45,6 +14,7 @@ async function executeStep(driver, step, actions) {
 }
 export async function runHarness(harness, task, opts = {}) {
     const { context, planner, driver, critic, reporter } = harness;
+    const handlers = opts.stepHandlers ?? defaultStepHandlers(opts.actions ?? {});
     const ctx = await context.provide(task);
     const scenario = await planner.plan(ctx);
     // Drive steps; stop on the first failure but still observe the resulting state.
@@ -52,7 +22,7 @@ export async function runHarness(harness, task, opts = {}) {
     try {
         for (const step of scenario.steps) {
             opts.signal?.throwIfAborted(); // cooperative cancellation between steps (host owns Stop)
-            const result = await executeStep(driver, step, opts.actions ?? {});
+            const result = await executeStep(handlers, step, driver);
             actions.push(result);
             if (opts.onStep) {
                 const screenshot = opts.captureScreenshots ? await driver.screenshot().catch(() => undefined) : undefined;
@@ -68,7 +38,7 @@ export async function runHarness(harness, task, opts = {}) {
             ...observed,
             execution: { ...observed.execution, actions, blocked: actions.some((a) => !a.ok) },
         };
-        const verdict = await critic.judge(evidence, scenario.assertions);
+        const verdict = await critic.judge(evidence, scenario.assertions, ctx);
         const out = { scenario: scenario.name, context: ctx, evidence, verdict };
         await reporter.emit(out);
         return out;

package/dist/core/pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"AAwBA,KAAK,UAAU,WAAW,CACxB,MAAyB,EACzB,IAAU,EACV,OAAqC;IAErC,IAAI,CAAC;QACH,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,MAAM;gBACT,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAC5B,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,aAAa;gBAChB,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACtC,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,MAAM;gBACT,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC7C,MAAM;YACR,KAAK,UAAU;gBACb,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACpC,MAAM;YACR,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACnC,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;gBACxF,MAAM,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;gBACzC,MAAM;YACR,CAAC;YACD,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,SAAS,GAAU,IAAI,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACtF,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAgB,EAChB,IAAY,EACZ,OAA0B,EAAE;IAE5B,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAE/D,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEzC,gFAAgF;IAChF,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,IAAI,CAAC;QACH,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC,0DAA0D;YACzF,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChB,MAAM,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC1G,IAAI,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;YACnG,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,MAAM;QACxB,CAAC;QAED,6FAA6F;QAC7F,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;QAEtB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAa;YACzB,GAAG,QAAQ;YACX,SAAS,EAAE,EAAE,GAAG,QAAQ,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;SACnF,CAAC;QAEF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;QAClE,MAAM,GAAG,GAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QACjF,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/core/ports.d.ts

@@ -2,7 +2,7 @@
  * The ports of the cairn engine (invariant #2: add behavior by implementing one of these,
  * never by branching inside a stage). Core depends only on these; `../adapters` implement them.
  */
-import type { Assertion, Context, Evidence, PageElement, Result, Scenario, SettleOptions, Target, Verdict } from "./types.js";
+import type { Assertion, AssertionResult, Context, Evidence, PageElement, Result, Scenario, SettleOptions, Step, Target, Verdict } from "./types.js";
 /** Grounding from any source (NL, git diff, ticket, RAG). */
 export interface ContextProvider {
     provide(task: string): Promise<Context>;
@@ -34,6 +34,17 @@ export interface Driver {
     observe(): Promise<Evidence>;
     close(): Promise<void>;
 }
+/** A product-defined interaction for a `{ kind: "custom", name }` step — composes the Driver. */
+export type CustomAction = (driver: Driver, params: Record<string, unknown>) => Promise<void>;
+/**
+ * One link in the Execute stage's dispatch chain (invariant #2): the pipeline routes each Step
+ * to the first handler that `supports` it, instead of branching inside the stage. Built-in kinds
+ * and product `custom` actions resolve through this one seam (Spring `HandlerAdapter`-style).
+ */
+export interface StepHandler {
+    supports(step: Step): boolean;
+    execute(step: Step, driver: Driver): Promise<void>;
+}
 export interface Skill {
     name: string;
     scenario: Scenario;
@@ -41,9 +52,19 @@ export interface Skill {
 export interface SkillStore {
     resolve(name: string): Promise<Skill | undefined>;
 }
-/** Judges evidence against assertions (mechanical, baseline, or LLM). */
+/**
+ * One link in the Judge stage's dispatch chain (mirror of StepHandler): a Critic routes each
+ * Assertion to the first handler that `supports` it. Mechanical, product `custom`, and LLM
+ * `expect` checks compose as separate handlers — critics differ only by which they register.
+ * Optional `ctx` grounds LLM judgment (e.g. the task intent); deterministic handlers ignore it.
+ */
+export interface AssertionHandler {
+    supports(assertion: Assertion): boolean;
+    judge(assertion: Assertion, evidence: Evidence, ctx?: Context): AssertionResult | Promise<AssertionResult>;
+}
+/** Judges evidence against assertions (mechanical, baseline, or LLM). Optional `ctx` grounds LLM judgment (e.g. the task intent); deterministic critics ignore it, so replay stays deterministic (invariant #4). */
 export interface Critic {
-    judge(evidence: Evidence, assertions: Assertion[]): Promise<Verdict>;
+    judge(evidence: Evidence, assertions: Assertion[], ctx?: Context): Promise<Verdict>;
 }
 /** Emits a result anywhere — console, json, an arbitrary tracker. */
 export interface Reporter {

package/dist/core/steps.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Execute-stage step handlers (invariant #2). The pipeline routes each Step to the first
+ * handler that `supports` it (DispatcherServlet-style) — built-in kinds and product-defined
+ * `custom` actions resolve through the same `StepHandler` seam, so adding an action means
+ * registering a handler, never editing a stage. Depends only on core ports/types.
+ */
+import type { CustomAction, Driver, StepHandler } from "./ports.js";
+import type { Step } from "./types.js";
+/** Handles cairn's built-in step vocabulary — every kind except product-defined `custom`. */
+export declare class BuiltinStepHandler implements StepHandler {
+    supports(step: Step): boolean;
+    execute(step: Step, driver: Driver): Promise<void>;
+}
+/** Handles product-defined `{ kind: "custom", name }` steps via a name→action registry. */
+export declare class CustomStepHandler implements StepHandler {
+    private readonly actions;
+    constructor(actions?: Record<string, CustomAction>);
+    supports(step: Step): boolean;
+    execute(step: Step, driver: Driver): Promise<void>;
+}
+/** The engine's default Execute-stage chain: built-ins first, then product `custom` actions. */
+export declare function defaultStepHandlers(actions?: Record<string, CustomAction>): StepHandler[];

package/dist/core/steps.js

@@ -0,0 +1,57 @@
+/** Handles cairn's built-in step vocabulary — every kind except product-defined `custom`. */
+export class BuiltinStepHandler {
+    supports(step) {
+        return step.kind !== "custom";
+    }
+    async execute(step, driver) {
+        switch (step.kind) {
+            case "goto":
+                return driver.goto(step.url);
+            case "click":
+                return driver.click(step.target);
+            case "doubleClick":
+                return driver.doubleClick(step.target);
+            case "hover":
+                return driver.hover(step.target);
+            case "type":
+                return driver.type(step.target, step.text);
+            case "select":
+                return driver.select(step.target, step.value);
+            case "pressKey":
+                return driver.pressKey(step.key);
+            case "scroll":
+                return driver.scroll(step.direction);
+            case "custom":
+                // Owned by CustomStepHandler; reaching here means a handler-ordering bug, not bad input.
+                throw new Error(`built-in handler received custom step "${step.name}"`);
+            default: {
+                // Exhaustiveness guard: a new Step kind that no case handles fails to compile here.
+                const unhandled = step;
+                throw new Error(`unhandled step kind: ${JSON.stringify(unhandled)}`);
+            }
+        }
+    }
+}
+/** Handles product-defined `{ kind: "custom", name }` steps via a name→action registry. */
+export class CustomStepHandler {
+    actions;
+    constructor(actions = {}) {
+        this.actions = actions;
+    }
+    supports(step) {
+        return step.kind === "custom";
+    }
+    async execute(step, driver) {
+        if (step.kind !== "custom")
+            throw new Error(`custom handler received "${step.kind}" step`);
+        const action = this.actions[step.name];
+        if (!action)
+            throw new Error(`no handler registered for custom action "${step.name}"`);
+        await action(driver, step.params ?? {});
+    }
+}
+/** The engine's default Execute-stage chain: built-ins first, then product `custom` actions. */
+export function defaultStepHandlers(actions = {}) {
+    return [new BuiltinStepHandler(), new CustomStepHandler(actions)];
+}
+//# sourceMappingURL=steps.js.map

package/dist/core/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/core/steps.ts"],"names":[],"mappings":"AASA,6FAA6F;AAC7F,MAAM,OAAO,kBAAkB;IAC7B,QAAQ,CAAC,IAAU;QACjB,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAU,EAAE,MAAc;QACtC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,MAAM;gBACT,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC/B,KAAK,OAAO;gBACV,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnC,KAAK,aAAa;gBAChB,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACzC,KAAK,OAAO;gBACV,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnC,KAAK,MAAM;gBACT,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7C,KAAK,QAAQ;gBACX,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAChD,KAAK,UAAU;gBACb,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACnC,KAAK,QAAQ;gBACX,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACvC,KAAK,QAAQ;gBACX,yFAAyF;gBACzF,MAAM,IAAI,KAAK,CAAC,0CAA0C,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;YAC1E,OAAO,CAAC,CAAC,CAAC;gBACR,oFAAoF;gBACpF,MAAM,SAAS,GAAU,IAAI,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YACvE,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,2FAA2F;AAC3F,MAAM,OAAO,iBAAiB;IACC;IAA7B,YAA6B,UAAwC,EAAE;QAA1C,YAAO,GAAP,OAAO,CAAmC;IAAG,CAAC;IAE3E,QAAQ,CAAC,IAAU;QACjB,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;IAChC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAU,EAAE,MAAc;QACtC,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,CAAC,IAAI,QAAQ,CAAC,CAAC;QAC3F,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACvF,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,gGAAgG;AAChG,MAAM,UAAU,mBAAmB,CAAC,UAAwC,EAAE;IAC5E,OAAO,CAAC,IAAI,kBAAkB,EAAE,EAAE,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;AACpE,CAAC"}

package/dist/core/types.d.ts

@@ -1,8 +1,6 @@
 /** Domain types for the pipeline (Context → Plan → Execute → Judge → Report). App-agnostic by invariant #1. */
 export interface Context {
     intent: string;
-    baseUrl?: string;
-    notes?: string[];
 }
 export type Step = {
     kind: "goto";

package/dist/index.d.ts

@@ -2,14 +2,15 @@
 export * from "./core/types.js";
 export * from "./core/ports.js";
 export { runHarness } from "./core/pipeline.js";
-export type { RunHarnessOptions, CustomAction } from "./core/pipeline.js";
+export type { RunHarnessOptions } from "./core/pipeline.js";
+export { BuiltinStepHandler, CustomStepHandler, defaultStepHandlers } from "./core/steps.js";
 export { runScenario, needsLlmCritic, applyHeals } from "./run.js";
 export type { RunScenarioOptions, RunScenarioResult } from "./run.js";
 export { InlineContextProvider } from "./adapters/context/inline.js";
 export { StaticPlanner } from "./adapters/planners/static.js";
-export { AssertionCritic, checkAssertion, resolveAssertion } from "./adapters/critics/assertion.js";
+export { AssertionCritic, checkAssertion, resolveAssertion, judgeAssertion, MechanicalAssertionHandler, CustomAssertionHandler, } from "./adapters/critics/assertion.js";
 export type { CustomCheck, CustomChecks } from "./adapters/critics/assertion.js";
-export { LlmCritic, summarizeEvidence } from "./adapters/critics/llm.js";
+export { LlmCritic, ExpectAssertionHandler, summarizeEvidence } from "./adapters/critics/llm.js";
 export { ConsoleReporter } from "./adapters/reporters/console.js";
 export { JsonReporter } from "./adapters/reporters/json.js";
 export { FakeDriver } from "./adapters/drivers/fake.js";

package/dist/index.js

@@ -2,11 +2,12 @@
 export * from "./core/types.js";
 export * from "./core/ports.js";
 export { runHarness } from "./core/pipeline.js";
+export { BuiltinStepHandler, CustomStepHandler, defaultStepHandlers } from "./core/steps.js";
 export { runScenario, needsLlmCritic, applyHeals } from "./run.js";
 export { InlineContextProvider } from "./adapters/context/inline.js";
 export { StaticPlanner } from "./adapters/planners/static.js";
-export { AssertionCritic, checkAssertion, resolveAssertion } from "./adapters/critics/assertion.js";
-export { LlmCritic, summarizeEvidence } from "./adapters/critics/llm.js";
+export { AssertionCritic, checkAssertion, resolveAssertion, judgeAssertion, MechanicalAssertionHandler, CustomAssertionHandler, } from "./adapters/critics/assertion.js";
+export { LlmCritic, ExpectAssertionHandler, summarizeEvidence } from "./adapters/critics/llm.js";
 export { ConsoleReporter } from "./adapters/reporters/console.js";
 export { JsonReporter } from "./adapters/reporters/json.js";
 export { FakeDriver } from "./adapters/drivers/fake.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAGnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGrF,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/run.d.ts

@@ -1,4 +1,4 @@
-import type { CustomAction } from "./core/pipeline.js";
+import type { CustomAction } from "./core/ports.js";
 import type { CustomChecks } from "./adapters/critics/assertion.js";
 import type { ContextProvider, Critic, Driver, LlmClient, Reporter } from "./core/ports.js";
 import type { Heal } from "./adapters/drivers/self-heal.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn-engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "An engine for self-healing E2E browser tests — discovered once by an AI, replayed deterministically.",
   "keywords": [
     "e2e",
@@ -29,7 +29,14 @@
     "cairn": "./dist/cli.js"
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    }
   },
   "files": [
     "dist",