start-vibing-stacks 2.18.0 → 2.20.0

package/dist/setup.js

@@ -187,6 +187,17 @@ export async function setupProject(projectDir, config, options = {}) {
                 spinner.text = 'Installed CI workflow templates';
             }
         }
+        // 11e. Copy stack-level helper scripts (e.g. nodejs/scripts/check-route-slugs.mjs)
+        // copyDirRecursive is non-destructive by default: existing files in the target
+        // project's scripts/ dir are preserved unless --force is passed.
+        const stackScriptsDir = join(PACKAGE_ROOT, 'stacks', config.stack, 'scripts');
+        if (existsSync(stackScriptsDir)) {
+            const projectScriptsDir = join(projectDir, 'scripts');
+            const copied = copyDirRecursive(stackScriptsDir, projectScriptsDir, options.force);
+            if (copied > 0) {
+                spinner.text = `Installed ${copied} stack helper script(s) to scripts/`;
+            }
+        }
         // 12. Copy commands
         const sharedCommandsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'commands');
         if (existsSync(sharedCommandsDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.18.0",
+  "version": "2.20.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/quality-gate/SKILL.md

@@ -24,12 +24,19 @@ vendor/bin/php-cs-fixer fix --dry-run    # Code style
 
 ### Node.js Gates
 ```bash
-bun run typecheck    # TypeScript errors
-bun run lint         # ESLint
-bun run test         # Vitest
-bun run build        # Build verification
+bun run typecheck                          # TypeScript errors
+bun run lint                               # ESLint
+bun run test                               # Vitest
+node scripts/check-route-slugs.mjs         # Next.js — only run if framework=nextjs
+bun run build                              # Build verification (must come AFTER route-slugs)
 ```
 
+> **Next.js note.** `next build` does NOT validate dynamic-segment slug
+> consistency (e.g. `[id]` and `[userId]` under the same parent). The
+> `check-route-slugs.mjs` script must run **before** `build` to catch this
+> statically — see `nextjs-app-router` skill, section "Dynamic Route Slug
+> Consistency".
+
 ## Gate Results
 
 | Result | Action |

package/stacks/frontend/react/skills/preline-ui/SKILL.md

@@ -1,11 +1,14 @@
 ---
 name: preline-ui
-version: 1.0.0
+version: 2.0.0
+description: "Preline UI — semantic-token component system on top of Tailwind v4 (stable Jan 2025). 220+ design tokens covering background/foreground/primary/secondary/muted/destructive/border/surface/layer + per-component groups (navbar, sidebar, card, dropdown, select, overlay, tooltip, popover, scrollbar). 840+ free copy-paste blocks (hero, testimonials, pricing, dashboards, forms). Mandatory `HSStaticMethods.autoInit()` after client-side navigation in Next.js — without it, dropdowns/modals/accordions break. Theme generator CLI, custom palettes via `@theme inline { … }`, light + dark via `data-theme` + `.dark`. Chart tokens require HEX (no oklch in -hex). Pairs with React 19 (refs as props, document metadata). Invoke when using Preline components, creating themes, or customising tokens."
 ---
 
-# Preline UI — Component & Theme System for TailwindCSS 4
+# Preline UI — Component & Theme System for Tailwind v4 (2026)
 
-**ALWAYS invoke when using Preline components, creating themes, or customizing design tokens.**
+**ALWAYS invoke when using Preline components, creating themes, or customising design tokens.**
+
+> Pairs with `tailwind-patterns` v2 (Tailwind v4 `@theme`, Oxide engine, OKLCH) and `react-standards` v2 (LABELS/STYLES const pattern). For shadcn-style primitives with Radix/Base UI underneath, see `shadcn-ui` v2 — pick **one** component system per project, don't mix Preline and shadcn.
 
 ## What is Preline
 

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

@@ -1,12 +1,23 @@
 ---
 name: react-patterns
-version: 1.0.0
+version: 2.0.0
+description: "Modern React 19 component architecture (stable Dec 5 2024; 19.1 in 2025). Covers the new hooks (`useActionState`, `useOptimistic`, `useFormStatus`, `use()` for promises and Context), refs-as-props (no more `forwardRef`), document metadata hoisting (write `<title>` and `<meta>` anywhere), Actions for async mutations, Server Components vs Client Components, compound + generic components, custom hooks, state-management decision matrix (useState → useReducer → Context → Zustand → server cache), Error Boundaries, performance via memo/useMemo/useCallback, and Suspense boundaries. Invoke for any new component, hook, state design, or React-architecture decision."
 ---
 
-# React Patterns — Modern Component Architecture
+# React 19 Patterns — Modern Component Architecture
 
 **ALWAYS invoke when writing React components, hooks, or state management.**
 
+## React 19 essentials (stable Dec 5, 2024 → 19.1 in 2025)
+
+- **Actions** — async functions passed straight to forms; `useActionState` manages pending/error/optimistic state automatically
+- **`use()`** — read promises and Context **conditionally** during render (paired with Suspense + Error Boundaries)
+- **Refs as props** — pass `ref` like any other prop. **`forwardRef` is no longer needed** for new components
+- **Document metadata hoisting** — `<title>`, `<meta>`, `<link>` get auto-hoisted into `<head>` from anywhere
+- **Form `action` prop** — submits via the action, auto-resets uncontrolled inputs on success
+- **Stylesheet management** — `<link rel="stylesheet">` in components is awaited before the Suspense boundary reveals
+- **Suspense sibling pre-warming** — fallback shows immediately and queues sibling requests in parallel
+
 ## Component Patterns
 
 ### Compound Components
@@ -109,52 +120,125 @@ const Heavy = lazy(() => import('./HeavyComponent'));
 <Suspense fallback={<Loading />}><Heavy /></Suspense>
 ```
 
-## React 19 Hooks
+## React 19 — Actions & form-state hooks
+
+### `useActionState` — pending + error + result for one form
 
 ```tsx
-// useActionState — form submission state
 import { useActionState } from 'react';
 
 function LoginForm() {
   const [state, formAction, isPending] = useActionState(
-    async (prev, formData: FormData) => {
+    async (_prev, formData: FormData) => {
       const result = await login(formData);
       if (result.error) return { error: result.error };
       redirect('/dashboard');
     },
-    { error: null }
+    { error: null as string | null }
   );
 
   return (
     <form action={formAction}>
-      <input name="email" type="email" />
+      <input name="email" type="email" required />
       {state.error && <p className="text-destructive">{state.error}</p>}
-      <button disabled={isPending}>
-        {isPending ? 'Signing in...' : 'Sign In'}
-      </button>
+      <button disabled={isPending}>{isPending ? 'Signing in…' : 'Sign In'}</button>
     </form>
   );
 }
+```
+
+### `useFormStatus` — child of a form reads its parent's submit state
+
+```tsx
+import { useFormStatus } from 'react-dom';
+
+function SubmitButton() {
+  const { pending } = useFormStatus();          // ← reads the enclosing <form action={…}>
+  return <button disabled={pending}>{pending ? 'Saving…' : 'Save'}</button>;
+}
+```
 
-// useOptimistic — instant UI feedback
+Drop `<SubmitButton />` inside any `<form action={…}>` — no prop drilling, no context.
+
+### `useOptimistic` — instant UI feedback that auto-reverts on error
+
+```tsx
 import { useOptimistic } from 'react';
 
 function TodoList({ todos }: { todos: Todo[] }) {
   const [optimisticTodos, addOptimistic] = useOptimistic(
     todos,
-    (state, newTodo: Todo) => [...state, newTodo]
+    (current, newTodo: Todo) => [...current, newTodo]
   );
 
-  const addTodo = async (formData: FormData) => {
-    const todo = { id: crypto.randomUUID(), title: formData.get('title') as string, done: false };
-    addOptimistic(todo);  // Instant UI
-    await saveTodo(todo);  // Server sync
-  };
+  async function add(formData: FormData) {
+    const todo = { id: crypto.randomUUID(), title: String(formData.get('title')), done: false };
+    addOptimistic(todo);          // instant
+    await saveTodo(todo);          // server confirms (or throws → revert is automatic on rerender)
+  }
 
-  return <ul>{optimisticTodos.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
+  return (
+    <>
+      <form action={add}><input name="title" /></form>
+      <ul>{optimisticTodos.map(t => <li key={t.id}>{t.title}</li>)}</ul>
+    </>
+  );
 }
 ```
 
+### `use()` — read a promise or Context conditionally
+
+```tsx
+import { use, Suspense } from 'react';
+
+function UserName({ userPromise }: { userPromise: Promise<User> }) {
+  const user = use(userPromise);                // suspends until resolved
+  return <span>{user.name}</span>;
+}
+
+// Parent
+<Suspense fallback={<Skeleton />}>
+  <UserName userPromise={fetchUser(id)} />
+</Suspense>
+```
+
+`use()` is the only hook allowed inside conditionals — perfect for "render after this resource resolves" without restructuring components.
+
+## React 19 — refs as props (no `forwardRef`)
+
+```tsx
+// React 19 — `ref` is just a prop
+function Input({ ref, className, ...props }: React.InputHTMLAttributes<HTMLInputElement> & {
+  ref?: React.Ref<HTMLInputElement>;
+}) {
+  return <input ref={ref} className={cn('h-10 px-3 …', className)} {...props} />;
+}
+
+// Usage — no different from before
+const myRef = useRef<HTMLInputElement>(null);
+<Input ref={myRef} />
+```
+
+`forwardRef` keeps working — but new components should ditch it.
+
+## React 19 — document metadata anywhere
+
+```tsx
+function Article({ post }: { post: Post }) {
+  return (
+    <article>
+      <title>{post.title} — My Site</title>          {/* hoisted into <head> */}
+      <meta name="description" content={post.summary} />
+      <link rel="canonical" href={`/blog/${post.slug}`} />
+      <h1>{post.title}</h1>
+      {/* … */}
+    </article>
+  );
+}
+```
+
+No `next/head` / `react-helmet` needed — React handles it. Server-rendered metadata appears in the initial HTML (good for SEO).
+
 ## State Management Selection
 
 | Complexity | Solution | When |
@@ -219,11 +303,26 @@ class ErrorBoundary extends Component<
 
 ## FORBIDDEN
 
-1. **Class components** — function components only (except ErrorBoundary)
-2. **Prop drilling** — use context or composition
-3. **Inline objects/functions in JSX** — causes re-renders
-4. **useEffect for derived state** — use useMemo
-5. **Mutating state directly** — always setState/dispatch
-6. **Index as key** — use stable unique ID (`uuid`, `id`)
-7. **Premature optimization** — profile first with React DevTools
-8. **useEffect for everything** — prefer server components for data
+| Pattern | Why |
+|---|---|
+| `forwardRef` in new components | Refs are props in React 19 — drop the wrapper |
+| `useEffect` to fetch data | Use Server Components, `use()` + Suspense, or TanStack Query |
+| `useEffect` for derived state | Compute it in render or via `useMemo` |
+| `next/head` / `react-helmet` in R19 | Use plain `<title>` / `<meta>` — React hoists |
+| Class components | Function components only (Error Boundaries are the rare exception) |
+| Prop drilling > 2 levels | Composition or `Context` |
+| Inline objects/functions in hot paths | Stable refs via `useMemo` / `useCallback` (only when profiler shows it matters) |
+| Direct state mutation | Always set new state — React relies on referential change |
+| Index as `key` | Use stable unique IDs (`crypto.randomUUID()`, server IDs) |
+| Premature memoisation | Profile with React DevTools first |
+| Manual `isPending` + `error` `useState` for forms | Use `useActionState` |
+| Custom optimistic-state code | `useOptimistic` + Action |
+
+## See Also
+
+- `react-standards` v2 — LABELS / STYLES const pattern
+- `react-ui-patterns` v2 — loading/error/empty + TanStack Query v5
+- `tailwind-patterns` v2 — `@theme`, container queries, OKLCH
+- `shadcn-ui` v2 — primitives without `forwardRef`, `data-slot` styling
+- `zod-validation` v2 — Zod 4 + RHF for form Actions
+- `_shared/skills/playwright-automation` v2 — E2E coverage including R19 forms

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

@@ -1,14 +1,18 @@
 ---
 name: react-standards
-version: 1.0.0
+version: 2.0.0
+description: "Project conventions for React 19 + Tailwind v4 codebases. Mandates the LABELS / STYLES const pattern (defined at file top, before hooks, with `as const` for stable references — prevents re-renders, centralises styles, supports i18n drop-in), controlled debug logging (no raw console.log), semantic Tailwind tokens (no raw colours), separate-file SVG icons, mandatory loading/empty states, modal data-flow contract (`onUpdated` callback), and third-party chart integration (no useRef DOM mutation). Pairs with `tailwind-patterns` v2 for tokens and `react-ui-patterns` v2 for state choreography. Invoke at the start of any new React project or component file."
 ---
 
-# React 19+ Standards
+# React 19 + Tailwind v4 — Project Standards
+
+> Conventions that apply to **every** component in the codebase. Pairs with `react-patterns` (architecture), `tailwind-patterns` (tokens), `react-ui-patterns` (state), and `shadcn-ui` (primitives).
 
 ## Version Requirements
 
-- **ReactJS >= 19** — MANDATORY
-- **TailwindCSS >= 4** — MANDATORY
+- **React ≥ 19.0** (stable Dec 5, 2024) — MANDATORY for new projects
+- **TailwindCSS ≥ 4.0** (stable Jan 22, 2025) — MANDATORY (CSS-first `@theme`, Oxide engine)
+- **TypeScript ≥ 5.6** strict mode
 
 ## Label Constants Pattern
 
@@ -279,3 +283,12 @@ const processedData = useMemo(() => {
 - Conditional rendering: `data && <Component />`
 - `useMemo` for expensive computations
 - Loading states before rendering charts
+
+## See Also
+
+- `react-patterns` v2 — React 19 hooks, `use()`, refs as props
+- `tailwind-patterns` v2 — `@theme`, Oxide engine, container queries, OKLCH
+- `shadcn-ui` v2 — primitives without `forwardRef`, `data-slot` slots
+- `react-ui-patterns` v2 — loading/error/empty + TanStack Query v5
+- `zod-validation` v2 — Zod 4 schemas for forms + env vars
+- `_shared/skills/ui-ux-audit` v2 — WCAG 2.2 AA validation

package/stacks/frontend/react/skills/react-ui-patterns/SKILL.md

@@ -1,12 +1,26 @@
 ---
 name: react-ui-patterns
-version: 1.0.0
+version: 2.0.0
+description: "React 19 + TanStack Query v5 UI patterns for production async UI: loading/error/empty state hierarchy, skeleton vs spinner choice, ErrorState/EmptyState/LoadingState reusable components, button states with disabled+loading indicator, RHF + Zod 4 forms, optimistic updates via React 19 `useOptimistic` (built-in, simpler than TanStack `onMutate`/rollback) AND TanStack Query v5 onMutate pattern (when you need cache surgery), Suspense + useSuspenseQuery boundaries, signal threading for cancellation. TanStack Query v5 renamed `loading` → `pending` (note isPending vs isFetching vs isLoading). Invoke when handling any async UI state, form, mutation, or user feedback."
 ---
 
-# React UI Patterns — Loading, Errors, Empty States & Forms
+# React UI Patterns — Loading, Errors, Empty States & Forms (R19 + TanStack v5)
 
 **ALWAYS invoke when handling async UI states, forms, or user feedback.**
 
+## Stack snapshot (2026)
+
+| Concern | Pick |
+|---|---|
+| Server cache + refetch + dedup | **TanStack Query v5** (`useQuery`, `useMutation`, `useSuspenseQuery`) |
+| Form state + validation | **react-hook-form** + **`@hookform/resolvers/zod`** (Zod 4) |
+| Optimistic UI for **submit-then-confirm** flows | React 19 **`useOptimistic`** (no cache surgery needed) |
+| Optimistic UI when you must mutate the cache | TanStack `onMutate` + `setQueryData` rollback |
+| Suspense / streaming data | `useSuspenseQuery` + `<Suspense>` |
+| Toasts | **Sonner** (`toast.success`, `toast.error`) |
+
+> **TanStack Query v5 renamed `loading` → `pending`.** Use `isPending` (no data yet, no error), `isFetching` (any fetch in flight, including refetch), `isLoading` (legacy alias for `isPending && isFetching`). The render-tree decision below is unchanged.
+
 ## Core Principles
 
 1. **Never show stale UI** — loading only when actually loading
@@ -33,18 +47,40 @@ Has data?
 ```
 
 ```tsx
-// ✅ CORRECT — only loading when no data
-const { data, isLoading, error, refetch } = useQuery(...);
+// ✅ CORRECT — TanStack v5: isPending = no data yet
+const { data, isPending, error, refetch } = useQuery({
+  queryKey: ['items'],
+  queryFn: ({ signal }) => fetchItems({ signal }),  // thread signal for cancellation
+});
 
-if (error) return <ErrorState error={error} onRetry={refetch} />;
-if (isLoading && !data) return <Skeleton />;
+if (error)               return <ErrorState error={error} onRetry={refetch} />;
+if (isPending)           return <Skeleton />;
 if (!data?.items.length) return <EmptyState />;
 return <ItemList items={data.items} />;
 
-// ❌ WRONG — flashes spinner on refetch when cached data exists
+// ❌ WRONG (v3 idiom) — flashes spinner on refetch when cached data exists
 if (isLoading) return <Spinner />;
 ```
 
+### Suspense alternative
+
+```tsx
+// useSuspenseQuery — cleaner when you wrap with <Suspense> + <ErrorBoundary>
+function ItemList() {
+  const { data } = useSuspenseQuery({
+    queryKey: ['items'],
+    queryFn: ({ signal }) => fetchItems({ signal }),
+  });
+  return <ul>{data.items.map(i => <li key={i.id}>{i.title}</li>)}</ul>;
+}
+
+<ErrorBoundary fallback={<ErrorState />}>
+  <Suspense fallback={<Skeleton />}>
+    <ItemList />
+  </Suspense>
+</ErrorBoundary>
+```
+
 ### Skeleton vs Spinner
 
 | Use Skeleton | Use Spinner |
@@ -276,49 +312,83 @@ export default function CreateUser() {
 }
 ```
 
-## Optimistic Updates (TanStack Query)
+## Optimistic Updates — pick by use case
+
+### Option A — React 19 `useOptimistic` (simpler, NEW DEFAULT for forms)
+
+When the optimistic update is **local to a component** and tied to a form Action, this is the cleanest option — no manual rollback, no cache surgery.
+
+```tsx
+"use client";
+import { useOptimistic } from "react";
+
+function TodoList({ todos, addTodo }: { todos: Todo[]; addTodo: (t: Todo) => Promise<void> }) {
+  const [optimisticTodos, addOptimistic] = useOptimistic(
+    todos,
+    (current, newTodo: Todo) => [...current, newTodo],
+  );
+
+  async function action(formData: FormData) {
+    const todo = { id: crypto.randomUUID(), title: String(formData.get("title")), done: false };
+    addOptimistic(todo);              // instant
+    await addTodo(todo);               // server confirms — on error React reverts on next render
+  }
+
+  return (
+    <>
+      <form action={action}>
+        <input name="title" required />
+        <button>Add</button>
+      </form>
+      <ul>{optimisticTodos.map(t => <li key={t.id}>{t.title}</li>)}</ul>
+    </>
+  );
+}
+```
+
+### Option B — TanStack Query `onMutate` + cache rollback
+
+Reach for this when the mutation has to update a **shared server cache** that other components also read (toggling a favourite that appears in three lists, for instance).
 
 ```tsx
-import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useMutation, useQueryClient } from "@tanstack/react-query";
 
 function ToggleFavorite({ item }: { item: Item }) {
-  const queryClient = useQueryClient();
+  const qc = useQueryClient();
 
   const mutation = useMutation({
     mutationFn: () =>
-      fetch(`/api/items/${item.id}/favorite`, { method: 'POST' }).then((res) => {
-        if (!res.ok) throw new Error('Failed');
-        return res.json();
+      fetch(`/api/items/${item.id}/favorite`, { method: "POST" }).then(r => {
+        if (!r.ok) throw new Error("Failed");
+        return r.json();
       }),
     onMutate: async () => {
-      await queryClient.cancelQueries({ queryKey: ['items'] });
-      const previous = queryClient.getQueryData<Item[]>(['items']);
-
-      queryClient.setQueryData<Item[]>(['items'], (old) =>
-        old?.map((i) =>
-          i.id === item.id ? { ...i, isFavorite: !i.isFavorite } : i
-        )
+      await qc.cancelQueries({ queryKey: ["items"] });
+      const previous = qc.getQueryData<Item[]>(["items"]);
+      qc.setQueryData<Item[]>(["items"], (old) =>
+        old?.map(i => i.id === item.id ? { ...i, isFavorite: !i.isFavorite } : i),
       );
-
       return { previous };
     },
     onError: (_err, _vars, context) => {
-      queryClient.setQueryData(['items'], context?.previous);
-      toast.error('Failed to update');
+      qc.setQueryData(["items"], context?.previous);    // rollback
+      toast.error("Failed to update");
     },
     onSettled: () => {
-      queryClient.invalidateQueries({ queryKey: ['items'] });
+      qc.invalidateQueries({ queryKey: ["items"] });    // truth from server
     },
   });
 
   return (
-    <button onClick={() => mutation.mutate()} className="text-xl">
-      {item.isFavorite ? '❤️' : '🤍'}
+    <button onClick={() => mutation.mutate()} className="text-xl" aria-label="Toggle favorite">
+      {item.isFavorite ? "❤️" : "🤍"}
     </button>
   );
 }
 ```
 
+> Don't combine both for the same flow — `useOptimistic` for forms, TanStack `onMutate` for cross-cache updates. Mixing them creates invisible double rollbacks.
+
 ## Checklist — Before Shipping Any UI Component
 
 - [ ] Error state handled and shown to user
@@ -332,8 +402,13 @@ function ToggleFavorite({ item }: { item: Item }) {
 
 ## FORBIDDEN
 
-1. **`if (loading) return <Spinner />`** — check `loading && !data` instead
-2. **Silent catch** — always toast/display errors to user
-3. **No empty state** — every list needs one
-4. **Clickable button during submit** — always `disabled={isPending}` or `disabled={isSubmitting}`
-5. **Console.log-only errors** — user must see feedback
+| Anti-pattern | Fix |
+|---|---|
+| `if (isLoading) return <Spinner />` (v3 idiom) | TanStack v5: check `isPending` (no data yet), keep cached data visible during refetch |
+| Silent `catch (e) { console.log(e) }` | Always surface via toast / inline error |
+| List without an empty state | Every collection needs `<EmptyState />` |
+| Clickable button while a mutation is pending | `disabled={mutation.isPending}` + spinner |
+| `console.log`-only errors | User must see feedback (toast / banner / inline) |
+| `useOptimistic` AND TanStack `onMutate` for the same flow | Pick one — mixing produces double rollbacks |
+| `mutationFn` that doesn't thread the `signal` | Add `({ signal }) => fetch(url, { signal })` so unmount cancels in-flight |
+| `forwardRef` wrappers around shadcn primitives | React 19 — refs are plain props |