@rxova/brand 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -20,7 +20,7 @@
   },
   "bugs": "https://github.com/rxova/brand/issues",
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=24.0.0"
   },
   "sideEffects": [
     "*.css"
@@ -58,14 +58,17 @@
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^26.1.1",
     "astro": "^7.1.3",
+    "publint": "^0.3.21",
     "satori": "^0.29.0",
+    "tsx": "^4.23.1",
     "typescript": "6.0.3"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "check:astro": "astro check",
-    "check:exports": "node scripts/check-exports.mjs",
-    "og": "node scripts/generate-og.mjs",
-    "check:og": "node scripts/generate-og.mjs --check"
+    "pack:smoke": "node --import tsx scripts/pack-smoke.ts",
+    "check:exports": "publint --strict",
+    "og": "node --import tsx scripts/generate-og.ts",
+    "check:og": "node --import tsx scripts/generate-og.ts --check"
   }
 }

package/src/components/ThemeSelect.astro

@@ -0,0 +1,57 @@
+---
+/**
+ * Starlight's theme picker, plus a resync when the page comes out of the
+ * back/forward cache.
+ *
+ * Starlight applies the stored theme in two places, both of which run exactly
+ * once, while the document is being parsed: the inline script in
+ * `ThemeProvider.astro`, and the `<starlight-theme-select>` constructor. A
+ * back/forward navigation that hits the bfcache *restores* the document rather
+ * than parsing it, so neither runs again and the page keeps whatever
+ * `data-theme` it carried when the visitor left.
+ *
+ * All of rxova.org is one origin sharing one `starlight-theme` key, so that is
+ * a visible jump rather than a curiosity: pick a theme on the landing page or
+ * on another project's docs, press Back, and the restored page is still on the
+ * old one.
+ *
+ * This wraps rather than replaces Starlight's component — the picker, its
+ * labels and its own logic are untouched, and a Starlight release that changes
+ * them changes them here too.
+ */
+import Default from '@astrojs/starlight/components/ThemeSelect.astro'
+---
+
+<Default><slot /></Default>
+
+<script>
+  type Theme = 'auto' | 'dark' | 'light'
+
+  /** Same key and coercion Starlight uses; unknown values mean "follow the OS". */
+  const STORAGE_KEY = 'starlight-theme'
+  const parseTheme = (theme: unknown): Theme =>
+    theme === 'auto' || theme === 'dark' || theme === 'light' ? theme : 'auto'
+  const preferredColorScheme = (): Theme =>
+    matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'
+
+  // `pageshow` is the only notification of a bfcache restore. A normal load
+  // also fires it with `persisted: false`, which we ignore — Starlight has
+  // already done the work in that case.
+  window.addEventListener('pageshow', (event) => {
+    if (!event.persisted) return
+
+    let stored: string | null
+    try {
+      stored = localStorage.getItem(STORAGE_KEY)
+    } catch {
+      // Storage can throw outright (Safari private mode, blocked cookies).
+      // Leaving the restored theme alone is the right fallback.
+      return
+    }
+
+    const theme = parseTheme(stored)
+    document.documentElement.dataset.theme = theme === 'auto' ? preferredColorScheme() : theme
+    // Keeps the picker from disagreeing with the page it controls.
+    StarlightThemeProvider.updatePickers(theme)
+  })
+</script>

package/src/env.d.ts

@@ -5,3 +5,17 @@
 // Starlight's own `.ts` sources, which import `virtual:starlight/*` modules
 // that only exist inside an Astro build — so plain `tsc` fails on them.
 // The one component that reads route data narrows it structurally instead.
+
+// Same reasoning for this one. It mirrors Starlight's own `global.d.ts`, which
+// we cannot `/// <reference>` because the package's types entry is `index.ts`
+// and drags in those same virtual modules. The global is defined at runtime by
+// the inline script in Starlight's `ThemeProvider.astro`; ThemeSelect.astro
+// calls it. Re-check this against Starlight's `global.d.ts` on a major bump.
+declare global {
+  interface StarlightThemeProvider {
+    updatePickers(theme?: string): void
+  }
+  var StarlightThemeProvider: StarlightThemeProvider
+}
+
+export {}

package/src/starlight.ts

@@ -73,6 +73,10 @@ export function sharedStarlightConfig({
       // Starlight's default footer (pagination, edit link, last updated) plus
       // the shared four-column site footer beneath it.
       Footer: '@rxova/brand/components/Footer.astro',
+      // Starlight's own picker, plus a resync when a page is restored from the
+      // back/forward cache — without it, changing the theme on one rxova.org
+      // surface and pressing Back leaves the restored page on the old theme.
+      ThemeSelect: '@rxova/brand/components/ThemeSelect.astro',
       ...components,
     },