Changelog

All notable changes to Papermill, the Press document language, and the public API are documented here. The format follows Keep a Changelog, and Press follows Semantic Versioning — minor versions add backwards-compatible features, patch versions are released continuously between cuts.

For breaking changes and migration guidance, see the Notes subsection on the relevant release.

Unreleased

Improvements currently rolling out to staging ahead of the next release.

Added

• Embedded image support for inline and block contexts in the new layout pipeline. Images now flow alongside text and obey the same break, scale, and alignment rules as other block content.
• MCP generate_thumbnails tool returning per-page PNG previews for any saved template. Useful for surfacing template galleries in agent-driven UIs.
• Diverse pattern palettes in the MCP press://patterns library, plus an authoring prompt that nudges agents toward considered colour choices instead of repeating the default theme.

Changed

• MCP template I/O is now routed through the live editor session, so writes from an agent appear in an open editor immediately and templates open in the editor reflect the agent's last write.

---

1.6.0 — 2026-04-24

A consolidation release focused on account security, the Stripe billing integration, and a long list of visualisation refinements that landed during the quarter. This release also begins the rollout of the new image rendering capability behind a feature flag.

Highlights

• Self-serve billing through Stripe Checkout, including automatic page-quota sync over the subscription lifecycle.
• Verified-email gate on /v2/account endpoints, with an in-product banner and verification panel that walks users through resending and confirming.
• Hardened public surface following the April 2026 security review (see Security below).

Added

• Stripe billing integration: Checkout-driven subscriptions, a redesigned subscription panel in account settings, and automatic page-quota updates when a plan changes, is cancelled, or is reactivated.
• API key naming: keys can be given a human-readable label and renamed from the API Keys settings page.
• Email verification flow: register form, password-strength meter aligned to NIST SP 800-63B, forgotten-password confirmation state with resend, and a verify-email banner that gates protected account routes until the address is confirmed.
• absolute attribute on <value> to coerce a numeric value to its absolute magnitude when binding into a document.
• stacked="true" on <x-bar-plot> and <x-line-plot> for stacked-series charts.
• marker-font-size on chart visualisations, with marker-font-size="auto" requesting the default label size.
• marker-flip to invert bar-plot label orientation when bars are short enough that an external label is preferable.
• fill-start and fill-end on <x-line-plot> for fade-gradient fills under series.
• forecast-dash for custom dash patterns on the forecast portion of a line plot.
• break-before="auto" to unset an inherited frame break, restoring default flow behaviour for a single child.
• separator attribute on <value> for thousands-grouping in formatted numbers.
• Template size guard: edits that would take a template over 950 KB are rejected at save time with an actionable message instead of failing later in the pipeline.

Changed

• PDF responses are streamed rather than buffered, removing the 32 MiB response cap that previously affected long reports and large image sets.
• PDF viewer zoom uses proportional wheel scaling and anchors the zoom at the gesture origin, eliminating the "jumping" behaviour that affected trackpad users.
• Image fetching prefetches URLs found inside <data type="json"> blocks for known image elements, reducing first-render latency on data-driven documents.
• /v2/account/usage now returns the current Stripe billing period alongside cumulative usage, so dashboards can render period-accurate charts without a second call.

Fixed

• Manual line-plot markers render at their declared (x, y) coordinates regardless of whether the value matches a series point.
• Grid layout no longer over-commits by a row gap on the trailing row, which previously caused silent drops of the last row in tightly-fitting grids.
• Page skipping: pages whose remaining flow content would produce nothing are skipped cleanly, preventing trailing blank pages on documents with conditional sections.
• Table rotation: nested repeats inside rotated tables now respect page breaks; auto-rotation is suppressed unless the column would actually overflow BREAK_WIDTH; apply-if predicates resolve correctly inside repeated rows.
• CDATA in < preprocessor: the lone-< preprocessor now skips CDATA sections, fixing documents that embed XML samples in code blocks.
• Component expansion preserves the original raw XML through nested expansion, fixing edge cases in templates that re-emit their input.
• Direct deep links on docs.papermill.io now serve clean URLs and resolve to the correct page on first hit.
• PDF viewer: navigating to a different document resets the viewport so the new file opens at the top.

Security

The April 2026 public-surface audit drove a number of hardening changes, all live as of this release:

• SSRF protection: requests to cloud metadata endpoints and private IP ranges are blocked across both the typesetter and the AI image service.
• Preview endpoint restricts which assets it will fetch and validates the structure of <data type="json"> payloads before rendering.
• Stripe webhooks are guarded against client_reference_id hijacking when matching checkout sessions to accounts.
• API key issuance is capped at 50 active keys per user. Existing keys above the cap continue to function; new issuance requires revoking an old key first.
• Unauthenticated /v2/expand endpoint has been removed. Callers should use the authenticated PDF or validate endpoints.
• JWT exp claim is now written in milliseconds to match the verifier used by the realtime sync layer, closing a token-acceptance edge case.
• Staging and preview deploys are marked noindex to prevent accidental indexing of pre-release content.

Notes

• The /v2/expand endpoint removal is a breaking change for the small number of integrations that depended on it. There is no replacement on the unauthenticated surface; switch to an authenticated endpoint with an API key.

---

1.5.0 — 2026-03-26

The MCP release. Papermill's Model Context Protocol server moved from preview to general availability, with a substantially expanded set of resources and tools for agent-driven document authoring. Visualisations also gained forecast and marker support, and the editor picked up syntax highlighting for embedded JSON, CSV, and Markdown.

Highlights

• MCP server (GA) with template management, Press validation, pattern library, and a pro reference resource. See the MCP Server guide.
• Forecast and marker support for line plots, including a series-based data format that carries forecast and marker metadata alongside the points.
• Press syntax highlighting in the editor for embedded JSON, CSV, and Markdown islands.

Added

• MCP press://patterns library with list_patterns and get_pattern tools, exposing curated, ready-to-adapt fragments for common document patterns.
• MCP press://gotchas resource capturing the most common authoring pitfalls with worked examples, with the canonical entries also covered by regression fixtures.
• MCP press://pro resource documenting the advanced reference material available to agents working on production templates.
• MCP design guidelines split into a focused press://design-guidelines resource and an expanded reference resource, making it easier for agents to load only the context they need.
• Semantic-tag dialect in MCP resources, teaching agents the canonical block and inline element names alongside their HTML-adjacent aliases.
• <schema> element for declarative JSON Schema validation of the user-data payload. Schema violations are rejected with a structured error before rendering.
• JSON and CSV content types on the /v2/pdf and /v2/validate endpoints. POSTing application/json or text/csv against a template_id merges the body into the template's default <data>, so payloads only need to carry the fields that change.
• <markdown> tag for embedding a Markdown island inside a Press document, including inline="true" for inline runs that preserve line breaks.
• Text case transformations: text-transform="upper", "lower", and "title" are now supported on inline and block elements.
• apply-if conditional styles with predicate functions, allowing styles to be applied only when a condition holds. Includes V2 support and full integration with the styling context.
• show-if is now supported in the new layout pipeline, matching the V2 behaviour for conditional rendering.
• <repeat> index attribute to expose the current iteration index as a scoped variable for conditional logic and styling.
• Variable-based dynamic indexing in data expressions, e.g. data.items[scope.index].label.
• Auto-assigned slug IDs on Markdown headings, making them addressable by cross-references and the table of contents without explicit id attributes.
• Space overflow diagnostics in error messages, naming the container that ran out of space and the contributing children. Replaces the previous "not enough space" rejection with an actionable message.
• break-before attribute for forcing a page break before a frame.
• gap attribute on <frame> for consistent spacing between children in horizontal and vertical frames.
• scale attribute on <img> for retina-scaled rendering of smaller-than-native images.
• Row-wrap on horizontal <frame> containers, allowing children to wrap onto subsequent rows when they exceed the container width.
• columns attribute on <grid> for declarative auto-layout instead of explicit cell positioning.
• Word hyphenation for improved justified-text layout.
• text-align="justify" is now supported.
• Custom canvas-based PDF viewer replaces the previous embedded viewer. Defaults to fit-page-width on initial load, with smoother zoom and reliable per-document viewport state.
• Mobile editor: a hamburger menu drawer makes the editor navigable on phone-size viewports.

Changed

• Preview endpoint: visualisations are enabled by default, and the templates available to public preview have been hardened against malformed input.
• Editor reconnect: a connection state machine prevents duplicate PDF renders during reconnect and keeps the editor visible during the SYNCING state instead of flashing the loading skeleton.

Fixed

• Page-margin overrides declared on <page> are now respected when the same property is set on <document>.
• Table of contents page-number placeholder (MMMM) is replaced correctly on deferred pages.
• Tables breaking across pages preserve all rows when the table is wide enough to trigger column rebalancing on the second page.
• Table empty-row false-positive on tight page breaks no longer rejects valid tables.
• Column-width FP overshoot (a floating-point rounding artefact) is corrected when columns sum to slightly more than the available width.
• PDF preview now updates reliably on the first Cmd+Enter after opening a document.
• Schema validation is no longer skipped when the JSON payload is sent via template_id.
• <markdown inline="true"> preserves explicit line breaks in the source.
• Style context offset propagates through directives, so odd() and even() predicates apply to the correct logical row when used inside repeats.
• Frame direction attribute resolves scoped data expressions, allowing layout direction to be data-driven.
• JSON formatter no longer inserts blank lines when given invalid JSON.
• Font fallback log deduplicates repeated messages to one entry per family, keeping logs readable.
• Workspace memory pressure is reduced through tighter PDF buffer lifecycle and idle-worker handling. Concurrent-request limits are now configurable per environment.
• Editor flicker and scroll reset on tab switch have been eliminated.

Notes

• The MCP server has been promoted from preview. The pre-1.5 preview endpoints continue to function for the deprecation window but will be removed in 2.0; switch to the documented MCP integration as soon as your agent supports it.

---

1.4.0 — 2026-02-23

A typography and layout-control release. Press picked up font-weight and per-letter spacing controls, frame-level cross-references, and the second iteration of the standard library.

Added

• font-weight is now a first-class style property, with explicit numeric weights and named keywords mapped to the closest available cut.
• letter-spacing and word-spacing style properties for fine-grained typographic control.
• target and id attributes on frames and inlines, enabling internal links and cross-references that resolve to a specific element rather than only to a page.
• Standard library v2: a refreshed set of built-in components and utilities, with a switch to allow templates to opt into either generation while authors migrate. See Standard Library.
• Lining numbers (lnum) are used in PDF output by default, replacing old-style figures (onum) for cleaner numeric tables.
• WebP support for embedded images.
• wrap="none" is supported in the new layout pipeline, matching V2 semantics.
• Pills in <span> for inline pill-style annotations.
• Word-breaking for very long unbroken tokens (URLs, identifiers) instead of overflowing the container.
• SVG documentation added to the image guide. (See Images.)

Fixed

• Component breaks: breaking inside a component no longer duplicates the component's content on the next page.
• Outline entries with unknown sources now provide source-location info in the rejection message instead of an opaque error.
• Generic error grouping: stopped reporting an unhelpful generic error wrapper from the rendering path, so customer-facing rejections carry the underlying diagnostic.
• Table sizing has been corrected for several edge cases involving tight columns and rotated layouts.
• Watermark tests no longer require the local emulator or fonts on disk, unblocking offline development.

Changed

• Font caching now keys on the resolved face and weight, fixing inconsistent caching behaviour when the same family was used at multiple weights.

---

1.3.0 — 2026-01-28

Visualisations land. Press now ships with first-class chart elements (<x-donut>, <x-bar-plot>, <x-line-plot>) integrated into the new layout pipeline. Landscape pages, image and colour assets, and feature flags are also part of this release.

Highlights

• Visualisations: donut, pie, bar, line, and area charts as native Press elements. See Visualisations.
• Landscape pages via the direction attribute on <page>.
• Asset blocks for images, colours, and reusable data — declared once in <assets> and referenced from anywhere in the document.

Added

• <x-line-plot> axis configuration attributes (y-label, x-label, y-prefix, y-suffix, y-dp, y-separator, y-min, y-max).
• <x-donut> data limits via limit and limit-color, allowing partial-fill charts (e.g. progress against a target).
• Total-pages primitive for "Page X of Y" footers and similar.
• name attribute on <data> for multiple named data blocks within a single template.
• Multiple <data> tags are supported in a single document, with merge semantics defined.
• Image and colour assets in <assets>, plus the ability to declare data blocks anywhere in the document.
• Boolean literals in data instructions.
• Border-radius for block and inline images.
• <frame-break> primitive for explicit frame-level breaks.
• Counter format support for outline entry numbering (numeric, alphabetic, roman).
• Feature flag plumbing so new capabilities can be rolled out incrementally to staging and beta accounts.
• Outline entries: <repeat> over the document outline, named-destination cross-references, page-reference rendering of outline entries, and extraction of outline data into expressions.

Fixed

• Table borders are now rendered centred on the cell boundary, eliminating sub-pixel asymmetry between adjacent cells.
• Page references through data variables are resolved correctly.
• Inline images with no declared size are not rendered (rather than being rendered at zero size or causing a layout exception).
• Invalid base64 syntax in image sources is rejected with an actionable message instead of an internal error.
• <frame-break> as the first child of a frame is rejected with a clear message instead of producing ghost pages at the end of the document.
• <repeat> race condition under concurrent renders has been resolved.
• Editor: automatic reconnection now works reliably after transient network drops.
• Anonymous flows are supported, simplifying templates that don't need named flow targets.
• Lone < and > in document content are preprocessed correctly without breaking the surrounding XML.

Notes

• The <flow-info> primitive has been removed; its functionality is covered by the new total-pages primitive and outline expressions. Templates that referenced <flow-info> should switch to the documented replacements.

---

1.2.0 — 2025-12-18

A polish-and-paper-cuts release covering the document outline, error reporting, and a stack of small authoring conveniences. Several long-standing edge cases in <repeat>, frame breaking, and page references were closed.

Added

• Document outline: structured <outline> rendering with cross-references, page-number resolution, and built-in support for table-of-contents authoring. See Table of Contents.
• Frame rotations are supported as a first-class layout primitive.
• Counter values can be popped and re-incremented for advanced numbering schemes.
• Repeating outline entries via <repeat over="outline">.
• Personal access tokens documentation added for API authentication.
• LRU cache for frequently-resolved data references improves render time on data-heavy documents.
• Anchor link alignment with text baselines.
• Headings auto-add to the outline by default; opt out with outline="false".
• Linting for the docs site to catch broken links and orphaned pages in CI.

Fixed

• Span inside a content repeat no longer rejects the document with an unexpected error.
• Multiple style aliases can now be applied to the same element.
• Style aliases via data resolve correctly when the alias name comes from a data expression.
• List items: spacing rules apply correctly; list items no longer disappear under specific nesting patterns.
• Headings trigger appropriate page breaks when they would otherwise be orphaned at the bottom of a page.
• Vertical text centering uses line-height-above and line-height-below symmetry for consistent baseline alignment.
• Counter pop: popped counters now display the correct value rather than the post-pop value at the previous level.
• Empty <span>, bad colour values, and frame wrap edge cases all produce actionable rejection messages instead of generic 500-class errors.
• Editor: fixed an immediate-disconnect failure mode on session resume.
• Underline rendering has been corrected.
• Absolutely-positioned elements no longer obey the parent's padding (matching documented behaviour).
• Absolute images scale to their declared size rather than the source's intrinsic dimensions.
• Arrays in <data> are no longer appended when a payload is merged with the template default — they replace, matching the documented merge semantics.
• Capitalised data keys are preserved through resolution.
• Source tracking is now attached to "cannot iterate over a data leaf" rejections.
• Confusing zero-width-frame rejection message has been replaced with a diagnostic that names the offending frame.

Notes

• Default <data> merge semantics for arrays changed: arrays in the payload now replace the template default rather than appending. Templates that depended on the previous behaviour should declare the appended values explicitly. This was always the documented behaviour; the change brings the implementation in line.

---

1.1.0 — 2025-11-26

The first follow-up to general availability, focused on AI-driven image rendering, frame rotations, and a substantial round of error-message improvements based on early-customer feedback.

Highlights

• AI image saliency: Papermill now crops imported images to their salient region when fitting them into a frame whose aspect ratio differs from the source. See Images.
• Frame rotations and named destinations: rotated content blocks plus cross-reference targets that survive layout reflows.
• Outline-driven cross-references: any element added to the document outline can be linked to by name.

Added

• AI image saliency service integrated into the typesetter for crop-aware image placement.
• Named destinations in PDF output, used by both the table of contents and arbitrary cross-references.
• Outline cross-references: link to outline entries by name, with automatic page-number resolution.
• <repeat> over outline entries for generating tables of contents and figure indexes from the document structure.
• Counter format options (numeric, alphabetic, roman) for outline numbering.
• Frame rotations as a layout primitive, including rotated children with correct bounds.
• Deferred pages for content that needs to be rendered after the rest of the document is laid out (e.g. cover pages with computed page counts).
• min-width is now respected during frame layout.

Fixed

• Vertical text centering uses balanced line-height padding above and below.
• Inconsistent frame placement for rotated content has been corrected.
• Orphan-line threshold activates correctly even when initial compilation fails.
• Empty body requests no longer cause an unexpected error; the rejection message names the missing field.
• Generic error swallowing in the AI API has been removed; underlying diagnostics now surface to the caller.

---

1.0.0 — 2025-11-08

Initial general-availability release of Papermill and the Press document language.

What's in 1.0

• Press document language: an XML-based, print-native language for defining page layouts, typography, content flows, components, and data bindings.
• PDF API: /v2/pdf and /v2/validate endpoints for rendering and validating Press documents.
• Editor: a browser-based editor with live preview, real-time collaboration, and template management.
• Templates and payloads: stored templates rendered against per-call data payloads, with merge semantics defined for data overrides.
• Standard library: built-in components for headings, tables, lists, code blocks, footers, and headers.
• Outline and table of contents support, with automatic page-number resolution.
• Image, font, and asset management with WebP, PNG, JPEG, and SVG support.
• Account and quota management, including API keys and per-user page quotas.

For documentation on each of the above, see the Quickstart and Core concepts.