@canopy-iiif/app 0.7.16 → 0.7.18

package/lib/AGENTS.md

@@ -57,6 +57,8 @@ 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-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`.
 
 Verification Commands
 ---------------------

package/lib/build/dev.js

@@ -2,7 +2,6 @@ const fs = require("fs");
 const fsp = fs.promises;
 const path = require("path");
 const { spawn, spawnSync } = require("child_process");
-const { build } = require("../build/build");
 const http = require("http");
 const url = require("url");
 const {
@@ -21,12 +20,30 @@ function resolveTailwindCli() {
   if (fs.existsSync(bin)) return { cmd: bin, args: [] };
   return { cmd: 'tailwindcss', args: [] };
 }
-const PORT = Number(process.env.PORT || 3000);
+const PORT = Number(process.env.PORT || 5001);
+const BUILD_MODULE_PATH = path.resolve(__dirname, "build.js");
 let onBuildSuccess = () => {};
 let onBuildStart = () => {};
 let onCssChange = () => {};
 let nextBuildSkipIiif = false; // hint set by watchers
 const UI_DIST_DIR = path.resolve(path.join(__dirname, "../../ui/dist"));
+const APP_PACKAGE_ROOT = path.resolve(path.join(__dirname, "..", ".."));
+const APP_LIB_DIR = path.join(APP_PACKAGE_ROOT, "lib");
+const APP_UI_DIR = path.join(APP_PACKAGE_ROOT, "ui");
+const APP_WATCH_TARGETS = [
+  { dir: APP_LIB_DIR, label: "@canopy-iiif/app/lib" },
+  { dir: APP_UI_DIR, label: "@canopy-iiif/app/ui" },
+];
+const HAS_APP_WORKSPACE = (() => {
+  try {
+    return fs.existsSync(path.join(APP_PACKAGE_ROOT, "package.json"));
+  } catch (_) {
+    return false;
+  }
+})();
+let pendingModuleReload = false;
+let building = false;
+let buildAgain = false;
 
 function prettyPath(p) {
   try {
@@ -40,16 +57,71 @@ function prettyPath(p) {
   }
 }
 
+function loadBuildFunction() {
+  let mod = null;
+  try {
+    mod = require(BUILD_MODULE_PATH);
+  } catch (error) {
+    throw new Error(
+      `[watch] Failed to load build module (${BUILD_MODULE_PATH}): ${
+        error && error.message ? error.message : error
+      }`
+    );
+  }
+  const fn =
+    mod && typeof mod.build === "function"
+      ? mod.build
+      : mod && mod.default && typeof mod.default.build === "function"
+      ? mod.default.build
+      : null;
+  if (typeof fn !== "function") {
+    throw new Error("[watch] Invalid build module export: expected build() function");
+  }
+  return fn;
+}
+
+function clearAppModuleCache() {
+  try {
+    const prefix = APP_PACKAGE_ROOT.endsWith(path.sep)
+      ? APP_PACKAGE_ROOT
+      : APP_PACKAGE_ROOT + path.sep;
+    for (const key of Object.keys(require.cache || {})) {
+      if (!key) continue;
+      try {
+        if (key === APP_PACKAGE_ROOT || key.startsWith(prefix)) {
+          delete require.cache[key];
+        }
+      } catch (_) {}
+    }
+  } catch (_) {}
+}
+
 async function runBuild() {
+  if (building) {
+    buildAgain = true;
+    return;
+  }
+  building = true;
+  const hint = { skipIiif: !!nextBuildSkipIiif };
+  nextBuildSkipIiif = false;
   try {
-    const hint = { skipIiif: !!nextBuildSkipIiif };
-    nextBuildSkipIiif = false;
-    await build(hint);
+    if (pendingModuleReload) {
+      clearAppModuleCache();
+      pendingModuleReload = false;
+    }
+    const buildFn = loadBuildFunction();
+    await buildFn(hint);
     try {
       onBuildSuccess();
     } catch (_) {}
   } catch (e) {
     console.error("Build failed:", e && e.message ? e.message : e);
+  } finally {
+    building = false;
+    if (buildAgain) {
+      buildAgain = false;
+      debounceBuild();
+    }
   }
 }
 
@@ -334,6 +406,131 @@ function watchUiDistPerDir() {
   };
 }
 
+const APP_WATCH_EXTENSIONS = new Set([".js", ".jsx", ".scss"]);
+
+function shouldIgnoreAppSourcePath(p) {
+  try {
+    const resolved = path.resolve(p);
+    const rel = path.relative(APP_PACKAGE_ROOT, resolved);
+    if (!rel || rel === "") return false;
+    if (rel.startsWith("..")) return true;
+    const segments = rel.split(path.sep).filter(Boolean);
+    if (!segments.length) return false;
+    if (segments.includes("node_modules")) return true;
+    if (segments.includes(".git")) return true;
+    if (segments[0] === "ui" && segments[1] === "dist") return true;
+    return false;
+  } catch (_) {
+    return true;
+  }
+}
+
+function handleAppSourceChange(baseDir, eventType, filename, label) {
+  if (!filename) return;
+  const full = path.resolve(baseDir, filename);
+  if (shouldIgnoreAppSourcePath(full)) return;
+  const ext = path.extname(full).toLowerCase();
+  if (!APP_WATCH_EXTENSIONS.has(ext)) return;
+  try {
+    const relLib = path.relative(APP_LIB_DIR, full);
+    if (!relLib.startsWith("..") && !path.isAbsolute(relLib)) {
+      pendingModuleReload = true;
+    }
+  } catch (_) {}
+  try {
+    console.log(
+      `[pkg] ${eventType}: ${prettyPath(full)}${label ? ` (${label})` : ""}`
+    );
+  } catch (_) {}
+  nextBuildSkipIiif = true;
+  try {
+    onBuildStart();
+  } catch (_) {}
+  debounceBuild();
+}
+
+function tryRecursiveWatchAppDir(dir, label) {
+  try {
+    return fs.watch(dir, { recursive: true }, (eventType, filename) => {
+      handleAppSourceChange(dir, eventType, filename, label);
+    });
+  } catch (_) {
+    return null;
+  }
+}
+
+function watchAppDirPerDir(dir, label) {
+  const watchers = new Map();
+
+  function watchDir(target) {
+    if (watchers.has(target)) return;
+    if (shouldIgnoreAppSourcePath(target)) return;
+    try {
+      const w = fs.watch(target, (eventType, filename) => {
+        if (filename) {
+          handleAppSourceChange(target, eventType, filename, label);
+        }
+        scan(target);
+      });
+      watchers.set(target, w);
+    } catch (_) {}
+  }
+
+  function scan(target) {
+    let entries;
+    try {
+      entries = fs.readdirSync(target, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const sub = path.join(target, entry.name);
+      if (shouldIgnoreAppSourcePath(sub)) continue;
+      watchDir(sub);
+      scan(sub);
+    }
+  }
+
+  watchDir(dir);
+  scan(dir);
+
+  return () => {
+    for (const w of watchers.values()) {
+      try {
+        w.close();
+      } catch (_) {}
+    }
+  };
+}
+
+function watchAppSources() {
+  if (!HAS_APP_WORKSPACE) return () => {};
+  const stops = [];
+  for (const target of APP_WATCH_TARGETS) {
+    const { dir, label } = target;
+    if (!dir || !fs.existsSync(dir)) continue;
+    console.log(`[Watching] ${prettyPath(dir)} (${label})`);
+    const watcher = tryRecursiveWatchAppDir(dir, label);
+    if (!watcher) {
+      stops.push(watchAppDirPerDir(dir, label));
+    } else {
+      stops.push(() => {
+        try {
+          watcher.close();
+        } catch (_) {}
+      });
+    }
+  }
+  return () => {
+    for (const stop of stops) {
+      try {
+        if (typeof stop === "function") stop();
+      } catch (_) {}
+    }
+  };
+}
+
 const MIME = {
   ".html": "text/html; charset=utf-8",
   ".css": "text/css; charset=utf-8",
@@ -900,6 +1097,9 @@ async function dev() {
     const urw = tryRecursiveWatchUiDist();
     if (!urw) watchUiDistPerDir();
   }
+  if (HAS_APP_WORKSPACE) {
+    watchAppSources();
+  }
 }
 
 module.exports = { dev };

package/lib/build/iiif.js

@@ -828,13 +828,6 @@ async function buildIiifCollectionPages(CONFIG) {
                   React.createElement(app.Head)
                 )
               : "";
-          const cssRel = path
-            .relative(
-              path.dirname(outPath),
-              path.join(OUT_DIR, "styles", "styles.css")
-            )
-            .split(path.sep)
-            .join("/");
           const needsHydrateViewer = body.includes("data-canopy-viewer");
           const needsRelated = body.includes("data-canopy-related-items");
           const needsHero = body.includes("data-canopy-hero");
@@ -942,7 +935,7 @@ async function buildIiifCollectionPages(CONFIG) {
           let html = htmlShell({
             title,
             body: pageBody,
-            cssHref: cssRel || "styles/styles.css",
+            cssHref: null,
             scriptHref: jsRel,
             headExtra: vendorTag + headExtra,
           });

package/lib/build/mdx.js

@@ -139,8 +139,11 @@ async function loadUiComponents() {
 }
 
 function extractTitle(mdxSource) {
-  const { content } = parseFrontmatter(String(mdxSource || ""));
-  const m = content.match(/^\s*#\s+(.+)\s*$/m);
+  const { data, content } = parseFrontmatter(String(mdxSource || ""));
+  if (data && typeof data.title === "string" && data.title.trim()) {
+    return data.title.trim();
+  }
+  const m = content.match(/^\s*#{1,6}\s+(.+?)\s*$/m);
   return m ? m[1].trim() : "Untitled";
 }
 

package/lib/build/pages.js

@@ -45,10 +45,6 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   const source = await fsp.readFile(filePath, 'utf8');
   const title = mdx.extractTitle(source);
   const { body, head } = await mdx.compileMdxFile(filePath, outPath, null, extraProps);
-  const cssRel = path
-    .relative(path.dirname(outPath), path.join(OUT_DIR, 'styles', 'styles.css'))
-    .split(path.sep)
-    .join('/');
   const needsHydrateViewer = body.includes('data-canopy-viewer');
   const needsHydrateSlider = body.includes('data-canopy-slider');
   const needsCommand = true; // command runtime is global
@@ -96,7 +92,7 @@ async function renderContentMdxToHtml(filePath, outPath, extraProps = {}) {
   if (sliderRel && jsRel !== sliderRel) extraScripts.push(`<script defer src="${sliderRel}"></script>`);
   if (commandRel && jsRel !== commandRel) extraScripts.push(`<script defer src="${commandRel}"></script>`);
   if (extraScripts.length) headExtra = extraScripts.join('') + headExtra;
-  const html = htmlShell({ title, body, cssHref: cssRel || 'styles.css', scriptHref: jsRel, headExtra: vendorTag + headExtra });
+  const html = htmlShell({ title, body, cssHref: null, scriptHref: jsRel, headExtra: vendorTag + headExtra });
   const { applyBaseToHtml } = require('../common');
   return applyBaseToHtml(html);
 }

package/lib/build/search.js

@@ -165,10 +165,6 @@ async function writeFacetsSearchApi() {
   await fsp.writeFile(dest, JSON.stringify(data, null, 2), 'utf8');
 }
 
-module.exports = { buildFacetsForWorks, writeFacetCollections, writeFacetsSearchApi };
-
-
-
 async function collectMdxPageRecords() {
   const { fs, fsp, path, CONTENT_DIR, rootRelativeHref } = require('../common');
   const mdx = require('./mdx');
@@ -183,7 +179,8 @@ async function collectMdxPageRecords() {
         const base = path.basename(p).toLowerCase();
         const src = await fsp.readFile(p, 'utf8');
         const fm = mdx.parseFrontmatter(src);
-        const title = mdx.extractTitle(src);
+        const titleRaw = mdx.extractTitle(src);
+        const title = typeof titleRaw === 'string' ? titleRaw.trim() : '';
         const rel = path.relative(CONTENT_DIR, p).replace(/\.mdx$/i, '.html');
         if (base !== 'sitemap.mdx') {
           const href = rootRelativeHref(rel.split(path.sep).join('/'));

package/lib/common.js

@@ -26,13 +26,13 @@ function readYamlConfigBaseUrl() {
 // Priority:
 // 1) CANOPY_BASE_URL env
 // 2) canopy.yml → site.baseUrl
-// 3) dev server default http://localhost:PORT (PORT env or 3000)
+// 3) dev server default http://localhost:PORT (PORT env or 5001)
 const BASE_ORIGIN = (() => {
   const env = String(process.env.CANOPY_BASE_URL || '').trim();
   if (env) return env.replace(/\/$/, '');
   const cfg = readYamlConfigBaseUrl();
   if (cfg) return cfg.replace(/\/$/, '');
-  const port = Number(process.env.PORT || 3000);
+  const port = Number(process.env.PORT || 5001);
   return `http://localhost:${port}`;
 })();
 
@@ -50,7 +50,8 @@ async function cleanDir(dir) {
 function htmlShell({ title, body, cssHref, scriptHref, headExtra }) {
   const scriptTag = scriptHref ? `<script defer src="${scriptHref}"></script>` : '';
   const extra = headExtra ? String(headExtra) : '';
-  return `<!doctype html><html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>${title}</title>${extra}<link rel="stylesheet" href="${cssHref}">${scriptTag}</head><body>${body}</body></html>`;
+  const cssTag = cssHref ? `<link rel="stylesheet" href="${cssHref}">` : '';
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>${title}</title>${extra}${cssTag}${scriptTag}</head><body>${body}</body></html>`;
 }
 
 function withBase(href) {
@@ -114,11 +115,18 @@ function absoluteUrl(p) {
 function applyBaseToHtml(html) {
   if (!BASE_PATH) return html;
   try {
-    let out = String(html || '');
-    // Avoid protocol-relative (//example.com) by using a negative lookahead
-    out = out.replace(/(href|src)=(\")\/(?!\/)/g, `$1=$2${BASE_PATH}/`);
-    out = out.replace(/(href|src)=(\')\/(?!\/)/g, `$1=$2${BASE_PATH}/`);
-    return out;
+    const out = String(html || '');
+    const normalizedBase = BASE_PATH.startsWith('/')
+      ? BASE_PATH.replace(/\/$/, '')
+      : `/${BASE_PATH.replace(/\/$/, '')}`;
+    if (!normalizedBase || normalizedBase === '/') return out;
+    const pattern = /(href|src)=(['"])(\/(?!\/)[^'"\s]*)\2/g;
+    return out.replace(pattern, (match, attr, quote, path) => {
+      if (path === normalizedBase || path.startsWith(`${normalizedBase}/`)) {
+        return match;
+      }
+      return `${attr}=${quote}${normalizedBase}${path}${quote}`;
+    });
   } catch (_) {
     return html;
   }

package/lib/head.js

@@ -0,0 +1,21 @@
+const React = require('react');
+const { withBase, rootRelativeHref } = require('./common');
+
+const DEFAULT_STYLESHEET_PATH = '/styles/styles.css';
+
+function stylesheetHref(href = DEFAULT_STYLESHEET_PATH) {
+  const normalized = rootRelativeHref(href || DEFAULT_STYLESHEET_PATH);
+  return withBase(normalized);
+}
+
+function Stylesheet(props = {}) {
+  const { href = DEFAULT_STYLESHEET_PATH, rel = 'stylesheet', ...rest } = props;
+  const resolved = stylesheetHref(href);
+  return React.createElement('link', { rel, href: resolved, ...rest });
+}
+
+module.exports = {
+  stylesheetHref,
+  Stylesheet,
+  DEFAULT_STYLESHEET_PATH,
+};

package/lib/index.js

@@ -1,4 +1,8 @@
+const { stylesheetHref, Stylesheet } = require('./head');
+
 module.exports = {
   build: require('./build/build').build,
-  dev: require('./build/dev').dev
+  dev: require('./build/dev').dev,
+  stylesheetHref,
+  Stylesheet,
 };

package/lib/orchestrator.js

@@ -0,0 +1,203 @@
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const log = (msg) => console.log(`[canopy] ${msg}`);
+const warn = (msg) => console.warn(`[canopy][warn] ${msg}`);
+const err = (msg) => console.error(`[canopy][error] ${msg}`);
+
+let uiWatcherChild = null;
+
+const workspacePackageJsonPath = path.resolve(process.cwd(), 'packages/app/package.json');
+const hasAppWorkspace = fs.existsSync(workspacePackageJsonPath);
+
+function getMode(argv = process.argv.slice(2), env = process.env) {
+  const cli = new Set(argv);
+  if (cli.has('--dev')) return 'dev';
+  if (cli.has('--build')) return 'build';
+
+  if (env.CANOPY_MODE === 'dev') return 'dev';
+  if (env.CANOPY_MODE === 'build') return 'build';
+
+  const npmScript = env.npm_lifecycle_event;
+  if (npmScript === 'dev') return 'dev';
+  if (npmScript === 'build') return 'build';
+
+  return 'build';
+}
+
+function runOnce(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', shell: false, ...opts });
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+      }
+    });
+  });
+}
+
+function start(cmd, args, opts = {}) {
+  const child = spawn(cmd, args, { stdio: 'inherit', shell: false, ...opts });
+  child.on('error', (error) => {
+    const message = error && error.message ? error.message : String(error);
+    warn(`Subprocess error (${cmd}): ${message}`);
+  });
+  return child;
+}
+
+async function prepareUi(mode, env = process.env) {
+  if (!hasAppWorkspace) {
+    log('Using bundled UI assets from @canopy-iiif/app (workspace not detected)');
+    return null;
+  }
+
+  if (mode === 'build') {
+    log('Building UI assets (@canopy-iiif/app/ui)');
+    try {
+      await runOnce('npm', ['-w', '@canopy-iiif/app', 'run', 'ui:build'], { env });
+      log('UI assets built');
+    } catch (error) {
+      warn(`UI build skipped: ${(error && error.message) || String(error)}`);
+    }
+    return null;
+  }
+
+  try {
+    log('Prebuilding UI assets (@canopy-iiif/app/ui)');
+    await runOnce('npm', ['-w', '@canopy-iiif/app', 'run', 'ui:build'], { env });
+  } catch (error) {
+    warn(`UI prebuild skipped: ${(error && error.message) || String(error)}`);
+  }
+
+  log('Starting UI watcher (@canopy-iiif/app/ui)');
+  try {
+    uiWatcherChild = start('npm', ['-w', '@canopy-iiif/app', 'run', 'ui:watch'], { env });
+  } catch (error) {
+    warn(`UI watch skipped: ${(error && error.message) || String(error)}`);
+    uiWatcherChild = null;
+  }
+  return uiWatcherChild;
+}
+
+function loadLibraryApi() {
+  let lib;
+  try {
+    lib = require('./index.js');
+  } catch (e) {
+    const hint = [
+      'Unable to load @canopy-iiif/app.',
+      'Ensure dependencies are installed (npm install)',
+      "and that peer deps like 'react' are present.",
+    ].join(' ');
+    const detail = e && e.message ? `\nCaused by: ${e.message}` : '';
+    throw new Error(`${hint}${detail}`);
+  }
+
+  const api = lib && (typeof lib.build === 'function' || typeof lib.dev === 'function')
+    ? lib
+    : lib && lib.default
+    ? lib.default
+    : lib;
+
+  if (!api || (typeof api.build !== 'function' && typeof api.dev !== 'function')) {
+    throw new TypeError('Invalid @canopy-iiif/app export: expected functions build() and/or dev().');
+  }
+
+  return api;
+}
+
+function attachSignalHandlers() {
+  const clean = () => {
+    if (uiWatcherChild && !uiWatcherChild.killed) {
+      try { uiWatcherChild.kill(); } catch (_) {}
+    }
+  };
+
+  process.on('SIGINT', () => {
+    clean();
+    process.exit(130);
+  });
+  process.on('SIGTERM', () => {
+    clean();
+    process.exit(143);
+  });
+  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;
+
+  process.title = 'canopy-app';
+  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();
+  try {
+    if (mode === 'dev') {
+      attachSignalHandlers();
+      log('Starting dev server...');
+      await (typeof api.dev === 'function' ? api.dev() : Promise.resolve());
+    } else {
+      log('Building site...');
+      if (typeof api.build === 'function') {
+        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) {
+      try { uiWatcherChild.kill(); } catch (_) {}
+    }
+  }
+}
+
+module.exports = {
+  orchestrate,
+  verifyBuildOutput,
+  _internals: {
+    getMode,
+    prepareUi,
+    loadLibraryApi,
+    runOnce,
+    start,
+  },
+  log,
+  warn,
+  err,
+};

package/lib/search/command-runtime.js

@@ -346,10 +346,11 @@ async function attachCommand(host) {
 
   host.addEventListener('click', (event) => {
     const trigger = event.target && event.target.closest && event.target.closest('[data-canopy-command-trigger]');
-    if (trigger) {
-      event.preventDefault();
-      openPanel();
-    }
+    if (!trigger) return;
+    const mode = (trigger.dataset && trigger.dataset.canopyCommandTrigger) || '';
+    if (mode === 'submit' || mode === 'form') return;
+    event.preventDefault();
+    openPanel();
   });
 
   try {