@birdycom/omniacss-migrate 0.0.0-stage → 0.11.1

package/src/resolve.mjs

@@ -0,0 +1,220 @@
+// File: packages/migrate/src/resolve.mjs
+// Resolver: a Tailwind-style class token (with variants, !important, negatives, modifiers) -> CSS rules
+// that only use OmniaCSS tokens. Entry points: createContext(), resolveToken(), compileTokens().
+// Author: Serge Cools | Framework: OmniaCSS
+
+import { applyVariant, esc, splitTop } from "./variants.mjs";
+import { HANDLERS, KEYFRAMES, MARKERS, STATIC } from "./utilities.mjs";
+import { arb, normalizeArb } from "./values.mjs";
+
+export const SCREENS = {
+  omnia: { sm: "36rem", md: "50rem", lg: "64rem", xl: "80rem", "2xl": "96rem" },
+  tailwind: { sm: "40rem", md: "48rem", lg: "64rem", xl: "80rem", "2xl": "96rem" },
+};
+
+/**
+ * Build the resolver context.
+ * @param {object} [o]
+ * @param {boolean} [o.v4=true]            Tailwind 4 naming (shadow-sm, rounded-sm, ring …)
+ * @param {"class"|"media"} [o.darkMode="class"]
+ * @param {string} [o.darkSelector=".dark"] selector for class based dark mode
+ * @param {"omnia"|"tailwind"} [o.breakpoints="omnia"]
+ * @param {Record<string,string>} [o.screens] extra/override screens
+ * @param {"nearest"|"keep"} [o.arbitraryColors="nearest"]
+ * @param {Iterable<string>} [o.themeVars] custom properties defined in the user's @theme (e.g. "--color-primary")
+ * @param {Record<string,string>} [o.customColors] extra color names -> css value (from tailwind.config)
+ * @param {string} [o.prefix]               Tailwind `prefix` option
+ */
+export function createContext(o = {}) {
+  const screens = { ...SCREENS[o.breakpoints || "omnia"], ...(o.screens || {}) };
+  const order = Object.keys(screens).sort((a, b) => parseFloat(screens[a]) - parseFloat(screens[b]));
+  const themeVars = new Set(o.themeVars || []);
+  return {
+    v4: o.v4 ?? true,
+    darkMode: o.darkMode || "class",
+    darkSelector: o.darkSelector || ".dark",
+    screens,
+    screenRank: (n) => order.indexOf(n) * 10,
+    arbitraryColors: o.arbitraryColors || "nearest",
+    themeVars,
+    hasTheme: (n) => themeVars.has(n),
+    customColors: new Map(Object.entries(o.customColors || {})),
+    prefix: o.prefix || "",
+    container: o.container || {},
+    tokensFile: o.tokensFile,
+    important: !!o.important,
+  };
+}
+
+/** Roots that accept a leading `-` (negative values). */
+const NEG_OK = /^(m[xytrblse]?|scroll-m[xytrblse]?|inset(-[xy])?|top|right|bottom|left|start|end|z|order|translate(-[xyz])?|rotate(-[xy])?|scale(-[xy])?|skew(-[xy])?|hue-rotate|backdrop-hue-rotate|tracking|indent|underline-offset|outline-offset|col(-start|-end)?|row(-start|-end)?|space-[xy]|spin-in|spin-out|bg)$/;
+
+// ---------------------------------------------------------------------------------------------- parsing
+
+/**
+ * Parse a raw class token.
+ * @returns {{ raw: string, variants: string[], utility: string, important: boolean, neg: boolean, body: string }}
+ */
+export function parseToken(raw, ctx) {
+  const parts = splitTop(raw, ":");
+  const variants = parts.slice(0, -1);
+  let utility = parts[parts.length - 1];
+  let important = false, neg = false;
+  if (utility.startsWith("!")) { important = true; utility = utility.slice(1); }
+  if (utility.endsWith("!")) { important = true; utility = utility.slice(0, -1); }
+  if (ctx?.prefix) {
+    const p = ctx.prefix;
+    if (utility.startsWith("-" + p)) utility = "-" + utility.slice(p.length + 1);
+    else if (utility.startsWith(p)) utility = utility.slice(p.length);
+    else if (utility.startsWith("[") === false && !MARKERS.test(utility)) return { raw, variants, utility, important, neg, body: utility, foreign: true };
+  }
+  if (utility.startsWith("-") && utility.length > 1) { neg = true; utility = utility.slice(1); }
+  return { raw, variants, utility, important, neg, body: utility };
+}
+
+/** Split `a-b-[c-d]` on dashes outside brackets. */
+function splitDash(s) {
+  return splitTop(s, "-");
+}
+
+/** Split `bg-red-500/50` into [body, modifier]; ignores slashes inside brackets. */
+function splitModifier(body) {
+  const parts = splitTop(body, "/");
+  if (parts.length < 2) return [body, undefined];
+  return [parts.slice(0, -1).join("/"), parts[parts.length - 1]];
+}
+
+const norm = (r) => (!r ? null : Array.isArray(r) ? { decls: r } : r);
+
+/** Resolve the utility part (no variants). Returns { decls, tail?, keyframes?, extraRules?, marker? } or null. */
+export function resolveUtility(p, ctx) {
+  const { body, neg } = p;
+  if (!neg) {
+    const m = body.match(/^\[(--[A-Za-z0-9_-]+|-?[a-z][a-z-]*):([^:\s].*)\]$/);
+    if (m && !/^[\s;{}]/.test(m[2])) return { decls: [[m[1], normalizeArb(m[2])]] };
+    if (MARKERS.test(body)) return { decls: [], marker: true };
+    if (Object.hasOwn(STATIC, body)) return { decls: STATIC[body], static: true, ...(body.startsWith("animate-in") || body.startsWith("animate-out") ? { keyframes: [body.slice(8)] } : {}) };
+    if (body === "container") return containerRule(ctx);
+  }
+  const [bare, mod] = splitModifier(body);
+  const words = splitDash(bare);
+  for (let i = words.length; i >= 1; i--) {
+    const root = words.slice(0, i).join("-");
+    const fn = Object.hasOwn(HANDLERS, root) ? HANDLERS[root] : null;
+    if (!fn) continue;
+    if (neg && !NEG_OK.test(root)) continue;
+    const value = words.slice(i).join("-");
+    if (!value && i === words.length && false) continue;
+    // `w-1/2`, `translate-x-1/2`: try the fraction first, then value + opacity/line-height modifier
+    let r = mod !== undefined ? norm(fn({ root, value: `${value}/${mod}`, mod: undefined, neg, ctx })) : null;
+    if (!r) r = norm(fn({ root, value, mod, neg, ctx }));
+    if (r) return r;
+  }
+  return null;
+}
+
+function containerRule(ctx) {
+  const decls = [["width", "100%"]];
+  if (ctx.container.center) decls.push(["margin-inline", "auto"]);
+  if (ctx.container.padding) decls.push(["padding-inline", ctx.container.padding]);
+  const extraRules = Object.entries(ctx.screens).map(([k, w]) => ({ media: [`@media (min-width: ${w})`], decls: [["max-width", w]], rank: ctx.screenRank(k) }));
+  return { decls, extraRules };
+}
+
+// property rank so shorthands sort before longhands (`p-4` before `px-2` before `pl-1`)
+const SHORTHANDS = new Set(["margin", "padding", "inset", "gap", "border-width", "border-color", "border-radius", "border", "overflow", "scroll-margin", "scroll-padding", "transition-property", "flex", "background", "font", "outline", "translate", "rotate", "scale", "size"]);
+function propRank(prop) {
+  if (SHORTHANDS.has(prop)) return 0;
+  if (/-(top|right|bottom|left|start|end)\b|^(top|right|bottom|left)$|-(x|y)$/.test(prop)) return 2;
+  return 1;
+}
+
+/**
+ * Resolve one token.
+ * @param {string} raw class token, e.g. "md:hover:bg-red-500/50"
+ * @param {object} ctx from createContext()
+ * @param {{ selector?: string }} [opts] selector: use instead of `.escaped-token` (for @apply)
+ * @returns {null | { token: string, rules: Array<{selectors:string[], media:string[], decls:string[][], rank:number}>, keyframes: string[], marker?: boolean }}
+ */
+export function resolveToken(raw, ctx, opts = {}) {
+  const p = parseToken(raw, ctx);
+  if (p.foreign || !p.body) return null;
+  const util = resolveUtility(p, ctx);
+  if (!util) return null;
+  if (util.marker) return { token: raw, rules: [], keyframes: [], marker: true };
+
+  const st = { sels: [opts.selector || `.${esc(raw)}`], media: [], prelude: [], rank: 0 };
+  for (let i = p.variants.length - 1; i >= 0; i--) {
+    if (!applyVariant(p.variants[i], st, ctx)) return null;
+  }
+  // a pseudo-element can only end a selector: `[&_.x]:placeholder:italic` would give `::placeholder .x` (invalid, dropped)
+  if (st.sels.some((s) => /::[a-z-]+(?:\([^)]*\))?[\s>+~.[#]/.test(s))) return null;
+  const important = p.important || ctx.important;
+  const fix = (decls) => decls.map(([k, v]) => [k, important && !/ !important$/.test(v) ? `${v} !important` : v]);
+  const hasContent = util.decls.some(([k]) => k === "content");
+  const base = fix([...(hasContent ? [] : st.prelude), ...util.decls]);
+  const urank = propRank((util.decls[0] || [""])[0]);
+  const tail = util.tail || "";
+  const selectors = st.sels.map((s) => s + tail);
+  const rules = [];
+  if (base.length) rules.push({ selectors, media: st.media, decls: base, rank: st.rank, urank });
+  for (const x of util.extraRules || []) rules.push({ selectors, media: [...st.media, ...x.media], decls: fix(x.decls), rank: st.rank + 1 + (x.rank || 0), urank });
+  return { token: raw, rules, keyframes: util.keyframes || [] };
+}
+
+// ---------------------------------------------------------------------------------------------- compile
+
+const fmtDecls = (decls, indent) => decls.map(([k, v]) => `${indent}${k}: ${v};`).join("\n");
+
+/**
+ * Compile a list of resolved tokens into one stylesheet (ordered like a utility framework: base < pseudo < dark < responsive).
+ * @param {Array<ReturnType<typeof resolveToken>>} resolved
+ */
+export function serialize(resolved) {
+  const rules = [];
+  const frames = new Set();
+  for (const r of resolved) {
+    if (!r) continue;
+    r.keyframes.forEach((k) => frames.add(k));
+    for (const rule of r.rules) rules.push({ ...rule, token: r.token });
+  }
+  rules.sort((a, b) => a.rank - b.rank || a.urank - b.urank || (a.token < b.token ? -1 : a.token > b.token ? 1 : 0));
+  const renderRule = (r, ind = "") => `${r.selectors.map((x) => ind + x).join(",\n")} {\n${fmtDecls(r.decls, ind + "  ")}\n${ind}}`;
+  const out = [];
+  for (const k of frames) if (KEYFRAMES[k]) out.push(KEYFRAMES[k]);
+  let group = null;
+  const flush = () => {
+    if (!group) return;
+    let inner = group.rules.map((r) => renderRule(r, "  ".repeat(group.media.length))).join("\n");
+    for (let i = group.media.length - 1; i >= 0; i--) {
+      const ind = "  ".repeat(i);
+      inner = `${ind}${group.media[i]} {\n${inner}\n${ind}}`;
+    }
+    out.push(inner);
+    group = null;
+  };
+  for (const rule of rules) {
+    if (!rule.media.length) { flush(); out.push(renderRule(rule)); continue; }
+    const key = rule.media.join("|");
+    if (!group || group.key !== key) { flush(); group = { key, media: rule.media, rules: [] }; }
+    group.rules.push(rule);
+  }
+  flush();
+  return out.join("\n");
+}
+
+/** Resolve many tokens and report what could not be resolved. */
+export function compileTokens(tokens, ctx) {
+  const resolved = [], unsupported = [];
+  for (const t of tokens) {
+    const r = resolveToken(t, ctx);
+    if (r) resolved.push(r); else unsupported.push(t);
+  }
+  return { css: serialize(resolved), resolved, unsupported };
+}
+
+/** Convenience: one token -> css string (or null). */
+export function compileToken(raw, ctx = createContext()) {
+  const r = resolveToken(raw, ctx);
+  return r ? serialize([r]) : null;
+}

package/src/scan.mjs

@@ -0,0 +1,106 @@
+// File: packages/migrate/src/scan.mjs
+// Coverage scan: how many of the Tailwind-style classes in a project can the compat layer resolve?
+// Author: Serge Cools | Framework: OmniaCSS
+
+import fs from "node:fs/promises";
+import { classStrings, walk, DEFAULT_EXTENSIONS } from "./extract.mjs";
+import { parseToken, resolveToken, createContext } from "./resolve.mjs";
+import { HANDLERS, STATIC } from "./utilities.mjs";
+import { applyVariant } from "./variants.mjs";
+
+const EXTRA_ROOTS = ["mask", "text-shadow", "bg-opacity", "text-opacity", "border-opacity", "ring-opacity", "divide-opacity", "placeholder-opacity", "font-stretch", "prose", "icon", "scrollbar",
+  "bg-position", "bg-size", "border-spacing", "grid-cols", "bg-linear", "bg-radial", "bg-conic", "text-balance", "stroke", "fill", "ring", "size", "outline", "container", "mix", "bg-blend", "line-clamp",
+  "scheme", "wrap", "perspective", "transform", "backface", "snap", "touch", "motion", "overflow", "sr", "not-sr", "decoration", "underline", "break", "hyphens", "font", "caption", "forced"];
+const ROOTS = new Set([...Object.keys(HANDLERS), ...Object.keys(STATIC).map((k) => k.split("-")[0]), ...Object.keys(STATIC), ...EXTRA_ROOTS]);
+
+const VARIANT_LIKE = /^(group|peer|data|aria|has|not|in|supports|min|max|nth|@|\[)/;
+
+/** Does an unresolved token look like a Tailwind class (so it counts as "unsupported" rather than "custom")? */
+export function looksLikeTailwind(token, ctx) {
+  const p = parseToken(token, ctx);
+  for (const v of p.variants) {
+    const st = { sels: ["&"], media: [], prelude: [], rank: 0 };
+    if (applyVariant(v, st, ctx) || VARIANT_LIKE.test(v)) return true;
+  }
+  const body = p.body.split("/")[0];
+  if (/^\[/.test(body)) return /^\[[a-z-]+:/i.test(body);
+  const words = body.split("-");
+  if (words.length === 1 && !p.variants.length) return false;
+  if (ROOTS.has(words[0])) return true;
+  return false;
+}
+
+/** Heuristic: is a quoted string a list of class names? (>= 30% of its words resolve, or a class-ish attribute/call precedes it) */
+export function isClassString(kinds, hinted) {
+  const hits = kinds.filter((k) => k === "supported").length;
+  return hits >= 1 && (hits / kinds.length >= 0.3 || hinted) && (kinds.length >= 2 || hinted);
+}
+
+/**
+ * Scan a directory.
+ * @param {string} dir
+ * @param {{ ctx?: object, extensions?: string[], onFile?: (f:string)=>void }} [o]
+ */
+export function makeKind(ctx, cache = new Map()) {
+  return (t) => {
+    let k = cache.get(t);
+    if (k) return k;
+    k = resolveToken(t, ctx) ? "supported" : looksLikeTailwind(t, ctx) ? "unsupported" : "custom";
+    cache.set(t, k);
+    return k;
+  };
+}
+
+export async function scanDir(dir, o = {}) {
+  const ctx = o.ctx || createContext();
+  const cache = new Map();
+  const kind = (t) => {
+    let k = cache.get(t);
+    if (k) return k;
+    const r = resolveToken(t, ctx);
+    k = r ? (r.marker ? "supported" : "supported") : looksLikeTailwind(t, ctx) ? "unsupported" : "custom";
+    cache.set(t, k);
+    return k;
+  };
+  const files = await walk(dir, { extensions: o.extensions || DEFAULT_EXTENSIONS });
+  const stats = { dir, files: files.length, occurrences: 0, supported: 0, unsupportedCount: 0, customCount: 0, unsupported: new Map(), custom: new Map(), uniqueSupported: new Set(), approximatedColors: 0 };
+  for (const file of files) {
+    let text;
+    try { text = await fs.readFile(file, "utf8"); } catch { continue; }
+    for (const s of classStrings(text)) {
+      const words = s.words;
+      if (!words.length) continue;
+      const kinds = words.map(kind);
+      const hits = kinds.filter((k) => k === "supported").length;
+      if (!isClassString(kinds, s.hinted)) continue;
+      words.forEach((w, i) => {
+        if (kinds[i] === "supported") {
+          stats.occurrences++; stats.supported++; stats.uniqueSupported.add(w);
+          if (/^[^:]*:?[a-z-]+-\[#|\[#[0-9a-f]{3,8}\]/i.test(w)) stats.approximatedColors++;
+        } else if (kinds[i] === "unsupported") {
+          stats.occurrences++; stats.unsupportedCount++; stats.unsupported.set(w, (stats.unsupported.get(w) || 0) + 1);
+        } else {
+          stats.customCount++; stats.custom.set(w, (stats.custom.get(w) || 0) + 1);
+        }
+      });
+    }
+  }
+  stats.coverage = stats.occurrences ? (stats.supported / stats.occurrences) * 100 : 100;
+  return stats;
+}
+
+/** Plain-text report. */
+export function formatScan(stats, { top = 40 } = {}) {
+  const sort = (m) => [...m.entries()].sort((a, b) => b[1] - a[1]);
+  const lines = [];
+  lines.push(`Scanned ${stats.files} files in ${stats.dir}`);
+  lines.push(`Tailwind-style class occurrences: ${stats.occurrences}`);
+  lines.push(`  supported:   ${stats.supported} (${stats.coverage.toFixed(2)}%)  [${stats.uniqueSupported.size} unique]`);
+  lines.push(`  unsupported: ${stats.unsupportedCount} (${stats.unsupported.size} unique)`);
+  lines.push(`  custom (not Tailwind, left alone): ${stats.customCount} occurrences, ${stats.custom.size} unique`);
+  if (stats.unsupported.size) {
+    lines.push("", `Top unsupported classes:`);
+    for (const [t, n] of sort(stats.unsupported).slice(0, top)) lines.push(`  ${String(n).padStart(5)}  ${t}`);
+  }
+  return lines.join("\n");
+}

package/src/setup.mjs

@@ -0,0 +1,205 @@
+// File: packages/migrate/src/setup.mjs
+// `omniacss-migrate setup <project>`: detect Tailwind in package.json / vite / postcss / CSS and plan (or apply)
+// the switch to OmniaCSS. Planning never touches the disk; `apply` writes only the planned files.
+// Author: Serge Cools | Framework: OmniaCSS
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadProject, loadTailwindConfig, themeFromConfig, findFiles } from "./project.mjs";
+import { createContext } from "./resolve.mjs";
+
+const TW_PKGS = ["tailwindcss", "@tailwindcss/vite", "@tailwindcss/postcss"];
+const TW_NAME = "(?:@tailwindcss\\/vite|@tailwindcss\\/postcss|tailwindcss)";
+const VERSION = "^0.4.0";
+
+const read = (f) => fs.readFile(f, "utf8").catch(() => null);
+
+function detectIndent(text) {
+  const m = text.match(/^([ \t]+)"/m);
+  return m ? m[1] : "  ";
+}
+
+/** Tiny line diff (common prefix/suffix trimmed) for the dry-run output. */
+export function diffLines(before, after) {
+  const a = before.split(/\r?\n/), b = after.split(/\r?\n/);
+  let s = 0;
+  while (s < a.length && s < b.length && a[s] === b[s]) s++;
+  let ea = a.length - 1, eb = b.length - 1;
+  while (ea >= s && eb >= s && a[ea] === b[eb]) { ea--; eb--; }
+  const x = a.slice(s, ea + 1), y = b.slice(s, eb + 1);
+  const out = [];
+  if (x.length * y.length > 4_000_000) {
+    x.forEach((l) => out.push(`- ${l}`)); y.forEach((l) => out.push(`+ ${l}`));
+    return out;
+  }
+  // LCS table (lines are few: config files)
+  const dp = Array.from({ length: x.length + 1 }, () => new Uint16Array(y.length + 1));
+  for (let i = x.length - 1; i >= 0; i--) for (let j = y.length - 1; j >= 0; j--) dp[i][j] = x[i] === y[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+  let i = 0, j = 0;
+  while (i < x.length || j < y.length) {
+    if (i < x.length && j < y.length && x[i] === y[j]) { i++; j++; }
+    else if (j < y.length && (i === x.length || dp[i][j + 1] >= dp[i + 1][j])) out.push(`+ ${y[j++]}`);
+    else out.push(`- ${x[i++]}`);
+  }
+  return out;
+}
+
+function transformVite(text) {
+  let out = text;
+  const notes = [];
+  const imp = out.match(new RegExp(`^[ \\t]*import\\s+(\\w+)\\s+from\\s+['"]${TW_NAME}['"];?[ \\t]*$`, "m"));
+  const req = out.match(new RegExp(`^[ \\t]*(?:const|let|var)\\s+(\\w+)\\s*=\\s*require\\(['"]${TW_NAME}['"]\\);?[ \\t]*$`, "m"));
+  const hit = imp || req;
+  const name = hit?.[1];
+  if (hit) {
+    const line = imp ? "import omniaMigrate from '@birdycom/omniacss-migrate/vite';" : "const omniaMigrate = require('@birdycom/omniacss-migrate/vite');";
+    out = out.replace(hit[0], hit[0].replace(/\S.*$/, line));
+    out = out.replace(new RegExp(`\\b${name}\\(`, "g"), "omniaMigrate(");
+    // bare references inside the css.postcss.plugins array: the Vite plugin injects the PostCSS part itself
+    out = out.replace(new RegExp(`(plugins:\\s*\\[)\\s*${name}\\s*,\\s*`, "g"), "$1");
+    out = out.replace(new RegExp(`,\\s*${name}\\s*(?=[,\\]])`, "g"), "");
+    out = out.replace(new RegExp(`(plugins:\\s*\\[)\\s*${name}\\s*\\]`, "g"), "$1]");
+  } else if (!/@birdycom\/omniacss-migrate/.test(out)) {
+    // no Tailwind import: add the plugin when there is a plugins array
+    if (/plugins:\s*\[/.test(out) && /import\s/.test(out)) {
+      const lines = out.split("\n");
+      const lastImport = lines.map((l, i) => (/^\s*import\s/.test(l) ? i : -1)).filter((i) => i >= 0).pop();
+      lines.splice(lastImport + 1, 0, "import omniaMigrate from '@birdycom/omniacss-migrate/vite';");
+      out = lines.join("\n").replace(/(\n\s*)plugins:\s*\[/, "$1plugins: [$1    omniaMigrate(),");
+      notes.push("added omniaMigrate() to plugins");
+    }
+  }
+  return { out, notes };
+}
+
+function transformPostcss(text, hasVite) {
+  let out = text;
+  const entry = new RegExp(`^[ \\t]*["']?${TW_NAME}["']?[ \\t]*:[ \\t]*\\{[^}]*\\}[ \\t]*,?[ \\t]*\\r?\\n`, "gm");
+  const arrayEntry = new RegExp(`^[ \\t]*(?:require\\(['"]${TW_NAME}['"]\\)|['"]${TW_NAME}['"]|tailwindcss(?:\\(\\))?)[ \\t]*,?[ \\t]*\\r?\\n`, "gm");
+  const replacement = hasVite ? "" : null;
+  if (replacement !== null) out = out.replace(entry, "").replace(arrayEntry, "");
+  else {
+    out = out.replace(entry, (m) => m.replace(/\S[\s\S]*?:\s*\{[^}]*\}/, '"@birdycom/omniacss-migrate/postcss": {}'));
+    out = out.replace(arrayEntry, (m) => m.replace(/\S[^,\r\n]*/, "require('@birdycom/omniacss-migrate/postcss')()"));
+  }
+  return out;
+}
+
+/**
+ * Plan the switch for a project.
+ * @param {string} dir
+ * @returns {Promise<{ changes: Array<{file:string, before:string, after:string, note:string}>, notes: string[], commands: string[], detected: object }>}
+ */
+export async function planSetup(dir, { keepBrandColors = false } = {}) {
+  const changes = [], notes = [], commands = [];
+  const detected = { tailwind: false, packages: [], vite: [], postcss: [], css: [], config: null };
+
+  // package.json
+  const pkgFile = path.join(dir, "package.json");
+  const pkgText = await read(pkgFile);
+  if (pkgText == null) throw new Error(`No package.json in ${dir}`);
+  const pkg = JSON.parse(pkgText);
+  const removed = [];
+  for (const section of ["dependencies", "devDependencies"]) {
+    for (const name of TW_PKGS) if (pkg[section]?.[name]) { removed.push(name); detected.packages.push(`${name}@${pkg[section][name]}`); }
+  }
+  detected.tailwind = removed.length > 0;
+  const afterPkg = structuredClone(pkg);
+  for (const section of ["dependencies", "devDependencies"]) for (const name of TW_PKGS) if (afterPkg[section]) delete afterPkg[section][name];
+  afterPkg.devDependencies ||= {};
+  afterPkg.devDependencies["@birdycom/omniacss-migrate"] = VERSION;
+  afterPkg.devDependencies = Object.fromEntries(Object.entries(afterPkg.devDependencies).sort(([a], [b]) => a.localeCompare(b)));
+  const nl = pkgText.includes("\r\n") ? "\r\n" : "\n";
+  const pkgAfter = JSON.stringify(afterPkg, null, detectIndent(pkgText)).replace(/\n/g, nl) + (pkgText.endsWith("\n") ? nl : "");
+  changes.push({ file: pkgFile, before: pkgText, after: pkgAfter, note: `remove ${removed.join(", ") || "(no tailwind packages)"}; add @birdycom/omniacss-migrate` });
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps["@iconify/tailwind4"] || deps["@iconify/tailwind"]) notes.push("Icon classes from the Iconify Tailwind plugin (icon-[mdi--home]) are not generated: switch those to an icon component or the Iconify web component.");
+  if (deps["@tailwindcss/typography"]) notes.push("@tailwindcss/typography (prose) is not emulated.");
+  if (deps["@tailwindcss/forms"]) notes.push("@tailwindcss/forms is not emulated; the base reset covers most form basics.");
+  if (deps["tailwindcss-animate"] || deps["tw-animate-css"]) notes.push("tailwindcss-animate classes (animate-in, fade-in-0, zoom-in-95, slide-in-from-*) are emulated.");
+  if (deps["tailwind-merge"]) notes.push("tailwind-merge keeps working unchanged: your class names stay the same.");
+  if (deps["prettier-plugin-tailwindcss"]) notes.push("prettier-plugin-tailwindcss only sorts class names; it can stay.");
+
+  // vite + postcss configs
+  const viteFiles = [];
+  for (const n of ["vite.config.js", "vite.config.ts", "vite.config.mjs", "vite.config.mts"]) if (await read(path.join(dir, n)) != null) viteFiles.push(path.join(dir, n));
+  for (const f of viteFiles) {
+    const before = await read(f);
+    const { out, notes: n } = transformVite(before);
+    detected.vite.push(path.basename(f));
+    if (out !== before) changes.push({ file: f, before, after: out, note: "use the OmniaCSS Vite plugin" + (n.length ? ` (${n.join(", ")})` : "") });
+    else notes.push(`${path.basename(f)}: no Tailwind plugin found. Add \`import omniaMigrate from '@birdycom/omniacss-migrate/vite'\` and put omniaMigrate() in plugins.`);
+  }
+  for (const n of ["postcss.config.js", "postcss.config.cjs", "postcss.config.mjs"]) {
+    const f = path.join(dir, n);
+    const before = await read(f);
+    if (before == null) continue;
+    detected.postcss.push(n);
+    const after = transformPostcss(before, viteFiles.length > 0);
+    if (after !== before) changes.push({ file: f, before, after, note: viteFiles.length ? "remove the Tailwind PostCSS plugin (the Vite plugin injects the OmniaCSS one)" : "swap the Tailwind PostCSS plugin for @birdycom/omniacss-migrate/postcss" });
+  }
+
+  // tailwind.config + css
+  const project = await loadProject(dir, { keepBrandColors });
+  detected.config = project.info.configFile ? path.basename(project.info.configFile) : null;
+  const loaded = await loadTailwindConfig(dir);
+  const cssFiles = (await findFiles(dir, (n) => n.endsWith(".css"))).filter((f) => !/[\\/]public[\\/]/.test(f));
+  let entryDone = false;
+  for (const f of cssFiles) {
+    const before = await read(f);
+    if (!/@import\s+["']tailwindcss|@tailwind\s+(base|utilities)/.test(before)) continue;
+    detected.css.push(path.relative(dir, f));
+    if (entryDone) continue;
+    entryDone = true;
+    const add = [];
+    if (loaded?.config) {
+      const t = themeFromConfig(loaded.config, createContext({}), { keepColors: keepBrandColors });
+      if (t.decls.length && !/omniacss-migrate: theme/.test(before)) {
+        add.push("/* omniacss-migrate: theme from tailwind.config (literal colors mapped to the nearest Omnia palette token) */");
+        add.push("@theme {");
+        for (const [k, v] of t.decls) add.push(`  ${k}: ${v};`);
+        add.push("}");
+      }
+      notes.push(...t.notes.filter((n) => !n.startsWith("color ")));
+      const dm = Array.isArray(loaded.config.darkMode) ? loaded.config.darkMode[0] : loaded.config.darkMode;
+      if ((dm === "class" || dm === "selector") && !/@custom-variant\s+dark/.test(before)) add.push("@custom-variant dark (&:where(.dark, .dark *));");
+    }
+    if (add.length) {
+      const re = /^(@import\s+["']tailwindcss["'][^;\n]*;|@tailwind\s+utilities;)[ \t]*\r?\n/m;
+      const m = before.match(re);
+      const eol = before.includes("\r\n") ? "\r\n" : "\n";
+      const after = m ? before.replace(re, `${m[0]}${eol}${add.join(eol)}${eol}`) : before + eol + add.join(eol) + eol;
+      changes.push({ file: f, before, after, note: "carry tailwind.config theme into CSS (@theme) and dark mode variant" });
+    } else notes.push(`${path.relative(dir, f)}: the directives (@import "tailwindcss" / @tailwind …) are handled by the plugin; no change needed.`);
+    if (/@plugin\s+['"]@iconify/.test(before)) notes.push("`@plugin '@iconify/...'` is ignored by the plugin (icon-[...] classes are not generated).");
+  }
+  if (!detected.css.length) notes.push("No CSS file with Tailwind directives found. The plugin works on `@import \"tailwindcss\"` or `@tailwind base/components/utilities`.");
+  commands.push("npm uninstall " + (removed.join(" ") || "tailwindcss @tailwindcss/vite"));
+  commands.push("npm install -D @birdycom/omniacss-migrate");
+  return { changes, notes, commands, detected };
+}
+
+/** Write the planned changes to disk. */
+export async function applySetup(plan, { backup = false } = {}) {
+  for (const c of plan.changes) {
+    if (backup) await fs.copyFile(c.file, c.file + ".pre-omnia");
+    await fs.writeFile(c.file, c.after);
+  }
+}
+
+export function formatPlan(plan, dir, { write = false } = {}) {
+  const lines = [];
+  lines.push(`OmniaCSS setup for ${dir}`);
+  lines.push(`Detected: ${plan.detected.tailwind ? "Tailwind " + plan.detected.packages.join(", ") : "no Tailwind package"}; vite: ${plan.detected.vite.join(", ") || "-"}; postcss: ${plan.detected.postcss.join(", ") || "-"}; css: ${plan.detected.css.join(", ") || "-"}; config: ${plan.detected.config || "-"}`);
+  lines.push("");
+  for (const c of plan.changes) {
+    lines.push(`${write ? "Updated" : "Would update"} ${path.relative(dir, c.file) || c.file}  (${c.note})`);
+    const diff = diffLines(c.before, c.after);
+    for (const l of diff.slice(0, 40)) lines.push("    " + l);
+    if (diff.length > 40) lines.push(`    ... ${diff.length - 40} more lines`);
+  }
+  if (plan.notes.length) { lines.push("", "Notes:"); for (const n of plan.notes) lines.push("  - " + n); }
+  lines.push("", write ? "Next:" : "Dry run only. Re-run with --write to apply. Then:");
+  for (const c of plan.commands) lines.push("  " + c);
+  return lines.join("\n");
+}