Compatibility and Release Policy
Browser Baseline
Batoi UIF targets the current and previous two stable major releases of Chrome, Edge, Firefox, and Safari, plus iOS Safari 16.4 and later. Distribution JavaScript targets ES2022. Progressive capabilities are feature-detected and must not break the server-rendered baseline when unavailable.
Public Compatibility Surface
Public package exports, documented data-uif-* attributes, lifecycle events, component metadata, configuration rules, design tokens, and browser globals form the v3 compatibility contract.
- Minor releases may add APIs and attributes.
- Patch releases may correct behavior while preserving documented intent.
- Deprecated v2 APIs remain available through the diagnostic compatibility path while applications migrate to strict v3 behavior.
- Incompatible signatures, events, attributes, or markup contracts require a major release.
- Internal modules, generated chunk names, editor-private markers, and undocumented CSS internals are not stable APIs.
Lifecycle Ownership
Stateful components use idempotent mount, update, suspend, resume, and destroy ownership. Initializers own their listeners, observers, timers, subscriptions, requests, and persistent resources. Reinitialization must not stack behavior, and destruction must be idempotent and cancel pending work.
Version 3 Compatibility Mode
Use the compatibility profile to retain v2 behavior while diagnostics identify constructs that strict v3 mode rejects. After resolving the reported issues, enable configureCompatibility({ mode: 'v3' }) and verify the application against the strict contract. See Package Profiles and Migration.
Integrity and Release Budgets
dist/integrity.json records SHA-256, SHA-384 SRI, byte, and gzip values for root distribution artifacts. Fixed-version deployments can use the recorded sri value with an appropriate crossorigin policy.
release-api.json records public export names and hashes of normalized TypeScript declarations. Generated contract and token references provide machine-readable authorities for declarative components, migration rules, accessibility notes, and security acceptance. Release checks reject removed exports and changed public signatures while allowing additions. Package verification also checks publish contents, entry points, declarations, wildcard exports, and an offline clean install of the packed package graph.
The release also publishes deterministic CycloneDX SBOM, provenance, and integrity artifacts. These artifacts document the package graph and build output; they do not replace deployment review or server-side authorization.
Root ESM JavaScript and CSS artifacts must remain below 120,000 gzip bytes. The global IIFE has a 120,100-byte format allowance. Framework packages must have no third-party runtime dependencies.
Release Gate
A UIF release runs linting, unit tests, a full build, release verification, package-install checks, cross-browser application journeys, the security audit, and git diff --check. Manual release review covers assistive technology, keyboard behavior, CSP and Trusted Types, and deployed artifact integrity.
Development requires Node.js 20.19 or later in the Node 20 line, or Node.js 22.12 or later.
For the deployed website snapshot, confirm that package.json reports the intended version and that the distribution files match dist/integrity.json before publishing.