inkbridge 0.1.0-beta.21 → 0.1.0-beta.23

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/layout-parser.ts

@@ -259,12 +259,48 @@ export class LayoutParser {
     const parentWantsStretch =
       fromFlexStretchBranch
       || (fromBlockFlowMinBranch && !childHasInlineDisplay);
+    // Only honour implicit STRETCH when the parent has a definite
+    // counter-axis width (FIXED). With AUTO counter sizing the parent
+    // is shrink-to-fit; stretching the child to "parent's width" then
+    // means stretching to whatever earlier non-stretch siblings hugged
+    // the parent to — which in CSS would never happen because CSS
+    // intrinsic sizing considers every child's max-content width
+    // before resolving the parent. Without this guard a `<div><h3>x</h3>
+    // <p>longer text</p></div>` collapses the `<p>` to the `<h3>`'s
+    // width and the longer text wraps. Skipping the stretch lets the
+    // `<p>` hug to its natural width and the parent grow to the wider
+    // of the two — CSS-equivalent.
+    const parentCounterFixed =
+      'counterAxisSizingMode' in parent
+      && parent.counterAxisSizingMode === 'FIXED';
     const shouldImplicitStretch = parentLayout === 'VERTICAL'
       && parentWantsStretch
+      && parentCounterFixed
       && ir.selfAlign === undefined
       && !isOutOfFlowChild;
     if (shouldImplicitStretch && 'layoutAlign' in child && !this.hasNonAutoWidthConstraint(childClasses)) {
       child.layoutAlign = 'STRETCH';
+      // Lock the counter axis to FIXED so the child's *own* children
+      // recognise it as definite-width in the next applyChildProperties
+      // pass. Without this, the implicit-STRETCH cascade stops one
+      // level deep — a block descendant of a STRETCH-aligned wrapper
+      // sees `counterAxisSizingMode === 'AUTO'` on its parent and the
+      // `parentCounterFixed` guard above skips its own STRETCH. The
+      // wrapper then HUGs to the widest non-stretch sibling (typically
+      // a short title) and longer block siblings (a description `<p>`)
+      // get cut to that width — which in CSS would never happen
+      // because the wrapper's effective width came from *its* parent.
+      // Setting FIXED here is safe: layoutAlign='STRETCH' already
+      // forces width = parent.contentWidth, so locking the sizing
+      // mode doesn't change the rendered size — it just signals the
+      // definite-width contract downstream.
+      if ('counterAxisSizingMode' in child) {
+        try {
+          child.counterAxisSizingMode = 'FIXED';
+        } catch (_err) {
+          // ignore — some node types (instance/text) reject the property
+        }
+      }
     }
 
     // CSS `text-align` on a block container centers/aligns inline content

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/layout/table-layout.ts

@@ -0,0 +1,271 @@
+/**
+ * Table column-width unification.
+ *
+ * Semantic HTML `<table>` columns align across rows because the browser
+ * computes column widths globally (max of any cell's max-content
+ * width per column, then distributed if a definite table width
+ * applies). Figma has no equivalent — each `<tr>` is its own HORIZONTAL
+ * auto-layout frame and its cells size independently. Rows whose
+ * content sums to different totals therefore render with misaligned
+ * columns: column N starts at a different X-offset on each row, and
+ * `whitespace-nowrap` cells visually run into their neighbours when
+ * the row's hugged width happens to be tighter than the sum of
+ * untruncated cells.
+ *
+ * This module runs in Phase 3 (deferred layout) and walks the built
+ * tree for `<table>` frames. For each table, it computes the
+ * max-content width per column across all rows (incl. `<thead>` /
+ * `<tbody>` / `<tfoot>`) and resizes every cell at that column index
+ * to the column's max width. The result mirrors what the browser
+ * produces from `table-fixed` — columns line up across rows.
+ *
+ * ## What this fix does NOT touch
+ *
+ * - **Cells with explicit width** (`w-32`, `flex-1`, etc.). Existing
+ *   `hasTableCellSizeOverride` cells are left alone; designer intent
+ *   wins over the inferred column width.
+ * - **Colspan > 1 cells**. They take their own natural width and are
+ *   excluded from per-column max calculation; without this exclusion a
+ *   `colSpan={7}` empty-state row would dominate column 0's max-width
+ *   and push every other row's first column to span the full table.
+ *   Skipping leaves them as-is — they render at content width and may
+ *   not perfectly align under the multi-cell rows, but the multi-cell
+ *   rows themselves align correctly with each other.
+ * - **Tables nested inside tables**. Each table is processed
+ *   independently; outer-table cells that contain an inner table are
+ *   sized by the inner table's column unification, which is fine.
+ *
+ * ## Phase
+ *
+ * Phase 3 (deferred layout). Runs once per built story-layout tree,
+ * after `reflowDeferredAbsolutePositioningTree` so cell sizes are
+ * settled. Earlier passes set every cell's `layoutGrow = 1` and let
+ * the row hug to content — at this point each cell's `width` is its
+ * max-content width per row, which is exactly what we need to compute
+ * the per-column max.
+ */
+
+import { applyDeferredTruncationPass } from './text-truncate-pass';
+
+const TABLE_TAGS = new Set(['table']);
+const ROW_GROUP_TAGS = new Set(['thead', 'tbody', 'tfoot']);
+const ROW_TAG = 'tr';
+const CELL_TAGS = new Set(['td', 'th']);
+
+export interface TableAlignStats {
+  tablesProcessed: number;
+  cellsResized: number;
+}
+
+/**
+ * Walk the tree rooted at `root`. For every `<table>` frame, unify
+ * each column's width across all its rows to the column's max-content
+ * width.
+ *
+ * Returns observability stats. Caller may discard.
+ */
+export function applyTableColumnAlignment(root: SceneNode): TableAlignStats {
+  const stats: TableAlignStats = { tablesProcessed: 0, cellsResized: 0 };
+  walk(root, stats);
+  return stats;
+}
+
+function walk(node: SceneNode, stats: TableAlignStats): void {
+  if ('name' in node && TABLE_TAGS.has(String(node.name).toLowerCase()) && 'children' in node) {
+    alignTable(node as FrameNode, stats);
+    // Tables can be nested — keep walking children so an outer-table
+    // alignment doesn't prevent a nested table from being processed.
+  }
+  if ('children' in node && Array.isArray(node.children)) {
+    for (const child of node.children) walk(child, stats);
+  }
+}
+
+function alignTable(tableFrame: FrameNode, stats: TableAlignStats): void {
+  stats.tablesProcessed += 1;
+
+  // Collect every <tr> under thead/tbody/tfoot (and any direct <tr> child).
+  const rows: FrameNode[] = [];
+  collectRows(tableFrame, rows);
+  if (rows.length < 2) {
+    // Single-row tables don't have a misalignment to fix.
+    return;
+  }
+
+  // First pass: per-column max of single-cell (colspan===1) cells.
+  // Multi-cell rows (colspan>1) are excluded from the max so an
+  // empty-state cell spanning all columns doesn't blow up column 0.
+  const maxWidths: number[] = [];
+  for (const row of rows) {
+    const cells = inFlowCells(row);
+    for (let c = 0; c < cells.length; c++) {
+      const cell = cells[c];
+      if (getColSpan(cell) !== 1) continue;
+      const w = Number.isFinite(cell.width) ? cell.width : 0;
+      if (w <= 0) continue;
+      if (maxWidths[c] === undefined || w > maxWidths[c]) {
+        maxWidths[c] = w;
+      }
+    }
+  }
+
+  // Fit the column sum to the table's available width. Mirrors the
+  // common consumer pattern of `min-w-full table-fixed`:
+  //   - sum > available → scale DOWN proportionally (columns shrink
+  //     to fit; cells truncate / wrap as in `table-fixed`).
+  //   - sum < available → scale UP proportionally (columns expand to
+  //     fill the row; matches `min-w-full` enforcing table = parent
+  //     width).
+  //   - no available anchor → leave at natural max-content widths.
+  // Without scale-up, Figma rows under-fill the card and the row
+  // separator borders end mid-card. Without scale-down they overflow
+  // the card right edge.
+  const totalNaturalWidth = maxWidths.reduce((acc, w) => acc + (w || 0), 0);
+  const availableWidth = computeTableAvailableWidth(tableFrame);
+  const finalWidths = (availableWidth != null && totalNaturalWidth > 0 && availableWidth > 0)
+    ? maxWidths.map((w) => (w ? Math.max(1, Math.floor(w * (availableWidth / totalNaturalWidth))) : w))
+    : maxWidths;
+
+  // Second pass: lock every single-cell to its column's final width and
+  // normalise sizing state (layoutGrow=0, primaryAxisSizingMode=FIXED).
+  // Even when the cell's width happens to already match the target, the
+  // sizing-mode normalisation must run so the cell doesn't snap back to
+  // a different width if the row's overall width changes later.
+  //
+  // Immediately after locking each cell, run the deferred-truncation
+  // pass against the cell. Any TextNode inside that the renderer
+  // marked via `markForTruncation` (because its source had `truncate`
+  // / `line-clamp-N`) is now resized to the cell's final content
+  // width with `textTruncation = 'ENDING'`. Cells whose text already
+  // fits are no-ops.
+  for (const row of rows) {
+    const cells = inFlowCells(row);
+    for (let c = 0; c < cells.length; c++) {
+      const cell = cells[c];
+      if (getColSpan(cell) !== 1) continue;
+      const target = finalWidths[c];
+      if (target === undefined || target <= 0) continue;
+      const needsResize = Math.abs(cell.width - target) >= 0.5;
+      lockCellWidth(cell, target);
+      if (needsResize) stats.cellsResized += 1;
+      applyDeferredTruncationPass(cell);
+    }
+  }
+}
+
+/**
+ * Walk up from the table to find the nearest ancestor with a definite
+ * width, accumulating paddings consumed along the path. Returns the
+ * available width at the table's slot, or `null` if no definite-width
+ * ancestor is reachable (in which case the table is allowed to take
+ * its natural max-content width).
+ *
+ * Sibling widths in horizontal ancestors are intentionally NOT
+ * subtracted — tables typically sit alone in a vertical card layout,
+ * and over-subtracting would shrink the table when it shouldn't.
+ * If a future use case needs sibling-aware budgeting, the shape mirrors
+ * `intrinsic-sizing.computeWrapAvailableWidth` and could be lifted into
+ * a shared helper at that point.
+ */
+function computeTableAvailableWidth(tableFrame: FrameNode): number | null {
+  let cur: SceneNode = tableFrame;
+  let consumed = 0;
+  for (let depth = 0; depth < 32; depth++) {
+    const parent = cur.parent as SceneNode | null;
+    if (!parent || !('children' in parent) || !('layoutMode' in parent)) {
+      return null;
+    }
+    const frame = parent as FrameNode;
+    consumed += (frame.paddingLeft || 0) + (frame.paddingRight || 0);
+
+    if (frame.layoutMode === 'VERTICAL') {
+      // Vertical parent — width is the counter axis. Definite when
+      // counter sizing is FIXED with a real width.
+      if (
+        frame.counterAxisSizingMode === 'FIXED'
+        && Number.isFinite(frame.width)
+        && frame.width > 0
+      ) {
+        return Math.max(0, frame.width - consumed);
+      }
+    } else if (frame.layoutMode === 'HORIZONTAL') {
+      // Horizontal parent — width is the primary axis. Definite when
+      // primary sizing is FIXED.
+      if (
+        frame.primaryAxisSizingMode === 'FIXED'
+        && Number.isFinite(frame.width)
+        && frame.width > 0
+      ) {
+        return Math.max(0, frame.width - consumed);
+      }
+    } else {
+      // NONE / freeform — width is whatever it is.
+      if (Number.isFinite(frame.width) && frame.width > 0) {
+        return Math.max(0, frame.width - consumed);
+      }
+    }
+    cur = frame;
+  }
+  return null;
+}
+
+function collectRows(node: SceneNode, out: FrameNode[]): void {
+  if (!('children' in node) || !Array.isArray(node.children)) return;
+  for (const child of node.children) {
+    const tagName = ('name' in child ? String(child.name).toLowerCase() : '');
+    if (tagName === ROW_TAG) {
+      out.push(child as FrameNode);
+      continue;
+    }
+    if (ROW_GROUP_TAGS.has(tagName)) {
+      collectRows(child, out);
+    }
+    // Anything else (e.g. nested table, divider) is skipped — we only
+    // unify columns of the immediate table's rows.
+  }
+}
+
+function inFlowCells(row: FrameNode): FrameNode[] {
+  const out: FrameNode[] = [];
+  if (!('children' in row) || !Array.isArray(row.children)) return out;
+  for (const child of row.children) {
+    if ('layoutPositioning' in child && child.layoutPositioning === 'ABSOLUTE') continue;
+    const tagName = ('name' in child ? String(child.name).toLowerCase() : '');
+    if (!CELL_TAGS.has(tagName)) continue;
+    out.push(child as FrameNode);
+  }
+  return out;
+}
+
+function getColSpan(cell: FrameNode): number {
+  // colspan is stored on the scene node via setPluginData when emitted
+  // from the JSX scanner. Default to 1 when absent.
+  try {
+    const raw = cell.getPluginData('inkbridge:col-span');
+    if (!raw) return 1;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : 1;
+  } catch (_e) {
+    return 1;
+  }
+}
+
+function lockCellWidth(cell: FrameNode, width: number): void {
+  // Drop layoutGrow so the cell honours its FIXED width instead of
+  // re-stretching to fill the row. Then flip primary sizing to FIXED
+  // and resize. Order matters per Figma API: AUTO is invalid when
+  // layoutGrow > 0 on the relevant axis.
+  try {
+    if ('layoutGrow' in cell && cell.layoutGrow !== 0) {
+      cell.layoutGrow = 0;
+    }
+    if ('primaryAxisSizingMode' in cell) {
+      cell.primaryAxisSizingMode = 'FIXED';
+    }
+    cell.resize(width, cell.height);
+  } catch (_e) {
+    // Best effort — some node subtypes (e.g. instance) may reject
+    // resize; the visual misalignment for that one cell is preferable
+    // to a crash that takes down the whole table.
+  }
+}