@koehler8/cms 1.4.0 → 1.4.2

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # 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
+
+- **The embedded config payload is now actually used on locale-prefixed routes.**
+  vite-ssg runs the setup fn *before* `app.use(router)`, so `router.currentRoute`
+  is still `START_LOCATION` (`'/'`, `params: {}`) there — identically on every
+  page. During SSG that was already handled, because vite-ssg hands the route
+  over on `ctx.routePath`. On the **client** it calls the setup fn with no
+  argument at all, so there was nothing to resolve and the code fell through to
+  `START_LOCATION`.
+
+  `loadSiteConfig` derives its cache key from `params.locale`, so the key came
+  out `'default'` on every client page while the SSG had stamped the real locale
+  on `siteConfigLocale`. On a locale-prefixed route the two never matched, so
+  `primeConfigSync` was skipped, `hydrateFromSyncCache` missed, and the client
+  discarded the payload it had just been served and awaited a full config load
+  **inside the setup fn, on the critical path, before mount** — the exact
+  regression the priming machinery exists to prevent.
+
+  Measured on a multi-locale site, same machine and build, only this patch
+  differing. First config chunk on a `/th/` piece page: **44 ms before**
+  (DOMContentLoaded 34 ms — on the critical path), **1364 ms after** (deferred
+  to `requestIdleCallback`, as designed). The load is *deferred, not removed*:
+  `trimConfigToPage` stamps `pagesPartial` on every page, so the idle reload
+  still runs.
+
+  ⚠️ A cross-environment comparison hides this completely. A production bundle
+  that needs ~1.4 s to download and execute shows its config chunks at ~1607 ms,
+  which *looks* deferred when it is in fact immediate. Only a same-environment
+  A/B separates the two.
+
+  **No action needed in a site.** Single-locale sites already stamped `default`
+  and primed correctly, so their behaviour is unchanged; multi-locale sites gain
+  the deferral.
+
 ## 1.4.0
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koehler8/cms",
-  "version": "1.4.0",
+  "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/main.js

@@ -8,6 +8,7 @@ import { routes, resolveHistory, applyRouterGuards } from './router/index.js';
 import { shouldEnableAnalytics, scheduleAnalyticsLoad, configureAnalyticsConsentMode } from './utils/cookieConsent.js';
 import { loadConfigData, primeConfigSync, trimConfigToPage, resolvePageIdForRoute } from './utils/loadConfig.js';
 import { applyInitialStateTrims } from './utils/initialStateTrim.js';
+import { currentRouteHref } from './utils/currentRoute.js';
 import { persistAttributionFromLocation } from './utils/trackingContext.js';
 import { applyThemeVariables } from './themes/themeManager.js';
 import { setActiveThemeKey } from './utils/themeColors.js';
@@ -136,19 +137,22 @@ export function createCmsApp() {
       };
 
       const extractCurrentRoute = () => {
-        // During SSG, vite-ssg passes the route being pre-rendered as a string
-        // on `ctx.routePath` and only pushes the router AFTER this setup fn runs
-        // — so `router.currentRoute` is still vue-router's START_LOCATION ('/')
-        // here, identically on every page. Resolve `routePath` through the router
-        // (a pure match, no navigation) to recover the real path + `params.locale`.
-        // Without this, `resolveCurrentPageId` sees '/' for every route, so the
-        // payload trim targets the wrong page — or, when '/' is ambiguous, none.
-        const routePath = ctx?.routePath;
-        if (typeof routePath === 'string' && routePath) {
+        // vite-ssg runs this setup fn BEFORE `app.use(router)`, so
+        // `router.currentRoute` is still vue-router's START_LOCATION ('/') here,
+        // identically on every page — during SSG *and* on the client. The href
+        // that IS authoritative differs per half (ctx.routePath vs the window's
+        // own location); currentRouteHref picks it, with the full account of why
+        // the client half is not optional. Resolve it through the router — a pure
+        // match, no navigation — to recover the real path + `params.locale`.
+        const href = currentRouteHref(
+          ctx,
+          typeof window !== 'undefined' ? window.location : null,
+        );
+        if (href) {
           try {
-            return router.resolve(routePath);
+            return router.resolve(href);
           } catch {
-            return { path: routePath, params: {} };
+            return { path: href, params: {} };
           }
         }
         if (ctx?.route) {

package/src/utils/currentRoute.js

@@ -0,0 +1,49 @@
+// Which href the app should resolve through the router to learn the route it is
+// actually on.
+//
+// Both halves of the lifecycle are blind to this in the same way, for the same
+// reason: vite-ssg runs the setup fn BEFORE `app.use(router)`, so
+// `router.currentRoute` is still vue-router's START_LOCATION ('/', `params: {}`)
+// — identically on every page.
+//
+//   - During SSG, vite-ssg hands the route being pre-rendered over as a string on
+//     `ctx.routePath`, so that is authoritative.
+//   - On the CLIENT it calls the setup fn with no argument at all: no
+//     `ctx.routePath`, no `ctx.route`. The only authoritative source left is the
+//     window's own location.
+//
+// Falling through to START_LOCATION on the client is not a cosmetic miss. The
+// config cache key is derived from `params.locale`, so it came out 'default' on
+// every page while the SSG had stamped the real locale on `siteConfigLocale`.
+// The two never matched on a locale-prefixed route, `primeConfigSync` was
+// skipped, and the client discarded the embedded payload and re-fetched the
+// whole config tree on the critical path — the exact regression the priming
+// machinery exists to prevent. Measured on sparkbang.com/th/<piece>/ before the
+// fix: 151 JS requests / 405 KB, 112 of them per-piece config chunks, while the
+// 17 KB embedded payload was parsed and thrown away.
+//
+// Pure and dependency-free so the fall-through can be pinned by a unit test;
+// `main.js` owns the router.resolve() call itself (a pure match, no navigation).
+//
+// Returns null when the caller should use `ctx.route` as-is, or when there is
+// nothing authoritative to resolve and START_LOCATION is genuinely all there is.
+
+/**
+ * @param {{routePath?: unknown, route?: unknown}|null|undefined} ctx
+ *   The vite-ssg setup context. `routePath` is set during SSG only.
+ * @param {{pathname?: unknown, search?: unknown}|null|undefined} location
+ *   `window.location` on the client; omit/null on the server.
+ * @returns {string|null} the href to resolve, or null to fall back.
+ */
+export function currentRouteHref(ctx, location) {
+  const routePath = ctx?.routePath;
+  if (typeof routePath === 'string' && routePath) return routePath;
+  // A context that already carries a resolved route needs no href at all.
+  if (ctx?.route) return null;
+  const pathname = location?.pathname;
+  if (typeof pathname === 'string' && pathname) {
+    const search = typeof location?.search === 'string' ? location.search : '';
+    return `${pathname}${search}`;
+  }
+  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',