@kenjura/ursa 0.93.0 → 0.96.0

package/src/helper/mdxRenderer.js

@@ -3,9 +3,9 @@ import { getMDXComponent } from "mdx-bundler/client/index.js";
 import React from "react";
 import { renderToString } from "react-dom/server";
 import * as esbuild from "esbuild";
-import { dirname, join, resolve } from "path";
+import { dirname, extname, join, resolve, sep } from "path";
 import { existsSync } from "fs";
-import { writeFile, mkdir } from "fs/promises";
+import { readFile, writeFile, mkdir } from "fs/promises";
 import remarkDirective from "remark-directive";
 import { remarkDefinitionList, defListHastHandlers } from "remark-definition-list";
 import remarkSupersub from "remark-supersub";
@@ -47,6 +47,160 @@ function remarkAsideContainers() {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Island hydration
+//
+// Components imported directly into an .mdx file are wrapped in an island: the
+// server renders each inside <ursa-island data-island="N">, and the client
+// hydrates each of those elements as its own React root. The markdown around
+// them is never handed to React, so the template is free to restructure it
+// (sectionify.js wraps H1 sections, breadcrumbs are injected, etc.) without
+// causing a hydration mismatch. See docs/changes/island-hydration.md.
+// ---------------------------------------------------------------------------
+
+const ISLAND_MODULE = "ursa:island";
+const ISLAND_NAMESPACE = "ursa-island";
+const ISLAND_RUNTIME_NAMESPACE = "ursa-island-runtime";
+const ISLAND_TAG = "ursa-island";
+
+// Extensions that are wrapped when imported from the .mdx entry. .js/.ts are
+// only wrapped when they live in a _components/ directory, since a plain .js
+// import from MDX is as likely to be data or a helper as a component.
+const ISLAND_COMPONENT_EXTS = new Set([".jsx", ".tsx"]);
+const ISLAND_COMPONENT_DIR_EXTS = new Set([".js", ".ts"]);
+
+/**
+ * Source of the `ursa:island` virtual module. Both variants assign island ids
+ * with a lazy useState initializer so each mount takes exactly one id, in tree
+ * order — which is what lets the client match the server's numbering.
+ */
+function islandRuntimeSource(platform) {
+  const shared = `
+    import React from 'react';
+    let counter = 0;
+    function useIslandId() {
+      const [id] = React.useState(() => counter++);
+      return id;
+    }
+  `;
+  if (platform === "node") {
+    return `${shared}
+      export function island(Component, name) {
+        if (typeof Component !== 'function') return Component;
+        function Island(props) {
+          const id = useIslandId();
+          return React.createElement(
+            ${JSON.stringify(ISLAND_TAG)},
+            { 'data-island': String(id), 'data-component': name, style: { display: 'contents' } },
+            React.createElement(Component, props)
+          );
+        }
+        Island.displayName = 'Island(' + name + ')';
+        return Island;
+      }
+    `;
+  }
+  return `${shared}
+    import * as ReactDOM from 'react-dom';
+    export function island(Component, name) {
+      if (typeof Component !== 'function') return Component;
+      function Island(props) {
+        const id = useIslandId();
+        React.useEffect(() => {
+          const target = document.querySelector(${JSON.stringify(ISLAND_TAG)} + '[data-island="' + id + '"]');
+          if (!target) {
+            console.warn('[ursa] island #' + id + ' (' + name + ') not found in document; skipping hydration');
+            return undefined;
+          }
+          const root = ReactDOM.hydrateRoot(target, React.createElement(Component, props));
+          return () => root.unmount();
+        }, []);
+        return null;
+      }
+      Island.displayName = 'Island(' + name + ')';
+      return Island;
+    }
+  `;
+}
+
+function isIslandCandidate(resolvedPath) {
+  const ext = extname(resolvedPath);
+  if (ISLAND_COMPONENT_EXTS.has(ext)) return true;
+  if (ISLAND_COMPONENT_DIR_EXTS.has(ext)) {
+    return resolvedPath.split(sep).includes("_components");
+  }
+  return false;
+}
+
+/**
+ * esbuild plugin that turns direct component imports of the .mdx entry into
+ * islands. Must be registered ahead of mdx-bundler's own resolvers so it sees
+ * the import first; it defers to them (via build.resolve) for the actual lookup.
+ */
+function islandPlugin(platform) {
+  return {
+    name: "ursa-island",
+    setup(build) {
+      // The runtime module itself
+      build.onResolve({ filter: /^ursa:island$/ }, () => ({
+        path: ISLAND_MODULE,
+        namespace: ISLAND_RUNTIME_NAMESPACE,
+      }));
+      build.onLoad({ filter: /.*/, namespace: ISLAND_RUNTIME_NAMESPACE }, () => ({
+        contents: islandRuntimeSource(platform),
+        loader: "js",
+        resolveDir: process.cwd(),
+      }));
+
+      // Imports from the .mdx entry
+      build.onResolve({ filter: /.*/ }, async (args) => {
+        if (args.pluginData?.ursaIsland) return undefined; // our own build.resolve
+        if (args.namespace !== "file" || !args.importer.endsWith(".mdx")) return undefined;
+        if (args.path === ISLAND_MODULE || /^react(\/|$)|^react-dom(\/|$)/.test(args.path)) return undefined;
+
+        const resolved = await build.resolve(args.path, {
+          importer: args.importer,
+          resolveDir: args.resolveDir,
+          kind: args.kind,
+          pluginData: { ursaIsland: true },
+        });
+        if (resolved.errors.length > 0 || resolved.external || resolved.namespace !== "file") return undefined;
+        if (!isIslandCandidate(resolved.path)) return undefined;
+
+        return {
+          path: resolved.path,
+          namespace: ISLAND_NAMESPACE,
+          pluginData: { name: args.path.split("/").pop().replace(/\.[jt]sx?$/, "") },
+        };
+      });
+      build.onLoad({ filter: /.*/, namespace: ISLAND_NAMESPACE }, (args) => {
+        const real = JSON.stringify(args.path);
+        const name = JSON.stringify(args.pluginData?.name || "Component");
+        return {
+          contents: `
+            import __ursaInner from ${real};
+            export * from ${real};
+            import { island } from ${JSON.stringify(ISLAND_MODULE)};
+            export default island(__ursaInner, ${name});
+          `,
+          loader: "js",
+          resolveDir: dirname(args.path),
+        };
+      });
+    },
+  };
+}
+
+/**
+ * React 19's renderToString hoists a <link rel="preload"> for images ahead of
+ * the content. It carries the un-rewritten relative href (so it preloads
+ * nothing useful) and, sitting before the first <h1>, defeats the template's
+ * "body starts with a heading" check, which then injects a duplicate title.
+ */
+function stripHoistedPreloads(html) {
+  return html.replace(/<link rel="preload"[^>]*>/g, "");
+}
+
 /**
  * Find _components directories by walking up from the MDX file to the source root.
  * Returns paths from most specific (nearest) to most general (root).
@@ -121,7 +275,10 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
       const parentDirs = componentDirs.map(d => dirname(d));
       options.nodePaths = [...(options.nodePaths || []), ...parentDirs];
     }
-    
+
+    // Island plugin goes first so it sees component imports before mdx-bundler's resolvers
+    options.plugins = [islandPlugin(platform), ...(options.plugins || [])];
+
     return options;
   };
 
@@ -170,7 +327,7 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
     const Component = getMDXComponent(serverCode);
 
     // Render to HTML with hydration markers (renderToString vs renderToStaticMarkup)
-    const html = renderToString(React.createElement(Component));
+    const html = stripHoistedPreloads(renderToString(React.createElement(Component)));
 
     // If hydration is not requested, return without client code
     if (!hydrate) {
@@ -279,11 +436,18 @@ function formatMDXError(error, filePath) {
  * @param {string} publicDir - Absolute path to the output public/ directory
  * @returns {Promise<void>}
  */
+// Bump when the runtime's contents change; an older runtime left in
+// output/public/ is then rebuilt instead of reused.
+const REACT_RUNTIME_MARKER = 'ursa-react-runtime/2';
+
 export async function buildReactRuntime(publicDir) {
   const outfile = join(publicDir, 'react-runtime.js');
 
-  // Skip rebuild if already exists (for incremental builds)
-  if (existsSync(outfile)) return;
+  // Skip rebuild if an up-to-date runtime already exists (for incremental builds)
+  if (existsSync(outfile)) {
+    const existing = await readFile(outfile, 'utf8');
+    if (existing.includes(REACT_RUNTIME_MARKER)) return;
+  }
 
   await mkdir(publicDir, { recursive: true });
 
@@ -292,11 +456,12 @@ export async function buildReactRuntime(publicDir) {
       contents: `
         import React from 'react';
         import * as ReactDOM from 'react-dom';
-        import { hydrateRoot } from 'react-dom/client';
+        import { hydrateRoot, createRoot } from 'react-dom/client';
         import * as _jsx_runtime from 'react/jsx-runtime';
         window.React = React;
-        window.ReactDOM = { ...ReactDOM, hydrateRoot };
+        window.ReactDOM = { ...ReactDOM, hydrateRoot, createRoot };
         window._jsx_runtime = _jsx_runtime;
+        window.__ursaReactRuntime = ${JSON.stringify(REACT_RUNTIME_MARKER)};
       `,
       resolveDir: dirname(new URL(import.meta.url).pathname),
       loader: 'js',
@@ -313,12 +478,17 @@ export async function buildReactRuntime(publicDir) {
 /**
  * Generate the hydration script tags for an MDX page.
  * References the locally-built React runtime instead of CDN.
- * 
+ *
+ * The bundled MDX module is rendered into a detached root purely to run the
+ * component tree: every island in it hydrates its own <ursa-island> element in
+ * the live document (see islandRuntimeSource). Nothing outside those elements
+ * is handed to React, so the template's DOM post-processing (sectionify,
+ * breadcrumbs, TOC) cannot cause a hydration mismatch.
+ *
  * @param {string} clientCode - The bundled MDX client code from renderMDX
- * @param {string} [containerId='main-content'] - The ID of the container element to hydrate
  * @returns {string} HTML script tags to include in the page
  */
-export function generateHydrationScript(clientCode, containerId = 'main-content') {
+export function generateHydrationScript(clientCode) {
   // Escape the code for embedding in a script tag
   const escapedCode = clientCode
     .replace(/\\/g, '\\\\')
@@ -330,7 +500,7 @@ export function generateHydrationScript(clientCode, containerId = 'main-content'
     <!-- React runtime for MDX hydration (built from node_modules) -->
     <script src="/public/react-runtime.js"></script>
     
-    <!-- MDX Hydration -->
+    <!-- MDX island hydration -->
     <script>
     (function() {
       // getMDXComponent: matches mdx-bundler/client calling convention.
@@ -344,23 +514,30 @@ export function generateHydrationScript(clientCode, containerId = 'main-content'
         var mdxExport = fn(React, ReactDOM, _jsx_runtime);
         return mdxExport.default;
       }
-      
-      // Hydrate when DOM is ready
+
+      // Hydrate when DOM is ready. Running after the template's own
+      // DOMContentLoaded handlers is fine: islands are found by id, so it
+      // does not matter where sectionify has moved them.
       function hydrate() {
         try {
-          var container = document.getElementById('${containerId}');
-          if (!container) {
-            console.error('MDX hydration: container #${containerId} not found');
+          if (!window.ReactDOM || !window.ReactDOM.createRoot) {
+            console.error('MDX hydration: React runtime not loaded');
+            return;
+          }
+          var islands = document.querySelectorAll('${ISLAND_TAG}[data-island]');
+          if (islands.length === 0) {
+            console.log('MDX hydration: no islands on this page');
             return;
           }
-          
+
           // MDX bundled code (compiled by mdx-bundler)
           var mdxCode = \`${escapedCode}\`;
           var Component = getMDXComponent(mdxCode);
-          
-          // Use hydrateRoot (React 18+)
-          window.ReactDOM.hydrateRoot(container, window.React.createElement(Component));
-          console.log('MDX hydration complete');
+
+          // Render into a detached root; each island hydrates itself in place.
+          var detached = document.createElement('div');
+          window.ReactDOM.createRoot(detached).render(window.React.createElement(Component));
+          console.log('MDX hydration: ' + islands.length + ' island(s)');
         } catch (err) {
           console.error('MDX hydration error:', err);
         }

package/src/helper/sourceTimestamps.js

@@ -0,0 +1,139 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { realpath, stat } from "fs/promises";
+import { relative, resolve, sep } from "path";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// When was a source document last edited?
+//
+// The recent-activity feed needs a per-document "last edited" time that does
+// not depend on when ursa happened to run. Two sources, in order:
+//
+// 1. git: the commit date of the last commit that touched the file. One
+//    `git log --name-only` pass over the source directory yields every file's
+//    latest commit in a single process, which is far cheaper than a `git log`
+//    per file. Files with uncommitted changes (per `git status`) are taken
+//    from the working tree instead, since the commit time predates the edit.
+// 2. filesystem mtime, for sources that are not in a git work tree, files git
+//    does not know about, and the uncommitted files above.
+//
+// A shallow clone (CI checkouts default to depth 1) truncates history, so
+// every file appears to have been edited in the one fetched commit. That is
+// detected and warned about; the fix is on the checkout side (fetch-depth: 0).
+// ---------------------------------------------------------------------------
+
+async function git(cwd, args) {
+  const { stdout } = await execFileAsync("git", ["-C", cwd, ...args], {
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+/**
+ * Parse `git log --format=%x00%ct --name-only` output into a map of
+ * repo-relative path → last-commit time in ms. The log is newest-first, so the
+ * first commit a path appears under is its latest.
+ * @param {string} log
+ * @returns {Map<string, number>}
+ */
+export function parseGitLog(log) {
+  const times = new Map();
+  let current = 0;
+  for (const line of log.split("\n")) {
+    if (line.startsWith("\0")) {
+      current = Number(line.slice(1)) * 1000;
+    } else if (line && !times.has(line)) {
+      times.set(line, current);
+    }
+  }
+  return times;
+}
+
+/**
+ * Parse `git status --porcelain -z` output into the set of repo-relative paths
+ * with uncommitted changes (modified, added, untracked, renamed — any status).
+ * @param {string} status
+ * @returns {Set<string>}
+ */
+export function parseGitStatus(status) {
+  const dirty = new Set();
+  const entries = status.split("\0");
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.length < 4) continue;
+    const code = entry.slice(0, 2);
+    dirty.add(entry.slice(3));
+    // A rename entry ("R  new\0old") is followed by the original path
+    if (code[0] === "R" || code[0] === "C") i++;
+  }
+  return dirty;
+}
+
+/**
+ * Build a lookup of last-edited times for files under `sourceDir`.
+ *
+ * @param {string} sourceDir - Absolute path to the source directory
+ * @param {object} [options]
+ * @param {(msg: string) => void} [options.log] - Receives one-line status/warnings
+ * @returns {Promise<{ get: (file: string) => Promise<number>, source: 'git'|'mtime' }>}
+ */
+export async function buildSourceTimestampIndex(sourceDir, { log = () => {} } = {}) {
+  const dir = resolve(sourceDir);
+
+  async function mtime(file) {
+    try {
+      return (await stat(file)).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  // git reports the real path of the work tree; resolve symlinks (macOS
+  // /var → /private/var, for one) so paths line up with what git prints.
+  let realDir = dir;
+  let toplevel = null;
+  try {
+    realDir = await realpath(dir);
+    toplevel = (await git(realDir, ["rev-parse", "--show-toplevel"])).trim();
+  } catch {
+    // Not a git work tree, or git is not installed
+  }
+  if (!toplevel) {
+    return { get: mtime, source: "mtime" };
+  }
+
+  let committed;
+  let dirty;
+  const relSource = relative(toplevel, realDir) || ".";
+  try {
+    const [logOut, statusOut, shallow] = await Promise.all([
+      git(toplevel, ["log", "--format=%x00%ct", "--name-only", "--", relSource]),
+      git(toplevel, ["status", "--porcelain", "-z", "--untracked-files=all", "--", relSource]),
+      git(toplevel, ["rev-parse", "--is-shallow-repository"]),
+    ]);
+    committed = parseGitLog(logOut);
+    dirty = parseGitStatus(statusOut);
+    if (shallow.trim() === "true") {
+      log(
+        "⚠️  Source is a shallow git clone: every document appears last edited in the one fetched commit, " +
+          "so recent activity will be inaccurate. Fetch full history (e.g. actions/checkout fetch-depth: 0)."
+      );
+    }
+  } catch (e) {
+    log(`⚠️  git history unavailable (${e.message.split("\n")[0]}); using file mtimes for recent activity`);
+    return { get: mtime, source: "mtime" };
+  }
+
+  return {
+    source: "git",
+    async get(file) {
+      // Repo-relative path as git prints it: forward slashes on every platform
+      const fromSource = relative(dir, resolve(file));
+      const rel = (relSource === "." ? fromSource : `${relSource}/${fromSource}`).split(sep).join("/");
+      if (dirty.has(rel) || !committed.has(rel)) return mtime(file);
+      return committed.get(rel);
+    },
+  };
+}

package/src/helper/ursaConfig.js

@@ -56,56 +56,10 @@ export function getAndIncrementBuildId(sourceDir) {
   const newBuildId = currentBuildId + 1;
   
   config.buildId = newBuildId;
+  // Dropped in 0.96.0: last-edited times now come from git/mtime, not the
+  // build. Remove the stale map so it stops taking up the file.
+  delete config.contentTimestamps;
   saveUrsaConfig(sourceDir, config);
   
   return newBuildId;
 }
-
-/**
- * Load content timestamps from .ursa.json
- * These track when each file's content actually changed (not filesystem mtime)
- * @param {string} sourceDir - The source directory path
- * @returns {Map<string, number>} Map of relative file paths to timestamps
- */
-export function loadContentTimestamps(sourceDir) {
-  const config = loadUrsaConfig(sourceDir);
-  const timestamps = config.contentTimestamps || {};
-  return new Map(Object.entries(timestamps));
-}
-
-/**
- * Save content timestamps to .ursa.json
- * @param {string} sourceDir - The source directory path
- * @param {Map<string, number>} timestampMap - Map of relative file paths to timestamps
- */
-export function saveContentTimestamps(sourceDir, timestampMap) {
-  const config = loadUrsaConfig(sourceDir);
-  config.contentTimestamps = Object.fromEntries(timestampMap);
-  saveUrsaConfig(sourceDir, config);
-}
-
-/**
- * Update the content timestamp for a single file
- * @param {string} sourceDir - The source directory path
- * @param {string} relativePath - The relative file path
- * @param {number} timestamp - The timestamp when content changed
- */
-export function updateContentTimestamp(sourceDir, relativePath, timestamp) {
-  const config = loadUrsaConfig(sourceDir);
-  if (!config.contentTimestamps) {
-    config.contentTimestamps = {};
-  }
-  config.contentTimestamps[relativePath] = timestamp;
-  saveUrsaConfig(sourceDir, config);
-}
-
-/**
- * Get the content timestamp for a file, or null if not tracked
- * @param {string} sourceDir - The source directory path
- * @param {string} relativePath - The relative file path
- * @returns {number|null} The timestamp or null
- */
-export function getContentTimestamp(sourceDir, relativePath) {
-  const config = loadUrsaConfig(sourceDir);
-  return config.contentTimestamps?.[relativePath] || null;
-}

package/src/jobs/__test__/generateJsonOnly.test.js

@@ -0,0 +1,154 @@
+/**
+ * `generate({ _jsonOnly: true })` — emit the data files and nothing else.
+ *
+ * The load-bearing claim is not "fewer files": it is that the .json a JSON-only
+ * build writes is byte-identical to the one a full build writes. Every step the
+ * mode skips operates on the assembled page, never on the JSON. If that ever
+ * stops being true, `identical to a full build's JSON` fails here rather than
+ * silently shipping different data to a consumer.
+ */
+
+import { join } from "path";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "fs/promises";
+import { existsSync } from "fs";
+import { tmpdir } from "os";
+import { generate } from "../generate.js";
+import { clearConfigCache } from "../../helper/folderConfig.js";
+
+const META = join(process.cwd(), "meta");
+
+let source;
+let output;
+
+async function doc(relPath, contents) {
+  const full = join(source, relPath);
+  await mkdir(join(full, ".."), { recursive: true });
+  await writeFile(full, contents);
+  return full;
+}
+
+beforeEach(async () => {
+  source = await mkdtemp(join(tmpdir(), "ursa-jsononly-src-"));
+  output = await mkdtemp(join(tmpdir(), "ursa-jsononly-out-"));
+  clearConfigCache();
+
+  await doc("index.md", "# Home\n\nWelcome.\n");
+  await doc(
+    "character/powers/absorb-magic.md",
+    [
+      "---",
+      "class: Witch",
+      "name: Absorb Magic",
+      "school: Antimagic",
+      "brief: Absorb energy from a touched spell",
+      "---",
+      "",
+      "# Absorb Magic",
+      "",
+      "Touch a spell and take it apart.",
+      "",
+      "## Range",
+      "",
+      "Touch.",
+      "",
+    ].join("\n")
+  );
+  await doc("character/powers/mind-blast.md", "# Mind Blast\n\nA blast, of the mind.\n");
+});
+
+afterEach(async () => {
+  await rm(source, { recursive: true, force: true });
+  await rm(output, { recursive: true, force: true });
+});
+
+const run = (opts) =>
+  generate({ _source: source, _meta: META, _output: output, _clean: true, ...opts });
+
+describe("generate --json-only", () => {
+  it("writes the document JSON", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "character/powers/absorb-magic.json"))).toBe(true);
+    expect(existsSync(join(output, "index.json"))).toBe(true);
+  });
+
+  it("writes the directory record lists, which are the point of the mode", async () => {
+    await run({ _jsonOnly: true });
+    const listPath = join(output, "character/powers.json");
+    expect(existsSync(listPath)).toBe(true);
+
+    const records = JSON.parse(await readFile(listPath, "utf8"));
+    const absorb = records.find((r) => r.name === "absorb-magic");
+    expect(absorb).toBeDefined();
+    expect(absorb.url).toBe("/character/powers/absorb-magic.html");
+    expect(absorb.metadata.school).toBe("Antimagic");
+  });
+
+  it("writes no HTML and no XML", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "index.html"))).toBe(false);
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(false);
+    expect(existsSync(join(output, "character/powers/absorb-magic.xml"))).toBe(false);
+    // The directory listing page, distinct from the record list above.
+    expect(existsSync(join(output, "character/powers.html"))).toBe(false);
+  });
+
+  it("writes no meta assets, search index, menu data or recent activity", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "public", "search-index.json"))).toBe(false);
+    expect(existsSync(join(output, "public", "fulltext-index.json"))).toBe(false);
+    expect(existsSync(join(output, "public", "menu-data.json"))).toBe(false);
+    expect(existsSync(join(output, "public", "recent-activity.json"))).toBe(false);
+  });
+
+  it("produces JSON identical to a full build's", async () => {
+    await run({ _jsonOnly: true });
+    const jsonOnly = await readFile(
+      join(output, "character/powers/absorb-magic.json"),
+      "utf8"
+    );
+    const jsonOnlyList = await readFile(join(output, "character/powers.json"), "utf8");
+
+    await rm(output, { recursive: true, force: true });
+    await mkdir(output, { recursive: true });
+    await run({ _jsonOnly: false });
+
+    const full = await readFile(join(output, "character/powers/absorb-magic.json"), "utf8");
+    const fullList = await readFile(join(output, "character/powers.json"), "utf8");
+
+    expect(jsonOnly).toBe(full);
+    expect(jsonOnlyList).toBe(fullList);
+  });
+
+  it("still emits everything on a normal build", async () => {
+    await run({ _jsonOnly: false });
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(true);
+    expect(existsSync(join(output, "character/powers/absorb-magic.xml"))).toBe(true);
+    expect(existsSync(join(output, "public", "menu-data.json"))).toBe(true);
+  });
+});
+
+describe("mixing modes against one source tree", () => {
+  // The hash cache lives in the SOURCE tree and is shared by both modes, so the
+  // per-document output check has to be mode-aware or one mode's cache entries
+  // would convince the other that its own missing outputs are up to date.
+
+  it("a full build after a JSON-only build still writes the HTML", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(false);
+
+    // Warm: no --clean, so the hash cache from the JSON-only run is in play.
+    await generate({ _source: source, _meta: META, _output: output, _jsonOnly: false });
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(true);
+    expect(existsSync(join(output, "character/powers/absorb-magic.xml"))).toBe(true);
+  });
+
+  it("a JSON-only build after a full build leaves the JSON in place", async () => {
+    await run({ _jsonOnly: false });
+    const before = await readFile(join(output, "character/powers/absorb-magic.json"), "utf8");
+
+    await generate({ _source: source, _meta: META, _output: output, _jsonOnly: true });
+    const after = await readFile(join(output, "character/powers/absorb-magic.json"), "utf8");
+
+    expect(after).toBe(before);
+  });
+});