staysfixed 0.7.1 → 0.8.0

package/src/v2/adapters/source.js

@@ -31,6 +31,7 @@ import fsp from 'node:fs/promises';
 import path from 'node:path';
 import nodeModule from 'node:module';
 import { defineAdapter, joinPath, notCovered, observation } from './contract.js';
+import { readPythonRoutes } from './python.js';
 
 // ---------------------------------------------------------------------------
 // The lexer
@@ -318,6 +319,19 @@ const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', '
  */
 const ROUTER_NAMES = new Set(['app', 'router', 'server', 'fastify', 'api', 'routes']);
 
+/**
+ * The two names a hand-written request handler almost always gives its arguments. A server
+ * written straight on `node:http` registers nothing — there is no `app.get` to find — so the
+ * only thing that says "this function is where requests arrive" is the shape of its
+ * parameters. Both halves have to match before either name is believed, because a lone
+ * `req` could be anything and a function taking `(req, res)` could not.
+ */
+const REQUEST_PARAM_NAMES = new Set(['req', 'request', 'incoming']);
+const RESPONSE_PARAM_NAMES = new Set(['res', 'response', 'reply']);
+
+/** What a route reads as when the code never checks which verb it is. */
+const METHOD_UNKNOWN = 'ANY';
+
 /** @param {string} file */
 export function looksLikeATest(file) {
   const normalised = file.split(path.sep).join('/');
@@ -524,6 +538,13 @@ export function readFile(relFile, text) {
     }
   }
 
+  // A server written straight on node:http registers nothing. There is no `app.get` for the
+  // sweep above to find, so every route in it was invisible — and a repository whose entire
+  // HTTP surface is invisible was then reported as covered in full, which is the worst
+  // sentence this tool can say. In a hand-written server the routes live in the comparisons
+  // instead, and that is what this reads.
+  doors.push(...handWrittenRoutes(tokens, relFile, inTest, fromConstant));
+
   return { doors, constants: exportedConstants, recoveries, typesStripped };
 }
 
@@ -558,6 +579,342 @@ function isRouterFactory(tokens, at) {
   return tokens[at + 1]?.v === '.' && /^(Router|createServer)$/.test(tokens[at + 2]?.v ?? '');
 }
 
+// ---------------------------------------------------------------------------
+// Servers written by hand, with no framework under them
+// ---------------------------------------------------------------------------
+
+/**
+ * A path a hand-written server would really answer on.
+ *
+ * The comparison this came from is already strong evidence — the left-hand side had to be
+ * proven to hold the request's own address before we got here — so this only has to throw
+ * out the shapes no route ever has. It deliberately does NOT reject a path because it ends
+ * in something that looks like a file: `/favicon.ico` and `/api/data.json` are real routes,
+ * and a reader that quietly dropped them would be hiding doors to look tidy.
+ *
+ * @param {Token|undefined} token
+ * @returns {string|null}
+ */
+function routePathIn(token) {
+  if (!token) return null;
+  if (token.t !== 'string' && token.t !== 'template') return null;
+  if (token.built) return null;
+  const value = token.v;
+  if (!value.startsWith('/')) return null;
+  if (value.length > 120) return null;
+  if (/[\\<>{}()\s]/.test(value)) return null;
+  return value;
+}
+
+/**
+ * The first parameter of the function written at `at`, when one is written there.
+ *
+ * Only a function literal counts. `createServer(handler)` names a function defined
+ * somewhere else, and guessing what that one calls its arguments would be inventing a fact —
+ * the `(req, res)` rule below is what covers that case, and it needs both names to agree
+ * before it believes either.
+ *
+ * @param {Token[]} tokens
+ * @param {number} at
+ * @returns {string|null}
+ */
+function firstParameterAt(tokens, at) {
+  let i = at;
+  while (tokens[i]?.t === 'name' && (tokens[i].v === 'async' || tokens[i].v === 'function')) i++;
+  if (tokens[i]?.v === '*') i++;
+  // A named function expression: skip its name, but only when a parameter list follows.
+  if (tokens[i]?.t === 'name' && tokens[i + 1]?.v === '(' && tokens[at]?.v !== tokens[i]?.v) i++;
+  const first = tokens[i];
+  if (!first) return null;
+  if (first.t === 'name' && tokens[i + 1]?.v === '=>') return first.v;
+  if (first.v !== '(') return null;
+  const name = tokens[i + 1];
+  if (name?.t !== 'name') return null;
+  const close = matchBracket(tokens, i);
+  const arrow = tokens[close + 1]?.v === '=>';
+  const wasFunction = tokens[at]?.v === 'function' || tokens[at]?.v === 'async';
+  if (!arrow && !wasFunction) return null;
+  return name.v;
+}
+
+/**
+ * Every name in this file that holds an arriving request.
+ *
+ * Two ways in, and both need proof. A function handed straight to `createServer` is a
+ * request handler by definition, whatever it calls its arguments. Everything else has to be
+ * a function taking `(req, res)` — BOTH halves conventional — because a lone `req` could be
+ * anything at all, and a pair could not be.
+ *
+ * @param {Token[]} tokens
+ * @returns {Set<string>}
+ */
+function requestNamesIn(tokens) {
+  /** @type {Set<string>} */
+  const names = new Set();
+
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.t !== 'name') continue;
+    let callbackAt = -1;
+    if (t.v === 'createServer' && tokens[i + 1]?.v === '(') callbackAt = i + 2;
+    else if (
+      t.v === 'on' && tokens[i - 1]?.v === '.' && tokens[i + 1]?.v === '('
+      && tokens[i + 2]?.t === 'string' && tokens[i + 2].v === 'request' && tokens[i + 3]?.v === ','
+    ) callbackAt = i + 4;
+    if (callbackAt === -1) continue;
+    const found = firstParameterAt(tokens, callbackAt);
+    if (found) names.add(found);
+  }
+
+  for (let i = 0; i + 4 < tokens.length; i++) {
+    if (tokens[i].v !== '(') continue;
+    const [a, comma, b, close] = [tokens[i + 1], tokens[i + 2], tokens[i + 3], tokens[i + 4]];
+    if (a?.t !== 'name' || comma?.v !== ',' || b?.t !== 'name' || close?.v !== ')') continue;
+    if (REQUEST_PARAM_NAMES.has(a.v) && RESPONSE_PARAM_NAMES.has(b.v)) names.add(a.v);
+  }
+
+  return names;
+}
+
+/**
+ * The bracket closing `new URL(<the request address>, …)` when that is what sits at `at`.
+ * @param {Token[]} tokens
+ * @param {number} at
+ * @param {(i: number) => number} pathEnd
+ * @returns {number}
+ */
+function urlBuiltFromRequest(tokens, at, pathEnd) {
+  if (tokens[at]?.v !== 'new' || tokens[at + 1]?.v !== 'URL' || tokens[at + 2]?.v !== '(') return -1;
+  if (pathEnd(at + 3) < 0) return -1;
+  return matchBracket(tokens, at + 2);
+}
+
+/**
+ * Every name in this file that holds the address being asked for, and every name that holds
+ * a parsed URL it was built from.
+ *
+ * Run to a standstill rather than once, because `const p = req.url` and
+ * `const q = p.split('?')[0]` is two hops and reading only the first hop loses the routes
+ * that hang off the second.
+ *
+ * @param {Token[]} tokens
+ * @param {Set<string>} requestNames
+ * @returns {{pathNames: Set<string>, urlNames: Set<string>}}
+ */
+function pathNamesIn(tokens, requestNames) {
+  /** @type {Set<string>} */
+  const pathNames = new Set();
+  /** @type {Set<string>} */
+  const urlNames = new Set();
+  /** @param {number} i */
+  const pathEnd = (i) => pathExpressionEnd(tokens, i, requestNames, pathNames, urlNames);
+
+  for (let round = 0; round < 4; round++) {
+    const before = pathNames.size + urlNames.size;
+    for (let i = 0; i + 3 < tokens.length; i++) {
+      const t = tokens[i];
+      if (t.t !== 'name' || (t.v !== 'const' && t.v !== 'let' && t.v !== 'var')) continue;
+
+      // const { pathname } = new URL(req.url, …)
+      if (tokens[i + 1]?.v === '{') {
+        const close = matchBracket(tokens, i + 1);
+        if (tokens[close + 1]?.v !== '=') continue;
+        if (urlBuiltFromRequest(tokens, close + 2, pathEnd) < 0) continue;
+        for (let j = i + 2; j < close; j++) {
+          if (tokens[j]?.t !== 'name' || tokens[j].v !== 'pathname') continue;
+          const renamed = tokens[j + 1]?.v === ':' && tokens[j + 2]?.t === 'name' ? tokens[j + 2].v : null;
+          pathNames.add(renamed ?? 'pathname');
+        }
+        continue;
+      }
+
+      const target = tokens[i + 1];
+      if (target.t !== 'name' || tokens[i + 2]?.v !== '=') continue;
+      if (pathEnd(i + 3) > 0) { pathNames.add(target.v); continue; }
+      if (urlBuiltFromRequest(tokens, i + 3, pathEnd) > 0) urlNames.add(target.v);
+    }
+    if (pathNames.size + urlNames.size === before) break;
+  }
+
+  return { pathNames, urlNames };
+}
+
+/**
+ * Where the expression starting at `at` ends, when that expression is the address being
+ * asked for. Anything else answers -1.
+ *
+ * `.split('?')[0]` is allowed on the end because cutting the query string off is the one
+ * thing every hand-written server does to the address before comparing it. `.replace(…)` and
+ * friends are not, and that is deliberate: they change the value into something we can no
+ * longer claim is the route, and inventing a route is worse than missing one.
+ *
+ * @param {Token[]} tokens
+ * @param {number} at
+ * @param {Set<string>} requestNames
+ * @param {Set<string>} pathNames
+ * @param {Set<string>} urlNames
+ * @returns {number}
+ */
+function pathExpressionEnd(tokens, at, requestNames, pathNames, urlNames) {
+  const t = tokens[at];
+  if (!t || t.t !== 'name') return -1;
+  /** @param {number} i */
+  const again = (i) => pathExpressionEnd(tokens, i, requestNames, pathNames, urlNames);
+
+  let end = -1;
+  const dotted = tokens[at + 1]?.v === '.' ? tokens[at + 2]?.v : null;
+  if (pathNames.has(t.v) && dotted !== 'pathname') end = at + 1;
+  else if (requestNames.has(t.v) && dotted === 'url') end = at + 3;
+  else if (urlNames.has(t.v) && dotted === 'pathname') end = at + 3;
+  else if (t.v === 'new') {
+    const close = urlBuiltFromRequest(tokens, at, again);
+    if (close > 0 && tokens[close + 1]?.v === '.' && tokens[close + 2]?.v === 'pathname') end = close + 3;
+  } else if (dotted === 'parse' && tokens[at + 3]?.v === '(') {
+    // The shape node's own `url` module has had since forever: url.parse(req.url).pathname.
+    const close = matchBracket(tokens, at + 3);
+    if (again(at + 4) > 0 && tokens[close + 1]?.v === '.' && tokens[close + 2]?.v === 'pathname') end = close + 3;
+  }
+  if (end < 0) return -1;
+
+  for (;;) {
+    if (tokens[end]?.v !== '.' || tokens[end + 1]?.v !== 'split' || tokens[end + 2]?.v !== '(') break;
+    const close = matchBracket(tokens, end + 2);
+    const separator = tokens[end + 3];
+    const cutsTheQuery = separator?.t === 'string' && (separator.v === '?' || separator.v === '#');
+    const takesTheFirst = tokens[close + 1]?.v === '[' && tokens[close + 2]?.v === '0' && tokens[close + 3]?.v === ']';
+    if (!cutsTheQuery || !takesTheFirst) break;
+    end = close + 4;
+  }
+  return end;
+}
+
+/**
+ * The verb this route is guarded by, when the same condition says.
+ *
+ * A hand-written server that never looks at `req.method` answers a route on every verb, and
+ * writing GET on it would be putting a fact in the report that is not in the code. Only what
+ * the condition itself says is believed; anything further out reads as unknown, which the
+ * rest of the tool already has a word for.
+ *
+ * @param {Token[]} tokens
+ * @param {number} at
+ * @param {Set<string>} requestNames
+ * @returns {string}
+ */
+function methodGuarding(tokens, at, requestNames) {
+  let depth = 0;
+  let open = -1;
+  for (let j = at - 1, steps = 0; j >= 0 && steps < 400; j--, steps++) {
+    const t = tokens[j];
+    if (t.t !== 'punct') continue;
+    if (t.v === ')' || t.v === ']' || t.v === '}') { depth++; continue; }
+    if (t.v === '[' || t.v === '{') { if (depth === 0) return METHOD_UNKNOWN; depth--; continue; }
+    if (t.v === '(') { if (depth === 0) { open = j; break; } depth--; }
+  }
+  if (open < 0) return METHOD_UNKNOWN;
+  const keyword = tokens[open - 1];
+  if (keyword?.t !== 'name' || (keyword.v !== 'if' && keyword.v !== 'while')) return METHOD_UNKNOWN;
+
+  const close = matchBracket(tokens, open);
+  for (let j = open + 1; j + 3 < close; j++) {
+    if (tokens[j].t !== 'name' || !requestNames.has(tokens[j].v)) continue;
+    if (tokens[j + 1]?.v !== '.' || tokens[j + 2]?.v !== 'method') continue;
+    const operator = tokens[j + 3]?.v;
+    if (operator !== '===' && operator !== '==') continue;
+    const verb = tokens[j + 4];
+    if (verb?.t !== 'string' || !/^[a-z]+$/i.test(verb.v)) continue;
+    return verb.v.toUpperCase();
+  }
+  return METHOD_UNKNOWN;
+}
+
+/**
+ * Read the routes out of a server nobody used a framework to write.
+ *
+ * The whole thing is gated on there being a proven request handler in the file, so a project
+ * with no server in it walks straight back out. That gate is also what keeps the trap out:
+ * a string like '/etc/app/config.json' compared against an ordinary variable never reaches
+ * here, because the left-hand side was never shown to hold the request's own address.
+ *
+ * @param {Token[]} tokens
+ * @param {string} relFile
+ * @param {boolean} inTest
+ * @param {(raw: string) => {name: string|Pending, via: string}} fromConstant
+ * @returns {RawDoor[]}
+ */
+function handWrittenRoutes(tokens, relFile, inTest, fromConstant) {
+  const requestNames = requestNamesIn(tokens);
+  if (requestNames.size === 0) return [];
+  const { pathNames, urlNames } = pathNamesIn(tokens, requestNames);
+
+  /** @type {RawDoor[]} */
+  const doors = [];
+  const via = 'a hand-written request handler';
+  /** @param {number} i */
+  const pathEnd = (i) => pathExpressionEnd(tokens, i, requestNames, pathNames, urlNames);
+
+  /** @param {Token} token @param {string} method @param {boolean} prefix */
+  const take = (token, method, prefix) => {
+    const value = routePathIn(token);
+    if (value === null) return;
+    // A prefix match is not one route, it is a family of them. Written as a changing part it
+    // joins the flow that already exists for `/users/:id` — the tool asks for a real value
+    // and, until it gets one, says out loud that nothing under here was ever looked at.
+    const name = prefix ? `${value.replace(/\/+$/, '')}/:rest` : value;
+    doors.push(door('route', name, method, relFile, token.line, inTest, true, via));
+  };
+
+  for (let i = 0; i < tokens.length; i++) {
+    // switch (pathname) { case '/a': … }
+    if (tokens[i].t === 'name' && tokens[i].v === 'switch' && tokens[i + 1]?.v === '(') {
+      const close = matchBracket(tokens, i + 1);
+      if (pathEnd(i + 2) !== close || tokens[close + 1]?.v !== '{') continue;
+      const endOfBody = matchBracket(tokens, close + 1);
+      for (let j = close + 2; j < endOfBody; j++) {
+        if (tokens[j].t !== 'name' || tokens[j].v !== 'case') continue;
+        const label = tokens[j + 1];
+        if (label?.t === 'name') {
+          const known = fromConstant(label.v);
+          if (typeof known.name === 'string' && known.name.startsWith('/')) {
+            doors.push(door('route', known.name, METHOD_UNKNOWN, relFile, label.line, inTest, true, known.via));
+          }
+          continue;
+        }
+        take(label, METHOD_UNKNOWN, false);
+      }
+      i = endOfBody;
+      continue;
+    }
+
+    // '/a' === req.url, which reads the same and is written often enough to matter.
+    const mirrored = routePathIn(tokens[i]);
+    if (mirrored !== null && (tokens[i + 1]?.v === '===' || tokens[i + 1]?.v === '==') && pathEnd(i + 2) > 0) {
+      take(tokens[i], methodGuarding(tokens, i, requestNames), false);
+      continue;
+    }
+
+    const end = pathEnd(i);
+    if (end < 0) continue;
+    const operator = tokens[end]?.v;
+    if (operator === '===' || operator === '==') {
+      const label = tokens[end + 1];
+      if (label?.t === 'name') {
+        const known = fromConstant(label.v);
+        if (typeof known.name === 'string' && known.name.startsWith('/')) {
+          doors.push(door('route', known.name, methodGuarding(tokens, i, requestNames), relFile, label.line, inTest, true, known.via));
+        }
+      } else {
+        take(label, methodGuarding(tokens, i, requestNames), false);
+      }
+    } else if (operator === '.' && tokens[end + 1]?.v === 'startsWith' && tokens[end + 2]?.v === '(') {
+      take(tokens[end + 3], methodGuarding(tokens, i, requestNames), true);
+    }
+    i = end - 1;
+  }
+
+  return doors;
+}
+
 /**
  * Index of the bracket closing the one at `open`. Returns the end of the token list when
  * the file is unbalanced, which happens in a file the lexer had to recover inside.
@@ -929,10 +1286,17 @@ async function collectFiles(root, folders, maxFileBytes) {
 // ---------------------------------------------------------------------------
 
 /**
+ * Every route that is not written as a call in JavaScript.
+ *
  * Next.js puts its routes in folder names, so no amount of reading calls will find them.
  * Both layouts are handled: an app folder, where a `route` file's exported method names are
  * the verbs, and a pages/api folder, where the file itself is the route.
  *
+ * Python's routes are read here too, and this is the reason they are read HERE rather than
+ * somewhere of their own: five places in this tool ask for routes, and four of them would
+ * have had to be found and changed. A Flask app that had routes in one of them and none in
+ * the others is a worse bug than no Python support at all.
+ *
  * A folder that cannot be opened takes every route behind it, so it is named rather than
  * skipped. This is the same bug as the one fixed in the file walk on 2026-08-30 — a hole that
  * looks exactly like a project with no routes in it — and it was still here in this function.
@@ -1014,6 +1378,10 @@ export async function readFileRoutes(root) {
     });
   }
 
+  const python = await readPythonRoutes(root);
+  doors.push(...python.doors);
+  problems.push(...python.problems);
+
   return { doors, problems };
 }
 
@@ -1183,16 +1551,15 @@ export function surfaceOf(project) {
   return 'library';
 }
 
-/** @type {ContractReading|null} */
-let lastReading = null;
-
 /**
  * The static-contract adapter.
  *
  * It applies to every project, always, because every project has source. It is the one
  * adapter that costs nothing to run and can never break anything, so the engine runs it
- * first and hands its result to the others — the HTTP adapter learns its routes from here
- * rather than by crawling a running server.
+ * first. It does NOT hand its reading to the other adapters: the HTTP adapter calls
+ * readContract() itself, which costs a second read and buys not caring what order the
+ * adapters ran in. A shared cache was tried and taken out again, because an adapter that
+ * silently needs another one to have gone first is the bug this tool exists to catch.
  */
 export const sourceAdapter = defineAdapter({
   name: 'source',
@@ -1271,22 +1638,10 @@ export const sourceAdapter = defineAdapter({
     for (const found of reading.doors) {
       reading.report.counts[found.kind] = (reading.report.counts[found.kind] ?? 0) + 1;
     }
-    lastReading = reading;
     return contractObservations(reading, journey.name);
   },
 
   async teardown() {
-    lastReading = null;
+    // Nothing to tear down. Nothing was started and nothing was written.
   },
 });
-
-/**
- * The last thing the source adapter read.
- *
- * The HTTP adapter uses this to find its routes without crawling. Anything that cannot
- * guarantee it runs after the source adapter should call {@link readContract} itself rather
- * than depend on run order.
- */
-export function lastContractReading() {
-  return lastReading;
-}

package/src/v2/adapters/web-driver.js

@@ -67,43 +67,73 @@ import { globToRegExp } from '../../freeze/network.js';
  */
 
 /**
- * Find Playwright, in the two places it could honestly be.
+ * Find the browser library, in every place it could honestly be.
  *
- * Stays Fixed is installed INTO other people's projects, so "is Playwright here" has two
- * different answers: is it beside us, and is it in the project we were pointed at. Both are
- * tried, because a project that already drives its own tests with Playwright should not be
- * asked to install a second copy.
+ * ## Two packages, not one
  *
- * It is loaded with `import()` rather than named at the top of the file on purpose. A tool
- * that cannot start at all because an optional browser library is missing is a tool that
- * cannot tell you what is missing.
+ * `playwright` and `playwright-core` are the same driver. The difference is that the first
+ * downloads its own copy of Chromium when it installs — about 150MB — and the second
+ * downloads nothing and expects to be told where a browser already is. This tool depends on
+ * `playwright-core` and finds the browser itself, because it already knows how: `browsers.js`
+ * locates Chrome for Testing, Chrome, Edge or Chromium on the machine, and deliberately
+ * prefers one that is not the browser the person actually uses.
+ *
+ * Both names are tried, in both places, because a project that already drives its own tests
+ * with the full `playwright` should never be asked to install a second copy of the same thing.
+ *
+ * ## Why it is loaded like this
+ *
+ * With `import()` rather than named at the top of the file: a tool that cannot start at all
+ * because a browser library is missing is a tool that cannot tell you what is missing.
+ *
+ * ## What went wrong here before, so it does not happen twice
+ *
+ * `playwright` was removed from this package's dependencies on the grounds that nothing in
+ * `src/` imported it. Nothing does — this line does, and a search for a static import cannot
+ * see it. The result shipped: 0.7.2 told every agent that asked that web apps and sites could
+ * be checked "here and now", and then answered every website check with "Playwright is not
+ * installed, so no web page can be opened". A tool that is wrong about its own headline
+ * ability is worse than one that lacks it. `test/v2/web-driver.test.js` now holds the
+ * dependency in place by name.
  *
  * @param {object} [opts]
  * @param {string} [opts.projectRoot]  The project being checked. Looked in second.
  * @returns {Promise<PlaywrightState>}
  */
 export async function loadPlaywright(opts = {}) {
-  const install = 'npm install --save-dev playwright';
+  const install = 'npm install playwright-core';
   /** @type {any} */
   let mod = null;
   /** @type {string|undefined} */
   let version;
+  /** @type {string|null} */
+  let loadedName = null;
 
   /** @param {any} loaded */
   const unwrap = (loaded) => (loaded && loaded.chromium ? loaded : (loaded?.default ?? null));
 
-  try {
-    mod = unwrap(await import('playwright'));
-  } catch {
-    // Not beside us. Try the project we were pointed at.
+  // `playwright` first, because a project that has the full package has a browser downloaded
+  // with it, and using that is one less thing to go looking for.
+  for (const name of ['playwright', 'playwright-core']) {
+    if (mod) break;
+    try {
+      mod = unwrap(await import(name));
+      if (mod) loadedName = name;
+    } catch {
+      // Not beside us under this name. Try the next, then the project we were pointed at.
+    }
   }
 
   if (!mod && opts.projectRoot) {
-    try {
-      const require = createRequire(path.join(opts.projectRoot, 'package.json'));
-      mod = unwrap(await import(require.resolve('playwright')));
-    } catch {
-      // Not there either. That is an answer, and it is reported as one.
+    for (const name of ['playwright', 'playwright-core']) {
+      if (mod) break;
+      try {
+        const require = createRequire(path.join(opts.projectRoot, 'package.json'));
+        mod = unwrap(await import(require.resolve(name)));
+        if (mod) loadedName = name;
+      } catch {
+        // Not there either. That is an answer, and it is reported as one.
+      }
     }
   }
 
@@ -111,14 +141,14 @@ export async function loadPlaywright(opts = {}) {
     return {
       ok: false,
       state: 'no package',
-      why: 'Playwright is not installed, so no web page can be opened. Everything read out of the source still works; nothing that needs a browser does.',
+      why: 'The browser driver is not installed, so no web page can be opened. Everything read out of the source still works; nothing that needs a browser does.',
       howToGet: install,
     };
   }
 
   try {
     const require = createRequire(import.meta.url);
-    version = String(require('playwright/package.json').version);
+    version = String(require(`${loadedName ?? 'playwright-core'}/package.json`).version);
   } catch {
     // A version we cannot read is not a reason to refuse to run.
   }
@@ -131,14 +161,40 @@ export async function loadPlaywright(opts = {}) {
     executable = undefined;
   }
 
-  const there = Boolean(executable) && (await exists(/** @type {string} */ (executable)));
+  let there = Boolean(executable) && (await exists(/** @type {string} */ (executable)));
+
+  // The driver's own browser is not the only browser.
+  //
+  // `playwright-core` downloads nothing, so it always names a Chromium that is not there.
+  // That is not a failure — this tool already knows how to find a browser, and has a
+  // considered opinion about which one: `browsers.js` prefers Chrome for Testing over the
+  // browser the person actually uses, precisely so a check can never take over their
+  // windows, their profile or their sign-ins.
+  //
+  // So: ask it. Only when there is no browser on the machine at all is this a real "no".
+  /** @type {string|undefined} */
+  let borrowedFrom;
+  if (!there) {
+    try {
+      const { surveyBrowsers } = await import('../browsers.js');
+      const survey = await surveyBrowsers({ headless: true });
+      if (survey.chosen?.binary && (await exists(survey.chosen.binary))) {
+        executable = survey.chosen.binary;
+        borrowedFrom = survey.chosen.name;
+        there = true;
+      }
+    } catch {
+      // Nothing found, or the survey itself would not run. Reported as "no browser" below.
+    }
+  }
+
   if (!there) {
     return {
       ok: false,
       state: 'no browser',
       chromium: mod.chromium,
       version,
-      why: `Playwright ${version ?? ''} is installed but its browser has not been downloaded, so no page can be opened yet. This is one command and nobody has to be asked.`.trim(),
+      why: `The browser driver ${version ?? ''} is installed, and there is no browser on this machine for it to open. This is one command and nobody has to be asked.`.trim(),
       howToGet: 'npx playwright install chromium',
       executable,
     };
@@ -150,7 +206,9 @@ export async function loadPlaywright(opts = {}) {
     chromium: mod.chromium,
     version,
     executable,
-    why: `Playwright ${version ?? ''} is here and its Chromium is downloaded, so pages can be opened.`.trim(),
+    why: borrowedFrom
+      ? `The browser driver ${version ?? ''} is here and it will open ${borrowedFrom}, which is a separate application from the browser you use, so pages can be opened.`.trim()
+      : `The browser driver ${version ?? ''} is here and its Chromium is downloaded, so pages can be opened.`.trim(),
   };
 }
 
@@ -192,6 +250,7 @@ async function exists(file) {
  *
  * @param {object} opts
  * @param {any} opts.chromium
+ * @param {string} [opts.executable]  Which browser to open. From `loadPlaywright`.
  * @param {string} opts.scratchDir
  * @param {{width: number, height: number, deviceScaleFactor?: number}} [opts.viewport]
  * @param {'light'|'dark'} [opts.colorScheme]
@@ -209,6 +268,15 @@ export async function openWindow(opts) {
   await fsp.mkdir(profileDir, { recursive: true });
 
   const context = await opts.chromium.launchPersistentContext(profileDir, {
+    // Which browser, said out loud rather than left to the driver's default.
+    //
+    // `playwright-core` has no browser of its own, so without this it looks for one that was
+    // never downloaded and the launch fails with a path nobody recognises. `loadPlaywright`
+    // has already decided which browser this machine should open — usually Chrome for
+    // Testing, deliberately not the browser the person uses — and this is where that decision
+    // is honoured. Left out when there is nothing to say, so the full `playwright` keeps
+    // using the Chromium it downloaded for itself.
+    ...(opts.executable ? { executablePath: opts.executable } : {}),
     headless: opts.headed !== true,
     viewport,
     deviceScaleFactor,
@@ -1243,7 +1311,9 @@ export function flattenAria(nodes) {
       // Two things with the same name in the same place have to be told apart somehow, and
       // counting is the only honest way left. The count is kept per place, so it cannot
       // spread: adding a row to one list never renumbers another.
-      const key = `${scope.join(' ')}${node.role}${node.name ?? ''}`;
+      // The separator is written as the escape, never as the byte. A raw NUL makes grep and
+      // file(1) treat this whole module as binary and skip it without saying so.
+      const key = `${scope.join(' ')}\u0000${node.role}\u0000${node.name ?? ''}`;
       const nth = (seen.get(key) ?? 0) + 1;
       seen.set(key, nth);