jsafa-pdf 0.1.1

package/dist/capture/image.d.ts

@@ -0,0 +1,28 @@
+import { type PathSegment, type Radii } from './box';
+import type { Rect } from '../types';
+/** Anything we can get pixels out of. */
+export type ImageSource = HTMLImageElement | HTMLCanvasElement | SVGSVGElement;
+export interface ImagePaint {
+    /** Where the image is drawn, after object-fit. May overflow the content box. */
+    draw: Rect;
+    /**
+     * Clip region in CSS px, or null when the image sits entirely inside its box
+     * with square corners. Needed for `object-fit: cover` and border-radius.
+     */
+    clip: PathSegment[] | null;
+    source: ImageSource;
+    opacity: number;
+}
+/** Natural (intrinsic) pixel size of a source, or null if not yet known. */
+export declare function naturalSize(source: ImageSource): {
+    width: number;
+    height: number;
+} | null;
+/**
+ * Read a paintable image, or null when there is nothing to draw.
+ *
+ * Only the geometry is resolved here. Pixel bytes are fetched during emission,
+ * because that is async and capture must stay synchronous — layout must be read
+ * in one pass, before anything can change it.
+ */
+export declare function readImage(element: Element, origin: DOMRect, radii: Radii): ImagePaint | null;

package/dist/capture/link.d.ts

@@ -0,0 +1,17 @@
+import type { Rect } from '../types';
+export interface LinkPaint {
+    /**
+     * One rect per line box the anchor occupies — a link that wraps across lines
+     * needs an annotation per line, not one box spanning both.
+     */
+    rects: Rect[];
+    url: string;
+}
+/**
+ * Read a clickable link, or null when the anchor is not one.
+ *
+ * `javascript:` targets do nothing in a PDF, and a bare `#fragment` refers to
+ * page state that does not survive the export, so both are skipped rather than
+ * written as annotations that silently fail when clicked.
+ */
+export declare function readLink(element: Element, origin: DOMRect): LinkPaint | null;

package/dist/capture/ready.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wait until a subtree is safe to capture.
+ *
+ * Capture reads laid-out geometry in a single synchronous pass, so anything
+ * still loading is silently wrong rather than merely late: text measured before
+ * its webfont arrives gets fallback metrics, and an image that has not decoded
+ * reports no intrinsic size and is skipped entirely.
+ *
+ * Both failure modes produce a plausible-looking PDF, which is why this runs by
+ * default instead of being left to the caller to remember.
+ */
+export declare function waitForAssets(target: Element | string): Promise<void>;

package/dist/capture/style.d.ts

@@ -0,0 +1,32 @@
+/** Colour with alpha, components in 0..1, ready for PDF. */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** The subset of computed style the emitter needs to paint a run. */
+export interface RunStyle {
+    /** Font families in CSS fallback order, unquoted. */
+    families: string[];
+    /** Font size in CSS px. */
+    sizePx: number;
+    weight: number;
+    italic: boolean;
+    color: Rgba;
+}
+export declare const TRANSPARENT: Rgba;
+/**
+ * Parse a computed colour. `getComputedStyle` always resolves to `rgb()` /
+ * `rgba()`, so names and hex never reach here.
+ */
+export declare function parseRgba(value: string): Rgba;
+/**
+ * Resolve any CSS colour string via the browser.
+ *
+ * Hand-parsing would mean reimplementing named colours, `hsl()`, `color-mix()`
+ * and everything else CSS keeps adding; letting the engine normalise it costs
+ * one throwaway element and is always right.
+ */
+export declare function cssColorToRgba(value: string): Rgba;
+export declare function readRunStyle(style: CSSStyleDeclaration): RunStyle;

package/dist/capture/text.d.ts

@@ -0,0 +1,12 @@
+import type { TextRun } from '../types';
+/**
+ * Read back how the browser laid out a text node.
+ *
+ * This is the load-bearing primitive of the library. We do not decide where
+ * lines break or where bidi runs start — the engine already did, and this
+ * recovers those decisions as positioned, paintable runs.
+ *
+ * A line of mixed Arabic/Latin/digits yields one run per directional segment,
+ * each already in correct visual order.
+ */
+export declare function extractTextRuns(node: Text): TextRun[];

package/dist/capture/transform.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CSS transform support.
+ *
+ * A transformed element defeats the usual approach outright: `getClientRects`
+ * reports axis-aligned bounding boxes of *already rotated* glyphs, so a rotated
+ * label decomposes into one run per character, each landing in its own vertical
+ * band. Painting those directly produces scattered, unrotated text.
+ *
+ * The way out is that **CSS transforms are a paint-time effect — they do not
+ * affect layout**. Nothing else on the page moves when a transform is removed.
+ * So capture neutralises them, reads the clean untransformed geometry, and
+ * re-applies each transform as a PDF matrix at paint time. Text stays a single
+ * run and stays selectable.
+ */
+/** 2D affine `[a, b, c, d, e, f]`, mapping (x,y) → (ax+cy+e, bx+dy+f). */
+export type Affine = [number, number, number, number, number, number];
+export declare const IDENTITY: Affine;
+/** Parse a computed `transform` value. Returns null for `none` or identity. */
+export declare function parseTransform(value: string): Affine | null;
+/** `transform-origin` in px, relative to the element's border box. */
+export declare function parseOrigin(value: string): {
+    x: number;
+    y: number;
+};
+/** Apply `inner` first, then `outer`. */
+export declare function compose(outer: Affine, inner: Affine): Affine;
+/**
+ * Express an element's transform in container coordinates.
+ *
+ * CSS applies the matrix about `transform-origin`, i.e. translate(O) · M ·
+ * translate(−O), so the origin has to be folded into the translation.
+ */
+export declare function aboutOrigin(matrix: Affine, originX: number, originY: number): Affine;
+interface Entry {
+    element: HTMLElement | SVGElement;
+    matrix: Affine;
+    originRaw: string;
+    previousInline: string;
+}
+export interface SuspendedTransforms {
+    /** Elements that carried a transform, with the data needed to rebuild it. */
+    entries: Entry[];
+    /** Put every inline style back exactly as it was. */
+    restore(): void;
+}
+/**
+ * Temporarily remove every transform in a subtree.
+ *
+ * Safe because transforms never participate in layout — sibling and ancestor
+ * geometry is unaffected, so what capture measures afterwards is the same
+ * layout the browser already computed, minus the paint-time distortion.
+ */
+export declare function suspendTransforms(root: Element): SuspendedTransforms;
+/**
+ * Build a lookup from element to its composed transform, in container
+ * coordinates. Must be called while transforms are suspended, because the
+ * origin depends on the element's untransformed layout box.
+ */
+export declare function buildTransformMap(suspended: SuspendedTransforms, origin: DOMRect): Map<Element, Affine>;
+/**
+ * Compose the transforms of an element and all its transformed ancestors,
+ * outermost first. Cached, since most elements have no transform at all.
+ */
+export declare function composedTransform(element: Element, own: Map<Element, Affine>, root: Element, cache: Map<Element, Affine | null>): Affine | null;
+export {};

package/dist/emit/image.d.ts

@@ -0,0 +1,14 @@
+import type { ImageSource } from '../capture/image';
+/** PDF can embed JPEG and PNG directly; everything else must be rasterised. */
+export interface ResolvedImage {
+    kind: 'jpg' | 'png';
+    bytes: Uint8Array;
+}
+/**
+ * Get embeddable bytes for an image.
+ *
+ * Fetching the original is preferred: a JPEG can be embedded byte-for-byte as
+ * DCTDecode with no re-encode, which keeps both quality and file size. Only if
+ * that fails, or the format is not one PDF understands, do we rasterise.
+ */
+export declare function resolveImage(source: ImageSource, cssWidth: number, cssHeight: number): Promise<ResolvedImage>;

package/dist/emit/page.d.ts

@@ -0,0 +1,98 @@
+import type { CapturedDocument, PaintOp } from '../capture/document';
+/** Page dimensions in PDF points (1/72 inch), portrait. */
+export declare const PAGE_SIZES: {
+    readonly A3: readonly [841.89, 1190.55];
+    readonly A4: readonly [595.28, 841.89];
+    readonly A5: readonly [419.53, 595.28];
+    readonly Letter: readonly [612, 792];
+    readonly Legal: readonly [612, 1008];
+};
+export type PageSizeName = keyof typeof PAGE_SIZES;
+export interface Margin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** A line of text drawn in the bottom margin of every page. */
+export interface FooterOptions {
+    /** Called once per page; return the line to draw. */
+    text: (info: {
+        page: number;
+        pages: number;
+    }) => string;
+    /** Family to render with. Must be registered or declared via `@font-face`. */
+    fontFamily?: string;
+    /** Points. Default 9. */
+    fontSize?: number;
+    /** Any CSS colour string. Default mid grey. */
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+}
+export interface PageOptions {
+    /** Named size or explicit `[width, height]` in points. */
+    size?: PageSizeName | [number, number];
+    orientation?: 'portrait' | 'landscape';
+    /** Points. Use the `mm` / `cm` / `inch` helpers for readability. */
+    margin?: number | Partial<Margin>;
+    /**
+     * `width` scales the captured element to fill the content width — the usual
+     * "fit to page" behaviour. `none` keeps 1 CSS px = 0.75pt, so wide content
+     * runs off the page.
+     */
+    fit?: 'width' | 'none';
+    /**
+     * Honour `break-inside: avoid` by moving a page boundary up rather than
+     * cutting through the element. Default true.
+     */
+    avoidBreakInside?: boolean;
+    /**
+     * Repeat `display: table-header-group` rows at the top of continuation pages.
+     * Default true.
+     */
+    repeatTableHeaders?: boolean;
+    footer?: FooterOptions;
+}
+/**
+ * How CSS pixels map into one page's PDF coordinates.
+ *
+ * `drawSvgPath` maps a path point (px, py) to (anchorX + px·scale,
+ * anchorY − py·scale), so a single anchor plus scale positions every kind of
+ * mark — text, paths and images alike — including the page's own vertical
+ * offset into the document.
+ */
+export interface Placement {
+    anchorX: number;
+    anchorY: number;
+    /** Combined CSS px → PDF pt factor, including any fit scaling. */
+    scale: number;
+}
+/** A table header redrawn at the top of a continuation page. */
+export interface RepeatedBlock {
+    headerIndex: number;
+    ops: PaintOp[];
+    placement: Placement;
+}
+export interface PlannedPage {
+    widthPt: number;
+    heightPt: number;
+    placement: Placement;
+    /** Content band for this page, in CSS px of the captured document. */
+    bandTopPx: number;
+    bandHeightPx: number;
+    ops: PaintOp[];
+    /** Headers redrawn above this page's band content. */
+    repeated: RepeatedBlock[];
+    margin: Margin;
+    footer?: FooterOptions;
+}
+/**
+ * Split a captured document into pages.
+ *
+ * Layout is sliced rather than re-flowed, so line breaks stay exactly where the
+ * browser put them. Page boundaries are nevertheless *chosen*: they snap above
+ * anything marked `break-inside: avoid`, and continuation pages reserve room for
+ * a repeated table header. That covers what a tabular report actually needs
+ * without re-running layout.
+ */
+export declare function planPages(captured: CapturedDocument, options: PageOptions): PlannedPage[];

package/dist/emit/pdf.d.ts

@@ -0,0 +1,14 @@
+import type { CapturedDocument } from '../capture/document';
+import { type PageOptions } from './page';
+export interface EmitOptions {
+    /** Subset embedded fonts. Shrinks output; not supported by every font file. */
+    subset?: boolean;
+    title?: string;
+    /**
+     * Paginate onto fixed-size pages. Omit to emit a single page sized exactly to
+     * the captured element.
+     */
+    page?: PageOptions;
+}
+/** Turn a captured document into PDF bytes. */
+export declare function emitPdf(captured: CapturedDocument, options?: EmitOptions): Promise<Uint8Array>;

package/dist/fonts/autodiscover.d.ts

@@ -0,0 +1,23 @@
+export interface DiscoveredFont {
+    family: string;
+    weight: number;
+    style: 'normal' | 'italic';
+    url: string;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Register every `@font-face` the page declares.
+ *
+ * Without this, a document that already declares its fonts in CSS still has to
+ * repeat every one of them through `registerFont`, which is both tedious and
+ * easy to get subtly wrong. Reading the stylesheets means the PDF embeds exactly
+ * the files the browser rendered with.
+ *
+ * Failures are per-font and non-fatal: one unreachable file should not stop a
+ * document from being produced. Cross-origin stylesheets throw on `cssRules`
+ * access and are skipped, since their bytes are unreachable anyway.
+ */
+export declare function registerFontsFromCss(doc?: Document): Promise<DiscoveredFont[]>;
+/** Forget which @font-face rules were already processed. */
+export declare function clearDiscoveredFonts(): void;

package/dist/fonts/registry.d.ts

@@ -0,0 +1,39 @@
+import { StandardFonts } from 'pdf-lib';
+import type { RunStyle } from '../capture/style';
+export interface FontSource {
+    /** CSS family name this font satisfies, e.g. "Noto Sans Arabic". */
+    family: string;
+    /** Font file bytes, or a URL / ArrayBuffer to load them from. */
+    src: string | ArrayBuffer | Uint8Array;
+    weight?: number;
+    style?: 'normal' | 'italic';
+}
+/**
+ * Make a font available for embedding.
+ *
+ * This is not optional polish — it is how the library gets glyphs. JavaScript
+ * cannot read arbitrary system font files, so any family that is not a PDF
+ * standard font must be registered (or reachable as a fetchable @font-face)
+ * before it can appear in a PDF. Notably, **any non-Latin script needs this**:
+ * the 14 standard PDF fonts have no Arabic coverage at all.
+ */
+export declare function registerFont(source: FontSource): Promise<void>;
+/** Forget all registered fonts. */
+export declare function clearFonts(): void;
+export declare function registeredFamilies(): string[];
+export type FontChoice = {
+    kind: 'registered';
+    key: string;
+    bytes: Uint8Array;
+} | {
+    kind: 'standard';
+    key: string;
+    name: StandardFonts;
+};
+/**
+ * Decide which font will paint a run. A registered face wins only if it can
+ * actually draw the text — see {@link matchRegistered}.
+ */
+export declare function resolveFont(style: RunStyle, text: string): FontChoice;
+/** True when the text needs glyphs the standard PDF fonts cannot provide. */
+export declare function needsEmbeddedFont(text: string): boolean;

package/dist/geom/units.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CSS reference pixels are 1/96 inch; PDF user-space units are 1/72 inch.
+ * Every dimension crossing the boundary goes through here.
+ */
+export declare const PX_TO_PT: number;
+export declare const pxToPt: (px: number) => number;
+export declare const ptToPx: (pt: number) => number;
+/** PDF points are 1/72 inch. These make page margins readable at call sites. */
+export declare const mm: (value: number) => number;
+export declare const cm: (value: number) => number;
+export declare const inch: (value: number) => number;
+/**
+ * CSS space is y-down from the top-left; PDF space is y-up from the bottom-left.
+ *
+ * @param yPx      distance from the top of the page, in CSS px
+ * @param heightPx total page height, in CSS px
+ * @returns        distance from the bottom of the page, in PDF pt
+ */
+export declare const flipY: (yPx: number, heightPx: number) => number;

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { type EmitOptions } from './emit/pdf';
+export interface ToPdfOptions extends EmitOptions {
+    /**
+     * Register `@font-face` fonts declared on the page automatically. Default
+     * true — without it, every font has to be repeated through `registerFont`.
+     */
+    autoFonts?: boolean;
+    /**
+     * Wait for webfonts and images before reading layout. Default true. Turning
+     * this off is only safe when everything is known to be loaded already.
+     */
+    waitForAssets?: boolean;
+}
+/** Convert an element to PDF bytes. Text stays real text: selectable and copyable. */
+export declare function toPdf(target: Element | string, options?: ToPdfOptions): Promise<Uint8Array>;
+/** Convert an element to a PDF Blob. */
+export declare function toBlob(target: Element | string, options?: ToPdfOptions): Promise<Blob>;
+/** Convert an element to PDF and save it to the user's downloads. */
+export declare function download(target: Element | string, filename?: string, options?: ToPdfOptions): Promise<void>;
+/** Open the PDF in a new tab instead of saving it. */
+export declare function open(target: Element | string, options?: ToPdfOptions): Promise<Window | null>;
+export { registerFont, clearFonts, registeredFamilies, type FontSource, } from './fonts/registry';
+export { registerFontsFromCss, clearDiscoveredFonts, type DiscoveredFont, } from './fonts/autodiscover';
+export { PAGE_SIZES, type PageOptions, type PageSizeName, type Margin, type FooterOptions, } from './emit/page';
+export { mm, cm, inch } from './geom/units';
+export { captureElement, type CapturedDocument, type CapturedRun, type PaintOp } from './capture/document';
+export { waitForAssets } from './capture/ready';
+export { extractTextRuns } from './capture/text';
+export type { LinkPaint } from './capture/link';
+export type { Affine } from './capture/transform';
+export { clearBaselineCache } from './capture/baseline';
+export { planPages, type Placement, type PlannedPage } from './emit/page';
+export { emitPdf, type EmitOptions } from './emit/pdf';
+export { pxToPt, ptToPx } from './geom/units';
+export type { TextRun, Rect, Direction } from './types';
+export type { RunStyle, Rgba } from './capture/style';
+export type { BoxPaint, BorderEdge, Radii } from './capture/box';
+export type { ImagePaint, ImageSource } from './capture/image';