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

package/manifest.json

@@ -25,6 +25,7 @@
     { "name": "Settings", "command": "settings" },
     { "separator": true },
     { "name": "Generate Design System Page", "command": "generate" },
+    { "name": "Clean Generated Artifacts", "command": "clean-generated" },
     { "name": "Debug Selection (Console)", "command": "debug-selection" }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "inkbridge",
-  "version": "0.1.0-beta.2",
-  "description": "Figma plugin that generates a pixel-accurate design system from your Tailwind React components.",
+  "version": "0.1.0-beta.21",
+  "description": "Generate a Figma design system from your Storybook stories — Tailwind React components rendered as native frames, design tokens, component states, and round-trip code sync.",
   "type": "module",
   "bin": {
     "inkbridge": "./bin/inkbridge.mjs"
@@ -19,21 +19,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "node build.mjs",
-    "watch": "node build.mjs --watch",
-    "doctor": "cd ../.. && node scripts/figma-doctor.mjs",
-    "scan": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/cli.ts",
-    "test:blob": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/blob-placement-regression.ts",
-    "test:tokens": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/css-token-reader-regression.ts",
-    "test:font": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/font-style-resolver-regression.ts",
-    "test:radial": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/radial-gradient-regression.ts",
-    "test:transform": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/transform-math-regression.ts",
-    "test:csspatch": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin-tailwind-tokens/scanner/css-patch-regression.ts",
-    "verify": "pnpm run scan && pnpm run test:blob && pnpm run test:tokens && pnpm run test:font && pnpm run test:radial && pnpm run test:transform && pnpm run test:csspatch && pnpm run build",
-    "postinstall": "node ./bin/inkbridge.mjs postinstall",
-    "prepublishOnly": "node build.mjs"
-  },
   "keywords": [
     "figma",
     "plugin",
@@ -42,10 +27,76 @@
     "storybook"
   ],
   "license": "MIT",
-  "homepage": "https://inkbridge.io",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/inkn9ne/inkbridge.git",
-    "directory": "tools/figma-plugin-tailwind-tokens"
+  "homepage": "https://inkbridge.ink",
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "tailwindcss": ">=4",
+    "postcss": ">=8"
+  },
+  "dependencies": {
+    "tailwind-merge": "^3.4.0",
+    "ts-morph": "^27.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node build.mjs --watch",
+    "doctor": "cd ../.. && node scripts/figma-doctor.mjs",
+    "scan": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/cli.ts",
+    "test:blob": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/blob-placement-regression.ts",
+    "test:tokens": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/css-token-reader-regression.ts",
+    "test:font": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/font-style-resolver-regression.ts",
+    "test:radial": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/radial-gradient-regression.ts",
+    "test:transform": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/transform-math-regression.ts",
+    "test:csspatch": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/css-patch-regression.ts",
+    "test:state-classification": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/state-classification-regression.ts",
+    "test:component-sections": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/component-sections-regression.ts",
+    "test:block-cache": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/block-cache-regression.ts",
+    "test:story-dimensioning": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/story-dimensioning-regression.ts",
+    "test:story-render-strategy": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/story-render-strategy-regression.ts",
+    "test:render-prop-parser": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/render-prop-parser-regression.ts",
+    "test:story-diagnostics": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/story-diagnostics-regression.ts",
+    "test:instance-rendering": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/instance-rendering-regression.ts",
+    "test:layout-spacing": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/layout-spacing-regression.ts",
+    "test:layout-sizing": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/layout-sizing-regression.ts",
+    "test:layout-alignment": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/layout-alignment-regression.ts",
+    "test:layout-flex": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/layout-flex-regression.ts",
+    "test:layout-mode": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/layout-mode-regression.ts",
+    "test:svg-marker": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/svg-marker-regression.ts",
+    "test:aspect-ratio": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/aspect-ratio-regression.ts",
+    "test:percent-position": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/percent-position-regression.ts",
+    "test:svg-fill-parent": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/svg-fill-parent-regression.ts",
+    "test:inline-flex": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/inline-flex-regression.ts",
+    "test:child-sizing-matrix": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/child-sizing-matrix-regression.ts",
+    "test:full-width-matrix": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/full-width-matrix-regression.ts",
+    "test:text-resize-matrix": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/text-resize-matrix-regression.ts",
+    "test:provider-flatten": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/provider-flatten-regression.ts",
+    "test:provider-cascade": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/provider-cascade-regression.ts",
+    "test:selection-pressed": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/selection-pressed-regression.ts",
+    "test:cva-jsx-child-fallback": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/cva-jsx-child-fallback-regression.ts",
+    "test:cva-master-icon": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/cva-master-icon-regression.ts",
+    "test:data-attr-prop-alias": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/data-attr-prop-alias-regression.ts",
+    "test:jsx-prop-unresolved": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/jsx-prop-unresolved-regression.ts",
+    "test:grid-cols-extraction": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/grid-cols-extraction-regression.ts",
+    "test:explicit-size-root": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/explicit-size-root-regression.ts",
+    "test:image-src-collector": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/image-src-collector-regression.ts",
+    "test:size-full-normalization": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/size-full-normalization-regression.ts",
+    "test:stretch-to-parent-width": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/stretch-to-parent-width-regression.ts",
+    "test:framework-adapter-shadcn": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/framework-adapter-shadcn-regression.ts",
+    "test:compound-classes-lookup": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/compound-classes-lookup-regression.ts",
+    "test:sandbox-spread": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/sandbox-spread-regression.ts",
+    "test:jsx-text": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/jsx-text-regression.ts",
+    "test:aspect-percent": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/aspect-percent-position-regression.ts",
+    "test:svg-group-inherit": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/svg-group-inheritance-regression.ts",
+    "test:svg-marker-inline": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/svg-marker-inline-regression.ts",
+    "test:bundle-size": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/bundle-size-regression.ts",
+    "test:ring-utility": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/ring-utility-regression.ts",
+    "test:adapter-utils": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/adapter-utils-regression.ts",
+    "test:input-range": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/input-range-regression.ts",
+    "test:font-family-extract": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/font-family-extract-regression.ts",
+    "test:local-const-className": "cd ../.. && ./node_modules/.bin/tsx tools/figma-plugin/scanner/local-const-className-regression.ts",
+    "docs:audit": "node ./scripts/docs-audit.mjs",
+    "verify": "pnpm run scan && pnpm run test:blob && pnpm run test:tokens && pnpm run test:font && pnpm run test:radial && pnpm run test:transform && pnpm run test:csspatch && pnpm run test:state-classification && pnpm run test:component-sections && pnpm run test:block-cache && pnpm run test:story-dimensioning && pnpm run test:story-render-strategy && pnpm run test:render-prop-parser && pnpm run test:story-diagnostics && pnpm run test:instance-rendering && pnpm run test:layout-spacing && pnpm run test:layout-sizing && pnpm run test:layout-alignment && pnpm run test:layout-flex && pnpm run test:layout-mode && pnpm run test:svg-marker && pnpm run test:aspect-ratio && pnpm run test:percent-position && pnpm run test:svg-fill-parent && pnpm run test:inline-flex && pnpm run test:child-sizing-matrix && pnpm run test:full-width-matrix && pnpm run test:text-resize-matrix && pnpm run test:provider-flatten && pnpm run test:provider-cascade && pnpm run test:selection-pressed && pnpm run test:cva-jsx-child-fallback && pnpm run test:cva-master-icon && pnpm run test:data-attr-prop-alias && pnpm run test:jsx-prop-unresolved && pnpm run test:grid-cols-extraction && pnpm run test:explicit-size-root && pnpm run test:image-src-collector && pnpm run test:size-full-normalization && pnpm run test:stretch-to-parent-width && pnpm run test:framework-adapter-shadcn && pnpm run test:compound-classes-lookup && pnpm run test:sandbox-spread && pnpm run test:jsx-text && pnpm run test:aspect-percent && pnpm run test:svg-group-inherit && pnpm run test:svg-marker-inline && pnpm run test:ring-utility && pnpm run test:adapter-utils && pnpm run test:input-range && pnpm run test:font-family-extract && pnpm run test:local-const-className && pnpm run docs:audit && pnpm run build && pnpm run test:bundle-size",
+    "release:beta": "pnpm publish --tag beta && npm dist-tag add inkbridge@$npm_package_version latest && npm view inkbridge dist-tags"
   }
-}
+}

package/scanner/adapter-utils-regression.ts

@@ -0,0 +1,159 @@
+import assert from 'node:assert/strict';
+
+import {
+  isClassedElement,
+  mergeMissing,
+  resolveValuePercents,
+} from '../src/tailwind/adapter-utils';
+import type { NodeIR } from '../src/tailwind/node-ir';
+
+/**
+ * Regression: `src/tailwind/adapter-utils.ts` is the shared toolbox both
+ * `framework-adapters/shadcn.ts` and `tailwind/node-ir.ts`'s native-HTML
+ * transforms call into. If these helpers drift, both adapters
+ * silently break — shadcn Slider thumbs end up at wrong positions and
+ * `<input type=range>` rewrites compute the wrong fill width.
+ */
+
+// ---------------------------------------------------------------------------
+// isClassedElement
+// ---------------------------------------------------------------------------
+
+{
+  const el: NodeIR = {
+    kind: 'element',
+    tagName: 'div',
+    tagLower: 'div',
+    props: {},
+    classes: [],
+    children: [],
+  };
+  const comp: NodeIR = {
+    kind: 'component',
+    tagName: 'Button',
+    tagLower: 'button',
+    props: {},
+    classes: [],
+    children: [],
+  };
+  const text: NodeIR = { kind: 'text', text: 'x' };
+  const frag: NodeIR = { kind: 'fragment', children: [] };
+
+  assert.equal(isClassedElement(el), true, 'element is classed');
+  assert.equal(isClassedElement(comp), true, 'component is classed');
+  assert.equal(isClassedElement(text), false, 'text is not classed');
+  assert.equal(isClassedElement(frag), false, 'fragment is not classed');
+}
+
+// ---------------------------------------------------------------------------
+// mergeMissing
+// ---------------------------------------------------------------------------
+
+{
+  // Empty extras → return existing by reference (cache-friendly).
+  const existing = ['a', 'b'];
+  const out = mergeMissing(existing, []);
+  assert.equal(out, existing, 'empty extras returns existing by reference');
+}
+
+{
+  // All extras already present → return existing by reference.
+  const existing = ['a', 'b', 'c'];
+  const out = mergeMissing(existing, ['b', 'c']);
+  assert.equal(out, existing, 'all present returns existing by reference');
+}
+
+{
+  // Some extras new → return a new array with originals + new ones in order.
+  const existing = ['a', 'b'];
+  const out = mergeMissing(existing, ['b', 'c', 'd']);
+  assert.notEqual(out, existing, 'new extras return a new array');
+  assert.deepEqual(out, ['a', 'b', 'c', 'd'], 'preserves order, de-dupes b');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — basic numeric input
+// ---------------------------------------------------------------------------
+
+{
+  // Default min=0, max=100: value 25 → 25%.
+  assert.deepEqual(resolveValuePercents(25, undefined, undefined), [25]);
+  // Default behavior with explicit undefined.
+  assert.deepEqual(resolveValuePercents(50, 0, 100), [50]);
+}
+
+{
+  // Non-zero min: (value - min) / (max - min) * 100.
+  // value=5, min=1.1, max=100 → ((5 - 1.1) / (100 - 1.1)) * 100 ≈ 3.9434
+  const out = resolveValuePercents(5, 1.1, 100);
+  assert.equal(out.length, 1);
+  assert.ok(Math.abs(out[0] - 3.9434) < 0.001, `got ${out[0]}`);
+}
+
+{
+  // Clamped to 0..100.
+  assert.deepEqual(resolveValuePercents(-50, 0, 100), [0], 'below-min clamps to 0');
+  assert.deepEqual(resolveValuePercents(200, 0, 100), [100], 'above-max clamps to 100');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — stringified props (scanner emits everything as
+// string)
+// ---------------------------------------------------------------------------
+
+{
+  assert.deepEqual(resolveValuePercents('25', '0', '100'), [25]);
+  // String min/max with non-zero baseline.
+  const out = resolveValuePercents('50', '0', '200');
+  assert.deepEqual(out, [25], 'string 50/200 → 25%');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — JSON array string (shadcn Slider tuple)
+// ---------------------------------------------------------------------------
+
+{
+  const out = resolveValuePercents('[25, 75]', 0, 100);
+  assert.deepEqual(out, [25, 75], 'JSON tuple parses both values');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — actual array
+// ---------------------------------------------------------------------------
+
+{
+  const out = resolveValuePercents([10, 50, 90], 0, 100);
+  assert.deepEqual(out, [10, 50, 90]);
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — degenerate ranges
+// ---------------------------------------------------------------------------
+
+{
+  // min === max → fallback range of 100.
+  const out = resolveValuePercents(5, 5, 5);
+  assert.equal(out.length, 1);
+  assert.equal(out[0], 0, 'min===max with value=min yields 0%');
+}
+
+{
+  // max < min → fallback. We don't care about specific number, just no crash
+  // and a finite result.
+  const out = resolveValuePercents(50, 100, 0);
+  assert.equal(out.length, 1);
+  assert.ok(Number.isFinite(out[0]), 'inverted min/max stays finite');
+}
+
+// ---------------------------------------------------------------------------
+// resolveValuePercents — unparseable value falls back to [0]
+// ---------------------------------------------------------------------------
+
+{
+  assert.deepEqual(resolveValuePercents(undefined, 0, 100), [0]);
+  assert.deepEqual(resolveValuePercents(null, 0, 100), [0]);
+  assert.deepEqual(resolveValuePercents('not-a-number', 0, 100), [0]);
+  assert.deepEqual(resolveValuePercents('', 0, 100), [0]);
+}
+
+console.log('adapter-utils-regression: ok');

package/scanner/aspect-percent-position-regression.ts

@@ -0,0 +1,237 @@
+import assert from 'node:assert/strict';
+
+(globalThis as unknown as { figma: unknown }).figma = {
+  notify: () => undefined,
+  showUI: () => undefined,
+};
+
+import {
+  applyAspectRatioIfPossible,
+  markAspectRatio,
+  markPositionInfo,
+  reflowDeferredAbsolutePositioningTree,
+} from '../src/layout/deferred-layout';
+
+/**
+ * Regression: an aspect-ratio container whose children are ALL absolutely
+ * positioned (e.g. the round-trip-section's triangle:
+ * `<div className="relative aspect-5/3 w-full">` with absolute icon nodes)
+ * must end up with the correct height by the time percent-position
+ * resolution runs.
+ *
+ * History: `applyAspectRatioIfPossible` is called eagerly during build,
+ * but the parent's `width` may still be 0 at that point (the mark is
+ * retained for retry). The final reflow pass
+ * (`reflowDeferredAbsolutePositioningTree`) used to call only the
+ * positioning resolvers — not the aspect-ratio retry — so the parent
+ * stayed at height=0, `applyDeferredPercentPositioning` bailed
+ * (`ph <= 0`), and percent-positioned children all stacked at y=0.
+ * The triangle of icons (Next.js top-left, Figma top-right, Storybook
+ * bottom-center) collapsed into a horizontal row.
+ */
+
+type StubChild = {
+  type: 'FRAME';
+  width: number;
+  height: number;
+  x: number;
+  y: number;
+  layoutPositioning: 'AUTO' | 'ABSOLUTE';
+};
+
+type StubFrame = {
+  type: 'FRAME';
+  layoutMode: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+  primaryAxisSizingMode: 'AUTO' | 'FIXED';
+  counterAxisSizingMode: 'AUTO' | 'FIXED';
+  width: number;
+  height: number;
+  children: StubChild[];
+  resize(w: number, h: number): void;
+};
+
+function makeChild(name: string): StubChild & { name: string } {
+  return {
+    type: 'FRAME',
+    name,
+    width: 40,
+    height: 40,
+    x: 0,
+    y: 0,
+    layoutPositioning: 'ABSOLUTE',
+  };
+}
+
+function makeAspectFrame(width: number): StubFrame {
+  const frame: StubFrame = {
+    type: 'FRAME',
+    layoutMode: 'VERTICAL',
+    primaryAxisSizingMode: 'AUTO',
+    counterAxisSizingMode: 'AUTO',
+    width,
+    height: 0, // hug-content with all-absolute children = 0
+    children: [],
+    resize(w, h) {
+      this.width = w;
+      this.height = h;
+    },
+  };
+  return frame;
+}
+
+// ---------------------------------------------------------------------------
+// Scenario A — direct simulation of the retry path.
+// applyAspectRatioIfPossible(frame) runs once with width=0 (early in build);
+// width settles afterwards; the reflow must retry and resolve to height=360.
+// ---------------------------------------------------------------------------
+{
+  const frame = makeAspectFrame(0);
+  markAspectRatio(frame as unknown as SceneNode, 5 / 3);
+
+  // First attempt: width=0, mark retained for retry.
+  applyAspectRatioIfPossible(frame as unknown as SceneNode);
+  assert.equal(frame.height, 0, 'first attempt with width=0 leaves height untouched');
+
+  // Width settles after some intermediate pass.
+  frame.resize(600, 0);
+
+  // Reflow must re-attempt the aspect-ratio resolution.
+  reflowDeferredAbsolutePositioningTree(frame as unknown as SceneNode);
+
+  assert.equal(frame.height, 360, 'reflow retry resolves height = 600 / (5/3) = 360');
+  assert.equal(frame.primaryAxisSizingMode, 'FIXED', 'reflow locks primary axis');
+  assert.equal(frame.counterAxisSizingMode, 'FIXED', 'reflow locks counter axis');
+}
+
+// ---------------------------------------------------------------------------
+// Scenario B — the actual round-trip-section pattern: aspect-5/3 parent with
+// three absolute children at percent positions. Before the fix, percent
+// positioning bailed (parent.height was 0); icons stacked at y=0.
+// ---------------------------------------------------------------------------
+{
+  const frame = makeAspectFrame(600);
+  markAspectRatio(frame as unknown as SceneNode, 5 / 3);
+
+  // Children mirror the NODES array: Next.js, Figma, Storybook.
+  const nextNode = makeChild('Next.js');
+  const figmaNode = makeChild('Figma');
+  const storybookNode = makeChild('Storybook');
+  frame.children.push(nextNode, figmaNode, storybookNode);
+
+  markPositionInfo(nextNode as unknown as SceneNode, {
+    leftPercent: 0.1833,
+    topPercent: 0.3056,
+  });
+  markPositionInfo(figmaNode as unknown as SceneNode, {
+    leftPercent: 0.8167,
+    topPercent: 0.3056,
+  });
+  markPositionInfo(storybookNode as unknown as SceneNode, {
+    leftPercent: 0.5,
+    topPercent: 0.8056,
+  });
+
+  // Simulate the "applyAspectRatioIfPossible ran early but width was 0" path
+  // by NOT calling it before reflow — the reflow must own the retry.
+  // (If we DID call it now it would resolve immediately because width is 600,
+  // which doesn't exercise the bug. The test in Scenario A pins that path;
+  // here we want to confirm reflow alone is sufficient.)
+  reflowDeferredAbsolutePositioningTree(frame as unknown as SceneNode);
+
+  assert.equal(frame.height, 360, 'reflow resolves aspect ratio to 360');
+
+  // Percent positions resolve against the now-final height.
+  assert.equal(Math.round(nextNode.x), Math.round(600 * 0.1833), 'Next.js x');
+  assert.equal(Math.round(nextNode.y), Math.round(360 * 0.3056), 'Next.js y');
+  assert.equal(Math.round(figmaNode.x), Math.round(600 * 0.8167), 'Figma x');
+  assert.equal(Math.round(figmaNode.y), Math.round(360 * 0.3056), 'Figma y');
+  assert.equal(Math.round(storybookNode.x), Math.round(600 * 0.5), 'Storybook x');
+  assert.equal(Math.round(storybookNode.y), Math.round(360 * 0.8056), 'Storybook y');
+
+  // Critical invariant: Storybook must sit BELOW the other two — that's the
+  // visual signal of a working triangle layout.
+  assert.ok(
+    storybookNode.y > nextNode.y && storybookNode.y > figmaNode.y,
+    `Storybook (y=${storybookNode.y}) must be below Next.js (y=${nextNode.y}) and Figma (y=${figmaNode.y})`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Scenario C — sanity: a frame with a NON-zero height should still resolve
+// the same way (aspect-ratio takes precedence and overrides intermediate
+// heights, matching CSS `aspect-ratio: 5/3`).
+// ---------------------------------------------------------------------------
+{
+  const frame = makeAspectFrame(600);
+  frame.height = 200; // intermediate value some pass may have set
+  markAspectRatio(frame as unknown as SceneNode, 5 / 3);
+
+  applyAspectRatioIfPossible(frame as unknown as SceneNode);
+  assert.equal(frame.height, 360, 'aspect-ratio overrides intermediate height');
+}
+
+// ---------------------------------------------------------------------------
+// Scenario D — `-translate-x-1/2 -translate-y-1/2` centers the child on the
+// percent point (CSS `transform: translate(-50%, -50%)`). Without this,
+// an icon at `left-[50%] top-[50%]` is anchored top-left at the centre
+// instead of visually centred.
+// ---------------------------------------------------------------------------
+{
+  const frame = makeAspectFrame(600);
+  markAspectRatio(frame as unknown as SceneNode, 5 / 3);
+
+  const node = makeChild('CenteredIcon');
+  node.width = 64;
+  node.height = 80;
+  frame.children.push(node);
+
+  markPositionInfo(node as unknown as SceneNode, {
+    leftPercent: 0.5,
+    topPercent: 0.5,
+    translateXFraction: -0.5,
+    translateYFraction: -0.5,
+  });
+
+  reflowDeferredAbsolutePositioningTree(frame as unknown as SceneNode);
+
+  // Parent: 600 × 360. Percent point: (300, 180). After -translate(-50%, -50%):
+  // x = 300 - 64/2 = 268; y = 180 - 80/2 = 140.
+  assert.equal(node.x, 268, 'translate-x-1/2 centers child on percent X');
+  assert.equal(node.y, 140, 'translate-y-1/2 centers child on percent Y');
+}
+
+// ---------------------------------------------------------------------------
+// Scenario E — position-info marks must NOT be deleted after a single
+// application. The reflow re-runs after dimensions change (aspect-ratio
+// retry), and the percent positioning must re-resolve against the new
+// dimensions instead of staying frozen at intermediate values.
+// ---------------------------------------------------------------------------
+{
+  const frame = makeAspectFrame(600);
+  markAspectRatio(frame as unknown as SceneNode, 5 / 3);
+
+  const node = makeChild('PercentNode');
+  frame.children.push(node);
+  markPositionInfo(node as unknown as SceneNode, {
+    leftPercent: 0.5,
+    topPercent: 0.5,
+  });
+
+  // First reflow — resolves against full dimensions.
+  reflowDeferredAbsolutePositioningTree(frame as unknown as SceneNode);
+  const firstX = node.x;
+  const firstY = node.y;
+  assert.ok(firstX > 0 && firstY > 0, 'first reflow resolves percent positions');
+
+  // Simulate parent dimensions changing (e.g. a later layout pass adjusts
+  // the parent). Re-run reflow — position must update to match the new
+  // dimensions, proving the mark wasn't deleted after first application.
+  frame.resize(800, 0);
+  markAspectRatio(frame as unknown as SceneNode, 5 / 3);
+  reflowDeferredAbsolutePositioningTree(frame as unknown as SceneNode);
+  assert.equal(frame.height, 480, 'second reflow re-resolves aspect ratio');
+  assert.equal(node.x, 400, 'position re-resolved against new width');
+  assert.equal(node.y, 240, 'position re-resolved against new height');
+}
+
+console.log('aspect-percent-position-regression: PASS');

package/scanner/aspect-ratio-regression.ts

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict';
+
+// Stub `figma` global before importing plugin internals — these modules
+// reference `figma.*` at import time even though our resolver only uses
+// instance methods on real nodes at runtime. The stubs are sufficient for
+// the parser/marker side of the test.
+(globalThis as unknown as { figma: unknown }).figma = {
+  notify: () => undefined,
+  showUI: () => undefined,
+};
+
+import { applyAspectRatioIfPossible, hasAspectRatio, markAspectRatio } from '../src/layout/deferred-layout';
+
+// Minimal SceneNode-shaped stub: only the bits the resolver inspects.
+type StubNode = {
+  type: 'FRAME';
+  width: number;
+  height: number;
+  primaryAxisSizingMode: 'AUTO' | 'FIXED';
+  counterAxisSizingMode: 'AUTO' | 'FIXED';
+  resize(w: number, h: number): void;
+};
+
+function makeStub(width: number, height: number): StubNode {
+  const node: StubNode = {
+    type: 'FRAME',
+    width,
+    height,
+    primaryAxisSizingMode: 'AUTO',
+    counterAxisSizingMode: 'AUTO',
+    resize(w, h) {
+      this.width = w;
+      this.height = h;
+    },
+  };
+  return node;
+}
+
+function runRegression(): void {
+  // ---- aspect-5/3 with width 600 → height 360 -----------------------------
+  const node = makeStub(600, 0);
+  markAspectRatio(node as unknown as SceneNode, 5 / 3);
+  assert.equal(hasAspectRatio(node as unknown as SceneNode), true, 'mark should register');
+
+  applyAspectRatioIfPossible(node as unknown as SceneNode);
+  assert.equal(node.width, 600, 'width preserved');
+  assert.equal(node.height, 360, 'height = 600 / (5/3) = 360 (5:3)');
+  assert.equal(node.primaryAxisSizingMode, 'FIXED', 'primary axis locked');
+  assert.equal(node.counterAxisSizingMode, 'FIXED', 'counter axis locked');
+  assert.equal(hasAspectRatio(node as unknown as SceneNode), false, 'mark cleared after apply');
+
+  // ---- aspect-square with width 240 → height 240 --------------------------
+  const square = makeStub(240, 0);
+  markAspectRatio(square as unknown as SceneNode, 1);
+  applyAspectRatioIfPossible(square as unknown as SceneNode);
+  assert.equal(square.height, 240, 'square ratio = width');
+
+  // ---- aspect-6/1 with width 1200 → height 200 ----------------------------
+  const wide = makeStub(1200, 0);
+  markAspectRatio(wide as unknown as SceneNode, 6);
+  applyAspectRatioIfPossible(wide as unknown as SceneNode);
+  assert.equal(wide.height, 200, 'aspect-6/1 ratio = 6 → 1200/6=200');
+
+  // ---- invalid ratios are ignored (no throw, no mark) ---------------------
+  const noop = makeStub(500, 100);
+  markAspectRatio(noop as unknown as SceneNode, 0);
+  markAspectRatio(noop as unknown as SceneNode, -2);
+  markAspectRatio(noop as unknown as SceneNode, Number.NaN);
+  assert.equal(hasAspectRatio(noop as unknown as SceneNode), false, 'invalid ratios rejected');
+  applyAspectRatioIfPossible(noop as unknown as SceneNode);
+  assert.equal(noop.height, 100, 'no resize when no ratio marked');
+
+  // ---- zero/missing width: skip (don't crash, don't divide by zero) -------
+  const collapsed = makeStub(0, 50);
+  markAspectRatio(collapsed as unknown as SceneNode, 5 / 3);
+  applyAspectRatioIfPossible(collapsed as unknown as SceneNode);
+  assert.equal(collapsed.width, 0, 'collapsed width untouched');
+  assert.equal(collapsed.height, 50, 'collapsed height untouched');
+  // Mark should NOT be cleared so the resolver can be retried after width settles.
+  assert.equal(hasAspectRatio(collapsed as unknown as SceneNode), true, 'mark retained for retry');
+}
+
+try {
+  runRegression();
+  console.log('aspect-ratio-regression: PASS');
+} catch (err) {
+  console.error('aspect-ratio-regression: FAIL');
+  console.error(err);
+  process.exit(1);
+}

package/scanner/blob-placement-regression.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
-import { resolveBlobDimensions, resolveBlobPlacement } from '../src/blob-placement';
-import { getClassesForBreakpoint } from '../src/responsive-analyzer';
+import { resolveBlobDimensions, resolveBlobPlacement } from '../src/effects/blob-placement';
+import { getClassesForBreakpoint } from '../src/tailwind/responsive-analyzer';
 
 type CaseDef = {
   name: string;