<p align="center">
  <a href="https://asterdoc.com?utm_source=github&utm_medium=render" target="_blank" rel="noopener noreferrer">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://assets.asterdoc.com/asterdoc-logo-400x400-dark.png" type="image/png">
      <img src="https://assets.asterdoc.com/asterdoc-logo-400x400-dark.png" height="64" alt="Asterdoc logo">
    </picture>
  </a>
  <br />
</p>

<h1 align="center">@asterdoc/render</h1>

<div align="center">

[![Asterdoc documentation](https://img.shields.io/badge/Documentation-Asterdoc-red.svg)](https://docs.asterdoc.com?utm_source=github&utm_medium=render)
[![Follow on Twitter](https://img.shields.io/twitter/follow/asterdoc?style=social)](https://x.com/asterdoc)

</div>

Dependency-light text, PDF, and DOCX rendering for Asterdoc. It works in modern
browsers and on the server. Forms use the MIME-selected renderer automatically
and load only the selected layer engine.

```ts
const output = await filled.render({ layer: 'final' })
```

Pass `createLayerRenderer()` explicitly when configuring the built-in renderer or
provide any compatible custom renderer as an override.

```ts
import { createLayerRenderer } from '@asterdoc/render'

const output = await filled.render({
  renderer: createLayerRenderer({ serializers }),
  layer: 'final'
})
```

Use a format-specific entry point for inspection, overlays, or other
format-specific operations so an application only bundles that implementation.

```ts
import { renderText } from '@asterdoc/render/text'
import { renderPdf } from '@asterdoc/render/pdf'
import { renderDocx } from '@asterdoc/render/docx'
```

`createLayerRenderer()` supports `text/plain`, `text/markdown`, `text/html`,
`application/pdf`, and DOCX Office MIME types. It fails loudly for an unknown
MIME type rather than guessing.

Values print with `defaultFormatter` unless you pass `formatter`. It is the
`@asterdoc/format` formatter with the phone and regions providers, so every
layer format an artifact declares prints. A formatter you create yourself needs
those providers for phone styles other than `e164` and for region names.

## Text templates

Text templates keep the block markers `{{#if}}`, `{{#unless}}`, `{{else}}`, and
`{{#each}}`. Everything inside a marker is an artifact expression from
`@asterdoc/expr`, the language field logic uses, so a condition means the same in
a template as in a rule. Templates do not execute arbitrary JavaScript.

```text
{{#if fields.approved and fields.total.amount > 1000}}
Approved for {{parties.owner.name}}: {{fields.total}}
{{else}}
Pending
{{/if}}

{{#each fields.items}}
- {{index(item) + 1}}. {{item.name}}{{#unless last(item)}},{{/unless}}
{{/each}}
```

Inside `{{#each}}`, `item` is the row and `parent` the enclosing row. A
condition must be boolean and a loop source a list. `checkTextTemplate()` and
`checkDocxTemplate()` check every expression against a type environment, and a
failed render throws `TemplateError` with the layer, position, and expression.

A placeholder, in a text or DOCX template, can carry format modifiers after a
`|`, as `key=literal` pairs separated by commas. They take the same options as
a layer `format`, for that one value:

```text
Due {{ fields.due | date.pattern="DD/MM/YYYY" }}, {{ fields.total | money.fractionDigits=0 }}
Call {{ fields.phone | phone.style="national" }}, born {{ fields.dob | part="year" }}
```

An unknown key, a bad literal, or a key that does not apply to the value's kind
throws `TemplateError` at render. `checkTextTemplate()` and
`checkDocxTemplate()` report it first when given `values: formValueResolver(form)`.

## PDF forms and overlays

A PDF render can fill AcroForm fields, add coordinate-based text or images, or
combine all three.
Overlay page numbers are one-based and coordinates use PDF points measured from
the bottom-left corner.

```ts
const output = await renderPdf({
  template,
  form,
  data: { name: 'Ada Lovelace' },
  bindings: { legal_name: 'name' },
  overlays: [
    { page: 1, x: 48, y: 72, text: 'Prepared for' },
    { page: 1, x: 48, y: 54, field: 'name', fontSize: 11 },
    {
      page: 1,
      x: 48,
      y: 20,
      width: 120,
      height: 30,
      image: signaturePng,
      mediaType: 'image/png',
      fit: 'contain',
    },
  ],
})
```

A binding is a path string or a binding object `{ path, format?, part? }`. A
PDF layer's `format` (the `format` option here) applies to every value it
prints; a binding's `format` merges over it per property. `part` prints one
piece of a date, phone, or money value as plain digits, such as a date's `year`
or a money amount's `cents`.

```ts
const output = await renderPdf({
  template,
  form,
  data,
  format: { date: { pattern: 'DD/MM/YYYY' } },
  bindings: {
    legal_name: 'name',
    birth_year: { path: 'dob', part: 'year' },
    fee: { path: 'fee', format: { money: { fractionDigits: 0 } } },
  },
})
```

`inspectAcroFormFields()` discovers fields without modifying a PDF.
`inspectPdf()` returns its page count and page dimensions. PNG overlays support
non-interlaced 8-bit grayscale, RGB, grayscale-alpha, and RGBA images; JPEG
overlays are also supported.

A filled field follows its own settings: declared font size or auto-size,
alignment, color, comb boxes, and multiline wrapping; a list box shows every
selected value. A value that does not fit shrinks to `MIN_FONT_SIZE` (6 points).
Past that, or with more characters than a comb field has boxes, the render throws
`PdfFieldFillError` with the field name, the `reason` (`overflow` or
`comb-length`), and the `limit`. Its `paths` are the artifact paths the field
prints, such as `fields.fullName`.

Each value, and each overlay text, uses the first font that can draw all of it:
the overlay's own `font` when it names one, then `font` (supplied at render
time), then `layerFont` (the font the artifact's PDF layer declares), then the
form's own embedded font for the field, then Helvetica for Latin-1 text. Fonts are TrueType programs given as `{ bytes, source }`, and
every font used is embedded. A character no font can draw fails with reason
`missing-glyph`; scripts that need shaping, such as Arabic or Devanagari, fail
with `unsupported-script` whatever font is available. A font that cannot be read,
is not TrueType, or forbids embedding fails with `PdfFontError` naming its
`source`.

`pdfFontMetrics(font)` measures text in a supplied font before you draw it:
`canDraw(text)` says whether overlays can draw every character, and
`width(text, size)` gives its width in points, so you can wrap overlay text
yourself.

## Reading filled forms back

`extractPdfData()` reads a filled PDF's AcroForm fields back through a layer's
bindings into artifact data, with a report for each binding target. Combined
bindings are reported as not recoverable rather than split. Most callers use
`form.extract()` from `@asterdoc/core`, which also chooses the PDF layer.

```ts
const { data, report } = await extractPdfData({ pdf: filled, form, bindings })
```

Values are read back through the format they were printed with. Each recovered
entry carries `lossy`, true when that format drops detail (upper case, a
rounded amount), so the value is the person's answer but may differ from the
one filled.

## Merging PDFs

`mergePdfs()` concatenates PDFs into one document, keeping every page in the
order given at its own size.

```ts
const packet = await mergePdfs([purchaseOrder, filledW9, certificate])
```

It writes a fresh document rather than an incremental update, because two
sources number their objects from one and an incremental update cannot hold
both. Every object a kept page can reach is copied with a new number and every
reference inside it rewritten; stream bytes are copied exactly as stored, so
nothing is re-encoded. The merge is deterministic: the same sources produce the
same bytes.

**What a merge drops.** Everything the old catalog held rather than the page:

| Dropped | Consequence |
| --- | --- |
| `AcroForm` | Field state is gone. Flatten a filled form with `flattenPdf()` first and its values arrive as page content. |
| `StructTreeRoot` and the role map | The pages are untagged. A copied page keeps its `StructParents` key, which then dangles; readers ignore it, screen readers lose the structure. |
| `Names` and `Dests` | A named destination no longer resolves, so a link that used one goes nowhere. |
| `OCProperties` | A page drawn with optional content loses the configuration deciding which layers are visible, and every layer paints. |
| `Lang` | The document declares no language. |
| `ViewerPreferences`, `PageMode`, `PageLabels` | Presentation hints are gone. |
| `Outlines` and `Metadata` | No bookmarks, no document metadata. |

None of those survive a print either, which is what makes the trade acceptable
for a packet assembled from documents that are already final. A caller who needs
any of them should say so rather than merge.

A single source is returned unchanged. Every failure names its source:
`PdfMergeError` carries the zero-based `source` index for a document with no
catalog, no pages, or bytes the parser cannot read at all.

An encrypted source throws `PdfEncryptedError`, as it does from every function
that reads or writes a PDF (`renderPdf`, `flattenPdf`, `selectPdfPages`,
`inspectPdf`, `extractPdfData`, and the rest). One check, in the parser every
entry point shares, decides: a trailer or cross-reference stream that declares
`/Encrypt`.

## Digital signature fields

`preparePdfSignature()` appends an incremental update that adds an invisible
signature field, an AcroForm with `/SigFlags 3`, and a signature dictionary
with a reserved `/Contents`. Sign `signedBytes(prepared)` with your own keys and
write the container with `embedPdfSignature()`. `readPdfSignature()` reads the
newest signature dictionary back, and its `coversWholeFile` is false when any
byte outside the container is unsigned.

```ts
const prepared = await preparePdfSignature(pdf, { contentsSize: 16384, signingTime: new Date(), name: 'Ada Lovelace' })
const signed = embedPdfSignature(prepared, createCmsSignature(signedBytes(prepared)))
```

## Signature placement

The `@asterdoc/render/pdf` subpath locates signature positions in converter-
produced PDFs without a PDF rendering engine. It reads the PDF text layer with
a built-in content-stream scanner, so it runs anywhere the renderer runs.

```ts
import { locate, extractFieldsFromPdf, encode, FieldType } from '@asterdoc/render/pdf'

// Find invisible markers injected during rendering, and literal anchor text.
const hits = await locate(pdf, [
  { id: 'client-sig', kind: 'marker', signerIndex: 0, fieldType: FieldType.SIGNATURE },
  { id: 'witness-sig', kind: 'anchor', text: 'Witnessed by:' },
])
// [{ id, page, x, y, width, height }] in PDF points, y from the top edge
```

`locate()` is all-or-nothing: an unresolved or ambiguous query throws a
`LocateError` naming every failed id, so a seal pipeline can never proceed on
a silently incomplete signature map. Anchor text must be unique unless the
query picks an `occurrence`, a one-based integer; any other `occurrence` throws a
`RangeError`. `extractFieldsFromPdf()` returns every marker in
a document, and throws `UnknownMarkerError` naming each marker whose field type
is not signature or initials; `pageTextRuns()` exposes positioned text runs for verification and
layout tooling.

## DOCX templates

DOCX rendering supports direct values, commands split across Word runs, custom
delimiters, line breaks, and structural commands:

```text
{{FOR line IN fields.items}}
{{line.name}}
{{END-FOR line}}

{{IF fields.approved}}
Approved
{{ELSE}}
Pending
{{END-IF}}
```

Conditions, loop sources, and placeholders are artifact expressions, as in text
templates. DOCX templates also support the signing directives `signature`,
`initials`, `signatureDate`, `capacity`, and `printedName`, written
`{{signature(parties.client, "client-sign")}}`.

`capacity` prints the signatory's capacity and `printedName` the signer's name.
After a `capacity` or `printed_name` capture at that location, each prints the
captured text. When no value is known, they fall back to a placeholder:
`[CAPACITY]` and `[PRINTED NAME]` in text templates, underscores in DOCX
templates. The `placeholder` and `captured` signature options replace the
defaults, but a known capacity or name wins over `placeholder`.

## Benchmarking

From a repository checkout, run `pnpm benchmark` from this package to record
current text, PDF, and DOCX timings. The benchmark is
intentionally separate from the unit-test gate, so timing variance does not
make ordinary tests flaky. Set
`ASTERDOC_BENCHMARK_ITERATIONS` to change the number of measured iterations.
Set `ASTERDOC_BINARY_BENCHMARK_ITERATIONS` for PDF and DOCX iterations. Use
`pnpm size-report` to verify browser bundles, server imports, and the exact npm
tarball contents and sizes without publishing.
