@hagicode/hagilight-starlight 0.3.2-dev.55.1.1e29eba → 0.3.2-dev.57.1.ee1f17e

package/dist/index.js

@@ -0,0 +1,490 @@
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { resolveFaviconHeadEntry } from '@hagicode/hagilight-core/favicon';
+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 { resolveRssOptions } from './rss-utils.js';
+import { resolveSeoLocales } from './seo-utils.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 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 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 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) {
+    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 />' : '';
+    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}
+/>
+${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}
+><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'))};
+import options from '${optionsId}';
+const isNotFound = /(?:^|\\/)404(?:\\.html)?\\/?$/u.test(Astro.url.pathname);
+---
+
+{options.seoEnabled ? <SEOHead options={options} /> : <DefaultHead />}
+{!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]] : []),
+    ]);
+    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,
+                })};`;
+            }
+            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'({ injectRoute, updateConfig }) {
+                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,
+                    });
+                }
+                updateConfig({ vite: { plugins: [vitePlugin] } });
+            },
+            'astro:config:done'() {
+                unregisterRssOwner();
+            },
+        },
+    };
+}
+/** 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 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 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 promoto = optionalRecord(input.promoto, 'promoto');
+    const promotoEnabled = optionalBoolean(promoto, 'enabled', 'promoto 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
+            ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
+            : undefined,
+    };
+    const serializedOptions = {
+        promotoEnabled,
+        hagicodePromotionEnabled,
+        links: options.links ?? {},
+        googleAnalyticsMeasurementId,
+        fiftyOneLaId,
+        aiDisclosures,
+        seoEnabled: seo.enabled,
+        seo,
+    };
+    const unregisterRssOwner = registerStarlightRssOwner(rssEnabled);
+    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 (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 Google Analytics cannot replace an existing Starlight Head override. Disable Google Analytics or compose @hagicode/hagilight-core/GoogleAnalytics in your Head instead.');
+                }
+                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));
+                updateConfig({
+                    ...(config.logo === undefined ? { logo: { src: defaultLogo, alt: 'HagiCode' } } : {}),
+                    customCss: [...(config.customCss ?? []), contentWidthCssPath],
+                    head: [
+                        ...(config.head ?? []),
+                        ...(rssFeedUrl ? [{
+                                tag: 'link',
+                                attrs: { rel: 'alternate', type: 'application/rss+xml', href: rssFeedUrl },
+                            }] : []),
+                        { tag: 'script', content: contentWidthHeadScript },
+                        ...(() => {
+                            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 } : {}),
+                    },
+                });
+            },
+        },
+    };
+}

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;

package/dist/language-routing.js

@@ -0,0 +1,95 @@
+import { locales } from './locales.js';
+export const DEFAULT_LANGUAGE_OPTIONS = Object.entries(locales).map(([code, locale]) => ({
+    code,
+    label: locale.label,
+    lang: locale.lang,
+}));
+const normalizeLang = (lang) => lang?.replaceAll('_', '-').toLowerCase();
+export function getConfiguredLanguageOptions(configuredLocales, currentLocale) {
+    const catalog = DEFAULT_LANGUAGE_OPTIONS;
+    return Object.entries(configuredLocales ?? {})
+        .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: _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/dist/locales.d.ts

@@ -0,0 +1,48 @@
+export interface LocaleDefinition {
+    label: string;
+    lang: string;
+}
+/** Starlight `locales` map for every language HagiCode documentation publishes. */
+export declare const locales: {
+    readonly root: {
+        readonly label: "English";
+        readonly lang: "en-US";
+    };
+    readonly 'zh-CN': {
+        readonly label: "简体中文";
+        readonly lang: "zh-CN";
+    };
+    readonly 'zh-Hant': {
+        readonly label: "繁體中文";
+        readonly lang: "zh-Hant";
+    };
+    readonly 'fr-FR': {
+        readonly label: "Français";
+        readonly lang: "fr-FR";
+    };
+    readonly 'de-DE': {
+        readonly label: "Deutsch";
+        readonly lang: "de-DE";
+    };
+    readonly 'es-ES': {
+        readonly label: "Español (España)";
+        readonly lang: "es-ES";
+    };
+    readonly 'ja-JP': {
+        readonly label: "日本語";
+        readonly lang: "ja-JP";
+    };
+    readonly 'ko-KR': {
+        readonly label: "한국어";
+        readonly lang: "ko-KR";
+    };
+    readonly 'pt-BR': {
+        readonly label: "Português (Brasil)";
+        readonly lang: "pt-BR";
+    };
+    readonly 'ru-RU': {
+        readonly label: "Русский";
+        readonly lang: "ru-RU";
+    };
+};
+export type HagicodeLocaleKey = keyof typeof locales;

package/dist/locales.js

@@ -0,0 +1,13 @@
+/** Starlight `locales` map for every language HagiCode documentation publishes. */
+export const locales = {
+    root: { label: 'English', lang: 'en-US' },
+    'zh-CN': { label: '简体中文', lang: 'zh-CN' },
+    'zh-Hant': { label: '繁體中文', lang: 'zh-Hant' },
+    'fr-FR': { label: 'Français', lang: 'fr-FR' },
+    'de-DE': { label: 'Deutsch', lang: 'de-DE' },
+    'es-ES': { label: 'Español (España)', lang: 'es-ES' },
+    'ja-JP': { label: '日本語', lang: 'ja-JP' },
+    'ko-KR': { label: '한국어', lang: 'ko-KR' },
+    'pt-BR': { label: 'Português (Brasil)', lang: 'pt-BR' },
+    'ru-RU': { label: 'Русский', lang: 'ru-RU' },
+};

package/dist/not-found.d.ts

@@ -0,0 +1,9 @@
+export type TrailingSlash = 'always' | 'never' | 'ignore';
+export declare function isNotFoundEntry(entryId: string): boolean;
+export interface NotFoundHomeHrefOptions {
+    basePath?: string;
+    locale?: string | undefined;
+    trailingSlash?: TrailingSlash;
+}
+export declare function getNotFoundHomeHref({ basePath, locale, trailingSlash }: NotFoundHomeHrefOptions): string;
+export declare function getNotFoundHomeLabel(lang: string | undefined): string;