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

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

@@ -0,0 +1,334 @@
+/**
+ * design-system.ts — Design System Page Generation
+ *
+ * Orchestrates building the "Design System" page in Figma.
+ *
+ * ## Incremental re-render
+ * Frames are no longer rebuilt from scratch on every run. Instead:
+ *
+ * - The "Design Tokens" row is rebuilt only when token values change
+ *   (detected via a hash stored in Figma plugin data).
+ * - Component section frames are preserved and
+ *   their contents are diffed at the per-component-block level — see
+ *   story-builder.ts and frame-cache.ts for details.
+ *
+ * When a frame is unchanged its node ID is preserved, so designer annotations
+ * and manual repositioning survive plugin re-runs.
+ *
+ * yOffset / xOffset in opts are only applied when a section is created for the
+ * first time. Existing sections keep their current position.
+ */
+
+import { debug } from '../tokens';
+import { getThemeNames, TOKENS } from '../tokens';
+import {
+  demoFrameColors,
+  demoFrameRadii,
+  demoFrameFonts,
+  demoFrameSpacing,
+  demoFrameFontSizes,
+  demoFrameShadows,
+  demoFrameBreakpoints,
+  buildTokensCategorySection,
+} from '../tokens';
+import { createUIComponents, pruneGeneratedComponentLibrary } from './ui-builder';
+import { hashString, stableStringify, getFrameHash, setFrameHash, findChildByName } from '../cache';
+import { isGeneratedDesignSystemNode, tagGeneratedNode } from './generated-node';
+
+const DESIGN_SYSTEM_PAGE_NAME = 'Design System';
+const COMPONENT_LIBRARY_ROOT_NAME = '__Inkbridge Component Library';
+// Synthetic preflight identifier — must match the constant in main.ts.
+const DESIGN_TOKENS_TOGGLE = '__design_tokens__';
+
+function removeStalePageLabels(page: PageNode | null, labels: string[]): void {
+  if (!page || !Array.isArray(page.children)) return;
+  const targets = new Set(labels);
+  const staleNodes = page.children.filter((node): node is TextNode =>
+    node.type === 'TEXT'
+      && typeof node.characters === 'string'
+      && targets.has(node.characters)
+  );
+  for (let i = 0; i < staleNodes.length; i++) {
+    staleNodes[i].remove();
+  }
+}
+
+// Remove orphaned top-level nodes left behind by failed/interrupted runs.
+// The Design System page is plugin-managed: only these named sections are
+// expected as direct children. Anything else is stale generator output.
+const KNOWN_TOP_LEVEL_SECTIONS = new Set([
+  'Design Tokens',
+  'UI Components',
+  COMPONENT_LIBRARY_ROOT_NAME,
+]);
+
+function removeDuplicateTopLevelSections(page: PageNode | null): void {
+  if (!page || !Array.isArray(page.children)) return;
+  const seen: Record<string, boolean> = {};
+  const children = page.children.slice();
+  for (let i = 0; i < children.length; i++) {
+    const node = children[i];
+    if (!node || !KNOWN_TOP_LEVEL_SECTIONS.has(node.name)) continue;
+    if (seen[node.name]) {
+      node.remove();
+      continue;
+    }
+    seen[node.name] = true;
+  }
+}
+
+function removeOrphanedTopLevelNodes(page: PageNode | null): void {
+  if (!page || !Array.isArray(page.children)) return;
+  const orphans = page.children.filter(function(node) {
+    if (!node) return false;
+    if (KNOWN_TOP_LEVEL_SECTIONS.has(node.name)) return false;
+    // Primary path: generated metadata marks this node as plugin output.
+    if (isGeneratedDesignSystemNode(node)) return true;
+    // Legacy fallback: older plugin runs didn't tag generated nodes.
+    if (isLegacyGeneratedOrphan(node)) return true;
+    // Defensive cleanup: plugin-managed page should not contain any additional
+    // direct children at root level, regardless of node type.
+    return true;
+  });
+  for (let i = 0; i < orphans.length; i++) {
+    orphans[i].remove();
+  }
+}
+
+function nodeHasTextDescendantLike(node: BaseNode, phrase: string): boolean {
+  if (!node) return false;
+  const value = String(phrase || '').trim().toLowerCase();
+  if (!value) return false;
+  if (node.type === 'TEXT' && typeof node.characters === 'string') {
+    return node.characters.trim().toLowerCase().indexOf(value) !== -1;
+  }
+  if (!('children' in node) || !Array.isArray(node.children)) return false;
+  for (let i = 0; i < node.children.length; i++) {
+    if (nodeHasTextDescendantLike(node.children[i], value)) return true;
+  }
+  return false;
+}
+
+function isLegacyGeneratedOrphan(node: BaseNode): boolean {
+  if (!node) return false;
+  if (node.name === COMPONENT_LIBRARY_ROOT_NAME) return true;
+  if (node.name === 'States' && nodeHasTextDescendantLike(node, 'state matrix')) return true;
+  if (node.name === 'Responsive' && nodeHasTextDescendantLike(node, 'responsive')) return true;
+  if (node.name === 'State Axes' || node.name === 'State Table') return true;
+  if (typeof node.name === 'string' && node.name.startsWith('State Row/')) return true;
+  if (node.type === 'TEXT' && typeof node.characters === 'string') {
+    const text = node.characters.trim().toLowerCase();
+    if (text.indexOf('state matrix') !== -1 || text === 'responsive') return true;
+  }
+  // Catch detached/renamed fragments that still carry legacy marker labels.
+  if (nodeHasTextDescendantLike(node, 'state matrix') || nodeHasTextDescendantLike(node, 'responsive')) return true;
+  return false;
+}
+
+function removeLegacyArtifactsFromNonDesignSystemPages(): void {
+  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' || page.name === DESIGN_SYSTEM_PAGE_NAME || !Array.isArray(page.children)) continue;
+    const staleNodes = page.children.filter(function(node: SceneNode) {
+      return isGeneratedDesignSystemNode(node) || isLegacyGeneratedOrphan(node);
+    });
+    for (let j = 0; j < staleNodes.length; j++) {
+      staleNodes[j].remove();
+    }
+  }
+}
+
+function removeGeneratedArtifactsInNode(node: BaseNode): number {
+  if (!node || !('children' in node) || !Array.isArray(node.children)) return 0;
+  let removed = 0;
+  const children = node.children.slice();
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!child) continue;
+    if (child.type === 'PAGE') {
+      removed += removeGeneratedArtifactsInNode(child);
+      continue;
+    }
+
+    const generated = isGeneratedDesignSystemNode(child);
+    const legacy = isLegacyGeneratedOrphan(child);
+    if (generated || legacy) {
+      child.remove();
+      removed += 1;
+      continue;
+    }
+
+    if ('children' in child && Array.isArray(child.children)) {
+      removed += removeGeneratedArtifactsInNode(child);
+    }
+  }
+  return removed;
+}
+
+export function cleanGeneratedDesignSystemArtifacts(): { removedNodes: number; touchedPages: number } {
+  const pages = figma.root && Array.isArray(figma.root.children) ? figma.root.children : [];
+  let removedNodes = 0;
+  let touchedPages = 0;
+  for (let i = 0; i < pages.length; i++) {
+    const page = pages[i];
+    if (!page || page.type !== 'PAGE') continue;
+    const removedInPage = removeGeneratedArtifactsInNode(page);
+    if (removedInPage > 0) {
+      removedNodes += removedInPage;
+      touchedPages += 1;
+    }
+  }
+  return { removedNodes, touchedPages };
+}
+
+/**
+ * Loading-panel status callback signature. Accepts either a flat string
+ * (legacy single-line status) or `{ phase, detail }` where the phase is
+ * sticky context across detail-only updates (so "Building components…"
+ * stays as the header while detail messages cycle through theme /
+ * section names). Both forms are honoured by `main.ts:setStatus`.
+ */
+export type StatusUpdate =
+  | string
+  | { phase?: string; detail?: string; noYield?: boolean };
+
+export interface BuildDesignSystemOptions {
+  onStatus?: (status: StatusUpdate) => void | Promise<void>;
+}
+
+export async function buildDesignSystemSinglePage(
+  excluded?: string[],
+  options?: BuildDesignSystemOptions,
+): Promise<void> {
+  const onStatus = options && options.onStatus
+    ? options.onStatus
+    : function (_s: StatusUpdate): void | Promise<void> { return; };
+  let ds: PageNode | null = figma.root.children.find(p => p.name === DESIGN_SYSTEM_PAGE_NAME) ?? null;
+  if (!ds) { ds = figma.createPage(); ds.name = DESIGN_SYSTEM_PAGE_NAME; }
+  tagGeneratedNode(ds, 'design-system-page');
+  removeLegacyArtifactsFromNonDesignSystemPages();
+  figma.currentPage = ds;
+  removeDuplicateTopLevelSections(ds);
+  removeOrphanedTopLevelNodes(ds);
+  removeStalePageLabels(ds, ['Design Tokens', 'UI Components']);
+
+  const themeNames = getThemeNames(TOKENS);
+
+  // Compute a single token hash for this run. Passed into createUIComponents
+  // so component blocks can include token state in their own hashes.
+  const tokenHash = hashString(stableStringify(TOKENS));
+
+  // The design-tokens toggle is a synthetic preflight item; strip it before
+  // forwarding the excluded list to the component builder so it isn't treated
+  // as a missing component.
+  const skipDesignTokens = (excluded || []).indexOf(DESIGN_TOKENS_TOGGLE) !== -1;
+  excluded = (excluded || []).filter(function (name) { return name !== DESIGN_TOKENS_TOGGLE; });
+
+  // --- Design Tokens row (incremental) ---
+  // Rebuilt only when token values have changed since the last run, and only
+  // when the design-tokens preflight toggle is selected.
+  let tokensRow: FrameNode | null = findChildByName(ds, 'Design Tokens') as FrameNode | null;
+  const tokensNeedRebuild = !skipDesignTokens && (!tokensRow || getFrameHash(tokensRow) !== tokenHash);
+  if (tokensNeedRebuild) await onStatus('Building design tokens…');
+  if (tokensNeedRebuild) {
+    const prevX: number = tokensRow ? tokensRow.x : 48;
+    const prevY: number = tokensRow ? tokensRow.y : 48;
+    if (tokensRow) tokensRow.remove();
+
+    tokensRow = figma.createFrame();
+    tokensRow.name = 'Design Tokens';
+    tokensRow.layoutMode = 'VERTICAL';
+    tokensRow.primaryAxisSizingMode = 'AUTO';
+    tokensRow.counterAxisSizingMode = 'AUTO';
+    tokensRow.itemSpacing = 32;
+    tokensRow.paddingLeft = tokensRow.paddingRight = 32;
+    tokensRow.paddingTop = tokensRow.paddingBottom = 24;
+    tokensRow.fills = [];
+    tokensRow.strokes = [];
+    const appendIfPresent = (node: SceneNode | null): void => {
+      if (node && tokensRow) tokensRow.appendChild(node);
+    };
+    appendIfPresent(buildTokensCategorySection(
+      'Colors',
+      themeNames.map((themeName) => demoFrameColors(themeName))
+    ));
+    appendIfPresent(buildTokensCategorySection(
+      'Fonts',
+      themeNames.map((themeName) => demoFrameFonts(themeName))
+    ));
+    appendIfPresent(buildTokensCategorySection('Font sizes', [demoFrameFontSizes()]));
+    appendIfPresent(buildTokensCategorySection('Radius', [demoFrameRadii()]));
+    appendIfPresent(buildTokensCategorySection('Spacing', [demoFrameSpacing()]));
+    appendIfPresent(buildTokensCategorySection('Breakpoints', [demoFrameBreakpoints()]));
+    appendIfPresent(buildTokensCategorySection(
+      'Shadows',
+      themeNames.map((themeName) => demoFrameShadows(themeName))
+    ));
+    tokensRow.x = prevX;
+    tokensRow.y = prevY;
+    ds.appendChild(tokensRow);
+    setFrameHash(tokensRow, tokenHash);
+    tagGeneratedNode(tokensRow, 'design-tokens-row');
+    debug('Tokens row rebuilt', { columns: tokensRow.children.length, hash: tokenHash });
+  } else if (tokensRow) {
+    tagGeneratedNode(tokensRow, 'design-tokens-row');
+    debug('Tokens row unchanged — skipped', { hash: tokenHash, skipped: skipDesignTokens });
+  }
+
+  // Default y for a new UI Components section (below tokens row).
+  // Only used when the section does not yet exist on the page. When the design
+  // tokens row was skipped and never existed, fall back to the page top.
+  const defaultUiY = tokensRow ? (tokensRow.y + tokensRow.height + 80) : 48;
+
+  // Keep hidden master library aligned with current scanner output and themes.
+  // Removes stale/duplicate generated masters from old runs.
+  pruneGeneratedComponentLibrary(themeNames);
+
+  const excludedNames: string[] = (excluded && excluded.length > 0) ? excluded : [];
+
+  // Set the phase as a sticky header; createUIComponents below emits
+  // detail-only updates per theme / section. Both lines stay visible
+  // together so the user always knows what bigger phase is in flight
+  // even as the detail cycles through theme + section names.
+  // Phase text is sticky; ui.html animates trailing dots via CSS so we
+  // don't bake them into the string here.
+  await onStatus({ phase: 'Building components', detail: '' });
+  await createUIComponents(ds, {
+    themeNames,
+    yOffset: defaultUiY,
+    xOffset: 48,
+    excludeComponents: excludedNames,
+    preserveUnselectedComponents: excludedNames.length > 0,
+    tokenHash,
+    showSectionHeader: false,
+    onStatus,
+  });
+
+  // Reflow guard: the UI Components section y is only set on first creation.
+  // Partial-selection or subset runs previously produced an overlap with the
+  // Design Tokens row; enforce a minimum y every run while preserving any
+  // further-down position a designer may have set. Also align x so the
+  // section never drifts above/left of the tokens row.
+  const uiSection = findChildByName(ds, 'UI Components') as FrameNode | null;
+  if (uiSection && tokensRow) {
+    const minUiY = tokensRow.y + tokensRow.height + 80;
+    if (uiSection.y < minUiY) uiSection.y = minUiY;
+    if (uiSection.x < tokensRow.x) uiSection.x = tokensRow.x;
+  }
+
+  // Post-build orphan sweep: frames can be abandoned during a partial run
+  // (e.g. a rebuild path that errors out mid-way leaves a dangling frame at
+  // the page root). Rerun the sweeps so nothing survives outside the known
+  // top-level sections.
+  removeDuplicateTopLevelSections(ds);
+  removeOrphanedTopLevelNodes(ds);
+
+  // Frame the freshly-built page so the user lands on the result instead of
+  // wherever the viewport was before the run. Filter out invisible children
+  // defensively — scrollAndZoomIntoView throws on an empty selection.
+  const visibleChildren = ds.children.filter((node) => node.visible);
+  if (visibleChildren.length > 0) {
+    figma.viewport.scrollAndZoomIntoView(visibleChildren);
+  }
+}

package/src/design-system/frame-stabilizers.ts

@@ -0,0 +1,191 @@
+import { getBaseClass, isElementLikeNode, type NodeIR } from '../tailwind';
+import { isTabsRootTag, isTabsListTag, isTabsContentTag } from './tag-predicates';
+import { getNodeEffectiveClasses, getNodeMarginTopPx } from './node-helpers';
+
+/**
+ * Post-render frame stabilizers. Each function takes a frame (and possibly
+ * its parent) that's already been auto-laid-out and applies a fix that
+ * couldn't be expressed cleanly during initial render — usually because
+ * the fix depends on the parent's resolved width or on sibling layout.
+ *
+ * - `constrainSingleHorizontalTextChild`: when a fixed-width row has one
+ *   text child and other in-flow siblings, cap the text width so it doesn't
+ *   overflow and steal space from a sibling.
+ * - `stabilizeHorizontalStretchChild`: pin a STRETCH'd horizontal child to
+ *   its parent's content width when the parent is a fixed-width column,
+ *   so the child renders at the same width Figma would compute on its own.
+ * - `reflowMxAutoChildren`: re-flow children that the layout pass tagged
+ *   as 'mx-auto' so they fill the parent's content box width.
+ * - `applyVerticalMarginSpacing`: when stacked vertical children carry
+ *   `mt-*` utilities, reflect the largest margin-top into the frame's
+ *   itemSpacing (Figma can't apply per-child margin in auto-layout).
+ * - `enforceTabsChildSizing`: stretch a Tabs.List / Tabs.Content child to
+ *   its parent's content width so the tab bar visually fills the row.
+ */
+
+export function constrainSingleHorizontalTextChild(node: SceneNode): void {
+  if (node.type !== 'FRAME') return;
+  const frame = node;
+  if (
+    frame.layoutMode !== 'HORIZONTAL'
+    || !Array.isArray(frame.children)
+    || frame.children.length < 2
+  ) {
+    return;
+  }
+
+  // Keep naturally centered CTA/action rows intact.
+  // Constraining text width in CENTER rows makes one text child consume the
+  // remaining width, which shifts sibling controls off-center.
+  if (frame.primaryAxisAlignItems === 'CENTER') {
+    return;
+  }
+
+  // Width constraints only make sense once the row width is fixed.
+  if (frame.primaryAxisSizingMode !== 'FIXED') {
+    return;
+  }
+
+  const textChildren = frame.children.filter((child): child is TextNode => child?.type === 'TEXT');
+  if (textChildren.length !== 1) return;
+
+  // CSS flex: absolute/fixed siblings are out-of-flow and don't consume space
+  // in the row. Including them would steal width from the text and force wrap
+  // (e.g. a Select item's absolute check-indicator shrinking the label text).
+  const inFlowNonText = frame.children.filter((child) => {
+    if (!child || child.type === 'TEXT') return false;
+    if ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE') return false;
+    return true;
+  });
+  const nonTextWidth = inFlowNonText.reduce((sum, child) => {
+    return sum + ('width' in child ? child.width : 0);
+  }, 0);
+  const gapContributingCount = inFlowNonText.length + textChildren.length;
+
+  const availableWidth = Math.max(
+    0,
+    frame.width
+      - (frame.paddingLeft || 0)
+      - (frame.paddingRight || 0)
+      - (frame.itemSpacing || 0) * Math.max(0, gapContributingCount - 1)
+      - nonTextWidth,
+  );
+
+  if (availableWidth <= 0) return;
+
+  const textChild = textChildren[0];
+  // CSS-default behavior for text in a horizontal flex row is to overflow, not
+  // wrap. Only constrain if the text would actually exceed the available space
+  // AND there's another in-flow sibling competing for it.
+  if (inFlowNonText.length === 0) return;
+  if ((textChild.width || 0) <= availableWidth) return;
+  try {
+    textChild.textAutoResize = 'HEIGHT';
+    textChild.resize(availableWidth, textChild.height);
+  } catch (_err) {
+    // ignore resize errors
+  }
+}
+
+export function stabilizeHorizontalStretchChild(child: SceneNode, parent: SceneNode): void {
+  if (!parent || parent.type !== 'FRAME') return;
+  if (parent.layoutMode !== 'VERTICAL') return;
+  if (
+    !child
+    || child.type !== 'FRAME'
+    || child.layoutPositioning === 'ABSOLUTE'
+    || child.layoutMode !== 'HORIZONTAL'
+    || child.layoutAlign !== 'STRETCH'
+    || child.primaryAxisSizingMode === 'FIXED'
+    || child.name === 'mx-auto'
+  ) {
+    return;
+  }
+
+  const parentContentWidth = Math.max(
+    0,
+    (parent.width || 0) - (parent.paddingLeft || 0) - (parent.paddingRight || 0),
+  );
+  if (parentContentWidth <= 0) return;
+
+  try {
+    child.resize(parentContentWidth, Math.max(1, child.height || 1));
+    child.primaryAxisSizingMode = 'FIXED';
+  } catch (_err) {
+    // ignore resize errors
+  }
+}
+
+export function reflowMxAutoChildren(parent: SceneNode): void {
+  if (!parent || parent.type !== 'FRAME') return;
+  if (!Array.isArray(parent.children) || parent.children.length === 0) return;
+  const contentWidth = Math.max(0, (parent.width || 0) - (parent.paddingLeft || 0) - (parent.paddingRight || 0));
+  if (!contentWidth) return;
+  for (const child of parent.children) {
+    if (!child || child.name !== 'mx-auto') continue;
+    if (!('resize' in child)) continue;
+    try {
+      child.resize(contentWidth, Math.max(1, child.height || 1));
+      if ('layoutAlign' in child) child.layoutAlign = 'STRETCH';
+      if ('primaryAxisSizingMode' in child) child.primaryAxisSizingMode = 'FIXED';
+      if ('layoutSizingHorizontal' in child) child.layoutSizingHorizontal = 'FIXED';
+    } catch (_err) {
+      // ignore
+    }
+  }
+}
+
+export function applyVerticalMarginSpacing(frame: FrameNode, children: NodeIR[]): void {
+  if (!frame || frame.layoutMode !== 'VERTICAL' || !children || children.length <= 1) return;
+  let maxMarginTop = 0;
+  for (const child of children) {
+    if (!isElementLikeNode(child)) continue;
+    const mt = getNodeMarginTopPx(child);
+    if (mt > maxMarginTop) maxMarginTop = mt;
+  }
+  if (maxMarginTop > 0 && (!frame.itemSpacing || frame.itemSpacing < maxMarginTop)) {
+    frame.itemSpacing = maxMarginTop;
+  }
+}
+
+export function enforceTabsChildSizing(
+  parentNode: NodeIR,
+  child: NodeIR,
+  childNode: SceneNode,
+  parentContentWidth?: number
+): void {
+  if ((parentNode.kind !== 'element' && parentNode.kind !== 'component') || !isTabsRootTag(parentNode.tagName)) return;
+  if (child.kind !== 'element' && child.kind !== 'component') return;
+
+  const isTabsList = isTabsListTag(child.tagName);
+  const isTabsContent = isTabsContentTag(child.tagName);
+  if (!isTabsList && !isTabsContent) return;
+
+  const childClasses = getNodeEffectiveClasses(child);
+  const hasFullWidth = childClasses.some(cls => getBaseClass(cls) === 'w-full');
+  const shouldStretch = isTabsContent || (isTabsList && hasFullWidth);
+  if (!shouldStretch) return;
+
+  if ('layoutAlign' in childNode) {
+    try {
+      childNode.layoutAlign = 'STRETCH';
+    } catch (_err) {
+      // ignore
+    }
+  }
+
+  if (parentContentWidth == null || !Number.isFinite(parentContentWidth) || parentContentWidth <= 0) return;
+  if (childNode.type !== 'FRAME') return;
+
+  try {
+    const targetWidth = Math.max(1, parentContentWidth);
+    childNode.resize(targetWidth, Math.max(1, childNode.height || 1));
+    if (childNode.layoutMode === 'HORIZONTAL') {
+      childNode.primaryAxisSizingMode = 'FIXED';
+    } else if (childNode.layoutMode === 'VERTICAL') {
+      childNode.counterAxisSizingMode = 'FIXED';
+    }
+  } catch (_err) {
+    // ignore resize errors
+  }
+}

package/src/design-system/frame-utils.ts

@@ -0,0 +1,46 @@
+/**
+ * Generic Figma frame helpers used by the design-system page builder.
+ * Kept distinct from layout helpers (which deal with auto-layout sizing)
+ * — these are children-array maintenance routines.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isTextNode(node: any): boolean {
+  return !!node && node.type === 'TEXT';
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function removeDirectTextChildren(parent: any, names?: string[]): void {
+  if (!parent || !Array.isArray(parent.children)) return;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const stale = parent.children.filter(function(child: any) {
+    if (!isTextNode(child)) return false;
+    if (!names || names.length === 0) return true;
+    return names.indexOf(child.name) !== -1 || names.indexOf(child.characters) !== -1;
+  });
+  for (let i = 0; i < stale.length; i++) {
+    stale[i].remove();
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function removeDuplicateChildrenByName(parent: any, name: string, type?: string): void {
+  if (!parent || !Array.isArray(parent.children)) return;
+  let seen = false;
+  const children = parent.children.slice();
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!child || child.name !== name) continue;
+    if (type && child.type !== type) continue;
+    if (!seen) {
+      seen = true;
+      continue;
+    }
+    child.remove();
+  }
+}
+
+export function hasNodeChildren(node: BaseNode | null | undefined): boolean {
+  if (!node || !('children' in node)) return false;
+  return Array.isArray(node.children) && node.children.length > 0;
+}

package/src/design-system/generated-node.ts

@@ -0,0 +1,84 @@
+const GENERATED_KEY = 'inkbridge:generated';
+const GENERATED_SCOPE_KEY = 'inkbridge:scope';
+const GENERATED_ROLE_KEY = 'inkbridge:role';
+const FALLBACK_REASON_KEY = 'inkbridge:fallback-reason';
+const SYMBOL_DECISION_KEY = 'inkbridge:symbol-decision';
+const SYMBOL_IGNORED_PROPS_KEY = 'inkbridge:symbol-ignored-props';
+const SYMBOL_TEXT_OVERRIDES_KEY = 'inkbridge:symbol-text-overrides';
+const SYMBOL_SLOT_PROP_MAPPINGS_KEY = 'inkbridge:symbol-slot-prop-mappings';
+const GENERATED_SCOPE_VALUE = 'design-system';
+
+export function tagGeneratedNode(node: BaseNode | null | undefined, role: string): void {
+  if (!node) return;
+  try {
+    node.setPluginData(GENERATED_KEY, '1');
+    node.setPluginData(GENERATED_SCOPE_KEY, GENERATED_SCOPE_VALUE);
+    node.setPluginData(GENERATED_ROLE_KEY, role || 'unknown');
+  } catch (_error) {
+    // Not all node types support plugin data; ignore safely.
+  }
+}
+
+export function tagGeneratedSubtree(node: BaseNode | null | undefined, role: string): void {
+  if (!node) return;
+  tagGeneratedNode(node, role);
+  if (!('children' in node)) return;
+  for (let i = 0; i < node.children.length; i++) {
+    tagGeneratedSubtree(node.children[i], role);
+  }
+}
+
+export function isGeneratedDesignSystemNode(node: BaseNode | null | undefined): boolean {
+  if (!node) return false;
+  try {
+    return node.getPluginData(GENERATED_KEY) === '1'
+      && node.getPluginData(GENERATED_SCOPE_KEY) === GENERATED_SCOPE_VALUE;
+  } catch (_error) {
+    return false;
+  }
+}
+
+export function setGeneratedFallbackReason(node: BaseNode | null | undefined, reason: string): void {
+  if (!node) return;
+  tagGeneratedNode(node, 'instance-fallback');
+  try {
+    node.setPluginData(FALLBACK_REASON_KEY, String(reason || 'unknown'));
+  } catch (_error) {
+    // ignore
+  }
+}
+
+function setPluginDataValue(node: BaseNode | null | undefined, key: string, value: string): void {
+  if (!node || !key) return;
+  try {
+    node.setPluginData(key, String(value || ''));
+  } catch (_error) {
+    // ignore
+  }
+}
+
+export function setGeneratedSymbolDebugData(
+  node: BaseNode | null | undefined,
+  data: {
+    decision?: string;
+    ignoredProps?: string[];
+    textOverrides?: Record<string, string>;
+    slotPropMappings?: Record<string, string>;
+  }
+): void {
+  if (!node) return;
+  tagGeneratedNode(node, 'symbol-instance');
+
+  if (data && data.decision) {
+    setPluginDataValue(node, SYMBOL_DECISION_KEY, data.decision);
+  }
+  if (data && data.ignoredProps && data.ignoredProps.length > 0) {
+    setPluginDataValue(node, SYMBOL_IGNORED_PROPS_KEY, JSON.stringify(data.ignoredProps));
+  }
+  if (data && data.textOverrides && Object.keys(data.textOverrides).length > 0) {
+    setPluginDataValue(node, SYMBOL_TEXT_OVERRIDES_KEY, JSON.stringify(data.textOverrides));
+  }
+  if (data && data.slotPropMappings && Object.keys(data.slotPropMappings).length > 0) {
+    setPluginDataValue(node, SYMBOL_SLOT_PROP_MAPPINGS_KEY, JSON.stringify(data.slotPropMappings));
+  }
+}