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

package/src/design-system/icon-rendering.ts

@@ -0,0 +1,229 @@
+import { parseColor, resolveTextColorValue, type RGB } from '../tokens';
+import {
+  ICON_PATHS,
+  createIcon,
+  createIconFromSvg,
+  getVectorPaintUsage,
+  resizeSvgNodeTo,
+  resolveIconSizeFromClasses,
+  wrapIconNode,
+} from '../effects';
+import { getIconRegistryEntry } from '../components';
+import type { RenderContext } from './render-context';
+
+/**
+ * Icon-rendering layer for the design-system page builder. Sits between
+ * effects/icon-builder.ts (which creates raw VECTOR / SVG nodes) and
+ * ui-builder's renderJsxTree (which classifies a JSX element as an icon
+ * and asks for one).
+ *
+ * Two source paths:
+ * - **Mapped icons**: Tailwind class names like `<X />` map to one of the
+ *   plugin's hand-rolled `ICON_PATHS` SVGs (close, chevron-down, …).
+ * - **Registry icons**: scanner-extracted SVGs for arbitrary icon-library
+ *   imports (Lucide, Heroicons, Phosphor, Tabler, …) keyed by component
+ *   name.
+ *
+ * Both paths normalize size from class strings (`size-4`, `h-5 w-5`) and
+ * pad strokes so corners aren't clipped.
+ */
+
+function resolveContextTextColorValue(
+  context: RenderContext,
+  colorGroup: Record<string, string>,
+  theme: string
+): string | RGB | null {
+  return resolveTextColorValue(context.textColor, context.textColorToken, colorGroup, theme);
+}
+
+function parseInlineStyleColor(style: unknown): string | null {
+  if (!style) return null;
+  if (typeof style === 'object') {
+    const raw = (style as Record<string, unknown>).color;
+    if (typeof raw === 'string' && raw.trim() !== '') return raw.trim();
+    return null;
+  }
+  if (typeof style === 'string') {
+    const match = style.match(/(?:^|;)\s*color\s*:\s*([^;]+)/i);
+    if (match) return match[1].trim();
+  }
+  return null;
+}
+
+export function resolveIconForegroundColor(
+  context: RenderContext,
+  colorGroup: Record<string, string>,
+  theme: string,
+  props?: Record<string, unknown>
+): RGB {
+  // Inline `style={{ color: "..." }}` (common for react-icons / SiFigma etc.)
+  // takes precedence over class-inherited text color.
+  if (props) {
+    const inline = parseInlineStyleColor(props.style);
+    if (inline) return parseColor(inline);
+  }
+  const resolvedTextColor = resolveContextTextColorValue(context, colorGroup, theme);
+  if (resolvedTextColor) return parseColor(resolvedTextColor);
+  if (colorGroup.foreground) return parseColor(colorGroup.foreground);
+  return { r: 0.1, g: 0.1, b: 0.1 };
+}
+
+function wrapSvgIconWithSize(
+  icon: SceneNode,
+  width: number,
+  height: number,
+  name: string
+): FrameNode {
+  resizeSvgNodeTo(icon, width, height);
+  const usage = getVectorPaintUsage(icon);
+  const pad = usage.hasStrokes ? 1 : 0;
+  return wrapIconNode(icon, width, height, pad, name);
+}
+
+function wrapMappedIconWithSize(
+  icon: SceneNode,
+  iconKey: string,
+  width: number,
+  height: number,
+  name: string,
+  rotate: boolean
+): FrameNode {
+  resizeSvgNodeTo(icon, width, height);
+  const pad = ICON_PATHS[iconKey].stroke
+    ? Math.max(1, Math.ceil((ICON_PATHS[iconKey].strokeWidth || 1.5) / 2))
+    : 0;
+  const wrapped = wrapIconNode(icon, width, height, pad, name);
+  if (rotate) {
+    wrapped.rotation = 180;
+  }
+  return wrapped;
+}
+
+export function wrapSvgIcon(
+  icon: SceneNode,
+  classes: string[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  props: Record<string, any>,
+  name: string
+): FrameNode {
+  const normalizedProps: Record<string, string> = {};
+  const source = props || {};
+  const keys = Object.keys(source);
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const value = source[key];
+    if (value == null) continue;
+    normalizedProps[key] = String(value);
+  }
+  const size = resolveIconSizeFromClasses(classes, normalizedProps);
+  return wrapSvgIconWithSize(icon, size.width, size.height, name);
+}
+
+const ICON_KEY_ALIASES: Record<string, string> = {
+  x: 'close',
+  xicon: 'close',
+  closeicon: 'close',
+  menuicon: 'menu',
+  hambugericon: 'menu',
+  checkicon: 'check',
+  chevrondownicon: 'chevron-down',
+};
+
+function toIconKey(tagName: string): string | null {
+  const raw = String(tagName || '').trim();
+  if (!raw) return null;
+  const basename = raw.split('.').pop() || raw;
+  const hasNamespace = raw.includes('.');
+  const namespace = hasNamespace ? raw.slice(0, raw.lastIndexOf('.')) : '';
+  const basenameIsExplicitIcon = /(?:icon|svg)$/i.test(basename);
+  const namespaceLooksIconish = /(?:icon|icons|lucide|heroicons|phosphor|tabler)/i.test(namespace);
+  // Avoid collapsing non-icon primitives/components (e.g. DialogPrimitive.Close)
+  // into icon nodes just because their basename happens to match an icon alias.
+  if (hasNamespace && !basenameIsExplicitIcon && !namespaceLooksIconish) {
+    return null;
+  }
+  const compact = basename.replace(/[^a-zA-Z0-9]/g, '');
+  const kebab = compact
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+  if (ICON_PATHS[kebab]) return kebab;
+
+  const compactLower = compact.toLowerCase();
+  const alias = ICON_KEY_ALIASES[compactLower];
+  if (alias && ICON_PATHS[alias]) return alias;
+  return null;
+}
+
+function resolveRegistryIconSvg(tagName: string): string | null {
+  const raw = String(tagName || '').trim();
+  if (!raw) return null;
+
+  const candidates = new Set<string>();
+  candidates.add(raw);
+
+  const basename = raw.split('.').pop() || raw;
+  if (basename) candidates.add(basename);
+
+  if (basename.endsWith('Icon')) {
+    candidates.add(basename.slice(0, -4));
+  }
+
+  for (const candidate of candidates) {
+    const entry = getIconRegistryEntry(candidate);
+    if (entry && typeof entry.svg === 'string' && entry.svg.trim()) {
+      return entry.svg;
+    }
+  }
+
+  return null;
+}
+
+export function renderRegistryIcon(
+  tagName: string,
+  classes: string[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  props: Record<string, any>,
+  fgColor: RGB
+): FrameNode | null {
+  const svg = resolveRegistryIconSvg(tagName);
+  const icon = svg ? createIconFromSvg(svg, fgColor) : null;
+  if (!icon) return null;
+  const normalizedProps: Record<string, string> = {};
+  const source = props || {};
+  const keys = Object.keys(source);
+  for (let i = 0; i < keys.length; i++) {
+    const propKey = keys[i];
+    const value = source[propKey];
+    if (value == null) continue;
+    normalizedProps[propKey] = String(value);
+  }
+  const size = resolveIconSizeFromClasses(classes, normalizedProps);
+  return wrapSvgIconWithSize(icon, size.width, size.height, String(tagName || 'icon/svg'));
+}
+
+export function renderMappedIcon(
+  tagName: string,
+  classes: string[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  props: Record<string, any>,
+  fgColor: RGB,
+  rotateChevron: boolean
+): FrameNode | null {
+  const key = toIconKey(tagName);
+  if (!key) return null;
+  const icon = createIcon(key, fgColor);
+  if (!icon) return null;
+  const normalizedProps: Record<string, string> = {};
+  const source = props || {};
+  const keys = Object.keys(source);
+  for (let i = 0; i < keys.length; i++) {
+    const propKey = keys[i];
+    const value = source[propKey];
+    if (value == null) continue;
+    normalizedProps[propKey] = String(value);
+  }
+  const size = resolveIconSizeFromClasses(classes, normalizedProps);
+  const shouldRotate = rotateChevron && key === 'chevron-down';
+  return wrapMappedIconWithSize(icon, key, size.width, size.height, 'icon/' + key, shouldRotate);
+}

package/src/design-system/index.ts

@@ -0,0 +1,13 @@
+export * from './design-system';
+export * from './ui-builder';
+export * from './story-builder-context';
+export * from './story-layout';
+export * from './preview-builder';
+export * from './render-context';
+export * from './generated-node';
+
+// story-builder has `createUIComponents` / `pruneGeneratedComponentLibrary`
+// that ui-builder re-exports as wrappers; the public API comes from
+// ui-builder. Only story-builder's `computePreflightData` is consumed
+// externally, so re-export that one explicitly.
+export { computePreflightData } from './story-builder';

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

@@ -0,0 +1,307 @@
+import { applyTailwindStylesToFrame, splitClassName } from '../tailwind';
+import {
+  createCompoundComponent,
+  tryCreateNonCvaComponentInstance as tryCreateNonCvaComponentInstanceShared,
+  type ComponentDef,
+  type ComponentInstance,
+  type ComponentStory,
+  type CvaAnalysis,
+  type LayoutInfo,
+} from '../components';
+import { createTextNode } from '../text';
+import {
+  componentInstanceBackend,
+  createCVAStoryInstance,
+  createStateStoryInstance,
+  createSimpleStoryInstance,
+} from './story-instance';
+import { createSimpleStoryFrame } from './story-frames';
+import { normalizeComponentName } from './story-tree-search';
+import { isTruthyStateProp } from './state-master';
+import { setGeneratedFallbackReason } from './generated-node';
+import { getNonCvaSymbolFallbackReason } from './symbol-fallback';
+import { parseRenderPropToSyntheticInstance } from './render-prop-parser';
+import type { StoryBuilderContext, StoryRenderContext } from './story-builder-context';
+
+/**
+ * Renders the JSX children of a trigger component (e.g. `<DialogTrigger>` /
+ * `<SheetTrigger>`) directly — the trigger itself is invisible at runtime but
+ * its visible children (the button, link, etc.) are what the user sees on the
+ * page. Used inside `renderGuardedPortalStoryInstances`.
+ */
+function renderGuardedTriggerJsxChildren(
+  instance: ComponentInstance,
+  theme: string,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  ctx: StoryBuilderContext
+): SceneNode[] {
+  const props = instance && instance.props ? instance.props : {};
+  const jsxChildren = Array.isArray(props.__jsxChildren) ? props.__jsxChildren : [];
+  if (jsxChildren.length === 0) return [];
+
+  const nodes: SceneNode[] = [];
+  const triggerContext: StoryRenderContext = { parentLayout: 'HORIZONTAL' };
+  for (let i = 0; i < jsxChildren.length; i++) {
+    const child = jsxChildren[i];
+    if (!child || typeof child !== 'object') continue;
+    const rendered = ctx.renderJsxTree(child, colorGroup, radiusGroup, theme, 0, triggerContext);
+    if (rendered) {
+      nodes.push(rendered);
+    }
+  }
+  return nodes;
+}
+
+/**
+ * Dispatches a resolved ComponentInstance to the right creator based on its
+ * analysis.type:
+ *  - `cva` → variant-matrix instance via createCVAStoryInstance
+ *  - `state` → state-matrix instance via createStateStoryInstance
+ *  - `simple` → single instance via createSimpleStoryInstance
+ *  - `compound` → symbol-instance attempt, falling back to compound frame
+ *  - anything else → returns false (caller renders an opaque fallback frame)
+ *
+ * Returns `true` when the layout received an appended child, `false` when the
+ * caller should fall through to its own fallback rendering.
+ */
+export function appendResolvedInstance(
+  layout: LayoutInfo,
+  analysis: CvaAnalysis,
+  instance: ComponentInstance,
+  story: ComponentStory,
+  theme: string,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  ctx: StoryBuilderContext
+): boolean {
+  if (!analysis) return false;
+  if (analysis.type === 'cva') {
+    layout.appendChild(createCVAStoryInstance(analysis, instance, theme, ctx));
+    return true;
+  }
+  if (analysis.type === 'state') {
+    layout.appendChild(createStateStoryInstance(analysis, instance, theme, ctx, story));
+    return true;
+  }
+  if (analysis.type === 'simple') {
+    layout.appendChild(createSimpleStoryInstance(analysis, instance, theme, ctx, story));
+    return true;
+  }
+  if (analysis.type === 'compound') {
+    const symbolInstance = tryCreateNonCvaComponentInstanceShared(analysis, instance, theme, ctx, componentInstanceBackend, story);
+    if (symbolInstance) {
+      layout.appendChild(symbolInstance);
+      return true;
+    }
+    const comp = createCompoundComponent(layout, analysis, theme);
+    if (comp) {
+      setGeneratedFallbackReason(comp, getNonCvaSymbolFallbackReason(analysis, instance));
+    }
+    const extra = splitClassName(instance.props && instance.props.className);
+    if (comp && comp.type === 'FRAME' && extra.length > 0) {
+      applyTailwindStylesToFrame(comp, extra, colorGroup, radiusGroup, theme);
+    }
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Renders portal-trigger components (Sheet, Dialog, Drawer, Popover, …) as
+ * "trigger row + popup content stack". The plugin can't actually open a Radix
+ * portal so it composes the two halves of the story manually:
+ *
+ *  - `<XTrigger>`: rendered inline at the top of the Story Layout. Multiple
+ *    triggers get a horizontal Trigger Row container; a single trigger lands
+ *    directly. Trigger JSX children are rendered via renderJsxTree;
+ *    `render="…"` strings are parsed via parseRenderPropToSyntheticInstance.
+ *  - `<XContent>` / `<XPopup>`: rendered below the trigger AS A FRAME (not a
+ *    symbol instance) so popup text stays visible. Skipped when the story
+ *    doesn't carry an `open` / `defaultOpen` / `visible` / `defaultVisible`
+ *    truthy prop on the root instance.
+ *  - `<XProvider>` / `<XPositioner>`: skipped (zero visual contribution).
+ *  - The root instance itself: skipped (its visual content lives in the trigger
+ *    + content slots, not on the root).
+ *
+ * Returns the number of child nodes appended to `layout`.
+ */
+export function renderGuardedPortalStoryInstances(
+  layout: LayoutInfo,
+  def: ComponentDef,
+  story: ComponentStory,
+  theme: string,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  ctx: StoryBuilderContext
+): number {
+  const instances = (story && Array.isArray(story.instances)) ? story.instances : [];
+  if (instances.length === 0) return 0;
+
+  const defKey = normalizeComponentName(def && def.name ? def.name : '');
+  if (!defKey) return 0;
+
+  let rootIsOpen = false;
+  for (let i = 0; i < instances.length; i++) {
+    const instance = instances[i];
+    if (!instance || normalizeComponentName(instance.componentName) !== defKey) continue;
+    const props = instance.props || {};
+    if (
+      isTruthyStateProp(props.open) ||
+      isTruthyStateProp(props.defaultOpen) ||
+      isTruthyStateProp(props.visible) ||
+      isTruthyStateProp(props.defaultVisible)
+    ) {
+      rootIsOpen = true;
+      break;
+    }
+  }
+
+  function buildResolvedNode(analysis: CvaAnalysis, instance: ComponentInstance): SceneNode | null {
+    if (!analysis) return null;
+    if (analysis.type === 'cva') return createCVAStoryInstance(analysis, instance, theme, ctx);
+    if (analysis.type === 'state') return createStateStoryInstance(analysis, instance, theme, ctx, story);
+    if (analysis.type === 'simple') return createSimpleStoryInstance(analysis, instance, theme, ctx, story);
+    if (analysis.type === 'compound') {
+      const symbolInstance = tryCreateNonCvaComponentInstanceShared(analysis, instance, theme, ctx, componentInstanceBackend, story);
+      if (symbolInstance) return symbolInstance;
+      const holder = figma.createFrame();
+      holder.name = analysis.name;
+      holder.layoutMode = 'VERTICAL';
+      holder.primaryAxisSizingMode = 'AUTO';
+      holder.counterAxisSizingMode = 'AUTO';
+      holder.fills = [];
+      const comp = createCompoundComponent(holder, analysis, theme);
+      if (comp) {
+        setGeneratedFallbackReason(comp, getNonCvaSymbolFallbackReason(analysis, instance));
+        const extra = splitClassName(instance.props && instance.props.className);
+        if (comp.type === 'FRAME' && extra.length > 0) {
+          applyTailwindStylesToFrame(comp, extra, colorGroup, radiusGroup, theme);
+        }
+        return comp;
+      }
+      holder.remove();
+    }
+    return null;
+  }
+
+  const triggerNodes: SceneNode[] = [];
+  const contentNodes: SceneNode[] = [];
+  for (let i = 0; i < instances.length; i++) {
+    const instance = instances[i];
+    if (!instance || !instance.componentName) continue;
+    const instanceKey = normalizeComponentName(instance.componentName);
+
+    // Root container instance for guarded/portal components usually doesn't carry
+    // renderable content by itself and creates empty placeholder cards in Figma.
+    if (instanceKey === defKey) continue;
+
+    if (instanceKey === defKey + 'provider' || instanceKey === defKey + 'positioner') {
+      continue;
+    }
+
+    if (instanceKey === defKey + 'trigger') {
+      const triggerNodesFromJsx = renderGuardedTriggerJsxChildren(instance, theme, colorGroup, radiusGroup, ctx);
+      if (triggerNodesFromJsx.length > 0) {
+        for (let i = 0; i < triggerNodesFromJsx.length; i++) {
+          triggerNodes.push(triggerNodesFromJsx[i]);
+        }
+        continue;
+      }
+      const synthetic = parseRenderPropToSyntheticInstance(instance.props && instance.props.render);
+      if (!synthetic) continue;
+      const triggerDef = ctx.getComponentDefByName(synthetic.componentName);
+      if (!triggerDef) continue;
+      const triggerAnalysis = ctx.normalizeComponentDef(triggerDef);
+      const triggerNode = buildResolvedNode(triggerAnalysis, synthetic);
+      if (triggerNode) triggerNodes.push(triggerNode);
+      continue;
+    }
+
+    if (instanceKey === defKey + 'content' || instanceKey === defKey + 'popup') {
+      if (!rootIsOpen) continue;
+      const popupInstance = {
+        props: instance.props || {},
+        children: instance.children || (instance.props && instance.props.children) || '',
+      };
+      // Force frame rendering here (not symbol instance) so popup text is always visible.
+      contentNodes.push(createSimpleStoryFrame(def, popupInstance, theme, ctx, 'portal_content_preview'));
+      continue;
+    }
+  }
+
+  let added = 0;
+  if (triggerNodes.length > 1) {
+    const triggerRow = figma.createFrame();
+    triggerRow.name = 'Trigger Row';
+    triggerRow.layoutMode = 'HORIZONTAL';
+    triggerRow.primaryAxisSizingMode = 'AUTO';
+    triggerRow.counterAxisSizingMode = 'AUTO';
+    triggerRow.counterAxisAlignItems = 'CENTER';
+    triggerRow.itemSpacing = 12;
+    triggerRow.fills = [];
+    ctx.applyClipBehavior(triggerRow, ['flex', 'items-center', 'gap-3']);
+    for (const node of triggerNodes) triggerRow.appendChild(node);
+    layout.appendChild(triggerRow);
+    added += triggerNodes.length;
+  } else if (triggerNodes.length === 1) {
+    layout.appendChild(triggerNodes[0]);
+    added += 1;
+  }
+
+  for (const node of contentNodes) {
+    layout.appendChild(node);
+    added += 1;
+  }
+
+  return added;
+}
+
+/**
+ * Generic instance-rendering path used when a story does NOT need portal
+ * guarding. Walks story.instances, resolves each via the scanner's component
+ * defs, and dispatches to the right creator via appendResolvedInstance.
+ * Unresolved components fall back to a labelled empty frame so the story
+ * still surfaces what was expected.
+ */
+export function renderStoryInstances(
+  layout: LayoutInfo,
+  story: ComponentStory,
+  theme: string,
+  colorGroup: Record<string, string>,
+  radiusGroup: Record<string, string> | null,
+  ctx: StoryBuilderContext
+): number {
+  let added = 0;
+  for (const instance of story.instances || []) {
+    if (!instance || !instance.componentName) continue;
+    const compDef = ctx.getComponentDefByName(instance.componentName);
+    if (compDef) {
+      const analysis = ctx.normalizeComponentDef(compDef);
+      if (appendResolvedInstance(layout, analysis, instance, story, theme, colorGroup, radiusGroup, ctx)) {
+        added++;
+        continue;
+      }
+    }
+
+    const fallback = figma.createFrame();
+    fallback.name = instance.componentName || 'Component';
+    fallback.layoutMode = 'VERTICAL';
+    fallback.primaryAxisSizingMode = 'AUTO';
+    fallback.counterAxisSizingMode = 'AUTO';
+    fallback.fills = [];
+    const extra = splitClassName(instance.props && instance.props.className);
+    ctx.applyClipBehavior(fallback, extra);
+    if (extra.length > 0) {
+      applyTailwindStylesToFrame(fallback, extra, colorGroup, radiusGroup, theme);
+    }
+    const label = instance.children || instance.props?.children || instance.componentName;
+    if (label) {
+      fallback.appendChild(createTextNode(String(label), { fontSize: 12, opacity: 0.7 }));
+    }
+    setGeneratedFallbackReason(fallback, 'component_definition_unresolved');
+    layout.appendChild(fallback);
+    added++;
+  }
+  return added;
+}

package/src/design-system/master-shared.ts

@@ -0,0 +1,133 @@
+import { COMPONENT_LIBRARY_ROOT_NAME } from '../components';
+import { findChildByName } from '../cache';
+import { tagGeneratedNode } from './generated-node';
+import { removeDuplicateChildrenByName } from './frame-utils';
+
+/**
+ * Shared infrastructure used by both the CVA-master and state-master
+ * extraction paths in the design-system page builder.
+ *
+ * - `ENABLE_SYMBOL_MASTERS` is the global feature flag for symbol-based
+ *   rendering (component sets per CVA / per state). When false, the
+ *   plugin renders raw frames instead.
+ * - `toFigmaVariantPropertyName` / `toFigmaVariantPropertyValue` are the
+ *   case-normalizers Figma's variant API expects.
+ * - The `ensureComponentLibraryRoot` / `ensureThemeComponentLibrary`
+ *   helpers create or reuse the hidden frames on the current page that
+ *   hold the generated symbol masters.
+ * - `shouldCreateNonCvaMaster` answers whether a non-CVA, non-state def
+ *   should get a symbol master.
+ */
+
+export const ENABLE_SYMBOL_MASTERS = true;
+
+export function toFigmaVariantPropertyName(rawKey: string): string {
+  const key = String(rawKey || '').trim();
+  if (!key) return 'Variant';
+  return key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+export function toFigmaVariantPropertyValue(rawValue: unknown): string {
+  const value = String(rawValue == null ? '' : rawValue).trim();
+  if (!value) return 'Default';
+  const lowered = value.toLowerCase();
+  if (lowered === 'true') return 'True';
+  if (lowered === 'false') return 'False';
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findExistingComponentLibraryRoot(): any | null {
+  const pages = figma.root && Array.isArray(figma.root.children) ? figma.root.children : [];
+  for (let i = 0; i < pages.length; i++) {
+    const page = pages[i];
+    if (!page || page.type !== 'PAGE' || !Array.isArray(page.children)) {
+      continue;
+    }
+    const root = findChildByName(page, COMPONENT_LIBRARY_ROOT_NAME);
+    if (root && root.type === 'FRAME') return root;
+  }
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ensureComponentLibraryRoot(): any | null {
+  // Prefer an existing hidden library root regardless of page name.
+  // Design systems may be generated on arbitrary page names (e.g. "Page 3"),
+  // so requiring a page named "Design System" breaks symbol instancing.
+  let root = findExistingComponentLibraryRoot();
+  if (root && root.type === 'FRAME') {
+    const parent = root.parent;
+    if (parent && Array.isArray(parent.children)) {
+      removeDuplicateChildrenByName(parent, COMPONENT_LIBRARY_ROOT_NAME, 'FRAME');
+      root = findChildByName(parent, COMPONENT_LIBRARY_ROOT_NAME) || root;
+    }
+  }
+
+  let page = figma.currentPage;
+  if ((!root || root.type !== 'FRAME') && (!page || !Array.isArray(page.children))) {
+    const pages = figma.root && Array.isArray(figma.root.children) ? figma.root.children : [];
+    for (let i = 0; i < pages.length; i++) {
+      const candidate = pages[i];
+      if (candidate && candidate.type === 'PAGE' && Array.isArray(candidate.children)) {
+        page = candidate;
+        break;
+      }
+    }
+  }
+  if (!root && (!page || !Array.isArray(page.children))) return null;
+
+  if (!root && page) {
+    removeDuplicateChildrenByName(page, COMPONENT_LIBRARY_ROOT_NAME, 'FRAME');
+    root = findChildByName(page, COMPONENT_LIBRARY_ROOT_NAME);
+  }
+  if (!root) {
+    root = figma.createFrame();
+    root.name = COMPONENT_LIBRARY_ROOT_NAME;
+    root.layoutMode = 'VERTICAL';
+    root.primaryAxisSizingMode = 'AUTO';
+    root.counterAxisSizingMode = 'AUTO';
+    root.itemSpacing = 32;
+    root.fills = [];
+    root.x = -20000;
+    root.y = -20000;
+    root.visible = false;
+    page.appendChild(root);
+  }
+  tagGeneratedNode(root, 'component-library-root');
+
+  return root;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function ensureThemeComponentLibrary(theme: string): any | null {
+  if (!ENABLE_SYMBOL_MASTERS) return null;
+  const root = ensureComponentLibraryRoot();
+  if (!root) return null;
+
+  const themeName = String(theme || 'primary');
+  const frameName = themeName + ' Masters';
+  removeDuplicateChildrenByName(root, frameName, 'FRAME');
+  let themeFrame = findChildByName(root, frameName);
+  if (!themeFrame) {
+    themeFrame = figma.createFrame();
+    themeFrame.name = frameName;
+    themeFrame.layoutMode = 'VERTICAL';
+    themeFrame.primaryAxisSizingMode = 'AUTO';
+    themeFrame.counterAxisSizingMode = 'AUTO';
+    themeFrame.itemSpacing = 16;
+    themeFrame.fills = [];
+    themeFrame.visible = false;
+    root.appendChild(themeFrame);
+  }
+  tagGeneratedNode(themeFrame, 'component-library-theme:' + themeName);
+
+  return themeFrame;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function shouldCreateNonCvaMaster(def: any): boolean {
+  if (!def || def.type === 'cva' || def.type === 'state') return false;
+  if (def.symbolCandidate === false) return false;
+  return true;
+}