@hagicode/hagilight-starlight 0.11.0 → 0.11.1-dev.133.1.338317a

package/ArticlePromotion.astro

@@ -57,7 +57,8 @@ const gallery = copy.gallery.flatMap((item) => {
           href={homeHref}
           {...showcaseTag('navigation', 'home')}
         >
-          {copy.visitLabel}
+          <span>{copy.visitLabel}</span>
+          <svg class="hagilight-article-promotion__arrow" aria-hidden="true" focusable="false" viewBox="0 0 20 20" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 10h11M11 5l5 5-5 5" /></svg>
         </a>
         <a
           class="hagilight-article-promotion__cta hagilight-article-promotion__cta--secondary"
@@ -137,7 +138,7 @@ const gallery = copy.gallery.flatMap((item) => {
           class="hagilight-article-promotion__downloads"
           href={downloadsHref}
           {...showcaseTag('download', 'downloadClient')}
-        >{copy.allDownloadsLabel}</a>
+        ><span>{copy.allDownloadsLabel}</span><svg class="hagilight-article-promotion__arrow" aria-hidden="true" focusable="false" viewBox="0 0 20 20" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 10h11M11 5l5 5-5 5" /></svg></a>
       </div>
     </div>
 
@@ -151,43 +152,74 @@ const gallery = copy.gallery.flatMap((item) => {
 
 <style>
   /*
-   * Zones, top to bottom: pitch (what it is, where to go, the three pillars), gallery (proof),
-   * closing (get it, share it). Zones are separated by space and hairlines rather than nested
-   * boxes. The topology follows the section's own width, so the wide-content toggle and the
-   * sidebar layouts reflow it, not just the viewport. Mobile-first: the base rules are the
-   * single-column layout, which is also what a browser without container queries renders.
+   * One stage, four beats, top to bottom: pitch (what it is, the way in, the three pillars),
+   * gallery (proof), closing band (get it, share it). The stage is tinted from the active theme's
+   * accent so it reads as a deliberate HagiCode moment against the article's neutral page, and the
+   * closing band bleeds to the stage edges so "get it" is the last, heaviest surface. Pillars are
+   * separated by accent rules rather than boxes. The topology follows the section's own width, so
+   * the wide-content toggle and the sidebar layouts reflow it, not just the viewport. Mobile-first:
+   * the base rules are the single-column layout, which is also what a browser without container
+   * queries renders. Every color derives from Starlight's tokens, so all themes and both modes work.
    */
   .hagilight-article-promotion {
+    --hagilight-promo-pad: 1.5rem;
+    --hagilight-promo-edge: color-mix(in srgb, var(--sl-color-text-accent) 38%, var(--sl-color-gray-5));
+    --hagilight-promo-tint: color-mix(in srgb, var(--sl-color-accent-low) 55%, var(--sl-color-bg-nav));
+    position: relative;
     container-type: inline-size;
     display: grid;
     grid-template-columns: minmax(0, 1fr);
-    gap: 2rem;
+    gap: 2.25rem;
     margin: 3rem auto 2rem;
-    padding: clamp(1rem, 3vw, 1.75rem);
-    border: 1px solid var(--sl-color-gray-5);
+    padding: calc(var(--hagilight-promo-pad) + 0.25rem) var(--hagilight-promo-pad) var(--hagilight-promo-pad);
+    overflow: clip;
+    border: 1px solid var(--hagilight-promo-edge);
     border-radius: var(--sl-radius-lg, 0.75rem);
-    background: var(--sl-color-bg-nav);
+    background:
+      radial-gradient(70% 45% at 0% 0%, color-mix(in srgb, var(--sl-color-text-accent) 16%, transparent), transparent 70%),
+      linear-gradient(180deg, var(--hagilight-promo-tint), var(--sl-color-bg-nav) 55%);
     color: var(--sl-color-text);
   }
 
+  /* The accent rule across the top edge: the stage's signature, drawn in on scroll where supported. */
+  .hagilight-article-promotion::before {
+    content: '';
+    position: absolute;
+    inset: 0 0 auto;
+    height: 4px;
+    background: linear-gradient(90deg, var(--sl-color-text-accent), color-mix(in srgb, var(--sl-color-text-accent) 20%, transparent));
+    transform-origin: left center;
+    pointer-events: none;
+  }
+
+  .hagilight-article-promotion ::selection {
+    background: color-mix(in srgb, var(--sl-color-text-accent) 38%, transparent);
+    color: var(--sl-color-white);
+  }
+
   .hagilight-article-promotion h2,
   .hagilight-article-promotion h3 {
     margin: 0;
     color: var(--sl-color-white);
-    line-height: 1.25;
+    line-height: 1.2;
+    text-wrap: balance;
   }
 
   .hagilight-article-promotion h2 {
-    font-size: var(--sl-text-2xl, 1.5rem);
+    font-size: clamp(2rem, 1.3rem + 3.2cqi, 3rem);
+    font-weight: 800;
+    letter-spacing: -0.02em;
   }
 
   .hagilight-article-promotion h3 {
-    font-size: var(--sl-text-lg, 1.125rem);
+    font-size: var(--sl-text-xl, 1.25rem);
+    font-weight: 700;
   }
 
   .hagilight-article-promotion p {
     margin: 0;
     line-height: 1.6;
+    text-wrap: pretty;
   }
 
   .hagilight-article-promotion ul {
@@ -201,17 +233,17 @@ const gallery = copy.gallery.flatMap((item) => {
     outline-offset: 3px;
   }
 
-  /* Pitch: headline, definition, promise, then the way in. */
+  /* Pitch: headline, one emphasized promise, the way in, then the pillars. */
   .hagilight-article-promotion__pitch {
     display: grid;
-    gap: 1.75rem;
+    gap: 2rem;
   }
 
   .hagilight-article-promotion__intro {
     display: grid;
     align-content: start;
     justify-items: start;
-    gap: 0.75rem;
+    gap: 0.875rem;
   }
 
   .hagilight-article-promotion__lead,
@@ -219,9 +251,15 @@ const gallery = copy.gallery.flatMap((item) => {
     max-inline-size: 68ch;
   }
 
+  .hagilight-article-promotion__lead {
+    color: var(--sl-color-gray-2);
+  }
+
   .hagilight-article-promotion__tagline {
     color: var(--sl-color-white);
-    font-weight: 600;
+    font-size: var(--sl-text-lg, 1.125rem);
+    font-weight: 650;
+    line-height: 1.45;
   }
 
   .hagilight-article-promotion__actions {
@@ -236,32 +274,60 @@ const gallery = copy.gallery.flatMap((item) => {
     display: inline-flex;
     align-items: center;
     justify-content: center;
+    gap: 0.5rem;
     min-height: 2.75rem;
-    padding: 0.5rem 1rem;
+    padding: 0.5rem 1.25rem;
     border: 1px solid var(--sl-color-text-accent);
     border-radius: var(--sl-radius-sm, 0.375rem);
     font-weight: 700;
     text-decoration: none;
+    transition: transform 0.2s cubic-bezier(0.22, 1, 0.36, 1), box-shadow 0.2s cubic-bezier(0.22, 1, 0.36, 1), background-color 0.2s;
   }
 
+  /* The one loud control: bigger than its sibling, lifted, with an arrow that leans forward on hover. */
   .hagilight-article-promotion__cta--primary {
+    min-height: 3.25rem;
+    padding-inline: 1.625rem;
     background: var(--sl-color-text-accent);
     color: var(--sl-color-bg);
+    font-size: var(--sl-text-lg, 1.125rem);
+    box-shadow: 0 8px 20px -8px color-mix(in srgb, var(--sl-color-text-accent) 70%, transparent);
   }
 
   .hagilight-article-promotion__cta--secondary {
     background: transparent;
+    color: var(--sl-color-white);
+    border-color: var(--sl-color-gray-3);
+  }
+
+  .hagilight-article-promotion__arrow {
+    flex: none;
+    transition: transform 0.2s cubic-bezier(0.22, 1, 0.36, 1);
+  }
+
+  .hagilight-article-promotion__cta--primary:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 12px 24px -8px color-mix(in srgb, var(--sl-color-text-accent) 80%, transparent);
+  }
+
+  .hagilight-article-promotion__cta--primary:active {
+    transform: translateY(0);
+  }
+
+  .hagilight-article-promotion__cta--secondary:hover {
+    border-color: var(--sl-color-text-accent);
     color: var(--sl-color-text-accent);
   }
 
-  .hagilight-article-promotion__cta:hover {
-    filter: brightness(1.08);
+  .hagilight-article-promotion__cta:hover .hagilight-article-promotion__arrow,
+  .hagilight-article-promotion__downloads:hover .hagilight-article-promotion__arrow {
+    transform: translateX(3px);
   }
 
-  /* Pillars: one hairline-topped row each, icon and word on a line, description under it. */
+  /* Pillars: each opens with an accent rule; the pillar word is the loudest text after the title. */
   .hagilight-article-promotion__features {
     display: grid;
-    gap: 1rem 1.5rem;
+    gap: 1.25rem 1.5rem;
   }
 
   .hagilight-article-promotion__features li {
@@ -269,16 +335,17 @@ const gallery = copy.gallery.flatMap((item) => {
     grid-template-columns: auto minmax(0, 1fr);
     align-content: start;
     align-items: center;
-    gap: 0.5rem 0.625rem;
+    gap: 0.625rem 0.75rem;
     min-width: 0;
-    padding-block-start: 0.875rem;
-    border-block-start: 1px solid var(--sl-color-gray-5);
+    padding-block-start: 1rem;
+    border-block-start: 2px solid color-mix(in srgb, var(--sl-color-text-accent) 55%, transparent);
   }
 
   .hagilight-article-promotion__features strong {
     color: var(--sl-color-text-accent);
-    font-size: var(--sl-text-lg, 1.125rem);
-    line-height: 1.25;
+    font-size: var(--sl-text-xl, 1.25rem);
+    font-weight: 750;
+    line-height: 1.2;
   }
 
   .hagilight-article-promotion__feature-text {
@@ -288,6 +355,17 @@ const gallery = copy.gallery.flatMap((item) => {
   }
 
   .hagilight-article-promotion__icon {
+    position: relative;
+    display: grid;
+    place-items: center;
+    width: 2.5rem;
+    height: 2.5rem;
+    border-radius: var(--sl-radius-md, 0.5rem);
+    background: color-mix(in srgb, var(--sl-color-text-accent) 18%, transparent);
+  }
+
+  .hagilight-article-promotion__icon::after {
+    content: '';
     width: 1.5rem;
     height: 1.5rem;
     background: var(--sl-color-text-accent);
@@ -298,12 +376,12 @@ const gallery = copy.gallery.flatMap((item) => {
   /* Gallery: three audited screenshots, kept in the catalog's narrative order. */
   .hagilight-article-promotion__gallery-block {
     display: grid;
-    gap: 1rem;
+    gap: 1.125rem;
   }
 
   .hagilight-article-promotion__gallery {
     display: grid;
-    gap: 1.25rem 1rem;
+    gap: 1.5rem 1.25rem;
   }
 
   .hagilight-article-promotion__gallery li {
@@ -312,7 +390,7 @@ const gallery = copy.gallery.flatMap((item) => {
 
   .hagilight-article-promotion figure {
     display: grid;
-    gap: 0.5rem;
+    gap: 0.625rem;
     margin: 0;
   }
 
@@ -324,22 +402,31 @@ const gallery = copy.gallery.flatMap((item) => {
     display: block;
     width: 100%;
     height: auto;
-    border: 1px solid var(--sl-color-gray-5);
+    border: 1px solid var(--hagilight-promo-edge);
     border-radius: var(--sl-radius-md, 0.5rem);
+    box-shadow: 0 18px 32px -18px color-mix(in srgb, var(--sl-color-black) 80%, transparent);
+    transition: transform 0.35s cubic-bezier(0.22, 1, 0.36, 1), border-color 0.35s;
+  }
+
+  .hagilight-article-promotion figure:hover img {
+    transform: translateY(-3px);
+    border-color: var(--sl-color-text-accent);
   }
 
   .hagilight-article-promotion figcaption {
-    color: var(--sl-color-gray-2);
+    color: var(--sl-color-gray-1);
     font-size: var(--sl-text-sm, 0.875rem);
     line-height: 1.5;
   }
 
-  /* Closing: the practical next steps, as two parallel headed blocks. */
+  /* Closing: a full-bleed band, the heaviest surface, so "get it" is where the eye lands last. */
   .hagilight-article-promotion__closing {
     display: grid;
-    gap: 1.5rem;
-    padding-block-start: 1.5rem;
-    border-block-start: 1px solid var(--sl-color-gray-5);
+    gap: 1.75rem;
+    margin: 0 calc(var(--hagilight-promo-pad) * -1) calc(var(--hagilight-promo-pad) * -1);
+    padding: var(--hagilight-promo-pad);
+    border-block-start: 1px solid var(--hagilight-promo-edge);
+    background: color-mix(in srgb, var(--sl-color-accent-low) 80%, var(--sl-color-bg));
   }
 
   .hagilight-article-promotion__windows,
@@ -347,7 +434,7 @@ const gallery = copy.gallery.flatMap((item) => {
     display: grid;
     align-content: start;
     justify-items: start;
-    gap: 0.5rem;
+    gap: 0.625rem;
     min-width: 0;
   }
 
@@ -356,7 +443,7 @@ const gallery = copy.gallery.flatMap((item) => {
     display: flex;
     flex-wrap: wrap;
     align-items: center;
-    gap: 0 1.25rem;
+    gap: 0 1.5rem;
     max-width: 100%;
   }
 
@@ -378,15 +465,18 @@ const gallery = copy.gallery.flatMap((item) => {
   .hagilight-article-promotion__downloads {
     display: inline-flex;
     align-items: center;
+    gap: 0.375rem;
     min-height: 2.75rem;
     color: var(--sl-color-text-accent);
-    font-weight: 600;
+    font-weight: 650;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 0.25em;
   }
 
   .hagilight-article-promotion__share-text {
     justify-self: stretch;
     padding: 0.75rem 1rem;
-    border: 1px dashed var(--sl-color-gray-4);
+    border: 1px dashed var(--sl-color-text-accent);
     border-radius: var(--sl-radius-md, 0.5rem);
     background: var(--sl-color-bg);
     overflow-wrap: anywhere;
@@ -452,4 +542,53 @@ const gallery = copy.gallery.flatMap((item) => {
       justify-self: stretch;
     }
   }
+
+  /*
+   * The one authored moment: as the stage scrolls into view its accent rule draws across and the
+   * screenshots rise into place one after another. Scroll-driven, so there is no JS and nothing
+   * replays; engines without view timelines, and readers who ask for less motion, get the final
+   * state. The animations start at 0.35 opacity, so a tall item that never reaches its full entry
+   * range is still readable.
+   */
+  @media (prefers-reduced-motion: no-preference) {
+    @supports (animation-timeline: view()) {
+      .hagilight-article-promotion::before {
+        animation-name: hagilight-promotion-rule;
+        animation-timing-function: linear;
+        animation-fill-mode: both;
+        animation-timeline: view();
+        animation-range: entry 0% entry 80%;
+      }
+
+      .hagilight-article-promotion__gallery li {
+        animation-name: hagilight-promotion-rise;
+        animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
+        animation-fill-mode: both;
+        animation-timeline: view();
+        animation-range: entry 5% entry 45%;
+      }
+
+      .hagilight-article-promotion__gallery li:nth-child(2) {
+        animation-range: entry 12% entry 52%;
+      }
+
+      .hagilight-article-promotion__gallery li:nth-child(3) {
+        animation-range: entry 19% entry 59%;
+      }
+    }
+  }
+
+  @keyframes hagilight-promotion-rule {
+    from {
+      transform: scaleX(0.04);
+    }
+  }
+
+  @keyframes hagilight-promotion-rise {
+    from {
+      opacity: 0.35;
+      translate: 0 1.75rem;
+      scale: 0.97;
+    }
+  }
 </style>

package/README.md

@@ -29,6 +29,43 @@ export default defineConfig({
 
 The plugin also exposes `@hagicode/hagilight-starlight/schema` for optional SEO frontmatter and individual Astro components such as `/Header` and `/MarkdownContent` for custom Starlight overrides. Configure features through the typed `HagilightStarlightOptions` passed to `hagilight()`.
 
+### Analytics
+
+`hagilight()` enables PostHog without analytics configuration, an enabled flag, or a consumer project key. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://us.i.posthog.com`, and SDK defaults `2026-05-30`. Google Analytics and PostHog render together in the generated global Head; 51LA stays in the Footer. PostHog covers all production pages, including localized and 404 pages, independently of Google's existing 404 exclusion. Development pages emit no PostHog loader.
+
+PostHog options follow the Google Analytics provider convention:
+
+| 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
+hagilight(); // shared analytics defaults
+hagilight({ analytics: { posthog: { apiKey: 'phc_Custom123' } } });
+hagilight({ analytics: { posthog: { enabled: false } } });
+```
+
+A site-owned `components.Head` conflicts with enabled SEO, Google Analytics, or PostHog. To retain it, disable all three head features and explicitly compose the desired metadata and `@hagicode/hagilight-core/GoogleAnalytics` / `@hagicode/hagilight-core/PostHog` components in that Head:
+
+```js
+hagilight({
+  seo: { enabled: false },
+  analytics: {
+    googleAnalytics: { enabled: false },
+    posthog: { enabled: false },
+  },
+});
+```
+
+The shared component initializes once per document; SDK defaults own PostHog navigation behavior. Choose one initialization owner and disable this provider when the site already initializes PostHog. Google Analytics and 51LA keep their configured behavior when PostHog is disabled.
+
 ### Theme picker
 
 By default the plugin replaces Starlight's light/dark toggle with a theme picker offering nine choices: the default theme plus the Ocean, Sakura, and Forest themes in light and dark, and a "Default" choice that follows the visitor's system color scheme and renders the Forest theme. First-time visitors, and visitors with an invalid saved choice, therefore see Forest; the other themes appear only after an explicit selection, which is remembered in `localStorage`.
@@ -45,6 +82,15 @@ hagilight({ themes: { enabled: false } })
 
 The plugin footer shows the same build line as the Astro package: `Branch:`, `Commit:`, and `Built:` after the attribution. It is always on and has no option of its own. The values come from `HAGILIGHT_BUILD_BRANCH` and `HAGILIGHT_BUILD_COMMIT`, then Git, then `unknown`; the core README gives the order. Detached-HEAD CI checkouts report `Branch: unknown` unless the build step sets `HAGILIGHT_BUILD_BRANCH`, as shown in the Astro README. Footer components mounted directly in a page (`@hagicode/hagilight-starlight/Footer` and `PromotoFooter`) render no build text.
 
+### Site metadata
+
+The plugin writes `/.well-known/hagilight.metadata.json` once per build, after the sitemap, so `discovery` lists the sitemap and any RSS feed that exist. The file's schema and privacy rules are in `@hagicode/hagilight-core`'s README.
+
+- `metadata: false` opts out. `metadata: { name, description }` sets the values; the name defaults to the Starlight `title` for the default locale, then the site hostname.
+- Analytics flags report the resolved options. A provider you disable with `analytics` reads `false`. The IDs and keys are never written.
+- When the plain-Astro `hagilight()` integration is also registered, this plugin writes the file, including `llms.txt` in `discovery`, whatever the order of registration. Set `metadata: false` here to let the plain-Astro integration write it instead.
+- GitHub Pages needs a `.nojekyll` file in the published root, or the `.well-known` directory is dropped. The `/docs/` base path puts the file at `<site URL>/docs/.well-known/hagilight.metadata.json`.
+
 ### Body images
 
 `hagilight()` registers the content-image plugin from `@hagicode/hagilight-core/content-images` for the whole site. Every Markdown or MDX body image outside a `<picture>` element gets `loading="lazy"`, `decoding="async"`, and the class `hagilight-content-image`. Values the author set are kept, and logos and showcase images are not changed.

package/dist/index.d.ts

@@ -20,6 +20,12 @@ export interface HagilightFiftyOneLaOptions {
 export interface HagilightAnalyticsOptions {
     googleAnalytics?: HagilightGoogleAnalyticsOptions;
     fiftyOneLa?: HagilightFiftyOneLaOptions;
+    posthog?: HagilightPostHogOptions;
+}
+export interface HagilightPostHogOptions {
+    /** Defaults to true when the provider options are omitted, otherwise to whether apiKey is set. */
+    enabled?: boolean;
+    apiKey?: string;
 }
 export interface HagilightSeoOptions {
     /** Replace Starlight's Head with Hagilight SEO metadata. Defaults to `true`; requires Astro `site`. */
@@ -49,7 +55,22 @@ export interface HagilightContentComponentsOptions {
     markdownContent?: boolean;
 }
 export type HagilightAIDisclosureOptions = Partial<AIDisclosureDefaults>;
+export interface HagilightMetadataOptions {
+    /** Defaults to `true`. */
+    enabled?: boolean;
+    /** Site name. Defaults to the Starlight `title` for the default locale, then the site hostname. */
+    name?: string;
+    /** Site description. Defaults to the Starlight `description` when the site sets one. */
+    description?: string;
+}
 export interface HagilightStarlightOptions {
+    /**
+     * Generate `/.well-known/hagilight.metadata.json` after the build. Defaults to `true`; `false`
+     * opts out, and an options object may set `name` and `description`. A site-provided file is
+     * never overwritten. When a plain-Astro `hagilight()` is also registered, this plugin writes
+     * the file and the plain-Astro integration defers to it.
+     */
+    metadata?: boolean | HagilightMetadataOptions;
     header?: HagilightToggleOptions;
     notFoundPage?: HagilightToggleOptions;
     rss?: HagilightRssOptions;

package/dist/index.js

@@ -3,11 +3,15 @@ import { fileURLToPath } from 'node:url';
 import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
 import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
 import { checkContentImageRegistration, registerContentImages } from '@hagicode/hagilight-core/content-images';
+import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagilight-core/posthog';
 import { resolveRssLocales } from '@hagicode/hagilight-core/rss';
 import { RSS_OWNER, registerStarlightRssOwner, } from '@hagicode/hagilight-core/rss-ownership';
 import { isValidSeoImageReference, resolveSeoImageUrl } from '@hagicode/hagilight-core/seo';
+import { resolveSiteMetadataOption } from '@hagicode/hagilight-core/site-metadata';
+import { registerStarlightSiteMetadataOwner } from '@hagicode/hagilight-core/site-metadata-ownership';
 import { resolveRssOptions } from './rss-utils.js';
 import { resolveSeoLocales } from './seo-utils.js';
+import { createStarlightMetadataFinalizer } from './site-metadata.js';
 import { THEME_BOOTSTRAP } from './themes.js';
 const packageRoot = new URL('../', import.meta.url);
 const packageFile = (name) => fileURLToPath(new URL(name, packageRoot));
@@ -201,7 +205,7 @@ function resolveDefaultSeoLocale(defaultLocale, locales) {
     }
     return found.route;
 }
-function createConfiguredIntegration(instanceId, serializedOptions, rssConfig, rssLocaleFeedUrls, componentIds, getConfiguredRssFeed, generateRss, unregisterRssOwner, contentImagesEnabled) {
+function createConfiguredIntegration(instanceId, serializedOptions, rssConfig, rssLocaleFeedUrls, componentIds, getConfiguredRssFeed, generateRss, unregisterRssOwner, contentImagesEnabled, siteMetadata, unregisterSiteMetadataOwner) {
     const optionsId = `virtual:hagilight-starlight/${instanceId}/options`;
     const rssConfigId = 'virtual:hagilight-starlight/rss-config';
     const headerPath = componentIds.header ? packageFile('Header.astro') : undefined;
@@ -267,11 +271,13 @@ import options from '${optionsId}';
 import DefaultHead from '@astrojs/starlight/components/Head.astro';
 import SEOHead from ${JSON.stringify(seoHeadPath)};
 import GoogleAnalytics from ${JSON.stringify(coreExport('GoogleAnalytics'))};
+${serializedOptions.posthogApiKey ? `import PostHog from ${JSON.stringify(coreExport('PostHog'))};` : ''}
 import options from '${optionsId}';
 const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
 ---
 
 {options.seoEnabled ? <SEOHead options={options} /> : <DefaultHead />}
+${serializedOptions.posthogApiKey ? '<PostHog apiKey={options.posthogApiKey} />' : ''}
 {!isNotFound && options.googleAnalyticsMeasurementId && (
   <GoogleAnalytics measurementId={options.googleAnalyticsMeasurementId} />
 )}
@@ -325,10 +331,18 @@ const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
                         prerender: true,
                     });
                 }
-                updateConfig({ vite: { plugins: [vitePlugin] } });
+                // Starlight splices its own sitemap into the integration list before this setup runs, so
+                // the finalizer appended in the same update runs after the sitemap has written its index.
+                updateConfig({
+                    vite: { plugins: [vitePlugin] },
+                    ...(siteMetadata.enabled
+                        ? { integrations: [createStarlightMetadataFinalizer(siteMetadata, () => buildInfo)] }
+                        : {}),
+                });
             },
             'astro:config:done'({ config, logger }) {
                 unregisterRssOwner();
+                unregisterSiteMetadataOwner();
                 checkContentImageRegistration({ config, logger, enabled: contentImagesEnabled });
                 if (config.image?.service?.entrypoint === NOOP_IMAGE_SERVICE) {
                     logger.warn(NOOP_IMAGE_SERVICE_WARNING);
@@ -371,6 +385,14 @@ export default function hagilight(options = {}) {
         pattern: FIFTY_ONE_LA_ID_PATTERN,
         defaultId: DEFAULT_51LA_ID,
     });
+    const posthog = optionalRecord(analytics.posthog, 'PostHog analytics');
+    optionalBoolean(posthog, 'enabled', 'PostHog analytics enabled');
+    const posthogApiKey = resolveProvider(analytics.posthog, {
+        name: 'PostHog',
+        idKey: 'apiKey',
+        pattern: POSTHOG_API_KEY_PATTERN,
+        defaultId: DEFAULT_POSTHOG_API_KEY,
+    });
     const promoto = optionalRecord(input.promoto, 'promoto');
     const promotoEnabled = optionalBoolean(promoto, 'enabled', 'promoto enabled') !== false;
     const contentImages = optionalRecord(input.contentImages, 'contentImages');
@@ -388,7 +410,7 @@ export default function hagilight(options = {}) {
         markdownContent: markdownContentEnabled
             ? `virtual:hagilight-starlight/${instanceId}/MarkdownContent.astro`
             : undefined,
-        head: seo.enabled || googleAnalyticsMeasurementId
+        head: seo.enabled || googleAnalyticsMeasurementId || posthogApiKey
             ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
             : undefined,
         themeSelect: themesEnabled ? packageFile('ThemeSelect.astro') : undefined,
@@ -399,11 +421,14 @@ export default function hagilight(options = {}) {
         links: options.links ?? {},
         googleAnalyticsMeasurementId,
         fiftyOneLaId,
+        posthogApiKey,
         aiDisclosures,
         seoEnabled: seo.enabled,
         seo,
     };
     const unregisterRssOwner = registerStarlightRssOwner(rssEnabled);
+    const metadata = resolveSiteMetadataOption(input.metadata);
+    const unregisterSiteMetadataOwner = registerStarlightSiteMetadataOwner(metadata.enabled);
     return {
         name: '@hagicode/hagilight-starlight',
         hooks: {
@@ -428,9 +453,9 @@ export default function hagilight(options = {}) {
                 }
                 if (componentIds.head && config.components?.Head) {
                     if (seo.enabled) {
-                        throw new Error('Hagilight SEO cannot replace an existing Starlight Head override. Set seo: { enabled: false } and disable Google Analytics to keep your Head, or compose your site metadata explicitly.');
+                        throw new Error('Hagilight SEO cannot replace an existing Starlight Head override. Set seo: { enabled: false }, analytics.googleAnalytics: { enabled: false }, and analytics.posthog: { enabled: false } to keep your Head, or compose SEO, @hagicode/hagilight-core/GoogleAnalytics and @hagicode/hagilight-core/PostHog explicitly.');
                     }
-                    throw new Error('Hagilight Google Analytics cannot replace an existing Starlight Head override. Disable Google Analytics or compose @hagicode/hagilight-core/GoogleAnalytics in your Head instead.');
+                    throw new Error('Hagilight Google Analytics or PostHog cannot replace an existing Starlight Head override. Set analytics.googleAnalytics: { enabled: false } and analytics.posthog: { enabled: false } to keep it, or compose @hagicode/hagilight-core/GoogleAnalytics and @hagicode/hagilight-core/PostHog in your Head.');
                 }
                 let seoSite;
                 let seoLocales = [];
@@ -483,7 +508,24 @@ export default function hagilight(options = {}) {
                         new URL(`rss.${filename}.xml`, baseUrl).toString(),
                     ]))
                     : {};
-                addIntegration(createConfiguredIntegration(instanceId, serializedOptions, { options: rssOptions, locales: rssLocales }, rssLocaleFeedUrls, componentIds, () => getRssFeedUrl(config) ?? rssFeedUrl, generateRss, unregisterRssOwner, contentImagesEnabled));
+                addIntegration(createConfiguredIntegration(instanceId, serializedOptions, { options: rssOptions, locales: rssLocales }, rssLocaleFeedUrls, componentIds, () => getRssFeedUrl(config) ?? rssFeedUrl, generateRss, unregisterRssOwner, contentImagesEnabled, {
+                    enabled: metadata.enabled,
+                    name: metadata.name,
+                    description: metadata.description,
+                    title: config.title,
+                    siteDescription: config.description,
+                    locales: config.locales,
+                    defaultLocale: config.defaultLocale,
+                    site: astroConfig.site,
+                    base: astroConfig.base,
+                    publicDir: astroConfig.publicDir,
+                    analytics: {
+                        googleAnalytics: serializedOptions.googleAnalyticsMeasurementId !== undefined,
+                        fiftyOneLa: serializedOptions.fiftyOneLaId !== undefined,
+                        posthog: serializedOptions.posthogApiKey !== undefined,
+                    },
+                    features: { seo: seo.enabled, promoto: promotoEnabled },
+                }, unregisterSiteMetadataOwner));
                 updateConfig({
                     ...(config.logo === undefined ? { logo: { src: defaultLogo, alt: 'HagiCode' } } : {}),
                     customCss: [

package/dist/site-metadata.d.ts

@@ -0,0 +1,38 @@
+import type { AstroIntegration } from 'astro';
+import type { BuildInfo } from '@hagicode/hagilight-core/build-info';
+import { type SiteMetadataAnalytics, type SiteMetadataFeatures } from '@hagicode/hagilight-core/site-metadata';
+import { type SiteMetadataLogger } from '@hagicode/hagilight-core/site-metadata-writer';
+export interface StarlightSiteMetadataSetup {
+    enabled: boolean;
+    /** Explicit `metadata.name`, when set. */
+    name?: string | undefined;
+    /** Explicit `metadata.description`, when set. */
+    description?: string | undefined;
+    /** Starlight `title`: a string or a localized record. */
+    title: unknown;
+    /** Starlight `description`, when the site configures one. */
+    siteDescription?: unknown;
+    /** Starlight `locales` map, for example `{ root: { lang: 'en' } }`. */
+    locales: unknown;
+    /** Starlight `defaultLocale`. */
+    defaultLocale: unknown;
+    site: unknown;
+    base: string | undefined;
+    publicDir: URL;
+    analytics: SiteMetadataAnalytics;
+    features: SiteMetadataFeatures;
+}
+export interface WriteStarlightSiteMetadataInput {
+    outDir: string;
+    setup: StarlightSiteMetadataSetup;
+    build: BuildInfo;
+    logger: SiteMetadataLogger;
+}
+/** Build and write the metadata file for a Starlight build. Skips with a warning when no absolute site URL exists. */
+export declare function writeStarlightSiteMetadata({ outDir, setup, build, logger }: WriteStarlightSiteMetadataInput): void;
+/**
+ * Integration appended after this plugin's sitemap, so the write runs after
+ * `@astrojs/sitemap` has written its index. The owner's write also waits for any
+ * deferring plain-Astro peer that reported before it.
+ */
+export declare function createStarlightMetadataFinalizer(setup: StarlightSiteMetadataSetup, buildInfo: () => BuildInfo | undefined): AstroIntegration;

package/dist/site-metadata.js

@@ -0,0 +1,109 @@
+/**
+ * Facts for `.well-known/hagilight.metadata.json` from a Starlight build. The
+ * Starlight plugin owns the file when it is enabled, so this module collects the
+ * title, locales and resolved feature flags from its own configuration.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildSiteMetadata, SITE_METADATA_PATH, } from '@hagicode/hagilight-core/site-metadata';
+import { findDiscoveryOutputs, writeSiteMetadata } from '@hagicode/hagilight-core/site-metadata-writer';
+import { completeSiteMetadataOwnerBuild } from '@hagicode/hagilight-core/site-metadata-ownership';
+import { resolveSeoLocales } from './seo-utils.js';
+const STARLIGHT_PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function absoluteSite(site) {
+    try {
+        const parsed = new URL(site);
+        return ['http:', 'https:'].includes(parsed.protocol) && !parsed.username && !parsed.password ? parsed.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function trimmedText(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+/** Starlight locale routes become metadata locales. The root route uses its language tag as the code. */
+function toMetadataLocales(locales) {
+    const routes = new Map();
+    const entries = locales.map(({ route, lang }) => {
+        const code = route === 'root' ? lang : route;
+        routes.set(route, code);
+        return { code, lang, path: route === 'root' ? '/' : `/${route}/` };
+    });
+    return { locales: entries, routes };
+}
+/** Starlight's default locale is the route named in `defaultLocale`, or `root`. */
+function defaultRoute(defaultLocale, locales) {
+    const configured = isRecord(defaultLocale) ? defaultLocale.locale ?? defaultLocale.lang : defaultLocale;
+    if (typeof configured !== 'string' || !configured.trim())
+        return locales.find(({ route }) => route === 'root')?.route ?? locales[0]?.route ?? 'root';
+    const match = locales.find(({ route, lang }) => route === configured || lang === configured);
+    return match?.route ?? configured;
+}
+/** Starlight's title, read for the default locale. A localized record uses `root` or its first entry. */
+function siteTitle(title, route) {
+    if (typeof title === 'string')
+        return trimmedText(title);
+    if (!isRecord(title))
+        return undefined;
+    return trimmedText(title[route] ?? title.root ?? Object.values(title)[0]);
+}
+/** Build and write the metadata file for a Starlight build. Skips with a warning when no absolute site URL exists. */
+export function writeStarlightSiteMetadata({ outDir, setup, build, logger }) {
+    const siteUrl = absoluteSite(setup.site);
+    if (!siteUrl) {
+        logger.warn(`${SITE_METADATA_PATH} requires an absolute Astro site URL, so it was not generated.`);
+        return;
+    }
+    const seoLocales = resolveSeoLocales(setup.locales);
+    const { locales, routes } = toMetadataLocales(seoLocales);
+    const defaultCode = routes.get(defaultRoute(setup.defaultLocale, seoLocales));
+    const route = defaultRoute(setup.defaultLocale, seoLocales);
+    const base = `${setup.base || '/'}`.replace(/\/?$/u, '/');
+    const metadata = buildSiteMetadata({
+        generator: { name: '@hagicode/hagilight-starlight', version: STARLIGHT_PACKAGE_VERSION },
+        site: {
+            name: setup.name ?? siteTitle(setup.title, route),
+            url: siteUrl,
+            base,
+            description: setup.description ?? trimmedText(setup.siteDescription),
+        },
+        locales,
+        defaultLocale: defaultCode,
+        fallbackLang: seoLocales.find((entry) => entry.route === route)?.lang,
+        build,
+        discovery: findDiscoveryOutputs(outDir),
+        analytics: setup.analytics,
+        features: setup.features,
+    });
+    writeSiteMetadata({
+        outDir,
+        metadata,
+        siteOwnedFiles: [join(fileURLToPath(setup.publicDir), SITE_METADATA_PATH)],
+        logger,
+    });
+}
+/**
+ * Integration appended after this plugin's sitemap, so the write runs after
+ * `@astrojs/sitemap` has written its index. The owner's write also waits for any
+ * deferring plain-Astro peer that reported before it.
+ */
+export function createStarlightMetadataFinalizer(setup, buildInfo) {
+    return {
+        name: '@hagicode/hagilight-starlight:metadata',
+        hooks: {
+            'astro:build:done'({ dir, logger }) {
+                completeSiteMetadataOwnerBuild(() => {
+                    const build = buildInfo();
+                    if (!build)
+                        return;
+                    writeStarlightSiteMetadata({ outDir: fileURLToPath(dir), setup, build, logger });
+                });
+            },
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.11.0",
+  "version": "0.11.1-dev.133.1.338317a",
   "type": "module",
   "description": "Starlight plugin and components for HagiCode documentation",
   "repository": {
@@ -53,7 +53,7 @@
     "assets/showcase/*"
   ],
   "dependencies": {
-    "@hagicode/hagilight-core": "0.11.0"
+    "@hagicode/hagilight-core": "0.11.1-dev.133.1.338317a"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",