@runeditrun/rer 0.1.1 → 0.2.0

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;
+ }
+}

package/cli/hydration/probe.mjs

@@ -0,0 +1,164 @@
+// The in-page half of the hydration check. `probe` is serialized into an init
+// script, so it must stay self-contained (no imports, no closures over module
+// scope). It runs before the document parses, while the check holds every
+// application script in the network layer:
+//  - when parsing ends (readyState "interactive"), it surveys the page sections,
+//    makes the case's edit, snapshots every element in <body> and starts sampling;
+//  - it releases the held scripts (window.__rerRelease) once every one-shot
+//    animation has finished ("after") or at the midpoint of the edited section's
+//    intro window ("mid"), recording whether React had already hydrated;
+//  - every frame it samples one-shot animations, the opacity of animated elements
+//    and which page sections are present;
+//  - once React owns the page and the DOM and animations are quiet, it records
+//    which snapshot elements were replaced and sets settledAt.
+// Elements are matched across a rebuild by a structural key (tag:index path from
+// <body>) that ignores script, style, link, template and noscript elements and the
+// nodes the probe inserted.
+export function probe(config) {
+ const S = window.__rerProbe = { config, survey: null, edit: null, editBeforeHydration: null, sectionKeys: [], addressSections: [], addressLoose: false,
+  replaced: [], starts: {}, opacity: {}, missing: [], frames: 0, oneShot: [], releasedAt: null, releaseNote: null, fiberAtRelease: null, hydratedAt: null, settledAt: null, settled: null, rer: null, error: null };
+ const SECTION = new Set(['HEADER', 'NAV', 'SECTION', 'ARTICLE', 'ASIDE', 'FOOTER']), SKIP = new Set(['SCRIPT', 'STYLE', 'LINK', 'TEMPLATE', 'NOSCRIPT']);
+ const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/, ADDRESS = '.__cf_email__,a[href*="/cdn-cgi/l/email-protection"]';
+ const inserted = new WeakSet(), tracked = new WeakMap(), watch = new Set();
+ const now = () => Math.round(performance.now() * 10) / 10;
+ const own = (el, prefix) => { for (const key of Object.keys(el)) if (key.startsWith(prefix)) return el[key]; return undefined; };
+ const fiber = el => own(el, '__reactFiber$') !== undefined;
+ const counted = el => !SKIP.has(el.tagName) && !inserted.has(el);
+ const kids = el => [...el.children].filter(counted);
+ const keyOf = el => {
+  const parts = [];
+  for (let e = el; e !== document.body; e = e.parentElement) { if (!e || !e.parentElement || !counted(e)) return null; parts.unshift(e.tagName.toLowerCase() + ':' + kids(e.parentElement).indexOf(e)); }
+  return parts.join('>');
+ };
+ const resolveKey = key => {
+  let el = document.body;
+  for (const part of key.split('>')) { const at = part.lastIndexOf(':'); el = kids(el)[+part.slice(at + 1)]; if (!el || el.tagName.toLowerCase() !== part.slice(0, at)) return null; }
+  return el;
+ };
+ const walk = (el, key, out) => { let i = 0; for (const child of el.children) { if (!counted(child)) continue; const k = (key ? key + '>' : '') + child.tagName.toLowerCase() + ':' + i++; out.push([child, k]); walk(child, k, out); } return out; };
+ const outermost = () => { const out = []; const visit = el => { for (const child of el.children) { if (!counted(child)) continue; if (SECTION.has(child.tagName)) out.push(child); else visit(child); } }; visit(document.body); return out; };
+ const label = el => el.tagName.toLowerCase() + (el.id ? '#' + el.id : el.classList.length ? '.' + el.classList[0] : '') + (el.getAttribute('aria-label') ? `[aria-label="${el.getAttribute('aria-label')}"]` : '');
+ const texts = root => {
+  const out = [], walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) { const p = n.parentElement; if (p && !p.closest('script,style,template,noscript,textarea,svg') && n.nodeValue.trim()) out.push(n); }
+  return out;
+ };
+ // A text node with sibling nodes is a separate text fiber: splitting it always mismatches.
+ const mixed = n => n.nodeValue.trim().length >= 4 && n.parentNode.childNodes.length >= 2;
+ const lone = n => n.nodeValue.trim().length >= 2 && n.parentNode.childNodes.length === 1;
+ const split = n => { const rest = n.splitText(Math.max(1, Math.floor(n.nodeValue.length / 2))), span = document.createElement('span'); inserted.add(span); span.textContent = rest.nodeValue; rest.replaceWith(span); };
+ const anyFiber = () => fiber(document.body) || [...document.body.querySelectorAll('*')].some(fiber);
+ // An element React has not hydrated yet: no fiber, under a parent React owns that does not set its HTML.
+ const pending = () => [...document.body.querySelectorAll('*')].filter(el => counted(el) && !el.closest('svg') && !fiber(el) && el.parentElement && fiber(el.parentElement) && !own(el.parentElement, '__reactProps$')?.dangerouslySetInnerHTML).length;
+ const oneShot = () => document.getAnimations().filter(a => {
+  if (typeof CSSTransition !== 'undefined' && a instanceof CSSTransition) return false;
+  const timing = a.effect && a.effect.getComputedTiming();
+  return timing && Number.isFinite(timing.endTime) && timing.activeDuration >= 50;
+ });
+ const outside = n => !outermost().some(section => section.contains(n));
+ let snapshot = [], scope = null, editAt = null, lastMutation = 0;
+
+ function begin() {
+  const sections = outermost();
+  S.sectionKeys = sections.map(keyOf);
+  S.survey = {
+   sections: sections.map(section => { const all = texts(section); return { key: keyOf(section), label: label(section), split: all.some(mixed), lone: all.some(lone) }; }),
+   loose: texts(document.body).some(n => outside(n) && mixed(n)),
+   advisories: texts(document.body).filter(n => mixed(n) && EMAIL.test(n.nodeValue)).map(n => { const section = sections.find(s => s.contains(n)); return { section: section ? label(section) : 'outside every section', text: n.nodeValue.trim().slice(0, 80) }; }),
+  };
+  S.addressSections = sections.filter(s => s.querySelector(ADDRESS) || EMAIL.test(s.textContent)).map(keyOf);
+  S.addressLoose = texts(document.body).some(n => outside(n) && EMAIL.test(n.nodeValue)) || [...document.querySelectorAll(ADDRESS)].some(outside);
+  S.editBeforeHydration = !anyFiber();
+  if (config.kind === 'section' || config.kind === 'loose') {
+   const root = config.kind === 'section' ? sections[config.section] : document.body;
+   if (config.kind === 'section') scope = root;
+   const candidates = root ? texts(root).filter(n => config.kind === 'section' || outside(n)) : [];
+   const target = candidates.find(mixed) ?? (config.kind === 'section' ? candidates.find(lone) : undefined);
+   if (target) {
+    const mode = mixed(target) ? 'split' : 'text';
+    S.edit = { mode, parent: keyOf(target.parentElement), text: target.nodeValue.trim().slice(0, 60) };
+    if (mode === 'split') split(target); else target.nodeValue = 'Übersetzt: ' + target.nodeValue;
+   }
+  }
+  snapshot = walk(document.body, '', []);
+  editAt = now();
+  new MutationObserver(() => { lastMutation = now(); }).observe(document.body, { childList: true, subtree: true, characterData: true });
+  requestAnimationFrame(frame);
+ }
+
+ function release(note) {
+  // React owning any element already means a script the check could not hold (an
+  // inline module script) hydrated the page, so the release timing was not exercised.
+  S.releasedAt = now(); S.releaseNote = note ?? null; S.fiberAtRelease = anyFiber();
+  window.__rerRelease();
+ }
+
+ function tryRelease() {
+  if (S.releasedAt !== null || S.frames < 3) return;
+  const animations = oneShot();
+  if (config.release === 'mid') {
+   const mine = animations.filter(a => (scope ?? document.body).contains(a.effect.target));
+   if (!mine.length) return release('no intro to release into');
+   if (mine.some(a => a.startTime === null)) return;
+   const start = Math.min(...mine.map(a => a.startTime + a.effect.getTiming().delay)), end = Math.max(...mine.map(a => a.startTime + a.effect.getComputedTiming().endTime));
+   const at = document.timeline.currentTime;
+   if (at >= (start + end) / 2) release(`${Math.round(100 * (at - start) / (end - start))}% through the intro window (${Math.round(start)}-${Math.round(end)} ms)`);
+   return;
+  }
+  if (animations.some(a => a.playState !== 'finished') && now() - editAt < 15000) return;
+  release();
+ }
+
+ function sample() {
+  S.frames++;
+  for (const a of oneShot()) {
+   const el = a.effect.target;
+   if (!el || !el.isConnected) continue;
+   let record = tracked.get(el);
+   // A new element object at a key gets a new id, so a rebuilt element is a second entry.
+   if (!record) { const key = keyOf(el); if (key === null) continue; record = { key, id: S.oneShot.length + 1 }; tracked.set(el, record); watch.add(key); }
+   const name = a.animationName || a.id || 'animation', list = (S.starts[record.key + ' ' + name] ??= []);
+   if (!S.oneShot.includes(record.key + ' ' + name)) S.oneShot.push(record.key + ' ' + name);
+   if (a.startTime !== null && !list.some(item => item.id === record.id)) list.push({ id: record.id, start: Math.round((a.startTime + a.effect.getTiming().delay) * 10) / 10, seen: now() });
+  }
+  for (const key of watch) {
+   const el = resolveKey(key);
+   if (!el) continue;
+   const opacity = +getComputedStyle(el).opacity, record = (S.opacity[key] ??= { first: opacity, max: opacity, dip: null });
+   if (opacity > record.max) record.max = opacity;
+   else if (record.max > record.first && record.max - opacity > 0.15 && (!record.dip || record.max - opacity > record.dip.from - record.dip.to)) record.dip = { from: record.max, to: opacity, at: now() };
+  }
+  const present = new Set(outermost().map(keyOf)), lost = S.sectionKeys.filter(key => !present.has(key));
+  if (lost.length) S.missing.push({ at: now(), lost });
+ }
+
+ function frame() {
+  if (S.settledAt !== null) return;
+  try {
+   sample();
+   tryRelease();
+   const t = now();
+   if (S.releasedAt !== null) {
+    if (S.hydratedAt === null && fiber(document.body) && pending() === 0) S.hydratedAt = t;
+    const quiet = t - lastMutation > 300 && !oneShot().some(a => a.playState === 'running');
+    if (S.hydratedAt !== null && t - S.hydratedAt > 300 && quiet) return settle('hydrated');
+    if (S.hydratedAt === null && t - S.releasedAt > 8000 && !anyFiber()) return settle('not hydrated');
+    if (t - S.releasedAt > 20000) return settle('timeout');
+   }
+  } catch (error) { S.error = String(error && error.stack || error); return settle('error'); }
+  requestAnimationFrame(frame);
+ }
+
+ function settle(state) {
+  S.settled = state; S.settledAt = now();
+  S.replaced = snapshot.filter(([el]) => !el.isConnected).map(([, key]) => key);
+  S.rer = window.__rerHydration ? JSON.parse(JSON.stringify(window.__rerHydration)) : null;
+ }
+
+ let begun = false;
+ document.addEventListener('readystatechange', () => {
+  if (begun || document.readyState === 'loading') return;
+  begun = true;
+  try { begin(); } catch (error) { S.error = String(error && error.stack || error); settle('error'); }
+ });
+}

package/cli/hydration/scripts.mjs

@@ -0,0 +1,39 @@
+// Which scripts a page loads count as the application's, so a page that loads them
+// and never hydrates fails rather than being skipped as plain HTML. They are:
+// script requests to the page's own origin; module scripts and modulepreload links
+// in the served document, from any origin (a Vite base on a CDN host); and
+// cross-origin script requests sent in CORS mode, as every module fetch is, that
+// the document does not name as a classic <script src>. A third-party classic
+// script on a plain-HTML page is none of these.
+
+const attribute = (attrs, name) => { const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>\`]+))`, 'i').exec(attrs); return match ? (match[1] ?? match[2] ?? match[3]) : null; };
+const resolveUrl = (href, base) => { try { return new URL(href, base).href; } catch { return null; } };
+
+/** The module scripts (inline ones as "inline module script"), modulepreload links
+ * and classic script sources of a served document, as absolute URLs. */
+export function documentScripts(html, pageUrl) {
+ const tag = /<!--[\s\S]*?-->|<(script|link)\b([^>]*)>/gi, modules = [], classic = [];
+ for (let match; (match = tag.exec(html));) {
+  const name = match[1]?.toLowerCase(), attrs = match[2] ?? '';
+  if (name === 'link') {
+   const href = attribute(attrs, 'href');
+   if (href && (attribute(attrs, 'rel') ?? '').toLowerCase().split(/\s+/).includes('modulepreload')) modules.push(resolveUrl(href, pageUrl));
+  } else if (name === 'script') {
+   const src = attribute(attrs, 'src'), module = (attribute(attrs, 'type') ?? '').trim().toLowerCase() === 'module';
+   if (module) modules.push(src ? resolveUrl(src, pageUrl) : 'inline module script');
+   else if (src) classic.push(resolveUrl(src, pageUrl));
+   const close = html.toLowerCase().indexOf('</script', tag.lastIndex);
+   tag.lastIndex = close < 0 ? html.length : close;
+  }
+ }
+ return { modules: modules.filter(Boolean), classic: classic.filter(Boolean) };
+}
+
+/** The application scripts of one load of `path`, given the document it was served:
+ * same-origin paths as paths, other origins as full URLs. */
+export function applicationScripts(load, html, origin, path) {
+ const page = new URL(path, origin), show = url => { const parsed = new URL(url, page); return parsed.origin === page.origin ? parsed.pathname + parsed.search : parsed.href; };
+ const { modules, classic } = documentScripts(html ?? '', page.href), named = new Set(classic);
+ const found = [...load.scripts, ...modules.map(url => url === 'inline module script' ? url : show(url)), ...load.crossScripts.filter(url => !named.has(url)).map(show)];
+ return [...new Set(found)];
+}