@canopy-iiif/app 0.8.1 → 0.8.3

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

@@ -62,6 +62,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

@@ -969,17 +969,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 +986,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 +1041,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 +1055,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 +1084,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

@@ -112,7 +112,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 +123,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(_){}

package/lib/build/pages.js

@@ -47,7 +47,7 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   const { body, head } = await mdx.compileMdxFile(filePath, outPath, null, extraProps);
   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 +58,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 +90,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 });
         }
       }
     }

package/lib/build/verify.js

@@ -21,10 +21,10 @@ function verifyHomepageElements(outDir) {
   const idx = path.join(outDir, 'index.html');
   const html = readFileSafe(idx);
   const okHero = /class=\"[^\"]*canopy-hero/.test(html) || /<div[^>]+canopy-hero/.test(html);
-  const okCommand = /data-canopy-command=/.test(html);
-  const okCommandTrigger = /data-canopy-command-trigger/.test(html);
-  const okCommandScriptRef = /<script[^>]+canopy-command\.js/.test(html);
-  return { okHero, okCommand, okCommandTrigger, okCommandScriptRef, htmlPath: idx };
+  const okSearchForm = /data-canopy-search-form=/.test(html);
+  const okSearchFormTrigger = /data-canopy-search-form-trigger/.test(html);
+  const okSearchFormScriptRef = /<script[^>]+canopy-search-form\.js/.test(html);
+  return { okHero, okSearchForm, okSearchFormTrigger, okSearchFormScriptRef, htmlPath: idx };
 }
 
 function verifyBuildOutput(options = {}) {
@@ -34,7 +34,7 @@ function verifyBuildOutput(options = {}) {
   const okAny = total > 0;
   const indexPath = path.join(outDir, 'index.html');
   const hasIndex = fs.existsSync(indexPath) && fs.statSync(indexPath).size > 0;
-  const { okHero, okCommand, okCommandTrigger, okCommandScriptRef } = verifyHomepageElements(outDir);
+  const { okHero, okSearchForm, okSearchFormTrigger, okSearchFormScriptRef } = verifyHomepageElements(outDir);
 
   const ck = (label, ok, extra) => {
     const status = ok ? '✓' : '✗';
@@ -44,12 +44,12 @@ function verifyBuildOutput(options = {}) {
   ck('HTML pages exist', okAny, okAny ? `(${total})` : '');
   ck('homepage exists', hasIndex, hasIndex ? `(${indexPath})` : '');
   ck('homepage: Hero present', okHero);
-  ck('homepage: Command present', okCommand);
-  ck('homepage: Command trigger present', okCommandTrigger);
-  ck('homepage: Command script referenced', okCommandScriptRef);
+  ck('homepage: Search form present', okSearchForm);
+  ck('homepage: Search form trigger present', okSearchFormTrigger);
+  ck('homepage: Search form script referenced', okSearchFormScriptRef);
 
   // Do not fail build on missing SSR trigger; the client runtime injects a default.
-  const ok = okAny && hasIndex && okHero && okCommand && okCommandScriptRef;
+  const ok = okAny && hasIndex && okHero && okSearchForm && okSearchFormScriptRef;
   if (!ok) {
     const err = new Error('Build verification failed');
     err.outDir = outDir;

package/lib/components/featured.js

@@ -105,9 +105,23 @@ function readFeaturedFromCacheSync() {
         href: rootRelativeHref(path.join('works', slug + '.html').split(path.sep).join('/')),
         type: 'work',
       };
-      if (entry && entry.thumbnail) rec.thumbnail = String(entry.thumbnail);
-      if (entry && typeof entry.thumbnailWidth === 'number') rec.thumbnailWidth = entry.thumbnailWidth;
-      if (entry && typeof entry.thumbnailHeight === 'number') rec.thumbnailHeight = entry.thumbnailHeight;
+      if (entry && entry.heroThumbnail) {
+        rec.thumbnail = String(entry.heroThumbnail);
+        if (typeof entry.heroThumbnailWidth === 'number') {
+          rec.thumbnailWidth = entry.heroThumbnailWidth;
+        } else if (typeof entry.thumbnailWidth === 'number') {
+          rec.thumbnailWidth = entry.thumbnailWidth;
+        }
+        if (typeof entry.heroThumbnailHeight === 'number') {
+          rec.thumbnailHeight = entry.heroThumbnailHeight;
+        } else if (typeof entry.thumbnailHeight === 'number') {
+          rec.thumbnailHeight = entry.thumbnailHeight;
+        }
+      } else {
+        if (entry && entry.thumbnail) rec.thumbnail = String(entry.thumbnail);
+        if (entry && typeof entry.thumbnailWidth === 'number') rec.thumbnailWidth = entry.thumbnailWidth;
+        if (entry && typeof entry.thumbnailHeight === 'number') rec.thumbnailHeight = entry.thumbnailHeight;
+      }
       if (!rec.thumbnail) {
         try {
           const t = m && m.thumbnail;

package/lib/search/search-app.jsx

@@ -681,7 +681,7 @@ function parseProps(el) {
 function bindSearchInputToStore() {
   if (!store || typeof document === "undefined") return;
   try {
-    const input = document.querySelector("[data-canopy-command-input]");
+    const input = document.querySelector("[data-canopy-search-form-input]");
     if (!input || input.dataset.canopySearchSync === "1") return;
     input.dataset.canopySearchSync = "1";
 
@@ -764,7 +764,7 @@ if (typeof document !== "undefined") {
           const q =
             ev && ev.detail && typeof ev.detail.query === "string"
               ? ev.detail.query
-              : document.querySelector("[data-canopy-command-input]")?.value ||
+              : document.querySelector("[data-canopy-search-form-input]")?.value ||
                 "";
           if (typeof q === "string") store.setQuery(q);
         } catch (_) {}

package/lib/search/{command-runtime.js → search-form-runtime.js}

@@ -217,7 +217,7 @@ function bindKeyboardNavigation({ input, list, panel }) {
   });
 }
 
-async function attachCommand(host) {
+async function attachSearchForm(host) {
   const config = parseProps(host) || {};
   const maxResults = Number(config.maxResults || 8) || 8;
   const groupOrder = Array.isArray(config.groupOrder) ? config.groupOrder : ['work', 'page'];
@@ -225,14 +225,14 @@ async function attachCommand(host) {
   const onSearchPage = isOnSearchPage();
 
   const panel = (() => {
-    try { return host.querySelector('[data-canopy-command-panel]'); } catch (_) { return null; }
+    try { return host.querySelector('[data-canopy-search-form-panel]'); } catch (_) { return null; }
   })();
   if (!panel) return;
 
   if (!onSearchPage) {
     try {
       const wrapper = host.querySelector('.relative');
-      if (wrapper) wrapper.setAttribute('data-canopy-panel-auto', '1');
+      if (wrapper) wrapper.setAttribute('data-canopy-search-form-auto', '1');
     } catch (_) {}
   }
 
@@ -244,7 +244,7 @@ async function attachCommand(host) {
   if (!list) return;
 
   const input = (() => {
-    try { return host.querySelector('[data-canopy-command-input]'); } catch (_) { return null; }
+    try { return host.querySelector('[data-canopy-search-form-input]'); } catch (_) { return null; }
   })();
   if (!input) return;
 
@@ -345,9 +345,9 @@ async function attachCommand(host) {
   }
 
   host.addEventListener('click', (event) => {
-    const trigger = event.target && event.target.closest && event.target.closest('[data-canopy-command-trigger]');
+    const trigger = event.target && event.target.closest && event.target.closest('[data-canopy-search-form-trigger]');
     if (!trigger) return;
-    const mode = (trigger.dataset && trigger.dataset.canopyCommandTrigger) || '';
+    const mode = (trigger.dataset && trigger.dataset.canopySearchFormTrigger) || '';
     if (mode === 'submit' || mode === 'form') return;
     event.preventDefault();
     openPanel();
@@ -359,12 +359,12 @@ async function attachCommand(host) {
 }
 
 ready(() => {
-  const hosts = Array.from(document.querySelectorAll('[data-canopy-command]'));
+  const hosts = Array.from(document.querySelectorAll('[data-canopy-search-form]'));
   if (!hosts.length) return;
   hosts.forEach((host) => {
-    attachCommand(host).catch((err) => {
+    attachSearchForm(host).catch((err) => {
       try {
-        console.warn('[canopy][command] failed to initialise', err && (err.message || err));
+        console.warn('[canopy][search-form] failed to initialise', err && (err.message || err));
       } catch (_) {}
     });
   });