@breakflow/core

Framework-independent core pagination engine, layout models, scoring, and diagnostics for BreakFlow.

🚀 Try the Live Interactive Demo (Angular 22 + Signals + client-side jsPDF showcase)

Overview

@breakflow/core is the pure, zero-DOM core engine behind BreakFlow. It operates on an abstract layout tree representation, evaluating page break candidates, computing penalty scores, and producing deterministic page plans.

Because it has zero external dependencies and no browser DOM requirement, it runs anywhere: in Node.js, Web Workers, Edge runtimes, or in browser applications.

Key Features

• Page Geometry Calculators: Full support for standard formats (A3, A4, A5, Letter, Legal), orientations (portrait, landscape), and custom dimensions (mm, cm, in, pt, px).
• Break Scoring Engine: Sophisticated penalty heuristics for:
  • Orphan headings (keepWithNext)
  • Component fragmentation (keepTogether / break-inside: avoid)
  • Table row slicing
  • Unbalanced whitespace / awkward page breaks
• Table Splitting Planner: Computes non-destructive multi-page slices for tabular data with repeating header preservation.
• Diagnostic Reporter: Emits actionable layout warnings and issue logs (orphan-heading, split-component, overflow-block, empty-page).
• Declarative Configuration: Strongly-typed defineConfig() helper with smart default presets.

Installation

npm install @breakflow/core

Or using pnpm / yarn:

pnpm add @breakflow/core
# or
yarn add @breakflow/core

Quick Example

import { defineConfig, GreedyStrategy, calculatePageCapacity } from '@breakflow/core';

// 1. Define page geometry and rules
const config = defineConfig({
  page: {
    format: 'A4',
    margin: { top: '15mm', bottom: '15mm', left: '15mm', right: '15mm' }
  },
  smartDefaults: true,
  table: {
    repeatHeader: true,
    preventRowSplit: true
  }
});

// 2. Compute available vertical budget (px at 96 DPI)
const capacity = calculatePageCapacity(config.page);
console.log(`Usable page height: ${capacity.contentHeight}px`);

// 3. Plan pagination strategy
const strategy = new GreedyStrategy(config);
// ... pass layout tree nodes to plan pagination

Monorepo Packages

• @breakflow/core - Core algorithmic engine (this package)
• @breakflow/browser - DOM layout measurement & sandbox paginator
• @breakflow/playwright - Server-side Headless Chromium PDF adapter
• @breakflow/cli - Command-line analysis & PDF generation tool

Links

• GitHub Repository: github.com/mehmetduran932/BreakFlow
• Live Demo: temporary-fast-argon-5v5qgvo.vercel.app
• Documentation: BreakFlow Documentation

License

MIT © BreakFlow Contributors