| Reference | Value |
|---|---|
| Subject and boundary | What counts as public, how API reports are generated and enforced, how consumer-visible changes are recorded and how contracts are deprecated. |
| Verified source | tools/api-authority.ts, tools/release-core.ts, DEPRECATION.md, ci.yml at tag v0.40.0. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10; earlier pass checked November 7, 2026. |
| Support state | Report, fragment and compatibility mechanisms in v0.40.0. Config is covered by repository contracts. The public boot asset fingerprint is recorded below. |
The public contract of the eight released packages is their exports and export conditions, TypeScript declarations, Svelte props and bindings, direct CSS and JSON assets, token names and meanings, and valid runtime behavior. Gallery code, test helpers and repository build internals are not public unless a document says so.
flowchart LR
M["package.json exports"] --> E["Declaration emit: TypeScript + svelte2tsx"]
E --> X["API Extractor per export target"]
M --> A["Direct CSS/JSON assets + sha256"]
X --> R["api-reports/pkg.api.md"]
A --> R
R --> C["api:check: fail on drift"]
R --> P["api:approve --base SHA: changed report needs a new fragment"]
| Command | Behavior |
|---|---|
bun run api:report |
Regenerates the seven reports in a temporary workspace and writes them. Read the diff before committing. |
bun run api:check |
Regenerates in memory and fails if any committed report differs. Part of bun run check, and run separately on Windows in CI. |
bun run api:approve -- --base <40-char SHA> |
CI runs it on every pull request and merge group with that event's base commit. Each package whose report differs from the base must be named by a .changes fragment that did not exist at the base. A base with no reports is the first baseline and passes. |
Reports cover tokens, motion, gates, seo-kit, ui, analytics and i18n-core. @yesid/config has no report; repository contract tests cover its shared configs. Report generation rejects exports marked @internal or named like test or internal symbols. Direct assets are listed with their export conditions and a content hash, so a change to a public stylesheet changes the report.
The public UI surface includes Card root, component prop and variant types, sectionGlow and footer types. Sheet Content requires caller-owned close copy unless the close button is explicitly disabled. Each package's API report defines its exports and types. Compatibility requirements and migration guidance are documented in DEPRECATION.md, connect-prune and module fixes.
At tag v0.40.0, @yesid/ui/boot.json is a direct public asset with SHA-256 fingerprint 168b9a3e53dc73f0caa95b158fbc77b126b23b11c0c19272c0ac3881742a0030. Its hash field is the CSP script source sha256-T9RENAm4pC90ybStT4bxIcqVoQRsaBAsbPFNg8179bw=. The fingerprint describes JSON bytes; the CSP source describes the injected script body. The boot contract applies theme and remembered-section geometry before paint, opening content when no valid choice is stored, with readable startup recovery. Sources: UI API report and boot.json. Consumer requirements are in remembered-sections.md.
---
"@yesid/ui": patch
"@yesid/tokens": minor
---
What changed for consumers, and how to migrate.
| Rule | Detail |
|---|---|
| Path | .changes/<kebab-slug>.md; the slug becomes the changelog marker release-fragment: <slug>. |
| Packages | Any of the eight lockstep packages, @yesid/config included. |
| Bump | patch fixes; minor adds functionality or carries an owner-approved compatibility transition under DEPRECATION.md; major breaks a contract. The API report diff decides when in doubt. |
| Lifetime | Fragments stay pending through source review and merge. Release preparation folds them into CHANGELOG.md, deletes them and refuses a fragment id already consumed. |
| Target version | Preparation requires the target to equal the highest requested bump from the current version, except that a prerelease may advance to a later prerelease of the same core, such as 0.36.0-rc.1 to 0.36.0-rc.2. A release with no fragments is allowed only as a same-core prerelease promotion. |
| Stage | Rule |
|---|---|
| Experimental | Labelled in docs and release notes. Incompatible changes wait for a minor with migration notes. |
| Stable | Default for every unlabelled contract. Compatible additions ship freely; incompatible changes go through Deprecated. |
| Deprecated | Functional and documented. Ending support for a deprecated contract requires at least 90 days from the first deprecation and one intervening minor after the deprecating minor. The release documentation names the affected surface, supported alternative and eligibility date. |
| Patch releases | Never intentionally break a documented contract. A defect fix may correct wrong output when the fragment names the contract and the regression proof. |
Compatibility evidence belongs in the change pull request: deprecation release and dates, intervening minor, migration documentation, report diff and consumer verification. DEPRECATION.md records lifecycle policy and scoped owner decisions.
Direct imports of @yesid/config/tsconfig/base.json and @yesid/config/turbo/base.json are deprecated contracts. Extend tsconfig/library.json or tsconfig/svelte-kit.json, and keep a product-owned turbo.json. They are eligible for removal from v0.31.0 and not before 90 days after v0.29.0 was published (January 27, 2027). The CHANGELOG 0.29.0 entry records the deprecation; DEPRECATION.md owns the policy.