WarblerPdf

WarblerPdf is a Flutter-inspired TypeScript framework for deterministic PDF generation. It is structured as a real framework: immutable widgets describe documents, elements own runtime identity, layout nodes compute geometry, render objects consume geometry, paint commands record platform-neutral drawing operations, the PDF renderer creates PDF objects, and the PDF writer serializes bytes.

Current Implementation Status

Implemented in the MVP:

• Bun workspace monorepo with Turborepo scripts.
• Strict TypeScript packages for core, widgets, layout, pagination contracts, rendering, painting, PDF rendering, PDF writing, fonts, testing, and the public facade.
• Public factory API for Document, Page, Text, Image, ImageNetwork, Container, Column, Row, Padding, SizedBox, PageBreak, and KeepTogether.
• Runtime support for text, images, containers, rows, columns, padding, sized boxes, explicit pages, and styled container decoration.
• Deterministic PDF generation using built-in Helvetica.
• Explicit multi-page documents.
• Tests for the implemented architecture layers.

Architected but not yet implemented:

• Automatic content pagination across physical pages.
• Advanced text shaping, Unicode fallback, Arabic shaping, and bidirectional layout.
• Vector import, table fragmentation, headers, footers, themes, and plugins beyond their documented architecture.
• Font parsing, subsetting, and embedding of custom font files.

Installation

bun install

For a new user project:

npm create warblerpdf@latest my-pdf
cd my-pdf
bun install
bun run dev

Basic Example

import { Column, Document, Page, Text, renderPdf } from "@warblerpdf/core";

const document = Document({
  children: [
    Page({
      size: "A4",
      child: Column({
        children: [Text("Hello PDF"), Text("Generated by the framework")],
      }),
    }),
  ],
});

const bytes = await renderPdf(document);

Architecture Pipeline

Document Widget
      |
      v
Element Tree
      |
      v
Layout Tree
      |
      v
Render Tree
      |
      v
Paint Commands
      |
      v
PDF Renderer
      |
      v
PDF Writer
      |
      v
Uint8Array

Monorepo Packages

Internal source folders:

• src/core: widgets, elements, diagnostics, and typed errors.
• src/widgets: public widget factories.
• src/layout: constraints, geometry, page and column layout.
• src/pagination: physical page pagination contracts.
• src/rendering: render tree objects.
• src/painting: paint command recording.
• src/pdf: PDF rendering adapter.
• src/pdf-writer: deterministic low-level PDF writer.
• src/text: deterministic MVP text measurement.
• src/fonts: built-in font descriptors.
• src/testing: reusable PDF and pipeline test helpers.

Published packages:

• @warblerpdf/core: public facade.
• @warblerpdf/playground: reusable preview server and warbler CLI.
• create-warblerpdf: starter template generator for npm create warblerpdf.

Development Commands

bun run format
bun run lint
bun run typecheck
bun run test
bun run build
bun run example:basic

Testing Commands

bun run verify

The test suite checks widget immutability, element ownership, text measurement, layout geometry, paint command order, PDF object serialization, deterministic output, and integration rendering.

Documentation

• Project Vision and Architecture
• Architectural Principles
• Widget Framework
• Layout Engine
• PDF Engine
• PDF Writer
• NPM Packaging
• Testing

Contribution Notes

Public widget construction must use factory functions. Internal widget classes are implementation details and are not exported from the public facade. New features should preserve the pipeline boundaries described in the architecture documentation and include tests at the lowest layer that proves the behavior.

See CONTRIBUTING.md for contribution licensing, copyright, and pull request guidelines.

License

WarblerPDF is released under the MIT License. You may use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software, provided that the copyright notice and license permission notice are included in all copies or substantial portions of the software.

The software is provided without warranty of any kind, including warranties of merchantability, fitness for a particular purpose, and noninfringement. Attribution must preserve the copyright notice, license text, and applicable project notices.

See LICENSE, NOTICE.md, and COPYRIGHT.md for the full license, ownership, and documentation notices.

© 2026

WarblerPDF is released under the MIT License.