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

package/scanner/intrinsic-sizing-regression.ts

@@ -0,0 +1,333 @@
+import assert from 'node:assert/strict';
+
+(globalThis as unknown as { figma: unknown }).figma = {
+  notify: () => undefined,
+  showUI: () => undefined,
+};
+
+import { hasDefiniteWidth, isUnanchoredStretchChild } from '../src/layout/intrinsic-sizing';
+import { breakHugStretchDeadlocks } from '../src/layout/intrinsic-applier';
+
+/**
+ * Locks in the intrinsic-sizing predicates + applier.
+ *
+ * Canonical real-world repro: greenhouse-app `MarketPriceCard` timeframe
+ * row at lg / xl. The wrap row sits at the bottom of a chain like:
+ *
+ *   Story Layout   VERTICAL  counter=FIXED w=1024   ← anchored (authored)
+ *   └── Card root  VERTICAL  layoutAlign=STRETCH    ← propagated
+ *       └── CardHdr HORIZONTAL primary=FIXED        ← authored FIXED width
+ *           └── R-grp VERTICAL layoutGrow=0 hug      ← chain BREAKS
+ *               └── mid VERTICAL layoutAlign=STRETCH ← would-be propagated, but R-grp is HUG
+ *                   └── wrap HORIZONTAL+WRAP layoutAlign=STRETCH
+ *
+ * Everything from R-grp down is unanchored. `mid` and `wrap` each carry
+ * `layoutAlign=STRETCH` but their parents' width chain is HUG-of-children.
+ * Figma resolves the deadlock by stamping the frame-creation default
+ * (~100px) at the topmost HUG and cascading STRETCH down to it.
+ *
+ * The applier flips each unanchored-STRETCH child's `layoutAlign` to
+ * `INHERIT` and resets its horizontal sizing axis to AUTO so the chain
+ * resolves to natural HUG widths from the bottom up — the same result
+ * CSS computes via max-content.
+ */
+
+// ---------------------------------------------------------------------------
+// Stub-frame harness — minimal FrameNode mock with parent links.
+// ---------------------------------------------------------------------------
+
+interface StubFrame {
+  type: 'FRAME';
+  name: string;
+  layoutMode: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+  layoutPositioning: 'AUTO' | 'ABSOLUTE';
+  primaryAxisSizingMode: 'AUTO' | 'FIXED';
+  counterAxisSizingMode: 'AUTO' | 'FIXED';
+  primaryAxisAlignItems: string;
+  counterAxisAlignItems: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH' | 'BASELINE';
+  layoutAlign: 'INHERIT' | 'STRETCH' | 'MIN' | 'CENTER' | 'MAX';
+  layoutGrow: number;
+  width: number;
+  height: number;
+  parent: StubFrame | null;
+  children: StubFrame[];
+  appendChild(child: StubFrame): void;
+}
+
+function mkFrame(name: string): StubFrame {
+  return {
+    type: 'FRAME',
+    name,
+    layoutMode: 'NONE',
+    layoutPositioning: 'AUTO',
+    primaryAxisSizingMode: 'AUTO',
+    counterAxisSizingMode: 'AUTO',
+    primaryAxisAlignItems: 'MIN',
+    counterAxisAlignItems: 'MIN',
+    layoutAlign: 'INHERIT',
+    layoutGrow: 0,
+    width: 100,
+    height: 100,
+    parent: null,
+    children: [],
+    appendChild(child) {
+      child.parent = this;
+      this.children.push(child);
+    },
+  };
+}
+
+interface FrameInit {
+  name: string;
+  mode?: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+  primaryFixed?: boolean;
+  counterFixed?: boolean;
+  layoutAlign?: 'INHERIT' | 'STRETCH' | 'MIN' | 'CENTER' | 'MAX';
+  layoutGrow?: number;
+  width?: number;
+  height?: number;
+}
+
+function newFrame(init: FrameInit): StubFrame {
+  const f = mkFrame(init.name);
+  if (init.mode) f.layoutMode = init.mode;
+  if (init.primaryFixed) f.primaryAxisSizingMode = 'FIXED';
+  if (init.counterFixed) f.counterAxisSizingMode = 'FIXED';
+  if (init.layoutAlign) f.layoutAlign = init.layoutAlign;
+  if (init.layoutGrow != null) f.layoutGrow = init.layoutGrow;
+  if (init.width != null) f.width = init.width;
+  if (init.height != null) f.height = init.height;
+  return f;
+}
+
+const asNode = (f: StubFrame) => f as unknown as SceneNode;
+
+// ---------------------------------------------------------------------------
+// hasDefiniteWidth — propagation
+// ---------------------------------------------------------------------------
+
+// Authored root: any orphaned frame is treated as definite.
+{
+  const root = newFrame({ name: 'root', mode: 'VERTICAL', counterFixed: true, width: 1024 });
+  assert.equal(hasDefiniteWidth(asNode(root)), true, 'orphan root = definite');
+}
+
+// STRETCH child of VERTICAL parent that's definite → propagated.
+{
+  const root = newFrame({ name: 'root', mode: 'VERTICAL', counterFixed: true, width: 1024 });
+  const child = newFrame({ name: 'child', mode: 'VERTICAL', layoutAlign: 'STRETCH' });
+  root.appendChild(child);
+  assert.equal(
+    hasDefiniteWidth(asNode(child)), true,
+    'STRETCH child of definite VERTICAL parent = definite',
+  );
+}
+
+// INHERIT VERTICAL child of VERTICAL parent without authored FIXED width
+// → HUG counter, NOT propagated.
+{
+  const root = newFrame({ name: 'root', mode: 'VERTICAL', counterFixed: true, width: 1024 });
+  const child = newFrame({ name: 'child', mode: 'VERTICAL' });
+  root.appendChild(child);
+  assert.equal(
+    hasDefiniteWidth(asNode(child)), false,
+    'INHERIT HUG-counter VERTICAL child of VERTICAL parent = not propagated',
+  );
+}
+
+// GROW child of HORIZONTAL parent that's definite → propagated.
+{
+  const root = newFrame({ name: 'root', mode: 'HORIZONTAL', primaryFixed: true, width: 1024 });
+  const child = newFrame({ name: 'child', mode: 'HORIZONTAL', layoutGrow: 1 });
+  root.appendChild(child);
+  assert.equal(
+    hasDefiniteWidth(asNode(child)), true,
+    'GROW child of definite HORIZONTAL parent = definite',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// hasDefiniteWidth — explicit-FIXED short-circuit
+// ---------------------------------------------------------------------------
+
+// HORIZONTAL frame with primary=FIXED width=400 and layoutAlign=INHERIT is
+// authored — even if its parent's chain isn't definite, the frame's own
+// width is authored. CardHeader-shape: nested under a HUG-primary ancestor
+// but explicitly sized by applyFullWidthIfPossible / w-[Npx].
+{
+  const unknownParent = newFrame({ name: 'parent', mode: 'VERTICAL' });
+  const fixed = newFrame({
+    name: 'fixed', mode: 'HORIZONTAL', primaryFixed: true, width: 400,
+  });
+  unknownParent.appendChild(fixed);
+  assert.equal(
+    hasDefiniteWidth(asNode(fixed)), true,
+    'HORIZONTAL primary=FIXED + align!=STRETCH = authored definite',
+  );
+}
+
+// HORIZONTAL frame with primary=FIXED but layoutAlign=STRETCH is NOT
+// authored — the FIXED is a Figma side-effect of STRETCH. Must fall
+// through to parent propagation.
+{
+  const unknownParent = newFrame({ name: 'parent', mode: 'VERTICAL' });
+  const sideEffect = newFrame({
+    name: 'side', mode: 'HORIZONTAL', primaryFixed: true, width: 100,
+    layoutAlign: 'STRETCH',
+  });
+  unknownParent.appendChild(sideEffect);
+  // Parent is orphan = root = definite. STRETCH child of VERTICAL parent
+  // propagates from parent → definite.
+  assert.equal(
+    hasDefiniteWidth(asNode(sideEffect)), true,
+    'STRETCH of definite VERTICAL parent propagates regardless of own FIXED side-effect',
+  );
+}
+
+// Same shape but inside a non-definite chain → the STRETCH side-effect FIXED
+// must not trick the predicate into definite.
+{
+  const horizParent = newFrame({ name: 'hp', mode: 'HORIZONTAL' });
+  const vertHug = newFrame({ name: 'v', mode: 'VERTICAL' });
+  horizParent.appendChild(vertHug);
+  const sideEffect = newFrame({
+    name: 'side', mode: 'HORIZONTAL', primaryFixed: true, width: 100,
+    layoutAlign: 'STRETCH',
+  });
+  vertHug.appendChild(sideEffect);
+  // horizParent is root-orphan = definite. But vertHug is layoutGrow=0 in
+  // HORIZONTAL parent → not propagated → vertHug is NOT definite.
+  // Therefore STRETCH child of vertHug is also NOT definite.
+  assert.equal(
+    hasDefiniteWidth(asNode(vertHug)), false,
+    'HUG-primary child of HORIZONTAL parent breaks chain (per the bug shape)',
+  );
+  assert.equal(
+    hasDefiniteWidth(asNode(sideEffect)), false,
+    'STRETCH-of-unanchored-parent + FIXED side-effect = still NOT definite',
+  );
+}
+
+// VERTICAL frame with counter=FIXED + align=INHERIT = authored definite.
+{
+  const wrapper = newFrame({ name: 'w', mode: 'VERTICAL' });
+  const fixed = newFrame({
+    name: 'fixed', mode: 'VERTICAL', counterFixed: true, width: 400,
+  });
+  wrapper.appendChild(fixed);
+  assert.equal(hasDefiniteWidth(asNode(fixed)), true, 'VERTICAL counter=FIXED + align=INHERIT authored');
+}
+
+// ---------------------------------------------------------------------------
+// isUnanchoredStretchChild — the canonical bug shape
+// ---------------------------------------------------------------------------
+
+// MarketPriceCard chain: chain breaks at the right-group (HUG primary
+// inside HORIZONTAL parent). Everything below is unanchored STRETCH.
+{
+  const story = newFrame({ name: 'story', mode: 'VERTICAL', counterFixed: true, width: 1024 });
+  const card = newFrame({ name: 'card', mode: 'VERTICAL', layoutAlign: 'STRETCH' });
+  const hdr = newFrame({
+    name: 'hdr', mode: 'HORIZONTAL', primaryFixed: true, width: 952, layoutAlign: 'STRETCH',
+  });
+  const rgrp = newFrame({ name: 'rgrp', mode: 'VERTICAL', layoutGrow: 0 });
+  const mid = newFrame({
+    name: 'mid', mode: 'VERTICAL', layoutAlign: 'STRETCH', primaryFixed: true, width: 100,
+  });
+  const wrap = newFrame({
+    name: 'wrap', mode: 'HORIZONTAL', layoutAlign: 'STRETCH', primaryFixed: true, width: 100,
+  });
+  story.appendChild(card);
+  card.appendChild(hdr);
+  hdr.appendChild(rgrp);
+  rgrp.appendChild(mid);
+  mid.appendChild(wrap);
+
+  assert.equal(hasDefiniteWidth(asNode(rgrp)), false, 'rgrp breaks chain (HUG primary in HORIZONTAL hdr)');
+  assert.equal(hasDefiniteWidth(asNode(mid)), false, 'mid: STRETCH of unanchored parent');
+  assert.equal(hasDefiniteWidth(asNode(wrap)), false, 'wrap: STRETCH of unanchored parent');
+
+  assert.equal(isUnanchoredStretchChild(asNode(card)), false, 'card: STRETCH of definite parent — anchored');
+  assert.equal(isUnanchoredStretchChild(asNode(hdr)), false, 'hdr: STRETCH of definite parent (card) — anchored');
+  assert.equal(isUnanchoredStretchChild(asNode(rgrp)), false, 'rgrp: layoutAlign=INHERIT, not a stretch child');
+  assert.equal(isUnanchoredStretchChild(asNode(mid)), true, 'mid: unanchored stretch — flag');
+  assert.equal(isUnanchoredStretchChild(asNode(wrap)), true, 'wrap: unanchored stretch — flag');
+}
+
+// Restricted to VERTICAL parents only — STRETCH children of HORIZONTAL
+// parents are a height-deadlock concern, not a width-deadlock concern.
+{
+  const horiz = newFrame({ name: 'h', mode: 'HORIZONTAL' });
+  const child = newFrame({ name: 'c', layoutAlign: 'STRETCH' });
+  horiz.appendChild(child);
+  assert.equal(
+    isUnanchoredStretchChild(asNode(child)), false,
+    'STRETCH child of HORIZONTAL parent is OUT of scope (height-axis)',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// breakHugStretchDeadlocks — end-to-end flip on MarketPriceCard chain
+// ---------------------------------------------------------------------------
+
+{
+  const story = newFrame({ name: 'story', mode: 'VERTICAL', counterFixed: true, width: 1024 });
+  const card = newFrame({ name: 'card', mode: 'VERTICAL', layoutAlign: 'STRETCH' });
+  const hdr = newFrame({
+    name: 'hdr', mode: 'HORIZONTAL', primaryFixed: true, width: 952, layoutAlign: 'STRETCH',
+  });
+  const rgrp = newFrame({ name: 'rgrp', mode: 'VERTICAL', layoutGrow: 0 });
+  const mid = newFrame({
+    name: 'mid', mode: 'VERTICAL', layoutAlign: 'STRETCH',
+    primaryFixed: true, counterFixed: true, width: 100,
+  });
+  const wrap = newFrame({
+    name: 'wrap', mode: 'HORIZONTAL', layoutAlign: 'STRETCH',
+    primaryFixed: true, width: 100,
+  });
+  story.appendChild(card);
+  card.appendChild(hdr);
+  hdr.appendChild(rgrp);
+  rgrp.appendChild(mid);
+  mid.appendChild(wrap);
+
+  const stats = breakHugStretchDeadlocks(asNode(story));
+
+  // Anchored frames untouched.
+  assert.equal(card.layoutAlign, 'STRETCH', 'card untouched (anchored)');
+  assert.equal(hdr.layoutAlign, 'STRETCH', 'hdr untouched (anchored)');
+  // Unanchored stretch children flipped.
+  assert.equal(mid.layoutAlign, 'INHERIT', 'mid flipped to INHERIT');
+  assert.equal(wrap.layoutAlign, 'INHERIT', 'wrap flipped to INHERIT');
+  // Sizing axes reset to AUTO so children hug naturally.
+  assert.equal(mid.counterAxisSizingMode, 'AUTO', 'mid VERTICAL: counter reset to AUTO');
+  assert.equal(wrap.primaryAxisSizingMode, 'AUTO', 'wrap HORIZONTAL: primary reset to AUTO');
+
+  assert.equal(stats.alignmentFlips, 2, 'flip count = 2 (mid + wrap)');
+  assert.equal(stats.nodesWalked, 6, 'walked entire chain (story+card+hdr+rgrp+mid+wrap)');
+}
+
+// Pure-anchored tree: no flips at all.
+{
+  const story = newFrame({ name: 'story', mode: 'VERTICAL', counterFixed: true, width: 1024 });
+  const a = newFrame({ name: 'a', mode: 'VERTICAL', layoutAlign: 'STRETCH' });
+  const b = newFrame({ name: 'b', mode: 'VERTICAL', layoutAlign: 'STRETCH' });
+  story.appendChild(a);
+  a.appendChild(b);
+
+  const stats = breakHugStretchDeadlocks(asNode(story));
+
+  assert.equal(stats.alignmentFlips, 0, 'fully-anchored tree: no flips');
+  assert.equal(a.layoutAlign, 'STRETCH', 'a untouched');
+  assert.equal(b.layoutAlign, 'STRETCH', 'b untouched');
+}
+
+// Empty tree: walker doesn't crash on leaf nodes.
+{
+  const leaf = newFrame({ name: 'leaf', mode: 'NONE' });
+  const stats = breakHugStretchDeadlocks(asNode(leaf));
+  assert.equal(stats.alignmentFlips, 0);
+  assert.equal(stats.nodesWalked, 1);
+}
+
+console.log('intrinsic-sizing-regression: ok');

package/scanner/story-args-resolution-regression.ts

@@ -0,0 +1,270 @@
+import assert from 'node:assert/strict';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { ComponentScanner } from './component-scanner';
+
+/**
+ * Regression: story `args` resolution must handle three shapes that
+ * commonly appear in real consumer stories but were silently dropped or
+ * mis-parsed before:
+ *
+ * 1. **Spread of a shared base** (`...BASE_ARGS`) — the canonical pattern
+ *    for stories that mostly share args and only override one field:
+ *
+ *        const BASE_ARGS = { marketSymbol: "SOL", activeSide: "long", ... };
+ *        export const WithLegend = { args: { ...BASE_ARGS, markers: [...] } };
+ *
+ *    Previously the scanner only walked `Node.isPropertyAssignment`,
+ *    silently skipping `Node.isSpreadAssignment`. Every BASE_ARGS field
+ *    went missing from `argsContext`, so the component body saw
+ *    `marketSymbol = undefined` and rendered blank.
+ *
+ * 2. **`null` / `undefined` keyword literals** as story arg values —
+ *    e.g. `error: null` in BASE_ARGS. `parseLiteralValue` previously
+ *    fell through to `val.getText()` and returned the STRING `"null"`,
+ *    which is truthy. Conditionals like `{error && <Banner>{error}</Banner>}`
+ *    then rendered the banner with literal "null" text.
+ *
+ * 3. **Array literal property values** (`markers: [{...}, {...}]`) —
+ *    `resolveExpressionValue` doesn't handle ArrayLiteralExpression, so
+ *    the story-args loop set the arg to `undefined`. Inside the component
+ *    `{markers.length ? <Legend/> : null}` then evaluated `undefined.length`
+ *    → undefined → both branches skipped → legend missing. Fix: fall back
+ *    to `parseLiteralValue` (already used by `extractPropsFromNode` for
+ *    the JSX-prop equivalent).
+ *
+ * These fixes are exercised against an on-disk fixture project so the
+ * test models the production scan path (`pnpm inkbridge:scan`), not a
+ * synthetic in-memory variant.
+ */
+
+interface JsxNodeLike {
+  type: 'element' | 'text';
+  tagName?: string;
+  content?: string;
+  props?: Record<string, unknown>;
+  children?: JsxNodeLike[];
+}
+
+interface StoryShape {
+  name: string;
+  jsxTree?: JsxNodeLike;
+}
+
+interface ScannedShape {
+  name: string;
+  stories?: StoryShape[];
+}
+
+function findElement(node: JsxNodeLike | undefined | null, tag: string): JsxNodeLike | null {
+  if (!node || node.type !== 'element') return null;
+  if (node.tagName === tag) return node;
+  for (const child of node.children || []) {
+    const found = findElement(child, tag);
+    if (found) return found;
+  }
+  return null;
+}
+
+function findAllElements(node: JsxNodeLike | undefined | null, tag: string, out: JsxNodeLike[] = []): JsxNodeLike[] {
+  if (!node || node.type !== 'element') return out;
+  if (node.tagName === tag) out.push(node);
+  for (const child of node.children || []) findAllElements(child, tag, out);
+  return out;
+}
+
+function collectText(node: JsxNodeLike | undefined | null, out: string[] = []): string[] {
+  if (!node) return out;
+  if (node.type === 'text') {
+    if (typeof node.content === 'string') out.push(node.content);
+    return out;
+  }
+  for (const child of node.children || []) collectText(child, out);
+  return out;
+}
+
+const FIXTURE_DIR = path.resolve(
+  process.cwd(),
+  'tools/figma-plugin/scanner/__fixtures__/story-args-resolution'
+);
+
+// Write fixture files to disk. The scanner discovers components via glob,
+// so in-memory ts-morph files aren't enough — we need real files. Cleaned
+// up at end of run so re-runs are idempotent.
+function writeFixtures(): void {
+  fs.mkdirSync(FIXTURE_DIR, { recursive: true });
+  fs.writeFileSync(
+    path.join(FIXTURE_DIR, 'Card.tsx'),
+    `
+      export interface CardProps {
+        title: string;
+        subtitle: string;
+        error: string | null;
+        activeSide: "long" | "short";
+        items: Array<{ id: string; label: string }>;
+      }
+      export function Card({ title, subtitle, error, activeSide, items }: CardProps) {
+        return (
+          <div>
+            <h1>{title}</h1>
+            <p>{subtitle}</p>
+            {error && <div data-role="error-banner">{error}</div>}
+            <button data-active={activeSide === "long" ? "true" : "false"}>{activeSide}</button>
+            {items.length ? (
+              <ul>
+                {items.map((it) => <li data-id={it.id}>{it.label}</li>)}
+              </ul>
+            ) : null}
+          </div>
+        );
+      }
+    `,
+    'utf-8'
+  );
+  fs.writeFileSync(
+    path.join(FIXTURE_DIR, 'Card.stories.tsx'),
+    `
+      import { Card } from "./Card";
+      const meta = { component: Card };
+      export default meta;
+
+      const BASE_ARGS = {
+        title: "Hello",
+        subtitle: "from base",
+        error: null,
+        activeSide: "long" as const,
+        items: [],
+      };
+
+      // Case 1: spread of base + override with array literal. Exercises
+      // the SpreadAssignment branch AND the ArrayLiteralExpression fallback
+      // in the PropertyAssignment branch.
+      export const WithItems = {
+        args: {
+          ...BASE_ARGS,
+          items: [{ id: "a", label: "Alpha" }, { id: "b", label: "Beta" }],
+        },
+      };
+
+      // Case 2: spread that includes a \`null\` keyword literal. The base's
+      // \`error: null\` MUST NOT become the string "null" (which is truthy
+      // and would render the error banner).
+      export const NoError = {
+        args: { ...BASE_ARGS },
+      };
+
+      // Case 3: explicit override that flips a value. Verifies args
+      // ordering — properties after the spread win.
+      export const ShortSide = {
+        args: { ...BASE_ARGS, activeSide: "short" as const },
+      };
+    `,
+    'utf-8'
+  );
+}
+
+function cleanupFixtures(): void {
+  try {
+    fs.rmSync(FIXTURE_DIR, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+async function run(): Promise<void> {
+  writeFixtures();
+
+  const scanner = new ComponentScanner({
+    componentPaths: [FIXTURE_DIR],
+    filePattern: '*.tsx',
+    exclude: [],
+  });
+
+  const results = (await scanner.scanAll()) as unknown as ScannedShape[];
+  const card = results.find((r) => r.name === 'Card');
+  assert.ok(card, `must find the Card component; got names: ${results.map((r) => r.name).join(', ')}`);
+  const stories = card.stories || [];
+  const byName = (n: string) => stories.find((s) => s.name === n || s.name.replace(/\s+/g, '') === n);
+
+  // -------------------------------------------------------------------------
+  // Case 1: WithItems — spread + array literal override
+  // -------------------------------------------------------------------------
+  {
+    const story = byName('WithItems');
+    assert.ok(story?.jsxTree, 'WithItems story must produce a jsxTree');
+    const h1 = findElement(story.jsxTree, 'h1');
+    const h1Text = collectText(h1).join('');
+    assert.ok(
+      h1Text.includes('Hello'),
+      `WithItems should inherit title="Hello" from BASE_ARGS via spread; got "${h1Text}"`,
+    );
+    const items = findAllElements(story.jsxTree, 'li');
+    assert.equal(
+      items.length,
+      2,
+      `WithItems should render 2 <li> from the array-literal override; got ${items.length}`,
+    );
+    const ids = items.map((it) => it.props?.['data-id']).join(',');
+    assert.equal(
+      ids,
+      'a,b',
+      `array-literal story-arg must preserve object keys; got "${ids}"`,
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Case 2: NoError — spread including `error: null`
+  // -------------------------------------------------------------------------
+  {
+    const story = byName('NoError');
+    assert.ok(story?.jsxTree, 'NoError story must produce a jsxTree');
+    // The error banner is the only nested <div> with data-role="error-banner".
+    function findByRole(n: JsxNodeLike | undefined, role: string): JsxNodeLike | null {
+      if (!n || n.type !== 'element') return null;
+      if (n.props?.['data-role'] === role) return n;
+      for (const c of n.children || []) {
+        const f = findByRole(c, role);
+        if (f) return f;
+      }
+      return null;
+    }
+    const errBanner = findByRole(story.jsxTree, 'error-banner');
+    assert.equal(
+      errBanner,
+      null,
+      `null literal must not be coerced to truthy string "null" — error banner should be absent`,
+    );
+    // h1 still resolves the title from the base.
+    const h1 = findElement(story.jsxTree, 'h1');
+    const h1Text = collectText(h1).join('');
+    assert.ok(h1Text.includes('Hello'), `NoError should inherit title from BASE_ARGS; got "${h1Text}"`);
+  }
+
+  // -------------------------------------------------------------------------
+  // Case 3: ShortSide — explicit override after spread wins
+  // -------------------------------------------------------------------------
+  {
+    const story = byName('ShortSide');
+    assert.ok(story?.jsxTree, 'ShortSide story must produce a jsxTree');
+    const btn = findElement(story.jsxTree, 'button');
+    const btnText = collectText(btn).join('');
+    assert.ok(
+      btnText.includes('short'),
+      `explicit override should win over base; got button text "${btnText}"`,
+    );
+    assert.equal(
+      btn?.props?.['data-active'],
+      'false',
+      `activeSide override should flip the ternary; expected data-active="false" got "${btn?.props?.['data-active']}"`,
+    );
+  }
+
+  console.log('story-args-resolution-regression: PASS (3 cases)');
+}
+
+run()
+  .catch((err) => {
+    cleanupFixtures();
+    throw err;
+  })
+  .then(cleanupFixtures);

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

@@ -41,6 +41,7 @@ import {
   applyFullWidthIfPossible,
   applyRingIfPossible,
   applyVerticalFlexGrowIfPossible,
+  breakHugStretchDeadlocks,
   enforceGrowChildPrimaryFixed,
   extractGridColumns,
   extractMaxWidth,
@@ -552,6 +553,17 @@ function populateStoryLayout(
   // positions settle against the final heights.
   walkVerticalFlexGrow(layout);
 
+  // Break the STRETCH-in-HUG-chain deadlock that CSS resolves via
+  // max-content but Figma cannot. For every HUG container in an
+  // unanchored chain that broadcasts STRETCH to its children, flip
+  // counterAxisAlignItems to MIN so children hug naturally and the
+  // container hugs to the widest child. See
+  // `src/layout/intrinsic-sizing.ts` for the predicate contract and
+  // `src/layout/intrinsic-applier.ts` for the transform rationale.
+  // Runs before the absolute-reflow pass so width readings downstream
+  // see the post-flip values.
+  breakHugStretchDeadlocks(layout);
+
   // Final pass: resolve deferred absolute positioning after all story-level
   // width/height/layout operations have completed.
   reflowDeferredAbsolutePositioningTree(layout);

package/src/layout/index.ts

@@ -18,6 +18,8 @@ export {
 export type { LayoutIR, SizingMode } from './parser';
 export * from './width-solver';
 export * from './deferred-layout';
+export * from './intrinsic-sizing';
+export * from './intrinsic-applier';
 export * from './layout-utils';
 export * from './size-utils';
 export * from './ring-utils';