# Folio

> Folio is a DOM-free paginated document engine for the web (TypeScript, `@nextgensoftwares/folio-*` packages, Apache-2.0, pre-1.0). It lays out ProseMirror-shaped JSON into Word-like pages using an injected text measurer (HarfBuzz over real font files), so the same layout runs in Node, a Web Worker and the browser. The editor, PDF export and DOCX export all read that layout or model.

Key facts for programs:

- Documents are plain JSON: `{ type, attrs?, content?, text?, marks? }`, root `{ type: 'doc', content: [...] }`. Nodes are immutable; caches key on object identity, so never mutate nodes in place.
- `validate(doc, schema)` returns every issue with its path and never throws; `normalize` returns a cleaned copy.
- `layoutDocument(doc, { measurer, theme?, cache?, previous?, ... })` returns `{ pages, warnings }`. Each page has `number`, `blocks: { first, last } | null` (top-level block range), lazy `fragments` (line, rect, media, math, marker, custom) with `path` back to the source node. Units are CSS px.
- Output is deterministic for the same document, theme and font bytes. Tests use a fixed-advance measurer: `{ width: (t, f) => t.length * f.size * 0.5 }`.
- Pagination rules (widows/orphans, keepWithNext, keepLinesTogether, pageBreakBefore, repeated table headers) are break penalties on measured flows.
- Edits are ProseMirror steps (JSON). `docChecksum(pmDoc)` proves two copies are identical; servers verify a result checksum on every push.
- Extensions are `FolioPlugin` objects (schema, renderers, painters, commands, keymap, UI items, formatter rules, exporter mappings), merged with `composePlugins(baseSchema, plugins)`.

## Guides

- [Getting started](/guide/getting-started): install, headless layout in Node, React embed
- [Document model & schema](/guide/document-model): JSON shape, standard schema, extend, validate
- [Layout pipeline](/guide/layout-pipeline): Flow, breaks, pagination rules, fragments, headers/footers, formatter hints
- [Incremental layout](/guide/incremental-layout): cache, previous, convergence, page reuse
- [Fonts & measurement](/guide/fonts): TextMeasurer contract, FontEngine
- [The editor](/guide/editor): headless ProseMirror core, position index, input, keymap
- [Loading & saving](/guide/loading-saving): chunked protocol, SyncClient, offline outbox, data safety
- [Performance](/guide/performance): numbers and rules for plugin authors
- [Plugin anatomy](/plugins/), [Tutorial: a custom block](/plugins/custom-block) and [Customizing the UI](/plugins/customizing-ui): slots, hide/move/arrange
- [Exporters](/plugins/exporters): PdfPainter / NodeExporter (attrs, ctx), PrintFallback, splitExporters

## API reference

- [@nextgensoftwares/folio-model](/api/model): FolioNode, Schema, standardSchema, validate, normalize
- [@nextgensoftwares/folio-layout](/api/layout): layoutDocument, LayoutCache, Theme, Fragment types, Flow, stack, paginate
- [@nextgensoftwares/folio-fonts](/api/fonts): FontEngine (HarfBuzz TextMeasurer), face matching
- [@nextgensoftwares/folio-formatter](/api/formatter): format, FormatRule, built-in rules
- [@nextgensoftwares/folio-editor](/api/editor): FolioEditor, PositionIndex, commands, composePlugins, FolioPlugin, collaboration
- [@nextgensoftwares/folio-sync](/api/sync): DocumentApi protocol, openDocument, assembleDocument, SyncClient, MemoryDocumentServer, docChecksum
- [@nextgensoftwares/folio-react](/api/react): FolioView, FolioToolbar, menus, page setup, theme editor (in progress)
- [@nextgensoftwares/folio-plugin-media](/api/plugin-media): media and file attachments, uploaders
- [@nextgensoftwares/folio-plugin-toc](/api/plugin-toc): outline, table of contents, navigation (in progress)
- [@nextgensoftwares/folio-export-pdf](/api/export-pdf): exportPdf from a layout (in progress)
- [In progress & stubs](/api/in-progress): @nextgensoftwares/folio-plugin-collab, @nextgensoftwares/folio-export-docx, @nextgensoftwares/folio-docx, @nextgensoftwares/folio-pdf

## Optional

- [Architecture decision records](/adr/)
- [Contributing](/contributing/)
- [License & attribution](/guide/license): Apache-2.0 with NOTICE