@hagicode/hagilight-starlight 0.6.0 → 0.6.1-dev.74.1.7df157f

package/README.md

@@ -31,7 +31,11 @@ The plugin also exposes `@hagicode/hagilight-starlight/schema` for optional SEO
 
 ### 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:
+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 } })

package/dist/index.d.ts

@@ -38,7 +38,8 @@ 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.
+     * choice that follows the system color scheme and renders the Forest theme, so
+     * first-visit users see Forest until they pick another theme.
      * Defaults to `true`.
      */
     enabled?: boolean;
@@ -56,7 +57,7 @@ export interface HagilightStarlightOptions {
     seo?: HagilightSeoOptions;
     contentComponents?: HagilightContentComponentsOptions;
     aiDisclosures?: HagilightAIDisclosureOptions;
-    /** Theme picker with three extra light/dark themes plus a randomized first-visit default. */
+    /** Theme picker with three extra light/dark themes and a Forest first-visit default. */
     themes?: HagilightThemesOptions;
     /** End-of-article HagiCode introduction. */
     hagicodePromotion?: HagilightToggleOptions;

package/dist/themes.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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
+ * each with a light and a dark appearance, plus a "default" choice that follows the system
+ * color scheme and renders the Forest palette. 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.
@@ -9,12 +9,13 @@
 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"];
+/** Themes beyond the Starlight default; each must have light and dark palettes in `themes.css`. */
+export declare const EXTRA_THEME_IDS: readonly ["ocean", "sakura", "forest"];
+/** The palette the "default" choice renders, so first-visit users always see the same theme. */
+export declare const DEFAULT_PALETTE_THEME_ID: Exclude<ThemeId, 'default'>;
 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;
@@ -22,9 +23,7 @@ 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". */
+/** The theme id a choice renders as: the theme itself, or the Forest palette 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. */
@@ -35,7 +34,7 @@ export declare function applyThemeChoice(choice: ThemeChoice, root?: HTMLElement
  */
 export declare const THEME_BOOTSTRAP: string;
 export interface ThemePickerLabels {
-    /** Label of the "default" choice: site default experience with an automatically assigned theme. */
+    /** Label of the "default" choice: follows the system color scheme and renders the Forest theme. */
     defaultOption: string;
     /** Label of the option group holding the built-in theme's light and dark appearances. */
     defaultThemeGroup: string;

package/dist/themes.js

@@ -1,13 +1,15 @@
 /**
  * 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
+ * each with a light and a dark appearance, plus a "default" choice that follows the system
+ * color scheme and renders the Forest palette. 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'];
+/** Themes beyond the Starlight default; each must have light and dark palettes in `themes.css`. */
+export const EXTRA_THEME_IDS = ['ocean', 'sakura', 'forest'];
+/** The palette the "default" choice renders, so first-visit users always see the same theme. */
+export const DEFAULT_PALETTE_THEME_ID = 'forest';
 export const DEFAULT_THEME_CHOICE = 'default';
 export const THEME_CHOICES = [
     'default',
@@ -21,10 +23,8 @@ export const THEME_CHOICES = [
     '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;
@@ -54,19 +54,10 @@ function writeStorage(key, value) {
         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". */
+/** The theme id a choice renders as: the theme itself, or the Forest palette for "default". */
 export function resolveThemeId(choice) {
     const { themeId, mode } = splitThemeChoice(choice);
-    return mode === undefined ? assignedRandomThemeId() : themeId;
+    return mode === undefined ? DEFAULT_PALETTE_THEME_ID : themeId;
 }
 export function readStoredThemeChoice() {
     return parseThemeChoice(readStorage(THEME_STORAGE_KEY));
@@ -86,31 +77,15 @@ export function applyThemeChoice(choice, root = document.documentElement) {
  */
 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('-'));
-  }
+  var themeId = choice === 'default'
+    ? ${JSON.stringify(DEFAULT_PALETTE_THEME_ID)}
+    : choice.slice(0, choice.lastIndexOf('-'));
   document.documentElement.dataset.hagilightTheme = themeId;
 })();`;
 const labels = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/hagilight-starlight",
-  "version": "0.6.0",
+  "version": "0.6.1-dev.74.1.7df157f",
   "type": "module",
   "description": "Starlight plugin and components for HagiCode documentation",
   "repository": {
@@ -53,7 +53,7 @@
     "assets/showcase/*"
   ],
   "dependencies": {
-    "@hagicode/hagilight-core": "0.6.0"
+    "@hagicode/hagilight-core": "0.6.1-dev.74.1.7df157f"
   },
   "peerDependencies": {
     "@astrojs/starlight": "^0.42.4",