@opencraw/core 0.1.1 → 0.1.3

package/dist/index.esm.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { randomInt, randomUUID } from 'node:crypto';
-import { readFile, mkdir, writeFile, stat, readdir } from 'node:fs/promises';
-import { resolve as resolve$1, dirname, extname, join as join$1 } from 'node:path';
+import { readFile, mkdir, writeFile, rm, stat, readdir } from 'node:fs/promises';
+import { resolve as resolve$1, join as join$1, dirname, extname } from 'node:path';
 import { firefox, webkit, chromium, request } from 'playwright';
 import { createWriteStream } from 'node:fs';
 import { once } from 'node:events';
@@ -67,10 +67,20 @@ const pluginSchema = z.strictObject({
   options: z.record(z.string(), z.unknown()).optional()
 });
 const accessProfileSchema = z.union([directSchema, proxySchema, poolSchema, cdpSchema, pluginSchema]);
+const hostRuleSchema = z.strictObject({
+  delayMs: z.int().nonnegative().optional(),
+  concurrency: z.int().min(1).max(256).optional()
+});
+const throttleConfigSchema = z.strictObject({
+  delayMs: z.int().nonnegative().optional(),
+  concurrency: z.int().min(1).max(256).optional(),
+  domains: z.record(z.string().regex(/^[\w.-]+$/, 'a domain such as example.com'), hostRuleSchema).optional()
+});
 const accessConfigSchema = z.strictObject({
   $schema: z.string().optional(),
   profiles: z.record(z.string().regex(/^[\w-]+$/, 'a profile name is letters, digits, hyphens and underscores'), accessProfileSchema),
-  default: z.string().optional()
+  default: z.string().optional(),
+  throttle: throttleConfigSchema.optional()
 }).refine(config => config.default === undefined || Object.hasOwn(config.profiles, config.default), {
   message: 'default names a profile that does not exist',
   path: ['default']
@@ -1179,6 +1189,17 @@ async function blockResources(context, types) {
     await route.continue();
   });
 }
+/**
+ * What a context gets after it opened: the cookies to add and the resource
+ * types to skip.
+ *
+ * @param context - The context.
+ * @param options - The session options.
+ */
+async function applySessionExtras(context, options) {
+  if (options.cookies !== undefined && options.cookies.length > 0) await context.addCookies(options.cookies);
+  if (options.blockResources !== undefined && options.blockResources.length > 0) await blockResources(context, new Set(options.blockResources));
+}
 /** A launched browser; sessions are opened from it and closed independently. */
 class BrowserClient {
   browser;
@@ -1238,8 +1259,7 @@ class BrowserClient {
     };
     const context = await this.browser.newContext(contextOptions);
     if (this.config.timeoutMs !== undefined) context.setDefaultTimeout(this.config.timeoutMs);
-    if (options.cookies !== undefined && options.cookies.length > 0) await context.addCookies(options.cookies);
-    if (options.blockResources !== undefined && options.blockResources.length > 0) await blockResources(context, new Set(options.blockResources));
+    await applySessionExtras(context, options);
     const page = await context.newPage();
     return new BrowserSession(context, page);
   }
@@ -1248,470 +1268,252 @@ class BrowserClient {
   }
 }
 
-/** Fans crawl events out to listeners. A listener that throws never breaks the crawl. */
-class EventBus {
-  listeners = new Set();
-  constructor(listener) {
-    if (listener !== undefined) this.listeners.add(listener);
+/** The file that marks a profile as in use, holding the owning process id. */
+const LOCK_FILE = '.opencraw.lock';
+/** A browser profile name: it becomes a directory, so no separators or dots. */
+const BROWSER_PROFILE_NAME = /^[\w-]+$/;
+/**
+ * Browser profiles that persist between runs: each is a directory of a real
+ * browser's user data (cookies, local storage, IndexedDB, cache, service
+ * workers), so a login, a consent choice or a site's trust in a returning
+ * visitor carries over to the next run. The browser equivalent of a user who
+ * never clears their history.
+ *
+ * A profile directory can be open in one browser at a time. Within this
+ * crawler, a second use waits for the first to close; the same owner (one
+ * recipe run reopening after a rotation) takes it over instead. Another
+ * crawler holding it, in this process or another, is reported, not waited
+ * for: a lock file in the profile names the process, and one left by a
+ * process that died is taken over. (Chromium's own profile lock is not
+ * enough: headless builds do not take it.)
+ */
+class BrowserProfiles {
+  directory;
+  config;
+  held = new Map();
+  waiting = new Map();
+  /**
+   * @param directory - Where the profiles live, one subdirectory each.
+   * @param config - The crawler's browser settings (type, binary, headless, timeouts).
+   */
+  constructor(directory, config = {}) {
+    this.directory = directory;
+    this.config = config;
   }
-  /** @returns A function that removes the listener. */
-  subscribe(listener) {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
+  async take(name, owner) {
+    for (;;) {
+      const holder = this.held.get(name);
+      if (holder === undefined) return;
+      if (holder.owner === owner) {
+        await holder.session.close();
+        continue;
+      }
+      await new Promise(resolve => {
+        const queue = this.waiting.get(name) ?? [];
+        queue.push(resolve);
+        this.waiting.set(name, queue);
+      });
+    }
   }
-  emit(input) {
-    const event = {
-      ...input,
-      at: new Date().toISOString()
-    };
-    for (const listener of this.listeners) {
+  free(name) {
+    this.held.delete(name);
+    this.waiting.get(name)?.shift()?.();
+  }
+  launch(path, options) {
+    const type = this.config.browserType ?? DEFAULT_BROWSER_CONFIG.browserType;
+    const launcher = type === 'firefox' ? firefox : type === 'webkit' ? webkit : chromium;
+    return launcher.launchPersistentContext(path, {
+      headless: this.config.headless ?? DEFAULT_BROWSER_CONFIG.headless,
+      slowMo: this.config.slowMo,
+      executablePath: this.config.executablePath,
+      proxy: options.proxy ?? this.config.proxy,
+      extraHTTPHeaders: options.headers,
+      userAgent: options.userAgent,
+      viewport: options.viewport,
+      ignoreHTTPSErrors: this.config.ignoreHTTPSErrors === true || options.ignoreHTTPSErrors === true
+    });
+  }
+  /**
+   * The profile's directory.
+   *
+   * @param name - A profile name.
+   * @returns The absolute path.
+   */
+  pathOf(name) {
+    if (!BROWSER_PROFILE_NAME.test(name)) throw new Error(`browser profile "${name}": a name is letters, digits, hyphens and underscores`);
+    return resolve$1(this.directory, name);
+  }
+  /**
+   * Opens a profile in its own browser, waiting while another run of this
+   * crawler uses it.
+   *
+   * @param name - The profile.
+   * @param options - Proxy, headers, viewport, cookies to add. `storageState` is ignored: the profile has its own.
+   * @param owner - Who opens it; the same owner reopening closes its previous session first.
+   * @returns The session; closing it frees the profile.
+   */
+  async open(name, options, owner) {
+    const path = this.pathOf(name);
+    await this.take(name, owner);
+    let context;
+    let unlock = unlocked;
+    try {
+      await mkdir(path, {
+        recursive: true
+      });
+      unlock = await lockProfile(path, name);
+      context = await this.launch(path, options);
+    } catch (error) {
+      await unlock();
+      this.free(name);
+      const message = error instanceof Error ? error.message : String(error);
+      if (/ProcessSingleton|SingletonLock|already in use/i.test(message)) throw new Error(`browser profile "${name}" is open in another browser (${path}); close it or use another profile`, {
+        cause: error
+      });
+      throw error;
+    }
+    if (this.config.timeoutMs !== undefined) context.setDefaultTimeout(this.config.timeoutMs);
+    await applySessionExtras(context, options);
+    const page = context.pages()[0] ?? (await context.newPage());
+    let closed = false;
+    const session = new BrowserSession(context, page, async () => {
+      if (closed) return;
+      closed = true;
       try {
-        listener(event);
-      } catch {
-        // A faulty listener is the caller's problem, not the crawl's.
+        await context.close();
+      } finally {
+        await unlock();
+        this.free(name);
       }
-    }
+    });
+    this.held.set(name, {
+      owner,
+      session
+    });
+    return session;
   }
 }
-
 /**
- * One line of a crawl trace: the route a recipe takes (pages visited, steps
- * run, records produced, policies fired), indented by how deep in the step
- * tree the event happened. `step:start` yields nothing; `step:finish` carries
- * the duration, so every step prints once.
+ * Marks a profile as used by this process, refusing one a live process
+ * holds and taking over one a dead process left behind.
  *
- * @param event - Any crawl event.
- * @returns The line, or `undefined` for events a trace does not show.
+ * @param path - The profile directory.
+ * @param name - The profile name, for the message.
+ * @returns The unlock.
+ * @throws Error when another crawler holds the profile.
  */
-function traceLine(event) {
-  switch (event.type) {
-    case 'recipe:start':
-      {
-        return `▶ ${event.recipeId} (${event.mode})`;
-      }
-    case 'recipe:finish':
-      {
-        return `■ ${event.recipeId}: ${event.emitted} emitted, ${event.rejected} rejected, ${event.duplicates} duplicates, ${event.skipped > 0 ? `${event.skipped} skipped, ` : ''}${(event.stepsSkipped ?? 0) > 0 ? `${event.stepsSkipped} steps skipped, ` : ''}${event.pages} pages, ${event.durationMs} ms${event.error === undefined ? '' : `\n  ✖ stopped: ${event.error}`}`;
-      }
-    case 'access:lease':
-      {
-        return `${indent(1)}⇄ access ${event.profile} (${event.kind}${event.server === undefined ? '' : ` ${event.server}`}${event.session === undefined ? '' : `, session ${event.session}`})`;
-      }
-    case 'access:blocked':
-      {
-        return `${indent(1)}⛔ blocked ${event.url}: ${event.reason}`;
-      }
-    case 'access:rotate':
-      {
-        return `${indent(1)}↻ new access lease (attempt ${event.attempt})`;
-      }
-    case 'page:visit':
-      {
-        return `${indent(1)}⇢ page ${event.number}  ${event.url}${event.status === undefined || event.status >= 200 && event.status < 300 ? '' : `  [${event.status}]`}`;
-      }
-    case 'step:start':
-      {
-        return undefined;
-      }
-    case 'step:finish':
-      {
-        return `${indent(depthOf$1(event.path))}· ${stepLabel(event)}  ${event.durationMs} ms`;
-      }
-    case 'step:retry':
-      {
-        return `${indent(depthOf$1(event.path))}↻ ${stepLabel(event)}  retry ${event.attempt}: ${event.error}`;
-      }
-    case 'step:skip':
-      {
-        return `${indent(depthOf$1(event.path))}↷ ${stepLabel(event)}  skipped: ${event.error}`;
-      }
-    case 'step:branch':
-      {
-        return `${indent(depthOf$1(event.path))}⑂ ${event.path}  ${event.branch}`;
-      }
-    case 'record:emit':
-      {
-        return `${indent(1)}✚ record ${event.key ?? '(no key)'}`;
-      }
-    case 'record:reject':
-      {
-        return `${indent(1)}✖ record rejected: ${event.field}: ${event.reason}`;
-      }
-    case 'record:duplicate':
-      {
-        return `${indent(1)}≡ duplicate ${event.key}`;
-      }
-    case 'record:skipped':
-      {
-        return `${indent(1)}⤼ skipped ${event.key}`;
-      }
-    case 'warning':
-      {
-        return `${indent(1)}! ${event.message}`;
-      }
-    case 'error':
-      {
-        return `${indent(1)}✖ ${event.message}`;
-      }
+async function lockProfile(path, name) {
+  const file = join$1(path, LOCK_FILE);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await writeFile(file, String(process.pid), {
+        flag: 'wx'
+      });
+      return async () => {
+        await rm(file, {
+          force: true
+        });
+      };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const holder = Number(await readHolder(file));
+      if (Number.isSafeInteger(holder) && holder > 0 && isAlive(holder)) throw new Error(`browser profile "${name}" is open in another browser (${path}, process ${holder}); close it or use another profile`, {
+        cause: error
+      });
+      await rm(file, {
+        force: true
+      });
+    }
   }
+  throw new Error(`browser profile "${name}": cannot lock ${path}`);
 }
-/** How deep a step path such as `steps.8.steps.2` or `steps.1.else.0` sits: one level per nested `steps` or `else`. */
-function depthOf$1(path) {
-  return path.split('.').filter(segment => ['steps', 'else'].includes(segment)).length;
-}
-function stepLabel(event) {
-  return `${event.path}  ${event.stepType}${event.stepId === undefined ? '' : ` ${event.stepId}`}`;
+/** The unlock of a profile that was never locked. */
+async function unlocked() {}
+async function readHolder(file) {
+  try {
+    return await readFile(file, 'utf8');
+  } catch {
+    return '';
+  }
 }
-function indent(depth) {
-  return '  '.repeat(depth);
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
 }
 
-/** A recipe named a hook nothing registered. */
-class UnknownHookError extends Error {
-  hookName;
-  name = 'UnknownHookError';
-  constructor(hookName, known) {
-    super(`unknown hook "${hookName}"${known.length === 0 ? ' (no hooks registered)' : `; registered: ${known.join(', ')}`}`);
-    this.hookName = hookName;
+/**
+ * Disposes a runner, ignoring a failure: a tab whose browser already went
+ * away (a rotation, a crash) has nothing left to close.
+ *
+ * @param runner - The runner.
+ */
+async function disposeQuietly(runner) {
+  try {
+    await runner.dispose();
+  } catch {
+    // already gone
   }
 }
 
-/** The hooks a crawler was created with, resolved by name at run time. */
-class HookRegistry {
-  hooks = {};
-  constructor(hooks = {}) {
-    for (const [name, hook] of Object.entries(hooks)) this.register(name, hook);
-  }
-  register(name, hook) {
-    this.hooks[name] = hook;
-  }
-  has(name) {
-    return Object.hasOwn(this.hooks, name);
-  }
-  names() {
-    return Object.keys(this.hooks);
-  }
-  /**
-   * @param name - The name a recipe used.
-   * @returns The hook.
-   * @throws UnknownHookError when nothing was registered under that name.
-   */
-  resolve(name) {
-    if (!this.has(name)) throw new UnknownHookError(name, this.names());
-    return this.hooks[name];
+/**
+ * Runs a body once per item of a list (`over`), or once per live element
+ * matching `selector`, each in a fresh child scope with the item bound under
+ * `as`; emits a record per iteration when asked.
+ *
+ * With a concurrent gate, iterations of a list run as permits allow and
+ * records come out in completion order; without one, in list order. In web
+ * mode each parallel iteration runs in a tab of its own (`runner.fork`); a
+ * loop over live elements stays sequential, since its elements live on one page.
+ *
+ * @param step - The forEach step.
+ * @param scope - The scope the list lives in.
+ * @param walk - Runs a step list; also carries the emit callback.
+ * @returns `stop` when the crawl reached its record limit.
+ */
+async function runForEach(step, scope, walk) {
+  const items = await itemsOf$1(step, scope, walk);
+  const gate = walk.gate;
+  if (gate?.concurrent === true && step.selector === undefined && (walk.recipe.mode === 'api' || walk.runner.fork !== undefined)) return runPooled(step, scope, walk, items, gate);
+  for (const item of items) {
+    if ((await runIteration(step, scope, walk, item)) === 'stop') return 'stop';
   }
+  return 'continue';
 }
-
-/** @returns A new in-memory sink. */
-function memorySink() {
-  const records = [];
-  return {
-    records,
-    open: async () => {},
-    write: async record => {
-      records.push(record);
-    },
-    has: async key => records.some(record => record.key === key),
-    close: async () => ({
-      written: records.length
-    })
-  };
+async function runIteration(step, scope, walk, item, overrides) {
+  const child = scope.child();
+  child.set(step.as, item);
+  const outcome = await walk.runSteps(step.steps, child, `${walk.path}.steps`, overrides);
+  if (outcome === 'stop' || step.emit === undefined) return outcome;
+  return walk.onEmit(child, step.emit === true ? undefined : step.emit.output);
 }
-
 /**
- * A sink that writes one JSON object per line to a file (JSON Lines). Each line
- * is the record's `data` plus a `_source` member (and `_key` in append mode).
- *
- * @param path - The file to write; created with its directories, truncated on open unless `append`.
- * @param options - Append mode.
- * @returns The sink.
- */
-function jsonLinesSink(path, options = {}) {
-  const target = resolve$1(path);
-  const append = options.append === true;
-  const keys = new Set();
-  let stream;
-  let written = 0;
-  return {
-    async open() {
-      await mkdir(dirname(target), {
-        recursive: true
-      });
-      const existing = append ? await existingKeys(target) : [];
-      for (const key of existing) keys.add(key);
-      stream = createWriteStream(target, {
-        encoding: 'utf8',
-        flags: append ? 'a' : 'w'
-      });
-      await once(stream, 'open');
-    },
-    async write(record) {
-      if (stream === undefined) throw new Error('jsonLinesSink: write before open');
-      const line = `${JSON.stringify({
-        ...record.data,
-        _source: record.source,
-        ...(append && record.key !== null && {
-          _key: record.key
-        })
-      })}\n`;
-      if (!stream.write(line)) await once(stream, 'drain');
-      if (record.key !== null) keys.add(record.key);
-      written += 1;
-    },
-    async close() {
-      if (stream !== undefined) {
-        stream.end();
-        await once(stream, 'finish');
-        stream = undefined;
-      }
-      return {
-        written,
-        location: target
-      };
-    },
-    async has(key) {
-      return keys.has(key);
-    }
-  };
-}
-/** The `_key` of every line already in the file; none when the file does not exist. */
-async function existingKeys(target) {
-  let content;
-  try {
-    content = await readFile(target, 'utf8');
-  } catch {
-    return [];
-  }
-  return content.split('\n').flatMap(line => {
-    if (line.trim() === '') return [];
-    try {
-      const key = JSON.parse(line)._key;
-      return typeof key === 'string' ? [key] : [];
-    } catch {
-      return [];
-    }
-  });
-}
-
-/** Drops records whose key was already seen. First record wins; keyless records always pass. */
-class DedupePolicy {
-  scope;
-  seen = new Set();
-  constructor(scope = 'run') {
-    this.scope = scope;
-  }
-  /** Called when an input recipe starts; forgets keys under `recipe` scope. */
-  startRecipe() {
-    if (this.scope === 'recipe') this.seen = new Set();
-  }
-  /**
-   * @param record - A validated record.
-   * @returns `true` when the record repeats an earlier key and must be dropped.
-   */
-  isDuplicate(record) {
-    if (this.scope === 'off' || record.key === null) return false;
-    if (this.seen.has(record.key)) return true;
-    this.seen.add(record.key);
-    return false;
-  }
-}
-
-/**
- * Evaluates a JSONPath expression on a decoded JSON document.
- *
- * @param document - The JSON value.
- * @param path - A JSONPath such as `$.items[*].url`.
- * @returns Every match, in document order.
- */
-function selectJson(document, path) {
-  return JSONPath({
-    path,
-    json: document,
-    wrap: true,
-    resultType: 'value'
-  });
-}
-
-/**
- * Evaluates a regular expression on text: the extract kind for values that
- * live in inline scripts, attributes or prose rather than in elements or JSON.
- *
- * @param text - The document text.
- * @param pattern - A regular expression source; group 1 is returned when the
- * pattern has a capturing group, else the whole match.
- * @returns Every match, in document order.
- * @throws When the pattern is not a valid regular expression.
- */
-function selectRegex(text, pattern) {
-  let expression;
-  try {
-    expression = new RegExp(pattern, 'gs');
-  } catch (error) {
-    throw new Error(`invalid pattern ${pattern}: ${error.message}`, {
-      cause: error
-    });
-  }
-  const values = Array.from(text.matchAll(expression), match => match[1] ?? match[0]);
-  return values;
-}
-
-const DOCUMENT = /^\s*(?:<!doctype|<html)/i;
-/**
- * Runs a CSS selector on static HTML. A whole document is parsed as one; anything
- * else (a table row, a list item taken with `take: "html"`) is parsed as a
- * fragment, so cells and rows outside a table survive instead of being dropped.
- *
- * @param html - The markup (a whole document or a fragment).
- * @param selector - A CSS selector.
- * @returns Every match, in document order.
- */
-function selectHtml(html, selector) {
-  const api = DOCUMENT.test(html) ? load(html) : load(html, undefined, false);
-  return api(selector).map((_, element) => ({
-    api,
-    element: api(element)
-  })).toArray();
-}
-
-/**
- * The value of an HTML match.
- *
- * @param match - A selected element.
- * @param take - What to take; `text` collapses whitespace.
- * @returns The value; `undefined` for a missing attribute.
- */
-function takeFromHtml(match, take) {
-  if (take === 'text') return collapse(match.element.text());
-  if (take === 'html') return match.element.html() ?? '';
-  if (take === 'value') return match.element.val() ?? match.element.attr('value');
-  if (take === 'json') return match.api.html(match.element);
-  return match.element.attr(take.slice('attr:'.length));
-}
-/**
- * The value of a JSON match.
- *
- * @param node - A JSONPath result.
- * @param take - `json` keeps the node; `text` stringifies scalars.
- * @returns The value.
- */
-function takeFromJson(node, take) {
-  if (take === 'json') return node;
-  if (node === null || node === undefined) return undefined;
-  if (typeof node === 'object') return JSON.stringify(node);
-  return String(node);
-}
-/**
- * Text as a human reads it: runs of whitespace collapsed, ends trimmed.
- *
- * @param text - Raw text content.
- * @returns The collapsed text.
- */
-function collapse(text) {
-  return text.replaceAll(/\s+/g, ' ').trim();
-}
-
-/**
- * JSON that arrives as text: a `<script type="application/ld+json">` body, a
- * `data-*` attribute, a fetched document read as text. Sites wrap inline JSON
- * in comment guards, which are stripped before parsing.
- */
-/** Comment guards sites wrap inline JSON-LD in: a CDATA marker inside a block comment, or an HTML comment. */
-const GUARDS = /^\s*(?:\/\*\s*<!\[CDATA\[\s*\*\/|<!\[CDATA\[|<!--)\s*|\s*(?:\/\*\s*\]\]>\s*\*\/|\]\]>|-->)\s*$/g;
-/**
- * Parses text as JSON, guards stripped.
- *
- * @param text - The text.
- * @returns The value, or `undefined` when it is not JSON.
- */
-function tryParseJson(text) {
-  try {
-    return JSON.parse(text.replaceAll(GUARDS, ''));
-  } catch {
-    return undefined;
-  }
-}
-/**
- * Parses text that must be JSON.
- *
- * @param text - The text.
- * @param id - What the text is, for the error.
- * @returns The value.
- * @throws Error when it is not JSON.
- */
-function parseJsonText(text, id) {
-  const parsed = tryParseJson(text);
-  if (parsed === undefined) throw new Error(`"${id}" is text but not JSON`);
-  return parsed;
-}
-/**
- * The data a value holds, whatever shape it arrived in: JSON text is parsed, a
- * list of texts becomes the list of its parsable entries, and an entry that
- * parses to a list is spliced in. Data that is not text is kept as is.
- *
- * @param value - A bound value: data, text, or a list of either.
- * @returns A list of items.
- */
-function dataItemsOf(value) {
-  if (typeof value === 'string') return itemsOf$1(tryParseJson(value));
-  if (Array.isArray(value)) return value.flatMap(entry => typeof entry === 'string' ? itemsOf$1(tryParseJson(entry)) : [entry]);
-  return itemsOf$1(value);
-}
-function itemsOf$1(parsed) {
-  if (parsed === undefined || parsed === null) return [];
-  return Array.isArray(parsed) ? parsed : [parsed];
-}
-
-/**
- * Runs a body once per item of a list (`over`), or once per live element
- * matching `selector`, each in a fresh child scope with the item bound under
- * `as`; emits a record per iteration when asked.
- *
- * With a concurrent gate, iterations run as permits allow and records come
- * out in completion order; without one, in list order.
- *
- * @param step - The forEach step.
- * @param scope - The scope the list lives in.
- * @param walk - Runs a step list; also carries the emit callback.
- * @returns `stop` when the crawl reached its record limit.
- */
-async function runForEach(step, scope, walk) {
-  const items = await itemsOf(step, scope, walk);
-  const gate = walk.gate;
-  if (gate?.concurrent === true) return runPooled(step, scope, walk, items, gate);
-  for (const item of items) {
-    if ((await runIteration(step, scope, walk, item)) === 'stop') return 'stop';
-  }
-  return 'continue';
-}
-async function runIteration(step, scope, walk, item, overrides) {
-  const child = scope.child();
-  child.set(step.as, item);
-  const outcome = await walk.runSteps(step.steps, child, `${walk.path}.steps`, overrides);
-  if (outcome === 'stop' || step.emit === undefined) return outcome;
-  return walk.onEmit(child, step.emit === true ? undefined : step.emit.output);
-}
-/**
- * Starts iterations as the gate hands out permits. A `stop` or a failure stops
- * new iterations; the ones in flight finish first, so the runner is never
- * disposed under them. The first failure is rethrown afterwards.
+ * Starts iterations as the gate hands out permits. A `stop` or a failure stops
+ * new iterations; the ones in flight finish first, so the runner is never
+ * disposed under them. The first failure is rethrown afterwards.
  */
 async function runPooled(step, scope, walk, items, gate) {
   let stopped = false;
   let failure;
   const tasks = [];
-  const overrides = {
-    gate: gate.nested()
-  };
+  const nested = gate.nested();
   const iterate = async (item, release) => {
+    let runner;
     try {
-      if ((await runIteration(step, scope, walk, item, overrides)) === 'stop') stopped = true;
+      runner = walk.runner.fork === undefined ? walk.runner : await walk.runner.fork();
+      if ((await runIteration(step, scope, walk, item, {
+        gate: nested,
+        runner
+      })) === 'stop') stopped = true;
     } catch (error) {
       failure ??= {
         error
       };
     } finally {
+      if (runner !== undefined && runner !== walk.runner) await disposeQuietly(runner);
       release();
     }
   };
@@ -1728,7 +1530,7 @@ async function runPooled(step, scope, walk, items, gate) {
   if (failure !== undefined) throw failure.error;
   return stopped ? 'stop' : 'continue';
 }
-async function itemsOf(step, scope, walk) {
+async function itemsOf$1(step, scope, walk) {
   if (step.selector !== undefined) {
     if (walk.runner.elements === undefined) throw new Error('forEach over selector iterates live elements and needs a browser; this recipe runs in api mode');
     return walk.runner.elements(renderText(step.selector, path => scope.lookup(path)), scope);
@@ -2019,6 +1821,7 @@ function logThrough(walk) {
 class RunGate {
   permits;
   minIntervalMs;
+  hosts;
   shared;
   inFlight = 0;
   waiting = [];
@@ -2026,11 +1829,13 @@ class RunGate {
   /**
    * @param permits - Iterations allowed in flight; 1 is sequential.
    * @param minIntervalMs - Minimum time between two request starts across the run.
+   * @param hosts - The crawler's per-site throttle, shared with every other recipe.
    * @param shared - The throttle state to share (internal: `nested` gates keep their parent's).
    */
-  constructor(permits, minIntervalMs, shared) {
+  constructor(permits, minIntervalMs, hosts, shared) {
     this.permits = permits;
     this.minIntervalMs = minIntervalMs;
+    this.hosts = hosts;
     this.shared = shared;
   }
   /** Whether this gate lets more than one iteration run at once. */
@@ -2054,57 +1859,1353 @@ class RunGate {
       this.inFlight -= 1;
       this.waiting.shift()?.();
     };
-  }
-  /**
-   * Waits until a request may start: `minIntervalMs` after the previous start,
-   * whichever loop started it. Returns at once when the interval has passed.
-   */
-  async throttle() {
-    const state = this.shared ?? this;
-    if (state.minIntervalMs <= 0) return;
-    const now = Date.now();
-    const at = Math.max(now, state.lastStart + state.minIntervalMs);
-    state.lastStart = at;
-    await sleep(at - now);
-  }
-  /** The gate for a body running inside an iteration that holds a permit: sequential, same throttle. */
-  nested() {
-    return new RunGate(1, this.minIntervalMs, this.shared ?? this);
+  }
+  /**
+   * Waits until a request may start: `minIntervalMs` after the previous start,
+   * whichever loop started it. Returns at once when the interval has passed.
+   */
+  async throttle() {
+    const state = this.shared ?? this;
+    if (state.minIntervalMs <= 0) return;
+    const now = Date.now();
+    const at = Math.max(now, state.lastStart + state.minIntervalMs);
+    state.lastStart = at;
+    await sleep(at - now);
+  }
+  /**
+   * Waits until a request to `url` may start: the recipe's interval, then its
+   * site's turn in the crawler's per-site throttle.
+   *
+   * @param url - Where the request goes.
+   * @returns The release of the site's lane: call it once the response arrived or the request failed.
+   */
+  async request(url) {
+    await this.throttle();
+    return this.hosts === undefined ? noop$1 : this.hosts.slot(url);
+  }
+  /** The gate for a body running inside an iteration that holds a permit: sequential, same throttle. */
+  nested() {
+    return new RunGate(1, this.minIntervalMs, this.hosts, this.shared ?? this);
+  }
+}
+function noop$1() {}
+
+/**
+ * Spaces and bounds requests per site, shared by every recipe of a crawler,
+ * so two recipes (or two parallel iterations) that hit one site add up to one
+ * polite client rather than two. A recipe's own `limits.delayMs` still applies
+ * on top, per recipe.
+ *
+ * Like a single-lane bridge with a traffic light: whoever arrives waits for
+ * the car ahead to be far enough, and for a free lane.
+ */
+class HostThrottle {
+  config;
+  buckets = new Map();
+  domains;
+  constructor(config = {}) {
+    this.config = config;
+    this.domains = Object.entries(config.domains ?? {}).map(([domain, rule]) => [domain.toLowerCase().replace(/^\.+/, ''), rule]).sort((first, second) => second[0].length - first[0].length);
+  }
+  bucketFor(url, always = false) {
+    const host = hostOf(url);
+    if (host === undefined) return undefined;
+    const match = this.domains.find(([domain]) => host === domain || host.endsWith(`.${domain}`));
+    const key = match?.[0] ?? host;
+    let bucket = this.buckets.get(key);
+    if (bucket === undefined) {
+      const rule = {
+        ...pick(this.config),
+        ...match?.[1]
+      };
+      if (!always && !hasLimit(rule)) return undefined;
+      bucket = {
+        rule,
+        inFlight: 0,
+        waiting: [],
+        lastStart: Promise.resolve(-Infinity),
+        pausedTo: 0
+      };
+      this.buckets.set(key, bucket);
+    }
+    return bucket;
+  }
+  /** Whether any rule can hold a request back. */
+  get active() {
+    return hasLimit(this.config) || this.domains.some(([, rule]) => hasLimit(rule)) || this.buckets.size > 0;
+  }
+  /**
+   * Waits until a request to `url` may start, then holds one of its site's
+   * lanes until the returned release is called.
+   *
+   * @param url - Where the request goes; anything but `http(s):` passes at once.
+   * @returns The release: call it once, when the response arrived or the request failed.
+   */
+  async slot(url) {
+    const bucket = this.bucketFor(url);
+    if (bucket === undefined) return noop;
+    const concurrency = bucket.rule.concurrency ?? Infinity;
+    if (bucket.inFlight >= concurrency) await new Promise(resolve => {
+      bucket.waiting.push(resolve);
+    });
+    bucket.inFlight += 1;
+    const previous = bucket.lastStart;
+    const turn = (async () => {
+      const after = await previous;
+      // A pause may arrive while waiting (a Retry-After), so check it again after each sleep.
+      for (;;) {
+        const now = Date.now();
+        const at = Math.max(now, after + (bucket.rule.delayMs ?? 0), bucket.pausedTo);
+        if (at <= now) return now;
+        await sleep(at - now);
+      }
+    })();
+    bucket.lastStart = turn;
+    await turn;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      bucket.inFlight -= 1;
+      bucket.waiting.shift()?.();
+    };
+  }
+  /**
+   * Holds every request to the site of `url` back until `untilMs` (a `Retry-After`).
+   *
+   * @param url - A URL of the site.
+   * @param untilMs - An epoch time.
+   */
+  pause(url, untilMs) {
+    const bucket = this.bucketFor(url, true);
+    if (bucket !== undefined) bucket.pausedTo = Math.max(bucket.pausedTo, untilMs);
+  }
+}
+function noop() {}
+function hostOf(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:' ? parsed.hostname.toLowerCase() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+function pick(config) {
+  return {
+    delayMs: config.delayMs,
+    concurrency: config.concurrency
+  };
+}
+function hasLimit(rule) {
+  return (rule.delayMs ?? 0) > 0 || rule.concurrency !== undefined;
+}
+
+/** Statuses a server uses for "not now": timeout, too early, too many requests, and the 5xx that pass. */
+const RETRY_STATUSES = [408, 425, 429, 500, 502, 503, 504];
+/** Three tries, one second then two apart, never a wait over 30 seconds. */
+const DEFAULT_RETRY_RULE = {
+  attempts: 3,
+  backoffMs: 1000,
+  maxDelayMs: 30_000,
+  statuses: [...RETRY_STATUSES]
+};
+/**
+ * Errors that say the connection failed rather than the site answered:
+ * resets, refusals, timeouts, a DNS lookup that could not run, a proxy that
+ * dropped the tunnel. A name that does not resolve at all (`ENOTFOUND`,
+ * `ERR_NAME_NOT_RESOLVED`) is not here: retrying a typo only wastes time.
+ */
+const TRANSIENT_ERROR = /ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|socket hang up|net::ERR_(?:CONNECTION_(?:RESET|REFUSED|CLOSED|ABORTED|TIMED_OUT)|TIMED_OUT|EMPTY_RESPONSE|NETWORK_CHANGED|INTERNET_DISCONNECTED|PROXY_CONNECTION_FAILED|TUNNEL_CONNECTION_FAILED|HTTP2_PROTOCOL_ERROR|NETWORK_IO_SUSPENDED)|NS_ERROR_NET_(?:RESET|INTERRUPT|TIMEOUT)|Timeout \d+ms exceeded/;
+/**
+ * The retry rule a recipe runs with: its `limits.retry` over the crawler's
+ * default over `DEFAULT_RETRY_RULE`.
+ *
+ * @param own - The recipe's `limits.retry`.
+ * @param crawler - The crawler's `retry` option.
+ * @returns The rule.
+ */
+function resolveRetryRule(own, crawler) {
+  return {
+    ...DEFAULT_RETRY_RULE,
+    ...definedOf(crawler),
+    ...definedOf(own)
+  };
+}
+/**
+ * Whether an error is a connection failure worth another try.
+ *
+ * @param error - What the request threw.
+ * @returns The reason, or `undefined`.
+ */
+function transientError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const match = TRANSIENT_ERROR.exec(message);
+  return match === null ? undefined : {
+    reason: match[0]
+  };
+}
+/**
+ * How long to wait before attempt `attempt + 1`: the server's `Retry-After`
+ * when it gave one, else `backoffMs` doubling per attempt with a little
+ * jitter; `undefined` when the server asks for longer than `maxDelayMs` (it
+ * means "come back much later", which a crawl cannot wait for).
+ *
+ * @param rule - The retry rule.
+ * @param attempt - The attempt that just failed, from 1.
+ * @param retryAfter - The `Retry-After` header: seconds, or an HTTP date.
+ * @param now - The current time, for dates.
+ * @returns Milliseconds, or `undefined` for no retry.
+ */
+function retryDelay(rule, attempt, retryAfter, now = Date.now()) {
+  const asked = retryAfterMs(retryAfter, now);
+  if (asked !== undefined) return asked > rule.maxDelayMs ? undefined : asked;
+  const base = rule.backoffMs * 2 ** (attempt - 1);
+  const jittered = base * (0.75 + Math.random() * 0.5);
+  return Math.min(Math.round(jittered), rule.maxDelayMs);
+}
+/**
+ * Sends a request through the gate (the recipe's rate, the site's lane), and
+ * sends it again after a pause while it fails in a passing way, up to
+ * `rule.attempts` tries in all. A `Retry-After` holds back every request to
+ * that site, not only this one. Each retry is reported as `request:retry`.
+ *
+ * Like redialling a busy number: wait a moment, dial again, give up after a
+ * few tries; and if the other end said "call back in a minute", wait that minute.
+ *
+ * @param url - Where the request goes.
+ * @param attempt - How to send it and how to judge the outcome.
+ * @param context - The recipe, gate, events and rule.
+ * @returns What the last try gave.
+ * @throws What the last try threw.
+ */
+async function withTransportRetry(url, attempt, context) {
+  const {
+    rule
+  } = context;
+  for (let tries = 1;; tries += 1) {
+    const release = await context.gate.request(url);
+    let outcome;
+    try {
+      outcome = {
+        value: await attempt.run()
+      };
+    } catch (error) {
+      outcome = {
+        error
+      };
+    } finally {
+      release();
+    }
+    const transient = tries < rule.attempts ? attempt.problem(outcome) : undefined;
+    const delay = transient === undefined ? undefined : retryDelay(rule, tries, transient.retryAfter);
+    if (transient === undefined || delay === undefined) {
+      if ('error' in outcome) throw outcome.error;
+      return outcome.value;
+    }
+    if (transient.retryAfter !== undefined) context.gate.hosts?.pause(url, Date.now() + delay);
+    context.events.emit({
+      type: 'request:retry',
+      recipeId: context.recipeId,
+      url,
+      attempt: tries + 1,
+      reason: transient.reason,
+      delayMs: delay
+    });
+    await sleep(delay);
+  }
+}
+function retryAfterMs(header, now) {
+  if (header === undefined || header.trim() === '') return undefined;
+  const seconds = Number(header.trim());
+  if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds * 1000));
+  const date = Date.parse(header);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - now);
+}
+function definedOf(rule) {
+  return Object.fromEntries(Object.entries(rule ?? {}).filter(([, value]) => value !== undefined));
+}
+
+/** A block unless a recipe says otherwise: forbidden, rate limited, or an AWS WAF challenge (IMDb answers 202 with it). */
+const DEFAULT_BLOCK_RULE = {
+  status: [403, 429],
+  header: {
+    'x-amzn-waf-action': 'challenge'
+  }
+};
+/**
+ * Whether a response is a block.
+ *
+ * @param response - What came back.
+ * @param rule - The recipe's `session.blockedWhen`; `DEFAULT_BLOCK_RULE` when omitted.
+ * @returns The error to throw, or `undefined` when the response is not a block.
+ */
+async function detectBlock(response, rule = DEFAULT_BLOCK_RULE) {
+  if (rule.status?.includes(response.status) === true) return new BlockedError(response.url, response.status, `HTTP ${response.status}`);
+  const headers = Object.entries(rule.header ?? {});
+  for (const [name, pattern] of headers) {
+    const value = response.headers[name.toLowerCase()];
+    if (value !== undefined && new RegExp(pattern, 'i').test(value)) return new BlockedError(response.url, response.status, `${name.toLowerCase()}: ${value}`);
+  }
+  if (rule.text !== undefined && response.text !== undefined) {
+    let body = '';
+    try {
+      body = await response.text();
+    } catch {
+      // a body that cannot be read (a redirect, a download) cannot match
+    }
+    const pattern = new RegExp(rule.text, 'i');
+    if (pattern.test(body)) return new BlockedError(response.url, response.status, `body matches /${rule.text}/i`);
+  }
+  return undefined;
+}
+
+/**
+ * A challenge the engine could not get past: the solver failed, the page did
+ * not confirm it, or the budget ran out. It is a block, so a recipe with
+ * `onBlock.rotate` retries the step on a new access lease (a new IP often
+ * means an easier challenge, or none), then the step's error policy applies.
+ */
+class CaptchaError extends BlockedError {
+  kind;
+  attempts;
+  constructor(url, kind, attempts, reason) {
+    super(url, 0, `captcha (${kind}) ${reason}`);
+    this.kind = kind;
+    this.attempts = attempts;
+  }
+}
+
+/** The captcha solvers a crawler was given, by name. */
+class CaptchaSolverRegistry {
+  solvers = new Map();
+  order = [];
+  constructor(solvers = []) {
+    for (const solver of solvers) {
+      if (this.solvers.has(solver.name)) throw new Error(`two captcha solvers are named "${solver.name}"`);
+      this.solvers.set(solver.name, solver);
+      this.order.push(solver.name);
+    }
+  }
+  /** The registered names. */
+  get names() {
+    return [...this.order];
+  }
+  has(name) {
+    return this.solvers.has(name);
+  }
+  /**
+   * The solver of that name.
+   *
+   * @param name - As a recipe names it.
+   * @returns The solver.
+   * @throws Error naming what is registered when it is not.
+   */
+  resolve(name) {
+    const solver = this.solvers.get(name);
+    if (solver === undefined) throw new Error(`captcha solver "${name}" is not registered (registered: ${this.names.join(', ') || 'none'}); give it to createCrawler({ captchaSolvers }) or export it from the plugins module`);
+    return solver;
+  }
+}
+
+/** Default solves a recipe run may spend. */
+const DEFAULT_MAX_SOLVES = 10;
+/**
+ * The solves a recipe run may still spend. Every solve costs money: a detector
+ * that matches the wrong element would drain a balance without it. Shared by
+ * every runner of the run, rotations included.
+ */
+class CaptchaBudget {
+  max;
+  used = 0;
+  constructor(max = DEFAULT_MAX_SOLVES) {
+    this.max = max;
+  }
+  /** Solves spent so far. */
+  get spent() {
+    return this.used;
+  }
+  /**
+   * Spends one solve.
+   *
+   * @returns Whether one was left.
+   */
+  take() {
+    if (this.used >= this.max) return false;
+    this.used += 1;
+    return true;
+  }
+}
+
+/** The widgets detection looks for when a recipe names none: reCAPTCHA v2, hCaptcha and Turnstile, as a container or as their iframe. */
+const DEFAULT_CAPTCHA_SELECTOR = ['.g-recaptcha', 'iframe[src*="recaptcha/api2/anchor"]', 'iframe[src*="recaptcha/enterprise/anchor"]', '.h-captcha', 'iframe[src*="hcaptcha.com"]', '.cf-turnstile', 'iframe[src*="challenges.cloudflare.com"]'].join(', ');
+/** reCAPTCHA v3 runs without a widget: its script is loaded with the site key as `render`. */
+const RECAPTCHA_V3_SCRIPT = 'script[src*="recaptcha/api.js?render="], script[src*="recaptcha/enterprise.js?render="]';
+/** Matches past this many are not looked at: a page does not show more challenges than that. */
+const MAX_CANDIDATES = 10;
+/**
+ * The first visible challenge on the page, if any. An element counts only
+ * when visible: sites keep hidden widgets around after a solve, and an
+ * invisible reCAPTCHA shows nothing until it challenges.
+ *
+ * @param page - The live page.
+ * @param selector - Where challenges are; `DEFAULT_CAPTCHA_SELECTOR` when omitted.
+ * @param options - `v3`: also report a reCAPTCHA v3 script (a `captcha` step asks for it; the automatic checks do not, since v3 never blocks a page by itself).
+ * @returns The challenge, or `undefined`.
+ */
+async function detectChallenge(page, selector = DEFAULT_CAPTCHA_SELECTOR, options = {}) {
+  const matches = page.locator(selector);
+  const count = Math.min(await matches.count(), MAX_CANDIDATES);
+  for (let index = 0; index < count; index += 1) {
+    const element = matches.nth(index);
+    if (!(await element.isVisible())) continue;
+    const facts = await element.evaluate(readWidget);
+    return challengeOf(facts, page.url(), `${selector} >> nth=${index}`);
+  }
+  if (options.v3 !== true) return undefined;
+  const script = page.locator(RECAPTCHA_V3_SCRIPT).first();
+  if ((await script.count()) === 0) return undefined;
+  const src = (await script.getAttribute('src')) ?? '';
+  const siteKey = new URL(src, page.url()).searchParams.get('render') ?? undefined;
+  return {
+    kind: 'recaptcha-v3',
+    url: page.url(),
+    ...(siteKey !== undefined && siteKey !== 'explicit' && {
+      siteKey
+    })
+  };
+}
+/**
+ * Whether the page is clear of challenges, tolerating a page that is
+ * navigating (a solve often submits a form): an evaluation cut short by the
+ * navigation counts as not clear yet.
+ *
+ * @param page - The live page.
+ * @param selector - Where challenges are.
+ * @returns Whether no challenge is visible.
+ */
+async function isClear(page, selector) {
+  try {
+    return (await detectChallenge(page, selector)) === undefined;
+  } catch {
+    return false;
+  }
+}
+/** Runs inside the page. Keep it self-contained; it is serialised. */
+function readWidget(element) {
+  const source = element.getAttribute('src') ?? element.querySelector('iframe')?.getAttribute('src') ?? '';
+  return {
+    tag: element.tagName.toLowerCase(),
+    className: element.getAttribute('class') ?? '',
+    src: source,
+    siteKey: element.dataset.sitekey,
+    action: element.dataset.action
+  };
+}
+function challengeOf(facts, url, selector) {
+  const siteKey = facts.siteKey ?? siteKeyIn(facts.src, url);
+  return {
+    kind: kindOf(facts),
+    url,
+    selector,
+    ...(siteKey !== undefined && {
+      siteKey
+    }),
+    ...(facts.action !== undefined && {
+      action: facts.action
+    })
+  };
+}
+function kindOf(facts) {
+  const hint = `${facts.className} ${facts.src}`.toLowerCase();
+  if (hint.includes('recaptcha')) return 'recaptcha-v2';
+  if (hint.includes('hcaptcha')) return 'hcaptcha';
+  if (hint.includes('turnstile') || hint.includes('challenges.cloudflare.com')) return 'turnstile';
+  return facts.tag === 'img' || facts.tag === 'canvas' ? 'image' : 'unknown';
+}
+/** A widget iframe carries its site key in the query: `k` (reCAPTCHA) or `sitekey` (hCaptcha). */
+function siteKeyIn(src, base) {
+  if (src === '') return undefined;
+  try {
+    const parameters = new URL(src, base).searchParams;
+    const hashParameters = new URLSearchParams(new URL(src, base).hash.slice(1));
+    return parameters.get('k') ?? parameters.get('sitekey') ?? hashParameters.get('sitekey') ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Default solves tried per challenge. */
+const DEFAULT_CAPTCHA_ATTEMPTS = 3;
+/** Default time one solve may take: token services take 10 to 60 seconds. */
+const DEFAULT_CAPTCHA_TIMEOUT_MS = 120_000;
+/** How long the page has to confirm a solve. */
+const VERIFY_TIMEOUT_MS = 10_000;
+const VERIFY_POLL_MS = 250;
+/**
+ * Gets past one challenge: asks the solver, then checks the page (a solver's
+ * `solved` is a claim; the challenge must be gone and/or the `verify` element
+ * must appear), and tries again with what the page shows next, up to
+ * `attempts`. Each try spends one solve of the run's budget.
+ *
+ * A failed try re-detects the challenge (a widget re-renders after a wrong
+ * answer). When it is gone without the page confirming, the page is reloaded
+ * for a fresh one; when a reload shows none, there is nothing left to solve.
+ *
+ * @param plan - The challenge, the solver and the limits.
+ * @throws CaptchaError when every try failed, or the budget is spent.
+ */
+async function resolveCaptcha(plan) {
+  const {
+    recipeId,
+    page,
+    solver,
+    events,
+    budget
+  } = plan;
+  let challenge = plan.challenge;
+  let reason = 'no attempt ran';
+  for (let attempt = 1; attempt <= plan.attempts; attempt += 1) {
+    if (!budget.take()) {
+      events.emit({
+        type: 'captcha:budget',
+        recipeId,
+        url: challenge.url,
+        kind: challenge.kind,
+        max: budget.max
+      });
+      throw new CaptchaError(challenge.url, challenge.kind, attempt - 1, `left unsolved: the run's ${budget.max} solves are spent (session.captcha.maxSolves)`);
+    }
+    events.emit({
+      type: 'captcha:solve',
+      recipeId,
+      url: challenge.url,
+      kind: challenge.kind,
+      solver: solver.name,
+      attempt
+    });
+    const started = Date.now();
+    const outcome = await solveOnce(plan, challenge, attempt);
+    if (outcome.status === 'solved' && (await confirmed(page, challenge, plan))) {
+      events.emit({
+        type: 'captcha:solved',
+        recipeId,
+        url: challenge.url,
+        kind: challenge.kind,
+        solver: solver.name,
+        attempt,
+        durationMs: Date.now() - started
+      });
+      return;
+    }
+    reason = outcome.status === 'failed' ? outcome.reason : 'the page still shows the challenge';
+    events.emit({
+      type: 'captcha:failed',
+      recipeId,
+      url: challenge.url,
+      kind: challenge.kind,
+      solver: solver.name,
+      attempt,
+      reason
+    });
+    if (attempt === plan.attempts) break;
+    const next = await nextChallenge(page, challenge, plan.selector);
+    if (next === undefined) return;
+    challenge = next;
+  }
+  throw new CaptchaError(challenge.url, challenge.kind, plan.attempts, `not solved after ${plan.attempts} attempt${plan.attempts === 1 ? '' : 's'}: ${reason}`);
+}
+/** Runs the solver once, bounded by the timeout; a throw or a malformed answer is a failure. */
+async function solveOnce(plan, challenge, attempt) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise(resolve => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve({
+        status: 'failed',
+        reason: `the solver took longer than ${plan.timeoutMs} ms`
+      });
+    }, plan.timeoutMs);
+  });
+  const log = (level, message, meta) => {
+    plan.events.emit({
+      type: level === 'error' ? 'error' : 'warning',
+      recipeId: plan.recipeId,
+      message: `[${plan.solver.name}] ${message}`,
+      meta
+    });
+  };
+  const solving = (async () => {
+    try {
+      return outcomeOf(await plan.solver.solve(challenge, {
+        page: plan.page,
+        lease: plan.lease,
+        attempt,
+        signal: controller.signal,
+        log
+      }));
+    } catch (error) {
+      return {
+        status: 'failed',
+        reason: error instanceof Error ? error.message : String(error)
+      };
+    }
+  })();
+  try {
+    return await Promise.race([solving, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function outcomeOf(value) {
+  if (typeof value !== 'object' || value === null) return {
+    status: 'failed',
+    reason: 'the solver returned no outcome'
+  };
+  const outcome = value;
+  if (outcome.status === 'solved') return {
+    status: 'solved'
+  };
+  return {
+    status: 'failed',
+    reason: typeof outcome.reason === 'string' ? outcome.reason : 'the solver reported a failure'
+  };
+}
+/**
+ * Whether the page confirms the solve: the challenge is gone (unless
+ * `verify.gone` is `false`, or the challenge has no widget, as with reCAPTCHA
+ * v3) and the `verify.selector` element is visible, within ten seconds.
+ */
+async function confirmed(page, challenge, plan) {
+  const needGone = plan.verify?.gone !== false && challenge.selector !== undefined;
+  const shown = plan.verify?.selector;
+  if (!needGone && shown === undefined) return true;
+  const deadline = Date.now() + VERIFY_TIMEOUT_MS;
+  for (;;) {
+    const gone = !needGone || (await isClear(page, plan.selector));
+    const visible = shown === undefined || (await isVisible(page, shown));
+    if (gone && visible) return true;
+    if (Date.now() >= deadline) return false;
+    await page.waitForTimeout(VERIFY_POLL_MS);
+  }
+}
+async function isVisible(page, selector) {
+  try {
+    return await page.locator(selector).first().isVisible();
+  } catch {
+    return false;
+  }
+}
+/** The challenge to try next: what the page shows now, else what a reload shows, else none. A widgetless challenge is tried as it is. */
+async function nextChallenge(page, previous, selector) {
+  if (previous.selector === undefined) return previous;
+  const current = await detectChallenge(page, selector);
+  if (current !== undefined) return current;
+  await page.reload();
+  return detectChallenge(page, selector);
+}
+
+/**
+ * Where a web runner meets captchas: after each navigation, click and key
+ * press (`session.captcha`), on a block page (`onBlock.solve`), and at a
+ * `captcha` step.
+ */
+class CaptchaGuard {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  settings() {
+    const captcha = this.options.recipe.session?.captcha;
+    if (captcha === undefined) return undefined;
+    return {
+      solver: captcha.solver,
+      selector: captcha.detect?.selector ?? DEFAULT_CAPTCHA_SELECTOR,
+      verify: captcha.verify,
+      attempts: captcha.attempts ?? DEFAULT_CAPTCHA_ATTEMPTS,
+      timeoutMs: captcha.timeoutMs ?? DEFAULT_CAPTCHA_TIMEOUT_MS
+    };
+  }
+  async solve(page, challenge, settings) {
+    const {
+      recipe,
+      events,
+      solvers,
+      budget,
+      lease
+    } = this.options;
+    events.emit({
+      type: 'captcha:detected',
+      recipeId: recipe.id,
+      url: challenge.url,
+      kind: challenge.kind,
+      siteKey: challenge.siteKey
+    });
+    await resolveCaptcha({
+      recipeId: recipe.id,
+      page,
+      challenge,
+      solver: solvers.resolve(settings.solver),
+      selector: settings.selector,
+      verify: settings.verify,
+      attempts: settings.attempts,
+      timeoutMs: settings.timeoutMs,
+      budget,
+      events,
+      lease
+    });
+  }
+  /** Whether a block page is searched for a challenge before the block counts. */
+  get solvesBlocks() {
+    const session = this.options.recipe.session;
+    return session?.onBlock?.solve === true && session.captcha !== undefined;
+  }
+  /**
+   * The automatic check: with `session.captcha`, solves the challenge the page
+   * shows, if any. Without it, nothing is looked for.
+   *
+   * @param page - The live page.
+   * @throws CaptchaError when the challenge could not be solved.
+   */
+  async check(page) {
+    const settings = this.settings();
+    if (settings === undefined) return;
+    const challenge = await detectChallenge(page, settings.selector);
+    if (challenge !== undefined) await this.solve(page, challenge, settings);
+  }
+  /**
+   * A block page under `onBlock.solve`: solves the challenge it shows. A block
+   * without a challenge stays a block.
+   *
+   * @param page - The page showing the block.
+   * @param blocked - The block.
+   * @throws BlockedError (`blocked`) when the page shows no challenge; CaptchaError when it could not be solved.
+   */
+  async solveBlock(page, blocked) {
+    const settings = this.settings();
+    if (settings === undefined) throw blocked;
+    const challenge = await detectChallenge(page, settings.selector);
+    if (challenge === undefined) throw blocked;
+    await this.solve(page, challenge, settings);
+  }
+  /**
+   * A `captcha` step: solves the challenge the page shows, reCAPTCHA v3
+   * included; a page without one is fine.
+   *
+   * @param page - The live page.
+   * @param step - The step.
+   * @throws CaptchaError when the challenge could not be solved.
+   */
+  async step(page, step) {
+    const base = this.settings();
+    const solver = step.solver ?? base?.solver;
+    if (solver === undefined) throw new Error('a captcha step needs a solver: name one ("solver") or add session.captcha');
+    const settings = {
+      solver,
+      selector: step.selector ?? base?.selector ?? DEFAULT_CAPTCHA_SELECTOR,
+      verify: step.verify ?? base?.verify,
+      attempts: step.attempts ?? base?.attempts ?? DEFAULT_CAPTCHA_ATTEMPTS,
+      timeoutMs: step.timeoutMs ?? base?.timeoutMs ?? DEFAULT_CAPTCHA_TIMEOUT_MS
+    };
+    const challenge = await detectChallenge(page, settings.selector, {
+      v3: true
+    });
+    if (challenge !== undefined) await this.solve(page, challenge, settings);
+  }
+}
+/**
+ * Every solver name a recipe uses (`session.captcha` and its `captcha`
+ * steps, the bootstrap's included), to check them before the run starts.
+ *
+ * @param recipe - The input recipe.
+ * @returns The names, without repeats.
+ */
+function captchaSolverNames(recipe) {
+  const names = new Set();
+  const fallback = recipe.session?.captcha?.solver;
+  if (fallback !== undefined) names.add(fallback);
+  const visit = steps => {
+    for (const step of steps) {
+      if (step.type === 'captcha') names.add(step.solver ?? fallback ?? '');
+      if ('steps' in step) visit(step.steps);
+      if (step.type === 'if') visit(step.else ?? []);
+    }
+  };
+  visit(recipe.steps);
+  visit(recipe.session?.bootstrap?.steps ?? []);
+  names.delete('');
+  return [...names];
+}
+
+/** Fans crawl events out to listeners. A listener that throws never breaks the crawl. */
+class EventBus {
+  listeners = new Set();
+  constructor(listener) {
+    if (listener !== undefined) this.listeners.add(listener);
+  }
+  /** @returns A function that removes the listener. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit(input) {
+    const event = {
+      ...input,
+      at: new Date().toISOString()
+    };
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // A faulty listener is the caller's problem, not the crawl's.
+      }
+    }
+  }
+}
+
+/**
+ * One line of a crawl trace: the route a recipe takes (pages visited, steps
+ * run, records produced, policies fired), indented by how deep in the step
+ * tree the event happened. `step:start` yields nothing; `step:finish` carries
+ * the duration, so every step prints once.
+ *
+ * @param event - Any crawl event.
+ * @returns The line, or `undefined` for events a trace does not show.
+ */
+function traceLine(event) {
+  switch (event.type) {
+    case 'recipe:start':
+      {
+        return `▶ ${event.recipeId} (${event.mode})`;
+      }
+    case 'recipe:finish':
+      {
+        return `■ ${event.recipeId}: ${event.emitted} emitted, ${event.rejected} rejected, ${event.duplicates} duplicates, ${event.skipped > 0 ? `${event.skipped} skipped, ` : ''}${(event.stepsSkipped ?? 0) > 0 ? `${event.stepsSkipped} steps skipped, ` : ''}${event.pages} pages, ${event.durationMs} ms${event.error === undefined ? '' : `\n  ✖ stopped: ${event.error}`}`;
+      }
+    case 'access:lease':
+      {
+        return `${indent(1)}⇄ access ${event.profile} (${event.kind}${event.server === undefined ? '' : ` ${event.server}`}${event.session === undefined ? '' : `, session ${event.session}`})`;
+      }
+    case 'access:blocked':
+      {
+        return `${indent(1)}⛔ blocked ${event.url}: ${event.reason}`;
+      }
+    case 'access:rotate':
+      {
+        return `${indent(1)}↻ new access lease (attempt ${event.attempt})`;
+      }
+    case 'request:retry':
+      {
+        return `${indent(1)}↺ ${event.url}: ${event.reason}, try ${event.attempt} in ${event.delayMs} ms`;
+      }
+    case 'captcha:detected':
+      {
+        return `${indent(1)}⚿ captcha ${event.kind} on ${event.url}`;
+      }
+    case 'captcha:solve':
+      {
+        return undefined;
+      }
+    case 'captcha:solved':
+      {
+        return `${indent(1)}✓ captcha solved by ${event.solver} (attempt ${event.attempt}, ${event.durationMs} ms)`;
+      }
+    case 'captcha:failed':
+      {
+        return `${indent(1)}✗ captcha attempt ${event.attempt} failed: ${event.reason}`;
+      }
+    case 'captcha:budget':
+      {
+        return `${indent(1)}⛔ captcha left unsolved: the run's ${event.max} solves are spent`;
+      }
+    case 'page:visit':
+      {
+        return `${indent(1)}⇢ page ${event.number}  ${event.url}${event.status === undefined || event.status >= 200 && event.status < 300 ? '' : `  [${event.status}]`}`;
+      }
+    case 'step:start':
+      {
+        return undefined;
+      }
+    case 'step:finish':
+      {
+        return `${indent(depthOf$1(event.path))}· ${stepLabel(event)}  ${event.durationMs} ms`;
+      }
+    case 'step:retry':
+      {
+        return `${indent(depthOf$1(event.path))}↻ ${stepLabel(event)}  retry ${event.attempt}: ${event.error}`;
+      }
+    case 'step:skip':
+      {
+        return `${indent(depthOf$1(event.path))}↷ ${stepLabel(event)}  skipped: ${event.error}`;
+      }
+    case 'step:branch':
+      {
+        return `${indent(depthOf$1(event.path))}⑂ ${event.path}  ${event.branch}`;
+      }
+    case 'record:emit':
+      {
+        return `${indent(1)}✚ record ${event.key ?? '(no key)'}`;
+      }
+    case 'record:reject':
+      {
+        return `${indent(1)}✖ record rejected: ${event.field}: ${event.reason}`;
+      }
+    case 'record:duplicate':
+      {
+        return `${indent(1)}≡ duplicate ${event.key}`;
+      }
+    case 'record:skipped':
+      {
+        return `${indent(1)}⤼ skipped ${event.key}`;
+      }
+    case 'warning':
+      {
+        return `${indent(1)}! ${event.message}`;
+      }
+    case 'error':
+      {
+        return `${indent(1)}✖ ${event.message}`;
+      }
+  }
+}
+/** How deep a step path such as `steps.8.steps.2` or `steps.1.else.0` sits: one level per nested `steps` or `else`. */
+function depthOf$1(path) {
+  return path.split('.').filter(segment => ['steps', 'else'].includes(segment)).length;
+}
+function stepLabel(event) {
+  return `${event.path}  ${event.stepType}${event.stepId === undefined ? '' : ` ${event.stepId}`}`;
+}
+function indent(depth) {
+  return '  '.repeat(depth);
+}
+
+/** A recipe named a hook nothing registered. */
+class UnknownHookError extends Error {
+  hookName;
+  name = 'UnknownHookError';
+  constructor(hookName, known) {
+    super(`unknown hook "${hookName}"${known.length === 0 ? ' (no hooks registered)' : `; registered: ${known.join(', ')}`}`);
+    this.hookName = hookName;
+  }
+}
+
+/** The hooks a crawler was created with, resolved by name at run time. */
+class HookRegistry {
+  hooks = {};
+  constructor(hooks = {}) {
+    for (const [name, hook] of Object.entries(hooks)) this.register(name, hook);
+  }
+  register(name, hook) {
+    this.hooks[name] = hook;
+  }
+  has(name) {
+    return Object.hasOwn(this.hooks, name);
+  }
+  names() {
+    return Object.keys(this.hooks);
+  }
+  /**
+   * @param name - The name a recipe used.
+   * @returns The hook.
+   * @throws UnknownHookError when nothing was registered under that name.
+   */
+  resolve(name) {
+    if (!this.has(name)) throw new UnknownHookError(name, this.names());
+    return this.hooks[name];
+  }
+}
+
+/** @returns A new in-memory sink. */
+function memorySink() {
+  const records = [];
+  return {
+    records,
+    open: async () => {},
+    write: async record => {
+      records.push(record);
+    },
+    has: async key => records.some(record => record.key === key),
+    close: async () => ({
+      written: records.length
+    })
+  };
+}
+
+/**
+ * A sink that writes one JSON object per line to a file (JSON Lines). Each line
+ * is the record's `data` plus a `_source` member (and `_key` in append mode).
+ *
+ * @param path - The file to write; created with its directories, truncated on open unless `append`.
+ * @param options - Append mode.
+ * @returns The sink.
+ */
+function jsonLinesSink(path, options = {}) {
+  const target = resolve$1(path);
+  const append = options.append === true;
+  const keys = new Set();
+  let stream;
+  let written = 0;
+  return {
+    async open() {
+      await mkdir(dirname(target), {
+        recursive: true
+      });
+      const existing = append ? await existingKeys(target) : [];
+      for (const key of existing) keys.add(key);
+      stream = createWriteStream(target, {
+        encoding: 'utf8',
+        flags: append ? 'a' : 'w'
+      });
+      await once(stream, 'open');
+    },
+    async write(record) {
+      if (stream === undefined) throw new Error('jsonLinesSink: write before open');
+      const line = `${JSON.stringify({
+        ...record.data,
+        _source: record.source,
+        ...(append && record.key !== null && {
+          _key: record.key
+        })
+      })}\n`;
+      if (!stream.write(line)) await once(stream, 'drain');
+      if (record.key !== null) keys.add(record.key);
+      written += 1;
+    },
+    async close() {
+      if (stream !== undefined) {
+        stream.end();
+        await once(stream, 'finish');
+        stream = undefined;
+      }
+      return {
+        written,
+        location: target
+      };
+    },
+    async has(key) {
+      return keys.has(key);
+    }
+  };
+}
+/** The `_key` of every line already in the file; none when the file does not exist. */
+async function existingKeys(target) {
+  let content;
+  try {
+    content = await readFile(target, 'utf8');
+  } catch {
+    return [];
+  }
+  return content.split('\n').flatMap(line => {
+    if (line.trim() === '') return [];
+    try {
+      const key = JSON.parse(line)._key;
+      return typeof key === 'string' ? [key] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+
+/**
+ * Drops records whose key was already seen. First record wins; keyless
+ * records always pass. Recipes running in parallel each get their own view:
+ * under `recipe` scope they never see each other's keys, under `run` scope
+ * they share them (and whichever emits a key first keeps it).
+ */
+class DedupePolicy {
+  scope;
+  shared = new Set();
+  constructor(scope = 'run') {
+    this.scope = scope;
+  }
+  /**
+   * The de-duplication one input recipe run uses.
+   *
+   * @returns Its view: keys shared with the run, its own, or none checked.
+   */
+  forRecipe() {
+    if (this.scope === 'off') return {
+      isDuplicate: () => false
+    };
+    const seen = this.scope === 'run' ? this.shared : new Set();
+    return {
+      isDuplicate: record => {
+        if (record.key === null) return false;
+        if (seen.has(record.key)) return true;
+        seen.add(record.key);
+        return false;
+      }
+    };
+  }
+}
+
+/**
+ * Evaluates a JSONPath expression on a decoded JSON document.
+ *
+ * @param document - The JSON value.
+ * @param path - A JSONPath such as `$.items[*].url`.
+ * @returns Every match, in document order.
+ */
+function selectJson(document, path) {
+  return JSONPath({
+    path,
+    json: document,
+    wrap: true,
+    resultType: 'value'
+  });
+}
+
+/**
+ * Evaluates a regular expression on text: the extract kind for values that
+ * live in inline scripts, attributes or prose rather than in elements or JSON.
+ *
+ * @param text - The document text.
+ * @param pattern - A regular expression source; group 1 is returned when the
+ * pattern has a capturing group, else the whole match.
+ * @returns Every match, in document order.
+ * @throws When the pattern is not a valid regular expression.
+ */
+function selectRegex(text, pattern) {
+  let expression;
+  try {
+    expression = new RegExp(pattern, 'gs');
+  } catch (error) {
+    throw new Error(`invalid pattern ${pattern}: ${error.message}`, {
+      cause: error
+    });
+  }
+  const values = Array.from(text.matchAll(expression), match => match[1] ?? match[0]);
+  return values;
+}
+
+const DOCUMENT = /^\s*(?:<!doctype|<html)/i;
+/**
+ * Runs a CSS selector on static HTML. A whole document is parsed as one; anything
+ * else (a table row, a list item taken with `take: "html"`) is parsed as a
+ * fragment, so cells and rows outside a table survive instead of being dropped.
+ *
+ * @param html - The markup (a whole document or a fragment).
+ * @param selector - A CSS selector.
+ * @returns Every match, in document order.
+ */
+function selectHtml(html, selector) {
+  const api = DOCUMENT.test(html) ? load(html) : load(html, undefined, false);
+  return api(selector).map((_, element) => ({
+    api,
+    element: api(element)
+  })).toArray();
+}
+
+/**
+ * The value of an HTML match.
+ *
+ * @param match - A selected element.
+ * @param take - What to take; `text` collapses whitespace.
+ * @returns The value; `undefined` for a missing attribute.
+ */
+function takeFromHtml(match, take) {
+  if (take === 'text') return collapse(match.element.text());
+  if (take === 'html') return match.element.html() ?? '';
+  if (take === 'value') return match.element.val() ?? match.element.attr('value');
+  if (take === 'json') return match.api.html(match.element);
+  return match.element.attr(take.slice('attr:'.length));
+}
+/**
+ * The value of a JSON match.
+ *
+ * @param node - A JSONPath result.
+ * @param take - `json` keeps the node; `text` stringifies scalars.
+ * @returns The value.
+ */
+function takeFromJson(node, take) {
+  if (take === 'json') return node;
+  if (node === null || node === undefined) return undefined;
+  if (typeof node === 'object') return JSON.stringify(node);
+  return String(node);
+}
+/**
+ * Text as a human reads it: runs of whitespace collapsed, ends trimmed.
+ *
+ * @param text - Raw text content.
+ * @returns The collapsed text.
+ */
+function collapse(text) {
+  return text.replaceAll(/\s+/g, ' ').trim();
+}
+
+/**
+ * JSON that arrives as text: a `<script type="application/ld+json">` body, a
+ * `data-*` attribute, a fetched document read as text. Sites wrap JSON in
+ * things that are not JSON: comment guards around inline JSON-LD, prefixes
+ * that stop a page from loading an API as a script, a JSONP callback, an
+ * assignment in an inline script. Those wrappers are removed, but only after
+ * the text failed to parse as it is, and what is left must still be strict
+ * JSON: nothing is evaluated.
+ */
+/** Comment guards sites wrap inline JSON-LD in: a CDATA marker inside a block comment, or an HTML comment. */
+const GUARDS = /^\s*(?:\/\*\s*<!\[CDATA\[\s*\*\/|<!\[CDATA\[|<!--)\s*|\s*(?:\/\*\s*\]\]>\s*\*\/|\]\]>|-->)\s*$/g;
+/** Anti-hijacking prefixes: `)]}'` (with or without a comma), `while(1);`, `for(;;);`. */
+const XSSI_PREFIX = /^\s*(?:\)\]\}'\s*,?|while\s*\(\s*1\s*\)\s*;|for\s*\(\s*;\s*;\s*\)\s*;)/;
+/** A JSONP call: `callback({...});`, the callback an identifier path. */
+const JSONP = /^\s*[$A-Z_][\w$]*(?:\.[$A-Z_][\w$]*)*\s*\(([\s\S]*)\)\s*(?:;\s*)?$/i;
+/** An assignment in an inline script: `window.__STATE__ = {...};`, with `var`, `let` or `const` or none. */
+const ASSIGNMENT = /^\s*(?:(?:var|let|const)\s+)?[$A-Z_a-z][\w$]*(?:\.[$A-Z_a-z][\w$]*|\[["'][^"']*["']\])*\s*=([\s\S]*)$/;
+/**
+ * Parses text as JSON, or as JSON inside one of the wrappers sites put around
+ * it: comment guards, an anti-hijacking prefix, a JSONP call, an assignment.
+ * Valid JSON is always read as it is; a wrapper is only removed when that
+ * fails.
+ *
+ * @param text - The text.
+ * @returns The value, or the error the text as it is gave.
+ */
+function parseJsonLike(text) {
+  const direct = parseJson$1(text);
+  if ('value' in direct) return direct;
+  const unguarded = text.replaceAll(GUARDS, '');
+  const assigned = ASSIGNMENT.exec(unguarded)?.[1].trim().replace(/;$/, '');
+  const candidates = [unguarded, unguarded.replace(XSSI_PREFIX, ''), JSONP.exec(unguarded)?.[1], assigned];
+  for (const candidate of candidates) {
+    if (candidate === undefined || candidate === text) continue;
+    const parsed = parseJson$1(candidate);
+    if ('value' in parsed) return parsed;
+  }
+  return direct;
+}
+/**
+ * Parses JSON Lines (NDJSON): one JSON value per non-blank line.
+ *
+ * @param text - The text.
+ * @param source - Where it came from, for the error.
+ * @returns The values, in order.
+ * @throws Error naming the source and the line that does not parse.
+ */
+function parseJsonLines(text, source) {
+  const values = [];
+  for (const [index, line] of text.split(/\r?\n/).entries()) {
+    if (line.trim() === '') continue;
+    const parsed = parseJson$1(line);
+    if ('error' in parsed) throw new Error(`${source}: line ${index + 1} is not JSON (${parsed.error.message})`, {
+      cause: parsed.error
+    });
+    values.push(parsed.value);
+  }
+  return values;
+}
+/**
+ * Parses text as JSON, wrappers removed (see {@link parseJsonLike}).
+ *
+ * @param text - The text.
+ * @returns The value, or `undefined` when it is not JSON.
+ */
+function tryParseJson(text) {
+  const parsed = parseJsonLike(text);
+  return 'value' in parsed ? parsed.value : undefined;
+}
+/**
+ * Parses text that must be JSON.
+ *
+ * @param text - The text.
+ * @param id - What the text is, for the error.
+ * @returns The value.
+ * @throws Error when it is not JSON.
+ */
+function parseJsonText(text, id) {
+  const parsed = tryParseJson(text);
+  if (parsed === undefined) throw new Error(`"${id}" is text but not JSON`);
+  return parsed;
+}
+/**
+ * The data a value holds, whatever shape it arrived in: JSON text is parsed, a
+ * list of texts becomes the list of its parsable entries, and an entry that
+ * parses to a list is spliced in. Data that is not text is kept as is.
+ *
+ * @param value - A bound value: data, text, or a list of either.
+ * @returns A list of items.
+ */
+function dataItemsOf(value) {
+  if (typeof value === 'string') return itemsOf(tryParseJson(value));
+  if (Array.isArray(value)) return value.flatMap(entry => typeof entry === 'string' ? itemsOf(tryParseJson(entry)) : [entry]);
+  return itemsOf(value);
+}
+function itemsOf(parsed) {
+  if (parsed === undefined || parsed === null) return [];
+  return Array.isArray(parsed) ? parsed : [parsed];
+}
+function parseJson$1(text) {
+  try {
+    return {
+      value: JSON.parse(text)
+    };
+  } catch (error) {
+    return {
+      error: error
+    };
   }
 }
 
-/** A block unless a recipe says otherwise: forbidden, rate limited, or an AWS WAF challenge (IMDb answers 202 with it). */
-const DEFAULT_BLOCK_RULE = {
-  status: [403, 429],
-  header: {
-    'x-amzn-waf-action': 'challenge'
-  }
-};
 /**
- * Whether a response is a block.
+ * The text a `regex` extract reads: per visible slide, its title, its text
+ * boxes in reading order, its tables' rows (cells separated by a tab) and its
+ * notes after `Notes:`; slides separated by a blank line.
  *
- * @param response - What came back.
- * @param rule - The recipe's `session.blockedWhen`; `DEFAULT_BLOCK_RULE` when omitted.
- * @returns The error to throw, or `undefined` when the response is not a block.
+ * @param document - The deck.
+ * @returns The text.
  */
-async function detectBlock(response, rule = DEFAULT_BLOCK_RULE) {
-  if (rule.status?.includes(response.status) === true) return new BlockedError(response.url, response.status, `HTTP ${response.status}`);
-  const headers = Object.entries(rule.header ?? {});
-  for (const [name, pattern] of headers) {
-    const value = response.headers[name.toLowerCase()];
-    if (value !== undefined && new RegExp(pattern, 'i').test(value)) return new BlockedError(response.url, response.status, `${name.toLowerCase()}: ${value}`);
-  }
-  if (rule.text !== undefined && response.text !== undefined) {
-    let body = '';
-    try {
-      body = await response.text();
-    } catch {
-      // a body that cannot be read (a redirect, a download) cannot match
-    }
-    const pattern = new RegExp(rule.text, 'i');
-    if (pattern.test(body)) return new BlockedError(response.url, response.status, `body matches /${rule.text}/i`);
+function deckText(document) {
+  return document.slides.filter(slide => !slide.hidden).map(slide => [...slide.shapes.map(shape => shape.text), ...slide.tables.flatMap(table => table.rows.map(row => row.map(String).join('\t'))), ...(slide.notes === '' ? [] : [`Notes: ${slide.notes}`])].join('\n')).join('\n\n');
+}
+/**
+ * Whether a value bound in scope is a read deck (so `extract … from` can take it).
+ *
+ * @param value - Anything.
+ * @returns Whether it is a {@link DeckDocument}.
+ */
+function isDeckDocument(value) {
+  return typeof value === 'object' && value !== null && value.kind === 'deck' && Array.isArray(value.slides);
+}
+
+/**
+ * Reads a `.pptx` presentation into a deck document, through
+ * `@opencraw/office-reader`: every slide's text boxes with their positions,
+ * its tables with their merged cells, its charts' cached data and its notes.
+ * The reader is imported on first use, so recipes that never read a
+ * presentation never load it.
+ *
+ * @param bytes - The file.
+ * @param source - Where it came from, for messages.
+ * @returns The deck.
+ * @throws Error naming the source, and saying what to do, for a file that is
+ * not a readable presentation (a legacy `.ppt`, a password-protected file, an `.odp`…).
+ */
+async function readPptxDeck(bytes, source) {
+  const {
+    readPptx,
+    OfficeReadError
+  } = await import('@opencraw/office-reader/pptx');
+  try {
+    const deck = await readPptx(bytes);
+    return {
+      kind: 'deck',
+      width: deck.width,
+      height: deck.height,
+      slides: deck.slides.map(slide => ({
+        ...slide,
+        tables: slide.tables.map(table => ({
+          name: table.name,
+          rows: table.rows,
+          merges: table.merges
+        }))
+      }))
+    };
+  } catch (error) {
+    if (error instanceof OfficeReadError) throw new Error(`${source}: ${error.message}`, {
+      cause: error
+    });
+    throw error;
   }
-  return undefined;
 }
 
 /** Runs closer than this share of the font size join into one cell. */
@@ -2128,7 +3229,17 @@ const ROW_OVERLAP = 0.4;
  * @returns The rows.
  */
 function assembleRows(runs) {
-  const cells = joinCells(runs);
+  return rowsOfCells(joinCells(runs));
+}
+/**
+ * Groups finished cells into rows, top to bottom: cells whose vertical extents
+ * overlap share a row. For cells that need no joining, such as a slide's text
+ * boxes, each already a cell.
+ *
+ * @param cells - The cells, in any order.
+ * @returns The rows.
+ */
+function rowsOfCells(cells) {
   const ordered = [...cells].sort((a, b) => middle(b) - middle(a) || a.x - b.x);
   const rows = [];
   let top = 0;
@@ -2305,7 +3416,7 @@ function isPdfDocument(value) {
 function findTables(document, query) {
   const tables = [];
   for (const page of document.pages) {
-    const starts = page.rows.flatMap((row, index) => query.header.test(plain(row)) ? [index] : []);
+    const starts = page.rows.flatMap((row, index) => query.header.test(plain$1(row)) ? [index] : []);
     for (const [position, start] of starts.entries()) {
       const body = bodyOf(page.rows.slice(start + 1, starts[position + 1] ?? page.rows.length), query.until);
       tables.push(readTable(page.number, page.rows[start], body, query));
@@ -2315,7 +3426,7 @@ function findTables(document, query) {
 }
 /** The rows under a header, up to the first one `until` matches. */
 function bodyOf(rows, until) {
-  const end = until === undefined ? -1 : rows.findIndex(row => until.test(plain(row)));
+  const end = until === undefined ? -1 : rows.findIndex(row => until.test(plain$1(row)));
   return end === -1 ? [...rows] : rows.slice(0, end);
 }
 function readTable(page, headerRow, body, query) {
@@ -2330,7 +3441,7 @@ function readTable(page, headerRow, body, query) {
     page,
     title: headers[0]?.text ?? '',
     header: headers.map(header => header.text),
-    rows: groups.map(group => named(joinLines(group, headers.length), headers, query.columns))
+    rows: groups.map(group => named$1(joinLines(group, headers.length), headers, query.columns))
   };
 }
 /**
@@ -2498,53 +3609,585 @@ function valuesOf(row, bands, width) {
   }
   return values;
 }
-function named(values, headers, columns) {
-  if (columns === undefined) return Object.fromEntries(headers.map((header, index) => [header.text, values[index]]));
-  const record = {};
-  for (const [key, pattern] of Object.entries(columns)) {
-    const index = headers.findIndex(header => pattern.test(header.text));
-    if (index !== -1) record[key] = values[index];
-  }
-  return record;
+function named$1(values, headers, columns) {
+  if (columns === undefined) return Object.fromEntries(headers.map((header, index) => [header.text, values[index]]));
+  const record = {};
+  for (const [key, pattern] of Object.entries(columns)) {
+    const index = headers.findIndex(header => pattern.test(header.text));
+    if (index !== -1) record[key] = values[index];
+  }
+  return record;
+}
+/** Distances closer than this, in points, are a tie. */
+const TIE = 1;
+/**
+ * The anchor a line belongs to: the nearest by vertical gap. On a tie (evenly
+ * spaced lines) the anchor below wins: text reads top down, so a wrapped
+ * cell's first line comes before the row it belongs to.
+ */
+function nearest(line, candidates) {
+  const row = line.row;
+  const gap = candidate => Math.max(0, candidate.bottom - row.top, row.bottom - candidate.top);
+  const [first, ...rest] = candidates;
+  if (first === undefined) throw new Error('no row to attach a line to');
+  let best = first;
+  for (const candidate of rest) {
+    const difference = gap(candidate.row) - gap(best.row);
+    if (difference < -TIE || Math.abs(difference) <= TIE && candidate.row.bottom < best.row.bottom) best = candidate;
+  }
+  return best;
+}
+function overlapOf(header, band) {
+  return Math.max(0, Math.min(header.x + header.width, band.end) - Math.max(header.x, band.start));
+}
+function plain$1(row) {
+  return row.cells.map(cell => cell.text).join(' ');
+}
+function joinText(first, second) {
+  return first === '' ? second : second === '' ? first : `${first} ${second}`;
+}
+function median(values) {
+  const ordered = [...values].sort((a, b) => a - b);
+  return ordered[Math.floor(ordered.length / 2)] ?? 0;
+}
+
+/**
+ * The text a `regex` extract reads: the visible rows of the visible sheets,
+ * cells separated by a tab, sheets separated by a blank line.
+ *
+ * @param document - The workbook.
+ * @returns The text.
+ */
+function workbookText(document) {
+  return document.sheets.filter(sheet => sheet.hidden !== true).map(sheet => visibleRows(sheet).map(row => row.map(String).join('\t')).join('\n')).join('\n\n');
+}
+/**
+ * Whether a value bound in scope is a read workbook (so `extract … from` can take it).
+ *
+ * @param value - Anything.
+ * @returns Whether it is a {@link WorkbookDocument}.
+ */
+function isWorkbookDocument(value) {
+  return typeof value === 'object' && value !== null && value.kind === 'workbook' && Array.isArray(value.sheets);
+}
+function visibleRows(sheet) {
+  if (sheet.hiddenRows === undefined || sheet.hiddenRows.length === 0) return sheet.rows;
+  const hidden = new Set(sheet.hiddenRows);
+  return sheet.rows.filter((_row, index) => !hidden.has(index));
+}
+
+/** The delimiters detection chooses between, in order of preference on a tie. */
+const CSV_DELIMITERS = [',', ';', '\t', '|'];
+/** How much of a file delimiter detection looks at. */
+const SAMPLE_CHARS = 64 * 1024;
+/** How many lines of the sample delimiter detection scores. */
+const SAMPLE_LINES = 100;
+/**
+ * Parses CSV text (RFC 4180, tolerant): a field in double quotes may hold the
+ * delimiter, line breaks and `""` for a quote; a quote inside an unquoted
+ * field is taken literally (`1.0 Hybrid "Cross"`); CRLF, LF and CR all end a
+ * record. Rows are kept as read: ragged rows stay ragged, nothing is trimmed.
+ *
+ * @param text - The decoded file.
+ * @param delimiter - One character.
+ * @returns The rows; a trailing empty line adds no row.
+ */
+function parseCsv(text, delimiter) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let index = 0;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '"' && field === '') {
+      const quoted = readQuoted(text, index + 1);
+      field = quoted.value;
+      index = quoted.next;
+    } else if (char === delimiter) {
+      row.push(field);
+      field = '';
+      index += 1;
+    } else if (char === '\n' || char === '\r') {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = '';
+      index += char === '\r' && text[index + 1] === '\n' ? 2 : 1;
+    } else {
+      const end = plainEnd(text, index + 1, delimiter);
+      field += text.slice(index, end);
+      index = end;
+    }
+  }
+  if (field !== '' || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+/**
+ * Chooses the delimiter of a CSV: the candidate whose field count (above one)
+ * is the most consistent over the first lines, so a title line or two above
+ * the header does not mislead it. A file of one column gets `,`.
+ *
+ * `;` with decimal commas (`Panda;15.950,00`), the usual European export,
+ * scores `;`: a comma split gives rows of uneven width.
+ *
+ * @param text - The decoded file.
+ * @returns The delimiter.
+ */
+function detectDelimiter(text) {
+  const sample = text.slice(0, SAMPLE_CHARS);
+  const truncated = text.length > SAMPLE_CHARS;
+  let best = {
+    delimiter: ',',
+    score: 0
+  };
+  for (const delimiter of CSV_DELIMITERS) {
+    const rows = parseCsv(sample, delimiter).slice(0, SAMPLE_LINES).filter(row => row.length > 1 || row[0] !== '');
+    // The sample may cut the last line short.
+    if (truncated && rows.length > 1) rows.pop();
+    const score = consistency(rows);
+    if (score > best.score) best = {
+      delimiter,
+      score
+    };
+  }
+  return best.delimiter;
+}
+/** The share of rows with the most common width above one, with that width breaking ties; 0 when no row splits. */
+function consistency(rows) {
+  const counts = new Map();
+  for (const row of rows) counts.set(row.length, (counts.get(row.length) ?? 0) + 1);
+  let width = 1;
+  let agreeing = 0;
+  for (const [length, count] of counts) {
+    if (!(length > 1 && (count > agreeing || count === agreeing && length > width))) {
+      continue;
+    }
+    width = length;
+    agreeing = count;
+  }
+  return width > 1 ? agreeing / rows.length * 1000 + width : 0;
+}
+/** Reads a quoted field starting after its opening quote. */
+function readQuoted(text, start) {
+  let value = '';
+  let index = start;
+  for (;;) {
+    const quote = text.indexOf('"', index);
+    if (quote === -1) return {
+      value: value + text.slice(index),
+      next: text.length
+    };
+    value += text.slice(index, quote);
+    if (text[quote + 1] !== '"') return {
+      value,
+      next: quote + 1
+    };
+    value += '"';
+    index = quote + 2;
+  }
+}
+/** Where a run of plain characters (no delimiter, no line break) ends. */
+function plainEnd(text, start, delimiter) {
+  const stops = new Set([delimiter, '\n', '\r']);
+  let index = start;
+  while (index < text.length) {
+    if (stops.has(text[index])) break;
+    index += 1;
+  }
+  return index;
+}
+
+/**
+ * Reads decoded CSV text into a workbook of one sheet, named after the file.
+ *
+ * @param text - The decoded file.
+ * @param options - The sheet name, the encoding it was decoded from (for a
+ * probe to report) and a delimiter; without one it is detected.
+ * @returns The workbook.
+ * @throws Error when the delimiter given is not one character.
+ */
+function csvWorkbook(text, options) {
+  if (options.delimiter !== undefined && [...options.delimiter].length !== 1) throw new Error(`a CSV delimiter is one character; got "${options.delimiter}"`);
+  const delimiter = options.delimiter ?? detectDelimiter(text);
+  return {
+    kind: 'workbook',
+    sheets: [{
+      name: options.name,
+      rows: parseCsv(text, delimiter)
+    }],
+    csv: {
+      encoding: options.encoding,
+      delimiter
+    }
+  };
+}
+/**
+ * The name a CSV's sheet takes: the file name without its extension
+ * (`…/prezzo_alle_8.csv` → `prezzo_alle_8`), else `csv`.
+ *
+ * @param url - Where the file came from.
+ * @returns The name.
+ */
+function sheetNameOf(url) {
+  let path;
+  try {
+    path = new URL(url).pathname;
+  } catch {
+    path = url;
+  }
+  const file = path.split('/').at(-1) ?? '';
+  let name;
+  try {
+    name = decodeURIComponent(file);
+  } catch {
+    name = file;
+  }
+  name = name.replace(/\.[^.]*$/, '');
+  return name === '' ? 'csv' : name;
+}
+
+/**
+ * Reads an `.xlsx` workbook into a workbook document, through
+ * `@opencraw/office-reader`: every worksheet's cells, with hidden sheets,
+ * hidden rows and merged ranges. Numbers and booleans keep their type (a
+ * cell's `13955.625` is unambiguous; as text, a locale guess could read it as
+ * thirteen million), dates become ISO text, errors their text, empty cells
+ * `''`. Formulas give their cached value. The reader is imported on first use,
+ * so recipes that never read a spreadsheet never load it.
+ *
+ * @param bytes - The file.
+ * @param source - Where it came from, for messages.
+ * @returns The workbook.
+ * @throws Error naming the source, and saying what to do, for a file that is
+ * not a readable workbook (a legacy `.xls`, a password-protected file, an `.ods`…).
+ */
+async function readXlsxWorkbook(bytes, source) {
+  const {
+    readXlsx,
+    OfficeReadError
+  } = await import('@opencraw/office-reader/xlsx');
+  try {
+    const book = await readXlsx(bytes);
+    return {
+      kind: 'workbook',
+      sheets: book.sheets.map(sheet => ({
+        name: sheet.name,
+        rows: sheet.rows.map(row => row.map(cell => workbookCell(cell))),
+        hidden: sheet.hidden,
+        hiddenRows: sheet.hiddenRows,
+        merges: sheet.merges
+      }))
+    };
+  } catch (error) {
+    if (error instanceof OfficeReadError) throw new Error(`${source}: ${error.message}`, {
+      cause: error
+    });
+    throw error;
+  }
+}
+/** A typed spreadsheet value as a workbook cell. */
+function workbookCell(value) {
+  if (value === null) return '';
+  if (value instanceof Date) return isoText(value);
+  if (typeof value === 'object') return value.error;
+  return value;
+}
+/** A date as ISO text: the day alone at midnight, the time alone for a time of day (Excel's day zero, 1899), both otherwise. */
+function isoText(date) {
+  const iso = date.toISOString();
+  if (date.getUTCFullYear() < 1900) return iso.slice(11, 19);
+  return iso.slice(11, 19) === '00:00:00' ? iso.slice(0, 10) : iso.slice(0, 19);
+}
+
+/**
+ * Finds every table whose header row matches, in every sheet the query
+ * selects, and reads its rows by column. Unlike a PDF, a grid needs no
+ * geometry: column *i* of a row belongs to header *i*.
+ *
+ * Merged ranges are filled first (the file stores their value in the top-left
+ * cell only), so a brand merged down its models' rows reads on every row, and
+ * a group header merged across its sub-columns names each of them. Empty rows
+ * are skipped.
+ *
+ * @param document - The workbook.
+ * @param query - Which tables, and how to name their columns.
+ * @returns The tables, sheet by sheet, top to bottom.
+ */
+function findGridTables(document, query) {
+  const tables = [];
+  for (const sheet of document.sheets) {
+    if (sheet.hidden === true && query.includeHidden !== true) continue;
+    if (query.sheet !== undefined && !query.sheet.test(sheet.name)) continue;
+    tables.push(...sheetTables(sheet, query));
+  }
+  return tables;
+}
+/**
+ * Fills blank cells in the given columns with the value of the row above,
+ * within one table: pivot exports write a group's name on its first row only.
+ *
+ * @param rows - The table's rows, in order.
+ * @param keys - The columns to fill.
+ * @returns The rows, filled (new objects; the input is not changed).
+ */
+function fillDown(rows, keys) {
+  const last = new Map();
+  return rows.map(row => {
+    const filled = {
+      ...row
+    };
+    for (const key of keys) {
+      const value = filled[key];
+      if (value === undefined || value === '') {
+        const above = last.get(key);
+        if (above !== undefined) filled[key] = above;
+      } else {
+        last.set(key, value);
+      }
+    }
+    return filled;
+  });
+}
+function sheetTables(sheet, query) {
+  const hidden = new Set(query.includeHidden === true ? [] : sheet.hiddenRows);
+  const visible = sheet.rows.flatMap((_row, index) => hidden.has(index) ? [] : [index]);
+  const grid = filledGrid(sheet);
+  const plainRows = new Map(visible.map(index => [index, plain(sheet.rows[index])]));
+  const starts = visible.filter(index => plainRows.get(index) !== '' && query.header.test(plainRows.get(index) ?? ''));
+  const headerRows = query.headerRows ?? 1;
+  return starts.map((start, position) => {
+    const at = visible.indexOf(start);
+    const headerIndexes = visible.slice(at, at + headerRows);
+    const next = starts[position + 1] ?? Infinity;
+    const body = [];
+    const below = visible.slice(at + headerRows);
+    for (const index of below) {
+      if (index >= next) break;
+      if (query.until?.test(plainRows.get(index) ?? '') === true) break;
+      if (plainRows.get(index) !== '') body.push(index);
+    }
+    const columns = columnsOf(grid, headerIndexes, body);
+    const rows = body.map(index => named(grid[index] ?? [], columns, query.columns));
+    return {
+      sheet: sheet.name,
+      title: sheet.rows[start].map(text => clean(text)).find(text => text !== '') ?? '',
+      header: columns.map(column => column.key),
+      rows: query.fillDown === undefined ? rows : fillDown(rows, query.fillDown)
+    };
+  });
+}
+/**
+ * The table's columns: each column's key joins the distinct texts its header
+ * rows hold (`Insgesamt` over `August 2026` gives `Insgesamt August 2026`). A
+ * column with no header text but data below is keyed by its letter (`A`); one
+ * with neither is dropped. A key seen before gets a counter (`Price 2`).
+ */
+function columnsOf(grid, headerIndexes, body) {
+  const width = Math.max(0, ...[...headerIndexes, ...body].map(index => grid[index]?.length ?? 0));
+  const seen = new Map();
+  const columns = [];
+  for (let index = 0; index < width; index += 1) {
+    const parts = [];
+    for (const row of headerIndexes) {
+      const text = clean(grid[row]?.[index] ?? '');
+      if (text !== '' && !parts.includes(text)) parts.push(text);
+    }
+    const hasData = body.some(row => clean(grid[row]?.[index] ?? '') !== '');
+    if (!hasData && parts.length === 0) continue;
+    const base = parts.length === 0 ? columnLetter(index) : parts.join(' ');
+    const count = (seen.get(base) ?? 0) + 1;
+    seen.set(base, count);
+    columns.push({
+      index,
+      key: count === 1 ? base : `${base} ${count}`
+    });
+  }
+  return columns;
+}
+function named(row, columns, patterns) {
+  const value = column => {
+    const cell = row[column.index] ?? '';
+    return typeof cell === 'string' ? cell.trim() : cell;
+  };
+  if (patterns === undefined) return Object.fromEntries(columns.map(column => [column.key, value(column)]));
+  const record = {};
+  for (const [key, pattern] of Object.entries(patterns)) {
+    const column = columns.find(candidate => pattern.test(candidate.key));
+    if (column !== undefined) record[key] = value(column);
+  }
+  return record;
+}
+/** The sheet's rows with every merged range's value copied into the cells it covers. */
+function filledGrid(sheet) {
+  if (sheet.merges === undefined || sheet.merges.length === 0) return sheet.rows;
+  const grid = sheet.rows.map(row => [...row]);
+  for (const reference of sheet.merges) {
+    const range = rangeOf(reference);
+    if (range === undefined) continue;
+    const value = sheet.rows[range.top]?.[range.left] ?? '';
+    for (let row = range.top; row <= range.bottom; row += 1) {
+      grid[row] ??= [];
+      for (let column = range.left; column <= range.right; column += 1) grid[row][column] = value;
+    }
+  }
+  return grid;
+}
+/** `B10:B13` as 0-based bounds; `undefined` for anything else. */
+function rangeOf(reference) {
+  const [from, to = from] = reference.split(':', 2);
+  const start = cellOf(from);
+  const end = cellOf(to);
+  if (start === undefined || end === undefined) return undefined;
+  return {
+    top: Math.min(start.row, end.row),
+    left: Math.min(start.column, end.column),
+    bottom: Math.max(start.row, end.row),
+    right: Math.max(start.column, end.column)
+  };
+}
+function cellOf(reference) {
+  const match = /^\$?([A-Z]+)\$?(\d+)$/i.exec(reference.trim());
+  if (match === null) return undefined;
+  const letters = match[1].toUpperCase();
+  let column = 0;
+  for (const char of letters) column = column * 26 + (char.codePointAt(0) ?? 64) - 64;
+  return {
+    row: Number(match[2]) - 1,
+    column: column - 1
+  };
+}
+/** `0` → `A`, `25` → `Z`, `26` → `AA`. */
+function columnLetter(index) {
+  let letters = '';
+  for (let rest = index + 1; rest > 0; rest = Math.floor((rest - 1) / 26)) letters = String.fromCodePoint(65 + (rest - 1) % 26) + letters;
+  return letters;
 }
-/** Distances closer than this, in points, are a tie. */
-const TIE = 1;
+/** A row as a header pattern sees it: its non-empty cells, whitespace collapsed, joined by spaces. */
+function plain(row) {
+  return (row ?? []).map(text => clean(text)).filter(text => text !== '').join(' ');
+}
+function clean(cell) {
+  return String(cell).replaceAll(/\s+/g, ' ').trim();
+}
+
 /**
- * The anchor a line belongs to: the nearest by vertical gap. On a tie (evenly
- * spaced lines) the anchor below wins: text reads top down, so a wrapped
- * cell's first line comes before the row it belongs to.
+ * Every `<table>` of an HTML document as a sheet (`table 1`, `table 2`…, in
+ * document order), so the workbook table reader works on web pages and
+ * rendered Markdown: rows in order (`thead`, `tbody`, `tfoot` alike), `th` and
+ * `td` alike, cell text with whitespace collapsed, `colspan` and `rowspan` as
+ * merged ranges. A table inside a table is a sheet of its own, and its rows
+ * are not its parent's.
+ *
+ * @param html - The document.
+ * @returns The tables.
  */
-function nearest(line, candidates) {
-  const row = line.row;
-  const gap = candidate => Math.max(0, candidate.bottom - row.top, row.bottom - candidate.top);
-  const [first, ...rest] = candidates;
-  if (first === undefined) throw new Error('no row to attach a line to');
-  let best = first;
-  for (const candidate of rest) {
-    const difference = gap(candidate.row) - gap(best.row);
-    if (difference < -TIE || Math.abs(difference) <= TIE && candidate.row.bottom < best.row.bottom) best = candidate;
-  }
-  return best;
-}
-function overlapOf(header, band) {
-  return Math.max(0, Math.min(header.x + header.width, band.end) - Math.max(header.x, band.start));
+function htmlTableSheets(html) {
+  const $ = load(html);
+  const tables = $('table').get();
+  return tables.map((table, index) => {
+    const all = $(table).find('tr').get();
+    const rows = all.filter(row => $(row).closest('table').get(0) === table);
+    const grid = [];
+    const merges = [];
+    for (const [rowIndex, row] of rows.entries()) {
+      grid[rowIndex] ??= [];
+      let column = 0;
+      const cells = $(row).children('th, td').get();
+      for (const cell of cells) {
+        while (grid[rowIndex][column] !== undefined) column += 1;
+        const columnSpan = span($(cell).attr('colspan'));
+        const rowSpan = span($(cell).attr('rowspan'));
+        for (let down = 0; down < rowSpan; down += 1) {
+          grid[rowIndex + down] ??= [];
+          for (let across = 0; across < columnSpan; across += 1) grid[rowIndex + down][column + across] = '';
+        }
+        grid[rowIndex][column] = $(cell).text().replaceAll(/\s+/g, ' ').trim();
+        if (columnSpan > 1 || rowSpan > 1) merges.push(`${letter(column)}${rowIndex + 1}:${letter(column + columnSpan - 1)}${rowIndex + rowSpan}`);
+        column += columnSpan;
+      }
+    }
+    return {
+      name: `table ${index + 1}`,
+      rows: grid.slice(0, rows.length).map(row => Array.from(row, cell => cell ?? '')),
+      merges
+    };
+  });
 }
-function plain(row) {
-  return row.cells.map(cell => cell.text).join(' ');
+function span(value) {
+  const number = Math.trunc(Number(value ?? '1'));
+  return Number.isFinite(number) && number > 0 ? Math.min(number, 1000) : 1;
 }
-function joinText(first, second) {
-  return first === '' ? second : second === '' ? first : `${first} ${second}`;
+function letter(index) {
+  let letters = '';
+  for (let rest = index + 1; rest > 0; rest = Math.floor((rest - 1) / 26)) letters = String.fromCodePoint(65 + (rest - 1) % 26) + letters;
+  return letters;
 }
-function median(values) {
-  const ordered = [...values].sort((a, b) => a - b);
-  return ordered[Math.floor(ordered.length / 2)] ?? 0;
+
+/**
+ * Finds tables in a deck: native tables through the workbook table reader
+ * (merged cells filled, a header over several rows joined), or, with
+ * `shapes`, text boxes laid out as a table through the PDF table reader (a box
+ * is a cell, boxes whose heights overlap a row, columns from where the body's
+ * boxes start). Hidden slides are skipped unless `includeHidden`.
+ *
+ * @param document - The deck.
+ * @param query - Which tables, on which slides, and how to name their columns.
+ * @returns The tables, slide by slide.
+ */
+function findDeckTables(document, query) {
+  const slides = document.slides.filter(slide => (query.includeHidden === true || !slide.hidden) && (query.slide === undefined || query.slide.test(slide.title ?? '')));
+  if (query.shapes === true) return shapeTables(document, slides, query);
+  return slides.flatMap(slide => findGridTables({
+    sheets: slide.tables
+  }, query).map(table => ({
+    slide: slide.number,
+    slideTitle: slide.title ?? '',
+    title: table.title,
+    header: table.header,
+    rows: table.rows
+  })));
+}
+/** Text boxes as a PDF of one page per slide, y flipped (PDF counts from the bottom), each box one cell. */
+function shapeTables(document, slides, query) {
+  const pdf = {
+    pages: slides.map(slide => ({
+      number: slide.number,
+      width: document.width,
+      height: document.height,
+      rows: rowsOfCells(slide.shapes.map(shape => ({
+        x: shape.x,
+        y: document.height - shape.y - shape.height,
+        width: shape.width,
+        height: shape.height,
+        text: shape.text.replaceAll(/\s+/g, ' ').trim()
+      })))
+    }))
+  };
+  const titles = new Map(slides.map(slide => [slide.number, slide.title ?? '']));
+  return findTables(pdf, {
+    header: query.header,
+    until: query.until,
+    columns: query.columns,
+    align: query.align
+  }).map(table => ({
+    slide: table.page,
+    slideTitle: titles.get(table.page) ?? '',
+    title: table.title,
+    header: table.header,
+    rows: query.fillDown === undefined ? table.rows : fillDown(table.rows, query.fillDown)
+  }));
 }
 
 /**
  * Runs an `extract` step against a static document: the value bound under
  * `from`, else the scope's current document. `css` reads HTML, `jsonpath`
- * reads JSON (or a read PDF's rows), `table` reads a PDF's tables, `regex`
- * reads any document as text; `xpath` needs a live page and is refused here.
+ * reads JSON (or a read PDF, workbook or deck as data), `table` reads the
+ * tables of a PDF, a workbook (a spreadsheet, a CSV), a deck (a presentation)
+ * or HTML (its `<table>`s), `regex` reads any document as text; `xpath` needs
+ * a live page and is refused here.
  *
  * A `jsonpath` extract whose `from` is text parses that text as JSON, and a
  * list of texts (every `<script type="application/ld+json">` of a page) becomes
@@ -2563,19 +4206,18 @@ function extractFromDocument(step, scope) {
   switch (step.kind) {
     case 'jsonpath':
       {
-        if (document.kind !== 'json' && document.kind !== 'pdf') throw new Error(`jsonpath needs a JSON document; the current document is ${document.kind}`);
-        values = selectJson(document.kind === 'pdf' ? document : document.data, selector).map(node => takeFromJson(node, take));
+        if (document.kind === 'html' || document.kind === 'text') throw new Error(`jsonpath needs a JSON document; the current document is ${document.kind}`);
+        values = selectJson(document.kind === 'json' ? document.data : document, selector).map(node => takeFromJson(node, take));
         break;
       }
     case 'table':
       {
-        if (document.kind !== 'pdf') throw new Error(`table reads a PDF; the current document is ${document.kind} (request it with "as": "pdf")`);
-        values = findTables(document, tableQuery(step, selector));
+        values = readTables(document, step, selector);
         break;
       }
     case 'css':
       {
-        if (document.kind !== 'html') throw new Error(`css needs an HTML document; the current document is ${document.kind}`);
+        if (document.kind !== 'html') throw new Error(`css needs an HTML document; the current document is ${document.kind}${['workbook', 'pdf', 'deck'].includes(document.kind) ? ' (read it with kind "table", "regex" or "jsonpath")' : ''}`);
         values = selectHtml(document.html, selector).map(match => takeFromHtml(match, take));
         break;
       }
@@ -2607,20 +4249,82 @@ function extractFromDocument(step, scope) {
 function renderSelector(selector, scope) {
   return hasPlaceholder(selector) ? renderText(selector, path => scope.lookup(path)) : selector;
 }
+/**
+ * The tables a `table` extract finds in a document: a PDF's, a workbook's, a
+ * deck's, or an HTML document's `<table>`s (a fetched page, rendered Markdown,
+ * a live page's content).
+ *
+ * @param document - The document.
+ * @param step - The extract step.
+ * @param scope - Where its selector renders.
+ * @returns The tables.
+ */
+function tablesIn(document, step, scope) {
+  return readTables(document, step, renderSelector(step.selector, scope));
+}
+function readTables(document, step, selector) {
+  const query = tableQuery(step, selector);
+  if (document.kind === 'html') {
+    refuseOptions(step, ['sheet', 'slide', 'shapes'], 'workbooks and decks', 'HTML');
+    return findGridTables({
+      sheets: htmlTableSheets(document.html)
+    }, {
+      ...query,
+      headerRows: step.headerRows,
+      fillDown: step.fillDown
+    });
+  }
+  if (document.kind === 'workbook') {
+    refuseOptions(step, ['slide', 'shapes'], 'decks (presentations)', 'a workbook');
+    return findGridTables(document, {
+      ...query,
+      sheet: optionalPattern(step.sheet, 'sheet'),
+      headerRows: step.headerRows,
+      fillDown: step.fillDown,
+      includeHidden: step.includeHidden
+    });
+  }
+  if (document.kind === 'deck') {
+    refuseOptions(step, ['sheet'], 'workbooks (spreadsheets, CSV)', 'a deck');
+    return findDeckTables(document, {
+      ...query,
+      slide: optionalPattern(step.slide, 'slide'),
+      shapes: step.shapes,
+      headerRows: step.headerRows,
+      fillDown: step.fillDown,
+      includeHidden: step.includeHidden
+    });
+  }
+  if (document.kind !== 'pdf') throw new Error(`table reads a PDF, a workbook (a spreadsheet, a CSV), a deck (a presentation) or HTML tables; the current document is ${document.kind} (request it with "as": "pdf", "csv", "xlsx", "pptx" or "html")`);
+  refuseOptions(step, ['sheet', 'headerRows', 'includeHidden', 'slide', 'shapes'], 'workbooks and decks', 'a PDF');
+  const tables = findTables(document, query);
+  return step.fillDown === undefined ? tables : tables.map(table => ({
+    ...table,
+    rows: fillDown(table.rows, step.fillDown ?? [])
+  }));
+}
 /**
  * A table extract's query: the selector matches the header row, the other
- * patterns come from the step; all case-insensitive, since PDFs capitalise
- * headings freely.
+ * patterns come from the step; all case-insensitive, since PDFs and
+ * spreadsheets capitalise headings freely.
  */
 function tableQuery(step, selector) {
   const columns = step.columns === undefined ? undefined : Object.fromEntries(Object.entries(step.columns).map(([key, pattern]) => [key, patternOf(pattern, `columns.${key}`)]));
   return {
     header: patternOf(selector, 'selector'),
-    until: step.until === undefined ? undefined : patternOf(step.until, 'until'),
+    until: optionalPattern(step.until, 'until'),
     columns,
     align: step.align
   };
 }
+function refuseOptions(step, options, reads, current) {
+  for (const option of options) {
+    if (step[option] !== undefined) throw new Error(`"${option}" reads ${reads}; the current document is ${current}`);
+  }
+}
+function optionalPattern(source, where) {
+  return source === undefined ? undefined : patternOf(source, where);
+}
 function patternOf(source, where) {
   try {
     return new RegExp(source, 'i');
@@ -2630,11 +4334,13 @@ function patternOf(source, where) {
     });
   }
 }
-/** The text a regex extract reads: markup, text, a PDF's rows, or JSON re-serialised (a list of texts joined by newlines). */
+/** The text a regex extract reads: markup, text, a PDF's or a workbook's rows, or JSON re-serialised (a list of texts joined by newlines). */
 function textOf$1(document) {
   if (document.kind === 'html') return document.html;
   if (document.kind === 'text') return document.text;
   if (document.kind === 'pdf') return pdfText(document);
+  if (document.kind === 'workbook') return workbookText(document);
+  if (document.kind === 'deck') return deckText(document);
   if (Array.isArray(document.data) && document.data.every(entry => typeof entry === 'string')) return document.data.join('\n');
   return typeof document.data === 'string' ? document.data : JSON.stringify(document.data);
 }
@@ -2646,8 +4352,8 @@ function documentFor(step, scope) {
   }
   const source = scope.get(step.from);
   if (source === undefined) throw new Error(`"${step.from}" is not bound`);
-  if (isPdfDocument(source)) return source;
-  if (step.kind === 'table') throw new Error(`"${step.from}" is not a PDF; request it with "as": "pdf"`);
+  if (isPdfDocument(source) || isWorkbookDocument(source) || isDeckDocument(source)) return source;
+  if (step.kind === 'table') throw new Error(`"${step.from}" is not a PDF, a workbook or a deck; request it with "as": "pdf", "csv", "xlsx" or "pptx"`);
   if (step.kind === 'regex') {
     if (typeof source === 'string') return {
       kind: 'text',
@@ -2683,6 +4389,135 @@ function documentFor(step, scope) {
   };
 }
 
+/** Aliases one document may expand: a "billion laughs" document needs far more. */
+const MAX_ALIASES = 100;
+/**
+ * Parses YAML with the `yaml` package, imported on first use. The version is
+ * pinned to YAML 1.2 (core schema) whatever the document declares: under a
+ * `%YAML 1.1` directive, `NO` would read as `false` and `0123` as octal `83`.
+ * Merge keys (`<<: *base`) are applied, duplicate keys are an error, aliases
+ * are capped, and custom tags never build values: nothing in the text runs.
+ *
+ * @param text - The YAML.
+ * @param source - Where it came from, for messages.
+ * @param scalars - `typed` (default), or `text` to keep every scalar as written (`0123` stays `"0123"`).
+ * @returns The data, the number of documents and the warnings.
+ * @throws Error naming the source, with the line and column, for YAML that does not parse.
+ */
+async function readYaml(text, source, scalars = 'typed') {
+  const {
+    parseAllDocuments
+  } = await import('yaml');
+  const parsed = parseAllDocuments(text, {
+    version: '1.2',
+    schema: scalars === 'text' ? 'failsafe' : 'core',
+    merge: true,
+    uniqueKeys: true,
+    prettyErrors: true
+  });
+  const documents = Array.isArray(parsed) ? parsed : [parsed];
+  const warnings = [];
+  const values = [];
+  for (const document of documents) {
+    const [error] = document.errors;
+    if (error !== undefined) throw new Error(`${source}: not YAML (${error.message.split('\n', 1)[0]})`, {
+      cause: error
+    });
+    warnings.push(...document.warnings.map(warning => warning.message.split('\n', 1)[0]));
+    try {
+      values.push(document.toJS({
+        maxAliasCount: MAX_ALIASES
+      }));
+    } catch (error) {
+      throw new Error(`${source}: ${error.message}`, {
+        cause: error
+      });
+    }
+  }
+  return {
+    data: values.length === 1 ? values[0] : values,
+    documents: values.length,
+    warnings
+  };
+}
+
+/** A leading `---` block of YAML. */
+const FRONT_MATTER = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/**
+ * Renders Markdown (GitHub-flavoured: tables, task lists, strikethrough,
+ * autolinks) to HTML with `marked`, imported on first use, so every `css`
+ * selector works on it:
+ *
+ * - each heading and everything up to the next heading of the same or a higher
+ *   level is wrapped in `<section data-heading="…" data-level="…">`, sections
+ *   nesting, so "the table under *Prezzi*" is one selector;
+ * - headings get slug ids (`<h2 id="prezzi">`);
+ * - a leading `---` YAML block is parsed (YAML 1.2, as `as: "yaml"` reads it)
+ *   and put in the head as `<script type="application/json" data-front-matter>`.
+ *
+ * Raw HTML in the Markdown is kept: it is data, parsed by cheerio, never run.
+ *
+ * @param text - The Markdown.
+ * @param source - Where it came from, for messages.
+ * @returns The HTML, the front matter's data and the YAML parser's warnings.
+ * @throws Error naming the source when the front matter is not YAML.
+ */
+async function readMarkdown(text, source) {
+  const matter = FRONT_MATTER.exec(text);
+  const body = matter === null ? text : text.slice(matter[0].length);
+  const front = matter === null ? undefined : await readYaml(matter[1], `${source} front matter`);
+  const {
+    marked
+  } = await import('marked');
+  const rendered = marked.parse(body, {
+    gfm: true,
+    async: false
+  });
+  const sections = sectioned(rendered);
+  const head = front === undefined ? '' : `<script type="application/json" data-front-matter>${JSON.stringify(front.data ?? null).replaceAll('<', '<')}</script>`;
+  return {
+    html: `<!doctype html><html><head>${head}</head><body>${sections}</body></html>`,
+    frontMatter: front?.data,
+    warnings: front?.warnings ?? []
+  };
+}
+/** Wraps each heading and what follows it, up to the next heading of the same or a higher level, in a section. */
+function sectioned(html) {
+  const $ = load(html, null, false);
+  const open = [];
+  const used = new Map();
+  let out = '';
+  const nodes = $.root().contents().toArray();
+  for (const node of nodes) {
+    const level = node.type === 'tag' ? /^h([1-6])$/.exec(node.name)?.[1] : undefined;
+    if (level === undefined) {
+      out += $.html(node);
+      continue;
+    }
+    const depth = Number(level);
+    while (open.length > 0 && (open.at(-1) ?? 0) >= depth) {
+      open.pop();
+      out += '</section>';
+    }
+    const heading = $(node);
+    const text = heading.text().replaceAll(/\s+/g, ' ').trim();
+    heading.attr('id', uniqueSlug(text, used));
+    out += `<section data-heading="${escapeAttribute(text)}" data-level="${depth}">${$.html(node)}`;
+    open.push(depth);
+  }
+  return out + '</section>'.repeat(open.length);
+}
+/** GitHub's heading ids: lower case, spaces to hyphens, punctuation dropped, a counter for repeats. */
+function uniqueSlug(text, used) {
+  const slug = text.toLowerCase().replaceAll(/[^\p{L}\p{N}\s-]/gu, '').trim().replaceAll(/\s/g, '-');
+  const count = used.get(slug) ?? 0;
+  used.set(slug, count + 1);
+  return count === 0 ? slug : `${slug}-${count}`;
+}
+function escapeAttribute(text) {
+  return text.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;');
+}
+
 /** A response with a 4xx or 5xx status. */
 class HttpError extends Error {
   status;
@@ -2699,6 +4534,82 @@ class HttpError extends Error {
   }
 }
 
+/**
+ * Decodes a body, in this order: a byte-order mark (UTF-8, UTF-16 LE/BE; Excel's
+ * "Unicode text" export is UTF-16 LE), the encoding a recipe asks for, the
+ * charset the server declares, strict UTF-8, and Windows-1252 (a superset of
+ * Latin-1) for text that is not UTF-8.
+ *
+ * The Windows-1252 fallback is only taken when the text holds no valid UTF-8
+ * beyond ASCII: a UTF-8 page with one stray byte keeps its accents, with a
+ * replacement character for the stray byte, instead of turning every accent
+ * into mojibake.
+ *
+ * @param bytes - The body.
+ * @param options - `encoding`: the recipe's choice, a WHATWG label (wins over
+ * the charset, not over a BOM); `charset`: from the content type (ignored when
+ * not a known label).
+ * @returns The text, without its BOM, and the encoding used.
+ * @throws Error when `encoding` is not a known label.
+ */
+function decodeText(bytes, options = {}) {
+  const bom = bomOf(bytes);
+  if (bom !== undefined) return decodeWith(new TextDecoder(bom), bytes);
+  if (options.encoding !== undefined) {
+    const decoder = decoderFor(options.encoding);
+    if (decoder === undefined) throw new Error(`"${options.encoding}" is not an encoding this runtime knows (try utf8, windows-1252, iso-8859-15, utf-16le, shift_jis…)`);
+    return decodeWith(decoder, bytes);
+  }
+  const declared = options.charset === undefined ? undefined : decoderFor(options.charset);
+  if (declared !== undefined) return decodeWith(declared, bytes);
+  try {
+    return decodeWith(new TextDecoder('utf-8', {
+      fatal: true
+    }), bytes);
+  } catch {
+    const lenient = decodeWith(new TextDecoder('utf-8'), bytes);
+    return hasNonAsciiText(lenient.text) ? lenient : decodeWith(new TextDecoder('windows-1252'), bytes);
+  }
+}
+/** Decodes, naming the encoding by its canonical WHATWG name (`utf-8`, `windows-1252`, `utf-16le`). */
+function decodeWith(decoder, bytes) {
+  return {
+    text: decoder.decode(bytes),
+    encoding: decoder.encoding
+  };
+}
+/**
+ * The charset a content type declares (`text/csv; charset=ISO-8859-1`).
+ *
+ * @param contentType - The header value.
+ * @returns The charset, or `undefined`.
+ */
+function charsetOf(contentType) {
+  const match = /;\s*charset\s*=\s*"?([^";\s]+)"?/i.exec(contentType);
+  return match?.[1];
+}
+function bomOf(bytes) {
+  if (bytes[0] === 0xEF && bytes[1] === 0xBB && bytes[2] === 0xBF) return 'utf8';
+  if (bytes[0] === 0xFF && bytes[1] === 0xFE) return 'utf-16le';
+  if (bytes[0] === 0xFE && bytes[1] === 0xFF) return 'utf-16be';
+  return undefined;
+}
+/** Whether the text holds a character beyond ASCII other than the replacement character: valid UTF-8 was seen. */
+function hasNonAsciiText(text) {
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code !== 0xFF_FD && code > 0x7F) return true;
+  }
+  return false;
+}
+function decoderFor(label) {
+  try {
+    return new TextDecoder(label.trim());
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * HTTP through Playwright's request context: cookies, redirects and storage
  * state behave exactly as they do in the browser, so a session captured by a
@@ -2738,12 +4649,20 @@ class HttpClient {
       data: httpRequest.body,
       timeout: httpRequest.timeoutMs ?? this.timeoutMs
     });
-    const body = await readBody(response, httpRequest.as);
+    const {
+      body,
+      warnings,
+      format
+    } = await readBody(response, httpRequest);
     const result = {
       status: response.status(),
       url: response.url(),
       headers: response.headers(),
-      body
+      body,
+      format,
+      ...(warnings.length > 0 && {
+        warnings
+      })
     };
     if (response.status() >= 400) throw new HttpError(response.status(), response.url(), body, response.headers());
     return result;
@@ -2756,40 +4675,107 @@ class HttpClient {
     return this.context.dispose();
   }
 }
-async function readBody(response, as) {
-  const kind = as ?? kindFromContentType(response.headers()['content-type'] ?? '');
-  return parseBody(kind, await response.body(), response.url());
+async function readBody(response, httpRequest) {
+  const contentType = response.headers()['content-type'] ?? '';
+  const format = httpRequest.as ?? formatFromContentType(contentType);
+  return parseBody(format, await response.body(), response.url(), {
+    ...httpRequest,
+    charset: charsetOf(contentType)
+  });
 }
 /**
- * A `file:` URL, read from disk: a PDF or JSON a recipe gets from a folder
- * instead of a server. The kind is `as`, else the file extension.
+ * A `file:` URL, read from disk: a PDF, spreadsheet, presentation, CSV, YAML
+ * or JSON a recipe gets from a folder instead of a server. The format is `as`,
+ * else the file extension.
  */
 async function readLocalFile(httpRequest) {
   const path = fileURLToPath(httpRequest.url);
   const bytes = await readFile(path);
+  const {
+    body,
+    warnings,
+    format
+  } = await parseBody(httpRequest.as ?? formatFromExtension(extname(path)), bytes, httpRequest.url, httpRequest);
   return {
     status: 200,
     url: httpRequest.url,
     headers: {},
-    body: await parseBody(httpRequest.as ?? kindFromExtension(extname(path)), bytes, httpRequest.url)
+    body,
+    format,
+    ...(warnings.length > 0 && {
+      warnings
+    })
   };
 }
-async function parseBody(kind, bytes, url) {
-  if (kind === 'pdf') return readPdf(bytes, url);
-  const text = new TextDecoder().decode(bytes);
-  if (kind === 'json') {
-    try {
-      return {
+async function parseBody(format, bytes, url, reading) {
+  if (format === 'yaml') {
+    const {
+      text
+    } = decodeText(bytes, reading);
+    const {
+      data,
+      warnings
+    } = await readYaml(text, url, reading.scalars);
+    return {
+      body: {
         kind: 'json',
-        data: JSON.parse(text)
-      };
-    } catch (error) {
-      throw new Error(`${url}: body is not JSON (${error.message})`, {
-        cause: error
-      });
-    }
+        data
+      },
+      warnings,
+      format
+    };
+  }
+  if (format === 'markdown') {
+    const {
+      text
+    } = decodeText(bytes, reading);
+    const {
+      html,
+      warnings
+    } = await readMarkdown(text, url);
+    return {
+      body: {
+        kind: 'html',
+        html
+      },
+      warnings,
+      format
+    };
+  }
+  return {
+    body: await parseFormat(format, bytes, url, reading),
+    warnings: [],
+    format
+  };
+}
+async function parseFormat(format, bytes, url, reading) {
+  if (format === 'pdf') return readPdf(bytes, url);
+  if (format === 'xlsx') return readXlsxWorkbook(bytes, url);
+  if (format === 'pptx') return readPptxDeck(bytes, url);
+  const {
+    text,
+    encoding
+  } = decodeText(bytes, reading);
+  if (format === 'csv') return csvWorkbook(text, {
+    name: sheetNameOf(url),
+    encoding,
+    delimiter: reading.delimiter
+  });
+  if (format === 'jsonl') return {
+    kind: 'json',
+    data: parseJsonLines(text, url)
+  };
+  if (format === 'json') {
+    const parsed = parseJsonLike(text);
+    if ('error' in parsed) throw new Error(`${url}: body is not JSON (${parsed.error.message})${looksLikeJsonLines(text) ? '; it looks like JSON Lines: read it with "as": "jsonl"' : ''}`, {
+      cause: parsed.error
+    });
+    return {
+      kind: 'json',
+      data: parsed.value
+    };
   }
-  return kind === 'html' ? {
+  return format === 'html' ? {
     kind: 'html',
     html: text
   } : {
@@ -2797,28 +4783,61 @@ async function parseBody(kind, bytes, url) {
     text
   };
 }
-function kindFromContentType(contentType) {
-  const type = contentType.toLowerCase();
+/** Several lines, the first of them JSON on its own. */
+function looksLikeJsonLines(text) {
+  const lines = text.split(/\r?\n/).filter(line => line.trim() !== '');
+  if (lines.length < 2) return false;
+  const first = parseJsonLike(lines[0]);
+  return 'value' in first;
+}
+function formatFromContentType(contentType) {
+  const type = contentType.toLowerCase().split(';', 1)[0].trim();
+  if (CSV_TYPES.has(type)) return 'csv';
+  if (JSON_LINES_TYPES.has(type)) return 'jsonl';
+  // A legacy .xls or .ppt goes to the Office reader too, which says what to do with it.
+  if (type.includes('spreadsheetml') || type.startsWith('application/vnd.ms-excel')) return 'xlsx';
+  if (type.includes('presentationml') || type.startsWith('application/vnd.ms-powerpoint')) return 'pptx';
+  if (YAML_TYPES.has(type)) return 'yaml';
+  if (type === 'text/markdown' || type === 'text/x-markdown') return 'markdown';
   if (type.includes('json')) return 'json';
   if (type.includes('pdf')) return 'pdf';
   if (type.includes('html') || type.includes('xml')) return 'html';
   return 'text';
 }
-function kindFromExtension(extension) {
-  const kinds = {
+const JSON_LINES_TYPES = new Set(['application/x-ndjson', 'application/ndjson', 'application/jsonl', 'application/x-jsonlines', 'application/jsonlines']);
+const YAML_TYPES = new Set(['application/yaml', 'application/x-yaml', 'text/yaml', 'text/x-yaml']);
+const CSV_TYPES = new Set(['text/csv', 'application/csv', 'text/x-csv', 'application/x-csv', 'text/comma-separated-values', 'text/tab-separated-values']);
+function formatFromExtension(extension) {
+  const formats = {
     '.json': 'json',
+    '.jsonl': 'jsonl',
+    '.ndjson': 'jsonl',
     '.pdf': 'pdf',
+    '.csv': 'csv',
+    '.tsv': 'csv',
+    '.xlsx': 'xlsx',
+    '.xlsm': 'xlsx',
+    '.xls': 'xlsx',
+    '.pptx': 'pptx',
+    '.pptm': 'pptx',
+    '.ppsx': 'pptx',
+    '.ppt': 'pptx',
+    '.yaml': 'yaml',
+    '.yml': 'yaml',
+    '.md': 'markdown',
+    '.markdown': 'markdown',
     '.html': 'html',
     '.htm': 'html',
     '.xml': 'html'
   };
-  return kinds[extension.toLowerCase()] ?? 'text';
+  return formats[extension.toLowerCase()] ?? 'text';
 }
 
 /**
  * Sends a `request` step: renders its templates, waits for the gate's throttle,
- * sends, checks the response against the recipe's block rule, then binds it as
- * the scope's current document (and under the step id).
+ * sends (again, after a pause, while it fails in passing: `limits.retry`),
+ * checks the response against the recipe's block rule, then binds it as the
+ * scope's current document (and under the step id).
  *
  * @param step - The request step.
  * @param scope - The scope to render in and bind into.
@@ -2826,22 +4845,34 @@ function kindFromExtension(extension) {
  * @param recipe - The recipe: its limits, block rule and id.
  * @param gate - Spaces request starts by `delayMs`.
  * @param events - Where to report the visit.
- * @throws BlockedError when the response is a block; HttpError for any other 4xx/5xx.
+ * @throws BlockedError when the response is a block, or a captcha page under `session.captcha`; HttpError for any other 4xx/5xx.
  */
 async function sendRequest(step, scope, client, recipe, gate, events) {
   const lookup = path => scope.lookup(path);
   const url = resolveUrl(renderText(step.url, lookup), scope.pageState?.url);
-  await gate.throttle();
+  const request = {
+    method: step.method,
+    url,
+    query: step.query === undefined ? undefined : renderMap(step.query, lookup),
+    headers: step.headers === undefined ? undefined : renderMap(step.headers, lookup),
+    body: renderDeep(step.body, lookup),
+    as: step.as,
+    encoding: step.encoding,
+    delimiter: step.delimiter,
+    scalars: step.scalars,
+    timeoutMs: recipe.limits?.timeoutMs
+  };
+  const rule = resolveRetryRule(recipe.limits?.retry);
   let response;
   try {
-    response = await client.send({
-      method: step.method,
-      url,
-      query: step.query === undefined ? undefined : renderMap(step.query, lookup),
-      headers: step.headers === undefined ? undefined : renderMap(step.headers, lookup),
-      body: renderDeep(step.body, lookup),
-      as: step.as,
-      timeoutMs: recipe.limits?.timeoutMs
+    response = await withTransportRetry(url, {
+      run: () => client.send(request),
+      problem: outcome => 'error' in outcome ? problemOf(outcome.error, rule.statuses) : undefined
+    }, {
+      recipeId: recipe.id,
+      gate,
+      events,
+      rule
     });
   } catch (error) {
     if (!(error instanceof HttpError)) throw error;
@@ -2866,6 +4897,15 @@ async function sendRequest(step, scope, client, recipe, gate, events) {
     number: scope.pageState?.number ?? 1,
     status: response.status
   });
+  const warnings = response.warnings ?? [];
+  for (const warning of warnings) events.emit({
+    type: 'warning',
+    recipeId: recipe.id,
+    message: `${response.url}: ${warning}`,
+    meta: {
+      url: response.url
+    }
+  });
   const blocked = await detectBlock({
     url: response.url,
     status: response.status,
@@ -2873,15 +4913,30 @@ async function sendRequest(step, scope, client, recipe, gate, events) {
     text: async () => bodyText(response.body)
   }, recipe.session?.blockedWhen);
   if (blocked !== undefined) throw blocked;
+  if (recipe.session?.captcha !== undefined && response.body.kind === 'html' && CAPTCHA_MARKUP.test(response.body.html)) {
+    throw new BlockedError(response.url, response.status, 'the page shows a captcha, which is solved on a live page: run this recipe in web mode, or get past it in session.bootstrap');
+  }
   scope.setPage({
     url: response.url,
     document: response.body
   });
   if (step.id !== undefined) scope.set(step.id, documentValue(response.body));
 }
+/** A retry status (with the server's `Retry-After`), or a connection that failed. */
+function problemOf(error, statuses) {
+  if (error instanceof HttpError) return statuses.includes(error.status) ? {
+    reason: `HTTP ${error.status}`,
+    retryAfter: error.headers['retry-after']
+  } : undefined;
+  return transientError(error);
+}
+/** The class names of the widgets `session.captcha` solves. Checked only when a recipe declares it. */
+const CAPTCHA_MARKUP = /\b(?:g-recaptcha|h-captcha|cf-turnstile)\b/;
 function bodyText(body) {
   if (body.kind === 'json') return JSON.stringify(body.data);
   if (body.kind === 'pdf') return pdfText(body);
+  if (body.kind === 'workbook') return workbookText(body);
+  if (body.kind === 'deck') return deckText(body);
   return body.kind === 'html' ? body.html : body.text;
 }
 function renderMap(map, lookup) {
@@ -2902,11 +4957,11 @@ function resolveUrl(target, base) {
     throw new Error(`"${target}" is not a URL${base === undefined || base === '' ? ' and no page is known to resolve it against' : ` and cannot be resolved against ${base}`}`);
   }
 }
-/** What a step id holds for a document: parsed JSON, the read PDF, or the markup / text. */
+/** What a step id holds for a document: parsed JSON, the read PDF, workbook or deck, or the markup / text. */
 function documentValue(body) {
   if (body.kind === 'json') return body.data;
-  if (body.kind === 'pdf') return body;
-  return body.kind === 'html' ? body.html : body.text;
+  if (body.kind === 'html') return body.html;
+  return body.kind === 'text' ? body.text : body;
 }
 
 /** Runs api-mode leaf steps against an HTTP sender. */
@@ -3988,11 +6043,10 @@ async function extractFromPage(step, page, scope) {
     extractFromDocument(step, scope);
     return;
   }
-  if (step.kind === 'table') throw new Error('table reads a PDF: fetch it with a request step in api mode, or extract "from" a PDF bound earlier');
-  const rendered = renderSelector(step.selector, scope);
-  const take = step.take ?? 'text';
-  const raw = step.kind === 'regex' ? selectRegex(await page.content(), rendered) : await page.locator(step.kind === 'xpath' ? `xpath=${rendered}` : rendered).evaluateAll(readAll, take);
-  const values = take === 'text' ? raw.map(value => typeof value === 'string' ? collapse(value) : value) : raw;
+  const values = step.kind === 'table' ? tablesIn({
+    kind: 'html',
+    html: await page.content()
+  }, step, scope) : await readPage(step, page, scope);
   if (step.many === true) {
     if (step.id !== undefined) scope.set(step.id, values);
     return;
@@ -4000,6 +6054,13 @@ async function extractFromPage(step, page, scope) {
   if (values.length === 0) throw new NoMatchError(step.selector);
   if (step.id !== undefined) scope.set(step.id, values[0]);
 }
+/** A css, xpath or regex extract on the live page. */
+async function readPage(step, page, scope) {
+  const rendered = renderSelector(step.selector, scope);
+  const take = step.take ?? 'text';
+  const raw = step.kind === 'regex' ? selectRegex(await page.content(), rendered) : await page.locator(step.kind === 'xpath' ? `xpath=${rendered}` : rendered).evaluateAll(readAll, take);
+  return take === 'text' ? raw.map(value => typeof value === 'string' ? collapse(value) : value) : raw;
+}
 /** Runs inside the page: one value per matched element. Keep it self-contained; it is serialised. */
 function readAll(elements, take) {
   return elements.map(element => {
@@ -4151,18 +6212,34 @@ function readElements(elements) {
 
 /**
  * Runs a `goto` step: renders the URL (relative to the current page), waits for
- * the gate's throttle (`delayMs`), navigates, records the page's real URL in the
- * scope, and checks the response against the recipe's block rule.
+ * the gate's throttle (`delayMs`), navigates (again, after a pause, while it
+ * fails in passing: `limits.retry`), records the page's real URL in the scope,
+ * and checks the response against the recipe's block rule.
  *
  * @throws BlockedError when the response is a block.
  */
 async function navigate(step, page, scope, recipe, gate, events) {
   const target = renderText(step.url, path => scope.lookup(path));
   const url = new URL(target, scope.pageState?.url ?? page.url()).href;
-  await gate.throttle();
-  const response = await page.goto(url, {
-    waitUntil: step.waitUntil,
-    timeout: recipe.limits?.timeoutMs
+  const rule = resolveRetryRule(recipe.limits?.retry);
+  const response = await withTransportRetry(url, {
+    run: () => page.goto(url, {
+      waitUntil: step.waitUntil,
+      timeout: recipe.limits?.timeoutMs
+    }),
+    problem: outcome => {
+      if ('error' in outcome) return transientError(outcome.error);
+      const status = outcome.value?.status();
+      return status !== undefined && rule.statuses.includes(status) ? {
+        reason: `HTTP ${status}`,
+        retryAfter: outcome.value?.headers()['retry-after']
+      } : undefined;
+    }
+  }, {
+    recipeId: recipe.id,
+    gate,
+    events,
+    rule
   });
   scope.setPage({
     url: page.url()
@@ -4185,18 +6262,26 @@ async function navigate(step, page, scope, recipe, gate, events) {
 }
 
 const NEXT_LINK_TIMEOUT_MS = 2000;
-/** Runs web-mode leaf steps on a browser page. */
+/** Steps after which a page may show a new captcha (`session.captcha`). */
+const CHALLENGING_STEPS = new Set(['click', 'press']);
+/**
+ * Runs web-mode leaf steps on a browser page. With a captcha guard, a page a
+ * navigation, click or key press leads to is checked for a challenge, solved
+ * before the next step runs.
+ */
 class WebStepRunner {
   session;
   recipe;
   events;
   gate;
+  captcha;
   page;
-  constructor(session, recipe, events, gate = new RunGate(1, recipe.limits?.delayMs ?? 0)) {
+  constructor(session, recipe, events, gate = new RunGate(1, recipe.limits?.delayMs ?? 0), captcha) {
     this.session = session;
     this.recipe = recipe;
     this.events = events;
     this.gate = gate;
+    this.captcha = captcha;
     this.page = session.page;
   }
   /** Clicks and key presses can navigate; keep `page.url` honest after every leaf step. */
@@ -4206,11 +6291,29 @@ class WebStepRunner {
       url
     });
   }
+  /** Navigates; a block page showing a captcha is solved under `onBlock.solve`, and a page reached is checked for one. */
+  async visit(step, scope) {
+    try {
+      await navigate(step, this.page, scope, this.recipe, this.gate, this.events);
+    } catch (error) {
+      if (!(error instanceof BlockedError) || this.captcha?.solvesBlocks !== true) throw error;
+      await this.captcha.solveBlock(this.page, error);
+      return;
+    }
+    await this.captcha?.check(this.page);
+  }
   async runLeaf(step, scope) {
     switch (step.type) {
       case 'goto':
         {
-          return navigate(step, this.page, scope, this.recipe, this.gate, this.events);
+          await this.visit(step, scope);
+          break;
+        }
+      case 'captcha':
+        {
+          if (this.captcha === undefined) throw new Error('a captcha step needs a crawler with captcha solvers');
+          await this.captcha.step(this.page, step);
+          break;
         }
       case 'click':
         {
@@ -4262,6 +6365,7 @@ class WebStepRunner {
           throw new Error(`"${step.type}" is an api step; this recipe runs in web mode`);
         }
     }
+    if (CHALLENGING_STEPS.has(step.type)) await this.captcha?.check(this.page);
     this.trackUrl(scope);
   }
   async nextPage(next, scope) {
@@ -4269,9 +6373,10 @@ class WebStepRunner {
     if ('url' in next) {
       const target = renderText(next.url, path => scope.lookup(path));
       if (target === '') return null;
-      await navigate({
+      await this.visit({
+        type: 'goto',
         url: target
-      }, this.page, scope, this.recipe, this.gate, this.events);
+      }, scope);
       return {
         kind: 'url',
         url: this.page.url()
@@ -4284,8 +6389,13 @@ class WebStepRunner {
     const link = this.page.locator(next.selector).first();
     if (!(await appears(link, NEXT_LINK_TIMEOUT_MS))) return null;
     const before = this.page.url();
-    await link.click();
-    await this.page.waitForLoadState();
+    const release = await this.gate.request(before);
+    try {
+      await link.click();
+      await this.page.waitForLoadState();
+    } finally {
+      release();
+    }
     if (this.page.url() === before) await this.page.waitForTimeout(NEXT_LINK_TIMEOUT_MS / 4);
     this.events.emit({
       type: 'page:visit',
@@ -4293,11 +6403,29 @@ class WebStepRunner {
       url: this.page.url(),
       number: (scope.pageState?.number ?? 1) + 1
     });
+    await this.captcha?.check(this.page);
     return {
       kind: 'url',
       url: this.page.url()
     };
   }
+  /**
+   * A runner on a new tab of the same context, for one parallel iteration:
+   * it shares cookies, the gate and the captcha guard; disposing it closes the tab only.
+   *
+   * @returns The forked runner.
+   */
+  async fork() {
+    const {
+      context
+    } = this.session;
+    const page = await context.newPage();
+    const viewport = this.recipe.session?.viewport;
+    if (viewport !== undefined) await page.setViewportSize(viewport);
+    return new WebStepRunner(new BrowserSession(context, page, async () => {
+      await page.close();
+    }), this.recipe, this.events, this.gate, this.captcha);
+  }
   async elements(selector) {
     return snapshotElements(selector, this.page);
   }
@@ -4334,15 +6462,30 @@ function accessOptions(lease, headers) {
  * The bootstrap runs through the same access lease as the crawl that follows,
  * so a login and the requests that use its cookies come from one IP.
  *
+ * With `session.browserProfile`, the bootstrap runs in that profile, and
+ * without a bootstrap the profile's own cookies and storage are the state: an
+ * api recipe picks up a login a browser left in the profile.
+ *
  * @param recipe - The input recipe.
  * @param deps - Browser, hooks, events.
  * @param lease - The recipe run's access; direct when omitted.
+ * @param captcha - Solves the bootstrap's captchas (a login form's).
+ * @param owner - The recipe run, which a browser profile is held by.
  * @returns The state, or `undefined` when the recipe declares none.
  */
-async function resolveStorageState(recipe, deps, lease) {
+async function resolveStorageState(recipe, deps, lease, captcha, owner = {}) {
   const saved = await readSavedState(recipe, deps);
+  if (saved !== undefined) return saved;
   const session = recipe.session;
-  if (saved !== undefined || session?.bootstrap === undefined) return saved;
+  if (session?.browserProfile !== undefined) {
+    const browserSession = await openBrowserProfile(recipe, deps, lease, owner);
+    try {
+      return session.bootstrap === undefined ? await browserSession.storageState() : await runBootstrap(recipe, browserSession, deps, captcha);
+    } finally {
+      await browserSession.close();
+    }
+  }
+  if (session?.bootstrap === undefined) return undefined;
   const browser = await deps.browser();
   const browserSession = await browser.newSession({
     cookies: session.cookies,
@@ -4351,11 +6494,32 @@ async function resolveStorageState(recipe, deps, lease) {
     ...accessOptions(lease, session.headers)
   });
   try {
-    return await runBootstrap(recipe, browserSession, deps);
+    return await runBootstrap(recipe, browserSession, deps, captcha);
   } finally {
     await browserSession.close();
   }
 }
+/**
+ * Opens the recipe's `session.browserProfile` with its session options and
+ * the lease's proxy.
+ *
+ * @param recipe - A recipe with `session.browserProfile`.
+ * @param deps - For `profiles`.
+ * @param lease - The access lease.
+ * @param owner - The recipe run.
+ * @returns The session in the profile.
+ */
+async function openBrowserProfile(recipe, deps, lease, owner) {
+  const session = recipe.session;
+  const name = session?.browserProfile ?? '';
+  if (deps.profiles === undefined) throw new Error(`recipe "${recipe.id}" uses browser profile "${name}", but this crawler has no profiles directory (CrawlOptions.profilesDir)`);
+  return deps.profiles.open(name, {
+    cookies: session?.cookies,
+    userAgent: session?.userAgent,
+    viewport: session?.viewport,
+    ...accessOptions(lease, session?.headers)
+  }, owner);
+}
 /**
  * The storage state saved by an earlier bootstrap (`session.storageStatePath`), if the recipe names one.
  *
@@ -4376,15 +6540,16 @@ async function readSavedState(recipe, deps) {
  * @param recipe - An input recipe with `session.bootstrap`.
  * @param browserSession - Where the steps run.
  * @param deps - Hooks, events, `storageStateDir`.
+ * @param captcha - Solves the bootstrap's captchas.
  * @returns The kept state.
  */
-async function runBootstrap(recipe, browserSession, deps) {
+async function runBootstrap(recipe, browserSession, deps, captcha) {
   const bootstrap = recipe.session?.bootstrap;
   if (bootstrap === undefined) return {
     cookies: [],
     origins: []
   };
-  const runner = new WebStepRunner(browserSession, recipe, deps.events);
+  const runner = new WebStepRunner(browserSession, recipe, deps.events, new RunGate(1, recipe.limits?.delayMs ?? 0, deps.hosts), captcha);
   const scope = new ExtractionScope();
   scope.set('vars', recipe.vars ?? {});
   scope.set('start', {
@@ -4489,6 +6654,66 @@ class RotatingRunner {
       throw error;
     }
   }
+  /**
+   * A runner for one parallel iteration, forked from whichever runner is
+   * current when it runs a step: after a rotation it forks again from the new
+   * one, since the old context is gone (or going). Blocks are noted and
+   * rotated like the main runner's.
+   *
+   * @returns The iteration's runner.
+   */
+  async fork() {
+    // `own`: a tab this iteration opened and must close; an api runner is shared and never disposed here.
+    let forked;
+    const disposeForked = async () => {
+      if (forked?.own === true) await disposeQuietly(forked.runner);
+      forked = undefined;
+    };
+    const current = async () => {
+      if (forked?.generation === this.generation) return forked.runner;
+      await disposeForked();
+      const inner = this.inner;
+      forked = inner.fork === undefined ? {
+        generation: this.generation,
+        runner: inner,
+        own: false
+      } : {
+        generation: this.generation,
+        runner: await inner.fork(),
+        own: true
+      };
+      return forked.runner;
+    };
+    return {
+      runLeaf: async (step, scope) => {
+        const generation = this.generation;
+        try {
+          const runner = await current();
+          await runner.runLeaf(step, scope);
+        } catch (error) {
+          this.note(error, generation);
+          throw error;
+        }
+      },
+      nextPage: async (next, scope) => {
+        const generation = this.generation;
+        try {
+          const runner = await current();
+          return await runner.nextPage(next, scope);
+        } catch (error) {
+          this.note(error, generation);
+          throw error;
+        }
+      },
+      elements: async (selector, scope) => {
+        const runner = await current();
+        if (runner.elements === undefined) throw new Error('forEach over selector iterates live elements and needs a browser; this recipe runs in api mode');
+        return runner.elements(selector, scope);
+      },
+      rotate: error => this.rotate(error),
+      dispose: disposeForked
+    };
+  }
   async elements(selector, scope) {
     if (this.inner.elements === undefined) throw new Error('forEach over selector iterates live elements and needs a browser; this recipe runs in api mode');
     return this.inner.elements(selector, scope);
@@ -4537,12 +6762,19 @@ class RotatingRunner {
  * the sink sees one record at a time and `maxRecords` is exact: once reached,
  * every later emit returns `stop` before mapping.
  *
- * @param input - The input recipe.
+ * @param recipe - The input recipe.
  * @param output - The output recipe it feeds.
  * @param deps - Shared browser, hooks, events, sink and de-duplication.
  * @returns What happened.
  */
-async function runInputRecipe(input, output, deps) {
+async function runInputRecipe(recipe, output, deps) {
+  const input = {
+    ...recipe,
+    limits: {
+      ...recipe.limits,
+      retry: resolveRetryRule(recipe.limits?.retry, deps.retry)
+    }
+  };
   const started = Date.now();
   const report = {
     recipeId: input.id,
@@ -4555,29 +6787,44 @@ async function runInputRecipe(input, output, deps) {
     pages: 0,
     durationMs: 0
   };
+  const captchas = {
+    detected: 0,
+    solved: 0,
+    failed: 0
+  };
   const limits = input.limits ?? {};
-  // A web recipe drives one page, so only api mode runs iterations in parallel.
-  const gate = new RunGate(input.mode === 'web' ? 1 : limits.concurrency ?? 1, limits.delayMs ?? 0);
+  // Parallel iterations: requests in api mode, tabs of the recipe's context in web mode.
+  const gate = new RunGate(limits.concurrency ?? 1, limits.delayMs ?? 0, deps.hosts);
   let stopped = false;
   let chain = Promise.resolve();
   const unsubscribe = deps.events.subscribe(event => {
     if (event.type === 'page:visit' && event.recipeId === input.id) report.pages += 1;
     if (event.type === 'step:skip' && event.recipeId === input.id) report.stepsSkipped += 1;
+    if (event.type === 'captcha:detected' && event.recipeId === input.id) captchas.detected += 1;
+    if (event.type === 'captcha:solved' && event.recipeId === input.id) captchas.solved += 1;
+    if (event.type === 'captcha:failed' && event.recipeId === input.id) captchas.failed += 1;
   });
   deps.events.emit({
     type: 'recipe:start',
     recipeId: input.id,
     mode: input.mode
   });
-  deps.dedupe.startRecipe();
+  const dedupe = deps.dedupe.forRecipe();
   let runner;
   try {
     const onBlock = input.session?.onBlock;
+    const solvers = deps.captchaSolvers ?? new CaptchaSolverRegistry();
+    for (const name of captchaSolverNames(input)) solvers.resolve(name);
+    const context = {
+      gate,
+      solvers,
+      budget: new CaptchaBudget(input.session?.captcha?.maxSolves ?? DEFAULT_MAX_SOLVES)
+    };
     runner = await RotatingRunner.open({
       recipe: input,
       events: deps.events,
       maxRotations: onBlock?.rotate === true ? onBlock.attempts ?? 2 : 0,
-      open: attempt => openLeased(input, deps, gate, attempt)
+      open: attempt => openLeased(input, deps, context, attempt)
     });
     for (const point of input.start) {
       const scope = new ExtractionScope();
@@ -4612,6 +6859,7 @@ async function runInputRecipe(input, output, deps) {
   } finally {
     await runner?.dispose();
     unsubscribe();
+    if (captchas.detected > 0) report.captchas = captchas;
     report.durationMs = Date.now() - started;
     deps.events.emit({
       type: 'recipe:finish',
@@ -4669,7 +6917,7 @@ async function runInputRecipe(input, output, deps) {
           url,
           key: record.key
         });
-      } else if (deps.dedupe.isDuplicate(record)) {
+      } else if (dedupe.isDuplicate(record)) {
         report.duplicates += 1;
         deps.events.emit({
           type: 'record:duplicate',
@@ -4737,11 +6985,11 @@ async function leaseAccess(input, deps, attempt) {
   return lease;
 }
 /** A lease and a runner opened on it; the lease is released again when opening fails. */
-async function openLeased(input, deps, gate, attempt) {
+async function openLeased(input, deps, context, attempt) {
   const lease = await leaseAccess(input, deps, attempt);
   try {
     return {
-      runner: await openRunner(input, deps, gate, lease),
+      runner: await openRunner(input, deps, context, lease),
       lease
     };
   } catch (error) {
@@ -4749,9 +6997,20 @@ async function openLeased(input, deps, gate, attempt) {
     throw error;
   }
 }
-async function openRunner(input, deps, gate, lease) {
-  if (lease.cdp !== undefined) return openRemoteRunner(input, deps, gate, lease, lease.cdp);
-  const storageState = await resolveStorageState(input, deps, lease);
+async function openRunner(input, deps, context, lease) {
+  const {
+    gate
+  } = context;
+  const captcha = new CaptchaGuard({
+    recipe: input,
+    events: deps.events,
+    solvers: context.solvers,
+    budget: context.budget,
+    lease
+  });
+  if (lease.cdp !== undefined) return openRemoteRunner(input, deps, context, lease, lease.cdp);
+  if (input.mode === 'web' && input.session?.browserProfile !== undefined) return openProfileRunner(input, deps, context, lease, captcha);
+  const storageState = await resolveStorageState(input, deps, lease, captcha, context);
   const session = input.session;
   const access = accessOptions(lease, session?.headers);
   if (input.mode === 'web') {
@@ -4763,7 +7022,7 @@ async function openRunner(input, deps, gate, lease) {
       viewport: session?.viewport,
       ...access
     });
-    return new WebStepRunner(browserSession, input, deps.events, gate);
+    return new WebStepRunner(browserSession, input, deps.events, gate, captcha);
   }
   const client = await HttpClient.open({
     storageState,
@@ -4775,13 +7034,43 @@ async function openRunner(input, deps, gate, lease) {
   });
   return new ApiStepRunner(client, input, deps.events, gate);
 }
+/**
+ * A web runner in a persistent browser profile. The bootstrap runs in the
+ * same browser as the crawl, and what both leave behind (cookies, storage)
+ * stays in the profile for the next run.
+ */
+async function openProfileRunner(input, deps, context, lease, captcha) {
+  const saved = await readSavedState(input, deps);
+  const browserSession = await openBrowserProfile(saved === undefined ? input : {
+    ...input,
+    session: {
+      ...input.session,
+      cookies: [...saved.cookies, ...(input.session?.cookies ?? [])]
+    }
+  }, deps, lease, context);
+  try {
+    if (saved === undefined && input.session?.bootstrap !== undefined) await runBootstrap(input, browserSession, deps, captcha);
+  } catch (error) {
+    await browserSession.close();
+    throw error;
+  }
+  return new WebStepRunner(browserSession, input, deps.events, context.gate, captcha);
+}
 /**
  * A web runner in a remote browser. The bootstrap runs in the same remote
  * session as the crawl: providers tie the IP and fingerprint to the
  * connection, so a login in one connection would not carry to another.
  */
-async function openRemoteRunner(input, deps, gate, lease, cdp) {
+async function openRemoteRunner(input, deps, context, lease, cdp) {
+  const captcha = new CaptchaGuard({
+    recipe: input,
+    events: deps.events,
+    solvers: context.solvers,
+    budget: context.budget,
+    lease
+  });
   if (input.mode === 'api') throw new AccessConfigError(`recipe "${input.id}" runs in api mode, but access profile "${lease.profile}" is a remote browser; api recipes need a proxy profile`);
+  if (input.session?.browserProfile !== undefined) throw new AccessConfigError(`recipe "${input.id}" uses browser profile "${input.session.browserProfile}", which needs a local browser, but access profile "${lease.profile}" is a remote browser`);
   const session = input.session;
   const storageState = await readSavedState(input, deps);
   const browserSession = await BrowserClient.connectOverCDP(cdp, {
@@ -4791,36 +7080,51 @@ async function openRemoteRunner(input, deps, gate, lease, cdp) {
     ...accessOptions(lease, session?.headers)
   }, input.limits?.timeoutMs);
   try {
-    if (storageState === undefined && session?.bootstrap !== undefined) await runBootstrap(input, browserSession, deps);
+    if (storageState === undefined && session?.bootstrap !== undefined) await runBootstrap(input, browserSession, deps, captcha);
   } catch (error) {
     await browserSession.close();
     throw error;
   }
-  return new WebStepRunner(browserSession, input, deps.events, gate);
+  return new WebStepRunner(browserSession, input, deps.events, context.gate, captcha);
 }
 
 /**
- * Runs every input recipe of a set, one after another, into one sink.
+ * Runs every input recipe of a set into one sink, `parallel` at a time
+ * (default one after another). Reports come back in the set's order whatever
+ * order the recipes finish in. Under `onRecipeError: 'stop'`, a failed recipe
+ * stops the ones not started yet; those already running finish.
  *
  * @param set - The bound recipes.
  * @param deps - Shared browser, hooks, events, sink and de-duplication.
  * @param onRecipeError - Whether a failed recipe stops the run.
+ * @param parallel - How many input recipes run at once.
  * @returns The report.
  */
-async function runCrawl(set, deps, onRecipeError) {
+async function runCrawl(set, deps, onRecipeError, parallel = 1) {
   const started = Date.now();
   await deps.sink.open(set.output);
-  const recipes = [];
+  const reports = [];
   let sink;
   try {
-    for (const input of set.inputs) {
-      const report = await runInputRecipe(input, set.output, deps);
-      recipes.push(report);
-      if (onRecipeError === 'stop' && report.error !== undefined) break;
-    }
+    let next = 0;
+    let stopped = false;
+    const lane = async () => {
+      while (!stopped && next < set.inputs.length) {
+        const index = next;
+        next += 1;
+        const report = await runInputRecipe(set.inputs[index], set.output, deps);
+        reports[index] = report;
+        if (onRecipeError === 'stop' && report.error !== undefined) stopped = true;
+      }
+    };
+    const lanes = Math.max(1, Math.min(parallel, set.inputs.length));
+    await Promise.all(Array.from({
+      length: lanes
+    }, lane));
   } finally {
     sink = await deps.sink.close();
   }
+  const recipes = reports.filter(report => report !== undefined);
   return {
     outputId: set.output.id,
     recipes,
@@ -4834,15 +7138,19 @@ async function runCrawl(set, deps, onRecipeError) {
  * Creates a crawler. The browser is launched lazily, on the first recipe or
  * bootstrap that needs it, and shared by every run until `close`.
  *
- * @param options - Hooks, sink, events, browser settings, access, policies.
+ * @param options - Hooks, sink, events, browser settings, access, captcha solvers, policies.
  * @returns The crawler.
  * @throws AccessConfigError when the access config cannot work.
+ * @throws Error when two captcha solvers share a name.
  */
 function createCrawler(options = {}) {
   const sink = options.sink ?? memorySink();
   if (options.resume === true && sink.has === undefined) throw new Error('resume needs a sink that can tell which keys it has (jsonLinesSink with append, memorySink, or a custom sink with `has`)');
   const access = new AccessBroker(options.access, options.accessPlugins);
   const hooks = new HookRegistry(options.hooks);
+  const captchaSolvers = new CaptchaSolverRegistry(options.captchaSolvers);
+  const hosts = new HostThrottle(options.throttle ?? options.access?.throttle);
+  const profiles = new BrowserProfiles(options.profilesDir ?? resolve$1(options.storageStateDir ?? '.', '.opencraw', 'profiles'), options.browser);
   const events = new EventBus(options.onEvent);
   let browser;
   const launch = () => {
@@ -4860,8 +7168,12 @@ function createCrawler(options = {}) {
       resume: options.resume === true,
       debug: options.debug === true,
       access,
+      captchaSolvers,
+      hosts,
+      profiles,
+      retry: options.retry,
       ignoreHTTPSErrors: options.browser?.ignoreHTTPSErrors
-    }, options.onRecipeError ?? 'continue'),
+    }, options.onRecipeError ?? 'continue', options.parallel ?? 1),
     async close() {
       const launched = browser;
       browser = undefined;
@@ -4877,7 +7189,8 @@ const CRAWL_MODES = ['web', 'api'];
 const SELECTOR_KINDS = ['css', 'xpath', 'jsonpath', 'regex', 'table'];
 /** `take` also accepts `attr:<name>`, which is validated by pattern rather than listed. */
 const TAKE_KINDS = ['text', 'html', 'value', 'json'];
-const BODY_KINDS = ['json', 'html', 'text', 'pdf'];
+const BODY_KINDS = ['json', 'jsonl', 'html', 'text', 'pdf', 'csv', 'xlsx', 'pptx', 'yaml', 'markdown'];
+const YAML_SCALARS = ['typed', 'text'];
 /** How a PDF table aligns a row's values against a cell wrapped over several lines. */
 const TABLE_ALIGNS = ['auto', 'top', 'center', 'bottom'];
 const FIELD_TYPES = ['string', 'number', 'integer', 'boolean', 'date', 'datetime', 'currency', 'url', 'enum', 'array', 'object', 'json'];
@@ -4889,7 +7202,7 @@ const KEEP_KINDS = ['cookies', 'localStorage'];
 const WAIT_UNTIL = ['load', 'domcontentloaded', 'networkidle', 'commit'];
 const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'];
 /** Steps that only make sense with a live browser page. */
-const WEB_ONLY_STEPS = ['goto', 'click', 'fill', 'press', 'select', 'scroll', 'wait', 'evaluate', 'screenshot'];
+const WEB_ONLY_STEPS = ['goto', 'click', 'fill', 'press', 'select', 'scroll', 'wait', 'evaluate', 'screenshot', 'captcha'];
 /** Steps that only make sense against an HTTP request context. */
 const API_ONLY_STEPS = ['request'];
 
@@ -5054,9 +7367,18 @@ const requestStep = z.strictObject({
   query: stringMap.optional(),
   headers: stringMap.optional(),
   body: z.unknown().optional(),
-  as: z.enum(BODY_KINDS).optional()
+  as: z.enum(BODY_KINDS).optional(),
+  encoding: z.string().min(1).optional(),
+  delimiter: z.string().length(1).optional(),
+  scalars: z.enum(YAML_SCALARS).optional()
+}).refine(step => step.delimiter === undefined || step.as === undefined || step.as === 'csv', {
+  message: '"delimiter" reads CSV only: drop it or set "as": "csv"',
+  path: ['delimiter']
+}).refine(step => step.scalars === undefined || step.as === undefined || step.as === 'yaml', {
+  message: '"scalars" reads YAML only: drop it or set "as": "yaml"',
+  path: ['scalars']
 });
-const tableOnly = ['columns', 'until', 'align'];
+const tableOnly = ['columns', 'until', 'align', 'sheet', 'headerRows', 'fillDown', 'includeHidden', 'slide', 'shapes'];
 const extractStep = z.strictObject({
   ...base,
   type: z.literal('extract'),
@@ -5067,7 +7389,13 @@ const extractStep = z.strictObject({
   from: stepId.optional(),
   columns: stringMap.optional(),
   until: z.string().min(1).optional(),
-  align: z.enum(TABLE_ALIGNS).optional()
+  align: z.enum(TABLE_ALIGNS).optional(),
+  sheet: z.string().min(1).optional(),
+  headerRows: z.int().min(1).optional(),
+  fillDown: z.array(z.string().min(1)).min(1).optional(),
+  includeHidden: z.boolean().optional(),
+  slide: z.string().min(1).optional(),
+  shapes: z.boolean().optional()
 }).check(context => {
   if (context.value.kind === 'table') return;
   for (const key of tableOnly) {
@@ -5101,6 +7429,19 @@ const hookStep = z.strictObject({
   name: z.string().min(1),
   args: z.record(z.string(), z.unknown()).optional()
 });
+const captchaCheckSchema = z.strictObject({
+  gone: z.boolean().optional(),
+  selector: z.string().min(1).optional()
+});
+const captchaStep = z.strictObject({
+  ...base,
+  type: z.literal('captcha'),
+  solver: z.string().min(1).optional(),
+  selector: z.string().min(1).optional(),
+  verify: captchaCheckSchema.optional(),
+  attempts: z.int().min(1).max(10).optional(),
+  timeoutMs: z.int().min(1000).optional()
+});
 const emitFlag = z.union([z.literal(true), z.strictObject({
   output: z.string().min(1)
 })]);
@@ -5129,7 +7470,7 @@ const paginateStep = z.strictObject({
   maxPages: z.int().min(1).optional(),
   steps
 });
-const stepSchema = z.discriminatedUnion('type', [gotoStep, clickStep, fillStep, pressStep, selectStep, scrollStep, waitStep, evaluateStep, screenshotStep, requestStep, extractStep, assignStep, collectStep, emitStep, hookStep, forEachStep, ifStep, paginateStep]);
+const stepSchema = z.discriminatedUnion('type', [gotoStep, clickStep, fillStep, pressStep, selectStep, scrollStep, waitStep, evaluateStep, screenshotStep, requestStep, extractStep, assignStep, collectStep, emitStep, hookStep, forEachStep, ifStep, paginateStep, captchaStep]);
 
 const args = z.record(z.string(), z.unknown());
 const stringList = z.array(z.string());
@@ -5277,9 +7618,20 @@ const blockRuleSchema = z.strictObject({
   text: regexSource.optional()
 });
 const blockRotationSchema = z.strictObject({
-  rotate: z.boolean(),
+  rotate: z.boolean().optional(),
+  solve: z.boolean().optional(),
   attempts: z.int().min(1).max(10).optional()
 });
+const captchaSettingsSchema = z.strictObject({
+  solver: z.string().min(1),
+  detect: z.strictObject({
+    selector: z.string().min(1)
+  }).optional(),
+  verify: captchaCheckSchema.optional(),
+  attempts: z.int().min(1).max(10).optional(),
+  timeoutMs: z.int().min(1000).optional(),
+  maxSolves: z.int().nonnegative().optional()
+});
 const sessionSpecSchema = z.strictObject({
   headers: z.record(z.string(), z.string()).optional(),
   cookies: z.array(cookieSchema).optional(),
@@ -5292,13 +7644,22 @@ const sessionSpecSchema = z.strictObject({
   bootstrap: bootstrapSchema.optional(),
   access: sessionAccessSchema.optional(),
   blockedWhen: blockRuleSchema.optional(),
-  onBlock: blockRotationSchema.optional()
+  onBlock: blockRotationSchema.optional(),
+  captcha: captchaSettingsSchema.optional(),
+  browserProfile: z.string().regex(/^[\w-]+$/, 'a browser profile name is letters, digits, hyphens and underscores').optional()
+});
+const retryRuleSchema = z.strictObject({
+  attempts: z.int().min(1).max(10).optional(),
+  backoffMs: z.int().nonnegative().optional(),
+  maxDelayMs: z.int().nonnegative().optional(),
+  statuses: z.array(z.int().min(400).max(599)).optional()
 });
 const limitsSchema = z.strictObject({
   maxRecords: z.int().positive().optional(),
   delayMs: z.int().nonnegative().optional(),
   timeoutMs: z.int().positive().optional(),
-  concurrency: z.int().min(1).max(64).optional()
+  concurrency: z.int().min(1).max(64).optional(),
+  retry: retryRuleSchema.optional()
 });
 const inputRecipeSchema = z.strictObject({
   $schema: z.string().optional(),
@@ -5595,7 +7956,9 @@ const API_ONLY = new Set(API_ONLY_STEPS);
  * - web-only steps appear only in web recipes or inside a bootstrap, api-only
  *   steps only in api recipes, and `next.selector` only in web mode;
  * - exactly one emitting construct exists on any path (the two branches of an
- *   `if` are separate paths).
+ *   `if` are separate paths);
+ * - a `captcha` step, and `onBlock.solve`, have a solver: their own or
+ *   `session.captcha.solver`.
  *
  * @param input - A parsed input recipe.
  * @param output - The parsed output recipe it names.
@@ -5613,17 +7976,22 @@ function validateBinding(input, output) {
   const known = new Set(RESERVED);
   const varNames = [input.vars ?? {}, ...input.start.map(point => point.vars ?? {})].flatMap(record => Object.keys(record));
   for (const name of varNames) known.add(name);
+  const solver = input.session?.captcha !== undefined;
   walkSteps(input.steps, 'steps', input.mode, known, report, {
     emitting: false,
-    ids: new Set()
+    ids: new Set(),
+    solver
   });
   if (input.session?.bootstrap !== undefined) {
     walkSteps(input.session.bootstrap.steps, 'session.bootstrap.steps', 'web', new Set(RESERVED), report, {
       emitting: false,
       ids: new Set(),
-      bootstrap: true
+      bootstrap: true,
+      solver
     });
   }
+  if (!solver && input.session?.onBlock?.solve === true) report('session.onBlock.solve', 'solving a block needs a solver: add session.captcha');
+  if (input.mode === 'api' && input.session?.onBlock?.solve === true) report('session.onBlock.solve', 'captchas are solved on a live page; this recipe runs in api mode (solve them in session.bootstrap)');
   for (const [target, rule] of Object.entries(input.mapping)) {
     const field = fieldAt(output.fields, target);
     if (field === undefined) {
@@ -5655,7 +8023,11 @@ function walkStep(step, at, mode, known, report, state) {
     known.add(step.id);
   }
   if (step.type === 'extract' && step.from !== undefined && !known.has(step.from)) report(`${at}.from`, `"${step.from}" is not a known id`);
-  if (mode === 'web' && state.bootstrap !== true && step.type === 'extract' && step.kind === 'table' && step.from === undefined) report(at, 'a "table" extract reads a PDF, which a web page is not: fetch the PDF with a request step in an api recipe, or extract "from" a PDF bound earlier');
+  if (mode === 'web' && state.bootstrap !== true && step.type === 'extract' && step.kind === 'table' && step.from === undefined) {
+    const foreign = ['sheet', 'slide', 'shapes', 'align', 'includeHidden'].filter(option => step[option] !== undefined);
+    if (foreign.length > 0) report(at, `a "table" extract on a web page reads its HTML tables; ${foreign.map(option => `"${option}"`).join(', ')} belong to PDFs, workbooks or decks (fetch one with a request step in an api recipe)`);
+  }
+  if (step.type === 'captcha' && step.solver === undefined && !state.solver) report(at, 'a captcha step needs a solver: name one ("solver") or add session.captcha');
   if (step.type === 'collect' && !known.has(step.into)) report(`${at}.into`, `"${step.into}" is not a known id: set it to [] before the loop that collects into it`);
   const nested = () => ({
     ...state,
@@ -5818,5 +8190,5 @@ function isSameOutput(document, output) {
   return recipeKindOf(document.content) === 'output' && document.content.id === output.id;
 }
 
-export { ACCESS_PRESETS, AccessBroker, AccessConfigError, BrowserClient, BrowserSession, HttpClient, HttpError, MappingFailedError, PdfReadError, RecipeBindingError, RecipeSet, RecipeValidationError, RecordRejectedError, StepFailure, TransformError, UnknownHookError, accessConfigJsonSchema, accessConfigSchema, bindRecipeSet, createCrawler, findTables, inputRecipeJsonSchema, inputRecipeSchema, jsonLinesSink, loadAccessConfig, loadRecipeSet, loadRecipes, memorySink, outputRecipeJsonSchema, outputRecipeSchema, parseInputRecipe, parseOutputRecipe, pdfText, readPdf, readRecipeSource, traceLine, tryParseJson, validateBinding };
+export { ACCESS_PRESETS, AccessBroker, AccessConfigError, BrowserClient, BrowserSession, CaptchaError, DEFAULT_CAPTCHA_SELECTOR, DEFAULT_RETRY_RULE, HostThrottle, HttpClient, HttpError, MappingFailedError, PdfReadError, RecipeBindingError, RecipeSet, RecipeValidationError, RecordRejectedError, StepFailure, TransformError, UnknownHookError, accessConfigJsonSchema, accessConfigSchema, bindRecipeSet, createCrawler, csvWorkbook, deckText, detectChallenge, detectDelimiter, fillDown, findDeckTables, findGridTables, findTables, htmlTableSheets, inputRecipeJsonSchema, inputRecipeSchema, isDeckDocument, isWorkbookDocument, jsonLinesSink, loadAccessConfig, loadRecipeSet, loadRecipes, memorySink, outputRecipeJsonSchema, outputRecipeSchema, parseCsv, parseInputRecipe, parseOutputRecipe, pdfText, readMarkdown, readPdf, readRecipeSource, readYaml, retryRuleSchema, throttleConfigSchema, traceLine, tryParseJson, validateBinding, workbookText };
 //# sourceMappingURL=index.esm.js.map