browser-broker 0.2.0 → 0.4.0

package/.env.example

@@ -155,20 +155,3 @@
 # than quietly running the first three. `broker doctor` reports on every
 # browser named in both lists above, so a browser added here gains its own
 # discovery and keeper-tab lines in the health report.
-
-# 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
-# attribute back on the entry, which is what the two lists exist to avoid.
-# Default: msedge
-# BROKER_REGULAR_BROWSER_ENGINE=msedge
-
-# 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

@@ -92,9 +92,17 @@ every run — so a published release arrives without anything being pulled or re
 }
 ```
 
-Weigh that against spawning a checkout directly: `npx` costs a registry round-trip on every spawn,
-which is several seconds against a fraction of one for a path on disk. A machine that develops this
-service is better off pointing at its own tree; a machine that only *uses* it is better off here.
+`npx` costs a registry round-trip on every spawn — **measured at ~1.1s warm and ~3.7s cold**, against
+~0.4s for a path on disk. Against a typical 30s MCP connect timeout that is ample headroom, so prefer
+this form even on a machine that develops the service: a config file shared between machines cannot
+carry an absolute path that is correct on all of them.
+
+⚠️ **If handshakes start timing out, prune the npx cache before blaming npx.** An unpruned 837MB
+`_npx` cache once pushed spawn cost to 9.7–33.2s and blew a 30s connect timeout outright. The cost is
+the cache, not the mechanism. Two related traps: `--prefer-offline` can serve a packument that
+predates a release, so npx resolves a version it then cannot fetch (`ETARGET`); and the local npm
+cache lags the registry independently, so `npm cache clean --force` is the fix when `npm view` and
+`npx` disagree about what exists.
 
 ### From a checkout
 
@@ -170,16 +178,10 @@ called, and a caller that names no browser gets the first signed-in one:
 ```bash
 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          # 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.
+**Every browser launches the automation library's own Chromium**, which a machine fetches once. The
+browser a caller names selects an identity and its profile directory, not a different binary.
 
 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
@@ -381,9 +383,7 @@ surface is being built, and the one manual step is wired: `broker login` hands a
 browser and `broker doctor` reports whether the sign-in took. Read [`docs/ROLLOUT.md`](docs/ROLLOUT.md) for taking it from installed to sole route in an order that
 never leaves traffic unarbitrated, [`docs/plans/PLAN.md`](docs/plans/PLAN.md) for how it works,
 [`docs/plans/DECISIONS.md`](docs/plans/DECISIONS.md) for why it is shaped this way, and
-[`docs/plans/MILESTONES.md`](docs/plans/MILESTONES.md) for the work queue, and
-[`RELEASES.md`](RELEASES.md) for what changes between versions — in particular for defaults that
-move, which change an installation that has taken no action.
+[`docs/plans/MILESTONES.md`](docs/plans/MILESTONES.md) for the work queue.
 
 ## Releasing
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "browser-broker",
-    "version": "0.2.0",
+    "version": "0.4.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",
@@ -53,7 +53,6 @@
         "dist/",
         ".env.example",
         "README.md",
-        "RELEASES.md",
         "LICENSE"
     ]
 }

package/dist/src/adapter/conformance/cases.js

@@ -320,7 +320,144 @@ export const CONFORMANCE_CASES = [
         operation: 'capture',
         seed: withALiveLease,
         input: {},
-        expect: { outcome: 'accepted' },
+        // §3.11's promised response, asserted as a response rather than as a row
+        // in a database. All three of `sourceWidth`, `sourceHeight` and `tier`
+        // were promised by §3.11 — *"the dimensions written, the dimensions
+        // before shrinking, the file size, the tier"* — computed by the pipeline,
+        // written to the `captures` table, and then **dropped by the service layer
+        // that builds the caller's reply**, for the whole life of the feature.
+        //
+        // Nothing caught it because nothing anywhere compared a response against
+        // the specification that promised it: `check:operations` proves the
+        // binaries reach the service, `check:argument-refusals` polices refusals,
+        // and neither walks from a documented response field to the code meant to
+        // populate it. Naming the fields here is the narrow, non-brittle version
+        // of that check — it binds the spec to the code at the one point both
+        // agree on, without a parser trying to read §3.x's English.
+        expect: {
+            outcome: 'accepted',
+            //
+            // ── Why these ten are not the list, and what bounds it ──────────────
+            //
+            // §3.11 promises more than this case names: an estimated token cost and
+            // how many captures this lease has taken are both in its sentence. They
+            // are deliberately absent here because they are **not in the reply the
+            // caller receives**: `estimatedTokens`, `capturesThisLease` and
+            // `escalation` are fields of the *pipeline's* `CaptureResult`, and
+            // `pages.ts` reshapes that into the `written` object without them. An
+            // assertion naming them would fail against correct code, which is the
+            // one failure a conformance case must never manufacture.
+            //
+            // That gap is real and it is item 557fdcd6's remaining half — a
+            // response still owes §3.11 two fields it does not carry. It is not
+            // closed here, because closing it means changing the response rather
+            // than the test, and this row is about the checks. Named so the next
+            // reader finds a known gap rather than an oversight.
+            //
+            // Spelled `capture.*` because the reply is an envelope: `capture` renews
+            // the lease it was called on, so the value carries `claimId`, `tabId`,
+            // `expiresAt` and `pageDriven` with the picture nested under `capture`.
+            // Naming the path asserts that nesting too.
+            valueFields: [
+                'capture.captureId',
+                'capture.path',
+                'capture.width',
+                'capture.height',
+                'capture.bytes',
+                // The three §3.11 promised and the shipped response omitted for the
+                // whole life of the feature. They are the reason this list exists.
+                'capture.sourceWidth',
+                'capture.sourceHeight',
+                'capture.tier',
+            ],
+        },
+    },
+    {
+        name: 'capture: an escalated tier changes the picture that comes back',
+        operation: 'capture',
+        // ── The assertion `check:argument-reachability` cannot make ───────────
+        //
+        // `tier` was read at the bridge, validated, packed into a request object,
+        // and then dropped at the single `takeCapture` call site, which spread
+        // only `fullPage` and `selector`. Every capture was taken at the default
+        // rung whatever was asked for, and `tier: "max"` charged the caller a
+        // written 8-200 character justification for it. The static check passed
+        // throughout, exactly as its own table says it must: *"a branch that reads
+        // an argument and drops it on the floor passes this."*
+        //
+        // So this case asserts the thing that actually failed: that passing the
+        // argument **changes what comes back**. The runner drives the operation a
+        // second time with `tier` and `reason` removed and requires the two
+        // readings to differ, so a `tier` hard-wired to `"max"` fails here rather
+        // than passing as a constant.
+        //
+        // `max` rather than `detail` because it is the rung that costs a reason,
+        // which puts both arguments on the same case: `reason` is recorded only on
+        // this tier (`pipeline.ts` — *"a reason attached to a capture nobody had to
+        // justify would put noise into the one column the resolution study
+        // reads"*), so the two travel together or not at all.
+        //
+        // ── What this case asserts about `reason`, stated honestly ───────────
+        //
+        // **It asserts that passing `reason` does not prevent the escalation, and
+        // nothing more.** `reason` is genuinely **not observable** from any route:
+        // it is written to the `captures` row and read back by no operation the
+        // conformance suite can reach (`capture-store.ts` exposes `recordCapture`
+        // and `capturesTakenBy`, and neither returns it). So there is no response
+        // field and no driver call in which a dropped `reason` would show.
+        //
+        // It is named in `arguments` regardless, because the baseline must remove
+        // it: `max` without a reason is **refused**, so a baseline that dropped
+        // only `tier` would be measuring a refusal rather than the default rung.
+        // Removing both is what makes the comparison a comparison.
+        //
+        // The one assertion that would close `reason` is a read path to the
+        // capture's own record, which does not exist and is not invented here.
+        seed: withALiveLease,
+        input: {
+            tier: 'max',
+            reason: 'conformance: proving an escalated tier reaches the pipeline that acts on it',
+        },
+        expect: {
+            outcome: 'accepted',
+            effects: [
+                {
+                    arguments: ['tier', 'reason'],
+                    expect: [
+                        {
+                            field: 'capture.tier',
+                            value: 'max',
+                            // The rung a caller lands on with no tier (`DEFAULT_TIER`).
+                            withoutArgument: 'default',
+                        },
+                        {
+                            // The **physical** consequence, not merely the label. `tier`
+                            // could be echoed back by a service that did nothing with it;
+                            // the width cannot. The fake produces 1280x720, so the default
+                            // rung's 1024 long edge shrinks it to 1024x576 while `max`'s
+                            // 2576 leaves it alone — never upscaled (`image.ts`: *"a picture
+                            // smaller than the rung is written as it is"*).
+                            //
+                            // This is the field that would have failed on the shipped
+                            // defect: every capture came back 1024 wide however it was
+                            // asked for.
+                            field: 'capture.width',
+                            value: 1280,
+                            withoutArgument: 1024,
+                        },
+                        {
+                            // The height, for the same reason as the width and as a
+                            // separate reading: the shrink is taken on the **long edge**,
+                            // so a change to `TIER_LONGEST_EDGE` that moved only one
+                            // dimension would leave the other's assertion standing.
+                            field: 'capture.height',
+                            value: 720,
+                            withoutArgument: 576,
+                        },
+                    ],
+                },
+            ],
+        },
     },
     {
         name: 'capture: a selector and a full page together are refused',

package/dist/src/adapter/conformance/run.js

@@ -1,5 +1,47 @@
+import { isDeepStrictEqual } from 'node:util';
 import { ADAPTER_IDS } from "../contract.js";
 import { isWriteOperation, OPERATION_NAMES } from "../operations.js";
+/**
+ * Structural comparison for effect assertions.
+ *
+ * `isDeepStrictEqual` rather than `===`, because an effect may name a
+ * structured field, and rather than `assert.deepStrictEqual`, because this
+ * runner reports findings instead of throwing (see the header).
+ */
+const deepEqual = (a, b) => isDeepStrictEqual(a, b);
+/**
+ * Read a field out of an accepted value, following a dotted path.
+ *
+ * ── Why a path and not a plain key ──────────────────────────────────────
+ *
+ * An accepted value is not flat. `capture` returns the lease's own fields —
+ * `claimId`, `tabId`, `expiresAt`, `pageDriven` — with **the capture itself
+ * nested under `capture`**, because the operation renews the lease it was
+ * called on and the reply says both things. `SCHEMA.md` §3.11's promises are
+ * about the capture object, so a case naming `width` flatly would read
+ * `undefined` from the envelope and report a missing field on a response that
+ * carries it — a finding that is wrong in the most expensive direction, since
+ * it accuses correct code.
+ *
+ * The path is resolved rather than the case being handed the sub-object,
+ * because the envelope is part of what the route returns: a case naming
+ * `capture.tier` asserts the nesting too, and an adapter that quietly
+ * flattened or re-keyed the reply would fail here rather than passing.
+ *
+ * Returns `undefined` for any path that does not resolve, which is the same
+ * answer as a field explicitly set to `undefined` — deliberately, because
+ * both mean "the caller cannot read this" and the assertions are about what
+ * a caller can read.
+ */
+function fieldAt(value, path) {
+    let current = value;
+    for (const step of path.split('.')) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[step];
+    }
+    return current;
+}
 /** Roughly four words, the same bar the hygiene gate holds a waiver to. */
 const WAIVER_MINIMUM_WORDS = 4;
 function wordCount(text) {
@@ -151,6 +193,99 @@ export async function runConformance(options) {
                         });
                     }
                 }
+                // ── Response conformance and argument effect ──────────────────────
+                //
+                // Both are assertions about the **accepted value**, which is why they
+                // sit together and why they are checked here rather than in a unit
+                // test: the value has crossed the route boundary by this point, so a
+                // field the service produced and the adapter dropped fails here and
+                // passes everywhere else.
+                if (outcome.outcome === 'accepted' && testCase.expect.outcome === 'accepted') {
+                    for (const field of testCase.expect.valueFields ?? []) {
+                        if (fieldAt(outcome.value, field) === undefined) {
+                            findings.push({
+                                kind: 'accepted-value-missing-a-field',
+                                adapter: adapterId,
+                                operation: testCase.operation,
+                                caseName: testCase.name,
+                                detail: `the accepted value has no "${field}" (it carries ${Object.keys(outcome.value).join(', ') || 'nothing'})`,
+                            });
+                        }
+                    }
+                    for (const effect of testCase.expect.effects ?? []) {
+                        // The same operation, driven again with the effect's arguments
+                        // removed. A fresh subject, because the first run consumed a lease
+                        // and moved the capture count — reusing it would measure the
+                        // second call's accounting rather than the argument.
+                        const baselineInput = Object.fromEntries(Object.entries(seeded.input).filter(([key]) => !effect.arguments.includes(key)));
+                        const baselineSubject = await options.makeService();
+                        let baseline;
+                        try {
+                            const baselineSubstitutions = (await testCase.seed?.apply(baselineSubject.service)) ?? {};
+                            const baselineCase = {
+                                ...testCase,
+                                name: `${testCase.name} (without ${effect.arguments.join(', ')})`,
+                                input: { ...baselineInput, ...baselineSubstitutions },
+                            };
+                            baseline = (await driver.run(baselineSubject.service, baselineCase, {
+                                driverCalls: baselineSubject.driverCalls,
+                                liveClaimCount: baselineSubject.liveClaimCount,
+                            })).outcome;
+                        }
+                        finally {
+                            await baselineSubject.dispose?.();
+                        }
+                        if (baseline.outcome !== 'accepted') {
+                            // Never silently skipped. An effect whose baseline refused would
+                            // otherwise report the same green as one that held.
+                            findings.push({
+                                kind: 'argument-effect-baseline-failed',
+                                adapter: adapterId,
+                                operation: testCase.operation,
+                                caseName: testCase.name,
+                                detail: `dropping ${effect.arguments.join(', ')} was refused (${baseline.code} / ${baseline.rule}), so the effect of those arguments could not be measured`,
+                            });
+                            continue;
+                        }
+                        for (const expectation of effect.expect) {
+                            const actual = fieldAt(outcome.value, expectation.field);
+                            const without = fieldAt(baseline.value, expectation.field);
+                            if (!deepEqual(actual, expectation.value)) {
+                                findings.push({
+                                    kind: 'argument-had-no-effect',
+                                    adapter: adapterId,
+                                    operation: testCase.operation,
+                                    caseName: testCase.name,
+                                    detail: `with ${effect.arguments.join(', ')}, "${expectation.field}" should be ${JSON.stringify(expectation.value)} but was ${JSON.stringify(actual)}`,
+                                });
+                                continue;
+                            }
+                            if (!deepEqual(without, expectation.withoutArgument)) {
+                                findings.push({
+                                    kind: 'argument-had-no-effect',
+                                    adapter: adapterId,
+                                    operation: testCase.operation,
+                                    caseName: testCase.name,
+                                    detail: `without ${effect.arguments.join(', ')}, "${expectation.field}" should be ${JSON.stringify(expectation.withoutArgument)} but was ${JSON.stringify(without)}`,
+                                });
+                                continue;
+                            }
+                            // The guard against a constant. Both readings can be individually
+                            // right and the argument still inert — if the two agree, passing
+                            // the argument changed nothing, whatever the field happens to
+                            // hold. This is the assertion the whole shape exists for.
+                            if (deepEqual(actual, without)) {
+                                findings.push({
+                                    kind: 'argument-had-no-effect',
+                                    adapter: adapterId,
+                                    operation: testCase.operation,
+                                    caseName: testCase.name,
+                                    detail: `"${expectation.field}" is ${JSON.stringify(actual)} whether or not ${effect.arguments.join(', ')} is passed, so the argument is inert`,
+                                });
+                            }
+                        }
+                    }
+                }
                 if (outcome.outcome === 'refused') {
                     // Both readings, because they catch different bugs (§8.2): a guard
                     // that opens a tab and closes it on the way to refusing leaves the

package/dist/src/browser/fake.js

@@ -92,6 +92,35 @@ const DEFAULT_COOKIES = [
  * members and there is nothing here that invents a third.
  */
 export class FakeBrowserDriver {
+    /**
+     * A way to end each handed-out session's connection, without ending the
+     * browser.
+     *
+     * ── Why the fake needs to be able to do this at all ─────────────────────
+     *
+     * A connection and the browser it points at have **independent lifetimes**,
+     * and the failure this models is the asymmetry: the browser is running and
+     * answers every liveness question truthfully, while the connection one
+     * process holds has ended. Nothing else in this fake can produce that state
+     * — seeding a failure makes an operation reject, which is a different thing
+     * and one the existing eviction path already handles.
+     *
+     * A test drives it with {@link FakeBrowserDriver.disconnect}; the fake's
+     * own tabs and recorded calls are deliberately left untouched, because the
+     * browser is unaffected.
+     */
+    #disconnectors = [];
+    /**
+     * End the connection on every session handed out for one browser, leaving
+     * the browser itself — its tabs, its call log — exactly as it was.
+     */
+    disconnect(browser) {
+        for (const entry of this.#disconnectors) {
+            if (entry.browser === browser) {
+                entry.end();
+            }
+        }
+    }
     #calls = [];
     #options;
     #openTabs = new Map();
@@ -301,6 +330,14 @@ export class FakeBrowserDriver {
     }
     #session(browser, mode) {
         const description = this.#describe(browser, mode);
+        // Every session this fake hands out starts connected, and only
+        // {@link FakeBrowserDriver.disconnect} changes that. It is per-session
+        // rather than per-browser deliberately: the state under test is *this
+        // connection ended while the browser carried on*, so a later acquisition
+        // for the same browser must come back connected, exactly as a real
+        // re-attach would.
+        let connected = true;
+        this.#disconnectors.push({ browser, end: () => (connected = false) });
         const openTab = (name) => {
             const driverTabId = `fake-tab-${String(this.#nextTabNumber++)}`;
             const failure = this.#enter({ name, browser, tab: { browser, driverTabId } });
@@ -314,6 +351,10 @@ export class FakeBrowserDriver {
         };
         return {
             describe: () => description,
+            // Reads the flag above and asks nothing, which is the contract
+            // {@link BrowserSession.isConnected} states: it is consulted before
+            // every page verb, so it must not perform input/output or throw.
+            isConnected: () => connected,
             openTab: () => openTab('openTab'),
             /**
              * Every page open in this browser **except the keeper tab**.
@@ -420,7 +461,18 @@ export class FakeBrowserDriver {
                 });
                 if (failure)
                     return Promise.reject(failure);
-                return Promise.resolve({ url, title: `fake page at ${url}`, status: 200 });
+                // **Where the page ARRIVES, which is not always where it was sent.**
+                // Defaults to the requested address, so every existing caller sees
+                // what it always saw; a test that configures `arriveAt` gets a fake
+                // that redirects, which is the only way a fake can exercise the
+                // difference between reporting the request and reporting the result.
+                const options = this.#options.navigate;
+                const arrived = options?.arriveAt?.(url) ?? url;
+                return Promise.resolve({
+                    url: arrived,
+                    title: options?.title?.(arrived) ?? `fake page at ${arrived}`,
+                    status: options?.status === undefined ? 200 : options.status,
+                });
             },
             seedStorage: (tab, entries) => {
                 // **The whole entries list, values included**, and that is deliberate

package/dist/src/browser/real.js

@@ -1254,6 +1254,18 @@ class RealBrowserSession {
             }
         }
     }
+    /**
+     * Whether this process's connection is still usable.
+     *
+     * Delegates to the flag the driving package already maintains — its
+     * `isConnected()` is declared `(): boolean` and its implementation is a
+     * bare field read (`return this._isConnected`), so this performs no
+     * input/output and cannot throw. That is what {@link BrowserSession.isConnected}
+     * requires of it, because it is consulted before every page verb.
+     */
+    isConnected() {
+        return this.#connection.isConnected();
+    }
     /**
      * End this process's connection. **The browser is unaffected.**
      *
@@ -1303,34 +1315,6 @@ async function connect(options) {
     await session.ensureKeeperTab();
     return session;
 }
-/**
- * Where a configured engine's binary lives, if this process was told.
- *
- * ── What is built here, and what is deliberately not ────────────────
- *
- * All three engines are Chromium over the same remote-debugging protocol, so
- * choosing between them is choosing a binary — which is what makes the hook
- * cheap, and it is the hook `DECISIONS.md` §13i asks for. **The expensive
- * half is explicitly out of scope there**: per-engine executable discovery,
- * per-engine discovery-record locations, per-engine health checks.
- *
- * **So resolution is a lookup of what a caller supplied, never a search.**
- * The engine selects among paths this process was given; it does not go
- * looking for an installation, and it never carries a path of its own.
- * Writing a per-engine install location into this file would name one machine
- * — §1.0's rule forbids that outright, and `check-external-refs` fails on the
- * shape.
- *
- * **What happens when nothing supplied a path for the configured engine** is
- * the case worth being exact about: the launch falls back to the automation
- * library's own Chromium, which is what an unconfigured build launches. That
- * is a real limit and it is named in §13i rather than hidden here — the
- * variables are validated and carried, and the row that resolves an engine to
- * an installed binary is separable work.
- */
-export function executablePathForEngine(engine, supplied) {
-    return supplied?.[engine];
-}
 /**
  * The real driver.
  *
@@ -1350,9 +1334,7 @@ export class RealBrowserDriver {
         if (this.#options.executablePath !== undefined) {
             return this.#options.executablePath;
         }
-        const engine = this.#options.engine;
-        const resolved = engine === undefined ? undefined : executablePathForEngine(engine, this.#options.enginePaths);
-        return resolved ?? chromium.executablePath();
+        return chromium.executablePath();
     }
     /**
      * Attach to a browser that is already running, **having checked the record

package/dist/src/capture/tiers.js

@@ -164,3 +164,56 @@ const TOKENS_PER_PIXEL_DIVISOR = 750;
 export function estimateTokens(width, height) {
     return Math.ceil((width * height) / TOKENS_PER_PIXEL_DIVISOR);
 }
+/**
+ * Describe the shrink, or return nothing when there was not one.
+ *
+ * **Absent rather than `scale: 1` when nothing was reduced**, and the
+ * difference is the one this whole helper is for: a field that is always
+ * present is a field a caller stops reading. Its presence is the signal.
+ */
+export function describeReduction(source, written, tier) {
+    if (written.width >= source.width && written.height >= source.height) {
+        return undefined;
+    }
+    // Taken on the long edge, which is the edge the cap is applied to — so this
+    // is the factor that was actually used rather than one recovered from
+    // whichever dimension happens to round more kindly.
+    const scale = Math.max(source.width, source.height) === 0
+        ? 1
+        : Math.max(written.width, written.height) / Math.max(source.width, source.height);
+    const percent = Math.round(scale * 100);
+    // Named only when there is one, so the sentence never tells a caller already
+    // on the top rung to escalate to it.
+    const higher = HIGHER_TIERS[tier];
+    const remedy = higher === undefined
+        ? `This is the highest rung, so a larger image of the whole page is not available; capture a selector, or read the page as text instead.`
+        : `For more detail pass tier="${higher}"${higher === TIER_REQUIRING_REASON ? ' together with reason' : ''}.`;
+    // The width is called out separately because it is the number that decides
+    // legibility on a tall page, and it is the one a caller reading "scale" on
+    // its own would not think to compare against the viewport.
+    return {
+        sourceWidth: source.width,
+        sourceHeight: source.height,
+        scale: Math.round(scale * 1000) / 1000,
+        note: `This image was REDUCED to about ${String(percent)}% of the page: ` +
+            `${String(source.width)}x${String(source.height)} was written as ` +
+            `${String(written.width)}x${String(written.height)}. ` +
+            `A capture is shrunk so its LONGEST edge fits ${String(TIER_LONGEST_EDGE[tier])}px, so on a page ` +
+            `taller than it is wide the height sets the factor and the width shrinks with it — ` +
+            `${String(written.width)}px of width here. Text may not be legible. ` +
+            remedy,
+    };
+}
+/**
+ * The next rung up from each, and `undefined` at the top.
+ *
+ * A table rather than an ordering computed from {@link TIER_LONGEST_EDGE},
+ * because "which rung does a caller ask for next" is a fact about the
+ * surface's vocabulary — `default` is not requestable by name — and not about
+ * which number is larger.
+ */
+const HIGHER_TIERS = {
+    default: 'detail',
+    detail: 'max',
+    max: undefined,
+};

package/dist/src/cli/commands.js

@@ -172,6 +172,11 @@ export const STANDALONE_COMMANDS = [
         words: ['snapshot'],
         summary: 'Write the operations document to a path and exit.',
         owedBy: 'the row that builds the operations document',
+        options: [
+            { flag: '--out <path>', summary: 'The file to write the document to. Required.' },
+            { flag: '--events <n>', summary: 'How many ledger entries to include.' },
+            { flag: '--feedback <n>', summary: 'How many feedback rows to include.' },
+        ],
     },
     {
         words: ['doctor'],