@hadoku/themes 0.0.0-stage → 5.12.15

package/dist/prefsApiBase.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Where the prefs SDK should talk to.
+ *
+ * @wolffm/prefs-client defaults to `https://hadoku.me/prefs`, which is correct
+ * everywhere except a local dev or E2E run — there it means the browser reaches
+ * PRODUCTION for every preference read and write.
+ *
+ * That default is why the theme specs mocked `/prefs/api/v1/*` at the network
+ * layer in the first place, and the mocks then hid a real bug: the shared row's
+ * request escaped to hadoku.me unrouted, where a row that FAILS to resolve is
+ * indistinguishable from an empty one, so `useThemePrefsMigration` looked fine
+ * under test while being permanently disabled in the field.
+ *
+ * An override lets the dev stack run the REAL prefs-api worker locally and point
+ * the SDK at it, so the specs exercise the true fetch → auth → D1 path instead of
+ * an interceptor's idea of it. Route mocking is what we are removing; this is the
+ * seam that makes removing it possible.
+ *
+ * Set it before app code runs — a Playwright `addInitScript`, or an inline
+ * <head> script in a dev shell:
+ *
+ *   window.__HADOKU_PREFS_API_BASE__ = 'http://localhost:3003/prefs'
+ *
+ * Unset (the normal case, including all of production) returns undefined, and
+ * every client falls through to the SDK's own default.
+ */
+/** The global the override is read from. Exported so callers agree on the name. */
+export declare const PREFS_API_BASE_GLOBAL = "__HADOKU_PREFS_API_BASE__";
+/**
+ * The prefs API base to use, or undefined to accept the SDK's default.
+ *
+ * Deliberately returns `undefined` rather than the production URL: passing
+ * `apiBase: undefined` to createPrefsClient lets its own `?? PREFS_API_BASE`
+ * default apply, so this module never has to restate — and never drifts from —
+ * whatever the SDK considers canonical.
+ */
+export declare function resolvePrefsApiBase(): string | undefined;

package/dist/prefsApiBase.js

@@ -0,0 +1,40 @@
+/**
+ * Where the prefs SDK should talk to.
+ *
+ * @wolffm/prefs-client defaults to `https://hadoku.me/prefs`, which is correct
+ * everywhere except a local dev or E2E run — there it means the browser reaches
+ * PRODUCTION for every preference read and write.
+ *
+ * That default is why the theme specs mocked `/prefs/api/v1/*` at the network
+ * layer in the first place, and the mocks then hid a real bug: the shared row's
+ * request escaped to hadoku.me unrouted, where a row that FAILS to resolve is
+ * indistinguishable from an empty one, so `useThemePrefsMigration` looked fine
+ * under test while being permanently disabled in the field.
+ *
+ * An override lets the dev stack run the REAL prefs-api worker locally and point
+ * the SDK at it, so the specs exercise the true fetch → auth → D1 path instead of
+ * an interceptor's idea of it. Route mocking is what we are removing; this is the
+ * seam that makes removing it possible.
+ *
+ * Set it before app code runs — a Playwright `addInitScript`, or an inline
+ * <head> script in a dev shell:
+ *
+ *   window.__HADOKU_PREFS_API_BASE__ = 'http://localhost:3003/prefs'
+ *
+ * Unset (the normal case, including all of production) returns undefined, and
+ * every client falls through to the SDK's own default.
+ */
+/** The global the override is read from. Exported so callers agree on the name. */
+export const PREFS_API_BASE_GLOBAL = '__HADOKU_PREFS_API_BASE__';
+/**
+ * The prefs API base to use, or undefined to accept the SDK's default.
+ *
+ * Deliberately returns `undefined` rather than the production URL: passing
+ * `apiBase: undefined` to createPrefsClient lets its own `?? PREFS_API_BASE`
+ * default apply, so this module never has to restate — and never drifts from —
+ * whatever the SDK considers canonical.
+ */
+export function resolvePrefsApiBase() {
+    const override = globalThis[PREFS_API_BASE_GLOBAL];
+    return typeof override === 'string' && override.length > 0 ? override : undefined;
+}

package/dist/theme-types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Theme-domain types.
+ *
+ * These described the theme model but lived in @wolffm/task-ui-components, so
+ * @wolffm/themes had to import them from there — half of the dependency edge
+ * that forced the context and its provider into separate packages. A type is
+ * erased at runtime and cannot itself cause a duplicate-module bug, but leaving
+ * it behind would have kept the import alive for no reason.
+ *
+ * Picker-specific types (DropdownPlacement, ThemePickerProps) stay in
+ * task-ui-components: they describe a component's props, not the theme model.
+ */
+import type { ReactNode } from 'react';
+/** Theme name — any string your theme system recognises. */
+export type ThemeName = string;
+/**
+ * A light/dark theme pair with its icons and labels.
+ *
+ * Icons are optional: the picker falls back to a shape based on the family's
+ * position when one is absent.
+ */
+export interface ThemeFamily {
+    lightIcon?: ReactNode;
+    darkIcon?: ReactNode;
+    lightTheme: ThemeName;
+    darkTheme: ThemeName;
+    lightLabel: string;
+    darkLabel: string;
+}
+/**
+ * Simple flattens advanced visuals (gradients, effects) to their solid colour
+ * fallback; advanced renders them.
+ */
+export type ThemeMode = 'simple' | 'advanced';

package/dist/theme-types.js

@@ -0,0 +1 @@
+export {};

package/dist/themeContext.d.ts

@@ -0,0 +1,62 @@
+/**
+ * HadokuThemeContext — how AppHeader gets a theme picker without importing one.
+ *
+ * WHY A CONTEXT AND NOT AN IMPORT
+ * ------------------------------
+ * The whole point of the locked header is that AppHeader RENDERS the theme
+ * picker itself, so no app can pass a different one. To do that it needs the
+ * theme families, the icon map and the current theme — all of which live in
+ * `@wolffm/themes`.
+ *
+ * It cannot import them. `@wolffm/themes` peer-depends on THIS package and
+ * imports `ThemeFamily` + every icon from it (see themes/src/metadata.tsx), so
+ * `tuic -> themes` closes a cycle. React context inverts the data flow without
+ * adding a package edge: tuic DEFINES and CONSUMES the context, themes PROVIDES
+ * it via `<HadokuThemeRoot>`. The dependency graph stays themes -> tuic.
+ *
+ * It also keeps this package dependency-free (react peer only), which is a
+ * property worth protecting — everything downstream installs it.
+ *
+ * Child apps never touch this. They mount `<HadokuThemeRoot>` from
+ * `@wolffm/themes` once at their root and are done; the theme picker is then
+ * identical everywhere by construction rather than by convention.
+ */
+import React from 'react';
+import type { ThemeFamily } from './theme-types';
+export interface HadokuThemeValue {
+    /** Active theme name, e.g. 'coffee-dark'. */
+    theme: string;
+    /** Change the theme. Persists (session + local + cross-device prefs). */
+    setTheme: (theme: string) => void;
+    /** Selectable families, in picker order. */
+    themeFamilies: ThemeFamily[];
+    /** Icon for a theme name, for the picker's toggle button. */
+    getThemeIcon: (theme: string) => React.ReactNode;
+    /** True when the active theme is a dark variant. */
+    isDarkTheme: boolean;
+    /** False until the theme has been applied to the DOM. Apps gate their first
+     *  paint on this to avoid a flash of unstyled content. */
+    isThemeReady: boolean;
+    /** True only during the very first resolve of a mount — lets an app tell
+     *  "still booting" apart from "theme changing", which need different gates. */
+    isInitialThemeLoad: boolean;
+}
+export interface HadokuThemeProviderProps {
+    value: HadokuThemeValue;
+    children: React.ReactNode;
+}
+/** Low-level provider. Apps should use `<HadokuThemeRoot>` from
+ *  `@wolffm/themes`, which builds the value; this is the seam it plugs into. */
+export declare function HadokuThemeProvider({ value, children }: HadokuThemeProviderProps): React.JSX.Element;
+/**
+ * Read the ambient theme. Throws when no provider is mounted rather than
+ * degrading to a default — a silent fallback here is precisely the failure
+ * mode the locked header exists to remove. A missing provider means the app
+ * root was never wrapped, and it should say so at mount, loudly, with the fix
+ * in the message. Guessing 'light' would ship a header that looks fine and
+ * silently ignores the user's saved theme.
+ */
+export declare function useHadokuTheme(): HadokuThemeValue;
+/** Non-throwing read, for the rare component that legitimately renders both
+ *  inside and outside a themed tree (e.g. a standalone error boundary). */
+export declare function useHadokuThemeOptional(): HadokuThemeValue | null;

package/dist/themeContext.js

@@ -0,0 +1,70 @@
+/**
+ * HadokuThemeContext — how AppHeader gets a theme picker without importing one.
+ *
+ * WHY A CONTEXT AND NOT AN IMPORT
+ * ------------------------------
+ * The whole point of the locked header is that AppHeader RENDERS the theme
+ * picker itself, so no app can pass a different one. To do that it needs the
+ * theme families, the icon map and the current theme — all of which live in
+ * `@wolffm/themes`.
+ *
+ * It cannot import them. `@wolffm/themes` peer-depends on THIS package and
+ * imports `ThemeFamily` + every icon from it (see themes/src/metadata.tsx), so
+ * `tuic -> themes` closes a cycle. React context inverts the data flow without
+ * adding a package edge: tuic DEFINES and CONSUMES the context, themes PROVIDES
+ * it via `<HadokuThemeRoot>`. The dependency graph stays themes -> tuic.
+ *
+ * It also keeps this package dependency-free (react peer only), which is a
+ * property worth protecting — everything downstream installs it.
+ *
+ * Child apps never touch this. They mount `<HadokuThemeRoot>` from
+ * `@wolffm/themes` once at their root and are done; the theme picker is then
+ * identical everywhere by construction rather than by convention.
+ */
+import React from 'react';
+const HadokuThemeContext = React.createContext(null);
+/** Low-level provider. Apps should use `<HadokuThemeRoot>` from
+ *  `@wolffm/themes`, which builds the value; this is the seam it plugs into. */
+export function HadokuThemeProvider({ value, children }) {
+    return React.createElement(HadokuThemeContext.Provider, { value: value }, children);
+}
+/**
+ * Read the ambient theme. Throws when no provider is mounted rather than
+ * degrading to a default — a silent fallback here is precisely the failure
+ * mode the locked header exists to remove. A missing provider means the app
+ * root was never wrapped, and it should say so at mount, loudly, with the fix
+ * in the message. Guessing 'light' would ship a header that looks fine and
+ * silently ignores the user's saved theme.
+ */
+export function useHadokuTheme() {
+    const value = React.useContext(HadokuThemeContext);
+    if (!value) {
+        // State the OBSERVATION, then both causes — do not assert one.
+        //
+        // The old message said "No <HadokuThemeRoot> above this component", which is
+        // only one of the two ways this reads empty, and on 2026-08-05 it was the
+        // wrong one: three apps had the provider plainly mounted and still threw,
+        // because a duplicated @wolffm/themes module meant the provider filled a
+        // DIFFERENT context object than the consumer read. Everyone who saw that
+        // message went looking for a missing provider that was never missing.
+        throw new Error('[hadoku] useHadokuTheme() read an empty theme context.\n\n' +
+            'Two things cause this:\n\n' +
+            '1. No <HadokuThemeRoot> above this component. Wrap the app root once:\n' +
+            "     import { HadokuThemeRoot } from '@wolffm/themes'\n" +
+            '     <HadokuThemeRoot>\n       <App />\n     </HadokuThemeRoot>\n\n' +
+            '2. TWO COPIES of @wolffm/themes are loaded, so the provider filled a\n' +
+            '   different context object than this consumer is reading. The provider\n' +
+            '   looks correctly mounted in this case — check it before assuming (1).\n' +
+            '   Usually a bundle inlined @wolffm/themes instead of externalizing it,\n' +
+            "   while the provider came from the parent page's import map.\n" +
+            '   Confirm by counting createContext( in the shipped bundles; there must\n' +
+            "   be exactly one. hadoku_site's `pnpm run check:mf-externals` and\n" +
+            "   hadoku-task's `pnpm run check:single-context` both assert this.");
+    }
+    return value;
+}
+/** Non-throwing read, for the rare component that legitimately renders both
+ *  inside and outside a themed tree (e.g. a standalone error boundary). */
+export function useHadokuThemeOptional() {
+    return React.useContext(HadokuThemeContext);
+}

package/dist/themePrefs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical theme-preferences client for the hadoku ecosystem.
+ *
+ * This file used to exist, byte-for-byte, in every child app under
+ * `src/prefs/themePrefs.ts` — its own header said "This module is identical
+ * across every child app and the portfolio shell." A module that documents
+ * itself as copy-paste is a module that belongs in a package, so here it is.
+ *
+ * Theme is platform-global: every app and the portfolio shell read/write the
+ * SAME row, so it lives under the shared appId 'portfolio' (NOT any app's own
+ * id). A per-app id would fragment the theme across apps. Scope is 'device' so
+ * "dark on phone, light on desktop" survives.
+ *
+ * App-specific settings do NOT belong here — declare them in their own
+ * prefs client under THAT app's appId.
+ */
+import { z } from 'zod';
+export declare const ThemePrefsSchema: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodString>;
+    themeMode: z.ZodOptional<z.ZodEnum<{
+        simple: "simple";
+        advanced: "advanced";
+    }>>;
+}, z.core.$strip>;
+export type ThemePrefs = z.infer<typeof ThemePrefsSchema>;
+export declare const themePrefs: import("@wolffm/prefs-client").PrefsClient<{
+    theme?: string | undefined;
+    themeMode?: "simple" | "advanced" | undefined;
+}>;

package/dist/themePrefs.js

@@ -0,0 +1,48 @@
+/**
+ * Canonical theme-preferences client for the hadoku ecosystem.
+ *
+ * This file used to exist, byte-for-byte, in every child app under
+ * `src/prefs/themePrefs.ts` — its own header said "This module is identical
+ * across every child app and the portfolio shell." A module that documents
+ * itself as copy-paste is a module that belongs in a package, so here it is.
+ *
+ * Theme is platform-global: every app and the portfolio shell read/write the
+ * SAME row, so it lives under the shared appId 'portfolio' (NOT any app's own
+ * id). A per-app id would fragment the theme across apps. Scope is 'device' so
+ * "dark on phone, light on desktop" survives.
+ *
+ * App-specific settings do NOT belong here — declare them in their own
+ * prefs client under THAT app's appId.
+ */
+import { z } from 'zod';
+import { createPrefsClient } from '@wolffm/prefs-client';
+import { resolvePrefsApiBase } from './prefsApiBase.js';
+// Turn off Zod's JIT before the schema below is CONSTRUCTED. Building a
+// z.object runs Zod v4's one-time `allowsEval` probe — `new Function("")` —
+// and caches the answer. hadoku.me's CSP grants no 'unsafe-eval', so on every
+// page that loads this module the browser recorded a script-src violation
+// (harmless: Zod catches it and uses its non-JIT parser). This module is
+// evaluated before any app code, so only this module can get ahead of the
+// probe: an app calling config() later is too late (watchparty tried it and
+// verified it ineffective, 2026-10-05). The config lives on globalThis and is
+// shared by every Zod copy on the page. Issue: WolffM/hadoku-task#93.
+z.config({ jitless: true });
+export const ThemePrefsSchema = z.object({
+    theme: z.string().optional(),
+    themeMode: z.enum(['simple', 'advanced']).optional()
+});
+export const themePrefs = createPrefsClient({
+    appId: 'portfolio',
+    schema: ThemePrefsSchema,
+    // Undefined in production, so the SDK's own default applies. Set only by a
+    // local dev/E2E stack pointing at the real prefs-api on localhost — see
+    // ./prefsApiBase.
+    apiBase: resolvePrefsApiBase(),
+    // No default theme on purpose: an absent `theme` means "nothing persisted",
+    // so a fresh read never overrides the inline FOUC script's browser-preference
+    // fallback. We adopt the SDK theme only when it's actually present.
+    //
+    // Mirror theme to sessionStorage['hadoku-theme'] on every read so the inline
+    // <head> FOUC script keeps applying theme before React mounts.
+    bootstrapToSessionStorage: { theme: 'hadoku-theme' }
+});

package/dist/useRefElement.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The element a caller's `RefObject` points at, as state — so an effect can
+ * depend on it and re-run when it attaches.
+ *
+ * `useTheme` and `usePlatform` stamp attributes onto an app's container, and
+ * every app hands them a plain `useRef()` object. Assigning `ref.current` does
+ * not re-render anything, so an effect keyed on the ref object alone runs once
+ * and never learns that the div attached later. Task's container mounts only
+ * after its loading skeleton gives way, which left it without `data-theme`
+ * whenever the skeleton outlived the hook's first passes (#102).
+ *
+ * React attaches an object ref by writing `ref.current = el` during commit, so
+ * this swaps `current` for an accessor that turns that write into a state
+ * update. Callers keep passing what they pass today, which is the point: 16
+ * apps hand over a `RefObject`, and none of them has to change. The plain data
+ * property comes back on cleanup.
+ */
+import { type RefObject } from 'react';
+export declare function useRefElement<T extends Element>(ref?: RefObject<T | null>): T | null;

package/dist/useRefElement.js

@@ -0,0 +1,52 @@
+/**
+ * The element a caller's `RefObject` points at, as state — so an effect can
+ * depend on it and re-run when it attaches.
+ *
+ * `useTheme` and `usePlatform` stamp attributes onto an app's container, and
+ * every app hands them a plain `useRef()` object. Assigning `ref.current` does
+ * not re-render anything, so an effect keyed on the ref object alone runs once
+ * and never learns that the div attached later. Task's container mounts only
+ * after its loading skeleton gives way, which left it without `data-theme`
+ * whenever the skeleton outlived the hook's first passes (#102).
+ *
+ * React attaches an object ref by writing `ref.current = el` during commit, so
+ * this swaps `current` for an accessor that turns that write into a state
+ * update. Callers keep passing what they pass today, which is the point: 16
+ * apps hand over a `RefObject`, and none of them has to change. The plain data
+ * property comes back on cleanup.
+ */
+import { useEffect, useLayoutEffect, useState } from 'react';
+// useLayoutEffect, so the element is read before paint; useEffect on the server,
+// where neither runs but React 18 warns about the layout variant.
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+export function useRefElement(ref) {
+    const [element, setElement] = useState(null);
+    useIsomorphicLayoutEffect(() => {
+        if (!ref) {
+            setElement(null);
+            return;
+        }
+        // Refs attach child-first, before this parent's layout effect, so a
+        // container rendered in the same commit is already here.
+        let current = ref.current;
+        Object.defineProperty(ref, 'current', {
+            configurable: true,
+            enumerable: true,
+            get: () => current,
+            set: (next) => {
+                current = next;
+                setElement(next);
+            }
+        });
+        setElement(current);
+        return () => {
+            Object.defineProperty(ref, 'current', {
+                configurable: true,
+                enumerable: true,
+                writable: true,
+                value: current
+            });
+        };
+    }, [ref]);
+    return element;
+}

package/dist/useTheme.d.ts

@@ -0,0 +1,46 @@
+/**
+ * useTheme — the one theme hook for the hadoku ecosystem.
+ *
+ * WHAT THIS REPLACES
+ * ------------------
+ * Eight child apps each carried a hand-copied `src/hooks/useTheme.ts`, because
+ * the version this package used to ship was strictly weaker than what an app
+ * actually needs: no cross-device persistence, no container mirroring for
+ * micro-frontend mounts, no FOUC gating, no system-preference auto-switch, no
+ * validation that the theme is even available. So everyone wrote their own, and
+ * the copies drifted on real behaviour — `hadoku-pygmalion` wrote localStorage
+ * (so a browser restart kept the theme and repainted correctly), while
+ * `hadoku-jobplatform` wrote only sessionStorage and lost it. Same file, same
+ * comments, one had the fix.
+ *
+ * This is the union of those copies, with the localStorage behaviour taken as
+ * canonical (see `saveTheme` in ./index).
+ *
+ * PERSISTENCE, THREE LAYERS
+ * -------------------------
+ *   sessionStorage — what the pre-paint inline <head> script reads; per tab.
+ *   localStorage   — what survives a browser restart, so the NEXT cold load
+ *                    paints the right theme directly with no default-then-swap.
+ *   prefs (device) — cross-device, via @wolffm/prefs-client; resolves async.
+ *
+ * The async layer is why `userOverrodeRef` exists: a late prefs resolve must
+ * not yank the user back to the previously persisted theme if they've already
+ * picked a new one this session.
+ */
+import { type RefObject } from 'react';
+export interface UseThemeOptions {
+    /** Theme forced by a parent shell. When set, it wins over everything and the
+     *  cross-device adopt is skipped (the shell already plumbed the SDK read). */
+    propsTheme?: string;
+    /** Mirror `data-theme` onto a container element as well as <html>, for
+     *  micro-frontend mounts that are styled within their own subtree. */
+    containerRef?: RefObject<HTMLElement | null>;
+}
+export declare function useTheme(options?: UseThemeOptions): {
+    theme: string;
+    setTheme: (next: string) => void;
+    themeFamilies: import("./theme-types").ThemeFamily[];
+    isDarkTheme: boolean;
+    isThemeReady: boolean;
+    isInitialThemeLoad: boolean;
+};

package/dist/useTheme.js

@@ -0,0 +1,216 @@
+/**
+ * useTheme — the one theme hook for the hadoku ecosystem.
+ *
+ * WHAT THIS REPLACES
+ * ------------------
+ * Eight child apps each carried a hand-copied `src/hooks/useTheme.ts`, because
+ * the version this package used to ship was strictly weaker than what an app
+ * actually needs: no cross-device persistence, no container mirroring for
+ * micro-frontend mounts, no FOUC gating, no system-preference auto-switch, no
+ * validation that the theme is even available. So everyone wrote their own, and
+ * the copies drifted on real behaviour — `hadoku-pygmalion` wrote localStorage
+ * (so a browser restart kept the theme and repainted correctly), while
+ * `hadoku-jobplatform` wrote only sessionStorage and lost it. Same file, same
+ * comments, one had the fix.
+ *
+ * This is the union of those copies, with the localStorage behaviour taken as
+ * canonical (see `saveTheme` in ./index).
+ *
+ * PERSISTENCE, THREE LAYERS
+ * -------------------------
+ *   sessionStorage — what the pre-paint inline <head> script reads; per tab.
+ *   localStorage   — what survives a browser restart, so the NEXT cold load
+ *                    paints the right theme directly with no default-then-swap.
+ *   prefs (device) — cross-device, via @wolffm/prefs-client; resolves async.
+ *
+ * The async layer is why `userOverrodeRef` exists: a late prefs resolve must
+ * not yank the user back to the previously persisted theme if they've already
+ * picked a new one this session.
+ */
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { usePrefs } from '@wolffm/prefs-client/react';
+import { setTheme as applyTheme, saveTheme, setThemeMode } from './index.js';
+import { THEME_FAMILIES } from './metadata.js';
+import { themePrefs } from './themePrefs.js';
+import { useRefElement } from './useRefElement.js';
+/** Bare family token → its light/dark pair, e.g. 'coffee' → coffee-light /
+ *  coffee-dark. Base 'light'/'dark' are already fully qualified and are matched
+ *  before this map is consulted. */
+const FAMILY_VARIANTS = new Map(THEME_FAMILIES.map(f => [
+    f.lightTheme.replace(/-light$/, ''),
+    { light: f.lightTheme, dark: f.darkTheme }
+]));
+function prefersDark() {
+    return typeof window !== 'undefined' && window.matchMedia
+        ? window.matchMedia('(prefers-color-scheme: dark)').matches
+        : false;
+}
+/**
+ * Normalize a raw theme value from the shared 'hadoku-theme' key (or a
+ * push-down StorageEvent) to a fully-qualified theme name.
+ *
+ * The hadoku.me host page may store a BARE FAMILY TOKEN — 'coffee', not
+ * 'coffee-light' — leaving the variant to the embedding app's colour scheme.
+ * Without this expansion such a value is not a real theme, so the validity
+ * check downstream discards it and the app silently lands on 'light',
+ * ignoring the theme the host asked for. Returns null for anything
+ * unrecognized so callers fall back to their own default rather than to a
+ * value that just happens to be in storage.
+ */
+function normalizeThemeName(value) {
+    const raw = value?.trim();
+    if (!raw)
+        return null;
+    if (THEME_FAMILIES.some(f => f.lightTheme === raw || f.darkTheme === raw))
+        return raw;
+    const variants = FAMILY_VARIANTS.get(raw);
+    if (variants)
+        return prefersDark() ? variants.dark : variants.light;
+    return null;
+}
+/** Seed the theme before any async source resolves. Order matters: whatever the
+ *  pre-paint script already put on <html> beats storage, because that is what
+ *  the user is currently LOOKING at — re-deriving it from storage risks a swap
+ *  in the first frame for no reason. */
+function seedTheme(propsTheme) {
+    if (propsTheme)
+        return propsTheme;
+    if (typeof document === 'undefined')
+        return 'light';
+    const painted = normalizeThemeName(document.documentElement.getAttribute('data-theme'));
+    if (painted)
+        return painted;
+    try {
+        const stored = normalizeThemeName(sessionStorage.getItem('hadoku-theme') ?? localStorage.getItem('hadoku-theme'));
+        if (stored)
+            return stored;
+    }
+    catch {
+        /* storage blocked — fall through to the browser preference */
+    }
+    return prefersDark() ? 'dark' : 'light';
+}
+export function useTheme(options = {}) {
+    const { propsTheme, containerRef } = options;
+    // State, not the ref: the container can attach after the first apply (#102).
+    const container = useRefElement(containerRef);
+    const [theme, setThemeState] = useState(() => seedTheme(propsTheme));
+    const [isThemeReady, setIsThemeReady] = useState(false);
+    const [isInitialThemeLoad, setIsInitialThemeLoad] = useState(true);
+    // Cross-device row. `save` comes from the hook (not the module) so the SDK
+    // can update its in-memory cache — using the module-level save let a stale
+    // snapshot race back into state.
+    const { prefs: persisted, save: savePrefs } = usePrefs(themePrefs);
+    // savePrefs' identity is not stable across renders, and `setTheme` is a
+    // dependency of the media-query effect below. Reading it through a ref keeps
+    // setTheme referentially stable forever, so that effect re-subscribes only
+    // when the theme actually changes rather than on every render. Declared up
+    // here because every setter below closes over it.
+    const savePrefsRef = useRef(savePrefs);
+    useEffect(() => {
+        savePrefsRef.current = savePrefs;
+    });
+    // True once the user has picked a theme this session, so a late prefs
+    // resolve doesn't overwrite their choice.
+    const userOverrodeRef = useRef(false);
+    const isThemeAvailable = useCallback((name) => THEME_FAMILIES.some(f => f.lightTheme === name || f.darkTheme === name), []);
+    const setTheme = useCallback((next) => {
+        setThemeState(next);
+        userOverrodeRef.current = true;
+        // Synchronous local write first: it is what preserves no-FOUC and same-tab
+        // behaviour regardless of whether the network write lands.
+        saveTheme(next);
+        savePrefsRef.current({ theme: next }, { scope: 'device' }).catch((err) => {
+            // Logged, never swallowed — silent save failures were the original
+            // "my theme keeps resetting" bug. This package stays free of the logger
+            // dependency, so console is the sink.
+            console.error('[useTheme] prefs save failed', {
+                error: err?.message ?? String(err),
+                theme: next
+            });
+        });
+    }, []);
+    // Another tab changing the theme should be reflected here.
+    useEffect(() => {
+        const onStorage = (e) => {
+            if (e.key !== 'hadoku-theme' || userOverrodeRef.current)
+                return;
+            // Same normalization as the seed: the host pushes down bare family
+            // tokens too, and an unrecognized value must leave the current theme
+            // alone rather than knock it back to the default.
+            const next = normalizeThemeName(e.newValue);
+            if (next)
+                setThemeState(next);
+        };
+        window.addEventListener('storage', onStorage);
+        return () => window.removeEventListener('storage', onStorage);
+    }, []);
+    // Apply to the DOM.
+    useEffect(() => {
+        const valid = isThemeAvailable(theme) ? theme : 'light';
+        document.documentElement.setAttribute('data-theme', valid);
+        // Micro-frontend mounts style within their own subtree.
+        container?.setAttribute('data-theme', valid);
+        applyTheme(valid);
+        // Advanced visuals are switched off platform-wide: the Simple/Advanced
+        // toggle is gone from the picker, so nothing can turn them on. The kit
+        // (advanced.css, THEME_EFFECTS, the hdk-advanced-* classes in JSX) is
+        // still shipped and still keyed off this attribute — pinning it to
+        // 'simple' is what keeps every surface flat. Restoring the toggle is the
+        // only thing needed to bring advanced back.
+        setThemeMode('simple');
+        // Delay "ready" on the very first pass so consumers can gate a fade-in
+        // and avoid a flash of unstyled content.
+        if (isInitialThemeLoad) {
+            const timer = setTimeout(() => {
+                setIsThemeReady(true);
+                setIsInitialThemeLoad(false);
+            }, 50);
+            return () => clearTimeout(timer);
+        }
+        setIsThemeReady(true);
+    }, [theme, container, isInitialThemeLoad, isThemeAvailable]);
+    // Adopt the cross-device theme once the SDK resolves — unless the parent
+    // shell forced one, or the user already chose this session.
+    useEffect(() => {
+        if (propsTheme)
+            return;
+        if (userOverrodeRef.current)
+            return;
+        const remote = persisted?.theme;
+        if (remote && remote !== theme && isThemeAvailable(remote)) {
+            setThemeState(remote);
+            // Cache it locally so the NEXT cold load's pre-paint script paints it
+            // directly instead of defaulting and swapping.
+            saveTheme(remote);
+        }
+    }, [persisted?.theme, propsTheme, theme, isThemeAvailable]);
+    // Follow the OS light/dark switch WITHIN the active family, so someone on
+    // `coffee-light` moves to `coffee-dark` at sunset rather than to plain dark.
+    // Base light/dark are left alone — those are explicit choices, not families.
+    useEffect(() => {
+        // jsdom and SSR have no matchMedia, so there is no OS preference to follow.
+        if (typeof window === 'undefined' || !window.matchMedia)
+            return;
+        const mq = window.matchMedia('(prefers-color-scheme: dark)');
+        const onChange = (e) => {
+            const family = theme.replace(/-light$|-dark$/, '');
+            if (family === 'light' || family === 'dark')
+                return;
+            const current = theme.endsWith('-dark') ? 'dark' : 'light';
+            const target = e.matches ? 'dark' : 'light';
+            if (current !== target)
+                setTheme(`${family}-${target}`);
+        };
+        mq.addEventListener('change', onChange);
+        return () => mq.removeEventListener('change', onChange);
+    }, [theme, setTheme]);
+    return {
+        theme,
+        setTheme,
+        themeFamilies: THEME_FAMILIES,
+        isDarkTheme: theme.endsWith('-dark') || theme === 'dark',
+        isThemeReady,
+        isInitialThemeLoad
+    };
+}