mnfst-render 0.5.24 → 0.5.26

package/README.md

@@ -8,4 +8,4 @@ Static renderer for Manifest projects.
 npx mnfst-render --root .
 ```
 
-The command reads `manifest.json` and writes rendered pages to `manifest.prerender.output` (default `website`).
+The command reads `manifest.json` and writes rendered pages to `manifest.render.output` (default `website`).

package/manifest.render.mjs

@@ -9,6 +9,7 @@ import { createServer } from 'node:http';
 import { cpus } from 'node:os';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -735,7 +736,7 @@ function stripDataTailwindAttr(html) {
  * BEFORE the first paint — based on the user's `localStorage.theme` (their
  * saved preference) or `prefers-color-scheme` (their system preference).
  *
- * The colors plugin (`manifest.colors.js`) still runs later for reactivity
+ * The color plugin (`manifest.color.js`) still runs later for reactivity
  * (Alpine bindings, click handlers, system-preference change listener), but
  * the initial paint already has the correct class so there's no flash.
  */
@@ -768,18 +769,18 @@ function debakeThemeClass(html) {
   return out;
 }
 
-/** Manifest utilities plugin: <style id="utility-styles"> and <style id="utility-styles-critical"> */
+/** Manifest utilities plugin: <style id="manifest-styles"> and <style id="manifest-styles-critical"> */
 function extractUtilityStyleBlocks(html) {
   const blocks = [];
   let out = html.replace(
-    /<style[^>]*\bid=["']utility-styles-critical["'][^>]*>([\s\S]*?)<\/style>/gi,
+    /<style[^>]*\bid=["']manifest-styles-critical["'][^>]*>([\s\S]*?)<\/style>/gi,
     (_, css) => {
       const t = (css || '').trim();
       if (t) blocks.push({ kind: 'critical', css: t });
       return '';
     }
   );
-  out = out.replace(/<style[^>]*\bid=["']utility-styles["'][^>]*>([\s\S]*?)<\/style>/gi, (_, css) => {
+  out = out.replace(/<style[^>]*\bid=["']manifest-styles["'][^>]*>([\s\S]*?)<\/style>/gi, (_, css) => {
     const t = (css || '').trim();
     if (t) blocks.push({ kind: 'main', css: t });
     return '';
@@ -1745,16 +1746,100 @@ function resolveHeadXBindings(html, xData) {
 // .fallback.image), capture a 1200×630 PNG of the rendered page and use that as
 // the og:image / twitter:image.  Saved to <output>/og/<sanitized-path>.png.
 //
-// 1200×630 is the OpenGraph / Twitter / LinkedIn recommended dimension.  We set
-// the viewport before snapshotting so layouts intended for desktop render
-// correctly (mobile-first sites otherwise look misaligned in social previews).
-async function takeOgSnapshot(page, outputDir, pathSeg) {
+// 1200×630 is the OpenGraph / Twitter / LinkedIn recommended dimension.
+
+const sha = (s) => createHash('sha256').update(String(s)).digest('hex').slice(0, 16);
+
+/**
+ * Hash of the project-wide assets that affect every page's visual output
+ * (theme CSS, manifest config, root HTML shell).  Computed once per prerender
+ * run and folded into each route's snapshot-cache key so that touching any of
+ * these invalidates every cached OG image — a more correct behaviour than
+ * per-route source-mtime caching, which would miss shared-chrome changes.
+ *
+ * Files included are conventional Manifest project assets that influence
+ * layout/theme; missing files are recorded as the literal `missing` so the
+ * hash still differs from an installation that has the file present.
+ */
+function computeGlobalAssetSignature(rootDir) {
+  const candidates = [
+    'manifest.json',
+    'manifest.theme.css',
+    'manifest.utilities.css',
+    'index.html',
+  ];
+  const parts = candidates.map((rel) => {
+    const p = join(rootDir, rel);
+    try {
+      return `${rel}:${sha(readFileSync(p, 'utf8'))}`;
+    } catch {
+      return `${rel}:missing`;
+    }
+  });
+  return sha(parts.join('|'));
+}
+
+/**
+ * Snapshot the page at 1200×630 and write to <output>/og/<slug>.png.  Cache
+ * sidecar lives in <root>/.mnfst-cache/og/ — outside the output dir, which is
+ * wiped at the start of every prerender.  On cache hit, the cached PNG is
+ * copied into the output dir and the screenshot is skipped — saves ~0.2–0.5s
+ * per hit, which adds up across hundreds of routes × locales.  Hash inputs:
+ *   - globalAssetSignature (theme CSS / manifest config / root HTML)
+ *   - body outerHTML, normalised to strip non-visual volatile attributes
+ *   - html.className (theme variant: light/dark/etc.)
+ */
+async function takeOgSnapshot(page, outputDir, pathSeg, globalAssetSignature, cacheDir) {
   const fileSeg = pathSeg === '' || pathSeg === '__404__'
     ? 'index'
     : pathSeg.replace(/\//g, '-').replace(/[^a-zA-Z0-9_-]/g, '_');
   const ogDir = join(outputDir, 'og');
   try { mkdirSync(ogDir, { recursive: true }); } catch { /* exists */ }
   const filePath = join(ogDir, `${fileSeg}.png`);
+  // Cache locations — outside the output dir so they survive the per-run
+  // rmSync.  cacheDir is .mnfst-cache/og under the project root.
+  const cachePngPath = cacheDir ? join(cacheDir, `${fileSeg}.png`) : null;
+  const cacheHashPath = cacheDir ? join(cacheDir, `${fileSeg}.hash`) : null;
+
+  // Cache lookup: fingerprint the rendered DOM and check against the stored
+  // hash.  The fingerprint normalises away attribute values assigned in
+  // iteration order (data-hydrate-id, data-component-N) and randomly-generated
+  // CSS anchor-name positioning IDs.  Without normalisation the hash would
+  // never match across runs and the cache would always miss.
+  let contentHash = null;
+  try {
+    const fingerprint = await page.evaluate(() => {
+      const body = document.body?.outerHTML || '';
+      const htmlClass = document.documentElement?.className || '';
+      const normalised = body
+        .replace(/\sdata-hydrate-id="[^"]*"/g, '')
+        .replace(/\sdata-component="[^"]*"/g, '')
+        .replace(/\sdata-pre-rendered="[^"]*"/g, '')
+        .replace(/\sid="(?:tab-|code-)[^"]*"/g, '')
+        .replace(/\saria-controls="(?:code-)[^"]*"/g, '')
+        .replace(/\saria-labelledby="(?:tab-)[^"]*"/g, '')
+        // CSS anchor-positioning IDs (e.g. `--dropdown-zc7nofh3c`) are
+        // regenerated per run by the dropdown/popover system.
+        .replace(/--dropdown-[a-z0-9]+/g, '--dropdown-X')
+        .replace(/--popover-[a-z0-9]+/g, '--popover-X')
+        .replace(/--anchor-[a-z0-9]+/g, '--anchor-X');
+      return normalised + '\n@html:' + htmlClass;
+    });
+    contentHash = sha(`${globalAssetSignature || ''}|${fingerprint}`);
+    if (cachePngPath && existsSync(cachePngPath) && existsSync(cacheHashPath)) {
+      const stored = readFileSync(cacheHashPath, 'utf8').trim();
+      if (stored === contentHash) {
+        // Cache hit — copy the cached PNG into the output dir.  We still need
+        // a copy in /og/ so the served site has it; the cache just lets us
+        // skip the screenshot + PNG-encode work.
+        try {
+          cpSync(cachePngPath, filePath);
+          return `/og/${fileSeg}.png`;
+        } catch { /* copy failure — fall through to fresh snapshot */ }
+      }
+    }
+  } catch { /* hash failure is non-fatal — fall through to fresh snapshot */ }
+
   try {
     // Viewport stays at the page-creation default (1200×800).  Clipping a
     // 1200×630 region from the top gives the OG/Twitter card aspect ratio
@@ -1780,9 +1865,21 @@ async function takeOgSnapshot(page, outputDir, pathSeg) {
       const sz = statSync(filePath).size;
       if (sz < 15 * 1024) {
         unlinkSync(filePath);
+        // Drop the cache too so the next run doesn't trust it.
+        if (cachePngPath) { try { unlinkSync(cachePngPath); } catch { /* missing is fine */ } }
+        if (cacheHashPath) { try { unlinkSync(cacheHashPath); } catch { /* missing is fine */ } }
         return null;
       }
     } catch { /* stat failure is non-fatal */ }
+    // Populate the cache: copy the fresh PNG into the cache dir and write the
+    // content hash sidecar.  Hash failure earlier leaves contentHash null —
+    // in that case we don't cache (correct fallback: prefer to re-snapshot
+    // than to claim a stale cache is valid).
+    if (cacheDir && contentHash) {
+      try { mkdirSync(cacheDir, { recursive: true }); } catch { /* exists */ }
+      try { cpSync(filePath, cachePngPath); } catch { /* ignore */ }
+      try { writeFileSync(cacheHashPath, contentHash, 'utf8'); } catch { /* ignore */ }
+    }
     return `/og/${fileSeg}.png`;
   } catch (e) {
     // Failures here are non-fatal — fall back to whatever other og:image source
@@ -2856,6 +2953,19 @@ async function runPrerender(config) {
 
   process.stdout.write(`Prerendering ${pathTotal} path(s) (${puppeteerTotal} via Puppeteer, ${localeVariantPaths.length} via substitution)...\n`);
 
+  // Asset-wide fingerprint used as a cache-invalidator for OG snapshots:
+  // changes to theme CSS, manifest config, or the root index.html mean every
+  // route's visual chrome has changed, so the snapshot cache must drop.  Per-
+  // route content hashes (in takeOgSnapshot) catch route-specific changes.
+  // The cache lives at <root>/.mnfst-cache/og/ — survives the output-dir
+  // rmSync that fires at the start of every prerender.
+  const globalAssetSig = config.seo?.imageSnapshots
+    ? computeGlobalAssetSignature(config.root)
+    : '';
+  const ogCacheDir = config.seo?.imageSnapshots
+    ? join(config.root, '.mnfst-cache', 'og')
+    : null;
+
   function pushDebug(row) {
     if (!config.debugPrerender) return;
     debugRows.push(row);
@@ -3111,7 +3221,7 @@ async function runPrerender(config) {
           || !!config.seo.meta?.fallback?.image
           || await page.evaluate(() => !!document.head.querySelector('meta[property="og:image"]'));
         if (!ogImageHandled) {
-          earlySnapshotUrl = await takeOgSnapshot(page, config.output, is404 ? '__404__' : pathSeg);
+          earlySnapshotUrl = await takeOgSnapshot(page, config.output, is404 ? '__404__' : pathSeg, globalAssetSig, ogCacheDir);
         }
       }
 
@@ -3328,14 +3438,14 @@ async function runPrerender(config) {
         // Interactive Manifest-registered directives that attach click/hover/
         // observer state at runtime and therefore need the live Alpine scope.
         const INTERACTIVE_DIRECTIVES = new Set([
-          'x-colors', 'x-dropdown', 'x-tooltip', 'x-tab', 'x-tabpanel',
+          'x-color', 'x-dropdown', 'x-tooltip', 'x-tab', 'x-tabpanel',
           'x-toast', 'x-carousel', 'x-resize', 'x-anchors', 'x-model',
           'x-files', 'x-data-files',
         ]);
         // Runtime-only Alpine magics whose values change after the prerender
         // snapshot (e.g. via media query, route change, auth state).  Bindings
         // referencing these must re-evaluate in the live page.
-        const RUNTIME_MAGIC_RX = /(?<!['"])\$(colors|locale|url|auth|search|query|toast)\b/;
+        const RUNTIME_MAGIC_RX = /(?<!['"])\$(color|locale|url|auth|search|query|toast)\b/;
 
         const isDiffBindingAttr = (name) =>
           name === ':class' || name === 'x-bind:class' ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mnfst-render",
-  "version": "0.5.24",
+  "version": "0.5.26",
   "description": "Render Manifest sites to static HTML for SEO",
   "type": "module",
   "bin": {