@hagicode/hagilight-starlight 0.5.1 → 0.5.2-dev.67.1.00da941

package/README.md

@@ -1,6 +1,6 @@
 # @hagicode/hagilight-starlight
 
-A Starlight plugin for HagiCode documentation sites. Adds a localized header and footer, language chooser, content-width toggle, custom 404 page, SEO metadata, RSS feeds, analytics, and AI-content disclosures.
+A Starlight plugin for HagiCode documentation sites. Adds a localized header and footer, language chooser, content-width toggle, theme picker, custom 404 page, SEO metadata, RSS feeds, analytics, and AI-content disclosures.
 
 ## Install
 
@@ -29,6 +29,14 @@ export default defineConfig({
 
 The plugin also exposes `@hagicode/hagilight-starlight/schema` for optional SEO frontmatter and individual Astro components such as `/Header` and `/MarkdownContent` for custom Starlight overrides. Configure features through the typed `HagilightStarlightOptions` passed to `hagilight()`.
 
+### Theme picker
+
+By default the plugin replaces Starlight's light/dark toggle with a theme picker offering nine choices: the default theme plus the Ocean, Sakura, and Forest themes in light and dark, and a "Default" choice that follows the visitor's system color scheme while a randomly assigned theme (stable per visitor, stored in `localStorage`) provides the palette. Disable it to keep Starlight's built-in toggle or compose `@hagicode/hagilight-starlight/ThemeSelect` yourself:
+
+```js
+hagilight({ themes: { enabled: false } })
+```
+
 The plugin footer and direct `/Footer` and `/PromotoFooter` components append
 the literal `Powered By hagilight-starlight@<version>`. The version comes from
 this package's own manifest at build time, not from Astro or Starlight.

package/ThemeSelect.astro

@@ -0,0 +1,176 @@
+---
+import {
+  applyThemeChoice,
+  getThemePickerLabels,
+  parseThemeChoice,
+  readStoredThemeChoice,
+  type ThemeChoice,
+} from './dist/themes.js';
+
+const { lang } = Astro.locals.starlightRoute;
+const labels = getThemePickerLabels(lang);
+const accessibleLabel = Astro.locals.t('themeSelect.accessibleLabel');
+const lightLabel = Astro.locals.t('themeSelect.light');
+const darkLabel = Astro.locals.t('themeSelect.dark');
+
+/* Inlined copies of Starlight's laptop, sun, moon, and down-caret icons; the Starlight
+ * Icon component is not part of the package's public exports. */
+const icons = {
+  laptop: `<path d="M21 14h-1V7a3 3 0 0 0-3-3H7a3 3 0 0 0-3 3v7H3a1 1 0 0 0-1 1v2a3 3 0 0 0 3 3h14a3 3 0 0 0 3-3v-2a1 1 0 0 0-1-1ZM6 7a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v7H6V7Zm14 10a1 1 0 0 1-1 1H5a1 1 0 0 1-1-1v-1h16v1Z"/>`,
+  sun: `<path d="M5 12a1 1 0 0 0-1-1H3a1 1 0 0 0 0 2h1a1 1 0 0 0 1-1Zm.64 5-.71.71a1 1 0 0 0 0 1.41 1 1 0 0 0 1.41 0l.71-.71A1 1 0 0 0 5.64 17ZM12 5a1 1 0 0 0 1-1V3a1 1 0 0 0-2 0v1a1 1 0 0 0 1 1Zm5.66 2.34a1 1 0 0 0 .7-.29l.71-.71a1 1 0 1 0-1.41-1.41l-.66.71a1 1 0 0 0 0 1.41 1 1 0 0 0 .66.29Zm-12-.29a1 1 0 0 0 1.41 0 1 1 0 0 0 0-1.41l-.71-.71a1.004 1.004 0 1 0-1.43 1.41l.73.71ZM21 11h-1a1 1 0 0 0 0 2h1a1 1 0 0 0 0-2Zm-2.64 6A1 1 0 0 0 17 18.36l.71.71a1 1 0 0 0 1.41 0 1 1 0 0 0 0-1.41l-.76-.66ZM12 6.5a5.5 5.5 0 1 0 5.5 5.5A5.51 5.51 0 0 0 12 6.5Zm0 9a3.5 3.5 0 1 1 0-7 3.5 3.5 0 0 1 0 7Zm0 3.5a1 1 0 0 0-1 1v1a1 1 0 0 0 2 0v-1a1 1 0 0 0-1-1Z"/>`,
+  moon: `<path d="M21.64 13a1 1 0 0 0-1.05-.14 8.049 8.049 0 0 1-3.37.73 8.15 8.15 0 0 1-8.14-8.1 8.59 8.59 0 0 1 .25-2A1 1 0 0 0 8 2.36a10.14 10.14 0 1 0 14 11.69 1 1 0 0 0-.36-1.05Zm-9.5 6.69A8.14 8.14 0 0 1 7.08 5.22v.27a10.15 10.15 0 0 0 10.14 10.14 9.784 9.784 0 0 0 2.1-.22 8.11 8.11 0 0 1-7.18 4.32v-.04Z"/>`,
+  caret: `<path d="M17 9.17a1 1 0 0 0-1.41 0L12 12.71 8.46 9.17a1 1 0 1 0-1.41 1.42l4.24 4.24a1.002 1.002 0 0 0 1.42 0L17 10.59a1.002 1.002 0 0 0 0-1.42Z"/>`,
+};
+
+const groups = [
+  {
+    label: labels.defaultThemeGroup,
+    prefix: labels.defaultOption,
+    choices: ['default-light', 'default-dark'],
+  },
+  {
+    label: labels.themes.ocean,
+    prefix: labels.themes.ocean,
+    choices: ['ocean-light', 'ocean-dark'],
+  },
+  {
+    label: labels.themes.sakura,
+    prefix: labels.themes.sakura,
+    choices: ['sakura-light', 'sakura-dark'],
+  },
+  {
+    label: labels.themes.forest,
+    prefix: labels.themes.forest,
+    choices: ['forest-light', 'forest-dark'],
+  },
+] as const satisfies ReadonlyArray<{
+  label: string;
+  prefix: string;
+  choices: readonly ThemeChoice[];
+}>;
+
+const groupOptionLabel = (prefix: string, choice: ThemeChoice): string =>
+  `${prefix} · ${choice.endsWith('-light') ? lightLabel : darkLabel}`;
+---
+
+<hagilight-theme-select class="theme-picker">
+  <label style="--sl-select-width: 12.5em">
+    <span class="sr-only">{accessibleLabel}</span>
+    <svg class="icon label-icon" aria-hidden="true" viewBox="0 0 24 24" fill="currentColor" set:html={icons.laptop} />
+    <select autocomplete="off">
+      <option value="default" selected>{labels.defaultOption}</option>
+      {groups.map((group) => (
+        <optgroup label={group.label}>
+          {group.choices.map((choice) => (
+            <option value={choice}>{groupOptionLabel(group.prefix, choice)}</option>
+          ))}
+        </optgroup>
+      ))}
+    </select>
+    <svg class="icon caret" aria-hidden="true" viewBox="0 0 24 24" fill="currentColor" set:html={icons.caret} />
+  </label>
+  <template class="mode-icons">
+    <svg class="mode-auto" aria-hidden="true" viewBox="0 0 24 24" fill="currentColor" set:html={icons.laptop} />
+    <svg class="mode-light" aria-hidden="true" viewBox="0 0 24 24" fill="currentColor" set:html={icons.sun} />
+    <svg class="mode-dark" aria-hidden="true" viewBox="0 0 24 24" fill="currentColor" set:html={icons.moon} />
+  </template>
+</hagilight-theme-select>
+
+<script>
+  import { applyThemeChoice, parseThemeChoice, readStoredThemeChoice, type ThemeChoice } from './dist/themes.js';
+
+  const modeClass = (choice: ThemeChoice): string =>
+    choice.endsWith('-light') ? 'mode-light' : choice.endsWith('-dark') ? 'mode-dark' : 'mode-auto';
+
+  class HagilightThemeSelect extends HTMLElement {
+    connectedCallback() {
+      if (this.dataset.initialized) return;
+      this.dataset.initialized = 'true';
+
+      const select = this.querySelector('select');
+      if (!(select instanceof HTMLSelectElement)) return;
+
+      const sync = (choice: ThemeChoice) => {
+        select.value = choice;
+        const icon = this.querySelector('svg.label-icon');
+        const next = this.querySelector('template.mode-icons')?.content.querySelector(`.${modeClass(choice)}`);
+        if (icon && next) icon.replaceChildren(...next.cloneNode(true).childNodes);
+      };
+
+      sync(readStoredThemeChoice());
+
+      select.addEventListener('change', () => {
+        const choice = parseThemeChoice(select.value);
+        applyThemeChoice(choice);
+        sync(choice);
+      });
+
+      matchMedia('(prefers-color-scheme: light)').addEventListener('change', (event) => {
+        if (readStoredThemeChoice() !== 'default') return;
+        document.documentElement.dataset.theme = event.matches ? 'light' : 'dark';
+      });
+    }
+  }
+
+  if (!customElements.get('hagilight-theme-select')) {
+    customElements.define('hagilight-theme-select', HagilightThemeSelect);
+  }
+</script>
+
+<style>
+  .theme-picker {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    color: var(--sl-color-gray-2);
+  }
+
+  .theme-picker:hover {
+    color: var(--sl-color-white);
+  }
+
+  .theme-picker .icon {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 1em;
+    height: 1em;
+    pointer-events: none;
+  }
+
+  .theme-picker select {
+    width: calc(var(--sl-select-width) + 1rem);
+    border: 0;
+    margin-inline: -0.5rem;
+    padding-block: 0.625rem;
+    padding-inline: calc(0.875rem + 0.75rem) calc(1.25rem + 0.75rem);
+    background-color: transparent;
+    color: inherit;
+    cursor: pointer;
+    text-overflow: ellipsis;
+    appearance: none;
+  }
+
+  .theme-picker option,
+  .theme-picker optgroup {
+    background-color: var(--sl-color-bg-nav);
+    color: var(--sl-color-gray-1);
+  }
+
+  .theme-picker .label-icon {
+    inset-inline-start: 0;
+    font-size: 0.875rem;
+  }
+
+  .theme-picker .caret {
+    inset-inline-end: 0;
+    font-size: 1.25rem;
+  }
+
+  @media (min-width: 50rem) {
+    .theme-picker select {
+      font-size: var(--sl-text-sm);
+    }
+  }
+</style>

package/dist/index.d.ts

@@ -34,6 +34,15 @@ export interface HagilightRssOptions extends RssContentOptions {
     /** Generate `/rss.xml` and localized feeds. Defaults to `true`; requires Astro `site`. */
     enabled?: boolean;
 }
+export interface HagilightThemesOptions {
+    /**
+     * Replace Starlight's light/dark picker with the Hagilight theme picker: four themes
+     * (the default plus Ocean, Sakura, and Forest) in light and dark, plus a "default"
+     * choice that assigns first-visit users one of the extra themes at random.
+     * Defaults to `true`.
+     */
+    enabled?: boolean;
+}
 export interface HagilightContentComponentsOptions {
     pageTitle?: boolean;
     markdownContent?: boolean;
@@ -47,6 +56,8 @@ export interface HagilightStarlightOptions {
     seo?: HagilightSeoOptions;
     contentComponents?: HagilightContentComponentsOptions;
     aiDisclosures?: HagilightAIDisclosureOptions;
+    /** Theme picker with three extra light/dark themes plus a randomized first-visit default. */
+    themes?: HagilightThemesOptions;
     /** End-of-article HagiCode introduction. */
     hagicodePromotion?: HagilightToggleOptions;
     /** Floating promotion banner rendered after the footer. */

package/dist/index.js

@@ -6,6 +6,7 @@ import { RSS_OWNER, registerStarlightRssOwner, } from '@hagicode/hagilight-core/
 import { isValidSeoImageReference, resolveSeoImageUrl } from '@hagicode/hagilight-core/seo';
 import { resolveRssOptions } from './rss-utils.js';
 import { resolveSeoLocales } from './seo-utils.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}`));
@@ -32,6 +33,7 @@ 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 {
@@ -336,6 +338,8 @@ export default function hagilight(options = {}) {
     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);
@@ -370,6 +374,7 @@ export default function hagilight(options = {}) {
         head: seo.enabled || googleAnalyticsMeasurementId
             ? `virtual:hagilight-starlight/${instanceId}/Head.astro`
             : undefined,
+        themeSelect: themesEnabled ? packageFile('ThemeSelect.astro') : undefined,
     };
     const serializedOptions = {
         promotoEnabled,
@@ -401,6 +406,9 @@ export default function hagilight(options = {}) {
                 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 } and disable Google Analytics to keep your Head, or compose your site metadata explicitly.');
@@ -461,7 +469,11 @@ export default function hagilight(options = {}) {
                 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],
+                    customCss: [
+                        ...(config.customCss ?? []),
+                        contentWidthCssPath,
+                        ...(themesEnabled ? [themesCssPath] : []),
+                    ],
                     head: [
                         ...(config.head ?? []),
                         ...(rssFeedUrl ? [{
@@ -469,6 +481,7 @@ export default function hagilight(options = {}) {
                                 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] : [];
@@ -482,6 +495,7 @@ export default function hagilight(options = {}) {
                         ...(componentIds.pageTitle ? { PageTitle: componentIds.pageTitle } : {}),
                         ...(componentIds.markdownContent ? { MarkdownContent: componentIds.markdownContent } : {}),
                         ...(componentIds.head ? { Head: componentIds.head } : {}),
+                        ...(componentIds.themeSelect ? { ThemeSelect: componentIds.themeSelect } : {}),
                     },
                 });
             },

package/dist/themes.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Hagilight theme picker: four themes (the Starlight default plus Ocean, Sakura, and Forest),
+ * each with a light and a dark appearance, plus a "default" choice that applies the site
+ * default experience. The palette in use is exposed to CSS through the
+ * `data-hagilight-theme` attribute on `<html>`; light/dark mode keeps using Starlight's
+ * `data-theme` attribute and `starlight-theme` storage so Starlight's pre-paint script
+ * continues to apply the correct mode.
+ */
+export type ThemeId = 'default' | 'ocean' | 'sakura' | 'forest';
+export type ThemeMode = 'light' | 'dark';
+export type ThemeChoice = 'default' | 'default-light' | 'default-dark' | 'ocean-light' | 'ocean-dark' | 'sakura-light' | 'sakura-dark' | 'forest-light' | 'forest-dark';
+/** Themes a first-visit user is randomly assigned while the "default" choice is selected. */
+export declare const RANDOM_THEME_IDS: readonly ["ocean", "sakura", "forest"];
+export declare const DEFAULT_THEME_CHOICE: ThemeChoice;
+export declare const THEME_CHOICES: readonly ["default", "default-light", "default-dark", "ocean-light", "ocean-dark", "sakura-light", "sakura-dark", "forest-light", "forest-dark"];
+export declare const THEME_STORAGE_KEY = "hagilight-theme";
+export declare const RANDOM_THEME_STORAGE_KEY = "hagilight-theme-random";
+/** Starlight's own storage key; kept in sync with the picker so its pre-paint script applies the right mode. */
+export declare const STARLIGHT_THEME_STORAGE_KEY = "starlight-theme";
+export declare function parseThemeChoice(value: unknown): ThemeChoice;
+export declare function splitThemeChoice(choice: ThemeChoice): {
+    themeId: ThemeId;
+    mode?: ThemeMode;
+};
+/** The theme randomly assigned to this user, picking and persisting one on the first visit. */
+export declare function assignedRandomThemeId(): ThemeId;
+/** The theme id a choice renders as: the theme itself, or the user's random assignment for "default". */
+export declare function resolveThemeId(choice: ThemeChoice): ThemeId;
+export declare function readStoredThemeChoice(): ThemeChoice;
+/** Apply a choice to the document, persist it, and keep Starlight's mode storage in sync. */
+export declare function applyThemeChoice(choice: ThemeChoice, root?: HTMLElement): void;
+/**
+ * Inline pre-paint bootstrap run from `<head>`: it must stay dependency-free because it
+ * executes before any module script. Keep the behavior identical to `applyThemeChoice`.
+ */
+export declare const THEME_BOOTSTRAP: string;
+export interface ThemePickerLabels {
+    /** Label of the "default" choice: site default experience with an automatically assigned theme. */
+    defaultOption: string;
+    /** Label of the option group holding the built-in theme's light and dark appearances. */
+    defaultThemeGroup: string;
+    themes: Record<Exclude<ThemeId, 'default'>, string>;
+}
+export declare function getThemePickerLabels(lang: string | undefined): ThemePickerLabels;

package/dist/themes.js

@@ -0,0 +1,181 @@
+/**
+ * Hagilight theme picker: four themes (the Starlight default plus Ocean, Sakura, and Forest),
+ * each with a light and a dark appearance, plus a "default" choice that applies the site
+ * default experience. The palette in use is exposed to CSS through the
+ * `data-hagilight-theme` attribute on `<html>`; light/dark mode keeps using Starlight's
+ * `data-theme` attribute and `starlight-theme` storage so Starlight's pre-paint script
+ * continues to apply the correct mode.
+ */
+/** Themes a first-visit user is randomly assigned while the "default" choice is selected. */
+export const RANDOM_THEME_IDS = ['ocean', 'sakura', 'forest'];
+export const DEFAULT_THEME_CHOICE = 'default';
+export const THEME_CHOICES = [
+    'default',
+    'default-light',
+    'default-dark',
+    'ocean-light',
+    'ocean-dark',
+    'sakura-light',
+    'sakura-dark',
+    'forest-light',
+    'forest-dark',
+];
+export const THEME_STORAGE_KEY = 'hagilight-theme';
+export const RANDOM_THEME_STORAGE_KEY = 'hagilight-theme-random';
+/** Starlight's own storage key; kept in sync with the picker so its pre-paint script applies the right mode. */
+export const STARLIGHT_THEME_STORAGE_KEY = 'starlight-theme';
+const RANDOM_THEME_ID_SET = new Set(RANDOM_THEME_IDS);
+const THEME_CHOICE_SET = new Set(THEME_CHOICES);
+export function parseThemeChoice(value) {
+    return THEME_CHOICE_SET.has(value) ? value : DEFAULT_THEME_CHOICE;
+}
+export function splitThemeChoice(choice) {
+    if (choice === DEFAULT_THEME_CHOICE)
+        return { themeId: 'default' };
+    const separator = choice.lastIndexOf('-');
+    return {
+        themeId: choice.slice(0, separator),
+        mode: choice.slice(separator + 1),
+    };
+}
+function readStorage(key) {
+    try {
+        return globalThis.localStorage?.getItem(key) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeStorage(key, value) {
+    try {
+        globalThis.localStorage?.setItem(key, value);
+    }
+    catch {
+        return;
+    }
+}
+/** The theme randomly assigned to this user, picking and persisting one on the first visit. */
+export function assignedRandomThemeId() {
+    let stored = readStorage(RANDOM_THEME_STORAGE_KEY);
+    if (stored === null || !RANDOM_THEME_ID_SET.has(stored)) {
+        stored = RANDOM_THEME_IDS[Math.floor(Math.random() * RANDOM_THEME_IDS.length)];
+        writeStorage(RANDOM_THEME_STORAGE_KEY, stored);
+    }
+    return stored;
+}
+/** The theme id a choice renders as: the theme itself, or the user's random assignment for "default". */
+export function resolveThemeId(choice) {
+    const { themeId, mode } = splitThemeChoice(choice);
+    return mode === undefined ? assignedRandomThemeId() : themeId;
+}
+export function readStoredThemeChoice() {
+    return parseThemeChoice(readStorage(THEME_STORAGE_KEY));
+}
+/** Apply a choice to the document, persist it, and keep Starlight's mode storage in sync. */
+export function applyThemeChoice(choice, root = document.documentElement) {
+    const { mode } = splitThemeChoice(choice);
+    root.dataset.hagilightTheme = resolveThemeId(choice);
+    if (mode !== undefined)
+        root.dataset.theme = mode;
+    writeStorage(THEME_STORAGE_KEY, choice);
+    writeStorage(STARLIGHT_THEME_STORAGE_KEY, mode ?? '');
+}
+/**
+ * Inline pre-paint bootstrap run from `<head>`: it must stay dependency-free because it
+ * executes before any module script. Keep the behavior identical to `applyThemeChoice`.
+ */
+export const THEME_BOOTSTRAP = `(function () {
+  var choices = ${JSON.stringify(THEME_CHOICES)};
+  var randomThemes = ${JSON.stringify(RANDOM_THEME_IDS)};
+  var choiceKey = ${JSON.stringify(THEME_STORAGE_KEY)};
+  var randomKey = ${JSON.stringify(RANDOM_THEME_STORAGE_KEY)};
+  var choice = 'default';
+  try {
+    var stored = localStorage.getItem(choiceKey);
+    if (choices.includes(stored)) choice = stored;
+  } catch (error) {}
+  var themeId;
+  if (choice === 'default') {
+    try {
+      themeId = localStorage.getItem(randomKey);
+      if (!randomThemes.includes(themeId)) themeId = null;
+    } catch (error) {
+      themeId = null;
+    }
+    if (!themeId) {
+      themeId = randomThemes[Math.floor(Math.random() * randomThemes.length)];
+      try {
+        localStorage.setItem(randomKey, themeId);
+      } catch (error) {}
+    }
+  } else {
+    themeId = choice.slice(0, choice.lastIndexOf('-'));
+  }
+  document.documentElement.dataset.hagilightTheme = themeId;
+})();`;
+const labels = {
+    'de-de': {
+        defaultOption: 'Standard',
+        defaultThemeGroup: 'Standard-Design',
+        themes: { ocean: 'Ozean', sakura: 'Sakura', forest: 'Wald' },
+    },
+    'en-us': {
+        defaultOption: 'Default',
+        defaultThemeGroup: 'Default theme',
+        themes: { ocean: 'Ocean', sakura: 'Sakura', forest: 'Forest' },
+    },
+    'es-es': {
+        defaultOption: 'Predeterminado',
+        defaultThemeGroup: 'Tema predeterminado',
+        themes: { ocean: 'Océano', sakura: 'Sakura', forest: 'Bosque' },
+    },
+    'fr-fr': {
+        defaultOption: 'Par défaut',
+        defaultThemeGroup: 'Thème par défaut',
+        themes: { ocean: 'Océan', sakura: 'Sakura', forest: 'Forêt' },
+    },
+    'ja-jp': {
+        defaultOption: 'デフォルト',
+        defaultThemeGroup: 'デフォルトテーマ',
+        themes: { ocean: '海', sakura: '桜', forest: '森' },
+    },
+    'ko-kr': {
+        defaultOption: '기본값',
+        defaultThemeGroup: '기본 테마',
+        themes: { ocean: '바다', sakura: '벚꽃', forest: '숲' },
+    },
+    'pt-br': {
+        defaultOption: 'Padrão',
+        defaultThemeGroup: 'Tema padrão',
+        themes: { ocean: 'Oceano', sakura: 'Sakura', forest: 'Floresta' },
+    },
+    'ru-ru': {
+        defaultOption: 'По умолчанию',
+        defaultThemeGroup: 'Стандартная тема',
+        themes: { ocean: 'Океан', sakura: 'Сакура', forest: 'Лес' },
+    },
+    'zh-cn': {
+        defaultOption: '默认',
+        defaultThemeGroup: '默认主题',
+        themes: { ocean: '海洋', sakura: '樱花', forest: '森林' },
+    },
+    'zh-hant': {
+        defaultOption: '預設',
+        defaultThemeGroup: '預設主題',
+        themes: { ocean: '海洋', sakura: '櫻花', forest: '森林' },
+    },
+};
+const enLabels = labels['en-us'];
+export function getThemePickerLabels(lang) {
+    if (lang !== undefined) {
+        const key = lang.toLowerCase();
+        const exact = labels[key];
+        if (exact)
+            return exact;
+        const prefix = key.split('-')[0];
+        const prefixed = Object.entries(labels).find(([id]) => id.split('-')[0] === prefix);
+        if (prefixed)
+            return prefixed[1];
+    }
+    return enLabels;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.5.1",
+  "version": "0.5.2-dev.67.1.00da941",
   "type": "module",
   "description": "Starlight plugin and components for HagiCode documentation",
   "repository": {
@@ -30,6 +30,7 @@
       "default": "./dist/schema.js"
     },
     "./ContentLayoutToggle": "./ContentLayoutToggle.astro",
+    "./ThemeSelect": "./ThemeSelect.astro",
     "./Header": "./Header.astro",
     "./Footer": "./Footer.astro",
     "./MarkdownContent": "./MarkdownContent.astro",
@@ -48,7 +49,7 @@
     "assets/*.png"
   ],
   "dependencies": {
-    "@hagicode/hagilight-core": "0.5.1"
+    "@hagicode/hagilight-core": "0.5.2-dev.67.1.00da941"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",

package/themes.css

@@ -0,0 +1,160 @@
+/*
+ * Hagilight extra themes: Ocean, Sakura, and Forest. Each theme overrides Starlight's
+ * color custom properties for its dark and light appearance. The applied theme is exposed
+ * through `data-hagilight-theme` on `<html>` by the theme picker's pre-paint bootstrap
+ * script, while light/dark mode keeps using Starlight's `data-theme` attribute.
+ *
+ * Starlight's dark palette is the `:root` default, so dark overrides must exclude the light
+ * mode with `:not([data-theme='light'])`; otherwise they would out-specify the light palette
+ * because custom CSS loads after Starlight's own styles.
+ */
+
+/* Ocean — cool blue accent. */
+:root[data-hagilight-theme='ocean']:not([data-theme='light']),
+:root[data-hagilight-theme='ocean']:not([data-theme='light']) ::backdrop {
+  --sl-color-white: hsl(0, 0%, 100%);
+  --sl-color-gray-1: hsl(212, 24%, 94%);
+  --sl-color-gray-2: hsl(212, 12%, 77%);
+  --sl-color-gray-3: hsl(212, 10%, 56%);
+  --sl-color-gray-4: hsl(212, 10%, 36%);
+  --sl-color-gray-5: hsl(212, 14%, 23%);
+  --sl-color-gray-6: hsl(212, 18%, 16%);
+  --sl-color-black: hsl(212, 20%, 10%);
+
+  --sl-hue-orange: 25;
+  --sl-hue-green: 160;
+  --sl-hue-blue: 206;
+  --sl-hue-purple: 265;
+  --sl-hue-red: 355;
+
+  --sl-color-accent-low: hsl(212, 64%, 22%);
+  --sl-color-accent: hsl(206, 100%, 63%);
+  --sl-color-accent-high: hsl(205, 100%, 84%);
+
+  --sl-color-backdrop-overlay: hsla(212, 40%, 8%, 0.66);
+}
+
+:root[data-hagilight-theme='ocean'][data-theme='light'],
+:root[data-hagilight-theme='ocean'][data-theme='light'] ::backdrop {
+  --sl-color-white: hsl(212, 24%, 10%);
+  --sl-color-gray-1: hsl(212, 18%, 16%);
+  --sl-color-gray-2: hsl(212, 12%, 23%);
+  --sl-color-gray-3: hsl(212, 10%, 36%);
+  --sl-color-gray-4: hsl(212, 8%, 56%);
+  --sl-color-gray-5: hsl(212, 10%, 77%);
+  --sl-color-gray-6: hsl(212, 26%, 94%);
+  --sl-color-gray-7: hsl(212, 32%, 97%);
+  --sl-color-black: hsl(0, 0%, 100%);
+
+  --sl-hue-orange: 25;
+  --sl-hue-green: 160;
+  --sl-hue-blue: 206;
+  --sl-hue-purple: 265;
+  --sl-hue-red: 355;
+
+  --sl-color-accent-high: hsl(211, 80%, 30%);
+  --sl-color-accent: hsl(206, 90%, 42%);
+  --sl-color-accent-low: hsl(206, 88%, 90%);
+
+  --sl-color-backdrop-overlay: hsla(212, 30%, 35%, 0.66);
+}
+
+/* Sakura — rose accent with warm neutrals. */
+:root[data-hagilight-theme='sakura']:not([data-theme='light']),
+:root[data-hagilight-theme='sakura']:not([data-theme='light']) ::backdrop {
+  --sl-color-white: hsl(0, 0%, 100%);
+  --sl-color-gray-1: hsl(340, 24%, 94%);
+  --sl-color-gray-2: hsl(340, 12%, 77%);
+  --sl-color-gray-3: hsl(340, 10%, 56%);
+  --sl-color-gray-4: hsl(340, 10%, 36%);
+  --sl-color-gray-5: hsl(340, 14%, 23%);
+  --sl-color-gray-6: hsl(340, 18%, 16%);
+  --sl-color-black: hsl(340, 20%, 10%);
+
+  --sl-hue-orange: 20;
+  --sl-hue-green: 145;
+  --sl-hue-blue: 230;
+  --sl-hue-purple: 285;
+  --sl-hue-red: 350;
+
+  --sl-color-accent-low: hsl(338, 60%, 22%);
+  --sl-color-accent: hsl(340, 85%, 70%);
+  --sl-color-accent-high: hsl(340, 100%, 88%);
+
+  --sl-color-backdrop-overlay: hsla(340, 40%, 8%, 0.66);
+}
+
+:root[data-hagilight-theme='sakura'][data-theme='light'],
+:root[data-hagilight-theme='sakura'][data-theme='light'] ::backdrop {
+  --sl-color-white: hsl(340, 24%, 10%);
+  --sl-color-gray-1: hsl(340, 18%, 16%);
+  --sl-color-gray-2: hsl(340, 12%, 23%);
+  --sl-color-gray-3: hsl(340, 10%, 36%);
+  --sl-color-gray-4: hsl(340, 8%, 56%);
+  --sl-color-gray-5: hsl(340, 10%, 77%);
+  --sl-color-gray-6: hsl(340, 26%, 94%);
+  --sl-color-gray-7: hsl(340, 32%, 97%);
+  --sl-color-black: hsl(0, 0%, 100%);
+
+  --sl-hue-orange: 20;
+  --sl-hue-green: 145;
+  --sl-hue-blue: 230;
+  --sl-hue-purple: 285;
+  --sl-hue-red: 350;
+
+  --sl-color-accent-high: hsl(338, 80%, 34%);
+  --sl-color-accent: hsl(340, 80%, 44%);
+  --sl-color-accent-low: hsl(340, 90%, 91%);
+
+  --sl-color-backdrop-overlay: hsla(340, 30%, 35%, 0.66);
+}
+
+/* Forest — green accent with cool neutrals. */
+:root[data-hagilight-theme='forest']:not([data-theme='light']),
+:root[data-hagilight-theme='forest']:not([data-theme='light']) ::backdrop {
+  --sl-color-white: hsl(0, 0%, 100%);
+  --sl-color-gray-1: hsl(150, 20%, 94%);
+  --sl-color-gray-2: hsl(150, 10%, 77%);
+  --sl-color-gray-3: hsl(150, 8%, 56%);
+  --sl-color-gray-4: hsl(150, 8%, 36%);
+  --sl-color-gray-5: hsl(150, 12%, 23%);
+  --sl-color-gray-6: hsl(150, 16%, 16%);
+  --sl-color-black: hsl(150, 18%, 10%);
+
+  --sl-hue-orange: 35;
+  --sl-hue-green: 155;
+  --sl-hue-blue: 200;
+  --sl-hue-purple: 262;
+  --sl-hue-red: 5;
+
+  --sl-color-accent-low: hsl(152, 60%, 20%);
+  --sl-color-accent: hsl(158, 80%, 52%);
+  --sl-color-accent-high: hsl(150, 90%, 78%);
+
+  --sl-color-backdrop-overlay: hsla(150, 40%, 8%, 0.66);
+}
+
+:root[data-hagilight-theme='forest'][data-theme='light'],
+:root[data-hagilight-theme='forest'][data-theme='light'] ::backdrop {
+  --sl-color-white: hsl(150, 20%, 10%);
+  --sl-color-gray-1: hsl(150, 16%, 16%);
+  --sl-color-gray-2: hsl(150, 10%, 23%);
+  --sl-color-gray-3: hsl(150, 8%, 36%);
+  --sl-color-gray-4: hsl(150, 6%, 56%);
+  --sl-color-gray-5: hsl(150, 8%, 77%);
+  --sl-color-gray-6: hsl(150, 24%, 94%);
+  --sl-color-gray-7: hsl(150, 30%, 97%);
+  --sl-color-black: hsl(0, 0%, 100%);
+
+  --sl-hue-orange: 35;
+  --sl-hue-green: 155;
+  --sl-hue-blue: 200;
+  --sl-hue-purple: 262;
+  --sl-hue-red: 5;
+
+  --sl-color-accent-high: hsl(152, 100%, 24%);
+  --sl-color-accent: hsl(155, 100%, 26%);
+  --sl-color-accent-low: hsl(152, 85%, 89%);
+
+  --sl-color-backdrop-overlay: hsla(150, 30%, 35%, 0.66);
+}