@hagicode/hagilight-docusaurus 0.0.0-stage → 0.1.0-dev.148.1.e0c630e

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# @hagicode/hagilight-docusaurus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Docusaurus plugin that adds the Hagilight footer, promotion banner, analytics, SEO metadata, and discovery files (`sitemap.xml`, `robots.txt`, `rss.xml`) to a Docusaurus 3 site.
+
+## Install
+
+```bash
+npm install @hagicode/hagilight-docusaurus
+```
+
+Peer dependencies are `@docusaurus/core` and `@docusaurus/theme-classic` `^3.9.2`, and `react` `^18 || ^19`. The demo site uses Docusaurus 3.10.
+
+## Minimal configuration
+
+```js
+// docusaurus.config.mjs
+import { hagilightDocusaurus } from '@hagicode/hagilight-docusaurus';
+import { i18n } from '@hagicode/hagilight-docusaurus/locales';
+
+export default {
+  title: 'My docs',
+  url: 'https://docs.example.com',
+  baseUrl: '/',
+  i18n,
+  plugins: [
+    hagilightDocusaurus({
+      analytics: {
+        googleAnalytics: { measurementId: 'G-XXXXXXXXXX' },
+        fiftyOneLa: { enabled: false },
+      },
+    }),
+  ],
+  themeConfig: {
+    image: 'img/social-card.png',
+    navbar: {
+      items: [{ type: 'localeDropdown' }],
+    },
+  },
+};
+```
+
+Keep `"type": "module"` out of the site's `package.json` and name an ESM config `docusaurus.config.mjs`. Docusaurus's generated registry needs webpack's CommonJS rewrite during SSR, which an ESM-typed package skips, so the production build fails with `require.resolveWeak is not a function`.
+
+## Options
+
+Every option is optional. Feature toggles take an object with `enabled`, which defaults to `true`.
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `footer` | `{ enabled: true }` | Replaces the Docusaurus footer with the Hagilight footer. Uses `links`. |
+| `links` | `{}` | Site link configuration from `@hagicode/hagilight-core`: `overrides`, `extraLinks`, `removeLinks`, `relatedSites`, `rssFeedUrl`, `rssLocaleFeedUrl`, `siteId`, `siteUrl`. |
+| `analytics.googleAnalytics` | built-in ID, enabled | `{ enabled, measurementId }`. Loads gtag in production builds only. |
+| `analytics.posthog` | built-in key, enabled | `{ enabled, apiKey }`. Loads PostHog in the global head in production builds only. |
+| `analytics.fiftyOneLa` | built-in ID, enabled | `{ enabled, siteId }`. Loads 51LA in production builds only. |
+| `promoto` | `{ enabled: true }` | Shows the promotion banner and its styles. |
+| `languageSelector` | `{ enabled: true }` | Controls the locale configuration warnings. It does not render a dropdown. Add `{ type: 'localeDropdown' }` to `themeConfig.navbar.items` for the switcher. |
+| `seo` | `{ enabled: true }` | Emits sharing metadata and Organization and WebSite JSON-LD. Sub-options: `image`, `organization.name`, `organization.url`, `organization.logo`. |
+| `sitemap` | `{ enabled: true }` | Writes a fallback `sitemap.xml` in production builds (see below). |
+| `robots` | `{ enabled: true }` | Writes `robots.txt` in the default-locale build (see below). |
+| `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`.
+
+An analytics object enables its provider when it contains an ID. Set `enabled` explicitly to override that. `enabled: true` with no ID is a configuration error.
+
+PostHog needs no configuration or consumer project key when registering `hagilightDocusaurus()`. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://us.i.posthog.com`, and SDK defaults `2026-05-30`. Its single inline initialization shares the global head with Google Analytics on every production HTML page, including localized docs, blogs and not-found pages. No PostHog loader is emitted outside production.
+
+| PostHog input | Behavior |
+| --- | --- |
+| Plugin options omitted, `analytics: {}`, or `posthog` omitted | Enabled with the supplied default key |
+| `posthog: {}` | Disabled, like an empty Google Analytics provider |
+| `posthog: { apiKey: 'phc_Custom123' }` | Enabled with the custom key |
+| `posthog: { enabled: true, apiKey: 'phc_Custom123' }` | Enabled with the custom key |
+| `posthog: { enabled: true }` | Configuration error: `apiKey` required |
+| `posthog: { enabled: false }` | Disabled independently of Google Analytics and 51LA |
+
+Keys must match `^phc_[A-Za-z0-9]+$`; enabled providers reject missing or malformed keys. Provider options must be objects and `enabled` must be boolean.
+
+```js
+hagilightDocusaurus(); // shared analytics defaults
+hagilightDocusaurus({ analytics: { posthog: { apiKey: 'phc_Custom123' } } });
+hagilightDocusaurus({ analytics: { posthog: { enabled: false } } });
+hagilightDocusaurus({
+  analytics: {
+    googleAnalytics: { enabled: false },
+    fiftyOneLa: { enabled: false },
+    posthog: { enabled: false },
+  },
+}); // all analytics disabled
+```
+
+Each provider is independent: disabling Google Analytics and 51LA alone leaves PostHog enabled. Choose one PostHog initialization owner and opt out here if the site already supplies it. The loader initializes once per document, and the supplied SDK defaults own navigation tracking; Hagilight adds no PostHog capture calls or route listeners. The existing analytics client module remains registered only for Google Analytics and 51LA, preserving their navigation behavior.
+
+### SEO
+
+- `seo.image` is an absolute HTTP(S) URL or a site-root path. When it is unset, `themeConfig.image` is the fallback sharing image.
+- `seo.organization.url` and `seo.organization.logo` must be absolute HTTP(S) URLs.
+- The Organization and WebSite JSON-LD is still emitted when a site replaces `SiteMetadata`.
+
+## Build line
+
+The Hagilight footer shows `Branch:`, `Commit:`, and `Built:` after the attribution. The values are resolved from the site directory: `HAGILIGHT_BUILD_BRANCH` and `HAGILIGHT_BUILD_COMMIT`, then Git, then `unknown`; the core README gives the order. The line belongs to the Hagilight footer, so it is absent when `footer` is disabled. For a detached-HEAD CI checkout, set `HAGILIGHT_BUILD_BRANCH` in the build step as shown in the Astro README.
+
+Docusaurus evaluates the plugin again for each locale it builds, so each locale resolves its own `Built:` time. Pages within one locale share that time, but two locales built in the same run can differ by a few seconds.
+
+## Locale catalog
+
+`@hagicode/hagilight-docusaurus/locales` exports the locale table used by the plugin:
+
+```js
+import { i18n, locales, localeConfigs, defaultLocale } from '@hagicode/hagilight-docusaurus/locales';
+```
+
+- `i18n` is a complete Docusaurus `i18n` config (`defaultLocale`, `locales`, `path: 'i18n'`, `localeConfigs`).
+- `locales` and `localeConfigs` are the pieces `i18n` is built from, for sites that assemble their own `i18n` object.
+
+Catalog locales are `en-US` (default), `zh-CN`, `zh-Hant`, `fr-FR`, `de-DE`, `es-ES`, `ja-JP`, `ko-KR`, `pt-BR`, and `ru-RU`.
+
+## Discovery output
+
+### sitemap.xml
+
+Written in production builds only, into each locale's output directory, when:
+
+- `sitemap` is enabled, and
+- `noIndex` is not set, and
+- the official `docusaurus-plugin-sitemap` is not in the loaded plugins.
+
+The fallback lists every built route except the 404 page, with absolute URLs built from `url` and that locale's base URL. If the official sitemap plugin is loaded, this plugin writes nothing.
+
+### robots.txt
+
+Written only by the default-locale build. It contains `User-agent: *`, `Allow: /`, and one absolute `Sitemap:` line for every configured locale.
+
+- A site-owned `static/robots.txt` takes precedence, and this plugin writes nothing.
+- A build of a non-default locale alone prints a warning when the default-locale build has not written `robots.txt`.
+- Build every locale (run `docusaurus build` without `--locale`) so `robots.txt` lists all sitemaps.
+
+### rss.xml
+
+Written per locale, into that locale's output directory, when feed items exist. Drafts and unlisted entries are excluded.
+
+- A site-owned `static/rss.xml` takes precedence.
+- The `<link rel="alternate">` head tag is added when feed items exist or the site owns `rss.xml`.
+- With no items, the build logs an info message and writes nothing.
+
+### .well-known/hagilight.metadata.json
+
+Written by the default-locale build, as the last discovery step. It lists every configured locale, the discovery files this build wrote, and build facts. The schema is in `@hagicode/hagilight-core`'s README.
+
+- `metadata: false` opts out. `metadata: { name, description }` overrides the site name, which defaults to `title`, and the description, which defaults to `tagline`.
+- Analytics flags are `true` only in production builds that load the provider. Non-production builds report `false`.
+- A build of a non-default locale writes nothing and warns when the default-locale build has not written the file, the same rule as `robots.txt`.
+- A site-owned `static/.well-known/hagilight.metadata.json` takes precedence, and this plugin keeps it untouched.
+- GitHub Pages needs a `.nojekyll` file in the published root, or the `.well-known` directory is dropped.
+
+## Configuration warnings
+
+The plugin prints a `[@hagicode/hagilight-docusaurus]` warning during the build when:
+
+- Several locales are configured but `themeConfig.navbar.items` has no `localeDropdown` item, and `languageSelector` is enabled.
+- A configured locale is not in the Hagilight catalog, so its native label and `lang` value are not checked. Use catalog locales or disable `languageSelector`.
+- `src/theme/Footer` exists in the site while `footer` is enabled. Remove the site component or disable `footer`.
+- `src/theme/SiteMetadata` exists while `seo` is enabled. Remove it or disable `seo`.
+- Neither `themeConfig.image` nor `seo.image` is set while `seo` is enabled.
+- `themeConfig.footer` is set while the Hagilight footer is enabled. Its links are ignored.
+- Google Analytics is configured twice, through `themeConfig.gtag` or the official gtag plugin, and through this plugin.
+
+## Plugin ordering
+
+The sitemap check looks at every loaded plugin, so the position of `hagilightDocusaurus()` in `plugins` does not change the result. The official `docusaurus-plugin-sitemap` must be loaded to be detected.
+
+## Demo
+
+The demo site for this package lives in the monorepo at `examples/demo-docusaurus-web` and is published to https://docusaurus.hagicode.com/.

package/dist/analytics.d.ts

@@ -0,0 +1,8 @@
+import type { HtmlTagObject } from '@docusaurus/types';
+export declare function posthogHeadTags(apiKey: string): HtmlTagObject[];
+export declare const DEFAULT_GOOGLE_ANALYTICS_ID = "G-EN03FMT2Q4";
+export declare const DEFAULT_FIFTY_ONE_LA_ID = "L6b88a5yK4h2Xnci";
+export declare const GOOGLE_ANALYTICS_ID_PATTERN: RegExp;
+export declare const FIFTY_ONE_LA_ID_PATTERN: RegExp;
+export declare function googleAnalyticsHeadTags(measurementId: string): HtmlTagObject[];
+export declare function fiftyOneLaHeadTags(siteId: string): HtmlTagObject[];

package/dist/analytics.js

@@ -0,0 +1,37 @@
+import { posthogInitScript } from '@hagicode/hagilight-core/posthog';
+export function posthogHeadTags(apiKey) {
+    return [{ tagName: 'script', innerHTML: posthogInitScript(apiKey) }];
+}
+export const DEFAULT_GOOGLE_ANALYTICS_ID = 'G-EN03FMT2Q4';
+export const DEFAULT_FIFTY_ONE_LA_ID = 'L6b88a5yK4h2Xnci';
+export const GOOGLE_ANALYTICS_ID_PATTERN = /^G-[A-Z0-9]+$/u;
+export const FIFTY_ONE_LA_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
+export function googleAnalyticsHeadTags(measurementId) {
+    return [
+        {
+            tagName: 'script',
+            attributes: { async: true, src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}` },
+        },
+        {
+            tagName: 'script',
+            innerHTML: [
+                'window.dataLayer = window.dataLayer || [];',
+                'function gtag(){dataLayer.push(arguments);}',
+                "gtag('js', new Date());",
+                `gtag('config', ${JSON.stringify(measurementId)});`,
+            ].join('\n'),
+        },
+    ];
+}
+export function fiftyOneLaHeadTags(siteId) {
+    return [
+        {
+            tagName: 'script',
+            attributes: { charset: 'UTF-8', id: 'LA_COLLECT', src: 'https://sdk.51.la/js-sdk-pro.min.js' },
+        },
+        {
+            tagName: 'script',
+            innerHTML: `LA.init(${JSON.stringify({ id: siteId, ck: siteId, autoTrack: true, hashMode: true, screenRecord: true })});`,
+        },
+    ];
+}

package/dist/client/analytics.d.ts

@@ -0,0 +1,23 @@
+export interface RouteLocation {
+    pathname: string;
+    search: string;
+    hash: string;
+}
+export interface RouteDidUpdate {
+    location: RouteLocation;
+    previousLocation: RouteLocation | null;
+}
+export interface PageSnapshot {
+    title: string;
+    location: string;
+    path: string;
+}
+export interface RouteReportDeps {
+    getGtag: () => unknown;
+    readPage: () => PageSnapshot;
+    schedule: (task: () => void) => void;
+}
+export declare function installClickTracking(target?: Pick<EventTarget, 'addEventListener'>): boolean;
+export declare function reportPageView(gtag: unknown, page: PageSnapshot): boolean;
+export declare function handleRouteDidUpdate(update: RouteDidUpdate, deps: RouteReportDeps): void;
+export declare function onRouteDidUpdate(update: RouteDidUpdate): void;

package/dist/client/analytics.js

@@ -0,0 +1,33 @@
+import { installGaEventTracking } from '@hagicode/hagilight-core/analytics-events';
+export function installClickTracking(target) {
+    return installGaEventTracking(target);
+}
+export function reportPageView(gtag, page) {
+    if (typeof gtag !== 'function')
+        return false;
+    gtag('event', 'page_view', { page_title: page.title, page_location: page.location, page_path: page.path });
+    return true;
+}
+export function handleRouteDidUpdate(update, deps) {
+    if (!update.previousLocation)
+        return;
+    deps.schedule(() => {
+        reportPageView(deps.getGtag(), deps.readPage());
+    });
+}
+const browserDeps = {
+    getGtag: () => globalThis.gtag,
+    readPage: () => ({
+        title: document.title,
+        location: window.location.href,
+        path: `${window.location.pathname}${window.location.search}`,
+    }),
+    schedule: (task) => {
+        window.setTimeout(task, 0);
+    },
+};
+export function onRouteDidUpdate(update) {
+    handleRouteDidUpdate(update, browserDeps);
+}
+if (typeof document !== 'undefined')
+    installClickTracking(document);

package/dist/client/promoto-markup.d.ts

@@ -0,0 +1 @@
+export declare const PROMOTO_SHELL_MARKUP = "\n  <section class=\"hagilight-promoto__shell\" data-promoto-shell hidden aria-label=\"Featured promotion\">\n    <div class=\"hagilight-promoto__viewport\">\n      <div class=\"hagilight-promoto__track\" data-promoto-track></div>\n    </div>\n    <nav class=\"hagilight-promoto__controls\" data-promoto-controls aria-label=\"Promotion controls\" hidden>\n      <button type=\"button\" class=\"hagilight-promoto__control\" data-promoto-previous aria-label=\"Previous promotion\">\n        <svg class=\"hagilight-promoto__icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M15 6l-6 6 6 6\" /></svg>\n      </button>\n      <span class=\"hagilight-promoto__count\" data-promoto-count aria-label=\"Promotion progress\"></span>\n      <button type=\"button\" class=\"hagilight-promoto__control\" data-promoto-next aria-label=\"Next promotion\">\n        <svg class=\"hagilight-promoto__icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M9 6l6 6-6 6\" /></svg>\n      </button>\n      <button type=\"button\" class=\"hagilight-promoto__control\" data-promoto-pause aria-pressed=\"false\" aria-label=\"Pause automatic promotion rotation\">\n        <svg class=\"hagilight-promoto__icon hagilight-promoto__icon--pause\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M9 6v12M15 6v12\" /></svg>\n        <svg class=\"hagilight-promoto__icon hagilight-promoto__icon--play\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M8 5.5v13l11-6.5z\" /></svg>\n      </button>\n    </nav>\n    <button type=\"button\" class=\"hagilight-promoto__dismiss\" data-promoto-dismiss aria-label=\"Dismiss promotion\">\n      <svg class=\"hagilight-promoto__icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M6.5 6.5l11 11M17.5 6.5l-11 11\" /></svg>\n    </button>\n    <span class=\"hagilight-promoto__progress\" data-promoto-progress aria-hidden=\"true\"></span>\n    <span class=\"hagilight-promoto__status\" data-promoto-status aria-live=\"polite\"></span>\n  </section>\n";

package/dist/client/promoto-markup.js

@@ -0,0 +1,25 @@
+export const PROMOTO_SHELL_MARKUP = `
+  <section class="hagilight-promoto__shell" data-promoto-shell hidden aria-label="Featured promotion">
+    <div class="hagilight-promoto__viewport">
+      <div class="hagilight-promoto__track" data-promoto-track></div>
+    </div>
+    <nav class="hagilight-promoto__controls" data-promoto-controls aria-label="Promotion controls" hidden>
+      <button type="button" class="hagilight-promoto__control" data-promoto-previous aria-label="Previous promotion">
+        <svg class="hagilight-promoto__icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M15 6l-6 6 6 6" /></svg>
+      </button>
+      <span class="hagilight-promoto__count" data-promoto-count aria-label="Promotion progress"></span>
+      <button type="button" class="hagilight-promoto__control" data-promoto-next aria-label="Next promotion">
+        <svg class="hagilight-promoto__icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 6l6 6-6 6" /></svg>
+      </button>
+      <button type="button" class="hagilight-promoto__control" data-promoto-pause aria-pressed="false" aria-label="Pause automatic promotion rotation">
+        <svg class="hagilight-promoto__icon hagilight-promoto__icon--pause" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M9 6v12M15 6v12" /></svg>
+        <svg class="hagilight-promoto__icon hagilight-promoto__icon--play" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M8 5.5v13l11-6.5z" /></svg>
+      </button>
+    </nav>
+    <button type="button" class="hagilight-promoto__dismiss" data-promoto-dismiss aria-label="Dismiss promotion">
+      <svg class="hagilight-promoto__icon" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M6.5 6.5l11 11M17.5 6.5l-11 11" /></svg>
+    </button>
+    <span class="hagilight-promoto__progress" data-promoto-progress aria-hidden="true"></span>
+    <span class="hagilight-promoto__status" data-promoto-status aria-live="polite"></span>
+  </section>
+`;

package/dist/client/promoto.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Centers the fixed card in the main content column instead of the viewport: it
+ * starts after the doc sidebar and ends before the desktop table of contents.
+ * Infima's layout cannot be expressed in CSS alone (collapsible sidebar, container
+ * max-width, TOC column), so the two insets are measured and handed to promoto.css.
+ */
+export declare function syncPromotoInsets(doc: Document, banner: HTMLElement): void;
+export declare function mountPromotoBanner(doc: Document, locale: string): void;
+export declare function onRouteDidUpdate(): void;

package/dist/client/promoto.js

@@ -0,0 +1,96 @@
+import { definePromotoBannerElement, recordSiteVisit } from '@hagicode/hagilight-core/promoto-banner';
+import { PROMOTO_SHELL_MARKUP } from './promoto-markup.js';
+const ELEMENT_NAME = 'hagilight-promoto-banner';
+const DEFAULT_LOCALE = 'en-US';
+const mounts = new WeakMap();
+/** Infima switches to the single-column mobile layout below this width. */
+const DESKTOP_MIN_WIDTH = 997;
+const INSET_START = '--hagilight-promoto-inset-start';
+const INSET_END = '--hagilight-promoto-inset-end';
+let stopWatchingLayout;
+function widest(elements) {
+    return elements
+        .map((element) => element.getBoundingClientRect())
+        .filter((rect) => rect.width > 0)
+        .sort((a, b) => b.width - a.width)[0];
+}
+/**
+ * Centers the fixed card in the main content column instead of the viewport: it
+ * starts after the doc sidebar and ends before the desktop table of contents.
+ * Infima's layout cannot be expressed in CSS alone (collapsible sidebar, container
+ * max-width, TOC column), so the two insets are measured and handed to promoto.css.
+ */
+export function syncPromotoInsets(doc, banner) {
+    const viewport = doc.documentElement.clientWidth;
+    let start = 0;
+    let end = 0;
+    if (viewport >= DESKTOP_MIN_WIDTH) {
+        const main = doc.querySelector('main');
+        const columns = main ? Array.from(main.querySelectorAll(':scope > * > .row > .col, :scope > .row > .col')) : [];
+        const content = widest(columns) ?? main?.getBoundingClientRect();
+        if (content && content.width > 0) {
+            const sidebar = doc.querySelector('.theme-doc-sidebar-container')?.getBoundingClientRect();
+            start = Math.max(content.left, sidebar && sidebar.width > 0 ? sidebar.right : 0);
+            end = Math.max(0, viewport - content.right);
+        }
+    }
+    banner.style.setProperty(INSET_START, `${Math.max(0, Math.round(start))}px`);
+    banner.style.setProperty(INSET_END, `${Math.max(0, Math.round(end))}px`);
+}
+function watchPromotoLayout(doc, banner) {
+    stopWatchingLayout?.();
+    stopWatchingLayout = undefined;
+    const win = doc.defaultView;
+    if (!win || !banner.style || typeof win.ResizeObserver !== 'function')
+        return;
+    let frame = 0;
+    const schedule = () => {
+        if (frame)
+            return;
+        frame = win.requestAnimationFrame(() => {
+            frame = 0;
+            syncPromotoInsets(doc, banner);
+        });
+    };
+    const observer = new win.ResizeObserver(schedule);
+    const main = doc.querySelector('main');
+    if (main)
+        observer.observe(main);
+    observer.observe(doc.documentElement);
+    syncPromotoInsets(doc, banner);
+    stopWatchingLayout = () => {
+        observer.disconnect();
+        if (frame)
+            win.cancelAnimationFrame(frame);
+    };
+}
+function readSiteId(doc) {
+    const content = doc.querySelector('meta[name="hagilight-site-id"]')?.getAttribute('content')?.trim();
+    return content || undefined;
+}
+export function mountPromotoBanner(doc, locale) {
+    const footer = doc.querySelector('footer');
+    const previous = mounts.get(doc);
+    if (previous?.banner.isConnected && previous.footer === footer && previous.locale === locale) {
+        // The page layout may have been swapped under the same footer (docs to blog), so re-measure it.
+        watchPromotoLayout(doc, previous.banner);
+        return;
+    }
+    doc.querySelectorAll(ELEMENT_NAME).forEach((existing) => existing.remove());
+    const banner = doc.createElement(ELEMENT_NAME);
+    banner.className = 'hagilight-promoto';
+    banner.dataset.locale = locale;
+    const siteId = readSiteId(doc);
+    if (siteId)
+        banner.dataset.siteId = siteId;
+    banner.hidden = true;
+    banner.innerHTML = PROMOTO_SHELL_MARKUP;
+    doc.body.append(banner);
+    mounts.set(doc, { banner, footer, locale });
+    watchPromotoLayout(doc, banner);
+}
+export function onRouteDidUpdate() {
+    definePromotoBannerElement();
+    mountPromotoBanner(document, document.documentElement.lang || DEFAULT_LOCALE);
+    recordSiteVisit();
+}

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/discovery.d.ts

@@ -0,0 +1,42 @@
+import type { HtmlTagObject, LoadContext } from '@docusaurus/types';
+import type { BuildInfo } from '@hagicode/hagilight-core/build-info';
+import { type RssFeedItem } from '@hagicode/hagilight-core/rss';
+import type { ResolvedHagilightOptions, ResolvedRssOptions } from './options.js';
+type Warn = (message: string) => void;
+export interface DiscoveryReporter {
+    warn: Warn;
+    info: Warn;
+}
+export interface DiscoverySite {
+    title: string;
+    tagline: string;
+    url: string;
+    baseUrl: string;
+    siteDir: string;
+    i18n: LoadContext['i18n'];
+}
+export interface DiscoveryOutputs {
+    options: ResolvedHagilightOptions;
+    site: DiscoverySite;
+    /** Version of this package, recorded as the metadata generator. */
+    generatorVersion: string;
+    buildInfo: BuildInfo;
+    outDir: string;
+    production: boolean;
+    plugins: readonly {
+        name: string;
+    }[];
+    routesPaths: readonly string[];
+    routesBuildMetadata: Readonly<Record<string, {
+        noIndex: boolean;
+    } | undefined>>;
+    feedItems: readonly RssFeedItem[];
+    report: DiscoveryReporter;
+}
+export declare function sitemapUrls(routesPaths: readonly string[], routesBuildMetadata: DiscoveryOutputs['routesBuildMetadata'], siteUrl: string, localeBaseUrl: string): string[];
+export declare function sitemapXml(urls: readonly string[]): string;
+export declare function robotsTxt(sitemapUrlList: readonly string[]): string;
+export declare function collectFeedItems(allContent: unknown, site: DiscoverySite, rss: ResolvedRssOptions, report: DiscoveryReporter): RssFeedItem[];
+export declare function feedHeadTags(site: DiscoverySite, rss: ResolvedRssOptions, feedItemCount: number): HtmlTagObject[];
+export declare function writeDiscoveryOutputs(outputs: DiscoveryOutputs): Promise<void>;
+export {};