@runeditrun/rer 0.1.0 → 0.2.0

package/cli/door.mjs

@@ -0,0 +1,263 @@
+// The front door's protocol (version 1). The door itself lives in the global
+// `rer` package, which bundles this file; each checkout's pinned copy reads the
+// same state, so the two meet only here.
+//
+// RER_DOOR_DIR (default ~/.rer/door): a 0700 directory owned by this account,
+// never a link, holding 0600 files:
+//   state.json    door policy, recorded environment and the registered sites
+//                 (and the names removed ones keep reserved)
+//                 (written under the job queue's bakery lock)
+//   token         the door's secret; it proves it holds it before rer prints a key
+//   process.json  the running door: protocol, PID and start, port, addresses,
+//                 version and version directory
+// A checkout keeps its door identity in its own .rer/local/door-site.json
+// ({id}, 0600); a registered site records the same id, so a moved or renamed
+// checkout keeps its name (and with it its origin and sign-in).
+// A checkout in door mode serves on 127.0.0.1:<proxyPort> and records
+// `door: {v, name, port, secret}` on its server-registry entry (also 0600). Its
+// proxy answers only its own Host carrying the per-start secret header, which
+// only the door (and rer's own probes) add.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { chmod, lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { userInfo } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { identity } from '../modules/job-queue/identity.mjs';
+import { processInfo } from '../modules/job-queue/processes.mjs';
+import { transaction } from '../modules/job-queue/storage.mjs';
+import { refuse } from './errors.mjs';
+import { shared } from './shared.mjs';
+
+export const doorProtocol = 1;
+export const defaultDoorPort = 8700;
+export const doorSecretHeader = 'x-rer-door-secret';
+export const doorChallengeHeader = 'x-rer-door-challenge';
+export const doorIdentityPath = '/__rer/door/identity';
+export const doorDefaults = Object.freeze({ serverLimit: 10, idleSeconds: 43200 });
+
+export const doorDirectory = (env = process.env) => resolve(env.RER_DOOR_DIR ?? join(userInfo().homedir, '.rer/door'));
+export const doorOrigin = (name, port) => `http://${name}.localhost:${port}`;
+export const doorHost = (name, port) => `${name}.localhost:${port}`;
+
+// A checkout's name: the DNS-safe slug of its folder name.
+export function siteSlug(path) {
+ return basename(path).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+/, '').slice(0, 50).replace(/-+$/, '') || 'site';
+}
+
+// { name, port } when `origin` is exactly a saved front-door origin.
+export function doorSite(origin) {
+ let url; try { url = new URL(origin); } catch { return undefined; }
+ const match = /^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)\.localhost$/.exec(url.hostname);
+ if (!match || url.protocol !== 'http:' || !url.port || url.origin !== origin) return undefined;
+ return { name: match[1], port: Number(url.port) };
+}
+
+async function ownedDirectory(directory, create) {
+ if (create) await mkdir(directory, { recursive: true, mode: 0o700 });
+ let info;
+ try { info = await lstat(directory); } catch (error) { if (error.code === 'ENOENT' && !create) return false; throw error; }
+ if (info.isSymbolicLink() || !info.isDirectory() || info.uid !== process.getuid()) throw refuse(`The front door directory ${directory} is foreign or linked. Preserve it for inspection and choose an owned RER_DOOR_DIR.`);
+ if (create) await chmod(directory, 0o700);
+ return true;
+}
+
+// A 0600 file in the door directory, or undefined when it does not exist.
+export async function readPrivate(path) {
+ let info;
+ try { info = await lstat(path); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+ if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1 || info.uid !== process.getuid()) throw refuse(`${path} is foreign or linked. Preserve it for inspection.`);
+ if ((info.mode & 0o077) !== 0) await chmod(path, 0o600);
+ return readFile(path, 'utf8');
+}
+
+export async function writePrivate(path, text) {
+ const existing = await readPrivate(path);
+ if (existing !== undefined) await chmod(path, 0o600);
+ await writeFile(path, text, { mode: 0o600 });
+ await chmod(path, 0o600);
+}
+
+export async function prepareDoorDirectory(env = process.env) {
+ const directory = doorDirectory(env);
+ await ownedDirectory(directory, true);
+ for (const name of ['locks', 'logs']) await ownedDirectory(join(directory, name), true);
+ return directory;
+}
+
+// The recorded door, read-only: { directory, door, sites } or undefined.
+// `sites` lists registered checkouts only, never a removed one's reservation.
+export async function readDoorState(env = process.env) {
+ const directory = doorDirectory(env);
+ if (!await ownedDirectory(directory, false)) return undefined;
+ const text = await readPrivate(join(directory, 'state.json'));
+ if (text === undefined) return undefined;
+ const state = JSON.parse(text);
+ return state.door ? { directory, door: state.door, sites: (state.sites ?? []).filter(site => !site.removed) } : undefined;
+}
+
+// Change the door state under the lock. `action(state)` edits state.door and
+// state.sites in place. (The lock's own file also keeps empty queue fields.)
+export async function changeDoorState(env, action) {
+ const directory = await prepareDoorDirectory(env);
+ await readPrivate(join(directory, 'state.json'));
+ const lifetime = await identity();
+ try {
+  return await transaction(directory, lifetime.info, async state => { state.sites ??= []; return action(state); });
+ } finally { await lifetime.close(); }
+}
+
+export async function ensureToken(directory) {
+ const path = join(directory, 'token');
+ if (await readPrivate(path) === undefined) await writeFile(path, randomBytes(32).toString('hex') + '\n', { flag: 'wx', mode: 0o600 }).catch(error => { if (error.code !== 'EEXIST') throw error; });
+ return (await readPrivate(path)).trim();
+}
+
+// The proof names the loopback address it was asked on, so a process holding
+// one address cannot relay a challenge to the door on the other.
+export const doorProof = (token, challenge, address) => createHmac('sha256', token).update(`rer-door:${address}:${challenge}`).digest('hex');
+
+// The running door's record, when its process is alive: { pid, start, port, ... }.
+export async function runningDoor(env = process.env) {
+ const directory = doorDirectory(env);
+ if (!await ownedDirectory(directory, false)) return undefined;
+ const text = await readPrivate(join(directory, 'process.json'));
+ if (!text) return undefined;
+ const record = JSON.parse(text), current = await processInfo(record.pid);
+ return current && !current.zombie && current.start === record.start ? record : undefined;
+}
+
+// Names are unique and stable per checkout. `rer door remove` keeps a removed
+// checkout's name reserved for it (`removed: true`), because its saved origin
+// still names it: the door stops routing it, no other checkout can claim it,
+// and that checkout's next rer dev or rer door add takes it back. A
+// reservation ends only when its checkout folder no longer exists.
+function releaseVanished(state) {
+ state.sites = state.sites.filter(site => !site.removed || existsSync(site.checkout));
+}
+
+const identityFile = '.rer/local/door-site.json';
+const newIdentity = () => randomBytes(16).toString('hex');
+
+// The door identity a checkout folder holds, or undefined.
+export function checkoutIdentity(root) {
+ try { const id = JSON.parse(readFileSync(join(root, identityFile), 'utf8')).id; return /^[0-9a-f]{32}$/.test(id) ? id : undefined; } catch { return undefined; }
+}
+
+export async function saveCheckoutIdentity(root, id) {
+ if (checkoutIdentity(root) === id) return;
+ const { privateDirectory, writePrivateFile } = await shared('private-files.mjs');
+ await privateDirectory(root, ['.rer', 'local']);
+ await writePrivateFile(join(root, identityFile), JSON.stringify({ id }) + '\n');
+}
+
+// In a door state being changed: the checkout's entry, claiming a name when it
+// has none (its slug, or `preferred`, with a numeric suffix when another
+// checkout holds that name). A removed entry is registered again.
+// `id` is the identity the checkout folder holds (undefined when it holds
+// none). A checkout is found by its folder, or else by its identity: a
+// registered checkout whose folder no longer holds that identity has moved,
+// and its entry follows it to the new folder, name and all. A copy (whose
+// identity the original folder still holds) is a checkout of its own and gets
+// a new identity. An entry registered before checkouts kept an identity
+// follows a checkout whose saved origin names it (`preferred`) once its own
+// folder is gone. The caller saves `entry.id` in the checkout folder.
+// `holder` names the checkout that holds `preferred` when it is not this one.
+export function claimEntry(state, checkout, preferred, id) {
+ releaseVanished(state);
+ // By folder, unless that folder now holds another checkout's identity.
+ let entry = state.sites.find(site => site.checkout === checkout && !(site.id && id && site.id !== id)), copy = false;
+ if (!entry && id) {
+  const prior = state.sites.find(site => site.id === id);
+  if (prior && checkoutIdentity(prior.checkout) !== id) entry = Object.assign(prior, { checkout, movedAt: Date.now() });
+  else copy = Boolean(prior);
+ }
+ if (!entry && preferred) {
+  const named = state.sites.find(site => site.name === preferred && !site.id && !existsSync(site.checkout));
+  if (named) entry = Object.assign(named, { checkout, movedAt: Date.now() });
+ }
+ if (entry) delete entry.removed;
+ else {
+  const taken = new Set(state.sites.map(site => site.name)), base = preferred ?? siteSlug(checkout);
+  let name = base;
+  for (let suffix = 2; taken.has(name); suffix++) name = `${base}-${suffix}`;
+  entry = { name, checkout, addedAt: Date.now() };
+  state.sites.push(entry);
+ }
+ entry.id ??= copy || !id ? newIdentity() : id;
+ const holder = preferred && entry.name !== preferred ? state.sites.find(site => site.name === preferred) : undefined;
+ return { entry, holder };
+}
+
+// A checkout's registered name, claiming one when it has none. `mode` (door or
+// direct) and a direct `origin` are kept on the entry for listings while the
+// checkout is stopped. With `exact` (a saved door origin, which names its
+// host), the claim must give `preferred` itself: when another checkout holds
+// it, or this checkout is registered under another name, nothing changes and
+// rer refuses, so a name and its cookies never reach a second checkout.
+export async function claimSiteName(env, checkout, { preferred, mode, origin, exact = false } = {}) {
+ const describe = entry => { if (mode) entry.mode = mode; if (origin) entry.origin = origin; else if (mode === 'door') delete entry.origin; };
+ const held = checkoutIdentity(checkout);
+ const claimed = await changeDoorState(env, state => {
+  const { entry, holder } = claimEntry(state, checkout, preferred, held);
+  if (exact && entry.name !== preferred) throw refuse(holder
+   ? `This checkout's saved origin names ${preferred}.localhost, which the front door has registered for another checkout (${holder.checkout}). Nothing was started and no sign-in link was printed. Give this checkout its own name: rer dev --direct, then rer dev --door.`
+   : `This checkout's saved origin names ${preferred}.localhost, but the front door has it registered as ${entry.name}. Nothing was started and no sign-in link was printed. Move it again: rer dev --direct, then rer dev --door.`);
+  describe(entry);
+  return { name: entry.name, id: entry.id };
+ });
+ await saveCheckoutIdentity(checkout, claimed.id);
+ return claimed.name;
+}
+
+const portOf = name => Number(/:(\d+)$/.exec(name)?.[1]);
+
+async function challenge(host, port, token) {
+ const { loopbackRequest } = await shared('app-fetch.mjs');
+ const nonce = randomBytes(24).toString('hex');
+ const reply = await loopbackRequest({ host, port, path: doorIdentityPath, headers: { host: `localhost:${port}`, [doorChallengeHeader]: nonce }, timeoutMs: 5000 });
+ let answer; try { answer = JSON.parse(reply.body.toString('utf8')); } catch {}
+ const expected = Buffer.from(doorProof(token, nonce, host)), given = Buffer.from(String(answer?.proof ?? ''));
+ return reply.status === 200 && given.length === expected.length && timingSafeEqual(given, expected) ? answer : undefined;
+}
+
+// Before rer prints a dev key for a door origin on port `port`: every loopback
+// listener on it must belong to the door PID recorded in its state, and the
+// door must prove it holds the 0600 token on each address it serves. While
+// `rer door restart` (or enable) replaces the door (`restarting` in its state,
+// for at most restartWindowMs), a failed check is repeated until the new door
+// passes it, so a start under way finishes against the new door.
+export const restartWindowMs = 90_000;
+export async function verifyDoor(env, port) {
+ for (;;) {
+  try { return await verifyOnce(env, port); }
+  catch (error) {
+   const since = (await readDoorState(env).catch(() => undefined))?.door?.restarting;
+   if (!(Date.now() - since < restartWindowMs)) throw error;
+   await delay(250);
+  }
+ }
+}
+
+async function verifyOnce(env, port) {
+ const directory = doorDirectory(env), record = await runningDoor(env);
+ const { listeners, processName } = await shared('process-diagnostics.mjs');
+ const holders = (await listeners()).filter(row => row.names.some(name => portOf(name) === port));
+ const foreign = holders.find(row => row.pid !== record?.pid);
+ const withheld = 'No sign-in link was printed.';
+ if (foreign) throw refuse(`Port ${port} is held by PID ${foreign.pid} (${await processName(foreign.pid)}), which is not this account's front door${record ? ` (PID ${record.pid})` : ''}. ${withheld} Stop PID ${foreign.pid}, then run rer door restart.`);
+ if (!record || record.port !== port) throw refuse(`The front door is not running on port ${port}. ${withheld} Start it with rer door start, then run this again.`);
+ const token = (await readPrivate(join(directory, 'token')))?.trim();
+ if (!token) throw refuse(`The front door's token is missing from ${directory}. ${withheld} Run rer door restart.`);
+ for (const host of ['127.0.0.1', '::1']) {
+  let answer;
+  try { answer = await challenge(host, port, token); }
+  catch (error) {
+   // No IPv6 loopback, or nothing on [::1]:P while the door serves only 127.0.0.1.
+   if (host === '::1' && ['ECONNREFUSED', 'EADDRNOTAVAIL', 'EAFNOSUPPORT', 'ENETUNREACH'].includes(error.code) && !record.addresses?.includes('::1')) continue;
+   throw refuse(`The front door (PID ${record.pid}) did not answer on ${host === '::1' ? '[::1]' : host}:${port}: ${error.code ?? error.message}. ${withheld} Run rer door restart.`);
+  }
+  if (!answer || answer.pid !== record.pid) throw refuse(`Something other than this account's front door (PID ${record.pid}) answers on ${host === '::1' ? '[::1]' : host}:${port}. ${withheld} Find and stop it, then run rer door restart.`);
+ }
+ return record;
+}

package/cli/hosted-output.mjs

@@ -32,8 +32,11 @@ async function miniflareFor(root) {
  return import(pathToFileURL(createRequire(wrangler).resolve('miniflare')));
 }
 
-// Deploy binds its declared secrets; stand-ins follow the setup manifest's kind or default.
-const standIn = field => field?.kind === 'email' ? 'owner@example.com' : typeof field?.default === 'string' && field.default ? field.default : randomBytes(24).toString('hex');
+// Deploy binds its declared secrets. A secret item's verifyStandIn is the
+// hosted-valid value this check uses (MAIL_PROVIDER: "resend" where the setup
+// default "development" is refused once deployed); otherwise stand-ins follow
+// the setup manifest's kind or default.
+const standIn = (item, field) => typeof item.verifyStandIn === 'string' && item.verifyStandIn ? item.verifyStandIn : field?.kind === 'email' ? 'owner@example.com' : typeof field?.default === 'string' && field.default ? field.default : randomBytes(24).toString('hex');
 const links = html => [...html.matchAll(/(?:src|href)=["'](\/[^"'#?\s]+)/g)].map(match => match[1].slice(1)).filter(path => !path.startsWith('/') && /\.[A-Za-z0-9]+$/.test(path));
 
 /** The build served as rer deploy hosts it, with the vars, origin and (stand-in) secrets of its
@@ -51,7 +54,7 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
  const entry = join(build, config.main);
  const modules = [entry, ...(await files(build)).map(path => join(build, path)).filter(path => path !== entry && moduleTypes[extname(path)])].map(path => ({ type: moduleTypes[extname(path)], path }));
  const identity = { sourceSha: createHash('sha1').update(randomBytes(16)).digest('hex'), fingerprint: createHash('sha256').update(randomBytes(16)).digest('hex'), versionId: crypto.randomUUID() };
- const secrets = Object.fromEntries((declaration.secrets ?? []).map(item => [item.binding, standIn(manifest.fields?.find(field => field.name === item.binding))]));
+ const secrets = Object.fromEntries((declaration.secrets ?? []).map(item => [item.binding, standIn(item, manifest.fields?.find(field => field.name === item.binding))]));
  const mf = new Miniflare(convertV4MiniflareOptions({ host: '127.0.0.1', port: 0, cf: false, workers: [{ name: 'ingress', modules: true, script: ingress, serviceBindings: { APP: 'app' } }, {
   name: 'app', modules, modulesRoot: build, compatibilityDate: config.compatibility_date, compatibilityFlags: config.compatibility_flags,
   bindings: { ...config.vars, ...declaration.vars, ...secrets, ...(declaration.originVar ? { [declaration.originVar]: ORIGIN } : {}),
@@ -83,15 +86,22 @@ export async function serveHosted(root, { declaration: declarationPath = 'deploy
 export async function checkHostedOutput(root, options) {
  const hosted = await serveHosted(root, options), { client, identity } = hosted, failures = [];
  try {
-  const request = async path => { const response = await hosted.fetch(path); return { status: response.status, type: response.headers.get('content-type') ?? '', body: await response.text() }; };
+  const request = async path => { const response = await hosted.fetch(path); return { status: response.status, type: response.headers.get('content-type') ?? '', etag: response.headers.get('etag'), body: await response.text() }; };
   const built = await files(client).catch(() => []);
   const documents = await Promise.all(built.filter(path => extname(path) === '.html').map(path => readFile(join(client, path), 'utf8')));
   const home = await request('');
   if (home.status === 200 && home.type.includes('text/html')) documents.push(home.body);
-  const paths = [...new Set([...publicAssetPaths(built).map(path => path.split('/').map(encodeURIComponent).join('/')), ...documents.flatMap(links)])];
+  // Every built file answers 200 by its own path, built `.html` documents included.
+  const html = built.filter(path => extname(path) === '.html' && !path.split('/').some(part => part.startsWith('.')));
+  const paths = [...new Set([...[...publicAssetPaths(built), ...html].map(path => path.split('/').map(encodeURIComponent).join('/')), ...documents.flatMap(links)])];
   for (let i = 0; i < paths.length; i += 8) await Promise.all(paths.slice(i, i + 8).map(async path => {
    const answer = await request(path);
    if (answer.status !== 200) failures.push(`${answer.status} /${path}`);
+   // A browser revisits a built .html with If-None-Match: it must answer 304, not the app's 404.
+   else if (answer.etag && path.endsWith('.html')) {
+    const again = await hosted.fetch(path, { headers: { 'if-none-match': answer.etag } }); await again.body?.cancel();
+    if (again.status !== 304) failures.push(`${again.status} /${path} (If-None-Match)`);
+   }
   }));
   failures.sort();
   const health = await request('health');

package/cli/hydration/browser.mjs

@@ -0,0 +1,91 @@
+// Chromium from the seed's own Playwright, the two ways of serving pages to it
+// (the production build as rer deploy hosts it, or a running origin), and one
+// load: scripts held until the probe releases them, every external request aborted.
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { RerError } from '../errors.mjs';
+import { serveHosted } from '../hosted-output.mjs';
+import { probe } from './probe.mjs';
+import { cloudflareRewrite } from './cases.mjs';
+
+const INSTALL = 'pnpm exec playwright install chromium';
+
+export async function launchChromium(root) {
+ const require = createRequire(join(root, 'package.json'));
+ let playwright, name;
+ for (const candidate of ['playwright-core', '@playwright/test', 'playwright']) { try { playwright = require(candidate); name = candidate; break; } catch {} }
+ if (!playwright?.chromium) throw new RerError('hydration_browser_missing', `The hydration check runs Chromium through the seed's own Playwright, and none of playwright-core, @playwright/test or playwright resolves from ${join(root, 'package.json')}. Add @playwright/test to devDependencies, install, then run ${INSTALL}.`, 1);
+ // Pages fulfilled by the check would otherwise count as public, and Chromium would
+ // refuse a dev server's loopback HMR socket from them.
+ try { return await playwright.chromium.launch({ args: ['--disable-features=LocalNetworkAccessChecks'] }); }
+ catch (error) { throw new RerError('hydration_browser_missing', `The hydration check could not start Chromium from the seed's ${name}: ${String(error.message).split('\n').find(line => line.trim()) ?? error}. Install the browser it pins with ${INSTALL}.`, 1); }
+}
+
+const strip = new Set(['content-encoding', 'content-length', 'transfer-encoding', 'connection']);
+const plainHeaders = headers => { const out = {}; headers.forEach((value, key) => { if (!strip.has(key)) out[key] = value; }); return out; };
+
+/** The production build served the way rer deploy hosts it, at its https origin. */
+export async function hostedServer(root, options) {
+ const hosted = await serveHosted(root, options);
+ const request = async (path, init) => { const response = await hosted.fetch(path.replace(/^\//, ''), init); return { status: response.status, headers: response.headers, body: Buffer.from(await response.arrayBuffer()) }; };
+ return { origin: hosted.origin, mode: 'hosted', close: () => hosted.close(), request,
+  answer: async route => { const r = route.request(), url = new URL(r.url()); const answer = await request(url.pathname + url.search, { method: r.method(), headers: r.headers(), body: r.postDataBuffer() ?? undefined }); return { status: answer.status, headers: plainHeaders(answer.headers), body: answer.body }; } };
+}
+
+/** A running rer dev or rer preview. */
+export function originServer(origin) {
+ origin = new URL(origin).origin;
+ const request = async (path, init) => { const response = await fetch(origin + path, { redirect: 'manual', ...init }); return { status: response.status, headers: response.headers, body: Buffer.from(await response.arrayBuffer()) }; };
+ return { origin, mode: 'origin', close: async () => {}, request,
+  answer: async route => { const response = await route.fetch({ maxRedirects: 0 }); const headers = { ...response.headers() }; for (const key of strip) delete headers[key]; return { status: response.status(), headers, body: await response.body() }; } };
+}
+
+/** One page load: returns the probe's record, console and page errors, the
+ * same-origin script requests (scripts), those answered before the probe released
+ * the hold (unheld: none unless the hold failed) and the aborted cross-origin script
+ * requests sent in CORS mode, as module fetches are (crossScripts). */
+export async function runLoad(browser, server, path, item, { timeout = 30000 } = {}) {
+ const context = await browser.newContext({ viewport: { width: 1440, height: 900 }, reducedMotion: item.reduced ? 'reduce' : 'no-preference', serviceWorkers: 'block' });
+ const errors = [], warnings = [], aborted = new Set(), scripts = new Set(), unheld = new Set(), crossScripts = new Set();
+ let release, isReleased = false; const released = new Promise(resolve => { release = () => { isReleased = true; resolve(); }; });
+ try {
+  const page = await context.newPage();
+  await page.exposeBinding('__rerRelease', () => { release(); });
+  await page.addInitScript({ content: `(${probe})(${JSON.stringify({ kind: item.kind, section: item.section, release: item.release })})` });
+  page.on('pageerror', error => errors.push(`page error: ${String(error.message).split('\n')[0]}`));
+  page.on('console', message => {
+   const text = message.text(), type = message.type();
+   if (type === 'error' && !(/^Failed to load resource/.test(text) && aborted.has(message.location().url))) errors.push(`console error: ${text.split('\n')[0].slice(0, 300)}`);
+   if (type === 'warning' && /hydrat/i.test(text)) warnings.push({ text: text.split('\n')[0].slice(0, 300), componentStack: /\n\s+at \S/.test(text) });
+  });
+  await page.route('**/*', async route => {
+   const request = route.request(), url = new URL(request.url());
+   if (url.origin !== server.origin) {
+    aborted.add(request.url());
+    if (request.resourceType() === 'script' && request.headers().origin) crossScripts.add(request.url());
+    return route.abort();
+   }
+   if (request.resourceType() === 'script') { scripts.add(url.pathname); await released; }
+   if (request.resourceType() === 'script' && !isReleased) unheld.add(url.pathname);
+   try {
+    const rewrite = item.kind === 'cloudflare' && request.isNavigationRequest() && request.frame() === page.mainFrame();
+    if (!rewrite && server.mode === 'origin') return await route.continue();
+    const answer = await server.answer(route);
+    if (rewrite && answer.status === 200) answer.body = Buffer.from(cloudflareRewrite(answer.body.toString('utf8'), { decode: item.decode }).html);
+    await route.fulfill(answer);
+   } catch (error) { if (!page.isClosed()) await route.abort().catch(() => {}); if (!/closed|disposed/i.test(String(error))) errors.push(`check could not serve ${url.pathname}: ${error.message}`); }
+  });
+  const started = Date.now();
+  await page.goto(server.origin + path, { waitUntil: 'commit', timeout });
+  const settled = await page.waitForFunction(() => window.__rerProbe?.settledAt !== null && window.__rerProbe?.settledAt !== undefined, null, { timeout, polling: 50 }).then(() => true, () => false);
+  const record = await page.evaluate(() => window.__rerProbe ?? null).catch(() => null);
+  return { record: settled ? record : { ...(record ?? {}), settled: 'timeout' }, errors, warnings, aborted: [...aborted], scripts: [...scripts], unheld: [...unheld], crossScripts: [...crossScripts], ms: Date.now() - started };
+ } finally { release(); await context.close(); }
+}
+
+/** Runs tasks with at most `width` in flight, keeping their order. */
+export async function pool(tasks, width) {
+ const results = []; let next = 0;
+ await Promise.all(Array.from({ length: Math.min(width, tasks.length) }, async () => { while (next < tasks.length) { const index = next++; results[index] = await tasks[index](); } }));
+ return results;
+}

package/cli/hydration/cases.mjs

@@ -0,0 +1,106 @@
+// Which pages the hydration check loads, which cases it runs on each, and the
+// Cloudflare email-obfuscation rewrite it applies to served HTML.
+
+export const MAX_PAGES = 6;
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/g;
+const RAW = new Set(['script', 'style', 'textarea', 'noscript', 'template', 'xmp', 'title']);
+
+const REDIRECTS = new Set([301, 302, 303, 307, 308]), HOPS = 5;
+const html = answer => answer.status === 200 && /text\/html/i.test(answer.type);
+const pagePath = (href, base) => { try { const url = new URL(href, base); return url.origin === new URL(base).origin ? url.pathname : null; } catch { return null; } };
+
+/** Requests `start` and follows same-origin redirects, at most HOPS. Returns the
+ * final { path, answer }, the redirects followed and, when the final answer is not
+ * a page, why (stopped). */
+async function follow(request, start, origin) {
+ const followed = [];
+ let path = start, answer = await request(path);
+ for (;;) {
+  if (!(REDIRECTS.has(answer.status) && answer.location)) return { path, answer, followed, stopped: html(answer) ? null : `${path} answered ${answer.status}${answer.type ? ' ' + answer.type : ''}` };
+  let next = null; try { next = new URL(answer.location, origin + path); } catch {}
+  const note = `${path} answered ${answer.status} to ${answer.location}`;
+  if (!next || next.origin !== origin) return { path, answer, followed, stopped: `${note}, another origin the check does not follow` };
+  if (followed.length >= HOPS) return { path, answer, followed, stopped: `${note}, past ${HOPS} redirects` };
+  followed.push(note); path = next.pathname + next.search; answer = await request(path);
+ }
+}
+
+/** The public pages to check: `publicPages` when the seed declares it, otherwise
+ * the page `/` answers (following same-origin redirects, at most HOPS) plus
+ * same-origin links on it that answer 200 HTML without a session (following only a
+ * trailing-slash redirect), at most MAX_PAGES. `request(path)` answers
+ * { status, type, location, body } from `origin`. Returns the pages, the redirects
+ * followed from `/` and what was not checked (refused). */
+export async function selectPages(request, declared, origin) {
+ if (Array.isArray(declared) && declared.length) return { source: 'publicPages', pages: await Promise.all([...new Set(declared)].map(async path => { const answer = await request(path); return { path, body: answer.body, cacheControl: answer.cacheControl }; })), redirects: [], refused: [] };
+ const home = await follow(request, '/', origin);
+ if (home.stopped) return { source: 'discovered', pages: [], redirects: home.followed, refused: [home.stopped] };
+ const pages = [{ path: home.path, body: home.answer.body, cacheControl: home.answer.cacheControl }], refused = [];
+ const links = [...new Set([...home.answer.body.matchAll(/<a\b[^>]*?\bhref=(["'])([^"']*)\1/gi)].map(match => match[2].startsWith('//') ? null : pagePath(match[2], origin + home.path)).filter(path => path && path !== '/' && path !== new URL(home.path, origin).pathname && !/\.[A-Za-z0-9]+$/.test(path)))];
+ for (const path of links) {
+  if (pages.length >= MAX_PAGES) break;
+  let answer = await request(path), final = path;
+  if (REDIRECTS.has(answer.status) && answer.location && pagePath(answer.location, origin + path) === path + '/') { final = path + '/'; answer = await request(final); }
+  if (html(answer)) { if (!pages.some(page => page.path === final)) pages.push({ path: final, body: answer.body, cacheControl: answer.cacheControl }); }
+  else refused.push(`${path} answered ${answer.status}${answer.location ? ' to ' + answer.location : ''}`);
+ }
+ return { source: 'discovered', pages, redirects: home.followed, refused };
+}
+
+// Cloudflare's Email Address Obfuscation: a text address becomes an anchor to
+// /cdn-cgi/l/email-protection (a span when it is already inside a link), and a
+// mailto: href becomes /cdn-cgi/l/email-protection#<hex>. <head> and raw-text
+// elements are left alone.
+const encode = address => { const key = 0x5a; return key.toString(16) + [...address].map(c => (c.charCodeAt(0) ^ key).toString(16).padStart(2, '0')).join(''); };
+const decoder = `<script>(function(){function d(h){var k=parseInt(h.slice(0,2),16),s='';for(var i=2;i<h.length;i+=2)s+=String.fromCharCode(parseInt(h.slice(i,i+2),16)^k);return s}[].forEach.call(document.querySelectorAll('a[href*="/cdn-cgi/l/email-protection#"]'),function(a){a.setAttribute('href','mailto:'+d(a.getAttribute('href').split('#')[1]))});[].forEach.call(document.querySelectorAll('.__cf_email__'),function(e){e.parentNode.replaceChild(document.createTextNode(d(e.getAttribute('data-cfemail'))),e)});document.currentScript.remove()})()</script>`;
+
+/** Returns { html, count }. With `decode`, appends Cloudflare's decoder so it runs
+ * before any held application script (the decoder is deferred; it runs before
+ * DOMContentLoaded). */
+export function cloudflareRewrite(source, { decode = false } = {}) {
+ const tag = /<!--[\s\S]*?-->|<(\/?)([A-Za-z][\w:-]*)\b[^>]*>/g;
+ let out = '', at = 0, count = 0, link = false, head = false;
+ for (;;) {
+  tag.lastIndex = at;
+  const match = tag.exec(source), end = match ? match.index : source.length;
+  const text = source.slice(at, end);
+  out += head ? text : text.replace(EMAIL, address => { count++; return link ? `<span class="__cf_email__" data-cfemail="${encode(address)}">[email&#160;protected]</span>` : `<a href="/cdn-cgi/l/email-protection" class="__cf_email__" data-cfemail="${encode(address)}">[email&#160;protected]</a>`; });
+  if (!match) break;
+  let token = match[0];
+  const closing = match[1] === '/', name = match[2]?.toLowerCase();
+  if (name === 'head') head = !closing;
+  if (name === 'a') {
+   link = !closing;
+   if (!closing) token = token.replace(/\bhref=(["'])mailto:([^"'?]+)([^"']*)\1/i, (all, quote, address) => { count++; return `href=${quote}/cdn-cgi/l/email-protection#${encode(decodeURIComponent(address))}${quote}`; });
+  }
+  out += token; at = match.index + match[0].length;
+  if (name && !closing && RAW.has(name)) { const close = source.toLowerCase().indexOf('</' + name, at), stop = close < 0 ? source.length : close; out += source.slice(at, stop); at = stop; }
+ }
+ if (decode) { const close = out.lastIndexOf('</body>'); out = close < 0 ? out + decoder : out.slice(0, close) + decoder + out.slice(close); }
+ return { html: out, count };
+}
+
+/** The loads for one page, from its plain load's survey. */
+export function planCases(page) {
+ const cases = [];
+ page.survey.sections.forEach((section, index) => {
+  if (!section.split && !section.lone) return;
+  cases.push({ kind: 'section', section: index, release: 'after' });
+  if (page.intros.some(key => key === section.key || key.startsWith(section.key + '>'))) cases.push({ kind: 'section', section: index, release: 'mid' });
+ });
+ if (page.survey.loose) cases.push({ kind: 'loose', release: 'after' });
+ if (page.addresses) for (const decode of [true, false]) {
+  cases.push({ kind: 'cloudflare', decode, release: 'after' });
+  if (page.intros.length) cases.push({ kind: 'cloudflare', decode, release: 'mid' });
+ }
+ cases.push({ kind: 'plain', reduced: true, release: 'after' });
+ return cases;
+}
+
+export function describeCase(item, survey) {
+ const when = item.release === 'mid' ? 'released mid-intro' : 'released after the intros';
+ if (item.kind === 'section') { const section = survey.sections[item.section]; return `edit in ${section.label} (${section.key}), ${when}`; }
+ if (item.kind === 'loose') return `edit in text outside every section, ${when}`;
+ if (item.kind === 'cloudflare') return `Cloudflare email rewrite ${item.decode ? 'decoded before hydration' : 'with its anchors present at hydration'}, ${when}`;
+ return item.reduced ? 'plain load with prefers-reduced-motion: reduce' : 'plain load';
+}

package/cli/hydration/check.mjs

@@ -0,0 +1,105 @@
+// The Base hydration check (SEED-COMMAND-CONTRACT.md, "Hydration units"). rer
+// verify runs it on the production build served as rer deploy hosts it; run it on
+// its own against a running rer dev or rer preview with --origin:
+//   node scripts/base-cli/cli/hydration/check.mjs [ROOT] [--origin URL] [--pages /,/docs] [--details]
+// For each public page it edits text in each page section before React hydrates
+// (scripts held in the network layer) and fails when anything outside that section
+// is replaced, an intro replays, a frame loses a section, recovery is noisy or
+// uncounted, or a hydrated page's document lacks Cache-Control: no-transform.
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { RerError } from '../errors.mjs';
+import { hostedServer, launchChromium, originServer, pool, runLoad } from './browser.mjs';
+import { cloudflareRewrite, describeCase, planCases, selectPages } from './cases.mjs';
+import { applicationScripts } from './scripts.mjs';
+import { judgePage, judgeUnhydrated, measure, plainHtml } from './verdict.mjs';
+
+const CONTEXTS = 3;
+
+/** Checks the pages and returns the result; `report(lines)` receives its human
+ * summary (pages, skips, redirects followed, what was not checked) before it
+ * returns or fails on a page. With no page to load it fails naming why. */
+export async function checkHydration(root, { origin, pages: declared, declaration, report } = {}) {
+ const started = Date.now();
+ const server = origin ? originServer(origin) : await hostedServer(root, { declaration });
+ let browser;
+ try {
+  const request = async path => { const answer = await server.request(path); return { status: answer.status, type: answer.headers.get('content-type') ?? '', location: answer.headers.get('location'), cacheControl: answer.headers.get('cache-control'), body: answer.body.toString('utf8') }; };
+  const failures = [];
+  const selection = await selectPages(request, declared, server.origin);
+  // A check that loads no page proves nothing, so it fails rather than passing.
+  if (!selection.pages.length) {
+   const notChecked = [...selection.redirects, ...selection.refused];
+   throw new RerError('hydration_no_pages', `The hydration check loaded no page, so it checked nothing. Not checked: ${notChecked.join('; ')}. Make / answer a page as HTML (directly or through a redirect on the same origin), or name the seed's public pages with the commandAdapter option publicPages (SEED-COMMAND-CONTRACT.md, Hydration units).`, 1, { hydration: { pages: [], redirects: selection.redirects, notChecked: selection.refused, loads: 0 } });
+  }
+  browser = await launchChromium(root);
+  const plain = { kind: 'plain', release: 'after' };
+  const baselines = await pool(selection.pages.map(page => () => runLoad(browser, server, page.path, plain)), CONTEXTS);
+  const pages = selection.pages.map((page, index) => {
+   const baseline = baselines[index], record = baseline.record;
+   const hydrated = record?.settled === 'hydrated', scripts = applicationScripts(baseline, page.body, server.origin, page.path);
+   const intros = [...new Set((record?.oneShot ?? []).map(id => id.split(' ')[0]))];
+   return { path: page.path, cacheControl: page.cacheControl, baseline, survey: record?.survey ?? { sections: [], loose: false, advisories: [] }, intros, addresses: cloudflareRewrite(page.body).count > 0, hydrated, scripts, skipped: plainHtml(baseline, scripts) };
+  });
+  // Only a document React hydrates needs no-transform: a redirect or a page that
+  // never hydrates has no HTML whose rewrite could cause a mismatch.
+  for (const page of pages.filter(page => page.hydrated)) if (!/(^|[\s,])no-transform($|[\s,])/i.test(page.cacheControl ?? '')) failures.push(`${page.path} document: Cache-Control is "${page.cacheControl ?? 'absent'}" and lacks no-transform, so a proxy (Cloudflare's email address obfuscation) may rewrite the HTML React hydrates`);
+  for (const page of pages) if (!page.hydrated && !page.skipped) failures.push(judgeUnhydrated(page));
+  const work = pages.filter(page => page.hydrated).flatMap(page => planCases(page).map(item => ({ page, item })));
+  const loads = await pool(work.map(({ page, item }) => () => runLoad(browser, server, page.path, item)), CONTEXTS);
+  work.forEach(({ page, item }, index) => { (page.loads ??= []).push({ item, load: loads[index] }); });
+  for (const page of pages.filter(page => page.hydrated)) failures.push(...judgePage({ ...page, loads: page.loads ?? [] }));
+  const result = {
+   served: server.mode === 'hosted' ? 'production build as rer deploy hosts it' : server.origin,
+   pages: pages.map(page => page.skipped ? { path: page.path, skipped: 'plain HTML: React does not hydrate this page and it loads no application script' } : {
+    path: page.path,
+    sections: page.survey.sections.map(section => `${section.label} (${section.key})`),
+    intros: page.baseline.record?.oneShot ?? [],
+    loads: 1 + (page.loads?.length ?? 0),
+    advisories: page.survey.advisories.map(item => `${item.section}: "${item.text}" is text beside sibling elements and holds an email address; make the address the only child of its element`),
+    cases: (page.loads ?? []).map(({ item, load }) => summarize(item, load, page)),
+   }),
+   ...(selection.redirects.length ? { redirects: selection.redirects } : {}),
+   ...(selection.refused.length ? { notChecked: selection.refused } : {}),
+   loads: pages.length + loads.length,
+   ms: Date.now() - started,
+  };
+  report?.(summary(result));
+  if (failures.length) throw new RerError('hydration_units_failed', `Page sections did not hydrate as separate units:\n  ${failures.join('\n  ')}\nEvery page section and the root chrome sit in a HydrationUnit, intros carry data-intro under the root's intro guard, and the client entry passes createRecoverableErrorHandler (src/base/hydration/README.md; SEED-COMMAND-CONTRACT.md, Hydration units).`, 1, { failures, hydration: result });
+  return result;
+ } finally { await browser?.close(); await server.close(); }
+}
+
+/** The human lines for a result: each page, then redirects and what was not checked. */
+export function summary(result) {
+ return [`Hydration check: ${result.pages.length} page(s), ${result.loads} load(s)`,
+  ...result.pages.map(page => `  ${page.path}: ${page.skipped ? `skipped, ${page.skipped}` : `${page.loads} load(s), ${page.sections.length} section(s)`}`),
+  ...(result.redirects ?? []).map(note => `  redirect followed: ${note}`),
+  ...(result.notChecked ?? []).map(note => `  not checked: ${note}`)];
+}
+
+function summarize(item, load, page) {
+ const record = load.record ?? {}, { replaced, outside, replays, missing } = record.replaced ? measure(item, record, page) : { replaced: [], outside: [], replays: [], missing: [] };
+ return { case: describeCase(item, page.survey), ...(record.edit ? { edit: `${record.edit.mode} "${record.edit.text}"` } : {}), ...(record.releaseNote ? { released: record.releaseNote } : {}), ...(record.fiberAtRelease ? { hydratedBeforeRelease: true } : {}), ...(load.unheld?.length ? { unheld: load.unheld } : {}),
+  replaced: replaced.length, replacedOutside: outside.length, replays: replays.length, framesMissingSection: missing.length, frames: record.frames, recovered: record.rer?.count ?? 0,
+  ...(load.warnings.length ? { warnings: load.warnings.length, warningsWithStack: load.warnings.filter(w => w.componentStack).length, warning: load.warnings[0].text.slice(0, 160) } : {}), ...(load.errors.length ? { errors: load.errors } : {}), ...(load.aborted.length ? { aborted: load.aborted } : {}) };
+}
+
+async function declaredPages(root) {
+ try { const { resolveProject } = await import('../project.mjs'); const project = await resolveProject(root); return { pages: project.adapter?.publicPages, declaration: project.adapter?.deployDeclaration ?? project.adapter?.deploy?.declaration }; }
+ catch { return {}; }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+ const args = process.argv.slice(2), flag = name => { const at = args.indexOf(name); return at < 0 ? undefined : args.splice(at, 2)[1]; };
+ const origin = flag('--origin'), pages = flag('--pages')?.split(',').filter(Boolean), details = args.includes('--details');
+ const root = resolve(args.find(arg => !arg.startsWith('--')) ?? '.'), declared = await declaredPages(root);
+ try {
+  const result = await checkHydration(root, { origin, pages: pages ?? declared.pages, declaration: declared.declaration });
+  console.log(JSON.stringify(details ? result : { ...result, pages: result.pages.map(({ cases, ...page }) => page) }, null, 1));
+ } catch (error) {
+  console.error(error.message);
+  if (details && error.hydration) console.error(JSON.stringify(error.hydration, null, 1));
+  process.exitCode = 1;
+ }
+}