@antelopejs/dms 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v0.16.0
+
+[compare changes](https://github.com/AntelopeJS/dms/compare/v0.15.1...v0.16.0)
+
+### 📖 Documentation
+
+- **readme:** Start the demos with npx @antelopejs/core ([#753](https://github.com/AntelopeJS/dms/pull/753))
+- **readme:** Show the Meet and DMS films, with new GIFs ([1e3f7694](https://github.com/AntelopeJS/dms/commit/1e3f7694))
+- **readme:** Link the read-only live demo ([#665](https://github.com/AntelopeJS/dms/pull/665))
+
+### 🏡 Chore
+
+- Land the cleanup campaign on main ([#761](https://github.com/AntelopeJS/dms/pull/761))
+- **release:** @antelopejs/interface-dms v0.12.0 ([0e6b850d](https://github.com/AntelopeJS/dms/commit/0e6b850d))
+
+### ❤️ Contributors
+
+- Antony Rizzitelli ([@Upd4ting](http://github.com/Upd4ting))
+
 ## v0.15.1
 
 [compare changes](https://github.com/AntelopeJS/dms/compare/v0.15.0...v0.15.1)

package/README.md

@@ -2,15 +2,15 @@
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AntelopeJS/dms/main/packages/dms/frontend-vue/layers/dms-layout/public/images/antelope-logo/dark.svg">
-  <img alt="Antelope DMS" src="https://raw.githubusercontent.com/AntelopeJS/dms/main/packages/dms/frontend-vue/layers/dms-layout/public/images/antelope-logo/light.svg" height="72">
+  <img alt="Antelope DMS" src="https://raw.githubusercontent.com/AntelopeJS/dms/main/packages/dms/frontend-vue/layers/dms-layout/public/images/antelope-logo/light.svg" data-illustration height="72">
 </picture>
 
-# @antelopejs/dms
+# `@antelopejs/dms`
 
-<a href="https://www.npmjs.com/package/@antelopejs/dms"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/dms?style=for-the-badge&labelColor=000000&color=000000"></a>
-<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/dms?style=for-the-badge&labelColor=000000&color=000000"></a>
-<a href="https://discord.gg/g4pFt6eXqu"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
-<a href="https://dms.antelopejs.com/docs"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
+<a href="https://www.npmjs.com/package/@antelopejs/dms"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/dms?style=for-the-badge&labelColor=000000&color=000000" data-illustration></a>
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/dms?style=for-the-badge&labelColor=000000&color=000000" data-illustration></a>
+<a href="https://discord.gg/g4pFt6eXqu"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" data-illustration></a>
+<a href="https://dms.antelopejs.com/docs"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" data-illustration></a>
 
 **Admin dashboards for AntelopeJS, declared in TypeScript on the backend.**
 
@@ -18,7 +18,7 @@
 
 </div>
 
-![A DMS dashboard: a period selector, KPI cards, a sales chart and ranked products](https://raw.githubusercontent.com/AntelopeJS/dms/main/packages/dms/docs/images/template-dashboard.png)
+![The Helio dashboard of the demo template: KPI cards, a revenue chart and the period selector](./docs/images/captures/helio-dashboard.webp)
 
 ## What it does
 
@@ -43,23 +43,21 @@ The DMS also needs an API module, a module implementing the database interface,
 
 ## Quick start
 
-Clone [template-dms-demo](https://github.com/AntelopeJS/template-dms-demo), which loads the DMS, its companions and a seeded demo application. It needs Node.js 22, pnpm and a MongoDB on `localhost:27017`.
+Create a project from the `template-dms-demo` template, which loads the DMS, its companion modules and Helio, a demo back office for a solar installer. It needs the Node.js and pnpm releases the template pins, and a MongoDB on `localhost:27017`.
 
 ```bash
-git clone https://github.com/AntelopeJS/template-dms-demo.git my-app
+npx @antelopejs/core project init my-app --template dms-demo
 cd my-app
-pnpm install
-pnpm --dir frontend-vue install
-cat > .env <<EOF
-DMS_API_BASE_URL=http://localhost:5010
-DMS_SESSION_SECRET=$(openssl rand -hex 32)
-EOF
-pnpm exec ajs project modules install
 pnpm dev            # backend on http://localhost:5010
-pnpm frontend:dev   # dashboard on http://localhost:3001, in a second terminal
 ```
 
-Open the address the backend logs after `No owner exists yet` and create the first administrator. A page is a class whose static fields are blocks:
+When the backend answers, start the dashboard in a second terminal, from the same folder:
+
+```bash
+pnpm frontend:dev   # dashboard on http://localhost:3001
+```
+
+Open the address that the backend logs after `No owner exists yet`, and create the first administrator. The [Quickstart](https://dms.antelopejs.com/docs/getting-started/quickstart) walks through each step. A page is a class whose static fields are blocks:
 
 ```ts
 import { PageController, RegisterPage, pagesCategory } from "@antelopejs/interface-dms/page";
@@ -77,14 +75,26 @@ export class SalesPage extends PageController("sales", {
 
 ## Compatibility
 
-| `@antelopejs/dms` | `@antelopejs/interface-dms` | `@antelopejs/dms-frontend` (renderer) |
-| --- | --- | --- |
-| 0.9 | 0.7 | `>=0.6.1 <0.7.0` |
-| 0.8 | 0.6 | `>=0.5.2 <0.6.0` |
-
-**Embedded / AdonisJS 6**: tested with `@antelopejs/core` 1.15.2, `@antelopejs/dms` 0.9.2 and `@antelopejs/dms-frontend` 0.6.1 in an AdonisJS 6 application (see [Run the DMS inside AdonisJS](https://dms.antelopejs.com/docs/getting-started/adonisjs)).
-
-`@antelopejs/dms` 0.9.2 needs `@antelopejs/core` `>=1.15.2 <2` (its peer dependency). Every renderer release is listed in the frontend's [compatibility table](https://dms.antelopejs.com/docs/frontend/introduction#compatibility).
+<!-- antelopejs-docs-compat:start -->
+
+| Package                                     | Supported                                                                  | Tested with                                                          |
+| ------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `@antelopejs/core`                          | `>=1.17.0 <2`                                                              | `1.17.0`                                                             |
+| `@antelopejs/interface-api`                 | `>=0.2.0 <1.0.0`                                                           | `0.2.0`                                                              |
+| `@antelopejs/interface-api-util`            | `>=0.3.0 <1.0.0`                                                           | `0.3.0`                                                              |
+| `@antelopejs/interface-core`                | `>=0.4.0 <1.0.0`                                                           | `0.4.0`                                                              |
+| `@antelopejs/interface-data-api`            | `>=0.6.0 <1.0.0`                                                           | `0.6.0`                                                              |
+| `@antelopejs/interface-database`            | `>=0.3.0 <1.0.0`                                                           | `0.3.0`                                                              |
+| `@antelopejs/interface-database-decorators` | `>=0.2.0 <1.0.0`                                                           | `0.2.0`                                                              |
+| `@antelopejs/interface-dms`                 | `>=0.12.0 <0.13.0`                                                         | `0.12.0`                                                             |
+| `@antelopejs/interface-dms-automation`      | `file:../../.campaign/tgz/antelopejs-interface-dms-automation-b4bc5d2.tgz` | `file:.campaign/tgz/antelopejs-interface-dms-automation-b4bc5d2.tgz` |
+| `@antelopejs/interface-email`               | `>=0.0.6 <1.0.0`                                                           | `0.0.6`                                                              |
+| `@antelopejs/interface-file-storage`        | `>=0.1.4 <1.0.0`                                                           | `0.1.4`                                                              |
+| `@antelopejs/interface-redis`               | `>=0.0.9 <1.0.0`                                                           | `0.0.9`                                                              |
+
+<!-- antelopejs-docs-compat:end -->
+
+Each DMS release declares the renderer releases it runs on in `engines["@antelopejs/dms-frontend"]` of its frontend module, and the frontend's [compatibility table](https://dms.antelopejs.com/docs/frontend/introduction#compatibility) lists the renderer release line of each DMS release it covers. The DMS also runs embedded in an AdonisJS application: see [Run the DMS inside AdonisJS](https://dms.antelopejs.com/docs/getting-started/adonisjs).
 
 ## Documentation
 

package/bin/control/base.mjs

@@ -24,8 +24,8 @@ function baseCache() {
  * A prepared worktree of the run's base ref, built once per commit under
  * `~/.cache/dms-control/base/<sha>` with the skill's `prepare` commands.
  *
- * @param {Record<string, any>} state The run
- * @param {Record<string, any>} skill The skill
+ * @param {import("./run-state.mjs").RunState} state The run
+ * @param {import("./verify/skill.mjs").Skill} skill The skill
  * @returns {{ sha: string, dir: string }} The base commit and its worktree
  */
 function baseCheckout(state, skill) {
@@ -47,12 +47,17 @@ function baseCheckout(state, skill) {
  * containment journey writes data with the base version inside `action`
  * and reads it back with the head version after it.
  *
- * @param {Record<string, any>} state The run
- * @param {Record<string, any>} skill The skill, whose `prepare` builds the base
+ * @param {import("./run-state.mjs").RunState} state The run
+ * @param {import("./verify/skill.mjs").Skill} skill The skill, whose `prepare` builds the base
  * @param {(sha: string) => Promise<void>} action What to do against the base backend
  * @returns {Promise<string>} The base commit
  */
 export async function withBaseBackend(state, skill, action) {
+  if (state.renderer) {
+    throw new Error(
+      "A run with --renderer has no base backend: the skill's prepare builds the renderer's repository, not the playground's.",
+    );
+  }
   const base = baseCheckout(state, skill);
   const playground = join(base.dir, relative(state.repo, state.playground));
   state.baseRoot = join(state.dir, "base-root");

package/bin/control/browser-client.mjs

@@ -1,3 +1,5 @@
+import { isOutcome } from "./browser-wire.mjs";
+import { decode } from "./json.mjs";
 import { CONTROL_BIN } from "./stack.mjs";
 import { freePort, isAlive, startDetached, waitForOk } from "./processes.mjs";
 import { saveRun } from "./run-state.mjs";
@@ -5,6 +7,10 @@ import { nextFolder } from "./session.mjs";
 
 const READY_TIMEOUT_MS = 60_000;
 
+/**
+ * @param {import("./run-state.mjs").RunState} state The run
+ * @returns {Promise<import("./run-state.mjs").ServerRecord>} Its running browser server, started if it was not
+ */
 async function browserServer(state) {
   if (state.browser && isAlive(state.browser.pid)) return state.browser;
   const port = await freePort();
@@ -28,17 +34,30 @@ async function browserServer(state) {
  * page, both kept between commands. The action, the URL, the ARIA snapshot
  * and a screenshot go to `<run>/evidence/browser/NN-<label>/`.
  *
- * @param {Record<string, any>} state The run
- * @param {Record<string, any>} request The action: `do`, `account`, `tab`, and the action's target, value, key or path
+ * @param {import("./run-state.mjs").RunState} state The run
+ * @param {Omit<import("./browser.mjs").BrowserRequest, "folder">} request The action: `do`, `account`, `tab`, and the action's target, value, key or path
  * @param {string} label What the step does
  * @returns {Promise<{ ok: boolean, url: string, error: string | null, aria: string, folder: string }>} The outcome
  */
 export async function browserCommand(state, request, label) {
   const server = await browserServer(state);
   const folder = nextFolder(state, "browser", label);
-  const response = await fetch(`http://127.0.0.1:${server.port}/`, {
+  const outcome = await postAction(server.port, { ...request, folder });
+  return { ...outcome, folder };
+}
+
+/**
+ * @param {number} port The browser server's port
+ * @param {import("./browser.mjs").BrowserRequest} request The action
+ * @returns {Promise<import("./browser.mjs").Outcome>} The server's answer
+ * @throws When the answer is not an outcome
+ */
+export async function postAction(port, request) {
+  const response = await fetch(`http://127.0.0.1:${port}/`, {
     method: "POST",
-    body: JSON.stringify({ ...request, folder }),
+    body: JSON.stringify(request),
   });
-  return { ...(await response.json()), folder };
+  /** @type {unknown} */
+  const answer = await response.json();
+  return decode(isOutcome, answer, "the browser server's answer", "an outcome");
 }

package/bin/control/browser-wire.mjs

@@ -0,0 +1,41 @@
+import {
+  isBoolean,
+  isNumber,
+  isString,
+  nullable,
+  objectOf,
+  oneOf,
+} from "./json.mjs";
+
+/**
+ * What the `dms-control browser` client and the browser server post to each
+ * other, checked on both sides.
+ */
+
+const isRoleName = { role: isString };
+const isRoleOptions = { name: isString, exact: isBoolean };
+
+/** @type {import("./json.mjs").Guard<import("./browser.mjs").BrowserRequest>} One browser action, as the client posts it */
+export const isBrowserRequest = objectOf(
+  { do: isString, account: isString, tab: isString, folder: isString },
+  {
+    target: objectOf(isRoleName, {
+      ...isRoleOptions,
+      nth: isNumber,
+      within: objectOf(isRoleName, isRoleOptions),
+    }),
+    value: isString,
+    key: isString,
+    path: isString,
+    state: oneOf(["attached", "detached", "visible", "hidden"]),
+    timeoutMs: isNumber,
+  },
+);
+
+/** @type {import("./json.mjs").Guard<import("./browser.mjs").Outcome>} What the server answers for one action */
+export const isOutcome = objectOf({
+  ok: isBoolean,
+  url: isString,
+  error: nullable(isString),
+  aria: isString,
+});

package/bin/control/browser-wire.test.mjs

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import test from "node:test";
+import { answerRequest } from "./browser.mjs";
+import { postAction } from "./browser-client.mjs";
+import { isOutcome } from "./browser-wire.mjs";
+import { decode } from "./json.mjs";
+import { freePort } from "./processes.mjs";
+
+const REQUEST = {
+  do: "click",
+  account: "admin",
+  tab: "main",
+  folder: "/run/evidence/browser/01-click",
+  target: { role: "button", name: "Invite", nth: 1 },
+};
+const OUTCOME = { ok: true, url: "/", error: null, aria: "- button" };
+
+/**
+ * @param {string} body What a client posted
+ * @returns {Promise<{ answer: import("./browser.mjs").Outcome, handled: unknown[] }>} The answer and the requests that reached the handler
+ */
+async function answered(body) {
+  /** @type {unknown[]} */
+  const handled = [];
+  const answer = await answerRequest(body, (request) => {
+    handled.push(request);
+    return Promise.resolve(OUTCOME);
+  });
+  /** @type {unknown} */
+  const posted = JSON.parse(answer);
+  return {
+    answer: decode(isOutcome, posted, "the answer", "an outcome"),
+    handled,
+  };
+}
+
+await test("a posted request reaches the handler as written and its outcome is the answer", async () => {
+  const { answer, handled } = await answered(JSON.stringify(REQUEST));
+  assert.deepEqual(handled, [REQUEST]);
+  assert.deepEqual(answer, OUTCOME);
+});
+
+await test("a request with a field of the wrong type is answered as a failed action, not run", async () => {
+  const { answer, handled } = await answered(
+    JSON.stringify({ ...REQUEST, tab: 5 }),
+  );
+  assert.deepEqual(handled, []);
+  assert.equal(answer.ok, false);
+  assert.match(
+    answer.error ?? "",
+    /browser request is malformed: expected a browser action/,
+  );
+});
+
+await test("a request without an action is answered as a failed action, not run", async () => {
+  const { answer, handled } = await answered(
+    JSON.stringify({ account: "admin" }),
+  );
+  assert.deepEqual(handled, []);
+  assert.match(answer.error ?? "", /malformed: expected a browser action/);
+});
+
+await test("a body that is no JSON is answered as a failed action", async () => {
+  const { answer, handled } = await answered("{");
+  assert.deepEqual(handled, []);
+  assert.equal(answer.ok, false);
+});
+
+/**
+ * @param {import("node:test").TestContext} t The test
+ * @param {unknown} answer What the server answers
+ * @returns {Promise<number>} The server's port
+ */
+async function serving(t, answer) {
+  const port = await freePort();
+  const server = createServer((_incoming, outgoing) => {
+    outgoing.end(JSON.stringify(answer));
+  });
+  await new Promise((resolve) => server.listen(port, "127.0.0.1", resolve));
+  t.after(() => server.close());
+  return port;
+}
+
+await test("the client returns the server's outcome", async (t) => {
+  const port = await serving(t, OUTCOME);
+  assert.deepEqual(await postAction(port, REQUEST), OUTCOME);
+});
+
+await test("the client refuses an answer that is no outcome", async (t) => {
+  const port = await serving(t, { ...OUTCOME, ok: "yes" });
+  await assert.rejects(
+    postAction(port, REQUEST),
+    /the browser server's answer is malformed: expected an outcome/,
+  );
+});

package/bin/control/browser.mjs

@@ -1,9 +1,22 @@
 import { writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { join } from "node:path";
+import { isBrowserRequest } from "./browser-wire.mjs";
+import { describeFailure } from "./failure.mjs";
+import { decode } from "./json.mjs";
 import { importFrom } from "./mongo.mjs";
 import { loadRun } from "./run-state.mjs";
 
+/**
+ * @typedef {import("playwright-core").Browser} Browser
+ * @typedef {import("playwright-core").BrowserContext} BrowserContext
+ * @typedef {import("playwright-core").Locator} Locator
+ * @typedef {import("playwright-core").Page} Page
+ * @typedef {{ ok: boolean, url: string, error: string | null, aria: string }} Outcome
+ * @typedef {{ do: string, baseUrl: string, target?: Target, value?: string, key?: string, path?: string, state?: "attached" | "detached" | "visible" | "hidden", timeoutMs?: number }} Action
+ * @typedef {Omit<Action, "baseUrl"> & { account: string, tab: string, folder: string }} BrowserRequest
+ */
+
 const ACTION_TIMEOUT_MS = 15_000;
 const NAVIGATION_TIMEOUT_MS = 60_000;
 const SETTLE_MS = 400;
@@ -13,9 +26,11 @@ const VIEWPORT = { width: 1280, height: 900 };
  * Launches the headless Chromium that playwright-core pins.
  *
  * @param {string[]} from Folders to resolve playwright-core from
- * @returns {Promise<any>} The Playwright browser
+ * @returns {Promise<Browser>} The Playwright browser
  */
 export async function launchBrowser(from) {
+  /** @type {typeof import("playwright-core")} */
+  // oxlint-disable-next-line typescript/no-unsafe-assignment -- importFrom resolves playwright-core by path from the project under test at run time and answers its namespace as any, which the JSDoc type binds to Playwright's own declarations.
   const { chromium } = await importFrom("playwright-core", from);
   return chromium.launch({ headless: true });
 }
@@ -24,8 +39,8 @@ export async function launchBrowser(from) {
  * A new browser context: one per account, so cookies never leak between
  * the users a journey plays.
  *
- * @param {any} browser The Playwright browser
- * @returns {Promise<any>} The context
+ * @param {Browser} browser The Playwright browser
+ * @returns {Promise<BrowserContext>} The context
  */
 export function newContext(browser) {
   return browser.newContext({
@@ -39,15 +54,15 @@ export function newContext(browser) {
  * What an action targets: an ARIA role and accessible name, optionally
  * inside another one (`within`), or the n-th of several matches.
  *
- * @typedef {{ role: string, name?: string, exact?: boolean, nth?: number, within?: { role: string, name?: string } }} Target
+ * @typedef {{ role: string, name?: string | RegExp, exact?: boolean, nth?: number, within?: { role: string, name?: string | RegExp, exact?: boolean } }} Target
  */
 
 /**
  * The locator of a target, by role and accessible name, as a user finds it.
  *
- * @param {any} page The Playwright page
+ * @param {Page} page The Playwright page
  * @param {Target} target What to find
- * @returns {any} The locator
+ * @returns {Locator} The locator
  */
 export function locate(page, target) {
   const scope = target.within
@@ -76,6 +91,7 @@ export function describeTarget(target) {
   return target.within ? `${own} in ${describeTarget(target.within)}` : own;
 }
 
+/** @type {Record<string, (page: Page, action: Action) => Promise<unknown> | undefined>} */
 const ACTIONS = {
   goto: (page, action) =>
     page.goto(new URL(action.path, action.baseUrl).href, {
@@ -123,7 +139,7 @@ export const ACTION_NAMES = Object.keys(ACTIONS);
  * Writes what the page shows into `folder`: `url.txt`, `aria.yml` (the ARIA
  * snapshot of the body) and `screenshot.png`.
  *
- * @param {any} page The Playwright page
+ * @param {Page} page The Playwright page
  * @param {string} folder The evidence folder
  * @returns {Promise<string>} The ARIA snapshot
  */
@@ -132,7 +148,10 @@ export async function capture(page, folder) {
   const aria = await page
     .locator("body")
     .ariaSnapshot({ timeout: ACTION_TIMEOUT_MS })
-    .catch((error) => `snapshot failed: ${error.message}`);
+    .catch(
+      (/** @type {unknown} */ error) =>
+        `snapshot failed: ${describeFailure(error)}`,
+    );
   writeFileSync(join(folder, "aria.yml"), `${aria}\n`);
   await page
     .screenshot({
@@ -148,10 +167,10 @@ export async function capture(page, folder) {
  * Runs one action on a page, then captures the page into `folder`. A target
  * that is missing, hidden or disabled past the timeout fails the action.
  *
- * @param {any} page The Playwright page
- * @param {{ do: string, baseUrl: string, target?: Target, value?: string, key?: string, path?: string, state?: string, timeoutMs?: number }} action What to do
+ * @param {Page} page The Playwright page
+ * @param {Action} action What to do
  * @param {string} folder The evidence folder
- * @returns {Promise<{ ok: boolean, url: string, error: string | null, aria: string }>} The outcome
+ * @returns {Promise<Outcome>} The outcome
  */
 export async function perform(page, action, folder) {
   const run = ACTIONS[action.do];
@@ -171,7 +190,7 @@ export async function perform(page, action, folder) {
       .catch(() => undefined);
     await page.waitForTimeout(SETTLE_MS);
   } catch (failure) {
-    error = String(failure?.message ?? failure).split("\n")[0];
+    error = describeFailure(failure).split("\n")[0];
   }
   const aria = await capture(page, folder);
   return { ok: error === null, url: page.url(), error, aria };
@@ -180,10 +199,10 @@ export async function perform(page, action, folder) {
 /**
  * Signs an account in through the sign-in form, the way a user does.
  *
- * @param {any} page The Playwright page
+ * @param {Page} page The Playwright page
  * @param {{ email: string, password: string }} credentials The account
  * @param {{ baseUrl: string, folder: (label: string) => string }} options Where the frontend is and where evidence goes
- * @returns {Promise<{ ok: boolean, url: string, error: string | null, aria: string }>} The outcome of the last step
+ * @returns {Promise<Outcome>} The outcome of the last step
  */
 export async function signInThroughForm(page, credentials, options) {
   const steps = [
@@ -221,6 +240,35 @@ export async function signInThroughForm(page, credentials, options) {
   };
 }
 
+/**
+ * @param {unknown} error What the action threw
+ * @returns {Outcome} The failed outcome
+ */
+function failedOutcome(error) {
+  return { ok: false, url: "", error: describeFailure(error), aria: "" };
+}
+
+/**
+ * Decodes a posted request and answers it. A body that is no valid request
+ * is answered as a failed action, like any action that throws.
+ *
+ * @param {string} body What the client posted
+ * @param {(request: BrowserRequest) => Promise<Outcome>} handle Runs one action
+ * @returns {Promise<string>} The outcome as JSON
+ */
+export function answerRequest(body, handle) {
+  return Promise.resolve()
+    .then(() => {
+      /** @type {unknown} */
+      const posted = JSON.parse(body);
+      return handle(
+        decode(isBrowserRequest, posted, "browser request", "a browser action"),
+      );
+    })
+    .catch(failedOutcome)
+    .then((outcome) => JSON.stringify(outcome));
+}
+
 /**
  * Serves the run's browser for `dms-control browser`: one context per
  * account and one page per tab name, kept between commands, driven by JSON
@@ -235,8 +283,15 @@ export async function signInThroughForm(page, credentials, options) {
 export async function serveBrowser(dir, from, port) {
   const browser = await launchBrowser(from);
   browser.on("disconnected", () => process.exit(0));
+  /** @type {Map<string, BrowserContext>} */
   const contexts = new Map();
+  /** @type {Map<string, Page>} */
   const pages = new Map();
+  /**
+   * @param {string} account The account
+   * @param {string} tab The tab name
+   * @returns {Promise<Page>} The tab's page
+   */
   const pageFor = async (account, tab) => {
     const key = `${account}/${tab}`;
     if (!pages.has(key)) {
@@ -246,6 +301,10 @@ export async function serveBrowser(dir, from, port) {
     }
     return pages.get(key);
   };
+  /**
+   * @param {BrowserRequest} request What the client posted
+   * @returns {Promise<Outcome>} The outcome
+   */
   const handle = async (request) => {
     const state = loadRun(dir);
     const page = await pageFor(request.account, request.tab);
@@ -270,21 +329,13 @@ export async function serveBrowser(dir, from, port) {
       outgoing.end("ok");
       return;
     }
+    /** @type {Buffer[]} */
     const chunks = [];
-    incoming.on("data", (chunk) => chunks.push(chunk));
+    incoming.on("data", (/** @type {Buffer} */ chunk) => chunks.push(chunk));
     incoming.on("end", () => {
-      handle(JSON.parse(Buffer.concat(chunks).toString("utf8")))
-        .then((result) => outgoing.end(JSON.stringify(result)))
-        .catch((error) =>
-          outgoing.end(
-            JSON.stringify({
-              ok: false,
-              url: "",
-              error: String(error?.message ?? error),
-              aria: "",
-            }),
-          ),
-        );
+      answerRequest(Buffer.concat(chunks).toString("utf8"), handle)
+        .then((answer) => outgoing.end(answer))
+        .catch(() => outgoing.destroy());
     });
   });
   await new Promise((resolve) => server.listen(port, "127.0.0.1", resolve));