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

package/src/design-system/story-instance.ts

@@ -0,0 +1,333 @@
+import { splitClassName, applyTailwindStylesToFrame, tailwindClassesToStyle } from '../tailwind';
+import { parseColor } from '../tokens';
+import { createTextNode } from '../text';
+import { enforceFixedBoxSizingAfterLayout } from '../layout';
+import {
+  analyzeSymbolPolicy,
+  extractCompoundSlotTextOverridesFromProps,
+  getInstantiableComponent,
+  tryCreateCvaComponentInstance as tryCreateCvaComponentInstanceShared,
+  tryCreateNonCvaComponentInstance as tryCreateNonCvaComponentInstanceShared,
+} from '../components';
+import { setGeneratedFallbackReason, setGeneratedSymbolDebugData } from './generated-node';
+import { getThemeContext } from './theme-context';
+import {
+  toFigmaVariantPropertyName,
+  toFigmaVariantPropertyValue,
+  ENABLE_SYMBOL_MASTERS,
+} from './master-shared';
+import {
+  ensureStateComponentSet,
+  isCheckedInstance,
+  hasCheckedStateVariant,
+  getStateVariantForInstance,
+} from './state-master';
+import {
+  ensureCvaComponentSet,
+  getCvaSelectionFromInstance,
+  isTruthyVariantValue,
+  applyStyleToFrame,
+  getCvaSymbolFallbackReason,
+} from './cva-master';
+import { buildCvaClassesWithSelection } from './cva-utils';
+import { getPreviewTypography } from './typography';
+import { createStateStoryFrame, createSimpleStoryFrame } from './story-frames';
+import { ensureNonCvaComponentMaster } from './non-cva-master';
+import {
+  getInstanceTextOverride,
+  applyTextOverrideToInstance,
+  getNonCvaSymbolFallbackReason,
+  getInstanceChildrenText,
+} from './symbol-fallback';
+import {
+  normalizeComponentName,
+  findBestStoryElementForClasses,
+  findFirstStoryText,
+} from './story-tree-search';
+import type { StoryBuilderContext } from './story-builder-context';
+
+/**
+ * Top-level story-instance entrypoints. The createX functions try the
+ * symbol-instance path first (via tryCreateXComponentInstance) and fall
+ * back to a freshly-rendered frame when no master is available.
+ *
+ * `componentInstanceBackend` is the wiring object passed to those
+ * try-create functions; it bundles all the predicates / accessors they
+ * need to read state from a def and apply text overrides to instances.
+ *
+ * The buildStoryX helpers are used by preview-builder for the state matrix
+ * and responsive previews.
+ */
+
+type CompoundTextOverrides = {
+  bySubcomponent: Record<string, string>;
+  bySlot: Record<string, string>;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildCompoundTextOverrides(def: any, story: any, instance?: any): CompoundTextOverrides {
+  const bySubcomponent: Record<string, string> = {};
+  const bySlot = extractCompoundSlotTextOverridesFromProps(def, instance && instance.props ? instance.props : {});
+  if (!def || def.type !== 'compound') return { bySubcomponent, bySlot };
+
+  const subComponents = Array.isArray(def.subComponents) ? def.subComponents : [];
+  const instances = (story && Array.isArray(story.instances)) ? story.instances : [];
+
+  for (let i = 0; i < subComponents.length; i++) {
+    const sub = subComponents[i];
+    const subName = normalizeComponentName(sub && sub.name ? sub.name : '');
+    const slotName = String(sub && sub.slot ? sub.slot : '').toLowerCase();
+    if (!subName) continue;
+    if (slotName && bySlot[slotName]) {
+      bySubcomponent[subName] = bySlot[slotName];
+      continue;
+    }
+
+    for (let j = 0; j < instances.length; j++) {
+      const instance = instances[j];
+      const instanceName = normalizeComponentName(instance && instance.componentName ? instance.componentName : '');
+      if (!instanceName || instanceName !== subName) continue;
+      const text = getInstanceChildrenText(instance);
+      if (!text) continue;
+      bySubcomponent[subName] = text;
+      if (slotName && !bySlot[slotName]) bySlot[slotName] = text;
+      break;
+    }
+  }
+
+  if (story && story.jsxTree) {
+    for (let i = 0; i < subComponents.length; i++) {
+      const sub = subComponents[i];
+      const subName = normalizeComponentName(sub && sub.name ? sub.name : '');
+      const slotName = String(sub && sub.slot ? sub.slot : '').toLowerCase();
+      const subClasses = Array.isArray(sub && sub.classes) ? sub.classes : [];
+      if (!subName || bySubcomponent[subName]) continue;
+      const match = findBestStoryElementForClasses(story.jsxTree, subClasses);
+      const text = findFirstStoryText(match);
+      if (!text) continue;
+      bySubcomponent[subName] = text;
+      if (slotName && !bySlot[slotName]) bySlot[slotName] = text;
+    }
+  }
+
+  return { bySubcomponent, bySlot };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function findFirstTextByAncestorPredicate(node: any, predicate: (name: string) => boolean, ancestry?: string[]): any | null {
+  if (!node) return null;
+  const trail = ancestry ? ancestry.slice() : [];
+  const nodeName = String(node.name || '');
+  if (nodeName) trail.push(nodeName);
+
+  if (node.type === 'TEXT') {
+    for (let i = 0; i < trail.length; i++) {
+      if (predicate(trail[i])) return node;
+    }
+  }
+
+  if (!Array.isArray(node.children)) return null;
+  for (let i = 0; i < node.children.length; i++) {
+    const found = findFirstTextByAncestorPredicate(node.children[i], predicate, trail);
+    if (found) return found;
+  }
+  return null;
+}
+
+function applyCompoundTextOverridesToInstance(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  def: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  story: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  storyInstance: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  instanceNode: any
+): { bySubcomponent: Record<string, string>; bySlot: Record<string, string> } {
+  const overrides = buildCompoundTextOverrides(def, story, storyInstance);
+  const appliedBySubcomponent: Record<string, string> = {};
+  const appliedBySlot: Record<string, string> = {};
+  const subComponents = Array.isArray(def && def.subComponents) ? def.subComponents : [];
+
+  for (let i = 0; i < subComponents.length; i++) {
+    const sub = subComponents[i];
+    const subNameRaw = String(sub && sub.name ? sub.name : '');
+    const subName = normalizeComponentName(subNameRaw);
+    const slotName = String(sub && sub.slot ? sub.slot : '').toLowerCase();
+    const value = overrides.bySubcomponent[subName] || (slotName ? overrides.bySlot[slotName] : '');
+    if (!value) continue;
+
+    let textNode = findFirstTextByAncestorPredicate(
+      instanceNode,
+      function(name: string): boolean {
+        return normalizeComponentName(name) === subName;
+      }
+    );
+
+    if (!textNode && slotName) {
+      textNode = findFirstTextByAncestorPredicate(
+        instanceNode,
+        function(name: string): boolean {
+          return normalizeComponentName(name).indexOf(normalizeComponentName(slotName)) !== -1;
+        }
+      );
+    }
+
+    if (!textNode) continue;
+    try {
+      textNode.characters = String(value);
+      if (subName) appliedBySubcomponent[subName] = String(value);
+      if (slotName) appliedBySlot[slotName] = String(value);
+    } catch (_error) {
+      // If override is blocked by component structure, keep default text.
+    }
+  }
+  return { bySubcomponent: appliedBySubcomponent, bySlot: appliedBySlot };
+}
+
+export const componentInstanceBackend = {
+  enableSymbolMasters: ENABLE_SYMBOL_MASTERS,
+  splitClassName,
+  ensureCvaComponentSet,
+  ensureStateComponentSet,
+  ensureNonCvaComponentMaster,
+  getInstantiableComponent,
+  getCvaSelectionFromInstance,
+  toFigmaVariantPropertyName,
+  toFigmaVariantPropertyValue,
+  getStateVariantForInstance,
+  isCheckedInstance,
+  hasCheckedStateVariant,
+  getInstanceTextOverride,
+  applyTextOverrideToInstance,
+  applyCompoundTextOverridesToInstance,
+  analyzeSymbolPolicy,
+  setGeneratedSymbolDebugData,
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildStatePreviewLabel(def: any, instance: any): string {
+  const props = instance && instance.props ? instance.props : {};
+  if (instance && instance.children) return String(instance.children);
+  if (props.children) return String(props.children);
+  if (props.placeholder) return String(props.placeholder);
+  if (props.defaultValue) return String(props.defaultValue);
+  return '';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildStoryStateClasses(def: any, instance: any): string[] {
+  const props = instance && instance.props ? instance.props : {};
+  const classes: string[] = [];
+
+  if (def && def.baseClasses) {
+    for (let i = 0; i < def.baseClasses.length; i++) classes.push(def.baseClasses[i]);
+  }
+
+  if (def && def.type === 'cva') {
+    const variantKeys = Object.keys(def.variants || {});
+    for (let i = 0; i < variantKeys.length; i++) {
+      const key = variantKeys[i];
+      const value = props[key] || (def.defaultVariants && def.defaultVariants[key]) || (def.variants[key] && def.variants[key][0]);
+      if (value && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+        const variantClasses = def.variantClasses[key][value];
+        for (let j = 0; j < variantClasses.length; j++) classes.push(variantClasses[j]);
+      }
+    }
+  }
+
+  const extra = splitClassName(props.className);
+  for (let i = 0; i < extra.length; i++) classes.push(extra[i]);
+  return classes;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildStoryInstanceClasses(def: any, instance: any): string[] {
+  const props = instance && instance.props ? instance.props : {};
+  let classes: string[] = def && def.baseClasses ? def.baseClasses.slice() : [];
+
+  if (def && def.type === 'cva') {
+    const variantKeys = Object.keys(def.variants || {});
+    for (let i = 0; i < variantKeys.length; i++) {
+      const key = variantKeys[i];
+      const value = props[key]
+        || (def.defaultVariants && def.defaultVariants[key])
+        || (def.variants && def.variants[key] && def.variants[key][0]);
+      if (value && def.variantClasses && def.variantClasses[key] && def.variantClasses[key][value]) {
+        classes = classes.concat(def.variantClasses[key][value]);
+      }
+    }
+  }
+
+  const extra = splitClassName(props.className);
+  if (extra.length > 0) {
+    classes = classes.concat(extra);
+  }
+
+  return classes;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createCVAStoryInstance(def: any, instance: any, theme: string, ctx: StoryBuilderContext): any {
+  const componentInstance = tryCreateCvaComponentInstanceShared(def, instance, theme, ctx, componentInstanceBackend);
+  if (componentInstance) {
+    return componentInstance;
+  }
+
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const props = instance.props || {};
+
+  const selection = getCvaSelectionFromInstance(def, instance);
+  const classes = buildCvaClassesWithSelection(def, selection, props.className);
+
+  const comp = figma.createFrame();
+  comp.name = def.name;
+  comp.primaryAxisSizingMode = 'AUTO';
+  comp.counterAxisSizingMode = 'AUTO';
+  comp.counterAxisAlignItems = 'CENTER';
+  comp.primaryAxisAlignItems = 'CENTER';
+  comp.itemSpacing = 8;
+  comp.fills = [];
+  comp.strokes = [];
+  ctx.applyClipBehavior(comp, classes);
+
+  applyTailwindStylesToFrame(comp, classes, colorGroup, radiusGroup, theme);
+
+  const state = isTruthyVariantValue(props.disabled) ? 'disabled' : 'default';
+  const style = tailwindClassesToStyle(classes, state, colorGroup);
+  applyStyleToFrame(comp, style, theme);
+
+  const label = instance.children || props.children || def.name;
+  const typography = getPreviewTypography(classes);
+  const textColor = style.text ? parseColor(style.text) :
+    (colorGroup.foreground ? parseColor(colorGroup.foreground) : { r: 0, g: 0, b: 0 });
+  const text = createTextNode(label, { bold: typography.bold, fontSize: typography.fontSize, fill: textColor });
+  if (style.underline && text.textDecoration !== undefined) {
+    text.textDecoration = 'UNDERLINE';
+  }
+  comp.appendChild(text);
+  enforceFixedBoxSizingAfterLayout(comp, classes);
+  setGeneratedFallbackReason(comp, getCvaSymbolFallbackReason(def, instance));
+
+  return comp;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createStateStoryInstance(def: any, instance: any, theme: string, ctx: StoryBuilderContext, story?: any): any {
+  const symbolInstance = tryCreateNonCvaComponentInstanceShared(def, instance, theme, ctx, componentInstanceBackend, story);
+  if (symbolInstance) {
+    return symbolInstance;
+  }
+  return createStateStoryFrame(def, instance, theme, ctx, getNonCvaSymbolFallbackReason(def, instance), story);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createSimpleStoryInstance(def: any, instance: any, theme: string, ctx: StoryBuilderContext, story?: any): any {
+  const symbolInstance = tryCreateNonCvaComponentInstanceShared(def, instance, theme, ctx, componentInstanceBackend, story);
+  if (symbolInstance) {
+    return symbolInstance;
+  }
+  return createSimpleStoryFrame(def, instance, theme, ctx, getNonCvaSymbolFallbackReason(def, instance));
+}

package/src/{story-layout.ts → design-system/story-layout.ts}

@@ -1,5 +1,5 @@
-import { type JsxNode, type JsxElement, splitClassName } from './node-ir';
-import { extractGridColumns, extractGridBreakpointWidth } from './width-solver';
+import { type JsxNode, type JsxElement, splitClassName } from '../tailwind';
+import { extractGridColumns, extractGridBreakpointWidth } from '../layout';
 
 export function extractGridColumnsFromTree(node: JsxNode | undefined): number | null {
   if (!node || node.type !== 'element') return null;

package/src/design-system/story-render-strategy.ts

@@ -0,0 +1,150 @@
+import { splitClassName, type JsxElement, type JsxNode } from '../tailwind';
+import type { ComponentDef, ComponentStory } from '../components';
+import { findMatchingInstance, normalizeComponentName } from './story-tree-search';
+import { hasCheckedStateVariant } from './state-master';
+
+/**
+ * Components that prefer instance rendering even when a JSX tree is available.
+ * `switch` lives here because the input element + indicator slot are hard to
+ * reconstruct correctly from the JSX tree alone — the symbol master is more
+ * reliable than the tree expansion.
+ */
+export const INSTANCE_FALLBACK_COMPONENTS = new Set(['switch']);
+
+// Tree-rendering budget. Stories that exceed any of these limits fall back to
+// symbol-instance rendering. Tuned empirically so the realistic component
+// catalogue still renders as a tree, but pathological deep stories (giant
+// marketing pages, accidentally-recursive trees) skip the tree path and render
+// as a labelled instance frame instead.
+const STORY_JSX_NODE_LIMIT = 320;
+const STORY_JSX_CLASS_TOKEN_LIMIT = 1800;
+const STORY_JSX_DEPTH_LIMIT = 36;
+
+/**
+ * Walks the JSX tree once, counting nodes, max depth, and total class tokens.
+ * Returns true as soon as any limit is exceeded. Pure data — the only side
+ * effect is the early return.
+ */
+export function exceedsStoryJsxComplexityLimits(tree: JsxNode | null | undefined): boolean {
+  if (!tree || typeof tree !== 'object') return false;
+  let nodeCount = 0;
+  let classTokenCount = 0;
+  let maxDepth = 0;
+  const stack: Array<{ node: JsxNode; depth: number }> = [{ node: tree, depth: 0 }];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || !current.node) continue;
+
+    nodeCount += 1;
+    if (current.depth > maxDepth) maxDepth = current.depth;
+    if (nodeCount > STORY_JSX_NODE_LIMIT) return true;
+    if (maxDepth > STORY_JSX_DEPTH_LIMIT) return true;
+
+    if (current.node.type === 'element') {
+      const el = current.node as JsxElement;
+      const rawClassName = el.props ? el.props.className : '';
+      if (rawClassName) {
+        classTokenCount += splitClassName(String(rawClassName)).length;
+        if (classTokenCount > STORY_JSX_CLASS_TOKEN_LIMIT) return true;
+      }
+
+      const children = Array.isArray(el.children) ? el.children : [];
+      for (let i = 0; i < children.length; i++) {
+        stack.push({ node: children[i], depth: current.depth + 1 });
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Returns true when story-tree rendering should be skipped in favour of the
+ * instance path. Two reasons:
+ *  - The component is on the explicit instance-fallback list (e.g. switch).
+ *  - The tree exceeds the complexity budget (`exceedsStoryJsxComplexityLimits`).
+ */
+export function shouldSkipStoryJsxTree(def: ComponentDef, story: ComponentStory): boolean {
+  if (!story || !story.jsxTree) return false;
+  const defName = normalizeComponentName(def && def.name ? def.name : '');
+  if (defName && INSTANCE_FALLBACK_COMPONENTS.has(defName)) return true;
+  return exceedsStoryJsxComplexityLimits(story.jsxTree);
+}
+
+/**
+ * Returns true when instance rendering should be preferred even though a JSX
+ * tree exists. Used by CVA and (most) state components, which represent
+ * variant matrices more compactly as instances than as expanded trees.
+ * Skipped when the story passes JSX children (manual content overrides),
+ * or when the def is on the explicit fallback list (those need true instance
+ * rendering, not the symbol-instance shortcut).
+ */
+export function shouldPreferInstanceRendering(def: ComponentDef, story: ComponentStory): boolean {
+  if (!def || !story) return false;
+  const defKey = normalizeComponentName(def && def.name ? def.name : '');
+  if (!defKey) return false;
+  const storyInstances = Array.isArray(story.instances) ? story.instances : [];
+  if (storyInstances.length > 0) {
+    const rootKey = normalizeComponentName(storyInstances[0] && storyInstances[0].componentName ? storyInstances[0].componentName : '');
+    // Do not treat nested subcomponents as the root story preview source.
+    if (rootKey && rootKey !== defKey) return false;
+  }
+  const matched = findMatchingInstance(def, story);
+  if (!matched) return false;
+  const normalizedName = defKey;
+  if (INSTANCE_FALLBACK_COMPONENTS.has(normalizedName)) return false;
+  const matchedProps = matched && matched.props ? matched.props : null;
+  if (matchedProps && Array.isArray(matchedProps.__jsxChildren) && matchedProps.__jsxChildren.length > 0) {
+    return false;
+  }
+  const analysis = def && def.analysis ? def.analysis : def;
+  if (!analysis) return false;
+  const type = String(analysis.type || '').toLowerCase();
+  if (type === 'cva') return true;
+  if (type === 'state') {
+    // The scanner classifies a component as `state` based on the presence
+    // of a `data-[disabled]:` / `aria-invalid:` / `data-[state=…]:` modifier
+    // somewhere in its className. That's a good signal for input-shaped
+    // primitives (one element, a few state variants) but a false positive
+    // for compound primitives like Slider whose body is a track + thumb +
+    // indicator structure — the state-matrix renderer can't represent the
+    // geometry. If the story's JSX tree contains multiple nested
+    // `data-slot` markers, the component is structurally compound; fall
+    // back to tree rendering so the layout actually renders.
+    if (jsxTreeHasNestedDataSlots(story.jsxTree)) return false;
+    const childrenText = matched && matched.children != null ? String(matched.children).trim() : '';
+    if (childrenText !== '' && hasCheckedStateVariant(analysis)) {
+      return false;
+    }
+    return true;
+  }
+  // For simple/compound components, prefer story JSX tree rendering so layout/content
+  // fidelity is preserved (e.g. portal wrappers, centered hero content, nested sections).
+  // Nested atoms are still rendered as symbol instances by renderJsxTree.
+  return false;
+}
+
+/**
+ * True when the story's JSX tree has 2+ elements carrying a `data-slot`
+ * marker. A `state`-classified component with this shape is actually
+ * compound (Slider, Progress, future Tabs, …) and the state-matrix
+ * renderer can't produce a faithful preview from it.
+ */
+export function jsxTreeHasNestedDataSlots(tree: JsxNode | null | undefined): boolean {
+  if (!tree || typeof tree !== 'object') return false;
+  let slotsFound = 0;
+  const stack: JsxNode[] = [tree];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (!node || typeof node !== 'object' || node.type !== 'element') continue;
+    const el = node as JsxElement;
+    if (el.props && typeof el.props['data-slot'] === 'string' && el.props['data-slot'].length > 0) {
+      slotsFound += 1;
+      if (slotsFound >= 2) return true;
+    }
+    const children = Array.isArray(el.children) ? el.children : [];
+    for (let i = 0; i < children.length; i++) stack.push(children[i]);
+  }
+  return false;
+}

package/src/design-system/story-tree-search.ts

@@ -0,0 +1,110 @@
+import { splitClassName } from '../tailwind';
+
+/**
+ * Pure tree-search and component-name helpers used across the design-system
+ * page builder. Kept in their own module so story-instance and the master
+ * builders can share them without re-importing from story-builder.ts (which
+ * would otherwise create cycles via cva-master / state-master callbacks).
+ *
+ * No file-level state, no Figma API calls — just JSX-tree traversal,
+ * class-set comparison, and name normalization.
+ */
+
+export function normalizeComponentName(name: string | undefined): string {
+  return String(name || '').toLowerCase().replace(/-/g, '');
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function collectStoryJsxElements(node: any, out: any[]): void {
+  if (!node || node.type !== 'element') return;
+  out.push(node);
+  const children = Array.isArray(node.children) ? node.children : [];
+  for (let i = 0; i < children.length; i++) {
+    collectStoryJsxElements(children[i], out);
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findFirstStoryText(node: any): string | null {
+  if (!node) return null;
+  if (node.type === 'text') {
+    const content = String(node.content || '').trim();
+    return content || null;
+  }
+  if (node.type !== 'element' || !Array.isArray(node.children)) return null;
+  for (let i = 0; i < node.children.length; i++) {
+    const value = findFirstStoryText(node.children[i]);
+    if (value) return value;
+  }
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findBestStoryElementForClasses(jsxTree: any, classes: string[]): any | null {
+  if (!jsxTree || !Array.isArray(classes) || classes.length === 0) return null;
+  const targets = new Set(classes);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const elements: any[] = [];
+  collectStoryJsxElements(jsxTree, elements);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let best: any | null = null;
+  let bestOverlap = 0;
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    const tokens = splitClassName(el && el.props ? el.props.className : '');
+    if (tokens.length === 0) continue;
+    let overlap = 0;
+    for (let j = 0; j < tokens.length; j++) {
+      if (targets.has(tokens[j])) overlap++;
+    }
+    if (overlap > bestOverlap) {
+      bestOverlap = overlap;
+      best = el;
+    }
+  }
+  if (!best || bestOverlap === 0) return null;
+  return best;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getStoriesWithJsxTree(def: any): any[] {
+  const stories = def && Array.isArray(def.stories) ? def.stories : [];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const out: any[] = [];
+  for (let i = 0; i < stories.length; i++) {
+    const story = stories[i];
+    if (story && story.jsxTree) out.push(story);
+  }
+  return out;
+}
+
+export function countClassOverlap(classes: string[], targetSet: Set<string>): number {
+  let overlap = 0;
+  for (let i = 0; i < classes.length; i++) {
+    if (targetSet.has(classes[i])) overlap++;
+  }
+  return overlap;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findMatchingInstance(def: any, story: any): any | null {
+  const instances = story && story.instances ? story.instances : [];
+  const defKey = normalizeComponentName(def && def.name);
+  for (let i = 0; i < instances.length; i++) {
+    const instance = instances[i];
+    if (!instance || !instance.componentName) continue;
+    if (normalizeComponentName(instance.componentName) === defKey) return instance;
+  }
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findFirstMatchingInstance(def: any): any | null {
+  const stories = def && Array.isArray(def.stories) ? def.stories : [];
+  for (let i = 0; i < stories.length; i++) {
+    const instance = findMatchingInstance(def, stories[i]);
+    if (instance) return instance;
+  }
+  return null;
+}

package/src/design-system/symbol-fallback.ts

@@ -0,0 +1,89 @@
+import { getNonDefaultSymbolPropReason, inferSafeTextOverridePropKeys } from '../components';
+
+/**
+ * Helpers for resolving the text content that should override a symbol
+ * instance, plus the "why we can't use a symbol" reason strings the design
+ * system page records when it falls back to raw rendering.
+ *
+ * The cva-flavoured fallback reason (and the symbol-master warming pass)
+ * still live in story-builder.ts because they read CVA-master constants;
+ * they'll move out alongside the cva-master extraction.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getInstanceTextOverride(def: any, instance: any): string | null {
+  const props = instance && instance.props ? instance.props : {};
+  if (instance && instance.children != null && String(instance.children).trim() !== '') {
+    return String(instance.children);
+  }
+  if (props.children != null && String(props.children).trim() !== '') {
+    return String(props.children);
+  }
+  if (def && def.type !== 'compound') {
+    const inferredTextKeys = inferSafeTextOverridePropKeys(def);
+    for (let i = 0; i < inferredTextKeys.length; i++) {
+      const key = inferredTextKeys[i];
+      if (props[key] != null && String(props[key]).trim() !== '') {
+        return String(props[key]);
+      }
+    }
+  }
+  if (def && def.type === 'state') {
+    if (props.placeholder != null && String(props.placeholder).trim() !== '') {
+      return String(props.placeholder);
+    }
+    if (props.defaultValue != null && String(props.defaultValue).trim() !== '') {
+      return String(props.defaultValue);
+    }
+  }
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getNonCvaSymbolFallbackReason(def: any, instance: any): string {
+  if (!def || def.type === 'cva') return 'non_cva_not_applicable';
+  if (def.symbolCandidate === false) return 'symbol_candidate_disabled';
+  const propReason = getNonDefaultSymbolPropReason(def, instance);
+  if (propReason) return propReason;
+  return 'master_or_instance_unavailable';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findFirstTextDescendant(node: any): any | null {
+  if (!node) return null;
+  if (node.type === 'TEXT') return node;
+  if (!Array.isArray(node.children)) return null;
+  for (let i = 0; i < node.children.length; i++) {
+    const found = findFirstTextDescendant(node.children[i]);
+    if (found) return found;
+  }
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyTextOverrideToInstance(instanceNode: any, value: string): boolean {
+  const text = String(value || '').trim();
+  if (!text) return false;
+  const textNode = findFirstTextDescendant(instanceNode);
+  if (!textNode) return false;
+  try {
+    textNode.characters = text;
+    return true;
+  } catch (_error) {
+    // If override is blocked by component structure, keep default text.
+    return false;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getInstanceChildrenText(instance: any): string | null {
+  if (!instance) return null;
+  if (instance.children != null && String(instance.children).trim() !== '') {
+    return String(instance.children);
+  }
+  const props = instance.props || {};
+  if (props.children != null && String(props.children).trim() !== '') {
+    return String(props.children);
+  }
+  return null;
+}