@tendrilapp/cli 0.1.38 → 0.1.39

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 an explicit maxDimension of at least ${Math.max(box.w, box.h)} (the tool defaults to 1024 and scales to fit)`;
+}
+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);
@@ -3514,7 +3545,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 +3558,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 +3604,27 @@ 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, ABSENT_RADIUS, ABSENT_MIN_PX, DIFF_LEGEND;
 var init_image_diff = __esm({
   "packages/verify/src/image-diff.ts"() {
     "use strict";
     INK_DELTA = 30;
     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]
+    };
   }
 });
 
@@ -6950,7 +7018,7 @@ body{margin:0;background:rgb(${backdrop.join(",")})}
           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 +14371,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 an explicit maxDimension of AT LEAST the node's longer edge from the get_metadata you just recorded \u2014 the tool DEFAULTS TO 1024 and SCALES the node to fit, so a component wider or taller than that silently becomes a downscaled reference, which is not pixel ground truth (ingest now refuses a reference smaller than its own recorded box). 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}"`;
   }

package/package.json

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