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

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

@@ -0,0 +1,1322 @@
+import { resolvePortalAwareStoryTree, jsxTreeIsPortalTriggerOnly } from './portal-handling';
+import { getThemeContext, BOARD_LAYOUT } from './theme-context';
+import { getNonCvaSymbolFallbackReason } from './symbol-fallback';
+import {
+  removeDirectTextChildren,
+  removeDuplicateChildrenByName,
+  hasNodeChildren,
+} from './frame-utils';
+import {
+  ENABLE_SYMBOL_MASTERS,
+  findExistingComponentLibraryRoot,
+  shouldCreateNonCvaMaster,
+} from './master-shared';
+import {
+  shouldCreateStateMaster,
+} from './state-master';
+import { shouldCreateCvaMaster } from './cva-master';
+import {
+  normalizeComponentName,
+} from './story-tree-search';
+import { warmSymbolMasters } from './non-cva-master';
+import {
+  componentInstanceBackend,
+  createCVAStoryInstance,
+  createStateStoryInstance,
+  createSimpleStoryInstance,
+} from './story-instance';
+// External modules.
+import {
+  COMPONENT_DEFS,
+  TOKENS,
+  debug,
+  extractTextColorToken,
+  getThemeNames,
+  isMultiModeEnabled,
+  resolveTextColorValue,
+  setThemeMode,
+} from '../tokens';
+import {
+  applyAspectRatioIfPossible,
+  applyFullWidthIfPossible,
+  applyRingIfPossible,
+  applyVerticalFlexGrowIfPossible,
+  enforceGrowChildPrimaryFixed,
+  extractGridColumns,
+  extractMaxWidth,
+  reapplyRightPositionedChildren,
+  reflowDeferredAbsolutePositioningTree,
+  shouldSkipFullWidthForClasses,
+} from '../layout';
+import {
+  extractRootGridColsFromTree,
+  propagateChildSelectorClasses,
+  splitClassName,
+  tailwindClassesToStyle,
+  type JsxElement,
+} from '../tailwind';
+import {
+  createCompoundComponent,
+  tryCreateNonCvaComponentInstance as tryCreateNonCvaComponentInstanceShared,
+  type ComponentDef,
+  type ComponentStory,
+  type LayoutInfo,
+} from '../components';
+import { createTextNode } from '../text';
+import { findChildByName, findChildIndexByName, getFrameHash, hashDef, hashString, setFrameHash } from '../cache';
+import { RENDER_ENGINE_VERSION } from '../render-engine-version';
+import { getActivePack } from '../plugin';
+
+// Sibling design-system modules.
+import { normalizeLayoutClasses } from './story-layout';
+import { isGeneratedDesignSystemNode, setGeneratedFallbackReason, tagGeneratedNode } from './generated-node';
+import { type StoryBuilderContext, type StoryRenderContext } from './story-builder-context';
+import { createStatePreviewBlock, createResponsivePreviewBlock, shouldRenderStatesForStory } from './preview-builder';
+import {
+  getComponentSectionName,
+  groupComponentDefs,
+  inferComponentSection,
+} from './component-sections';
+import {
+  blockHashMatchesCurrent,
+  findComponentBlocksInPage,
+  normalizeForPreflight,
+} from './block-cache';
+import {
+  resolveStoryLayoutHeight,
+  resolveStoryLayoutWidth,
+} from './story-dimensioning';
+import {
+  INSTANCE_FALLBACK_COMPONENTS,
+  shouldPreferInstanceRendering,
+  shouldSkipStoryJsxTree,
+} from './story-render-strategy';
+import { setStoryRenderDiagnostics } from './story-diagnostics';
+import { type StatusUpdate } from './design-system';
+import {
+  appendResolvedInstance,
+  renderGuardedPortalStoryInstances,
+  renderStoryInstances,
+} from './instance-rendering';
+
+// Per-component + per-phase build timings to the Figma plugin console.
+// Off by default for end users — flip to `true` locally when you need to
+// see where build time goes during a "Generate Design System Page" run.
+// The loading-panel status messages are always emitted via `onStatus`;
+// this flag only gates the extra `console.log` lines that include
+// elapsed-seconds + per-component millisecond timings.
+const INKBRIDGE_PERF_LOGS = false;
+
+function ensureHeaderBlock(
+  parent: FrameNode,
+  frameName: string,
+  title: string,
+  description: string | null,
+  opts?: { titleSize?: number; titleLineHeight?: number; descriptionSize?: number }
+): FrameNode {
+  removeDuplicateChildrenByName(parent, frameName, 'FRAME');
+  let frame = findChildByName(parent, frameName);
+  if (!frame) {
+    frame = figma.createFrame();
+    frame.name = frameName;
+  }
+
+  frame.layoutMode = 'VERTICAL';
+  frame.primaryAxisSizingMode = 'AUTO';
+  frame.counterAxisSizingMode = 'AUTO';
+  frame.counterAxisAlignItems = 'MIN';
+  frame.itemSpacing = description ? 10 : 0;
+  frame.fills = [];
+
+  const titleNode = createTextNode(title, {
+    fontSize: opts && opts.titleSize ? opts.titleSize : 20,
+    lineHeight: opts && opts.titleLineHeight ? opts.titleLineHeight : undefined,
+    bold: true,
+  });
+  titleNode.name = 'Title';
+
+  frame.children.slice().forEach(function(child: SceneNode) { child.remove(); });
+  frame.appendChild(titleNode);
+
+  if (description) {
+    const descriptionNode = createTextNode(description, {
+      fontSize: opts && opts.descriptionSize ? opts.descriptionSize : 14,
+      lineHeight: 20,
+      opacity: 0.62,
+    });
+    descriptionNode.name = 'Description';
+    frame.appendChild(descriptionNode);
+  }
+
+  return frame;
+}
+
+export function pruneGeneratedComponentLibrary(themeNames: string[], ctx: StoryBuilderContext): void {
+  if (!ENABLE_SYMBOL_MASTERS) return;
+  const root = findExistingComponentLibraryRoot();
+  if (!root || !Array.isArray(root.children)) return;
+
+  const requestedThemes = Array.isArray(themeNames)
+    ? themeNames
+      .filter(function(theme: string) { return typeof theme === 'string' && theme.trim().length > 0; })
+      .map(function(theme: string) { return theme.trim(); })
+    : [];
+  const themeSet: Record<string, boolean> = {};
+  for (let i = 0; i < requestedThemes.length; i++) themeSet[requestedThemes[i]] = true;
+
+  const defsRaw = (COMPONENT_DEFS && Array.isArray(COMPONENT_DEFS.components)) ? COMPONENT_DEFS.components : [];
+  const defs = defsRaw
+    .map(ctx.normalizeComponentDef)
+    .filter(function(def: ComponentDef) {
+      return !!def && Array.isArray(def.stories) && def.stories.length > 0;
+    });
+
+  const expectedByTheme: Record<string, Record<string, boolean>> = {};
+  for (let i = 0; i < requestedThemes.length; i++) {
+    expectedByTheme[requestedThemes[i]] = {};
+  }
+
+  for (let i = 0; i < defs.length; i++) {
+    const def = defs[i];
+    for (let ti = 0; ti < requestedThemes.length; ti++) {
+      const theme = requestedThemes[ti];
+      if (shouldCreateCvaMaster(def) || shouldCreateStateMaster(def) || shouldCreateNonCvaMaster(def)) {
+        expectedByTheme[theme][def.name + ' [' + theme + ']'] = true;
+      }
+    }
+  }
+
+  const rootChildren = root.children.slice();
+  const seenThemeFrames: Record<string, boolean> = {};
+  for (let i = 0; i < rootChildren.length; i++) {
+    const child = rootChildren[i];
+    if (!child || child.type !== 'FRAME') continue;
+    const name = String(child.name || '');
+    if (!name.endsWith(' Masters')) continue;
+
+    if (seenThemeFrames[name]) {
+      if (isGeneratedDesignSystemNode(child)) child.remove();
+      continue;
+    }
+    seenThemeFrames[name] = true;
+
+    const theme = name.slice(0, -' Masters'.length);
+    if (!themeSet[theme]) {
+      if (isGeneratedDesignSystemNode(child)) child.remove();
+      continue;
+    }
+
+    const expectedNames = expectedByTheme[theme] || {};
+    if (!Array.isArray(child.children)) continue;
+
+    const childMasters = child.children.slice();
+    const seenMasterNames: Record<string, boolean> = {};
+    for (let mi = 0; mi < childMasters.length; mi++) {
+      const master = childMasters[mi];
+      if (!master) continue;
+      const masterName = String(master.name || '');
+      const isExpected = !!expectedNames[masterName];
+      const isGenerated = isGeneratedDesignSystemNode(master) || masterName.endsWith(' [' + theme + ']');
+
+      if (seenMasterNames[masterName]) {
+        if (isGenerated) master.remove();
+        continue;
+      }
+      seenMasterNames[masterName] = true;
+
+      if (!isExpected && isGenerated) {
+        master.remove();
+      }
+    }
+  }
+}
+
+
+function appendTypeDefaultPreview(
+  layout: LayoutInfo,
+  def: ComponentDef,
+  story: ComponentStory,
+  theme: string,
+  ctx: StoryBuilderContext
+): boolean {
+  if (!def) return false;
+  if (def.type === 'compound') {
+    const symbolInstance = tryCreateNonCvaComponentInstanceShared(def, { props: {} }, theme, ctx, componentInstanceBackend, story);
+    if (symbolInstance) {
+      layout.appendChild(symbolInstance);
+    } else {
+      const comp = createCompoundComponent(layout, def, theme);
+      if (comp) {
+        setGeneratedFallbackReason(comp, getNonCvaSymbolFallbackReason(def, { props: {} }));
+      }
+    }
+    return true;
+  }
+  if (def.type === 'simple') {
+    layout.appendChild(createSimpleStoryInstance(def, { props: {} }, theme, ctx, story));
+    return true;
+  }
+  if (def.type === 'cva') {
+    layout.appendChild(createCVAStoryInstance(def, { props: {} }, theme, ctx));
+    return true;
+  }
+  if (def.type === 'state') {
+    layout.appendChild(createStateStoryInstance(def, { props: {} }, theme, ctx, story));
+    return true;
+  }
+  return false;
+}
+
+function populateStoryLayout(
+  layout: LayoutInfo,
+  def: ComponentDef | null,
+  story: ComponentStory,
+  theme: string,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  ctx: StoryBuilderContext,
+  effectiveWidth: number,
+  opts?: { viewportWidth?: number; allowTypeDefaultFallback?: boolean }
+): { added: number; renderMode: string; useStoryTree: boolean } {
+  const layoutClasses = normalizeLayoutClasses(story.layoutClasses);
+  const skipLayoutFullWidth = shouldSkipFullWidthForClasses(layoutClasses);
+  const layoutGridCols = extractGridColumns(layoutClasses);
+  const allowAbsolute = ctx.hasExplicitHeight(layoutClasses);
+  // Story-level viewport width — passed down via context so deeper
+  // elements resolve responsive breakpoints against the viewport (matches
+  // CSS @media), not against their container's narrowed maxWidth.
+  const storyViewportWidth = opts?.viewportWidth != null && opts.viewportWidth > 0
+    ? opts.viewportWidth
+    : (Number.isFinite(effectiveWidth) && effectiveWidth > 0 ? effectiveWidth : undefined);
+  // When the tree has both a trigger element AND portal-unwrapped content:
+  //   - closed-state stories (Default): portal is NOT rendered → no __fromPortal nodes → tree unchanged
+  //   - open-state stories (OpenPanel): portal IS rendered → extract only the portal content so
+  //     the popup panel renders in Figma rather than the trigger button
+  // When the tree has only a trigger (no __fromPortal): render as-is (trigger button).
+  // Three cases for stories that have both a trigger and portal content:
+  //   1. Open-state (defaultOpen=true): extract portal content → show popup in Figma
+  //   2. Closed-state (no defaultOpen, Radix SSR renders portal anyway): filter portal out → show trigger
+  //   3. No portal content at all (base-ui closed state): show tree as-is → shows trigger
+  const rawJsxTree = story.jsxTree
+    ? resolvePortalAwareStoryTree(story.jsxTree)
+    : null;
+  // Normalize child-wildcard selector utilities (e.g. *:w-full sm:*:w-auto) into
+  // explicit per-child classes before rendering. This keeps main story renders and
+  // responsive preview renders behaviorally identical.
+  const effectiveJsxTree = rawJsxTree
+    ? propagateChildSelectorClasses(rawJsxTree)
+    : null;
+  const useStoryTree = !!effectiveJsxTree
+    && !shouldPreferInstanceRendering(def, story)
+    && !shouldSkipStoryJsxTree(def, story);
+  // The scanner extracts `story.layoutClasses` from the root JSX node's
+  // className regardless of whether the root is a plain <div> wrapper or a
+  // real component (`<ScrollArea className="rounded-md border bg-background
+  // h-48 w-60 p-3">…`). For div roots the unwrap path below replaces the
+  // wrapper with the bench, so applying the visual classes to the bench
+  // matches the consumer's intent. For component roots the component
+  // renders ITS OWN visual styling — so leaving the same `rounded-md border
+  // bg-background` on the bench paints a phantom rounded rectangle behind
+  // the real component (the symptom: two overlapping bordered boxes, the
+  // bench's padding shifting the component out of register). Reset the
+  // bench's visual styling here when we detect this overlap; the bench's
+  // sizing was already pinned by resolveStoryLayoutWidth via the layout
+  // classes, so the responsive math is unaffected.
+  const rootIsOverpaintingComponent =
+    !!effectiveJsxTree
+    && (effectiveJsxTree as JsxElement).type === 'element'
+    && !!(effectiveJsxTree as JsxElement).isComponent
+    && layoutClasses.length > 0
+    && (() => {
+      const rootClasses = splitClassName(
+        (effectiveJsxTree as JsxElement).props && (effectiveJsxTree as JsxElement).props.className
+      );
+      if (rootClasses.length === 0) return false;
+      const set: Record<string, true> = {};
+      for (const c of rootClasses) set[c] = true;
+      for (const c of layoutClasses) if (!set[c]) return false;
+      return true;
+    })();
+  if (rootIsOverpaintingComponent) {
+    try { layout.fills = []; } catch { /* ignore */ }
+    try { layout.strokes = []; } catch { /* ignore */ }
+    try { layout.cornerRadius = 0; } catch { /* ignore */ }
+    try {
+      layout.paddingLeft = 0;
+      layout.paddingRight = 0;
+      layout.paddingTop = 0;
+      layout.paddingBottom = 0;
+    } catch { /* ignore */ }
+  }
+  const layoutPadding = (layout.paddingLeft || 0) + (layout.paddingRight || 0);
+  const contentWidth = effectiveWidth ? effectiveWidth - layoutPadding : undefined;
+  let added = 0;
+  let renderMode = 'none';
+
+  if (useStoryTree) {
+    let rendered = false;
+    const rootNode = effectiveJsxTree as JsxElement | null;
+    if (layoutClasses.length > 0 && rootNode && rootNode.type === 'element' && rootNode.tagName === 'div') {
+      const rootClasses = splitClassName(rootNode.props && rootNode.props.className);
+      const sameClasses = rootClasses.length > 0 && rootClasses.join(' ') === layoutClasses.join(' ');
+      if (sameClasses) {
+        const rootStyle = tailwindClassesToStyle(rootClasses, 'default', colorGroup);
+        const rootTextToken = rootStyle.textToken || extractTextColorToken(rootClasses) || undefined;
+        const rootTextColor = resolveTextColorValue(rootStyle.text, rootTextToken, colorGroup, theme) || undefined;
+        let gridChildWidth: number | undefined;
+        const rootGridCols = extractGridColumns(rootClasses, contentWidth);
+        const gridColsForChildren = layoutGridCols || rootGridCols;
+        if (gridColsForChildren && contentWidth != null && contentWidth > 0) {
+          const gap = layout.itemSpacing || 0;
+          const available = contentWidth - gap * Math.max(0, gridColsForChildren - 1);
+          if (available > 0) {
+            gridChildWidth = Math.max(0, available / gridColsForChildren);
+          }
+        }
+        const rootContext: StoryRenderContext = {
+          textColor: rootTextColor,
+          textColorToken: rootTextToken,
+          parentLayout: layout.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+          maxWidth: gridChildWidth != null ? gridChildWidth : contentWidth,
+          viewportWidth: storyViewportWidth,
+        };
+        for (const child of rootNode.children || []) {
+          const childNode = ctx.renderJsxTree(child, colorGroup, radiusGroup, theme, 0, rootContext);
+          if (!childNode) continue;
+          layout.appendChild(childNode);
+          ctx.applyAbsoluteIfAllowed(childNode, layout, allowAbsolute);
+          const fullWidthOptions = (skipLayoutFullWidth || contentWidth != null)
+            ? { skipFullWidth: skipLayoutFullWidth, widthOverride: contentWidth }
+            : undefined;
+          applyFullWidthIfPossible(childNode, layout, fullWidthOptions);
+          applyRingIfPossible(childNode, layout);
+          applyAspectRatioIfPossible(childNode);
+          enforceGrowChildPrimaryFixed(childNode, layout);
+          const childRootGridCols = extractRootGridColsFromTree(child);
+          if ('layoutMode' in childNode && childRootGridCols != null) {
+            ctx.applyGridColumnsWithReflow(childNode as FrameNode, contentWidth);
+          }
+          rendered = true;
+        }
+        if (rendered) {
+          renderMode = 'tree-root-children';
+          added = 1;
+        }
+      }
+    }
+
+    // Transparent context-provider roots (Radix/Base UI *.Root, *.Provider) have
+    // no className or component def — they exist only to supply React context.
+    // When such a root has 2+ children (e.g. Trigger + Content in `defaultOpen`
+    // stories), rendering the wrapper adds an empty frame around the scene.
+    // Iterate its children directly into the Story Layout instead.
+    if (!rendered && rootNode && rootNode.type === 'element' && rootNode.isComponent
+        && (!rootNode.props || !rootNode.props.className)
+        && !ctx.getComponentDefByName(rootNode.tagName)
+        && Array.isArray(rootNode.children) && rootNode.children.length > 1) {
+      const rootContext: StoryRenderContext = {
+        parentLayout: layout.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+        maxWidth: contentWidth,
+        viewportWidth: storyViewportWidth,
+      };
+      for (const child of rootNode.children) {
+        const childNode = ctx.renderJsxTree(child, colorGroup, radiusGroup, theme, 0, rootContext);
+        if (!childNode) continue;
+        layout.appendChild(childNode);
+        ctx.applyAbsoluteIfAllowed(childNode, layout, allowAbsolute);
+        const fullWidthOptions = (skipLayoutFullWidth || contentWidth != null)
+          ? { skipFullWidth: skipLayoutFullWidth, widthOverride: contentWidth }
+          : undefined;
+        applyFullWidthIfPossible(childNode, layout, fullWidthOptions);
+        applyRingIfPossible(childNode, layout);
+        applyAspectRatioIfPossible(childNode);
+        enforceGrowChildPrimaryFixed(childNode, layout);
+        rendered = true;
+      }
+      if (rendered) {
+        renderMode = 'tree-root-children-unwrapped';
+        added = 1;
+      }
+    }
+
+    if (!rendered) {
+      const treeContext: StoryRenderContext = {
+        maxWidth: contentWidth,
+        parentLayout: layout.layoutMode === 'HORIZONTAL' ? 'HORIZONTAL' : 'VERTICAL',
+        viewportWidth: storyViewportWidth,
+      };
+      const treeNode = ctx.renderJsxTree(effectiveJsxTree, colorGroup, radiusGroup, theme, 0, treeContext);
+      if (treeNode) {
+        layout.appendChild(treeNode);
+        ctx.applyAbsoluteIfAllowed(treeNode, layout, allowAbsolute);
+        const fullWidthOptions = (skipLayoutFullWidth || contentWidth != null)
+          ? { skipFullWidth: skipLayoutFullWidth, widthOverride: contentWidth }
+          : undefined;
+        applyFullWidthIfPossible(treeNode, layout, fullWidthOptions);
+        applyRingIfPossible(treeNode, layout);
+        applyAspectRatioIfPossible(treeNode);
+        enforceGrowChildPrimaryFixed(treeNode, layout);
+        const treeRootGridCols = extractRootGridColsFromTree(effectiveJsxTree);
+        if ('layoutMode' in treeNode && treeRootGridCols != null) {
+          ctx.applyGridColumnsWithReflow(treeNode as FrameNode, contentWidth);
+        }
+
+        if (effectiveWidth && rootNode && rootNode.type === 'element') {
+          const rootClasses = splitClassName(rootNode.props && rootNode.props.className);
+          const wantsFullWidth = rootClasses.includes('w-full');
+          if (wantsFullWidth && 'resize' in treeNode) {
+            try {
+              // Respect max-w-* constraint: clamp to min(layout.width, max-width).
+              const maxWConstraint = extractMaxWidth(rootClasses);
+              const targetWidth = maxWConstraint != null ? Math.min(layout.width, maxWConstraint) : layout.width;
+              treeNode.resize(targetWidth, treeNode.height);
+              const treeLayout = ('layoutMode' in treeNode) ? treeNode.layoutMode : 'VERTICAL';
+              if (treeLayout === 'HORIZONTAL' && 'primaryAxisSizingMode' in treeNode) {
+                treeNode.primaryAxisSizingMode = 'FIXED';
+              } else if (treeLayout === 'VERTICAL' && 'counterAxisSizingMode' in treeNode) {
+                treeNode.counterAxisSizingMode = 'FIXED';
+              }
+              // Reapply right-anchored absolute children (e.g. DialogPrimitive.Close) after resize.
+              if (treeNode.type === 'FRAME') {
+                reapplyRightPositionedChildren(treeNode, targetWidth);
+              }
+            } catch (_err) {
+              // ignore resize errors
+            }
+          }
+        }
+        added = 1;
+        renderMode = 'tree-root';
+      }
+    }
+  }
+
+  // `applyGridColumnsIfPossible` guards on `cols <= 1` internally, so
+  // forwarding `layoutGridCols === 1` (the Tailwind default for plain
+  // `grid` with no `grid-cols-N`) is a no-op. The truthiness check
+  // here just avoids a function call when there's no grid at all.
+  if (layoutGridCols) {
+    ctx.applyGridColumnsWithReflow(layout, effectiveWidth || layout.width, layoutGridCols);
+  }
+
+  const layoutHasChildren = hasNodeChildren(layout);
+  const normalizedDefName = normalizeComponentName(def && def.name ? def.name : '');
+  const isGuardedPortalDef =
+    (normalizedDefName && INSTANCE_FALLBACK_COMPONENTS.has(normalizedDefName))
+    || jsxTreeIsPortalTriggerOnly(story && story.jsxTree);
+  if (added === 0 && !layoutHasChildren && isGuardedPortalDef) {
+    added += renderGuardedPortalStoryInstances(layout, def, story, theme, colorGroup, radiusGroup, ctx);
+    if (added > 0) {
+      renderMode = 'guarded-portal';
+    }
+  }
+
+  if (added === 0 && !layoutHasChildren && !useStoryTree) {
+    if (def) {
+      for (const instance of story.instances || []) {
+        if (!instance || !instance.componentName) continue;
+        const normalizedInstanceName = instance.componentName.toLowerCase().replace(/-/g, '');
+        const normalizedCurrentDefName = def.name.toLowerCase().replace(/-/g, '');
+        if (normalizedInstanceName !== normalizedCurrentDefName) continue;
+        if (isGuardedPortalDef) continue;
+        if (appendResolvedInstance(layout, def, instance, story, theme, colorGroup, radiusGroup, ctx)) {
+          added++;
+        }
+      }
+    } else {
+      added = renderStoryInstances(layout, story, theme, colorGroup, radiusGroup, ctx);
+    }
+    if (added > 0) {
+      renderMode = 'instances';
+    }
+  }
+
+  const finalLayoutChildren = layout.children;
+  const hasFinalLayoutChildren = !!finalLayoutChildren
+    && typeof finalLayoutChildren.length === 'number'
+    && finalLayoutChildren.length > 0;
+  if (added === 0 && !hasFinalLayoutChildren && opts?.allowTypeDefaultFallback && def) {
+    if (appendTypeDefaultPreview(layout, def, story, theme, ctx)) {
+      renderMode = 'type-default';
+    }
+  }
+
+  if (added === 0 && !hasNodeChildren(layout) && !opts?.allowTypeDefaultFallback) {
+    layout.appendChild(createTextNode(story.name || 'Story', { fontSize: 12, opacity: 0.6 }));
+    renderMode = 'placeholder';
+  }
+
+  // Distribute remaining vertical space among flex-1/grow children inside
+  // every viewport-anchored VERTICAL frame (Story Layout itself plus any
+  // nested fixed-height sub-frame). Runs before absolute-reflow so deferred
+  // positions settle against the final heights.
+  walkVerticalFlexGrow(layout);
+
+  // Final pass: resolve deferred absolute positioning after all story-level
+  // width/height/layout operations have completed.
+  reflowDeferredAbsolutePositioningTree(layout);
+
+  return { added, renderMode, useStoryTree };
+}
+
+function walkVerticalFlexGrow(node: SceneNode): void {
+  if (!node || typeof node !== 'object') return;
+  if (node.type === 'FRAME' && node.layoutMode === 'VERTICAL' && node.primaryAxisSizingMode === 'FIXED') {
+    applyVerticalFlexGrowIfPossible(node);
+  }
+  if (!('children' in node) || !Array.isArray(node.children)) return;
+  for (let i = 0; i < node.children.length; i++) walkVerticalFlexGrow(node.children[i]);
+}
+
+export function renderStandaloneStory(
+  story: ComponentStory,
+  theme: string,
+  ctx: StoryBuilderContext,
+  viewportWidth?: number
+): FrameNode {
+  const themeContext = getThemeContext(theme);
+  const colorGroup = themeContext.colorGroup;
+  const radiusGroup = themeContext.radiusGroup;
+  const layoutClasses = normalizeLayoutClasses(story.layoutClasses);
+
+  const layout = figma.createFrame();
+  layout.name = 'Story Layout';
+  layout.primaryAxisSizingMode = 'AUTO';
+  layout.counterAxisSizingMode = 'AUTO';
+  layout.fills = [];
+  ctx.applyClipBehavior(layout, layoutClasses);
+
+  ctx.applyLayoutClasses(layout, layoutClasses, colorGroup, radiusGroup, theme);
+  const effectiveWidth = resolveStoryLayoutWidth(story, layout, layoutClasses, ctx, viewportWidth);
+  resolveStoryLayoutHeight(story, layout, layoutClasses, ctx);
+  const result = populateStoryLayout(layout, null, story, theme, colorGroup, radiusGroup, ctx, effectiveWidth, {
+    viewportWidth,
+    allowTypeDefaultFallback: false,
+  });
+  expandStoryLayoutForPortalContent(layout);
+  setStoryRenderDiagnostics(layout, null, story, result.renderMode, result.added, result.useStoryTree);
+
+  return layout;
+}
+
+/**
+ * Portal panels (marked via `inkbridge:portal-panel` pluginData) visually escape
+ * their parent in the browser. In Figma we render them inside the Story Layout
+ * frame, so if the layout is narrower than the panel it clips. Walk the subtree,
+ * find portal panels, grow the layout to contain them.
+ */
+function expandStoryLayoutForPortalContent(layout: FrameNode): void {
+  if (!layout || typeof layout.width !== 'number') return;
+  const layoutBox = layout.absoluteBoundingBox;
+  if (!layoutBox) return;
+  let requiredWidth = layout.width;
+  const stack: SceneNode[] = Array.isArray(layout.children) ? layout.children.slice() : [];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (!node) continue;
+    try {
+      const tag = typeof node.getPluginData === 'function'
+        ? node.getPluginData('inkbridge:portal-panel')
+        : '';
+      if (tag === '1' && node.absoluteBoundingBox) {
+        const overflow = (node.absoluteBoundingBox.x + node.absoluteBoundingBox.width)
+          - (layoutBox.x + layoutBox.width);
+        if (overflow > 0) requiredWidth = Math.max(requiredWidth, layout.width + overflow);
+      }
+    } catch { /* ignore */ }
+    if ('children' in node && Array.isArray(node.children) && node.children.length > 0) {
+      for (const child of node.children) stack.push(child);
+    }
+  }
+  if (requiredWidth > layout.width) {
+    try {
+      layout.resize(requiredWidth, layout.height);
+      if (layout.layoutMode === 'HORIZONTAL' && 'primaryAxisSizingMode' in layout) {
+        layout.primaryAxisSizingMode = 'FIXED';
+      } else if ('counterAxisSizingMode' in layout) {
+        layout.counterAxisSizingMode = 'FIXED';
+      }
+    } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Build (or incrementally update) a UI components section on the Design System page.
+ *
+ * ## Incremental strategy
+ * The section frame and per-theme column frames are reused across runs — only
+ * their contents are updated. Inside each column, component blocks are diffed
+ * individually:
+ *
+ *   blockHash = defHash + ":" + tokenHash
+ *
+ * - Hash match  → block is left completely untouched (node ID preserved).
+ * - Hash change → block is removed and rebuilt at the same auto-layout index.
+ * - New block   → appended to the end of the component list.
+ * - Removed     → blocks whose component no longer exists in defs are deleted.
+ *
+ * Pack stories are grouped in a named "Pack Stories" container and rebuilt
+ * whenever the pack story list changes (compared by hash).
+ *
+ * Section x/y are only set on first creation. Existing sections keep their
+ * current position so designers can reposition without it resetting.
+ */
+export interface CreateUIComponentsOptions {
+  primary?: boolean;
+  secondary?: boolean;
+  themeNames?: string[];
+  sectionTitle?: string;
+  tokenHash?: string;
+  showSectionHeader?: boolean;
+  sectionPaddingX?: number;
+  sectionPaddingY?: number;
+  yOffset?: number;
+  xOffset?: number;
+  excludeComponents?: string[];
+  preserveUnselectedComponents?: boolean;
+  storyTagFilter?: string[];
+  onlyComponents?: string[];
+  /**
+   * Optional progress hook. Called at phase boundaries so the loading
+   * view can show finer-grained status than the single
+   * "Building components…" message. Pair with `Promise.resolve()` and
+   * `setTimeout(0)` upstream so the iframe gets a paint frame between
+   * synchronous build chunks. Each call costs ~50ms of yield — limit to
+   * per-theme and per-atomic-section (atoms / molecules / organisms),
+   * not per-component, or the overhead dominates the savings.
+   *
+   * Accepts either a flat string (legacy) or `{ phase, detail }`. emit()
+   * below sends detail-only updates so the parent-set phase
+   * ("Building components…") stays visible as a sticky header.
+   */
+  onStatus?: (status: StatusUpdate) => Promise<void> | void;
+}
+
+export async function createUIComponents(parent: FrameNode | PageNode, opts: CreateUIComponentsOptions, ctx: StoryBuilderContext): Promise<FrameNode> {
+  const options = {
+    primary: true,
+    secondary: true,
+    themeNames: getThemeNames(TOKENS),
+    ...(opts || {}),
+  };
+  debug('createUIComponents start', { opts: options });
+
+  // Progress hook + a soft yield between phases. `onStatus` posts a
+  // status update to the loading view. `noYield: true` posts the message
+  // (the iframe runs on its own thread and updates the panel) but skips
+  // the 50ms wait — without that, every fine-grained emit would let
+  // Figma's canvas paint a half-built scene-graph state, producing the
+  // theme-column overlap the user sees mid-build. Coarse phases in
+  // main.ts (Reading components / Building tokens / Building components)
+  // still yield 50ms so the canvas paints between top-level phases.
+  const onStatus = options.onStatus;
+  const phaseStart = Date.now();
+  async function emit(message: string): Promise<void> {
+    if (INKBRIDGE_PERF_LOGS) {
+      const elapsed = ((Date.now() - phaseStart) / 1000).toFixed(1);
+      console.log('[Inkbridge][build] +' + elapsed + 's  ' + message);
+    }
+    if (onStatus) {
+      await Promise.resolve(onStatus({ detail: message, noYield: true }));
+    }
+  }
+
+  const sectionTitle: string = options.sectionTitle || 'UI Components';
+
+  // tokenHash is computed once per run in design-system.ts and forwarded here.
+  // It covers all TOKENS so any token change invalidates all component blocks.
+  const tokenHash: string = typeof options.tokenHash === 'string' ? options.tokenHash : '';
+  const showSectionHeader = options.showSectionHeader !== false;
+  const sectionPaddingX = typeof options.sectionPaddingX === 'number'
+    ? options.sectionPaddingX
+    : (showSectionHeader ? BOARD_LAYOUT.sectionPaddingX : 0);
+  const sectionPaddingY = typeof options.sectionPaddingY === 'number'
+    ? options.sectionPaddingY
+    : (showSectionHeader ? BOARD_LAYOUT.sectionPaddingY : 0);
+
+  // --- Find or create the section frame ---
+  // On first run it is created and positioned. On subsequent runs the existing
+  // frame is reused so its position and any designer annotations are preserved.
+  removeDuplicateChildrenByName(parent, sectionTitle, 'FRAME');
+  let section: FrameNode = findChildByName(parent, sectionTitle);
+  if (!section) {
+    section = figma.createFrame();
+    section.name = sectionTitle;
+    const offsetY = typeof options.yOffset === 'number' ? options.yOffset : 0;
+    const offsetX = typeof options.xOffset === 'number' ? options.xOffset : 0;
+    section.x = offsetX;
+    section.y = offsetY;
+    parent.appendChild(section);
+  }
+  tagGeneratedNode(section, 'section:' + sectionTitle);
+  section.layoutMode = 'VERTICAL';
+  section.itemSpacing = showSectionHeader ? BOARD_LAYOUT.boardGap : 0;
+  section.primaryAxisSizingMode = 'AUTO';
+  section.counterAxisSizingMode = 'AUTO';
+  section.paddingLeft = section.paddingRight = sectionPaddingX;
+  section.paddingTop = section.paddingBottom = sectionPaddingY;
+  section.counterAxisAlignItems = 'MIN';
+  section.fills = [];
+  ctx.applyClipBehavior(section, []);
+  removeDirectTextChildren(section);
+
+  // Early reflow guard against the Design Tokens row: re-anchor section.y
+  // before any visible content is built so a previously-created section
+  // (with stale y from before the tokens row grew) doesn't paint
+  // overlapping tokens. design-system.ts runs the same guard AFTER
+  // `createUIComponents` returns; this one front-loads it. Mirrors the
+  // post-build math (only pushes y down, never up) so designer-set
+  // positions further down are preserved.
+  const tokensSibling = findChildByName(parent, 'Design Tokens') as FrameNode | null;
+  if (tokensSibling) {
+    const tokensY = typeof tokensSibling.y === 'number' ? tokensSibling.y : 0;
+    const tokensHeight = typeof tokensSibling.height === 'number' ? tokensSibling.height : 0;
+    const minY = tokensY + tokensHeight + 80;
+    if (section.y < minY) section.y = minY;
+    const tokensX = typeof tokensSibling.x === 'number' ? tokensSibling.x : 0;
+    if (section.x < tokensX) section.x = tokensX;
+  }
+
+
+  const existingSectionHeader = findChildByName(section, 'Section Header');
+  if (showSectionHeader) {
+    const sectionHeader = ensureHeaderBlock(section, 'Section Header', sectionTitle, null, {
+      titleSize: 32,
+      titleLineHeight: 38,
+    });
+    if (findChildIndexByName(section, 'Section Header') !== 0) {
+      section.insertChild(0, sectionHeader);
+    }
+  } else if (existingSectionHeader) {
+    existingSectionHeader.remove();
+  }
+
+  function formatThemeLabel(theme: string): string {
+    if (!theme) return 'Theme';
+    return theme.charAt(0).toUpperCase() + theme.slice(1);
+  }
+
+  // Build a single component block frame (all stories for one component def).
+  // Returns the newly created block frame.
+  function buildComponentBlock(def: ComponentDef, theme: string, _colFrame: FrameNode): FrameNode {
+    const themeContext = getThemeContext(theme);
+    const colorGroup = themeContext.colorGroup;
+    const radiusGroup = themeContext.radiusGroup;
+
+    const block = figma.createFrame();
+    block.name = def.name;
+    block.layoutMode = 'VERTICAL';
+    block.itemSpacing = BOARD_LAYOUT.componentTitleGap;
+    block.primaryAxisSizingMode = 'AUTO';
+    block.counterAxisSizingMode = 'AUTO';
+    block.counterAxisAlignItems = 'MIN';
+    block.fills = [];
+    ctx.applyClipBehavior(block, []);
+
+    block.appendChild(createTextNode(def.name, { fontSize: 22, lineHeight: 28, bold: true }));
+
+    const storyList = def.stories || [];
+    for (let storyIndex = 0; storyIndex < storyList.length; storyIndex++) {
+      const story = storyList[storyIndex];
+      const storyWrap = figma.createFrame();
+      storyWrap.name = story.name;
+      storyWrap.layoutMode = 'VERTICAL';
+      storyWrap.itemSpacing = BOARD_LAYOUT.storyGap;
+      storyWrap.primaryAxisSizingMode = 'AUTO';
+      storyWrap.counterAxisSizingMode = 'AUTO';
+      storyWrap.counterAxisAlignItems = 'MIN';
+      storyWrap.fills = [];
+      ctx.applyClipBehavior(storyWrap, []);
+
+      storyWrap.appendChild(createTextNode(story.name, { fontSize: 16, lineHeight: 22, opacity: 0.6, textAlignHorizontal: 'LEFT' }));
+
+      const layout = figma.createFrame();
+      layout.name = 'Story Layout';
+      layout.primaryAxisSizingMode = 'AUTO';
+      layout.counterAxisSizingMode = 'AUTO';
+      layout.fills = [];
+
+      const layoutClasses = normalizeLayoutClasses(story.layoutClasses);
+      ctx.applyClipBehavior(layout, layoutClasses);
+      ctx.applyLayoutClasses(layout, layoutClasses, colorGroup, radiusGroup, theme);
+
+      const effectiveWidth = resolveStoryLayoutWidth(story, layout, layoutClasses, ctx);
+      resolveStoryLayoutHeight(story, layout, layoutClasses, ctx);
+      const populated = populateStoryLayout(layout, def, story, theme, colorGroup, radiusGroup, ctx, effectiveWidth, {
+        allowTypeDefaultFallback: true,
+      });
+      expandStoryLayoutForPortalContent(layout);
+      const added = populated.added;
+      const renderMode = populated.renderMode;
+      const useStoryTree = populated.useStoryTree;
+      setStoryRenderDiagnostics(layout, def, story, renderMode, added, useStoryTree);
+
+      storyWrap.appendChild(layout);
+      if (shouldRenderStatesForStory(def, story, storyIndex)) {
+        const statesBlock = createStatePreviewBlock(def, story, theme, ctx);
+        if (statesBlock) storyWrap.appendChild(statesBlock);
+      }
+      // No pre-flight gate — `createResponsivePreviewBlock` already
+      // returns null when the story has no responsive signals (layout /
+      // tree / instance classes all lack `sm:`/`md:`/`lg:` etc.) or when
+      // the breakpoint set collapses to one, so the gate would have been
+      // a strict subset of the renderer's existing check.
+      const responsiveBlock = createResponsivePreviewBlock(def, story, theme, ctx);
+      if (responsiveBlock) storyWrap.appendChild(responsiveBlock);
+      block.appendChild(storyWrap);
+    }
+
+    return block;
+  }
+
+  // Build (or incrementally update) a theme column frame inside the Columns container.
+  async function addColumn(label: string, theme: string): Promise<FrameNode> {
+    await emit('Building ' + label.toLowerCase() + ' theme…');
+    // --- Find or create the column frame ---
+    // Column frames live inside the "Columns" container (built below) and are
+    // identified by name. Existing columns are reused so their position in the
+    // auto-layout and any sub-frames with preserved node IDs stay intact.
+    const columnsContainer: FrameNode | null = findChildByName(section, 'Columns') as FrameNode | null;
+    if (columnsContainer) {
+      removeDuplicateChildrenByName(columnsContainer, label + ' Column', 'FRAME');
+    }
+    let colFrame: FrameNode | null = columnsContainer ? findChildByName(columnsContainer, label + ' Column') as FrameNode | null : null;
+    if (!colFrame) {
+      colFrame = figma.createFrame();
+      colFrame.name = label + ' Column';
+      // Park the new column far off-screen. `figma.createFrame()` in
+      // API 1.0 auto-appends to `figma.currentPage`, so the freshly-
+      // created node is *not* orphan — it sits as a direct child of
+      // the Design System page at default `(0, 0)` until the outer
+      // loop's `columns.insertChild(ti, themeCol)` re-parents it
+      // AFTER addColumn returns. Between then and now the per-section
+      // yields let Figma paint that intermediate state. (0, 0) on the
+      // design system page is right inside the Design Tokens row, so
+      // the user sees the column overlap tokens for the entire build.
+      // Auto-layout overrides x/y when the column lands in the
+      // `Columns` HORIZONTAL container, so this park has no effect on
+      // the final position. See also `componentList` / `packStoriesFrame`
+      // / `sectionFrame` below — they get appended into the off-screen
+      // colFrame immediately for the same reason.
+      colFrame.x = -100000;
+      colFrame.y = -100000;
+    }
+    tagGeneratedNode(colFrame, 'theme-column:' + sectionTitle + ':' + theme);
+    colFrame.layoutMode = 'VERTICAL';
+    colFrame.itemSpacing = BOARD_LAYOUT.columnGap;
+    colFrame.primaryAxisSizingMode = 'AUTO';
+    colFrame.counterAxisSizingMode = 'AUTO';
+    colFrame.counterAxisAlignItems = 'MIN';
+    colFrame.paddingLeft = colFrame.paddingRight = BOARD_LAYOUT.columnPaddingX;
+    colFrame.paddingTop = colFrame.paddingBottom = BOARD_LAYOUT.columnPaddingY;
+    colFrame.fills = [];
+    // Keep columns transparent; story surfaces are responsible for their own backgrounds.
+    ctx.applyClipBehavior(colFrame, []);
+    removeDirectTextChildren(colFrame);
+    const themeHeader = ensureHeaderBlock(
+      colFrame,
+      'Theme Header',
+      label + ' Theme',
+      'Generated component board with grouped stories and larger comparison spacing.',
+      { titleSize: 32, titleLineHeight: 38, descriptionSize: 14 }
+    );
+    if (findChildIndexByName(colFrame, 'Theme Header') !== 0) {
+      colFrame.insertChild(0, themeHeader);
+    }
+
+    // --- Pack stories (incremental by hash) ---
+    // Wrapped in a named container so we can cleanly replace them without
+    // disturbing the component blocks below.
+    const pack = getActivePack();
+    const packStories = pack && pack.stories ? pack.stories : [];
+    const storyTagFilter = options && options.storyTagFilter ? String(options.storyTagFilter) : '';
+    const filteredStories = packStories.filter(function(s: ComponentStory) {
+      if (!storyTagFilter) return true;
+      const tags = s.tags || [];
+      return tags.indexOf(storyTagFilter) !== -1;
+    });
+    const packStoriesHash = hashString(JSON.stringify(filteredStories) + theme);
+    removeDuplicateChildrenByName(colFrame, 'Showcase Stories', 'FRAME');
+    let packStoriesFrame: FrameNode | null = findChildByName(colFrame, 'Showcase Stories');
+    if (!packStoriesFrame || getFrameHash(packStoriesFrame) !== packStoriesHash) {
+      if (packStoriesFrame) packStoriesFrame.remove();
+      const stalePackFrame = findChildByName(colFrame, 'Pack Stories');
+      if (stalePackFrame) stalePackFrame.remove();
+      if (filteredStories.length > 0) {
+        packStoriesFrame = figma.createFrame();
+        packStoriesFrame.name = 'Showcase Stories';
+        // Append into colFrame immediately so the API-1.0 auto-append to
+        // currentPage doesn't leave it at ds-page (0,0) during the
+        // synchronous build of its children (same class of bug as
+        // `componentList` above).
+        colFrame.appendChild(packStoriesFrame);
+        packStoriesFrame.layoutMode = 'VERTICAL';
+        packStoriesFrame.itemSpacing = BOARD_LAYOUT.showcaseGap;
+        packStoriesFrame.primaryAxisSizingMode = 'AUTO';
+        packStoriesFrame.counterAxisSizingMode = 'AUTO';
+        packStoriesFrame.counterAxisAlignItems = 'MIN';
+        packStoriesFrame.fills = [];
+        ctx.applyClipBehavior(packStoriesFrame, []);
+        packStoriesFrame.appendChild(ensureHeaderBlock(
+          packStoriesFrame,
+          'Section Header',
+          'Showcase Stories',
+          'Larger composite stories rendered before the component catalog.',
+          { titleSize: 20, titleLineHeight: 26, descriptionSize: 14 }
+        ));
+        for (let si = 0; si < filteredStories.length; si++) {
+          const story = filteredStories[si];
+          const storyBlock = figma.createFrame();
+          storyBlock.name = story.name || 'Story';
+          storyBlock.layoutMode = 'VERTICAL';
+          storyBlock.itemSpacing = BOARD_LAYOUT.componentTitleGap;
+          storyBlock.primaryAxisSizingMode = 'AUTO';
+          storyBlock.counterAxisSizingMode = 'AUTO';
+          storyBlock.counterAxisAlignItems = 'MIN';
+          storyBlock.fills = [];
+          ctx.applyClipBehavior(storyBlock, []);
+          storyBlock.appendChild(createTextNode(story.name || 'Story', { fontSize: 16, lineHeight: 22, bold: true }));
+          storyBlock.appendChild(renderStandaloneStory(story, theme, ctx));
+          packStoriesFrame.appendChild(storyBlock);
+        }
+        setFrameHash(packStoriesFrame, packStoriesHash);
+        tagGeneratedNode(packStoriesFrame, 'showcase-stories:' + sectionTitle + ':' + theme);
+      }
+    }
+    packStoriesFrame = findChildByName(colFrame, 'Showcase Stories');
+    if (packStoriesFrame && findChildIndexByName(colFrame, 'Showcase Stories') !== 1) {
+      colFrame.insertChild(1, packStoriesFrame);
+    }
+
+    // --- Component blocks (per-component hash diff) ---
+    // "Component Blocks" is a named container holding one block per component def.
+    // We find or create it, then diff its contents against the current defs list.
+    removeDuplicateChildrenByName(colFrame, 'Component Blocks', 'FRAME');
+    let componentList: FrameNode = findChildByName(colFrame, 'Component Blocks');
+    if (!componentList) {
+      componentList = figma.createFrame();
+      componentList.name = 'Component Blocks';
+      componentList.layoutMode = 'VERTICAL';
+      // Append into colFrame IMMEDIATELY so the API-1.0 auto-append to
+      // figma.currentPage doesn't leave it as a ds-page direct child at
+      // (0, 0) — that's the frame we observed sitting ON TOP OF the
+      // Design Tokens row during the entire build (47k px tall, exactly
+      // where the user reported overlap). Attaching it to colFrame
+      // (parked at -100000, -100000) means the build's incremental
+      // content is built in the off-screen tree.
+      colFrame.appendChild(componentList);
+    }
+    tagGeneratedNode(componentList, 'component-blocks:' + sectionTitle + ':' + theme);
+    componentList.primaryAxisSizingMode = 'AUTO';
+    componentList.counterAxisSizingMode = 'AUTO';
+    componentList.counterAxisAlignItems = 'MIN';
+    componentList.itemSpacing = BOARD_LAYOUT.sectionGroupGap;
+    componentList.fills = [];
+    ctx.applyClipBehavior(componentList, []);
+
+    const defsRaw = (COMPONENT_DEFS && COMPONENT_DEFS.components) ? COMPONENT_DEFS.components : [];
+    const onlyComponents: string[] | undefined = options.onlyComponents;
+    const excludeComponents: string[] | undefined = options.excludeComponents;
+    const preserveUnselectedComponents = options.preserveUnselectedComponents === true;
+    const defs = defsRaw
+      .map(ctx.normalizeComponentDef)
+      .filter(function(d: ComponentDef) {
+        if (!d || !d.stories || d.stories.length === 0) return false;
+        if (onlyComponents && onlyComponents.length > 0) return onlyComponents.includes(d.name);
+        if (excludeComponents && excludeComponents.length > 0) return !excludeComponents.includes(d.name);
+        return true;
+      })
+      .sort(function(a: ComponentDef, b: ComponentDef) { return a.name.localeCompare(b.name); });
+
+    warmSymbolMasters(defs, theme, ctx);
+
+    const groupedDefs = groupComponentDefs(defs);
+    const expectedSectionNames: Record<string, boolean> = {};
+    for (let gi = 0; gi < groupedDefs.length; gi++) {
+      expectedSectionNames[getComponentSectionName(groupedDefs[gi].section)] = true;
+    }
+
+    const existingGroups: SceneNode[] = componentList.children ? Array.from(componentList.children) : [];
+    const seenSectionFrames: Record<string, boolean> = {};
+    for (let gi = 0; gi < existingGroups.length; gi++) {
+      const existingGroup = existingGroups[gi];
+      const duplicate = !!seenSectionFrames[existingGroup.name];
+      const stale = !expectedSectionNames[existingGroup.name];
+      if (duplicate || (stale && !preserveUnselectedComponents)) {
+        existingGroup.remove();
+      } else {
+        seenSectionFrames[existingGroup.name] = true;
+      }
+    }
+
+    for (let gi = 0; gi < groupedDefs.length; gi++) {
+      const group = groupedDefs[gi];
+      const sectionName = getComponentSectionName(group.section);
+      // Per-atomic-section status (atoms / molecules / organisms / …).
+      // Includes the theme label so a multi-theme run shows clearly which
+      // pass is in flight. Yields the JS thread so the iframe repaints.
+      await emit(label + ' theme · ' + sectionName + ' (' + group.defs.length + ' components)');
+      removeDuplicateChildrenByName(componentList, sectionName, 'FRAME');
+      let sectionFrame: FrameNode = findChildByName(componentList, sectionName);
+      if (!sectionFrame) {
+        sectionFrame = figma.createFrame();
+        sectionFrame.name = sectionName;
+        // Append into componentList immediately (componentList is now
+        // inside the off-screen colFrame, so sectionFrame inherits the
+        // off-screen position). Same class of bug as `componentList`
+        // and `packStoriesFrame` above — without this, sectionFrame
+        // sits at ds-page (0,0) during the synchronous build of its
+        // component blocks. The later `componentList.appendChild` /
+        // `componentList.insertChild` calls then no-op or re-order.
+        componentList.appendChild(sectionFrame);
+      }
+      tagGeneratedNode(sectionFrame, 'atomic-section:' + sectionTitle + ':' + theme + ':' + group.section.key);
+
+      sectionFrame.layoutMode = 'VERTICAL';
+      sectionFrame.primaryAxisSizingMode = 'AUTO';
+      sectionFrame.counterAxisSizingMode = 'AUTO';
+      sectionFrame.counterAxisAlignItems = 'MIN';
+      sectionFrame.itemSpacing = BOARD_LAYOUT.sectionTitleGap;
+      sectionFrame.fills = [];
+      ctx.applyClipBehavior(sectionFrame, []);
+
+      const groupHeader = ensureHeaderBlock(
+        sectionFrame,
+        'Section Header',
+        group.section.title,
+        group.section.description,
+        { titleSize: 26, titleLineHeight: 32, descriptionSize: 14 }
+      );
+      if (findChildIndexByName(sectionFrame, 'Section Header') !== 0) {
+        sectionFrame.insertChild(0, groupHeader);
+      }
+
+      removeDuplicateChildrenByName(sectionFrame, 'Blocks', 'FRAME');
+      let groupBlocks: FrameNode = findChildByName(sectionFrame, 'Blocks');
+      if (!groupBlocks) {
+        groupBlocks = figma.createFrame();
+        groupBlocks.name = 'Blocks';
+        sectionFrame.appendChild(groupBlocks);
+      }
+      tagGeneratedNode(groupBlocks, 'atomic-section-blocks:' + sectionTitle + ':' + theme + ':' + group.section.key);
+      groupBlocks.layoutMode = 'VERTICAL';
+      groupBlocks.primaryAxisSizingMode = 'AUTO';
+      groupBlocks.counterAxisSizingMode = 'AUTO';
+      groupBlocks.counterAxisAlignItems = 'MIN';
+      groupBlocks.itemSpacing = BOARD_LAYOUT.componentBlockGap;
+      groupBlocks.fills = [];
+      ctx.applyClipBehavior(groupBlocks, []);
+
+      const expectedNames: Record<string, boolean> = {};
+      for (let di = 0; di < group.defs.length; di++) {
+        expectedNames[group.defs[di].name] = true;
+      }
+
+      const existingBlocks: SceneNode[] = groupBlocks.children ? Array.from(groupBlocks.children) : [];
+      const seenComponentBlocks: Record<string, boolean> = {};
+      for (let ei = 0; ei < existingBlocks.length; ei++) {
+        const existingBlock = existingBlocks[ei];
+        const duplicate = !!seenComponentBlocks[existingBlock.name];
+        const stale = !expectedNames[existingBlock.name];
+        if (duplicate || (stale && !preserveUnselectedComponents)) {
+          existingBlock.remove();
+          debug('Removed stale component block', { name: existingBlock.name });
+        } else {
+          seenComponentBlocks[existingBlock.name] = true;
+        }
+      }
+
+      for (let di = 0; di < group.defs.length; di++) {
+        const def = group.defs[di];
+        const blockHash = hashDef(def) + ':' + tokenHash + ':' + RENDER_ENGINE_VERSION;
+        const existingBlock: FrameNode = findChildByName(groupBlocks, def.name);
+        const existingBlockIndex = existingBlock ? findChildIndexByName(groupBlocks, def.name) : -1;
+
+        if (existingBlock && getFrameHash(existingBlock) === blockHash) {
+          const currentIndex = existingBlockIndex;
+          if (!preserveUnselectedComponents && currentIndex !== di) {
+            groupBlocks.insertChild(di, existingBlock);
+          }
+          debug('Component block unchanged — skipped', { name: def.name });
+          continue;
+        }
+
+        let insertIndex = di;
+        if (preserveUnselectedComponents) {
+          insertIndex = existingBlockIndex >= 0 ? existingBlockIndex : groupBlocks.children.length;
+        }
+        if (existingBlock) {
+          existingBlock.remove();
+          debug('Component block changed — rebuilding', { name: def.name });
+        }
+
+        // Per-component timing log to the plugin console (no toast,
+        // no yield — would balloon overhead). Lets us see in dev tools
+        // which components dominate build time without slowing the run.
+        const componentStart = Date.now();
+        const newBlock = buildComponentBlock(def, theme, colFrame);
+        const componentMs = Date.now() - componentStart;
+        if (INKBRIDGE_PERF_LOGS && componentMs > 50) {
+          console.log('[Inkbridge][build]   · ' + def.name + ' (' + theme + ')  ' + componentMs + 'ms');
+        }
+        setFrameHash(newBlock, blockHash);
+        tagGeneratedNode(newBlock, 'component-block:' + sectionTitle + ':' + theme + ':' + def.name);
+
+        if (insertIndex >= 0 && insertIndex < groupBlocks.children.length) {
+          groupBlocks.insertChild(insertIndex, newBlock);
+        } else {
+          groupBlocks.appendChild(newBlock);
+        }
+      }
+
+      const currentSectionIndex = findChildIndexByName(componentList, sectionName);
+      if (currentSectionIndex === -1) {
+        // Newly created section: always attach, even when preserving unselected.
+        // Without this, a subset run on a fresh file produces a section frame
+        // that never enters the component list and no blocks are rendered.
+        componentList.appendChild(sectionFrame);
+      } else if (!preserveUnselectedComponents && currentSectionIndex !== gi) {
+        componentList.insertChild(gi, sectionFrame);
+      }
+    }
+
+    if (componentList.children.length > 0 && !findChildByName(colFrame, 'Component Blocks')) {
+      colFrame.appendChild(componentList);
+    }
+    if (findChildByName(colFrame, 'Component Blocks')) {
+      const componentListIndex = packStoriesFrame ? 2 : 1;
+      if (findChildIndexByName(colFrame, 'Component Blocks') !== componentListIndex) {
+        colFrame.insertChild(componentListIndex, componentList);
+      }
+    }
+
+    return colFrame;
+  }
+
+  // --- Find or create the Columns container ---
+  // Named "Columns" so it survives across runs. Column frames inside it are
+  // found/created by addColumn using the theme label as a stable key.
+  let columns: FrameNode | null = findChildByName(section, 'Columns');
+  if (!columns) {
+    columns = figma.createFrame();
+    columns.name = 'Columns';
+    section.appendChild(columns);
+  }
+  tagGeneratedNode(columns, 'columns:' + sectionTitle);
+  columns.layoutMode = 'HORIZONTAL';
+  columns.itemSpacing = BOARD_LAYOUT.columnsGap;
+  columns.primaryAxisSizingMode = 'AUTO';
+  columns.counterAxisSizingMode = 'AUTO';
+  columns.counterAxisAlignItems = 'MIN';
+  columns.fills = [];
+  ctx.applyClipBehavior(columns, []);
+
+  const requestedThemes: string[] = Array.isArray(options.themeNames)
+    ? options.themeNames.filter(function(theme: string, index: number, list: string[]) {
+      return typeof theme === 'string' &&
+        theme.trim().length > 0 &&
+        list.indexOf(theme) === index;
+    })
+    : [];
+  if (requestedThemes.length === 0) {
+    if (options.primary) requestedThemes.push('primary');
+    if (options.secondary) requestedThemes.push('secondary');
+  }
+  const expectedColumnNames: Record<string, boolean> = {};
+  const multiMode = isMultiModeEnabled();
+  if (multiMode) {
+    const activeTheme = requestedThemes[0] || 'primary';
+    expectedColumnNames['Theme Column'] = true;
+    const singleCol = await addColumn('Theme', activeTheme);
+    if (findChildIndexByName(columns, 'Theme Column') !== 0) {
+      columns.insertChild(0, singleCol);
+    }
+    setThemeMode(singleCol, activeTheme);
+  } else {
+    for (let ti = 0; ti < requestedThemes.length; ti++) {
+      const themeName = requestedThemes[ti];
+      const themeCol = await addColumn(formatThemeLabel(themeName), themeName);
+      const columnName = formatThemeLabel(themeName) + ' Column';
+      expectedColumnNames[columnName] = true;
+      if (findChildIndexByName(columns, columnName) !== ti) {
+        columns.insertChild(ti, themeCol);
+      }
+      setThemeMode(themeCol, themeName);
+    }
+  }
+  const existingColumns: SceneNode[] = columns.children ? Array.from(columns.children) : [];
+  const seenColumns: Record<string, boolean> = {};
+  for (let i = 0; i < existingColumns.length; i++) {
+    const col = existingColumns[i];
+    if (!expectedColumnNames[col.name] || seenColumns[col.name]) {
+      col.remove();
+    } else {
+      seenColumns[col.name] = true;
+    }
+  }
+  debug('UI section updated', { columns: columns.children.length });
+  return section;
+}
+
+// ====================================================================
+// Pre-flight data computation
+// ====================================================================
+
+export interface PreflightItem {
+  name: string;
+  status: 'new' | 'changed' | 'unchanged';
+  section: string;
+  sectionTitle: string;
+  /**
+   * Optional human-readable label. Used when `name` is a synthetic identifier
+   * (e.g. the design tokens toggle) that isn't suitable for direct display.
+   */
+  displayName?: string;
+}
+
+export function computePreflightData(tokenHash: string): PreflightItem[] {
+  let ds: PageNode | null = null;
+  if (figma.root && Array.isArray(figma.root.children)) {
+    for (let pi = 0; pi < figma.root.children.length; pi++) {
+      if (figma.root.children[pi].name === 'Design System') {
+        ds = figma.root.children[pi];
+        break;
+      }
+    }
+  }
+
+  const defsRaw = (COMPONENT_DEFS && COMPONENT_DEFS.components) ? COMPONENT_DEFS.components : [];
+  const result: PreflightItem[] = [];
+
+  for (let i = 0; i < defsRaw.length; i++) {
+    const def = normalizeForPreflight(defsRaw[i]);
+    if (!def || !def.stories || def.stories.length === 0) continue;
+
+    const section = inferComponentSection(def);
+    const defHash = hashDef(def);
+
+    let status: 'new' | 'changed' | 'unchanged' = 'new';
+    if (ds) {
+      const matchingBlocks = findComponentBlocksInPage(ds, def.name);
+      if (matchingBlocks.length > 0) {
+        let hasCurrentHash = false;
+        for (let bi = 0; bi < matchingBlocks.length; bi++) {
+          if (blockHashMatchesCurrent(getFrameHash(matchingBlocks[bi]), defHash, tokenHash, RENDER_ENGINE_VERSION)) {
+            hasCurrentHash = true;
+            break;
+          }
+        }
+        status = hasCurrentHash ? 'unchanged' : 'changed';
+      }
+    }
+
+    result.push({
+      name: def.name,
+      status: status,
+      section: section.key,
+      sectionTitle: section.title,
+    });
+  }
+
+  return result;
+}