@kenjura/ursa 0.75.0 → 0.77.0

package/CHANGELOG.md

@@ -1,3 +1,88 @@
+# 0.77.0
+2026-02-13
+
+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.
+
+Meta cleanup:
+- Templates should have their own folder, including default
+- All static files for a template should be in the template's folder, and probably in the right subfolder (e.g. public/default.css should be in templates/default/public/default.css or something like that).
+- Template filenames should be templates/{templateName}/index.html
+- Ursa should throw a warning if it finds orphaned static files in meta that aren't referenced by a template
+
+Static assets revamp:
+- Revamped the building of static assets (stylesheets and scripts). The new logic is:
+  - All meta scripts and stylesheets should be bundled together into a single CSS file and a single JS file for the entire site. This applies to build mode; in dev mode, they are served individually for easier debugging and regeneration.
+  - Bundle-able document files (style.css, script.js, menu.md) will be bundled together on a per-folder basis. Each document will include the bundles from its own folder and all parent folders (where they exist).
+
+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.
+- Regeneration priority order:
+  - When regeneration is triggered, check for connected WebSocket clients and get their current URL.
+  - If their current URL is affected by the change (document, static asset, template, anything), prioritize the necessary documents and assets to serve that URL before all others, and when they are regenerated, send the push notification to reload.
+  - After that, regenerate the rest of the affected documents in the background.
+  - In cases of rapid changing of files, do the following:
+    - Debounce all file system change events within a short time window (e.g. 500ms); wait for at least 500ms of no changes before starting regeneration. This helps in cases where a script or bot is making many changes to many files.
+  - When a change is detected, before any complex processing, send a ping to WebSocket-connected clients that an update is in progress, but it isn't known yet if it will affect their page.
+  - When it is determined that a change will affect the current page of a connected client, send another push to let the client know.
+  - Handle the above two notifications in the UI thus:
+    - When updates start, add a subtle loading indicator to the right of all left widgets, such as <Loader color="gray" />
+    - If it turns out the update doesn't need a refresh, remove the indicator.
+    - If it does need a refresh, change the indicator to a <Loader color="green" />.
+    - When the hot refresh actually happens, the indicator shouldn't be there anymore.
+- Cache changes (under consideration):
+  - Before the cache was implemented, every file change triggered a complete regeneration of the entire site. This was slow, obviously. First, an in-memory cache was added to speed up the regeneration of unchanged files. But since the watcher back then missed a lot of regeneration cases (such as all meta changes), killing 'serve' and restarting it was quite common. Thus, the cache was persisted to disk, so that even in the case of a full regeneration (such as after a restart), unchanged files would still be skipped. This has worked fairly well, but for the invalidation edge cases described above (already fixed).
+  - However, considering that we now have a robust regeneration system that can handle all edge cases and push updates to the client, we may want to consider removing the cache entirely. The cache adds complexity and can sometimes get into a bad state, requiring manual deletion. With the new regeneration system, we could keep the cache in-memory, and rarely will the user need to kill 'serve' and restart just to get an update (ideally, never). In-memory cache is even faster than disk, so this might be a better experience overall.
+- Regeneration cases still unhandled:
+  - User updates Ursa itself (e.g. npm update) while serve is active. I mean, this shouldn't be very common outside of Ursa devs, but's determine:
+    - Does the current system actually catch the meta changes?
+
+
+
+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:
+- [x] 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).
+- [x] 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.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 */
@@ -145,6 +152,35 @@ nav#nav-global .nav-right-controls {
   gap: 0;
 }
 
+/* Ursa update indicator (loading spinner in nav bar) */
+.ursa-update-indicator {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  width: var(--global-nav-height);
+  height: var(--global-nav-height);
+  opacity: 0.7;
+}
+.ursa-spinner {
+  width: 14px;
+  height: 14px;
+  border: 2px solid rgba(128, 128, 128, 0.3);
+  border-top-color: rgba(128, 128, 128, 0.8);
+  border-radius: 50%;
+  animation: ursa-spin 0.8s linear infinite;
+}
+.ursa-update-gray .ursa-spinner {
+  border-color: rgba(128, 128, 128, 0.3);
+  border-top-color: rgba(128, 128, 128, 0.8);
+}
+.ursa-update-green .ursa-spinner {
+  border-color: rgba(76, 175, 80, 0.3);
+  border-top-color: rgba(76, 175, 80, 0.9);
+}
+@keyframes ursa-spin {
+  to { transform: rotate(360deg); }
+}
+
 .widget-button {
   display: flex;
   align-items: center;
@@ -174,7 +210,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 +226,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 +454,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;
@@ -558,6 +700,8 @@ nav#nav-main-top .top-menu-dropdown {
   top: 100%;
   left: 0;
   min-width: 200px;
+  max-height: calc(100vh - var(--global-nav-height) - 20px);
+  overflow-y: auto;
   background-color: var(--widget-bg);
   border: 1px solid var(--widget-border);
   border-radius: 4px;
@@ -612,6 +756,8 @@ nav#nav-main-top .top-menu-flyout {
   left: 100%;
   top: -1px;
   min-width: 200px;
+  max-height: calc(100vh - var(--global-nav-height) - 20px);
+  overflow-y: auto;
   background-color: var(--widget-bg);
   border: 1px solid var(--widget-border);
   border-radius: 4px;