@techninja/clearstack 0.3.43 → 0.3.45

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-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

@@ -53,10 +53,12 @@ export function loadTokens(projectDir) {
     const full = resolve(projectDir, p);
     if (!existsSync(full)) continue;
     const css = readFileSync(full, 'utf-8');
+    /** @type {Record<string, string>} */
     const vars = {};
     for (const m of css.matchAll(/--([^:]+):\s*([^;]+)/g)) vars[m[1].trim()] = m[2].trim();
     if (Object.keys(vars).length) return vars;
   }
+  /** @type {Record<string, string>} */
   return {};
 }
 
@@ -67,15 +69,15 @@ export function loadTokens(projectDir) {
  * @param {{ tokens?: Record<string, string>, logo?: string, siteName?: string }} site
  */
 export function buildContext(config, itemData, site) {
-  const t = site.tokens || {};
+  const t = /** @type {Record<string, string>} */ (site.tokens || {});
   const title = interpolate(config.title, itemData);
   const desc = config.description ? interpolate(config.description, itemData) : '';
   const image = config.image ? interpolate(config.image, itemData) : '';
   const baseUrl = itemData.store?.url || '';
   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 item = /** @type {Record<string, unknown>} */ (itemData.item || {});
+  const emoji = /** @type {string} */ (item.emoji || itemData.emoji || '');
+  const tags = /** @type {string[]} */ (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 || '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.3.43",
+  "version": "0.3.45",
   "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>