@jokerized/decksmith 0.3.0 → 0.3.2

package/dist/types/server/pipeline.d.ts

@@ -1,21 +1,44 @@
-import { type ImageProvider, type Runner } from "../index.js";
+import { type HarvestOptions, type ImageProvider, type Runner, type Source } from "../index.js";
 import type { JobOptions } from "./options.js";
 import type { JobHandle, JobResult, Stage } from "./queue.js";
 import { type Upload } from "./upload.js";
 export interface PipelineInput {
-    upload: Upload;
+    /**
+     * The document that arrived, when a file was posted. Exactly one of this and
+     * `url` is set — `parseSubmission` is what guarantees it, and `ingest` refuses
+     * loudly rather than guessing if a direct caller hands it both or neither.
+     */
+    upload?: Upload;
+    /** The page to harvest, when a URL was posted instead of a file. */
+    url?: string;
     options: JobOptions;
     /**
      * Whether a figure named by an http(s) URL may be downloaded.
      *
-     * OFF by default, and that is a security decision, not a performance one. The
-     * document is a stranger's; `![](http://169.254.169.254/latest/meta-data/)` is
-     * a request this process would make from inside the network it runs in, and a
-     * hostname allowlist does not close it because DNS can answer differently the
-     * second time. Off, the figure is dropped and named in the warnings. On (the
-     * owner's own box, own papers), it is fetched with a count and a timeout.
+     * ON by default — src/server/main.ts sets `DECKSMITH_FETCH_FIGURES` to true —
+     * because a paper's markdown links its images and a deck that silently drops
+     * them is not the deck anyone asked for. The flag is therefore NOT the guard;
+     * `guardFigures` below is, and it refuses any URL resolving to a private,
+     * loopback or link-local address before the fetch is attempted.
+     *
+     * When it is on, the fetch itself is `fetchGuarded` in src/net/fetch.ts by way
+     * of `fetchFigures`: a 32 MB streaming cap and a 20s whole-call timeout at the
+     * socket, with the connection PINNED to the address that was validated. That
+     * last part is what closed the DNS-rebinding hole an earlier version of this
+     * comment called unclosable. `MAX_REMOTE_FIGURES` below is the count.
+     *
+     * Off, a remote figure is dropped and named in the warnings.
      */
     fetchRemoteFigures: boolean;
+    /**
+     * Caps for the harvest of `url`, overriding `HARVEST_LIMITS`.
+     *
+     * TEST SEAM, the same shape as `imageChain` and `run` below. It is the only
+     * way to point a harvest at a `node:http` server on loopback, which is what
+     * test/server.test.ts needs to drive this path with no network. Nothing in
+     * src/ sets it, so production always gets `HARVEST_LIMITS` exactly.
+     */
+    harvest?: HarvestOptions;
     /**
      * The rungs `illustrate` draws through. A test injects the tool's own SVG and
      * nothing else; absent, the stage resolves its providers from the environment
@@ -33,3 +56,23 @@ export interface PipelineInput {
 /** Which rows the step list should have, decided before anything runs. */
 export declare function stagesFor(options: JobOptions): Stage[];
 export declare function runPipeline(job: JobHandle, input: PipelineInput): Promise<JobResult>;
+/**
+ * Rewrite every figure's `src` to something safe to read, or drop the figure.
+ *
+ * `fetchFigures` does `readFile(src)` for anything that is not an http URL, and
+ * `src` is whatever the document's markdown said. A document containing
+ * `![](../../../../etc/ssh/ssh_host_rsa_key)` would otherwise have this process
+ * read it — the image sniffer rejects it a moment later, but the read already
+ * happened and the error message quotes the path. So relative paths are resolved
+ * inside the upload directory and confined there, and everything else is dropped
+ * unless remote fetching has been deliberately switched on.
+ *
+ * Dropped figures leave before the planner sees the source, so no beat can cite
+ * one and `assertRefsResolve` has nothing to fail on.
+ *
+ * EXPORTED FOR ITS TEST, like `safeUrlPath` and `parseRange` in ./http.ts. Its
+ * warnings are the only evidence of which rule fired, and they do not reach a
+ * `JobHandle` — so reading them through a whole `runPipeline` is impossible and
+ * the alternative was to leave the guard untested.
+ */
+export declare function guardFigures(source: Source, root: string, allowRemote: boolean, warnings: string[]): Promise<Source>;

package/dist/types/server/upload.d.ts

@@ -2,9 +2,10 @@
  * What arrives on the socket, treated as hostile.
  *
  * Three jobs, in order: get the bytes off the wire without letting the sender
- * choose how much memory we spend, turn them into a file and a set of fields,
- * and — if the file is a zip — get its contents onto disk without letting an
- * entry name decide where "onto disk" is.
+ * choose how much memory we spend, turn them into a `Submission` — a file or a
+ * URL, never both and never neither, plus the option fields — and, if the file
+ * is a zip, get its contents onto disk without letting an entry name decide
+ * where "onto disk" is.
  *
  * Everything here is pure except `readBody`, which is why the zip half can be
  * tested against an actually malicious archive with no server running.
@@ -44,7 +45,30 @@ export interface Upload {
     fields: Record<string, string>;
 }
 /**
- * multipart/form-data, with no dependency.
+ * What one POST carries: a document, or the address of one.
+ *
+ * A union rather than two optional fields on one record, because "exactly one of
+ * these" IS the rule, and a shape that can hold both — or neither — is a shape
+ * every reader downstream has to re-check. `parseSubmission` is the last place
+ * that can still answer the client, so both refusals live there and nothing
+ * after it asks the question again.
+ *
+ * `fields` is on both arms because the option fields belong to the REQUEST, and a
+ * URL submission has them just as an upload does. On the file arm it is the very
+ * same object as `upload.fields`, not a copy — read either; `Upload` keeps its
+ * own reference because src/mcp/tools.ts builds one without ever seeing a form.
+ */
+export type Submission = {
+    kind: "file";
+    upload: Upload;
+    fields: Record<string, string>;
+} | {
+    kind: "url";
+    url: string;
+    fields: Record<string, string>;
+};
+/**
+ * multipart/form-data, with no dependency, and the exactly-one rule enforced.
  *
  * `new Response(body, { headers }).formData()` is undici's parser, which ships
  * in Node — measured against a hand-built body with a filename containing a
@@ -52,7 +76,7 @@ export interface Upload {
  * with the right bytes. It throws a bare TypeError on a malformed body, which
  * is not a sentence anyone can act on, so it is translated here.
  */
-export declare function parseMultipart(body: Buffer, contentType: string): Promise<Upload>;
+export declare function parseSubmission(body: Buffer, contentType: string): Promise<Submission>;
 /** A zip starts "PK". Asked before unzipping so a PDF reads as a PDF. */
 export declare function looksLikeZip(bytes: Uint8Array): boolean;
 /**

package/dist/types/source/assets.d.ts

@@ -1,11 +1,84 @@
 import { type Source } from "../types.js";
-/** Fetch every figure into `dir`, rewrite `src` to the local name, measure it. */
-export declare function fetchFigures(source: Source, dir: string): Promise<Source>;
 /**
- * Intrinsic size from the file header. Just enough PNG/JPEG/GIF to answer the
- * one question layout asks — four field reads do not justify a dependency.
+ * Fetch every figure into `dir`, rewrite `src` to the local name, measure it.
+ *
+ * A figure that cannot be fetched, cannot be measured, or cannot be represented
+ * is DROPPED and named in `warnings` — the same shape `guardFigures` in
+ * src/server/pipeline.ts already uses for the figures it refuses to fetch at
+ * all. The reason is what the caller is: a whole ingest. A paper with eleven
+ * figures and one dead CDN link is still the deck someone asked for, and before
+ * this the dead link ended the run with `unrecognised image header` and no
+ * indication of which figure had produced it.
+ *
+ * `warnings` is an out-parameter rather than a second return value so the two
+ * callers that do not collect them (`decksmith ingest`, and the pipeline's own
+ * call) keep compiling unchanged, and so a caller that does collect them can
+ * pass the SAME array it already threads through `guardFigures` and have both
+ * sets of drops read as one list. Omit it and the drops go to stderr instead —
+ * dropping a figure only stops being an improvement over aborting if somebody
+ * is told which figure went.
+ */
+export declare function fetchFigures(source: Source, dir: string, warnings?: string[]): Promise<Source>;
+/** Every format this reads. Also every format a page is likely to serve a figure in. */
+export type ImageFormat = "png" | "jpeg" | "gif" | "webp" | "avif" | "svg";
+/**
+ * The format the bytes claim to be, from the header alone.
+ *
+ * Exported and separate from `imageSize` because two callers ask two different
+ * questions of the same eight bytes: what to name the file, and how to measure
+ * it. Keeping them one function is how a file ends up named after the reader
+ * that happened to succeed.
+ */
+export declare function sniffFormat(b: Buffer): ImageFormat | undefined;
+/**
+ * Intrinsic size from the file header, for every format a page may hand us.
+ *
+ * PNG, JPEG and GIF were enough while a source was a markdown file with its own
+ * images beside it. A URL is not: a page today serves WebP for the photograph,
+ * AVIF for the hero and SVG for the diagram, and a reader that knows three
+ * formats measures the other three as "unrecognised" and drops them.
+ *
+ * Still no dependency for this. Each reader below is a handful of field reads
+ * against a published header layout, and the alternative is a decoder that
+ * pulls in the whole pixel pipeline to answer two integers.
+ *
+ * It THROWS rather than returning zeros, and the message names what it saw.
+ * `figureSchema` requires a positive int, so a zero would not be caught here at
+ * all — it would surface much later as `width: too small` against a figure id,
+ * with nothing to say which URL had produced it.
  */
 export declare function imageSize(b: Buffer): {
     width: number;
     height: number;
 };
+/**
+ * The size an SVG declares, in CSS pixels.
+ *
+ * Two callers: figure ingest above, and `sizeOf` in src/images/illustrate.ts
+ * through the re-export in src/images/providers.ts, where this used to live as a
+ * regex for `viewBox="0 0 %d %d"` over the first 200 bytes. That was honest for
+ * the SVG the tool draws itself and wrong for everything else, because a real
+ * SVG opens with a licence comment above the root element, spells the viewBox
+ * with floats, writes `width="640px"`, or carries no viewBox at all.
+ *
+ * `width`/`height` win when BOTH resolve to an absolute length, because that is
+ * the intrinsic size a browser would use. The viewBox is the fallback, and it is
+ * also the right answer for the very common `width="100%"`: a percentage is a
+ * fraction of a viewport this pipeline has not created yet, so it is deliberately
+ * left unresolved rather than read as 100 pixels.
+ *
+ * CHECKED against the browser that draws these: 60 real SVGs off this machine
+ * measured here and loaded in Chrome, and all 60 agree with `naturalWidth` and
+ * `naturalHeight` to the pixel. Two deliberate divergences remain. A fractional
+ * viewBox is rounded, where Chrome's own rounding differs by up to a pixel in
+ * either direction (300.5 → 300, 300.4 → 299, 99.9 → 100), which is a ratio
+ * unchanged in the third decimal. And an SVG declaring NEITHER a size nor a
+ * viewBox is refused rather than given the 300x150 a browser hands a replaced
+ * element with no intrinsic size: that default is a CSS fallback, not a fact
+ * about the picture, and everything downstream frames the figure against the box
+ * recorded here.
+ */
+export declare function svgSize(bytes: Buffer): {
+    width: number;
+    height: number;
+};

package/dist/types/source/harvest.d.ts

@@ -0,0 +1,250 @@
+import { type Source } from "../types.js";
+export interface HarvestOptions {
+    /** Cap on the page's own HTML. Generous: a real article ships megabytes of it. */
+    maxBytes?: number;
+    /** Cap on one asset, matching what `fetchFigures` allows a figure to be. */
+    maxAssetBytes?: number;
+    /** Whole-call budget for each fetch, and for the browser's own steps. */
+    timeoutMs?: number;
+    /** How many assets are downloaded before the rest are named in `warnings`. */
+    maxAssets?: number;
+    /**
+     * How many VIDEOS are downloaded, counted separately from `maxAssets`.
+     *
+     * Separate because the two are different sizes of mistake. A page with forty
+     * images costs a few megabytes; a page with forty videos costs a gigabyte and
+     * an hour, and one of them was probably an advertisement. A clip earns its
+     * place by being the thing a beat is planned around, and a deck does not have
+     * room for four of those, let alone forty.
+     */
+    maxClips?: number;
+    /**
+     * Seconds of a downloaded clip that are kept. Longer is TRUNCATED, and the
+     * trim is warned about rather than performed quietly.
+     *
+     * A cap on SECONDS rather than on bytes because seconds are what the render
+     * spends: hyperframes pre-decodes a clip to one still per output frame before
+     * capture begins, so a five-minute video inside a four-minute deck is four
+     * minutes of full-size stills written to disk for a beat that can be sixty
+     * seconds at most (`beatSchema` in src/types.ts caps it there). The default
+     * lives in ./transcode.ts beside the rest of the encode.
+     *
+     * Ignored when `transcode` is false: trimming is something ffmpeg does, and
+     * there is no ffmpeg in that path to do it.
+     */
+    maxClipSeconds?: number;
+    /**
+     * Whether a downloaded clip is re-encoded to a slide-sized VP9 webm at all.
+     * True unless stated, and stating `false` ships the page's own file.
+     *
+     * The reason to turn it off is that the encode is the one part of a harvest
+     * that costs CPU rather than network: a caller re-ingesting the same page ten
+     * times while tuning a plan pays for it ten times, and the deck it is looking
+     * at does not care. The reason to leave it on is everything ./transcode.ts
+     * says — the bytes shipped, and the stills the render writes.
+     */
+    transcode?: boolean;
+    /**
+     * Total bytes across every asset this harvest downloads.
+     *
+     * `maxAssetBytes` bounds ONE file; nothing bounded the sum, so forty assets
+     * one byte under the per-file cap was a legal harvest of 1.2 GB. Charged from
+     * what actually arrived, and only for a fetch that succeeded — the counter
+     * that charges before the check is how a refused figure still costs the
+     * budget it was refused for (`guardFigures` in src/server/pipeline.ts does
+     * exactly that, deliberately not copied here).
+     */
+    maxTotalBytes?: number;
+    /**
+     * Wall clock for the whole harvest, checked BEFORE each fetch is started.
+     *
+     * BE HONEST ABOUT WHAT THIS BOUNDS: it stops the NEXT fetch, never one already
+     * in flight, so the real ceiling is this plus one `timeoutMs`. Bounding it
+     * exactly would mean an abort signal threaded through `fetchGuarded`, and a
+     * harvest that overruns by twenty seconds is not the failure this is for — a
+     * page whose forty images each take fifteen seconds is.
+     */
+    maxWallMs?: number;
+    /**
+     * How the markdown SPELLS its asset references. Absolute paths by default,
+     * which is what a caller reading the document in place needs.
+     *
+     * `"relative"` writes the bare filename instead, for a caller that is about to
+     * move the directory somewhere this process cannot see — the MCP zips the
+     * harvest and hands it to the server, where an absolute path out of this
+     * machine's temp directory is refused by `guardFigures` and the figure is
+     * dropped. `assets` stays absolute either way: it names files on THIS disk.
+     */
+    refs?: "absolute" | "relative";
+    /**
+     * TEST SEAM, passed straight through to `fetchGuarded`, where it is documented.
+     *
+     * It is the only way to point this at a `node:http` server on loopback, which
+     * is what test/harvest.test.ts needs to drive the real code path — including
+     * the interception proof, which requires a second server this process can see
+     * the request count of. It relaxes nothing else: the private ranges, the
+     * schemes, the caps and the timeout all still apply. Nothing in src passes it.
+     */
+    allowLoopback?: boolean;
+}
+export interface Harvested {
+    /** The document, in the dialect src/source/markdown.ts reads. */
+    markdown: string;
+    /**
+     * Absolute paths of every file the MARKDOWN references, in document order. A
+     * clip's video is written into `dir` too and is deliberately not one of them:
+     * the markdown cannot reference it, and a caller shipping the document
+     * elsewhere (the MCP zips this list) would otherwise carry megabytes nothing
+     * in the document points at. It is named in `clips` instead.
+     */
+    assets: string[];
+    /**
+     * The videos, which the markdown CANNOT carry — see `HarvestedClip`. Hand
+     * these to `attachClips` with the parsed source to get them back.
+     */
+    clips: HarvestedClip[];
+    /** Everything left out, and why. One dead image is not a failed harvest. */
+    warnings: string[];
+    /** The page's title, also emitted as the document's opening `#` heading. */
+    title: string;
+}
+/**
+ * One video, carried BESIDE the markdown because the dialect has no word for it.
+ *
+ * `parseMarkdown` produces figures out of images and nothing else, so a clip —
+ * `kind: "clip"`, a poster, a duration, and either a file or a page to watch it
+ * on — cannot be spelled in the document at all. Rather than invent a dialect
+ * extension that only this module writes and only `parseMarkdown` would have to
+ * learn, the clip travels alongside and `attachClips` puts it back afterwards.
+ *
+ * `poster` is also the JOIN: when there is one, the markdown references it as an
+ * ordinary image, so `parseMarkdown` gives that figure the id, the section and
+ * the sentence that mentions it — everything the planner uses to decide where a
+ * picture belongs — and `attachClips` upgrades that same figure in place. A clip
+ * with no poster has nothing to join to and is appended as a new figure, which
+ * costs it exactly those three facts.
+ */
+export interface HarvestedClip {
+    /** Absolute path of the downloaded video, or "" for one we hold no file for. */
+    file: string;
+    /** Absolute path of the still, or "" when the page offered none. */
+    poster: string;
+    /** Where a viewer watches it, when there is no file. "" when there is one. */
+    href: string;
+    /**
+     * The VIDEO's own pixels when we hold the file, and the poster's when we do
+     * not. types.ts says this box is the video's rather than the still's, and it
+     * is right — every annotation downstream is a fraction of it. A clip we could
+     * not download has no other box to offer, and the deck shows the still.
+     */
+    width: number;
+    height: number;
+    /** Measured off the container, never guessed. Absent for a link-only clip. */
+    seconds?: number;
+    /** The figcaption, link text or iframe title the page gave it. */
+    caption: string;
+}
+/**
+ * One block of the page, as the DOM walker sees it and as `toMarkdown` writes it.
+ *
+ * `src`, `poster` and `href` hold the PAGE's URLs when `readDom` returns them and
+ * LOCAL absolute paths once `localise` has rewritten them. One type rather than
+ * two because the two differ in nothing but that, and a second near-identical
+ * union is the kind of thing that grows a third.
+ */
+export type Block = {
+    kind: "heading";
+    depth: number;
+    text: string;
+} | {
+    kind: "paragraph";
+    text: string;
+} | {
+    kind: "code";
+    text: string;
+} | {
+    kind: "list";
+    ordered: boolean;
+    items: string[];
+} | {
+    kind: "table";
+    columns: string[];
+    rows: string[][];
+} | {
+    kind: "image";
+    src: string;
+    alt: string;
+    caption: string;
+} | {
+    kind: "video";
+    src: string;
+    poster: string;
+    href: string;
+    caption: string;
+};
+export declare function harvest(url: string, dir: string, opts?: HarvestOptions): Promise<Harvested>;
+/** What a container declares about the picture inside it. */
+export interface Measured {
+    width: number;
+    height: number;
+    /** Absent when the container declares no usable duration — a live capture does. */
+    seconds?: number;
+}
+/**
+ * A video's display box and its length, read out of its own header.
+ *
+ * WHY NOT `ffprobe`, WHICH WOULD BE FOUR LINES. Because it would make ingest —
+ * the one verb that has to work on a laptop with a browser and nothing else —
+ * depend on a binary this project otherwise needs only to RENDER. A machine
+ * without ffmpeg would then harvest a page and silently come back with the video
+ * demoted to a link, which is the shape of failure this file exists to avoid. A
+ * width, a height and a duration are four integers in a header; reading them is
+ * cheaper than the dependency, and it is the same trade `imageSize` already
+ * makes for PNG, JPEG, WebP and AVIF.
+ *
+ * Exported because it is pure, and because the half of test/harvest.test.ts that
+ * runs on CI has no browser — measuring a hand-built header is testable there
+ * and driving a real page is not.
+ */
+export declare function videoSize(b: Buffer): Measured & {
+    container: "mp4" | "webm";
+};
+/**
+ * Put the harvest's clips back into the parsed source, and their files beside it.
+ *
+ * CALL THIS BEFORE `fetchFigures`, not after. `fetchFigures` passes a clip
+ * through untouched — it says so in as many words, because a clip carries the
+ * video's dimensions rather than an image's and its first bytes are an `ftyp`
+ * box the image sniffer is right to refuse — so a clip that arrives after it has
+ * run is a figure nothing ever localises, whose `src` is an absolute path into a
+ * temp directory that will not exist on the machine that opens the deck.
+ *
+ * WHERE A CLIP LANDS. One with a poster REPLACES the figure `parseMarkdown` made
+ * out of that poster, keeping its id, its section and the sentence that mentions
+ * it — the three facts the planner uses to decide which point a picture belongs
+ * to, and the reason the poster is written into the markdown at all. One without
+ * a poster has nothing to replace and is appended, which costs it exactly those
+ * three facts and is why a page that gives its videos posters harvests better.
+ */
+export declare function attachClips(source: Source, clips: readonly HarvestedClip[], dir: string): Promise<Source>;
+/**
+ * Blocks become THIS PROJECT'S markdown dialect, which is narrower than markdown.
+ *
+ * Three rules from src/source/markdown.ts, each of which loses content silently
+ * when broken — no error, no gate, just a text-only deck:
+ *
+ *  - A figure is lifted only from a paragraph whose children are ALL images
+ *    (`onlyImages`, around :82 and :158). So an image is always alone in its
+ *    paragraph; `readDom` has already broken sentences around inline ones.
+ *  - A caption is read only from a FOLLOWING paragraph that is a single run of
+ *    emphasis (`captionOf`, :166). So a caption is `*text*` on its own, directly
+ *    after the image, with every `*` inside it escaped.
+ *  - Raw HTML returns the empty string in BOTH walkers (:243 and :264). So
+ *    nothing here emits raw HTML, ever — not a `<figure>`, not a `<br>`, not an
+ *    HTML comment.
+ *
+ * Exported because test/harvest.test.ts runs `parseMarkdown` back over its output
+ * and asserts the figures survive, and that test must run on a machine with no
+ * browser — which is every CI runner this project has.
+ */
+export declare function toMarkdown(blocks: readonly Block[]): string;

package/dist/types/source/readability.d.ts

@@ -0,0 +1,120 @@
+/**
+ * WHICH PART OF A PAGE IS THE ARTICLE — the Readability scoring algorithm,
+ * implemented here rather than depended on.
+ *
+ * `src/source/harvest.ts` picks its content region with three rules: believe
+ * `<main>`, believe `<article>`, else take the deepest element whose block text
+ * minus its link text is maximal. Its own comment says that is deliberately not
+ * a Readability implementation, and it holds up on the shapes it was written
+ * against. It loses on the shapes it was not: a `<main>` that also wraps the
+ * comment thread is believed whole and short-circuits before the loop ever runs;
+ * a `<div role="dialog">` cookie banner matches nothing in the walker's SKIP set,
+ * so it is neither scored down nor skipped; and the score counts text inside
+ * `nav`/`aside`/`footer` subtrees that the walker will then throw away, so a
+ * wrapper can be chosen on the strength of text that never reaches the markdown.
+ *
+ * This is Mozilla Readability's `grabArticle`, in the shape that fits here:
+ * strip the elements whose tag, role, class or id say chrome; score every
+ * paragraph by its length and its comma count; propagate that score to the
+ * parent, the grandparent and up to five levels of ancestor, dividing as it
+ * climbs; discount each candidate by its LINK DENSITY, which is the term that
+ * tells a rail of headlines from prose; take the highest, climb to a parent that
+ * scores higher still, then merge in the siblings that score close to it.
+ *
+ * WHAT THIS IS NOT. It is not a semantic understanding of the page. Nothing here
+ * reads the article; it is arithmetic over text length, punctuation, and the
+ * words site authors happen to put in class names. It is much better than one
+ * subtraction and it is wrong in ways that are structural rather than accidental,
+ * so they are worth naming:
+ *
+ *  - A PAGINATED ARTICLE harvests as page one and nothing says so. Readability
+ *    proper follows "next page" links; this cannot, because `harvest` fetches
+ *    exactly one document and every subresource is aborted.
+ *  - A PAGE WHOSE CONTENT IS A LIST OF LINKS — a link blog, a search result, a
+ *    documentation index — is scored down by the very term that makes the pass
+ *    work. Link density cannot tell a nav from a page that is a nav on purpose.
+ *  - A GALLERY loses. Pictures carry no text, `<li>` is not a scored tag, and a
+ *    page of captioned images scores near zero everywhere, so the winner is
+ *    whichever caption block happened to be longest.
+ *  - CLASS NAMES ARE A GUESS, and the same word list that rescues
+ *    `<div class="article-body">` rescues `<div class="comment-body">`.
+ *  - AN ELEMENT THE STRIP REMOVES TAKES ITS `<video>` WITH IT. That matters more
+ *    here than in a reader: harvest's poster is the join that lets `attachClips`
+ *    keep a clip's id, section and mention, so a silently dropped player demotes
+ *    a clip with every gate green. Hence `mediaDropped` in the report — this pass
+ *    counts what it lost rather than leaving the caller to find out later.
+ *
+ * When it declines it says so, PUTS BACK EVERY NODE IT REMOVED, and changes
+ * nothing else, so `harvest`'s own heuristic runs against the document it would
+ * have seen. Declining is the retry Readability performs with its flags off;
+ * here the simpler pass IS that retry, and it already exists.
+ *
+ * IT RUNS INSIDE THE PAGE. `harvest` ships code into the browser as a function
+ * reference — `page.evaluate(readDom)` — which puppeteer serialises with
+ * `Function.prototype.toString()` and evaluates as source text. `readContentRegion`
+ * is shipped the same way and carries the same rule: it may not close over
+ * anything in this module, so every constant and every helper it uses is declared
+ * inside it, INCLUDING the marker attribute that `CONTENT_MARKER` below spells a
+ * second time. A closed-over constant does not fail here, where a test would see
+ * it; it fails in the page, as a `ReferenceError`, on somebody's ingest — so
+ * test/readability.test.ts asserts the two spellings agree and that the source
+ * names nothing from Node. The node bundle is built with `minify: false`
+ * (scripts/build.mjs), which is what keeps the serialised text intact.
+ */
+/**
+ * The attribute the pass puts on the region it chose.
+ *
+ * A marker rather than a return value because an `Element` cannot cross the
+ * `page.evaluate` boundary — what comes back is structured-clone data. Marking
+ * is also what lets this stay a second self-contained function beside `readDom`
+ * rather than something `readDom` has to grow a second job for: the walker's
+ * `pickRoot` need only look for this attribute first and keep its own three
+ * rules as the fallback for when this pass declines.
+ */
+export declare const CONTENT_MARKER = "data-ds-content";
+/** One element the scorer considered, in the terms it was judged on. */
+export interface Candidate {
+    /** Up to three levels, `div#page > div#content > article.post`, to name it. */
+    path: string;
+    /** Paragraph scores propagated up, plus this element's tag and class weight. */
+    content: number;
+    /** Anchor text over all text, 0..1 — a rail of headlines is near 1. */
+    linkDensity: number;
+    /** `content * (1 - linkDensity)`. This is what the winner is chosen on. */
+    score: number;
+    /** Characters of text held, whitespace collapsed. */
+    text: number;
+}
+/** What the pass hands back across the `page.evaluate` boundary. */
+export interface ContentPick {
+    /** True when some element in the document now carries `CONTENT_MARKER`. */
+    marked: boolean;
+    /**
+     * Why, in a sentence a `warnings` entry can carry verbatim. Populated on
+     * every path, including the ones that change nothing.
+     */
+    reason: string;
+    /** The best few candidates, best first, so a failure names which part broke. */
+    candidates: Candidate[];
+    /** Siblings merged in beside the winner, the winner itself not counted. */
+    merged: number;
+    /** Elements the strip removed. Zero when the pass declined and put them back. */
+    stripped: number;
+    /** Characters of text in the marked region. */
+    text: number;
+    /**
+     * `<video>` and `<iframe>` elements the page had that the region does not.
+     * Not an error — a related-videos rail SHOULD be lost — but the clip path is
+     * load-bearing enough downstream that the number is reported rather than
+     * discovered.
+     */
+    mediaDropped: number;
+}
+/**
+ * Choose the content region, mark it, and report what that cost.
+ *
+ * Evaluated INSIDE THE PAGE, so nothing outside this function body exists at
+ * run time. Type annotations are erased by the build and are the only thing
+ * here that refers to anything above.
+ */
+export declare function readContentRegion(): ContentPick;