@exxatdesignux/ui 0.5.9 → 0.5.11

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.5.11
+
+### Patch Changes
+
+- **Senior-UX discovery gate now actually gates.** The 0.5.6 senior-UX layer was missing two enforcement teeth that made it skippable in practice — confirmed by a real-world failure where the agent was prompted "create new page of student details page instead of what we have currently" and immediately wrote 4 files without posting a brief. The fix tightens three documents:
+  - **`.cursor/rules/exxat-ux-discovery-protocol.mdc`** — gains a literal **`STOP — read before you write any file`** banner before the H1, an explicit fires-on / does-not-fire-on table (rebuild / redesign / replace / "instead of what we have" / "from scratch" all fire), and a new **MUST #0**: *"Output the brief, then WAIT. Do not bundle the brief and the first file edit in the same turn. After posting the brief, end your turn with 'Ready to build — confirm or edit.' Resume only on the user's next message."* Adds an explicit MUST NOT for "Skip the brief because the prompt sounds like a refactor."
+  - **`.cursor/skills/exxat-senior-ux/SKILL.md`** — description string now lists the trigger verbs that previously slipped through (`rebuild`, `redesign`, `replace`, `redo`, `refresh`, `modernize`, `re-imagine`, `"make a new version"`, `"instead of what we have"`, `"from scratch"`) so Cursor's skill auto-discovery picks up refactor-shaped prompts. Adds a new **Hard gate** section under "When to load" and restructures the five-step protocol as **sequential checkpoints** with **step 3 (Synthesis) ending the turn** — the user's reply is the green light to step 4 (Build).
+  - **`.cursor/rules/exxat-ds-agents.mdc` Top-of-stack** — renamed the brief instruction from a passive bullet to a bold **"Brief-before-code is a CHECKPOINT, not a preamble"** sub-section that lists the protocol as three numbered actions and ends with: *"If your next tool call would be `write_file` / `str_replace` / `create_file` and you have not posted a brief + received user confirmation, you are violating the protocol. Stop, post the brief, end the turn."*
+- **Why it failed silently before:** the rule's trigger language was "**new** route, page, template, wizard" — the agent reading "create new page of student details page **instead of what we have currently**" semantically parsed "instead of what we have" as a refactor of an existing route, so the gate didn't fire. The MUST list also said "before writing files" which the agent could satisfy by writing the brief + 200 lines of code in the same turn — not a checkpoint.
+- **Consumer impact:** `npx exxat-ui sync-extras` overwrites `.cursor/rules/exxat-ux-discovery-protocol.mdc`, `.cursor/rules/exxat-ds-agents.mdc`, and `.cursor/skills/exxat-senior-ux/SKILL.md` with the tightened versions. No code changes in the UI library; no app routes are modified.
+
+## 0.5.10
+
+### Patch Changes
+
+- **Turbopack memory cap + cache-bust scripts.** The Next 16.1+ Turbopack file-system cache (default-on) was writing 800+ `.meta` files per process and growing `.next/` to **3+ GB on disk**, which was then mmap'd back into RSS — adding several GB of resident memory per `next-server` on top of what 0.5.9 already capped. Three additions to the scaffolded `template/`:
+  - **`turbopack: { memoryLimit: 4 * 1024 * 1024 * 1024 }`** in `next.config.mjs` (top-level, **not** under `experimental` — that key was removed in Next 16). Hard 4 GiB cap on the Turbopack worker; prevents the unbounded growth observed when the FS cache and module graph accumulate over a long dev session.
+  - **`pnpm clean`** (`rm -rf .next`) and **`pnpm clean:cache`** (`rm -rf .next/dev/cache .next/dev/trace .next/diagnostics`) — one-command cache bust when `.next` crosses ~2 GB. The FS cache is kept enabled (cold start is ~15s without it) but is now explicitly disposable.
+  - **`pnpm dev:fresh`** (`pnpm clean:cache && pnpm dev`) — bust + restart in a single command. Use after a major dependency upgrade or whenever HMR starts skipping updates.
+- **`perf-memory-pattern.md` gains two new sections:**
+  - **§3 Turbopack file-system cache** explains the trade-off, when to bust, and why disabling the cache outright is the wrong call.
+  - **§4 Don't run two dev servers at the same time** — the #1 cause of memory exhaustion in practice. Two checkouts of the same monorepo (`DS_Workspace/` + `Exxat-DS-Workspace/`), or a customer app + `apps/web` running simultaneously, each carry their own ~2 GB of caches and don't share anything. Includes a `ps` / `lsof` diagnostic table for identifying which checkout owns which `next-server` lineage.
+- **`perf-memory-pattern.md` §6 diagnose table** now leads with the boring checks (`du -sh .next`, `ps aux | grep next-server | wc -l`, `lsof -p <pid> | wc -l`) before suggesting a heap profile — most "high RSS" reports are dual-server or stale-cache, not a real leak.
+- **`consumer-upgrade-checklist.md` §4** gains a `≥ 0.5.10` block listing the three new knobs and the one-time `pnpm clean && pnpm dev` step that customer apps need after upgrading (pre-0.5.10 cache files were written without the memory cap).
+
 ## 0.5.9
 
 ### Patch Changes

package/consumer-extras/cursor-rules/exxat-ds-agents.mdc

@@ -15,12 +15,22 @@ Before implementing or reviewing **list / table / board / dashboard / data-heavy
 
 **`.cursor/skills/exxat-senior-ux/SKILL.md`** is the persona every other rule and skill is downstream of. It defines the **five-step protocol** (Discovery → Research → Synthesis → Build → Audit), the **brief format**, and the **push-back triggers**. Pair with:
 
-- **`.cursor/rules/exxat-ux-discovery-protocol.mdc`** — brief-before-code gate + question bank per surface type.
+- **`.cursor/rules/exxat-ux-discovery-protocol.mdc`** — brief-before-code gate + question bank per surface type. **`alwaysApply: true`** — fires on every design task automatically.
 - **`.cursor/rules/exxat-ux-principles.mdc`** — 20 principles (P1–P20) split into **always-follow (P1–P8)** and **default-follow with stated reason (P9–P20)**. Every deviation MUST be named in the design brief.
 - **`apps/web/docs/modern-saas-patterns.md`** — the 12 modern SaaS patterns (M1–M12) the DS works against; cite by `(Mx)` codes.
 - **`apps/web/docs/jobs/`** — canonical references per **job-to-be-done** (start with `record-detail.md`). If no job doc matches, write one.
 
-On any **new** route / page / hub / detail / wizard / settings / dashboard / overlay, output a **design brief** in chat BEFORE writing files. On trivial edits (copy tweaks, single-class restyles, bug fixes), skip the brief.
+### Brief-before-code is a CHECKPOINT, not a preamble
+
+On any task that **decides what a surface should be** — including *new* pages **and** *rebuilds / redesigns / replacements of existing pages* — the protocol is:
+
+1. **Post the brief in chat. END THE TURN with "Ready to build — confirm or edit."**
+2. **Wait for the user's next message.** Silence is not consent until the next user reply arrives.
+3. **Only then** call code-mutating tools.
+
+Treat **"rebuild X"**, **"redesign X"**, **"replace what we have"**, **"make a new version of X"**, **"from scratch"**, and **"instead of what we currently have"** identically to "create new X" — all of them make a design decision, all of them require the brief checkpoint. The only exempt edits are trivial ones (copy tweaks, single-class restyles, bug fixes, dep bumps, ESLint passes, adding a column to an existing `HubTable` without changing IA).
+
+If your next tool call would be `write_file` / `str_replace` / `create_file` and you have not posted a brief + received user confirmation, **you are violating the protocol**. Stop, post the brief, end the turn.
 
 **Reviewing existing work?** Load **`.cursor/skills/exxat-ux-audit/SKILL.md`** instead. It runs an EXISTING surface (route / file / component / customer-app path / screenshot) through the same P1–P20 / M1–M12 rubric and outputs a **Blocker / Issue / Nit** findings report with code citations, a fix plan, and an offer to auto-apply text-only Blocker fixes. Triggers: "audit X", "review the X page", "is this following DS?", "what's wrong with this screen", "do a UX review", or a route URL with a symptom.
 

package/consumer-extras/cursor-rules/exxat-ux-discovery-protocol.mdc

@@ -1,25 +1,72 @@
 ---
-description: Exxat DS — output a design brief before writing files for any new surface; question bank by surface type
+description: Exxat DS — STOP before code on any surface design (new, rebuild, redesign, replace); output a design brief and WAIT for user go-ahead
 alwaysApply: true
 ---
 
 # Exxat DS — UX discovery protocol
 
-On any task that creates a **new route, page, template, wizard, or
-significant component**, the assistant MUST output a **design brief in chat**
-BEFORE writing files. Brief format is defined in
-`.cursor/skills/exxat-senior-ux/SKILL.md` §3.
+## STOP — read before you write any file
+
+If the user's prompt asks you to **design, create, build, rebuild, redesign,
+replace, redo, refresh, modernize, re-imagine, or "make a new version of"**
+any **page, route, screen, hub, detail view, wizard, settings section,
+dashboard, dialog, sheet, drawer, panel, layout, or significant component**:
+
+1. **Do NOT write code, do NOT edit files, do NOT call edit tools yet.**
+2. **Output the design brief** (template below) in chat.
+3. **Wait for the user to reply** with `yes` / `proceed` / `ship it` / edits.
+4. **Only then** move to implementation.
+
+If your next tool call would be `write_file`, `str_replace`, `create_file`,
+or any code-mutating action **and** you have not posted a brief and received
+go-ahead, you are violating this rule. **Stop and post the brief.**
+
+## When this gate fires (and when it doesn't)
+
+This gate fires on **any task that decides what a surface should look like
+or how it works** — whether the surface exists today or not. Treat
+"replace what we have" and "create from scratch" identically — both need a
+brief, because both make a design decision.
+
+**Fires (brief required):**
+
+- "Create a new student detail page."
+- "Rebuild the dashboard."
+- "Redesign the settings screen instead of what we have."
+- "Make a new version of the placements table."
+- "Replace the current onboarding flow."
+- "Build a wizard for adding a site."
+- "Design a sheet for inviting collaborators."
+- User attaches a screenshot / mockup / Figma link and asks to "build this".
+
+**Does NOT fire (brief not required, edit freely):**
+
+- Single-class restyle of an existing surface that already follows DS rules.
+- Copy / label edits.
+- Bug fixes (a11y violation, broken state, wrong data).
+- Dependency bumps, ESLint passes, type fixes, test-only changes.
+- Adding a new column / filter to an *existing* `HubTable` that doesn't
+  change the page's IA.
+
+When in doubt, ask: **"Am I deciding what this surface should be?"** Yes →
+brief. No → edit.
 
 ## MUST
 
-1. **No code without a brief.** New surfaces require the brief. Trivial edits
-   to existing surfaces (copy tweak, single-class change, bug fix, refactor)
-   are exempt.
+0. **Output the brief, then WAIT.** The brief is a checkpoint, not a
+   preamble. Do not bundle the brief and the first file edit in the same
+   turn. After posting the brief, end your turn with an explicit
+   "Ready to build — confirm or edit." prompt. Resume only on the user's
+   next message.
+1. **No code without a confirmed brief.** "Confirmed" means the user wrote
+   `yes`, `proceed`, `ship it`, `LGTM`, `build it`, accepted edits, or asked
+   a follow-up that implies acceptance. Silence is not consent.
 2. **Cite a reference.** Every brief names **one repo reference** + **two
-   modern SaaS analogues** (Linear / Notion / Stripe / Figma / Vercel / etc.)
-   that solve the same **job-to-be-done**. Cite the SaaS analogues by
-   product name + pattern codes from
-   `apps/web/docs/modern-saas-patterns.md` (e.g. `Linear issue detail (M1, M4, M7)`).
+   modern SaaS analogues** (Linear / Notion / Stripe / Figma / Vercel /
+   Linear / Airtable / Coda / Height / etc.) that solve the same
+   **job-to-be-done**. Cite the SaaS analogues by product name + pattern
+   codes from `apps/web/docs/modern-saas-patterns.md` (e.g.
+   `Linear issue detail (M1, M4, M7)`).
 3. **Name principles + breaks.** Brief lists the principles applied
    (`exxat-ux-principles.mdc`) and any deviations with one-sentence reasons.
    **Never-break** principles (P1–P8) cannot be deviated from.
@@ -30,6 +77,11 @@ BEFORE writing files. Brief format is defined in
 
 ## MUST NOT
 
+- **Skip the brief because the prompt sounds like a refactor.** "Rebuild",
+  "redesign", "replace", "instead of what we have", and "from scratch" are
+  design decisions, not refactors. Brief required.
+- **Post a brief and then write 8 files in the same turn.** That's not a
+  brief — that's a press release. End the turn after the brief.
 - Generate files before the brief.
 - Ask more than **3** questions in one batch.
 - Ask questions whose answer is already in the prompt, the file tree, or

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/consumer-upgrade-checklist.md

@@ -30,7 +30,7 @@ Use it when you need to know **what files exist**, **how shims re-export** `@exx
 - Keep **`@exxatdesignux/ui`** on the same semver your team tested; prefer explicit **`^x.y.z`** or pinned **`x.y.z`**.
 - Match **`engines.node`** in your app to the value declared in **`node_modules/@exxatdesignux/ui/package.json`** (see CHANGELOG if it changed).
 - **≥ 0.5.3:** Remove **`vaul`** from your app `package.json` and delete any `components/ui/drawer.tsx` shim — side panels use **`Sheet`** only (**`.cursor/rules/exxat-no-vaul.mdc`**).
-- **≥ 0.5.9:** Bump to **Node 24** (LTS-track) and apply the dev-memory tuning. The template ships these by default; existing apps need a one-time copy:
+- **≥ 0.5.9:** Bump to **Node 24** (LTS-track) and apply the dev-memory tuning. The template ships these by default; existing apps need a one-time copy. *(0.5.10 adds the Turbopack cap below; apply both together.)*
 
   | What | Where | Effect |
   |------|-------|--------|
@@ -44,7 +44,17 @@ Use it when you need to know **what files exist**, **how shims re-export** `@exx
   | `env: { NODE_OPTIONS, NEXT_TELEMETRY_DISABLED }` + `max_memory_restart: "7G"` | `ecosystem.config.cjs` (if using pm2) | Daemon recycles before macOS swaps |
   | New `pnpm dev:profile` script | `package.json` | `--heap-prof` + `--cpu-prof` snapshots dropped into `.next/diagnostics/` |
 
-  Full rationale + diagnostics in **`docs/exxat-ds/perf-memory-pattern.md`** (after `sync-extras`) or **[`apps/web/docs/perf-memory-pattern.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/perf-memory-pattern.md)**.
+- **≥ 0.5.10:** Cap Turbopack and add cache-bust scripts. The dev FS cache is enabled by default in Next 16.1 — without these knobs it grows to 2–3 GB on disk and mmaps the same back into RSS:
+
+  | What | Where | Effect |
+  |------|-------|--------|
+  | `turbopack: { memoryLimit: 4 * 1024 * 1024 * 1024 }` | `next.config.mjs` (top-level, **not** under `experimental`) | Hard 4 GiB cap on the Turbopack worker — prevents the unbounded cache → RSS growth |
+  | New `pnpm clean` (`rm -rf .next`) and `pnpm clean:cache` (`rm -rf .next/dev/cache .next/dev/trace .next/diagnostics`) | `package.json` `scripts` | One-command cache bust when `.next` > 2 GB |
+  | New `pnpm dev:fresh` (`pnpm clean:cache && pnpm dev`) | `package.json` `scripts` | Bust + restart in one shot |
+
+  **Run `pnpm clean && pnpm dev` once after the upgrade.** Pre-0.5.10 cache files were written without the memory cap and may carry stale mmap layouts.
+
+  Full rationale + diagnostics in **`docs/exxat-ds/perf-memory-pattern.md`** (after `sync-extras`) or **[`apps/web/docs/perf-memory-pattern.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/perf-memory-pattern.md)** — especially §3 (Turbopack FS cache) and §4 (don't run two dev servers).
 
 ## 5. Consumer UI audit (after sync-extras)
 

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

@@ -9,15 +9,16 @@ 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 five knobs
+## 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 | `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` |
-| 3 | `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` |
-| 4 | `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` |
-| 5 | `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 | `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
 
@@ -33,7 +34,61 @@ processes inherit and honour it.
 - **VS Code / Cursor terminals:** these inherit the parent shell env, so the
   `package.json` script is enough.
 
-## 3. Two `next-server` processes is normal
+## 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:
 
@@ -45,12 +100,17 @@ 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.
 
-## 4. Diagnose a memory regression
+## 6. Diagnose a memory regression
 
 When dev RSS climbs past 4 GB and stays there:
 
 ```bash
-# Profile a 60s window and write heap snapshots to .next/diagnostics/
+# 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"
@@ -59,15 +119,18 @@ ls -lt .next/diagnostics | head -3
 
 Common culprits and their signatures:
 
-| Symptom in the heap snapshot | Likely cause | Fix |
-|------------------------------|--------------|-----|
-| Many copies of `lucide-react.js` / `recharts.js` retained | Missing entry in `optimizePackageImports` | Add the package to the list (knob 3) |
-| Compiled chunks for routes you never visited | `preloadEntriesOnStart` is `true` | Set to `false` (knob 2) |
-| Heap grows on every HMR cycle, never shrinks | RSC HMR cache + import.meta.hot leak | `experimental.serverComponentsHmrCache: false` (try only if knob 2 is already on) |
+| 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 |
 
-## 5. Node 24 features we leverage
+## 7. Node 24 features we leverage
 
 Node 24 (LTS-track) is required by `engines.node` in `package.json` and
 pinned in `.nvmrc`. Specifically:
@@ -93,7 +156,7 @@ pinned in `.nvmrc`. Specifically:
 - **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
+## 8. Anti-patterns
 
 | Anti-pattern | Why it's wrong |
 |--------------|----------------|
@@ -104,27 +167,35 @@ pinned in `.nvmrc`. Specifically:
 | 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. |
 
-## 7. Upgrading an existing customer app
+## 9. Upgrading an existing customer app
 
-If your app was scaffolded before `@exxatdesignux/ui@0.5.9`, copy the diffs
+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` script.
-3. `next.config.mjs` — add the expanded `experimental.optimizePackageImports`
-   array, `experimental.preloadEntriesOnStart: false`,
-   `experimental.webpackMemoryOptimizations: true`, and the `onDemandEntries`
-   block.
+   `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.
+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
 

package/dist/hooks/use-app-theme.d.ts

@@ -10,7 +10,7 @@ declare function useAppTheme(): {
     brand: Brand;
     setBrand: (b: Brand) => void;
     /** The user's preference: "system" | "normal" | "high" | "windows" */
-    contrastPref: "system" | "normal" | "high" | "windows";
+    contrastPref: "normal" | "high" | "system" | "windows";
     /** The resolved contrast mode actually applied to the DOM. */
     contrast: ContrastMode;
     /** Set the contrast preference. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "license": "UNLICENSED",
   "author": "Exxat Design",

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

@@ -9,15 +9,16 @@ 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 five knobs
+## 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 | `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` |
-| 3 | `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` |
-| 4 | `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` |
-| 5 | `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 | `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
 
@@ -33,7 +34,61 @@ processes inherit and honour it.
 - **VS Code / Cursor terminals:** these inherit the parent shell env, so the
   `package.json` script is enough.
 
-## 3. Two `next-server` processes is normal
+## 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:
 
@@ -45,12 +100,17 @@ 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.
 
-## 4. Diagnose a memory regression
+## 6. Diagnose a memory regression
 
 When dev RSS climbs past 4 GB and stays there:
 
 ```bash
-# Profile a 60s window and write heap snapshots to .next/diagnostics/
+# 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"
@@ -59,15 +119,18 @@ ls -lt .next/diagnostics | head -3
 
 Common culprits and their signatures:
 
-| Symptom in the heap snapshot | Likely cause | Fix |
-|------------------------------|--------------|-----|
-| Many copies of `lucide-react.js` / `recharts.js` retained | Missing entry in `optimizePackageImports` | Add the package to the list (knob 3) |
-| Compiled chunks for routes you never visited | `preloadEntriesOnStart` is `true` | Set to `false` (knob 2) |
-| Heap grows on every HMR cycle, never shrinks | RSC HMR cache + import.meta.hot leak | `experimental.serverComponentsHmrCache: false` (try only if knob 2 is already on) |
+| 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 |
 
-## 5. Node 24 features we leverage
+## 7. Node 24 features we leverage
 
 Node 24 (LTS-track) is required by `engines.node` in `package.json` and
 pinned in `.nvmrc`. Specifically:
@@ -93,7 +156,7 @@ pinned in `.nvmrc`. Specifically:
 - **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
+## 8. Anti-patterns
 
 | Anti-pattern | Why it's wrong |
 |--------------|----------------|
@@ -104,27 +167,35 @@ pinned in `.nvmrc`. Specifically:
 | 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. |
 
-## 7. Upgrading an existing customer app
+## 9. Upgrading an existing customer app
 
-If your app was scaffolded before `@exxatdesignux/ui@0.5.9`, copy the diffs
+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` script.
-3. `next.config.mjs` — add the expanded `experimental.optimizePackageImports`
-   array, `experimental.preloadEntriesOnStart: false`,
-   `experimental.webpackMemoryOptimizations: true`, and the `onDemandEntries`
-   block.
+   `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.
+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
 

package/template/next.config.mjs

@@ -153,6 +153,13 @@ const SECURITY_HEADERS = [
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   transpilePackages: ["@exxatdesignux/ui"],
+  // Hard cap on the Turbopack worker. Without this, the dev cache + module
+  // graph + mmap'd .meta files grow unbounded (we observed 3.2 GB on disk
+  // and 5+ GB RSS per process). 4 GiB is generous — Turbopack rarely needs
+  // more on apps with < ~1000 routes. See `docs/perf-memory-pattern.md` §6.
+  turbopack: {
+    memoryLimit: 4 * 1024 * 1024 * 1024,
+  },
   // Dev memory tuning — see `docs/perf-memory-pattern.md` for rationale.
   experimental: {
     // Tree-shake heavy barrel re-exports. Every package here was identified by

package/template/package.json

@@ -13,6 +13,9 @@
     "dev:3001": "NODE_OPTIONS='--max-old-space-size=6144 --max-semi-space-size=64' NEXT_TELEMETRY_DISABLED=1 next dev --turbopack -p 3001",
     "dev:3005": "NODE_OPTIONS='--max-old-space-size=6144 --max-semi-space-size=64' NEXT_TELEMETRY_DISABLED=1 next dev --turbopack -p 3005",
     "dev:profile": "NODE_OPTIONS='--max-old-space-size=6144 --heap-prof --heap-prof-interval=512000 --diagnostic-dir=./.next/diagnostics' NEXT_TELEMETRY_DISABLED=1 next dev --turbopack",
+    "dev:fresh": "pnpm clean:cache && pnpm dev",
+    "clean": "rm -rf .next",
+    "clean:cache": "rm -rf .next/dev/cache .next/dev/trace .next/diagnostics",
     "dev:daemon": "pm2 start ecosystem.config.cjs",
     "dev:daemon:stop": "pm2 stop exxat-ds",
     "dev:daemon:restart": "pm2 restart exxat-ds",