@@ -209,13 +209,28 @@ Only users with **write** access can approve; others get a 👎 reaction.
 | `fail-on-new` | `false` | new snapshots need approval too |
 | `fail-on-missing` | `false` | baselines not captured this run fail the check |
 | `fail-on-change` | `false` | also fail the step (the commit status is the primary signal) |
-| `comment` / `max-comment-images` | `true` / `20` | PR comment behavior |
+| `comment` / `max-comment-images` | `true` / `30` | PR comment behavior; the budget counts inline images (changed = 3, new = 1), worst diffs first, the rest degrade to links |
+| `thumbnail-width` | `360` | inline images are thumbnails linking to the full files; `0` embeds full-size |
 | `status-context` | `nitpix/visual` | the check name |
 | `github-token` | `github.token` | needs contents/PR/statuses write |
 
 Outputs: `status`, `changed-count`, `added-count`, `missing-count`,
 `unapproved-count`.
 
+### Comment weight
+
+GitHub loads every inline image in a comment at once (even inside closed
+`<details>`, and `width=` doesn't shrink the download), and notification
+emails carry the comment body as created. nitpix keeps reports light three
+ways:
+
+- inline images are **thumbnails** (`thumbnail-width`, default 360px)
+  hyperlinked to the full-size files;
+- a total **image budget** (`max-comment-images`) is spent on the worst
+  diffs first; snapshots beyond it render as `baseline · new · diff` links;
+- the comment is **created links-only and immediately edited** to the full
+  version — GitHub only emails on creation, so emails never embed images.
+
 ## Notes & limitations
 
 - **Fork PRs & dependabot**: fully supported via the `workflow_run` topology
 
@@ -65,9 +65,18 @@ inputs:
     required: false
     default: 'true'
   max-comment-images:
-    description: 'Maximum number of snapshots rendered with inline images in the PR comment'
+    description: >-
+      Maximum number of inline images embedded in the PR comment (a changed
+      snapshot costs 3, a new one costs 1; worst diffs first). Snapshots
+      beyond the budget degrade to baseline/new/diff links.
+    required: false
+    default: '30'
+  thumbnail-width:
+    description: >-
+      Width of the thumbnails embedded in the PR comment (they link to the
+      full-size images). Set to '0' to embed full-size images instead.
     required: false
-    default: '20'
+    default: '360'
   status-context:
     description: 'Commit status context name (make this a required check)'
     required: false
@@ -117,12 +126,12 @@ runs:
         run-id: ${{ github.event.workflow_run.id || github.run_id }}
         github-token: ${{ inputs.github-token }}
 
-    - name: Install odiff
+    - name: Install odiff and sharp
       shell: bash
       run: |
-        if [ ! -x "$RUNNER_TEMP/nitpix-odiff/node_modules/.bin/odiff" ]; then
+        if [ ! -d "$RUNNER_TEMP/nitpix-odiff/node_modules/odiff-bin" ] || [ ! -d "$RUNNER_TEMP/nitpix-odiff/node_modules/sharp" ]; then
           npm install --prefix "$RUNNER_TEMP/nitpix-odiff" --no-save --no-audit --no-fund \
-            "odiff-bin@${{ inputs.odiff-version }}"
+            "odiff-bin@${{ inputs.odiff-version }}" "sharp@^0.35.0"
         fi
 
     - name: Diff and report
@@ -141,6 +150,7 @@ runs:
         INPUT_FAIL_ON_CHANGE: ${{ inputs.fail-on-change }}
         INPUT_COMMENT: ${{ inputs.comment }}
         INPUT_MAX_COMMENT_IMAGES: ${{ inputs.max-comment-images }}
+        INPUT_THUMBNAIL_WIDTH: ${{ inputs.thumbnail-width }}
         INPUT_STATUS_CONTEXT: ${{ inputs.status-context }}
         INPUT_COMMAND_PREFIX: ${{ inputs.command-prefix }}
         INPUT_GITHUB_TOKEN: ${{ inputs.github-token }}
 
@@ -91,8 +91,14 @@ class GitHub {
     return data.permission; // admin | write | read | none
   }
 
-  /** Create or update the single nitpix comment (identified by marker) on a PR. */
-  async upsertComment(prNumber, marker, body) {
+  /**
+   * Create or update the single nitpix comment (identified by marker) on a PR.
+   * When creating and `createBody` is given, the comment is first posted with
+   * that lighter body and immediately edited to the full one: GitHub only
+   * sends notification emails for comment creation, so the email carries the
+   * light (image-free) version while the PR page shows the full report.
+   */
+  async upsertComment(prNumber, marker, body, createBody) {
     let existing = null;
     for (let page = 1; page <= 10 && !existing; page++) {
       const batch = await this.get(`/repos/${this.repo}/issues/${prNumber}/comments?per_page=100&page=${page}`);
@@ -102,7 +108,13 @@ class GitHub {
     if (existing) {
       return this.request('PATCH', `/repos/${this.repo}/issues/comments/${existing.id}`, { body });
     }
-    return this.request('POST', `/repos/${this.repo}/issues/${prNumber}/comments`, { body });
+    const created = await this.request('POST', `/repos/${this.repo}/issues/${prNumber}/comments`, {
+      body: createBody || body,
+    });
+    if (createBody && createBody !== body) {
+      return this.request('PATCH', `/repos/${this.repo}/issues/comments/${created.id}`, { body });
+    }
+    return created;
   }
 
   createComment(prNumber, body) {
 
@@ -8,6 +8,7 @@ const { input, boolInput, setOutput, stepSummary, eventPayload, listPngs, copyFi
 const { GitHub } = require('./github');
 const { remoteUrl, checkoutBaseline, commitAndPush } = require('./git');
 const { compareDirs, countByStatus } = require('./diffing');
+const { makeThumbs } = require('./thumbs');
 const { buildReport, rawUrls, MARKER } = require('./report');
 
 async function main() {
@@ -201,6 +202,24 @@ async function diff({ gh, repo, remote, branch, baselineRepoDir, snapshotsDir, w
     results: results.map(({ name, status, hash, diffPercentage }) => ({ name, status, hash, diffPercentage })),
   };
 
+  // Small thumbnails for the comment (full-size PNGs are only a click away).
+  // GitHub loads every inline image in a comment at once — even inside closed
+  // <details> — so embedding full screenshots makes big reports very heavy.
+  const thumbsDir = path.join(workDir, 'thumbs');
+  const thumbJobs = [];
+  for (const r of visual) {
+    thumbJobs.push({ src: path.join(snapshotsDir, r.name), kind: 'snapshot', name: r.name });
+    if (r.status === 'changed') {
+      thumbJobs.push({ src: path.join(baselineDir, r.name), kind: 'baseline', name: r.name });
+      const diffImg = path.join(diffDir, r.name);
+      if (!r.layoutDiff && fs.existsSync(diffImg)) {
+        thumbJobs.push({ src: diffImg, kind: 'diff', name: r.name });
+      }
+    }
+  }
+  const thumbWidth = parseInt(input('thumbnail-width', '360'), 10);
+  const hasThumbs = await makeThumbs(thumbJobs, thumbsDir, thumbWidth);
+
   let pushedSha = null;
   try {
     pushedSha = commitAndPush(
@@ -217,6 +236,11 @@ async function diff({ gh, repo, remote, branch, baselineRepoDir, snapshotsDir, w
             copyFile(diffImg, path.join(dir, pendingDir, 'diff', r.name));
           }
         }
+        if (hasThumbs) {
+          for (const { kind, name } of thumbJobs) {
+            copyFile(path.join(thumbsDir, kind, name), path.join(dir, pendingDir, 'thumb', kind, name));
+          }
+        }
         fs.mkdirSync(path.join(dir, pendingDir), { recursive: true });
         fs.writeFileSync(path.join(dir, pendingDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
       },
@@ -233,25 +257,30 @@ async function diff({ gh, repo, remote, branch, baselineRepoDir, snapshotsDir, w
       ? `${process.env.GITHUB_SERVER_URL}/${repo}/actions/runs/${process.env.GITHUB_RUN_ID}`
       : null;
 
-  const urls = rawUrls({ repo, commitSha: pushedSha, baseRef, pendingDir });
-  const body = buildReport({
+  const urls = rawUrls({ repo, commitSha: pushedSha, baseRef, pendingDir, hasThumbs });
+  const reportArgs = {
     results,
     baseRef,
     headSha,
     urls,
     approvedNames,
     unapproved,
-    maxImages: parseInt(input('max-comment-images', '20'), 10),
+    maxImages: parseInt(input('max-comment-images', '30'), 10),
     commandPrefix,
     runUrl,
-  });
+  };
+  const body = buildReport(reportArgs);
+  // Links-only variant used as the creation body: GitHub emails the comment
+  // as created, so notifications stay light; the immediate edit to the full
+  // body is what people see on the PR page.
+  const emailBody = buildReport({ ...reportArgs, inlineImages: false });
 
   stepSummary(body.replace(MARKER, '').trim());
 
   let commentUrl = null;
   if (boolInput('comment', true)) {
     try {
-      const comment = await gh.upsertComment(prNumber, MARKER, body);
+      const comment = await gh.upsertComment(prNumber, MARKER, body, emailBody);
       commentUrl = comment && comment.html_url;
     } catch (err) {
       warn(`nitpix: could not post PR comment: ${err.message}`);
 
@@ -8,8 +8,20 @@ const MARKER = '<!-- nitpix-report -->';
 /**
  * Build the PR comment / step summary markdown.
  *
- * urls: { baseline(name), snapshot(name), diff(name) } returning a raw image
- * URL or null (e.g. fork PRs where we couldn't push pending images).
+ * urls: { baseline(name), snapshot(name), diff(name), thumb(kind, name) }
+ * returning a raw image URL, or null helpers when images couldn't be pushed
+ * (e.g. fork PRs without the workflow_run topology). thumb() returns null
+ * when thumbnails are disabled — full images are embedded instead.
+ *
+ * Comment-weight strategy (GitHub loads every <img> in a comment at once,
+ * even inside closed <details>, and `width=` doesn't reduce the download):
+ * - inline images are small thumbnails hyperlinked to the full-size files
+ * - snapshots are ordered by severity and only `maxImages` inline images are
+ *   embedded (changed rows cost 3, added rows cost 1); the rest degrade to
+ *   plain baseline/new/diff links
+ * - with `inlineImages: false` the whole report is links-only; main.js posts
+ *   that version first so notification emails never embed images, then
+ *   immediately edits in the full version (GitHub only emails on creation)
  */
 function buildReport({
   results,
@@ -21,13 +33,16 @@ function buildReport({
   maxImages,
   commandPrefix,
   runUrl,
+  inlineImages = true,
 }) {
   const counts = countByStatus(results);
-  const changed = results.filter((r) => r.status === 'changed');
+  const bySeverity = (a, b) =>
+    (b.layoutDiff ? 100 : b.diffPercentage || 0) - (a.layoutDiff ? 100 : a.diffPercentage || 0);
+  const changed = results.filter((r) => r.status === 'changed').sort(bySeverity);
   const added = results.filter((r) => r.status === 'added');
   const missing = results.filter((r) => r.status === 'missing');
 
-  const lines = ['<!-- nitpix-report -->', '## 👁 nitpix visual review', ''];
+  const lines = [MARKER, '## 👁 nitpix visual review', ''];
 
   const needsReview = unapproved.length > 0;
   const verdict = needsReview
@@ -43,7 +58,23 @@ function buildReport({
   );
 
   let imagesUsed = 0;
-  const imageBudgetExceeded = () => imagesUsed >= maxImages;
+  const canEmbed = (cost) => inlineImages && urls.baseline && imagesUsed + cost <= maxImages;
+
+  // thumbnail-if-available <img> wrapped in a link to the full image
+  const img = (kind, name) => {
+    const full = urls[kind](name);
+    const thumb = urls.thumb && urls.thumb(kind, name);
+    return `<a href="${full}"><img src="${thumb || full}" width="260"></a>`;
+  };
+  const linkRow = (r) => {
+    if (!urls.baseline) return '_images unavailable (no write access to the baseline branch)_';
+    const parts = [`[new](${urls.snapshot(r.name)})`];
+    if (r.status === 'changed') {
+      parts.unshift(`[baseline](${urls.baseline(r.name)})`);
+      if (!r.layoutDiff) parts.push(`[diff](${urls.diff(r.name)})`);
+    }
+    return parts.join(' · ');
+  };
 
   for (const r of changed) {
     const approved = approvedNames.has(r.name) ? ' — ✅ approved' : '';
@@ -53,32 +84,24 @@ function buildReport({
         ? `${r.diffPercentage.toFixed(2)}% diff`
         : 'changed';
     lines.push(`<details><summary>🔄 <code>${escapeHtml(r.name)}</code> (${pct})${approved}</summary>`, '');
-    if (urls.baseline && !imageBudgetExceeded()) {
-      imagesUsed++;
-      const cells = [
-        `<img src="${urls.baseline(r.name)}" width="260">`,
-        `<img src="${urls.snapshot(r.name)}" width="260">`,
-        r.layoutDiff ? '—' : `<img src="${urls.diff(r.name)}" width="260">`,
-      ];
+    if (canEmbed(3)) {
+      imagesUsed += 3;
+      const cells = [img('baseline', r.name), img('snapshot', r.name), r.layoutDiff ? '—' : img('diff', r.name)];
       lines.push('| baseline | new | diff |', '| --- | --- | --- |', `| ${cells.join(' | ')} |`);
-    } else if (!urls.baseline) {
-      lines.push('_images unavailable (no write access to the baseline branch — see the report artifact)_');
     } else {
-      lines.push('_image budget exceeded — see the run artifacts for this diff_');
+      lines.push(linkRow(r));
     }
     lines.push('', '</details>', '');
   }
 
   for (const r of added) {
     const approved = approvedNames.has(r.name) ? ' — ✅ approved' : '';
     lines.push(`<details><summary>🆕 <code>${escapeHtml(r.name)}</code> (new snapshot)${approved}</summary>`, '');
-    if (urls.snapshot && !imageBudgetExceeded()) {
-      imagesUsed++;
-      lines.push(`<img src="${urls.snapshot(r.name)}" width="260">`);
-    } else if (!urls.snapshot) {
-      lines.push('_image unavailable (no write access to the baseline branch)_');
+    if (canEmbed(1)) {
+      imagesUsed += 1;
+      lines.push(img('snapshot', r.name));
     } else {
-      lines.push('_image budget exceeded — see the run artifacts_');
+      lines.push(linkRow(r));
     }
     lines.push('', '</details>', '');
   }
@@ -94,6 +117,10 @@ function buildReport({
     );
   }
 
+  if (inlineImages && urls.baseline && imagesUsed >= maxImages && changed.length + added.length > 0) {
+    lines.push(`_Inline image budget (${maxImages}) reached — remaining snapshots are linked above._`, '');
+  }
+
   if (needsReview) {
     lines.push(`To approve these changes, comment \`${commandPrefix} approve\` (write access required).`);
   }
@@ -105,16 +132,22 @@ function escapeHtml(s) {
   return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
-/** Build url helpers pointing at a pinned commit on the baseline branch. */
-function rawUrls({ repo, commitSha, baseRef, pendingDir }) {
-  if (!commitSha) return { baseline: null, snapshot: null, diff: null };
+/**
+ * Build url helpers pointing at a pinned commit on the baseline branch.
+ * `hasThumbs` controls whether thumb() resolves into pending/<...>/thumb/.
+ */
+function rawUrls({ repo, commitSha, baseRef, pendingDir, hasThumbs = false }) {
+  if (!commitSha) return { baseline: null, snapshot: null, diff: null, thumb: null };
   const server = process.env.GITHUB_SERVER_URL || 'https://github.com';
   const rawHost = server === 'https://github.com' ? 'https://raw.githubusercontent.com' : `${server}/raw`;
   const base = `${rawHost}/${repo}/${commitSha}`;
   return {
     baseline: (name) => `${base}/baselines/${encodePath(baseRef)}/${encodePath(name)}`,
     snapshot: (name) => `${base}/${pendingDir}/new/${encodePath(name)}`,
     diff: (name) => `${base}/${pendingDir}/diff/${encodePath(name)}`,
+    thumb: hasThumbs
+      ? (kind, name) => `${base}/${pendingDir}/thumb/${kind}/${encodePath(name)}`
+      : null,
   };
 }
 
 
@@ -0,0 +1,41 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { pool, warn } = require('./util');
+
+/**
+ * Load sharp from the runtime-installed prefix (same dir the action installs
+ * odiff-bin into) or a regular require (tests). Returns null when
+ * unavailable — callers fall back to embedding full-size images.
+ */
+function loadSharp() {
+  try {
+    const dir = process.env.NITPIX_ODIFF_DIR;
+    if (dir) return require(path.join(dir, 'node_modules', 'sharp'));
+    return require('sharp');
+  } catch (err) {
+    warn(`nitpix: sharp unavailable, comment will embed full-size images (${err.message})`);
+    return null;
+  }
+}
+
+/**
+ * Generate thumbnails for the report comment. `jobs` is a list of
+ * { src, kind, name }; thumbnails land in outDir/<kind>/<name>.
+ * Returns true when thumbnails were generated.
+ */
+async function makeThumbs(jobs, outDir, width) {
+  if (!width || jobs.length === 0) return false;
+  const sharp = loadSharp();
+  if (!sharp) return false;
+  await pool(jobs, 4, async ({ src, kind, name }) => {
+    const dest = path.join(outDir, kind, name);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    await sharp(src).resize({ width, withoutEnlargement: true }).png().toFile(dest);
+  });
+  return true;
+}
+
+module.exports = { makeThumbs };
@@ -11,6 +11,7 @@
     "test": "node --test test/"
   },
   "devDependencies": {
-    "odiff-bin": "4.3.8"
+    "odiff-bin": "4.3.8",
+    "sharp": "^0.35.0"
   }
 }
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,7 @@`
`11`	`11`	`"test": "node --test test/"`
`12`	`12`	`},`
`13`	`13`	`"devDependencies": {`
`14`		`- "odiff-bin": "4.3.8"`
	`14`	`+ "odiff-bin": "4.3.8",`
	`15`	`+ "sharp": "^0.35.0"`
`15`	`16`	`}`
`16`	`17`	`}`