@venn-lang/browser 0.1.0

package/src/drivers/real-driver.ts

@@ -0,0 +1,28 @@
+import { VennError } from "@venn-lang/contracts";
+import { type BrowserDriver, BrowserDriverPort } from "../port/index.js";
+
+function notImplemented(): VennError {
+  return new VennError({
+    code: "VN8090",
+    message: "browser real driver not implemented in this build",
+  });
+}
+
+/**
+ * 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.
+ */
+export function createRealBrowserDriver(): BrowserDriver {
+  const fail = (): never => {
+    throw notImplemented();
+  };
+  const entries = BrowserDriverPort.methods.map((method) => [method, fail] as const);
+  return Object.fromEntries(entries) as unknown as BrowserDriver;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * `@venn-lang/browser`: the verbs that drive a page, the matchers that assert about
+ * an element, and the two ports behind them. `BrowserDriver` does the driving;
+ * `PreviewProvider` streams frames for a live view of a run.
+ */
+
+export * from "./drivers/index.js";
+export { browserPlugin, browserPlugin as default } from "./plugin.js";
+export * from "./port/index.js";
+export * from "./preview/index.js";

package/src/matchers/index.ts

@@ -0,0 +1,6 @@
+import type { MatcherDefinition } from "@venn-lang/sdk";
+import { text } from "./text.js";
+import { visible } from "./visible.js";
+
+/** Every matcher the `browser` namespace contributes to `expect`. */
+export const browserMatchers: MatcherDefinition[] = [visible, text];

package/src/matchers/text.ts

@@ -0,0 +1,22 @@
+import { arg, defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+
+/**
+ * `expect element text "Order confirmed"`.
+ *
+ * Passes when the element's text equals or contains the expected string.
+ * Containment is deliberate: assertions about copy should survive a stray
+ * space or a wrapping node.
+ */
+export const text: MatcherDefinition = defineMatcher({
+  name: "text",
+  args: [arg("value", t.string, "The text the element should carry.")],
+  appliesTo: "Element",
+  test: ({ subject, args }) => matchesText(subject, String(args[0])),
+  message: ({ args }) => `expected the element text to contain "${String(args[0])}"`,
+});
+
+function matchesText(subject: unknown, expected: string): boolean {
+  const actual = (subject as { text?: string } | null)?.text ?? "";
+  return actual === expected || actual.includes(expected);
+}

package/src/matchers/visible.ts

@@ -0,0 +1,18 @@
+import { defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+
+/**
+ * `expect element visible`.
+ *
+ * Passes when the element is on screen. An element that is absent, or whose
+ * subject is not an element at all, fails rather than erroring.
+ */
+export const visible: MatcherDefinition = defineMatcher({
+  name: "visible",
+  appliesTo: "Element",
+  test: ({ subject }) => isVisible(subject),
+  message: () => "expected the element to be visible",
+});
+
+function isVisible(subject: unknown): boolean {
+  return (subject as { visible?: boolean } | null)?.visible === true;
+}

package/src/plugin.ts

@@ -0,0 +1,25 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { browserActions } from "./actions/index.js";
+import { browserMatchers } from "./matchers/index.js";
+import { browserTypes } from "./plugin.types.js";
+import { browserResources } from "./resources/index.js";
+import { browserTypeDefs } from "./types.js";
+
+/**
+ * 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.
+ */
+export const browserPlugin: PluginDefinition = definePlugin({
+  name: "venn/browser",
+  version: "0.0.0",
+  namespace: "browser",
+  requires: ["net"],
+  actions: browserActions,
+  matchers: browserMatchers,
+  resources: browserResources,
+  types: browserTypes,
+  typeDefs: browserTypeDefs,
+});
+
+export { browserPlugin as default };

package/src/plugin.types.ts

@@ -0,0 +1,13 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+
+/** The handle `browser.launch` yields. */
+const Browser = z.object({ id: z.string(), engine: z.string() });
+
+/** The handle `browser.newContext` yields; what `page.` completes against. */
+const Page = z.object({ id: z.string(), url: z.string() });
+
+/** A resolved DOM element, as `visible` and `text` are handed it. */
+const Element = z.object({ visible: z.boolean(), text: z.string(), value: z.string() });
+
+/** Runtime validators for the nominal types the `browser` namespace registers. */
+export const browserTypes: Record<string, ZodType> = { Browser, Page, Element };

package/src/port/browser-driver.port.ts

@@ -0,0 +1,33 @@
+import type { Port } from "@venn-lang/contracts";
+import type { BrowserDriver } from "./browser-driver.types.js";
+
+/**
+ * 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.
+ */
+export const BrowserDriverPort: Port<BrowserDriver> = {
+  id: "venn.port.browser-driver",
+  version: 1,
+  requires: ["net"],
+  methods: [
+    "launch",
+    "newContext",
+    "visit",
+    "click",
+    "fill",
+    "select",
+    "hover",
+    "press",
+    "upload",
+    "download",
+    "screenshot",
+    "waitFor",
+    "waitForUrl",
+    "evaluate",
+    "frame",
+    "clearCookies",
+  ],
+};

package/src/port/browser-driver.types.ts

@@ -0,0 +1,108 @@
+/** How an engine is launched. Both fields fall back to the driver's default. */
+export interface LaunchOptions {
+  engine?: string;
+  headless?: boolean;
+}
+
+/** A viewport size, in CSS pixels. */
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+/** How an isolated context is opened. */
+export interface ContextOptions {
+  locale?: string;
+  viewport?: Viewport;
+}
+
+/** Where to navigate, and what to send with the request. */
+export interface VisitArgs {
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** A selector paired with the value to write. Shared by `fill` and `select`. */
+export interface FillArgs {
+  selector: string;
+  value: string;
+}
+
+/** A key press. Without a `selector`, the page holds focus. */
+export interface PressArgs {
+  key: string;
+  selector?: string;
+}
+
+/** A file input, and the path of the file to hand it. */
+export interface UploadArgs {
+  selector: string;
+  file: string;
+}
+
+/** What to click to start a download. */
+export interface DownloadArgs {
+  selector: string;
+}
+
+/** A page condition to wait on. Every field is optional; `timeout` is in milliseconds. */
+export interface WaitForArgs {
+  text?: string;
+  selector?: string;
+  timeout?: number;
+}
+
+/** JavaScript to run inside the page. */
+export interface EvaluateArgs {
+  script: string;
+}
+
+/** An iframe to enter, named or selected. */
+export interface FrameArgs {
+  name: string;
+}
+
+/** A live engine. The nominal `browser.Browser`. */
+export interface BrowserHandle {
+  id: string;
+  engine: string;
+}
+
+/** A live isolated context. The nominal `browser.Page`. */
+export 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. */
+export interface DownloadResult {
+  path: string;
+  bytes: number;
+}
+
+/** Where a screenshot landed, under the name it was asked for. */
+export interface ScreenshotResult {
+  name: string;
+  path: string;
+}
+
+/** The contract every `browser` verb goes through. */
+export 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>;
+}

package/src/port/index.ts

@@ -0,0 +1,21 @@
+export { BrowserDriverPort } from "./browser-driver.port.js";
+export type {
+  BrowserDriver,
+  BrowserHandle,
+  ContextOptions,
+  DownloadArgs,
+  DownloadResult,
+  EvaluateArgs,
+  FillArgs,
+  FrameArgs,
+  LaunchOptions,
+  PageHandle,
+  PressArgs,
+  ScreenshotResult,
+  UploadArgs,
+  Viewport,
+  VisitArgs,
+  WaitForArgs,
+} from "./browser-driver.types.js";
+export { PreviewProviderPort } from "./preview-provider.port.js";
+export type { PreviewFrame, PreviewProvider, PreviewTarget } from "./preview-provider.types.js";

package/src/port/preview-provider.port.ts

@@ -0,0 +1,13 @@
+import type { Port } from "@venn-lang/contracts";
+import type { PreviewProvider } from "./preview-provider.types.js";
+
+/**
+ * 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.
+ */
+export const PreviewProviderPort: Port<PreviewProvider> = {
+  id: "venn.port.preview-provider",
+  version: 1,
+  requires: [],
+  methods: ["start", "stop", "latestFrame"],
+};

package/src/port/preview-provider.types.ts

@@ -0,0 +1,28 @@
+/** Which worker's frame stream a call targets. Workers stream independently. */
+export interface PreviewTarget {
+  worker: number;
+}
+
+/** One captured frame, encoded in `data` under the stated `mime`. */
+export 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.
+ */
+export 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;
+}

package/src/preview/fake-preview.ts

@@ -0,0 +1,37 @@
+import type { PreviewFrame, PreviewProvider } from "../port/index.js";
+
+function startStream(streaming: Set<number>, worker: number): Promise<void> {
+  streaming.add(worker);
+  return Promise.resolve();
+}
+
+function stopStream(streaming: Set<number>, worker: number): Promise<void> {
+  streaming.delete(worker);
+  return Promise.resolve();
+}
+
+function cannedFrame(worker: number): PreviewFrame {
+  return {
+    seq: worker + 1,
+    width: 1280,
+    height: 800,
+    mime: "image/jpeg",
+    data: "ZmFrZS1mcmFtZQ==",
+  };
+}
+
+/**
+ * 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.
+ */
+export function createFakePreviewProvider(): PreviewProvider {
+  const streaming = new Set<number>();
+  return {
+    start: (target) => startStream(streaming, target.worker),
+    stop: (target) => stopStream(streaming, target.worker),
+    latestFrame: (target) =>
+      streaming.has(target.worker) ? cannedFrame(target.worker) : undefined,
+  };
+}

package/src/preview/index.ts

@@ -0,0 +1,2 @@
+export { createFakePreviewProvider } from "./fake-preview.js";
+export { createNonePreviewProvider } from "./none-preview.js";

package/src/preview/none-preview.ts

@@ -0,0 +1,15 @@
+import type { PreviewProvider } from "../port/index.js";
+
+/**
+ * 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.
+ */
+export function createNonePreviewProvider(): PreviewProvider {
+  return {
+    start: () => Promise.resolve(),
+    stop: () => Promise.resolve(),
+    latestFrame: () => undefined,
+  };
+}

package/src/resources/browser-resource.ts

@@ -0,0 +1,15 @@
+import { defineResource, type ResourceDefinition } from "@venn-lang/sdk";
+
+/**
+ * A worker-scoped browser: one engine per worker, shared by every flow that
+ * worker runs.
+ *
+ * `open` hands back a placeholder handle and `close` does nothing, because the
+ * runtime does not execute `resource` declarations yet.
+ */
+export const browserResource: ResourceDefinition = defineResource({
+  name: "Browser",
+  scope: "worker",
+  open: () => ({ id: "browser-1", engine: "chromium" }),
+  close: () => undefined,
+});

package/src/resources/index.ts

@@ -0,0 +1,6 @@
+import type { ResourceDefinition } from "@venn-lang/sdk";
+import { browserResource } from "./browser-resource.js";
+import { pageResource } from "./page-resource.js";
+
+/** Every resource the `browser` namespace declares, outer scope first. */
+export const browserResources: ResourceDefinition[] = [browserResource, pageResource];

package/src/resources/page-resource.ts

@@ -0,0 +1,15 @@
+import { defineResource, type ResourceDefinition } from "@venn-lang/sdk";
+
+/**
+ * A flow-scoped page: one isolated context per flow, so two flows never share
+ * a session.
+ *
+ * `open` hands back a placeholder handle and `close` does nothing, because the
+ * runtime does not execute `resource` declarations yet.
+ */
+export const pageResource: ResourceDefinition = defineResource({
+  name: "Page",
+  scope: "flow",
+  open: () => ({ id: "page-1", url: "about:blank" }),
+  close: () => undefined,
+});

package/src/types.ts

@@ -0,0 +1,28 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The types `@venn-lang/browser` publishes to the checker, under the `browser`
+ * namespace.
+ *
+ * `Browser` and `Page` are opaque because they are live things, and their
+ * insides belong to the driver rather than to a flow. `Download` and
+ * `Screenshot` are plain data, mirroring `DownloadResult` and
+ * `ScreenshotResult` in `port/browser-driver.types.ts` field by field. No
+ * driver method returns an element, so `Element` mirrors `FakeElement` instead.
+ */
+export const browserTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /** A launched engine. Held, passed to the `browser` verbs, closed by scope. */
+  Browser: t.opaque("browser.Browser", { id: t.string, engine: t.string }),
+  /** An isolated context: which one it is, and where it currently points. */
+  Page: t.opaque("browser.Page", { id: t.string, url: t.string }),
+  /**
+   * A resolved element: the subject `visible` and `text` match against. The
+   * selector is how an element is found, not something it carries, so what the
+   * matchers are handed is `{ visible, text, value }`, all three always set.
+   */
+  Element: t.record({ visible: t.bool, text: t.string, value: t.string }, { open: true }),
+  /** What `browser.download` captured: where it landed, and how big it was. */
+  Download: t.record({ path: t.string, bytes: t.number }),
+  /** What `browser.screenshot` captured, under the name it was asked for. */
+  Screenshot: t.record({ name: t.string, path: t.string }),
+};