renderpdf-js 0.0.0-stage → 0.1.0

package/dist/layout.d.ts

@@ -0,0 +1,20 @@
+import type { RegisteredFont } from './api-types.js';
+import type { LayoutSnapshot } from './types.js';
+/** Prepare browser resources, then snapshot the supported static DOM subset without changing it.
+ * @param root Connected, visible HTMLElement whose existing browser layout is exported.
+ * @param fonts Explicit faces used both by the browser and PDF embedding.
+ * @param options Whether safe local effects may choose raster boundaries automatically.
+ */
+export declare function snapshotLayout(root: HTMLElement, fonts: readonly RegisteredFont[], options?: {
+    /** Strict mode keeps native errors unless a boundary has explicit data-raster markup. */
+    fallback?: 'auto' | 'strict';
+}): Promise<LayoutSnapshot>;
+/** Measure settled browser resources synchronously so a source guard can share the same task.
+ * @param root Connected, visible HTMLElement with its fonts and source images already prepared.
+ * @param fonts Exact registered faces used both by the browser and PDF embedding.
+ * @param options Whether safe local effects may choose raster boundaries automatically.
+ */
+export declare function measurePreparedLayout(root: HTMLElement, fonts: readonly RegisteredFont[], options?: {
+    /** Strict mode keeps native errors unless a boundary has explicit data-raster markup. */
+    fallback?: 'auto' | 'strict';
+}): LayoutSnapshot;

package/dist/page.d.ts

@@ -0,0 +1,5 @@
+import type { PageGeometry, RenderPDFOptions } from './api-types.js';
+/** Resolve physical paper dimensions and validate the small public option surface. */
+export declare function resolvePage(
+/** Caller-owned options; resolving them never changes their values. */
+options: RenderPDFOptions): PageGeometry;

package/dist/pagination.d.ts

@@ -0,0 +1,17 @@
+import type { RenderWarning } from './diagnostics.js';
+import type { LayoutSnapshot } from './types.js';
+/** One source-coordinate interval mapped into a PDF page. */
+export interface PageSlice {
+    /** Inclusive source top in CSS pixels. */
+    start: number;
+    /** Exclusive source bottom in CSS pixels. */
+    end: number;
+}
+/** Map one continuous source into pages with required cuts and best-effort CSS avoidance. */
+export declare function paginate(
+/** Browser-measured display list plus optional CSS page-break metadata. */
+snapshot: LayoutSnapshot, 
+/** Usable height after top/bottom page margins, in CSS pixels. */
+contentHeight: number, 
+/** Optional observer for a preference that cannot fit without splitting native content. */
+onWarning?: (warning: RenderWarning) => void): PageSlice[];

package/dist/pdf.d.ts

@@ -0,0 +1,31 @@
+import type { PageGeometry, RegisteredFont } from './api-types.js';
+import type { PageSlice } from './pagination.js';
+import type { LayoutSnapshot } from './types.js';
+/** Bounded writer settings independent of DOM layout measurement. */
+export interface PDFWriteOptions {
+    /** Physical pixels per CSS pixel for explicitly selected raster regions. */
+    rasterScale?: number;
+    /** Include extraction-only text inside a region already painted as a bitmap. */
+    includeRasterText?: boolean;
+    /** Stop before beginning subsequent asynchronous writing stages. */
+    signal?: AbortSignal;
+}
+/** Serialized PDF and the exact source intervals used for page ownership. */
+export interface PDFWriteResult {
+    /** Complete PDF file owned by this export. */
+    bytes: Uint8Array;
+    /** Shared source offsets for visible objects and extraction text. */
+    slices: PageSlice[];
+}
+/** Serialize a measured display list with consistent ordered paint and page mapping. */
+export declare function writePDF(
+/** Prepared source geometry; this adapter never performs DOM measurement. */
+snapshot: LayoutSnapshot, 
+/** Exact font programs already registered for source browser layout. */
+fonts: readonly RegisteredFont[], 
+/** Validated physical page and per-edge margins, in CSS pixels. */
+geometry: PageGeometry, 
+/** Validated source intervals planned before diagnostics and any PDF allocation. */
+slices: PageSlice[], 
+/** Optional raster quality and cancellation controls. */
+options?: PDFWriteOptions): Promise<PDFWriteResult>;

package/dist/planner.d.ts

@@ -0,0 +1,9 @@
+/** Identify only effects that a bounded subtree can reproduce without surrounding pixels.
+ * @param style Browser-computed declarations; native layout and typography remain unchanged.
+ */
+export declare function automaticRasterReason(style: CSSStyleDeclaration): string | undefined;
+/** Require a single formatting box that can be cloned into an independent rectangular viewport.
+ * @param element Candidate selected for its own local visual effects.
+ * @param style Browser-computed display mode for the candidate.
+ */
+export declare function assertAutomaticRasterBoundary(element: HTMLElement, style: CSSStyleDeclaration): void;

package/dist/prepare.d.ts

@@ -0,0 +1,17 @@
+/** Wait for one browser stage while releasing the cancellation listener on every outcome. */
+export declare function withCancellation<T>(
+/** Work whose underlying browser API may not itself accept an AbortSignal. */
+pending: Promise<T>, 
+/** Optional application cancellation. */
+signal?: AbortSignal): Promise<T>;
+/** Observe caller ownership throughout preparation, capture and asynchronous PDF writing. */
+export declare function prepareSource(
+/** Connected browser element; a live source is measured without cloning application state. */
+root: HTMLElement, 
+/** Optional cancellation for fonts and image preparation. */
+signal?: AbortSignal): {
+    ready: () => Promise<void>;
+    captureBaseline: () => void;
+    assertUnchanged: () => void;
+    dispose: () => void;
+};

package/dist/raster.d.ts

@@ -0,0 +1,20 @@
+import type { RegisteredFont } from './api-types.js';
+/**
+ * Captures one explicitly isolated, self-contained HTML region as PNG bytes.
+ * Gradients, rounded corners and inset shadows remain browser-painted. Effects
+ * involving a backdrop, external assets or pixels beyond the box fail explicitly.
+ */
+export declare function captureRaster(
+/** Connected source region; capture never mutates its DOM. */
+element: HTMLElement, 
+/** Font bytes also used to lay out the original browser document. */
+fonts: readonly RegisteredFont[], 
+/** Physical bitmap pixels per CSS pixel. */
+scale: number, 
+/** Fractional CSS origin retained inside a bitmap placed on an integer pixel grid. */
+offset?: {
+    /** Horizontal transparent padding in CSS pixels, from zero inclusive to one exclusive. */
+    x: number;
+    /** Vertical transparent padding in CSS pixels, from zero inclusive to one exclusive. */
+    y: number;
+}): Promise<Uint8Array>;

package/dist/render-pdf.d.ts

@@ -0,0 +1,21 @@
+import type { RenderPDFOptions, RenderPDFResult } from './api-types.js';
+import { type RenderWarning } from './diagnostics.js';
+/** Measure a stable browser element and export supported paint as selectable, paginated PDF. */
+export declare function renderDocument(
+/** Connected source in the current browser document; its width and markup stay caller-owned. */
+element: HTMLElement, 
+/** Explicit fonts and the small supported page, raster and diagnostic options. */
+options: RenderPDFOptions, 
+/** Research-only switch for comparing visible pixels without the invisible text layer. */
+includeRasterText?: boolean): Promise<{
+    snapshot: import("./types.js").LayoutSnapshot;
+    warnings: RenderWarning[];
+    bytes: Uint8Array;
+    slices: import("./pagination.js").PageSlice[];
+}>;
+/** Export a stable browser element through the minimal public PDF API. */
+export declare function renderPDF(
+/** Connected source; browser layout and caller-owned markup remain unchanged. */
+element: HTMLElement, 
+/** Explicit font programs and supported conversion options. */
+options: RenderPDFOptions): Promise<RenderPDFResult>;

package/dist/result.d.ts

@@ -0,0 +1,10 @@
+import type { RenderPDFResult } from './api-types.js';
+import type { RenderWarning } from './diagnostics.js';
+/** Retain immutable PDF output and expose browser-native forms without re-rendering the source. */
+export declare function createResult(
+/** Complete successfully written PDF bytes; never expose this owned buffer directly. */
+bytes: Uint8Array, 
+/** Physical PDF page count from the shared page mapping. */
+pageCount: number, 
+/** Export diagnostics, copied and frozen to preserve the original outcome. */
+warnings: readonly RenderWarning[]): RenderPDFResult;

package/dist/text.d.ts

@@ -0,0 +1,39 @@
+import { PDFHexString } from 'pdf-lib';
+import type { PDFDocument, PDFFont } from 'pdf-lib';
+/** One encoded glyph at its shaped origin, in unscaled font units. */
+export interface PositionedGlyph {
+    /** Authoritative PDF encoding returned by the public font adapter. */
+    encoded: PDFHexString;
+    /** Horizontal pen position including the font's placement offset. */
+    x: number;
+    /** Vertical pen position including the font's placement offset, positive upward. */
+    y: number;
+}
+/** Reusable shaping state for one exact static font during a single export. */
+export declare class PositionedFont {
+    readonly font: PDFFont;
+    /** Original font metrics and OpenType positioning owned by this export. */
+    private readonly program;
+    /** Identical words share shaping work without sharing browser coordinates. */
+    private readonly words;
+    /** Used glyph mappings include GSUB ligatures without Unicode cmap entries. */
+    private readonly unicode;
+    /** Used substituted glyphs also need nominal PDF widths even without cmap entries. */
+    private readonly widths;
+    /** Font units per em, used to convert shaped origins without stretching outlines. */
+    readonly unitsPerEm: number;
+    /** Own a shaper matching the font program embedded through pdf-lib.
+     * @param font Public PDF font whose encoding remains authoritative.
+     * @param bytes Exact registered program shared with browser layout.
+     */
+    constructor(font: PDFFont, bytes: Uint8Array);
+    /** Shape one browser-measured word while retaining kerning, ligatures and marks.
+     * @param text Complete word; splitting into characters would lose OpenType context.
+     * @param kerning Whether CSS admits kerning for this line.
+     */
+    shape(text: string, kerning?: boolean): readonly PositionedGlyph[];
+    /** Preserve extraction for every used shaped glyph, including uncoded ligatures.
+     * @param document Export document owning the public font reference and object context.
+     */
+    embedUnicode(document: PDFDocument): Promise<void>;
+}

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+import type { RenderWarning } from './diagnostics.js';
+/** A rectangle relative to the source root, measured in CSS pixels. */
+export interface Bounds {
+    /** Horizontal distance from the root's left edge. */
+    x: number;
+    /** Vertical distance from the root's top edge. */
+    y: number;
+    /** Browser-measured width. */
+    width: number;
+    /** Browser-measured height. */
+    height: number;
+}
+/** A browser-measured line of selectable text. */
+export interface TextOperation {
+    /** Discriminant for ordered paint dispatch. */
+    kind: 'text';
+    /** Line fragment bounds in root CSS pixels. */
+    bounds: Bounds;
+    /** Browser-resolved visible text for this line. */
+    text: string;
+    /** Browser-measured words retain native origins without accumulating run-width drift. */
+    runs: {
+        /** Word text, retaining ligatures and non-breaking spaces within each run. */
+        text: string;
+        /** Horizontal word origin relative to the source root, in CSS pixels. */
+        x: number;
+        /** Browser-measured word advance width in CSS pixels. */
+        width: number;
+    }[];
+    /** Baseline position relative to the root's top edge. */
+    baseline: number;
+    /** CSS font size in pixels. */
+    fontSize: number;
+    /** Exact registered family selected by the browser-facing font contract. */
+    family: string;
+    /** Registered face weight. */
+    weight: number;
+    /** Registered face style. */
+    style: 'normal' | 'italic';
+    /** Disable OpenType kerning when the browser explicitly selects font-kerning: none. */
+    kerning?: boolean;
+    /** Computed CSS rgb/rgba text color. */
+    color: string;
+    /** True for extraction-only text inside a raster subtree. */
+    invisible: boolean;
+}
+/** A supported axis-aligned box painted by native PDF operations. */
+export interface BoxOperation {
+    /** Discriminant for ordered paint dispatch. */
+    kind: 'box';
+    /** Border-box geometry in root CSS pixels. */
+    bounds: Bounds;
+    /** Computed solid background. */
+    background: string;
+    /** Uniform border color. */
+    borderColor: string;
+    /** Uniform border width in CSS pixels. */
+    borderWidth: number;
+}
+/** An explicitly isolated DOM subtree captured at its paint-order position. */
+export interface RasterOperation {
+    /** Discriminant for ordered paint dispatch. */
+    kind: 'raster';
+    /** Region in root CSS pixels; effects must stay within this box. */
+    bounds: Bounds;
+    /** Live source used only by the browser capture adapter. */
+    element: HTMLElement;
+}
+/** An image source embedded once as a PDF image object. */
+export interface ImageOperation {
+    /** Discriminant for ordered paint dispatch. */
+    kind: 'image';
+    /** Browser-measured image border box. */
+    bounds: Bounds;
+    /** Decoded image source; experiment fixtures use self-contained PNGs. */
+    element: HTMLImageElement;
+}
+/** A flattened, ordered experiment display list, not a general CSS paint tree. */
+export type PaintOperation = TextOperation | BoxOperation | RasterOperation | ImageOperation;
+/** Immutable geometry metadata plus a bounded list of ordered paint operations. */
+export interface LayoutSnapshot {
+    /** Measured root width in CSS pixels. */
+    width: number;
+    /** Measured root height in CSS pixels. */
+    height: number;
+    /** Operations in the supported static DOM paint order. */
+    operations: PaintOperation[];
+    /** Explicitly diagnosed approximations and unsupported behavior. */
+    warnings: RenderWarning[];
+    /** Indivisible browser-measured table rows and spanning cells, in root CSS pixels. */
+    atomicBounds?: Bounds[];
+    /** Forced CSS page boundaries in source coordinates; zero/end boundaries create no empty pages. */
+    forcedBreaks?: number[];
+    /** Preferred indivisible blocks; oversized preferences may relax with an explicit warning. */
+    avoidBreakBounds?: Bounds[];
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "renderpdf-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Browser-only HTML to PDF renderer with explicit fonts and local raster regions",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichalekJan93/renderPDF.js.git"
+  },
+  "homepage": "https://github.com/MichalekJan93/renderPDF.js#readme",
+  "bugs": {
+    "url": "https://github.com/MichalekJan93/renderPDF.js/issues"
+  },
+  "keywords": [
+    "pdf",
+    "html",
+    "browser",
+    "typescript",
+    "html-to-pdf"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist/index.js",
+    "dist/*.d.ts",
+    "README.md",
+    "LICENSE",
+    "assets/renderpdf-logo.png"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "dev": "vp dev --host 127.0.0.1",
+    "build": "npm run build:library",
+    "build:library": "npm run typecheck && vp build --config vite.library.config.ts && tsc -p tsconfig.build.json",
+    "prepack": "npm run build:library && npm run check:package",
+    "check:package": "node scripts/check-package.ts",
+    "typecheck": "vp check --no-fmt --no-lint",
+    "test": "vp test",
+    "test:browser": "playwright test",
+    "benchmark": "npm run build:library && playwright test --config playwright.benchmark.config.ts",
+    "lint": "vp lint",
+    "format": "vp fmt",
+    "format:check": "vp fmt --check",
+    "check": "vp check && npm test && npm run test:browser && npm run build && npm run check:package"
+  },
+  "dependencies": {
+    "@pdf-lib/fontkit": "^1.1.1",
+    "html-to-image": "^1.11.13",
+    "pdf-lib": "^1.17.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^26.6.5",
+    "@types/pngjs": "^6.0.5",
+    "pdfjs-dist": "^6.4.299",
+    "pixelmatch": "^8.0.0",
+    "pngjs": "^7.0.0",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0",
+    "vite-plus": "1.4.0"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.4.0"
+  }
+}