inkbridge 0.1.0-beta.20 → 0.1.0-beta.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inkbridge",
-  "version": "0.1.0-beta.20",
+  "version": "0.1.0-beta.21",
   "description": "Generate a Figma design system from your Storybook stories — Tailwind React components rendered as native frames, design tokens, component states, and round-trip code sync.",
   "type": "module",
   "bin": {
@@ -76,6 +76,8 @@
     "test:cva-jsx-child-fallback": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/cva-jsx-child-fallback-regression.ts",
     "test:cva-master-icon": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/cva-master-icon-regression.ts",
     "test:data-attr-prop-alias": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/data-attr-prop-alias-regression.ts",
+    "test:jsx-prop-unresolved": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/jsx-prop-unresolved-regression.ts",
+    "test:grid-cols-extraction": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/grid-cols-extraction-regression.ts",
     "test:explicit-size-root": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/explicit-size-root-regression.ts",
     "test:image-src-collector": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/image-src-collector-regression.ts",
     "test:size-full-normalization": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/size-full-normalization-regression.ts",
@@ -89,8 +91,12 @@
     "test:svg-marker-inline": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/svg-marker-inline-regression.ts",
     "test:bundle-size": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/bundle-size-regression.ts",
     "test:ring-utility": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/ring-utility-regression.ts",
+    "test:adapter-utils": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/adapter-utils-regression.ts",
+    "test:input-range": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/input-range-regression.ts",
+    "test:font-family-extract": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/font-family-extract-regression.ts",
+    "test:local-const-className": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/local-const-className-regression.ts",
     "docs:audit": "node ./scripts/docs-audit.mjs",
-    "verify": "pnpm run scan && pnpm run test:blob && pnpm run test:tokens && pnpm run test:font && pnpm run test:radial && pnpm run test:transform && pnpm run test:csspatch && pnpm run test:state-classification && pnpm run test:component-sections && pnpm run test:block-cache && pnpm run test:story-dimensioning && pnpm run test:story-render-strategy && pnpm run test:render-prop-parser && pnpm run test:story-diagnostics && pnpm run test:instance-rendering && pnpm run test:layout-spacing && pnpm run test:layout-sizing && pnpm run test:layout-alignment && pnpm run test:layout-flex && pnpm run test:layout-mode && pnpm run test:svg-marker && pnpm run test:aspect-ratio && pnpm run test:percent-position && pnpm run test:svg-fill-parent && pnpm run test:inline-flex && pnpm run test:child-sizing-matrix && pnpm run test:full-width-matrix && pnpm run test:text-resize-matrix && pnpm run test:provider-flatten && pnpm run test:provider-cascade && pnpm run test:selection-pressed && pnpm run test:cva-jsx-child-fallback && pnpm run test:cva-master-icon && pnpm run test:data-attr-prop-alias && pnpm run test:explicit-size-root && pnpm run test:image-src-collector && pnpm run test:size-full-normalization && pnpm run test:stretch-to-parent-width && pnpm run test:framework-adapter-shadcn && pnpm run test:compound-classes-lookup && pnpm run test:sandbox-spread && pnpm run test:jsx-text && pnpm run test:aspect-percent && pnpm run test:svg-group-inherit && pnpm run test:svg-marker-inline && pnpm run test:ring-utility && pnpm run docs:audit && pnpm run build && pnpm run test:bundle-size",
+    "verify": "pnpm run scan && pnpm run test:blob && pnpm run test:tokens && pnpm run test:font && pnpm run test:radial && pnpm run test:transform && pnpm run test:csspatch && pnpm run test:state-classification && pnpm run test:component-sections && pnpm run test:block-cache && pnpm run test:story-dimensioning && pnpm run test:story-render-strategy && pnpm run test:render-prop-parser && pnpm run test:story-diagnostics && pnpm run test:instance-rendering && pnpm run test:layout-spacing && pnpm run test:layout-sizing && pnpm run test:layout-alignment && pnpm run test:layout-flex && pnpm run test:layout-mode && pnpm run test:svg-marker && pnpm run test:aspect-ratio && pnpm run test:percent-position && pnpm run test:svg-fill-parent && pnpm run test:inline-flex && pnpm run test:child-sizing-matrix && pnpm run test:full-width-matrix && pnpm run test:text-resize-matrix && pnpm run test:provider-flatten && pnpm run test:provider-cascade && pnpm run test:selection-pressed && pnpm run test:cva-jsx-child-fallback && pnpm run test:cva-master-icon && pnpm run test:data-attr-prop-alias && pnpm run test:jsx-prop-unresolved && pnpm run test:grid-cols-extraction && pnpm run test:explicit-size-root && pnpm run test:image-src-collector && pnpm run test:size-full-normalization && pnpm run test:stretch-to-parent-width && pnpm run test:framework-adapter-shadcn && pnpm run test:compound-classes-lookup && pnpm run test:sandbox-spread && pnpm run test:jsx-text && pnpm run test:aspect-percent && pnpm run test:svg-group-inherit && pnpm run test:svg-marker-inline && pnpm run test:ring-utility && pnpm run test:adapter-utils && pnpm run test:input-range && pnpm run test:font-family-extract && pnpm run test:local-const-className && pnpm run docs:audit && pnpm run build && pnpm run test:bundle-size",
     "release:beta": "pnpm publish --tag beta && npm dist-tag add inkbridge@$npm_package_version latest && npm view inkbridge dist-tags"
   }
 }

package/scanner/adapter-utils-regression.ts

@@ -0,0 +1,159 @@
+import assert from 'node:assert/strict';
+
+import {
+  isClassedElement,
+  mergeMissing,
+  resolveValuePercents,
+} from '../src/tailwind/adapter-utils';
+import type { NodeIR } from '../src/tailwind/node-ir';
+
+/**
+ * Regression: `src/tailwind/adapter-utils.ts` is the shared toolbox both
+ * `framework-adapters/shadcn.ts` and `tailwind/node-ir.ts`'s native-HTML
+ * transforms call into. If these helpers drift, both adapters
+ * silently break — shadcn Slider thumbs end up at wrong positions and
+ * `<input type=range>` rewrites compute the wrong fill width.
+ */
+
+// ---------------------------------------------------------------------------
+// isClassedElement
+// ---------------------------------------------------------------------------
+
+{
+  const el: NodeIR = {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes: [],
+    children: [],
+  };
+  const comp: NodeIR = {
+    kind: 'component',
+    tagName: 'Button',
+    tagLower: 'button',
+    props: {},
+    classes: [],
+    children: [],
+  };
+  const text: NodeIR = { kind: 'text', text: 'x' };
+  const frag: NodeIR = { kind: 'fragment', children: [] };
+
+  assert.equal(isClassedElement(el), true, 'element is classed');
+  assert.equal(isClassedElement(comp), true, 'component is classed');
+  assert.equal(isClassedElement(text), false, 'text is not classed');
+  assert.equal(isClassedElement(frag), false, 'fragment is not classed');
+}
+
+// ---------------------------------------------------------------------------
+// mergeMissing
+// ---------------------------------------------------------------------------
+
+{
+  // Empty extras → return existing by reference (cache-friendly).
+  const existing = ['a', 'b'];
+  const out = mergeMissing(existing, []);
+  assert.equal(out, existing, 'empty extras returns existing by reference');
+}
+
+{
+  // All extras already present → return existing by reference.
+  const existing = ['a', 'b', 'c'];
+  const out = mergeMissing(existing, ['b', 'c']);
+  assert.equal(out, existing, 'all present returns existing by reference');
+}
+
+{
+  // Some extras new → return a new array with originals + new ones in order.
+  const existing = ['a', 'b'];
+  const out = mergeMissing(existing, ['b', 'c', 'd']);
+  assert.notEqual(out, existing, 'new extras return a new array');
+  assert.deepEqual(out, ['a', 'b', 'c', 'd'], 'preserves order, de-dupes b');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — basic numeric input
+// ---------------------------------------------------------------------------
+
+{
+  // Default min=0, max=100: value 25 → 25%.
+  assert.deepEqual(resolveValuePercents(25, undefined, undefined), [25]);
+  // Default behavior with explicit undefined.
+  assert.deepEqual(resolveValuePercents(50, 0, 100), [50]);
+}
+
+{
+  // Non-zero min: (value - min) / (max - min) * 100.
+  // value=5, min=1.1, max=100 → ((5 - 1.1) / (100 - 1.1)) * 100 ≈ 3.9434
+  const out = resolveValuePercents(5, 1.1, 100);
+  assert.equal(out.length, 1);
+  assert.ok(Math.abs(out[0] - 3.9434) < 0.001, `got ${out[0]}`);
+}
+
+{
+  // Clamped to 0..100.
+  assert.deepEqual(resolveValuePercents(-50, 0, 100), [0], 'below-min clamps to 0');
+  assert.deepEqual(resolveValuePercents(200, 0, 100), [100], 'above-max clamps to 100');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — stringified props (scanner emits everything as
+// string)
+// ---------------------------------------------------------------------------
+
+{
+  assert.deepEqual(resolveValuePercents('25', '0', '100'), [25]);
+  // String min/max with non-zero baseline.
+  const out = resolveValuePercents('50', '0', '200');
+  assert.deepEqual(out, [25], 'string 50/200 → 25%');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — JSON array string (shadcn Slider tuple)
+// ---------------------------------------------------------------------------
+
+{
+  const out = resolveValuePercents('[25, 75]', 0, 100);
+  assert.deepEqual(out, [25, 75], 'JSON tuple parses both values');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — actual array
+// ---------------------------------------------------------------------------
+
+{
+  const out = resolveValuePercents([10, 50, 90], 0, 100);
+  assert.deepEqual(out, [10, 50, 90]);
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — degenerate ranges
+// ---------------------------------------------------------------------------
+
+{
+  // min === max → fallback range of 100.
+  const out = resolveValuePercents(5, 5, 5);
+  assert.equal(out.length, 1);
+  assert.equal(out[0], 0, 'min===max with value=min yields 0%');
+}
+
+{
+  // max < min → fallback. We don't care about specific number, just no crash
+  // and a finite result.
+  const out = resolveValuePercents(50, 100, 0);
+  assert.equal(out.length, 1);
+  assert.ok(Number.isFinite(out[0]), 'inverted min/max stays finite');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — unparseable value falls back to [0]
+// ---------------------------------------------------------------------------
+
+{
+  assert.deepEqual(resolveValuePercents(undefined, 0, 100), [0]);
+  assert.deepEqual(resolveValuePercents(null, 0, 100), [0]);
+  assert.deepEqual(resolveValuePercents('not-a-number', 0, 100), [0]);
+  assert.deepEqual(resolveValuePercents('', 0, 100), [0]);
+}
+
+console.log('adapter-utils-regression: ok');

package/scanner/component-scanner.ts

@@ -27,7 +27,7 @@ import type {
   JsxText,
   IconImportSpec,
 } from './types';
-import { groupClassesByState, STATE_MODIFIERS } from './tailwind-parser';
+import { groupClassesByState, OWN_STATE_MODIFIERS } from './tailwind-parser';
 import { twMerge } from 'tailwind-merge';
 
 /**
@@ -146,6 +146,11 @@ export class ComponentScanner {
   // "analyzed, no cascade detected" — still cached to skip the body walk
   // on subsequent invocations of the same component.
   private providerCascadeNamesCache: WeakMap<Node, Set<string>>;
+  // Re-entry guard for `resolveLocalIdentifier` — prevents infinite recursion
+  // when a local const's initializer references another local const that
+  // (directly or transitively) references the first one. Keyed by
+  // `${filePath}:${name}` so unrelated identifiers don't block each other.
+  private localResolutionStack: Set<string> = new Set();
 
   constructor(config: ScannerConfig) {
     this.config = config;
@@ -485,9 +490,11 @@ export class ComponentScanner {
       return null;
     }
 
-    // Check if any classes have state modifiers
+    // Check if any classes have an OWN state modifier (excludes
+    // `group-*:` / `peer-*:` — those are passive reactions to a
+    // parent's state, not the component's own variant axis).
     const hasStateModifiers = allClasses.some(cls =>
-      STATE_MODIFIERS.some(mod => cls.startsWith(mod))
+      OWN_STATE_MODIFIERS.some(mod => cls.startsWith(mod))
     );
 
     if (!hasStateModifiers) {
@@ -590,7 +597,7 @@ export class ComponentScanner {
 
     const classes = className.split(/\s+/).filter(Boolean);
     for (const cls of classes) {
-      for (const modifier of STATE_MODIFIERS) {
+      for (const modifier of OWN_STATE_MODIFIERS) {
         if (cls.startsWith(modifier)) {
           return true;
         }
@@ -920,6 +927,22 @@ export class ComponentScanner {
               //      `relativeImports`.
               if (!story.jsxTree) {
                 const argsContext = this.buildArgsPropsContext(args);
+                // Walk the args initializer AST so prop values that are
+                // arrays, objects, or identifiers referencing such
+                // (e.g. `blocks: mockBlocks`) resolve to their real
+                // structure — not the string-coerced text. Without
+                // this an args-based BlockTable story would see
+                // `blocks = "mockBlocks"` and the .map call inside the
+                // component couldn't resolve the iteration source.
+                for (const prop of argsInit.getProperties()) {
+                  if (!Node.isPropertyAssignment(prop)) continue;
+                  const propInit = prop.getInitializer();
+                  if (!propInit) continue;
+                  const resolved = this.resolveExpressionValue(propInit, new Map());
+                  if (resolved !== undefined && resolved !== null) {
+                    argsContext.set(prop.getName(), resolved);
+                  }
+                }
                 const localCompBody = localComponents.get(metaComponentName);
                 if (localCompBody) {
                   story.jsxTree = this.extractJsxTreeFromFunctionBody(
@@ -933,6 +956,26 @@ export class ComponentScanner {
                     ) || undefined;
                   }
                 }
+
+                // Inject `args.children` as a text node when the
+                // built tree has no element/text children of its own.
+                // Many shadcn primitives use `<Primitive {...props} />`
+                // to forward children, so the scanner sees a bare
+                // element — the children value lives in the args
+                // object but never makes it into the rendered tree.
+                // Without this an args-based `<Label>Email</Label>`
+                // story renders as an empty Label frame in Figma.
+                if (
+                  story.jsxTree
+                  && story.jsxTree.type === 'element'
+                  && (!story.jsxTree.children || story.jsxTree.children.length === 0)
+                  && typeof args.children === 'string'
+                  && args.children.length > 0
+                ) {
+                  story.jsxTree.children = [
+                    { type: 'text', content: args.children },
+                  ];
+                }
               }
             }
           }
@@ -1548,13 +1591,18 @@ export class ComponentScanner {
           } else if (expr && Node.isIdentifier(expr) && propsContext.has(expr.getText())) {
             this.pushResolvedPropValue(children, propsContext.get(expr.getText()));
           } else if (expr && Node.isIdentifier(expr)) {
-            // Try to resolve as a module-level const string (e.g. const LONG = "...")
-            const varDecl = node.getSourceFile().getVariableDeclaration(expr.getText());
-            if (varDecl) {
-              const init = varDecl.getInitializer();
-              if (init && Node.isStringLiteral(init)) {
-                children.push({ type: 'text', content: init.getLiteralValue() });
-              }
+            // Delegate to resolveExpressionValue so function-body-local `const`
+            // declarations (e.g. `const statusText = sourceLabel === "db" ? ...`)
+            // resolve the same way they do for className identifiers. Without
+            // this, a JSX text child like `<span>{statusText}</span>` falls
+            // through to the "unresolved" branch and renders nothing — even
+            // when the local const's initializer would resolve fine against
+            // the current propsContext. Same scope-walk fix as the className
+            // path; the bug only shows on JSX *children* because the children
+            // pipeline used a custom (module-level-only) lookup here.
+            const resolved = this.resolveExpressionValue(expr, propsContext);
+            if (resolved !== undefined && resolved !== null) {
+              this.pushResolvedPropValue(children, resolved);
             }
           } else if (expr && Node.isPropertyAccessExpression(expr)) {
             // Resolve {plan.name} style expressions when `plan` is an object in propsContext
@@ -2482,20 +2530,44 @@ export class ComponentScanner {
       return this.arrayValueCache.get(cacheKey)!;
     }
 
-    // Look for const declaration: const features = [...]
-    for (const varStmt of sourceFile.getVariableStatements()) {
+    // Look for `const features = [...]` style declarations. Walks ALL
+    // variable statements in the source file (top-level AND inside
+    // function bodies) so locally-scoped arrays like
+    // `function BlockTable() { const sortedBlocks = [...blocks].sort(...); ... }`
+    // resolve too — the canonical case is greenhouse-app's block-table
+    // where the .map source is a local sort over an imported JSON file.
+    //
+    // Initializer may be a direct array literal, a spread literal
+    // (`[...other]`), a method chain on an existing array
+    // (`[...blocks].sort(...)`, `data.filter(...).slice(0, N)`), or
+    // simply an identifier that points at another array (re-export).
+    // All of those routes funnel into `resolveArrayFromExpression`.
+    const allVarStatements = sourceFile.getDescendantsOfKind(SyntaxKind.VariableStatement);
+    for (const varStmt of allVarStatements) {
       for (const decl of varStmt.getDeclarationList().getDeclarations()) {
         if (decl.getName() === arrayName) {
-          const init = this.unwrapStaticValueExpression(decl.getInitializer());
-          if (init && Node.isArrayLiteralExpression(init)) {
-            const value = this.parseArrayLiteral(init);
-            this.arrayValueCache.set(cacheKey, value);
-            return value;
+          const init = this.unwrapStaticValueExpression(decl.getInitializer()) || decl.getInitializer();
+          if (init) {
+            const value = this.resolveArrayFromExpression(init, sourceFile);
+            if (value) {
+              this.arrayValueCache.set(cacheKey, value);
+              return value;
+            }
           }
         }
       }
     }
 
+    // If the name is a default import of a `.json` file, load it from
+    // disk. Covers patterns like `import data from '~/constants/blocks.json'`
+    // followed by `.map(item => …)` over the imported array (block-table
+    // is the canonical case in greenhouse-app).
+    const jsonImported = this.resolveImportedJsonValue(arrayName, sourceFile);
+    if (Array.isArray(jsonImported)) {
+      this.arrayValueCache.set(cacheKey, jsonImported);
+      return jsonImported;
+    }
+
     // Look for default parameter value in function: function Comp({ features = defaultFeatures })
     for (const func of sourceFile.getFunctions()) {
       const params = func.getParameters();
@@ -2558,6 +2630,101 @@ export class ComponentScanner {
     return null;
   }
 
+  /**
+   * Resolve an expression to an array of items. Handles:
+   *
+   *   - `[a, b, c]`               — direct array literal (parsed verbatim)
+   *   - `[...items]`              — spread of another array (resolved
+   *                                 recursively against the source file)
+   *   - `items.sort(...)`         — array-returning method chains
+   *                                 (`sort`, `filter`, `slice`, `reverse`,
+   *                                 `toSorted`, `toReversed`, `with`) are
+   *                                 unwrapped to the receiver. We do not
+   *                                 *apply* the operation — for design-
+   *                                 system rendering, any non-empty sample
+   *                                 of items is good enough.
+   *   - identifier                — recurses through `findArrayValue`
+   *                                 (local var) and JSON-import resolution.
+   *
+   * Returns `null` when nothing resolvable is found; the caller then
+   * falls back to its placeholder-iteration path.
+   */
+  private resolveArrayFromExpression(expr: Node, sourceFile: SourceFile): ResolvedExpressionValue[] | null {
+    const unwrapped = this.unwrapStaticValueExpression(expr) || expr;
+
+    if (Node.isArrayLiteralExpression(unwrapped)) {
+      const elements = unwrapped.getElements();
+      if (elements.length === 1 && Node.isSpreadElement(elements[0])) {
+        // `[...items]` — unwrap to `items` and resolve that.
+        const spreadInner = (elements[0] as import('ts-morph').SpreadElement).getExpression();
+        return this.resolveArrayFromExpression(spreadInner, sourceFile);
+      }
+      return this.parseArrayLiteral(unwrapped);
+    }
+
+    if (Node.isCallExpression(unwrapped)) {
+      const callee = unwrapped.getExpression();
+      if (Node.isPropertyAccessExpression(callee)) {
+        const methodName = callee.getName();
+        const PASS_THROUGH_METHODS = new Set([
+          'sort', 'filter', 'slice', 'reverse',
+          'toSorted', 'toReversed', 'with', 'concat', 'flat', 'flatMap',
+        ]);
+        if (PASS_THROUGH_METHODS.has(methodName)) {
+          return this.resolveArrayFromExpression(callee.getExpression(), sourceFile);
+        }
+      }
+    }
+
+    if (Node.isIdentifier(unwrapped)) {
+      const name = unwrapped.getText();
+      const fromCache = this.findArrayValue(name, sourceFile);
+      if (fromCache) return fromCache;
+      const fromJson = this.resolveImportedJsonValue(name, sourceFile);
+      if (Array.isArray(fromJson)) return fromJson;
+    }
+
+    return null;
+  }
+
+  /**
+   * If `name` is a default-imported JSON file in `sourceFile` (e.g.
+   * `import blocks from '~/constants/blocks.json'`), load + parse the
+   * file from disk and return the value. Returns `null` for any other
+   * import shape (named imports, non-JSON files, unresolvable paths).
+   *
+   * Path-alias resolution piggybacks on the existing
+   * `resolveImportedComponentPath`, plus a JSON-only branch that probes
+   * the literal path (without `.tsx`/`.ts` candidates).
+   */
+  private resolveImportedJsonValue(name: string, sourceFile: SourceFile): unknown {
+    const fileDir = path.dirname(sourceFile.getFilePath());
+    for (const imp of sourceFile.getImportDeclarations()) {
+      const defaultImport = imp.getDefaultImport();
+      if (!defaultImport || defaultImport.getText() !== name) continue;
+      const moduleSpec = imp.getModuleSpecifierValue();
+      if (!moduleSpec.endsWith('.json')) return null;
+
+      let absPath: string | null = null;
+      if (moduleSpec.startsWith('./') || moduleSpec.startsWith('../')) {
+        absPath = path.resolve(fileDir, moduleSpec);
+      } else if (moduleSpec.startsWith('~/') || moduleSpec.startsWith('@/')) {
+        absPath = path.resolve(process.cwd(), 'src', moduleSpec.slice(2));
+      } else {
+        return null;
+      }
+
+      if (!fs.existsSync(absPath)) return null;
+      try {
+        const raw = fs.readFileSync(absPath, 'utf-8');
+        return JSON.parse(raw);
+      } catch (_e) {
+        return null;
+      }
+    }
+    return null;
+  }
+
   /**
    * Unwrap syntax wrappers around static values so declarations like
    * `const FAQS = [...] as const` still resolve to the underlying literal.
@@ -3741,6 +3908,59 @@ export class ComponentScanner {
     return null;
   }
 
+  /**
+   * Resolve an identifier against function-body / block-scoped `const`
+   * declarations, walking ancestor scopes from the reference site outward.
+   * Returns `undefined` if no scope-local declaration is found so the caller
+   * can fall back to module-level lookup.
+   *
+   * Necessary because `SourceFile.getVariableDeclaration` only sees top-level
+   * statements — anything declared inside a function body (the common
+   * `const dotClass = sourceLabel === "db" ? "..." : "..."` pattern used to
+   * derive Tailwind classes from a prop value) is invisible to it. Without
+   * this helper such derived classes silently collapse to "no class" in the
+   * scanner output even though the runtime evaluates them fine.
+   *
+   * Forward references (a `const` declared AFTER the reference site in the
+   * same scope) are skipped to match real JavaScript TDZ semantics.
+   *
+   * Cycle protection via `localResolutionStack` — re-entering the same
+   * `${filePath}:${name}` returns `undefined` instead of recursing forever.
+   */
+  private resolveLocalIdentifier(
+    name: string,
+    fromNode: Node,
+    propsContext: Map<string, ResolvedExpressionValue>,
+  ): ResolvedExpressionValue {
+    const filePath = fromNode.getSourceFile().getFilePath();
+    const stackKey = `${filePath}:${name}`;
+    if (this.localResolutionStack.has(stackKey)) return undefined;
+    const fromStart = fromNode.getStart();
+    let cursor: Node | undefined = fromNode.getParent();
+    while (cursor && !Node.isSourceFile(cursor)) {
+      if (Node.isBlock(cursor) || Node.isCaseClause(cursor) || Node.isDefaultClause(cursor)) {
+        for (const stmt of cursor.getStatements()) {
+          if (!Node.isVariableStatement(stmt)) continue;
+          // Skip forward references — match TDZ semantics.
+          if (stmt.getEnd() > fromStart) continue;
+          for (const decl of stmt.getDeclarationList().getDeclarations()) {
+            if (decl.getName() !== name) continue;
+            const init = decl.getInitializer();
+            if (!init) return undefined;
+            this.localResolutionStack.add(stackKey);
+            try {
+              return this.resolveExpressionValue(init, propsContext);
+            } finally {
+              this.localResolutionStack.delete(stackKey);
+            }
+          }
+        }
+      }
+      cursor = cursor.getParent();
+    }
+    return undefined;
+  }
+
   private resolveExpressionValue(expr: Node, propsContext: Map<string, ResolvedExpressionValue>): ResolvedExpressionValue {
     if (Node.isParenthesizedExpression(expr)) {
       return this.resolveExpressionValue(expr.getExpression(), propsContext);
@@ -3756,6 +3976,13 @@ export class ComponentScanner {
     if (exprText === 'false') return false;
     if (Node.isIdentifier(expr)) {
       if (propsContext.has(exprText)) return propsContext.get(exprText);
+      // Resolve function-body-local consts FIRST so they shadow module-level
+      // names — same rule JavaScript scoping enforces. Without this, a
+      // pattern like `const dotClass = sourceLabel === "db" ? "bg-emerald-500"
+      // : "bg-sky-400"` followed by `<span className={cn(base, dotClass)}/>`
+      // collapses to just `base` and the conditional color is dropped.
+      const localValue = this.resolveLocalIdentifier(exprText, expr, propsContext);
+      if (localValue !== undefined) return localValue;
       // Resolve module-level consts: strings, object literals (e.g.
       // `const WIDTH_CLASSNAMES = {...} as const;`), and array literals
       // (e.g. `const DEFAULT_WIDTHS = [...]`). Returning the parsed value
@@ -3898,6 +4125,24 @@ export class ComponentScanner {
           if (methodName === 'trim') return baseValue.trim();
           if (methodName === 'toString') return baseValue;
         }
+      } else if (Node.isIdentifier(calleeExpr)) {
+        // User-defined function call (e.g. `truncateHash(block.blockHash)`,
+        // `formatTimestamp(block.timestamp)`). We can't execute the
+        // function — that'd require evaluating arbitrary JS — but we
+        // CAN resolve the first argument and return it as a graceful
+        // fallback. Rendering "DKjW9hX6dqBE6aDgqdX7Ytqa…" as-is is
+        // better than rendering an empty cell. If the user's function
+        // does important formatting (e.g. truncation) the value will
+        // look longer than the runtime, but it's visible and obviously
+        // points at the right field. Skip well-known *side-effect*
+        // helpers like `console.*` so we don't surface noise.
+        const fnName = calleeExpr.getText();
+        if (fnName === 'console' || fnName.startsWith('use')) return undefined;
+        const firstArg = expr.getArguments()[0];
+        if (firstArg) {
+          const resolved = this.resolveExpressionValue(firstArg, propsContext);
+          if (resolved !== undefined && resolved !== null) return resolved;
+        }
       }
     }
     return undefined;
@@ -4163,7 +4408,19 @@ export class ComponentScanner {
           props[name] = this.parseLiteralValue(expr);
         } else if (expr) {
           const resolved = this.resolveExpressionValue(expr, propsContext);
-          props[name] = resolved !== undefined ? resolved : expr.getText();
+          if (resolved !== undefined) {
+            props[name] = resolved;
+          }
+          // Unresolved expression (typically an unresolved identifier like a
+          // function parameter with no default — e.g. `data-inset={inset}`
+          // where `inset` is undefined in the story). Falling back to
+          // `expr.getText()` here used to serialise the identifier *name*
+          // as the attribute's value (`"inset"`), which the variant engine
+          // mistook for "data-inset is present" and activated every
+          // `data-[inset]:` utility (e.g. DropdownMenuItem's
+          // `data-[inset]:pl-8`, leaving every item indented 32px when no
+          // story used `inset`). Omitting the prop matches React's runtime
+          // behaviour: `data-x={undefined}` renders no attribute.
         }
       }
     }