@kenjura/ursa 0.95.0 → 0.96.0

package/CHANGELOG.md

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

package/README.md

@@ -318,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/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.95.0",
+  "version": "0.96.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

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

@@ -28,7 +28,8 @@ import {
   markInactiveLinks,
   resolveRelativeUrls,
 } from "../helper/linkValidator.js";
-import { getAndIncrementBuildId, loadContentTimestamps, saveContentTimestamps, updateContentTimestamp } from "../helper/ursaConfig.js";
+import { getAndIncrementBuildId } from "../helper/ursaConfig.js";
+import { buildSourceTimestampIndex } from "../helper/sourceTimestamps.js";
 import { extractSections } from "../helper/sectionExtractor.js";
 import { renderFile, renderFileAsync, terminateParserPool } from "../helper/fileRenderer.js";
 import { buildReactRuntime } from "../helper/mdxRenderer.js";
@@ -418,11 +419,11 @@ export async function generate({
     progress.stopTimer('Cache');
   }
   
-  // Load content timestamps from .ursa.json (survives --clean)
-  // These track when content actually changed, not filesystem mtime
-  const contentTimestamps = loadContentTimestamps(source);
-  const buildTimestamp = Date.now();
-  progress.logTimed(`Loaded ${contentTimestamps.size} content timestamps`);
+  // Last-edited times for the recent-activity feed come from git history (or
+  // file mtimes outside git), never from when ursa ran, so --clean cannot
+  // stamp every document with the build time.
+  const sourceTimestamps = await buildSourceTimestampIndex(source, { log: (m) => progress.log(m) });
+  progress.logTimed(`Source timestamps: ${sourceTimestamps.source}`);
   profiler.endPhase('Load cache');
 
   // Phase: Copy meta/public files
@@ -673,24 +674,11 @@ export async function generate({
         content: rawBody
       });
 
-      // Collect timestamp for recent activity tracking
-      // Use stored content timestamp if available, otherwise fall back to file mtime
-      // Content timestamps track when content actually changed, not filesystem mtime
-      const storedTimestamp = contentTimestamps.get(relativePath);
-      let activityTimestamp = storedTimestamp;
-      if (!activityTimestamp) {
-        // No stored timestamp - use file mtime as initial value
-        try {
-          const fileStat = await stat(file);
-          activityTimestamp = fileStat.mtimeMs;
-        } catch (e) {
-          activityTimestamp = 0;
-        }
-      }
+      // Collect last-edited time for recent activity tracking
       recentActivity.push({
         title: title,
         url: searchUrl,
-        mtime: activityTimestamp
+        mtime: await sourceTimestamps.get(file)
       });
       
       // Check if a corresponding .html file already exists in source directory
@@ -1040,14 +1028,6 @@ export async function generate({
       
       // Update the content hash for this file
       updateHash(file, rawBody, hashCache);
-      
-      // Update content timestamp since this file was regenerated (content changed)
-      contentTimestamps.set(relativePath, buildTimestamp);
-      // Also update the recentActivity entry we pushed earlier with the new timestamp
-      const activityEntry = recentActivity.find(e => e.url === searchUrl);
-      if (activityEntry) {
-        activityEntry.mtime = buildTimestamp;
-      }
     } catch (e) {
       progress.log(`Error processing ${file}: ${e.message}`);
       errors.push({ file, phase: 'article-generation', error: e });
@@ -1371,12 +1351,6 @@ export async function generate({
     await saveHashCache(source, hashCache);
   }
   
-  // Save content timestamps to .ursa.json (tracks when content actually changed)
-  if (contentTimestamps.size > 0) {
-    saveContentTimestamps(source, contentTimestamps);
-    progress.log(`Saved ${contentTimestamps.size} content timestamps`);
-  }
-
   // Persist the dependency tracker so hash-skipped documents keep their
   // edges on the next warm start (invalidation plans stay accurate).
   //
@@ -1859,9 +1833,10 @@ export async function regenerateSingleFile(changedFile, {
     // Update hash cache
     updateHash(changedFile, rawBody, hashCache);
     
-    // Update recent-activity.json with this file's new content timestamp
+    // Update recent-activity.json with this file's last-edited time
     try {
-      const now = Date.now();
+      const sourceTimestamps = await buildSourceTimestampIndex(source);
+      const now = await sourceTimestamps.get(changedFile);
       const recentActivityPath = join(output, 'public', 'recent-activity.json');
       let recentActivity = [];
       try {
@@ -1870,16 +1845,11 @@ export async function regenerateSingleFile(changedFile, {
       } catch (e) { /* no existing file, start fresh */ }
       // Remove old entry for this URL if present
       recentActivity = recentActivity.filter(r => r.url !== url);
-      // Add updated entry with current timestamp (content changed now)
       recentActivity.push({ title, url, mtime: now });
       // Sort by mtime descending, keep top 10
       recentActivity.sort((a, b) => b.mtime - a.mtime);
       recentActivity = recentActivity.slice(0, 10);
       await outputFile(recentActivityPath, JSON.stringify(recentActivity));
-      
-      // Also update content timestamp in .ursa.json for persistence
-      const relativePath = '/' + changedFile.replace(source, '').replace(/\.(md|mdx|txt|yml)$/, '.html');
-      updateContentTimestamp(source, relativePath, now);
     } catch (e) {
       // ignore recent activity update errors
     }