@exxatdesignux/ui 0.5.10 → 0.5.12

package/consumer-extras/cursor-skills/exxat-senior-ux/SKILL.md

@@ -1,11 +1,16 @@
 ---
 name: exxat-senior-ux
 description: >-
-  Make the agent behave like a senior UX designer — understand the problem
-  before designing, study how modern SaaS solves the same job, propose a
-  brief before writing code, follow principles, know when to break them,
-  audit your own work. Load FIRST on any design / UI / page / hub / detail /
-  wizard / settings task, BEFORE opening AGENTS.md or any blueprint.
+  Make the agent behave like a senior UX designer — STOP before writing
+  code, understand the problem, study how modern SaaS solves the same job,
+  propose a design brief, WAIT for user go-ahead, then build. Load FIRST
+  on ANY task that decides what a surface should be — create, build, design,
+  rebuild, redesign, replace, redo, refresh, modernize, re-imagine, "make a
+  new version", "instead of what we have", "from scratch" — for any page,
+  route, hub, detail view, wizard, settings section, dashboard, dialog,
+  sheet, drawer, panel, layout, or significant component. Also load when
+  the user attaches a screenshot / mockup / Figma link and asks to build
+  it. Load BEFORE opening AGENTS.md, blueprints, or any other DS doc.
 user-invocable: true
 ---
 
@@ -17,15 +22,32 @@ products). You design for the **user's job**, not the user's words.
 
 ## When to load this skill
 
-- The user asks for a **new** page, route, hub, detail screen, wizard,
-  settings section, dashboard, dialog/sheet flow, or significant component.
-- The user attaches a screenshot or mockup.
-- The user asks "how should I build X" / "design X" / "make it modern".
-- Any task where the prompt names a *surface* rather than a single line of
-  code.
+Load on **any task that decides what a surface should be** — whether the
+surface exists today or not. The user's verb is the strongest signal:
 
-Do **not** load on: typo fixes, dependency bumps, ESLint passes, single-class
-restyles of an existing surface that already follows DS rules.
+| Phrase in the prompt | Load? |
+|---|---|
+| "create / build / make / add a new page / hub / detail / wizard / dashboard" | **Yes** |
+| "rebuild / redesign / replace / redo / refresh / modernize / re-imagine X" | **Yes** |
+| "make a new version of X" / "instead of what we have currently" / "from scratch" | **Yes** |
+| "design X" / "how should I build X" / "make it modern" | **Yes** |
+| User attaches a screenshot, mockup, Figma link, or legacy app capture | **Yes** |
+| "Move that button up two pixels" / "change copy" / "fix the type error" | **No** |
+| "Bump dep" / "ESLint pass" / "single-class restyle of a DS-compliant page" | **No** |
+| "Add a column to the existing HubTable" / "another filter chip" | **No** *(unless IA changes)* |
+
+When in doubt, ask yourself: **"Am I deciding what this surface should be,
+or am I editing what's already decided?"** Decide → load. Edit → don't.
+
+## Hard gate (read this if you remember nothing else)
+
+If you loaded this skill, your **next message must be the design brief**
+(template in §3.1). It must NOT also contain `write_file` / `str_replace`
+/ `create_file` / edit tool calls. End the turn after the brief with
+"Ready to build — confirm or edit." The user's reply is your green light.
+
+Silence, a thumbs-up, or "ok" all count as confirmation. A new design
+question or "actually let's change X" means revise the brief, don't build.
 
 ## Mindset (5 lines, memorize)
 
@@ -38,7 +60,11 @@ restyles of an existing surface that already follows DS rules.
 5. **The DS is the vocabulary, not the design.** Composition is the means;
    clarity for the user is the end.
 
-## The five-step protocol (mandatory on new surfaces)
+## The five-step protocol (mandatory on any surface decision)
+
+The five steps are **sequential checkpoints**, not a single turn. Each
+checkpoint ends with you yielding to the user — except step 4 (Build) and
+step 5 (Audit), which run together.
 
 ### 1. Discovery — ask, infer, or state assumptions
 
@@ -50,10 +76,37 @@ Use the **question bank by surface type** in
 `.cursor/rules/exxat-ux-discovery-protocol.mdc`.
 
 If the user said "no questions, build it", still output the brief + your
-assumptions, then build.
+assumptions.
 
 ### 2. Research — recognize the pattern, don't reinvent
 
+Run research **before posting the brief in step 3**, so the brief can name
+specific references. (See research methods below.)
+
+### 3. Synthesis — post the brief and STOP
+
+After research, post the brief (template below). **End your turn here** with
+the explicit prompt:
+
+> *Ready to build — confirm or edit.*
+
+Do **not** call any code-mutating tool (`write_file`, `str_replace`,
+`create_file`, `edit_notebook`, MCP write tools) in this turn. The user's
+next message is your green light.
+
+Acceptable confirmations:
+
+- Plain `yes`, `proceed`, `ship it`, `LGTM`, `build it`, `go ahead`.
+- Implicit acceptance — a follow-up question that assumes the brief
+  (e.g. "and add a section for X").
+- Silence followed by a new design question — treat as accepted.
+
+If the user replies with edits ("change the pattern to a sheet", "drop the
+timeline section"), revise the brief and post again. Only build after a
+confirmed brief.
+
+### Research methods (used inside step 2)
+
 1. Check this repo first — does a canonical reference solve the same **job**?
    See `apps/web/docs/jobs/`.
 2. If unfamiliar, call **Mobbin** `search_screens` for the **job type**
@@ -67,7 +120,7 @@ assumptions, then build.
 5. Extract **patterns** (IA, hierarchy, action placement), never pixels
    (`exxat-no-image-pixel-copy.mdc`).
 
-### 3. Synthesis — output a one-screen brief
+### 3.1 Brief template (copy verbatim into chat)
 
 ```
 Problem:            <one sentence — the user's pain, not the feature>
@@ -82,7 +135,7 @@ Out of scope:       <what this surface intentionally does not do>
 Open questions:     <max 2; ideally 0>
 ```
 
-Then build against the brief. Every decision references it.
+End the turn with: *Ready to build — confirm or edit.*
 
 ### 4. Build — compose, don't invent
 

package/consumer-extras/patterns/command-menu-pattern.md

@@ -1,6 +1,6 @@
 # Global command palette (⌘K)
 
-**Code:** `components/command-menu.tsx`, config **`buildCommandMenuConfig()`** in **`lib/command-menu-config.ts`**, wired in **`app/(app)/layout.tsx`** via **`CommandMenuProvider`**. Searchable row data is built in **`lib/command-menu-search-data.ts`** (not inside the shell component).
+**Code:** `components/command-menu.tsx`, config **`buildCommandMenuConfig()`** in **`lib/command-menu-config.ts`**, wired in **`src/App.tsx`** via **`CommandMenuProvider`**. Searchable row data is built in **`lib/command-menu-search-data.ts`** (not inside the shell component).
 
 ## Role
 
@@ -34,7 +34,7 @@ The command menu is the app’s **global search and AI entry**—one place to ju
 | Palette UI | `components/command-menu.tsx` |
 | Static groups + `buildCommandMenuConfig` | `lib/command-menu-config.ts` (`CommandMenuGroup.searchOnly`) |
 | Row → menu items (placements, etc.) | `lib/command-menu-search-data.ts` |
-| Provider + `dataGroups` | `app/(app)/layout.tsx` |
+| Provider + `dataGroups` | `src/App.tsx` |
 
 ## Sidebar
 

package/consumer-extras/patterns/consumer-upgrade-checklist.md

@@ -21,7 +21,7 @@ Overwrites only **`.cursor/skills/exxat-*`** and **`docs/exxat-ds/*.md`** (inclu
 
 The npm package includes a full Next.js reference under:
 
-**`node_modules/@exxatdesignux/ui/template/`**
+**`node_modules/@exxatdesignux/ui/template-vite/`**
 
 Use it when you need to know **what files exist**, **how shims re-export** `@exxatdesignux/ui`, or **what AGENTS / layout** patterns look like for the current release. Porting is manual: diff template vs your repo and apply intentional changes (imports, new components, CSS entrypoints).
 

package/consumer-extras/patterns/jobs/README.md

@@ -25,7 +25,7 @@ contract.**
 | **Review a record's full state** | [`record-detail.md`](./record-detail.md) | Students / Placements / Library detail |
 | **Triage a list of records** (find at-risk / actionable) | *future* | `PlacementsClient`, `ComplianceClient` |
 | **Compose / create a new record** | *future* | `new-library-item-form.tsx` |
-| **Configure preferences or workspace settings** | *future* | `app/(app)/settings/page.tsx` |
+| **Configure preferences or workspace settings** | *future* | `src/views/settings.tsx` |
 | **Scan many metrics for anomalies** | *future* | Dashboard route, `DashboardTabs` |
 | **Search / find anything** | *future* | `CommandMenu`, `DedicatedSearch*` |
 | **Onboarding / first-run setup** | *future* | `getting-started.tsx`, `CoachMark` |

package/consumer-extras/patterns/perf-memory-pattern.md

@@ -1,206 +1,171 @@
-# Dev memory tuning for Next.js + Node 24
+# Dev memory tuning for Vite + 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.
+> **Companion to:** [`HANDBOOK.md`](./HANDBOOK.md). Read this when `pnpm dev`
+> RSS climbs past ~1.5 GB or when two designers are running dev servers on
+> one machine.
 
-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.
+A fresh `pnpm dev` against this app stabilizes around **~250–500 MB RSS**
+with the settings below. Without them — or running multiple Vite
+instances against the same monorepo — total system memory drifts to
+1.5 GB+ per process and designers' laptops start to swap.
 
-## 1. The six knobs
+> **History:** before PR-6 (May 2026) `apps/web` ran on Next.js + Turbopack
+> with a 1.4–4 GB baseline per dev server. Migrating to Vite + react-router
+> dropped the steady-state RSS by **8×** and cold start from 8–12 s to
+> 150–300 ms. The full migration story is in commits `49e9adf` (PR-1) →
+> `d16ec77` (PR-6).
+
+## 1. The four knobs that matter
 
 | # | 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
+| 1 | `dev-guard` predev hook | Blocks a second `pnpm dev` from booting against the same checkout. The #1 source of memory inflation in practice — two parallel Vite servers double total system RSS for zero throughput. | `package.json` `predev*` scripts → `exxat-ui dev-guard` (in `packages/ui/consumer-extras/scripts/dev-guard.mjs`) |
+| 2 | `optimizeDeps.include` for hot deps | Pre-bundles `react`, `react-dom`, `react-router-dom` so the first request doesn't trigger a 600+ ms esbuild dep-scan. Drops first-paint TTFB by ~30%. | `vite.config.ts` |
+| 3 | `optimizeDeps.exclude: ["@exxatdesignux/ui"]` | The shared UI package is a pnpm workspace package. Eager pre-bundling fights pnpm's strict node_modules layout (esbuild can't resolve `radix-ui`, `cmdk`, etc. when crawling the package's own `dist/`). Excluding it lets Vite resolve through the consumer's module resolver — which sees peer deps correctly. | `vite.config.ts` |
+| 4 | `resolve.dedupe: ["react", "react-dom", "react-router-dom"]` | Prevents two React instances from being bundled when `apps/web` and `packages/ui` resolve different versions in pnpm. The classic "Invalid hook call" runtime error and a hidden 30+ MB heap duplicate. | `vite.config.ts` |
 
-`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.
+`NODE_OPTIONS` is **not** required under Vite — V8's default heap is fine
+for a 250–500 MB process. The Next-era `--max-old-space-size=6144` was
+fighting Turbopack's mmap'd FS cache; that whole class of problem is gone.
 
-- **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.
+## 2. Don't run two Vite servers against the same checkout
 
-## 3. Turbopack file-system cache (Next ≥ 16.1)
+A single `vite` process (Vite + the React plugin + Tailwind plugin)
+stabilizes at ~280 MB RSS once the route tree is warm. Two parallel
+servers stabilize at ~560 MB, three at ~840 MB — they don't share dep
+caches across processes.
 
-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 `predev` hook (`exxat-ui dev-guard`) detects an already-running
+`vite` instance under the same checkout and exits with a friendly
+message instead of starting a second one. Unconditionally honour it —
+do not bypass with `--no-predev` unless you've explicitly killed the
+other server.
 
-**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:
+To check what's running:
 
 ```bash
-du -sh .next
-# 3.2G  .next
+ps aux | grep -E "vite/bin/vite" | grep -v grep
 ```
 
-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:
+If you legitimately need two designer servers (e.g. comparing two
+branches side-by-side), use the dedicated alternate ports:
 
 ```bash
-pnpm clean:cache  # removes .next/dev/cache and .next/dev/trace
-pnpm dev:fresh    # bust + restart in one command
+pnpm dev          # http://localhost:3000
+pnpm dev:3001     # http://localhost:3001
+pnpm dev:3005     # http://localhost:3005
 ```
 
-The `dev:fresh` script is the right move whenever:
+These all share the same `dev-guard` so a third can't sneak in.
 
-- 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.
+## 3. Clearing the dep cache
 
-For a full nuke (build artifacts too):
+Vite caches pre-bundled deps under `node_modules/.vite/`. The cache is
+small (10–50 MB typical) but can grow stale after major dependency
+changes:
 
 ```bash
-pnpm clean
+pnpm clean:cache    # removes node_modules/.vite
+pnpm dev:fresh      # clean + restart
 ```
 
-`turbopack.memoryLimit` (knob #2) prevents the cache from blowing past 4 GiB of RAM even when the on-disk cache is large.
+Bust the cache when:
 
-## 4. Don't run two dev servers at the same time
+- A `pnpm install` changed `@exxatdesignux/ui` or any framework dep.
+- HMR starts skipping updates.
+- The browser console shows `[vite] (client) Re-optimizing dependencies` looping repeatedly.
 
-**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:
+For a full nuke (build artefacts too):
 
 ```bash
-ps aux | grep next-server | grep -v grep
-lsof -p <pid> | grep '\.next/dev/cache' | head -5  # which checkout owns it
+pnpm clean
 ```
 
-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
+## 4. Diagnose a memory regression
 
-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:
+When dev RSS climbs past 1 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
+# Check the boring stuff first
+ps aux | grep -E "vite" | grep -v grep | wc -l    # > 1 = duplicate dev servers
+du -sh node_modules/.vite                          # > 200 MB = bust the cache
+
+# Then check the active dep graph
+# Vite ships a built-in module-graph endpoint at /__inspect/ when
+# `vite-plugin-inspect` is installed; not currently wired in apps/web,
+# but a one-line `pnpm add -D vite-plugin-inspect` plus the plugin
+# import gives instant visibility for one-off investigations.
 ```
 
-Common culprits and their signatures:
+Common culprits:
 
 | 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 |
+| Two or more `vite` processes in `ps` | Dual dev server across checkouts | Stop the duplicate (see §2) |
+| `[vite] (client) Re-optimizing dependencies` looping every save | Dep cache invalidated on every change | `pnpm clean:cache && pnpm dev` |
+| Initial paint + first navigation feel slow but steady-state is fine | `optimizeDeps.include` is missing a hot dep | Add it to the list (knob 2) |
+| `Invalid hook call` runtime error | Two React copies in the bundle | Verify `dedupe` (knob 4) is set |
+| Heap grows on every HMR cycle, never shrinks | Module-level `Map` / `Set` that never gets cleared | Move to request-scoped storage |
+| tsserver alone is > 1.5 GB | TS strict + large lib check | `skipLibCheck: true` is already on; drop `allowJs` if not needed |
 
-## 7. Node 24 features we leverage
+## 5. 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
+- **V8 13.6 with Maglev JIT default-on** — faster startup, lower base
+  heap. Steady-state RSS for the Vite 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.
+- **`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`.
+- **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.
+
+## 6. 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. |
+| Bypassing `dev-guard` with `npm run dev --ignore-scripts` | Defeats the only protection against parallel servers. The `predev` hook is the cheapest possible safety net. |
+| Adding `nodemon` on top of `vite` | Vite has its own watcher; nodemon doubles the file-system event handlers. |
+| Importing `@exxatdesignux/ui` from the package root for every icon | Bypasses tree-shaking. Always import from the leaf path the DS exposes (e.g. `@exxatdesignux/ui/components/button`). |
 | 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.
+| Running `vite dev` with `--inspect` in normal dev | Allocates an extra inspector arena per process (~200 MB). Use only when actively debugging. |
+
+## 7. Upgrading an existing customer app to the Vite stack
+
+If your customer repo was scaffolded before `@exxatdesignux/ui@0.5.10`
+on the legacy Next stack, the migration path is the one this repo took
+in PR-1 → PR-6:
+
+1. **PR-1**: add `dev-guard` predev hook + bump Node engines to 24.
+2. **PR-2**: scaffold `template-vite/` alongside Next; designers move first.
+3. **PR-3**: set up `vite.config.ts` with `next/*` aliases pointing at
+   shims so existing component code keeps compiling.
+4. **PR-4**: smoke `pnpm build:vite` and fix any cross-stack env vars
+   (`process.env.NEXT_PUBLIC_*` ⇄ `import.meta.env.VITE_*`).
+5. **PR-5**: flip `pnpm dev` from Next to Vite; demote Next variants to `:next` slot.
+6. **PR-6**: codemod all `next/*` imports to `react-router-dom` direct,
+   delete `app/`, `next.config.mjs`, `next-env.d.ts`, the shim directory,
+   and remove `next` + `eslint-config-next` + `@next/bundle-analyzer`
+   from `package.json`.
+
+A reusable codemod for step 6 lives in commit `d16ec77` under
+`apps/web/scripts/codemod-next-to-rr.mjs` (deleted in the same commit
+to keep the tree clean — pull it from git history if you need it).
+
+The full sequence took roughly an afternoon of focused work end-to-end
+on the canonical app. For repos with significant Next-only surfaces
+(RSC server actions, `next/image` heavy use, custom Next middleware),
+expect to spend additional time on those specific subsystems — they
+were not present in `apps/web`.
 
 ## 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)
+- [Vite — Performance](https://vite.dev/guide/performance.html)
 - [Node.js — Diagnostics](https://nodejs.org/api/cli.html#--heap-profheap_dir)
 - [V8 — Maglev](https://v8.dev/blog/maglev)