@opencraw/core 0.1.1 → 0.1.2

package/dist/src/index.d.ts

@@ -5,7 +5,7 @@ export type { Crawler, CrawlOptions, CrawlReport, RecipeReport } from './crawl-e
 export { loadRecipeSet, loadRecipes, readRecipeSource, bindRecipeSet, RecipeSet, RecipeBindingError, validateBinding } from './recipe-loading/index.js';
 export type { RecipeSetSource, RecipeSource, RecipeBytes, RecipeDocument, BindingIssue } from './recipe-loading/index.js';
 export { parseInputRecipe, parseOutputRecipe, RecipeValidationError, inputRecipeJsonSchema, outputRecipeJsonSchema, inputRecipeSchema, outputRecipeSchema } from './recipe-schema/index.js';
-export type { InputRecipe, OutputRecipe, FieldSpec, Step, StepType, MappingRule, TransformRule, ErrorPolicy, PaginateNext, SessionSpec, SessionAccess, RecipeIssue } from './recipe-schema/index.js';
+export type { InputRecipe, OutputRecipe, FieldSpec, Step, StepType, MappingRule, TransformRule, ErrorPolicy, PaginateNext, SessionSpec, SessionAccess, CaptchaSettings, CaptchaStep, RecipeIssue } from './recipe-schema/index.js';
 export type { Hook, HookMap, HookContext } from './hooks/index.js';
 export { UnknownHookError } from './hooks/index.js';
 export type { OutputRecord } from './output-mapping/index.js';
@@ -21,6 +21,14 @@ export type { HttpClientOptions, HttpRequest, HttpResponse, HttpBody } from './h
 export { tryParseJson } from './selection/index.js';
 export { readPdf, PdfReadError, findTables, pdfText } from './pdf-document/index.js';
 export type { PdfDocument, PdfPage, PdfRow, PdfCell, PdfTable, TableQuery, TableAlign } from './pdf-document/index.js';
+export { parseCsv, detectDelimiter, csvWorkbook, findGridTables, fillDown, workbookText, isWorkbookDocument, htmlTableSheets } from './workbook-document/index.js';
+export { readMarkdown } from './markdown-document/index.js';
+export { readYaml } from './yaml-document/index.js';
+export { findDeckTables, deckText, isDeckDocument } from './deck-document/index.js';
+export type { DeckDocument, DeckSlide, DeckShape, DeckChart, DeckTable, DeckTableQuery } from './deck-document/index.js';
+export type { WorkbookDocument, WorkbookCell, Sheet, CsvFormat, GridTable, GridTableQuery } from './workbook-document/index.js';
 export { StepFailure } from './step-flow/index.js';
 export { TransformError } from './transformation/index.js';
+export { CaptchaError, DEFAULT_CAPTCHA_SELECTOR, detectChallenge } from './captcha/index.js';
+export type { CaptchaSolver, CaptchaChallenge, CaptchaContext, CaptchaOutcome, CaptchaKind, CaptchaLog } from './captcha/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/markdown-document/index.d.ts

@@ -0,0 +1,3 @@
+export { readMarkdown } from './read-markdown.client.js';
+export type { MarkdownRead } from './read-markdown.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/markdown-document/read-markdown.client.d.ts

@@ -0,0 +1,29 @@
+/** Markdown, rendered. */
+export interface MarkdownRead {
+    /** A full HTML document: front matter in the head, the rendered body wrapped in sections. */
+    html: string;
+    /** The front matter's data, when there is some. */
+    frontMatter: unknown;
+    warnings: string[];
+}
+/**
+ * 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.
+ */
+export declare function readMarkdown(text: string, source: string): Promise<MarkdownRead>;
+//# sourceMappingURL=read-markdown.client.d.ts.map

package/dist/src/pdf-document/index.d.ts

@@ -1,7 +1,7 @@
 export { readPdf, PdfReadError } from './read-pdf.client.js';
 export { pdfText, isPdfDocument } from './pdf-document.model.js';
 export type { PdfDocument, PdfPage, PdfRow, PdfCell, PositionedText } from './pdf-document.model.js';
-export { assembleRows } from './row-assembly.algorithm.js';
+export { assembleRows, rowsOfCells } from './row-assembly.algorithm.js';
 export { findTables } from './pdf-table.algorithm.js';
 export type { PdfTable, TableQuery, TableAlign } from './pdf-table.algorithm.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/pdf-document/row-assembly.algorithm.d.ts

@@ -1,4 +1,4 @@
-import type { PdfRow, PositionedText } from './pdf-document.model.js';
+import type { PdfCell, PdfRow, PositionedText } from './pdf-document.model.js';
 /**
  * Turns a page's text runs into rows of cells, top to bottom.
  *
@@ -12,6 +12,15 @@ import type { PdfRow, PositionedText } from './pdf-document.model.js';
  * @returns The rows.
  */
 export declare function assembleRows(runs: readonly PositionedText[]): PdfRow[];
+/**
+ * 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.
+ */
+export declare function rowsOfCells(cells: readonly PdfCell[]): PdfRow[];
 /** `Array#findLast`, which the es2022 library does not declare. */
 export declare function lastOf<T>(items: readonly T[], test: (item: T) => boolean): T | undefined;
 //# sourceMappingURL=row-assembly.algorithm.d.ts.map

package/dist/src/recipe-loading/recipe-binding.validator.d.ts

@@ -14,7 +14,9 @@ import type { BindingIssue } from './recipe-binding.error.js';
  * - 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.

package/dist/src/recipe-schema/index.d.ts

@@ -2,11 +2,11 @@ export * from './recipe-kind.enum.js';
 export { fieldSpecSchema, outputRecipeSchema } from './output-recipe.contract.js';
 export type { FieldSpec, OutputRecipe } from './output-recipe.contract.js';
 export { stepSchema, errorPolicySchema, paginateNextSchema } from './step.contract.js';
-export type { Step, StepType, StepBaseFields, TargetFields, ErrorPolicy, PaginateNext, TakeKind, GotoStep, ClickStep, FillStep, PressStep, SelectStep, ScrollStep, WaitStep, EvaluateStep, ScreenshotStep, RequestStep, ExtractStep, SetStep, CollectStep, ForEachStep, IfStep, PaginateStep, EmitStep, HookStep, } from './step.contract.js';
+export type { Step, StepType, StepBaseFields, TargetFields, ErrorPolicy, PaginateNext, TakeKind, GotoStep, ClickStep, FillStep, PressStep, SelectStep, ScrollStep, WaitStep, EvaluateStep, ScreenshotStep, RequestStep, ExtractStep, SetStep, CollectStep, ForEachStep, IfStep, PaginateStep, EmitStep, HookStep, CaptchaStep, CaptchaCheck, } from './step.contract.js';
 export { transformRuleSchema, mappingRuleSchema } from './transform-rule.contract.js';
 export type { TransformRule, TransformOp, MappingRule, FromRule, EachRule } from './transform-rule.contract.js';
 export { inputRecipeSchema, sessionSpecSchema, startPointSchema } from './input-recipe.contract.js';
-export type { InputRecipe, SessionSpec, SessionBootstrap, SessionAccess, BlockRule, BlockRotation, StartPoint, CrawlLimits, RecipeCookie } from './input-recipe.contract.js';
+export type { InputRecipe, SessionSpec, SessionBootstrap, SessionAccess, BlockRule, BlockRotation, CaptchaSettings, StartPoint, CrawlLimits, RecipeCookie } from './input-recipe.contract.js';
 export { parseInputRecipe, parseOutputRecipe, recipeKindOf } from './recipe.validator.js';
 export { RecipeValidationError } from './recipe-validation.error.js';
 export type { RecipeIssue } from './recipe-validation.error.js';

package/dist/src/recipe-schema/input-recipe.contract.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { CrawlMode, KeepKind } from './recipe-kind.enum.js';
-import type { ErrorPolicy, Step } from './step.contract.js';
+import type { CaptchaCheck, ErrorPolicy, Step } from './step.contract.js';
 import type { MappingRule } from './transform-rule.contract.js';
 /** A URL the crawl starts from, with variables visible to its templates as `vars.*`. */
 export interface StartPoint {
@@ -49,12 +49,41 @@ export interface BlockRule {
     /** A regular expression the response body must match (case-insensitive). */
     text?: string;
 }
-/** What to do when blocked: take a new access lease (a new IP), reopen the session, and retry the step. */
+/**
+ * What to do when blocked. `solve`: when the block page shows a captcha, the
+ * `session.captcha` solver solves it on the spot. `rotate`: take a new access
+ * lease (a new IP), reopen the session, and retry the step; with `solve`, only
+ * once solving failed.
+ */
 export interface BlockRotation {
-    rotate: boolean;
+    rotate?: boolean;
+    solve?: boolean;
     /** How many rotations a recipe run may use. Default 2. */
     attempts?: number;
 }
+/**
+ * How a web recipe gets past captchas: a solver the runner registered (a
+ * plugin's `captchaSolvers`), where to look for challenges, how to confirm
+ * one is solved, and what the run may spend. With it, the engine checks for a
+ * challenge after each navigation, click and key press, and solves it before
+ * the next step runs.
+ */
+export interface CaptchaSettings {
+    /** The name of a registered captcha solver. */
+    solver: string;
+    /** Where challenges are (a Playwright selector); the common widgets when omitted. */
+    detect?: {
+        selector: string;
+    };
+    /** How a solve is confirmed. Default: the challenge is gone. */
+    verify?: CaptchaCheck;
+    /** Solves tried per challenge before it counts as a block. Default 3. */
+    attempts?: number;
+    /** How long one solve may take. Default 120000. */
+    timeoutMs?: number;
+    /** Solves the whole run may spend (a paid solver bills each). Default 10; 0 detects without solving. */
+    maxSolves?: number;
+}
 export interface SessionSpec {
     headers?: Record<string, string>;
     cookies?: RecipeCookie[];
@@ -69,6 +98,7 @@ export interface SessionSpec {
     access?: SessionAccess;
     blockedWhen?: BlockRule;
     onBlock?: BlockRotation;
+    captcha?: CaptchaSettings;
 }
 export interface CrawlLimits {
     maxRecords?: number;

package/dist/src/recipe-schema/recipe-kind.enum.d.ts

@@ -4,7 +4,8 @@ export declare const CRAWL_MODES: readonly ["web", "api"];
 export declare const SELECTOR_KINDS: readonly ["css", "xpath", "jsonpath", "regex", "table"];
 /** `take` also accepts `attr:<name>`, which is validated by pattern rather than listed. */
 export declare const TAKE_KINDS: readonly ["text", "html", "value", "json"];
-export declare const BODY_KINDS: readonly ["json", "html", "text", "pdf"];
+export declare const BODY_KINDS: readonly ["json", "jsonl", "html", "text", "pdf", "csv", "xlsx", "pptx", "yaml", "markdown"];
+export declare const YAML_SCALARS: readonly ["typed", "text"];
 /** How a PDF table aligns a row's values against a cell wrapped over several lines. */
 export declare const TABLE_ALIGNS: readonly ["auto", "top", "center", "bottom"];
 export declare const FIELD_TYPES: readonly ["string", "number", "integer", "boolean", "date", "datetime", "currency", "url", "enum", "array", "object", "json"];
@@ -16,7 +17,7 @@ export declare const KEEP_KINDS: readonly ["cookies", "localStorage"];
 export declare const WAIT_UNTIL: readonly ["load", "domcontentloaded", "networkidle", "commit"];
 export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
 /** Steps that only make sense with a live browser page. */
-export declare const WEB_ONLY_STEPS: readonly ["goto", "click", "fill", "press", "select", "scroll", "wait", "evaluate", "screenshot"];
+export declare const WEB_ONLY_STEPS: readonly ["goto", "click", "fill", "press", "select", "scroll", "wait", "evaluate", "screenshot", "captcha"];
 /** Steps that only make sense against an HTTP request context. */
 export declare const API_ONLY_STEPS: readonly ["request"];
 export type RecipeKind = typeof RECIPE_KINDS[number];

package/dist/src/recipe-schema/step.contract.d.ts

@@ -86,6 +86,12 @@ export interface RequestStep extends StepBaseFields {
     headers?: Record<string, string>;
     body?: unknown;
     as?: BodyKind;
+    /** The body's text encoding (a WHATWG label, `windows-1252`); default: the BOM, the declared charset, UTF-8, else Windows-1252. */
+    encoding?: string;
+    /** A CSV body's delimiter (one character); default: detected among `,` `;` tab `|`. */
+    delimiter?: string;
+    /** A YAML body's scalars: `typed` (default, YAML 1.2) or `text`, every scalar as written (`0123` stays `"0123"`). */
+    scalars?: 'typed' | 'text';
 }
 export interface ExtractStep extends StepBaseFields {
     type: 'extract';
@@ -99,8 +105,20 @@ export interface ExtractStep extends StepBaseFields {
     columns?: Record<string, string>;
     /** `table` only: a pattern (case-insensitive) for the row that ends a table. */
     until?: string;
-    /** `table` only: how a row's values sit against a cell wrapped over several lines; default `auto`. */
+    /** `table` only: how a row's values sit against a cell wrapped over several lines (PDF); default `auto`. */
     align?: TableAlign;
+    /** `table` only: a pattern (case-insensitive) for the names of the sheets to read (workbook); default every sheet. */
+    sheet?: string;
+    /** `table` only: how many rows the header spans (workbook); a column's key joins its header texts. Default 1. */
+    headerRows?: number;
+    /** `table` only: output keys whose empty cells take the value of the row above. */
+    fillDown?: string[];
+    /** `table` only: read hidden sheets and rows (workbook) or hidden slides (deck) too. */
+    includeHidden?: boolean;
+    /** `table` only: a pattern (case-insensitive) for the titles of the slides to read (deck); default every slide. */
+    slide?: string;
+    /** `table` only: read text boxes laid out as a table instead of native tables (deck). */
+    shapes?: boolean;
 }
 export interface SetStep extends StepBaseFields {
     type: 'set';
@@ -150,9 +168,35 @@ export interface HookStep extends StepBaseFields {
     name: string;
     args?: Record<string, unknown>;
 }
-export type Step = GotoStep | ClickStep | FillStep | PressStep | SelectStep | ScrollStep | WaitStep | EvaluateStep | ScreenshotStep | RequestStep | ExtractStep | SetStep | CollectStep | ForEachStep | IfStep | PaginateStep | EmitStep | HookStep;
+/**
+ * How the engine confirms a captcha was solved (it never takes the solver's
+ * word): the challenge is gone, and/or an element appears.
+ */
+export interface CaptchaCheck {
+    /** The detected challenge must be off the page. Default `true`. */
+    gone?: boolean;
+    /** An element that must appear once solved. */
+    selector?: string;
+}
+/**
+ * Solves the captcha on the live page, if there is one (none is not an error):
+ * a challenge known to sit at one point of the crawl, a login form. The solver
+ * and the defaults come from `session.captcha`, unless the step names its own.
+ */
+export interface CaptchaStep extends StepBaseFields {
+    type: 'captcha';
+    /** A captcha solver the runner registered; `session.captcha.solver` when omitted. */
+    solver?: string;
+    /** Where the challenge is (a Playwright selector); the common widgets when omitted. */
+    selector?: string;
+    verify?: CaptchaCheck;
+    attempts?: number;
+    timeoutMs?: number;
+}
+export type Step = GotoStep | ClickStep | FillStep | PressStep | SelectStep | ScrollStep | WaitStep | EvaluateStep | ScreenshotStep | RequestStep | ExtractStep | SetStep | CollectStep | ForEachStep | IfStep | PaginateStep | EmitStep | HookStep | CaptchaStep;
 export type StepType = Step['type'];
 export declare const errorPolicySchema: z.ZodType<ErrorPolicy>;
 export declare const paginateNextSchema: z.ZodType<PaginateNext>;
+export declare const captchaCheckSchema: z.ZodType<CaptchaCheck>;
 export declare const stepSchema: z.ZodType<Step>;
 //# sourceMappingURL=step.contract.d.ts.map

package/dist/src/selection/index.d.ts

@@ -4,5 +4,5 @@ export { selectHtml } from './html-selector.algorithm.js';
 export type { HtmlMatch } from './html-selector.algorithm.js';
 export { takeFromHtml, takeFromJson, collapse } from './take-value.mapper.js';
 export type { Take } from './take-value.mapper.js';
-export { tryParseJson, parseJsonText, dataItemsOf } from './json-text.algorithm.js';
+export { tryParseJson, parseJsonText, dataItemsOf, parseJsonLike, parseJsonLines } from './json-text.algorithm.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/selection/json-text.algorithm.d.ts

@@ -1,10 +1,37 @@
 /**
  * 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.
+ * `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.
  */
 /**
- * Parses text as JSON, guards stripped.
+ * 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.
+ */
+export declare function parseJsonLike(text: string): {
+    value: unknown;
+} | {
+    error: Error;
+};
+/**
+ * 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.
+ */
+export declare function parseJsonLines(text: string, source: string): unknown[];
+/**
+ * Parses text as JSON, wrappers removed (see {@link parseJsonLike}).
  *
  * @param text - The text.
  * @returns The value, or `undefined` when it is not JSON.

package/dist/src/web-steps/run-web-step.use-case.d.ts

@@ -1,19 +1,27 @@
 import type { BrowserSession } from '../browser-session/index.js';
+import type { CaptchaGuard } from '../captcha/index.js';
 import type { EventBus } from '../crawl-events/index.js';
 import type { ExtractionScope, LiveElement } from '../extraction-scope/index.js';
 import type { InputRecipe, PaginateNext, Step } from '../recipe-schema/index.js';
 import { RunGate } from '../step-flow/index.js';
 import type { NextPageResult, StepRunner } from '../step-flow/index.js';
-/** Runs web-mode leaf steps on a browser page. */
+/**
+ * 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.
+ */
 export declare class WebStepRunner implements StepRunner {
     private readonly session;
     private readonly recipe;
     private readonly events;
     private readonly gate;
+    private readonly captcha?;
     private readonly page;
-    constructor(session: BrowserSession, recipe: InputRecipe, events: EventBus, gate?: RunGate);
+    constructor(session: BrowserSession, recipe: InputRecipe, events: EventBus, gate?: RunGate, captcha?: CaptchaGuard | undefined);
     /** Clicks and key presses can navigate; keep `page.url` honest after every leaf step. */
     private trackUrl;
+    /** Navigates; a block page showing a captcha is solved under `onBlock.solve`, and a page reached is checked for one. */
+    private visit;
     runLeaf(step: Step, scope: ExtractionScope): Promise<void>;
     nextPage(next: PaginateNext, scope: ExtractionScope): Promise<NextPageResult>;
     elements(selector: string): Promise<LiveElement[]>;

package/dist/src/workbook-document/csv-parser.algorithm.d.ts

@@ -0,0 +1,26 @@
+/** The delimiters detection chooses between, in order of preference on a tie. */
+export declare const CSV_DELIMITERS: readonly [",", ";", "\t", "|"];
+/**
+ * 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.
+ */
+export declare function parseCsv(text: string, delimiter: string): string[][];
+/**
+ * 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.
+ */
+export declare function detectDelimiter(text: string): string;
+//# sourceMappingURL=csv-parser.algorithm.d.ts.map

package/dist/src/workbook-document/csv-workbook.mapper.d.ts

@@ -0,0 +1,24 @@
+import type { WorkbookDocument } from './workbook-document.model.js';
+/**
+ * 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.
+ */
+export declare function csvWorkbook(text: string, options: {
+    name: string;
+    encoding: string;
+    delimiter?: string;
+}): WorkbookDocument;
+/**
+ * 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.
+ */
+export declare function sheetNameOf(url: string): string;
+//# sourceMappingURL=csv-workbook.mapper.d.ts.map

package/dist/src/workbook-document/grid-table.algorithm.d.ts

@@ -0,0 +1,53 @@
+import type { WorkbookCell, WorkbookDocument } from './workbook-document.model.js';
+/** What a table extract looks for in a workbook. */
+export interface GridTableQuery {
+    /** Matches a table's (first) header row: its non-empty cells joined by spaces, whitespace collapsed. */
+    header: RegExp;
+    /** Matches the row that ends a table; a table also ends at the next header or the sheet's end. `^$` ends it at the first empty row. */
+    until?: RegExp;
+    /** Output key -> a pattern for that column's header; unmatched columns are dropped. Without it, the headers are the keys. */
+    columns?: Record<string, RegExp>;
+    /** Matches the names of the sheets to read; default every sheet. */
+    sheet?: RegExp;
+    /** How many rows the header spans (default 1): a column's key joins its header texts. */
+    headerRows?: number;
+    /** Output keys whose empty cells take the value of the row above. */
+    fillDown?: string[];
+    /** Read hidden sheets and hidden rows too. */
+    includeHidden?: boolean;
+}
+/** One table found in a workbook. */
+export interface GridTable {
+    sheet: string;
+    /** The first header cell: the table's name when it has one. */
+    title: string;
+    /** The column keys, left to right. */
+    header: string[];
+    /** One object per row, keyed by column; text trimmed, numbers and booleans as they are. */
+    rows: Record<string, WorkbookCell>[];
+}
+/**
+ * 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.
+ */
+export declare function findGridTables(document: WorkbookDocument, query: GridTableQuery): GridTable[];
+/**
+ * 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).
+ */
+export declare function fillDown<Row extends Record<string, unknown>>(rows: readonly Row[], keys: readonly string[]): Row[];
+//# sourceMappingURL=grid-table.algorithm.d.ts.map

package/dist/src/workbook-document/html-tables.mapper.d.ts

@@ -0,0 +1,14 @@
+import type { Sheet } from './workbook-document.model.js';
+/**
+ * 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.
+ */
+export declare function htmlTableSheets(html: string): Sheet[];
+//# sourceMappingURL=html-tables.mapper.d.ts.map

package/dist/src/workbook-document/index.d.ts

@@ -0,0 +1,9 @@
+export { workbookText, isWorkbookDocument } from './workbook-document.model.js';
+export type { WorkbookDocument, Sheet, CsvFormat, WorkbookCell } from './workbook-document.model.js';
+export { parseCsv, detectDelimiter, CSV_DELIMITERS } from './csv-parser.algorithm.js';
+export { csvWorkbook, sheetNameOf } from './csv-workbook.mapper.js';
+export { readXlsxWorkbook } from './read-xlsx.client.js';
+export { findGridTables, fillDown } from './grid-table.algorithm.js';
+export { htmlTableSheets } from './html-tables.mapper.js';
+export type { GridTable, GridTableQuery } from './grid-table.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/workbook-document/read-xlsx.client.d.ts

@@ -0,0 +1,18 @@
+import type { WorkbookDocument } from './workbook-document.model.js';
+/**
+ * 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`…).
+ */
+export declare function readXlsxWorkbook(bytes: Uint8Array, source: string): Promise<WorkbookDocument>;
+//# sourceMappingURL=read-xlsx.client.d.ts.map

package/dist/src/workbook-document/workbook-document.model.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A cell: text, or, from a spreadsheet, the number or boolean it holds
+ * (`13955.625` stays a number, so no locale guess can misread it). Dates are
+ * ISO text (`2026-06-01`, `2026-06-01T09:30:00`), errors their text
+ * (`#DIV/0!`), an empty cell `''`. A CSV's cells are all text.
+ */
+export type WorkbookCell = string | number | boolean;
+/** One sheet of a workbook. A CSV is a workbook of one sheet. */
+export interface Sheet {
+    name: string;
+    /** Top to bottom; a row holds as many cells as were read (rows can be ragged). */
+    rows: WorkbookCell[][];
+    /** A sheet hidden in the workbook: `table` skips it unless `includeHidden`. */
+    hidden?: boolean;
+    /** Rows hidden in the sheet (0-based): `table` skips them unless `includeHidden`. */
+    hiddenRows?: number[];
+    /**
+     * Merged ranges as A1 references (`B10:B13`). The value of a merged range
+     * sits in its top-left cell only, as the file stores it; `table` copies it
+     * into every cell the range covers.
+     */
+    merges?: string[];
+}
+/** How a CSV was read, for a probe to report. */
+export interface CsvFormat {
+    encoding: string;
+    delimiter: string;
+}
+/** A spreadsheet or a CSV read into sheets of cells: what `extract` works on. */
+export interface WorkbookDocument {
+    kind: 'workbook';
+    sheets: Sheet[];
+    /** Present when the workbook came from a CSV. */
+    csv?: CsvFormat;
+}
+/**
+ * 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.
+ */
+export declare function workbookText(document: WorkbookDocument): string;
+/**
+ * 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}.
+ */
+export declare function isWorkbookDocument(value: unknown): value is WorkbookDocument;
+//# sourceMappingURL=workbook-document.model.d.ts.map

package/dist/src/yaml-document/index.d.ts

@@ -0,0 +1,3 @@
+export { readYaml } from './read-yaml.client.js';
+export type { YamlRead, YamlScalars } from './read-yaml.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/yaml-document/read-yaml.client.d.ts

@@ -0,0 +1,25 @@
+/** How YAML scalars are read: typed as YAML 1.2 types them, or as the text written. */
+export type YamlScalars = 'typed' | 'text';
+/** A YAML text, read. */
+export interface YamlRead {
+    /** The document's value; several documents (`---`) give an array of their values. */
+    data: unknown;
+    documents: number;
+    /** What the parser noticed but read anyway: an unknown tag (`!!js/function`) is kept as its plain value. */
+    warnings: string[];
+}
+/**
+ * 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.
+ */
+export declare function readYaml(text: string, source: string, scalars?: YamlScalars): Promise<YamlRead>;
+//# sourceMappingURL=read-yaml.client.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.esm.js",
   "module": "./dist/index.esm.js",
@@ -20,11 +20,14 @@
     "!**/*.js.map"
   ],
   "dependencies": {
+    "@opencraw/office-reader": "^0.0.2",
     "cheerio": "^1.2.0",
     "domhandler": "^6.0.1",
     "jsonpath-plus": "^10.4.0",
+    "marked": "^18.0.14",
     "pdfjs-dist": "^6.3.289",
     "playwright": "^1.63.0",
+    "yaml": "^2.9.1",
     "zod": "^4.6.5"
   },
   "publishConfig": {
@@ -54,7 +57,8 @@
       "e2e": {
         "executor": "nx:run-commands",
         "dependsOn": [
-          "build"
+          "build",
+          "^build"
         ],
         "options": {
           "command": "tsc -p tsconfig.e2e.json && jest --config jest.e2e.config.cts",
@@ -70,6 +74,16 @@
           "command": "node tools/emit-json-schemas.mjs",
           "cwd": "packages/core"
         }
+      },
+      "typecheck": {
+        "dependsOn": [
+          "^build"
+        ]
+      },
+      "lint": {
+        "dependsOn": [
+          "^build"
+        ]
       }
     }
   }