@effect-uai/browser 0.9.0

package/src/internal/cdp.ts

@@ -0,0 +1,203 @@
+/**
+ * Minimal raw Chrome DevTools Protocol client over a WebSocket.
+ *
+ * CDP is JSON-RPC-shaped: commands are `{ id, method, params, sessionId? }`,
+ * replies are `{ id, result }` or `{ id, error }`, and events are `{ method,
+ * params }` with no id. Commands are correlated via a pending-`Deferred`
+ * map; events are demuxed into a `PubSub` that callers subscribe to (e.g.
+ * navigation waits on `Page.loadEventFired` instead of polling).
+ *
+ * Commands are typed against the official `devtools-protocol` schema (types
+ * only, zero runtime): `send("Page.navigate", params)` gets its params and
+ * return type from the protocol. The transport rides Effect's native
+ * `WebSocket` (via `layerWebSocketConstructorGlobal`), so no `ws` dependency is
+ * needed on modern runtimes; CDP connect uses a bare `ws://` URL with no custom
+ * headers.
+ *
+ * Failures are transport-shaped ({@link CdpError}), not the public
+ * `BrowserError`: the transport cannot know which browser verb a command was
+ * serving, so the session layer maps `CdpError` onto the typed `BrowserError`
+ * using the operation it knows.
+ */
+import {
+  Cause,
+  Data,
+  Deferred,
+  Effect,
+  HashMap,
+  Option,
+  PubSub,
+  Ref,
+  Schema,
+  type Scope,
+} from "effect"
+import * as Socket from "effect/unstable/socket/Socket"
+import type { ProtocolMapping } from "devtools-protocol/types/protocol-mapping.js"
+import * as JSONL from "@effect-uai/core/JSONL"
+
+type Commands = ProtocolMapping.Commands
+
+export type CdpMethod = keyof Commands
+export type CdpParams<M extends CdpMethod> = Commands[M]["paramsType"][0]
+export type CdpReturn<M extends CdpMethod> = Commands[M]["returnType"]
+
+/**
+ * Transport-level failure. `reply` is the browser rejecting a command,
+ * `write` is a failed socket send, `closed` is the connection going away
+ * (or never opening; the socket connects lazily) with the command still in
+ * flight. `method` names the CDP command that was in flight.
+ */
+export class CdpError extends Data.TaggedError("CdpError")<{
+  kind: "reply" | "write" | "closed"
+  method?: string
+  reason?: string
+  raw?: unknown
+}> {}
+
+/** An id-less CDP message: an event emitted by the browser. */
+export type CdpEvent = {
+  readonly method: string
+  readonly params: unknown
+  readonly sessionId: string | undefined
+}
+
+export type Cdp = {
+  readonly send: <M extends CdpMethod>(
+    method: M,
+    params?: CdpParams<M>,
+    sessionId?: string,
+  ) => Effect.Effect<CdpReturn<M>, CdpError>
+  /**
+   * Subscribe to browser events. Subscribe BEFORE issuing the command
+   * whose event you await, or the event can slip past. Subscription
+   * lifetime is the scope.
+   */
+  readonly subscribe: Effect.Effect<PubSub.Subscription<CdpEvent>, never, Scope.Scope>
+}
+
+// Replies are heterogeneous per command; the map is keyed by request id and the
+// awaited value is narrowed back to `CdpReturn<M>` at the `send` boundary. The
+// method rides along so a failure can name the command it was for.
+type Pending = {
+  readonly method: string
+  readonly deferred: Deferred.Deferred<unknown, CdpError>
+}
+
+const CdpMessage = Schema.Struct({
+  id: Schema.optional(Schema.Number),
+  result: Schema.optional(Schema.Unknown),
+  error: Schema.optional(Schema.Struct({ message: Schema.optional(Schema.String) })),
+  method: Schema.optional(Schema.String),
+  params: Schema.optional(Schema.Unknown),
+  sessionId: Schema.optional(Schema.String),
+})
+const decodeMessage = Schema.decodeUnknownEffect(CdpMessage)
+
+const frame = (
+  id: number,
+  method: string,
+  params: unknown,
+  sessionId: string | undefined,
+): string =>
+  JSON.stringify(
+    sessionId === undefined ? { id, method, params } : { id, method, params, sessionId },
+  )
+
+/**
+ * Open a scoped CDP connection to a browser-level WebSocket endpoint. The
+ * socket and its reader fiber are torn down on scope close. The underlying
+ * socket connects lazily, so a bad endpoint surfaces on the first `send` as
+ * a `CdpError` of kind `closed` (carrying the socket failure on `raw`), not
+ * here.
+ */
+export const openCdp = (endpoint: string): Effect.Effect<Cdp, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const socket = yield* Socket.makeWebSocket(endpoint, {
+      // Effect's Socket treats every close code as an error; whitelist the
+      // standard clean-close codes.
+      closeCodeIsError: (code) => code !== 1000 && code !== 1001 && code !== 1005,
+    }).pipe(Effect.provide(Socket.layerWebSocketConstructorGlobal))
+
+    const pending = yield* Ref.make(HashMap.empty<number, Pending>())
+    const counter = yield* Ref.make(0)
+    const events = yield* PubSub.unbounded<CdpEvent>()
+    // Why the socket died (failed to open, dropped, dirty close); carried on
+    // the `closed` errors handed to in-flight commands.
+    const closeCause = yield* Ref.make<unknown>(undefined)
+    const write = yield* socket.writer
+
+    const dispatch = (raw: string): Effect.Effect<void> =>
+      Effect.gen(function* () {
+        const json = yield* JSONL.parseSafe(raw)
+        if (json === undefined) return
+        const message = yield* decodeMessage(json).pipe(Effect.option)
+        if (Option.isNone(message)) return
+        if (message.value.id === undefined) {
+          if (message.value.method !== undefined) {
+            yield* PubSub.publish(events, {
+              method: message.value.method,
+              params: message.value.params,
+              sessionId: message.value.sessionId,
+            })
+          }
+          return
+        }
+        const id = message.value.id
+        const taken = yield* Ref.modify(pending, (m) => [HashMap.get(m, id), HashMap.remove(m, id)])
+        if (Option.isNone(taken)) return
+        yield* message.value.error === undefined
+          ? Deferred.succeed(taken.value.deferred, message.value.result ?? {})
+          : Deferred.fail(
+              taken.value.deferred,
+              new CdpError({
+                kind: "reply",
+                method: taken.value.method,
+                reason: message.value.error.message ?? "CDP error",
+                raw: message.value.error,
+              }),
+            )
+      })
+
+    // Reader fiber: fail every still-pending command when the socket closes so
+    // callers don't hang.
+    const failPending = Effect.gen(function* () {
+      const raw = yield* Ref.get(closeCause)
+      const taken = yield* Ref.getAndSet(pending, HashMap.empty())
+      yield* Effect.forEach(HashMap.values(taken), ({ deferred, method }) =>
+        Deferred.fail(
+          deferred,
+          new CdpError({ kind: "closed", method, reason: "connection closed", raw }),
+        ),
+      )
+    })
+    yield* socket.runString(dispatch).pipe(
+      Effect.tapCause((cause) => Ref.set(closeCause, Cause.squash(cause))),
+      Effect.ensuring(failPending),
+      Effect.forkScoped,
+    )
+
+    const send = <M extends CdpMethod>(
+      method: M,
+      params?: CdpParams<M>,
+      sessionId?: string,
+    ): Effect.Effect<CdpReturn<M>, CdpError> =>
+      Effect.gen(function* () {
+        const id = yield* Ref.updateAndGet(counter, (n) => n + 1)
+        const deferred = yield* Deferred.make<unknown, CdpError>()
+        const entry: Pending = { method, deferred }
+        yield* Ref.update(pending, HashMap.set(id, entry))
+        // `ensuring` reclaims the entry on write failure and on caller
+        // interruption; on the success path dispatch has already removed it.
+        const result = yield* write(frame(id, method, params ?? {}, sessionId)).pipe(
+          Effect.mapError(
+            (raw) => new CdpError({ kind: "write", method, reason: "socket write failed", raw }),
+          ),
+          Effect.flatMap(() => Deferred.await(deferred)),
+          Effect.ensuring(Ref.update(pending, HashMap.remove(id))),
+        )
+        return result as CdpReturn<M>
+      })
+
+    const cdp: Cdp = { send, subscribe: PubSub.subscribe(events) }
+    return cdp
+  })

package/src/internal/injected.ts

@@ -0,0 +1,413 @@
+/**
+ * The page agent: the code that runs INSIDE the browser page.
+ *
+ * Everything lives in one self-contained function, {@link installPageAgent},
+ * which is serialized with `Function.prototype.toString` and shipped through
+ * `Runtime.evaluate` (the lowest-common-denominator CDP method, so it works
+ * against partial CDP servers like obscura). It installs an idempotent
+ * global (`globalThis.__effectUaiPageAgent`) holding the helpers the session
+ * verbs call. Arguments cross the wire as `JSON.stringify` values, never as
+ * interpolated code, so there is no escaping surface.
+ *
+ * Rules for code inside `installPageAgent`:
+ * - Self-contained: no captures of module scope, no imports. Types are fine
+ *   (they erase); values are not.
+ * - Helpers signal failure by throwing `Error` with a descriptive message;
+ *   the host surfaces it via `exceptionDetails`. The exception is
+ *   `waitForSelector`, which reports timeout as `false` so the host can
+ *   raise a typed `BrowserTimeout` instead of an action failure.
+ *
+ * The whole in-page world (including the ref registry) is reset by every
+ * navigation, which is exactly the documented lifetime of element refs.
+ */
+
+import { Schema } from "effect"
+
+// ---------------------------------------------------------------------------
+// Wire shapes. Values crossing page -> host are untrusted JSON; the host
+// decodes them with these schemas instead of casting. The derived types
+// double as the agent's own annotations (types erase, so serialization
+// stays self-contained).
+// ---------------------------------------------------------------------------
+
+/** Viewport-relative center of an element, for `Input.dispatch*` events. */
+export const InjectedPoint = Schema.Struct({ x: Schema.Number, y: Schema.Number })
+export type InjectedPoint = typeof InjectedPoint.Type
+
+/** Element box: viewport-relative from `query`, page coords from `pageBox`. */
+export const InjectedBox = Schema.Struct({
+  x: Schema.Number,
+  y: Schema.Number,
+  width: Schema.Number,
+  height: Schema.Number,
+})
+export type InjectedBox = typeof InjectedBox.Type
+
+export const InjectedSize = Schema.Struct({ width: Schema.Number, height: Schema.Number })
+export type InjectedSize = typeof InjectedSize.Type
+
+/** Element data returned by `query`; serializable, never a live handle. */
+export const InjectedElementInfo = Schema.Struct({
+  ref: Schema.String,
+  tag: Schema.String,
+  text: Schema.String,
+  attributes: Schema.Record(Schema.String, Schema.String),
+  box: InjectedBox,
+})
+export type InjectedElementInfo = typeof InjectedElementInfo.Type
+
+/** The surface installed on `globalThis.__effectUaiPageAgent`. */
+export type PageAgentApi = {
+  readonly query: (selector: string, limit: number) => Array<InjectedElementInfo>
+  readonly targetPoint: (selector: string) => InjectedPoint
+  readonly pageBox: (selector: string) => InjectedBox
+  readonly contentSize: () => InjectedSize
+  readonly fill: (selector: string, text: string) => void
+  readonly selectValue: (selector: string, value: string) => void
+  readonly isChecked: (selector: string) => boolean
+  readonly focusEl: (selector: string) => void
+  readonly scrollBy: (direction: "up" | "down" | "left" | "right", pixels: number) => void
+  readonly scrollIntoView: (selector: string) => void
+  readonly waitForSelector: (selector: string, timeoutMs: number) => Promise<boolean>
+  readonly html: () => string
+  readonly markdown: () => string
+  readonly readyState: () => string
+}
+
+const AGENT_GLOBAL = "__effectUaiPageAgent"
+
+const installPageAgent = (): void => {
+  const holder = globalThis as Record<string, unknown>
+  // Global name must match AGENT_GLOBAL; duplicated because this function
+  // is serialized and cannot capture module scope.
+  if (holder["__effectUaiPageAgent"] !== undefined) return
+
+  // -- ref registry: `@e1`-style refs minted by `query`, valid until the
+  // -- next navigation (a navigation resets this whole world).
+  const byRef = new Map<string, Element>()
+  const refOf = new WeakMap<Element, string>()
+  let refCounter = 0
+
+  const refFor = (el: Element): string => {
+    const existing = refOf.get(el)
+    if (existing !== undefined) return existing
+    refCounter += 1
+    const ref = `@e${refCounter}`
+    byRef.set(ref, el)
+    refOf.set(el, ref)
+    return ref
+  }
+
+  const mustResolve = (selector: string): Element => {
+    if (selector.startsWith("@")) {
+      const el = byRef.get(selector)
+      if (el === undefined)
+        throw new Error(`stale or unknown ref ${selector} (refs reset on navigation)`)
+      if (!el.isConnected) throw new Error(`ref ${selector} is no longer in the document`)
+      return el
+    }
+    const el = document.querySelector(selector)
+    if (el === null) throw new Error(`no element matches selector ${selector}`)
+    return el
+  }
+
+  // -- markdown serialization ------------------------------------------------
+
+  const SKIP = new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "IFRAME", "SVG", "HEAD"])
+
+  const isHidden = (el: Element): boolean =>
+    el.hasAttribute("hidden") || el.getAttribute("aria-hidden") === "true"
+
+  const collapse = (text: string): string => text.replace(/\s+/g, " ").trim()
+
+  const inlineText = (node: Node): string => {
+    if (node.nodeType === Node.TEXT_NODE) return (node.textContent ?? "").replace(/\s+/g, " ")
+    if (!(node instanceof Element)) return ""
+    const tag = node.tagName.toUpperCase()
+    if (SKIP.has(tag) || isHidden(node)) return ""
+    const kids = (): string => Array.from(node.childNodes).map(inlineText).join("")
+    if (tag === "BR") return "\n"
+    if (tag === "STRONG" || tag === "B") {
+      const t = collapse(kids())
+      return t === "" ? "" : `**${t}**`
+    }
+    if (tag === "EM" || tag === "I") {
+      const t = collapse(kids())
+      return t === "" ? "" : `*${t}*`
+    }
+    if (tag === "CODE") {
+      const t = collapse(node.textContent ?? "")
+      return t === "" ? "" : `\`${t}\``
+    }
+    if (tag === "A") {
+      const t = collapse(kids())
+      if (t === "") return ""
+      const href = node.getAttribute("href")
+      return href === null || href.startsWith("javascript:") ? t : `[${t}](${href})`
+    }
+    if (tag === "IMG") {
+      const src = node.getAttribute("src")
+      return src === null ? "" : `![${node.getAttribute("alt") ?? ""}](${src})`
+    }
+    return kids()
+  }
+
+  const renderList = (el: Element, depth: number): string => {
+    const ordered = el.tagName.toUpperCase() === "OL"
+    const items: Array<string> = []
+    let index = 0
+    for (const li of Array.from(el.children)) {
+      if (li.tagName.toUpperCase() !== "LI") continue
+      index += 1
+      let own = ""
+      const sublists: Array<Element> = []
+      for (const child of Array.from(li.childNodes)) {
+        const childTag = child instanceof Element ? child.tagName.toUpperCase() : ""
+        if (childTag === "UL" || childTag === "OL") sublists.push(child as Element)
+        else own += inlineText(child)
+      }
+      let line = "  ".repeat(depth) + (ordered ? `${index}. ` : "- ") + collapse(own)
+      for (const sub of sublists) line += "\n" + renderList(sub, depth + 1)
+      items.push(line)
+    }
+    return items.join("\n")
+  }
+
+  const renderTable = (el: Element): string => {
+    const rows = Array.from(el.querySelectorAll("tr"))
+    const first = rows[0]
+    if (first === undefined) return ""
+    const cells = (tr: Element): Array<string> =>
+      Array.from(tr.children)
+        .filter((c) => c.tagName.toUpperCase() === "TD" || c.tagName.toUpperCase() === "TH")
+        .map((c) => collapse(inlineText(c)) || " ")
+    const lines = rows.map((tr) => `| ${cells(tr).join(" | ")} |`)
+    const separator = `| ${cells(first)
+      .map(() => "---")
+      .join(" | ")} |`
+    return [lines[0], separator, ...lines.slice(1)].join("\n")
+  }
+
+  const walkBlocks = (el: Element, out: Array<string>): void => {
+    for (const child of Array.from(el.children)) {
+      const tag = child.tagName.toUpperCase()
+      if (SKIP.has(tag) || isHidden(child)) continue
+      const heading = /^H([1-6])$/.exec(tag)
+      if (heading !== null) {
+        const t = collapse(inlineText(child))
+        if (t !== "") out.push("#".repeat(Number(heading[1] ?? "1")) + " " + t)
+        continue
+      }
+      if (tag === "P") {
+        const t = collapse(inlineText(child))
+        if (t !== "") out.push(t)
+        continue
+      }
+      if (tag === "PRE") {
+        out.push("```\n" + (child.textContent ?? "").replace(/\s+$/, "") + "\n```")
+        continue
+      }
+      if (tag === "BLOCKQUOTE") {
+        const t = collapse(inlineText(child))
+        if (t !== "") out.push("> " + t)
+        continue
+      }
+      if (tag === "UL" || tag === "OL") {
+        const t = renderList(child, 0)
+        if (t !== "") out.push(t)
+        continue
+      }
+      if (tag === "TABLE") {
+        const t = renderTable(child)
+        if (t !== "") out.push(t)
+        continue
+      }
+      if (tag === "HR") {
+        out.push("---")
+        continue
+      }
+      if (child.children.length > 0) {
+        walkBlocks(child, out)
+        continue
+      }
+      const t = collapse(inlineText(child))
+      if (t !== "") out.push(t)
+    }
+  }
+
+  // -- the agent surface -----------------------------------------------------
+
+  const agent: PageAgentApi = {
+    query: (selector, limit) => {
+      const els = selector.startsWith("@")
+        ? [mustResolve(selector)]
+        : Array.from(document.querySelectorAll(selector))
+      return els.slice(0, limit).map((el) => {
+        const rect = el.getBoundingClientRect()
+        const attributes: Record<string, string> = {}
+        for (const attr of Array.from(el.attributes)) attributes[attr.name] = attr.value
+        return {
+          ref: refFor(el),
+          tag: el.tagName.toLowerCase(),
+          text: collapse(el.textContent ?? "").slice(0, 200),
+          attributes,
+          box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+        }
+      })
+    },
+
+    targetPoint: (selector) => {
+      const el = mustResolve(selector)
+      el.scrollIntoView({ block: "center", inline: "center" })
+      const rect = el.getBoundingClientRect()
+      if (rect.width === 0 || rect.height === 0) {
+        throw new Error(`element ${selector} has no visible box`)
+      }
+      return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 }
+    },
+
+    pageBox: (selector) => {
+      const rect = mustResolve(selector).getBoundingClientRect()
+      return {
+        x: rect.x + window.scrollX,
+        y: rect.y + window.scrollY,
+        width: rect.width,
+        height: rect.height,
+      }
+    },
+
+    contentSize: () => ({
+      width: document.documentElement.scrollWidth,
+      height: document.documentElement.scrollHeight,
+    }),
+
+    fill: (selector, text) => {
+      const el = mustResolve(selector)
+      if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+        // Set through the native prototype setter so framework value
+        // trackers (React et al.) see the change, then fire the events a
+        // real keyboard session would.
+        const proto =
+          el instanceof HTMLInputElement
+            ? HTMLInputElement.prototype
+            : HTMLTextAreaElement.prototype
+        const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set
+        el.focus()
+        if (setter !== undefined) setter.call(el, text)
+        else el.value = text
+        el.dispatchEvent(new Event("input", { bubbles: true }))
+        el.dispatchEvent(new Event("change", { bubbles: true }))
+        return
+      }
+      if (el instanceof HTMLElement && el.isContentEditable) {
+        el.focus()
+        el.textContent = text
+        el.dispatchEvent(new Event("input", { bubbles: true }))
+        return
+      }
+      throw new Error(`element ${selector} is not fillable (input, textarea, or contenteditable)`)
+    },
+
+    selectValue: (selector, value) => {
+      const el = mustResolve(selector)
+      if (!(el instanceof HTMLSelectElement)) {
+        throw new Error(`element ${selector} is not a <select>`)
+      }
+      const option = Array.from(el.options).find((o) => o.value === value)
+      if (option === undefined) {
+        throw new Error(`select ${selector} has no option with value ${JSON.stringify(value)}`)
+      }
+      el.value = value
+      el.dispatchEvent(new Event("input", { bubbles: true }))
+      el.dispatchEvent(new Event("change", { bubbles: true }))
+    },
+
+    isChecked: (selector) => {
+      const el = mustResolve(selector)
+      if (el instanceof HTMLInputElement && (el.type === "checkbox" || el.type === "radio")) {
+        return el.checked
+      }
+      throw new Error(`element ${selector} is not a checkbox or radio input`)
+    },
+
+    focusEl: (selector) => {
+      const el = mustResolve(selector)
+      if (!(el instanceof HTMLElement)) throw new Error(`element ${selector} is not focusable`)
+      el.focus()
+    },
+
+    scrollBy: (direction, pixels) => {
+      const [dx, dy] =
+        direction === "up"
+          ? [0, -pixels]
+          : direction === "down"
+            ? [0, pixels]
+            : direction === "left"
+              ? [-pixels, 0]
+              : [pixels, 0]
+      window.scrollBy({ left: dx, top: dy, behavior: "instant" })
+    },
+
+    scrollIntoView: (selector) => {
+      mustResolve(selector).scrollIntoView({ block: "center", inline: "center" })
+    },
+
+    waitForSelector: (selector, timeoutMs) =>
+      new Promise((resolve) => {
+        const found = (): boolean =>
+          selector.startsWith("@")
+            ? (byRef.get(selector)?.isConnected ?? false)
+            : document.querySelector(selector) !== null
+        if (found()) return resolve(true)
+        const observer = new MutationObserver(() => {
+          if (!found()) return
+          observer.disconnect()
+          window.clearTimeout(timer)
+          resolve(true)
+        })
+        const timer = window.setTimeout(() => {
+          observer.disconnect()
+          resolve(false)
+        }, timeoutMs)
+        observer.observe(document.documentElement, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+        })
+      }),
+
+    html: () => document.documentElement.outerHTML,
+
+    markdown: () => {
+      const out: Array<string> = []
+      const title = document.title.trim()
+      if (title !== "") out.push(`# ${title}`)
+      // Prefer the primary content region so the serialization leads with the
+      // article, not a site-wide nav/sidebar (which in DOM order often comes
+      // first and would otherwise dominate a truncated view).
+      const root = document.querySelector("main, [role=main], article") ?? document.body
+      if (root !== null) walkBlocks(root, out)
+      return out.join("\n\n")
+    },
+
+    readyState: () => document.readyState,
+  }
+
+  holder["__effectUaiPageAgent"] = agent
+}
+
+/**
+ * Build the `Runtime.evaluate` expression for one agent call: install the
+ * agent (idempotent) and invoke the named helper. Arguments are embedded via
+ * `JSON.stringify`, so user input never becomes code.
+ *
+ * The whole thing is one IIFE that `return`s the helper result, so the
+ * expression has a single, well-defined completion value. A bare sequence of
+ * `;`-separated statements would leave the completion value engine-dependent
+ * (obscura's `Runtime.evaluate` yields `undefined` for it), and a returned
+ * promise still resolves correctly under `awaitPromise`.
+ */
+export const agentExpression = (fn: keyof PageAgentApi, args: ReadonlyArray<unknown>): string =>
+  `(()=>{(${installPageAgent.toString()})();return globalThis.${AGENT_GLOBAL}.${fn}(${args
+    .map((a) => JSON.stringify(a))
+    .join(",")});})()`