Migration and versioning

Every template carries schemaVersion. The current version is 1.

import { migrateTemplate, needsMigration } from "@broadpaper/core";

const { template, applied, fromVersion } = migrateTemplate(storedJson);

• Migrations are pure functions from version n to n + 1, applied in order and unit-tested. Shipped migrations are never edited; new ones are appended.
• A template newer than the SDK throws MigrationError rather than rendering something wrong.
• The editor, the preview and the PDF service all migrate on load, so you can pass stored JSON straight through.
• Unknown block types and unknown props are preserved verbatim through a round-trip.

Compatibility promise

Within a major version of BroadPaper:

• fields are only added, never removed or re-typed;
• new block types may appear; existing types keep their props (blocks bump their own version and migrate props if needed);
• theme tokens keep their names; new tokens may be added.

Custom block versions

defineBlock({
  type: "acme.risk-profile",
  version: 2,
  migrate(props, fromVersion) {
    return fromVersion < 2 ? { ...props, scaleMax: props.scale ?? 10 } : props;
  },
  …
});

Storing templates

Persist the JSON as returned by onChange/getTemplate(). It is stable (JSON.stringify round-trips losslessly), deterministic in key order, and typically 20–60 KB for a multi-page report. Store the version you saved with the record; validate with validateTemplate before accepting writes from untrusted clients.

Renamed from ReportKit (breaking)

The product is BroadPaper. Packages moved from @reportkit/* to @broadpaper/*, environment variables from REPORTKIT_* to BROADPAPER_*, and — the one that can break working code — the CSS class prefixes moved from rk- to bp-, and from rke- to bpe-.

Those class names are the documented DOM contract for custom blocks, so a block that renders .rk-stack, or a table as table.rk-table, has to be updated. So does any host stylesheet that themes the editor through .rke or --rke-* custom properties.

- h("div", { class: "rk-stack", "data-dropzone": node.nodeId }, children)
+ h("div", { class: "bp-stack", "data-dropzone": node.nodeId }, children)

- .rke { --rke-accent: #7c5cff; }
+ .bpe { --bpe-accent: #7c5cff; }

Nothing in the document schema changed, so stored templates load unaltered and schemaVersion stays at 1.