@exxatdesignux/ui 0.5.11 → 0.5.12

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)

package/consumer-extras/scripts/dev-guard.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/**
+ * dev-guard — catches the #1 cause of memory exhaustion before a second
+ *             dev server boots and lifts total system RSS unnecessarily.
+ *
+ * Detects Vite parents under the same `pnpm dev` lineage. A single Vite
+ * dev server stabilizes at ~250–500 MB; stacking two doubles total RSS,
+ * confuses HMR (two ports, two websockets), and creates "which one am I
+ * actually viewing?" mistakes when designers compare branches.
+ *
+ * (History: until PR-6 (May 2026) this guard also detected `next-server`
+ * parents because `apps/web` ran on Next + Turbopack. After Next was
+ * removed, the Next branch became dead code — this version is Vite-only.)
+ *
+ * Run as `predev` hook (or any time you want to verify environment health):
+ *   "predev": "exxat-ui dev-guard"
+ *
+ * Behavior:
+ *   - Lists every running `vite` parent.
+ *   - Exits 0 silently if zero or one is found (the one is *us* — fine).
+ *   - Prints a guided warning if 2+ are found, names the cwd of each,
+ *     and asks the user whether to abort or continue.
+ *   - In CI (`CI=true`) or with `--quiet`, exits 0 without prompting.
+ *
+ * Tested against macOS / Linux. Windows users: PowerShell `Get-Process` would
+ * need a separate branch; not implemented yet because the team is mac/linux.
+ */
+
+import { execFileSync } from "node:child_process"
+import { createInterface } from "node:readline/promises"
+
+const QUIET = process.argv.includes("--quiet") || process.env.CI === "true"
+
+/** @typedef {{ pid: number, cwd: string, rss: number }} ViteProc */
+
+/** @returns {ViteProc[]} */
+function listDevServers() {
+  let out = ""
+  try {
+    out = execFileSync(
+      "ps",
+      ["-axo", "pid=,rss=,command="],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    )
+  } catch {
+    // ps unavailable (very unusual). Fail open — better to let dev start.
+    return []
+  }
+
+  const matches = []
+  for (const line of out.split("\n")) {
+    const m = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/)
+    if (!m) continue
+    const [, pid, rss, command] = m
+
+    // Vite — bin/vite.js or `node ... vite ...` parents. Skip vitest, esbuild
+    // children, vite preview workers. We require the literal `vite` token
+    // either at end of path (.../bin/vite[.js]) or as a subcommand argv.
+    const isViteDev =
+      /(\/vite(\.js|\.mjs)?|[\s/]vite\s)\b/.test(command) &&
+      !/\bvitest\b/.test(command) &&
+      !/\bvite\s+preview\b/.test(command) &&
+      !/\besbuild\b/.test(command)
+
+    if (!isViteDev) continue
+    matches.push({
+      pid: Number(pid),
+      cwd: cwdOfPid(Number(pid)) ?? "(cwd unknown)",
+      rss: Number(rss), // KB
+    })
+  }
+  return matches
+}
+
+/** Best-effort cwd lookup. macOS has lsof; Linux has /proc/<pid>/cwd. */
+function cwdOfPid(pid) {
+  try {
+    if (process.platform === "darwin") {
+      const out = execFileSync("lsof", ["-p", String(pid), "-d", "cwd", "-Fn"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+      const line = out.split("\n").find(l => l.startsWith("n"))
+      return line ? line.slice(1) : null
+    }
+    if (process.platform === "linux") {
+      const out = execFileSync("readlink", ["-f", `/proc/${pid}/cwd`], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      })
+      return out.trim() || null
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+function fmtMB(kb) {
+  return (kb / 1024).toFixed(0) + " MB"
+}
+
+async function main() {
+  const servers = listDevServers()
+  if (servers.length <= 1) {
+    if (!QUIET) {
+      console.log(
+        servers.length === 0
+          ? "[dev-guard] No other dev server running. Safe to start."
+          : `[dev-guard] One vite already running (pid ${servers[0].pid}, ${fmtMB(servers[0].rss)}). Reusing it.`,
+      )
+    }
+    process.exit(0)
+  }
+
+  // Two or more — this is the bad path.
+  console.error("")
+  console.error("⚠  dev-guard: multiple Vite dev-server processes detected.")
+  console.error("")
+  console.error("Two parallel Vite dev servers stabilize at ~500–800 MB combined")
+  console.error("and confuse HMR (two ports, two websockets, components from two")
+  console.error("workspace roots). Stop the one you're not actively touching.")
+  console.error("")
+  for (const s of servers) {
+    console.error(
+      `  pid ${String(s.pid).padEnd(6)}  ${fmtMB(s.rss).padEnd(8)}  ${s.cwd}`,
+    )
+  }
+  console.error("")
+  console.error("Recommended: stop the one you're not actively touching.")
+  console.error("  • macOS / Linux: kill <pid>")
+  console.error("  • pm2 daemon:    pm2 stop exxat-ds (or pm2 delete exxat-ds)")
+  console.error("")
+
+  if (QUIET) {
+    // CI / quiet mode — don't block, just warn.
+    process.exit(0)
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  const ans = (await rl.question("Continue starting another dev server anyway? [y/N] ")).trim().toLowerCase()
+  rl.close()
+
+  if (ans === "y" || ans === "yes") {
+    console.error("[dev-guard] Continuing.")
+    process.exit(0)
+  }
+  console.error("[dev-guard] Aborted. Stop the other server, then re-run dev.")
+  process.exit(1)
+}
+
+main().catch(err => {
+  // Never let a guard bug block dev. Log and pass through.
+  console.error("[dev-guard] internal error, allowing dev to start:", err?.message ?? err)
+  process.exit(0)
+})

package/consumer-extras/templates/README.md

@@ -0,0 +1,23 @@
+# Exxat DS — templates
+
+Markdown templates the agent fills in (or copies into a PR / docs folder) at
+specific points of a design task.
+
+| File | When the agent emits it |
+|------|------------------------|
+| `handoff.md` | After every design task that creates or rebuilds a surface, before the engineer wires real data. Source of truth for the design → engineering handoff. |
+
+These ship via `@exxatdesignux/ui` and are written into the consumer repo at:
+
+```
+docs/exxat-ds/templates/<file>
+```
+
+…by `exxat-ui sync-extras`.
+
+The agent locates the template via the `exxat-ux-discovery-protocol` rule
+(see `.cursor/rules/exxat-ux-discovery-protocol.mdc`) and fills it in as
+the closing artifact of a build.
+
+Engineers do not edit these templates by hand. They open the filled-in copy
+attached to a PR / saved at `docs/exxat-ds/handoff/<surface-slug>.md`.