@antelopejs/dms 0.15.0 → 0.16.0

package/bin/control/session.mjs

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { firstString, stringField } from "./json.mjs";
 import { saveRun } from "./run-state.mjs";
 
 const REQUEST_TIMEOUT_MS = 30_000;
@@ -9,11 +10,15 @@ const PASSWORD_BYTES = 9;
 const OK_MIN = 200;
 const OK_MAX = 299;
 
+/**
+ * @typedef {{ status: number | null, body: unknown, error: string | null }} ApiAnswer
+ */
+
 /**
  * The credentials of the run's administrator, derived from the run id so a
  * journey can name them before onboarding.
  *
- * @param {{ id: string }} state The run
+ * @param {Pick<import("./run-state.mjs").RunState, "id" | "adminPassword">} state The run
  * @returns {{ email: string, password: string, firstName: string, lastName: string }} The administrator's credentials
  */
 export function adminCredentials(state) {
@@ -35,6 +40,10 @@ export function newPassword() {
   return `Vr1!${randomBytes(PASSWORD_BYTES).toString("base64url").replace(/[-_]/g, "x")}`;
 }
 
+/**
+ * @param {string} text The text
+ * @returns {string} The text as a folder name
+ */
 function slug(text) {
   return text
     .toLowerCase()
@@ -63,9 +72,15 @@ export function nextFolder(state, group, label) {
   return folder;
 }
 
+/**
+ * @param {string} text The response text
+ * @returns {unknown} The parsed JSON, or the text when it is not JSON
+ */
 function parseBody(text) {
   try {
-    return JSON.parse(text);
+    /** @type {unknown} */
+    const parsed = JSON.parse(text);
+    return parsed;
   } catch {
     return text;
   }
@@ -76,8 +91,8 @@ function parseBody(text) {
  * response.json into `folder`. Secrets in the request are left out.
  *
  * @param {string} folder Where the evidence goes
- * @param {{ url: string, method: string, body?: any, token?: string }} request What to send
- * @returns {Promise<{ status: number | null, body: any, error: string | null }>} The answer
+ * @param {{ url: string, method: string, body?: unknown, token?: string }} request What to send
+ * @returns {Promise<ApiAnswer>} The answer
  */
 export async function recordedRequest(folder, request) {
   const headers = { accept: "application/json" };
@@ -127,9 +142,9 @@ export function isOk(answer) {
  * Signs an account in through `POST /api/auth/login` and keeps its tokens in
  * the run state.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @param {string} account The account name, `admin` for the run's administrator
- * @returns {Promise<{ status: number | null, body: any }>} The login answer
+ * @returns {Promise<ApiAnswer>} The login answer
  */
 export async function signIn(state, account) {
   const credentials = state.accounts?.[account];
@@ -144,8 +159,9 @@ export async function signIn(state, account) {
     method: "POST",
     body: { email: credentials.email, password: credentials.password },
   });
-  if (isOk(answer) && answer.body?.access_token) {
-    state.tokens = { ...state.tokens, [account]: answer.body.access_token };
+  const token = stringField(answer.body, "access_token");
+  if (isOk(answer) && token) {
+    state.tokens = { ...state.tokens, [account]: token };
     saveRun(state);
   }
   return answer;
@@ -155,9 +171,9 @@ export async function signIn(state, account) {
  * Creates the run's administrator through `POST /api/onboarding/register`,
  * then signs it in.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @param {{ platformName?: string }} options Wizard details
- * @returns {Promise<{ register: { status: number | null, body: any }, login: { status: number | null, body: any } | null }>} Both answers
+ * @returns {Promise<{ register: ApiAnswer, login: ApiAnswer | null }>} Both answers
  */
 export async function onboard(state, options) {
   const admin = adminCredentials(state);
@@ -168,6 +184,7 @@ export async function onboard(state, options) {
       method: "POST",
       body: {
         ...admin,
+        setupToken: state.secrets.DMS_SETUP_TOKEN,
         platformName: options.platformName ?? `Verify ${state.id}`,
       },
     },
@@ -178,7 +195,7 @@ export async function onboard(state, options) {
     admin: {
       email: admin.email,
       password: admin.password,
-      userId: register.body?.[0] ?? null,
+      userId: firstString(register.body) ?? null,
     },
   };
   saveRun(state);
@@ -189,9 +206,9 @@ export async function onboard(state, options) {
  * An authenticated (or anonymous) request to the run's backend, signing the
  * account in again once when its token was refused.
  *
- * @param {Record<string, any>} state The run
- * @param {{ method: string, path: string, body?: any, as: string, label?: string, folder?: () => string }} request What to send and as whom; `as` is an account name or `anon`; `folder` makes each attempt's evidence folder
- * @returns {Promise<{ status: number | null, body: any, error: string | null, folder: string }>} The answer and its evidence folder
+ * @param {import("./run-state.mjs").RunState} state The run
+ * @param {{ method: string, path: string, body?: unknown, as: string, label?: string, folder?: () => string }} request What to send and as whom; `as` is an account name or `anon`; `folder` makes each attempt's evidence folder
+ * @returns {Promise<ApiAnswer & { folder: string }>} The answer and its evidence folder
  */
 export async function apiRequest(state, request) {
   const label = request.label ?? `${request.method} ${request.path}`;

package/bin/control/stack.mjs

@@ -11,7 +11,9 @@ import {
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { describeFailure } from "./failure.mjs";
 import { checkoutOf } from "./git.mjs";
+import { stringField } from "./json.mjs";
 import { dropDatabase, dropRunDatabases, startMongod } from "./mongo.mjs";
 import {
   freePort,
@@ -29,8 +31,14 @@ import {
   runsRoot,
   saveRun,
 } from "./run-state.mjs";
+import { RENDERER_CLI, resolveRenderer } from "./renderer.mjs";
 import { newPassword } from "./session.mjs";
 
+/**
+ * @typedef {import("./run-state.mjs").RunState} RunState
+ * @typedef {{ playground: string, renderer?: string, runs?: string, mongoUrl?: string, env?: string[], base?: string, skill?: string }} UpOptions Where the playground and the runs are
+ */
+
 const READY_TIMEOUT_MS = 180_000;
 const SECRET_BYTES = 32;
 const MAIL_PORT_ATTEMPTS = 3;
@@ -42,6 +50,7 @@ const SECRET_NAMES = [
   "DMS_BOOTSTRAP_SECRET",
   "DMS_HTML_RENDER_SECRET",
   "DMS_SESSION_SECRET",
+  "DMS_SETUP_TOKEN",
 ];
 const DROPPED_PREFIXES = ["ANTELOPEJS_", "npm_", "PNPM_", "DMS_", "MONGO_"];
 
@@ -66,23 +75,30 @@ export function resolutionFolders(state) {
 }
 
 /**
- * The `ajs` and `ajs dms` entry points the playground installs.
+ * The `ajs` and `ajs dms` entry points the playground installs, `ajs dms`
+ * being the renderer checkout's when the run serves one.
  *
  * @param {string} playground The playground folder
+ * @param {string} [renderer] The renderer checkout the run serves
  * @returns {{ ajs: string, dms: string }} Their scripts
  */
-export function cliPaths(playground) {
+export function cliPaths(playground, renderer) {
   const require = createRequire(join(playground, "package.json"));
   const core = dirname(require.resolve("@antelopejs/core/package.json"));
-  const frontend = dirname(
-    require.resolve("@antelopejs/dms-frontend/package.json"),
-  );
+  const frontend =
+    renderer ??
+    dirname(require.resolve("@antelopejs/dms-frontend/package.json"));
   return {
     ajs: join(core, "dist", "core", "cli", "index.js"),
-    dms: join(frontend, "dist", "index.js"),
+    dms: join(frontend, RENDERER_CLI),
   };
 }
 
+/**
+ * @param {string} real
+ * @param {string} shadow
+ * @param {string} keep
+ */
 function shadowLevel(real, shadow, keep) {
   mkdirSync(shadow, { recursive: true });
   for (const entry of readdirSync(real)) {
@@ -91,19 +107,40 @@ function shadowLevel(real, shadow, keep) {
   }
 }
 
+/**
+ * A `node_modules` that is `modules` with `@antelopejs/dms-frontend` replaced
+ * by the renderer checkout, every other entry linked to the original.
+ *
+ * @param {string} modules The playground's installed modules
+ * @param {string} shadow The run's `node_modules`
+ * @param {string} renderer The renderer checkout
+ */
+export function linkRenderer(modules, shadow, renderer) {
+  const scope = "@antelopejs";
+  shadowLevel(modules, shadow, scope);
+  const scoped = join(modules, scope);
+  const shadowScope = join(shadow, scope);
+  if (existsSync(scoped)) shadowLevel(scoped, shadowScope, "dms-frontend");
+  else mkdirSync(shadowScope);
+  symlinkSync(renderer, join(shadowScope, "dms-frontend"));
+}
+
 /**
  * Lays out the run's copy of the checkout: from the checkout root down to
  * the playground, every sibling is linked, so relative paths such as a
  * tsconfig `extends` resolve as in the checkout. The playground itself is
  * copied without its installed modules and build, so `.antelope/` and the
- * frontend build belong to the run.
+ * frontend build belong to the run. Its `node_modules` is the playground's,
+ * except that `@antelopejs/dms-frontend` is the `renderer` checkout when
+ * there is one.
  *
  * @param {string} playground The playground folder
  * @param {string} checkout The checkout root, or the module folder outside one
  * @param {string} root The run's copy of the checkout
+ * @param {string} [renderer] The renderer checkout the run serves
  * @returns {string} The run's playground folder
  */
-export function layOutCopy(playground, checkout, root) {
+export function layOutCopy(playground, checkout, root, renderer) {
   const segments = relative(checkout, playground).split(sep);
   let real = checkout;
   let shadow = root;
@@ -116,7 +153,9 @@ export function layOutCopy(playground, checkout, root) {
     recursive: true,
     filter: (source) => !COPY_SKIPPED.has(basename(source)),
   });
-  symlinkSync(join(playground, "node_modules"), join(shadow, "node_modules"));
+  const modules = join(playground, "node_modules");
+  if (renderer) linkRenderer(modules, join(shadow, "node_modules"), renderer);
+  else symlinkSync(modules, join(shadow, "node_modules"));
   return shadow;
 }
 
@@ -133,7 +172,7 @@ function inheritedEnv() {
  * database, origin and secrets, an npm cache and a pnpm store shared by
  * every run, no update checks and no colors. Extra `KEY=VALUE` pairs from `--env` come last.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @returns {NodeJS.ProcessEnv} The environment
  */
 export function runEnv(state) {
@@ -162,6 +201,10 @@ export function runEnv(state) {
   };
 }
 
+/**
+ * @param {string[]} pairs
+ * @returns {Record<string, string>}
+ */
 function parseExtraEnv(pairs) {
   return Object.fromEntries(
     pairs.map((pair) => {
@@ -172,6 +215,10 @@ function parseExtraEnv(pairs) {
   );
 }
 
+/**
+ * @param {UpOptions} options
+ * @returns {Promise<RunState>}
+ */
 async function initialState(options) {
   const playground = resolve(options.playground);
   if (!existsSync(join(playground, "antelope.config.ts"))) {
@@ -183,7 +230,9 @@ async function initialState(options) {
   const webPort = await freePort();
   const smtpPort = await freePort();
   const checkout = checkoutOf(playground);
-  return {
+  const renderer = options.renderer && resolveRenderer(options.renderer);
+  const verified = renderer ? checkoutOf(renderer) : checkout;
+  const state = {
     ...paths,
     id,
     createdAt: new Date().toISOString(),
@@ -191,7 +240,7 @@ async function initialState(options) {
     playground,
     moduleRoot: dirname(playground),
     repo: checkout.root,
-    headSha: checkout.head,
+    headSha: verified.head,
     baseRef: options.base ?? "origin/main",
     skill: options.skill ?? null,
     apiPort,
@@ -217,13 +266,15 @@ async function initialState(options) {
     tokens: {},
     ready: false,
   };
+  if (renderer) state.renderer = renderer;
+  return state;
 }
 
 /**
  * How to run one of the playground's CLIs for the run: its own log, the
  * run's environment, from the run's playground copy or `cwd`.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @param {string} name The log name
  * @param {string} script The CLI script
  * @param {string[]} args Its arguments
@@ -241,6 +292,10 @@ export function spec(state, name, script, args, cwd = state.runPlayground) {
   };
 }
 
+/**
+ * @param {RunState} state
+ * @param {import("./run-state.mjs").ProcessRecord} processRecord
+ */
 function record(state, processRecord) {
   state.processes = [
     ...state.processes.filter((entry) => entry.name !== processRecord.name),
@@ -253,7 +308,7 @@ function record(state, processRecord) {
  * Starts the run's mail sink unless it already runs, and waits until it is
  * the process listening on the run's mail port.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @returns {Promise<void>} Resolves once it listens
  */
 export async function ensureMail(state) {
@@ -271,6 +326,10 @@ export async function ensureMail(state) {
   await waitForOwnPort(state.smtpPort, mail, READY_TIMEOUT_MS);
 }
 
+/**
+ * @param {RunState} state
+ * @returns {Promise<void>}
+ */
 async function startFirstMail(state) {
   for (let attempt = 1; ; attempt += 1) {
     try {
@@ -283,6 +342,11 @@ async function startFirstMail(state) {
   }
 }
 
+/**
+ * @param {RunState} state
+ * @param {{ playground?: string, cwd?: string }} [build]
+ * @returns {Promise<void>}
+ */
 async function startBackend(state, build) {
   const { ajs } = cliPaths(build?.playground ?? state.playground);
   const backend = startDetached(
@@ -302,12 +366,17 @@ async function startBackend(state, build) {
   );
 }
 
+/**
+ * @param {RunState} state
+ * @returns {Promise<void>}
+ */
 async function buildAndStart(state) {
-  const clis = cliPaths(state.playground);
+  const clis = cliPaths(state.playground, state.renderer);
   state.runPlayground = layOutCopy(
     state.playground,
     state.repo ?? state.moduleRoot,
     state.root,
+    state.renderer,
   );
   if (state.ownsMongo) {
     const mongo = await startMongod(state, resolutionFolders(state));
@@ -345,12 +414,13 @@ async function buildAndStart(state) {
 /**
  * Starts an isolated DMS from a playground: a copy of it in a run folder,
  * free ports, the `docs` environment, a `verify_<run>` database on a mongod
- * the run owns (or `--mongo-url`), fresh secrets and a mail sink. Ready once
+ * the run owns (or `--mongo-url`), fresh secrets and a mail sink. With
+ * `renderer`, the dashboard is that built dms-frontend checkout. Ready once
  * `/api/onboarding/informations` and `/dms-preview` answer 200. On failure
  * it stops what it started and keeps the logs.
  *
- * @param {{ playground: string, runs?: string, mongoUrl?: string, env?: string[], base?: string, skill?: string }} options Where the playground and the runs are
- * @returns {Promise<Record<string, any>>} The ready run
+ * @param {UpOptions} options Where the playground and the runs are
+ * @returns {Promise<import("./run-state.mjs").RunState>} The ready run
  */
 export async function up(options) {
   const state = await initialState(options);
@@ -373,7 +443,7 @@ export async function up(options) {
  * a crash would, from the run's build or another one (`build`, the base
  * version's). The frontend keeps serving and proxies to the same port.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @param {{ playground: string, cwd: string }} [build] Another build to start
  * @returns {Promise<void>} Resolves once the backend answers again
  */
@@ -389,7 +459,7 @@ export async function restartBackend(state, build) {
  * journey database is dropped, so a long run does not exhaust mongod's
  * file handles; its evidence stays.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @param {string} suffix What tells the database apart, such as `j03`
  * @returns {Promise<string>} The database now in use
  */
@@ -411,7 +481,7 @@ export async function freshDatabase(state, suffix) {
  * run's databases, and removes everything but `evidence/`, `logs/` and
  * `run.json`, from which the secrets and passwords are removed.
  *
- * @param {Record<string, any>} state The run
+ * @param {import("./run-state.mjs").RunState} state The run
  * @returns {Promise<string[]>} One line per action
  */
 export async function down(state) {
@@ -428,8 +498,8 @@ export async function down(state) {
       state.mongoUrl,
       state.databasePrefix,
       resolutionFolders(state),
-    ).catch((error) => [
-      `could not drop the run's databases: ${error.message}`,
+    ).catch((/** @type {unknown} */ error) => [
+      `could not drop the run's databases: ${describeFailure(error)}`,
     ]);
     lines.push(...dropped);
   }
@@ -473,7 +543,9 @@ export async function down(state) {
  */
 export function packageVersion(file) {
   try {
-    return JSON.parse(readFileSync(file, "utf8")).version ?? "missing";
+    /** @type {unknown} */
+    const manifest = JSON.parse(readFileSync(file, "utf8"));
+    return stringField(manifest, "version") ?? "missing";
   } catch {
     return "missing";
   }

package/bin/control/tab.mjs

@@ -5,10 +5,22 @@ import {
   signInThroughForm,
 } from "./browser.mjs";
 
+/**
+ * @typedef {import("./browser.mjs").Action} Action
+ * @typedef {import("./browser.mjs").Outcome} Outcome
+ * @typedef {import("./browser.mjs").Target} Target
+ * @typedef {import("./journey.mjs").Check} Check
+ * @typedef {{ timeoutMs?: number }} Timeout
+ */
+
 const EXPECT_TIMEOUT_MS = 15_000;
 const POLL_MS = 250;
 const DETAIL_LENGTH = 300;
 
+/**
+ * @param {string} text The text
+ * @returns {string} The text on one line, cut to the detail length
+ */
 function flatten(text) {
   const flat = text.replace(/\s+/g, " ").trim();
   return flat.length > DETAIL_LENGTH
@@ -25,7 +37,7 @@ function flatten(text) {
 export class Tab {
   /**
    * @param {import("./journey.mjs").JourneyContext} context The journey
-   * @param {any} page The Playwright page
+   * @param {import("playwright-core").Page} page The Playwright page
    * @param {string} label The tab's name in evidence
    */
   constructor(context, page, label) {
@@ -37,9 +49,9 @@ export class Tab {
   /**
    * Runs one browser action and records it as a critical step.
    *
-   * @param {Record<string, any>} action The action, as `perform` takes it
+   * @param {Omit<Action, "baseUrl">} action The action, as `perform` takes it
    * @param {string} label What the step does
-   * @returns {Promise<{ ok: boolean, url: string, error: string | null, aria: string, folder: string }>} The outcome
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
    */
   async act(action, label) {
     const folder = this.context.step(`${this.label} ${label}`);
@@ -56,22 +68,44 @@ export class Tab {
     return { ...outcome, folder };
   }
 
-  /** Opens a path of the frontend. */
+  /**
+   * Opens a path of the frontend. Callers pass link lookups that are
+   * `undefined` when no link matched; the navigation then targets the
+   * literal path `undefined`.
+   *
+   * @param {string | undefined} path The path
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   goto(path) {
     return this.act({ do: "goto", path }, `open ${path}`);
   }
 
-  /** Reloads the page. */
+  /**
+   * Reloads the page.
+   *
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   reload() {
     return this.act({ do: "reload" }, "reload");
   }
 
-  /** Clicks a target found by role and name. */
+  /**
+   * Clicks a target found by role and name.
+   *
+   * @param {Target} target What to click
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   click(target) {
     return this.act({ do: "click", target }, `click ${describeTarget(target)}`);
   }
 
-  /** Types into a target found by role and name, replacing its value. */
+  /**
+   * Types into a target found by role and name, replacing its value.
+   *
+   * @param {Target} target What to fill
+   * @param {string} value The new value
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   fill(target, value) {
     return this.act(
       { do: "fill", target, value },
@@ -79,7 +113,13 @@ export class Tab {
     );
   }
 
-  /** Chooses an option of a native select by its label. */
+  /**
+   * Chooses an option of a native select by its label.
+   *
+   * @param {Target} target The select
+   * @param {string} value The option label
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   select(target, value) {
     return this.act(
       { do: "select", target, value },
@@ -87,23 +127,44 @@ export class Tab {
     );
   }
 
-  /** Ticks a checkbox or switch. */
+  /**
+   * Ticks a checkbox or switch.
+   *
+   * @param {Target} target The checkbox or switch
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   check(target) {
     return this.act({ do: "check", target }, `check ${describeTarget(target)}`);
   }
 
-  /** Presses a key, on a target or on the page. */
+  /**
+   * Presses a key, on a target or on the page.
+   *
+   * @param {string} key The key
+   * @param {Target} [target] Where to press it
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   press(key, target) {
     const where = target ? ` in ${describeTarget(target)}` : "";
     return this.act({ do: "press", key, target }, `press ${key}${where}`);
   }
 
-  /** Records the page as it is now. */
+  /**
+   * Records the page as it is now.
+   *
+   * @param {string} label What the step records
+   * @returns {Promise<Outcome & { folder: string }>} The outcome
+   */
   snapshot(label) {
     return this.act({ do: "snapshot" }, label);
   }
 
-  /** Signs an account of the journey in through the sign-in form. */
+  /**
+   * Signs an account of the journey in through the sign-in form.
+   *
+   * @param {string} account The account name
+   * @returns {Promise<Outcome | { ok: boolean, url: string, error: string }>} The outcome of the last sign-in step, or a failure without a snapshot when the journey has no such account
+   */
   async signIn(account) {
     const credentials = this.context.state.accounts?.[account];
     const outcome = credentials
@@ -127,7 +188,12 @@ export class Tab {
     return outcome;
   }
 
-  /** The Playwright locator of a target. */
+  /**
+   * The Playwright locator of a target.
+   *
+   * @param {Target} target What to find
+   * @returns {import("playwright-core").Locator} The locator
+   */
   locator(target) {
     return locate(this.page, target);
   }
@@ -135,6 +201,10 @@ export class Tab {
   /**
    * A check that a target becomes visible, or with `{ hidden: true }`
    * hidden or absent, within the timeout.
+   *
+   * @param {Target} target What to wait for
+   * @param {Timeout & { hidden?: boolean }} [options] Whether to wait for it to be hidden, and how long
+   * @returns {Promise<Check>} The check
    */
   async visible(target, options = {}) {
     const state = options.hidden ? "hidden" : "visible";
@@ -152,7 +222,13 @@ export class Tab {
     };
   }
 
-  /** A check that a target is enabled (or, with `{ disabled: true }`, disabled). */
+  /**
+   * A check that a target is enabled (or, with `{ disabled: true }`, disabled).
+   *
+   * @param {Target} target The control
+   * @param {Timeout & { disabled?: boolean }} [options] Whether to expect it disabled, and how long
+   * @returns {Promise<Check>} The check
+   */
   async enabled(target, options = {}) {
     const element = this.locator(target).first();
     const disabled = await element
@@ -166,7 +242,13 @@ export class Tab {
     };
   }
 
-  /** A check that the page shows (or, with `{ not: true }`, never shows) text matching `pattern`. */
+  /**
+   * A check that the page shows (or, with `{ not: true }`, never shows) text matching `pattern`.
+   *
+   * @param {RegExp} pattern The text to match
+   * @param {Timeout & { not?: boolean }} [options] Whether the text must never show, and how long
+   * @returns {Promise<Check>} The check
+   */
   async shows(pattern, options = {}) {
     const deadline = Date.now() + (options.timeoutMs ?? EXPECT_TIMEOUT_MS);
     let text = "";
@@ -185,7 +267,13 @@ export class Tab {
     };
   }
 
-  /** A check that the current path matches `pattern` within the timeout. */
+  /**
+   * A check that the current path matches `pattern` within the timeout.
+   *
+   * @param {RegExp} pattern The path to match
+   * @param {Timeout} [options] How long to wait
+   * @returns {Promise<Check>} The check
+   */
   async at(pattern, options = {}) {
     const reached = await this.page
       .waitForURL((url) => pattern.test(url.pathname), {
@@ -202,7 +290,13 @@ export class Tab {
     };
   }
 
-  /** A check on how many targets match. */
+  /**
+   * A check on how many targets match.
+   *
+   * @param {Target} target What to count
+   * @param {number} expected How many should match
+   * @returns {Promise<Check>} The check
+   */
   async count(target, expected) {
     const actual = await this.locator(target).count();
     return {
@@ -212,7 +306,12 @@ export class Tab {
     };
   }
 
-  /** The current value of a form field. */
+  /**
+   * The current value of a form field.
+   *
+   * @param {Target} target The form field
+   * @returns {Promise<string>} The value
+   */
   value(target) {
     return this.locator(target)
       .first()