start-vibing-stacks 2.21.0 → 2.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/skills/debugging-patterns/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: debugging-patterns
-version: 1.0.0
+version: 1.1.0
+description: Universal debugging strategies plus the "Bundle, not Backend"
+  triage for silent wrong-component renders (HTTP 200, empty server logs,
+  wrong default export shipped). Pairs with `inertia-react` "Vite Build
+  Gotchas" section.
 ---
 
 # Debugging Patterns
@@ -34,6 +38,72 @@ node --inspect script.js
 DEBUG=* node script.js
 ```
 
+## Bundle, not Backend (silent wrong-component / wrong-output renders)
+
+> **When the server returns HTTP 200, server logs are empty, and the browser
+> still renders the wrong content — STOP debugging the server.** The bug is
+> in the bundle. This is the #1 source of "Sonnet runs in circles for 90
+> minutes" debugging sessions.
+
+### Symptoms that point to the bundle, not the server
+
+| Symptom | Why it implicates the bundle |
+|---|---|
+| HTTP 200 on every request, browser shows wrong content | Server is producing correct payload; client is misresolving it |
+| Empty server logs (Laravel/Node/Python) | No exception was thrown; backend is genuinely correct |
+| The wrong component/page/template is rendered | Default export of the loaded chunk is not the expected one |
+| Reverting the last `vite.config.js` / `webpack.config.js` / `rollup.config.js` change fixes it | Build graph is the locus |
+| Only happens after `npm run build` (dev works) | Production chunking heuristics differ from dev's per-file modules |
+| Different routes resolve to the same JS asset URL | Resolve-map collision in `import.meta.glob` / module federation |
+
+### Triage protocol (5 steps, ~3 minutes)
+
+1. **Confirm the payload** — DevTools → Network → click the HTML/XHR request
+   for the broken route → inspect the response. If the server-side identifier
+   (`component:` for Inertia, route name for Next.js RSC, etc.) is the EXPECTED
+   one, the server is correct. Move to step 2.
+2. **Find the JS chunk that loaded** — in the same Network tab, look at the
+   `.js` requests that fired after the page request. For SPA frameworks, one
+   of them is the page chunk. Note its URL/hash.
+3. **Inspect the chunk's `default` export** — open the chunk URL in a new tab,
+   `Ctrl+F` for `default:` / `export{` / `as default}`. Identify the actual
+   component name being exported.
+4. **Compare** — if (chunk's default export) ≠ (server's component identifier),
+   confirmed: the bug is in the bundle. Possible causes (in order of likelihood):
+   - `manualChunks` collided with an `entry` chunk (Rollup/Rolldown silently
+     dropped a group — see `inertia-react §Vite Build Gotchas`)
+   - Two files with the same default export name caused a hash reuse
+   - A barrel/re-export chain has the wrong file at the top
+   - Tree-shaking removed the expected export because it was only referenced
+     conditionally
+5. **Bisect on the build config** — revert the last commit that touched
+   `vite.config.*`, `rollup.config.*`, `webpack.config.*`, `next.config.*`,
+   `turbo.json`, or any chunking-related setting. If the bug disappears,
+   you've located it. Do NOT debug the server.
+
+### Common causes (multi-stack)
+
+| Stack | Pattern | Fix reference |
+|---|---|---|
+| Laravel + Inertia + Vite | Same module in `laravel.input[]` AND `Pages/**` glob | `inertia-react §Vite Build Gotchas` |
+| Next.js App Router | Server/Client component boundary mis-resolved by bundler split | Check `'use client'` placement, then `next.config.mjs` |
+| Module Federation | Remote chunk hash mismatch after redeploy | Force remote re-fetch, check `shared` deps versions |
+| Webpack 5 | `splitChunks.cacheGroups` overlap with `entry` | Same class of bug as Vite manualChunks |
+| esbuild | Two CJS modules with same `module.exports.default` deduped | Set `format: 'esm'` or use named exports |
+
+### Validators that catch the bug at build time
+
+If a `scripts/check-vite-manifest.mjs` exists in the project (shipped by
+`start-vibing-stacks` for PHP/Laravel projects), run it after every build:
+
+```bash
+node scripts/check-vite-manifest.mjs
+```
+
+It cross-references `laravel.input[]` against `import.meta.glob` patterns and
+fails the build if any module appears in both — which is the Laravel/Inertia
+specific shape of "Bundle, not Backend."
+
 ## Anti-Patterns
 
 | Don't | Do |
@@ -42,3 +112,6 @@ DEBUG=* node script.js
 | Fix symptom, not cause | Trace to root cause |
 | Skip writing test for fix | Always add regression test |
 | Leave debug code in commit | Clean before commit |
+| Debug the server when HTTP 200 + empty logs + wrong content | Triage as "Bundle, not Backend" — start from the chunk graph |
+| Trust that `manualChunks` / `splitChunks` always honors your grouping | Bundlers silently drop groups when they collide with entry chunks |
+| Move on after one `npm run build` succeeded | Run the manifest validator; bundlers don't warn on collision |

package/stacks/frontend/react-inertia/skills/inertia-react/SKILL.md

@@ -1,10 +1,13 @@
 ---
 name: inertia-react
-version: 2.0.0
+version: 2.1.0
 description: LEGACY skill — Inertia.js + React frontend integration with
   Laravel-rendered pages. Use ONLY in pre-existing Inertia projects. For NEW
   projects use the `react-api` frontend stack (`axios-laravel-api` +
-  `react-api-standards`) which decouples render from data fetching.
+  `react-api-standards`) which decouples render from data fetching. v2.1.0 adds
+  the "Vite Build Gotchas" section covering the `manualChunks` × entry-chunk
+  × `resolvePageComponent` glob interaction that produces silent
+  wrong-component renders (production post-mortem 2026-05).
 ---
 
 # Inertia.js + React Integration (LEGACY)
@@ -343,6 +346,138 @@ router.reload({ only: ['stats'] }); // Partial reload
 - Access shared props via `usePage().props`
 - `processing` boolean from `useForm` for button loading states
 
+## Vite Build Gotchas (Inertia-specific)
+
+> **Production post-mortem 2026-05.** Reverting/rebuilding `vite.config.js`
+> chunking in an Inertia + Laravel project can produce a **silent wrong-component
+> render** (Login renders HttpErrorPage with HTTP 200, no console errors, empty
+> Laravel logs). The bug lives in the bundle graph, not the server.
+
+### The three-way collision
+
+```
+laravel-vite-plugin       ┐
+  laravel({ input: [      │  Anything here becomes an ENTRY chunk.
+    '.../HttpErrorPage'   │  Rollup/Rolldown ALWAYS prioritizes entries.
+  ]})                     ┘
+
+@inertiajs/react          ┐
+  resolvePageComponent(   │  Builds a STATIC resolve-map at build time
+    `./Pages/${name}.jsx`,│  via import.meta.glob. The map points each
+    import.meta.glob(     │  Page path to whatever chunk hash Rollup
+      './Pages/**/*.jsx') │  ended up putting that module in.
+  )                       ┘
+
+build.rollupOptions       ┐
+  .manualChunks(id) {     │  This is ADVISORY. Returning 'pages-auth' for
+    if (/Auth\//.test(id))│  a module that is ALSO an entry has NO EFFECT.
+      return 'pages-auth' │  The grouping is silently dropped — no warning.
+  }                       ┘
+```
+
+When the same module (e.g. `HttpErrorPage.jsx`) is:
+
+1. listed in `laravel.input[]` (because `app.blade.php` has a direct
+   `@vite('resources/js/Pages/.../HttpErrorPage.jsx')` for the error layout), AND
+2. caught by `manualChunks` returning `'pages-auth'`,
+
+…Rollup/Rolldown creates a **standalone entry chunk** containing ONLY
+`HttpErrorPage`. The `pages-auth` group is reduced to that one module, and the
+`import.meta.glob` resolve-map points **every sibling** (`Login`, `Register`,
+`ForgotPassword`, …) at that same chunk hash. The siblings' code is discarded.
+
+Symptom: `Inertia::render('Auth/Login', …)` returns 200 OK with a valid Inertia
+payload. The browser fetches the chunk listed in the resolve-map. That chunk's
+`default` export is `HttpErrorPage`. The error page is rendered. Backend is
+perfect; frontend lies.
+
+### Rule 1 — Never duplicate a module between `laravel.input` and the glob
+
+If a page MUST be referenced directly by `@vite()` in a blade file (typical
+cases: error pages, mail templates rendered server-side, OG/share-image
+renderers), it becomes an entry chunk. You have two options:
+
+- **A. Exclude it from the glob** — change `resolvePageComponent`'s glob to
+  ignore that path, OR
+- **B. Short-circuit `manualChunks` BEFORE any grouping rule** so the entry
+  chunk's identity is preserved without polluting a group.
+
+Pattern B (preferred — works without touching the Inertia bootstrap):
+
+```js
+// vite.config.js
+build: {
+    rollupOptions: {
+        output: {
+            manualChunks(id) {
+                if (!id.includes('/resources/js/Pages/')) return;
+
+                // Entry chunks referenced directly by @vite() in blade MUST
+                // return undefined here — BEFORE any grouping rule.
+                // Otherwise the group is collapsed into the entry and the
+                // import.meta.glob resolve-map points siblings at the wrong
+                // chunk hash. See "Vite Build Gotchas" in inertia-react skill.
+                if (id.includes('/Pages/OtherPages/HttpErrorPage')) return;
+
+                if (id.includes('/Pages/Auth/') || id.includes('/Pages/OtherPages/')) {
+                    return 'pages-auth';
+                }
+                if (id.includes('/Pages/Dashboard/')) {
+                    return 'pages-dashboard';
+                }
+            },
+        },
+    },
+},
+```
+
+### Rule 2 — `manualChunks` is advisory; entries always win
+
+There is no warning when Rollup/Rolldown ignores a `manualChunks` return value
+for an entry module. The validation MUST be done out-of-band on `manifest.json`
+after every build (see `scripts/check-vite-manifest.mjs` shipped by
+`start-vibing-stacks`).
+
+### Rule 3 — Validate `public/build/manifest.json` after every `vite build`
+
+```bash
+# 1. Quick eyeball
+cat public/build/manifest.json | jq 'keys'
+
+# 2. Automated (shipped script)
+node scripts/check-vite-manifest.mjs public/build/manifest.json vite.config.js
+```
+
+The script cross-references `laravel.input[]` against the `Pages/**` glob and
+fails (non-zero exit) on any collision.
+
+### Rule 4 — Smoke-test after any `vite.config.js` change touching `build`
+
+Three-step browser check for one critical route per page group:
+
+1. DevTools → Network → click the Inertia XHR → read the `component:` field
+   in the JSON response.
+2. Click the JS asset request that followed → open the resolved chunk URL.
+3. Search for `default:` / `export{ ... as default}` in that chunk. The
+   component name MUST match the server's `component:`.
+
+If they don't match, the bug is in the chunk graph. Revert the last
+`vite.config.js` change before debugging anything else.
+
+### Why Sonnet (and humans) get stuck on this class of bug
+
+| Layer | What it looks like | Why it misleads |
+|---|---|---|
+| Laravel logs | Empty | Backend is genuinely correct |
+| `manifest.json` | Valid, every input has an entry | Manifest doesn't enforce uniqueness across groups |
+| Browser network tab | 200 OK on every request | The wrong JS arrives successfully |
+| Console | Clean | The rendered component is valid React |
+
+Triage rule of thumb: **when wrong-component render happens with HTTP 200 and
+empty server logs, the bug is in the bundle. Start from the chunk graph, not
+from Laravel.** This is captured as the "Bundle, not Backend" pattern in
+`debugging-patterns`.
+
 ## Forbidden Patterns
 
 | Pattern | Reason | Use Instead |
@@ -354,3 +489,6 @@ router.reload({ only: ['stats'] }); // Partial reload
 | `window.location` for navigation | Full page reload | `router.visit()` |
 | `Inertia::render()` after POST | Breaks Inertia protocol | `redirect()->route()` |
 | Loading all translations globally | Performance waste | On-demand per page route |
+| Same module in `laravel.input[]` AND `Pages/**` glob | Rollup collapses the manual chunk group into the entry; resolve-map points siblings at the wrong chunk (silent wrong-component render) | Short-circuit `manualChunks` with early `return undefined` for entry pages |
+| `manualChunks` grouping pages without running `check-vite-manifest.mjs` | Grouping is advisory and silently ignored for entry chunks | Always run the validator after touching `build.rollupOptions` |
+| Trusting empty Laravel logs as "no bug" | Server can be 100% correct while the bundle ships the wrong default export | Use the "Bundle, not Backend" triage in `debugging-patterns` |

package/stacks/php/scripts/check-vite-manifest.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+/**
+ * check-vite-manifest.mjs
+ *
+ * Static validator for Vite + laravel-vite-plugin builds that catches the
+ * "entry chunk collides with manualChunks group" bug in Inertia/React apps.
+ *
+ * Production post-mortem 2026-05: a `vite.config.js` "perf" change added
+ *   manualChunks(id) { if (/Auth\//.test(id)) return 'pages-auth' }
+ * while `laravel.input[]` already listed `Pages/.../HttpErrorPage.jsx`
+ * (referenced directly via `@vite()` in `app.blade.php` for the error layout).
+ * Rollup/Rolldown silently dropped the manualChunks group, kept only the
+ * entry, and the `import.meta.glob` resolve-map in `resolvePageComponent`
+ * ended up pointing every sibling page (Login, Register, ForgotPassword) at
+ * the same single-module entry chunk. Server sent `component: 'Auth/Login'`,
+ * browser rendered HttpErrorPage. HTTP 200. Empty Laravel logs.
+ *
+ * Rules enforced (all silent failures in Rollup/Rolldown by default):
+ *
+ *   R1. Every path in `laravel.input[]` MUST appear in `manifest.json` with
+ *       `isEntry: true`.
+ *   R2. Any `laravel.input[]` path that ALSO matches a `import.meta.glob`
+ *       pattern in the project's JS is a COLLISION. Either exclude it from
+ *       the glob, OR short-circuit `manualChunks` with an early
+ *       `return undefined` before grouping rules.
+ *   R3. Any file under `resources/js/Pages/` that appears as `isEntry: true`
+ *       in the manifest is suspect — entry pages must be inspected (they
+ *       collapse manualChunks groups). If the file is referenced direct via
+ *       `@vite()` in blade, document it; otherwise treat as a build leak.
+ *
+ * Usage:
+ *   node scripts/check-vite-manifest.mjs                     # auto-detect
+ *   node scripts/check-vite-manifest.mjs <manifest> <vite.config>
+ *
+ * Auto-detect order (when no args):
+ *   manifest:   public/build/manifest.json,
+ *               public/build/.vite/manifest.json
+ *   vite.config: vite.config.js, vite.config.mjs, vite.config.ts
+ *
+ * Exit codes:
+ *   0  OK (or no Vite/manifest found — skipped)
+ *   1  collision (entry × glob) detected
+ *   2  manifest missing an `isEntry: true` for a declared input
+ *   3  malformed input (could not parse vite.config or manifest)
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, join, relative, dirname, basename } from 'node:path';
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+
+// ── Auto-detect paths ────────────────────────────────────────────────────
+const MANIFEST_CANDIDATES = [
+  'public/build/manifest.json',
+  'public/build/.vite/manifest.json',
+];
+const CONFIG_CANDIDATES = [
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.ts',
+];
+
+const manifestPath = args[0]
+  ? resolve(cwd, args[0])
+  : MANIFEST_CANDIDATES.map((p) => resolve(cwd, p)).find(existsSync);
+
+const configPath = args[1]
+  ? resolve(cwd, args[1])
+  : CONFIG_CANDIDATES.map((p) => resolve(cwd, p)).find(existsSync);
+
+if (!manifestPath) {
+  console.error(
+    '[check-vite-manifest] No manifest.json found. ' +
+      'Run `npm run build` first, then re-run this check.',
+  );
+  process.exit(0); // Skip silently if no build artifact yet.
+}
+
+if (!configPath) {
+  console.error(
+    '[check-vite-manifest] No vite.config.{js,mjs,ts} found. Skipping.',
+  );
+  process.exit(0);
+}
+
+// ── Load manifest ────────────────────────────────────────────────────────
+let manifest;
+try {
+  manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+} catch (e) {
+  console.error(
+    `[check-vite-manifest] Could not parse ${relative(cwd, manifestPath)}: ${e.message}`,
+  );
+  process.exit(3);
+}
+
+// ── Load vite.config ─────────────────────────────────────────────────────
+let configSrc;
+try {
+  configSrc = await readFile(configPath, 'utf8');
+} catch (e) {
+  console.error(`[check-vite-manifest] Could not read ${configPath}: ${e.message}`);
+  process.exit(3);
+}
+
+// ── Extract laravel({ input: [...] }) ────────────────────────────────────
+// Tolerant regex: matches `laravel({ ... input: [ '...', "..." ] ... })`
+// across multiple lines. Also catches the helper form
+// `laravel(['resources/css/app.css', 'resources/js/app.jsx'])`.
+function extractLaravelInputs(src) {
+  const inputs = new Set();
+
+  // Form A: laravel({ input: [...] })
+  const formA = /laravel\s*\(\s*\{[\s\S]*?input\s*:\s*\[([\s\S]*?)\][\s\S]*?\}\s*\)/g;
+  for (const m of src.matchAll(formA)) {
+    const arr = m[1];
+    for (const sm of arr.matchAll(/['"`]([^'"`]+)['"`]/g)) inputs.add(sm[1]);
+  }
+
+  // Form B: laravel([ ... ])  (shorthand)
+  const formB = /laravel\s*\(\s*\[([\s\S]*?)\]\s*\)/g;
+  for (const m of src.matchAll(formB)) {
+    const arr = m[1];
+    for (const sm of arr.matchAll(/['"`]([^'"`]+)['"`]/g)) inputs.add(sm[1]);
+  }
+
+  return [...inputs];
+}
+
+// ── Extract import.meta.glob patterns from JS sources ────────────────────
+// We scan the bootstrap entries listed in laravel.input plus any obvious
+// Inertia files (app.jsx, app.tsx, ssr.jsx, ssr.tsx, bootstrap.js) under
+// resources/js/.
+async function findInertiaGlobs(laravelInputs) {
+  const candidates = new Set();
+  for (const input of laravelInputs) {
+    if (/\.(jsx?|tsx?)$/.test(input)) candidates.add(input);
+  }
+  for (const f of ['app.jsx', 'app.tsx', 'ssr.jsx', 'ssr.tsx', 'bootstrap.js']) {
+    const p = `resources/js/${f}`;
+    if (existsSync(resolve(cwd, p))) candidates.add(p);
+  }
+
+  const patterns = [];
+  for (const rel of candidates) {
+    const abs = resolve(cwd, rel);
+    if (!existsSync(abs)) continue;
+    const src = await readFile(abs, 'utf8');
+
+    // resolvePageComponent(`./Pages/${name}.jsx`, import.meta.glob('./Pages/**/*.jsx'))
+    // We just want every `import.meta.glob('...')` literal.
+    for (const m of src.matchAll(
+      /import\.meta\.glob\s*\(\s*\[?\s*['"`]([^'"`]+)['"`]/g,
+    )) {
+      patterns.push({ file: rel, pattern: m[1] });
+    }
+    // Multi-pattern form: import.meta.glob(['./Pages/**/*.jsx', './Other/**/*.jsx'])
+    const multi = /import\.meta\.glob\s*\(\s*\[([\s\S]*?)\]/g;
+    for (const m of src.matchAll(multi)) {
+      for (const sm of m[1].matchAll(/['"`]([^'"`]+)['"`]/g)) {
+        patterns.push({ file: rel, pattern: sm[1] });
+      }
+    }
+  }
+  return patterns;
+}
+
+// Convert a `import.meta.glob` pattern (relative to its host file) into an
+// absolute prefix + suffix matcher. Globs supported: `**`, `*`, and explicit
+// `{jsx,tsx,vue,svelte}` extension brace groups.
+function compileGlob(hostFile, pattern) {
+  const hostDir = dirname(resolve(cwd, hostFile));
+  // Resolve `./` and `../` segments against the host directory.
+  let absPattern = resolve(hostDir, pattern);
+  absPattern = absPattern.replace(/\\/g, '/'); // Windows safety
+
+  // Build a regex from the glob.
+  // Step 1: expand brace groups `{a,b,c}`.
+  const expandBraces = (str) => {
+    const m = str.match(/\{([^{}]+)\}/);
+    if (!m) return [str];
+    const opts = m[1].split(',');
+    const out = [];
+    for (const o of opts) {
+      out.push(...expandBraces(str.slice(0, m.index) + o + str.slice(m.index + m[0].length)));
+    }
+    return out;
+  };
+
+  // Step 2: convert each expansion into a regex.
+  const regexes = expandBraces(absPattern).map((expanded) => {
+    const reSrc = expanded
+      .replace(/[.+^$()|[\]\\]/g, '\\$&')
+      .replace(/\*\*/g, '__GLOBSTAR__')
+      .replace(/\*/g, '[^/]*')
+      .replace(/__GLOBSTAR__/g, '.*');
+    return new RegExp(`^${reSrc}$`);
+  });
+
+  return { pattern, hostFile, regexes };
+}
+
+function globMatches(compiled, absPath) {
+  const normalized = absPath.replace(/\\/g, '/');
+  return compiled.regexes.some((re) => re.test(normalized));
+}
+
+// ── Run validation ───────────────────────────────────────────────────────
+const laravelInputs = extractLaravelInputs(configSrc);
+if (laravelInputs.length === 0) {
+  console.error(
+    '[check-vite-manifest] Could not find laravel({ input: [...] }) in ' +
+      relative(cwd, configPath) +
+      '. Skipping (is this a Laravel + Vite project?).',
+  );
+  process.exit(0);
+}
+
+const errors = [];
+const warnings = [];
+
+// R1. Every laravel.input MUST be in the manifest as isEntry.
+for (const input of laravelInputs) {
+  const entry = manifest[input];
+  if (!entry) {
+    errors.push({
+      rule: 'R1',
+      msg: `Input "${input}" declared in laravel.input but absent from manifest. Did the build fail?`,
+    });
+    continue;
+  }
+  if (!entry.isEntry) {
+    errors.push({
+      rule: 'R1',
+      msg: `Input "${input}" present in manifest but NOT marked isEntry. Check laravel-vite-plugin version.`,
+    });
+  }
+}
+
+// R2 + R3. Cross-reference laravel.input against glob patterns.
+const globs = await findInertiaGlobs(laravelInputs);
+if (globs.length > 0) {
+  const compiledGlobs = globs.map((g) => compileGlob(g.file, g.pattern));
+
+  for (const input of laravelInputs) {
+    if (!/\.(jsx?|tsx?)$/.test(input)) continue; // skip CSS, etc.
+    const absInput = resolve(cwd, input);
+    for (const cg of compiledGlobs) {
+      if (globMatches(cg, absInput)) {
+        errors.push({
+          rule: 'R2',
+          msg:
+            `Collision: "${input}" is BOTH in laravel.input[] AND matched by ` +
+            `import.meta.glob("${cg.pattern}") in ${cg.hostFile}. ` +
+            `Rollup/Rolldown will silently collapse the manualChunks group ` +
+            `containing this module, leaving the glob resolve-map pointing ` +
+            `siblings at the wrong chunk hash. Either remove from ` +
+            `laravel.input[], exclude from the glob, or add early ` +
+            `\`return undefined\` for this module in manualChunks.`,
+        });
+      }
+    }
+  }
+}
+
+// R3. Pages/ files marked as isEntry that are NOT in laravel.input.
+// These mean someone added an entry chunk indirectly (e.g. dynamic import
+// promoted to entry by chunking heuristics) — worth flagging.
+const declaredInputSet = new Set(laravelInputs);
+for (const [key, entry] of Object.entries(manifest)) {
+  if (!entry.isEntry) continue;
+  if (declaredInputSet.has(key)) continue;
+  if (key.includes('resources/js/Pages/')) {
+    warnings.push({
+      rule: 'R3',
+      msg:
+        `Suspicious entry chunk: "${key}" is under Pages/ and marked ` +
+        `isEntry=true but NOT declared in laravel.input[]. This usually ` +
+        `means the bundler promoted it to entry to break a circular import ` +
+        `or because manualChunks excluded it. Verify the resolve-map of ` +
+        `import.meta.glob still points other pages at THIS chunk's siblings, ` +
+        `not at this chunk.`,
+    });
+  }
+}
+
+// ── Report ───────────────────────────────────────────────────────────────
+const tag = '[check-vite-manifest]';
+
+if (warnings.length > 0) {
+  for (const w of warnings) console.warn(`${tag} WARN  ${w.rule}: ${w.msg}`);
+}
+
+if (errors.length === 0) {
+  console.log(
+    `${tag} OK  ${laravelInputs.length} input(s), ${globs.length} glob(s), ` +
+      `${Object.keys(manifest).length} manifest entries — no collisions.`,
+  );
+  process.exit(0);
+}
+
+for (const e of errors) console.error(`${tag} FAIL  ${e.rule}: ${e.msg}`);
+console.error(
+  `\n${tag} Manifest validation failed: ${errors.length} error(s). ` +
+    `See "Vite Build Gotchas" in the inertia-react skill for the fix pattern.`,
+);
+process.exit(errors.some((e) => e.rule === 'R1') ? 2 : 1);

package/stacks/php/skills/inertia-react/SKILL.md

@@ -1,10 +1,13 @@
 ---
 name: inertia-react
-version: 2.0.0
+version: 2.1.0
 description: LEGACY skill — Inertia.js + React with Laravel-rendered pages. Use
   ONLY in pre-existing projects already built on Inertia. For NEW projects use
   `laravel-api-architecture` + `axios-laravel-api` + `react-api-standards`
-  (API-first React SPA, no controller-rendered pages).
+  (API-first React SPA, no controller-rendered pages). v2.1.0 adds the "Vite
+  Build Gotchas" section covering the manualChunks × entry-chunk ×
+  resolvePageComponent glob collision (silent wrong-component render
+  post-mortem 2026-05).
 ---
 
 # Inertia.js + React — Laravel Frontend (LEGACY)
@@ -207,6 +210,124 @@ export interface PaginatedData<T> {
 }
 ```
 
+## Vite Build Gotchas (Inertia-specific)
+
+> **Production post-mortem 2026-05.** A `vite.config.js` "perf" change adding
+> `manualChunks` to group `Pages/Auth/*` produced a silent wrong-component
+> render: `Inertia::render('Auth/Login', ...)` returned HTTP 200 OK but the
+> browser rendered the error page. Laravel logs were empty. Bug lived
+> entirely in the bundle graph.
+
+### The three-way collision
+
+```
+laravel-vite-plugin      ┐  laravel({ input: [...HttpErrorPage] })
+                         │  → module becomes an ENTRY chunk
+                         │    Rollup/Rolldown ALWAYS prioritizes entries.
+
+@inertiajs/react         ┐  resolvePageComponent(..., import.meta.glob(
+                         │    './Pages/**/*.jsx'))
+                         │  → builds a STATIC resolve-map at build time
+                         │    pointing each Page path to its chunk hash.
+
+build.rollupOptions      ┐  manualChunks(id) { if (Auth) return 'pages-auth' }
+                         │  → ADVISORY ONLY. Returning a group for a module
+                         │    that's already an entry has NO EFFECT and
+                         │    emits NO WARNING.
+```
+
+When the same module (e.g. `HttpErrorPage.jsx`) is BOTH:
+
+1. listed in `laravel.input[]` (typical: error pages referenced directly via
+   `@vite()` in `resources/views/app.blade.php` or a layout), AND
+2. caught by a `manualChunks` rule (e.g. `pages-auth`),
+
+…Rollup/Rolldown creates a **standalone entry chunk** with only that one
+module. The `pages-auth` group collapses into that entry. The
+`import.meta.glob` resolve-map points **every sibling page**
+(`Login`, `Register`, `ForgotPassword`, …) at the same chunk hash. The
+siblings' source is discarded.
+
+Symptom: server sends `component: 'Auth/Login'`, browser loads the chunk,
+chunk's `default` export is `HttpErrorPage`, error page renders. Server 100%
+correct; bundle ships the wrong default export.
+
+### Rule 1 — Never duplicate a module between `laravel.input` and the `Pages/**` glob
+
+Either exclude the entry page from the Inertia glob, OR short-circuit
+`manualChunks` BEFORE any grouping rule to preserve the entry's identity.
+Preferred pattern (no change to Inertia bootstrap):
+
+```js
+// vite.config.js
+build: {
+    rollupOptions: {
+        output: {
+            manualChunks(id) {
+                if (!id.includes('/resources/js/Pages/')) return;
+
+                // Entry chunks referenced directly by @vite() in blade MUST
+                // return undefined here — BEFORE any grouping rule. Otherwise
+                // the manualChunks group is collapsed into the entry and the
+                // import.meta.glob resolve-map points siblings at the wrong
+                // chunk hash. Production post-mortem 2026-05.
+                if (id.includes('/Pages/OtherPages/HttpErrorPage')) return;
+
+                if (id.includes('/Pages/Auth/') || id.includes('/Pages/OtherPages/')) {
+                    return 'pages-auth';
+                }
+                if (id.includes('/Pages/Dashboard/')) {
+                    return 'pages-dashboard';
+                }
+            },
+        },
+    },
+},
+```
+
+### Rule 2 — `manualChunks` is advisory; entries always win
+
+There is no warning when Rollup/Rolldown ignores a `manualChunks` return value
+for an entry module. Validation MUST be done out-of-band on `manifest.json`
+after every build.
+
+### Rule 3 — Validate `public/build/manifest.json` after every `vite build`
+
+`start-vibing-stacks` ships `scripts/check-vite-manifest.mjs` (wired as the
+`ViteManifest` quality gate at order 5):
+
+```bash
+node scripts/check-vite-manifest.mjs public/build/manifest.json vite.config.js
+```
+
+The script cross-references `laravel.input[]` against `Pages/**` glob patterns
+and fails (non-zero exit) on any collision.
+
+### Rule 4 — Smoke-test after any `vite.config.js` change touching `build`
+
+For one critical route per page group:
+
+1. DevTools → Network → click the Inertia XHR → read `component:` in the JSON.
+2. Click the JS asset request that follows → open the resolved chunk URL.
+3. Search for `default:` / `export{ ... as default}` in that chunk. The
+   exported component name MUST match the server's `component:`.
+
+If they don't match, revert the last `vite.config.js` change before debugging
+anything else.
+
+### Why this class of bug is so misleading
+
+| Layer | What it looks like | Why it misleads |
+|---|---|---|
+| Laravel logs | Empty | Backend is genuinely correct |
+| `manifest.json` | Valid, every input has an entry | Manifest doesn't enforce uniqueness across groups |
+| Browser network | 200 OK on every request | The wrong JS arrives successfully |
+| Console | Clean | The rendered component is valid React |
+
+Triage rule: **wrong-component render with HTTP 200 and empty server logs =
+bug is in the bundle, not the server.** See `debugging-patterns §Bundle, not
+Backend`.
+
 ## FORBIDDEN
 
 1. **API routes for Inertia pages** — use `Inertia::render()` in controllers
@@ -214,3 +335,6 @@ export interface PaginatedData<T> {
 3. **Fetching data in useEffect** — pass as props from controller
 4. **Duplicating validation** — validate in FormRequest, show errors from `useForm`
 5. **`any` types for page props** — always type with `interface Props extends PageProps`
+6. **Same module in `laravel.input[]` and `Pages/**` glob** — Rollup collapses the manual chunk group into the entry; resolve-map silently points siblings at the wrong chunk hash (wrong-component render with HTTP 200)
+7. **`manualChunks` grouping pages without running `check-vite-manifest.mjs`** — grouping is advisory and silently ignored for entry chunks
+8. **Trusting empty Laravel logs as "no bug"** — server can be 100% correct while the bundle ships the wrong `default` export

package/stacks/php/stack.json

@@ -19,7 +19,8 @@
     { "name": "PHPStan", "command": "vendor/bin/phpstan analyse --level=6", "required": true, "order": 1 },
     { "name": "PHPUnit", "command": "vendor/bin/phpunit", "required": true, "order": 2 },
     { "name": "TypeCheck", "command": "npx tsc --noEmit", "required": true, "order": 3 },
-    { "name": "Lint", "command": "npx eslint resources/js/", "required": false, "order": 4 }
+    { "name": "Lint", "command": "npx eslint resources/js/", "required": false, "order": 4 },
+    { "name": "ViteManifest", "command": "node scripts/check-vite-manifest.mjs", "required": false, "order": 5 }
   ],
   "frameworks": [
     {

package/templates/CLAUDE-php.md

@@ -310,6 +310,22 @@ const stripePublishable = import.meta.env.VITE_STRIPE_KEY;   // pk_...
 | `useEffect` to derive state | Anti-pattern — use `useMemo` |
 | Skipping skeleton/empty/error states | Bad UX — all three are mandatory per page |
 
+### Vite Build (CRITICAL — silent bug class)
+
+> **Production post-mortem 2026-05.** A bad `manualChunks` rule can produce
+> silent wrong-component renders (HTTP 200, empty Laravel logs, browser
+> shows the error page when server asked for `Auth/Login`). Bug lives in the
+> bundle graph, not the server. See `inertia-react §Vite Build Gotchas` and
+> `debugging-patterns §Bundle, not Backend`.
+
+| Action | Reason |
+|--------|--------|
+| Same module in `laravel.input[]` and `Pages/**` glob | Rollup/Rolldown silently collapses the manualChunks group into the entry chunk; `import.meta.glob` resolve-map points siblings at the wrong hash |
+| `manualChunks` grouping pages without short-circuit for entry pages | `manualChunks` is advisory — entries always win, with no warning. Add early `return undefined` for any page also listed in `laravel.input[]` |
+| Skipping `node scripts/check-vite-manifest.mjs` after `vite build` | Bundler emits no warning on collision; manual validation is the only signal |
+| Debugging Laravel/server when HTTP 200 + empty logs + wrong content | Triage as "Bundle, not Backend" — start from the JS chunk's `default` export, not the controller |
+| Adding new `@vite('resources/js/Pages/...')` direct reference in blade without auditing `vite.config.js` | Promoting a page to entry chunk while it's still in the Inertia glob is the exact collision shape |
+
 ## UI/UX Design Intelligence
 
 > When the project has a frontend, the **UI/UX Pro Max** skill is auto-installed. It provides 67 UI styles, 161 color palettes, 57 font pairings, and 161 industry-specific reasoning rules. It activates automatically for any UI/UX task.