@canopy-iiif/app 0.8.5 → 0.9.0

package/lib/AGENTS.md

@@ -34,6 +34,11 @@ Current Focus
 - Runtime bundling: review `search/search.js` for esbuild config drift (externals, shims); list required adjustments if UI adds new hydrated components.
 - Cache hygiene: document when `.cache/mdx` vs `.cache/iiif` are pruned and add TODOs if cleanup relies on manual intervention.
 
+### Interstitial hero support
+- Featured manifests come from `canopy.yml → featured`; `lib/components/featured.js` normalizes IDs, resolves slugs from `.cache/iiif/index.json`, and surfaces thumbnails (`heroThumbnail*` when the IIIF build computed representative images).
+- `build/iiif.js` now writes `heroThumbnail`, `heroThumbnailWidth`, and `heroThumbnailHeight` alongside standard thumbnails so the UI hero can display consistent crops.
+- `build/mdx.js` → `ensureHeroRuntime()` bundles `packages/app/lib/components/hero-slider-runtime.js` to `site/scripts/canopy-hero-slider.js`; keep Swiper external and mirror any esbuild option changes in the UI workspace docs.
+
 Risks & Watchpoints
 -------------------
 - Long reruns: if `dev` mode clears `.cache/iiif` too aggressively it slows iteration; capture triggers before modifying cleanup behavior.

package/lib/build/build.js

@@ -19,7 +19,6 @@ const {
 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
@@ -74,7 +73,7 @@ async function build(options = {}) {
     );
   }
   // 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
+  // so SSR interstitials 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 (_) {}
 
@@ -87,7 +86,7 @@ async function build(options = {}) {
     bright: true,
     underscore: true,
   });
-  // FeaturedHero now reads directly from the local IIIF cache; no API file needed
+  // Interstitials read 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");
@@ -135,16 +134,6 @@ async function build(options = {}) {
   });
   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/dev.js

@@ -1050,6 +1050,13 @@ async function dev() {
       }
     };
     attachCssWatcher();
+    const handleUiSassChange = () => {
+      attachCssWatcher();
+      scheduleTailwindRestart(
+        "[tailwind] detected @canopy-iiif/app/ui Sass change — restarting Tailwind",
+        "[tailwind] compile after UI Sass change failed"
+      );
+    };
     if (fs.existsSync(uiStylesDir)) {
       try {
         fs.watch(
@@ -1057,7 +1064,7 @@ async function dev() {
           { persistent: false, recursive: true },
           (evt, fn) => {
             try {
-              if (fn && /\.s[ac]ss$/i.test(String(fn))) attachCssWatcher();
+              if (fn && /\.s[ac]ss$/i.test(String(fn))) handleUiSassChange();
             } catch (_) {}
           }
         );
@@ -1071,7 +1078,7 @@ async function dev() {
               { persistent: false },
               (evt, fn) => {
                 try {
-                  if (fn && /\.s[ac]ss$/i.test(String(fn))) attachCssWatcher();
+                  if (fn && /\.s[ac]ss$/i.test(String(fn))) handleUiSassChange();
                 } catch (_) {}
                 scan(dir);
               }

package/lib/build/iiif.js

@@ -578,7 +578,7 @@ async function saveCachedManifest(manifest, id, parentId) {
 }
 
 // Ensure any configured featured manifests are present in the local cache
-// (and have thumbnails computed) so SSR components like <Hero /> can read them.
+// (and have thumbnails computed) so interstitial heroes can read them.
 async function ensureFeaturedInCache(cfg) {
   try {
     const CONFIG = cfg || (await loadConfig());
@@ -1144,9 +1144,10 @@ async function buildIiifCollectionPages(CONFIG) {
                   React.createElement(app.Head)
                 )
               : "";
-          const needsHydrateViewer = body.includes("data-canopy-viewer");
+          const needsHydrateViewer =
+            body.includes("data-canopy-viewer") || body.includes("data-canopy-scroll");
           const needsRelated = body.includes("data-canopy-related-items");
-          const needsHero = body.includes("data-canopy-hero");
+          const needsHeroSlider = body.includes("data-canopy-hero-slider");
           const needsSearchForm = body.includes("data-canopy-search-form");
           const needsHydrate =
             body.includes("data-canopy-hydrate") ||
@@ -1172,11 +1173,11 @@ async function buildIiifCollectionPages(CONFIG) {
                 .split(path.sep)
                 .join("/")
             : null;
-          const heroRel = needsHero
+          const heroRel = needsHeroSlider
             ? path
                 .relative(
                   path.dirname(outPath),
-                  path.join(OUT_DIR, "scripts", "canopy-hero.js")
+                  path.join(OUT_DIR, "scripts", "canopy-hero-slider.js")
                 )
                 .split(path.sep)
                 .join("/")
@@ -1201,15 +1202,14 @@ async function buildIiifCollectionPages(CONFIG) {
             : null;
 
           let jsRel = null;
-          if (needsHero && heroRel) jsRel = heroRel;
+          if (needsHeroSlider && heroRel) jsRel = heroRel;
           else if (needsRelated && sliderRel) jsRel = sliderRel;
           else if (viewerRel) jsRel = viewerRel;
 
           let headExtra = head;
           const needsReact = !!(
             needsHydrateViewer ||
-            needsRelated ||
-            needsHero
+            needsRelated
           );
           let vendorTag = "";
           if (needsReact) {

package/lib/build/mdx.js

@@ -113,7 +113,7 @@ async function loadUiComponents() {
     }
     let comp = (mod && typeof mod === 'object') ? mod : {};
     // Hard-require core exports; do not inject fallbacks
-    const required = ['SearchPanel', 'SearchFormModal', 'SearchResults', 'SearchSummary', 'SearchTabs', 'Viewer', 'Slider', 'RelatedItems', 'Hero', 'FeaturedHero'];
+    const required = ['SearchPanel', 'SearchFormModal', 'SearchResults', 'SearchSummary', 'SearchTabs', 'Viewer', 'Slider', 'RelatedItems', 'Interstitials'];
     const missing = required.filter((k) => !comp || !comp[k]);
     if (missing.length) {
       throw new Error('[canopy][mdx] Missing UI exports: ' + missing.join(', '));
@@ -358,6 +358,7 @@ async function ensureClientRuntime() {
   const outFile = path.join(scriptsDir, "canopy-viewer.js");
   const entry = `
     import CloverViewer from '@samvera/clover-iiif/viewer';
+    import CloverScroll from '@samvera/clover-iiif/scroll';
 
     function ready(fn) {
       if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', fn, { once: true });
@@ -373,22 +374,29 @@ async function ensureClientRuntime() {
       } catch (_) { return {}; }
     }
 
-    ready(function() {
+    function mountAll(selector, Component) {
       try {
-        const nodes = document.querySelectorAll('[data-canopy-viewer]');
-        if (!nodes || !nodes.length) return;
+        const nodes = document.querySelectorAll(selector);
+        if (!nodes || !nodes.length || !Component) return;
+        const React = (window && window.React) || null;
+        const ReactDOMClient = (window && window.ReactDOMClient) || null;
+        const createRoot = ReactDOMClient && ReactDOMClient.createRoot;
+        if (!React || !createRoot) return;
         for (const el of nodes) {
           try {
+            if (el.__canopyHydrated) continue;
             const props = parseProps(el);
-            const React = (window && window.React) || null;
-            const ReactDOMClient = (window && window.ReactDOMClient) || null;
-            const createRoot = ReactDOMClient && ReactDOMClient.createRoot;
-            if (!React || !createRoot) continue;
             const root = createRoot(el);
-            root.render(React.createElement(CloverViewer, props));
+            root.render(React.createElement(Component, props));
+            el.__canopyHydrated = true;
           } catch (_) { /* skip */ }
         }
       } catch (_) { /* no-op */ }
+    }
+
+    ready(function() {
+      mountAll('[data-canopy-viewer]', CloverViewer);
+      mountAll('[data-canopy-scroll]', CloverScroll);
     });
   `;
   const reactShim = `
@@ -764,67 +772,21 @@ 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) throw new Error('Hero runtime bundling requires esbuild. Install dependencies before building.');
-  const { path } = require("../common");
+  try {
+    esbuild = require("../ui/node_modules/esbuild");
+  } catch (_) {
+    try { esbuild = require("esbuild"); } catch (_) {}
+  }
+  if (!esbuild) throw new Error('Hero slider runtime bundling requires esbuild. Install dependencies before building.');
   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' }));
-    }
-  };
+  const outFile = path.join(scriptsDir, 'canopy-hero-slider.js');
+  const entryFile = path.join(__dirname, '..', 'components', 'hero-slider-runtime.js');
   await esbuild.build({
-    stdin: { contents: entry, resolveDir: process.cwd(), sourcefile: 'canopy-hero-entry.js', loader: 'js' },
+    entryPoints: [entryFile],
     outfile: outFile,
     platform: 'browser',
     format: 'iife',
@@ -833,8 +795,18 @@ async function ensureHeroRuntime() {
     target: ['es2018'],
     logLevel: 'silent',
     minify: true,
-    plugins: [plugin],
   });
+  try {
+    const { logLine } = require('./log');
+    let size = 0;
+    try {
+      const st = fs.statSync(outFile);
+      size = (st && st.size) || 0;
+    } catch (_) {}
+    const kb = size ? ` (${(size / 1024).toFixed(1)} KB)` : '';
+    const rel = path.relative(process.cwd(), outFile).split(path.sep).join('/');
+    logLine(`✓ Wrote ${rel}${kb}`, 'cyan');
+  } catch (_) {}
 }
 
 module.exports = {

package/lib/build/pages.js

@@ -59,8 +59,10 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
     mergedProps.navigation = navData;
   }
   const { body, head } = await mdx.compileMdxFile(filePath, outPath, null, mergedProps);
-  const needsHydrateViewer = body.includes('data-canopy-viewer');
+  const needsHydrateViewer =
+    body.includes('data-canopy-viewer') || body.includes('data-canopy-scroll');
   const needsHydrateSlider = body.includes('data-canopy-slider');
+  const needsHeroSlider = body.includes('data-canopy-hero-slider');
   const needsSearchForm = true; // search form runtime is global
   const needsFacets = body.includes('data-canopy-related-items');
   const viewerRel = needsHydrateViewer
@@ -69,6 +71,9 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   const sliderRel = (needsHydrateSlider || needsFacets)
     ? path.relative(path.dirname(outPath), path.join(OUT_DIR, 'scripts', 'canopy-slider.js')).split(path.sep).join('/')
     : null;
+  const heroRel = needsHeroSlider
+    ? path.relative(path.dirname(outPath), path.join(OUT_DIR, 'scripts', 'canopy-hero-slider.js')).split(path.sep).join('/')
+    : null;
   const facetsRel = needsFacets
     ? path.relative(path.dirname(outPath), path.join(OUT_DIR, 'scripts', 'canopy-related-items.js')).split(path.sep).join('/')
     : null;
@@ -80,7 +85,8 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
     searchFormRel = rel;
   }
   let jsRel = null;
-  if (needsFacets && sliderRel) jsRel = sliderRel;
+  if (needsHeroSlider && heroRel) jsRel = heroRel;
+  else if (needsFacets && sliderRel) jsRel = sliderRel;
   else if (viewerRel) jsRel = viewerRel;
   else if (sliderRel) jsRel = sliderRel;
   else if (facetsRel) jsRel = facetsRel;
@@ -101,6 +107,7 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   } catch (_) {}
   let headExtra = head;
   const extraScripts = [];
+  if (heroRel && jsRel !== heroRel) extraScripts.push(`<script defer src="${heroRel}"></script>`);
   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>`);

package/lib/build/runtimes.js

@@ -5,11 +5,7 @@ async function prepareAllRuntimes() {
   const mdx = require('./mdx');
   try { await mdx.ensureClientRuntime(); } catch (_) {}
   try { if (typeof mdx.ensureSliderRuntime === 'function') await mdx.ensureSliderRuntime(); } catch (_) {}
-  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.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 (_) {}
   await prepareSearchFormRuntime();

package/lib/components/hero-slider-runtime.js

@@ -0,0 +1,78 @@
+import Swiper from 'swiper';
+import { Navigation, Pagination, Autoplay } from 'swiper/modules';
+import 'swiper/css';
+import 'swiper/css/navigation';
+import 'swiper/css/pagination';
+
+function ready(fn) {
+  if (typeof document === 'undefined') return;
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', fn, { once: true });
+  } else {
+    fn();
+  }
+}
+
+function initSlider(host) {
+  if (!host || host.__canopyHeroBound) return;
+  const slider = host.querySelector('.canopy-interstitial__slider');
+  if (!slider) return;
+  const prev = host.querySelector('.canopy-interstitial__nav-btn--prev');
+  const next = host.querySelector('.canopy-interstitial__nav-btn--next');
+  const pagination = host.querySelector('.canopy-interstitial__pagination');
+
+  try {
+    const swiperInstance = new Swiper(slider, {
+      modules: [Navigation, Pagination, Autoplay],
+      loop: true,
+      slidesPerView: 1,
+      navigation: {
+        prevEl: prev || undefined,
+        nextEl: next || undefined,
+      },
+      pagination: {
+        el: pagination || undefined,
+        clickable: true,
+      },
+      autoplay: {
+        delay: 6000,
+        disableOnInteraction: false,
+      },
+    });
+    host.__canopyHeroBound = true;
+    host.__canopyHeroSwiper = swiperInstance;
+  } catch (error) {
+    try {
+      console.warn('[canopy][hero] failed to initialise slider', error);
+    } catch (_) {}
+  }
+}
+
+function observeHosts() {
+  try {
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        mutation.addedNodes &&
+          mutation.addedNodes.forEach((node) => {
+            if (!(node instanceof Element)) return;
+            if (node.matches && node.matches('[data-canopy-hero-slider]')) initSlider(node);
+            const inner = node.querySelectorAll
+              ? node.querySelectorAll('[data-canopy-hero-slider]')
+              : [];
+            inner && inner.forEach && inner.forEach((el) => initSlider(el));
+          });
+      });
+    });
+    observer.observe(document.documentElement || document.body, {
+      childList: true,
+      subtree: true,
+    });
+  } catch (_) {}
+}
+
+ready(() => {
+  if (typeof document === 'undefined') return;
+  const hosts = document.querySelectorAll('[data-canopy-hero-slider]');
+  hosts.forEach((host) => initSlider(host));
+  observeHosts();
+});

package/lib/orchestrator.js

@@ -128,26 +128,6 @@ function attachSignalHandlers() {
   process.on('exit', clean);
 }
 
-function verifyBuildOutput(outDir = 'site') {
-  const root = path.resolve(outDir);
-  function walk(dir) {
-    let count = 0;
-    if (!fs.existsSync(dir)) return 0;
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const p = path.join(dir, entry.name);
-      if (entry.isDirectory()) count += walk(p);
-      else if (entry.isFile() && p.toLowerCase().endsWith('.html')) count += 1;
-    }
-    return count;
-  }
-  const pages = walk(root);
-  if (!pages) {
-    throw new Error('CI check failed: no HTML pages generated in "site/".');
-  }
-  log(`CI check: found ${pages} HTML page(s) in ${root}.`);
-}
-
 async function orchestrate(options = {}) {
   const argv = options.argv || process.argv.slice(2);
   const env = options.env || process.env;
@@ -156,12 +136,6 @@ async function orchestrate(options = {}) {
   const mode = getMode(argv, env);
   log(`Mode: ${mode}`);
 
-  const cli = new Set(argv);
-  if (cli.has('--verify')) {
-    verifyBuildOutput(env.CANOPY_OUT_DIR || 'site');
-    return;
-  }
-
   await prepareUi(mode, env);
 
   const api = loadLibraryApi();
@@ -176,9 +150,6 @@ async function orchestrate(options = {}) {
         await api.build();
       }
       log('Build complete');
-      if (env.CANOPY_VERIFY === '1' || env.CANOPY_VERIFY === 'true') {
-        verifyBuildOutput(env.CANOPY_OUT_DIR || 'site');
-      }
     }
   } finally {
     if (uiWatcherChild && !uiWatcherChild.killed) {
@@ -189,7 +160,6 @@ async function orchestrate(options = {}) {
 
 module.exports = {
   orchestrate,
-  verifyBuildOutput,
   _internals: {
     getMode,
     prepareUi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canopy-iiif/app",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "private": false,
   "license": "MIT",
   "author": "Mat Jordan <mat@northwestern.edu>",

package/types/orchestrator.d.ts

@@ -15,4 +15,3 @@ export interface OrchestratorOptions {
 }
 
 export declare function orchestrate(options?: OrchestratorOptions): Promise<void>;
-export declare function verifyBuildOutput(outDir?: string): void;