inkbridge 0.1.0-beta.20 → 0.1.0-beta.21

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

@@ -34,6 +34,7 @@ import {
   applyDeferredBottomPositioning,
   applyDeferredCenterYPositioning,
   applyFullWidthIfPossible,
+  applyRingIfPossible,
   applyGridColumnsWithReflow,
   enforceFixedBoxSizingAfterLayout,
   enforceGrowChildPrimaryFixed,
@@ -560,6 +561,32 @@ function nodeIRToJsxNode(node: NodeIR): JsxNode | null {
 // JSX Tree Rendering
 // ---------------------------------------------------------------------------
 
+/**
+ * Returns true when any direct IR child carries `ml-auto` (or `mx-auto`)
+ * on its className. `ml-auto` on a flex child means "push me along the
+ * primary axis"; the Figma equivalent is `primaryAxisAlignItems =
+ * 'SPACE_BETWEEN'` on the parent. The parent-side detection is needed
+ * because inline-text children (e.g. a `<span className="ml-auto">`
+ * containing only text) render via `createInlineTextNode` and never get
+ * a frame to carry the per-child `SELF_ALIGNMENT_NODES` mark that
+ * `deferred-layout.applyFullWidthIfPossible` reads. DropdownMenuShortcut
+ * was the canonical case — the inline-text path swallowed `ml-auto`
+ * entirely, leaving the shortcut anchored to the start of the item.
+ */
+function hasAutoMarginChild(children: readonly NodeIR[] | undefined): boolean {
+  if (!Array.isArray(children)) return false;
+  for (const child of children) {
+    if (!child || typeof child !== 'object') continue;
+    if (child.kind !== 'element' && child.kind !== 'component') continue;
+    const cl = (child as { classes?: unknown }).classes;
+    if (!Array.isArray(cl)) continue;
+    for (const cls of cl) {
+      if (cls === 'ml-auto' || cls === 'mx-auto') return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Create a separator node for divide-y/divide-x
  */
@@ -960,6 +987,7 @@ function buildFigmaNode(
         stabilizeHorizontalStretchChild(childNode, wrapper);
         constrainSingleHorizontalTextChild(childNode);
         applyFullWidthIfPossible(childNode, wrapper, context.maxWidth != null ? { widthOverride: context.maxWidth } : undefined);
+        applyRingIfPossible(childNode, wrapper);
         applyAspectRatioIfPossible(childNode);
         // The just-resolved aspect ratio / full-width may have given this
         // child its final dimensions, so resolve any deferred percent
@@ -1031,18 +1059,33 @@ function buildFigmaNode(
     ring.cornerRadius = baseRadius + node.offsetWidth;
 
     let innerParent: FrameNode = ring;
-    if (node.offsetWidth > 0 && node.offsetColor) {
+    if (node.offsetWidth > 0) {
+      // ring-offset-N — even without an explicit ring-offset-COLOR class
+      // we still need the gap. CSS draws the offset as a transparent
+      // band (inheriting the page background) that separates the inner
+      // element's border from the outer ring stroke. Without this
+      // wrapper, the ring stroke sits flush against the border and the
+      // two visually merge into one thick line — the symptom: shadcn
+      // Select trigger / Input focus state showing a single fat green
+      // ring instead of "gray border + gap + green ring" like in the
+      // browser.
       const offsetFrame = figma.createFrame();
       offsetFrame.name = 'ring-offset';
       offsetFrame.layoutMode = 'HORIZONTAL';
       offsetFrame.primaryAxisSizingMode = 'AUTO';
       offsetFrame.counterAxisSizingMode = 'AUTO';
       applyClipBehavior(offsetFrame, []);
-      offsetFrame.fills = [{
-        type: 'SOLID',
-        color: { r: node.offsetColor.r, g: node.offsetColor.g, b: node.offsetColor.b },
-        opacity: 1,
-      }];
+      if (node.offsetColor) {
+        offsetFrame.fills = [{
+          type: 'SOLID',
+          color: { r: node.offsetColor.r, g: node.offsetColor.g, b: node.offsetColor.b },
+          opacity: 1,
+        }];
+      } else {
+        // Transparent gap — matches CSS's default offset behaviour when
+        // no `ring-offset-COLOR` was set.
+        offsetFrame.fills = [];
+      }
       offsetFrame.strokes = [];
       offsetFrame.paddingLeft = offsetFrame.paddingRight = offsetFrame.paddingTop = offsetFrame.paddingBottom = node.offsetWidth;
       offsetFrame.cornerRadius = baseRadius + node.offsetWidth;
@@ -1087,6 +1130,7 @@ function buildFigmaNode(
       if (!ringIsAbsolute) {
         applyFullWidthIfPossible(childNode, innerParent);
       }
+      applyRingIfPossible(childNode, innerParent);
       return maybeWrapMxAuto(ring, node.classes, context);
     }
 
@@ -1786,6 +1830,57 @@ function buildFigmaNode(
         applyTailwindStylesToFrame(wrapperFrame, activeMergedClasses, colorGroup, radiusGroup, theme);
       }
       applyClipBehavior(wrapperFrame, activeMergedClasses);
+      // Component wrappers that the scanner emits as Radix primitives
+      // (`<DropdownMenuPrimitive.Item>`, `<TabsPrimitive.Trigger>`, …) reach
+      // this branch with `kind: 'component'`. The `kind: 'element'` branch
+      // applies `shouldStretchToParentWidth` to stretch block-level children
+      // to a vertical parent's content width; without the same check here a
+      // DropdownMenuItem inside a `w-56` Content stays HUG-width. Treat the
+      // wrapper as a div — Radix/shadcn primitives render <div> by default
+      // unless `asChild` is used (handled separately) — so block-flow stretch
+      // applies. The `__fromPortal` guard below intentionally runs after so
+      // portal panels still tag themselves.
+      if (
+        context.parentLayout === 'VERTICAL'
+        && shouldStretchToParentWidth('div', activeMergedClasses)
+      ) {
+        try { wrapperFrame.layoutAlign = 'STRETCH'; } catch (_err) { /* ignore */ }
+        // Mirror the `kind: 'element'` branch's resize: layoutAlign alone may
+        // not grow the frame when the parent isn't sized yet, so when we know
+        // context.maxWidth, set the axis we'd otherwise hug to FIXED at that
+        // width. Without this the Item stays at its content width even after
+        // the STRETCH mark.
+        if (context.maxWidth && context.maxWidth > 0) {
+          try {
+            if (
+              wrapperFrame.layoutMode === 'HORIZONTAL'
+              && wrapperFrame.primaryAxisSizingMode !== 'FIXED'
+            ) {
+              wrapperFrame.resize(context.maxWidth, wrapperFrame.height);
+              wrapperFrame.primaryAxisSizingMode = 'FIXED';
+            } else if (
+              wrapperFrame.layoutMode === 'VERTICAL'
+              && wrapperFrame.counterAxisSizingMode !== 'FIXED'
+            ) {
+              wrapperFrame.resize(context.maxWidth, wrapperFrame.height);
+              wrapperFrame.counterAxisSizingMode = 'FIXED';
+            }
+          } catch (_err) { /* ignore resize errors */ }
+        }
+      }
+      // `ml-auto` on any direct child → parent uses SPACE_BETWEEN along the
+      // primary axis. See `hasAutoMarginChild` above for why the parent has
+      // to detect this itself (inline-text children never carry a frame
+      // mark). Only flip when the consumer hasn't already set a `justify-*`
+      // (the default Figma value is `MIN`, which is also what we get for a
+      // flex with no `justify-*`).
+      if (
+        wrapperFrame.layoutMode === 'HORIZONTAL'
+        && wrapperFrame.primaryAxisAlignItems === 'MIN'
+        && hasAutoMarginChild(node.children)
+      ) {
+        try { wrapperFrame.primaryAxisAlignItems = 'SPACE_BETWEEN'; } catch (_err) { /* ignore */ }
+      }
       // Tag portal panels so story-builder can grow Story Layout past narrow wrapper
       // classes (e.g. `w-56`) that would otherwise clip the panel. See portal-panel.ts.
       if (node.props && node.props.__fromPortal) {
@@ -1842,6 +1937,7 @@ function buildFigmaNode(
             ? { skipFullWidth: skipWrapperFullWidth, widthOverride: childCtx.maxWidth }
             : undefined;
           applyFullWidthIfPossible(childNode, wrapperFrame, fullWidthOptions);
+          applyRingIfPossible(childNode, wrapperFrame);
           applyAspectRatioIfPossible(childNode);
           enforceTabsChildSizing(node, child, childNode, childCtx.maxWidth);
           if (isElementLikeNode(child)) {
@@ -1914,6 +2010,7 @@ function buildFigmaNode(
           ? { skipFullWidth: skipCompFullWidth, widthOverride: compChildCtx.maxWidth }
           : undefined;
         applyFullWidthIfPossible(childNode, compFrame, fullWidthOptions);
+        applyRingIfPossible(childNode, compFrame);
         applyAspectRatioIfPossible(childNode);
         if (isElementLikeNode(child)) {
           enforceFixedBoxSizingAfterLayout(childNode, child.classes);
@@ -1965,6 +2062,17 @@ function buildFigmaNode(
         applyTailwindStylesToFrame(frame, classes, colorGroup, radiusGroup, theme);
       }
       applyClipBehavior(frame, classes);
+      // `ml-auto` on any direct child → flip parent to SPACE_BETWEEN. Mirror
+      // of the wrapper-branch detection above; needed here because inline
+      // text children (e.g. `<span className="ml-auto">`) render as text
+      // nodes and never carry a frame mark for deferred-layout to read.
+      if (
+        frame.layoutMode === 'HORIZONTAL'
+        && frame.primaryAxisAlignItems === 'MIN'
+        && hasAutoMarginChild(node.children)
+      ) {
+        try { frame.primaryAxisAlignItems = 'SPACE_BETWEEN'; } catch (_err) { /* ignore */ }
+      }
       if (
         context.parentLayout === 'VERTICAL'
         && shouldStretchToParentWidth(tagLower, classes)
@@ -2041,6 +2149,7 @@ function buildFigmaNode(
               ? { skipFullWidth: skipElementFullWidth, widthOverride: childContext.maxWidth }
               : undefined;
             applyFullWidthIfPossible(childNode, frame, fullWidthOptions);
+            applyRingIfPossible(childNode, frame);
             applyAspectRatioIfPossible(childNode);
             if (isElementLikeNode(child)) {
               enforceFixedBoxSizingAfterLayout(childNode, child.classes);
@@ -2406,6 +2515,7 @@ function buildFigmaNode(
         ? { skipFullWidth: skipChildFullWidth, widthOverride: contentWidth }
         : undefined;
       applyFullWidthIfPossible(childNode, frame, fullWidthOptions);
+      applyRingIfPossible(childNode, frame);
       applyAspectRatioIfPossible(childNode);
       enforceGrowChildPrimaryFixed(childNode, frame);
       enforceTabsChildSizing(node, child, childNode, childContext.maxWidth);

package/src/framework-adapters/index.ts

@@ -15,9 +15,22 @@
  */
 
 import type { NodeIR } from '../tailwind/node-ir';
-import { applyShadcnAdapter } from './shadcn';
+import { applyShadcnAdapter, isShadcnAdapterDroppedTag } from './shadcn';
 
-export { applyShadcnAdapter, getShadcnSlotInjections } from './shadcn';
+export { applyShadcnAdapter, getShadcnSlotInjections, isShadcnAdapterDroppedTag } from './shadcn';
+
+/**
+ * Returns true when the given JSX tagName is unconditionally dropped by
+ * some registered framework adapter at render time. Walks that adapters
+ * declare via their own `is…DroppedTag` predicate so callers don't have to
+ * know which adapters exist. Pre-render scans (responsive-signal
+ * detection, complexity heuristics, …) consult this to avoid counting
+ * classes on elements that never reach Figma.
+ */
+export function isFrameworkAdapterDroppedTag(tagName: string): boolean {
+  return isShadcnAdapterDroppedTag(tagName);
+  // Future adapters add `|| isMuiAdapterDroppedTag(tagName)` etc.
+}
 
 /**
  * Run every registered framework adapter against the IR in turn. Each

package/src/framework-adapters/shadcn.ts

@@ -38,14 +38,7 @@
 // Type-only import: avoid a runtime cycle with `tailwind/node-ir.ts`,
 // which imports this file's `applyShadcnAdapter`.
 import type { NodeIR } from '../tailwind/node-ir';
-
-// Inlined to avoid the runtime import cycle above. We only care about
-// `element` / `component` nodes (the ones with `props` + `classes`).
-// `ring` nodes wrap a child without props/classes of their own — they
-// have a separate recursion branch.
-function isClassedElement(node: NodeIR): node is Extract<NodeIR, { kind: 'element' | 'component' }> {
-  return node.kind === 'element' || node.kind === 'component';
-}
+import { isClassedElement, mergeMissing, resolveValuePercents } from '../tailwind/adapter-utils';
 
 /**
  * `data-slot` → extra Tailwind classes injected before layout solving.
@@ -90,19 +83,6 @@ function toElementWithClasses(node: NodeIR, classes: string[]): NodeIR {
   return Object.assign({}, node, patch) as NodeIR;
 }
 
-function mergeMissing(existing: string[], extras: readonly string[]): string[] {
-  if (extras.length === 0) return existing;
-  const set = new Set(existing);
-  let out: string[] | null = null;
-  for (const cls of extras) {
-    if (set.has(cls)) continue;
-    if (!out) out = existing.slice();
-    out.push(cls);
-    set.add(cls);
-  }
-  return out ?? existing;
-}
-
 export function getShadcnSlotInjections(slot: string): readonly string[] | null {
   return SLOT_CLASS_INJECTIONS[slot] ?? null;
 }
@@ -256,51 +236,6 @@ function applyProgressIndicatorWidth(
   return changed ? out : null;
 }
 
-/**
- * Resolve a shadcn Slider's `defaultValue` (or `value`) into an array of
- * percent positions. shadcn / base-ui accepts a number for single-thumb
- * and a tuple for range. The scanner preserves both shapes verbatim,
- * but for safety we also handle stringified forms ("[25, 75]" or "50").
- */
-function resolveSliderValues(rawValue: unknown, rawMax: unknown): number[] {
-  const maxRaw =
-    typeof rawMax === 'number' ? rawMax
-    : typeof rawMax === 'string' && rawMax.trim().length > 0 ? parseFloat(rawMax)
-    : 100;
-  const max = Number.isFinite(maxRaw) && maxRaw > 0 ? maxRaw : 100;
-  const toPct = (v: number): number => Math.max(0, Math.min(100, (v / max) * 100));
-
-  if (Array.isArray(rawValue)) {
-    const nums: number[] = [];
-    for (const v of rawValue) {
-      const n = typeof v === 'number' ? v : typeof v === 'string' ? parseFloat(v) : NaN;
-      if (Number.isFinite(n)) nums.push(toPct(n));
-    }
-    if (nums.length > 0) return nums;
-  }
-  if (typeof rawValue === 'number' && Number.isFinite(rawValue)) {
-    return [toPct(rawValue)];
-  }
-  if (typeof rawValue === 'string') {
-    const trimmed = rawValue.trim();
-    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
-      try {
-        const parsed = JSON.parse(trimmed);
-        if (Array.isArray(parsed)) {
-          const nums = parsed
-            .map((v) => (typeof v === 'number' ? v : parseFloat(String(v))))
-            .filter((v: number) => Number.isFinite(v))
-            .map(toPct);
-          if (nums.length > 0) return nums;
-        }
-      } catch (_e) { /* not valid JSON — fall through */ }
-    }
-    const num = parseFloat(trimmed);
-    if (Number.isFinite(num)) return [toPct(num)];
-  }
-  return [0];
-}
-
 /**
  * Walk the Slider subtree and rebuild it so the indicator + thumbs
  * reflect the value prop:
@@ -322,7 +257,8 @@ function applySliderPositioning(
   if (getDataSlot(root) !== 'slider') return null;
   const rawValue = root.props && (root.props.defaultValue ?? root.props.value);
   const rawMax = root.props ? root.props.max : undefined;
-  const pcts = resolveSliderValues(rawValue, rawMax);
+  // base-ui's Slider is min=0..max only; pass min=0 explicitly.
+  const pcts = resolveValuePercents(rawValue, 0, rawMax);
   if (pcts.length === 0) return null;
 
   // Figma plugin sandbox doesn't support spread (`...arr`); compute min/max
@@ -433,6 +369,74 @@ function applySliderPositioning(
   return touched ? single : null;
 }
 
+/**
+ * Drop Radix ScrollArea control children AND flatten the Viewport
+ * wrapper. Two operations rolled into one pass because they target
+ * sibling positions inside the same ScrollAreaPrimitive.Root subtree.
+ *
+ * 1. `ScrollAreaPrimitive.Scrollbar` / `.Thumb` / `.Corner` are
+ *    runtime-only behavioural overlays (scrollbar fades in while the
+ *    user scrolls, Corner only appears when both axes overflow). In a
+ *    static design-system render they manifest as visible content
+ *    blobs inside the scroll-area. Strip them.
+ *
+ * 2. `ScrollAreaPrimitive.Viewport` is a structural wrapper Radix
+ *    uses for `overflow: hidden` + scroll-position tracking — it
+ *    carries no visual styling beyond `h-full w-full
+ *    rounded-[inherit]`. In Figma the default frame fill (white)
+ *    paints it as a second nested rounded rectangle, producing the
+ *    "double card / ghost-border" effect the user reported. Flatten
+ *    by pulling Viewport's children up to be Root's direct children.
+ *
+ * Returns the rewritten children array when something changed, `null`
+ * when the subtree was untouched (so callers can keep object identity
+ * stable for caching).
+ */
+const RADIX_SCROLL_AREA_RUNTIME_TAGS = new Set([
+  'ScrollAreaPrimitive.Scrollbar',
+  'ScrollAreaPrimitive.Thumb',
+  'ScrollAreaPrimitive.Corner',
+]);
+
+/**
+ * JSX-tree tags the shadcn adapter unconditionally drops at render time.
+ * Exposed so pre-render scans that walk classes (e.g. responsive-signal
+ * detection) can ignore classes that won't actually reach Figma — without
+ * this, a `sm:bg-black/60` on `ScrollAreaPrimitive.Scrollbar` falsely
+ * trips `treeHasResponsiveClasses` and emits a duplicate-content
+ * Responsive preview block even though every breakpoint render is
+ * identical post-adapter.
+ */
+export function isShadcnAdapterDroppedTag(tagName: string): boolean {
+  return RADIX_SCROLL_AREA_RUNTIME_TAGS.has(tagName);
+}
+function flattenScrollAreaSubtree(node: NodeIR): NodeIR[] | null {
+  if (!('children' in node) || !Array.isArray(node.children)) return null;
+  let changed = false;
+  const next: NodeIR[] = [];
+  for (const child of node.children) {
+    if (!isClassedElement(child)) {
+      next.push(child);
+      continue;
+    }
+    const tag = (child as { tagName?: string }).tagName;
+    if (typeof tag === 'string' && RADIX_SCROLL_AREA_RUNTIME_TAGS.has(tag)) {
+      changed = true;
+      continue;
+    }
+    if (tag === 'ScrollAreaPrimitive.Viewport') {
+      const viewportChildren = ('children' in child && Array.isArray(child.children))
+        ? child.children
+        : [];
+      for (const vc of viewportChildren) next.push(vc);
+      changed = true;
+      continue;
+    }
+    next.push(child);
+  }
+  return changed ? next : null;
+}
+
 /**
  * Recurse the IR, injecting registry classes for any element whose
  * `data-slot` matches a known shadcn pattern AND applying shadcn-specific
@@ -487,6 +491,18 @@ export function applyShadcnAdapter(node: NodeIR): NodeIR {
     }
   }
 
+  // Tree transform: Radix ScrollArea drops its Scrollbar / Thumb /
+  // Corner overlays (runtime-only behaviour, not visual content) AND
+  // flattens its Viewport wrapper (no visual styling of its own —
+  // Figma's default frame fill would render it as a ghost-bordered
+  // duplicate of Root).
+  if (isClassedElement(nextNode)) {
+    const filtered = flattenScrollAreaSubtree(nextNode);
+    if (filtered) {
+      nextNode = Object.assign({}, nextNode, { children: filtered });
+    }
+  }
+
   // Tree transform: shadcn Progress reads `value` on Root and (at
   // runtime) inline-styles the Indicator's transform/width. Inject a
   // `w-[N%]` class on the descendant indicator so the universal

package/src/layout/deferred-layout.ts

@@ -18,6 +18,7 @@ import {
   hasResponsiveVariant as hasResponsiveVariantSemantic,
   variantState as variantStateSemantic,
 } from '../tailwind';
+import type { RingInfo } from './ring-utils';
 
 // ---------------------------------------------------------------------------
 // State stores
@@ -67,6 +68,13 @@ const MAX_WIDTH_NODES = new WeakMap<SceneNode, number>(); // child → max-width
 const DEFERRED_CENTER_Y_NODES = new WeakSet<SceneNode>(); // absolute children needing cross-axis centering
 const ASPECT_RATIO_NODES = new WeakMap<SceneNode, number>(); // node → width/height ratio (e.g. 5/3 for aspect-5/3)
 const BORDER_WIDTH_CLASSES = new WeakMap<SceneNode, string[]>();
+// Ring overlays (Tailwind `ring-*`). Eagerly creating the overlay during
+// frame construction inflates Hug-sized parents during the brief flex-child
+// moment between `appendChild` and `layoutPositioning = 'ABSOLUTE'`. Marking
+// at parse time and applying at post-pass time (when the host has all its
+// content children and we can lock its sizing modes) makes the inflation
+// class impossible. See `applyRingIfPossible` below.
+const RING_NODES = new WeakMap<SceneNode, RingInfo>();
 // SVG icon wraps whose inner SVG vectors must be rescaled when the wrap
 // itself resizes (e.g. an inline `<svg className="absolute inset-0 h-full
 // w-full">` overlay that originally got a 24×24 default size from
@@ -104,6 +112,35 @@ export function markAbsoluteNode(node: SceneNode): void {
   ABSOLUTE_NODES.add(node);
 }
 
+/**
+ * Mark a node as needing a Tailwind `ring-*` overlay. The actual overlay
+ * frame is created later by `applyRingIfPossible` once the host's content
+ * children are all in place — that's the only moment when we can lock the
+ * host's sizing modes briefly without truncating its natural size.
+ *
+ * The mark is per-node and idempotent — repeated calls overwrite the prior
+ * `RingInfo`, which matches how Tailwind's class cascade works (the last
+ * `ring-*` utility in the class list wins).
+ */
+export function markRingNode(node: SceneNode, ring: RingInfo): void {
+  RING_NODES.set(node, ring);
+}
+
+export function hasRingNode(node: SceneNode): boolean {
+  return RING_NODES.has(node);
+}
+
+/**
+ * Read the ring mark off a node. Used to bridge node-identity transitions
+ * — e.g. `figma.createComponentFromNode(sourceNode)` creates a new node
+ * identity, so the WeakMap entry keyed on `sourceNode` becomes unreachable
+ * from the resulting component. Callers read the mark with `getRingNode`
+ * before the transition and re-set it on the new node with `markRingNode`.
+ */
+export function getRingNode(node: SceneNode): RingInfo | undefined {
+  return RING_NODES.get(node);
+}
+
 /**
  * Lock a frame's aspect ratio (`aspect-5/3`, `aspect-square`, `aspect-[3/4]`).
  * The ratio is `width / height`. Resolved by `applyAspectRatioIfPossible`
@@ -296,6 +333,132 @@ function reapplyDirectionalBordersIfNeeded(node: SceneNode): void {
 // Apply functions — resolve intent after a node is appended to its parent
 // ---------------------------------------------------------------------------
 
+/**
+ * Resolve a marked ring overlay on this host. Called from the post-append
+ * pipeline (after `applyAbsoluteIfPossible` / `applyFullWidthIfPossible`)
+ * when the host's content children are all in place and its natural W × H
+ * is settled.
+ *
+ * The architecturally important step is **briefly switching the host's
+ * auto-layout sizing modes to FIXED** at the host's current dimensions
+ * before appending the overlay. The Figma sandbox requires
+ * `appendChild` before `layoutPositioning = 'ABSOLUTE'`, so the overlay
+ * unavoidably participates in the host's auto-layout for a moment. With
+ * the host locked to FIXED, that moment cannot inflate the host — the
+ * sizing is no longer derived from children. After the overlay is marked
+ * ABSOLUTE, the host's sizing modes are restored to AUTO; the host then
+ * re-measures from its non-absolute children only, returning to its
+ * natural size with no drift.
+ *
+ * Ring geometry: overlay matches the host's W × H exactly, with
+ * `strokeAlign: 'OUTSIDE'` so the ring paints past the geometric edge
+ * (matching CSS `box-shadow: 0 0 0 N <color>` — see the "DO NOT use
+ * Figma DROP_SHADOW spread parameter" entry in `.ai/troubleshooting.md`
+ * for why `spread`-based effects fail on transparent frames).
+ *
+ * `parent` is accepted for API symmetry with the other `apply*IfPossible`
+ * functions; it isn't used directly. The host's `clipsContent` IS toggled
+ * off so the OUTSIDE stroke isn't clipped.
+ */
+export function applyRingIfPossible(host: SceneNode, _parent: FrameNode): void {
+  const ring = RING_NODES.get(host);
+  if (!ring) return;
+  if (!('layoutMode' in host) || !('resize' in host) || !('appendChild' in host)) {
+    RING_NODES.delete(host);
+    return;
+  }
+  const hostFrame = host as FrameNode;
+  const width = typeof hostFrame.width === 'number' ? hostFrame.width : 0;
+  const height = typeof hostFrame.height === 'number' ? hostFrame.height : 0;
+  if (!(width > 0) || !(height > 0)) {
+    // Host has no usable dimensions yet — leave the mark in place so a later
+    // reflow pass (after width-solver, aspect-ratio resolution, etc.) can
+    // retry. Idempotent: re-running applyRingIfPossible after dimensions
+    // settle picks up where we left off.
+    return;
+  }
+
+  // Remove any stale overlay from a previous pass (e.g. when the State Matrix
+  // re-renders a component master).
+  const children = hostFrame.children;
+  if (Array.isArray(children) && children.length > 0) {
+    for (let i = children.length - 1; i >= 0; i--) {
+      const child = children[i];
+      if (!child || child.name !== '__inkbridge-ring__') continue;
+      try { child.remove(); } catch (_e) { /* ignore */ }
+    }
+  }
+
+  const originalPrimary = hostFrame.primaryAxisSizingMode;
+  const originalCounter = hostFrame.counterAxisSizingMode;
+  const primaryWasAuto = originalPrimary === 'AUTO';
+  const counterWasAuto = originalCounter === 'AUTO';
+
+  // Lock host at current dimensions so the brief flex-child moment of the
+  // overlay's appendChild can't grow the host. This is the invariant that
+  // makes the inflation class impossible.
+  try {
+    if (primaryWasAuto) hostFrame.primaryAxisSizingMode = 'FIXED';
+    if (counterWasAuto) hostFrame.counterAxisSizingMode = 'FIXED';
+    hostFrame.resize(width, height);
+  } catch (_e) { /* ignore */ }
+
+  const overlay = figma.createFrame();
+  overlay.name = '__inkbridge-ring__';
+  overlay.resize(width, height);
+  overlay.fills = [];
+  overlay.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,
+  }];
+  overlay.strokeWeight = ring.width;
+  try { overlay.strokeAlign = 'OUTSIDE'; } catch (_e) { /* ignore */ }
+  try {
+    (overlay as { strokesIncludedInLayout?: boolean }).strokesIncludedInLayout = false;
+  } catch (_e) { /* ignore */ }
+
+  // Mirror host corner radii — OUTSIDE stroke extends the visible perimeter
+  // outward automatically, no `+ ringWidth` arithmetic needed.
+  const nodeRadius = hostFrame.cornerRadius;
+  if (typeof nodeRadius === 'number') {
+    overlay.cornerRadius = nodeRadius;
+  } else {
+    const tl = typeof hostFrame.topLeftRadius === 'number' ? hostFrame.topLeftRadius : null;
+    const tr = typeof hostFrame.topRightRadius === 'number' ? hostFrame.topRightRadius : null;
+    const br = typeof hostFrame.bottomRightRadius === 'number' ? hostFrame.bottomRightRadius : null;
+    const bl = typeof hostFrame.bottomLeftRadius === 'number' ? hostFrame.bottomLeftRadius : null;
+    if (tl != null && tr != null && br != null && bl != null) {
+      overlay.topLeftRadius = tl;
+      overlay.topRightRadius = tr;
+      overlay.bottomRightRadius = br;
+      overlay.bottomLeftRadius = bl;
+    }
+  }
+
+  try { hostFrame.appendChild(overlay); } catch (_e) { /* ignore */ }
+  try { overlay.layoutPositioning = 'ABSOLUTE'; } catch (_e) { /* ignore */ }
+  overlay.x = 0;
+  overlay.y = 0;
+  try { hostFrame.clipsContent = false; } catch (_e) { /* ignore */ }
+  // Z-order: overlay sits in front of host's content children (last in
+  // `children` array) — exactly what CSS box-shadow does (rendered on top
+  // of the host's content along the stroke band).
+
+  // Restore the host's original sizing modes. The overlay is now ABSOLUTE
+  // and excluded from the host's flow, so AUTO sizing recomputes from the
+  // host's content children only (returning to the natural size).
+  try {
+    if (primaryWasAuto) hostFrame.primaryAxisSizingMode = 'AUTO';
+    if (counterWasAuto) hostFrame.counterAxisSizingMode = 'AUTO';
+  } catch (_e) { /* ignore */ }
+
+  // Keep the mark in `RING_NODES` so reflow passes (e.g. after
+  // `applyFullWidthIfPossible` resizes the host) can re-run this function
+  // idempotently — the stale-overlay-removal step at the top of this
+  // function makes re-application safe.
+}
+
 export function applyAbsoluteIfPossible(child: SceneNode, parent: FrameNode): void {
   if (!ABSOLUTE_NODES.has(child)) return;
   const parentIsAutoLayout = 'layoutMode' in parent && parent.layoutMode && parent.layoutMode !== 'NONE';
@@ -645,6 +808,8 @@ export function reflowDeferredAbsolutePositioningTree(root: SceneNode): void {
         for (const child of rootFrame.children) {
           if (!FULL_WIDTH_NODES.has(child) && !FULL_HEIGHT_NODES.has(child)) continue;
           applyFullWidthIfPossible(child, rootFrame);
+          // Re-sync any ring overlay to the child's new width/height.
+          applyRingIfPossible(child, rootFrame);
           // Standard `applyFullWidthIfPossible` for a non-absolute child in
           // a VERTICAL parent uses `layoutAlign='STRETCH'` + `layoutGrow=1`,
           // which Figma resolves asynchronously and doesn't trigger our
@@ -706,6 +871,20 @@ export function applyFullWidthIfPossible(
         try { child.layoutAlign = align; } catch (_err) { /* ignore */ }
       }
     } else {
+      // `ml-auto` on a horizontal-flex child means "push me along the primary
+      // axis" in CSS. The child-level MAX mark alone can't express that — the
+      // Figma equivalent is the parent flipping to SPACE_BETWEEN so the child
+      // anchors to the end while siblings stay at MIN. Only promote when the
+      // parent's primary alignment is still the default MIN (consumer didn't
+      // set justify-*) and the parent has at least two children to space out.
+      if (
+        align === 'MAX'
+        && parent.layoutMode === 'HORIZONTAL'
+        && parent.primaryAxisAlignItems === 'MIN'
+        && parent.children.length >= 2
+      ) {
+        try { parent.primaryAxisAlignItems = 'SPACE_BETWEEN'; } catch (_err) { /* ignore */ }
+      }
       // MIN / CENTER / MAX: avoid forcing HUG when an explicit width utility exists.
       // Otherwise classes like w-9 can be collapsed back to content width.
       if (hasMarkedFixedWidth) {
@@ -1113,7 +1292,14 @@ export function applyGridColumnsIfPossible(
   colsOverride?: number
 ): void {
   const cols = colsOverride != null ? colsOverride : GRID_COLUMNS_NODES.get(frame);
-  if (!cols || cols <= 0) return;
+  // A single-column grid (`grid` with no `grid-cols-N`, or an explicit
+  // `grid-cols-1`) is CSS-semantically a vertical stack. Flipping to
+  // HORIZONTAL + WRAP for it produces a one-row layout that
+  // Hug-grows along its counter axis to the sum of children — exactly
+  // the bench-renders-horizontal bug that recurred at multiple call
+  // sites until the guard moved here. Single source of truth: callers
+  // can forward whatever `cols` they extracted and rely on this gate.
+  if (!cols || cols <= 1) return;
   if (colsOverride != null) {
     GRID_COLUMNS_NODES.set(frame, cols);
   }

package/src/layout/layout-utils.ts

@@ -1,4 +1,4 @@
-import { applyAspectRatioIfPossible, applyFullWidthIfPossible, applyGridColumnsIfPossible, getGridColumnsNode, hasGridColumnsNode, getColSpanNode, markFullWidthNode } from './deferred-layout';
+import { applyAspectRatioIfPossible, applyFullWidthIfPossible, applyRingIfPossible, applyGridColumnsIfPossible, getGridColumnsNode, hasGridColumnsNode, getColSpanNode, markFullWidthNode } from './deferred-layout';
 import { getBaseClass } from '../tailwind';
 
 export type LayoutWrapContext = {
@@ -43,6 +43,7 @@ function reflowFullWidthInSubtree(parent: FrameNode): void {
 
   for (const child of parent.children) {
     applyFullWidthIfPossible(child, parent, options);
+    applyRingIfPossible(child, parent);
     applyAspectRatioIfPossible(child);
     if ('layoutMode' in child) {
       const childFrame = child as FrameNode;