chore: dev-middleware error logging, styleguide modernization, snapshot script hardening

zephyrie · claude · zephyrie · commit 45b7269e9420 · 2026-06-10T21:50:14.000-07:00
The md-twins and llms-txt dev middlewares log conversion failures
instead of failing silently. STYLEGUIDE's page-structure example and
checklist now show the BaseLayout pattern instead of retired SSI
includes. visual-snapshot.js validates its arguments and cleans up
the server/browser on failure.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/docs/STYLEGUIDE.md b/docs/STYLEGUIDE.md
@@ -103,25 +103,20 @@ Always use this above section titles (`text-brand-teal` on light backgrounds; `t
 ## Layout
 
 ### Page Structure
-```html
-<!DOCTYPE html>
-<html lang="en" class="scroll-smooth">
-<!-- Page-specific meta tags -->
-<title>MONAI - Page Title</title>
-<meta name="description" content="...">
-<!-- OG tags, twitter tags, canonical -->
-
-<!-- #include file="components/head.html" -->
-
-<body class="flex flex-col min-h-screen bg-white">
-    <!-- #include file="components/header.html" -->
-    <main class="flex-grow pt-16">
-        <!-- Page content sections here -->
-        <!-- #include file="components/footer.html" -->
-    </main>
-    <!-- #include file="components/scripts.html" -->
-</body>
-</html>
+```astro
+---
+import BaseLayout from '../layouts/BaseLayout.astro';
+const frontmatter = {
+  title: 'MONAI - Page Title',
+  description: '...',
+  canonical: 'https://project-monai.github.io/<name>.html',
+  // optional: audience, schemaType, metaRefresh
+};
+---
+<BaseLayout {...frontmatter}>
+  <!-- Page sections here. BaseLayout provides <head> (SEO, JSON-LD, GA4),
+       Header, Footer, and the shared scripts. -->
+</BaseLayout>
 ```
 
 ### Container
@@ -530,17 +525,13 @@ For displaying code snippets (e.g., install commands, code examples):
 When creating a new page:
 
 1. Use `class="scroll-smooth"` on `<html>` (NOT inline style)
-2. Include all 4 component files via SSI:
-   - `<!-- #include file="components/head.html" -->`
-   - `<!-- #include file="components/header.html" -->`
-   - `<!-- #include file="components/footer.html" -->`
-   - `<!-- #include file="components/scripts.html" -->`
-3. Add complete meta tags: title, description, og:title, og:description, og:url, twitter:title, twitter:description, canonical
+2. Wrap the page in `BaseLayout` (it renders head, Header, Footer, and shared scripts).
+3. Fill the `frontmatter` const: title, description, canonical (BaseHead derives OG/Twitter/canonical/markdown-twin tags from it)
 4. Start with a light hero (`bg-gradient-to-br from-white via-brand-light/40 to-white`, dark text; see DESIGN.md, dark heroes are legacy)
 5. Use `reveal` classes for scroll-reveal animations, sparingly
 6. Alternate `bg-white` and `bg-gray-50` for content sections
 7. Test responsive layout at mobile (375px), tablet (768px), desktop (1280px)
-8. Run `npm run build` to verify SSI includes resolve
+8. Run `npm run build` and `npm test` to verify the page and LLM artifacts generate
 
 ---
 
diff --git a/scripts/visual-snapshot.js b/scripts/visual-snapshot.js
@@ -8,11 +8,32 @@ const ROOT = process.argv[2];
 const OUT  = process.argv[3];
 const PORT = 4321;
 
+if (!ROOT || !OUT) {
+  console.error('Usage: node scripts/visual-snapshot.js <ROOT> <OUT>');
+  console.error('  ROOT: directory of built HTML to serve (e.g. ./dist)');
+  console.error('  OUT:  directory to write screenshots into');
+  process.exit(1);
+}
+
 (async () => {
+  let server;
+  let browser;
+  try {
+    await main();
+  } catch (e) {
+    console.error('visual-snapshot failed:', e.message);
+    console.error(e.stack);
+    process.exitCode = 1;
+  } finally {
+    if (browser) await browser.close().catch(() => {});
+    if (server) server.close();
+  }
+
+  async function main() {
   fs.mkdirSync(OUT, { recursive: true });
-  const server = http.createServer((req, res) => handler(req, res, { public: ROOT }));
+  server = http.createServer((req, res) => handler(req, res, { public: ROOT }));
   await new Promise(r => server.listen(PORT, r));
-  const browser = await puppeteer.launch({
+  browser = await puppeteer.launch({
     args: ['--no-sandbox', '--disable-setuid-sandbox'],
   });
   const page = await browser.newPage();
@@ -39,6 +60,5 @@ const PORT = 4321;
       console.warn(`Skip ${h}: ${e.message}`);
     }
   }
-  await browser.close();
-  server.close();
+  }
 })();
diff --git a/src/integrations/llms-txt.ts b/src/integrations/llms-txt.ts
@@ -67,7 +67,8 @@ export default function llmsTxt(): AstroIntegration {
             res.end(
               `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`,
             );
-          } catch {
+          } catch (err) {
+            console.error(`[llms-txt] dev synthesis failed for ${url}:`, err);
             next();
           }
         });
diff --git a/src/integrations/md-twins.ts b/src/integrations/md-twins.ts
@@ -128,7 +128,8 @@ export default function mdTwins(): AstroIntegration {
             const md = htmlToMarkdownTwin(html, frontmatterFromHtml(html, rel));
             res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
             res.end(md);
-          } catch {
+          } catch (err) {
+            console.error(`[md-twins] dev twin conversion failed for ${url}:`, err);
             next();
           }
         });
