inkbridge 0.1.0-beta.1

package/scanner/tailwind-parser.ts

@@ -0,0 +1,644 @@
+/**
+ * Tailwind Class Parser
+ *
+ * Parses Tailwind CSS classes and extracts styling information
+ * for mapping to Figma properties.
+ */
+
+import type { ParsedTailwindClass, ColorMapping, SizeMapping } from './types';
+import colors from 'tailwindcss/colors';
+
+// ============================================================================
+// Responsive Breakpoints (all standard Tailwind breakpoints)
+// ============================================================================
+
+export const RESPONSIVE_PREFIXES = [
+  'sm:',
+  'md:',
+  'lg:',
+  'xl:',
+  '2xl:',
+  'min-[',   // arbitrary min-width: min-[320px]:
+  'max-sm:',
+  'max-md:',
+  'max-lg:',
+  'max-xl:',
+  'max-2xl:',
+  'max-[',   // arbitrary max-width: max-[600px]:
+] as const;
+
+// ============================================================================
+// Pseudo-element / Pseudo-class / Structural Modifiers
+// ============================================================================
+
+export const PSEUDO_MODIFIERS = [
+  // Pseudo-elements
+  'before:',
+  'after:',
+  'placeholder:',
+  'file:',
+  'selection:',
+  'marker:',
+  'backdrop:',
+  'first-line:',
+  'first-letter:',
+  // Structural pseudo-classes
+  'first:',
+  'last:',
+  'odd:',
+  'even:',
+  'only:',
+  'first-of-type:',
+  'last-of-type:',
+  'only-of-type:',
+  'empty:',
+  // Form pseudo-classes
+  'required:',
+  'optional:',
+  'valid:',
+  'invalid:',
+  'in-range:',
+  'out-of-range:',
+  'read-only:',
+  'read-write:',
+  'autofill:',
+  'checked:',
+  'indeterminate:',
+  'default:',
+  'enabled:',
+  // Print / Motion / Contrast
+  'print:',
+  'motion-safe:',
+  'motion-reduce:',
+  'contrast-more:',
+  'contrast-less:',
+  'forced-colors:',
+  // Direction / Language
+  'ltr:',
+  'rtl:',
+  // Dark mode
+  'dark:',
+  // Container queries
+  '@sm:',
+  '@md:',
+  '@lg:',
+  '@xl:',
+  '@2xl:',
+  // Supports / Has
+  'supports-[',
+  'has-[',
+  'not-[',
+  // Portrait / Landscape
+  'portrait:',
+  'landscape:',
+  // Open
+  'open:',
+] as const;
+
+// ============================================================================
+// Tailwind Spacing Scale (default values in pixels, assuming 1rem = 16px)
+// ============================================================================
+
+export const TAILWIND_SPACING: Record<string, number> = {
+  '0': 0,
+  'px': 1,
+  '0.5': 2,
+  '1': 4,
+  '1.5': 6,
+  '2': 8,
+  '2.5': 10,
+  '3': 12,
+  '3.5': 14,
+  '4': 16,
+  '5': 20,
+  '6': 24,
+  '7': 28,
+  '8': 32,
+  '9': 36,
+  '10': 40,
+  '11': 44,
+  '12': 48,
+  '14': 56,
+  '16': 64,
+  '20': 80,
+  '24': 96,
+  '28': 112,
+  '32': 128,
+  '36': 144,
+  '40': 160,
+  '44': 176,
+  '48': 192,
+  '52': 208,
+  '56': 224,
+  '60': 240,
+  '64': 256,
+  '72': 288,
+  '80': 320,
+  '96': 384,
+  // Tailwind v4 named container sizes (rem × 16 → px)
+  'xs':  320,
+  'sm':  384,
+  'md':  448,
+  'lg':  512,
+  'xl':  576,
+  '2xl': 672,
+  '3xl': 768,
+  '4xl': 896,
+  '5xl': 1024,
+  '6xl': 1152,
+  '7xl': 1280,
+};
+
+/**
+ * Resolve a spacing token to pixels.
+ * Handles the v3 named scale, v4 named container sizes, and v4's open numeric
+ * scale where any integer n maps to n × 4 px (e.g. w-100 = 400 px).
+ */
+export function resolveSpacing(value: string): number | undefined {
+  const named = TAILWIND_SPACING[value];
+  if (named !== undefined) return named;
+  const n = parseFloat(value);
+  if (!Number.isNaN(n) && String(n) === value) return n * 4;
+  return undefined;
+}
+
+// ============================================================================
+// State Modifiers
+// ============================================================================
+
+export const STATE_MODIFIERS = [
+  'hover:',
+  'focus:',
+  'focus-visible:',
+  'focus-within:',
+  'active:',
+  'disabled:',
+  'aria-invalid:',
+  'aria-selected:',
+  'aria-expanded:',
+  'data-[state=open]:',
+  'data-[state=checked]:',
+  'data-[state=active]:',
+  'data-[disabled]:',
+  'group-hover:',
+  'group-focus:',
+  'peer-focus:',
+  'peer-disabled:',
+];
+
+// ============================================================================
+// Parsing Functions
+// ============================================================================
+
+/**
+ * All known modifier prefixes (state, responsive, pseudo, dark, etc.)
+ * Sorted longest-first so that e.g. `focus-visible:` matches before `focus:`.
+ */
+const ALL_MODIFIERS: string[] = [
+  ...STATE_MODIFIERS,
+  ...RESPONSIVE_PREFIXES,
+  ...PSEUDO_MODIFIERS,
+].sort((a, b) => b.length - a.length);
+
+/**
+ * Strip one modifier prefix from the front of a class string.
+ * Handles bracket-based modifiers like `data-[state=open]:`, `min-[320px]:`,
+ * `supports-[display:grid]:`, `has-[>img]:`, `not-[.disabled]:`, `max-[600px]:`.
+ * Returns the modifier string (including the trailing `:`) and the remainder,
+ * or null if no modifier is found.
+ */
+function stripOneModifier(cls: string): { modifier: string; rest: string } | null {
+  // 1. Try bracket-based modifiers first (data-[...]:, aria-[...]:, min-[...]:, etc.)
+  const bracketMatch = cls.match(/^([a-z@-]*\[[^\]]*\]:)(.*)/);
+  if (bracketMatch) {
+    return { modifier: bracketMatch[1], rest: bracketMatch[2] };
+  }
+
+  // 2. Try known fixed modifiers
+  for (const mod of ALL_MODIFIERS) {
+    if (cls.startsWith(mod)) {
+      return { modifier: mod, rest: cls.slice(mod.length) };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse a single Tailwind class into its components.
+ *
+ * Handles stacked modifiers (e.g. `sm:hover:bg-primary`, `dark:focus:ring-2`)
+ * and arbitrary bracket selectors (e.g. `data-[state=open]:animate-in`).
+ */
+export function parseTailwindClass(cls: string): ParsedTailwindClass {
+  const modifiers: string[] = [];
+  let utility = cls;
+
+  // Peel off all modifier layers
+  let result = stripOneModifier(utility);
+  while (result) {
+    modifiers.push(result.modifier);
+    utility = result.rest;
+    result = stripOneModifier(utility);
+  }
+
+  const modifier = modifiers.length > 0 ? modifiers.join('') : undefined;
+
+  // Categorise the modifiers
+  const responsive = modifiers.find(m =>
+    (RESPONSIVE_PREFIXES as readonly string[]).includes(m) || /^(min|max)-\[/.test(m)
+  );
+  const pseudo = modifiers.find(m =>
+    (PSEUDO_MODIFIERS as readonly string[]).includes(m)
+  );
+  const state = modifiers.find(m =>
+    STATE_MODIFIERS.includes(m)
+  );
+  const isDark = modifiers.includes('dark:');
+
+  // Handle opacity modifier in the utility (e.g. bg-muted/50)
+  let opacity: number | undefined;
+  const opacityMatch = utility.match(/^(.+)\/(\d+)$/);
+  if (opacityMatch) {
+    utility = opacityMatch[1];
+    opacity = parseInt(opacityMatch[2], 10);
+  }
+
+  // Handle arbitrary values (e.g. text-[13px], left-[calc(50%-11rem)])
+  let arbitrary: string | undefined;
+  const arbitraryMatch = utility.match(/^([a-z-]+)-\[(.+)\]$/);
+  if (arbitraryMatch) {
+    arbitrary = arbitraryMatch[2];
+  }
+
+  // Handle line-height slash notation (e.g. text-sm/6)
+  const slashNotation = cls.match(/^text-([a-z]+)\/(\d+)$/);
+
+  // Extract value from utility (e.g., "p-4" -> value = "4")
+  const match = utility.match(/^([a-z-]+)-(.+)$/);
+  const value = match?.[2];
+
+  return {
+    original: cls,
+    modifier,
+    modifiers,
+    utility,
+    value,
+    responsive,
+    pseudo,
+    state,
+    isDark,
+    opacity,
+    arbitrary,
+    lineHeight: slashNotation ? slashNotation[2] : undefined,
+  };
+}
+
+/**
+ * Parse a space-separated string of Tailwind classes
+ */
+export function parseClassString(classString: string): ParsedTailwindClass[] {
+  return classString
+    .split(/\s+/)
+    .filter(Boolean)
+    .map(parseTailwindClass);
+}
+
+/**
+ * Extract color-related classes and map to token names
+ */
+export function extractColorMappings(classes: string[]): ColorMapping[] {
+  const mappings: ColorMapping[] = [];
+
+  for (const cls of classes) {
+    const parsed = parseTailwindClass(cls);
+    const utility = parsed.utility;
+
+    // Background colors
+    if (utility.startsWith('bg-')) {
+      const tokenName = utility.slice(3);
+      // Filter out non-token values like opacity modifiers
+      if (!tokenName.includes('/') && !tokenName.match(/^(transparent|current|inherit|white|black)$/)) {
+        mappings.push({
+          tailwindClass: cls,
+          tokenName,
+          property: 'background',
+        });
+      }
+    }
+
+    // Text colors
+    if (utility.startsWith('text-') && !utility.match(/^text-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)$/)) {
+      const tokenName = utility.slice(5);
+      if (!tokenName.includes('/') && !tokenName.match(/^(transparent|current|inherit|white|black)$/)) {
+        mappings.push({
+          tailwindClass: cls,
+          tokenName,
+          property: 'text',
+        });
+      }
+    }
+
+    // Border colors
+    if (utility.startsWith('border-') && !utility.match(/^border-(\d+|t|r|b|l|x|y)$/)) {
+      const tokenName = utility.slice(7);
+      if (!tokenName.includes('/') && !tokenName.match(/^(transparent|current|inherit|white|black)$/)) {
+        mappings.push({
+          tailwindClass: cls,
+          tokenName,
+          property: 'border',
+        });
+      }
+    }
+
+    // Ring colors
+    if (utility.startsWith('ring-') && !utility.match(/^ring-(\d+|inset|offset)$/)) {
+      const tokenName = utility.slice(5);
+      if (!tokenName.includes('/') && !tokenName.match(/^(transparent|current|inherit|white|black)$/)) {
+        mappings.push({
+          tailwindClass: cls,
+          tokenName,
+          property: 'ring',
+        });
+      }
+    }
+  }
+
+  return mappings;
+}
+
+/**
+ * Extract Tailwind palette tokens used in classes and map to color values.
+ */
+export function extractPaletteTokens(classes: string[]): Record<string, string> {
+  const palette: Record<string, string> = {};
+  const prefixes = ['bg-', 'text-', 'border-', 'ring-', 'from-', 'to-', 'via-', 'fill-', 'stroke-'];
+
+  const resolvePaletteColor = (token: string): string | null => {
+    if (!token) return null;
+    if (token === 'transparent' || token === 'current' || token === 'inherit') return null;
+    const direct = (colors as any)[token];
+    if (typeof direct === 'string') return direct;
+    const parts = token.split('-');
+    if (parts.length < 2) return null;
+    const shade = parts[parts.length - 1];
+    const name = parts.slice(0, -1).join('-');
+    const group = (colors as any)[name];
+    if (group && typeof group === 'object' && group[shade]) return group[shade];
+    return null;
+  };
+
+  for (const cls of classes) {
+    const parsed = parseTailwindClass(cls);
+    const utility = parsed.utility;
+    for (const prefix of prefixes) {
+      if (!utility.startsWith(prefix)) continue;
+      const token = utility.slice(prefix.length);
+      if (!token || token.startsWith('[')) break;
+      const value = resolvePaletteColor(token);
+      if (value) palette[token] = value;
+      break;
+    }
+  }
+
+  return palette;
+}
+
+/**
+ * Extract size-related classes and convert to pixel values
+ */
+export function extractSizeMappings(classes: string[]): SizeMapping[] {
+  const mappings: SizeMapping[] = [];
+
+  for (const cls of classes) {
+    const parsed = parseTailwindClass(cls);
+    const utility = parsed.utility;
+
+    // Height
+    if (utility.startsWith('h-')) {
+      const value = utility.slice(2);
+      const px = resolveSpacing(value);
+      if (px !== undefined) {
+        mappings.push({ tailwindClass: cls, property: 'height', value: px });
+      }
+    }
+
+    // Width
+    if (utility.startsWith('w-')) {
+      const value = utility.slice(2);
+      const px = resolveSpacing(value);
+      if (px !== undefined) {
+        mappings.push({ tailwindClass: cls, property: 'width', value: px });
+      }
+    }
+
+    // Padding (all sides)
+    if (utility.startsWith('p-') && !utility.startsWith('px-') && !utility.startsWith('py-') && !utility.startsWith('pt-') && !utility.startsWith('pr-') && !utility.startsWith('pb-') && !utility.startsWith('pl-')) {
+      const value = utility.slice(2);
+      const px = resolveSpacing(value);
+      if (px !== undefined) {
+        mappings.push({ tailwindClass: cls, property: 'padding', value: px });
+      }
+    }
+
+    // Padding X
+    if (utility.startsWith('px-')) {
+      const value = utility.slice(3);
+      const px = resolveSpacing(value);
+      if (px !== undefined) {
+        mappings.push({ tailwindClass: cls, property: 'padding', value: px });
+      }
+    }
+
+    // Padding Y
+    if (utility.startsWith('py-')) {
+      const value = utility.slice(3);
+      const px = resolveSpacing(value);
+      if (px !== undefined) {
+        mappings.push({ tailwindClass: cls, property: 'padding', value: px });
+      }
+    }
+
+    // Gap
+    if (utility.startsWith('gap-')) {
+      const value = utility.slice(4);
+      const px = resolveSpacing(value);
+      if (px !== undefined) {
+        mappings.push({ tailwindClass: cls, property: 'gap', value: px });
+      }
+    }
+
+    // Space-y, space-x (item spacing)
+    if (utility.startsWith('space-y-') || utility.startsWith('space-x-')) {
+      const value = utility.slice(8);
+      const px = resolveSpacing(value);
+      if (px !== undefined) {
+        mappings.push({ tailwindClass: cls, property: 'gap', value: px });
+      }
+    }
+  }
+
+  return mappings;
+}
+
+/**
+ * Group classes by their state modifier
+ */
+export function groupClassesByState(classes: string[]): Record<string, string[]> {
+  const groups: Record<string, string[]> = {
+    default: [],
+  };
+
+  for (const cls of classes) {
+    const parsed = parseTailwindClass(cls);
+
+    if (parsed.state) {
+      // Normalize modifier to state name
+      let stateName = 'default';
+      if (parsed.state.includes('hover')) stateName = 'hover';
+      else if (parsed.state.includes('focus')) stateName = 'focus';
+      else if (parsed.state.includes('disabled') || parsed.state.includes('[disabled]')) stateName = 'disabled';
+      else if (parsed.state.includes('aria-invalid')) stateName = 'error';
+      else if (parsed.state.includes('active')) stateName = 'active';
+      else if (parsed.state.includes('checked')) stateName = 'checked';
+      else if (parsed.state.includes('open')) stateName = 'open';
+
+      if (!groups[stateName]) {
+        groups[stateName] = [];
+      }
+      groups[stateName].push(parsed.utility);
+    } else if (!parsed.modifier) {
+      groups.default.push(cls);
+    } else {
+      // Classes with only responsive/pseudo/dark modifiers go to default
+      groups.default.push(cls);
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Group classes by responsive breakpoint
+ */
+export function groupClassesByBreakpoint(classes: string[]): Record<string, string[]> {
+  const groups: Record<string, string[]> = {
+    base: [],
+  };
+
+  for (const cls of classes) {
+    const parsed = parseTailwindClass(cls);
+
+    if (parsed.responsive) {
+      const bp = parsed.responsive.replace(/:$/, '');
+      if (!groups[bp]) groups[bp] = [];
+      groups[bp].push(parsed.utility);
+    } else {
+      groups.base.push(cls);
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * Separate dark mode classes from light mode classes
+ */
+export function groupClassesByColorScheme(classes: string[]): { light: string[]; dark: string[] } {
+  const light: string[] = [];
+  const dark: string[] = [];
+
+  for (const cls of classes) {
+    const parsed = parseTailwindClass(cls);
+    if (parsed.isDark) {
+      dark.push(parsed.utility);
+    } else {
+      light.push(cls);
+    }
+  }
+
+  return { light, dark };
+}
+
+/**
+ * Infer layout properties from a set of Tailwind classes
+ */
+export function inferLayout(classes: string[]): import('./types').LayoutInfo {
+  const layout: import('./types').LayoutInfo = {
+    display: null,
+    direction: null,
+  };
+
+  for (const cls of classes) {
+    const parsed = parseTailwindClass(cls);
+    // Only look at base (non-responsive, non-state) classes for primary layout
+    if (parsed.modifier) continue;
+    const u = parsed.utility;
+
+    // Display
+    if (u === 'flex') layout.display = 'flex';
+    else if (u === 'grid') layout.display = 'grid';
+    else if (u === 'block') layout.display = 'block';
+    else if (u === 'inline' || u === 'inline-flex' || u === 'inline-block') layout.display = 'inline';
+    else if (u === 'hidden') layout.display = 'hidden';
+    else if (u === 'table') layout.display = 'table';
+    else if (u === 'contents') layout.display = 'contents';
+
+    // Direction
+    if (u === 'flex-row') layout.direction = 'row';
+    else if (u === 'flex-col') layout.direction = 'col';
+
+    // Wrap
+    if (u === 'flex-wrap') layout.wrap = true;
+    else if (u === 'flex-nowrap') layout.wrap = false;
+
+    // Gap
+    if (u.startsWith('gap-')) {
+      const val = u.slice(4);
+      const px = resolveSpacing(val);
+      if (px !== undefined) layout.gap = px;
+    }
+
+    // Padding
+    if (u.startsWith('p-') && !u.startsWith('px-') && !u.startsWith('py-') && !u.startsWith('pt-') && !u.startsWith('pb-') && !u.startsWith('pl-') && !u.startsWith('pr-') && !u.startsWith('ps-') && !u.startsWith('pe-')) {
+      const val = u.slice(2);
+      const px = resolveSpacing(val);
+      if (px !== undefined) layout.padding = { all: px };
+    }
+    if (u.startsWith('px-')) {
+      const val = u.slice(3);
+      const px = resolveSpacing(val);
+      if (px !== undefined) layout.padding = { ...layout.padding, x: px };
+    }
+    if (u.startsWith('py-')) {
+      const val = u.slice(3);
+      const px = resolveSpacing(val);
+      if (px !== undefined) layout.padding = { ...layout.padding, y: px };
+    }
+
+    // Alignment
+    if (u.startsWith('items-')) layout.alignment = u.slice(6);
+    if (u.startsWith('justify-')) layout.justification = u.slice(8);
+  }
+
+  // Default flex direction to row if display is flex and no explicit direction
+  if (layout.display === 'flex' && !layout.direction) {
+    layout.direction = 'row';
+  }
+
+  return layout;
+}
+
+/**
+ * Extract all unique color tokens used in a set of classes
+ */
+export function extractColorTokens(classes: string[]): string[] {
+  const tokens = new Set<string>();
+  const colorMappings = extractColorMappings(classes);
+
+  for (const mapping of colorMappings) {
+    tokens.add(mapping.tokenName);
+  }
+
+  return Array.from(tokens);
+}

package/scanner/transform-math-regression.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import {
+  centerPlacedRotationTransform,
+  rotationTransformAroundPointRadians,
+} from '../src/transform-math';
+
+function approxEqual(actual: number, expected: number, epsilon = 0.0001): void {
+  assert.ok(Math.abs(actual - expected) <= epsilon, `expected ${expected}, got ${actual}`);
+}
+
+function assertMatrix(
+  actual: [[number, number, number], [number, number, number]],
+  expected: [[number, number, number], [number, number, number]],
+): void {
+  approxEqual(actual[0][0], expected[0][0]);
+  approxEqual(actual[0][1], expected[0][1]);
+  approxEqual(actual[0][2], expected[0][2]);
+  approxEqual(actual[1][0], expected[1][0]);
+  approxEqual(actual[1][1], expected[1][1]);
+  approxEqual(actual[1][2], expected[1][2]);
+}
+
+// For 45° around normalized center, this should match previous hardcoded
+// Tailwind gradient direction matrix semantics.
+const angle = Math.PI / 4;
+const rotateCenter = rotationTransformAroundPointRadians(angle, 0.5, 0.5);
+const cos = Math.cos(angle);
+const sin = Math.sin(angle);
+assertMatrix(rotateCenter, [
+  [cos, -sin, 0.5 * (1 - cos + sin)],
+  [sin, cos, 0.5 * (1 - sin - cos)],
+]);
+
+// Hero reference case: width=1155, height=678, center=(32,339), rotation=30deg.
+// We keep this as a regression lock for blob center placement.
+const blobTransform = centerPlacedRotationTransform(1155, 678, 32, 339, 30);
+assertMatrix(blobTransform, [
+  [Math.cos(Math.PI / 6), -Math.sin(Math.PI / 6), -298.62967068551336],
+  [Math.sin(Math.PI / 6), Math.cos(Math.PI / 6), -243.33261188292465],
+]);
+
+console.log('transform math regression passed');