@kenjura/ursa 0.95.0 → 0.97.0

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

@@ -0,0 +1,159 @@
+import { join } from 'path';
+import { mkdtemp, writeFile, mkdir, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { renderMDX, generateHydrationScript } from '../mdxRenderer.js';
+
+// Helper: a temp source tree with a _components/ directory
+let tempDir;
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'ursa-mdx-'));
+  await mkdir(join(tempDir, '_components'), { recursive: true });
+});
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+async function writeComponent(name, body) {
+  const path = join(tempDir, '_components', `${name}.jsx`);
+  await writeFile(path, body);
+  return path;
+}
+
+async function render(mdx, { hydrate = true } = {}) {
+  const filePath = join(tempDir, 'page.mdx');
+  await writeFile(filePath, mdx);
+  return renderMDX({ source: mdx, filePath, sourceRoot: tempDir, hydrate });
+}
+
+const COUNTER = `
+import React from 'react';
+export default function Counter({ label }) {
+  const [n, setN] = React.useState(0);
+  return <button onClick={() => setN(n + 1)}>{label}: {n}</button>;
+}
+`;
+
+// ---------------------------------------------------------------------------
+// Island wrapping
+// ---------------------------------------------------------------------------
+describe('renderMDX islands', () => {
+  test('wraps a component imported from the MDX in <ursa-island>', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { html } = await render(`
+import Counter from '_components/Counter.jsx';
+
+# Page
+
+<Counter label="Clicks" />
+`);
+    expect(html).toMatch(/<ursa-island data-island="0" data-component="Counter"[^>]*>/);
+    expect(html).toContain('<button>Clicks<!-- -->: <!-- -->0</button>');
+    expect(html).toContain('</ursa-island>');
+  });
+
+  test('numbers islands in document order', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { html } = await render(`
+import Counter from '_components/Counter.jsx';
+
+<Counter label="A" />
+
+Some prose.
+
+<Counter label="B" />
+`);
+    const ids = [...html.matchAll(/<ursa-island data-island="(\d+)"/g)].map((m) => m[1]);
+    expect(ids).toEqual(['0', '1']);
+    expect(html.indexOf('>A<')).toBeLessThan(html.indexOf('>B<'));
+  });
+
+  test('does not nest islands: a component imported by a component is rendered plainly', async () => {
+    await writeComponent('Inner', `
+import React from 'react';
+export default function Inner() { return <em>inner</em>; }
+`);
+    await writeComponent('Outer', `
+import React from 'react';
+import Inner from './Inner.jsx';
+export default function Outer() { return <div>outer <Inner /></div>; }
+`);
+    const { html } = await render(`
+import Outer from '_components/Outer.jsx';
+
+<Outer />
+`);
+    expect(html.match(/<ursa-island/g)).toHaveLength(1);
+    expect(html).toContain('data-component="Outer"');
+    expect(html).toContain('<em>inner</em>');
+  });
+
+  test('leaves the surrounding markdown outside any island', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { html } = await render(`
+import Counter from '_components/Counter.jsx';
+
+# Heading
+
+<Counter label="x" />
+
+## Sub
+`);
+    // Headings are siblings of the island, not children of it
+    expect(html).toMatch(/<h1>Heading<\/h1>\s*<ursa-island/);
+    expect(html).toMatch(/<\/ursa-island>\s*<h2>Sub<\/h2>/);
+  });
+
+  test('client bundle contains the island runtime', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { clientCode } = await render(`
+import Counter from '_components/Counter.jsx';
+
+<Counter label="x" />
+`);
+    expect(clientCode).toContain('hydrateRoot');
+    expect(clientCode).toContain('data-island');
+  });
+
+  test('hydrate: false still renders islands but emits no client code', async () => {
+    await writeComponent('Counter', COUNTER);
+    const result = await render(`
+import Counter from '_components/Counter.jsx';
+
+<Counter label="x" />
+`, { hydrate: false });
+    expect(result.html).toContain('<ursa-island');
+    expect(result.clientCode).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Preload stripping
+// ---------------------------------------------------------------------------
+describe('renderMDX preload stripping', () => {
+  test('removes React 19 hoisted <link rel="preload"> so the body starts with its heading', async () => {
+    const { html } = await render(`
+# Title
+![pic](../img/pic.jpg)
+`);
+    expect(html).not.toContain('rel="preload"');
+    expect(html.trimStart().startsWith('<h1>')).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Hydration script
+// ---------------------------------------------------------------------------
+describe('generateHydrationScript', () => {
+  test('renders into a detached root and looks up islands rather than a page container', () => {
+    const script = generateHydrationScript('return { default: function () { return null; } };');
+    expect(script).toContain('ursa-island[data-island]');
+    expect(script).toContain('createRoot(detached)');
+    expect(script).not.toContain("getElementById('main-content')");
+  });
+
+  test('escapes the bundle for embedding in a template literal', () => {
+    const script = generateHydrationScript('var s = `a${b}`; // </script>');
+    expect(script).toContain('\\`a\\${b}\\`');
+    expect(script).toContain('<\\/script>');
+  });
+});

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?)`

package/src/helper/build/__test__/autoIndex.test.js

@@ -1,9 +1,7 @@
 import { join } from "path";
-import { mkdtemp, mkdir, writeFile, rm, readFile } from "fs/promises";
-import { existsSync } from "fs";
+import { mkdtemp, mkdir, writeFile, rm } from "fs/promises";
 import { tmpdir } from "os";
-import { generateAutoIndices, generateAutoIndexHtmlFromSource } from "../autoIndex.js";
-import { clearConfigCache } from "../../folderConfig.js";
+import { generateAutoIndexHtmlFromSource } from "../autoIndex.js";
 
 let tempDir;
 let source;
@@ -19,82 +17,6 @@ afterEach(async () => {
   await rm(tempDir, { recursive: true, force: true });
 });
 
-const TEMPLATE =
-  "<html><head>${styleLink}</head><body>${menu}${body}${footer}${customScript}</body></html>";
-
-function makeProgress() {
-  const logs = [];
-  return {
-    logs,
-    log: (msg) => logs.push(msg),
-    status: () => {},
-    done: () => {},
-  };
-}
-
-function runAutoIndices(directories, generatedArticles, progress) {
-  return generateAutoIndices(
-    output,
-    directories,
-    source,
-    { "default-template": TEMPLATE },
-    "",
-    "",
-    generatedArticles,
-    new Set(),
-    new Set(),
-    "20260101000000",
-    progress,
-    null
-  );
-}
-
-describe("generateAutoIndices with empty source folders", () => {
-  it("skips output directories that were never created instead of logging an error", async () => {
-    // Source has an empty folder (guides) and a folder with a document (docs).
-    // Only docs produced output files, so output/guides does not exist.
-    await mkdir(join(source, "guides"));
-    await mkdir(join(source, "docs"));
-    await writeFile(join(source, "docs", "hello.md"), "# Hello\n\nWorld\n");
-    await mkdir(join(output, "docs"));
-    await writeFile(join(output, "docs", "hello.html"), "<html><body>Hello</body></html>");
-
-    const progress = makeProgress();
-    await runAutoIndices(
-      [join(source, "guides"), join(source, "docs")],
-      [join(source, "docs", "hello.md")],
-      progress
-    );
-
-    const errors = progress.logs.filter((m) => /Error generating auto-index/i.test(m));
-    expect(errors).toEqual([]);
-    // The missing output directory is skipped, not created
-    expect(existsSync(join(output, "guides"))).toBe(false);
-    expect(existsSync(join(output, "guides", "index.html"))).toBe(false);
-  });
-
-  it("still generates auto-indices for folders that produced output", async () => {
-    await mkdir(join(source, "guides"));
-    await mkdir(join(source, "docs"));
-    await writeFile(join(source, "docs", "hello.md"), "# Hello\n\nWorld\n");
-    await mkdir(join(output, "docs"));
-    await writeFile(join(output, "docs", "hello.html"), "<html><body>Hello</body></html>");
-
-    const progress = makeProgress();
-    await runAutoIndices(
-      [join(source, "guides"), join(source, "docs")],
-      [join(source, "docs", "hello.md")],
-      progress
-    );
-
-    // Root and docs both exist in output, so both get an index.html
-    const docsIndex = await readFile(join(output, "docs", "index.html"), "utf8");
-    expect(docsIndex).toContain('<a href="hello.html">');
-    const rootIndex = await readFile(join(output, "index.html"), "utf8");
-    expect(rootIndex).toContain('<a href="docs/index.html">');
-  });
-});
-
 describe("auto-index naming matches the automenu", () => {
   it("uses menu-label from a folder's index frontmatter, and config.json when there is no index", async () => {
     // bnw has a real index.md carrying the label; hfr has no index at all, so
@@ -140,35 +62,9 @@ describe("auto-index naming matches the automenu", () => {
 
     expect(html).toContain('<a href="SoL/index.html">SoL</a>');
   });
-
-  it("labels generated index pages with the folder's menu-label", async () => {
-    // No index.md content, so this folder gets an auto-generated index.html;
-    // its <h1> should use the label rather than the raw folder name.
-    await mkdir(join(source, "bnw"));
-    await writeFile(
-      join(source, "bnw", "config.json"),
-      JSON.stringify({ label: "BNW - Brave New World" })
-    );
-    await writeFile(join(source, "bnw", "quests.md"), "# Quests\n");
-    await mkdir(join(output, "bnw"));
-    await writeFile(join(output, "bnw", "quests.html"), "<html><body>Quests</body></html>");
-
-    await runAutoIndices([join(source, "bnw")], [join(source, "bnw", "quests.md")], makeProgress());
-
-    const bnwIndex = await readFile(join(output, "bnw", "index.html"), "utf8");
-    expect(bnwIndex).toContain("<h1>BNW - Brave New World</h1>");
-    const rootIndex = await readFile(join(output, "index.html"), "utf8");
-    expect(rootIndex).toContain('<a href="bnw/index.html">BNW - Brave New World</a>');
-  });
 });
 
 describe("folders ignored via config.json { hidden: true }", () => {
-  beforeEach(() => {
-    // getFolderConfig memoizes per absolute path; temp dirs are unique per
-    // test, but clearing keeps the cache from growing across the suite.
-    clearConfigCache();
-  });
-
   it("omits a hidden folder from an auto-index built from source", async () => {
     await mkdir(join(source, "_art"), { recursive: true });
     await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
@@ -183,32 +79,6 @@ describe("folders ignored via config.json { hidden: true }", () => {
     expect(html).not.toContain("prompts");
   });
 
-  it("omits a hidden folder even when stale output for it still exists", async () => {
-    // A folder generated before it was hidden leaves files behind in output.
-    // The listing is built from output, so without a source-side check the
-    // hidden folder would reappear in the index.
-    await mkdir(join(source, "_art"), { recursive: true });
-    await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
-    await mkdir(join(source, "people"), { recursive: true });
-    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
-
-    await mkdir(join(output, "_art"), { recursive: true });
-    await writeFile(join(output, "_art", "prompts.html"), "<html><body>stale</body></html>");
-    await mkdir(join(output, "people"), { recursive: true });
-    await writeFile(join(output, "people", "alice.html"), "<html><body>Alice</body></html>");
-
-    const progress = makeProgress();
-    await runAutoIndices(
-      [source, join(source, "people")],
-      [join(source, "people", "alice.md")],
-      progress
-    );
-
-    const index = await readFile(join(output, "index.html"), "utf8");
-    expect(index).toContain("people");
-    expect(index).not.toContain("_art");
-  });
-
   it("does not count documents inside a hidden subfolder when deciding a folder has content", async () => {
     // `notes` holds nothing but a hidden subfolder, so it produces no pages
     // and must not be linked as though it did.