OUI_XFAB documentation

Dependency Handbook

Authority and maintenance

This handbook owns the purpose, maintenance owner, declared range, resolved version, compatibility constraints, and audit policy/status for every direct package in package.json.

• package.json is authoritative for direct dependency ranges and supported runtime engines.
• package-lock.json is authoritative for exact direct versions and the complete resolved transitive graph.
• This handbook documents direct packages only. Manually duplicating the transitive graph here is prohibited because it would drift from the lockfile.
• npm run validate:dependencies checks that every direct dependency appears exactly once and that its declared and resolved versions match the package files.

Update the relevant row whenever package.json or package-lock.json changes. The owner column identifies the repository area responsible for compatibility review.

The focused UI libraries and versions inventory compares every current UI runtime, integration, styling, and verification package with npm's latest tag as of 23 August 2026.

Runtime baseline

• Node.js: >=24.15.0 <25, required by the jsdom 30 test runtime while preserving Node 24 LTS.
• npm: version 11 is the validated package-manager generation; the declared minimum remains >=8.0.0.
• Install reproducibly with npm ci.
• Keep @types/node on the Node 24 line while Node 24 LTS is the deployment runtime.

Runtime dependencies

Development dependencies

Transitive dependency inspection

Do not copy the transitive package list into documentation. Inspect the authoritative lockfile graph with:

npm ls --all
npm explain <package>
npm outdated
npm audit
npm audit --omit=dev

Use npm ci to prove that a lockfile change installs reproducibly before committing it.

Upgrade cohorts and compatibility constraints

• Phase 1 has a dedicated compatible dependency checkpoint and provides this machine-validated handbook.
• Phase 2 installed jsdom 30.0.0 and Pinia 4.0.2 as separate, independently verified cohorts.
• Vuetify 4.1.x is the sole UI component library and reuses @mdi/font 7.4.47.
• Eleventy and Wrangler are development-only documentation tooling; they do not enter the browser application bundle. Documentation deploys use the dedicated oui-xfab-docs Cloudflare Pages project.
• PrimeVue, PrimeIcons, and PrimeUIX Themes were removed after the UI migration; they are no longer direct or resolved dependencies of the browser application.
• Keep every interaction surface coherent: component, test, and style ownership move together.
• Node 26 and TypeScript 7 are deferred. TypeScript 6 uses the canonical typescript package so the future TypeScript 7 upgrade remains a direct major-version change.
• Do not use forced overrides or breaking downgrades to make audit output disappear.

Audit status

There are currently no accepted audit exceptions. Both npm audit --omit=dev and the full npm audit must report zero vulnerabilities. Do not use npm audit fix --force; apply compatible lockfile updates deliberately and verify them with npm ci and the repository gates.

Update workflow

1. Change one dependency cohort at a time.
2. Regenerate package-lock.json with the validated Node 24/npm 11 toolchain.
3. Update the affected handbook rows and compatibility notes.
4. Run npm run validate:dependencies.
5. Run focused tests for the affected owner, followed by lint, strict type-check, coverage, production build, and browser verification required by AGENTS.md.
6. Run npm audit --omit=dev and npm audit; never force-fix a breaking downgrade.
7. Commit each verified cohort independently so it can be reverted without disturbing later work.