@kenjura/ursa 0.77.0 → 0.79.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# 0.79.0
+2026-02-14
+
+- Menu fixes:
+  - Zero-item submenus will no longer be hidden if they have subfolders with one+ item
+  - Bug fix for missing menu items
+  - Level 2+ menus now have overflow:scroll (vertical only)
+
+# 0.78.0
+2026-02-13
+
+- added release-it
+- --clean now fully deletes the .ursa cache folder and clears the output directory before generation, ensuring a completely fresh build without any stale files. Previously, --clean only ignored the cache but left existing output files in place, which could cause issues with stale auto-generated indexes and other files blocking new generation. This change provides a more robust clean build experience.
+
 # 0.77.0
 2026-02-13
 

package/README.md

@@ -66,7 +66,7 @@ Start a development server that:
 - `--port, -p` - Port for development server (default: 8080, serve command only)
 - `--whitelist, -w` - Path to whitelist file containing patterns for files to include
 - `--exclude, -e` - Folders to exclude: comma-separated paths relative to source, or path to file with one folder per line
-- `--clean` - Clear output directory and ignore cache, forcing full regeneration
+- `--clean` - Delete the `.ursa` cache folder and clear output directory, forcing full regeneration
 
 ### Whitelist File Format
 

package/meta/default.css

@@ -735,7 +735,7 @@ nav#nav-main-top .dropdown-label {
 }
 
 nav#nav-main-top .dropdown-label:hover {
-  background-color: var(--nav-top-bg);
+  background-color: rgba(255, 255, 255, 0.1);
 }
 
 nav#nav-main-top a.dropdown-label:hover {
@@ -749,14 +749,12 @@ nav#nav-main-top .flyout-indicator {
   margin-left: 8px;
 }
 
-/* Flyout menu (nested children) */
+/* Flyout menu (nested children) - uses fixed positioning to avoid clipping by parent overflow */
 nav#nav-main-top .top-menu-flyout {
   display: none;
-  position: absolute;
-  left: 100%;
-  top: -1px;
+  position: fixed;
   min-width: 200px;
-  max-height: calc(100vh - var(--global-nav-height) - 20px);
+  max-height: calc(100vh - var(--global-nav-height) - 40px);
   overflow-y: auto;
   background-color: var(--widget-bg);
   border: 1px solid var(--widget-border);
@@ -766,9 +764,10 @@ nav#nav-main-top .top-menu-flyout {
   margin: 0;
   padding: 0;
   z-index: 1006;
+  /* JS will set top/left via inline styles */
 }
 
-/* Show flyout on hover */
+/* Show flyout on hover - JS handles positioning */
 nav#nav-main-top .dropdown-item.has-flyout:hover > .top-menu-flyout {
   display: block;
 }

package/meta/menu.js

@@ -0,0 +1,898 @@
+/**
+ * Column-based menu navigation (Finder-style)
+ * 
+ * Displays 2 columns at a time, with horizontal scrolling to navigate deeper levels.
+ * Each column represents one level of the folder hierarchy.
+ * 
+ * Also supports top menu position for horizontal navigation with dropdowns.
+ * Top menu is the default; side menu is used only when explicitly set.
+ */
+document.addEventListener('DOMContentLoaded', () => {
+    const navMain = document.querySelector('nav#nav-main');
+    const navMainTop = document.querySelector('nav#nav-main-top');
+    const menuPosition = document.body.dataset.menuPosition || 'top';
+
+    // If menu position is top (default), handle differently
+    if (menuPosition === 'top') {
+        initTopMenu();
+        return;
+    }
+    
+    if (!navMain) return;
+
+    // Check for custom menu
+    const customMenuPath = document.body.dataset.customMenu;
+    const isCustomMenu = !!customMenuPath;
+
+    // State - menu data will be loaded asynchronously
+    let menuData = null;
+    let menuDataLoaded = false;
+    let menuDataLoading = false;
+    
+    // Load menu config from embedded JSON (contains openMenuItems)
+    const menuConfigScript = document.getElementById('menu-config');
+    let menuConfig = { openMenuItems: [] };
+    if (menuConfigScript) {
+        try {
+            menuConfig = JSON.parse(menuConfigScript.textContent);
+        } catch (e) {
+            console.error('Failed to parse menu config:', e);
+        }
+    }
+
+    // Column navigation state
+    let allColumns = [];           // Array of column data: [{items: [], parentPath: '', selectedPath: ''}]
+    let scrollPosition = 0;        // Which column index is the leftmost visible
+    let currentDocPath = [];       // Path segments to current document
+    let currentDocColumnIndex = 0; // Which column contains the current document
+    
+    // DOM element references (set during createMenuStructure)
+    let elements = null;
+    
+    // Constants
+    const VISIBLE_COLUMNS = 2;
+    const COLUMN_WIDTH = 130;      // Width of each column in pixels
+
+    // Helper to check if we're on mobile
+    const isMobile = () => window.matchMedia('(max-width: 800px)').matches;
+    
+    /**
+     * Load menu data from external JSON file
+     */
+    async function loadMenuData() {
+        if (menuDataLoaded || menuDataLoading) return;
+        menuDataLoading = true;
+        
+        try {
+            const menuUrl = customMenuPath || '/public/menu-data.json';
+            const response = await fetch(menuUrl);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            menuData = await response.json();
+            menuDataLoaded = true;
+            
+            initializeFromCurrentPage();
+        } catch (error) {
+            console.error('Failed to load menu data:', error);
+            menuDataLoaded = true;
+        } finally {
+            menuDataLoading = false;
+        }
+    }
+    
+    // Start loading menu data immediately
+    loadMenuData();
+
+    /**
+     * Find item by path string
+     */
+    function findItemByPath(pathString) {
+        if (!menuData) return null;
+        if (!pathString) return null;
+        
+        const segments = pathString.split('/').filter(Boolean);
+        let items = menuData;
+        let item = null;
+        
+        for (let i = 0; i < segments.length; i++) {
+            const targetPath = segments.slice(0, i + 1).join('/');
+            item = items.find(it => it.path === targetPath);
+            if (!item) return null;
+            if (item.children && i < segments.length - 1) {
+                items = item.children;
+            }
+        }
+        return item;
+    }
+
+    /**
+     * Check if an item matches the current page
+     */
+    function isCurrentPage(item) {
+        if (!item.href) return false;
+        const currentHref = window.location.pathname;
+        const normalizedItemHref = decodeURIComponent(item.href).replace(/\/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
+        const normalizedCurrentHref = decodeURIComponent(currentHref).replace(/\/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
+        return normalizedItemHref === normalizedCurrentHref;
+    }
+
+    /**
+     * Build the column structure based on current document path
+     */
+    function buildColumns() {
+        allColumns = [];
+        
+        // Always start with root column
+        allColumns.push({
+            items: menuData || [],
+            parentPath: '',
+            selectedPath: currentDocPath.length > 0 ? currentDocPath[0] : null
+        });
+        
+        // Build columns for each level of the current document path
+        let currentPathString = '';
+        for (let i = 0; i < currentDocPath.length; i++) {
+            currentPathString = currentDocPath.slice(0, i + 1).join('/');
+            const item = findItemByPath(currentPathString);
+            
+            if (item && item.children && item.children.length > 0) {
+                const nextSelectedPath = i + 1 < currentDocPath.length 
+                    ? currentDocPath.slice(0, i + 2).join('/')
+                    : null;
+                    
+                allColumns.push({
+                    items: item.children,
+                    parentPath: currentPathString,
+                    selectedPath: nextSelectedPath
+                });
+            }
+        }
+        
+        // Set current doc column index (rightmost column that contains actual content)
+        currentDocColumnIndex = allColumns.length - 1;
+        
+        // Default scroll position: show current doc column as rightmost visible
+        scrollPosition = Math.max(0, currentDocColumnIndex - VISIBLE_COLUMNS + 1);
+    }
+
+    /**
+     * Create the menu DOM structure
+     */
+    function createMenuStructure() {
+        // Clear existing content but preserve any breadcrumb/config scripts
+        const configScript = navMain.querySelector('#menu-config');
+        navMain.innerHTML = '';
+        if (configScript) {
+            navMain.appendChild(configScript);
+        }
+        
+        // Create main container
+        const container = document.createElement('div');
+        container.className = 'menu-columns-container';
+        
+        // Create columns wrapper (this scrolls)
+        const columnsWrapper = document.createElement('div');
+        columnsWrapper.className = 'menu-columns-wrapper';
+        container.appendChild(columnsWrapper);
+        
+        navMain.appendChild(container);
+        
+        // Create scroll indicator (shows when current doc is off-screen)
+        const scrollIndicator = document.createElement('div');
+        scrollIndicator.className = 'menu-scroll-indicator';
+        scrollIndicator.innerHTML = '<button class="scroll-to-current" title="Go to current page">Current →</button>';
+        scrollIndicator.style.display = 'none';
+        navMain.appendChild(scrollIndicator);
+        
+        // Create scroll buttons
+        const scrollLeft = document.createElement('button');
+        scrollLeft.className = 'menu-scroll-btn scroll-left';
+        scrollLeft.innerHTML = '‹';
+        scrollLeft.title = 'Scroll left (shallower)';
+        navMain.appendChild(scrollLeft);
+        
+        const scrollRight = document.createElement('button');
+        scrollRight.className = 'menu-scroll-btn scroll-right';
+        scrollRight.innerHTML = '›';
+        scrollRight.title = 'Scroll right (deeper)';
+        navMain.appendChild(scrollRight);
+        
+        return { container, columnsWrapper, scrollIndicator, scrollLeft, scrollRight };
+    }
+
+    /**
+     * Render all columns
+     */
+    function renderColumns() {
+        if (!elements) return;
+        
+        const { columnsWrapper } = elements;
+        columnsWrapper.innerHTML = '';
+        
+        for (let i = 0; i < allColumns.length; i++) {
+            const col = allColumns[i];
+            const columnEl = document.createElement('div');
+            columnEl.className = 'menu-column';
+            columnEl.dataset.columnIndex = i;
+            
+            const ul = document.createElement('ul');
+            ul.className = 'menu-column-list';
+            
+            for (const item of col.items) {
+                const li = document.createElement('li');
+                li.className = 'menu-column-item';
+                li.dataset.path = item.path;
+                
+                // Check if this item is selected (on path to current doc)
+                if (item.path === col.selectedPath) {
+                    li.classList.add('selected');
+                }
+                
+                // Check if this is the current page
+                if (isCurrentPage(item)) {
+                    li.classList.add('current-page');
+                }
+                
+                // Check if has children
+                if (item.hasChildren) {
+                    li.classList.add('has-children');
+                }
+                
+                // Check if this is an index file
+                if (item.isIndex) {
+                    li.classList.add('is-index');
+                }
+                
+                // Create the item content
+                const row = document.createElement('div');
+                row.className = 'menu-column-item-row';
+                
+                // Label (link if has href)
+                if (item.href) {
+                    const link = document.createElement('a');
+                    link.href = item.href;
+                    link.className = 'menu-column-label';
+                    link.textContent = item.label;
+                    row.appendChild(link);
+                } else {
+                    const span = document.createElement('span');
+                    span.className = 'menu-column-label';
+                    span.textContent = item.label;
+                    row.appendChild(span);
+                }
+                
+                // Arrow indicator for folders
+                if (item.hasChildren) {
+                    const arrow = document.createElement('span');
+                    arrow.className = 'menu-column-arrow';
+                    arrow.textContent = '›';
+                    row.appendChild(arrow);
+                }
+                
+                li.appendChild(row);
+                ul.appendChild(li);
+            }
+            
+            columnEl.appendChild(ul);
+            columnsWrapper.appendChild(columnEl);
+        }
+        
+        // Set wrapper width
+        columnsWrapper.style.width = `${allColumns.length * COLUMN_WIDTH}px`;
+    }
+
+    /**
+     * Update scroll position (with snap)
+     */
+    function updateScrollPosition() {
+        if (!elements) return;
+        
+        const { columnsWrapper, scrollIndicator, scrollLeft, scrollRight } = elements;
+        
+        // Clamp scroll position
+        const maxScroll = Math.max(0, allColumns.length - VISIBLE_COLUMNS);
+        scrollPosition = Math.max(0, Math.min(scrollPosition, maxScroll));
+        
+        // Apply transform
+        const translateX = -scrollPosition * COLUMN_WIDTH;
+        columnsWrapper.style.transform = `translateX(${translateX}px)`;
+        
+        // Update scroll button visibility
+        scrollLeft.style.opacity = scrollPosition > 0 ? '1' : '0.3';
+        scrollLeft.disabled = scrollPosition <= 0;
+        
+        const canScrollRight = scrollPosition < maxScroll;
+        scrollRight.style.opacity = canScrollRight ? '1' : '0.3';
+        scrollRight.disabled = !canScrollRight;
+        
+        // Show indicator if current doc is not visible
+        const currentDocVisible = scrollPosition <= currentDocColumnIndex && 
+                                  currentDocColumnIndex < scrollPosition + VISIBLE_COLUMNS;
+        scrollIndicator.style.display = currentDocVisible ? 'none' : 'flex';
+        
+        // Update indicator direction
+        if (!currentDocVisible) {
+            const indicatorBtn = scrollIndicator.querySelector('.scroll-to-current');
+            if (currentDocColumnIndex < scrollPosition) {
+                indicatorBtn.innerHTML = '← Current';
+            } else {
+                indicatorBtn.innerHTML = 'Current →';
+            }
+        }
+    }
+
+    /**
+     * Navigate into a folder (expand it as a new column)
+     */
+    function navigateIntoFolder(item) {
+        if (!item.hasChildren) return;
+        
+        const pathSegments = item.path.split('/').filter(Boolean);
+        currentDocPath = pathSegments;
+        
+        // Rebuild columns with this item expanded
+        buildColumns();
+        renderColumns();
+        
+        // Scroll to show the new column
+        scrollPosition = Math.max(0, allColumns.length - VISIBLE_COLUMNS);
+        updateScrollPosition();
+        
+        attachItemHandlers();
+    }
+
+    /**
+     * Attach click handlers to menu items
+     */
+    function attachItemHandlers() {
+        if (!elements) return;
+        
+        const items = elements.columnsWrapper.querySelectorAll('.menu-column-item');
+        
+        items.forEach(li => {
+            const path = li.dataset.path;
+            const item = findItemByPath(path);
+            if (!item) return;
+            
+            const row = li.querySelector('.menu-column-item-row');
+            const link = li.querySelector('a.menu-column-label');
+            
+            // For folders: clicking anywhere on the row expands
+            if (item.hasChildren) {
+                row.addEventListener('click', (e) => {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    navigateIntoFolder(item);
+                });
+                
+                // But if there's also a link, ctrl/cmd+click should still work
+                if (link) {
+                    link.addEventListener('click', (e) => {
+                        if (e.ctrlKey || e.metaKey) {
+                            // Allow normal link behavior for ctrl/cmd+click
+                            return;
+                        }
+                        e.preventDefault();
+                        e.stopPropagation();
+                        navigateIntoFolder(item);
+                    });
+                }
+            }
+            // For files: link navigates normally (no special handling needed)
+        });
+    }
+
+    /**
+     * Set up scroll event handlers
+     */
+    function setupScrollHandlers() {
+        if (!elements) return;
+        
+        const { container, scrollIndicator, scrollLeft, scrollRight } = elements;
+        
+        // Scroll button handlers
+        scrollLeft.addEventListener('click', () => {
+            scrollPosition = Math.max(0, scrollPosition - 1);
+            updateScrollPosition();
+        });
+        
+        scrollRight.addEventListener('click', () => {
+            scrollPosition = Math.min(allColumns.length - VISIBLE_COLUMNS, scrollPosition + 1);
+            updateScrollPosition();
+        });
+        
+        // Scroll to current button
+        scrollIndicator.querySelector('.scroll-to-current').addEventListener('click', () => {
+            scrollPosition = Math.max(0, currentDocColumnIndex - VISIBLE_COLUMNS + 1);
+            updateScrollPosition();
+        });
+        
+        // Trackpad/wheel horizontal scrolling with snap
+        let accumulatedDelta = 0;
+        let scrollTimeout = null;
+        
+        container.addEventListener('wheel', (e) => {
+            // Only handle horizontal scroll - let vertical scroll work normally for column scrolling
+            const isHorizontalScroll = Math.abs(e.deltaX) > Math.abs(e.deltaY);
+            
+            if (!isHorizontalScroll) {
+                // Allow vertical scrolling within columns
+                return;
+            }
+            
+            const delta = e.deltaX;
+            
+            if (Math.abs(delta) > 0) {
+                e.preventDefault();
+                
+                accumulatedDelta += delta;
+                
+                // Clear previous timeout
+                if (scrollTimeout) clearTimeout(scrollTimeout);
+                
+                // Snap after scrolling stops
+                scrollTimeout = setTimeout(() => {
+                    if (accumulatedDelta > 50) {
+                        scrollPosition = Math.min(allColumns.length - VISIBLE_COLUMNS, scrollPosition + 1);
+                    } else if (accumulatedDelta < -50) {
+                        scrollPosition = Math.max(0, scrollPosition - 1);
+                    }
+                    accumulatedDelta = 0;
+                    updateScrollPosition();
+                }, 100);
+            }
+        }, { passive: false });
+    }
+
+    /**
+     * Main render function
+     */
+    function renderMenu() {
+        if (!menuData) {
+            navMain.innerHTML = '<div class="menu-loading">Loading menu...</div>';
+            return;
+        }
+        
+        buildColumns();
+        elements = createMenuStructure();
+        renderColumns();
+        updateScrollPosition();
+        attachItemHandlers();
+        setupScrollHandlers();
+    }
+
+    /**
+     * Initialize from current page URL
+     */
+    function initializeFromCurrentPage() {
+        const currentHref = window.location.pathname;
+        let pathParts = currentHref.split('/').filter(Boolean);
+        
+        // Remove .html extension from the last part
+        if (pathParts.length > 0) {
+            pathParts[pathParts.length - 1] = pathParts[pathParts.length - 1].replace(/\.html$/, '');
+        }
+        
+        // If the last part is "index", treat it as if we're viewing the parent folder
+        if (pathParts.length > 0 && pathParts[pathParts.length - 1] === 'index') {
+            pathParts = pathParts.slice(0, -1);
+        }
+        
+        // Validate path against menu data and build currentDocPath
+        currentDocPath = [];
+        let testPath = [];
+        for (const part of pathParts) {
+            testPath.push(part);
+            const item = findItemByPath(testPath.join('/'));
+            if (item) {
+                currentDocPath.push(part);
+            } else {
+                break;
+            }
+        }
+        
+        renderMenu();
+    }
+
+    // Mobile menu toggle
+    const globalNav = document.querySelector('nav#nav-global');
+    const menuButton = globalNav?.querySelector('.menu-button');
+    
+    if (menuButton) {
+        function updateButtonIcon(isOpen) {
+            menuButton.textContent = isOpen ? '✕' : '☰';
+        }
+
+        menuButton.addEventListener('click', (e) => {
+            e.stopPropagation();
+            
+            if (isMobile()) {
+                const isNowActive = navMain.classList.toggle('active');
+                updateButtonIcon(isNowActive);
+            } else {
+                navMain.classList.toggle('collapsed');
+            }
+        });
+
+        document.addEventListener('click', (e) => {
+            if (isMobile() && 
+                navMain.classList.contains('active') && 
+                !navMain.contains(e.target) && 
+                !menuButton.contains(e.target)) {
+                navMain.classList.remove('active');
+                updateButtonIcon(false);
+            }
+        });
+
+        document.addEventListener('keydown', (e) => {
+            if (e.key === 'Escape') {
+                if (isMobile() && navMain.classList.contains('active')) {
+                    navMain.classList.remove('active');
+                    updateButtonIcon(false);
+                    menuButton.focus();
+                }
+            }
+        });
+    }
+
+    // Initial render (shows loading, then loadMenuData will call initializeFromCurrentPage)
+    renderMenu();
+});
+
+/**
+ * Initialize top menu (horizontal navigation with dropdowns)
+ * Also handles: home button on desktop, hamburger → mobile side menu
+ */
+function initTopMenu() {
+    const navMainTop = document.querySelector('nav#nav-main-top');
+    const navMain = document.querySelector('nav#nav-main');
+    const globalNav = document.querySelector('nav#nav-global');
+    const menuButton = globalNav?.querySelector('.menu-button');
+    const customMenuPath = document.body.dataset.customMenu;
+    
+    if (!navMainTop) return;
+    
+    // Determine which URL to load — custom menu or default auto-menu
+    const menuUrl = customMenuPath || '/public/menu-data.json';
+    
+    // Load menu data and render both top menu and mobile menu
+    fetch(menuUrl)
+        .then(response => response.json())
+        .then(data => {
+            const menuData = data.menuData || data;
+            renderTopMenu(navMainTop, menuData);
+            buildMobileMenu(menuData, navMain);
+        })
+        .catch(error => {
+            console.error('Failed to load top menu data:', error);
+        });
+    
+    // Set up home button (desktop) / hamburger (mobile)
+    setupMenuButton(menuButton, navMain);
+}
+
+/**
+ * Set up the menu button:
+ * - Desktop: shows 🏠 (home icon), navigates to "/" on click
+ * - Mobile: shows ☰ (hamburger), toggles mobile side menu on click
+ */
+function setupMenuButton(menuButton, navMain) {
+    if (!menuButton) return;
+    
+    const isMobile = () => window.matchMedia('(max-width: 50rem)').matches;
+    
+    function updateButtonIcon() {
+        if (isMobile()) {
+            const isActive = navMain?.classList.contains('active');
+            menuButton.textContent = isActive ? '✕' : '☰';
+            menuButton.setAttribute('aria-label', isActive ? 'Close menu' : 'Menu');
+        } else {
+            menuButton.textContent = '🏠';
+            menuButton.setAttribute('aria-label', 'Home');
+        }
+    }
+    
+    // Set initial icon
+    updateButtonIcon();
+    
+    // Update icon on resize
+    window.addEventListener('resize', updateButtonIcon);
+    
+    menuButton.addEventListener('click', (e) => {
+        e.stopPropagation();
+        
+        if (isMobile()) {
+            // Mobile: toggle side menu
+            if (navMain) {
+                const isNowActive = navMain.classList.toggle('active');
+                menuButton.textContent = isNowActive ? '✕' : '☰';
+                menuButton.setAttribute('aria-label', isNowActive ? 'Close menu' : 'Menu');
+            }
+        } else {
+            // Desktop: navigate to home
+            window.location.href = '/';
+        }
+    });
+    
+    // Close mobile menu on outside click
+    document.addEventListener('click', (e) => {
+        if (isMobile() && navMain?.classList.contains('active') &&
+            !navMain.contains(e.target) && !menuButton.contains(e.target)) {
+            navMain.classList.remove('active');
+            updateButtonIcon();
+        }
+    });
+    
+    // Close mobile menu on Escape
+    document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape' && isMobile() && navMain?.classList.contains('active')) {
+            navMain.classList.remove('active');
+            updateButtonIcon();
+            menuButton.focus();
+        }
+    });
+}
+
+/**
+ * Build the mobile side menu from the same data as the top menu.
+ * Repurposes #nav-main as a vertical list with a "Home" link at top.
+ */
+function buildMobileMenu(menuData, navMain) {
+    if (!navMain) return;
+    
+    // Clear existing content
+    navMain.innerHTML = '';
+    
+    const ul = document.createElement('ul');
+    ul.className = 'mobile-menu-list';
+    
+    // Add "Home" item at the top
+    const homeLi = document.createElement('li');
+    homeLi.className = 'mobile-menu-item mobile-menu-home';
+    const homeLink = document.createElement('a');
+    homeLink.href = '/';
+    homeLink.className = 'mobile-menu-label';
+    homeLink.textContent = '🏠 Home';
+    homeLi.appendChild(homeLink);
+    ul.appendChild(homeLi);
+    
+    // Build menu items recursively
+    buildMobileMenuItems(menuData, ul, 0);
+    
+    navMain.appendChild(ul);
+}
+
+/**
+ * Recursively build mobile menu items as a flat indented list
+ */
+function buildMobileMenuItems(items, parentUl, depth) {
+    for (const item of items) {
+        const li = document.createElement('li');
+        li.className = 'mobile-menu-item';
+        if (depth > 0) {
+            li.classList.add('mobile-menu-depth-' + Math.min(depth, 4));
+        }
+        
+        const el = item.href
+            ? document.createElement('a')
+            : document.createElement('span');
+        el.className = 'mobile-menu-label';
+        el.textContent = item.label;
+        if (item.href) el.href = item.href;
+        
+        // Highlight current page
+        if (item.href && isCurrentTopMenuPage(item.href)) {
+            li.classList.add('mobile-menu-current');
+        }
+        
+        li.appendChild(el);
+        parentUl.appendChild(li);
+        
+        // Recurse into children
+        if (item.children && item.children.length > 0) {
+            buildMobileMenuItems(item.children, parentUl, depth + 1);
+        }
+    }
+}
+
+/**
+ * Check if an href matches the current page
+ */
+function isCurrentTopMenuPage(href) {
+    if (!href || href === '#') return false;
+    const current = decodeURIComponent(window.location.pathname)
+        .replace(/\/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
+    const target = decodeURIComponent(href)
+        .replace(/\/index\.html$/, '').replace(/\.html$/, '').replace(/\/$/, '');
+    return current === target;
+}
+
+/**
+ * Render the top navigation menu
+ */
+function renderTopMenu(container, menuData) {
+    const ul = document.createElement('ul');
+    ul.className = 'top-menu-level';
+    
+    menuData.forEach(item => {
+        const li = document.createElement('li');
+        li.className = 'top-menu-item';
+        if (item.hasChildren || (item.children && item.children.length > 0)) {
+            li.classList.add('has-dropdown');
+        }
+        
+        // Create label (link or span)
+        const label = item.href 
+            ? document.createElement('a')
+            : document.createElement('span');
+        label.className = 'top-menu-label';
+        label.textContent = item.label;
+        if (item.href) {
+            label.href = item.href;
+        }
+        li.appendChild(label);
+        
+        // Create dropdown if has children
+        if (item.children && item.children.length > 0) {
+            const dropdown = createTopMenuDropdown(item.children);
+            li.appendChild(dropdown);
+        }
+        
+        ul.appendChild(li);
+    });
+    
+    container.appendChild(ul);
+}
+
+/**
+ * Create a dropdown menu for top navigation
+ */
+function createTopMenuDropdown(items) {
+    const ul = document.createElement('ul');
+    ul.className = 'top-menu-dropdown';
+    
+    items.forEach(item => {
+        const li = document.createElement('li');
+        li.className = 'dropdown-item';
+        if (item.hasChildren || (item.children && item.children.length > 0)) {
+            li.classList.add('has-flyout');
+        }
+        
+        // Create label
+        const label = item.href
+            ? document.createElement('a')
+            : document.createElement('span');
+        label.className = 'dropdown-label';
+        label.textContent = item.label;
+        if (item.href) {
+            label.href = item.href;
+        }
+        li.appendChild(label);
+        
+        // Add flyout indicator if has children
+        if (item.children && item.children.length > 0) {
+            const indicator = document.createElement('span');
+            indicator.className = 'flyout-indicator';
+            indicator.textContent = '▶';
+            label.appendChild(indicator);
+            
+            // Create flyout submenu
+            const flyout = createTopMenuFlyout(item.children);
+            li.appendChild(flyout);
+        }
+        
+        ul.appendChild(li);
+    });
+    
+    return ul;
+}
+
+/**
+ * Create a flyout submenu for nested items
+ */
+function createTopMenuFlyout(items) {
+    const ul = document.createElement('ul');
+    ul.className = 'top-menu-flyout';
+    
+    items.forEach(item => {
+        const li = document.createElement('li');
+        li.className = 'dropdown-item';
+        if (item.hasChildren || (item.children && item.children.length > 0)) {
+            li.classList.add('has-flyout');
+        }
+        
+        const label = item.href
+            ? document.createElement('a')
+            : document.createElement('span');
+        label.className = 'dropdown-label';
+        label.textContent = item.label;
+        if (item.href) {
+            label.href = item.href;
+        }
+        li.appendChild(label);
+        
+        // Recursive flyout for deeper levels
+        if (item.children && item.children.length > 0) {
+            const indicator = document.createElement('span');
+            indicator.className = 'flyout-indicator';
+            indicator.textContent = '▶';
+            label.appendChild(indicator);
+            
+            const flyout = createTopMenuFlyout(item.children);
+            li.appendChild(flyout);
+        }
+        
+        ul.appendChild(li);
+    });
+    
+    return ul;
+}
+
+// (Search functionality is now handled by widgets.js)
+
+/**
+ * Initialize flyout positioning for top menu
+ * Flyouts use position:fixed to avoid being clipped by parent overflow
+ */
+function initFlyoutPositioning() {
+  const nav = document.querySelector('nav#nav-main-top');
+  if (!nav) return;
+  
+  // Use event delegation for all flyout triggers
+  nav.addEventListener('mouseenter', (e) => {
+    const trigger = e.target.closest('.dropdown-item.has-flyout');
+    if (!trigger) return;
+    
+    const flyout = trigger.querySelector(':scope > .top-menu-flyout');
+    if (!flyout) return;
+    
+    positionFlyout(trigger, flyout);
+  }, true);
+}
+
+/**
+ * Position a flyout menu relative to its trigger element
+ */
+function positionFlyout(trigger, flyout) {
+  const triggerRect = trigger.getBoundingClientRect();
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  const navHeight = parseInt(getComputedStyle(document.documentElement).getPropertyValue('--global-nav-height')) || 48;
+  
+  // Default: position to the right of the trigger
+  let left = triggerRect.right;
+  let top = triggerRect.top;
+  
+  // Temporarily show to measure
+  flyout.style.visibility = 'hidden';
+  flyout.style.display = 'block';
+  const flyoutRect = flyout.getBoundingClientRect();
+  flyout.style.display = '';
+  flyout.style.visibility = '';
+  
+  // If flyout would overflow right edge, flip to left side
+  if (left + flyoutRect.width > viewportWidth - 10) {
+    left = triggerRect.left - flyoutRect.width;
+  }
+  
+  // Keep flyout within vertical bounds
+  // Clamp to bottom of nav bar (no gap for top items)
+  if (top < navHeight) {
+    top = navHeight;
+  }
+  // Prevent overflow at bottom of viewport
+  if (top + flyoutRect.height > viewportHeight - 10) {
+    top = viewportHeight - flyoutRect.height - 10;
+  }
+  
+  flyout.style.left = `${left}px`;
+  flyout.style.top = `${top}px`;
+}
+
+// Initialize flyout positioning when DOM is ready
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initFlyoutPositioning);
+} else {
+  initFlyoutPositioning();
+}

package/meta/templates/default-template/default.css

@@ -796,7 +796,7 @@ nav#nav-main-top .dropdown-label {
 }
 
 nav#nav-main-top .dropdown-label:hover {
-  background-color: var(--nav-top-bg);
+  background-color: rgba(255, 255, 255, 0.1);
 }
 
 nav#nav-main-top a.dropdown-label:hover {
@@ -810,14 +810,12 @@ nav#nav-main-top .flyout-indicator {
   margin-left: 8px;
 }
 
-/* Flyout menu (nested children) */
+/* Flyout menu (nested children) - uses fixed positioning to avoid clipping by parent overflow */
 nav#nav-main-top .top-menu-flyout {
   display: none;
-  position: absolute;
-  left: 100%;
-  top: -1px;
+  position: fixed;
   min-width: 200px;
-  max-height: calc(100vh - var(--global-nav-height) - 20px);
+  max-height: calc(100vh - var(--global-nav-height) - 40px);
   overflow-y: auto;
   background-color: var(--widget-bg);
   border: 1px solid var(--widget-border);
@@ -827,9 +825,10 @@ nav#nav-main-top .top-menu-flyout {
   margin: 0;
   padding: 0;
   z-index: 1006;
+  /* JS will set top/left via inline styles */
 }
 
-/* Show flyout on hover */
+/* Show flyout on hover - JS handles positioning */
 nav#nav-main-top .dropdown-item.has-flyout:hover > .top-menu-flyout {
   display: block;
 }

package/meta/templates/default-template/menu.js

@@ -829,4 +829,70 @@ function createTopMenuFlyout(items) {
     return ul;
 }
 
-// (Search functionality is now handled by widgets.js)
+// (Search functionality is now handled by widgets.js)
+
+/**
+ * Initialize flyout positioning for top menu
+ * Flyouts use position:fixed to avoid being clipped by parent overflow
+ */
+function initFlyoutPositioning() {
+  const nav = document.querySelector('nav#nav-main-top');
+  if (!nav) return;
+  
+  // Use event delegation for all flyout triggers
+  nav.addEventListener('mouseenter', (e) => {
+    const trigger = e.target.closest('.dropdown-item.has-flyout');
+    if (!trigger) return;
+    
+    const flyout = trigger.querySelector(':scope > .top-menu-flyout');
+    if (!flyout) return;
+    
+    positionFlyout(trigger, flyout);
+  }, true);
+}
+
+/**
+ * Position a flyout menu relative to its trigger element
+ */
+function positionFlyout(trigger, flyout) {
+  const triggerRect = trigger.getBoundingClientRect();
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  const navHeight = parseInt(getComputedStyle(document.documentElement).getPropertyValue('--global-nav-height')) || 48;
+  
+  // Default: position to the right of the trigger
+  let left = triggerRect.right;
+  let top = triggerRect.top;
+  
+  // Temporarily show to measure
+  flyout.style.visibility = 'hidden';
+  flyout.style.display = 'block';
+  const flyoutRect = flyout.getBoundingClientRect();
+  flyout.style.display = '';
+  flyout.style.visibility = '';
+  
+  // If flyout would overflow right edge, flip to left side
+  if (left + flyoutRect.width > viewportWidth - 10) {
+    left = triggerRect.left - flyoutRect.width;
+  }
+  
+  // Keep flyout within vertical bounds
+  // Clamp to bottom of nav bar (no gap for top items)
+  if (top < navHeight) {
+    top = navHeight;
+  }
+  // Prevent overflow at bottom of viewport
+  if (top + flyoutRect.height > viewportHeight - 10) {
+    top = viewportHeight - flyoutRect.height - 10;
+  }
+  
+  flyout.style.left = `${left}px`;
+  flyout.style.top = `${top}px`;
+}
+
+// Initialize flyout positioning when DOM is ready
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initFlyoutPositioning);
+} else {
+  initFlyoutPositioning();
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.77.0",
+  "version": "0.79.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -72,7 +72,9 @@
     "CHANGELOG.md"
   ],
   "pnpm": {
-    "onlyBuiltDependencies": ["esbuild"]
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   },
   "publishConfig": {
     "access": "public",

package/src/helper/automenu.js

@@ -411,6 +411,14 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
  * When a folder contains only an index file (index.md) or a foldername-matching
  * file (e.g. Arcanist/Arcanist.md) and no other children, the folder is replaced
  * with a direct link to that document using the folder's label.
+ * 
+ * Conditions for collapse:
+ * - Exactly one child
+ * - That child is an index-like file (isIndex: true)
+ * - The child has no children (i.e., not a subfolder)
+ * 
+ * This ensures folders with subfolders are never collapsed, even if they only
+ * have 0-1 regular documents.
  */
 function collapseSingleDocFolders(items) {
   return items.map(item => {
@@ -419,18 +427,20 @@ function collapseSingleDocFolders(items) {
     // Recurse first so nested single-doc folders are collapsed bottom-up
     item.children = collapseSingleDocFolders(item.children);
     
-    // Check if the only child(ren) are index-like files (no sub-folders)
-    const nonIndexChildren = item.children.filter(c => !c.isIndex);
-    if (nonIndexChildren.length === 0 && item.children.length > 0) {
-      // All children are index files — collapse to a single link
-      const indexChild = item.children[0];
-      return {
-        ...item,
-        hasChildren: false,
-        children: undefined,
-        href: indexChild.href || item.href,
-        isIndex: false,
-      };
+    // Only collapse if there is exactly one child that is an index-like file
+    // Collapsed subfolders have isIndex: false, so they won't trigger collapse
+    // Folders with any remaining subfolders (hasChildren: true) won't collapse
+    if (item.children.length === 1) {
+      const onlyChild = item.children[0];
+      if (onlyChild.isIndex && !onlyChild.hasChildren) {
+        return {
+          ...item,
+          hasChildren: false,
+          children: undefined,
+          href: onlyChild.href || item.href,
+          isIndex: false,
+        };
+      }
     }
     
     return item;

package/src/helper/customMenu.js

@@ -20,10 +20,58 @@ const FOLDER_ICON = '📁';
 const DOCUMENT_ICON = '📄';
 const HOME_ICON = '🏠';
 
+/**
+ * Check if a menu item represents an index-like file.
+ * Index-like files are: index, home, or {foldername}.html
+ * 
+ * IMPORTANT: The index file must be DIRECTLY within the parent folder,
+ * not in a nested subfolder. This prevents collapsed nested folders
+ * from being treated as index files for their parent.
+ * 
+ * @param {object} item - Menu item
+ * @param {string} parentLabel - The parent folder's label
+ * @returns {boolean}
+ */
+function isIndexLikeItem(item, parentLabel) {
+  if (!item.href) return false;
+  
+  const hrefLower = item.href.toLowerCase();
+  const parts = hrefLower.split('/').filter(Boolean);
+  
+  // Need at least 2 parts: parent folder and filename
+  if (parts.length < 2) return false;
+  
+  const filename = parts[parts.length - 1]?.replace(/\.html$/, '') || '';
+  const parentFolder = parts[parts.length - 2] || '';
+  
+  // The parent folder in the href must match the expected parent label
+  // This prevents /foo/bar/nested/index.html from matching as index for /foo/bar/
+  if (parentLabel && parentFolder !== parentLabel.toLowerCase()) {
+    return false;
+  }
+  
+  // Check for index or home
+  if (filename === 'index' || filename === 'home') return true;
+  
+  // Check if filename matches parent folder name (e.g., 'arcanist.html' in 'Arcanist/' folder)
+  if (parentLabel && filename === parentLabel.toLowerCase()) return true;
+  
+  return false;
+}
+
 /**
  * Collapse single-document folders into direct links.
- * If a folder's only children are index-like files (no sub-folders),
- * collapse it to a direct link using the folder's label and the first child's href.
+ * When a folder contains only an index file (index.md) or a foldername-matching
+ * file and no subfolders, collapse it to a direct link using the folder's label.
+ * 
+ * Conditions for collapse:
+ * - Exactly one child
+ * - That child is an index-like file (index, home, or {foldername})
+ * - The child has no children (i.e., not a subfolder)
+ * 
+ * This ensures folders with subfolders are never collapsed, even if they only
+ * have 0-1 regular documents.
+ * 
  * @param {Array} items - Menu items
  * @returns {Array} - Processed menu items
  */
@@ -34,13 +82,11 @@ function collapseSingleDocFolders(items) {
     // Recurse first so nested single-doc folders are collapsed bottom-up
     item.children = collapseSingleDocFolders(item.children);
     
-    // Check if all children are non-folder items (i.e., no child has children)
-    const hasSubfolders = item.children.some(c => c.hasChildren);
-    if (!hasSubfolders && item.children.length > 0) {
-      // All children are leaf files — if there's only one, collapse to a direct link
-      // For index-like content (single child), collapse the folder entirely
-      if (item.children.length === 1) {
-        const onlyChild = item.children[0];
+    // Only collapse if there is exactly one child that is an index-like file
+    if (item.children.length === 1) {
+      const onlyChild = item.children[0];
+      // Check that the child is not a subfolder and is an index-like file
+      if (!onlyChild.hasChildren && isIndexLikeItem(onlyChild, item.label)) {
         return {
           ...item,
           hasChildren: false,

package/src/jobs/generate.js

@@ -17,6 +17,7 @@ import {
   saveHashCache,
   needsRegeneration,
   updateHash,
+  getUrsaDir,
 } from "../helper/contentHash.js";
 import {
   buildValidPaths,
@@ -32,7 +33,7 @@ import { bundleMetaTemplateAssets, bundleDocumentCss, bundleDocumentJs, clearMet
 import { buildFullTextIndex, buildIncrementalIndex, loadIndexCache, saveIndexCache } from "../helper/fullTextIndex.js";
 import { dependencyTracker } from "../helper/dependencyTracker.js";
 import { CacheBustHashMap } from "../helper/build/cacheBust.js";
-import { copy as copyDir, emptyDir, outputFile } from "fs-extra";
+import { copy as copyDir, emptyDir, outputFile, remove } from "fs-extra";
 import { basename, dirname, extname, join, parse, resolve } from "path";
 import { URL } from "url";
 import o2x from "object-to-xml";
@@ -131,9 +132,12 @@ export async function generate({
   // Initialize dependency tracker for this build
   dependencyTracker.init(source);
 
-  // Clear output directory when --clean is specified
+  // Clear output directory and cache when --clean is specified
   if (_clean) {
     progress.startTimer('Clean');
+    const ursaDir = getUrsaDir(source);
+    progress.logTimed(`Clean build: deleting cache folder ${ursaDir}`);
+    await remove(ursaDir);
     progress.logTimed(`Clean build: clearing output directory ${output}`);
     await emptyDir(output);
     progress.logTimed(`Clean complete [${progress.stopTimer('Clean')}]`);