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, selective profile entry points, and browser globals form the maintained compatibility surface. UIF 4 retains the 3.1-compatible facade.
- 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.
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.
The full browser artifacts remain subject to the release budgets. Selective UIF 4 Essential consumers are limited to 24,000 gzip bytes of JavaScript, 10,000 gzip bytes of CSS, and 34,000 combined; the shipped Essential graph is smaller. 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.
UIF 4 Release Scope
UIF 4.0.0 is stable for its implemented scope: selective component imports, cooperative application ownership, Essential/Web/RAD/Mobile/Desktop profiles and CSS, lifecycle and overlay fixes, scoped governed RAD/form/table integration, icon subsets, and measured consumer budgets. The existing compatibility facade remains available.
The local theme compiler, CLI, MCP, and studio are experimental. Hosted OAuth and assistant connectors, asset materialization, native OS applications, and broader contract consolidation remain outside the implemented release scope.
Manual screen-reader, touch, and device testing; real hosted-assistant workflows; and RADX route, migration, and rollback pilots remain deferred. The release does not imply WCAG conformance, field-performance validation, hosted interoperability, or completion of every enhancement-plan item. Provenance metadata is currently unsigned.