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

package/src/layout/deferred-layout.ts

@@ -0,0 +1,1556 @@
+/**
+ * deferred-layout.ts — Post-render deferred layout state machine
+ *
+ * Figma nodes are created and styled before they are appended to their parent,
+ * so many sizing/alignment decisions cannot be made at creation time. This module
+ * owns the full lifecycle of those deferred decisions:
+ *
+ *   1. mark*   — called during node creation to record intent
+ *   2. apply*  — called after a node is appended to its parent to resolve intent
+ *   3. reflow* — called after the full tree is built to fix up any remaining drift
+ *
+ * All state lives in module-level WeakSets/WeakMaps keyed on SceneNode, so nodes
+ * are automatically garbage-collected and there is no cleanup burden on callers.
+ */
+
+import {
+  parseUtilityClass,
+  hasResponsiveVariant as hasResponsiveVariantSemantic,
+  variantState as variantStateSemantic,
+} from '../tailwind';
+import type { RingInfo } from './ring-utils';
+
+// ---------------------------------------------------------------------------
+// State stores
+// ---------------------------------------------------------------------------
+
+const ABSOLUTE_NODES = new WeakSet<SceneNode>();
+const CSS_GRID_VERTICAL_FRAMES = new WeakSet<SceneNode>(); // grid without grid-cols-N → single-column, children stretch
+const FULL_WIDTH_NODES = new WeakSet<SceneNode>();
+const FULL_HEIGHT_NODES = new WeakSet<SceneNode>();
+const FIXED_HEIGHT_NODES = new WeakSet<SceneNode>();
+const FRACTION_WIDTH_NODES = new WeakMap<SceneNode, number>();
+const FIXED_WIDTH_NODES = new WeakSet<SceneNode>();
+const SELF_ALIGNMENT_NODES = new WeakMap<SceneNode, 'MIN' | 'CENTER' | 'MAX' | 'STRETCH'>();
+const FLEX_BASIS_NODES = new WeakMap<SceneNode, number>();
+const MIN_WIDTH_NODES = new WeakMap<SceneNode, number>();
+const GRID_COLUMNS_NODES = new WeakMap<SceneNode, number>();
+const COL_SPAN_NODES = new WeakMap<SceneNode, number>(); // child → number of columns spanned
+type PositionInfo = {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+  // Percentage-based positions (fractions in [0, 1]). Resolved against the
+  // parent's final dimensions in `applyDeferredPercentPositioning`. Stored
+  // separately because they can't be evaluated until the parent's width and
+  // height are settled (after `applyAspectRatioIfPossible` and friends).
+  topPercent?: number;
+  bottomPercent?: number;
+  leftPercent?: number;
+  rightPercent?: number;
+  // Self-translate fractions of the child's own width/height — `translate-x-1/2`
+  // = 0.5, `-translate-x-1/2` = -0.5, `-translate-x-full` = -1. Applied
+  // alongside percent positions to mirror CSS `transform: translate(N%, N%)`
+  // on absolute elements. Without this, an icon meant to be centered on
+  // `(left-50%, top-50%)` via `-translate-x-1/2 -translate-y-1/2` ends up
+  // anchored top-left at the percent point instead.
+  translateXFraction?: number;
+  translateYFraction?: number;
+  hintParentHeight?: number;
+  inset?: number;
+};
+const POSITION_INFO_NODES = new WeakMap<SceneNode, PositionInfo>();
+const DEFERRED_BOTTOM_NODES = new WeakMap<SceneNode, number>(); // child → bottom pixel offset
+const DEFERRED_RIGHT_NODES = new WeakMap<SceneNode, number>(); // child → right pixel offset
+const DEFERRED_TOP_RELATIVE_NODES = new WeakMap<SceneNode, number>(); // child → (parentHeight - N) top offset
+const MAX_WIDTH_NODES = new WeakMap<SceneNode, number>(); // child → max-width constraint from max-w-* classes
+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
+// `resolveIconSizeFromClasses`). The callback is registered by the
+// icon-rendering layer with a closure over `resizeSvgNodeTo`, so this
+// module doesn't depend on `effects/icon-builder`.
+const SVG_CONTENT_RESIZE_HOOKS = new WeakMap<SceneNode, (width: number, height: number) => void>();
+
+export function markSvgContentWrap(
+  wrap: SceneNode,
+  resize: (width: number, height: number) => void
+): void {
+  SVG_CONTENT_RESIZE_HOOKS.set(wrap, resize);
+}
+
+function resizeSvgContentIfMarked(wrap: SceneNode, width: number, height: number): void {
+  const hook = SVG_CONTENT_RESIZE_HOOKS.get(wrap);
+  if (!hook) return;
+  try {
+    hook(width, height);
+  } catch (_e) {
+    // ignore
+  }
+}
+
+function isSvgContentWrap(node: SceneNode): boolean {
+  return SVG_CONTENT_RESIZE_HOOKS.has(node);
+}
+
+// ---------------------------------------------------------------------------
+// Mark functions — record intent at node-creation time
+// ---------------------------------------------------------------------------
+
+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`
+ * once the frame's width is settled (after `w-full` / `max-w-*` resolve).
+ */
+export function markAspectRatio(node: SceneNode, ratio: number): void {
+  if (!Number.isFinite(ratio) || ratio <= 0) return;
+  ASPECT_RATIO_NODES.set(node, ratio);
+}
+
+export function hasAspectRatio(node: SceneNode): boolean {
+  return ASPECT_RATIO_NODES.has(node);
+}
+
+export function markPositionInfo(node: SceneNode, info: PositionInfo): void {
+  const existing = POSITION_INFO_NODES.get(node) || {};
+  POSITION_INFO_NODES.set(node, { ...existing, ...info });
+}
+
+export function markFullWidthNode(node: SceneNode): void {
+  FULL_WIDTH_NODES.add(node);
+}
+
+function markFullHeightNode(node: SceneNode): void {
+  FULL_HEIGHT_NODES.add(node);
+}
+
+function markFixedHeightNode(node: SceneNode): void {
+  FIXED_HEIGHT_NODES.add(node);
+}
+
+function markFixedWidthNode(node: SceneNode): void {
+  FIXED_WIDTH_NODES.add(node);
+}
+
+function markSelfAlignmentNode(node: SceneNode, align: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH'): void {
+  SELF_ALIGNMENT_NODES.set(node, align);
+}
+
+function markFlexBasisNode(node: SceneNode, basis: number): void {
+  if (!Number.isFinite(basis)) return;
+  FLEX_BASIS_NODES.set(node, basis);
+}
+
+function markMinWidthNode(node: SceneNode, minWidth: number): void {
+  if (!Number.isFinite(minWidth)) return;
+  MIN_WIDTH_NODES.set(node, minWidth);
+}
+
+function markMaxWidthNode(node: SceneNode, maxWidth: number): void {
+  if (!Number.isFinite(maxWidth)) return;
+  MAX_WIDTH_NODES.set(node, maxWidth);
+}
+
+function markGridColumnsNode(node: SceneNode, cols: number): void {
+  if (!Number.isFinite(cols) || cols <= 0) return;
+  GRID_COLUMNS_NODES.set(node, cols);
+}
+
+function markColSpanNode(node: SceneNode, span: number): void {
+  if (!Number.isFinite(span) || span <= 0) return;
+  COL_SPAN_NODES.set(node, span);
+}
+
+export function getColSpanNode(node: SceneNode): number {
+  return COL_SPAN_NODES.get(node) ?? 1;
+}
+
+function markFractionWidthNode(node: SceneNode, fraction: number): void {
+  if (!Number.isFinite(fraction) || fraction <= 0) return;
+  FRACTION_WIDTH_NODES.set(node, fraction);
+}
+
+// Re-exported so tailwind.ts can mark CSS_GRID_VERTICAL_FRAMES (which stays private here)
+export function markCssGridVerticalFrame(node: SceneNode): void {
+  CSS_GRID_VERTICAL_FRAMES.add(node);
+}
+
+// ---------------------------------------------------------------------------
+// State variant helpers (used by applyBorderWidthUtilities)
+// ---------------------------------------------------------------------------
+
+const STATE_VARIANTS = new Set([
+  'hover',
+  'focus',
+  'focus-visible',
+  'disabled',
+  'active',
+  'aria-invalid',
+]);
+
+function isStateVariant(variant: string): boolean {
+  if (STATE_VARIANTS.has(variant)) return true;
+  return variant.startsWith('data-[state=');
+}
+
+export function shouldApplyAtom(atom: ReturnType<typeof parseUtilityClass>, state: string): boolean {
+  if (hasResponsiveVariantSemantic(atom.variants)) return false;
+  if (state === 'default') return atom.variants.length === 0;
+  if (!atom.variants.length) return false;
+  if (!atom.variants.every(isStateVariant)) return false;
+  return variantStateSemantic(atom.variants) === state;
+}
+
+// ---------------------------------------------------------------------------
+// Fraction helpers
+// ---------------------------------------------------------------------------
+
+function parseFractionToken(token: string): number | null {
+  if (!token.includes('/')) return null;
+  const [rawNum, rawDen] = token.split('/');
+  const num = Number(rawNum);
+  const den = Number(rawDen);
+  if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0) return null;
+  return num / den;
+}
+
+// ---------------------------------------------------------------------------
+// Border width utilities
+// ---------------------------------------------------------------------------
+
+
+function setBorderSideWeights(frame: FrameNode, sides: { top: number; right: number; bottom: number; left: number }): void {
+  frame.strokeTopWeight = sides.top;
+  frame.strokeRightWeight = sides.right;
+  frame.strokeBottomWeight = sides.bottom;
+  frame.strokeLeftWeight = sides.left;
+  // Do not write strokeWeight: in Figma this can normalize all sides and undo
+  // directional borders (e.g. border-t becoming full box).
+}
+
+
+export function applyBorderWidthUtilities(frame: FrameNode, classes: string[]): void {
+  let touched = false;
+  let next = { top: 0, right: 0, bottom: 0, left: 0 };
+  for (const cls of classes) {
+    const atom = parseUtilityClass(cls);
+    if (!atom.utility) continue;
+    if (!shouldApplyAtom(atom, 'default')) continue;
+
+    const utility = atom.utility;
+    if (utility === 'border') {
+      next = { top: 1, right: 1, bottom: 1, left: 1 };
+      touched = true;
+      continue;
+    }
+    const borderWidthMatch = utility.match(/^border-(\d+)$/);
+    if (borderWidthMatch) {
+      const weight = parseFloat(borderWidthMatch[1]);
+      if (Number.isFinite(weight) && weight >= 0) {
+        next = { top: weight, right: weight, bottom: weight, left: weight };
+        touched = true;
+      }
+      continue;
+    }
+    if (utility === 'border-t') { next.top = 1; touched = true; continue; }
+    if (utility === 'border-r') { next.right = 1; touched = true; continue; }
+    if (utility === 'border-b') { next.bottom = 1; touched = true; continue; }
+    if (utility === 'border-l') { next.left = 1; touched = true; continue; }
+    if (utility === 'border-x') { next.left = 1; next.right = 1; touched = true; continue; }
+    if (utility === 'border-y') { next.top = 1; next.bottom = 1; touched = true; continue; }
+    const directionalBorderWidthMatch = utility.match(/^(border-(?:t|r|b|l|x|y))-(\d+)$/);
+    if (directionalBorderWidthMatch) {
+      const borderWeight = parseFloat(directionalBorderWidthMatch[2]);
+      if (!Number.isFinite(borderWeight) || borderWeight < 0) continue;
+      const directionalUtility = directionalBorderWidthMatch[1];
+      if (directionalUtility === 'border-t') next.top = borderWeight;
+      else if (directionalUtility === 'border-r') next.right = borderWeight;
+      else if (directionalUtility === 'border-b') next.bottom = borderWeight;
+      else if (directionalUtility === 'border-l') next.left = borderWeight;
+      else if (directionalUtility === 'border-x') { next.left = borderWeight; next.right = borderWeight; }
+      else if (directionalUtility === 'border-y') { next.top = borderWeight; next.bottom = borderWeight; }
+      touched = true;
+      continue;
+    }
+  }
+  if (touched) {
+    setBorderSideWeights(frame, next);
+  }
+}
+
+function reapplyDirectionalBordersIfNeeded(node: SceneNode): void {
+  const classes = BORDER_WIDTH_CLASSES.get(node);
+  if (!classes || classes.length === 0) return;
+  if (!('strokes' in node)) return;
+  applyBorderWidthUtilities(node as FrameNode, classes);
+}
+
+// ---------------------------------------------------------------------------
+// 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';
+  try {
+    if (parentIsAutoLayout && 'layoutPositioning' in child) {
+      child.layoutPositioning = 'ABSOLUTE';
+    }
+    // Match CSS stacking: a `position: absolute` child renders ABOVE its
+    // non-positioned siblings in the same stacking context. Figma's
+    // z-order is the parent.children array index (back-to-front), so we
+    // re-append the child to push it to the top. This is what makes a
+    // shadcn Avatar.Image overlay its Fallback instead of being hidden
+    // behind it.
+    try { parent.appendChild(child); } catch (_zerr) { /* ignore */ }
+
+    // Apply positioning from stored position info
+    const posInfo = POSITION_INFO_NODES.get(child);
+    if (posInfo) {
+      // If the child hints a minimum parent height (e.g. gradient-blob inside collapsed container)
+      if (posInfo.hintParentHeight != null && 'resize' in parent) {
+        try {
+          const ph = posInfo.hintParentHeight;
+          const pw = Math.max(1, parent.width);
+          // Respect explicit fixed-height parents. Only auto-expand when the
+          // parent is effectively unconstrained/collapsed.
+          let heightIsFixed = false;
+          if ('layoutMode' in parent && 'primaryAxisSizingMode' in parent && 'counterAxisSizingMode' in parent) {
+            if (parent.layoutMode === 'VERTICAL') {
+              heightIsFixed = parent.primaryAxisSizingMode === 'FIXED';
+            } else if (parent.layoutMode === 'HORIZONTAL') {
+              heightIsFixed = parent.counterAxisSizingMode === 'FIXED';
+            }
+          }
+          const parentCollapsed = parent.height <= 1;
+          if (!heightIsFixed && parentCollapsed && parent.height < ph) {
+            parent.resize(pw, ph);
+            if ('primaryAxisSizingMode' in parent) parent.primaryAxisSizingMode = 'FIXED';
+          }
+        } catch (_e) { /* ignore */ }
+      }
+      if ('x' in child && 'y' in child) {
+        const childFrame = child as FrameNode;
+        // inset-{n}: position at (n, n) and resize to fill parent minus inset on all sides
+        if (posInfo.inset != null) {
+          const inset = posInfo.inset;
+          childFrame.x = inset;
+          childFrame.y = inset;
+          const targetW = Math.max(1, parent.width - inset * 2);
+          const targetH = Math.max(1, parent.height - inset * 2);
+          try {
+            childFrame.resize(targetW, targetH);
+            if ('primaryAxisSizingMode' in childFrame) childFrame.primaryAxisSizingMode = 'FIXED';
+            if ('counterAxisSizingMode' in childFrame) childFrame.counterAxisSizingMode = 'FIXED';
+          } catch (_e) { /* ignore */ }
+        } else {
+          if (posInfo.left != null) {
+            childFrame.x = posInfo.left;
+          } else if (posInfo.right != null) {
+            // Defer right anchoring until parent width is final.
+            DEFERRED_RIGHT_NODES.set(child, posInfo.right);
+            childFrame.x = parent.width - childFrame.width - posInfo.right;
+          }
+          if (posInfo.top != null) {
+            childFrame.y = posInfo.top;
+          } else if (posInfo.bottom != null) {
+            // Defer: parent height may not be final yet (flow children added after this call)
+            DEFERRED_BOTTOM_NODES.set(child, posInfo.bottom);
+          } else if (posInfo.topPercent == null && posInfo.bottomPercent == null) {
+            // No explicit top/bottom and no percent — CSS places absolute children
+            // at the cross-axis static position. For items-center parents this means
+            // vertically centered.
+            if (parent.counterAxisAlignItems === 'CENTER') {
+              DEFERRED_CENTER_Y_NODES.add(child);
+            }
+          }
+        }
+      }
+    }
+  } catch (_err) {
+    // ignore
+  }
+  ABSOLUTE_NODES.delete(child);
+  // Retain percent fields AND translate fractions for the deferred percent
+  // resolver — they need the parent's FINAL width/height (which won't exist
+  // until aspect-ratio / full-width passes settle) and the child's own final
+  // width/height. Pixel fields are consumed; percent + translate stay.
+  const remaining = POSITION_INFO_NODES.get(child);
+  if (remaining && hasPercentPosition(remaining)) {
+    POSITION_INFO_NODES.set(child, {
+      topPercent: remaining.topPercent,
+      bottomPercent: remaining.bottomPercent,
+      leftPercent: remaining.leftPercent,
+      rightPercent: remaining.rightPercent,
+      translateXFraction: remaining.translateXFraction,
+      translateYFraction: remaining.translateYFraction,
+    });
+  } else {
+    POSITION_INFO_NODES.delete(child);
+  }
+}
+
+function hasPercentPosition(info: PositionInfo): boolean {
+  return info.topPercent != null
+    || info.bottomPercent != null
+    || info.leftPercent != null
+    || info.rightPercent != null;
+}
+
+/**
+ * Resolve any percent-based positions (`top-[X%]`, `left-[X%]`, etc.) on
+ * `parent`'s children against the parent's now-final dimensions. Should be
+ * called after `applyAspectRatioIfPossible(parent)` and the full-width pass
+ * — by that point `parent.width` and `parent.height` reflect the final size
+ * those percentages should resolve against.
+ *
+ * Mirrors CSS: `top: 30%` is `0.3 * containing-block-height`,
+ * `left: 50%` is `0.5 * containing-block-width`. `bottom: 70%` anchors the
+ * child's bottom edge at 70% from the parent's bottom (= 30% from top), so
+ * `child.y = parent.height * (1 - 0.7) - child.height`.
+ */
+export function applyDeferredPercentPositioning(parent: FrameNode): void {
+  if (!('children' in parent)) return;
+  const pw = parent.width;
+  const ph = parent.height;
+  if (!Number.isFinite(pw) || !Number.isFinite(ph) || pw <= 0 || ph <= 0) return;
+
+  for (const child of parent.children as SceneNode[]) {
+    const info = POSITION_INFO_NODES.get(child);
+    if (!info || !hasPercentPosition(info)) continue;
+    if (!('x' in child) || !('y' in child)) continue;
+    const childFrame = child as FrameNode;
+    const cw = Number.isFinite(childFrame.width) ? childFrame.width : 0;
+    const chh = Number.isFinite(childFrame.height) ? childFrame.height : 0;
+    try {
+      if (info.leftPercent != null) {
+        childFrame.x = pw * info.leftPercent;
+      } else if (info.rightPercent != null) {
+        childFrame.x = pw - cw - pw * info.rightPercent;
+      }
+      if (info.topPercent != null) {
+        childFrame.y = ph * info.topPercent;
+      } else if (info.bottomPercent != null) {
+        childFrame.y = ph - chh - ph * info.bottomPercent;
+      }
+      // Apply self-translate (CSS `transform: translate(N%, N%)`) — offset
+      // by the child's OWN width/height times the fraction. Most common
+      // case is `-translate-x-1/2 -translate-y-1/2` (center on point).
+      if (info.translateXFraction != null) {
+        childFrame.x += cw * info.translateXFraction;
+      }
+      if (info.translateYFraction != null) {
+        childFrame.y += chh * info.translateYFraction;
+      }
+    } catch (_e) {
+      // ignore
+    }
+    // Keep the mark — application is idempotent and the parent's dimensions
+    // may still change (aspect-ratio retry, w-full resolution, etc.). The
+    // final `reflowDeferredAbsolutePositioningTree` pass uses these marks to
+    // re-resolve positions against the parent's final size. Earlier this
+    // was deleted after use, which caused percent-positioned children to
+    // freeze at coordinates computed from intermediate parent dimensions
+    // (e.g. parent hugging to one child before aspect-ratio resolved).
+  }
+}
+
+/** Re-apply right-anchored x positions for children of a frame after its width changes. */
+export function reapplyRightPositionedChildren(frame: FrameNode, newWidth: number): void {
+  if (!('children' in frame)) return;
+  for (const child of (frame.children as SceneNode[])) {
+    const right = DEFERRED_RIGHT_NODES.get(child);
+    if (right != null) {
+      try {
+        child.x = newWidth - child.width - right;
+      } catch (_e) { /* ignore */ }
+    }
+  }
+}
+
+function reflowNestedFullWidthChildren(parent: FrameNode): void {
+  if (!parent || !('children' in parent)) return;
+  const padding = (parent.paddingLeft || 0) + (parent.paddingRight || 0);
+  const widthOverride = Number.isFinite(parent.width) ? Math.max(0, parent.width - padding) : null;
+  const options = widthOverride != null ? { widthOverride: widthOverride } : undefined;
+  for (const child of (parent.children as SceneNode[])) {
+    if ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE') continue;
+    applyFullWidthIfPossible(child, parent, options);
+    if ('layoutMode' in child) {
+      reflowNestedFullWidthChildren(child as FrameNode);
+    }
+  }
+}
+
+/** Call after all children have been appended to a frame to apply bottom-anchored positions. */
+export function applyDeferredBottomPositioning(parent: FrameNode): void {
+  for (const child of (parent.children as SceneNode[])) {
+    const right = DEFERRED_RIGHT_NODES.get(child);
+    if (right != null) {
+      try {
+        child.x = parent.width - child.width - right;
+      } catch (_e) { /* ignore */ }
+      // Do not delete — applyFullWidthIfPossible may recalculate after parent is resized.
+    }
+
+    const bottom = DEFERRED_BOTTOM_NODES.get(child);
+    if (bottom != null) {
+      try {
+        child.y = parent.height - child.height - bottom;
+      } catch (_e) { /* ignore */ }
+      DEFERRED_BOTTOM_NODES.delete(child);
+    }
+    // Handle top-[calc(100%-Nrem)]: top = parentHeight - N
+    const topRelative = DEFERRED_TOP_RELATIVE_NODES.get(child);
+    if (topRelative != null) {
+      try {
+        child.y = parent.height - topRelative;
+      } catch (_e) { /* ignore */ }
+      DEFERRED_TOP_RELATIVE_NODES.delete(child);
+    }
+  }
+}
+
+/** Call after all children have been appended to center absolute children with no explicit top/bottom. */
+export function applyDeferredCenterYPositioning(parent: FrameNode): void {
+  const parentHeight = parent.height;
+  if (parentHeight <= 0) return;
+  for (const child of (parent.children as SceneNode[])) {
+    if (DEFERRED_CENTER_Y_NODES.has(child)) {
+      try {
+        const childHeight = child.height || 0;
+        child.y = Math.round((parentHeight - childHeight) / 2);
+      } catch (_e) { /* ignore */ }
+      DEFERRED_CENTER_Y_NODES.delete(child);
+    }
+  }
+}
+
+/**
+ * Resolve a marked aspect ratio against the node's now-settled width.
+ * Caller is responsible for calling this AFTER any width-deciding pass
+ * (e.g. `applyFullWidthIfPossible`) so `child.width` reflects the final
+ * value. Computes `height = width / ratio`, resizes, and locks both
+ * sizing axes to FIXED so subsequent auto-layout passes don't collapse it.
+ *
+ * Mirrors CSS `aspect-ratio: <ratio>` semantics — if a `width` is set,
+ * the height is computed from the ratio; explicit `h-*` utilities will
+ * be overridden, which matches Tailwind's behaviour.
+ */
+export function applyAspectRatioIfPossible(child: SceneNode): void {
+  const ratio = ASPECT_RATIO_NODES.get(child);
+  if (ratio == null) return;
+  if (!('resize' in child) || !('width' in child)) return;
+  const w = (child as FrameNode).width;
+  if (!Number.isFinite(w) || w <= 0) return;
+  const h = w / ratio;
+  if (!Number.isFinite(h) || h <= 0) return;
+  try {
+    (child as FrameNode).resize(w, h);
+    if ('primaryAxisSizingMode' in child) {
+      (child as FrameNode).primaryAxisSizingMode = 'FIXED';
+    }
+    if ('counterAxisSizingMode' in child) {
+      (child as FrameNode).counterAxisSizingMode = 'FIXED';
+    }
+  } catch (_e) {
+    // ignore
+  }
+  ASPECT_RATIO_NODES.delete(child);
+}
+
+/**
+ * Re-apply deferred absolute positioning after the layout tree has settled.
+ * This is a post-pass used to avoid timing/order drift when parent widths/heights
+ * change after initial child construction.
+ *
+ * Aspect-ratio retry is part of this reflow: a frame like
+ * `<div className="aspect-5/3 w-full">` whose children are all absolute
+ * collapses to 0 height under hug-content layout. The earlier
+ * `applyAspectRatioIfPossible` pass may have run while `width` was still 0
+ * (mark retained for retry). Without re-attempting it here, the parent
+ * stays at 0 height and `applyDeferredPercentPositioning` bails — leaving
+ * every percent-positioned child stacked at y=0.
+ */
+export function reflowDeferredAbsolutePositioningTree(root: SceneNode): void {
+  if (!root) return;
+  if (!('children' in root)) return;
+  for (const child of root.children) {
+    reflowDeferredAbsolutePositioningTree(child);
+  }
+  if ('layoutMode' in root) {
+    try {
+      applyAspectRatioIfPossible(root as FrameNode);
+      const rootFrame = root as FrameNode;
+      // Detect "pure positioning container" — every child is absolute. In CSS
+      // such a parent's display mode is irrelevant (block / flex / grid all
+      // behave the same when children are out-of-flow). In Figma, leaving an
+      // auto-layout VERTICAL/HORIZONTAL mode on such a parent causes Figma to
+      // try to flow children and re-hug the parent height back to 0 even
+      // after `applyAspectRatioIfPossible` set FIXED sizing. Switch to NONE
+      // (freeform) so the aspect-ratio size sticks and percent positioning
+      // resolves against the real dimensions. Round-trip-section's triangle
+      // is the canonical case: `aspect-5/3 w-full` with one absolute SVG
+      // overlay + three absolute icon nodes.
+      if (
+        'children' in rootFrame
+        && rootFrame.children.length > 0
+        && rootFrame.layoutMode !== 'NONE'
+      ) {
+        let allAbs = true;
+        for (const child of rootFrame.children) {
+          const isAbs = ABSOLUTE_NODES.has(child)
+            || ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE');
+          if (!isAbs) {
+            allAbs = false;
+            break;
+          }
+        }
+        if (allAbs) {
+          try {
+            rootFrame.layoutMode = 'NONE';
+          } catch (_err) {
+            // ignore
+          }
+        }
+      }
+      // Re-apply fill-parent marks now that the parent dimensions are
+      // settled. Critical for two patterns:
+      //   1. SVG overlay `absolute inset-0 h-full w-full` inside an
+      //      `aspect-5/3` container — initial size was computed against
+      //      parent.height === 0.
+      //   2. Bridge SVG `width="100%" height="100%"` inside `aspect-6/1
+      //      w-full` — same timing issue; the child is a flow child but
+      //      the parent's aspect-ratio resolved AFTER the initial pass.
+      //
+      // SKIP for HORIZONTAL+WRAP parents — those are grid containers
+      // sized by `applyGridColumnsIfPossible`, where each child's width is
+      // the column width (not the full parent width). Re-running
+      // `applyFullWidthIfPossible` here would resize each `w-full` grid
+      // child to the FULL grid width, forcing each onto its own row
+      // (vertical stack instead of N-column grid). Canonical break:
+      // MediaCard Grid story with three `w-full` cards inside
+      // `grid-cols-3`.
+      const isGridWrap = rootFrame.layoutMode === 'HORIZONTAL'
+        && 'layoutWrap' in rootFrame
+        && rootFrame.layoutWrap === 'WRAP';
+      if ('children' in rootFrame && !isGridWrap) {
+        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
+          // `markSvgContentWrap` resize hook. Bridge SVG (`width="100%"
+          // height="100%"` inside an `aspect-6/1` wrapper) ends up with the
+          // wrap notionally sized but the inner SVG vectors still 24×24.
+          // Force a direct resize for SVG content wraps so the hook fires
+          // and the vectors scale with the wrap.
+          if (
+            isSvgContentWrap(child)
+            && 'resize' in child
+            && Number.isFinite(rootFrame.width)
+            && Number.isFinite(rootFrame.height)
+            && rootFrame.width > 0
+            && rootFrame.height > 0
+          ) {
+            try {
+              const padX = (rootFrame.paddingLeft || 0) + (rootFrame.paddingRight || 0);
+              const padY = (rootFrame.paddingTop || 0) + (rootFrame.paddingBottom || 0);
+              const targetW = FULL_WIDTH_NODES.has(child)
+                ? Math.max(1, rootFrame.width - padX)
+                : (child as FrameNode).width;
+              const targetH = FULL_HEIGHT_NODES.has(child)
+                ? Math.max(1, rootFrame.height - padY)
+                : (child as FrameNode).height;
+              child.resize(targetW, targetH);
+              resizeSvgContentIfMarked(child, targetW, targetH);
+            } catch (_err) {
+              // ignore
+            }
+          }
+        }
+      }
+      applyDeferredBottomPositioning(rootFrame);
+      applyDeferredCenterYPositioning(rootFrame);
+      applyDeferredPercentPositioning(rootFrame);
+    } catch (_e) {
+      // ignore
+    }
+  }
+}
+
+export function applyFullWidthIfPossible(
+  child: SceneNode,
+  parent: FrameNode,
+  options?: { skipFullWidth?: boolean; widthOverride?: number }
+): void {
+  const hasMarkedFixedWidth = FIXED_WIDTH_NODES.has(child);
+  const hasMarkedFractionWidth = FRACTION_WIDTH_NODES.get(child) != null;
+  const hasMarkedFullWidth = FULL_WIDTH_NODES.has(child);
+  const align = SELF_ALIGNMENT_NODES.get(child);
+  const hasSelfAlign = align != null;
+  // mx-auto + max-w: CENTER self-alignment combined with full-width mark means
+  // the element should be center-aligned and resized to its max-width constraint.
+  const isMxAutoFill = align === 'CENTER' && hasMarkedFullWidth;
+  if (align) {
+    if (align === 'STRETCH') {
+      if ('layoutAlign' in child) {
+        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) {
+        if ('layoutSizingHorizontal' in child) {
+          try { child.layoutSizingHorizontal = 'FIXED'; } catch (_err) { /* ignore if unsupported */ }
+        }
+      } else if (!hasMarkedFractionWidth && !hasMarkedFullWidth) {
+        // Best proxy for non-stretch self alignment when width is content-driven.
+        if ('layoutSizingHorizontal' in child) {
+          try { child.layoutSizingHorizontal = 'HUG'; } catch (_err) { /* ignore if unsupported */ }
+        }
+      }
+    }
+    SELF_ALIGNMENT_NODES.delete(child);
+  }
+
+  const basis = FLEX_BASIS_NODES.get(child);
+  if (basis != null && basis > 0 && 'resize' in child) {
+    try {
+      if (parent.layoutMode === 'HORIZONTAL') {
+        child.resize(basis, child.height);
+        if ('primaryAxisSizingMode' in child) child.primaryAxisSizingMode = 'FIXED';
+      } else if (parent.layoutMode === 'VERTICAL') {
+        child.resize(child.width, basis);
+        if ('primaryAxisSizingMode' in child) child.primaryAxisSizingMode = 'FIXED';
+      }
+    } catch (_err) {
+      // ignore
+    }
+  }
+  if (basis != null) {
+    FLEX_BASIS_NODES.delete(child);
+  }
+
+  const minWidth = MIN_WIDTH_NODES.get(child);
+  if (minWidth != null && 'resize' in child) {
+    const currentWidth = child.width as number;
+    if (!Number.isFinite(currentWidth) || currentWidth < minWidth) {
+      try {
+        child.resize(minWidth, child.height);
+        if (parent.layoutMode === 'HORIZONTAL' && 'primaryAxisSizingMode' in child) {
+          child.primaryAxisSizingMode = 'FIXED';
+        } else if (parent.layoutMode === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+          child.counterAxisSizingMode = 'FIXED';
+        }
+      } catch (_err) {
+        // ignore
+      }
+    }
+    MIN_WIDTH_NODES.delete(child);
+  }
+
+  const skipFullWidth = !!(options && options.skipFullWidth);
+  const rawWidthOverride = options && typeof options.widthOverride === 'number' && Number.isFinite(options.widthOverride)
+    ? options.widthOverride
+    : null;
+  // Bound inherited width overrides to the parent content box — but only when the parent
+  // has been explicitly sized (FIXED mode). Auto-sized frames (compFrame, wrapperFrame)
+  // may still be at their Figma default width before children are rendered and layout
+  // settles; bounding against that default would incorrectly clamp a correct narrow
+  // override (e.g. 320px viewport) down to the frame's unset default (~100px).
+  const parentIsFixedWidth =
+    parent.layoutMode === 'NONE'
+    || (parent.layoutMode === 'HORIZONTAL' && parent.primaryAxisSizingMode === 'FIXED')
+    || (parent.layoutMode === 'VERTICAL' && parent.counterAxisSizingMode === 'FIXED');
+  const parentPaddingX = (parent.paddingLeft || 0) + (parent.paddingRight || 0);
+  const parentContentWidth = Math.max(0, parent.width - parentPaddingX);
+  const widthOverride = rawWidthOverride != null && parentIsFixedWidth && parentContentWidth > 0
+    ? Math.min(rawWidthOverride, parentContentWidth)
+    : rawWidthOverride;
+  const widthBase = widthOverride != null ? widthOverride : parent.width;
+  // CSS grid (single-column) children stretch to fill the column by default (align-items: stretch).
+  // Don't stretch absolute-positioned children — they're handled separately.
+  const childIsAbsolutePositioned = ABSOLUTE_NODES.has(child)
+    || ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE');
+  const isGridStretchChild = !skipFullWidth
+    && CSS_GRID_VERTICAL_FRAMES.has(parent)
+    && !childIsAbsolutePositioned;
+  const hasFullWidth = skipFullWidth ? false : (hasMarkedFullWidth || isGridStretchChild);
+  const fractionWidth = skipFullWidth ? null : FRACTION_WIDTH_NODES.get(child);
+  const hasFixedWidth = hasMarkedFixedWidth;
+  const hasFullHeight = FULL_HEIGHT_NODES.has(child);
+  if (!hasFullWidth && fractionWidth == null && !hasFullHeight && !hasFixedWidth) return;
+  if (hasFixedWidth && parent.layoutMode === 'VERTICAL' && !hasSelfAlign && 'layoutAlign' in child) {
+    try {
+      child.layoutAlign = 'INHERIT';
+    } catch (_err) {
+      // ignore
+    }
+  }
+  try {
+    if (!hasFullWidth && fractionWidth != null && 'resize' in child && widthBase > 0) {
+      // widthOverride is already content-width; only subtract padding when using parent.width
+      const padding = widthOverride != null ? 0 : (parent.paddingLeft || 0) + (parent.paddingRight || 0);
+      const targetWidth = Math.max(0, widthBase - padding) * fractionWidth;
+      try {
+        child.resize(targetWidth, child.height);
+        // Prevent fractional width children from expanding
+        if ('layoutGrow' in child) {
+          child.layoutGrow = 0;
+        }
+        if (parent.layoutMode === 'VERTICAL' && !hasSelfAlign && 'layoutAlign' in child) {
+          child.layoutAlign = 'INHERIT';
+        }
+        // Set sizing mode to FIXED so the width is respected
+        if ('layoutMode' in child) {
+          const childLayout = child.layoutMode;
+          if (childLayout === 'HORIZONTAL' && 'primaryAxisSizingMode' in child) {
+            child.primaryAxisSizingMode = 'FIXED';
+          } else if (childLayout === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+            child.counterAxisSizingMode = 'FIXED';
+          }
+          reflowNestedFullWidthChildren(child as FrameNode);
+        } else if (parent.layoutMode === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+          // For non-layout children in vertical parent, fix the width
+          child.counterAxisSizingMode = 'FIXED';
+        }
+      } catch (_err) {
+        // ignore resize errors
+      }
+    }
+
+    if (hasFullWidth) {
+      if (parent.layoutMode === 'HORIZONTAL') {
+        // The synthetic mx-auto wrapper is HORIZONTAL with primaryAxisAlignItems='CENTER'.
+        // When its sole child has a max-w-* constraint, the child is pre-sized to its
+        // max-w and meant to sit centered inside the wrapper. Applying full-width here
+        // would stretch the child back to the wrapper width, defeating the centering.
+        // Without a max-w (e.g. `mx-auto w-full`), the child should still fill — fall
+        // through. The check is structural (parent.name and child's max-w mark) rather
+        // than relying on `isMxAutoFill`, because `SELF_ALIGNMENT_NODES.delete(child)`
+        // above nukes the CENTER mark after the first pass and subsequent calls from
+        // `reflowNestedFullWidthChildren` would otherwise bypass the guard.
+        if (parent.name === 'mx-auto' && MAX_WIDTH_NODES.has(child)) {
+          return;
+        }
+        // When parent uses SPACE_BETWEEN, don't apply layoutGrow=1 because that would
+        // make this child consume all space, leaving nothing for siblings.
+        // In CSS flexbox, width:100% with justify-content:space-between still spaces items at edges.
+        // In Figma, we need to explicitly set layoutGrow=0 and let SPACE_BETWEEN distribute items.
+        const isSpaceBetween = parent.primaryAxisAlignItems === 'SPACE_BETWEEN';
+        if (isSpaceBetween) {
+          // Explicitly set to 0 to prevent any expansion
+          if ('layoutGrow' in child) child.layoutGrow = 0;
+          // Also ensure the child sizes to its content, not to fill
+          if ('primaryAxisSizingMode' in child) {
+            child.primaryAxisSizingMode = 'AUTO';
+          }
+        } else {
+          if ('layoutGrow' in child) child.layoutGrow = 1;
+        }
+        if (
+          (('primaryAxisSizingMode' in parent && parent.primaryAxisSizingMode === 'FIXED') || widthOverride != null)
+          && 'resize' in child
+          && !isSpaceBetween
+          && widthBase > 0
+        ) {
+          try {
+            child.resize(widthBase, child.height);
+            if ('primaryAxisSizingMode' in child) {
+              child.primaryAxisSizingMode = 'FIXED';
+            }
+            reapplyRightPositionedChildren(child as FrameNode, widthBase);
+            if ('layoutMode' in child) {
+              reflowNestedFullWidthChildren(child as FrameNode);
+            }
+          } catch (_err) {
+            // ignore resize errors
+          }
+        }
+      } else if (
+        (childIsAbsolutePositioned || !('layoutMode' in parent) || parent.layoutMode === 'NONE')
+        && 'resize' in child
+        && Number.isFinite(parent.width)
+        && parent.width > 0
+      ) {
+        // Direct-resize path for either:
+        //   (a) parents with no auto-layout (positioning containers, e.g.
+        //       an `aspect-*` div or a `relative` overlay), or
+        //   (b) absolute-positioned children of an auto-layout parent
+        //       (e.g. `<svg className="absolute inset-0 h-full w-full">`
+        //       inside an `aspect-5/3` triangle frame). For absolute
+        //       children, `layoutAlign='STRETCH'` and `layoutGrow=1` are
+        //       no-ops — only direct resize works. Mirrors CSS
+        //       `width: 100%` semantics.
+        try {
+          const padding = (parent.paddingLeft || 0) + (parent.paddingRight || 0);
+          const rawTarget = Math.max(0, parent.width - padding);
+          const maxWConst = MAX_WIDTH_NODES.get(child);
+          const targetWidth = maxWConst != null ? Math.min(rawTarget, maxWConst) : rawTarget;
+          if (targetWidth > 0) {
+            child.resize(targetWidth, child.height);
+            resizeSvgContentIfMarked(child, targetWidth, child.height);
+            if ('primaryAxisSizingMode' in child) {
+              child.primaryAxisSizingMode = 'FIXED';
+            }
+            if ('counterAxisSizingMode' in child) {
+              child.counterAxisSizingMode = 'FIXED';
+            }
+          }
+        } catch (_err) {
+          // ignore
+        }
+      } else if (parent.layoutMode === 'VERTICAL') {
+        // If the child is HORIZONTAL with SPACE_BETWEEN and already has FIXED sizing,
+        // don't use STRETCH as it conflicts. Instead, keep the explicit FIXED width.
+        const childIsHorizontal = 'layoutMode' in child && child.layoutMode === 'HORIZONTAL';
+        const childHasSpaceBetween = childIsHorizontal && child.primaryAxisAlignItems === 'SPACE_BETWEEN';
+        const childHasFixedWidth = 'primaryAxisSizingMode' in child && child.primaryAxisSizingMode === 'FIXED';
+        if (childHasSpaceBetween && childHasFixedWidth) {
+          // Keep the FIXED sizing, but set layoutAlign to FILL to take parent width
+          // Actually, for SPACE_BETWEEN to work, we need the child to have a specific width
+          // So we resize it to parent width and keep FIXED
+          if ('resize' in child && widthBase > 0) {
+            try {
+              const padding = (parent.paddingLeft || 0) + (parent.paddingRight || 0);
+              const resizedWidth = widthBase - padding;
+              child.resize(resizedWidth, child.height);
+              reapplyRightPositionedChildren(child as FrameNode, resizedWidth);
+            } catch (_err) {
+              // ignore
+            }
+          }
+        } else if (isMxAutoFill) {
+          // mx-auto + max-w: center-align child and resize to max-w constraint.
+          // `layoutAlign` only accepts 'INHERIT' | 'STRETCH' in current Figma —
+          // legacy 'CENTER' triggers a console warning per call. Use
+          // `counterAxisAlignSelf` for non-STRETCH alignment.
+          if ('counterAxisAlignSelf' in child) {
+            try { child.counterAxisAlignSelf = 'CENTER'; } catch (_e) { /* ignore */ }
+          }
+          if ('resize' in child && widthBase > 0) {
+            try {
+              const padding = widthOverride != null ? 0 : (parent.paddingLeft || 0) + (parent.paddingRight || 0);
+              const rawTarget = Math.max(0, widthBase - padding);
+              const maxWConst = MAX_WIDTH_NODES.get(child);
+              const targetWidth = maxWConst != null ? Math.min(rawTarget, maxWConst) : rawTarget;
+              if (targetWidth > 0) {
+                child.resize(targetWidth, child.height);
+                reapplyRightPositionedChildren(child as FrameNode, targetWidth);
+                if ('layoutMode' in child) {
+                  const childLayout = child.layoutMode;
+                  if (childLayout === 'HORIZONTAL' && 'primaryAxisSizingMode' in child) {
+                    child.primaryAxisSizingMode = 'FIXED';
+                  } else if (childLayout === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+                    child.counterAxisSizingMode = 'FIXED';
+                  }
+                  reflowNestedFullWidthChildren(child as FrameNode);
+                } else if ('counterAxisSizingMode' in child) {
+                  child.counterAxisSizingMode = 'FIXED';
+                }
+              }
+            } catch (_err) {
+              // ignore
+            }
+          }
+        } else {
+          if ('layoutAlign' in child) child.layoutAlign = 'STRETCH';
+          const forceResizeForMxAutoWrapper = child.name === 'mx-auto';
+          if (
+            (
+              ('counterAxisSizingMode' in parent && parent.counterAxisSizingMode === 'FIXED')
+              || widthOverride != null
+              || forceResizeForMxAutoWrapper
+            )
+            && 'resize' in child
+          ) {
+            try {
+              // widthOverride is already content-width (padding already subtracted by caller).
+              // When falling back to parent.width we must subtract padding ourselves.
+              const padding = widthOverride != null ? 0 : (parent.paddingLeft || 0) + (parent.paddingRight || 0);
+              const rawTarget = Math.max(0, widthBase - padding);
+              // Respect max-w-* constraints for normal nodes, but never for the synthetic
+              // mx-auto wrapper itself: wrapper must stay full-width and center its child.
+              const maxWConst = forceResizeForMxAutoWrapper ? null : MAX_WIDTH_NODES.get(child);
+              const targetWidth = maxWConst != null ? Math.min(rawTarget, maxWConst) : rawTarget;
+              if (targetWidth > 0) {
+                child.resize(targetWidth, child.height);
+                reapplyRightPositionedChildren(child as FrameNode, targetWidth);
+                if ('layoutMode' in child) {
+                  const childLayout = child.layoutMode;
+                  if (childLayout === 'HORIZONTAL' && 'primaryAxisSizingMode' in child) {
+                    child.primaryAxisSizingMode = 'FIXED';
+                  } else if (childLayout === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+                    child.counterAxisSizingMode = 'FIXED';
+                  }
+                  reflowNestedFullWidthChildren(child as FrameNode);
+                } else if ('counterAxisSizingMode' in child) {
+                  child.counterAxisSizingMode = 'FIXED';
+                }
+              }
+            } catch (_err) {
+              // ignore
+            }
+          }
+        }
+      }
+    }
+    if (hasFullHeight) {
+      // Absolute-positioned children don't honor layoutGrow / layoutAlign —
+      // for `absolute inset-0 h-full w-full` (e.g. the round-trip arrow SVG
+      // overlay) only a direct resize works. Mirrors the width branch above.
+      if (childIsAbsolutePositioned && 'resize' in child && Number.isFinite(parent.height) && parent.height > 0) {
+        try {
+          const padding = (parent.paddingTop || 0) + (parent.paddingBottom || 0);
+          const targetHeight = Math.max(0, parent.height - padding);
+          if (targetHeight > 0) {
+            child.resize(child.width, targetHeight);
+            resizeSvgContentIfMarked(child, child.width, targetHeight);
+            if ('counterAxisSizingMode' in child) {
+              child.counterAxisSizingMode = 'FIXED';
+            }
+            if ('primaryAxisSizingMode' in child) {
+              child.primaryAxisSizingMode = 'FIXED';
+            }
+          }
+        } catch (_err) {
+          // ignore
+        }
+      } else if (parent.layoutMode === 'VERTICAL') {
+        if ('layoutGrow' in child && parent.primaryAxisSizingMode === 'FIXED') {
+          child.layoutGrow = 1;
+        }
+      } else if (parent.layoutMode === 'HORIZONTAL') {
+        if ('layoutAlign' in child) {
+          child.layoutAlign = 'STRETCH';
+        }
+        if (
+          'counterAxisSizingMode' in parent
+          && parent.counterAxisSizingMode === 'FIXED'
+          && 'resize' in child
+        ) {
+          try {
+            const padding = (parent.paddingTop || 0) + (parent.paddingBottom || 0);
+            const targetHeight = Math.max(0, parent.height - padding);
+            if (targetHeight > 0) {
+              child.resize(child.width, targetHeight);
+              if ('counterAxisSizingMode' in child) {
+                child.counterAxisSizingMode = 'FIXED';
+              }
+            }
+          } catch (_err) {
+            // ignore
+          }
+        }
+      } else if ('resize' in child && Number.isFinite(parent.height) && parent.height > 0) {
+        // Parent has no auto-layout (layoutMode='NONE') — typical for relative
+        // positioning containers and absolutely-positioned overlays. Direct
+        // resize to parent's content box, mirroring CSS `height: 100%`.
+        try {
+          const padding = (parent.paddingTop || 0) + (parent.paddingBottom || 0);
+          const targetHeight = Math.max(0, parent.height - padding);
+          if (targetHeight > 0) {
+            child.resize(child.width, targetHeight);
+            if ('counterAxisSizingMode' in child) {
+              child.counterAxisSizingMode = 'FIXED';
+            }
+            if ('primaryAxisSizingMode' in child) {
+              child.primaryAxisSizingMode = 'FIXED';
+            }
+          }
+        } catch (_err) {
+          // ignore
+        }
+      }
+    }
+  } catch (_err) {
+    // ignore
+  }
+  reapplyDirectionalBordersIfNeeded(child);
+  // Keep mark so we can re-apply after parent resize.
+}
+
+/**
+ * Vertical mirror of the hasFullHeight post-pass that already runs inside
+ * `applyFullWidthIfPossible` for HORIZONTAL parents: once a VERTICAL parent
+ * has a FIXED primary axis (set by `resolveStoryLayoutHeight`), pin each grow
+ * child's own primary-axis sizing to FIXED so the cascade continues. Figma
+ * auto-layout resizes the grow child to its proportional share; this just
+ * locks that allocation in place so the child's own descendants (`h-full`,
+ * nested `flex-1`) keep resolving correctly.
+ */
+export function enforceGrowChildPrimaryFixed(child: SceneNode, parent: FrameNode): void {
+  if (!parent || parent.layoutMode !== 'VERTICAL') return;
+  if (parent.primaryAxisSizingMode !== 'FIXED') return;
+  if (!('layoutGrow' in child)) return;
+  const grow = child.layoutGrow;
+  if (!Number.isFinite(grow) || grow <= 0) return;
+  if (!('layoutMode' in child)) return;
+  const childLayout = child.layoutMode;
+  try {
+    if (childLayout === 'VERTICAL' && 'primaryAxisSizingMode' in child) {
+      child.primaryAxisSizingMode = 'FIXED';
+    } else if (childLayout === 'HORIZONTAL' && 'counterAxisSizingMode' in child) {
+      child.counterAxisSizingMode = 'FIXED';
+    }
+  } catch (_err) {
+    // ignore
+  }
+}
+
+export function applyGridColumnsIfPossible(
+  frame: FrameNode,
+  widthOverride?: number,
+  colsOverride?: number
+): void {
+  const cols = colsOverride != null ? colsOverride : GRID_COLUMNS_NODES.get(frame);
+  // 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);
+  }
+
+  const wasVerticalBeforeFlip = frame.layoutMode === 'VERTICAL';
+  try {
+    if (frame.layoutMode !== 'HORIZONTAL') {
+      frame.layoutMode = 'HORIZONTAL';
+    }
+    if (frame.layoutWrap !== undefined) {
+      frame.layoutWrap = 'WRAP';
+    }
+    // When flipping from VERTICAL, the old height (computed from stacked children)
+    // lingers on the counter axis and causes STRETCH-aligned children to inflate to
+    // that stale value. Reset counter-axis sizing to AUTO so the frame re-hugs the
+    // true row height of the new horizontal-wrap layout.
+    if (wasVerticalBeforeFlip && 'counterAxisSizingMode' in frame) {
+      frame.counterAxisSizingMode = 'AUTO';
+    }
+  } catch (_err) {
+    // ignore
+  }
+
+  const totalWidth = widthOverride && Number.isFinite(widthOverride) ? widthOverride : frame.width;
+  if (!totalWidth || totalWidth <= 0) return;
+
+  const gap = frame.itemSpacing || 0;
+  const padding = (frame.paddingLeft || 0) + (frame.paddingRight || 0);
+  const available = totalWidth - padding - gap * (cols - 1);
+  if (available <= 0) return;
+
+  const childWidth = Math.max(0, available / cols);
+  if (frame.counterAxisSpacing !== undefined) {
+    frame.counterAxisSpacing = gap;
+  }
+
+  for (const child of frame.children) {
+    if (!('resize' in child)) continue;
+    try {
+      if ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE') continue;
+      const span = Math.min(COL_SPAN_NODES.get(child) ?? 1, cols);
+      const spanWidth = childWidth * span + gap * (span - 1);
+      // For text nodes, fix the width so textAlignHorizontal (e.g. text-right) takes effect.
+      // Without this, WIDTH_AND_HEIGHT auto-resize snaps the node back to text-fit width.
+      if (child.type === 'TEXT' && child.textAutoResize !== undefined) {
+        child.textAutoResize = 'HEIGHT';
+      }
+      // Track whether the child has an explicit fixed height (h-*, size-*, etc.).
+      // Can't rely on counterAxisSizingMode alone because Figma promotes it to FIXED
+      // as a side effect of resize() and of STRETCH-inheritance from row height.
+      const hadFixedHeight = FIXED_HEIGHT_NODES.has(child);
+      child.resize(spanWidth, child.height);
+      // Prevent grid children from expanding beyond calculated width
+      if ('layoutGrow' in child) {
+        child.layoutGrow = 0;
+      }
+      if ('layoutMode' in child) {
+        const childLayout = child.layoutMode;
+        if (childLayout === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+          child.counterAxisSizingMode = 'FIXED';
+        } else if (childLayout === 'HORIZONTAL' && 'primaryAxisSizingMode' in child) {
+          child.primaryAxisSizingMode = 'FIXED';
+          // Let height hug content unless the child had an explicit h-* class.
+          // Two things conspire to freeze the wrong height:
+          //   1. resize() above promotes counterAxisSizingMode to FIXED.
+          //   2. Figma can STRETCH an un-fixed child to the row height (input's 36px),
+          //      so its snapshot already reads FIXED before we look.
+          // Resetting layoutAlign to INHERIT prevents re-stretch after we go AUTO.
+          if (!hadFixedHeight) {
+            if ('layoutAlign' in child && child.layoutAlign === 'STRETCH') {
+              child.layoutAlign = 'INHERIT';
+            }
+            if ('counterAxisSizingMode' in child) {
+              child.counterAxisSizingMode = 'AUTO';
+            }
+          }
+        }
+      } else if ('primaryAxisSizingMode' in child) {
+        child.primaryAxisSizingMode = 'FIXED';
+      }
+      reapplyDirectionalBordersIfNeeded(child);
+    } catch (_err) {
+      // ignore
+    }
+  }
+}
+
+export function hasGridColumnsNode(node: SceneNode): boolean {
+  return GRID_COLUMNS_NODES.has(node);
+}
+
+export function getGridColumnsNode(node: SceneNode): number | null {
+  const cols = GRID_COLUMNS_NODES.get(node);
+  return cols != null ? cols : null;
+}
+
+export function applyFlexGrowIfPossible(frame: FrameNode, widthOverride?: number): void {
+  if (frame.layoutMode !== 'HORIZONTAL') return;
+
+  const padding = (frame.paddingLeft || 0) + (frame.paddingRight || 0);
+  const gap = frame.itemSpacing || 0;
+  const children = frame.children.filter(child => {
+    if (!('layoutPositioning' in child)) return true;
+    return child.layoutPositioning !== 'ABSOLUTE';
+  });
+  if (children.length === 0) return;
+
+  let fixedWidth = 0;
+  let growTotal = 0;
+  const growChildren: SceneNode[] = [];
+
+  for (const child of children) {
+    if (!('layoutGrow' in child)) continue;
+    const grow = child.layoutGrow;
+    if (Number.isFinite(grow) && grow > 0) {
+      growTotal += grow;
+      growChildren.push(child);
+    } else {
+      fixedWidth += child.width || 0;
+    }
+  }
+
+  if (growChildren.length === 0 || growTotal <= 0) return;
+
+  // Determine target width: use override, frame width, or compute based on children
+  let targetWidth = widthOverride && Number.isFinite(widthOverride) ? widthOverride : frame.width;
+
+  // If no width available, compute a minimum width based on fixed children + space for grow children
+  const totalGap = gap * Math.max(0, children.length - 1);
+  if (!targetWidth || targetWidth <= 0) {
+    // Use 150px per grow unit as a reasonable default for flex-grow children
+    const growWidth = 150 * growTotal;
+    targetWidth = padding + totalGap + fixedWidth + growWidth;
+  }
+
+  // Resize frame to target width and set to FIXED
+  try {
+    frame.resize(targetWidth, frame.height);
+    frame.primaryAxisSizingMode = 'FIXED';
+  } catch (_err) {
+    // ignore
+  }
+
+  const remaining = targetWidth - padding - totalGap - fixedWidth;
+  if (!Number.isFinite(remaining) || remaining <= 0) return;
+
+  for (const child of growChildren) {
+    if (!('layoutGrow' in child)) continue;
+    const grow = child.layoutGrow;
+    const width = remaining * (grow / growTotal);
+    if (!Number.isFinite(width) || width <= 0) continue;
+    if (!('resize' in child)) continue;
+    try {
+      child.resize(width, child.height);
+      if ('layoutMode' in child) {
+        const childLayout = child.layoutMode;
+        if (childLayout === 'VERTICAL' && 'counterAxisSizingMode' in child) {
+          child.counterAxisSizingMode = 'FIXED';
+        } else if (childLayout === 'HORIZONTAL' && 'primaryAxisSizingMode' in child) {
+          child.primaryAxisSizingMode = 'FIXED';
+        }
+      } else if ('primaryAxisSizingMode' in child) {
+        child.primaryAxisSizingMode = 'FIXED';
+      }
+    } catch (_err) {
+      // ignore
+    }
+  }
+}
+
+/**
+ * Vertical mirror of `applyFlexGrowIfPossible` for viewport-anchored frames.
+ * When a VERTICAL frame has a FIXED primary axis (set by the story-level
+ * viewport-height pre-pass), distribute the remaining height among grow
+ * children proportional to their `layoutGrow` values. Grow children that are
+ * themselves auto-layout frames have their own primary axis locked to FIXED so
+ * the cascade continues into their descendants.
+ */
+export function applyVerticalFlexGrowIfPossible(frame: FrameNode): void {
+  if (frame.layoutMode !== 'VERTICAL') return;
+  if (frame.primaryAxisSizingMode !== 'FIXED') return;
+
+  const padding = (frame.paddingTop || 0) + (frame.paddingBottom || 0);
+  const gap = frame.itemSpacing || 0;
+  const children = frame.children.filter(child => {
+    if (!('layoutPositioning' in child)) return true;
+    return child.layoutPositioning !== 'ABSOLUTE';
+  });
+  if (children.length === 0) return;
+
+  let fixedHeight = 0;
+  let growTotal = 0;
+  const growChildren: SceneNode[] = [];
+
+  for (const child of children) {
+    if (!('layoutGrow' in child)) continue;
+    const grow = child.layoutGrow;
+    if (Number.isFinite(grow) && grow > 0) {
+      growTotal += grow;
+      growChildren.push(child);
+    } else {
+      fixedHeight += child.height || 0;
+    }
+  }
+
+  if (growChildren.length === 0 || growTotal <= 0) return;
+
+  const totalGap = gap * Math.max(0, children.length - 1);
+  const remaining = frame.height - padding - totalGap - fixedHeight;
+  if (!Number.isFinite(remaining) || remaining <= 0) return;
+
+  for (const child of growChildren) {
+    if (!('layoutGrow' in child)) continue;
+    const grow = child.layoutGrow;
+    const height = remaining * (grow / growTotal);
+    if (!Number.isFinite(height) || height <= 0) continue;
+    if (!('resize' in child)) continue;
+    try {
+      child.resize(child.width, height);
+      if ('layoutMode' in child) {
+        const childLayout = child.layoutMode;
+        if (childLayout === 'VERTICAL' && 'primaryAxisSizingMode' in child) {
+          child.primaryAxisSizingMode = 'FIXED';
+        } else if (childLayout === 'HORIZONTAL' && 'counterAxisSizingMode' in child) {
+          child.counterAxisSizingMode = 'FIXED';
+        }
+      } else if ('primaryAxisSizingMode' in child) {
+        child.primaryAxisSizingMode = 'FIXED';
+      }
+    } catch (_err) {
+      // ignore
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports for tailwind.ts internal use (mark functions called during CSS processing)
+// ---------------------------------------------------------------------------
+
+export {
+  markFullHeightNode,
+  markFixedHeightNode,
+  markFixedWidthNode,
+  markSelfAlignmentNode,
+  markFlexBasisNode,
+  markMinWidthNode,
+  markMaxWidthNode,
+  markGridColumnsNode,
+  markColSpanNode,
+  markFractionWidthNode,
+  parseFractionToken,
+  BORDER_WIDTH_CLASSES,
+  DEFERRED_TOP_RELATIVE_NODES,
+};