@koehler8/cms 1.0.0-beta.27 → 1.0.0-beta.29

package/package.json

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

package/scripts/image-variants/reconcile.js

@@ -64,10 +64,18 @@ export async function reconcileVariantCache({
       continue;
     }
 
+    // Source is "cached" if the manifest knows it, mtime hasn't changed,
+    // config hasn't changed, AND every variant the previous run wrote is
+    // still on disk. We check `previous.variants` (what was actually
+    // generated) rather than `job.outputs` (everything the planner asked
+    // for) so tiny-source sites — where the renderer skipped over-large
+    // widths to avoid Vite content-dedup — aren't perpetually re-rendered
+    // on each build.
+    const previousVariants = previous?.variants || [];
     const allCached = !configChanged
       && previous
       && previous.mtimeMs >= sourceMtime
-      && job.outputs.every((o) => fs.existsSync(path.join(cacheDir, o.cacheRelPath)));
+      && previousVariants.every((v) => fs.existsSync(path.join(cacheDir, v)));
 
     if (allCached) {
       plannedRenders.push({ job, sourceMtime, render: false });
@@ -87,12 +95,43 @@ export async function reconcileVariantCache({
     sharp = mod.default;
   }
 
+  // Per-source: filter outputs to widths the source can actually fulfill.
+  // Sharp's `withoutEnlargement: true` clamps oversize requests to the
+  // source dimensions, producing content-identical files for every width
+  // greater than the source. Vite content-hashes those files identically
+  // and emits ONE physical asset under one of the names — but assetUrlMap
+  // still has URL keys for every width, so requests for the deduped
+  // higher-width URLs 404.
+  //
+  // Fix: only generate variants for widths < source.width. Plus, always
+  // generate at exactly source.width (for crisp 1× display) by remapping
+  // any single oversize width down to source.width if no smaller variant
+  // would otherwise exist. The pipeline's natural fallback to the bare
+  // `img/{name}.{ext}` URL (which exists because the original is in the
+  // flat dir) covers tiny sources where no variant width fits.
+  const filteredOutputsByJob = new Map();
+  for (const { job } of plannedRenders) {
+    let sourceWidth = Number.MAX_SAFE_INTEGER;
+    if (sharp) {
+      try {
+        const meta = await sharp(job.sourcePath).metadata();
+        if (meta && Number.isFinite(meta.width)) sourceWidth = meta.width;
+      } catch {
+        // If metadata read fails, fall through and render everything —
+        // the failure is benign (just the dedup risk we're trying to avoid).
+      }
+    }
+    const kept = job.outputs.filter((o) => o.width <= sourceWidth);
+    filteredOutputsByJob.set(job.sourceKey, kept);
+  }
+
   for (const { job, sourceMtime, render } of plannedRenders) {
     if (!render) {
-      skipped += job.outputs.length;
+      skipped += (filteredOutputsByJob.get(job.sourceKey) || job.outputs).length;
       continue;
     }
-    for (const output of job.outputs) {
+    const outputs = filteredOutputsByJob.get(job.sourceKey) || job.outputs;
+    for (const output of outputs) {
       const outPath = path.join(cacheDir, output.cacheRelPath);
       try {
         await renderOutput(sharp, job.sourcePath, { ...output, outPath }, currentConfig);
@@ -104,15 +143,32 @@ export async function reconcileVariantCache({
     void sourceMtime;
   }
 
+  // Evict any cached variants that the source can no longer fulfill
+  // (e.g. someone replaced a 4000px source with a 200px one — the
+  // 1280/1920/2560 outputs from the previous run are now stale).
+  for (const { job, render } of plannedRenders) {
+    if (!render) continue;
+    const kept = new Set((filteredOutputsByJob.get(job.sourceKey) || job.outputs).map((o) => o.cacheRelPath));
+    for (const o of job.outputs) {
+      if (kept.has(o.cacheRelPath)) continue;
+      const stalePath = path.join(cacheDir, o.cacheRelPath);
+      if (fs.existsSync(stalePath)) {
+        await fs.promises.rm(stalePath, { force: true });
+        evicted += 1;
+      }
+    }
+  }
+
   const newManifest = {
     version: MANIFEST_VERSION,
     config: currentConfig,
     sources: {},
   };
   for (const { job, sourceMtime } of plannedRenders) {
+    const outputs = filteredOutputsByJob.get(job.sourceKey) || job.outputs;
     newManifest.sources[job.sourceKey] = {
       mtimeMs: sourceMtime,
-      variants: job.outputs.map((o) => o.cacheRelPath),
+      variants: outputs.map((o) => o.cacheRelPath),
     };
   }
   writeManifest(manifestPath, newManifest);

package/src/components/Hero.vue

@@ -273,10 +273,19 @@ function getHeaderOffset() {
 .promo-surface {
   position: relative;
   min-height: var(--promo-surface-min-height, calc(100vh + 75px));
-  background: var(
+  background-color: var(
     --promo-surface-bg,
     var(--hero-surface-bg, var(--theme-body-background, #060212))
   );
+  /* Two background-image declarations form a CSS-cascade fallback chain.
+     The first sets a basic url(); the second, if the browser parses
+     image-set() (and the type() argument), overrides with format
+     negotiation. Browsers that can't parse image-set fall back to the
+     url() above. Custom properties are populated by usePromoBackgroundStyles
+     via Vue's :style object binding — see that composable for why this
+     pattern is needed instead of a single background-image string. */
+  background-image: var(--promo-bg-fallback);
+  background-image: var(--promo-bg-set, var(--promo-bg-fallback));
   background-repeat: no-repeat;
   background-size: cover;
   background-position: center;

package/src/composables/usePromoBackgroundStyles.js

@@ -23,14 +23,34 @@ function selectLargestEntry(srcset = '') {
 }
 
 /**
- * Build a CSS background-image declaration that respects the neon backdrop toggle
- * and reuses the responsive image metadata returned by `useResponsiveImage`.
+ * Build a hero-background style binding that pairs a `url()` fallback with an
+ * `image-set()` upgrade. Returns an OBJECT with two CSS custom properties.
+ *
+ * Why an object with custom properties instead of a single `background-image`
+ * string: Vue 3's `:style` parses a string into a normalized object keyed by
+ * property name. A string with two `background-image` declarations
+ * (`background-image: url(...); background-image: image-set(...)`) collapses
+ * to a single entry — only the last value survives. This loses the
+ * progressive-enhancement chain that's the whole point of pairing a `url()`
+ * fallback with an `image-set()` upgrade. By emitting two custom properties,
+ * Vue keeps both, and the consuming CSS rule chains them as two real
+ * declarations of `background-image` so browsers walk the cascade naturally.
+ *
+ * Consumed by Hero.vue's `.promo-surface` rule, which declares:
+ *
+ *   background-image: var(--promo-bg-fallback);
+ *   background-image: var(--promo-bg-set, var(--promo-bg-fallback));
+ *
+ * Browsers that can parse `image-set()` (and its `type()` argument) use the
+ * second declaration; browsers that can't fall through to the first.
+ *
  * @param {object} options
  * @param {{
  *   sources: import('vue').MaybeRefOrGetter<Array<{ type: string, srcset: string }>>,
  *   fallbackSrc: import('vue').MaybeRefOrGetter<string>,
  *   fallbackFormat: import('vue').MaybeRefOrGetter<string>
  * }} options.imageSet
+ * @returns {import('vue').ComputedRef<Record<string, string> | null>}
  */
 export function usePromoBackgroundStyles({ imageSet }) {
   return computed(() => {
@@ -38,30 +58,26 @@ export function usePromoBackgroundStyles({ imageSet }) {
     const fallbackFormat = (unref(imageSet?.fallbackFormat) || 'jpg').toLowerCase();
     const sources = unref(imageSet?.sources) || [];
 
-    const formatEntries = [];
+    if (!fallbackSrc) return null;
 
+    const formatEntries = [];
     sources.forEach((source) => {
       const largest = selectLargestEntry(source?.srcset);
       if (largest) {
         formatEntries.push(`url("${largest}") type("${source?.type}") 1x`);
       }
     });
-
     if (fallbackSrc) {
       const fallbackMime = fallbackFormat === 'jpg' ? 'jpeg' : fallbackFormat;
       formatEntries.push(`url("${fallbackSrc}") type("image/${fallbackMime}") 1x`);
     }
 
-    const cssImageSet = formatEntries.length ? `image-set(${formatEntries.join(', ')})` : '';
-    let style = '';
-
-    if (fallbackSrc) {
-      style += `background-image: url("${fallbackSrc}");`;
-    }
-    if (cssImageSet) {
-      style += `background-image: ${cssImageSet};`;
+    const result = {
+      '--promo-bg-fallback': `url("${fallbackSrc}")`,
+    };
+    if (formatEntries.length) {
+      result['--promo-bg-set'] = `image-set(${formatEntries.join(', ')})`;
     }
-
-    return style;
+    return result;
   });
 }