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

package/src/design-system/preview-builder.ts

@@ -0,0 +1,738 @@
+// External modules.
+import { jsxTreeHasNestedDataSlots } from './story-render-strategy';
+import {
+  applyTailwindStylesToFrame,
+  buildCvaClassesForVariant,
+  cloneJsxNodeForBreakpoint,
+  collectTreeClasses,
+  extractBreakpointsFromClasses,
+  extractRootGridColsFromTree,
+  extractStatesFromClasses,
+  getBreakpointLabel,
+  getClassesForBreakpoint,
+  getResponsivePreviewWidth,
+  hasSignificantResponsiveChanges,
+  isHiddenAtBreakpoint,
+  mergeStatesWithDefinition,
+  parseUtilityClass,
+  propagateChildSelectorClasses,
+  splitClassName,
+  tailwindClassesToStyle,
+  treeClassSignature,
+  treeHasResponsiveClasses,
+  uniqueClassSignature,
+  type JsxNode,
+  type JsxElement,
+  type StateInfo,
+} from '../tailwind';
+import { parseColor } from '../tokens';
+import { createTextNode, type CreateTextOptions } from '../text';
+import { getRingInfoFromClasses, markRingNode, applyRingIfPossible } from '../layout';
+import type {
+  ComponentDef,
+  ComponentStory,
+} from '../components/scanner-types';
+
+// Sibling design-system modules.
+import { defaultGridWidth, normalizeLayoutClasses } from './story-layout';
+import { tagGeneratedSubtree } from './generated-node';
+import { type StoryBuilderContext } from './story-builder-context';
+import { renderStandaloneStory } from './story-builder';
+import {
+  buildStatePreviewLabel,
+  buildStoryStateClasses,
+  buildStoryInstanceClasses,
+  createStateStoryInstance,
+} from './story-instance';
+import { findMatchingInstance } from './story-tree-search';
+import { getThemeContext, BOARD_LAYOUT } from './theme-context';
+import { resolvePortalAwareStoryTree } from './portal-handling';
+
+// ---------------------------------------------------------------------------
+// State-preview helpers (private to this module)
+// ---------------------------------------------------------------------------
+
+function getStateEntry(states: StateInfo[], name: string): StateInfo | null {
+  for (let i = 0; i < states.length; i++) {
+    if (states[i].name === name) return states[i];
+  }
+  return null;
+}
+
+function getStateNames(states: StateInfo[]): string[] {
+  const names: string[] = ['default'];
+  for (let i = 0; i < states.length; i++) {
+    const name = states[i].name;
+    if (name === 'default') continue;
+    names.push(name);
+  }
+  return names;
+}
+
+function buildStateClasses(states: StateInfo[], name: string): string[] {
+  const defaultEntry = getStateEntry(states, 'default');
+  const baseClasses = defaultEntry ? defaultEntry.classes.slice() : [];
+  if (name === 'default') return baseClasses;
+  const entry = getStateEntry(states, name);
+  if (!entry) return baseClasses;
+  return baseClasses.concat(entry.classes);
+}
+
+function isVisualStateUtility(cls: string): boolean {
+  const atom = parseUtilityClass(cls);
+  const utility = atom.utility || cls;
+  if (!utility) return false;
+  if (utility.startsWith('text-')) return false;
+  if (utility.startsWith('font-')) return false;
+  if (utility === 'underline' || utility === 'no-underline') return false;
+  if (utility.startsWith('decoration-')) return false;
+
+  return (
+    utility.startsWith('bg-')
+    || utility.startsWith('border')
+    || utility.startsWith('ring')
+    || utility.startsWith('shadow')
+    || utility.startsWith('opacity-')
+    || utility.startsWith('outline')
+    || utility.startsWith('cursor-')
+    || utility.startsWith('pointer-events-')
+    || utility.startsWith('scale-')
+    || utility.startsWith('translate-')
+    || utility.startsWith('rotate-')
+    || utility.startsWith('skew-')
+  );
+}
+
+function shouldSkipStatePreview(def: ComponentDef): boolean {
+  if (!def || def.type !== 'state') return false;
+  const states = def.states || {};
+  const names = Object.keys(states).filter(name => name !== 'default');
+  if (names.length === 0) return true;
+
+  let hasVisualState = false;
+  for (let i = 0; i < names.length; i++) {
+    const state = states[names[i]];
+    const classes = state && state.classes ? state.classes : [];
+    for (let j = 0; j < classes.length; j++) {
+      if (isVisualStateUtility(classes[j])) {
+        hasVisualState = true;
+        break;
+      }
+    }
+    if (hasVisualState) break;
+  }
+  if (hasVisualState) return false;
+
+  const stories = def.stories || [];
+  for (let i = 0; i < stories.length; i++) {
+    const tree = stories[i] && stories[i].jsxTree ? stories[i].jsxTree : null;
+    if (!tree || tree.type !== 'element') continue;
+    const tagName = String((tree as JsxElement).tagName || '').toLowerCase();
+    if (
+      tagName === 'div'
+      || tagName === 'section'
+      || tagName === 'header'
+      || tagName === 'footer'
+      || tagName === 'main'
+      || tagName === 'article'
+      || tagName === 'nav'
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+import { getPreviewTypography } from './typography';
+export { getPreviewTypography };
+
+export function measureTextWidth(label: string, options?: CreateTextOptions): number {
+  const node = createTextNode(label, options);
+  const width = node.width;
+  try {
+    node.remove();
+  } catch (_err) {
+    // ignore
+  }
+  return width;
+}
+
+export function createPreviewLabelNode(label: string, classes: string[], colorGroup: Record<string, string>): TextNode {
+  const style = tailwindClassesToStyle(classes, 'default', colorGroup);
+  const textColor = style.text ? parseColor(style.text) :
+    (colorGroup.foreground ? parseColor(colorGroup.foreground) : { r: 0, g: 0, b: 0 });
+  const typography = getPreviewTypography(classes);
+  const text = createTextNode(label, { bold: typography.bold, fontSize: typography.fontSize, fill: textColor });
+  if (style.underline && text.textDecoration !== undefined) {
+    text.textDecoration = 'UNDERLINE';
+  }
+  return text;
+}
+
+// ---------------------------------------------------------------------------
+// Public: state preview block
+// ---------------------------------------------------------------------------
+
+export function createStatePreviewBlock(
+  def: ComponentDef,
+  story: ComponentStory,
+  theme: string,
+  ctx: StoryBuilderContext
+): FrameNode | null {
+  if (!def || (def.type !== 'cva' && def.type !== 'state')) return null;
+  if (shouldSkipStatePreview(def)) return null;
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const instance = findMatchingInstance(def, story);
+  const props = instance && instance.props ? instance.props : {};
+
+  const matrixTitleStyle = { fontSize: 18, bold: true, opacity: 0.95 };
+  const axisLabelStyle = { fontSize: 13, bold: true, opacity: 0.78 };
+  const itemLabelStyle = { fontSize: 13, bold: true, opacity: 0.72 };
+
+  const label = buildStatePreviewLabel(def, instance);
+
+  function createStateCell(stateName: string, classes: string[], columnLabel: string): FrameNode {
+    if (String(def && def.type ? def.type : '').toLowerCase() === 'state') {
+      const baseProps = Object.assign({}, props || {});
+      const originalExtraClasses = splitClassName(props && props.className);
+      delete baseProps.className;
+      delete baseProps.state;
+      delete baseProps['data-state'];
+      delete baseProps.disabled;
+      delete baseProps['aria-disabled'];
+      delete baseProps['aria-invalid'];
+      delete baseProps.checked;
+      delete baseProps.defaultChecked;
+      delete baseProps['aria-checked'];
+
+      const normalizedState = String(stateName || 'default').trim().toLowerCase();
+      let visualState = normalizedState || 'default';
+      let checked = false;
+
+      if (visualState === 'checked') {
+        visualState = 'default';
+        checked = true;
+      }
+
+      // Keep only story-level extras (e.g. width wrappers) here.
+      // Visual state classes are applied in createStateStoryFrame via def.states.
+      if (originalExtraClasses.length > 0) {
+        baseProps.className = originalExtraClasses.join(' ');
+      }
+
+      if (checked) {
+        baseProps.checked = 'true';
+      }
+      if (visualState && visualState !== 'default') {
+        baseProps.state = visualState;
+      }
+      if (visualState === 'disabled') {
+        baseProps.disabled = 'true';
+      } else if (visualState === 'error') {
+        baseProps['aria-invalid'] = 'true';
+      } else if (visualState === 'open') {
+        baseProps['data-state'] = 'open';
+      }
+
+      const stateNode = createStateStoryInstance(
+        def,
+        { props: baseProps },
+        theme,
+        ctx,
+        story
+      );
+
+      const cell = figma.createFrame();
+      cell.name = def.name + '/' + columnLabel + '/' + stateName;
+      cell.layoutMode = 'HORIZONTAL';
+      cell.primaryAxisSizingMode = 'AUTO';
+      cell.counterAxisSizingMode = 'AUTO';
+      cell.primaryAxisAlignItems = 'CENTER';
+      cell.counterAxisAlignItems = 'CENTER';
+      cell.fills = [];
+      cell.strokes = [];
+      ctx.applyClipBehavior(cell, []);
+      cell.appendChild(stateNode);
+      return cell;
+    }
+
+    const comp = figma.createFrame();
+    comp.name = def.name + '/' + columnLabel + '/' + stateName;
+    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);
+    if (label && String(label).trim() !== '') {
+      comp.appendChild(createPreviewLabelNode(label, classes, colorGroup));
+    }
+    // Append any icon-like JSX-element child from the matched instance so
+    // icon-only components (e.g. Toggle with `<Bold />`) show their icon in
+    // every matrix cell instead of being invisible (default variant) or
+    // empty-bordered (outline variant). Use the first element child as a
+    // representative sample — the matrix is a state × variant grid, not a
+    // story-by-story render, so a single icon across cells is fine.
+    const jsxChildren = props && Array.isArray((props as { __jsxChildren?: unknown }).__jsxChildren)
+      ? ((props as { __jsxChildren?: JsxNode[] }).__jsxChildren as JsxNode[])
+      : [];
+    for (let i = 0; i < jsxChildren.length; i++) {
+      const child = jsxChildren[i];
+      if (!child || (child as { type?: string }).type !== 'element') continue;
+      const iconNode = ctx.renderJsxTree(
+        child,
+        colorGroup,
+        radiusGroup,
+        theme,
+        0,
+        { parentLayout: 'HORIZONTAL' }
+      );
+      if (iconNode) {
+        comp.appendChild(iconNode);
+      }
+      break; // one sample is enough
+    }
+    const ringInfo = getRingInfoFromClasses(classes, colorGroup);
+    if (ringInfo) markRingNode(comp, ringInfo);
+
+    const cell = figma.createFrame();
+    cell.name = def.name + '/' + columnLabel + '/' + stateName + '/Cell';
+    cell.layoutMode = 'HORIZONTAL';
+    cell.primaryAxisSizingMode = 'AUTO';
+    cell.counterAxisSizingMode = 'AUTO';
+    cell.primaryAxisAlignItems = 'CENTER';
+    cell.counterAxisAlignItems = 'CENTER';
+    cell.fills = [];
+    cell.strokes = [];
+    ctx.applyClipBehavior(cell, []);
+    cell.appendChild(comp);
+    // Comp is now in the cell — its dimensions are final, so we can safely
+    // apply the marked ring overlay. The host-FIXED-toggle inside
+    // applyRingIfPossible ensures appending the overlay can't inflate comp.
+    applyRingIfPossible(comp, cell);
+    return cell;
+  }
+
+  type VariantColumn = { label: string; states: StateInfo[] };
+  const columns: VariantColumn[] = [];
+
+  if (def.type === 'cva' && def.variants && Object.keys(def.variants).length > 0) {
+    const variantKeys = Object.keys(def.variants);
+    const primaryKey = def.variants.variant ? 'variant' : variantKeys[0];
+    const primaryValues = def.variants[primaryKey] || [];
+    for (let i = 0; i < primaryValues.length; i++) {
+      const value = primaryValues[i];
+      const classes = buildCvaClassesForVariant(def, props, primaryKey, value);
+      const states = mergeStatesWithDefinition(extractStatesFromClasses(classes), def);
+      const labelText = value ? value.charAt(0).toUpperCase() + value.slice(1) : '';
+      columns.push({ label: labelText, states: states });
+    }
+  } else {
+    const classes = buildStoryStateClasses(def, instance);
+    if (classes.length === 0) return null;
+    const states = mergeStatesWithDefinition(extractStatesFromClasses(classes), def);
+    columns.push({ label: def.name || 'Component', states: states });
+  }
+
+  if (columns.length === 0) return null;
+
+  const stateNames: string[] = columns.length > 0 ? getStateNames(columns[0].states) : [];
+  for (let i = 1; i < columns.length; i++) {
+    const names = getStateNames(columns[i].states);
+    for (let j = 0; j < names.length; j++) {
+      const name = names[j];
+      if (stateNames.indexOf(name) === -1) {
+        stateNames.push(name);
+      }
+    }
+  }
+  if (stateNames.length <= 1) return null;
+
+  const block = figma.createFrame();
+  block.name = 'States';
+  block.layoutMode = 'VERTICAL';
+  block.itemSpacing = BOARD_LAYOUT.stateMatrixGap;
+  block.primaryAxisSizingMode = 'AUTO';
+  block.counterAxisSizingMode = 'AUTO';
+  block.fills = [];
+  ctx.applyClipBehavior(block, []);
+  block.appendChild(createTextNode('State Matrix', matrixTitleStyle));
+
+  const cellMatrix: FrameNode[][] = [];
+  const columnWidths: number[] = [];
+  for (let ci = 0; ci < columns.length; ci++) {
+    const column = columns[ci];
+    let maxWidth = measureTextWidth(column.label, itemLabelStyle);
+    const cells: FrameNode[] = [];
+    for (let si = 0; si < stateNames.length; si++) {
+      const stateName = stateNames[si];
+      const classes = buildStateClasses(column.states, stateName);
+      const cell = createStateCell(stateName, classes, column.label || def.name);
+      if (cell.width > maxWidth) maxWidth = cell.width;
+      cells.push(cell);
+    }
+    cellMatrix.push(cells);
+    columnWidths.push(maxWidth);
+  }
+
+  let legendWidth = measureTextWidth('State', itemLabelStyle);
+  for (let i = 0; i < stateNames.length; i++) {
+    const width = measureTextWidth(stateNames[i], itemLabelStyle);
+    if (width > legendWidth) legendWidth = width;
+  }
+  legendWidth += 24;
+
+  function createLegendCell(textValue: string, style: CreateTextOptions): FrameNode {
+    const cell = figma.createFrame();
+    cell.layoutMode = 'VERTICAL';
+    cell.primaryAxisSizingMode = 'AUTO';
+    cell.counterAxisSizingMode = 'AUTO';
+    cell.fills = [];
+    cell.appendChild(createTextNode(textValue, style));
+    try {
+      cell.resize(legendWidth, cell.height);
+      cell.counterAxisSizingMode = 'FIXED';
+    } catch (_err) {
+      // ignore
+    }
+    return cell;
+  }
+
+  const axesRow = figma.createFrame();
+  axesRow.name = 'State Axes';
+  axesRow.layoutMode = 'HORIZONTAL';
+  axesRow.itemSpacing = BOARD_LAYOUT.stateMatrixAxisGap;
+  axesRow.primaryAxisSizingMode = 'AUTO';
+  axesRow.counterAxisSizingMode = 'AUTO';
+  axesRow.fills = [];
+  ctx.applyClipBehavior(axesRow, []);
+  axesRow.appendChild(createLegendCell('States', axisLabelStyle));
+  axesRow.appendChild(createTextNode('Variants', axisLabelStyle));
+  block.appendChild(axesRow);
+
+  const table = figma.createFrame();
+  table.name = 'State Table';
+  table.layoutMode = 'VERTICAL';
+  table.itemSpacing = BOARD_LAYOUT.stateMatrixGap;
+  table.primaryAxisSizingMode = 'AUTO';
+  table.counterAxisSizingMode = 'AUTO';
+  table.fills = [];
+  ctx.applyClipBehavior(table, []);
+
+  const tableHeader = figma.createFrame();
+  tableHeader.name = 'State Table Header';
+  tableHeader.layoutMode = 'HORIZONTAL';
+  tableHeader.itemSpacing = BOARD_LAYOUT.stateMatrixAxisGap;
+  tableHeader.primaryAxisSizingMode = 'AUTO';
+  tableHeader.counterAxisSizingMode = 'AUTO';
+  tableHeader.fills = [];
+  tableHeader.appendChild(createLegendCell('State', itemLabelStyle));
+  for (let ci = 0; ci < columns.length; ci++) {
+    const headerCell = figma.createFrame();
+    headerCell.layoutMode = 'VERTICAL';
+    headerCell.primaryAxisSizingMode = 'AUTO';
+    headerCell.counterAxisSizingMode = 'AUTO';
+    headerCell.fills = [];
+    headerCell.appendChild(createTextNode(columns[ci].label, itemLabelStyle));
+    try {
+      headerCell.resize(columnWidths[ci], headerCell.height);
+      headerCell.counterAxisSizingMode = 'FIXED';
+    } catch (_err) {
+      // ignore
+    }
+    tableHeader.appendChild(headerCell);
+  }
+  table.appendChild(tableHeader);
+
+  for (let si = 0; si < stateNames.length; si++) {
+    const row = figma.createFrame();
+    row.name = 'State Row/' + stateNames[si];
+    row.layoutMode = 'HORIZONTAL';
+    row.itemSpacing = BOARD_LAYOUT.stateMatrixAxisGap;
+    row.primaryAxisSizingMode = 'AUTO';
+    row.counterAxisSizingMode = 'AUTO';
+    row.counterAxisAlignItems = 'CENTER';
+    row.fills = [];
+    ctx.applyClipBehavior(row, []);
+    row.appendChild(createLegendCell(stateNames[si], itemLabelStyle));
+    for (let ci = 0; ci < columns.length; ci++) {
+      const cell = cellMatrix[ci][si];
+      try {
+        cell.resize(columnWidths[ci], cell.height);
+        if (cell.layoutMode === 'HORIZONTAL') {
+          cell.primaryAxisSizingMode = 'FIXED';
+        } else if (cell.layoutMode === 'VERTICAL') {
+          cell.counterAxisSizingMode = 'FIXED';
+        }
+      } catch (_err) {
+        // ignore
+      }
+      row.appendChild(cell);
+    }
+    table.appendChild(row);
+  }
+
+  block.appendChild(table);
+  tagGeneratedSubtree(block, 'state-preview-block:' + def.name + ':' + (story && story.name ? story.name : 'default'));
+  return block;
+}
+
+// ---------------------------------------------------------------------------
+// Public: responsive preview block
+// ---------------------------------------------------------------------------
+
+export function createResponsivePreviewBlock(
+  def: ComponentDef,
+  story: ComponentStory,
+  theme: string,
+  ctx: StoryBuilderContext
+): FrameNode | null {
+  if (!def) return null;
+  const instance = findMatchingInstance(def, story);
+  const layoutClasses = normalizeLayoutClasses(story && story.layoutClasses);
+  const layoutHasResponsive = hasSignificantResponsiveChanges(layoutClasses);
+  // Use the same portal-filtering logic as main rendering so trigger-only stories
+  // don't pick up sm: classes from portal content (e.g. Dialog's sm:max-w-lg).
+  const effectiveJsxTree = story && story.jsxTree
+    ? resolvePortalAwareStoryTree(story.jsxTree)
+    : null;
+  const treeHasResponsive = effectiveJsxTree ? treeHasResponsiveClasses(effectiveJsxTree as JsxNode) : false;
+  const instanceClasses = buildStoryInstanceClasses(def, instance);
+  const instanceHasResponsive = hasSignificantResponsiveChanges(instanceClasses);
+  if (!layoutHasResponsive && !treeHasResponsive && !instanceHasResponsive) return null;
+
+  const sourceClasses: string[] = [];
+  if (layoutHasResponsive && layoutClasses.length > 0) {
+    for (let i = 0; i < layoutClasses.length; i++) sourceClasses.push(layoutClasses[i]);
+  }
+  if (treeHasResponsive && effectiveJsxTree) {
+    collectTreeClasses(effectiveJsxTree as JsxNode, sourceClasses);
+  }
+  if (sourceClasses.length === 0) {
+    for (let i = 0; i < instanceClasses.length; i++) sourceClasses.push(instanceClasses[i]);
+  }
+  const breakpoints = extractBreakpointsFromClasses(sourceClasses);
+  if (breakpoints.length <= 1) return null;
+  const entries: Array<{
+    bp: { name: string; minWidth: number };
+    layoutOverride: string[];
+    treeOverride: JsxNode | null;
+    instanceOverride: string[];
+    signature: string;
+  }> = [];
+  for (let i = 0; i < breakpoints.length; i++) {
+    const bp = breakpoints[i];
+    const layoutOverride = layoutClasses.length > 0 ? getClassesForBreakpoint(layoutClasses, bp.name) : layoutClasses;
+    let treeOverride: JsxNode | null = effectiveJsxTree ?? null;
+    if (treeHasResponsive && effectiveJsxTree) {
+      // Clone for this breakpoint, then propagate *:X child-wildcard classes so
+      // the renderer sees explicit per-element classes (e.g. *:w-full on a flex-col
+      // footer → w-full on each button at base, *:w-auto → w-auto at sm+).
+      // Propagation runs here — after breakpoint mapping — so the main story render
+      // path is unaffected and keeps its original auto-sizing behaviour.
+      treeOverride = propagateChildSelectorClasses(
+        cloneJsxNodeForBreakpoint(effectiveJsxTree as JsxNode, bp.name)
+      );
+    }
+    const instanceOverride = getClassesForBreakpoint(instanceClasses, bp.name);
+    let signature = 'I:' + uniqueClassSignature(instanceOverride);
+    if (layoutHasResponsive || treeHasResponsive) {
+      signature = 'L:' + uniqueClassSignature(layoutOverride) + '|T:' + treeClassSignature(treeOverride as JsxNode);
+    }
+    entries.push({
+      bp: { name: bp.name, minWidth: bp.minWidth },
+      layoutOverride: layoutOverride,
+      treeOverride: treeOverride,
+      instanceOverride: instanceOverride,
+      signature: signature,
+    });
+  }
+  if (entries.length <= 1) return null;
+  // Drop breakpoints where the root element resolves to `display: none` at
+  // that breakpoint (e.g. `md:hidden` hides the whole component at md+). Walk
+  // the leading single-child spine so a decorator-wrapped component still
+  // exposes the inner root's visibility intent; deep-child `hidden` on a
+  // sibling branch is ignored.
+  const rootClassSet: string[] = [];
+  let spineNode: JsxNode | null | undefined = effectiveJsxTree;
+  let spineDepth = 0;
+  while (spineNode && spineNode.type === 'element' && spineDepth < 4) {
+    const el = spineNode as JsxElement;
+    const cls = el.props && el.props.className;
+    if (typeof cls === 'string') {
+      const list = splitClassName(cls);
+      for (let i = 0; i < list.length; i++) rootClassSet.push(list[i]);
+    }
+    const children = el.children || [];
+    if (children.length !== 1 || !children[0] || children[0].type !== 'element') break;
+    spineNode = children[0];
+    spineDepth++;
+  }
+  for (let i = 0; i < layoutClasses.length; i++) rootClassSet.push(layoutClasses[i]);
+  const visibleEntries = rootClassSet.length > 0
+    ? entries.filter(e => !isHiddenAtBreakpoint(rootClassSet, e.bp.name))
+    : entries;
+  if (visibleEntries.length <= 1) return null;
+  const filteredEntries: typeof entries = [];
+  const baseSignature = visibleEntries[0].signature;
+  const seenSignatures: Record<string, boolean> = {};
+  seenSignatures[baseSignature] = true;
+  filteredEntries.push(visibleEntries[0]);
+  for (let i = 1; i < visibleEntries.length; i++) {
+    const entry = visibleEntries[i];
+    if (entry.signature === baseSignature) continue;
+    if (seenSignatures[entry.signature]) continue;
+    seenSignatures[entry.signature] = true;
+    filteredEntries.push(entry);
+  }
+  if (filteredEntries.length <= 1) return null;
+
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const label = buildStatePreviewLabel(def, instance);
+
+  const block = figma.createFrame();
+  block.name = 'Responsive';
+  block.layoutMode = 'VERTICAL';
+  block.itemSpacing = BOARD_LAYOUT.responsiveBlockGap;
+  block.primaryAxisSizingMode = 'AUTO';
+  block.counterAxisSizingMode = 'AUTO';
+  block.fills = [];
+  ctx.applyClipBehavior(block, []);
+
+  block.appendChild(createTextNode('Responsive', { fontSize: 16, lineHeight: 22, opacity: 0.6 }));
+
+  const row = figma.createFrame();
+  row.name = 'Responsive Strip';
+  row.layoutMode = 'HORIZONTAL';
+  row.itemSpacing = BOARD_LAYOUT.responsiveColumnGap;
+  row.primaryAxisSizingMode = 'AUTO';
+  row.counterAxisSizingMode = 'AUTO';
+  row.fills = [];
+  ctx.applyClipBehavior(row, []);
+
+  for (let i = 0; i < filteredEntries.length; i++) {
+    const entry = filteredEntries[i];
+    const bp = entry.bp;
+    const viewportWidth = getResponsivePreviewWidth(bp.name, bp.minWidth);
+
+    const col = figma.createFrame();
+    col.name = getBreakpointLabel(bp.name, bp.minWidth);
+    col.layoutMode = 'VERTICAL';
+    col.itemSpacing = BOARD_LAYOUT.responsiveLabelGap;
+    col.primaryAxisSizingMode = 'AUTO';
+    col.counterAxisSizingMode = 'AUTO';
+    col.fills = [];
+
+    col.appendChild(createTextNode(getBreakpointLabel(bp.name, bp.minWidth), { fontSize: 12, bold: true, opacity: 0.6 }));
+    const viewport = figma.createFrame();
+    viewport.name = 'Viewport';
+    viewport.layoutMode = 'VERTICAL';
+    viewport.itemSpacing = 0;
+    viewport.primaryAxisSizingMode = 'AUTO';
+    viewport.counterAxisSizingMode = 'FIXED';
+    viewport.fills = [];
+    viewport.strokes = [];
+    // Keep responsive previews fully visible vertically; clipping here caused
+    // taller panels (e.g. Dialog OpenPanel/Confirm) to appear truncated.
+    viewport.clipsContent = false;
+    viewport.resize(viewportWidth, viewport.height);
+
+    if (layoutHasResponsive || treeHasResponsive) {
+      const layoutOverride = entry.layoutOverride;
+      const treeOverride = entry.treeOverride;
+      const storyOverride = Object.assign({}, story, { layoutClasses: layoutOverride, jsxTree: treeOverride });
+      const preview = renderStandaloneStory(storyOverride, theme, ctx, viewportWidth);
+      if (preview) {
+        const colsOverride = treeOverride ? extractRootGridColsFromTree(treeOverride as JsxNode) : null;
+        // The `cols > 1` part of the gate now lives in
+        // `applyGridColumnsIfPossible`, so a `cols === 1` forward is a
+        // safe no-op. Keep the `preview.children.length === 1` check —
+        // that's preview-builder-specific (only reflow when the
+        // standalone-story render produced a single root frame to
+        // re-grid).
+        if (colsOverride != null && preview.children.length === 1) {
+          const target = preview.children[0];
+          if ('layoutMode' in target) {
+            const previewPadding = (preview.paddingLeft || 0) + (preview.paddingRight || 0);
+            const minWidth = defaultGridWidth(colsOverride);
+            let previewWidth = Number.isFinite(preview.width) ? preview.width - previewPadding : undefined;
+            if (!Number.isFinite(previewWidth) || (previewWidth != null && previewWidth < minWidth)) {
+              previewWidth = minWidth;
+            }
+            ctx.applyGridColumnsWithReflow(target as FrameNode, previewWidth, colsOverride);
+          }
+        }
+        if ('layoutAlign' in preview) {
+          preview.layoutAlign = 'STRETCH';
+        }
+        viewport.appendChild(preview);
+      }
+    } else {
+      const bpClasses = entry.instanceOverride;
+      const comp = figma.createFrame();
+      comp.name = def.name + '/' + bp.name;
+      comp.primaryAxisSizingMode = 'AUTO';
+      comp.counterAxisSizingMode = 'AUTO';
+      comp.counterAxisAlignItems = 'CENTER';
+      comp.primaryAxisAlignItems = 'CENTER';
+      comp.itemSpacing = 8;
+      comp.fills = [];
+      comp.strokes = [];
+      ctx.applyClipBehavior(comp, bpClasses);
+
+      applyTailwindStylesToFrame(comp, bpClasses, colorGroup, radiusGroup, theme);
+      comp.appendChild(createPreviewLabelNode(label, bpClasses, colorGroup));
+
+      if ('layoutAlign' in comp) {
+        comp.layoutAlign = 'STRETCH';
+      }
+      viewport.appendChild(comp);
+    }
+    col.appendChild(viewport);
+    row.appendChild(col);
+  }
+
+  block.appendChild(row);
+  tagGeneratedSubtree(block, 'responsive-preview-block:' + def.name + ':' + (story && story.name ? story.name : 'default'));
+  return block;
+}
+
+// ---------------------------------------------------------------------------
+// Public: gate functions (decide whether to render previews)
+// ---------------------------------------------------------------------------
+
+export function shouldRenderStatesForStory(def: ComponentDef, story: ComponentStory, storyIndex: number): boolean {
+  // Slider / Progress / future Tabs are mis-classified as `type:'state'` by
+  // the scanner but are structurally compound — the State Matrix renderer
+  // (createStateStoryFrame) can't reconstruct their geometry and would
+  // emit empty rows ("default" / "focus" / "disabled" with nothing in
+  // them). The same nested-data-slot signal we use to gate the
+  // tree-vs-instance choice also gates this preview block.
+  if (story && jsxTreeHasNestedDataSlots(story.jsxTree as JsxNode)) {
+    return false;
+  }
+  const name = String(story && story.name ? story.name : '').toLowerCase();
+  if (name && (name === 'default' || name.indexOf('default') !== -1)) {
+    return true;
+  }
+  const stories = def && def.stories ? def.stories : [];
+  let hasDefault = false;
+  for (let i = 0; i < stories.length; i++) {
+    const storyName = String(stories[i] && stories[i].name ? stories[i].name : '').toLowerCase();
+    if (storyName && (storyName === 'default' || storyName.indexOf('default') !== -1)) {
+      hasDefault = true;
+      break;
+    }
+  }
+  if (hasDefault) return false;
+  return storyIndex === 0;
+}
+