@atomazing-org/design-system 2.0.1 → 3.7.2

package/migrations/docs/migrations/design-system/shared/phases.md

@@ -0,0 +1,377 @@
+# Shared Migration Phases
+
+Use this document as the canonical step-by-step execution checklist for future
+consumer app migrations to `@atomazing-org/design-system`.
+
+Read this after route selection and before editing the target app.
+Then combine it with:
+
+- the selected route runbook
+- the selected route `migration.spec.json`
+- `shared/common-regressions.md`
+- `shared/phase-exit-criteria.md`
+- `shared/manual-qa-matrix.md`
+- `shared/gates.md`
+- `shared/acceptance.md`
+
+## How To Use This Playbook
+
+1. Detect the route first:
+   - `greenfield`
+   - `adopt-existing`
+   - `mui4-to-latest`
+2. Build the migration plan from the phases below.
+3. Keep the app runnable at the end of each phase.
+4. Run the relevant checks before moving to the next phase.
+5. Do not merge unrelated change classes into one unvalidated batch.
+
+## Phase Map
+
+1. Route selection and scope
+2. Baseline and safety net
+3. Dependency landing
+4. Mechanical migration or provider landing
+5. Runtime startup cleanup
+6. Shared infrastructure stabilization
+7. Token, typography, and primitive cleanup
+8. Domain migration waves
+9. Final gates and closeout
+
+## Phase 1: Route Selection And Scope
+
+Goal:
+Select the correct route and define the migration boundary before code changes.
+
+Do:
+
+- inspect `package.json`, imports, theme entrypoints, and current design-system usage
+- choose the route:
+  - `mui4-to-latest` if `@material-ui/*` is present
+  - `greenfield` if the app is new and has no legacy theme or token layer
+  - `adopt-existing` otherwise
+- identify:
+  - app root and provider wiring
+  - theme state source of truth
+  - shared shell and layout containers
+  - shared overlays
+  - protected routes
+  - token modules and hardcoded visual drift
+  - repo-local gates such as style, design, or typography contract scripts
+
+Output:
+
+- selected route and why
+- initial migration scope
+- list of required validation commands
+
+Stop gate:
+
+- the route is explicit
+- the app areas at highest regression risk are named
+
+Route notes:
+
+- `greenfield`: scope is usually limited to provider wiring, app theme module, and startup safety
+- `adopt-existing`: include provider, tokens, shared shell, shared overlays, and consumer primitives
+- `mui4-to-latest`: also inventory legacy styling APIs, MUI v4 imports, and codemod impact zones
+
+## Phase 2: Baseline And Safety Net
+
+Goal:
+Capture the repo state before migration and make regressions visible early.
+
+Do:
+
+- run the repo's normal commands:
+  - `npm run lint` when present
+  - `npm test` when present
+  - `npm run build`
+- run repo-local contract gates when present:
+  - `npm run lint:style-contract`
+  - `npm run lint:design-contract`
+  - `npm run lint:typography-contract`
+- record pre-existing red checks separately from migration defects
+- add or tighten smoke coverage before broad rewrites when the app has:
+  - a shared shell
+  - protected routes
+  - shared overlays
+  - dashboards, analytics, or dense workflow screens
+
+Output:
+
+- baseline check matrix
+- known pre-existing failures
+- smoke coverage plan
+
+Stop gate:
+
+- you can tell whether a later failure is new or pre-existing
+- shell-critical or overlay-critical changes are covered by at least one route check
+
+Route notes:
+
+- `greenfield`: a simple startup check may be enough
+- `adopt-existing`: shell and at least one real content route should be covered
+- `mui4-to-latest`: add smoke coverage before codemod fallout reaches shared UI
+
+## Phase 3: Dependency Landing
+
+Goal:
+Land the dependency set needed for the target route without mixing in broad UI cleanup.
+
+Do:
+
+- update `package.json` directly
+- add or align:
+  - `@atomazing-org/design-system`
+  - `@mui/material`
+  - `@mui/icons-material` when needed
+  - `@emotion/react`
+  - `@emotion/styled`
+- remove route-incompatible packages such as `@material-ui/*`
+- install dependencies with the repo's package manager
+- if install scripts fail because of local tooling, retry with the package manager's `--ignore-scripts` equivalent only as recovery
+
+Output:
+
+- dependency set aligned with the chosen route
+- install completed
+
+Stop gate:
+
+- the repo installs successfully
+- dependency conflicts do not block the next phase
+
+Route notes:
+
+- `greenfield`: this is usually the main dependency phase
+- `adopt-existing`: keep adjacent runtime alignment small and controlled
+- `mui4-to-latest`: remove legacy Material-UI packages before broad theme unification
+
+## Phase 4: Mechanical Migration Or Provider Landing
+
+Goal:
+Reach the route-specific structural landing point before visual cleanup.
+
+Do:
+
+- `greenfield`:
+  - connect `ThemeProviderWrapper` at the app root
+  - create one explicit app theme module for preset choice when needed
+  - add theme controls only through `useThemeSettings()`
+- `adopt-existing`:
+  - connect or normalize `ThemeProviderWrapper`
+  - remove competing root theme providers
+  - replace outdated design-system imports with public APIs or local app abstractions
+  - move preset selection into one app-owned theme module
+- `mui4-to-latest`:
+  - run the official MUI codemod
+  - resolve compile breaks from the codemod
+  - replace JSS-only APIs and legacy theme APIs
+  - get the app stable on modern MUI plus Emotion before provider unification
+
+Output:
+
+- route-specific mechanical landing completed
+
+Stop gate:
+
+- the app compiles after the structural change
+- there is one clear theme-root direction
+
+## Phase 5: Runtime Startup Cleanup
+
+Goal:
+Prove the app actually boots in a browser and remove startup defects before deeper cleanup.
+
+Do:
+
+- start the app with the normal dev or start command
+- open the first route in a real browser
+- fix:
+  - browser console startup errors
+  - migration-caused startup warnings
+  - duplicate runtime singleton loading for `react`, `react-dom`, `@emotion/react`, `@emotion/styled`
+- remove module-scope code that depends on:
+  - `window`
+  - `document`
+  - `navigator`
+  - storage
+  - i18n locale activation
+- move browser listeners into effects with cleanup
+- if smoke mode bypasses auth, seed a deterministic role-bearing user for protected routes
+
+Output:
+
+- startup-clean browser boot
+
+Stop gate:
+
+- first route loads successfully
+- migration-caused startup errors are gone
+
+## Phase 6: Shared Infrastructure Stabilization
+
+Goal:
+Stabilize the app shell and shared UI contracts before domain-by-domain feature work.
+
+Do:
+
+- preserve shell layout behavior:
+  - display mode
+  - grid or flex template
+  - `min-width`
+  - `min-height`
+  - `overflow`
+  - scroll behavior
+- keep route roots and page containers filling the intended workspace
+- if shared padded containers also fill width, normalize with `box-sizing: border-box` or remove forced width
+- restore overlay semantics:
+  - stable `aria-labelledby`
+  - stable `aria-describedby`
+  - labeled close actions
+  - `combobox` and `listbox` semantics for searchable overlays
+- audit shared charts, legends, chips, metric badges, and segmented filters for preset drift
+- remove placeholder regressions and low-fidelity pass-through wrappers
+- if analytics dashboards or metric cards are touched:
+  - keep labels and values on different hierarchy levels
+  - keep one explicit grid gap contract
+  - remove accidental full-width spans that break desktop rows
+
+Output:
+
+- stable shared shell
+- stable shared overlays
+- stable shared dashboard or compact-control contracts
+
+Stop gate:
+
+- desktop and mobile shell behavior matches the intended layout
+- shared UI is usable and semantically wired
+
+## Phase 7: Token, Typography, And Primitive Cleanup
+
+Goal:
+Move the consumer toward the design-system contract instead of preserving legacy local drift.
+
+Do:
+
+- replace legacy tokens with `theme.palette`, `theme.typography`, and helpers such as `alpha()`
+- normalize visible text:
+  - `Typography`
+  - explicit semantic `variant`
+  - `Typography component="span"` for visible text inside interactive controls
+- remove zero-value wrappers:
+  - primitive wrappers
+  - surface wrappers
+- simplify decorative consumer chrome that fights the preset:
+  - gradients
+  - direct shadow styling
+  - palette alpha suffix hacks
+- if the repo needs guardrails, add or tighten:
+  - design-contract lint
+  - typography-contract lint
+- if localized copy was touched, scan for mojibake or replacement characters and verify a real localized route
+
+Output:
+
+- token and text layer aligned with the design-system contract
+
+Stop gate:
+
+- typography and design drift are reduced, not just moved around
+- the repo has enough local gates to keep the fix from regressing
+
+## Phase 8: Domain Migration Waves
+
+Goal:
+Migrate feature areas in controlled batches after shared infrastructure is stable.
+
+Do:
+
+- move feature areas one wave at a time
+- keep each wave small enough to validate independently
+- after each wave, re-run the relevant checks:
+  - smoke
+  - lint
+  - route checks
+  - build when the wave changes bundling or shared runtime behavior
+- stop if a wave reintroduces shell, overlay, typography, or token regressions
+
+Output:
+
+- migrated domains with isolated validation history
+
+Stop gate:
+
+- each wave ends in a runnable, validated state
+
+## Phase 9: Final Gates And Closeout
+
+Goal:
+Close the migration only after runtime, route, and contract checks are all green.
+
+Do:
+
+- re-run:
+  - `npm run lint`
+  - `npm test`
+  - `npm run build`
+  - `npm run test:smoke` when present
+  - repo-local contract gates when present
+- verify route-specific exit conditions:
+  - no `@material-ui/*` left for `mui4-to-latest`
+  - provider wiring and preset ownership are correct
+  - no migration-caused startup warnings remain
+- record any remaining upstream-only warnings precisely by package and file
+- write the migration summary:
+  - route used
+  - commands run
+  - startup issues fixed
+  - remaining manual QA
+  - rollback guidance if partial
+
+Output:
+
+- migration report suitable for future reuse
+
+Stop gate:
+
+- shared acceptance is satisfied
+- the app is browser-runnable, not only build-green
+
+## Recommended Phase Splits By Route
+
+`greenfield`:
+
+1. Route selection and baseline
+2. Dependency landing
+3. Provider landing
+4. Runtime startup cleanup
+5. Final gates
+
+`adopt-existing`:
+
+1. Route selection and baseline
+2. Safety net
+3. Dependency landing
+4. Provider and theme unification
+5. Runtime cleanup
+6. Shared infrastructure stabilization
+7. Token and typography cleanup
+8. Domain waves
+9. Final gates
+
+`mui4-to-latest`:
+
+1. Route selection and baseline
+2. Safety net
+3. Dependency landing
+4. Mechanical MUI migration
+5. Legacy styling cleanup
+6. Provider and theme unification
+7. Runtime cleanup
+8. Shared infrastructure stabilization
+9. Token and typography cleanup
+10. Domain waves
+11. Final gates

package/migrations/skills/design-system-consumer-agent/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: design-system-consumer-agent
+description: Rules for integrating and maintaining @atomazing-org/design-system in application repos. Use when an AI agent needs to add the library, wire it into an app, or decide whether the request should become a route-based migration.
+---
+
+# Design System Consumer Agent
+
+Use this skill whenever the task is about adopting, integrating, or maintaining
+`@atomazing-org/design-system` in an application repository.
+
+## Source Of Truth
+
+1. Read `../../docs/migrations/design-system/shared/WORKING-RULES.md`.
+2. Use `../../docs/migrations/design-system/README.md` for route selection context.
+3. If migration is needed, switch to `../design-system-migration-agent/SKILL.md`.
+
+## Default Workflow
+
+1. Inspect the target app:
+   - current dependencies
+   - current theme provider setup
+   - theme or token modules
+   - SSR or Next.js usage
+2. Apply the working rules from `WORKING-RULES.md`.
+3. Decide whether the task is:
+   - a normal integration task
+   - or a route-based migration
+
+## Escalate To Migration
+
+Escalate to the migration workflow if any of these are true:
+
+- `@material-ui/*` exists
+- the app already has a substantial theme/token system
+- the request would leave dual theme providers or dual sources of truth
+- the user asks to standardize or replace the design foundation
+- changes affect a large set of colors, typography, or component overrides
+
+When escalation is needed:
+
+1. State that route-based migration is recommended.
+2. Select the route:
+   - `mui4-to-latest`
+   - `greenfield`
+   - `adopt-existing`
+3. Load `../design-system-migration-agent/SKILL.md`.
+4. For large repos, execute the selected route phase by phase instead of batching broad edits into one pass.
+
+## Normal Integration Expectations
+
+When migration is not needed:
+
+- use public imports only
+- prefer `ThemeProviderWrapper`
+- prefer `useThemeSettings()`
+- use `defaultThemes`, `landingPageThemes`, or `allBuiltInThemes` intentionally
+- keep preset choice in one explicit app-owned theme module instead of generic constants passthrough files
+- let the active preset own the visual treatment of `Paper`, `Card`, `Dialog`, `Drawer`, and similar surfaces across the app
+- do not hand-style consumer surfaces with app-local glow, bloom, blur, decorative borders, gradient washes, or pseudo-element chrome; those belong in presets/theme overrides
+- keep app styling focused on layout, spacing, sizing, and content hierarchy
+- if the app shell exposes a dedicated workspace or content pane, keep route roots and page containers stretched to fill it instead of shrinking to intrinsic content width
+- for landing and marketing surfaces, prefer MUI-native preview composition over custom decorative UI logic
+- do not hand-style landing surfaces with app-local glow, bloom, blur, decorative borders, gradient washes, or pseudo-element chrome; those belong in presets/theme overrides
+- do not build nested rectangular surface hierarchies such as `card inside card inside card`
+- keep one primary surface per logical block and use `Stack`, `List`, `Divider`, `Typography`, `Chip`, and `Avatar` before introducing another bordered layer
+- keep landing preview blocks spacious and reduce content before compressing spacing
+- remove zero-value wrappers that only rename MUI primitives or surfaces
+- do not leave large inline `sx` objects in JSX; if a component needs substantial styling, extract a local `styled(...)` component in the same file and keep those styled declarations near the bottom
+- if multiple role pages share the same shell, extract a shared workflow layout before changing visuals independently
+- if a local barrel creates chunk-cycle warnings, prefer direct local imports for the affected workflow internals
+- fix consumer-owned build warnings such as stale PWA asset globs or oversized local chunks instead of silencing them
+- if a remaining warning belongs to an upstream toolchain package, record it precisely as external debt
+- keep visible text on `Typography` with explicit semantic variants instead of raw JSX text nodes
+- when buttons, chips, alerts, menu items, or toggle buttons show text, wrap that label in `Typography component="span"`
+- keep compact legends, chips, segmented filters, and metric badges visually aligned with the active preset instead of restyling them into ad hoc chip-like chrome
+- when shared dialogs, drawers, or bottom sheets are touched, keep stable `aria-labelledby` and `aria-describedby` wiring plus labeled close actions
+- when an overlay owns filtered keyboard navigation, use `combobox` and `listbox` semantics instead of generic wrapper markup
+- keep browser event listeners such as `beforeinstallprompt` or `matchMedia` subscriptions inside effects with cleanup
+- remove zero-value surface wrappers that only forward to MUI `Card` or `Paper`
+- use `alpha()` or equivalent theme helpers instead of palette-string alpha suffix hacks
+- treat decorative gradients and shadow styling as migration defects unless the component is an explicit preview exception documented in the repo-local design-contract gate
+- keep browser-only APIs out of module scope
+- after dependency or provider wiring changes, start the app and verify the first route boots without browser console startup errors
+- if bulk rewrites or localized copy changes were part of the work, keep files in UTF-8, scan for mojibake or replacement characters, and verify readable text on a real route

package/migrations/skills/design-system-migration-agent/SKILL.md

@@ -9,20 +9,32 @@ Use this skill to run a design-system migration as an AI-guided workflow.
 
 Treat `migrations/docs/migrations/design-system/` as the source of truth.
 Treat `migrations/scripts/` as optional legacy automation/reference, not a requirement.
+Read `../../docs/migrations/design-system/shared/WORKING-RULES.md` before selecting the route.
 
 ## Quick start
 
 1. Read `../../docs/migrations/design-system/README.md`.
-2. Detect the route from the target app (`package.json`, imports, current theme setup).
-3. Read only the selected route files:
+2. Read `../../docs/migrations/design-system/shared/WORKING-RULES.md`.
+3. Read `../../docs/migrations/design-system/shared/phases.md`.
+4. Detect the route from the target app (`package.json`, imports, current theme setup).
+5. Read only the selected route files:
    - `../../docs/migrations/design-system/routes/<route>/RUNBOOK.md`
    - `../../docs/migrations/design-system/routes/<route>/migration.spec.json`
-4. Read shared checks:
+6. Read shared checks:
    - `../../docs/migrations/design-system/shared/FOUNDATION.md`
+   - `../../docs/migrations/design-system/shared/WORKING-RULES.md`
+   - `../../docs/migrations/design-system/shared/phases.md`
+   - `../../docs/migrations/design-system/shared/phase-exit-criteria.md`
+   - `../../docs/migrations/design-system/shared/common-regressions.md`
+   - `../../docs/migrations/design-system/shared/manual-qa-matrix.md`
    - `../../docs/migrations/design-system/shared/gates.md`
    - `../../docs/migrations/design-system/shared/acceptance.md`
    - `../../docs/migrations/design-system/shared/rollback.md` (before risky edits)
-5. Execute the migration in small commits, validating after each major step.
+7. Execute the migration in small commits, validating after each major step.
+8. For large repos, keep the migration phase-gated:
+   - keep the app runnable at the end of each phase
+   - keep one main change class per phase
+   - stabilize shared infrastructure before domain-by-domain waves
 
 ## Select route
 
@@ -35,22 +47,36 @@ Inspect the target app repository:
 - Else:
   - use `adopt-existing`
 
+Use migration instead of ad hoc integration if the request would otherwise leave
+multiple theme providers, multiple theme state stores, or a large unresolved token layer.
+
 If detection is ambiguous, stop and ask the user which route to prefer.
 
 ## Execute workflow (AI-driven, no local migration scripts required)
 
-1. Create a short plan and name the selected route.
+1. Create a phased plan and name the selected route.
+   - use `shared/phases.md` as the default step-by-step scaffold for the plan
+   - For large repos, define explicit stop-gates between dependency landing, mechanical migration, root theme unification, runtime cleanup, shared infrastructure, domain waves, and final closeout.
 2. Run baseline checks (`npm test`, `npm run build`, and `npm run lint` when available).
-3. Parse `migration.spec.json` and convert each step into concrete actions:
+   - If the repo exposes contract gates such as `npm run lint:style-contract`,
+     `npm run lint:design-contract`, or `npm run lint:typography-contract`,
+     include them in the baseline and closeout pass.
+   - If the repo exposes smoke or e2e coverage for shell, protected routes, or
+     overlays such as `npm run test:smoke`, include that in the migration gate.
+3. Run the repo's normal dev/start command and verify the app reaches the first route in a real browser before and after migration work.
+4. Parse `migration.spec.json` and convert each step into concrete actions:
    - execute `run` commands when they are generic and safe;
    - if a `run` command references `migrations/scripts/*`, perform the intent manually:
      - dependency updates: edit `package.json` directly;
      - route detection: inspect `package.json` and imports directly;
      - token replacements: use CSV mapping + targeted search/replace + manual review;
      - gates: use `rg` searches and test/build commands.
-4. Execute `manualReview` items as explicit subtasks and record what was changed.
-5. Re-run route gates and shared acceptance checks.
-6. Summarize:
+5. Execute `manualReview` items as explicit subtasks and record what was changed.
+   - Do not batch dependency upgrades, shell rewrites, and broad token cleanup into one unvalidated change set.
+   - If shell, overlays, or shared primitives are in scope, add or tighten smoke coverage before broad refactors.
+6. If install scripts fail because of repo tooling such as Husky, retry with the package manager's `--ignore-scripts` equivalent only as a recovery path, then continue with the intended validation commands.
+7. Re-run route gates and shared acceptance checks, including runtime startup verification in a real browser.
+8. Summarize:
    - selected route;
    - files changed;
    - remaining manual follow-up (visual QA, edge screens, regressions).
@@ -75,6 +101,45 @@ Use these substitutions when specs mention local `.mjs` helpers:
 
 Prefer `rg` for all searches.
 
+## Runtime Startup Gate
+
+Do not close a migration on the basis of build success alone.
+
+- Start the app with the repo's normal dev/start command.
+- Open the first route in a real browser.
+- Fix startup console errors before closeout.
+- Fix migration-caused startup warnings before closeout when they indicate broken runtime alignment.
+- If `react`, `react-dom`, `@emotion/react`, or `@emotion/styled` are loaded more than once, align bundler/runtime configuration with dedupe, aliasing, or singleton-sharing.
+- Remove module-scope code that depends on browser APIs, storage, or i18n locale activation.
+- Verify that the active preset still owns the application background after migration.
+- If root shells, layouts, or page wrappers set page-level `background` or `backgroundColor`, remove those overrides unless they are intentional component surfaces.
+- If shell workspaces or route-level content panes were touched, verify the main page root still fills the available content region instead of collapsing to content width or leaving empty workspace.
+- If shared charts, legends, chips, segmented filters, or compact status controls were touched, verify they still read as preset-aligned UI instead of ad hoc chip-like chrome.
+- Keep preset selection explicit in one app-owned theme module instead of generic constants passthrough files.
+- If several role-based pages share the same structural shell, extract a shared workflow layout contract before continuing with visual cleanup.
+- If a local barrel re-export introduces circular chunk warnings, switch the affected app internals to direct local imports.
+- Fix consumer-owned build warnings such as stale asset globs or oversized local chunks with config and bundling changes.
+- If a remaining build warning is emitted by an upstream toolchain package, record the exact package and file rather than pretending the app owns it.
+- Audit visible text when UI components are touched:
+  - use `Typography` with explicit `variant`
+  - wrap visible text in `Button`, `ToggleButton`, `MenuItem`, `Chip`, and `Alert` with `Typography component="span"`
+  - if typography regressions are broad, add or update a repo-local typography contract check and keep it green
+- If raw token drift is broad, add or update a repo-local design-contract check for hardcoded colors, raw numeric font sizes, or ad hoc radius/opacity values and keep it green
+- Expand the design-contract check when needed so it also catches decorative gradients, direct shadow styling, theme shadow-token drift, palette alpha suffix hacks, and unapproved visual-preview exceptions
+- If the consumer repo already enforces a style-contract or styleless-UI rule, keep that gate green during the migration instead of treating it as unrelated local debt
+- If a migrated consumer component still carries a large inline `sx` object, extract that styling into a local `styled(...)` component in the same file and keep the styled declarations near the bottom of the file
+- If bulk replacements, codemods, or encoding-sensitive file rewrites touched localized copy, scan for mojibake or replacement characters and verify at least one real localized route renders readable text
+- Remove zero-value surface wrappers that only forward to MUI `Card` or `Paper`
+- Replace palette-string alpha hacks with theme helpers such as `alpha()`
+- Treat consumer-owned gradient or shadow chrome on normal surfaces as a migration defect unless it is an explicitly documented preview exception
+- When shared overlays are touched:
+  - keep `aria-labelledby` and `aria-describedby` wired through stable ids
+  - label close actions explicitly
+  - hide decorative bottom-sheet chrome from assistive tech when it carries no state
+  - use `combobox` and `listbox` semantics for overlay search UIs with keyboard filtering
+- Keep browser event listeners such as `beforeinstallprompt` or `matchMedia` subscriptions inside effects with cleanup instead of render paths or module scope
+- Prefer smoke checks through stable overlay entrypoints if overlay infrastructure changes during migration
+
 ## Required outputs
 
 Produce all of the following in the final response/work log:
@@ -82,6 +147,7 @@ Produce all of the following in the final response/work log:
 - selected route and why
 - completed steps vs skipped steps
 - exact commands run
+- startup issues found and how they were fixed
 - unresolved warnings / manual QA checklist
 - rollback guidance if migration is partial
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomazing-org/design-system",
-  "version": "2.0.1",
+  "version": "3.7.2",
   "private": false,
   "type": "module",
   "packageManager": "pnpm@9.14.4",
@@ -18,20 +18,24 @@
     "styles",
     "utils"
   ],
+  "main": "./dist/index.js",
   "module": "dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./presets": {
       "types": "./dist/presets/index.d.ts",
-      "import": "./dist/presets/index.js"
+      "import": "./dist/presets/index.js",
+      "default": "./dist/presets/index.js"
     }
   },
   "files": [
     "dist",
+    "AGENTS.md",
     "README.MD",
     "migrations/README.UPDATE.md",
     "migrations/docs",
@@ -43,13 +47,18 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node tools/fix-dts-runtime-stubs.mjs",
+    "changeset": "changeset",
     "dev": "tsup --watch",
     "test": "vitest run",
     "check:runtime-alignment": "node tools/checks/runtime-version-alignment.mjs",
+    "check:migration-readiness": "node tools/checks/migration-readiness.mjs",
+    "release": "changeset publish",
+    "release:verify": "pnpm lint && pnpm test && pnpm build && pnpm run smoke:esm && pnpm run smoke:react-app && pnpm run smoke:next && pnpm run check:migration-readiness",
     "smoke:esm": "node tools/smoke/esm-imports.mjs",
     "smoke:react-app": "pnpm --dir examples/react-app run lint:ts && pnpm --dir examples/react-app run build",
     "smoke:next": "pnpm --dir examples/next-app-router run lint && pnpm run check:runtime-alignment && pnpm --dir examples/next-app-router run build",
+    "version-packages": "changeset version",
     "format": "pnpm run format:eslint && pnpm run format:prettier",
     "format:eslint": "pnpm run lint:eslint -- --fix",
     "format:prettier": "prettier \"**/*.{json,js,ts,tsx}\" --write",
@@ -73,6 +82,7 @@
   },
   "devDependencies": {
     "@atomazing-org/eslint-config": "3.6.0",
+    "@changesets/cli": "^2.30.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.1",
     "@mui/icons-material": "7.3.8",