inkbridge 0.1.0-beta.2 → 0.1.0-beta.21

package/scanner/css-token-reader.ts

@@ -6,13 +6,13 @@ import {
   type ScannedThemeTokens,
   type ScannedTokenMap,
   type TokenSourceMode,
-} from '../src/token-source';
+} from '../src/tokens/token-source';
 
 const CSS_DISCOVERY_PATHS = [
-  'src/app/tokens.css',
   'src/app/globals.css',
   'app/globals.css',
   'styles/globals.css',
+  'src/app/tokens.css',
 ];
 
 const DEFAULT_DTCG_PATH = 'design-tokens/tokens.dtcg.json';
@@ -32,8 +32,69 @@ type TargetTokenGroup = {
   spacing: Record<string, number>;
   fontSize: Record<string, number>;
   shadows: Record<string, string>;
+  breakpoints: Record<string, number>;
 };
 
+// The Tailwind default theme ships ~240 color shades (red-50, blue-500, …) plus
+// `black` and `white`. They bloat the Figma Variables collection and the design
+// tokens overview without giving designers anything actionable — semantic
+// overrides like --primary, --background, etc. carry the real intent. Drop the
+// raw scale; user-defined tokens that happen to share these names are an
+// accepted edge case.
+const TAILWIND_DEFAULT_COLOR_SCALE = /^(red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone|mauve|olive|mist|taupe)-(50|100|200|300|400|500|600|700|800|900|950)$/;
+const TAILWIND_DEFAULT_COLOR_NAMES = new Set(['black', 'white']);
+
+function isTailwindDefaultColorKey(key: string): boolean {
+  return TAILWIND_DEFAULT_COLOR_SCALE.test(key) || TAILWIND_DEFAULT_COLOR_NAMES.has(key);
+}
+
+// CSS variables that appear in Tailwind's default theme but are not design
+// tokens we surface (font weights, easing curves, animations, container sizes,
+// tracking/leading metadata, blur scales, internal `--default-*` pointers,
+// and *-shadow effect variants like inset/drop/text). Skipping these keeps the
+// plugin focused on tokens designers actually edit.
+const SKIP_PREFIXES = [
+  'font-weight-',
+  'font-feature-settings-',
+  'font-variation-settings-',
+  'inset-shadow-',
+  'drop-shadow-',
+  'text-shadow-',
+  'ease-',
+  'animate-',
+  // tw-animate-css helper variables — animation timing/duration/etc., not design tokens.
+  'animation-',
+  // tw-animate-css percentage helpers used by keyframe utilities.
+  'percentage-',
+  'blur-',
+  'perspective-',
+  'aspect-',
+  'default-',
+  'tracking-',
+  'leading-',
+  'container-',
+];
+
+// Single-name leftovers from Tailwind's deprecated `@theme default inline reference`
+// block (no suffix). They would otherwise fall through to the catch-all and pollute
+// the color group.
+const SKIP_EXACT_NAMES = new Set([
+  'blur',
+  'drop-shadow',
+  'max-width-prose',
+]);
+
+function shouldSkipVariableName(name: string): boolean {
+  if (SKIP_EXACT_NAMES.has(name)) return true;
+  for (const prefix of SKIP_PREFIXES) {
+    if (name.startsWith(prefix)) return true;
+  }
+  // Tailwind also emits `--text-{size}--line-height` siblings that are calc
+  // expressions — they are metadata, not standalone tokens.
+  if (/^text-.+--line-height$/.test(name)) return true;
+  return false;
+}
+
 function toDisplayPath(projectRoot: string, filePath: string): string {
   const rel = path.relative(projectRoot, filePath);
   if (!rel || rel.startsWith('..')) return filePath;
@@ -63,6 +124,37 @@ function extractImportSpecifier(params: string): string | null {
   return null;
 }
 
+function resolveBareSpecifierFromNodeModules(baseFilePath: string, specifier: string): string | null {
+  let dir = path.dirname(baseFilePath);
+  while (true) {
+    const pkgRoot = path.join(dir, 'node_modules', specifier);
+    if (fs.existsSync(pkgRoot)) {
+      const pkgJsonPath = path.join(pkgRoot, 'package.json');
+      if (fs.existsSync(pkgJsonPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+          // Prefer "style" field (CSS entry), fall back to "main" if it ends in .css.
+          if (typeof pkg.style === 'string' && pkg.style) {
+            const stylePath = path.join(pkgRoot, pkg.style);
+            if (fs.existsSync(stylePath)) return stylePath;
+          }
+          if (typeof pkg.main === 'string' && pkg.main && pkg.main.endsWith('.css')) {
+            const mainPath = path.join(pkgRoot, pkg.main);
+            if (fs.existsSync(mainPath)) return mainPath;
+          }
+        } catch {
+          // Malformed package.json — fall through to index.css.
+        }
+      }
+      const indexCss = path.join(pkgRoot, 'index.css');
+      if (fs.existsSync(indexCss)) return indexCss;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 function resolveImportedCssPath(baseFilePath: string, params: string): string | null {
   const specifier = extractImportSpecifier(params);
   if (!specifier) return null;
@@ -80,10 +172,23 @@ function resolveImportedCssPath(baseFilePath: string, params: string): string |
   const direct = path.resolve(fromDir, specifier);
   if (fs.existsSync(direct)) return direct;
   if (!path.extname(direct) && fs.existsSync(direct + '.css')) return direct + '.css';
+
+  // Bare specifiers (e.g. `@import "tailwindcss"`) resolve via node_modules so
+  // we can pull Tailwind's default `@theme` block — breakpoints, default text
+  // sizes, etc. — into the scanned token map.
+  const isBare = !specifier.startsWith('./') && !specifier.startsWith('../') && !path.isAbsolute(specifier);
+  if (isBare) {
+    const nm = resolveBareSpecifierFromNodeModules(baseFilePath, specifier);
+    if (nm) return nm;
+  }
   return null;
 }
 
 function cssHasTokenDeclarations(cssText: string): boolean {
+  // Only count declarations inside :root {} or .[theme] {} rules — the same
+  // selectors that patchCssVariables targets. We intentionally skip @theme
+  // at-rules (Tailwind v4 utility mappings) because those contain var()
+  // references, not source values, and the patcher cannot update them.
   try {
     const root = postcss.parse(cssText);
     let found = false;
@@ -91,16 +196,9 @@ function cssHasTokenDeclarations(cssText: string): boolean {
       if (found) return;
       if (!decl.prop || !decl.prop.startsWith('--')) return;
       const parent = decl.parent;
-      if (!parent) return;
-      if (parent.type === 'atrule') {
-        const at = parent as AtRule;
-        if ((at.name || '').toLowerCase() === 'theme') found = true;
-        return;
-      }
-      if (parent.type === 'rule') {
-        const selector = (parent as Rule).selector || '';
-        if (parseThemeSelectors(selector).length > 0) found = true;
-      }
+      if (!parent || parent.type !== 'rule') return;
+      const selector = (parent as Rule).selector || '';
+      if (parseThemeSelectors(selector).length > 0) found = true;
     });
     return found;
   } catch {
@@ -108,7 +206,7 @@ function cssHasTokenDeclarations(cssText: string): boolean {
   }
 }
 
-function resolveCssTokenPathFromImports(filePath: string, visited: Set<string> = new Set()): string {
+export function resolveCssTokenPathFromImports(filePath: string, visited: Set<string> = new Set()): string {
   const absolute = path.resolve(filePath);
   if (visited.has(absolute)) return absolute;
   visited.add(absolute);
@@ -179,12 +277,11 @@ function readCssWithImports(filePath: string, visited: Set<string> = new Set()):
 
 export function discoverCssTokenPath(projectRoot: string, explicitPath?: string): string | null {
   if (explicitPath && explicitPath.trim()) {
-    const explicit = discoverFilePath(projectRoot, explicitPath.trim());
-    return explicit ? resolveCssTokenPathFromImports(explicit) : null;
+    return discoverFilePath(projectRoot, explicitPath.trim());
   }
   for (const rel of CSS_DISCOVERY_PATHS) {
     const found = discoverFilePath(projectRoot, rel);
-    if (found) return resolveCssTokenPathFromImports(found);
+    if (found) return found;
   }
   return null;
 }
@@ -235,6 +332,7 @@ function getTargetGroup(map: ScannedTokenMap, themeName: string): TargetTokenGro
       spacing: map.spacing,
       fontSize: map.fontSize,
       shadows: map.shadows,
+      breakpoints: map.breakpoints,
     };
   }
   const theme = ensureThemeContainer(map, themeName);
@@ -243,6 +341,7 @@ function getTargetGroup(map: ScannedTokenMap, themeName: string): TargetTokenGro
   if (!theme.spacing) theme.spacing = {};
   if (!theme.fontSize) theme.fontSize = {};
   if (!theme.shadows) theme.shadows = {};
+  if (!theme.breakpoints) theme.breakpoints = {};
   return {
     colors: theme.colors,
     radius: theme.radius,
@@ -250,6 +349,7 @@ function getTargetGroup(map: ScannedTokenMap, themeName: string): TargetTokenGro
     spacing: theme.spacing,
     fontSize: theme.fontSize,
     shadows: theme.shadows,
+    breakpoints: theme.breakpoints,
   };
 }
 
@@ -259,14 +359,22 @@ function parseThemeSelectors(selector: string): string[] {
   if (!raw) return [];
   const normalized = raw.toLowerCase();
 
+  // data-theme attribute approach: :root[data-theme="secondary"]
   const dataThemeMatches = normalized.matchAll(/\[data-theme\s*=\s*["']?([^"'\\\]]+)["']?\]/g);
   for (const match of dataThemeMatches) {
     const themeName = String(match[1] || '').trim();
     if (themeName) themes.add(themeName);
   }
 
-  if (/(\.|:)(dark)\b/.test(normalized)) {
-    themes.add('dark');
+  // Class-based brand themes: .secondary — skip compound .dark.X selectors
+  // so dark-mode overrides don't pollute the brand theme list.
+  const hasDarkClass = /(?:^|[\s.])dark\b/.test(normalized);
+  if (!hasDarkClass) {
+    const classMatches = normalized.matchAll(/\.([a-z][a-z0-9-]*)/g);
+    for (const match of classMatches) {
+      const name = String(match[1] || '').trim();
+      if (name && name !== 'dark' && name !== 'root') themes.add(name);
+    }
   }
 
   if (normalized.includes(':root') && themes.size === 0) {
@@ -276,18 +384,23 @@ function parseThemeSelectors(selector: string): string[] {
   return Array.from(themes);
 }
 
-type VariableCategory = 'color' | 'radius' | 'font' | 'spacing' | 'fontSize' | 'shadow';
+type VariableCategory = 'color' | 'radius' | 'font' | 'spacing' | 'fontSize' | 'shadow' | 'breakpoint';
 
 function classifyVariable(rawName: string): { category: VariableCategory; key: string } | null {
   const name = String(rawName || '').trim().replace(/^--/, '');
   if (!name) return null;
 
+  if (shouldSkipVariableName(name)) return null;
+
   if (name === 'radius') return { category: 'radius', key: 'base' };
   if (name.startsWith('radius-')) return { category: 'radius', key: name.slice('radius-'.length) };
 
+  if (name.startsWith('breakpoint-')) return { category: 'breakpoint', key: name.slice('breakpoint-'.length) };
+
   if (name.startsWith('font-family-')) return { category: 'font', key: name.slice('font-family-'.length) };
   if (name.startsWith('font-') && !name.startsWith('font-size-')) return { category: 'font', key: name.slice('font-'.length) };
 
+  if (name === 'spacing') return { category: 'spacing', key: 'base' };
   if (name.startsWith('spacing-')) return { category: 'spacing', key: name.slice('spacing-'.length) };
   if (name.startsWith('text-')) return { category: 'fontSize', key: name.slice('text-'.length) };
   if (name.startsWith('font-size-')) return { category: 'fontSize', key: name.slice('font-size-'.length) };
@@ -295,7 +408,12 @@ function classifyVariable(rawName: string): { category: VariableCategory; key: s
   if (name === 'shadow') return { category: 'shadow', key: 'DEFAULT' };
   if (name.startsWith('shadow-')) return { category: 'shadow', key: name.slice('shadow-'.length) };
 
-  if (name.startsWith('color-')) return { category: 'color', key: name.slice('color-'.length) };
+  if (name.startsWith('color-')) {
+    const key = name.slice('color-'.length);
+    if (isTailwindDefaultColorKey(key)) return null;
+    return { category: 'color', key };
+  }
+  if (isTailwindDefaultColorKey(name)) return null;
   return { category: 'color', key: name };
 }
 
@@ -323,6 +441,11 @@ function applyDeclaration(target: TargetTokenGroup, decl: Declaration): void {
     if (px != null) target.radius[classification.key] = px;
     return;
   }
+  if (classification.category === 'breakpoint') {
+    const px = parseDimensionPx(value);
+    if (px != null) target.breakpoints[classification.key] = px;
+    return;
+  }
   if (classification.category === 'spacing') {
     const px = parseDimensionPx(value);
     if (px != null) target.spacing[classification.key] = px;
@@ -376,7 +499,7 @@ function walkCssNodes(map: ScannedTokenMap, container: postcss.Container): void
   }
 }
 
-export function parseCssTokenMap(cssText: string, source: string, requestedMode: TokenSourceMode = 'auto'): ScannedTokenMap {
+export function parseCssTokenMap(cssText: string, source: string, requestedMode: TokenSourceMode = 'css'): ScannedTokenMap {
   const map = createEmptyScannedTokenMap('css', source, requestedMode);
   const root = postcss.parse(cssText);
   walkCssNodes(map, root);
@@ -417,7 +540,7 @@ function applyDtcgDimensionGroup(
 function parseDtcgTokenMap(
   dtcgJson: unknown,
   source: string,
-  requestedMode: TokenSourceMode = 'auto'
+  requestedMode: TokenSourceMode = 'dtcg'
 ): ScannedTokenMap {
   const map = createEmptyScannedTokenMap('dtcg', source, requestedMode);
   if (!isPlainObject(dtcgJson)) return map;
@@ -445,16 +568,10 @@ function parseDtcgTokenMap(
 
 export function readTokenSourceMap(options: ReadTokenSourceOptions): ScannedTokenMap {
   const projectRoot = path.resolve(options.projectRoot);
-  const requestedMode = options.tokenSourceMode || 'auto';
+  const requestedMode: TokenSourceMode = options.tokenSourceMode === 'dtcg' ? 'dtcg' : 'css';
   const cssPath = discoverCssTokenPath(projectRoot, options.cssTokenPath);
   const dtcgPath = discoverDtcgTokenPath(projectRoot, options.dtcgTokenPath);
 
-  if (requestedMode === 'css') {
-    if (!cssPath) return createEmptyScannedTokenMap('embedded', 'embedded:tokens.ts', requestedMode);
-    const cssText = readCssWithImports(cssPath);
-    return parseCssTokenMap(cssText, toDisplayPath(projectRoot, cssPath), requestedMode);
-  }
-
   if (requestedMode === 'dtcg') {
     if (!dtcgPath) return createEmptyScannedTokenMap('embedded', 'embedded:tokens.ts', requestedMode);
     const dtcgText = fs.readFileSync(dtcgPath, 'utf-8');
@@ -462,10 +579,14 @@ export function readTokenSourceMap(options: ReadTokenSourceOptions): ScannedToke
     return parseDtcgTokenMap(dtcgJson, toDisplayPath(projectRoot, dtcgPath), requestedMode);
   }
 
-  // auto mode: CSS always wins when present.
+  // css mode: CSS preferred; fall back to DTCG if no CSS file found, then embedded.
   if (cssPath) {
     const cssText = readCssWithImports(cssPath);
-    return parseCssTokenMap(cssText, toDisplayPath(projectRoot, cssPath), requestedMode);
+    // Use the file that actually contains the declarations as source so the
+    // write-back path (PR/patch) targets the right file even when globals.css
+    // delegates token definitions to an imported file like tokens.css.
+    const writeTarget = resolveCssTokenPathFromImports(cssPath);
+    return parseCssTokenMap(cssText, toDisplayPath(projectRoot, writeTarget), requestedMode);
   }
   if (dtcgPath) {
     const dtcgText = fs.readFileSync(dtcgPath, 'utf-8');

package/scanner/cva-jsx-child-fallback-regression.ts

@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+
+import { cvaInstanceHasOverridingJsxChildren } from '../src/components/component-instance';
+
+// Regression: predicate that decides whether a CVA component instance has
+// per-instance JSX-element children (e.g. icons) that the symbol-instance
+// path can't honour, forcing a fall back to frame rendering.
+//
+// History: `<ToggleGroup>` with three `<Toggle>` items, each with a different
+// icon child (AlignLeft / AlignCenter / AlignRight), rendered all three with
+// the same icon (Bold) — because the Toggle CVA master is built from one of
+// Toggle's own stories and Figma's instance API can't swap SVG vectors per
+// instance. The story-root path already had a similar guard
+// (`shouldUseInstance` in story-render-strategy.ts); this is the parallel
+// guard for NESTED CVA instances inside a JSX tree.
+
+interface Case {
+  name: string;
+  props: { __jsxChildren?: unknown } | null;
+  expected: boolean;
+}
+
+const CASES: Case[] = [
+  {
+    name: 'no props at all',
+    props: null,
+    expected: false,
+  },
+  {
+    name: 'empty props',
+    props: {},
+    expected: false,
+  },
+  {
+    name: '__jsxChildren is not an array (defensive)',
+    props: { __jsxChildren: 'not-an-array' },
+    expected: false,
+  },
+  {
+    name: 'empty __jsxChildren array',
+    props: { __jsxChildren: [] },
+    expected: false,
+  },
+  {
+    name: 'text-only children (e.g. <Button>Click me</Button>)',
+    props: { __jsxChildren: [{ type: 'text', content: 'Click me' }] },
+    expected: false,
+  },
+  {
+    name: 'single element child (e.g. <Toggle><Bold /></Toggle>)',
+    props: {
+      __jsxChildren: [
+        { type: 'element', tagName: 'Bold', isComponent: true, props: {}, children: [] },
+      ],
+    },
+    expected: true,
+  },
+  {
+    name: 'icon + text mixed (e.g. <Button><Plus /> Add</Button>)',
+    props: {
+      __jsxChildren: [
+        { type: 'element', tagName: 'Plus', isComponent: true, props: {}, children: [] },
+        { type: 'text', content: ' Add' },
+      ],
+    },
+    expected: true,
+  },
+  {
+    name: 'multiple elements (rare; defensive)',
+    props: {
+      __jsxChildren: [
+        { type: 'element', tagName: 'AlignLeft', isComponent: true, props: {}, children: [] },
+        { type: 'element', tagName: 'AlignCenter', isComponent: true, props: {}, children: [] },
+      ],
+    },
+    expected: true,
+  },
+  {
+    name: 'null entries in array are tolerated',
+    props: { __jsxChildren: [null, undefined, { type: 'text', content: 'Hi' }] },
+    expected: false,
+  },
+];
+
+let failed = 0;
+for (const c of CASES) {
+  const actual = cvaInstanceHasOverridingJsxChildren(c.props);
+  if (actual !== c.expected) {
+    console.error(`  ✗ ${c.name}: expected ${c.expected}, got ${actual}`);
+    failed++;
+  }
+}
+
+if (failed > 0) {
+  assert.fail(`${failed}/${CASES.length} cva-jsx-child-fallback cases failed`);
+}
+
+console.log(`cva-jsx-child-fallback-regression: PASS (${CASES.length} cases)`);