@glossarist/concept-browser 0.7.108 → 0.7.110

package/README.md

@@ -235,22 +235,33 @@ Then in `site-config.yml`:
 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" />
+    icons:                                    # DATA — declare each icon, not HTML
+      - rel: icon
+        type: image/svg+xml
+        href: favicon.svg
+      - rel: icon
+        type: image/png
+        sizes: 96x96
+        href: favicon-96x96.png
+      - rel: shortcut icon
+        href: favicon.ico
+      - rel: apple-touch-icon
+        sizes: 180x180
+        href: apple-touch-icon.png
+      - rel: manifest
+        href: site.webmanifest
 ```
 
+The CLI copies every file from `source_dir/` into `public/` (also removing the default cruft), then renders one `<link>` tag per icon entry. The `href` is a **filename** — the system applies the correct `base_path` prefix automatically. Absolute URLs (`https://cdn.example.com/x.png`) and root-relative paths (`/x.png`) are emitted unchanged.
+
 | 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. |
+| `icons` | `FaviconIcon[]` | **DATA — recommended.** Array of `{ rel, href, type?, sizes? }` entries. Each renders to one `<link>` tag with BASE_PATH-aware href. Replaces the default 16-link set. |
+| `skip_default_links` | boolean | When true, the CLI does NOT call the `favicons` package and does NOT emit the default `<link>` tags. Pair with `icons` 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/`). |
+| ~~`links_html`~~ | string | **@deprecated** — use `icons` instead. Raw HTML emitted verbatim. Impossible to validate or safely BASE_PATH-rewrite; kept for backward compat with a console warning. |
 
 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.
 

package/cli/index.mjs

@@ -97,9 +97,12 @@ Environment:
     //      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/.
+    //      - `icons`: DATA — array of { rel, href, type?, sizes? } entries.
+    //        The hrefs are filenames; the CLI applies BASE_PATH and renders
+    //        well-formed <link> tags. Recommended over `links_html`.
+    //      - `links_html` (deprecated): raw HTML emitted verbatim.
+    //        Skips the `favicons` package entirely; impossible to validate
+    //        or safely BASE_PATH-rewrite. Use `icons` instead.
     //      - `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.
@@ -109,19 +112,57 @@ Environment:
     const faviconCfgIsObject =
       faviconCfg !== null && typeof faviconCfg === 'object' && !Array.isArray(faviconCfg);
 
+    // Defensive field access: loadSiteConfig normalizes snake_case YAML keys
+    // to camelCase at load time, so `source_dir` arrives as `sourceDir`. But
+    // the canonical FaviconConfig schema documents snake_case (matching the
+    // YAML wire format), and Astro's getSiteConfig path does NOT normalize.
+    // Accept both forms so a future change to either loader can't break this.
+    // See src/utils/favicon-config-access.ts for the SSOT + tests.
+    const cfgBasePath       = faviconCfgIsObject ? (faviconCfg.basePath ?? faviconCfg.base_path) : undefined;
+    const cfgSkipDefault    = faviconCfgIsObject ? (faviconCfg.skipDefaultLinks ?? faviconCfg.skip_default_links) === true : false;
+    const cfgLinksHtml      = faviconCfgIsObject ? (faviconCfg.linksHtml ?? faviconCfg.links_html) : undefined;
+    const cfgSourceDir      = faviconCfgIsObject ? (faviconCfg.sourceDir ?? faviconCfg.source_dir) : undefined;
+    const cfgIcons          = faviconCfgIsObject ? faviconCfg.icons : undefined;
+
     let faviconHtml = '';
     let skipDefaultGeneration = false;
 
     if (faviconCfgIsObject) {
       // Object form — honor each declared field.
-      if (faviconCfg.links_html) {
-        faviconHtml = String(faviconCfg.links_html);
+      if (cfgIcons && Array.isArray(cfgIcons) && cfgIcons.length > 0) {
+        // Data-driven: build <link> tags from the icons array.
+        const basePathForIcons =
+          cfgBasePath ||
+          process.env.BASE_PATH?.replace(/\/+$/, '') ||
+          '';
+        faviconHtml = cfgIcons.map((icon) => {
+          const attrs = [`rel="${icon.rel || 'icon'}"`];
+          if (icon.type) attrs.push(`type="${icon.type}"`);
+          if (icon.sizes) attrs.push(`sizes="${icon.sizes}"`);
+          // Bare filenames get BASE_PATH-prefixed; absolute URLs / root-relative
+          // paths are emitted as-is.
+          let href = icon.href || '';
+          if (href && !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('//') && !href.startsWith('/')) {
+            href = basePathForIcons ? `${basePathForIcons}/${href}` : `/${href}`;
+          }
+          attrs.push(`href="${href}"`);
+          return `<link ${attrs.join(' ')} />`;
+        }).join('\n    ');
+        skipDefaultGeneration = true;
+      }
+      if (cfgLinksHtml) {
+        if (faviconHtml) {
+          console.warn('  Warning: branding.favicon.icons and links_html are both set; using icons (data form).');
+        } else {
+          console.warn('  Warning: branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead.');
+          faviconHtml = String(cfgLinksHtml);
+        }
         skipDefaultGeneration = true;
       }
-      if (faviconCfg.source_dir) {
-        const srcDir = resolve(process.cwd(), faviconCfg.source_dir);
+      if (cfgSourceDir) {
+        const srcDir = resolve(process.cwd(), cfgSourceDir);
         if (fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory()) {
-          console.log(`\n=== FAVICONS (copy from ${faviconCfg.source_dir}) ===\n`);
+          console.log(`\n=== FAVICONS (copy from ${cfgSourceDir}) ===\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.
@@ -162,12 +203,12 @@ Environment:
               copied++;
             }
           }
-          console.log(`  Copied ${copied} canonical favicon file(s) from ${faviconCfg.source_dir}`);
+          console.log(`  Copied ${copied} canonical favicon file(s) from ${cfgSourceDir}`);
         } else {
           console.warn(`  Warning: branding.favicon.source_dir not found: ${srcDir}`);
         }
       }
-      if (faviconCfg.skip_default_links) {
+      if (cfgSkipDefault) {
         skipDefaultGeneration = true;
       }
     }
@@ -224,7 +265,7 @@ Environment:
       fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
       // Apply base_path prefix (issue #173 + BASE_PATH-aware deployments).
       const basePath =
-        (faviconCfgIsObject && faviconCfg.base_path) ||
+        cfgBasePath ||
         process.env.BASE_PATH?.replace(/\/+$/, '') ||
         '';
       if (basePath) {

package/cli/index.ts

@@ -66,20 +66,29 @@ interface BrandingFonts {
   weights?: number[];
 }
 
+interface FaviconIcon {
+  rel?: string;
+  href: string;
+  type?: string;
+  sizes?: string;
+}
+
 interface FaviconConfig {
-  /** Path prefix for all favicon URLs. Defaults to '/', set to a sub-path
-   *  when deploying under BASE_PATH != '/'. */
+  /** Path prefix for all favicon URLs. Accepts both forms because
+   *  loadSiteConfig normalizes snake_case → camelCase at load time. */
   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). */
+  basePath?: string;
+  /** Skip emitting the default <link> block. */
   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. */
+  skipDefaultLinks?: boolean;
+  /** Consumer-declared icons (DATA, not HTML). */
+  icons?: FaviconIcon[];
+  /** @deprecated Use `icons` instead. */
   links_html?: string;
-  /** Consumer-side directory (relative to cwd) holding canonical favicon files.
-   *  The CLI copies these into public/, overriding defaults. */
+  linksHtml?: string;
+  /** Consumer-side directory of canonical favicon files. */
   source_dir?: string;
+  sourceDir?: string;
 }
 
 interface BrandingConfig {
@@ -133,14 +142,46 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
 
   if (faviconCfgObject) {
     const cfg: FaviconConfig = faviconCfgObject;
-    if (cfg.links_html) {
-      faviconHtml = String(cfg.links_html);
+    // Defensive field access: loadSiteConfig normalizes snake_case → camelCase
+    // at load time. Accept both forms.
+    const cfgBasePath: string | undefined    = cfg.basePath ?? cfg.base_path;
+    const cfgSkipDefault: boolean            = (cfg.skipDefaultLinks ?? cfg.skip_default_links) === true;
+    const cfgLinksHtml: string | undefined   = cfg.linksHtml ?? cfg.links_html;
+    const cfgSourceDir: string | undefined   = cfg.sourceDir ?? cfg.source_dir;
+    const cfgIcons: FaviconIcon[] | undefined = cfg.icons;
+
+    if (cfgIcons && cfgIcons.length > 0) {
+      // Data-driven: build <link> tags from the icons array.
+      const basePathForIcons: string =
+        cfgBasePath ||
+        process.env.BASE_PATH?.replace(/\/+$/, '') ||
+        '';
+      faviconHtml = cfgIcons.map((icon: FaviconIcon): string => {
+        const attrs: string[] = [`rel="${icon.rel || 'icon'}"`];
+        if (icon.type) attrs.push(`type="${icon.type}"`);
+        if (icon.sizes) attrs.push(`sizes="${icon.sizes}"`);
+        let href: string = icon.href || '';
+        if (href && !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('//') && !href.startsWith('/')) {
+          href = basePathForIcons ? `${basePathForIcons}/${href}` : `/${href}`;
+        }
+        attrs.push(`href="${href}"`);
+        return `<link ${attrs.join(' ')} />`;
+      }).join('\n    ');
+      skipDefaultGeneration = true;
+    }
+    if (cfgLinksHtml) {
+      if (faviconHtml) {
+        console.warn('  Warning: branding.favicon.icons and links_html are both set; using icons (data form).');
+      } else {
+        console.warn('  Warning: branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead.');
+        faviconHtml = String(cfgLinksHtml);
+      }
       skipDefaultGeneration = true;
     }
-    if (cfg.source_dir) {
-      const srcDir: string = resolve(process.cwd(), cfg.source_dir);
+    if (cfgSourceDir) {
+      const srcDir: string = resolve(process.cwd(), cfgSourceDir);
       if (fs.existsSync(srcDir) && fs.statSync(srcDir).isDirectory()) {
-        console.log(`\n=== FAVICONS (copy from ${cfg.source_dir}) ===\n`);
+        console.log(`\n=== FAVICONS (copy from ${cfgSourceDir}) ===\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[] = [
@@ -179,12 +220,12 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
             copied++;
           }
         }
-        console.log(`  Copied ${copied} canonical favicon file(s) from ${cfg.source_dir}`);
+        console.log(`  Copied ${copied} canonical favicon file(s) from ${cfgSourceDir}`);
       } else {
         console.warn(`  Warning: branding.favicon.source_dir not found: ${srcDir}`);
       }
     }
-    if (cfg.skip_default_links) {
+    if (cfgSkipDefault) {
       skipDefaultGeneration = true;
     }
   }
@@ -238,7 +279,7 @@ async function runBuildPipeline(config: SiteConfig | null): Promise<void> {
   if (faviconHtml) {
     fs.writeFileSync(resolve(publicDir, 'favicon-links.html'), faviconHtml);
     const basePath: string =
-      (faviconCfgObject?.base_path) ||
+      (faviconCfgObject ? (faviconCfgObject.basePath ?? faviconCfgObject.base_path) : undefined) ||
       process.env.BASE_PATH?.replace(/\/+$/, '') ||
       '';
     if (basePath) {

package/package.json

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

package/src/__tests__/utils/favicon-config-access.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getFaviconBasePath,
+  getFaviconSkipDefaultLinks,
+  getFaviconLinksHtml,
+  getFaviconSourceDir,
+  getFaviconIcons,
+} from '../../utils/favicon-config-access';
+
+/**
+ * Regression test for the snake_case/camelCase mismatch reported against
+ * 0.7.109 (user-filed bug, 2026-08-01):
+ *
+ *   "source_dir reads snake_case — CLI reads faviconCfg.source_dir but
+ *    loadSiteConfig normalizes to sourceDir. Same bug as skip_default_links,
+ *    base_path, links_html. The canonical files never get copied."
+ *
+ * Root cause: two loaders, two conventions.
+ *   - scripts/load-site-config.mjs normalizes snake_case → camelCase.
+ *   - src/lib/site-config.ts (Astro) does NOT normalize.
+ *
+ * Fix: the accessors below accept BOTH forms. They check camelCase first
+ * (the post-normalization form) and fall back to snake_case (the raw YAML
+ * wire form). Either loader's output works.
+ */
+
+describe('getFaviconBasePath', () => {
+  it('returns undefined for null/undefined', () => {
+    expect(getFaviconBasePath(null)).toBeUndefined();
+    expect(getFaviconBasePath(undefined)).toBeUndefined();
+    expect(getFaviconBasePath({})).toBeUndefined();
+  });
+
+  it('reads camelCase basePath', () => {
+    expect(getFaviconBasePath({ basePath: '/vocab/' })).toBe('/vocab/');
+  });
+
+  it('reads snake_case base_path', () => {
+    expect(getFaviconBasePath({ base_path: '/vocab/' })).toBe('/vocab/');
+  });
+
+  it('camelCase wins when both forms are set', () => {
+    expect(getFaviconBasePath({ basePath: '/camel/', base_path: '/snake/' })).toBe('/camel/');
+  });
+});
+
+describe('getFaviconSkipDefaultLinks', () => {
+  it('returns false for null/undefined', () => {
+    expect(getFaviconSkipDefaultLinks(null)).toBe(false);
+    expect(getFaviconSkipDefaultLinks(undefined)).toBe(false);
+    expect(getFaviconSkipDefaultLinks({})).toBe(false);
+  });
+
+  it('reads camelCase skipDefaultLinks', () => {
+    expect(getFaviconSkipDefaultLinks({ skipDefaultLinks: true })).toBe(true);
+    expect(getFaviconSkipDefaultLinks({ skipDefaultLinks: false })).toBe(false);
+  });
+
+  it('reads snake_case skip_default_links', () => {
+    expect(getFaviconSkipDefaultLinks({ skip_default_links: true })).toBe(true);
+  });
+});
+
+describe('getFaviconLinksHtml', () => {
+  it('returns undefined for null/undefined', () => {
+    expect(getFaviconLinksHtml(null)).toBeUndefined();
+    expect(getFaviconLinksHtml({})).toBeUndefined();
+  });
+
+  it('reads camelCase linksHtml', () => {
+    expect(getFaviconLinksHtml({ linksHtml: '<link>' })).toBe('<link>');
+  });
+
+  it('reads snake_case links_html', () => {
+    expect(getFaviconLinksHtml({ links_html: '<link>' })).toBe('<link>');
+  });
+});
+
+describe('getFaviconSourceDir', () => {
+  it('returns undefined for null/undefined', () => {
+    expect(getFaviconSourceDir(null)).toBeUndefined();
+    expect(getFaviconSourceDir({})).toBeUndefined();
+  });
+
+  it('reads camelCase sourceDir', () => {
+    expect(getFaviconSourceDir({ sourceDir: 'assets/favicons' })).toBe('assets/favicons');
+  });
+
+  /**
+   * THE LOAD-BEARING TEST — pins the exact bug the user reported.
+   * "source_dir reads snake_case — CLI reads faviconCfg.source_dir but
+   *  loadSiteConfig normalizes to sourceDir. The canonical files never
+   *  get copied."
+   *
+   * After loadSiteConfig normalization, the config object has sourceDir
+   * (camelCase), NOT source_dir. The accessor must return the value.
+   */
+  it('reads snake_case source_dir (the user-reported regression form)', () => {
+    expect(getFaviconSourceDir({ source_dir: 'assets/favicons' })).toBe('assets/favicons');
+  });
+
+  it('camelCase wins when both forms are set', () => {
+    expect(getFaviconSourceDir({ sourceDir: 'a', source_dir: 'b' })).toBe('a');
+  });
+});
+
+describe('getFaviconIcons', () => {
+  it('returns undefined for null/undefined', () => {
+    expect(getFaviconIcons(null)).toBeUndefined();
+    expect(getFaviconIcons({})).toBeUndefined();
+  });
+
+  it('reads icons (same key in both forms)', () => {
+    const icons = [{ rel: 'icon', href: 'favicon.ico' }];
+    expect(getFaviconIcons({ icons })).toBe(icons);
+  });
+});
+
+describe('regression — both loader outputs work end-to-end', () => {
+  // Simulate the two loader paths:
+  //   - Astro's getSiteConfig (no normalization): snake_case keys preserved
+  //   - CLI's loadSiteConfig (normalizes): camelCase keys
+  const snakeCaseForm = {
+    base_path: '/cie-eilv/',
+    skip_default_links: true,
+    source_dir: 'assets/favicons',
+    links_html: '<link>',
+    icons: [{ rel: 'icon', href: 'favicon.ico' }],
+  };
+  const camelCaseForm = {
+    basePath: '/cie-eilv/',
+    skipDefaultLinks: true,
+    sourceDir: 'assets/favicons',
+    linksHtml: '<link>',
+    icons: [{ rel: 'icon', href: 'favicon.ico' }],
+  };
+
+  for (const [label, cfg] of [['snake_case (Astro)', snakeCaseForm], ['camelCase (CLI)', camelCaseForm]] as const) {
+    it(`accessors return identical values for ${label}`, () => {
+      expect(getFaviconBasePath(cfg)).toBe('/cie-eilv/');
+      expect(getFaviconSkipDefaultLinks(cfg)).toBe(true);
+      expect(getFaviconSourceDir(cfg)).toBe('assets/favicons');
+      expect(getFaviconLinksHtml(cfg)).toBe('<link>');
+      expect(getFaviconIcons(cfg)).toEqual([{ rel: 'icon', href: 'favicon.ico' }]);
+    });
+  }
+});

package/src/__tests__/utils/favicon-links.test.ts

@@ -1,25 +1,23 @@
 import { describe, it, expect } from 'vitest';
-import { buildDefaultFaviconLinks, renderFaviconLinkTag } from '../../utils/favicon-links';
+import { buildFaviconLinks, renderFaviconLinkTag, type FaviconIcon } from '../../utils/favicon-links';
 
 /**
- * Regression test for the sub-path deployment 404 bug.
+ * Regression test for the sub-path deployment 404 bug + the
+ * data-driven icons API.
  *
- * Bug (filed by user, 2026-08-01): deployments at sub-paths
+ * Bug 1 (filed by user, 2026-08-01): deployments at sub-paths
  * (e.g. `/cie-eilv/`) saw console 404s for `favicon-32x32.png`,
  * `favicon-16x16.png`, `favicon-48x48.png` because the emitted
- * `<link href>` pointed at the ROOT (`/favicon-32x32.png`) instead
- * of the deployment sub-path (`/cie-eilv/favicon-32x32.png`).
+ * `<link href>` pointed at the ROOT instead of the deployment sub-path.
  *
- * Root cause: Default.astro hardcoded `const faviconBase = '/'`.
- * Fix: cascade through configuration sources (favicon-base.ts) and
- * emit links with the resolved prefix.
- *
- * This test exercises the full link-emission path: config in →
- * resolved base → link tags with correct hrefs.
+ * Bug 2 (filed by user, 2026-08-01): the `links_html` field required
+ * consumers to inject raw HTML — impossible to validate, can't be safely
+ * BASE_PATH-rewritten. Refactored to DATA: `icons: [{ rel, href, type?,
+ * sizes? }]` — href is a filename, system applies the correct prefix.
  */
-describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
+describe('buildFaviconLinks — BASE_PATH regression', () => {
   it('emits /-prefixed hrefs for root deployment', () => {
-    const links = buildDefaultFaviconLinks({ astroBaseUrl: '/' });
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
     const png16 = links.find(l => l.sizes === '16x16');
     const png32 = links.find(l => l.sizes === '32x32');
     const png48 = links.find(l => l.sizes === '48x48');
@@ -30,13 +28,9 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
 
   /**
    * THE LOAD-BEARING TEST — pins the exact bug the user reported.
-   *
-   * Reproduction: cie-eilv deployment at /cie-eilv/. The 0.7.106/0.7.107
-   * build emitted href="/favicon-32x32.png" — wrong. The fix must emit
-   * href="/cie-eilv/favicon-32x32.png".
    */
   it('emits /cie-eilv/-prefixed hrefs for sub-path deployment', () => {
-    const links = buildDefaultFaviconLinks({
+    const links = buildFaviconLinks({
       siteConfigBasePath: '/cie-eilv/',
       astroBaseUrl: '/',
     });
@@ -49,24 +43,18 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
   });
 
   it('handles deep sub-paths', () => {
-    const links = buildDefaultFaviconLinks({
-      siteConfigBasePath: '/vocab/iala/',
-    });
+    const links = buildFaviconLinks({ siteConfigBasePath: '/vocab/iala/' });
     const icon = links.find(l => l.rel === 'icon' && l.type === 'image/x-icon');
     expect(icon?.href).toBe('/vocab/iala/favicon.ico');
   });
 
   it('handles basePath without trailing slash', () => {
-    const links = buildDefaultFaviconLinks({
-      siteConfigBasePath: '/cie-eilv', // no trailing slash
-    });
+    const links = buildFaviconLinks({ siteConfigBasePath: '/cie-eilv' });
     const icon = links.find(l => l.rel === 'icon' && l.type === 'image/x-icon');
     expect(icon?.href).toBe('/cie-eilv/favicon.ico');
   });
 
   it('never produces a bare "/" href', () => {
-    // Regression guard: a future bug that drops the filename would leave
-    // just the prefix. This test fails loudly if that happens.
     const scenarios = [
       { astroBaseUrl: '/' },
       { astroBaseUrl: '/vocab/' },
@@ -74,7 +62,7 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
       { brandingFaviconBasePath: '/custom/' },
     ];
     for (const input of scenarios) {
-      const links = buildDefaultFaviconLinks(input);
+      const links = buildFaviconLinks(input);
       for (const link of links) {
         expect(link.href, `bare href for input ${JSON.stringify(input)}`).not.toBe('/');
         expect(link.href.length, `empty href for input ${JSON.stringify(input)}`).toBeGreaterThan(1);
@@ -83,14 +71,88 @@ describe('buildDefaultFaviconLinks — BASE_PATH regression', () => {
   });
 
   it('emits the canonical 16 default favicon tags', () => {
-    const links = buildDefaultFaviconLinks({ astroBaseUrl: '/' });
-    // 5 icons (ico + svg + 3 PNG sizes) + 11 apple-touch-icon sizes = 16
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
     expect(links.length).toBe(16);
     expect(links.filter(l => l.rel === 'icon').length).toBe(5);
     expect(links.filter(l => l.rel === 'apple-touch-icon').length).toBe(11);
   });
 });
 
+describe('buildFaviconLinks — consumer-declared icons (data form)', () => {
+  const consumerIcons: FaviconIcon[] = [
+    { rel: 'icon',          type: 'image/svg+xml', href: 'favicon.svg' },
+    { rel: 'icon',          type: 'image/png',     sizes: '96x96', href: 'favicon-96x96.png' },
+    { rel: 'shortcut icon', href: 'favicon.ico' },
+    { rel: 'apple-touch-icon', sizes: '180x180',  href: 'apple-touch-icon.png' },
+    { rel: 'manifest',      href: 'site.webmanifest' },
+  ];
+
+  it('replaces the default set when icons is non-empty', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: consumerIcons });
+    expect(links.length).toBe(consumerIcons.length);
+    // Should NOT contain any of the default 16 links.
+    expect(links.find(l => l.sizes === '16x16')).toBeUndefined();
+    expect(links.find(l => l.sizes === '32x32')).toBeUndefined();
+  });
+
+  it('prefixes bare filenames with the resolved base path', () => {
+    const links = buildFaviconLinks({
+      siteConfigBasePath: '/cie-eilv/',
+      icons: consumerIcons,
+    });
+    const svg = links.find(l => l.type === 'image/svg+xml');
+    const png96 = links.find(l => l.sizes === '96x96');
+    const ico = links.find(l => l.rel === 'shortcut icon');
+    const manifest = links.find(l => l.rel === 'manifest');
+    expect(svg?.href).toBe('/cie-eilv/favicon.svg');
+    expect(png96?.href).toBe('/cie-eilv/favicon-96x96.png');
+    expect(ico?.href).toBe('/cie-eilv/favicon.ico');
+    expect(manifest?.href).toBe('/cie-eilv/site.webmanifest');
+  });
+
+  it('emits absolute URLs as-is (no prefix)', () => {
+    const links = buildFaviconLinks({
+      astroBaseUrl: '/vocab/',
+      icons: [
+        { rel: 'icon', type: 'image/svg+xml', href: 'https://cdn.example.com/favicon.svg' },
+        { rel: 'icon', href: 'favicon.ico' },
+      ],
+    });
+    const cdn = links.find(l => l.href.startsWith('https://'));
+    const local = links.find(l => l.href.endsWith('favicon.ico') && !l.href.startsWith('https://'));
+    expect(cdn?.href).toBe('https://cdn.example.com/favicon.svg');
+    expect(local?.href).toBe('/vocab/favicon.ico');
+  });
+
+  it('emits root-relative paths as-is', () => {
+    const links = buildFaviconLinks({
+      astroBaseUrl: '/vocab/',
+      icons: [{ rel: 'icon', href: '/absolute-path.png' }],
+    });
+    expect(links[0].href).toBe('/absolute-path.png');
+  });
+
+  it('preserves type and sizes attributes from the data', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: consumerIcons });
+    const svg = links.find(l => l.type === 'image/svg+xml');
+    const png96 = links.find(l => l.sizes === '96x96');
+    const touch = links.find(l => l.rel === 'apple-touch-icon');
+    expect(svg?.type).toBe('image/svg+xml');
+    expect(png96?.sizes).toBe('96x96');
+    expect(touch?.sizes).toBe('180x180');
+  });
+
+  it('falls back to default set when icons is empty array', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/', icons: [] });
+    expect(links.length).toBe(16);
+  });
+
+  it('falls back to default set when icons is undefined', () => {
+    const links = buildFaviconLinks({ astroBaseUrl: '/' });
+    expect(links.length).toBe(16);
+  });
+});
+
 describe('renderFaviconLinkTag', () => {
   it('renders all attributes in deterministic order', () => {
     const html = renderFaviconLinkTag({
@@ -112,8 +174,7 @@ describe('renderFaviconLinkTag', () => {
   });
 
   it('never emits an empty href', () => {
-    // Build a complete link tag and verify the href attribute has content.
-    const links = buildDefaultFaviconLinks({ siteConfigBasePath: '/sub-path/' });
+    const links = buildFaviconLinks({ siteConfigBasePath: '/sub-path/' });
     for (const link of links) {
       const html = renderFaviconLinkTag(link);
       const hrefMatch = html.match(/href="([^"]+)"/);

package/src/config/types.ts

@@ -30,16 +30,31 @@ export interface LogoConfig {
   localDark?: string;
 }
 
+export interface FaviconIcon {
+  /** The `rel` attribute: "icon", "shortcut icon", "apple-touch-icon", "manifest". */
+  rel: string;
+  /** Icon file path. Bare filenames ("favicon.ico") get BASE_PATH-prefixed
+   *  automatically; absolute URLs and root-relative paths are emitted as-is. */
+  href: string;
+  /** Optional MIME type hint (e.g., "image/png", "image/svg+xml"). */
+  type?: string;
+  /** Optional sizes attribute (e.g., "180x180", "any"). */
+  sizes?: string;
+}
+
 export interface FaviconConfig {
-  /** Path prefix for all favicon URLs. Defaults to '/', set to a sub-path
-   *  when deploying under BASE_PATH != '/'. */
+  /** Path prefix for all favicon URLs. Defaults to BASE_PATH-aware '/'. */
   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 emitting the default <link> block. Use when the consumer provides
+   *  their own icons via `icons` or wants zero favicon <link> 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. */
+  /** Consumer-declared icons (DATA, not HTML). Replaces the default 16-link
+   *  set when non-empty. Each entry renders to a single <link> tag with
+   *  BASE_PATH-aware href. */
+  icons?: FaviconIcon[];
+  /** @deprecated Use `icons` instead. Raw HTML emitted verbatim — impossible
+   *  to validate, can't be safely BASE_PATH-rewritten. Kept for backward
+   *  compat; emits a console warning when used. */
   links_html?: string;
   /** Consumer-side directory (relative to cwd) holding canonical favicon files.
    *  The CLI's favicon step copies these into public/, overriding defaults. */

package/src/layouts/Default.astro

@@ -9,7 +9,7 @@ import {
   type FontConfigLike,
 } from '../utils/font-stack';
 import { resolveFaviconBase } from '../utils/favicon-base';
-import { buildDefaultFaviconLinks, renderFaviconLinkTag } from '../utils/favicon-links';
+import { buildFaviconLinks, renderFaviconLinkTag } from '../utils/favicon-links';
 
 interface Props {
   title: string;
@@ -52,24 +52,52 @@ const fontHeading = fontStack(headingFont, DEFAULT_CATEGORY.heading) ?? DEFAULT_
 const fontBody = fontStack(brandingFonts?.body, DEFAULT_CATEGORY.body) ?? DEFAULT_FONTS.body;
 const fontMono = fontStack(brandingFonts?.mono, DEFAULT_CATEGORY.mono) ?? DEFAULT_FONTS.mono;
 
-// Favicon configuration (issue #173).
+// Favicon configuration (issues #173, #177, and the data-driven refactor).
 //
-// Consumers provide their own favicon set in one of two ways:
+// Consumers provide their own favicon set in one of these ways:
 //
-//   1. Drop canonical files at `branding.favicon.source_dir` (relative
-//      to the consumer's cwd). The CLI's existing favicon step already
-//      copies these into public/ overriding the defaults — this layout
-//      just needs to emit the right <link> tags.
+//   1. Declare icons as DATA (recommended):
+//        branding:
+//          favicon:
+//            icons:
+//              - rel: icon
+//                type: image/svg+xml
+//                href: favicon.svg
+//              - rel: icon
+//                type: image/png
+//                sizes: 96x96
+//                href: favicon-96x96.png
+//              - rel: shortcut icon
+//                href: favicon.ico
+//              - rel: apple-touch-icon
+//                sizes: 180x180
+//                href: apple-touch-icon.png
+//              - rel: manifest
+//                href: site.webmanifest
+//      The hrefs are filenames (or absolute URLs) — the layout applies
+//      the correct BASE_PATH prefix automatically.
 //
-//   2. Set `branding.favicon.skip_default_links: true` and inject
-//      custom <link> tags via the `branding.favicon.links_html`
-//      string (e.g. RealFaviconGenerator output). The layout emits
-//      that verbatim and skips the default tag block.
+//   2. Drop canonical files at `branding.favicon.source_dir` (relative
+//      to the consumer's cwd). The CLI copies these into public/, and
+//      the layout emits the default 16-link set with BASE_PATH-aware URLs.
 //
-// When neither is set, today's default behavior is preserved.
+//   3. Set `branding.favicon.skip_default_links: true` to emit nothing
+//      (consumer takes full control via their own layout patching).
+//
+// `links_html` is DEPRECATED — raw HTML can't be safely BASE_PATH-rewritten
+// or validated. It still works for backward compat, with a console warning.
 const faviconCfg = siteConfig?.branding?.favicon ?? {};
-const skipDefaultFaviconLinks = faviconCfg.skip_default_links === true;
-const customFaviconLinks: string = faviconCfg.links_html ?? '';
+const faviconCfgIsObject =
+  faviconCfg !== null && typeof faviconCfg === 'object' && !Array.isArray(faviconCfg);
+const skipDefaultFaviconLinks = faviconCfgIsObject && faviconCfg.skip_default_links === true;
+const consumerIcons = faviconCfgIsObject ? (faviconCfg.icons ?? null) : null;
+const deprecatedLinksHtml: string = faviconCfgIsObject ? (faviconCfg.links_html ?? '') : '';
+if (deprecatedLinksHtml) {
+  console.warn(
+    'branding.favicon.links_html is deprecated. Use branding.favicon.icons (data) instead — ' +
+    'see src/utils/favicon-links.ts for the schema. links_html will be removed in a future release.',
+  );
+}
 
 // BASE_PATH-aware favicon URL prefix. Walks the configuration cascade:
 // branding.favicon.base_path → siteConfig.basePath → import.meta.env.BASE_URL → '/'.
@@ -83,17 +111,22 @@ const faviconBaseInput = {
   astroBaseUrl: import.meta.env.BASE_URL,
 };
 const faviconBase = resolveFaviconBase(faviconBaseInput);
-const faviconLinks = buildDefaultFaviconLinks(faviconBaseInput).map(renderFaviconLinkTag);
+// Build the favicon <link> block from data (consumer-declared icons or
+// the default 16-link set). BASE_PATH is applied to every href.
+const faviconLinks = buildFaviconLinks({
+  ...faviconBaseInput,
+  icons: consumerIcons ?? undefined,
+}).map(renderFaviconLinkTag);
 ---
 
 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
-    {!skipDefaultFaviconLinks && (
+    {!skipDefaultFaviconLinks && faviconLinks.length > 0 && (
       <Fragment set:html={faviconLinks.join('\n    ')} />
     )}
-    {customFaviconLinks && <Fragment set:html={customFaviconLinks} />}
+    {deprecatedLinksHtml && <Fragment set:html={deprecatedLinksHtml} />}
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
     <meta name="apple-mobile-web-app-title" content={siteConfig.title} />

package/src/utils/favicon-config-access.ts

@@ -0,0 +1,68 @@
+/**
+ * Defensive favicon config accessor.
+ *
+ * WHY THIS EXISTS
+ *
+ * `loadSiteConfig` (scripts/load-site-config.mjs) normalizes YAML keys
+ * from snake_case to camelCase at load time. So a YAML config with
+ * `branding.favicon.source_dir: assets/favicons` arrives at the CLI as
+ * `cfg.sourceDir`. But the canonical `FaviconConfig` type documents the
+ * snake_case form (matching the YAML wire format), and Astro's
+ * `getSiteConfig` does NOT normalize — so `Default.astro` sees the raw
+ * snake_case form.
+ *
+ * The 0.7.107–0.7.109 CLI used `cfg.source_dir` directly, which silently
+ * returned `undefined` after the loader's normalization. Canonical files
+ * never got copied. Regression caught by user 2026-08-01.
+ *
+ * The fix: this helper reads BOTH forms. Each accessor takes the config
+ * object and returns whichever form is present. The class of "loader
+ * changed normalization, broke the CLI" is now permanently closed.
+ */
+
+export interface RawFaviconConfig {
+  // snake_case (YAML wire format / Astro path)
+  base_path?: string;
+  skip_default_links?: boolean;
+  links_html?: string;
+  source_dir?: string;
+  icons?: unknown;
+  // camelCase (loadSiteConfig normalized form / TS convention)
+  basePath?: string;
+  skipDefaultLinks?: boolean;
+  linksHtml?: string;
+  sourceDir?: string;
+}
+
+function pick<T>(...vals: Array<T | undefined>): T | undefined {
+  for (const v of vals) {
+    if (v !== undefined && v !== null) return v;
+  }
+  return undefined;
+}
+
+export function getFaviconBasePath(cfg: RawFaviconConfig | null | undefined): string | undefined {
+  if (!cfg) return undefined;
+  return pick(cfg.basePath, cfg.base_path);
+}
+
+export function getFaviconSkipDefaultLinks(cfg: RawFaviconConfig | null | undefined): boolean {
+  if (!cfg) return false;
+  return pick(cfg.skipDefaultLinks, cfg.skip_default_links) === true;
+}
+
+export function getFaviconLinksHtml(cfg: RawFaviconConfig | null | undefined): string | undefined {
+  if (!cfg) return undefined;
+  return pick(cfg.linksHtml, cfg.links_html);
+}
+
+export function getFaviconSourceDir(cfg: RawFaviconConfig | null | undefined): string | undefined {
+  if (!cfg) return undefined;
+  return pick(cfg.sourceDir, cfg.source_dir);
+}
+
+export function getFaviconIcons(cfg: RawFaviconConfig | null | undefined): unknown {
+  if (!cfg) return undefined;
+  // `icons` has no snake_case form — same key in both worlds.
+  return cfg.icons;
+}

package/src/utils/favicon-links.ts

@@ -4,16 +4,39 @@
  *
  * Used by:
  *   - `src/layouts/Default.astro` (build-time SSG)
+ *   - `cli/index.mjs`             (consumer-side favicon pipeline)
  *
- * Why this exists: a deployment at `/cie-eilv/` has its favicon files
- * at `/cie-eilv/favicon.ico`, NOT `/favicon.ico`. Hardcoding `/` as
- * the URL prefix (which 0.7.106 did) caused 404s on every sub-path
- * deployment. This builder walks the configuration cascade via
- * `resolveFaviconBase` and emits correctly-prefixed link tags.
+ * Design principle: declare icons as DATA, not HTML. Consumers describe
+ * their favicon set via `branding.favicon.icons: [{ rel, href, type?,
+ * sizes? }]`. The href is a filename (or path relative to the deployment
+ * root); the system applies the correct BASE_PATH prefix and renders
+ * well-formed `<link>` tags. No raw HTML in YAML.
+ *
+ * Why data over HTML: HTML-in-YAML is impossible to validate, can't be
+ * BASE_PATH-rewritten safely (regex on user-supplied markup is brittle),
+ * and forces the consumer to know the exact attribute order/shape the
+ * browser expects. Data lets us validate, normalize, and render.
  */
 
 import { resolveFaviconBase } from './favicon-base';
 
+export interface FaviconIcon {
+  /** The `rel` attribute. Most common: "icon", "shortcut icon",
+   *  "apple-touch-icon", "manifest". */
+  rel: string;
+  /** The icon file path. May be either:
+   *  - A bare filename ("favicon.ico") — gets prefixed with the resolved
+   *    base path automatically.
+   *  - An absolute URL ("https://...") or root-relative path ("/x.png")
+   *    — emitted as-is, no prefixing.
+   */
+  href: string;
+  /** Optional MIME type hint. */
+  type?: string;
+  /** Optional `sizes` attribute (e.g., "180x180", "any"). */
+  sizes?: string;
+}
+
 export interface FaviconLinkTag {
   rel: string;
   type?: string;
@@ -21,8 +44,9 @@ export interface FaviconLinkTag {
   href: string;
 }
 
-/** Default favicon file set emitted by the CLI's `favicons` pipeline. */
-const DEFAULT_FAVICON_FILES: readonly FaviconLinkTag[] = [
+/** Default favicon file set emitted by the CLI's `favicons` pipeline.
+ *  Used when the consumer doesn't declare `branding.favicon.icons`. */
+const DEFAULT_FAVICON_FILES: readonly FaviconIcon[] = [
   { rel: 'icon',       type: 'image/x-icon',  href: 'favicon.ico' },
   { rel: 'icon',       type: 'image/svg+xml', href: 'favicon.svg' },
   { rel: 'icon',       type: 'image/png',     sizes: '16x16',  href: 'favicon-16x16.png' },
@@ -48,22 +72,47 @@ export interface BuildFaviconLinksInput {
   siteConfigBasePath?: string;
   /** Build-time BASE_PATH from Astro/Vite (`import.meta.env.BASE_URL`). */
   astroBaseUrl?: string;
+  /** Consumer-declared icons. When set, replaces the default set. */
+  icons?: readonly FaviconIcon[];
 }
 
 /**
- * Build the list of default favicon link tags with BASE_PATH-aware URLs.
+ * Build the list of favicon link tags with BASE_PATH-aware URLs.
  *
- * Returns the tag descriptors; the caller (Default.astro) renders them
- * into <link> elements.
+ * - If `input.icons` is provided (non-empty), uses that set; otherwise
+ *   falls back to the default 16-link set.
+ * - For each icon, the href is normalized:
+ *   - Filenames ("favicon.ico") → prefixed with the resolved base path.
+ *   - Absolute URLs ("https://...") → emitted as-is.
+ *   - Root-relative paths ("/x.png") → emitted as-is.
  */
-export function buildDefaultFaviconLinks(input: BuildFaviconLinksInput): FaviconLinkTag[] {
+export function buildFaviconLinks(input: BuildFaviconLinksInput): FaviconLinkTag[] {
   const base = resolveFaviconBase(input);
-  return DEFAULT_FAVICON_FILES.map(tag => ({
-    ...tag,
-    href: `${base}${tag.href}`,
+  const icons = input.icons && input.icons.length > 0 ? input.icons : DEFAULT_FAVICON_FILES;
+  return icons.map(icon => ({
+    rel: icon.rel,
+    type: icon.type,
+    sizes: icon.sizes,
+    href: prefixHref(icon.href, base),
   }));
 }
 
+/** Back-compat alias — older name for the same operation. */
+export const buildDefaultFaviconLinks = buildFaviconLinks;
+
+/** Decide whether to prefix the href with the base path.
+ *  Absolute URLs and root-relative paths are emitted as-is; bare filenames
+ *  and relative paths are prefixed. */
+function prefixHref(href: string, base: string): string {
+  if (!href) return base;
+  // Absolute URL: https://, http://, //, data:, etc.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//')) return href;
+  // Root-relative: /anything
+  if (href.startsWith('/')) return href;
+  // Bare filename or relative path: prefix with base.
+  return `${base}${href}`;
+}
+
 /**
  * Render a single FaviconLinkTag to an HTML <link> string.
  *