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

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

@@ -0,0 +1,237 @@
+import { getBaseClass, mergeClasses, parseUtilityClass } from '../tailwind';
+import { parseSquareSizeToken } from '../layout';
+import { getComponentDefByName } from '../components';
+import {
+  isAccordionRootTag,
+  isAccordionItemTag,
+  isSelectItemIndicatorTag,
+  isRadioGroupIndicatorTag,
+} from './tag-predicates';
+import type { NodeIR } from '../tailwind';
+import type { RenderContext } from './render-context';
+
+/**
+ * NodeIR tree helpers shared by ui-builder and the rendering pipeline.
+ * Mostly about resolving the *effective* classes for a node (taking
+ * scanned component defs into account), per-child render-context
+ * derivation, and small structural utilities.
+ */
+
+/**
+ * Unwraps transparent single-child component wrappers so the caller's loop
+ * sees the visual child directly. Matches the same short-circuit applied
+ * during scanner classification.
+ *
+ * Without the `compDef` guard a real CVA component like `<Badge variant="soft">`
+ * (which has empty `classes` because the className is computed inside the
+ * component) would be unwrapped to its single text child, dropping the
+ * symbol entirely.
+ */
+export function unwrapTransparentWrapper(node: NodeIR): NodeIR {
+  let current = node;
+  for (let i = 0; i < 8; i++) {
+    if (current.kind !== 'component') return current;
+    if ((current.classes || []).length !== 0) return current;
+    if (!current.children || current.children.length !== 1) return current;
+    if (current.tagName.toLowerCase().endsWith('trigger')) return current;
+    if (getComponentDefByName(current.tagName)) return current;
+    // Context-sensitive indicator wrappers (Select/RadioGroup item indicators)
+    // gate their child's visibility on the parent Item being selected/checked.
+    // The gating check lives in `buildFigmaNode` and only runs when this
+    // function preserves the wrapper — without this guard, the wrapper was
+    // unwrapped to its check/dot icon BEFORE the suppression could fire, and
+    // every non-selected item rendered a stale indicator (the recurring
+    // "checkmarks on every Select item" bug).
+    if (isSelectItemIndicatorTag(current.tagName)) return current;
+    if (isRadioGroupIndicatorTag(current.tagName)) return current;
+    current = current.children[0];
+  }
+  return current;
+}
+
+export function createPerChildRenderContext(
+  baseContext: RenderContext,
+  parentNode: NodeIR,
+  child: NodeIR,
+  accordionItemOrdinal: { value: number }
+): RenderContext {
+  const childContext: RenderContext = { ...baseContext };
+  if (
+    (parentNode.kind === 'element' || parentNode.kind === 'component') &&
+    isAccordionRootTag(parentNode.tagName) &&
+    (child.kind === 'element' || child.kind === 'component') &&
+    isAccordionItemTag(child.tagName)
+  ) {
+    childContext.accordionItemIndex = accordionItemOrdinal.value++;
+  }
+  return childContext;
+}
+
+export function getRenderableChildren(node: NodeIR, classes: string[]): NodeIR[] {
+  if (node.kind !== 'element' && node.kind !== 'component') return [];
+  const children = node.children.slice();
+  if (node.kind !== 'element' || node.tagLower !== 'table') return children;
+  if (!classes.includes('caption-bottom')) return children;
+
+  const captions: NodeIR[] = [];
+  const others: NodeIR[] = [];
+  for (const child of children) {
+    if ((child.kind === 'element' || child.kind === 'component') && child.tagLower === 'caption') captions.push(child);
+    else others.push(child);
+  }
+  return captions.length > 0 ? others.concat(captions) : children;
+}
+
+export function normalizeComponentLookupKey(value: string): string {
+  return String(value || '').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function shouldMergeDefBaseClassesForTag(def: any, tagName: string): boolean {
+  if (!def || !def.name || !tagName) return false;
+  // Do not merge scanned component base classes into intrinsic HTML tags.
+  // Example: a native `button` inside Dialog.Close should not inherit the
+  // global Button component's class bag.
+  if (tagName === tagName.toLowerCase()) return false;
+  return normalizeComponentLookupKey(def.name) === normalizeComponentLookupKey(tagName);
+}
+
+/**
+ * Unwraps the scanner's nested `{ analysis: ... }` envelope when present,
+ * preserving the metadata fields (stories, layout, responsive, colorScheme,
+ * etc.) that live alongside `analysis`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function normalizeComponentDef(raw: any): any {
+  if (!raw || !raw.analysis) return raw;
+
+  // Scanner output stores component metadata (stories, layout, responsive, colorScheme)
+  // alongside the nested `analysis`. Many render paths want the analysis shape but still
+  // need the attached metadata, so preserve it when normalizing.
+  return {
+    ...raw.analysis,
+    filePath: raw.analysis.filePath || raw.filePath,
+    stories: Array.isArray(raw.analysis.stories)
+      ? raw.analysis.stories
+      : (Array.isArray(raw.stories) ? raw.stories : []),
+    hasStory: typeof raw.analysis.hasStory === 'boolean'
+      ? raw.analysis.hasStory
+      : !!raw.hasStory,
+    layout: raw.layout,
+    responsive: raw.responsive,
+    colorScheme: raw.colorScheme,
+    kind: raw.kind,
+    usesCount: raw.usesCount,
+    usedByCount: raw.usedByCount,
+    isLeaf: raw.isLeaf,
+    symbolCandidate: raw.symbolCandidate,
+    safeTextOverrideProps: Array.isArray(raw.safeTextOverrideProps) ? raw.safeTextOverrideProps : undefined,
+  };
+}
+
+export function getNodeEffectiveClasses(node: NodeIR): string[] {
+  if (node.kind !== 'element' && node.kind !== 'component') return [];
+  if (node.kind === 'element') return node.classes || [];
+
+  const ownClasses = node.classes || [];
+  const def = getComponentDefByName(node.tagName);
+  if (!def) return ownClasses;
+  const normalized = normalizeComponentDef(def);
+  const baseClasses = Array.isArray(normalized?.baseClasses)
+    ? normalized.baseClasses
+    : (Array.isArray(normalized?.classes) ? normalized.classes : []);
+  if (!baseClasses || baseClasses.length === 0) return ownClasses;
+  if (!shouldMergeDefBaseClassesForTag(normalized, node.tagName)) return ownClasses;
+  if (normalized?.type === 'simple') {
+    // Scanner "simple" class bags are file-wide and can include child-only display/layout classes.
+    // Prefer the instance classes; only fall back to sanitized base classes when none exist.
+    if (ownClasses.length > 0) return ownClasses;
+    return pickPreservedWrapperBaseClasses(baseClasses);
+  }
+  return mergeClasses(baseClasses, ownClasses);
+}
+
+export function getNodeMarginTopPx(node: NodeIR): number {
+  const classes = getNodeEffectiveClasses(node);
+  let maxMarginTop = 0;
+  for (const cls of classes) {
+    const atom = parseUtilityClass(cls);
+    if (!atom || !atom.utility) continue;
+    if (Array.isArray(atom.variants) && atom.variants.length > 0) continue;
+    const match = atom.utility.match(/^mt-(.+)$/);
+    if (!match) continue;
+    const resolved = parseSquareSizeToken(match[1]);
+    if (resolved != null && Number.isFinite(resolved) && resolved > maxMarginTop) {
+      maxMarginTop = resolved;
+    }
+  }
+  return maxMarginTop;
+}
+
+/**
+ * From a scanned component's bag of base classes, keep only the structural
+ * intent (positioning, container spacing, the first display class, gap /
+ * grid-template tokens) while dropping child-only classes that would
+ * over-style a wrapper frame.
+ */
+export function pickPreservedWrapperBaseClasses(defClasses: string[]): string[] {
+  if (!Array.isArray(defClasses) || defClasses.length === 0) return [];
+
+  const out: string[] = [];
+  let pickedDisplay = false;
+
+  for (const cls of defClasses) {
+    const base = getBaseClass(cls);
+    if (!base) continue;
+
+    // Positioning + container spacing
+    if (base === 'relative' || base === 'isolate') {
+      out.push(cls);
+      continue;
+    }
+    if (base.startsWith('p-') || base.startsWith('px-') || base.startsWith('py-')) {
+      out.push(cls);
+      continue;
+    }
+    if (base.startsWith('rounded')) {
+      out.push(cls);
+      continue;
+    }
+
+    // Preserve only the first display class from base definitions.
+    // Scanner class bags can include child classes; taking the first display signal
+    // keeps root intent (e.g. grid) and avoids later child overrides (e.g. inline-flex).
+    const isDisplayClass =
+      base === 'flex'
+      || base === 'inline-flex'
+      || base === 'grid'
+      || base === 'inline-grid'
+      || base === 'block'
+      || base === 'inline-block'
+      || base === 'contents'
+      || base === 'flow-root';
+    if (isDisplayClass) {
+      if (!pickedDisplay) {
+        out.push(cls);
+        pickedDisplay = true;
+      }
+      continue;
+    }
+
+    if (
+      base.startsWith('gap-')
+      || base.startsWith('gap-x-')
+      || base.startsWith('gap-y-')
+      || base.startsWith('space-x-')
+      || base.startsWith('space-y-')
+      || base.startsWith('grid-cols-')
+      || base.startsWith('grid-rows-')
+      || base.startsWith('auto-cols-')
+      || base.startsWith('auto-rows-')
+    ) {
+      out.push(cls);
+    }
+  }
+
+  return out;
+}

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

@@ -0,0 +1,196 @@
+import { parseUtilityClass } from '../tailwind';
+import type { NodeIR } from '../tailwind';
+
+/**
+ * Evaluates Tailwind v4 conditional variants (`data-[…]`, `has-[…]`,
+ * `has-data-[…]`, compound `has-[[…].…]`) against a resolved NodeIR. Used
+ * by ui-builder to "activate" conditionally-applied utilities — i.e. when
+ * the variant predicate matches the node's actual props/structure, the
+ * underlying utility is appended to the live class list.
+ *
+ * Pure: NodeIR-only walk, no Figma calls.
+ */
+
+/**
+ * Aliases that map a `data-*` lookup to the React/JSX prop conventions
+ * various component libraries use to express the same state. The variant
+ * engine itself only knows `data-*` selectors, but consumers write
+ * `defaultPressed`, `defaultChecked`, `disabled`, etc. as plain props.
+ *
+ * Without this table, `data-[pressed]:bg-accent` on a `<Toggle defaultPressed>`
+ * never resolves — there's no literal `data-pressed` attribute on the node,
+ * only the React prop. With it, `defaultPressed` flowing through after
+ * scanner expansion is treated as if the element had `data-pressed="true"`
+ * for variant-matching purposes.
+ *
+ * Only consulted by `getNodePropValue` when a lookup for a literal `data-*`
+ * key misses — so it never overrides an explicit attribute the consumer set.
+ */
+const DATA_ATTR_PROP_ALIASES: Record<string, ReadonlyArray<string>> = {
+  'data-pressed': ['defaultPressed', 'pressed'],
+  'data-disabled': ['disabled', 'aria-disabled'],
+  'data-checked': ['checked', 'defaultChecked', 'aria-checked'],
+  'data-selected': ['selected', 'aria-selected'],
+  'data-open': ['open', 'defaultOpen'],
+};
+
+function isTruthyPropValue(value: unknown): boolean {
+  if (value === true) return true;
+  if (typeof value === 'string') {
+    const lower = value.trim().toLowerCase();
+    return lower === 'true' || lower === 'on';
+  }
+  return false;
+}
+
+function getNodePropValue(node: NodeIR, key: string): string | null {
+  if ((node.kind !== 'element' && node.kind !== 'component') || !node.props) return null;
+  const props = node.props as Record<string, unknown>;
+  const value = props[key];
+  if (value != null) return String(value);
+  const aliases = DATA_ATTR_PROP_ALIASES[key];
+  if (aliases) {
+    for (let i = 0; i < aliases.length; i++) {
+      if (isTruthyPropValue(props[aliases[i]])) return 'true';
+    }
+  }
+  return null;
+}
+
+function nodeMatchesDataVariant(node: NodeIR, variant: string): boolean {
+  const equalMatch = variant.match(/^data-\[([a-zA-Z0-9_-]+)=([^\]]+)\]$/);
+  if (equalMatch) {
+    const attr = 'data-' + equalMatch[1];
+    const expected = equalMatch[2];
+    const actual = getNodePropValue(node, attr);
+    return actual != null && actual.trim() === expected;
+  }
+  const presentMatch = variant.match(/^data-\[([a-zA-Z0-9_-]+)\]$/);
+  if (presentMatch) {
+    const attr = 'data-' + presentMatch[1];
+    return getNodePropValue(node, attr) != null;
+  }
+  // Tailwind v4 / shadcn bare syntax: `data-highlighted` (without brackets).
+  const bareMatch = variant.match(/^data-([a-zA-Z][a-zA-Z0-9_-]*)$/);
+  if (bareMatch) {
+    const attr = 'data-' + bareMatch[1];
+    return getNodePropValue(node, attr) != null;
+  }
+  return false;
+}
+
+function getNodeChildren(node: NodeIR): NodeIR[] {
+  if (node.kind === 'element' || node.kind === 'component' || node.kind === 'fragment') {
+    return node.children;
+  }
+  if (node.kind === 'ring') return [node.child];
+  return [];
+}
+
+function nodeHasDescendantDataVariant(node: NodeIR, variant: string): boolean {
+  const equalMatch = variant.match(/^has-data-\[([a-zA-Z0-9_-]+)=([^\]]+)\]$/);
+  const presentMatch = variant.match(/^has-data-\[([a-zA-Z0-9_-]+)\]$/);
+  if (!equalMatch && !presentMatch) return false;
+
+  const attr = 'data-' + (equalMatch ? equalMatch[1] : presentMatch![1]);
+  const expected = equalMatch ? equalMatch[2] : null;
+
+  const stack: NodeIR[] = getNodeChildren(node).slice();
+  while (stack.length > 0) {
+    const current = stack.pop() as NodeIR;
+    const value = getNodePropValue(current, attr);
+    if (value != null) {
+      if (expected == null || value.trim() === expected) return true;
+    }
+    const children = getNodeChildren(current);
+    if (children.length > 0) {
+      for (let i = 0; i < children.length; i++) {
+        stack.push(children[i]);
+      }
+    }
+  }
+  return false;
+}
+
+function nodeHasClass(node: NodeIR, className: string): boolean {
+  if (node.kind !== 'element' && node.kind !== 'component') return false;
+  return Array.isArray(node.classes) && node.classes.indexOf(className) !== -1;
+}
+
+function nodeHasDescendantCompoundSelector(node: NodeIR, variant: string): boolean {
+  // Matches patterns like `has-[[data-slot=card-header].border-b]` — any
+  // descendant that carries BOTH the data attribute and the class.
+  const compoundMatch = variant.match(/^has-\[\[([a-zA-Z0-9_-]+)(?:=([^\]]+))?\]\.([a-zA-Z0-9_:\[\]\/-]+)\]$/);
+  if (!compoundMatch) return false;
+  const attr = compoundMatch[1];
+  const expected = compoundMatch[2] != null ? compoundMatch[2] : null;
+  const className = compoundMatch[3];
+
+  const stack: NodeIR[] = getNodeChildren(node).slice();
+  while (stack.length > 0) {
+    const current = stack.pop() as NodeIR;
+    const attrValue = getNodePropValue(current, attr);
+    const attrMatches = attrValue != null && (expected == null || attrValue.trim() === expected);
+    if (attrMatches && nodeHasClass(current, className)) return true;
+    const children = getNodeChildren(current);
+    for (let i = 0; i < children.length; i++) stack.push(children[i]);
+  }
+  return false;
+}
+
+function nodeMatchesHasVariant(node: NodeIR, variant: string): boolean {
+  if (variant === 'has-[>img:first-child]') {
+    const children = getNodeChildren(node);
+    if (children.length === 0) return false;
+    for (let i = 0; i < children.length; i++) {
+      const child = children[i];
+      if (child.kind !== 'element' && child.kind !== 'component') continue;
+      return child.tagLower === 'img';
+    }
+    return false;
+  }
+  if (nodeHasDescendantDataVariant(node, variant)) return true;
+  return nodeHasDescendantCompoundSelector(node, variant);
+}
+
+function isActivatedConditionalVariant(node: NodeIR, variant: string): boolean {
+  if (!variant) return false;
+  if (nodeMatchesDataVariant(node, variant)) return true;
+  if (nodeMatchesHasVariant(node, variant)) return true;
+  return false;
+}
+
+/**
+ * For each class with conditional variants (`data-*`, `has-*`), if every
+ * variant predicate matches the node, append the underlying utility to
+ * the active class list. This is the "if the data-state is open, also
+ * apply `bg-accent`" expansion the renderer needs to do at draw time.
+ */
+export function expandActiveConditionalVariants(classes: string[], node: NodeIR): string[] {
+  if (!classes || classes.length === 0) return classes;
+  const out = classes.slice();
+  const seen: Record<string, true> = {};
+  for (let i = 0; i < out.length; i++) {
+    seen[out[i]] = true;
+  }
+
+  for (let i = 0; i < classes.length; i++) {
+    const atom = parseUtilityClass(classes[i]);
+    if (!atom || !atom.utility) continue;
+    if (!Array.isArray(atom.variants) || atom.variants.length === 0) continue;
+
+    let allMatched = true;
+    for (let j = 0; j < atom.variants.length; j++) {
+      if (!isActivatedConditionalVariant(node, atom.variants[j])) {
+        allMatched = false;
+        break;
+      }
+    }
+    if (!allMatched) continue;
+    if (seen[atom.utility]) continue;
+    seen[atom.utility] = true;
+    out.push(atom.utility);
+  }
+
+  return out;
+}

package/src/design-system/non-cva-master.ts

@@ -0,0 +1,104 @@
+import { findChildByName, getFrameHash, setFrameHash, hashString, hashDef } from '../cache';
+import { RENDER_ENGINE_VERSION } from '../render-engine-version';
+import { tagGeneratedNode } from './generated-node';
+import { getThemeContext } from './theme-context';
+import { ENABLE_SYMBOL_MASTERS, ensureThemeComponentLibrary } from './master-shared';
+import { buildNonCvaSymbolSourceNode } from './story-frames';
+import { ensureCvaComponentSet } from './cva-master';
+import { ensureStateComponentSet } from './state-master';
+import type { StoryBuilderContext } from './story-builder-context';
+
+/**
+ * Master creation for non-CVA component types (simple / compound) and the
+ * preflight pass that warms all three master kinds (CVA, state, non-CVA)
+ * for a given theme.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildBasicComponentMasterHash(def: any, theme: string): string {
+  const themeContext = getThemeContext(theme);
+  return hashString(
+    hashDef(def)
+      + ':'
+      + theme
+      + ':basic-symbol-v3:'
+      + RENDER_ENGINE_VERSION
+      + ':'
+      + JSON.stringify({
+        colorGroup: themeContext.colorGroup,
+        radiusGroup: themeContext.radiusGroup,
+      })
+  );
+}
+
+export function ensureNonCvaComponentMaster(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  def: any,
+  theme: string,
+  ctx: StoryBuilderContext
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any | null {
+  if (!ENABLE_SYMBOL_MASTERS) return null;
+  if (!def || def.type === 'cva') return null;
+  if (def.symbolCandidate === false) return null;
+
+  const themeLibrary = ensureThemeComponentLibrary(theme);
+  if (!themeLibrary) return null;
+
+  const name = def.name + ' [' + theme + ']';
+  const masterHash = buildBasicComponentMasterHash(def, theme);
+  const existing = findChildByName(themeLibrary, name);
+  if (existing && existing.type === 'COMPONENT' && getFrameHash(existing) === masterHash) {
+    return existing;
+  }
+  if (existing) {
+    existing.remove();
+  }
+
+  const sourceNode = buildNonCvaSymbolSourceNode(def, theme, ctx);
+  if (!sourceNode) return null;
+  themeLibrary.appendChild(sourceNode);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let component: any = null;
+  try {
+    component = figma.createComponentFromNode(sourceNode);
+  } catch (_error) {
+    try {
+      sourceNode.remove();
+    } catch (_cleanupError) {
+      // ignore cleanup errors
+    }
+    return null;
+  }
+  if (!component) return null;
+
+  component.name = name;
+  component.visible = false;
+  if (component.parent !== themeLibrary) {
+    themeLibrary.appendChild(component);
+  }
+  setFrameHash(component, masterHash);
+  tagGeneratedNode(component, 'component-master:' + def.name + ':' + theme);
+  return component;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function warmSymbolMasters(defs: any[], theme: string, ctx: StoryBuilderContext): void {
+  if (!ENABLE_SYMBOL_MASTERS || !Array.isArray(defs) || defs.length === 0) return;
+  for (let i = 0; i < defs.length; i++) {
+    const def = defs[i];
+    if (!def || def.symbolCandidate === false) continue;
+    try {
+      if (def.type === 'cva') {
+        ensureCvaComponentSet(def, theme, ctx);
+      } else if (def.type === 'state') {
+        ensureStateComponentSet(def, theme, ctx);
+      } else if (def.type === 'simple' || def.type === 'compound') {
+        ensureNonCvaComponentMaster(def, theme, ctx);
+      }
+    } catch (_error) {
+      // Keep runtime resilient: missing master creation should not block raw preview rendering.
+    }
+  }
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Portal-aware story-tree resolution.
+ *
+ * Radix UI components like Dialog / Popover / Tooltip render content via
+ * React portals. When the scanner walks a story's JSX tree, portal-rooted
+ * subtrees are tagged `__fromPortal: true`. This module decides what to do
+ * with those tagged nodes for each story:
+ *
+ * - **Closed-state stories** (e.g. Dialog.Default — no `defaultOpen`):
+ *   strip portal subtrees so only the trigger button shows in Figma.
+ *   Mirrors browser closed state — the portal panel isn't visible.
+ *
+ * - **Open-state stories** (e.g. Popover.OpenPanel with `defaultOpen`):
+ *   keep the full tree so both trigger and panel render. Storybook shows
+ *   both in this case, and earlier behaviour (stripping the trigger) made
+ *   open stories look like orphan panels.
+ *
+ * The decision happens up-front in `resolvePortalAwareStoryTree`; the
+ * other exports are building blocks for callers that need finer control.
+ */
+
+/**
+ * Removes nodes marked __fromPortal from the tree.
+ * Used for closed-state stories (e.g. Select.Default, Dialog.Default) where Radix UI
+ * renders portal content in SSR even when closed — only the trigger should show in Figma.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function filterPortalNodesFromTree(node: any): any {
+  if (!node || typeof node !== 'object') return node;
+  if (node.__fromPortal || (node.props && node.props.__fromPortal)) return null;
+  const children = Array.isArray(node.children) ? node.children : [];
+  if (children.length === 0) return node;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const filtered: any[] = [];
+  let changed = false;
+  for (let i = 0; i < children.length; i++) {
+    const result = filterPortalNodesFromTree(children[i]);
+    if (result === null) {
+      changed = true;
+      continue;
+    }
+    if (result !== children[i]) changed = true;
+    filtered.push(result);
+  }
+  if (!changed) return node;
+  return Object.assign({}, node, { children: filtered });
+}
+
+/**
+ * Extracts the first node marked __fromPortal from the tree.
+ * Used for open-state stories (e.g. Popover.OpenPanel, Tooltip.OpenPanel) where
+ * the popup content should render in Figma, not the trigger button.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function extractPortalContentFromTree(node: any): any {
+  if (!node || typeof node !== 'object') return null;
+  if (node.props && node.props.__fromPortal) return node;
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) {
+      const found = extractPortalContentFromTree(child);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns true if the jsxTree contains any element whose tagName ends with "trigger".
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function treeHasTriggerElement(node: any): boolean {
+  if (!node || typeof node !== 'object') return false;
+  if (node.tagName && typeof node.tagName === 'string' &&
+      node.tagName.toLowerCase().endsWith('trigger')) return true;
+  if (Array.isArray(node.children)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return node.children.some((c: any) => treeHasTriggerElement(c));
+  }
+  return false;
+}
+
+/**
+ * Returns true if the jsxTree contains any node marked with __fromPortal by the scanner.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function treeHasPortalContent(node: any): boolean {
+  if (!node || typeof node !== 'object') return false;
+  if (node.props && node.props.__fromPortal) return true;
+  if (Array.isArray(node.children)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return node.children.some((c: any) => treeHasPortalContent(c));
+  }
+  return false;
+}
+
+/**
+ * Returns true if any node within the first few levels has defaultOpen or open=true.
+ * Used to distinguish intentionally-open stories from closed-state Radix SSR renders.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function treeHasOpenState(node: any, depth: number = 0): boolean {
+  if (!node || typeof node !== 'object' || depth > 4) return false;
+  const p = node.props;
+  if (p && (p.defaultOpen === 'true' || p.defaultOpen === true || p.open === 'true' || p.open === true)) return true;
+  if (Array.isArray(node.children)) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return node.children.some((c: any) => treeHasOpenState(c, depth + 1));
+  }
+  return false;
+}
+
+/**
+ * Returns true when the story jsxTree has both a trigger element and portal-unwrapped content
+ * AND the component is intentionally open (defaultOpen). Used for open-state stories like
+ * Popover.OpenPanel, Tooltip.OpenPanel.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function jsxTreeIsPortalTriggerOnly(tree: any): boolean {
+  return treeHasTriggerElement(tree) && treeHasPortalContent(tree);
+}
+
+/**
+ * Resolve story jsxTree for portal components:
+ * - closed stories: remove portal subtree so only trigger remains (matches
+ *   browser closed-state — portal isn't visible).
+ * - open stories: keep the full tree so both trigger and panel render. This
+ *   mirrors how Storybook renders the open state (e.g. Popover.OpenPanel,
+ *   Select.OpenPanel) — users see the button that opened the panel.
+ *   Previously we stripped the trigger for most portals, which made Popover
+ *   / Tooltip / DropdownMenu open stories look like orphan panels.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function resolvePortalAwareStoryTree(tree: any): any {
+  if (!tree) return null;
+  if (!jsxTreeIsPortalTriggerOnly(tree)) return tree;
+  if (treeHasOpenState(tree)) return tree;
+  return filterPortalNodesFromTree(tree);
+}