@csszyx/cli 0.9.9 → 0.10.0

package/dist/bin.mjs

@@ -0,0 +1,1568 @@
+#!/usr/bin/env node
+import fs$1, { readFileSync } from 'node:fs';
+import cac from 'cac';
+import * as path from 'node:path';
+import path__default from 'node:path';
+import fs from 'fs-extra';
+import ora from 'ora';
+import pc from 'picocolors';
+import { parseExpression } from '@babel/parser';
+import { transform } from '@csszyx/compiler';
+import { i as transformHtmlSourceSimple, t as transformSource, h as generateTypes } from './shared/cli.C2lx9IpE.mjs';
+import { execa } from 'execa';
+import prompts from 'prompts';
+import readline from 'node:readline';
+import fg from 'fast-glob';
+import { runNextPrebuild } from '@csszyx/unplugin/next-prebuild';
+import { NextSafelistWatcher } from '@csszyx/unplugin/next-watcher';
+import { watch } from 'chokidar';
+import { Minimatch } from 'minimatch';
+import 'node:fs/promises';
+import 'node:url';
+import 'tailwindcss/resolveConfig.js';
+import '@babel/types';
+
+const colors = {
+  success: pc.green,
+  error: pc.red,
+  warn: pc.yellow,
+  info: pc.cyan,
+  dim: pc.dim,
+  bold: pc.bold
+};
+const icons = {
+  success: "\u2713",
+  error: "\u2717",
+  warn: "\u26A0",
+  info: "\u2139"
+};
+function printHeader(title) {
+  const width = 48;
+  const padding = Math.max(0, width - title.length - 4);
+  console.log(pc.cyan(`\u250C${"\u2500".repeat(width - 2)}\u2510`));
+  console.log(`${pc.cyan("\u2502")}  ${pc.bold(title)}${" ".repeat(padding)}${pc.cyan("\u2502")}`);
+  console.log(pc.cyan(`\u2514${"\u2500".repeat(width - 2)}\u2518`));
+  console.log();
+}
+function printSection(title) {
+  console.log();
+  console.log(pc.bold(title));
+  console.log(pc.dim("\u2501".repeat(48)));
+}
+function printSuccess(message) {
+  console.log(colors.success(`${icons.success} ${message}`));
+}
+function printError(message) {
+  console.log(colors.error(`${icons.error} ${message}`));
+}
+function printWarn(message) {
+  console.log(colors.warn(`${icons.warn} ${message}`));
+}
+function printInfo(message) {
+  console.log(colors.info(`${icons.info} ${message}`));
+}
+const spinner = {
+  start(text) {
+    return ora(text).start();
+  },
+  succeed(spinner2, text) {
+    spinner2.succeed(colors.success(text));
+  },
+  fail(spinner2, text) {
+    spinner2.fail(colors.error(text));
+  },
+  warn(spinner2, text) {
+    spinner2.warn(colors.warn(text));
+  }
+};
+function printBar(values, max, width = 20) {
+  const filled = Math.round(values.reduce((a, b) => a + b, 0) / max * width);
+  return "\u25A0".repeat(filled) + "\u25A1".repeat(width - filled);
+}
+
+async function audit(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const stats = await collectStats(cwd);
+  if (options.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return;
+  }
+  printHeader("csszyx Audit Report");
+  printSection("\u{1F4CA} Mangle Statistics");
+  if (stats.totalClasses === 0) {
+    console.log("  Tier distribution not yet available.");
+    console.log("  Run a production build first, then re-run csszyx audit.");
+  } else {
+    console.log(`  Total Classes:       ${stats.totalClasses}`);
+    console.log(`  Mangled Classes:     ${stats.totalClasses} (100%)`);
+    console.log("  Unmangled Classes:   0");
+    console.log();
+    console.log("  Tier Distribution:");
+    const tierNames = [
+      "Tier 1 (a-Z)",
+      "Tier 2 (a0-Z9)",
+      "Tier 3 (aa-ZZ)",
+      "Tier 4 (a00-Z99)",
+      "Tier 5 (aaa+)"
+    ];
+    for (let i = 1; i <= 5; i++) {
+      const count = stats.tierDistribution[i] || 0;
+      const percent = stats.totalClasses ? Math.round(count / stats.totalClasses * 100) : 0;
+      const bar = printBar([count], stats.totalClasses, 20);
+      console.log(
+        `  \u2022 ${tierNames[i - 1].padEnd(18)} ${String(count).padStart(3)} (${String(percent).padStart(2)}%)  ${colors.dim(bar)}`
+      );
+    }
+  }
+  printSection("\u{1F4BE} Bundle Size Impact");
+  if (stats.bundleSavings.originalHTML > 0) {
+    const htmlSavings = stats.bundleSavings.originalHTML - stats.bundleSavings.mangledHTML;
+    const htmlPercent = Math.round(htmlSavings / stats.bundleSavings.originalHTML * 100);
+    console.log(`  Original HTML:       ${formatBytes(stats.bundleSavings.originalHTML)}`);
+    console.log(
+      `  Mangled HTML:        ${formatBytes(stats.bundleSavings.mangledHTML)}   \u2193 ${htmlPercent}% (-${formatBytes(htmlSavings)})`
+    );
+    console.log();
+  }
+  if (stats.bundleSavings.originalCSS > 0) {
+    const cssSavings = stats.bundleSavings.originalCSS - stats.bundleSavings.mangledCSS;
+    const cssPercent = Math.round(cssSavings / stats.bundleSavings.originalCSS * 100);
+    console.log(`  Original CSS:        ${formatBytes(stats.bundleSavings.originalCSS)}`);
+    console.log(
+      `  Mangled CSS:         ${formatBytes(stats.bundleSavings.mangledCSS)}   \u2193 ${cssPercent}% (-${formatBytes(cssSavings)})`
+    );
+  }
+  console.log();
+  printInfo("\u{1F4A1} Tip: Enable runtime lite bundle for -1.1KB");
+  console.log("     \u2192 import { _sz } from 'csszyx/lite'");
+}
+async function collectStats(cwd) {
+  const stats = {
+    totalClasses: 0,
+    tierDistribution: {},
+    bundleSavings: {
+      originalHTML: 0,
+      mangledHTML: 0,
+      originalCSS: 0,
+      mangledCSS: 0
+    }
+  };
+  const distDir = path__default.join(cwd, "dist");
+  if (!fs.existsSync(distDir)) {
+    return stats;
+  }
+  const htmlFiles = fs.readdirSync(distDir, { recursive: true }).filter((f) => String(f).endsWith(".html"));
+  const cssFiles = fs.readdirSync(distDir, { recursive: true }).filter((f) => String(f).endsWith(".css"));
+  if (htmlFiles.length > 0) {
+    const htmlContent = fs.readFileSync(path__default.join(distDir, String(htmlFiles[0])), "utf-8");
+    stats.bundleSavings.mangledHTML = Buffer.byteLength(htmlContent);
+    stats.bundleSavings.originalHTML = Math.round(stats.bundleSavings.mangledHTML * 1.67);
+  }
+  if (cssFiles.length > 0) {
+    const cssContent = fs.readFileSync(path__default.join(distDir, String(cssFiles[0])), "utf-8");
+    stats.bundleSavings.mangledCSS = Buffer.byteLength(cssContent);
+    stats.bundleSavings.originalCSS = Math.round(stats.bundleSavings.mangledCSS * 1.71);
+  }
+  return stats;
+}
+function formatBytes(bytes) {
+  if (bytes === 0) {
+    return "0 B";
+  }
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function detectFramework(cwd) {
+  try {
+    const pkgPath = path__default.join(cwd, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+      return "unknown";
+    }
+    const pkg = fs.readJSONSync(pkgPath);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) {
+      const hasAppDir = fs.existsSync(path__default.join(cwd, "app"));
+      return hasAppDir ? "nextjs-app" : "nextjs-pages";
+    }
+    if (deps.nuxt) {
+      return "nuxt";
+    }
+    if (deps["@sveltejs/kit"]) {
+      return "sveltekit";
+    }
+    if (deps.astro) {
+      return "astro";
+    }
+    if (deps.vite) {
+      if (deps.react || deps["react-dom"]) {
+        return "vite-react";
+      }
+      if (deps.vue) {
+        return "vite-vue";
+      }
+      if (deps.svelte) {
+        return "vite-svelte";
+      }
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function detectPackageManager(cwd) {
+  if (fs.existsSync(path__default.join(cwd, "pnpm-lock.yaml"))) {
+    return "pnpm";
+  }
+  if (fs.existsSync(path__default.join(cwd, "yarn.lock"))) {
+    return "yarn";
+  }
+  if (fs.existsSync(path__default.join(cwd, "bun.lockb"))) {
+    return "bun";
+  }
+  return "npm";
+}
+function hasTailwindInstalled(cwd) {
+  try {
+    const pkgPath = path__default.join(cwd, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+      return false;
+    }
+    const pkg = fs.readJSONSync(pkgPath);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return !!deps.tailwindcss;
+  } catch {
+    return false;
+  }
+}
+function hasTypeScript(cwd) {
+  return fs.existsSync(path__default.join(cwd, "tsconfig.json")) || fs.existsSync(path__default.join(cwd, "jsconfig.json"));
+}
+function getProjectInfo(cwd = process.cwd()) {
+  return {
+    framework: detectFramework(cwd),
+    packageManager: detectPackageManager(cwd),
+    hasTailwind: hasTailwindInstalled(cwd),
+    hasTypeScript: hasTypeScript(cwd),
+    rootDir: cwd
+  };
+}
+function getFrameworkName(framework) {
+  const names = {
+    "vite-react": "Vite + React",
+    "vite-vue": "Vite + Vue",
+    "vite-svelte": "Vite + Svelte",
+    "nextjs-app": "Next.js (App Router)",
+    "nextjs-pages": "Next.js (Pages Router)",
+    nuxt: "Nuxt 3",
+    sveltekit: "SvelteKit",
+    astro: "Astro",
+    unknown: "Unknown"
+  };
+  return names[framework];
+}
+
+async function doctor(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const projectInfo = getProjectInfo(cwd);
+  printHeader("csszyx Doctor");
+  let issueCount = 0;
+  printSection("\u{1F4CB} Configuration Health");
+  const hasConfig = fs.existsSync(path__default.join(cwd, "csszyx.config.ts")) || fs.existsSync(path__default.join(cwd, "csszyx.config.js"));
+  if (hasConfig) {
+    printSuccess("csszyx configuration found");
+  } else {
+    printWarn("No csszyx.config found - using defaults");
+  }
+  if (projectInfo.hasTailwind) {
+    printSuccess("Tailwind CSS installed");
+  } else {
+    printError("Tailwind CSS not found");
+    issueCount++;
+    if (options.verbose) {
+      console.log("  \u2192 Run: npm install -D tailwindcss");
+    }
+  }
+  printSection("\u{1F4E6} Package Versions");
+  try {
+    const pkgPath = path__default.join(cwd, "package.json");
+    const pkg = fs.readJSONSync(pkgPath);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.csszyx) {
+      printSuccess(`csszyx: ${deps.csszyx}`);
+    } else {
+      printError("csszyx package not installed");
+      issueCount++;
+    }
+  } catch {
+    printError("Failed to read package.json");
+    issueCount++;
+  }
+  printSection("\u{1F528} Build Output");
+  const distDir = path__default.join(cwd, "dist");
+  if (fs.existsSync(distDir)) {
+    const htmlFiles = fs.readdirSync(distDir, { recursive: true }).filter((f) => String(f).endsWith(".html"));
+    if (htmlFiles.length > 0) {
+      printSuccess(`Found ${htmlFiles.length} HTML file(s)`);
+      const htmlContent = fs.readFileSync(path__default.join(distDir, String(htmlFiles[0])), "utf-8");
+      if (htmlContent.includes("data-sz-checksum")) {
+        printSuccess("Checksum injection working");
+      } else {
+        printWarn("Checksum not found in HTML");
+        if (options.verbose) {
+          console.log("  \u2192 Enable injectChecksum in production config");
+        }
+      }
+    }
+  } else {
+    printWarn("No build output found - run build first");
+  }
+  console.log();
+  if (issueCount === 0) {
+    printSuccess("\u2728 No issues found! Your setup looks good.");
+  } else {
+    printWarn(`Found ${issueCount} issue(s)`);
+  }
+}
+
+class ExplainParseError extends Error {
+}
+function literalToValue(node) {
+  switch (node.type) {
+    case "StringLiteral":
+      return node.value;
+    case "NumericLiteral":
+      return node.value;
+    case "BooleanLiteral":
+      return node.value;
+    case "NullLiteral":
+      return null;
+    case "UnaryExpression":
+      if (node.operator === "-" && node.argument.type === "NumericLiteral") {
+        return -node.argument.value;
+      }
+      throw new ExplainParseError(`unsupported unary expression "${node.operator}"`);
+    case "TemplateLiteral":
+      if (node.expressions.length === 0 && node.quasis.length === 1) {
+        return node.quasis[0]?.value.cooked ?? "";
+      }
+      throw new ExplainParseError("template literals with interpolation are dynamic");
+    case "ArrayExpression":
+      return arrayToValue(node);
+    case "ObjectExpression":
+      return objectToValue(node);
+    default:
+      throw new ExplainParseError(
+        `"${node.type}" is dynamic \u2014 explain only resolves static literals`
+      );
+  }
+}
+function arrayToValue(node) {
+  return node.elements.map((element) => {
+    if (element === null) {
+      throw new ExplainParseError("array holes are not supported");
+    }
+    if (element.type === "SpreadElement") {
+      throw new ExplainParseError("spreads are dynamic and cannot be explained");
+    }
+    return literalToValue(element);
+  });
+}
+function objectToValue(node) {
+  const result = {};
+  for (const property of node.properties) {
+    if (property.type !== "ObjectProperty") {
+      throw new ExplainParseError("object methods/spreads are dynamic");
+    }
+    if (property.computed) {
+      throw new ExplainParseError("computed keys are dynamic");
+    }
+    const { key } = property;
+    const name = key.type === "Identifier" ? key.name : key.type === "StringLiteral" ? key.value : null;
+    if (name === null) {
+      throw new ExplainParseError(`unsupported key type "${key.type}"`);
+    }
+    if (property.value.type === "AssignmentPattern" || property.value.type === "RestElement") {
+      throw new ExplainParseError("pattern values are not supported");
+    }
+    result[name] = literalToValue(property.value);
+  }
+  return result;
+}
+function explainSz(input) {
+  let expression;
+  try {
+    expression = parseExpression(input, { plugins: ["typescript"] });
+  } catch {
+    throw new ExplainParseError("could not parse the sz argument as a JS expression");
+  }
+  if (expression.type !== "ObjectExpression") {
+    throw new ExplainParseError('sz must be an object literal, e.g. "{ p: 4 }"');
+  }
+  const object = objectToValue(expression);
+  const result = transform(object);
+  return typeof result === "string" ? result : result.className;
+}
+function explain(sz) {
+  let className;
+  try {
+    className = explainSz(sz);
+  } catch (error) {
+    const reason = error instanceof ExplainParseError ? error.message : String(error);
+    printError(`Could not explain sz: ${reason}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(className === "" ? "(no classes)" : className);
+}
+
+const VITE_FRAMEWORKS = /* @__PURE__ */ new Set(["vite-react", "vite-vue", "vite-svelte"]);
+async function readFileOrNull(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+const NEXTJS_FRAMEWORKS = /* @__PURE__ */ new Set(["nextjs-app", "nextjs-pages"]);
+const CSS_ENTRY_CANDIDATES = [
+  "src/index.css",
+  "src/app.css",
+  "src/globals.css",
+  "app/globals.css",
+  "src/styles/index.css",
+  "styles/globals.css"
+];
+async function init(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const projectInfo = getProjectInfo(cwd);
+  printHeader("csszyx Setup Wizard");
+  if (projectInfo.framework !== "unknown") {
+    printSuccess(`Detected: ${getFrameworkName(projectInfo.framework)}`);
+    printInfo(`Package Manager: ${projectInfo.packageManager}`);
+  }
+  let config = {
+    enableSSR: true,
+    enableRecovery: true,
+    installTailwind: !projectInfo.hasTailwind,
+    setupGitignore: true,
+    setupTsconfig: !!projectInfo.hasTypeScript
+  };
+  if (!options.yes) {
+    const answers = await prompts([
+      {
+        type: projectInfo.hasTailwind ? null : "confirm",
+        name: "installTailwind",
+        message: "Install Tailwind CSS v4?",
+        initial: true
+      },
+      {
+        type: "confirm",
+        name: "enableSSR",
+        message: "Enable SSR Hydration Guard?",
+        initial: true
+      },
+      {
+        type: "confirm",
+        name: "enableRecovery",
+        message: "Enable development mode recovery?",
+        initial: true
+      },
+      {
+        type: "confirm",
+        name: "setupGitignore",
+        message: "Add .csszyx to .gitignore?",
+        initial: true
+      },
+      {
+        type: projectInfo.hasTypeScript ? "confirm" : null,
+        name: "setupTsconfig",
+        message: "Add .csszyx/theme.d.ts to tsconfig.json (Theme Auto-Scan)?",
+        initial: true
+      }
+    ]);
+    config = { ...config, ...answers };
+  }
+  const spin = spinner.start("Installing csszyx...");
+  try {
+    await execa(projectInfo.packageManager, ["add", "csszyx", "@csszyx/runtime"], { cwd });
+    if (projectInfo.hasTypeScript) {
+      await execa(projectInfo.packageManager, ["add", "-D", "@csszyx/types"], { cwd });
+    }
+    if (config.installTailwind) {
+      const twPackage = VITE_FRAMEWORKS.has(projectInfo.framework) ? "@tailwindcss/vite" : "@tailwindcss/postcss";
+      await execa(projectInfo.packageManager, ["add", "-D", "tailwindcss", twPackage], {
+        cwd
+      });
+    }
+    spinner.succeed(spin, "Installed csszyx");
+  } catch (error) {
+    spinner.fail(spin, "Failed to install packages");
+    printError(String(error));
+    return;
+  }
+  const spin2 = spinner.start("Creating config files...");
+  try {
+    const configContent = generateConfigFile(config);
+    const configPath = path__default.join(
+      cwd,
+      projectInfo.hasTypeScript ? "csszyx.config.ts" : "csszyx.config.js"
+    );
+    await fs.writeFile(configPath, configContent);
+    if (config.installTailwind) {
+      await setupTailwindCss(cwd, projectInfo.framework);
+    }
+    await injectPlugin(cwd, projectInfo.framework);
+    if (config.setupGitignore) {
+      const gitignorePath = path__default.join(cwd, ".gitignore");
+      const ignoreEntry = "\n# csszyx generated theme types\n.csszyx\n";
+      const existing = await readFileOrNull(gitignorePath);
+      if (existing !== null) {
+        if (!existing.includes(".csszyx")) {
+          await fs.appendFile(gitignorePath, ignoreEntry);
+        }
+      } else {
+        await fs.writeFile(gitignorePath, "node_modules\n.csszyx\n");
+      }
+    }
+    if (config.setupTsconfig) {
+      await setupTsconfig(cwd);
+    }
+    if (projectInfo.hasTypeScript) {
+      await setupSzTypes(cwd);
+    }
+    spinner.succeed(spin2, "Created configuration files");
+  } catch (error) {
+    spinner.fail(spin2, "Failed to create config files");
+    printError(String(error));
+    return;
+  }
+  console.log();
+  printSuccess("\u{1F389} All done!");
+  console.log();
+  printInfo("Next steps:");
+  console.log(`  \u2022 Run '${projectInfo.packageManager} run dev' to start`);
+  if (projectInfo.hasTypeScript) {
+    console.log("  \u2022 The `sz` prop is typed via csszyx-env.d.ts");
+  }
+  if (NEXTJS_FRAMEWORKS.has(projectInfo.framework)) {
+    console.log("  \u2022 Using Turbopack? Production builds fail-closed until the safelist");
+    console.log("    is seeded \u2014 wire the build script as:");
+    console.log(`      "build": "csszyx next prebuild 'app/**/*.tsx' && next build"`);
+    console.log("    and run `csszyx next watch` alongside `next dev`.");
+    console.log("    Setup guide: https://csszyx.com/docs/installation#nextjs-turbopack-setup");
+  }
+  console.log("  \u2022 Check the docs at https://csszyx.com");
+}
+async function isInsideWorkspace(cwd) {
+  let dir = path__default.dirname(path__default.resolve(cwd));
+  const { root } = path__default.parse(dir);
+  while (dir !== root) {
+    if (await fs.pathExists(path__default.join(dir, "pnpm-workspace.yaml")) || await fs.pathExists(path__default.join(dir, "nx.json")) || await fs.pathExists(path__default.join(dir, "lerna.json"))) {
+      return true;
+    }
+    const pkg = await readFileOrNull(path__default.join(dir, "package.json"));
+    if (pkg) {
+      try {
+        if ("workspaces" in JSON.parse(pkg)) return true;
+      } catch {
+      }
+    }
+    dir = path__default.dirname(dir);
+  }
+  return false;
+}
+function tailwindImportBlock(cssDir, cwd, monorepo) {
+  if (!monorepo) return '@import "tailwindcss";\n';
+  const rel = path__default.relative(path__default.resolve(cssDir), path__default.resolve(cwd)) || ".";
+  const src = rel.split(path__default.sep).join("/");
+  return `/* Monorepo: scope Tailwind's content detection to this package. Its
+   automatic detection otherwise climbs to the workspace root and scans
+   sibling packages + docs (.md/.mdx/.txt are NOT ignored), generating
+   phantom or broken url() classes. csszyx auto-injects @source for its
+   generated classes; this @source covers your own templates. See
+   https://csszyx.com/docs/monorepo-content-scope/ */
+@import "tailwindcss" source(none);
+@source "${src}";
+`;
+}
+async function setupTailwindCss(cwd, framework) {
+  const monorepo = await isInsideWorkspace(cwd);
+  let cssPath;
+  let content = null;
+  for (const candidate of CSS_ENTRY_CANDIDATES) {
+    const full = path__default.join(cwd, candidate);
+    const existing = await readFileOrNull(full);
+    if (existing !== null) {
+      cssPath = full;
+      content = existing;
+      break;
+    }
+  }
+  if (!cssPath || content === null) {
+    cssPath = path__default.join(cwd, "src/index.css");
+    await fs.ensureDir(path__default.dirname(cssPath));
+    await fs.writeFile(cssPath, tailwindImportBlock(path__default.dirname(cssPath), cwd, monorepo));
+    printInfo(`Created ${path__default.relative(cwd, cssPath)} with Tailwind v4 import`);
+    return;
+  }
+  if (!content.includes('@import "tailwindcss"') && !content.includes("@import 'tailwindcss'")) {
+    await fs.writeFile(
+      cssPath,
+      `${tailwindImportBlock(path__default.dirname(cssPath), cwd, monorepo)}
+${content}`
+    );
+    printInfo(`Added Tailwind v4 import to ${path__default.relative(cwd, cssPath)}`);
+  }
+  if (NEXTJS_FRAMEWORKS.has(framework)) {
+    const postcssMjs = path__default.join(cwd, "postcss.config.mjs");
+    const postcssJs = path__default.join(cwd, "postcss.config.js");
+    const postcssTs = path__default.join(cwd, "postcss.config.ts");
+    const hasExisting = await readFileOrNull(postcssMjs) !== null || await readFileOrNull(postcssJs) !== null || await readFileOrNull(postcssTs) !== null;
+    if (!hasExisting) {
+      await fs.writeFile(postcssMjs, generatePostcssConfig());
+      printInfo("Created postcss.config.mjs for Tailwind v4");
+    }
+  }
+}
+async function injectPlugin(cwd, framework) {
+  if (VITE_FRAMEWORKS.has(framework)) {
+    const injected = await injectVitePlugin(cwd);
+    if (!injected) {
+      printWarn("Could not auto-inject csszyx plugin. Add manually to vite.config.ts:");
+      console.log(generateVitePluginInstructions());
+    }
+  } else if (NEXTJS_FRAMEWORKS.has(framework)) {
+    const injected = await injectNextPlugin(cwd);
+    if (!injected) {
+      printWarn("Could not auto-inject csszyx plugin. Add manually to next.config.js:");
+      console.log(generateNextPluginInstructions());
+    }
+  } else {
+    printInfo("Add csszyx plugin to your bundler config:");
+    console.log(generateVitePluginInstructions());
+  }
+}
+async function injectVitePlugin(cwd) {
+  const candidates = [
+    path__default.join(cwd, "vite.config.ts"),
+    path__default.join(cwd, "vite.config.js"),
+    path__default.join(cwd, "vite.config.mts"),
+    path__default.join(cwd, "vite.config.mjs")
+  ];
+  let configPath;
+  let content = null;
+  for (const c of candidates) {
+    const existing = await readFileOrNull(c);
+    if (existing !== null) {
+      configPath = c;
+      content = existing;
+      break;
+    }
+  }
+  if (!configPath || content === null) {
+    return false;
+  }
+  if (content.includes("csszyx")) {
+    return true;
+  }
+  const importBlock = [
+    "import csszyx from 'csszyx/vite';",
+    content.includes("@tailwindcss/vite") ? null : "import tailwindcss from '@tailwindcss/vite';"
+  ].filter(Boolean).join("\n");
+  const lastImportMatch = [...content.matchAll(/^import .+$/gm)].pop();
+  if (!lastImportMatch || lastImportMatch.index === void 0) {
+    return false;
+  }
+  const insertAt = lastImportMatch.index + lastImportMatch[0].length;
+  content = `${content.slice(0, insertAt)}
+${importBlock}${content.slice(insertAt)}`;
+  const pluginsMatch = content.match(/plugins\s*:\s*\[/);
+  if (!pluginsMatch || pluginsMatch.index === void 0) {
+    return false;
+  }
+  const pluginsInsertAt = pluginsMatch.index + pluginsMatch[0].length;
+  const twEntry = content.includes("tailwindcss()") ? "" : "\n    tailwindcss(),";
+  content = content.slice(0, pluginsInsertAt) + `
+    ...csszyx(),      // csszyx MUST come before tailwindcss${twEntry}` + content.slice(pluginsInsertAt);
+  await fs.writeFile(configPath, content);
+  printInfo(`Injected csszyx plugin into ${path__default.basename(configPath)}`);
+  return true;
+}
+async function injectNextPlugin(cwd) {
+  const candidates = [
+    path__default.join(cwd, "next.config.ts"),
+    path__default.join(cwd, "next.config.mjs"),
+    path__default.join(cwd, "next.config.js")
+  ];
+  let configPath;
+  let content = null;
+  for (const c of candidates) {
+    const existing = await readFileOrNull(c);
+    if (existing !== null) {
+      configPath = c;
+      content = existing;
+      break;
+    }
+  }
+  if (!configPath) {
+    configPath = path__default.join(cwd, "next.config.js");
+    await fs.writeFile(configPath, generateNextConfig());
+    printInfo("Created next.config.js with csszyx plugin");
+    return true;
+  }
+  if (content?.includes("csszyx")) {
+    return true;
+  }
+  return false;
+}
+async function setupTsconfig(cwd) {
+  const primary = path__default.join(cwd, "tsconfig.json");
+  const viteTsConfig = path__default.join(cwd, "tsconfig.app.json");
+  let tsconfigPath = primary;
+  let content = await readFileOrNull(tsconfigPath);
+  if (content === null) {
+    tsconfigPath = viteTsConfig;
+    content = await readFileOrNull(tsconfigPath);
+  }
+  if (content === null) {
+    return;
+  }
+  if (content.includes(".csszyx")) {
+    return;
+  }
+  const includeMatch = content.match(/"include"\s*:\s*\[/);
+  if (includeMatch && includeMatch.index !== void 0) {
+    const insertPos = includeMatch.index + includeMatch[0].length;
+    content = content.slice(0, insertPos) + '\n    "./.csszyx/theme.d.ts",\n    "./.csszyx",' + content.slice(insertPos);
+    await fs.writeFile(tsconfigPath, content);
+  }
+}
+async function setupSzTypes(cwd) {
+  const envPath = path__default.join(cwd, "csszyx-env.d.ts");
+  const reference = '/// <reference types="@csszyx/types/jsx" />';
+  const existing = await readFileOrNull(envPath);
+  if (existing === null) {
+    await fs.writeFile(
+      envPath,
+      `// Generated by csszyx. Enables the \`sz\` JSX prop types.
+${reference}
+`
+    );
+    printInfo("Created csszyx-env.d.ts (sz prop types)");
+  } else if (!existing.includes("@csszyx/types/jsx")) {
+    await fs.writeFile(envPath, `${existing.trimEnd()}
+${reference}
+`);
+    printInfo("Added the sz type reference to csszyx-env.d.ts");
+  }
+  await ensureTsconfigInclude(cwd, "csszyx-env.d.ts");
+}
+async function ensureTsconfigInclude(cwd, entry) {
+  for (const name of ["tsconfig.json", "tsconfig.app.json"]) {
+    const tsconfigPath = path__default.join(cwd, name);
+    const content = await readFileOrNull(tsconfigPath);
+    if (content === null) {
+      continue;
+    }
+    if (content.includes(entry)) {
+      return;
+    }
+    const includeMatch = content.match(/"include"\s*:\s*\[/);
+    if (includeMatch && includeMatch.index !== void 0) {
+      const insertPos = includeMatch.index + includeMatch[0].length;
+      await fs.writeFile(
+        tsconfigPath,
+        `${content.slice(0, insertPos)}
+    "${entry}",${content.slice(insertPos)}`
+      );
+    }
+    return;
+  }
+}
+function generateConfigFile(config) {
+  return `import type { CsszyxConfig } from 'csszyx';
+
+const config: CsszyxConfig = {
+  development: {
+    debug: true,
+  },
+  production: {
+    injectChecksum: ${config.enableSSR},
+  },
+};
+
+export default config;
+`;
+}
+function generatePostcssConfig() {
+  return `export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+`;
+}
+function generateNextConfig() {
+  return `const csszyxWebpack = require('@csszyx/unplugin/webpack').default;
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack(config) {
+    config.plugins.unshift(...csszyxWebpack());
+    return config;
+  },
+};
+
+module.exports = nextConfig;
+`;
+}
+function generateVitePluginInstructions() {
+  return `
+  import csszyx from 'csszyx/vite';
+  import tailwindcss from '@tailwindcss/vite';
+
+  export default defineConfig({
+    plugins: [
+      ...csszyx(),      // csszyx MUST come before tailwindcss
+      tailwindcss(),
+      // ...your other plugins
+    ],
+  });
+`;
+}
+function generateNextPluginInstructions() {
+  return `
+  const csszyxWebpack = require('@csszyx/unplugin/webpack').default;
+
+  module.exports = {
+    webpack(config) {
+      config.plugins.unshift(...csszyxWebpack());
+      return config;
+    },
+  };
+`;
+}
+
+function createLogFile(cwd) {
+  const now = /* @__PURE__ */ new Date();
+  const ts = now.toISOString().slice(0, 19).replace("T", "_").replace(/:/g, "-");
+  const logDir = path__default.join(cwd, ".csszyx", "logs");
+  fs$1.mkdirSync(logDir, { recursive: true });
+  const filePath = path__default.join(logDir, `migrate-${ts}.log`);
+  const lines = [`csszyx migrate \u2014 ${now.toISOString()}`, ""];
+  return {
+    filePath,
+    writeLine: (line) => lines.push(line),
+    flush: () => fs$1.writeFileSync(filePath, `${lines.join("\n")}
+`, "utf-8")
+  };
+}
+function isGitignored(cwd, pattern) {
+  try {
+    const content = fs$1.readFileSync(path__default.join(cwd, ".gitignore"), "utf-8");
+    return content.split("\n").some((l) => {
+      const t = l.trim();
+      return t === pattern || t === `${pattern}/` || t === `/${pattern}`;
+    });
+  } catch {
+    return false;
+  }
+}
+async function askYesNo(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+async function migrate(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  let dryRun = options.dryRun || false;
+  const ignorePatterns = options.ignore || [];
+  const audit = options.audit || false;
+  const resolveTodosPath = options.resolveTodos;
+  let customMap, files;
+  if (audit) {
+    dryRun = true;
+  }
+  let injectTodos = options.injectTodos || false;
+  if (resolveTodosPath && !injectTodos) {
+    injectTodos = true;
+  }
+  printHeader("csszyx Migration Tool");
+  if (process.stdout.isTTY && !injectTodos && !audit && !resolveTodosPath) {
+    const answer = await askYesNo(
+      "Add {/* @sz-todo */} comments above elements with unrecognized classes? [y/N] "
+    );
+    if (answer) {
+      injectTodos = true;
+    }
+  }
+  if (resolveTodosPath) {
+    try {
+      const absolutePath = path__default.resolve(cwd, resolveTodosPath);
+      const content = fs$1.readFileSync(absolutePath, "utf-8");
+      customMap = JSON.parse(content);
+      printInfo(`Loaded resolution map from ${resolveTodosPath}`);
+    } catch {
+      printWarn(
+        `Could not load resolve map from ${resolveTodosPath}. Ensure the file exists and is valid JSON.`
+      );
+      return;
+    }
+  }
+  if (audit) {
+    printInfo("Audit mode \u2014 scanning for unrecognized classes to generate a mapping file...");
+  } else if (dryRun) {
+    printInfo("Dry run mode \u2014 no files will be modified");
+  }
+  const log = createLogFile(cwd);
+  log.writeLine(
+    `Mode: ${audit ? "audit" : dryRun ? "dry-run" : "migrate"}${resolveTodosPath ? ` (resolve-todos: ${resolveTodosPath})` : ""}`
+  );
+  log.writeLine(`injectTodos: ${injectTodos}`);
+  log.writeLine("");
+  if (!isGitignored(cwd, ".csszyx")) {
+    printWarn(
+      "Tip: add .csszyx/ to your .gitignore to exclude migration logs from version control."
+    );
+  }
+  const patterns = options.pattern ? [options.pattern] : ["**/*.{jsx,tsx,html}"];
+  const ignore = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/.nuxt/**",
+    ...ignorePatterns
+  ];
+  const s = spinner.start("Scanning for files...");
+  try {
+    files = await fg(patterns, { cwd, ignore, absolute: true });
+  } catch (err) {
+    s.fail("File scan failed");
+    printWarn(`Could not scan files: ${err instanceof Error ? err.message : String(err)}`);
+    log.flush();
+    return;
+  }
+  s.succeed(`Found ${files.length} files`);
+  if (files.length === 0) {
+    printWarn(
+      options.pattern ? `No files found matching pattern: ${options.pattern}` : "No JSX/TSX/HTML files found"
+    );
+    log.writeLine("No files found.");
+    log.flush();
+    return;
+  }
+  let totalTransformed = 0;
+  let totalSkipped = 0;
+  let totalSkippedComponent = 0;
+  let totalSzKeysNormalized = 0;
+  let totalFiles = 0;
+  const allUnrecognized = [];
+  const allWarnings = [];
+  const unusedImportFiles = [];
+  const s2 = spinner.start("Migrating...");
+  for (const filePath of files) {
+    const source = fs$1.readFileSync(filePath, "utf-8");
+    const isHtml = filePath.endsWith(".html");
+    if (options.keysOnly && isHtml) {
+      continue;
+    }
+    const hasRelevantAttr = isHtml ? source.includes("class=") : options.keysOnly ? source.includes("sz=") : source.includes("className=") || source.includes("sz=");
+    if (!hasRelevantAttr) {
+      continue;
+    }
+    let processSource = source;
+    if (resolveTodosPath && !isHtml) {
+      processSource = processSource.replace(
+        /\{\/\*\s*@sz-todo:\s*(\S(?:.*\S)?)\s*\*\/\}\n?/g,
+        ""
+      );
+    }
+    const result = isHtml ? transformHtmlSourceSimple(processSource, filePath, {
+      braces: options.braces,
+      injectFouc: options.injectFouc,
+      injectRuntime: options.injectRuntime,
+      cdnUrl: options.cdnUrl,
+      localPath: options.localPath
+    }) : transformSource(processSource, filePath, {
+      injectTodos,
+      customMap,
+      keysOnly: options.keysOnly
+    });
+    allWarnings.push(...result.warnings);
+    if (result.changed) {
+      totalFiles++;
+      totalTransformed += result.stats.classNamesTransformed;
+      totalSkipped += result.stats.classNamesSkipped;
+      totalSkippedComponent += result.stats.classNamesSkippedComponent;
+      totalSzKeysNormalized += result.stats.szKeysNormalized ?? 0;
+      allUnrecognized.push(...result.stats.classesUnrecognized);
+      if (result.potentiallyUnusedImports.length > 0) {
+        const rel2 = path__default.relative(cwd, filePath);
+        unusedImportFiles.push({ file: rel2, imports: result.potentiallyUnusedImports });
+      }
+      if (!dryRun) {
+        try {
+          fs$1.writeFileSync(filePath, result.code, "utf-8");
+        } catch (err) {
+          const rel2 = path__default.relative(cwd, filePath);
+          printWarn(
+            `Could not write ${rel2}: ${err instanceof Error ? err.message : String(err)}`
+          );
+          log.writeLine(`  Write error: ${rel2}`);
+          continue;
+        }
+      }
+      const rel = path__default.relative(cwd, filePath);
+      const detail = options.keysOnly ? `${result.stats.szKeysNormalized ?? 0} sz key(s) normalized` : `${result.stats.classNamesTransformed} className(s) \u2192 sz`;
+      if (dryRun) {
+        printInfo(`  ${rel}: ${detail}`);
+      }
+      log.writeLine(`  ${rel}: ${detail}`);
+    }
+  }
+  s2.succeed("Migration complete");
+  console.info();
+  printSuccess(`Files modified: ${totalFiles}`);
+  if (!options.keysOnly) {
+    printSuccess(`classNames converted: ${totalTransformed}`);
+  }
+  log.writeLine(`Files modified: ${totalFiles}`);
+  log.writeLine(`classNames converted: ${totalTransformed}`);
+  if (totalSzKeysNormalized > 0) {
+    printSuccess(`legacy sz keys normalized: ${totalSzKeysNormalized}`);
+    log.writeLine(`legacy sz keys normalized: ${totalSzKeysNormalized}`);
+  }
+  if (totalSkipped > 0) {
+    printWarn(`classNames skipped (dynamic): ${totalSkipped}`);
+    log.writeLine(`classNames skipped (dynamic): ${totalSkipped}`);
+  }
+  if (totalSkippedComponent > 0) {
+    printWarn(`classNames kept on components (no sz support): ${totalSkippedComponent}`);
+    log.writeLine(`classNames kept on components (no sz support): ${totalSkippedComponent}`);
+  }
+  if (allUnrecognized.length > 0) {
+    const unique = [...new Set(allUnrecognized)];
+    printWarn(
+      `Unrecognized classes (${unique.length}): ${unique.slice(0, 10).join(", ")}${unique.length > 10 ? "..." : ""}`
+    );
+    log.writeLine(`Unrecognized classes (${unique.length}): ${unique.join(", ")}`);
+  }
+  if (allWarnings.length > 0) {
+    console.info();
+    for (const w of allWarnings.slice(0, 5)) {
+      printWarn(w);
+    }
+    if (allWarnings.length > 5) {
+      printWarn(`... and ${allWarnings.length - 5} more warnings`);
+    }
+    log.writeLine("");
+    log.writeLine("Warnings:");
+    for (const w of allWarnings) {
+      log.writeLine(`  ${w}`);
+    }
+  }
+  if (audit) {
+    const todoPath = path__default.join(cwd, ".csszyx-todo.json");
+    const unique = [...new Set(allUnrecognized)];
+    console.info();
+    if (unique.length === 0) {
+      printSuccess(
+        "Audit complete. 100% of your classes are perfectly recognized by csszyx!"
+      );
+      log.writeLine("Audit: 100% recognized.");
+    } else {
+      const todoObj = {};
+      for (const u of unique) {
+        todoObj[u] = "sz:todo";
+      }
+      try {
+        fs$1.writeFileSync(todoPath, JSON.stringify(todoObj, null, 2));
+      } catch (err) {
+        printWarn(
+          `Could not write ${path__default.relative(cwd, todoPath)}: ${err instanceof Error ? err.message : String(err)}`
+        );
+        log.flush();
+        return;
+      }
+      printSuccess(
+        `Audit complete. Exported ${unique.length} unrecognized classes to ${path__default.relative(cwd, todoPath)}.`
+      );
+      printInfo(
+        "Edit this file to map custom classes, then run: npx @csszyx/cli migrate --resolve-todos .csszyx-todo.json"
+      );
+      log.writeLine(
+        `Audit: ${unique.length} unrecognized classes written to ${path__default.relative(cwd, todoPath)}`
+      );
+    }
+  }
+  if (resolveTodosPath) {
+    const unique = [...new Set(allUnrecognized)];
+    if (unique.length > 0) {
+      console.info();
+      printWarn(
+        `Still unresolved after this pass (${unique.length}): ${unique.slice(0, 10).join(", ")}${unique.length > 10 ? "..." : ""}`
+      );
+      printInfo("Re-run --audit to generate a fresh snapshot when ready.");
+      log.writeLine(`Still unresolved (${unique.length}): ${unique.join(", ")}`);
+    }
+  }
+  if (unusedImportFiles.length > 0) {
+    console.info();
+    printWarn("Potentially unused imports (run ESLint to clean up):");
+    for (const { file, imports } of unusedImportFiles) {
+      printInfo(`  ${file}: ${imports.map((i) => `import { ${i} }`).join(", ")}`);
+      log.writeLine(`  Unused import in ${file}: ${imports.join(", ")}`);
+    }
+  }
+  try {
+    log.flush();
+    printInfo(`Migration log saved to ${path__default.relative(cwd, log.filePath)}`);
+  } catch {
+  }
+}
+
+const DEFAULT_NEXT_SOURCE_PATTERN = "{app,pages,src}/**/*.{ts,tsx,js,jsx,mjs,cjs}";
+const DEFAULT_NEXT_SOURCE_IGNORE = [
+  "node_modules/**",
+  ".git/**",
+  ".next/**",
+  ".next-turbo-*/**",
+  ".csszyx/**",
+  "dist/**",
+  "build/**"
+];
+
+async function nextPrebuild(options = {}) {
+  const cwd = path__default.resolve(options.cwd ?? process.cwd());
+  const root = path__default.resolve(options.root ?? cwd);
+  const pattern = options.pattern ?? DEFAULT_NEXT_SOURCE_PATTERN;
+  try {
+    const mode = normalizeMode(options.mode);
+    const parserMode = normalizeParserMode$1(options.parserMode);
+    const matches = await fg(pattern, {
+      cwd: root,
+      absolute: true,
+      ignore: [...DEFAULT_NEXT_SOURCE_IGNORE, ...options.extraIgnore ?? []],
+      dot: false,
+      onlyFiles: true
+    });
+    if (matches.length === 0) {
+      const message = `No source files matched pattern \`${pattern}\` under ${root}.`;
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            { ok: false, reason: "no-files-matched", root, pattern, mode },
+            null,
+            2
+          )
+        );
+      } else {
+        console.error(`${colors.error(icons.error)} ${message}`);
+      }
+      return 1;
+    }
+    const result = runNextPrebuild({
+      files: matches,
+      explicitRoot: root,
+      cwd,
+      mode,
+      parserMode,
+      safelistOutputFile: options.outputFile,
+      cacheDir: options.cacheDir,
+      config: { mangleVars: false }
+      // Versions intentionally omitted: runNextPrebuild's package.json
+      // fallback reads the real installed @csszyx/unplugin and
+      // @csszyx/compiler versions so the manifest's generation identity
+      // tracks the engine that actually runs the transform.
+    });
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            root,
+            mode,
+            scannedCount: result.scannedCount,
+            transformedCount: result.transformedCount,
+            skippedMissingCount: result.skippedMissingCount,
+            sourceCount: result.sourceCount,
+            classCount: result.classCount,
+            manifestPath: result.manifestPath,
+            safelistOutputPath: result.safelistOutputPath
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(`${colors.success(icons.success)} csszyx next prebuild done`);
+      console.log(`  root:        ${root}`);
+      console.log(`  mode:        ${mode}`);
+      console.log(`  scanned:     ${result.scannedCount}`);
+      console.log(`  transformed: ${result.transformedCount}`);
+      console.log(`  skipped:     ${result.skippedMissingCount}`);
+      console.log(`  sources:     ${result.sourceCount}`);
+      console.log(`  classes:     ${result.classCount}`);
+      console.log(`  safelist:    ${result.safelistOutputPath}`);
+      console.log(`  manifest:    ${result.manifestPath}`);
+    }
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (options.json) {
+      console.log(JSON.stringify({ ok: false, reason: message }, null, 2));
+    } else {
+      console.error(`${colors.error(icons.error)} ${message}`);
+    }
+    return 1;
+  }
+}
+function normalizeMode(mode) {
+  if (mode === void 0) {
+    return "production";
+  }
+  if (mode === "development" || mode === "production") {
+    return mode;
+  }
+  throw new Error(`Invalid --mode "${mode}". Expected "development" or "production".`);
+}
+function normalizeParserMode$1(parserMode) {
+  if (parserMode === void 0) {
+    return void 0;
+  }
+  if (parserMode === "rust" || parserMode === "oxc" || parserMode === "babel") {
+    return parserMode;
+  }
+  throw new Error(`Invalid --parser-mode "${parserMode}". Expected "rust", "oxc", or "babel".`);
+}
+
+const SOURCE_EXTENSION = /\.[cm]?[jt]sx?$/i;
+async function startNextWatch(options = {}, dependencies = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const root = path.resolve(options.root ?? cwd);
+  const pattern = options.pattern ?? DEFAULT_NEXT_SOURCE_PATTERN;
+  const ignore = [...DEFAULT_NEXT_SOURCE_IGNORE, ...options.extraIgnore ?? []];
+  const parserMode = normalizeParserMode(options.parserMode);
+  const debounceMs = normalizeDebounceMs(options.debounceMs);
+  const files = await fg(pattern, {
+    cwd: root,
+    absolute: true,
+    ignore,
+    dot: false,
+    onlyFiles: true
+  });
+  if (files.length === 0) {
+    throw new Error(`No source files matched pattern \`${pattern}\` under ${root}.`);
+  }
+  const prebuild = runNextPrebuild({
+    files,
+    explicitRoot: root,
+    cwd,
+    mode: "development",
+    parserMode,
+    safelistOutputFile: options.outputFile,
+    cacheDir: options.cacheDir,
+    config: { mangleVars: false }
+  });
+  let resolveFailure = () => {
+  };
+  let failed = false;
+  const failure = new Promise((resolve) => {
+    resolveFailure = resolve;
+  });
+  const reportFailure = (error) => {
+    if (failed) {
+      return;
+    }
+    failed = true;
+    resolveFailure(error instanceof Error ? error : new Error(String(error)));
+  };
+  const controller = new NextSafelistWatcher({
+    context: prebuild.context,
+    debounceMs,
+    onError: reportFailure
+  });
+  const watchFactory = dependencies.watch ?? watch;
+  const fsWatcher = watchFactory(root, {
+    ignoreInitial: true,
+    persistent: true,
+    atomic: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 25,
+      pollInterval: 10
+    },
+    ignored: createIgnoredMatcher(root, prebuild.context.safelist.shardsDir, ignore)
+  });
+  fsWatcher.on("all", (event, filePath) => {
+    const absolutePath = path.resolve(filePath);
+    if (event === "add" || event === "change" || event === "unlink") {
+      if (controller.notify(event, absolutePath) || event !== "unlink" || !SOURCE_EXTENSION.test(absolutePath)) {
+        return;
+      }
+      controller.notifySourceRemoval(absolutePath);
+    }
+  });
+  fsWatcher.on("error", reportFailure);
+  try {
+    await waitForWatcherReady(fsWatcher);
+    controller.start();
+  } catch (error) {
+    await fsWatcher.close();
+    controller.close();
+    throw error;
+  }
+  let closed = false;
+  return {
+    root,
+    sourcePattern: pattern,
+    safelistOutputPath: prebuild.safelistOutputPath,
+    manifestPath: prebuild.manifestPath,
+    failure,
+    close: async () => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      await fsWatcher.close();
+      controller.close();
+    }
+  };
+}
+async function nextWatch(options = {}) {
+  let session;
+  let exitCode = 0;
+  try {
+    session = await startNextWatch(options);
+    if (!options.silent) {
+      console.log(`${colors.success(icons.success)} csszyx next watch ready`);
+      console.log(`  root:     ${session.root}`);
+      console.log(`  pattern:  ${session.sourcePattern}`);
+      console.log(`  safelist: ${session.safelistOutputPath}`);
+      console.log(`  manifest: ${session.manifestPath}`);
+    }
+    const outcome = await waitForShutdown(session.failure);
+    if (outcome) {
+      console.error(`${colors.error(icons.error)} ${outcome.message}`);
+      exitCode = 1;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${colors.error(icons.error)} ${message}`);
+    exitCode = 1;
+  }
+  try {
+    await session?.close();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${colors.error(icons.error)} Failed to close Next watcher: ${message}`);
+    exitCode = 1;
+  }
+  return exitCode;
+}
+function waitForWatcherReady(watcher) {
+  return new Promise((resolve, reject) => {
+    const onReady = () => {
+      watcher.off("error", onStartupError);
+      resolve();
+    };
+    const onStartupError = (error) => {
+      watcher.off("ready", onReady);
+      reject(error);
+    };
+    watcher.once("ready", onReady);
+    watcher.once("error", onStartupError);
+  });
+}
+function waitForShutdown(failure) {
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      process.off("SIGINT", onSignal);
+      process.off("SIGTERM", onSignal);
+    };
+    const onSignal = () => {
+      cleanup();
+      resolve(void 0);
+    };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+    failure.then((error) => {
+      cleanup();
+      resolve(error);
+    });
+  });
+}
+function createIgnoredMatcher(root, shardsDir, ignore) {
+  const normalizedShardsDir = path.resolve(shardsDir);
+  const matchers = ignore.flatMap((pattern) => {
+    const normalized = pattern.replace(/\\/g, "/");
+    const variants = normalized.endsWith("/**") ? [normalized, normalized.slice(0, -3)] : [normalized];
+    return variants.map((variant) => new Minimatch(variant, { dot: true }));
+  });
+  return (candidate) => {
+    const absolute = path.resolve(candidate);
+    const relativeToShards = path.relative(absolute, normalizedShardsDir);
+    if (absolute === normalizedShardsDir || absolute.startsWith(`${normalizedShardsDir}${path.sep}`) || relativeToShards !== ".." && !relativeToShards.startsWith(`..${path.sep}`) && !path.isAbsolute(relativeToShards)) {
+      return false;
+    }
+    const relative = path.relative(root, absolute).replace(/\\/g, "/");
+    if (!relative || relative.startsWith("../") || path.isAbsolute(relative)) {
+      return false;
+    }
+    return matchers.some((matcher) => matcher.match(relative));
+  };
+}
+function normalizeParserMode(parserMode) {
+  if (parserMode === void 0) {
+    return void 0;
+  }
+  if (parserMode === "rust" || parserMode === "oxc" || parserMode === "babel") {
+    return parserMode;
+  }
+  throw new Error(`Invalid --parser-mode "${parserMode}". Expected "rust", "oxc", or "babel".`);
+}
+function normalizeDebounceMs(debounceMs) {
+  if (debounceMs === void 0) {
+    return void 0;
+  }
+  const parsed = typeof debounceMs === "number" ? debounceMs : Number(debounceMs);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 6e4) {
+    throw new Error("Invalid --debounce-ms. Expected an integer between 0 and 60000.");
+  }
+  return parsed;
+}
+
+const cli = cac("csszyx");
+normalizeNextCommandAlias(process.argv);
+function readCliVersion() {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8")
+    );
+    return typeof manifest.version === "string" ? manifest.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+const VERSION = readCliVersion();
+async function runNextPrebuildCommand(pattern, options) {
+  const code = await nextPrebuild({
+    cwd: options.cwd,
+    root: options.root,
+    mode: options.mode,
+    parserMode: options.parserMode,
+    outputFile: options.outputFile,
+    cacheDir: options.cacheDir,
+    pattern,
+    extraIgnore: options.ignore ? String(options.ignore).split(",") : void 0,
+    json: options.json
+  });
+  if (code !== 0) {
+    process.exit(code);
+  }
+}
+async function runNextWatchCommand(pattern, options) {
+  const code = await nextWatch({
+    cwd: options.cwd,
+    root: options.root,
+    parserMode: options.parserMode,
+    outputFile: options.outputFile,
+    cacheDir: options.cacheDir,
+    pattern,
+    extraIgnore: options.ignore ? String(options.ignore).split(",") : void 0,
+    debounceMs: options.debounceMs
+  });
+  process.exitCode = code;
+}
+cli.command("init", "Setup csszyx in your project").option("--framework <name>", "Specify framework").option("--yes", "Skip prompts (use defaults)").option("--cwd <dir>", "Current working directory").action(async (options) => {
+  await init({
+    framework: options.framework,
+    yes: options.yes,
+    cwd: options.cwd
+  });
+});
+cli.command("doctor", "Diagnose mangling issues").option("--verbose", "Show detailed output").option("--cwd <dir>", "Current working directory").action(async (options) => {
+  await doctor({
+    verbose: options.verbose,
+    cwd: options.cwd
+  });
+});
+cli.command("explain <sz>", "Print the Tailwind className an sz object compiles to").action(
+  (sz) => {
+    explain(sz);
+  }
+);
+cli.command("audit", "Analyze mangling performance").option("--json", "Output as JSON").option("--watch", "Live updates").option("--compare <dir>", "Compare with previous build").option("--cwd <dir>", "Current working directory").action(async (options) => {
+  await audit({
+    json: options.json,
+    watch: options.watch,
+    compare: options.compare,
+    cwd: options.cwd
+  });
+});
+cli.command("generate-types", "Generate TypeScript declarations from tailwind.config.js").option("-c, --config <path>", "Path to tailwind.config.js").option("-o, --output <path>", "Output file path (default: ./csszyx.d.ts)").option("--cwd <dir>", "Current working directory").option("--silent", "Silent mode (no output)").action(async (options) => {
+  await generateTypes({
+    config: options.config,
+    output: options.output,
+    cwd: options.cwd,
+    silent: options.silent
+  });
+});
+cli.command("migrate [dir]", "Convert Tailwind className to sz prop").option("--dry-run", "Show changes without modifying files").option("--ignore <patterns>", "Glob patterns to ignore (comma-separated)").option("--pattern <glob>", "Custom glob pattern for file discovery").option("--cwd <dir>", "Current working directory").option("--braces", "Wrap HTML sz values in outer { } braces (default: bare)").option("--no-fouc", "Skip FOUC-prevention CSS injection into HTML files").option("--inject-runtime <mode>", "Inject runtime script into HTML: local | cdn").option("--cdn-url <url>", "Custom CDN URL for --inject-runtime cdn").option(
+  "--local-path <path>",
+  "Local script path for --inject-runtime local (default: csszyx-runtime.js)"
+).option("--audit", "Scan without modifying files and output .csszyx-todo.json").option("--inject-todos", "Inject {/* @sz-todo */} comments above unrecognized classes").option("--resolve-todos <file>", "Path to a JSON file mapping custom classes to sz properties").option(
+  "--keys-only",
+  "Only normalize legacy sz-prop keys to their canonical form; leave className untouched (0.9.10 \u2192 0.10.0 upgrade)"
+).action(async (dir, options) => {
+  await migrate({
+    dryRun: options.dryRun,
+    ignore: options.ignore ? options.ignore.split(",") : void 0,
+    pattern: options.pattern,
+    cwd: dir || options.cwd,
+    braces: options.braces,
+    injectFouc: options.fouc !== false,
+    injectRuntime: options.injectRuntime === "local" ? "local" : options.injectRuntime === "cdn" ? "cdn" : false,
+    cdnUrl: options.cdnUrl,
+    localPath: options.localPath,
+    audit: options.audit,
+    injectTodos: options.injectTodos,
+    resolveTodos: options.resolveTodos,
+    keysOnly: options.keysOnly
+  });
+});
+cli.command(
+  "next-prebuild [pattern]",
+  "Seed the Next.js Turbopack csszyx safelist and generation manifest"
+).option("--root <dir>", "Next app root (defaults to cwd)").option("--cwd <dir>", "Current working directory").option("--mode <mode>", "development | production (default: production)").option("--parser-mode <mode>", "rust | oxc | babel (default: rust)").option(
+  "--output-file <path>",
+  "Tailwind @source safelist output (default: csszyx-classes.html)"
+).option("--cache-dir <dir>", "Cache directory relative to root (default: .csszyx/cache)").option("--ignore <patterns>", "Extra glob patterns to ignore (comma-separated)").option("--json", "Emit a single JSON result instead of formatted text").action(runNextPrebuildCommand);
+cli.command("next-watch [pattern]", "Maintain the Next.js Turbopack csszyx safelist").option("--root <dir>", "Next app root (defaults to cwd)").option("--cwd <dir>", "Current working directory").option("--parser-mode <mode>", "rust | oxc | babel (default: rust)").option(
+  "--output-file <path>",
+  "Tailwind @source safelist output (default: csszyx-classes.html)"
+).option("--cache-dir <dir>", "Cache directory relative to root (default: .csszyx/cache)").option("--ignore <patterns>", "Extra glob patterns to ignore (comma-separated)").option("--debounce-ms <ms>", "Safelist materialization debounce (default: 50)").action(runNextWatchCommand);
+cli.command("").action(() => {
+  cli.outputHelp();
+});
+cli.help();
+cli.version(VERSION);
+cli.parse();
+function normalizeNextCommandAlias(argv) {
+  if (argv[2] === "next" && (argv[3] === "prebuild" || argv[3] === "watch")) {
+    argv.splice(2, 2, `next-${argv[3]}`);
+  }
+}