resuml 1.5.2 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resuml",
-  "version": "1.5.2",
+  "version": "1.7.0",
   "description": "Generate JSON resumes from YAML with theme support",
   "type": "module",
   "main": "./dist/api.js",
@@ -28,6 +28,8 @@
     "dev:builder": "node scripts/dev-server.js",
     "prepublishOnly": "npm run generate:types && npm run build:lib",
     "generate:types": "node scripts/generate-types.cjs",
+    "bundle:themes": "node scripts/bundle-themes.js",
+    "bundle:themes:all": "node scripts/bundle-themes.js --all",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src api --ext .ts,.tsx",

package/scripts/bundle-themes.js

@@ -1,12 +1,17 @@
 /**
  * Theme Bundling Script
  *
- * Discovers jsonresume-theme packages from npm, installs them,
- * and bundles each into a browser-compatible ES module.
+ * Bundles jsonresume-theme packages for the browser with:
+ *   - Per-theme fs shim with embedded assets (CSS, templates, etc.)
+ *   - CSS extraction (separate .css files)
+ *   - Build-time snapshots (pre-rendered HTML for instant preview)
+ *   - Node.js built-in shims (buffer, stream, util, events, os, etc.)
  *
  * Output:
- *   docs/themes/{name}.js       — bundled theme module
- *   docs/themes/manifest.json   — theme metadata registry
+ *   docs/themes/{name}.js           — bundled render module
+ *   docs/themes/{name}.css          — extracted CSS (if any)
+ *   docs/themes/{name}.snapshot.html— pre-rendered HTML with sample data
+ *   docs/themes/manifest.json       — theme metadata registry
  *
  * Usage:
  *   node scripts/bundle-themes.js              # Bundle popular themes
@@ -19,8 +24,10 @@ import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync } from 'fs';
+import { createRequire } from 'module';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
 const THEMES_DIR = resolve(__dirname, '../docs/themes');
 
 // Popular themes that are known to work in the browser
@@ -43,45 +50,113 @@ const POPULAR_THEMES = [
   'compact',
 ];
 
-async function discoverThemes() {
-  const themes = [];
-  let from = 0;
-  const size = 250;
-
-  console.log('🔍 Discovering themes from npm...');
-
-  // npm search API has pagination, fetch up to 1000
-  for (let page = 0; page < 4; page++) {
-    const url = `https://registry.npmjs.org/-/v1/search?text=jsonresume-theme&size=${size}&from=${from}`;
-    const res = await fetch(url);
-    if (!res.ok) break;
-    const data = await res.json();
-
-    for (const pkg of data.objects) {
-      const name = pkg.package.name;
-      if (!name.startsWith('jsonresume-theme-')) continue;
-      const shortName = name.replace('jsonresume-theme-', '');
-
-      // Skip themes with 0 downloads or very old
-      if (pkg.score?.detail?.popularity === 0) continue;
-
-      themes.push({
-        name: shortName,
-        packageName: name,
-        description: pkg.package.description || '',
-        version: pkg.package.version,
-      });
-    }
+// File extensions to embed in the fs shim
+const TEXT_EXTS = new Set([
+  'css', 'hbs', 'html', 'json', 'txt', 'handlebars', 'mustache', 'template',
+  'pug', 'jade', 'ejs', 'svg', 'less', 'scss',
+]);
+
+// Sample resume for generating snapshots
+const SAMPLE_RESUME = {
+  basics: {
+    name: 'Jane Smith',
+    label: 'Senior Software Engineer',
+    image: '',
+    email: 'jane@example.com',
+    phone: '+1-555-987-6543',
+    url: 'https://janesmith.dev',
+    summary: 'Full-stack engineer with 8+ years of experience building scalable web applications. Passionate about clean architecture, performance optimization, and mentoring teams.',
+    location: { address: '', postalCode: '', city: 'San Francisco', countryCode: 'US', region: 'California' },
+    profiles: [
+      { network: 'LinkedIn', username: 'janesmith', url: 'https://linkedin.com/in/janesmith' },
+      { network: 'GitHub', username: 'janesmith', url: 'https://github.com/janesmith' },
+    ],
+  },
+  work: [
+    {
+      name: 'Tech Corp',
+      position: 'Senior Software Engineer',
+      url: 'https://techcorp.com',
+      startDate: '2020-03-01',
+      summary: 'Lead engineer for the platform team, owning core API infrastructure.',
+      highlights: [
+        'Reduced API latency by 45% through caching and query optimization',
+        'Designed microservices architecture serving 2M daily requests',
+        'Mentored 4 junior engineers through technical growth plans',
+      ],
+    },
+    {
+      name: 'StartupXYZ',
+      position: 'Full Stack Developer',
+      startDate: '2017-06-01',
+      endDate: '2020-02-28',
+      summary: 'Built customer-facing web applications from prototype to production.',
+      highlights: [
+        'Built real-time dashboard used by 15,000+ daily active users',
+        'Implemented CI/CD pipeline reducing deploy time from 2 hours to 8 minutes',
+      ],
+    },
+  ],
+  education: [
+    {
+      institution: 'University of Technology',
+      area: 'Computer Science',
+      studyType: 'Bachelor of Science',
+      startDate: '2013-09-01',
+      endDate: '2017-05-15',
+      score: '3.8',
+    },
+  ],
+  skills: [
+    { name: 'Languages', level: 'Expert', keywords: ['TypeScript', 'JavaScript', 'Python', 'Go'] },
+    { name: 'Frontend', level: 'Expert', keywords: ['React', 'Next.js', 'HTML/CSS', 'Tailwind'] },
+    { name: 'Backend & Cloud', level: 'Advanced', keywords: ['Node.js', 'PostgreSQL', 'AWS', 'Docker'] },
+  ],
+  projects: [
+    {
+      name: 'Open Source CLI Tool',
+      description: 'Developer productivity tool with 2,000+ GitHub stars',
+      url: 'https://github.com/janesmith/cli-tool',
+      startDate: '2022-01-01',
+      highlights: ['Published to npm with 5,000+ weekly downloads'],
+    },
+  ],
+  volunteer: [],
+  awards: [],
+  certificates: [],
+  publications: [],
+  languages: [],
+  interests: [],
+  references: [],
+};
 
-    if (data.objects.length < size) break;
-    from += size;
+/**
+ * Pad resume with safe defaults so themes don't crash on missing fields.
+ * Ported from api/_lib/themeInstaller.ts.
+ */
+function padResume(r) {
+  const basics = r.basics ?? {};
+  const location = basics.location ?? {};
+  const safe = {
+    ...r,
+    basics: {
+      name: '', label: '', image: '', email: '', phone: '', url: '', summary: '',
+      ...basics,
+      location: { address: '', postalCode: '', city: '', countryCode: '', region: '', ...location },
+    },
+  };
+  const arraySections = ['work','volunteer','education','awards','certificates','publications','skills','languages','interests','references','projects'];
+  for (const key of arraySections) {
+    safe[key] = Array.isArray(safe[key]) ? safe[key] : [];
   }
-
-  console.log(`   Found ${themes.length} themes`);
-  return themes;
+  const safeBasics = safe.basics;
+  safeBasics.profiles = Array.isArray(safeBasics.profiles) ? safeBasics.profiles : [];
+  return safe;
 }
 
-/** Recursively collect text files from a theme directory for embedding in the fs shim. */
+// ── Theme file collection ────────────────────────────────────────────
+
+/** Recursively collect text files from a theme directory for the fs shim. */
 function collectThemeFiles(themeDir) {
   const files = {};
   const dirs = {};
@@ -102,9 +177,9 @@ function collectThemeFiles(themeDir) {
         walk(full, rel);
       } else {
         const ext = (entry.name.split('.').pop() || '').toLowerCase();
-        if (['css', 'hbs', 'html', 'json', 'txt', 'handlebars', 'mustache'].includes(ext)) {
+        if (TEXT_EXTS.has(ext)) {
           try { files[rel] = readFileSync(full, 'utf-8'); }
-          catch { /* skip unreadable */ }
+          catch { /* skip */ }
         }
       }
     }
@@ -115,53 +190,168 @@ function collectThemeFiles(themeDir) {
   return { files, dirs };
 }
 
-/** Generate an fs shim that embeds the theme's files so readFileSync/readdirSync work at runtime. */
+/** Generate an fs shim that embeds the theme's files. */
 function generateThemeFsShim(themeFiles) {
   const { files, dirs } = themeFiles;
-  return `
-const __files = ${JSON.stringify(files)};
-const __dirs = ${JSON.stringify(dirs)};
-
-function matchFile(path) {
-  const clean = path.replace(/\\/+/g, '/').replace(/^\\/+/, '');
-  if (__files[clean] !== undefined) return __files[clean];
-  for (const key of Object.keys(__files)) {
-    if (clean.endsWith('/' + key) || clean.endsWith(key)) return __files[key];
+  const lines = [
+    `var __files = ${JSON.stringify(files)};`,
+    `var __dirs = ${JSON.stringify(dirs)};`,
+    '',
+    'function normalizePath(p) {',
+    '  return String(p).replace(/[\\\\]+/g, "/").replace(/^\\/+/, "");',
+    '}',
+    '',
+    'function matchFile(p) {',
+    '  var clean = normalizePath(p);',
+    '  if (__files[clean] !== undefined) return __files[clean];',
+    '  var keys = Object.keys(__files);',
+    '  for (var i = 0; i < keys.length; i++) {',
+    '    if (clean.endsWith("/" + keys[i]) || clean === keys[i]) return __files[keys[i]];',
+    '  }',
+    '  return undefined;',
+    '}',
+    '',
+    'function matchDir(p) {',
+    '  var clean = normalizePath(p);',
+    '  if (__dirs[clean] !== undefined) return __dirs[clean];',
+    '  var keys = Object.keys(__dirs);',
+    '  for (var i = 0; i < keys.length; i++) {',
+    '    if (clean.endsWith("/" + keys[i]) || clean === keys[i]) return __dirs[keys[i]];',
+    '  }',
+    '  return undefined;',
+    '}',
+    '',
+    'export var readFileSync = function(p, encoding) {',
+    '  var r = matchFile(p);',
+    '  if (r !== undefined) return r;',
+    '  return typeof encoding === "string" ? "" : "";',
+    '};',
+    '',
+    'export var readdirSync = function(p, opts) {',
+    '  var r = matchDir(p);',
+    '  if (r === undefined) r = [];',
+    '  if (opts && opts.withFileTypes) {',
+    '    return r.map(function(name) {',
+    '      var childPath = normalizePath(p) + "/" + name;',
+    '      var isDir = matchDir(childPath) !== undefined;',
+    '      return { name: name, isFile: function() { return !isDir; }, isDirectory: function() { return isDir; } };',
+    '    });',
+    '  }',
+    '  return r;',
+    '};',
+    '',
+    'export var existsSync = function(p) { return matchFile(p) !== undefined || matchDir(p) !== undefined; };',
+    'export var writeFileSync = function() {};',
+    'export var mkdirSync = function() {};',
+    'export var statSync = function() { return { isFile: function() { return true; }, isDirectory: function() { return false; }, size: 0, mtime: new Date() }; };',
+    'export var lstatSync = statSync;',
+    'export var unlinkSync = function() {};',
+    'export var rmdirSync = function() {};',
+    'export var createReadStream = function() { return { pipe: function(d) { return d; }, on: function() { return this; } }; };',
+    'export var createWriteStream = function() { return { write: function() {}, end: function() {}, on: function() { return this; } }; };',
+    'export default { readFileSync: readFileSync, readdirSync: readdirSync, existsSync: existsSync, writeFileSync: writeFileSync, mkdirSync: mkdirSync, statSync: statSync, lstatSync: lstatSync, unlinkSync: unlinkSync, rmdirSync: rmdirSync, createReadStream: createReadStream, createWriteStream: createWriteStream };',
+  ];
+  return lines.join('\n');
+}
+
+// ── CSS extraction ───────────────────────────────────────────────────
+
+/** Extract <style> blocks from rendered HTML and write to a .css file. */
+function extractCss(html, shortName) {
+  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi;
+  let css = '';
+  let match;
+  while ((match = styleRegex.exec(html)) !== null) {
+    css += match[1] + '\n';
+  }
+  if (css.trim()) {
+    writeFileSync(resolve(THEMES_DIR, `${shortName}.css`), css.trim());
+    return true;
   }
-  return undefined;
+  return false;
 }
 
-function matchDir(path) {
-  const clean = path.replace(/\\/+/g, '/').replace(/^\\/+/, '');
-  if (__dirs[clean] !== undefined) return __dirs[clean];
-  for (const key of Object.keys(__dirs)) {
-    if (clean.endsWith('/' + key) || clean.endsWith(key)) return __dirs[key];
+// ── Snapshot generation ──────────────────────────────────────────────
+
+/** Render a theme with sample data in Node.js and save as snapshot. */
+function generateSnapshot(shortName, packageName) {
+  try {
+    // Clear require cache to get a fresh instance
+    const pkgPath = require.resolve(packageName);
+    delete require.cache[pkgPath];
+
+    const theme = require(packageName);
+    const render = theme.render || (theme.default && theme.default.render);
+    if (typeof render !== 'function') return null;
+
+    const paddedResume = padResume(SAMPLE_RESUME);
+    const result = render(paddedResume);
+    // render() may return a string or a Promise
+    if (typeof result === 'string') {
+      writeFileSync(resolve(THEMES_DIR, `${shortName}.snapshot.html`), result);
+      extractCss(result, shortName);
+      return result;
+    }
+    if (result && typeof result.then === 'function') {
+      return result.then((html) => {
+        if (typeof html === 'string') {
+          writeFileSync(resolve(THEMES_DIR, `${shortName}.snapshot.html`), html);
+          extractCss(html, shortName);
+          return html;
+        }
+        return null;
+      }).catch(() => null);
+    }
+    return null;
+  } catch (e) {
+    console.log(`    (snapshot failed: ${e.message})`);
+    return null;
   }
-  return undefined;
 }
 
-export const readFileSync = (path, encoding) => {
-  const r = matchFile(path);
-  return r !== undefined ? r : '';
-};
+// ── npm discovery ────────────────────────────────────────────────────
 
-export const readdirSync = (path) => {
-  const r = matchDir(path);
-  return r !== undefined ? r : [];
-};
+async function discoverThemes() {
+  const themes = [];
+  let from = 0;
+  const size = 250;
 
-export const existsSync = (path) => {
-  return matchFile(path) !== undefined || matchDir(path) !== undefined;
-};
+  console.log('🔍 Discovering themes from npm...');
 
-export default { readFileSync, readdirSync, existsSync };
-`;
+  for (let page = 0; page < 4; page++) {
+    const url = `https://registry.npmjs.org/-/v1/search?text=jsonresume-theme&size=${size}&from=${from}`;
+    const res = await fetch(url);
+    if (!res.ok) break;
+    const data = await res.json();
+
+    for (const pkg of data.objects) {
+      const name = pkg.package.name;
+      if (!name.startsWith('jsonresume-theme-')) continue;
+      const shortName = name.replace('jsonresume-theme-', '');
+      if (pkg.score?.detail?.popularity === 0) continue;
+
+      themes.push({
+        name: shortName,
+        packageName: name,
+        description: pkg.package.description || '',
+        version: pkg.package.version,
+      });
+    }
+
+    if (data.objects.length < size) break;
+    from += size;
+  }
+
+  console.log(`   Found ${themes.length} themes`);
+  return themes;
 }
 
+// ── esbuild bundling ─────────────────────────────────────────────────
+
 async function bundleTheme(shortName, packageName, shimsDir) {
-  // Generate a theme-specific fs shim with embedded file contents so that
-  // readFileSync / readdirSync return real CSS, templates, and partials at runtime.
   const themeDir = resolve(__dirname, `../node_modules/${packageName}`);
+
+  // Generate per-theme fs shim with embedded files
   const themeFiles = collectThemeFiles(themeDir);
   writeFileSync(resolve(shimsDir, 'fs.js'), generateThemeFsShim(themeFiles));
 
@@ -183,44 +373,264 @@ async function bundleTheme(shortName, packageName, shimsDir) {
       format: 'esm',
       target: 'es2022',
       platform: 'browser',
-      // Use 'require' condition so packages like underscore/lodash resolve to their
-      // CJS/UMD builds (which export a callable function) instead of their ESM builds
-      // (which export a namespace object that breaks _(collection) call syntax).
       conditions: ['browser', 'require', 'default'],
-      // Prefer the CJS 'main' field over the ESM 'module' field for packages
-      // that don't use the exports map (older packages).
       mainFields: ['browser', 'main'],
       outfile: resolve(THEMES_DIR, `${shortName}.js`),
       define: {
         'process.env.NODE_ENV': '"production"',
+        'process.env.LANG': '""',
         'global': 'globalThis',
         '__dirname': '"/"',
         '__filename': '"/index.js"',
         'process.browser': 'true',
         'process.platform': '"browser"',
-        'process.version': '"v18.0.0"',
+        'process.version': '"v20.0.0"',
+        'process.versions': '{}',
+        'process.stdout': 'false',
+        'process.stderr': 'false',
       },
-      // Polyfill Node.js built-ins as no-ops for browser
       alias: {
-        'path': resolve(__dirname, 'shims/path.js'),
-        'fs': resolve(__dirname, 'shims/fs.js'),
-        'url': resolve(__dirname, 'shims/url.js'),
-        'node:url': resolve(__dirname, 'shims/url.js'),
-        'node:crypto': resolve(__dirname, 'shims/crypto.js'),
-        'assert': resolve(__dirname, 'shims/assert.js'),
+        'path': resolve(shimsDir, 'path.js'),
+        'fs': resolve(shimsDir, 'fs.js'),
+        'url': resolve(shimsDir, 'url.js'),
+        'assert': resolve(shimsDir, 'assert.js'),
+        'buffer': resolve(shimsDir, 'buffer.js'),
+        'stream': resolve(shimsDir, 'stream.js'),
+        'util': resolve(shimsDir, 'util.js'),
+        'events': resolve(shimsDir, 'events.js'),
+        'os': resolve(shimsDir, 'os.js'),
+        // node: prefixed variants
+        'node:fs': resolve(shimsDir, 'fs.js'),
+        'node:path': resolve(shimsDir, 'path.js'),
+        'node:url': resolve(shimsDir, 'url.js'),
+        'node:crypto': resolve(shimsDir, 'crypto.js'),
+        'node:buffer': resolve(shimsDir, 'buffer.js'),
+        'node:stream': resolve(shimsDir, 'stream.js'),
+        'node:util': resolve(shimsDir, 'util.js'),
+        'node:events': resolve(shimsDir, 'events.js'),
+        'node:os': resolve(shimsDir, 'os.js'),
+        'node:assert': resolve(shimsDir, 'assert.js'),
       },
       logLevel: 'silent',
     });
 
-    // Clean up entry file
     execSync(`rm -f "${entryFile}"`);
     return true;
   } catch (e) {
+    console.log(`    (bundle error: ${e.message})`);
     execSync(`rm -f "${entryFile}"`);
     return false;
   }
 }
 
+// ── Shim file writers ────────────────────────────────────────────────
+
+function writeShims(shimsDir) {
+  writeFileSync(resolve(shimsDir, 'path.js'), [
+    'export var join = function() { return [].slice.call(arguments).join("/"); };',
+    'export var resolve = function() { return [].slice.call(arguments).join("/"); };',
+    'export var dirname = function(p) { return p.split("/").slice(0, -1).join("/"); };',
+    'export var basename = function(p, ext) { var b = p.split("/").pop() || ""; return ext && b.endsWith(ext) ? b.slice(0, -ext.length) : b; };',
+    'export var extname = function(p) { var m = p.match(/\\.[^.]+$/); return m ? m[0] : ""; };',
+    'export var sep = "/";',
+    'export var isAbsolute = function(p) { return p.charAt(0) === "/"; };',
+    'export var normalize = function(p) { return p; };',
+    'export var relative = function(from, to) { return to; };',
+    'export var parse = function(p) { return { root: "", dir: dirname(p), base: basename(p), ext: extname(p), name: basename(p, extname(p)) }; };',
+    'export default { join: join, resolve: resolve, dirname: dirname, basename: basename, extname: extname, sep: sep, isAbsolute: isAbsolute, normalize: normalize, relative: relative, parse: parse };',
+  ].join('\n'));
+
+  // fs shim is generated per-theme in bundleTheme()
+
+  writeFileSync(resolve(shimsDir, 'url.js'), [
+    'export var URL = globalThis.URL;',
+    'export var URLSearchParams = globalThis.URLSearchParams;',
+    'export var fileURLToPath = function(u) { return u.replace(/^file:\\/\\//, ""); };',
+    'export var pathToFileURL = function(p) { return new globalThis.URL("file://" + p); };',
+    'export var format = function(u) { return typeof u === "string" ? u : u.href; };',
+    'export var parse = function(u) { return new globalThis.URL(u); };',
+    'export default { URL: URL, URLSearchParams: URLSearchParams, fileURLToPath: fileURLToPath, pathToFileURL: pathToFileURL, format: format, parse: parse };',
+  ].join('\n'));
+
+  writeFileSync(resolve(shimsDir, 'crypto.js'), [
+    'export var createHash = function() { return { update: function() { return this; }, digest: function() { return ""; } }; };',
+    'export var randomBytes = function(n) { return new Uint8Array(n); };',
+    'export var createHmac = function() { return { update: function() { return this; }, digest: function() { return ""; } }; };',
+    'export default { createHash: createHash, randomBytes: randomBytes, createHmac: createHmac };',
+  ].join('\n'));
+
+  writeFileSync(resolve(shimsDir, 'assert.js'), [
+    'var assert = function(v, msg) { if (!v) throw new Error(msg || "Assertion failed"); };',
+    'assert.ok = assert;',
+    'assert.strictEqual = function(a, b) { if (a !== b) throw new Error("Not equal"); };',
+    'assert.deepStrictEqual = function() {};',
+    'assert.fail = function(msg) { throw new Error(msg); };',
+    'export default assert;',
+    'export var ok = assert;',
+    'export var strictEqual = assert.strictEqual;',
+  ].join('\n'));
+
+  writeFileSync(resolve(shimsDir, 'buffer.js'), [
+    'var _enc = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;',
+    'var _dec = typeof TextDecoder !== "undefined" ? new TextDecoder() : null;',
+    '',
+    'function BufferShim(arg) {',
+    '  if (typeof arg === "number") return new Uint8Array(arg);',
+    '  if (arg instanceof Uint8Array) return arg;',
+    '  if (arg instanceof ArrayBuffer) return new Uint8Array(arg);',
+    '  return new Uint8Array(0);',
+    '}',
+    '',
+    'BufferShim.from = function(data, encoding) {',
+    '  if (typeof data === "string") {',
+    '    if (encoding === "base64") {',
+    '      var bin = atob(data);',
+    '      var bytes = new Uint8Array(bin.length);',
+    '      for (var i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);',
+    '      return bytes;',
+    '    }',
+    '    return _enc ? _enc.encode(data) : new Uint8Array(0);',
+    '  }',
+    '  if (Array.isArray(data)) return new Uint8Array(data);',
+    '  if (data instanceof ArrayBuffer) return new Uint8Array(data);',
+    '  if (data instanceof Uint8Array) return new Uint8Array(data);',
+    '  return new Uint8Array(0);',
+    '};',
+    'BufferShim.alloc = function(size) { return new Uint8Array(size); };',
+    'BufferShim.allocUnsafe = function(size) { return new Uint8Array(size); };',
+    'BufferShim.isBuffer = function(obj) { return obj instanceof Uint8Array; };',
+    'BufferShim.isEncoding = function() { return true; };',
+    'BufferShim.byteLength = function(str) { return _enc ? _enc.encode(str).length : str.length; };',
+    'BufferShim.concat = function(list) {',
+    '  var total = 0;',
+    '  for (var i = 0; i < list.length; i++) total += list[i].length;',
+    '  var result = new Uint8Array(total);',
+    '  var offset = 0;',
+    '  for (var j = 0; j < list.length; j++) { result.set(list[j], offset); offset += list[j].length; }',
+    '  return result;',
+    '};',
+    '',
+    'export var Buffer = BufferShim;',
+    'export var SlowBuffer = BufferShim;',
+    'export var INSPECT_MAX_BYTES = 50;',
+    'export var kMaxLength = 2147483647;',
+    'export default { Buffer: BufferShim, SlowBuffer: BufferShim, INSPECT_MAX_BYTES: 50, kMaxLength: 2147483647 };',
+  ].join('\n'));
+
+  writeFileSync(resolve(shimsDir, 'stream.js'), [
+    'function EventBase() { this._e = {}; }',
+    'EventBase.prototype.on = function(ev, fn) { (this._e[ev] = this._e[ev] || []).push(fn); return this; };',
+    'EventBase.prototype.addListener = EventBase.prototype.on;',
+    'EventBase.prototype.once = function(ev, fn) { var self = this; var w = function() { self.removeListener(ev, w); fn.apply(null, arguments); }; return this.on(ev, w); };',
+    'EventBase.prototype.emit = function(ev) { var args = [].slice.call(arguments, 1); (this._e[ev] || []).forEach(function(fn) { fn.apply(null, args); }); return true; };',
+    'EventBase.prototype.removeListener = function(ev, fn) { var l = this._e[ev]; if (l) this._e[ev] = l.filter(function(f) { return f !== fn; }); return this; };',
+    'EventBase.prototype.off = EventBase.prototype.removeListener;',
+    'EventBase.prototype.removeAllListeners = function(ev) { if (ev) delete this._e[ev]; else this._e = {}; return this; };',
+    'EventBase.prototype.setMaxListeners = function() { return this; };',
+    'EventBase.prototype.listeners = function(ev) { return this._e[ev] || []; };',
+    '',
+    'function Readable() { EventBase.call(this); } Readable.prototype = Object.create(EventBase.prototype);',
+    'Readable.prototype.read = function() { return null; };',
+    'Readable.prototype.pipe = function(d) { return d; };',
+    'Readable.prototype.unpipe = function() { return this; };',
+    'Readable.prototype.destroy = function() { return this; };',
+    '',
+    'function Writable() { EventBase.call(this); } Writable.prototype = Object.create(EventBase.prototype);',
+    'Writable.prototype.write = function() { return true; };',
+    'Writable.prototype.end = function() { return this; };',
+    'Writable.prototype.destroy = function() { return this; };',
+    '',
+    'function Transform() { EventBase.call(this); } Transform.prototype = Object.create(EventBase.prototype);',
+    'Transform.prototype.write = function() { return true; };',
+    'Transform.prototype.end = function() { return this; };',
+    'Transform.prototype.pipe = function(d) { return d; };',
+    'Transform.prototype.destroy = function() { return this; };',
+    '',
+    'function PassThrough() { Transform.call(this); } PassThrough.prototype = Object.create(Transform.prototype);',
+    'function Duplex() { EventBase.call(this); } Duplex.prototype = Object.create(EventBase.prototype);',
+    'Duplex.prototype.write = function() { return true; };',
+    'Duplex.prototype.end = function() { return this; };',
+    'Duplex.prototype.read = function() { return null; };',
+    'Duplex.prototype.pipe = function(d) { return d; };',
+    'Duplex.prototype.destroy = function() { return this; };',
+    '',
+    'function Stream() { EventBase.call(this); } Stream.prototype = Object.create(EventBase.prototype);',
+    'Stream.prototype.pipe = function(d) { return d; };',
+    'Stream.Readable = Readable; Stream.Writable = Writable; Stream.Transform = Transform;',
+    'Stream.PassThrough = PassThrough; Stream.Duplex = Duplex; Stream.Stream = Stream;',
+    '',
+    'export { Readable, Writable, Transform, PassThrough, Duplex, Stream };',
+    'export default Stream;',
+  ].join('\n'));
+
+  writeFileSync(resolve(shimsDir, 'util.js'), [
+    'export var inherits = function(ctor, superCtor) { ctor.super_ = superCtor; Object.setPrototypeOf(ctor.prototype, superCtor.prototype); };',
+    'export var deprecate = function(fn) { return fn; };',
+    'export var promisify = function(fn) { return function() { var args = [].slice.call(arguments); return new Promise(function(ok, fail) { args.push(function(err, res) { err ? fail(err) : ok(res); }); fn.apply(null, args); }); }; };',
+    'export var inspect = function(obj) { try { return JSON.stringify(obj); } catch(e) { return String(obj); } };',
+    'export var format = function(f) { if (typeof f !== "string") return [].map.call(arguments, function(a) { return inspect(a); }).join(" "); var i = 1; var args = arguments; return f.replace(/%[sdj%]/g, function(m) { if (m === "%%") return "%"; if (i >= args.length) return m; var v = args[i++]; if (m === "%s") return String(v); if (m === "%d") return Number(v); if (m === "%j") try { return JSON.stringify(v); } catch(e) { return "[Circular]"; } return m; }); };',
+    'export var debuglog = function() { return function() {}; };',
+    'export var isArray = Array.isArray;',
+    'export var isBoolean = function(v) { return typeof v === "boolean"; };',
+    'export var isNull = function(v) { return v === null; };',
+    'export var isNumber = function(v) { return typeof v === "number"; };',
+    'export var isString = function(v) { return typeof v === "string"; };',
+    'export var isUndefined = function(v) { return v === undefined; };',
+    'export var isObject = function(v) { return typeof v === "object" && v !== null; };',
+    'export var isFunction = function(v) { return typeof v === "function"; };',
+    'export var isRegExp = function(v) { return v instanceof RegExp; };',
+    'export var isDate = function(v) { return v instanceof Date; };',
+    'export var isError = function(v) { return v instanceof Error; };',
+    'export var isPrimitive = function(v) { return v === null || typeof v !== "object" && typeof v !== "function"; };',
+    'export var TextEncoder = globalThis.TextEncoder;',
+    'export var TextDecoder = globalThis.TextDecoder;',
+    'export var types = { isAnyArrayBuffer: function() { return false; }, isTypedArray: function(v) { return ArrayBuffer.isView(v); } };',
+    'export default { inherits: inherits, deprecate: deprecate, promisify: promisify, inspect: inspect, format: format, debuglog: debuglog, isArray: isArray, isBoolean: isBoolean, isNull: isNull, isNumber: isNumber, isString: isString, isUndefined: isUndefined, isObject: isObject, isFunction: isFunction, isRegExp: isRegExp, isDate: isDate, isError: isError, isPrimitive: isPrimitive, TextEncoder: TextEncoder, TextDecoder: TextDecoder, types: types };',
+  ].join('\n'));
+
+  writeFileSync(resolve(shimsDir, 'events.js'), [
+    'function EventEmitter() { this._events = {}; this._maxListeners = 10; }',
+    'EventEmitter.prototype.on = function(ev, fn) { (this._events[ev] = this._events[ev] || []).push(fn); return this; };',
+    'EventEmitter.prototype.addListener = EventEmitter.prototype.on;',
+    'EventEmitter.prototype.once = function(ev, fn) { var self = this; var w = function() { self.removeListener(ev, w); fn.apply(null, arguments); }; return this.on(ev, w); };',
+    'EventEmitter.prototype.emit = function(ev) { var args = [].slice.call(arguments, 1); (this._events[ev] || []).forEach(function(fn) { fn.apply(null, args); }); return true; };',
+    'EventEmitter.prototype.removeListener = function(ev, fn) { var l = this._events[ev]; if (l) this._events[ev] = l.filter(function(f) { return f !== fn; }); return this; };',
+    'EventEmitter.prototype.off = EventEmitter.prototype.removeListener;',
+    'EventEmitter.prototype.removeAllListeners = function(ev) { if (ev) delete this._events[ev]; else this._events = {}; return this; };',
+    'EventEmitter.prototype.setMaxListeners = function(n) { this._maxListeners = n; return this; };',
+    'EventEmitter.prototype.getMaxListeners = function() { return this._maxListeners; };',
+    'EventEmitter.prototype.listeners = function(ev) { return this._events[ev] || []; };',
+    'EventEmitter.prototype.listenerCount = function(ev) { return (this._events[ev] || []).length; };',
+    'EventEmitter.prototype.prependListener = EventEmitter.prototype.on;',
+    'EventEmitter.prototype.prependOnceListener = EventEmitter.prototype.once;',
+    'EventEmitter.prototype.eventNames = function() { return Object.keys(this._events); };',
+    'EventEmitter.EventEmitter = EventEmitter;',
+    'EventEmitter.defaultMaxListeners = 10;',
+    'export { EventEmitter };',
+    'export default EventEmitter;',
+  ].join('\n'));
+
+  writeFileSync(resolve(shimsDir, 'os.js'), [
+    'export var platform = function() { return "browser"; };',
+    'export var tmpdir = function() { return "/tmp"; };',
+    'export var homedir = function() { return "/"; };',
+    'export var hostname = function() { return "localhost"; };',
+    'export var type = function() { return "Browser"; };',
+    'export var arch = function() { return "wasm"; };',
+    'export var release = function() { return "0.0.0"; };',
+    'export var EOL = "\\n";',
+    'export var endianness = function() { return "LE"; };',
+    'export var cpus = function() { return []; };',
+    'export var totalmem = function() { return 0; };',
+    'export var freemem = function() { return 0; };',
+    'export var networkInterfaces = function() { return {}; };',
+    'export var userInfo = function() { return { username: "browser", uid: 0, gid: 0, shell: "", homedir: "/" }; };',
+    'export default { platform: platform, tmpdir: tmpdir, homedir: homedir, hostname: hostname, type: type, arch: arch, release: release, EOL: EOL, endianness: endianness, cpus: cpus, totalmem: totalmem, freemem: freemem, networkInterfaces: networkInterfaces, userInfo: userInfo };',
+  ].join('\n'));
+}
+
+// ── Main ─────────────────────────────────────────────────────────────
+
 async function main() {
   const args = process.argv.slice(2);
   const doAll = args.includes('--all');
@@ -229,43 +639,10 @@ async function main() {
 
   mkdirSync(THEMES_DIR, { recursive: true });
 
-  // Create shims directory
+  // Create shims directory and write all shims
   const shimsDir = resolve(__dirname, 'shims');
   mkdirSync(shimsDir, { recursive: true });
-  writeFileSync(resolve(shimsDir, 'path.js'), `
-    export const join = (...parts) => parts.join('/');
-    export const resolve = (...parts) => parts.join('/');
-    export const dirname = (p) => p.split('/').slice(0, -1).join('/');
-    export const basename = (p) => p.split('/').pop();
-    export const extname = (p) => { const m = p.match(/\\.[^.]+$/); return m ? m[0] : ''; };
-    export default { join, resolve, dirname, basename, extname };
-  `);
-  // fs shim is generated per-theme in bundleTheme() with embedded file contents
-  writeFileSync(resolve(shimsDir, 'url.js'), `
-    export const URL = globalThis.URL;
-    export const URLSearchParams = globalThis.URLSearchParams;
-    export const fileURLToPath = (u) => u.replace(/^file:\\/\\//, '');
-    export const pathToFileURL = (p) => new globalThis.URL('file://' + p);
-    export const format = (u) => (typeof u === 'string' ? u : u.href);
-    export const parse = (u) => new globalThis.URL(u);
-    export default { URL, URLSearchParams, fileURLToPath, pathToFileURL, format, parse };
-  `);
-  writeFileSync(resolve(shimsDir, 'crypto.js'), `
-    export const createHash = () => ({ update: function() { return this; }, digest: () => '' });
-    export const randomBytes = (n) => new Uint8Array(n);
-    export const createHmac = () => ({ update: function() { return this; }, digest: () => '' });
-    export default { createHash, randomBytes, createHmac };
-  `);
-  writeFileSync(resolve(shimsDir, 'assert.js'), `
-    const assert = (v, msg) => { if (!v) throw new Error(msg || 'Assertion failed'); };
-    assert.ok = assert;
-    assert.strictEqual = (a, b) => { if (a !== b) throw new Error('Not equal'); };
-    assert.deepStrictEqual = () => {};
-    assert.fail = (msg) => { throw new Error(msg); };
-    export default assert;
-    export const ok = assert;
-    export const strictEqual = assert.strictEqual;
-  `);
+  writeShims(shimsDir);
 
   let themes;
   if (specificThemes) {
@@ -295,16 +672,16 @@ async function main() {
 
     // Install the theme
     try {
-      execSync(`npm install --no-save ${theme.packageName} 2>/dev/null`, {
+      execSync(`npm install --no-save --prefer-offline ${theme.packageName} 2>/dev/null`, {
         cwd: resolve(__dirname, '..'),
-        timeout: 30000,
+        timeout: 60000,
       });
     } catch {
       console.log('❌ install failed');
       continue;
     }
 
-    // Try to get description from installed package
+    // Read package metadata
     try {
       const pkgPath = resolve(__dirname, `../node_modules/${theme.packageName}/package.json`);
       if (existsSync(pkgPath)) {
@@ -314,21 +691,44 @@ async function main() {
       }
     } catch {}
 
-    // Bundle it
+    // Step 1: Generate snapshot (pre-render in Node.js)
+    let hasSnapshot = false;
+    let hasCss = false;
+    const snapshotResult = generateSnapshot(theme.name, theme.packageName);
+    if (snapshotResult && typeof snapshotResult.then === 'function') {
+      const html = await snapshotResult;
+      hasSnapshot = !!html;
+      hasCss = existsSync(resolve(THEMES_DIR, `${theme.name}.css`));
+    } else {
+      hasSnapshot = !!snapshotResult;
+      hasCss = existsSync(resolve(THEMES_DIR, `${theme.name}.css`));
+    }
+
+    // Step 2: Bundle for browser
     const success = await bundleTheme(theme.name, theme.packageName, shimsDir);
 
     if (success) {
       const outFile = resolve(THEMES_DIR, `${theme.name}.js`);
       const stat = existsSync(outFile) ? readFileSync(outFile).length : 0;
+      const cssFile = resolve(THEMES_DIR, `${theme.name}.css`);
+      const cssSize = hasCss && existsSync(cssFile) ? readFileSync(cssFile).length : 0;
+
       manifest.push({
         name: theme.name,
         displayName: theme.name.charAt(0).toUpperCase() + theme.name.slice(1).replace(/-/g, ' '),
         description: theme.description,
         version: theme.version || '',
         browserCompatible: true,
+        hasSnapshot,
+        hasCss,
         fileSize: stat,
+        cssSize,
       });
-      console.log(`✅ (${(stat / 1024).toFixed(0)}KB)`);
+
+      const parts = [`✅ (${(stat / 1024).toFixed(0)}KB`];
+      if (hasCss) parts.push(`css:${(cssSize / 1024).toFixed(0)}KB`);
+      if (hasSnapshot) parts.push('snapshot');
+      console.log(parts.join(', ') + ')');
     } else {
       manifest.push({
         name: theme.name,
@@ -336,9 +736,13 @@ async function main() {
         description: theme.description,
         version: theme.version || '',
         browserCompatible: false,
+        hasSnapshot,
+        hasCss: false,
         fileSize: 0,
+        cssSize: 0,
       });
-      console.log('⚠️  browser incompatible');
+      const note = hasSnapshot ? '⚠️  browser incompatible (has snapshot)' : '⚠️  browser incompatible';
+      console.log(note);
     }
   }
 
@@ -346,7 +750,8 @@ async function main() {
   writeFileSync(resolve(THEMES_DIR, 'manifest.json'), JSON.stringify(manifest, null, 2));
 
   const successful = manifest.filter(t => t.browserCompatible).length;
-  console.log(`\n✅ Done! ${successful}/${manifest.length} themes bundled for the browser`);
+  const snapshots = manifest.filter(t => t.hasSnapshot).length;
+  console.log(`\n✅ Done! ${successful}/${manifest.length} themes bundled, ${snapshots} snapshots generated`);
   console.log(`📁 Output: docs/themes/`);
 
   // Clean up shims