cbrowser 18.69.3 → 18.71.0

package/dist/recording/types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Recording manifest contract.
+ *
+ * The manifest is the single artifact that describes a recording run: how it
+ * was captured, what was captured, and every frame that made it into the
+ * output. Encoders, the CLI, and any downstream consumer read this file rather
+ * than re-deriving state from the frame directory.
+ *
+ * Schemas are zod v4; every exported TS type is inferred from its schema so the
+ * runtime contract and the compile-time contract cannot drift.
+ */
+import { z } from "zod";
+/** Manifest format version emitted by this build. */
+export declare const MANIFEST_VERSION = 1;
+export declare const EngineSchema: z.ZodEnum<{
+    chromium: "chromium";
+    firefox: "firefox";
+    webkit: "webkit";
+}>;
+export declare const CaptureMethodSchema: z.ZodEnum<{
+    "cdp-screencast": "cdp-screencast";
+    "screenshot-loop": "screenshot-loop";
+}>;
+export declare const ViewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    deviceScaleFactor: z.ZodNumber;
+}, z.core.$strip>;
+export declare const RectSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export declare const DimsSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * What the recorder was pointed at. Discriminated on `kind` so encoders can
+ * switch exhaustively without guessing from the presence of optional fields.
+ */
+export declare const TargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"viewport">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"region">;
+    rect: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"element">;
+    selector: z.ZodString;
+    padding: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+/**
+ * Console and network records are kept deliberately permissive: the recorder
+ * owns their exact shape and may attach engine-specific extras. Only the fields
+ * the encoders and reports actually read are required; unknown keys survive
+ * parsing untouched.
+ */
+export declare const ConsoleEntrySchema: z.ZodObject<{
+    t_ms: z.ZodNumber;
+    type: z.ZodString;
+    text: z.ZodString;
+}, z.core.$loose>;
+export declare const NetworkEntrySchema: z.ZodObject<{
+    t_ms: z.ZodNumber;
+    url: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    failed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const FrameSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    t_ms: z.ZodNumber;
+    path: z.ZodString;
+    crop: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    ssim_prev: z.ZodNullable<z.ZodNumber>;
+    anomaly: z.ZodBoolean;
+    tracking: z.ZodNullable<z.ZodEnum<{
+        ok: "ok";
+        stale: "stale";
+    }>>;
+    console: z.ZodArray<z.ZodObject<{
+        t_ms: z.ZodNumber;
+        type: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$loose>>;
+    network: z.ZodArray<z.ZodObject<{
+        t_ms: z.ZodNumber;
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        failed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export declare const FrameGapSchema: z.ZodObject<{
+    after_index: z.ZodNumber;
+    gap_ms: z.ZodNumber;
+}, z.core.$strip>;
+export declare const RecordingManifestSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    slug: z.ZodString;
+    engine: z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>;
+    capture_method: z.ZodEnum<{
+        "cdp-screencast": "cdp-screencast";
+        "screenshot-loop": "screenshot-loop";
+    }>;
+    target_fps: z.ZodNumber;
+    actual_fps: z.ZodNumber;
+    viewport: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        deviceScaleFactor: z.ZodNumber;
+    }, z.core.$strip>;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"viewport">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"region">;
+        rect: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"element">;
+        selector: z.ZodString;
+        padding: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    start_trigger: z.ZodNullable<z.ZodString>;
+    stop_trigger: z.ZodNullable<z.ZodString>;
+    trigger_timeout: z.ZodBoolean;
+    started_at: z.ZodString;
+    duration_ms: z.ZodNumber;
+    output_dims: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    frames: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        t_ms: z.ZodNumber;
+        path: z.ZodString;
+        crop: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        ssim_prev: z.ZodNullable<z.ZodNumber>;
+        anomaly: z.ZodBoolean;
+        tracking: z.ZodNullable<z.ZodEnum<{
+            ok: "ok";
+            stale: "stale";
+        }>>;
+        console: z.ZodArray<z.ZodObject<{
+            t_ms: z.ZodNumber;
+            type: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$loose>>;
+        network: z.ZodArray<z.ZodObject<{
+            t_ms: z.ZodNumber;
+            url: z.ZodString;
+            method: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodNumber>;
+            failed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$strip>>;
+    change_points: z.ZodArray<z.ZodNumber>;
+    frame_gaps: z.ZodArray<z.ZodObject<{
+        after_index: z.ZodNumber;
+        gap_ms: z.ZodNumber;
+    }, z.core.$strip>>;
+    region_clamped: z.ZodOptional<z.ZodBoolean>;
+    artifacts: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export type Engine = z.infer<typeof EngineSchema>;
+export type CaptureMethod = z.infer<typeof CaptureMethodSchema>;
+export type Viewport = z.infer<typeof ViewportSchema>;
+export type Rect = z.infer<typeof RectSchema>;
+export type Dims = z.infer<typeof DimsSchema>;
+export type RecordingTarget = z.infer<typeof TargetSchema>;
+export type ConsoleEntry = z.infer<typeof ConsoleEntrySchema>;
+export type NetworkEntry = z.infer<typeof NetworkEntrySchema>;
+export type Frame = z.infer<typeof FrameSchema>;
+export type FrameGap = z.infer<typeof FrameGapSchema>;
+export type RecordingManifest = z.infer<typeof RecordingManifestSchema>;
+/**
+ * Parse and validate a manifest.
+ *
+ * Accepts an already-parsed object or a raw JSON string. Throws an `Error`
+ * whose message lists every failing path, so a malformed manifest reports all
+ * of its problems at once instead of one per run.
+ */
+export declare function parseManifest(input: unknown): RecordingManifest;
+//# sourceMappingURL=types.d.ts.map

package/dist/recording/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/recording/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAMlC,eAAO,MAAM,YAAY;;;;EAA4C,CAAC;AAEtE,eAAO,MAAM,mBAAmB;;;EAAgD,CAAC;AAEjF,eAAO,MAAM,cAAc;;;;iBAIzB,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;iBAKrB,CAAC;AAEH,eAAO,MAAM,UAAU;;;iBAGrB,CAAC;AAMH;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;2BAQvB,CAAC;AAMH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;iBAMrB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;;;;iBAQrB,CAAC;AAMX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBtB,CAAC;AAEH,eAAO,MAAM,cAAc;;;iBAIzB,CAAC;AAMH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6BlC,CAAC;AAMH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAChD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAsB/D"}

package/dist/recording/types.js

@@ -0,0 +1,171 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Recording manifest contract.
+ *
+ * The manifest is the single artifact that describes a recording run: how it
+ * was captured, what was captured, and every frame that made it into the
+ * output. Encoders, the CLI, and any downstream consumer read this file rather
+ * than re-deriving state from the frame directory.
+ *
+ * Schemas are zod v4; every exported TS type is inferred from its schema so the
+ * runtime contract and the compile-time contract cannot drift.
+ */
+import { z } from "zod";
+/** Manifest format version emitted by this build. */
+export const MANIFEST_VERSION = 1;
+// ============================================================================
+// Primitives
+// ============================================================================
+export const EngineSchema = z.enum(["chromium", "firefox", "webkit"]);
+export const CaptureMethodSchema = z.enum(["cdp-screencast", "screenshot-loop"]);
+export const ViewportSchema = z.object({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    deviceScaleFactor: z.number().positive(),
+});
+export const RectSchema = z.object({
+    x: z.number(),
+    y: z.number(),
+    width: z.number().positive(),
+    height: z.number().positive(),
+});
+export const DimsSchema = z.object({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+});
+// ============================================================================
+// Capture target
+// ============================================================================
+/**
+ * What the recorder was pointed at. Discriminated on `kind` so encoders can
+ * switch exhaustively without guessing from the presence of optional fields.
+ */
+export const TargetSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("viewport") }),
+    z.object({ kind: z.literal("region"), rect: RectSchema }),
+    z.object({
+        kind: z.literal("element"),
+        selector: z.string().min(1),
+        padding: z.number().nonnegative(),
+    }),
+]);
+// ============================================================================
+// Per-frame side-channel records
+// ============================================================================
+/**
+ * Console and network records are kept deliberately permissive: the recorder
+ * owns their exact shape and may attach engine-specific extras. Only the fields
+ * the encoders and reports actually read are required; unknown keys survive
+ * parsing untouched.
+ */
+export const ConsoleEntrySchema = z
+    .object({
+    t_ms: z.number().nonnegative(),
+    type: z.string(),
+    text: z.string(),
+})
+    .loose();
+export const NetworkEntrySchema = z
+    .object({
+    t_ms: z.number().nonnegative(),
+    url: z.string(),
+    method: z.string().optional(),
+    status: z.number().int().optional(),
+    failed: z.boolean().optional(),
+})
+    .loose();
+// ============================================================================
+// Frames
+// ============================================================================
+export const FrameSchema = z.object({
+    /** Position in the frame sequence, 0-based and dense. */
+    index: z.number().int().nonnegative(),
+    /** Milliseconds since `started_at`. Non-decreasing across the sequence. */
+    t_ms: z.number().nonnegative(),
+    /** Path to the frame image, relative to the manifest. */
+    path: z.string().min(1),
+    /** Source-image crop this frame was cut from (post-clamp). */
+    crop: RectSchema,
+    /** SSIM against the previous frame; null for frame 0 or when not computed. */
+    ssim_prev: z.number().nullable(),
+    /** Frame flagged as a visual anomaly by the change detector. */
+    anomaly: z.boolean(),
+    /** Element-tracking state for element targets; null when not tracking. */
+    tracking: z.enum(["ok", "stale"]).nullable(),
+    console: z.array(ConsoleEntrySchema),
+    network: z.array(NetworkEntrySchema),
+});
+export const FrameGapSchema = z.object({
+    /** Gap occurred between this frame index and the next one. */
+    after_index: z.number().int().nonnegative(),
+    gap_ms: z.number().positive(),
+});
+// ============================================================================
+// Manifest
+// ============================================================================
+export const RecordingManifestSchema = z.object({
+    version: z.number().int().positive(),
+    slug: z.string().min(1),
+    engine: EngineSchema,
+    capture_method: CaptureMethodSchema,
+    /** Frame rate requested by the caller. */
+    target_fps: z.number().positive(),
+    /** Frame rate actually achieved: frames / (duration_ms / 1000). */
+    actual_fps: z.number().nonnegative(),
+    viewport: ViewportSchema,
+    target: TargetSchema,
+    /** Trigger that started capture; null when capture started immediately. */
+    start_trigger: z.string().nullable(),
+    /** Trigger that stopped capture; null when capture ran to a fixed duration. */
+    stop_trigger: z.string().nullable(),
+    /** True when capture ended because a trigger timed out rather than fired. */
+    trigger_timeout: z.boolean(),
+    /** ISO-8601 timestamp of the first frame. */
+    started_at: z.string().min(1),
+    duration_ms: z.number().nonnegative(),
+    output_dims: DimsSchema,
+    frames: z.array(FrameSchema),
+    /** Frame indices where SSIM dropped below the change threshold. */
+    change_points: z.array(z.number().int().nonnegative()),
+    frame_gaps: z.array(FrameGapSchema),
+    /** Present when a region/element rect had to be clamped into the viewport. */
+    region_clamped: z.boolean().optional(),
+    /** Output format ("gif", "webp", "mp4", ...) to artifact path. */
+    artifacts: z.record(z.string(), z.string()),
+});
+// ============================================================================
+// Parsing
+// ============================================================================
+/**
+ * Parse and validate a manifest.
+ *
+ * Accepts an already-parsed object or a raw JSON string. Throws an `Error`
+ * whose message lists every failing path, so a malformed manifest reports all
+ * of its problems at once instead of one per run.
+ */
+export function parseManifest(input) {
+    let candidate = input;
+    if (typeof candidate === "string") {
+        try {
+            candidate = JSON.parse(candidate);
+        }
+        catch (e) {
+            throw new Error(`Invalid recording manifest: not valid JSON (${e.message})`);
+        }
+    }
+    const result = RecordingManifestSchema.safeParse(candidate);
+    if (result.success)
+        return result.data;
+    const details = result.error.issues
+        .map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+        return `  - ${path}: ${issue.message}`;
+    })
+        .join("\n");
+    throw new Error(`Invalid recording manifest:\n${details}`);
+}
+//# sourceMappingURL=types.js.map

package/dist/recording/types.js.map

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

package/dist/testing/nl-test-suite.d.ts

@@ -3,6 +3,7 @@
  * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
  * Learn more at https://cbrowser.ai - MIT License
  */
+import { type AutoCaptureSetting } from "../recording/auto-capture.js";
 import type { NLTestStep, NLTestCase, NLTestSuiteResult } from "../types.js";
 /**
  * Parse a single natural language instruction into an NLTestStep.
@@ -12,7 +13,9 @@ import type { NLTestStep, NLTestCase, NLTestSuiteResult } from "../types.js";
  * - "click [the] <target>" / "press <target>"
  * - "type '<value>' in[to] <target>" / "fill <target> with '<value>'"
  * - "select '<option>' from <dropdown>"
- * - "scroll down/up"
+ * - "scroll down/up [N times | N pixels]" / "scroll to [the] top/bottom [of the page]"
+ * - "set cookie <name> to <value>" (applies to the current page's origin — navigate first)
+ * - "tap at <x>,<y>" / "click at <x>,<y>" (real pointer events at viewport coordinates)
  * - "wait [for] <seconds> seconds"
  * - "wait for content" / "wait for page to load" / "wait for page ready" (v16.7.1)
  * - "wait for '<text>' appears" / "wait for <element> to appear" (v16.7.1)
@@ -55,6 +58,15 @@ export interface NLTestSuiteOptions {
     headless?: boolean;
     /** Use fuzzy matching for text assertions */
     fuzzyMatch?: boolean;
+    /**
+     * Record the run to GIF/WebP/video (v18.70.0).
+     *
+     * `true` uses defaults; pass an options object to set fps, formats or output
+     * directory. The capture starts once the browser is up and stops before it
+     * closes, so no separate capture_start/capture_stop call is needed. Capture
+     * failures never fail the suite — they are reported on `result.capture.error`.
+     */
+    capture?: AutoCaptureSetting;
 }
 /**
  * Dry-run a test suite: parse all instructions and return without executing.

package/dist/testing/nl-test-suite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nl-test-suite.d.ts","sourceRoot":"","sources":["../../src/testing/nl-test-suite.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EAIV,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAqKlE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAwB,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,CA0CvC;AAED,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kCAAkC;IAClC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mBAAmB;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAqED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAQvE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,EAC5C,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAoR5B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAyFpE;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAU5B"}
+{"version":3,"file":"nl-test-suite.d.ts","sourceRoot":"","sources":["../../src/testing/nl-test-suite.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EAIV,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAmMlE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAwB,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,CA0CvC;AAED,MAAM,WAAW,kBAAkB;IACjC,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kCAAkC;IAClC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mBAAmB;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAqED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAA;CAAE,CAQvE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,UAAU,EAAE,CAAA;CAAE,EAC5C,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAoV5B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAyFpE;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAU5B"}

package/dist/testing/nl-test-suite.js

@@ -5,6 +5,7 @@
  */
 import { existsSync, readFileSync } from "fs";
 import { CBrowser } from "../browser.js";
+import { finishAutoCapture, resolveCaptureOptions, startAutoCapture, } from "../recording/auto-capture.js";
 /**
  * Parse a single natural language instruction into an NLTestStep.
  *
@@ -13,7 +14,9 @@ import { CBrowser } from "../browser.js";
  * - "click [the] <target>" / "press <target>"
  * - "type '<value>' in[to] <target>" / "fill <target> with '<value>'"
  * - "select '<option>' from <dropdown>"
- * - "scroll down/up"
+ * - "scroll down/up [N times | N pixels]" / "scroll to [the] top/bottom [of the page]"
+ * - "set cookie <name> to <value>" (applies to the current page's origin — navigate first)
+ * - "tap at <x>,<y>" / "click at <x>,<y>" (real pointer events at viewport coordinates)
  * - "wait [for] <seconds> seconds"
  * - "wait for content" / "wait for page to load" / "wait for page ready" (v16.7.1)
  * - "wait for '<text>' appears" / "wait for <element> to appear" (v16.7.1)
@@ -35,6 +38,15 @@ export function parseNLInstruction(instruction) {
             target: originalMatch ? originalMatch[1].trim() : navigateMatch[1].trim(),
         };
     }
+    // Coordinate tap MUST parse before the generic click pattern (which would swallow it)
+    const tapAtMatch = lower.match(/^(?:tap|click)\s+at\s+(\d+)\s*[,x]\s*(\d+)$/i);
+    if (tapAtMatch) {
+        return {
+            instruction,
+            action: "click",
+            target: `at:${tapAtMatch[1]},${tapAtMatch[2]}`,
+        };
+    }
     // Click patterns - preserve original case for target
     const clickMatch = lower.match(/^(?:click|tap|press)\s+(?:on\s+)?(?:the\s+)?(.+)$/i);
     if (clickMatch) {
@@ -79,13 +91,32 @@ export function parseNLInstruction(instruction) {
         };
     }
     // Scroll patterns
-    const scrollMatch = lower.match(/^scroll\s+(up|down|left|right)(?:\s+(\d+)\s+(?:times|pixels))?$/i);
+    const scrollToMatch = lower.match(/^scroll\s+to\s+(?:the\s+)?(top|bottom)(?:\s+of\s+the\s+page)?$/i);
+    if (scrollToMatch) {
+        return {
+            instruction,
+            action: "scroll",
+            target: scrollToMatch[1],
+        };
+    }
+    const scrollMatch = lower.match(/^scroll\s+(up|down|left|right)(?:\s+(\d+)\s+(times|pixels))?$/i);
     if (scrollMatch) {
         return {
             instruction,
             action: "scroll",
             target: scrollMatch[1],
-            value: scrollMatch[2] || "3",
+            value: scrollMatch[2] || "1",
+            unit: scrollMatch[3] || "times",
+        };
+    }
+    // Cookie pattern — "set cookie NAME to VALUE" (value from the ORIGINAL string to preserve case)
+    const cookieMatch = trimmed.match(/^set\s+cookie\s+(\S+)\s+to\s+(.+)$/i);
+    if (cookieMatch) {
+        return {
+            instruction,
+            action: "cookie",
+            target: cookieMatch[1],
+            value: cookieMatch[2].trim(),
         };
     }
     // Wait patterns
@@ -303,7 +334,7 @@ export function dryRunNLTestSuite(suite) {
  * Run a natural language test suite.
  */
 export async function runNLTestSuite(suite, options = {}) {
-    const { stepTimeout = 30000, continueOnFailure = true, screenshotOnFailure = true, headless = true, fuzzyMatch = false, } = options;
+    const { stepTimeout = 30000, continueOnFailure = true, screenshotOnFailure = true, headless = true, fuzzyMatch = false, capture, } = options;
     const startTime = Date.now();
     const testResults = [];
     console.log(`\n🧪 Running Test Suite: ${suite.name}`);
@@ -315,8 +346,15 @@ export async function runNLTestSuite(suite, options = {}) {
     const browser = new CBrowser({
         headless,
     });
+    let captureResult;
+    let captureSession = null;
     try {
         await browser.launch();
+        // Auto-capture (v18.70.0): starts here so the recording covers every test
+        // in the suite, and stops in the finally below before the browser closes.
+        captureSession = await startAutoCapture(await browser.getPage(), capture, `suite-${suite.name.replace(/[^a-zA-Z0-9-_]+/g, "-").toLowerCase()}-${Date.now()}`);
+        if (captureSession)
+            console.log(`   🎥 Capturing to ${captureSession.status().outDir}`);
         for (const test of suite.tests) {
             console.log(`\n📋 Test: ${test.name}`);
             const testStartTime = Date.now();
@@ -338,6 +376,18 @@ export async function runNLTestSuite(suite, options = {}) {
                             break;
                         }
                         case "click": {
+                            const coordTarget = (step.target || "").match(/^at:(\d+),(\d+)$/);
+                            if (coordTarget) {
+                                const page = browser.page;
+                                if (page) {
+                                    const x = parseInt(coordTarget[1], 10);
+                                    const y = parseInt(coordTarget[2], 10);
+                                    await page.mouse.move(x, y);
+                                    await page.mouse.down();
+                                    await page.mouse.up();
+                                }
+                                break;
+                            }
                             const result = await browser.smartClick(step.target || "");
                             if (!result.success) {
                                 throw new Error(`Failed to click: ${step.target}`);
@@ -353,11 +403,42 @@ export async function runNLTestSuite(suite, options = {}) {
                             break;
                         }
                         case "scroll": {
-                            const direction = step.target?.toLowerCase() === "up" ? -500 : 500;
                             const page = browser.page;
                             if (page) {
-                                await page.evaluate((d) => window.scrollBy(0, d), direction);
+                                const target = step.target?.toLowerCase();
+                                if (target === "top" || target === "bottom") {
+                                    await page.evaluate((t) => {
+                                        window.scrollTo(0, t === "bottom" ? document.documentElement.scrollHeight : 0);
+                                    }, target);
+                                }
+                                else {
+                                    const sign = target === "up" ? -1 : 1;
+                                    const n = parseInt(step.value || "1", 10) || 1;
+                                    const delta = sign * (step.unit === "pixels" ? n : n * 500);
+                                    await page.evaluate((d) => window.scrollBy(0, d), delta);
+                                }
+                            }
+                            break;
+                        }
+                        case "cookie": {
+                            const page = browser.page;
+                            if (!page || !step.target) {
+                                throw new Error(`Cookie step could not run (page=${!!page}, name=${step.target ?? "<missing>"}) — navigate before setting cookies`);
+                            }
+                            // A site-set cookie of the same name (often dot-domain, e.g. an anon PHP
+                            // session) would otherwise COEXIST with ours (host-only vs dot-domain are
+                            // distinct identities) and win first-occurrence parsing server-side.
+                            // Clear same-name cookies first so this is a true replacement.
+                            const host = new URL(page.url()).hostname;
+                            try {
+                                await page.context().clearCookies({ name: step.target });
+                            }
+                            catch {
+                                /* clearCookies filters unsupported on old Playwright — best effort */
                             }
+                            await page.context().addCookies([
+                                { name: step.target, value: step.value || "", domain: host, path: "/" },
+                            ]);
                             break;
                         }
                         case "wait": {
@@ -519,6 +600,9 @@ export async function runNLTestSuite(suite, options = {}) {
         }
     }
     finally {
+        // Stop before the browser closes — the page has to still exist. Bounded, so
+        // a wedged recorder cannot hang the suite (see finishAutoCapture).
+        captureResult = await finishAutoCapture(captureSession, resolveCaptureOptions(capture)?.stopTimeoutMs);
         await browser.close();
     }
     const passed = testResults.filter(t => t.passed).length;
@@ -553,6 +637,7 @@ export async function runNLTestSuite(suite, options = {}) {
             stepPassRate,
         },
         recommendations: recommendations.length > 0 ? recommendations : undefined,
+        ...(captureResult ? { capture: captureResult } : {}),
     };
     return result;
 }