@salla.sa/twilight-components 2.14.537 → 2.14.539

package/dist/collection/plugins/build-base-css.js

@@ -0,0 +1,43 @@
+// Generates src/global/base-css.ts: the small always-loaded global utilities
+// (s-hidden, form classes, checkbox/toggle/scrollbar) used outside components.
+const fs = require('fs');
+const path = require('path');
+const tailwindcss = require('tailwindcss');
+const twPlugin = require('tailwindcss/plugin');
+const core = require('@salla.sa/twilight-tailwind-theme/plugin-core');
+const generatorGlobals = require('@salla.sa/twilight-tailwind-theme/generator-globals');
+const globalUtilities = require('@salla.sa/twilight-tailwind-theme/global-utilities');
+const tokens = require('@salla.sa/twilight-tailwind-theme/component-tokens');
+const postcss = require(require.resolve('postcss', {
+  paths: [path.dirname(require.resolve('tailwindcss/package.json'))],
+}));
+
+const names = new Set();
+for (const group of [...globalUtilities, generatorGlobals]) {
+  for (const key of Object.keys(group)) {
+    const m = key.match(/^\.([\w-]+)/); // leading class (pseudo/descendant keys count too)
+    if (m) names.add(m[1]);
+  }
+}
+
+const basePlugin = twPlugin((api) => {
+  core.handler(api);
+  api.addUtilities(generatorGlobals);
+}, core.config);
+
+(async () => {
+  const result = await postcss([tailwindcss({
+    important: false,
+    darkMode: 'class',
+    corePlugins: { preflight: false, outline: false },
+    content: [{ raw: '' }],
+    safelist: [...names],
+    theme: tokens,
+    plugins: [basePlugin],
+  })]).process('@tailwind utilities;', { from: undefined });
+
+  const css = result.css.replace(/\n\s*/g, ''); // values never span lines
+  const out = path.resolve(__dirname, '../global/base-css.ts');
+  fs.writeFileSync(out, `// GENERATED by src/plugins/build-base-css.js. Do not edit.\nexport const BASE_CSS = ${JSON.stringify(css)};\n`);
+  console.log('base-css.ts:', css.length, 'bytes');
+})();

package/dist/collection/plugins/css-coverage-check.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// CSS coverage REPORT - advisory, non-blocking. Lists every s-* class a component
+// renders whose rule lands in no chunk or base-css (a sibling that may be absent).
+// ALWAYS exits 0; it never gates a build. Runs PR-side only (build-for-testing.yaml)
+// to post a reference comment for the author, and is deliberately NOT in the release
+// workflow: coverage is a heuristic presence check, so blocking a release on it would
+// fail with no safe remediation. Run: node src/plugins/css-coverage-check.js [--json]
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const DIST_ESM = path.join(ROOT, 'dist', 'esm');
+const COMPONENTS_DIR = path.join(ROOT, 'src', 'components');
+const BASE_CSS_TS = path.join(ROOT, 'src', 'global', 'base-css.ts');
+// Snapshot: classes styled by the pre-split build / by a migrated theme.
+const BASELINE_JSON = path.join(__dirname, 'css-coverage-baseline.json');
+
+// Known-safe flags, each with the contract that makes it safe.
+const WHITELIST = [
+  { component: 'salla-loyalty', class: 's-button-solid', reason: 'only styles a loader child; the raw anchor has none' },
+  { component: 'salla-products-list', class: 's-product-card-fit-height', reason: 'default card loads the chunk; custom cards ship their own CSS' },
+  { component: 'salla-login-modal', class: 's-login-modal', reason: 'utilities emptied upstream; baseline rule from a stale published package' },
+];
+
+// ---------- helpers ----------
+
+const read = (p) => fs.readFileSync(p, 'utf8');
+const exists = (p) => fs.existsSync(p);
+
+// Unescape a JS double-quoted string body.
+function unescapeJsString(raw) {
+  try {
+    return JSON.parse('"' + raw + '"');
+  } catch {
+    return raw
+      .replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+      .replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\\\\/g, '\\');
+  }
+}
+
+// Class names appearing in CSS selectors (skips declaration bodies).
+function cssClasses(css) {
+  const classes = new Set();
+  let depth = 0;
+  let buf = '';
+  for (let i = 0; i < css.length; i++) {
+    const ch = css[i];
+    if (ch === '{') {
+      const sel = buf.trim();
+      // at-rule preludes carry no classes
+      if (sel && !sel.startsWith('@')) {
+        for (const m of sel.matchAll(/\.(-?[A-Za-z_][\w-]*)/g)) classes.add(m[1]);
+      }
+      buf = '';
+      depth++;
+    } else if (ch === '}') {
+      buf = '';
+      depth = Math.max(0, depth - 1);
+    } else {
+      buf += ch;
+    }
+  }
+  return classes;
+}
+
+// All `const fooCss = "..."` strings inside a built entry chunk.
+function chunkCssClasses(file) {
+  const src = read(file);
+  const classes = new Set();
+  for (const m of src.matchAll(/Css\s*=\s*"((?:[^"\\]|\\.)*)"/g)) {
+    for (const c of cssClasses(unescapeJsString(m[1]))) classes.add(c);
+  }
+  return classes;
+}
+
+// String literal bodies + template literal static chunks from a TS/TSX source.
+// Returns { literals: string[], dynamicPrefixes: string[] }.
+function extractLiterals(src) {
+  const literals = [];
+  const dynamicPrefixes = [];
+  let i = 0;
+  const n = src.length;
+  while (i < n) {
+    const ch = src[i];
+    if (ch === '/' && src[i + 1] === '/') { // line comment
+      while (i < n && src[i] !== '\n') i++;
+    } else if (ch === '/' && src[i + 1] === '*') { // block comment
+      i += 2;
+      while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++;
+      i += 2;
+    } else if (ch === "'" || ch === '"') {
+      const quote = ch;
+      let buf = '';
+      i++;
+      while (i < n && src[i] !== quote) {
+        if (src[i] === '\\') { buf += src[i + 1] ?? ''; i += 2; }
+        else buf += src[i++];
+      }
+      i++;
+      literals.push(buf);
+    } else if (ch === '`') {
+      i++;
+      let buf = '';
+      while (i < n) {
+        if (src[i] === '\\') { buf += src[i + 1] ?? ''; i += 2; continue; }
+        if (src[i] === '`') { i++; break; }
+        if (src[i] === '$' && src[i + 1] === '{') {
+          literals.push(buf);
+          const dyn = buf.match(/(?:^|[\s"'>])((?:s|salla)-[\w-]*)$/);
+          if (dyn) dynamicPrefixes.push(dyn[1]);
+          buf = '';
+          // scan the interpolation body too (classes live in ternaries)
+          i += 2;
+          const start = i;
+          let braces = 1;
+          while (i < n && braces > 0) {
+            if (src[i] === '{') braces++;
+            else if (src[i] === '}') braces--;
+            i++;
+          }
+          const inner = extractLiterals(src.slice(start, i - 1));
+          literals.push(...inner.literals);
+          dynamicPrefixes.push(...inner.dynamicPrefixes);
+          continue;
+        }
+        buf += src[i++];
+      }
+      literals.push(buf);
+    } else {
+      i++;
+    }
+  }
+  return { literals, dynamicPrefixes };
+}
+
+// Rendered s-* class tokens in one literal. Skips selector usage (.s-foo / #s-foo).
+function classTokens(literal) {
+  const out = [];
+  for (const m of literal.matchAll(/(?<![.#\w$-])s-[a-z][\w-]*/g)) out.push(m[0]);
+  return out;
+}
+
+// ---------- pass 1: ownership ----------
+
+function loadTagToBundle() {
+  const loader = read(path.join(DIST_ESM, 'loader.js'));
+  const m = loader.match(/JSON\.parse\("((?:[^"\\]|\\.)*)"\)/);
+  if (!m) throw new Error('Cannot find bundle map in dist/esm/loader.js');
+  const bundles = JSON.parse(unescapeJsString(m[1]));
+  const tagToBundle = new Map();
+  for (const [bundleName, cmps] of bundles) {
+    for (const cmp of cmps) tagToBundle.set(cmp[1], bundleName);
+  }
+  return tagToBundle;
+}
+
+function loadBaseCssClasses() {
+  const src = read(BASE_CSS_TS);
+  const m = src.match(/BASE_CSS\s*=\s*"((?:[^"\\]|\\.)*)"/);
+  if (!m) throw new Error('Cannot find BASE_CSS in base-css.ts');
+  return cssClasses(unescapeJsString(m[1]));
+}
+
+// Classes in selectors any utilities.json defines (plugin's mapping).
+function sdkDefinedClasses() {
+  const classes = new Set();
+  for (const dir of fs.readdirSync(COMPONENTS_DIR)) {
+    const p = path.join(COMPONENTS_DIR, dir, 'utilities.json');
+    if (!exists(p)) continue;
+    let json;
+    try { json = JSON.parse(read(p)); } catch { continue; }
+    const owner = dir.replace('salla-', '');
+    for (const [key, value] of Object.entries(json)) {
+      const selector = typeof value === 'string'
+        ? (key.startsWith('@at-root') ? key.replace('@at-root ', '') : `.s-${owner}-${key}`)
+        : key;
+      for (const m of selector.matchAll(/\.([\w-]+)/g)) classes.add(m[1]);
+    }
+  }
+  return classes;
+}
+
+// ---------- pass 2 + 3: usage & composition ----------
+
+// All non-test source files under a component dir, nested folders included.
+function walkSources(dirPath) {
+  const out = [];
+  for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+    const p = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      if (!/^tests?$/.test(entry.name)) out.push(...walkSources(p));
+    } else if (/\.(tsx|ts)$/.test(entry.name)
+      && !/\.(spec|e2e|d)\.tsx?$/.test(entry.name) && !/interface/i.test(entry.name)) {
+      out.push(p);
+    }
+  }
+  return out;
+}
+
+function scanComponents() {
+  const components = []; // { tag, dir, ownClasses(after), used:Set, dynamic:[], children:Set }
+  for (const dir of fs.readdirSync(COMPONENTS_DIR)) {
+    const dirPath = path.join(COMPONENTS_DIR, dir);
+    if (!fs.statSync(dirPath).isDirectory()) continue;
+    const tagFiles = [];
+    const sharedSrcs = [];
+    for (const f of walkSources(dirPath)) {
+      const src = read(f);
+      const tagMatch = src.match(/tag:\s*['"`]([\w-]+)['"`]/);
+      if (tagMatch) tagFiles.push({ tag: tagMatch[1], src });
+      else sharedSrcs.push(src);
+    }
+    for (const { tag, src } of tagFiles) {
+      const used = new Set();
+      const dynamic = [];
+      const children = new Set();
+      for (const body of [src, ...sharedSrcs]) {
+        const { literals, dynamicPrefixes } = extractLiterals(body);
+        for (const lit of literals) {
+          // template prefixes count as dynamic, not usage
+          for (const t of classTokens(lit)) if (!t.endsWith('-')) used.add(t);
+          // bare tag literals catch createElement(variable); skip import paths
+          if (!lit.includes('/')) {
+            for (const m of lit.matchAll(/(?<![.#\w-])salla-[a-z][\w-]*/g)) children.add(m[0]);
+          }
+        }
+        dynamic.push(...dynamicPrefixes);
+        for (const m of body.matchAll(/<(salla-[a-z][\w-]*)/g)) children.add(m[1]);
+      }
+      children.delete(tag);
+      components.push({ tag, dir, used, dynamic, children });
+    }
+  }
+  return components.sort((a, b) => a.tag.localeCompare(b.tag));
+}
+
+// ---------- pass 4: coverage ----------
+
+function main() {
+  const asJson = process.argv.includes('--json');
+
+  const tagToBundle = loadTagToBundle();
+  const baseClasses = loadBaseCssClasses();
+  const components = scanComponents();
+  const sdkDefined = sdkDefinedClasses();
+
+  const bundleClasses = new Map(); // bundleName -> Set
+  for (const bundle of new Set(tagToBundle.values())) {
+    const file = path.join(DIST_ESM, bundle + '.entry.js');
+    bundleClasses.set(bundle, exists(file) ? chunkCssClasses(file) : new Set());
+  }
+
+  const baseline = JSON.parse(read(BASELINE_JSON));
+  const baselineClasses = new Set(baseline.centralBuildClasses);
+  const themeClasses = new Set(baseline.themeOwnedClasses);
+
+  const whitelistFor = (component, cls) =>
+    WHITELIST.find((w) => w.class === cls && (!w.component || w.component === component));
+
+  // class -> set of bundles whose chunk styles it
+  const classOwners = new Map();
+  for (const [bundle, classes] of bundleClasses) {
+    for (const c of classes) {
+      if (!classOwners.has(c)) classOwners.set(c, new Set());
+      classOwners.get(c).add(bundle);
+    }
+  }
+
+  // Transitive children per tag (descendants whose chunks load alongside).
+  const byTag = new Map(components.map((c) => [c.tag, c]));
+  function descendants(tag, seen = new Set()) {
+    for (const child of byTag.get(tag)?.children ?? []) {
+      if (!seen.has(child)) { seen.add(child); descendants(child, seen); }
+    }
+    return seen;
+  }
+  // transitive ancestors
+  const directAncestors = new Map();
+  for (const c of components) {
+    for (const child of c.children) {
+      if (!directAncestors.has(child)) directAncestors.set(child, new Set());
+      directAncestors.get(child).add(c.tag);
+    }
+  }
+  function ancestors(tag, seen = new Set()) {
+    for (const a of directAncestors.get(tag) ?? []) {
+      if (!seen.has(a)) { seen.add(a); ancestors(a, seen); }
+    }
+    return seen;
+  }
+  // dir utilities ride the dir-main component's chunk only
+  const dirMainTag = new Map();
+  for (const c of components) if (c.tag === c.dir) dirMainTag.set(c.dir, c.tag);
+
+  const flags = [];
+  for (const c of components) {
+    const bundle = tagToBundle.get(c.tag);
+    if (!bundle) { flags.push({ component: c.tag, class: '(whole component)', type: 'no-bundle', detail: 'tag missing from loader map' }); continue; }
+    const own = bundleClasses.get(bundle) ?? new Set();
+    const desc = descendants(c.tag);
+
+    for (const cls of [...c.used].sort()) {
+      if (own.has(cls) || baseClasses.has(cls)) continue;
+      const wl = whitelistFor(c.tag, cls);
+      if (wl) { flags.push({ component: c.tag, class: cls, type: 'whitelisted', detail: wl.reason }); continue; }
+      const owners = classOwners.get(cls);
+      if (owners && owners.size) {
+        const ownerTags = [...tagToBundle].filter(([, b]) => owners.has(b)).map(([t]) => t);
+        const anc = ancestors(c.tag);
+        const viaChild = ownerTags.filter((t) => desc.has(t));
+        const viaAncestor = ownerTags.filter((t) => anc.has(t));
+        const dirMain = dirMainTag.get(c.dir);
+        if (dirMain && dirMain !== c.tag && ownerTags.includes(dirMain)) {
+          flags.push({ component: c.tag, class: cls, type: 'same-dir-split', detail: `dir utilities ride main chunk only: ${dirMain}` });
+        } else if (viaChild.length) {
+          flags.push({ component: c.tag, class: cls, type: 'fragile-composition', detail: `styled only by rendered child: ${viaChild.join(', ')}` });
+        } else if (viaAncestor.length) {
+          flags.push({ component: c.tag, class: cls, type: 'ancestor-provided', detail: `styled only by ancestor that renders it: ${viaAncestor.join(', ')}` });
+        } else {
+          flags.push({ component: c.tag, class: cls, type: 'hard-drop', detail: `styled only by unrelated: ${ownerTags.join(', ') || owners.size + ' bundle(s)'}` });
+        }
+      } else if (sdkDefined.has(cls)) {
+        // SDK ownership beats theme-owned
+        flags.push({ component: c.tag, class: cls, type: 'lost-rule', detail: 'selector defined in a utilities.json but emitted into no chunk' });
+      } else if (themeClasses.has(cls)) {
+        flags.push({ component: c.tag, class: cls, type: 'theme-owned', detail: 'styled by the migrated theme css, not an SDK rule' });
+      } else if (baselineClasses.has(cls)) {
+        flags.push({ component: c.tag, class: cls, type: 'lost-rule', detail: 'rule existed in central build, now in no chunk' });
+      } else {
+        flags.push({ component: c.tag, class: cls, type: 'never-styled', detail: 'no rule anywhere, incl. central baseline' });
+      }
+    }
+    for (const prefix of [...new Set(c.dynamic)].sort()) {
+      if (prefix.startsWith('salla-')) continue;
+      flags.push({ component: c.tag, class: prefix + '${...}', type: 'dynamic-wildcard', detail: 'runtime-built class, verify owner chunk covers all variants' });
+    }
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({ components: components.length, flags }, null, 2));
+  } else {
+    const order = ['lost-rule', 'hard-drop', 'same-dir-split', 'fragile-composition', 'ancestor-provided', 'dynamic-wildcard', 'theme-owned', 'whitelisted', 'never-styled', 'no-bundle'];
+    const missing = flags.filter((f) => f.type === 'lost-rule' || f.type === 'hard-drop');
+    console.log(`Scanned ${components.length} components, ${bundleClasses.size} bundles.`);
+    console.log(missing.length
+      ? `⚠️  ${missing.length} class(es) now styled by no chunk - see lost-rule/hard-drop below. Verify each is intentionally dropped.\n`
+      : `✅ No dropped classes.\n`);
+    for (const type of order) {
+      const group = flags.filter((f) => f.type === type);
+      if (!group.length) continue;
+      console.log(`== ${type} (${group.length}) ==`);
+      for (const f of group) console.log(`  ${f.component}  ${f.class}  -> ${f.detail}`);
+      console.log('');
+    }
+    if (!flags.length) console.log('No flags. Invariant holds.');
+  }
+
+  // Report only - never blocks the build or CI; dropped classes print above under lost-rule/hard-drop.
+  process.exit(0);
+}
+
+main();

package/dist/collection/plugins/tailwind-per-component.js

@@ -0,0 +1,146 @@
+// Per-component Tailwind: appends each component's CSS (utilities.json rules +
+// classes used in its own tsx) to its styleUrl output, so styles lazy-load with
+// the component chunk instead of one big global CSS file.
+// Third-party-lib selectors (flatpickr, filepond) must live with the component
+// that imports the lib, so the styles ride the same chunk as the lib itself.
+const fs = require('fs');
+const path = require('path');
+const tailwindcss = require('tailwindcss');
+const twPlugin = require('tailwindcss/plugin');
+const core = require('@salla.sa/twilight-tailwind-theme/plugin-core');
+const generatorGlobals = require('@salla.sa/twilight-tailwind-theme/generator-globals');
+const tokens = require('@salla.sa/twilight-tailwind-theme/component-tokens');
+const postcss = require(require.resolve('postcss', {
+  paths: [path.dirname(require.resolve('tailwindcss/package.json'))],
+}));
+
+const crypto = require('crypto');
+const { isDevMode } = require('./commonjs-cache-fix');
+
+const componentsDir = path.resolve(__dirname, '../components');
+const CLASS_RE = /\.((?:[\w-]|\\.)+)/g;
+const md5 = (s) => crypto.createHash('md5').update(s).digest('hex');
+
+let cachedRules = null;
+let aggregateSig = '';
+// Pre-existing collisions, frozen as the central generator shipped them.
+const KNOWN_COLLISIONS = new Set(['.s-modal-header']);
+
+// Aggregate all utilities.json (same mapping as tailwind-theme/generator.js).
+function allRules() {
+  if (cachedRules && !isDevMode()) return cachedRules;
+  const map = new Map(); // selector -> {owner, css}
+  for (const dir of fs.readdirSync(componentsDir, { withFileTypes: true })) {
+    if (!dir.isDirectory()) continue;
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(path.join(componentsDir, dir.name, 'utilities.json'), 'utf8'));
+    } catch (e) {
+      continue;
+    }
+    const owner = dir.name.replace('salla-', '');
+    for (const [key, value] of Object.entries(json)) {
+      const selector = typeof value === 'string'
+        ? (key.startsWith('@at-root') ? key.replace('@at-root ', '') : `.s-${owner}-${key}`)
+        : key;
+      const prev = map.get(selector);
+      if (prev && prev.owner !== owner && !KNOWN_COLLISIONS.has(selector)) {
+        throw new Error(`utilities.json selector collision: "${selector}" is defined by both `
+          + `salla-${prev.owner} and salla-${owner}; the aggregate is last-write-wins, so one `
+          + `silently loses its rule. Scope the selector under your component's own class instead.`);
+      }
+      map.set(selector, { owner, css: typeof value === 'string' ? { [`@apply ${value}`]: {} } : value });
+    }
+  }
+  cachedRules = [...map.entries()].map(([selector, r]) => ({ selector, ...r }));
+  aggregateSig = md5(JSON.stringify(cachedRules));
+  return cachedRules;
+}
+
+// Component dir state (tsx content scan + utilities.json) for cache invalidation.
+function dirSignature(dirName) {
+  const dir = path.join(componentsDir, dirName);
+  return fs.readdirSync(dir)
+    .filter((f) => /\.(tsx|ts|json)$/.test(f))
+    .map((f) => f + ':' + fs.statSync(path.join(dir, f)).mtimeMs)
+    .join('|');
+}
+
+// Candidate classes that force-emit this component's rules (covers `s-x-${dynamic}` names).
+function safelistFor(owner) {
+  const own = `s-${owner}`;
+  const out = new Set();
+  for (const rule of allRules()) {
+    if (rule.owner !== owner) continue;
+    const classes = Array.from(rule.selector.matchAll(CLASS_RE), (m) => m[1].replace(/\\/g, ''));
+    const owned = classes.filter((c) => c === own || c.startsWith(`${own}-`));
+    for (const c of owned.length ? owned : classes) out.add(c);
+  }
+  return [...out];
+}
+
+// Own rules + foreign rules that mention this component's classes.
+function rulesFor(owner) {
+  const own = `s-${owner}`;
+  return allRules().filter((rule) => {
+    if (rule.owner === owner) return true;
+    return Array.from(rule.selector.matchAll(CLASS_RE), (m) => m[1].replace(/\\/g, ''))
+      .some((c) => c === own || c.startsWith(`${own}-`));
+  });
+}
+
+function tailwindConfigFor(owner, dirName) {
+  const componentPlugin = twPlugin((api) => {
+    core.handler(api);
+    api.addUtilities(generatorGlobals);
+    api.addUtilities(rulesFor(owner).map((r) => ({ [r.selector]: r.css })));
+  }, core.config);
+
+  return {
+    important: false,
+    darkMode: 'class',
+    corePlugins: { preflight: false, outline: false },
+    content: [
+      path.join(componentsDir, dirName, '**/*.{tsx,ts}'),
+      '!' + path.join(componentsDir, dirName, '**/test/**'),
+    ],
+    safelist: safelistFor(owner),
+    theme: tokens,
+    plugins: [componentPlugin],
+  };
+}
+
+// Stencil compiles styles once per output target (dist, custom-elements,
+// hydrate): share one compute per input state instead of running 3x.
+const resultCache = new Map(); // `${fileName}:${dirName}` -> {key, promise}
+
+exports.tailwindPerComponent = () => ({
+  name: 'tailwind-per-component',
+  pluginType: 'css',
+  async transform(sourceText, fileName) {
+    if (process.env.TWPC_DEBUG) console.log('TWPC transform:', fileName);
+    // Stencil passes sass output as .css (original styleUrl is .scss).
+    if (!fileName || !/\.s?css$/.test(fileName)) return null;
+    const rel = path.relative(componentsDir, fileName);
+    if (rel.startsWith('..')) return null;
+    const [dirName, base] = rel.split(path.sep);
+    // Utilities ride the main component file only (sub-component scss pass through).
+    if (base !== `${dirName}.css` && base !== `${dirName}.scss`) return null;
+    const owner = dirName.replace('salla-', '');
+    allRules();
+    const key = md5(sourceText) + aggregateSig + md5(dirSignature(dirName));
+    // Key by file + dir: dir drives owner/config, several components share one styleUrl.
+    const cacheKey = `${fileName}:${dirName}`;
+    const hit = resultCache.get(cacheKey);
+    if (hit && hit.key === key) return { code: await hit.promise };
+    const promise = postcss([tailwindcss(tailwindConfigFor(owner, dirName))])
+      .process(`${sourceText}\n@tailwind utilities;\n`, { from: fileName })
+      .then((result) => {
+        if (isDevMode()) console.log(`✅ [utilities] ${dirName} compiled (${Math.round(result.css.length / 1024)}kb)`);
+        // Marker lets the global script keep this chunk's <style> ahead of the theme css.
+        return `/*!twlt*/${result.css}`;
+      });
+    resultCache.set(cacheKey, { key, promise });
+    return { code: await promise };
+  },
+});

package/dist/collection/plugins/watch-utilities.js

@@ -0,0 +1,22 @@
+// Stencil doesn't watch json: on utilities.json change, touch the component's
+// scss so the watch build re-runs the per-component Tailwind transform.
+const fs = require('fs');
+const path = require('path');
+
+const componentsDir = path.resolve(__dirname, '../components');
+
+const lastSeen = new Map();
+fs.watch(componentsDir, { recursive: true }, (event, file) => {
+  if (!file || !file.endsWith('utilities.json')) return;
+  // macOS fires twice per save
+  if (Date.now() - (lastSeen.get(file) || 0) < 200) return;
+  lastSeen.set(file, Date.now());
+  const dir = path.dirname(file);
+  const scss = path.join(componentsDir, dir, `${path.basename(dir)}.scss`);
+  if (!fs.existsSync(scss)) return console.log(`⚠️  [utilities] no scss for ${dir}, styles won't rebuild`);
+  const now = new Date();
+  fs.utimesSync(scss, now, now);
+  console.log(`⚙️  [utilities] ${dir} changed, compiling new utilities...`);
+});
+
+console.log('👀 [utilities] watching src/components/**/utilities.json');