@kenjura/ursa 0.47.0 → 0.49.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# 0.49.0
+2025-12-20
+
+- Fixed more instances of false inactive links, this time in wikitext files (.txt)
+
+
+# 0.48.0
+2025-12-20
+
+- **External CSS**: CSS files are now externally linked via `<link>` tags instead of being embedded in each HTML page. This significantly reduces HTML file sizes and improves browser caching.
+- **Fast CSS Updates**: CSS file changes in watch mode now just copy the file to output (~1ms) instead of triggering a full rebuild
+- **Fast Single-File Regeneration**: Article changes in watch mode use a new fast-path that regenerates only the changed file (~50-100ms) instead of scanning all source files
+- **Clickable Folder Links**: All folders in the navigation menu are now clickable links (auto-index ensures every folder has an index.html)
+- **Menu Collapse Fix**: Fixed issue where clicking the caret on a folder containing the current page wouldn't collapse it
+- **URL Encoding Fix**: Fixed menu not highlighting current page when URLs contain spaces or special characters
+- **Link Validation Fix**: Links to folders are no longer incorrectly marked as inactive (folders now included in valid paths since auto-index generates index.html for all)
+- **WikiText Link Fix**: Fixed wikitext links (in .txt files) being incorrectly marked as inactive. Link validation is now handled centrally by the link validator after HTML generation.
+- **Folder/Index Link Fix**: Links to folders containing a `(foldername).md` file (instead of `index.md`) are now correctly recognized as valid
+
 # 0.47.0
 2025-12-20
 

package/meta/default-template.html

@@ -5,9 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>${title}</title>
     <link rel="stylesheet" href="/public/default.css" />
-     <style>
-        ${embeddedStyle}
-     </style>
+    ${styleLink}
      <script>
         // Search index loaded asynchronously from separate file to reduce page size
         window.SEARCH_INDEX = ${searchIndex};

package/meta/menu.js

@@ -28,6 +28,7 @@ document.addEventListener('DOMContentLoaded', () => {
     // State
     let currentPath = []; // Array of path segments representing current directory
     let expandedLevel1 = new Set(); // Track which level-1 items are expanded
+    let collapsedLevel1 = new Set(); // Track which level-1 items are explicitly collapsed (overrides auto-expand for current page)
 
     // DOM elements
     const breadcrumb = navMain.querySelector('.menu-breadcrumb');
@@ -124,8 +125,8 @@ document.addEventListener('DOMContentLoaded', () => {
             const hasChildrenClass = item.hasChildren ? ' has-children' : '';
             
             // Level-1 items with children get a caret, not triple-dot
-            // Expanded if: manually expanded, or current page is in this tree
-            const isExpanded = expandedLevel1.has(item.path) || isCurrentPageInTree(item);
+            // Expanded if: manually expanded, or (current page is in this tree AND not explicitly collapsed)
+            const isExpanded = expandedLevel1.has(item.path) || (isCurrentPageInTree(item) && !collapsedLevel1.has(item.path));
             const expandedClass = isExpanded ? ' expanded' : '';
             const caretIndicator = item.hasChildren 
                 ? `<span class="menu-caret">${isExpanded ? '▼' : '▶'}</span>` 
@@ -204,9 +205,9 @@ document.addEventListener('DOMContentLoaded', () => {
     function isCurrentPage(item) {
         if (!item.href) return false;
         const currentHref = window.location.pathname;
-        // Normalize paths for comparison
-        const normalizedItemHref = item.href.replace(/\/index\.html$/, '').replace(/\.html$/, '');
-        const normalizedCurrentHref = currentHref.replace(/\/index\.html$/, '').replace(/\.html$/, '');
+        // Normalize paths for comparison - decode URI components to handle spaces and special chars
+        const normalizedItemHref = decodeURIComponent(item.href).replace(/\/index\.html$/, '').replace(/\.html$/, '');
+        const normalizedCurrentHref = decodeURIComponent(currentHref).replace(/\/index\.html$/, '').replace(/\.html$/, '');
         return normalizedItemHref === normalizedCurrentHref;
     }
 
@@ -249,10 +250,18 @@ document.addEventListener('DOMContentLoaded', () => {
                         e.stopPropagation();
                         const path = li.dataset.path;
                         const hasLink = !!link;
+                        const containsCurrentPage = li.dataset.path === currentPageParentPath;
                         
-                        if (expandedLevel1.has(path)) {
+                        // Check current expanded state (same logic as renderMenu)
+                        const isCurrentlyExpanded = expandedLevel1.has(path) || (containsCurrentPage && !collapsedLevel1.has(path));
+                        
+                        if (isCurrentlyExpanded) {
                             // Collapsing this item
                             expandedLevel1.delete(path);
+                            // If it contains current page, mark as explicitly collapsed
+                            if (containsCurrentPage) {
+                                collapsedLevel1.add(path);
+                            }
                         } else {
                             // Expanding this item
                             // If this item has no link (non-navigable folder), collapse others
@@ -260,6 +269,8 @@ document.addEventListener('DOMContentLoaded', () => {
                                 expandedLevel1.clear();
                             }
                             expandedLevel1.add(path);
+                            // Remove from explicit collapsed set
+                            collapsedLevel1.delete(path);
                         }
                         renderMenu();
                     };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/helper/automenu.js

@@ -161,20 +161,27 @@ function buildMenuData(tree, source, validPaths, parentPath = '') {
     const label = folderConfig?.label || toDisplayName(baseName);
     
     let rawHref = null;
+    let href = null;
+    let inactive = false;
+    let debug = '';
+    
     if (hasChildren) {
-      if (hasIndexFile(item.path)) {
-        // Construct proper path - relativePath already starts with /
-        const cleanPath = relativePath.startsWith('/') ? relativePath : '/' + relativePath;
-        rawHref = `${cleanPath}/index.html`.replace(/\/\//g, '/');
-      }
+      // All folders now have index pages (either existing or auto-generated)
+      const cleanPath = relativePath.startsWith('/') ? relativePath : '/' + relativePath;
+      rawHref = `${cleanPath}/index.html`.replace(/\/\//g, '/');
+      href = rawHref;
+      inactive = false; // Always active - auto-index ensures all folders have index.html
+      debug = 'folder (auto-index enabled)';
     } else {
       const cleanPath = relativePath.startsWith('/') ? relativePath : '/' + relativePath;
       rawHref = cleanPath.replace(ext, '');
+      // Resolve the href and check if target exists
+      const resolved = resolveHref(rawHref, validPaths);
+      href = resolved.href;
+      inactive = resolved.inactive;
+      debug = resolved.debug;
     }
     
-    // Resolve the href and check if target exists
-    const { href, inactive, debug } = resolveHref(rawHref, validPaths);
-    
     // Determine icon - custom from config, or custom icon file, or default
     let icon = getIcon(item, source);
     if (folderConfig?.icon) {

package/src/helper/findStyleCss.js

@@ -3,11 +3,11 @@ import { existsSync } from "fs";
 
 /**
  * Recursively search for style.css or _style.css up the directory tree.
- * Returns the contents of the first found file, or null if not found.
+ * Returns the path to the first found file, or null if not found.
  * @param {string} startDir - Directory to start searching from
  * @param {string[]} [names=["style.css", "_style.css"]] - Filenames to look for
  * @param {string} [baseDir] - Stop searching when this directory is reached
- * @returns {Promise<string|null>} CSS contents or null
+ * @returns {Promise<string|null>} CSS file path or null
  */
 export async function findStyleCss(startDir, names = ["style-ursa.css", "style.css", "_style.css"], baseDir = null) {
   let dir = resolve(startDir);
@@ -16,7 +16,7 @@ export async function findStyleCss(startDir, names = ["style-ursa.css", "style.c
     for (const name of names) {
       const candidate = join(dir, name);
       if (existsSync(candidate)) {
-        return (await import('fs/promises')).readFile(candidate, "utf8");
+        return candidate; // Return path instead of contents
       }
     }
     if (dir === baseDir || dir === dirname(dir)) break;

package/src/helper/linkValidator.js

@@ -1,12 +1,13 @@
-import { extname, dirname, join, normalize, posix } from "path";
+import { extname, dirname, join, normalize, posix, basename } from "path";
 
 /**
- * Build a set of valid internal paths from the list of source files
+ * Build a set of valid internal paths from the list of source files and directories
  * @param {string[]} sourceFiles - Array of source file paths
  * @param {string} source - Source directory path
+ * @param {string[]} [directories] - Optional array of directory paths (for auto-index support)
  * @returns {Set<string>} Set of valid internal paths (without extension, lowercased)
  */
-export function buildValidPaths(sourceFiles, source) {
+export function buildValidPaths(sourceFiles, source, directories = []) {
   const validPaths = new Set();
   
   for (const file of sourceFiles) {
@@ -19,6 +20,13 @@ export function buildValidPaths(sourceFiles, source) {
       relativePath = "/" + relativePath;
     }
     
+    // Decode URI components for paths with special characters (spaces, etc.)
+    try {
+      relativePath = decodeURIComponent(relativePath);
+    } catch (e) {
+      // Ignore decode errors
+    }
+    
     // Add both with and without trailing slash for directories
     validPaths.add(relativePath.toLowerCase());
     validPaths.add((relativePath + ".html").toLowerCase());
@@ -30,6 +38,46 @@ export function buildValidPaths(sourceFiles, source) {
       validPaths.add((dirPath + "/").toLowerCase());
       validPaths.add((dirPath + "/index.html").toLowerCase());
     }
+    
+    // Handle (foldername).md files - they get promoted to index.html by auto-index
+    // e.g., /foo/bar/bar.md becomes /foo/bar/index.html (bar.html promoted to index.html)
+    const fileName = basename(relativePath); // e.g., "bar" from "/foo/bar/bar"
+    const parentDir = dirname(relativePath); // e.g., "/foo/bar" from "/foo/bar/bar"
+    const parentDirName = basename(parentDir); // e.g., "bar" from "/foo/bar"
+    
+    if (fileName === parentDirName) {
+      // This file has same name as its parent folder - it will be promoted to index.html
+      validPaths.add(parentDir.toLowerCase());
+      validPaths.add((parentDir + "/").toLowerCase());
+      validPaths.add((parentDir + "/index.html").toLowerCase());
+    }
+  }
+  
+  // Add all directories as valid paths (they get auto-generated index.html)
+  for (const dir of directories) {
+    let relativePath = dir.replace(source, "");
+    
+    // Normalize: ensure leading slash
+    if (!relativePath.startsWith("/")) {
+      relativePath = "/" + relativePath;
+    }
+    
+    // Remove trailing slash for consistency
+    if (relativePath.endsWith("/")) {
+      relativePath = relativePath.slice(0, -1);
+    }
+    
+    // Decode URI components
+    try {
+      relativePath = decodeURIComponent(relativePath);
+    } catch (e) {
+      // Ignore decode errors
+    }
+    
+    // Add directory paths - all folders now have index.html (auto-generated if needed)
+    validPaths.add(relativePath.toLowerCase());
+    validPaths.add((relativePath + "/").toLowerCase());
+    validPaths.add((relativePath + "/index.html").toLowerCase());
   }
   
   // Add root

package/src/helper/wikitextHelper.js

@@ -10,8 +10,6 @@ export function wikiToHtml({ wikitext, articleName, args } = {}) {
   const linkbase = ("/" + db + "/").replace(/\/\//g, "/");
   const imageroot = ("/" + db + "/img/").replace(/\/\//g, "/");
 
-  const allArticles = args.allArticles || [];
-
   // console.log('wikitext=',wikitext);
   var html = String(wikitext);
   // instance.article = article;
@@ -226,31 +224,19 @@ export function wikiToHtml({ wikitext, articleName, args } = {}) {
     if (!anchor) anchor = "";
     else anchor = "#" + anchor;
 
-    var active = true;
-
-    active = !!allArticles.find((article) => article.match(articleName));
+    // Note: Link validation (active/inactive status) is now handled by linkValidator.js
+    // after HTML generation, so we don't set active/inactive class here.
 
     if (articleName.indexOf("/") >= 0) {
       // assume the link is fully formed
-      return `<a class="wikiLink${
-        active ? " active" : ""
-      } data-articleName="${articleName}" href="${articleName}">${
+      return `<a class="wikiLink" data-articleName="${articleName}" href="${articleName}">${
         displayName || articleName
       }</a>`;
     } else {
       var link = linkbase + articleName + anchor;
 
-      // not sure what this did, but I need a new handler for this case
-      // if (articleName.indexOf('/')>-1) {
-      // 	link = '/'+articleName+anchor;
-      // 	displayName = articleName.substr(articleName.indexOf('/')+1);
-      // 	console.log('link=',link);
-      // }
-
       return (
-        '<a class="wikiLink ' +
-        (active ? "active" : "inactive") +
-        '" data-articleName="' +
+        '<a class="wikiLink" data-articleName="' +
         articleName +
         '" href="' +
         link +

package/src/jobs/generate.js

@@ -5,6 +5,36 @@ import { copyFile, mkdir, readdir, readFile, stat } from "fs/promises";
 // Concurrency limiter for batch processing to avoid memory exhaustion
 const BATCH_SIZE = parseInt(process.env.URSA_BATCH_SIZE || '50', 10);
 
+/**
+ * Cache for watch mode - stores expensive data that doesn't change often
+ * This allows single-file regeneration to skip re-building menu, templates, etc.
+ */
+const watchModeCache = {
+  templates: null,
+  menu: null,
+  footer: null,
+  validPaths: null,
+  source: null,
+  meta: null,
+  output: null,
+  hashCache: null,
+  lastFullBuild: 0,
+  isInitialized: false,
+};
+
+/**
+ * Clear the watch mode cache (call when templates/meta/config change)
+ */
+export function clearWatchCache() {
+  watchModeCache.templates = null;
+  watchModeCache.menu = null;
+  watchModeCache.footer = null;
+  watchModeCache.validPaths = null;
+  watchModeCache.hashCache = null;
+  watchModeCache.isInitialized = false;
+  console.log('Watch cache cleared');
+}
+
 /**
  * Progress reporter that updates lines in place (like pnpm)
  */
@@ -270,7 +300,8 @@ export async function generate({
   )).filter((filename) => !filename.match(hiddenOrSystemDirs) && !isFolderHidden(filename, source));
 
   // Build set of valid internal paths for link validation (must be before menu)
-  const validPaths = buildValidPaths(allSourceFilenamesThatAreArticles, source);
+  // Pass directories to ensure folder links are valid (auto-index generates index.html for all folders)
+  const validPaths = buildValidPaths(allSourceFilenamesThatAreArticles, source, allSourceFilenamesThatAreDirectories);
   progress.log(`Built ${validPaths.size} valid paths for link validation`);
 
   const menu = await getMenu(allSourceFilenames, source, validPaths);
@@ -304,6 +335,9 @@ export async function generate({
   // Directory index cache: only stores minimal data needed for directory indices
   // Uses WeakRef-style approach - store only what's needed, clear as we go
   const dirIndexCache = new Map();
+  
+  // Track CSS files that have been copied to avoid duplicates
+  const copiedCssFiles = new Set();
 
   // Track files that were regenerated (for incremental mode stats)
   let regeneratedCount = 0;
@@ -380,12 +414,24 @@ export async function generate({
         basename: base,
       });
 
-      // Find nearest style.css or _style.css up the tree
-      let embeddedStyle = "";
+      // Find nearest style.css or _style.css up the tree and copy to output
+      let styleLink = "";
       try {
-        const css = await findStyleCss(resolve(_source, dir));
-        if (css) {
-          embeddedStyle = css;
+        const cssPath = await findStyleCss(resolve(_source, dir));
+        if (cssPath) {
+          // Calculate output path for the CSS file (mirrors source structure)
+          const cssOutputPath = cssPath.replace(source, output);
+          const cssUrlPath = '/' + cssPath.replace(source, '');
+          
+          // Copy CSS file if not already copied
+          if (!copiedCssFiles.has(cssPath)) {
+            const cssContent = await readFile(cssPath, 'utf8');
+            await outputFile(cssOutputPath, cssContent);
+            copiedCssFiles.add(cssPath);
+          }
+          
+          // Generate link tag
+          styleLink = `<link rel="stylesheet" href="${cssUrlPath}" />`;
         }
       } catch (e) {
         // ignore
@@ -409,7 +455,7 @@ export async function generate({
         "${meta}": JSON.stringify(fileMeta),
         "${transformedMetadata}": transformedMetadata,
         "${body}": body,
-        "${embeddedStyle}": embeddedStyle,
+        "${styleLink}": styleLink,
         "${searchIndex}": "[]", // Placeholder - search index written separately as JSON file
         "${footer}": footer
       };
@@ -520,7 +566,7 @@ export async function generate({
           "${title}": "Index",
           "${meta}": "{}",
           "${transformedMetadata}": "",
-          "${embeddedStyle}": "",
+          "${styleLink}": "",
           "${footer}": footer
         };
         for (const [key, value] of Object.entries(replacements)) {
@@ -585,6 +631,19 @@ export async function generate({
     await saveHashCache(source, hashCache);
   }
 
+  // Populate watch mode cache for fast single-file regeneration
+  watchModeCache.templates = templates;
+  watchModeCache.menu = menu;
+  watchModeCache.footer = footer;
+  watchModeCache.validPaths = validPaths;
+  watchModeCache.source = source;
+  watchModeCache.meta = meta;
+  watchModeCache.output = output;
+  watchModeCache.hashCache = hashCache;
+  watchModeCache.lastFullBuild = Date.now();
+  watchModeCache.isInitialized = true;
+  progress.log(`Watch cache initialized for fast single-file regeneration`);
+
   // Write error report if there were any errors
   if (errors.length > 0) {
     const errorReportPath = join(output, '_errors.log');
@@ -743,7 +802,7 @@ async function generateAutoIndices(output, directories, source, templates, menu,
           "${title}": folderDisplayName,
           "${meta}": "{}",
           "${transformedMetadata}": "",
-          "${embeddedStyle}": "",
+          "${styleLink}": "",
           "${footer}": footer
         };
         for (const [key, value] of Object.entries(replacements)) {
@@ -766,6 +825,157 @@ async function generateAutoIndices(output, directories, source, templates, menu,
   }
 }
 
+/**
+ * Regenerate a single file without scanning the entire source directory.
+ * This is much faster for watch mode - only regenerate what changed.
+ * 
+ * @param {string} changedFile - Absolute path to the file that changed
+ * @param {Object} options - Same options as generate()
+ * @returns {Promise<{success: boolean, message: string}>}
+ */
+export async function regenerateSingleFile(changedFile, {
+  _source,
+  _meta,
+  _output,
+} = {}) {
+  const startTime = Date.now();
+  const source = resolve(_source) + "/";
+  const meta = resolve(_meta);
+  const output = resolve(_output) + "/";
+  
+  // Check if this is an article file we can regenerate
+  const articleExtensions = /\.(md|txt|yml)$/;
+  if (!changedFile.match(articleExtensions)) {
+    return { success: false, message: `Not an article file: ${changedFile}` };
+  }
+  
+  // Check if cache is initialized
+  if (!watchModeCache.isInitialized) {
+    return { success: false, message: 'Cache not initialized - need full build first' };
+  }
+  
+  // Verify paths match cached paths
+  if (watchModeCache.source !== source || watchModeCache.output !== output) {
+    return { success: false, message: 'Paths changed - need full rebuild' };
+  }
+  
+  try {
+    const { templates, menu, footer, validPaths, hashCache } = watchModeCache;
+    
+    const rawBody = await readFile(changedFile, "utf8");
+    const type = parse(changedFile).ext;
+    const ext = extname(changedFile);
+    const base = basename(changedFile, ext);
+    const dir = addTrailingSlash(dirname(changedFile)).replace(source, "");
+    
+    // Calculate output paths
+    const outputFilename = changedFile
+      .replace(source, output)
+      .replace(parse(changedFile).ext, ".html");
+    const url = '/' + outputFilename.replace(output, '');
+    
+    // Title from filename
+    const title = toTitleCase(base);
+    
+    // Extract metadata
+    const fileMeta = extractMetadata(rawBody);
+    const transformedMetadata = await getTransformedMetadata(
+      dirname(changedFile),
+      fileMeta
+    );
+    
+    // Calculate the document's URL path
+    const docUrlPath = '/' + dir + base + '.html';
+    
+    // Render body
+    const body = renderFile({
+      fileContents: rawBody,
+      type,
+      dirname: dir,
+      basename: base,
+    });
+    
+    // Find CSS and copy to output
+    let styleLink = "";
+    try {
+      const cssPath = await findStyleCss(resolve(_source, dir));
+      if (cssPath) {
+        // Calculate output path for the CSS file
+        const cssOutputPath = cssPath.replace(source, output);
+        const cssUrlPath = '/' + cssPath.replace(source, '');
+        
+        // Copy CSS file (always copy in single-file mode to ensure it's up to date)
+        const cssContent = await readFile(cssPath, 'utf8');
+        await outputFile(cssOutputPath, cssContent);
+        
+        // Generate link tag
+        styleLink = `<link rel="stylesheet" href="${cssUrlPath}" />`;
+      }
+    } catch (e) {
+      // ignore
+    }
+    
+    // Get template
+    const requestedTemplateName = fileMeta && fileMeta.template;
+    const template =
+      templates[requestedTemplateName] || templates[DEFAULT_TEMPLATE_NAME];
+    
+    if (!template) {
+      return { success: false, message: `Template not found: ${requestedTemplateName || DEFAULT_TEMPLATE_NAME}` };
+    }
+    
+    // Build final HTML
+    let finalHtml = template;
+    const replacements = {
+      "${title}": title,
+      "${menu}": menu,
+      "${meta}": JSON.stringify(fileMeta),
+      "${transformedMetadata}": transformedMetadata,
+      "${body}": body,
+      "${styleLink}": styleLink,
+      "${searchIndex}": "[]",
+      "${footer}": footer
+    };
+    for (const [key, value] of Object.entries(replacements)) {
+      finalHtml = finalHtml.replace(key, value);
+    }
+    
+    // Mark broken links
+    finalHtml = markInactiveLinks(finalHtml, validPaths, docUrlPath, false);
+    
+    await outputFile(outputFilename, finalHtml);
+    
+    // JSON output
+    const jsonOutputFilename = outputFilename.replace(".html", ".json");
+    const sections = type === '.md' ? extractSections(rawBody) : [];
+    const jsonObject = {
+      name: base,
+      url,
+      contents: rawBody,
+      bodyHtml: body,
+      metadata: fileMeta,
+      sections,
+      transformedMetadata,
+    };
+    const json = JSON.stringify(jsonObject);
+    await outputFile(jsonOutputFilename, json);
+    
+    // XML output
+    const xmlOutputFilename = outputFilename.replace(".html", ".xml");
+    const xml = `<article>${o2x(jsonObject)}</article>`;
+    await outputFile(xmlOutputFilename, xml);
+    
+    // Update hash cache
+    updateHash(changedFile, rawBody, hashCache);
+    
+    const elapsed = Date.now() - startTime;
+    const shortFile = changedFile.replace(source, '');
+    return { success: true, message: `Regenerated ${shortFile} in ${elapsed}ms` };
+  } catch (e) {
+    return { success: false, message: `Error: ${e.message}` };
+  }
+}
+
 /**
  * gets { [templateName:String]:[templateBody:String] }
  * meta: full path to meta files (default-template.html, etc)

package/src/serve.js

@@ -1,10 +1,37 @@
 import express from "express";
 import watch from "node-watch";
-import { generate } from "./jobs/generate.js";
+import { generate, regenerateSingleFile, clearWatchCache } from "./jobs/generate.js";
 import { join, resolve } from "path";
 import fs from "fs";
 import { promises } from "fs";
-const { readdir, mkdir } = promises;
+import { outputFile } from "fs-extra";
+const { readdir, mkdir, readFile } = promises;
+
+// Debounce timer and lock for preventing concurrent regenerations
+let debounceTimer = null;
+let isRegenerating = false;
+const DEBOUNCE_MS = 100; // Wait 100ms after last change before regenerating
+
+/**
+ * Copy a single CSS file to the output directory
+ * @param {string} cssPath - Absolute path to the CSS file
+ * @param {string} sourceDir - Source directory root
+ * @param {string} outputDir - Output directory root
+ */
+async function copyCssFile(cssPath, sourceDir, outputDir) {
+  const startTime = Date.now();
+  const relativePath = cssPath.replace(sourceDir, '');
+  const outputPath = join(outputDir, relativePath);
+  
+  try {
+    const content = await readFile(cssPath, 'utf8');
+    await outputFile(outputPath, content);
+    const elapsed = Date.now() - startTime;
+    return { success: true, message: `Copied ${relativePath} in ${elapsed}ms` };
+  } catch (e) {
+    return { success: false, message: `Error copying CSS: ${e.message}` };
+  }
+}
 
 /**
  * Configurable serve function for CLI and library use
@@ -32,13 +59,14 @@ export async function serve({
   console.log("⏳ Generating site in background...\n");
 
   // Initial generation (use _clean flag only for initial generation)
+  // 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.\n"))
+    .then(() => console.log("\n✅ Initial generation complete. Fast single-file regeneration enabled.\n"))
     .catch((error) => console.error("Error during initial generation:", error.message));
 
   // Watch for changes
   console.log("👀 Watching for changes in:");
-  console.log("   Source:", sourceDir, "(incremental)");
+  console.log("   Source:", sourceDir, "(fast single-file mode)");
   console.log("   Meta:", metaDir, "(full rebuild)");
   console.log("\nPress Ctrl+C to stop the server\n");
   
@@ -46,6 +74,7 @@ export async function serve({
   watch(metaDir, { recursive: true, filter: /\.(js|json|css|html|md|txt|yml|yaml)$/ }, async (evt, name) => {
     console.log(`Meta files changed! Event: ${evt}, File: ${name}`);
     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.");
@@ -54,8 +83,8 @@ export async function serve({
     }
   });
 
-  // Source changes use incremental mode (only regenerate changed files)
-  // Exception: CSS changes require full rebuild since they're embedded in all pages
+  // Source changes: try fast single-file regeneration first
+  // Falls back to full rebuild for CSS, config, or if cache isn't ready
   watch(sourceDir, { 
     recursive: true, 
     filter: (f, skip) => {
@@ -65,26 +94,93 @@ export async function serve({
       return /\.(js|json|css|html|md|txt|yml|yaml)$/.test(f);
     }
   }, async (evt, name) => {
-    console.log(`Source files changed! Event: ${evt}, File: ${name}`);
+    // Skip if we're already regenerating
+    if (isRegenerating) {
+      console.log(`⏳ Skipping ${name} (regeneration in progress)`);
+      return;
+    }
     
-    // CSS files affect all pages (embedded styles), so trigger full rebuild
+    // CSS files: just copy the file (no longer embedded in HTML)
     const isCssChange = name && name.endsWith('.css');
+    // Menu/config changes need full rebuild
+    const isMenuChange = name && (name.includes('_menu') || name.includes('menu.'));
+    const isConfigChange = name && (name.includes('_config') || name.includes('.ursa'));
+    
     if (isCssChange) {
-      console.log("CSS change detected - full rebuild required...");
+      console.log(`\n🎨 CSS change detected: ${name}`);
+      isRegenerating = true;
+      try {
+        const result = await copyCssFile(name, sourceDir + '/', outputDir + '/');
+        if (result.success) {
+          console.log(`✅ ${result.message}`);
+        } else {
+          console.log(`⚠️ ${result.message}`);
+        }
+      } catch (error) {
+        console.error("Error copying CSS:", error.message);
+      } finally {
+        isRegenerating = false;
+      }
+      return;
+    }
+    
+    if (isMenuChange || isConfigChange) {
+      console.log(`\n📦 ${isMenuChange ? 'Menu' : 'Config'} change detected: ${name}`);
+      console.log("Full rebuild required...");
+      clearWatchCache();
+      isRegenerating = true;
       try {
         await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude, _clean: true });
         console.log("Regeneration complete.");
       } catch (error) {
         console.error("Error during regeneration:", error.message);
+      } finally {
+        isRegenerating = false;
       }
-    } else {
-      console.log("Incremental rebuild...");
+      return;
+    }
+    
+    // Try fast single-file regeneration for article files
+    const isArticle = name && /\.(md|txt|yml)$/.test(name);
+    if (isArticle) {
+      console.log(`\n⚡ Fast regeneration: ${name}`);
+      isRegenerating = true;
       try {
+        const result = await regenerateSingleFile(name, {
+          _source: sourceDir,
+          _meta: metaDir,
+          _output: outputDir
+        });
+        
+        if (result.success) {
+          console.log(`✅ ${result.message}`);
+          return;
+        }
+        
+        // Fall back to full rebuild if single-file failed
+        console.log(`⚠️ ${result.message}`);
+        console.log("Falling back to full rebuild...");
         await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude });
         console.log("Regeneration complete.");
       } catch (error) {
         console.error("Error during regeneration:", error.message);
+      } finally {
+        isRegenerating = false;
       }
+      return;
+    }
+    
+    // Non-article files - incremental build
+    console.log(`\n📄 Non-article change: ${name}`);
+    console.log("Running incremental rebuild...");
+    isRegenerating = true;
+    try {
+      await generate({ _source: sourceDir, _meta: metaDir, _output: outputDir, _whitelist, _exclude });
+      console.log("Regeneration complete.");
+    } catch (error) {
+      console.error("Error during regeneration:", error.message);
+    } finally {
+      isRegenerating = false;
     }
   });
 }