Fix matrix test failures

Author: ItsMeSamey

DOCUMENTATION.md

@@ -19,16 +19,9 @@ const std = @import("std");
 const driver = @import("alldriver");
 
 pub fn run(allocator: std.mem.Allocator) !void {
-    var installs = try driver.modern.discover(allocator, .{
+    var session = try driver.modern.launchAuto(allocator, .{
         .kinds = &.{ .chrome, .firefox, .lightpanda },
         .allow_managed_download = false,
-    }, .{});
-    defer installs.deinit();
-
-    if (installs.items.len == 0) return error.NoBrowserFound;
-
-    var session = try driver.modern.launch(allocator, .{
-        .install = installs.items[0],
         .profile_mode = .ephemeral,
         .headless = true,
     });
@@ -47,10 +40,12 @@ pub fn run(allocator: std.mem.Allocator) !void {
 - `discover(...) -> BrowserInstallList`
 - `discoverWebViews(...) -> WebViewRuntimeList`
 - Caller owns the returned lists and must call `.deinit()`.
+- `launchAuto(...)` / `launchAutoAsync(...)` run discovery with sane defaults and return a fully ready session.
 
 ### Modern session domains
 
 - `page()`, `runtime()`, `network()`, `input()`, `log()`, `storage()`, `contexts()`, `targets()`
+- `launch`, `launchAuto`, `attach`, and webview attach/launch all wait for protocol readiness; no manual CDP/BiDi session bootstrap is required.
 
 ### Waits and cancellation
 

README.md

@@ -1,50 +1,36 @@
-# alldriver
+# 🚀 alldriver
 
-> Modern browser automation for Zig using CDP and BiDi.
+Modern browser automation for Zig with a CDP/BiDi-first API, deterministic discovery, and production gates.
 
-[![zig](https://img.shields.io/badge/Zig-0.15.x-orange)](#)
-[![platforms](https://img.shields.io/badge/Platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue)](#)
-[![protocols](https://img.shields.io/badge/Protocols-CDP%20%7C%20BiDi-green)](#)
+![Zig](https://img.shields.io/badge/Zig-0.15.x-f7a41d?logo=zig&logoColor=111)
+![Platforms](https://img.shields.io/badge/Platforms-Windows%20%7C%20macOS%20%7C%20Linux-2ea44f)
+![Protocols](https://img.shields.io/badge/Protocols-CDP%20%7C%20BiDi-0366d6)
+![API](https://img.shields.io/badge/API-modern-0f766e)
 
-`alldriver` is a library-first automation framework focused on real browser binaries, deterministic discovery, and typed behavior.
+## ⚡ Features
 
-## Why
+- CDP/BiDi-first modern API (`driver.modern.*`) with typed domain clients.
+- Auto-launch and auto-attach flows that wait for real protocol readiness.
+- Deterministic browser discovery (PATH + known paths + OS probes + managed cache).
+- Typed waits, cancellation tokens, lifecycle events, timeout policies, diagnostics.
+- Typed cookie query/export helpers and built-in session cache.
+- Runtime Lightpanda download/install support (no build-time dependency).
+- Production tooling: adversarial detection gate, matrix, release bundle.
 
-- CDP/BiDi-first API with typed domain clients.
-- Deterministic browser/webview discovery across desktop platforms.
-- Strong capability and error contracts (explicit unsupported behavior).
-- Built-in adversarial, matrix, and GA tooling.
-
-## Safety Boundary
-
-`alldriver` is for standards-compliant automation (testing, QA, scripting).
-It does **not** include detection-bypass/evasion primitives.
-
-## Install
-
-```bash
-zig fetch --save git+https://github.com/SmallThingz/alldriver
-```
-
-Then import in `build.zig.zon` and `build.zig` as usual for Zig dependencies.
-
-## Quick Start
+## 🚀 Quick Start
 
 ```zig
 const std = @import("std");
 const driver = @import("alldriver");
 
-pub fn run(allocator: std.mem.Allocator) !void {
-    var installs = try driver.modern.discover(allocator, .{
+pub fn main() !void {
+    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    defer _ = gpa.deinit();
+    const allocator = gpa.allocator();
+
+    var session = try driver.modern.launchAuto(allocator, .{
         .kinds = &.{ .chrome, .firefox, .lightpanda },
         .allow_managed_download = false,
-    }, .{});
-    defer installs.deinit();
-
-    if (installs.items.len == 0) return error.NoBrowserFound;
-
-    var session = try driver.modern.launch(allocator, .{
-        .install = installs.items[0],
         .profile_mode = .ephemeral,
         .headless = true,
     });
@@ -56,135 +42,140 @@ pub fn run(allocator: std.mem.Allocator) !void {
 }
 ```
 
-## API At A Glance
-
-### Discovery ownership
-
-- `discover(...) -> BrowserInstallList`
-- `discoverWebViews(...) -> WebViewRuntimeList`
-- Caller owns memory and must call `.deinit()`.
-
-### Modern session domains
+## 📦 Install
 
-- `page()`, `runtime()`, `network()`, `input()`, `log()`, `storage()`, `contexts()`, `targets()`
-
-### Waits and cancellation
-
-- `waitFor(target, opts)` + `waitForAsync(target, opts)`
-- Targets: `dom_ready`, `network_idle`, `selector_visible`, `url_contains`, `cookie_present`, `storage_key_present`, `js_truthy`
-- `CancelToken` for cooperative cancel.
-
-### Events
+```bash
+zig fetch --save git+https://github.com/SmallThingz/alldriver
+```
 
-- `onEvent(filter, callback)` / `offEvent(id)`
-- Event kinds: `navigation_started`, `navigation_completed`, `challenge_detected`, `challenge_solved`, `cookie_updated`
+Then add the dependency import in your `build.zig` as usual.
 
-### Timeouts and diagnostics
+## 🧠 API At A Glance
 
-- `setTimeoutPolicy`, `timeoutPolicy`, `lastDiagnostic`
-- `setHardErrorLogger` (global hard-error callback; defaults to stderr if unset)
+### Modern surface
 
-### Cookie helpers
+- `driver.modern.discover(...)`
+- `driver.modern.launch(...)`
+- `driver.modern.launchAuto(...)`
+- `driver.modern.attach(...)`
 
-- `queryCookies`
-- `buildCookieHeaderForUrl`
+### Session domains
 
-### Session cache
+- `session.page()`
+- `session.runtime()`
+- `session.network()`
+- `session.input()`
+- `session.log()`
+- `session.storage()`
+- `session.contexts()`
+- `session.targets()`
 
-- `SessionCacheStore.open/load/save/saveWithOptions/invalidate/cleanupExpired`
-- Payload presets:
-  - `.minimal` (cookies)
-  - `.http_session` (cookies + user agent)
-  - `.rich_state` (cookies + user agent + storage + url + extra headers)
-- Custom combinations via `SessionCachePayloadMask`.
+### Waits, cancel, events
 
-### Runtime Lightpanda Download
+- `session.waitFor(target, opts)`
+- `session.waitForAsync(target, opts)`
+- `driver.CancelToken`
+- `session.onEvent(filter, callback)` / `session.offEvent(id)`
 
-- Runtime API: `driver.lightpanda.downloadLatest(allocator, .{ .cache_dir = null, .tag = null })`
-- Tools command: `zig build tools -- download-lightpanda`
+### Timeout + diagnostics
 
-## Coverage
+- `session.setTimeoutPolicy(...)`
+- `session.timeoutPolicy()`
+- `session.lastDiagnostic()`
+- `driver.modern.setHardErrorLogger(...)`
 
-### Modern (supported)
+### Cookie/session utilities
 
-- Chromium-family browsers via CDP
-- Firefox/Gecko via BiDi
-- CDP-capable webviews: `webview2`, `electron`, `android_webview`
+- `session.storage().queryCookies(...)`
+- `session.storage().buildCookieHeaderForUrl(...)`
+- `driver.SessionCacheStore.open/load/save/saveWithOptions/invalidate/cleanupExpired`
 
-### Unsupported tier (discovered/classified, not driven)
+## 🌐 Coverage
 
-- Targets without usable CDP/BiDi surfaces on the host.
+### Modern supported
 
-## Runtime Notes
+- Chromium-family browsers via CDP.
+- Firefox/Gecko via BiDi.
+- CDP-capable webviews: `webview2`, `electron`, `android_webview`.
 
-- Launch now blocks until the local debug endpoint is reachable (bounded by launch timeout policy) to reduce race-condition `ConnectionRefused` failures in immediate post-launch actions.
-- Deprecated launch compatibility flag `legacy_automation_markers` has been removed from public options.
+### Unsupported tier
 
-## External Binary Dependencies
+- Targets without usable CDP/BiDi surfaces on the host are discovered/classified but not driven.
 
-### Core runtime
+## 💾 Managed Browser Cache
 
-- Browser binaries (at least one target installed): Chrome/Chromium, Edge, Firefox, Brave, Tor Browser, DuckDuckGo Browser, Mullvad Browser, LibreWolf, Epic, Arc, Vivaldi, SigmaOS, Sidekick, Shift, Opera GX, Pale Moon.
-- Optional Lightpanda binary can be installed at runtime via `driver.lightpanda.downloadLatest(...)` (GitHub release assets).
-- Webview/runtime binaries as applicable: `msedgewebview2`, `electron`.
-- Mobile bridge tooling: `adb`, `shizuku` (or `rish`) for Android WebView.
+When `managed_cache_dir` is unset, default paths are:
 
-Managed browser cache defaults (used when `managed_cache_dir` is unset):
 - Linux: `$XDG_CACHE_HOME/alldriver/browsers` (fallback `$HOME/.cache/alldriver/browsers`)
 - macOS: `$HOME/Library/Caches/alldriver/browsers`
 - Windows: `%LOCALAPPDATA%\\alldriver\\browsers`
 
-`discover()` always scans managed cache. `allow_managed_download` controls provisioning/download permission, not cache discovery.
+`discover()` always scans managed cache.  
+`allow_managed_download` controls whether provisioning/download is allowed.
+
+## 🐼 Lightpanda Runtime Download
 
-### Tooling / matrix / release (`zig build tools -- ...`)
+Programmatic:
 
-- Base tooling: `zig`, `git`, `bash`, `tar`, `date`, `which` (or `where` on Windows), `chmod`.
-- Signing: `gpg`.
-- Remote orchestration: `ssh`, `scp`, `rsync`.
-- VM/QEMU workflows: `qemu-system-x86_64`, `qemu-img`, `curl`, `ssh-keygen`.
-- Optional checksum verification: `sha256sum`.
+```zig
+const installed = try driver.modern.downloadLightpandaLatest(allocator, .{
+    .cache_dir = null,
+    .tag = null,
+    .expected_sha256_hex = null,
+});
+defer allocator.free(installed);
+```
+
+Tooling:
+
+```bash
+zig build tools -- download-lightpanda
+```
 
-## Common Commands
+## 🧪 Build / Test / Gates
 
 ```bash
-# Build + tests
+# core
 zig build test
 zig build examples
+zig build run
 
-# Opt-in live adversarial check for flatmates.com.au (fails on 429/challenge facade)
-ALLDRIVER_ADVERSARIAL_FLATMATES=1 zig build test --summary all
-
-# Tool self-check
+# tool sanity
 zig build tools -- self-test
 
-# Gates
+# adversarial gate
 zig build tools -- adversarial-detection-gate --allow-missing-browser=1
+
+# production gate
 zig build production-gate
 zig build tools -- production-gate --strict-ga
+```
 
-# Matrix + release
-zig build tools -- matrix-run --platform linux
-zig build tools -- matrix-collect
-zig build tools -- release-bundle --release-id v1.0.0
+## 🧰 External Binaries
 
-# Runtime browser provisioning
-zig build tools -- download-lightpanda
+### Core runtime (library users)
 
-# VM / QEMU helpers
-zig build tools -- vm-check-prereqs
-zig build tools -- vm-image-sources --check
-zig build tools -- vm-init-lab --project alldriver
-zig build tools -- vm-create-linux --project alldriver --name linux-matrix
-zig build tools -- vm-start-linux --project alldriver --name linux-matrix
-zig build tools -- vm-run-linux-matrix --project alldriver --name linux-matrix
-```
+- Browser binaries for your chosen targets (Chrome/Edge/Firefox/Brave/etc.).
+- Optional Lightpanda binary (auto-downloaded at runtime if requested).
+- Optional webview runtimes/tools when using those flows (`msedgewebview2`, `electron`, Android bridge tools such as `adb` or `shizuku`/`rish`).
+
+If you only use `discover/launch/attach` against installed desktop browsers, no additional tooling binaries are required by the library core.
+
+### Tooling/matrix/release (`zig build tools -- ...`)
+
+- `git`, `bash`, `tar`, `date`, `which`/`where`, `chmod`
+- `gpg` (sign/verify)
+- `ssh`, `scp`, `rsync` (remote matrix)
+- `qemu-system-x86_64`, `qemu-img`, `curl`, `ssh-keygen` (VM workflows)
 
-## Examples
+## 🛡 Safety Boundary
 
-See `/home/a/projects/zig/browser_driver/examples/README.md` for runnable examples.
+`alldriver` is for standards-compliant automation (QA/testing/scripting).  
+It does **not** provide built-in detection-bypass/evasion primitives.
 
-## Docs
+## 📚 Documentation
 
 - `/home/a/projects/zig/browser_driver/DOCUMENTATION.md`
+- `/home/a/projects/zig/browser_driver/examples/README.md`
 - `/home/a/projects/zig/browser_driver/CONTRIBUTING.md`
 - `/home/a/projects/zig/browser_driver/SECURITY.md`

build.zig

@@ -207,6 +207,30 @@ pub fn build(b: *std.Build) void {
     // A run step that will run the test executable.
     const run_mod_tests = b.addRunArtifact(mod_tests);
 
+    const platform_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/platform_matrix_runner.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "alldriver_config", .module = config.createModule() },
+            },
+        }),
+    });
+    const run_platform_tests = b.addRunArtifact(platform_tests);
+
+    const behavioral_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/behavioral_matrix_runner.zig"),
+            .target = target,
+            .optimize = optimize,
+            .imports = &.{
+                .{ .name = "alldriver_config", .module = config.createModule() },
+            },
+        }),
+    });
+    const run_behavioral_tests = b.addRunArtifact(behavioral_tests);
+
     // Creates an executable that will run `test` blocks from the executable's
     // root module. Note that test executables only test one module at a time,
     // hence why we have to create two separate ones.
@@ -227,6 +251,8 @@ pub fn build(b: *std.Build) void {
     // make the two of them run in parallel.
     const test_step = b.step("test", "Run tests");
     test_step.dependOn(&run_mod_tests.step);
+    test_step.dependOn(&run_platform_tests.step);
+    test_step.dependOn(&run_behavioral_tests.step);
     test_step.dependOn(&run_exe_tests.step);
     test_step.dependOn(&run_tools_tests.step);
 

examples/02_launch_and_navigate.zig

@@ -6,22 +6,11 @@ pub fn main() !void {
     defer _ = gpa_state.deinit();
     const allocator = gpa_state.allocator();
 
-    var installs = try driver.discover(allocator, .{
-        .kinds = &.{ .chrome, .edge, .firefox },
+    var launch_op = try driver.modern.launchAutoAsync(allocator, .{
+        .kinds = &.{ .chrome, .edge, .firefox, .lightpanda },
         .allow_managed_download = false,
-    }, .{});
-    defer installs.deinit();
-
-    if (installs.items.len == 0) {
-        std.debug.print("no browser install found\n", .{});
-        return;
-    }
-
-    var launch_op = try driver.modern.launchAsync(allocator, .{
-        .install = installs.items[0],
         .profile_mode = .ephemeral,
         .headless = true,
-        .args = &.{},
     });
     defer launch_op.deinit();
     var session = try launch_op.await(30_000);