@kenjura/ursa 0.79.0 → 0.81.2

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 0.81.2
+2026-03-28
+
+- MDX hydration: MDX documents now support hydration of embedded React components, allowing for interactive content within static pages.
+
+- **Fixed Recent Activity tracking**: The Recent Activity widget now properly tracks when document content actually changed, rather than relying on file system modification times (mtime). 
+  - Previously, Recent Activity used filesystem mtime, which doesn't work correctly after git clone (git doesn't preserve timestamps) or when all files are built simultaneously.
+  - Now, content change timestamps are stored in `.ursa.json` (in the source directory), which:
+    - Survives `--clean` builds (unlike the `.ursa/` cache folder)
+    - Can be committed to git to preserve wiki history across clones
+    - Falls back to file mtime for files that haven't been tracked yet (backward compatibility)
+  - Both full builds and single-file regeneration (serve/dev mode) now update content timestamps when content actually changes (detected by hash comparison).
+
+# 0.80.1
+2026-02-16
+
+- Fixed package.json issue
+
+# 0.80.0
+2026-02-16
+
+- Added remark extensions to ensure MDX has the same extended markdown features as regular markdown (e.g. footnotes, definition lists, etc.)
+
 # 0.79.0
 2026-02-14
 

package/meta/templates/default-template/toc.js

@@ -42,7 +42,7 @@
 
   // === observer factory tied to current STICKY_TOP ===
   let observer = null;
-  function (re)buildObserver() {
+  function rebuildObserver() {
     if (observer) observer.disconnect();
     // ignore intersections near the bottom; we only care about the top line
     const bottomRM = -(window.innerHeight - 1) + 'px';
@@ -72,7 +72,7 @@
 
   // initial setup
   ensureSentinels();
-  (re)buildObserver();
+  rebuildObserver();
   updateActiveFromSentinels();
 
   // react when sticky top changes
@@ -86,7 +86,7 @@
       // update sentinel offsets
       document.querySelectorAll('.toc-sentinel').forEach(s => s.style.marginTop = `-${STICKY_TOP}px`);
       heads.forEach(h => h.style.scrollMarginTop = (STICKY_TOP + 8) + 'px');
-      (re)buildObserver();
+      rebuildObserver();
       updateActiveFromSentinels();
     });
   }, { passive: true });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.79.0",
+  "version": "0.81.2",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -39,7 +39,12 @@
     "object-to-xml": "^2.0.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "remark-definition-list": "^2.0.0",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-supersub": "^1.0.0",
     "sharp": "^0.33.2",
+    "unist-util-visit": "^5.1.0",
     "ws": "^8.19.0",
     "yaml": "^2.1.3",
     "yargs": "^17.7.2"

package/src/dev.js

@@ -19,6 +19,7 @@ const { readFile, readdir, stat, mkdir } = promises;
 
 // Import helper modules
 import { renderFileAsync } from "./helper/fileRenderer.js";
+import { buildReactRuntime } from "./helper/mdxRenderer.js";
 import { findStyleCss } from "./helper/findStyleCss.js";
 import { findAllScriptJs } from "./helper/findScriptJs.js";
 import { extractMetadata, getAutoIndexConfig, isMetadataOnly } from "./helper/metadataExtractor.js";
@@ -382,22 +383,37 @@ async function renderDocument(urlPath) {
     if (autoIndexHtml) {
       // Wrap in template and return — use parent folder name for title
       const indexTitle = toTitleCase(basename(dirname(sourcePath)) || 'Index');
-      return await wrapInTemplate(autoIndexHtml, indexTitle, null, urlPath, sourcePath);
+      return await wrapInTemplate(autoIndexHtml, indexTitle, null, urlPath, sourcePath, '');
     }
   }
   
+  // Extract metadata first to determine if hydration is needed
+  const fileMeta = extractMetadata(rawBody);
+  
   // Render body
-  let body = await renderFileAsync({
+  // For MDX files, enable hydration if frontmatter has `hydrate: true`
+  const shouldHydrate = type === '.mdx' && fileMeta?.hydrate === true;
+  
+  let renderResult = await renderFileAsync({
     fileContents: rawBody,
     type,
     dirname: dir,
     basename: base,
     filePath: sourcePath,
     sourceRoot: devState.source,
-    useWorker: false // Use main thread for faster single-file processing
+    useWorker: false, // Use main thread for faster single-file processing
+    hydrate: shouldHydrate,
   });
   
-  const fileMeta = extractMetadata(rawBody);
+  // Handle the result - can be string or { html, hydrationScript }
+  let body;
+  let hydrationScript = '';
+  if (typeof renderResult === 'object' && renderResult.html) {
+    body = renderResult.html;
+    hydrationScript = renderResult.hydrationScript || '';
+  } else {
+    body = renderResult;
+  }
 
   // Title from filename (for index/home, use parent folder name)
   const titleBase = (base === 'index' || base === 'home') ? basename(dirname(sourcePath)) : base;
@@ -438,7 +454,7 @@ async function renderDocument(urlPath) {
   // Process images in this document
   body = await processDocumentImages(body, sourcePath);
   
-  const html = await wrapInTemplate(body, title, fileMeta, urlPath, sourcePath);
+  const html = await wrapInTemplate(body, title, fileMeta, urlPath, sourcePath, hydrationScript);
   
   // Cache rendered document
   // documentCache.set(urlPath, html);
@@ -449,7 +465,7 @@ async function renderDocument(urlPath) {
 /**
  * Wrap body in template
  */
-async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath) {
+async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath, hydrationScript = '') {
   const { source, output, templates, menuHtml, footer, validPaths, customMenus } = devState;
   
   // Get template
@@ -504,6 +520,11 @@ async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath) {
   // Calculate document URL path
   const docUrlPath = urlPath.endsWith('.html') ? urlPath : urlPath + '.html';
   
+  // Append hydration script to customScript if present (for MDX with hydrate: true)
+  const finalCustomScript = hydrationScript 
+    ? customScript + '\n' + hydrationScript 
+    : customScript;
+  
   // Build replacements
   const replacements = {
     "${title}": fileMeta?.title || title,
@@ -512,7 +533,7 @@ async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath) {
     "${transformedMetadata}": "",
     "${body}": body,
     "${styleLink}": styleLink,
-    "${customScript}": customScript,
+    "${customScript}": finalCustomScript,
     "${searchIndex}": "[]",
     "${footer}": footer || ""
   };
@@ -765,6 +786,9 @@ export async function dev({
   devState.templates = await bundleMetaTemplateAssets(rawTemplates, metaDir, publicDir, { minify: true, sourcemap: false });
   console.log('📦 Meta template assets bundled');
   
+  // Build React runtime for MDX hydration (React 19 has no UMD, so we bundle locally)
+  await buildReactRuntime(publicDir);
+  
   // Start server immediately
   const app = express();
   const httpServer = createServer(app);

package/src/helper/fileRenderer.js

@@ -1,7 +1,7 @@
 
 import { markdownToHtml } from "./markdownHelper.cjs";
 import { wikiToHtml } from "./wikitextHelper.js";
-import { renderMDX } from "./mdxRenderer.js";
+import { renderMDX, generateHydrationScript } from "./mdxRenderer.js";
 import { parseWithWorker, terminateParserPool } from "./parserPool.js";
 
 const DEFAULT_WIKITEXT_ARGS = { db: "noDB", noSection: true, noTOC: true };
@@ -39,10 +39,11 @@ export function renderFile({ fileContents, type, dirname, basename }) {
  * @param {string} options.basename - Base filename
  * @param {string} [options.filePath] - Absolute path to file (required for .mdx)
  * @param {string} [options.sourceRoot] - Source root directory (for .mdx absolute imports)
- * @param {boolean} options.useWorker - Whether to attempt worker thread parsing (default: true)
- * @returns {Promise<string>} Rendered HTML
+ * @param {boolean} [options.useWorker=true] - Whether to attempt worker thread parsing
+ * @param {boolean} [options.hydrate=false] - Whether to enable client-side hydration (.mdx only)
+ * @returns {Promise<string|{html: string, hydrationScript?: string}>} Rendered HTML or object with HTML and hydration script
  */
-export async function renderFileAsync({ fileContents, type, dirname, basename, filePath, sourceRoot, useWorker = true }) {
+export async function renderFileAsync({ fileContents, type, dirname, basename, filePath, sourceRoot, useWorker = true, hydrate = false }) {
   // Wikitext always runs on main thread due to complex ES module dependencies
   if (type === ".txt") {
     return wikiToHtml({
@@ -70,7 +71,16 @@ export async function renderFileAsync({ fileContents, type, dirname, basename, f
   // Falls back to markdown rendering if MDX compilation fails
   if (type === ".mdx") {
     try {
-      const result = await renderMDX({ source: fileContents, filePath, sourceRoot });
+      const result = await renderMDX({ source: fileContents, filePath, sourceRoot, hydrate });
+      
+      // If hydration was requested and we have client code, return object with hydration script
+      if (hydrate && result.clientCode) {
+        return {
+          html: result.html,
+          hydrationScript: generateHydrationScript(result.clientCode),
+        };
+      }
+      
       return result.html;
     } catch (mdxError) {
       // Extract a concise error description for the warning banner

package/src/helper/frontmatterTable.js

@@ -74,7 +74,8 @@ export function metadataToTable(metadata) {
     'menu-sort-as',   // Custom sort key for menu ordering
     'generate-auto-index', // Auto-indexing control
     'auto-index-depth',    // Auto-indexing depth
-    'auto-index-position'  // Auto-indexing position
+    'auto-index-position', // Auto-indexing position
+    'hydrate'         // MDX hydration control
   ];
   const entries = Object.entries(metadata).filter(
     ([key]) => !excludeKeys.includes(key.toLowerCase())

package/src/helper/mdxRenderer.js

@@ -1,9 +1,32 @@
 import { bundleMDX } from "mdx-bundler";
 import { getMDXComponent } from "mdx-bundler/client/index.js";
 import React from "react";
-import { renderToStaticMarkup } from "react-dom/server";
+import { renderToString } from "react-dom/server";
+import * as esbuild from "esbuild";
 import { dirname, join, resolve } from "path";
 import { existsSync } from "fs";
+import { writeFile, mkdir } from "fs/promises";
+import remarkDirective from "remark-directive";
+import { remarkDefinitionList, defListHastHandlers } from "remark-definition-list";
+import remarkSupersub from "remark-supersub";
+import remarkGfm from "remark-gfm";
+import { visit } from "unist-util-visit";
+
+/**
+ * Custom remark plugin that converts container directives (:::name ... :::)
+ * into <aside> HTML elements, matching the markdown-it-container behavior
+ * used in the .md pipeline (markdownHelper.cjs).
+ */
+function remarkAsideContainers() {
+  return (tree) => {
+    visit(tree, (node) => {
+      if (node.type === "containerDirective") {
+        const data = node.data || (node.data = {});
+        data.hName = "aside";
+      }
+    });
+  };
+}
 
 /**
  * Find _components directories by walking up from the MDX file to the source root.
@@ -34,10 +57,10 @@ function findComponentDirs(startDir, sourceRoot) {
 }
 
 /**
- * Render an MDX file to static HTML.
+ * Render an MDX file to HTML with optional client-side hydration support.
  * 
  * Uses mdx-bundler to compile MDX source (with component imports resolved via esbuild),
- * then renders the resulting React component to static HTML using react-dom/server.
+ * then renders the resulting React component to HTML using react-dom/server.
  * 
  * Supports a `_components/` directory convention: any `_components/` folder found in
  * the MDX file's directory or any parent directory (up to sourceRoot) will be added
@@ -48,13 +71,18 @@ function findComponentDirs(startDir, sourceRoot) {
  * @param {string} options.source - Raw MDX file contents
  * @param {string} options.filePath - Absolute path to the MDX file (used for import resolution)
  * @param {string} [options.sourceRoot] - Root directory of the source files (for absolute imports)
- * @returns {Promise<{ html: string, frontmatter: Record<string, any> }>}
+ * @param {boolean} [options.hydrate=false] - If true, includes client bundle for hydration
+ * @returns {Promise<{ html: string, frontmatter: Record<string, any>, clientCode?: string }>}
  */
-export async function renderMDX({ source, filePath, sourceRoot }) {
+export async function renderMDX({ source, filePath, sourceRoot, hydrate = false }) {
   const cwd = dirname(filePath);
   const componentDirs = findComponentDirs(cwd, sourceRoot);
 
-  const esbuildOptions = (options) => {
+  /**
+   * Create esbuild options for the given platform
+   * @param {'node'|'browser'} platform - Target platform
+   */
+  const createEsbuildOptions = (platform) => (options) => {
     // Enable loaders for TypeScript/JSX component files
     options.loader = {
       ...options.loader,
@@ -63,9 +91,9 @@ export async function renderMDX({ source, filePath, sourceRoot }) {
       ".tsx": "tsx",
       ".jsx": "jsx",
     };
-    // Set target for modern Node.js
+    // Set target based on platform
     options.target = "es2020";
-    options.platform = "node";
+    options.platform = platform;
     
     // Add _components directories as resolve paths so imports like
     // '_components/Foo.tsx' resolve without relative path prefixes
@@ -78,26 +106,72 @@ export async function renderMDX({ source, filePath, sourceRoot }) {
     return options;
   };
 
+  /**
+   * Create MDX options with remark plugins
+   */
+  const createMdxOptions = () => (options) => {
+    // Add remark plugins matching the markdown-it extensions in markdownHelper.cjs:
+    // - remarkGfm: adds GFM support (tables, strikethrough, autolinks, task lists)
+    // - remarkDirective: parses :::name container syntax into AST nodes
+    // - remarkAsideContainers: converts container directives to <aside> elements
+    // - remarkDefinitionList: adds PHP Markdown Extra style definition lists (Term\n: Def)
+    // - remarkSupersub: adds ^superscript^ and ~subscript~ syntax
+    options.remarkPlugins = [
+      ...(options.remarkPlugins || []),
+      remarkGfm,
+      remarkDirective,
+      remarkAsideContainers,
+      remarkDefinitionList,
+      remarkSupersub,
+    ];
+    // remark-definition-list needs custom handlers for remark-rehype conversion
+    options.remarkRehypeOptions = {
+      ...(options.remarkRehypeOptions || {}),
+      handlers: {
+        ...(options.remarkRehypeOptions?.handlers || {}),
+        ...defListHastHandlers,
+      },
+    };
+    return options;
+  };
+
   try {
-    const result = await bundleMDX({
+    // Server-side bundle (for SSR)
+    const serverResult = await bundleMDX({
       source,
       cwd,
-      esbuildOptions,
-      // mdx-bundler uses gray-matter internally for frontmatter
-      mdxOptions(options) {
-        return options;
-      },
+      esbuildOptions: createEsbuildOptions('node'),
+      mdxOptions: createMdxOptions(),
     });
 
-    const { code, frontmatter } = result;
+    const { code: serverCode, frontmatter } = serverResult;
 
     // getMDXComponent evaluates the bundled code and returns a React component
-    const Component = getMDXComponent(code);
+    const Component = getMDXComponent(serverCode);
 
-    // Render to static HTML (no client-side React needed)
-    const html = renderToStaticMarkup(React.createElement(Component));
+    // Render to HTML with hydration markers (renderToString vs renderToStaticMarkup)
+    const html = renderToString(React.createElement(Component));
+
+    // If hydration is not requested, return without client code
+    if (!hydrate) {
+      return { html, frontmatter: frontmatter || {} };
+    }
+
+    // Client-side bundle (for hydration)
+    // Same settings as server — mdx-bundler output is platform-agnostic
+    // (it references React/ReactDOM/jsx-runtime via function parameters, not imports)
+    const clientResult = await bundleMDX({
+      source,
+      cwd,
+      esbuildOptions: createEsbuildOptions('browser'),
+      mdxOptions: createMdxOptions(),
+    });
 
-    return { html, frontmatter: frontmatter || {} };
+    return { 
+      html, 
+      frontmatter: frontmatter || {},
+      clientCode: clientResult.code,
+    };
   } catch (error) {
     throw formatMDXError(error, filePath);
   }
@@ -173,3 +247,110 @@ function formatMDXError(error, filePath) {
   wrappedError.originalError = error;
   return wrappedError;
 }
+
+/**
+ * Build a local React runtime bundle for client-side hydration.
+ * 
+ * Uses esbuild to bundle React + ReactDOM from node_modules into a single
+ * browser-ready file that sets window.React and window.ReactDOM globals.
+ * This replaces the previous CDN approach (unpkg) which broke with React 19
+ * since React 19 removed UMD builds.
+ * 
+ * @param {string} publicDir - Absolute path to the output public/ directory
+ * @returns {Promise<void>}
+ */
+export async function buildReactRuntime(publicDir) {
+  const outfile = join(publicDir, 'react-runtime.js');
+
+  // Skip rebuild if already exists (for incremental builds)
+  if (existsSync(outfile)) return;
+
+  await mkdir(publicDir, { recursive: true });
+
+  await esbuild.build({
+    stdin: {
+      contents: `
+        import React from 'react';
+        import * as ReactDOM from 'react-dom';
+        import { hydrateRoot } from 'react-dom/client';
+        import * as _jsx_runtime from 'react/jsx-runtime';
+        window.React = React;
+        window.ReactDOM = { ...ReactDOM, hydrateRoot };
+        window._jsx_runtime = _jsx_runtime;
+      `,
+      resolveDir: dirname(new URL(import.meta.url).pathname),
+      loader: 'js',
+    },
+    bundle: true,
+    format: 'iife',
+    platform: 'browser',
+    target: 'es2020',
+    minify: true,
+    outfile,
+  });
+}
+
+/**
+ * Generate the hydration script tags for an MDX page.
+ * References the locally-built React runtime instead of CDN.
+ * 
+ * @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') {
+  // Escape the code for embedding in a script tag
+  const escapedCode = clientCode
+    .replace(/\\/g, '\\\\')
+    .replace(/`/g, '\\`')
+    .replace(/\$\{/g, '\\${')
+    .replace(/<\/script>/gi, '<\\/script>');
+
+  return `
+    <!-- React runtime for MDX hydration (built from node_modules) -->
+    <script src="/public/react-runtime.js"></script>
+    
+    <!-- MDX Hydration -->
+    <script>
+    (function() {
+      // getMDXComponent: matches mdx-bundler/client calling convention.
+      // The bundled code is a function body expecting (React, ReactDOM, _jsx_runtime)
+      // as parameters and returning { default: Component }.
+      function getMDXComponent(code) {
+        var React = window.React;
+        var ReactDOM = window.ReactDOM;
+        var _jsx_runtime = window._jsx_runtime;
+        var fn = new Function('React', 'ReactDOM', '_jsx_runtime', code);
+        var mdxExport = fn(React, ReactDOM, _jsx_runtime);
+        return mdxExport.default;
+      }
+      
+      // Hydrate when DOM is ready
+      function hydrate() {
+        try {
+          var container = document.getElementById('${containerId}');
+          if (!container) {
+            console.error('MDX hydration: container #${containerId} not found');
+            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');
+        } catch (err) {
+          console.error('MDX hydration error:', err);
+        }
+      }
+      
+      if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', hydrate);
+      } else {
+        hydrate();
+      }
+    })();
+    </script>`;
+}

package/src/helper/ursaConfig.js

@@ -60,3 +60,52 @@ export function getAndIncrementBuildId(sourceDir) {
   
   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

@@ -24,9 +24,10 @@ import {
   markInactiveLinks,
   resolveRelativeUrls,
 } from "../helper/linkValidator.js";
-import { getAndIncrementBuildId } from "../helper/ursaConfig.js";
+import { getAndIncrementBuildId, loadContentTimestamps, saveContentTimestamps, updateContentTimestamp } from "../helper/ursaConfig.js";
 import { extractSections } from "../helper/sectionExtractor.js";
 import { renderFile, renderFileAsync, terminateParserPool } from "../helper/fileRenderer.js";
+import { buildReactRuntime } from "../helper/mdxRenderer.js";
 import { findStyleCss, findAllStyleCss } from "../helper/findStyleCss.js";
 import { findScriptJs, findAllScriptJs } from "../helper/findScriptJs.js";
 import { bundleMetaTemplateAssets, bundleDocumentCss, bundleDocumentJs, clearMetaBundleCache, generateSeparateCssTags, generateSeparateJsTags } from "../helper/assetBundler.js";
@@ -291,6 +292,12 @@ export async function generate({
     progress.logTimed(`Clean build: ignoring cached hashes`);
     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`);
   profiler.endPhase('Load cache');
 
   // Phase: Copy meta/public files
@@ -322,6 +329,9 @@ export async function generate({
   templates = await bundleMetaTemplateAssets(templates, meta, pub, { minify: true, sourcemap: false });
   progress.logTimed(`Meta template assets bundled`);
 
+  // Build React runtime for MDX hydration (React 19 has no UMD, so we bundle locally)
+  await buildReactRuntime(pub);
+
   // Process all CSS files in the entire output directory tree for cache-busting
   const allOutputFiles = await recurse(output, [() => false]);
   for (const cssFile of allOutputFiles.filter(f => f.endsWith('.css'))) {
@@ -521,17 +531,25 @@ export async function generate({
         content: rawBody
       });
 
-      // Collect mtime for recent activity tracking
-      try {
-        const fileStat = await stat(file);
-        recentActivity.push({
-          title: title,
-          url: searchUrl,
-          mtime: fileStat.mtimeMs
-        });
-      } catch (e) {
-        // ignore stat errors
+      // 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;
+        }
       }
+      recentActivity.push({
+        title: title,
+        url: searchUrl,
+        mtime: activityTimestamp
+      });
       
       // Check if a corresponding .html file already exists in source directory
       const outputHtmlRelative = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
@@ -587,16 +605,30 @@ export async function generate({
 
       // Use async rendering with worker threads for parallel markdown parsing
       // Wikitext (.txt) files will fall back to main thread
-      let body = await renderFileAsync({
+      // For MDX files, enable hydration if frontmatter has `hydrate: true`
+      const shouldHydrate = type === '.mdx' && fileMeta?.hydrate === true;
+      
+      let renderResult = await renderFileAsync({
         fileContents: rawBody,
         type,
         dirname: dir,
         basename: base,
         filePath: file,
         sourceRoot: source,
-        useWorker: true
+        useWorker: true,
+        hydrate: shouldHydrate,
       });
 
+      // Handle the result - can be string or { html, hydrationScript }
+      let body;
+      let hydrationScript = '';
+      if (typeof renderResult === 'object' && renderResult.html) {
+        body = renderResult.html;
+        hydrationScript = renderResult.hydrationScript || '';
+      } else {
+        body = renderResult;
+      }
+
       // Inject default H1 if body doesn't start with one
       if (!body || !body.trimStart().startsWith('<h1')) {
         const h1Title = fileMeta?.title || title;
@@ -738,6 +770,11 @@ export async function generate({
 
       // Build final HTML with all replacements in a single regex pass
       // This avoids creating 8 intermediate strings
+      // Append hydration script to customScript if present (for MDX with hydrate: true)
+      const finalCustomScript = hydrationScript 
+        ? customScript + '\n' + hydrationScript 
+        : customScript;
+      
       const replacements = {
         "${title}": fileMeta?.title || title,
         "${menu}": menu,
@@ -745,7 +782,7 @@ export async function generate({
         "${transformedMetadata}": lazyTransformedMeta,
         "${body}": body,
         "${styleLink}": styleLink,
-        "${customScript}": customScript,
+        "${customScript}": finalCustomScript,
         "${searchIndex}": "[]", // Placeholder - search index written separately as JSON file
         "${footer}": footer
       };
@@ -824,6 +861,14 @@ 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 });
@@ -1085,6 +1130,12 @@ export async function generate({
   if (hashCache.size > 0) {
     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`);
+  }
 
   // Populate watch mode cache for fast single-file regeneration
   watchModeCache.templates = templates;
@@ -1319,18 +1370,31 @@ export async function regenerateSingleFile(changedFile, {
     // Calculate the document's URL path
     const docUrlPath = '/' + dir + base + '.html';
     
+    // Check if hydration should be enabled for MDX files
+    const shouldHydrate = type === '.mdx' && fileMeta?.hydrate === true;
+    
     // Render body (use async for .mdx, sync for .md/.txt)
     let body;
+    let hydrationScript = '';
     if (type === '.mdx') {
-      body = await renderFileAsync({
+      const renderResult = await renderFileAsync({
         fileContents: rawBody,
         type,
         dirname: dir,
         basename: base,
         filePath: changedFile,
         sourceRoot: source,
-        useWorker: false
+        useWorker: false,
+        hydrate: shouldHydrate,
       });
+      
+      // Handle the result - can be string or { html, hydrationScript }
+      if (typeof renderResult === 'object' && renderResult.html) {
+        body = renderResult.html;
+        hydrationScript = renderResult.hydrationScript || '';
+      } else {
+        body = renderResult;
+      }
     } else {
       body = renderFile({
         fileContents: rawBody,
@@ -1425,6 +1489,11 @@ export async function regenerateSingleFile(changedFile, {
     // Check if this file has a custom menu
     const customMenuInfo = customMenus ? getCustomMenuForFile(changedFile, source, customMenus) : null;
 
+    // Append hydration script to customScript if present (for MDX with hydrate: true)
+    const finalCustomScript = hydrationScript 
+      ? customScript + '\n' + hydrationScript 
+      : customScript;
+
     // Build final HTML
     let finalHtml = template;
     const replacements = {
@@ -1434,7 +1503,7 @@ export async function regenerateSingleFile(changedFile, {
       "${transformedMetadata}": transformedMetadata,
       "${body}": body,
       "${styleLink}": styleLink,
-      "${customScript}": customScript,
+      "${customScript}": finalCustomScript,
       "${searchIndex}": "[]",
       "${footer}": footer
     };
@@ -1496,9 +1565,9 @@ export async function regenerateSingleFile(changedFile, {
     // Update hash cache
     updateHash(changedFile, rawBody, hashCache);
     
-    // Update recent-activity.json with this file's new mtime
+    // Update recent-activity.json with this file's new content timestamp
     try {
-      const fileStat = await stat(changedFile);
+      const now = Date.now();
       const recentActivityPath = join(output, 'public', 'recent-activity.json');
       let recentActivity = [];
       try {
@@ -1507,12 +1576,16 @@ 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
-      recentActivity.push({ title, url, mtime: fileStat.mtimeMs });
+      // 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
     }