@hagicode/hagilight-starlight 0.11.1-dev.129.1.ea757b8 → 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

@@ -82,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

@@ -55,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

@@ -7,8 +7,11 @@ import { DEFAULT_POSTHOG_API_KEY, POSTHOG_API_KEY_PATTERN } from '@hagicode/hagi
 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));
@@ -202,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;
@@ -328,10 +331,18 @@ ${serializedOptions.posthogApiKey ? '<PostHog apiKey={options.posthogApiKey} />'
                         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);
@@ -416,6 +427,8 @@ export default function hagilight(options = {}) {
         seo,
     };
     const unregisterRssOwner = registerStarlightRssOwner(rssEnabled);
+    const metadata = resolveSiteMetadataOption(input.metadata);
+    const unregisterSiteMetadataOwner = registerStarlightSiteMetadataOwner(metadata.enabled);
     return {
         name: '@hagicode/hagilight-starlight',
         hooks: {
@@ -495,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.1-dev.129.1.ea757b8",
+  "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.1-dev.129.1.ea757b8"
+    "@hagicode/hagilight-core": "0.11.1-dev.133.1.338317a"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",