Public API stability

QForm Builder Community 0.1.20 introduced the candidate freeze of its public API before 1.0.0-rc.1. Versions 0.1.21 through 0.1.30 preserve that exact surface. 0.1.21 adds release-evidence verification, 0.1.22 fixes internal preview-value synchronization, 0.1.23 stabilizes the internal right-drawer transition, 0.1.24 hardens internal selection of interactive canvas fields, 0.1.25 preserves values after submit, 0.1.26 stabilizes the Playwright harness and Windows paths, 0.1.27 adds the Playwright documentation pipeline and internal DOM selectors, and 0.1.28 hardens its fixture, cold-start timeouts and atomic PNG publication. 0.1.29 only changes the Playwright framing of the history timeline. 0.1.30 stabilizes npm packaging and publication without adding a public prop, event, method or type.

The freeze covers the boundaries consumed by a Nuxt host application:

• subpaths declared in package.json#exports;
• FormBuilder props, events and exposed methods;
• FormViewer props, model and submit event;
• types exported by @vevedh/qform-builder-layer/types;
• the @vevedh/qform-builder-layer/contract runtime subpath.

Machine-readable manifest

The canonical file is published in the package:

public-api.manifest.json

It is also exposed through:

import manifest from '@vevedh/qform-builder-layer/contract-manifest'

Depending on the consumer TypeScript configuration, JSON imports may require resolveJsonModule or a JSON import attribute. For runtime use without JSON, use:

import {
  QFORM_BUILDER_PUBLIC_API_CONTRACT_VERSION,
  QFORM_BUILDER_PUBLIC_API_STATUS,
  qFormBuilderPublicApiContract,
} from '@vevedh/qform-builder-layer/contract'

Reusable component contracts

Props and events are no longer defined only inside the SFC. They are exported as public types:

import type {
  FormBuilderEvents,
  FormBuilderProps,
  FormBuilderPublicApi,
  FormViewerEvents,
  FormViewerProps,
} from '@vevedh/qform-builder-layer/types'

FormBuilder.vue directly consumes FormBuilderProps and FormBuilderEvents. FormBuilderPublicApi is compared with the actual defineExpose() methods. The manifest also stores normalized SHA-256 hashes for the five component interfaces and every public source under app/types*. Optionality, type and signature changes are therefore detected even when a member name remains unchanged.

Automated checks

bun run api:contract:check
bun run typecheck:contract

api:contract:check rebuilds the actual surface from source and compares it exactly with the committed manifest. It fails on:

• an unreviewed npm subpath addition or removal;
• a props or events change;
• drift between FormBuilderPublicApi and defineExpose();
• a public-type list or signature change;
• a manifest that does not match the package version.

Public type source hashes are intentionally conservative: any change to a public type file must be reviewed and explicitly accepted, even when the change appears compatible.

typecheck:contract compiles an external consumer that imports public subpaths only. It prevents a declared but unusable export from reaching a release.

Intentional updates

A deliberate evolution follows this process:

bun run api:contract:update
git diff -- public-api.manifest.json
bun run api:contract:check
bun run typecheck:contract

The update command is never invoked by CI or release gates. Its diff must be reviewed explicitly.

SemVer policy

Before 1.0.0, the status is candidate-frozen:

• an internal fix without surface changes remains a patch;
• a compatible public addition requires manifest and consumer-contract review;
• a removal, rename or type incompatibility is prohibited before the RC unless an explicit decision and migration are provided.

Starting with 1.0.0, breaking this surface requires a major version. Persisted formats remain governed separately by document, schema and theme versions.

Release-candidate gate

bun run release:candidate:check

This command chains the complete quality suite, visual baselines, Chromium scenarios and verified npm package creation. GitHub Actions also exposes a final Release candidate gate job that becomes green only after the quality, browser and package jobs have succeeded.