@opencraw/core 0.1.1 → 0.1.3

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/step-flow/for-each.use-case.d.ts

@@ -6,8 +6,10 @@ import type { EmitOutcome, StepWalk } from './run-steps.use-case.js';
  * 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.
+ * With a concurrent gate, iterations of a list run as permits allow and
+ * records come out in completion order; without one, in list order. In web
+ * mode each parallel iteration runs in a tab of its own (`runner.fork`); a
+ * loop over live elements stays sequential, since its elements live on one page.
  *
  * @param step - The forEach step.
  * @param scope - The scope the list lives in.

package/dist/src/step-flow/host-throttle.policy.d.ts

@@ -0,0 +1,49 @@
+/** How gently one site is crawled. */
+export interface HostRule {
+    /** Minimum time between two request starts to the site, whatever recipe sends them. */
+    delayMs?: number;
+    /** Requests to the site in flight at once. */
+    concurrency?: number;
+}
+/**
+ * The crawler's politeness towards each site, across every recipe and run it
+ * executes: a default rule for any host, and rules by domain (`example.com`
+ * also covers `www.example.com`; the longest match wins).
+ */
+export interface ThrottleConfig extends HostRule {
+    domains?: Record<string, HostRule>;
+}
+/**
+ * Spaces and bounds requests per site, shared by every recipe of a crawler,
+ * so two recipes (or two parallel iterations) that hit one site add up to one
+ * polite client rather than two. A recipe's own `limits.delayMs` still applies
+ * on top, per recipe.
+ *
+ * Like a single-lane bridge with a traffic light: whoever arrives waits for
+ * the car ahead to be far enough, and for a free lane.
+ */
+export declare class HostThrottle {
+    private readonly config;
+    private readonly buckets;
+    private readonly domains;
+    constructor(config?: ThrottleConfig);
+    private bucketFor;
+    /** Whether any rule can hold a request back. */
+    get active(): boolean;
+    /**
+     * Waits until a request to `url` may start, then holds one of its site's
+     * lanes until the returned release is called.
+     *
+     * @param url - Where the request goes; anything but `http(s):` passes at once.
+     * @returns The release: call it once, when the response arrived or the request failed.
+     */
+    slot(url: string): Promise<() => void>;
+    /**
+     * Holds every request to the site of `url` back until `untilMs` (a `Retry-After`).
+     *
+     * @param url - A URL of the site.
+     * @param untilMs - An epoch time.
+     */
+    pause(url: string, untilMs: number): void;
+}
+//# sourceMappingURL=host-throttle.policy.d.ts.map

package/dist/src/step-flow/index.d.ts

@@ -1,9 +1,14 @@
 export { runSteps } from './run-steps.use-case.js';
 export type { StepWalkOptions, EmitOutcome } from './run-steps.use-case.js';
 export type { StepRunner, NextPageResult } from './step-runner.contract.js';
+export { disposeQuietly } from './step-runner.contract.js';
 export { StepFailure, NoMatchError } from './step-failure.error.js';
 export { resolveErrorPolicy, backoffFor, sleep } from './retry.policy.js';
 export { RunGate } from './run-gate.policy.js';
+export { HostThrottle } from './host-throttle.policy.js';
+export { withTransportRetry, resolveRetryRule, transientError, retryDelay, DEFAULT_RETRY_RULE, RETRY_STATUSES } from './transport-retry.policy.js';
+export type { ResolvedRetryRule, Transient, TransportAttempt, RetryContext } from './transport-retry.policy.js';
+export type { HostRule, ThrottleConfig } from './host-throttle.policy.js';
 export { BlockedError } from './blocked.error.js';
 export { detectBlock, DEFAULT_BLOCK_RULE } from './block-rule.policy.js';
 export type { ObservedResponse } from './block-rule.policy.js';

package/dist/src/step-flow/run-gate.policy.d.ts

@@ -1,3 +1,4 @@
+import type { HostThrottle } from './host-throttle.policy.js';
 /**
  * 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
@@ -10,6 +11,7 @@
 export declare class RunGate {
     readonly permits: number;
     readonly minIntervalMs: number;
+    readonly hosts?: HostThrottle | undefined;
     private readonly shared?;
     private inFlight;
     private readonly waiting;
@@ -17,9 +19,10 @@ export declare class RunGate {
     /**
      * @param permits - Iterations allowed in flight; 1 is sequential.
      * @param minIntervalMs - Minimum time between two request starts across the run.
+     * @param hosts - The crawler's per-site throttle, shared with every other recipe.
      * @param shared - The throttle state to share (internal: `nested` gates keep their parent's).
      */
-    constructor(permits: number, minIntervalMs: number, shared?: RunGate | undefined);
+    constructor(permits: number, minIntervalMs: number, hosts?: HostThrottle | undefined, shared?: RunGate | undefined);
     /** Whether this gate lets more than one iteration run at once. */
     get concurrent(): boolean;
     /**
@@ -33,6 +36,14 @@ export declare class RunGate {
      * whichever loop started it. Returns at once when the interval has passed.
      */
     throttle(): Promise<void>;
+    /**
+     * Waits until a request to `url` may start: the recipe's interval, then its
+     * site's turn in the crawler's per-site throttle.
+     *
+     * @param url - Where the request goes.
+     * @returns The release of the site's lane: call it once the response arrived or the request failed.
+     */
+    request(url: string): Promise<() => void>;
     /** The gate for a body running inside an iteration that holds a permit: sequential, same throttle. */
     nested(): RunGate;
 }

package/dist/src/step-flow/step-runner.contract.d.ts

@@ -1,6 +1,13 @@
 import type { ExtractionScope, LiveElement } from '../extraction-scope/index.js';
 import type { PaginateNext, Step } from '../recipe-schema/index.js';
 import type { BlockedError } from './blocked.error.js';
+/**
+ * Disposes a runner, ignoring a failure: a tab whose browser already went
+ * away (a rotation, a crash) has nothing left to close.
+ *
+ * @param runner - The runner.
+ */
+export declare function disposeQuietly(runner: StepRunner): Promise<void>;
 /** What `paginate` learns from the runner after a page body ran. */
 export type NextPageResult = 
 /** The next page is at this URL (the runner already navigated in web mode). */
@@ -34,6 +41,12 @@ export interface StepRunner {
      * `false` means it cannot, and the block fails the step like any error.
      */
     rotate?: (error: BlockedError) => Promise<boolean>;
+    /**
+     * A runner of its own for one parallel `forEach` iteration: a new tab in the
+     * same browser context (same cookies, its own page), disposed when the
+     * iteration ends. Web mode; an api runner is shared as it is.
+     */
+    fork?: () => Promise<StepRunner>;
     dispose: () => Promise<void>;
 }
 //# sourceMappingURL=step-runner.contract.d.ts.map

package/dist/src/step-flow/transport-retry.policy.d.ts

@@ -0,0 +1,76 @@
+import type { EventBus } from '../crawl-events/index.js';
+import type { RetryRule } from '../recipe-schema/index.js';
+import type { RunGate } from './run-gate.policy.js';
+/** A retry rule with every default filled in. */
+export type ResolvedRetryRule = Required<RetryRule>;
+/** Statuses a server uses for "not now": timeout, too early, too many requests, and the 5xx that pass. */
+export declare const RETRY_STATUSES: readonly number[];
+/** Three tries, one second then two apart, never a wait over 30 seconds. */
+export declare const DEFAULT_RETRY_RULE: ResolvedRetryRule;
+/** Why an attempt may be worth repeating, and the server's own `Retry-After`, if it sent one. */
+export interface Transient {
+    reason: string;
+    retryAfter?: string;
+}
+/** One try of a request, and how to tell a passing failure in what it gave. */
+export interface TransportAttempt<T> {
+    run: () => Promise<T>;
+    /** A transient problem in the outcome (a retry status, a connection error), or `undefined` when the outcome stands. */
+    problem: (outcome: {
+        value: T;
+    } | {
+        error: unknown;
+    }) => Transient | undefined;
+}
+export interface RetryContext {
+    recipeId: string;
+    gate: RunGate;
+    events: EventBus;
+    rule: ResolvedRetryRule;
+}
+/**
+ * The retry rule a recipe runs with: its `limits.retry` over the crawler's
+ * default over `DEFAULT_RETRY_RULE`.
+ *
+ * @param own - The recipe's `limits.retry`.
+ * @param crawler - The crawler's `retry` option.
+ * @returns The rule.
+ */
+export declare function resolveRetryRule(own?: RetryRule, crawler?: RetryRule): ResolvedRetryRule;
+/**
+ * Whether an error is a connection failure worth another try.
+ *
+ * @param error - What the request threw.
+ * @returns The reason, or `undefined`.
+ */
+export declare function transientError(error: unknown): Transient | undefined;
+/**
+ * How long to wait before attempt `attempt + 1`: the server's `Retry-After`
+ * when it gave one, else `backoffMs` doubling per attempt with a little
+ * jitter; `undefined` when the server asks for longer than `maxDelayMs` (it
+ * means "come back much later", which a crawl cannot wait for).
+ *
+ * @param rule - The retry rule.
+ * @param attempt - The attempt that just failed, from 1.
+ * @param retryAfter - The `Retry-After` header: seconds, or an HTTP date.
+ * @param now - The current time, for dates.
+ * @returns Milliseconds, or `undefined` for no retry.
+ */
+export declare function retryDelay(rule: ResolvedRetryRule, attempt: number, retryAfter?: string, now?: number): number | undefined;
+/**
+ * Sends a request through the gate (the recipe's rate, the site's lane), and
+ * sends it again after a pause while it fails in a passing way, up to
+ * `rule.attempts` tries in all. A `Retry-After` holds back every request to
+ * that site, not only this one. Each retry is reported as `request:retry`.
+ *
+ * Like redialling a busy number: wait a moment, dial again, give up after a
+ * few tries; and if the other end said "call back in a minute", wait that minute.
+ *
+ * @param url - Where the request goes.
+ * @param attempt - How to send it and how to judge the outcome.
+ * @param context - The recipe, gate, events and rule.
+ * @returns What the last try gave.
+ * @throws What the last try threw.
+ */
+export declare function withTransportRetry<T>(url: string, attempt: TransportAttempt<T>, context: RetryContext): Promise<T>;
+//# sourceMappingURL=transport-retry.policy.d.ts.map

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

@@ -5,8 +5,9 @@ import type { GotoStep, InputRecipe } from '../recipe-schema/index.js';
 import type { RunGate } from '../step-flow/index.js';
 /**
  * Runs a `goto` step: renders the URL (relative to the current page), waits for
- * the gate's throttle (`delayMs`), navigates, records the page's real URL in the
- * scope, and checks the response against the recipe's block rule.
+ * the gate's throttle (`delayMs`), navigates (again, after a pause, while it
+ * fails in passing: `limits.retry`), records the page's real URL in the scope,
+ * and checks the response against the recipe's block rule.
  *
  * @throws BlockedError when the response is a block.
  */

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

@@ -1,21 +1,36 @@
-import type { BrowserSession } from '../browser-session/index.js';
+import { 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>;
+    /**
+     * A runner on a new tab of the same context, for one parallel iteration:
+     * it shares cookies, the gate and the captcha guard; disposing it closes the tab only.
+     *
+     * @returns The forked runner.
+     */
+    fork(): Promise<WebStepRunner>;
     elements(selector: string): Promise<LiveElement[]>;
     dispose(): Promise<void>;
 }

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.3",
   "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"
+        ]
       }
     }
   }