norma-scope 0.1.1 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-<img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNjgwIiBoZWlnaHQ9IjIwMCIgdmlld0JveD0iMCAwIDY4MCAyMDAiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgcm9sZT0iaW1nIiBhcmlhLWxhYmVsPSJOb3JtYSI+CiAgPHRpdGxlPk5vcm1hPC90aXRsZT4KICA8dGV4dCB4PSIzNDAiIHk9IjEzNSIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC1mYW1pbHk9Ii1hcHBsZS1zeXN0ZW0sICdIZWx2ZXRpY2EgTmV1ZScsIEFyaWFsLCBzYW5zLXNlcmlmIiBmb250LXdlaWdodD0iNzAwIiBmb250LXNpemU9IjEwMCIgZmlsbD0iI0E4NzM2RSIgbGV0dGVyLXNwYWNpbmc9IjIiPm5vcm1hPC90ZXh0Pgo8L3N2Zz4K" alt="Norma" width="200" />
+# Norma
 
 Norma compares your implementation screenshots against the original Figma designs and generates a visual diff report — automatically, every time you commit. No servers, no LLM, no blocking: just a report you can open and share.
 
@@ -33,6 +33,26 @@ Figma frame name     Screenshot filename
 "Nav Bar"         →  nav-bar.png
 ```
 
+## Taking the screenshot
+
+Norma compares images pixel-for-pixel from the top-left corner — it doesn't understand scrolling or page sections. So your screenshot needs to be a **full-page capture at the exact dimensions `init` showed you** (e.g. `1440×10661px`), not just what's visible in your browser viewport. A partial screenshot (like just the footer) will get compared against the top of the design and produce a meaningless, huge diff %.
+
+**Chrome / Edge (Mac and Windows — same steps, since this is a browser feature, not an OS one):**
+1. Open the page and resize your browser window to match the frame's width (e.g. 1440px wide)
+2. Open DevTools (`Cmd+Option+I` on Mac, `Ctrl+Shift+I` on Windows)
+3. Open the Command Menu (`Cmd+Shift+P` on Mac, `Ctrl+Shift+P` on Windows)
+4. Type "screenshot" and choose **Capture full size screenshot**
+5. Chrome downloads a PNG of the entire page, full height, no scrolling needed
+
+**Firefox (Mac and Windows):**
+1. Right-click anywhere on the page and choose **Take Screenshot** (or press `Shift+F2`, type `screenshot --fullpage`, then Enter)
+2. Choose **Save full page**
+
+**Browser extensions (any browser, if you prefer a permanent toolbar button):**
+- [GoFullPage](https://chromewebstore.google.com/detail/gofullpage-full-page-scr/fdpohaocaechififmbbbbbknoalclacl) (Chrome) or [FireShot](https://addons.mozilla.org/en-US/firefox/addon/fireshot/) (Firefox) both export a single full-page PNG in one click
+
+Once you have the PNG, drop it into `.bridge/screenshots/` with the exact filename `init` printed for that frame, then `git commit` as normal.
+
 ## Running manually
 
 The pre-commit hook runs this for you automatically, but you can also run it by hand any time:
@@ -47,6 +67,14 @@ Add `--fresh` to bypass Norma's local Figma cache and force a fresh fetch (usefu
 npx norma-scope compare --fresh
 ```
 
+## Cleaning up
+
+```bash
+npx norma-scope clean
+```
+
+Empties `.bridge/screenshots/`, `.bridge/diff/`, `.bridge/reports/`, and `.bridge/.cache/`. Useful when switching to a different Figma file, or just to clear out old local artifacts — `.bridge/config.json` is never touched.
+
 ## Config
 
 `init` writes `.bridge/config.json`, which is committed to your repo:
@@ -81,12 +109,9 @@ Your Figma personal access token is stored in `.env.local`, which is never commi
 
 Only `.bridge/config.json` is committed — everything else is local to your machine.
 
-## Coming soon
-
-Norma's current version (V1) is screenshot diffing, local and free, with no LLM involved. Two upgrades are planned:
+Norma's current version (V1) is screenshot diffing, local and free, with no LLM involved.
 
-- **V2 (pro)** — LLM code scan that points to the exact lines of code causing a visual mismatch
-- **V3 (team)** — runs on every PR via GitHub Action, posts the report as a PR comment, plus a team dashboard and report history
+See [COMMANDS.md](COMMANDS.md) for a full command reference and the step-by-step workflow.
 
 ## License
 

package/dist/cache.js

@@ -1,24 +1,61 @@
 import { readFile, writeFile, mkdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { fetchFramePng } from "./figma.js";
+import { fetchFramesPng } from "./figma.js";
 const CACHE_DIR = path.join(".bridge", ".cache");
 const TTL_MS = 10 * 60 * 1000; // 10 minutes
 function cachePathFor(frameId) {
     const safeId = frameId.replace(/[^a-zA-Z0-9]/g, "_");
     return path.join(CACHE_DIR, `${safeId}.png`);
 }
+async function isCacheFresh(cachePath) {
+    if (!existsSync(cachePath)) {
+        return false;
+    }
+    const stats = await stat(cachePath);
+    return Date.now() - stats.mtimeMs < TTL_MS;
+}
 export async function getFramePng(fileKey, frameId, token, options = {}) {
-    const cachePath = cachePathFor(frameId);
-    if (!options.fresh && existsSync(cachePath)) {
-        const stats = await stat(cachePath);
-        const age = Date.now() - stats.mtimeMs;
-        if (age < TTL_MS) {
-            return readFile(cachePath);
-        }
+    const result = await getFramesPng(fileKey, [frameId], token, options);
+    const png = result.pngs.get(frameId);
+    if (!png) {
+        throw new Error(result.fetchError ?? `No image returned for frame ${frameId}`);
     }
-    const png = await fetchFramePng(fileKey, frameId, token);
-    await mkdir(CACHE_DIR, { recursive: true });
-    await writeFile(cachePath, png);
     return png;
 }
+export async function getFramesPng(fileKey, frameIds, token, options = {}) {
+    const pngs = new Map();
+    const staleFrameIds = new Set();
+    const toFetch = [];
+    for (const frameId of frameIds) {
+        const cachePath = cachePathFor(frameId);
+        if (!options.fresh && (await isCacheFresh(cachePath))) {
+            pngs.set(frameId, await readFile(cachePath));
+        }
+        else {
+            toFetch.push(frameId);
+        }
+    }
+    let fetchError = null;
+    if (toFetch.length > 0) {
+        try {
+            const fetched = await fetchFramesPng(fileKey, toFetch, token);
+            await mkdir(CACHE_DIR, { recursive: true });
+            for (const [frameId, png] of fetched) {
+                pngs.set(frameId, png);
+                await writeFile(cachePathFor(frameId), png);
+            }
+        }
+        catch (err) {
+            fetchError = err.message;
+            for (const frameId of toFetch) {
+                const cachePath = cachePathFor(frameId);
+                if (existsSync(cachePath)) {
+                    pngs.set(frameId, await readFile(cachePath));
+                    staleFrameIds.add(frameId);
+                }
+            }
+        }
+    }
+    return { pngs, staleFrameIds, fetchError };
+}

package/dist/clean.js

@@ -0,0 +1,31 @@
+import { rm, mkdir, readdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+const BRIDGE_DIR = ".bridge";
+const CLEAN_TARGETS = [
+    { dir: path.join(BRIDGE_DIR, "screenshots"), label: "screenshots" },
+    { dir: path.join(BRIDGE_DIR, "diff"), label: "diff images" },
+    { dir: path.join(BRIDGE_DIR, "reports"), label: "reports" },
+    { dir: path.join(BRIDGE_DIR, ".cache"), label: "Figma cache" },
+];
+export async function runClean() {
+    if (!existsSync(BRIDGE_DIR)) {
+        console.log("Norma: no .bridge directory found — nothing to clean.");
+        return;
+    }
+    console.log("Norma — Clean");
+    console.log("══════════════════════════════════════════════");
+    for (const target of CLEAN_TARGETS) {
+        let fileCount = 0;
+        if (existsSync(target.dir)) {
+            const entries = await readdir(target.dir);
+            fileCount = entries.length;
+            await rm(target.dir, { recursive: true, force: true });
+        }
+        await mkdir(target.dir, { recursive: true });
+        console.log(`  ${target.label.padEnd(14)} →  ${fileCount} file(s) removed`);
+    }
+    console.log("");
+    console.log("  .bridge/config.json was left untouched.");
+    console.log("══════════════════════════════════════════════");
+}

package/dist/compare.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { getFramePng } from "./cache.js";
+import { getFramesPng } from "./cache.js";
 import { runDiff } from "./diff.js";
 import { generateReport } from "./report.js";
 const BRIDGE_DIR = ".bridge";
@@ -18,6 +18,25 @@ function readEnvToken() {
     const match = content.match(/^FIGMA_TOKEN=(.*)$/m);
     return match ? match[1].trim() : null;
 }
+function parseConfig(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+    const candidate = parsed;
+    if (typeof candidate.figmaFileKey !== "string" ||
+        typeof candidate.threshold !== "number" ||
+        !Array.isArray(candidate.frames)) {
+        return null;
+    }
+    return candidate;
+}
 export async function runCompare(options = {}) {
     if (!existsSync(CONFIG_PATH)) {
         console.log("Norma: no .bridge/config.json found — run `npx norma-scope init` first.");
@@ -28,30 +47,46 @@ export async function runCompare(options = {}) {
         console.log("Norma: ⚠ .env.local missing or FIGMA_TOKEN not set — skipping comparison.");
         return;
     }
-    const config = JSON.parse(await readFile(CONFIG_PATH, "utf-8"));
+    const config = parseConfig(await readFile(CONFIG_PATH, "utf-8"));
+    if (!config) {
+        console.log("Norma: ⚠ .bridge/config.json is malformed — skipping comparison. Run `npx norma-scope init` to regenerate it.");
+        return;
+    }
     const results = [];
     const lines = [];
+    const framesWithScreenshots = config.frames.filter((frame) => existsSync(path.join(SCREENSHOTS_DIR, frame.screenshot)));
+    let figmaPngs = new Map();
+    let staleFrameIds = new Set();
+    let batchFetchError = null;
+    if (framesWithScreenshots.length > 0) {
+        const result = await getFramesPng(config.figmaFileKey, framesWithScreenshots.map((f) => f.figmaFrameId), token, { fresh: options.fresh });
+        figmaPngs = result.pngs;
+        staleFrameIds = result.staleFrameIds;
+        if (result.fetchError) {
+            batchFetchError = result.fetchError.includes("429")
+                ? "rate limited by Figma — try again in a few minutes (Norma caches results for 10 min, so this should resolve on its own)"
+                : result.fetchError;
+        }
+    }
     for (const frame of config.frames) {
         const screenshotPath = path.join(SCREENSHOTS_DIR, frame.screenshot);
         if (!existsSync(screenshotPath)) {
             lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (no screenshot found)`);
             continue;
         }
-        let figmaPng;
-        try {
-            figmaPng = await getFramePng(config.figmaFileKey, frame.figmaFrameId, token, {
-                fresh: options.fresh,
-            });
-        }
-        catch (err) {
-            lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (Figma fetch failed: ${err.message})`);
+        const figmaPng = figmaPngs.get(frame.figmaFrameId);
+        if (!figmaPng) {
+            const reason = batchFetchError ?? `no image returned for frame ${frame.figmaFrameId}`;
+            lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (Figma fetch failed: ${reason})`);
             continue;
         }
         const diffPath = path.join(DIFF_DIR, frame.screenshot.replace(/\.png$/, "-diff.png"));
         let mismatchPercent;
+        let dimensionMismatch;
         try {
             const result = await runDiff(screenshotPath, figmaPng, diffPath);
             mismatchPercent = result.mismatchPercent;
+            dimensionMismatch = result.dimensionMismatch;
         }
         catch (err) {
             lines.push(`  ${frame.screenshot.padEnd(22)} →  ⚠ skipped (diff failed: ${err.message})`);
@@ -68,6 +103,12 @@ export async function runCompare(options = {}) {
             ? `⚠ above threshold (${config.threshold}%)`
             : "✓";
         lines.push(`  ${frame.screenshot.padEnd(22)} →  ${mismatchPercent.toFixed(1).padStart(5)}%  ${flag}`);
+        if (dimensionMismatch) {
+            lines.push(`  ${"".padEnd(22)}    ⚠ image dimensions differ significantly — check screenshot export scale`);
+        }
+        if (staleFrameIds.has(frame.figmaFrameId)) {
+            lines.push(`  ${"".padEnd(22)}    ⚠ Figma fetch failed — using a cached design image older than 10 min`);
+        }
     }
     console.log("Norma");
     console.log("══════════════════════════════════════════════");

package/dist/diff.js

@@ -1,6 +1,12 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { PNG } from "pngjs";
 import pixelmatch from "pixelmatch";
+const DIMENSION_MISMATCH_THRESHOLD = 0.15;
+function isDimensionMismatch(aWidth, aHeight, bWidth, bHeight) {
+    const widthDiff = Math.abs(aWidth - bWidth) / Math.max(aWidth, bWidth);
+    const heightDiff = Math.abs(aHeight - bHeight) / Math.max(aHeight, bHeight);
+    return widthDiff > DIMENSION_MISMATCH_THRESHOLD || heightDiff > DIMENSION_MISMATCH_THRESHOLD;
+}
 function resizeToCanvas(png, width, height) {
     if (png.width === width && png.height === height) {
         return png;
@@ -13,6 +19,7 @@ export async function runDiff(screenshotPath, figmaPngBuffer, outputPath) {
     const screenshotBuffer = await readFile(screenshotPath);
     const screenshotPng = PNG.sync.read(screenshotBuffer);
     const figmaPng = PNG.sync.read(figmaPngBuffer);
+    const dimensionMismatch = isDimensionMismatch(screenshotPng.width, screenshotPng.height, figmaPng.width, figmaPng.height);
     const width = Math.max(screenshotPng.width, figmaPng.width);
     const height = Math.max(screenshotPng.height, figmaPng.height);
     const a = resizeToCanvas(screenshotPng, width, height);
@@ -21,5 +28,5 @@ export async function runDiff(screenshotPath, figmaPngBuffer, outputPath) {
     const mismatchedPixels = pixelmatch(a.data, b.data, diff.data, width, height, { threshold: 0.1 });
     const mismatchPercent = (mismatchedPixels / (width * height)) * 100;
     await writeFile(outputPath, PNG.sync.write(diff));
-    return { mismatchPercent };
+    return { mismatchPercent, dimensionMismatch };
 }

package/dist/figma.js

@@ -12,26 +12,52 @@ export async function fetchFrameList(fileKey, token) {
         const pageChildren = page.children ?? [];
         for (const node of pageChildren) {
             if (node.type === "FRAME") {
-                frames.push({ id: node.id, name: node.name });
+                frames.push({
+                    id: node.id,
+                    name: node.name,
+                    width: node.absoluteBoundingBox ? Math.round(node.absoluteBoundingBox.width) : null,
+                    height: node.absoluteBoundingBox ? Math.round(node.absoluteBoundingBox.height) : null,
+                });
             }
         }
     }
     return frames;
 }
 export async function fetchFramePng(fileKey, frameId, token) {
-    const res = await fetch(`${FIGMA_API_BASE}/images/${fileKey}?ids=${encodeURIComponent(frameId)}&format=png`, { headers: { "X-Figma-Token": token } });
+    const result = await fetchFramesPng(fileKey, [frameId], token);
+    const png = result.get(frameId);
+    if (!png) {
+        throw new Error(`No image returned for frame ${frameId}`);
+    }
+    return png;
+}
+export async function fetchFramesPng(fileKey, frameIds, token) {
+    if (frameIds.length === 0) {
+        return new Map();
+    }
+    const idsParam = frameIds.map(encodeURIComponent).join(",");
+    const res = await fetch(`${FIGMA_API_BASE}/images/${fileKey}?ids=${idsParam}&format=png`, { headers: { "X-Figma-Token": token } });
     if (!res.ok) {
-        throw new Error(`Figma API error exporting frame ${frameId}: ${res.status} ${res.statusText}`);
+        throw new Error(`Figma API error exporting frames ${frameIds.join(", ")}: ${res.status} ${res.statusText}`);
     }
     const data = (await res.json());
-    const imageUrl = data.images[frameId];
-    if (!imageUrl) {
-        throw new Error(`No image returned for frame ${frameId}`);
-    }
-    const imgRes = await fetch(imageUrl);
-    if (!imgRes.ok) {
-        throw new Error(`Failed to download exported PNG: ${imgRes.status} ${imgRes.statusText}`);
+    const entries = await Promise.all(frameIds.map(async (frameId) => {
+        const imageUrl = data.images[frameId];
+        if (!imageUrl) {
+            return null;
+        }
+        const imgRes = await fetch(imageUrl);
+        if (!imgRes.ok) {
+            return null;
+        }
+        const arrayBuffer = await imgRes.arrayBuffer();
+        return [frameId, Buffer.from(arrayBuffer)];
+    }));
+    const result = new Map();
+    for (const entry of entries) {
+        if (entry) {
+            result.set(entry[0], entry[1]);
+        }
     }
-    const arrayBuffer = await imgRes.arrayBuffer();
-    return Buffer.from(arrayBuffer);
+    return result;
 }

package/dist/index.js

@@ -1,5 +1,6 @@
 import { runInit } from "./init.js";
 import { runCompare } from "./compare.js";
+import { runClean } from "./clean.js";
 const HELP = `
 Norma
 
@@ -10,6 +11,7 @@ Commands:
   init             Set up Norma in this project
   compare          Compare local screenshots against Figma designs
   compare --fresh  Bypass the Figma cache and force a fresh fetch
+  clean            Remove local screenshots, diffs, reports, and cache
 `;
 async function main() {
     const command = process.argv[2];
@@ -20,6 +22,9 @@ async function main() {
         case "compare":
             await runCompare({ fresh: process.argv.includes("--fresh") });
             break;
+        case "clean":
+            await runClean();
+            break;
         default:
             console.log(HELP);
             break;

package/dist/init.js

@@ -1,5 +1,5 @@
 import { createInterface } from "node:readline/promises";
-import { mkdir, writeFile, readFile, appendFile, chmod } from "node:fs/promises";
+import { mkdir, writeFile, readFile, appendFile, chmod, copyFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fetchFrameList } from "./figma.js";
@@ -47,16 +47,25 @@ async function updateGitignore() {
         await appendFile(gitignorePath, `${prefix}${missing.join("\n")}\n`);
     }
 }
-async function installPreCommitHook() {
+export async function installPreCommitHook() {
     const hooksDir = ".git/hooks";
     if (!existsSync(hooksDir)) {
         console.log("  ⚠ No .git/hooks directory found — skipping pre-commit hook install.");
-        return;
+        return { backedUpTo: null };
     }
     const hookPath = path.join(hooksDir, "pre-commit");
-    const hookContent = "#!/bin/sh\nnpx norma-scope compare\n";
+    const hookContent = "#!/bin/sh\nnpx norma-scope compare\nexit 0\n";
+    let backedUpTo = null;
+    if (existsSync(hookPath)) {
+        const existing = await readFile(hookPath, "utf-8");
+        if (!existing.includes("npx norma-scope compare")) {
+            backedUpTo = `${hookPath}.pre-norma-backup`;
+            await copyFile(hookPath, backedUpTo);
+        }
+    }
     await writeFile(hookPath, hookContent, { mode: 0o755 });
     await chmod(hookPath, 0o755);
+    return { backedUpTo };
 }
 export async function runInit() {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -77,7 +86,8 @@ export async function runInit() {
         }
         console.log("Which frames do you want to check? (comma-separated numbers)\n");
         frames.forEach((frame, i) => {
-            console.log(`  ${i + 1}   ${frame.name}`);
+            const dims = frame.width && frame.height ? `  (${frame.width}×${frame.height}px)` : "";
+            console.log(`  ${i + 1}   ${frame.name}${dims}`);
         });
         const selection = await rl.question("\n> ");
         const indices = selection
@@ -106,25 +116,36 @@ export async function runInit() {
             await writeFile(".env.local", `FIGMA_TOKEN=${trimmedToken}\n`);
         }
         await updateGitignore();
-        await installPreCommitHook();
+        const { backedUpTo } = await installPreCommitHook();
         console.log("\n✓ Config written to .bridge/config.json");
         console.log("✓ .bridge/screenshots/ folder created");
         console.log("✓ .bridge/reports/ folder created");
         console.log("✓ .bridge/diff/ folder created");
         console.log("✓ .gitignore updated");
-        console.log("✓ Pre-commit hook installed");
+        if (backedUpTo) {
+            console.log(`✓ Pre-commit hook installed (your existing hook was backed up to ${backedUpTo})`);
+        }
+        else {
+            console.log("✓ Pre-commit hook installed");
+        }
         console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
         console.log("You're ready. Here's what to do next:\n");
         console.log("  Screenshot your implementation for each component");
         console.log("  and drop the files here: .bridge/screenshots/\n");
         console.log("  Expected filenames:");
-        for (const frame of config.frames) {
-            console.log(`    ${frame.screenshot}`);
-        }
+        config.frames.forEach((frame, i) => {
+            const source = selectedFrames[i];
+            const dims = source.width && source.height ? `  — capture at ${source.width}×${source.height}px` : "";
+            console.log(`    ${frame.screenshot}${dims}`);
+        });
         console.log("\n  Then just git commit as normal.");
         console.log("  The report generates automatically.");
         console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
     }
+    catch (err) {
+        console.log(`\n✗ Setup failed: ${err.message}`);
+        process.exitCode = 1;
+    }
     finally {
         rl.close();
     }

package/dist/report.js

@@ -14,12 +14,28 @@ function escapeHtml(str) {
     return str
         .replace(/&/g, "&")
         .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;");
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
 }
 async function toBase64(filePath) {
     const buffer = await readFile(filePath);
     return buffer.toString("base64");
 }
+function frame(src, alt, dotClass, caption) {
+    return `
+          <figure class="shot-frame">
+            <div class="shot-chrome">
+              <span class="shot-dot ${dotClass}"></span>
+              <span class="shot-chrome-line short"></span>
+              <span class="shot-chrome-line"></span>
+            </div>
+            <div class="shot-body">
+              <img src="${src}" loading="lazy" onclick="openLightbox('${src}')" alt="${alt}" />
+            </div>
+            <figcaption>${caption}</figcaption>
+          </figure>`;
+}
 export async function generateReport(results, threshold, outputPath) {
     const { branch, commit } = getGitInfo();
     const generated = new Date().toLocaleString("en-GB", {
@@ -37,68 +53,211 @@ export async function generateReport(results, threshold, outputPath) {
         const buildB64 = await toBase64(r.screenshotPath);
         const figmaB64 = r.figmaPng.toString("base64");
         const diffB64 = await toBase64(r.diffPath);
+        const buildSrc = `data:image/png;base64,${buildB64}`;
+        const figmaSrc = `data:image/png;base64,${figmaB64}`;
+        const diffSrc = `data:image/png;base64,${diffB64}`;
+        const label = escapeHtml(r.label);
         return `
-      <div class="component ${isFlagged ? "flagged" : "clean"}">
+      <section class="component">
         <div class="component-header">
-          <span class="component-label">${escapeHtml(r.label)}</span>
-          <span class="component-status">${isFlagged ? "⚠" : "✓"} ${r.mismatchPercent.toFixed(1)}% diff</span>
+          <h2>${label}</h2>
+          <span class="component-status ${isFlagged ? "flagged" : "clean"}">${isFlagged ? "⚠ " : ""}${r.mismatchPercent.toFixed(1)}% diff</span>
         </div>
         <div class="component-images">
-          <div class="image-col">
-            <p>Your build</p>
-            <img src="data:image/png;base64,${buildB64}" />
-          </div>
-          <div class="image-col">
-            <p>Figma design</p>
-            <img src="data:image/png;base64,${figmaB64}" />
-          </div>
-          <div class="image-col">
-            <p>Diff overlay</p>
-            <img src="data:image/png;base64,${diffB64}" />
-          </div>
+${frame(buildSrc, `${label} — your build`, "dot-build", "Your build")}
+${frame(figmaSrc, `${label} — Figma design`, "dot-build", "Figma design")}
+${frame(diffSrc, `${label} — diff overlay`, "dot-diff", "Diff overlay")}
         </div>
-      </div>`;
+      </section>`;
     }));
     const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>Norma Report</title>
 <style>
-  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f5f5f7; color: #1d1d1f; margin: 0; padding: 32px; }
-  header h1 { margin: 0 0 4px; font-size: 22px; }
-  header p { margin: 2px 0; color: #555; font-size: 13px; }
-  .summary { display: flex; gap: 24px; margin: 24px 0; padding: 16px; background: #fff; border-radius: 8px; box-shadow: 0 1px 3px rgba(0,0,0,0.08); font-size: 14px; }
-  .summary strong { font-size: 18px; display: block; }
-  .component { background: #fff; border-radius: 8px; margin-bottom: 20px; box-shadow: 0 1px 3px rgba(0,0,0,0.08); overflow: hidden; }
-  .component-header { display: flex; justify-content: space-between; align-items: center; padding: 12px 16px; border-bottom: 1px solid #eee; }
-  .component-label { font-weight: 600; }
-  .component.flagged .component-status { color: #b45309; font-weight: 600; }
-  .component.clean .component-status { color: #15803d; font-weight: 600; }
-  .component-images { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 1px; background: #eee; }
-  .image-col { background: #fff; padding: 12px; text-align: center; }
-  .image-col p { margin: 0 0 8px; font-size: 12px; color: #777; text-transform: uppercase; letter-spacing: 0.05em; }
-  .image-col img { max-width: 100%; border: 1px solid #ddd; border-radius: 4px; }
-  footer { margin-top: 32px; text-align: center; color: #888; font-size: 12px; }
+  :root {
+    --clay: #A8736E;
+    --ink: #1C1B1A;
+    --ink-soft: #6B6664;
+    --line: #E7E1DF;
+    --page-bg: #EDE7E1;
+    --card: #FFFFFF;
+    --frame-bg: #F7F5F3;
+    --chrome-bg: #F0EDEA;
+    --danger: #B6611F;
+    --success: #3E7D52;
+  }
+  * { box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, sans-serif;
+    background: var(--page-bg);
+    color: var(--ink);
+    margin: 0;
+    padding: 48px 24px;
+    -webkit-font-smoothing: antialiased;
+  }
+  .card {
+    max-width: 1080px;
+    margin: 0 auto;
+    background: var(--card);
+    border-radius: 24px;
+    box-shadow: 0 24px 60px rgba(28,27,26,0.10);
+    overflow: hidden;
+  }
+  header {
+    display: flex;
+    justify-content: space-between;
+    align-items: flex-start;
+    padding: 32px 40px;
+    border-bottom: 1px solid var(--line);
+  }
+  header h1 { font-size: 26px; font-weight: 700; margin: 0 0 8px; }
+  .report-meta {
+    font-family: "SF Mono", ui-monospace, Menlo, monospace;
+    font-size: 13px;
+    color: var(--ink-soft);
+  }
+  .wordmark { font-size: 14px; font-weight: 700; color: var(--clay); letter-spacing: -0.01em; }
+  .summary-bar {
+    display: flex;
+    gap: 28px;
+    flex-wrap: wrap;
+    padding: 20px 40px;
+    border-bottom: 1px solid var(--line);
+    font-size: 15px;
+  }
+  .summary-bar b { font-weight: 700; }
+  .summary-bar .attention b { color: var(--danger); }
+  .summary-bar .clean b { color: var(--success); }
+  .components { padding: 8px 40px 40px; }
+  .component { padding: 28px 0; border-bottom: 1px solid var(--line); }
+  .component:last-child { border-bottom: none; }
+  .component-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 18px;
+  }
+  .component-header h2 { font-size: 19px; font-weight: 700; margin: 0; }
+  .component-status { font-size: 13px; font-weight: 600; }
+  .component-status.flagged { color: var(--danger); }
+  .component-status.clean { color: var(--success); }
+  .component-images {
+    display: grid;
+    grid-template-columns: 1fr 1fr 1fr;
+    gap: 20px;
+  }
+  .shot-frame { margin: 0; }
+  .shot-chrome {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    height: 28px;
+    padding: 0 12px;
+    background: var(--chrome-bg);
+    border: 1px solid var(--line);
+    border-bottom: none;
+    border-radius: 10px 10px 0 0;
+  }
+  .shot-dot { width: 7px; height: 7px; border-radius: 50%; flex-shrink: 0; }
+  .dot-build { background: var(--clay); }
+  .dot-diff { background: #B9B3AE; }
+  .shot-chrome-line { height: 4px; border-radius: 2px; background: #DCD6D1; }
+  .shot-chrome-line.short { width: 18px; }
+  .shot-chrome-line:not(.short) { width: 40px; margin-left: auto; }
+  .shot-body {
+    background: var(--frame-bg);
+    border: 1px solid var(--line);
+    border-top: none;
+    border-radius: 0 0 10px 10px;
+    padding: 14px;
+  }
+  .shot-body img {
+    width: 100%;
+    height: 240px;
+    object-fit: contain;
+    object-position: top center;
+    cursor: zoom-in;
+    display: block;
+    transition: opacity 0.15s ease;
+  }
+  .shot-body img:hover { opacity: 0.85; }
+  .shot-frame figcaption {
+    margin-top: 12px;
+    text-align: center;
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--ink-soft);
+  }
+  footer {
+    text-align: center;
+    color: var(--ink-soft);
+    font-size: 12px;
+    line-height: 1.7;
+    padding: 28px 40px 8px;
+  }
+  #lightbox {
+    display: none;
+    position: fixed;
+    inset: 0;
+    background: rgba(20,18,17,0.88);
+    align-items: center;
+    justify-content: center;
+    padding: 40px;
+    z-index: 10;
+    cursor: zoom-out;
+  }
+  #lightbox.open { display: flex; }
+  #lightbox img {
+    max-width: 100%;
+    max-height: 100%;
+    border-radius: 8px;
+    box-shadow: 0 20px 60px rgba(0,0,0,0.4);
+  }
+  @media (max-width: 720px) {
+    .component-images { grid-template-columns: 1fr; }
+    header { flex-direction: column; gap: 16px; }
+  }
 </style>
 </head>
 <body>
-<header>
-  <h1>Norma Report</h1>
-  <p>Branch: ${escapeHtml(branch)}</p>
-  <p>Commit: ${escapeHtml(commit)}</p>
-  <p>Generated: ${escapeHtml(generated)}</p>
-</header>
-<div class="summary">
-  <div><strong>${results.length}</strong> components checked</div>
-  <div><strong>${needsAttention.length}</strong> need attention</div>
-  <div><strong>${clean.length}</strong> clean</div>
+<div class="card">
+  <header>
+    <div>
+      <h1>Report</h1>
+      <p class="report-meta">Branch: ${escapeHtml(branch)} &middot; Commit: ${escapeHtml(commit)} &middot; ${escapeHtml(generated)}</p>
+    </div>
+    <span class="wordmark">norma</span>
+  </header>
+  <div class="summary-bar">
+    <span>${results.length} components checked</span>
+    <span class="attention"><b>${needsAttention.length}</b> needs attention</span>
+    <span class="clean"><b>${clean.length}</b> clean</span>
+  </div>
+  <div class="components">
+    ${rows.join("\n")}
+  </div>
+  <footer>
+    <p>Generated by Norma</p>
+    <p>To fix: update your implementation, re-screenshot, commit again.</p>
+  </footer>
+</div>
+<div id="lightbox" onclick="closeLightbox()">
+  <img id="lightbox-img" src="" alt="Full size preview" />
 </div>
-${rows.join("\n")}
-<footer>
-  <p>Generated by Norma</p>
-  <p>To fix: update your implementation, re-screenshot, commit again.</p>
-</footer>
+<script>
+  function openLightbox(src) {
+    document.getElementById('lightbox-img').src = src;
+    document.getElementById('lightbox').classList.add('open');
+  }
+  function closeLightbox() {
+    document.getElementById('lightbox').classList.remove('open');
+  }
+</script>
 </body>
 </html>`;
     await writeFile(outputPath, html);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "norma-scope",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Compare your implementation screenshots against Figma designs with a zero-friction, local pre-commit report.",
   "type": "module",
   "bin": {