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

package/scanner/full-width-matrix-regression.ts

@@ -0,0 +1,338 @@
+import assert from 'node:assert/strict';
+
+(globalThis as unknown as { figma: unknown }).figma = {
+  notify: () => undefined,
+  showUI: () => undefined,
+  createFrame: () => makeStubFrame(),
+};
+
+import {
+  applyFullWidthIfPossible,
+  markFullWidthNode,
+  markFullHeightNode,
+  markAbsoluteNode,
+  markCssGridVerticalFrame,
+} from '../src/layout/deferred-layout';
+
+// MATRIX REGRESSION — full-width / full-height resolution under varying
+// parent context.
+//
+// `applyFullWidthIfPossible` is the SECOND major pass where the "context-
+// dependent sizing" class of bug recurs. The per-class parser writes a
+// `FULL_WIDTH_NODES` / `FULL_HEIGHT_NODES` mark for `w-full` / `h-full`;
+// this pass later reads the mark + parent context and decides whether to:
+//   - set `layoutAlign=STRETCH` (vertical flex parent)
+//   - set `layoutGrow=1` (horizontal flex parent)
+//   - direct-resize (NONE parent, OR absolute child of any parent)
+//
+// Historical fix sites in this class (see troubleshooting.md and commit
+// d817a58):
+//   1. Absolute child with `h-full w-full` not resized in flex parents —
+//      old code only direct-resized when `parent.layoutMode === 'NONE'`,
+//      so absolute children of VERTICAL/HORIZONTAL parents got dead
+//      `layoutAlign='STRETCH'`/`layoutGrow=1` no-ops. Fix: added direct-
+//      resize branch for `childIsAbsolutePositioned`.
+//   2. CSS grid (single-column) children failed to stretch — fix:
+//      `CSS_GRID_VERTICAL_FRAMES.has(parent)` implies `hasFullWidth`.
+//   3. SPACE_BETWEEN parents had children consume all space — fix: set
+//      `layoutGrow=0` + `primaryAxisSizingMode='AUTO'` on `w-full` children
+//      of SPACE_BETWEEN parents.
+//   4. `mx-auto + max-w-N` resized child back to wrapper width — fix:
+//      structural check (`parent.name === 'mx-auto'` + `MAX_WIDTH_NODES`)
+//      bypasses the HORIZONTAL stretch branch.
+//   5. Reflow re-application stacked grid cards — fix in caller
+//      (`HORIZONTAL+WRAP` skip), NOT in this function directly. Out of
+//      scope for this matrix; covered by `aspect-percent-position-
+//      regression.ts`.
+//
+// Cells assert the final state of `layoutAlign`, `layoutGrow`, and
+// post-resize `width` for every (child intent, parent context) cross
+// product.
+
+type StubFrame = {
+  type: 'FRAME';
+  name: string;
+  layoutMode: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+  layoutPositioning: 'AUTO' | 'ABSOLUTE';
+  primaryAxisSizingMode: 'AUTO' | 'FIXED';
+  counterAxisSizingMode: 'AUTO' | 'FIXED';
+  primaryAxisAlignItems: string;
+  counterAxisAlignItems: string;
+  layoutAlign: string;
+  layoutGrow: number;
+  layoutSizingHorizontal: 'HUG' | 'FIXED' | 'FILL';
+  layoutSizingVertical: 'HUG' | 'FIXED' | 'FILL';
+  counterAxisAlignSelf: string;
+  width: number;
+  height: number;
+  paddingLeft: number;
+  paddingRight: number;
+  paddingTop: number;
+  paddingBottom: number;
+  fills: unknown[];
+  strokes: unknown[];
+  effects: unknown[];
+  children: never[];
+  appendChild(): void;
+  resize(w: number, h: number): void;
+};
+
+function makeStubFrame(): StubFrame {
+  return {
+    type: 'FRAME',
+    name: '',
+    layoutMode: 'NONE',
+    layoutPositioning: 'AUTO',
+    primaryAxisSizingMode: 'AUTO',
+    counterAxisSizingMode: 'AUTO',
+    primaryAxisAlignItems: 'MIN',
+    counterAxisAlignItems: 'MIN',
+    layoutAlign: 'INHERIT',
+    layoutGrow: 0,
+    layoutSizingHorizontal: 'HUG',
+    layoutSizingVertical: 'HUG',
+    counterAxisAlignSelf: 'AUTO',
+    width: 0,
+    height: 0,
+    paddingLeft: 0,
+    paddingRight: 0,
+    paddingTop: 0,
+    paddingBottom: 0,
+    fills: [],
+    strokes: [],
+    effects: [],
+    children: [],
+    appendChild() { /* no-op */ },
+    resize(w, h) { this.width = w; this.height = h; },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Parent factories. Sized at width=600 so cells can assert numeric resizes
+// where applicable.
+// ---------------------------------------------------------------------------
+
+type ParentKind =
+  | 'flex-col-fixed-cross'    // VERTICAL, counterAxisSizing=FIXED — resize-on-stretch fires
+  | 'flex-col-hug-cross'      // VERTICAL, counterAxisSizing=AUTO — STRETCH only, no resize
+  | 'flex-row-fixed-primary'  // HORIZONTAL, primaryAxisSizing=FIXED — grow + resize
+  | 'positioning-container'   // NONE — direct resize for anything marked w-full
+  | 'css-grid-vertical'       // VERTICAL + CSS_GRID_VERTICAL_FRAMES → implicit w-full;
+  | 'flex-row-space-between'; // HORIZONTAL with SPACE_BETWEEN — special case
+
+function makeParent(kind: ParentKind): FrameNode {
+  const parent = makeStubFrame();
+  parent.width = 600;
+  switch (kind) {
+    case 'flex-col-fixed-cross':
+      parent.layoutMode = 'VERTICAL';
+      parent.primaryAxisSizingMode = 'AUTO';
+      parent.counterAxisSizingMode = 'FIXED';
+      break;
+    case 'flex-col-hug-cross':
+      parent.layoutMode = 'VERTICAL';
+      parent.primaryAxisSizingMode = 'AUTO';
+      parent.counterAxisSizingMode = 'AUTO';
+      break;
+    case 'flex-row-fixed-primary':
+      parent.layoutMode = 'HORIZONTAL';
+      parent.primaryAxisSizingMode = 'FIXED';
+      parent.counterAxisSizingMode = 'AUTO';
+      break;
+    case 'positioning-container':
+      parent.layoutMode = 'NONE';
+      break;
+    case 'css-grid-vertical':
+      parent.layoutMode = 'VERTICAL';
+      parent.primaryAxisSizingMode = 'AUTO';
+      parent.counterAxisSizingMode = 'FIXED';
+      markCssGridVerticalFrame(parent as unknown as FrameNode);
+      break;
+    case 'flex-row-space-between':
+      parent.layoutMode = 'HORIZONTAL';
+      parent.primaryAxisSizingMode = 'FIXED';
+      parent.primaryAxisAlignItems = 'SPACE_BETWEEN';
+      parent.counterAxisSizingMode = 'AUTO';
+      break;
+  }
+  return parent as unknown as FrameNode;
+}
+
+// ---------------------------------------------------------------------------
+// Child factories. Marks set here mimic what tailwind.ts records for the
+// relevant utility classes.
+// ---------------------------------------------------------------------------
+
+type ChildKind =
+  | 'w-full'              // <div class="w-full">
+  | 'absolute-w-full'     // <div class="absolute w-full">
+  | 'absolute-w-h-full'   // <div class="absolute h-full w-full"> — SVG overlay
+  | 'unmarked';           // <div class="p-4"> — no width directive; sanity check
+
+function makeChild(kind: ChildKind): FrameNode {
+  const child = makeStubFrame();
+  child.width = 24;   // simulate Figma default
+  child.height = 24;
+  switch (kind) {
+    case 'w-full':
+      markFullWidthNode(child as unknown as FrameNode);
+      break;
+    case 'absolute-w-full':
+      child.layoutPositioning = 'ABSOLUTE';
+      markAbsoluteNode(child as unknown as FrameNode);
+      markFullWidthNode(child as unknown as FrameNode);
+      break;
+    case 'absolute-w-h-full':
+      child.layoutPositioning = 'ABSOLUTE';
+      markAbsoluteNode(child as unknown as FrameNode);
+      markFullWidthNode(child as unknown as FrameNode);
+      markFullHeightNode(child as unknown as FrameNode);
+      break;
+    case 'unmarked':
+      break;
+  }
+  return child as unknown as FrameNode;
+}
+
+// ---------------------------------------------------------------------------
+// Truth table. Each cell asserts the parts of the contract that matter for
+// the (child, parent) pair. `undefined` expectations are unchecked.
+// ---------------------------------------------------------------------------
+
+interface Cell {
+  child: ChildKind;
+  parent: ParentKind;
+  expect: {
+    layoutAlign?: 'INHERIT' | 'STRETCH';
+    layoutGrow?: number;
+    width?: number;
+    height?: number;
+  };
+  note: string;
+}
+
+const CELLS: Cell[] = [
+  // ---- w-full block child ------------------------------------------------
+  { child: 'w-full', parent: 'flex-col-fixed-cross',
+    expect: { layoutAlign: 'STRETCH', width: 600 },
+    note: 'w-full in vertical flex with FIXED cross-axis: STRETCH + resize' },
+  { child: 'w-full', parent: 'flex-col-hug-cross',
+    expect: { layoutAlign: 'STRETCH' },
+    note: 'w-full in vertical flex with AUTO cross-axis: STRETCH only, parent will hug to widest' },
+  { child: 'w-full', parent: 'flex-row-fixed-primary',
+    expect: { layoutGrow: 1, width: 600 },
+    note: 'w-full in horizontal flex: layoutGrow=1 + resize to parent.width' },
+  { child: 'w-full', parent: 'positioning-container',
+    expect: { width: 600 },
+    note: 'w-full in NONE parent (positioning container): direct resize' },
+  { child: 'w-full', parent: 'css-grid-vertical',
+    expect: { layoutAlign: 'STRETCH', width: 600 },
+    note: 'CSS-grid vertical (single column): children implicitly stretch' },
+  { child: 'w-full', parent: 'flex-row-space-between',
+    expect: { layoutGrow: 0 },
+    note: 'SPACE_BETWEEN parent: layoutGrow=0 so siblings get spaced (CSS justify-content)' },
+
+  // ---- absolute w-full child (no h-full) ---------------------------------
+  { child: 'absolute-w-full', parent: 'flex-col-fixed-cross',
+    expect: { width: 600 },
+    note: 'absolute child in vertical flex: direct-resize (per d817a58 fix)' },
+  { child: 'absolute-w-full', parent: 'flex-row-fixed-primary',
+    expect: { width: 600 },
+    note: 'absolute child in horizontal flex: direct-resize (NOT layoutGrow=1; that is a no-op)' },
+  { child: 'absolute-w-full', parent: 'positioning-container',
+    expect: { width: 600 },
+    note: 'absolute child in NONE parent: direct-resize (canonical absolute overlay)' },
+
+  // ---- absolute w-full + h-full (SVG overlay) ----------------------------
+  { child: 'absolute-w-h-full', parent: 'flex-col-fixed-cross',
+    expect: { width: 600 },
+    note: 'absolute overlay: width resizes regardless of parent layoutMode' },
+  { child: 'absolute-w-h-full', parent: 'positioning-container',
+    expect: { width: 600 },
+    note: 'absolute overlay in aspect-ratio container: width+height both resize (height tested below)' },
+
+  // ---- unmarked control (sanity) -----------------------------------------
+  { child: 'unmarked', parent: 'flex-col-fixed-cross',
+    expect: { layoutAlign: 'INHERIT', layoutGrow: 0, width: 24 },
+    note: 'no width directive: no changes' },
+  { child: 'unmarked', parent: 'flex-row-fixed-primary',
+    expect: { layoutAlign: 'INHERIT', layoutGrow: 0, width: 24 },
+    note: 'no width directive in horizontal parent: no changes' },
+];
+
+function runRegression(): void {
+  const failures: string[] = [];
+
+  for (const cell of CELLS) {
+    const parent = makeParent(cell.parent);
+    const child = makeChild(cell.child);
+
+    applyFullWidthIfPossible(child, parent);
+
+    const cellId = `${cell.child} × ${cell.parent}`;
+    const stub = child as unknown as StubFrame;
+
+    if (cell.expect.layoutAlign !== undefined) {
+      if (stub.layoutAlign !== cell.expect.layoutAlign) {
+        failures.push(
+          `${cellId}: expected layoutAlign=${cell.expect.layoutAlign}, got ${stub.layoutAlign}\n  → ${cell.note}`,
+        );
+      }
+    }
+    if (cell.expect.layoutGrow !== undefined) {
+      if (stub.layoutGrow !== cell.expect.layoutGrow) {
+        failures.push(
+          `${cellId}: expected layoutGrow=${cell.expect.layoutGrow}, got ${stub.layoutGrow}\n  → ${cell.note}`,
+        );
+      }
+    }
+    if (cell.expect.width !== undefined) {
+      if (stub.width !== cell.expect.width) {
+        failures.push(
+          `${cellId}: expected width=${cell.expect.width}, got ${stub.width}\n  → ${cell.note}`,
+        );
+      }
+    }
+    if (cell.expect.height !== undefined) {
+      if (stub.height !== cell.expect.height) {
+        failures.push(
+          `${cellId}: expected height=${cell.expect.height}, got ${stub.height}\n  → ${cell.note}`,
+        );
+      }
+    }
+  }
+
+  // Extra: absolute overlay in NONE parent should resize BOTH axes. The
+  // height branch fires after the width branch — assert here so the matrix
+  // covers the full-height direct-resize path that fix-sites have touched.
+  {
+    const parent = makeParent('positioning-container');
+    (parent as unknown as StubFrame).height = 400;
+    const child = makeChild('absolute-w-h-full');
+    applyFullWidthIfPossible(child, parent);
+    const stub = child as unknown as StubFrame;
+    if (stub.width !== 600) {
+      failures.push(`absolute-w-h-full × NONE: width should be 600, got ${stub.width}`);
+    }
+    if (stub.height !== 400) {
+      failures.push(
+        `absolute-w-h-full × NONE: height should be 400 (parent.height direct-resize), got ${stub.height}`,
+      );
+    }
+  }
+
+  if (failures.length > 0) {
+    for (const msg of failures) console.error('  ✗ ' + msg);
+    assert.fail(`${failures.length} full-width matrix cells failed`);
+  }
+
+  console.log(`full-width-matrix-regression: PASS (${CELLS.length} cells + height assertion)`);
+}
+
+try {
+  runRegression();
+} catch (err) {
+  console.error('full-width-matrix-regression: FAIL');
+  console.error(err);
+  process.exit(1);
+}

package/scanner/grid-cols-extraction-regression.ts

@@ -0,0 +1,110 @@
+import assert from 'node:assert/strict';
+
+import { extractGridColumns } from '../src/layout';
+
+/**
+ * Regression: `extractGridColumns` is the single source of truth for
+ * "how many columns does this Tailwind class list specify?" — consumed
+ * by both the story-bench and preview-builder reflow pipelines.
+ *
+ * The function intentionally returns `1` for plain `grid` (no explicit
+ * `grid-cols-N`) because Tailwind's default for `display: grid` is
+ * single-column flow, and the value is useful for responsive previews
+ * (so `sm:grid-cols-3` can flip the layout at a breakpoint). The
+ * downstream hazard: `applyGridColumnsIfPossible` would
+ * unconditionally flip the frame to `HORIZONTAL` + `WRAP` +
+ * `counterAxisSizingMode = AUTO`. A "1-column" reflow on a VERTICAL
+ * bench produces a single Hug row of children laid side-by-side
+ * instead of stacked.
+ *
+ * History: this bug class recurred at multiple call sites — every
+ * place that forwarded a `cols` value to `applyGridColumnsWithReflow`
+ * had to remember the `> 1` guard. preview-builder.ts:668 had the
+ * guard; story-builder.ts:491 didn't, so every `<div className="grid
+ * w-[Npx] gap-N">` story root rendered as a horizontal Hug-width row.
+ * The guard now lives inside `applyGridColumnsIfPossible` itself, so
+ * the contract is "forward whatever cols you extracted, the helper
+ * decides".
+ *
+ * This file locks the function's return values so the helper's
+ * `cols <= 1` early-return keeps its meaning. Drift in either
+ * direction (returning `null` for plain grid, or returning `> 1` for a
+ * single-column source) would either silently break responsive
+ * previews or re-introduce the horizontal-bench bug.
+ */
+
+// Plain `grid` with no explicit columns → implicit single-column flow.
+// Call sites MUST guard with `> 1` before applying a column reflow.
+assert.equal(
+  extractGridColumns(['grid']),
+  1,
+  'plain `grid` → 1 (Tailwind default single-column flow)',
+);
+assert.equal(
+  extractGridColumns(['grid', 'gap-2']),
+  1,
+  '`grid gap-N` → 1',
+);
+assert.equal(
+  extractGridColumns(['grid', 'w-[360px]', 'gap-2']),
+  1,
+  '`grid w-[N] gap-N` → 1 (the FormField story shape)',
+);
+assert.equal(
+  extractGridColumns(['inline-grid']),
+  1,
+  'plain `inline-grid` → 1',
+);
+
+// Explicit `grid-cols-N` → that number, and downstream reflow IS
+// expected to fire.
+assert.equal(
+  extractGridColumns(['grid', 'grid-cols-2']),
+  2,
+  '`grid grid-cols-2` → 2',
+);
+assert.equal(
+  extractGridColumns(['grid', 'grid-cols-3', 'gap-4']),
+  3,
+  '`grid grid-cols-3 gap-N` → 3',
+);
+assert.equal(
+  extractGridColumns(['grid', 'grid-cols-12']),
+  12,
+  'multi-digit column count parsed',
+);
+
+// No grid at all → null. Call sites short-circuit without ambiguity.
+assert.equal(
+  extractGridColumns(['flex', 'flex-col', 'gap-2']),
+  null,
+  'flex layouts → null',
+);
+assert.equal(
+  extractGridColumns(['p-4', 'rounded-md']),
+  null,
+  'no display utility → null',
+);
+assert.equal(
+  extractGridColumns([]),
+  null,
+  'empty class list → null',
+);
+assert.equal(
+  extractGridColumns(undefined),
+  null,
+  'undefined input → null',
+);
+
+// Responsive `sm:grid-cols-N` without a base `grid-cols-N` — the function
+// reports the responsive column count when the BASE already has `grid`.
+// (The bench renders at `base` width by default, so without an
+// `availableWidth` hint, the function returns the responsive value as
+// the prevailing column count.)
+assert.equal(
+  extractGridColumns(['grid', 'sm:grid-cols-3']),
+  3,
+  'responsive grid-cols (no base cols) → responsive value',
+);
+
+console.log('grid-cols-extraction-regression: PASS (11 cases)');

package/scanner/image-src-collector-regression.ts

@@ -0,0 +1,204 @@
+import assert from 'node:assert/strict';
+
+import {
+  collectImageSrcs,
+  collectImageSrcsFromJsxTree,
+  looksLikeImageSrc,
+} from '../src/plugin/image-src-collector';
+import type { ComponentDef } from '../src/components';
+
+/**
+ * Regression: the prefetch step at the top of generation needs to collect
+ * every image `src` reachable from the scanned JSX trees. The old tagName
+ * filter (`tag === 'img' || tag === 'Image'`) silently skipped shadcn-style
+ * image wrappers like `<AvatarImage>` and `<AvatarPrimitive.Image>` — even
+ * though the renderer is willing to draw any leaf element whose `src` prop
+ * points at a fetchable path.
+ *
+ * Symptom: `<Avatar><AvatarImage src="/images/avatar.svg" /></Avatar>`
+ * rendered as an empty 40×40 frame in Figma because the src was never
+ * prefetched into `imageMap` / `svgMap`. Storybook showed the image fine.
+ *
+ * Fix: widen the collector to "any node with a `src` prop that looks like a
+ * path/URL," matching the renderer's tolerance. This file locks both
+ * primitives together — drift between scanner and renderer is what caused
+ * the bug in the first place.
+ */
+
+// ---------------------------------------------------------------------------
+// looksLikeImageSrc — what shapes the prefetch can resolve
+// ---------------------------------------------------------------------------
+
+const positiveSrcs: string[] = [
+  '/images/avatar.svg',
+  '/foo.png',
+  '/api/avatar?u=1',
+  'http://localhost:3000/img.png',
+  'https://cdn.example.com/x.jpg',
+  './local.svg',
+  '../parent.png',
+];
+
+for (const src of positiveSrcs) {
+  assert.equal(looksLikeImageSrc(src), true, 'must accept: ' + src);
+}
+
+const negativeSrcs: string[] = [
+  '',
+  'avatar.svg',           // bare filename — no path anchor, can't resolve
+  'src',                  // literal placeholder some scanners emit
+  'data:image/png;base64,AAAA', // browser handles data URLs directly
+  'blob:http://x/y',
+  'javascript:alert(1)',
+];
+
+for (const src of negativeSrcs) {
+  assert.equal(looksLikeImageSrc(src), false, 'must reject: ' + JSON.stringify(src));
+}
+
+// ---------------------------------------------------------------------------
+// collectImageSrcsFromJsxTree — walks the tree, captures any leaf with src
+// ---------------------------------------------------------------------------
+
+function el(tagName: string, props: Record<string, unknown>, children: unknown[] = []) {
+  return { type: 'element', tagName, props, children };
+}
+
+// (a) raw <img> still captured
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(el('img', { src: '/foo.png' }), out);
+  assert.deepEqual([...out], ['/foo.png'], '<img> src captured');
+}
+
+// (b) Next.js <Image> still captured
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(el('Image', { src: '/next.png' }), out);
+  assert.deepEqual([...out], ['/next.png'], 'Next.js <Image> src captured');
+}
+
+// (c) <AvatarImage> — the regression case
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(el('AvatarImage', { src: '/images/avatar.svg' }), out);
+  assert.deepEqual([...out], ['/images/avatar.svg'], 'AvatarImage src captured (new behaviour)');
+}
+
+// (d) <AvatarPrimitive.Image> — namespaced primitive
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(el('AvatarPrimitive.Image', { src: '/x.svg' }), out);
+  assert.deepEqual([...out], ['/x.svg'], 'namespaced image primitive src captured');
+}
+
+// (e) nested children — recurses
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(
+    el('Avatar', {}, [
+      el('AvatarImage', { src: '/a.svg' }),
+      el('AvatarFallback', {}, [{ type: 'text', content: 'CN' }]),
+    ]),
+    out,
+  );
+  assert.deepEqual([...out], ['/a.svg'], 'recursed into Avatar wrapper');
+}
+
+// (f) multiple images deduped
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(
+    el('section', {}, [
+      el('img', { src: '/a.png' }),
+      el('AvatarImage', { src: '/a.png' }),
+      el('img', { src: '/b.png' }),
+    ]),
+    out,
+  );
+  assert.deepEqual([...out].sort(), ['/a.png', '/b.png'], 'duplicates collapsed via Set');
+}
+
+// (g) literal 'src' placeholder and missing src — ignored
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(
+    el('img', { src: 'src' }), // some scanners emit this for unresolved attrs
+    out,
+  );
+  collectImageSrcsFromJsxTree(el('img', {}), out);
+  assert.equal(out.size, 0, 'placeholder + missing src do not pollute output');
+}
+
+// (h) data: URL — not captured (browser handles directly)
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(
+    el('img', { src: 'data:image/png;base64,AAAA' }),
+    out,
+  );
+  assert.equal(out.size, 0, 'data: URL is not a prefetch candidate');
+}
+
+// (i) src prop on a wrapping component with children — STILL captured
+// (the renderer's "leaf" rule is enforced there, not here; the collector
+// is intentionally generous so renderer changes never need a follow-up
+// collector change).
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(
+    el('CustomFrame', { src: '/wrap.svg' }, [el('span', {}, [])]),
+    out,
+  );
+  assert.deepEqual([...out], ['/wrap.svg'], 'src on non-leaf is still collected (renderer decides usage)');
+}
+
+// (j) non-object / null tolerated
+{
+  const out = new Set<string>();
+  collectImageSrcsFromJsxTree(null, out);
+  collectImageSrcsFromJsxTree('not-a-node' as unknown, out);
+  collectImageSrcsFromJsxTree(undefined, out);
+  assert.equal(out.size, 0, 'null / non-object inputs are no-ops');
+}
+
+// ---------------------------------------------------------------------------
+// collectImageSrcs — walks every component's analysis and every story
+// ---------------------------------------------------------------------------
+
+{
+  const components: ComponentDef[] = [
+    {
+      analysis: {
+        jsxTree: el('Avatar', {}, [el('AvatarImage', { src: '/comp.svg' })]),
+        stories: [
+          { jsxTree: el('Avatar', {}, [el('AvatarImage', { src: '/story1.svg' })]) },
+          { jsxTree: el('Avatar', {}, [el('AvatarImage', { src: '/story2.svg' })]) },
+        ],
+      },
+    } as unknown as ComponentDef,
+    {
+      analysis: {
+        jsxTree: el('Card', {}, [el('img', { src: '/card.png' })]),
+        stories: [],
+      },
+    } as unknown as ComponentDef,
+    // Component with no analysis is tolerated.
+    { analysis: null } as unknown as ComponentDef,
+  ];
+
+  const srcs = collectImageSrcs(components).sort();
+  assert.deepEqual(
+    srcs,
+    ['/card.png', '/comp.svg', '/story1.svg', '/story2.svg'],
+    'collectImageSrcs walks component analysis + every story, tolerates missing analysis',
+  );
+}
+
+console.log(
+  'image-src-collector-regression: PASS ('
+    + positiveSrcs.length
+    + ' positive + '
+    + negativeSrcs.length
+    + ' negative URL cases + 10 tree cases + 1 component-level case)',
+);