@koehler8/cms 1.4.1 → 1.4.2

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 1.4.2
+
+### Fixed
+
+- **`manifest.json` no longer names an icon that 404s.** Its primary icon has
+  always been `/favicon-256.png`, but `cms-generate-public-assets` never left
+  that file behind: on the letter-glyph path it wrote it only as a temporary
+  input to the `.ico` and deleted it, and when a site ships its own
+  `site/favicon.ico` it returned before writing it at all. Every site in the
+  fleet served a manifest whose 256px icon 404'd (found on site-chrismaus,
+  which worked around it with `manifest.icons` overrides).
+
+  `cms-generate-public-assets` now always tries to publish
+  `public/favicon-256.png`:
+
+  - **Letter-glyph favicon** — the 256px glyph it already renders is kept.
+  - **Site-provided `favicon.ico`** — its 256px frame, extracted as-is (PNG
+    frames) or decoded (32-bit BMP frames, which canvas can't read). Failing
+    that, a **square** `site/assets/img/logo.png` scaled to 256px. A
+    non-square logo is never squashed into the icon, and a smaller favicon
+    frame is never upscaled.
+  - **Neither available** — no icon is written (a stale copy is removed) and
+    the script says how to fix it.
+
+  And the plugin now lists a default icon in `manifest.json` only if the file
+  is actually in `public/` when the build starts, so the manifest can't drift
+  from what ships. Author-supplied `site.manifest.icons` are untouched.
+
+  **No action needed in a site** beyond picking up this release. Across the
+  fleet, sites without their own `favicon.ico` get the letter glyph; most of
+  the rest have a 256px favicon frame or a square logo. Sites whose favicon
+  stops at 64px *and* whose logo is a wordmark (e.g. site-buildmill,
+  site-trifi) now list `favicon.ico` alone — correct, but a 256px frame in
+  `site/favicon.ico` would give them a sharp home-screen icon. Sites that
+  added `manifest.icons` overrides to work around this (site-chrismaus) can
+  keep them or drop them.
+
 ## 1.4.1
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Vertex CMS — lightweight, config-driven Vue 3 framework with theming, extensions, and SSG support",
   "license": "MIT",
   "type": "module",

package/scripts/generate-public-assets.js

@@ -1,5 +1,5 @@
 // scripts/generate-public-assets.js (run at build time)
-// Syncs favicon.ico, logo.png, and og-image.jpg for the site.
+// Syncs favicon.ico, favicon-256.png, logo.png, and og-image.jpg for the site.
 //
 // Reads from CMS_SITE_DIR env var (e.g. /path/to/my-site/site/).
 // Assets are read from {CMS_SITE_DIR}/assets/, config from
@@ -9,6 +9,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { extractIcoFrame } from './lib/ico.mjs';
 
 // dotenv is optional — without it, config comes from the process environment.
 try {
@@ -22,10 +23,11 @@ try {
 // command still installs cleanly. This command DOES need them — fail loudly
 // with the fix instead of a bare module-not-found stack.
 let createCanvas;
+let loadImage;
 let registerFont;
 let pngToIco;
 try {
-  ({ createCanvas, registerFont } = await import('canvas'));
+  ({ createCanvas, loadImage, registerFont } = await import('canvas'));
   ({ default: pngToIco } = await import('png-to-ico'));
 } catch (err) {
   console.error('❌ cms-generate-public-assets requires the optional dependencies `canvas` and `png-to-ico`.');
@@ -53,6 +55,10 @@ if (!CMS_SITE_DIR || !fs.existsSync(CMS_SITE_DIR)) {
 
 const PUBLIC_DIR = path.join(path.dirname(CMS_SITE_DIR), 'public');
 
+// Must match the primary icon in src/utils/webAppManifest.js.
+const MANIFEST_ICON_SIZE = 256;
+const MANIFEST_ICON_FILE = `favicon-${MANIFEST_ICON_SIZE}.png`;
+
 function resolveSiteAssetFile(relativePaths = []) {
   for (const rel of relativePaths) {
     if (!rel) continue;
@@ -339,6 +345,57 @@ function loadSiteTitle() {
   return '';
 }
 
+// The Web App Manifest names /favicon-256.png as its primary icon
+// (src/utils/webAppManifest.js). When the site ships its own favicon, build
+// that file from the site's own art: the favicon's 256px frame first (the
+// designed icon, no resampling), else a square logo scaled to fit. A
+// wordmark is never squashed into a square and a small favicon is never
+// upscaled. With neither, any stale copy is removed — the plugin lists only
+// icons that exist in public/, so the manifest falls back to favicon.ico.
+async function writeManifestIconFromSiteArt({ icoBuffer, logoSource, iconPath }) {
+  const frame = extractIcoFrame(icoBuffer, MANIFEST_ICON_SIZE);
+  if (frame?.format === 'png') {
+    fs.writeFileSync(iconPath, frame.data);
+    console.log(`✅ Wrote ${iconPath} from the favicon's ${MANIFEST_ICON_SIZE}px frame`);
+    return;
+  }
+  if (frame?.format === 'rgba') {
+    const canvas = createCanvas(frame.width, frame.height);
+    const ctx = canvas.getContext('2d');
+    const imageData = ctx.createImageData(frame.width, frame.height);
+    imageData.data.set(frame.rgba);
+    ctx.putImageData(imageData, 0, 0);
+    fs.writeFileSync(iconPath, canvas.toBuffer('image/png'));
+    console.log(`✅ Wrote ${iconPath} from the favicon's ${MANIFEST_ICON_SIZE}px frame`);
+    return;
+  }
+
+  if (logoSource) {
+    try {
+      const logo = await loadImage(logoSource);
+      if (logo.width === logo.height) {
+        const canvas = createCanvas(MANIFEST_ICON_SIZE, MANIFEST_ICON_SIZE);
+        const ctx = canvas.getContext('2d');
+        ctx.quality = 'best';
+        ctx.drawImage(logo, 0, 0, MANIFEST_ICON_SIZE, MANIFEST_ICON_SIZE);
+        fs.writeFileSync(iconPath, canvas.toBuffer('image/png'));
+        console.log(`✅ Wrote ${iconPath} from the ${logo.width}px square logo`);
+        return;
+      }
+      console.log(`   Logo is ${logo.width}x${logo.height}, not square — not used as the manifest icon`);
+    } catch (err) {
+      console.warn(`⚠️  Could not read logo ${logoSource} for the manifest icon`, err);
+    }
+  }
+
+  fs.rmSync(iconPath, { force: true });
+  console.warn(
+    `⚠️  No ${MANIFEST_ICON_SIZE}px manifest icon: favicon.ico has no ${MANIFEST_ICON_SIZE}px frame and there is no square logo.`
+    + ` manifest.json will list favicon.ico only. Add a ${MANIFEST_ICON_SIZE}px frame to site/favicon.ico`
+    + ' or a square site/assets/img/logo.png to give installs a sharp icon.',
+  );
+}
+
 async function generateFavicon() {
   const siteTitle = loadSiteTitle() || 'X';
   const letter = siteTitle.charAt(0).toUpperCase();
@@ -409,34 +466,31 @@ async function generateFavicon() {
     }
   }
 
+  const iconPath = path.join(publicDir, MANIFEST_ICON_FILE);
+
   const providedFavicon = resolveSiteAssetFile(['favicon.ico']);
   if (providedFavicon) {
     fs.copyFileSync(providedFavicon, icoPath);
     console.log(`✅ Found existing favicon; copied from ${providedFavicon}`);
+    await writeManifestIconFromSiteArt({ icoBuffer: fs.readFileSync(providedFavicon), logoSource, iconPath });
     return;
   }
 
   console.log(`Generating favicon.ico using letter "${letter}" from site "${siteTitle}"`);
 
-  const sizes = [256, 128, 64, 48, 32, 16];
+  const sizes = [MANIFEST_ICON_SIZE, 128, 64, 48, 32, 16];
   const pngBuffers = sizes.map((s) => renderLetterPng(letter, s, { bg, fg }));
 
-  const pngPath = path.join(publicDir, 'favicon-256.png');
-  fs.writeFileSync(pngPath, pngBuffers[0]);
+  // The 256px glyph doubles as the manifest's primary icon, so it stays.
+  fs.writeFileSync(iconPath, pngBuffers[0]);
 
   const ico = await pngToIco(pngBuffers);
   fs.writeFileSync(icoPath, ico);
 
-  try {
-    fs.unlinkSync(pngPath);
-    console.log(`🗑️  Removed temporary file ${pngPath}`);
-  } catch (err) {
-    console.warn(`⚠️  Could not remove temporary PNG: ${pngPath}`, err);
-  }
-
   console.log(`✅ Created favicon.ico using letter "${letter}" from site "${siteTitle}"`);
   console.log(`   Colors bg=${bg} fg=${fg}`);
   console.log(`   Wrote: ${icoPath}`);
+  console.log(`   Wrote: ${iconPath}`);
 }
 
 generateFavicon().catch((err) => {

package/scripts/lib/ico.mjs

@@ -0,0 +1,116 @@
+// Minimal .ico reader for cms-generate-public-assets.
+//
+// The script needs one thing from a site-provided favicon.ico: its 256px
+// frame, to publish as the Web App Manifest's /favicon-256.png. canvas can't
+// load .ico at all, so this lists the frames and decodes the 32-bit BMP ones
+// (what most encoders write); PNG-embedded frames are returned as-is.
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function isPng(data) {
+  return data.length >= 24 && data.subarray(0, 8).equals(PNG_SIGNATURE);
+}
+
+/**
+ * List a .ico's frames. Dimensions come from the frame itself (PNG IHDR or
+ * BMP header), not the directory entry, whose single byte can't say 256+.
+ * Returns [] for anything that isn't a well-formed icon file.
+ */
+export function readIcoFrames(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 6) return [];
+  if (buf.readUInt16LE(0) !== 0 || buf.readUInt16LE(2) !== 1) return [];
+  const count = buf.readUInt16LE(4);
+  const frames = [];
+  for (let i = 0; i < count; i++) {
+    const entry = 6 + 16 * i;
+    if (entry + 16 > buf.length) break;
+    const size = buf.readUInt32LE(entry + 8);
+    const offset = buf.readUInt32LE(entry + 12);
+    if (!size || offset + size > buf.length) continue;
+    const data = buf.subarray(offset, offset + size);
+    if (isPng(data)) {
+      frames.push({ format: 'png', width: data.readUInt32BE(16), height: data.readUInt32BE(20), data });
+    } else if (data.length >= 40) {
+      // BMP frames store the XOR image and the AND mask stacked, so the
+      // header height is double the icon's.
+      frames.push({
+        format: 'bmp',
+        width: data.readInt32LE(4),
+        height: Math.abs(data.readInt32LE(8)) / 2,
+        data,
+      });
+    }
+  }
+  return frames;
+}
+
+/**
+ * Decode a 32bpp uncompressed BMP icon frame to straight RGBA. Returns null
+ * for any other depth or compression — those are rare enough in practice
+ * that the caller falls back to another source rather than decoding them.
+ */
+export function decodeIcoBmp(data) {
+  if (!data || data.length < 40) return null;
+  const headerSize = data.readUInt32LE(0);
+  const width = data.readInt32LE(4);
+  const rawHeight = data.readInt32LE(8);
+  const bpp = data.readUInt16LE(14);
+  const compression = data.readUInt32LE(16);
+  if (bpp !== 32 || compression !== 0 || width <= 0 || rawHeight === 0) return null;
+
+  const height = Math.abs(rawHeight) / 2;
+  const bottomUp = rawHeight > 0;
+  const xorStride = width * 4;
+  const andStride = Math.ceil(width / 32) * 4;
+  const andStart = headerSize + xorStride * height;
+  if (!Number.isInteger(height) || andStart > data.length) return null;
+  const hasAndMask = andStart + andStride * height <= data.length;
+
+  const rgba = new Uint8ClampedArray(width * height * 4);
+  let usesAlpha = false;
+  for (let y = 0; y < height; y++) {
+    const row = bottomUp ? height - 1 - y : y;
+    for (let x = 0; x < width; x++) {
+      const s = headerSize + row * xorStride + x * 4;
+      const d = (y * width + x) * 4;
+      rgba[d] = data[s + 2];
+      rgba[d + 1] = data[s + 1];
+      rgba[d + 2] = data[s];
+      rgba[d + 3] = data[s + 3];
+      if (data[s + 3]) usesAlpha = true;
+    }
+  }
+
+  // Older encoders leave the alpha byte at 0 and carry transparency in the
+  // 1-bit AND mask alone; reading the zeros literally would blank the icon.
+  if (!usesAlpha) {
+    for (let y = 0; y < height; y++) {
+      const row = bottomUp ? height - 1 - y : y;
+      for (let x = 0; x < width; x++) {
+        const masked = hasAndMask
+          && (data[andStart + row * andStride + (x >> 3)] >> (7 - (x & 7))) & 1;
+        rgba[(y * width + x) * 4 + 3] = masked ? 0 : 255;
+      }
+    }
+  }
+
+  return { width, height, rgba };
+}
+
+/**
+ * The icon's square frame at exactly `size` px, ready to write:
+ *   { format: 'png', data }            — a PNG frame, byte-for-byte
+ *   { format: 'rgba', width, height, rgba } — a decoded BMP frame
+ * or null when the icon has no usable frame at that size (upscaling a
+ * 64px favicon would only publish a blurry icon under a 256px label).
+ */
+export function extractIcoFrame(buf, size) {
+  const frames = readIcoFrames(buf).filter((f) => f.width === size && f.height === size);
+  const png = frames.find((f) => f.format === 'png');
+  if (png) return { format: 'png', data: png.data };
+  for (const frame of frames) {
+    const decoded = decodeIcoBmp(frame.data);
+    if (decoded) return { format: 'rgba', ...decoded };
+  }
+  return null;
+}

package/src/utils/webAppManifest.js

@@ -18,7 +18,11 @@
  *   "manifest.icons[0].type": "image/png"
  *
  * Defaults are derived from existing site config and the icons that
- * cms-generate-public-assets writes (favicon-256.png + favicon.ico).
+ * cms-generate-public-assets writes (favicon-256.png + favicon.ico). Pass
+ * `iconExists` to drop default icons whose file isn't there: the script
+ * can't always produce favicon-256.png (a site-provided favicon with no
+ * 256px frame and no square logo), and a listed icon that 404s is worse
+ * than an unlisted one. Author-supplied `manifest.icons` are never filtered.
  */
 
 const DEFAULT_DISPLAY = 'standalone';
@@ -45,7 +49,7 @@ function defaultIcons() {
   ];
 }
 
-export function buildWebAppManifest(siteConfig) {
+export function buildWebAppManifest(siteConfig, { iconExists } = {}) {
   const site = (siteConfig && siteConfig.site) || {};
   const m = (site.manifest && typeof site.manifest === 'object') ? site.manifest : {};
 
@@ -66,7 +70,9 @@ export function buildWebAppManifest(siteConfig) {
         .filter((icon) => icon && typeof icon === 'object' && typeof icon.src === 'string')
         .map((icon) => ({ ...icon }))
     : null;
-  const icons = customIcons && customIcons.length ? customIcons : defaultIcons();
+  const icons = customIcons && customIcons.length
+    ? customIcons
+    : defaultIcons().filter((icon) => typeof iconExists !== 'function' || iconExists(icon.src));
 
   const manifest = {
     name,

package/vite-plugin.js

@@ -584,7 +584,11 @@ export default function cmsPlugin(options = {}) {
     // Web App Manifest. The template emits <link rel="manifest"> on every
     // page; browsers use this to enable Add-to-Home-Screen + control
     // splash colors when the site is launched from a homescreen icon.
-    const manifest = buildWebAppManifest(siteConfig);
+    // Default icons are listed only if generate-public-assets (which runs
+    // before the build) actually put them in public/.
+    const manifest = buildWebAppManifest(siteConfig, {
+      iconExists: (src) => fs.existsSync(path.join(sitePublicDir, src.replace(/^\/+/, ''))),
+    });
     writeFileIfChanged(
       path.join(sitePublicDir, 'manifest.json'),
       JSON.stringify(manifest, null, 2) + '\n',