@birdycom/omniacss-migrate 0.12.1 → 0.12.2

package/README.md

@@ -51,7 +51,7 @@ export default { plugins: [omniaMigrate({ content: ["resources/views/**/*.blade.
 - Replaces `@import "@birdycom/omniacss-migrate"` / `@import "tailwindcss"` / `@tailwind base|components|utilities` with Omnia core (tokens + the Omnia classes you use), a small base reset and the compat CSS for the classes it finds in your content.
 - Expands `@apply` (with variants, `!important`, and your own classes), `theme(colors.red.500)`, `--spacing(4)`, `@theme`, `@custom-variant`, `@variant`, `@source`, `@source inline("…")`; ignores `@plugin` and `@config`.
 - Reads `tailwind.config.{js,cjs,mjs}` (`darkMode`, `theme.colors`/`extend.colors`, `fontFamily`, `borderRadius`, `spacing`, `boxShadow`, `screens`, `container`, `prefix`, `important`) and your `@theme` blocks.
-- Output is wrapped in cascade layers `omnia, theme, base, components, utilities`.
+- Output is wrapped in cascade layers `omnia, theme, base, components, utilities`: Omnia's reset and tokens lowest; the Omnia classes (for example what the codemod wrote) and the Tailwind-style names together in `utilities`, sorted the Tailwind way (variants after the base class, shorthands before longhands, the class with more properties first). So an Omnia class beats every reset and your own `@layer components`, and wins or loses against a Tailwind-style class in the same `class` exactly as before the codemod.
 
 Class coverage: layout, flex/grid, spacing, sizing, typography, colors (text, bg, border, ring, outline, fill, stroke, divide, accent, caret, decoration, gradients `from-`/`via-`/`to-`), borders, radius, shadow, ring, opacity, filters and backdrop filters, transitions, animations, transforms, display, position, z-index, overflow, cursor, scroll snap, `tailwindcss-animate` classes, arbitrary values (`w-[37px]`, `bg-(--brand)`, `[mask-type:luminance]`), opacity modifiers (`bg-red-500/50`), negatives (`-mt-2`), `!important`, and variants `hover: focus: active: disabled: first: odd: before: after: placeholder: file: marker: selection:`, `sm: md: lg: xl: 2xl: max-md: min-[…]:`, `@md:` container queries, `dark:`, `group-*`, `peer-*`, `data-[…]:`, `aria-*:`, `has-[…]:`, `not-*`, `in-*`, `supports-[…]:`, `*:`, arbitrary variants `[&>svg]:`, `motion-safe:`, `print:`, `rtl:`.
 
@@ -82,7 +82,7 @@ omniacss-migrate css "md:hover:bg-red-500/50"  print the CSS for one class
 
 ## Codemod (optional)
 
-`codemod` rewrites `class`/`className`/`cn()`/`cva()` strings to **native** OmniaCSS names when an Omnia class has exactly the same declarations (for example `items-center` becomes `align-items-center`, `p-4` becomes `p-1`). Everything else is left alone and listed. After `--write` the file `omniacss-migrate.manifest.json` tells the compat layer which names are now native, so `p-1` (Omnia, `1rem`) is never confused with the old `p-1` (`0.25rem`). Run it over the whole project, not a single folder.
+`codemod` rewrites `class`/`className`/`cn()`/`cva()` strings to **native** OmniaCSS names when an Omnia class has exactly the same declarations (for example `items-center` becomes `align-items-center`, `p-4` becomes `p-1`). Everything else is left alone and listed. After `--write` the file `omniacss-migrate.manifest.json` tells the compat layer which names are now native, so `p-1` (Omnia, `1rem`) is never confused with the old `p-1` (`0.25rem`). Run it over the whole project, not a single folder. Tests and scripts (`tests/`, `scripts/`, `*.test.*`, `*.spec.*` …) are skipped and listed, because they often assert class names as data; add `--include-tests` to rewrite them too.
 
 ## From Bootstrap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@birdycom/omniacss-migrate",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Switch a Laravel / Vue / React project from Tailwind CSS to OmniaCSS and keep your class names (PostCSS + Vite plugin, scan, setup, codemod), or convert a Bootstrap 3/4/5 site to OmniaCSS + OmniaUI.",
   "type": "module",
   "license": "MIT",
@@ -54,7 +54,7 @@
     "build:colors": "node scripts/build-color-map.mjs"
   },
   "dependencies": {
-    "@birdycom/omniacss": "^0.12.1",
+    "@birdycom/omniacss": "^0.12.2",
     "postcss": "^8.5.3"
   },
   "publishConfig": {

package/src/cli.mjs

@@ -26,6 +26,7 @@ Bootstrap 3/4/5 -> OmniaCSS + OmniaUI
 
 Options
   --write               apply changes (setup, codemod)
+  --include-tests       (codemod) also rewrite tests/, scripts/, *.test.* and *.spec.* files (skipped by default)
   --top <n>             rows in the unsupported list (scan, codemod; default 40)
   --json                machine readable output (scan)
   --breakpoints <omnia|tailwind>   sm/md/lg values (default omnia)
@@ -44,7 +45,7 @@ function parse(args) {
   options: {
     write: { type: "boolean" }, top: { type: "string" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" },
     breakpoints: { type: "string" }, dark: { type: "string" }, tailwind: { type: "string" }, "keep-brand-colors": { type: "boolean" },
-    content: { type: "string", short: "c", multiple: true }, output: { type: "string", short: "o" }, backup: { type: "boolean" },
+    content: { type: "string", short: "c", multiple: true }, output: { type: "string", short: "o" }, backup: { type: "boolean" }, "include-tests": { type: "boolean" },
     bs: { type: "string" }, compat: { type: "string" }, "omnia-href": { type: "string" }, "omniaui-href": { type: "string" }, "compat-href": { type: "string" },
   },
   });
@@ -102,7 +103,7 @@ export async function run(args = process.argv.slice(2)) {
 
   if (command === "codemod") {
     const { ctx } = await loadProject(dir, { ...ctxOptions(), breakpoints: values.breakpoints || "omnia" });
-    const report = await runCodemod(dir, { ctx, write: !!values.write, cwd: dir });
+    const report = await runCodemod(dir, { ctx, write: !!values.write, cwd: dir, includeTests: !!values["include-tests"] });
     console.log(formatCodemod(report, { top }));
     return;
   }

package/src/codemod.mjs

@@ -11,6 +11,11 @@ import { loadOmniaIndex, nativeFor } from "./native.mjs";
 
 export const MANIFEST = "omniacss-migrate.manifest.json";
 
+// Tests and scripts often assert or build class names as data: rewriting them breaks the tests. Skipped unless asked.
+const TEST_DIRS = /[\\/](tests?|__tests__|specs?|e2e|cypress|playwright|scripts)[\\/]/i;
+const TEST_FILES = /\.(test|spec|cy)\.[cm]?[jt]sx?$|Test\.php$/;
+const isTestOrScript = (file, dir) => TEST_DIRS.test(path.sep + path.relative(dir, file)) || TEST_FILES.test(file);
+
 /**
  * @param {string} dir
  * @param {{ ctx: object, write?: boolean, extensions?: string[], cwd?: string }} o
@@ -21,8 +26,10 @@ export async function runCodemod(dir, o) {
   const kind = makeKind(ctx);
   const memo = new Map();
   const map = (t) => { if (!memo.has(t)) memo.set(t, nativeFor(t, ctx, index)); return memo.get(t); };
-  const files = await walk(dir, { extensions: o.extensions || DEFAULT_EXTENSIONS });
-  const report = { dir, write, files: [], total: 0, rewritten: 0, unchanged: 0, leftovers: new Map(), collisions: new Map(), mapping: new Map() };
+  const all = await walk(dir, { extensions: o.extensions || DEFAULT_EXTENSIONS });
+  const skipped = o.includeTests ? [] : all.filter((f) => isTestOrScript(f, dir));
+  const files = o.includeTests ? all : all.filter((f) => !isTestOrScript(f, dir));
+  const report = { dir, write, files: [], skipped, total: 0, rewritten: 0, unchanged: 0, leftovers: new Map(), collisions: new Map(), mapping: new Map() };
   for (const file of files) {
     let text;
     try { text = await fs.readFile(file, "utf8"); } catch { continue; }
@@ -71,6 +78,11 @@ export function formatCodemod(r, { top = 25 } = {}) {
   lines.push(`${r.write ? "Rewrote" : "Dry run, would rewrite"} ${r.rewritten} of ${r.total} class occurrences (${pct}%) in ${r.files.length} files under ${r.dir}`);
   for (const f of r.files.slice(0, 15)) lines.push(`  ${f.file}  (${f.changes})  e.g. ${f.sample.slice(0, 3).join(", ")}`);
   if (r.files.length > 15) lines.push(`  ... and ${r.files.length - 15} more files`);
+  if (r.skipped?.length) {
+    lines.push("", `Skipped ${r.skipped.length} test and script files (tests/, scripts/, *.test.*, *.spec.* …); add --include-tests to rewrite them too:`);
+    for (const f of r.skipped.slice(0, 8)) lines.push(`  ${path.relative(r.dir, f)}`);
+    if (r.skipped.length > 8) lines.push(`  ... and ${r.skipped.length - 8} more`);
+  }
   const left = [...r.leftovers.entries()].sort((a, b) => b[1] - a[1]);
   lines.push("", `Left as they are (no 1:1 native class): ${left.reduce((n, [, c]) => n + c, 0)} occurrences, ${left.length} unique`);
   for (const [t, n] of left.slice(0, top)) lines.push(`  ${String(n).padStart(5)}  ${t}${r.collisions.has(t) ? "   (name exists in OmniaCSS with different meaning)" : ""}`);

package/src/core.mjs

@@ -6,6 +6,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import postcss from "postcss";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 let enginePromise;
@@ -42,9 +43,16 @@ export function omniaClassNames(full) {
  * Omnia core CSS for a project: tokens (every var(--color-*) the compat output uses) plus the Omnia-native
  * classes found in the content. Classes the compat layer resolves are excluded, so a Tailwind-style `p-4`
  * never collides with Omnia's own `p-4`.
- * @param {{ candidates: Set<string>, compatCss: string, exclude: Set<string>, cwd?: string, layer?: string|false, mode?: true|"tokens" }} o
+ *
+ * The result comes in two parts, so each can sit in its own cascade layer:
+ * - `base`: what styles elements, not classes (Omnia's reset, tokens, @keyframes, @property, @font-face);
+ * - `classes`: the rules of the Omnia classes. These are utilities: after the codemod they replace Tailwind-style
+ *   classes, so they sort in with those (see nativeRules in postcss.mjs) and beat every reset, as those classes did.
+ * `used` is the set of Omnia class names that were kept.
+ * @param {{ candidates: Set<string>, compatCss: string, exclude: Set<string>, cwd?: string, mode?: true|"tokens" }} o
+ * @returns {Promise<{ base: string, classes: string, used: Set<string> }>}
  */
-export async function buildCoreCss({ candidates, compatCss, exclude, cwd, layer = "omnia", mode = true }) {
+export async function buildCoreCss({ candidates, compatCss, exclude, cwd, mode = true }) {
   const engine = await loadEngine(cwd);
   const full = mode === true ? await engine.loadFullCss() : await fs.readFile(path.join(engine.DIST, "oc-colors.css"), "utf8");
   const set = new Set();
@@ -52,12 +60,41 @@ export async function buildCoreCss({ candidates, compatCss, exclude, cwd, layer
     const known = omniaClassNames(full);
     for (const c of candidates) if (known.has(c) && !exclude.has(c)) set.add(c);
   }
-  const key = `${layer}|${mode}|${hash(compatCss)}|${[...set].sort().join(" ")}`;
+  const key = `${mode}|${hash(compatCss)}|${[...set].sort().join(" ")}`;
   if (cache.has(key)) return cache.get(key);
-  const css = engine.generate(full, set, { layer, referencedBy: [compatCss] });
+  const parts = { ...splitByClass(engine.generate(full, set, { layer: false, referencedBy: [compatCss] })), used: set };
   cache.clear();
-  cache.set(key, css);
-  return css;
+  cache.set(key, parts);
+  return parts;
+}
+
+/** A selector that targets a class (`.p-1`, `a.link`, `:where(.dark) .x`); attribute values do not count. */
+const HAS_CLASS = (selector) => /\.(?:[A-Za-z_-]|\\)/.test(selector.replace(/\[[^\]]*\]/g, "").replace(/"[^"]*"|'[^']*'/g, ""));
+
+/** Splits generated CSS into the element/global part and the class part, keeping the at-rules around each rule. */
+function splitByClass(css) {
+  const root = postcss.parse(css);
+  const base = root.clone();
+  const classes = root.clone();
+  base.walkRules((rule) => { if (!inKeyframes(rule) && HAS_CLASS(rule.selector)) rule.remove(); });
+  classes.walkRules((rule) => { if (inKeyframes(rule) || !HAS_CLASS(rule.selector)) rule.remove(); });
+  // Only element-free at-rules (@keyframes, @property, @font-face …) belong to the base part.
+  classes.walkAtRules((at) => { if (/^(keyframes|-\w+-keyframes|property|font-face|font-feature-values|counter-style|import|charset)$/.test(at.name)) at.remove(); });
+  for (const part of [base, classes]) pruneEmpty(part);
+  return { base: base.toString().trim(), classes: classes.toString().trim() };
+}
+
+const inKeyframes = (node) => { for (let p = node.parent; p; p = p.parent) if (p.type === "atrule" && /keyframes$/.test(p.name)) return true; return false; };
+
+/** Removes at-rules left without rules (innermost first), keeping statement at-rules such as `@layer a, b;`. */
+function pruneEmpty(root) {
+  let again = true;
+  while (again) {
+    again = false;
+    root.walkAtRules((at) => {
+      if (at.nodes && !at.nodes.some((n) => n.type !== "comment")) { at.remove(); again = true; }
+    });
+  }
 }
 
 function hash(s) {

package/src/postcss.mjs

@@ -12,14 +12,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import postcss from "postcss";
-import { createContext, resolveToken, serialize } from "./resolve.mjs";
+import { createContext, resolveToken, serialize, propRank } from "./resolve.mjs";
 import { KEYFRAMES } from "./utilities.mjs";
 import { extractTokens } from "./extract.mjs";
 import { loadProject, parseThemeBlocks } from "./project.mjs";
 import { preflight } from "./preflight.mjs";
 import { buildCoreCss } from "./core.mjs";
 import { COLOR_MAP } from "./values.mjs";
-import { applyVariant } from "./variants.mjs";
+import { applyVariant, splitTop } from "./variants.mjs";
 
 // `@import "tailwindcss"`, or the same entry under our own name, so a project can drop every Tailwind mention.
 const TW_IMPORT = /^["'](?:tailwindcss|@birdycom\/omniacss-migrate)(?:\/(theme|preflight|utilities|base|components)(?:\.css)?)?["']/;
@@ -107,7 +107,8 @@ function withTheme(ctx, extra, patch = {}) {
  * @param {string} [options.cwd]
  * @param {true|"tokens"|false} [options.core=true]  true: Omnia core on demand; "tokens": only color tokens + base; false: you load Omnia yourself
  * @param {boolean} [options.preflight=true]   include the base reset
- * @param {boolean} [options.layers=true]      wrap output in cascade layers (omnia, theme, base, components, utilities)
+ * @param {boolean} [options.layers=true]      wrap output in cascade layers (omnia, theme, base, components, utilities):
+ *   Omnia's reset and tokens lowest; the Omnia classes and the Tailwind-style names together in utilities, sorted the Tailwind way
  * @param {3|4} [options.tailwind]             naming flavor (default: detected from package.json / CSS)
  * @param {"class"|"media"} [options.darkMode]
  * @param {"omnia"|"tailwind"} [options.breakpoints="omnia"]
@@ -157,7 +158,7 @@ export default function omniaMigrate(options = {}) {
       const ctx = withTheme(baseCtx, themeDecls.map(([k]) => k), { ...patch, customVariants, ...(options.important ? { important: true } : {}) });
 
       // --- content ---------------------------------------------------------------------------------------------
-      let compatCss = "", exclude = new Set(), candidates = new Set(), files = [];
+      let compatCss = "", exclude = new Set(), candidates = new Set(), files = [], resolved = [];
       if (hasEntry) {
         const globs = [];
         for (const at of sources) {
@@ -176,7 +177,6 @@ export default function omniaMigrate(options = {}) {
         for (const t of collected.tokens) candidates.add(t);
         for (const t of options.safelist || []) candidates.add(t);
 
-        const resolved = [];
         const manifest = options.manifest === false ? {} : JSON.parse(await fs.readFile(path.join(cwd, "omniacss-migrate.manifest.json"), "utf8").catch(() => "{}"));
         const native = new Set(manifest.native || []);
         for (const t of candidates) {
@@ -191,12 +191,16 @@ export default function omniaMigrate(options = {}) {
       const layers = options.layers !== false;
       const wrap = (name, css) => (layers && css.trim() ? `@layer ${name} {\n${css}\n}` : css);
       const pieces = {};
+      // omnia (Omnia's reset + tokens) < theme < base (compat preflight) < components < utilities. The Omnia classes
+      // (e.g. what the codemod wrote) share `utilities` with the Tailwind-style names, sorted together the Tailwind way,
+      // so an Omnia class beats every reset and wins or loses against a compat class exactly as before the codemod.
       pieces.order = layers ? "@layer omnia, theme, base, components, utilities;" : "";
       const themeBody = themeDecls.map(([k, v]) => `  ${k}: ${v};`).join("\n");
       pieces.theme = wrap("theme", (themeBody ? `:root, :host {\n${themeBody}\n}\n` : "") + keyframes.join("\n"));
       pieces.preflight = options.preflight === false ? "" : wrap("base", preflight({ borderColor: ctx.v4 ? "currentColor" : `var(${COLOR_MAP["gray-200"]})` }));
-      pieces.core = options.core === false ? "" : await buildCoreCss({ candidates, compatCss, exclude, cwd, layer: layers ? "omnia" : false, mode: options.core === "tokens" ? "tokens" : true });
-      pieces.utilities = wrap("utilities", compatCss);
+      const core = options.core === false ? { base: "", classes: "", used: new Set() } : await buildCoreCss({ candidates, compatCss, exclude, cwd, mode: options.core === "tokens" ? "tokens" : true });
+      pieces.core = wrap("omnia", core.base);
+      pieces.utilities = wrap("utilities", core.classes ? serialize([...resolved, ...nativeRules(core.classes, core.used, ctx)]) : compatCss);
       const all = [pieces.order, pieces.theme, pieces.preflight, pieces.core, pieces.utilities];
       // `from`: the stylesheet being built, so Vite resolves url() in the generated CSS against it (no "did not pass from" warning).
       const mk = (css) => postcss.parse(css, { from: result.opts.from }).nodes;
@@ -246,11 +250,48 @@ export default function omniaMigrate(options = {}) {
       root.walkDecls((decl) => { const v = replaceThemeFunctions(decl.value, ctx); if (v !== decl.value) decl.value = v; });
 
       for (const file of files) result.messages.push({ type: "dependency", plugin: "omniacss-migrate", file: path.resolve(file), parent: result.opts.from });
+
+      // Anything still here was not understood: the page would silently miss its tokens and classes.
+      root.walkAtRules((at) => {
+        if ((at.name === "import" && TW_IMPORT.test(at.params.trim())) || at.name === "theme" || at.name === "tailwind") {
+          at.warn(result, `omniacss-migrate left "@${at.name} ${at.params}" unprocessed. If you just updated @birdycom/omniacss-migrate, restart the dev server.`);
+        }
+      });
     },
   };
 }
 omniaMigrate.postcss = true;
 
+/**
+ * The Omnia class rules as resolved tokens, so serialize() sorts them in with the compat classes: the variant rank
+ * comes from the class's own prefixes (`hover:`, `md:` …), the property rank from its first declaration.
+ * @param {string} css   the class part of the Omnia core output
+ * @param {Set<string>} used  Omnia class names in it (to find a rule's own class among the ones in its selector)
+ */
+function nativeRules(css, used, ctx) {
+  const out = [];
+  postcss.parse(css).walkRules((rule) => {
+    const decls = [];
+    rule.each((n) => { if (n.type === "decl") decls.push([n.prop, n.important ? `${n.value} !important` : n.value]); });
+    if (!decls.length) return;
+    const media = [];
+    for (let p = rule.parent; p && p.type === "atrule"; p = p.parent) media.unshift(`@${p.name} ${p.params}`.trim());
+    const classes = [...rule.selector.matchAll(/\.((?:\\.|[A-Za-z0-9_-])+)/g)].map((m) => m[1].replace(/\\(.)/g, "$1"));
+    const token = classes.find((c) => used.has(c)) || classes.at(-1) || rule.selector;
+    out.push({ token, rules: [{ selectors: rule.selectors, media, decls, rank: variantRank(token, ctx), urank: propRank(decls[0][0]) }], keyframes: [] });
+  });
+  return out;
+}
+
+/** Cascade rank of a class's variant prefixes, as the compat layer ranks them (unknown Omnia-only prefixes go late). */
+function variantRank(token, ctx) {
+  const parts = splitTop(token, ":");
+  parts.pop();
+  const st = { sels: ["&"], media: [], prelude: [], rank: 0 };
+  for (let i = parts.length - 1; i >= 0; i--) if (!applyVariant(parts[i], st, ctx)) st.rank += 15000;
+  return st.rank;
+}
+
 function expandUtility(at) {
   if (/--value|--modifier/.test(at.toString())) { at.remove(); return; }
   const rule = postcss.rule({ selector: `.${at.params.trim()}` });

package/src/resolve.mjs

@@ -123,7 +123,7 @@ function containerRule(ctx) {
 
 // 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) {
+export 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;
@@ -178,7 +178,9 @@ export function serialize(resolved) {
     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));
+  // Like Tailwind: variants after the base class, shorthands before longhands, then the class that sets more
+  // properties first (so `leading-*` overrides the line-height of `text-sm`), then by name.
+  rules.sort((a, b) => a.rank - b.rank || a.urank - b.urank || propCount(b) - propCount(a) || (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]);
@@ -203,6 +205,9 @@ export function serialize(resolved) {
   return out.join("\n");
 }
 
+/** Number of real (not custom) properties a rule sets. */
+const propCount = (rule) => new Set(rule.decls.map(([k]) => k).filter((k) => !k.startsWith("--"))).size;
+
 /** Resolve many tokens and report what could not be resolved. */
 export function compileTokens(tokens, ctx) {
   const resolved = [], unsupported = [];

package/src/vite.mjs

@@ -49,9 +49,24 @@ async function loadExistingPlugins(root) {
   return out;
 }
 
+// The version this process loaded. A running dev server keeps it after `npm install` brings a newer one.
+const OWN_MANIFEST = new URL("../package.json", import.meta.url);
+const LOADED_VERSION = JSON.parse(fs.readFileSync(OWN_MANIFEST, "utf8")).version;
+
+/** The version now on disk when it differs from the loaded one (read again only when package.json changed). */
+let seen = { mtime: 0, version: LOADED_VERSION };
+function updatedVersion() {
+  try {
+    const mtime = fs.statSync(OWN_MANIFEST).mtimeMs;
+    if (mtime !== seen.mtime) seen = { mtime, version: JSON.parse(fs.readFileSync(OWN_MANIFEST, "utf8")).version };
+  } catch { return null; }
+  return seen.version !== LOADED_VERSION ? seen.version : null;
+}
+
 /** @param {Parameters<typeof omniaMigratePostcss>[0]} [options] */
 export default function omniaMigrate(options = {}) {
   let root = process.cwd();
+  let warnedStale = false;
   return {
     name: "omniacss-migrate",
     enforce: "pre",
@@ -61,8 +76,15 @@ export default function omniaMigrate(options = {}) {
       const file = id.split("?")[0];
       if (!/\.(css|pcss|postcss)$/.test(file)) return null;
       if (!/@import\s+["'](?:tailwindcss|@birdycom\/omniacss-migrate)|@tailwind\s+\w+|@apply\s|@theme\b/.test(code)) return null;
+      // Vite does not reload a plugin whose package changed underneath it; the old one may not understand the CSS.
+      const newer = !warnedStale && updatedVersion();
+      if (newer) {
+        warnedStale = true;
+        this.warn(`@birdycom/omniacss-migrate was updated from ${LOADED_VERSION} to ${newer} while this dev server runs. Restart the dev server: it still uses ${LOADED_VERSION}.`);
+      }
       const result = await postcss([omniaMigratePostcss({ cwd: root, ...options })]).process(code, { from: file, map: false });
       for (const m of result.messages) if (m.type === "dependency" && m.file) this.addWatchFile(m.file);
+      for (const w of result.warnings()) this.warn(w.text);
       return { code: result.css, map: null };
     },
     configResolved(config) {