# Changelog

Product updates and release notes

Canonical URL: https://docs.paradoc.dev/changelog/

All notable changes to Paradoc. Packages are versioned in lockstep.

## \[Unreleased]

## [0.8.0](/changelog/v0.8.0) - 2026-10-19

Paradoc 0.8 gives registries editions and versions. A registry manifest now lists every release of an artifact with its checksum, and the CLI and AI tools can ask for one edition or version.

### Highlights

* `paradoc add @ns/name[/edition][@version]` installs one release, checks its SHA-256, and records the edition and version in `.paradoc/lock.json`.
* `get_artifact` and registry sources in the AI tools take `edition` and `version`, and the output names the release that was read.
* `paradoc registry compile` builds a registry from `registry.config.json`: one manifest and a folder for each release.

### Breaking changes

#### Registries

* The registry manifest (`registry.json`) lists `currentEdition` and `editions`, or `latestVersion` and `versions`, for each item. `artifactsPath` and the item `path` are removed. Paradoc 0.8 cannot read an older manifest, and 0.7 cannot read a new one.

#### CLI

* `paradoc registry make` writes `registry.config.json` and no longer takes `--artifacts-path`. `registry catalog add`, `catalog remove` and `compile` read that file: `-r, --registry` is now `-c, --config`, and `catalog add` has no `--yes`.
* `paradoc check` takes `tsx` from your project, which halves the CLI install. Without it, the command stops and prints the install line.

#### AI tools

* `fetchRegistryItem`, `fetchRegistryItemResponse` and `buildArtifactItemUrl` are removed.
* The `get_registry` output has no `artifacts_path` or item `path`. Each item lists its editions and versions.

### Upgrading from 0.7

1. If you host a registry, run `paradoc registry make`, add your artifact files to `registry.config.json`, and run `paradoc registry compile`. Host the output in place of the old `registry.json` and `r/` folder, and upgrade its clients to 0.8 at the same time.
2. Replace calls to the removed AI tools registry functions with `fetchRegistryArtifact`.
3. Run `npm install -D tsx` in a project that runs `paradoc check`.

### Other changes

#### Schemas

* New exports resolve a release from a manifest (`resolveRegistryRelease`, `listRegistryReleases`), parse and format registry references, and compare versions by SemVer precedence.
* A lock file entry can record an `edition`.

#### Core

* An empty string no longer satisfies a required field or annex, so fill state keeps it open and validation reports it as missing.

#### CLI

* `paradoc search` shows every edition and version of an artifact.
* A reference to an edition or version the registry does not list fails and names the ones it does list.

## [0.7.1](/changelog/v0.7.1) - 2026-10-08

Paradoc 0.7.1 fixes problems that real models hit with the AI tools. Renders no longer report a blank file as success, registry calls can rely on the configured default registry, and the Mastra adapter passes free-form JSON through intact.

### Highlights

* `render` refuses a form or checklist with no values instead of returning a blank file. Set `blank: true` to render a blank copy on purpose.
* `registry_url` is optional. A call without it uses `defaultRegistryUrl`.
* `get_fill_state` returns typed targets, exported as `FillTarget` and `FillItemState` from every adapter.
* Mastra tools keep `data`, `patch` and `artifact` inputs, so OpenAI models no longer send `null` for them.
* The documentation has separate Docs and Reference tabs, and the AI agents section is rewritten as task guides.

### Other changes

#### AI tools

* `render` with missing, `null` or empty `data` for a form or checklist returns `success: false` with `missing_data`. If you render blank copies, pass `blank: true`.
* A registry call with no `registry_url` and no `defaultRegistryUrl` fails with `missing_registry_url`.
* The `get_fill_state` output schema types `open_required`, `open_optional`, `blocked`, `done`, `candidates` and `next`.

#### Core

* Progressive validation refuses an array for a party role with `max` 1. Pass one party object.

#### Adapters

* `@paradoc/mastra` creates its tools with `strict: false`.
* `@paradoc/ai-sdk`, `@paradoc/mastra` and `@paradoc/tanstack-ai` export the `FillTarget` and `FillItemState` types.

## [0.7.0](/changelog/v0.7.0) - 2026-10-08

Paradoc 0.7 records who issued a form and which edition an artifact encodes, and lets bundles address registry artifacts by edition and version. It also adds PDF digital-signature helpers and per-overlay fonts to the renderer.

### Highlights

* Artifacts carry an optional `issuer` and `edition` (`key`, `label`, `date`, `effectiveFrom`), and `code` is the form number as the issuer prints it.
* Registry coordinates take the form `@org/repo/name[/edition][@version]`, with helpers to parse and format them.
* `@paradoc/render/pdf` can prepare, embed and read a PDF digital signature.
* PDF text overlays can each use their own font, and `pdfFontMetrics()` reports whether a font can draw a string and how wide it is.
* `paradoc migrate` moves artifacts to schema `2026-10-02`.

### Breaking changes

#### Schemas and artifacts

* Schema `2026-10-02` removes `releaseDate`. Record the issuer and edition with `issuer` and `edition` instead.
* A registry bundle item's `slug` is only the address `@org/repo/name`. Edition and version move to the new `edition` and `version` fields. Edition keys cannot be `current`, `latest`, `editions`, `tags` or `diff`.
* The hosted `2026-09-24` schemas are removed from `schema.paradoc.dev`. Run `paradoc migrate` to move files to `2026-10-02`.

#### Core and SDK

* The builders drop `.releaseDate()` for `.issuer()` and `.edition()`. `.registry(key, coordinate, include?)` takes a full three-segment coordinate and throws a `TypeError` on any other value.

#### Essentials

* Each form's `spec` has a top-level `issuer` instead of `metadata.issuer`, and `metadata.sourceUrl` is removed.

### Upgrading from 0.6

1. Run `paradoc migrate <file-or-directory> --dry-run`, review the changes, then rerun without `--dry-run`. The step removes `releaseDate` and moves a slug's `@version` into `version`.
2. Correct by hand any registry slug that is not `@org/repo/name[@version]`, such as `@paradoc/essentials/tax/w-9@1.0.0`. The migration stops on it.
3. Replace `.releaseDate()` with `.issuer()` and `.edition()`, and pass full `@org/repo/name` coordinates to `.registry()`.
4. Read `issuer` from an essentials form's `spec` instead of `spec.metadata.issuer`.

### Other changes

#### Schemas and types

* `@paradoc/schemas` exports `parseArtifactCoordinate`, `formatArtifactCoordinate`, `ArtifactCoordinateSchema`, the edition and version selector schemas, and the reserved edition keys. `@paradoc/types` exports `ArtifactEdition`.

#### Core

* `sealBundle` refuses a part whose edition differs from the edition its bundle item declares.

#### Render

* `preparePdfSignature`, `signedBytes`, `embedPdfSignature` and `readPdfSignature` sign a PDF with a container from any signing service.
* A text overlay takes its own `font`, and `pdfFontMetrics(font)` returns `canDraw` and `width`.
* Rendering on a page that an earlier render drew on keeps the earlier fonts and images.

#### CLI

* `paradoc show` prints the issuer and edition, and shows registry bundle items as full coordinates. `paradoc new --code` sets the issuer's form number.
* The CLI sends all telemetry to `telemetry.paradoc.dev`. Public-registry installs send a `directory.installed` event in the same batch, and nothing goes to `tasks.paradoc.dev`. `PARADOC_TELEMETRY_URL` points the CLI at another telemetry origin, such as `https://telemetry-dev.paradoc.dev`.

#### AI tools

* `inspect_artifact` returns the artifact's issuer and edition.

## [0.6.1](/changelog/v0.6.1) - 2026-09-28

Paradoc 0.6.1 tightens prerelease schema distribution and makes the documentation easier for people and agents to discover. It also publishes a reusable service-layer boundary for projects using the Paradoc ESLint configuration.

### Highlights

* `@paradoc/schemas` now packages only the current dated schema set and live-root schemas, while older prerelease schemas remain available through Git history.
* The documentation publishes a permanent page for each release alongside the latest changelog index.
* Canonical URLs, a generated sitemap, and improved Markdown responses make documentation routes easier for search engines and agents to discover.
* `@paradoc/eslint-config/service-boundary` enforces API-free service modules by preventing imports from co-located contracts and `@paradoc/api-kernel`.

### Other changes

#### Documentation

* Public navigation no longer advertises the hosted MCP reference; AI guidance directs developers to the published adapter packages for in-process tools.
* Sidebar and content-grid behavior is more consistent across documentation pages.

## [0.6.0](/changelog/v0.6.0) - 2026-09-25

Paradoc 0.6 turns documents into a complete application surface: compose them in React, migrate versioned artifacts, extract filled PDFs, and seal multi-document packets. It also tightens public contracts across the SDK, CLI, rendering, sessions, and AI adapters.

### Highlights

* Dated schemas and `paradoc migrate` make artifact upgrades explicit, reviewable, and reversible with `--dry-run`.
* React layers, live `paradoc dev` previews, `paradoc check`, and the copyable component registry provide an end-to-end document composition workflow.
* `sealBundle` prepares and seals multi-part packets with one canonical PDF, packet-wide signer mapping, and part-level provenance.
* PDF rendering now embeds fonts, follows AcroForm appearance settings, rejects encrypted inputs, and can extract filled values back into artifact data.
* Templates and artifact logic share `@paradoc/expr`, including typed conditions, list aggregates, party data, and row-aware expressions.
* `@paradoc/format` replaces serialization with locale-aware formatting shared by text, DOCX, PDF, and React output.
* AI SDK, TanStack AI, and Mastra adapters expose the same validated document operations, including extraction and progressive filling.

### Breaking changes

#### Schemas and artifacts

* Artifact files must use the current dated `$schema`; run `paradoc migrate` before loading older, undated, or unversioned files.
* Signing fields now live only in `signatures`; migrate legacy `signatureBlocks` and `anchorBlocks` to signature slots.
* Field, party, option, and config schemas reject unknown keys; correct misspellings instead of relying on dropped properties.
* The marker placement literal is `flow`, not `auto`; the migration rewrites existing slots.

#### Core and SDK

* Import the builder namespace as `p` instead of `para`.
* `fill()` and `safeFill()` are progressive; replace partial-fill APIs with `fill()` followed by `update()`.
* Bind file resolvers when constructing or loading an artifact, not in `render()`, `seal()`, or bundle operations.
* Pass a `SealAdapter` through `seal({ adapter })`; the legacy `Sealer` overload and formal-signing aliases are removed.
* Replace `DraftForm.setField()` and `updateFields()` with `draft.update({ fields: ... })`.
* Custom renderers must read `parties`, `annexes`, `signers`, `captures`, and `defs` beside `data.fields`.

#### Rendering and React

* Import PDF runtime APIs from `@paradoc/react-pdf`; `@paradoc/react` now contains the headless React runtime and discovery APIs.
* Text and DOCX templates must use full paths such as `{{fields.name}}`; binding aliases are supported only on PDF file layers.
* PDF bindings now fail on missing fields, invalid roots, and malformed qualifiers; use AcroForm field names as keys and Paradoc paths as values.
* Replace legacy template helpers and Handlebars context paths with artifact expressions, `item`, `parent`, and `index(item)`.
* Application styles own typography; remove `fontFamily` tokens and registered package font families.
* Remove PDF signature rendering options and deprecated SDK renderer wrappers; use built-in rendering or `@paradoc/render` subpaths.

#### CLI, sessions, AI, and resolvers

* The CLI, `@paradoc/ai-tools`, `@paradoc/ai-sdk`, and `@paradoc/tanstack-ai` require Node.js 22 or newer.
* Invoke the CLI as `paradoc`; the `para` binary is removed.
* Configure every registry explicitly; the CLI no longer falls back to a default registry.
* Session projections now include annexes and richer party state; persist events directly instead of using the removed spine adapter.
* Use the unified `@paradoc/ai-tools` operation contracts and renamed validation outputs.
* Import resolvers from `@paradoc/resolvers/fs`, `/http`, or `/memory`; the package root exports nothing.
* Replace `@paradoc/serialization` with `@paradoc/format` and pass a formatter through render context.

### Upgrading from 0.5

1. Upgrade CLI and AI runtimes to Node.js 22 or newer.
2. Run `paradoc migrate <file-or-directory> --dry-run`, review the schema and signature-slot changes, then rerun without `--dry-run`.
3. Rename `para` imports to `p`, bind resolvers when artifacts are constructed, and replace removed draft and fill helpers.
4. Install `@paradoc/react-pdf` for React PDF rendering, checking, or Chromium output and update imports from `@paradoc/react`.
5. Replace template binding aliases and helpers, then run `paradoc validate` and `paradoc check` across the migrated project.

### Other changes

#### Core, schemas, and sessions

* Builders cover every schema key, and validation reports schema versions, file references, template expressions, signing slots, and PDF bindings earlier.
* List aggregates, typed party expressions, row references, progressive checklists, annex commands, and rule IDs improve guided form completion.
* Bundle rendering preserves nested parts, while sealing and finalization enforce signer, capture, and required-slot integrity.

#### Render, React, and components

* PDF fill and extraction support embedded fonts, Unicode strings, comb fields, multiline values, overlays, page selection, flattening, and merging.
* React documents add pagination, page furniture, explicit breaks, application fonts, right-to-left output, annex images, and packet previews.
* The `@paradoc` component registry ships document components and complete blocks for invoices, engagement letters, purchase orders, and vendor packets.
* Formatters add selection, rating, contact, temporal, money, party, attachment, and signature output with locale fallbacks and structured issues.

#### CLI, SDK, and AI

* `paradoc migrate`, `data extract`, `dev`, and `check` cover schema upgrades, PDF recovery, live composition previews, and static composition checks.
* CLI validation accepts multiple artifacts, validates project files and data through core, and preserves installed layer dependencies and checksums.
* AI adapters share bounded model output, validated inputs and outputs, fill-state inspection, updates, rendering, and extraction.
* `hostedSealAdapter` uses the served conversion route, supports cancellation, and reports structured conversion and response errors.

#### Packages

* `@paradoc/react`, `@paradoc/react-pdf`, `@paradoc/format`, and `@paradoc/mastra` join the public framework.
* `@paradoc/resolvers/http` safely resolves file-backed layers beneath a base URL in any runtime with `fetch`.
* Essentials artifacts and examples use current schemas, signature slots, formatter behavior, and rendering limits.

## [0.5.0](/changelog/v0.5.0) - 2026-08-10

Paradoc 0.5 introduces a single signature-slot model and a dependency-light placement engine for preparing documents before signing.

### Highlights

* Layers declare a unified `signatures` map for marker, anchor, or absolute signature placement.
* `prepareSeal()` returns the exact pre-flatten PDF, resolved fields, provenance, and warnings without changing form state.
* The built-in PDF locator resolves signature markers and anchor text without a PDF rendering engine.
* Pure byte converters such as `hostedSealAdapter` work with anchor-based sealing without extra placement configuration.

### Breaking changes

#### Core and types

* `SealingRequest.options` is removed; stop passing its unused `renderer` or `format` keys.

### Other changes

#### Schemas and render

* Schema version `2026-08-10` adds signature slots while keeping the published `2026-08-06` schemas available.
* `SealOptions.locate` allows a custom placement locator when the built-in PDF locator is not suitable.
* PDF parsing resolves indirect stream lengths, preserving content from PDFs written by LibreOffice.

## [0.4.0](/changelog/v0.4.0) - 2026-08-06

Paradoc 0.4 consolidates rendering into one dependency-light package and makes MIME-selected rendering the default across the framework.

### Highlights

* `@paradoc/render` renders text, Markdown, HTML, PDF, and DOCX layers through one public package.
* Form rendering and sealing select built-in renderers by MIME type while preserving custom renderer overrides.
* Recursive list fields work across builders, schemas, validation, serialization, and rendering.
* Sealing can flatten PDFs locally and delegate non-PDF conversion through an adapter.

### Breaking changes

#### Render

* Replace `@paradoc/renderers` and the format-specific renderer packages with `@paradoc/render` and its `/text`, `/pdf`, and `/docx` subpaths.

### Upgrading from 0.3

1. Update renderer imports and remove dependencies on `@paradoc/renderer-text`, `@paradoc/renderer-pdf`, and `@paradoc/renderer-docx`.

### Other changes

#### Schemas

* Schema version `2026-08-06` becomes current while the published `2026-01-01` schemas remain available.
* Rendering and e-signing paths no longer require the previous heavy PDF, DOCX templating, and Handlebars dependency stack.

## [0.3.0](/changelog/v0.3.0) - 2026-06-19

Paradoc 0.3 adds a purpose-built expression language and publishes the deterministic session engine for guided form completion.

### Highlights

* `@paradoc/expr` provides a typed parser, evaluator, and artifact-aware checker with exact decimal and temporal values.
* `@paradoc/sessions` provides an event-sourced, storage-agnostic form-completion engine.
* Fill state reports one visibility and requirement status, transitive blockers, and the next field in dependency order.
* The SDK exposes expression APIs through `expr`, including parsing, checking, and `Decimal`.

### Other changes

#### Core

* Artifact logic runs on `@paradoc/expr`, and hidden fieldsets now hide their full subtree.
* The `expr-eval-fork` dependency is removed.

## [0.2.0](/changelog/v0.2.0) - 2026-05-19

Paradoc 0.2 adds labeled enum choices and source-language metadata across artifacts, schemas, builders, and CLI workflows.

### Highlights

* Enum and multiselect options use `{ value, label? }`, allowing display labels without changing stored values.
* Artifacts can declare a BCP 47 source language through `language`.
* Shared artifact methods expose the artifact `code`.

### Breaking changes

#### Types and schemas

* Replace primitive enum arrays with `EnumOption[]`; multiselect defaults now contain option values rather than option objects.

### Upgrading from 0.1

1. Rewrite enum options as `{ value, label? }` and keep multiselect defaults as the selected primitive values.

### Other changes

#### CLI and schemas

* CLI fill, validation, and template commands understand labeled options.
* Published per-form JSON schemas are regenerated without the stale non-standard `id` property.

## [0.1.1](/changelog/v0.1.1) - 2026-05-08

This patch expands signature blocks and corrects rendering and schema behavior for common field values.

### Highlights

* Signature blocks support `capacity` and `printed_name`, with matching text and PDF helpers.
* PDF rendering handles multiselect arrays in qualified checkbox bindings.
* Address-region schema and rendering behavior are corrected.

### Other changes

#### Packages

* All public packages remain on the same 0.1.1 lockstep version.

## [0.1.0](/changelog/v0.1.0) - 2026-04-28

The first public Paradoc release establishes documents as typed, machine-readable artifacts for applications and AI agents.

### Highlights

* Typed builders define forms, documents, checklists, bundles, parties, fields, annexes, and output layers.
* Core validation checks artifact definitions and filled data against shared Zod and JSON Schema contracts.
* Text, PDF, and DOCX renderers produce multiple outputs from the same artifact definition.
* `@paradoc/sdk` provides the all-in-one framework entry point, with CLI and AI adapter packages alongside it.
* The published packages support Node.js 18 and are released in lockstep under the MIT license.