jsafa-pdf 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Safwan Murad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,476 @@
+# jsafa-pdf
+
+Client-side HTML/CSS → PDF with **real, selectable, copyable text**. No server, no rasterization.
+
+Drop in one script tag and call one function. Latin and Arabic both come out as real text you can
+select, copy and search — not a picture of text.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/jsafa-pdf/dist/jsafa-pdf.umd.js"></script>
+<script>
+  JsafaPDF.download('#invoice', 'invoice.pdf');
+</script>
+```
+
+That's the whole integration. No build step, no bundler, no framework.
+
+That tag always fetches the newest release, which is what you want while trying it out. For a page
+you actually ship, [pin a version](#install).
+
+> **0.1.1** — the feature set below is implemented and tested on Chromium, Firefox and WebKit. The
+> API may still shift before 1.0; [Limitations](#limitations) lists what isn't covered.
+
+---
+
+## Contents
+
+- [Why](#why)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [API reference](#api-reference)
+- [Options](#options)
+- [Fonts](#fonts)
+- [Multiple pages](#multiple-pages)
+- [Limitations](#limitations)
+- [Development](#development)
+
+---
+
+## Why
+
+jsafa-pdf is built around one idea:
+
+> **The browser has already laid out the document. Read it back — don't recompute it.**
+
+`Range.getClientRects()` reports one rect per *rendered line box*, so the engine tells us exactly
+where every line sits and where it broke. We never decide where a line breaks; we observe where it
+broke, then transpile that into PDF operators.
+
+Three things follow from that:
+
+- **Text stays text.** Glyphs are drawn as glyphs with an embedded font, so the output is selectable,
+  searchable and small — not a picture of a page.
+- **Your CSS is the layout engine.** Flexbox, grid, floats, bidi, `@font-face` — whatever the browser
+  renders is what gets measured, so there's no CSS subset to learn and no document to rewrite.
+- **It runs in the page.** No print dialog, no server, no headless browser to operate.
+
+The tradeoff is stated plainly in [Limitations](#limitations): this is a transpiler from computed
+layout to PDF operators, not a second rendering engine, so effects that never produce measurable
+geometry are the parts that don't come across.
+
+---
+
+## Install
+
+### CDN — nothing to download
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/jsafa-pdf@0.1/dist/jsafa-pdf.umd.js"></script>
+```
+
+unpkg works the same way: `https://unpkg.com/jsafa-pdf@0.1/dist/jsafa-pdf.umd.js`
+
+Either defines the `JsafaPDF` global.
+
+**Choosing a version.** The CDNs accept a full version, a range, or nothing at all:
+
+| URL | Gets |
+|---|---|
+| `jsafa-pdf@0.1` | the newest `0.1.x` — bug fixes, never a breaking change. **Recommended.** |
+| `jsafa-pdf@0.1.1` | exactly that build, forever. Use when you need byte-identical output. |
+| `jsafa-pdf` | the newest release of anything, breaking changes included. This is the tag at the top of this page. |
+
+The unversioned form is the right shortcut for a first try, but it updates a live page without you
+touching it. Before 1.0 the API can still shift between minor versions, so `@0.1` gives you fixes
+automatically while keeping a breaking release from reaching users you did not ship it to.
+
+### npm
+
+```bash
+npm install jsafa-pdf
+```
+
+```js
+import { download, registerFont, mm } from 'jsafa-pdf';
+```
+
+### Self-hosted
+
+Serve `jsafa-pdf.umd.js` from your own origin — the file from the CDN, the npm package, or a
+[GitHub release](https://github.com/Safwan-Murad/jsafa-pdf/releases):
+
+```html
+<script src="/js/jsafa-pdf.umd.js"></script>
+```
+
+### From source
+
+```bash
+git clone https://github.com/Safwan-Murad/jsafa-pdf.git
+cd jsafa-pdf && npm install && npm run build
+```
+
+Every route gives you both builds:
+
+| File | Use |
+|---|---|
+| `jsafa-pdf.umd.js` | `<script>` tag. Defines the `JsafaPDF` global. |
+| `jsafa-pdf.js` | ESM, for bundlers. |
+
+Type declarations (`.d.ts`) are emitted alongside them.
+
+> The UMD build is ~519 KB gzipped. It carries a full PDF writer and font engine — subsetting,
+> Identity-H encoding and OpenType shaping — which is what lets text stay real text.
+
+> Serve your page over **http(s)**, not `file://`. On `file://` the browser blocks `fetch` and ES
+> modules, so fonts and images cannot be embedded.
+
+---
+
+## Quick start
+
+Everything below is optional configuration. The minimum is one call:
+
+```html
+<style>
+  /* Declared once in CSS — jsafa-pdf finds and embeds it automatically. */
+  @font-face {
+    font-family: 'Noto Sans Arabic';
+    src: url('/fonts/NotoSansArabic-Regular.ttf') format('truetype');
+  }
+  #invoice { width: 420px; padding: 20px; border: 2px solid #cbd5e1; }
+  #invoice .rtl { direction: rtl; font-family: 'Noto Sans Arabic', serif; }
+</style>
+
+<div id="invoice">
+  <h2>Invoice #A-1042</h2>
+  <p>The quick brown fox jumps over the lazy dog.</p>
+  <p class="rtl">مرحبا بالعالم</p>
+</div>
+
+<button onclick="JsafaPDF.download('#invoice', 'invoice.pdf')">Download PDF</button>
+
+<script src="https://cdn.jsdelivr.net/npm/jsafa-pdf@0.1/dist/jsafa-pdf.umd.js"></script>
+```
+
+jsafa-pdf automatically waits for webfonts and images to load, discovers `@font-face` rules and
+embeds them. See [examples/simple.html](./examples/simple.html).
+
+---
+
+## API reference
+
+All functions are properties of the `JsafaPDF` global (or named ESM exports).
+
+`target` is always an **`Element` or a CSS selector string**.
+
+### Producing a PDF
+
+| Function | Returns | Description |
+|---|---|---|
+| `toPdf(target, options?)` | `Promise<Uint8Array>` | Raw PDF bytes. |
+| `toBlob(target, options?)` | `Promise<Blob>` | PDF as an `application/pdf` Blob. |
+| `download(target, filename?, options?)` | `Promise<void>` | Generates and saves the file. `filename` defaults to `"document.pdf"`. |
+| `open(target, options?)` | `Promise<Window \| null>` | Opens the PDF in a new browser tab. |
+
+```js
+// Bytes, for uploading or storing yourself
+const bytes = await JsafaPDF.toPdf('#invoice');
+await fetch('/api/save', { method: 'POST', body: bytes });
+
+// Blob, e.g. to preview in an <iframe>
+const blob = await JsafaPDF.toBlob(document.getElementById('invoice'));
+iframe.src = URL.createObjectURL(blob);
+
+// Save to the user's downloads
+await JsafaPDF.download('#invoice', 'invoice-1042.pdf');
+
+// Open in a new tab
+await JsafaPDF.open('#invoice');
+```
+
+### Fonts
+
+| Function | Returns | Description |
+|---|---|---|
+| `registerFont({ family, src, weight?, style? })` | `Promise<void>` | Make a font embeddable. `src` is a URL, `ArrayBuffer` or `Uint8Array`. |
+| `registerFontsFromCss(document?)` | `Promise<DiscoveredFont[]>` | Register every `@font-face` on the page. Runs automatically. |
+| `registeredFamilies()` | `string[]` | Families currently available for embedding. |
+| `clearFonts()` | `void` | Forget all registered fonts. |
+| `clearDiscoveredFonts()` | `void` | Forget which `@font-face` rules were processed, so they are re-read. |
+
+```js
+// Only needed when a font is NOT declared via @font-face
+await JsafaPDF.registerFont({
+  family: 'Cairo',
+  src: '/fonts/Cairo-Bold.ttf',
+  weight: 700,
+  style: 'normal',
+});
+
+// Or from a file the user picked
+await JsafaPDF.registerFont({ family: 'Cairo', src: await file.arrayBuffer() });
+```
+
+### Units and page sizes
+
+| Function | Returns | Description |
+|---|---|---|
+| `mm(n)` | `number` | Millimetres → PDF points. |
+| `cm(n)` | `number` | Centimetres → points. |
+| `inch(n)` | `number` | Inches → points. |
+| `PAGE_SIZES` | `object` | `{ A3, A4, A5, Letter, Legal }`, each `[width, height]` in points. |
+
+PDF points are 1/72 inch. `A4` is `[595.28, 841.89]`.
+
+### Advanced
+
+Not needed for ordinary use — these expose the pipeline for custom output or debugging.
+
+| Function | Returns | Description |
+|---|---|---|
+| `waitForAssets(element)` | `Promise<void>` | Wait for webfonts and images. Runs automatically. |
+| `captureElement(element)` | `CapturedDocument` | Read layout into a paint list without producing a PDF. |
+| `extractTextRuns(textNode)` | `TextRun[]` | Line- and direction-split runs for one text node. |
+| `planPages(captured, pageOptions)` | `PlannedPage[]` | Slice a captured document into pages. |
+| `emitPdf(captured, options?)` | `Promise<Uint8Array>` | Render an already-captured document. |
+| `clearBaselineCache()` | `void` | Drop memoised font metrics after swapping webfonts. |
+| `pxToPt(px)` / `ptToPx(pt)` | `number` | CSS px ↔ PDF points (× 0.75). |
+
+```js
+// Inspect what was captured, without generating anything
+const captured = JsafaPDF.captureElement('#invoice');
+console.log(captured.runs.map(r => `${r.direction} "${r.text}"`));
+```
+
+---
+
+## Options
+
+Every producing function accepts the same options object.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `page` | `PageOptions` | *(none)* | Paginate onto fixed pages. Omit for a single page sized to the element. |
+| `autoFonts` | `boolean` | `true` | Discover and register `@font-face` fonts automatically. |
+| `waitForAssets` | `boolean` | `true` | Wait for fonts and images before reading layout. |
+| `subset` | `boolean` | `true` | Embed only the glyphs used. Smaller files; unsupported by a few font files. |
+| `title` | `string` | *(none)* | PDF document title metadata. |
+
+### `PageOptions`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `size` | `'A3' \| 'A4' \| 'A5' \| 'Letter' \| 'Legal' \| [w, h]` | `'A4'` | Named size, or explicit `[width, height]` in points. |
+| `orientation` | `'portrait' \| 'landscape'` | `'portrait'` | |
+| `margin` | `number \| { top, right, bottom, left }` | `mm(12)` | In points. Use `mm()` / `cm()` / `inch()`. |
+| `fit` | `'width' \| 'none'` | `'width'` | `width` scales the element to the content width. `none` keeps 1px = 0.75pt. |
+| `avoidBreakInside` | `boolean` | `true` | Move a page boundary above a `break-inside: avoid` element rather than cutting it. |
+| `repeatTableHeaders` | `boolean` | `true` | Repeat `<thead>` at the top of continuation pages. |
+| `footer` | `FooterOptions` | *(none)* | Text drawn in the bottom margin. See below. |
+
+### Page numbers and footers
+
+```js
+page: {
+  size: 'A4',
+  footer: {
+    text: ({ page, pages }) => `Page ${page} of ${pages}`,
+    align: 'center',       // 'left' | 'center' | 'right'
+    fontSize: 9,           // points
+    color: '#607d8b',      // any CSS colour
+    fontFamily: 'Inter',   // only needed for a non-Latin footer
+  }
+}
+```
+
+### Table pagination
+
+Two hints your print stylesheet probably already sets are read automatically:
+
+| CSS | effect |
+|---|---|
+| `tr { break-inside: avoid }` (or `page-break-inside`) | the boundary moves **above** the row instead of cutting through it |
+| `thead { display: table-header-group }` | the header **repeats** on every continuation page, with space reserved for it |
+
+A region taller than a whole page is still cut — honouring it would leave no legal break anywhere.
+
+```js
+await JsafaPDF.download('#report', 'report.pdf', {
+  page: {
+    size: 'A4',
+    orientation: 'landscape',
+    margin: { top: JsafaPDF.mm(20), right: JsafaPDF.mm(15),
+              bottom: JsafaPDF.mm(20), left: JsafaPDF.mm(15) },
+  },
+  title: 'Quarterly Report',
+});
+```
+
+---
+
+## Fonts
+
+**This is the one constraint worth understanding up front.**
+
+JavaScript cannot read arbitrary system font files. A font can only be embedded if its bytes are
+reachable, which means one of:
+
+1. **`@font-face` in your CSS** — found and embedded automatically. *Recommended.*
+2. **`registerFont()`** — for fonts loaded some other way.
+
+Fonts you don't provide fall back to the closest PDF standard font (serif → Times, sans-serif →
+Helvetica, monospace → Courier). A document set in Georgia will render as Times.
+
+> **Non-Latin scripts must be provided.** The 14 standard PDF fonts contain **no Arabic, CJK, Cyrillic
+> or Greek glyphs at all.** If your document has Arabic and you haven't supplied a font that covers
+> it, jsafa-pdf throws an error naming the family rather than silently producing a broken PDF.
+
+So if your document uses Arial or Segoe UI, self-host them:
+
+```css
+@font-face { font-family: 'Inter'; src: url('/fonts/Inter.ttf') format('truetype'); }
+body { font-family: 'Inter', sans-serif; }
+```
+
+Prefer **TTF or OTF**. WOFF works; WOFF2 is brotli-compressed and may fail to parse — if your CSS
+offers several formats, jsafa-pdf picks the most compatible one automatically.
+
+Font fallback follows the browser's **per-glyph** behaviour: `font-family: 'Noto Sans Arabic', serif`
+paints Arabic with Noto and Latin with serif, exactly as on screen.
+
+---
+
+## Links and transforms
+
+**`<a href>` becomes a clickable link annotation.** Nothing to configure. Relative URLs are resolved
+to absolute, so they still work from a PDF opened anywhere. A link that wraps across lines gets one
+annotation per line. `javascript:` and bare `#fragment` targets are skipped — they would do nothing
+in a reader.
+
+**CSS `transform` is supported**, including `rotate`, `scale`, `translate` and nested combinations.
+Transformed text stays a single selectable run rather than fragmenting into one run per character.
+This works because transforms are paint-time only: capture suspends them, reads clean geometry, and
+re-applies each as a PDF matrix.
+
+---
+
+## Multiple pages
+
+Pass `page` to paginate. Omit it and you get a single page sized exactly to the element — ideal for
+a ticket, badge or label.
+
+```js
+await JsafaPDF.download('#statement', 'statement.pdf', {
+  page: { size: 'A4', margin: JsafaPDF.mm(12) }
+});
+```
+
+Pages are produced by **slicing** the captured layout, not re-flowing it, so line breaks stay exactly
+where the browser put them. Text is assigned whole-line to a single page (a line may overhang into
+the margin rather than be cut in half), and backgrounds, borders and images continue across breaks,
+clipped to each page.
+
+See [examples/paginate.html](./examples/paginate.html).
+
+---
+
+## Limitations
+
+Honest list. jsafa-pdf is not a browser.
+
+**Not implemented yet**
+
+- `box-shadow`, `text-shadow`
+- `background-image` and CSS gradients
+- Running headers (footers and page numbers *are* supported)
+- `break-before` / `break-after`, widow and orphan control — these need layout re-flowed, which
+  slicing deliberately does not do. `break-inside: avoid` and repeating `<thead>` **are** honoured
+
+**Inherent**
+
+- Fonts must be reachable as bytes (see [Fonts](#fonts))
+- Cross-origin images need CORS, or their pixels cannot be read
+- Exotic CSS (filters, blend modes) may not reproduce exactly
+- Serve over http(s); `file://` blocks the fetches this relies on
+
+---
+
+## Development
+
+Requires **Node 20+**.
+
+```bash
+npm install
+npm run build
+```
+
+```bash
+npm run example
+```
+
+Then open **http://localhost:5174/examples/simple.html**.
+
+| Example | |
+|---|---|
+| [simple.html](./examples/simple.html) | Minimal zero-config usage |
+| [verify.html](./examples/verify.html) | Correctness suite — re-opens generated PDFs with pdf.js and checks the text layer, path geometry and pixel colours |
+| [paginate.html](./examples/paginate.html) | Multi-page output, checked for content loss and duplication |
+
+### Tests
+
+The suite runs in **real browsers** — jsdom has no layout engine, so it would pass while proving
+nothing — and on **all three engines**, because capture reads layout back out of the engine and a
+single-engine run proves very little.
+
+**30 tests × Chromium, Firefox, WebKit = 90**, covering line-box and bidi capture, backgrounds,
+borders, `border-radius`, images, `object-fit`, links, transforms, slicing, `break-inside`, repeated
+headers and footers. Generated PDFs are re-opened with pdf.js and asserted against the DOM they came
+from. Fixtures use standard PDF fonts and images encoded at runtime, so nothing needs a font file or
+the network.
+
+First fetch the browser binaries (once):
+
+```bash
+npx playwright install chromium firefox webkit
+```
+
+```bash
+npm test
+```
+
+CI runs the same thing on every push — see [.github/workflows/ci.yml](./.github/workflows/ci.yml).
+
+`npm run dev` serves the internal capture harness at http://localhost:5173. It must not be used to
+serve the examples: Vite transforms what it serves and would rewrite `dist/` into a broken stub.
+
+### Releasing
+
+Bump `version` in `package.json`, then tag it:
+
+```bash
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+That runs [.github/workflows/release.yml](./.github/workflows/release.yml): it refuses to continue if
+the tag disagrees with `package.json`, runs typecheck, build and the full three-engine suite, then
+creates the GitHub release with `jsafa-pdf.umd.js` and `jsafa-pdf.js` attached.
+
+Publishing to npm stays manual, since it is the one step that cannot be undone:
+
+```bash
+npm publish --access public
+```
+
+`prepublishOnly` re-runs typecheck and build first, so a stale `dist/` cannot ship.
+
+`dist/` is intentionally not committed — minified bundles diff badly and would grow the repository by
+roughly its own size on every build. The CDN and release assets serve that need instead.
+
+See [DESIGN.md](./DESIGN.md) for architecture and rationale.
+
+---
+
+## License
+
+MIT

package/dist/capture/baseline.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where is the text baseline inside a line box?
+ *
+ * We need this to place text in the PDF, and it must be identical across Chrome,
+ * Firefox and Safari. Canvas `TextMetrics.fontBoundingBoxAscent` is unusable for
+ * that: Firefox doesn't implement it, and Chrome and Safari disagree.
+ *
+ * So we ask the engine instead. A zero-size inline-block with
+ * `vertical-align: baseline` sits exactly on the baseline without perturbing
+ * layout, so its top edge *is* the baseline. Comparing that against the Range
+ * rect for adjacent text gives the ascent as a fraction of the run's height —
+ * a constant for a given font + size, so it's measured once and cached.
+ */
+export declare function baselineRatio(style: CSSStyleDeclaration): number;
+/** Clear memoised metrics. Call after swapping webfonts. */
+export declare function clearBaselineCache(): void;

package/dist/capture/box.d.ts

@@ -0,0 +1,62 @@
+import { type Rgba } from './style';
+import type { Rect } from '../types';
+export interface BorderEdge {
+    /** Width in CSS px. Zero means no edge. */
+    width: number;
+    color: Rgba;
+}
+/** Corner radii in CSS px, clockwise from top-left. */
+export type Radii = [number, number, number, number];
+/** An element's painted box: background fill and border strokes. */
+export interface BoxPaint {
+    /** Border box, in CSS px relative to the captured root. */
+    rect: Rect;
+    background: Rgba | null;
+    radii: Radii;
+    top: BorderEdge;
+    right: BorderEdge;
+    bottom: BorderEdge;
+    left: BorderEdge;
+    /** True when all four edges share a width and colour — strokeable as one path. */
+    uniformBorder: boolean;
+}
+/** Corner radii for an element, already clamped to its box. */
+export declare function readRadii(element: Element, style?: CSSStyleDeclaration): Radii;
+/**
+ * Read an element's paintable box, or null when there is nothing to draw.
+ *
+ * Most elements in a document have neither a background nor a border, so
+ * returning null keeps the paint list to what actually produces marks.
+ */
+export declare function readBox(element: Element, origin: DOMRect): BoxPaint | null;
+/** One path segment, in CSS px, y-down. */
+export type PathSegment = {
+    type: 'M' | 'L';
+    x: number;
+    y: number;
+} | {
+    type: 'C';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x: number;
+    y: number;
+};
+/**
+ * Geometry for a rounded rectangle, in CSS px, y-down.
+ *
+ * Kept as segments rather than a string because the same shape is needed both
+ * as an SVG path (for fills and strokes) and as PDF path operators in point
+ * space (for clipping), and duplicating the bezier maths across the two is how
+ * they drift apart.
+ *
+ * `inset` pulls the path inwards, which is how border strokes stay inside the
+ * border box: CSS draws borders within the box, but PDF centres a stroke on its
+ * path, so the path must sit half a border-width in.
+ */
+export declare function roundedRectSegments(rect: Rect, radii: Radii, inset?: number): PathSegment[];
+/** Serialise segments as an SVG path string, in CSS px, y-down. */
+export declare function segmentsToSvgPath(segments: PathSegment[]): string;
+/** Convenience: rounded rectangle as an SVG path in CSS px, y-down. */
+export declare function roundedRectPath(rect: Rect, radii: Radii, inset?: number): string;

package/dist/capture/document.d.ts

@@ -0,0 +1,62 @@
+import { type RunStyle } from './style';
+import { type BoxPaint } from './box';
+import { type ImagePaint } from './image';
+import { type LinkPaint } from './link';
+import { type Region, type RepeatHeader } from './fragments';
+import { type Affine } from './transform';
+import type { TextRun } from '../types';
+/** A text run with everything the emitter needs, in container-relative px. */
+export interface CapturedRun extends TextRun {
+    style: RunStyle;
+    /** Baseline offset from the top of the run's box, in CSS px. */
+    baselineOffset: number;
+}
+/** One mark to make, in paint order. */
+export type PaintOp = {
+    transform: Affine | null;
+    /** The element this mark came from, so the paginator can group by subtree. */
+    element: Element;
+} & ({
+    kind: 'box';
+    box: BoxPaint;
+} | {
+    kind: 'image';
+    image: ImagePaint;
+} | {
+    kind: 'link';
+    link: LinkPaint;
+} | {
+    kind: 'text';
+    run: CapturedRun;
+});
+export interface CapturedDocument {
+    /** Page box, in CSS px, matching the captured element. */
+    widthPx: number;
+    heightPx: number;
+    /** Everything to paint, in document order. */
+    ops: PaintOp[];
+    /** Convenience view of the text ops. */
+    runs: CapturedRun[];
+    /** Spans a page boundary must not cut through. */
+    unbreakable: Region[];
+    /** Table headers to repeat at the top of continuation pages. */
+    repeatHeaders: RepeatHeader[];
+}
+/**
+ * Accept either an element or a CSS selector.
+ *
+ * Every public entry point takes a target the same way; having one of them
+ * quietly refuse selectors is the kind of inconsistency that costs a debugging
+ * session for no reason.
+ */
+export declare function resolveTarget(target: Element | string): Element;
+/**
+ * Read everything paintable out of `root`, with coordinates relative to `root`'s
+ * own top-left rather than the viewport — so the result is independent of scroll
+ * position and of where the element sits on the page.
+ *
+ * Ops come out in document order. Because an element precedes its descendants,
+ * a parent's background is painted before the text inside it, which is the
+ * painter's order a browser uses for ordinary flow content.
+ */
+export declare function captureElement(target: Element | string): CapturedDocument;

package/dist/capture/fragments.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pagination hints read from the document.
+ *
+ * Slicing cannot re-flow, but it *can* choose where to cut. Reading the same
+ * hints the browser's own print path uses — `break-inside: avoid` and
+ * `display: table-header-group` — lets page boundaries land between rows instead
+ * of through them, and lets a table's header follow it onto later pages.
+ */
+/** A vertical span in CSS px, relative to the captured root. */
+export interface Region {
+    top: number;
+    bottom: number;
+}
+export interface RepeatHeader {
+    region: Region;
+    element: Element;
+}
+/**
+ * Regions a page boundary must not pass through.
+ *
+ * Nested candidates are kept as-is: the planner walks them all and only needs to
+ * know whether *some* region straddles a proposed cut.
+ */
+export declare function readUnbreakable(root: Element, origin: DOMRect): Region[];
+/**
+ * Table headers that should repeat on continuation pages.
+ *
+ * `display: table-header-group` is exactly what `<thead>` computes to, so this
+ * picks up the intent already expressed in ordinary print stylesheets without a
+ * library-specific attribute.
+ */
+export declare function readRepeatHeaders(root: Element, origin: DOMRect): RepeatHeader[];