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

package/MarkdownContent.astro

@@ -0,0 +1,45 @@
+---
+import { getCollection } from 'astro:content';
+import DefaultMarkdownContent from '@astrojs/starlight/components/MarkdownContent.astro';
+import ArticlePromotion from './ArticlePromotion.astro';
+import AIDisclosureNotice from './AIDisclosureNotice.astro';
+import {
+  getSourcePath,
+  isTranslationLocale,
+  resolveAIDisclosureFlags,
+} from './dist/ai-disclosures.js';
+import { resolveArticlePromotion } from './dist/article-promotion.js';
+
+const {
+  aiDisclosures = { isAITranslation: false, isAIAuthor: false, sourceLocale: 'root' },
+  hagicodePromotionEnabled = true,
+  hagicodePromotionRandomAvatar = true,
+} = Astro.props;
+const route = Astro.locals.starlightRoute;
+const isDocsEntry = route.entry.id !== '404' && !route.entry.id.endsWith('/404');
+const flags = isDocsEntry
+  ? resolveAIDisclosureFlags(route.entry.data, aiDisclosures)
+  : { isAITranslation: false, isAIAuthor: false };
+const showHagicodePromotion = isDocsEntry
+  && resolveArticlePromotion(route.entry.data.hagicodePromotion, hagicodePromotionEnabled);
+const showTranslation = flags.isAITranslation
+  && isTranslationLocale(route.entryMeta.locale, aiDisclosures.sourceLocale);
+let sourceHref;
+
+if (showTranslation) {
+  const docs = await getCollection('docs');
+  sourceHref = getSourcePath({
+    docs,
+    routeId: route.id,
+    currentLocale: route.locale,
+    sourceLocale: aiDisclosures.sourceLocale,
+    pathname: Astro.url.pathname,
+    baseUrl: import.meta.env.BASE_URL,
+  });
+}
+---
+
+{flags.isAIAuthor && <AIDisclosureNotice kind="author" lang={route.lang} />}
+<DefaultMarkdownContent><slot /></DefaultMarkdownContent>
+{showTranslation && <AIDisclosureNotice kind="translation" lang={route.lang} sourceHref={sourceHref} />}
+{showHagicodePromotion && <ArticlePromotion lang={route.lang} randomAvatar={hagicodePromotionRandomAvatar} />}

package/NotFoundHero.astro

@@ -0,0 +1,44 @@
+---
+import DefaultHero from '@astrojs/starlight/components/Hero.astro';
+import context from 'virtual:starlight/project-context';
+import {
+  getNotFoundHomeHref,
+  getNotFoundHomeLabel,
+  isNotFoundEntry,
+} from './dist/not-found.js';
+
+const route = Astro.locals.starlightRoute;
+const isNotFound = isNotFoundEntry(route.entry.id);
+const homeHref = getNotFoundHomeHref({
+  basePath: import.meta.env.BASE_URL,
+  locale: route.locale,
+  trailingSlash: context.trailingSlash,
+});
+const homeLabel = getNotFoundHomeLabel(route.lang);
+---
+
+{
+  isNotFound ? (
+    <div class="not-found-hero">
+      <DefaultHero />
+      <div class="recovery-action">
+        <a class="sl-link-button primary" href={homeHref}>{homeLabel}</a>
+      </div>
+    </div>
+  ) : (
+    <DefaultHero />
+  )
+}
+
+<style>
+  .not-found-hero {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+  }
+
+  .recovery-action {
+    margin-block: 0.5rem 2rem;
+    text-align: center;
+  }
+</style>

package/PageTitle.astro

@@ -0,0 +1,7 @@
+---
+import DefaultPageTitle from '@astrojs/starlight/components/PageTitle.astro';
+import ContentLayoutToggle from './ContentLayoutToggle.astro';
+---
+
+<DefaultPageTitle />
+<ContentLayoutToggle />

package/PromotoFooter.astro

@@ -0,0 +1,7 @@
+---
+import PromotoBanner from '@hagicode/hagilight-core/PromotoBanner';
+import Footer from './Footer.astro';
+---
+
+<Footer />
+<PromotoBanner />

package/README.md

@@ -0,0 +1,178 @@
+# @hagicode/hagilight-starlight
+
+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
+
+```sh
+npm install @hagicode/hagilight-starlight @astrojs/starlight astro
+```
+
+Use Starlight `^0.42.4` and Astro `^7.3.5`. The matching `@hagicode/hagilight-core` version is installed as a dependency.
+
+## Use
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import hagilight from '@hagicode/hagilight-starlight';
+import { locales } from '@hagicode/hagilight-starlight/locales';
+
+export default defineConfig({
+  site: 'https://docs.example.com',
+  integrations: [
+    starlight({ title: 'Docs', locales, plugins: [hagilight()] }),
+  ],
+});
+```
+
+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()`.
+
+### Analytics
+
+`hagilight()` enables PostHog without analytics configuration, an enabled flag, or a consumer project key. It uses `phc_qiVVihsL925ovhPYNdLJWz4k7aoKVMwYCevgZPE6PER5`, API host `https://us.i.posthog.com`, and SDK defaults `2026-05-30`. Google Analytics and PostHog render together in the generated global Head; 51LA stays in the Footer. PostHog covers all production pages, including localized and 404 pages, independently of Google's existing 404 exclusion. Development pages emit no PostHog loader.
+
+PostHog options follow the Google Analytics provider convention:
+
+| PostHog input | Behavior |
+| --- | --- |
+| Plugin options omitted, `analytics: {}`, or `posthog` omitted | Enabled with the supplied default key |
+| `posthog: {}` | Disabled, like an empty Google Analytics provider |
+| `posthog: { apiKey: 'phc_Custom123' }` | Enabled with the custom key |
+| `posthog: { enabled: true, apiKey: 'phc_Custom123' }` | Enabled with the custom key |
+| `posthog: { enabled: true }` | Configuration error: `apiKey` required |
+| `posthog: { enabled: false }` | Disabled independently of Google Analytics and 51LA |
+
+Keys must match `^phc_[A-Za-z0-9]+$`; enabled providers reject missing or malformed keys. Provider options must be objects and `enabled` must be boolean.
+
+```js
+hagilight(); // shared analytics defaults
+hagilight({ analytics: { posthog: { apiKey: 'phc_Custom123' } } });
+hagilight({ analytics: { posthog: { enabled: false } } });
+```
+
+A site-owned `components.Head` conflicts with enabled SEO, Google Analytics, or PostHog. To retain it, disable all three head features and explicitly compose the desired metadata and `@hagicode/hagilight-core/GoogleAnalytics` / `@hagicode/hagilight-core/PostHog` components in that Head:
+
+```js
+hagilight({
+  seo: { enabled: false },
+  analytics: {
+    googleAnalytics: { enabled: false },
+    posthog: { enabled: false },
+  },
+});
+```
+
+The shared component initializes once per document; SDK defaults own PostHog navigation behavior. Choose one initialization owner and disable this provider when the site already initializes PostHog. Google Analytics and 51LA keep their configured behavior when PostHog is disabled.
+
+### 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 and renders the Forest theme. First-time visitors, and visitors with an invalid saved choice, therefore see Forest; the other themes appear only after an explicit selection, which is remembered in `localStorage`.
+
+Earlier versions assigned each first-time visitor a random theme and stored it under `hagilight-theme-random`. That value is now ignored: returning visitors who never picked a theme explicitly see Forest after upgrading, while visitors with an explicit choice keep it.
+
+Disable the picker to keep Starlight's built-in toggle or compose `@hagicode/hagilight-starlight/ThemeSelect` yourself:
+
+```js
+hagilight({ themes: { enabled: false } })
+```
+
+### Build line
+
+The plugin footer shows the same build line as the Astro package: `Branch:`, `Commit:`, and `Built:` after the attribution. It is always on and has no option of its own. The values come from `HAGILIGHT_BUILD_BRANCH` and `HAGILIGHT_BUILD_COMMIT`, then Git, then `unknown`; the core README gives the order. Detached-HEAD CI checkouts report `Branch: unknown` unless the build step sets `HAGILIGHT_BUILD_BRANCH`, as shown in the Astro README. Footer components mounted directly in a page (`@hagicode/hagilight-starlight/Footer` and `PromotoFooter`) render no build text.
+
+### Site metadata
+
+The plugin writes `/.well-known/hagilight.metadata.json` once per build, after the sitemap, so `discovery` lists the sitemap and any RSS feed that exist. The file's schema and privacy rules are in `@hagicode/hagilight-core`'s README.
+
+- `metadata: false` opts out. `metadata: { name, description }` sets the values; the name defaults to the Starlight `title` for the default locale, then the site hostname.
+- Analytics flags report the resolved options. A provider you disable with `analytics` reads `false`. The IDs and keys are never written.
+- When the plain-Astro `hagilight()` integration is also registered, this plugin writes the file, including `llms.txt` in `discovery`, whatever the order of registration. Set `metadata: false` here to let the plain-Astro integration write it instead.
+- GitHub Pages needs a `.nojekyll` file in the published root, or the `.well-known` directory is dropped. The `/docs/` base path puts the file at `<site URL>/docs/.well-known/hagilight.metadata.json`.
+
+### Body images
+
+`hagilight()` registers the content-image plugin from `@hagicode/hagilight-core/content-images` for the whole site. Every Markdown or MDX body image outside a `<picture>` element gets `loading="lazy"`, `decoding="async"`, and the class `hagilight-content-image`. Values the author set are kept, and logos and showcase images are not changed.
+
+Local body images in `.md` and `.mdx` files are also wrapped in a `<picture>` element with AVIF and WebP `<source>` elements, produced by Astro's image service. The rule is the same for both file types: a relative local image that is not `.svg` or `.gif` and does not resolve into `public/` is wrapped. A Markdown image in an `.mdx` page therefore renders as `picture` with an inner `<img>`, the same as in `.md`. The default sharp service encodes AVIF. With the passthrough no-op service, the wrapper is skipped and one warning is logged. Site-root and remote images, and raw HTML `<img>` tags, are not wrapped. Encoding adds build time, which Astro caches. In `.md`, each `<source>` also carries `src`, `loading`, `decoding`, `width`, and `height` from Astro's output; in `.mdx`, `<source>` carries only `srcset` and `type`. Browsers ignore the extra attributes on `source`, but they are not valid HTML there. The opt-out below turns this step off too. The step adds no option of its own.
+
+Turn it off for the site:
+
+```js
+hagilight({ contentImages: { enabled: false } })
+```
+
+### HagiCode showcase
+
+After the body (and any translation notice) of every documentation article, the plugin renders a static HagiCode showcase: a headline, lead, and tagline with calls to action to the website and the documentation, three pillars (Smart, Efficient, Fun), a gallery with captions (three audited screenshots and one hero-avatar illustration), and a closing row with the Windows download button beside a selectable, copy-ready share sentence. The layout follows the showcase's own width: one column when narrow, a three-up pillar row, a gallery mosaic, and a two-column closing row from 36rem, and the pillars beside the pitch from 56rem (for example in the wide content mode). All text is localized for the ten published locales (`en-US`, `zh-CN`, `zh-Hant`, `ja-JP`, `ko-KR`, `de-DE`, `fr-FR`, `es-ES`, `pt-BR`, `ru-RU`) and falls back to English for any other language. Links come from the same locale-aware catalog as the footer.
+
+Turn it off for the whole site, or override it per article:
+
+```js
+hagilight({ hagicodePromotion: { enabled: false } })
+```
+
+```md
+---
+title: An article without the showcase
+hagicodePromotion: false
+---
+```
+
+The floating banner is a separate option (`promoto`).
+
+#### Reuse the copy
+
+`@hagicode/hagilight-starlight/showcase` returns the same read-only copy, including the share sentence, so sibling sites can show identical wording:
+
+```js
+import { getShowcaseCopy, showcaseLocales } from '@hagicode/hagilight-starlight/showcase';
+
+const copy = getShowcaseCopy('ja-JP'); // English copy for any unsupported locale
+copy.shareText; // one sentence that ends with https://www.hagicode.com/
+```
+
+The catalog is frozen; changing a returned object throws.
+
+#### Windows download button and the Microsoft badge script
+
+The Windows button follows the official HagiCode website and documentation: the `<ms-store-badge>` element for product `9N3PM0N3SVDW` (`window-mode="direct"`, `theme="auto"`, `size="large"`, badge language matching the page locale). Inside it sits a plain "Get it from Microsoft Store" link to the Store listing, and next to it an "All downloads" link to the localized downloads page for other platforms. The store URL and the downloads URL come from `@hagicode/hagilight-core` (`microsoftStore`, `downloadClient`).
+
+This is the only script the showcase loads: `https://get.microsoft.com/badge/ms-store-badge.bundled.js`, as a module script. It only draws the badge. If your content security policy blocks it, or the reader is offline or blocks third-party scripts, the plain Store link stays visible and works, and nothing else changes. To use the badge, allow `get.microsoft.com` in `script-src`. The loader is emitted once per page, and only when the showcase is enabled. There is no first-party script, no operating-system detection, and no Steam link (the Steam app is retired).
+
+#### Assets and image traffic
+
+The gallery images and pillar icons live in `assets/showcase/`. The illustration `hero-avatar.webp` is the R2 object `hero-avatars/ember-01.avif` (1024 px) upscaled to the 1200 px minimum; its manifest entry records the source and this transform, with a provenance record in `assets/showcase/manifest.json`. Each entry states its kind (`sourced` from the HagiCode web app or documentation, a hand-authored `svg`, or a `generated` illustration), its source path or generation record (tool, prompt, parameters, date), the crop and conversion applied, its size, and the audit verdict. Nothing is fetched from the product sites at build or read time.
+
+Every asset passes the same audit before it is committed: the current `HagiCode` brand, no Steam or other retired-channel content, no third-party promotion, no credentials, private repository names, or personal data, and rasters at least 1200 px wide. A removable offending region may be cropped out, and the crop is recorded. Pick images in this order to keep traffic low: an audited existing image converted to WebP, then a hand-authored SVG, then a newly generated raster only when neither fits. Generated art is an illustration, never a replica of the product UI, contains no text or logos, is captioned as an illustration, is reviewed by a person, and records its prompt and parameters (never credentials). Generation is an authoring step; the package never calls a generator.
+
+Budgets for the shipped sources, enforced by `npm test`: 768 KiB for all showcase sources together, 200 KiB per raster source (WebP only), and 8 KiB per SVG. `npm run build:example` also checks the built output: each delivered raster variant at most 200 KiB, the variants of one format at most 768 KiB together, and each AVIF variant smaller than the WebP variant of the same width.
+
+Each gallery image renders as a `<picture>` with an AVIF source, a WebP source, and a JPEG `<img>` fallback, at widths 480, 800, and the native width. The tiers are derived at the consumer's build from the shipped WebP, with the `sharp` service that Astro already bundles, so no conversion runs outside the site's own build and no external service is involved. The chain needs a transforming image service: with the passthrough `astro/assets/services/noop` service the tiers serve the original bytes, and the plugin logs one warning. Opaque images use the JPEG tier. The JPEG tier cannot carry transparency, so an image that needs alpha needs a PNG tier, which the component does not offer yet, and a budget review before it is added.
+
+Images are served through Astro's image pipeline as responsive, content-hashed files, load lazily with low priority, and sit after the article body, so a reader who does not reach the end downloads none of them.
+
+Measured on `examples/demo-starlight-web` with one warm build each: the nine AVIF variants total 139.0 KiB (largest 41.4 KiB) and the nine JPEG variants total 387.4 KiB (largest 118.2 KiB). The shipped WebP sources are unchanged. The build took 21.6 s without the tiers and 20.4 s with them, a difference within run-to-run noise. A browser that supports AVIF downloads one variant per image, the AVIF one.
+
+#### Adopting and verifying
+
+Upgrading `@hagicode/hagilight`, `@hagicode/hagilight-starlight`, and `@hagicode/hagilight-core` together is the whole change. It needs no configuration, dependency, script, or CI step: the consumer's existing build derives the tiers. If the build logs the passthrough image service warning, remove the `image` service override or use the default `sharp` service.
+
+To check a deployed site, run `curl -sI https://<site>/_astro/<file>.avif` with a real file name from the built `dist/_astro`; it should report `Content-Type: image/avif`. `docs` also previews on Azure Static Web Apps, so check that preview as well. Any host header fix belongs to the owning repository, not to this package.
+
+#### Keep it in sync
+
+The copy and assets mirror `repos/web` and `repos/docs` in the HagiCode monorepo, which this package never edits.
+
+- **Copy:** edit `src/article-promotion-copy/<locale>.ts` (every locale must keep the same fields, feature ids, and gallery ids). Terminology is pinned in `GLOSSARY` in `src/article-promotion-copy/index.ts`, seeded from the product locale files in `repos/web/src/locales/<locale>/`. `HagiCode`, `OpenSpec`, `Hero Scenario`, `Microsoft Store`, and `Windows` are never translated.
+- **Images:** audit the candidate, crop and convert it to WebP (the AVIF and JPEG tiers are derived at build time, so an opaque image needs no extra file), add or update its `manifest.json` entry, register it in the `galleryImages` map in `ArticlePromotion.astro`, and add a caption and text alternative in every locale. The gallery mosaic places the first, second, and third catalog entries as the left top, left bottom, and right tall slot, so keep the three screenshots first. The illustration is the fourth entry: from 36rem it takes a full-width row with a 12 rem square and its caption, and it is the only gallery image that may change. To add a screenshot, revisit the placement in the component's `@container (min-width: 36rem)` block. `npm test` checks that the manifest, the files, the component registry, and the copy agree.
+- **Random illustration (R2 pool):** the `hero-avatar` entry in `assets/showcase/manifest.json` carries `source` (`repo: img-gen`, `album`, `objectKey`), its audit, and `pool` (`album`, `maxBytes` 200 KiB, `entries` with `key` and `bytes`). `ArticlePromotion.astro` builds the pool attribute at build time and renders `ArticlePromotionPicker.astro` only when the option is on. Refresh: take keys from the `hero-avatars` album `index.json`, keep 12 to 200 unique keys each within `maxBytes`, audit them text-free and current, update `pool.entries`, and keep the footer pool in `repos/hagilight/packages/core/assets/footer/manifest.json` in step. To rebuild the WebP, resize the source to 1200 px (lanczos3) and encode at quality 88. `npm test` (`test/showcase-assets.test.mjs`) checks the entry, the pool, the byte caps and the budgets.
+- **Options:** `hagicodePromotion: { randomAvatar: false }` keeps the default illustration and loads no picker; `footer: { avatar: false }` removes the footer avatar, and `footer: { randomAvatar: false }` keeps its default. A site whose `img-src` policy blocks `https://img-gen.hagicode.com` keeps the defaults.
+- **Badge:** the product id is parsed from the Store URL and the badge language map lives in `src/windows-download.ts`. Re-check both against `repos/docs/src/components/MicrosoftStoreBadge.tsx` and the official site when the Store listing or the supported languages change.
+
+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.
+
+See the [repository documentation](https://github.com/HagiCode-org/hagilight#readme) for schema setup and feature options.

package/SEOHead.astro

@@ -0,0 +1,67 @@
+---
+import { getCollection } from 'astro:content';
+import { composeSeoHead, resolveSeoMetadata, serializeJsonLd } from '@hagicode/hagilight-core/seo';
+import {
+  buildStructuredData,
+  createPublishedDocsLookup,
+  filterPublishedLocaleAlternates,
+  resolveSeoPage,
+} from './dist/seo-utils.js';
+
+const { options } = Astro.props;
+const route = Astro.locals.starlightRoute;
+const routeId = route?.id ?? route?.entry?.id ?? '';
+const isNotFound = /(?:^|\/)404(?:\.html)?\/?$/u.test(Astro.url.pathname)
+  || routeId === '404'
+  || routeId.endsWith('/404');
+let head = route?.head ?? [];
+let structuredData = [];
+
+if (route?.entry?.collection === 'docs' && !isNotFound && route.entry.data?.draft !== true) {
+  const entries = await getCollection('docs', ({ data }) => data.draft !== true);
+  const lookup = createPublishedDocsLookup(entries, options.seoLocales);
+  const page = resolveSeoPage(routeId, options.seoLocales);
+  const sourceEntry = lookup.get(page.route, page.slug);
+  const explicitHead = [options.consumerHead, route.entry.data.head];
+  head = filterPublishedLocaleAlternates(head, {
+    entryId: routeId,
+    locales: options.seoLocales,
+    lookup,
+    basePath: options.seoBasePath,
+    explicitHead,
+  });
+
+  const seoMetadata = resolveSeoMetadata({
+    entry: route.entry,
+    head,
+    pageSeo: route.entry.data.seo,
+    siteSeo: options.seo,
+    site: options.seoSite,
+    basePath: options.seoBasePath,
+    explicitHead,
+    body: sourceEntry?.body,
+  });
+  head = composeSeoHead(head, seoMetadata, explicitHead);
+  const canonicalUrl = head.find(({ tag, attrs }) => tag === 'link' && attrs?.rel === 'canonical')?.attrs.href;
+  structuredData = buildStructuredData({
+    entry: route.entry,
+    entryId: routeId,
+    canonicalUrl,
+    site: options.seoSite,
+    siteTitle: route.siteTitle,
+    pageSeo: { ...route.entry.data.seo, description: seoMetadata.description },
+    organization: options.seo.organization,
+    locales: options.seoLocales,
+    defaultLocale: options.seoDefaultLocale,
+    lookup,
+    basePath: options.seoBasePath,
+    format: options.seoFormat,
+    trailingSlash: options.seoTrailingSlash,
+  });
+}
+---
+
+{head.map(({ tag: Tag, attrs, content }) => <Tag {...attrs} set:html={content} />)}
+{structuredData.map((value) => (
+  <script type="application/ld+json" set:html={serializeJsonLd(value)} />
+))}

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>