@hagicode/hagilight-docusaurus 0.14.1-dev.146.1.e98244c → 0.14.1-dev.150.1.68cde77

package/README.md

@@ -60,6 +60,14 @@ Every option is optional. Feature toggles take an object with `enabled`, which d
 | `rss` | `{ enabled: true, includeDocs: true, includeBlog: true }` | Writes `rss.xml` for each locale that has feed items. `includeDocs` and `includeBlog` choose the sources. |
 | `noIndex` | `false` | Stops this plugin from writing `sitemap.xml` and `robots.txt`. |
 
+### Footer avatar
+
+`footer` takes `avatar` and `randomAvatar` next to `enabled`. Both default to `true`. `avatar: false` removes the decorative avatar from the brand block and its request; `randomAvatar: false` keeps the vendored default and ships no pool list and no picker script. The avatar and its pool come from `@hagicode/hagilight-core` (`assets/footer`), and the build emits the AVIF and WebP files as ordinary assets rather than inlining them into every page. A site whose `img-src` policy blocks `https://img-gen.hagicode.com` keeps the default image, and the pool refresh procedure is in the core README.
+
+```js
+hagilightDocusaurus({ footer: { avatar: true, randomAvatar: false } });
+```
+
 ### Analytics defaults
 
 The built-in analytics IDs (`G-EN03FMT2Q4`, 51LA `L6b88a5yK4h2Xnci`, and PostHog `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`) belong to HagiCode. A site that omits `analytics` sends its traffic to HagiCode's properties. Set your own IDs, or disable each provider with `enabled: false`.

package/dist/client/random-image.d.ts

@@ -0,0 +1,2 @@
+/** Picks the footer avatar once per page view, on the first load and after each client-side route change. */
+export declare function onRouteDidUpdate(): void;

package/dist/client/random-image.js

@@ -0,0 +1,5 @@
+import { mountRandomImages } from '@hagicode/hagilight-core/random-image';
+/** Picks the footer avatar once per page view, on the first load and after each client-side route change. */
+export function onRouteDidUpdate() {
+    void mountRandomImages(document);
+}

package/dist/global-data.d.ts

@@ -7,4 +7,6 @@ export interface HagilightGlobalData {
     options: ResolvedHagilightOptions;
     i18n: LoadContext['i18n'];
     buildInfo: BuildInfo;
+    /** The footer avatar's random pool, validated at build time; absent when the random option is off. */
+    footerAvatarPool?: readonly string[];
 }

package/dist/index.js

@@ -1,6 +1,8 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
+import footerAvatarManifest from '@hagicode/hagilight-core/assets/footer/manifest.json' with { type: 'json' };
+import { randomPoolFromManifest } from '@hagicode/hagilight-core/random-image';
 import { fiftyOneLaHeadTags, googleAnalyticsHeadTags, posthogHeadTags } from './analytics.js';
 import { collectFeedItems, feedHeadTags, writeDiscoveryOutputs } from './discovery.js';
 import { PLUGIN_NAME } from './global-data.js';
@@ -28,12 +30,16 @@ function promotoSiteIdHeadTags(options) {
         return [];
     return [{ tagName: 'meta', attributes: { name: 'hagilight-site-id', content: siteId } }];
 }
+/** The footer avatar pair in the core package; matched by path so the rule holds in any install layout. */
+const FOOTER_AVATAR_ASSET = /[\\/]footer[\\/]avatar\.(?:avif|webp)$/u;
 function clientModules(options) {
     const analyticsEnabled = options.googleAnalyticsId !== undefined || options.fiftyOneLaId !== undefined;
+    const footerAvatarPicker = options.footer && options.footerAvatar.randomAvatar;
     return [
         ...(analyticsEnabled ? [packageFile('./client/analytics.js')] : []),
         ...(options.promoto ? [packageFile('./client/promoto.js'), packageFile('../promoto.css')] : []),
         ...(options.footer ? [packageFile('../styles.css')] : []),
+        ...(footerAvatarPicker ? [packageFile('./client/random-image.js')] : []),
     ];
 }
 function createPlugin(context, options) {
@@ -45,6 +51,9 @@ function createPlugin(context, options) {
         options,
         i18n: context.i18n,
         buildInfo: resolveBuildInfo({ root: context.siteDir }),
+        footerAvatarPool: options.footer && options.footerAvatar.randomAvatar
+            ? randomPoolFromManifest(footerAvatarManifest.pool)
+            : undefined,
     };
     const themeEnabled = options.footer || options.seo.enabled;
     const site = {
@@ -64,6 +73,18 @@ function createPlugin(context, options) {
         name: PLUGIN_NAME,
         ...(themeEnabled ? { getThemePath: () => packageFile('./theme') } : {}),
         getClientModules: () => clientModules(options),
+        configureWebpack(config) {
+            // Docusaurus inlines images under 10 000 bytes as data URIs in every page. The footer avatar is a
+            // shared asset, so its two files are emitted as ordinary images instead, once per build.
+            const rules = config.module?.rules ?? [];
+            for (const rule of rules) {
+                const candidate = rule;
+                if (candidate.test instanceof RegExp && candidate.use && candidate.test.test('avatar.webp')) {
+                    candidate.exclude = FOOTER_AVATAR_ASSET;
+                }
+            }
+            rules.push({ test: FOOTER_AVATAR_ASSET, type: 'asset/resource', generator: { filename: 'assets/images/hagilight-footer-[name]-[contenthash:8][ext]' } });
+        },
         contentLoaded({ actions }) {
             actions.setGlobalData(globalData);
         },

package/dist/options.d.ts

@@ -1,4 +1,5 @@
 import type { SiteLinksOptions } from '@hagicode/hagilight-core/links';
+import { type ResolvedFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
 import { type SiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
 export interface FeatureToggle {
     enabled?: boolean;
@@ -36,6 +37,12 @@ export interface MetadataOptions extends FeatureToggle {
     /** Site description. Defaults to `siteConfig.tagline`. */
     description?: string;
 }
+export interface FooterOptions extends FeatureToggle {
+    /** The decorative avatar in the brand block. Defaults to `true`; `false` removes it. */
+    avatar?: boolean;
+    /** Swap the avatar for one random pool entry per page view. Defaults to `true`. */
+    randomAvatar?: boolean;
+}
 export interface HagilightDocusaurusOptions {
     /**
      * Write `.well-known/hagilight.metadata.json` at the end of the build. Defaults to `true`;
@@ -43,7 +50,7 @@ export interface HagilightDocusaurusOptions {
      * `static/.well-known/` is kept. Only the default locale build writes the file.
      */
     metadata?: boolean | MetadataOptions;
-    footer?: FeatureToggle;
+    footer?: FooterOptions;
     links?: SiteLinksOptions;
     analytics?: AnalyticsOptions;
     promoto?: FeatureToggle;
@@ -66,6 +73,7 @@ export interface ResolvedRssOptions {
 }
 export interface ResolvedHagilightOptions {
     footer: boolean;
+    footerAvatar: ResolvedFooterAvatarOptions;
     links: SiteLinksOptions;
     googleAnalyticsId: string | undefined;
     fiftyOneLaId: string | undefined;

package/dist/options.js

@@ -1,3 +1,4 @@
+import { resolveFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
 import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagilight-core/posthog';
 import { isValidSeoImageReference, resolveAbsoluteHttpUrl } from '@hagicode/hagilight-core/seo';
 import { resolveSiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
@@ -25,6 +26,15 @@ function nonEmptyStringOption(value, path) {
         throw invalid(path, 'must be a non-empty string');
     return value;
 }
+function resolveFooterAvatar(value) {
+    if (value === undefined)
+        return resolveFooterAvatarOptions();
+    const group = objectOption(value, 'footer');
+    return resolveFooterAvatarOptions({
+        avatar: booleanOption(group.avatar, 'footer.avatar'),
+        randomAvatar: booleanOption(group.randomAvatar, 'footer.randomAvatar'),
+    });
+}
 function featureEnabled(value, path) {
     if (value === undefined)
         return true;
@@ -89,6 +99,7 @@ export function resolveOptions(input) {
     const analytics = options.analytics === undefined ? {} : objectOption(options.analytics, 'analytics');
     return {
         footer: featureEnabled(options.footer, 'footer'),
+        footerAvatar: resolveFooterAvatar(options.footer),
         links: options.links === undefined ? {} : objectOption(options.links, 'links'),
         googleAnalyticsId: resolveProvider(analytics.googleAnalytics, 'analytics.googleAnalytics', 'measurementId', GOOGLE_ANALYTICS_ID_PATTERN, DEFAULT_GOOGLE_ANALYTICS_ID),
         fiftyOneLaId: resolveProvider(analytics.fiftyOneLa, 'analytics.fiftyOneLa', 'siteId', FIFTY_ONE_LA_ID_PATTERN, DEFAULT_FIFTY_ONE_LA_ID),

package/dist/theme/Footer/FooterView.d.ts

@@ -1,10 +1,17 @@
 import { type ReactElement } from 'react';
 import { type BuildInfo } from '@hagicode/hagilight-core/build-info';
 import type { FooterLinks } from '../../footer.js';
+/** The decorative avatar: the vendored default pair and, when the random option is on, the baked pool. */
+export interface FooterAvatar {
+    avif: string;
+    webp: string;
+    randomPool?: readonly string[];
+}
 export interface FooterViewProps {
     links: FooterLinks;
     version: string;
     year: number;
     buildInfo?: BuildInfo;
+    avatar?: FooterAvatar;
 }
-export declare function FooterView({ links, version, year, buildInfo }: FooterViewProps): ReactElement;
+export declare function FooterView({ links, version, year, buildInfo, avatar }: FooterViewProps): ReactElement;

package/dist/theme/Footer/FooterView.js

@@ -3,16 +3,18 @@ import { Fragment } from 'react';
 import { siteLinkGaAttributes } from '@hagicode/hagilight-core/analytics-events';
 import { buildInfoItems } from '@hagicode/hagilight-core/build-info';
 import { pickFooterBrandLinks, resolveFooterBrand } from '@hagicode/hagilight-core/footer-brand';
+import { footerAvatarImageAttributes } from '@hagicode/hagilight-core/footer-avatar';
+import { randomPoolAttribute } from '@hagicode/hagilight-core/random-image';
 function LinkSection({ heading, navLabel, links, tagged }) {
     return (_jsxs("section", { children: [_jsx("h2", { children: heading }), _jsx("nav", { "aria-label": navLabel, children: _jsx("ul", { children: links.map((link) => (_jsx("li", { children: _jsx("a", { href: link.href, target: link.target, rel: link.rel, "aria-label": link.ariaLabel, ...(tagged ? siteLinkGaAttributes(link, 'footer') : {}), children: link.label }) }, link.id))) }) })] }));
 }
-function FooterBrand({ locale, links }) {
+function FooterBrand({ locale, links, avatar }) {
     const brand = resolveFooterBrand(locale);
     const { primary, secondary } = pickFooterBrandLinks(links);
-    return (_jsxs("section", { className: "hagilight-brand", lang: brand.locale, "aria-labelledby": "hagilight-brand-title", children: [_jsxs("div", { className: "hagilight-brand__lead", children: [_jsx("h2", { className: "hagilight-brand__headline", id: "hagilight-brand-title", children: brand.headline }), _jsxs("div", { className: "hagilight-brand__body", children: [_jsx("p", { className: "hagilight-brand__summary", children: brand.summary }), (primary || secondary) && (_jsxs("div", { className: "hagilight-brand__actions", children: [primary && (_jsxs("a", { className: "hagilight-brand__primary", href: primary.href, target: primary.target, rel: primary.rel, "aria-label": primary.ariaLabel, ...siteLinkGaAttributes(primary, 'footer_brand'), children: [_jsx("span", { children: primary.label }), _jsx("svg", { className: "hagilight-brand__arrow", viewBox: "0 0 16 16", width: "16", height: "16", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M2.5 8h10M8.5 3.5 13 8l-4.5 4.5", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" }) })] })), secondary && (_jsx("a", { className: "hagilight-brand__secondary", href: secondary.href, target: secondary.target, rel: secondary.rel, "aria-label": secondary.ariaLabel, ...siteLinkGaAttributes(secondary, 'footer_brand'), children: secondary.label }))] }))] })] }), _jsx("dl", { className: "hagilight-brand__pillars", children: brand.pillars.map((pillar, index) => (_jsxs("div", { className: "hagilight-brand__pillar", "data-pillar": pillar.id, style: { '--hagilight-brand-i': index }, children: [_jsx("dt", { children: pillar.label }), _jsx("dd", { children: pillar.description })] }, pillar.id))) })] }));
+    return (_jsxs("section", { className: "hagilight-brand", lang: brand.locale, "aria-labelledby": "hagilight-brand-title", children: [_jsxs("div", { className: "hagilight-brand__lead", children: [_jsxs("div", { className: "hagilight-brand__title", children: [avatar && (_jsxs("picture", { className: "hagilight-brand__avatar", "data-random-pool": avatar.randomPool && randomPoolAttribute(avatar.randomPool), children: [_jsx("source", { type: "image/avif", srcSet: avatar.avif }), _jsx("source", { type: "image/webp", srcSet: avatar.webp }), _jsx("img", { src: avatar.webp, ...footerAvatarImageAttributes() })] })), _jsx("h2", { className: "hagilight-brand__headline", id: "hagilight-brand-title", children: brand.headline })] }), _jsxs("div", { className: "hagilight-brand__body", children: [_jsx("p", { className: "hagilight-brand__summary", children: brand.summary }), (primary || secondary) && (_jsxs("div", { className: "hagilight-brand__actions", children: [primary && (_jsxs("a", { className: "hagilight-brand__primary", href: primary.href, target: primary.target, rel: primary.rel, "aria-label": primary.ariaLabel, ...siteLinkGaAttributes(primary, 'footer_brand'), children: [_jsx("span", { children: primary.label }), _jsx("svg", { className: "hagilight-brand__arrow", viewBox: "0 0 16 16", width: "16", height: "16", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M2.5 8h10M8.5 3.5 13 8l-4.5 4.5", fill: "none", stroke: "currentColor", strokeWidth: "1.75", strokeLinecap: "round", strokeLinejoin: "round" }) })] })), secondary && (_jsx("a", { className: "hagilight-brand__secondary", href: secondary.href, target: secondary.target, rel: secondary.rel, "aria-label": secondary.ariaLabel, ...siteLinkGaAttributes(secondary, 'footer_brand'), children: secondary.label }))] }))] })] }), _jsx("dl", { className: "hagilight-brand__pillars", children: brand.pillars.map((pillar, index) => (_jsxs("div", { className: "hagilight-brand__pillar", "data-pillar": pillar.id, style: { '--hagilight-brand-i': index }, children: [_jsx("dt", { children: pillar.label }), _jsx("dd", { children: pillar.description })] }, pillar.id))) })] }));
 }
-export function FooterView({ links, version, year, buildInfo }) {
+export function FooterView({ links, version, year, buildInfo, avatar }) {
     const { labels } = links;
     const buildItems = buildInfoItems(buildInfo);
-    return (_jsxs("footer", { className: "hagilight-footer", children: [_jsx(FooterBrand, { locale: links.locale, links: links.quick }), _jsxs("div", { className: "hagilight-footer__sections", children: [links.relatedSites.length > 0 && (_jsxs("section", { children: [_jsx("h2", { children: labels.relatedSites }), _jsx("nav", { "aria-label": labels.navigation.relatedSites, children: _jsx("ul", { children: links.relatedSites.map((site) => (_jsx("li", { children: _jsx("a", { href: site.href, target: site.target, rel: site.rel, children: site.name }) }, site.id))) }) })] })), _jsx(LinkSection, { heading: labels.quickLinks, navLabel: labels.navigation.quickLinks, links: links.quick, tagged: true }), _jsx(LinkSection, { heading: labels.community, navLabel: labels.navigation.community, links: links.community, tagged: true })] }), links.filings.length > 0 && (_jsx("nav", { className: "hagilight-footer__filings", "aria-label": labels.navigation.filings, children: links.filings.map((link) => (_jsx("a", { href: link.href, target: link.target, rel: link.rel, "aria-label": link.ariaLabel, children: link.label }, link.id))) })), _jsxs("p", { className: "hagilight-footer__copyright", children: [_jsxs("span", { children: ["\u00A9 ", year, " HagiCode"] }), ' | ', _jsxs("span", { className: "hagilight-footer__attribution", children: ["Powered By hagilight-docusaurus@", version] }), buildItems.map((item) => (_jsxs(Fragment, { children: [' | ', _jsxs("span", { className: "hagilight-footer__build", "data-build-field": item.field, title: item.title, "data-build-commit": item.title, children: [item.label, ": ", item.datetime ? _jsx("time", { dateTime: item.datetime, children: item.text }) : item.text] })] }, item.field)))] })] }));
+    return (_jsxs("footer", { className: "hagilight-footer", children: [_jsx(FooterBrand, { locale: links.locale, links: links.quick, avatar: avatar }), _jsxs("div", { className: "hagilight-footer__sections", children: [links.relatedSites.length > 0 && (_jsxs("section", { children: [_jsx("h2", { children: labels.relatedSites }), _jsx("nav", { "aria-label": labels.navigation.relatedSites, children: _jsx("ul", { children: links.relatedSites.map((site) => (_jsx("li", { children: _jsx("a", { href: site.href, target: site.target, rel: site.rel, children: site.name }) }, site.id))) }) })] })), _jsx(LinkSection, { heading: labels.quickLinks, navLabel: labels.navigation.quickLinks, links: links.quick, tagged: true }), _jsx(LinkSection, { heading: labels.community, navLabel: labels.navigation.community, links: links.community, tagged: true })] }), links.filings.length > 0 && (_jsx("nav", { className: "hagilight-footer__filings", "aria-label": labels.navigation.filings, children: links.filings.map((link) => (_jsx("a", { href: link.href, target: link.target, rel: link.rel, "aria-label": link.ariaLabel, children: link.label }, link.id))) })), _jsxs("p", { className: "hagilight-footer__copyright", children: [_jsxs("span", { children: ["\u00A9 ", year, " HagiCode"] }), ' | ', _jsxs("span", { className: "hagilight-footer__attribution", children: ["Powered By hagilight-docusaurus@", version] }), buildItems.map((item) => (_jsxs(Fragment, { children: [' | ', _jsxs("span", { className: "hagilight-footer__build", "data-build-field": item.field, title: item.title, "data-build-commit": item.title, children: [item.label, ": ", item.datetime ? _jsx("time", { dateTime: item.datetime, children: item.text }) : item.text] })] }, item.field)))] })] }));
 }

package/dist/theme/Footer/index.js

@@ -5,16 +5,21 @@ import { usePluginData } from '@docusaurus/useGlobalData';
 import { resolveFooterLinks } from '../../footer.js';
 import { PLUGIN_NAME } from '../../global-data.js';
 import { FooterView } from './FooterView.js';
+import avatarAvif from '@hagicode/hagilight-core/assets/footer/avatar.avif';
+import avatarWebp from '@hagicode/hagilight-core/assets/footer/avatar.webp';
 export default function Footer() {
     const { i18n, siteConfig } = useDocusaurusContext();
-    const { version, options, buildInfo } = usePluginData(PLUGIN_NAME);
+    const { version, options, buildInfo, footerAvatarPool } = usePluginData(PLUGIN_NAME);
     if (!options.footer)
         return _jsx(FooterDefaults, {});
+    const avatar = options.footerAvatar.avatar
+        ? { avif: avatarAvif, webp: avatarWebp, randomPool: footerAvatarPool }
+        : undefined;
     const links = resolveFooterLinks({
         locale: i18n.currentLocale,
         baseUrl: siteConfig.baseUrl,
         links: options.links,
         rssEnabled: options.rss.enabled,
     });
-    return (_jsx(FooterView, { links: links, version: version, year: new Date().getFullYear(), buildInfo: buildInfo }));
+    return (_jsx(FooterView, { links: links, version: version, year: new Date().getFullYear(), buildInfo: buildInfo, avatar: avatar }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-docusaurus",
-  "version": "0.14.1-dev.146.1.e98244c",
+  "version": "0.14.1-dev.150.1.68cde77",
   "type": "module",
   "description": "Docusaurus plugin for HagiCode site features: footer, analytics, promote card, locales, SEO, sitemap, robots.txt, and RSS",
   "repository": {
@@ -38,7 +38,7 @@
   ],
   "dependencies": {
     "@docusaurus/types": "^3.9.2",
-    "@hagicode/hagilight-core": "0.14.1-dev.146.1.e98244c"
+    "@hagicode/hagilight-core": "0.14.1-dev.150.1.68cde77"
   },
   "peerDependencies": {
     "@docusaurus/core": "^3.9.2",

package/styles.css

@@ -112,6 +112,36 @@
   gap: 1.5rem 3.5rem;
 }
 
+.hagilight-footer .hagilight-brand__title {
+  display: flex;
+  align-items: center;
+  gap: 1.25rem;
+  min-width: 0;
+}
+
+/* The decorative avatar keeps a fixed 64 px box, so a random swap never moves the headline. */
+.hagilight-footer .hagilight-brand__avatar {
+  display: block;
+  flex: none;
+  width: 64px;
+  height: 64px;
+}
+
+.hagilight-footer .hagilight-brand__avatar img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border-radius: 0.5rem;
+  object-fit: cover;
+}
+
+/* Hidden in a brand block narrower than 360 px, where the headline needs the full width. */
+@container hagilight-brand (max-width: 359.98px) {
+  .hagilight-footer .hagilight-brand__avatar {
+    display: none;
+  }
+}
+
 .hagilight-footer .hagilight-brand__headline {
   margin: 0;
   color: var(--_heading);