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

package/src/{component-gen.ts → components/component-gen.ts}

@@ -1,13 +1,13 @@
-import { TOKENS, COMPONENT_DEFS, getThemeColors, getThemeRadius } from './tokens';
-import { parseColor, debug } from './colors';
+import { TOKENS, COMPONENT_DEFS, getThemeColors, getThemeRadius } from '../tokens';
+import { parseColor, debug } from '../tokens';
 import { getComponentDef } from './component-defs';
-import { tailwindClassesToStyle, applyTailwindStylesToFrame } from './tailwind';
-import { bindColorVariable, pxFromSizeToken } from './variables';
-import { createTextNode } from './text-builder';
-import { extractStatesFromClasses, mergeStatesWithDefinition, type StateInfo } from './state-analyzer';
-import { extractArbitraryValue, parseLength } from './utility-resolver';
-
-type RingInfo = { width: number; color: { r: number; g: number; b: number; a?: number } };
+import type { ComponentAnalysis } from '../../scanner/types';
+import type { ComponentDef } from './scanner-types';
+import { tailwindClassesToStyle, applyTailwindStylesToFrame } from '../tailwind';
+import { bindColorVariable, pxFromSizeToken } from '../tokens';
+import { createTextNode } from '../text';
+import { extractStatesFromClasses, mergeStatesWithDefinition, type StateInfo } from '../tailwind';
+import { getRingInfoFromClasses, markRingNode, applyRingIfPossible } from '../layout';
 
 function getStateEntry(states: StateInfo[], name: string): StateInfo | null {
   for (let i = 0; i < states.length; i++) {
@@ -35,100 +35,7 @@ function buildStateClasses(states: StateInfo[], name: string): string[] {
   return baseClasses.concat(entry.classes);
 }
 
-function parseRingWidth(utility: string): number | null {
-  if (utility === 'ring') return 3;
-  if (!utility.startsWith('ring-')) return null;
-  const token = utility.substring(5);
-  if (token === 'inset' || token.startsWith('offset-')) return null;
-  if (token.startsWith('[')) {
-    const arbitrary = extractArbitraryValue(utility);
-    if (!arbitrary) return null;
-    return parseLength(arbitrary);
-  }
-  const num = parseFloat(token);
-  if (!Number.isNaN(num) && String(num) === token) return num;
-  return null;
-}
-
-function parseRingColor(utility: string, colorGroup: Record<string, string>): { r: number; g: number; b: number; a?: number } | null {
-  if (!utility.startsWith('ring-')) return null;
-  const token = utility.substring(5);
-  if (token === 'inset' || token.startsWith('offset-')) return null;
-  if (token.startsWith('[')) return null;
-  const num = parseFloat(token);
-  if (!Number.isNaN(num) && String(num) === token) return null;
-  const resolved = colorGroup[token];
-  if (!resolved) return null;
-  return parseColor(resolved);
-}
-
-function getRingInfoFromClasses(classes: string[], colorGroup: Record<string, string>): RingInfo | null {
-  let width: number | null = null;
-  let color: { r: number; g: number; b: number; a?: number } | null = null;
-
-  for (let i = 0; i < classes.length; i++) {
-    const cls = classes[i];
-    const nextWidth = parseRingWidth(cls);
-    if (nextWidth != null) width = nextWidth;
-    const nextColor = parseRingColor(cls, colorGroup);
-    if (nextColor) color = nextColor;
-  }
-
-  if (width == null && color == null) return null;
-  if (width == null) width = 3;
-  if (!color) {
-    const fallback = colorGroup.ring || colorGroup.primary;
-    if (!fallback) return null;
-    color = parseColor(fallback);
-  }
-  if (!width || width <= 0) return null;
-  return { width, color };
-}
-
-function hasVisibleFill(node: FrameNode): boolean {
-  const fills = (node as any).fills;
-  if (!Array.isArray(fills)) return false;
-  for (let i = 0; i < fills.length; i++) {
-    const fill = fills[i];
-    if (!fill || fill.visible === false) continue;
-    if (fill.opacity != null && fill.opacity <= 0) continue;
-    return true;
-  }
-  return false;
-}
-
-function applyRingEffect(node: FrameNode, classes: string[], colorGroup: Record<string, string>): void {
-  const ring = getRingInfoFromClasses(classes, colorGroup);
-  if (!ring) return;
-  const useSpread = (node as any).clipsContent === true && hasVisibleFill(node);
-  if (!useSpread) {
-    const strokeWeight = typeof node.strokeWeight === 'number' ? node.strokeWeight : 0;
-    node.strokes = [{
-      type: 'SOLID',
-      color: { r: ring.color.r, g: ring.color.g, b: ring.color.b },
-      opacity: ring.color.a == null ? 1 : ring.color.a,
-    }];
-    node.strokeWeight = Math.max(strokeWeight, ring.width);
-    return;
-  }
-  const effect: DropShadowEffect = {
-    type: 'DROP_SHADOW',
-    color: { r: ring.color.r, g: ring.color.g, b: ring.color.b, a: ring.color.a == null ? 1 : ring.color.a },
-    offset: { x: 0, y: 0 },
-    radius: 0,
-    spread: ring.width,
-    visible: true,
-    blendMode: 'NORMAL'
-  };
-  const effects: Effect[] = [];
-  if (node.effects && node.effects.length > 0) {
-    for (let i = 0; i < node.effects.length; i++) effects.push(node.effects[i]);
-  }
-  effects.push(effect);
-  node.effects = effects;
-}
-
-export function createCVAComponentSet(parent: any, def: any, theme: string): any {
+export function createCVAComponentSet(parent: FrameNode | PageNode, def: ComponentDef, theme: string): SceneNode | null {
   const colorGroup = getThemeColors(TOKENS, theme);
   const radiusGroup = getThemeRadius(TOKENS, theme);
 
@@ -210,7 +117,13 @@ export function createCVAComponentSet(parent: any, def: any, theme: string): any
       // Apply background - try variable binding first, fall back to raw color
       if (style.bg) {
         const bgBound = style.bgToken && bindColorVariable(comp, style.bgToken, 'fill', theme);
-        if (!bgBound) {
+        if (bgBound) {
+          if (style.bgOpacity != null && Array.isArray(comp.fills) && comp.fills.length > 0) {
+            const nextFills = JSON.parse(JSON.stringify(comp.fills));
+            nextFills[0].opacity = style.bgOpacity;
+            comp.fills = nextFills;
+          }
+        } else {
           const bg = parseColor(style.bg);
           const bgOpacity = style.bgOpacity != null ? style.bgOpacity : (bg.a == null ? 1 : bg.a);
           comp.fills = [{ type: 'SOLID', color: { r: bg.r, g: bg.g, b: bg.b }, opacity: bgOpacity }];
@@ -242,8 +155,14 @@ export function createCVAComponentSet(parent: any, def: any, theme: string): any
       }
 
       comp.appendChild(text);
-      applyRingEffect(comp, stateClasses, colorGroup);
+      const ringInfo = getRingInfoFromClasses(stateClasses, colorGroup);
+      if (ringInfo) markRingNode(comp, ringInfo);
       stateRow.appendChild(comp);
+      // Comp's children are in place and it's now in the parent's auto-layout
+      // — apply ring (no-op if not marked). `applyRingIfPossible` locks the
+      // comp's sizing modes during the overlay append so inflation is
+      // impossible.
+      applyRingIfPossible(comp, stateRow);
     }
 
     variantSection.appendChild(stateRow);
@@ -254,7 +173,7 @@ export function createCVAComponentSet(parent: any, def: any, theme: string): any
   return container;
 }
 
-export function createStateComponentSet(parent: any, def: any, theme: string): any {
+export function createStateComponentSet(parent: FrameNode | PageNode, def: ComponentDef, theme: string): SceneNode | null {
   const colorGroup = getThemeColors(TOKENS, theme);
   const radiusGroup = getThemeRadius(TOKENS, theme);
 
@@ -304,7 +223,13 @@ export function createStateComponentSet(parent: any, def: any, theme: string): a
 
     if (style.bg) {
       const bgBound = style.bgToken && bindColorVariable(comp, style.bgToken, 'fill', theme);
-      if (!bgBound) {
+      if (bgBound) {
+        if (style.bgOpacity != null && Array.isArray(comp.fills) && comp.fills.length > 0) {
+          const nextFills = JSON.parse(JSON.stringify(comp.fills));
+          nextFills[0].opacity = style.bgOpacity;
+          comp.fills = nextFills;
+        }
+      } else {
         const bg = parseColor(style.bg);
         const bgOpacity = style.bgOpacity != null ? style.bgOpacity : (bg.a == null ? 1 : bg.a);
         comp.fills = [{ type: 'SOLID', color: { r: bg.r, g: bg.g, b: bg.b }, opacity: bgOpacity }];
@@ -349,9 +274,11 @@ export function createStateComponentSet(parent: any, def: any, theme: string): a
       fill: { r: placeholderColor.r, g: placeholderColor.g, b: placeholderColor.b }
     });
     comp.appendChild(placeholder);
-    applyRingEffect(comp, stateClasses, colorGroup);
+    const ringInfo = getRingInfoFromClasses(stateClasses, colorGroup);
+    if (ringInfo) markRingNode(comp, ringInfo);
 
     stateRow.appendChild(comp);
+    applyRingIfPossible(comp, stateRow);
   }
 
   container.appendChild(stateRow);
@@ -359,7 +286,7 @@ export function createStateComponentSet(parent: any, def: any, theme: string): a
   return container;
 }
 
-export function createCompoundComponent(parent: any, def: any, theme: string): any {
+export function createCompoundComponent(parent: FrameNode | PageNode, def: ComponentDef, theme: string): SceneNode | null {
   const colorGroup = getThemeColors(TOKENS, theme);
   const radiusGroup = getThemeRadius(TOKENS, theme);
 
@@ -372,7 +299,7 @@ export function createCompoundComponent(parent: any, def: any, theme: string): a
   container.strokes = [];
 
   // Find the main container sub-component
-  let mainSub: any = null;
+  let mainSub: ComponentDef = null;
   const subComponents = def.subComponents || [];
   for (let i = 0; i < subComponents.length; i++) {
     if (subComponents[i].slot === 'container' || subComponents[i].name === def.name) {
@@ -391,7 +318,7 @@ export function createCompoundComponent(parent: any, def: any, theme: string): a
   container.primaryAxisSizingMode = 'AUTO';
 
   // Helper to find a sub-component by slot
-  function findSub(slot: string): any {
+  function findSub(slot: string): ComponentDef {
     for (let j = 0; j < subComponents.length; j++) {
       if (subComponents[j].slot === slot) return subComponents[j];
     }
@@ -491,7 +418,7 @@ export function createCompoundComponent(parent: any, def: any, theme: string): a
   return container;
 }
 
-export function createSimpleComponent(parent: any, def: any, theme: string): any {
+export function createSimpleComponent(parent: FrameNode | PageNode, def: ComponentDef, theme: string): SceneNode | null {
   const colorGroup = getThemeColors(TOKENS, theme);
   const radiusGroup = getThemeRadius(TOKENS, theme);
 
@@ -512,7 +439,7 @@ export function createSimpleComponent(parent: any, def: any, theme: string): any
   return frame;
 }
 
-export function createComponentFromDef(parent: any, componentName: string, theme: string, options?: any): any {
+export function createComponentFromDef(parent: FrameNode | PageNode, componentName: string, theme: string, _options?: { types?: string[]; exclude?: string[] }): SceneNode | null {
   const def = getComponentDef(componentName);
   if (!def) {
     debug('Component not found in COMPONENT_DEFS:', componentName);
@@ -531,18 +458,18 @@ export function createComponentFromDef(parent: any, componentName: string, theme
     case 'simple':
       return createSimpleComponent(parent, def, theme);
     default:
-      debug('Unknown component type:', def.type);
+      debug('Unknown component type:', (def as ComponentAnalysis).type);
       return null;
   }
 }
 
-export function createAllComponentsFromDefs(parent: any, theme: string, options?: any): any[] {
+export function createAllComponentsFromDefs(parent: FrameNode | PageNode, theme: string, options?: { types?: string[]; exclude?: string[] }): SceneNode[] {
   options = options || {};
   const allowedTypes = options.types || ['cva', 'compound', 'state', 'simple'];
   const excludeNames = options.exclude || [];
 
   const components = COMPONENT_DEFS && COMPONENT_DEFS.components ? COMPONENT_DEFS.components : [];
-  const created: any[] = [];
+  const created: SceneNode[] = [];
 
   for (let i = 0; i < components.length; i++) {
     const def = components[i];

package/src/components/component-instance.ts

@@ -0,0 +1,386 @@
+import type { BackendCtx, ComponentDef, ComponentInstance, ComponentStory } from './scanner-types';
+
+/**
+ * Whether a CVA instance carries non-text JSX children that the symbol-instance
+ * path can't honour. Figma's component-property API can override TEXT and
+ * boolean/instance-swap properties on an instance — but it can't swap arbitrary
+ * SVG vectors. So when the consumer writes
+ * `<Toggle><AlignLeft /></Toggle>` inside a `<ToggleGroup>`, the Toggle master
+ * (built from Toggle's own stories) has a fixed icon, and every cloned instance
+ * inherits it. Result: all 3 ToggleGroup items render the same icon.
+ *
+ * The plugin's symmetric guard at the STORY root (`shouldUseInstance` in
+ * story-render-strategy.ts) already falls back to JSX-tree rendering when the
+ * root instance has `__jsxChildren`. This is the parallel guard for NESTED
+ * CVA instances inside a JSX tree (e.g. ToggleGroup items, icon-bearing
+ * Buttons inside another component's story). Returning null causes the JSX-
+ * tree renderer to build a frame for the instance instead, with its own
+ * per-instance children preserved.
+ *
+ * Text-only `__jsxChildren` (e.g. `<Button>Click me</Button>`) is NOT a
+ * reason to fall back — the text-override path handles it correctly. We
+ * only fall back when there's at least one element-type child.
+ */
+export function cvaInstanceHasOverridingJsxChildren(props: { __jsxChildren?: unknown } | null | undefined): boolean {
+  if (!props) return false;
+  const children = props.__jsxChildren;
+  if (!Array.isArray(children)) return false;
+  for (let i = 0; i < children.length; i++) {
+    const c = children[i];
+    if (c && typeof c === 'object' && (c as { type?: string }).type === 'element') return true;
+  }
+  return false;
+}
+
+/**
+ * State props that, when truthy on a CVA instance, require frame-render
+ * fall-back instead of a symbol-instance reuse. The reason: Figma's
+ * component instance API can't per-instance-activate data-attribute CSS
+ * variants. So even if the icon matches the master, an instance with
+ * `defaultPressed=true` wouldn't get the master's pressed styling unless
+ * the master itself was built from a pressed story — which is non-
+ * deterministic and brittle. Frame rendering lets the variant engine
+ * activate `data-[pressed]:*` / `data-[checked]:*` per-instance correctly.
+ *
+ * The set mirrors DATA_ATTR_PROP_ALIASES in node-variants.ts. Only the
+ * "user explicitly wants this state" props (defaultX / X) are included —
+ * not the `aria-*` mirrors, which are accessibility metadata and don't
+ * by themselves indicate a visual state requested by the consumer.
+ */
+const STATE_OVERRIDING_PROP_NAMES = [
+  'defaultPressed',
+  'pressed',
+  'defaultChecked',
+  'checked',
+  'disabled',
+  'defaultOpen',
+  'open',
+  'selected',
+] as const;
+
+function isStateTruthy(value: unknown): boolean {
+  if (value === true) return true;
+  if (typeof value === 'string') {
+    const lower = value.trim().toLowerCase();
+    return lower === 'true' || lower === 'on' || lower === '';
+  }
+  return false;
+}
+
+/**
+ * Whether a CVA instance carries any truthy state-conveying prop that
+ * the master-instance path can't honour. See STATE_OVERRIDING_PROP_NAMES.
+ *
+ * `disabled=false` etc. return false (the prop is set but to a falsy
+ * value, which doesn't change the visual). Only truthy values trigger
+ * fall-back.
+ */
+export function cvaInstanceHasOverridingState(
+  props: Record<string, unknown> | null | undefined
+): boolean {
+  if (!props) return false;
+  for (let i = 0; i < STATE_OVERRIDING_PROP_NAMES.length; i++) {
+    if (isStateTruthy(props[STATE_OVERRIDING_PROP_NAMES[i]])) return true;
+  }
+  return false;
+}
+
+/**
+ * Extract the tagName of the first JSX-element child of an instance.
+ * Used by the smart fall-back in `tryCreateCvaComponentInstance` to decide
+ * whether the instance's icon matches the master's recorded icon.
+ *
+ * Returns null when there's no element child (text-only or empty).
+ */
+export function getFirstElementJsxChildTagName(jsxChildren: unknown): string | null {
+  if (!Array.isArray(jsxChildren)) return null;
+  for (let i = 0; i < jsxChildren.length; i++) {
+    const c = jsxChildren[i];
+    if (c && typeof c === 'object' && (c as { type?: string }).type === 'element') {
+      const tag = (c as { tagName?: string }).tagName;
+      if (typeof tag === 'string' && tag.length > 0) return tag;
+    }
+  }
+  return null;
+}
+
+/**
+ * The plugin-data key under which `cva-master` records the icon name a
+ * CVA variant master was built with. `tryCreateCvaComponentInstance` reads
+ * it to decide whether an instance with element children can safely reuse
+ * the master (icons match) or must fall back to frame rendering
+ * (icons differ).
+ */
+export const MASTER_ICON_NAME_KEY = 'inkbridge:master-icon-name';
+
+function copyVariantFillsToInstance(componentSet: SceneNode | null, instanceNode: InstanceNode | null, properties: Record<string, string>): void {
+  if (!componentSet || !('children' in componentSet) || !Array.isArray(componentSet.children)) return;
+  if (!instanceNode) return;
+  const keys = Object.keys(properties);
+  if (keys.length === 0) return;
+
+  // Match variant name: `Key1=Value1, Key2=Value2`. Split on ', ' and compare
+  // as an unordered set so order differences don't break the lookup.
+  const targetTokens: Record<string, string> = {};
+  for (let i = 0; i < keys.length; i++) {
+    targetTokens[keys[i]] = properties[keys[i]];
+  }
+  let match: ComponentNode | null = null;
+  const children = componentSet.children;
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!child || typeof child.name !== 'string') continue;
+    const parts = child.name.split(', ');
+    const tokens: Record<string, string> = {};
+    for (let j = 0; j < parts.length; j++) {
+      const eq = parts[j].indexOf('=');
+      if (eq > 0) tokens[parts[j].slice(0, eq)] = parts[j].slice(eq + 1);
+    }
+    let allMatch = true;
+    for (let j = 0; j < keys.length; j++) {
+      if (tokens[keys[j]] !== targetTokens[keys[j]]) { allMatch = false; break; }
+    }
+    if (allMatch && child.type === 'COMPONENT') { match = child; break; }
+  }
+  if (!match) return;
+  if (!Array.isArray(match.fills) || match.fills.length === 0) return;
+
+  try {
+    instanceNode.fills = JSON.parse(JSON.stringify(match.fills));
+  } catch (_error) {
+    // Leave instance fills as-is if the override fails.
+  }
+}
+
+export type InstanceBackend = {
+  enableSymbolMasters: boolean;
+  splitClassName: (value: string | undefined) => string[];
+  ensureCvaComponentSet: (def: ComponentDef, theme: string, ctx: BackendCtx) => SceneNode | null;
+  ensureStateComponentSet: (def: ComponentDef, theme: string, ctx: BackendCtx) => SceneNode | null;
+  ensureNonCvaComponentMaster: (def: ComponentDef, theme: string, ctx: BackendCtx) => SceneNode | null;
+  getInstantiableComponent: (node: SceneNode) => ComponentNode | null;
+  getCvaSelectionFromInstance: (def: ComponentDef, instance: ComponentInstance) => Record<string, string>;
+  toFigmaVariantPropertyName: (key: string) => string;
+  toFigmaVariantPropertyValue: (value: string) => string;
+  getStateVariantForInstance: (def: ComponentDef, instance: ComponentInstance) => string;
+  isCheckedInstance: (instance: ComponentInstance) => boolean;
+  hasCheckedStateVariant: (def: ComponentDef) => boolean;
+  getInstanceTextOverride: (def: ComponentDef, instance: ComponentInstance) => string | null;
+  applyTextOverrideToInstance: (instanceNode: InstanceNode, value: string) => boolean;
+  applyCompoundTextOverridesToInstance: (def: ComponentDef, story: ComponentStory, instance: ComponentInstance, instanceNode: InstanceNode) => {
+    bySlot: Record<string, string>;
+    bySubcomponent: Record<string, string>;
+  };
+  analyzeSymbolPolicy: (def: ComponentDef, instance: ComponentInstance) => {
+    reason?: string | null;
+    ignoredProps: string[];
+    slotPropMappings: Record<string, string>;
+  };
+  setGeneratedSymbolDebugData: (node: SceneNode, data: Record<string, unknown>) => void;
+};
+
+export function tryCreateCvaComponentInstance(
+  def: ComponentDef,
+  instance: ComponentInstance,
+  theme: string,
+  ctx: BackendCtx,
+  backend: InstanceBackend
+): InstanceNode | null {
+  if (!backend.enableSymbolMasters) return null;
+  const props = instance && instance.props ? instance.props : {};
+  if (backend.splitClassName(props.className).length > 0) {
+    return null;
+  }
+
+  const variantKeys = Object.keys((def && def.variants) || {});
+  if (variantKeys.length === 0) return null;
+
+  const componentSet = backend.ensureCvaComponentSet(def, theme, ctx);
+  if (!componentSet) return null;
+
+  const sourceComponent = backend.getInstantiableComponent(componentSet);
+  if (!sourceComponent) return null;
+
+  // Smart fall-back: when the instance has overriding JSX-element children
+  // (e.g. an icon child like `<Bold />`), the symbol-instance path can only
+  // produce a faithful render if the master happens to have been built with
+  // the SAME icon — Figma's instance API can't per-instance-swap SVG
+  // vectors. So compare the master's recorded icon name (stamped by
+  // cva-master when the variant was built) against the instance's first
+  // element-child tagName:
+  //   - match  → master would render the same icon → proceed (symbol instance)
+  //   - differ → master would render the WRONG icon → return null (caller
+  //              falls through to JSX-tree frame rendering so the actual
+  //              instance icon is preserved)
+  // For text-only children (e.g. `<Button>Click me</Button>`), the text-
+  // override path handles per-instance content and this guard is a no-op.
+  if (cvaInstanceHasOverridingJsxChildren(props)) {
+    const masterIconName = typeof sourceComponent.getPluginData === 'function'
+      ? sourceComponent.getPluginData(MASTER_ICON_NAME_KEY)
+      : '';
+    const instanceIconName = getFirstElementJsxChildTagName(props.__jsxChildren);
+    if (!masterIconName || !instanceIconName || masterIconName !== instanceIconName) {
+      return null;
+    }
+  }
+
+  // Secondary fall-back: even when the icon matches, an instance carrying
+  // a truthy state prop (`defaultPressed`, `defaultChecked`, etc.) can't
+  // be expressed as a symbol-instance reuse — the master was built once
+  // from one story whose state is fixed in its baked-in classes, and
+  // Figma's instance API doesn't apply per-instance `data-[pressed]:*`
+  // resolution. Fall back to frame rendering so the variant engine
+  // (DATA_ATTR_PROP_ALIASES in node-variants.ts) activates the right
+  // state styling at render time.
+  if (cvaInstanceHasOverridingState(props)) {
+    return null;
+  }
+
+  let figmaInstance: InstanceNode | null = null;
+  try {
+    figmaInstance = sourceComponent.createInstance();
+  } catch (_error) {
+    return null;
+  }
+  if (!figmaInstance) return null;
+
+  const selection = backend.getCvaSelectionFromInstance(def, instance);
+  const properties: Record<string, string> = {};
+  for (let i = 0; i < variantKeys.length; i++) {
+    const key = variantKeys[i];
+    if (!selection[key]) continue;
+    properties[backend.toFigmaVariantPropertyName(key)] = backend.toFigmaVariantPropertyValue(selection[key]);
+  }
+
+  if (Object.keys(properties).length > 0) {
+    try {
+      figmaInstance.setProperties(properties);
+    } catch (_error) {
+      // Keep the default instance when property mapping fails.
+    }
+    // Figma's variant swap inherits boundVariables.color from the target variant
+    // but drops paint.opacity — so for tokens with a Tailwind alpha modifier
+    // (e.g. bg-primary/10), the instance renders at full opacity. Copy the
+    // matching variant master's fills onto the instance to restore opacity.
+    copyVariantFillsToInstance(componentSet, figmaInstance, properties);
+  }
+
+  const textOverrides: Record<string, string> = {};
+  const textOverride = backend.getInstanceTextOverride(def, instance);
+  if (textOverride) {
+    const applied = backend.applyTextOverrideToInstance(figmaInstance, textOverride);
+    if (applied) {
+      textOverrides.primary = textOverride;
+    }
+  }
+
+  backend.setGeneratedSymbolDebugData(figmaInstance, {
+    decision: 'cva-instance',
+    ignoredProps: [],
+    slotPropMappings: {},
+    textOverrides,
+  });
+
+  return figmaInstance;
+}
+
+export function tryCreateNonCvaComponentInstance(
+  def: ComponentDef,
+  instance: ComponentInstance,
+  theme: string,
+  ctx: BackendCtx,
+  backend: InstanceBackend,
+  story?: ComponentStory
+): InstanceNode | null {
+  if (!backend.enableSymbolMasters) return null;
+  if (!def || def.type === 'cva') return null;
+  if (def.symbolCandidate === false) return null;
+  const props = instance && instance.props ? instance.props : {};
+
+  if (def.type === 'state' && backend.splitClassName(props.className).length === 0) {
+    const stateSet = backend.ensureStateComponentSet(def, theme, ctx);
+    const sourceComponent = stateSet ? backend.getInstantiableComponent(stateSet) : null;
+    if (sourceComponent) {
+      try {
+        const figmaInstance = sourceComponent.createInstance();
+        const requestedState = backend.getStateVariantForInstance(def, instance);
+        const requestedChecked = backend.isCheckedInstance(instance);
+        try {
+          const stateProps: Record<string, string> = {
+            [backend.toFigmaVariantPropertyName('state')]: backend.toFigmaVariantPropertyValue(requestedState),
+          };
+          if (backend.hasCheckedStateVariant(def)) {
+            stateProps[backend.toFigmaVariantPropertyName('checked')] =
+              backend.toFigmaVariantPropertyValue(String(requestedChecked));
+          }
+          figmaInstance.setProperties(stateProps);
+        } catch (_setPropertiesError) {
+          // Keep default instance when mapping fails.
+        }
+
+        const textOverrides: Record<string, string> = {};
+        // Checked state controls (e.g. checkbox/switch) should not absorb story labels
+        // into the symbol itself; labels belong to surrounding layout.
+        if (!backend.hasCheckedStateVariant(def)) {
+          const textOverride = backend.getInstanceTextOverride(def, instance);
+          if (textOverride) {
+            const applied = backend.applyTextOverrideToInstance(figmaInstance, textOverride);
+            if (applied) textOverrides.primary = textOverride;
+          }
+        }
+        backend.setGeneratedSymbolDebugData(figmaInstance, {
+          decision: 'state-instance',
+          ignoredProps: [],
+          slotPropMappings: {},
+          textOverrides,
+        });
+        return figmaInstance;
+      } catch (_error) {
+        // Fall back to raw rendering below.
+      }
+    }
+  }
+
+  const policy = backend.analyzeSymbolPolicy(def, instance);
+  if (policy.reason) return null;
+
+  const master = backend.ensureNonCvaComponentMaster(def, theme, ctx);
+  if (!master || master.type !== 'COMPONENT') return null;
+
+  try {
+    const figmaInstance = master.createInstance();
+    const textOverrides: Record<string, string> = {};
+    if (def.type === 'compound' && story) {
+      const applied = backend.applyCompoundTextOverridesToInstance(def, story, instance, figmaInstance);
+      const appliedSlots = Object.keys(applied.bySlot);
+      if (appliedSlots.length > 0) {
+        for (let i = 0; i < appliedSlots.length; i++) {
+          const key = appliedSlots[i];
+          textOverrides[key] = applied.bySlot[key];
+        }
+      } else {
+        const appliedSubs = Object.keys(applied.bySubcomponent);
+        for (let i = 0; i < appliedSubs.length; i++) {
+          const key = appliedSubs[i];
+          textOverrides[key] = applied.bySubcomponent[key];
+        }
+      }
+    } else {
+      const textOverride = backend.getInstanceTextOverride(def, instance);
+      if (textOverride) {
+        const applied = backend.applyTextOverrideToInstance(figmaInstance, textOverride);
+        if (applied) textOverrides.primary = textOverride;
+      }
+    }
+
+    backend.setGeneratedSymbolDebugData(figmaInstance, {
+      decision: 'instance',
+      ignoredProps: policy.ignoredProps,
+      slotPropMappings: policy.slotPropMappings,
+      textOverrides,
+    });
+    return figmaInstance;
+  } catch (_error) {
+    return null;
+  }
+}

package/src/components/component-library.ts

@@ -0,0 +1,44 @@
+import { findChildByName } from '../cache';
+
+export const DESIGN_SYSTEM_PAGE_NAME = 'Design System';
+export const COMPONENT_LIBRARY_ROOT_NAME = '__Inkbridge Component Library';
+
+export function getInstantiableComponent(node: BaseNode | null): ComponentNode | null {
+  if (!node) return null;
+  if (node.type === 'COMPONENT') return node;
+  if (node.type === 'COMPONENT_SET') {
+    if (node.defaultVariant) return node.defaultVariant;
+    for (const candidate of node.children) {
+      if (candidate.type === 'COMPONENT') return candidate;
+    }
+  }
+  return null;
+}
+
+export function findExistingComponentLibraryRoot(): FrameNode | 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;
+}
+
+// findChildByName returns `any` at the boundary; the caller type-narrows.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findExistingThemeComponentLibrary(theme: string): any | null {
+  const root = findExistingComponentLibraryRoot();
+  if (!root) return null;
+  return findChildByName(root, String(theme || 'primary') + ' Masters');
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function findExistingThemedComponentNode(theme: string, name: string): any | null {
+  const themeLibrary = findExistingThemeComponentLibrary(theme);
+  if (!themeLibrary) return null;
+  return findChildByName(themeLibrary, name);
+}