webrecipe 0.1.0

package/dist/src/benchmark/screen.js

@@ -0,0 +1,144 @@
+import { SETTLE_MS } from '../browser/navigate.js';
+import { openSession } from '../browser/session.js';
+import { DEFAULT_USER_AGENT, PolitenessLayer } from '../net/politeness.js';
+/**
+ * Held-out 4's accessibility screen was robots.txt plus one GET, and it passed
+ * three sites that turned out to be boundaries: a virtualised timeline the plan
+ * sees one row of, a page that does not render in time, and a site that hands
+ * the engine a 200 challenge. Each of those is visible before a plan exists,
+ * but only by putting the engine's client and a real browser side by side.
+ *
+ * This measures; it does not judge. Even the line about the two pages differing
+ * names the evidence rather than returning a verdict: mastodon.social reads as
+ * a title mismatch because its SPA shell is titled differently, which is true
+ * and is not musicbrainz's kind of discrimination. The human decides which it is.
+ */
+const NAVIGATION_TIMEOUT_MS = 30_000;
+/** A body this much smaller than the browser's is not the same page. */
+const SIZE_RATIO = 0.1;
+function titleOf(html) {
+    return /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html)?.[1]?.trim() ?? null;
+}
+/** The longest array anywhere in a payload, which is what a listing arrives as. */
+export function largestArray(value) {
+    if (Array.isArray(value)) {
+        return value.reduce((best, v) => Math.max(best, largestArray(v)), value.length);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.values(value).reduce((best, v) => Math.max(best, largestArray(v)), 0);
+    }
+    return 0;
+}
+/**
+ * The largest run of sibling elements sharing a tag+class signature, which is
+ * the same heuristic the authoring scratch scripts used to find a listing
+ * before anyone had written a selector for it.
+ */
+const LARGEST_SIBLING_RUN = `(() => {
+  let best = { count: 0, signature: '' }
+  const walk = (parent) => {
+    const counts = new Map()
+    for (const child of parent.children) {
+      const cls = (child.getAttribute('class') || '').trim().split(/\\s+/).filter(Boolean).join('.')
+      const signature = child.tagName.toLowerCase() + (cls ? '.' + cls : '')
+      counts.set(signature, (counts.get(signature) || 0) + 1)
+    }
+    for (const [signature, count] of counts) {
+      if (count > best.count) best = { count, signature }
+    }
+    for (const child of parent.children) walk(child)
+  }
+  if (document.body) walk(document.body)
+  return best.count > 0 ? best : null
+})()`;
+export async function screen(url, net) {
+    const client = net ?? new PolitenessLayer({ userAgent: DEFAULT_USER_AGENT });
+    const fetched = await client.fetch(url);
+    const session = await openSession();
+    let largestJsonArray = 0;
+    const bodies = [];
+    session.page.on('response', (response) => {
+        if (!/json/i.test(response.headers()['content-type'] ?? ''))
+            return;
+        bodies.push(response
+            .text()
+            .then((text) => { largestJsonArray = Math.max(largestJsonArray, largestArray(JSON.parse(text))); })
+            .catch(() => undefined));
+    });
+    try {
+        const started = Date.now();
+        const response = await session.page.goto(url, {
+            waitUntil: 'domcontentloaded',
+            timeout: NAVIGATION_TIMEOUT_MS,
+        });
+        // Idle is the condition a slow page fails, so it gets the full navigation
+        // budget rather than navigate.ts's short best-effort wait. A run that ends
+        // at the timeout is the measurement, which is why whether it arrived is
+        // reported beside the number.
+        const networkIdle = await session.page
+            .waitForLoadState('networkidle', { timeout: NAVIGATION_TIMEOUT_MS })
+            .then(() => true)
+            .catch(() => false);
+        await session.page.waitForTimeout(SETTLE_MS);
+        const renderMs = Date.now() - started;
+        // A body still parsing is part of the measurement. Left to race the report,
+        // it is silently missed, and a missed array is what a virtualised list
+        // looks like.
+        await Promise.all(bodies);
+        const html = await session.page.content();
+        const browser = {
+            status: response?.status() ?? 0,
+            bytes: Buffer.byteLength(html, 'utf8'),
+            title: titleOf(html),
+        };
+        const engine = {
+            status: fetched.status,
+            bytes: fetched.bytesDownloaded,
+            title: titleOf(fetched.body),
+        };
+        const carriesBrowserTitle = browser.title !== null && browser.title !== '' && fetched.body.includes(browser.title);
+        return {
+            url,
+            engine,
+            browser,
+            carriesBrowserTitle,
+            differences: differencesBetween(engine, browser),
+            renderMs,
+            networkIdle,
+            largestListing: (await session.page.evaluate(LARGEST_SIBLING_RUN)),
+            largestJsonArray,
+        };
+    }
+    finally {
+        await session.close();
+    }
+}
+function differencesBetween(engine, browser) {
+    const differences = [];
+    if (engine.title !== browser.title)
+        differences.push('title mismatch');
+    if (browser.bytes > 0 && engine.bytes < browser.bytes * SIZE_RATIO) {
+        differences.push(`engine body is ${Math.round((engine.bytes / browser.bytes) * 100)}% of browser`);
+    }
+    return differences;
+}
+function kb(bytes) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+}
+function side(name, s) {
+    return `  ${name.padEnd(8)} ${String(s.status).padEnd(4)} ${kb(s.bytes).padStart(8)}  ${JSON.stringify(s.title)}`;
+}
+export function formatScreen(r) {
+    const listing = r.largestListing === null
+        ? 'largest listing: none'
+        : `largest listing: ${r.largestListing.count} × ${r.largestListing.signature}`;
+    return [
+        r.url,
+        side('engine', r.engine),
+        side('browser', r.browser),
+        `  engine body carries the browser title: ${r.carriesBrowserTitle ? 'yes' : 'no'}`,
+        `  engine page differs from browser page: ${r.differences.join(', ') || 'no'}`,
+        `  render: ${r.renderMs}ms${r.networkIdle ? '' : ' (networkidle not reached)'}`,
+        `  ${listing}   largest json array: ${r.largestJsonArray}`,
+    ].join('\n');
+}

package/dist/src/benchmark/selector-score.js

@@ -0,0 +1,86 @@
+import { elementsOf, generateCandidates, loadPage, normalize, perceivedText } from '../authoring/candidates.js';
+/** `/item/1` must not answer for `/item/12`, so the match has to end at a boundary. */
+function hrefCovers(href, item) {
+    let from = 0;
+    for (;;) {
+        const at = href.indexOf(item, from);
+        if (at === -1)
+            return false;
+        const after = href[at + item.length];
+        if (after === undefined || !/[A-Za-z0-9_-]/.test(after))
+            return true;
+        from = at + 1;
+    }
+}
+function coversOf($, el, label) {
+    if (label.identifier === 'text') {
+        const text = perceivedText($, el);
+        return label.items.flatMap((item, i) => (text.includes(normalize(item)) ? [i] : []));
+    }
+    const own = $(el).attr('href');
+    const hrefs = [...(own === undefined ? [] : [own]), ...$(el).find('[href]').map((_, n) => $(n).attr('href') ?? '').toArray()];
+    return label.items.flatMap((item, i) => (hrefs.some((href) => hrefCovers(href, item)) ? [i] : []));
+}
+function scoreAgainst($, selector, label) {
+    const matched = elementsOf($, selector);
+    if (matched.length === 0)
+        return { precision: 0, recall: 0, exact: false };
+    const covers = matched.map((el) => coversOf($, el, label));
+    const covered = new Set(covers.flat());
+    const precision = covers.filter((c) => c.length > 0).length / matched.length;
+    const recall = covered.size / label.items.length;
+    // A single <ul> wrapping every item scores 1.00 on both ratios and is not an
+    // item selector, so exactness asks for a one-to-one correspondence as well.
+    const onePerMatch = covers.every((c) => c.length === 1);
+    const onePerItem = label.items.every((_, i) => covers.filter((c) => c.includes(i)).length === 1);
+    const exact = matched.length === label.items.length && onePerMatch && onePerItem;
+    return { precision, recall, exact };
+}
+export function scoreSelector(html, selector, label) {
+    return scoreAgainst(loadPage(html), selector, label);
+}
+export function scoreSnapshot(snapshot, html, label) {
+    const $ = loadPage(html);
+    const rows = generateCandidates(html).map((candidate) => ({
+        candidate,
+        score: scoreAgainst($, candidate.selector, label),
+    }));
+    const found = rows.findIndex((r) => r.score.exact);
+    return {
+        snapshot,
+        labeled: label.items.length,
+        rows,
+        exactRank: found === -1 ? null : found + 1,
+        topIsExact: rows[0]?.score.exact === true,
+    };
+}
+const pct = (value) => value.toFixed(2);
+/** Rows are for a human to scan; the measurement itself runs over the full list. */
+const MAX_ROWS_SHOWN = 50;
+function formatSnapshotReport(report) {
+    const lines = [
+        `${report.snapshot}  (${report.labeled} labeled items)`,
+        `  generator: an exact candidate is present   ${report.exactRank === null ? 'no' : `yes  (rank ${report.exactRank} of ${report.rows.length})`}`,
+        `  heuristic: top candidate is exact          ${report.topIsExact ? 'yes' : 'no'}`,
+    ];
+    report.rows.slice(0, MAX_ROWS_SHOWN).forEach(({ candidate, score }, i) => {
+        const mark = score.exact ? '  <- exact' : '';
+        const scope = candidate.scoped ? '' : '  (unscoped)';
+        lines.push(`  ${String(i + 1).padStart(2)}. ${candidate.selector.padEnd(44)} ${String(candidate.count).padStart(4)}` +
+            `  p=${pct(score.precision)} r=${pct(score.recall)}${mark}${scope}`);
+    });
+    if (report.rows.length > MAX_ROWS_SHOWN) {
+        lines.push(`  ... and ${report.rows.length - MAX_ROWS_SHOWN} further candidates, not shown`);
+    }
+    return lines.join('\n');
+}
+export function formatCorpus(reports) {
+    const generated = reports.filter((r) => r.exactRank !== null).length;
+    const ranked = reports.filter((r) => r.topIsExact).length;
+    return [
+        ...reports.map(formatSnapshotReport),
+        '',
+        `generator recall:  ${generated}/${reports.length}`,
+        `ranking accuracy:  ${ranked}/${reports.length}`,
+    ].join('\n\n');
+}

package/dist/src/benchmark/verification-cases.js

@@ -0,0 +1,138 @@
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { teach } from '../authoring/teach.js';
+import { HttpHtmlStrategy } from '../executor/strategies/http-html.js';
+import { HttpJsonStrategy } from '../executor/strategies/http-json.js';
+import { PolitenessLayer } from '../net/politeness.js';
+import { StaticSiteResolver } from '../sites.js';
+import { judgeByGroundTruth, DATASET_TRUTH, PAGE_TRUTH, pageWindow } from './ground-truth.js';
+import { structurallySuccessful } from './verification-matrix.js';
+import { CheckNameSchema } from '../local.js';
+import { startSsrFixture } from '../../fixtures/ssr.js';
+import { startIgnoringFixture } from '../../fixtures/ignoring.js';
+import { startShiftedFixture } from '../../fixtures/shifted.js';
+import { startVolatileFixture } from '../../fixtures/volatile.js';
+import { startLimitingFixture } from '../../fixtures/limiting.js';
+import { startCloakingFixture } from '../../fixtures/cloaking.js';
+import { startPageIgnoringFixture, startPinnedFixture, startPageLimitedFixture } from '../../fixtures/paging.js';
+import { search } from '../../fixtures/data.js';
+/**
+ * The first set: one fixture per behaviour the verifier has to tell apart.
+ *
+ * Small on purpose. What is being measured is whether the plumbing can show a
+ * false success at all, not how a large site population behaves.
+ */
+export const VERIFICATION_CASES = [
+    { id: 'honest', start: startSsrFixture, query: 'rust', truth: DATASET_TRUTH },
+    { id: 'ignoring', start: startIgnoringFixture, query: 'rust', truth: DATASET_TRUTH },
+    { id: 'shifted', start: startShiftedFixture, query: 'rust', truth: DATASET_TRUTH },
+    // The one fixture that invents a row, and the only one allowed to.
+    { id: 'volatile', start: startVolatileFixture, query: 'rust',
+        truth: { expected: DATASET_TRUTH.expected, ephemeral: /^\/item\/live-\d+$/ } },
+    { id: 'rate-limited', start: () => startLimitingFixture(429), query: 'rust', truth: DATASET_TRUTH },
+    { id: 'cloaking', start: startCloakingFixture, query: 'rust', truth: DATASET_TRUTH },
+];
+const FIELDS = { title: 'a.title', url: 'a.title@href' };
+/**
+ * Pagination cases, counted apart from the query ones.
+ *
+ * A separate denominator on purpose: these fixtures are built to exercise a
+ * page control and the query ones are not, so pooling them would produce a rate
+ * over a population nobody chose.
+ */
+export const PAGINATION_CASES = [
+    { id: 'paged', start: startSsrFixture, query: 'senior', page: 1,
+        answerInput: { query: 'senior', page: 2 }, truth: PAGE_TRUTH },
+    { id: 'page-ignored', start: () => startPageIgnoringFixture({ browserPaginates: false }), query: 'senior', page: 1,
+        answerInput: { query: 'senior', page: 2 }, truth: PAGE_TRUTH },
+    { id: 'page-stale', start: () => startPageIgnoringFixture({ browserPaginates: true }), query: 'senior', page: 1,
+        answerInput: { query: 'senior', page: 2 }, truth: PAGE_TRUTH },
+    // Eight matches, so page two is genuinely empty and page one is the answer.
+    { id: 'single-page', start: startSsrFixture, query: 'elixir', page: 1,
+        answerInput: { query: 'elixir', page: 1 }, truth: PAGE_TRUTH },
+    // Its pinned row belongs to page one and is declared, not tolerated by a
+    // general rule that would excuse any unrecognised row.
+    { id: 'page-pinned', start: startPinnedFixture, query: 'senior', page: 1,
+        answerInput: { query: 'senior', page: 2 },
+        truth: { expected: (input) => new Set([...pageWindow(input), `/item/${search(String(input.query ?? ''), 1)[0].id}`]) } },
+    { id: 'page-volatile', start: startVolatileFixture, query: 'senior', page: 1,
+        answerInput: { query: 'senior', page: 2 },
+        truth: { expected: pageWindow, ephemeral: /^\/item\/live-\d+$/ } },
+    // Answers page one and declines the rest, so the probe is declined while the
+    // answer being judged is fine.
+    { id: 'page-limited', start: () => startPageLimitedFixture(503, 1), query: 'senior', page: 1,
+        answerInput: { query: 'senior', page: 1 }, truth: PAGE_TRUTH },
+    { id: 'page-cloaking', start: startCloakingFixture, query: 'senior', page: 1,
+        answerInput: { query: 'senior', page: 2 }, truth: PAGE_TRUTH },
+];
+export async function runCase(one, opts = {}) {
+    const fixture = await one.start();
+    try {
+        const planDir = await mkdtemp(join(tmpdir(), 'matrix-plans-'));
+        const recipeDir = await mkdtemp(join(tmpdir(), 'matrix-recipes-'));
+        const site = `case-${one.id}`;
+        const input = one.page === undefined
+            ? { query: one.query }
+            : { query: one.query, page: one.page };
+        const url = one.page === undefined
+            ? `${fixture.url}/search?q=${encodeURIComponent(one.query)}`
+            : `${fixture.url}/search?q=${encodeURIComponent(one.query)}&page=${one.page}`;
+        const taught = await teach({
+            site, intent: 'search',
+            url,
+            input,
+            itemSelector: 'li.result', fields: FIELDS,
+            planDir, recipeDir, minIntervalMs: 0,
+            ...(opts.skipSemanticVerification === true ? { skipSemanticVerification: true } : {}),
+        });
+        const evidence = taught.plan.verification?.evidence ?? {};
+        const checks = {};
+        const reasons = {};
+        for (const name of CheckNameSchema.options) {
+            const entry = evidence[name];
+            if (entry === undefined || name === 'non_empty' || name === 'required_fields')
+                continue;
+            checks[name] = entry.status;
+            if (entry.reason !== undefined)
+                reasons[name] = entry.reason;
+        }
+        // The answer a run would actually return: the recipe, not the recording.
+        const answerInput = one.answerInput ?? input;
+        const items = taught.recipe === null ? null : await answerOf(taught.recipe, site, fixture.url, answerInput);
+        const oracle = items === null
+            ? { match: null, reason: 'no answer to judge' }
+            : judgeByGroundTruth(items, answerInput, one.truth);
+        return {
+            id: one.id,
+            checks,
+            oracleMatch: oracle.match,
+            structuralSuccess: items !== null && structurallySuccessful(items, Object.keys(FIELDS)),
+            ...(oracle.reason === '' ? {} : { oracleReason: oracle.reason }),
+            ...(Object.keys(reasons).length === 0 ? {} : { reasons }),
+        };
+    }
+    finally {
+        await fixture.close();
+    }
+}
+async function answerOf(recipe, site, origin, input) {
+    const net = new PolitenessLayer({ minIntervalMs: 0 });
+    const sites = new StaticSiteResolver({ [site]: origin });
+    const strategy = recipe.output.type === 'json' ? new HttpJsonStrategy(net, sites) : new HttpHtmlStrategy(net, sites);
+    try {
+        const result = await strategy.execute(recipe, { id: 'matrix', site, intent: 'search', input });
+        return result.status !== undefined && result.status !== recipe.validation.status ? null : result.items;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runVerificationCases(cases = VERIFICATION_CASES, opts = {}) {
+    const outcomes = [];
+    // Sequential: each case launches a browser, and running them at once would
+    // measure contention rather than the sites.
+    for (const one of cases)
+        outcomes.push(await runCase(one, opts));
+    return outcomes;
+}

package/dist/src/benchmark/verification-matrix.js

@@ -0,0 +1,97 @@
+/**
+ * What a contract requiring exactly these checks would conclude.
+ *
+ * Scoring a layer means asking this with a shorter list, which is how adding a
+ * check can be read as a change rather than as a new number with no ancestor.
+ */
+export function verdictFrom(outcome, required) {
+    const verdicts = required.map((check) => outcome.checks[check] ?? 'not_tested');
+    if (verdicts.includes('failed'))
+        return 'failed';
+    return verdicts.every((v) => v === 'passed') ? 'passed' : 'not_tested';
+}
+export function tabulate(outcomes, required) {
+    const verdict = (o) => verdictFrom(o, required);
+    const judged = outcomes.filter((o) => o.oracleMatch !== null);
+    const passed = outcomes.filter((o) => verdict(o) === 'passed');
+    const withheld = judged.filter((o) => verdict(o) !== 'passed');
+    return {
+        cases: outcomes.length,
+        judged: judged.length,
+        passed: passed.length,
+        failed: outcomes.filter((o) => verdict(o) === 'failed').length,
+        notTested: outcomes.filter((o) => verdict(o) === 'not_tested').length,
+        oracleCorrect: judged.filter((o) => o.oracleMatch === true).length,
+        oracleWrong: judged.filter((o) => o.oracleMatch === false).length,
+        oracleUnjudged: outcomes.length - judged.length,
+        verifiedCorrect: passed.filter((o) => o.oracleMatch === true).length,
+        falseSuccess: passed.filter((o) => o.oracleMatch === false).length,
+        abstainedCorrect: withheld.filter((o) => o.oracleMatch === true).length,
+        rejectedWrong: withheld.filter((o) => o.oracleMatch === false).length,
+        structuralSuccess: outcomes.filter((o) => o.structuralSuccess).length,
+        structuralFalseSuccess: judged.filter((o) => o.structuralSuccess && o.oracleMatch === false).length,
+    };
+}
+/** Null rather than 0 when the denominator is empty: no cases is not a score of zero. */
+export function ratio(numerator, denominator) {
+    return denominator === 0 ? null : numerator / denominator;
+}
+const pct = (value) => value === null ? 'n/a (no cases)' : `${(value * 100).toFixed(1)}%`;
+/** Every rate prints its own denominator, so no name has to be guessed at. */
+export function formatMatrix(m, label) {
+    return [
+        `${label}:`,
+        `  passed:           ${m.passed}/${m.cases}`,
+        `  failed:           ${m.failed}/${m.cases}`,
+        `  not_tested:       ${m.notTested}/${m.cases}`,
+        `  false success:    ${m.falseSuccess}/${m.judged} oracle-judged cases  (${pct(ratio(m.falseSuccess, m.judged))})`,
+        `  precision:        ${m.verifiedCorrect}/${m.passed} passed cases were correct  (${pct(ratio(m.verifiedCorrect, m.passed))})`,
+        `  correct coverage: ${m.verifiedCorrect}/${m.oracleCorrect} correct answers were verified  (${pct(ratio(m.verifiedCorrect, m.oracleCorrect))})`,
+    ].join('\n');
+}
+/**
+ * One layer per check the contract has gained, so adding a check reads as a
+ * change to two numbers that move in opposite directions: how many wrong
+ * answers stopped being blessed, and how many right ones stopped being
+ * verified.
+ */
+export function formatLayers(outcomes, layers) {
+    const structural = tabulate(outcomes, []);
+    const lines = [];
+    lines.push(`cases: ${structural.cases}${structural.oracleUnjudged > 0 ? ` (${structural.oracleUnjudged} the oracle could not judge)` : ''}`);
+    lines.push('');
+    lines.push('structural-only (non_empty + required_fields):');
+    lines.push(`  called success:   ${structural.structuralSuccess}/${structural.cases}`);
+    lines.push(`  false success:    ${structural.structuralFalseSuccess}/${structural.judged} oracle-judged cases  (${pct(ratio(structural.structuralFalseSuccess, structural.judged))})`);
+    for (const layer of layers) {
+        lines.push('');
+        lines.push(formatMatrix(tabulate(outcomes, layer.required), layer.label));
+    }
+    const last = tabulate(outcomes, layers[layers.length - 1]?.required ?? []);
+    lines.push('');
+    lines.push(`quadrants at "${layers[layers.length - 1]?.label ?? 'structural'}" (oracle-judged cases only):`);
+    lines.push(`  verified_correct:   ${last.verifiedCorrect}`);
+    lines.push(`  false_success:      ${last.falseSuccess}`);
+    lines.push(`  abstained_correct:  ${last.abstainedCorrect}`);
+    lines.push(`  rejected_wrong:     ${last.rejectedWrong}`);
+    lines.push('');
+    lines.push('per case:');
+    const width = Math.max(...outcomes.map((o) => o.id.length));
+    for (const o of outcomes) {
+        const oracle = o.oracleMatch === null ? 'unjudged' : o.oracleMatch ? 'correct' : 'wrong';
+        const verdicts = layers.map((l) => `${l.label}=${verdictFrom(o, l.required)}`).join('  ');
+        const flag = verdictFrom(o, layers[layers.length - 1]?.required ?? []) === 'passed' && o.oracleMatch === false
+            ? '  <- FALSE SUCCESS' : '';
+        lines.push(`  ${o.id.padEnd(width)}  oracle=${oracle.padEnd(8)} ${verdicts}${flag}`);
+    }
+    return lines.join('\n');
+}
+/** The structural bar, kept here so the baseline cannot drift from what it claims to be. */
+export function structurallySuccessful(items, fields) {
+    if (items.length === 0)
+        return false;
+    return !fields.some((field) => items.some((item) => {
+        const value = item[field];
+        return value === null || value === undefined || value === '';
+    }));
+}

package/dist/src/browser/navigate.js

@@ -0,0 +1,22 @@
+const NAVIGATION_TIMEOUT_MS = 30_000;
+const SELECTOR_TIMEOUT_MS = 10_000;
+/** After the items appear, give late XHR a moment to land before reading. */
+export const SETTLE_MS = 800;
+/**
+ * Loads a page and waits for its items, without requiring the network to fall
+ * silent.
+ *
+ * `networkidle` never arrives on a site that polls or streams analytics —
+ * arbeitnow.com simply timed out — and waiting for silence is the wrong
+ * condition anyway. What matters is that the items are present. The wait is for
+ * the selector, with a short settle for anything still in flight, and a
+ * network-idle attempt only as a best effort that is allowed to fail.
+ */
+export async function navigateAndSettle(page, url, itemSelector) {
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: NAVIGATION_TIMEOUT_MS });
+    await page
+        .waitForSelector(itemSelector, { timeout: SELECTOR_TIMEOUT_MS })
+        .catch(() => undefined);
+    await page.waitForLoadState('networkidle', { timeout: SETTLE_MS }).catch(() => undefined);
+    await page.waitForTimeout(SETTLE_MS);
+}

package/dist/src/browser/pool.js

@@ -0,0 +1,31 @@
+import { costSink } from '../measurement.js';
+import { chromium } from 'playwright';
+import { BROWSER_USER_AGENT, observePage } from './session.js';
+/**
+ * One browser process reused across tasks.
+ *
+ * A cold launch costs about 800ms, which on a light page is most of what a
+ * browser run costs at all. Keeping the process alive separates "this task
+ * needed a browser" from "this task paid to start one", which is the
+ * difference between avoiding a full browser and being browser-free.
+ *
+ * Each task still gets a fresh context, so cookies and storage cannot leak
+ * from one task into the next and make a recipe look better than it is.
+ */
+export class BrowserPool {
+    browser = null;
+    async acquire() {
+        const launched = this.browser === null;
+        this.browser ??= await chromium.launch({ headless: true });
+        if (launched)
+            costSink()({ browserLaunches: 1 });
+        const context = await this.browser.newContext({ userAgent: BROWSER_USER_AGENT });
+        const page = await context.newPage();
+        const { cost, drain } = observePage(page);
+        return { page, cost, launched, release: async () => { await context.close(); await drain(); } };
+    }
+    async close() {
+        await this.browser?.close();
+        this.browser = null;
+    }
+}

package/dist/src/browser/session.js

@@ -0,0 +1,44 @@
+import { costSink } from '../measurement.js';
+import { chromium } from 'playwright';
+export const BROWSER_USER_AGENT = 'webrecipe/0.1 (+https://github.com/Pillsoon/webrecipe)';
+/**
+ * A cold browser with instrumentation attached. Nothing is blocked or cached —
+ * this is the baseline the whole project is measured against, so it has to pay
+ * the real cost.
+ */
+export async function openSession() {
+    const browser = await chromium.launch({ headless: true });
+    costSink()({ browserLaunches: 1 });
+    const context = await browser.newContext({ userAgent: BROWSER_USER_AGENT });
+    const page = await context.newPage();
+    const { cost, drain } = observePage(page);
+    return { page, cost, close: async () => { await browser.close(); await drain(); } };
+}
+/** Count all content types; drain settled body reads after the page closes. */
+export function observePage(page) {
+    const cost = { pageNavigations: 0, networkRequests: 0, bytesDownloaded: 0, unreadResponseBodies: 0 };
+    const charge = costSink();
+    const pending = new Set();
+    page.on('request', () => { cost.networkRequests += 1; charge({ networkRequests: 1 }); });
+    page.on('framenavigated', (frame) => {
+        if (frame === page.mainFrame()) {
+            cost.pageNavigations += 1;
+            charge({ pageNavigations: 1 });
+        }
+    });
+    page.on('response', (response) => {
+        // These responses have no HTTP body; Playwright may reject body() for them.
+        if (response.request().method() === 'HEAD' || [204, 205, 304].includes(response.status()))
+            return;
+        const read = response.body().then((buf) => {
+            cost.bytesDownloaded += buf.byteLength;
+            charge({ bytesDownloaded: buf.byteLength });
+        }).catch(() => {
+            cost.unreadResponseBodies += 1;
+            charge({ unreadResponseBodies: 1 });
+        });
+        pending.add(read);
+        void read.finally(() => pending.delete(read));
+    });
+    return { cost, drain: async () => { await Promise.all(pending); } };
+}