Building paragraf: a typesetter with industry-standard methods for print-ready publication quality documents in Node.js
Β§0 β Introduction
When you open a professionally printed book, a luxury product catalog, or a pharmaceutical package insert, the text feels different. Words are evenly spaced. Paragraphs have a calm, consistent density. Punctuation sits exactly where it should. The page looks deliberate.
When you generate the same content programmatically β using the JavaScript libraries available today β something is lost. Word spacing is uneven. Lines break at awkward places. Certain letter combinations look slightly wrong. The output is functional but it does not look typeset.
paragraf is an attempt to close that gap. 12 packages are complete, 3 are planned for the coming weeks. The typesetting core β line breaking, font shaping, optical margins, bidirectional text, hyphenation, styles, layout, and the compile pipeline β is production-ready. The print production layer β color management, color separations, and print-ready PDF output β and the visual editor layer are in progress. This article is an overview of what paragraf is, how it is built, and where it is going.
Β§1 β The Problem: Why does text look different in books vs documents generated by code?
Professional typesetting solves several distinct problems simultaneously. Most JavaScript PDF pipelines solve none of them.
Line Breaking
The greedy algorithm β used by every JavaScript PDF library and every browser β fills each line as fully as possible and breaks there, making each decision in isolation. The Knuth-Plass algorithm, developed by Donald Knuth and Michael Plass in 1981 and used by TeX and Adobe InDesign since then, treats the entire paragraph as a single optimisation problem and finds the break sequence that minimises total spacing deviation across all lines simultaneously.
The demo above shows the same text set with Knuth-Plass (left) and the greedy algorithm (right), at identical column width and font size.
Font Shaping
Correct line breaking requires correct word widths. Correct word widths require processing the actual glyph outlines in the actual font file: rules that combine letter pairs into designed ligature forms (the Glyph Substitution, or GSUB table) and rules that adjust spacing between specific character combinations (the Glyph Positioning, or GPOS table). Most libraries get this wrong β they approximate from pre-computed tables β and the errors compound directly into Knuth-Plass spacing calculations. paragraf uses rustybuzz β a Rust port of HarfBuzz, the shaping engine used by Firefox, Chrome, and LibreOffice β compiled to WebAssembly.
Optical Margin Alignment
A line beginning with a quotation mark or hyphen creates a visual indent even when geometrically flush, because those glyphs are narrower than full characters. The text block looks ragged at the margin even though every line starts at the same x coordinate. Optical margin alignment corrects this by allowing punctuation to protrude fractionally into the margin β typically 0.3 to 0.7 times the font size depending on the character β so the text block appears visually straight.
Bidirectional Text
Arabic and Hebrew run right-to-left (RTL). Latin text runs left-to-right (LTR). Each Arabic letter takes a different form depending on its position within a word β the letter ΨΉ (ayn) has four distinct forms: isolated, initial, medial, and final. Mixed LTR and RTL paragraphs require the Unicode Bidirectional Algorithm to resolve the correct visual order of characters. This is not a bolt-on feature β it requires the GSUB shaping pipeline to already exist. You cannot add BiDi to a library that approximates font metrics.
Hyphenation
Without correct hyphenation patterns, Knuth-Plass has fewer valid break points and is forced toward wider spacing or tighter compression. Hyphenation rules vary significantly by language and cannot be derived from simple character patterns β English breaks "rec-ord" differently as a noun versus a verb, German compounds stack hyphenation boundaries in ways that require dictionary knowledge, Turkish has vowel harmony rules that affect syllabification. paragraf uses the Liang algorithm implemented via the hyphen npm package, covering 22 languages.
In the example above, the minimum word length to hyphenate is 5, so words with fewer than 5 characters are not hyphenated.
Styles, Layout, and Assembly
Change the body font size in pdfmake and you change one paragraph, not the document. Without a style system with inheritance, every derived style is an independent manual update. Without a layout model, page geometry and unit conversions are the caller's responsibility on every project. Without a template schema, binding data fields to content slots β and handling missing fields gracefully β requires custom code per integration. paragraf provides all of it as a coherent stack: a style system with inheritance, a layout model handling units and page geometry, a template schema with defined missing-field behaviour, and a compiler assembling everything into a single function call.
Β§2 β The Architecture: Monorepo, Layered, Modular
paragraf is a monorepo of 12 published packages organised in strict layers. Each layer imports only from layers below it. No exceptions.
For most developers, @paragraf/compile is the only package that matters directly. It takes a template and a data record and returns a PDF buffer. The packages beneath it are there for developers who need to work at lower levels of the stack β custom renderers, browser-side line breaking, integration with existing font pipelines.
Layer 0 carries zero-dependency shared interfaces. Layer 1 covers the algorithm and measurement packages β line breaking, font engine, page layout, style registry β all browser-safe. Layer 2 adds the Rust/WebAssembly shaper and the SVG/Canvas renderer. Layer 3 is Node-only: the paragraph compositor with OMA and BiDi, and the PDF renderer. Layer 4 is the user-facing API: the template schema and the compile pipeline.
Β§3 β The Approach: Spec-Driven, AI-Assisted, Test-Validated
paragraf was designed and built through a disciplined two-loop process. The outer loop covers the project: problem, scope, specifications, constraints, high-level layer architecture, diagrams and models, and a versioned roadmap with future work. The inner loop covers each package: scope definition, input/output schemas, diagrams and models, a full implementation plan with defined steps and edge cases, unit tests written before implementation, then implementation against that specification, closing with integration and end-to-end tests validating every contract.
The two loops are not independent. An issue discovered mid-package β an edge case that invalidates an assumption, a schema that cannot express a required input β feeds back into the outer loop and may revise the project scope, the architecture, or the roadmap. The project artifacts are living documents, not a fixed contract.
The implementation was AI-assisted. Claude and GitHub Copilot were used as implementation engines operating against precise specifications. No agentic framework was used β every step involved a human decision. The specifications, architectural decisions, and constraint definitions came from domain knowledge: years working with software engineering, project management, InDesign, publishing automation, and multi-agent systems research.
The quality of AI-assisted output is directly proportional to the precision of the specification the human provides. A developer without this domain background asking an AI to build a typesetting engine would get something that looks like one but breaks in ways they would not recognise.
A separate article covering this process in detail will be published β the artifacts, the feedback loops, and the specific ways domain knowledge shaped the specifications.
Β§4 β The Technique: TypeScript, Node, WASM, Rust
The core packages are TypeScript targeting Node.js 18+. Browser-safe packages also run in modern browsers β the live demo executes the full shaping and line-breaking pipeline client-side without a server. The OpenType shaper is Rust compiled to WebAssembly via wasm-pack: Rust was chosen for access to the rustybuzz shaping library, which would have taken months (if not years) to reimplement correctly in TypeScript. When the WASM binary is unavailable, the pipeline falls back automatically to a fontkit TypeScript path. PDF output uses pdfkit. The monorepo uses npm workspaces with tsup for package builds and Vitest for testing across all packages.
Β§5 β The Live Demo: See It Yourself
The live demo runs entirely in the browser β the WASM shaper, the Knuth-Plass algorithm, and the SVG renderer all execute client-side. Type your own text, adjust the tolerance and looseness sliders, and watch the line breaks recalculate in real time. Four interactive pages: line breaking with side-by-side KP vs greedy comparison, layout controls, typography showcase, and multilingual rendering across 6 scripts.
The line breaking page β edit text, adjust tolerance, and see Knuth-Plass and greedy results recalculate side by side.
Β§6 β Future Work
paragraf's package architecture is stable and deliberate, though still open to revision as the project evolves. The 12 published packages cover the full typesetting pipeline from algorithm to PDF output, and the three remaining planned packages β @paragraf/color, @paragraf/color-wasm β address color management and print production, and @paragraf/studio β the browser-based editor template. Every feature below fits within the existing package structure as an enhancement, not a structural addition. That is a deliberate outcome of the layered architecture.
Color and print production are the most significant items ahead. ICC color profile support, CMYK color spaces, and PDF/X compliance β the ISO standard for print-ready PDF exchange β are the bridge between paragraf's current typesetting quality and full print production readiness. These depend on @paragraf/color-wasm, a Rust/LCMS2 WebAssembly package following the same pattern as the existing shaping layer.
Typographic quality features planned within existing packages include micro-typography (per-line letter-spacing adjustments as an additional optimisation degree of freedom alongside word spacing), font expansion (horizontal glyph scaling, another Knuth-Plass optimisation dimension), drop caps, small caps, optical sizes, and balanced ragged lines.
Layout and composition additions include page-level widow and orphan control (the paragraph-level penalty system exists; full page reflow is a separate pass in @paragraf/compile), vertical justification, cross-column baseline grid alignment, inline figures with text runaround, and anchored objects.
The Studio is a browser-based visual template editor β a web application in the monorepo, not a published npm package β that writes the same JSON format @paragraf/template defines. It is the non-developer interface to the compile pipeline: drag-and-drop frame layout, point-and-click style definitions, and a live PDF preview powered by the same WASM stack that runs in the demo today.
Contributions, issues, and discussions are open on GitHub. If you are working on a document pipeline and running into the limitations described in this article, opening an issue is the best place to start.
Annex: Terminology
Bleed β artwork that extends beyond the trim edge of a page to prevent white borders after cutting.
BiDi β Unicode Bidirectional Algorithm. Resolves display order for mixed left-to-right and right-to-left text.
Greedy line breaking β fills each line as fully as possible, one line at a time, with no lookahead.
ICC profile β International Color Consortium profile. Defines the color characteristics of a device for accurate color reproduction.
Knuth-Plass β optimal paragraph line-breaking algorithm (Knuth & Plass, 1981). Minimises total spacing deviation across all lines simultaneously.
OpenType shaping β processing font files to apply ligatures, kerning, and contextual letter forms defined in GSUB/GPOS tables.
Optical margin alignment (OMA) β allowing punctuation to protrude fractionally into the margin for a visually straight text edge.
PDF/X β ISO standard for print-ready PDF exchange. Guarantees color, font embedding, and other production requirements are met.
This article is the entry point to a series. Each section above corresponds to a dedicated article in this series, published as they become available. The algorithm, the WASM architecture, the compile pipeline, the AI-assisted development process, and the print production roadmap are each covered separately.
![Defluffer - reduce token usage π by 45% using this one simple trick! [Earthday challenge]](https://media2.dev.to/dynamic/image/width=1000,height=420,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Farticles%2Fiekbgepcutl4jse0sfs0.png)
