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

package/scanner/cva-master-icon-regression.ts

@@ -0,0 +1,315 @@
+import assert from 'node:assert/strict';
+
+import {
+  cvaInstanceHasOverridingJsxChildren,
+  cvaInstanceHasOverridingState,
+  getFirstElementJsxChildTagName,
+  MASTER_ICON_NAME_KEY,
+  tryCreateCvaComponentInstance,
+} from '../src/components/component-instance';
+
+// Regression: the smart fall-back in tryCreateCvaComponentInstance.
+//
+// Background: a CVA component used with JSX-element children (an icon)
+// can't be cleanly represented as a symbol instance, because Figma's
+// instance-property API can't per-instance-swap SVG vectors. So when an
+// instance's icon DIFFERS from the icon recorded on the master, we must
+// fall back to frame rendering. When they MATCH, the symbol instance
+// renders the same icon as the master would, so it's safe to use.
+//
+// History: an initial fix returned null for ANY CVA instance with element
+// children. That correctly preserved per-instance icons via frame
+// rendering but cost the symbol benefit for every Toggle/Toggle-group
+// instance — even cases like `Toggle.Sizes` where every item used the
+// same icon as the master. The smart fall-back keeps the symbol path
+// when icons match, falls back when they differ.
+//
+// This file tests:
+//   1. The pure helpers (predicate + tagName extractor).
+//   2. The end-to-end function with a minimal stubbed backend, asserting
+//      that match vs. differ produce instance vs. null per the contract.
+
+// ---------------------------------------------------------------------------
+// Helper-level cases
+// ---------------------------------------------------------------------------
+
+// cvaInstanceHasOverridingJsxChildren
+{
+  assert.equal(cvaInstanceHasOverridingJsxChildren(null), false, 'null props');
+  assert.equal(cvaInstanceHasOverridingJsxChildren({}), false, 'empty props');
+  assert.equal(
+    cvaInstanceHasOverridingJsxChildren({ __jsxChildren: [{ type: 'text', content: 'x' }] }),
+    false,
+    'text-only children do not override',
+  );
+  assert.equal(
+    cvaInstanceHasOverridingJsxChildren({
+      __jsxChildren: [{ type: 'element', tagName: 'Bold' }],
+    }),
+    true,
+    'a single element child overrides',
+  );
+}
+
+// getFirstElementJsxChildTagName
+{
+  assert.equal(getFirstElementJsxChildTagName(null), null, 'null returns null');
+  assert.equal(getFirstElementJsxChildTagName('not-an-array'), null, 'non-array returns null');
+  assert.equal(getFirstElementJsxChildTagName([]), null, 'empty array returns null');
+  assert.equal(
+    getFirstElementJsxChildTagName([{ type: 'text', content: 'Hello' }]),
+    null,
+    'text-only returns null (the predicate-side guard)',
+  );
+  assert.equal(
+    getFirstElementJsxChildTagName([{ type: 'element', tagName: 'Italic' }]),
+    'Italic',
+    'extracts first element tagName',
+  );
+  assert.equal(
+    getFirstElementJsxChildTagName([
+      { type: 'text', content: ' ' },
+      { type: 'element', tagName: 'Bold' },
+      { type: 'element', tagName: 'Italic' },
+    ]),
+    'Bold',
+    'extracts FIRST element tagName, skipping leading text',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// End-to-end cases — minimal stubbed backend + figmaInstance.
+// These are the cases the kind/type bug slipped through earlier: a unit
+// test of the helper passes while the full function silently mis-routes.
+// ---------------------------------------------------------------------------
+
+interface StubBackend {
+  enableSymbolMasters: boolean;
+  splitClassName: (s: string | undefined) => string[];
+  ensureCvaComponentSet: () => unknown;
+  getInstantiableComponent: () => StubComponent | null;
+  getCvaSelectionFromInstance: () => Record<string, string>;
+  toFigmaVariantPropertyName: (k: string) => string;
+  toFigmaVariantPropertyValue: (v: string) => string;
+  getInstanceTextOverride: () => string | null;
+  applyTextOverrideToInstance: () => boolean;
+  setGeneratedSymbolDebugData: () => void;
+}
+
+interface StubComponent {
+  type: 'COMPONENT';
+  iconNamePluginData: string;
+  getPluginData(key: string): string;
+  createInstance(): StubInstance;
+}
+
+interface StubInstance {
+  type: 'INSTANCE';
+  setProperties(_p: Record<string, string>): void;
+  fills: unknown[];
+}
+
+function makeStubComponent(iconName: string): StubComponent {
+  return {
+    type: 'COMPONENT',
+    iconNamePluginData: iconName,
+    getPluginData(key: string): string {
+      if (key === MASTER_ICON_NAME_KEY) return this.iconNamePluginData;
+      return '';
+    },
+    createInstance(): StubInstance {
+      return {
+        type: 'INSTANCE',
+        setProperties() { /* noop */ },
+        fills: [],
+      };
+    },
+  };
+}
+
+function makeBackend(master: StubComponent | null): StubBackend {
+  return {
+    enableSymbolMasters: true,
+    splitClassName: (s) => (s ? s.split(/\s+/).filter(Boolean) : []),
+    ensureCvaComponentSet: () => ({}),
+    getInstantiableComponent: () => master,
+    getCvaSelectionFromInstance: () => ({}),
+    toFigmaVariantPropertyName: (k) => k,
+    toFigmaVariantPropertyValue: (v) => v,
+    getInstanceTextOverride: () => null,
+    applyTextOverrideToInstance: () => false,
+    setGeneratedSymbolDebugData: () => { /* noop */ },
+  };
+}
+
+const cvaDef = {
+  type: 'cva',
+  name: 'Toggle',
+  variants: { variant: ['default', 'outline'], size: ['default'] },
+  defaultVariants: { variant: 'default', size: 'default' },
+} as const;
+
+// (a) Instance icon matches master icon → tryCreate succeeds (returns InstanceNode).
+{
+  const master = makeStubComponent('Bold');
+  const result = tryCreateCvaComponentInstance(
+    cvaDef as unknown as Parameters<typeof tryCreateCvaComponentInstance>[0],
+    {
+      componentName: 'Toggle',
+      props: {
+        __jsxChildren: [{ type: 'element', tagName: 'Bold' }],
+      },
+    },
+    'default',
+    {} as Parameters<typeof tryCreateCvaComponentInstance>[3],
+    makeBackend(master) as unknown as Parameters<typeof tryCreateCvaComponentInstance>[4],
+  );
+  assert.ok(result, 'matching icon must produce a symbol instance, got null');
+}
+
+// (b) Instance icon differs from master icon → tryCreate returns null (fall back).
+{
+  const master = makeStubComponent('Bold');
+  const result = tryCreateCvaComponentInstance(
+    cvaDef as unknown as Parameters<typeof tryCreateCvaComponentInstance>[0],
+    {
+      componentName: 'Toggle',
+      props: {
+        __jsxChildren: [{ type: 'element', tagName: 'Italic' }],
+      },
+    },
+    'default',
+    {} as Parameters<typeof tryCreateCvaComponentInstance>[3],
+    makeBackend(master) as unknown as Parameters<typeof tryCreateCvaComponentInstance>[4],
+  );
+  assert.equal(result, null, 'differing icon must trigger fall back (null), got an instance');
+}
+
+// (c) No element children (text only) → fall-back does NOT trigger; the
+// symbol-instance path proceeds even if master has a recorded icon
+// (text-override path handles the content).
+{
+  const master = makeStubComponent('Bold');
+  const result = tryCreateCvaComponentInstance(
+    cvaDef as unknown as Parameters<typeof tryCreateCvaComponentInstance>[0],
+    {
+      componentName: 'Toggle',
+      props: {
+        __jsxChildren: [{ type: 'text', content: 'Click me' }],
+      },
+    },
+    'default',
+    {} as Parameters<typeof tryCreateCvaComponentInstance>[3],
+    makeBackend(master) as unknown as Parameters<typeof tryCreateCvaComponentInstance>[4],
+  );
+  assert.ok(result, 'text-only children must NOT trigger fall back, got null');
+}
+
+// (d) Element child present but master has no recorded icon name (older
+// build, or no story-content for this variant) → fall back. Avoids
+// silently picking the wrong icon at instance time.
+{
+  const master = makeStubComponent('');
+  const result = tryCreateCvaComponentInstance(
+    cvaDef as unknown as Parameters<typeof tryCreateCvaComponentInstance>[0],
+    {
+      componentName: 'Toggle',
+      props: {
+        __jsxChildren: [{ type: 'element', tagName: 'Bold' }],
+      },
+    },
+    'default',
+    {} as Parameters<typeof tryCreateCvaComponentInstance>[3],
+    makeBackend(master) as unknown as Parameters<typeof tryCreateCvaComponentInstance>[4],
+  );
+  assert.equal(result, null, 'unknown master icon must fall back, got an instance');
+}
+
+// ---------------------------------------------------------------------------
+// State-overriding props (defaultPressed, defaultChecked, disabled, ...)
+// MUST also trigger fall-back, even when the icon matches. The master was
+// built from one story whose state is baked in — Figma instances can't
+// per-instance-activate the data-[X]:* CSS at render time.
+// ---------------------------------------------------------------------------
+
+// cvaInstanceHasOverridingState helper checks
+{
+  assert.equal(cvaInstanceHasOverridingState(null), false, 'null props');
+  assert.equal(cvaInstanceHasOverridingState({}), false, 'empty props');
+  assert.equal(
+    cvaInstanceHasOverridingState({ defaultPressed: 'true' }),
+    true,
+    'defaultPressed="true" triggers',
+  );
+  assert.equal(
+    cvaInstanceHasOverridingState({ defaultPressed: 'false' }),
+    false,
+    'defaultPressed="false" does NOT trigger — instance not in pressed state',
+  );
+  assert.equal(
+    cvaInstanceHasOverridingState({ defaultPressed: true }),
+    true,
+    'boolean defaultPressed=true triggers',
+  );
+  assert.equal(
+    cvaInstanceHasOverridingState({ defaultPressed: '' }),
+    true,
+    'bare attribute (defaultPressed without value) = empty string = truthy',
+  );
+  assert.equal(
+    cvaInstanceHasOverridingState({ disabled: 'true' }),
+    true,
+    'disabled triggers (visual state baked into master would differ)',
+  );
+  assert.equal(
+    cvaInstanceHasOverridingState({ 'aria-disabled': 'true' }),
+    false,
+    'aria-disabled alone is metadata — does NOT trigger fall-back',
+  );
+  assert.equal(
+    cvaInstanceHasOverridingState({ defaultChecked: 'true' }),
+    true,
+    'defaultChecked triggers (checkboxes / radios)',
+  );
+}
+
+// End-to-end: matching icon BUT defaultPressed=true → fall back so the
+// variant engine can activate data-[pressed]:* per-instance at render time.
+{
+  const master = makeStubComponent('Bold');
+  const result = tryCreateCvaComponentInstance(
+    cvaDef as unknown as Parameters<typeof tryCreateCvaComponentInstance>[0],
+    {
+      componentName: 'Toggle',
+      props: {
+        __jsxChildren: [{ type: 'element', tagName: 'Bold' }],
+        defaultPressed: 'true',
+      },
+    },
+    'default',
+    {} as Parameters<typeof tryCreateCvaComponentInstance>[3],
+    makeBackend(master) as unknown as Parameters<typeof tryCreateCvaComponentInstance>[4],
+  );
+  assert.equal(result, null, 'icon matches BUT defaultPressed=true must still fall back, got an instance');
+}
+
+// And the negative control: icon matches AND no state props → still uses
+// the symbol instance (pure happy path).
+{
+  const master = makeStubComponent('Bold');
+  const result = tryCreateCvaComponentInstance(
+    cvaDef as unknown as Parameters<typeof tryCreateCvaComponentInstance>[0],
+    {
+      componentName: 'Toggle',
+      props: {
+        __jsxChildren: [{ type: 'element', tagName: 'Bold' }],
+      },
+    },
+    'default',
+    {} as Parameters<typeof tryCreateCvaComponentInstance>[3],
+    makeBackend(master) as unknown as Parameters<typeof tryCreateCvaComponentInstance>[4],
+  );
+  assert.ok(result, 'icon matches and no state props → symbol instance (regression on (a))');
+}
+
+console.log('cva-master-icon-regression: PASS (4 helper + 4 e2e + 9 state-helper + 2 state-e2e cases)');

package/scanner/data-attr-prop-alias-regression.ts

@@ -0,0 +1,129 @@
+import assert from 'node:assert/strict';
+
+import { expandActiveConditionalVariants } from '../src/design-system/node-variants';
+import type { NodeIR } from '../src/tailwind';
+
+// Regression: Tailwind v4 `data-[X]:` conditional variants must resolve
+// when the consumer expresses the state via the JSX prop convention
+// (e.g. `defaultPressed`, `defaultChecked`, `disabled`) rather than a
+// literal `data-X` attribute. Without this, `data-[pressed]:bg-accent`
+// on a `<Toggle defaultPressed>` never activates — the variant engine
+// only sees `defaultPressed="true"`, never an actual `data-pressed`.
+//
+// History: pressed state on the Toggle.Pressed story rendered as default
+// (no `bg-accent`) because the engine only matched literal `data-*`. The
+// fix adds a DATA_ATTR_PROP_ALIASES table inside `getNodePropValue` so a
+// `data-*` lookup falls back to known prop-convention aliases.
+
+function makeComponentNode(props: Record<string, string>, classes: string[]): NodeIR {
+  return {
+    kind: 'component',
+    tagName: 'TogglePrimitive',
+    tagLower: 'toggleprimitive',
+    props,
+    classes: classes.slice(),
+    children: [],
+  };
+}
+
+interface Case {
+  name: string;
+  props: Record<string, string>;
+  classes: string[];
+  expectedAdded: string[];
+}
+
+const CASES: Case[] = [
+  // ---- data-pressed (Toggle/Toggle-group pressed state) -------------------
+  {
+    name: 'defaultPressed=true activates data-[pressed]:* classes',
+    props: { defaultPressed: 'true' },
+    classes: ['data-[pressed]:bg-accent', 'data-[pressed]:text-accent-foreground'],
+    expectedAdded: ['bg-accent', 'text-accent-foreground'],
+  },
+  {
+    name: 'pressed=true (alternate prop name) activates data-[pressed]:*',
+    props: { pressed: 'true' },
+    classes: ['data-[pressed]:bg-accent'],
+    expectedAdded: ['bg-accent'],
+  },
+  {
+    name: 'defaultPressed=false does NOT activate data-[pressed]:*',
+    props: { defaultPressed: 'false' },
+    classes: ['data-[pressed]:bg-accent'],
+    expectedAdded: [],
+  },
+  {
+    name: 'literal data-pressed attribute still works (and takes precedence)',
+    props: { 'data-pressed': 'true' },
+    classes: ['data-[pressed]:bg-accent'],
+    expectedAdded: ['bg-accent'],
+  },
+
+  // ---- data-disabled ------------------------------------------------------
+  {
+    name: 'disabled=true activates data-[disabled]:* classes',
+    props: { disabled: 'true' },
+    classes: ['data-[disabled]:opacity-50', 'data-[disabled]:pointer-events-none'],
+    expectedAdded: ['opacity-50', 'pointer-events-none'],
+  },
+  {
+    name: 'aria-disabled=true also activates data-[disabled]:*',
+    props: { 'aria-disabled': 'true' },
+    classes: ['data-[disabled]:opacity-50'],
+    expectedAdded: ['opacity-50'],
+  },
+
+  // ---- data-checked -------------------------------------------------------
+  {
+    name: 'defaultChecked=true activates data-[checked]:* classes',
+    props: { defaultChecked: 'true' },
+    classes: ['data-[checked]:bg-primary'],
+    expectedAdded: ['bg-primary'],
+  },
+
+  // ---- data-open ----------------------------------------------------------
+  {
+    name: 'defaultOpen=true activates data-[open]:* classes',
+    props: { defaultOpen: 'true' },
+    classes: ['data-[open]:rotate-180'],
+    expectedAdded: ['rotate-180'],
+  },
+
+  // ---- negative control --------------------------------------------------
+  {
+    name: 'unknown prop alias does NOT leak (e.g. defaultPressed does not activate data-[foo])',
+    props: { defaultPressed: 'true' },
+    classes: ['data-[foo]:bg-red-500'],
+    expectedAdded: [],
+  },
+
+  // ---- bare Tailwind v4 syntax (data-pressed: without brackets) ----------
+  {
+    name: 'bare `data-pressed:` selector also resolves via the alias',
+    props: { defaultPressed: 'true' },
+    classes: ['data-pressed:font-bold'],
+    expectedAdded: ['font-bold'],
+  },
+];
+
+let failed = 0;
+for (const c of CASES) {
+  const node = makeComponentNode(c.props, c.classes);
+  const result = expandActiveConditionalVariants(c.classes, node);
+  const addedUtilities = result.filter((cls) => !c.classes.includes(cls));
+  const sortedActual = addedUtilities.slice().sort();
+  const sortedExpected = c.expectedAdded.slice().sort();
+  if (JSON.stringify(sortedActual) !== JSON.stringify(sortedExpected)) {
+    console.error(`  ✗ ${c.name}`);
+    console.error(`    expected added: ${JSON.stringify(sortedExpected)}`);
+    console.error(`    actual added:   ${JSON.stringify(sortedActual)}`);
+    failed++;
+  }
+}
+
+if (failed > 0) {
+  assert.fail(`${failed}/${CASES.length} data-attr-prop-alias cases failed`);
+}
+
+console.log(`data-attr-prop-alias-regression: PASS (${CASES.length} cases)`);

package/scanner/explicit-size-root-regression.ts

@@ -0,0 +1,102 @@
+import assert from 'node:assert/strict';
+
+import { getNodeLayoutComputed } from '../src/layout/width-solver';
+import type { NodeIR } from '../src/tailwind';
+
+/**
+ * Regression: at depth=0 (story root) `buildFigmaNode` overrides the frame
+ * width with `context.maxWidth` (typically 900 — the page canvas) so that
+ * page-level containers fill the canvas. That override must NOT fire when
+ * the root element has an explicit width class (size-N / w-N / size-full
+ * etc.), or a 40×40 avatar becomes a 900-wide pill.
+ *
+ * The override is gated on `layoutComputed.hasExplicitSize`. This file
+ * locks the predicate: every variant of "explicit size" that downstream
+ * authors reasonably reach for must register as `hasExplicitSize=true`,
+ * and nothing else must.
+ *
+ * History: shadcn's `Avatar` is `<AvatarPrimitive.Root className="relative
+ * flex size-10 ...">`. `flattenComponentNodes` rewrites compound primitives
+ * to `kind: 'element', tagLower: 'div'` so they fall into the generic
+ * container path. There, the `depth === 0` width override kicked in and
+ * resized the 40×40 root to 900×40. The fix: skip the override when the
+ * element class list carries an explicit width. This regression keeps that
+ * decision intact.
+ */
+
+function el(classes: string[]): NodeIR {
+  return {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes,
+    children: [],
+  } as unknown as NodeIR;
+}
+
+// ---------------------------------------------------------------------------
+// Positive cases — these MUST register as hasExplicitSize.
+// ---------------------------------------------------------------------------
+
+const positives: Array<[string, string[]]> = [
+  ['size-10 (shadcn Avatar)', ['relative', 'flex', 'size-10', 'shrink-0']],
+  ['size-8 (small avatar)', ['size-8']],
+  ['size-12.5 (decimal allowed)', ['size-12.5']],
+  ['size-[40px] (arbitrary)', ['size-[40px]']],
+  ['size-full (avatar Image/Fallback)', ['size-full']],
+  ['w-10 (width only)', ['w-10']],
+  ['h-10 (height only)', ['h-10']],
+  ['w-[200px] (arbitrary width)', ['w-[200px]']],
+  ['h-[64px] (arbitrary height)', ['h-[64px]']],
+  ['w-full', ['w-full']],
+  ['h-full', ['h-full']],
+  ['w-1/2 (fractional)', ['w-1/2']],
+];
+
+for (const [label, classes] of positives) {
+  const computed = getNodeLayoutComputed(el(classes));
+  assert.equal(
+    computed.hasExplicitSize,
+    true,
+    'positive case must register hasExplicitSize=true: ' + label,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Negative cases — must NOT register. A page-level container with only
+// layout / padding / colors needs the depth=0 canvas-width override to
+// fire, otherwise full-page stories would collapse to hug width.
+// ---------------------------------------------------------------------------
+
+const negatives: Array<[string, string[]]> = [
+  ['empty class list', []],
+  ['layout only', ['flex', 'flex-col', 'gap-4']],
+  ['padding only', ['p-6', 'pt-8']],
+  ['bg + text only', ['bg-card', 'text-foreground']],
+  ['max-w-* alone (a cap, not a fixed width)', ['max-w-md']],
+  ['min-w-* alone', ['min-w-0']],
+  // size-* token alias like `size-full` is positive, but `size-fit` etc.
+  // are not handled by the plugin's sizing parser today — keep them OUT
+  // of the predicate until they are wired through so we don't silently
+  // suppress the canvas-width override for shapes the renderer can't size.
+  ['size-fit (not supported as fixed size)', ['size-fit']],
+  ['size-auto', ['size-auto']],
+];
+
+for (const [label, classes] of negatives) {
+  const computed = getNodeLayoutComputed(el(classes));
+  assert.equal(
+    computed.hasExplicitSize,
+    false,
+    'negative case must register hasExplicitSize=false: ' + label,
+  );
+}
+
+console.log(
+  'explicit-size-root-regression: PASS ('
+    + positives.length
+    + ' positive + '
+    + negatives.length
+    + ' negative cases)',
+);

package/scanner/font-family-extract-regression.ts

@@ -0,0 +1,113 @@
+import assert from 'node:assert/strict';
+
+import { extractFontName } from '../src/tokens/tokens';
+
+/**
+ * Regression: `extractFontName` in `src/tokens/tokens.ts` walks a
+ * comma-separated font stack and returns the first entry that ISN'T a
+ * system keyword / generic family / web-safe fallback / emoji-fallback
+ * font. The returned name is what's passed to `figma.loadFontAsync` —
+ * a wrong pick (e.g. "Apple Color Emoji" from Tailwind's default sans
+ * stack, or "ui-sans-serif" from a stack with no quoted font) throws
+ * "couldn't load font" inside the Figma sandbox.
+ *
+ * Bug that motivated this fixture: Tailwind's default sans-serif
+ * value is `ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
+ * 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'`. The original
+ * keyword set didn't include the emoji-fallback entries, so the resolver
+ * skipped past the three generic-family entries and picked "Apple Color
+ * Emoji" as the body font. The fix adds the four emoji fallbacks to
+ * SYSTEM_FONT_KEYWORDS.
+ */
+
+// ---------------------------------------------------------------------------
+// Quoted intended font in a Tailwind-style stack
+// ---------------------------------------------------------------------------
+
+assert.equal(
+  extractFontName('"Open Sans", ui-sans-serif, system-ui, sans-serif'),
+  'Open Sans',
+  'quoted family wins over generic-family fallbacks',
+);
+
+assert.equal(
+  extractFontName("'Inter', system-ui, sans-serif"),
+  'Inter',
+  'single-quoted name is unwrapped',
+);
+
+// ---------------------------------------------------------------------------
+// Tailwind default sans stack — the canonical "emoji bug" case
+// ---------------------------------------------------------------------------
+
+const tailwindDefaultSans =
+  "ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'";
+
+assert.equal(
+  extractFontName(tailwindDefaultSans),
+  null,
+  'stack of only generic-families + emoji-fallbacks returns null so the caller falls back',
+);
+
+// Variants of the same emoji-fallback names with/without quotes
+assert.equal(extractFontName('Apple Color Emoji'), null);
+assert.equal(extractFontName('"Apple Color Emoji"'), null);
+assert.equal(extractFontName("'Segoe UI Emoji'"), null);
+assert.equal(extractFontName('Noto Color Emoji'), null);
+assert.equal(extractFontName('Segoe UI Symbol'), null);
+
+// Case-insensitive: extractFontName lowercases before comparing
+assert.equal(extractFontName('APPLE COLOR EMOJI'), null);
+
+// Real-world: intended font wins even with the emoji fallbacks appended
+assert.equal(
+  extractFontName(`"Open Sans", ${tailwindDefaultSans}`),
+  'Open Sans',
+  'quoted intended font wins over the full Tailwind default tail',
+);
+
+// ---------------------------------------------------------------------------
+// Generic-family / system keywords are skipped
+// ---------------------------------------------------------------------------
+
+assert.equal(extractFontName('ui-sans-serif'), null);
+assert.equal(extractFontName('system-ui'), null);
+assert.equal(extractFontName('sans-serif'), null);
+assert.equal(extractFontName('-apple-system'), null);
+assert.equal(
+  extractFontName('Arial, Helvetica, sans-serif'),
+  null,
+  'web-safe-only stacks return null — the consumer hadn\'t picked a design font',
+);
+
+// ---------------------------------------------------------------------------
+// CSS variable references — return the derived name if no intended font
+// is present, but a real font name still wins
+// ---------------------------------------------------------------------------
+
+assert.equal(
+  extractFontName('var(--font-open-sans), ui-sans-serif, sans-serif'),
+  'Open Sans',
+  'var(--font-foo) derives a font name when nothing else matches',
+);
+
+assert.equal(
+  extractFontName('var(--font-geist-mono), monospace'),
+  'Geist Mono',
+);
+
+assert.equal(
+  extractFontName('"Inter", var(--font-fallback), sans-serif'),
+  'Inter',
+  'real quoted font beats var() fallback',
+);
+
+// ---------------------------------------------------------------------------
+// Edge cases
+// ---------------------------------------------------------------------------
+
+assert.equal(extractFontName(''), null);
+assert.equal(extractFontName(undefined), null);
+assert.equal(extractFontName(null), null);
+
+console.log('font-family-extract-regression: ok');

package/scanner/font-style-resolver-regression.ts

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { inferFontWeight, rankStylesForRequest } from '../src/font-style-resolver';
+import { inferFontWeight, rankStylesForRequest } from '../src/text/font-style-resolver';
 
 assert.equal(inferFontWeight('Regular'), 400);
 assert.equal(inferFontWeight('Medium'), 500);