@brandon_m_behring/book-scaffold-astro 4.14.1 → 4.14.2

package/CLAUDE.md

@@ -106,6 +106,28 @@ Two callout families coexist. Authors import what they need.
 
 Full reference in `recipes/04-component-library.md`.
 
+### Theme-change event (v4.14.2)
+
+`Base.astro` emits `book:theme:change` on `window` whenever the **effective** theme changes — both the chrome's dark-mode toggle and a system `prefers-color-scheme` flip (the latter only when no explicit theme is pinned). Use it for **canvas / JS islands** that can't recolor via CSS alone; CSS-token elements recolor automatically from the `[data-theme]` attribute.
+
+```ts
+// inside a Preact island (client:visible / client:idle)
+function currentTheme(): 'light' | 'dark' {
+  const t = document.documentElement.getAttribute('data-theme');
+  return t === 'light' || t === 'dark'
+    ? t
+    : matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+useEffect(() => {
+  draw(currentTheme());                                 // initial paint
+  const onChange = (e: Event) => draw((e as CustomEvent).detail.theme);
+  window.addEventListener('book:theme:change', onChange);
+  return () => window.removeEventListener('book:theme:change', onChange);
+}, []);
+```
+
+`detail.theme` is `'light' | 'dark'`. Pull design-token colors via `getComputedStyle(document.documentElement).getPropertyValue('--…')` so the canvas matches the page, and respect `prefers-reduced-motion` for any redraw animation. (Event-only by design — a `useThemeColors` helper graduates with the demo kit, #103.)
+
 ## Citation patterns
 
 Academic profile uses BibTeX → `references.json`:

package/layouts/Base.astro

@@ -176,21 +176,47 @@ const ogDescription = description ?? bookConfig.description ?? '';
     ) : (
       <main><slot /></main>
     )}
+    {/*
+      Theme-change hook (#103, v4.14.2). Whenever the EFFECTIVE theme changes,
+      emit `book:theme:change` on `window` with `detail.theme` ∈ {'light','dark'}.
+      CSS recolors via the `data-theme` attribute alone; canvas/JS islands can't,
+      so they subscribe to this event (and read the attribute / matchMedia on
+      mount for the initial value) to redraw. Contract documented in the package
+      CLAUDE.md. Event-only by design — a `useThemeColors` helper graduates later
+      with the demo kit.
+    */}
     <script is:inline>
       (function () {
+        var root = document.documentElement;
+        function effectiveTheme() {
+          var explicit = root.getAttribute('data-theme');
+          if (explicit === 'light' || explicit === 'dark') return explicit;
+          return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+        }
+        function emitThemeChange() {
+          window.dispatchEvent(new CustomEvent('book:theme:change', { detail: { theme: effectiveTheme() } }));
+        }
         var btn = document.getElementById('theme-toggle');
-        if (!btn) return;
-        btn.addEventListener('click', function () {
-          var current = document.documentElement.getAttribute('data-theme');
-          // If no explicit theme, pick the opposite of prefers-color-scheme.
-          if (!current) {
-            var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-            current = prefersDark ? 'dark' : 'light';
-          }
-          var next = current === 'dark' ? 'light' : 'dark';
-          document.documentElement.setAttribute('data-theme', next);
-          try { localStorage.setItem('theme', next); } catch (e) {}
-        });
+        if (btn) {
+          btn.addEventListener('click', function () {
+            var current = root.getAttribute('data-theme');
+            // If no explicit theme, pick the opposite of prefers-color-scheme.
+            if (!current) {
+              current = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+            }
+            var next = current === 'dark' ? 'light' : 'dark';
+            root.setAttribute('data-theme', next);
+            try { localStorage.setItem('theme', next); } catch (e) {}
+            emitThemeChange();
+          });
+        }
+        // A system-preference flip only changes the effective theme when no
+        // explicit theme is pinned — emit then so islands can redraw too.
+        try {
+          window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function () {
+            if (!root.getAttribute('data-theme')) emitThemeChange();
+          });
+        } catch (e) { /* older browsers: no media-query change events */ }
       })();
     </script>
   </body>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.14.1",
+  "version": "4.14.2",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",