@kenjura/ursa 0.75.0 → 0.76.0

package/CHANGELOG.md

@@ -1,3 +1,70 @@
+# 0.77.0 (TODO)
+
+QOL:
+- When 'serve' encounters an occupied port 8080, prompt the user to find an available port instead of just exiting with an error. Will check open ports and find the closest port to 8080, then ask the user if they want to use it.
+
+Static assets revamp:
+- Meta
+  - All scripts and stylesheets referenced by a template should be bundled together into a single CSS file and a single JS file per template. Use esbuild or similar for bundling and minification. This will reduce the number of requests and ensure that all template assets are loaded together.
+- Documents
+  - style.css and script.js files should be external
+  - in serve mode, a document can have multiple style.css and script.js from multiple levels; this should be separate tags so individual ones can be invalidated
+  - in generate mode, these should be bundled together into a single CSS file and a single JS file per folder
+    - why folder? well, /foo may have style.css and script.js, and /foo/bar may have its own style.css and script.js. Every document in foo/bar includes both scripts and both stylesheets, but documents in foo only include the foo ones.
+    - it is true that foo.bundle.js and foo-bar.bundle.js will duplicate code (foo-bar is a superset of foo), but the point is that every page load has the minimum number of requests (1 CSS and 1 JS)
+  - future optimization: bundle document and meta scripts/styles together. This sounds complicated compared to the expected return
+- Bundling logic:
+  - In serve mode, minification without obfuscation is fine, as serve is often used to debug stylesheets and scripts.
+  - In generate mode, we can do full bundling and minification for optimal performance. Map files can be generated for debugging if needed.
+
+Regeneration revamp:
+- Existing logic:
+  - On first generation, save a cache of document output given some sort of hash of the source file and metadata (e.g. mtime, size, etc.)
+    - All static files (meta and document) should include a datetime or hash-based cache-buster in their query strings / filenames, so they can be invalidated as needed
+  - On subsequent generations, if the source file's hash is unchanged, skip regeneration and reuse the existing output file. (Note: this doesn't handle cases where the statis files changed and the document didn't; see below)
+  - Push a notification to the client when a file is regenerated, so the client can update the page if it's currently being viewed
+- New logic is as above, plus: (some of this is partially complete, but these are the complete requirements)
+  - When any file being watched is changed, determine the list of affected files. For instance:
+    - A normal document will obviously invalidate that exact document.
+    - Special Ursa static files (menu.md, style.css, and script.js) are inherited by all documents in the current folder and all subfolders, so they will invalidate all documents in the current folder and all subfolders.
+    - Meta static files:
+      - A template file in meta will invalidate all documents that use that template.
+      - A stylesheet or script file in meta will invalidate all documents that inherit from that meta (which is probably everything).
+    - All other static files in the docroot (assuming they're linked at all by any document) should be invalidated thus:
+      - Calculate a new hash for the static file
+      - Find all documents that reference that static file
+      - Regenerate the html (even if the source md/mdx/txt file is unchanged) for those documents to update the cache-busting query string for the static file reference
+- This should catch all the various edge cases that previously required restarting the server or doing a full regeneration.
+
+
+Top Menu improvements:
+- When a submenu overflows the available viewport height, it should become scrollable instead of overflowing off the screen. This can be achieved with CSS by setting a max-height and overflow-y: auto on the submenu container.
+    
+New Widgets:
+- Suggested Content
+  - A new left-side widget that shows a list of suggested content based on the current page. Categories of suggested content:
+    - Content you frequently view (uses localStorage to track page views and show most viewed content)
+    - Future ideas:
+      - LLM-guided suggestions based on frequently viewed content, suggested related documents you haven't viewed yet, etc.
+
+Bugs:
+- [ ] When using menu.md with auto-generation, the top menu's Home href is "//index.html" instead of "/index.html". On localhost, this ends up working fine, but on https://realdomain.com, this loads https://index.html which obviously doesn't work. The current logic seems to prefer absolute URLs, so in this case, the url for home should be "/index.html" (not double slash).
+- [ ] Site style.css is not present on auto-generated index pages
+  - Regeneration issues:
+    - Create a power, that power page now exists. But powers.json doesn't have it.
+
+# 0.76.0
+2026-02-11
+
+- **New Feature: Recent Activity widget.** A new topbar widget shows the 10 most recently modified documents in the docroot, sorted by modification date (most recent first). The widget appears on the left side of the top nav (to the right of the home icon) and is open by default.
+  - Recent activity data is collected during the generate phase by stat-ing each article file, then written to `public/recent-activity.json`.
+  - In serve/dev mode, the recent activity list is built during background cache initialization and updated live when article files are changed.
+  - The single-file regeneration path (`regenerateSingleFile`) also updates the recent activity JSON incrementally.
+- **Widget system improvements:**
+  - All widgets now have a close (✕) button in the upper-right corner of their panel header. Clicking it closes the widget and deselects the corresponding icon in the top bar.
+  - Widget open/closed state is now persisted in localStorage. Widgets that were open will remain open after a page reload, and widgets that were closed will remain closed. Widgets with no saved state fall back to their default (Recent Activity defaults to open; others default to closed).
+  - The widget system now supports both left-side and right-side widget panels, which operate independently (one widget per side can be open at a time).
+
 # 0.75.0
 2026-02-10
 

package/meta/default-template.html

@@ -10,7 +10,14 @@
 
 <body data-template-id="default">
     <nav id="nav-global">
-        <button class="menu-button" aria-label="Menu">☰</button>
+        <div class="nav-left-controls">
+            <button class="menu-button" aria-label="Menu">☰</button>
+            <div class="widget-bar widget-bar-left">
+                <button class="widget-button" data-widget="recent-activity" data-widget-side="left" aria-label="Recent Activity" title="Recent Activity">
+                    <span class="widget-icon">🕒</span>
+                </button>
+            </div>
+        </div>
 
         <div class="nav-center">
             <nav id="nav-main-top">
@@ -37,15 +44,40 @@
         </div>
     </nav>
 
-    <!-- Widget dropdown panel (shared by all widgets) -->
+    <!-- Widget dropdown panel for LEFT-side widgets -->
+    <div id="widget-dropdown-left" class="widget-dropdown widget-dropdown-left hidden">
+        <div id="widget-content-recent-activity" class="widget-content" data-widget="recent-activity">
+            <div class="widget-header">
+                <span class="widget-header-title">Recent Activity</span>
+                <button class="widget-close-btn" aria-label="Close">✕</button>
+            </div>
+            <div class="recent-activity-list">
+                <!-- Populated by JavaScript -->
+            </div>
+        </div>
+    </div>
+
+    <!-- Widget dropdown panel for RIGHT-side widgets -->
     <div id="widget-dropdown" class="widget-dropdown hidden">
         <div id="widget-content-toc" class="widget-content" data-widget="toc">
+            <div class="widget-header">
+                <span class="widget-header-title">Table of Contents</span>
+                <button class="widget-close-btn" aria-label="Close">✕</button>
+            </div>
             <!-- TOC will be generated by JavaScript -->
         </div>
         <div id="widget-content-search" class="widget-content" data-widget="search">
+            <div class="widget-header">
+                <span class="widget-header-title">Search</span>
+                <button class="widget-close-btn" aria-label="Close">✕</button>
+            </div>
             <!-- Search input + results placed here by JS -->
         </div>
         <div id="widget-content-profile" class="widget-content" data-widget="profile">
+            <div class="widget-header">
+                <span class="widget-header-title">Profile</span>
+                <button class="widget-close-btn" aria-label="Close">✕</button>
+            </div>
             <div class="widget-profile-placeholder">
                 <span class="widget-profile-avatar">👤</span>
                 <p>Sign in to access your profile</p>

package/meta/default.css

@@ -72,12 +72,19 @@ nav#nav-global {
     background: none;
     border: none;
     cursor: pointer;
-    justify-self: start;
   }
   button.menu-button:hover {
     opacity: 0.7;
   }
 
+  /* Left controls: menu button + left-side widgets */
+  .nav-left-controls {
+    display: flex;
+    align-items: center;
+    justify-self: start;
+    gap: 0;
+  }
+
   /* Center container for search and top menu */
   .nav-center {
     width: calc(var(--article-width) + 38px);
@@ -128,7 +135,7 @@ nav#nav-global {
 
 /* ==========================================
    WIDGET SYSTEM STYLES
-   Right-side nav widgets (TOC, Search, Profile)
+   Nav widgets (TOC, Search, Profile, Recent Activity)
    ========================================== */
 
 /* Widget bar in the nav right column */
@@ -174,7 +181,7 @@ nav#nav-global .nav-right-controls {
   pointer-events: none;
 }
 
-/* Widget dropdown panel */
+/* Widget dropdown panel (right-side, default) */
 .widget-dropdown {
   position: fixed;
   top: var(--global-nav-height);
@@ -190,10 +197,54 @@ nav#nav-global .nav-right-controls {
   transition: opacity 0.15s ease;
 }
 
+/* Widget dropdown panel (left-side) */
+.widget-dropdown.widget-dropdown-left {
+  right: auto;
+  left: 0;
+  border-left: none;
+  border-right: 1px solid var(--widget-border);
+  box-shadow: 2px 4px 12px rgba(0, 0, 0, 0.2);
+}
+
 .widget-dropdown.hidden {
   display: none;
 }
 
+/* Widget header with title and close button */
+.widget-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--widget-border);
+}
+
+.widget-header-title {
+  font-weight: 600;
+  font-size: 0.85rem;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  opacity: 0.7;
+}
+
+.widget-close-btn {
+  background: none;
+  border: none;
+  color: var(--text-color);
+  font-size: 1rem;
+  cursor: pointer;
+  opacity: 0.5;
+  padding: 4px 8px;
+  line-height: 1;
+  border-radius: 3px;
+  transition: opacity 0.15s ease, background-color 0.15s ease;
+}
+
+.widget-close-btn:hover {
+  opacity: 1;
+  background-color: rgba(128, 128, 128, 0.2);
+}
+
 /* Widget content panels — only the active one is visible */
 .widget-content {
   display: none;
@@ -374,6 +425,68 @@ nav#nav-global .nav-right-controls {
   font-style: italic;
 }
 
+/* --- Recent Activity Widget --- */
+.recent-activity-list {
+  padding: 0;
+}
+
+.recent-activity-loading,
+.recent-activity-empty {
+  padding: 1.5rem 1rem;
+  text-align: center;
+  color: var(--text-color);
+  opacity: 0.6;
+  font-style: italic;
+  font-size: 0.85rem;
+}
+
+.recent-activity-items {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.recent-activity-item {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.75rem;
+  padding: 0.5rem 0.75rem;
+  border-bottom: 1px solid var(--widget-border);
+  transition: background-color 0.15s ease;
+}
+
+.recent-activity-item:last-child {
+  border-bottom: none;
+}
+
+.recent-activity-item:hover {
+  background-color: rgba(128, 128, 128, 0.1);
+}
+
+.recent-activity-link {
+  color: var(--text-color);
+  text-decoration: none;
+  font-size: 0.9rem;
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.recent-activity-link:hover {
+  text-decoration: underline;
+}
+
+.recent-activity-time {
+  font-size: 0.75rem;
+  color: var(--text-color);
+  opacity: 0.5;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
 /* Search functionality styles */
 .search-results {
   position: fixed;

package/meta/widgets.js

@@ -1,23 +1,65 @@
 /**
- * Widget system for the top nav right-side panel.
+ * Widget system for the top nav panel.
  * 
  * Widgets appear as icon buttons in the nav bar. Clicking a button toggles a
- * dropdown panel anchored to the right side below the nav. Only one widget can
- * be open at a time.
+ * dropdown panel below the nav. Left-side and right-side widgets have separate
+ * dropdown panels. One widget can be open per side at a time.
  * 
- * Built-in widgets: TOC, Search, Profile
+ * Widget state (open/closed) is persisted in localStorage so it survives page reloads.
+ * 
+ * Built-in widgets:
+ *   Left: Recent Activity (open by default)
+ *   Right: TOC, Search, Profile
  */
 class WidgetManager {
   constructor() {
-    this.dropdown = document.getElementById('widget-dropdown');
+    this.dropdownRight = document.getElementById('widget-dropdown');
+    this.dropdownLeft = document.getElementById('widget-dropdown-left');
     this.buttons = document.querySelectorAll('.widget-button[data-widget]');
-    this.activeWidget = null;
+    this.activeRight = null;
+    this.activeLeft = null;
+
+    // Widgets that default to open on first visit
+    this.defaultOpen = new Set(['recent-activity']);
     
-    if (!this.dropdown || this.buttons.length === 0) return;
+    if (this.buttons.length === 0) return;
     
     this.init();
   }
   
+  /**
+   * Get the side (left/right) for a widget based on its button's data-widget-side attribute
+   */
+  getSide(widgetName) {
+    const btn = document.querySelector(`.widget-button[data-widget="${widgetName}"]`);
+    return btn?.dataset.widgetSide === 'left' ? 'left' : 'right';
+  }
+  
+  /**
+   * Get the dropdown element for a given side
+   */
+  getDropdown(side) {
+    return side === 'left' ? this.dropdownLeft : this.dropdownRight;
+  }
+  
+  /**
+   * Get the active widget name for a given side
+   */
+  getActive(side) {
+    return side === 'left' ? this.activeLeft : this.activeRight;
+  }
+  
+  /**
+   * Set the active widget name for a given side
+   */
+  setActive(side, widgetName) {
+    if (side === 'left') {
+      this.activeLeft = widgetName;
+    } else {
+      this.activeRight = widgetName;
+    }
+  }
+
   init() {
     // Bind button clicks
     this.buttons.forEach(btn => {
@@ -28,32 +70,92 @@ class WidgetManager {
       });
     });
     
+    // Bind close buttons inside widget headers
+    document.querySelectorAll('.widget-close-btn').forEach(closeBtn => {
+      closeBtn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const widgetContent = closeBtn.closest('.widget-content');
+        if (widgetContent) {
+          const widgetName = widgetContent.dataset.widget;
+          this.close(this.getSide(widgetName));
+        }
+      });
+    });
+    
     // Close on outside click
     document.addEventListener('click', (e) => {
-      if (this.activeWidget && 
-          !this.dropdown.contains(e.target) &&
+      // Close right-side widget if click is outside
+      if (this.activeRight && this.dropdownRight &&
+          !this.dropdownRight.contains(e.target) &&
           !e.target.closest('.widget-button')) {
-        this.close();
+        this.close('right');
+      }
+      // Close left-side widget if click is outside
+      if (this.activeLeft && this.dropdownLeft &&
+          !this.dropdownLeft.contains(e.target) &&
+          !e.target.closest('.widget-button')) {
+        this.close('left');
       }
     });
     
     // Close on Escape
     document.addEventListener('keydown', (e) => {
-      if (e.key === 'Escape' && this.activeWidget) {
-        this.close();
+      if (e.key === 'Escape') {
+        if (this.activeRight) this.close('right');
+        if (this.activeLeft) this.close('left');
       }
     });
 
     // Initialize search widget content
     this.initSearchWidget();
+    
+    // Initialize recent activity widget
+    this.initRecentActivityWidget();
+
+    // Restore saved widget states from localStorage
+    this.restoreState();
   }
   
   /**
-   * Toggle a widget open/closed. If a different widget is open, switch to the new one.
+   * Save widget open/closed state to localStorage
+   */
+  saveState(widgetName, isOpen) {
+    try {
+      const key = `ursa-widget-${widgetName}`;
+      localStorage.setItem(key, isOpen ? 'open' : 'closed');
+    } catch (e) { /* localStorage not available */ }
+  }
+  
+  /**
+   * Restore widget states from localStorage. 
+   * For widgets with no saved state, use their default (defaultOpen set).
+   */
+  restoreState() {
+    // Gather all widget names
+    const widgetNames = new Set();
+    this.buttons.forEach(btn => widgetNames.add(btn.dataset.widget));
+    
+    for (const widgetName of widgetNames) {
+      const key = `ursa-widget-${widgetName}`;
+      let saved;
+      try {
+        saved = localStorage.getItem(key);
+      } catch (e) { /* localStorage not available */ }
+      
+      const shouldOpen = saved === 'open' || (saved === null && this.defaultOpen.has(widgetName));
+      if (shouldOpen) {
+        this.open(widgetName);
+      }
+    }
+  }
+  
+  /**
+   * Toggle a widget open/closed.
    */
   toggle(widgetName) {
-    if (this.activeWidget === widgetName) {
-      this.close();
+    const side = this.getSide(widgetName);
+    if (this.getActive(side) === widgetName) {
+      this.close(side);
       return;
     }
     
@@ -64,54 +166,80 @@ class WidgetManager {
    * Open a specific widget panel.
    */
   open(widgetName) {
-    // Close any open widget first
-    if (this.activeWidget) {
-      this.deactivateContent(this.activeWidget);
+    const side = this.getSide(widgetName);
+    const dropdown = this.getDropdown(side);
+    if (!dropdown) return;
+    
+    // Close any open widget on the same side first
+    const currentActive = this.getActive(side);
+    if (currentActive) {
+      this.deactivateContent(currentActive);
+      // Save the closed widget's state
+      this.saveState(currentActive, false);
     }
     
-    this.activeWidget = widgetName;
+    this.setActive(side, widgetName);
     
     // Show dropdown
-    this.dropdown.classList.remove('hidden');
-    this.dropdown.dataset.activeWidget = widgetName;
+    dropdown.classList.remove('hidden');
+    dropdown.dataset.activeWidget = widgetName;
     
     // Show the correct content panel
     this.activateContent(widgetName);
     
-    // Update button states
+    // Update button states (only for this side's buttons)
     this.buttons.forEach(btn => {
-      btn.classList.toggle('active', btn.dataset.widget === widgetName);
+      if (this.getSide(btn.dataset.widget) === side) {
+        btn.classList.toggle('active', btn.dataset.widget === widgetName);
+      }
     });
 
+    // Save state
+    this.saveState(widgetName, true);
+
     // Fire event for other scripts to listen to
-    document.dispatchEvent(new CustomEvent('widget-opened', { detail: { widget: widgetName } }));
+    document.dispatchEvent(new CustomEvent('widget-opened', { detail: { widget: widgetName, side } }));
   }
   
   /**
-   * Close the currently open widget.
+   * Close the currently open widget on a given side.
    */
-  close() {
-    if (!this.activeWidget) return;
+  close(side) {
+    const active = this.getActive(side);
+    if (!active) return;
     
-    const closing = this.activeWidget;
-    this.deactivateContent(closing);
+    const dropdown = this.getDropdown(side);
+    this.deactivateContent(active);
     
-    this.activeWidget = null;
-    this.dropdown.classList.add('hidden');
-    delete this.dropdown.dataset.activeWidget;
+    // Save state
+    this.saveState(active, false);
+    
+    this.setActive(side, null);
+    if (dropdown) {
+      dropdown.classList.add('hidden');
+      delete dropdown.dataset.activeWidget;
+    }
     
-    // Update button states
-    this.buttons.forEach(btn => btn.classList.remove('active'));
+    // Update button states for this side
+    this.buttons.forEach(btn => {
+      if (this.getSide(btn.dataset.widget) === side) {
+        btn.classList.remove('active');
+      }
+    });
     
     // Fire event
-    document.dispatchEvent(new CustomEvent('widget-closed', { detail: { widget: closing } }));
+    document.dispatchEvent(new CustomEvent('widget-closed', { detail: { widget: active, side } }));
   }
   
   /**
    * Show a widget's content panel.
    */
   activateContent(widgetName) {
-    const content = this.dropdown.querySelector(`.widget-content[data-widget="${widgetName}"]`);
+    const side = this.getSide(widgetName);
+    const dropdown = this.getDropdown(side);
+    if (!dropdown) return;
+
+    const content = dropdown.querySelector(`.widget-content[data-widget="${widgetName}"]`);
     if (content) {
       content.classList.add('active');
     }
@@ -126,7 +254,11 @@ class WidgetManager {
    * Hide a widget's content panel.
    */
   deactivateContent(widgetName) {
-    const content = this.dropdown.querySelector(`.widget-content[data-widget="${widgetName}"]`);
+    const side = this.getSide(widgetName);
+    const dropdown = this.getDropdown(side);
+    if (!dropdown) return;
+
+    const content = dropdown.querySelector(`.widget-content[data-widget="${widgetName}"]`);
     if (content) {
       content.classList.remove('active');
     }
@@ -368,6 +500,73 @@ class WidgetManager {
   deactivateSearch() {
     // Keep the search query so user can re-open and see results
   }
+
+  /**
+   * Initialize the Recent Activity widget — fetch data and render the list.
+   */
+  initRecentActivityWidget() {
+    const container = document.querySelector('.recent-activity-list');
+    if (!container) return;
+
+    container.innerHTML = '<div class="recent-activity-loading">Loading...</div>';
+
+    fetch('/public/recent-activity.json')
+      .then(res => {
+        if (!res.ok) throw new Error('Not found');
+        return res.json();
+      })
+      .then(items => {
+        container.innerHTML = '';
+        if (!items || items.length === 0) {
+          container.innerHTML = '<div class="recent-activity-empty">No recent activity</div>';
+          return;
+        }
+        const ul = document.createElement('ul');
+        ul.className = 'recent-activity-items';
+        for (const item of items) {
+          const li = document.createElement('li');
+          li.className = 'recent-activity-item';
+          const a = document.createElement('a');
+          a.href = item.url;
+          a.textContent = item.title || 'Untitled';
+          a.className = 'recent-activity-link';
+          const time = document.createElement('span');
+          time.className = 'recent-activity-time';
+          time.textContent = this.formatRelativeTime(item.mtime);
+          time.title = new Date(item.mtime).toLocaleString();
+          li.appendChild(a);
+          li.appendChild(time);
+          ul.appendChild(li);
+        }
+        container.appendChild(ul);
+      })
+      .catch(() => {
+        container.innerHTML = '<div class="recent-activity-empty">Recent activity unavailable</div>';
+      });
+  }
+
+  /**
+   * Format a timestamp into a human-readable relative time string.
+   */
+  formatRelativeTime(mtimeMs) {
+    const now = Date.now();
+    const diff = now - mtimeMs;
+    const seconds = Math.floor(diff / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const weeks = Math.floor(days / 7);
+    const months = Math.floor(days / 30);
+    const years = Math.floor(days / 365);
+
+    if (seconds < 60) return 'just now';
+    if (minutes < 60) return `${minutes}m ago`;
+    if (hours < 24) return `${hours}h ago`;
+    if (days < 7) return `${days}d ago`;
+    if (weeks < 5) return `${weeks}w ago`;
+    if (months < 12) return `${months}mo ago`;
+    return `${years}y ago`;
+  }
 }
 
 // Initialize widgets when DOM is ready

package/package.json

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

package/src/dev.js

@@ -20,7 +20,7 @@ const { readFile, readdir, stat, mkdir } = promises;
 // Import helper modules
 import { renderFileAsync } from "./helper/fileRenderer.js";
 import { findStyleCss } from "./helper/findStyleCss.js";
-import { findScriptJs } from "./helper/findScriptJs.js";
+import { findAllScriptJs } from "./helper/findScriptJs.js";
 import { extractMetadata, getAutoIndexConfig, isMetadataOnly } from "./helper/metadataExtractor.js";
 import { injectFrontmatterTable } from "./helper/frontmatterTable.js";
 import { buildValidPaths, markInactiveLinks, resolveRelativeUrls } from "./helper/linkValidator.js";
@@ -58,6 +58,7 @@ const devState = {
   footer: null,
   fullTextIndex: null,
   searchIndex: null,
+  recentActivity: null,
   
   // Path → nearest menu.md mapping
   menuPathMap: new Map(),
@@ -282,19 +283,19 @@ async function findNearestStyle(dirPath) {
 }
 
 /**
- * Find the nearest script.js
+ * Find all script.js files from docroot to dirPath
  */
-async function findNearestScript(dirPath) {
-  const { scriptPathMap } = devState;
+async function findAllScripts(dirPath) {
+  const { scriptPathMap, source } = devState;
   
   // Check cache first
   if (scriptPathMap.has(dirPath)) {
     return scriptPathMap.get(dirPath);
   }
   
-  const scriptPath = await findScriptJs(dirPath);
-  scriptPathMap.set(dirPath, scriptPath);
-  return scriptPath;
+  const scriptPaths = await findAllScriptJs(dirPath, source);
+  scriptPathMap.set(dirPath, scriptPaths);
+  return scriptPaths;
 }
 
 /**
@@ -457,15 +458,17 @@ async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath) {
     // Ignore CSS errors
   }
   
-  // Find nearest script.js and inline its contents
+  // Find all script.js files from docroot to current dir and inline their contents
   let customScript = "";
   try {
     const scriptDir = sourcePath ? dirname(sourcePath) : source;
-    const scriptPath = await findNearestScript(scriptDir);
-    if (scriptPath) {
+    const scriptPaths = await findAllScripts(scriptDir);
+    const scriptTags = [];
+    for (const scriptPath of scriptPaths) {
       const scriptContent = await readFile(scriptPath, 'utf8');
-      customScript = `<script>\n${scriptContent}\n</script>`;
+      scriptTags.push(`<script>\n${scriptContent}\n</script>`);
     }
+    customScript = scriptTags.join('\n');
   } catch (e) {
     // Ignore script errors
   }
@@ -635,6 +638,7 @@ async function buildBackgroundCaches() {
     
     const searchIndex = [];
     const fullTextDocs = [];
+    const recentActivity = [];
     
     for (const article of allArticles) {
       try {
@@ -657,6 +661,16 @@ async function buildBackgroundCaches() {
           title,
           content
         });
+
+        // Collect mtime for recent activity
+        try {
+          const articleStat = await stat(article);
+          recentActivity.push({
+            title,
+            url: relativePath.startsWith('/') ? relativePath : '/' + relativePath,
+            mtime: articleStat.mtimeMs
+          });
+        } catch (e) {}
       } catch (e) {}
     }
     
@@ -664,6 +678,10 @@ async function buildBackgroundCaches() {
     devState.fullTextIndex = buildFullTextIndex(fullTextDocs);
     devState.searchIndex = searchIndex;
     
+    // Build recent activity (top 10 by mtime)
+    recentActivity.sort((a, b) => b.mtime - a.mtime);
+    devState.recentActivity = recentActivity.slice(0, 10);
+    
     // Write search index files
     const publicDir = join(output, 'public');
     await mkdir(publicDir, { recursive: true });
@@ -671,6 +689,7 @@ async function buildBackgroundCaches() {
     await outputFile(join(publicDir, 'search-index.json'), JSON.stringify(searchIndex));
     await outputFile(join(publicDir, 'fulltext-index.json'), JSON.stringify(devState.fullTextIndex));
     await outputFile(join(publicDir, 'menu-data.json'), JSON.stringify(devState.menuData));
+    await outputFile(join(publicDir, 'recent-activity.json'), JSON.stringify(devState.recentActivity));
     
     devState.searchReady = true;
     console.log('✅ Search index ready');
@@ -956,6 +975,33 @@ export async function dev({
       console.log(`✅ MDX caches cleared for component change: ${name}`);
     }
     
+    // Update recent activity for article changes
+    const isArticleChange = name && /\.(md|mdx|txt|yml)$/.test(name);
+    if (isArticleChange && devState.recentActivity) {
+      try {
+        const articleStat = await stat(name);
+        const ext = extname(name);
+        const base = basename(name, ext);
+        const relativePath = name.replace(sourceDir + '/', '').replace(/\.(md|mdx|txt|yml)$/, '.html');
+        const titleBase = (base === 'index' || base === 'home') ? basename(dirname(name)) : base;
+        const title = toTitleCase(titleBase || base);
+        const url = relativePath.startsWith('/') ? relativePath : '/' + relativePath;
+        
+        // Remove old entry for this URL, add updated one
+        let activity = devState.recentActivity.filter(r => r.url !== url);
+        activity.push({ title, url, mtime: articleStat.mtimeMs });
+        activity.sort((a, b) => b.mtime - a.mtime);
+        devState.recentActivity = activity.slice(0, 10);
+        
+        // Write updated file
+        const publicDir = join(devState.output, 'public');
+        await outputFile(join(publicDir, 'recent-activity.json'), JSON.stringify(devState.recentActivity));
+        console.log(`✅ Recent activity updated for ${name}`);
+      } catch (e) {
+        // ignore
+      }
+    }
+    
     // Broadcast reload
     broadcast('reload', { file: name });
   });

package/src/helper/build/autoIndex.js

@@ -4,7 +4,7 @@ import { readdir, readFile } from "fs/promises";
 import { basename, dirname, extname, join } from "path";
 import { outputFile } from "fs-extra";
 import { findStyleCss } from "../findStyleCss.js";
-import { findScriptJs } from "../findScriptJs.js";
+import { findAllScriptJs } from "../findScriptJs.js";
 import { toTitleCase } from "./titleCase.js";
 import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
 import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
@@ -370,15 +370,17 @@ export async function generateAutoIndices(output, directories, source, templates
           // ignore CSS lookup errors
         }
         
-        // Find nearest script.js for this directory
+        // Find all script.js files from docroot to this directory
         let customScript = "";
         try {
           const sourceDir = dir.replace(outputNorm, sourceNorm);
-          const scriptPath = await findScriptJs(sourceDir);
-          if (scriptPath) {
+          const scriptPaths = await findAllScriptJs(sourceDir, sourceNorm);
+          const scriptTags = [];
+          for (const scriptPath of scriptPaths) {
             const scriptContent = await readFile(scriptPath, 'utf8');
-            customScript = `<script>\n${scriptContent}\n</script>`;
+            scriptTags.push(`<script>\n${scriptContent}\n</script>`);
           }
+          customScript = scriptTags.join('\n');
         } catch (e) {
           // ignore script lookup errors
         }

package/src/helper/findScriptJs.js

@@ -24,3 +24,32 @@ export async function findScriptJs(startDir, names = ["script.js", "_script.js"]
   }
   return null;
 }
+
+/**
+ * Find ALL script.js or _script.js files from the docroot down to startDir.
+ * Walks up from startDir to docroot collecting all matches, then returns them
+ * sorted from shortest path (closest to docroot) to longest (closest to startDir).
+ * @param {string} startDir - Directory to start searching from (deepest)
+ * @param {string} docroot - The root directory to stop at (shallowest)
+ * @param {string[]} [names=["script.js", "_script.js"]] - Filenames to look for
+ * @returns {Promise<string[]>} Array of script file paths, ordered from shallowest to deepest
+ */
+export async function findAllScriptJs(startDir, docroot, names = ["script.js", "_script.js"]) {
+  const found = [];
+  let dir = resolve(startDir);
+  const base = resolve(docroot);
+  while (true) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) {
+        found.push(candidate);
+        break; // Only one match per directory (prefer script.js over _script.js)
+      }
+    }
+    if (dir === base || dir === dirname(dir)) break;
+    dir = dirname(dir);
+  }
+  // Sort from shortest path (docroot) to longest (startDir)
+  found.sort((a, b) => a.length - b.length);
+  return found;
+}

package/src/jobs/generate.js

@@ -27,7 +27,7 @@ import { getAndIncrementBuildId } from "../helper/ursaConfig.js";
 import { extractSections } from "../helper/sectionExtractor.js";
 import { renderFile, renderFileAsync, terminateParserPool } from "../helper/fileRenderer.js";
 import { findStyleCss } from "../helper/findStyleCss.js";
-import { findScriptJs } from "../helper/findScriptJs.js";
+import { findScriptJs, findAllScriptJs } from "../helper/findScriptJs.js";
 import { buildFullTextIndex, buildIncrementalIndex, loadIndexCache, saveIndexCache } from "../helper/fullTextIndex.js";
 import { copy as copyDir, emptyDir, outputFile } from "fs-extra";
 import { basename, dirname, extname, join, parse, resolve } from "path";
@@ -313,6 +313,8 @@ export async function generate({
   const searchIndex = [];
   // Full-text index: collect documents for word-to-document mapping
   const fullTextDocs = [];
+  // Recent activity: collect {title, url, mtime} for all articles, keep top 10 by mtime
+  const recentActivity = [];
   // Track paths of documents that were regenerated (for incremental index updates)
   const changedPaths = new Set();
   // Directory index cache: only stores minimal data needed for directory indices
@@ -481,6 +483,18 @@ export async function generate({
         title: title,
         content: rawBody
       });
+
+      // Collect mtime for recent activity tracking
+      try {
+        const fileStat = await stat(file);
+        recentActivity.push({
+          title: title,
+          url: searchUrl,
+          mtime: fileStat.mtimeMs
+        });
+      } catch (e) {
+        // ignore stat errors
+      }
       
       // Check if a corresponding .html file already exists in source directory
       const outputHtmlRelative = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
@@ -614,21 +628,22 @@ export async function generate({
         console.error(e);
       }
 
-      // Find nearest script.js or _script.js up the tree and inline its contents
+      // Find all script.js or _script.js files from docroot to current dir and inline their contents
       // Use cache to avoid repeated filesystem walks for same directory
       let customScript = "";
       try {
         const dirKey = (dir === "/" || dir === "") ? _source : resolve(_source, dir);
-        let scriptPath = scriptPathCache.get(dirKey);
-        if (scriptPath === undefined) {
-          scriptPath = await findScriptJs(dirKey);
-          scriptPathCache.set(dirKey, scriptPath); // Cache null results too
+        let scriptPaths = scriptPathCache.get(dirKey);
+        if (scriptPaths === undefined) {
+          scriptPaths = await findAllScriptJs(dirKey, _source);
+          scriptPathCache.set(dirKey, scriptPaths); // Cache empty arrays too
         }
-        if (scriptPath) {
+        const scriptTags = [];
+        for (const scriptPath of scriptPaths) {
           const scriptContent = await readFile(scriptPath, 'utf8');
-          // Inline the script content in a script tag
-          customScript = `<script>\n${scriptContent}\n</script>`;
+          scriptTags.push(`<script>\n${scriptContent}\n</script>`);
         }
+        customScript = scriptTags.join('\n');
       } catch (e) {
         // ignore
         console.error(e);
@@ -807,6 +822,17 @@ export async function generate({
     profiler.endPhase('Write search index');
   }
 
+  // Phase: Write recent activity data
+  profiler.startPhase('Write recent activity');
+  progress.startTimer('Recent activity');
+  // Sort by mtime descending, keep top 10
+  recentActivity.sort((a, b) => b.mtime - a.mtime);
+  const top10 = recentActivity.slice(0, 10);
+  const recentActivityPath = join(output, 'public', 'recent-activity.json');
+  await outputFile(recentActivityPath, JSON.stringify(top10));
+  progress.done('Recent activity', `${top10.length} entries [${progress.stopTimer('Recent activity')}]`);
+  profiler.endPhase('Write recent activity');
+
   // Phase: Write menu data
   profiler.startPhase('Write menu data');
   progress.startTimer('Menu data');
@@ -1209,15 +1235,17 @@ export async function regenerateSingleFile(changedFile, {
       return { success: false, message: `Template not found: ${requestedTemplateName || DEFAULT_TEMPLATE_NAME}` };
     }
     
-    // Find nearest script.js or _script.js and inline its contents
+    // Find all script.js or _script.js files from docroot to current dir and inline their contents
     let customScript = "";
     try {
       const dirKey = (dir === "/" || dir === "") ? _source : resolve(_source, dir);
-      const scriptPath = await findScriptJs(dirKey);
-      if (scriptPath) {
+      const scriptPaths = await findAllScriptJs(dirKey, _source);
+      const scriptTags = [];
+      for (const scriptPath of scriptPaths) {
         const scriptContent = await readFile(scriptPath, 'utf8');
-        customScript = `<script>\n${scriptContent}\n</script>`;
+        scriptTags.push(`<script>\n${scriptContent}\n</script>`);
       }
+      customScript = scriptTags.join('\n');
     } catch (e) {
       // ignore
     }
@@ -1296,6 +1324,27 @@ export async function regenerateSingleFile(changedFile, {
     // Update hash cache
     updateHash(changedFile, rawBody, hashCache);
     
+    // Update recent-activity.json with this file's new mtime
+    try {
+      const fileStat = await stat(changedFile);
+      const recentActivityPath = join(output, 'public', 'recent-activity.json');
+      let recentActivity = [];
+      try {
+        const existing = await readFile(recentActivityPath, 'utf8');
+        recentActivity = JSON.parse(existing);
+      } catch (e) { /* no existing file, start fresh */ }
+      // Remove old entry for this URL if present
+      recentActivity = recentActivity.filter(r => r.url !== url);
+      // Add updated entry
+      recentActivity.push({ title, url, mtime: fileStat.mtimeMs });
+      // Sort by mtime descending, keep top 10
+      recentActivity.sort((a, b) => b.mtime - a.mtime);
+      recentActivity = recentActivity.slice(0, 10);
+      await outputFile(recentActivityPath, JSON.stringify(recentActivity));
+    } catch (e) {
+      // ignore recent activity update errors
+    }
+    
     const elapsed = Date.now() - startTime;
     const shortFile = changedFile.replace(source, '');
     return { success: true, message: `Regenerated ${shortFile} in ${elapsed}ms` };