tailwind-styled-v4 5.0.0 → 5.0.1

package/dist/compiler.d.mts

@@ -0,0 +1,1009 @@
+declare function hasTwUsage(source: string): boolean;
+declare function isDynamic(content: string): boolean;
+declare function isServerComponent(source: string): boolean;
+declare function hasInteractiveFeatures(content: string): boolean;
+
+interface TransformOptions {
+    /** @deprecated Mode is always "zero-runtime" in v5. This option will be removed in v6. */
+    mode?: "zero-runtime";
+    autoClientBoundary?: boolean;
+    addDataAttr?: boolean;
+    hoist?: boolean;
+    filename?: string;
+    /** Keep all imports from tailwind-styled-v4 intact — only transform tw.* usages */
+    preserveImports?: boolean;
+    /** Enable Dead Style Elimination - removes unused CSS after transformation (default: false) */
+    deadStyleElimination?: boolean;
+}
+interface TransformResult {
+    code: string;
+    classes: string[];
+    rsc?: {
+        isServer: boolean;
+        needsClientDirective: boolean;
+        clientReasons: string[];
+    };
+    changed: boolean;
+}
+declare function transformSource(source: string, opts?: TransformOptions): TransformResult;
+
+/**
+ * tailwind-styled-v4 — CSS Compiler (Rust-backed LightningCSS-style)
+ *
+ * v5 CHANGE: Now requires native binding. Previously fell back to JS implementation.
+ *
+ * Compiles Tailwind class lists to atomic CSS using Rust native engine.
+ */
+interface CssCompileResult$1 {
+    /** Generated atomic CSS */
+    css: string;
+    /** Classes successfully resolved to native CSS */
+    resolvedClasses: string[];
+    /** Classes with no native mapping (get @apply fallback) */
+    unknownClasses: string[];
+    /** Byte size of generated CSS */
+    sizeBytes: number;
+    /** Which engine produced this output */
+    engine: "rust" | "fallback";
+}
+/**
+ * Compile a list of Tailwind classes into atomic CSS.
+ *
+ * v5 CHANGE: Now THROWS if native binding is unavailable.
+ * Previously fell back to JS implementation.
+ *
+ * Uses Rust LightningCSS-style engine when native binary is available.
+ *
+ * @example
+ * const { css } = compileCssFromClasses(['flex', 'items-center', 'hover:bg-blue-600'])
+ * // → ".flex { display: flex } .items-center { align-items: center } ..."
+ *
+ * @throws Error if native binding is not available
+ */
+declare function compileCssFromClasses(classes: string[], options?: {
+    prefix?: string;
+}): CssCompileResult$1;
+/**
+ * Compile CSS for a set of classes and inject as a <style> block (SSR helper).
+ */
+declare function buildStyleTag(classes: string[]): string;
+
+/**
+ * Extract all Tailwind classes from source code.
+ *
+ * v5 CHANGE: Now THROWS if native binding is unavailable.
+ * Previously fell back to JS implementation.
+ *
+ * @param source - Source code to extract classes from
+ * @returns Array of unique class names (sorted)
+ * @throws Error if native binding is not available
+ */
+declare function extractAllClasses(source: string): string[];
+
+/**
+ * tailwind-styled-v4 — Dead Style Eliminator
+ *
+ * Build-time analysis yang scan component usage dan hapus variant + class
+ * yang tidak pernah dipakai. Hasilnya: CSS output yang sangat kecil.
+ *
+ * Pipeline:
+ *   scan all .tsx/.ts files
+ *     ↓ extract component usage (JSX props)
+ *     ↓ compare dengan registered variants
+ *     ↓ mark unused variants as dead
+ *     ↓ remove from CSS output
+ *
+ * @example
+ * const Button = tw.button({
+ *   base: "px-4 py-2",
+ *   variants: {
+ *     size: { sm: "text-sm", lg: "text-lg", xl: "text-xl" },  // xl never used!
+ *     intent: { primary: "bg-blue-500", danger: "bg-red-500" }
+ *   }
+ * })
+ *
+ * // In codebase: only <Button size="sm"> and <Button size="lg"> appear
+ * // Eliminator removes: size.xl → saves CSS
+ *
+ * Result:
+ *   Before: 3 size variants in CSS
+ *   After:  2 size variants in CSS (xl eliminated)
+ */
+interface VariantUsage {
+    /** Component name */
+    component: string;
+    /** Which variant props were used with which values */
+    usedValues: Record<string, Set<string>>;
+    /** Files where component is used */
+    usedInFiles: string[];
+}
+interface EliminationReport {
+    /** Total unused variant values found */
+    unusedCount: number;
+    /** Estimated bytes saved */
+    bytesSaved: number;
+    /** Details per component */
+    components: Record<string, {
+        usedVariants: Record<string, string[]>;
+        unusedVariants: Record<string, string[]>;
+    }>;
+}
+/**
+ * Extract all JSX component usages from source.
+ * Finds: <ComponentName prop="value" /> patterns.
+ */
+declare function extractComponentUsage(source: string): Record<string, Record<string, Set<string>>>;
+/**
+ * Scan entire project for component usage.
+ *
+ * @param dirs - Directories to scan (e.g. ["src"])
+ * @param cwd - Project root
+ */
+declare function scanProjectUsage(dirs: string[], cwd?: string): Record<string, Record<string, Set<string>>>;
+interface RegisteredComponent {
+    name: string;
+    variants: Record<string, Record<string, string>>;
+}
+/**
+ * Find unused variant values by comparing registered components with actual usage.
+ */
+declare function findDeadVariants(registered: RegisteredComponent[], projectUsage: Record<string, Record<string, Set<string>>>): EliminationReport;
+/**
+ * Filter a CSS string to remove selectors for unused classes.
+ *
+ * @param css - Full CSS string
+ * @param deadClasses - Set of class names to remove
+ */
+declare function eliminateDeadCss(css: string, deadClasses: Set<string>): string;
+/**
+ * Merge duplicate CSS rules and deduplicate media queries.
+ * Reduces final CSS size for atomic outputs.
+ *
+ * @example
+ * optimizeCss(".tw-a1{padding:16px} .tw-b1{padding:16px}")
+ * → ".tw-a1,.tw-b1{padding:16px}"
+ */
+declare function optimizeCss(css: string): string;
+interface EliminationOptions {
+    dirs?: string[];
+    cwd?: string;
+    registered?: RegisteredComponent[];
+    inputCss: string;
+    verbose?: boolean;
+}
+/**
+ * Run full dead style elimination pipeline.
+ *
+ * @example
+ * const result = await runElimination({
+ *   dirs: ["src"],
+ *   inputCss: fs.readFileSync("dist/styles.css", "utf-8"),
+ *   registered: [...componentConfigs],
+ * })
+ * fs.writeFileSync("dist/styles.min.css", result.css)
+ * console.log(result.report)
+ */
+declare function runElimination(opts: EliminationOptions): {
+    css: string;
+    report: EliminationReport;
+};
+
+/**
+ * tailwind-styled-v4 — Incremental CSS Compiler
+ *
+ * Hanya compile ulang file yang berubah, bukan semua file.
+ * Hasil: hot-reload styling dalam 5–20ms, bukan 3–10s.
+ *
+ * Pipeline:
+ *   file watcher detects change
+ *     ↓ hash check → skip jika file belum berubah
+ *     ↓ update dependency graph (hapus rule lama, tambah rule baru)
+ *     ↓ compute CSS diff (only changed rules)
+ *     ↓ write diff ke output — bukan rewrite seluruh file
+ *     ↓ hot reload
+ *
+ * Integrasi ke webpack/turbopack loader:
+ *   import { incrementalEngine } from "./incrementalEngine"
+ *   incrementalEngine.processFile(filepath, source, extractedClasses)
+ *
+ * Cache disimpan di `.tw-cache/` — persist antar build sessions.
+ */
+/** Satu style node dalam dependency graph */
+interface StyleNode {
+    /** Tailwind class, e.g. "p-4" */
+    twClass: string;
+    /** CSS declaration, e.g. "padding: 1rem" */
+    declaration: string;
+    /** Modifier (pseudo/media), e.g. ":hover" atau "@media (min-width: 768px)" */
+    modifier?: string;
+    /** Generated atomic class name, e.g. "tw-a1b2" */
+    atomicClass: string;
+}
+/** Graph: filepath → style nodes yang dihasilkan file itu */
+type FileDependencyGraph = Map<string, StyleNode[]>;
+/** Diff antara build sebelum dan setelah */
+interface CssDiff {
+    /** Rule yang perlu ditambah ke CSS output */
+    added: StyleNode[];
+    /** Atomic class names yang perlu dihapus dari CSS output */
+    removed: string[];
+    /** true jika tidak ada perubahan */
+    noChange: boolean;
+}
+/** Summary setelah process satu file */
+interface ProcessResult {
+    /** File yang diproses */
+    filepath: string;
+    /** true jika file berubah dan registry di-update */
+    changed: boolean;
+    /** CSS diff untuk file ini */
+    diff: CssDiff;
+    /** Durasi proses dalam ms */
+    durationMs: number;
+}
+/** Stats engine */
+interface IncrementalStats {
+    totalFiles: number;
+    changedFiles: number;
+    skippedFiles: number;
+    addedRules: number;
+    removedRules: number;
+    buildTimeMs: number;
+}
+interface IncrementalEngineOptions {
+    /** Output path untuk CSS file incremental. Default: ".tw-cache/atomic.css" */
+    outputPath?: string;
+    /** Apakah persist cache ke disk. Default: true */
+    persistCache?: boolean;
+    /** Verbose logging. Default: false */
+    verbose?: boolean;
+}
+declare class IncrementalEngine {
+    private hashCache;
+    private depGraph;
+    private globalReg;
+    private cssWriter;
+    private opts;
+    private stats;
+    private sessionStart;
+    constructor(opts?: IncrementalEngineOptions);
+    /**
+     * Proses satu file. Core method dipanggil oleh webpack/turbopack loader.
+     *
+     * @param filepath      - Absolute path ke file
+     * @param source        - Source code file (untuk hashing)
+     * @param extractedNodes - Style nodes yang di-extract compiler dari file ini
+     * @returns ProcessResult dengan diff dan stats
+     */
+    processFile(filepath: string, source: string, extractedNodes: StyleNode[]): ProcessResult;
+    /**
+     * Dipanggil di akhir build. Flush CSS ke disk, persist cache.
+     */
+    buildEnd(): Promise<void>;
+    /** Sync version untuk webpack buildEnd hook */
+    buildEndSync(): void;
+    /**
+     * Invalidate satu file (untuk hot reload — file dihapus atau renamed).
+     */
+    invalidateFile(filepath: string): void;
+    /** Get all active style nodes — untuk full CSS generation */
+    getAllNodes(): StyleNode[];
+    /** Get stats untuk current build session */
+    getStats(): Readonly<IncrementalStats>;
+    /** Get output CSS path */
+    getOutputPath(): string;
+    /** Reset stats untuk build session baru */
+    resetStats(): void;
+    /** Reset semua cache — untuk clean build */
+    reset(): void;
+    private log;
+}
+/**
+ * Parse daftar Tailwind classes menjadi StyleNodes untuk incremental engine.
+ * Supports: responsive variants (md:, lg:), pseudo (hover:, focus:), arbitrary.
+ *
+ * @example
+ * parseClassesToNodes(["p-4", "hover:bg-blue-500", "md:text-lg"])
+ */
+declare function parseClassesToNodes(classes: string[]): StyleNode[];
+declare function getIncrementalEngine(opts?: IncrementalEngineOptions): IncrementalEngine;
+declare function resetIncrementalEngine(): void;
+
+/**
+ * tailwind-styled-v4 — RSC Analyzer
+ *
+ * Inti dari RSC-Aware upgrade.
+ * Menganalisis setiap file untuk menentukan:
+ * - Server Component atau Client Component
+ * - Variant mana yang bisa di-resolve di server
+ * - Class mana yang membutuhkan client runtime
+ * - Auto client boundary injection
+ *
+ * Hasilnya:
+ * - Server Component → pure static className, zero JS ke client
+ * - Client Component → tetap seperti biasa dengan lookup table
+ */
+type ComponentEnv = "server" | "client" | "auto";
+interface RscAnalysis {
+    /** File ini adalah server component */
+    isServer: boolean;
+    /** File ini butuh "use client" directive */
+    needsClientDirective: boolean;
+    /** Alasan butuh client */
+    clientReasons: string[];
+    /** Classes yang membutuhkan client interaction */
+    interactiveClasses: string[];
+    /** Apakah semua variants bisa di-resolve statically di server */
+    canStaticResolveVariants: boolean;
+}
+declare function analyzeFile(source: string, _filename?: string): RscAnalysis;
+interface StaticVariantUsage {
+    /** Variant prop values yang ditemukan di JSX — bisa di-resolve di server */
+    resolved: Record<string, string>;
+    /** Variant props yang dinamis — butuh runtime */
+    dynamic: string[];
+}
+/**
+ * Deteksi penggunaan variant dalam JSX:
+ * <Button variant="primary"/> → dapat di-resolve statically
+ * <Button variant={userVariant}/> → dinamis, butuh runtime
+ */
+declare function analyzeVariantUsage(source: string, componentName: string, variantKeys: string[]): StaticVariantUsage;
+/**
+ * Untuk server component dengan variant usage statically known,
+ * resolve langsung ke className string — nol runtime.
+ *
+ * Input:
+ *   base = "px-4 py-2"
+ *   table = { variant: { primary: "px-4 py-2 bg-blue-500" } }
+ *   resolved = { variant: "primary" }
+ *
+ * Output:
+ *   "px-4 py-2 bg-blue-500"  ← langsung inline di server
+ */
+declare function resolveServerVariant(base: string, table: Record<string, Record<string, string>>, defaults: Record<string, string>, resolved: Record<string, string>): string;
+declare function injectClientDirective(code: string): string;
+declare function injectServerOnlyComment(code: string): string;
+
+/**
+ * tailwind-styled-v4 — Style Bucket System
+ *
+ * Setiap CSS rule masuk ke "bucket" berdasarkan tipe property-nya.
+ * Bucket di-emit dalam urutan yang selalu sama → CSS order stabil
+ * meskipun rule di-generate dari banyak file secara incremental.
+ *
+ * Tanpa bucket system:
+ *   .tw-color { color: blue }   ← dari file A
+ *   .tw-flex  { display: flex } ← dari file B
+ *   .tw-color2 { color: red }   ← dari file C
+ *   → urutan output bergantung urutan file di-process = TIDAK STABIL
+ *
+ * Dengan bucket system:
+ *   /* reset *\/
+ *   /* layout *\/   → display, position, flex, grid, overflow
+ *   /* spacing *\/  → margin, padding, gap, inset
+ *   /* sizing *\/   → width, height, max/min-width/height
+ *   /* typography *\/ → font-size, font-weight, line-height, text-*
+ *   /* visual *\/   → color, background, border, shadow, opacity
+ *   /* interaction *\/ → cursor, pointer-events, user-select, transition
+ *   /* responsive *\/ → @media queries (selalu di akhir)
+ *   → SELALU urutan ini, terlepas dari urutan file
+ *
+ * Keuntungan utama:
+ *  1. CSS output deterministic antar build (reproducible builds)
+ *  2. Specificity conflict sangat kecil — base selalu lebih awal dari responsive
+ *  3. Debug lebih mudah — tahu section mana rule berada
+ *
+ * Integrasi:
+ *   import { BucketEngine, bucketSort } from "./styleBucketSystem"
+ *
+ *   const engine = new BucketEngine()
+ *   engine.add(styleNode)
+ *   const css = engine.emit()
+ */
+
+/**
+ * 8 bucket utama + 1 bucket "unknown" untuk fallback.
+ * Urutan angka = urutan emit di CSS output.
+ */
+type StyleBucket = "reset" | "layout" | "spacing" | "sizing" | "typography" | "visual" | "interaction" | "responsive" | "unknown";
+/**
+ * Classify satu StyleNode ke bucket yang tepat.
+ *
+ * Priority:
+ * 1. Jika ada modifier @media → "responsive" (selalu paling akhir)
+ * 2. Cek declaration property → lookup PROPERTY_BUCKET_MAP
+ * 3. Fallback ke "unknown"
+ */
+declare function classifyNode(node: StyleNode): StyleBucket;
+interface BucketStats {
+    totalNodes: number;
+    perBucket: Record<StyleBucket, number>;
+}
+/**
+ * BucketEngine — menyimpan dan emit CSS dalam urutan bucket yang stabil.
+ *
+ * @example
+ * const engine = new BucketEngine()
+ * for (const node of styleNodes) engine.add(node)
+ * const css = engine.emit()
+ */
+declare class BucketEngine {
+    private buckets;
+    constructor();
+    /**
+     * Tambah StyleNode ke bucket yang tepat.
+     * Idempotent — atomic class yang sama tidak akan duplikat.
+     */
+    add(node: StyleNode): void;
+    /**
+     * Hapus node dari bucket (untuk incremental update).
+     */
+    remove(atomicClass: string): void;
+    /**
+     * Apply CssDiff dari incremental engine.
+     */
+    applyDiff(diff: {
+        added: StyleNode[];
+        removed: string[];
+    }): void;
+    /**
+     * Emit seluruh CSS dalam urutan bucket yang deterministic.
+     *
+     * @param comments - Tambahkan komentar section per bucket. Default: true
+     * @returns CSS string yang siap di-write ke file
+     */
+    emit(comments?: boolean): string;
+    /**
+     * Emit dengan @layer CSS untuk native browser layering.
+     * Lebih powerful — browser respects layer order untuk specificity.
+     *
+     * @example output:
+     * @layer tw-layout, tw-spacing, tw-visual, tw-responsive;
+     * @layer tw-layout { .tw-a1 { display: flex } }
+     */
+    emitLayered(): string;
+    /** Semua nodes dari semua bucket (untuk full registry access) */
+    allNodes(): StyleNode[];
+    /** Stats per bucket */
+    stats(): BucketStats;
+    /** Clear semua bucket */
+    clear(): void;
+}
+/**
+ * Sort array StyleNodes dalam urutan bucket.
+ * Berguna untuk one-off sorting tanpa perlu BucketEngine instance.
+ *
+ * @example
+ * const sorted = bucketSort(allNodes)
+ * const css = sorted.map(nodeToCSS).join("\n")
+ */
+declare function bucketSort(nodes: StyleNode[]): StyleNode[];
+interface ConflictWarning {
+    property: string;
+    classes: string[];
+    bucket: StyleBucket;
+    message: string;
+}
+/**
+ * Detect potential CSS conflicts dalam satu set StyleNodes.
+ * Hanya untuk dev mode — tidak perlu run di production.
+ *
+ * Conflict = dua node dengan property yang sama tapi value berbeda
+ * di bucket yang sama (bukan responsive override).
+ *
+ * @example
+ * const warnings = detectConflicts(nodes)
+ * if (warnings.length) console.warn(warnings)
+ */
+declare function detectConflicts(nodes: StyleNode[]): ConflictWarning[];
+declare function getBucketEngine(): BucketEngine;
+declare function resetBucketEngine(): void;
+
+/**
+ * @deprecated in v5 — Use @tailwind-styled/atomic package instead
+ * This module will be removed in v6
+ *
+ * tailwind-styled-v4 — Atomic CSS Mode (Optional)
+ *
+ * Mode opsional yang mengubah Tailwind classes menjadi atomic CSS rules.
+ * Mirip konsep StyleX dari Meta — setiap class menghasilkan satu CSS rule.
+ *
+ * Keuntungan:
+ * - CSS global deduplicated (p-4 hanya satu rule di seluruh app)
+ * - Bundle CSS lebih kecil untuk app besar
+ * - Zero duplicate styles
+ *
+ * Mode ini TIDAK mengganti Tailwind — tetap pakai Tailwind utilities,
+ * hanya menambahkan layer extraction untuk SSR streaming.
+ *
+ * Usage:
+ *   withTailwindStyled({ atomic: true })(nextConfig)
+ */
+interface AtomicRule {
+    /** Original Tailwind class */
+    twClass: string;
+    /** Generated atomic class name */
+    atomicName: string;
+    /** CSS property */
+    property: string;
+    /** CSS value */
+    value: string;
+    /** Modifier (hover:, md:, etc.) */
+    modifier?: string;
+}
+declare function parseAtomicClass(twClass: string): AtomicRule | null;
+declare function generateAtomicCss(rules: AtomicRule[]): string;
+declare function toAtomicClasses(twClasses: string): {
+    atomicClasses: string;
+    rules: AtomicRule[];
+    unknownClasses: string[];
+};
+declare function getAtomicRegistry(): Map<string, AtomicRule>;
+declare function clearAtomicRegistry(): void;
+
+/**
+ * tailwind-styled-v4 — classMerger
+ *
+ * FIX #05: Ganti custom UTILITY_GROUPS resolver dengan twMerge.
+ *
+ * WHY: Custom regex resolver memiliki banyak edge case yang salah
+ * (ring-, text- grouping, dll). tailwind-merge sudah jadi dependency,
+ * lebih akurat, dan di-maintain oleh komunitas Tailwind.
+ *
+ * RESULT: Output compile-time dan runtime kini identik — tidak ada
+ * behavior perbedaan antara dev mode dan production build.
+ */
+/**
+ * Merge Tailwind classes statically at compile time.
+ * Menggunakan tailwind-merge untuk conflict resolution yang akurat.
+ *
+ * FIX #05: Sebelumnya pakai custom UTILITY_GROUPS regex yang tidak
+ * kompatibel dengan tailwind-merge runtime. Sekarang keduanya identik.
+ *
+ * @example
+ * mergeClassesStatic("p-4 p-2 bg-red-500 bg-blue-500")
+ * → "p-2 bg-blue-500"
+ *
+ * mergeClassesStatic("ring-2 ring-4")
+ * → "ring-4"  ✓ (custom resolver dulu return "ring-2 ring-4" — salah!)
+ */
+declare function mergeClassesStatic(classes: string): string;
+/**
+ * Normalize raw class string — trim, dedupe whitespace, join lines.
+ */
+declare function normalizeClasses(raw: string): string;
+
+/**
+ * tailwind-styled-v4 — Component Hoister
+ *
+ * Problem: Component yang didefinisikan di dalam fungsi lain
+ * akan direcreate setiap render — sangat buruk untuk performa.
+ *
+ * BEFORE (buruk):
+ *   export default function Page() {
+ *     const Box = tw.div`p-4`   ← dibuat ulang tiap render!
+ *     return <Box/>
+ *   }
+ *
+ * AFTER (benar):
+ *   const Box = tw.div`p-4`    ← module scope, dibuat sekali
+ *   export default function Page() {
+ *     return <Box/>
+ *   }
+ *
+ * Hoister mendeteksi pola ini dan memindahkan deklarasi ke module scope.
+ */
+interface HoistResult {
+    code: string;
+    hoisted: string[];
+    warnings: string[];
+}
+declare function hoistComponents(source: string): HoistResult;
+
+type CompileEngine = "none" | "native" | "js";
+interface CompileInput {
+    filepath: string;
+    source: string;
+    options: TransformOptions;
+}
+declare class CompileContext {
+    filepath: string;
+    source: string;
+    options: TransformOptions;
+    result: TransformResult | null;
+    done: boolean;
+    engine: CompileEngine;
+    constructor(input: CompileInput);
+}
+
+/**
+ * tailwind-styled-v4 — NativeBridge
+ *
+ * Loads the native Rust engine (.node binding via index.mjs) and exposes
+ * its functions to the JS compiler pipeline.
+ *
+ * The bridge is loaded lazily and cached. If the .node binary is not
+ * present (e.g. the user hasn't built the Rust crate yet), every function
+ * returns null and the pipeline falls through to the JS implementation.
+ *
+ * Environment flags:
+ *   TWS_NO_NATIVE=1  — disable native bridge entirely
+ *   TWS_NO_RUST=1    — alias for TWS_NO_NATIVE
+ */
+
+/** Raw shape returned by Rust transform_source — napi auto-converts snake_case → camelCase */
+interface NativeTransformResult {
+    code: string;
+    classes: string[];
+    changed: boolean;
+    /** JSON string: { isServer: boolean, needsClientDirective: boolean } */
+    rscJson?: string | null;
+    /** JSON string: ComponentMetadata[] */
+    metadataJson?: string | null;
+}
+/** Metadata for one compound component, produced by Rust and consumed by @tailwind-styled/runtime */
+interface ComponentMetadata {
+    component: string;
+    tag: string;
+    baseClass: string;
+    subComponents: Record<string, {
+        tag: string;
+        class: string;
+    }>;
+}
+/** Full bridge interface — all members optional so feature detection is easy */
+interface NativeBridge {
+    /** Parse individual class tokens. Throws if binding is unavailable. */
+    parseClassesNative?: (input: string) => Array<{
+        raw: string;
+        base: string;
+        variants: string[];
+        modifierType?: string | null;
+        modifierValue?: string | null;
+    }>;
+    /** Fast pre-check — returns null if binding unavailable. */
+    hasTwUsageNative?: (source: string) => boolean | null;
+    /** Idempotency guard — returns null if binding unavailable. */
+    isAlreadyTransformedNative?: (source: string) => boolean | null;
+    /** RSC analysis — returns null if binding unavailable. */
+    analyzeRscNative?: (source: string, filename?: string) => {
+        isServer: boolean;
+        needsClientDirective: boolean;
+        clientReasons: string[];
+    } | null;
+    /** Full transform — returns null if binding unavailable (JS pipeline takes over). */
+    transformSourceNative?: (source: string, opts: Record<string, unknown>) => NativeTransformResult | null;
+    /** AST-based class extraction (Oxc+regex hybrid) */
+    astExtractClassesNative?: (source: string, filename?: string) => {
+        classes: string[];
+        engine: string;
+    } | null;
+    /** Rust-based class extraction via regex */
+    extractClassesFromSourceNative?: (source: string) => string[] | null;
+    /** Analyze class frequency - used for DSE */
+    analyzeClassesNative?: (filesJson: string, root: string, topN: number) => {
+        root: string;
+        totalFiles: number;
+        uniqueClassCount: number;
+        totalClassOccurrences: number;
+        topClasses: Array<{
+            name: string;
+            count: number;
+        }>;
+        duplicateCandidates: Array<{
+            name: string;
+            count: number;
+        }>;
+        safelist: string[];
+    } | null;
+}
+/**
+ * Get the native bridge - THROWS if unavailable.
+ *
+ * v5 CHANGE: Previously returned null and fell back to JS pipeline.
+ * Now throws an error to ensure native binding is always used.
+ *
+ * @throws Error if native binding is not available
+ */
+declare function getNativeBridge(): NativeBridge;
+declare function resetNativeBridgeCache(): void;
+declare function adaptNativeResult(raw: NativeTransformResult): TransformResult & {
+    metadata?: ComponentMetadata[];
+};
+
+interface CoreCompileOptions extends TransformOptions {
+}
+interface CoreCompileResult {
+    result: TransformResult;
+    engine: CompileEngine;
+    cacheHit: boolean;
+    /** Compound component metadata produced by Rust — undefined when the JS pipeline ran */
+    metadata?: ComponentMetadata[];
+    /** CSS output after DSE (when deadStyleElimination option is enabled) */
+    css?: string;
+}
+declare function compileWithCore(input: CompileInput): CoreCompileResult;
+declare function resetCompileCache(): void;
+
+/**
+ * tailwind-styled-v5 - loaderCore
+ *
+ * Unified loader path:
+ *   incremental precheck -> core compiler (native/js pipeline) -> finalize
+ */
+
+interface LoaderOptions extends TransformOptions {
+    routeCss?: boolean;
+    incremental?: boolean;
+    verbose?: boolean;
+    autoClientBoundary?: boolean;
+}
+interface LoaderContext {
+    filepath: string;
+    source: string;
+    options: LoaderOptions;
+    isDev?: boolean;
+}
+interface LoaderOutput {
+    code: string;
+    changed: boolean;
+    classes: string[];
+    rsc?: TransformResult["rsc"];
+    engine?: "native" | "js" | "none";
+    cacheHit?: boolean;
+    /** Compound component metadata — only present when Rust engine ran */
+    metadata?: ComponentMetadata[];
+}
+declare function shouldSkipFile(filepath: string): boolean;
+declare function runLoaderTransform(ctx: LoaderContext): LoaderOutput;
+
+/**
+ * tailwind-styled-v4 — Tailwind Config Loader
+ *
+ * Auto-load tailwind config dari project.
+ * Jika tidak ada → fallback ke defaultPreset (zero-config mode).
+ *
+ * Priority:
+ *   1. tailwind.config.ts  (TypeScript)
+ *   2. tailwind.config.js  (JavaScript)
+ *   3. tailwind.config.mjs (ESM)
+ *   4. defaultPreset       (fallback — zero-config)
+ */
+type TailwindConfig = Record<string, any>;
+/**
+ * Load tailwind config. Cached per process.
+ * Returns defaultPreset if no config found (zero-config mode).
+ */
+declare function loadTailwindConfig(cwd?: string): TailwindConfig;
+/**
+ * Get content paths dari config (atau default paths)
+ */
+declare function getContentPaths(config: TailwindConfig, cwd?: string): string[];
+/**
+ * Invalidate config cache (useful for watch mode)
+ */
+declare function invalidateConfigCache(): void;
+/**
+ * Check if project has zero-config setup (no user tailwind config)
+ */
+declare function isZeroConfig(cwd?: string): boolean;
+/**
+ * Auto-generate tailwind.config.ts dan globals.css jika tidak ada
+ * (dipanggil oleh CLI dan withTailwindStyled pada first run)
+ */
+declare function bootstrapZeroConfig(cwd?: string): {
+    generatedConfig: boolean;
+    generatedCss: boolean;
+};
+
+type PipelineStep<T> = (ctx: T) => void;
+declare class Pipeline<T extends {
+    done?: boolean;
+}> {
+    private steps;
+    use(step: PipelineStep<T>): this;
+    run(ctx: T): T;
+}
+
+/**
+ * tailwind-styled-v4 — Route CSS Collector
+ *
+ * Mengumpulkan Tailwind classes per-route sehingga setiap halaman
+ * hanya memuat CSS yang benar-benar dipakai.
+ *
+ * Tailwind default: ~300kb global CSS
+ * Route CSS: ~2–10kb per halaman
+ *
+ * Cara kerja:
+ * 1. Setiap file yang di-transform oleh compiler melaporkan classnya
+ * 2. Collector memetakan file → route
+ * 3. Di akhir build, CSS di-generate per route
+ *
+ * File structure output:
+ *   .next/static/css/
+ *     _global.css        ← base + reset (sekali load)
+ *     app/page.css       ← hanya class yang dipakai di /
+ *     app/about/page.css ← hanya class untuk /about
+ *     app/dashboard/...
+ */
+interface RouteClassMap {
+    /** filepath → array of tw classes */
+    files: Map<string, Set<string>>;
+    /** route → Set of files yang dipakai */
+    routes: Map<string, Set<string>>;
+    /** Global classes (di-load semua route) */
+    global: Set<string>;
+}
+/**
+ * Register classes dari sebuah file setelah compiler transform.
+ * Dipanggil oleh turbopackLoader/webpackLoader setelah setiap file di-transform.
+ */
+declare function registerFileClasses(filepath: string, classes: string[]): void;
+/**
+ * Register global classes (base styles, layout, dsb.)
+ * Global classes dimuat di semua route.
+ */
+declare function registerGlobalClasses(classes: string[]): void;
+/**
+ * Get all classes for a specific route (termasuk global)
+ */
+declare function getRouteClasses(route: string): Set<string>;
+/**
+ * Get all routes yang sudah ter-register
+ */
+declare function getAllRoutes(): string[];
+/**
+ * Get complete map (untuk build-time generation)
+ */
+declare function getCollector(): RouteClassMap;
+/**
+ * Reset collector (start of each build)
+ */
+declare function resetCollector(): void;
+/**
+ * Konversi filepath ke Next.js App Router route.
+ *
+ * /src/app/page.tsx           → /
+ * /src/app/about/page.tsx     → /about
+ * /src/app/dashboard/page.tsx → /dashboard
+ * /src/components/Button.tsx  → null (shared component, goes to global)
+ * /src/app/layout.tsx         → __layout (global)
+ */
+declare function fileToRoute(filepath: string): string | null;
+declare function getCollectorSummary(): string;
+
+interface CssCompileResult {
+    css: string;
+    resolvedClasses: string[];
+    unknownClasses: string[];
+    sizeBytes: number;
+    engine: "rust" | "fallback";
+}
+interface AstExtractResult {
+    classes: string[];
+    componentNames: string[];
+    hasTwUsage: boolean;
+    hasUseClient: boolean;
+    imports: string[];
+    engine: "rust" | "fallback";
+}
+/**
+ * Compile Tailwind class list → atomic CSS via Rust LightningCSS-style compiler.
+ *
+ * v5 CHANGE: Now THROWS if native binding is unavailable.
+ * Previously fell back to JS implementation.
+ *
+ * @throws Error if native binding is not available
+ */
+declare function compileCssNative(classes: string[], prefix?: string | null): CssCompileResult;
+/**
+ * Extract Tailwind classes from source via Rust AST-style extractor.
+ *
+ * v5 CHANGE: Now THROWS if native binding is unavailable.
+ * Previously fell back to JS implementation.
+ *
+ * @throws Error if native binding is not available
+ */
+declare function astExtractClassesNative(source: string, filename: string): AstExtractResult;
+
+/**
+ * tailwind-styled-v4 — safelistGenerator
+ *
+ * Scan semua source files dan extract Tailwind classes untuk safelist.
+ * Output: .tailwind-styled-safelist.json
+ *
+ * Developer tidak perlu manual safelist.
+ */
+declare function generateSafelist(scanDirs: string[], outputPath?: string, cwd?: string): string[];
+declare function loadSafelist(safelistPath: string): string[];
+/**
+ * Tailwind v4 variant — output CSS dengan @source inline() bukan JSON.
+ * Tailwind v4 tidak punya 'safelist' di config — pakai @source inline() di CSS.
+ */
+declare function generateSafelistCss(scanDirs: string[], outputPath?: string, cwd?: string): string[];
+
+/**
+ * tailwind-styled-v4 — Embedded Tailwind Engine
+ *
+ * Compiler menjalankan Tailwind internally — tidak perlu tailwind CLI,
+ * tidak perlu postcss config manual.
+ *
+ * Cara kerja:
+ * 1. Compiler extract semua class dari source (via classExtractor)
+ * 2. Engine generate CSS hanya untuk class tersebut
+ * 3. CSS di-output per route (route-level CSS bundling)
+ *
+ * Ini membuat CSS output jauh lebih kecil:
+ *   Tailwind normal: ~300kb global
+ *   Route CSS:       ~2–10kb per route
+ *
+ * NOTE: v5 only supports Tailwind v4. v3 support has been removed.
+ */
+type TailwindEngineMode = "jit" | "build" | "manual";
+interface TailwindEngineOptions {
+    mode?: TailwindEngineMode;
+    cwd?: string;
+    outputDir?: string;
+    config?: Record<string, any>;
+    minify?: boolean;
+}
+interface CssGenerateResult {
+    route: string;
+    css: string;
+    classes: string[];
+    sizeBytes: number;
+}
+/**
+ * Try to use Tailwind's internal API for CSS generation.
+ * Fallback ke manual CSS generation jika Tailwind API tidak tersedia.
+ *
+ * NOTE: v5 only supports Tailwind v4. v3 support has been removed.
+ */
+declare function generateCssForClasses(classes: string[], config?: Record<string, any>, cwd?: string): Promise<string>;
+declare function generateAllRouteCss(opts?: TailwindEngineOptions): Promise<CssGenerateResult[]>;
+
+/**
+ * tailwind-styled-v4 — variantCompiler
+ *
+ * FIXES:
+ *  #01 — Don't pre-merge base into variant table values (double-merge bug)
+ *  #06 — Use proper AST parser instead of fragile regex
+ *
+ * BEFORE (double-merge):
+ *   compileVariants: table["size"]["sm"] = "px-4 py-2 text-sm"  ← base included
+ *   astTransform:    [base, table["size"][...]]                   ← base AGAIN → DUPE
+ *
+ * AFTER (correct):
+ *   compileVariants: table["size"]["sm"] = "text-sm"             ← variant only
+ *   astTransform:    [base, table["size"][...], className]        ← base once, correct
+ *
+ * Input:
+ *   { base: "px-4 py-2", variants: { size: { sm: "text-sm" } } }
+ *
+ * Output code:
+ *   const __vt_abc123 = { size: { sm: "text-sm" } }
+ *   // className = [base, table[variant]] → no duplication
+ */
+interface CompiledVariants {
+    base: string;
+    table: Record<string, Record<string, string>>;
+    compounds: Array<{
+        class: string;
+        [key: string]: any;
+    }>;
+    defaults: Record<string, string>;
+}
+/**
+ * Compile variant config into lookup table.
+ *
+ * FIX #01: Do NOT pre-merge base into table values.
+ * Table contains variant-specific classes only.
+ * Base is always injected separately in the component className array.
+ */
+declare function compileVariants(base: string, variants: Record<string, Record<string, string>>, compounds?: Array<{
+    class: string;
+    [key: string]: any;
+}>, defaults?: Record<string, string>): CompiledVariants;
+
+export { type AstExtractResult, type AtomicRule, BucketEngine, type BucketStats, CompileContext, type CompileEngine, type CompileInput, type ComponentEnv, type ComponentMetadata, type ConflictWarning, type CoreCompileOptions, type CoreCompileResult, type CssCompileResult$1 as CssCompileResult, type CssDiff, type CssGenerateResult, type EliminationReport, type FileDependencyGraph, type HoistResult, IncrementalEngine, type IncrementalEngineOptions, type IncrementalStats, type LoaderContext, type LoaderOptions, type LoaderOutput, type NativeBridge, type NativeTransformResult, Pipeline, type ProcessResult, type RouteClassMap, type RscAnalysis, type StaticVariantUsage, type StyleBucket, type StyleNode, type TailwindEngineOptions, type TransformOptions, type TransformResult, type VariantUsage, adaptNativeResult, analyzeFile, analyzeVariantUsage, astExtractClassesNative, bootstrapZeroConfig, bucketSort, buildStyleTag, classifyNode, clearAtomicRegistry, compileCssFromClasses, compileCssNative, compileVariants, compileWithCore, detectConflicts, eliminateDeadCss, extractAllClasses, extractComponentUsage, fileToRoute, findDeadVariants, generateAllRouteCss, generateAtomicCss, generateCssForClasses, generateSafelist, generateSafelistCss, getAllRoutes, getAtomicRegistry, getBucketEngine, getCollector, getCollectorSummary, getContentPaths, getIncrementalEngine, getNativeBridge, getRouteClasses, hasInteractiveFeatures, hasTwUsage, hoistComponents, injectClientDirective, injectServerOnlyComment, invalidateConfigCache, isDynamic, isServerComponent, isZeroConfig, loadSafelist, loadTailwindConfig, mergeClassesStatic, normalizeClasses, optimizeCss, parseAtomicClass, parseClassesToNodes, registerFileClasses, registerGlobalClasses, resetBucketEngine, resetCollector, resetCompileCache, resetIncrementalEngine, resetNativeBridgeCache, resolveServerVariant, runElimination, runLoaderTransform, scanProjectUsage, hasTwUsage as shouldProcess, shouldSkipFile, toAtomicClasses, transformSource };