@exxatdesignux/ui 0.5.10 → 0.5.12

package/template/docs/migrations/0003-globals-css-canonical.md

@@ -1,110 +0,0 @@
-# 0003 — `packages/ui/src/globals.css` is now the only CSS source of truth
-
-**Status:** Landed
-**Date:** 2026-05-19
-**Author:** Exxat DS hardening sweep
-**Breaking?** Yes for any external consumer of `@exxatdesignux/ui` that
-imported `@exxatdesignux/ui/theme.css` directly. The package is **not yet
-shipped**, so customer impact is zero. Internal consumers updated as part
-of this PR.
-
-## Why
-
-Until now, the design system kept the same theme tokens duplicated across
-**four** CSS files:
-
-| File | Purpose | Status |
-|---|---|---|
-| `packages/ui/src/theme.css`     | "thin" package CSS without Tailwind imports | dead — never `@import`-ed by code |
-| `packages/ui/src/globals.css`   | "full" package CSS (Tailwind imports + tokens) | drifted (older `--input` value, missing `--header-height`) |
-| `apps/web/app/globals.css`      | consumer of the package | up-to-date copy |
-| `packages/ui/template/app/globals.css` | starter template (auto-synced from apps/web) | up-to-date copy |
-
-Each token change required up to **three** manual mirror edits, and the
-files had **already silently drifted**: `--input` value differed between
-the package and apps/web (one was `oklch(0.62 0.01 264.52)`, the other
-`oklch(0.6694 0.0063 264.52)`).
-
-This is exactly the maintenance trap SLDS deliberately avoids by having
-one source file. Now that the package is not yet shipped, the breaking
-change is free.
-
-## What changed
-
-1. **`packages/ui/src/globals.css` is now canonical.** It carries
-   `@import "tailwindcss"`, `@import "tw-animate-css"`, the
-   `@custom-variant` declarations, the full `@theme inline` block (L2),
-   every `:root` / `.dark` / `.theme-*` / `[data-contrast="high"]` block
-   (L0 + L1 + L3), the `@layer base` rules, and the `@font-face`
-   declarations. No `@source` directive — that lives in the consumer.
-
-2. **`apps/web/app/globals.css` is now a 20-line shell.** It does:
-   ```css
-   @import "@exxatdesignux/ui/globals.css";
-   @source "../../../packages/ui/src";
-   ```
-   Nothing else. All previous content moved into the package.
-
-3. **`packages/ui/template/app/globals.css` is the same shell** with the
-   `@source` path patched to `../node_modules/@exxatdesignux/ui/src` (the
-   `sync-template-from-web.mjs` script already does this rewrite).
-
-4. **`packages/ui/src/theme.css` is deleted.** It was a stale, smaller
-   copy of `globals.css` that no code `@import`-ed (only docs referenced
-   it). The `./theme.css` entry was removed from `package.json` exports.
-
-5. **`packages/ui/scripts/build-tokens-index.mjs` now parses
-   `globals.css` only** (instead of theme.css + globals.css). Token
-   count went from 163 → **195** because the canonical file now captures
-   tokens that previously lived only in `apps/web/app/globals.css`
-   (`--header-height`, `--theme-color-chrome`, scoped overlays, etc.).
-   Namespace count went from 36 → **41**.
-
-## Migration recipe
-
-### Internal consumers (this monorepo)
-
-Nothing to do. The shells already `@import "@exxatdesignux/ui/globals.css"`.
-
-### External consumers (post-publish)
-
-If you previously had:
-```css
-/* app/globals.css */
-@import "tailwindcss";
-@import "tw-animate-css";
-@import "@exxatdesignux/ui/theme.css";   /* ❌ no longer exported */
-@source "...";
-```
-
-Change it to:
-```css
-/* app/globals.css */
-@import "@exxatdesignux/ui/globals.css"; /* brings Tailwind + tw-animate-css + tokens + base layer */
-@source "../node_modules/@exxatdesignux/ui/src";
-```
-
-The package globals.css now carries the `@import "tailwindcss"` /
-`@import "tw-animate-css"` for you — your shell only needs `@source`
-plus any app-specific additions.
-
-## Verification
-
-- `pnpm --filter @exxatdesignux/ui tokens:index` → 195 tokens / 41 namespaces, no errors.
-- `pnpm --filter @exxat-ds/web lint` → no new violations.
-- Grep for stale `theme.css` references → only this migration + the 0002 link.
-
-## Follow-ups (optional)
-
-- Document the canonical-file rule in `apps/web/AGENTS.md` § token
-  taxonomy (already updated).
-- Add a CI check to `tokens:check` that fails when the consumer shell
-  contains anything other than `@import` + `@source` + comments, so the
-  shell stays thin.
-
-## See also
-
-- [`docs/token-taxonomy.md`](../token-taxonomy.md) — layered token model.
-- [`0002-exxat-token-namespace.md`](./0002-exxat-token-namespace.md) — the
-  L0 namespace introduction (which now lives in `globals.css`, not
-  `theme.css`).

package/template/docs/migrations/README.md

@@ -1,100 +0,0 @@
-# Exxat DS — Migrations
-
-**Inspired by:** SLDS [v1 → v2 uplift skill](https://www.lightningdesignsystem.com/2e1ef9c7e/v/1604/p/9929fa-uplift-skill).
-
-Every breaking change in `@exxatdesignux/ui` (token rename, component prop
-removal, deprecated pattern) lives here as a numbered migration entry. The
-**first entry of any release that breaks API or tokens** must land alongside
-the change.
-
----
-
-## How migrations work
-
-```
-docs/migrations/
-├── README.md           ← this file (active deprecations + index)
-└── NNNN-<slug>.md      ← one file per migration
-```
-
-| Field | Meaning |
-|---|---|
-| `NNNN` | Zero-padded 4-digit sequence number (`0001`, `0002`, …) |
-| `<slug>` | Short kebab-case identifier — what is changing |
-
-**One file per migration.** Two unrelated changes in the same release get two
-files.
-
----
-
-## Lifecycle of a deprecation
-
-1. **Plan** — Open a migration file even before the release ships. Author the
-   `Why` and `Before/After` sections; leave `Released in` blank.
-2. **Announce** — When the change lands, fill `Released in` (e.g. `v0.3.0`),
-   add the `@deprecated` comment in `packages/ui/src/globals.css` or the component file:
-   ```css
-   /* @deprecated v0.3.0 — use --brand-color-dark; remove in v0.4.0 */
-   ```
-   Make sure `pnpm --filter @exxatdesignux/ui tokens:index` picks it up
-   (`tokens/hooks-index.json` will mark `deprecated: true`).
-3. **Migrate** — Land the migration script (if scriptable) under
-   `packages/ui/scripts/migrate-NNNN-<slug>.mjs`; otherwise document the manual
-   grep + replace.
-4. **Remove** — When the deprecation window closes (named in the comment),
-   delete the deprecated token / component. Set `Removed in` in the migration
-   file. The file stays in the repo forever as a record.
-
----
-
-## Active deprecations
-
-> _None yet._ Update this table when announcing a deprecation.
-
-| Migration | Token / Component | Deprecated in | Remove in |
-|---|---|---|---|
-| — | — | — | — |
-
----
-
-## Migration template
-
-Copy [`_template.md`](./_template.md) when adding a migration:
-
-```
-# Migration NNNN — <Title>
-
-> **Released in:** vX.Y.Z · **Removed in:** vX.Y.Z (or "planned") · **Owner:** <person/team>
-
-## Why
-…
-## Affected surface
-…
-## Before
-…
-## After
-…
-## Migration recipe
-…
-## Verification
-…
-```
-
----
-
-## Index
-
-| # | Slug | Released | Removed |
-|---|---|---|---|
-| [0001](./0001-brand-deep-alias-stabilization.md) | `brand-deep-alias-stabilization` | v0.2.18 | — (no removal — stabilization) |
-| [0002](./0002-exxat-token-namespace.md) | `exxat-token-namespace` | v0.2.19 | — (additive — L1 stays) |
-| [0003](./0003-globals-css-canonical.md) | `globals-css-canonical` | v0.2.20 | `theme.css` removed |
-
----
-
-## See also
-
-- [`token-taxonomy.md`](../token-taxonomy.md) — naming + deprecation policy (§5)
-- [`packages/ui/CHANGELOG.md`](../../../packages/ui/CHANGELOG.md) — release notes
-- [`.cursor/rules/exxat-token-discipline.mdc`](../../../.cursor/rules/exxat-token-discipline.mdc) — lint rule for deprecated tokens
-- [`packages/ui/tokens/hooks-index.json`](../../../packages/ui/tokens/hooks-index.json) — machine-readable index (includes `deprecated: true`)

package/template/docs/migrations/_template.md

@@ -1,64 +0,0 @@
-# Migration NNNN — <Title>
-
-> **Released in:** vX.Y.Z · **Removed in:** vX.Y.Z (or _planned_) · **Owner:** <person / team>
-> **Type:** token rename · component rename · prop removal · pattern deprecation · stabilization
-
-## Why
-
-One paragraph. Explain the user-visible or developer-visible problem this
-migration addresses.
-
-## Affected surface
-
-| Surface | Was | Becomes |
-|---|---|---|
-| Tailwind utility | `text-foo` | `text-bar` |
-| CSS custom prop | `--foo` | `--bar` |
-| React component | `<OldName />` | `<NewName />` |
-| Pattern | … | … |
-
-## Before
-
-```tsx
-// Old usage
-```
-
-## After
-
-```tsx
-// New usage
-```
-
-## Migration recipe
-
-### Automatic
-
-```bash
-# Run from the monorepo root.
-node packages/ui/scripts/migrate-NNNN-<slug>.mjs
-```
-
-(Or note "manual only — no script.")
-
-### Manual
-
-1. Search for `<pattern>` across `apps/web/`, `packages/ui/src/`, and
-   `packages/ui/template/`.
-2. Replace per the table above.
-3. Re-run `pnpm --filter @exxatdesignux/ui tokens:index`.
-4. Re-run `pnpm --filter @exxat-ds/web lint`.
-
-## Verification
-
-- [ ] `pnpm typecheck` clean across workspace
-- [ ] `pnpm --filter @exxatdesignux/ui tokens:check` passes
-- [ ] No remaining matches for `<old pattern>` in code search (excluding this
-      migration file)
-- [ ] Visual regression sweep on affected hubs (Placements / Team /
-      Compliance / Library)
-
-## References
-
-- `packages/ui/CHANGELOG.md` (vX.Y.Z)
-- Related rule: `.cursor/rules/<rule>.mdc`
-- Related blueprint: `apps/web/docs/blueprints/<blueprint>.md`

package/template/docs/modern-saas-patterns.md

@@ -1,165 +0,0 @@
-# Modern SaaS patterns — the canon Exxat DS works against
-
-> **Audience:** humans + AI agents.
-> **Companion to:** [`exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md),
-> [`exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc),
-> [`jobs/`](./jobs/).
-
-A senior designer recognizes the work. This doc names the patterns the best
-products converged on in 2024–2026, so the agent can pattern-match instead
-of inventing. **Cite by name + code** when you reference one in a design brief
-(e.g. `Linear issue detail (M1, M4, M7)`).
-
-## Canon products — cite by product, not by URL
-
-| Product | What to learn from it |
-|---------|-----------------------|
-| **Linear** | Issue detail, command palette spine, density, keyboard-first, presence, "less chrome" |
-| **Notion** | Inline editing, property panels, page-as-database, blocks, slash-commands |
-| **Stripe Dashboard** | Record home, status chips, activity log, money-grade precision |
-| **Figma** | Multiplayer, presence, side panel inspector, infinite-canvas chrome discipline |
-| **Vercel** | Type-first hierarchy, dark-first, minimal chrome, log streams |
-| **Height** | View tabs (table/board/timeline), custom fields, view parity |
-| **Plain / Pylon** | Support detail = identity + timeline + actions; conversation-as-document |
-| **Cron / Amie** | Keyboard-only flows, dense calendar, command surface |
-| **Raycast** | Command palette as full app, extension surface, deep keyboard |
-| **Arc Browser** | Control-stripped, content-first, sidebar as the only chrome |
-
-## The 12 patterns that make products feel modern
-
-### M1. Content-first chrome
-The data is the star. Sidebars collapse to icons. Headers stay 48–56px. Page
-surfaces are generous. No purple gradient on the top bar.
-
-- **In DS:** `SiteHeader` ~h-12; `PrimaryPageTemplate` body has generous
-  `max-w-[1440px]`; sidebar collapsible (`SidebarTrigger`).
-
-### M2. Command palette as the spine
-`⌘K` opens search + navigation + AI + recent. It is the primary navigation
-for power users. The sidebar exists for orientation, not speed.
-
-- **In DS:** `CommandMenu` (⌘K) + Ask Leo split (⌘⌥K).
-  Rule: `exxat-command-menu.mdc`.
-
-### M3. Side-panel detail over modal dialog
-For non-destructive context-keeping actions (properties, export, invite,
-preview, single-step compose), use a slide-in sheet — never a centered modal.
-
-- **In DS:** `Sheet` (no Vaul).
-  Rule: `exxat-drawer-vs-dialog.mdc`. Pattern:
-  `apps/web/docs/drawer-vs-dialog-pattern.md`.
-
-### M4. Status as a first-class citizen
-Colored dots, chips, counts visible everywhere data appears. Status isn't
-hidden in a detail page; it appears on rows, cards, headers, navigation.
-
-- **In DS:** `ListHubStatusBadge` + `lib/list-status-badges.ts`. Available per
-  row, board card, detail header, breadcrumb count slot.
-
-### M5. Inline editing where data is read
-Click the value, edit it. No bounce to forms for single-field changes.
-
-- **In DS:** Inline-edit primitive emerging; until then, use a `Sheet` for
-  multi-field, popover or contenteditable for single-field. Principle: P15.
-
-### M6. Optimistic UI + undo
-Low-risk actions (favorite, archive, status flip) feel instant; reconcile on
-error. Undo via banner or in-place affordance — **never** toast
-(`exxat-no-toast.mdc`).
-
-- **In DS:** Optimistic state in `useTableState` selection ops; undo via
-  `LocalBanner` with action.
-
-### M7. Activity timeline on every record
-Who did what when. The audit log is also a navigation device.
-
-- **In DS:** `ActivityTimeline` primitive emerging. Compose from
-  `lib/mock/activity` shape until then.
-
-### M8. Empty states with one CTA + one sentence
-Illustration optional. One sentence of context. One primary action. Never a
-wall of help text or a tutorial inline.
-
-- **In DS:** `EmptyState` primitive; voice from `docs/voice-and-tone.md`.
-
-### M9. Skeleton, not spinner
-Loading shapes content. Spinners only for indeterminate < 200ms.
-
-- **In DS:** `Skeleton` primitive; suspense boundaries shape the body.
-
-### M10. Type-first hierarchy
-Weight, size, color do the heavy lifting before borders, boxes, or tints.
-Ornament is rare and intentional.
-
-- **In DS:** Token scale; body in `Inter`; display in `Ivy Presto` (only on
-  `PageHeader` H1 by default).
-
-### M11. Real-time presence + collaboration as default
-If the product is shared, show who else is here — face rails, cursors,
-status. Inviting others is one click from the page.
-
-- **In DS:** `PageHeader variant="collaboration"` face rail +
-  `InviteCollaboratorsDrawer`.
-  Rule: `exxat-collaboration-access.mdc`.
-
-### M12. AI as opt-in sidecar
-Ask Leo style — never the primary path, never auto-runs on a record, always
-discoverable, always cancellable. Deterministic path still exists.
-
-- **In DS:** `AskLeoSidebar` + `⌘⌥K` toggle; never a "magic" button on a
-  destructive surface.
-
----
-
-## The anti-modern signals (what NOT to do)
-
-| Signal | Why it's dated |
-|--------|----------------|
-| Toasts everywhere | Modern products use inline + banner + undo. Toasts get missed. |
-| Full-width tab bars stretched edge-to-edge | 2010s pattern. Modern uses `w-fit` segmented controls. |
-| Centered modals for everything | Sheets and routes carry more without breaking flow. |
-| Color-coded sidebar sections | Modern is monochrome chrome + status color on data. |
-| Modal wizards with progress bar | If it has > 3 steps, give it a route. |
-| Spinners on initial load | Skeleton the content shape instead. |
-| Hover-only affordances | Touch + keyboard need parity. |
-| Icons without text labels in primary nav | Recognition fails for new users. |
-| "Beautiful" gradients on chrome | Data should be beautiful; chrome should disappear. |
-| Aggressive empty-state illustrations | One sentence + one action beats illustration + 5 tips. |
-| Edit-takes-you-to-a-form for single fields | Inline edit (M5). |
-| "Back to <parent>" button alongside breadcrumb | P1 — choose one. |
-| Auto-running AI on record open | M12 — opt-in only. |
-
----
-
-## Density layers (Linear / Vercel model)
-
-| Layer | When |
-|-------|------|
-| **Cozy** (default) | Most surfaces; balances scan + breathing room |
-| **Compact** | Power users on daily workflow; tables, command results |
-| **Comfortable** | Accessibility (low-vision, motor); marketing-adjacent |
-
-Provide a user-level setting where audiences differ; default to **cozy**.
-Don't fork stacks per density.
-
----
-
-## How to use this doc in a design brief
-
-```
-Reference (modern): Linear issue detail (M1, M4, M7),
-                    Stripe customer record (M4, M11)
-```
-
-Cite the **patterns (Mx)** the agent applied, not just the product. Forces
-clear thinking and lets reviewers verify intent.
-
-## See also
-
-- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md) — persona
-- [`../../../.cursor/rules/exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc) — brief gate
-- [`../../../.cursor/rules/exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc) — principles + breaks
-- [`./jobs/`](./jobs/) — canonical reference per job type
-- [`./component-selection-guide.md`](./component-selection-guide.md) — picking the composition
-- [`./blueprints/`](./blueprints/) — framework-agnostic surface specs
-- [`./voice-and-tone.md`](./voice-and-tone.md) — copy rules

package/template/docs/perf-memory-pattern.md

@@ -1,206 +0,0 @@
-# Dev memory tuning for Next.js + Node 24
-
-> **Audience:** humans + AI agents.
-> **Companion to:** [`HANDBOOK.md`](./HANDBOOK.md). Read this when `next dev`
-> RSS climbs past ~3 GB, when two `next-server` processes total > 5 GB, or
-> when adopting Node 24.
-
-A fresh `next dev` against this app stabilizes around **~1.4 GB RSS** with
-the settings below. Without them, the same app drifts to **3–6 GB per
-process** and pm2 will eventually swap or OOM.
-
-## 1. The six knobs
-
-| # | Knob | Why it matters | Where it lives |
-|---|------|----------------|----------------|
-| 1 | `NODE_OPTIONS="--max-old-space-size=6144 --max-semi-space-size=64"` | Caps V8 old-space at 6 GB (default on macOS is ~94% of system RAM = unbounded for practical purposes). With a ceiling, V8 GC pressure kicks in earlier and steady-state heap is lower. `--max-semi-space-size=64` widens the young generation so short-lived render allocations don't promote to old-space. | `package.json` `dev*` scripts + `ecosystem.config.cjs` `env` |
-| 2 | `turbopack.memoryLimit: 4 GiB` | Hard cap on the Turbopack worker process. Without this, Turbopack's module graph + mmap'd FS cache files grow unbounded — we observed 3.2 GB on disk and 5+ GB RSS per process with no cap. 4 GiB is generous for apps with < ~1000 routes. | `next.config.mjs` `turbopack` |
-| 3 | `experimental.preloadEntriesOnStart: false` | Next compiles routes on first visit instead of pre-warming every entry on dev start. Dev TTFB drops from ~15s → ~2s; steady-state heap is ~30% lower. | `next.config.mjs` |
-| 4 | `experimental.optimizePackageImports: [...]` | Re-export barrels (`lucide-react`, `@tabler/icons-react`, `motion`, `@dnd-kit/*`, `recharts`) get tree-shaken to leaf imports. Cuts the dev server's parsed-module count by ~40%. | `next.config.mjs` |
-| 5 | `experimental.webpackMemoryOptimizations: true` | Drops large in-memory webpack caches at the cost of slightly slower rebuilds. **Only the `pnpm dev:webpack` fallback uses webpack** — Turbopack ignores this flag. Keep it on for the rare cases where the webpack path is needed. | `next.config.mjs` |
-| 6 | `target: ES2022` (tsconfig) | The TS compiler emits less polyfill scaffolding for `async/await`, optional chaining, nullish coalescing, etc. tsserver in-memory AST shrinks proportionally. Safe with React 19 + Next 16 + Node 24. | `tsconfig.json` |
-
-## 2. NODE_OPTIONS propagation
-
-`NODE_OPTIONS` is read by **every Node process** the moment it boots. The npm
-parent doesn't read it (npm is a shell wrapper), but its child `next-server`
-processes inherit and honour it.
-
-- **Local dev:** set inline in `package.json` `scripts`. Cross-shell safe
-  because Next dev is only run from POSIX shells.
-- **PM2 daemon:** set in `ecosystem.config.cjs` `env` (which becomes the child
-  environment).
-- **CI:** set in the workflow `env:` block on the same step that runs `next`.
-- **VS Code / Cursor terminals:** these inherit the parent shell env, so the
-  `package.json` script is enough.
-
-## 3. Turbopack file-system cache (Next ≥ 16.1)
-
-Since Next 16.1, **`experimental.turbopackFileSystemCacheForDev` defaults to `true`** — Turbopack writes compilation artifacts to `.next/dev/cache/turbopack/<hash>/*.meta` and mmaps them across dev sessions. This is what makes the second `next dev` start in ~1 s instead of ~15 s.
-
-**The trade-off** is that the cache grows linearly with the number of unique routes / modules you've touched. After a few weeks of feature work it's normal to see:
-
-```bash
-du -sh .next
-# 3.2G  .next
-```
-
-Each `.meta` file is mmap'd by the running `next-server`, so the cache size is roughly the floor of the dev process's RSS until the OS evicts pages.
-
-**Do not disable** the FS cache (`turbopackFileSystemCacheForDev: false`) — cold-start dev becomes painful (~15–30 s every restart on this app). Instead, **bust the cache** when it grows past 1–2 GB:
-
-```bash
-pnpm clean:cache  # removes .next/dev/cache and .next/dev/trace
-pnpm dev:fresh    # bust + restart in one command
-```
-
-The `dev:fresh` script is the right move whenever:
-
-- A pnpm install changed `@exxatdesignux/ui` or any framework dep.
-- `.next` is > 2 GB and dev memory is climbing.
-- HMR starts skipping updates or compilation gets stuck on a stale module.
-
-For a full nuke (build artifacts too):
-
-```bash
-pnpm clean
-```
-
-`turbopack.memoryLimit` (knob #2) prevents the cache from blowing past 4 GiB of RAM even when the on-disk cache is large.
-
-## 4. Don't run two dev servers at the same time
-
-**This is the #1 cause of memory exhaustion in practice.** A single `next-server` (parent + render worker) stabilizes at ~2 GB total RSS with the knobs above. Two parallel servers stabilize at ~4 GB, three at ~6 GB, and so on — they don't share any caches.
-
-If you see two `next-server` lineages in `ps`, check:
-
-```bash
-ps aux | grep next-server | grep -v grep
-lsof -p <pid> | grep '\.next/dev/cache' | head -5  # which checkout owns it
-```
-
-Common dual-server scenarios:
-
-| Scenario | Symptom | Fix |
-|----------|---------|-----|
-| Two checkouts of the same monorepo (e.g. `DS_Workspace/` and `Exxat-DS-Workspace/`) both running `pnpm dev:web` | Two `next-server` parents, both in `apps/web/.next/...` paths but on different absolute roots | Quit one. Pin to a single checkout per machine. |
-| A customer app (e.g. `test-9`) + the monorepo `apps/web` running at the same time | Different cache hashes (`ee6e79b1/`) under different roots | Stop whichever you're not actively touching: `pm2 stop exxat-ds` or `Ctrl+C` |
-| A stale pm2 daemon from a prior `nvm use 22` session left running after upgrading to Node 24 | One Node-22 + one Node-24 dev server | `pm2 delete exxat-ds` then `pnpm dev:daemon` to re-launch under Node 24 |
-| `next build` running in another tab while `next dev` is up | Three or four `next-server` for the duration of the build | Wait for the build, or kill the dev server until the build is done |
-
-## 5. Two `next-server` processes per app is normal
-
-Next 16 splits dev into:
-
-- **`next-server` (main)** — HTTP entry, watcher, router.
-- **`next-server` (render worker)** — RSC + SSR pipeline.
-
-Both inherit `NODE_OPTIONS`, so the 6 GB cap applies to **each**. With the
-config in this app the totals stabilize around **~1.4 GB + ~0.6 GB ≈ 2 GB**.
-If you ever see a third or fourth `next-server`, that's the build worker
-spawning during a route compile — they exit when the build completes.
-
-## 6. Diagnose a memory regression
-
-When dev RSS climbs past 4 GB and stays there:
-
-```bash
-# First, check the boring stuff
-du -sh .next                                         # > 2 GB → run pnpm clean:cache
-ps aux | grep next-server | grep -v grep | wc -l     # > 2 lines → you have two dev servers
-lsof -p <pid> | wc -l                                # > 5000 FDs → cache is mmap-flooding
-
-# Then profile a 60s window — heap snapshots to .next/diagnostics/
-pnpm dev:profile
-
-# Open the latest .heapprofile in Chrome DevTools → Memory → "Load"
-ls -lt .next/diagnostics | head -3
-```
-
-Common culprits and their signatures:
-
-| Symptom | Likely cause | Fix |
-|---------|--------------|-----|
-| `.next` is > 2 GB on disk; many `.meta` files | Turbopack FS cache bloat over weeks | `pnpm clean:cache` then `pnpm dev` (see §3) |
-| Two or more `next-server` parents in `ps` | Dual dev server across checkouts / apps | Stop the one you aren't using (see §4) |
-| Many copies of `lucide-react.js` / `recharts.js` retained in heap | Missing entry in `optimizePackageImports` | Add the package to the list (knob 4) |
-| Compiled chunks for routes you never visited | `preloadEntriesOnStart` is `true` | Set to `false` (knob 3) |
-| Heap grows on every HMR cycle, never shrinks | RSC HMR cache + import.meta.hot leak | `experimental.serverComponentsHmrCache: false` (try only if knob 3 is already on) |
-| Single retainer chain holds 100 MB+ | A module-level `Map` / `Set` in app code never gets cleared | Move to request-scoped storage |
-| tsserver alone is > 1.5 GB | TS strict + large lib check | `skipLibCheck: true` (already on), drop `allowJs` if not needed |
-| Turbopack worker RSS keeps growing past 4 GiB | `turbopack.memoryLimit` not set | Apply knob 2 |
-
-## 7. Node 24 features we leverage
-
-Node 24 (LTS-track) is required by `engines.node` in `package.json` and
-pinned in `.nvmrc`. Specifically:
-
-- **V8 13.6 with Maglev JIT default-on** — faster startup, lower base heap.
-  Steady-state RSS for the `next dev` parent is ~12% lower vs Node 22.
-- **Improved incremental marking GC** — fewer long pauses during HMR; the
-  perceived "stutter" when saving a large file is gone.
-- **Permission model (`--permission`)** — not enabled in dev (Next reads
-  too many paths to make `--permission` ergonomic), but available for
-  hardening production scripts.
-- **`node --run <script>`** — replaces `npm run` for one-off scripts with
-  ~30 ms less per-invocation overhead. Use it in any CI step that runs a
-  workspace script directly: `node --run typecheck`. Not yet wired into
-  this repo's pm2 / package scripts because pm2 itself spawns `npm`.
-- **`--heap-prof` / `--cpu-prof` always-on** — the `dev:profile` script in
-  `package.json` uses these to drop snapshots into `.next/diagnostics/`
-  without any third-party profiler dependency.
-- **`--experimental-strip-types`** — Node 24 can run `.ts` files directly,
-  but Next still uses tsc + swc, so this only helps for stand-alone
-  scripts under `apps/web/scripts/` (e.g. `fa:subset-audit`) if they're
-  converted from `.mjs` to `.ts`.
-- **Smaller initial heap allocations** — V8 13.6 starts with ~50 MB less
-  reserved arena vs V8 12.x. Most visible in fast CI test runs.
-
-## 8. Anti-patterns
-
-| Anti-pattern | Why it's wrong |
-|--------------|----------------|
-| Setting `NODE_OPTIONS` only in `.env.local` | `.env.local` is read by Next, not by Node. The dev server's own runtime never sees it. |
-| Setting `--max-old-space-size` to the system RAM amount | Defeats the cap. The point is to force GC pressure, not raise the ceiling. |
-| Running multiple `next dev` instances on the same machine without unique ports | Each instance ignores the others' caches and the total RSS is N × steady-state. Use the dedicated `dev:3001` / `dev:3005` scripts. |
-| `NODE_OPTIONS=--inspect` in normal dev | Allocates an extra inspector arena per process (~200 MB). Use only when actively debugging. |
-| Adding `nodemon` on top of `next dev` | Next has its own watcher; nodemon doubles the file-system event handlers. |
-| Importing `@exxatdesignux/ui` from the package root for every icon | Defeats `optimizePackageImports`. Always import from the leaf path the DS exposes. |
-| Running pm2 without `max_memory_restart` | A wedged worker stays wedged. The 7 GB ceiling lets pm2 recycle before the OS swaps. |
-| Disabling `turbopackFileSystemCacheForDev` because "cache is the problem" | Cold starts go from ~1s to ~15–30s every restart. Bust with `pnpm clean:cache` instead. |
-| Two checkouts of the same monorepo both running dev | Caches don't share — 2× total RSS. Pin to one checkout per machine. |
-
-## 9. Upgrading an existing customer app
-
-If your app was scaffolded before `@exxatdesignux/ui@0.5.10`, copy the diffs
-below from `node_modules/@exxatdesignux/ui/template/`:
-
-1. `.nvmrc` — set to `24`.
-2. `package.json` — `engines.node: ">=24.0.0"` + the `NODE_OPTIONS` /
-   `NEXT_TELEMETRY_DISABLED` prefix on every `dev*` script + the new
-   `dev:profile`, `dev:fresh`, `clean`, `clean:cache` scripts.
-3. `next.config.mjs` — add the `turbopack: { memoryLimit }` block, the
-   expanded `experimental.optimizePackageImports` array,
-   `experimental.preloadEntriesOnStart: false`,
-   `experimental.webpackMemoryOptimizations: true`, and the
-   `onDemandEntries` block.
-4. `tsconfig.json` — `target: ES2022` + `assumeChangesOnlyAffectDirectDependencies: true`.
-5. `ecosystem.config.cjs` (if used) — add the `env` block with
-   `NODE_OPTIONS` + `NEXT_TELEMETRY_DISABLED` and `max_memory_restart: "7G"`.
-6. Run `nvm install 24 && nvm use` (or your Node manager equivalent).
-7. **First run after upgrading:** `pnpm clean && pnpm dev` to drop the
-   pre-0.5.10 Turbopack cache (it was written without the memory cap and
-   may carry stale mmap layouts).
-
-Restart the dev server. You should see steady-state RSS settle in the
-1.5–2 GB range within ~30 s of the first navigation. If you still see
-> 3 GB per process: re-read §4 — you almost certainly have a second
-dev server running somewhere.
-
-## See also
-
-- [`HANDBOOK.md`](./HANDBOOK.md) — workspace orientation
-- [`consumer-upgrade-checklist.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/packages/ui/consumer-extras/patterns/consumer-upgrade-checklist.md) — what to do after `pnpm add @exxatdesignux/ui@latest`
-- [Next.js — Reducing dev memory usage](https://nextjs.org/docs/app/building-your-application/optimizing/memory-usage)
-- [Node.js — Diagnostics](https://nodejs.org/api/cli.html#--heap-profheap_dir)
-- [V8 — Maglev](https://v8.dev/blog/maglev)