Skip to content

README.md

Latest commit

 

History

History
75 lines (51 loc) · 3.31 KB

README.md

File metadata and controls

75 lines (51 loc) · 3.31 KB

@vmprint/engine

The deterministic layout engine at the center of VMPrint.

This package is for developers who already know why they want a layout engine: they want authored structure in, positioned boxes out, and no browser screenshot pipeline pretending to be typesetting.

Primary API

The main surface is VMPrintEngine.

import { VMPrintEngine, loadDocument } from '@vmprint/engine';
import { StandardFontManager } from '@vmprint/standard-fonts';
import { PdfLiteContext } from '@vmprint/context-pdf-lite';

const document = loadDocument(sourceTextOrObject, 'document.json');
const engine = new VMPrintEngine(document, new StandardFontManager());

const { width, height } = engine.info.pageSize;
const context = new PdfLiteContext({
  size: [width, height],
  margins: { top: 0, right: 0, bottom: 0, left: 0 },
  autoFirstPage: false,
  bufferPages: false
});

await engine.render(context);
const pdf: Uint8Array = context.getOutput();

If you want the positioned pages before rendering, call await engine.layout() first. The resulting Page[] is cached and reused by render(). Documents can use layout.pageTemplates to change page dimensions or margins per page; the returned Page[] carries those resolved sizes through to renderers that support per-page media boxes.

For previews and incremental layout tools, layout() also accepts a page limit:

const firstTwoPages = await engine.layout({ stopAtPage: 1 });

stopAtPage is zero-based and inclusive. A value of 1 returns the page prefix through the second physical page and records the run as a "page-limit" stop in the simulation report.

VMPrintEngine is the preferred API going forward, but it is not a hard break with the past. The older low-level bootstrap path built around LayoutEngine, Renderer, createPrintEngineRuntime, and toLayoutConfig is still supported for advanced integrations that want finer control over layout and rendering stages.

What the engine owns

  • Document validation and normalization via loadDocument
  • Font-aware layout through a FontManager
  • Pagination and box generation
  • Per-page geometry resolution from document-level page templates
  • Rendering orchestration into any Context

What stays outside

  • Font acquisition and embedding policy
  • Output transport and file I/O
  • Source-format conversion
  • Overlay logic and tooling concerns

Those seams are described by the engine's exported contract types.

Lower-level surface

The package still exports lower-level pieces such as LayoutEngine, Renderer, SimulationLoop, spatial helpers, and document serialization utilities. They remain supported for tooling, tests, and engine-adjacent integrations, but they are no longer the primary entry point.

Recommended stacks

  • Smallest Node bootstrap: @vmprint/local-fonts + @vmprint/context-pdf
  • Zero-embedded standard-font PDFs: @vmprint/standard-fonts + @vmprint/context-pdf-lite
  • Custom environments: bring your own FontManager and Context

Related material