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

package/src/components/component-lookup.ts

@@ -0,0 +1,161 @@
+import { COMPONENT_DEFS } from '../tokens';
+import type { ComponentAnalysis, EnrichedComponentAnalysis } from '../../scanner/types';
+
+type RawComponentEntry = EnrichedComponentAnalysis | ComponentAnalysis;
+
+export type IconRegistryEntry = {
+  module: string;
+  exportName: string;
+  svg: string;
+};
+
+const REACT_ICON_MAP: Record<string, string> = {
+  HiOutlineHome: 'home',
+  HiHome: 'home',
+  RiTableView: 'portfolio',
+  HiMiniSquares2x2: 'portfolio',
+  RiCompass3Line: 'strategy',
+  RiWallet2Fill: 'pda',
+  RiAccountBoxLine: 'account',
+  HiLogout: 'logout',
+  RiLogoutBoxLine: 'logout',
+  HiMenu: 'menu',
+  HiX: 'close',
+  HiCheck: 'check',
+  ChevronDown: 'chevron-down',
+  ChevronDownIcon: 'chevron-down',
+};
+
+let COMPONENT_DEF_MAP: Record<string, RawComponentEntry> | null = null;
+let ICON_REGISTRY_MAP: Record<string, IconRegistryEntry> | null = null;
+
+export function resetComponentLookupCaches(): void {
+  COMPONENT_DEF_MAP = null;
+  ICON_REGISTRY_MAP = null;
+}
+
+function normalizeLookupKey(value: string): string {
+  return String(value || '').toLowerCase().trim();
+}
+
+function compactLookupKey(value: string): string {
+  return normalizeLookupKey(value).replace(/[^a-z0-9]/g, '');
+}
+
+function addLookupKey(map: Record<string, RawComponentEntry>, key: string, value: RawComponentEntry): void {
+  const normalized = normalizeLookupKey(key);
+  if (normalized && !map[normalized]) {
+    map[normalized] = value;
+  }
+  const compact = compactLookupKey(key);
+  if (compact && !map[compact]) {
+    map[compact] = value;
+  }
+}
+
+export function getComponentLookupCandidates(name: string): string[] {
+  return getLookupCandidates(name);
+}
+
+function getLookupCandidates(name: string): string[] {
+  const raw = normalizeLookupKey(name);
+  const out: string[] = [];
+  const seen: Record<string, true> = {};
+  const push = (candidate: string): void => {
+    const normalized = normalizeLookupKey(candidate);
+    if (!normalized || seen[normalized]) return;
+    seen[normalized] = true;
+    out.push(normalized);
+  };
+
+  push(raw);
+  push(compactLookupKey(raw));
+
+  const noRoot = raw.replace(/([._/\-])?root$/, '');
+  if (noRoot !== raw) {
+    push(noRoot);
+    push(compactLookupKey(noRoot));
+    const withoutPrimitive = noRoot.replace(/([._/\-])?primitive$/, '');
+    if (withoutPrimitive !== noRoot) {
+      push(withoutPrimitive);
+      push(compactLookupKey(withoutPrimitive));
+    }
+  }
+
+  const compact = compactLookupKey(raw);
+  if (compact.endsWith('root')) {
+    const compactNoRoot = compact.slice(0, -4);
+    push(compactNoRoot);
+    if (compactNoRoot.endsWith('primitive')) {
+      push(compactNoRoot.slice(0, -9));
+    }
+  }
+
+  if (compact.includes('primitive')) {
+    const compactNoPrimitive = compact.replace(/primitive/g, '');
+    push(compactNoPrimitive);
+    if (compactNoPrimitive.endsWith('root')) {
+      push(compactNoPrimitive.slice(0, -4));
+    }
+  }
+
+  return out;
+}
+
+export function getComponentDefByName(name: string): RawComponentEntry | null {
+  const defName = String(name || '');
+  if (!COMPONENT_DEF_MAP) {
+    COMPONENT_DEF_MAP = {};
+    const defsArray = ((COMPONENT_DEFS && COMPONENT_DEFS.components) ? COMPONENT_DEFS.components : []) as RawComponentEntry[];
+    for (let i = 0; i < defsArray.length; i++) {
+      const d = defsArray[i];
+      const analysis = 'analysis' in d ? d.analysis : d;
+      if (!analysis || !analysis.name) continue;
+      const key = String(analysis.name);
+      addLookupKey(COMPONENT_DEF_MAP, key, d);
+      // Also index under dash-stripped key so PascalCase JSX refs (e.g. "HeroSection")
+      // resolve to kebab-case scanner names (e.g. "Hero-section" → "herosection").
+      const dashlessKey = normalizeLookupKey(key).replace(/-/g, '');
+      addLookupKey(COMPONENT_DEF_MAP, dashlessKey, d);
+    }
+  }
+  const candidates = getLookupCandidates(defName);
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    if (COMPONENT_DEF_MAP[candidate]) {
+      return COMPONENT_DEF_MAP[candidate];
+    }
+  }
+  return null;
+}
+
+function getIconRegistry(): Record<string, IconRegistryEntry> {
+  if (ICON_REGISTRY_MAP) return ICON_REGISTRY_MAP;
+  const registry = (COMPONENT_DEFS && COMPONENT_DEFS.iconRegistry) ? COMPONENT_DEFS.iconRegistry : {};
+  ICON_REGISTRY_MAP = {};
+  for (const key in registry) {
+    ICON_REGISTRY_MAP[key] = registry[key];
+  }
+  return ICON_REGISTRY_MAP;
+}
+
+export function getIconRegistryEntry(name: string): IconRegistryEntry | null {
+  if (!name) return null;
+  const registry = getIconRegistry();
+  if (registry[name]) return registry[name];
+  const target = name.toLowerCase();
+  for (const key in registry) {
+    if (key.toLowerCase() === target) return registry[key];
+  }
+  return null;
+}
+
+export function getReactIconKey(name: string): string | null {
+  if (!name) return null;
+  if (REACT_ICON_MAP[name]) return REACT_ICON_MAP[name];
+  const target = name.toLowerCase();
+  for (const key in REACT_ICON_MAP) {
+    if (key.toLowerCase() === target) return REACT_ICON_MAP[key];
+  }
+  return null;
+}

package/src/components/index.ts

@@ -0,0 +1,7 @@
+export * from './component-defs';
+export * from './component-gen';
+export * from './component-instance';
+export * from './component-library';
+export * from './component-lookup';
+export * from './scanner-types';
+export * from './symbol-instance-policy';

package/src/components/scanner-types.ts

@@ -0,0 +1,39 @@
+/**
+ * Type aliases for the unstructured JSON shapes that flow from the
+ * scanner (tools/figma-plugin/scanner/) into the plugin runtime.
+ *
+ * These shapes have grown organically over many iterations and don't
+ * yet have a single canonical schema (the scanner emits one JSON blob,
+ * the plugin consumes parts of it from many call sites). Until the
+ * schema is formalized, these aliases give the consumers a *named*
+ * `any` so the call sites read intentionally — `def: ComponentDef`
+ * makes it obvious the parameter is a scanner-emitted def — rather
+ * than scattering bare `any` everywhere.
+ *
+ * Each alias is the only place `any` appears for that shape; consumers
+ * import the name and never see the literal `any`.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ComponentDef = any;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ComponentInstance = any;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ComponentStory = any;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CvaAnalysis = any;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type LayoutInfo = any;
+
+/**
+ * Type-erasure boundary used by InstanceBackend to accept differently-shaped
+ * ctx objects from each consumer (story-builder vs ui-builder). Each consumer
+ * passes its own typed ctx through to the backend's helper hooks; the backend
+ * itself doesn't reach into the shape.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type BackendCtx = any;

package/src/components/symbol-instance-policy.ts

@@ -0,0 +1,312 @@
+import { splitClassName } from '../tailwind';
+import type { ComponentDef, ComponentInstance } from './scanner-types';
+
+const IGNORED_SYMBOL_PROP_KEYS = new Set([
+  'className',
+  'children',
+  'placeholder',
+  'defaultValue',
+  'aria-invalid',
+  'disabled',
+  'ref',
+  'key',
+]);
+
+export type SymbolPolicyAnalysis = {
+  reason: string | null;
+  ignoredProps: string[];
+  slotPropMappings: Record<string, string>;
+};
+
+type TextPropInferenceStats = {
+  stringCount: number;
+  nonStringCount: number;
+  uniqueValues: Record<string, boolean>;
+  hasLikelyTextValue: boolean;
+  hasUrlLikeValue: boolean;
+  hasTokenLikeValue: boolean;
+};
+
+const SAFE_TEXT_PROP_CACHE: Record<string, string[] | undefined> = {};
+
+function pushUnique(out: string[], value: string): void {
+  if (!value) return;
+  if (out.indexOf(value) !== -1) return;
+  out.push(value);
+}
+
+export function isEventHandlerPropKey(key: string): boolean {
+  if (!key || key.length < 3) return false;
+  if (!(key[0] === 'o' && key[1] === 'n')) return false;
+  const firstSuffixChar = key[2];
+  return firstSuffixChar === firstSuffixChar.toUpperCase() && firstSuffixChar !== firstSuffixChar.toLowerCase();
+}
+
+export function isNonVisualA11yPropKey(key: string): boolean {
+  return key === 'aria-label'
+    || key === 'aria-labelledby'
+    || key === 'aria-describedby'
+    || key === 'aria-controls'
+    || key === 'aria-details';
+}
+
+export function isNonVisualMetaPropKey(key: string): boolean {
+  if (key === 'id' || key === 'role' || key === 'tabIndex') return true;
+  if (key === 'data-testid' || key === 'data-cy') return true;
+  return key.indexOf('data-test') === 0;
+}
+
+export function normalizeSlotKey(value: string | undefined): string {
+  return String(value || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+export function buildCompoundSlotAliasMap(def: ComponentDef): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!def || def.type !== 'compound') return out;
+  const subComponents = Array.isArray(def.subComponents) ? def.subComponents : [];
+  for (let i = 0; i < subComponents.length; i++) {
+    const sub = subComponents[i];
+    const slotName = String(sub && sub.slot ? sub.slot : '').toLowerCase();
+    if (!slotName) continue;
+    const slotNorm = normalizeSlotKey(slotName);
+    if (slotNorm) out[slotNorm] = slotName;
+
+    const subNameNorm = normalizeSlotKey(String(sub && sub.name ? sub.name : ''));
+    if (subNameNorm && !out[subNameNorm]) out[subNameNorm] = slotName;
+  }
+  return out;
+}
+
+export function extractCompoundSlotTextOverridesFromProps(def: ComponentDef, props: Record<string, unknown> | undefined): Record<string, string> {
+  const bySlot: Record<string, string> = {};
+  if (!def || def.type !== 'compound') return bySlot;
+  const slotAliases = buildCompoundSlotAliasMap(def);
+  const safeProps = props || {};
+  const keys = Object.keys(safeProps);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const canonicalSlot = slotAliases[normalizeSlotKey(key)];
+    if (!canonicalSlot) continue;
+    const value = safeProps[key];
+    if (value == null) continue;
+    const text = String(value).trim();
+    if (!text) continue;
+    bySlot[canonicalSlot] = text;
+  }
+  return bySlot;
+}
+
+export function isSafeTextOverridePropForNonCompound(def: ComponentDef, key: string, value: unknown): boolean {
+  if (!def || def.type === 'compound' || def.type === 'cva') return false;
+  if (typeof value !== 'string' || value.trim() === '') return false;
+  const text = String(value).trim();
+  if (isUrlLikeText(text)) return false;
+  const precomputed = getPrecomputedSafeTextOverridePropKeys(def);
+  const inferred = inferSafeTextOverridePropKeys(def);
+  if (inferred.indexOf(key) !== -1) return true;
+  if (precomputed.length > 0) return false;
+  // Fallback for components with sparse story coverage: allow clearly human text values.
+  return isLikelyVisibleTextValue(text);
+}
+
+export function isSafeCompoundSlotOverrideProp(def: ComponentDef, key: string, value: unknown): boolean {
+  if (!def || def.type !== 'compound') return false;
+  if (value == null) return false;
+  const text = String(value).trim();
+  if (!text) return false;
+  return getCompoundSlotForPropKey(def, key) !== null;
+}
+
+export function getCompoundSlotForPropKey(def: ComponentDef, key: string): string | null {
+  const slotAliases = buildCompoundSlotAliasMap(def);
+  return slotAliases[normalizeSlotKey(key)] || null;
+}
+
+export function analyzeSymbolPolicy(def: ComponentDef, instance: ComponentInstance): SymbolPolicyAnalysis {
+  const props = instance && instance.props ? instance.props : {};
+  const ignoredProps: string[] = [];
+  const slotPropMappings: Record<string, string> = {};
+  if (splitClassName(props.className).length > 0) {
+    return { reason: 'class_override', ignoredProps, slotPropMappings };
+  }
+
+  // Keep boolean/semantic state props on fallback path for visual correctness.
+  if (props['aria-invalid'] != null && String(props['aria-invalid']).toLowerCase() !== 'false') {
+    return { reason: 'aria_invalid_prop', ignoredProps, slotPropMappings };
+  }
+  if (props.disabled != null && String(props.disabled).toLowerCase() !== 'false') {
+    return { reason: 'disabled_prop', ignoredProps, slotPropMappings };
+  }
+
+  const keys = Object.keys(props || {});
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    if (IGNORED_SYMBOL_PROP_KEYS.has(key)) continue;
+    const value = props[key];
+    // Runtime/non-visual props should not force fallback rendering.
+    if (isEventHandlerPropKey(key)) {
+      pushUnique(ignoredProps, key);
+      continue;
+    }
+    if (isNonVisualA11yPropKey(key)) {
+      pushUnique(ignoredProps, key);
+      continue;
+    }
+    if (isNonVisualMetaPropKey(key)) {
+      pushUnique(ignoredProps, key);
+      continue;
+    }
+    if (isSafeTextOverridePropForNonCompound(def, key, value)) {
+      pushUnique(ignoredProps, key);
+      continue;
+    }
+    const mappedSlot = isSafeCompoundSlotOverrideProp(def, key, value)
+      ? getCompoundSlotForPropKey(def, key)
+      : null;
+    if (mappedSlot) {
+      pushUnique(ignoredProps, key);
+      slotPropMappings[key] = mappedSlot;
+      continue;
+    }
+    if (value == null) continue;
+    if (typeof value === 'string' && value.trim() === '') continue;
+    if (typeof value === 'function') continue;
+    return { reason: 'unsupported_prop:' + key, ignoredProps, slotPropMappings };
+  }
+  return { reason: null, ignoredProps, slotPropMappings };
+}
+
+export function getNonDefaultSymbolPropReason(def: ComponentDef, instance: ComponentInstance): string | null {
+  return analyzeSymbolPolicy(def, instance).reason;
+}
+
+function buildDefCacheKey(def: ComponentDef): string {
+  const name = String(def && def.name ? def.name : '');
+  const filePath = String(def && def.filePath ? def.filePath : '');
+  const type = String(def && def.type ? def.type : '');
+  return name + '|' + filePath + '|' + type;
+}
+
+function normalizeComponentName(name: string | undefined): string {
+  return String(name || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+function isMatchingInstanceForDef(def: ComponentDef, instance: ComponentInstance): boolean {
+  if (!def || !instance || !instance.componentName) return false;
+  return normalizeComponentName(instance.componentName) === normalizeComponentName(def.name);
+}
+
+function isLikelyVisibleTextValue(value: string): boolean {
+  const text = String(value || '').trim();
+  if (!text) return false;
+  if (isUrlLikeText(text)) return false;
+  if (/\s/.test(text)) return true;
+  if (/[.!?,:;()]/.test(text)) return true;
+  if (text.length >= 12) return true;
+  if (/^[A-Z]/.test(text)) return true;
+  return false;
+}
+
+function isUrlLikeText(value: string): boolean {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return false;
+  return text.indexOf('http://') === 0
+    || text.indexOf('https://') === 0
+    || text.indexOf('mailto:') === 0
+    || text.indexOf('tel:') === 0
+    || text.indexOf('/') === 0
+    || text.indexOf('#') === 0;
+}
+
+function isTokenLikeText(value: string): boolean {
+  const text = String(value || '').trim();
+  if (!text) return false;
+  return /^[a-z0-9_-]+$/.test(text);
+}
+
+function buildTextPropInference(def: ComponentDef): Record<string, TextPropInferenceStats> {
+  const statsByKey: Record<string, TextPropInferenceStats> = {};
+  const stories = def && Array.isArray(def.stories) ? def.stories : [];
+  for (let i = 0; i < stories.length; i++) {
+    const story = stories[i];
+    const instances = story && Array.isArray(story.instances) ? story.instances : [];
+    for (let j = 0; j < instances.length; j++) {
+      const instance = instances[j];
+      if (!isMatchingInstanceForDef(def, instance)) continue;
+      const props = instance && instance.props ? instance.props : {};
+      const keys = Object.keys(props);
+      for (let k = 0; k < keys.length; k++) {
+        const key = keys[k];
+        if (IGNORED_SYMBOL_PROP_KEYS.has(key)) continue;
+        const value = props[key];
+        if (value == null) continue;
+        if (!statsByKey[key]) {
+          statsByKey[key] = {
+            stringCount: 0,
+            nonStringCount: 0,
+            uniqueValues: {},
+            hasLikelyTextValue: false,
+            hasUrlLikeValue: false,
+            hasTokenLikeValue: false,
+          };
+        }
+        const stats = statsByKey[key];
+        if (typeof value !== 'string') {
+          stats.nonStringCount++;
+          continue;
+        }
+        const text = value.trim();
+        if (!text) continue;
+        stats.stringCount++;
+        stats.uniqueValues[text] = true;
+        if (isLikelyVisibleTextValue(text)) stats.hasLikelyTextValue = true;
+        if (isUrlLikeText(text)) stats.hasUrlLikeValue = true;
+        if (isTokenLikeText(text)) stats.hasTokenLikeValue = true;
+      }
+    }
+  }
+  return statsByKey;
+}
+
+function getPrecomputedSafeTextOverridePropKeys(def: ComponentDef): string[] {
+  const raw = def && Array.isArray(def.safeTextOverrideProps)
+    ? def.safeTextOverrideProps
+    : [];
+  const out: string[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    const key = String(raw[i] || '').trim();
+    if (!key) continue;
+    if (out.indexOf(key) !== -1) continue;
+    out.push(key);
+  }
+  return out;
+}
+
+export function inferSafeTextOverridePropKeys(def: ComponentDef): string[] {
+  if (!def || def.type === 'compound' || def.type === 'cva') return [];
+  const precomputed = getPrecomputedSafeTextOverridePropKeys(def);
+  if (precomputed.length > 0) return precomputed;
+  const cacheKey = buildDefCacheKey(def);
+  const cached = SAFE_TEXT_PROP_CACHE[cacheKey];
+  if (cached) return cached.slice();
+
+  const statsByKey = buildTextPropInference(def);
+  const out: string[] = [];
+  const keys = Object.keys(statsByKey);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const stats = statsByKey[key];
+    if (!stats) continue;
+    if (isEventHandlerPropKey(key) || isNonVisualA11yPropKey(key) || isNonVisualMetaPropKey(key)) continue;
+    if (stats.nonStringCount > 0 || stats.stringCount === 0) continue;
+    const uniqueCount = Object.keys(stats.uniqueValues).length;
+    const hasEvidence = stats.hasLikelyTextValue || uniqueCount > 1;
+    if (!hasEvidence) continue;
+    // Avoid props that look purely URL/token-like across all observed stories.
+    if (stats.hasUrlLikeValue && !stats.hasLikelyTextValue) continue;
+    if (stats.hasTokenLikeValue && !stats.hasLikelyTextValue && uniqueCount <= 1) continue;
+    out.push(key);
+  }
+  SAFE_TEXT_PROP_CACHE[cacheKey] = out.slice();
+  return out;
+}

package/src/design-system/block-cache.ts

@@ -0,0 +1,130 @@
+import type { ComponentDef } from '../components';
+
+/**
+ * Finds existing component-block frames on a page (or any subtree). Two
+ * matching strategies, tried in order:
+ *
+ * 1. `inkbridge:role` plugin data set to `component-block:...:<name>` — the
+ *    canonical path. Survives user-driven frame renames and is set by the
+ *    builder when blocks are generated.
+ * 2. Legacy name + structural fallback — frame's own name matches AND it
+ *    contains a `Story Layout` child. Catches blocks generated before the
+ *    plugin data tagging landed.
+ */
+export function findComponentBlocksInPage(root: BaseNode, name: string): SceneNode[] {
+  const out: SceneNode[] = [];
+  if (!root || !('children' in root) || !Array.isArray(root.children)) return out;
+
+  function getGeneratedRole(node: SceneNode): string {
+    try {
+      return (node && typeof node.getPluginData === 'function')
+        ? (node.getPluginData('inkbridge:role') || '')
+        : '';
+    } catch (_e) {
+      return '';
+    }
+  }
+
+  function roleMatchesComponent(role: string, componentName: string): boolean {
+    if (!role || role.indexOf('component-block:') !== 0) return false;
+    const parts = role.split(':');
+    if (parts.length < 4) return false;
+    return parts[parts.length - 1] === componentName;
+  }
+
+  const visit = (node: BaseNode): void => {
+    if (!node || !('children' in node) || !Array.isArray(node.children)) return;
+    for (let i = 0; i < node.children.length; i++) {
+      const child = node.children[i];
+      if (!child) continue;
+      const role = getGeneratedRole(child);
+      // Primary matching path: generated metadata is explicit and resilient to
+      // user renames or future block node type changes.
+      if (roleMatchesComponent(role, name)) {
+        out.push(child);
+        continue;
+      }
+      // Legacy fallback: match by structure for older untagged blocks.
+      if (!role && child.name === name && 'children' in child && Array.isArray(child.children)) {
+        let hasStoryLayout = false;
+        for (let ci = 0; ci < child.children.length; ci++) {
+          if (child.children[ci] && child.children[ci].name === 'Story Layout') {
+            hasStoryLayout = true;
+            break;
+          }
+        }
+        if (hasStoryLayout) {
+          out.push(child);
+          continue;
+        }
+      }
+      if ('children' in child) visit(child);
+    }
+  };
+
+  visit(root);
+  return out;
+}
+
+/**
+ * Parses a stored `inkbridge:hash` plugin-data value into its parts. Stored
+ * format is `defHash:tokenHash:engineHash` (engineHash optional for legacy
+ * pre-engine-aware blocks). Returns null for unparseable input.
+ */
+export function parseStoredBlockHash(value: string | null): { defHash: string; tokenHash: string; engineHash: string | null } | null {
+  if (!value || typeof value !== 'string') return null;
+  const parts = value.split(':');
+  if (parts.length < 2) return null;
+  return {
+    defHash: parts[0],
+    tokenHash: parts[1],
+    engineHash: parts.length > 2 ? parts.slice(2).join(':') : null,
+  };
+}
+
+/**
+ * True when the stored hash represents the same def + token as the current
+ * render. The engine segment is tolerated as a free variable so render-engine
+ * upgrades don't force every block to rebuild; the def+token equality is the
+ * load-bearing check.
+ */
+export function blockHashMatchesCurrent(
+  storedHash: string | null,
+  defHash: string,
+  tokenHash: string,
+  engineHash: string
+): boolean {
+  if (!storedHash) return false;
+  const exact = defHash + ':' + tokenHash + ':' + engineHash;
+  if (storedHash === exact) return true;
+
+  // Backward compatibility:
+  // - pre-engine format: def:token
+  // - engine/hash migration: same def+token but different engine segment
+  const parsed = parseStoredBlockHash(storedHash);
+  return !!parsed && parsed.defHash === defHash && parsed.tokenHash === tokenHash;
+}
+
+/**
+ * Mirror of `normalizeComponentDef` in ui-builder.ts (no spread — `Object.assign`).
+ * Keeps computePreflightData independent of ui-builder to avoid circular
+ * imports. Hoists `def.analysis` fields onto the top-level def shape while
+ * preserving classification metadata (`kind`, `usesCount`, etc.) from the raw
+ * scanner output.
+ */
+export function normalizeForPreflight(raw: ComponentDef): ComponentDef {
+  if (!raw || !raw.analysis) return raw;
+  return Object.assign({}, raw.analysis, {
+    filePath: raw.analysis.filePath || raw.filePath,
+    stories: Array.isArray(raw.analysis.stories)
+      ? raw.analysis.stories
+      : (Array.isArray(raw.stories) ? raw.stories : []),
+    hasStory: typeof raw.analysis.hasStory === 'boolean'
+      ? raw.analysis.hasStory
+      : !!raw.hasStory,
+    kind: raw.kind,
+    usesCount: raw.usesCount,
+    usedByCount: raw.usedByCount,
+    isLeaf: raw.isLeaf,
+  });
+}