@canopy-iiif/app 0.7.9 → 0.7.10

package/lib/build/build.js

@@ -19,6 +19,7 @@ const {
 const { ensureStyles } = require("./styles");
 const { copyAssets } = require("./assets");
 const { logLine } = require("./log");
+const { verifyBuildOutput } = require("./verify");
 
 // hold records between builds if skipping IIIF
 let iiifRecordsCache = [];
@@ -57,11 +58,15 @@ async function build(options = {}) {
     underscore: true,
   });
   let iiifRecords = [];
+  const CONFIG = await iiif.loadConfig();
   if (!skipIiif) {
-    const CONFIG = await iiif.loadConfig();
     const results = await iiif.buildIiifCollectionPages(CONFIG);
     iiifRecords = results?.iiifRecords;
   }
+  // 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
+  // the traversed collection or when IIIF build is skipped during incremental rebuilds.
+  try { await iiif.ensureFeaturedInCache(CONFIG); } catch (_) {}
 
   /**
    * Build contextual MDX content from the content directory.
@@ -72,6 +77,7 @@ async function build(options = {}) {
     bright: true,
     underscore: true,
   });
+  // FeaturedHero now reads directly from the local IIIF cache; no API file needed
   pageRecords = await searchBuild.collectMdxPageRecords();
   await pages.buildContentTree(CONTENT_DIR, pageRecords);
   logLine("✓ MDX pages built", "green");
@@ -94,6 +100,8 @@ async function build(options = {}) {
     logLine("  " + String(e), "red");
   }
 
+  // No-op: Featured API file no longer written (SSR reads from cache directly)
+
   /**
    * Prepare client runtimes (e.g. search) by bundling with esbuild.
    * This is done early so that MDX content can reference runtime assets if needed.
@@ -116,6 +124,17 @@ async function build(options = {}) {
     underscore: true,
   });
   await copyAssets();
+
+  /**
+   * Final verification (checklist)
+   */
+  try {
+    verifyBuildOutput({ outDir: OUT_DIR });
+  } catch (e) {
+    logLine("✗ Build verification failed", "red", { bright: true });
+    logLine(String(e && e.message ? e.message : e), "red");
+    process.exit(1);
+  }
 }
 
 module.exports = { build };

package/lib/build/iiif.js

@@ -365,6 +365,51 @@ async function saveCachedManifest(manifest, id, parentId) {
   } catch (_) {}
 }
 
+// Ensure any configured featured manifests are present in the local cache
+// (and have thumbnails computed) so SSR components like <Hero /> can read them.
+async function ensureFeaturedInCache(cfg) {
+  try {
+    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'));
+    for (const rawId of featured) {
+      const id = normalizeIiifId(String(rawId || ''));
+      if (!id) continue;
+      let manifest = await loadCachedManifestById(id);
+      if (!manifest) {
+        const m = await readJsonFromUri(id).catch(() => null);
+        if (!m) continue;
+        const v3 = await normalizeToV3(m);
+        if (!v3 || !v3.id) continue;
+        await saveCachedManifest(v3, id, '');
+        manifest = v3;
+      }
+      // Ensure thumbnail fields exist in index for this manifest (if computable)
+      try {
+        const t = await getThumbnail(manifest, thumbSize, unsafeThumbs);
+        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);
+            }
+          }
+        }
+      } catch (_) {}
+    }
+  } catch (_) {
+    // ignore failures; fallback SSR will still render a minimal hero without content
+  }
+}
+
 async function flushManifestCache() {
   try {
     await fsp.rm(IIIF_CACHE_MANIFESTS_DIR, { recursive: true, force: true });
@@ -762,7 +807,11 @@ async function buildIiifCollectionPages(CONFIG) {
             href = withBase(href);
             return React.createElement("a", { href, ...rest }, props.children);
           };
+          // Map exported UI components into MDX, with sensible aliases/fallbacks
           const compMap = { ...components, a: Anchor };
+          if (!compMap.SearchPanel && compMap.CommandPalette) {
+            compMap.SearchPanel = compMap.CommandPalette;
+          }
           if (!components.HelloWorld) {
             components.HelloWorld = components.Fallback
               ? (props) =>
@@ -811,6 +860,7 @@ async function buildIiifCollectionPages(CONFIG) {
             .join("/");
           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 needsHydrate =
             body.includes("data-canopy-hydrate") ||
@@ -836,6 +886,15 @@ async function buildIiifCollectionPages(CONFIG) {
                 .split(path.sep)
                 .join("/")
             : null;
+          const heroRel = needsHero
+            ? path
+                .relative(
+                  path.dirname(outPath),
+                  path.join(OUT_DIR, "scripts", "canopy-hero.js")
+                )
+                .split(path.sep)
+                .join("/")
+            : null;
           const relatedRel = needsRelated
             ? path
                 .relative(
@@ -856,11 +915,12 @@ async function buildIiifCollectionPages(CONFIG) {
             : null;
 
           let jsRel = null;
-          if (needsRelated && sliderRel) jsRel = sliderRel;
+          if (needsHero && heroRel) jsRel = heroRel;
+          else if (needsRelated && sliderRel) jsRel = sliderRel;
           else if (viewerRel) jsRel = viewerRel;
 
           let headExtra = head;
-          const needsReact = !!(needsHydrateViewer || needsRelated);
+          const needsReact = !!(needsHydrateViewer || needsRelated || needsHero);
           let vendorTag = "";
           if (needsReact) {
             try {
@@ -881,6 +941,8 @@ async function buildIiifCollectionPages(CONFIG) {
             } catch (_) {}
           }
           const extraScripts = [];
+          if (heroRel && jsRel !== heroRel)
+            extraScripts.push(`<script defer src="${heroRel}"></script>`);
           if (relatedRel && jsRel !== relatedRel)
             extraScripts.push(`<script defer src="${relatedRel}"></script>`);
           if (viewerRel && jsRel !== viewerRel)
@@ -979,6 +1041,10 @@ module.exports = {
   loadConfig,
   loadManifestIndex,
   saveManifestIndex,
+  // Expose helpers used by build for cache warming
+  loadCachedManifestById,
+  saveCachedManifest,
+  ensureFeaturedInCache,
 };
 
 // Debug: list collections cache after traversal

package/lib/build/mdx.js

@@ -44,15 +44,210 @@ async function getMdxProvider() {
 }
 
 // Lazily load UI components from the workspace package and cache them.
+// Re-import when the built UI server bundle changes on disk.
 let UI_COMPONENTS = null;
+let UI_COMPONENTS_PATH = '';
+let UI_COMPONENTS_MTIME = 0;
+const DEBUG = process.env.CANOPY_DEBUG === '1' || process.env.CANOPY_DEBUG === 'true';
 async function loadUiComponents() {
-  if (UI_COMPONENTS) return UI_COMPONENTS;
+  // Do not rely on a cached mapping; re-import each time to avoid transient races.
+  const fallbackCommand = function CommandPalette(props = {}) {
+    const {
+      placeholder = 'Search…',
+      hotkey = 'mod+k',
+      maxResults = 8,
+      groupOrder = ['work', 'page'],
+      button = true,
+      buttonLabel = 'Search',
+      label,
+      searchPath = '/search',
+    } = props || {};
+    const text = (typeof label === 'string' && label.trim()) ? label.trim() : buttonLabel;
+    let json = "{}";
+    try { json = JSON.stringify({ placeholder, hotkey, maxResults, groupOrder, label: text, searchPath }); } catch (_) { json = "{}"; }
+    return React.createElement(
+      'div',
+      { 'data-canopy-command': true, className: 'flex-1 min-w-0' },
+      // Teaser form fallback
+      React.createElement('div', { className: 'relative w-full' },
+        React.createElement('style', { dangerouslySetInnerHTML: { __html: ".relative[data-canopy-panel-auto='1']:focus-within [data-canopy-command-panel]{display:block}" } }),
+        React.createElement('form', { action: searchPath, method: 'get', role: 'search', className: 'group flex items-center gap-2 px-2 py-1.5 rounded-lg border border-slate-300 bg-white/95 backdrop-blur text-slate-700 shadow-sm hover:shadow transition w-full focus-within:ring-2 focus-within:ring-brand-500' },
+          // Left icon
+          React.createElement('span', { 'aria-hidden': true, className: 'text-slate-500' }, '🔎'),
+          // Input teaser
+          React.createElement('input', { type: 'search', name: 'q', 'data-canopy-command-input': true, placeholder, 'aria-label': 'Search', className: 'flex-1 bg-transparent outline-none placeholder:text-slate-400 py-0.5 min-w-0' }),
+          // Right submit (navigates)
+          React.createElement('button', { type: 'submit', 'data-canopy-command-link': true, className: 'inline-flex items-center gap-1 px-2 py-1 rounded-md border border-slate-200 bg-slate-50 hover:bg-slate-100 text-slate-700' }, text)
+        ),
+        // SSR placeholder panel; runtime will reuse and control visibility
+        React.createElement('div', { 'data-canopy-command-panel': true, style: { display: 'none', position: 'absolute', left: 0, right: 0, top: 'calc(100% + 4px)', background: '#fff', border: '1px solid #e5e7eb', borderRadius: '8px', boxShadow: '0 10px 25px rgba(0,0,0,0.12)', zIndex: 1000, overflow: 'auto', maxHeight: '60vh' } },
+          React.createElement('div', { id: 'cplist' })
+        )
+      ),
+      React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: json } })
+    );
+  };
   try {
-    // Use server-safe UI subset to avoid importing browser-only components
-    const mod = await import("@canopy-iiif/app/ui/server");
-    UI_COMPONENTS = mod || {};
+    // Prefer resolving the actual dist file and busting cache via mtime to pick up new exports during dev
+    let resolved = null;
+    // Prefer explicit dist path to avoid export-map issues
+    try { resolved = require.resolve("@canopy-iiif/app/ui/dist/server.mjs"); } catch (_) {
+      try { resolved = require.resolve("@canopy-iiif/app/ui/server"); } catch (_) { resolved = null; }
+    }
+    // Determine current mtime for change detection
+    let currentPath = resolved || '';
+    let currentMtime = 0;
+    if (currentPath) {
+      try { const st = fs.statSync(currentPath); currentMtime = Math.floor(st.mtimeMs || 0); } catch (_) { currentMtime = 0; }
+    }
+    // If we have a cached module and the path/mtime have not changed, return cached
+    if (UI_COMPONENTS && UI_COMPONENTS_PATH === currentPath && UI_COMPONENTS_MTIME === currentMtime) {
+      if (DEBUG) {
+        try { console.log('[canopy][mdx] UI components cache hit:', { path: UI_COMPONENTS_PATH, mtime: UI_COMPONENTS_MTIME }); } catch(_){}
+      }
+      return UI_COMPONENTS;
+    }
+    let mod = null;
+    if (resolved) {
+      const { pathToFileURL } = require("url");
+      let bust = currentMtime ? `?v=${currentMtime}` : `?v=${Date.now()}`;
+      mod = await import(pathToFileURL(resolved).href + bust).catch((e) => {
+        if (DEBUG) { try { console.warn('[canopy][mdx] ESM import failed for', resolved, '\n', e && (e.stack || e.message || String(e))); } catch(_){} }
+        return null;
+      });
+      if (DEBUG) {
+        try { console.log('[canopy][mdx] UI components resolved', { path: resolved, mtime: currentMtime, loaded: !!mod }); } catch(_){}
+      }
+    }
+    if (!mod) {
+      mod = await import("@canopy-iiif/app/ui/server").catch((e) => {
+        if (DEBUG) { try { console.warn('[canopy][mdx] Export-map import failed for @canopy-iiif/app/ui/server', '\n', e && (e.stack || e.message || String(e))); } catch(_){} }
+        return null;
+      });
+      if (DEBUG) {
+        try { console.log('[canopy][mdx] UI components fallback import via export map', { ok: !!mod }); } catch(_){}
+      }
+    }
+    let comp = (mod && typeof mod === 'object') ? mod : {};
+    // Fallback: import workspace source directly if key exports missing
+    const needFallback = !(comp && (comp.CommandPalette || comp.FeaturedHero || comp.Viewer));
+    if (needFallback) {
+      try {
+        const ws = path.join(process.cwd(), 'packages', 'app', 'ui', 'server.js');
+        if (fs.existsSync(ws)) {
+          const { pathToFileURL } = require('url');
+          // Use workspace server.js mtime for busting
+          let bustWs = `?v=${Date.now()}`;
+          try { const st = fs.statSync(ws); currentPath = ws; currentMtime = Math.floor(st.mtimeMs || 0); bustWs = `?v=${currentMtime}`; } catch (_) {}
+          const wsMod = await import(pathToFileURL(ws).href + bustWs).catch(() => null);
+          if (wsMod && typeof wsMod === 'object') {
+            comp = { ...wsMod, ...comp };
+          }
+          if (DEBUG) {
+            try { console.log('[canopy][mdx] UI components augmented from workspace source', { ws, ok: !!wsMod }); } catch(_){}
+          }
+        }
+      } catch (_) {}
+    }
+    // Ensure core placeholders exist to avoid MDX compile failures
+    if (!comp.CommandPalette) comp.CommandPalette = fallbackCommand;
+    if (!comp.SearchPanel) comp.SearchPanel = comp.CommandPalette || fallbackCommand;
+    if (DEBUG) {
+      try { console.log('[canopy][mdx] UI component sources', {
+        path: currentPath,
+        mtime: currentMtime,
+        hasServerExport: !!mod,
+        hasWorkspace: typeof comp !== 'undefined',
+        CommandPalette: !!comp.CommandPalette,
+        Viewer: !!comp.Viewer,
+        Slider: !!comp.Slider,
+      }); } catch(_){}
+    }
+    const mkJson = (props) => {
+      try { return JSON.stringify(props || {}); } catch (_) { return '{}'; }
+    };
+    if (!comp.Viewer) comp.Viewer = function Viewer(props){
+      return React.createElement('div', { 'data-canopy-viewer': '1', className: 'not-prose' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    if (!comp.Slider) comp.Slider = function Slider(props){
+      return React.createElement('div', { 'data-canopy-slider': '1', className: 'not-prose' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    if (!comp.RelatedItems) comp.RelatedItems = function RelatedItems(props){
+      return React.createElement('div', { 'data-canopy-related-items': '1', className: 'not-prose' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    if (!comp.SearchForm) comp.SearchForm = function SearchForm(props){
+      return React.createElement('div', { 'data-canopy-search-form': '1' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    if (!comp.SearchResults) comp.SearchResults = function SearchResults(props){
+      return React.createElement('div', { 'data-canopy-search-results': '1' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    if (!comp.SearchSummary) comp.SearchSummary = function SearchSummary(props){
+      return React.createElement('div', { 'data-canopy-search-summary': '1' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    if (!comp.SearchTotal) comp.SearchTotal = function SearchTotal(props){
+      return React.createElement('div', { 'data-canopy-search-total': '1' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    if (!comp.SearchTabs) comp.SearchTabs = function SearchTabs(props){
+      return React.createElement('div', { 'data-canopy-search-tabs': '1' },
+        React.createElement('script', { type: 'application/json', dangerouslySetInnerHTML: { __html: mkJson(props) } })
+      );
+    };
+    // Ensure a minimal SSR Hero exists
+    if (!comp.Hero) {
+      comp.Hero = function SimpleHero({ height = 360, item, className = '', style = {}, ...rest }){
+        const h = typeof height === 'number' ? `${height}px` : String(height || '').trim() || '360px';
+        const base = { position: 'relative', width: '100%', height: h, overflow: 'hidden', backgroundColor: 'var(--color-gray-muted)', ...style };
+        const title = (item && item.title) || '';
+        const href = (item && item.href) || '#';
+        const thumbnail = (item && item.thumbnail) || '';
+        return React.createElement('div', { className: ['canopy-hero', className].filter(Boolean).join(' '), style: base, ...rest },
+          thumbnail ? React.createElement('img', { src: thumbnail, alt: '', 'aria-hidden': 'true', style: { position:'absolute', inset:0, width:'100%', height:'100%', objectFit:'cover', objectPosition:'center', filter:'none' } }) : null,
+          React.createElement('div', { className:'canopy-hero-overlay', style: { position:'absolute', left:0, right:0, bottom:0, padding:'1rem', background:'linear-gradient(180deg, rgba(0,0,0,0) 0%, rgba(0,0,0,0.35) 55%, rgba(0,0,0,0.65) 100%)', color:'white' } },
+            React.createElement('h3', { style: { margin:0, fontSize:'1.5rem', fontWeight:600, lineHeight:1.2, textShadow:'0 1px 3px rgba(0,0,0,0.6)' } },
+              React.createElement('a', { href, style:{ color:'inherit', textDecoration:'none' }, className:'canopy-hero-link' }, title)
+            )
+          )
+        );
+      };
+    }
+    // Provide a minimal SSR FeaturedHero fallback if missing
+    if (!comp.FeaturedHero) {
+      try {
+        const helpers = require('../components/featured');
+        comp.FeaturedHero = function FeaturedHero(props) {
+          try {
+            const list = helpers && helpers.readFeaturedFromCacheSync ? helpers.readFeaturedFromCacheSync() : [];
+            if (!Array.isArray(list) || list.length === 0) return null;
+            const index = (props && typeof props.index === 'number') ? Math.max(0, Math.min(list.length - 1, Math.floor(props.index))) : null;
+            const pick = (index != null) ? index : ((props && (props.random === true || props.random === 'true')) ? Math.floor(Math.random() * list.length) : 0);
+            const item = list[pick] || list[0];
+            return React.createElement(comp.Hero, { ...props, item });
+          } catch (_) { return null; }
+        };
+      } catch (_) { /* ignore */ }
+    }
+    UI_COMPONENTS = comp;
+    UI_COMPONENTS_PATH = currentPath;
+    UI_COMPONENTS_MTIME = currentMtime;
   } catch (_) {
-    UI_COMPONENTS = {};
+    // As a last resort, supply minimal stubs so pages still compile
+    UI_COMPONENTS = { CommandPalette: fallbackCommand };
+    UI_COMPONENTS_PATH = '';
+    UI_COMPONENTS_MTIME = 0;
   }
   return UI_COMPONENTS;
 }
@@ -672,6 +867,79 @@ async function ensureReactGlobals() {
   });
 }
 
+// Bundle a small runtime to hydrate <Hero /> placeholders from featured items
+async function ensureHeroRuntime() {
+  let esbuild = null;
+  try { esbuild = require("../../ui/node_modules/esbuild"); } catch (_) { try { esbuild = require("esbuild"); } catch (_) {} }
+  if (!esbuild) return;
+  const { path } = require("../common");
+  ensureDirSync(OUT_DIR);
+  const scriptsDir = path.join(OUT_DIR, 'scripts');
+  ensureDirSync(scriptsDir);
+  const outFile = path.join(scriptsDir, 'canopy-hero.js');
+  const entry = `
+    import { Hero } from '@canopy-iiif/app/ui';
+    function ready(fn){ if(document.readyState==='loading') document.addEventListener('DOMContentLoaded', fn, { once: true }); else fn(); }
+    function parseProps(el){ try{ const s=el.querySelector('script[type="application/json"]'); if(s) return JSON.parse(s.textContent||'{}'); }catch(_){ } return {}; }
+    function rootBase(){ try { var bp=(window&&window.CANOPY_BASE_PATH)?String(window.CANOPY_BASE_PATH):''; return bp && bp.endsWith('/') ? bp.slice(0,-1) : bp; } catch(_){ return ''; } }
+    async function getApiVersion(){ try{ const u=rootBase() + '/api/index.json'; const res=await fetch(u).catch(()=>null); const j=res&&res.ok?await res.json().catch(()=>null):null; return (j && j.version) || ''; }catch(_){ return ''; } }
+    async function loadFeatured(){ try { const v = await getApiVersion(); const q = v ? ('?v='+encodeURIComponent(v)) : ''; const res = await fetch(rootBase() + '/api/featured.json' + q).catch(()=>null); const j = res && res.ok ? await res.json().catch(()=>[]) : []; return Array.isArray(j) ? j : (j && j.items) || []; } catch(_){ return []; } }
+    function mount(el, rec){ try{ const React=(window&&window.React)||null; const RDC=(window&&window.ReactDOMClient)||null; const createRoot = RDC && RDC.createRoot; if(!React||!createRoot) return; const props = parseProps(el) || {}; const height = props.height || 360; const node = React.createElement(Hero, { height, item: rec }); const root=createRoot(el); root.render(node); } catch(_){} }
+    ready(async function(){ const hosts = Array.from(document.querySelectorAll('[data-canopy-hero]')); if(!hosts.length) return; const featured = await loadFeatured(); if(!featured.length) return; hosts.forEach((el, i) => { try { const p = parseProps(el) || {}; let idx = 0; if (p && typeof p.index === 'number') idx = Math.max(0, Math.min(featured.length-1, Math.floor(p.index))); else if (p && (p.random===true || p.random==='true')) idx = Math.floor(Math.random() * featured.length); const rec = featured[idx] || featured[0]; if (rec) mount(el, rec); } catch(_){} }); });
+  `;
+  const reactShim = `
+    const React = (typeof window !== 'undefined' && window.React) || {};
+    export default React;
+    export const Children = React.Children;
+    export const Component = React.Component;
+    export const Fragment = React.Fragment;
+    export const createElement = React.createElement;
+    export const cloneElement = React.cloneElement;
+    export const createContext = React.createContext;
+    export const forwardRef = React.forwardRef;
+    export const memo = React.memo;
+    export const startTransition = React.startTransition;
+    export const isValidElement = React.isValidElement;
+    export const useEffect = React.useEffect;
+    export const useLayoutEffect = React.useLayoutEffect;
+    export const useMemo = React.useMemo;
+    export const useState = React.useState;
+    export const useRef = React.useRef;
+    export const useCallback = React.useCallback;
+    export const useContext = React.useContext;
+    export const useReducer = React.useReducer;
+    export const useId = React.useId;
+  `;
+  const rdomClientShim = `
+    const RDC = (typeof window !== 'undefined' && window.ReactDOMClient) || {};
+    export default RDC;
+    export const createRoot = RDC.createRoot;
+    export const hydrateRoot = RDC.hydrateRoot;
+  `;
+  const plugin = {
+    name: 'canopy-react-shims-hero',
+    setup(build) {
+      const ns = 'canopy-shim';
+      build.onResolve({ filter: /^react$/ }, () => ({ path: 'react', namespace: ns }));
+      build.onResolve({ filter: /^react-dom\/client$/ }, () => ({ path: 'react-dom-client', namespace: ns }));
+      build.onLoad({ filter: /^react$/, namespace: ns }, () => ({ contents: reactShim, loader: 'js' }));
+      build.onLoad({ filter: /^react-dom-client$/, namespace: ns }, () => ({ contents: rdomClientShim, loader: 'js' }));
+    }
+  };
+  await esbuild.build({
+    stdin: { contents: entry, resolveDir: process.cwd(), sourcefile: 'canopy-hero-entry.js', loader: 'js' },
+    outfile: outFile,
+    platform: 'browser',
+    format: 'iife',
+    bundle: true,
+    sourcemap: false,
+    target: ['es2018'],
+    logLevel: 'silent',
+    minify: true,
+    plugins: [plugin],
+  });
+}
+
 module.exports = {
   extractTitle,
   isReservedFile,
@@ -682,6 +950,7 @@ module.exports = {
   loadAppWrapper,
   ensureClientRuntime,
   ensureSliderRuntime,
+  ensureHeroRuntime,
   ensureFacetsRuntime,
   ensureReactGlobals,
   resetMdxCaches: function () {
@@ -689,5 +958,6 @@ module.exports = {
       DIR_LAYOUTS.clear();
     } catch (_) {}
     APP_WRAPPER = null;
+    UI_COMPONENTS = null;
   },
 };

package/lib/build/pages.js

@@ -62,9 +62,13 @@ 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;
-  const commandRel = needsCommand
-    ? path.relative(path.dirname(outPath), path.join(OUT_DIR, 'scripts', 'canopy-command.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 jsRel = null;
   if (needsFacets && sliderRel) jsRel = sliderRel;
   else if (viewerRel) jsRel = viewerRel;

package/lib/build/runtimes.js

@@ -6,6 +6,12 @@ async function prepareAllRuntimes() {
   const mdx = require('./mdx');
   try { await mdx.ensureClientRuntime(); } catch (_) {}
   try { if (typeof mdx.ensureSliderRuntime === 'function') await mdx.ensureSliderRuntime(); } catch (_) {}
+  // Optional: Hero runtime is SSR-only by default; enable explicitly to avoid bundling Node deps in browser
+  try {
+    if (process.env.CANOPY_ENABLE_HERO_RUNTIME === '1' || process.env.CANOPY_ENABLE_HERO_RUNTIME === 'true') {
+      if (typeof mdx.ensureHeroRuntime === 'function') await mdx.ensureHeroRuntime();
+    }
+  } catch (_) {}
   try { if (typeof mdx.ensureFacetsRuntime === 'function') await mdx.ensureFacetsRuntime(); } catch (_) {}
   try { if (typeof mdx.ensureReactGlobals === 'function') await mdx.ensureReactGlobals(); } catch (_) {}
   try { await ensureCommandFallback(); } catch (_) {}
@@ -24,15 +30,63 @@ async function ensureCommandFallback() {
         function norm(s){ try{ return String(s||'').toLowerCase(); }catch(_){ return ''; } }
         function withBase(href){ try{ var bp = (window && window.CANOPY_BASE_PATH) ? String(window.CANOPY_BASE_PATH) : ''; if(!bp) return href; if(/^https?:/i.test(href)) return href; var clean = href.replace(/^\\/+/, ''); return (bp.endsWith('/') ? bp.slice(0,-1) : bp) + '/' + clean; } catch(_){ return href; } }
         function rootBase(){ try { var bp = (window && window.CANOPY_BASE_PATH) ? String(window.CANOPY_BASE_PATH) : ''; return bp && bp.endsWith('/') ? bp.slice(0,-1) : bp; } catch(_) { return ''; } }
-        function createUI(){ var root=document.createElement('div'); root.setAttribute('data-canopy-command-fallback',''); root.style.cssText='position:fixed;inset:0;display:none;align-items:flex-start;justify-content:center;background:rgba(0,0,0,0.3);z-index:9999;padding-top:10vh;'; root.innerHTML='<div style="position:relative;background:#fff;min-width:320px;max-width:720px;width:90%;border-radius:8px;box-shadow:0 10px 30px rgba(0,0,0,0.2);overflow:hidden;font-family:system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Helvetica,Arial,sans-serif"><button id="cpclose" aria-label="Close" style="position:absolute;top:8px;right:8px;border:1px solid #e5e7eb;background:#fff;border-radius:6px;padding:2px 6px;cursor:pointer">&times;</button><div style="padding:10px 12px;border-bottom:1px solid #e5e7eb"><input id="cpq" type="text" placeholder="Search…" style="width:100%;padding:8px 10px;border:1px solid #e5e7eb;border-radius:6px;outline:none"/></div><div id="cplist" style="max-height:50vh;overflow:auto;padding:6px 0"></div></div>'; document.body.appendChild(root); return root; }
+        function isOnSearchPage(){ try{ var base=rootBase(); var p=String(location.pathname||''); if(base && p.startsWith(base)) p=p.slice(base.length); if(p.endsWith('/')) p=p.slice(0,-1); return p==='/search'; }catch(_){ return false; } }
+        function createUI(host){ var rel=(function(){ try{ var w=host.querySelector('.relative'); return w||host; }catch(_){ return host; } })(); try{ var cs = window.getComputedStyle(rel); if(!cs || cs.position==='static') rel.style.position='relative'; }catch(_){ } var existing = rel.querySelector('[data-canopy-command-panel]'); if(existing) return existing; var panel=document.createElement('div'); panel.setAttribute('data-canopy-command-panel',''); panel.style.cssText='position:absolute;left:0;right:0;top:calc(100% + 4px);display:none;background:#fff;border:1px solid #e5e7eb;border-radius:8px;box-shadow:0 10px 25px rgba(0,0,0,0.12);z-index:1000;overflow:auto;max-height:60vh;'; panel.innerHTML='<div id="cplist"></div>'; rel.appendChild(panel); return panel; }
         async function loadRecords(){ try{ var v=''; try{ var m = await fetch(rootBase() + '/api/index.json').then(function(r){return r&&r.ok?r.json():null;}).catch(function(){return null;}); v=(m&&m.version)||''; }catch(_){} var res = await fetch(rootBase() + '/api/search-index.json' + (v?('?v='+encodeURIComponent(v)):'')).catch(function(){return null;}); var j = res && res.ok ? await res.json().catch(function(){return[];}) : []; return Array.isArray(j) ? j : (j && j.records) || []; } catch(_){ return []; } }
-        ready(async function(){ var host=document.querySelector('[data-canopy-command]'); if(!host) return; var cfg=parseProps(host)||{}; var maxResults = Number(cfg.maxResults||8)||8; var groupOrder = Array.isArray(cfg.groupOrder)?cfg.groupOrder:['work','page']; var overlay=createUI(); var input=overlay.querySelector('#cpq'); var list=overlay.querySelector('#cplist'); var btnClose=overlay.querySelector('#cpclose'); var records = await loadRecords(); function render(items){ list.innerHTML=''; if(!items.length){ list.innerHTML='<div style="padding:10px 12px;color:#6b7280">No results found.</div>'; return; } var groups=new Map(); items.forEach(function(r){ var t=String(r.type||'page'); if(!groups.has(t)) groups.set(t, []); groups.get(t).push(r); }); function gl(t){ if(t==='work') return 'Works'; if(t==='page') return 'Pages'; return t.charAt(0).toUpperCase()+t.slice(1);} var ordered=[].concat(groupOrder.filter(function(t){return groups.has(t);})).concat(Array.from(groups.keys()).filter(function(t){return groupOrder.indexOf(t)===-1;})); ordered.forEach(function(t){ var hdr=document.createElement('div'); hdr.textContent=gl(t); hdr.style.cssText='padding:6px 12px;font-weight:600;color:#374151'; list.appendChild(hdr); groups.get(t).forEach(function(r){ var it=document.createElement('div'); it.tabIndex=0; it.style.cssText='display:flex;align-items:center;gap:8px;padding:8px 12px;cursor:pointer'; var thumb=(String(r.type||'')==='work' && r.thumbnail)?r.thumbnail:''; if(thumb){ var img=document.createElement('img'); img.src=thumb; img.alt=''; img.style.cssText='width:40px;height:40px;object-fit:cover;border-radius:4px'; it.appendChild(img);} var span=document.createElement('span'); span.textContent=r.title||r.href; it.appendChild(span); it.onmouseenter=function(){ it.style.background='#f8fafc'; }; it.onmouseleave=function(){ it.style.background='transparent'; }; it.onclick=function(){ try{ window.location.href = withBase(String(r.href||'')); }catch(_){} overlay.style.display='none'; }; list.appendChild(it); }); }); }
-        function filterAndShow(q){ try{ var qq=norm(q); if(!qq){ render([]); return; } var out=[]; for(var i=0;i<records.length;i++){ var r=records[i]; var title=String((r&&r.title)||''); if(!title) continue; if(norm(title).indexOf(qq)!==-1) out.push(r); if(out.length>=maxResults) break; } render(out); }catch(_){} }
-        btnClose.addEventListener('click', function(){ overlay.style.display='none'; });
-        input.addEventListener('input', function(){ filterAndShow(input.value||''); });
-        document.addEventListener('keydown', function(e){ if(e.key==='Escape'){ overlay.style.display='none'; }});
-        host.addEventListener('click', function(e){ var trg=e.target && e.target.closest && e.target.closest('[data-canopy-command-trigger]'); if(trg){ e.preventDefault(); overlay.style.display='flex'; input.focus(); filterAndShow(input.value||''); }});
-        var btn = document.querySelector('[data-canopy-command-trigger]'); if(btn){ btn.addEventListener('click', function(){ overlay.style.display='flex'; input.focus(); filterAndShow(input.value||''); }); }
+        ready(async function(){ var host=document.querySelector('[data-canopy-command]'); if(!host) return; var cfg=parseProps(host)||{}; var maxResults = Number(cfg.maxResults||8)||8; var groupOrder = Array.isArray(cfg.groupOrder)?cfg.groupOrder:['work','page']; var onSearchPage = isOnSearchPage(); var panel=createUI(host); try{ var rel=host.querySelector('.relative'); if(rel && !onSearchPage) rel.setAttribute('data-canopy-panel-auto','1'); }catch(_){} if(onSearchPage){ panel.style.display='none'; } var list=panel.querySelector('#cplist'); var teaser = host.querySelector('[data-canopy-command-input]'); var input = teaser; if(!input){ input = document.createElement('input'); input.type='search'; input.placeholder = cfg.placeholder || 'Search…'; input.setAttribute('aria-label','Search'); input.style.cssText='display:block;width:100%;padding:8px 10px;border-bottom:1px solid #e5e7eb;outline:none;'; panel.insertBefore(input, list); }
+        // Populate from ?q= URL param if present
+        try {
+          var sp = new URLSearchParams(location.search || '');
+          var qp = sp.get('q');
+          if (qp) input.value = qp;
+        } catch(_) {}
+        // Only inject a legacy trigger button if neither a trigger nor a teaser input exists
+        try{ if(!host.querySelector('[data-canopy-command-trigger]') && !host.querySelector('[data-canopy-command-input]')){ var btn=document.createElement('button'); btn.type='button'; btn.setAttribute('data-canopy-command-trigger',''); btn.setAttribute('aria-label','Open search'); btn.className='inline-flex items-center gap-2 px-3 py-1.5 rounded border border-slate-300 text-slate-700 hover:bg-slate-50'; var lbl=((cfg&&cfg.label)||(cfg&&cfg.buttonLabel)||'Search'); var sLbl=document.createElement('span'); sLbl.textContent=String(lbl); var sK=document.createElement('span'); sK.setAttribute('aria-hidden','true'); sK.className='text-slate-500'; sK.textContent='⌘K'; btn.appendChild(sLbl); btn.appendChild(sK); host.appendChild(btn); } }catch(_){ }
+        var records = await loadRecords(); function render(items){ list.innerHTML=''; if(!items.length){ panel.style.display='none'; return; } var groups=new Map(); items.forEach(function(r){ var t=String(r.type||'page'); if(!groups.has(t)) groups.set(t, []); groups.get(t).push(r); }); function gl(t){ if(t==='work') return 'Works'; if(t==='page') return 'Pages'; return t.charAt(0).toUpperCase()+t.slice(1);} var ordered=[].concat(groupOrder.filter(function(t){return groups.has(t);})).concat(Array.from(groups.keys()).filter(function(t){return groupOrder.indexOf(t)===-1;})); ordered.forEach(function(t){ var hdr=document.createElement('div'); hdr.textContent=gl(t); hdr.style.cssText='padding:6px 12px;font-weight:600;color:#374151'; list.appendChild(hdr); groups.get(t).forEach(function(r){ var it=document.createElement('div'); it.setAttribute('data-canopy-item',''); it.tabIndex=0; it.style.cssText='display:flex;align-items:center;gap:8px;padding:8px 12px;cursor:pointer;outline:none;'; var thumb=(String(r.type||'')==='work' && r.thumbnail)?r.thumbnail:''; if(thumb){ var img=document.createElement('img'); img.src=thumb; img.alt=''; img.style.cssText='width:40px;height:40px;object-fit:cover;border-radius:4px'; it.appendChild(img);} var span=document.createElement('span'); span.textContent=r.title||r.href; it.appendChild(span); it.onmouseenter=function(){ it.style.background='#f8fafc'; }; it.onmouseleave=function(){ it.style.background='transparent'; }; it.onfocus=function(){ it.style.background='#eef2ff'; try{ it.scrollIntoView({ block: 'nearest' }); }catch(_){} }; it.onblur=function(){ it.style.background='transparent'; }; it.onclick=function(){ try{ window.location.href = withBase(String(r.href||'')); }catch(_){} panel.style.display='none'; }; list.appendChild(it); }); }); }
+        function getItems(){ try{ return Array.prototype.slice.call(list.querySelectorAll('[data-canopy-item]')); }catch(_){ return []; } }
+        function filterAndShow(q){ try{ var qq=norm(q); if(!qq){ try{ panel.style.display='block'; list.innerHTML=''; }catch(_){} return; } var out=[]; for(var i=0;i<records.length;i++){ var r=records[i]; var title=String((r&&r.title)||''); if(!title) continue; if(norm(title).indexOf(qq)!==-1) out.push(r); if(out.length>=maxResults) break; } render(out); }catch(_){} }
+        input.addEventListener('input', function(){ if(onSearchPage){ try{ var ev = new CustomEvent('canopy:search:setQuery', { detail: { query: (input.value||'') } }); window.dispatchEvent(ev); }catch(_){ } return; } filterAndShow(input.value||''); });
+        // Keyboard navigation: ArrowDown/ArrowUp to move through items; Enter to select
+        input.addEventListener('keydown', function(e){
+          if(e.key==='ArrowDown'){ e.preventDefault(); try{ var items=getItems(); if(items.length){ panel.style.display='block'; items[0].focus(); } }catch(_){} }
+          else if(e.key==='ArrowUp'){ e.preventDefault(); try{ var items2=getItems(); if(items2.length){ panel.style.display='block'; items2[items2.length-1].focus(); } }catch(_){} }
+        });
+        list.addEventListener('keydown', function(e){
+          var cur = e.target && e.target.closest && e.target.closest('[data-canopy-item]');
+          if(!cur) return;
+          if(e.key==='ArrowDown'){
+            e.preventDefault();
+            try{ var arr=getItems(); var i=arr.indexOf(cur); var nxt=arr[Math.min(arr.length-1, i+1)]||cur; nxt.focus(); }catch(_){}
+          } else if(e.key==='ArrowUp'){
+            e.preventDefault();
+            try{ var arr2=getItems(); var i2=arr2.indexOf(cur); if(i2<=0){ input && input.focus && input.focus(); } else { var prv=arr2[i2-1]; (prv||cur).focus(); } }catch(_){}
+          } else if(e.key==='Enter'){
+            e.preventDefault(); try{ cur.click(); }catch(_){}
+          } else if(e.key==='Escape'){
+            panel.style.display='none'; try{ input && input.focus && input.focus(); }catch(_){}
+          }
+        });
+        document.addEventListener('keydown', function(e){ if(e.key==='Escape'){ panel.style.display='none'; }});
+        document.addEventListener('mousedown', function(e){ try{ if(!panel.contains(e.target) && !host.contains(e.target)){ panel.style.display='none'; } }catch(_){} });
+        // Hotkey support (e.g., mod+k)
+        document.addEventListener('keydown', function(e){
+          try {
+            var want = String((cfg && cfg.hotkey) || '').toLowerCase();
+            if (!want) return;
+            var isMod = e.metaKey || e.ctrlKey;
+            if ((want === 'mod+k' || want === 'cmd+k' || want === 'ctrl+k') && isMod && (e.key === 'k' || e.key === 'K')) {
+              e.preventDefault();
+              if(onSearchPage){ try{ var ev2 = new CustomEvent('canopy:search:setQuery', { detail: { hotkey: true } }); window.dispatchEvent(ev2); }catch(_){ } return; }
+              panel.style.display='block';
+              (input && input.focus && input.focus());
+              filterAndShow(input && input.value || '');
+          }
+          } catch(_) { }
+        });
+        function openPanel(){ if(onSearchPage){ try{ var ev3 = new CustomEvent('canopy:search:setQuery', { detail: {} }); window.dispatchEvent(ev3); }catch(_){ } return; } panel.style.display='block'; (input && input.focus && input.focus()); filterAndShow(input && input.value || ''); }
+        host.addEventListener('click', function(e){ var trg=e.target && e.target.closest && e.target.closest('[data-canopy-command-trigger]'); if(trg){ e.preventDefault(); openPanel(); }});
+        var btn = document.querySelector('[data-canopy-command-trigger]'); if(btn){ btn.addEventListener('click', function(){ openPanel(); }); }
+        try{ var teaser2 = host.querySelector('[data-canopy-command-input]'); if(teaser2){ teaser2.addEventListener('focus', function(){ openPanel(); }); } }catch(_){}
       });
     })();
       `;