flet-box 1.0.6 → 1.0.8

package/bin/commands/create.js

@@ -18,6 +18,7 @@ import { createFile, copyFile, makeExecutable } from "../utils/helpers.js";
 import * as templates from "../utils/templates.js";
 import { parseGithubRepo } from "../utils/bundleConfig.js";
 import { checkApi } from "../commands/checkApi.js";
+import { unpack } from "../commands/unpack.js";
 import { c, banner, gradient } from "../utils/colors.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -51,25 +52,38 @@ const capacitorAppId = (projectName) => {
  * @returns {{ template: string, projectName: string|null, repo: string|null }}
  */
 const parseCreateArgs = (args) => {
+  const TEMPLATES = ["basic", "adaptive", "blank", "full", "sidebar"];
   let template = "basic"; // default template
   let projectName = null;
   let repo = null;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--adaptive") {
+    const arg = args[i];
+    if (arg === "--adaptive") {
       template = "adaptive";
-    } else if (args[i] === "--blank") {
+    } else if (arg === "--blank") {
       template = "blank";
-    } else if (args[i] === "--full") {
+    } else if (arg === "--full") {
       template = "full";
-    } else if (args[i] === "--sidebar") {
+    } else if (arg === "--sidebar") {
       template = "sidebar";
-    } else if (args[i] === "--repo") {
+    } else if (arg === "--template" || arg.startsWith("--template=")) {
+      // `--template blank` was read as a bare positional, so the value became the
+      // project name and `flet-box create myapp --template blank` built a folder
+      // called `blank` running the `basic` template.
+      const inline = arg.startsWith("--template=");
+      const value = inline ? arg.slice("--template=".length) : args[++i];
+      if (TEMPLATES.includes(value)) template = value;
+      else if (value !== undefined)
+        console.warn(c("yellow", `⚠️ Unknown template "${value}", using ${template}`));
+    } else if (arg === "--repo") {
       if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
         repo = args[i + 1];
         i++;
       }
-    } else if (!args[i].startsWith("--")) {
-      projectName = args[i];
+    } else if (!arg.startsWith("--") && projectName === null) {
+      // The FIRST positional is the name. A later one is an unclaimed flag value
+      // and must not silently rename the project.
+      projectName = arg;
     }
   }
   return { template, projectName, repo };
@@ -94,6 +108,21 @@ const askRepo = () =>
     );
   });
 
+/**
+ * The GitHub Pages address a repo value implies, or null when the value is not
+ * a GitHub repo. Kept apart from `resolveOtaUrl` because the workflow header
+ * names the *Pages* site: a custom-domain OTA URL is not an address this file
+ * can publish to, so it must not be printed as one.
+ *
+ * @param {string|null} input - "user/repo" or a github.com URL.
+ * @returns {string|null} Base URL ending in "/", or null.
+ */
+const pagesSiteUrl = (input) => {
+  if (!input) return null;
+  const gh = parseGithubRepo(input.trim());
+  return gh ? `https://${gh.user}.github.io/${gh.repo}/` : null;
+};
+
 /**
  * Normalizes the user's OTA target into a base URL ending in "/".
  * - "user/repo" (or any GitHub URL shape) → GitHub Pages URL.
@@ -109,8 +138,7 @@ const resolveOtaUrl = (input) => {
   if (/^https?:\/\//i.test(value)) {
     return value.endsWith("/") ? value : `${value}/`;
   }
-  const gh = parseGithubRepo(value);
-  return gh ? `https://${gh.user}.github.io/${gh.repo}/` : null;
+  return pagesSiteUrl(value);
 };
 
 /**
@@ -153,6 +181,10 @@ export const createProject = async (projectName, rawArgs = []) => {
     repoInput = await askRepo();
   }
   const otaUrl = resolveOtaUrl(repoInput);
+  // The Pages address the workflow file prints as its own header. Derived from
+  // the repo alone: `flet-box create myapp --repo me/my-website` says so in
+  // build.yml, and a missing or unparsable repo leaves the placeholder to edit.
+  const siteUrl = pagesSiteUrl(repoInput);
   if (repoInput && !otaUrl) {
     console.warn(
       c(
@@ -184,6 +216,8 @@ export const createProject = async (projectName, rawArgs = []) => {
     ".fletbox/api",
     ".fletbox/memory/notes",
     ".claude",
+    ".claude/skills/fletbox-clean-ui",
+    ".qoder/skills/fletbox-clean-ui",
     ".cursor/rules",
   ];
   const extraDirs =
@@ -214,7 +248,11 @@ export const createProject = async (projectName, rawArgs = []) => {
   createFile(path.join(projectPath, ".gitignore"), templates.gitignore());
   createFile(
     path.join(projectPath, ".github/workflows/build.yml"),
-    templates.githubWorkflow(finalName, appId),
+    templates.githubWorkflow(finalName, siteUrl),
+  );
+  createFile(
+    path.join(projectPath, ".github/workflows/build-native.yml"),
+    templates.nativeWorkflow(finalName),
   );
   createFile(
     path.join(projectPath, "README.md"),
@@ -398,6 +436,29 @@ export const createProject = async (projectName, rawArgs = []) => {
     path.join(projectPath, ".cursor/rules/fletbox.mdc"),
     templates.cursorRules(),
   );
+
+  // The clean-UI skill. Claude Code loads `.claude/skills/<name>/SKILL.md` by
+  // description, so the agent picks it up whenever it touches a screen without
+  // being told. `.qoder/skills/` holds a byte-identical copy because Qoder reads
+  // the same shape from a different root — one text, two loaders, never two edits.
+  const cleanUiSkill = templates.cleanUiSkill();
+  createFile(
+    path.join(projectPath, ".claude/skills/fletbox-clean-ui/SKILL.md"),
+    cleanUiSkill,
+  );
+  createFile(
+    path.join(projectPath, ".qoder/skills/fletbox-clean-ui/SKILL.md"),
+    cleanUiSkill,
+  );
+  createFile(
+    path.join(projectPath, ".cursor/rules/fletbox-clean-ui.mdc"),
+    templates.cleanUiCursorRule(),
+  );
+  createFile(
+    path.join(projectPath, "scripts/check-ui.mjs"),
+    templates.checkUiScript(finalName),
+  );
+
   createFile(
     path.join(projectPath, ".fletbox/memory/MEMORY.md"),
     templates.memoryIndexMd(finalName),
@@ -418,6 +479,17 @@ export const createProject = async (projectName, rawArgs = []) => {
     print: (line) => console.log(line),
   });
 
+  // The machine-readable twin of the cheatsheet: one entry per widget per prop,
+  // each with the engine route, the default and a sample value that the types
+  // prove. The agent inside the app writes calls from this file.
+  const dump = await unpack(["--all", "--md", "--root", projectPath], { print: () => {} });
+  if (dump.exitCode !== 0)
+    console.warn(
+      c("yellow", "⚠️  Could not generate .fletbox/api/api.json — run `npm run api` after installing."),
+    );
+  else
+    console.log(`   ${c("gray", ".fletbox/api/api.json + api.md — the verified surface, for the agent")}`);
+
   makeExecutable(path.join(projectPath, "run.sh"));
 
   console.log(
@@ -464,8 +536,10 @@ export const createProject = async (projectName, rawArgs = []) => {
   console.log(
     c(
       "gray",
-      "CI:      .github/workflows/build.yml builds web + Android + iOS on every push.\n" +
-        "         Enable GitHub Pages (Settings → Pages → Source: GitHub Actions) for the web preview.\n",
+      "CI:      .github/workflows/build.yml publishes the web to GitHub Pages on every push.\n" +
+        `         It goes live at: ${siteUrl || `https://TU-USUARIO.github.io/${finalName}/`}\n` +
+        "         Enable it once: Settings → Pages → Source: GitHub Actions. The job prints the URL.\n" +
+        "         Android and iOS are manual: .github/workflows/build-native.yml, Run workflow.\n",
     ),
   );
   console.log(

package/bin/commands/createBundle.js

@@ -17,7 +17,8 @@ import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { c, banner, gradient, section } from "../utils/colors.js";
-import { buildBundleConfig, getGitRemoteUrl } from "../utils/bundleConfig.js";
+import { buildBundleConfig, collectAssets, getGitRemoteUrl, resolveAssetPatterns, absoluteShareTags } from "../utils/bundleConfig.js";
+import { normaliseManifest, writeSpaFallback } from "../utils/pwaShell.js";
 import { INITIAL_VERSION, incrementVersion, isValidVersion } from "../utils/version.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -57,6 +58,7 @@ const copyFolderSync = (src, dest) => {
  * ```
  * <target>/
  *   index.html
+ *   404.html          ← copy of the shell, so a refresh on a deep link serves the app
  *   manifest.json
  *   service-worker.js
  *   run.sh
@@ -191,6 +193,20 @@ export const createBundle = async (targetArg) => {
     console.log(c("green", "✅ Copied: src/assets (fonts + PWA icons)"));
   }
 
+  // The icon font is a stylesheet, not a bundle input, so it is copied as
+  // written. A generated app keeps it in src/assets/fonts (covered above); the
+  // framework root keeps it in src/fonts, which is the path its own index.html
+  // links — without this the bundled demo 404s the font and every <Icon/> is
+  // spelled as text.
+  if (fs.existsSync(path.join(srcDir, "fonts"))) {
+    fs.cpSync(
+      path.join(srcDir, "fonts"),
+      path.join(targetDir, "src", "fonts"),
+      { recursive: true },
+    );
+    console.log(c("green", "✅ Copied: src/fonts (icon font)"));
+  }
+
   // Copy global CSS (loaded directly by index.html, not bundled by esbuild).
   const globalCss = path.join(srcDir, "styles", "global.css");
   if (fs.existsSync(globalCss)) {
@@ -264,10 +280,31 @@ export const createBundle = async (targetArg) => {
   const stampedCode = header + bundledCode;
   fs.writeFileSync(outAppJs, stampedCode);
 
+  // ---- Release assets -----------------------------------------------------
+  // `update.assets` in fletbox.config.json lists files the app serves that are
+  // not part of the JS bundle (markdown docs, JSON data, images). They are copied
+  // into the bundle AND named in config.json with a hash, so an app that updated
+  // its bundle by OTA can still fetch the current copy of a file that its
+  // packaged build predates.
+  const assets = collectAssets(projectRoot, resolveAssetPatterns(projectRoot));
+  for (const asset of assets) {
+    const from = path.join(projectRoot, asset.path);
+    const to = path.join(targetDir, asset.path);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.copyFileSync(from, to);
+  }
+  if (assets.length) {
+    const kb = (assets.reduce((sum, a) => sum + a.size, 0) / 1024).toFixed(0);
+    console.log(
+      c("green", `✅ Copied: ${assets.length} OTA asset file(s) (${kb} KB)`),
+    );
+  }
+
   const bundleConfig = buildBundleConfig({
     projectRoot,
     bundleContent: stampedCode,
     bundlePath: "src/app.js",
+    assets,
   });
   fs.writeFileSync(
     path.join(targetDir, "config.json"),
@@ -355,6 +392,43 @@ export const createBundle = async (targetArg) => {
     }
   }
 
+  // ---- Social preview card --------------------------------------------------
+  // A scraper fetches the HTML and resolves the tags itself; it does not run the
+  // app and does not treat `./assets/hero.jpg` as the page origin does. Left
+  // relative, every share of the site posts a headline with no picture — and the
+  // site looks perfect to anyone who opens it, so nobody notices. The base is the
+  // URL OTA already derived, so the card points where the bundle is actually
+  // reachable, and only the built copy changes: `index.html` in the project stays
+  // host-agnostic so the same folder still runs on :8000 and through a tunnel.
+  const shareIndex = path.join(targetDir, "index.html");
+  if (fs.existsSync(shareIndex) && bundleConfig.update?.url) {
+    const html = fs.readFileSync(shareIndex, "utf8");
+    const stamped = absoluteShareTags(html, bundleConfig.update.url);
+    if (stamped !== html) {
+      fs.writeFileSync(shareIndex, stamped);
+      console.log(c("green", `✅ share card → absolute images at ${bundleConfig.update.url}`));
+    }
+  }
+
+  // ---- Installable, deep-linkable output ----------------------------------
+  // Both corrections belong to the deployable folder, not to the project: the
+  // app's own manifest.json stays host-agnostic and this bundle is what a static
+  // host serves. See bin/utils/pwaShell.js for the two failure modes.
+  const manifestFixes = normaliseManifest(targetDir);
+  if (manifestFixes.length) {
+    console.log(c("green", `✅ manifest.json → ${manifestFixes.length} correction(s)`));
+    for (const fix of manifestFixes) console.log(c("gray", `      ${fix}`));
+  }
+
+  if (writeSpaFallback(targetDir)) {
+    console.log(
+      c(
+        "green",
+        "✅ 404.html → copy of the shell (hosts without SPA rewrites now serve the app on a refresh)",
+      ),
+    );
+  }
+
   // Preserve the app source tree so the in-app "View code" feature can read it.
   for (const dir of ["modules", "screens", "database", "components"]) {
     const src = path.join(srcDir, dir);

package/bin/commands/images.js

@@ -0,0 +1,349 @@
+/**
+ * @file bin/commands/images.js
+ * @description `flet-box images` — shrinks a folder of photos to a byte budget
+ * with the platform's own WebP encoder.
+ *
+ * The problem this solves is a connection, not a disk: a page that pulls 8 MB of
+ * photographs never finishes loading, and every visitor pays for all of them at
+ * once. So the unit of work is the per-file budget, and the search goes in the
+ * order that costs quality least — throw away pixels nobody can see first, then
+ * ask the encoder harder.
+ *
+ * `to-png` is the sibling command for flat art. It stays lossless and needs no
+ * binary at all; this one needs a real encoder and says which one it found,
+ * because a photograph has no lossless answer. What it also cannot do is verify
+ * pixels: with no WebP decoder in the package, the read-back check is the
+ * container plus the alpha plane, which is why `--replace` asks the app's own
+ * sources before it deletes a master.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { c, section, dot } from "../utils/colors.js";
+import { decodeImage, readImageHeader, UnsupportedImage } from "../utils/images/index.js";
+import { readAppSources, references, protectedMaster } from "../utils/appSources.js";
+import { ensureEncoder, findEncoder, encode, tempIn, describeMachine, hasTransparency, webpCarriesAlpha } from "../utils/imageTools.js";
+
+const USAGE = `Usage: flet-box images [dir] [options]
+
+  dir                 Folder of photos (default: ./assets, or ./public/assets)
+
+Options:
+  --budget <KB>       Largest file to accept, per image (default: 40)
+  --width <px>        Never exceed this pixel width (default: the source width)
+  --quality <n>       Highest quality to try (default: 80, floor 62)
+  --referenced        Only convert sources whose .webp the app's own code names
+  --root <dir>        Project root the sources are read from (default: .)
+  --force             Overwrite an existing WebP with the same name
+  --replace           Delete each source after its WebP was written and read back
+  --install           Install the encoder this machine is missing
+  --dry-run           Report what would happen; write nothing
+  --quiet             Only the summary line
+  --help              This page`;
+
+const DEFAULT_DIRS = ["assets", "public/assets", "src/assets"];
+const SKIPPED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".cache", "www"]);
+const SOURCE_FILE = /\.(jpe?g|png)$/i;
+
+/**
+ * Pixels before quality, always in that order. A soft 540px photo at q70 is a
+ * better picture than a blocky 540px one at q44, and nobody can see the pixels
+ * between 2x the width the layout paints and the sensor's native 2000.
+ */
+const WIDTH_SCALES = [1, 0.9, 0.8, 0.7, 0.62];
+const QUALITY_FLOOR = 62;
+
+const size = (bytes) =>
+  bytes >= 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+    : bytes >= 1024
+      ? `${Math.round(bytes / 1024)} KB`
+      : `${bytes} B`;
+
+/**
+ * @param {string} dir
+ * @returns {string[]} Absolute paths, sorted.
+ */
+const collect = (dir) => {
+  const found = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIPPED_DIRS.has(entry.name)) walk(full);
+        continue;
+      }
+      if (entry.isFile() && SOURCE_FILE.test(entry.name)) found.push(full);
+    }
+  };
+  if (fs.existsSync(dir)) walk(dir);
+  return found.sort();
+};
+
+/**
+ * Confirms the bytes on disk are a WebP container.
+ *
+ * @param {Buffer} buf
+ * @returns {boolean}
+ */
+const isWebPBytes = (buf) =>
+  buf.length > 12 && buf.toString("ascii", 0, 4) === "RIFF" && buf.toString("ascii", 8, 12) === "WEBP";
+
+/**
+ * Runs the shrink.
+ *
+ * @param {string[]} args - CLI arguments after the command name.
+ * @returns {Promise<{exitCode: number}>} Non-zero when a file failed to encode.
+ */
+export const images = async (args = []) => {
+  const has = (flag) => args.includes(flag);
+  const valueOf = (flag) => {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+  };
+
+  if (has("--help") || has("-h")) {
+    console.log(USAGE);
+    return { exitCode: 0 };
+  }
+
+  const quiet = has("--quiet");
+  const dryRun = has("--dry-run");
+  const force = has("--force");
+  const replace = has("--replace");
+  const referenced = has("--referenced");
+  const budgetKB = Number(valueOf("--budget") || 40);
+  const capWidth = Number(valueOf("--width") || 0);
+  const topQuality = Number(valueOf("--quality") || 80);
+  const root = path.resolve(valueOf("--root") || ".");
+
+  if (!Number.isFinite(budgetKB) || budgetKB <= 0) {
+    console.log(c("red", `--budget wants a number of kilobytes, got: ${valueOf("--budget")}`));
+    return { exitCode: 1 };
+  }
+
+  const positional = args.filter(
+    (a, i) => !a.startsWith("--") && !["--budget", "--width", "--quality", "--root"].includes(args[i - 1]),
+  );
+  let target = positional[0] ? path.resolve(positional[0]) : null;
+  if (!target) {
+    target = DEFAULT_DIRS.map((d) => path.resolve(d)).find((d) => fs.existsSync(d)) || null;
+  }
+  if (!target || !fs.existsSync(target) || !fs.statSync(target).isDirectory()) {
+    console.log(c("red", `Nothing to convert: ${target || DEFAULT_DIRS.join(", ")} is not a folder here.`));
+    console.log(c("gray", "  Pass one: flet-box images assets/landing --budget 40"));
+    return { exitCode: 1 };
+  }
+
+  const encoder = await ensureEncoder(findEncoder(), { autoInstall: has("--install"), quiet });
+  if (!encoder) {
+    console.log("");
+    return { exitCode: 1 };
+  }
+
+  // The name gate is read from the app's own sources, comments stripped, so a
+  // note like `mojito.jpg is the frappé` does not count as a consumer. `--replace`
+  // always loads it: deleting a master because its WebP exists is only safe when
+  // something in the project already asks for that WebP by name.
+  const namesSources = referenced || replace;
+  const text = namesSources ? readAppSources(root) : "";
+  const keyOf = (file) => {
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    return rel && !rel.startsWith("..") ? rel : path.basename(file);
+  };
+  const named = (file) => references(text, keyOf(file));
+
+  const qualities = [];
+  for (let q = Math.max(QUALITY_FLOOR, Math.min(topQuality, 100)); q >= QUALITY_FLOOR; q -= 4) qualities.push(q);
+  if (qualities[qualities.length - 1] !== QUALITY_FLOOR) qualities.push(QUALITY_FLOOR);
+
+  const files = collect(target);
+  const lines = [];
+  let written = 0;
+  let inside = 0;
+  let over = 0;
+  let failed = 0;
+  let clash = 0;
+  let removed = 0;
+  let masters = 0;
+  let unreferenced = 0;
+  let sourceKept = 0;
+  let beforeBytes = 0;
+  let afterBytes = 0;
+
+  for (const file of files) {
+    const relative = path.relative(process.cwd(), file) || path.basename(file);
+    const out = path.join(path.dirname(file), path.basename(file, path.extname(file)) + ".webp");
+
+    const master = protectedMaster(keyOf(file));
+    if (master) {
+      masters++;
+      lines.push(`  ${dot("#64748b")} ${relative} — ${c("dim", `left alone: ${master.why}`)}`);
+      continue;
+    }
+
+    // The WebP, not the source: an app that loads `assets/favicon.png` by name
+    // means it — a browser tab icon and a social preview are declared formats, and
+    // a `favicon.webp` beside them is a file nothing requests. Point the code at
+    // the .webp and this converts it.
+    if (referenced && !named(out)) {
+      unreferenced++;
+      lines.push(`  ${dot("#64748b")} ${relative} — ${c("dim", `not referenced: no source loads ${path.basename(out)}`)}`);
+      continue;
+    }
+
+    let dims;
+    let sourceBytes;
+    try {
+      sourceBytes = fs.readFileSync(file);
+    } catch (error) {
+      failed++;
+      lines.push(`  ${dot("#ef4444")} ${relative} — ${c("red", "unreadable")} — ${error.message}`);
+      continue;
+    }
+    let fromHeader = false;
+    try {
+      dims = decodeImage(sourceBytes);
+    } catch (error) {
+      if (!(error instanceof UnsupportedImage)) {
+        failed++;
+        lines.push(`  ${dot("#ef4444")} ${relative} — ${c("red", "failed")} — ${error.message}`);
+        continue;
+      }
+      // A progressive JPEG is a ordinary export from Photoshop or macOS and every
+      // browser paints it; the pixel decoder declines multi-scan coding because
+      // that is the honest thing for a lossless converter to do. A budget search
+      // needs no pixels: the frame size and the presence of an alpha plane are
+      // both in the header, and the encoder reads the file itself.
+      try {
+        dims = readImageHeader(sourceBytes);
+        fromHeader = true;
+      } catch {
+        failed++;
+        lines.push(`  ${dot("#ef4444")} ${relative} — ${c("red", "declined")} — ${error.message}`);
+        continue;
+      }
+    }
+
+    const needsAlpha = fromHeader ? dims.hasAlpha === true : hasTransparency(dims.rgba);
+    const fullWidth = capWidth > 0 ? Math.min(dims.width, capWidth) : dims.width;
+    beforeBytes += sourceBytes.length;
+
+    // A file already inside the budget is not re-encoded: another lossy pass on
+    // bytes the same encoder already chose buys nothing anyone can see.
+    if (!force && fs.existsSync(out) && fs.statSync(out).size <= budgetKB * 1024) {
+      inside++;
+      afterBytes += fs.statSync(out).size;
+      continue;
+    }
+    if (fs.existsSync(out) && !force) {
+      clash++;
+      lines.push(`  ${dot("#f59e0b")} ${relative} — ${c("yellow", "kept")} — ${path.basename(out)} already exists (--force to replace it)`);
+      continue;
+    }
+
+    const tmp = tempIn(path.dirname(file), path.basename(file, path.extname(file)));
+    // The widest frame that still fits at an acceptable quality. Every scale is
+    // tried even when none of them fits, and the smallest attempt is kept: a file
+    // that cannot make the budget should still ship as small as it can, not be
+    // skipped and left at 900 KB.
+    let chosen = null;
+    let smallest = null;
+    for (const scale of WIDTH_SCALES) {
+      const width = Math.max(1, Math.round(fullWidth * scale));
+      for (const quality of qualities) {
+        const bytes = encode(encoder, { src: file, width, quality, out: tmp });
+        if (bytes === null) continue;
+        const candidate = { width, quality, bytes };
+        if (!smallest || candidate.bytes < smallest.bytes) smallest = candidate;
+        if (bytes <= budgetKB * 1024) {
+          chosen = candidate;
+          break;
+        }
+      }
+      if (chosen) break;
+    }
+    fs.rmSync(tmp, { force: true });
+    const final = chosen || smallest;
+
+    if (!final) {
+      failed++;
+      lines.push(`  ${dot("#ef4444")} ${relative} — ${c("red", "failed")} — ${encoder.bin} produced nothing for it`);
+      continue;
+    }
+
+    const overBudget = final.bytes > budgetKB * 1024;
+    afterBytes += final.bytes;
+    if (overBudget) over++;
+    const height = Math.max(1, Math.round((final.width / dims.width) * dims.height));
+
+    if (dryRun) {
+      written++;
+      lines.push(
+        `  ${dot("#22d3ee")} ${relative} → ${path.basename(out)} ${final.width}×${height} q${final.quality} ${size(sourceBytes.length)} → ${c(overBudget ? "yellow" : "green", size(final.bytes))}${overBudget ? c("yellow", " OVER") : ""}${needsAlpha ? c("dim", " ·alpha") : ""}${c("dim", " [dry run]")}`,
+      );
+      continue;
+    }
+
+    encode(encoder, { src: file, width: final.width, quality: final.quality, out });
+    let back = null;
+    try {
+      back = fs.readFileSync(out);
+    } catch {
+      back = null;
+    }
+    if (!back || !isWebPBytes(back)) {
+      failed++;
+      lines.push(`  ${dot("#ef4444")} ${relative} — ${c("red", "failed")} — the WebP written back is not readable`);
+      continue;
+    }
+    // The one pixel-level promise this container allows: if the source had a
+    // transparent pixel, the output must still have an alpha plane. A sticker
+    // flattened onto white is a different picture, and it is the kind of loss a
+    // byte budget cannot report.
+    if (needsAlpha && !webpCarriesAlpha(back)) {
+      failed++;
+      fs.rmSync(out, { force: true });
+      lines.push(`  ${dot("#ef4444")} ${relative} — ${c("red", "failed")} — ${path.basename(out)} has no alpha plane; the source's transparency was dropped`);
+      continue;
+    }
+    written++;
+    let gone = "";
+    if (replace && named(out)) {
+      fs.rmSync(file);
+      removed++;
+      gone = c("dim", " · source removed");
+    } else if (replace) {
+      sourceKept++;
+      gone = c("dim", ` · source kept: the app names ${path.basename(file)}, not ${path.basename(out)}`);
+    }
+    lines.push(
+      `  ${dot("#34d399")} ${relative} → ${path.basename(out)} ${final.width}×${height} q${final.quality} ${size(sourceBytes.length)} → ${c(overBudget ? "yellow" : "green", size(final.bytes))}${overBudget ? c("yellow", ` OVER ${budgetKB}KB`) : ""}${needsAlpha ? c("dim", " ·alpha") : ""}${gone}`,
+    );
+  }
+
+  if (!quiet) {
+    console.log(section("🖼", `images — ${path.relative(process.cwd(), target) || "."}`));
+    for (const line of lines) console.log(line);
+  }
+  if (!files.length) console.log(c("gray", "  No JPG or PNG files in that folder."));
+
+  const parts = [
+    `${written} written`,
+    inside ? `${inside} already inside budget` : null,
+    `${over} over ${budgetKB}KB`,
+    masters ? `${masters} master kept` : null,
+    unreferenced ? `${unreferenced} not referenced` : null,
+    clash ? `${clash} name clash` : null,
+    removed ? `${removed} sources removed` : null,
+    sourceKept ? `${sourceKept} sources kept` : null,
+    failed ? `${failed} failed` : null,
+    size(beforeBytes) + " → " + c(afterBytes < beforeBytes ? "green" : "yellow", size(afterBytes)),
+  ].filter(Boolean);
+  console.log(`\n  ${describeMachine()} · ${encoder.bin}\n`);
+  console.log(`  ${parts.join("  ·  ")}${dryRun ? c("yellow", "  ·  nothing written (--dry-run)") : ""}\n`);
+
+  return { exitCode: failed ? 1 : 0 };
+};
+
+export default images;