@minhduydev/mdpi 0.4.1 → 0.5.0

package/dist/index.js

@@ -10,7 +10,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { mkdir, readdir } from "node:fs/promises";
 //#region package.json
-var version = "0.4.1";
+var version = "0.5.0";
 //#endregion
 //#region src/utils/manifest.ts
 /**

package/dist/template/.pi/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.0

package/dist/template/.pi/extensions/templates-injector.ts

@@ -1,7 +1,6 @@
 /**
  * Templates Injector Extension
  *
- * Auto-injects project context files into system prompt.
  * Auto-injects project context files into system prompt via pi's before_agent_start hook.
  *
  * Resolution: prefer the LIVE file at `.pi/{name}` (filled by /init, the project's
@@ -9,21 +8,40 @@
  * when no live file exists. This keeps templates/ pristine as deliverables while
  * ensuring real project state is what the agent actually sees.
  *
- * Auto-injected (always, whichever resolves):
+ * Auto-injected (always, whichever resolves) — but ONLY when not placeholder-heavy:
  * - project.md
  * - tech-stack.md
  * - state.md   ← the "you are here" marker; live version injected once /init fills it
  *
- * User can opt-in to inject more via /inject-template command.
+ * Placeholder-skip: at before_agent_start, blank seed templates (still full of
+ * `[Criterion]`/`[URL]`/`<!-- ... -->` markers) are skipped so they don't tax the
+ * first message. A live file with real content (few markers) still injects.
+ *
+ * DESIGN.md is NOT auto-injected — load it on demand via `/inject-template DESIGN.md`
+ * (e.g. when starting UI work).
+ *
+ * User can opt-in to inject more via /inject-template command (placeholder-skip
+ * does not apply to explicit on-demand injection).
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-const ALWAYS_INJECT = ["project.md", "tech-stack.md", "state.md", "DESIGN.md"];
+const ALWAYS_INJECT = ["project.md", "tech-stack.md", "state.md"];
 
-function readTemplate(cwd: string, name: string): string | null {
+// Placeholder markers that indicate a template is still a blank seed (not filled).
+// Counted to decide whether an auto-injected file would just add noise to the
+// first message. Threshold is intentionally low (>5) so a genuinely filled live
+// file (a handful of incidental bracket occurrences) still injects.
+const PLACEHOLDER_MARKER_RE = /\[(?:e\.g\.|Criterion|URL|Title|Date|slug)[^\]]*\]|<slug>|<!-- /g;
+const PLACEHOLDER_MARKER_THRESHOLD = 5;
+
+function readTemplate(
+	cwd: string,
+	name: string,
+	skipPlaceholders = false,
+): string | null {
 	// Prefer live file at .pi/{name} (filled by /init — real project state);
 	// fall back to blank seed at .pi/templates/{name} when no live file exists.
 	const livePath = path.join(cwd, ".pi", name);
@@ -33,7 +51,17 @@ function readTemplate(cwd: string, name: string): string | null {
 	const content = fs.readFileSync(filePath, "utf-8");
 	// Strip frontmatter for injection
 	const fmMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-	return (fmMatch ? fmMatch[1] : content).trim();
+	const body = (fmMatch ? fmMatch[1] : content).trim();
+	// Auto-inject only: skip placeholder-heavy files so unfilled templates don't
+	// tax the first message. On-demand /inject-template bypasses this (default).
+	// Anchored to a closing `]` so real markdown links like `[Vercel](...)` don't
+	// count; only placeholder-shaped tokens (`[URL]`, `[Criterion 1]`, `[e.g., ...]`,
+	// `<slug>`, `<!-- `) do.
+	if (skipPlaceholders) {
+		const markers = body.match(PLACEHOLDER_MARKER_RE);
+		if (markers && markers.length > PLACEHOLDER_MARKER_THRESHOLD) return null;
+	}
+	return body;
 }
 
 export default function templatesInjector(pi: ExtensionAPI) {
@@ -41,7 +69,7 @@ export default function templatesInjector(pi: ExtensionAPI) {
 		const injected: string[] = [];
 
 		for (const name of ALWAYS_INJECT) {
-			const content = readTemplate(ctx.cwd, name);
+			const content = readTemplate(ctx.cwd, name, /* skipPlaceholders */ true);
 			if (content && content.length > 0) {
 				injected.push(`### ${name}\n\n${content}`);
 			}

package/dist/template/.pi/prompts/INDEX.md

@@ -4,7 +4,7 @@ purpose: Index of slash commands with purpose, when-to-use, and lifecycle positi
 
 # Prompts Index
 
-14 slash commands. Lifecycle is canonical; utilities attach at any phase.
+11 slash commands. Lifecycle is canonical; utilities attach at any phase.
 
 ## Canonical Lifecycle
 
@@ -39,9 +39,6 @@ Status:                 /status
 | `/gc` | Fallow analysis + quality grades + optional cleanup PRs | Maintenance cadence; not during active feature work | `[--dry-run] [--apply] [--scope <dir>]` | Maintenance |
 | `/status` | Show active feature, progress tail, blockers | Orient at session start or when unsure | `[--full]` | Any (read-only) |
 | `/close` | Finalize active feature, clear `.active` | Feature done/blocked/abandoned, or recover dangling `.active` | `[--done\|--blocked\|--abandoned] [--note <text>]` | Ship/Recovery |
-| `/loop-check` | NO-GO qualification gate — refuse-list + 2-condition test + 30s checklist | Before scheduling a task as an unattended loop | `<task description> [--help]` | Define |
-| `/loop-init` | Scaffold `.pi/loops/<name>/` from templates (VISION/STATE/SKILL) | Once a task passes /loop-check | `<name> [--help]` | Define |
-| `/loop-review` | Maker/checker gate — verifier subagent runs the gate, emits ACCEPT/REJECT | After a maker run, before ship | `<loop-name> [--help]` | Review |
 
 ## When to use what
 
@@ -57,9 +54,6 @@ Status:                 /status
 | "Where am I / what's the state" | `/status` |
 | Feature done but `/ship` left `.active` dangling | `/close --done` |
 | Maintenance / dead code sweep | `/gc --dry-run` |
-| Qualify a task as an unattended loop (refuse-list + 2-condition test) | `/loop-check "<task>"` (Define) |
-| Scaffold a loop after /loop-check returns GO | `/loop-init <name>` (Define) |
-| Maker/checker gate on a loop run before shipping | `/loop-review <name>` (Review) |
 
 ## Conventions (shared across commands)
 
@@ -73,6 +67,6 @@ Status:                 /status
 
 ## Related
 
-- `skills/INDEX.md` — task → skill routing (70 skills)
+- `skills/INDEX.md` — task → skill routing (67 skills)
 - `workflows/INDEX.md` — 6 DAG workflows invoked by commands
-- `templates/` — 19 template files (PRD, plan body, state, roadmap, loop-vision, loop-state, orchestrators, etc.)
+- `templates/` — 12 template files (PRD, plan body, state, roadmap, etc.)

package/dist/template/.pi/skills/INDEX.md

@@ -17,17 +17,22 @@ When the agent edits files matching these patterns, the listed skills auto-load.
 
 | File pattern | Auto-load skill(s) | Why |
 |-------------|-------------------|-----|
-| `*.ts,*.tsx,*.jsx` | `react-best-practices`, `deep-module-design` | TypeScript/React best practices + structural quality |
+| `*.ts,*.tsx,*.jsx` | `react-best-practices`, `deep-module-design`, `react-compiler` | TypeScript/React best practices + structural quality |
+| `**/actions.ts`, `**/actions/**` | `react-server-actions` | Server Actions + useActionState patterns |
+| `**/app/**/page.tsx`, `**/app/**/layout.tsx` | `nextjs-app-router`, `nextjs-cache` | App Router conventions + caching |
+| `**/stores/**`, `**/store.ts` | `zustand` | Zustand state management patterns |
+| `**/hooks/use-query*.ts`, `**/queries/**` | `tanstack-query` | TanStack Query hooks and patterns |
+| `**/forms/**` with `useForm`, `zodResolver` | `react-hook-form` | React Hook Form + Zod patterns |
 | `*.swift,*.swiftui` | `swift-concurrency`, `swiftui-expert-skill` | Swift patterns + concurrency safety |
 | `*.test.*,*.spec.*,__tests__/**` | `test-driven-development`, `testing-anti-patterns` | Test-first discipline + mock hygiene |
 | `*.sql,migrations/**` | `supabase-postgres-best-practices` | Query performance + RLS |
 | `.github/workflows/**,Dockerfile,docker-compose*.yml` | `ci-cd-and-automation` | Pipeline design + caching |
 | `.pi/skills/*/SKILL.md` | `writing-skills` | Skill authoring best practices |
-| `.pi/loops/**`,`loop-orchestrator.*`,`loop-guard.ts` | `loop-engineering`, `loop-audit` | Loop design/qualification + readiness scoring |
+
 | `*.css,*.scss,*.less` | `baseline-ui`, `frontend-design`, `design-taste-frontend` | Deslop pass + design system consistency |
 | `*.tsx,*.jsx` | `baseline-ui`, `frontend-ui-engineering` | Deslop pass + production-quality UI standards |
 | `*.md,docs/**,ADR*.md` | `documentation-and-adrs` | Doc structure + ADR format |
-| `.pi/**/DESIGN.md` | `frontend-design`, `design-taste-frontend` | Project design identity — load aesthetic skills when DESIGN.md is edited |
+| `.pi/**/DESIGN.md` | `frontend-design`, `design-taste-frontend` | Project design identity — load aesthetic skills when DESIGN.md is edited. NOTE: DESIGN.md is no longer auto-injected; load it into context on demand via `/inject-template DESIGN.md` when starting UI work. |
 
 ---
 
@@ -65,10 +70,19 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | payment, subscription, license, billing, checkout | `polar` |
 | Figma, design token, mockup, screenshot to code | `figma`, `mockup-to-code` |
 | Jira, Confluence, Atlassian, issue, ticket | `jira` |
+| v0, v0.sh, v0.dev, AI UI generator, Vercel v0, v0 component, v0 generate | `v0` |
+| shadcn, shadcn/ui, shadcn-ui, shadcn ui, shadcn component, shadcn add | `shadcn-ui` |
+| Server Actions, useActionState, useOptimistic, useFormStatus, 'use server', form action, progressive enhancement | `react-server-actions` |
+| App Router, layout.tsx, page.tsx, parallel routes, intercepting routes, route groups, async params, template.tsx, loading.tsx | `nextjs-app-router` |
+| use cache, cacheLife, cacheTag, revalidateTag, revalidatePath, Next.js cache, connection() | `nextjs-cache` |
+| React Compiler, auto-memoize, babel-plugin-react-compiler, useMemo, useCallback, memoization | `react-compiler` |
+| TanStack Query, React Query, useQuery, useMutation, optimistic update, infinite query, prefetch | `tanstack-query` |
+| Zustand, state management, global state, create store, useShallow, immer, persist, devtools | `zustand` |
+| React Hook Form, useForm, zodResolver, Controller, useFieldArray, form validation, conditional fields | `react-hook-form` |
 | browser, e2e, screenshot, playwright, chrome | `playwright`, `chrome-devtools`, `browser-testing-with-devtools` |
 | dependency, package, library, npm, PyPI, source | `opensrc` |
 | scrape, crawl, webclaw, bot protection, 403, webfetch fail, extract web content, web scraping | `webclaw` |
-| loop, unattended loop, nightly triage, loop-readiness, loop-cost, loop-check, loop-review | `loop-engineering`, `loop-audit`, `loop-cost` |
+
 | Swift, iOS, macOS, actor, async/await, Sendable | `swift-concurrency`, `swiftui-expert-skill`, `core-data-expert` |
 
 ---
@@ -111,9 +125,7 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | `dcp-hygiene` | At command/phase closure — compress closed exploratory work-streams via pi-dcp when `compress` is available; no-ops if DCP absent | All | Low |
 | `memory-system` | Understanding/leveraging pi-hermes-memory — auto-flywheel, tools, commands, when to use memory_search vs vcc_recall | All | Low |
 | `doubt-driven-development` | In-flight adversarial review of non-trivial decisions before they stand | Build | Medium |
-| `loop-engineering` | Designing/qualifying/running unattended coding loops; 2-condition test + VISION/state + confidence-gated action | All | Medium |
-| `loop-audit` | Scoring a project's loop-readiness 0-100 + L0/L1/L2/L3; L3 gated on proven run | Review | Low |
-| `loop-cost` | Estimating tokens/day + daily cap + early-exit flag before approving a loop budget | Plan | Low |
+
 
 ### Implementation
 
@@ -155,7 +167,14 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | `mockup-to-code` | Converting UI mockups, screenshots, Figma/Sketch designs into code | Build | Medium |
 | `oklch-color-workflow` | Complete OKLCH color system — syntax, palette generation, contrast, Tailwind v4 | Build | Low |
 | `production-hardening` | Production hardening — i18n, error states, edge cases, cross-browser | Ship | High |
-| `react-best-practices` | Writing, reviewing, or refactoring React/Next.js code for performance | Build | Medium |
+| `react-best-practices` | Writing, reviewing, or refactoring React 19 / Next.js 16 code for performance | Build | Medium |
+| `react-server-actions` | Building forms, mutations, data writes with React 19 Server Actions | Build | Medium |
+| `nextjs-app-router` | Building Next.js App Router pages — layouts, routes, RSC boundaries | Build | Medium |
+| `nextjs-cache` | Next.js 16 caching — `use cache`, cacheLife, cacheTag, revalidation | Build | Medium |
+| `react-compiler` | Enabling, debugging, optimizing with the React Compiler | Build | Low |
+| `tanstack-query` | Data fetching, caching, mutations with TanStack Query v5 | Build | Medium |
+| `zustand` | Global/shared state management with Zustand v5 | Build | Medium |
+| `react-hook-form` | Building forms with React Hook Form v7 + Zod v3 | Build | Medium |
 | `redesign-existing-projects` | Upgrading an existing website or app's visual design | Build | High |
 | `ui-craft-principles` | 16 craft principles — concentric radius, optical alignment, interruptible animations | Build | Low |
 | `ui-quality-audit` | 5-dimension UI quality scoring (0-4) with P0-P3 severity tags | Review | Medium |
@@ -197,6 +216,8 @@ When the user's prompt contains these keywords (case-insensitive), the listed sk
 | `opensrc` | Understanding how a library works internally, debugging dependency issues | Build | Low |
 | `pdf-extract` | Extracting text, images, tables, or metadata from PDF files | Build | Low |
 | `webclaw` | When webfetch returns 403 or bot protection errors | Build | Low |
+| `v0` | Using v0 (v0.app by Vercel) for AI-powered UI generation, prompt engineering, CLI/SDK integration | Build | Medium |
+| `shadcn-ui` | Setting up, configuring, or adding shadcn/ui components — CLI v4, presets, skills, registries | Build | Medium |
 | `gemini-large-context` | Analyzing large codebases, comparing multiple files exceeding typical context limits | Plan | Low |
 | `fallow` | Codebase intelligence — quality, dead code, duplication, complexity hotspots | Review | Low |
 
@@ -227,8 +248,18 @@ Maps user intent to skill(s). `→` = sequential pipeline (execute in order). `+
 | "I'm stuck" / "not sure what to do" | `behavioral-kernel` + `using-agent-skills` | All | Low |
 | "which skill to use" / "what skill for" | `using-agent-skills` | Define | Low |
 | "create UI" / "build component" / "design page" | `frontend-design` + `design-taste-frontend` | Build | Medium |
+| "generate with v0" / "v0 component" / "v0 prompt" / "AI generate UI" | `v0` + `frontend-design` | Build | Medium |
+| "add shadcn components" / "shadcn init" / "setup shadcn" / "shadcn/ui setup" | `shadcn-ui` + `frontend-design` | Build | Medium |
+| "Server Action" / "useActionState" / "useOptimistic" / "'use server'" | `react-server-actions` + `nextjs-app-router` | Build | Medium |
+| "App Router" / "layout.tsx" / "parallel route" / "intercepting route" | `nextjs-app-router` + `react-best-practices` | Build | Medium |
+| "use cache" / "revalidateTag" / "cacheLife" / "Next.js cache" | `nextjs-cache` + `nextjs-app-router` | Build | Medium |
+| "React Compiler" / "auto-memoize" / "useMemo unnecessary" | `react-compiler` + `react-best-practices` | Build | Low |
+| "useQuery" / "useMutation" / "TanStack Query" / "optimistic update" | `tanstack-query` + `zustand` | Build | Medium |
+| "Zustand" / "create store" / "useShallow" / "global state" | `zustand` + `tanstack-query` | Build | Medium |
+| "React Hook Form" / "useForm" / "zodResolver" / "useFieldArray" | `react-hook-form` + `react-server-actions` | Build | Medium |
 | "deploy to Cloudflare" | `cloudflare` | Ship | High |
 | "deploy to Vercel" | `vercel-deploy-claimable` | Ship | High |
+| "animate" / "animation" / "motion" / "framer" / "transition" | `frontend-design` (references/animation/) | Build | Low |
 | "set up database" / "Supabase" | `supabase` + `supabase-postgres-best-practices` | Build | High |
 | "add logging" / "monitoring" / "observability" | `observability-and-instrumentation` | Ship | Medium |
 | "optimize context" / "agent quality degraded" / "too many tokens" | `context-engineering` | All | Low |

package/dist/template/.pi/skills/dcp-hygiene/SKILL.md

@@ -16,7 +16,7 @@ description: "Use at command/phase closure points to compress closed exploratory
 - The `compress` tool is not registered (DCP extension not installed, or `compress.permission: "deny"`) — see No-op clause below.
 - The work-stream is still in-flight or spans your most recent turn — DCP turn protection (last 3 turns) already refuses these; don't try.
 - The user just asked about the content you'd be compressing — they still need it verbatim.
-- The command is read-only/scaffold and produced almost no tool output (`/status`, `/close`, `/loop-init`, `/loop-check`, `/loop-review`) — compressing near-empty streams wastes more tokens than it saves.
+- The command is read-only/scaffold and produced almost no tool output (`/status`, `/close`) — compressing near-empty streams wastes more tokens than it saves.
 - Inside orchestrator workflows' phase prompts — subagents carry their own context; only the orchestrator's accumulated summaries matter, and those are bounded by "Keep under N words" per prompt.
 
 ## Core Principle

package/dist/template/.pi/skills/frontend-design/SKILL.md

@@ -43,7 +43,7 @@ description: MUST load when building any web UI with React-based frameworks —
 
 Search: `@theme`, `@container`, `OKLCH`, `mask-`, `text-shadow`
 
-### shadcn/ui (CLI v3.6)
+### shadcn/ui (CLI v4.11)
 
 - `./references/shadcn/setup.md` - Installation, visual styles, component list
 - `./references/shadcn/core-components.md` - Button, Card, Dialog, Select, Tabs, Toast

package/dist/template/.pi/skills/frontend-design/references/animation/motion-advanced.md

@@ -1,13 +1,13 @@
 # Motion Advanced
 
-Scroll, orchestration, TypeScript, performance.
+Scroll, orchestration, TypeScript, AnimateView, performance.
 
 ## Scroll Animations
 
 ```tsx
 import { motion, useScroll, useTransform } from 'motion/react';
 
-// Scroll progress
+// Scroll progress (GPU-accelerated via ScrollTimeline API since v12.32)
 const { scrollYProgress } = useScroll();
 const opacity = useTransform(scrollYProgress, [0, 1], [1, 0]);
 
@@ -36,7 +36,7 @@ const scale = useTransform(scrollYProgress, [0, 0.5, 1], [0.8, 1, 0.8]);
 ## AnimatePresence Modes
 
 ```tsx
-// Wait for exit before enter
+// Wait for exit before enter (recommended for page transitions)
 <AnimatePresence mode="wait">
   <motion.div key={currentPage} />
 </AnimatePresence>
@@ -50,6 +50,37 @@ const scale = useTransform(scrollYProgress, [0, 0.5, 1], [0.8, 1, 0.8]);
 <AnimatePresence mode="sync" />
 ```
 
+## AnimateView (New — Motion+ Early Access)
+
+View Transitions wrapper for React. Enter/exit/update/share animations for page transitions:
+
+```tsx
+import { AnimateView } from 'motion/react'
+
+<AnimateView>
+  <motion.div
+    animate={{ opacity: 1, scale: 1 }}
+    initial={{ opacity: 0, scale: 0.95 }}
+  />
+</AnimateView>
+```
+
+Built on React 19.2 `ViewTransition` component. Works alongside Next.js 16 `experimental.viewTransition`.
+
+## arc() — Curved Motion Paths (v12.40+)
+
+```tsx
+import { arc } from 'motion/react'
+
+<motion.div
+  animate={{
+    x: 200,
+    y: -120,
+    transition: { path: arc() }
+  }}
+/>
+```
+
 ## Orchestration
 
 ```tsx
@@ -157,6 +188,24 @@ const prefersReduced = useReducedMotion();
 
 // Use layoutRoot to isolate layout calculations
 <motion.div layoutRoot />
+
+// Axis-locked layout (v12.35+) — cheaper than full layout
+<motion.div layout="x" />
+
+// Custom anchor point (v12.38+)
+<motion.div layoutAnchor={{ x: 0.5, y: 0.5 }} />
+```
+
+## CSS Color Support (v12.35+)
+
+Motion now supports modern CSS color formats:
+- `oklch()`, `oklab()`, `lab()`, `lch()`
+- `color-mix()`, `light-dark()`
+
+```tsx
+<motion.div
+  animate={{ backgroundColor: 'oklch(0.65 0.22 250)' }}
+/>
 ```
 
 ## Common Patterns
@@ -171,18 +220,28 @@ const prefersReduced = useReducedMotion();
 />
 ```
 
-### Page transitions
+### Page transitions (Next.js App Router)
 ```tsx
-<AnimatePresence mode="wait">
-  <motion.main
-    key={pathname}
-    initial={{ opacity: 0, x: 20 }}
-    animate={{ opacity: 1, x: 0 }}
-    exit={{ opacity: 0, x: -20 }}
-  >
-    {children}
-  </motion.main>
-</AnimatePresence>
+// app/template.tsx
+'use client'
+import { AnimatePresence, motion } from 'motion/react'
+import { usePathname } from 'next/navigation'
+
+export default function Template({ children }) {
+  const pathname = usePathname()
+  return (
+    <AnimatePresence mode="wait" initial={false}>
+      <motion.main
+        key={pathname}
+        initial={{ opacity: 0, x: 20 }}
+        animate={{ opacity: 1, x: 0 }}
+        exit={{ opacity: 0, x: -20 }}
+      >
+        {children}
+      </motion.main>
+    </AnimatePresence>
+  )
+}
 ```
 
 ### Expandable card
@@ -212,13 +271,27 @@ anime.js v4 still appropriate for:
 - Non-React projects
 
 ```javascript
-// anime.js for SVG morphing
 import { animate, svg } from 'animejs';
 animate('#path1', { d: svg.morphTo('#path2'), duration: 1 });
 ```
 
+## Library Comparison (2026)
+
+| Library | Bundle | React DX | Scroll | Gestures | Layout Anim |
+|---------|--------|----------|--------|----------|-------------|
+| **Motion** | ~85KB | 🏆 Best | Built-in | Built-in | Built-in |
+| GSAP | ~78KB | Imperative | ScrollTrigger | Draggable | Flip plugin |
+| React Spring | ~45KB | Good | External | ❌ | ❌ |
+| Anime.js | ~52KB | Imperative | External | ❌ | ❌ |
+| TailwindCSS Motion | ~5KB | Good | Built-in | ❌ | ❌ |
+
+**Verdict**: Motion for React-first projects with complex interactions. GSAP for marketing sites with complex timelines. React Spring for physics-driven natural motion. Anime.js for SVG path animations.
+
 ## Installation
 
 ```bash
 npm install motion
+# or migrate from framer-motion:
+npm uninstall framer-motion && npm install motion
+# swap imports: "framer-motion" → "motion/react"
 ```

package/dist/template/.pi/skills/frontend-design/references/animation/motion-core.md

@@ -1,6 +1,9 @@
 # Motion Core (motion/react)
 
-**Import**: `import { motion, AnimatePresence } from 'motion/react'`
+**Package**: `motion` (v12.40.0). Formerly "framer-motion".
+**Import**: `import { motion, AnimatePresence, useScroll, useTransform } from 'motion/react'`
+
+Framer Motion rebranded to **Motion** in November 2024. Both `motion` and `framer-motion` packages published in lockstep. New projects use `motion`. No breaking changes in v12 for React.
 
 ## Motion Principles
 
@@ -8,6 +11,8 @@
 - Use motion to explain state change and hierarchy
 - Prefer subtle distance (`8-16px`) and opacity shifts
 - Use consistent timing/easing system across the app
+- Let Tailwind handle static styles; Motion handles behavior
+- **Remove `transition-*` Tailwind classes from motion elements** — they conflict
 
 ## Timing System
 
@@ -19,6 +24,7 @@
 | Large entrances               | 500-800ms  |
 
 **Rule**: exit duration = ~75% of enter duration.
+**Never exceed 600ms for UI responsiveness.**
 
 ## Easing System
 
@@ -29,20 +35,20 @@ const EASING_ENTER = [0.16, 1, 0.3, 1];
 const EASING_EXIT = [0.4, 0, 1, 1];
 ```
 
-Avoid bounce/elastic easings for product UI.
+Avoid bounce/elastic easings for product UI. Motion's hybrid engine runs animations natively via Web Animations API (WAAPI) and ScrollTimeline for 120fps GPU performance, falling back to JS only for spring physics and gestures.
 
 ## Performance Rules
 
 Animate only compositor-friendly properties:
 
-- `transform`
+- `transform` (x, y, scale, rotate, skew)
 - `opacity`
 
 Avoid animating:
 
-- `width`, `height`
-- `top`, `left`
-- `margin`, `padding`
+- `width`, `height` — triggers layout recalculation
+- `top`, `left` — use `x`/`y` instead
+- `margin`, `padding`, `border`
 
 ## Basic Pattern
 
@@ -54,6 +60,101 @@ Avoid animating:
 />
 ```
 
+## React 19 + Next.js 15/16
+
+### Page Transitions (App Router)
+
+**Critical**: Use `template.tsx`, NOT `layout.tsx`. Layout persists across routes and never remounts.
+
+```tsx
+// app/template.tsx
+'use client'
+
+import { AnimatePresence, motion } from 'motion/react'
+import { usePathname } from 'next/navigation'
+
+export default function Template({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname()
+  return (
+    <AnimatePresence mode="wait" initial={false}>
+      <motion.div
+        key={pathname}
+        initial={{ opacity: 0, y: 8 }}
+        animate={{ opacity: 1, y: 0 }}
+        exit={{ opacity: 0, y: -8 }}
+        transition={{ duration: 0.18, ease: 'easeInOut' }}
+        style={{ minHeight: 'var(--page-min-height, 100dvh)' }}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  )
+}
+```
+
+### Dynamic Import (Performance)
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const AnimatedWrapper = dynamic(() => import('@/components/animated-wrapper'), {
+  ssr: false,
+  loading: ({ children }) => <>{children}</>,
+})
+```
+
+### React 19.2 View Transitions
+
+Next.js 16 + React 19.2 support native View Transitions via `experimental.viewTransition: true`. Motion's `AnimateView` (premium) builds on this.
+
+## Integration with shadcn/ui
+
+**Architecture**: shadcn/ui = structure + accessibility. Motion = behavior + animation. Wrap/extend shadcn components — don't replace.
+
+```
+src/
+├── components/
+│   ├── ui/              # shadcn generated (untouched)
+│   └── animated/        # Motion-wrapped shadcn components
+│       ├── AnimatedButton.tsx
+│       ├── AnimatedDialog.tsx
+│       └── ...
+└── lib/
+    └── animations.ts    # Shared variants & transition configs
+```
+
+### Shared Variants Pattern
+
+```ts
+// lib/animations.ts
+import type { Variants, Transition } from 'motion/react'
+
+export const fadeIn: Variants = {
+  initial: { opacity: 0 },
+  animate: { opacity: 1 },
+  exit: { opacity: 0 },
+}
+
+export const slideUp: Variants = {
+  initial: { opacity: 0, y: 20 },
+  animate: { opacity: 1, y: 0 },
+  exit: { opacity: 0, y: 20 },
+}
+
+export const spring: Transition = {
+  type: 'spring',
+  stiffness: 300,
+  damping: 25,
+}
+```
+
+### Installation Order
+
+1. `npx shadcn init` + add components
+2. `npm install motion`
+3. Create `lib/animations.ts` for shared variants
+4. Create `components/animated/` directory for wrapped components
+
 ## Variants Pattern (Recommended)
 
 ```tsx
@@ -69,8 +170,6 @@ const card = {
 <motion.div variants={card} initial="hidden" animate="visible" />
 ```
 
-Use variants for shared timing and maintainability.
-
 ## Exit Animations (AnimatePresence)
 
 ```tsx
@@ -87,7 +186,7 @@ Use variants for shared timing and maintainability.
 </AnimatePresence>
 ```
 
-Always provide stable `key` values for exiting elements.
+Always provide stable `key` values. Use `mode="wait"` to prevent overlapping DOM elements.
 
 ## Stagger Patterns
 
@@ -123,6 +222,9 @@ Use `layout` for reordering and size changes. Add spring only when needed:
 <motion.div layout transition={{ type: 'spring', stiffness: 320, damping: 28 }} />
 ```
 
+**New (v12.35+)**: Axis-locked layout: `layout="x"` or `layout="y"`.
+**New (v12.38+)**: Custom anchor: `layoutAnchor={{ x: 0.5, y: 0.5 }}`.
+
 ## Gestures
 
 ```tsx
@@ -133,7 +235,7 @@ Use `layout` for reordering and size changes. Add spring only when needed:
 />
 ```
 
-Keep gesture amplitudes subtle (`0.98-1.03`).
+Keep gesture amplitudes subtle (`0.98-1.03`). Available: `whileHover`, `whileTap`, `whileFocus`, `whileDrag`, `whileInView`.
 
 ## Height Expand/Collapse (No height animation)
 
@@ -168,14 +270,47 @@ Use CSS grid technique:
 }
 ```
 
-For motion/react, switch spatial movement to opacity-only when reduced motion is enabled.
+For motion/react, use `useReducedMotion()`:
+
+```tsx
+import { useReducedMotion } from 'motion/react'
+
+const prefersReduced = useReducedMotion()
+
+<motion.div
+  animate={prefersReduced ? {} : { scale: 1.1 }}
+/>
+```
+
+## Motion AI Kit
+
+Official Motion AI tools (premium, Motion+ required):
+```bash
+npx motion-ai     # Install MCP server + skills for Claude Code, Cursor, Windsurf, etc.
+```
+
+Provides: 400+ premium examples, MotionScore runtime profiling, CSS spring generation, transition editing.
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| `layout.tsx` for AnimatePresence (CLS) | Use `template.tsx` with `mode="wait"` |
+| `transition-*` classes on motion elements | Remove Tailwind transition classes |
+| Animating `width`/`height` | Use `scaleX`/`scaleY` or grid technique |
+| Missing `use client` in Next.js | Extract animation to client component |
+| `mode="sync"` with page transitions | Use `mode="wait"` to prevent overlap |
+| Duration > 600ms for UI | Cap at 600ms; reserve long durations for storytelling |
 
 ## Quick Checklist
 
-- [ ] Uses `motion/react` import
+- [ ] Uses `motion/react` import (not `framer-motion`)
 - [ ] Timing follows 100/300/500ms system
 - [ ] Exponential easing, no bounce/elastic
 - [ ] Animates only `transform` and `opacity`
 - [ ] Uses `AnimatePresence` for exit states
-- [ ] Includes reduced motion support
+- [ ] Includes reduced motion support (CSS + `useReducedMotion()`)
 - [ ] Stagger windows stay under 500ms
+- [ ] Next.js: uses `template.tsx` not `layout.tsx`
+- [ ] No `transition-*` classes on motion elements
+- [ ] shadcn/ui: animated components in `components/animated/`