pasika 0.10.130 → 0.10.132

package/dist/eslint/pasika/index.d.ts

@@ -121,6 +121,7 @@ declare const nextjsPackageJsonRules: {
 
 declare const tailwindRules: {
     "theme-reset": _eslint_css.CSSRuleDefinition;
+    "theme-mode": _eslint_css.CSSRuleDefinition;
     "color-role-usage": _eslint_css.CSSRuleDefinition;
     "root-variables": _eslint_css.CSSRuleDefinition;
     "apply-usage": _eslint_css.CSSRuleDefinition;
@@ -161,6 +162,7 @@ declare const pasikaPlugin: {
         "lint-setup": _eslint_json.JSONRuleDefinition;
         "vitest-coverage": _eslint_json.JSONRuleDefinition;
         "theme-reset": _eslint_css.CSSRuleDefinition;
+        "theme-mode": _eslint_css.CSSRuleDefinition;
         "color-role-usage": _eslint_css.CSSRuleDefinition;
         "root-variables": _eslint_css.CSSRuleDefinition;
         "apply-usage": _eslint_css.CSSRuleDefinition;

package/dist/eslint/pasika/index.js

@@ -2866,6 +2866,16 @@ var rulePairedExamplesRule = {
             node,
             message: `${String(incorrect.length)} Incorrect and ${String(correct.length)} Correct examples`
           });
+        } else {
+          const misplaced = exampleHeadings.find(
+            (heading, index) => !heading.text.startsWith(index % 2 === 0 ? "Incorrect" : "Correct")
+          );
+          if (misplaced) {
+            context.report({
+              node,
+              message: `Rule examples must alternate Incorrect then Correct; found "${misplaced.text}" at line ${String(misplaced.line)}.`
+            });
+          }
         }
       }
     };
@@ -10829,19 +10839,16 @@ var rootVariablesRule = {
             return;
           }
           const isConditional = conditional || currentNode.type === "Atrule" && currentNode.name !== "layer";
-          if (currentNode.type === "Rule") {
-            const selector = context.sourceCode.getText(currentNode.prelude).trim();
-            const isDefaultRoot = selector === ":root" && !isConditional;
-            if (!isDefaultRoot) {
-              for (const declaration of blockChildren2(currentNode)) {
-                if (declaration.type !== "Declaration") continue;
-                if (mirroredTokens.has(declaration.property)) continue;
-                if (!names.has(declaration.property) && !declaration.property.startsWith("--color-")) continue;
-                context.report({
-                  node: declaration,
-                  message: `Tailwind token "${declaration.property}" must not be redeclared outside @theme; map it through @theme inline to its same-named runtime variable instead.`
-                });
-              }
+          const isDefaultRoot = currentNode.type === "Rule" && context.sourceCode.getText(currentNode.prelude).trim() === ":root" && !isConditional;
+          if (currentNode.type === "Rule" && !isDefaultRoot || currentNode.type === "Atrule" && currentNode.name === "variant") {
+            for (const declaration of blockChildren2(currentNode)) {
+              if (declaration.type !== "Declaration") continue;
+              if (mirroredTokens.has(declaration.property)) continue;
+              if (!names.has(declaration.property) && !declaration.property.startsWith("--color-")) continue;
+              context.report({
+                node: declaration,
+                message: `Tailwind token "${declaration.property}" must not be redeclared outside @theme; map it through @theme inline to its same-named runtime variable instead.`
+              });
             }
           }
           const children = currentNode.type === "StyleSheet" ? currentNode.children : blockChildren2(currentNode);
@@ -10869,7 +10876,27 @@ var rootVariablesRule = {
 
 // eslint/rules/tailwind/stylesheet-ordering.ts
 import path73 from "path";
+import { generate as generate4 } from "@eslint/css-tree";
 var SECTION_ORDER = ["imports", "custom-variant", "root", "theme", "utility", "base styles", "keyframes"];
+var LATE_RESET_ERROR = "The global --*: initial theme reset must precede feature stylesheet imports, or it will erase their theme tokens.";
+function themeBody(node, source) {
+  if (node.type !== "Atrule" || node.name !== "theme" || !node.loc) return void 0;
+  const raw = source.slice(node.loc.start.offset, node.loc.end.offset);
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start < 0 || end <= start) return void 0;
+  return raw.slice(start + 1, end).replace(/\/\*[\s\S]*?\*\//gu, "").trim();
+}
+function containsThemeReset(body) {
+  return body !== void 0 && /(?:^|[;{])\s*--\*\s*:\s*initial\s*(?:;|$)/u.test(body);
+}
+function isStandaloneThemeReset(body) {
+  return body !== void 0 && /^--\*\s*:\s*initial\s*;?$/u.test(body);
+}
+function isTailwindImport(node) {
+  if (node.type !== "Atrule" || node.name !== "import" || !node.prelude) return false;
+  return /^["']tailwindcss["'](?:\s|$)/u.test(generate4(node.prelude).trim());
+}
 function scopesCustomProperties(node) {
   if (node.type === "Declaration") return node.property.startsWith("--");
   if (node.type === "Atrule" && !["media", "supports", "container"].includes(node.name)) return false;
@@ -10892,9 +10919,24 @@ var stylesheetOrderingRule = {
       "StyleSheet:exit"(node) {
         const sections = [];
         let index = 0;
+        let sawTailwindImport = false;
+        let sawFeatureImport = false;
+        let sawNonImport = false;
+        let sawEarlyReset = false;
         for (const child of node.children) {
+          const body = themeBody(child, context.sourceCode.text);
+          let isEarlyReset = false;
+          if (containsThemeReset(body) && sawFeatureImport) {
+            context.report({ node: child, message: LATE_RESET_ERROR });
+            return;
+          }
           if (child.type === "Atrule" && child.name === "import") {
             sections.push({ name: "imports", at: index });
+            if (isTailwindImport(child)) sawTailwindImport = true;
+            else sawFeatureImport = true;
+          } else if (isStandaloneThemeReset(body) && sawTailwindImport && !sawFeatureImport && !sawNonImport && !sawEarlyReset) {
+            sawEarlyReset = true;
+            isEarlyReset = true;
           } else if (child.type === "Atrule" && child.name === "custom-variant") {
             sections.push({ name: "custom-variant", at: index });
           } else if (child.type === "Atrule" && child.name === "theme") {
@@ -10912,6 +10954,9 @@ var stylesheetOrderingRule = {
           } else if (child.type === "Atrule" && scopesCustomProperties(child)) {
             sections.push({ name: "root", at: index });
           }
+          if (child.type !== "Comment" && !(child.type === "Atrule" && child.name === "import") && !isEarlyReset) {
+            sawNonImport = true;
+          }
           index += 1;
         }
         const firstAt = /* @__PURE__ */ new Map();
@@ -10952,14 +10997,135 @@ var stylesheetOrderingRule = {
   }
 };
 
-// eslint/rules/tailwind/theme-reset.ts
-import { existsSync as existsSync12 } from "fs";
+// eslint/rules/tailwind/theme-mode.ts
 import path74 from "path";
-import { generate as generate4, parse as parse7, toPlainObject as toPlainObject2 } from "@eslint/css-tree";
+import { generate as generate5 } from "@eslint/css-tree";
+var MODE_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+var MODE_REFERENCE = /(?:^|[^a-z0-9-])(?<name>[a-z][a-z0-9]*(?:-[a-z0-9]+)*):(?=[a-z[(])/gu;
+var MODE_ATTRIBUTE = /data-theme\s*=\s*["'](?<name>[a-z][a-z0-9]*(?:-[a-z0-9]+)*)["']/gu;
+var CUSTOM_REGISTRATION = /@custom-variant\s+(?<name>[a-z][a-z0-9-]*)\b(?<selector>[^;]*);/gu;
+var MODE_SELECTOR = /\[\s*data-theme\s*=\s*["']?(?<mode>[a-z][a-z0-9-]*)["']?\s*\]/u;
+var SELECTOR_OVERRIDE = "Use a data-theme @custom-variant for mode-specific styles; direct [data-theme] selectors are not allowed.";
+var CLASS_OVERRIDE = "Use the data-theme @custom-variant instead of a .dark CSS selector.";
+var SYSTEM_OVERRIDE = "Use data-theme with @custom-variant for mode styling; resolve system preferences in application code, not a prefers-color-scheme CSS media query.";
+var MODE_LOCATION = "Declare appearance-mode @custom-variant definitions in globals.css only.";
+var MISSING_CSS_VARIANT = (name) => `CSS @variant "${name}" requires a matching @custom-variant declaration in globals.css.`;
+function variantName(prelude) {
+  return /^(?<name>[a-z][a-z0-9-]*)\b/u.exec(prelude.trim())?.groups?.name;
+}
+function isModeVariant(name, prelude) {
+  return name === "dark" || name.startsWith("theme-") || /\[\s*data-theme\b/u.test(prelude);
+}
+function canonicalModePrelude(name, source) {
+  if (!MODE_NAME.test(name)) return false;
+  const normalized = source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/["']/gu, "").replace(/\s+/gu, "");
+  return normalized === `${name}(&:where([data-theme=${name}],[data-theme=${name}]*))`;
+}
+function registeredModes(source) {
+  const result = /* @__PURE__ */ new Set();
+  for (const match of source.replace(/\/\*[\s\S]*?\*\//gu, "").matchAll(CUSTOM_REGISTRATION)) {
+    const name = match.groups?.name;
+    if (name && isModeVariant(name, `${name}${match.groups?.selector ?? ""}`)) result.add(name);
+  }
+  return result;
+}
+var themeModeRule = {
+  meta: {
+    schema: [],
+    type: "problem",
+    docs: { description: "Require a single data-theme/@custom-variant strategy for appearance modes." }
+  },
+  create(context) {
+    const sourceRoot = sourceRootOf(context);
+    const current = path74.normalize(path74.resolve(context.filename));
+    const globalFile = path74.normalize(path74.join(sourceRoot, "app", "styles", "globals.css"));
+    if (path74.dirname(current) !== path74.dirname(globalFile)) return {};
+    const read = cachedTextReader();
+    return {
+      "StyleSheet:exit"(node) {
+        const registered = /* @__PURE__ */ new Set();
+        for (const variant of atrulesNamed(node, "custom-variant")) {
+          if (variant.type !== "Atrule") continue;
+          const prelude = variant.prelude ? generate5(variant.prelude) : "";
+          const name = variantName(prelude);
+          if (!name) continue;
+          if (!isModeVariant(name, prelude)) continue;
+          if (current !== globalFile) {
+            context.report({ node: variant, message: MODE_LOCATION });
+            continue;
+          }
+          if (!canonicalModePrelude(name, prelude)) {
+            const selected = MODE_SELECTOR.exec(prelude)?.groups?.mode;
+            context.report({
+              node: variant,
+              message: selected && selected !== name ? `Theme variant "${name}" must be named "${selected}" to match its data-theme selector.` : `Theme variant "${name}" must match both [data-theme="${name}"] and its descendants with &:where(...).`
+            });
+          }
+          if (registered.has(name)) {
+            context.report({ node: variant, message: `Theme variant "${name}" is already defined in globals.css.` });
+          }
+          registered.add(name);
+        }
+        const modeHints = /* @__PURE__ */ new Set();
+        for (const file of findFiles(sourceRoot, MODULE_EXTENSIONS4)) {
+          for (const match of read(file).matchAll(MODE_ATTRIBUTE)) {
+            if (match.groups?.name) modeHints.add(match.groups.name);
+          }
+        }
+        const globalRegistrations = current === globalFile ? registered : registeredModes(read(globalFile));
+        for (const variant of atrulesNamed(node, "variant")) {
+          if (variant.type !== "Atrule" || !variant.prelude) continue;
+          const name = variantName(generate5(variant.prelude));
+          if (name && (name === "dark" || name.startsWith("theme-") || globalRegistrations.has(name) || modeHints.has(name)) && !globalRegistrations.has(name)) {
+            context.report({ node: variant, message: MISSING_CSS_VARIANT(name) });
+          }
+        }
+        for (const rule of rules(node)) {
+          if (rule.type !== "Rule") continue;
+          const selector = generate5(rule.prelude);
+          if (/\[\s*data-theme(?:\s*[~|^$*]?=|\s*\])/u.test(selector)) {
+            context.report({ node: rule, message: SELECTOR_OVERRIDE });
+          } else if (/\.dark(?![\w-])/u.test(selector)) {
+            context.report({ node: rule, message: CLASS_OVERRIDE });
+          }
+        }
+        walkNodes(node, (child) => {
+          if (child.type !== "Atrule" || child.name !== "media" || !child.prelude) return;
+          if (/\bprefers-color-scheme\b/u.test(generate5(child.prelude))) {
+            context.report({ node: child, message: SYSTEM_OVERRIDE });
+          }
+        });
+        if (current !== globalFile) return;
+        const referenced = /* @__PURE__ */ new Set();
+        for (const file of findFiles(sourceRoot, MODULE_EXTENSIONS4)) {
+          for (const match of read(file).matchAll(MODE_REFERENCE)) {
+            const name = match.groups?.name;
+            if (!name) continue;
+            if (name === "dark" || name.startsWith("theme-") || registered.has(name) || modeHints.has(name)) {
+              referenced.add(name);
+            }
+          }
+        }
+        for (const name of referenced) {
+          if (!registered.has(name)) {
+            context.report({
+              node,
+              message: `Theme utility prefix "${name}:" requires a matching @custom-variant in globals.css; Tailwind's default media-based dark mode is not allowed.`
+            });
+          }
+        }
+      }
+    };
+  }
+};
+
+// eslint/rules/tailwind/theme-reset.ts
+import path75 from "path";
+import { generate as generate6 } from "@eslint/css-tree";
 function isThemeReset(node) {
   if (!node) return false;
-  if (node.type === "Declaration") return node.property === "--*" && generate4(node.value).trim() === "initial";
-  if (node.type === "Raw") return /--\*\s*:\s*initial\s*;/u.test(node.value);
+  if (node.type === "Declaration") return node.property === "--*" && generate6(node.value).trim() === "initial";
+  if (node.type === "Raw") return /(?:^|[;{])\s*--\*\s*:\s*initial\s*(?:;|$)/u.test(node.value);
   return false;
 }
 function hasThemeReset(node) {
@@ -10977,46 +11143,39 @@ var themeResetRule = {
     schema: [],
     type: "problem",
     docs: {
-      description: "Require the CSS tree to reset Tailwind's default theme with --*: initial."
+      description: "Require the default-theme reset in globals.css, never in feature stylesheets."
     }
   },
   create(context) {
     const sourceRoot = sourceRootOf(context);
-    const current = path74.normalize(path74.resolve(context.filename));
-    const entryPoint = path74.normalize(path74.join(sourceRoot, "app", "styles", "globals.css"));
-    if (current !== entryPoint) return {};
+    const current = path75.normalize(path75.resolve(context.filename));
+    const entryPoint = path75.normalize(path75.join(sourceRoot, "app", "styles", "globals.css"));
+    if (path75.dirname(current) !== path75.dirname(entryPoint)) return {};
     return {
       "StyleSheet:exit"(node) {
-        if (hasThemeReset(node)) return;
-        const textOf = cachedTextReader();
-        const seen = /* @__PURE__ */ new Set([current]);
-        const queue = [{ file: current, source: context.sourceCode.text }];
-        while (queue.length > 0) {
-          const from = queue.shift();
-          if (!from) continue;
-          for (const specifier of importedSpecifiers(from.source)) {
-            const target = resolveSpecifier2(from.file, specifier, sourceRoot);
-            if (!target || path74.extname(target) !== ".css") continue;
-            const filename = path74.normalize(target);
-            if (seen.has(filename) || !existsSync12(filename)) continue;
-            seen.add(filename);
-            const source = textOf(filename);
-            const parsed = toPlainObject2(parse7(source, { parseAtrulePrelude: false }));
-            if (parsed.type === "StyleSheet" && hasThemeReset(parsed)) return;
-            queue.push({ file: filename, source });
+        const hasReset = hasThemeReset(node);
+        if (current !== entryPoint) {
+          if (hasReset) {
+            context.report({
+              node,
+              message: "Only globals.css may reset Tailwind's default theme with --*: initial; remove it from feature stylesheets."
+            });
           }
+          return;
+        }
+        if (!hasReset) {
+          context.report({
+            node,
+            message: "globals.css must reset Tailwind's default theme with --*: initial inside @theme or @theme inline."
+          });
         }
-        context.report({
-          node,
-          message: "The global stylesheet must reset Tailwind's default theme with --*: initial inside an @theme block."
-        });
       }
     };
   }
 };
 
 // eslint/rules/tailwind/unique-css-definition.ts
-import path75 from "path";
+import path76 from "path";
 function ownershipKey(symbol) {
   if (symbol.kind === "selector") return void 0;
   if (symbol.kind === "root-variable" && symbol.scope !== "default") return void 0;
@@ -11048,7 +11207,7 @@ var uniqueCssDefinitionRule = {
   },
   create(context) {
     const sourceRoot = sourceRootOf(context);
-    const current = path75.normalize(path75.resolve(context.filename));
+    const current = path76.normalize(path76.resolve(context.filename));
     const cssFiles = findFiles(sourceRoot, CSS_EXTENSIONS);
     if (cssFiles.length === 0) return {};
     const textOf = cachedTextReader();
@@ -11056,7 +11215,7 @@ var uniqueCssDefinitionRule = {
       sourceRoot,
       css: cssFiles.map((file) => ({
         path: file,
-        content: path75.normalize(file) === current ? context.sourceCode.text : textOf(file)
+        content: path76.normalize(file) === current ? context.sourceCode.text : textOf(file)
       })),
       modules: [],
       includeReferences: false
@@ -11078,7 +11237,7 @@ var uniqueCssDefinitionRule = {
           if (!canonical) continue;
           for (const symbol of definitions.slice(1)) {
             if (symbol.file !== current) continue;
-            const message = symbol.file === canonical.file ? `${symbolLabel(symbol)} "${symbol.name}" is defined more than once in this CSS file; define it only once.` : `${symbolLabel(symbol)} "${symbol.name}" is also defined in ${path75.relative(sourceRoot, canonical.file)}; define it in only one CSS file.`;
+            const message = symbol.file === canonical.file ? `${symbolLabel(symbol)} "${symbol.name}" is defined more than once in this CSS file; define it only once.` : `${symbolLabel(symbol)} "${symbol.name}" is also defined in ${path76.relative(sourceRoot, canonical.file)}; define it in only one CSS file.`;
             context.report({
               node,
               loc: {
@@ -11095,7 +11254,7 @@ var uniqueCssDefinitionRule = {
 };
 
 // eslint/rules/tailwind/unique-css-token-value.ts
-import path76 from "path";
+import path77 from "path";
 function valueIdentity(value) {
   const text = value.trim();
   const hex = /^#(?<digits>[\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/iu.exec(text)?.groups?.digits;
@@ -11123,14 +11282,14 @@ var uniqueCssTokenValueRule = {
   },
   create(context) {
     const sourceRoot = sourceRootOf(context);
-    const current = path76.normalize(path76.resolve(context.filename));
+    const current = path77.normalize(path77.resolve(context.filename));
     const textOf = cachedTextReader();
     const cssFiles = findFiles(sourceRoot, CSS_EXTENSIONS);
     const graph = buildCssDependencyGraph({
       sourceRoot,
       css: cssFiles.map((file) => ({
         path: file,
-        content: path76.normalize(file) === current ? context.sourceCode.text : textOf(file)
+        content: path77.normalize(file) === current ? context.sourceCode.text : textOf(file)
       })),
       modules: [],
       includeReferences: false
@@ -11162,7 +11321,7 @@ var uniqueCssTokenValueRule = {
               start: { line: definition.line, column: 1 },
               end: { line: definition.line, column: 2 }
             },
-            message: `Token "${definition.name}" duplicates the value of "${original.name}" in ${path76.relative(
+            message: `Token "${definition.name}" duplicates the value of "${original.name}" in ${path77.relative(
               sourceRoot,
               original.file
             )}:${String(original.line)}; reuse one design token.`
@@ -11175,7 +11334,7 @@ var uniqueCssTokenValueRule = {
 
 // eslint/rules/tailwind/unused-utility.ts
 import { statSync as statSync5 } from "fs";
-import path77 from "path";
+import path78 from "path";
 var unusedUtilityRule = {
   meta: {
     schema: [],
@@ -11191,7 +11350,7 @@ var unusedUtilityRule = {
     } catch {
       return {};
     }
-    const current = path77.normalize(path77.resolve(context.filename));
+    const current = path78.normalize(path78.resolve(context.filename));
     const textOf = cachedTextReader();
     const cssFiles = findFiles(sourceRoot, CSS_EXTENSIONS);
     const moduleFiles = findFiles(sourceRoot, MODULE_EXTENSIONS4);
@@ -11199,7 +11358,7 @@ var unusedUtilityRule = {
       sourceRoot,
       css: cssFiles.map((file) => ({
         path: file,
-        content: path77.normalize(file) === current ? context.sourceCode.text : textOf(file)
+        content: path78.normalize(file) === current ? context.sourceCode.text : textOf(file)
       })),
       modules: moduleFiles.map((file) => ({ path: file, content: textOf(file) }))
     });
@@ -11221,8 +11380,8 @@ var unusedUtilityRule = {
 
 // eslint/rules/tailwind/utility-mapping.ts
 import { spawnSync } from "child_process";
-import { existsSync as existsSync13 } from "fs";
-import path78 from "path";
+import { existsSync as existsSync12 } from "fs";
+import path79 from "path";
 function applyOperationCount(utility, textOf) {
   let count = 0;
   for (const apply of atrulesNamed(utility, "apply")) {
@@ -11383,6 +11542,27 @@ function singleCssFunction(value) {
   const args = value.slice(match[0].length, -1).trim();
   return args ? { name, args } : void 0;
 }
+function gradientOnlyBackground(value) {
+  if (!value || /[;{}'"\\]/u.test(value)) return false;
+  const layers = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < value.length; index++) {
+    if (value[index] === "(") depth++;
+    if (value[index] === ")") depth--;
+    if (depth < 0) return false;
+    if (value[index] === "," && depth === 0) {
+      layers.push(value.slice(start, index).trim());
+      start = index + 1;
+    }
+  }
+  if (depth !== 0) return false;
+  layers.push(value.slice(start).trim());
+  return layers.every((layer) => {
+    const fn = singleCssFunction(layer);
+    return fn !== void 0 && /^(?:repeating-)?(?:linear|radial|conic)-gradient$/u.test(fn.name);
+  });
+}
 function boxShadowNamespace(value) {
   const layers = [];
   let depth = 0;
@@ -11445,7 +11625,9 @@ function themeCandidate(name, utilityText) {
   if (!cssValue) return void 0;
   const namedOperation = arbitraryApply?.groups?.prefix ? arbitraryApplyOperation(arbitraryApply.groups.prefix, cssValue) : void 0;
   if (arbitraryApply && !namedOperation) return void 0;
-  const property = arbitrary?.groups?.property ?? direct?.groups?.property ?? namedOperation?.property;
+  const declaredProperty = arbitrary?.groups?.property ?? direct?.groups?.property ?? namedOperation?.property;
+  const gradientShorthand = declaredProperty === "background" && gradientOnlyBackground(cssValue);
+  const property = gradientShorthand ? "background-image" : declaredProperty;
   const functionValue = property === "filter" || property === "backdrop-filter" ? singleCssFunction(cssValue) : void 0;
   const shadowNamespace = property === "box-shadow" ? boxShadowNamespace(cssValue) : void 0;
   if (property === "box-shadow" && !shadowNamespace) return void 0;
@@ -11481,7 +11663,8 @@ function themeCandidate(name, utilityText) {
     value,
     prefix: matched.prefix,
     namespace: matched.namespace,
-    probe: Boolean(arbitraryApply) || matched.property === "transition-property"
+    probe: Boolean(arbitraryApply) || matched.property === "transition-property",
+    gradientShorthand
   };
 }
 var builtInTextSizes = /* @__PURE__ */ new Set([
@@ -11520,6 +11703,9 @@ function isTypographySize(name) {
   return /^--text-(?!.*--)(?:[a-z0-9]+-)*[a-z0-9]+$/u.test(name);
 }
 function suggestedThemeToken(candidate) {
+  if (candidate.namespace === "background-image") {
+    return candidate.token.endsWith("-canvas") ? candidate.token : `${candidate.token}-canvas`;
+  }
   if (candidate.namespace !== "color") return candidate.token;
   let role = "edge";
   if (["bg", "fill"].includes(candidate.prefix)) {
@@ -11537,7 +11723,8 @@ function themeMigrationGuidance(candidate, utilityName) {
   const runtimeDependent = /\bvar\s*\(/iu.test(candidate.value);
   const action = runtimeDependent ? `only use a self-named @theme inline token "${token}" with an unconditional :root default and a detected runtime override; otherwise resolve the fixed value directly in @theme. ` : `define a direct @theme token "${token}" with value "${candidate.value}" rather than adding a :root bridge. `;
   const classGuidance = generatedClass === utilityName ? "Preserve the generated class name" : `Update class usages to "${generatedClass}"`;
-  return `${action}${classGuidance} and compare compiled CSS before removing the utility.`;
+  const resetWarning = candidate.gradientShorthand ? " Replacing the background shorthand with background-image stops resetting other background properties; verify cascade and rendering." : "";
+  return `${action}${classGuidance} and compare compiled CSS before removing the utility.${resetWarning}`;
 }
 var utilityMappingRule = {
   meta: {
@@ -11549,13 +11736,13 @@ var utilityMappingRule = {
   },
   create(context) {
     const sourceRoot = sourceRootOf(context);
-    const current = path78.normalize(path78.resolve(context.filename));
+    const current = path79.normalize(path79.resolve(context.filename));
     const textOf = cachedTextReader();
     const graph = buildCssDependencyGraph({
       sourceRoot,
       css: findFiles(sourceRoot, CSS_EXTENSIONS).map((file) => ({
         path: file,
-        content: path78.normalize(file) === current ? context.sourceCode.text : textOf(file)
+        content: path79.normalize(file) === current ? context.sourceCode.text : textOf(file)
       })),
       modules: [],
       includeReferences: false
@@ -11703,8 +11890,8 @@ var utilityMappingRule = {
         const generatorCandidates = utilities.map(
           (utility) => themeCandidate(preludeIdentifiers(utility)[0] ?? "unknown", context.sourceCode.getText(utility))
         ).filter((candidate) => Boolean(candidate && requiresGeneratorProbe(candidate)));
-        const physicalDir = path78.dirname(context.physicalFilename);
-        const tailwindCwd = path78.isAbsolute(physicalDir) && existsSync13(physicalDir) ? physicalDir : context.cwd;
+        const physicalDir = path79.dirname(context.physicalFilename);
+        const tailwindCwd = path79.isAbsolute(physicalDir) && existsSync12(physicalDir) ? physicalDir : context.cwd;
         const themeGenerators = themeSupportedGenerators(generatorCandidates, tailwindCwd);
         for (const utility of utilities) {
           const name = preludeIdentifiers(utility)[0] ?? "unknown";
@@ -11730,7 +11917,7 @@ var utilityMappingRule = {
           if (candidate && equivalent && nameCounts.get(name) === 1) {
             context.report({
               node: utility,
-              message: `Custom utility "${name}" duplicates theme-generated "${equivalent}" (${candidate.property}: ${candidate.value}); reuse "${equivalent}" instead.`
+              message: `Custom utility "${name}" duplicates theme-generated "${equivalent}" (${candidate.property}: ${candidate.value}); reuse "${equivalent}" instead.${candidate.gradientShorthand ? " Check background shorthand reset behavior before switching to background-image." : ""}`
             });
             continue;
           }
@@ -11746,7 +11933,7 @@ var utilityMappingRule = {
           if (!candidate.token) {
             context.report({
               node: utility,
-              message: `Custom utility "${name}" only maps ${candidate.property} (${candidate.value}); define an @theme token in the "--${candidate.namespace}-*" namespace and use its generated "${candidate.prefix}-*" class instead.${candidate.property === "box-shadow" ? " Compare compiled CSS and ring/inset-shadow composition before migration." : ""}`
+              message: `Custom utility "${name}" only maps ${candidate.property} (${candidate.value}); define ${candidate.gradientShorthand ? "a semantic" : "an"} @theme token in the "--${candidate.namespace}-*${candidate.gradientShorthand ? "-canvas" : ""}" namespace and use its generated "${candidate.prefix}-*" class instead.${candidate.property === "box-shadow" ? " Compare compiled CSS and ring/inset-shadow composition before migration." : ""}${candidate.gradientShorthand ? " Check background shorthand reset behavior before switching to background-image." : ""}`
             });
             continue;
           }
@@ -11813,10 +12000,9 @@ var utilityMappingRule = {
 
 // eslint/rules/tailwind/utility-name-parity.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { createHash } from "crypto";
-import { existsSync as existsSync14 } from "fs";
-import path79 from "path";
-import { generate as generate5, parse as parse8, toPlainObject as toPlainObject3 } from "@eslint/css-tree";
+import { existsSync as existsSync13 } from "fs";
+import path80 from "path";
+import { generate as generate7, parse as parse7, toPlainObject as toPlainObject2 } from "@eslint/css-tree";
 function numericPart(value) {
   const match = /^(?<negative>-?)(?<number>(?:\d+(?:\.\d+)?|\.\d+))(?<unit>%|px|rem|em|vw|vh|dvw|dvh|ch|fr|s|ms|deg|turn)?$/u.exec(
     value
@@ -11855,14 +12041,6 @@ function readableValue(value) {
   const slug = parts.join("-");
   return slug.length <= 70 ? slug : void 0;
 }
-function compoundValue(value) {
-  const readable = readableValue(value);
-  if (readable) return readable;
-  const candidate = /^(?<fn>[a-z][a-z0-9-]*)\(/iu.exec(value.trim())?.groups?.fn?.toLowerCase();
-  const hint = candidate?.endsWith("-") ? void 0 : candidate;
-  const digest = createHash("sha256").update(value.trim()).digest("hex").slice(0, 12);
-  return [hint, "hash", digest].filter(Boolean).join("-");
-}
 var TAILWIND_WORKER = String.raw`
 import { readFileSync } from "node:fs";
 import { compile } from "tailwindcss";
@@ -11916,7 +12094,7 @@ function compileApplies(applies, cwd) {
 }
 function compiledOperation(compiled, index) {
   if (!compiled.css) return void 0;
-  const sheet = toPlainObject3(parse8(compiled.css, { parseValue: false }));
+  const sheet = toPlainObject2(parse7(compiled.css, { parseValue: false }));
   const probe = rules(sheet).find((candidate) => selectorNames(candidate).includes(`pasika-probe-${String(index)}`));
   if (!probe) return void 0;
   const declarations = blockChildren2(probe).filter(
@@ -11930,13 +12108,14 @@ function compiledOperation(compiled, index) {
       (child) => child.type === "Declaration" && child.property === "--tw-shadow"
     );
     if (shadow?.type === "Declaration") {
-      return { property: "box-shadow", value: generate5(shadow.value).trim() };
+      return { property: "box-shadow", value: generate7(shadow.value).trim() };
     }
   }
-  return { property: declaration.property, value: generate5(declaration.value).trim() };
+  return { property: declaration.property, value: generate7(declaration.value).trim() };
 }
 function expectedName(operation) {
-  const value = compoundValue(operation.value);
+  const value = readableValue(operation.value);
+  if (!value) return void 0;
   const property = operation.property.replace(/^-+/u, "").replace(/^background-/u, "bg-");
   return `${property}-${value}`;
 }
@@ -11952,7 +12131,7 @@ var utilityNameParityRule = {
     schema: [],
     type: "problem",
     docs: {
-      description: "Require single-operation custom utilities to have deterministic property/value-derived names."
+      description: "Use property/value-derived names for readable values and semantic names for complex values."
     }
   },
   create(context) {
@@ -11965,8 +12144,8 @@ var utilityNameParityRule = {
           return apply ? [{ utility, name, apply }] : [];
         });
         if (candidates.length === 0) return;
-        const physicalDir = path79.dirname(context.physicalFilename);
-        const cwd = path79.isAbsolute(physicalDir) && existsSync14(physicalDir) ? physicalDir : context.cwd;
+        const physicalDir = path80.dirname(context.physicalFilename);
+        const cwd = path80.isAbsolute(physicalDir) && existsSync13(physicalDir) ? physicalDir : context.cwd;
         const compiled = compileApplies(
           candidates.map((candidate) => candidate.apply),
           cwd
@@ -11982,6 +12161,15 @@ var utilityNameParityRule = {
             continue;
           }
           const expected = expectedName(operation);
+          if (!expected) {
+            if (/-hash-[a-f0-9]{12}$/u.test(candidate.name)) {
+              context.report({
+                node: candidate.utility,
+                message: `Custom utility "${candidate.name}" uses an opaque hash for a complex ${operation.property} value; use a semantic name, or prefer a theme-generated utility where supported.`
+              });
+            }
+            continue;
+          }
           if (candidate.name === expected) continue;
           context.report({
             node: candidate.utility,
@@ -11996,6 +12184,7 @@ var utilityNameParityRule = {
 // eslint/rules/tailwind/index.ts
 var tailwindRules = {
   "theme-reset": themeResetRule,
+  "theme-mode": themeModeRule,
   "color-role-usage": colorRoleUsageRule,
   "root-variables": rootVariablesRule,
   "apply-usage": applyUsageRule,
@@ -12014,7 +12203,7 @@ var tailwindRules = {
 };
 
 // eslint/rules/type-extraction.ts
-import path80 from "path";
+import path81 from "path";
 var typeExtractionRule = {
   meta: {
     schema: [],
@@ -12025,7 +12214,7 @@ var typeExtractionRule = {
   },
   create(context) {
     const sourceRoot = sourceRootOf(context);
-    const file = path80.resolve(context.filename);
+    const file = path81.resolve(context.filename);
     const segments = segmentsOf(file, sourceRoot);
     if (segments.length === 0) return {};
     const index = getProjectIndex(sourceRoot);
@@ -12164,9 +12353,9 @@ var uiStateRule = {
 };
 
 // eslint/rules/unknown-utility.ts
-import { existsSync as existsSync15, readdirSync as readdirSync6, readFileSync as readFileSync15, statSync as statSync6 } from "fs";
+import { existsSync as existsSync14, readdirSync as readdirSync6, readFileSync as readFileSync15, statSync as statSync6 } from "fs";
 import { createRequire } from "module";
-import path81 from "path";
+import path82 from "path";
 var PREFIX_NAMESPACES = {
   bg: ["color", "background-image"],
   text: ["color", "text"],
@@ -12452,7 +12641,7 @@ function stylesheetFiles(dir) {
   }
   return entries.flatMap((entry) => {
     if (entry.startsWith(".") || entry === "node_modules") return [];
-    const entryPath = path81.join(dir, entry);
+    const entryPath = path82.join(dir, entry);
     let stats;
     try {
       stats = statSync6(entryPath);
@@ -12460,7 +12649,7 @@ function stylesheetFiles(dir) {
       return [];
     }
     if (stats.isDirectory()) return stylesheetFiles(entryPath);
-    return path81.extname(entry) === ".css" ? [entryPath] : [];
+    return path82.extname(entry) === ".css" ? [entryPath] : [];
   });
 }
 function packageNameOf(specifier) {
@@ -12471,24 +12660,24 @@ function packageNameOf(specifier) {
 function resolvePackageStylesheet(fromFile, specifier) {
   const packageName = packageNameOf(specifier);
   if (!packageName || packageName === "tailwindcss") return void 0;
-  let directory = path81.dirname(fromFile);
-  while (directory !== path81.dirname(directory)) {
-    const packageRoot = path81.join(directory, "node_modules", packageName);
-    const manifestPath = path81.join(packageRoot, "package.json");
-    if (existsSync15(manifestPath)) {
+  let directory = path82.dirname(fromFile);
+  while (directory !== path82.dirname(directory)) {
+    const packageRoot = path82.join(directory, "node_modules", packageName);
+    const manifestPath = path82.join(packageRoot, "package.json");
+    if (existsSync14(manifestPath)) {
       try {
         const manifest = readFileSync15(manifestPath, "utf8");
         const stylesheet = /"style"\s*:\s*"(?<file>[^"]+\.css)"/.exec(manifest)?.groups?.file;
         const main = /"main"\s*:\s*"(?<file>[^"]+\.css)"/.exec(manifest)?.groups?.file;
         const target = stylesheet ?? main;
         if (!target) return void 0;
-        const resolved = path81.resolve(packageRoot, target);
-        return existsSync15(resolved) ? resolved : void 0;
+        const resolved = path82.resolve(packageRoot, target);
+        return existsSync14(resolved) ? resolved : void 0;
       } catch {
         return void 0;
       }
     }
-    directory = path81.dirname(directory);
+    directory = path82.dirname(directory);
   }
   return void 0;
 }
@@ -12760,7 +12949,7 @@ var unknownUtilityRule = {
 };
 
 // eslint/rules/util-file-name.ts
-import path82 from "path";
+import path83 from "path";
 function toKebabCase2(value) {
   return value.replace(/(?<lower>[a-z0-9])(?<upper>[A-Z])/g, "$<lower>-$<upper>").replace(/(?<first>[A-Z])(?<rest>[A-Z][a-z])/g, "$<first>-$<rest>").toLowerCase();
 }
@@ -12773,7 +12962,7 @@ var utilFileNameRule = {
     }
   },
   create(context) {
-    const filename = path82.resolve(context.filename);
+    const filename = path83.resolve(context.filename);
     const segments = filename.replace(/\\/g, "/").split("/");
     if (!segments.includes("utils")) return {};
     let module;
@@ -12787,13 +12976,13 @@ var utilFileNameRule = {
     const functionName = functions[0]?.name;
     if (!functionName) return {};
     const expected = toKebabCase2(functionName);
-    const actual = path82.basename(filename, path82.extname(filename));
+    const actual = path83.basename(filename, path83.extname(filename));
     if (!expected || actual === expected) return {};
     return {
       Program(node) {
         context.report({
           node,
-          message: `A utility file exporting ${functionName} must be named ${expected}.${path82.extname(filename).slice(1)}.`
+          message: `A utility file exporting ${functionName} must be named ${expected}.${path83.extname(filename).slice(1)}.`
         });
       }
     };
@@ -12801,7 +12990,7 @@ var utilFileNameRule = {
 };
 
 // eslint/rules/value-extraction.ts
-import path83 from "path";
+import path84 from "path";
 var valueExtractionRule = {
   meta: {
     schema: [],
@@ -12812,7 +13001,7 @@ var valueExtractionRule = {
   },
   create(context) {
     const sourceRoot = sourceRootOf(context);
-    const file = path83.resolve(context.filename);
+    const file = path84.resolve(context.filename);
     const segments = segmentsOf(file, sourceRoot);
     if (segments.length === 0 || segments[0] !== "app") return {};
     const index = getProjectIndex(sourceRoot);
@@ -12833,8 +13022,8 @@ var valueExtractionRule = {
 };
 
 // eslint/rules/vulyk/tracked-docs.ts
-import { existsSync as existsSync16, readFileSync as readFileSync16 } from "fs";
-import path84 from "path";
+import { existsSync as existsSync15, readFileSync as readFileSync16 } from "fs";
+import path85 from "path";
 var PASIKA_REPO = "Bredansky/pasika";
 var BASE_REQUIRED_TRACKED_DOCS = [
   { name: "documentation-guide", path: "docs/documentation-guide" },
@@ -12867,9 +13056,9 @@ var trackedDocsRule = {
         if (!context.filename.endsWith("package.json")) return;
         const root = node.body;
         if (root.type !== "Object") return;
-        const projectRoot = path84.dirname(path84.resolve(context.filename));
-        const configPath = path84.join(projectRoot, "vulyk.config.ts");
-        if (!existsSync16(configPath)) {
+        const projectRoot = path85.dirname(path85.resolve(context.filename));
+        const configPath = path85.join(projectRoot, "vulyk.config.ts");
+        if (!existsSync15(configPath)) {
           context.report({
             node,
             message: "No vulyk.config.ts found. Run npx vulyk init to create one that tracks the framework's required tracked docs."
@@ -12893,8 +13082,8 @@ var trackedDocsRule = {
             });
           }
         }
-        const agentsPath = path84.join(projectRoot, "AGENTS.md");
-        if (!existsSync16(agentsPath)) {
+        const agentsPath = path85.join(projectRoot, "AGENTS.md");
+        if (!existsSync15(agentsPath)) {
           context.report({
             node,
             message: "No AGENTS.md found. Run npx vulyk agents to generate the agent file that routes to the tracked docs."
@@ -12993,7 +13182,7 @@ var withResponseHelperRule = {
 
 // eslint/rules/zirka-baseline.ts
 import fs7 from "fs";
-import path85 from "path";
+import path86 from "path";
 var ESLINT_CONFIG = /^eslint\.config\.(?:ts|mts|cts|js|mjs|cjs)$/;
 var PRETTIER_CONFIGS = [
   "prettier.config.mjs",
@@ -13012,10 +13201,10 @@ var zirkaBaselineRule = {
     }
   },
   create(context) {
-    const filename = path85.resolve(context.filename);
-    const basename = path85.basename(filename);
+    const filename = path86.resolve(context.filename);
+    const basename = path86.basename(filename);
     if (!ESLINT_CONFIG.test(basename)) return {};
-    const projectRoot = path85.dirname(filename);
+    const projectRoot = path86.dirname(filename);
     const report3 = (message) => {
       context.report({
         node: context.sourceCode.ast,
@@ -13030,7 +13219,7 @@ var zirkaBaselineRule = {
             'ESLint config must take its configuration from zirka (import { styleguide } from "zirka") instead of restating rules locally.'
           );
         }
-        const tsconfigPath = path85.join(projectRoot, "tsconfig.json");
+        const tsconfigPath = path86.join(projectRoot, "tsconfig.json");
         if (!fs7.existsSync(tsconfigPath)) {
           report3('No tsconfig.json found. Create one extending the zirka TypeScript base config ("zirka/typescript").');
         } else {
@@ -13048,13 +13237,13 @@ var zirkaBaselineRule = {
             report3('tsconfig.json must extend the zirka TypeScript base config ("zirka/typescript").');
           }
         }
-        const prettierConfigFile = PRETTIER_CONFIGS.find((name) => fs7.existsSync(path85.join(projectRoot, name)));
+        const prettierConfigFile = PRETTIER_CONFIGS.find((name) => fs7.existsSync(path86.join(projectRoot, name)));
         if (!prettierConfigFile) {
           report3(
             "No prettier config found. Create one that takes its configuration from zirka (styleguide({ prettier: true }).prettierConfig)."
           );
         } else {
-          const content = fs7.readFileSync(path85.join(projectRoot, prettierConfigFile), "utf8");
+          const content = fs7.readFileSync(path86.join(projectRoot, prettierConfigFile), "utf8");
           if (!content.includes("zirka")) {
             report3(
               "The prettier config must take its configuration from zirka (styleguide({ prettier: true }).prettierConfig) instead of restating it locally."
@@ -13390,7 +13579,7 @@ var tailwindStructureRules = {
   languageOptions: { tolerant: true },
   rules: Object.fromEntries(
     tailwindRuleIds.filter(
-      (id) => id !== "pasika/css-entry-point" && id !== "pasika/feature-css-placement" && id !== "pasika/unique-css-definition" && id !== "pasika/utility-mapping" && id !== "pasika/utility-name-parity" && id !== "pasika/no-utility-alias" && id !== "pasika/root-variables" && id !== "pasika/color-role-usage"
+      (id) => id !== "pasika/css-entry-point" && id !== "pasika/feature-css-placement" && id !== "pasika/unique-css-definition" && id !== "pasika/utility-mapping" && id !== "pasika/utility-name-parity" && id !== "pasika/no-utility-alias" && id !== "pasika/root-variables" && id !== "pasika/color-role-usage" && id !== "pasika/theme-mode"
     ).map((id) => [id, "error"])
   )
 };
@@ -13411,7 +13600,8 @@ var tailwindImportGraph = {
     "pasika/utility-name-parity": "error",
     "pasika/no-utility-alias": "error",
     "pasika/root-variables": "error",
-    "pasika/color-role-usage": "error"
+    "pasika/color-role-usage": "error",
+    "pasika/theme-mode": "error"
   }
 };
 var pasikaAppPackageJsonConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pasika",
-  "version": "0.10.130",
+  "version": "0.10.132",
   "description": "Reusable agent setup package",
   "repository": {
     "type": "git",