@kenjura/ursa 0.96.0 → 0.97.0

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# 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
 
@@ -439,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/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/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.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 () => {

package/src/helper/assetBundler.js

@@ -13,8 +13,8 @@
 
 import * as esbuild from "esbuild";
 import { join, dirname, basename, relative, resolve } from "path";
-import { readFile, writeFile, mkdir } from "fs/promises";
-import { existsSync } from "fs";
+import { writeFile, mkdir } from "fs/promises";
+import { readFile, existsSync } from "./build/tracedFs.js";
 import { outputFile } from "fs-extra";
 
 // Cache for meta bundles so we don't rebuild them per-document
@@ -68,10 +68,13 @@ export function parseTemplateAssets(templateHtml) {
  * @param {string} templateHtml - Original template HTML
  * @param {string} templateName - Template name (used for bundle filename)
  * @param {{ cssFiles: string[], jsFiles: string[], cdnCss: string[], cdnJs: string[] }} assets - Parsed assets
+ * @param {{cssUrl?: string, jsUrl?: string}} [urls] - Bundle URLs to emit (default: /public/<name>.bundle.*)
  * @returns {string} Rewritten template HTML
  */
-export function rewriteTemplateWithBundles(templateHtml, templateName, assets) {
+export function rewriteTemplateWithBundles(templateHtml, templateName, assets, urls = {}) {
   let html = templateHtml;
+  const cssUrl = urls.cssUrl ?? `/public/${templateName}.bundle.css`;
+  const jsUrl = urls.jsUrl ?? `/public/${templateName}.bundle.js`;
 
   // Replace individual CSS <link> tags with a single bundle reference
   if (assets.cssFiles.length > 0) {
@@ -86,7 +89,7 @@ export function rewriteTemplateWithBundles(templateHtml, templateName, assets) {
       html = html.replace(pattern, "\n");
     }
     // Insert single bundle link where the first CSS link was (in <head>)
-    const bundleCssTag = `    <link rel="stylesheet" href="/public/${templateName}.bundle.css" />`;
+    const bundleCssTag = `    <link rel="stylesheet" href="${cssUrl}" />`;
     // Insert after the last CDN CSS or at the position of the first removed tag
     // Best heuristic: insert right before ${styleLink} or before </head>
     if (html.includes("${styleLink}")) {
@@ -107,7 +110,7 @@ export function rewriteTemplateWithBundles(templateHtml, templateName, assets) {
       html = html.replace(pattern, "\n");
     }
     // Insert single bundle script before ${customScript} or before </body>
-    const bundleJsTag = `    <script src="/public/${templateName}.bundle.js"></script>`;
+    const bundleJsTag = `    <script src="${jsUrl}"></script>`;
     if (html.includes("${customScript}")) {
       html = html.replace("${customScript}", bundleJsTag + "\n    ${customScript}");
     } else {
@@ -192,6 +195,19 @@ function rebaseCssUrls(css, cssFileDir, sourceDir) {
  */
 export async function bundleCss(filePaths, outputPath, { minify = true, rebaseUrls = false, sourceDir = "" } = {}) {
   if (filePaths.length === 0) return;
+  const code = await bundleCssContent(filePaths, { minify, rebaseUrls, sourceDir });
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, code);
+}
+
+/**
+ * Bundle CSS files and return the result instead of writing it.
+ * @param {string[]} filePaths - Absolute paths to CSS files to bundle
+ * @param {{ minify?: boolean, rebaseUrls?: boolean, sourceDir?: string }} options
+ * @returns {Promise<string>} Bundled (and, when possible, minified) CSS
+ */
+export async function bundleCssContent(filePaths, { minify = true, rebaseUrls = false, sourceDir = "" } = {}) {
+  if (filePaths.length === 0) return "";
 
   const allImports = [];
   const allRules = [];
@@ -224,17 +240,14 @@ export async function bundleCss(filePaths, outputPath, { minify = true, rebaseUr
         loader: "css",
         minify: true,
       });
-      await mkdir(dirname(outputPath), { recursive: true });
-      await writeFile(outputPath, result.code);
-      return;
+      return result.code;
     } catch (e) {
       console.warn(`⚠️  CSS minification failed, using unminified bundle: ${e.message}`);
     }
   }
 
-  // Fallback: write raw concatenated CSS
-  await mkdir(dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, combined);
+  // Fallback: raw concatenated CSS
+  return combined;
 }
 
 /**
@@ -251,6 +264,22 @@ export async function bundleCss(filePaths, outputPath, { minify = true, rebaseUr
  */
 export async function bundleJs(filePaths, outputPath, { minify = true, minifySyntax = true } = {}) {
   if (filePaths.length === 0) return { success: false };
+  const { success, code } = await bundleJsContent(filePaths, { minify, minifySyntax });
+  if (!success) return { success: false };
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, code);
+  return { success: true };
+}
+
+/**
+ * Bundle JS files and return the result instead of writing it.
+ * @param {string[]} filePaths - Absolute paths to JS files to bundle
+ * @param {{ minify?: boolean, minifySyntax?: boolean }} options
+ * @returns {Promise<{ success: boolean, code: string }>} success is false when the
+ *   concatenation has a syntax error (callers keep individual tags)
+ */
+export async function bundleJsContent(filePaths, { minify = true, minifySyntax = true } = {}) {
+  if (filePaths.length === 0) return { success: false, code: "" };
 
   // Concatenate all JS files with separators
   const contents = [];
@@ -268,9 +297,7 @@ export async function bundleJs(filePaths, outputPath, { minify = true, minifySyn
         minify: true,
         minifySyntax,
       });
-      await mkdir(dirname(outputPath), { recursive: true });
-      await writeFile(outputPath, result.code);
-      return { success: true };
+      return { success: true, code: result.code };
     } catch (e) {
       // If minification fails (e.g., non-standard syntax), fall back to raw concatenation
       console.warn(`⚠️  JS minification failed, trying unminified bundle: ${e.message}`);
@@ -284,13 +311,60 @@ export async function bundleJs(filePaths, outputPath, { minify = true, minifySyn
     await esbuild.transform(combined, { loader: "js" });
   } catch (e) {
     console.warn(`⚠️  JS bundle has syntax errors, keeping individual script tags: ${e.message}`);
-    return { success: false };
+    return { success: false, code: "" };
   }
 
-  // Write raw concatenated code (syntax-valid but unminified)
-  await mkdir(dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, combined);
-  return { success: true };
+  // Raw concatenated code (syntax-valid but unminified)
+  return { success: true, code: combined };
+}
+
+/**
+ * Where a template's `/public/<rel>` reference lives in the meta directory:
+ * the template's own folder first, then `meta/shared`, then (legacy) the meta
+ * root. Every probe is a recorded lookup, so moving an asset between the two
+ * folders is observed. Returns null when nothing exists.
+ */
+export function resolveMetaAssetPath(publicPath, templateDir, metaDir) {
+  const relativePath = publicPath.replace(/^\/public\//, "");
+  for (const candidate of [
+    resolve(templateDir, relativePath),
+    resolve(metaDir, "shared", relativePath),
+    resolve(metaDir, relativePath),
+  ]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Append `?v=<hash>` to every `url()` in a stylesheet whose target `lookup`
+ * knows. URLs with a query string, data: URIs, fragments and anything the
+ * lookup does not recognise are left alone. Cache-busting by content hash
+ * keeps an unchanged asset's URL stable, so pages are not rewritten for it.
+ * @param {string} css
+ * @param {(url: string) => string|null} lookup - site-absolute URL → content hash
+ */
+export function versionCssUrls(css, lookup) {
+  return css.replace(/url\(\s*(['"]?)(?!data:)([^'"\)]+?)\1\s*\)/gi, (match, quote, url) => {
+    if (url.includes("?") || url.startsWith("#")) return match;
+    const hash = lookup(url);
+    if (!hash) return match;
+    return `url(${quote}${url}?v=${hash}${quote})`;
+  });
+}
+
+/**
+ * Rewrite literal `fetch('/public/x.json')` calls in template JavaScript so
+ * the request carries the page's build id: `data-build` on <body>, set once
+ * per serve session and once per generate run. The bundle itself stays a pure
+ * function of the meta files — baking a JSON file's content hash into it
+ * would rewrite the bundle, and so every page, whenever the menu changed.
+ */
+export function rewriteJsonFetches(js) {
+  return js.replace(
+    /fetch\((['"])([^'"\)]+\.json)\1(?!\s*\+)/g,
+    (m, q, url) => `fetch(${q}${url}?v=${q}+(document.body&&document.body.dataset.build||'')`
+  );
 }
 
 /**

package/src/helper/automenu.js

@@ -1,9 +1,7 @@
-import dirTree from "directory-tree";
 import { isHiddenOrSystemPath } from "./hiddenPaths.js";
 import { extname, basename, join, dirname } from "path";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, readdirSync, isIgnoredDirEntry } from "./build/tracedFs.js";
 import { getFolderConfig, isFolderHidden, getRootConfig } from "./folderConfig.js";
-import { isMetadataOnly } from "./metadataExtractor.js";
 import {
   INDEX_EXTENSIONS,
   toDisplayName,
@@ -11,6 +9,7 @@ import {
   getMenuSortAsFromFile,
   getFolderLabel,
   getFolderSortKey,
+  readFrontmatterInfo,
 } from "./menuLabels.js";
 
 // Icon extensions to check for custom icons
@@ -208,13 +207,8 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
     
     // Skip metadata-only index files (they only provide folder metadata, not actual pages)
     if (!hasChildren && isIndexFile(baseName)) {
-      try {
-        const content = readFileSync(item.path, 'utf8');
-        if (isMetadataOnly(content)) {
-          continue; // Skip - this file doesn't produce a page
-        }
-      } catch (e) {
-        // If we can't read it, include it in the menu
+      if (readFrontmatterInfo(item.path)?.isMetadataOnly) {
+        continue; // Skip - this file doesn't produce a page
       }
     }
     
@@ -390,6 +384,37 @@ export function pruneHiddenNodes(node, source) {
   };
 }
 
+/**
+ * Build a directory tree in the shape `directory-tree` produced
+ * ({name, path, children?}), reading through the traced filesystem so the
+ * build graph records every listing the menu depends on. Entries are sorted
+ * by name; readdir order never reaches the menu.
+ * @param {string} dir - Absolute directory path
+ * @returns {object|null} Tree node, or null if `dir` cannot be listed
+ */
+function walkTree(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  const children = [];
+  for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+    // Never inputs (see tracedFs.isIgnoredDirEntry); skipping them here also
+    // keeps the walk out of a .git or node_modules sitting inside the docroot.
+    if (isIgnoredDirEntry(entry.name)) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const child = walkTree(path);
+      if (child) children.push(child);
+    } else if (entry.isFile()) {
+      children.push({ name: entry.name, path });
+    }
+  }
+  return { name: basename(dir), path: dir, children };
+}
+
 export async function getAutomenu(source, validPaths) {
   /*
    * Walk first, prune second.
@@ -406,7 +431,7 @@ export async function getAutomenu(source, validPaths) {
    * discarded; docroots do not normally contain one, and correctness on every
    * ordinary path is worth more than speed on a pathological one.
    */
-  const fullTree = dirTree(source);
+  const fullTree = walkTree(source.replace(/\/$/, ''));
   if (!fullTree) {
     throw new Error(
       `Cannot read docroot for menu generation: ${source} (does it exist and is it a directory?)`