@kenjura/ursa 0.95.0 → 0.97.0

package/CHANGELOG.md

@@ -1,3 +1,51 @@
+# 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
+
+MDX pages hydrate their components, not the page; Recent Activity is dated from git.
+
+`hydrate: true` on an `.mdx` page broke the page's layout, and the break got worse the more headings the page had: sticky H1s piled on top of one another, breadcrumbs vanished, and the table of contents listed the title twice. The hydration script handed React the whole of `#main-content` and the whole MDX component and expected them to match. They never did. The template puts breadcrumbs and (sometimes) a title heading inside that container, and the default template's `sectionify.js` rewrites it on `DOMContentLoaded`, wrapping each H1 section in `<section class="sectionOuter">` — and the hydration script, being the last script in the body, always ran after it. React reported the mismatch (error #418), discarded the server-rendered DOM and rendered the component from scratch, with none of the template's structure.
+
+- **Each component imported into the `.mdx` is now an island.** An esbuild plugin wraps the default export of every `.jsx`/`.tsx` the entry imports (and `.js`/`.ts` under `_components/`), so the build renders it inside `<ursa-island data-island="N">` and the browser hydrates that element as its own React root, against exactly the markup the build produced for it. The Markdown around the islands is never handed to React; `sectionify`, breadcrumbs and the TOC can do what they like to it.
+- **Function props keep working.** The client still runs the whole bundled MDX module — into a detached root, purely to execute the tree — so each island receives its real props, `filter={fn}` included, rather than a serialized replay. Island numbering is a per-render counter taken in `useState`'s lazy initializer, so it increments once per mount in tree order on both sides.
+- **Components imported by components are not islands.** They render inside their parent's root, as before; nesting would put one root inside another. Named exports and non-function imports pass through untouched.
+- **React 19's hoisted `<link rel="preload">` is stripped** from the MDX render. It carried the un-rewritten relative image path, so it fetched nothing useful, and its position ahead of the first `<h1>` is what defeated the "body starts with a heading" check and produced the duplicate title.
+- **`react-runtime.js` now exposes `createRoot`** and carries a version marker; `buildReactRuntime` rebuilds an older runtime found in `output/public/` instead of reusing it.
+- **`window.ursa.contentChanged(root)` tells the template the article changed.** The template's scripts read the article once, on `DOMContentLoaded`: `sticky.js` collects the headings it marks `.stuck`, `toc-generator.js` builds the table of contents from them. A component that fetches data and renders a list with its own headings after that point was invisible to both — its H2s never rolled up into the stuck H1 and piled on top of each other, and the TOC did not list them. The helper dispatches `ursa:content-changed` on `document` (coalesced per task, so a multi-step render can call it freely) and both scripts re-read the headings on it: sticky state is recomputed, and the TOC is rebuilt in place with existing heading ids preserved. `content-hooks.js` is a new template script, loaded first.
+
+**Recent Activity is dated from git, not from the build.** The feed took each document's time from a `contentTimestamps` map in `.ursa.json` that was set to the build time whenever the document was regenerated. Under `--clean` every document regenerates, so every entry got the same time and the feed showed ten arbitrary pages. The map also grew to one line per document and changed on every build, which in a repo that commits `.ursa.json` meant a diff on every commit.
+
+- **One `git log --name-only` pass over the source directory** at the start of a build gives every document's last-commit time in a single process (0.4s on 1,400 documents). A document with uncommitted changes, an untracked one, or any document when the source is not a git work tree, is dated by file mtime instead.
+- **A shallow clone is detected and warned about**, since with one fetched commit every document looks edited in it. The fix is `fetch-depth: 0` on the checkout.
+- **`contentTimestamps` is gone from `.ursa.json`**; the next build removes the stale key. `serve`'s single-file regeneration dates the changed document the same way instead of stamping "now".
+
+`hydrate: true` means what it did: emit the client bundle. Without it, islands are rendered at build time and inert. React context does not cross island boundaries, which no MDX page relied on — there is no provider above the components to begin with. Design notes are in `docs/changes/island-hydration.md`, and the README gains an "MDX and Interactive Components" section.
+
 # 0.95.0
 2026-09-06
 

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
 
@@ -318,6 +362,48 @@ Both panels carry it: `#widget-dropdown` for the right-hand widgets (`toc`,
 Ursa uses this hook itself, to lay the TOC out along the bottom of the viewport
 on a narrow screen.
 
+## Recent Activity
+
+The site's Recent Activity widget lists the ten most recently edited documents. A document is dated by the last git commit that touched it — one `git log` pass over the source directory at the start of a build — or by its file mtime if it has uncommitted changes, is untracked, or the source is not in a git work tree. The build's own time never enters into it, so `--clean` does not reset the feed.
+
+This needs git history to be present. A shallow checkout (GitHub Actions' `actions/checkout` defaults to depth 1) makes every document look edited in the one fetched commit; ursa warns when it sees one. Use `fetch-depth: 0`.
+
+## MDX and Interactive Components
+
+A `.mdx` document is Markdown that can import and use React components. Put components in a `_components/` folder anywhere from the docroot down to the document's own folder, and import them without a relative prefix:
+
+```mdx
+---
+hydrate: true
+---
+import PowerList from '_components/PowerList.jsx';
+
+# Spells
+
+<PowerList class="Witch" groupBy="school" />
+```
+
+Every document is rendered to HTML at build time, components included, so a page reads the same with JavaScript off. `hydrate: true` in the frontmatter additionally ships the page's components to the browser so they can run there.
+
+Hydration works per component, not per page. Each component imported directly into the `.mdx` file becomes an **island**: the build wraps its output in `<ursa-island data-island="N">`, and in the browser each island is hydrated as its own React root against exactly the markup the build produced for it. The Markdown around the islands is never handed to React, so the template is free to rearrange it — section wrappers for sticky headings, breadcrumbs, the table of contents — without any hydration mismatch. Two things follow from this:
+
+- A component's first render must produce the same markup in the browser as it did at build time (the usual hydration contract). Fetch data in an effect and render a placeholder first.
+- React context does not cross from one island to another. Components that need to share state should be one island, with the shared state inside it.
+
+`island` wrapping applies to the default export of any `.jsx`/`.tsx` file the `.mdx` imports, and of `.js`/`.ts` files under `_components/`. Components that a component imports are not islands themselves — they render inside their parent's root. Non-function imports (JSON, data) pass through untouched.
+
+### Telling the template the article changed
+
+The template's scripts read the article once, when the page loads: the sticky headings and the table of contents are both built from the headings present at that moment. A component that renders content later — a list fetched from a JSON file, say, with headings of its own — should say so once it has:
+
+```jsx
+useEffect(() => {
+  if (items.length) window.ursa?.contentChanged?.(rootRef.current);
+}, [items]);
+```
+
+`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.
+
 ## 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:
@@ -397,11 +483,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/content-hooks.js

@@ -0,0 +1,45 @@
+// Content-change hook
+//
+// The template's scripts read the article once, on DOMContentLoaded: sticky.js
+// collects the headings it will mark .stuck, toc-generator.js builds the table
+// of contents from them. Anything that adds content to the article after that
+// point — an island that fetches data and renders a list with its own headings —
+// is invisible to them unless it says so.
+//
+// This is how it says so. A script that has changed the article calls
+//
+//     window.ursa.contentChanged(root)
+//
+// where `root` is the element whose contents changed (optional; defaults to the
+// article). That dispatches `ursa:content-changed` on `document`, with the root
+// in `event.detail.root`, and each template script that keeps a view of the
+// article listens for it and re-reads what it needs. Calls made in the same
+// task are coalesced into one event (a macrotask, not an animation frame, so it
+// also fires in a background tab), so a component that renders in several
+// steps can call it freely.
+//
+// Dispatching the event directly works just as well; the helper exists so a
+// caller does not have to know the event's name.
+(() => {
+  const EVENT = 'ursa:content-changed';
+  let queued = null;
+
+  function contentChanged(root) {
+    if (root && !(root instanceof Element)) root = null;
+    // Coalesce: keep the broadest root seen so far
+    if (queued) {
+      if (queued.root && root && queued.root !== root && !queued.root.contains(root)) {
+        queued.root = null;
+      }
+      return;
+    }
+    queued = { root: root || null };
+    setTimeout(() => {
+      const detail = { root: queued.root || document.querySelector('article#main-content') };
+      queued = null;
+      document.dispatchEvent(new CustomEvent(EVENT, { detail }));
+    });
+  }
+
+  window.ursa = Object.assign(window.ursa || {}, { contentChanged, CONTENT_CHANGED_EVENT: EVENT });
+})();

package/meta/templates/default-template/index.html

@@ -162,6 +162,7 @@
     <div id="global-nav">
     </div>
 
+    <script src="/public/content-hooks.js"></script>
     <script src="/public/toc.js"></script>
     <script src="/public/toc-generator.js"></script>
     <script src="/public/menu.js"></script>

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/sticky.js

@@ -2,7 +2,9 @@ document.addEventListener('DOMContentLoaded', () => {
     const article = document.querySelector('article#main-content');
     if (!article) return;
 
-    const headings = article.querySelectorAll('h1, h2, h3');
+    // Re-collected on ursa:content-changed, since an island may add headings
+    // after load (see content-hooks.js).
+    let headings = article.querySelectorAll('h1, h2, h3');
 
     function updateStuckState() {
         let currentStuckHeading = null;
@@ -70,4 +72,8 @@ document.addEventListener('DOMContentLoaded', () => {
     updateStuckState();
     window.addEventListener('scroll', updateStuckState, { passive: true });
     window.addEventListener('resize', updateStuckState);
+    document.addEventListener('ursa:content-changed', () => {
+        headings = article.querySelectorAll('h1, h2, h3');
+        updateStuckState();
+    });
 });

package/meta/templates/default-template/toc-generator.js

@@ -6,47 +6,67 @@ document.addEventListener('DOMContentLoaded', () => {
     
     if (!tocTarget || !article) return;
     
-    // Find all headings in the article
-    const headings = article.querySelectorAll('h1, h2, h3');
-    
-    if (headings.length === 0) {
-        // Hide the TOC widget button if no headings
-        const tocButton = document.querySelector('.widget-button[data-widget="toc"]');
-        if (tocButton) tocButton.style.display = 'none';
-        tocTarget.style.display = 'none';
-        return;
-    }
-    
-    // Generate TOC HTML
-    const tocList = document.createElement('ul');
-    
-    headings.forEach((heading, index) => {
-        // Create unique ID for the heading if it doesn't have one
-        if (!heading.id) {
-            const text = heading.textContent.trim()
-                .toLowerCase()
-                .replace(/[^\w\s-]/g, '') // Remove special characters
-                .replace(/\s+/g, '-'); // Replace spaces with hyphens
-            heading.id = `heading-${index}-${text}`;
-        }
-        
-        // Create TOC item
-        const listItem = document.createElement('li');
-        listItem.className = `toc-${heading.tagName.toLowerCase()}`;
-        
-        const link = document.createElement('a');
-        link.href = `#${heading.id}`;
-        link.textContent = heading.textContent;
-        link.addEventListener('click', handleTocClick);
-        
-        listItem.appendChild(link);
-        tocList.appendChild(listItem);
-    });
-    
+    // The headings the TOC currently reflects. Rebuilt on ursa:content-changed,
+    // since an island may add headings after load (see content-hooks.js).
+    let headings = [];
+    const tocButton = document.querySelector('.widget-button[data-widget="toc"]');
+
     // Add an id=toc wrapper for the toc.js sentinel-based highlighter
+    const tocList = document.createElement('ul');
     tocList.id = 'toc';
     tocTarget.appendChild(tocList);
-    
+
+    function headingId(heading, index) {
+        const text = heading.textContent.trim()
+            .toLowerCase()
+            .replace(/[^\w\s-]/g, '') // Remove special characters
+            .replace(/\s+/g, '-'); // Replace spaces with hyphens
+        let id = `heading-${index}-${text}`;
+        // A heading added later can land on an index an earlier one already used
+        let n = 2;
+        while (document.getElementById(id)) id = `heading-${index}-${text}-${n++}`;
+        return id;
+    }
+
+    // (Re)build the list from the article's current headings. Headings keep the
+    // ids they already have, so existing anchors and links stay valid.
+    function buildToc() {
+        headings = article.querySelectorAll('h1, h2, h3');
+
+        if (headings.length === 0) {
+            // Hide the TOC widget button if no headings
+            if (tocButton) tocButton.style.display = 'none';
+            tocTarget.style.display = 'none';
+            return;
+        }
+        if (tocButton) tocButton.style.display = '';
+        tocTarget.style.display = '';
+
+        tocList.replaceChildren();
+        headings.forEach((heading, index) => {
+            // Create unique ID for the heading if it doesn't have one
+            if (!heading.id) heading.id = headingId(heading, index);
+
+            // Create TOC item
+            const listItem = document.createElement('li');
+            listItem.className = `toc-${heading.tagName.toLowerCase()}`;
+
+            const link = document.createElement('a');
+            link.href = `#${heading.id}`;
+            link.textContent = heading.textContent;
+            link.addEventListener('click', handleTocClick);
+
+            listItem.appendChild(link);
+            tocList.appendChild(listItem);
+        });
+    }
+
+    buildToc();
+    document.addEventListener('ursa:content-changed', () => {
+        buildToc();
+        updateActiveTocItem();
+    });
+
     // Handle TOC link clicks for smooth scrolling
     function handleTocClick(e) {
         e.preventDefault();

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.95.0",
+  "version": "0.97.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) };
     }
   }
   

package/src/helper/__test__/contentHash.test.js

@@ -2,12 +2,22 @@ import { join } from "path";
 import { mkdtemp, rm, mkdir, writeFile, readFile } from "fs/promises";
 import { existsSync } from "fs";
 import { tmpdir } from "os";
-import {
-  enforceCacheVersion,
-  getUrsaDir,
-  loadHashCache,
-  saveHashCache,
-} from "../contentHash.js";
+import { enforceCacheVersion, getUrsaDir } from "../contentHash.js";
+
+// The cache `.ursa/` holds is the build graph. These tests only need a file
+// that must survive a matching stamp and vanish on a mismatch.
+const CACHE_FILE = "graph.json";
+async function saveHashCache(dir, map) {
+  await mkdir(getUrsaDir(dir), { recursive: true });
+  await writeFile(join(getUrsaDir(dir), CACHE_FILE), JSON.stringify([...map]));
+}
+async function loadHashCache(dir) {
+  try {
+    return new Map(JSON.parse(await readFile(join(getUrsaDir(dir), CACHE_FILE), "utf8")));
+  } catch {
+    return new Map();
+  }
+}
 
 let sourceDir;
 beforeEach(async () => {