tailwind-styled-v4 1.0.0 → 1.0.1

package/README.md

@@ -1,50 +1,70 @@
-# tailwind-styled-v4
+# 🎨 tailwind-styled-v4
 
-**PRO Engine** — styled-components + Tailwind CSS v4, zero-runtime compile option, variant system, responsive props, plugin ecosystem.
+> **styled-components meets Tailwind CSS** — dengan type safety penuh, zero DOM pollution, dan zero-runtime build output.
 
-> Melampaui `twin.macro` dengan tetap kompatibel penuh terhadap Next.js 16 · React 19 · Tailwind CSS v4 · styled-components v6 · TypeScript 5 · shadcn/ui.
+```tsx
+const Button = tw.button({
+  base: "px-4 py-2 rounded-lg font-medium transition",
+  variants: {
+    variant: {
+      primary: "bg-blue-500 text-white hover:bg-blue-600",
+      ghost:   "bg-transparent border hover:bg-zinc-800",
+    },
+    size: { sm: "h-8 text-sm", lg: "h-12 text-base" },
+  },
+  defaultVariants: { variant: "primary", size: "sm" },
+})
+
+<Button variant="primary" size="lg" p={4} rounded="card" />
+```
+
+---
+
+## ✨ Fitur Utama
+
+| Fitur | Keterangan |
+|-------|------------|
+| 🧱 **styled-components API** | Familiar, chainable, SSR-safe |
+| 🎭 **Variant System** | `variants`, `compoundVariants`, `defaultVariants` |
+| 📐 **Responsive Props** | `p={{ sm: 2, lg: 8 }}` — responsive object syntax |
+| 🎨 **Design Tokens** | `bg="primary"` → `bg-blue-600` via theme store |
+| ⚡ **Zero-Runtime** | Build-time transform → static `className` strings |
+| 🔌 **Plugin System** | Register custom prop resolvers |
+| 🛡️ **Type Safe** | Full TypeScript generics & inference |
+| 🚫 **Zero DOM Pollution** | Props tidak bocor ke HTML attributes |
 
 ---
 
-## Installation
+## 📦 Instalasi
 
 ```bash
-npm install tailwind-styled-v4
-# peerDependencies
-npm install styled-components tailwind-merge clsx
+npm install tailwind-styled-v4 styled-components tailwind-merge
 ```
 
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
-### Template Literal (sederhana)
+### 1️⃣ Template Literal (paling simpel)
 
 ```tsx
 import { tw } from "tailwind-styled-v4"
 
-const Card = tw.div`
-  p-6
-  bg-zinc-900
-  rounded-2xl
-  border border-zinc-800
-`
-
-// Responsive props inline
-<Card p={{ base: 4, md: 6, lg: 8 }} />
-// → p-4 md:p-6 lg:p-8
+const Box   = tw.div`p-4 bg-zinc-900 rounded-xl`
+const Title = tw.h1`text-2xl font-bold text-white`
+const Badge = tw.span`px-2 py-1 rounded-full text-xs bg-blue-500 text-white`
 ```
 
-### Object Config (full power)
+### 2️⃣ Object Config + Variants
 
 ```tsx
 const Button = tw.button({
-  base: "inline-flex items-center justify-center rounded-lg font-medium transition",
+  base: "inline-flex items-center font-medium transition rounded-lg",
   variants: {
     variant: {
-      primary: "bg-blue-600 text-white hover:bg-blue-700",
+      primary: "bg-blue-500 text-white hover:bg-blue-600",
       ghost:   "bg-transparent border border-zinc-700 hover:bg-zinc-800",
-      danger:  "bg-red-600 text-white hover:bg-red-700",
+      danger:  "bg-red-500 text-white hover:bg-red-600",
     },
     size: {
       sm: "h-8  px-3 text-sm",
@@ -53,278 +73,536 @@ const Button = tw.button({
     },
   },
   compoundVariants: [
-    { variant: "primary", size: "lg", class: "shadow-lg shadow-blue-600/30" },
+    { variant: "primary", size: "lg", class: "shadow-lg shadow-blue-500/30" },
   ],
   defaultVariants: { variant: "primary", size: "md" },
 })
 
 // Usage
-<Button variant="primary" size="lg">Click me</Button>
-<Button variant="ghost" size="sm">Cancel</Button>
+<Button variant="ghost" size="lg" />
+<Button variant="danger" />
 ```
 
-### Extend existing component
+### 3️⃣ Prop Shorthand (responsive-ready)
 
 ```tsx
-const HeroCard = Card.extend`shadow-2xl ring-1 ring-zinc-700/50`
+// Scalar
+<Box p={4} bg="zinc-900" rounded="xl" flex />
+
+// Responsive object
+<Box p={{ base: 2, md: 4, lg: 8 }} cols={{ sm: 1, md: 2, lg: 3 }} />
+
+// Design token
+<Box bg="primary" text="foreground" rounded="card" shadow="modal" />
 ```
 
-### Wrap any component (shadcn/ui, Radix, dll)
+### 4️⃣ Extend Component
 
 ```tsx
-import { withTw, tw } from "tailwind-styled-v4"
-import { Button } from "@/components/ui/button"   // shadcn
-import Link from "next/link"
-
-const TwButton = withTw(Button, "px-4 py-2")
-const NavLink  = tw(Link)`text-zinc-400 hover:text-zinc-100 transition-colors`
+const Card    = tw.div`p-6 rounded-2xl bg-zinc-900`
+const HeroCard = Card.extend`shadow-2xl ring-1 ring-zinc-700`
+const DarkCard = Card.withVariants({
+  variants: { elevated: { true: "shadow-2xl", false: "" } }
+})
 ```
 
-### Standalone class variants (headless/shadcn compatible)
+### 5️⃣ Wrap Komponen Apapun
 
 ```tsx
-import { cv } from "tailwind-styled-v4"
+// shadcn/ui, Radix, komponen custom
+const TwButton  = withTw(Button, "px-4 py-2")
+const TwDialog  = tw(Dialog.Content)`p-6 rounded-2xl`
+
+<TwButton p={4} rounded="xl" bg="zinc-900" />
+```
+
+---
+
+## 🎭 Variant System
 
-const badgeCv = cv({
-  base: "inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium",
+### Basic Variants
+
+```tsx
+const Alert = tw.div({
+  base: "p-4 rounded-lg border",
   variants: {
-    color: {
-      blue:  "bg-blue-100 text-blue-800",
-      green: "bg-green-100 text-green-800",
-      red:   "bg-red-100 text-red-800",
-    }
+    status: {
+      info:    "bg-sky-50    border-sky-200   text-sky-800",
+      success: "bg-emerald-50 border-emerald-200 text-emerald-800",
+      warning: "bg-amber-50  border-amber-200  text-amber-800",
+      danger:  "bg-red-50    border-red-200    text-red-800",
+    },
   },
-  defaultVariants: { color: "blue" }
+  defaultVariants: { status: "info" },
 })
+```
+
+### Compound Variants
+
+```tsx
+// Class tambahan ketika 2+ variant aktif bersamaan
+compoundVariants: [
+  { variant: "primary", size: "lg", class: "shadow-lg shadow-blue-500/30" },
+  { variant: "ghost",   size: "sm", class: "opacity-70" },
+]
+```
+
+### withVariants — tambah variant ke komponen existing
 
-// Use anywhere
-<span className={badgeCv({ color: "green" })}>Active</span>
+```tsx
+const EnhancedButton = Button.withVariants({
+  variants: {
+    loading: { true: "opacity-50 cursor-not-allowed", false: "" }
+  }
+})
 ```
 
 ---
 
-## Responsive Props
+## 📐 Prop Engine
+
+Semua prop otomatis di-convert ke Tailwind class. Tidak perlu `className="..."`.
+
+### Spacing
+```tsx
+<Box p={4} px={6} py={2} m="auto" mx={4} gap={3} />
+// → p-4 px-6 py-2 m-auto mx-4 gap-3
+```
+
+### Flexbox & Grid
+```tsx
+<Box flex items="center" justify="between" wrap />
+<Box cols={3} rows={2} colSpan={2} gap={4} />
+// → flex items-center justify-between flex-wrap
+// → grid-cols-3 grid-rows-2 col-span-2 gap-4
+```
+
+### Colors & Typography
+```tsx
+<Box bg="zinc-900" text="white" border ring="blue-500" />
+<Box fontSize="heading" font="sans" leading="relaxed" tracking="tight" />
+```
 
-Semua props mendukung responsive object:
+### Layout & Position
+```tsx
+<Box pos="absolute" top={0} right={0} z={50} inset="x-4" />
+<Box overflow="hidden" rounded="xl" shadow="card" opacity={90} />
+```
 
+### Responsive Object
 ```tsx
+// Semua prop mendukung responsive object
 <Box
   p={{ base: 2, sm: 4, md: 6, lg: 8 }}
-  cols={{ base: 1, sm: 2, lg: 3 }}
-  gap={{ base: 3, md: 4 }}
-  display="grid"
+  cols={{ base: 1, md: 2, lg: 3 }}
+  hidden={{ base: true, md: false }}
 />
-// → p-2 sm:p-4 md:p-6 lg:p-8 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3 md:gap-4
-```
-
-### Available Props
-
-| Category | Props |
-|----------|-------|
-| **Padding** | `p` `px` `py` `pt` `pb` `pl` `pr` |
-| **Margin** | `m` `mx` `my` `mt` `mb` `ml` `mr` |
-| **Gap** | `gap` `gapX` `gapY` `spaceX` `spaceY` |
-| **Sizing** | `w` `h` `size` `minW` `maxW` `minH` `maxH` |
-| **Colors** | `bg` `text` `border` `ring` `fill` `stroke` |
-| **Typography** | `font` `fontSize` `leading` `tracking` `align` `truncate` `lineClamp` |
-| **Flexbox** | `flex` `flexDir` `items` `justify` `wrap` `grow` `shrink` `basis` `self` |
-| **Grid** | `cols` `rows` `colSpan` `rowSpan` `colStart` `colEnd` |
-| **Layout** | `display` `overflow` `pos` `z` `top` `right` `bottom` `left` `inset` |
-| **Border** | `rounded` `roundedT` `roundedB` `borderStyle` `outline` |
-| **Effects** | `opacity` `shadow` `blur` `brightness` `contrast` `grayscale` `backdrop` |
-| **Motion** | `transition` `duration` `ease` `delay` `animate` |
-| **Interaction** | `cursor` `select` `pointer` `touch` |
+```
 
 ---
 
-## Zero-Runtime (Next.js)
-
-Di production build, semua `tw.tag\`...\`` dikompilasi menjadi static string — zero JS runtime overhead.
+## 🎨 Theme & Design Tokens
 
-```ts
-// next.config.ts
-import { withTailwindStyled } from "tailwind-styled-v4/compiler"
+### Setup
 
-export default withTailwindStyled({
-  mode: "zero-runtime",    // "runtime" di dev, "zero-runtime" di production
-  addDataAttr: true,        // data-tw="tw-3f2a1" untuk DevTools
-  generateSafelist: true,   // auto-generate tailwind.safelist.json
-})(/** nextConfig */ {})
+```tsx
+// app/layout.tsx
+import { loadDefaultTheme } from "tailwind-styled-v4"
+loadDefaultTheme()
 ```
 
-**Before (source):**
+### Custom Theme
+
 ```tsx
-const Box = tw.div`p-4 bg-zinc-900 rounded-xl`
+import { setTheme } from "tailwind-styled-v4"
+
+setTheme({
+  colors: {
+    primary:    "blue-600",
+    secondary:  "violet-600",
+    brand:      "cyan-400",
+    background: "zinc-950",
+    surface:    "zinc-900",
+    muted:      "zinc-500",
+  },
+  radius: {
+    card:   "2xl",
+    button: "lg",
+    badge:  "full",
+    input:  "md",
+  },
+  spacing: {
+    section: "16",
+    page:    "24",
+  },
+  duration: {
+    fast:   "150",
+    normal: "200",
+    slow:   "300",
+  },
+})
 ```
 
-**After (compiled output):**
+### Penggunaan Token
+
 ```tsx
-const Box = styled.div.attrs(() => ({ className: "p-4 bg-zinc-900 rounded-xl" }))``
+// Token otomatis di-resolve
+<Box bg="primary" />          // → bg-blue-600
+<Box rounded="card" />        // → rounded-2xl
+<Box p="section" />           // → p-16
+<Box duration="fast" />       // → duration-150
 ```
 
-Runtime cost: **0 bytes** untuk class resolution.
-
 ---
 
-## Zero-Runtime (Vite)
+## 🎯 cv() — Standalone Class Variants
 
-```ts
-// vite.config.ts
-import { tailwindStyledPlugin } from "tailwind-styled-v4/compiler"
+Cocok untuk **shadcn/ui**, **Radix UI**, atau komponen headless apapun tanpa styled-components.
 
-export default defineConfig({
-  plugins: [react(), tailwindStyledPlugin({ mode: "zero-runtime" })],
+```tsx
+import { cv } from "tailwind-styled-v4"
+
+const buttonVariants = cv({
+  base: "inline-flex items-center rounded-lg font-medium transition",
+  variants: {
+    variant: {
+      primary: "bg-blue-500 text-white hover:bg-blue-600",
+      ghost:   "bg-transparent border hover:bg-zinc-800",
+    },
+    size: {
+      sm: "h-8  px-3 text-sm",
+      md: "h-10 px-4 text-sm",
+      lg: "h-12 px-6 text-base",
+    },
+  },
+  compoundVariants: [
+    { variant: "primary", size: "lg", class: "shadow-lg" }
+  ],
+  defaultVariants: { variant: "primary", size: "md" },
 })
+
+// Pakai di komponen apapun
+function Button({ variant, size, className, ...props }) {
+  return <button className={buttonVariants({ variant, size, className })} {...props} />
+}
 ```
 
 ---
 
-## Plugin System
+## 🔌 Plugin System
+
+### Built-in Plugins
+
+```tsx
+import { loadBuiltinPlugins } from "tailwind-styled-v4"
+loadBuiltinPlugins()
+
+// Setelah load, props berikut tersedia:
+<Box motionSafe backdropBlur="md" gradientFrom="blue-500" gradientTo="purple-500" />
+<Box scrollSmooth printHidden autoRows="fr" />
+```
+
+### Tailwind v4 Plugins
+
+```tsx
+import { loadAllV4Plugins } from "tailwind-styled-v4"
+loadAllV4Plugins()
+
+// Typography
+<article prose="lg" proseDark proseMaxW={false} />
+// → prose prose-lg dark:prose-invert max-w-none
+
+// Forms
+<input formInput />
+<select formSelect />
+
+// Aspect Ratio
+<div aspectRatio="video" />    // → aspect-video
+<div aspectRatio="square" />   // → aspect-square
+
+// Animations
+<div enterAnim="fade-up" />    // → animate-in fade-in slide-in-from-bottom-4
+<div exitAnim="fade" />        // → animate-out fade-out
+
+// Interactivity
+<button hoverBg="zinc-800" hoverScale focusRing="blue-500" activeScale />
+
+// Container Queries
+<div cqContainer />            // → @container
+```
+
+### Custom Plugin
 
 ```tsx
 import { registerPlugin } from "tailwind-styled-v4"
 
-// Custom plugin
 registerPlugin({
   name: "glass",
   props: {
-    glass:   v => v === true ? "bg-white/10 backdrop-blur-xl border border-white/10" : "",
-    frosted: v => v === true ? "bg-white/5 backdrop-blur-md saturate-150" : "",
-  }
+    glass: (v) => v === true
+      ? "backdrop-blur-md bg-white/10 border border-white/20"
+      : `backdrop-blur-${v} bg-white/10`,
+  },
 })
 
-// Usage
-<Box glass />     // → bg-white/10 backdrop-blur-xl border border-white/10
-<Box frosted />   // → bg-white/5 backdrop-blur-md saturate-150
+// Langsung bisa dipakai
+<Box glass />
+<Box glass="xl" />
 ```
 
-### Built-in Plugins
+---
+
+## ⚡ Zero-Runtime Mode
+
+### Next.js
+
+```ts
+// next.config.ts
+import { withTailwindStyled } from "tailwind-styled-v4/compiler"
+
+export default withTailwindStyled({
+  mode: "zero-runtime",   // transform tw.div`...` → static className
+  addDataAttr: true,       // tambah data-tw="hash" untuk DevTools
+})(nextConfig)
+```
+
+### Vite
+
+```ts
+// vite.config.ts
+import { tailwindStyledPlugin } from "tailwind-styled-v4/compiler"
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindStyledPlugin({ mode: "zero-runtime" }),
+  ],
+})
+```
 
+**Before:**
 ```tsx
-import { loadBuiltinPlugins } from "tailwind-styled-v4"
-loadBuiltinPlugins()  // animation, grid, backdrop, gradient, scroll, print
+const Box = tw.div`p-4 bg-zinc-900 rounded-xl`
+```
+
+**After (build output):**
+```tsx
+const Box = styled.div.attrs(() => ({ className: "p-4 bg-zinc-900 rounded-xl" }))``
 ```
 
+> 🚀 Nol JS runtime cost — `className` jadi static string, bukan computed di setiap render.
+
 ---
 
-## Theme System
+## 🛡️ shouldForwardProp
+
+Semua tw props **otomatis diblokir** dari forwarding ke DOM. Tidak ada warning `Unknown prop` di console.
 
 ```tsx
-import { setTheme, loadDefaultTheme, loadDarkTheme } from "tailwind-styled-v4"
+// ✅ Tidak ada warning di DOM
+<Box p={4} flex cols={3} bg="zinc-900" />
 
-// Preset themes
-loadDefaultTheme()  // semantic tokens: primary, surface, muted, dll
-loadDarkTheme()     // fintech/crypto/Web3 dark preset
+// Transient props ($) selalu di-forward
+<Box $isActive={true} />
 
-// Custom tokens
-setTheme({
-  colors: {
-    brand:    "blue-600",
-    "brand-hover": "blue-700",
-    surface:  "zinc-900",
-  },
-  radius: {
-    card:   "2xl",
-    button: "lg",
-  },
+// Manual block/allow
+import { blockProp, allowProp } from "tailwind-styled-v4"
+blockProp("customProp")
+allowProp("size")  // kalau mau size sampai ke DOM
+```
+
+---
+
+## 🧪 Validation (Dev Only)
+
+```tsx
+import { validateVariantProps, buildSchema } from "tailwind-styled-v4"
+
+const schema = buildSchema("button", {
+  variant: { primary: "...", ghost: "..." },
+  size:    { sm: "...", lg: "..." },
 })
 
-// Now works everywhere
-<Box bg="brand" rounded="card" />
-// → bg-blue-600 rounded-2xl
+validateVariantProps({ variant: "invalid" }, schema)
+// [tw-error] Invalid prop "variant"="invalid" on <button>
+//   Expected one of: "primary" | "ghost"
+//   Got: "invalid"
+//   Hint: Add "invalid" to the variants config, or fix the typo.
 ```
 
+> ⚠️ Validation hanya aktif di `NODE_ENV !== "production"` — **zero overhead di production**.
+
 ---
 
-## Safelist Generation
+## 🔧 Utils
 
-```bash
-npm run build:safelist
-```
+### cx / cxm
 
-Menghasilkan `tailwind.safelist.json` yang bisa direferensikan di `tailwind.config.ts`:
+```tsx
+import { cx, cxm } from "tailwind-styled-v4"
 
-```ts
-// tailwind.config.ts
-import safelist from "./tailwind.safelist.json"
+// cx — lightweight class joiner
+cx("p-4", isActive && "bg-blue-500", ["rounded", "shadow"])
+cx({ "p-4": true, "hidden": false })
 
-export default {
-  safelist: safelist.safelist,
-  // ...
-}
+// cxm — cx + tailwind-merge (conflict resolution)
+cxm("p-2", "p-4")   // → "p-4"  (p-2 dihapus)
 ```
 
----
+### Class Parser
 
-## IntelliSense (VSCode)
+```tsx
+import { parseClassString, splitModifiers, groupByModifier } from "tailwind-styled-v4"
 
-Library ini menyertakan **58.055 class definitions** di `src/types/tailwind.generated.ts` untuk autocomplete penuh di VSCode termasuk semua modifier:
+splitModifiers("p-4 hover:bg-blue-500 md:p-8")
+// → { base: ["p-4"], modifiers: ["hover:bg-blue-500", "md:p-8"] }
 
-```
-bg-blue-500          ← base class
-hover:bg-blue-500    ← hover state
-md:bg-blue-500       ← responsive
-dark:bg-blue-500     ← dark mode
-dark:hover:bg-blue-500 ← combined
+groupByModifier("p-4 hover:bg-blue-500 hover:text-white")
+// → { "": ["p-4"], hover: ["bg-blue-500", "text-white"] }
 ```
 
-Tambahkan ke `.vscode/settings.json`:
-```json
-{
-  "tailwindCSS.experimental.classRegex": [
-    ["tw\\.\\w+`([^`]*)`", "([^`]*)"],
-    ["tw\\.\\w+\\(([^)]*)\\)", "\"([^\"]*)\""],
-    ["cv\\(([^)]*)\\)", "\"([^\"]*)\""]
-  ]
-}
+### Safelist Generator
+
+```tsx
+import { generateSafelist } from "tailwind-styled-v4/compiler"
+
+generateSafelist({
+  cwd: process.cwd(),
+  scanDirs: ["src", "app", "components"],
+  outputPath: "tailwind.safelist.json",
+})
+// ✓ Safelist: 247 classes → /project/tailwind.safelist.json
 ```
 
 ---
 
-## Scripts
+## 📁 Struktur Engine
 
-```bash
-npm run build           # build library
-npm run build:types     # regenerate 58k class types
-npm run build:safelist  # scan src/ dan generate safelist
-npm run dev             # watch mode
-npm run test            # run all tests
+```
+src/
+├── core/
+│   ├── tw.ts              🎯 Proxy-free tw object (v2 fix)
+│   ├── createComponent.ts 🏗️  Single styled-chain factory
+│   ├── templateParser.ts  📝 Tagged template literal parser
+│   ├── cv.ts              🎭 Standalone class variants
+│   ├── withTw.ts          🔌 HOC wrapper untuk komponen apapun
+│   └── styledFactory.ts   🏭 Thin styled-components wrapper
+│
+├── runtime/
+│   ├── propEngine.ts      ⚙️  80+ prop → class resolvers
+│   ├── variantEngine.ts   🎭 Variant resolution
+│   ├── compoundVariant.ts 🔀 Compound variant resolution
+│   ├── responsiveEngine.ts📐 Responsive object handler
+│   └── classResolver.ts   🔗 Full pipeline orchestrator
+│
+├── theme/
+│   ├── themeStore.ts      🎨 Global token store
+│   ├── tokenResolver.ts   🔑 Token → class segment resolver
+│   └── defaultTheme.ts    📦 Ready-to-use semantic tokens
+│
+├── plugins/
+│   ├── pluginEngine.ts    🔌 Plugin registry & resolver
+│   ├── registerPlugin.ts  📋 Public plugin registration API
+│   ├── builtinPlugins.ts  🧰 Animation, grid, backdrop, gradient
+│   └── tailwindV4Plugins.ts 🆕 Typography, forms, aspect, animations
+│
+├── compiler/
+│   ├── astTransform.ts    🔄 Source code transformer (zero-runtime)
+│   ├── transformTw.ts     🛠️  Transform orchestrator
+│   ├── vitePlugin.ts      ⚡ Vite/Rollup plugin
+│   ├── swcPlugin.ts       🔧 Next.js SWC transform
+│   ├── webpackLoader.ts   📦 Webpack loader
+│   └── classExtractor.ts  🔍 Class extraction for safelist
+│
+├── validation/
+│   └── propValidator.ts   🛡️  Dev-only prop validation
+│
+└── utils/
+    ├── cx.ts              🔗 Lightweight class joiner
+    ├── classParser.ts     🔤 Class string utilities
+    ├── hash.ts            #️⃣  Stable hash generator
+    ├── merge.ts           🔀 twMerge wrapper
+    └── isObject.ts        🔍 Type guard utility
 ```
 
 ---
 
-## Comparison
-
-| Feature | tailwind-styled-v4 | twin.macro | CVA | Stitches |
-|---------|--------------------|------------|-----|----------|
-| Template literal | ✅ | ✅ | ❌ | ❌ |
-| Object config + variants | ✅ | ❌ | ✅ | ✅ |
-| Compound variants | ✅ | ❌ | ✅ | ✅ |
-| Responsive props | ✅ | ❌ | ❌ | ❌ |
-| Zero-runtime | ✅ | ✅ | ❌ | ✅ |
-| Plugin system | ✅ | ❌ | ❌ | ❌ |
-| styled-components compat | ✅ | ✅ | ❌ | ❌ |
-| shadcn/ui compat | ✅ | ❌ | ✅ | ❌ |
-| Theme/token system | ✅ | ❌ | ❌ | ✅ |
-| IntelliSense 58k classes | ✅ | ✅ | ❌ | ❌ |
-| Wrap any component | ✅ | ❌ | ❌ | ❌ |
+## 🧪 Test Coverage
+
+```
+228 tests — 228 pass ✅
+
+🔵 templateParser       9/9
+🔵 themeStore           7/7
+🔵 tokenResolver        7/7
+🔵 defaultTheme         2/2
+🔵 responsiveEngine     7/7
+🔵 variantEngine        5/5
+🔵 compoundVariant      5/5
+🔵 propEngine          15/15
+🔵 classResolver        2/2
+🔵 pluginEngine         4/4
+🔵 registerPlugin       3/3
+🔵 builtinPlugins       7/7
+🔵 tailwindV4Plugins   14/14
+🔵 cv                   4/4
+🔵 propValidator        6/6
+🔵 astTransform        10/10
+🔵 utils                9/9
+🔵 withTw               5/5
+🔵 styledFactory        6/6
+🔵 classParser         10/10
+🔵 cx / cxm             8/8
+🔵 classExtractor       4/4
+🔵 generateSafelist     4/4
+🔵 barrel exports      67/67
+🔵 end-to-end           5/5
+```
 
 ---
 
-## Stack Compatibility
+## 📋 Changelog v2
+
+### 🔴 Bug Fixes
+
+**`tw` undefined setelah bundle split (Vite/tsup)**
+```
+BEFORE: export const tw = new Proxy(fn, { get })
+        → Proxy + tsup splitting = tw undefined di Next.js/Vite
+
+AFTER:  Object.assign(twCallable, { div, button, ... })
+        → Plain object, transparan ke semua bundler
+```
+
+**Double wrap SSR hydration mismatch**
+```
+BEFORE: styled(tag)`` → styled(BaseStyled).attrs()``
+        → Double wrap = SSR hydration mismatch + SC v6 error
+
+AFTER:  styled(tag).withConfig().attrs()``
+        → Single chain, satu SC instance per component
+```
+
+**shouldForwardProp hardcoded**
+```
+BEFORE: Hanya blokir variant names yang hardcoded
+        → User variant keys bocor ke DOM
+
+AFTER:  Built dynamically dari variant keys aktual
+        → Zero DOM pollution apapun nama variant-nya
+```
 
-- **Next.js** 15 / 16 (App Router + Pages Router)
-- **React** 18 / 19 (Server Components compatible)
-- **Tailwind CSS** v3 / v4
-- **styled-components** v5 / v6
-- **TypeScript** 4.9 / 5.x
-- **shadcn/ui** (semua komponen)
-- **Radix UI** (via `withTw()`)
-- **Vite** 4 / 5
-- **Webpack** 4 / 5
+**TypeScript generic inference**
+```
+BEFORE: TwTagFactory tidak generic
+        → "Binding element '$isHover' implicitly has 'any' type"
+
+AFTER:  TwTagFactory<P> generic function
+        → Full type inference di template interpolations
+```
 
 ---
 
-## License
+## 📝 License
 
-MIT
+MIT © tailwind-styled-v4