@kenjura/ursa 0.73.0 → 0.76.0

package/CHANGELOG.md

@@ -1,3 +1,84 @@
+# 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
+
+- Top Menu changes: the top menu is now the default first-level navigation. Top-left nav is either root, or 'hamburger' on smaller screens.
+  - Right column is now a standardized widget zone, with TOC, Search, and Profile widgets implemented.
+- Default header: documents without an initial H1 will now have their title rendered as an H1 header at the top of the article. Index/home pages will default to the parent folder name if not overridden.
+- Breadcrumbs: added breadcrumbs to the top of each article for easier navigation and context
+
+# 0.74.0
+2026-02-08
+
+- added a feature to skip preview generation and swapping on a per-image basis. You can use the data-no-preview tag in html, and the ?no-preview query parameter in markdown or wikitext images.
+- when building automenus and autoindex pages, folders with no md/mdx/txt/html documents anywhere in their tree will not be shown.
+
 # 0.73.0
 2026-02-07
 

package/meta/default-template.html

@@ -10,29 +10,86 @@
 
 <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">
                 <!-- Top menu will be populated by JavaScript when data-menu-position="top" -->
             </nav>
 
-            <div class="search-wrapper">
+            <div class="search-wrapper search-wrapper-inline">
                 <input id="global-search" type="text" placeholder="Search..." />
             </div>
         </div>
 
         <div class="nav-right-controls">
-            <button class="search-button" aria-label="Search">🔍</button>
-            <span class="avatar" aria-hidden="true">👤</span>
+            <div class="widget-bar">
+                <button class="widget-button" data-widget="toc" aria-label="Table of Contents" title="Table of Contents">
+                    <span class="widget-icon">≡</span>
+                </button>
+                <button class="widget-button" data-widget="search" aria-label="Search" title="Search">
+                    <span class="widget-icon">🔍</span>
+                </button>
+                <button class="widget-button" data-widget="profile" aria-label="Profile" title="Profile">
+                    <span class="widget-icon">👤</span>
+                </button>
+            </div>
         </div>
     </nav>
+
+    <!-- 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>
+                <button class="widget-profile-signin" disabled>Sign In</button>
+                <p class="widget-profile-note">Authentication coming soon</p>
+            </div>
+        </div>
+    </div>
+
     <nav id="nav-main">
         ${menu}
     </nav>
-    <nav id="nav-toc">
-        <!-- TOC will be generated by JavaScript -->
-    </nav>
     <article id="main-content">
         ${body}
     </article>
@@ -46,6 +103,7 @@
     <script src="/public/toc-generator.js"></script>
     <script src="/public/menu.js"></script>
     <script src="/public/search.js"></script>
+    <script src="/public/widgets.js"></script>
     <script src="/public/sectionify.js"></script>
     <script src="/public/sticky.js"></script>
     ${customScript}