inkbridge 0.1.0-beta.21 → 0.1.0-beta.22

package/src/layout/intrinsic-applier.ts

@@ -0,0 +1,105 @@
+/**
+ * Intrinsic-sizing applier.
+ *
+ * Walks a built Figma tree and rewrites the auto-layout properties
+ * that would otherwise leave HUG containers stuck at Figma's frame-
+ * creation default (~100px) due to the STRETCH-in-HUG-chain deadlock
+ * described in `intrinsic-sizing.ts`.
+ *
+ * ## Why we transform alignment, not size
+ *
+ * Per the Figma plugin API:
+ *
+ *   > AUTO: The primary axis length is determined by the size of the
+ *   > children.
+ *   > AUTO: The counter axis length is determined by the size of the
+ *   > children. If set, the auto-layout frame will automatically resize
+ *   > along the counter axis to fit its children.
+ *
+ * Calling `frame.resize(w, h)` on a HUG frame does NOT stick — the
+ * engine recomputes from children on the next pass. So we can't force
+ * a width on a HUG container without flipping `layoutMode` to `'NONE'`
+ * (which destroys designer auto-layout editability).
+ *
+ * Instead, we change the *child* contribution to the parent's HUG
+ * computation. For each STRETCH child whose parent's chain isn't
+ * width-anchored:
+ *
+ *   1. Flip the child's `layoutAlign` from `'STRETCH'` to `'INHERIT'`
+ *      (drop the cross-axis stretch directive).
+ *   2. Reset the sizing axis that the STRETCH side-effect had silently
+ *      flipped to FIXED back to `'AUTO'`. Parent is VERTICAL (per the
+ *      predicate), so the affected child axis is its horizontal axis:
+ *      `primaryAxisSizingMode` for a HORIZONTAL child,
+ *      `counterAxisSizingMode` for a VERTICAL child.
+ *
+ * After the flip, the child hugs its own content, the parent's HUG
+ * resolves to max-of-children — the exact result CSS produces via
+ * max-content. Designer affordance is preserved: if the designer
+ * later anchors the chain by setting an ancestor to FIXED, they can
+ * re-enable Fill / STRETCH on the children manually and Figma's
+ * STRETCH cascade will work correctly against the new anchor.
+ *
+ * ## Phase
+ *
+ * Phase 3 (deferred layout). Runs once per built story-layout tree
+ * from `populateStoryLayout`, before `reflowDeferredAbsolutePositioningTree`.
+ */
+
+import { isUnanchoredStretchChild } from './intrinsic-sizing';
+
+export interface IntrinsicApplierStats {
+  /** Number of children whose layoutAlign was flipped STRETCH → INHERIT. */
+  alignmentFlips: number;
+  /** Number of nodes walked. */
+  nodesWalked: number;
+}
+
+/**
+ * Walk the tree rooted at `root`. For every STRETCH child of a VERTICAL
+ * parent whose chain doesn't reach a width-anchored ancestor, flip the
+ * child's `layoutAlign` to `'INHERIT'` and reset its horizontal sizing
+ * axis to `'AUTO'`. Children then hug their own content; the parent's
+ * HUG resolves to max-of-children.
+ *
+ * Returns a stats object for observability / tests.
+ */
+export function breakHugStretchDeadlocks(root: SceneNode): IntrinsicApplierStats {
+  const stats: IntrinsicApplierStats = { alignmentFlips: 0, nodesWalked: 0 };
+  walk(root, stats);
+  return stats;
+}
+
+function walk(node: SceneNode, stats: IntrinsicApplierStats): void {
+  stats.nodesWalked += 1;
+
+  if (isUnanchoredStretchChild(node)) {
+    try {
+      const frame = node as FrameNode;
+      // Order matters per Figma API: AUTO is not valid on an axis where
+      // layoutAlign === 'STRETCH'. Drop the STRETCH first, then reset
+      // the sizing axis that the STRETCH side-effect had flipped to
+      // FIXED. Parent is VERTICAL (guaranteed by the predicate), so the
+      // affected axis is child's HORIZONTAL: primary for a HORIZONTAL
+      // child, counter for a VERTICAL child.
+      frame.layoutAlign = 'INHERIT';
+      if ('layoutMode' in frame) {
+        if (frame.layoutMode === 'HORIZONTAL') {
+          frame.primaryAxisSizingMode = 'AUTO';
+        } else if (frame.layoutMode === 'VERTICAL') {
+          frame.counterAxisSizingMode = 'AUTO';
+        }
+      }
+      stats.alignmentFlips += 1;
+    } catch (_err) {
+      // Some node types may not accept the assignment in edge cases;
+      // ignore and continue — best-effort transform.
+    }
+  }
+
+  if ('children' in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      walk(child, stats);
+    }
+  }
+}

package/src/layout/intrinsic-sizing.ts

@@ -0,0 +1,183 @@
+/**
+ * Intrinsic-sizing predicates.
+ *
+ * Pure inspectors that detect where Figma's auto-layout reaches the
+ * intrinsic-sizing deadlock that CSS resolves via its two-pass
+ * algorithm (max-content bottom-up, then constraints top-down).
+ *
+ * ## The deadlock
+ *
+ * Consider a chain where a HUG container has STRETCH children:
+ *
+ *   parent VERTICAL HUG counter            ← width = max(children widths)
+ *   └── child VERTICAL layoutAlign=STRETCH ← width = parent.width
+ *
+ * CSS resolves this by computing the child's intrinsic max-content,
+ * making that the parent's HUG width, then stretching the child back
+ * to that width. Figma's layout engine doesn't compute max-content —
+ * the dependency is circular, and Figma falls back to the frame-
+ * creation default (~100px) at the top, which then cascades down as
+ * "stretch to 100" through every level of the chain.
+ *
+ * ## What "width propagation" means here
+ *
+ * A frame's horizontal width is "definite" (i.e. its source is not
+ * one of its own children) if EITHER:
+ *
+ *  1. It is the root frame with an explicit width (Story Layout etc.).
+ *  2. It is a STRETCH child of a VERTICAL parent whose width is
+ *     definite — the parent's width flows down to the child's
+ *     horizontal axis.
+ *  3. It is a GROW (layoutGrow=1) child of a HORIZONTAL parent whose
+ *     primary axis (horizontal) is definite — parent's primary width
+ *     minus siblings flows down.
+ *
+ * Otherwise the frame's width is HUG-of-children — i.e. determined by
+ * walking into the subtree. If every ancestor in turn is also HUG-of-
+ * children, the chain is unanchored and the deadlock applies.
+ *
+ * ## Why we don't trust `primaryAxisSizingMode === 'FIXED'` alone
+ *
+ * Per the Figma plugin API, `layoutAlign='STRETCH'` cannot coexist
+ * with `primaryAxisSizingMode='AUTO'` on the relevant axis — Figma
+ * silently flips it to FIXED. So a HORIZONTAL frame inside a VERTICAL
+ * parent with STRETCH appears as `primaryAxisSizingMode=FIXED` even
+ * when the user wrote no explicit width utility. Reading the mode
+ * alone tells us only that Figma's resolver decided FIXED, not whether
+ * the width was authored by intent. The propagation walk is the
+ * authoritative check.
+ *
+ * ## Phase
+ *
+ * Phase 3 (deferred layout). The predicates need full ancestor context
+ * — they can only run after `appendChild`. Use from
+ * `reflowDeferredAbsolutePositioningTree` or another post-build pass.
+ */
+
+const WIDTH_DEFINITE_CACHE = new WeakMap<SceneNode, boolean>();
+
+interface ChainRule {
+  /** Walks parent → child to see if the child's width is propagated from the parent. */
+  childWidthPropagates: (parent: FrameNode, child: SceneNode) => boolean;
+}
+
+const VERTICAL_PARENT_RULE: ChainRule = {
+  childWidthPropagates(_parent, child) {
+    // In a VERTICAL parent the child's horizontal axis is the parent's
+    // counter axis. The child gets the parent's width only if it
+    // explicitly stretches.
+    return 'layoutAlign' in child && child.layoutAlign === 'STRETCH';
+  },
+};
+
+const HORIZONTAL_PARENT_RULE: ChainRule = {
+  childWidthPropagates(_parent, child) {
+    // In a HORIZONTAL parent the child's horizontal axis is the parent's
+    // primary axis. The child gets a definite slice of the parent's
+    // width only if it grows to fill remaining primary space.
+    return 'layoutGrow' in child && child.layoutGrow === 1;
+  },
+};
+
+function getParentRule(parent: FrameNode): ChainRule | null {
+  if (parent.layoutMode === 'VERTICAL') return VERTICAL_PARENT_RULE;
+  if (parent.layoutMode === 'HORIZONTAL') return HORIZONTAL_PARENT_RULE;
+  // NONE / freeform parent does not propagate sizing through auto-layout.
+  return null;
+}
+
+function isAuthoredRoot(node: SceneNode): boolean {
+  // Top-level frames (no parent or a non-frame parent like PageNode) are
+  // treated as definite — their width came from upstream code that knows
+  // what it's doing (Story Layout, component master, etc.).
+  const parent = node.parent;
+  if (!parent) return true;
+  if (!('layoutMode' in parent)) return true;
+  return false;
+}
+
+/**
+ * Does this node's horizontal width come from somewhere other than its
+ * own children? Memoized — a tree walk evaluates each node at most once.
+ *
+ * NOTE: callers must invalidate the cache (call `clearWidthDefiniteCache`)
+ * if they mutate any property the predicate reads (layoutAlign,
+ * layoutGrow, layoutMode) between calls. Within a single Phase-3 pass
+ * the tree is stable; this is the intended use.
+ */
+export function hasDefiniteWidth(node: SceneNode): boolean {
+  const cached = WIDTH_DEFINITE_CACHE.get(node);
+  if (cached !== undefined) return cached;
+  const result = computeHasDefiniteWidth(node, new Set());
+  WIDTH_DEFINITE_CACHE.set(node, result);
+  return result;
+}
+
+function computeHasDefiniteWidth(node: SceneNode, seen: Set<SceneNode>): boolean {
+  // Cycle guard for pathological trees.
+  if (seen.has(node)) return false;
+  seen.add(node);
+
+  if (isAuthoredRoot(node)) return true;
+
+  // Trust an explicit FIXED width set by the plugin's own code paths
+  // (applyFullWidthIfPossible, applyGridColumnsIfPossible, w-[Npx], etc.)
+  // when it's NOT a layoutAlign=STRETCH / layoutGrow=1 side-effect.
+  // Figma silently flips primaryAxisSizingMode to FIXED when those
+  // child-side directives are set, but the resulting "FIXED" width may
+  // be the frame-creation default (~100) — we can't trust those. When
+  // the child is neither STRETCH nor GROW, a FIXED axis means the value
+  // was authored.
+  if (hasAuthoredFixedWidth(node)) return true;
+
+  const parent = node.parent as FrameNode;
+  const rule = getParentRule(parent);
+  if (rule == null) return false;
+  if (!rule.childWidthPropagates(parent, node)) return false;
+  return computeHasDefiniteWidth(parent, seen);
+}
+
+function hasAuthoredFixedWidth(node: SceneNode): boolean {
+  // STRETCH / GROW side-effects: the FIXED axis came from Figma silently
+  // upgrading the sizing mode, not from authored intent.
+  if ('layoutAlign' in node && node.layoutAlign === 'STRETCH') return false;
+  if ('layoutGrow' in node && node.layoutGrow === 1) return false;
+  if (!('layoutMode' in node)) return false;
+  const frame = node as FrameNode;
+  if (!('width' in frame) || !Number.isFinite(frame.width) || frame.width <= 0) return false;
+  if (frame.layoutMode === 'HORIZONTAL') {
+    return frame.primaryAxisSizingMode === 'FIXED';
+  }
+  if (frame.layoutMode === 'VERTICAL') {
+    return frame.counterAxisSizingMode === 'FIXED';
+  }
+  // NONE freeform — width is just whatever the user / plugin set.
+  return true;
+}
+
+/**
+ * Is this node a STRETCH child of a VERTICAL parent whose width is not
+ * definite — i.e. the STRETCH cascades into the frame-creation default
+ * and produces a ~100px stuck frame width?
+ *
+ * Restricted to VERTICAL parents because that's the width-deadlock
+ * shape: in a VERTICAL parent, `layoutAlign=STRETCH` on a child means
+ * "stretch horizontally to parent's width". If parent's width is HUG
+ * and unanchored, the STRETCH has nothing to stretch to.
+ *
+ * (HORIZONTAL parents have an analogous height-deadlock for
+ * `layoutAlign=STRETCH` and a width-deadlock for `layoutGrow=1`, but
+ * those are separate concerns covered by other heuristics in the
+ * pipeline. Width deadlocks via STRETCH in a VERTICAL chain are the
+ * canonical pattern this module addresses.)
+ */
+export function isUnanchoredStretchChild(node: SceneNode): boolean {
+  if (!('layoutAlign' in node)) return false;
+  if (node.layoutAlign !== 'STRETCH') return false;
+  const parent = node.parent as SceneNode | null;
+  if (!parent || !('layoutMode' in parent)) return false;
+  const parentFrame = parent as FrameNode;
+  if (parentFrame.layoutMode !== 'VERTICAL') return false;
+  return !hasDefiniteWidth(parent);
+}
+

package/src/layout/parser/layout-mode.ts

@@ -36,10 +36,20 @@ export function parseLayoutMode(classes: string[]): 'HORIZONTAL' | 'VERTICAL' |
     }
     if (cls === 'grid' || cls === 'inline-grid') {
       // grid without grid-cols-N is a single-column layout (like flex-col).
-      // grid WITH grid-cols-N wraps horizontally — the column count is
-      // applied later by markGridColumnsNode, not stored in the IR.
-      const hasColumns = classes.some(c => /^grid-cols-\d+$/.test(c));
-      mode = hasColumns ? 'HORIZONTAL' : 'VERTICAL';
+      // grid WITH grid-cols-N (N >= 2) wraps horizontally — the column count
+      // is applied later by markGridColumnsNode, not stored in the IR.
+      //
+      // `grid-cols-1` is special: one column in CSS means children stack
+      // vertically (single column = no horizontal flow). Treating it as
+      // HORIZONTAL — like grid-cols-2+ — flips the layout, eats the
+      // primary-axis gap (no vertical itemSpacing), and forces wrap. Comes
+      // up via `mapClassNameForBreakpoint`'s grid-cols-1 injection at the
+      // base breakpoint when the source had a responsive `sm:grid-cols-N`.
+      const hasMultiColumns = classes.some(c => {
+        const match = c.match(/^grid-cols-(\d+)$/);
+        return match != null && parseInt(match[1], 10) >= 2;
+      });
+      mode = hasMultiColumns ? 'HORIZONTAL' : 'VERTICAL';
       directionSet = true;
       continue;
     }

package/src/render-engine-version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by build.mjs. Do not edit manually.
-export const RENDER_ENGINE_VERSION = '011e89524e15bfda';
+export const RENDER_ENGINE_VERSION = '40e3e9df6d50c02c';

package/src/tailwind/tailwind.ts

@@ -328,15 +328,20 @@ function applyCssDeclarationsToFrame(frame: FrameNode, declarations: Record<stri
       continue;
     }
     if (prop === 'display' && (value === 'grid' || value === 'inline-grid')) {
-      if (declaredGridColumns != null) {
+      // `grid-cols-1` (1 explicit column) is CSS-semantically a vertical
+      // stack — same as `grid` without any column class. Only flip to
+      // HORIZONTAL+WRAP when there are >=2 columns; otherwise route through
+      // the vertical-flow path so itemSpacing (primary axis = vertical)
+      // applies correctly and children don't get a stale horizontal layout.
+      if (declaredGridColumns != null && declaredGridColumns >= 2) {
         frame.layoutMode = 'HORIZONTAL';
         markGridColumnsNode(frame, declaredGridColumns);
         if (frame.layoutWrap !== undefined) {
           frame.layoutWrap = 'WRAP';
         }
       } else {
-        // CSS grid without explicit template columns behaves like a single-column
-        // vertical flow in our Figma mapping.
+        // CSS grid without explicit template columns (or with exactly 1
+        // column) behaves like a single-column vertical flow.
         frame.layoutMode = 'VERTICAL';
         markCssGridVerticalFrame(frame);
       }
@@ -842,6 +847,13 @@ function applySemanticUtilitiesToFrame(
     const atom = parseUtilityClass(cls);
     if (!atom.utility) continue;
 
+    // Filter breakpoint-prefixed atoms FIRST so utilities like `sm:grid-cols-2`
+    // don't leak through to `markGridColumnsNode` at the base breakpoint.
+    // The responsive-analyzer normally strips breakpoint prefixes before
+    // calling here, but defense-in-depth: any atom carrying a non-active
+    // variant must be skipped before any structural side-effects run.
+    if (!shouldApplyAtom(atom, 'default')) continue;
+
     const utility = atom.utility;
 
     const gridColsMatch = utility.match(/^grid-cols-(\d+)$/);
@@ -860,8 +872,6 @@ function applySemanticUtilitiesToFrame(
       continue;
     }
 
-    if (!shouldApplyAtom(atom, 'default')) continue;
-
     if (utility === 'flex' || utility === 'inline-flex') {
       // Bare `flex` enables flex layout but does not set direction. Only write
       // HORIZONTAL when the direction hasn't been declared yet by a prior
@@ -906,14 +916,25 @@ function applySemanticUtilitiesToFrame(
       continue;
     }
     if (utility === 'grid' || utility === 'inline-grid') {
-      const hasColumns = classes.some((c: string) => /^grid-cols-\d+$/.test(c));
-      if (hasColumns) {
+      // Match parseLayoutMode + applyCssDeclarationsToFrame: only flip
+      // to HORIZONTAL+WRAP when there are >=2 columns. `grid-cols-1` is
+      // CSS-semantically a vertical stack (single column = no horizontal
+      // flow) and must route through the VERTICAL path so itemSpacing
+      // applies on the right axis. The `mapClassNameForBreakpoint`
+      // helper injects `grid-cols-1` at the base breakpoint when the
+      // source had a responsive `sm:grid-cols-N`, so this case is hit
+      // any time a grid with responsive columns renders at base.
+      const hasMultiColumns = classes.some((c: string) => {
+        const match = c.match(/^grid-cols-(\d+)$/);
+        return match != null && parseInt(match[1], 10) >= 2;
+      });
+      if (hasMultiColumns) {
         frame.layoutMode = 'HORIZONTAL';
         if (frame.layoutWrap !== undefined) {
           frame.layoutWrap = 'WRAP';
         }
       } else {
-        // Single-column implicit grid → VERTICAL; children stretch to fill (CSS default align-items: stretch)
+        // Single-column implicit grid or `grid-cols-1` → VERTICAL; children stretch to fill (CSS default align-items: stretch)
         frame.layoutMode = 'VERTICAL';
         markCssGridVerticalFrame(frame);
       }