browser-broker 0.1.0 → 0.2.0

package/.env.example

@@ -156,7 +156,9 @@
 # browser named in both lists above, so a browser added here gains its own
 # discovery and keeper-tab lines in the health report.
 
-# Which browser binary the signed-in browsers launch.
+# Which engine the signed-in browsers name. Does not decide which binary
+# launches: per-engine executable resolution is not built, so every browser
+# launches the automation library's own Chromium. See RELEASES.md.
 # Options: chrome, brave, msedge — all Chromium over the same remote-debugging
 #          protocol, which is why the choice is a path rather than a driver.
 # One engine per kind, never per browser: an engine per entry would put an
@@ -164,10 +166,9 @@
 # Default: msedge
 # BROKER_REGULAR_BROWSER_ENGINE=msedge
 
-# Which browser binary the clean-room browsers launch. MAY DIFFER from the
-# engine above: a person signs into the signed-in browsers by hand, so which
-# binary those are can follow what they already use, while nobody signs into
-# a clean-room browser at all.
+# Which engine the clean-room browsers name. Accepted and validated, and read
+# by nothing: one driver serves every browser in the process and only the
+# regular engine is handed to it, so a differing value reaches no launch.
 # Options: chrome, brave, msedge
 # Default: msedge
 # BROKER_PRIVATE_BROWSER_ENGINE=msedge

package/README.md

@@ -61,23 +61,33 @@ hanging the report.
 service to keep running: the process is started by whatever calls it and exits with it. So getting it
 working is an install and one more fetch below — there is no step after that.
 
-You need **Node 22.18 or newer**.
+You need **Node 22.18 or newer**. Either path below also needs a browser binary, which is a separate
+fetch from either install step — see [Browser binary](#browser-binary) once you've picked a path.
 
 ### From the registry
 
-The package ships compiled JavaScript, so nothing is built on your machine:
+The package ships compiled JavaScript, so **nothing is compiled** on your machine. That is not the
+same as nothing to set up: a browser binary is still owed, and this path does not fetch it — see
+[Browser binary](#browser-binary) below before your first `broker doctor`.
 
 ```bash
-npx browser-broker doctor
+npx -p browser-broker broker doctor
 ```
 
+The package installs two executables — `broker`, the command line, and `broker-tool`, the surface a
+client spawns — and neither is named for the package, so `npx browser-broker` cannot tell which you
+meant and refuses. `-p` names the package and the word after it names the executable.
+
 A client that spawns the tool surface names the same package, and npm revalidates the version on
 every run — so a published release arrives without anything being pulled or rebuilt by hand:
 
 ```json
 {
   "mcpServers": {
-    "browser-broker": { "command": "npx", "args": ["-y", "browser-broker"] }
+    "browser-broker": {
+      "command": "npx",
+      "args": ["-y", "-p", "browser-broker", "broker-tool"]
+    }
   }
 }
 ```
@@ -97,20 +107,8 @@ cd browser-broker
 npm install
 ```
 
-That compiles the one runtime dependency's native binding, which is *not* the only part of the install
-that does real work: this repository depends on `playwright-core`, not the full `playwright`
-distribution, precisely because the browser binary is spawned by this service, detached and by path,
-rather than downloaded and managed by the package. `playwright-core` does not fetch a browser on
-install, so a checkout that has never had one fetched by some other tooling has none, and `broker
-doctor`'s automation check will genuinely fail with exit code 11 until you run:
-
-```bash
-npx playwright-core install chromium
-```
-
-Run this once per machine, before the first `broker doctor`. It is the same install mechanism the
-full `playwright` package would run automatically on `npm install`; `playwright-core` just does not
-run it for you. Then run the broker itself:
+That compiles the one runtime dependency's native binding. It does not fetch a browser binary — see
+[Browser binary](#browser-binary) below before your first `broker doctor`. Then run the broker itself:
 
 ```bash
 node src/bin/broker.ts
@@ -134,6 +132,23 @@ To get the command on your path as `broker`, link the package from the checkout:
 npm link          # then: broker --help
 ```
 
+### Browser binary
+
+**Neither install path above fetches a browser.** This repository depends on `playwright-core`, not
+the full `playwright` distribution, precisely because the browser binary is spawned by this service,
+detached and by path, rather than downloaded and managed by the package. `playwright-core` does not
+fetch a browser on install, so a machine that has never had one fetched by some other tooling has
+none, and `broker doctor`'s automation check will genuinely fail with exit code 11 until you run:
+
+```bash
+npx playwright-core install chromium
+```
+
+Run this once per machine, before the first `broker doctor` — it applies whether you installed from
+the registry or from a checkout, because it is a fetch neither install step performs. It is the same
+install mechanism the full `playwright` package would run automatically on `npm install`;
+`playwright-core` just does not run it for you.
+
 ### Configuring it
 
 **Nothing needs setting.** Every value is an environment variable with a working default, so the
@@ -156,9 +171,16 @@ called, and a caller that names no browser gets the first signed-in one:
 BROKER_REGULAR_BROWSERS=regular,checkout      # persistent, signed in, at most 3
 BROKER_PRIVATE_BROWSERS=private               # ephemeral, at most 3
 BROKER_REGULAR_BROWSER_ENGINE=msedge          # chrome | brave | msedge
-BROKER_PRIVATE_BROWSER_ENGINE=msedge          # may differ from the line above
+BROKER_PRIVATE_BROWSER_ENGINE=msedge          # accepted and validated, and read by nothing
 ```
 
+**Neither engine variable changes which binary launches.** Resolving an engine name to an executable
+is deliberately not built, so every browser launches the automation library's own Chromium whichever
+engine is named, and a machine still has to fetch that Chromium once. The private variable goes one
+step less far than the regular one: a single driver serves every browser in the process and only the
+regular engine is handed to it, so the private value is validated at startup and then read by nothing
+at all. `RELEASES.md` has the fuller account.
+
 Two signed-in browsers is how two identities are exercised at once: tabs within one browser share
 its cookie jar, so they are isolated from other browsers and not from each other. **Note that each
 browser is a process before it holds a single tab**, which the tab budget does not count —
@@ -198,6 +220,24 @@ it is rarely the checkout. Nothing else is required: there is no port to configu
 issue, and no process to have started first — the client starts it, and it exits when the client
 closes the pipe.
 
+**If that configuration file is itself synchronised between machines, an absolute path is the one
+thing in it that cannot travel.** A home directory differs per machine and often per user, so one
+entry naming a checkout is correct on the machine it was written on and names nothing on the other
+— where it fails as a connection that closes immediately, which reads as a broken service rather
+than as a path that does not exist. Give each machine its own entry under its own server name, or
+point the shared entry at the published package, which carries no machine's path:
+
+```json
+{
+  "mcpServers": {
+    "browser-broker": {
+      "command": "npx",
+      "args": ["-y", "-p", "browser-broker", "broker-tool"]
+    }
+  }
+}
+```
+
 To point it at a store other than the default, add the environment to the same block:
 
 ```json

package/RELEASES.md

@@ -1,97 +1,255 @@
-# Release notes
-
-**What changes between versions, and specifically what changes *behaviour* on an installation that
-sets nothing.**
-
-That second half is the reason this file exists rather than the commit log being enough. A new
-setting with a neutral default is not news: an installation that does not set it behaves exactly as
-before. **A changed default is news**, because it moves an installation that has taken no action and
-made no decision. `docs/plans/DECISIONS.md` §6.3 puts a changed default here rather than in a quiet
-edit for that reason.
-
-Entries are newest first. Each names what moved, what an installation has to do about it, and what
-happens if it does nothing.
-
----
-
-## Unreleased
-
-### The package is published, and it ships compiled JavaScript
-
-**What moved.** The service is installable from the registry as `browser-broker`, so a caller can
-spawn it without a checkout. The manifest's `bin` entries now name emitted JavaScript under `dist/`
-rather than the TypeScript sources.
-
-**Why the build exists**, given that the development path deliberately has none: **Node refuses to
-strip types from any file under a `node_modules` path**, and an installed package is a directory
-under `node_modules`. A manifest whose `bin` named a `.ts` file would install cleanly and then fail
-on the machine of whoever installed it. There is no flag that changes this. The compiler therefore
-runs once per release rather than on every machine that consumes the package, and `erasableSyntaxOnly`
-stays on so the sources still run unbuilt — the two paths execute the same dialect.
-
-**What an installation has to do.** Nothing. A checkout is unaffected: `node src/bin/broker.ts` still
-runs the sources with no build. An installation that would rather not track a checkout can point at
-the package instead, and npm revalidates the version on every spawn:
-
-```json
-{ "command": "npx", "args": ["-y", "browser-broker"] }
-```
-
-**Worth weighing before switching:** `npx` performs a registry round-trip on every spawn, costing
-seconds where a path on disk costs a fraction of one. It buys an upgrade path, not speed.
-
-**One surface changes what it reports.** The tool handshake's `serverInfo.version` was the literal
-`0.0.0` while the package was unversioned, and now reads the manifest — so a client logging it sees
-the released version rather than a placeholder.
-
-
-### ⚠ Behaviour change: the default browser engine is Edge
-
-**What moved.** A browser launched by this service uses **`msedge`** by default. The previous
-behaviour was to launch whatever `chromium.executablePath()` resolved to — the Chromium build the
-automation library had fetched.
-
-**Why.** Edge is present on every Windows machine, so a fresh install runs with nothing set, with no
-separate browser download step. That is `DECISIONS.md` §6.1's *"a fresh install runs with nothing
-set"* applied to the one prerequisite `npm install` genuinely could not cover.
-
-**What an installation has to do.** Nothing, if Edge is acceptable. To keep the prior behaviour, or
-to pick a different browser, set the engine per kind:
-
-```bash
-BROKER_REGULAR_BROWSER_ENGINE=chrome     # chrome | brave | msedge
-BROKER_PRIVATE_BROWSER_ENGINE=chrome     # may differ from the line above
-```
-
-**If it does nothing:** browsers launch under Edge. **Profiles are per browser and are not shared
-between engines**, so an installation whose signed-in profile was established under a different
-binary will find that browser signed out, and a person will be asked to sign in once more with
-`broker login`. Nothing is destroyed — `setup.profile_never_destroyed` still holds, and the earlier
-profile directory is left exactly where it is.
-
-### Browsers are a configured list, and `browser` on a claim is optional
-
-**What moved.** Two things, both reversals of recorded decisions — the argument for each is in
-`DECISIONS.md` §13i:
-
-- **The fixed pair of browsers becomes a bounded list per kind**, at most three each, named in
-  configuration. A name is what a caller claims by and what its profile directory is called.
-- **`browser` on `browser_claim` becomes optional.** Unstated resolves to the first signed-in
-  browser; `regular` or `private` resolves to the first of that kind; a configured name resolves to
-  that browser exactly.
-
-**What an installation has to do.** Nothing. The defaults name one browser of each kind, `regular`
-and `private`, which is the pair that existed before — so an installation that sets nothing has the
-same two browsers under the same two names, and a caller that states `browser` explicitly is
-unaffected.
-
-**Worth reading before configuring more than the default two:** the tab budget counts *tabs*, and
-each browser costs a process **before it holds a single tab**. `BROKER_TAB_BUDGET=15` with six
-browsers is six browser processes, plus up to fifteen tabs, plus six keeper tabs that are not
-counted against the budget at all. `.env.example` states this beside the variables.
-
-**One schema step.** The store gains a `kind` column on `browsers` and drops the check constraint
-that limited a browser's name to two literals. It is applied on the next spawn, like every step, and
-the two existing rows are backfilled to their own kinds. **A store stepped by this build is not
-readable by an earlier one**, which is the ordinary direction — a build refuses a store newer than
-itself rather than downgrading it.
+# Release notes
+
+**What changes between versions, and specifically what changes *behaviour* on an installation that
+sets nothing.**
+
+That second half is the reason this file exists rather than the commit log being enough. A new
+setting with a neutral default is not news: an installation that does not set it behaves exactly as
+before. **A changed default is news**, because it moves an installation that has taken no action and
+made no decision. `docs/plans/DECISIONS.md` §6.3 puts a changed default here rather than in a quiet
+edit for that reason.
+
+Entries are newest first. Each names what moved, what an installation has to do about it, and what
+happens if it does nothing.
+
+---
+
+## 0.2.0
+
+### ⚠ Behaviour change: `browser_status` asks whether the browser is still there
+
+**What moved.** Liveness was derived from rows and a clock. `browser_status` now asks the operating
+system whether the browser process is still answering, and a session that has died is let go, so the
+next acquisition relaunches rather than handing back a dead one.
+
+**Why this is a behaviour change and not a new check.** A lease whose browser had died reported
+`active`, with its expiry advancing, and no sequence of calls from the tool surface could recover it:
+releasing and reclaiming reached the same settled session, because the provider memoised it for the
+life of the process. The lease looked healthy from every angle a caller could see, and every page
+call on it failed.
+
+**What an installation has to do.** Nothing.
+
+**If it does nothing:** `browser_status` may report a browser gone where it reported `active`. **That
+is the check working, not a new fault appearing** — the browser was already gone, and the report is
+what changed.
+
+**The discriminator is load-bearing, and worth knowing about.** A row that says `running` while
+nothing answers is a browser that died; a row that says `stopped` never started. Acquisition is lazy,
+so a freshly granted lease on a machine with no browser installed is the ordinary case, not an error
+— probing without that distinction reports those leases as expired.
+
+### A claim says when a browser's tabs are stranded
+
+**What moved.** Three reports about tabs stranded mid-close:
+
+- **A grant now carries the count**, from the same query and the same instant. A browser holding a
+  backlog of tabs left by sessions killed mid-lease can grant a lease that cannot be used: the claim
+  succeeds and every navigate on it fails. Five consecutive claims were granted against such a
+  backlog before anything said so.
+- **`broker doctor` splits its stranded count per browser** rather than reporting one total, so
+  clearing one browser moves the number it is judged by.
+- **`broker reconcile` says when the tab blocking it belongs to the caller's own lease**, given a
+  `--session-id` to know it by.
+
+**What an installation has to do.** Nothing. The count rides on a grant that is genuinely
+granted — capacity was taken and the lease is active — so this is a note on a successful response
+rather than a refusal, and it is absent rather than zero when there is no backlog.
+
+### Command-line help lists the flags a command is refused for omitting, and an unknown flag is refused
+
+**What moved.** `broker claim --help` documents `--session-id` and `--purpose`, the two flags a claim
+is refused by name for omitting, and `broker reconcile --help` documents its optional `--session-id`.
+A help text listing three optional flags and neither required one teaches a reader how to call the
+command unsuccessfully.
+
+An unknown flag on `snapshot`, `events` or `reconcile` is refused, naming the flag and the accepted
+set, rather than being accepted and discarded.
+
+**What an installation has to do.** Nothing. A caller passing correct flags is unaffected.
+
+**The refusal's reach is narrower than the help fix, and worth stating plainly:** it covers those
+three commands. `claim` and the other operation commands parse their arguments by a different route,
+so `broker claim --session x` still does not name the typo. The completeness gate covering the
+documented commands is a hand-written list.
+
+### `act emulate` says how long its effect lasts
+
+**What moved.** An `emulate` result carries `emulationScope`, naming the bound the preference lives
+within and the path that works: emulate and capture within one invocation, or use the tool surface,
+where one connection spans the calls.
+
+The preference is scoped to the connection that set it — the tab survives and the emulation binding
+does not — so an emulate driven from a separate invocation than the capture that reads it returns
+`accepted` and changes nothing on the page. A reviewer checking dark mode that way gets a clean
+result and a light screenshot. The harm is the silence rather than the impersistence.
+
+**What an installation has to do.** Nothing; the field is additive. `pageDriven` is unchanged and
+still reports `true` here, because a browser genuinely was reached.
+
+### `browser_capture` can ask for a higher-resolution tier
+
+**What moved.** `browser_capture` takes `tier` — `"detail"` or `"max"` — and `reason` is bounded at 8
+to 200 characters and required alongside `tier="max"`. The default has no name and is what passing
+nothing gives you. A new refusal, `capture.tier_known`, names both accepted words when a tier is not
+one of them.
+
+The ladder was built end to end, and the pipeline refuses the top rung without a written reason,
+while no surface could populate either field — so the escalation rollup could only ever read as
+*nobody escalates*, which is a measurement of the surface rather than of any caller.
+
+**What an installation has to do.** Nothing. A capture that names no tier gets the default.
+
+### ⚠ Behaviour change: `wait_ms` on a navigate is now honoured
+
+**What moved.** `browser_navigate` has advertised a `wait_ms` argument for some time, typed,
+documented and accepted without complaint. **Nothing read it.** It now reaches the browser as the
+navigation's timeout, and it is bounded by the lease: a wait longer than the lease can live is
+refused, and the refusal names the accepted range rather than quietly clamping the value.
+
+**Why this is a behaviour change and not a new feature.** An installation that has set nothing is
+unaffected — but a *caller* that was already passing `wait_ms`, exactly as the schema invited, was
+having it discarded and now is not. Nothing about that caller's code changes and its behaviour does.
+
+**What an installation has to do.** Nothing. A caller passing no wait is unaffected: the argument is
+omitted rather than defaulted, so the browser's own default still applies, and this service does not
+invent a number the browser library owns.
+
+**Worth knowing before relying on it:** the wait bounds the **load**, and does not cover work the
+page starts afterwards. A canvas or a lazily-loaded region can still be unfinished when the call
+returns, so two captures differing only in this argument tell you nothing about how long the page
+was given to settle — see `browser_capture` on how to tell. An inert argument is worse than a
+missing one precisely because a caller draws conclusions from it, and that is the conclusion most
+easily drawn here.
+
+### Dialog and form-filling become reachable from the command line, and a contradictory answer is refused
+
+**What moved.** Two things a command-line caller had no way to do at all:
+
+- `act dialog` and `act fill_form` take nested arguments that the flat command-line parser could not
+  produce, so **no argument a person could type would ever parse**. They now assemble from ordinary
+  flags — `--accept` / `--dismiss`, `--prompt-text`, and a repeatable `--field`.
+- **A contradictory dialog answer is now refused instead of resolved silently.** Asking to accept
+  and dismiss the same dialog used to take whichever the code read first. A caller answering a
+  destructive `confirm()` deserves a refusal rather than a coin flip, and now gets one.
+
+**What an installation has to do.** Nothing. Callers already sending a single, coherent answer — by
+either surface — are unaffected.
+
+### Capture responses point at `compare_to`
+
+**What moved.** A capture response now carries a hint naming the comparison it could have made. The
+comparison itself already existed and is roughly two orders of magnitude cheaper than reading a
+screenshot back to answer *did this change* — and in all recorded history it had been used once,
+because nothing pointed at it.
+
+**What an installation has to do.** Nothing; the hint is additive. It is listed here because the
+cheapest path through this service was, in practice, unreachable, and a caller that never learned
+the verb existed was not making an informed choice.
+
+### Closing a tab is recorded, and the doctor counts what was left behind
+
+**What moved.** Tab closes now write their outcome, rows nothing could reach are settled, and
+`broker doctor` reports tabs stranded in `closing`. Without that, a released lease can leave its tab
+open with the record stuck mid-close and **nothing anywhere says so** — a state reachable only by
+looking at the browser.
+
+**What an installation has to do.** Nothing. **If it does nothing:** `broker doctor` may now report
+stranded tabs that no check could see before. That is the check working, not a new fault appearing.
+
+### The package is published, and it ships compiled JavaScript
+
+**What moved.** The service is installable from the registry as `browser-broker`, so a caller can
+spawn it without a checkout. The manifest's `bin` entries now name emitted JavaScript under `dist/`
+rather than the TypeScript sources.
+
+**Why the build exists**, given that the development path deliberately has none: **Node refuses to
+strip types from any file under a `node_modules` path**, and an installed package is a directory
+under `node_modules`. A manifest whose `bin` named a `.ts` file would install cleanly and then fail
+on the machine of whoever installed it. There is no flag that changes this. The compiler therefore
+runs once per release rather than on every machine that consumes the package, and `erasableSyntaxOnly`
+stays on so the sources still run unbuilt — the two paths execute the same dialect.
+
+**What an installation has to do.** Nothing. A checkout is unaffected: `node src/bin/broker.ts` still
+runs the sources with no build. An installation that would rather not track a checkout can point at
+the package instead, and npm revalidates the version on every spawn:
+
+```json
+{ "command": "npx", "args": ["-y", "-p", "browser-broker", "broker-tool"] }
+```
+
+The `-p` is not decoration: the package ships two executables and neither is named for the package,
+so `npx browser-broker` cannot choose between them and refuses to run at all.
+
+**Worth weighing before switching:** `npx` performs a registry round-trip on every spawn, costing
+seconds where a path on disk costs a fraction of one. It buys an upgrade path, not speed.
+
+**One surface changes what it reports.** The tool handshake's `serverInfo.version` was the literal
+`0.0.0` while the package was unversioned, and now reads the manifest — so a client logging it sees
+the released version rather than a placeholder.
+
+
+### The default browser engine is named Edge, but resolving it is not built yet
+
+**What moved.** `BROKER_REGULAR_BROWSER_ENGINE` and `BROKER_PRIVATE_BROWSER_ENGINE` default to
+**`msedge`** rather than being unset. `DECISIONS.md` §13i chose Edge as the default *name* because it
+is present on every Windows machine, applying §6.1's *"a fresh install runs with nothing set"* to
+which engine a fresh install prefers.
+
+**What this does not do: it does not change which binary launches, and it does not remove the browser
+download step.** Resolving an engine name to an executable path is deliberately not built (§13i) —
+`executablePathForEngine` only looks up a path this process was *given* for that engine, and nothing
+in this repository supplies one. So the launch still falls through to `chromium.executablePath()`
+regardless of which engine is named, and a machine that has never fetched a Chromium build still
+needs to, exactly as before this change. The earlier release note claiming this default removed the
+download step was wrong and is corrected here.
+
+**What an installation has to do.** Nothing, either way — the engine setting has no observable effect
+yet. Setting it now is preparation for when per-engine resolution is built, not a way to skip the
+browser fetch:
+
+```bash
+BROKER_REGULAR_BROWSER_ENGINE=chrome     # chrome | brave | msedge — has no effect on which binary launches
+BROKER_PRIVATE_BROWSER_ENGINE=chrome     # accepted and validated, and read by nothing — see below
+```
+
+Both are parsed and validated, and an unaccepted value is refused at startup and named — that much is
+finished. **The private variable goes one step less far than the regular one:** one driver serves
+every browser in a process, and only the regular engine is handed to it, so the private value is
+validated and then never read by anything at all. It is not merely ineffective downstream; it has no
+downstream.
+
+**If it does nothing:** browsers keep launching under whichever Chromium build `playwright-core`
+resolves, same as before this change. **No profile is signed out by setting an engine**, which an
+earlier note claimed would happen: a profile directory is named for its *browser*, not for an engine,
+so there is no engine-keyed profile to move between and nothing to sign in again.
+`setup.profile_never_destroyed` holds, as it did before. The per-engine profile and sign-in
+consequences described in `DECISIONS.md` §13i are what would follow once resolution is wired, and
+describe nothing that happens now.
+
+### Browsers are a configured list, and `browser` on a claim is optional
+
+**What moved.** Two things, both reversals of recorded decisions — the argument for each is in
+`DECISIONS.md` §13i:
+
+- **The fixed pair of browsers becomes a bounded list per kind**, at most three each, named in
+  configuration. A name is what a caller claims by and what its profile directory is called.
+- **`browser` on `browser_claim` becomes optional.** Unstated resolves to the first signed-in
+  browser; `regular` or `private` resolves to the first of that kind; a configured name resolves to
+  that browser exactly.
+
+**What an installation has to do.** Nothing. The defaults name one browser of each kind, `regular`
+and `private`, which is the pair that existed before — so an installation that sets nothing has the
+same two browsers under the same two names, and a caller that states `browser` explicitly is
+unaffected.
+
+**Worth reading before configuring more than the default two:** the tab budget counts *tabs*, and
+each browser costs a process **before it holds a single tab**. `BROKER_TAB_BUDGET=15` with six
+browsers is six browser processes, plus up to fifteen tabs, plus six keeper tabs that are not
+counted against the budget at all. `.env.example` states this beside the variables.
+
+**One schema step.** The store gains a `kind` column on `browsers` and drops the check constraint
+that limited a browser's name to two literals. It is applied on the next spawn, like every step, and
+the two existing rows are backfilled to their own kinds. **A store stepped by this build is not
+readable by an earlier one**, which is the ordinary direction — a build refuses a store newer than
+itself rather than downgrading it.

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "browser-broker",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "license": "MIT",
     "description": "Leases over tabs in a fixed set of browsers: bounded capacity, a queue, reclamation, and an enforced capture policy.",
     "type": "module",
@@ -19,12 +19,13 @@
         "check:operations": "node scripts/check-operations.mjs",
         "check:argument-refusals": "node scripts/check-argument-refusals.mjs",
         "check:injected-tests": "node scripts/check-injected-tests.mjs",
+        "check:argument-reachability": "node scripts/check-argument-reachability.mjs",
         "typecheck": "tsc --noEmit",
         "lint": "eslint .",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "test": "node --test \"tests/**/*.test.mjs\" \"tests/**/*.test.ts\"",
-        "check": "npm run check:external-refs && npm run check:doc-links && npm run check:arbitration && npm run check:capture-isolation && npm run check:artifact-path && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:install && npm run check:operations && npm run check:argument-refusals && npm run check:injected-tests",
+        "check": "npm run check:external-refs && npm run check:doc-links && npm run check:arbitration && npm run check:capture-isolation && npm run check:artifact-path && npm run typecheck && npm run lint && npm run format:check && npm test && npm run check:install && npm run check:operations && npm run check:argument-refusals && npm run check:argument-reachability && npm run check:injected-tests && npm run check:package",
         "check:arbitration": "node scripts/check-arbitration.mjs",
         "check:artifact-path": "node scripts/check-artifact-path.mjs",
         "build": "tsc --project tsconfig.build.json",

package/dist/src/adapter/conformance/service-subject.js

@@ -150,7 +150,11 @@ export async function makeServiceSubject() {
     return {
         service: runtime.service,
         // The fake's own log, which is what makes "a refusal touched no browser"
-        // checkable rather than asserted.
+        // checkable rather than asserted — and the entries are passed whole, so a
+        // case can also ask what the browser was told, not merely that it was
+        // spoken to. Dropping the arguments here would make a route that forwards
+        // an argument and one that discards it indistinguishable to every case in
+        // the table.
         driverCalls: () => driver.calls,
         // **The same predicate the capacity check uses**, per `driver.ts`'s
         // requirement for this reading — not a count of rows in `claims`, which

package/dist/src/browser/fake.js

@@ -402,8 +402,22 @@ export class FakeBrowserDriver {
                 this.#tabsFor(tab.browser).delete(tab.driverTabId);
                 return Promise.resolve();
             },
-            navigate: (tab, url) => {
-                const failure = this.#enter({ name: 'navigate', browser, tab, detail: { url } });
+            navigate: (tab, url, waitMs) => {
+                // The wait is recorded even though nothing here waits, because what a
+                // test needs to assert is that the service *asked* for it. An argument
+                // that is accepted and dropped between the caller and the driver looks
+                // identical from the outside to one that was honoured, and the only
+                // place that difference is observable is this log.
+                //
+                // Recorded as an absent key when the caller omitted it, rather than as
+                // an explicit undefined, so a test can tell "asked for no wait" from
+                // "asked for a wait of nothing".
+                const failure = this.#enter({
+                    name: 'navigate',
+                    browser,
+                    tab,
+                    detail: { url, ...(waitMs === undefined ? {} : { waitMs }) },
+                });
                 if (failure)
                     return Promise.reject(failure);
                 return Promise.resolve({ url, title: `fake page at ${url}`, status: 200 });

package/dist/src/browser/real.js

@@ -493,9 +493,17 @@ class RealBrowserSession {
      * The address after redirects rather than the one asked for, because those
      * differ constantly and the caller needs the one it got.
      */
-    async navigate(tab, url) {
+    async navigate(tab, url, waitMs) {
         const page = await this.#page(tab);
-        const response = await page.goto(url);
+        // Passed as the navigation's own timeout rather than as a pause taken
+        // afterwards, so a page that arrives early returns early and the argument
+        // only ever costs what the page costs.
+        //
+        // Absent means the library's configured default applies. Spread rather
+        // than passed as `{ timeout: undefined }`, because an explicit undefined
+        // and an omitted key are the same to this library only by convention, and
+        // relying on that convention would make the default this service's to own.
+        const response = await page.goto(url, ...(waitMs === undefined ? [] : [{ timeout: waitMs }]));
         return {
             url: page.url(),
             title: await page.title(),