@lad-sapienza/scms-core 0.1.0-alpha.11 → 0.1.0-alpha.12

package/README.md

@@ -89,6 +89,96 @@ A consuming site typically wires these up as `npm run add-collection` / `npm run
 
 Both commands are multilingual-aware. `scms-add-collection` optionally takes a list of locale codes and scaffolds one sample per `src/content/<name>/<locale>/` folder; `scms-add-content` detects those language folders (every sub-folder is a locale code, nothing loose at the collection root) and asks which language the new file belongs in — a single locale, a comma-separated subset, or `all`.
 
+## Image optimization
+
+`scms-optimize-images` is a maintenance command (also a `bin`, run from the site's project root) that keeps the images in your content light: it converts every JPG/JPEG/PNG under the content folder to WebP, scales them down to a maximum size, deletes the originals and rewrites every reference to them in your `.md`/`.mdx` files. It uses [sharp](https://sharp.pixelplumbing.com/), so nothing else needs to be installed on the machine.
+
+```bash
+npx scms-optimize-images              # convert, delete the originals, rewrite references
+npx scms-optimize-images --dry-run    # print the estimated savings, touch nothing
+npx scms-optimize-images --check      # touch nothing; exit 1 if something is left to do
+npx scms-optimize-images --only a.jpg b.png   # limit the work to these files
+```
+
+Wire it up in the site's `package.json`:
+
+```json
+{
+  "scripts": {
+    "images": "scms-optimize-images",
+    "prebuild": "scms-optimize-images --check"
+  }
+}
+```
+
+`--check` never changes anything — the build must not modify or delete source files. It exits with a non-zero code (and lists the offenders) if it finds a JPG/PNG that could be converted, a WebP larger than the maximum size, or a stale reference from code (see below), so a forgotten image fails the build or the CI instead of being published at 5 MB. Fix it locally with `npm run images`, review the diff, commit.
+
+### What it does
+
+- **Resize**: the long side is limited to `maxSize` (2000 px); images are only ever scaled down. EXIF orientation is applied and metadata stripped.
+- **JPG → lossy WebP** at quality 82. **PNG → lossless WebP**; if the result is still larger than 50% of the original *and* the original is over 500 KB, it falls back to lossy WebP (quality 85, alpha quality 100).
+- **Not lighter, not converted**: when the WebP would not be smaller than the original, the original is left as it is. The verdict is stored (file hash + settings) in `.scms-optimize-images.json` at the project root — **commit it** — so such images are neither re-encoded on every run nor reported again by `--check`. Replace the file, or change a setting, and it is evaluated again.
+- **References** in `.md`/`.mdx` files (frontmatter such as `img:`, `![](…)`, relative and absolute paths) are rewritten. Absolute paths are rooted at the content folder, as in `contentAssetsIntegration`. `%20` is decoded and names are compared case-insensitively.
+- **Languages**: pages in a non-default language usually have no assets of their own and reuse those of the default-language twin (`blog/en/post/index.md` citing `a.jpg` that lives in `blog/it/post/`). Such references are resolved by swapping the language folder for the default one — using the languages declared in `userConfig.i18n` (below), not fixed codes.
+- **Name conflicts**: `bdus.jpg` + `bdus.png` would both become `bdus.webp`. The one cited by a `.md`/`.mdx` in the same folder (or its twin in another language) is kept, the other is deleted; if that does not single one out, both are skipped and reported.
+- **WebP already larger than `maxSize`** are scaled down in place (lossless stays lossless, lossy is re-encoded at `quality`), and reported by `--check`.
+- **Idempotent**: a second run changes nothing (and takes a fraction of a second).
+- The report lists converted files, skipped ones (with the reason), deleted duplicates and converted WebP that nothing cites (images in `gallery/` folders are not expected to be cited).
+
+### References in code
+
+Only `.md`/`.mdx` files are rewritten. Images can also be referenced from `.astro`, `.jsx`, `.tsx`, `.ts`, `.js` and `.mjs` files under `src/` (`<img src="/didattica/cover.jpg">`, `import x from '@content/…'`): those are **never rewritten** — every one that points at an image that is, or was, converted is reported with file and line, and the command exits with an error:
+
+```
+src/pages/[locale]/didattica/index.astro:22  /didattica/cover.jpg is now broken: the image was converted → use /didattica/cover.webp
+```
+
+The report keeps coming back (also from `--check`) until the code is fixed, so a broken link cannot slip through silently. Paths are resolved from the content folder (`/…`), from the file (`./…`, `../…`) and through the `@content/` and `@user/` aliases.
+
+### Configuration
+
+All optional; defaults shown. In `src/user.config.mjs`:
+
+```js
+export const userConfig = {
+  // Languages of the site. Pages in a language other than defaultLocale may reuse
+  // the images of the defaultLocale twin. Omit for a monolingual site.
+  i18n: {
+    defaultLocale: 'it',
+    locales: ['it', 'en'],
+  },
+
+  images: {
+    contentDir: 'src/content',  // scanned for images and .md/.mdx files
+    srcDir: 'src',              // scanned for references from code
+    maxSize: 2000,              // px, long side
+    quality: 82,                // WebP quality for JPGs (and for re-encoded lossy WebP)
+    pngLossyRatio: 0.5,         // PNG: go lossy if lossless WebP > this fraction of the original...
+    pngLossyMinSize: 500,       // ...and the original is larger than this many KB
+    pngLossyQuality: 85,        // quality of that lossy fallback
+    exclude: [],                // folders left alone: paths relative to contentDir, or plain folder names
+  },
+};
+```
+
+Keep `i18n` in sync with the site's own locale list (e.g. `LOCALES`/`DEFAULT_LOCALE` in `src/utils/i18n.ts`). Images outside the content folder (e.g. `public/`) are never touched.
+
+### Optional: pre-commit hook
+
+Nothing is installed automatically. If you want images checked at commit time, add `.git/hooks/pre-commit` (or the equivalent in husky/lefthook) and make it executable. It only looks at the images staged in the commit:
+
+```sh
+#!/bin/sh
+# Block the commit if a staged image is not optimized
+git diff --cached --name-only --diff-filter=AM -z -- '*.jpg' '*.jpeg' '*.png' '*.JPG' '*.JPEG' '*.PNG' '*.webp' \
+  | xargs -0 npx scms-optimize-images --check --only || {
+    echo "Run 'npm run images', review the changes and stage them." >&2
+    exit 1
+  }
+```
+
+An empty list is fine: `--only` with no files does nothing and exits 0. To convert instead of just blocking, run `npx scms-optimize-images --only <files>` and then `git add` the converted `.webp` files and the rewritten `.md`/`.mdx` — the command never stages anything itself.
+
 ## Development
 
 ```bash

package/bin/lib/optimize-images.mjs

@@ -0,0 +1,440 @@
+// optimize-images engine — shared by bin/optimize-images.mjs and the tests.
+//
+// Converts the JPG/PNG images found under the content directory to WebP (max
+// `maxSize` px on the long side), deletes the originals and rewrites every
+// reference to them in the .md/.mdx files. Pure Node + sharp: no side effects
+// besides the file system, no console output (the CLI prints the report).
+//
+// See the "Image optimization" section of the package README for the rules.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+
+export const DEFAULTS = {
+  /** Folder (relative to the project root) scanned for images and .md/.mdx files. */
+  contentDir: 'src/content',
+  /** Folder (relative to the project root) scanned for code files referencing images. */
+  srcDir: 'src',
+  /** Max size, in px, of the long side. Images are only ever scaled down. */
+  maxSize: 2000,
+  /** WebP quality for JPGs. */
+  quality: 82,
+  /** PNG: fall back to lossy when the lossless WebP is larger than this fraction of the original... */
+  pngLossyRatio: 0.5,
+  /** ...and the original is larger than this many KB. */
+  pngLossyMinSize: 500,
+  /** Quality of the lossy PNG fallback. */
+  pngLossyQuality: 85,
+  /** Folders (relative to contentDir, or plain folder names) left untouched. */
+  exclude: [],
+};
+
+export const MANIFEST_NAME = '.scms-optimize-images.json';
+
+const IMAGE_RE = /\.(jpe?g|png)$/i;
+const TEXT_RE = /\.mdx?$/i;
+const CODE_RE = /\.(astro|jsx|tsx|mjs|ts|js)$/i;
+// A reference token inside a markdown/frontmatter line (no whitespace, quotes or brackets)
+const MD_REF_RE = /[^\s"'()<>[\]=]+\.(?:jpe?g|png)(?![\w.])/gi;
+// Same for code, where the token can also be delimited by template-literal / JSX / object punctuation
+const CODE_REF_RE = /[^\s"'`()<>[\]={},;]+\.(?:jpe?g|png)(?![\w.])/gi;
+
+const posix = (p) => p.split(path.sep).join('/');
+const kb = (bytes) => (bytes / 1024).toFixed(0);
+
+/** Merges `userConfig.images` / `userConfig.i18n` (either may be undefined) over the defaults. */
+export function resolveConfig(root, userConfig = {}) {
+  const images = { ...DEFAULTS, ...(userConfig.images ?? {}) };
+  const i18n = userConfig.i18n ?? {};
+  const locales = Array.isArray(i18n.locales) ? i18n.locales : [];
+  const defaultLocale = i18n.defaultLocale ?? locales[0];
+  return {
+    root,
+    contentRoot: path.resolve(root, images.contentDir),
+    srcRoot: path.resolve(root, images.srcDir),
+    maxSize: images.maxSize,
+    quality: images.quality,
+    pngLossyRatio: images.pngLossyRatio,
+    pngLossyMinSize: images.pngLossyMinSize,
+    pngLossyQuality: images.pngLossyQuality,
+    exclude: (images.exclude ?? []).map((e) => posix(e).replace(/^\.?\/+|\/+$/g, '')),
+    locales,
+    defaultLocale,
+  };
+}
+
+function walk(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .flatMap((e) => {
+      if (e.name === 'node_modules' || e.name.startsWith('.')) return [];
+      const p = path.join(dir, e.name);
+      return e.isDirectory() ? walk(p) : [p];
+    });
+}
+
+function isExcluded(c, rel) {
+  const segments = rel.split('/');
+  return c.exclude.some((e) => rel === e || rel.startsWith(`${e}/`) || (!e.includes('/') && segments.slice(0, -1).includes(e)));
+}
+
+// ─── Locale twins ────────────────────────────────────────────────────────────
+
+/**
+ * Alternative locations of a path: pages in a non-default locale have no assets
+ * of their own and reuse the files of their default-locale twin, so the first
+ * locale segment of a non-default language is swapped for the default one.
+ * `relPath` is relative to the content root, posix-style.
+ */
+function defaultLocaleTwin(c, relPath) {
+  if (!c.defaultLocale) return null;
+  const segments = relPath.split('/');
+  const i = segments.findIndex((s) => s !== c.defaultLocale && c.locales.includes(s));
+  if (i === -1) return null;
+  segments[i] = c.defaultLocale;
+  return segments.join('/');
+}
+
+/** The folder itself plus its twins in the other languages (used to find which images a page cites). */
+function twinDirs(c, dir) {
+  const rel = posix(path.relative(c.contentRoot, dir));
+  const segments = rel.split('/');
+  const out = [dir];
+  const i = c.defaultLocale ? segments.indexOf(c.defaultLocale) : -1;
+  if (i !== -1) {
+    for (const l of c.locales.filter((l) => l !== c.defaultLocale)) {
+      const s = [...segments];
+      s[i] = l;
+      out.push(path.join(c.contentRoot, ...s));
+    }
+  }
+  return out;
+}
+
+// ─── Manifest (images known not to benefit) ──────────────────────────────────
+
+const sha1 = (file) => crypto.createHash('sha1').update(fs.readFileSync(file)).digest('hex');
+
+function settingsHash(c) {
+  const s = [c.maxSize, c.quality, c.pngLossyRatio, c.pngLossyMinSize, c.pngLossyQuality].join('|');
+  return crypto.createHash('sha1').update(s).digest('hex').slice(0, 10);
+}
+
+function loadManifest(c) {
+  const file = path.join(c.root, MANIFEST_NAME);
+  try {
+    const m = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return m && m.settings === settingsHash(c) && m.kept ? m.kept : {};
+  } catch {
+    return {};
+  }
+}
+
+function saveManifest(c, kept) {
+  const file = path.join(c.root, MANIFEST_NAME);
+  const keys = Object.keys(kept).sort();
+  if (!keys.length) {
+    fs.rmSync(file, { force: true });
+    return;
+  }
+  const sorted = Object.fromEntries(keys.map((k) => [k, kept[k]]));
+  fs.writeFileSync(file, `${JSON.stringify({ settings: settingsHash(c), kept: sorted }, null, 2)}\n`);
+}
+
+// ─── sharp ───────────────────────────────────────────────────────────────────
+
+// Inputs are always passed to sharp as buffers, never as paths: libvips caches by file path
+// and would serve stale metadata for a file rewritten earlier in the same process.
+function pipeline(input, c) {
+  return sharp(Buffer.isBuffer(input) ? input : fs.readFileSync(input), { failOn: 'error' })
+    .rotate()
+    .resize({ width: c.maxSize, height: c.maxSize, fit: 'inside', withoutEnlargement: true });
+}
+
+/** Encodes a JPG/PNG to WebP. Same lossless/lossy logic as the original ImageMagick script. */
+async function encode(src, c) {
+  if (!/\.png$/i.test(src)) return pipeline(src, c).webp({ quality: c.quality }).toBuffer();
+  // PNGs are mostly screenshots and graphics: lossless first, lossy if that is still heavy
+  const original = fs.statSync(src).size;
+  let out = await pipeline(src, c).webp({ lossless: true, effort: 6 }).toBuffer();
+  if (out.length > original * c.pngLossyRatio && original > c.pngLossyMinSize * 1024) {
+    out = await pipeline(src, c).webp({ quality: c.pngLossyQuality, alphaQuality: 100 }).toBuffer();
+  }
+  return out;
+}
+
+/** True for a lossless WebP (VP8L chunk), false for lossy (VP8 chunk). */
+function webpIsLossless(buf) {
+  let offset = 12;
+  while (offset + 8 <= buf.length) {
+    const fourcc = buf.toString('ascii', offset, offset + 4);
+    if (fourcc === 'VP8L') return true;
+    if (fourcc === 'VP8 ') return false;
+    const size = buf.readUInt32LE(offset + 4);
+    offset += 8 + size + (size & 1);
+  }
+  return false;
+}
+
+async function resizeWebp(file, c) {
+  const buf = fs.readFileSync(file);
+  const opts = webpIsLossless(buf) ? { lossless: true, effort: 6 } : { quality: c.quality, alphaQuality: 100 };
+  return { before: buf.length, out: await pipeline(buf, c).webp(opts).toBuffer() };
+}
+
+async function pixelSize(file) {
+  const m = await sharp(fs.readFileSync(file), { failOn: 'error' }).metadata();
+  return { max: Math.max(m.width ?? 0, m.height ?? 0), animated: (m.pages ?? 1) > 1 };
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {ReturnType<typeof resolveConfig>} c
+ * @param {{ dryRun?: boolean, check?: boolean, only?: string[] | null }} [mode]
+ *   `check`: touch nothing and convert nothing, just list what is left to do.
+ *   `only`: restrict the images that get converted/checked to these files.
+ */
+export async function optimizeImages(c, { dryRun = false, check = false, only = null } = {}) {
+  const readOnly = dryRun || check;
+  const rel = (f) => posix(path.relative(c.contentRoot, f));
+  const onlySet = only ? new Set(only.map((f) => path.resolve(f).toLowerCase())) : null;
+  const inScope = (f) => !onlySet || onlySet.has(f.toLowerCase());
+
+  const report = {
+    converted: [], // { rel, before, after }
+    skipped: [], // { rel, reason }
+    dropped: [], // unused duplicates (rel)
+    resized: [], // oversized WebPs scaled down: { rel, before, after }
+    pending: [], // --check: JPG/PNG still to convert (rel)
+    oversized: [], // --check: WebP larger than maxSize (rel)
+    unreferenced: [],
+    codeRefs: [], // { file, line, ref, kind, replacement }
+    keptCount: 0, // already known not to benefit, left alone
+    rewritten: 0,
+    before: 0,
+    after: 0,
+    problems: 0,
+  };
+
+  const all = walk(c.contentRoot).filter((f) => !isExcluded(c, rel(f)));
+  const textFiles = all.filter((f) => TEXT_RE.test(f));
+  const allImages = all.filter((f) => IMAGE_RE.test(f));
+  const webps = all.filter((f) => /\.webp$/i.test(f));
+
+  const kept = loadManifest(c);
+  const keptKey = (f) => rel(f);
+  const isKept = (f) => {
+    const e = kept[keptKey(f)];
+    return Boolean(e) && e.sha1 === sha1(f);
+  };
+  const markKept = (f, reason) => {
+    kept[keptKey(f)] = { sha1: sha1(f), reason };
+  };
+
+  const converted = new Map(); // old absolute path -> new absolute path
+
+  if (check) {
+    for (const f of allImages) {
+      if (!inScope(f)) continue;
+      if (isKept(f)) report.keptCount++;
+      else report.pending.push(rel(f));
+    }
+    for (const f of webps) {
+      if (!inScope(f) || isKept(f)) continue;
+      const { max, animated } = await pixelSize(f).catch(() => ({ max: 0, animated: true }));
+      if (!animated && max > c.maxSize) report.oversized.push(rel(f));
+    }
+    for (const f of allImages.filter((f) => inScope(f) && !isKept(f))) converted.set(f, f.replace(IMAGE_RE, '.webp'));
+  } else {
+    // Same name, different extension in one folder (e.g. bdus.jpg + bdus.png): they would both
+    // become bdus.webp. Keep only the one a sibling .md/.mdx (or its locale twin) points to.
+    let images = allImages;
+    const byTarget = new Map();
+    for (const f of images) {
+      const k = f.replace(IMAGE_RE, '');
+      byTarget.set(k, [...(byTarget.get(k) ?? []), f]);
+    }
+    for (const group of [...byTarget.values()].filter((g) => g.length > 1)) {
+      const dirs = twinDirs(c, path.dirname(group[0]));
+      const text = dirs
+        .flatMap((d) => textFiles.filter((t) => path.dirname(t) === d))
+        .map((t) => fs.readFileSync(t, 'utf8'))
+        .join('\n');
+      const used = group.filter((g) => text.includes(path.basename(g)));
+      if (used.length !== 1) continue; // ambiguous: reported as skipped below
+      for (const unused of group.filter((g) => g !== used[0])) {
+        if (!inScope(unused)) continue;
+        report.dropped.push(rel(unused));
+        if (!readOnly) fs.rmSync(unused);
+      }
+      images = images.filter((i) => !group.includes(i) || i === used[0]);
+    }
+
+    for (const src of images) {
+      if (!inScope(src)) continue;
+      const dest = src.replace(IMAGE_RE, '.webp');
+      const name = rel(src);
+
+      if (isKept(src)) {
+        report.keptCount++;
+        continue;
+      }
+      if (fs.existsSync(dest) || images.some((o) => o !== src && o.replace(IMAGE_RE, '.webp') === dest)) {
+        report.skipped.push({ rel: name, reason: 'target .webp already exists or name clashes with another image' });
+        continue;
+      }
+
+      const origSize = fs.statSync(src).size;
+      let out;
+      try {
+        const { animated } = await pixelSize(src);
+        if (animated) {
+          report.skipped.push({ rel: name, reason: 'animated image, left as is' });
+          continue;
+        }
+        out = await encode(src, c);
+      } catch (err) {
+        report.skipped.push({ rel: name, reason: `conversion failed (${err.message.split('\n')[0]})` });
+        continue;
+      }
+      if (out.length >= origSize) {
+        report.skipped.push({ rel: name, reason: `WebP is not smaller (${kb(origSize)} -> ${kb(out.length)} KB), kept as is` });
+        if (!readOnly) markKept(src, 'webp-not-smaller');
+        continue;
+      }
+
+      report.before += origSize;
+      report.after += out.length;
+      converted.set(src, dest);
+      report.converted.push({ rel: name, before: origSize, after: out.length });
+      if (!readOnly) {
+        const tmp = `${dest}.tmp`;
+        fs.writeFileSync(tmp, out);
+        fs.renameSync(tmp, dest);
+        fs.rmSync(src);
+      }
+    }
+
+    // WebPs that were already there but exceed the max size are scaled down in place
+    // (same mode as the source: lossless stays lossless, lossy is re-encoded at `quality`).
+    for (const f of webps) {
+      if (!inScope(f)) continue;
+      if (isKept(f)) {
+        report.keptCount++;
+        continue;
+      }
+      try {
+        const { max, animated } = await pixelSize(f);
+        if (animated || max <= c.maxSize) continue;
+        const { before, out } = await resizeWebp(f, c);
+        if (out.length >= before) {
+          report.skipped.push({ rel: rel(f), reason: 'oversized WebP, but scaling it down does not make it smaller, kept as is' });
+          if (!readOnly) markKept(f, 'resize-not-smaller');
+          continue;
+        }
+        report.resized.push({ rel: rel(f), before, after: out.length });
+        if (!readOnly) fs.writeFileSync(f, out);
+      } catch (err) {
+        report.skipped.push({ rel: rel(f), reason: `could not inspect WebP (${err.message.split('\n')[0]})` });
+      }
+    }
+
+    if (!readOnly) {
+      // prune entries whose file is gone (or no longer the one that was evaluated)
+      for (const k of Object.keys(kept)) {
+        const abs = path.join(c.contentRoot, ...k.split('/'));
+        if (!fs.existsSync(abs) || sha1(abs) !== kept[k].sha1) delete kept[k];
+      }
+      saveManifest(c, kept);
+    }
+
+    // Rewrite references in .md/.mdx
+    const lookup = new Map([...converted].map(([o, n]) => [o.toLowerCase(), n]));
+    for (const file of textFiles) {
+      const dir = path.dirname(file);
+      const text = fs.readFileSync(file, 'utf8');
+      const next = text.replace(MD_REF_RE, (ref) => {
+        if (/^(https?:)?\/\//i.test(ref)) return ref;
+        let decoded = ref;
+        try {
+          decoded = decodeURIComponent(ref);
+        } catch {
+          /* keep raw */
+        }
+        // Relative to the file, or absolute from the content root (see contentAssetsIntegration)
+        const target = decoded.startsWith('/') ? path.join(c.contentRoot, decoded) : path.resolve(dir, decoded);
+        // Pages in a non-default language have no assets of their own: they reuse the twin's files
+        const twinRel = defaultLocaleTwin(c, rel(target));
+        const twin = twinRel ? path.join(c.contentRoot, ...twinRel.split('/')) : null;
+        const hit = lookup.get(target.toLowerCase()) ?? (twin ? lookup.get(twin.toLowerCase()) : undefined);
+        return hit ? ref.replace(IMAGE_RE, '.webp') : ref;
+      });
+      if (next !== text) {
+        report.rewritten++;
+        if (!readOnly) fs.writeFileSync(file, next);
+      }
+    }
+  }
+
+  // ─── References from code (reported, never rewritten) ──────────────────────
+  const codeFiles = walk(c.srcRoot).filter((f) => CODE_RE.test(f) && !f.startsWith(c.contentRoot + path.sep));
+  const existing = new Set(all.map((f) => f.toLowerCase()));
+  const convertedLower = new Map([...converted].map(([o, n]) => [o.toLowerCase(), n]));
+  const kind = check || dryRun ? 'to-convert' : 'converted';
+
+  for (const file of codeFiles) {
+    const dir = path.dirname(file);
+    const lines = fs.readFileSync(file, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      for (const [ref] of line.matchAll(CODE_REF_RE)) {
+        if (/^(https?:)?\/\//i.test(ref)) continue;
+        let decoded = ref;
+        try {
+          decoded = decodeURIComponent(ref);
+        } catch {
+          /* keep raw */
+        }
+        const candidates = decoded.startsWith('@content/')
+          ? [path.join(c.contentRoot, decoded.slice(9))]
+          : decoded.startsWith('@user/')
+            ? [path.join(c.srcRoot, decoded.slice(6))]
+            : decoded.startsWith('/')
+              ? [path.join(c.contentRoot, decoded)]
+              : [path.resolve(dir, decoded), path.join(c.contentRoot, decoded)];
+        let found = null;
+        for (const cand of candidates) {
+          const lower = cand.toLowerCase();
+          if (convertedLower.has(lower)) {
+            found = kind;
+            break;
+          }
+          // a JPG/PNG that no longer exists although its .webp does: left over from an earlier conversion
+          if (!existing.has(lower) && existing.has(lower.replace(IMAGE_RE, '.webp'))) {
+            found = 'stale';
+            break;
+          }
+        }
+        if (found) {
+          report.codeRefs.push({ file: posix(path.relative(c.root, file)), line: i + 1, ref, kind: found, replacement: ref.replace(IMAGE_RE, '.webp') });
+        }
+      }
+    });
+  }
+
+  // Sanity check: every converted file must be referenced or live in a gallery/ folder
+  if (!readOnly) {
+    const corpus = [...textFiles, ...codeFiles].map((f) => fs.readFileSync(f, 'utf8')).join('\n');
+    report.unreferenced = [...converted.values()]
+      .filter((d) => !rel(d).split('/').includes('gallery'))
+      .filter((d) => !corpus.includes(path.basename(d)))
+      .map(rel);
+  }
+
+  report.problems = check ? report.pending.length + report.oversized.length + report.codeRefs.length : report.codeRefs.length;
+  return report;
+}

package/bin/optimize-images.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// optimize-images.mjs — Convert content images to WebP and rewrite their references.
+// Usage: npx scms-optimize-images [--dry-run | --check] [--only <file>...]
+//    or: npm run images (from a consuming site's package.json)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { optimizeImages, resolveConfig } from './lib/optimize-images.mjs';
+
+const G = '\x1b[32m', Y = '\x1b[33m', R = '\x1b[31m';
+const B = '\x1b[1m', X = '\x1b[0m';
+
+const HELP = `scms-optimize-images — convert content JPG/PNG images to WebP
+
+  scms-optimize-images                 convert, delete the originals, rewrite references
+  scms-optimize-images --dry-run       report what would happen, touch nothing
+  scms-optimize-images --check         touch nothing; exit 1 if anything is left to convert
+                                       (JPG/PNG, WebP larger than the max size, stale code references).
+                                       Meant for "prebuild" scripts and CI.
+  scms-optimize-images --only <files>  limit conversion/checks to these image files
+                                       (e.g. the ones staged in a pre-commit hook)
+
+Settings live in src/user.config.mjs (userConfig.images, userConfig.i18n); see the scms-core README.`;
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(HELP);
+  process.exit(0);
+}
+const dryRun = args.includes('--dry-run');
+const check = args.includes('--check');
+const onlyIdx = args.indexOf('--only');
+const only = onlyIdx === -1 ? null : args.slice(onlyIdx + 1).filter((a) => !a.startsWith('--'));
+const unknown = args.filter((a) => a.startsWith('-') && !['--dry-run', '--check', '--only'].includes(a));
+if (unknown.length) {
+  console.error(`${R}✖${X}  Unknown option: ${unknown.join(' ')}\n\n${HELP}`);
+  process.exit(2);
+}
+if (only && only.length === 0) {
+  console.log('No files given to --only, nothing to do.');
+  process.exit(0);
+}
+
+// This file ships inside the @lad-sapienza/scms-core package (bin/): the project is wherever it was run from.
+const ROOT = process.cwd();
+const configFile = path.join(ROOT, 'src', 'user.config.mjs');
+let userConfig = {};
+if (fs.existsSync(configFile)) {
+  try {
+    userConfig = (await import(pathToFileURL(configFile).href)).userConfig ?? {};
+  } catch (err) {
+    console.error(`${R}✖${X}  Cannot load src/user.config.mjs: ${err.message}`);
+    process.exit(2);
+  }
+}
+
+const config = resolveConfig(ROOT, userConfig);
+if (!fs.existsSync(config.contentRoot)) {
+  console.error(`${R}✖${X}  Content folder not found: ${config.contentRoot}`);
+  process.exit(2);
+}
+
+const r = await optimizeImages(config, { dryRun, check, only });
+
+const kb = (n) => (n / 1024).toFixed(0);
+const mb = (n) => (n / 1048576).toFixed(1);
+const list = (title, items) => items.length && console.log(`\n${title} (${items.length}):\n  ${items.join('\n  ')}`);
+const tag = dryRun ? '[dry run] ' : '';
+
+if (check) {
+  list(`${R}JPG/PNG images to convert${X}`, r.pending);
+  list(`${R}WebP images larger than ${config.maxSize}px${X}`, r.oversized);
+} else {
+  for (const c of r.converted) console.log(`${c.rel}: ${kb(c.before)} -> ${kb(c.after)} KB`);
+  for (const c of r.resized) console.log(`${c.rel}: scaled to max ${config.maxSize}px, ${kb(c.before)} -> ${kb(c.after)} KB`);
+  console.log(`\n${tag}${r.converted.length} images converted, ${r.resized.length} resized, ${r.rewritten} text files updated`);
+  console.log(`Size: ${mb(r.before)} MB -> ${mb(r.after)} MB${r.before ? ` (-${(100 - (r.after / r.before) * 100).toFixed(0)}%)` : ''}`);
+  list(`${B}Unused duplicates ${dryRun ? 'to delete' : 'deleted'}${X}`, r.dropped);
+  list(`${Y}Skipped${X}`, r.skipped.map((s) => `${s.rel}: ${s.reason}`));
+  list(`${Y}Converted but not referenced anywhere (check)${X}`, r.unreferenced);
+  if (r.keptCount) console.log(`\n${r.keptCount} image(s) already evaluated and kept as they are (see .scms-optimize-images.json)`);
+}
+
+if (r.codeRefs.length) {
+  const verb = { 'to-convert': 'will break once the image is converted', converted: 'is now broken: the image was converted', stale: 'points to an image that was converted earlier' };
+  console.error(`\n${R}✖${X}  ${r.codeRefs.length} reference(s) in code must be updated by hand (code is never rewritten):`);
+  for (const c of r.codeRefs) console.error(`  ${c.file}:${c.line}  ${c.ref} ${verb[c.kind]} → use ${c.replacement}`);
+}
+
+if (r.problems) {
+  console.error(`\n${R}✖${X}  ${r.problems} problem(s) found.${check ? ' Run `npx scms-optimize-images` to fix the images.' : ''}`);
+  process.exit(1);
+}
+if (check) console.log(`${G}✔${X}  Images are optimized.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lad-sapienza/scms-core",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "description": "Framework components and Astro integrations for s:CMS — DataTb, Gallery, Map, ZoteroGeoViewer, Record.",
   "type": "module",
   "license": "BSD-0-Clause",
@@ -13,7 +13,8 @@
   "bin": {
     "scms-add-collection": "./bin/add-collection.mjs",
     "scms-add-content": "./bin/add-content.mjs",
-    "scms-create": "./bin/create.mjs"
+    "scms-create": "./bin/create.mjs",
+    "scms-optimize-images": "./bin/optimize-images.mjs"
   },
   "files": [
     "index.ts",
@@ -54,6 +55,7 @@
     "papaparse": "^5.5.3",
     "photoswipe": "^5.4.4",
     "react-photoswipe-gallery": "^4.0.0",
+    "sharp": "^0.35.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/template/README.md.tmpl

@@ -14,6 +14,19 @@ Built with [s:CMS](https://github.com/lad-sapienza/scms-core), on top of [Astro]
 | `npm run preview` | Preview the production build locally |
 | `npm run add-collection` | Scaffold a new content collection |
 | `npm run add-content` | Add a new content file to an existing collection |
+| `npm run images` | Convert content images to WebP (max 2000 px) and rewrite their references |
+
+## Optimizing images
+
+Drop JPG/PNG images next to your content as usual, then run `npm run images`: they are converted to WebP, scaled down to 2000 px, the originals are deleted and the `.md`/`.mdx` references are rewritten (`--dry-run` shows the savings without touching anything). References from `.astro`/`.tsx` files are only reported — update them by hand.
+
+To make the build fail when an unoptimized image slips in, add a check to `package.json`; it never modifies any file:
+
+```json
+"prebuild": "scms-optimize-images --check"
+```
+
+Limits, quality and the site languages are configured in `src/user.config.mjs` (`userConfig.images`, `userConfig.i18n`); see the [scms-core README](https://github.com/lad-sapienza/scms-core#image-optimization) for all the options, including an optional pre-commit hook. Commit the `.scms-optimize-images.json` file it may create.
 
 ## Updating the framework
 

package/template/package.json.tmpl

@@ -10,7 +10,8 @@
     "preview": "astro preview",
     "astro": "astro",
     "add-collection": "scms-add-collection",
-    "add-content": "scms-add-content"
+    "add-content": "scms-add-content",
+    "images": "scms-optimize-images"
   },
   "dependencies": {
     "@astrojs/check": "^0.9.10",