@asterdoc/render 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Paradoc AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+**Trademark Notice**: This license does not grant permission to use the trade names, trademarks, service marks, logos, taglines, or product names of Asterdoc, except as required for reasonable and customary use in describing the origin of the Software.

package/README.md

@@ -1,3 +1,265 @@
-# Temporary Holding Version
+<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>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<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.
+
+## 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.
+
+## 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',
+    },
+  ],
+})
+```
+
+`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`.
+
+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 })
+```
+
+## 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.

package/dist/check-BA5xdYgi.d.ts

@@ -0,0 +1,69 @@
+import { TypeEnv } from '@asterdoc/expr';
+
+/**
+ * Template diagnostics: where an expression sits in a layer, and what replaces
+ * syntax the single expression language no longer accepts.
+ */
+/** A position inside a text template (1-based line and column). */
+interface TemplatePosition {
+    line: number;
+    column: number;
+}
+/** One problem found in a template, at authoring validation or render. */
+interface TemplateDiagnostic {
+    /** Stable category: `syntax`, `removed-syntax`, `markers`, a checker code, or an evaluation code. */
+    code: string;
+    message: string;
+    /** The expression source, when the problem is inside one. */
+    expression?: string;
+    /** Line and column in a text template, or in the paragraph of a DOCX part. */
+    position?: TemplatePosition;
+    /** The DOCX part and paragraph, such as `word/document.xml paragraph 12`. */
+    location?: string;
+}
+/** A template that cannot render: malformed markers, a failed expression, or removed syntax. */
+declare class TemplateError extends Error {
+    readonly code: string;
+    readonly layer?: string;
+    readonly expression?: string;
+    readonly position?: TemplatePosition;
+    readonly location?: string;
+    readonly diagnostic: TemplateDiagnostic;
+    constructor(diagnostic: TemplateDiagnostic, layer?: string);
+    /** The same error, naming the layer it came from. */
+    inLayer(layer: string | undefined): TemplateError;
+}
+
+/**
+ * Authoring checks for template expressions.
+ *
+ * Every condition, loop source, placeholder, and directive argument is parsed
+ * and type-checked against the artifact's type environment, the one its field
+ * logic is checked against. A condition must be boolean and a loop source a
+ * list; `item`, `parent`, a DOCX loop's name, and the loop-only functions
+ * resolve only inside a loop.
+ */
+
+/** Check every expression in a text, Markdown, or HTML template. */
+declare function checkTextTemplate(template: string, env: TypeEnv): TemplateDiagnostic[];
+interface DocxCheckOptions {
+    /** Command delimiters, when the template does not use `{{` and `}}`. */
+    cmdDelimiter?: [string, string];
+}
+/** Check every control command and expression in a Word template. */
+declare function checkDocxTemplate(template: Uint8Array, env: TypeEnv, options?: DocxCheckOptions): TemplateDiagnostic[];
+/** A signing directive a template writes, such as `signature(parties.tenant, "tenant-sign")`. */
+interface SigningDirectiveUse {
+    /** The directive name: `signature`, `initials`, `signatureDate`, `capacity`, or `printedName`. */
+    directive: string;
+    /** The location the directive places, when written as a string literal; undefined when computed. */
+    location?: string;
+}
+/**
+ * The signing directives a text, Markdown, or HTML template writes, including
+ * those inside blocks. Undefined when the template's markers do not parse, so
+ * which directives it writes is unknown.
+ */
+declare function textTemplateSigningDirectives(template: string): SigningDirectiveUse[] | undefined;
+
+export { type DocxCheckOptions as D, type SigningDirectiveUse as S, type TemplateDiagnostic as T, TemplateError as a, type TemplatePosition as b, checkDocxTemplate as c, checkTextTemplate as d, textTemplateSigningDirectives as t };

package/dist/chunk-4QVR6LUY.js

@@ -0,0 +1,98 @@
+// src/layer-bindings.ts
+function isPdfLayer(layer) {
+  return layer.mimeType?.toLowerCase() === "application/pdf";
+}
+function resolveLayerBindings(layers, layer) {
+  if (!isPdfLayer(layer)) return void 0;
+  if (layer.bindings || !layer.bindingsFrom) return layer.bindings;
+  const source = layers[layer.bindingsFrom];
+  if (!source) {
+    throw new Error(`bindingsFrom "${layer.bindingsFrom}" references unknown layer. Available: ${Object.keys(layers).join(", ")}`);
+  }
+  return isPdfLayer(source) ? source.bindings : void 0;
+}
+var PdfBindingSyntaxError = class extends Error {
+  binding;
+  constructor(binding, problem) {
+    super(`Binding ${JSON.stringify(binding)} ${problem}.`);
+    this.name = "PdfBindingSyntaxError";
+    this.binding = binding;
+  }
+};
+function parseBinding(binding) {
+  const parts = binding.split(",").map((text) => {
+    const separator = text.indexOf(":");
+    const source = (separator === -1 ? text : text.slice(0, separator)).trim();
+    if (!source) throw new PdfBindingSyntaxError(binding, "has an empty path");
+    if (separator === -1) return { source, path: bindingDataPath(source) };
+    const qualifier = text.slice(separator + 1).trim();
+    if (!qualifier) throw new PdfBindingSyntaxError(binding, `has an empty qualifier after "${source}:"`);
+    return { source, path: bindingDataPath(source), qualifier };
+  });
+  if (parts.length > 1 && parts.some((part) => part.qualifier !== void 0)) {
+    throw new PdfBindingSyntaxError(binding, "qualifies a part of a joined binding; a joined binding reads whole values");
+  }
+  return parts;
+}
+function parseBindings(bindings) {
+  return Object.entries(bindings).map(([pdfName, binding]) => [pdfName, parseBinding(binding)]);
+}
+function splitPartIndex(qualifier) {
+  return /^[1-9]\d*$/.test(qualifier) ? Number(qualifier) - 1 : void 0;
+}
+var PdfBindingKeyError = class extends Error {
+  /** The binding keys the template has no field for. */
+  keys;
+  constructor(keys, templateFields) {
+    super(
+      `PDF bindings name form fields the template does not have: ${keys.map((key) => JSON.stringify(key)).join(", ")}. ` + (templateFields.length > 0 ? `Template fields: ${templateFields.join(", ")}` : "The template has no form fields")
+    );
+    this.name = "PdfBindingKeyError";
+    this.keys = keys;
+  }
+};
+function bindingDataPath(path) {
+  const trimmed = path.trim();
+  return trimmed.startsWith("fields.") ? trimmed.slice("fields.".length) : trimmed;
+}
+function renderDataPath(data, path) {
+  const trimmed = path.trim();
+  const hasFieldsRoot = data.fields !== null && typeof data.fields === "object" && !Array.isArray(data.fields);
+  if (!hasFieldsRoot) return bindingDataPath(trimmed);
+  if (trimmed.startsWith("fields.")) return trimmed;
+  const root = trimmed.split(".", 1)[0];
+  return root === "parties" || root === "annexes" || root === "defs" || root === "_signers" || root === "_captures" ? trimmed : `fields.${trimmed}`;
+}
+
+// src/path.ts
+var blockedSegments = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function pathSegments(path) {
+  const normalized = path.replace(/\[(\d+)\]/g, ".$1");
+  if (normalized.includes("[") || normalized.includes("]")) return [];
+  const segments = normalized.split(".");
+  return segments.some((segment) => segment.length === 0) ? [] : segments;
+}
+function getPath(value, path) {
+  const segments = pathSegments(path);
+  if (segments.length === 0) return void 0;
+  let current = value;
+  for (const segment of segments) {
+    if (blockedSegments.has(segment) || current === null || current === void 0) return void 0;
+    if (typeof current !== "object" && typeof current !== "function") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+
+export {
+  resolveLayerBindings,
+  PdfBindingSyntaxError,
+  parseBinding,
+  parseBindings,
+  splitPartIndex,
+  PdfBindingKeyError,
+  bindingDataPath,
+  renderDataPath,
+  pathSegments,
+  getPath
+};