@csszyx/compiler 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -329,6 +329,39 @@ function stripInvalidColorStrings(sz) {
 var babel = __toESM(require("@babel/core"), 1);
 var t = __toESM(require("@babel/types"), 1);
 
+// src/ast-budget.ts
+var AST_BUDGET = 5e4;
+var ASTBudgetExceededError = class extends Error {
+  /**
+   *
+   * @param filename Source filename if known, otherwise `undefined`.
+   * @param nodeCount Node count at the point traversal was aborted.
+   * @param budget Effective budget that was exceeded. Defaults to
+   *   {@link AST_BUDGET} for backwards compatibility with callers that
+   *   don't pass an override.
+   */
+  constructor(filename, nodeCount, budget = AST_BUDGET) {
+    const where = filename ?? "<anonymous>";
+    super(
+      `[csszyx] AST budget exceeded: ${where} has more than ${budget} nodes (traversal aborted at ${nodeCount}). Files this large are almost always machine-generated and should be excluded from sz transformation. Either exclude the file from the plugin (Vite: \`csszyx({ exclude: [/large-data\\.ts$/] })\`), or raise the limit globally with \`csszyx({ build: { astBudgetLimit: 100_000 } })\`.`
+    );
+    this.name = "ASTBudgetExceededError";
+    this.filename = filename;
+    this.nodeCount = nodeCount;
+    this.budget = budget;
+  }
+};
+
+// src/recovery-tokens.ts
+var import_node_crypto = require("crypto");
+function generateInlineRecoveryToken(filename, line, column, elementType) {
+  const input = `${filename}:${line}:${column}:${elementType}`;
+  return (0, import_node_crypto.createHash)("sha256").update(input).digest("hex").substring(0, 12);
+}
+function isValidInlineRecoveryMode(value) {
+  return value === "csr" || value === "dev-only";
+}
+
 // src/transform-core.ts
 var PROPERTY_MAP = {
   // Background
@@ -2321,7 +2354,8 @@ function normalizeClassName(className) {
 }
 
 // src/transform.ts
-function transformSourceCode(source) {
+function transformSourceCode(source, filename, options) {
+  const astBudget = options?.astBudget ?? AST_BUDGET;
   let usesRuntime = false;
   let usesMerge = false;
   let usesColorVar = false;
@@ -2329,12 +2363,13 @@ function transformSourceCode(source) {
   const collectedClasses = /* @__PURE__ */ new Set();
   const rawClassNames = /* @__PURE__ */ new Set();
   const diagnostics = [];
+  const recoveryTokens = /* @__PURE__ */ new Map();
   if (!source.includes("sz")) {
-    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics };
+    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics, recoveryTokens };
   }
   try {
     const result = babel.transformSync(source, {
-      filename: "file.tsx",
+      filename: filename ?? "file.tsx",
       // Enable TS/JSX parsing
       ast: true,
       code: true,
@@ -2346,6 +2381,21 @@ function transformSourceCode(source) {
       plugins: [
         function() {
           return {
+            // Budget guard runs in `pre` (before the visitor pass)
+            // so it short-circuits pathologically large files
+            // before any sz transform work begins, and doesn't
+            // interfere with the JSXAttribute handler below.
+            pre(file) {
+              let nodeCount = 0;
+              babel.traverse(file.ast, {
+                enter() {
+                  nodeCount++;
+                  if (nodeCount > astBudget) {
+                    throw new ASTBudgetExceededError(filename, nodeCount, astBudget);
+                  }
+                }
+              });
+            },
             visitor: {
               JSXAttribute(path) {
                 const attrName = t.isJSXIdentifier(path.node.name) ? path.node.name.name : "";
@@ -2360,6 +2410,50 @@ function transformSourceCode(source) {
                   }
                   return;
                 }
+                if (attrName === "szRecover") {
+                  const recoverValue = path.node.value;
+                  if (!t.isStringLiteral(recoverValue)) {
+                    diagnostics.push(
+                      `[csszyx] szRecover at ${filename ?? "<anonymous>"}: only string-literal values ("csr" | "dev-only") are supported. Dynamic values disable token emission for this element.`
+                    );
+                    return;
+                  }
+                  if (!isValidInlineRecoveryMode(recoverValue.value)) {
+                    diagnostics.push(
+                      `[csszyx] szRecover at ${filename ?? "<anonymous>"}: unknown mode "${recoverValue.value}" \u2014 expected "csr" or "dev-only". Token emission skipped.`
+                    );
+                    return;
+                  }
+                  const opening = path.parentPath;
+                  if (!opening?.isJSXOpeningElement()) {
+                    return;
+                  }
+                  const alreadyTagged = opening.node.attributes.some(
+                    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name) && attr.name.name === "data-sz-recovery-token"
+                  );
+                  if (alreadyTagged) {
+                    return;
+                  }
+                  const loc = path.node.loc;
+                  const elementType = t.isJSXIdentifier(opening.node.name) ? opening.node.name.name : t.isJSXMemberExpression(opening.node.name) ? "<member>" : "<unknown>";
+                  const line = loc?.start.line ?? 0;
+                  const column = loc?.start.column ?? 0;
+                  const file = filename ?? "file.tsx";
+                  const token = generateInlineRecoveryToken(file, line, column, elementType);
+                  opening.node.attributes.push(
+                    t.jsxAttribute(
+                      t.jsxIdentifier("data-sz-recovery-token"),
+                      t.stringLiteral(token)
+                    )
+                  );
+                  recoveryTokens.set(token, {
+                    mode: recoverValue.value,
+                    component: elementType,
+                    path: `${file}:${line}:${column}`
+                  });
+                  transformed = true;
+                  return;
+                }
                 if (attrName !== "sz") {
                   return;
                 }
@@ -2862,11 +2956,15 @@ function transformSourceCode(source) {
       usesColorVar,
       classes: collectedClasses,
       rawClassNames,
-      diagnostics
+      diagnostics,
+      recoveryTokens
     };
   } catch (e) {
+    if (e instanceof ASTBudgetExceededError) {
+      throw e;
+    }
     console.warn("[csszyx] AST transform failed, falling back to original code:", e);
-    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics };
+    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics, recoveryTokens };
   }
 }
 function parseStyleStringToObjectExpr(styleStr) {
@@ -3716,7 +3814,7 @@ function hoistCSSVariables(usages, parentMap) {
 }
 function buildParentMap(ast) {
   const map = /* @__PURE__ */ new Map();
-  function traverse(node, parent) {
+  function traverse2(node, parent) {
     if (parent) {
       map.set(node, parent);
     }
@@ -3726,16 +3824,16 @@ function buildParentMap(ast) {
         if (Array.isArray(value)) {
           for (const item of value) {
             if (item && typeof item === "object" && "type" in item) {
-              traverse(item, node);
+              traverse2(item, node);
             }
           }
         } else if ("type" in value) {
-          traverse(value, node);
+          traverse2(value, node);
         }
       }
     }
   }
-  traverse(ast);
+  traverse2(ast);
   return map;
 }
 

package/dist/index.d.cts

@@ -1,137 +1,6 @@
 import * as t from '@babel/types';
 import * as CSS from 'csstype';
 
-/**
- * JSX Transform - Converts sz prop to className string.
- *
- * This module handles the transformation of csszyx object syntax into
- * Tailwind CSS class strings. It processes nested objects for variants
- * like hover, focus, etc.
- */
-/**
- * Represents a value in the sz object.
- * Can be a string, number, boolean, or nested object for variants.
- */
-type SzValue = string | number | boolean | SzObject;
-/**
- * Represents the sz object structure.
- * Keys are CSS property abbreviations, values can be primitives or nested objects.
- */
-interface SzObject {
-    [key: string]: SzValue;
-}
-declare const PROPERTY_MAP: Record<string, string>;
-declare const SUGGESTION_MAP: Record<string, string>;
-declare const KNOWN_VARIANTS: Set<string>;
-declare const BOOLEAN_SHORTHANDS: Set<string>;
-/**
- * Represents the result of a transformation.
- */
-interface TransformResult {
-    className: string;
-    attributes: Record<string, string>;
-}
-/**
- * Transforms a csszyx sz object into a Tailwind CSS className string and extracted attributes.
- *
- * @param {SzObject} szProp - The sz object from JSX
- * @param {string} prefix - Variant prefix for nested properties
- * @param {Record<string, string>} [mangleMap] - Optional map for property name mangling
- * @returns {TransformResult} The transformation result
- */
-declare function transform(szProp: SzObject, prefix?: string, mangleMap?: Record<string, string>): TransformResult;
-/**
- * Validates that an sz prop object is valid.
- *
- * @param {unknown} szProp - The value to validate
- * @returns {boolean} True if valid, false otherwise
- */
-declare function isValidSzProp(szProp: unknown): szProp is SzObject;
-/**
- * Normalizes a className string by removing extra whitespace.
- *
- * @param {string} className - The className string to normalize
- * @returns {string} The normalized className string
- */
-declare function normalizeClassName(className: string): string;
-
-/**
- * Transforms all sz props in a source code string into Tailwind classNames.
- *
- * @param {string} source - The source code to transform
- * @returns {object} Transformation result with code and metadata
- */
-declare function transformSourceCode(source: string): {
-    code: string;
-    transformed: boolean;
-    usesRuntime: boolean;
-    usesMerge: boolean;
-    usesColorVar: boolean;
-    classes: Set<string>;
-    rawClassNames: Set<string>;
-    diagnostics: string[];
-};
-
-/**
- * Core Compiler class for csszyx.
- *
- * This class manages the WASM lifecycle and provides high-performance
- * transformation methods. It falls back to JavaScript if WASM is not available.
- */
-declare class CsszyxCompiler {
-    private static instance;
-    private wasmLoaded;
-    /**
-     * Private constructor to enforce singleton pattern.
-     */
-    private constructor();
-    /**
-     * Gets the singleton instance of the compiler.
-     *
-     * @returns {CsszyxCompiler} The compiler instance.
-     */
-    static getInstance(): CsszyxCompiler;
-    /**
-     * Initializes the WASM core.
-     *
-     * @returns {Promise<void>} Resolves when WASM is ready.
-     */
-    init(): Promise<void>;
-    /**
-     * Transforms an sz object into Tailwind classes.
-     *
-     * @param {SzObject} sz - The object to transform.
-     * @returns {string} The transformed class string.
-     */
-    transform(sz: SzObject): string;
-    /**
-     * Checks if the WASM core is currently active.
-     *
-     * @returns {boolean} True if WASM is loaded.
-     */
-    isWasmActive(): boolean;
-    /**
-     * Generates a recovery token using WASM or JS fallback.
-     *
-     * @param {object} metadata - Token metadata
-     * @param metadata.component - Component name
-     * @param metadata.filePath - File path source
-     * @param metadata.line - Line number
-     * @param metadata.column - Column number
-     * @param metadata.mode - Build mode (dev/prod)
-     * @param metadata.buildId - Unique build identifier
-     * @returns {string} The generated token
-     */
-    generateRecoveryToken(metadata: {
-        component: string;
-        filePath: string;
-        line: number;
-        column: number;
-        mode: 'csr' | 'dev-only';
-        buildId: string;
-    }): string;
-}
-
 /**
  * Valid recovery modes for szRecover attribute.
  */
@@ -426,6 +295,157 @@ declare function validateManifest(manifest: unknown): {
     error?: string;
 };
 
+/**
+ * JSX Transform - Converts sz prop to className string.
+ *
+ * This module handles the transformation of csszyx object syntax into
+ * Tailwind CSS class strings. It processes nested objects for variants
+ * like hover, focus, etc.
+ */
+/**
+ * Represents a value in the sz object.
+ * Can be a string, number, boolean, or nested object for variants.
+ */
+type SzValue = string | number | boolean | SzObject;
+/**
+ * Represents the sz object structure.
+ * Keys are CSS property abbreviations, values can be primitives or nested objects.
+ */
+interface SzObject {
+    [key: string]: SzValue;
+}
+declare const PROPERTY_MAP: Record<string, string>;
+declare const SUGGESTION_MAP: Record<string, string>;
+declare const KNOWN_VARIANTS: Set<string>;
+declare const BOOLEAN_SHORTHANDS: Set<string>;
+/**
+ * Represents the result of a transformation.
+ */
+interface TransformResult {
+    className: string;
+    attributes: Record<string, string>;
+}
+/**
+ * Transforms a csszyx sz object into a Tailwind CSS className string and extracted attributes.
+ *
+ * @param {SzObject} szProp - The sz object from JSX
+ * @param {string} prefix - Variant prefix for nested properties
+ * @param {Record<string, string>} [mangleMap] - Optional map for property name mangling
+ * @returns {TransformResult} The transformation result
+ */
+declare function transform(szProp: SzObject, prefix?: string, mangleMap?: Record<string, string>): TransformResult;
+/**
+ * Validates that an sz prop object is valid.
+ *
+ * @param {unknown} szProp - The value to validate
+ * @returns {boolean} True if valid, false otherwise
+ */
+declare function isValidSzProp(szProp: unknown): szProp is SzObject;
+/**
+ * Normalizes a className string by removing extra whitespace.
+ *
+ * @param {string} className - The className string to normalize
+ * @returns {string} The normalized className string
+ */
+declare function normalizeClassName(className: string): string;
+
+/**
+ * Options for {@link transformSourceCode}.
+ */
+interface TransformSourceCodeOptions {
+    /**
+     * Override the AST node budget. Files larger than this throw
+     * {@link ASTBudgetExceededError}. Defaults to {@link AST_BUDGET} (50 000).
+     * Useful for repos with legitimately large generated files (json-as-ts
+     * fixtures, GraphQL schema snapshots) that exceed the default cap but
+     * are still safe to transform.
+     */
+    astBudget?: number;
+}
+/**
+ * Transforms all sz props in a source code string into Tailwind classNames.
+ *
+ * @param {string} source - The source code to transform
+ * @param {string} [filename] - Source filename, used in error messages and
+ *   passed to Babel as the parser filename. Defaults to a placeholder.
+ * @param {TransformSourceCodeOptions} [options] - Optional overrides
+ *   (currently: `astBudget` to raise/lower the per-file node cap).
+ * @returns {object} Transformation result with code and metadata
+ * @throws {ASTBudgetExceededError} when the file's AST exceeds the
+ *   effective budget (`options.astBudget` or {@link AST_BUDGET}).
+ */
+declare function transformSourceCode(source: string, filename?: string, options?: TransformSourceCodeOptions): {
+    code: string;
+    transformed: boolean;
+    usesRuntime: boolean;
+    usesMerge: boolean;
+    usesColorVar: boolean;
+    classes: Set<string>;
+    rawClassNames: Set<string>;
+    diagnostics: string[];
+    recoveryTokens: Map<string, TokenData>;
+};
+
+/**
+ * Core Compiler class for csszyx.
+ *
+ * This class manages the WASM lifecycle and provides high-performance
+ * transformation methods. It falls back to JavaScript if WASM is not available.
+ */
+declare class CsszyxCompiler {
+    private static instance;
+    private wasmLoaded;
+    /**
+     * Private constructor to enforce singleton pattern.
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of the compiler.
+     *
+     * @returns {CsszyxCompiler} The compiler instance.
+     */
+    static getInstance(): CsszyxCompiler;
+    /**
+     * Initializes the WASM core.
+     *
+     * @returns {Promise<void>} Resolves when WASM is ready.
+     */
+    init(): Promise<void>;
+    /**
+     * Transforms an sz object into Tailwind classes.
+     *
+     * @param {SzObject} sz - The object to transform.
+     * @returns {string} The transformed class string.
+     */
+    transform(sz: SzObject): string;
+    /**
+     * Checks if the WASM core is currently active.
+     *
+     * @returns {boolean} True if WASM is loaded.
+     */
+    isWasmActive(): boolean;
+    /**
+     * Generates a recovery token using WASM or JS fallback.
+     *
+     * @param {object} metadata - Token metadata
+     * @param metadata.component - Component name
+     * @param metadata.filePath - File path source
+     * @param metadata.line - Line number
+     * @param metadata.column - Column number
+     * @param metadata.mode - Build mode (dev/prod)
+     * @param metadata.buildId - Unique build identifier
+     * @returns {string} The generated token
+     */
+    generateRecoveryToken(metadata: {
+        component: string;
+        filePath: string;
+        line: number;
+        column: number;
+        mode: 'csr' | 'dev-only';
+        buildId: string;
+    }): string;
+}
+
 /**
  * Property Type System for CSS Variable Auto-Compile.
  *

package/dist/index.d.ts

@@ -1,137 +1,6 @@
 import * as t from '@babel/types';
 import * as CSS from 'csstype';
 
-/**
- * JSX Transform - Converts sz prop to className string.
- *
- * This module handles the transformation of csszyx object syntax into
- * Tailwind CSS class strings. It processes nested objects for variants
- * like hover, focus, etc.
- */
-/**
- * Represents a value in the sz object.
- * Can be a string, number, boolean, or nested object for variants.
- */
-type SzValue = string | number | boolean | SzObject;
-/**
- * Represents the sz object structure.
- * Keys are CSS property abbreviations, values can be primitives or nested objects.
- */
-interface SzObject {
-    [key: string]: SzValue;
-}
-declare const PROPERTY_MAP: Record<string, string>;
-declare const SUGGESTION_MAP: Record<string, string>;
-declare const KNOWN_VARIANTS: Set<string>;
-declare const BOOLEAN_SHORTHANDS: Set<string>;
-/**
- * Represents the result of a transformation.
- */
-interface TransformResult {
-    className: string;
-    attributes: Record<string, string>;
-}
-/**
- * Transforms a csszyx sz object into a Tailwind CSS className string and extracted attributes.
- *
- * @param {SzObject} szProp - The sz object from JSX
- * @param {string} prefix - Variant prefix for nested properties
- * @param {Record<string, string>} [mangleMap] - Optional map for property name mangling
- * @returns {TransformResult} The transformation result
- */
-declare function transform(szProp: SzObject, prefix?: string, mangleMap?: Record<string, string>): TransformResult;
-/**
- * Validates that an sz prop object is valid.
- *
- * @param {unknown} szProp - The value to validate
- * @returns {boolean} True if valid, false otherwise
- */
-declare function isValidSzProp(szProp: unknown): szProp is SzObject;
-/**
- * Normalizes a className string by removing extra whitespace.
- *
- * @param {string} className - The className string to normalize
- * @returns {string} The normalized className string
- */
-declare function normalizeClassName(className: string): string;
-
-/**
- * Transforms all sz props in a source code string into Tailwind classNames.
- *
- * @param {string} source - The source code to transform
- * @returns {object} Transformation result with code and metadata
- */
-declare function transformSourceCode(source: string): {
-    code: string;
-    transformed: boolean;
-    usesRuntime: boolean;
-    usesMerge: boolean;
-    usesColorVar: boolean;
-    classes: Set<string>;
-    rawClassNames: Set<string>;
-    diagnostics: string[];
-};
-
-/**
- * Core Compiler class for csszyx.
- *
- * This class manages the WASM lifecycle and provides high-performance
- * transformation methods. It falls back to JavaScript if WASM is not available.
- */
-declare class CsszyxCompiler {
-    private static instance;
-    private wasmLoaded;
-    /**
-     * Private constructor to enforce singleton pattern.
-     */
-    private constructor();
-    /**
-     * Gets the singleton instance of the compiler.
-     *
-     * @returns {CsszyxCompiler} The compiler instance.
-     */
-    static getInstance(): CsszyxCompiler;
-    /**
-     * Initializes the WASM core.
-     *
-     * @returns {Promise<void>} Resolves when WASM is ready.
-     */
-    init(): Promise<void>;
-    /**
-     * Transforms an sz object into Tailwind classes.
-     *
-     * @param {SzObject} sz - The object to transform.
-     * @returns {string} The transformed class string.
-     */
-    transform(sz: SzObject): string;
-    /**
-     * Checks if the WASM core is currently active.
-     *
-     * @returns {boolean} True if WASM is loaded.
-     */
-    isWasmActive(): boolean;
-    /**
-     * Generates a recovery token using WASM or JS fallback.
-     *
-     * @param {object} metadata - Token metadata
-     * @param metadata.component - Component name
-     * @param metadata.filePath - File path source
-     * @param metadata.line - Line number
-     * @param metadata.column - Column number
-     * @param metadata.mode - Build mode (dev/prod)
-     * @param metadata.buildId - Unique build identifier
-     * @returns {string} The generated token
-     */
-    generateRecoveryToken(metadata: {
-        component: string;
-        filePath: string;
-        line: number;
-        column: number;
-        mode: 'csr' | 'dev-only';
-        buildId: string;
-    }): string;
-}
-
 /**
  * Valid recovery modes for szRecover attribute.
  */
@@ -426,6 +295,157 @@ declare function validateManifest(manifest: unknown): {
     error?: string;
 };
 
+/**
+ * JSX Transform - Converts sz prop to className string.
+ *
+ * This module handles the transformation of csszyx object syntax into
+ * Tailwind CSS class strings. It processes nested objects for variants
+ * like hover, focus, etc.
+ */
+/**
+ * Represents a value in the sz object.
+ * Can be a string, number, boolean, or nested object for variants.
+ */
+type SzValue = string | number | boolean | SzObject;
+/**
+ * Represents the sz object structure.
+ * Keys are CSS property abbreviations, values can be primitives or nested objects.
+ */
+interface SzObject {
+    [key: string]: SzValue;
+}
+declare const PROPERTY_MAP: Record<string, string>;
+declare const SUGGESTION_MAP: Record<string, string>;
+declare const KNOWN_VARIANTS: Set<string>;
+declare const BOOLEAN_SHORTHANDS: Set<string>;
+/**
+ * Represents the result of a transformation.
+ */
+interface TransformResult {
+    className: string;
+    attributes: Record<string, string>;
+}
+/**
+ * Transforms a csszyx sz object into a Tailwind CSS className string and extracted attributes.
+ *
+ * @param {SzObject} szProp - The sz object from JSX
+ * @param {string} prefix - Variant prefix for nested properties
+ * @param {Record<string, string>} [mangleMap] - Optional map for property name mangling
+ * @returns {TransformResult} The transformation result
+ */
+declare function transform(szProp: SzObject, prefix?: string, mangleMap?: Record<string, string>): TransformResult;
+/**
+ * Validates that an sz prop object is valid.
+ *
+ * @param {unknown} szProp - The value to validate
+ * @returns {boolean} True if valid, false otherwise
+ */
+declare function isValidSzProp(szProp: unknown): szProp is SzObject;
+/**
+ * Normalizes a className string by removing extra whitespace.
+ *
+ * @param {string} className - The className string to normalize
+ * @returns {string} The normalized className string
+ */
+declare function normalizeClassName(className: string): string;
+
+/**
+ * Options for {@link transformSourceCode}.
+ */
+interface TransformSourceCodeOptions {
+    /**
+     * Override the AST node budget. Files larger than this throw
+     * {@link ASTBudgetExceededError}. Defaults to {@link AST_BUDGET} (50 000).
+     * Useful for repos with legitimately large generated files (json-as-ts
+     * fixtures, GraphQL schema snapshots) that exceed the default cap but
+     * are still safe to transform.
+     */
+    astBudget?: number;
+}
+/**
+ * Transforms all sz props in a source code string into Tailwind classNames.
+ *
+ * @param {string} source - The source code to transform
+ * @param {string} [filename] - Source filename, used in error messages and
+ *   passed to Babel as the parser filename. Defaults to a placeholder.
+ * @param {TransformSourceCodeOptions} [options] - Optional overrides
+ *   (currently: `astBudget` to raise/lower the per-file node cap).
+ * @returns {object} Transformation result with code and metadata
+ * @throws {ASTBudgetExceededError} when the file's AST exceeds the
+ *   effective budget (`options.astBudget` or {@link AST_BUDGET}).
+ */
+declare function transformSourceCode(source: string, filename?: string, options?: TransformSourceCodeOptions): {
+    code: string;
+    transformed: boolean;
+    usesRuntime: boolean;
+    usesMerge: boolean;
+    usesColorVar: boolean;
+    classes: Set<string>;
+    rawClassNames: Set<string>;
+    diagnostics: string[];
+    recoveryTokens: Map<string, TokenData>;
+};
+
+/**
+ * Core Compiler class for csszyx.
+ *
+ * This class manages the WASM lifecycle and provides high-performance
+ * transformation methods. It falls back to JavaScript if WASM is not available.
+ */
+declare class CsszyxCompiler {
+    private static instance;
+    private wasmLoaded;
+    /**
+     * Private constructor to enforce singleton pattern.
+     */
+    private constructor();
+    /**
+     * Gets the singleton instance of the compiler.
+     *
+     * @returns {CsszyxCompiler} The compiler instance.
+     */
+    static getInstance(): CsszyxCompiler;
+    /**
+     * Initializes the WASM core.
+     *
+     * @returns {Promise<void>} Resolves when WASM is ready.
+     */
+    init(): Promise<void>;
+    /**
+     * Transforms an sz object into Tailwind classes.
+     *
+     * @param {SzObject} sz - The object to transform.
+     * @returns {string} The transformed class string.
+     */
+    transform(sz: SzObject): string;
+    /**
+     * Checks if the WASM core is currently active.
+     *
+     * @returns {boolean} True if WASM is loaded.
+     */
+    isWasmActive(): boolean;
+    /**
+     * Generates a recovery token using WASM or JS fallback.
+     *
+     * @param {object} metadata - Token metadata
+     * @param metadata.component - Component name
+     * @param metadata.filePath - File path source
+     * @param metadata.line - Line number
+     * @param metadata.column - Column number
+     * @param metadata.mode - Build mode (dev/prod)
+     * @param metadata.buildId - Unique build identifier
+     * @returns {string} The generated token
+     */
+    generateRecoveryToken(metadata: {
+        component: string;
+        filePath: string;
+        line: number;
+        column: number;
+        mode: 'csr' | 'dev-only';
+        buildId: string;
+    }): string;
+}
+
 /**
  * Property Type System for CSS Variable Auto-Compile.
  *

package/dist/index.js

@@ -270,6 +270,39 @@ function stripInvalidColorStrings(sz) {
 import * as babel from "@babel/core";
 import * as t from "@babel/types";
 
+// src/ast-budget.ts
+var AST_BUDGET = 5e4;
+var ASTBudgetExceededError = class extends Error {
+  /**
+   *
+   * @param filename Source filename if known, otherwise `undefined`.
+   * @param nodeCount Node count at the point traversal was aborted.
+   * @param budget Effective budget that was exceeded. Defaults to
+   *   {@link AST_BUDGET} for backwards compatibility with callers that
+   *   don't pass an override.
+   */
+  constructor(filename, nodeCount, budget = AST_BUDGET) {
+    const where = filename ?? "<anonymous>";
+    super(
+      `[csszyx] AST budget exceeded: ${where} has more than ${budget} nodes (traversal aborted at ${nodeCount}). Files this large are almost always machine-generated and should be excluded from sz transformation. Either exclude the file from the plugin (Vite: \`csszyx({ exclude: [/large-data\\.ts$/] })\`), or raise the limit globally with \`csszyx({ build: { astBudgetLimit: 100_000 } })\`.`
+    );
+    this.name = "ASTBudgetExceededError";
+    this.filename = filename;
+    this.nodeCount = nodeCount;
+    this.budget = budget;
+  }
+};
+
+// src/recovery-tokens.ts
+import { createHash } from "crypto";
+function generateInlineRecoveryToken(filename, line, column, elementType) {
+  const input = `${filename}:${line}:${column}:${elementType}`;
+  return createHash("sha256").update(input).digest("hex").substring(0, 12);
+}
+function isValidInlineRecoveryMode(value) {
+  return value === "csr" || value === "dev-only";
+}
+
 // src/transform-core.ts
 var PROPERTY_MAP = {
   // Background
@@ -2262,7 +2295,8 @@ function normalizeClassName(className) {
 }
 
 // src/transform.ts
-function transformSourceCode(source) {
+function transformSourceCode(source, filename, options) {
+  const astBudget = options?.astBudget ?? AST_BUDGET;
   let usesRuntime = false;
   let usesMerge = false;
   let usesColorVar = false;
@@ -2270,12 +2304,13 @@ function transformSourceCode(source) {
   const collectedClasses = /* @__PURE__ */ new Set();
   const rawClassNames = /* @__PURE__ */ new Set();
   const diagnostics = [];
+  const recoveryTokens = /* @__PURE__ */ new Map();
   if (!source.includes("sz")) {
-    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics };
+    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics, recoveryTokens };
   }
   try {
     const result = babel.transformSync(source, {
-      filename: "file.tsx",
+      filename: filename ?? "file.tsx",
       // Enable TS/JSX parsing
       ast: true,
       code: true,
@@ -2287,6 +2322,21 @@ function transformSourceCode(source) {
       plugins: [
         function() {
           return {
+            // Budget guard runs in `pre` (before the visitor pass)
+            // so it short-circuits pathologically large files
+            // before any sz transform work begins, and doesn't
+            // interfere with the JSXAttribute handler below.
+            pre(file) {
+              let nodeCount = 0;
+              babel.traverse(file.ast, {
+                enter() {
+                  nodeCount++;
+                  if (nodeCount > astBudget) {
+                    throw new ASTBudgetExceededError(filename, nodeCount, astBudget);
+                  }
+                }
+              });
+            },
             visitor: {
               JSXAttribute(path) {
                 const attrName = t.isJSXIdentifier(path.node.name) ? path.node.name.name : "";
@@ -2301,6 +2351,50 @@ function transformSourceCode(source) {
                   }
                   return;
                 }
+                if (attrName === "szRecover") {
+                  const recoverValue = path.node.value;
+                  if (!t.isStringLiteral(recoverValue)) {
+                    diagnostics.push(
+                      `[csszyx] szRecover at ${filename ?? "<anonymous>"}: only string-literal values ("csr" | "dev-only") are supported. Dynamic values disable token emission for this element.`
+                    );
+                    return;
+                  }
+                  if (!isValidInlineRecoveryMode(recoverValue.value)) {
+                    diagnostics.push(
+                      `[csszyx] szRecover at ${filename ?? "<anonymous>"}: unknown mode "${recoverValue.value}" \u2014 expected "csr" or "dev-only". Token emission skipped.`
+                    );
+                    return;
+                  }
+                  const opening = path.parentPath;
+                  if (!opening?.isJSXOpeningElement()) {
+                    return;
+                  }
+                  const alreadyTagged = opening.node.attributes.some(
+                    (attr) => t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name) && attr.name.name === "data-sz-recovery-token"
+                  );
+                  if (alreadyTagged) {
+                    return;
+                  }
+                  const loc = path.node.loc;
+                  const elementType = t.isJSXIdentifier(opening.node.name) ? opening.node.name.name : t.isJSXMemberExpression(opening.node.name) ? "<member>" : "<unknown>";
+                  const line = loc?.start.line ?? 0;
+                  const column = loc?.start.column ?? 0;
+                  const file = filename ?? "file.tsx";
+                  const token = generateInlineRecoveryToken(file, line, column, elementType);
+                  opening.node.attributes.push(
+                    t.jsxAttribute(
+                      t.jsxIdentifier("data-sz-recovery-token"),
+                      t.stringLiteral(token)
+                    )
+                  );
+                  recoveryTokens.set(token, {
+                    mode: recoverValue.value,
+                    component: elementType,
+                    path: `${file}:${line}:${column}`
+                  });
+                  transformed = true;
+                  return;
+                }
                 if (attrName !== "sz") {
                   return;
                 }
@@ -2803,11 +2897,15 @@ function transformSourceCode(source) {
       usesColorVar,
       classes: collectedClasses,
       rawClassNames,
-      diagnostics
+      diagnostics,
+      recoveryTokens
     };
   } catch (e) {
+    if (e instanceof ASTBudgetExceededError) {
+      throw e;
+    }
     console.warn("[csszyx] AST transform failed, falling back to original code:", e);
-    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics };
+    return { code: source, transformed: false, usesRuntime: false, usesMerge: false, usesColorVar: false, classes: collectedClasses, rawClassNames, diagnostics, recoveryTokens };
   }
 }
 function parseStyleStringToObjectExpr(styleStr) {
@@ -3374,7 +3472,7 @@ function injectRecoveryToken(attributes, token) {
 }
 
 // src/manifest.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 var ManifestBuilder = class {
   /**
    * Creates a new manifest builder.
@@ -3447,7 +3545,7 @@ var ManifestBuilder = class {
       sortedTokens[key] = tokens[key];
     }
     const content = JSON.stringify(sortedTokens);
-    return createHash("sha256").update(content).digest("hex");
+    return createHash2("sha256").update(content).digest("hex");
   }
   /**
    * Builds the final recovery manifest.
@@ -3657,7 +3755,7 @@ function hoistCSSVariables(usages, parentMap) {
 }
 function buildParentMap(ast) {
   const map = /* @__PURE__ */ new Map();
-  function traverse(node, parent) {
+  function traverse2(node, parent) {
     if (parent) {
       map.set(node, parent);
     }
@@ -3667,16 +3765,16 @@ function buildParentMap(ast) {
         if (Array.isArray(value)) {
           for (const item of value) {
             if (item && typeof item === "object" && "type" in item) {
-              traverse(item, node);
+              traverse2(item, node);
             }
           }
         } else if ("type" in value) {
-          traverse(value, node);
+          traverse2(value, node);
         }
       }
     }
   }
-  traverse(ast);
+  traverse2(ast);
   return map;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@csszyx/compiler",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Core compiler and transformation logic for csszyx",
   "keywords": [
     "csszyx",
@@ -47,7 +47,7 @@
     "@babel/core": "^7.23.7",
     "@babel/types": "^7.23.6",
     "@babel/traverse": "^7.23.7",
-    "@csszyx/core": "0.4.0"
+    "@csszyx/core": "0.6.0"
   },
   "devDependencies": {
     "@types/babel__core": "^7.20.5",