@hagicode/hagilight-starlight 0.1.2-dev.5.1.c41051d → 0.1.2-dev.7.1.c02207e

package/Footer.astro

@@ -1,12 +1,123 @@
 ---
 import Copyright from '@hagicode/hagilight/Copyright';
 import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
+import { resolveSiteLinks, type SiteLinksOptions } from '@hagicode/hagilight/site-links';
+
+interface Props {
+  locale?: string;
+  links?: SiteLinksOptions;
+}
+
+const { locale = Astro.locals?.starlightRoute?.locale, links } = Astro.props;
+const resolvedLinks = resolveSiteLinks(locale, links);
 ---
 
 <DefaultFooter />
+<div class="hagilight-site-links">
+  {resolvedLinks.relatedSites.length > 0 && (
+    <section>
+      <h2>{resolvedLinks.labels.relatedSites}</h2>
+      <nav aria-label={resolvedLinks.labels.navigation.relatedSites}>
+        <ul>
+          {resolvedLinks.relatedSites.map((site) => (
+            <li>
+              <a href={site.href} target={site.target} rel={site.rel}>
+                {site.name}
+                {site.description && <span class="hagilight-site-description">{site.description}</span>}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </section>
+  )}
+  <section>
+    <h2>{resolvedLinks.labels.quickLinks}</h2>
+    <nav aria-label={resolvedLinks.labels.navigation.quickLinks}>
+      <ul>
+        {resolvedLinks.quick.map((link) => (
+          <li><a href={link.href} target={link.target} rel={link.rel}>{link.label}</a></li>
+        ))}
+      </ul>
+    </nav>
+  </section>
+  <section>
+    <h2>{resolvedLinks.labels.community}</h2>
+    <nav aria-label={resolvedLinks.labels.navigation.community}>
+      <ul>
+        {resolvedLinks.community.map((link) => (
+          <li><a href={link.href} target={link.target} rel={link.rel}>{link.label}</a></li>
+        ))}
+      </ul>
+    </nav>
+  </section>
+  <nav class="hagilight-filings" aria-label={resolvedLinks.labels.navigation.filings}>
+    {resolvedLinks.filings.map((link) => (
+      <a
+        href={link.href}
+        target={link.target}
+        rel={link.rel}
+        aria-label={link.ariaLabel}
+      >{link.label}</a>
+    ))}
+  </nav>
+</div>
 <p class="hagilight-copyright"><Copyright name="HagiCode" /></p>
 
 <style>
+  .hagilight-site-links {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
+    gap: 1.5rem;
+    margin: 2rem auto 1rem;
+    max-width: 72rem;
+    padding-inline: 1rem;
+  }
+
+  .hagilight-site-links section {
+    min-width: 0;
+  }
+
+  .hagilight-site-links h2 {
+    margin: 0 0 0.75rem;
+    color: var(--sl-color-white);
+    font-size: var(--sl-text-sm);
+  }
+
+  .hagilight-site-links ul {
+    display: grid;
+    gap: 0.5rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .hagilight-site-links a {
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+    text-decoration: none;
+  }
+
+  .hagilight-site-links a:hover {
+    color: var(--sl-color-white);
+  }
+
+  .hagilight-site-description {
+    display: block;
+    margin-top: 0.25rem;
+    font-size: var(--sl-text-xs);
+  }
+
+  .hagilight-filings {
+    grid-column: 1 / -1;
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 0.75rem 1.5rem;
+    border-top: 1px solid var(--sl-color-gray-5);
+    padding-top: 1rem;
+  }
+
   .hagilight-copyright {
     margin-block: 1rem;
     color: var(--sl-color-gray-3);

package/Header.astro

@@ -0,0 +1,129 @@
+---
+import config from 'virtual:starlight/user-config';
+import Search from 'virtual:starlight/components/Search';
+import SiteTitle from 'virtual:starlight/components/SiteTitle';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
+import { resolveSiteLinks, type SiteLinksOptions } from '@hagicode/hagilight/site-links';
+import LanguageChooser from './LanguageChooser.astro';
+
+interface Props {
+  links?: SiteLinksOptions;
+}
+
+const { links } = Astro.props;
+const locale = Astro.locals.starlightRoute.locale;
+const resolvedLinks = resolveSiteLinks(locale, links);
+const shouldRenderSearch =
+  config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
+---
+
+<div class="header">
+  <div class="title-wrapper sl-flex">
+    <SiteTitle />
+  </div>
+  <div class="sl-flex print:hidden">
+    {shouldRenderSearch && <Search />}
+  </div>
+  <div class="sl-hidden md:sl-flex print:hidden right-group">
+    <nav class="header-links" aria-label="Site navigation">
+      {resolvedLinks.header.map((link) => (
+        <a href={link.href} target={link.target} rel={link.rel}>{link.label}</a>
+      ))}
+    </nav>
+    <div class="sl-flex social-icons">
+      <SocialIcons />
+    </div>
+    <ThemeSelect />
+    <LanguageChooser />
+  </div>
+</div>
+
+<style>
+  @layer starlight.core {
+    .header {
+      display: flex;
+      gap: var(--sl-nav-gap);
+      justify-content: space-between;
+      align-items: center;
+      height: 100%;
+    }
+
+    .title-wrapper {
+      overflow: clip;
+      padding: 0.25rem;
+      margin: -0.25rem;
+      min-width: 0;
+    }
+
+    .right-group,
+    .social-icons {
+      gap: 1rem;
+      align-items: center;
+    }
+
+    .right-group {
+      flex-wrap: nowrap;
+    }
+
+    .social-icons:has(a)::after {
+      content: '';
+      height: 2rem;
+      border-inline-end: 1px solid var(--sl-color-gray-5);
+    }
+
+    .header-links {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      white-space: nowrap;
+    }
+
+    .header-links a {
+      padding: 0.375rem 0.5rem;
+      border-radius: var(--sl-radius-sm);
+      color: var(--sl-color-text-high);
+      font-size: var(--sl-text-sm);
+      text-decoration: none;
+    }
+
+    .header-links a:hover {
+      background: var(--sl-color-gray-6);
+      color: var(--sl-color-white);
+    }
+
+    @media (max-width: 72rem) {
+      .header-links {
+        display: none;
+      }
+    }
+
+    @media (min-width: 50rem) {
+      :global(:root[data-has-sidebar]) {
+        --__sidebar-pad: calc(2 * var(--sl-nav-pad-x));
+      }
+      :global(:root:not([data-has-toc])) {
+        --__toc-width: 0rem;
+      }
+      .header {
+        --__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
+        --__main-column-fr: calc(
+          (
+              100% + var(--__sidebar-pad, 0rem) - var(--__toc-width, var(--sl-sidebar-width)) -
+                (2 * var(--__toc-width, var(--sl-nav-pad-x))) - var(--sl-content-inline-start, 0rem) -
+                var(--sl-content-width)
+            ) / 2
+        );
+        display: grid;
+        grid-template-columns:
+          minmax(
+            calc(var(--__sidebar-width) + max(0rem, var(--__main-column-fr) - var(--sl-nav-gap))),
+            auto
+          )
+          1fr
+          auto;
+        align-content: center;
+      }
+    }
+  }
+</style>

package/LanguageChooser.astro

@@ -0,0 +1,357 @@
+---
+import config from 'virtual:starlight/user-config';
+import context from 'virtual:starlight/project-context';
+import {
+  buildLocaleNavigationTarget,
+  getConfiguredLanguageOptions,
+} from './language-routing.mjs';
+
+const currentLocale = Astro.locals.starlightRoute.locale ?? config.defaultLocale?.locale ?? 'root';
+const options = getConfiguredLanguageOptions(config.locales, currentLocale);
+const currentOption = options.find((option) => option.selected) ?? options[0];
+const accessibleLabel = Astro.locals.t('languageSelect.accessibleLabel');
+const copy = {
+  'zh-cn': ['当前语言', '已选', '关闭语言选择'],
+  'en-us': ['Current language', 'Selected', 'Close language selector'],
+  'zh-hant': ['目前語言', '已選取', '關閉語言選擇'],
+  'fr-fr': ['Langue actuelle', 'Sélectionné', 'Fermer le sélecteur de langue'],
+  'de-de': ['Aktuelle Sprache', 'Ausgewählt', 'Sprachauswahl schließen'],
+  'es-es': ['Idioma actual', 'Seleccionado', 'Cerrar selector de idioma'],
+  'ja-jp': ['現在の言語', '選択中', '言語選択を閉じる'],
+  'ko-kr': ['현재 언어', '선택됨', '언어 선택 닫기'],
+  'pt-br': ['Idioma atual', 'Selecionado', 'Fechar seletor de idioma'],
+  'ru-ru': ['Текущий язык', 'Выбрано', 'Закрыть выбор языка'],
+};
+const langKey = (currentOption?.lang ?? currentLocale).toLowerCase();
+const languagePrefix = langKey.split('-')[0];
+const fallbackCopy = copy[langKey]
+  ?? Object.entries(copy).find(([key]) => key.startsWith(`${languagePrefix}-`))?.[1]
+  ?? copy['en-us'];
+const currentLabel = fallbackCopy[0];
+const selectedLabel = fallbackCopy[1];
+const closeLabel = fallbackCopy[2];
+const basePath = import.meta.env.BASE_URL;
+const routeLocales = Object.keys(config.locales ?? {});
+const navigationOptions = options.map((option) => ({
+  ...option,
+  href: buildLocaleNavigationTarget(
+    Astro.url,
+    option.code,
+    routeLocales,
+    basePath,
+    context.trailingSlash,
+  ).pathname,
+}));
+---
+
+{
+  config.isMultilingual && navigationOptions.length > 1 && (
+    <hagilight-language-chooser class="language-switcher">
+      <button
+        type="button"
+        class="language-trigger"
+        aria-haspopup="dialog"
+        aria-controls="hagilight-language-dialog"
+        aria-expanded="false"
+        aria-label={`${accessibleLabel}: ${currentOption?.label ?? currentLocale}`}
+        title={currentOption?.label ?? currentLocale}
+      >
+        <span class="trigger-label">{currentOption?.label ?? currentLocale}</span>
+        <span class="trigger-chevron" aria-hidden="true">▾</span>
+      </button>
+      <dialog
+        id="hagilight-language-dialog"
+        class="language-dialog"
+        aria-modal="true"
+        aria-labelledby="language-dialog-title"
+      >
+        <div class="dialog-header">
+          <div>
+            <h2 id="language-dialog-title" class="dialog-title">{accessibleLabel}</h2>
+            <p class="dialog-current">
+              {currentLabel}: <strong>{currentOption?.label ?? currentLocale}</strong>
+            </p>
+          </div>
+          <button type="button" class="dialog-close" aria-label={closeLabel}>×</button>
+        </div>
+        <div class="language-grid-scroller">
+          <div class="language-grid" role="listbox" aria-label={accessibleLabel}>
+            {navigationOptions.map((option) => (
+              <button
+                type="button"
+                role="option"
+                data-locale={option.code}
+                data-href={option.href}
+                lang={option.lang}
+                aria-selected={option.selected ? 'true' : 'false'}
+                class:list={['language-option', { 'language-option-selected': option.selected }]}
+              >
+                <span class="language-option-label">{option.label}</span>
+                {option.selected && <span class="selected-badge">{selectedLabel}</span>}
+              </button>
+            ))}
+          </div>
+        </div>
+      </dialog>
+    </hagilight-language-chooser>
+  )
+}
+
+<script>
+  import {
+    getKeyboardTargetIndex,
+    persistStarlightLocaleSelection,
+  } from './language-routing.mjs';
+
+  class HagilightLanguageChooser extends HTMLElement {
+    connectedCallback() {
+      if (this.dataset.initialized) return;
+      this.dataset.initialized = 'true';
+
+      const trigger = this.querySelector('.language-trigger');
+      const dialog = this.querySelector('.language-dialog');
+      const closeButton = this.querySelector('.dialog-close');
+      const options = [...this.querySelectorAll('[role="option"]')];
+      if (!(trigger instanceof HTMLButtonElement)
+        || !(dialog instanceof HTMLDialogElement)
+        || !(closeButton instanceof HTMLButtonElement)) return;
+
+      const closeDialog = () => {
+        if (dialog.open) dialog.close();
+        else trigger.focus();
+      };
+
+      trigger.addEventListener('click', () => {
+        if (dialog.open) {
+          closeDialog();
+          return;
+        }
+        dialog.showModal();
+        trigger.setAttribute('aria-expanded', 'true');
+        const activeOption = options.find((option) => option.getAttribute('aria-selected') === 'true');
+        (activeOption ?? options[0])?.focus();
+      });
+      closeButton.addEventListener('click', closeDialog);
+      dialog.addEventListener('cancel', (event) => {
+        event.preventDefault();
+        closeDialog();
+      });
+      dialog.addEventListener('close', () => {
+        trigger.setAttribute('aria-expanded', 'false');
+        trigger.focus();
+      });
+      dialog.addEventListener('click', (event) => {
+        if (event.target === dialog) closeDialog();
+      });
+      dialog.querySelector('[role="listbox"]')?.addEventListener('keydown', (event) => {
+        if (!(event.target instanceof HTMLButtonElement)) return;
+        const index = options.indexOf(event.target);
+        const nextIndex = getKeyboardTargetIndex(index, event.key, options.length);
+        if (nextIndex !== index) {
+          event.preventDefault();
+          options[nextIndex]?.focus();
+        }
+      });
+      for (const option of options) {
+        option.addEventListener('click', () => {
+          const locale = option.dataset.locale;
+          const href = option.dataset.href;
+          if (!locale || !href) return;
+          closeDialog();
+          if (option.getAttribute('aria-selected') === 'true') return;
+          persistStarlightLocaleSelection(locale);
+          const target = new URL(href, window.location.origin);
+          target.search = window.location.search;
+          target.hash = window.location.hash;
+          window.location.assign(target.toString());
+        });
+      }
+    }
+  }
+
+  if (!customElements.get('hagilight-language-chooser')) {
+    customElements.define('hagilight-language-chooser', HagilightLanguageChooser);
+  }
+</script>
+
+<style>
+  .language-switcher {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .language-trigger {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.55rem;
+    min-width: 7.25rem;
+    min-height: 2.125rem;
+    padding: 0 0.8rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--sl-color-black) 8%, transparent);
+    color: var(--sl-color-text-high);
+    cursor: pointer;
+    font: inherit;
+    transition: background-color var(--sl-transition-fast), border-color var(--sl-transition-fast);
+  }
+
+  .language-trigger:hover,
+  .dialog-close:hover,
+  .language-option:hover {
+    background: var(--sl-color-gray-6);
+    border-color: var(--sl-color-accent-high);
+  }
+
+  .language-trigger:focus-visible,
+  .dialog-close:focus-visible,
+  .language-option:focus-visible {
+    outline: 2px solid var(--sl-color-accent-high);
+    outline-offset: 2px;
+  }
+
+  .trigger-label {
+    max-width: 10rem;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: var(--sl-text-sm);
+    font-weight: var(--sl-font-weight-medium);
+  }
+
+  .trigger-chevron {
+    font-size: 0.75rem;
+    transition: transform var(--sl-transition-fast);
+  }
+
+  .language-switcher:has(.language-dialog[open]) .trigger-chevron {
+    transform: rotate(180deg);
+  }
+
+  .language-dialog {
+    width: min(54rem, calc(100vw - 3rem));
+    max-width: none;
+    max-height: min(30rem, calc(100dvh - 3rem));
+    padding: 1.1rem 1.1rem 1rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 1rem;
+    background: color-mix(in srgb, var(--sl-color-bg) 94%, transparent);
+    color: var(--sl-color-text);
+    box-shadow: 0 24px 64px rgba(2, 6, 23, 0.32);
+  }
+
+  .language-dialog::backdrop {
+    background: rgba(15, 23, 42, 0.52);
+  }
+
+  .dialog-header {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 1rem;
+    margin-bottom: 1rem;
+  }
+
+  .dialog-title {
+    margin: 0;
+    color: var(--sl-color-white);
+    font-size: 1rem;
+    font-weight: 700;
+  }
+
+  .dialog-current {
+    margin: 0.35rem 0 0;
+    font-size: var(--sl-text-sm);
+  }
+
+  .dialog-close {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.25rem;
+    height: 2.25rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 999px;
+    background: transparent;
+    color: var(--sl-color-text-high);
+    cursor: pointer;
+    font: inherit;
+    font-size: 1.125rem;
+  }
+
+  .language-grid-scroller {
+    max-height: min(20rem, calc(100dvh - 11rem));
+    overflow: auto;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.875rem;
+    background: color-mix(in srgb, var(--sl-color-black) 6%, transparent);
+    padding: 0.95rem 1rem;
+  }
+
+  .language-grid {
+    display: grid;
+    grid-template-columns: repeat(5, minmax(7.75rem, 8.75rem));
+    justify-content: center;
+    gap: 0.7rem;
+  }
+
+  .language-option {
+    display: flex;
+    min-height: 4.2rem;
+    width: 100%;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 0.45rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.875rem;
+    background: color-mix(in srgb, var(--sl-color-bg-nav) 88%, transparent);
+    color: var(--sl-color-text-high);
+    cursor: pointer;
+    font: inherit;
+    font-size: 0.95rem;
+    font-weight: 700;
+    padding: 0.75rem 0.65rem;
+    text-align: center;
+  }
+
+  .language-option-selected {
+    border-color: var(--sl-color-accent-high);
+    background: color-mix(in srgb, var(--sl-color-accent-high) 18%, transparent);
+  }
+
+  .selected-badge {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-height: 1.45rem;
+    padding: 0 0.55rem;
+    border-radius: 999px;
+    background: color-mix(in srgb, var(--sl-color-accent-high) 18%, transparent);
+    color: var(--sl-color-accent-high);
+    font-size: 0.75rem;
+  }
+
+  @media (max-width: 72rem) {
+    .language-dialog {
+      width: min(46rem, calc(100vw - 2.5rem));
+    }
+
+    .language-grid {
+      grid-template-columns: repeat(4, minmax(7.35rem, 8.35rem));
+    }
+  }
+
+  @media (max-width: 50rem) {
+    .language-dialog {
+      width: calc(100vw - 2rem);
+      max-height: calc(100dvh - 2rem);
+      padding: 1rem;
+    }
+
+    .language-grid {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+  }
+</style>

package/index.mjs

@@ -1,19 +1,169 @@
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
+const GOOGLE_ID_PATTERN = /^G-[A-Z0-9]+$/u;
+const FIFTY_ONE_LA_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
+const defaultLogo = fileURLToPath(import.meta.resolve('@hagicode/hagilight/logo.png'));
+
+function resolveProvider(config, { name, idKey, pattern }) {
+  if (config === undefined) return undefined;
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new TypeError(`Hagilight ${name} analytics options must be an object.`);
+  }
+
+  const enabled = config.enabled ?? Boolean(config[idKey]);
+  if (!enabled) return undefined;
+
+  const id = config[idKey];
+  if (typeof id !== 'string' || !id.trim()) {
+    throw new Error(`Hagilight ${name} analytics is enabled but its ${idKey} is missing.`);
+  }
+  if (!pattern.test(id)) {
+    throw new Error(`Hagilight ${name} analytics ${idKey} has an invalid format.`);
+  }
+  return id;
+}
+
+function createConfiguredIntegration(instanceId, serializedOptions, componentIds) {
+  const optionsId = `virtual:hagilight-starlight/${instanceId}/options`;
+  const headerPath = componentIds.header
+    ? fileURLToPath(new URL('./Header.astro', import.meta.url))
+    : undefined;
+  const footerPath = fileURLToPath(new URL('./Footer.astro', import.meta.url));
+  const headerSource = headerPath
+    ? `---
+import Header from ${JSON.stringify(headerPath)};
+import options from '${optionsId}';
+---
+
+<Header links={options.links} />
+`
+    : undefined;
+  const promotionImport = serializedOptions.promotoEnabled
+    ? "import PromotoBanner from '@hagicode/hagilight/PromotoBanner';"
+    : '';
+  const promotionRender = serializedOptions.promotoEnabled ? '<PromotoBanner />' : '';
+  const analyticsImport = serializedOptions.fiftyOneLaId
+    ? "import Analytics51LA from '@hagicode/hagilight/Analytics51LA';"
+    : '';
+  const analyticsRender = serializedOptions.fiftyOneLaId
+    ? '<Analytics51LA siteId={options.fiftyOneLaId} />'
+    : '';
+  const footerSource = `---
+import Footer from ${JSON.stringify(footerPath)};
+${promotionImport}
+${analyticsImport}
+import options from '${optionsId}';
+---
+
+<Footer locale={Astro.locals?.starlightRoute?.locale} links={options.links} />
+${promotionRender}
+${analyticsRender}
+`;
+  const headSource = `---
+import DefaultHead from '@astrojs/starlight/components/Head.astro';
+import GoogleAnalytics from '@hagicode/hagilight/GoogleAnalytics';
+import options from '${optionsId}';
+const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
+---
+
+<DefaultHead />
+{!isNotFound && options.googleAnalyticsMeasurementId && (
+  <GoogleAnalytics measurementId={options.googleAnalyticsMeasurementId} />
+)}
+`;
+  const modules = new Map([
+    ...(componentIds.header ? [[componentIds.header, headerSource]] : []),
+    [componentIds.footer, footerSource],
+    ...(componentIds.head ? [[componentIds.head, headSource]] : []),
+    [optionsId, `export default ${JSON.stringify(serializedOptions)};`],
+  ]);
+  const vitePlugin = {
+    name: `@hagicode/hagilight-starlight:${instanceId}`,
+    resolveId(id) {
+      return modules.has(id) ? `\0${id}` : null;
+    },
+    load(id) {
+      return id.startsWith('\0') ? modules.get(id.slice(1)) ?? null : null;
+    },
+  };
+
+  return {
+    name: `@hagicode/hagilight-starlight:${instanceId}`,
+    hooks: {
+      'astro:config:setup'({ updateConfig }) {
+        updateConfig({ vite: { plugins: [vitePlugin] } });
+      },
+    },
+  };
+}
+
 export default function hagilight(options = {}) {
-  const footer = options.promoto?.enabled === false ? 'Footer.astro' : 'PromotoFooter.astro';
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('Hagilight Starlight options must be an object.');
+  }
+  if (options.header !== undefined
+    && (!options.header || typeof options.header !== 'object' || Array.isArray(options.header))) {
+    throw new TypeError('Hagilight header options must be an object.');
+  }
+  if (options.header?.enabled !== undefined && typeof options.header.enabled !== 'boolean') {
+    throw new TypeError('Hagilight header enabled option must be a boolean.');
+  }
+  if (options.analytics !== undefined
+    && (!options.analytics || typeof options.analytics !== 'object' || Array.isArray(options.analytics))) {
+    throw new TypeError('Hagilight analytics options must be an object.');
+  }
+  const analytics = options.analytics ?? {};
+  const googleAnalyticsMeasurementId = resolveProvider(analytics.googleAnalytics, {
+    name: 'Google Analytics',
+    idKey: 'measurementId',
+    pattern: GOOGLE_ID_PATTERN,
+  });
+  const fiftyOneLaId = resolveProvider(analytics.fiftyOneLa, {
+    name: '51LA',
+    idKey: 'siteId',
+    pattern: FIFTY_ONE_LA_ID_PATTERN,
+  });
+  const instanceId = randomUUID();
+  const headerEnabled = options.header?.enabled !== false;
+  const componentIds = {
+    header: headerEnabled
+      ? `virtual:hagilight-starlight/${instanceId}/Header.astro`
+      : undefined,
+    footer: `virtual:hagilight-starlight/${instanceId}/Footer.astro`,
+    head: googleAnalyticsMeasurementId
+      ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
+      : undefined,
+  };
+  const serializedOptions = {
+    promotoEnabled: options.promoto?.enabled !== false,
+    links: options.links ?? {},
+    googleAnalyticsMeasurementId,
+    fiftyOneLaId,
+  };
+
   return {
     name: '@hagicode/hagilight-starlight',
     hooks: {
-      'config:setup'({ config, updateConfig }) {
+      'config:setup'({ config, updateConfig, addIntegration }) {
+        if (headerEnabled && config.components?.Header) {
+          throw new Error('Hagilight cannot replace an existing Starlight Header override. Set header: { enabled: false } to keep it, or compose @hagicode/hagilight-starlight/Header directly.');
+        }
         if (config.components?.Footer) {
           throw new Error('Hagilight cannot replace an existing Starlight Footer override.');
         }
+        if (googleAnalyticsMeasurementId && config.components?.Head) {
+          throw new Error('Hagilight Google Analytics cannot replace an existing Starlight Head override. Compose @hagicode/hagilight/GoogleAnalytics in your Head instead.');
+        }
 
+        addIntegration(createConfiguredIntegration(instanceId, serializedOptions, componentIds));
         updateConfig({
+          ...(config.logo === undefined ? { logo: { src: defaultLogo, alt: 'HagiCode' } } : {}),
           components: {
             ...config.components,
-            Footer: fileURLToPath(new URL(`./${footer}`, import.meta.url)),
+            ...(componentIds.header ? { Header: componentIds.header } : {}),
+            Footer: componentIds.footer,
+            ...(componentIds.head ? { Head: componentIds.head } : {}),
           },
         });
       },

package/language-routing.mjs

@@ -0,0 +1,114 @@
+export const DEFAULT_LANGUAGE_OPTIONS = [
+  { code: 'root', label: '简体中文', lang: 'zh-CN' },
+  { code: 'en-US', label: 'English', lang: 'en-US' },
+  { code: 'zh-Hant', label: '繁體中文', lang: 'zh-Hant' },
+  { code: 'fr-FR', label: 'Français', lang: 'fr-FR' },
+  { code: 'de-DE', label: 'Deutsch', lang: 'de-DE' },
+  { code: 'es-ES', label: 'Español (España)', lang: 'es-ES' },
+  { code: 'ja-JP', label: '日本語', lang: 'ja-JP' },
+  { code: 'ko-KR', label: '한국어', lang: 'ko-KR' },
+  { code: 'pt-BR', label: 'Português (Brasil)', lang: 'pt-BR' },
+  { code: 'ru-RU', label: 'Русский', lang: 'ru-RU' },
+];
+
+const normalizeLang = (lang) => lang?.replaceAll('_', '-').toLowerCase();
+
+export function getConfiguredLanguageOptions(locales, currentLocale) {
+  const catalog = DEFAULT_LANGUAGE_OPTIONS;
+  return Object.entries(locales ?? {})
+    .map(([code, locale]) => {
+      const lang = typeof locale === 'string' ? locale : locale?.lang ?? code;
+      const catalogEntry = catalog.find((entry) =>
+        entry.code === code || normalizeLang(entry.lang) === normalizeLang(lang),
+      );
+      return {
+        code,
+        label: typeof locale === 'object' && locale?.label
+          ? locale.label
+          : catalogEntry?.label ?? code,
+        lang,
+        selected: code === currentLocale,
+        catalogOrder: catalogEntry ? catalog.indexOf(catalogEntry) : catalog.length,
+      };
+    })
+    .sort((left, right) => left.catalogOrder - right.catalogOrder)
+    .map(({ catalogOrder, ...option }) => option);
+}
+
+export function getKeyboardTargetIndex(index, key, count) {
+  if (count < 1) return -1;
+  switch (key) {
+    case 'ArrowDown':
+    case 'ArrowRight':
+      return (index + 1) % count;
+    case 'ArrowUp':
+    case 'ArrowLeft':
+      return (index - 1 + count) % count;
+    case 'Home':
+      return 0;
+    case 'End':
+      return count - 1;
+    default:
+      return index;
+  }
+}
+
+export function buildLocaleNavigationTarget(
+  currentUrl,
+  targetLocale,
+  configuredLocales,
+  basePath = '/',
+  trailingSlash = 'ignore',
+) {
+  const targetUrl = new URL(currentUrl);
+  const base = basePath.replace(/\/+$/u, '');
+  const hasBase = base === ''
+    ? true
+    : targetUrl.pathname === base || targetUrl.pathname.startsWith(`${base}/`);
+  let pathname = hasBase ? targetUrl.pathname.slice(base.length) || '/' : targetUrl.pathname;
+  const [, firstSegment = '', remainder = ''] = pathname.match(/^\/([^/]*)(.*)$/u) ?? [];
+  const isHtmlRoute = firstSegment.endsWith('.html');
+  const currentSlug = isHtmlRoute ? firstSegment.slice(0, -5) : firstSegment;
+  const currentLocale = configuredLocales.find((locale) => locale !== 'root' && locale === currentSlug);
+
+  if (currentLocale) {
+    if (targetLocale === 'root') {
+      pathname = isHtmlRoute ? '/index.html' : remainder || '/';
+    } else {
+      pathname = `/${targetLocale}${isHtmlRoute ? '.html' : remainder}`;
+    }
+  } else if (targetLocale !== 'root') {
+    pathname = firstSegment === 'index.html'
+      ? `/${targetLocale}.html`
+      : `/${targetLocale}${pathname}`;
+  }
+
+  targetUrl.pathname = `${hasBase ? base : ''}${pathname}` || '/';
+  if (trailingSlash === 'never') {
+    targetUrl.pathname = targetUrl.pathname.replace(/\/+$/u, '') || '/';
+  }
+  return targetUrl;
+}
+
+export function persistStarlightLocaleSelection(locale) {
+  try {
+    const storedValue = window.localStorage.getItem('starlight-route');
+    let routePreference = {};
+    if (storedValue) {
+      try {
+        const parsed = JSON.parse(storedValue);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          routePreference = parsed;
+        }
+      } catch {
+        routePreference = {};
+      }
+    }
+    window.localStorage.setItem(
+      'starlight-route',
+      JSON.stringify({ ...routePreference, lang: locale }),
+    );
+  } catch {
+    // Language navigation must remain available when browser storage is blocked.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.1.2-dev.5.1.c41051d",
+  "version": "0.1.2-dev.7.1.c02207e",
   "type": "module",
   "description": "Starlight customizations for HagiCode documentation",
   "repository": {
@@ -14,15 +14,17 @@
   },
   "exports": {
     ".": "./index.mjs",
+    "./Header": "./Header.astro",
     "./Footer": "./Footer.astro",
     "./PromotoFooter": "./PromotoFooter.astro"
   },
   "files": [
     "index.mjs",
+    "*.mjs",
     "*.astro"
   ],
   "dependencies": {
-    "@hagicode/hagilight": "0.1.2-dev.5.1.c41051d"
+    "@hagicode/hagilight": "0.1.2-dev.7.1.c02207e"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",