chore: add documentation

src/browser.ts

@@ -64,6 +64,7 @@ async function runCommand(
   return { process, endpoint };
 }
 
+/** Options for launching a browser */
 export interface BrowserOptions {
   headless: boolean;
   product: "chrome" | "firefox";

src/cache.ts

@@ -7,6 +7,7 @@ import { join } from "@std/path/join";
 import { ZipReader } from "@zip-js/zip-js";
 import ProgressBar from "@deno-library/progress";
 
+/** The automatically downloaded browser versions that are known to work. */
 export const SUPPORTED_VERSIONS = {
   chrome: "125.0.6400.0",
   firefox: "116.0",

src/debug.ts

@@ -1,5 +1,7 @@
+/** Whether to enable debug logging. */
 export const DEBUG = !!Deno.env.get("DEBUG");
 
+/** Attach a websocket to the console for debugging. */
 export function attachWs(ws: WebSocket) {
   ws.addEventListener("message", (ev) => {
     console.log(`<--`, ev.data);

src/dialog.ts

@@ -4,6 +4,7 @@ import type {
   Page_javascriptDialogOpening,
 } from "../bindings/celestial.ts";
 
+/** The type of the dialog. */
 export type DialogType = Page_DialogType;
 
 /**

src/element_handle.ts

@@ -9,18 +9,22 @@ import type {
 } from "./page.ts";
 import { retryDeadline } from "./util.ts";
 
+/** The x and y coordinates of a point. */
 export interface Offset {
   x: number;
   y: number;
 }
 
+/** The x and y coordinates of a point. */
 export type Point = Offset;
 
+/** The xywh model of an element. */
 export interface BoundingBox extends Point {
   height: number;
   width: number;
 }
 
+/** The box model of an element. */
 export interface BoxModel {
   border: Point[];
   content: Point[];
@@ -57,12 +61,14 @@ function getTopLeft(points: Point[]) {
 
 type AnyArray = readonly unknown[];
 
+/** The evaluate function for `ElementHandle.evaluate` method. */
 export type ElementEvaluateFunction<
   E extends unknown,
   R extends AnyArray,
   T,
 > = (element: E, ...args: R) => T;
 
+/** The options for `ElementHandle.evaluate` method. */
 export interface ElementEvaluateOptions<T> {
   args: Readonly<T>;
 }

src/keyboard.ts

@@ -1,6 +1,7 @@
 import type { Celestial } from "../bindings/celestial.ts";
 
 // https://pptr.dev/api/puppeteer.keyinput
+/** Valid keys. */
 export type KeyInput =
   | "0"
   | "1"
@@ -258,6 +259,7 @@ export type KeyInput =
   | "VolumeDown"
   | "VolumeUp";
 
+/** Options for typing on the keyboard */
 export interface KeyboardTypeOptions {
   delay?: number;
 }

src/locator.ts

@@ -3,6 +3,7 @@ import { deadline } from "@std/async/deadline";
 import type { Page } from "./page.ts";
 import type { ElementHandle } from "./element_handle.ts";
 
+/** Locator provides an api for interacting with elements on a page in a way that avoids race conditions. */
 export class Locator<T> {
   #page: Page;
   #selector: string;
@@ -18,6 +19,7 @@ export class Locator<T> {
     this.#timeout = timeout;
   }
 
+  /** Clicks the element. */
   async click() {
     await retry(async () => {
       const p = this.#click();
@@ -35,6 +37,7 @@ export class Locator<T> {
     await handle.click();
   }
 
+  /** Fills the element with the given text. */
   async fill(text: string) {
     await retry(async () => {
       const p = this.#fill(text);
@@ -52,10 +55,12 @@ export class Locator<T> {
     await handle.type(text);
   }
 
+  /** Waits for the element to appear in the page. */
   async wait(): Promise<ElementHandle> {
     return await this.#page.waitForSelector(this.#selector);
   }
 
+  /** Evaluates the given function in the context of the element. */
   async evaluate<R>(fn: (el: T) => R): Promise<R> {
     return await retry(async () => {
       const p = this.#evaluate(fn);

src/mouse.ts

@@ -1,10 +1,12 @@
 import type { Celestial, Input_MouseButton } from "../bindings/celestial.ts";
 
+/** Options for mouse clicking. */
 export interface MouseClickOptions {
   count?: number;
   delay?: number;
 }
 
+/** Options for mouse events. */
 export interface MouseOptions {
   button?: Input_MouseButton;
   clickCount?: number;

src/page.ts

@@ -17,88 +17,106 @@ import { Dialog } from "./dialog.ts";
 import { FileChooser } from "./file_chooser.ts";
 import { Locator } from "./locator.ts";
 
+/** The options for deleting a cookie */
 export type DeleteCookieOptions = Omit<
   Parameters<Celestial["Network"]["deleteCookies"]>[0],
   "transferMode"
 >;
 
+/** The options for `goTo` */
 export type GoToOptions = WaitForOptions & {
   referrer?: string;
 };
 
+/** The options for `pdf` */
 export type PdfOptions = Omit<
   Parameters<Celestial["Page"]["printToPDF"]>[0],
   "transferMode"
 >;
 
+/** The options for `screenshot` */
 export type ScreenshotOptions = Parameters<
   Celestial["Page"]["captureScreenshot"]
 >[0];
 
+/** The type definition for a cookie */
 export type Cookie = Network_Cookie;
 
+/** The options for `waitFor` */
 export type WaitForOptions = {
   waitUntil?: "none" | "load" | "networkidle0" | "networkidle2";
 };
 
+/** The options for `waitForSelector` */
 export interface WaitForSelectorOptions {
   timeout?: number;
 }
 
+/** The options for `waitForNetworkIdle` */
 export type WaitForNetworkIdleOptions = {
   idleTime?: number;
   idleConnections?: number;
 };
 
+/** The options for sandboxing */
 export type SandboxOptions = {
   sandbox?: boolean;
 };
 
+/** The options for valid media features */
 export type MediaFeature = Exclude<
   Parameters<Celestial["Emulation"]["setEmulatedMedia"]>[0]["features"],
   undefined
 >[0];
 
 type AnyArray = readonly unknown[];
 
+/** The type definition for a function that can be evaluated in the page */
 export type EvaluateFunction<T, R extends AnyArray> =
   | string
   | ((...args: R) => T);
 
+/** The options for evaluating a function in the page */
 export interface EvaluateOptions<T> {
   args: Readonly<T>;
 }
 
+/** The events that may be emitted from a page */
 export interface PageEventMap {
   "console": ConsoleEvent;
   "dialog": DialogEvent;
   "filechooser": FileChooserEvent;
   "pageerror": PageErrorEvent;
 }
 
+/** The details for a console event */
 export interface ConsoleEventDetails {
   type: Runtime_consoleAPICalled["type"];
   text: string;
 }
 
+/** The console event class */
 export class ConsoleEvent extends CustomEvent<ConsoleEventDetails> {
   constructor(detail: ConsoleEventDetails) {
     super("console", { detail });
   }
 }
 
+/** The dialog event class */
 export class DialogEvent extends CustomEvent<Dialog> {
   constructor(detail: Dialog) {
     super("dialog", { detail });
   }
 }
 
+/** The file chooser event class */
 export class FileChooserEvent extends CustomEvent<FileChooser> {
   constructor(detail: FileChooser) {
     super("filechooser", { detail });
   }
 }
 
+/** The page error event class */
 export class PageErrorEvent extends CustomEvent<Error> {
   constructor(detail: Error) {
     super("pageerror", { detail });

src/util.ts

@@ -1,6 +1,7 @@
 import { deadline } from "@std/async/deadline";
 import { retry } from "@std/async/retry";
 
+/** Regular expression to extract the endpoint from a websocket url */
 export const WEBSOCKET_ENDPOINT_REGEX = /ws:\/\/(.*:.*?)\//;
 
 /**