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

package/scanner/inline-flex-regression.ts

@@ -0,0 +1,235 @@
+import assert from 'node:assert/strict';
+
+(globalThis as unknown as { figma: unknown }).figma = {
+  notify: () => undefined,
+  showUI: () => undefined,
+  createFrame: () => makeStubFrame(),
+};
+
+import { LayoutParser, setFrameCrossAlign, setFrameFromBlockFlow, setFrameInlineAlign } from '../src/layout/layout-parser';
+
+// The recurring "pill renders full width" bug — see
+// `tools/figma-plugin/.ai/troubleshooting.md`. The root cause is that
+// `LayoutParser.applyChildProperties` runs after the per-class parser
+// (which sets `inline-flex` → HUG) and re-stretches inline-flex children
+// when the parent has cross-align STRETCH (which is the default for any
+// flex parent). Past fixes patched the per-class parser only, so any
+// refactor that didn't carry the exclusion through the implicit-stretch
+// path would silently re-introduce the bug.
+//
+// This fixture asserts the END-TO-END behaviour: after calling
+// `applyChildProperties`, an inline-flex child of a STRETCH-cross-align
+// vertical parent must NOT have `layoutAlign === 'STRETCH'`.
+
+type StubFrame = {
+  type: 'FRAME';
+  layoutMode: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+  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',
+    layoutMode: 'NONE',
+    primaryAxisSizingMode: 'AUTO',
+    counterAxisSizingMode: 'AUTO',
+    primaryAxisAlignItems: 'MIN',
+    counterAxisAlignItems: 'MIN',
+    layoutAlign: 'INHERIT',
+    layoutGrow: 0,
+    layoutSizingHorizontal: 'HUG',
+    layoutSizingVertical: 'HUG',
+    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; },
+  };
+}
+
+function runRegression(): void {
+  // The pill / chip / badge bug applies to inline-flex children of a
+  // BLOCK-FLOW parent (a regular `<div>` promoted to VERTICAL by the plugin
+  // even though CSS-wise it's not a flex container). In that context inline
+  // children hug content per CSS spec — the plugin's "implicit stretch"
+  // pass would otherwise stretch them to full card width.
+  //
+  // Real flex parents (`<div class="flex flex-col">`) are different:
+  // CSS `align-items: stretch` (the flex default) applies to ALL items
+  // including inline-flex, so dialog footer buttons / cancel-save pairs
+  // stretch to full width on mobile.
+
+  // ---- Case 1: inline-flex pill in a BLOCK-FLOW vertical parent —
+  // the actual how-it-works / round-trip-section pill bug. Pill must NOT
+  // stretch. -------------------------------------------------------------
+  const blockFlowCard = makeStubFrame();
+  blockFlowCard.layoutMode = 'VERTICAL';
+  blockFlowCard.width = 600;
+  blockFlowCard.primaryAxisSizingMode = 'FIXED';
+  setFrameCrossAlign(blockFlowCard as unknown as FrameNode, 'MIN');
+  setFrameFromBlockFlow(blockFlowCard as unknown as FrameNode, true);
+
+  const pill = makeStubFrame();
+  pill.layoutMode = 'HORIZONTAL'; // inline-flex sets HORIZONTAL
+  pill.layoutAlign = 'INHERIT';
+
+  LayoutParser.applyChildProperties(
+    pill as unknown as FrameNode,
+    'inline-flex items-center rounded-full px-3 py-1 text-sm font-medium'.split(' '),
+    blockFlowCard as unknown as FrameNode,
+  );
+
+  assert.notEqual(
+    pill.layoutAlign,
+    'STRETCH',
+    'inline-flex pill in a BLOCK-FLOW MIN parent must NOT be implicitly stretched',
+  );
+
+  // ---- Case 2: inline-block in BLOCK-FLOW parent — same exclusion. ----
+  const blockFlowCard2 = makeStubFrame();
+  blockFlowCard2.layoutMode = 'VERTICAL';
+  blockFlowCard2.width = 600;
+  blockFlowCard2.primaryAxisSizingMode = 'FIXED';
+  setFrameCrossAlign(blockFlowCard2 as unknown as FrameNode, 'MIN');
+  setFrameFromBlockFlow(blockFlowCard2 as unknown as FrameNode, true);
+
+  const inlineBlock = makeStubFrame();
+  inlineBlock.layoutAlign = 'INHERIT';
+  LayoutParser.applyChildProperties(
+    inlineBlock as unknown as FrameNode,
+    'inline-block px-2 py-1'.split(' '),
+    blockFlowCard2 as unknown as FrameNode,
+  );
+
+  assert.notEqual(
+    inlineBlock.layoutAlign,
+    'STRETCH',
+    'inline-block child of BLOCK-FLOW parent must also opt out of implicit STRETCH',
+  );
+
+  // ---- Case 3: block-level child of BLOCK-FLOW parent SHOULD stretch
+  // (plugin emulates items-stretch for block children even in non-flex
+  // parents — preserves the "items fill card" expectation). -------------
+  const blockFlowCard3 = makeStubFrame();
+  blockFlowCard3.layoutMode = 'VERTICAL';
+  blockFlowCard3.width = 600;
+  blockFlowCard3.primaryAxisSizingMode = 'FIXED';
+  setFrameCrossAlign(blockFlowCard3 as unknown as FrameNode, 'MIN');
+  setFrameFromBlockFlow(blockFlowCard3 as unknown as FrameNode, true);
+
+  const blockChild = makeStubFrame();
+  blockChild.layoutMode = 'VERTICAL';
+  blockChild.layoutAlign = 'INHERIT';
+
+  LayoutParser.applyChildProperties(
+    blockChild as unknown as FrameNode,
+    'flex flex-col gap-2'.split(' '),
+    blockFlowCard3 as unknown as FrameNode,
+  );
+
+  assert.equal(
+    blockChild.layoutAlign,
+    'STRETCH',
+    'block-level child SHOULD stretch in BLOCK-FLOW parent (plugin emulates items-stretch)',
+  );
+
+  // ---- Case 4: inline-flex BUTTON in a REAL FLEX parent SHOULD stretch
+  // (CSS default `align-items: stretch` applies to inline-flex flex items).
+  // The dialog footer at base breakpoint: `<DialogFooter className="flex
+  // flex-col-reverse">` with `<Button>` (inline-flex) — buttons must
+  // stretch to full footer width on mobile. ------------------------------
+  const flexFooter = makeStubFrame();
+  flexFooter.layoutMode = 'VERTICAL';
+  flexFooter.width = 400;
+  flexFooter.primaryAxisSizingMode = 'FIXED';
+  setFrameCrossAlign(flexFooter as unknown as FrameNode, 'STRETCH');
+  setFrameFromBlockFlow(flexFooter as unknown as FrameNode, false);
+
+  const button = makeStubFrame();
+  button.layoutMode = 'HORIZONTAL';
+  button.layoutAlign = 'INHERIT';
+
+  LayoutParser.applyChildProperties(
+    button as unknown as FrameNode,
+    'inline-flex items-center justify-center h-9 px-4 py-2 rounded-md'.split(' '),
+    flexFooter as unknown as FrameNode,
+  );
+
+  assert.equal(
+    button.layoutAlign,
+    'STRETCH',
+    'inline-flex button in a REAL FLEX-col parent (CSS default items-stretch) SHOULD stretch — dialog footer base breakpoint',
+  );
+
+  // ---- Case 5: inline-flex pill in BLOCK-FLOW MIN parent WITH text-center
+  // CSS centers inline content via the parent's text-align — the round-trip
+  // section pill `<span class="inline-flex ...">Round-trip in motion</span>`
+  // inside `<div class="text-center">` should appear horizontally centered.
+  // The pill must NOT stretch (case 1 rule), but its
+  // counterAxisAlignSelf should be CENTER so it sits at parent's center.
+  const centeredBlockParent = makeStubFrame() as StubFrame & { counterAxisAlignSelf?: string };
+  centeredBlockParent.layoutMode = 'VERTICAL';
+  centeredBlockParent.width = 600;
+  centeredBlockParent.primaryAxisSizingMode = 'FIXED';
+  setFrameCrossAlign(centeredBlockParent as unknown as FrameNode, 'MIN');
+  setFrameFromBlockFlow(centeredBlockParent as unknown as FrameNode, true);
+  setFrameInlineAlign(centeredBlockParent as unknown as FrameNode, 'CENTER');
+
+  const centeredPill = makeStubFrame() as StubFrame & { counterAxisAlignSelf?: string };
+  centeredPill.layoutMode = 'HORIZONTAL';
+  centeredPill.layoutAlign = 'INHERIT';
+  centeredPill.counterAxisAlignSelf = 'AUTO';
+
+  LayoutParser.applyChildProperties(
+    centeredPill as unknown as FrameNode,
+    'inline-flex items-center rounded-full px-3 py-1 text-sm font-medium'.split(' '),
+    centeredBlockParent as unknown as FrameNode,
+  );
+
+  assert.notEqual(
+    centeredPill.layoutAlign,
+    'STRETCH',
+    'pill in text-center block-flow parent must still NOT stretch',
+  );
+  assert.equal(
+    centeredPill.counterAxisAlignSelf,
+    'CENTER',
+    'pill in text-center block-flow parent SHOULD be horizontally centered via counterAxisAlignSelf',
+  );
+}
+
+try {
+  runRegression();
+  console.log('inline-flex-regression: PASS');
+} catch (err) {
+  console.error('inline-flex-regression: FAIL');
+  console.error(err);
+  process.exit(1);
+}

package/scanner/input-range-regression.ts

@@ -0,0 +1,217 @@
+import assert from 'node:assert/strict';
+
+import { transformInputNodes } from '../src/tailwind/node-ir';
+import type { NodeIR } from '../src/tailwind/node-ir';
+
+/**
+ * Regression: `<input type="range">` is rewritten by `transformInputNodes`
+ * in `src/tailwind/node-ir.ts` into a synthetic 3-child tree (track +
+ * filled indicator + thumb). Locks:
+ *
+ *   1. The rewrite fires only for `type="range"` (other input types pass
+ *      through untouched).
+ *   2. Geometry is `((value - min) / (max - min)) * 100`.
+ *   3. `defaultValue` is honored when `value` is missing.
+ *   4. `disabled` adds `opacity-50` to the wrapper.
+ *   5. Sizing classes from the consumer (`w-full`, paddings) survive on
+ *      the wrapper.
+ *
+ * Why this fixture exists: a previous version of the plugin had no
+ * rendering path for `type="range"`. The default input branch in
+ * `ui-builder.ts` reads `value/defaultValue/placeholder` as text — for
+ * range that meant either a tiny "5" text node or, more often, an
+ * infinite hang as downstream layout deferred-pass solvers stalled on a
+ * 0-content frame with `w-full accent-primary`. The transform produces
+ * a real visual structure the existing pipeline renders cleanly.
+ */
+
+// Minimal helpers (props are always stringified by the scanner — mirror
+// that here so assertions match real-world IR input).
+
+function inputEl(props: Record<string, string>, classes: string[] = []): NodeIR {
+  return {
+    kind: 'element',
+    tagName: 'input',
+    tagLower: 'input',
+    props,
+    classes,
+    children: [],
+  };
+}
+
+function rewrite(node: NodeIR): NodeIR {
+  return transformInputNodes(node);
+}
+
+function expectElement(node: NodeIR): Extract<NodeIR, { kind: 'element' }> {
+  assert.equal(node.kind, 'element', 'expected element node');
+  return node as Extract<NodeIR, { kind: 'element' }>;
+}
+
+// ---------------------------------------------------------------------------
+// (1) Bare `<input type="range">` with value/min/max → track + filled + thumb
+// ---------------------------------------------------------------------------
+
+{
+  const input = inputEl(
+    { type: 'range', min: '0', max: '100', value: '25' },
+    ['w-full', 'accent-primary'],
+  );
+  const out = rewrite(input);
+  const wrap = expectElement(out);
+
+  assert.equal(wrap.tagLower, 'div', 'rewrite produces a div wrapper');
+  // Structure mirrors shadcn Slider: track (flow child, contains filled),
+  // thumb (absolute sibling). Two top-level children, NOT three.
+  assert.equal(wrap.children.length, 2, 'wrapper has track + thumb');
+
+  // Consumer's sizing classes preserved on the wrapper; layout classes added.
+  assert.ok(wrap.classes.includes('w-full'), 'preserves consumer w-full');
+  assert.ok(wrap.classes.includes('relative'), 'wrapper is relative');
+  assert.ok(wrap.classes.includes('flex'), 'wrapper is flex');
+  assert.ok(wrap.classes.includes('items-center'), 'wrapper items-center');
+  assert.ok(wrap.classes.includes('h-4'), 'wrapper height set');
+
+  const [track, thumb] = wrap.children.map(expectElement);
+
+  // Track is a FLOW child (not absolute) — that's what gives the wrapper
+  // content to size against. Without this, all-absolute siblings collapse
+  // the auto-layout into a 0-content stall.
+  assert.ok(!track.classes.includes('absolute'), 'track is flow, not absolute');
+  assert.ok(track.classes.includes('w-full'), 'track full-width');
+  assert.ok(track.classes.includes('overflow-hidden'), 'track clips its fill');
+  assert.ok(track.classes.includes('bg-secondary'), 'track background neutral');
+
+  // Filled portion is a flow child of the track (not a sibling of it).
+  // No absolute positioning — sits at the left edge by natural flow.
+  assert.equal(track.children.length, 1, 'track has one filled child');
+  const filled = expectElement(track.children[0]);
+  assert.ok(!filled.classes.includes('absolute'), 'filled is flow inside track');
+  assert.ok(filled.classes.includes('w-[25%]'), 'filled width matches value');
+  assert.ok(filled.classes.includes('bg-primary'), 'filled paints accent');
+
+  // Thumb: absolute sibling positioned at 25% with -translate-x-1/2.
+  // No top-N — wrapper's h-4 + flex items-center centers via static position.
+  assert.ok(thumb.classes.includes('absolute'), 'thumb is absolute');
+  assert.ok(thumb.classes.includes('left-[25%]'), 'thumb at 25%');
+  assert.ok(thumb.classes.includes('-translate-x-1/2'), 'thumb centered on point');
+  assert.ok(thumb.classes.includes('rounded-full'), 'thumb circular');
+  assert.ok(!thumb.classes.some((c) => c.startsWith('top-')),
+    'thumb has no top-N — flex items-center on wrapper handles vertical centering');
+}
+
+// ---------------------------------------------------------------------------
+// (2) Non-zero min — the case from greenhouse-app LeverageSlider
+// ---------------------------------------------------------------------------
+
+{
+  // ((5 - 1.1) / (100 - 1.1)) * 100 ≈ 3.9434...
+  const input = inputEl({ type: 'range', min: '1.1', max: '100', value: '5' });
+  const out = rewrite(input);
+  const wrap = expectElement(out);
+  const track = expectElement(wrap.children[0]);
+  const filled = expectElement(track.children[0]);
+  const thumb = expectElement(wrap.children[1]);
+
+  // Match the value the transform actually emits (two-decimal precision,
+  // trailing-zero strip). Locking exact percentage prevents silent
+  // rounding drift.
+  const widthClass = filled.classes.find((c) => c.startsWith('w-['));
+  assert.equal(widthClass, 'w-[3.94%]', `got ${widthClass}`);
+
+  const leftClass = thumb.classes.find((c) => c.startsWith('left-['));
+  assert.equal(leftClass, 'left-[3.94%]', `got ${leftClass}`);
+}
+
+// ---------------------------------------------------------------------------
+// (3) `defaultValue` honored when `value` missing
+// ---------------------------------------------------------------------------
+
+{
+  const input = inputEl({ type: 'range', min: '0', max: '100', defaultValue: '75' });
+  const out = rewrite(input);
+  const wrap = expectElement(out);
+  const track = expectElement(wrap.children[0]);
+  const filled = expectElement(track.children[0]);
+
+  assert.ok(filled.classes.includes('w-[75%]'), 'defaultValue drives width');
+}
+
+// ---------------------------------------------------------------------------
+// (4) `disabled` adds opacity-50 to wrapper
+// ---------------------------------------------------------------------------
+
+{
+  const input = inputEl({ type: 'range', min: '0', max: '100', value: '50', disabled: 'true' });
+  const out = rewrite(input);
+  const wrap = expectElement(out);
+
+  assert.ok(wrap.classes.includes('opacity-50'), 'disabled adds opacity-50');
+}
+
+{
+  // disabled="false" should NOT trigger (some libs serialize false this way).
+  const input = inputEl({ type: 'range', min: '0', max: '100', value: '50', disabled: 'false' });
+  const out = rewrite(input);
+  const wrap = expectElement(out);
+
+  assert.ok(!wrap.classes.includes('opacity-50'), 'disabled=false does not dim');
+}
+
+// ---------------------------------------------------------------------------
+// (5) Non-range inputs pass through untouched
+// ---------------------------------------------------------------------------
+
+{
+  const before = inputEl({ type: 'text', placeholder: 'Name' }, ['h-10']);
+  const after = rewrite(before);
+  // Identity is preserved for non-range inputs (cache-friendly).
+  assert.equal(after, before, 'type=text returned by reference');
+}
+
+{
+  const before = inputEl({ type: 'number', value: '5' }, ['h-10']);
+  const after = rewrite(before);
+  assert.equal(after, before, 'type=number returned by reference');
+}
+
+// ---------------------------------------------------------------------------
+// (6) Missing value defaults to 0%
+// ---------------------------------------------------------------------------
+
+{
+  const input = inputEl({ type: 'range', min: '0', max: '100' });
+  const out = rewrite(input);
+  const wrap = expectElement(out);
+  const track = expectElement(wrap.children[0]);
+  const filled = expectElement(track.children[0]);
+
+  assert.ok(filled.classes.includes('w-[0%]'), 'missing value → 0% fill');
+}
+
+// ---------------------------------------------------------------------------
+// (7) Range inside a larger tree gets rewritten in place
+// ---------------------------------------------------------------------------
+
+{
+  const tree: NodeIR = {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes: ['p-4'],
+    children: [
+      inputEl({ type: 'range', min: '0', max: '100', value: '40' }, ['w-full']),
+    ],
+  };
+  const out = rewrite(tree);
+  const outer = expectElement(out);
+  assert.equal(outer.children.length, 1);
+  const slider = expectElement(outer.children[0]);
+  assert.equal(slider.children.length, 2, 'nested range rewritten (track + thumb)');
+  const track = expectElement(slider.children[0]);
+  const filled = expectElement(track.children[0]);
+  assert.ok(filled.classes.includes('w-[40%]'), 'nested range geometry correct');
+}
+
+console.log('input-range-regression: ok');

package/scanner/instance-rendering-regression.ts

@@ -0,0 +1,224 @@
+import assert from 'node:assert/strict';
+import {
+  appendResolvedInstance,
+  renderGuardedPortalStoryInstances,
+  renderStoryInstances,
+} from '../src/design-system/instance-rendering';
+import type {
+  ComponentDef,
+  ComponentInstance,
+  ComponentStory,
+  CvaAnalysis,
+  LayoutInfo,
+} from '../src/components';
+import type { StoryBuilderContext } from '../src/design-system/story-builder-context';
+
+/**
+ * Regression: instance-rendering is the Figma-API-heavy module that composes
+ * ComponentInstances into a Story Layout frame. Most of its surface needs a
+ * real Figma sandbox to exercise — but the early-return guards (no instances,
+ * no def name, missing analysis, unknown analysis type) are pure data and run
+ * before any Figma API call. Lock those.
+ *
+ * The full happy paths are exercised in real Figma during plugin runs.
+ *
+ * Extracted from `src/design-system/story-builder.ts` into
+ * `src/design-system/instance-rendering.ts`.
+ */
+
+// Minimal LayoutInfo stub — just captures appendChild calls and reports the
+// number of appended children. Used to assert that early-return paths do NOT
+// touch the layout.
+function makeLayoutStub(): { layout: LayoutInfo; appended: unknown[] } {
+  const appended: unknown[] = [];
+  const layout = {
+    appendChild: (node: unknown) => { appended.push(node); },
+    children: [],
+  } as unknown as LayoutInfo;
+  return { layout, appended };
+}
+
+function makeCtxStub(): StoryBuilderContext {
+  return {
+    getComponentDefByName: () => null,
+    normalizeComponentDef: (def: ComponentDef) => def,
+  } as unknown as StoryBuilderContext;
+}
+
+// ---------------------------------------------------------------------------
+// appendResolvedInstance — early-return guards
+// ---------------------------------------------------------------------------
+
+// null analysis → false, no layout touched
+{
+  const { layout, appended } = makeLayoutStub();
+  const result = appendResolvedInstance(
+    layout,
+    null as unknown as CvaAnalysis,
+    { componentName: 'X', props: {} } as ComponentInstance,
+    { name: 's', instances: [] } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(result, false, 'null analysis returns false');
+  assert.equal(appended.length, 0, 'null analysis must not touch layout — no appendChild calls');
+}
+
+// Unknown analysis.type → false, no layout touched
+{
+  const { layout, appended } = makeLayoutStub();
+  const result = appendResolvedInstance(
+    layout,
+    { type: 'mystery-type', name: 'X' } as unknown as CvaAnalysis,
+    { componentName: 'X', props: {} } as ComponentInstance,
+    { name: 's', instances: [] } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(result, false, 'unknown analysis.type returns false');
+  assert.equal(appended.length, 0, 'unknown type must not touch layout');
+}
+
+// ---------------------------------------------------------------------------
+// renderStoryInstances — empty / missing data
+// ---------------------------------------------------------------------------
+
+// story.instances undefined → 0, no layout touched
+{
+  const { layout, appended } = makeLayoutStub();
+  const added = renderStoryInstances(
+    layout,
+    { name: 's' } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(added, 0, 'no instances → 0 added');
+  assert.equal(appended.length, 0, 'no instances must not touch layout');
+}
+
+// Empty instances array → 0
+{
+  const { layout, appended } = makeLayoutStub();
+  const added = renderStoryInstances(
+    layout,
+    { name: 's', instances: [] } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(added, 0, 'empty instances array → 0 added');
+  assert.equal(appended.length, 0, 'empty instances array must not touch layout');
+}
+
+// Instances with falsy / nameless entries → skipped
+{
+  const { layout, appended } = makeLayoutStub();
+  const added = renderStoryInstances(
+    layout,
+    {
+      name: 's',
+      instances: [null, undefined, { componentName: '' }, { componentName: null }],
+    } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(added, 0, 'falsy / nameless instance entries are skipped — no fallback frames created');
+  assert.equal(appended.length, 0, 'no Figma frame creation triggered');
+}
+
+// ---------------------------------------------------------------------------
+// renderGuardedPortalStoryInstances — early-return guards
+// ---------------------------------------------------------------------------
+
+// No instances → 0
+{
+  const { layout, appended } = makeLayoutStub();
+  const added = renderGuardedPortalStoryInstances(
+    layout,
+    { name: 'Sheet' } as ComponentDef,
+    { name: 's' } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(added, 0, 'no instances → 0 added');
+  assert.equal(appended.length, 0, 'no layout touch');
+}
+
+// Empty def.name → 0 (normalizeComponentName returns empty key)
+{
+  const { layout, appended } = makeLayoutStub();
+  const added = renderGuardedPortalStoryInstances(
+    layout,
+    { name: '' } as ComponentDef,
+    {
+      name: 's',
+      instances: [{ componentName: 'SheetTrigger', props: {} }],
+    } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(added, 0, 'empty def name → 0 added (cannot key portal slots)');
+  assert.equal(appended.length, 0, 'no layout touch');
+}
+
+// Null def → 0
+{
+  const { layout, appended } = makeLayoutStub();
+  const added = renderGuardedPortalStoryInstances(
+    layout,
+    null as unknown as ComponentDef,
+    {
+      name: 's',
+      instances: [{ componentName: 'X', props: {} }],
+    } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(added, 0, 'null def → 0 added defensively');
+  assert.equal(appended.length, 0, 'no layout touch');
+}
+
+// All instances are the root container only (no trigger/content) → 0
+// (root instance is intentionally skipped — its visual content lives in slots)
+{
+  const { layout, appended } = makeLayoutStub();
+  const added = renderGuardedPortalStoryInstances(
+    layout,
+    { name: 'Sheet' } as ComponentDef,
+    {
+      name: 's',
+      instances: [
+        { componentName: 'Sheet', props: { open: false } },
+        { componentName: 'SheetProvider', props: {} },
+        { componentName: 'SheetPositioner', props: {} },
+      ],
+    } as unknown as ComponentStory,
+    'primary',
+    {},
+    null,
+    makeCtxStub(),
+  );
+  assert.equal(
+    added,
+    0,
+    'root + Provider + Positioner all skip — no trigger or content present',
+  );
+  assert.equal(appended.length, 0, 'no layout touch');
+}
+
+console.log('instance-rendering-regression: PASS');