@glossarist/concept-browser 0.7.106 → 0.7.107

package/README.md

@@ -109,7 +109,65 @@ branding:
 
 If no logo is configured, the Glossarist logo is shown by default. The footer always shows the Glossarist logo ("Powered by Glossarist").
 
-Favicons work the same way — place `favicon.svg`, `favicon.ico`, and `apple-touch-icon*.png` in `public/`. If not provided, the Glossarist favicon is used.
+### Favicons
+
+`branding.favicon` accepts two shapes — a legacy **string** form and an **object** form that lets consumers provide their own canonical favicon set without writing a post-build script.
+
+#### String form (legacy, still supported)
+
+Path to a single source SVG/PNG. The CLI generates the full variant set (favicon.ico, apple-touch-icon-*.png, etc.) from it using the `favicons` package:
+
+```yaml
+branding:
+  favicon: assets/my-brand.svg
+```
+
+#### Object form (recommended for branded deployments)
+
+The object form lets you provide your own canonical favicon set (typically RealFaviconGenerator output) and have the CLI install it without a post-build script.
+
+A canonical favicon set is **multiple files** — typically `favicon.svg`, `favicon.ico`, `favicon-96x96.png`, `apple-touch-icon.png`, `web-app-manifest-192x192.png`, `web-app-manifest-512x512.png`, and `site.webmanifest`. Put all of them in a directory (e.g. `assets/favicons/`) and reference it via `source_dir`:
+
+```
+my-deployment/
+├── site-config.yml
+└── assets/
+    └── favicons/                  ← branding.favicon.source_dir points here
+        ├── favicon.svg
+        ├── favicon.ico
+        ├── favicon-96x96.png
+        ├── apple-touch-icon.png
+        ├── web-app-manifest-192x192.png
+        ├── web-app-manifest-512x512.png
+        └── site.webmanifest       ← optional; CLI regenerates with BASE_PATH
+```
+
+Then in `site-config.yml`:
+
+```yaml
+branding:
+  favicon:
+    base_path: /                              # URL prefix (BASE_PATH-aware; default '/')
+    skip_default_links: true                  # suppress the default <link> block
+    source_dir: assets/favicons               # canonical files (all of them, in one directory)
+    links_html: |-                            # raw HTML emitted verbatim in <head>
+      <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
+      <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+      <link rel="shortcut icon" href="/favicon.ico" />
+      <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
+      <link rel="manifest" href="/site.webmanifest" />
+```
+
+| Field | Type | Effect |
+|---|---|---|
+| `source_dir` | string | Path (relative to cwd) to a directory containing **all** canonical favicon files. The CLI copies every file in this directory into `public/`, overriding any defaults. Also removes the default-generated cruft (`apple-touch-icon-57x57.png`, `favicon-16x16.png`, etc.) so it doesn't linger. |
+| `links_html` | string | Raw HTML (one or more `<link>` tags) emitted verbatim in `<head>`. Use this to declare which of the source_dir files the browser should load, with what `sizes`/`type`. |
+| `skip_default_links` | boolean | When true, the CLI does NOT call the `favicons` package and does NOT emit the default `<link>` tags. Pair with `links_html` and `source_dir` for fully custom branding. |
+| `base_path` | string | URL prefix prepended to every emitted link. Useful for BASE_PATH-scoped deployments (e.g. `/vocab/`). |
+
+The object form exists so consumers with a RealFaviconGenerator favicon set (or any other canonical brand favicon bundle) can install it without a post-build script. Previously this required workarounds like `glossarist/cie-eilv/scripts/install-favicons.mjs` (149 lines) and `glossarist/iala-vocab/scripts/install-favicons.mjs` (175 lines) — both are now unnecessary.
+
+If neither form is set, the Glossarist default favicon is used.
 
 ### About pages
 

package/cli/index.mjs

@@ -88,53 +88,150 @@ Environment:
     fs.mkdirSync(publicDir, { recursive: true });
 
     const branding = config?.branding || {};
-    const faviconSrc =
-      (branding.favicon && resolve(process.cwd(), branding.favicon)) ||
-      (branding.logo?.localPath && resolve(process.cwd(), branding.logo.localPath)) ||
-      resolve(pkgRoot, 'public', 'favicon.svg');
+
+    // Favicon resolution (issue #173).
+    //
+    // `branding.favicon` accepts two shapes:
+    //
+    //   1. String (legacy) — path to a single source SVG/PNG. The `favicons`
+    //      package generates the full variant set from it.
+    //
+    //   2. Object — `{ source_dir?, links_html?, skip_default_links?, base_path? }`.
+    //      - `links_html`: raw HTML (one or more <link> tags) emitted verbatim.
+    //        Skips the `favicons` package entirely; consumer is responsible
+    //        for providing the actual icon files in public/.
+    //      - `source_dir`: directory of canonical favicon files copied as-is
+    //        into public/ (overriding any defaults). Useful when the consumer
+    //        already has a RealFaviconGenerator output set.
+    //      - `skip_default_links`: don't emit the default <link> block at all.
+    //      - `base_path`: URL prefix for the emitted links (BASE_PATH-aware).
+    const faviconCfg = branding.favicon;
+    const faviconCfgIsObject =
+      faviconCfg !== null && typeof faviconCfg === 'object' && !Array.isArray(faviconCfg);
 
     let faviconHtml = '';
-    if (fs.existsSync(faviconSrc)) {
-      console.log(`\n=== FAVICONS ===\n`);
-      const favicons = (await import('favicons')).default;
-      const source = fs.readFileSync(faviconSrc);
-      const response = await favicons(source, {
-        appName: config?.title || 'Glossarist',
-        background: branding.primaryColor || '#2563eb',
-        theme_color: branding.primaryColor || '#2563eb',
-        icons: {
-          android: false,
-          appleIcon: true,
-          appleStartup: false,
-          favicons: true,
-          windows: false,
-          yandex: false,
-        },
-      });
-
-      for (const img of response.images) {
-        fs.writeFileSync(resolve(publicDir, img.name), img.contents);
-      }
-      for (const file of response.files) {
-        fs.writeFileSync(resolve(publicDir, file.name), file.contents);
+    let skipDefaultGeneration = false;
+
+    if (faviconCfgIsObject) {
+      // Object form — honor each declared field.
+      if (faviconCfg.links_html) {
+        faviconHtml = String(faviconCfg.links_html);
+        skipDefaultGeneration = true;
       }
+      if (faviconCfg.source_dir) {
+        const srcDir = resolve(process.cwd(), faviconCfg.source_dir);
+        if (fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory()) {
+          console.log(`\n=== FAVICONS (copy from ${faviconCfg.source_dir}) ===\n`);
+          // When the consumer provides a canonical favicon set, also delete
+          // the default-generated cruft (apple-touch-icon-*.png, etc.) so
+          // it doesn't linger in public/ and pollute the deployment.
+          // Mirrors glossarist/iala-vocab/scripts/install-favicons.mjs.
+          const cruftFiles = [
+            'apple-touch-icon-57x57.png',
+            'apple-touch-icon-60x60.png',
+            'apple-touch-icon-72x72.png',
+            'apple-touch-icon-76x76.png',
+            'apple-touch-icon-114x114.png',
+            'apple-touch-icon-120x120.png',
+            'apple-touch-icon-144x144.png',
+            'apple-touch-icon-152x152.png',
+            'apple-touch-icon-167x167.png',
+            'apple-touch-icon-180x180.png',
+            'apple-touch-icon-1024x1024.png',
+            'apple-touch-icon-precomposed.png',
+            'favicon-16x16.png',
+            'favicon-32x32.png',
+            'favicon-48x48.png',
+            'browserconfig.xml',
+          ];
+          let removed = 0;
+          for (const cruft of cruftFiles) {
+            const cruftPath = resolve(publicDir, cruft);
+            if (fs.existsSync(cruftPath)) {
+              fs.unlinkSync(cruftPath);
+              removed++;
+            }
+          }
+          if (removed > 0) console.log(`  Removed ${removed} default cruft file(s)`);
 
-      if (faviconSrc.endsWith('.svg')) {
-        fs.copyFileSync(faviconSrc, resolve(publicDir, 'favicon.svg'));
+          let copied = 0;
+          for (const entry of fs.readdirSync(srcDir)) {
+            const fromPath = resolve(srcDir, entry);
+            if (fs.statSync(fromPath).isFile()) {
+              fs.copyFileSync(fromPath, resolve(publicDir, entry));
+              copied++;
+            }
+          }
+          console.log(`  Copied ${copied} canonical favicon file(s) from ${faviconCfg.source_dir}`);
+        } else {
+          console.warn(`  Warning: branding.favicon.source_dir not found: ${srcDir}`);
+        }
       }
+      if (faviconCfg.skip_default_links) {
+        skipDefaultGeneration = true;
+      }
+    }
+
+    if (!skipDefaultGeneration) {
+      // Legacy / default path — derive a single source file and let the
+      // `favicons` package generate the full variant set.
+      const faviconSrc =
+        (typeof faviconCfg === 'string' && faviconCfg && resolve(process.cwd(), faviconCfg)) ||
+        (branding.logo?.localPath && resolve(process.cwd(), branding.logo.localPath)) ||
+        resolve(pkgRoot, 'public', 'favicon.svg');
 
-      faviconHtml = response.html.join('\n    ');
-      if (faviconSrc.endsWith('.svg')) {
-        faviconHtml += '\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg">';
+      if (fs.existsSync(faviconSrc)) {
+        console.log(`\n=== FAVICONS ===\n`);
+        const favicons = (await import('favicons')).default;
+        const source = fs.readFileSync(faviconSrc);
+        const response = await favicons(source, {
+          appName: config?.title || 'Glossarist',
+          background: branding.primaryColor || '#2563eb',
+          theme_color: branding.primaryColor || '#2563eb',
+          icons: {
+            android: false,
+            appleIcon: true,
+            appleStartup: false,
+            favicons: true,
+            windows: false,
+            yandex: false,
+          },
+        });
+
+        for (const img of response.images) {
+          fs.writeFileSync(resolve(publicDir, img.name), img.contents);
+        }
+        for (const file of response.files) {
+          fs.writeFileSync(resolve(publicDir, file.name), file.contents);
+        }
+
+        if (faviconSrc.endsWith('.svg')) {
+          fs.copyFileSync(faviconSrc, resolve(publicDir, 'favicon.svg'));
+        }
+
+        // Only use the generated HTML if the consumer didn't supply their own.
+        if (!faviconHtml) {
+          faviconHtml = response.html.join('\n    ');
+          if (faviconSrc.endsWith('.svg')) {
+            faviconHtml += '\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg">';
+          }
+        }
+        console.log(`  Generated ${response.images.length} favicon files`);
       }
-      fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
-      console.log(`  Generated ${response.images.length} favicon files`);
     }
 
     if (faviconHtml) {
-      const basePath = process.env.BASE_PATH?.replace(/\/+$/, '') || '';
+      fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
+      // Apply base_path prefix (issue #173 + BASE_PATH-aware deployments).
+      const basePath =
+        (faviconCfgIsObject && faviconCfg.base_path) ||
+        process.env.BASE_PATH?.replace(/\/+$/, '') ||
+        '';
       if (basePath) {
-        faviconHtml = faviconHtml.replace(/(href|content)="\/([^"]+)"/g, `$1="${basePath}/$2"`);
+        faviconHtml = faviconHtml.replace(
+          /(href|content)="\/([^"]+)"/g,
+          `$1="${basePath}/$2`,
+        );
       }
       process.env.FAVICON_HTML = faviconHtml;
     }

package/cli/index.ts

@@ -66,8 +66,26 @@ interface BrandingFonts {
   weights?: number[];
 }
 
+interface FaviconConfig {
+  /** Path prefix for all favicon URLs. Defaults to '/', set to a sub-path
+   *  when deploying under BASE_PATH != '/'. */
+  base_path?: string;
+  /** Skip emitting the default <link rel="icon"> and <link rel="apple-touch-icon">
+   *  tags. Use when the consumer provides their own RFG-compatible markup via
+   *  `links_html`. Default: false (emit default tags). */
+  skip_default_links?: boolean;
+  /** Raw HTML string (one or more <link> tags) to emit in <head> instead of
+   *  the default favicon block. RealFaviconGenerator output goes here. */
+  links_html?: string;
+  /** Consumer-side directory (relative to cwd) holding canonical favicon files.
+   *  The CLI copies these into public/, overriding defaults. */
+  source_dir?: string;
+}
+
 interface BrandingConfig {
-  favicon?: string;
+  /** Either a string (legacy: path to a source SVG/PNG) or an object form
+   *  with `source_dir`, `links_html`, `skip_default_links`, `base_path`. */
+  favicon?: string | FaviconConfig;
   logo?: { localPath?: string };
   primaryColor?: string;
   fonts?: { header?: BrandingFonts; body?: BrandingFonts };
@@ -99,53 +117,135 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
   fs.mkdirSync(publicDir, { recursive: true });
 
   const branding: BrandingConfig = config?.branding ?? {};
-  const faviconSrc: string =
-    (branding.favicon && resolve(process.cwd(), branding.favicon)) ||
-    (branding.logo?.localPath && resolve(process.cwd(), branding.logo.localPath)) ||
-    resolve(pkgRoot, 'public', 'favicon.svg');
+
+  // Favicon resolution (issue #173, #177).
+  // `branding.favicon` accepts two shapes:
+  //   1. String (legacy) — path to a single source SVG/PNG.
+  //   2. Object — `{ source_dir?, links_html?, skip_default_links?, base_path? }`.
+  const faviconCfg: string | FaviconConfig | undefined = branding.favicon;
+  const faviconCfgIsObject: boolean =
+    faviconCfg !== null && typeof faviconCfg === 'object' && !Array.isArray(faviconCfg);
+  const faviconCfgObject: FaviconConfig | undefined =
+    faviconCfgIsObject ? (faviconCfg as FaviconConfig) : undefined;
 
   let faviconHtml = '';
-  if (fs.existsSync(faviconSrc)) {
-    console.log(`\n=== FAVICONS ===\n`);
-    const favicons = (await import('favicons')).default;
-    const source: Buffer = fs.readFileSync(faviconSrc);
-    const response: FaviconResponse = await favicons(source, {
-      appName: config?.title || 'Glossarist',
-      background: branding.primaryColor || '#2563eb',
-      theme_color: branding.primaryColor || '#2563eb',
-      icons: {
-        android: false,
-        appleIcon: true,
-        appleStartup: false,
-        favicons: true,
-        windows: false,
-        yandex: false,
-      },
-    });
-
-    for (const img of response.images) {
-      fs.writeFileSync(resolve(publicDir, img.name), img.contents);
+  let skipDefaultGeneration = false;
+
+  if (faviconCfgObject) {
+    const cfg: FaviconConfig = faviconCfgObject;
+    if (cfg.links_html) {
+      faviconHtml = String(cfg.links_html);
+      skipDefaultGeneration = true;
     }
-    for (const file of response.files) {
-      fs.writeFileSync(resolve(publicDir, file.name), file.contents);
+    if (cfg.source_dir) {
+      const srcDir: string = resolve(process.cwd(), cfg.source_dir);
+      if (fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory()) {
+        console.log(`\n=== FAVICONS (copy from ${cfg.source_dir}) ===\n`);
+        // When the consumer provides a canonical favicon set, also delete
+        // the default-generated cruft so it doesn't linger in public/.
+        const cruftFiles: readonly string[] = [
+          'apple-touch-icon-57x57.png',
+          'apple-touch-icon-60x60.png',
+          'apple-touch-icon-72x72.png',
+          'apple-touch-icon-76x76.png',
+          'apple-touch-icon-114x114.png',
+          'apple-touch-icon-120x120.png',
+          'apple-touch-icon-144x144.png',
+          'apple-touch-icon-152x152.png',
+          'apple-touch-icon-167x167.png',
+          'apple-touch-icon-180x180.png',
+          'apple-touch-icon-1024x1024.png',
+          'apple-touch-icon-precomposed.png',
+          'favicon-16x16.png',
+          'favicon-32x32.png',
+          'favicon-48x48.png',
+          'browserconfig.xml',
+        ];
+        let removed = 0;
+        for (const cruft of cruftFiles) {
+          const cruftPath: string = resolve(publicDir, cruft);
+          if (fs.existsSync(cruftPath)) {
+            fs.unlinkSync(cruftPath);
+            removed++;
+          }
+        }
+        if (removed > 0) console.log(`  Removed ${removed} default cruft file(s)`);
+
+        let copied = 0;
+        for (const entry of fs.readdirSync(srcDir)) {
+          const fromPath: string = resolve(srcDir, entry);
+          if (fs.statSync(fromPath).isFile()) {
+            fs.copyFileSync(fromPath, resolve(publicDir, entry));
+            copied++;
+          }
+        }
+        console.log(`  Copied ${copied} canonical favicon file(s) from ${cfg.source_dir}`);
+      } else {
+        console.warn(`  Warning: branding.favicon.source_dir not found: ${srcDir}`);
+      }
     }
-
-    if (faviconSrc.endsWith('.svg')) {
-      fs.copyFileSync(faviconSrc, resolve(publicDir, 'favicon.svg'));
+    if (cfg.skip_default_links) {
+      skipDefaultGeneration = true;
     }
+  }
 
-    faviconHtml = response.html.join('\n    ');
-    if (faviconSrc.endsWith('.svg')) {
-      faviconHtml += '\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg">';
+  if (!skipDefaultGeneration) {
+    const faviconSrc: string =
+      (typeof faviconCfg === 'string' && faviconCfg && resolve(process.cwd(), faviconCfg)) ||
+      (branding.logo?.localPath && resolve(process.cwd(), branding.logo.localPath)) ||
+      resolve(pkgRoot, 'public', 'favicon.svg');
+
+    if (fs.existsSync(faviconSrc)) {
+      console.log(`\n=== FAVICONS ===\n`);
+      const favicons = (await import('favicons')).default;
+      const source: Buffer = fs.readFileSync(faviconSrc);
+      const response: FaviconResponse = await favicons(source, {
+        appName: config?.title || 'Glossarist',
+        background: branding.primaryColor || '#2563eb',
+        theme_color: branding.primaryColor || '#2563eb',
+        icons: {
+          android: false,
+          appleIcon: true,
+          appleStartup: false,
+          favicons: true,
+          windows: false,
+          yandex: false,
+        },
+      });
+
+      for (const img of response.images) {
+        fs.writeFileSync(resolve(publicDir, img.name), img.contents);
+      }
+      for (const file of response.files) {
+        fs.writeFileSync(resolve(publicDir, file.name), file.contents);
+      }
+
+      if (faviconSrc.endsWith('.svg')) {
+        fs.copyFileSync(faviconSrc, resolve(publicDir, 'favicon.svg'));
+      }
+
+      // Only use the generated HTML if the consumer didn't supply their own.
+      if (!faviconHtml) {
+        faviconHtml = response.html.join('\n    ');
+        if (faviconSrc.endsWith('.svg')) {
+          faviconHtml += '\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg">';
+        }
+      }
+      console.log(`  Generated ${response.images.length} favicon files`);
     }
-    fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
-    console.log(`  Generated ${response.images.length} favicon files`);
   }
 
   if (faviconHtml) {
-    const basePath: string = process.env.BASE_PATH?.replace(/\/+$/, '') || '';
+    fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
+    const basePath: string =
+      (faviconCfgObject?.base_path) ||
+      process.env.BASE_PATH?.replace(/\/+$/, '') ||
+      '';
     if (basePath) {
-      faviconHtml = faviconHtml.replace(/(href|content)="\/([^"]+)"/g, `$1="${basePath}/$2"`);
+      faviconHtml = faviconHtml.replace(
+        /(href|content)="\/([^"]+)"/g,
+        `$1="${basePath}/$2`,
+      );
     }
     process.env.FAVICON_HTML = faviconHtml;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.106",
+  "version": "0.7.107",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {

package/src/__tests__/cli/favicon-config.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { resolve } from 'path';
+
+/**
+ * Regression test for issue #177 — `branding.favicon` object form crashes
+ * the CLI with ERR_INVALID_ARG_TYPE.
+ *
+ * The 0.7.106 fix for #173 shipped `branding.favicon` as an object
+ * (`{ source_dir, links_html, skip_default_links, base_path }`) in the
+ * TypeScript types and in `src/layouts/Default.astro`, but `cli/index.mjs`
+ * still called `resolve(process.cwd(), branding.favicon)` — which throws
+ * `ERR_INVALID_ARG_TYPE` when `branding.favicon` is an object.
+ *
+ * Importing `cli/index.mjs` directly runs the full build pipeline, which
+ * is too heavy for a unit test. Instead, this spec pins the type-narrowing
+ * contract that the CLI's favicon resolution MUST honor: a string is a
+ * path, an object is a config, and the two must never be conflated. The
+ * integration smoke test (scripts/smoke.mjs) covers the end-to-end path.
+ */
+
+describe('CLI favicon config (issue #177)', () => {
+  it('resolve() throws ERR_INVALID_ARG_TYPE when branding.favicon is an object — proves the bug class', async () => {
+    // This is the bug: the legacy code did `resolve(cwd, branding.favicon)`
+    // unconditionally. When branding.favicon is an object, Node throws.
+    const faviconCfg = { skip_default_links: true, links_html: '<link>' };
+    expect(() => resolve(process.cwd(), faviconCfg as any)).toThrow(/paths\[1\].*string|ERR_INVALID_ARG_TYPE/);
+  });
+
+  it('typeof-string guard prevents the crash', () => {
+    const faviconCfg = { skip_default_links: true, links_html: '<link>' };
+    const safeResolve = () =>
+      typeof faviconCfg === 'string' && faviconCfg
+        ? resolve(process.cwd(), faviconCfg)
+        : null;
+    expect(safeResolve).not.toThrow();
+    expect(safeResolve()).toBe(null);
+  });
+
+  it('accepts string form (legacy) — single source path', () => {
+    const faviconCfg = 'assets/my-brand.svg';
+    const resolved =
+      typeof faviconCfg === 'string' && faviconCfg
+        ? resolve(process.cwd(), faviconCfg)
+        : null;
+    expect(resolved).toBe(resolve(process.cwd(), 'assets/my-brand.svg'));
+  });
+
+  it('accepts object form — no path resolution attempted on the object itself', () => {
+    const faviconCfg = {
+      source_dir: 'assets/favicons',
+      links_html: '<link rel="icon" href="/favicon.svg" />',
+      skip_default_links: true,
+      base_path: '/',
+    };
+    expect(typeof faviconCfg).toBe('object');
+    // The object form must be inspected for fields, not passed to resolve().
+    expect((faviconCfg as any).source_dir).toBe('assets/favicons');
+    expect((faviconCfg as any).links_html).toContain('<link');
+    expect((faviconCfg as any).skip_default_links).toBe(true);
+  });
+});