@zerotal/flow 1.3.0 → 1.5.0

package/src/browser/FlowBrowser.ts

@@ -0,0 +1,270 @@
+/**
+ * Drive a real browser against a running Flow app.
+ *
+ * `FlowTest` calls actions directly, which is the right tool for a component's
+ * logic but structurally cannot fail the way production fails: it never renders
+ * an attribute, never dispatches a DOM event, and never opens the WebSocket. The
+ * bugs Flow has actually shipped all lived in that gap — a `<select>` that lost
+ * its binding, a click cancelled by `preventDefault`, an action the server
+ * refused and reported only to the browser console.
+ *
+ * `FlowBrowser` closes it. A click here is a real click, dispatched by Chrome
+ * into the page's own delegated listener, travelling over the real socket to the
+ * real dispatcher and back as a real patch. If any link in that chain is broken,
+ * the assertion fails — which is the whole point.
+ *
+ * ```ts
+ * const page = await FlowBrowser.open(`http://localhost:${port}/counter`);
+ * await page.click("#increment");
+ * await page.waitForText("#count", "1");
+ * expect(await page.consoleErrors()).toEqual([]);
+ * await page.close();
+ * ```
+ *
+ * Requires a Chrome or Edge install (or `CHROME_PATH`). Use {@link FlowBrowser.available}
+ * to skip a suite where there is no browser rather than failing it.
+ */
+import { CdpSession, findChrome, launchBrowser, type LaunchedBrowser } from "./cdp.ts";
+
+/** How long to wait for a condition driven by a server round-trip. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export interface OpenOptions {
+  /** Milliseconds to wait for the page to load and Flow to connect. */
+  timeout?: number;
+  /**
+   * Wait for Flow's WebSocket to report itself online before returning.
+   * Default: true. Set false for a page with no Flow component on it.
+   */
+  waitForConnection?: boolean;
+}
+
+export class FlowBrowser {
+  private readonly _consoleErrors: string[] = [];
+  private readonly _pageErrors: string[] = [];
+
+  private constructor(
+    private readonly _browser: LaunchedBrowser,
+    private readonly _session: CdpSession,
+  ) {}
+
+  /** Whether a browser is installed, so a suite can skip rather than fail. */
+  static available(): boolean {
+    return findChrome() !== null;
+  }
+
+  /** Launch a browser, load `url`, and wait for Flow to connect. */
+  static async open(url: string, options: OpenOptions = {}): Promise<FlowBrowser> {
+    const chrome = findChrome();
+    if (!chrome) {
+      throw new Error(
+        "No Chrome or Edge found. Install one, or set CHROME_PATH. " +
+          "Guard the suite with `FlowBrowser.available()` to skip instead.",
+      );
+    }
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    const browser = await launchBrowser(chrome);
+    const page = new FlowBrowser(browser, browser.session);
+    page._captureConsole();
+
+    const loaded = browser.session.once("Page.loadEventFired", timeout);
+    await browser.session.send("Page.navigate", { url });
+    await loaded;
+
+    if (options.waitForConnection !== false) {
+      // The bridge stamps the body when its socket opens. Waiting on that rather
+      // than on a sleep is what makes these tests deterministic: a slow boot
+      // waits longer, and a bridge that never connects fails with a clear reason
+      // instead of a mystery assertion further down.
+      await page.waitUntil(
+        `document.body.getAttribute("data-flow-connection") === "online"`,
+        "Flow to connect its WebSocket",
+        timeout,
+      );
+    }
+    return page;
+  }
+
+  /**
+   * Record console errors and uncaught exceptions.
+   *
+   * This is deliberate, not incidental. A Flow action the server refuses is
+   * reported *only* here — nothing reaches the server log and the page does not
+   * change — so a test that cannot see the console cannot see the failure. B15
+   * cost an afternoon for exactly this reason.
+   */
+  private _captureConsole(): void {
+    this._session.on("Runtime.consoleAPICalled", (params) => {
+      if (params["type"] !== "error") return;
+      const args = (params["args"] ?? []) as Array<{ value?: unknown; description?: string }>;
+      this._consoleErrors.push(args.map((a) => String(a.value ?? a.description ?? "")).join(" "));
+    });
+    this._session.on("Runtime.exceptionThrown", (params) => {
+      const details = params["exceptionDetails"] as
+        { text?: string; exception?: { description?: string } } | undefined;
+      this._pageErrors.push(details?.exception?.description ?? details?.text ?? "unknown error");
+    });
+  }
+
+  /**
+   * Navigate this browser to another URL and wait for Flow to reconnect.
+   *
+   * Reusing one browser across a suite is worth the small amount of state
+   * management: launching Chrome costs about a second, and a fresh navigation
+   * gives each test a fresh component anyway. Recorded console output is cleared
+   * so one test's errors cannot be attributed to the next.
+   */
+  async goto(url: string, options: OpenOptions = {}): Promise<void> {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this._consoleErrors.length = 0;
+    this._pageErrors.length = 0;
+
+    const loaded = this._session.once("Page.loadEventFired", timeout);
+    await this._session.send("Page.navigate", { url });
+    await loaded;
+
+    if (options.waitForConnection !== false) {
+      await this.waitUntil(
+        `document.body.getAttribute("data-flow-connection") === "online"`,
+        "Flow to connect its WebSocket",
+        timeout,
+      );
+    }
+  }
+
+  /** Evaluate an expression in the page and return its value. */
+  async evaluate<T = unknown>(expression: string): Promise<T> {
+    const res = (await this._session.send("Runtime.evaluate", {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    })) as {
+      result?: { value?: T };
+      exceptionDetails?: { text?: string; exception?: { description?: string } };
+    };
+    if (res.exceptionDetails) {
+      const detail =
+        res.exceptionDetails.exception?.description ?? res.exceptionDetails.text ?? "unknown";
+      throw new Error(`Evaluation failed: ${detail}\n  expression: ${expression}`);
+    }
+    return res.result?.value as T;
+  }
+
+  /** Poll `expression` until it is truthy. */
+  async waitUntil(
+    expression: string,
+    label: string,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  ): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    let last: unknown;
+    while (Date.now() < deadline) {
+      last = await this.evaluate(`Boolean(${expression})`);
+      if (last === true) return;
+      await Bun.sleep(40);
+    }
+    throw new Error(
+      `Timed out after ${timeoutMs}ms waiting for ${label}.\n` +
+        `  expression: ${expression}\n` +
+        `  console errors: ${this._consoleErrors.length ? this._consoleErrors.join(" | ") : "(none)"}`,
+    );
+  }
+
+  /** Wait for an element to exist. */
+  async waitForSelector(selector: string, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<void> {
+    await this.waitUntil(
+      `document.querySelector(${JSON.stringify(selector)})`,
+      `selector ${selector}`,
+      timeoutMs,
+    );
+  }
+
+  /** Wait until an element's trimmed text equals `text` — the usual post-action assertion. */
+  async waitForText(selector: string, text: string, timeoutMs = DEFAULT_TIMEOUT_MS): Promise<void> {
+    const sel = JSON.stringify(selector);
+    await this.waitUntil(
+      `(document.querySelector(${sel})?.textContent ?? "").trim() === ${JSON.stringify(text)}`,
+      `${selector} to read ${JSON.stringify(text)} (currently ` +
+        `${JSON.stringify(await this.text(selector).catch(() => null))})`,
+      timeoutMs,
+    );
+  }
+
+  /**
+   * Click an element the way a user does.
+   *
+   * Dispatched through the element's own `click()`, so it runs the page's
+   * delegated `click` listener and the browser's activation behaviour — which is
+   * what made `flow:click` on a radio detectable at all (B4b).
+   */
+  async click(selector: string): Promise<void> {
+    await this.waitForSelector(selector);
+    await this.evaluate(`document.querySelector(${JSON.stringify(selector)}).click()`);
+  }
+
+  /**
+   * Type into a `flow:model` field.
+   *
+   * Sets the value and fires a real `input` event, because that is the event the
+   * bridge listens for — assigning `.value` alone changes the DOM without ever
+   * telling Flow, which is precisely the silent failure this harness exists to
+   * catch.
+   */
+  async fill(selector: string, value: string): Promise<void> {
+    await this.waitForSelector(selector);
+    const sel = JSON.stringify(selector);
+    await this.evaluate(
+      `(() => {
+        const el = document.querySelector(${sel});
+        el.value = ${JSON.stringify(value)};
+        el.dispatchEvent(new Event("input", { bubbles: true }));
+        el.dispatchEvent(new Event("change", { bubbles: true }));
+      })()`,
+    );
+  }
+
+  /** An element's trimmed text. */
+  async text(selector: string): Promise<string> {
+    return (
+      (await this.evaluate<string>(
+        `(document.querySelector(${JSON.stringify(selector)})?.textContent ?? "").trim()`,
+      )) ?? ""
+    );
+  }
+
+  /** An element's attribute value, or null. */
+  async attr(selector: string, name: string): Promise<string | null> {
+    return await this.evaluate<string | null>(
+      `document.querySelector(${JSON.stringify(selector)})?.getAttribute(${JSON.stringify(name)}) ?? null`,
+    );
+  }
+
+  /** An input's current value. */
+  async value(selector: string): Promise<string> {
+    return (
+      (await this.evaluate<string>(
+        `document.querySelector(${JSON.stringify(selector)})?.value ?? ""`,
+      )) ?? ""
+    );
+  }
+
+  /** The page's full HTML, for diagnosing a failure. */
+  async html(): Promise<string> {
+    return await this.evaluate<string>("document.documentElement.outerHTML");
+  }
+
+  /** Console errors recorded so far — a refused action shows up here and nowhere else. */
+  consoleErrors(): string[] {
+    return [...this._consoleErrors];
+  }
+
+  /** Uncaught exceptions recorded so far. */
+  pageErrors(): string[] {
+    return [...this._pageErrors];
+  }
+
+  /** Close the page and kill the browser. */
+  async close(): Promise<void> {
+    await this._browser.close();
+  }
+}

package/src/browser/cdp.ts

@@ -0,0 +1,273 @@
+/**
+ * A minimal Chrome DevTools Protocol client, with no dependencies.
+ *
+ * Flow's failure mode has always been silence: a button that renders correctly,
+ * type-checks, compiles, and does nothing when clicked. Every such bug in two
+ * rounds of field reports lived in the WebSocket bridge — the layer between a
+ * real DOM event and the server action it should dispatch — and `FlowTest`
+ * cannot reach it, because it calls actions directly instead of letting the
+ * browser do it. The suite was deep and shaped away from where the bugs were.
+ *
+ * This is the missing layer: a real browser, a real socket, a real click.
+ *
+ * It speaks CDP over Bun's built-in WebSocket and drives a headless Chrome the
+ * runtime already has, rather than pulling in Puppeteer or Playwright — the same
+ * zero-dependency posture as the telemetry tracer and the media image driver.
+ * The protocol surface needed is small: enable two domains, navigate, evaluate.
+ */
+import { rmSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+/** Where Chrome lives, per platform. First hit wins. */
+const CHROME_PATHS: Record<string, string[]> = {
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+    "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+  ],
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  ],
+  linux: ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"],
+};
+
+/**
+ * The browser binary to drive, or `null` when none is installed.
+ *
+ * `CHROME_PATH` overrides the search, which is how CI pins a specific build.
+ * Returning `null` rather than throwing lets a suite skip itself on a machine
+ * without a browser instead of failing — a browser test that cannot run is not
+ * the same as one that failed.
+ */
+export function findChrome(): string | null {
+  const override = Bun.env["CHROME_PATH"];
+  if (override) return override;
+  for (const candidate of CHROME_PATHS[process.platform] ?? []) {
+    try {
+      if (Bun.file(candidate).size > 0) return candidate;
+    } catch {
+      /* not here — keep looking */
+    }
+  }
+  return null;
+}
+
+interface CdpMessage {
+  id?: number;
+  method?: string;
+  params?: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  error?: { message: string };
+}
+
+/**
+ * One CDP connection to one page target.
+ *
+ * Requests are correlated by the `id` field the protocol echoes back, so several
+ * can be in flight; events (no `id`) are dispatched to listeners.
+ */
+export class CdpSession {
+  private _nextId = 1;
+  private readonly _pending = new Map<
+    number,
+    { resolve: (v: Record<string, unknown>) => void; reject: (e: Error) => void }
+  >();
+  private readonly _listeners = new Map<string, Array<(params: Record<string, unknown>) => void>>();
+
+  private constructor(private readonly _ws: WebSocket) {}
+
+  static async connect(wsUrl: string, timeoutMs = 10_000): Promise<CdpSession> {
+    const ws = new WebSocket(wsUrl);
+    const session = new CdpSession(ws);
+
+    ws.addEventListener("message", (event: MessageEvent) => {
+      let msg: CdpMessage;
+      try {
+        msg = JSON.parse(String(event.data)) as CdpMessage;
+      } catch {
+        return;
+      }
+      if (typeof msg.id === "number") {
+        const pending = session._pending.get(msg.id);
+        if (!pending) return;
+        session._pending.delete(msg.id);
+        if (msg.error) pending.reject(new Error(msg.error.message));
+        else pending.resolve(msg.result ?? {});
+        return;
+      }
+      if (msg.method) {
+        for (const fn of session._listeners.get(msg.method) ?? []) fn(msg.params ?? {});
+      }
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("CDP connect timed out")), timeoutMs);
+      ws.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      ws.addEventListener("error", () => {
+        clearTimeout(timer);
+        reject(new Error("CDP socket error"));
+      });
+    });
+
+    return session;
+  }
+
+  /** Issue a command and await its result. */
+  send(method: string, params: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
+    const id = this._nextId++;
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      this._ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  /** Subscribe to a protocol event. */
+  on(method: string, fn: (params: Record<string, unknown>) => void): void {
+    const list = this._listeners.get(method) ?? [];
+    list.push(fn);
+    this._listeners.set(method, list);
+  }
+
+  /** Resolve once `method` fires, or reject on timeout. */
+  once(method: string, timeoutMs = 10_000): Promise<Record<string, unknown>> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error(`timed out waiting for ${method}`)),
+        timeoutMs,
+      );
+      this.on(method, (params) => {
+        clearTimeout(timer);
+        resolve(params);
+      });
+    });
+  }
+
+  close(): void {
+    try {
+      this._ws.close();
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+/** A launched browser process plus the endpoint to talk to it. */
+export interface LaunchedBrowser {
+  session: CdpSession;
+  close(): Promise<void>;
+}
+
+/** Poll `fn` until it returns a value, or throw after `timeoutMs`. */
+async function poll<T>(fn: () => Promise<T | null>, timeoutMs: number, label: string): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const value = await fn();
+    if (value !== null) return value;
+    await Bun.sleep(50);
+  }
+  throw new Error(`timed out waiting for ${label}`);
+}
+
+/**
+ * Launch headless Chrome and attach to its first page target.
+ *
+ * Port 0 lets the OS pick, and Chrome writes the chosen port into
+ * `DevToolsActivePort` in the profile directory — polling that file is more
+ * reliable than parsing stderr, which differs between Chrome and Edge builds.
+ */
+export async function launchBrowser(chromePath: string): Promise<LaunchedBrowser> {
+  const profile = join(tmpdir(), `zt-flow-cdp-${Math.random().toString(36).slice(2)}`);
+  const proc = Bun.spawn(
+    [
+      chromePath,
+      "--headless=new",
+      "--remote-debugging-port=0",
+      `--user-data-dir=${profile}`,
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-gpu",
+      "--disable-dev-shm-usage",
+      // A sandboxed renderer cannot start as root in most CI images.
+      "--no-sandbox",
+      "about:blank",
+    ],
+    { stdout: "ignore", stderr: "ignore" },
+  );
+
+  const cleanup = async (): Promise<void> => {
+    try {
+      proc.kill();
+      await proc.exited;
+    } catch {
+      /* already dead */
+    }
+
+    // `proc.exited` resolving does not mean Windows has released the profile
+    // directory: Chrome's child processes linger briefly with open handles, and
+    // `rm` on a locked directory throws EBUSY. That surfaced as a browser test
+    // failing roughly half the time, in cleanup, long after the assertions had
+    // passed. Retry, then give up — a leftover directory under the OS temp path
+    // is not worth failing a closed session over.
+    try {
+      rmSync(profile, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+    } catch {
+      /* still locked — the OS reclaims it with the rest of temp */
+    }
+  };
+
+  try {
+    const port = await poll(
+      async () => {
+        try {
+          const text = await readFile(join(profile, "DevToolsActivePort"), "utf8");
+          const first = text.split("\n")[0]?.trim();
+          return first && /^\d+$/.test(first) ? first : null;
+        } catch {
+          return null;
+        }
+      },
+      60_000,
+      "Chrome to report its debugging port",
+    );
+
+    // The first page target is the `about:blank` tab we asked for.
+    const wsUrl = await poll(
+      async () => {
+        try {
+          const res = await fetch(`http://127.0.0.1:${port}/json/list`);
+          const targets = (await res.json()) as Array<{
+            type: string;
+            webSocketDebuggerUrl?: string;
+          }>;
+          return targets.find((t) => t.type === "page")?.webSocketDebuggerUrl ?? null;
+        } catch {
+          return null;
+        }
+      },
+      60_000,
+      "a page target",
+    );
+
+    const session = await CdpSession.connect(wsUrl);
+    await session.send("Page.enable");
+    await session.send("Runtime.enable");
+
+    return {
+      session,
+      close: async () => {
+        session.close();
+        await cleanup();
+      },
+    };
+  } catch (err) {
+    await cleanup();
+    throw err;
+  }
+}

package/src/browser/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@zerotal/flow/browser` — drive a real browser against a running Flow app.
+ *
+ * The counterpart to `@zerotal/flow/testing`. `FlowTest` exercises a component's
+ * logic by calling its actions directly; `FlowBrowser` exercises everything
+ * between a user's click and that action — the rendered attribute, the delegated
+ * listener, the WebSocket frame, the patch that comes back. Flow's silent
+ * failures have all lived in that gap, so the two are complementary rather than
+ * alternatives: unit-test behaviour with `FlowTest`, and pin the wiring with a
+ * handful of `FlowBrowser` tests.
+ *
+ * Needs a Chrome or Edge install (or `CHROME_PATH`). Guard a suite with
+ * {@link FlowBrowser.available} so it skips, rather than fails, without one.
+ *
+ * @packageDocumentation
+ */
+export { FlowBrowser } from "./FlowBrowser.ts";
+export type { OpenOptions } from "./FlowBrowser.ts";
+export { findChrome } from "./cdp.ts";

package/src/client/FlowComponent.ts

@@ -1,6 +1,6 @@
 // ── Client-side component state model ────────────────────────────────────────
 //
-// Mirrors Livewire v3's three-copy state model:
+// A three-copy state model:
 //   canonical  — last confirmed server state (used for diffing)
 //   ephemeral  — current local state (may have unsent mutations from flow:model)
 //   reactive   — Alpine.reactive(ephemeral) — what DOM expressions read