@rxova/brand 0.1.1 → 0.2.0

package/README.md

@@ -98,9 +98,14 @@ once and gets both modes for free.
 
 ## Development
 
+The package lives in a two-package workspace — itself and `apps/preview`, a
+Starlight site that renders it. Run everything from the repo root; Turbo fans the
+tasks out and replays whatever the commit did not touch.
+
 ```sh
 pnpm install
-pnpm run verify   # format, lint, tsc, astro check, social cards, package contract
+pnpm run dev      # the preview site — the only place to *look* at the theme
+pnpm run verify   # audit, dedupe, format, lint, types, astro check, cards, contract
 pnpm run og       # re-render the social cards after a palette or tagline change
 ```
 
@@ -119,7 +124,13 @@ are perfectly correct.
 
 ### Trying a change in a consumer
 
-The package has no `workspace:*` shortcut, so iterate through snapshot releases:
+`apps/preview` links the package by `workspace:*`, so most changes can be seen
+immediately with `pnpm run dev`. It cannot catch a `files` omission, though —
+the link resolves to the source directory, where every file exists. That is what
+`check:exports` is for.
+
+For a real external consumer (the landing, a docs site), iterate through snapshot
+releases:
 
 1. Add a changeset (`pnpm exec changeset`).
 2. Run the **Snapshot** workflow — publishes `0.x.y-next.N` to the `next` tag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -15,11 +15,12 @@
   "homepage": "https://rxova.org",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rxova/brand.git"
+    "url": "git+https://github.com/rxova/brand.git",
+    "directory": "packages/brand"
   },
   "bugs": "https://github.com/rxova/brand/issues",
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=24.0.0"
   },
   "sideEffects": [
     "*.css"
@@ -54,42 +55,20 @@
   "devDependencies": {
     "@astrojs/check": "^0.9.9",
     "@astrojs/starlight": "^0.41.4",
-    "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.29.7",
-    "@commitlint/cli": "^21.2.1",
-    "@commitlint/config-conventional": "^21.2.0",
-    "@eslint/js": "^10.0.1",
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^26.1.1",
     "astro": "^7.1.3",
-    "eslint": "^10.7.0",
-    "eslint-plugin-astro": "^1.3.0",
-    "globals": "^17.6.0",
-    "husky": "^9.1.7",
-    "lint-staged": "^17.2.0",
-    "prettier": "^3.9.6",
-    "prettier-plugin-astro": "^0.14.0",
+    "publint": "^0.3.21",
     "satori": "^0.29.0",
-    "typescript": "6.0.3",
-    "typescript-eslint": "^8.65.0"
-  },
-  "lint-staged": {
-    "*.{ts,tsx,astro,mjs,js}": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "*.{json,jsonc,css,md,mdx,yaml,yml}": "prettier --write"
+    "tsx": "^4.23.1",
+    "typescript": "6.0.3"
   },
   "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
     "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",
-    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run check:astro && pnpm run check:og && pnpm run check:exports"
+    "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,
     },