@kenjura/ursa 0.96.0 → 0.98.0

package/CHANGELOG.md

@@ -1,3 +1,47 @@
+# 0.98.0
+2026-09-20
+
+Named menus: `menu-<name>.md` files rendered inline where a document anchors them.
+
+A folder's `menu.md` replaces the site navigation for its subtree. That is one menu per folder, always in the chrome. Sites also want small menus that belong to the content — a strip of sibling pages at the top of each class page, say — and those have been written by hand into every page, and kept in sync by hand.
+
+- **Any `menu*.md` is a menu file.** `menu.md` (and `_menu.md`, `.txt` variants) is the folder menu as before; `menu-classes.md`, `menu-2.md` and so on are additional menus in the same folder, and the same file format.
+- **An `id` makes a menu named.** A menu file whose frontmatter has `id: classes` renders nowhere on its own. A document in that folder or below it places it with `{menu:classes}` on a line of its own, and the menu appears there as a static `<nav class="ursa-menu">` inside the article — not a fixed element. `menu.md` with an `id` is a named menu too, and stops being the folder's nav. The `id` is required for `menu-<name>.md`; a file without one is warned about and renders nowhere.
+- **`appearance: horizontal | vertical`**, default horizontal: a strip of items with hover dropdowns for nested items, or a stacked, indented list. Both mark the current page's item (`ursa-menu-current`) and its ancestors (`ursa-menu-active`). Styles live in the default template's stylesheet, scoped like the breadcrumbs so a site's `a { … }` cannot break them and a site's more specific selector can restyle them.
+- **Resolution is by nearest id.** The walk goes up from the document's folder to the docroot; the first menu file with a matching `id` wins, so a deeper folder can shadow one defined above it. `auto-generate-menu` and `menu-depth` work as in `menu.md`.
+- **Anchors fail quietly.** `{menu:x}` is inert Markdown — braces mean nothing to the renderer — and it is substituted after rendering, so an anchor never changes how the Markdown around it parses. If no menu answers, or the menu file cannot be parsed, the anchor becomes `<!-- ursa: menu "x" not found -->` and the build warns, naming the document; the page renders normally. Anchors inside code spans and code blocks stay as written. In `.mdx`, where `{…}` is an expression, an anchor alone on a line is rewritten before compilation and never reaches the compiler.
+- **A menu above the first heading stays above the title.** The default `<h1>` is injected after any leading menus rather than before them, and the default template's `sectionify.js` keeps leading menus with the breadcrumbs, outside the sections.
+- **Menus are build-graph nodes.** Editing `menu-classes.md` rewrites exactly the pages that anchor it (their `.html`, `.json` and `.xml`), nothing else; creating a missing menu file fills the anchors in the next pass without the pages being edited; deleting it puts the comments back. A page that anchors a menu depends on a projection of each candidate menu file's identity, not its body, so adding an unrelated file to the folder does not re-render it.
+- **Menu files are not documents.** They are not rendered to pages, listed in the automenu, an auto-index or a `<dir>.html` listing, indexed for search, or dated in recent activity. This applies to `menu.md` too, which used to be rendered to `menu.html`. The upgrade discards the build cache, so that stale page is not known to the new graph and is not deleted; one `--clean` removes it.
+
+The README gains a "Menus" section documenting both kinds.
+
+# 0.97.0
+2026-09-20
+
+`ursa serve` catches every change; `generate` and `serve` are one build.
+
+`serve` had a history of missed updates — a font replaced in `meta/shared`, a folder renamed, a document deleted, an image added where a page had a dead link, a `.tsx` edited, `menu-label` changed in a non-index file — each one a case that some filename heuristic in the watcher or some cache-clear call site had not been told about, and each one fixed by restarting with `--clean`. `docs/SERVE.md` (written 2026-09-03) specifies what `serve` promises instead and lists twenty-seven ways the old implementation fell short of it. This release implements that specification.
+
+**One rule replaces all of the heuristics: every output is a node in a build graph, and a node recomputes if and only if one of its recorded inputs changed.** The engine that shipped unused in 0.87 (`src/helper/build/graph.js`) is now the build. Every file a node reads, every path it probes and every directory it lists while computing is recorded as an edge — including reads made deep inside the menu walker, the label resolver and the breadcrumb builder, which now import their `fs` calls from a traced shim rather than being rewritten to thread a context through. Nothing decides what to rebuild by looking at a filename.
+
+- **`generate` runs the same pass.** A cold start is a pass in which every leaf is new; a warm start re-checks the persisted graph (`.ursa/graph.json`, replacing `content-hashes.json`, `nav-cache.json`, `dependency-graph.json`, `image-cache.json` and `fulltext-index.json`) and recomputes what its inputs say has changed. The output of `serve` after any sequence of edits is byte-identical to a clean `generate` of the same tree, modulo the footer's build id and timestamp — the acceptance test in `src/helper/build/__test__/pass.test.js` asserts it for every scenario in the spec's §10.
+- **Minimality.** Editing an article body rewrites its `.html`/`.json`/`.xml`, the full-text index and recent activity, and nothing else. Editing `menu-label` rewrites `menu-data.json` and the listings that show the label. Saving a file without changing its bytes writes nothing. Editing a `.tsx` re-renders exactly the MDX documents that import it. `--explain` (new on both commands) prints, for every output rebuilt, the input that changed.
+- **Catchment zones are exact.** Adding, editing or removing a `style.css` rewrites exactly the pages in its subtree, plus the bundle; renaming it to `_style.css` with the same content rewrites nothing. A template edit rewrites the pages using it, including generated index and listing pages, which the old tracker never registered. A shared font rewrites the meta bundle and every page whose template bundles it. A root-level add or rename rewrites every page (the root menu is inlined); a deeper one rewrites only the menu data.
+- **Nothing is left behind.** Every output file is owned by exactly one node, and ownership is persisted. Deleting or renaming a document deletes its `.html`/`.json`/`.xml`; renaming a folder deletes the old subtree, its listing and its bundles; hiding a folder with `config.json` deletes its outputs. This applies to `generate` too: `output/` no longer accumulates ghosts, and `--clean` is corruption recovery rather than a routine step.
+- **Several sources for one output.** `index.mdx` beside `index.md`, `foo.md` beside a hand-written `foo.html`, `home.md` beside `foo/foo.md` — the winner used to be whichever wrote last. One precedence list (`src/helper/build/precedence.js`, documented in the README's "Link logic") now decides it everywhere: hand-written `.html`, then `.mdx`, `.md`, `.txt`, `.yml`; for a folder's index, `index.*`, `_index.*`, `home.*`, `_home.*`, `<foldername>.*`, then the auto-index. The shadowed source is not rendered, indexed or listed, and a warning names both files; removing the winner promotes the next candidate in the same pass, so deleting the only `index.md` of a folder hands its URL to the auto-index without a restart. `/foo` with both `foo.md` and `foo/` present resolves to `foo.html` in links as it always did in the server; the link validator had said the opposite.
+- **Dead links come alive.** A page records the images it references whether or not they exist, so adding the missing image gives the page its preview and lightbox without the page being edited, and replacing an image changes the page's `?v=` token. A page depends on one resolution node per link target, not on the whole path map, so creating a document that other pages link to rewrites only those pages.
+- **Cache-busting is by content hash**, not build timestamp: `?v=<hash of the file>` on bundles, images, scripts and CSS `url()` targets. An unchanged asset keeps its URL, so pages are not rewritten for it; a changed one changes its URL, which is exactly the set of pages a browser must reload. The meta bundle's `fetch('/public/x.json')` calls carry the page's build id (`data-build` on `<body>`) at request time instead of the JSON's hash — hashing the menu data into the bundle would have rewritten every page whenever the menu changed.
+- **Watching, batching, single writer.** Both trees are watched recursively without an extension allow-list (`.otf`, `.wav`, `.zip` and files with no extension were invisible before); only `.ursa/`, the output directory, `node_modules`, `.git` and editor scratch files are excluded. Directory events rescan their subtree, since macOS reports a renamed folder as one event. Events are batched with a 500 ms quiet window and a 2 s upper bound, so a process writing continuously cannot postpone regeneration forever. Exactly one pass runs at a time — the startup build included, which used to race a meta edit — and events that arrive during a pass form the next batch.
+- **Viewer first, early reload.** The pages connected browsers are looking at are built before anything else, and each browser is told to reload the moment its page is written — before the rest of the affected set is processed. "Changed" means the bytes the browser would fetch changed, so a tab on a page whose owner moved (the auto-index taking over a deleted `index.md`) or that was deleted reloads to the truth, and a tab parked on a 404 loads the page when it appears. A page whose owner failed is told `update-failed` instead of being left with the indicator on. When only the menu data, the search indices or recent activity changed, open tabs get `data-updated` and refetch in place — the default template's `menu.js`, `search.js` and `widgets.js` listen for it — rather than reloading.
+- **The `$&` bug.** The single-file regenerator substituted template placeholders with `String.replace(string, string)`, which interprets `$&`, `` $` `` and `$'` in the document body; the full build did not. There is one render path now, and it uses a function replacer.
+- **Determinism.** Every listing, index and menu is sorted; readdir order never reaches the output. The footer's build id, timestamp and git hash are computed once per session and are not an input of anything, so a `generate` run after an unrelated edit does not rewrite every page to stamp them.
+- **`transformMetadata.js` edits take effect** (the dynamic import carries the file's content hash), a hand-written `.html` is never overwritten by `serve`, a frontmatter-only `index.md` never displaces the auto-index in `serve`, the whitelist and exclude files are live inputs (editing them adds and removes documents), and `.yaml` is no longer watched as if it were an article.
+
+Smaller changes that fall out of the one render path: the `<dir>.html` listing pages emit root-absolute links (they were relative to the wrong directory below one level) and fill `${customScript}` instead of leaving the placeholder in the page; the auto-index no longer lists a folder's listing page as a document beside the folder itself; search-index and recent-activity entries are ordered deterministically; copies of `style.css` are no longer placed in the output beside the bundles. `dev` reads the shared precedence list but is otherwise unchanged; its future is still an open question in `docs/SERVE.md`. The `directory-tree` dependency is gone.
+
+Upgrading: the first build discards the old caches and rebuilds everything. Files the previous version left in `output/` that this version does not produce (the `style.css` copies) are not known to the graph and are not deleted; one `--clean` removes them.
+
 # 0.96.0
 2026-09-16
 

package/README.md

@@ -53,10 +53,21 @@ Generate a static site once and exit.
 
 #### `ursa serve <source>`
 Start a development server that:
-- Generates the site initially
-- Starts an HTTP server to serve the output directory
-- Watches source and meta directories for changes
-- Automatically regenerates the site when files change
+- Starts an HTTP server over the output directory, then builds the site
+- Watches the source and meta directories for changes — every file, no
+  extension allow-list — and keeps the output continuously equal to what a
+  build from the current source would produce: adds, deletes, renames, folder
+  renames, inherited `style.css`/`script.js`/`menu.md`/`config.json` files
+  appearing or disappearing, images and linked documents that come alive,
+  template and shared-asset edits
+- Rebuilds only the outputs whose inputs actually changed (see
+  [Incremental builds](#incremental-builds)), the page a connected browser is
+  looking at first, and tells that browser to reload the moment it is written
+- Tells other open tabs to refetch the menu, search indices and recent
+  activity in place when those change, instead of reloading them
+
+The same incremental pass runs under `generate`, so the two never disagree
+about the output; `docs/SERVE.md` is the specification.
 
 ### CLI Options
 
@@ -68,6 +79,40 @@ Start a development server that:
 - `--exclude, -e` - Folders to exclude: comma-separated paths relative to source, or path to file with one folder per line
 - `--clean` - Delete the `.ursa` cache folder and clear output directory, forcing full regeneration
 - `--json-only, -j` - Emit only the `.json` data files (generate command only)
+- `--explain` - Log, for every output that was rebuilt, the input that changed
+
+### Incremental builds
+
+Every build — `generate` and each `serve` pass alike — runs over a persisted
+build graph (`.ursa/graph.json`). Every output file is owned by exactly one
+node of the graph, and every file, path probe and directory listing a node
+consumed while producing it is recorded as an input. A pass re-checks the
+inputs that changed, recomputes only the nodes that consumed them, stops
+propagating where a recomputed value came out identical, writes only files
+whose bytes differ, and deletes the outputs of anything whose source is gone.
+
+Consequences:
+
+- `generate` after an edit rewrites the edited document's page and data, the
+  full-text index and recent activity — nothing else. A `menu-label` edit
+  rewrites the menu data and the listings that show the label. A root
+  `style.css` edit rewrites every page (the bundle's URL, which carries its
+  content hash, appears in every one of them). Run with `--explain` to see the
+  reason for each rewrite.
+- Deleting or renaming a source removes its outputs; hiding a folder with
+  `config.json` deletes the folder's outputs. `output/` no longer accumulates
+  ghosts, and `--clean` is corruption recovery, not a routine step.
+- Asset URLs carry `?v=<content hash>` rather than a build timestamp, so
+  identical inputs give identical output. The one exception is the footer's
+  build id and timestamp, which are fixed once per `serve` session or
+  `generate` run and are not an input of anything.
+- Starting `serve` (or running `generate`) against a tree that changed while
+  ursa was not running converges on the startup pass, without `--clean`.
+- Upgrading ursa discards the graph and rebuilds everything.
+
+Files that used to live in `.ursa/` (`content-hashes.json`, `nav-cache.json`,
+`dependency-graph.json`, `image-cache.json`, `fulltext-index.json`) are
+replaced by the graph.
 
 ### JSON-Only Builds
 
@@ -91,11 +136,10 @@ Everything skipped operates on the assembled *page*; the JSON's `bodyHtml` is
 the pre-template render, which none of those steps touch. That is why the output
 is identical rather than merely similar.
 
-Mixing modes against one source tree is safe. The two share the `.ursa` hash
-cache, but each asks only for the outputs its own mode emits, so a full build
-following a JSON-only build still writes the HTML it is missing. A JSON-only
-build does not write the dependency graph or seed the watch cache, so it cannot
-degrade a later `serve`.
+Mixing modes against one source tree is safe. The build mode is an input of
+the data nodes, so a full build following a JSON-only build writes the HTML and
+XML it is missing, and a JSON-only build after a full one leaves the rest of
+the output in place.
 
 ### Whitelist File Format
 
@@ -360,6 +404,78 @@ useEffect(() => {
 
 `contentChanged(root)` dispatches `ursa:content-changed` on `document` with the changed element in `event.detail.root` (the article, if omitted). Sticky headings and the table of contents re-read the article on it; calls within the same task are coalesced into one event. A site's own scripts can listen for the same event.
 
+## Menus
+
+The site's navigation is generated from the folder tree. A folder can replace
+it with its own menu by holding a `menu.md` (or `menu.txt`, `_menu.md`,
+`_menu.txt`); that menu applies to the folder and everything below it, until a
+deeper folder holds a menu of its own.
+
+```markdown
+---
+auto-generate-menu: true   # start from the folder tree…
+menu-position: top         # top (default) or side
+menu-depth: 3
+---
+
+- [Custom link](./somewhere.md)
+{menu}                     # …and put the generated items here
+- [Another](https://example.com)
+```
+
+Items are Markdown list links (`- [Label](./path.md)`, nested by indentation)
+or wikitext (`* [[path|Label]]`). Relative paths resolve from the menu file's
+folder.
+
+### Named menus
+
+A menu file whose frontmatter has an `id` is a **named menu**. It does not
+replace the folder's navigation; instead any document in that folder or below
+it places the menu in its body with an anchor on a line of its own:
+
+```markdown
+---
+id: classes
+appearance: horizontal     # horizontal (default) or vertical
+---
+
+- [Arcanist](./arcanist.md)
+- [Fighter](./fighter.md)
+- [Witch](./witch.mdx)
+```
+
+```markdown
+# Fighter
+
+{menu:classes}
+
+Fighters are…
+```
+
+- Name the file `menu.md` or `menu-<anything>.md` (`menu-classes.md`,
+  `menu-2.txt`); a folder can hold several. The `id` is required for
+  `menu-<anything>.md`; `menu.md` without one is the folder menu above.
+- The anchor renders as a static `<nav class="ursa-menu ursa-menu-<appearance>">`
+  exactly where it stands in the document, not as a fixed element. The item
+  whose link is the current page gets `ursa-menu-current` (its ancestors
+  `ursa-menu-active`), so a menu of sibling pages works as a category switcher.
+  `horizontal` is a strip of items with hover dropdowns for nested items;
+  `vertical` is a stacked, indented list.
+- The nearest file with that `id` wins, so a deeper folder can shadow a menu
+  defined above it. `auto-generate-menu` and `menu-depth` work as in `menu.md`.
+- A menu anchored above the first heading stays above the page title.
+- The anchor must be on its own line. It works in `.md`, `.txt` and `.mdx`.
+  An anchor inside a code span or code block is left as written.
+- Menu files are navigation, not documents: they are not rendered to pages,
+  listed in menus or indices, or searched.
+
+**Failure is quiet.** An anchor whose menu does not exist, or whose menu file
+cannot be parsed, is replaced by `<!-- ursa: menu "id" not found -->` and
+reported as a build warning naming the document. The page renders normally
+with nothing where the menu would have been, and the surrounding Markdown is
+untouched. Under `ursa serve`, creating the missing menu file fills the anchor
+without editing the page.
+
 ## Auto-Index Generation
 
 Ursa automatically generates index pages for folders that don't have one. You can also explicitly control auto-index generation in your index documents using frontmatter:
@@ -439,11 +555,23 @@ SOURCE folder should have at least an index.md in it.
 ## Link logic
 Links are allowed to be extensionless. Link resolution works as follows:
 - If link has an extension, look for exact match, and 404 if not found
+  (`.md`/`.mdx` links are rewritten to `.html` optimistically)
 - If link has no extension:
-  - Look for exact match with .md, .txt, .yml extensions (in that order)
-  - If not found, assume the path is a folder, and look for:
-    - index.md, index.txt, _index.md, _index.txt
-    - home.md, home.txt, _home.md, _home.txt
-    - (folder name).md, (folder name).txt
-  - If any of these are found, link to that file's html version
-  - If still not found, 404
+  - `/foo` names the document `foo.*` if there is one — the file wins over a
+    folder of the same name — and otherwise the folder's index, `foo/index.html`
+  - `/foo/` always names the folder's index
+- Every folder that holds documents has an index page. Which source produces
+  it is decided by one precedence list, highest first:
+  1. a hand-written `index.html`
+  2. `index.mdx`, `index.md`, `index.txt`, `index.yml`
+  3. `_index.*` in the same extension order
+  4. `home.*`, then `_home.*`
+  5. `<foldername>.*` (the file also renders to its own path)
+  6. the generated auto-index listing
+- The same list decides which of several sources for one output path is
+  rendered (`index.mdx` beside `index.md`: the `.mdx`; `foo.md` beside a
+  hand-written `foo.html`: the `.html`). The shadowed source is not rendered,
+  indexed or listed, and a warning names both files. Removing the winner
+  promotes the next candidate on the next build.
+- A frontmatter-only `index.md` supplies the folder's label; the auto-index is
+  still the page.

package/bin/ursa.js

@@ -60,6 +60,11 @@ yargs(hideBin(process.argv))
           describe: 'Emit only the .json data files — no HTML, XML, images, static assets, search indices or menu data',
           type: 'boolean',
           default: false
+        })
+        .option('explain', {
+          describe: 'Log, for every output that was rebuilt, the input that changed',
+          type: 'boolean',
+          default: false
         });
     },
     async (argv) => {
@@ -71,6 +76,7 @@ yargs(hideBin(process.argv))
       const clean = argv.clean;
       const promoteChangelog = argv['promote-changelog'] || null;
       const jsonOnly = argv['json-only'];
+      const explain = argv.explain;
 
       console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
       if (whitelist) {
@@ -96,7 +102,8 @@ yargs(hideBin(process.argv))
           _whitelist: whitelist,
           _exclude: exclude,
           _clean: clean,
-          _jsonOnly: jsonOnly
+          _jsonOnly: jsonOnly,
+          _explain: explain
         });
         console.log('Site generation completed successfully!');
       } catch (error) {
@@ -158,6 +165,11 @@ yargs(hideBin(process.argv))
         .option('promote-changelog', {
           describe: 'Path to a markdown file to render at the output root (sibling of index.html)',
           type: 'string'
+        })
+        .option('explain', {
+          describe: 'Log, for every output that was rebuilt, the input that changed',
+          type: 'boolean',
+          default: false
         });
     },
     async (argv) => {
@@ -194,6 +206,7 @@ yargs(hideBin(process.argv))
           _whitelist: whitelist,
           _exclude: exclude,
           _clean: clean,
+          _explain: argv.explain,
           strictPort: argv['strict-port']
         });
       } catch (error) {

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

@@ -1465,6 +1465,150 @@
   }
 }
 
+/* Named menus (`{menu:<id>}` anchors) render inside the article too, as a
+   static block where the author put them.  Same treatment as the breadcrumbs:
+   Ursa's chrome, scoped, unlayered.  Horizontal is a strip of items with
+   hover dropdowns for children; vertical is a stacked list, TOC-like. */
+@scope (nav.ursa-menu) {
+  :scope {
+    font-size: 0.9rem;
+    margin: 0.5rem 0 1rem;
+    color: var(--text-color);
+  }
+
+  ul {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  li {
+    margin: 0;
+    padding: 0;
+  }
+
+  a, span {
+    display: block;
+    text-decoration: none;
+    white-space: nowrap;
+  }
+
+  /* Same colour as the top menu, visited or not: this is navigation, not
+     prose, and it may sit outside any section the site colours. */
+  a, a:visited {
+    color: var(--text-color);
+  }
+
+  a:hover {
+    text-decoration: none;
+  }
+
+  /* --- horizontal: a strip, children in hover dropdowns --- */
+  :scope.ursa-menu-horizontal > ul {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.25rem;
+  }
+
+  :scope.ursa-menu-horizontal > ul > li {
+    position: relative;
+  }
+
+  :scope.ursa-menu-horizontal > ul > li > a,
+  :scope.ursa-menu-horizontal > ul > li > span {
+    padding: 0.3rem 0.75rem;
+    border-radius: 4px;
+    transition: background-color 0.15s ease;
+  }
+
+  :scope.ursa-menu-horizontal > ul > li > a:hover {
+    background-color: color-mix(in srgb, var(--text-color) 10%, transparent);
+  }
+
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-current > a,
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-active > a {
+    font-weight: 600;
+    background-color: var(--widget-bg);
+    box-shadow: inset 0 0 0 1px var(--widget-border);
+  }
+
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-has-children > a::after,
+  :scope.ursa-menu-horizontal > ul > li.ursa-menu-has-children > span::after {
+    content: '▼';
+    font-size: 0.4em;
+    margin-left: 6px;
+    opacity: 0.6;
+    vertical-align: middle;
+  }
+
+  :scope.ursa-menu-horizontal li > ul {
+    display: none;
+    position: absolute;
+    top: 100%;
+    left: 0;
+    min-width: 12rem;
+    background-color: var(--widget-bg);
+    border: 1px solid var(--widget-border);
+    border-radius: 4px;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+    z-index: 1005;
+  }
+
+  :scope.ursa-menu-horizontal li:hover > ul {
+    display: block;
+  }
+
+  :scope.ursa-menu-horizontal li li {
+    position: relative;
+  }
+
+  :scope.ursa-menu-horizontal li li > a,
+  :scope.ursa-menu-horizontal li li > span {
+    padding: 0.5rem 1rem;
+  }
+
+  :scope.ursa-menu-horizontal li li > a:hover {
+    background-color: color-mix(in srgb, var(--text-color) 10%, transparent);
+  }
+
+  :scope.ursa-menu-horizontal li li.ursa-menu-current > a {
+    font-weight: 600;
+  }
+
+  /* third level and deeper fly out to the side */
+  :scope.ursa-menu-horizontal li li > ul {
+    top: 0;
+    left: 100%;
+  }
+
+  /* --- vertical: stacked, nested levels indented --- */
+  :scope.ursa-menu-vertical a,
+  :scope.ursa-menu-vertical span {
+    padding: 0.25rem 0.7rem;
+    border-left: 2px solid transparent;
+    white-space: normal;
+  }
+
+  :scope.ursa-menu-vertical a:hover {
+    background-color: color-mix(in srgb, var(--text-color) 8%, transparent);
+  }
+
+  :scope.ursa-menu-vertical li.ursa-menu-current > a {
+    font-weight: 600;
+    border-left-color: var(--text-color);
+  }
+
+  :scope.ursa-menu-vertical li.ursa-menu-active > a {
+    font-weight: 600;
+  }
+
+  :scope.ursa-menu-vertical li > ul {
+    margin-left: 0.7rem;
+    border-left: 1px solid var(--widget-border);
+  }
+}
+
 
 /* --------------------------------------------------------------------------
    Document content.  Layered *and* scoped: layered so site CSS always wins,

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

@@ -84,6 +84,15 @@ document.addEventListener('DOMContentLoaded', () => {
     // Start loading menu data immediately
     loadMenuData();
 
+    // `ursa serve` says the menu data changed (a document was added or
+    // renamed somewhere): refetch and re-render in place rather than reload.
+    document.addEventListener('ursa:data-updated', (e) => {
+        if (!(e.detail?.what || []).includes('menu')) return;
+        menuDataLoaded = false;
+        menuDataLoading = false;
+        loadMenuData();
+    });
+
     /**
      * Find item by path string
      */
@@ -557,7 +566,7 @@ function initTopMenu() {
     const menuUrl = customMenuPath || '/public/menu-data.json';
     
     // Load menu data and render both top menu and mobile menu
-    fetch(menuUrl)
+    const loadTopMenu = () => fetch(menuUrl)
         .then(response => response.json())
         .then(data => {
             const menuData = data.menuData || data;
@@ -567,6 +576,12 @@ function initTopMenu() {
         .catch(error => {
             console.error('Failed to load top menu data:', error);
         });
+    loadTopMenu();
+
+    // `ursa serve` says the menu data changed: refetch and re-render in place
+    document.addEventListener('ursa:data-updated', (e) => {
+        if ((e.detail?.what || []).includes('menu')) loadTopMenu();
+    });
     
     // Set up home button (desktop) / hamburger (mobile)
     setupMenuButton(menuButton, navMain);
@@ -715,6 +730,8 @@ function isCurrentTopMenuPage(href) {
  * Render the top navigation menu
  */
 function renderTopMenu(container, menuData) {
+    // Re-rendered in place when the menu data changes under `ursa serve`
+    container.innerHTML = '';
     const ul = document.createElement('ul');
     ul.className = 'top-menu-level';
     

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

@@ -33,6 +33,17 @@ class GlobalSearch {
     // Start loading the indices immediately (but don't block)
     this.loadSearchIndex();
     this.loadFullTextIndex();
+
+    // `ursa serve` says the indices changed: refetch them in place
+    document.addEventListener('ursa:data-updated', (e) => {
+      if (!(e.detail?.what || []).includes('search')) return;
+      window.SEARCH_INDEX = null;
+      window.FULLTEXT_INDEX = null;
+      this.indexLoaded = false;
+      this.fullTextLoaded = false;
+      this.loadSearchIndex();
+      this.loadFullTextIndex();
+    });
   }
   
   wrapSearchInput() {

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

@@ -7,10 +7,23 @@ document.addEventListener('DOMContentLoaded', () => {
     let currentSection = document.createElement('section');
     currentSection.classList.add('sectionOuter');
 
+    // The page header stays outside any section: the breadcrumbs, and any
+    // named menu (`{menu:…}`) anchored above the first heading. A menu placed
+    // further down is part of its section like any other content.
+    const preamble = [];
+    let inPreamble = true;
+
     for (let i = 0; i < children.length; i++) {
         const el = children[i];
-        // Skip breadcrumb nav — it stays outside sections
-        if (el.classList && el.classList.contains('breadcrumbs')) continue;
+        if (el.classList && el.classList.contains('breadcrumbs')) {
+            preamble.push(el);
+            continue;
+        }
+        if (inPreamble && el.classList && el.classList.contains('ursa-menu')) {
+            preamble.push(el);
+            continue;
+        }
+        inPreamble = false;
         if (el.tagName === 'H1' && currentSection.childNodes.length > 0) {
             sections.push(currentSection);
             currentSection = document.createElement('section');
@@ -22,18 +35,13 @@ document.addEventListener('DOMContentLoaded', () => {
         sections.push(currentSection);
     }
 
-    // Preserve breadcrumb nav before clearing
-    const breadcrumbs = article.querySelector('.breadcrumbs');
-
     // Remove all existing children
     while (article.firstChild) {
         article.removeChild(article.firstChild);
     }
 
-    // Re-insert breadcrumbs at the top, outside any section
-    if (breadcrumbs) {
-        article.appendChild(breadcrumbs);
-    }
+    // Re-insert the header at the top, outside any section
+    preamble.forEach(el => article.appendChild(el));
 
     // Append new sections
     sections.forEach(section => article.appendChild(section));

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

@@ -141,6 +141,10 @@ class WidgetManager {
     
     // Initialize recent activity widget
     this.initRecentActivityWidget();
+    // `ursa serve` says recent activity changed: refetch in place
+    document.addEventListener('ursa:data-updated', (e) => {
+      if ((e.detail?.what || []).includes('recent-activity')) this.initRecentActivityWidget();
+    });
     
     // Track current page view and initialize suggested content widget
     this.trackPageView();

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.96.0",
+  "version": "0.98.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -25,7 +25,6 @@
   },
   "dependencies": {
     "compression": "^1.7.4",
-    "directory-tree": "^3.3.2",
     "esbuild": "^0.27.3",
     "express": "^4.18.2",
     "fs-extra": "^10.1.0",

package/src/dev.js

@@ -39,6 +39,7 @@ import { getTemplates, getMenu, findAllCustomMenus, getCustomMenuForFile, getTra
 import { findCustomMenu, extractMenuFrontmatter, parseCustomMenu, combineAutoAndManualMenu } from "./helper/customMenu.js";
 import { getAndIncrementBuildId } from "./helper/ursaConfig.js";
 import { resolvePort } from "./helper/portUtils.js";
+import { candidatesForOutput } from "./helper/build/precedence.js";
 import { findAllStyleCss } from "./helper/findStyleCss.js";
 import { bundleMetaTemplateAssets, generateSeparateCssTags, generateSeparateJsTags, clearMetaBundleCache } from "./helper/assetBundler.js";
 
@@ -213,30 +214,19 @@ async function resolveSourceFile(urlPath) {
   
   // Remove leading slash for joining
   const relativePath = cleanPath.startsWith('/') ? cleanPath.slice(1) : cleanPath;
-  
-  // Try different file extensions and patterns
+
+  // The one precedence list (helper/build/precedence.js): a document named
+  // like the URL, then the folder's index candidates — index, _index, home,
+  // _home, the folder's own name — .mdx before .md before .txt before .yml.
   const candidates = [
-    { path: join(source, relativePath + '.md'), type: '.md' },
-    { path: join(source, relativePath + '.mdx'), type: '.mdx' },
-    { path: join(source, relativePath + '.txt'), type: '.txt' },
-    { path: join(source, relativePath, 'index.md'), type: '.md' },
-    { path: join(source, relativePath, 'index.mdx'), type: '.mdx' },
-    { path: join(source, relativePath, 'index.txt'), type: '.txt' },
-  ];
-  
-  // Also try folder-named file (e.g., /foo/bar -> /foo/bar/bar.md)
-  const folderName = basename(relativePath);
-  if (folderName) {
-    candidates.push(
-      { path: join(source, relativePath, folderName + '.md'), type: '.md' },
-      { path: join(source, relativePath, folderName + '.mdx'), type: '.mdx' },
-      { path: join(source, relativePath, folderName + '.txt'), type: '.txt' }
-    );
-  }
-  
-  for (const candidate of candidates) {
-    if (existsSync(candidate.path)) {
-      return { sourcePath: candidate.path, type: candidate.type };
+    ...candidatesForOutput(relativePath + '.html'),
+    ...candidatesForOutput(join(relativePath, 'index.html')),
+  ].filter((c) => typeof c === 'string' && !c.endsWith('.html'));
+
+  for (const rel of candidates) {
+    const path = join(source, rel);
+    if (existsSync(path)) {
+      return { sourcePath: path, type: extname(rel) };
     }
   }