@hagicode/hagilight-starlight 0.1.0-dev.148.1.e0c630e

package/dist/index.js

@@ -0,0 +1,583 @@
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
+import { resolveBuildInfo } from '@hagicode/hagilight-core/build-info-resolver';
+import { resolveFooterAvatarOptions } from '@hagicode/hagilight-core/footer-avatar';
+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));
+const coreExport = (name) => fileURLToPath(import.meta.resolve(`@hagicode/hagilight-core/${name}`));
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function optionalRecord(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        throw new TypeError(`Hagilight ${label} options must be an object.`);
+    return value;
+}
+function optionalBoolean(record, key, label) {
+    const value = record?.[key];
+    if (value !== undefined && typeof value !== 'boolean') {
+        throw new TypeError(`Hagilight ${label} option must be a boolean.`);
+    }
+    return value;
+}
+const NOOP_IMAGE_SERVICE = 'astro/assets/services/noop';
+const NOOP_IMAGE_SERVICE_WARNING = '@hagicode/hagilight-starlight: the Astro image service is the passthrough no-op, so the showcase AVIF and JPEG tiers will serve the original bytes. Use the default sharp service or another transforming image service.';
+const GOOGLE_ID_PATTERN = /^G-[A-Z0-9]+$/u;
+const FIFTY_ONE_LA_ID_PATTERN = /^[A-Za-z0-9_-]+$/u;
+const DEFAULT_GOOGLE_ANALYTICS_ID = 'G-EN03FMT2Q4';
+const DEFAULT_51LA_ID = 'L6b88a5yK4h2Xnci';
+const defaultLogo = coreExport('logo.png');
+const contentWidthCssPath = packageFile('content-width.css');
+const themesCssPath = packageFile('themes.css');
+const contentWidthHeadScript = `(() => {
+  let mode = 'wide';
+  try {
+    const stored = localStorage.getItem('hagilight-content-width');
+    if (stored === 'wide' || stored === 'narrow') mode = stored;
+  } catch {
+    mode = 'wide';
+  }
+  document.documentElement.dataset.hagilightContentWidth = mode;
+})();`;
+function resolveProvider(config, { name, idKey, pattern, defaultId }) {
+    if (config !== undefined && !isRecord(config)) {
+        throw new TypeError(`Hagilight ${name} analytics options must be an object.`);
+    }
+    const enabled = config === undefined ? true : config.enabled ?? Boolean(config[idKey]);
+    if (!enabled)
+        return undefined;
+    const id = config === undefined ? defaultId : 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 resolveAIDisclosures(config) {
+    if (config === undefined) {
+        return {
+            isAITranslation: false,
+            isAIAuthor: false,
+            sourceLocale: 'root',
+        };
+    }
+    if (!isRecord(config)) {
+        throw new TypeError('Hagilight aiDisclosures options must be an object.');
+    }
+    for (const key of ['isAITranslation', 'isAIAuthor']) {
+        if (config[key] !== undefined && typeof config[key] !== 'boolean') {
+            throw new TypeError(`Hagilight aiDisclosures ${key} option must be a boolean.`);
+        }
+    }
+    const sourceLocale = config.sourceLocale === undefined ? 'root' : config.sourceLocale;
+    if (typeof sourceLocale !== 'string' || !sourceLocale.trim() || /[/\\]/u.test(sourceLocale)) {
+        throw new TypeError('Hagilight aiDisclosures sourceLocale option must be a non-empty string.');
+    }
+    return {
+        isAITranslation: config.isAITranslation ?? false,
+        isAIAuthor: config.isAIAuthor ?? false,
+        sourceLocale: sourceLocale.trim(),
+    };
+}
+function resolveHagicodePromotion(config) {
+    if (config === undefined)
+        return true;
+    if (!isRecord(config)) {
+        throw new TypeError('Hagilight hagicodePromotion options must be an object.');
+    }
+    if (config.enabled !== undefined && typeof config.enabled !== 'boolean') {
+        throw new TypeError('Hagilight hagicodePromotion enabled option must be a boolean.');
+    }
+    return config.enabled ?? true;
+}
+function resolveHagicodePromotionRandomAvatar(config) {
+    if (config === undefined || !isRecord(config))
+        return true;
+    if (config.randomAvatar !== undefined && typeof config.randomAvatar !== 'boolean') {
+        throw new TypeError('Hagilight hagicodePromotion randomAvatar option must be a boolean.');
+    }
+    return config.randomAvatar ?? true;
+}
+function getRssFeedUrl(config) {
+    if (!Array.isArray(config.head))
+        return undefined;
+    const rssLink = config.head.find((entry) => {
+        const attrs = entry?.attrs;
+        return entry?.tag === 'link'
+            && attrs?.rel === 'alternate'
+            && typeof attrs.type === 'string'
+            && attrs.type.toLowerCase() === 'application/rss+xml'
+            && typeof attrs.href === 'string';
+    });
+    return rssLink?.attrs?.href;
+}
+function optionalSeoText(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`Hagilight SEO ${field} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function resolveSeoOptions(config) {
+    if (config !== undefined && !isRecord(config)) {
+        throw new TypeError('Hagilight seo options must be an object.');
+    }
+    if (config?.enabled !== undefined && typeof config.enabled !== 'boolean') {
+        throw new TypeError('Hagilight seo enabled option must be a boolean.');
+    }
+    const image = config?.image;
+    if (image !== undefined && !isValidSeoImageReference(image)) {
+        throw new TypeError('Hagilight SEO image must be an absolute HTTP(S) URL or a site-root path.');
+    }
+    let organization;
+    if (config?.organization !== undefined) {
+        const identity = config.organization;
+        if (!isRecord(identity)) {
+            throw new TypeError('Hagilight SEO organization option must be an object.');
+        }
+        const name = optionalSeoText(identity.name, 'organization name');
+        const url = optionalSeoText(identity.url, 'organization URL');
+        if (!name)
+            throw new TypeError('Hagilight SEO organization name is required.');
+        if (!url)
+            throw new TypeError('Hagilight SEO organization URL is required.');
+        let parsedUrl;
+        try {
+            parsedUrl = new URL(url);
+        }
+        catch {
+            throw new TypeError('Hagilight SEO organization URL must be an absolute HTTP(S) URL.');
+        }
+        if (!['http:', 'https:'].includes(parsedUrl.protocol) || parsedUrl.username || parsedUrl.password) {
+            throw new TypeError('Hagilight SEO organization URL must be an absolute HTTP(S) URL.');
+        }
+        if (identity.logo !== undefined && !isValidSeoImageReference(identity.logo)) {
+            throw new TypeError('Hagilight SEO organization logo must be an absolute HTTP(S) URL or a site-root path.');
+        }
+        organization = {
+            name,
+            url: parsedUrl.href,
+            ...(identity.logo === undefined ? {} : { logo: identity.logo }),
+        };
+    }
+    return {
+        enabled: config?.enabled ?? true,
+        title: optionalSeoText(config?.title, 'title'),
+        description: optionalSeoText(config?.description, 'description'),
+        ...(image === undefined ? {} : { image }),
+        ...(organization === undefined ? {} : { organization }),
+    };
+}
+function resolveAstroSite(site) {
+    if (site === undefined || site === null || site === '') {
+        throw new Error('Hagilight SEO requires an absolute Astro site URL. Set site or disable generated SEO with seo: { enabled: false }.');
+    }
+    let parsed;
+    try {
+        parsed = new URL(site);
+    }
+    catch {
+        throw new Error('Hagilight SEO requires Astro site to be an absolute HTTP(S) URL.');
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) {
+        throw new Error('Hagilight SEO requires Astro site to be an absolute HTTP(S) URL.');
+    }
+    return parsed.href;
+}
+function resolveDefaultSeoLocale(defaultLocale, locales) {
+    const configured = isRecord(defaultLocale)
+        ? defaultLocale.locale ?? defaultLocale.lang
+        : defaultLocale;
+    if (configured === undefined) {
+        return locales.find(({ route }) => route === 'root')?.route ?? locales[0].route;
+    }
+    const found = locales.find(({ route, lang }) => route === configured || lang.toLowerCase() === String(configured).toLowerCase());
+    if (!found) {
+        throw new Error(`Hagilight SEO default locale "${configured}" is not present in Starlight locales.`);
+    }
+    return found.route;
+}
+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;
+    const footerPath = packageFile('Footer.astro');
+    const pageTitlePath = packageFile('PageTitle.astro');
+    const markdownContentPath = packageFile('MarkdownContent.astro');
+    const seoHeadPath = packageFile('SEOHead.astro');
+    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 ${JSON.stringify(coreExport('PromotoBanner'))};`
+        : '';
+    const promotionRender = serializedOptions.promotoEnabled
+        ? '<PromotoBanner siteId={options.links?.siteId} />'
+        : '';
+    const analyticsImport = serializedOptions.fiftyOneLaId
+        ? `import Analytics51LA from ${JSON.stringify(coreExport('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}
+  rssFeedUrl={options.rssFeedUrl}
+  rssLocaleFeedUrls={options.rssLocaleFeedUrls}
+  buildInfo={options.buildInfo}
+  avatar={options.footerAvatar.avatar}
+  randomAvatar={options.footerAvatar.randomAvatar}
+/>
+${promotionRender}
+${analyticsRender}
+`;
+    const pageTitleSource = `---
+import PageTitle from ${JSON.stringify(pageTitlePath)};
+---
+
+<PageTitle />
+`;
+    const markdownContentSource = `---
+import MarkdownContent from ${JSON.stringify(markdownContentPath)};
+import options from '${optionsId}';
+---
+
+<MarkdownContent
+  aiDisclosures={options.aiDisclosures}
+  hagicodePromotionEnabled={options.hagicodePromotionEnabled}
+  hagicodePromotionRandomAvatar={options.hagicodePromotionRandomAvatar}
+><slot /></MarkdownContent>
+`;
+    const headSource = `---
+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} />
+)}
+`;
+    const modules = new Map([
+        ...(componentIds.header && headerSource ? [[componentIds.header, headerSource]] : []),
+        [componentIds.footer, footerSource],
+        ...(componentIds.pageTitle ? [[componentIds.pageTitle, pageTitleSource]] : []),
+        ...(componentIds.markdownContent ? [[componentIds.markdownContent, markdownContentSource]] : []),
+        ...(componentIds.head ? [[componentIds.head, headSource]] : []),
+    ]);
+    let buildInfo;
+    const vitePlugin = {
+        name: `@hagicode/hagilight-starlight:${instanceId}`,
+        resolveId(id) {
+            return modules.has(id) || id === optionsId || id === rssConfigId ? `\0${id}` : null;
+        },
+        load(id) {
+            if (!id.startsWith('\0'))
+                return null;
+            const moduleId = id.slice(1);
+            if (moduleId === optionsId) {
+                return `export default ${JSON.stringify({
+                    ...serializedOptions,
+                    rssFeedUrl: getConfiguredRssFeed(),
+                    rssLocaleFeedUrls,
+                    buildInfo,
+                })};`;
+            }
+            if (moduleId === rssConfigId)
+                return `export default ${JSON.stringify(rssConfig)};`;
+            return modules.get(moduleId) ?? null;
+        },
+    };
+    return {
+        name: `@hagicode/hagilight-starlight:${instanceId}`,
+        [RSS_OWNER]: { package: 'starlight', enabled: generateRss },
+        hooks: {
+            'astro:config:setup'({ config, injectRoute, updateConfig, logger }) {
+                registerContentImages({ config, logger, enabled: contentImagesEnabled });
+                buildInfo = resolveBuildInfo({ root: fileURLToPath(config.root) });
+                if (generateRss) {
+                    injectRoute({
+                        pattern: '/rss.xml',
+                        entrypoint: packageFile('rss.xml.ts'),
+                        prerender: true,
+                    });
+                    injectRoute({
+                        pattern: '/rss.[language].xml',
+                        entrypoint: packageFile('rss.[language].xml.ts'),
+                        prerender: true,
+                    });
+                }
+                // 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);
+                }
+            },
+        },
+    };
+}
+/** Starlight plugin that applies HagiCode header, footer, content, SEO, RSS, and analytics customizations. */
+export default function hagilight(options = {}) {
+    if (!isRecord(options)) {
+        throw new TypeError('Hagilight Starlight options must be an object.');
+    }
+    const input = options;
+    const header = optionalRecord(input.header, 'header');
+    const headerEnabled = optionalBoolean(header, 'enabled', 'header enabled') !== false;
+    const notFoundPage = optionalRecord(input.notFoundPage, 'notFoundPage');
+    const notFoundPageEnabled = optionalBoolean(notFoundPage, 'enabled', 'notFoundPage enabled') !== false;
+    const rss = optionalRecord(input.rss, 'rss');
+    const rssEnabled = optionalBoolean(rss, 'enabled', 'rss enabled') !== false;
+    const rssOptions = resolveRssOptions(rss);
+    const analytics = optionalRecord(input.analytics, 'analytics') ?? {};
+    const seo = resolveSeoOptions(input.seo);
+    const contentComponents = optionalRecord(input.contentComponents, 'contentComponents');
+    const themes = optionalRecord(input.themes, 'themes');
+    const themesEnabled = optionalBoolean(themes, 'enabled', 'themes enabled') !== false;
+    const pageTitleEnabled = optionalBoolean(contentComponents, 'pageTitle', 'contentComponents pageTitle') !== false;
+    const markdownContentEnabled = optionalBoolean(contentComponents, 'markdownContent', 'contentComponents markdownContent') !== false;
+    const aiDisclosures = resolveAIDisclosures(input.aiDisclosures);
+    const hagicodePromotionEnabled = resolveHagicodePromotion(input.hagicodePromotion);
+    const hagicodePromotionRandomAvatar = resolveHagicodePromotionRandomAvatar(input.hagicodePromotion);
+    const footerOptions = optionalRecord(input.footer, 'footer');
+    const footerAvatar = resolveFooterAvatarOptions({
+        avatar: optionalBoolean(footerOptions, 'avatar', 'footer avatar'),
+        randomAvatar: optionalBoolean(footerOptions, 'randomAvatar', 'footer randomAvatar'),
+    });
+    const googleAnalyticsMeasurementId = resolveProvider(analytics.googleAnalytics, {
+        name: 'Google Analytics',
+        idKey: 'measurementId',
+        pattern: GOOGLE_ID_PATTERN,
+        defaultId: DEFAULT_GOOGLE_ANALYTICS_ID,
+    });
+    const fiftyOneLaId = resolveProvider(analytics.fiftyOneLa, {
+        name: '51LA',
+        idKey: 'siteId',
+        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');
+    const contentImagesEnabled = optionalBoolean(contentImages, 'enabled', 'contentImages enabled') !== false;
+    const instanceId = randomUUID();
+    const componentIds = {
+        header: headerEnabled
+            ? `virtual:hagilight-starlight/${instanceId}/Header.astro`
+            : undefined,
+        hero: notFoundPageEnabled
+            ? packageFile('NotFoundHero.astro')
+            : undefined,
+        footer: `virtual:hagilight-starlight/${instanceId}/Footer.astro`,
+        pageTitle: pageTitleEnabled ? `virtual:hagilight-starlight/${instanceId}/PageTitle.astro` : undefined,
+        markdownContent: markdownContentEnabled
+            ? `virtual:hagilight-starlight/${instanceId}/MarkdownContent.astro`
+            : undefined,
+        head: seo.enabled || googleAnalyticsMeasurementId || posthogApiKey
+            ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
+            : undefined,
+        themeSelect: themesEnabled ? packageFile('ThemeSelect.astro') : undefined,
+    };
+    const serializedOptions = {
+        promotoEnabled,
+        hagicodePromotionEnabled,
+        hagicodePromotionRandomAvatar,
+        footerAvatar,
+        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: {
+            'config:setup'({ astroConfig, 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 (notFoundPageEnabled && config.components?.Hero) {
+                    throw new Error('Hagilight cannot replace an existing Starlight Hero override. Set notFoundPage: { enabled: false } to keep it, or compose @hagicode/hagilight-starlight/NotFoundHero directly.');
+                }
+                if (config.components?.Footer) {
+                    throw new Error('Hagilight cannot replace an existing Starlight Footer override.');
+                }
+                if (pageTitleEnabled && config.components?.PageTitle) {
+                    throw new Error('Hagilight cannot replace an existing Starlight PageTitle override. Set contentComponents: { pageTitle: false } and compose @hagicode/hagilight-starlight/ContentLayoutToggle into your PageTitle component.');
+                }
+                if (markdownContentEnabled && config.components?.MarkdownContent) {
+                    throw new Error('Hagilight cannot replace an existing Starlight MarkdownContent override. Set contentComponents: { markdownContent: false } and compose @hagicode/hagilight-starlight/MarkdownContent into your MarkdownContent component.');
+                }
+                if (themesEnabled && config.components?.ThemeSelect) {
+                    throw new Error('Hagilight cannot replace an existing Starlight ThemeSelect override. Set themes: { enabled: false } to keep it, or compose @hagicode/hagilight-starlight/ThemeSelect into your component.');
+                }
+                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 }, 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 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 = [];
+                let defaultSeoLocale = 'root';
+                if (seo.enabled) {
+                    seoSite = resolveAstroSite(astroConfig.site);
+                    seoLocales = resolveSeoLocales(config.locales);
+                    defaultSeoLocale = resolveDefaultSeoLocale(config.defaultLocale, seoLocales);
+                }
+                const basePath = astroConfig.base ?? '/';
+                serializedOptions.seoSite = seoSite;
+                serializedOptions.seoBasePath = basePath;
+                serializedOptions.seoLocales = seoLocales;
+                serializedOptions.seoDefaultLocale = defaultSeoLocale;
+                serializedOptions.seoFormat = astroConfig.build?.format ?? 'directory';
+                serializedOptions.seoTrailingSlash = astroConfig.trailingSlash ?? 'ignore';
+                serializedOptions.seo = seo.enabled
+                    ? {
+                        ...seo,
+                        ...(seo.image === undefined
+                            ? {}
+                            : { image: resolveSeoImageUrl(seo.image, { site: seoSite, basePath }) }),
+                        ...(seo.organization === undefined
+                            ? {}
+                            : {
+                                organization: {
+                                    ...seo.organization,
+                                    ...(seo.organization.logo === undefined
+                                        ? {}
+                                        : { logo: resolveSeoImageUrl(seo.organization.logo, { site: seoSite, basePath }) }),
+                                },
+                            }),
+                    }
+                    : seo;
+                serializedOptions.consumerHead = config.head ?? [];
+                const generateRss = rssEnabled && !getRssFeedUrl(config);
+                if (generateRss && !astroConfig.site) {
+                    throw new Error('Hagilight RSS requires the Astro site option. Set site or disable RSS with rss: { enabled: false }.');
+                }
+                const rssLocales = generateRss ? resolveRssLocales(config.locales) : [];
+                const baseUrl = generateRss
+                    ? new URL((astroConfig.base ?? '/').replace(/\/?$/u, '/'), astroConfig.site)
+                    : undefined;
+                const rssFeedUrl = baseUrl ? new URL('rss.xml', baseUrl).toString() : undefined;
+                const rssLocaleFeedUrls = baseUrl
+                    ? Object.fromEntries(rssLocales
+                        .filter(({ filename }) => filename !== 'en')
+                        .map(({ lang, filename }) => [
+                        lang,
+                        new URL(`rss.${filename}.xml`, baseUrl).toString(),
+                    ]))
+                    : {};
+                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: [
+                        ...(config.customCss ?? []),
+                        contentWidthCssPath,
+                        ...(themesEnabled ? [themesCssPath] : []),
+                    ],
+                    head: [
+                        ...(config.head ?? []),
+                        ...(rssFeedUrl ? [{
+                                tag: 'link',
+                                attrs: { rel: 'alternate', type: 'application/rss+xml', href: rssFeedUrl },
+                            }] : []),
+                        { tag: 'script', content: contentWidthHeadScript },
+                        ...(themesEnabled ? [{ tag: 'script', content: THEME_BOOTSTRAP }] : []),
+                        ...(() => {
+                            const entry = resolveFaviconHeadEntry(config.head, config.favicon === undefined ? {} : { href: config.favicon });
+                            return entry ? [entry] : [];
+                        })(),
+                    ],
+                    components: {
+                        ...config.components,
+                        ...(componentIds.header ? { Header: componentIds.header } : {}),
+                        ...(componentIds.hero ? { Hero: componentIds.hero } : {}),
+                        Footer: componentIds.footer,
+                        ...(componentIds.pageTitle ? { PageTitle: componentIds.pageTitle } : {}),
+                        ...(componentIds.markdownContent ? { MarkdownContent: componentIds.markdownContent } : {}),
+                        ...(componentIds.head ? { Head: componentIds.head } : {}),
+                        ...(componentIds.themeSelect ? { ThemeSelect: componentIds.themeSelect } : {}),
+                    },
+                });
+            },
+        },
+    };
+}

package/dist/language-routing.d.ts

@@ -0,0 +1,18 @@
+import type { TrailingSlash } from './not-found.js';
+export interface LanguageOption {
+    code: string;
+    label: string;
+    lang: string;
+}
+export interface ConfiguredLanguageOption extends LanguageOption {
+    selected: boolean;
+}
+export type ConfiguredLocales = Readonly<Record<string, string | {
+    label?: string;
+    lang?: string;
+} | undefined>>;
+export declare const DEFAULT_LANGUAGE_OPTIONS: readonly LanguageOption[];
+export declare function getConfiguredLanguageOptions(configuredLocales: ConfiguredLocales | undefined, currentLocale: string | undefined): ConfiguredLanguageOption[];
+export declare function getKeyboardTargetIndex(index: number, key: string, count: number): number;
+export declare function buildLocaleNavigationTarget(currentUrl: string | URL, targetLocale: string, configuredLocales: readonly string[], basePath?: string, trailingSlash?: TrailingSlash): URL;
+export declare function persistStarlightLocaleSelection(locale: string): void;