@tendrilapp/cli 0.1.38 → 0.1.40

package/dist/SKILL.md

@@ -198,7 +198,10 @@ Batch runs (several components in one session):
    real faces is the only path to certification.
 3. Record each planned rep with FOUR tool calls: make the THREE
    Figma MCP calls in protocol order — get_metadata, then
-   get_design_context (excludeScreenshot=true), then get_screenshot —
+   get_design_context (excludeScreenshot=true), then get_screenshot
+   (ALWAYS with contentsOnly: true and maxDimension: 4096 — without
+   isolation the export bakes in the editor's component-set chrome,
+   which scores as ink no implementation can paint) —
    and then ONE `tendril_record_ingest_rep` carrying all three:
    metadata and context response text passed VERBATIM — responses
    often arrive as MULTIPLE output blocks (block counts vary BY

package/dist/tendril-mcp.js

@@ -112,7 +112,7 @@ var TOOLS = [
   },
   {
     name: "tendril_record_ingest_rep",
-    description: "Ingest a rep's ENTIRE recording in ONE call \u2014 the get_metadata response, the get_design_context response, and the get_screenshot image_url together. Make the three Figma calls first, in protocol order (get_metadata, then get_design_context with excludeScreenshot=true, then get_screenshot), then pass all three here VERBATIM. PREFER THIS over three separate ingest/fetch calls: one approvable operation per rep instead of three. Pieces land independently: on a partial failure the error names exactly which piece(s) to re-record \u2014 the rest are already on disk. The response carries `next` and, for design context, `assets` (auto-fetched server-side; only listed failures need record_asset).",
+    description: "Ingest a rep's ENTIRE recording in ONE call \u2014 the get_metadata response, the get_design_context response, and the get_screenshot image_url together. Make the three Figma calls first, in protocol order (get_metadata, then get_design_context with excludeScreenshot=true, then get_screenshot with contentsOnly=true and maxDimension=4096 \u2014 isolation keeps the editor's component-set chrome out of the padded export, where it would otherwise score as unpaintable reference ink), then pass all three here VERBATIM. PREFER THIS over three separate ingest/fetch calls: one approvable operation per rep instead of three. Pieces land independently: on a partial failure the error names exactly which piece(s) to re-record \u2014 the rest are already on disk. The response carries `next` and, for design context, `assets` (auto-fetched server-side; only listed failures need record_asset).",
     schema: z.object({
       setDir: str("recording set directory"),
       rep: str("planned rep slug"),

package/dist/tendril.js

@@ -1203,6 +1203,33 @@ function containedPath(setDir, ...segments) {
   }
   return target;
 }
+function clampedReference(setDir, slug, payload) {
+  const metaFile = containedPath(setDir, slug, "get_metadata.json");
+  if (!existsSync(metaFile)) return void 0;
+  let box;
+  try {
+    const m = /width="([\d.]+)"\s+height="([\d.]+)"/.exec(envelopeTextContent(JSON.parse(readFileSync(metaFile, "utf8"))));
+    if (m !== null) box = { w: Math.round(Number(m[1])), h: Math.round(Number(m[2])) };
+  } catch {
+    return void 0;
+  }
+  if (box === void 0 || box.w === 0 || box.h === 0) return void 0;
+  const dims = referencePngDims(payload);
+  if (dims === void 0) return void 0;
+  if (dims.w >= box.w - 1 && dims.h >= box.h - 1) return void 0;
+  return `the reference image is ${dims.w}\xD7${dims.h} but the recorded box is ${box.w}\xD7${box.h} \u2014 it was SCALED DOWN, so it is not pixel ground truth. Re-run get_screenshot passing contentsOnly: true and maxDimension: 4096 (the tool defaults to 1024 and clamps anything longer; a flat generous cap is always at least the ${Math.max(box.w, box.h)} this box needs, and contentsOnly keeps the editor's component-set chrome out of the padding)`;
+}
+function referencePngDims(payload) {
+  const parts = payload?.content;
+  if (!Array.isArray(parts)) return void 0;
+  for (const p of parts) {
+    if (p?.type !== "image" || typeof p.data !== "string") continue;
+    const buf = Buffer.from(p.data, "base64");
+    if (buf.length < 24) return void 0;
+    return { w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) };
+  }
+  return void 0;
+}
 function ingestEnvelope(setDir, slug, tool, payload) {
   const manifest = loadManifest(setDir);
   if (!manifest.reps.some((r) => r.slug === slug)) throw new Error(`unknown rep "${slug}" \u2014 not in the planned manifest`);
@@ -1218,6 +1245,10 @@ function ingestEnvelope(setDir, slug, tool, payload) {
   if (!parsed.success) {
     throw new Error(`${slug}/${tool} was NOT recorded \u2014 envelope rejected at the boundary: ${parsed.error.issues[0]?.message ?? "invalid"}. ${REINGEST_GUIDANCE}`);
   }
+  const clamped = tool === "get_screenshot" ? clampedReference(setDir, slug, payload) : void 0;
+  if (clamped !== void 0) {
+    throw new Error(`${slug}/${tool} was NOT recorded \u2014 ${clamped}. ${REINGEST_GUIDANCE}`);
+  }
   const file = containedPath(setDir, slug, `${tool}.json`);
   mkdirSync(path.dirname(file), { recursive: true });
   const overwrote = existsSync(file);
@@ -3277,6 +3308,7 @@ function absentInkClusters(render, reference, background = [255, 255, 255]) {
         let x1 = sx;
         let y1 = sy;
         let px = 0;
+        let chromePx = 0;
         const stack = [si];
         seen[si] = 1;
         while (stack.length > 0) {
@@ -3284,6 +3316,8 @@ function absentInkClusters(render, reference, background = [255, 255, 255]) {
           const cx = i % width;
           const cy = (i - cx) / width;
           px += 1;
+          const ci = i * 4;
+          if (canvasB.data[ci] === FIGMA_CHROME[0] && canvasB.data[ci + 1] === FIGMA_CHROME[1] && canvasB.data[ci + 2] === FIGMA_CHROME[2]) chromePx += 1;
           if (cx < x0) x0 = cx;
           if (cy < y0) y0 = cy;
           if (cx > x1) x1 = cx;
@@ -3301,7 +3335,7 @@ function absentInkClusters(render, reference, background = [255, 255, 255]) {
             }
           }
         }
-        if (px >= ABSENT_MIN_PX) found.push({ x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1, px, memberX: sx, memberY: sy });
+        if (px >= ABSENT_MIN_PX) found.push({ x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1, px, memberX: sx, memberY: sy, ...chromePx * 2 >= px ? { chrome: true } : {} });
       }
     }
   }
@@ -3514,7 +3548,7 @@ function localizeDifference(render, reference, masks = []) {
   const boxArea = (x1 - x0 + 1) * (y1 - y0 + 1);
   return { x0, y0, x1, y1, density: count / boxArea };
 }
-function diffPng(render, reference, masks = []) {
+function diffPng(render, reference, masks = [], background = [255, 255, 255]) {
   const a = PNG.sync.read(Buffer.from(render));
   const b = PNG.sync.read(Buffer.from(reference));
   const width = Math.max(a.width, b.width);
@@ -3527,6 +3561,29 @@ function diffPng(render, reference, masks = []) {
   }
   const out = new PNG({ width, height });
   pixelmatch(canvasA.data, canvasB.data, out.data, width, height, { threshold: 0.15 });
+  const inkAt = (data, index) => isInk(data, index * 4, background);
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = width * y + x;
+      const o = i * 4;
+      if (!(out.data[o] === 255 && out.data[o + 1] === 0 && out.data[o + 2] === 0)) continue;
+      const refInk = inkAt(canvasB.data, i);
+      const renInk = inkAt(canvasA.data, i);
+      let covered = false;
+      for (let dy = -1; dy <= 1 && !covered; dy++) {
+        for (let dx = -1; dx <= 1 && !covered; dx++) {
+          const nx = x + dx;
+          const ny = y + dy;
+          if (nx < 0 || ny < 0 || nx >= width || ny >= height) continue;
+          if (inkAt(canvasA.data, width * ny + nx)) covered = true;
+        }
+      }
+      const colour = refInk && !renInk ? covered ? DIFF_LEGEND.shift : DIFF_LEGEND.absent : !refInk && renInk ? DIFF_LEGEND.extra : DIFF_LEGEND.recolor;
+      out.data[o] = colour[0];
+      out.data[o + 1] = colour[1];
+      out.data[o + 2] = colour[2];
+    }
+  }
   return new Uint8Array(PNG.sync.write(out));
 }
 function cropPng(png, x, y, width, height) {
@@ -3550,13 +3607,65 @@ function cropPng(png, x, y, width, height) {
   }
   return new Uint8Array(PNG.sync.write(out));
 }
-var INK_DELTA, ABSENT_RADIUS, ABSENT_MIN_PX;
+var INK_DELTA, FIGMA_CHROME, ABSENT_RADIUS, ABSENT_MIN_PX, DIFF_LEGEND, DIFF_LEGEND_TEXT;
 var init_image_diff = __esm({
   "packages/verify/src/image-diff.ts"() {
     "use strict";
     INK_DELTA = 30;
+    FIGMA_CHROME = [138, 56, 245];
     ABSENT_RADIUS = 3;
     ABSENT_MIN_PX = 6;
+    DIFF_LEGEND = {
+      /** Reference ink with no render ink within ±1px. THIS is the ink
+       * deficit — the only category that moves inkRecall. Red. */
+      absent: [255, 0, 0],
+      /** Ink in both, different colour. Moves similarity only. Amber. */
+      recolor: [255, 170, 0],
+      /** Render painted ink where the reference records none. Blue. */
+      extra: [0, 120, 255],
+      /** Reference ink covered within the metric's ±1px neighbourhood —
+       * ALREADY FORGIVEN by inkRecall. Dimmed grey, so it reads as tolerated
+       * rather than as a defect to chase (measured at only 3.0% of red, but
+       * chasing it is exactly what the nudge saga was). */
+      shift: [150, 150, 150],
+      /** pixelmatch's OWN anti-aliasing colour, passed through unrepainted.
+       * `includeAA` is false, so these pixels are painted but NOT counted as
+       * mismatches — they are in neither the similarity number nor the ink
+       * deficit. Listed here because the first field run measured 343-380 of
+       * them per config and the reader had a fourth colour with no key
+       * (CompTest run, 2026-08-19). Do not repaint it: passing pixelmatch's
+       * own marking through unchanged is what keeps "not counted" honest. */
+      antialias: [255, 255, 0]
+    };
+    DIFF_LEGEND_TEXT = [
+      "Tendril diff image legend \u2014 what each colour means.",
+      "",
+      "A verdict has TWO gates and this one image serves both, so the colour",
+      "says WHICH number a pixel belongs to. Marked pixels are exactly the",
+      "ones pixelmatch marks; only their colour carries the cause.",
+      "",
+      `  #ff0000  RED     reference ink the render never painted, and no render`,
+      `                   ink within 1px. THE INK DEFICIT \u2014 the only category`,
+      `                   that moves inkRecall.`,
+      `  #ffaa00  AMBER   ink in BOTH images, different colour. Moves`,
+      `                   similarity. CANNOT move inkRecall.`,
+      `  #0078ff  BLUE    render ink where the reference records none. Moves`,
+      `                   similarity. Cannot move inkRecall.`,
+      `  #969696  GREY    reference ink covered within 1px \u2014 a displacement`,
+      `                   inkRecall ALREADY FORGIVES. Not a defect to chase.`,
+      `  #ffff00  YELLOW  pixelmatch judged this anti-aliasing. Painted but`,
+      `                   NOT COUNTED: in neither the similarity number nor`,
+      `                   the ink deficit.`,
+      "",
+      "Raw marked-pixel count is a poor guide to cause: a field run measured a",
+      "config where BLUE dominated 1797 to 270 while only the 270 red pixels",
+      "demoted it.",
+      "",
+      "If red clusters sit OUTSIDE the recorded node box, suspect the",
+      "reference rather than the code \u2014 Figma pads exports to contain outer",
+      "effects, and the pad can capture the editor's own component-set chrome.",
+      ""
+    ].join("\n");
   }
 });
 
@@ -6841,7 +6950,10 @@ function repEffectExtents(set, rep) {
   }
 }
 async function scoreBundleForTask(task, bundleDir, bar = BAR, opts = {}) {
-  if (opts.evidenceDir !== void 0) mkdirSync3(opts.evidenceDir, { recursive: true });
+  if (opts.evidenceDir !== void 0) {
+    mkdirSync3(opts.evidenceDir, { recursive: true });
+    writeFileSync6(path20.join(opts.evidenceDir, "diff-legend.txt"), DIFF_LEGEND_TEXT);
+  }
   const CONFIGS2 = task.configs;
   const timeoutMs = opts.mountDeadlineMs ?? ENGINE_MOUNT_DEADLINE_MS;
   const entryTsx = path20.join(bundleDir, task.entry);
@@ -6944,13 +7056,14 @@ body{margin:0;background:rgb(${backdrop.join(",")})}
           const pass = r.similarity >= bar.sim && r.inkRecall >= bar.ink && !slab;
           const region = pass ? void 0 : localizeDifference(scored, ref);
           const absent = absentInkClusters(scored, ref, backdrop).map((c) => {
+            if (c.chrome === true) return c;
             const name = deepestNodeNameAt(task.set, cfg.rep, c.memberX - seat.x, c.memberY - seat.y);
             return name === void 0 ? c : { ...c, name };
           });
           if (opts.evidenceDir !== void 0) {
             writeFileSync6(path20.join(opts.evidenceDir, `${cfg.rep}-render.png`), scored);
             writeFileSync6(path20.join(opts.evidenceDir, `${cfg.rep}-ref.png`), ref);
-            writeFileSync6(path20.join(opts.evidenceDir, `${cfg.rep}-diff.png`), diffPng(scored, ref));
+            writeFileSync6(path20.join(opts.evidenceDir, `${cfg.rep}-diff.png`), diffPng(scored, ref, [], backdrop));
             for (const [i, c] of absent.slice(0, 3).entries()) {
               writeFileSync6(path20.join(opts.evidenceDir, `${cfg.rep}-absent-${i}-ref.png`), zoomCrop(ref, c));
               writeFileSync6(path20.join(opts.evidenceDir, `${cfg.rep}-absent-${i}-render.png`), zoomCrop(scored, c));
@@ -14303,7 +14416,7 @@ var init_record = __esm({
       const shown = items.length <= MAX_SPOKEN_VALUES ? items : [...items.slice(0, MAX_SPOKEN_VALUES), `${items.length - MAX_SPOKEN_VALUES} more`];
       return shown.length <= 1 ? shown[0] ?? "" : `${shown.slice(0, -1).join(", ")} and ${shown[shown.length - 1]}`;
     };
-    ENVELOPE_HELP = `Envelope format: text tools save {"content":[{"type":"text","text":"<VERBATIM response text incl. any Currently-selected-nodes block>"}]}; get_screenshot: do NOT download the image yourself \u2014 pass its image_url to \`${tendrilCommand("record fetch")}\` (MCP: tendril_record_fetch), which pulls the bytes to disk directly. That keeps the pixel ground truth out of your context and costs one approval instead of a shell command per asset. Assets are asset-<first-8-hex-of-figma-uuid>.<ext>; their URLs appear as const declarations inside the design-context text and also expire.`;
+    ENVELOPE_HELP = `Envelope format: text tools save {"content":[{"type":"text","text":"<VERBATIM response text incl. any Currently-selected-nodes block>"}]}; VERBATIM MEANS EVERY PART, NOT JUST THE TEXT ONE: if a response carries additional content blocks \u2014 an image block especially \u2014 keep them in the envelope you save. get_design_context is documented to return a screenshot alongside the code, and whether it actually does is a question our whole recorded corpus cannot answer because every saved envelope holds text only. Saving what arrives settles it at no extra call. get_screenshot: pass contentsOnly: true AND maxDimension: 4096 \u2014 always, on every call, whatever the node's size. contentsOnly renders the node in isolation; without it the export is what the CANVAS looks like, which for a node inside a component set includes the editor's own component-set chrome (#8a38f5 dashes) baked into the padding. That chrome is reference ink no implementation can paint, so it lands as absent-ink clusters and demotes an otherwise perfect component: measured 2026-08-19, a Modal scored 0/3 certified whose every absent cluster was chrome, and the same render against a contentsOnly reference scored 3/3 (ink 0.9949 -> 0.9996). Isolation does NOT drop the outer effects we deliberately capture \u2014 the padded dimensions come back byte-identical (1276x199 and 1836x175, drop shadow intact). maxDimension is a CAP, not a target: a 56x28 node requested at a high cap comes back 56x28, never upscaled (measured across 24 poses, 2026-08-19). The tool DEFAULTS TO 1024 and clamps anything longer, which silently yields a downscaled reference that is not pixel ground truth, and ingest refuses that. Do NOT compute the cap from the node box: Figma PADS the export to contain outer effects, so the reference is routinely larger than the box it came from \u2014 a recorded 1800px-wide modal exported at 1836px, and a cap sized to the box would have been refused. A flat generous cap removes the arithmetic and the whole failure class. Then do NOT download the image yourself \u2014 pass its image_url to \`${tendrilCommand("record fetch")}\` (MCP: tendril_record_fetch), which pulls the bytes to disk directly. That keeps the pixel ground truth out of your context and costs one approval instead of a shell command per asset. Assets are asset-<first-8-hex-of-figma-uuid>.<ext>; their URLs appear as const declarations inside the design-context text and also expire.`;
     isAutoFetchAssetUrl = (url) => isFigmaAssetUrl(url) || isLocalAssetUrl(url);
     describeRoleLoss = (loss) => loss.kind === "main" ? `drops main "${loss.main}"` : `stops "${loss.part}" being a part of main "${loss.main}"`;
   }
@@ -14806,7 +14919,17 @@ function foldConfigStatus(s, failDemotions, substitutedFamilies) {
   if (status === "certified" && s.absentInk !== void 0 && s.absentInk.length > 0) {
     status = "pass";
     absentInkDemoted = true;
-    certDemote.push(...s.absentInk.map((c) => `absent ink: ${c.name ?? "unnamed region"} \u2014 ${c.px}px of recorded ink with no render ink within reach (missing or invisible feature)`));
+    certDemote.push(
+      ...s.absentInk.map(
+        (c) => (
+          // A chrome cluster is a defect in the RECORDING, and saying
+          // "missing or invisible feature" points the reader at code that
+          // is not wrong — run 26's operator spent a round hunting a
+          // layout bug that did not exist.
+          c.chrome === true ? `absent ink: ${c.px}px of Figma's component-set CHROME baked into the reference \u2014 this is the editor's own outline, not your component, and no implementation can paint it. RE-RECORD this rep with get_screenshot contentsOnly: true (the outer effect survives isolation; only the chrome goes).` : `absent ink: ${c.name ?? "unnamed region"} \u2014 ${c.px}px of recorded ink with no render ink within reach (missing or invisible feature)`
+        )
+      )
+    );
   }
   if (status === "certified" && substitutedFamilies.length > 0) {
     status = "pass";
@@ -15544,7 +15667,7 @@ ${certified}/${statuses.length} certified \xB7 ${report.coverage.pass}/${statuse
   if (certBlockedByAbsentInk.length > 0) {
     warn(
       opts,
-      `${certBlockedByAbsentInk.length} config(s) demoted by absent-ink clusters (${certBlockedByAbsentInk.join(", ")}) \u2014 certification never ships a missing or invisible feature; each cluster is named in the report above. Fix the component and re-verify, or verify at --bar pass for the disclosed result.`
+      `${certBlockedByAbsentInk.length} config(s) demoted by absent-ink clusters (${certBlockedByAbsentInk.join(", ")}) \u2014 certification never ships a missing or invisible feature; each cluster is named in the report above. Fix the component and re-verify, or verify at --bar pass for the disclosed result. BEFORE changing code, check WHERE the clusters sit: open the -absent-*-ref.png crops in the evidence dir. If the missing ink lies at the extreme EDGES of the reference rather than inside the component, it is probably not yours \u2014 Figma pads an export to contain outer effects (a shadow, a glow), and the pad can capture the editor's own component-set chrome, which is purple #8a38f5 and which no correct implementation can ever paint. Measured 2026-08-19: a shadowed modal was demoted 0/3 with EVERY absent cluster made of chrome, while the same kit's unshadowed button, exported with no pad, certified 24/24 \u2014 and re-recording with contentsOnly: true took the same code to 3/3. That is a recording artifact, not a defect in your component.`
     );
     process.exitCode = ExitCode.VerificationFailed;
   }
@@ -16381,7 +16504,7 @@ var init_server = __esm({
       },
       {
         name: "tendril_record_ingest_rep",
-        description: "Ingest a rep's ENTIRE recording in ONE call \u2014 the get_metadata response, the get_design_context response, and the get_screenshot image_url together. Make the three Figma calls first, in protocol order (get_metadata, then get_design_context with excludeScreenshot=true, then get_screenshot), then pass all three here VERBATIM. PREFER THIS over three separate ingest/fetch calls: one approvable operation per rep instead of three. Pieces land independently: on a partial failure the error names exactly which piece(s) to re-record \u2014 the rest are already on disk. The response carries `next` and, for design context, `assets` (auto-fetched server-side; only listed failures need record_asset).",
+        description: "Ingest a rep's ENTIRE recording in ONE call \u2014 the get_metadata response, the get_design_context response, and the get_screenshot image_url together. Make the three Figma calls first, in protocol order (get_metadata, then get_design_context with excludeScreenshot=true, then get_screenshot with contentsOnly=true and maxDimension=4096 \u2014 isolation keeps the editor's component-set chrome out of the padded export, where it would otherwise score as unpaintable reference ink), then pass all three here VERBATIM. PREFER THIS over three separate ingest/fetch calls: one approvable operation per rep instead of three. Pieces land independently: on a partial failure the error names exactly which piece(s) to re-record \u2014 the rest are already on disk. The response carries `next` and, for design context, `assets` (auto-fetched server-side; only listed failures need record_asset).",
         schema: z14.object({
           setDir: str("recording set directory"),
           rep: str("planned rep slug"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tendrilapp/cli",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "description": "Figma design systems → verified React components. CLI ruler + MCP server.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",