@techninja/clearstack 0.3.47 → 0.3.48

package/lib/build-modulepreload.js

@@ -2,21 +2,33 @@
  * 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.
+ *
+ * Importmap safety: modules that directly import bare specifiers are excluded
+ * from preload (the browser can race importmap registration when parsing
+ * preloaded modules). Bare specifier targets (vendor files) are preloaded
+ * first so they are in the module cache before any dependent module runs.
  * @module lib/build-modulepreload
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve, dirname, relative, extname } from 'node:path';
 
+/** Extract the importmap object from an HTML string, or return {}. */
+function parseImportMap(html) {
+  const m = html.match(/<script type="importmap">([\s\S]*?)<\/script>/);
+  try { return m ? JSON.parse(m[1]).imports ?? {} : {}; } catch { return {}; }
+}
+
 /**
- * @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)
+ * @param {string} srcDir
+ * @param {string} entryFile
+ * @param {string[]} ignoreDirs
+ * @returns {{ order: string[], hasBareImport: Set<string> }}
  */
 export function crawlModules(srcDir, entryFile, ignoreDirs = ['vendor', 'deps']) {
   const visited = new Set();
   const order = [];
+  const hasBareImport = new Set();
 
   /**
    *
@@ -35,25 +47,28 @@ export function crawlModules(srcDir, entryFile, ignoreDirs = ['vendor', 'deps'])
     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);
+        const mapped = resolveAlias(spec);
         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);
+      } else {
+        // Bare specifier — mark this module as unsafe to preload
+        hasBareImport.add(relPath);
       }
-      // Skip bare specifiers (vendor/hybrids handled separately)
     }
     order.push(relPath);
   }
 
   crawl(entryFile);
-  return order;
+  return { order, hasBareImport };
 }
 
-/** Resolve #alias/ import map specifiers to relative paths. */
-function resolveAlias(spec, fromFile) {
+/**
+ *
+ */
+function resolveAlias(spec) {
   const aliases = {
     '#store/': 'store/',
     '#utils/': 'utils/',
@@ -71,7 +86,9 @@ function resolveAlias(spec, fromFile) {
 
 /**
  * Inject modulepreload tags into index.html.
- * @param {{ projectDir: string, srcDir?: string, outDir?: string, entry?: string, ignore?: string[] }} opts
+ * Vendor files (importmap targets) are preloaded first, then app modules
+ * that contain no bare specifier imports.
+ * @param {{ projectDir: string, srcDir?: string, outDir?: string, entry?: string, ignore?: string[], hashSuffix?: string }} opts
  * @returns {{ modules: number }}
  */
 export function buildModulePreload(opts) {
@@ -81,6 +98,7 @@ export function buildModulePreload(opts) {
     outDir = resolve(projectDir, 'dist'),
     entry = 'router/index.js',
     ignore = ['vendor', 'deps'],
+    hashSuffix = '',
   } = opts;
 
   const indexPath = resolve(outDir, 'index.html');
@@ -89,17 +107,32 @@ export function buildModulePreload(opts) {
     return { modules: 0 };
   }
 
-  const modules = crawlModules(srcDir, entry, ignore);
-  const tags = modules.map((m) => `  <link rel="modulepreload" href="/${m}">`).join('\n');
+  const html0 = readFileSync(indexPath, 'utf-8');
+  const importMap = parseImportMap(html0);
+
+  const { order, hasBareImport } = crawlModules(srcDir, entry, ignore);
+
+  // Vendor files from importmap — preload these first (no bare imports inside them)
+  const vendorPaths = [...new Set(Object.values(importMap))]
+    .filter((v) => v.startsWith('/') && v.endsWith('.js'));
+
+  // App modules safe to preload — exclude any that directly import a bare specifier
+  const appPaths = order.filter((m) => !hasBareImport.has(m));
+
+  const v = hashSuffix ? `?v=${hashSuffix}` : '';
+  const tags = [
+    ...vendorPaths.map((p) => `  <link rel="modulepreload" href="${p}${v}">`),
+    ...appPaths.map((m) => `  <link rel="modulepreload" href="/${m}${v}">`),
+  ].join('\n');
 
-  let html = readFileSync(indexPath, 'utf-8');
+  let html = html0;
   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 };
+  const skipped = hasBareImport.size;
+  console.log(`✅ Modulepreload: ${vendorPaths.length} vendor + ${appPaths.length} app modules → dist/index.html (${skipped} skipped — bare imports)`);
+  return { modules: vendorPaths.length + appPaths.length };
 }

package/package.json

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