Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ jobs:
with:
python-version: '3.12'
- run: python -m pip install pypdf==6.19.0 pypdfium2==5.14.0 fonttools==4.65.0 pillow==12.3.0
- name: Read installed batch outputs and actual README examples independently
run: python tools/verify-batches.py
- name: Verify the packed Workers entry in local workerd
run: |
npm run verify:cloudflare
Expand Down Expand Up @@ -117,7 +119,7 @@ jobs:
npm run render:fonts -- --package-root output/font-baseline-consumer/node_modules/fullbleed --out output/font-baseline
npm run verify:fonts -- --evidence-root output/font-baseline --allow-legacy-metadata
npm run render:fonts
npm run verify:fonts -- --baseline output/font-baseline --reviewed-layout test/fixtures/inline-layout-2.5.43.json
npm run verify:fonts -- --baseline output/font-baseline --reviewed-layout test/fixtures/inline-layout-2.5.46.json
- name: Verify installed custom font families against explicit faces
run: |
npm run render:families
Expand All @@ -144,6 +146,11 @@ jobs:
output/native-verification/**/*.png
output/native-verification/**/input.html
output/native-verification/**/style.css
output/native-verification/**/records.json
output/native-verification/**/result.json
output/batch-verification/
output/pack-verification/batch-tests.log
output/pack-verification/installed-batches.log
output/pack-verification/verification.json
output/pack-verification/text-extraction.json
output/pack-verification/queue-tests.log
Expand Down Expand Up @@ -225,7 +232,7 @@ jobs:
run: |
python -m pip install pypdf==6.19.0 pypdfium2==5.14.0 fonttools==4.65.0 pillow==12.3.0
npm run render:fonts
npm run verify:fonts -- --reviewed-layout test/fixtures/inline-layout-2.5.43.json
npm run verify:fonts -- --reviewed-layout test/fixtures/inline-layout-2.5.46.json
npm run render:families
npm run verify:families
npm run render:inline
Expand All @@ -251,6 +258,7 @@ jobs:
npm run render:radial
npm run verify:radial
python tools/verify-components.py
python tools/verify-batches.py
npm run verify:cloudflare
python tools/verify-cloudflare.py
npm run verify:cloudflare:starter
Expand Down Expand Up @@ -298,6 +306,9 @@ jobs:
output/pack-verification/queue-tests.log
output/pack-verification/default-styles-tests.log
output/pack-verification/component-tests.log
output/pack-verification/batch-tests.log
output/pack-verification/installed-batches.log
output/batch-verification/
output/component-verification/
output/default-styles/
output/queue-verification/
Expand Down
68 changes: 65 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ no Python, Rust compiler, browser, or system fonts. MIT licensed.

Use `fullbleed` in Node.js, `fullbleed/browser` in a web application, or
[`fullbleed/cloudflare`](docs/cloudflare.md) inside a Cloudflare Worker.
Package **0.8.7** wraps the published **Fullbleed 2.5.43** engine.
Package **0.9.0** wraps the published **Fullbleed 2.5.46** engine.

[Try the browser playground](https://docs.fullbleed.dev/playground/) ·
[Documentation](https://docs.fullbleed.dev/getting-started/node/) ·
Expand Down Expand Up @@ -38,7 +38,7 @@ await writeFile('invoice.png', result.previews[0]);
Open `invoice.pdf` or its PNG preview. Inter is the default font. CommonJS also
works: `const { renderPdf } = require('fullbleed')`. TypeScript declarations are
included. For a pinned installation, use
`npm install --save-exact fullbleed@0.8.7`.
`npm install --save-exact fullbleed@0.9.0`.

Prefer components? [Compose documents with functions or JSX](#compose-documents-with-components)
and export HTML with or without styles using `fullbleed/ui`.
Expand Down Expand Up @@ -192,6 +192,67 @@ cover the twelve Latin faces, an embedded-font control, and the blank-preview
failure in public 0.3.1. Font provenance and complete license notices ship with
both the npm package and copied browser runtime.

## Generate a batch from one template

Use `renderPdfBatch()` for notices, letters, invoices, or statements that share a
design. The engine compiles the template once per request and returns one PDF in
record order, with page ranges and selected-font character reports:

```javascript
import { writeFile } from 'node:fs/promises';
import { renderPdfBatch } from 'fullbleed';

const result = await renderPdfBatch({
html: '<h1>Account {{account}}</h1><p>{{message}}</p>',
css: '@page { size: A5; margin: 18mm } h1 { color: #175c52 }',
records: [
{ account: '1042', message: 'Your account is up to date.' },
{ account: '1043', message: 'Your next review is scheduled for November.' },
],
});
await writeFile('notices.pdf', result.pdf);
for (const row of result.records) {
console.log(`Record ${row.recordIndex}: pages ${row.pageOffset + 1}–${row.pageOffset + row.pageCount}`);
}
```

`layout: 'reflow'` is the default: longer text can wrap and add pages. Choose
`layout: 'fixed'` for values that fit the compiled geometry; it retains the
template's layout and selected fonts. Records contain plain strings, including
literal `<` and `>` characters. Format numbers and dates in your application.
Every record must have the same own enumerable fields, exactly matching the
template's text bindings. Use ordinary renders for changes to document structure,
image sources, attributes, or CSS.

Component-authored templates use the same batch function:

```javascript
import { renderPdfBatch } from 'fullbleed';
import { Document, Heading, Paragraph } from 'fullbleed/ui';

const notice = Document(Heading('Account {{account}}'), Paragraph('{{message}}'));
const result = await notice.renderPdf(renderPdfBatch, {
records: [{ account: '1042', message: 'Your account is up to date.' }],
});
```

Each `result.records` entry has zero-based `recordIndex` and `pageOffset`, a
`pageCount`, and a `missingGlyphs` array. Missing characters reject the batch by
default. With `allowMissingGlyphs: true`, inspect each entry's `codepoint`, `char`,
`count`, and `fontsTried` before accepting the PDF. `fontsTried` identifies the
first selected registered font where the character was absent. The top-level
`missingGlyphs` number counts distinct missing code points across all records.
These checks exclude Base-14 fonts and text in images; they do not establish
correct shaping, layout, accessibility, or PDF conformance.

Batches accept the other rendering options, including previews and the combined
`maxPages` limit. Up to 10,000 records are accepted. HTML, CSS, and all record
keys/values share the 4,000,000 UTF-8 byte budget (1,000,000 in Cloudflare).
The PDF, reports, and optional previews remain in memory; split large workloads
according to your host's memory and CPU budget. Compilation is per request.
The browser renderer exposes `renderer.renderPdfBatch()` and Cloudflare exports
`renderPdfBatch` from `fullbleed/cloudflare`.

## Limit concurrent renders

Create one queue per application process and reuse it across requests:
Expand Down Expand Up @@ -291,7 +352,8 @@ Error codes include `INVALID_INPUT`, `MISSING_GLYPHS`, `PAGE_LIMIT`, `TIMEOUT`,
include `exitCode` and `signal`. Failed or cancelled calls do not return a partial
PDF. Caller-owned asset buffers are copied when a call starts.

`createRenderQueue({ concurrency?, maxQueue? })` exposes `renderPdf()` with the
`createRenderQueue({ concurrency?, maxQueue? })` exposes `renderPdf()` and
`renderPdfBatch()` with the
same options and result. Defaults are one active render and sixteen waiting
jobs. `maxQueue: 0` rejects buffering. Accepted calls snapshot their strings and
asset/font bytes immediately. The queue adds `QUEUE_FULL` and `QUEUE_CLOSED`,
Expand Down
18 changes: 13 additions & 5 deletions docs/browser.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Generate PDFs in a browser

The `fullbleed/browser` entry in Fullbleed 0.8.7 renders static HTML/CSS in a
dedicated Web Worker. It uses the same pinned 2.5.43 engine and bundled fonts as
The `fullbleed/browser` entry in Fullbleed 0.9.0 renders static HTML/CSS in a
dedicated Web Worker. It uses the same pinned 2.5.46 engine and bundled fonts as
the Node entry. The result is a `Uint8Array`, suitable for a PDF `Blob`, plus
optional PNG previews. No PDF server or account is required.

Expand All @@ -21,7 +21,7 @@ Install the package in your web project, then copy its browser files into the
directory your application serves as static files:

```sh
npm install --save-exact fullbleed@0.8.7
npm install --save-exact fullbleed@0.9.0
npx fullbleed-browser-assets public/fullbleed
```

Expand Down Expand Up @@ -76,14 +76,22 @@ document off the page's JavaScript thread. Normal browser HTTP caching can reuse
the static files according to your server's headers. There is no persistent
renderer pool or offline-service-worker installation.

For documents sharing one template, use `renderer.renderPdfBatch()` with
string-valued `records`. It returns one combined PDF and a `records` array of
page ranges and selected-font character reports. Reflow is the default; choose
`layout: 'fixed'` to retain the compiled geometry and fonts. Up to 10,000 records
are accepted, and their keys and values share the 4,000,000-byte source budget.
See the [batch authoring guide](../README.md#generate-a-batch-from-one-template)
for HTML and component examples. Download `result.pdf` with the same Blob flow.

## Inputs, limits and errors

`renderer.renderPdf(options)` returns `{ pdf, previews, pages, missingGlyphs,
engineVersion }`. `pdf` and each preview are byte arrays backed by ordinary
`ArrayBuffer` objects. A preview can be displayed with an `image/png` Blob URL;
release those URLs when replacing a preview or unmounting the component.

Options are `html`, `css`, `fonts`, `assets`, `previewDpi`, `timeoutMs`, `maxPages`,
Options are `html`, `css`, `defaultStyles`, `fonts`, `assets`, `previewDpi`, `timeoutMs`, `maxPages`,
`allowMissingGlyphs` and `signal`. They follow the [Node input rules](../README.md#api):
4,000,000 UTF-8 bytes of HTML/CSS, 64 MiB of supplied fonts/assets, previews at
36–300 DPI or disabled, a default 30-second deadline and 1,000-page limit.
Expand Down Expand Up @@ -117,7 +125,7 @@ WebAssembly instance has a 512 MiB ceiling, and previews need additional memory.

`FullbleedError.code` includes `INVALID_INPUT`, `UNSUPPORTED_BROWSER`,
`VERSION_MISMATCH`, `WORKER_FAILED`, `ENGINE_LOAD_FAILED`, `MISSING_GLYPHS`,
`PAGE_LIMIT`, `TIMEOUT`, `ABORTED`, `ENGINE_LIMIT`, `RENDER_FAILED` and
`INVALID_BINDINGS`, `PAGE_LIMIT`, `TIMEOUT`, `ABORTED`, `ENGINE_LIMIT`, `RENDER_FAILED` and
`PREVIEW_FAILED`. Version mismatch means the installed client and hosted worker
must be deployed together. Engine-load errors can indicate missing or changed
files, blocked requests or a content security policy that prevents WebAssembly.
Expand Down
19 changes: 14 additions & 5 deletions docs/cloudflare.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ the package's pinned WebAssembly engine and four font faces with your applicatio
The renderer uses an in-memory filesystem and produces PDF bytes plus optional
PNG previews. HTML/CSS and document data stay in the Worker handling the request.

This entry is checked in local `workerd` on Windows and Linux. A hosted
[Workers Playground smoke test](#hosted-playground-smoke-test) also reproduces the
invoice starter's PDFs. Production CPU, memory, startup behavior, and Free-plan
This entry is checked in local `workerd` on Windows and Linux. The historical
[Workers Playground smoke test](#hosted-playground-smoke-test) covers version
0.8.0. Production CPU, memory, startup behavior, and Free-plan
suitability still require testing in your deployment. See
[Cloudflare's current limits](https://developers.cloudflare.com/workers/platform/limits/).

Expand All @@ -21,7 +21,7 @@ local tests for normal, long, escaped and invalid invoices.
Use Node.js 22 or newer for your development tools:

```sh
npm install --save-exact fullbleed@0.8.7
npm install --save-exact fullbleed@0.9.0
npm install --save-dev --save-exact wrangler@4.151.3
```

Expand Down Expand Up @@ -96,6 +96,14 @@ its stylesheet embedded. This also renders with `css: ''` and
`defaultStyles: false`; the Workers checks compare both forms' PDF and preview
bytes. Remote stylesheets are not fetched.

Import `renderPdfBatch` from the same entry for documents sharing one template.
It accepts string-valued `records`, defaults to reflow, and returns one combined
PDF with page ranges and selected-font character reports for each record.
Record keys and values share the 1,000,000-byte source budget; the 20-page default
applies to the whole PDF. Up to 10,000 records are accepted. See the
[batch authoring guide](../README.md#generate-a-batch-from-one-template) for the
fixed-layout option, component templates, and missing-character policy.

## Options and execution

`renderPdf(options)` returns a Promise for `{ pdf, previews, pages,
Expand Down Expand Up @@ -148,7 +156,8 @@ python tools/verify-cloudflare.py

The Workers check uses the isolated tarball installation. It compares PDF and
PNG bytes with Node for Northstar, Common Ground, a custom font/SVG fixture, and
component-authored documents. It exercises input budgets, unsupported controls,
component-authored documents, and seven fixed/reflow batch cases. It compares
per-record reports and exercises input budgets, unsupported controls,
asset paths, page limits, missing glyphs, repeated calls, and failure recovery.
Runtime fetching and asynchronous Wasm compilation are disabled during the check.
An independent PDF reader checks pages, expected text, and the custom font face;
Expand Down
102 changes: 99 additions & 3 deletions engine/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading