@canopy-iiif/app 0.8.2 → 0.8.4

package/lib/AGENTS.md

@@ -56,7 +56,7 @@ Logbook Template
 Logbook
 -------
 - 2025-09-26 / chatgpt: Hardened runtime bundlers to throw when esbuild or source compilation fails and required `content/works/_layout.mdx`; build now aborts instead of silently writing placeholder assets.
-- 2025-09-26 / chatgpt: Replaced the legacy command runtime stub with an esbuild-bundled runtime (`search/command-runtime.js`); `prepareCommandRuntime()` now builds `site/scripts/canopy-command.js` and fails if esbuild is missing.
+- 2025-09-26 / chatgpt: Replaced the legacy command runtime stub with an esbuild-bundled runtime (`search/search-form-runtime.js`); `prepareSearchFormRuntime()` now builds `site/scripts/canopy-search-form.js` and fails if esbuild is missing.
 - 2025-09-27 / chatgpt: Documented Tailwind token flow in `app/styles/tailwind.config.js`, compiled UI Sass variables during config load, and exposed `stylesheetHref`/`Stylesheet` helpers via `@canopy-iiif/app/head` so `_app.mdx` can reference the generated CSS directly.
 - 2025-09-27 / chatgpt: Expanded search indexing to harvest MDX pages (respecting frontmatter/layout types), injected BASE_PATH hydration data into search.html, and reworked `mdx.extractTitle()` so generated records surface real headings instead of `Untitled`.
 

package/lib/build/build.js

@@ -20,6 +20,7 @@ const { ensureStyles } = require("./styles");
 const { copyAssets } = require("./assets");
 const { logLine } = require("./log");
 const { verifyBuildOutput } = require("./verify");
+const navigation = require("../components/navigation");
 
 // hold records between builds if skipping IIIF
 let iiifRecordsCache = [];
@@ -41,6 +42,7 @@ async function build(options = {}) {
   });
   logLine("• Reset MDX cache", "blue", { dim: true });
   mdx?.resetMdxCaches();
+  navigation?.resetNavigationCache?.();
   if (!skipIiif) {
     await cleanDir(OUT_DIR);
     logLine(`• Cleaned output directory`, "blue", { dim: true });
@@ -62,6 +64,14 @@ async function build(options = {}) {
   if (!skipIiif) {
     const results = await iiif.buildIiifCollectionPages(CONFIG);
     iiifRecords = results?.iiifRecords;
+    iiifRecordsCache = Array.isArray(iiifRecords) ? iiifRecords : [];
+  } else {
+    iiifRecords = Array.isArray(iiifRecordsCache) ? iiifRecordsCache : [];
+    logLine(
+      `• Reusing cached IIIF search records (${iiifRecords.length})`,
+      "blue",
+      { dim: true }
+    );
   }
   // Ensure any configured featured manifests are cached (and thumbnails computed)
   // so SSR components like <Hero /> can resolve items even if they are not part of

package/lib/build/dev.js

@@ -617,29 +617,45 @@ function startServer() {
     }
     if (pathname === "/") pathname = "/index.html";
 
-    // Resolve candidate paths in order:
-    // 1) as-is
-    // 2) add .html for extensionless
-    // 3) if a directory, use its index.html
-    let filePath = null;
-    const candidateA = path.join(OUT_DIR, pathname);
-    const candidateB = path.join(OUT_DIR, pathname + ".html");
-    if (fs.existsSync(candidateA)) {
-      filePath = candidateA;
-    } else if (fs.existsSync(candidateB)) {
-      filePath = candidateB;
+    function toSitePath(p) {
+      const rel = p.startsWith("/") ? `.${p}` : p;
+      return path.resolve(OUT_DIR, rel);
     }
-    if (!filePath) {
-      // Try directory index for extensionless or folder routes
-      const maybeDir = path.join(OUT_DIR, pathname);
-      if (fs.existsSync(maybeDir)) {
-        try {
-          const st = fs.statSync(maybeDir);
-          if (st.isDirectory()) {
-            const idx = path.join(maybeDir, "index.html");
-            if (fs.existsSync(idx)) filePath = idx;
-          }
-        } catch (_) {}
+
+    const ensureLeadingSlash = (p) => (p.startsWith("/") ? p : `/${p}`);
+    const basePath = ensureLeadingSlash(pathname);
+    const noTrailing = basePath !== "/" ? basePath.replace(/\/+$/, "") : basePath;
+    const attempts = [];
+
+    const primaryPath = noTrailing === "/" ? "/index.html" : noTrailing;
+    attempts.push(toSitePath(primaryPath));
+
+    if (!/\.html$/i.test(primaryPath)) {
+      attempts.push(toSitePath(`${primaryPath}.html`));
+    }
+
+    const withoutHtml = primaryPath.replace(/\.html$/i, "");
+    attempts.push(toSitePath(`${withoutHtml}/index.html`));
+
+    let filePath = null;
+    for (const candidate of attempts) {
+      if (!candidate) continue;
+      let stat;
+      try {
+        stat = fs.statSync(candidate);
+      } catch (_) {
+        continue;
+      }
+      if (stat.isFile()) {
+        filePath = candidate;
+        break;
+      }
+      if (stat.isDirectory()) {
+        const idx = path.join(candidate, "index.html");
+        if (fs.existsSync(idx)) {
+          filePath = idx;
+          break;
+        }
       }
     }
     if (!filePath) {
@@ -969,17 +985,16 @@ async function dev() {
     child = startTailwindWatcher();
 
     const uiPlugin = path.join(
-      __dirname,
-      "../ui",
+      APP_UI_DIR,
       "tailwind-canopy-iiif-plugin.js"
     );
     const uiPreset = path.join(
-      __dirname,
-      "../ui",
+      APP_UI_DIR,
       "tailwind-canopy-iiif-preset.js"
     );
-    const uiStylesDir = path.join(__dirname, "../ui", "styles");
-    const files = [uiPlugin, uiPreset].filter((p) => {
+    const uiStylesDir = path.join(APP_UI_DIR, "styles");
+    const uiStylesCss = path.join(uiStylesDir, "index.css");
+    const pluginFiles = [uiPlugin, uiPreset].filter((p) => {
       try {
         return fs.existsSync(p);
       } catch (_) {
@@ -987,25 +1002,54 @@ async function dev() {
       }
     });
     let restartTimer = null;
-    const restart = () => {
+    let uiCssWatcherAttached = false;
+    const scheduleTailwindRestart = (message, compileLabel) => {
       clearTimeout(restartTimer);
       restartTimer = setTimeout(() => {
-        console.log(
-          "[tailwind] detected UI plugin/preset change — restarting Tailwind"
-        );
+        if (message) console.log(message);
         try {
           if (child && !child.killed) child.kill();
         } catch (_) {}
-        safeCompile("[tailwind] compile after plugin change failed");
+        safeCompile(compileLabel);
         child = startTailwindWatcher();
         try { onBuildStart(); } catch (_) {}
-      }, 50);
+      }, 120);
     };
-    for (const f of files) {
+    for (const f of pluginFiles) {
       try {
-        fs.watch(f, { persistent: false }, restart);
+        fs.watch(f, { persistent: false }, () => {
+          scheduleTailwindRestart(
+            "[tailwind] detected UI plugin/preset change — restarting Tailwind",
+            "[tailwind] compile after plugin change failed"
+          );
+        });
       } catch (_) {}
     }
+    const attachCssWatcher = () => {
+      if (uiCssWatcherAttached) {
+        if (fs.existsSync(uiStylesCss)) return;
+        uiCssWatcherAttached = false;
+      }
+      if (!fs.existsSync(uiStylesCss)) return;
+      const handler = () =>
+        scheduleTailwindRestart(
+          "[tailwind] detected @canopy-iiif/app/ui styles change — restarting Tailwind",
+          "[tailwind] compile after UI styles change failed"
+        );
+      try {
+        const watcher = fs.watch(uiStylesCss, { persistent: false }, handler);
+        uiCssWatcherAttached = true;
+        watcher.on("close", () => {
+          uiCssWatcherAttached = false;
+        });
+      } catch (_) {
+        try {
+          fs.watchFile(uiStylesCss, { interval: 250 }, handler);
+          uiCssWatcherAttached = true;
+        } catch (_) {}
+      }
+    };
+    attachCssWatcher();
     if (fs.existsSync(uiStylesDir)) {
       try {
         fs.watch(
@@ -1013,7 +1057,7 @@ async function dev() {
           { persistent: false, recursive: true },
           (evt, fn) => {
             try {
-              if (fn && /\.s[ac]ss$/i.test(String(fn))) restart();
+              if (fn && /\.s[ac]ss$/i.test(String(fn))) attachCssWatcher();
             } catch (_) {}
           }
         );
@@ -1027,8 +1071,9 @@ async function dev() {
               { persistent: false },
               (evt, fn) => {
                 try {
-                  if (fn && /\.s[ac]ss$/i.test(String(fn))) restart();
+                  if (fn && /\.s[ac]ss$/i.test(String(fn))) attachCssWatcher();
                 } catch (_) {}
+                scan(dir);
               }
             );
             watchers.set(dir, w);
@@ -1055,8 +1100,10 @@ async function dev() {
     if (fs.existsSync(configPath)) {
       try {
         fs.watch(configPath, { persistent: false }, () => {
-          console.log("[tailwind] tailwind.config change — restarting Tailwind");
-          restart();
+          scheduleTailwindRestart(
+            "[tailwind] tailwind.config change — restarting Tailwind",
+            "[tailwind] compile after config change failed"
+          );
         });
       } catch (_) {}
     }

package/lib/build/iiif.js

@@ -32,6 +32,34 @@ const IIIF_CACHE_INDEX_MANIFESTS = path.join(
   "manifest-index.json"
 );
 
+const DEFAULT_THUMBNAIL_SIZE = 400;
+const DEFAULT_CHUNK_SIZE = 20;
+const DEFAULT_FETCH_CONCURRENCY = 5;
+
+function resolvePositiveInteger(value, fallback) {
+  const num = Number(value);
+  if (Number.isFinite(num) && num > 0) return Math.max(1, Math.floor(num));
+  return Math.max(1, Math.floor(fallback));
+}
+
+function resolveBoolean(value) {
+  if (typeof value === "boolean") return value;
+  if (value === undefined || value === null) return false;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) return false;
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+
+function resolveThumbnailPreferences() {
+  return {
+    size: resolvePositiveInteger(
+      process.env.CANOPY_THUMBNAIL_SIZE,
+      DEFAULT_THUMBNAIL_SIZE
+    ),
+    unsafe: resolveBoolean(process.env.CANOPY_THUMBNAILS_UNSAFE),
+  };
+}
+
 function firstLabelString(label) {
   if (!label) return "Untitled";
   if (typeof label === "string") return label;
@@ -373,10 +401,9 @@ async function ensureFeaturedInCache(cfg) {
     const CONFIG = cfg || (await loadConfig());
     const featured = Array.isArray(CONFIG && CONFIG.featured) ? CONFIG.featured : [];
     if (!featured.length) return;
-    const { getThumbnail } = require("../iiif/thumbnail");
-    // Thumbnail sizing config
-    const thumbSize = CONFIG && CONFIG.iiif && CONFIG.iiif.thumbnails && typeof CONFIG.iiif.thumbnails.preferredSize === 'number' ? CONFIG.iiif.thumbnails.preferredSize : 400;
-    const unsafeThumbs = !!(CONFIG && CONFIG.iiif && CONFIG.iiif.thumbnails && (CONFIG.iiif.thumbnails.unsafe === true || CONFIG.iiif.thumbnails.unsafe === 'true'));
+    const { getThumbnail, getRepresentativeImage } = require("../iiif/thumbnail");
+    const { size: thumbSize, unsafe: unsafeThumbs } = resolveThumbnailPreferences();
+    const HERO_THUMBNAIL_SIZE = 1200;
     for (const rawId of featured) {
       const id = normalizeIiifId(String(rawId || ''));
       if (!id) continue;
@@ -392,18 +419,88 @@ async function ensureFeaturedInCache(cfg) {
       // Ensure thumbnail fields exist in index for this manifest (if computable)
       try {
         const t = await getThumbnail(manifest, thumbSize, unsafeThumbs);
+        const idx = await loadManifestIndex();
+        if (!Array.isArray(idx.byId)) continue;
+        const entry = idx.byId.find(
+          (e) =>
+            e &&
+            e.type === 'Manifest' &&
+            normalizeIiifId(String(e.id)) === normalizeIiifId(String(manifest.id))
+        );
+        if (!entry) continue;
+
+        let touched = false;
         if (t && t.url) {
-          const idx = await loadManifestIndex();
-          if (Array.isArray(idx.byId)) {
-            const entry = idx.byId.find((e) => e && e.type === 'Manifest' && normalizeIiifId(String(e.id)) === normalizeIiifId(String(manifest.id)));
-            if (entry) {
-              entry.thumbnail = String(t.url);
-              if (typeof t.width === 'number') entry.thumbnailWidth = t.width;
-              if (typeof t.height === 'number') entry.thumbnailHeight = t.height;
-              await saveManifestIndex(idx);
-            }
+          const nextUrl = String(t.url);
+          if (entry.thumbnail !== nextUrl) {
+            entry.thumbnail = nextUrl;
+            touched = true;
+          }
+          if (typeof t.width === 'number') {
+            if (entry.thumbnailWidth !== t.width) touched = true;
+            entry.thumbnailWidth = t.width;
+          }
+          if (typeof t.height === 'number') {
+            if (entry.thumbnailHeight !== t.height) touched = true;
+            entry.thumbnailHeight = t.height;
           }
         }
+
+        try {
+          const heroSource = (() => {
+            if (manifest && manifest.thumbnail) {
+              const clone = { ...manifest };
+              try {
+                delete clone.thumbnail;
+              } catch (_) {
+                clone.thumbnail = undefined;
+              }
+              return clone;
+            }
+            return manifest;
+          })();
+          const heroRep = await getRepresentativeImage(
+            heroSource || manifest,
+            HERO_THUMBNAIL_SIZE,
+            true
+          );
+          if (heroRep && heroRep.id) {
+            const nextHero = String(heroRep.id);
+            if (entry.heroThumbnail !== nextHero) {
+              entry.heroThumbnail = nextHero;
+              touched = true;
+            }
+            if (typeof heroRep.width === 'number') {
+              if (entry.heroThumbnailWidth !== heroRep.width) touched = true;
+              entry.heroThumbnailWidth = heroRep.width;
+            } else if (entry.heroThumbnailWidth !== undefined) {
+              delete entry.heroThumbnailWidth;
+              touched = true;
+            }
+            if (typeof heroRep.height === 'number') {
+              if (entry.heroThumbnailHeight !== heroRep.height) touched = true;
+              entry.heroThumbnailHeight = heroRep.height;
+            } else if (entry.heroThumbnailHeight !== undefined) {
+              delete entry.heroThumbnailHeight;
+              touched = true;
+            }
+          } else {
+            if (entry.heroThumbnail !== undefined) {
+              delete entry.heroThumbnail;
+              touched = true;
+            }
+            if (entry.heroThumbnailWidth !== undefined) {
+              delete entry.heroThumbnailWidth;
+              touched = true;
+            }
+            if (entry.heroThumbnailHeight !== undefined) {
+              delete entry.heroThumbnailHeight;
+              touched = true;
+            }
+          }
+        } catch (_) {}
+
+        if (touched) await saveManifestIndex(idx);
       } catch (_) {}
     }
   } catch (err) {
@@ -613,11 +710,9 @@ async function buildIiifCollectionPages(CONFIG) {
   if (!tasks.length) return { searchRecords: [] };
 
   // Split into chunks and process with limited concurrency
-  const chunkSize = Math.max(
-    1,
-    Number(
-      process.env.CANOPY_CHUNK_SIZE || (cfg.iiif && cfg.iiif.chunkSize) || 20
-    )
+  const chunkSize = resolvePositiveInteger(
+    process.env.CANOPY_CHUNK_SIZE,
+    DEFAULT_CHUNK_SIZE
   );
   const chunks = Math.ceil(tasks.length / chunkSize);
   // Summary before processing chunks
@@ -630,18 +725,8 @@ async function buildIiifCollectionPages(CONFIG) {
     );
   } catch (_) {}
   const iiifRecords = [];
-  const unsafeThumbs = !!(
-    cfg &&
-    cfg.iiif &&
-    cfg.iiif.thumbnails &&
-    cfg.iiif.thumbnails.unsafe === true
-  );
-  const thumbSize =
-    (cfg &&
-      cfg.iiif &&
-      cfg.iiif.thumbnails &&
-      cfg.iiif.thumbnails.preferredSize) ||
-    1200;
+  const { size: thumbSize, unsafe: unsafeThumbs } =
+    resolveThumbnailPreferences();
 
   // Compile the works layout component once per run
   const worksLayoutPath = path.join(CONTENT_DIR, "works", "_layout.mdx");
@@ -664,13 +749,9 @@ async function buildIiifCollectionPages(CONFIG) {
     const chunk = tasks.slice(ci * chunkSize, (ci + 1) * chunkSize);
     logLine(`• Chunk ${ci + 1}/${chunks}`, "blue", { dim: true });
 
-    const concurrency = Math.max(
-      1,
-      Number(
-        process.env.CANOPY_FETCH_CONCURRENCY ||
-          (cfg.iiif && cfg.iiif.concurrency) ||
-          6
-      )
+    const concurrency = resolvePositiveInteger(
+      process.env.CANOPY_FETCH_CONCURRENCY,
+      DEFAULT_FETCH_CONCURRENCY
     );
     let next = 0;
     const logs = new Array(chunk.length);
@@ -831,12 +912,12 @@ async function buildIiifCollectionPages(CONFIG) {
           const needsHydrateViewer = body.includes("data-canopy-viewer");
           const needsRelated = body.includes("data-canopy-related-items");
           const needsHero = body.includes("data-canopy-hero");
-          const needsCommand = body.includes("data-canopy-command");
+          const needsSearchForm = body.includes("data-canopy-search-form");
           const needsHydrate =
             body.includes("data-canopy-hydrate") ||
             needsHydrateViewer ||
             needsRelated ||
-            needsCommand;
+            needsSearchForm;
 
           const viewerRel = needsHydrateViewer
             ? path
@@ -874,11 +955,11 @@ async function buildIiifCollectionPages(CONFIG) {
                 .split(path.sep)
                 .join("/")
             : null;
-          const commandRel = needsCommand
+          const searchFormRel = needsSearchForm
             ? path
                 .relative(
                   path.dirname(outPath),
-                  path.join(OUT_DIR, "scripts", "canopy-command.js")
+                  path.join(OUT_DIR, "scripts", "canopy-search-form.js")
                 )
                 .split(path.sep)
                 .join("/")
@@ -919,8 +1000,8 @@ async function buildIiifCollectionPages(CONFIG) {
             extraScripts.push(`<script defer src="${viewerRel}"></script>`);
           if (sliderRel && jsRel !== sliderRel)
             extraScripts.push(`<script defer src="${sliderRel}"></script>`);
-          if (commandRel && jsRel !== commandRel)
-            extraScripts.push(`<script defer src="${commandRel}"></script>`);
+          if (searchFormRel && jsRel !== searchFormRel)
+            extraScripts.push(`<script defer src="${searchFormRel}"></script>`);
           if (extraScripts.length)
             headExtra = extraScripts.join("") + headExtra;
           try {

package/lib/build/mdx.js

@@ -12,6 +12,7 @@ const {
   withBase,
 } = require("../common");
 const yaml = require("js-yaml");
+const { getPageContext } = require("../page-context");
 
 function parseFrontmatter(src) {
   let input = String(src || "");
@@ -112,7 +113,7 @@ async function loadUiComponents() {
     }
     let comp = (mod && typeof mod === 'object') ? mod : {};
     // Hard-require core exports; do not inject fallbacks
-    const required = ['SearchPanel', 'CommandPalette', 'SearchResults', 'SearchSummary', 'SearchTabs', 'Viewer', 'Slider', 'RelatedItems', 'Hero', 'FeaturedHero'];
+    const required = ['SearchPanel', 'SearchFormModal', 'SearchResults', 'SearchSummary', 'SearchTabs', 'Viewer', 'Slider', 'RelatedItems', 'Hero', 'FeaturedHero'];
     const missing = required.filter((k) => !comp || !comp[k]);
     if (missing.length) {
       throw new Error('[canopy][mdx] Missing UI exports: ' + missing.join(', '));
@@ -123,7 +124,7 @@ async function loadUiComponents() {
         mtime: currentMtime,
         hasServerExport: !!mod,
         hasWorkspace: typeof comp !== 'undefined',
-        CommandPalette: !!comp.CommandPalette,
+        SearchFormModal: !!comp.SearchFormModal,
         Viewer: !!comp.Viewer,
         Slider: !!comp.Slider,
       }); } catch(_){}
@@ -280,10 +281,19 @@ async function compileMdxFile(filePath, outPath, Layout, extraProps = {}) {
   const app = await loadAppWrapper();
   const dirLayout = await getNearestDirLayout(filePath);
   const contentNode = React.createElement(MDXContent, extraProps);
+  const layoutProps = dirLayout ? { ...extraProps } : null;
   const withLayout = dirLayout
-    ? React.createElement(dirLayout, null, contentNode)
+    ? React.createElement(dirLayout, layoutProps, contentNode)
     : contentNode;
-  const withApp = React.createElement(app.App, null, withLayout);
+  const PageContext = getPageContext();
+  const contextValue = {
+    navigation: extraProps && extraProps.navigation ? extraProps.navigation : null,
+    page: extraProps && extraProps.page ? extraProps.page : null,
+  };
+  const withContext = PageContext
+    ? React.createElement(PageContext.Provider, { value: contextValue }, withLayout)
+    : withLayout;
+  const withApp = React.createElement(app.App, null, withContext);
   const compMap = { ...components, a: Anchor };
   const page = MDXProvider
     ? React.createElement(MDXProvider, { components: compMap }, withApp)

package/lib/build/pages.js

@@ -1,6 +1,7 @@
 const { fs, fsp, path, CONTENT_DIR, OUT_DIR, ensureDirSync, htmlShell } = require('../common');
 const { log } = require('./log');
 const mdx = require('./mdx');
+const navigation = require('../components/navigation');
 
 // Cache: dir -> frontmatter data for _layout.mdx in that dir
 const LAYOUT_META = new Map();
@@ -44,10 +45,23 @@ function mapContentPathToOutput(filePath) {
 async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   const source = await fsp.readFile(filePath, 'utf8');
   const title = mdx.extractTitle(source);
-  const { body, head } = await mdx.compileMdxFile(filePath, outPath, null, extraProps);
+  const relContentPath = path.relative(CONTENT_DIR, filePath);
+  const normalizedRel = navigation.normalizeRelativePath(relContentPath);
+  const pageInfo = navigation.getPageInfo(normalizedRel);
+  const navData = navigation.buildNavigationForFile(normalizedRel);
+  const mergedProps = { ...(extraProps || {}) };
+  if (pageInfo) {
+    mergedProps.page = mergedProps.page
+      ? { ...pageInfo, ...mergedProps.page }
+      : pageInfo;
+  }
+  if (navData && !mergedProps.navigation) {
+    mergedProps.navigation = navData;
+  }
+  const { body, head } = await mdx.compileMdxFile(filePath, outPath, null, mergedProps);
   const needsHydrateViewer = body.includes('data-canopy-viewer');
   const needsHydrateSlider = body.includes('data-canopy-slider');
-  const needsCommand = true; // command runtime is global
+  const needsSearchForm = true; // search form runtime is global
   const needsFacets = body.includes('data-canopy-related-items');
   const viewerRel = needsHydrateViewer
     ? path.relative(path.dirname(outPath), path.join(OUT_DIR, 'scripts', 'canopy-viewer.js')).split(path.sep).join('/')
@@ -58,12 +72,12 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   const facetsRel = needsFacets
     ? path.relative(path.dirname(outPath), path.join(OUT_DIR, 'scripts', 'canopy-related-items.js')).split(path.sep).join('/')
     : null;
-  let commandRel = null;
-  if (needsCommand) {
-    const cmdAbs = path.join(OUT_DIR, 'scripts', 'canopy-command.js');
-    let rel = path.relative(path.dirname(outPath), cmdAbs).split(path.sep).join('/');
-    try { const st = fs.statSync(cmdAbs); rel += `?v=${Math.floor(st.mtimeMs || Date.now())}`; } catch (_) {}
-    commandRel = rel;
+  let searchFormRel = null;
+  if (needsSearchForm) {
+    const runtimeAbs = path.join(OUT_DIR, 'scripts', 'canopy-search-form.js');
+    let rel = path.relative(path.dirname(outPath), runtimeAbs).split(path.sep).join('/');
+    try { const st = fs.statSync(runtimeAbs); rel += `?v=${Math.floor(st.mtimeMs || Date.now())}`; } catch (_) {}
+    searchFormRel = rel;
   }
   let jsRel = null;
   if (needsFacets && sliderRel) jsRel = sliderRel;
@@ -90,7 +104,7 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   if (facetsRel && jsRel !== facetsRel) extraScripts.push(`<script defer src="${facetsRel}"></script>`);
   if (viewerRel && jsRel !== viewerRel) extraScripts.push(`<script defer src="${viewerRel}"></script>`);
   if (sliderRel && jsRel !== sliderRel) extraScripts.push(`<script defer src="${sliderRel}"></script>`);
-  if (commandRel && jsRel !== commandRel) extraScripts.push(`<script defer src="${commandRel}"></script>`);
+  if (searchFormRel && jsRel !== searchFormRel) extraScripts.push(`<script defer src="${searchFormRel}"></script>`);
   if (extraScripts.length) headExtra = extraScripts.join('') + headExtra;
   const html = htmlShell({ title, body, cssHref: null, scriptHref: jsRel, headExtra: vendorTag + headExtra });
   const { applyBaseToHtml } = require('../common');

package/lib/build/runtimes.js

@@ -12,7 +12,7 @@ async function prepareAllRuntimes() {
   } catch (_) {}
   try { if (typeof mdx.ensureFacetsRuntime === 'function') await mdx.ensureFacetsRuntime(); } catch (_) {}
   try { if (typeof mdx.ensureReactGlobals === 'function') await mdx.ensureReactGlobals(); } catch (_) {}
-  await prepareCommandRuntime();
+  await prepareSearchFormRuntime();
   try { logLine('✓ Prepared client hydration runtimes', 'cyan', { dim: true }); } catch (_) {}
 }
 
@@ -24,14 +24,14 @@ async function resolveEsbuild() {
   }
 }
 
-async function prepareCommandRuntime() {
+async function prepareSearchFormRuntime() {
   const esbuild = await resolveEsbuild();
-  if (!esbuild) throw new Error('Command runtime bundling requires esbuild. Install dependencies before building.');
+  if (!esbuild) throw new Error('Search form runtime bundling requires esbuild. Install dependencies before building.');
   ensureDirSync(OUT_DIR);
   const scriptsDir = path.join(OUT_DIR, 'scripts');
   ensureDirSync(scriptsDir);
-  const entry = path.join(__dirname, '..', 'search', 'command-runtime.js');
-  const outFile = path.join(scriptsDir, 'canopy-command.js');
+  const entry = path.join(__dirname, '..', 'search', 'search-form-runtime.js');
+  const outFile = path.join(scriptsDir, 'canopy-search-form.js');
   await esbuild.build({
     entryPoints: [entry],
     outfile: outFile,
@@ -68,4 +68,4 @@ async function prepareSearchRuntime(timeoutMs = 10000, label = '') {
   }
 }
 
-module.exports = { prepareAllRuntimes, prepareCommandRuntime, prepareSearchRuntime };
+module.exports = { prepareAllRuntimes, prepareSearchFormRuntime, prepareSearchRuntime };

package/lib/build/search.js

@@ -188,23 +188,20 @@ async function collectMdxPageRecords() {
           let include = !underSearch;
           let resolvedType = null;
           const pageFm = fm && fm.data ? fm.data : null;
-          if (pageFm) {
-            if (pageFm.search === false) include = false;
-            if (Object.prototype.hasOwnProperty.call(pageFm, 'type')) {
-              if (pageFm.type) resolvedType = String(pageFm.type);
-              else include = false;
-            } else {
-              include = false; // frontmatter present w/o type => exclude per policy
-            }
+          if (pageFm && pageFm.search === false) include = false;
+          if (include && pageFm && Object.prototype.hasOwnProperty.call(pageFm, 'type')) {
+            if (pageFm.type) resolvedType = String(pageFm.type);
+            else include = false;
           }
           if (include && !resolvedType) {
             const layoutMeta = await pagesHelpers.getNearestDirLayoutMeta(p);
             if (layoutMeta && layoutMeta.type) resolvedType = String(layoutMeta.type);
           }
           if (include && !resolvedType) {
-            if (!pageFm) resolvedType = 'page';
+            resolvedType = 'page';
           }
-          pages.push({ title, href, searchInclude: include && !!resolvedType, searchType: resolvedType || undefined });
+          const trimmedType = resolvedType && String(resolvedType).trim();
+          pages.push({ title, href, searchInclude: include && !!trimmedType, searchType: trimmedType || undefined });
         }
       }
     }