@opencraw/core 0.1.1 → 0.1.2

package/dist/index.esm.js

@@ -1248,6 +1248,928 @@ class BrowserClient {
   }
 }
 
+/**
+ * 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$1(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.
+ */
+async function runPooled(step, scope, walk, items, gate) {
+  let stopped = false;
+  let failure;
+  const tasks = [];
+  const overrides = {
+    gate: gate.nested()
+  };
+  const iterate = async (item, release) => {
+    try {
+      if ((await runIteration(step, scope, walk, item, overrides)) === 'stop') stopped = true;
+    } catch (error) {
+      failure ??= {
+        error
+      };
+    } finally {
+      release();
+    }
+  };
+  for (const item of items) {
+    if (stopped || failure !== undefined) break;
+    const release = await gate.acquire();
+    if (stopped || failure !== undefined) {
+      release();
+      break;
+    }
+    tasks.push(iterate(item, release));
+  }
+  await Promise.allSettled(tasks);
+  if (failure !== undefined) throw failure.error;
+  return stopped ? 'stop' : 'continue';
+}
+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);
+  }
+  const list = scope.get(step.over ?? '');
+  return Array.isArray(list) ? list : list === undefined || list === null ? [] : [list];
+}
+
+/**
+ * Runs a body once per page, each in a fresh child scope, then asks the runner
+ * for the next page until there is none, `until` renders truthy, or `maxPages`
+ * is reached.
+ *
+ * The runner reports the visit of each new page; this only steers.
+ *
+ * @param step - The paginate step.
+ * @param scope - The scope to page in; its page URL advances with each page.
+ * @param walk - Runs a step list; carries the runner and the emit callback.
+ * @returns `stop` when the crawl reached its record limit.
+ */
+async function runPaginate(step, scope, walk) {
+  let number = scope.pageState?.number ?? 1;
+  let bound;
+  for (let count = 1;; count += 1) {
+    const page = scope.child();
+    page.setPage({
+      number
+    });
+    if (bound !== undefined) page.set(bound.name, bound.value);
+    const outcome = await walk.runSteps(step.steps, page, `${walk.path}.steps`);
+    if (outcome === 'stop') return 'stop';
+    if (step.until !== undefined && isTruthy(render(step.until, path => page.lookup(path)))) break;
+    if (step.maxPages !== undefined && count >= step.maxPages) break;
+    const next = await walk.runner.nextPage(step.next, page);
+    if (next === null) break;
+    number += 1;
+    if (next.kind === 'url') {
+      scope.setPage({
+        url: next.url,
+        number
+      });
+      bound = undefined;
+    } else {
+      scope.setPage({
+        number
+      });
+      bound = {
+        name: next.name,
+        value: next.value
+      };
+    }
+  }
+  return 'continue';
+}
+
+const FAIL = {
+  policy: 'fail'
+};
+/**
+ * The policy for a failing step: the step's own, else the recipe's, else `fail`.
+ *
+ * @param step - The step that failed.
+ * @param recipe - Its recipe.
+ * @returns The policy to apply.
+ */
+function resolveErrorPolicy(step, recipe) {
+  return step.onError ?? recipe.onError ?? FAIL;
+}
+/**
+ * How long to wait before a retry: linear backoff.
+ *
+ * @param policy - A retry policy.
+ * @param attempt - The attempt about to be made, starting at 2.
+ * @returns Milliseconds.
+ */
+function backoffFor(policy, attempt) {
+  return (policy.backoffMs ?? 0) * (attempt - 1);
+}
+function sleep(ms) {
+  return ms <= 0 ? Promise.resolve() : new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/** A response the recipe's `session.blockedWhen` rule (or the default one) says is the site refusing the crawl. */
+class BlockedError extends Error {
+  url;
+  status;
+  reason;
+  name = 'BlockedError';
+  constructor(url, status, reason) {
+    super(`blocked at ${url}: ${reason}`);
+    this.url = url;
+    this.status = status;
+    this.reason = reason;
+  }
+}
+
+/** A step that failed under the `fail` policy: the recipe stops here. */
+class StepFailure extends Error {
+  stepPath;
+  stepType;
+  name = 'StepFailure';
+  constructor(stepPath, stepType, cause) {
+    super(`step ${stepPath} (${stepType}) failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
+      cause
+    });
+    this.stepPath = stepPath;
+    this.stepType = stepType;
+  }
+}
+/** A single `extract` that matched nothing. */
+class NoMatchError extends Error {
+  selector;
+  name = 'NoMatchError';
+  constructor(selector) {
+    super(`no match for ${selector}`);
+    this.selector = selector;
+  }
+}
+
+/**
+ * Walks a step list in order. Control flow (`forEach`, `if`, `paginate`, `emit`,
+ * `set`, `hook`, `when`, error policies) is handled here; leaf steps go to the
+ * runner. Mode-agnostic: the same walk drives a browser page or an HTTP context.
+ *
+ * @param steps - The steps.
+ * @param scope - The scope to run in.
+ * @param options - Recipe, runner, hooks, events and the emit callback.
+ * @param path - Where these steps are, for messages and events.
+ * @returns `stop` when the emit callback asked to stop.
+ * @throws StepFailure when a step fails under the `fail` policy.
+ */
+async function runSteps(steps, scope, options, path = 'steps') {
+  for (const [index, step] of steps.entries()) {
+    if (step.when !== undefined && !isTruthy(render(step.when, lookupIn(scope)))) continue;
+    const at = `${path}.${index}`;
+    const walk = {
+      ...options,
+      path: at,
+      runSteps: (inner, innerScope, innerPath, overrides) => runSteps(inner, innerScope, {
+        ...options,
+        ...overrides
+      }, innerPath)
+    };
+    const outcome = await runWithPolicy(step, scope, walk);
+    if (outcome === 'stop') return 'stop';
+  }
+  return 'continue';
+}
+async function runWithPolicy(step, scope, walk) {
+  const policy = resolveErrorPolicy(step, walk.recipe);
+  const attempts = policy.policy === 'retry' ? policy.attempts : 1;
+  let attempt = 1;
+  for (;;) {
+    const started = Date.now();
+    walk.events.emit({
+      type: 'step:start',
+      recipeId: walk.recipe.id,
+      stepType: step.type,
+      stepId: step.id,
+      path: walk.path
+    });
+    try {
+      const outcome = await runOne(step, scope, walk);
+      walk.events.emit({
+        type: 'step:finish',
+        recipeId: walk.recipe.id,
+        stepType: step.type,
+        stepId: step.id,
+        path: walk.path,
+        durationMs: Date.now() - started
+      });
+      return outcome;
+    } catch (error) {
+      if (error instanceof StepFailure) throw error;
+      // A block the runner can rotate away from is retried on the new access, without spending a retry attempt.
+      if (error instanceof BlockedError && walk.runner.rotate !== undefined && (await walk.runner.rotate(error))) continue;
+      const message = error instanceof Error ? error.message : String(error);
+      if (policy.policy === 'retry' && attempt < attempts) {
+        attempt += 1;
+        walk.events.emit({
+          type: 'step:retry',
+          recipeId: walk.recipe.id,
+          stepType: step.type,
+          stepId: step.id,
+          path: walk.path,
+          attempt,
+          error: message
+        });
+        await sleep(backoffFor(policy, attempt));
+        continue;
+      }
+      if (policy.policy === 'skip') {
+        walk.events.emit({
+          type: 'step:skip',
+          recipeId: walk.recipe.id,
+          stepType: step.type,
+          stepId: step.id,
+          path: walk.path,
+          error: message
+        });
+        return 'continue';
+      }
+      throw new StepFailure(walk.path, step.type, error);
+    }
+  }
+}
+async function runOne(step, scope, walk) {
+  switch (step.type) {
+    case 'forEach':
+      {
+        return runForEach(step, scope, walk);
+      }
+    case 'if':
+      {
+        const branch = isTruthy(render(step.test, lookupIn(scope))) ? 'then' : 'else';
+        walk.events.emit({
+          type: 'step:branch',
+          recipeId: walk.recipe.id,
+          path: walk.path,
+          branch
+        });
+        const chosen = branch === 'then' ? step.steps : step.else ?? [];
+        return walk.runSteps(chosen, scope, `${walk.path}.${branch === 'then' ? 'steps' : 'else'}`);
+      }
+    case 'paginate':
+      {
+        return runPaginate(step, scope, walk);
+      }
+    case 'emit':
+      {
+        return walk.onEmit(scope, step.output);
+      }
+    case 'set':
+      {
+        if (step.id !== undefined) scope.set(step.id, typeof step.value === 'string' ? render(step.value, lookupIn(scope)) : step.value);
+        return 'continue';
+      }
+    case 'collect':
+      {
+        const value = typeof step.value === 'string' ? render(step.value, lookupIn(scope)) : step.value;
+        if (value !== undefined) scope.append(step.into, Array.isArray(value) ? value : [value]);
+        return 'continue';
+      }
+    case 'hook':
+      {
+        const hook = walk.hooks.resolve(step.name);
+        const result = await hook(undefined, renderArgs(step.args ?? {}, scope), {
+          recipeId: walk.recipe.id,
+          scope: scope.snapshot(),
+          log: logThrough(walk)
+        });
+        if (step.id !== undefined) scope.set(step.id, result);
+        return 'continue';
+      }
+    default:
+      {
+        await walk.runner.runLeaf(step, scope);
+        return 'continue';
+      }
+  }
+}
+function lookupIn(scope) {
+  return path => scope.lookup(path);
+}
+function renderArgs(args, scope) {
+  return Object.fromEntries(Object.entries(args).map(([name, value]) => [name, typeof value === 'string' ? render(value, lookupIn(scope)) : value]));
+}
+function logThrough(walk) {
+  return (level, message, meta) => {
+    walk.events.emit({
+      type: level === 'error' ? 'error' : 'warning',
+      recipeId: walk.recipe.id,
+      message: `[${level}] ${message}`,
+      meta
+    });
+  };
+}
+
+/**
+ * What bounds a recipe run: how many `forEach` iterations may be in flight and
+ * how close together requests may start. One gate per recipe run, shared by
+ * every loop in it, so nested loops never multiply the limit.
+ *
+ * Permits go to the outermost concurrent loop: a loop that runs inside an
+ * iteration already holding a permit runs its body sequentially (see `nested`),
+ * which keeps the total at `permits` and cannot deadlock.
+ */
+class RunGate {
+  permits;
+  minIntervalMs;
+  shared;
+  inFlight = 0;
+  waiting = [];
+  lastStart = -Infinity;
+  /**
+   * @param permits - Iterations allowed in flight; 1 is sequential.
+   * @param minIntervalMs - Minimum time between two request starts across the run.
+   * @param shared - The throttle state to share (internal: `nested` gates keep their parent's).
+   */
+  constructor(permits, minIntervalMs, shared) {
+    this.permits = permits;
+    this.minIntervalMs = minIntervalMs;
+    this.shared = shared;
+  }
+  /** Whether this gate lets more than one iteration run at once. */
+  get concurrent() {
+    return this.permits > 1;
+  }
+  /**
+   * Takes a permit, waiting for one when all are in flight.
+   *
+   * @returns The release; call it exactly once, when the iteration ends.
+   */
+  async acquire() {
+    if (this.inFlight >= this.permits) await new Promise(resolve => {
+      this.waiting.push(resolve);
+    });
+    this.inFlight += 1;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      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);
+  }
+}
+
+/** 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();
@@ -1307,6 +2229,26 @@ function traceLine(event) {
       {
         return `${indent(1)}↻ new access lease (attempt ${event.attempt})`;
       }
+    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}]`}`;
@@ -1574,537 +2516,215 @@ function selectHtml(html, selector) {
     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.
- */
-async function runPooled(step, scope, walk, items, gate) {
-  let stopped = false;
-  let failure;
-  const tasks = [];
-  const overrides = {
-    gate: gate.nested()
-  };
-  const iterate = async (item, release) => {
-    try {
-      if ((await runIteration(step, scope, walk, item, overrides)) === 'stop') stopped = true;
-    } catch (error) {
-      failure ??= {
-        error
-      };
-    } finally {
-      release();
-    }
-  };
-  for (const item of items) {
-    if (stopped || failure !== undefined) break;
-    const release = await gate.acquire();
-    if (stopped || failure !== undefined) {
-      release();
-      break;
-    }
-    tasks.push(iterate(item, release));
-  }
-  await Promise.allSettled(tasks);
-  if (failure !== undefined) throw failure.error;
-  return stopped ? 'stop' : 'continue';
-}
-async function itemsOf(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);
-  }
-  const list = scope.get(step.over ?? '');
-  return Array.isArray(list) ? list : list === undefined || list === null ? [] : [list];
-}
-
-/**
- * Runs a body once per page, each in a fresh child scope, then asks the runner
- * for the next page until there is none, `until` renders truthy, or `maxPages`
- * is reached.
- *
- * The runner reports the visit of each new page; this only steers.
- *
- * @param step - The paginate step.
- * @param scope - The scope to page in; its page URL advances with each page.
- * @param walk - Runs a step list; carries the runner and the emit callback.
- * @returns `stop` when the crawl reached its record limit.
- */
-async function runPaginate(step, scope, walk) {
-  let number = scope.pageState?.number ?? 1;
-  let bound;
-  for (let count = 1;; count += 1) {
-    const page = scope.child();
-    page.setPage({
-      number
-    });
-    if (bound !== undefined) page.set(bound.name, bound.value);
-    const outcome = await walk.runSteps(step.steps, page, `${walk.path}.steps`);
-    if (outcome === 'stop') return 'stop';
-    if (step.until !== undefined && isTruthy(render(step.until, path => page.lookup(path)))) break;
-    if (step.maxPages !== undefined && count >= step.maxPages) break;
-    const next = await walk.runner.nextPage(step.next, page);
-    if (next === null) break;
-    number += 1;
-    if (next.kind === 'url') {
-      scope.setPage({
-        url: next.url,
-        number
-      });
-      bound = undefined;
-    } else {
-      scope.setPage({
-        number
-      });
-      bound = {
-        name: next.name,
-        value: next.value
-      };
-    }
-  }
-  return 'continue';
-}
-
-const FAIL = {
-  policy: 'fail'
-};
+
 /**
- * The policy for a failing step: the step's own, else the recipe's, else `fail`.
+ * The value of an HTML match.
  *
- * @param step - The step that failed.
- * @param recipe - Its recipe.
- * @returns The policy to apply.
+ * @param match - A selected element.
+ * @param take - What to take; `text` collapses whitespace.
+ * @returns The value; `undefined` for a missing attribute.
  */
-function resolveErrorPolicy(step, recipe) {
-  return step.onError ?? recipe.onError ?? FAIL;
+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));
 }
 /**
- * How long to wait before a retry: linear backoff.
+ * The value of a JSON match.
  *
- * @param policy - A retry policy.
- * @param attempt - The attempt about to be made, starting at 2.
- * @returns Milliseconds.
+ * @param node - A JSONPath result.
+ * @param take - `json` keeps the node; `text` stringifies scalars.
+ * @returns The value.
  */
-function backoffFor(policy, attempt) {
-  return (policy.backoffMs ?? 0) * (attempt - 1);
+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);
 }
-function sleep(ms) {
-  return ms <= 0 ? Promise.resolve() : new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * 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();
 }
 
-/** A response the recipe's `session.blockedWhen` rule (or the default one) says is the site refusing the crawl. */
-class BlockedError extends Error {
-  url;
-  status;
-  reason;
-  name = 'BlockedError';
-  constructor(url, status, reason) {
-    super(`blocked at ${url}: ${reason}`);
-    this.url = url;
-    this.status = status;
-    this.reason = reason;
-  }
+/**
+ * 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;
 }
-
-/** A step that failed under the `fail` policy: the recipe stops here. */
-class StepFailure extends Error {
-  stepPath;
-  stepType;
-  name = 'StepFailure';
-  constructor(stepPath, stepType, cause) {
-    super(`step ${stepPath} (${stepType}) failed: ${cause instanceof Error ? cause.message : String(cause)}`, {
-      cause
+/**
+ * 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
     });
-    this.stepPath = stepPath;
-    this.stepType = stepType;
-  }
-}
-/** A single `extract` that matched nothing. */
-class NoMatchError extends Error {
-  selector;
-  name = 'NoMatchError';
-  constructor(selector) {
-    super(`no match for ${selector}`);
-    this.selector = selector;
+    values.push(parsed.value);
   }
+  return values;
 }
-
 /**
- * Walks a step list in order. Control flow (`forEach`, `if`, `paginate`, `emit`,
- * `set`, `hook`, `when`, error policies) is handled here; leaf steps go to the
- * runner. Mode-agnostic: the same walk drives a browser page or an HTTP context.
+ * Parses text as JSON, wrappers removed (see {@link parseJsonLike}).
  *
- * @param steps - The steps.
- * @param scope - The scope to run in.
- * @param options - Recipe, runner, hooks, events and the emit callback.
- * @param path - Where these steps are, for messages and events.
- * @returns `stop` when the emit callback asked to stop.
- * @throws StepFailure when a step fails under the `fail` policy.
+ * @param text - The text.
+ * @returns The value, or `undefined` when it is not JSON.
  */
-async function runSteps(steps, scope, options, path = 'steps') {
-  for (const [index, step] of steps.entries()) {
-    if (step.when !== undefined && !isTruthy(render(step.when, lookupIn(scope)))) continue;
-    const at = `${path}.${index}`;
-    const walk = {
-      ...options,
-      path: at,
-      runSteps: (inner, innerScope, innerPath, overrides) => runSteps(inner, innerScope, {
-        ...options,
-        ...overrides
-      }, innerPath)
-    };
-    const outcome = await runWithPolicy(step, scope, walk);
-    if (outcome === 'stop') return 'stop';
-  }
-  return 'continue';
-}
-async function runWithPolicy(step, scope, walk) {
-  const policy = resolveErrorPolicy(step, walk.recipe);
-  const attempts = policy.policy === 'retry' ? policy.attempts : 1;
-  let attempt = 1;
-  for (;;) {
-    const started = Date.now();
-    walk.events.emit({
-      type: 'step:start',
-      recipeId: walk.recipe.id,
-      stepType: step.type,
-      stepId: step.id,
-      path: walk.path
-    });
-    try {
-      const outcome = await runOne(step, scope, walk);
-      walk.events.emit({
-        type: 'step:finish',
-        recipeId: walk.recipe.id,
-        stepType: step.type,
-        stepId: step.id,
-        path: walk.path,
-        durationMs: Date.now() - started
-      });
-      return outcome;
-    } catch (error) {
-      if (error instanceof StepFailure) throw error;
-      // A block the runner can rotate away from is retried on the new access, without spending a retry attempt.
-      if (error instanceof BlockedError && walk.runner.rotate !== undefined && (await walk.runner.rotate(error))) continue;
-      const message = error instanceof Error ? error.message : String(error);
-      if (policy.policy === 'retry' && attempt < attempts) {
-        attempt += 1;
-        walk.events.emit({
-          type: 'step:retry',
-          recipeId: walk.recipe.id,
-          stepType: step.type,
-          stepId: step.id,
-          path: walk.path,
-          attempt,
-          error: message
-        });
-        await sleep(backoffFor(policy, attempt));
-        continue;
-      }
-      if (policy.policy === 'skip') {
-        walk.events.emit({
-          type: 'step:skip',
-          recipeId: walk.recipe.id,
-          stepType: step.type,
-          stepId: step.id,
-          path: walk.path,
-          error: message
-        });
-        return 'continue';
-      }
-      throw new StepFailure(walk.path, step.type, error);
-    }
-  }
+function tryParseJson(text) {
+  const parsed = parseJsonLike(text);
+  return 'value' in parsed ? parsed.value : undefined;
 }
-async function runOne(step, scope, walk) {
-  switch (step.type) {
-    case 'forEach':
-      {
-        return runForEach(step, scope, walk);
-      }
-    case 'if':
-      {
-        const branch = isTruthy(render(step.test, lookupIn(scope))) ? 'then' : 'else';
-        walk.events.emit({
-          type: 'step:branch',
-          recipeId: walk.recipe.id,
-          path: walk.path,
-          branch
-        });
-        const chosen = branch === 'then' ? step.steps : step.else ?? [];
-        return walk.runSteps(chosen, scope, `${walk.path}.${branch === 'then' ? 'steps' : 'else'}`);
-      }
-    case 'paginate':
-      {
-        return runPaginate(step, scope, walk);
-      }
-    case 'emit':
-      {
-        return walk.onEmit(scope, step.output);
-      }
-    case 'set':
-      {
-        if (step.id !== undefined) scope.set(step.id, typeof step.value === 'string' ? render(step.value, lookupIn(scope)) : step.value);
-        return 'continue';
-      }
-    case 'collect':
-      {
-        const value = typeof step.value === 'string' ? render(step.value, lookupIn(scope)) : step.value;
-        if (value !== undefined) scope.append(step.into, Array.isArray(value) ? value : [value]);
-        return 'continue';
-      }
-    case 'hook':
-      {
-        const hook = walk.hooks.resolve(step.name);
-        const result = await hook(undefined, renderArgs(step.args ?? {}, scope), {
-          recipeId: walk.recipe.id,
-          scope: scope.snapshot(),
-          log: logThrough(walk)
-        });
-        if (step.id !== undefined) scope.set(step.id, result);
-        return 'continue';
-      }
-    default:
-      {
-        await walk.runner.runLeaf(step, scope);
-        return 'continue';
-      }
-  }
+/**
+ * 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;
 }
-function lookupIn(scope) {
-  return path => scope.lookup(path);
+/**
+ * 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 renderArgs(args, scope) {
-  return Object.fromEntries(Object.entries(args).map(([name, value]) => [name, typeof value === 'string' ? render(value, lookupIn(scope)) : value]));
+function itemsOf(parsed) {
+  if (parsed === undefined || parsed === null) return [];
+  return Array.isArray(parsed) ? parsed : [parsed];
 }
-function logThrough(walk) {
-  return (level, message, meta) => {
-    walk.events.emit({
-      type: level === 'error' ? 'error' : 'warning',
-      recipeId: walk.recipe.id,
-      message: `[${level}] ${message}`,
-      meta
-    });
-  };
+function parseJson$1(text) {
+  try {
+    return {
+      value: JSON.parse(text)
+    };
+  } catch (error) {
+    return {
+      error: error
+    };
+  }
 }
 
 /**
- * What bounds a recipe run: how many `forEach` iterations may be in flight and
- * how close together requests may start. One gate per recipe run, shared by
- * every loop in it, so nested loops never multiply the limit.
+ * 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.
  *
- * Permits go to the outermost concurrent loop: a loop that runs inside an
- * iteration already holding a permit runs its body sequentially (see `nested`),
- * which keeps the total at `permits` and cannot deadlock.
+ * @param document - The deck.
+ * @returns The text.
  */
-class RunGate {
-  permits;
-  minIntervalMs;
-  shared;
-  inFlight = 0;
-  waiting = [];
-  lastStart = -Infinity;
-  /**
-   * @param permits - Iterations allowed in flight; 1 is sequential.
-   * @param minIntervalMs - Minimum time between two request starts across the run.
-   * @param shared - The throttle state to share (internal: `nested` gates keep their parent's).
-   */
-  constructor(permits, minIntervalMs, shared) {
-    this.permits = permits;
-    this.minIntervalMs = minIntervalMs;
-    this.shared = shared;
-  }
-  /** Whether this gate lets more than one iteration run at once. */
-  get concurrent() {
-    return this.permits > 1;
-  }
-  /**
-   * Takes a permit, waiting for one when all are in flight.
-   *
-   * @returns The release; call it exactly once, when the iteration ends.
-   */
-  async acquire() {
-    if (this.inFlight >= this.permits) await new Promise(resolve => {
-      this.waiting.push(resolve);
-    });
-    this.inFlight += 1;
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      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);
-  }
+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);
 }
 
-/** 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.
+ * 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 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 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 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`);
+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 +2748,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 +2935,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 +2945,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 +2960,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))
   };
 }
 /**
@@ -2477,74 +3107,606 @@ function assignColumns(spans, headers) {
       };
     }));
   }
-  const last = table.at(-1) ?? [];
-  let column = last.reduce((best, score, index) => better(score, last[best]) ? index : best, 0);
-  const columns = [];
-  for (let index = table.length - 1; index >= 0; index -= 1) {
-    columns.unshift(column);
-    column = table[index][column].previous;
+  const last = table.at(-1) ?? [];
+  let column = last.reduce((best, score, index) => better(score, last[best]) ? index : best, 0);
+  const columns = [];
+  for (let index = table.length - 1; index >= 0; index -= 1) {
+    columns.unshift(column);
+    column = table[index][column].previous;
+  }
+  return columns;
+}
+function valuesOf(row, bands, width) {
+  const values = Array.from({
+    length: width
+  }, () => '');
+  const ordered = [...row.cells].sort((a, b) => b.y - a.y || a.x - b.x);
+  for (const cell of ordered) {
+    const band = lastOf(bands, candidate => candidate.start <= cell.x + 0.5) ?? bands[0];
+    if (band === undefined) continue;
+    values[band.column] = joinText(values[band.column], cell.text);
+  }
+  return values;
+}
+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 columns;
+  return tables;
 }
-function valuesOf(row, bands, width) {
-  const values = Array.from({
-    length: width
-  }, () => '');
-  const ordered = [...row.cells].sort((a, b) => b.y - a.y || a.x - b.x);
-  for (const cell of ordered) {
-    const band = lastOf(bands, candidate => candidate.start <= cell.x + 0.5) ?? bands[0];
-    if (band === undefined) continue;
-    values[band.column] = joinText(values[band.column], cell.text);
+/**
+ * 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 values;
+  return columns;
 }
-function named(values, headers, columns) {
-  if (columns === undefined) return Object.fromEntries(headers.map((header, index) => [header.text, values[index]]));
+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(columns)) {
-    const index = headers.findIndex(header => pattern.test(header.text));
-    if (index !== -1) record[key] = values[index];
+  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;
 }
-/** 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;
+/** 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 best;
+  return grid;
 }
-function overlapOf(header, band) {
-  return Math.max(0, Math.min(header.x + header.width, band.end) - Math.max(header.x, band.start));
+/** `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;
+}
+/** A row as a header pattern sees it: its non-empty cells, whitespace collapsed, joined by spaces. */
 function plain(row) {
-  return row.cells.map(cell => cell.text).join(' ');
+  return (row ?? []).map(text => clean(text)).filter(text => text !== '').join(' ');
 }
-function joinText(first, second) {
-  return first === '' ? second : second === '' ? first : `${first} ${second}`;
+function clean(cell) {
+  return String(cell).replaceAll(/\s+/g, ' ').trim();
 }
-function median(values) {
-  const ordered = [...values].sort((a, b) => a - b);
-  return ordered[Math.floor(ordered.length / 2)] ?? 0;
+
+/**
+ * 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 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 span(value) {
+  const number = Math.trunc(Number(value ?? '1'));
+  return Number.isFinite(number) && number > 0 ? Math.min(number, 1000) : 1;
+}
+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;
+}
+
+/**
+ * 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 +3725,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 +3768,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 +3853,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 +3871,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 +3908,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 +4053,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 +4168,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 +4194,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,22 +4302,54 @@ 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';
 }
 
 /**
@@ -2826,7 +4363,7 @@ 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);
@@ -2841,6 +4378,9 @@ async function sendRequest(step, scope, client, recipe, gate, events) {
       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
     });
   } catch (error) {
@@ -2866,6 +4406,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 +4422,22 @@ 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));
 }
+/** 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 +4458,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 +5544,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 +5555,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 => {
@@ -4185,18 +5747,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 +5776,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 +5850,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 +5858,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()
@@ -4293,6 +5883,7 @@ 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()
@@ -4337,9 +5928,10 @@ function accessOptions(lease, headers) {
  * @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).
  * @returns The state, or `undefined` when the recipe declares none.
  */
-async function resolveStorageState(recipe, deps, lease) {
+async function resolveStorageState(recipe, deps, lease, captcha) {
   const saved = await readSavedState(recipe, deps);
   const session = recipe.session;
   if (saved !== undefined || session?.bootstrap === undefined) return saved;
@@ -4351,7 +5943,7 @@ 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();
   }
@@ -4376,15 +5968,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, undefined, captcha);
   const scope = new ExtractionScope();
   scope.set('vars', recipe.vars ?? {});
   scope.set('start', {
@@ -4555,6 +6148,11 @@ 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);
@@ -4563,6 +6161,9 @@ async function runInputRecipe(input, output, deps) {
   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',
@@ -4573,11 +6174,18 @@ async function runInputRecipe(input, output, deps) {
   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 +6220,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',
@@ -4737,11 +6346,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 +6358,19 @@ 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);
+  const storageState = await resolveStorageState(input, deps, lease, captcha);
   const session = input.session;
   const access = accessOptions(lease, session?.headers);
   if (input.mode === 'web') {
@@ -4763,7 +6382,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,
@@ -4780,7 +6399,14 @@ async function openRunner(input, deps, gate, lease) {
  * 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`);
   const session = input.session;
   const storageState = await readSavedState(input, deps);
@@ -4791,12 +6417,12 @@ 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);
 }
 
 /**
@@ -4834,15 +6460,17 @@ 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 events = new EventBus(options.onEvent);
   let browser;
   const launch = () => {
@@ -4860,6 +6488,7 @@ function createCrawler(options = {}) {
       resume: options.resume === true,
       debug: options.debug === true,
       access,
+      captchaSolvers,
       ignoreHTTPSErrors: options.browser?.ignoreHTTPSErrors
     }, options.onRecipeError ?? 'continue'),
     async close() {
@@ -4877,7 +6506,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 +6519,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 +6684,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 +6706,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 +6746,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 +6787,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 +6935,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,7 +6961,8 @@ const sessionSpecSchema = z.strictObject({
   bootstrap: bootstrapSchema.optional(),
   access: sessionAccessSchema.optional(),
   blockedWhen: blockRuleSchema.optional(),
-  onBlock: blockRotationSchema.optional()
+  onBlock: blockRotationSchema.optional(),
+  captcha: captchaSettingsSchema.optional()
 });
 const limitsSchema = z.strictObject({
   maxRecords: z.int().positive().optional(),
@@ -5595,7 +7265,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 +7285,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 +7332,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 +7499,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, 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, traceLine, tryParseJson, validateBinding, workbookText };
 //# sourceMappingURL=index.esm.js.map