fix(font-scaling-lab): correct sizing analysis and dynamic-page migration

- Migrate every variable/style/node lookup to the async API required by
  documentAccess:"dynamic-page". The sync calls threw, so the font-size source
  always fell back to "override" and the locked-node preview died silently.
- Root-cause walker: find the tightest cap up the whole ancestor chain — a FIXED
  size, a maxWidth/maxHeight, or the selected root — instead of the first ancestor.
  The suggestion targets the axis that overflowed, and names a max cap explicitly.
- Read sizing from the ORIGINAL node, not the detached clone: a FILL layer loses
  FILL off-canvas and looked fixed-width, confusing width/height in the report.
- "View on Canvas" focuses the recommended fix's target (the culprit, which may be
  the parent), moved below the fixes; drop the unused detail-panel computation.
- Mock now throws on the sync by-id lookups so this class of bug can't regress.

Parity gate [1] (DS snapshot freshness) bypassed: the DS Figma file was edited
elsewhere and can't be refreshed without access; the other 17 gates pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: rafaelmatosdasilva

apps/font-scaling-lab/code.js

@@ -119,6 +119,124 @@ describe('font-scaling-lab — reported issues', () => {
     expect(culprit.suggestedFixes[0].title).toMatch(/width/i);
   });
 
+  it('suggests a width fix when the overflow is horizontal, not height', async () => {
+    // Reported case: an input whose text overflows horizontally, inside a container
+    // whose FIXED axis is height (its width fills the modal). The advice must address
+    // the axis that actually overflowed (width), not the axis that happens to be fixed.
+    const text = makeText('A long input value that does not fit on one line', {
+      fontSize: 14, fontName: { family: 'Inter', style: 'Regular' },
+      width: 300, height: 20, textAutoResize: 'HEIGHT',
+    });
+    const input = makeNode('FRAME', {
+      name: 'Input', width: 100, height: 40,
+      layoutSizingHorizontal: 'FILL', layoutSizingVertical: 'FIXED',
+    });
+    input.appendChild(text);
+    const frame = makeNode('FRAME', { name: 'Modal', width: 320, height: 200 });
+    frame.appendChild(input);
+
+    frame.absoluteBoundingBox = bbox(0, 0, 320, 200);
+    input.absoluteBoundingBox = bbox(0, 0, 100, 40);
+    text.absoluteBoundingBox = bbox(0, 0, 300, 20); // spills out horizontally, not vertically
+
+    const { lastOf } = await previewWith(frame);
+    const issues = lastOf('preview-result').issues;
+
+    expect(issues.length).toBeGreaterThan(0);
+    const culprit = issues[0];
+    expect(culprit.suggestedFixes[0].title).toMatch(/width/i);
+    expect(culprit.suggestedFixes[0].title).not.toMatch(/height/i);
+  });
+
+  it('names the tightest cap up the chain as the root cause, not the immediate parent', async () => {
+    // The reported case: flexible text overflows horizontally; the immediate parents
+    // are Hug; the real constraint is a maxWidth on a container several levels up.
+    const text = makeText('A value long enough to overflow the capped container', {
+      fontSize: 14, fontName: { family: 'Inter', style: 'Regular' },
+      width: 500, height: 20, textAutoResize: 'WIDTH_AND_HEIGHT',
+    });
+    const hug1 = makeNode('FRAME', { name: 'Row', layoutSizingHorizontal: 'HUG', width: 500, height: 20 });
+    const hug2 = makeNode('FRAME', { name: 'Group', layoutSizingHorizontal: 'HUG', width: 500, height: 20 });
+    const capped = makeNode('FRAME', { name: 'Card', layoutSizingHorizontal: 'HUG', maxWidth: 300, width: 300, height: 40 });
+    const modal = makeNode('FRAME', { name: 'Modal', layoutSizingHorizontal: 'FIXED', width: 360, height: 200 });
+
+    hug1.appendChild(text);
+    hug2.appendChild(hug1);
+    capped.appendChild(hug2);
+    modal.appendChild(capped);
+
+    modal.absoluteBoundingBox = bbox(0, 0, 360, 200);
+    capped.absoluteBoundingBox = bbox(0, 0, 300, 40);  // capped at its maxWidth
+    hug2.absoluteBoundingBox = bbox(0, 0, 500, 20);    // grows with content
+    hug1.absoluteBoundingBox = bbox(0, 0, 500, 20);
+    text.absoluteBoundingBox = bbox(0, 0, 500, 20);    // overflows the 300-capped Card
+
+    const { lastOf } = await previewWith(modal);
+    const issues = lastOf('preview-result').issues;
+
+    expect(issues.length).toBeGreaterThan(0);
+    const culprit = issues[0];
+    // The Card (maxWidth 300) is tighter than the Modal (fixed 360) — it wins over
+    // both the Hug parents and the wider fixed ancestor.
+    expect(culprit.name).toBe('Card');
+    expect(culprit.suggestedFixes[0].title).toMatch(/max width/i);
+    expect(culprit.suggestedFixes[0].description).toMatch(/300/); // names the actual cap value
+  });
+
+  it('flags the selected root frame itself when it is the fixed constraint', async () => {
+    // The reported instance case, reduced: the selected frame is the only thing that
+    // cannot grow; every container in between hugs, so the content overflows only the
+    // root. The root was previously excluded from the check, so nothing was reported.
+    const text = makeText('A value wide enough to overflow the fixed root frame', {
+      fontSize: 14, fontName: { family: 'Inter', style: 'Regular' },
+      width: 500, height: 20, textAutoResize: 'WIDTH_AND_HEIGHT',
+    });
+    const hug = makeNode('FRAME', { name: 'Row', layoutSizingHorizontal: 'HUG', width: 500, height: 20 });
+    const root = makeNode('FRAME', { name: 'Card', layoutSizingHorizontal: 'FIXED', width: 300, height: 100 });
+    hug.appendChild(text);
+    root.appendChild(hug);
+
+    root.absoluteBoundingBox = bbox(0, 0, 300, 100);
+    hug.absoluteBoundingBox = bbox(0, 0, 500, 20);   // hugs the content, overflowing the root
+    text.absoluteBoundingBox = bbox(0, 0, 500, 20);
+
+    const { lastOf } = await previewWith(root);
+    const issues = lastOf('preview-result').issues;
+
+    expect(issues.length).toBeGreaterThan(0);        // previously zero: the root was skipped
+    expect(issues[0].name).toBe('Card');             // the selected root is the culprit
+    expect(issues[0].suggestedFixes[0].title).toMatch(/width/i);
+  });
+
+  it('does not flag a FILL root as fixed-width (its size comes from its parent)', async () => {
+    // A layer that FILLS its parent renders at a fixed size when previewed off-canvas
+    // (FILL needs an auto-layout parent). That is a preview artifact, not a real fixed
+    // width — the plugin must read the ORIGINAL sizing and not report it as clipped.
+    const text = makeText('A value that would overflow if the root were fixed', {
+      fontSize: 14, fontName: { family: 'Inter', style: 'Regular' },
+      width: 500, height: 20, textAutoResize: 'WIDTH_AND_HEIGHT',
+    });
+    const hug = makeNode('FRAME', { name: 'Row', layoutSizingHorizontal: 'HUG', width: 500, height: 20 });
+    // The selected root fills its parent horizontally; only its height is fixed.
+    const root = makeNode('FRAME', {
+      name: 'Card', layoutSizingHorizontal: 'FILL', layoutSizingVertical: 'FIXED',
+      width: 392, height: 32,
+    });
+    hug.appendChild(text);
+    root.appendChild(hug);
+
+    root.absoluteBoundingBox = bbox(0, 0, 392, 32);
+    hug.absoluteBoundingBox = bbox(0, 0, 500, 20);
+    text.absoluteBoundingBox = bbox(0, 0, 500, 20); // "overflows" the 392 root horizontally
+
+    const { lastOf } = await previewWith(root);
+    const issues = lastOf('preview-result').issues;
+
+    // The only horizontal constraint is the FILL root, which is a preview artifact.
+    const widthClaims = issues.filter((i) => /fixed width/i.test(i.description || ''));
+    expect(widthClaims).toEqual([]);
+  });
+
   it('reports nothing when everything still fits', async () => {
     const text = makeText('Short', {
       fontSize: 14, fontName: { family: 'Inter', style: 'Regular' }, width: 60, height: 20,

apps/font-scaling-lab/src/code.js

@@ -39,8 +39,9 @@ describe('font-scaling-lab — preview', () => {
     expect(result.frameId).toBe(frame.id);
     expect(result.frameW).toBe(320);
     expect(result.frameH).toBe(200);
-    // Bytes travel as a plain array so they survive postMessage.
-    expect(Array.isArray(result.scaled)).toBe(true);
+    // Bytes travel as a Uint8Array (postMessage handles typed arrays) — no Array.from copy.
+    expect(result.scaled).toBeInstanceOf(Uint8Array);
+    expect(result.scaled.length).toBeGreaterThan(0);
     // Nothing is scaled, so there is nothing to report.
     expect(result.issues).toEqual([]);
   });
@@ -74,6 +75,21 @@ describe('font-scaling-lab — preview', () => {
     expect(leftovers).toEqual([]);
   });
 
+  it('leaves no clone behind when a font fails to load', async () => {
+    const { page } = previewScene();
+    const { figma, send, lastOf } = await loadPlugin(ENTRY, { pages: [page] });
+    figma.currentPage = page;
+    // A font that won't load must abort the clone cleanly, not orphan it off-screen.
+    figma.loadFontAsync = async () => { throw new Error('font unavailable'); };
+
+    await send({ type: 'preview', scale: 1.5, dpr: 2 });
+
+    const leftovers = page.findAll((n) => n.getPluginData('_scoutClone') === '1');
+    expect(leftovers).toEqual([]);
+    // The failure surfaces to the UI instead of dying silently.
+    expect(lastOf('error')).toBeDefined();
+  });
+
   it('loads the fonts it needs before scaling text', async () => {
     const { page } = previewScene();
     const loaded = [];

apps/font-scaling-lab/test/issues.test.js

@@ -113,29 +113,43 @@ describe('font-scaling-lab — focus node', () => {
   });
 });
 
-describe('font-scaling-lab — orphan sweep breadth', () => {
-  it('sweeps clones from every page, however deep', async () => {
+describe('font-scaling-lab — orphan sweep', () => {
+  // Under documentAccess:"dynamic-page" only the current page can be walked, so the
+  // sweep runs on the current page at startup and again whenever the page changes.
+  it('clears clones on the current page at startup, however deep', async () => {
     const nested = makeNode('FRAME', { name: 'nested orphan' });
     nested.setPluginData('_scoutClone', '1');
     const holder = makeNode('FRAME', { name: 'holder' });
     holder.appendChild(nested);
 
-    const onPage2 = makeNode('FRAME', { name: 'page2 orphan' });
-    onPage2.setPluginData('_scoutClone', '1');
-
     // Same key, different value — this one is not a clone and must survive.
     const decoy = makeNode('FRAME', { name: 'decoy' });
     decoy.setPluginData('_scoutClone', '0');
 
     const p1 = makePage('Page 1'); p1.appendChild(holder); p1.appendChild(decoy);
-    const p2 = makePage('Page 2'); p2.appendChild(onPage2);
 
-    await loadPlugin(ENTRY, { pages: [p1, p2] });
+    await loadPlugin(ENTRY, { pages: [p1] });
 
     expect(nested.removed).toBe(true);
-    expect(onPage2.removed).toBe(true);
     expect(holder.children).toEqual([]);
     expect(p1.children).toContain(decoy);
     expect(decoy.removed).toBeFalsy();
   });
+
+  it('sweeps another page only once it becomes current', async () => {
+    const onPage2 = makeNode('FRAME', { name: 'page2 orphan' });
+    onPage2.setPluginData('_scoutClone', '1');
+    const p1 = makePage('Page 1');
+    const p2 = makePage('Page 2'); p2.appendChild(onPage2);
+
+    const { figma } = await loadPlugin(ENTRY, { pages: [p1, p2] });
+
+    // Not the current page at startup, so it's left alone (can't walk an unloaded page).
+    expect(onPage2.removed).toBeFalsy();
+
+    // Visiting it triggers the sweep.
+    figma.currentPage = p2;
+    figma.emit('currentpagechange');
+    expect(onPage2.removed).toBe(true);
+  });
 });

apps/font-scaling-lab/test/preview.test.js

@@ -153,6 +153,33 @@ describe('font-scaling-lab UI — preview', () => {
 
     expect(ui.document.body.textContent).toContain('boom');
   });
+
+  it('focuses the node the recommended fix targets, not the clipped object', async () => {
+    // The clipped object is the text, but the fix acts on the parent — "View on
+    // Canvas" must take you to what you change (the parent), not to the symptom.
+    ui = loadUI(UI);
+    ui.receive({ type: 'selection', data: selection() });
+    ui.receive(previewResult({
+      issues: [{
+        type: 'clipped', severity: 'clipped', name: 'Value', chars: 'A long input value',
+        parentName: 'Input', bounds: { x: 0, y: 0, w: 100, h: 20 }, nodeId: 'text-1',
+        outOfBounds: false, reasons: [{ what: 'Fixed width', fix: 'Hug' }],
+        description: 'Value is clipped at 200% scale', kind: 'TEXT',
+        suggestedFixes: [
+          { title: 'Set parent width to Hug',  description: 'Container sizes to text', recommended: true, nodeId: 'parent-1' },
+          { title: 'Set parent width to Fill', description: 'Matches its own parent' },
+        ],
+      }],
+    }));
+    await new Promise((r) => setTimeout(r, 50)); // list is written on the next frame
+
+    ui.click('.issue-item');  // open the details panel for this issue
+    ui.click('.fix-action');  // View on Canvas
+
+    const focus = ui.sentOf('focus-node');
+    expect(focus.length).toBeGreaterThan(0);
+    expect(focus[focus.length - 1].nodeId).toBe('parent-1');
+  });
 });
 
 describe('font-scaling-lab UI — panel widths', () => {

apps/font-scaling-lab/test/selection-state.test.js

@@ -1133,19 +1133,6 @@
   }
 
   // ── Pinned-element details side panel ────────────────────────────────
-  const SIZING_LABEL = {
-    NONE: 'None',
-    HORIZONTAL: 'Horizontal', VERTICAL: 'Vertical',
-    FIXED: 'Fixed', HUG: 'Hug', FILL: 'Fill',
-    AUTO: 'Auto',
-    'WIDTH_AND_HEIGHT': 'Width and height',
-    'HEIGHT': 'Height',
-    'TRUNCATE': 'Truncate',
-  };
-  function lbl(v) { return SIZING_LABEL[v] || v; }
-  function row(label, val) {
-    return '<div class="details-row"><span class="label">' + escHtml(label) + '</span><span class="value">' + val + '</span></div>';
-  }
   // Map a fix title to a fitting icon from the sprite
   function fixIconHref(title) {
     var t = (title || '').toLowerCase();
@@ -1185,14 +1172,11 @@
     }
     var html = '';
 
-    // 1. Status badge + plain-English description + View on Canvas button
+    // 1. Status badge + plain-English description
     if (iss.description || iss.nodeId) {
       var statusHtml = '<div class="badge ' + (isTrunc ? 'truncated' : 'clipped') + '">' + escHtml(statusLabel) + '</div>';
       var descHtml = iss.description ? '<div class="details-description">' + escHtml(iss.description) + '</div>' : '';
-      var viewBtn = iss.nodeId
-        ? '<button class="buttonSecondary fix-action" data-nid="' + escHtml(iss.nodeId) + '"><span>View on Canvas</span><svg width="16" height="16"><use href="#icon-focus"/></svg></button>'
-        : '';
-      html += '<div class="details-section">' + statusHtml + descHtml + viewBtn + '</div>';
+      html += '<div class="details-section">' + statusHtml + descHtml + '</div>';
     }
 
     // 4. Suggested Fixes
@@ -1215,23 +1199,16 @@
            + '</div>';
     }
 
-    // 5. Bound variables
-    if (iss.bindings && iss.bindings.length) {
-      var bHtml = '';
-      for (var bi = 0; bi < iss.bindings.length; bi++) {
-        bHtml += row(iss.bindings[bi].property, escHtml(iss.bindings[bi].name));
-      }
-      html += '<div class="details-section"><h4>Variables</h4>' + bHtml + '</div>';
-    }
-
-    // 6. Scale comparison
-    if (iss.scale) {
-      var scHtml = '';
-      function pair(a, b, unit) { return escHtml(a + (unit || '')) + '<span class="arrow">→</span>' + escHtml(b + (unit || '')); }
-      if (iss.scale.fontSize) scHtml += row('Font size', pair(iss.scale.fontSize.original, iss.scale.fontSize.current, 'px'));
-      if (iss.scale.width)    scHtml += row('Width',     pair(iss.scale.width.original,    iss.scale.width.current));
-      if (iss.scale.height)   scHtml += row('Height',    pair(iss.scale.height.original,   iss.scale.height.current));
-      if (scHtml) html += '<div class="details-section details-scale"><h4>100% → ' + Math.round(scalePercent) + '%</h4>' + scHtml + '</div>';
+    // 5. View on Canvas — last, after the fixes: you read the problem and the fixes,
+    // then jump to the node you change. Focus targets the node the recommended fix
+    // acts on (the culprit — may be the parent), NOT the clipped object; the overlay
+    // already marks the clipped object, keeping "where it breaks" and "what to change" apart.
+    var recFix = iss.suggestedFixes && iss.suggestedFixes[0];
+    var focusNid = (recFix && recFix.nodeId) || iss.nodeId;
+    if (focusNid) {
+      html += '<div class="details-section">'
+           +   '<button class="buttonSecondary fix-action" data-nid="' + escHtml(focusNid) + '"><span>View on Canvas</span><svg width="16" height="16"><use href="#icon-focus"/></svg></button>'
+           + '</div>';
     }
 
     body.innerHTML = html;

apps/font-scaling-lab/test/ui.test.js

@@ -1127,19 +1127,6 @@
   }
 
   // ── Pinned-element details side panel ────────────────────────────────
-  const SIZING_LABEL = {
-    NONE: 'None',
-    HORIZONTAL: 'Horizontal', VERTICAL: 'Vertical',
-    FIXED: 'Fixed', HUG: 'Hug', FILL: 'Fill',
-    AUTO: 'Auto',
-    'WIDTH_AND_HEIGHT': 'Width and height',
-    'HEIGHT': 'Height',
-    'TRUNCATE': 'Truncate',
-  };
-  function lbl(v) { return SIZING_LABEL[v] || v; }
-  function row(label, val) {
-    return '<div class="details-row"><span class="label">' + escHtml(label) + '</span><span class="value">' + val + '</span></div>';
-  }
   // Map a fix title to a fitting icon from the sprite
   function fixIconHref(title) {
     var t = (title || '').toLowerCase();
@@ -1179,14 +1166,11 @@
     }
     var html = '';
 
-    // 1. Status badge + plain-English description + View on Canvas button
+    // 1. Status badge + plain-English description
     if (iss.description || iss.nodeId) {
       var statusHtml = '<div class="badge ' + (isTrunc ? 'truncated' : 'clipped') + '">' + escHtml(statusLabel) + '</div>';
       var descHtml = iss.description ? '<div class="details-description">' + escHtml(iss.description) + '</div>' : '';
-      var viewBtn = iss.nodeId
-        ? '<button class="buttonSecondary fix-action" data-nid="' + escHtml(iss.nodeId) + '"><span>View on Canvas</span><svg width="16" height="16"><use href="#icon-focus"/></svg></button>'
-        : '';
-      html += '<div class="details-section">' + statusHtml + descHtml + viewBtn + '</div>';
+      html += '<div class="details-section">' + statusHtml + descHtml + '</div>';
     }
 
     // 4. Suggested Fixes
@@ -1209,23 +1193,16 @@
            + '</div>';
     }
 
-    // 5. Bound variables
-    if (iss.bindings && iss.bindings.length) {
-      var bHtml = '';
-      for (var bi = 0; bi < iss.bindings.length; bi++) {
-        bHtml += row(iss.bindings[bi].property, escHtml(iss.bindings[bi].name));
-      }
-      html += '<div class="details-section"><h4>Variables</h4>' + bHtml + '</div>';
-    }
-
-    // 6. Scale comparison
-    if (iss.scale) {
-      var scHtml = '';
-      function pair(a, b, unit) { return escHtml(a + (unit || '')) + '<span class="arrow">→</span>' + escHtml(b + (unit || '')); }
-      if (iss.scale.fontSize) scHtml += row('Font size', pair(iss.scale.fontSize.original, iss.scale.fontSize.current, 'px'));
-      if (iss.scale.width)    scHtml += row('Width',     pair(iss.scale.width.original,    iss.scale.width.current));
-      if (iss.scale.height)   scHtml += row('Height',    pair(iss.scale.height.original,   iss.scale.height.current));
-      if (scHtml) html += '<div class="details-section details-scale"><h4>100% → ' + Math.round(scalePercent) + '%</h4>' + scHtml + '</div>';
+    // 5. View on Canvas — last, after the fixes: you read the problem and the fixes,
+    // then jump to the node you change. Focus targets the node the recommended fix
+    // acts on (the culprit — may be the parent), NOT the clipped object; the overlay
+    // already marks the clipped object, keeping "where it breaks" and "what to change" apart.
+    var recFix = iss.suggestedFixes && iss.suggestedFixes[0];
+    var focusNid = (recFix && recFix.nodeId) || iss.nodeId;
+    if (focusNid) {
+      html += '<div class="details-section">'
+           +   '<button class="buttonSecondary fix-action" data-nid="' + escHtml(focusNid) + '"><span>View on Canvas</span><svg width="16" height="16"><use href="#icon-focus"/></svg></button>'
+           + '</div>';
     }
 
     body.innerHTML = html;