@techninja/clearstack 0.3.42 → 0.3.44

package/bin/cli.js

@@ -68,7 +68,13 @@ async function run(action) {
     report(process.cwd(), { json: !!flags.json });
   } else if (action === 'build') {
     const sub = args.find((a) => a !== 'build' && !a.startsWith('-'));
-    if (sub === 'og-images' || sub === 'images') {
+    if (sub === 'sitemap') {
+      const { buildSitemap } = await import('../lib/build-sitemap.js');
+      buildSitemap({ projectDir: process.cwd(), outDir: flags.out || 'dist', baseUrl: flags.url || '' });
+    } else if (sub === 'modulepreload' || sub === 'preload') {
+      const { buildModulePreload } = await import('../lib/build-modulepreload.js');
+      buildModulePreload({ projectDir: process.cwd(), outDir: flags.out || 'dist' });
+    } else if (sub === 'og-images' || sub === 'images') {
       const mod = await import('../lib/build-og-images.js');
       const common = { projectDir: process.cwd(), outDir: flags.out || 'dist', logo: flags.logo || '', siteName: flags.site || '' };
       if (flags.slug) await mod.buildOneOGImage({ ...common, slug: flags.slug });
@@ -80,7 +86,11 @@ async function run(action) {
         outDir: flags.out || 'dist',
         baseUrl: flags.url || '',
       });
+      const { buildSitemap } = await import('../lib/build-sitemap.js');
+      buildSitemap({ projectDir: process.cwd(), outDir: flags.out || 'dist', baseUrl: flags.url || '' });
       if (sub === 'all') {
+        const { buildModulePreload } = await import('../lib/build-modulepreload.js');
+        buildModulePreload({ projectDir: process.cwd(), outDir: flags.out || 'dist' });
         const { buildOGImages } = await import('../lib/build-og-images.js');
         await buildOGImages({
           projectDir: process.cwd(),

package/lib/build-modulepreload.js

@@ -0,0 +1,105 @@
+/**
+ * Module preload builder — statically crawls ES module imports and injects
+ * <link rel="modulepreload"> tags into index.html so the browser fetches all
+ * modules in parallel instead of chaining waterfall requests.
+ * @module lib/build-modulepreload
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, relative, extname } from 'node:path';
+
+/**
+ * @param {string} srcDir - The src/ directory to crawl
+ * @param {string} entryFile - Relative path to entry (e.g. 'router/index.js')
+ * @param {string[]} ignoreDirs - Dirs to skip (e.g. ['vendor', 'deps'])
+ * @returns {string[]} Ordered list of module paths (entry last)
+ */
+export function crawlModules(srcDir, entryFile, ignoreDirs = ['vendor', 'deps']) {
+  const visited = new Set();
+  const order = [];
+
+  /**
+   *
+   */
+  function crawl(relPath) {
+    if (visited.has(relPath)) return;
+    visited.add(relPath);
+    if (ignoreDirs.some((d) => relPath.includes(`/${d}/`) || relPath.startsWith(`${d}/`))) return;
+
+    const absPath = resolve(srcDir, relPath);
+    if (!existsSync(absPath) || extname(absPath) !== '.js') return;
+
+    const src = readFileSync(absPath, 'utf-8');
+    const importRe = /(?:^|\n)\s*import\s[^'"]*['"]([^'"]+)['"]/g;
+    let m;
+    while ((m = importRe.exec(src)) !== null) {
+      const spec = m[1];
+      if (spec.startsWith('#')) {
+        // Import map alias — resolve via known prefixes
+        const mapped = resolveAlias(spec, relPath);
+        if (mapped) crawl(mapped);
+      } else if (spec.startsWith('./') || spec.startsWith('../')) {
+        const abs = resolve(dirname(resolve(srcDir, relPath)), spec);
+        const rel = relative(srcDir, abs.endsWith('.js') ? abs : abs + '.js');
+        crawl(rel);
+      }
+      // Skip bare specifiers (vendor/hybrids handled separately)
+    }
+    order.push(relPath);
+  }
+
+  crawl(entryFile);
+  return order;
+}
+
+/** Resolve #alias/ import map specifiers to relative paths. */
+function resolveAlias(spec, fromFile) {
+  const aliases = {
+    '#store/': 'store/',
+    '#utils/': 'utils/',
+    '#atoms/': 'components/atoms/',
+    '#molecules/': 'components/molecules/',
+    '#organisms/': 'components/organisms/',
+    '#templates/': 'components/templates/',
+    '#pages/': 'pages/',
+  };
+  for (const [prefix, dir] of Object.entries(aliases)) {
+    if (spec.startsWith(prefix)) return dir + spec.slice(prefix.length);
+  }
+  return null;
+}
+
+/**
+ * Inject modulepreload tags into index.html.
+ * @param {{ projectDir: string, srcDir?: string, outDir?: string, entry?: string, ignore?: string[] }} opts
+ * @returns {{ modules: number }}
+ */
+export function buildModulePreload(opts) {
+  const {
+    projectDir,
+    srcDir = resolve(projectDir, 'src'),
+    outDir = resolve(projectDir, 'dist'),
+    entry = 'router/index.js',
+    ignore = ['vendor', 'deps'],
+  } = opts;
+
+  const indexPath = resolve(outDir, 'index.html');
+  if (!existsSync(indexPath)) {
+    console.log('⚠ dist/index.html not found — run build first');
+    return { modules: 0 };
+  }
+
+  const modules = crawlModules(srcDir, entry, ignore);
+  const tags = modules.map((m) => `  <link rel="modulepreload" href="/${m}">`).join('\n');
+
+  let html = readFileSync(indexPath, 'utf-8');
+  if (html.includes('rel="modulepreload"')) {
+    // Remove existing preload tags before re-injecting
+    html = html.replace(/\s*<link rel="modulepreload"[^>]*>/g, '');
+  }
+  html = html.replace('</head>', `${tags}\n</head>`);
+  writeFileSync(indexPath, html);
+
+  console.log(`✅ Modulepreload: ${modules.length} modules → dist/index.html`);
+  return { modules: modules.length };
+}

package/lib/build-og-images.js

@@ -17,6 +17,8 @@ import { resolveTemplate, renderTemplate, buildContext, loadTokens, WIDTH, HEIGH
  * @property {string} [logo] - Path or URL to logo
  * @property {string} [siteName] - Site name for badge
  * @property {Record<string, unknown>} [context] - Extra interpolation data
+ * @property {(slug: string) => boolean} [filter] - Only render matching slugs
+ * @property {(slug: string, n: number, total: number) => void} [onProgress]
  */
 
 /**
@@ -25,7 +27,7 @@ import { resolveTemplate, renderTemplate, buildContext, loadTokens, WIDTH, HEIGH
  * @returns {Promise<{ images: number, routes: number }>}
  */
 export async function buildOGImages(opts) {
-  const { projectDir, outDir = 'dist', logo, siteName, context = {} } = opts;
+  const { projectDir, outDir = 'dist', logo, siteName, context = {}, filter, onProgress } = opts;
   const routes = loadRoutes(projectDir);
   if (!routes) {
     console.log('⚠ No routes config found. Create clearstack.routes.json');
@@ -37,7 +39,8 @@ export async function buildOGImages(opts) {
   const start = performance.now();
 
   const { chromium } = await import('playwright');
-  const browser = await chromium.launch();
+  const browser = await chromium.launch({ executablePath: process.env.PLAYWRIGHT_EXECUTABLE_PATH });
+  console.log('  Browser ready, rendering...');
   const page = await browser.newPage({ viewport: { width: WIDTH, height: HEIGHT } });
   const out = resolve(projectDir, outDir);
   let images = 0;
@@ -47,6 +50,7 @@ export async function buildOGImages(opts) {
     const isDynamic = pattern.includes(':');
 
     if (!isDynamic) {
+      if (filter) continue;
       const data = { app: { name: siteName }, ...context };
       const ctx = buildContext(config, data, site);
       await screenshot(page, renderTemplate(template, ctx, projectDir), out, pattern);
@@ -57,11 +61,13 @@ export async function buildOGImages(opts) {
       for (const item of items) {
         const slug = item.slug || item.id || item.sku || item[paramName];
         if (!slug) continue;
+        if (filter && !filter(String(slug))) continue;
         const path = pattern.replace(`:${paramName}`, String(slug));
         const data = { [paramName]: item, item, app: { name: siteName }, ...context };
         const ctx = buildContext(config, data, site);
         await screenshot(page, renderTemplate(template, ctx, projectDir), out, path);
         images++;
+        if (onProgress) onProgress(String(slug), images, -1);
       }
     }
   }
@@ -85,7 +91,7 @@ export async function buildOneOGImage(opts) {
   const tokens = loadTokens(projectDir);
   const site = { tokens, logo, siteName };
   const { chromium } = await import('playwright');
-  const browser = await chromium.launch();
+  const browser = await chromium.launch({ executablePath: process.env.PLAYWRIGHT_EXECUTABLE_PATH });
   const page = await browser.newPage({ viewport: { width: WIDTH, height: HEIGHT } });
   const out = resolve(projectDir, outDir);
   let result = '';
@@ -113,7 +119,8 @@ export async function buildOneOGImage(opts) {
 
 /** Render HTML content and save screenshot to disk. */
 async function screenshot(page, html, outDir, routePath) {
-  await page.setContent(html, { waitUntil: 'networkidle' });
+  await page.setContent(html, { waitUntil: 'domcontentloaded' });
+  await page.waitForTimeout(html.includes('fonts.googleapis') ? 2500 : 800);
   const imgPath = routePath === '/'
     ? resolve(outDir, 'og-image.png')
     : resolve(outDir, routePath.slice(1) + '.png');

package/lib/build-sitemap.js

@@ -0,0 +1,101 @@
+/**
+ * Sitemap generator — builds sitemap.xml from clearstack.routes.json.
+ * Static routes get one URL each; dynamic routes iterate their data source.
+ * @module lib/build-sitemap
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadRoutes, resolveDataSource } from './build-og.js';
+import { interpolate } from './og-template.js';
+
+/** @param {string} s */
+const esc = (s) => s.replace(/&/g, '&').replace(/'/g, ''');
+
+/** Default priority by route type. */
+function defaultPriority(pattern) {
+  if (pattern === '/') return '1.0';
+  if (pattern.includes(':')) return '0.5';
+  return '0.7';
+}
+
+/** Default changefreq by route type. */
+function defaultChangefreq(pattern) {
+  if (pattern === '/') return 'daily';
+  if (pattern.includes(':')) return 'weekly';
+  return 'monthly';
+}
+
+/**
+ * @param {string} date - ISO date string or empty
+ * @returns {string}
+ */
+function fmtDate(date) {
+  if (!date) return '';
+  try { return new Date(date).toISOString().slice(0, 10); } catch { return ''; }
+}
+
+/**
+ * Build sitemap.xml from route config.
+ * @param {{ projectDir: string, outDir?: string, baseUrl: string, context?: Record<string, unknown> }} opts
+ * @returns {{ urls: number }}
+ */
+export function buildSitemap(opts) {
+  const { projectDir, outDir = 'dist', baseUrl, context = {} } = opts;
+  const routes = loadRoutes(projectDir);
+  if (!routes) {
+    console.log('⚠ No routes config found. Create clearstack.routes.json');
+    return { urls: 0 };
+  }
+
+  const urls = [];
+
+  for (const [pattern, config] of Object.entries(routes)) {
+    const sm = config.sitemap || {};
+    const priority = sm.priority ?? defaultPriority(pattern);
+    const changefreq = sm.changefreq ?? defaultChangefreq(pattern);
+    const isDynamic = pattern.includes(':');
+
+    if (!isDynamic) {
+      const lastmod = fmtDate(sm.lastmod || '');
+      urls.push(entry(`${baseUrl}${pattern}`, changefreq, String(priority), lastmod));
+    } else if (config.data) {
+      const items = resolveDataSource(config.data, projectDir);
+      const paramName = pattern.match(/:(\w+)/)?.[1] || 'id';
+      for (const item of items) {
+        const slug = item.slug || item.id || item.sku || item[paramName];
+        if (!slug) continue;
+        const path = pattern.replace(`:${paramName}`, String(slug));
+        const data = { [paramName]: item, item, ...context };
+        const resolvedPath = interpolate(path, data);
+        const lastmod = fmtDate(item.date || item.modified || item.created || '');
+        urls.push(entry(`${baseUrl}${resolvedPath}`, changefreq, String(priority), lastmod));
+      }
+    }
+  }
+
+  const xml = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ...urls,
+    '</urlset>',
+  ].join('\n');
+
+  const out = resolve(projectDir, outDir);
+  mkdirSync(out, { recursive: true });
+  writeFileSync(resolve(out, 'sitemap.xml'), xml);
+  console.log(`✅ Sitemap: ${urls.length} URLs → ${outDir}/sitemap.xml`);
+  return { urls: urls.length };
+}
+
+/** Build a single <url> entry. */
+function entry(loc, changefreq, priority, lastmod) {
+  return [
+    '  <url>',
+    `    <loc>${esc(loc)}</loc>`,
+    lastmod ? `    <lastmod>${lastmod}</lastmod>` : '',
+    `    <changefreq>${changefreq}</changefreq>`,
+    `    <priority>${priority}</priority>`,
+    '  </url>',
+  ].filter(Boolean).join('\n');
+}

package/lib/og-image-template.js

@@ -75,6 +75,14 @@ export function buildContext(config, itemData, site) {
   const resolvedImage = image && !image.startsWith('http') ? `${baseUrl}${image}` : image;
   const item = itemData.item || {};
   const emoji = item.emoji || itemData.emoji || '';
+  const tags = item.tags || itemData.tags || [];
+  const tagsHtml = tags.map((t) => `<div class="tag">#${t}</div>`).join('');
+  const postTitle = item.title || item.caption || item.name || '';
+  const logoSrc = item.logo?.wordmark || item.logo?.mark || '';
+  const itemLogoHtml = logoSrc ? `<img src="${logoSrc}" alt="${postTitle}">` : '';
+  const dateFormatted = item.date ? new Date(item.date).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }) : '';
+  const mediaUrl = resolvedImage || (item.files?.[0] ? `https://data.tn42.com/assets-media/${item.files[0]}` : '');
+  const isVideo = item.type === 'video' || (item.files?.[0] || '').endsWith('.mp4');
 
   return {
     ...itemData, ...item,
@@ -87,12 +95,18 @@ export function buildContext(config, itemData, site) {
     text: t['color-text'] || '#e2e8f0',
     textMuted: t['color-text-muted'] || '#a8b8cc',
     emoji, image: resolvedImage,
+    tagsHtml, postTitle, dateFormatted, mediaUrl,
+    logoHtml: itemLogoHtml,
+    noLogoMark: itemLogoHtml ? '' : '<div class="mark">42</div>',
+    mediaHtml: isVideo
+      ? `<video src="${mediaUrl}" autoplay muted playsinline style="position:absolute;inset:0;width:100%;height:100%;object-fit:cover"></video>`
+      : mediaUrl ? `<img src="${mediaUrl}" style="position:absolute;inset:0;width:100%;height:100%;object-fit:cover">` : '',
     variantsFormatted: formatNum(item.expected_variants),
     uniqueFormatted: formatNum(item.estimated_unique_variants),
     priceFormatted: item.price ? `$${(item.price / 100).toFixed(2)}` : '',
     imageHtml: resolvedImage ? `<img class="hero" src="${resolvedImage}">` : '',
     cardClass: resolvedImage ? 'card-with-image' : '',
-    logoHtml: site.logo ? `<img class="logo" src="${site.logo}">` : '',
+    siteLogo: site.logo ? `<img class="logo" src="${site.logo}">` : '',
     badgeHtml: site.siteName ? `<div class="badge">${site.siteName}</div>` : '',
     emojiHtml: emoji ? `<div class="emoji">${emoji}</div>` : '',
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.42",
+  "version": "0.3.44",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {

package/templates/shared/src/index.html

@@ -4,6 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{{name}}</title>
+    <!-- FOUC prevention — matches --color-bg in tokens.css -->
+    <style>html,body{background:#0f172a;color:#e2e8f0;margin:0}</style>
     <link rel="stylesheet" href="/styles/reset.css" />
     <link rel="stylesheet" href="/styles/tokens.css" />
     <link rel="stylesheet" href="/styles/shared.css" />
@@ -27,7 +29,22 @@
     </script>
   </head>
   <body>
+    <noscript>
+      <div style="font-family:system-ui;padding:2rem;max-width:40rem;margin:4rem auto;text-align:center">
+        <h1>JavaScript required</h1>
+        <p>{{name}} requires JavaScript to run. Please enable it in your browser settings.</p>
+      </div>
+    </noscript>
     <app-router></app-router>
     <script type="module" src="/router/index.js"></script>
+    <script>
+      // Global error boundary — catches unhandled promise rejections and JS errors
+      window.addEventListener('unhandledrejection', (e) => {
+        console.error('[app] Unhandled rejection:', e.reason);
+      });
+      window.addEventListener('error', (e) => {
+        console.error('[app] Uncaught error:', e.message, e.filename, e.lineno);
+      });
+    </script>
   </body>
 </html>