@venn-lang/browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @venn-lang/browser
+
+> The `browser` namespace: sixteen verbs that drive a page, plus two element matchers and the ports the driving actually goes through.
+
+Venn's grammar knows nothing about browsers. This package adds the vocabulary: `browser.visit`, `browser.click`, `browser.fill` and the rest arrive as a plugin, exactly the way a third-party package would add them. None of them touch a browser directly. Every verb calls a `BrowserDriver`, a port with two implementations, so a flow can run against a real engine or against a deterministic in-memory model with the same source unchanged.
+
+## Install
+
+Nothing to install: the plugin ships inside the CLI's stdlib. Declare it in the file that needs it, and the runner loads it.
+
+```ruby
+use "venn/browser"
+use "venn/browser" as web   # or under an alias
+```
+
+## Usage
+
+```ruby
+module demo.signin
+
+use "venn/browser"
+use "venn/assert"
+
+flow "Sign in" {
+  step "open the app" {
+    const page = browser.newContext { viewport: { width: 1280, height: 800 } }
+    browser.visit "/login"
+    browser.fill "#email" "ada@example.test"
+    browser.fill "#password" "hunter2"
+    browser.click "button[type=submit]"
+    browser.waitFor { text: "Welcome back" }
+    browser.waitForUrl "/dashboard"
+
+    const shot = browser.screenshot "after-login"
+    expect shot.name == "after-login"
+    expect page.url != null
+  }
+}
+```
+
+`venn test` runs this offline against the fake driver the stdlib binds by default.
+
+## Verbs
+
+The namespace is `browser`. Positional arguments come first, the options map last.
+
+| Verb | Gives back |
+| --- | --- |
+| `browser.launch { engine, headless }` | `browser.Browser` |
+| `browser.newContext { locale, viewport }` | `browser.Page` |
+| `browser.visit "url" { headers }` | nothing |
+| `browser.click "selector"` | nothing |
+| `browser.fill "selector" "value"` | nothing |
+| `browser.select "selector" "value"` | nothing |
+| `browser.hover "selector"` | nothing |
+| `browser.press "key"` | nothing |
+| `browser.upload "selector" { file }` | nothing |
+| `browser.download "selector"` | `browser.Download` |
+| `browser.screenshot "name"` | `browser.Screenshot` |
+| `browser.waitFor { text, selector, timeout }` | nothing |
+| `browser.waitForUrl "url"` | nothing |
+| `browser.evaluate "script"` | whatever the script returned |
+| `browser.frame "name"` | nothing |
+| `browser.clearCookies` | nothing |
+
+`press` takes one argument or two. With one, it is the key and the page has focus. With two, the first is the selector to focus and the second is the key: `browser.press "#email" "Control+A"`.
+
+`select` matches the option's value, not its label. `waitFor` takes its condition as options, so the wait is `browser.waitFor { text: "Welcome back" }`, never a bare argument. Its `timeout` is written as a string or as a number of milliseconds (`{ timeout: "5s" }`, `{ timeout: 5000 }`); a bare duration literal is not accepted there in this build.
+
+## Types and matchers
+
+The plugin publishes five names under `browser.`:
+
+| Type | Shape |
+| --- | --- |
+| `browser.Browser` | opaque handle carrying `id` and `engine` |
+| `browser.Page` | opaque handle carrying `id` and `url` |
+| `browser.Element` | `{ visible, text, value }`, open |
+| `browser.Download` | `{ path, bytes }` |
+| `browser.Screenshot` | `{ name, path }` |
+
+`Browser` and `Page` stay opaque because they are live things owned by the driver. `Download` and `Screenshot` are plain data the verbs hand back, so a flow reads their fields.
+
+Two matchers apply to an `Element` subject: `visible` passes when the element model says it is visible, and `text` passes when the element's text equals or contains the argument.
+
+The plugin also declares two resources, `Browser` (worker scope) and `Page` (flow scope). The runtime does not execute `resource` declarations yet, so they describe the surface rather than open anything.
+
+## Ports
+
+Two ports, both with a real implementation and a double, which is the condition for being a port at all.
+
+### `BrowserDriverPort`
+
+`venn.port.browser-driver`, contract version 1, requires the `net` capability. Sixteen methods, one per verb. Every action reaches it through `ctx.port(BrowserDriverPort)`, so a verb never knows which engine is underneath.
+
+| Implementation | What it is |
+| --- | --- |
+| `createFakeBrowserDriver(options?)` | A deterministic, offline driver over an in-memory DOM model. Preload elements and a starting URL; read back `state` and `element(selector)`. |
+| `createRealBrowserDriver()` | The real-engine stub. Every method throws `VN8090`, because engine automation is out of scope for the language repository. |
+
+```ts
+import { createFakeBrowserDriver } from "@venn-lang/browser";
+
+const driver = createFakeBrowserDriver({ elements: { "#email": { visible: true } } });
+await driver.visit({ url: "/dashboard" });
+await driver.fill({ selector: "#email", value: "a@b.test" });
+
+driver.state.url;            // "/dashboard"
+driver.state.history;        // ["/dashboard"]
+driver.element("#email");    // { visible: true, text: "", value: "a@b.test" }
+```
+
+The fake records `url`, `history`, `clicks`, `fills`, `frame` and `cookiesCleared`, which is what a test asserts against.
+
+### `PreviewProviderPort`
+
+`venn.port.preview-provider`, contract version 1, requires nothing. Three methods, `start`, `stop` and `latestFrame`, for the live frame stream a studio UI renders. Frame streaming is CDP-only on some engines and polled on others, which is why it is a port and not a method on the driver. A frame is the control-plane pointer (`seq`, `width`, `height`, `mime`, `data`), not a pixel buffer.
+
+| Implementation | What it is |
+| --- | --- |
+| `createNonePreviewProvider()` | The zero-cost default for CI. Starts nothing, never yields a frame. |
+| `createFakePreviewProvider()` | Returns a canned JPEG frame for any worker that has been started. |
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `browserPlugin` (also the default export) | The `PluginDefinition`: namespace `browser`, requires `net`, carrying the actions, matchers, resources and types. |
+| `BrowserDriverPort`, `BrowserDriver` | The port descriptor and its interface. |
+| `PreviewProviderPort`, `PreviewProvider` | The frame-stream port descriptor and its interface. |
+| `createFakeBrowserDriver`, `createRealBrowserDriver` | The two driver implementations. |
+| `createNonePreviewProvider`, `createFakePreviewProvider` | The two preview implementations. |
+| `FakeBrowserDriver`, `FakeBrowserState`, `FakeDriverOptions`, `FakeElement`, `FillRecord` | The fake driver's inspection surface. |
+| `LaunchOptions`, `ContextOptions`, `Viewport`, `VisitArgs`, `FillArgs`, `PressArgs`, `UploadArgs`, `DownloadArgs`, `WaitForArgs`, `EvaluateArgs`, `FrameArgs` | The driver's argument types. |
+| `BrowserHandle`, `PageHandle`, `DownloadResult`, `ScreenshotResult` | What the driver returns. |
+| `PreviewTarget`, `PreviewFrame` | The preview port's argument and result types. |
+
+## Binding a driver
+
+A host chooses the implementation once, at startup. `@venn-lang/stdlib` binds the fake for both ports; pass your own binding to override it.
+
+```ts
+import { BrowserDriverPort, createRealBrowserDriver } from "@venn-lang/browser";
+import { createRunner } from "@venn-lang/runtime";
+
+const runner = createRunner({
+  host,
+  plugins,
+  sink,
+  ports: [{ port: BrowserDriverPort, impl: createRealBrowserDriver() }],
+});
+```
+
+`BrowserDriverPort` requires `net`. A host that does not offer it fails at bind time with a readable problem, rather than with a `TypeError` in the middle of a flow.
+
+## See also
+
+- [`@venn-lang/sdk`](../sdk) for `definePlugin`, `defineAction` and `defineMatcher`, the API this package is built on.
+- [`@venn-lang/contracts`](../contracts) for `Port`, `Host` and capability negotiation.
+- [`@venn-lang/stdlib`](../stdlib) for the plugin list and the default port bindings the CLI runs with.
+- [`@venn-lang/mail`](../std-mail) for the sibling plugin that checks the email a browser flow triggered.

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { Port } from "@venn-lang/contracts";
+import { PluginDefinition } from "@venn-lang/sdk";
+//#region src/port/browser-driver.types.d.ts
+/** How an engine is launched. Both fields fall back to the driver's default. */
+interface LaunchOptions {
+  engine?: string;
+  headless?: boolean;
+}
+/** A viewport size, in CSS pixels. */
+interface Viewport {
+  width: number;
+  height: number;
+}
+/** How an isolated context is opened. */
+interface ContextOptions {
+  locale?: string;
+  viewport?: Viewport;
+}
+/** Where to navigate, and what to send with the request. */
+interface VisitArgs {
+  url: string;
+  headers?: Record<string, string>;
+}
+/** A selector paired with the value to write. Shared by `fill` and `select`. */
+interface FillArgs {
+  selector: string;
+  value: string;
+}
+/** A key press. Without a `selector`, the page holds focus. */
+interface PressArgs {
+  key: string;
+  selector?: string;
+}
+/** A file input, and the path of the file to hand it. */
+interface UploadArgs {
+  selector: string;
+  file: string;
+}
+/** What to click to start a download. */
+interface DownloadArgs {
+  selector: string;
+}
+/** A page condition to wait on. Every field is optional; `timeout` is in milliseconds. */
+interface WaitForArgs {
+  text?: string;
+  selector?: string;
+  timeout?: number;
+}
+/** JavaScript to run inside the page. */
+interface EvaluateArgs {
+  script: string;
+}
+/** An iframe to enter, named or selected. */
+interface FrameArgs {
+  name: string;
+}
+/** A live engine. The nominal `browser.Browser`. */
+interface BrowserHandle {
+  id: string;
+  engine: string;
+}
+/** A live isolated context. The nominal `browser.Page`. */
+interface PageHandle {
+  id: string;
+  /** Where the context points at the moment the handle is taken. */
+  url: string;
+}
+/** Where a downloaded file landed, and how big it is. */
+interface DownloadResult {
+  path: string;
+  bytes: number;
+}
+/** Where a screenshot landed, under the name it was asked for. */
+interface ScreenshotResult {
+  name: string;
+  path: string;
+}
+/** The contract every `browser` verb goes through. */
+interface BrowserDriver {
+  launch(opts: LaunchOptions): Promise<BrowserHandle>;
+  newContext(opts: ContextOptions): Promise<PageHandle>;
+  visit(args: VisitArgs): Promise<void>;
+  click(selector: string): Promise<void>;
+  fill(args: FillArgs): Promise<void>;
+  select(args: FillArgs): Promise<void>;
+  hover(selector: string): Promise<void>;
+  press(args: PressArgs): Promise<void>;
+  upload(args: UploadArgs): Promise<void>;
+  download(args: DownloadArgs): Promise<DownloadResult>;
+  screenshot(name: string): Promise<ScreenshotResult>;
+  waitFor(args: WaitForArgs): Promise<void>;
+  waitForUrl(url: string): Promise<void>;
+  evaluate(args: EvaluateArgs): Promise<unknown>;
+  frame(args: FrameArgs): Promise<void>;
+  clearCookies(): Promise<void>;
+}
+//#endregion
+//#region src/port/browser-driver.port.d.ts
+/**
+ * The port every `browser` verb reaches through. Requires the `net` capability,
+ * so a host without it fails to load the plugin rather than failing mid-run.
+ *
+ * `methods` must list every method a verb calls. An omission is not checked at
+ * load time, so it surfaces as a TypeError mid-run instead of a legible VN2011.
+ */
+declare const BrowserDriverPort: Port<BrowserDriver>;
+//#endregion
+//#region src/port/preview-provider.types.d.ts
+/** Which worker's frame stream a call targets. Workers stream independently. */
+interface PreviewTarget {
+  worker: number;
+}
+/** One captured frame, encoded in `data` under the stated `mime`. */
+interface PreviewFrame {
+  /** Rises by one per frame, so a consumer can tell a repeat from a fresh capture. */
+  seq: number;
+  width: number;
+  height: number;
+  mime: string;
+  data: string;
+}
+/**
+ * What feeds a live view of a running browser.
+ *
+ * Two strategies exist behind it: a screencast, which only CDP engines offer,
+ * and polling for everything else.
+ */
+interface PreviewProvider {
+  /** Begins capturing for a worker. Capturing costs, so nothing streams unstarted. */
+  start(target: PreviewTarget): Promise<void>;
+  stop(target: PreviewTarget): Promise<void>;
+  /** The most recent frame, or `undefined` when the worker is not streaming. */
+  latestFrame(target: PreviewTarget): PreviewFrame | undefined;
+}
+//#endregion
+//#region src/port/preview-provider.port.d.ts
+/**
+ * The port a live view of a run pulls frames from. Requires no capability: both
+ * implementations here are in-process, so the port loads anywhere.
+ */
+declare const PreviewProviderPort: Port<PreviewProvider>;
+//#endregion
+//#region src/drivers/fake-driver.types.d.ts
+/** The in-memory model of one DOM element, as the matchers see it. */
+interface FakeElement {
+  visible: boolean;
+  text: string;
+  value: string;
+}
+/** One recorded `fill` or `select` call. */
+interface FillRecord {
+  selector: string;
+  value: string;
+}
+/** Everything the fake driver records, so a test can assert on what a flow did. */
+interface FakeBrowserState {
+  url: string;
+  /** Every URL visited, in order. `visit` and `waitForUrl` both append. */
+  history: string[];
+  clicks: string[];
+  fills: FillRecord[];
+  /** The iframe currently entered, or `undefined` at the top level. */
+  frame: string | undefined;
+  cookiesCleared: number;
+  /** What `evaluate` resolves to, whatever the script says. */
+  evalResult: unknown;
+  elements: Map<string, FakeElement>;
+}
+/** What to preload the fake driver's page with. */
+interface FakeDriverOptions {
+  /** Elements by selector. Missing fields default to visible with empty text. */
+  elements?: Record<string, Partial<FakeElement>>;
+  url?: string;
+}
+/** The fake driver, plus the state a test reads back. */
+interface FakeBrowserDriver extends BrowserDriver {
+  readonly state: FakeBrowserState;
+  element(selector: string): FakeElement | undefined;
+}
+//#endregion
+//#region src/drivers/fake-driver.d.ts
+/**
+ * The offline `BrowserDriver`. Every method resolves at once against an
+ * in-memory page, so a test never waits on a real browser.
+ *
+ * @param options elements to preload and the URL to start at.
+ * @returns a fresh driver whose `state` records what the flow did.
+ */
+declare function createFakeBrowserDriver(options?: FakeDriverOptions): FakeBrowserDriver;
+//#endregion
+//#region src/drivers/real-driver.d.ts
+/**
+ * The engine-driving `BrowserDriver`. Not wired up in this repo, which ships
+ * the language rather than an automation backend.
+ *
+ * Methods are generated from the port descriptor, so the stub cannot fall
+ * behind the interface.
+ *
+ * @returns a driver whose every method throws, so the gap is a legible failure
+ * rather than a test that passes against nothing.
+ * @throws {VennError} `VN8090` on any call.
+ */
+declare function createRealBrowserDriver(): BrowserDriver;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `@venn-lang/browser` plugin. Registers the `browser` namespace: sixteen verbs,
+ * the `visible` and `text` matchers, the `Browser` and `Page` resources, and
+ * the nominal types those hand around. Requires the `net` capability.
+ */
+declare const browserPlugin: PluginDefinition;
+//#endregion
+//#region src/preview/fake-preview.d.ts
+/**
+ * The in-memory `PreviewProvider`. Hands back a fixed JPEG for any worker that
+ * has been started, and nothing for one that has not.
+ *
+ * @returns a fresh provider with no worker streaming.
+ */
+declare function createFakePreviewProvider(): PreviewProvider;
+//#endregion
+//#region src/preview/none-preview.d.ts
+/**
+ * The `PreviewProvider` that captures nothing. The default on CI, where nobody
+ * is watching and a frame stream is pure cost.
+ *
+ * @returns a provider that accepts every call and never yields a frame.
+ */
+declare function createNonePreviewProvider(): PreviewProvider;
+//#endregion
+export { type BrowserDriver, BrowserDriverPort, type BrowserHandle, type ContextOptions, type DownloadArgs, type DownloadResult, type EvaluateArgs, type FakeBrowserDriver, type FakeBrowserState, type FakeDriverOptions, type FakeElement, type FillArgs, type FillRecord, type FrameArgs, type LaunchOptions, type PageHandle, type PressArgs, type PreviewFrame, type PreviewProvider, PreviewProviderPort, type PreviewTarget, type ScreenshotResult, type UploadArgs, type Viewport, type VisitArgs, type WaitForArgs, browserPlugin, browserPlugin as default, createFakeBrowserDriver, createFakePreviewProvider, createNonePreviewProvider, createRealBrowserDriver };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/port/browser-driver.types.ts","../src/port/browser-driver.port.ts","../src/port/preview-provider.types.ts","../src/port/preview-provider.port.ts","../src/drivers/fake-driver.types.ts","../src/drivers/fake-driver.ts","../src/drivers/real-driver.ts","../src/plugin.ts","../src/preview/fake-preview.ts","../src/preview/none-preview.ts"],"mappings":";;;;UACiB;EACf;EACA;;;UAIe;EACf;EACA;;;UAIe;EACf;EACA,WAAW;;;UAII;EACf;EACA,UAAU;;;UAIK;EACf;EACA;;;UAIe;EACf;EACA;;;UAIe;EACf;EACA;;;UAIe;EACf;;;UAIe;EACf;EACA;EACA;;;UAIe;EACf;;;UAIe;EACf;;;UAIe;EACf;EACA;;;UAIe;EACf;;EAEA;;;UAIe;EACf;EACA;;;UAIe;EACf;EACA;;;UAIe;EACf,OAAO,MAAM,gBAAgB,QAAQ;EACrC,WAAW,MAAM,iBAAiB,QAAQ;EAC1C,MAAM,MAAM,YAAY;EACxB,MAAM,mBAAmB;EACzB,KAAK,MAAM,WAAW;EACtB,OAAO,MAAM,WAAW;EACxB,MAAM,mBAAmB;EACzB,MAAM,MAAM,YAAY;EACxB,OAAO,MAAM,aAAa;EAC1B,SAAS,MAAM,eAAe,QAAQ;EACtC,WAAW,eAAe,QAAQ;EAClC,QAAQ,MAAM,cAAc;EAC5B,WAAW,cAAc;EACzB,SAAS,MAAM,eAAe;EAC9B,MAAM,MAAM,YAAY;EACxB,gBAAgB;;;;;;;;;;;cChGL,mBAAmB,KAAK;;;;UCTpB;EACf;;;UAIe;;EAEf;EACA;EACA;EACA;EACA;;;;;;;;UASe;;EAEf,MAAM,QAAQ,gBAAgB;EAC9B,KAAK,QAAQ,gBAAgB;;EAE7B,YAAY,QAAQ,gBAAgB;;;;;;;;cCnBzB,qBAAqB,KAAK;;;;UCJtB;EACf;EACA;EACA;;;UAIe;EACf;EACA;;;UAIe;EACf;;EAEA;EACA;EACA,OAAO;;EAEP;EACA;;EAEA;EACA,UAAU,YAAY;;;UAIP;;EAEf,WAAW,eAAe,QAAQ;EAClC;;;UAIe,0BAA0B;WAChC,OAAO;EAChB,QAAQ,mBAAmB;;;;;;;;;;;iBCoDb,wBAAwB,UAAS,oBAAyB;;;;;;;;;;;;;;iBCvE1D,2BAA2B;;;;;;;;cCT9B,eAAe;;;;;;;;;iBCgBZ,6BAA6B;;;;;;;;;iBCpB7B,6BAA6B"}