webrecipe 0.1.0

package/dist/src/compiler/verify.js

@@ -0,0 +1,29 @@
+import { extractBySelector } from '../executor/extract.js';
+import { diffGolden } from '../benchmark/golden.js';
+/**
+ * Checks a candidate recipe's output against what the browser actually
+ * extracted from the same visit. This is the golden diff moved to compile
+ * time: without it a recipe can point at a plausible-looking endpoint that
+ * carries different data — a crate's owners rather than the crate, an
+ * article's own URL rather than the discussion link — and nothing notices
+ * until the numbers are already wrong.
+ */
+/** What the browser extracted from this visit, using the plan's own selectors. */
+export function browserItemsOf(trace, plan) {
+    return extractBySelector(trace.finalHtml, plan.itemSelector, plan.fields);
+}
+export function verifyAgainstBrowser(trace, plan, recipeItems) {
+    const browserItems = browserItemsOf(trace, plan);
+    if (browserItems.length === 0) {
+        return { equivalent: false, reasons: ['browser extracted nothing to compare against'] };
+    }
+    // Two extractions that both found nothing agree vacuously. If the browser
+    // side carries no values, the plan's selectors are wrong and there is no
+    // behaviour to reproduce.
+    const populated = browserItems.some((item) => Object.values(item).some((v) => v !== null && v !== undefined && v !== ''));
+    if (!populated) {
+        return { equivalent: false, reasons: ['browser extracted items with no field values; check the plan selectors'] };
+    }
+    const diff = diffGolden({ taskId: 'compile-check', capturedAt: new Date().toISOString(), items: browserItems }, recipeItems);
+    return { equivalent: diff.match, reasons: diff.reasons };
+}

package/dist/src/executor/extract.js

@@ -0,0 +1,179 @@
+import * as cheerio from 'cheerio';
+import { resolvePath } from '../recipes/paths.js';
+import { renderRowTemplate } from '../compiler/derive.js';
+/** Strings are trimmed: browser extraction trims, and the two must agree. */
+function coerce(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string')
+        return value.trim();
+    if (typeof value === 'number')
+        return value;
+    return String(value).trim();
+}
+/** A path that resolves to one object yields a single item; an array yields many. */
+export function extractJsonItems(recipe, payload) {
+    if (recipe.output.type !== 'json')
+        throw new Error('extractJsonItems requires a json recipe');
+    const located = resolvePath(payload, recipe.output.items.path);
+    if (located === undefined || located === null)
+        return [];
+    const rows = Array.isArray(located) ? located : [located];
+    const fields = Object.entries(recipe.output.items.fields);
+    // A spec starting with `$` reads a value; anything else composes one from the
+    // row, reproducing a derivation the page performs on top of its API.
+    return rows.map((row) => Object.fromEntries(fields.map(([name, spec]) => [
+        name,
+        spec.startsWith('$')
+            ? coerce(resolvePath(row, spec))
+            : renderRowTemplate(spec, row).trim(),
+    ])));
+}
+export function extractHtmlItems(recipe, html) {
+    if (recipe.output.type !== 'html')
+        throw new Error('extractHtmlItems requires an html recipe');
+    return extractBySelector(html, recipe.output.items.selector, recipe.output.items.fields);
+}
+/**
+ * The structural signature of an HTML response: which of the recipe's declared
+ * fields actually resolved. Fingerprinting the raw HTML would change on every
+ * content edit; fingerprinting the recipe's own selectors would never change at
+ * all. What matters is whether the selectors still find anything.
+ */
+export function htmlSignature(recipe, items) {
+    if (recipe.output.type !== 'html')
+        throw new Error('htmlSignature requires an html recipe');
+    const first = items[0];
+    const fields = first === undefined
+        ? []
+        : Object.keys(first).filter((name) => first[name] !== null && first[name] !== '').sort();
+    return { selector: recipe.output.items.selector, fields };
+}
+/**
+ * The structural signature of a JSON response, limited to what the recipe
+ * actually reads. Hashing every path in the payload treats content-driven
+ * variation as schema drift — Algolia's per-hit _highlightResult carries
+ * different keys for different queries — so a recipe would be judged broken
+ * every time the search term changed.
+ */
+export function jsonSignature(recipe, payload) {
+    const located = resolvePath(payload, recipe.output.items.path);
+    const rows = Array.isArray(located) ? located : located === undefined || located === null ? [] : [located];
+    const sample = rows[0];
+    const fields = sample === undefined
+        ? []
+        : Object.entries(recipe.output.items.fields)
+            .filter(([, spec]) => (spec.startsWith('$') ? resolvePath(sample, spec) !== undefined : true))
+            .map(([name]) => name)
+            .sort();
+    return { itemsPath: located === undefined || located === null ? '(missing)' : recipe.output.items.path, fields };
+}
+/** Elements HTML parsing only accepts inside a particular parent. */
+const FRAGMENT_WRAPPERS = [
+    [/^<tr[\s>]/i, (h) => `<table><tbody>${h}</tbody></table>`],
+    [/^<(td|th)[\s>]/i, (h) => `<table><tbody><tr>${h}</tr></tbody></table>`],
+    [/^<(li)[\s>]/i, (h) => `<ul>${h}</ul>`],
+    [/^<(option)[\s>]/i, (h) => `<select>${h}</select>`],
+    [/^<(dt|dd)[\s>]/i, (h) => `<dl>${h}</dl>`],
+];
+/**
+ * Parses HTML that may be a fragment rather than a document.
+ *
+ * A response can be a bare run of `<tr>` elements, which an XHR splices into an
+ * existing table — remoteok.com answers a search that way. Parsing that as a
+ * document silently discards every row, because a table row outside a table is
+ * invalid HTML, and the result is an empty extraction with no error to explain
+ * it. Supplying the missing parent keeps the rows.
+ */
+export function parseHtmlFragment(html) {
+    const head = html.replace(/^\s*(?:<!--[\s\S]*?-->\s*)*/, '');
+    const wrapper = FRAGMENT_WRAPPERS.find(([pattern]) => pattern.test(head));
+    return cheerio.load(wrapper ? wrapper[1](head) : html);
+}
+/** One interpretation of a field spec, shared by cheerio and the browser. */
+export function planFields(fields) {
+    return Object.entries(fields).map(([name, spec]) => {
+        if (spec === '')
+            return { name, mode: 'own-text' };
+        if (spec.startsWith('@'))
+            return { name, mode: 'own-attr', attribute: spec.slice(1) };
+        const suffix = attributeSuffix(spec);
+        return suffix
+            ? { name, mode: 'find-attr', selector: suffix.selector, attribute: suffix.attribute }
+            : { name, mode: 'find-text', selector: spec };
+    });
+}
+/**
+ * Splits `selector@attr`, tolerating an `@` inside the selector itself — jsr.io
+ * links start with `/@`, so `a[href^="/@"]@href` must split on the trailing
+ * suffix and not on the first one it finds. The suffix only counts outside
+ * brackets and quotes.
+ */
+function attributeSuffix(spec) {
+    const match = /@([a-zA-Z][\w-]*)$/.exec(spec);
+    if (!match)
+        return null;
+    const selector = spec.slice(0, match.index);
+    let depth = 0;
+    let quote = null;
+    for (const ch of selector) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === '[')
+            depth += 1;
+        else if (ch === ']')
+            depth -= 1;
+    }
+    // An unbalanced selector means the @ we matched belongs inside it.
+    if (depth !== 0 || quote !== null || selector === '')
+        return null;
+    return { selector, attribute: match[1] };
+}
+/**
+ * Extracts items from HTML with a bare selector and field map, independent of a
+ * recipe. Used to reconstruct what the browser saw so a candidate recipe can be
+ * checked against it.
+ */
+export function extractBySelector(html, selector, fields) {
+    const $ = parseHtmlFragment(html);
+    const plans = planFields(fields);
+    return $(selector).toArray().map((element) => {
+        const item = $(element);
+        const row = {};
+        // Field candidates ask for `a`, `a@href` and `a@id` of the same item; one find serves all three.
+        const found = new Map();
+        const find = (sel) => {
+            let f = found.get(sel);
+            if (f === undefined) {
+                f = item.find(sel);
+                found.set(sel, f);
+            }
+            return f;
+        };
+        for (const f of plans) {
+            switch (f.mode) {
+                case 'own-text':
+                    row[f.name] = item.text().trim();
+                    break;
+                case 'own-attr':
+                    row[f.name] = item.attr(f.attribute) ?? null;
+                    break;
+                case 'find-attr':
+                    row[f.name] = find(f.selector).attr(f.attribute) ?? null;
+                    break;
+                default: {
+                    const matches = find(f.selector);
+                    row[f.name] = matches.length === 0 ? null : matches.first().text().trim();
+                }
+            }
+        }
+        return row;
+    });
+}

package/dist/src/executor/format.js

@@ -0,0 +1,55 @@
+const ORIGIN = /^https?:\/\/[^/]+/;
+/** The `https?://host` every item's url starts with, or undefined if they do not share one. */
+function sharedOrigin(items) {
+    if (items.length === 0)
+        return undefined;
+    let origin;
+    for (const item of items) {
+        const url = item.url;
+        if (typeof url !== 'string')
+            return undefined;
+        const match = ORIGIN.exec(url);
+        if (match === null)
+            return undefined;
+        if (origin === undefined)
+            origin = match[0];
+        else if (origin !== match[0])
+            return undefined;
+    }
+    return origin;
+}
+// A tab, newline or carriage return inside a value becomes a space, so a title
+// cannot break the table. That is the whole escaping story: no quoting.
+function cell(value) {
+    if (value === null || value === undefined)
+        return '';
+    return String(value).replace(/[\t\n\r]/g, ' ');
+}
+/**
+ * Serialises items for an agent to read. `tsv` is a header line plus one line
+ * per item, preceded by a `base` line carrying the origin every url shares.
+ */
+export function formatItems(items, format) {
+    if (format === 'json')
+        return JSON.stringify(items);
+    const columns = [];
+    for (const item of items) {
+        for (const key of Object.keys(item))
+            if (!columns.includes(key))
+                columns.push(key);
+    }
+    const origin = sharedOrigin(items);
+    const lines = origin === undefined ? [] : [`base\t${origin}`];
+    lines.push(columns.join('\t'));
+    for (const item of items) {
+        lines.push(columns
+            .map((key) => {
+            const value = item[key];
+            return key === 'url' && origin !== undefined && typeof value === 'string'
+                ? cell(value.slice(origin.length))
+                : cell(value);
+        })
+            .join('\t'));
+    }
+    return lines.join('\n');
+}

package/dist/src/executor/index.js

@@ -0,0 +1,147 @@
+import { measureResult } from '../measurement.js';
+import { validate } from '../validator/index.js';
+import { addMeta } from '../types.js';
+/** How long a site stays off the recipe path after it refused one. */
+export const BLOCK_COOLDOWN_MS = 10 * 60_000;
+/** Statuses a site uses to say no: auth wall, forbidden, rate limit, shed load. */
+const BLOCK_STATUSES = new Set([401, 403, 429, 503]);
+/** Replaced in place once the healer reports why the compiler refused. */
+const NO_RECIPE = 'no recipe registered';
+/** Only a json signature reports whether the recipe's items path still resolved. */
+function keptRecordedShape(recipe, payload) {
+    // An html recipe has no items path to test, so its challenge pages are caught
+    // only because this returns false; narrowing this line away kills rule (b) for
+    // every html site, with nothing but the siteRefusing test to notice.
+    if (recipe.output.type !== 'json')
+        return false;
+    return payload?.itemsPath === recipe.output.items.path;
+}
+export class Executor {
+    opts;
+    /** Site -> the time until which it is treated as refusing us. */
+    blockedUntil = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    strategy(name) {
+        const found = this.opts.strategies.find((s) => s.name === name);
+        if (!found)
+            throw new Error(`no strategy registered for "${name}"`);
+        return found;
+    }
+    /**
+     * Descends the browser levels rather than jumping to the bottom. A warm pool
+     * still needs a browser but does not pay to start one, and hardcoding the
+     * cold browser here made that distinction unobservable: the level split
+     * reported L2 at zero because nothing could ever reach it.
+     */
+    async fallback(recipe, task, reasons) {
+        const ladder = this.opts.strategies.filter((s) => s.name === 'warm-browser' || s.name === 'browser');
+        ladder.sort((a, b) => (a.name === 'warm-browser' ? -1 : 1) - (b.name === 'warm-browser' ? -1 : 1));
+        let lastError = new Error('no browser strategy registered');
+        for (const strategy of ladder) {
+            try {
+                const result = await strategy.execute(recipe ?? {}, task);
+                return { ...result, recipeUsed: false, fellBack: true, reasons };
+            }
+            catch (err) {
+                lastError = err;
+                reasons.push(err instanceof Error ? err.message : String(err));
+            }
+        }
+        throw lastError;
+    }
+    async run(task) {
+        return measureResult('browser', () => this.runTask(task));
+    }
+    async runTask(task) {
+        const now = this.opts.now ?? Date.now;
+        const recipe = await this.opts.registry.load(task.site, task.intent);
+        const reasons = [];
+        const cooldown = this.blockedUntil.get(task.site);
+        if (cooldown !== undefined && cooldown > now()) {
+            reasons.push(`blocked: cooling down for ${task.site}`);
+            const cooling = await this.fallback(recipe, task, reasons);
+            return { ...cooling, blocked: true, reasons: [...reasons] };
+        }
+        let attempt = null;
+        /** What was spent before the answer arrived, kept so the total can include it. */
+        const spent = [];
+        if (recipe && recipe.strategy.type !== 'browser') {
+            try {
+                const result = await this.strategy(recipe.strategy.type).execute(recipe, task);
+                const outcome = validate(recipe, {
+                    status: result.status ?? recipe.validation.status,
+                    payload: result.payload,
+                    items: result.items,
+                });
+                if (outcome.valid) {
+                    return { ...result, recipeUsed: true, fellBack: false, blocked: false, reasons: [] };
+                }
+                reasons.push(...outcome.reasons);
+                spent.push(result.meta);
+                // The raw status, never the expected one standing in for it: reading a
+                // missing status as the expected one would make every browser result a
+                // 200 that carried nothing, which is half of rule (b).
+                if (result.status !== undefined) {
+                    attempt = {
+                        status: result.status,
+                        items: result.items,
+                        recordedShape: keptRecordedShape(recipe, result.payload),
+                    };
+                }
+            }
+            catch (err) {
+                reasons.push(err instanceof Error ? err.message : String(err));
+            }
+        }
+        else if (!recipe) {
+            reasons.push(NO_RECIPE);
+        }
+        // (a) is settled before the browser runs. A site that answered 403 has
+        // earned the cooldown whatever the browser then does, and deciding it after
+        // would lose the entry whenever the fallback throws.
+        let blocked = false;
+        if (attempt && BLOCK_STATUSES.has(attempt.status)) {
+            reasons.push(`blocked: status ${attempt.status}`);
+            this.blockedUntil.set(task.site, now() + BLOCK_COOLDOWN_MS);
+            blocked = true;
+        }
+        const fellBack = await this.fallback(recipe, task, reasons);
+        // (b) cannot be settled any earlier: a 200 that carried nothing is only a
+        // challenge page if the browser beside it could not read the page either.
+        // Drift the browser can still read is a rotted recipe, and heals.
+        // An empty result and a challenge page both carry no items; only the empty
+        // result still has the response shape the recipe recorded.
+        if (!blocked && attempt?.status === 200 && attempt.items.length === 0
+            && !attempt.recordedShape && fellBack.items.length === 0) {
+            reasons.push('blocked: 200 with no items, browser also empty');
+            this.blockedUntil.set(task.site, now() + BLOCK_COOLDOWN_MS);
+            blocked = true;
+        }
+        // (c) costs this one task a re-record, and has to: comparing the recipe the
+        // browser yields now against the stored one is the measurement, and there
+        // is no way to learn it changed nothing without performing it once.
+        if (!blocked) {
+            const healResult = await this.opts.onFallback?.({ task, recipe, reasons });
+            if (healResult?.meta)
+                spent.push(healResult.meta);
+            // On the run that learned it, not a later one: a benchmark task runs
+            // once, so a reason held back for next time is a reason nothing reports.
+            if (healResult?.refused !== undefined) {
+                const bare = reasons.indexOf(NO_RECIPE);
+                const line = `no recipe: ${healResult.refused}`;
+                if (bare === -1)
+                    reasons.push(line);
+                else
+                    reasons[bare] = line;
+            }
+            if (healResult && healResult.unchanged) {
+                reasons.push('blocked: re-record produced the same recipe — the site serves the engine a different page');
+                this.blockedUntil.set(task.site, now() + BLOCK_COOLDOWN_MS);
+                blocked = true;
+            }
+        }
+        return { ...fellBack, meta: addMeta(fellBack.meta, ...spent), blocked, reasons: [...reasons] };
+    }
+}

package/dist/src/executor/strategies/browser.js

@@ -0,0 +1,60 @@
+import { measureResult } from '../../measurement.js';
+import { openSession } from '../../browser/session.js';
+import { navigateAndSettle } from '../../browser/navigate.js';
+import { planFields } from '../extract.js';
+import { countTokens } from '../tokens.js';
+import { emptyMeta } from '../../types.js';
+export const BROWSER_PLANS = {};
+export class BrowserStrategy {
+    sites;
+    plans;
+    countAgentTokens;
+    name = 'browser';
+    constructor(sites, plans = BROWSER_PLANS, 
+    /** The token count costs a page read of its own; a timing benchmark can decline to pay it. */
+    countAgentTokens = true) {
+        this.sites = sites;
+        this.plans = plans;
+        this.countAgentTokens = countAgentTokens;
+    }
+    async execute(recipe, task) {
+        return measureResult(this.name, () => this.executeAttempt(recipe, task));
+    }
+    async executeAttempt(_recipe, task) {
+        const plan = this.plans[task.site]?.[task.intent];
+        if (!plan)
+            throw new Error(`no browser plan for ${task.site}/${task.intent}`);
+        const meta = emptyMeta(this.name);
+        const started = performance.now();
+        const session = await openSession();
+        meta.browserLaunches = 1;
+        try {
+            await navigateAndSettle(session.page, plan.url(this.sites.origin(task.site), task), plan.itemSelector);
+            // The field specs are interpreted once, in node, so that the browser and
+            // cheerio cannot drift apart on what a spec means.
+            const items = (await session.page.$$eval(plan.itemSelector, (elements, plans) => elements.map((el) => Object.fromEntries(plans.map((f) => {
+                switch (f.mode) {
+                    case 'own-text': return [f.name, el.textContent?.trim() ?? null];
+                    case 'own-attr': return [f.name, el.getAttribute(f.attribute)];
+                    case 'find-attr': return [f.name, el.querySelector(f.selector)?.getAttribute(f.attribute) ?? null];
+                    default: return [f.name, el.querySelector(f.selector)?.textContent?.trim() ?? null];
+                }
+            }))), planFields(plan.fields)));
+            meta.pageNavigations = session.cost.pageNavigations;
+            meta.networkRequests = session.cost.networkRequests;
+            meta.bytesDownloaded = session.cost.bytesDownloaded;
+            meta.latencyMs = Math.round(performance.now() - started);
+            // After the latency line: taking the snapshot and tokenising it both take
+            // real time, and charging that to the baseline would flatter the engine.
+            // The read is allowed to fail — a late client-side navigation destroys
+            // the execution context — because instrumentation must never turn a
+            // graded run into a thrown one.
+            const snapshot = this.countAgentTokens ? await session.page.locator('body').ariaSnapshot().catch(() => '') : '';
+            meta.llmTokens = countTokens(snapshot);
+            return { items, meta };
+        }
+        finally {
+            await session.close();
+        }
+    }
+}

package/dist/src/executor/strategies/http-html.js

@@ -0,0 +1,42 @@
+import { measureResult } from '../../measurement.js';
+import { render } from '../../recipes/template.js';
+import { buildUrl } from './http-json.js';
+import { extractHtmlItems, htmlSignature } from '../extract.js';
+import { countTokens } from '../tokens.js';
+import { formatItems } from '../format.js';
+import { emptyMeta } from '../../types.js';
+export class HttpHtmlStrategy {
+    net;
+    sites;
+    name = 'http-html';
+    constructor(net, sites) {
+        this.net = net;
+        this.sites = sites;
+    }
+    async execute(recipe, task) {
+        return measureResult(this.name, () => this.executeAttempt(recipe, task));
+    }
+    async executeAttempt(recipe, task) {
+        const meta = emptyMeta(this.name);
+        const started = performance.now();
+        const url = buildUrl(this.sites.origin(task.site), recipe, task);
+        const res = await this.net.fetch(url, {
+            method: recipe.request.method,
+            headers: recipe.request.headers,
+            body: recipe.request.body ? render(recipe.request.body, task.input) : undefined,
+        });
+        meta.networkRequests = 1;
+        meta.bytesDownloaded = res.bytesDownloaded;
+        meta.politenessWaitMs = res.waitedMs;
+        meta.latencyMs = Math.max(0, Math.round(performance.now() - started) - res.waitedMs);
+        // Reported, not thrown. A status that becomes an error message is invisible
+        // to the validator that has to judge it and to the executor that has to tell
+        // a site refusing us from a recipe that rotted.
+        if (res.status !== recipe.validation.status) {
+            return { items: [], meta, status: res.status, payload: undefined };
+        }
+        const items = extractHtmlItems(recipe, res.body);
+        meta.llmTokens = countTokens(formatItems(items, 'tsv'));
+        return { items, meta, payload: htmlSignature(recipe, items), status: res.status };
+    }
+}

package/dist/src/executor/strategies/http-json.js

@@ -0,0 +1,71 @@
+import { measureResult } from '../../measurement.js';
+import { render, renderPath, renderQuery } from '../../recipes/template.js';
+import { extractJsonItems, jsonSignature } from '../extract.js';
+import { countTokens } from '../tokens.js';
+import { formatItems } from '../format.js';
+import { emptyMeta } from '../../types.js';
+export function buildUrl(siteOrigin, recipe, task) {
+    const origin = new URL(recipe.request.origin ?? siteOrigin).origin;
+    const url = new URL(renderPath(recipe.request.path, task.input), origin);
+    // An input value must not be able to redirect a request the recipe did not
+    // describe: a rendered path beginning `//`, such as a `detail` input of
+    // `/evil.example/x` against a path of `/{{id}}`, is protocol-relative and
+    // `new URL` resolves it against that host instead of `origin`.
+    if (url.origin !== origin)
+        throw new Error(`recipe would request ${url.origin}, outside ${origin}`);
+    for (const [k, v] of Object.entries(renderQuery(recipe.request.query ?? {}, task.input))) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+export class HttpJsonStrategy {
+    net;
+    sites;
+    name = 'http-json';
+    constructor(net, sites) {
+        this.net = net;
+        this.sites = sites;
+    }
+    async execute(recipe, task) {
+        return measureResult(this.name, () => this.executeAttempt(recipe, task));
+    }
+    async executeAttempt(recipe, task) {
+        const meta = emptyMeta(this.name);
+        const started = performance.now();
+        const url = buildUrl(this.sites.origin(task.site), recipe, task);
+        const res = await this.net.fetch(url, {
+            method: recipe.request.method,
+            headers: recipe.request.headers,
+            body: recipe.request.body ? render(recipe.request.body, task.input) : undefined,
+        });
+        meta.networkRequests = 1;
+        meta.bytesDownloaded = res.bytesDownloaded;
+        meta.politenessWaitMs = res.waitedMs;
+        meta.latencyMs = Math.max(0, Math.round(performance.now() - started) - res.waitedMs);
+        // Reported, not thrown. A status that becomes an error message is invisible
+        // to the validator that has to judge it and to the executor that has to tell
+        // a site refusing us from a recipe that rotted.
+        if (res.status !== recipe.validation.status) {
+            return { items: [], meta, status: res.status, payload: undefined };
+        }
+        let payload;
+        try {
+            payload = JSON.parse(res.body);
+        }
+        catch {
+            // A challenge page answers 200 with HTML where the API used to be; that is
+            // a site response like any other and is reported the same way.
+            return { items: [], meta, status: res.status, payload: undefined };
+        }
+        if (recipe.output.type !== 'json')
+            throw new Error('http-json requires a json recipe');
+        const items = extractJsonItems(recipe, payload);
+        meta.llmTokens = countTokens(formatItems(items, 'tsv'));
+        return {
+            items,
+            meta,
+            payload: jsonSignature({ output: recipe.output }, payload),
+            status: res.status,
+        };
+    }
+}

package/dist/src/executor/strategies/warm-browser.js

@@ -0,0 +1,57 @@
+import { measureResult } from '../../measurement.js';
+import { BrowserPool } from '../../browser/pool.js';
+import { navigateAndSettle } from '../../browser/navigate.js';
+import { planFields } from '../extract.js';
+import { countTokens } from '../tokens.js';
+import { BROWSER_PLANS } from './browser.js';
+import { emptyMeta } from '../../types.js';
+/** A browser run that does not pay to start a browser. */
+export class WarmBrowserStrategy {
+    sites;
+    plans;
+    name = 'warm-browser';
+    pool = new BrowserPool();
+    constructor(sites, plans = BROWSER_PLANS) {
+        this.sites = sites;
+        this.plans = plans;
+    }
+    async execute(recipe, task) {
+        return measureResult(this.name, () => this.executeAttempt(recipe, task));
+    }
+    async executeAttempt(_recipe, task) {
+        const plan = this.plans[task.site]?.[task.intent];
+        if (!plan)
+            throw new Error(`no browser plan for ${task.site}/${task.intent}`);
+        const meta = emptyMeta(this.name);
+        const started = performance.now();
+        const warm = await this.pool.acquire();
+        try {
+            await navigateAndSettle(warm.page, plan.url(this.sites.origin(task.site), task), plan.itemSelector);
+            const items = (await warm.page.$$eval(plan.itemSelector, (elements, plans) => elements.map((el) => Object.fromEntries(plans.map((f) => {
+                switch (f.mode) {
+                    case 'own-text': return [f.name, el.textContent?.trim() ?? null];
+                    case 'own-attr': return [f.name, el.getAttribute(f.attribute)];
+                    case 'find-attr': return [f.name, el.querySelector(f.selector)?.getAttribute(f.attribute) ?? null];
+                    default: return [f.name, el.querySelector(f.selector)?.textContent?.trim() ?? null];
+                }
+            }))), planFields(plan.fields)));
+            // Zero only when the pool already had a browser. The first call starts
+            // Chromium like any cold run does, and reporting none said otherwise.
+            meta.browserLaunches = warm.launched ? 1 : 0;
+            meta.pageNavigations = warm.cost.pageNavigations;
+            meta.networkRequests = warm.cost.networkRequests;
+            meta.bytesDownloaded = warm.cost.bytesDownloaded;
+            meta.latencyMs = Math.round(performance.now() - started);
+            // After the latency line, and allowed to fail, for the reasons in browser.ts.
+            const snapshot = await warm.page.locator('body').ariaSnapshot().catch(() => '');
+            meta.llmTokens = countTokens(snapshot);
+            return { items, meta };
+        }
+        finally {
+            await warm.release();
+        }
+    }
+    async close() {
+        await this.pool.close();
+    }
+}

package/dist/src/executor/tokens.js

@@ -0,0 +1,11 @@
+import { Tiktoken } from 'js-tiktoken';
+import cl100k_base from 'js-tiktoken/ranks/cl100k_base';
+// The rank table is a static import and loads with this module; what is
+// deferred is turning it into the encoder's lookup maps, which is the
+// expensive half and is done once, on first use.
+let encoder;
+/** Tokens an agent would spend reading `text`, under cl100k_base. */
+export function countTokens(text) {
+    encoder ??= new Tiktoken(cl100k_base);
+    return encoder.encode(text).length;
+}