@kenjura/ursa 0.61.1 → 0.62.2

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+# 0.62.2
+2026-01-29
+
+- Fixed CI issue with pnpm using npm-specific syntax
+
+# 0.62.1
+2026-01-29
+
+- CI now uses pnpm to avoid redundant package managers
+
+# 0.62.0
+2026-01-29
+
+- **Enhanced Auto-Index**: Index documents can now configure auto-index generation via frontmatter
+  - `generate-auto-index: true` - Include an auto-generated index listing in the page
+  - `auto-index-depth: N` - Control recursion depth (1 = current folder, 2 = current + subfolders, etc.)
+  - `auto-index-position: top|bottom` - Insert the auto-index before or after the document content
+
+- **Faster Serve Mode**: The `serve` command now uses deferred image processing for significantly faster startup
+  - HTML files are generated immediately with original image paths
+  - Image preview generation runs in the background after HTML is ready
+  - Site is browsable within seconds instead of waiting for full image processing
+  - Images will display as originals until preview generation completes (then show optimized WebP previews)
+  - Added hot reloading for regeneration
+
+- **Bug Fixes**:
+  - Fixed issue where style.css changes were not reflected until server restart in `serve` mode
+  - Fixed issue where root-level auto-index had incorrect HREFs
+  - Fixed issue where re-generating an index document with `generate-auto-index:true` did not include the auto-index until server restart
+  - Fixed issue where auto-indexer was rendering 'img' folders
+
 # 0.61.1
 2026-01-14
 

package/README.md

@@ -216,6 +216,53 @@ your-project/
 └── output/          # Generated site (created automatically)
 ```
 
+## Auto-Index Generation
+
+Ursa automatically generates index pages for folders that don't have one. You can also explicitly control auto-index generation in your index documents using frontmatter:
+
+```yaml
+---
+title: My Section
+generate-auto-index: true
+auto-index-depth: 2
+auto-index-position: bottom
+---
+
+# Welcome to My Section
+
+This is the introduction to my section. The auto-generated file listing will appear below.
+```
+
+### Auto-Index Frontmatter Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `generate-auto-index` | boolean | false | When true, generates an auto-index listing for this folder |
+| `auto-index-depth` | number | 1 | Recursion depth: 1 = current folder only, 2 = include subfolders, etc. |
+| `auto-index-position` | 'top' \| 'bottom' | 'top' | Where to insert the auto-index relative to document content |
+
+### Examples
+
+**Basic auto-index (top of page):**
+```yaml
+---
+generate-auto-index: true
+---
+```
+
+**Deep auto-index at bottom:**
+```yaml
+---
+generate-auto-index: true
+auto-index-depth: 3
+auto-index-position: bottom
+---
+
+# Section Overview
+
+Here's some content explaining this section...
+```
+
 ## Developing
 
 For development on ursa itself:

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.61.1",
+  "version": "0.62.2",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -36,6 +36,7 @@
     "node-watch": "^0.7.3",
     "object-to-xml": "^2.0.0",
     "sharp": "^0.33.2",
+    "ws": "^8.19.0",
     "yaml": "^2.1.3",
     "yargs": "^17.7.2"
   },

package/src/helper/build/autoIndex.js

@@ -6,7 +6,149 @@ import { outputFile } from "fs-extra";
 import { findStyleCss } from "../findStyleCss.js";
 import { toTitleCase } from "./titleCase.js";
 import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
-import { isMetadataOnly } from "../metadataExtractor.js";
+import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
+
+/**
+ * Generate auto-index HTML content for a directory from the OUTPUT folder
+ * (used by fallback auto-index generation after all files are generated)
+ * @param {string} dir - The directory path to generate index for (in output folder)
+ * @param {number} depth - How deep to recurse (1 = current level only, 2 = current + children, etc.)
+ * @param {number} [currentDepth=0] - Current recursion depth (internal use)
+ * @param {string} [pathPrefix=''] - Path prefix for generating correct hrefs (internal use)
+ * @returns {Promise<string>} HTML content for the auto-index
+ */
+export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pathPrefix = '') {
+  try {
+    const children = await readdir(dir, { withFileTypes: true });
+    
+    // Filter to only include relevant files and folders
+    const filteredChildren = children
+      .filter(child => {
+        // Skip hidden files
+        if (child.name.startsWith('.')) return false;
+        // Skip index.html - we're generating it or it's the current page
+        if (child.name === 'index.html') return false;
+        // Skip img folders (contain images, not content)
+        if (child.isDirectory() && child.name === 'img') return false;
+        // Include directories and html files
+        return child.isDirectory() || child.name.endsWith('.html');
+      })
+      .sort((a, b) => {
+        // Directories first, then files, alphabetically within each group
+        if (a.isDirectory() && !b.isDirectory()) return -1;
+        if (!a.isDirectory() && b.isDirectory()) return 1;
+        return a.name.localeCompare(b.name);
+      });
+    
+    if (filteredChildren.length === 0) {
+      return '';
+    }
+    
+    const items = [];
+    
+    for (const child of filteredChildren) {
+      const isDir = child.isDirectory();
+      const name = isDir ? child.name : child.name.replace('.html', '');
+      // Use pathPrefix to ensure hrefs are correct relative to the document root
+      const childPath = pathPrefix ? `${pathPrefix}/${child.name}` : child.name;
+      const href = isDir ? `${childPath}/index.html` : (pathPrefix ? `${pathPrefix}/${child.name}` : child.name);
+      const displayName = toTitleCase(name);
+      const icon = isDir ? '📁' : '📄';
+      
+      let itemHtml = `<li>${icon} <a href="${href}">${displayName}</a>`;
+      
+      // If this is a directory and we need to go deeper, recurse
+      if (isDir && currentDepth + 1 < depth) {
+        const childDir = join(dir, child.name);
+        const childHtml = await generateAutoIndexHtml(childDir, depth, currentDepth + 1, childPath);
+        if (childHtml) {
+          itemHtml += `\n${childHtml}`;
+        }
+      }
+      
+      itemHtml += '</li>';
+      items.push(itemHtml);
+    }
+    
+    return `<ul class="auto-index depth-${currentDepth + 1}">\n${items.join('\n')}\n</ul>`;
+  } catch (e) {
+    console.error(`Error generating auto-index HTML for ${dir}: ${e.message}`);
+    return '';
+  }
+}
+
+/**
+ * Generate auto-index HTML content from the SOURCE folder
+ * (used for inline auto-index generation in index.md files with generate-auto-index: true)
+ * This version reads from source to avoid race conditions with concurrent file generation
+ * @param {string} sourceDir - The source directory path
+ * @param {number} depth - How deep to recurse (1 = current level only, 2 = current + children, etc.)
+ * @param {number} [currentDepth=0] - Current recursion depth (internal use)
+ * @param {string} [pathPrefix=''] - Path prefix for generating correct hrefs (internal use)
+ * @returns {Promise<string>} HTML content for the auto-index
+ */
+export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, currentDepth = 0, pathPrefix = '') {
+  try {
+    const children = await readdir(sourceDir, { withFileTypes: true });
+    
+    // Filter to only include relevant files and folders
+    const filteredChildren = children
+      .filter(child => {
+        // Skip hidden files
+        if (child.name.startsWith('.')) return false;
+        // Skip index files (we're generating into the index)
+        if (child.name.match(/^index\.(md|txt|yml|html)$/i)) return false;
+        // Skip img folders (contain images, not content)
+        if (child.isDirectory() && child.name === 'img') return false;
+        // Include directories and article files (md, txt, yml, html)
+        return child.isDirectory() || child.name.match(/\.(md|txt|yml|html)$/i);
+      })
+      .sort((a, b) => {
+        // Directories first, then files, alphabetically within each group
+        if (a.isDirectory() && !b.isDirectory()) return -1;
+        if (!a.isDirectory() && b.isDirectory()) return 1;
+        return a.name.localeCompare(b.name);
+      });
+    
+    if (filteredChildren.length === 0) {
+      return '';
+    }
+    
+    const items = [];
+    
+    for (const child of filteredChildren) {
+      const isDir = child.isDirectory();
+      // Get name without extension for display
+      const ext = isDir ? '' : extname(child.name);
+      const nameWithoutExt = isDir ? child.name : basename(child.name, ext);
+      // Generate href - directories link to folder/index.html, files convert to .html
+      // Use pathPrefix to ensure hrefs are correct relative to the document root
+      const childPath = pathPrefix ? `${pathPrefix}/${child.name}` : child.name;
+      const href = isDir ? `${childPath}/index.html` : `${pathPrefix ? pathPrefix + '/' : ''}${nameWithoutExt}.html`;
+      const displayName = toTitleCase(nameWithoutExt);
+      const icon = isDir ? '📁' : '📄';
+      
+      let itemHtml = `<li>${icon} <a href="${href}">${displayName}</a>`;
+      
+      // If this is a directory and we need to go deeper, recurse
+      if (isDir && currentDepth + 1 < depth) {
+        const childDir = join(sourceDir, child.name);
+        const childHtml = await generateAutoIndexHtmlFromSource(childDir, depth, currentDepth + 1, childPath);
+        if (childHtml) {
+          itemHtml += `\n${childHtml}`;
+        }
+      }
+      
+      itemHtml += '</li>';
+      items.push(itemHtml);
+    }
+    
+    return `<ul class="auto-index depth-${currentDepth + 1}">\n${items.join('\n')}\n</ul>`;
+  } catch (e) {
+    console.error(`Error generating auto-index HTML for ${sourceDir}: ${e.message}`);
+    return '';
+  }
+}
 
 /**
  * Generate automatic index.html files for folders that don't have one

package/src/helper/frontmatterTable.js

@@ -65,12 +65,16 @@ export function metadataToTable(metadata) {
   // Filter out Ursa-internal keys that shouldn't be displayed in the metadata table
   // These are used by Ursa for rendering/menu behavior, not document metadata
   const excludeKeys = [
+    'title',          // Document title
     'template',       // Specifies which HTML template to use
     'layout',         // Alternative name for template
     'draft',          // Marks document as draft (not published)
     'published',      // Publication status
     'menu-label',     // Custom label for menu display
     'menu-sort-as',   // Custom sort key for menu ordering
+    'generate-auto-index', // Auto-indexing control
+    'auto-index-depth',    // Auto-indexing depth
+    'auto-index-position'  // Auto-indexing position
   ];
   const entries = Object.entries(metadata).filter(
     ([key]) => !excludeKeys.includes(key.toLowerCase())

package/src/helper/imageProcessor.js

@@ -151,6 +151,69 @@ export async function processImage(sourcePath, outputDir, relativeDir) {
   }
 }
 
+/**
+ * Copy a single image file without preview generation (fast copy).
+ * Used for deferred image processing mode where HTML is generated first.
+ * 
+ * @param {string} sourcePath - Absolute path to source image
+ * @param {string} outputDir - Absolute path to output directory
+ * @param {string} relativeDir - Relative directory path for URL generation
+ * @returns {Promise<{original: string, preview: string}|null>} Paths or null if not an image
+ */
+export async function copyImageFast(sourcePath, outputDir, relativeDir) {
+  const ext = extname(sourcePath).toLowerCase();
+  const filename = basename(sourcePath);
+  
+  // Ensure output directory exists
+  await mkdir(outputDir, { recursive: true });
+  
+  const originalOutputPath = join(outputDir, filename);
+  // Ensure URL is absolute (starts with /)
+  let originalUrl = join(relativeDir, filename).replace(/\\/g, '/');
+  if (!originalUrl.startsWith('/')) {
+    originalUrl = '/' + originalUrl;
+  }
+  
+  // Check if this is an image we handle
+  const allImageExtensions = [...COPY_ONLY_EXTENSIONS, ...PROCESSABLE_EXTENSIONS];
+  if (!allImageExtensions.includes(ext)) {
+    return null;
+  }
+  
+  // Just copy the original (no preview generation)
+  await copyFile(sourcePath, originalOutputPath);
+  
+  return {
+    original: originalUrl,
+    preview: originalUrl, // Same as original - no preview yet
+  };
+}
+
+/**
+ * Copy all images without processing (fast copy).
+ * Used for deferred image processing mode.
+ * 
+ * @param {string[]} imageFiles - Array of absolute paths to image files
+ * @param {string} sourceDir - Source directory root
+ * @param {string} outputDir - Output directory root
+ * @param {Function} progressCallback - Optional callback for progress updates
+ * @returns {Promise<void>}
+ */
+export async function copyAllImagesFast(imageFiles, sourceDir, outputDir, progressCallback) {
+  for (let i = 0; i < imageFiles.length; i++) {
+    const file = imageFiles[i];
+    const relativePath = file.replace(sourceDir, '');
+    const relativeDir = dirname(relativePath);
+    const absoluteOutputDir = join(outputDir, relativeDir);
+    
+    if (progressCallback) {
+      progressCallback(i + 1, imageFiles.length, relativePath);
+    }
+    
+    await copyImageFast(file, absoluteOutputDir, relativeDir);
+  }
+}
+
 /**
  * Build a map of all image paths to their preview/original URLs.
  * This is used to transform img tags in HTML.

package/src/helper/metadataExtractor.js

@@ -37,6 +37,19 @@ export function isMetadataOnly(rawBody) {
   return contentAfter.length === 0;
 }
 
+/**
+ * Extract auto-index configuration from metadata
+ * @param {object} metadata - Parsed frontmatter metadata
+ * @returns {{enabled: boolean, depth: number, position: 'top'|'bottom'}} Auto-index configuration
+ */
+export function getAutoIndexConfig(metadata) {
+  return {
+    enabled: metadata?.['generate-auto-index'] === true,
+    depth: typeof metadata?.['auto-index-depth'] === 'number' ? metadata['auto-index-depth'] : 1,
+    position: metadata?.['auto-index-position'] === 'bottom' ? 'bottom' : 'top'
+  };
+}
+
 function matchFrontMatter(str) {
   // Only match YAML front matter at the start of the file
   // Must have --- at line start, content, then closing --- also at line start

package/src/jobs/generate.js

@@ -8,6 +8,7 @@ import {
   extractMetadata,
   extractRawMetadata,
   isMetadataOnly,
+  getAutoIndexConfig,
 } from "../helper/metadataExtractor.js";
 import { injectFrontmatterTable } from "../helper/frontmatterTable.js";
 import {
@@ -33,7 +34,7 @@ import o2x from "object-to-xml";
 import { existsSync } from "fs";
 import { fileExists } from "../helper/fileExists.js";
 import { createWhitelistFilter } from "../helper/whitelistFilter.js";
-import { processAllImages, transformImageTags, clearImageCache } from "../helper/imageProcessor.js";
+import { processAllImages, transformImageTags, clearImageCache, copyAllImagesFast } from "../helper/imageProcessor.js";
 
 // Import build helpers from organized modules
 import {
@@ -55,6 +56,7 @@ import {
   getTransformedMetadata,
   getFooter,
   generateAutoIndices,
+  generateAutoIndexHtmlFromSource,
 } from "../helper/build/index.js";
 
 // Concurrency limiter for batch processing to avoid memory exhaustion
@@ -81,8 +83,9 @@ export async function generate({
   _exclude = null,
   _incremental = false,  // Legacy flag, now ignored (always incremental)
   _clean = false,  // When true, ignore cache and regenerate all files
+  _deferImages = false,  // When true, copy images without processing, return promise for background processing
 } = {}) {
-  console.log({ _source, _meta, _output, _whitelist, _exclude, _clean });
+  console.log({ _source, _meta, _output, _whitelist, _exclude, _clean, _deferImages });
   const source = resolve(_source) + "/";
   const meta = resolve(_meta);
   const output = resolve(_output) + "/";
@@ -225,23 +228,63 @@ export async function generate({
   // Track CSS files that have been copied to avoid duplicates
   const copiedCssFiles = new Set();
 
-  // Process all images FIRST to build the preview image map
-  // This is done before articles so we can transform img tags in the HTML
+  // Identify all image files
   const imageExtensions = /\.(jpg|jpeg|png|gif|webp|svg|ico)/;
   const allSourceFilenamesThatAreImages = allSourceFilenames.filter(
     (filename) => filename.match(imageExtensions) && !filename.match(hiddenOrSystemDirs)
   );
   
-  progress.log(`Processing ${allSourceFilenamesThatAreImages.length} images for preview generation...`);
-  const imageMap = await processAllImages(
-    allSourceFilenamesThatAreImages,
-    source,
-    output,
-    (current, total, path) => {
-      progress.status('Images', `${current}/${total} ${path}`);
-    }
-  );
-  progress.done('Images', `${allSourceFilenamesThatAreImages.length} done (${imageMap.size} with previews)`);
+  // Handle images based on deferred mode
+  let imageMap = new Map();
+  let deferredImageProcessingPromise = null;
+  
+  if (_deferImages) {
+    // Fast mode: just copy images without processing, defer preview generation
+    progress.log(`Copying ${allSourceFilenamesThatAreImages.length} images (preview generation deferred)...`);
+    await copyAllImagesFast(
+      allSourceFilenamesThatAreImages,
+      source,
+      output,
+      (current, total, path) => {
+        progress.status('Images (copy)', `${current}/${total} ${path}`);
+      }
+    );
+    progress.done('Images (copy)', `${allSourceFilenamesThatAreImages.length} copied (previews deferred)`);
+    
+    // Create promise for background image processing (will be returned to caller)
+    deferredImageProcessingPromise = (async () => {
+      progress.log(`\n🖼️  Starting deferred image preview generation...`);
+      const startTime = Date.now();
+      const processedImageMap = await processAllImages(
+        allSourceFilenamesThatAreImages,
+        source,
+        output,
+        (current, total, path) => {
+          progress.status('Images (previews)', `${current}/${total} ${path}`);
+        }
+      );
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+      progress.done('Images (previews)', `${allSourceFilenamesThatAreImages.length} done (${processedImageMap.size} with previews) in ${elapsed}s`);
+      
+      // Update the watch cache with the processed image map
+      watchModeCache.imageMap = processedImageMap;
+      
+      return processedImageMap;
+    })();
+  } else {
+    // Normal mode: process all images FIRST to build the preview image map
+    // This is done before articles so we can transform img tags in the HTML
+    progress.log(`Processing ${allSourceFilenamesThatAreImages.length} images for preview generation...`);
+    imageMap = await processAllImages(
+      allSourceFilenamesThatAreImages,
+      source,
+      output,
+      (current, total, path) => {
+        progress.status('Images', `${current}/${total} ${path}`);
+      }
+    );
+    progress.done('Images', `${allSourceFilenamesThatAreImages.length} done (${imageMap.size} with previews)`);
+  }
 
   // Track files that were regenerated (for incremental mode stats)
   let regeneratedCount = 0;
@@ -348,11 +391,32 @@ export async function generate({
         body = injectFrontmatterTable(body, fileMeta);
       }
 
+      // Handle auto-index generation for index files with generate-auto-index: true
+      if (base === 'index' && fileMeta) {
+        const autoIndexConfig = getAutoIndexConfig(fileMeta);
+        if (autoIndexConfig.enabled) {
+          // Generate auto-index HTML for this directory from source
+          // Using source avoids race conditions with concurrent file generation
+          const sourceDir = dirname(file);
+          const autoIndexHtml = await generateAutoIndexHtmlFromSource(sourceDir, autoIndexConfig.depth);
+          
+          if (autoIndexHtml) {
+            if (autoIndexConfig.position === 'bottom') {
+              body = body + '\n' + autoIndexHtml;
+            } else {
+              body = autoIndexHtml + '\n' + body;
+            }
+          }
+        }
+      }
+
       // Find nearest style.css or _style.css up the tree and copy to output
       // Use cache to avoid repeated filesystem walks for same directory
       let styleLink = "";
       try {
-        const dirKey = resolve(_source, dir);
+        // For root-level files, dir may be "/" which would resolve to filesystem root
+        // Use source directory directly in that case
+        const dirKey = (dir === "/" || dir === "") ? _source : resolve(_source, dir);
         let cssPath = cssPathCache.get(dirKey);
         if (cssPath === undefined) {
           cssPath = await findStyleCss(dirKey);
@@ -417,7 +481,10 @@ export async function generate({
       finalHtml = markInactiveLinks(finalHtml, validPaths, docUrlPath, false);
 
       // Transform image tags to use preview images with data-fullsrc for originals
-      finalHtml = transformImageTags(finalHtml, imageMap, docUrlPath);
+      // Skip in deferred mode - images will use original paths until preview generation completes
+      if (!_deferImages) {
+        finalHtml = transformImageTags(finalHtml, imageMap, docUrlPath);
+      }
 
       // Add cache-busting timestamps to static file references
       finalHtml = addTimestampToHtmlStaticRefs(finalHtml, cacheBustTimestamp);
@@ -613,7 +680,10 @@ export async function generate({
         // Resolve internal links to have proper .html extensions
         htmlContent = markInactiveLinks(htmlContent, validPaths, docUrlPath, false);
         // Transform image tags to use preview images with data-fullsrc for originals
-        htmlContent = transformImageTags(htmlContent, imageMap, docUrlPath);
+        // Skip in deferred mode - images will use original paths until preview generation completes
+        if (!_deferImages) {
+          htmlContent = transformImageTags(htmlContent, imageMap, docUrlPath);
+        }
         // Add cache-busting timestamps
         htmlContent = addTimestampToHtmlStaticRefs(htmlContent, cacheBustTimestamp);
         await outputFile(outputFilename, htmlContent);
@@ -686,6 +756,12 @@ export async function generate({
   } else {
     progress.log(`\n✅ Generation complete with no errors.\n`);
   }
+  
+  // Return deferred image processing promise if in deferred mode
+  // Caller can await this to know when image previews are ready
+  return {
+    deferredImageProcessing: deferredImageProcessingPromise
+  };
 }
 
 /**
@@ -751,17 +827,42 @@ export async function regenerateSingleFile(changedFile, {
     const docUrlPath = '/' + dir + base + '.html';
     
     // Render body
-    const body = renderFile({
+    let body = renderFile({
       fileContents: rawBody,
       type,
       dirname: dir,
       basename: base,
     });
     
+    // Inject frontmatter table for markdown files
+    if (type === '.md' && fileMeta) {
+      body = injectFrontmatterTable(body, fileMeta);
+    }
+
+    // Handle auto-index generation for index files with generate-auto-index: true
+    if (base === 'index' && fileMeta) {
+      const autoIndexConfig = getAutoIndexConfig(fileMeta);
+      if (autoIndexConfig.enabled) {
+        // Generate auto-index HTML for this directory from source
+        const sourceDir = dirname(changedFile);
+        const autoIndexHtml = await generateAutoIndexHtmlFromSource(sourceDir, autoIndexConfig.depth);
+        
+        if (autoIndexHtml) {
+          if (autoIndexConfig.position === 'bottom') {
+            body = body + '\n' + autoIndexHtml;
+          } else {
+            body = autoIndexHtml + '\n' + body;
+          }
+        }
+      }
+    }
+
     // Find CSS and copy to output
     let styleLink = "";
     try {
-      const cssPath = await findStyleCss(resolve(_source, dir));
+      // For root-level files, dir may be "/" which would resolve to filesystem root
+      const dirKey = (dir === "/" || dir === "") ? _source : resolve(_source, dir);
+      const cssPath = await findStyleCss(dirKey);
       if (cssPath) {
         // Calculate output path for the CSS file
         const cssOutputPath = cssPath.replace(source, output);

package/src/serve.js

@@ -7,8 +7,92 @@ import fs from "fs";
 import { promises } from "fs";
 import { outputFile } from "fs-extra";
 import { processImage } from "./helper/imageProcessor.js";
+import { WebSocketServer } from "ws";
+import { createServer } from "http";
 const { readdir, mkdir, readFile, copyFile } = promises;
 
+// WebSocket server for hot reloading
+let wss = null;
+
+/**
+ * Broadcast a reload message to all connected clients
+ * @param {string} [changedFile] - Optional path of the changed file
+ */
+function broadcastReload(changedFile = null) {
+  if (!wss) return;
+  const message = JSON.stringify({ 
+    type: 'reload',
+    file: changedFile,
+    timestamp: Date.now()
+  });
+  wss.clients.forEach(client => {
+    if (client.readyState === 1) { // WebSocket.OPEN
+      client.send(message);
+    }
+  });
+  const clientCount = wss.clients.size;
+  if (clientCount > 0) {
+    console.log(`🔄 Hot reload: notified ${clientCount} browser${clientCount > 1 ? 's' : ''}`);
+  }
+}
+
+/**
+ * Generate the hot reload client script
+ * @param {number} wsPort - WebSocket server port
+ * @returns {string} JavaScript code to inject
+ */
+function getHotReloadScript(wsPort) {
+  return `
+<!-- Ursa Hot Reload -->
+<script>
+(function() {
+  const wsUrl = 'ws://' + window.location.hostname + ':${wsPort}';
+  let ws;
+  let reconnectAttempts = 0;
+  const maxReconnectAttempts = 10;
+  const reconnectDelay = 1000;
+
+  function connect() {
+    ws = new WebSocket(wsUrl);
+    
+    ws.onopen = function() {
+      console.log('[Ursa] Hot reload connected');
+      reconnectAttempts = 0;
+    };
+    
+    ws.onmessage = function(event) {
+      try {
+        const data = JSON.parse(event.data);
+        if (data.type === 'reload') {
+          console.log('[Ursa] Reloading page...');
+          window.location.reload();
+        }
+      } catch (e) {
+        console.error('[Ursa] Hot reload error:', e);
+      }
+    };
+    
+    ws.onclose = function() {
+      if (reconnectAttempts < maxReconnectAttempts) {
+        reconnectAttempts++;
+        console.log('[Ursa] Hot reload disconnected, reconnecting... (' + reconnectAttempts + '/' + maxReconnectAttempts + ')');
+        setTimeout(connect, reconnectDelay);
+      } else {
+        console.log('[Ursa] Hot reload: max reconnect attempts reached');
+      }
+    };
+    
+    ws.onerror = function(error) {
+      console.error('[Ursa] Hot reload WebSocket error');
+    };
+  }
+  
+  connect();
+})();
+</script>
+`;
+}
+
 // Debounce timer and lock for preventing concurrent regenerations
 let debounceTimer = null;
 let isRegenerating = false;
@@ -98,12 +182,25 @@ export async function serve({
   serveFiles(outputDir, port);
   console.log(`🚀 Development server running at http://localhost:${port}`);
   console.log("📁 Serving files from:", outputDir);
-  console.log("⏳ Generating site in background...\n");
+  console.log("⏳ Generating site in background (deferred image processing)...\n");
 
-  // Initial generation (use _clean flag only for initial generation)
+  // Initial generation with deferred image processing for faster startup
   // This also initializes the watch cache for fast single-file updates
-  generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude, _clean })
-    .then(() => console.log("\n✅ Initial generation complete. Fast single-file regeneration enabled.\n"))
+  generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude, _clean, _deferImages: true })
+    .then(async (result) => {
+      console.log("\n✅ Initial HTML generation complete. Fast single-file regeneration enabled.");
+      console.log("   Note: Images may show as originals until preview generation completes.\n");
+      
+      // Wait for deferred image processing to complete
+      if (result && result.deferredImageProcessing) {
+        try {
+          await result.deferredImageProcessing;
+          console.log("\n✅ Image preview generation complete. Full site ready.\n");
+        } catch (error) {
+          console.error("Error during image processing:", error.message);
+        }
+      }
+    })
     .catch((error) => console.error("Error during initial generation:", error.message));
 
   // Watch for changes
@@ -118,8 +215,15 @@ export async function serve({
     console.log("Full rebuild required (meta files affect all pages)...");
     clearWatchCache(); // Clear cache since templates/CSS may have changed
     try {
-      await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude, _clean: true });
-      console.log("Regeneration complete.");
+      // Use deferred images for meta rebuilds too
+      const result = await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude, _clean: true, _deferImages: true });
+      console.log("HTML regeneration complete.");
+      broadcastReload(name);
+      if (result && result.deferredImageProcessing) {
+        result.deferredImageProcessing.then(() => {
+          console.log("Image preview generation complete.");
+        }).catch(e => console.error("Image processing error:", e.message));
+      }
     } catch (error) {
       console.error("Error during regeneration:", error.message);
     }
@@ -155,6 +259,7 @@ export async function serve({
         const result = await copyCssFile(name, sourceDir + '/', outputDir + '/');
         if (result.success) {
           console.log(`✅ ${result.message}`);
+          broadcastReload(name);
         } else {
           console.log(`⚠️ ${result.message}`);
         }
@@ -188,6 +293,7 @@ export async function serve({
           const result = await copyStaticFile(name, sourceDir + '/', outputDir + '/');
           if (result.success) {
             console.log(`✅ ${result.message}`);
+            broadcastReload(name);
           } else {
             console.log(`⚠️ ${result.message}`);
           }
@@ -208,6 +314,7 @@ export async function serve({
       try {
         await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude, _clean: true });
         console.log("Regeneration complete.");
+        broadcastReload(name);
       } catch (error) {
         console.error("Error during regeneration:", error.message);
       } finally {
@@ -230,6 +337,7 @@ export async function serve({
         
         if (result.success) {
           console.log(`✅ ${result.message}`);
+          broadcastReload(name);
           return;
         }
         
@@ -238,6 +346,7 @@ export async function serve({
         console.log("Falling back to full rebuild...");
         await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude });
         console.log("Regeneration complete.");
+        broadcastReload(name);
       } catch (error) {
         console.error("Error during regeneration:", error.message);
       } finally {
@@ -253,6 +362,7 @@ export async function serve({
     try {
       await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude });
       console.log("Regeneration complete.");
+      broadcastReload(name);
     } catch (error) {
       console.error("Error during regeneration:", error.message);
     } finally {
@@ -262,10 +372,14 @@ export async function serve({
 }
 
 /**
- * Start HTTP server to serve static files
+ * Start HTTP server to serve static files with hot reload support
+ * @param {string} outputDir - Directory to serve files from
+ * @param {number} port - HTTP server port
+ * @returns {object} Object containing httpServer and wsPort
  */
 function serveFiles(outputDir, port = 8080) {
   const app = express();
+  const wsPort = port + 1; // WebSocket on port+1
 
   // Enable gzip compression for all responses
   // This significantly reduces transfer size for JSON and HTML files
@@ -276,49 +390,83 @@ function serveFiles(outputDir, port = 8080) {
     level: 6
   }));
 
+  // Middleware to inject hot reload script into HTML responses
+  app.use(async (req, res, next) => {
+    // Only intercept HTML requests
+    const url = req.url;
+    const isHtmlRequest = url.endsWith('.html') || 
+                          url.endsWith('/') || 
+                          !url.includes('.') ||
+                          url === '/';
+    
+    if (!isHtmlRequest) {
+      return next();
+    }
+    
+    // Determine the file path
+    let filePath;
+    if (url === '/' || url.endsWith('/')) {
+      filePath = join(outputDir, url, 'index.html');
+    } else if (url.endsWith('.html')) {
+      filePath = join(outputDir, url);
+    } else {
+      // Try adding .html extension
+      filePath = join(outputDir, url + '.html');
+      if (!fs.existsSync(filePath)) {
+        filePath = join(outputDir, url, 'index.html');
+      }
+    }
+    
+    try {
+      if (fs.existsSync(filePath)) {
+        let html = await readFile(filePath, 'utf8');
+        // Inject hot reload script before </body>
+        const hotReloadScript = getHotReloadScript(wsPort);
+        if (html.includes('</body>')) {
+          html = html.replace('</body>', hotReloadScript + '</body>');
+        } else {
+          html += hotReloadScript;
+        }
+        res.setHeader('Content-Type', 'text/html');
+        res.send(html);
+      } else {
+        next();
+      }
+    } catch (error) {
+      next();
+    }
+  });
+
+  // Fallback static file serving for non-HTML files
   app.use(
     express.static(outputDir, { extensions: ["html"], index: "index.html" })
   );
 
-  app.get("/", async (req, res) => {
-    try {
-      console.log({ output: outputDir });
-      const dir = await readdir(outputDir);
-      const html = `
-        <!DOCTYPE html>
-        <html>
-        <head>
-          <title>Ursa Development Server</title>
-          <style>
-            body { font-family: Arial, sans-serif; margin: 40px; }
-            h1 { color: #333; }
-            ul { list-style-type: none; padding: 0; }
-            li { margin: 8px 0; }
-            a { color: #0066cc; text-decoration: none; }
-            a:hover { text-decoration: underline; }
-          </style>
-        </head>
-        <body>
-          <h1>Ursa Development Server</h1>
-          <p>Files in ${outputDir}:</p>
-          <ul>
-            ${dir
-              .map((file) => `<li><a href="${file}">${file}</a></li>`)
-              .join("")}
-          </ul>
-        </body>
-        </html>
-      `;
-      res.setHeader("Content-Type", "text/html");
-      res.send(html);
-    } catch (error) {
-      res.status(500).send("Error reading directory");
-    }
+  // Create HTTP server
+  const httpServer = createServer(app);
+  
+  // Create WebSocket server for hot reload
+  wss = new WebSocketServer({ port: wsPort });
+  
+  wss.on('connection', (ws) => {
+    // Send a ping to keep connection alive
+    const pingInterval = setInterval(() => {
+      if (ws.readyState === 1) {
+        ws.ping();
+      }
+    }, 30000);
+    
+    ws.on('close', () => {
+      clearInterval(pingInterval);
+    });
   });
 
-  app.listen(port, () => {
+  httpServer.listen(port, () => {
     console.log(`🌐 Server listening on port ${port}`);
+    console.log(`🔥 Hot reload WebSocket on port ${wsPort}`);
   });
+  
+  return { httpServer, wsPort };
 }
 
 /**