tailwind-styled-v4 5.0.36 → 5.0.37

package/dist/engine.d.ts

@@ -1,9 +1,407 @@
-import { S as SourceLocation, R as RuleIR, a as RuleId, E as EnginePlugin } from './index-UkYbyBkR.js';
-export { B as BuildResult, C as CascadeResolutionIR, b as CascadeResolutionId, c as CascadeResolver, d as CascadeStage, e as ConditionIR, f as ConditionId, g as ConditionResult, h as ConflictTrace, i as EngineMetricsCollector, j as EngineMetricsSnapshot, k as EngineOptions, l as EnginePluginContext, m as EngineWatchContext, n as EngineWatchEvent, o as EngineWatchOptions, F as FinalComputedStyleIR, p as FinalStyleProperty, I as Importance, q as InspectionReport, L as LayerId, O as Origin, P as PropertyBucketIR, r as PropertyId, s as ResolutionCause, t as ResolutionReason, u as RuleTrace, v as SelectorIR, w as SelectorId, x as StyleGraphIR, T as TailwindStyledEngine, y as TraceResult, V as ValueId, z as VariantChainIR, A as VariantChainId, D as VariantTrace, G as analyzeWorkspace, H as build, J as buildProvenanceChain, K as createEngine, M as createFingerprint, N as createResolutionReason, Q as generateSafelist, U as inspectClass, W as runAfterBuild, X as runAfterScan, Y as runAfterWatch, Z as runBeforeBuild, _ as runBeforeScan, $ as runBeforeWatch, a0 as runOnError, a1 as runTransformClasses, a2 as scanWorkspace, a3 as trace, a4 as traceClass, a5 as traceClasses } from './index-UkYbyBkR.js';
 import { z } from 'zod';
-import { b as ScanWorkspaceResult, a as ScanWorkspaceOptions } from './schemas-DR-SLxZZ.js';
-export { S as ScanFileResult } from './schemas-DR-SLxZZ.js';
-import './analyzeWorkspace-B1_XRfdl.js';
+
+declare class RuleId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class SelectorId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class VariantChainId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class PropertyId {
+    readonly value: number;
+    readonly name?: string | undefined;
+    constructor(value: number, name?: string | undefined);
+    toString(): string;
+}
+declare class ValueId {
+    readonly value: number;
+    readonly name?: string | undefined;
+    constructor(value: number, name?: string | undefined);
+    toString(): string;
+}
+declare class LayerId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class ConditionId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare class CascadeResolutionId {
+    readonly value: number;
+    constructor(value: number);
+    toString(): string;
+}
+declare enum Origin {
+    UserAgent = 0,
+    UserNormal = 1,
+    AuthorNormal = 2,
+    AuthorImportant = 3,
+    UserImportant = 4
+}
+declare enum Importance {
+    Normal = 0,
+    Important = 1
+}
+declare enum ConditionResult {
+    Active = 0,
+    Inactive = 1,
+    Unknown = 2
+}
+declare enum CascadeStage {
+    Origin = 0,
+    Layer = 1,
+    Importance = 2,
+    Specificity = 3,
+    Order = 4
+}
+type ResolutionCause = {
+    type: "LowerOrigin";
+    winnerOrigin: Origin;
+    loserOrigin: Origin;
+} | {
+    type: "LowerLayer";
+    winnerLayer: string;
+    loserLayer: string;
+} | {
+    type: "LowerImportance";
+} | {
+    type: "LowerSpecificity";
+    delta: number;
+} | {
+    type: "EarlierOrder";
+    delta: number;
+} | {
+    type: "InactiveCondition";
+    condition: string;
+};
+interface ResolutionReason {
+    causes: readonly ResolutionCause[];
+    finalDecision: string;
+}
+interface SelectorIR {
+    id: SelectorId;
+    normalized: string;
+    specificity: number;
+    parts: readonly string[];
+}
+interface VariantChainIR {
+    id: VariantChainId;
+    chain: readonly VariantChainId[];
+    conditionGraphId: number | null;
+}
+interface ConditionIR {
+    id: ConditionId;
+    conditionType: string;
+    expression: string;
+}
+interface RuleIR {
+    id: RuleId;
+    selector: SelectorId;
+    variantChain: VariantChainId;
+    property: PropertyId;
+    value: ValueId;
+    origin: Origin;
+    importance: Importance;
+    layer: LayerId | null;
+    layerOrder: number;
+    specificity: number;
+    condition: ConditionId | null;
+    conditionResult: ConditionResult;
+    insertionOrder: number;
+    fingerprint: string;
+    source: SourceLocation;
+}
+interface PropertyBucketIR {
+    property: PropertyId;
+    rules: readonly RuleId[];
+}
+interface CascadeResolutionIR {
+    id: CascadeResolutionId;
+    property: PropertyId;
+    winner: RuleId;
+    losers: readonly RuleId[];
+    reason: ResolutionReason;
+    stage: CascadeStage;
+}
+interface StyleGraphIR {
+    ruleConflicts: Map<RuleId, readonly RuleId[]>;
+}
+interface FinalComputedStyleIR {
+    className: string;
+    resolvedProperties: Map<PropertyId, CascadeResolutionId>;
+}
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * Generate a short fingerprint string from a list of ordered parts.
+ * Native-only: delegates to Rust `create_fingerprint()` (FNV-1a, base-36 output).
+ */
+declare function createFingerprint(parts: string[]): string;
+declare function createResolutionReason(causes: ResolutionCause[], finalDecision: string): ResolutionReason;
+
+/**
+ * tailwind-styled-v4 — Cascade Resolver
+ *
+ * JS layer: state management (rule collection, class registration).
+ * Rust layer: cascade algorithm (sort, compare, resolve winner/loser).
+ *
+ * Moved to native: compareCascade, resolveProperty, buildResolutionReason,
+ * determineCascadeStage — all pure computation, zero browser API.
+ *
+ * Rust #[napi] fn: resolve_cascade(rules_json: String) -> String
+ */
+
+declare class CascadeResolver {
+    private readonly rules;
+    private readonly classRules;
+    private readonly styleGraph;
+    addRule(rule: RuleIR): void;
+    addRules(rules: RuleIR[]): void;
+    registerClass(className: string, ruleIds: RuleId[]): void;
+    getRule(ruleId: RuleId): RuleIR | undefined;
+    getClassRules(className: string): RuleId[] | undefined;
+    getStyleGraph(): StyleGraphIR;
+    /**
+     * Resolve cascade for a specific class.
+     * Delegates sort + winner selection to Rust.
+     */
+    resolveByClassName(className: string): {
+        resolvedProperties: Map<PropertyId, CascadeResolutionIR>;
+    } | null;
+    /**
+     * Resolve cascade for all rules.
+     * Delegates sort + winner selection to Rust.
+     */
+    resolveAllProperties(): Map<PropertyId, CascadeResolutionIR>;
+    /**
+     * Resolve cascade for a specific set of rule IDs.
+     */
+    resolveForClass(classRuleIds: RuleId[]): Map<PropertyId, CascadeResolutionIR>;
+    /**
+     * Resolve cascade for a single property bucket.
+     */
+    resolveProperty(property: PropertyId): CascadeResolutionIR | null;
+    getResolution(_id: CascadeResolutionId): CascadeResolutionIR | undefined;
+}
+
+/**
+ * tailwind-styled-v4 — Cascade Tracer
+ *
+ * Delegates cascade resolution to CascadeResolver (Rust-backed).
+ * JS layer: format trace output only.
+ *
+ * Removed from JS: resolvePropertyTraced, compareCascadeTraced,
+ * buildResolutionReasonTraced, determineCascadeStageTraced.
+ */
+
+interface VariantTrace {
+    name: string;
+    value: string;
+    source: SourceLocation;
+}
+interface RuleTrace {
+    property: string;
+    value: string;
+    applied: boolean;
+    reason: string | null;
+    source: SourceLocation;
+    specificity: number;
+}
+interface ConflictTrace {
+    property: string;
+    winner: string;
+    loser: string;
+    stage: string;
+    causes: string[];
+}
+interface FinalStyleProperty {
+    property: string;
+    value: string;
+}
+interface TraceResult {
+    class: string;
+    definedAt: SourceLocation;
+    variants: VariantTrace[];
+    rules: RuleTrace[];
+    conflicts: ConflictTrace[];
+    finalStyle: FinalStyleProperty[];
+}
+interface ProvenanceData {
+    className: string;
+    source: SourceLocation;
+    variants: Map<string, VariantTrace>;
+    rules: Map<string, RuleIR[]>;
+}
+declare function buildProvenanceChain(className: string): ProvenanceData;
+declare function trace(className: string, resolver: CascadeResolver): TraceResult;
+
+declare const ScanWorkspaceOptionsSchema: z.ZodObject<{
+    includeExtensions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ignoreDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    useCache: z.ZodOptional<z.ZodBoolean>;
+    cacheDir: z.ZodOptional<z.ZodString>;
+    smartInvalidation: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type ScanWorkspaceOptions = z.infer<typeof ScanWorkspaceOptionsSchema>;
+declare const ScanFileResultSchema: z.ZodObject<{
+    file: z.ZodString;
+    classes: z.ZodArray<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ScanFileResult = z.infer<typeof ScanFileResultSchema>;
+declare const ScanWorkspaceResultSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        classes: z.ZodArray<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    totalFiles: z.ZodNumber;
+    uniqueClasses: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+type ScanWorkspaceResult = z.infer<typeof ScanWorkspaceResultSchema>;
+
+/**
+ * Public type contracts for @tailwind-styled/analyzer.
+ * Keep this file aligned with the runtime report shape exposed by src/index.ts.
+ */
+
+interface ClassUsage$1 {
+    readonly name: string;
+    readonly count: number;
+    readonly isUnused?: boolean;
+    readonly isConflict?: boolean;
+}
+interface ClassConflict {
+    readonly className: string;
+    readonly variants: readonly string[];
+    readonly classes: readonly string[];
+    readonly message: string;
+}
+interface AnalyzerClassStats {
+    readonly all: readonly ClassUsage$1[];
+    readonly top: readonly ClassUsage$1[];
+    readonly frequent: readonly ClassUsage$1[];
+    readonly unique: readonly ClassUsage$1[];
+    readonly distribution: Readonly<Record<string, number>>;
+}
+interface TailwindConfigSummary {
+    readonly path: string;
+    readonly loaded: boolean;
+    readonly safelistCount: number;
+    readonly customUtilityCount: number;
+    readonly warning?: string;
+}
+interface AnalyzerSemanticReport {
+    readonly unusedClasses: readonly ClassUsage$1[];
+    readonly unknownClasses: readonly ClassUsage$1[];
+    readonly conflicts: readonly ClassConflict[];
+    readonly tailwindConfig?: TailwindConfigSummary;
+}
+interface AnalyzerReport {
+    readonly root: string;
+    readonly totalFiles: number;
+    readonly uniqueClassCount: number;
+    readonly totalClassOccurrences: number;
+    readonly classStats: AnalyzerClassStats;
+    /** Alias for classStats.top — backward compat & test contract */
+    readonly topClasses: readonly ClassUsage$1[];
+    readonly safelist: readonly string[];
+    readonly semantic?: AnalyzerSemanticReport;
+}
+interface AnalyzerOptions {
+    readonly scanner?: ScanWorkspaceOptions;
+    readonly classStats?: {
+        readonly top?: number;
+        readonly frequentThreshold?: number;
+    };
+    readonly includeClass?: (className: string) => boolean;
+    readonly semantic?: boolean | {
+        readonly tailwindConfigPath?: string;
+    };
+}
+
+/**
+ * Analyze Tailwind class usage in a workspace and return usage statistics.
+ * Set `semantic.tailwindConfigPath` to override Tailwind config lookup.
+ * @example
+ * const report = await analyzeWorkspace("./src", {
+ *   classStats: { top: 20, frequentThreshold: 2 },
+ *   semantic: { tailwindConfigPath: "tailwind.config.js" },
+ * })
+ */
+declare function analyzeWorkspace$1(root: string, options?: AnalyzerOptions): Promise<AnalyzerReport>;
+
+interface EngineMetricsSnapshot {
+    eventsReceived: number;
+    eventsProcessed: number;
+    batchesProcessed: number;
+    incrementalUpdates: number;
+    fullRescans: number;
+    skippedLargeFiles: number;
+    queueMaxSize: number;
+    lastBuildMs: number;
+    avgBuildMs: number;
+}
+declare class EngineMetricsCollector {
+    private eventsReceived;
+    private eventsProcessed;
+    private batchesProcessed;
+    private incrementalUpdates;
+    private fullRescans;
+    private skippedLargeFiles;
+    private queueMaxSize;
+    private lastBuildMs;
+    private totalBuildMs;
+    markEventReceived(queueSize: number): void;
+    markBatchProcessed(batchSize: number): void;
+    markIncremental(): void;
+    markFullRescan(): void;
+    markSkippedLargeFile(): void;
+    markBuildDuration(ms: number): void;
+    snapshot(): EngineMetricsSnapshot;
+}
+
+interface EnginePluginContext {
+    root: string;
+    timestamp: number;
+}
+interface EngineWatchContext {
+    root: string;
+    timestamp: number;
+}
+interface EnginePlugin {
+    name: string;
+    beforeScan?(context: EnginePluginContext): void | Promise<void>;
+    afterScan?(scan: ScanWorkspaceResult, context: EnginePluginContext): ScanWorkspaceResult | undefined | Promise<ScanWorkspaceResult | undefined>;
+    transformClasses?(classes: string[], context: EnginePluginContext): string[] | undefined | Promise<string[] | undefined>;
+    beforeBuild?(scan: ScanWorkspaceResult, context: EnginePluginContext): void | Promise<void>;
+    afterBuild?(result: BuildResult, context: EnginePluginContext): BuildResult | undefined | Promise<BuildResult | undefined>;
+    onError?(error: Error, context: EnginePluginContext): void | Promise<void>;
+    beforeWatch?(context: EngineWatchContext): void | Promise<void>;
+    afterWatch?(context: EngineWatchContext): void | Promise<void>;
+}
+declare function runBeforeScan(plugins: EnginePlugin[], context: EnginePluginContext): Promise<void>;
+declare function runAfterScan(plugins: EnginePlugin[], scan: ScanWorkspaceResult, context: EnginePluginContext): Promise<ScanWorkspaceResult>;
+declare function runTransformClasses(plugins: EnginePlugin[], classes: string[], context: EnginePluginContext): Promise<string[]>;
+declare function runBeforeBuild(plugins: EnginePlugin[], scan: ScanWorkspaceResult, context: EnginePluginContext): Promise<void>;
+declare function runAfterBuild(plugins: EnginePlugin[], result: BuildResult, context: EnginePluginContext): Promise<BuildResult>;
+declare function runOnError(plugins: EnginePlugin[], error: Error, context: EnginePluginContext): Promise<void>;
+declare function runBeforeWatch(plugins: EnginePlugin[], context: EngineWatchContext): Promise<void>;
+declare function runAfterWatch(plugins: EnginePlugin[], context: EngineWatchContext): Promise<void>;
 
 interface ClassBundleInfo {
     className: string;
@@ -274,4 +672,157 @@ declare const parseEngineWatchOptions: (options: unknown) => {
     largeFileThreshold?: number | undefined;
 };
 
-export { type BuildResultInput, BuildResultSchema, type BundleAnalysisResult, BundleAnalyzer, type ClassBundleInfo, type ClassUsage, type ComponentImpact, type EngineOptionsInput, EngineOptionsSchema, EnginePlugin, type EngineWatchOptionsInput, EngineWatchOptionsSchema, type ImpactReport, ImpactTracker, ReverseLookup, type ReverseLookupResult, RuleIR, RuleId, ScanWorkspaceOptions, ScanWorkspaceResult, SourceLocation, type WatchCallback, type WatchEvent, type WatchEventKind, type WatchHandle, type WorkspaceWatcher, applyIncrementalChange, parseCssToIr, parseEngineOptions, parseEngineWatchOptions, watchWorkspace$1 as watchWorkspaceLegacy, watchWorkspace as watchWorkspaceNative };
+interface EngineOptions {
+    root?: string;
+    scanner?: ScanWorkspaceOptions;
+    compileCss?: boolean;
+    tailwindConfigPath?: string;
+    plugins?: EnginePlugin[];
+    /** Enable analyzer integration - provides semantic report (unused classes, conflicts). Default: false */
+    analyze?: boolean;
+}
+interface EngineWatchOptions {
+    debounceMs?: number;
+    maxEventsPerFlush?: number;
+    largeFileThreshold?: number;
+}
+interface BuildResult {
+    scan: ScanWorkspaceResult;
+    mergedClassList: string;
+    css: string;
+    /** Analyzer semantic report - present when analyze: true in options */
+    analysis?: {
+        unusedClasses: string[];
+        classConflicts: Array<{
+            className: string;
+            files: string[];
+            classes?: string[];
+            message?: string;
+        }>;
+        classUsage: Record<string, number>;
+        semantic?: AnalyzerSemanticReport;
+        report: AnalyzerReport;
+    };
+}
+type EngineBuildWatchEventType = "initial" | "change" | "unlink" | "full-rescan";
+type EngineWatchEvent = {
+    type: EngineBuildWatchEventType;
+    filePath?: string;
+    result: BuildResult;
+    metrics?: EngineMetricsSnapshot;
+} | {
+    type: "error";
+    filePath?: string;
+    error: string;
+    metrics?: EngineMetricsSnapshot;
+};
+interface TailwindStyledEngine {
+    scan(): Promise<ScanWorkspaceResult>;
+    scanWorkspace(): Promise<ScanWorkspaceResult>;
+    analyzeWorkspace(): Promise<Awaited<ReturnType<typeof analyzeWorkspace$1>>>;
+    generateSafelist(): Promise<string[]>;
+    build(): Promise<BuildResult>;
+    watch(onEvent: (event: EngineWatchEvent) => void, options?: EngineWatchOptions): Promise<{
+        close(): void;
+    }>;
+}
+declare function createEngine(rawOptions?: EngineOptions): Promise<TailwindStyledEngine>;
+
+/**
+ * Scan workspace dan return hasil scan.
+ * Facade tipis di atas scanWorkspaceAsync dari @tailwind-styled/scanner.
+ *
+ * @example
+ * const result = await scanWorkspace({ root: "./src" })
+ * console.log(result.uniqueClasses)
+ */
+declare function scanWorkspace(opts?: {
+    root?: string;
+    extensions?: string[];
+    ignoreDirectories?: string[];
+}): Promise<ScanWorkspaceResult>;
+/**
+ * Analyze workspace — scan + analyze classes.
+ * Facade di atas runWorkspaceAnalysis.
+ *
+ * @example
+ * const report = await analyzeWorkspace({ root: "./src" })
+ * console.log(report.topClasses)
+ */
+declare function analyzeWorkspace(opts?: {
+    root?: string;
+    top?: number;
+}): Promise<Awaited<ReturnType<typeof analyzeWorkspace$1>>>;
+/**
+ * Generate safelist dari scan result.
+ * Berguna untuk Tailwind config safelist generation.
+ *
+ * @example
+ * const safelist = await generateSafelist({ root: "./src" })
+ * // Pakai di tailwind.config.ts: { safelist }
+ */
+declare function generateSafelist(opts?: {
+    root?: string;
+}): Promise<string[]>;
+/**
+ * Build CSS dari scan result.
+ * One-shot build tanpa watch mode.
+ *
+ * @example
+ * const result = await build({ root: "./src" })
+ * fs.writeFileSync("dist/tailwind.css", result.css)
+ */
+declare function build(opts?: EngineOptions): Promise<{
+    css: string;
+    classes: string[];
+    totalFiles: number;
+}>;
+
+/**
+ * High-level trace API — satu entry point untuk semua tooling.
+ *
+ * Dipakai oleh:
+ * - CLI: `tw trace <class>`
+ * - DevTools: TracePanel fetch
+ * - Dashboard: trace endpoint
+ *
+ * @example
+ * const result = await traceClass("flex", scanResult, cssString)
+ * console.log(result.finalStyle)  // [{ property: "display", value: "flex" }]
+ */
+declare function traceClass(className: string, scanResult: ScanWorkspaceResult, css: string): Promise<TraceResult | null>;
+/**
+ * Trace multiple classes at once — for batch inspection.
+ */
+declare function traceClasses(classNames: string[], scanResult: ScanWorkspaceResult, css: string): Promise<Map<string, TraceResult>>;
+interface InspectionReport {
+    className: string;
+    /** CSS rules yang dihasilkan */
+    css: string;
+    /** Properties yang di-set */
+    properties: Array<{
+        property: string;
+        value: string;
+    }>;
+    /** Classes yang berkonflik dengan ini */
+    conflicts: string[];
+    /** Files yang menggunakan class ini */
+    usedIn: string[];
+    /** Risk level untuk removal */
+    risk: "low" | "medium" | "high";
+    /** Estimated bundle contribution */
+    bundleBytes: number;
+}
+/**
+ * Inspect a single class — gabungan trace + impact + usage.
+ * Reusable surface untuk CLI (`tw why`), DevTools panel, dashboard endpoint.
+ *
+ * @example
+ * const report = await inspectClass("flex", scanResult, cssString)
+ * console.log(report.properties)  // [{ property: "display", value: "flex" }]
+ * console.log(report.usedIn)      // ["src/Button.tsx", "src/Card.tsx"]
+ * console.log(report.risk)        // "low"
+ */
+declare function inspectClass(className: string, scanResult: ScanWorkspaceResult, css?: string): Promise<InspectionReport>;
+
+export { type BuildResult, type BuildResultInput, BuildResultSchema, type BundleAnalysisResult, BundleAnalyzer, type CascadeResolutionIR, CascadeResolutionId, CascadeResolver, CascadeStage, type ClassBundleInfo, type ClassUsage, type ComponentImpact, type ConditionIR, ConditionId, ConditionResult, type ConflictTrace, EngineMetricsCollector, type EngineMetricsSnapshot, type EngineOptions, type EngineOptionsInput, EngineOptionsSchema, type EnginePlugin, type EnginePluginContext, type EngineWatchContext, type EngineWatchEvent, type EngineWatchOptions, type EngineWatchOptionsInput, EngineWatchOptionsSchema, type FinalComputedStyleIR, type FinalStyleProperty, type ImpactReport, ImpactTracker, Importance, type InspectionReport, LayerId, Origin, type PropertyBucketIR, PropertyId, type ResolutionCause, type ResolutionReason, ReverseLookup, type ReverseLookupResult, type RuleIR, RuleId, type RuleTrace, type ScanFileResult, type ScanWorkspaceOptions, type ScanWorkspaceResult, type SelectorIR, SelectorId, type SourceLocation, type StyleGraphIR, type TailwindStyledEngine, type TraceResult, ValueId, type VariantChainIR, VariantChainId, type VariantTrace, type WatchCallback, type WatchEvent, type WatchEventKind, type WatchHandle, type WorkspaceWatcher, analyzeWorkspace, applyIncrementalChange, build, buildProvenanceChain, createEngine, createFingerprint, createResolutionReason, generateSafelist, inspectClass, parseCssToIr, parseEngineOptions, parseEngineWatchOptions, runAfterBuild, runAfterScan, runAfterWatch, runBeforeBuild, runBeforeScan, runBeforeWatch, runOnError, runTransformClasses, scanWorkspace, trace, traceClass, traceClasses, watchWorkspace$1 as watchWorkspaceLegacy, watchWorkspace as watchWorkspaceNative };