@csszyx/unplugin 0.9.9 → 0.10.0

package/dist/shared/{unplugin.CMsKFZ-l.mjs → unplugin.CLXpKBe4.mjs}

@@ -13,6 +13,7 @@ import { isTailwindReservedCustomProperty, CSSZYX_GLOBAL_ALIAS_PREFIX, isCsszyxG
 import { preprocess } from '@csszyx/vue-adapter';
 import { createUnplugin } from 'unplugin';
 import { mangleCSSSync } from '../css-mangler.mjs';
+import { e as escapeHtmlAttribute } from './unplugin.3UumZ5gn.mjs';
 import { createHash } from 'node:crypto';
 import { r as resolveTransformCacheDir, c as createTransformCacheKey, a as readTransformCache, w as writeTransformCache, e as evictOldTransformCacheEntries } from './unplugin.BpWUtI9U.mjs';
 import postcss from 'postcss';
@@ -454,15 +455,7 @@ const CLIENT_RUNTIME_MODULES = /* @__PURE__ */ new Set(["csszyx/browser"]);
 const CLIENT_RUNTIME_MODULE_ROOTS = ["@csszyx/dynamic", "csszyx/dynamic"];
 const normalizedModuleIdCache = /* @__PURE__ */ new Map();
 const resolvedLocalModuleCache = /* @__PURE__ */ new Map();
-const FORBIDDEN_SYMBOLS = /* @__PURE__ */ new Set([
-  "_sz",
-  "_sz2",
-  "_sz3",
-  "_szIf",
-  "_szMerge",
-  "_szSwitch",
-  "__csszyx_runtime__"
-]);
+const FORBIDDEN_SYMBOLS = /* @__PURE__ */ new Set(["_sz", "_sz2", "_sz3", "_szMerge", "__csszyx_runtime__"]);
 function hasUseServerDirective(code) {
   for (const statement of readDirectivePrologue(code)) {
     if (SERVER_DIRECTIVE_RE.test(statement)) {
@@ -841,7 +834,10 @@ function resolveLocalModule(importer, source) {
   const cacheKey = `${importer}\0${source}`;
   const cached = resolvedLocalModuleCache.get(cacheKey);
   if (cached) {
-    return cached;
+    if (fs.existsSync(cached)) {
+      return cached;
+    }
+    resolvedLocalModuleCache.delete(cacheKey);
   }
   const base = source.startsWith("/") ? source : path.resolve(path.dirname(importer), source);
   const candidates = [
@@ -1006,7 +1002,14 @@ function stripCommentsForImportScan(code) {
   return out;
 }
 
-const EMPTY_THEME = { colors: [], spacings: [], fonts: [], radii: [], shadows: [] };
+const EMPTY_THEME = {
+  colors: [],
+  spacings: [],
+  fonts: [],
+  radii: [],
+  shadows: [],
+  breakpoints: []
+};
 function stripLayerWrappers(css) {
   let result = "";
   let i = 0;
@@ -1074,12 +1077,15 @@ function categorizeProperty(prop) {
     ["spacing-", "spacings"],
     ["font-", "fonts"],
     ["radius-", "radii"],
-    ["shadow-", "shadows"]
+    ["shadow-", "shadows"],
+    ["breakpoint-", "breakpoints"]
   ];
   for (const [prefix, category] of categoryMap) {
     if (prop.startsWith(prefix)) {
       let token = prop.slice(prefix.length);
-      token = token.replace(/-\d+$/, "");
+      if (category !== "breakpoints") {
+        token = token.replace(/-\d+$/, "");
+      }
       if (token) {
         return { category, token };
       }
@@ -1093,7 +1099,8 @@ function parseThemeBlocks(cssContent) {
     spacings: /* @__PURE__ */ new Set(),
     fonts: /* @__PURE__ */ new Set(),
     radii: /* @__PURE__ */ new Set(),
-    shadows: /* @__PURE__ */ new Set()
+    shadows: /* @__PURE__ */ new Set(),
+    breakpoints: /* @__PURE__ */ new Set()
   };
   const stripped = stripLayerWrappers(cssContent);
   const blocks = extractThemeBlocks(stripped);
@@ -1111,7 +1118,8 @@ function parseThemeBlocks(cssContent) {
     spacings: [...result.spacings].sort(),
     fonts: [...result.fonts].sort(),
     radii: [...result.radii].sort(),
-    shadows: [...result.shadows].sort()
+    shadows: [...result.shadows].sort(),
+    breakpoints: [...result.breakpoints].sort()
   };
 }
 function mergeThemes(themes) {
@@ -1123,7 +1131,8 @@ function mergeThemes(themes) {
     spacings: /* @__PURE__ */ new Set(),
     fonts: /* @__PURE__ */ new Set(),
     radii: /* @__PURE__ */ new Set(),
-    shadows: /* @__PURE__ */ new Set()
+    shadows: /* @__PURE__ */ new Set(),
+    breakpoints: /* @__PURE__ */ new Set()
   };
   for (const theme of themes) {
     for (const cat of Object.keys(merged)) {
@@ -1137,7 +1146,8 @@ function mergeThemes(themes) {
     spacings: [...merged.spacings].sort(),
     fonts: [...merged.fonts].sort(),
     radii: [...merged.radii].sort(),
-    shadows: [...merged.shadows].sort()
+    shadows: [...merged.shadows].sort(),
+    breakpoints: [...merged.breakpoints].sort()
   };
 }
 function hasTokens(theme) {
@@ -1425,11 +1435,15 @@ function isSameFileVersion(before, after) {
   return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeNs === after.mtimeNs && before.ctimeNs === after.ctimeNs;
 }
 
+function escapeTsString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\r/g, "\\r").replace(/\n/g, "\\n");
+}
 function generateThemeDts(opts) {
   const { theme, sourceFiles } = opts;
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-  const sources = sourceFiles.join(", ");
-  const toUnion = (tokens) => tokens.map((t) => `'${t}'`).join(" | ");
+  const sources = sourceFiles.join(", ").replace(/[\r\n]/g, " ");
+  const toUnion = (tokens) => tokens.map((t) => `'${escapeTsString(t)}'`).join(" | ");
+  const quoteKey = (key) => /^[a-z_$][\w$]*$/i.test(key) ? key : `'${escapeTsString(key)}'`;
   const entries = [];
   if (theme.colors.length > 0) {
     entries.push(`        colors: ${toUnion(theme.colors)};`);
@@ -1446,19 +1460,36 @@ function generateThemeDts(opts) {
   if (theme.shadows.length > 0) {
     entries.push(`        shadows: ${toUnion(theme.shadows)};`);
   }
-  return [
-    "// Auto-generated by csszyx theme-scanner \u2014 DO NOT EDIT",
-    `// Source: ${sources}`,
-    `// Updated: ${timestamp}`,
-    "",
-    "declare module '@csszyx/compiler' {",
+  const moduleBody = [
     "    /**",
     "     * Custom design tokens extracted from @theme blocks.",
     "     * These tokens are surfaced in sz prop IntelliSense.",
     "     */",
     "    interface CustomTheme {",
     ...entries,
-    "    }",
+    "    }"
+  ];
+  if (theme.breakpoints.length > 0) {
+    const variantEntries = theme.breakpoints.map(
+      (bp) => `        ${quoteKey(bp)}?: SzPropsBase;`
+    );
+    moduleBody.push(
+      "    /**",
+      "     * Custom responsive breakpoints from @theme (--breakpoint-*),",
+      "     * surfaced as typed sz variant keys.",
+      "     */",
+      "    interface VariantModifiers {",
+      ...variantEntries,
+      "    }"
+    );
+  }
+  return [
+    "// Auto-generated by csszyx theme-scanner \u2014 DO NOT EDIT",
+    `// Source: ${sources}`,
+    `// Updated: ${timestamp}`,
+    "",
+    "declare module '@csszyx/compiler' {",
+    ...moduleBody,
     "}",
     "",
     "export {};",
@@ -1532,6 +1563,7 @@ const UNKNOWN_PACKAGE_VERSION = "0.0.0";
 const TRANSFORM_CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
 const TRANSFORM_CACHE_MAX_ENTRIES = 1e4;
 const TRANSFORM_MEMORY_CACHE_MAX_ENTRIES = 1e3;
+const MAX_SAFELIST_CLASSES = 1e5;
 const DEFAULT_VAR_MANGLE_MAP_MAX_BYTES = 100 * 1024;
 const GLOBAL_VAR_ALIAS_MAP_OWNER = "\0csszyx:global-var-aliases";
 const DIRECTIVE_PROLOGUE_PREFIX_RE = /^((?:\s|\/\/[^\n]*\n|\/\*(?:[^*]|\*(?!\/))*\*\/)*)(['"]use (?:client|server)['"];?\s*)/;
@@ -1572,6 +1604,133 @@ function resolveNativeCacheIdentity() {
 }
 const BENCH_TRACE_ENABLED = process.env.CSSZYX_BENCH_TRACE === "1";
 const BENCH_TRACE_FILE = process.env.CSSZYX_BENCH_TRACE_FILE;
+function appendTailwindSourceDirective(code, relPath) {
+  const directive = `@source "${relPath}";`;
+  if (code.includes(directive)) {
+    return null;
+  }
+  const separator = code.length === 0 || code.endsWith("\n") ? "" : "\n";
+  return `${code}${separator}${directive}
+`;
+}
+function stripCssBlockComments(code) {
+  const SLASH = 47;
+  const STAR = 42;
+  let out = "";
+  let last = 0;
+  let i = 0;
+  const n = code.length;
+  while (i < n) {
+    if (code.charCodeAt(i) === SLASH && code.charCodeAt(i + 1) === STAR) {
+      out += code.slice(last, i);
+      i += 2;
+      while (i < n && !(code.charCodeAt(i) === STAR && code.charCodeAt(i + 1) === SLASH)) {
+        i++;
+      }
+      i += 2;
+      last = i;
+    } else {
+      i++;
+    }
+  }
+  return out + code.slice(last);
+}
+function cssImportsTailwind(code) {
+  const withoutBlockComments = stripCssBlockComments(code);
+  return /@import\s+["']tailwindcss(?:\/[^"']*)?["']/.test(withoutBlockComments);
+}
+function hasInjectableTailwindCandidate(classes) {
+  for (const c of classes) {
+    if (c.length >= 2 && /^[a-z]/.test(c)) {
+      return true;
+    }
+  }
+  return false;
+}
+function shouldWarnMissingTailwindEntry(ownedClassCount, sawTailwindEntry) {
+  return ownedClassCount > 0 && !sawTailwindEntry;
+}
+function missingTailwindEntryMessage(ownedClassCount) {
+  return `[csszyx] generated ${ownedClassCount} sz class(es) but found no CSS entry importing "tailwindcss" \u2014 those classes will produce no CSS. Import "tailwindcss" in a CSS file (csszyx auto-injects @source for the generated classes) so Tailwind emits their styles.`;
+}
+function cssHasContentScope(code) {
+  const s = stripCssBlockComments(code);
+  return /@import\s+["']tailwindcss(?:\/[^"']*)?["']\s+source\(/.test(s) || /@source\s+not\b/.test(s);
+}
+function isMonorepoPackage(root) {
+  let dir = path.dirname(path.resolve(root));
+  const { root: fsRoot } = path.parse(dir);
+  while (dir !== fsRoot) {
+    if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml")) || fs.existsSync(path.join(dir, "nx.json")) || fs.existsSync(path.join(dir, "lerna.json"))) {
+      return true;
+    }
+    const pkgPath = path.join(dir, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        if ("workspaces" in JSON.parse(fs.readFileSync(pkgPath, "utf8"))) {
+          return true;
+        }
+      } catch {
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  return false;
+}
+function shouldWarnUnscopedMonorepo(sawTailwindEntry, tailwindEntryScoped, inMonorepo) {
+  return sawTailwindEntry && !tailwindEntryScoped && inMonorepo;
+}
+function unscopedMonorepoMessage() {
+  return '[csszyx] Tailwind content detection is UNSCOPED in a monorepo. Tailwind v4 climbs to the workspace root and scans sibling packages + docs (.md/.mdx/.txt are not ignored), which can generate phantom or broken url() classes and fail the build. Scope it in your Tailwind CSS entry:\n    @import "tailwindcss" source(none);\n    @source ".";   /* this package, relative to the CSS file */\ncsszyx auto-injects @source for its generated classes, so only your own templates need listing. Guide: https://csszyx.com/docs/monorepo-content-scope/\nSilence (if a broad scan is intentional): csszyx({ contentScopeCheck: false }).';
+}
+function isCompilePackageOptedIn(id, compilePackages) {
+  const path2 = id.replace(/\\/g, "/");
+  if (path2.includes("node_modules")) {
+    return false;
+  }
+  return compilePackages.some((name) => path2.includes(`/packages/${name}/`));
+}
+function isHardIgnoredPath(id, compilePackages = []) {
+  const path2 = id.replace(/\\/g, "/");
+  if (path2.includes("node_modules")) {
+    return true;
+  }
+  if (path2.includes(".next") && !path2.includes("static")) {
+    return true;
+  }
+  if (path2.includes("/packages/")) {
+    return !isCompilePackageOptedIn(path2, compilePackages);
+  }
+  return false;
+}
+function isPackagesSkippedSource(id, compilePackages = []) {
+  const path2 = id.replace(/\\/g, "/");
+  if (path2.includes("node_modules")) {
+    return false;
+  }
+  if (path2.includes(".next") && !path2.includes("static")) {
+    return false;
+  }
+  if (!path2.includes("/packages/")) {
+    return false;
+  }
+  return !isCompilePackageOptedIn(path2, compilePackages);
+}
+function skippedSzFilesMessage(files) {
+  const list = files.map((file) => `  - ${file}`).join("\n");
+  return `[csszyx] ${files.length} file(s) under packages/ contain \`sz\` but were skipped by ignore rules:
+${list}
+Add the package to \`compilePackages\` (or move the file out of packages/) \u2014 otherwise their \`sz\` produces no CSS.`;
+}
+function computeSafelistRelPath(rootDir, safelistFilename, cssId) {
+  const safelistPath = path.join(rootDir, safelistFilename).replace(/\\/g, "/");
+  const cssDir = path.dirname(cssId).replace(/\\/g, "/");
+  let relPath = path.posix.relative(cssDir, safelistPath);
+  if (!relPath.startsWith(".")) {
+    relPath = `./${relPath}`;
+  }
+  return relPath;
+}
 function cssVariableEntries(result) {
   const entries = [];
   for (const [original, value] of result.cssVariableMap ?? []) {
@@ -2035,6 +2194,45 @@ function mangleCodeClassesSync(code, mangleMap) {
     }
     return changed ? `className:\`${out}\`` : fullMatch;
   });
+  function scanClassExpression(source, from) {
+    let depth = 0;
+    let j = from;
+    while (j < source.length) {
+      const ch = source[j];
+      if (ch === "(" || ch === "[") {
+        depth++;
+      } else if (ch === ")" || ch === "]") {
+        if (depth === 0) {
+          break;
+        }
+        depth--;
+      } else if (depth === 0 && (ch === "," || ch === ";" || ch === "\n" || ch === "}")) {
+        break;
+      }
+      j++;
+    }
+    return j;
+  }
+  function mangleTernaryClassStrings(expr) {
+    const qIdx = expr.indexOf("?");
+    if (qIdx === -1 || !expr.slice(qIdx).includes(":")) {
+      return null;
+    }
+    let changed = false;
+    const mangled = expr.replace(/"([^"]*)"/g, (qm, inner) => {
+      const parts = inner.split(/\s+/).filter(Boolean);
+      if (parts.length === 0) {
+        return qm;
+      }
+      const mangledStr = parts.map((p) => mangleMap[p] || p).join(" ");
+      if (mangledStr !== inner) {
+        changed = true;
+        return `"${mangledStr}"`;
+      }
+      return qm;
+    });
+    return changed ? mangled : null;
+  }
   {
     const marker = "className:";
     let searchFrom = 0;
@@ -2056,47 +2254,39 @@ function mangleCodeClassesSync(code, mangleMap) {
         searchFrom = afterColon;
         continue;
       }
-      let depth = 0;
-      let j = afterColon;
-      while (j < result.length) {
-        const ch = result[j];
-        if (ch === "(" || ch === "[") {
-          depth++;
-        } else if (ch === ")" || ch === "]") {
-          if (depth === 0) {
-            break;
-          }
-          depth--;
-        } else if (depth === 0 && (ch === "," || ch === ";" || ch === "\n" || ch === "}")) {
-          break;
-        }
-        j++;
-      }
+      const j = scanClassExpression(result, afterColon);
       const expr = result.slice(afterColon, j);
-      const qIdx = expr.indexOf("?");
-      if (qIdx === -1 || !expr.slice(qIdx).includes(":")) {
-        out += expr;
-        searchFrom = j;
-        continue;
-      }
-      let changed = false;
-      const mangled = expr.replace(/"([^"]*)"/g, (qm, inner) => {
-        const parts = inner.split(/\s+/).filter(Boolean);
-        if (parts.length === 0) {
-          return qm;
-        }
-        const mangledStr = parts.map((p) => mangleMap[p] || p).join(" ");
-        if (mangledStr !== inner) {
-          changed = true;
-          return `"${mangledStr}"`;
-        }
-        return qm;
-      });
-      out += changed ? mangled : expr;
+      out += mangleTernaryClassStrings(expr) ?? expr;
       searchFrom = j;
     }
     result = out;
   }
+  {
+    const markerRe = /"class(?:Name)?"\s*,\s*/g;
+    let out = "";
+    let copiedTo = 0;
+    let m = markerRe.exec(result);
+    while (m !== null) {
+      const exprStart = m.index + m[0].length;
+      const firstChar = result[exprStart];
+      if (firstChar === '"' || firstChar === "'" || firstChar === "`") {
+        m = markerRe.exec(result);
+        continue;
+      }
+      const j = scanClassExpression(result, exprStart);
+      const expr = result.slice(exprStart, j);
+      const mangled = mangleTernaryClassStrings(expr);
+      if (mangled !== null) {
+        out += result.slice(copiedTo, exprStart) + mangled;
+        copiedTo = j;
+      }
+      markerRe.lastIndex = j;
+      m = markerRe.exec(result);
+    }
+    if (copiedTo > 0) {
+      result = out + result.slice(copiedTo);
+    }
+  }
   result = result.replace(/(?<=(?:[,(]|&&)\s*)"([^"]+)"/g, (match, inner) => {
     const tokens = inner.split(/\s+/).filter(Boolean);
     if (tokens.length === 0) {
@@ -2164,6 +2354,7 @@ function createCsszyxPlugins(options = {}) {
       "[csszyx] Transform cache disabled because package versions could not be resolved."
     );
   }
+  const compilePackages = options.compilePackages ?? [];
   const parserOverride = process.env.CSSZYX_PARSER;
   const defaultParser = DEFAULT_BUILD_CONFIG.parser ?? "rust";
   const parserMode = parserOverride === "babel" || parserOverride === "oxc" || parserOverride === "rust" ? parserOverride : options.build?.parser ?? defaultParser;
@@ -2171,6 +2362,15 @@ function createCsszyxPlugins(options = {}) {
   const transformMemoryCache = /* @__PURE__ */ new Map();
   const state = {
     classes: /* @__PURE__ */ new Set(),
+    sawTailwindEntry: false,
+    tailwindWarningEmitted: false,
+    tailwindEntryScoped: false,
+    contentScopeWarningEmitted: false,
+    spreadWarnings: /* @__PURE__ */ new Set(),
+    skippedSzFiles: /* @__PURE__ */ new Set(),
+    skipWarningEmitted: false,
+    classesCapped: false,
+    ownedClasses: /* @__PURE__ */ new Set(),
     mangleMap: {},
     varMangleEntriesByFile: /* @__PURE__ */ new Map(),
     varMangleMap: Object.fromEntries(earlyGlobalVarAliasEntries),
@@ -2231,7 +2431,7 @@ function createCsszyxPlugins(options = {}) {
     return result;
   }
   function isHardIgnored(id) {
-    return id.includes("node_modules") || id.includes("/packages/") || id.includes(".next") && !id.includes("static");
+    return isHardIgnoredPath(id, compilePackages);
   }
   function shouldProcessSource(id) {
     return !isHardIgnored(id) && !isUserExcluded(id) && isUserIncluded(id) && (/\.[tj]sx?(\?.*)?$/.test(id) || id.endsWith(".vue") || id.endsWith(".svelte"));
@@ -2437,12 +2637,19 @@ function createCsszyxPlugins(options = {}) {
       maxEntries: TRANSFORM_CACHE_MAX_ENTRIES
     });
   }
+  function addSafelistClass(cls) {
+    if (state.classes.size >= MAX_SAFELIST_CLASSES) {
+      state.classesCapped = true;
+      return;
+    }
+    state.classes.add(cls);
+  }
   function writeSafelistFile(classes) {
     if (classes.size === 0) {
       return;
     }
     const safelistPath = path.join(state.rootDir, SAFELIST_FILENAME);
-    const classList = Array.from(classes).join(" ");
+    const classList = escapeHtmlAttribute(Array.from(classes).join(" "));
     const content = `<!-- Auto-generated by csszyx \u2014 DO NOT EDIT -->
 <!-- Tailwind CSS scans this file for class name detection -->
 <div class="${classList}"><div class="${classList}">x</div><div class="${classList}">x</div></div>
@@ -2462,6 +2669,20 @@ function createCsszyxPlugins(options = {}) {
     } catch {
     }
   }
+  function recordPackagesSkipIfSz(filePath) {
+    if (!isPackagesSkippedSource(filePath, compilePackages)) {
+      return;
+    }
+    let content;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      return;
+    }
+    if (content.includes("sz=") || content.includes("sz:")) {
+      state.skippedSzFiles.add(filePath);
+    }
+  }
   function prescanAndWriteClasses() {
     const prescanStarted = performance.now();
     const discoveredClasses = /* @__PURE__ */ new Set();
@@ -2482,6 +2703,7 @@ function createCsszyxPlugins(options = {}) {
         } else if (SOURCE_EXTENSIONS.has(path.extname(entry.name))) {
           const filePath = path.join(dir, entry.name);
           if (!shouldProcessSource(filePath)) {
+            recordPackagesSkipIfSz(filePath);
             continue;
           }
           let content;
@@ -2505,7 +2727,8 @@ function createCsszyxPlugins(options = {}) {
       collectPrescanResult(result, filePath, discoveredClasses, rawDiscoveredClasses);
     }
     for (const cls of discoveredClasses) {
-      state.classes.add(cls);
+      addSafelistClass(cls);
+      state.ownedClasses.add(cls);
     }
     const safelistClasses = /* @__PURE__ */ new Set([...discoveredClasses, ...rawDiscoveredClasses]);
     writeSafelistFile(safelistClasses);
@@ -2593,7 +2816,7 @@ function createCsszyxPlugins(options = {}) {
       for (const match of code.matchAll(classPattern)) {
         const classes = match[1].split(/\s+/).filter(Boolean);
         for (const cls of classes) {
-          state.classes.add(cls);
+          addSafelistClass(cls);
         }
       }
     }
@@ -2615,13 +2838,13 @@ function createCsszyxPlugins(options = {}) {
         const str = strMatch[1] || strMatch[2];
         const classes = str.split(/\s+/).filter(Boolean);
         for (const cls of classes) {
-          state.classes.add(cls);
+          addSafelistClass(cls);
         }
       }
     }
   }
   function finalizeMangleMap() {
-    const sortedClasses = Array.from(state.classes);
+    const sortedClasses = Array.from(state.ownedClasses);
     const newMap = {};
     for (let i = 0; i < sortedClasses.length; i++) {
       newMap[sortedClasses[i]] = encode(i);
@@ -2668,6 +2891,21 @@ function createCsszyxPlugins(options = {}) {
         }
         return null;
       },
+      /**
+       * Restricts the load hook to csszyx's own virtual modules.
+       *
+       * Without this, unplugin's webpack adapter registers its load
+       * loader with `type: 'javascript/auto'` for every module (its
+       * include defaults to all ids when no loadInclude exists). That
+       * corrupts binary asset modules (images, fonts) in webpack apps —
+       * Next.js builds fail with "not a valid image file" / "Module
+       * parse failed" on assets that build fine without csszyx.
+       * @param id - the module ID webpack is about to load
+       * @returns true only for csszyx virtual modules
+       */
+      loadInclude(id) {
+        return id === RESOLVED_VIRTUAL_MODULE_ID || id === RESOLVED_VIRTUAL_CHECKSUM_ID;
+      },
       /**
        * Loads virtual module content — generates mangle map or checksum module code.
        * @param id - the resolved module ID to load
@@ -2691,7 +2929,7 @@ function createCsszyxPlugins(options = {}) {
       },
       /**
        * Filters files for the pre-transform phase — source files plus CSS files.
-       * CSS files need special handling to inject @source inline() for Tailwind class discovery.
+       * CSS files need special handling to append an @source directive for Tailwind class discovery.
        * @param id - the file path to check for inclusion
        * @returns true if the file should be transformed, false otherwise
        */
@@ -2703,7 +2941,7 @@ function createCsszyxPlugins(options = {}) {
       },
       /**
        * Core transform: detects sz prop, compiles to className, injects runtime, collects classes.
-       * For CSS files: injects @source inline() so Tailwind generates CSS for sz-derived classes.
+       * For CSS files: appends an @source directive so Tailwind generates CSS for sz-derived classes.
        * @param code - the source code to transform
        * @param id - the file path of the module being transformed
        * @returns transformed code with source map, or null if no changes were made
@@ -2719,24 +2957,19 @@ function createCsszyxPlugins(options = {}) {
           assertNoRSCBoundaryViolation(code, id);
         }
         if (/\.css(\?.*)?$/.test(id)) {
-          const hasTailwindImport = code.includes('@import "tailwindcss') || code.includes("@import 'tailwindcss");
-          if (hasTailwindImport && state.classes.size > 0) {
-            const candidates = Array.from(state.classes).filter((c) => c.length >= 2 && /^[a-z]/.test(c)).join(" ");
-            if (candidates) {
-              const safelistPath = path.join(state.rootDir, SAFELIST_FILENAME).replace(/\\/g, "/");
-              const cssDir = path.dirname(id).replace(/\\/g, "/");
-              let relPath = path.posix.relative(cssDir, safelistPath);
-              if (!relPath.startsWith(".")) {
-                relPath = `./${relPath}`;
-              }
-              const sourceDirective = `@source "${relPath}";
-`;
-              const transformed2 = code.replace(
-                /(@import\s+["']tailwindcss[^"']*["'];)/,
-                `$1
-${sourceDirective}`
+          if (cssImportsTailwind(code)) {
+            state.sawTailwindEntry = true;
+            if (cssHasContentScope(code)) {
+              state.tailwindEntryScoped = true;
+            }
+            if (hasInjectableTailwindCandidate(state.classes)) {
+              const relPath = computeSafelistRelPath(
+                state.rootDir,
+                SAFELIST_FILENAME,
+                id
               );
-              if (transformed2 !== code) {
+              const transformed2 = appendTailwindSourceDirective(code, relPath);
+              if (transformed2 !== null) {
                 return { code: transformed2, map: null };
               }
             }
@@ -2779,8 +3012,15 @@ ${sourceDirective}`
             szClasses = result.classes;
             recordFileVarMangleEntries(state, id, cssVariableEntries(result));
             recordFileCSSVariableMetrics(state, id, result.code);
+            for (const msg of result.diagnostics) {
+              if (msg.includes("unresolvable sz spread")) {
+                state.spreadWarnings.add(`${id}
+  ${msg}`);
+              }
+            }
             if (result.diagnostics.length > 0 && process.env.NODE_ENV !== "production") {
               for (const msg of result.diagnostics) {
+                if (msg.includes("unresolvable sz spread")) continue;
                 this.warn(`[csszyx] ${id}
   ${msg}`);
               }
@@ -2848,7 +3088,8 @@ ${sourceDirective}`
         if (transformed || transformedCode.includes("class=") || transformedCode.includes("className=")) {
           if (szClasses !== void 0) {
             for (const cls of szClasses) {
-              state.classes.add(cls);
+              addSafelistClass(cls);
+              state.ownedClasses.add(cls);
             }
           } else {
             extractClasses(transformedCode);
@@ -2861,6 +3102,36 @@ ${sourceDirective}`
       buildEnd() {
         finalizeMangleMap();
         assertNoRSCGraphViolation(state.rscModules);
+        if (!state.tailwindWarningEmitted && shouldWarnMissingTailwindEntry(state.ownedClasses.size, state.sawTailwindEntry)) {
+          state.tailwindWarningEmitted = true;
+          console.warn(missingTailwindEntryMessage(state.ownedClasses.size));
+        }
+        if (!state.contentScopeWarningEmitted && options.contentScopeCheck !== false && state.sawTailwindEntry && !state.tailwindEntryScoped) {
+          if (state.inMonorepo === void 0) {
+            state.inMonorepo = isMonorepoPackage(state.rootDir);
+          }
+          if (shouldWarnUnscopedMonorepo(
+            state.sawTailwindEntry,
+            state.tailwindEntryScoped,
+            state.inMonorepo
+          )) {
+            state.contentScopeWarningEmitted = true;
+            console.warn(unscopedMonorepoMessage());
+          }
+        }
+        if (!state.skipWarningEmitted && state.skippedSzFiles.size > 0) {
+          state.skipWarningEmitted = true;
+          console.warn(skippedSzFilesMessage([...state.skippedSzFiles].sort()));
+        }
+        if (state.classesCapped) {
+          console.warn(
+            `[csszyx] safelist exceeded ${MAX_SAFELIST_CLASSES} classes; additional classes were dropped. This usually means an unbounded set of arbitrary values reached an sz prop.`
+          );
+        }
+        for (const warning of state.spreadWarnings) {
+          console.warn(`[csszyx] ${warning}`);
+        }
+        state.spreadWarnings.clear();
         if (manglingEnabled && Object.keys(state.mangleMap).length > 0) {
           globalThis.__csszyx_ssr_mangle_map = state.mangleMap;
         }
@@ -2960,7 +3231,8 @@ ${sourceDirective}`
           const sizeBefore = state.classes.size;
           recordGlobalVarSourceFile(state, ctx.file, fileContent);
           for (const cls of result.classes) {
-            state.classes.add(cls);
+            addSafelistClass(cls);
+            state.ownedClasses.add(cls);
           }
           recordFileVarMangleEntries(state, ctx.file, cssVariableEntries(result));
           recordFileCSSVariableMetrics(state, ctx.file, result.code);
@@ -3299,4 +3571,4 @@ const esbuildPlugin = (options = {}) => {
   };
 };
 
-export { rollupPlugin as A, scanGlobalVarCss as B, validateGlobalVarAliasInputs as C, vitePlugin as D, webpackPlugin as E, writeGlobalVarScanCache as F, assertNoRSCBoundaryViolation as a, assertNoRSCGraphViolation as b, createGlobalVarAliasValidationOptions as c, createGlobalVarMapAssetSource as d, createGlobalVarScanCacheKey as e, createRSCModuleRecord as f, deleteRSCModuleRecord as g, esbuildPlugin as h, extractGlobalVarAliasesForManifest as i, findRSCBoundaryViolation as j, findRSCGraphViolation as k, hasTokens as l, hasUseClientDirective as m, hasUseServerDirective as n, isRSCServerModule as o, isTailwindReservedGlobalVar as p, mangleCodeClassesSync as q, mergeThemes as r, normalizeGlobalVarAliasesForCache as s, parseThemeBlocks as t, unplugin as u, planGlobalVarAliases as v, readGlobalVarScanCache as w, resolveGlobalVarScanCacheDir as x, resolveNativeCacheIdentity as y, rewriteGlobalVarCssAliases as z };
+export { mangleCodeClassesSync as A, mergeThemes as B, missingTailwindEntryMessage as C, normalizeGlobalVarAliasesForCache as D, parseThemeBlocks as E, planGlobalVarAliases as F, readGlobalVarScanCache as G, resolveGlobalVarScanCacheDir as H, resolveNativeCacheIdentity as I, rewriteGlobalVarCssAliases as J, rollupPlugin as K, scanGlobalVarCss as L, shouldWarnMissingTailwindEntry as M, shouldWarnUnscopedMonorepo as N, skippedSzFilesMessage as O, unscopedMonorepoMessage as P, validateGlobalVarAliasInputs as Q, vitePlugin as R, webpackPlugin as S, writeGlobalVarScanCache as T, appendTailwindSourceDirective as a, assertNoRSCBoundaryViolation as b, assertNoRSCGraphViolation as c, computeSafelistRelPath as d, createGlobalVarAliasValidationOptions as e, createGlobalVarMapAssetSource as f, createGlobalVarScanCacheKey as g, createRSCModuleRecord as h, cssHasContentScope as i, cssImportsTailwind as j, deleteRSCModuleRecord as k, esbuildPlugin as l, extractGlobalVarAliasesForManifest as m, findRSCBoundaryViolation as n, findRSCGraphViolation as o, hasInjectableTailwindCandidate as p, hasTokens as q, hasUseClientDirective as r, hasUseServerDirective as s, isCompilePackageOptedIn as t, unplugin as u, isHardIgnoredPath as v, isMonorepoPackage as w, isPackagesSkippedSource as x, isRSCServerModule as y, isTailwindReservedGlobalVar as z };