@kenjura/ursa 0.93.0 → 0.96.0

package/CHANGELOG.md

@@ -1,3 +1,57 @@
+# 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
+
+`generate --json-only` builds the data and skips the site.
+
+ursa emits a `.json` beside every document and a `<dir>.json` record list beside every directory, and those files are useful on their own — an application can ingest a docs repo at build time and never serve the HTML. Getting them, though, meant paying for the whole site: rendering every page, resizing every image, bundling the React runtime, and writing a full-text index nobody would query. On the system8 docs that is 2.85s and 88 MB to obtain 8.8 MB of JSON.
+
+- **`--json-only` (`-j`) emits only the data files.** Skipped: HTML, XML, images and their previews, meta/template assets, the React runtime, per-folder CSS/JS bundles, static file copying (fonts, audio, video, PDFs), the search and full-text indices, `menu-data.json`, `recent-activity.json`, and auto-generated index pages. On the system8 docs: **1.12s and 8.8 MB**, down from 2.85s and 88 MB.
+- **The JSON is byte-identical to a full build's**, not merely similar — verified across all 1,475 content files of the system8 docs, and asserted in the test suite. Every step the mode skips operates on the assembled *page*: `bodyHtml` in the JSON is the pre-template render, and `transformImageTags`, `markInactiveLinks` and `resolveRelativeUrls` only ever rewrote the finished HTML. So there is nothing for image processing or template bundling to contribute to it.
+- **The directory record lists are kept.** They are the one thing a data consumer most wants — `character/powers.json` is the list of every power with its frontmatter — so only the directory's *listing page* is skipped, never its `.json`.
+
+Mixing modes against one source tree is safe. The `.ursa` hash cache lives in the source and is shared, so the per-document output check now asks only for the outputs the current mode emits: a JSON-only run after a full build skips work (the `.json` is present and identical either way), and a full build after a JSON-only run regenerates, because its `.html` and `.xml` are missing. That check already existed for a related reason — one hash cache serving several output directories — and it extends to modes for free.
+
+Two pieces of build state are deliberately not written by a JSON-only run. The dependency graph is skipped because registration lives inside the page assembly the mode skips, so saving would replace a full build's graph with an empty one. The watch-mode cache is skipped because it would be seeded with unbundled templates and an empty image map, which would make a later single-file regeneration emit an unstyled page.
+
+# 0.94.0
+2026-09-04
+
+`config.json { hidden: true }` now actually ignores a folder.
+
+It was documented as "hide from menu and don't generate files", and it did neither reliably. `generate` filtered articles and directories, but every other category was derived from an unfiltered list, so a hidden folder still had its images, fonts, audio and video copied into the output and its hand-written HTML carried across. Auto-index listings never consulted the setting at all, so a hidden folder was listed — with working-looking links — in its parent's index. `serve` rendered its pages on request, which is the worst version of the bug: the page works all through development and 404s in production, exactly the failure the setting exists to prevent.
+
+- **One filter, applied once.** `generate` now drops hidden paths from the whole source file list, ahead of classification, instead of re-checking in each category. Articles, directories, images, media and hand-written HTML all inherit it, so no category can be missed — which is how images and media came to be copied out of hidden folders in the first place.
+- **Auto-indices skip hidden folders**, in all three listing paths: from source, from output, and the fallback index generated for a folder without one. The output-scanning path checks the *source* tree, so a folder hidden after it was generated does not reappear from stale files left in `output/`.
+- **A folder holding nothing but a hidden subfolder is no longer treated as having content**, and so is not linked as if it had pages.
+- **`serve` returns 404 for anything under a hidden folder** — documents, images, `config.json` itself — from a single gate ahead of the static-file fallbacks. `serve` and `generate` now agree.
+- **The menu check no longer depends on the folder having children**, so an empty hidden folder is skipped too.
+
+`isFolderHidden()` accepts file paths as well as directories: the walk begins at the path itself, and a file has no `config.json` of its own, so its ancestors decide. That is what lets one predicate filter a mixed list of files and directories. Its shallow companion `isFolderSelfHidden()` tests one folder without a docroot, for the auto-index builders, which know only the folder they are listing.
+
+Files already written to `output/` before a folder was hidden are still not deleted — nothing links to them any more, but removing them needs `--clean`. That is the general "generate never deletes" behaviour, unchanged here.
+
 # 0.93.0
 2026-09-03
 

package/README.md

@@ -67,6 +67,35 @@ Start a development server that:
 - `--whitelist, -w` - Path to whitelist file containing patterns for files to include
 - `--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)
+
+### JSON-Only Builds
+
+`--json-only` builds the data and skips the site:
+
+```bash
+ursa content --json-only --output data
+```
+
+What it emits: every document's `<name>.json` and every directory's `<dir>.json`
+record list — the same files a normal build writes, byte for byte.
+
+What it skips: HTML, XML, images and their previews, meta/template assets, the
+React runtime, per-folder CSS/JS bundles, static file copying (fonts, audio,
+video, PDFs), the search and full-text indices, `menu-data.json`,
+`recent-activity.json`, and auto-generated index pages.
+
+This is for pipelines that consume ursa's JSON as data rather than publishing a
+site — ingesting a docs repo into an application at build time, for example.
+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`.
 
 ### Whitelist File Format
 
@@ -124,6 +153,44 @@ old-content/v1
 test/fixtures
 ```
 
+### Ignoring a Folder
+
+To keep a folder out of the build permanently — working notes, prompt
+scratchpads, raw source material — put a `config.json` in it:
+
+```json
+{
+  "hidden": true
+}
+```
+
+The folder and everything beneath it then take no part in the build:
+
+- no HTML is rendered from its documents
+- its images, fonts and other static assets are not copied to the output
+- it does not appear in the sidebar menu, in any auto-index, or in breadcrumbs
+- its text is not added to the search index
+- `ursa serve` returns 404 for anything under it, matching what `generate`
+  produces
+
+The files stay where they are in the source tree; the site simply behaves as
+though they were not there.
+
+This differs from `--exclude` in scope and in lifetime: `--exclude` is a flag on
+one invocation, useful for a one-off or a per-environment build, while
+`config.json` travels with the content and applies to every build and every
+person who checks the repo out.
+
+`config.json` accepts a few other keys, all of which apply to the folder it
+sits in:
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `hidden` | boolean | Ignore this folder and its subtree entirely (above) |
+| `label` | string | Name to show for this folder in menus and indices |
+| `icon` | string | URL of an icon to show beside it in the menu |
+| `openMenuItems` | string[] | Root `config.json` only: folders to expand by default |
+
 ### Large Workloads
 
 For sites with many documents (hundreds or thousands), you may need to increase Node.js memory limits:
@@ -251,6 +318,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:

package/bin/ursa.js

@@ -54,6 +54,12 @@ 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('json-only', {
+          alias: 'j',
+          describe: 'Emit only the .json data files — no HTML, XML, images, static assets, search indices or menu data',
+          type: 'boolean',
+          default: false
         });
     },
     async (argv) => {
@@ -64,7 +70,8 @@ yargs(hideBin(process.argv))
       const exclude = argv.exclude || null;
       const clean = argv.clean;
       const promoteChangelog = argv['promote-changelog'] || null;
-      
+      const jsonOnly = argv['json-only'];
+
       console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
       if (whitelist) {
         console.log(`Using whitelist: ${whitelist}`);
@@ -75,7 +82,10 @@ yargs(hideBin(process.argv))
       if (clean) {
         console.log(`Clean build: ignoring cached hashes`);
       }
-      
+      if (jsonOnly) {
+        console.log(`JSON-only build: emitting .json data files only`);
+      }
+
       let promoted = { stagedFile: null, cleanup: async () => {} };
       try {
         promoted = await stagePromotedChangelog({ changelogPath: promoteChangelog, sourceDir: source });
@@ -85,7 +95,8 @@ yargs(hideBin(process.argv))
           _output: output,
           _whitelist: whitelist,
           _exclude: exclude,
-          _clean: clean
+          _clean: clean,
+          _jsonOnly: jsonOnly
         });
         console.log('Site generation completed successfully!');
       } 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/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/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.93.0",
+  "version": "0.96.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/dev.js

@@ -372,6 +372,15 @@ async function renderDocument(urlPath) {
   }
   
   const { sourcePath, type } = resolved;
+
+  // `hidden: true` means the folder takes no part in the build. `generate`
+  // writes nothing for it, so serving it on demand would make `serve` and
+  // `generate` disagree — the page works all through development and 404s in
+  // production, the exact failure mode this is meant to prevent.
+  if (isFolderHidden(dirname(sourcePath), source)) {
+    return null;
+  }
+
   const ext = type;
   const base = basename(sourcePath, ext);
   const dir = addTrailingSlash(dirname(sourcePath)).replace(source, "");
@@ -834,6 +843,26 @@ export async function dev({
   app.use(async (req, res, next) => {
     const url = req.url;
     
+    // Nothing under a folder that config.json marks `hidden: true` is served.
+    //
+    // This gate sits ahead of everything, including the `express.static`
+    // fallbacks mounted below — falling through with `next()` would just hand
+    // the file to them. `generate` writes no output for a hidden folder, so
+    // anything served here would work all through development and 404 in
+    // production, which is precisely what the setting exists to avoid.
+    let requestedSourcePath = null;
+    try {
+      requestedSourcePath = join(sourceDir, decodeURIComponent(url.split('?')[0]));
+    } catch (e) {
+      // Malformed percent-encoding — not a path we can classify; let it fall through
+    }
+    // Tested against the path itself, not its parent: `/foo/_art/` and
+    // `/foo/_art/index.html` must both be refused, and a file simply has no
+    // config.json of its own, so the ancestors decide either way.
+    if (requestedSourcePath && isFolderHidden(requestedSourcePath, sourceDir)) {
+      return res.status(404).send('<h1>404 Not Found</h1>');
+    }
+    
     // Handle search index requests
     if (url === '/public/search-index.json' || url === '/public/fulltext-index.json') {
       if (!devState.searchReady) {

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

@@ -0,0 +1,89 @@
+import { join } from "path";
+import { mkdtemp, mkdir, writeFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import {
+  clearConfigCache,
+  isFolderHidden,
+  isFolderSelfHidden,
+} from "../folderConfig.js";
+
+let source;
+beforeEach(async () => {
+  source = await mkdtemp(join(tmpdir(), "ursa-folderconfig-"));
+  clearConfigCache();
+});
+afterEach(async () => {
+  await rm(source, { recursive: true, force: true });
+});
+
+async function hide(...segments) {
+  const dir = join(source, ...segments);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "config.json"), JSON.stringify({ hidden: true }));
+  return dir;
+}
+
+describe("isFolderHidden", () => {
+  it("matches the hidden folder itself", async () => {
+    const art = await hide("everdew", "_art");
+    expect(isFolderHidden(art, source)).toBe(true);
+  });
+
+  it("matches a descendant folder of a hidden folder", async () => {
+    await hide("everdew", "_art");
+    const nested = join(source, "everdew", "_art", "prompts", "people");
+    await mkdir(nested, { recursive: true });
+    expect(isFolderHidden(nested, source)).toBe(true);
+  });
+
+  it("matches file paths, not just directories", async () => {
+    // The build filters one list holding both files and directories through
+    // this predicate, so a file must resolve via its ancestors.
+    await hide("everdew", "_art");
+    expect(
+      isFolderHidden(join(source, "everdew", "_art", "prompts.md"), source)
+    ).toBe(true);
+    expect(
+      isFolderHidden(join(source, "everdew", "_art", "img", "map.png"), source)
+    ).toBe(true);
+  });
+
+  it("leaves siblings and ancestors of a hidden folder visible", async () => {
+    await hide("everdew", "_art");
+    await mkdir(join(source, "everdew", "people"), { recursive: true });
+    expect(isFolderHidden(join(source, "everdew", "people"), source)).toBe(false);
+    expect(isFolderHidden(join(source, "everdew"), source)).toBe(false);
+    expect(
+      isFolderHidden(join(source, "everdew", "people", "alice.md"), source)
+    ).toBe(false);
+  });
+
+  it("ignores a config.json that does not set hidden", async () => {
+    const dir = join(source, "everdew");
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "config.json"), JSON.stringify({ label: "Everdew" }));
+    expect(isFolderHidden(dir, source)).toBe(false);
+  });
+
+  it("tolerates a trailing slash on the docroot", async () => {
+    const art = await hide("everdew", "_art");
+    expect(isFolderHidden(art, source + "/")).toBe(true);
+  });
+});
+
+describe("isFolderSelfHidden", () => {
+  it("is true only for the folder carrying the config, not its descendants", async () => {
+    const art = await hide("everdew", "_art");
+    const nested = join(art, "prompts");
+    await mkdir(nested, { recursive: true });
+
+    expect(isFolderSelfHidden(art)).toBe(true);
+    expect(isFolderSelfHidden(nested)).toBe(false);
+  });
+
+  it("is false for a folder with no config.json", async () => {
+    const dir = join(source, "people");
+    await mkdir(dir, { recursive: true });
+    expect(isFolderSelfHidden(dir)).toBe(false);
+  });
+});