@gusnips/react 0.9.6 → 0.9.7

package/README.md

@@ -141,6 +141,11 @@ Choose the words by `code` (GoTrue's `error_code`, such as `otp_expired`), not b
 pressing Cancel at Google; only the last one arrives with no code, and that is what `cancelled`
 means. A cancel was their choice, so say nothing or offer the button again.
 
+A handler you mount for Google's refusals also receives every email link's. An expired magic link
+or reset link comes back with the same parameters, to whatever page `redirectTo` named. If that
+handler only knows Google copy, the person whose link ran out is told Google failed. Check `code`
+before you reach for provider copy: `otp_expired` is a link, never a provider.
+
 Every email link type is accepted, `invite` included, even if your templates never send it. An
 operator can still send one from Studio. Name a destination for each with
 `Record<EmailLinkType, string>`, so a new type is a compile error rather than a wrong page.
@@ -333,6 +338,55 @@ Some APIs write `message` for whoever reads the screen. Some write it for whoeve
 in English, in an app that ships three languages. Your arm also gets the stated wait, which the
 default has nowhere to put.
 
+## Light, dark, or the system's
+
+```ts
+const { mode, resolved, setMode } = useTheme();
+```
+
+`mode` is what the person picked: `"light"`, `"dark"` or `"system"`. `resolved` is what is on
+screen. `setMode("dark")` switches, saves the choice, and every other open tab follows.
+
+You make `useTheme` once, with the storage key your app already uses:
+
+```ts
+// src/theme.ts
+import { createTheme, type ThemeOptions } from "@gusnips/react/theme";
+
+export const THEME = { key: "app.theme" } satisfies ThemeOptions;
+export const { useTheme } = createTheme(THEME);
+```
+
+Then give the same options to the Vite plugin, which paints the page in the right theme before
+its first frame. Without it, a reader who chose dark sees one light frame on every load.
+
+```ts
+// vite.config.ts
+import { themeScript } from "@gusnips/vite/theme";
+import { THEME } from "./src/theme";
+
+export default defineConfig({ plugins: [themeScript(THEME)] });
+```
+
+What it does that the copies it replaced each missed at least once:
+
+- A browser that blocks site data throws when you touch `localStorage`. Here that is not a white
+  page: the default applies, and a choice made after that lasts until the page is left.
+- The script that runs before paint is not a second copy. The plugin writes this function's own
+  source into a file, so the two cannot disagree about a stale value or blocked storage.
+- That file is a real file, not an inline script, so a `script-src 'self'` policy lets it run.
+  An inline one under that policy never runs, and nothing tells you.
+- `"system"` follows the OS live, even when the person switched to it mid-page. A laptop that
+  turns dark at sunset takes the page with it.
+- `themeColor: { light: "#fff", dark: "#111" }` moves `<meta name="theme-color">` too, so the
+  browser toolbar matches the page instead of the OS.
+- `attribute: "data-theme"` writes `data-theme="dark"` instead of the `dark` class, and
+  `defaultMode` picks what an empty key means (`"system"` unless you say otherwise).
+
+In jsdom tests, mock `window.matchMedia`, which jsdom does not have, and run
+`delete window.__frontkitTheme` between tests. There is one controller per page, and a jsdom
+window lasts the whole file.
+
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
@@ -406,6 +460,7 @@ lives behind a subpath, so you install a dependency only if you import the thing
 | `@gusnips/react/supabase` | the session adapter, `parseAuthCallback` | @supabase/supabase-js |
 | `@gusnips/react/ui`       | the seven wrappers                       | @base-ui/react        |
 | `@gusnips/react/contract` | two prerender names                      | nothing               |
+| `@gusnips/react/theme`    | `createTheme`, `startTheme`              | react                 |
 
 The rule behind that table: **a peer marked optional must not be reachable from the main entry
 point.** An optional peer the barrel imports anyway is not optional — it is a required one whose

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -13,6 +13,8 @@
 //   @gusnips/react/guards    the route guards       → react-router-dom
 //   @gusnips/react/hydrate   hydrateOrMount         → react-dom
 //   @gusnips/react/supabase  the session adapter    → @supabase/supabase-js
+//   @gusnips/react/theme     the theme controller   → react only, but `@gusnips/vite/theme`
+//                                                    serializes it and must not load the rest
 //
 // `react-dom` is the one the second migration added, and it is the sharpest case yet: that
 // adopter ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GAQb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,4FAA4F;AAC5F,8FAA8F;AAC9F,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GAQb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/dist/theme.d.ts

@@ -0,0 +1,90 @@
+/** What a person picked. `"system"` means "follow the operating system", live. */
+export type ThemeMode = "light" | "dark" | "system";
+/** What is on screen right now. */
+export type ResolvedTheme = "light" | "dark";
+export interface ThemeOptions {
+    /**
+     * The `localStorage` key holding the choice. Keep the key your app already uses: a new key
+     * resets everybody's choice once.
+     */
+    key: string;
+    /**
+     * What an empty, unreadable or unrecognised key means. Defaults to `"system"`.
+     */
+    defaultMode?: ThemeMode;
+    /**
+     * Where the resolved theme goes on `<html>`. `"class"` toggles `dark`, which is what
+     * Tailwind's `dark:` variant and `@gusnips/tokens` read. `"data-theme"` writes `"light"` or
+     * `"dark"` into that attribute, for a stylesheet whose `@custom-variant` reads it. Defaults
+     * to `"class"`.
+     */
+    attribute?: "class" | "data-theme";
+    /**
+     * The browser toolbar colour for each theme, written to every `<meta name="theme-color">`.
+     * Leave it out and the tags are not touched. It is needed whenever the choice can differ from
+     * the OS setting: a `media` query on the tag follows the OS, not your app.
+     */
+    themeColor?: Readonly<Record<ResolvedTheme, string>>;
+}
+export interface ThemeSnapshot {
+    readonly mode: ThemeMode;
+    readonly resolved: ResolvedTheme;
+}
+export interface ThemeController {
+    getSnapshot(): ThemeSnapshot;
+    /** Applies at once, and is remembered when storage allows it. */
+    setMode(mode: ThemeMode): void;
+    subscribe(listener: () => void): () => void;
+}
+declare global {
+    interface Window {
+        /** The page's one theme controller. See {@link startTheme}. */
+        __frontkitTheme?: ThemeController;
+    }
+}
+/**
+ * Reads the choice, paints it, and keeps it painted: when the OS switches (a laptop that goes
+ * dark at sunset), when another tab picks a theme, and when the page comes back from the
+ * back-forward cache.
+ *
+ * **This function is serialized.** `@gusnips/vite/theme` writes `startTheme.toString()` into the
+ * pre-paint file, so it must not reference anything outside its own body: no imports, no helpers
+ * or constants from this module. It would still pass here and throw a `ReferenceError` in that
+ * file, before first paint. The vite package's test runs the serialized copy in a bare context
+ * to catch that. Comments go up here rather than in the body, because the body ships.
+ *
+ * **One per page.** The first call stores the controller on `window` and later calls return it,
+ * whatever options they pass. Two would both follow the OS, and the one that missed a `setMode`
+ * would repaint its stale choice on the next change. So the pre-paint script and the app must
+ * pass the same options, which is easiest when both import them from one module.
+ *
+ * **Blocked storage is not an empty key.** When storage throws, the default applies at boot, and
+ * a choice made afterwards lasts until the page is left. A resync never replaces that choice
+ * with the default, because a read that failed says nothing about what was chosen.
+ *
+ * "system" is stored as the word, not as an empty key. An empty key means the default, and the
+ * default is not always "system".
+ */
+export declare function startTheme(options: ThemeOptions): ThemeController;
+export interface Theme {
+    /** The choice and what it resolves to, re-rendering when either changes. */
+    useTheme(): ThemeSnapshot & {
+        setMode(mode: ThemeMode): void;
+    };
+    /** For code outside React: a keyboard shortcut, a command palette. Browser only. */
+    setMode(mode: ThemeMode): void;
+    /** For code outside React. Answers the prerender snapshot where there is no window. */
+    getSnapshot(): ThemeSnapshot;
+}
+/**
+ * The React side of {@link startTheme}. Nothing starts at import, so a module calling this at
+ * its top level is safe to prerender. The controller starts on first use, or is found if the
+ * pre-paint script already started it.
+ *
+ * During a prerender, and while hydrating, `useTheme` answers the default. `"system"` cannot be
+ * resolved without a window, so it reads as light, as `color-scheme` does before the pre-paint
+ * script runs. React then re-renders with the real snapshot, so a toggle hydrates cleanly and
+ * shows the right choice a frame later instead of failing to hydrate.
+ */
+export declare function createTheme(options: ThemeOptions): Theme;
+//# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAsCA,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD,mCAAmC;AACnC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,IAAI,aAAa,CAAC;IAC7B,iEAAiE;IACjE,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,+DAA+D;QAC/D,eAAe,CAAC,EAAE,eAAe,CAAC;KACnC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,CAsEjE;AAED,MAAM,WAAW,KAAK;IACpB,4EAA4E;IAC5E,QAAQ,IAAI,aAAa,GAAG;QAAE,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;KAAE,CAAC;IAC/D,oFAAoF;IACpF,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAC/B,uFAAuF;IACvF,WAAW,IAAI,aAAa,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,KAAK,CAiBxD"}

package/dist/theme.js

@@ -0,0 +1,160 @@
+/**
+ * Light, dark, or whatever the operating system says — chosen once, remembered, and painted
+ * before the first frame.
+ *
+ * Nearly every app in the fleet had written this on its own, and each copy knew something the
+ * others did not. What they got wrong is the design brief for this file:
+ *
+ * - **Storage is read unguarded.** A browser that blocks site data throws on `localStorage`
+ *   itself, and the read ran during a render, so a privacy setting was a white page. Apps fixed
+ *   this one at a time, and the last copy still had it.
+ * - **The pre-paint script and the runtime disagreed.** Most apps kept two copies of "read the
+ *   key, resolve system, set the class": an inline script in `index.html`, because it has to run
+ *   before any module loads, and the store the app renders from. They drifted on exactly the
+ *   inputs nobody tests. With storage blocked one forced light while the other followed the OS,
+ *   and with a stale value in the key one read it as light while the other read it as system.
+ *   Either way the page painted one theme, and React swapped it for the other one frame later.
+ *   One app had written a build check that the two copies at least named the same key.
+ * - **The OS preference started as a guess.** A provider that holds the OS preference in state,
+ *   starting at `"light"` and correcting it in an effect, commits a light frame first. That
+ *   frame REMOVES the `.dark` class the pre-paint script had just set, so a reader whose OS is
+ *   dark sees a flash on every load.
+ * - **The pre-paint script was inline, and a strict CSP blocks inline scripts.** Under
+ *   `script-src 'self'` it never ran in production: the app booted light and turned dark a frame
+ *   later. A CSP hash works until the first whitespace change silently breaks it again.
+ * - **Another tab's choice was ignored.** A tab left open kept the old theme until it reloaded.
+ *   One app did listen for `storage`, then re-read its own page, which the other tab had not
+ *   changed.
+ *
+ * So there is ONE function, {@link startTheme}. The page runs it before first paint and the app
+ * uses it after React mounts. `@gusnips/vite/theme` serves it as a same-origin FILE, built from
+ * this function's own source, so the two cannot drift and a strict CSP allows it. The runtime
+ * the pre-paint script creates is also the one the app talks to: {@link createTheme} finds it
+ * rather than starting a second one.
+ *
+ * What stays in the app: the control (three buttons, a menu, a switch) and its words.
+ */
+import { useSyncExternalStore } from "react";
+/**
+ * Reads the choice, paints it, and keeps it painted: when the OS switches (a laptop that goes
+ * dark at sunset), when another tab picks a theme, and when the page comes back from the
+ * back-forward cache.
+ *
+ * **This function is serialized.** `@gusnips/vite/theme` writes `startTheme.toString()` into the
+ * pre-paint file, so it must not reference anything outside its own body: no imports, no helpers
+ * or constants from this module. It would still pass here and throw a `ReferenceError` in that
+ * file, before first paint. The vite package's test runs the serialized copy in a bare context
+ * to catch that. Comments go up here rather than in the body, because the body ships.
+ *
+ * **One per page.** The first call stores the controller on `window` and later calls return it,
+ * whatever options they pass. Two would both follow the OS, and the one that missed a `setMode`
+ * would repaint its stale choice on the next change. So the pre-paint script and the app must
+ * pass the same options, which is easiest when both import them from one module.
+ *
+ * **Blocked storage is not an empty key.** When storage throws, the default applies at boot, and
+ * a choice made afterwards lasts until the page is left. A resync never replaces that choice
+ * with the default, because a read that failed says nothing about what was chosen.
+ *
+ * "system" is stored as the word, not as an empty key. An empty key means the default, and the
+ * default is not always "system".
+ */
+export function startTheme(options) {
+    const running = window.__frontkitTheme;
+    if (running)
+        return running;
+    const { key, defaultMode = "system", attribute = "class", themeColor } = options;
+    const media = window.matchMedia("(prefers-color-scheme: dark)");
+    const listeners = new Set();
+    const isMode = (value) => value === "light" || value === "dark" || value === "system";
+    const read = () => {
+        try {
+            const stored = window.localStorage.getItem(key);
+            return isMode(stored) ? stored : defaultMode;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const resolve = (mode) => mode === "system" ? (media.matches ? "dark" : "light") : mode;
+    const paint = (resolved) => {
+        const root = document.documentElement;
+        if (attribute === "class")
+            root.classList.toggle("dark", resolved === "dark");
+        else
+            root.setAttribute(attribute, resolved);
+        if (themeColor)
+            document
+                .querySelectorAll('meta[name="theme-color"]')
+                .forEach((meta) => meta.setAttribute("content", themeColor[resolved]));
+    };
+    const initial = read() ?? defaultMode;
+    let snapshot = { mode: initial, resolved: resolve(initial) };
+    const apply = (mode) => {
+        const resolved = resolve(mode);
+        paint(resolved);
+        if (mode === snapshot.mode && resolved === snapshot.resolved)
+            return;
+        snapshot = { mode, resolved };
+        listeners.forEach((listener) => listener());
+    };
+    const sync = () => {
+        const stored = read();
+        if (stored)
+            apply(stored);
+    };
+    paint(snapshot.resolved);
+    media.addEventListener("change", () => apply(snapshot.mode));
+    window.addEventListener("storage", (event) => {
+        if (event.key === key || event.key === null)
+            sync();
+    });
+    window.addEventListener("pageshow", sync);
+    const controller = {
+        getSnapshot: () => snapshot,
+        setMode(mode) {
+            if (!isMode(mode))
+                return;
+            try {
+                window.localStorage.setItem(key, mode);
+            }
+            catch {
+                // Blocked: the choice lasts until the page is left.
+            }
+            apply(mode);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    window.__frontkitTheme = controller;
+    return controller;
+}
+/**
+ * The React side of {@link startTheme}. Nothing starts at import, so a module calling this at
+ * its top level is safe to prerender. The controller starts on first use, or is found if the
+ * pre-paint script already started it.
+ *
+ * During a prerender, and while hydrating, `useTheme` answers the default. `"system"` cannot be
+ * resolved without a window, so it reads as light, as `color-scheme` does before the pre-paint
+ * script runs. React then re-renders with the real snapshot, so a toggle hydrates cleanly and
+ * shows the right choice a frame later instead of failing to hydrate.
+ */
+export function createTheme(options) {
+    const defaultMode = options.defaultMode ?? "system";
+    const serverSnapshot = {
+        mode: defaultMode,
+        resolved: defaultMode === "dark" ? "dark" : "light",
+    };
+    const subscribe = (listener) => startTheme(options).subscribe(listener);
+    const getSnapshot = () => typeof window === "undefined" ? serverSnapshot : startTheme(options).getSnapshot();
+    const getServerSnapshot = () => serverSnapshot;
+    const setMode = (mode) => startTheme(options).setMode(mode);
+    function useTheme() {
+        return { ...useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot), setMode };
+    }
+    return { useTheme, setMode, getSnapshot };
+}
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,10 @@
     "./contract": {
       "types": "./dist/prerender-contract.d.ts",
       "default": "./dist/prerender-contract.js"
+    },
+    "./theme": {
+      "types": "./dist/theme.d.ts",
+      "default": "./dist/theme.js"
     }
   },
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -13,6 +13,8 @@
 //   @gusnips/react/guards    the route guards       → react-router-dom
 //   @gusnips/react/hydrate   hydrateOrMount         → react-dom
 //   @gusnips/react/supabase  the session adapter    → @supabase/supabase-js
+//   @gusnips/react/theme     the theme controller   → react only, but `@gusnips/vite/theme`
+//                                                    serializes it and must not load the rest
 //
 // `react-dom` is the one the second migration added, and it is the sharpest case yet: that
 // adopter ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to

package/src/theme.test.ts

@@ -0,0 +1,268 @@
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createTheme, startTheme, type ThemeOptions } from "./theme.ts";
+
+const KEY = "app.theme";
+
+/**
+ * The few globals the controller touches, stubbed rather than run under a DOM — the same call as
+ * `deploy-recovery.test.ts`. What matters is what a browser does at the edges: storage that
+ * throws from both methods when site data is blocked, an OS preference that changes under the
+ * page, and events from other tabs.
+ */
+function browser({
+  stored,
+  osDark = false,
+  blocked = false,
+  metas = 0,
+}: { stored?: string; osDark?: boolean; blocked?: boolean; metas?: number } = {}) {
+  const store = new Map<string, string>(stored === undefined ? [] : [[KEY, stored]]);
+  const state = { blocked };
+  const classes = new Set<string>();
+  const attributes = new Map<string, string>();
+  const media = { matches: osDark, listeners: [] as Array<() => void> };
+  const events = new Map<string, Array<(event: { key: string | null }) => void>>();
+  const themeColors = Array.from({ length: metas }, () => ({ content: "" }));
+
+  const fire = (type: string, event: { key: string | null } = { key: null }) =>
+    events.get(type)?.forEach((listener) => listener(event));
+
+  vi.stubGlobal("window", {
+    matchMedia: () => ({
+      get matches() {
+        return media.matches;
+      },
+      addEventListener: (_type: string, listener: () => void) => media.listeners.push(listener),
+    }),
+    localStorage: {
+      getItem: (key: string) => {
+        if (state.blocked) throw new Error("site data blocked");
+        return store.get(key) ?? null;
+      },
+      setItem: (key: string, value: string) => {
+        if (state.blocked) throw new Error("site data blocked");
+        store.set(key, value);
+      },
+    },
+    addEventListener: (type: string, listener: (event: { key: string | null }) => void) =>
+      events.set(type, [...(events.get(type) ?? []), listener]),
+  });
+  vi.stubGlobal("document", {
+    documentElement: {
+      classList: {
+        toggle: (name: string, on: boolean) => (on ? classes.add(name) : classes.delete(name)),
+      },
+      setAttribute: (name: string, value: string) => attributes.set(name, value),
+    },
+    querySelectorAll: () =>
+      themeColors.map((meta) => ({
+        setAttribute: (_name: string, value: string) => (meta.content = value),
+      })),
+  });
+
+  return {
+    store,
+    themeColors,
+    dark: () => classes.has("dark"),
+    attribute: (name: string) => attributes.get(name),
+    osSwitches(dark: boolean) {
+      media.matches = dark;
+      media.listeners.forEach((listener) => listener());
+    },
+    /** Another tab wrote the key: `storage` fires here, never in the tab that wrote it. */
+    otherTabPicks(value: string) {
+      store.set(KEY, value);
+      fire("storage", { key: KEY });
+    },
+    storageEvent: (key: string | null) => fire("storage", { key }),
+    backForwardRestore: () => fire("pageshow"),
+    block: () => (state.blocked = true),
+  };
+}
+
+const options: ThemeOptions = { key: KEY };
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("startTheme", () => {
+  it("paints the stored choice the moment it starts", () => {
+    const page = browser({ stored: "dark" });
+    expect(startTheme(options).getSnapshot()).toEqual({ mode: "dark", resolved: "dark" });
+    expect(page.dark()).toBe(true);
+  });
+
+  it("follows the OS while the choice is system, live — and only then", () => {
+    const page = browser({ stored: "system", osDark: true });
+    const theme = startTheme(options);
+    expect(page.dark()).toBe(true);
+
+    page.osSwitches(false);
+    expect(theme.getSnapshot()).toEqual({ mode: "system", resolved: "light" });
+    expect(page.dark()).toBe(false);
+
+    theme.setMode("dark");
+    page.osSwitches(false);
+    expect(page.dark()).toBe(true);
+  });
+
+  // A choice made later in the same page must still follow the OS. A listener attached only
+  // when the page started in "system" would miss every switch after that.
+  it("follows the OS after switching to system mid-page", () => {
+    const page = browser({ stored: "light" });
+    const theme = startTheme(options);
+    theme.setMode("system");
+    page.osSwitches(true);
+    expect(page.dark()).toBe(true);
+  });
+
+  it("reads an empty key, and one holding anything else, as the default", () => {
+    browser({ stored: "blue" });
+    expect(startTheme({ key: KEY, defaultMode: "dark" }).getSnapshot().mode).toBe("dark");
+  });
+
+  // The white page: storage throws on read, during the first render. The default has to apply,
+  // following the OS like any other "system".
+  it("starts on the default when storage is blocked, instead of throwing", () => {
+    const page = browser({ blocked: true, osDark: true });
+    expect(startTheme(options).getSnapshot()).toEqual({ mode: "system", resolved: "dark" });
+    expect(page.dark()).toBe(true);
+  });
+
+  it("keeps a choice made under blocked storage when the page resyncs", () => {
+    const page = browser({ blocked: true });
+    const theme = startTheme(options);
+    theme.setMode("dark");
+    // A failed read says nothing about what was chosen, so it must not reset to the default.
+    page.backForwardRestore();
+    page.storageEvent(KEY);
+    expect(theme.getSnapshot().mode).toBe("dark");
+    expect(page.dark()).toBe(true);
+  });
+
+  it("repaints when another tab picks, and tells subscribers", () => {
+    const page = browser({ stored: "light" });
+    const theme = startTheme(options);
+    const listener = vi.fn();
+    theme.subscribe(listener);
+
+    page.otherTabPicks("dark");
+    expect(page.dark()).toBe(true);
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores another key, and resyncs when storage is cleared", () => {
+    const page = browser({ stored: "dark" });
+    const theme = startTheme(options);
+    page.store.set(KEY, "light");
+    page.storageEvent("some.other.key");
+    expect(theme.getSnapshot().mode).toBe("dark");
+
+    page.store.clear();
+    page.storageEvent(null);
+    expect(theme.getSnapshot().mode).toBe("system");
+  });
+
+  it("picks up a choice made while this page sat in the back-forward cache", () => {
+    const page = browser({ stored: "light" });
+    const theme = startTheme(options);
+    page.store.set(KEY, "dark");
+    page.backForwardRestore();
+    expect(theme.getSnapshot().mode).toBe("dark");
+  });
+
+  // An empty key means the DEFAULT, and the default is not always "system". Clearing the key
+  // for "system" in an app that defaults to dark would come back dark on the next visit.
+  it("stores system as the word, so it survives a non-system default", () => {
+    const page = browser();
+    startTheme({ key: KEY, defaultMode: "dark" }).setMode("system");
+    expect(page.store.get(KEY)).toBe("system");
+  });
+
+  it("still applies a choice when storage refuses to keep it", () => {
+    const page = browser({ stored: "light" });
+    const theme = startTheme(options);
+    page.block();
+    expect(() => theme.setMode("dark")).not.toThrow();
+    expect(page.dark()).toBe(true);
+  });
+
+  it("ignores a mode it does not know, rather than storing it", () => {
+    const page = browser({ stored: "light" });
+    const theme = startTheme(options);
+    const fromASelect: string = "blue";
+    theme.setMode(fromASelect as "dark");
+    expect(page.store.get(KEY)).toBe("light");
+    expect(theme.getSnapshot().mode).toBe("light");
+  });
+
+  it("notifies only on a change, and stops after unsubscribing", () => {
+    const page = browser({ stored: "dark" });
+    const theme = startTheme(options);
+    const listener = vi.fn();
+    const unsubscribe = theme.subscribe(listener);
+
+    theme.setMode("dark");
+    page.osSwitches(true);
+    expect(listener).not.toHaveBeenCalled();
+
+    unsubscribe();
+    theme.setMode("light");
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("writes data-theme both ways when asked to", () => {
+    const page = browser({ stored: "dark" });
+    const theme = startTheme({ key: KEY, attribute: "data-theme" });
+    expect(page.attribute("data-theme")).toBe("dark");
+    expect(page.dark()).toBe(false);
+    theme.setMode("light");
+    expect(page.attribute("data-theme")).toBe("light");
+  });
+
+  // Both tags, whatever their `media`: a query on the tag follows the OS, and the reader may have
+  // picked the opposite of it.
+  it("moves every theme-color tag with the theme", () => {
+    const page = browser({ stored: "light", metas: 2 });
+    const theme = startTheme({ key: KEY, themeColor: { light: "#fff", dark: "#111" } });
+    expect(page.themeColors.map((meta) => meta.content)).toEqual(["#fff", "#fff"]);
+    theme.setMode("dark");
+    expect(page.themeColors.map((meta) => meta.content)).toEqual(["#111", "#111"]);
+  });
+
+  // Two controllers would both follow the OS, and the one that missed a `setMode` would repaint
+  // its stale choice on the next switch.
+  it("runs once per page — the pre-paint script's controller is the app's", () => {
+    const page = browser({ stored: "light" });
+    const prePaint = startTheme(options);
+    const { setMode, getSnapshot } = createTheme(options);
+    expect(startTheme(options)).toBe(prePaint);
+
+    setMode("dark");
+    page.osSwitches(false);
+    expect(prePaint.getSnapshot().mode).toBe("dark");
+    expect(getSnapshot().mode).toBe("dark");
+    expect(page.dark()).toBe(true);
+  });
+});
+
+describe("createTheme", () => {
+  // A module that calls `createTheme` at its top level is imported by the prerender too, where
+  // there is no window. Nothing may start until something asks.
+  it("touches no browser global at creation, and prerenders the default", () => {
+    const { useTheme, getSnapshot } = createTheme({ key: KEY, defaultMode: "dark" });
+    expect(getSnapshot()).toEqual({ mode: "dark", resolved: "dark" });
+
+    function Toggle() {
+      const { mode, resolved } = useTheme();
+      return createElement("span", null, `${mode}/${resolved}`);
+    }
+    expect(renderToString(createElement(Toggle))).toContain("dark/dark");
+  });
+
+  it("prerenders system as light, the same guess color-scheme makes", () => {
+    expect(createTheme(options).getSnapshot()).toEqual({ mode: "system", resolved: "light" });
+  });
+});

package/src/theme.ts

@@ -0,0 +1,220 @@
+/**
+ * Light, dark, or whatever the operating system says — chosen once, remembered, and painted
+ * before the first frame.
+ *
+ * Nearly every app in the fleet had written this on its own, and each copy knew something the
+ * others did not. What they got wrong is the design brief for this file:
+ *
+ * - **Storage is read unguarded.** A browser that blocks site data throws on `localStorage`
+ *   itself, and the read ran during a render, so a privacy setting was a white page. Apps fixed
+ *   this one at a time, and the last copy still had it.
+ * - **The pre-paint script and the runtime disagreed.** Most apps kept two copies of "read the
+ *   key, resolve system, set the class": an inline script in `index.html`, because it has to run
+ *   before any module loads, and the store the app renders from. They drifted on exactly the
+ *   inputs nobody tests. With storage blocked one forced light while the other followed the OS,
+ *   and with a stale value in the key one read it as light while the other read it as system.
+ *   Either way the page painted one theme, and React swapped it for the other one frame later.
+ *   One app had written a build check that the two copies at least named the same key.
+ * - **The OS preference started as a guess.** A provider that holds the OS preference in state,
+ *   starting at `"light"` and correcting it in an effect, commits a light frame first. That
+ *   frame REMOVES the `.dark` class the pre-paint script had just set, so a reader whose OS is
+ *   dark sees a flash on every load.
+ * - **The pre-paint script was inline, and a strict CSP blocks inline scripts.** Under
+ *   `script-src 'self'` it never ran in production: the app booted light and turned dark a frame
+ *   later. A CSP hash works until the first whitespace change silently breaks it again.
+ * - **Another tab's choice was ignored.** A tab left open kept the old theme until it reloaded.
+ *   One app did listen for `storage`, then re-read its own page, which the other tab had not
+ *   changed.
+ *
+ * So there is ONE function, {@link startTheme}. The page runs it before first paint and the app
+ * uses it after React mounts. `@gusnips/vite/theme` serves it as a same-origin FILE, built from
+ * this function's own source, so the two cannot drift and a strict CSP allows it. The runtime
+ * the pre-paint script creates is also the one the app talks to: {@link createTheme} finds it
+ * rather than starting a second one.
+ *
+ * What stays in the app: the control (three buttons, a menu, a switch) and its words.
+ */
+import { useSyncExternalStore } from "react";
+
+/** What a person picked. `"system"` means "follow the operating system", live. */
+export type ThemeMode = "light" | "dark" | "system";
+
+/** What is on screen right now. */
+export type ResolvedTheme = "light" | "dark";
+
+export interface ThemeOptions {
+  /**
+   * The `localStorage` key holding the choice. Keep the key your app already uses: a new key
+   * resets everybody's choice once.
+   */
+  key: string;
+  /**
+   * What an empty, unreadable or unrecognised key means. Defaults to `"system"`.
+   */
+  defaultMode?: ThemeMode;
+  /**
+   * Where the resolved theme goes on `<html>`. `"class"` toggles `dark`, which is what
+   * Tailwind's `dark:` variant and `@gusnips/tokens` read. `"data-theme"` writes `"light"` or
+   * `"dark"` into that attribute, for a stylesheet whose `@custom-variant` reads it. Defaults
+   * to `"class"`.
+   */
+  attribute?: "class" | "data-theme";
+  /**
+   * The browser toolbar colour for each theme, written to every `<meta name="theme-color">`.
+   * Leave it out and the tags are not touched. It is needed whenever the choice can differ from
+   * the OS setting: a `media` query on the tag follows the OS, not your app.
+   */
+  themeColor?: Readonly<Record<ResolvedTheme, string>>;
+}
+
+export interface ThemeSnapshot {
+  readonly mode: ThemeMode;
+  readonly resolved: ResolvedTheme;
+}
+
+export interface ThemeController {
+  getSnapshot(): ThemeSnapshot;
+  /** Applies at once, and is remembered when storage allows it. */
+  setMode(mode: ThemeMode): void;
+  subscribe(listener: () => void): () => void;
+}
+
+declare global {
+  interface Window {
+    /** The page's one theme controller. See {@link startTheme}. */
+    __frontkitTheme?: ThemeController;
+  }
+}
+
+/**
+ * Reads the choice, paints it, and keeps it painted: when the OS switches (a laptop that goes
+ * dark at sunset), when another tab picks a theme, and when the page comes back from the
+ * back-forward cache.
+ *
+ * **This function is serialized.** `@gusnips/vite/theme` writes `startTheme.toString()` into the
+ * pre-paint file, so it must not reference anything outside its own body: no imports, no helpers
+ * or constants from this module. It would still pass here and throw a `ReferenceError` in that
+ * file, before first paint. The vite package's test runs the serialized copy in a bare context
+ * to catch that. Comments go up here rather than in the body, because the body ships.
+ *
+ * **One per page.** The first call stores the controller on `window` and later calls return it,
+ * whatever options they pass. Two would both follow the OS, and the one that missed a `setMode`
+ * would repaint its stale choice on the next change. So the pre-paint script and the app must
+ * pass the same options, which is easiest when both import them from one module.
+ *
+ * **Blocked storage is not an empty key.** When storage throws, the default applies at boot, and
+ * a choice made afterwards lasts until the page is left. A resync never replaces that choice
+ * with the default, because a read that failed says nothing about what was chosen.
+ *
+ * "system" is stored as the word, not as an empty key. An empty key means the default, and the
+ * default is not always "system".
+ */
+export function startTheme(options: ThemeOptions): ThemeController {
+  const running = window.__frontkitTheme;
+  if (running) return running;
+
+  const { key, defaultMode = "system", attribute = "class", themeColor } = options;
+  const media = window.matchMedia("(prefers-color-scheme: dark)");
+  const listeners = new Set<() => void>();
+  const isMode = (value: unknown): value is ThemeMode =>
+    value === "light" || value === "dark" || value === "system";
+  const read = (): ThemeMode | undefined => {
+    try {
+      const stored = window.localStorage.getItem(key);
+      return isMode(stored) ? stored : defaultMode;
+    } catch {
+      return undefined;
+    }
+  };
+  const resolve = (mode: ThemeMode): ResolvedTheme =>
+    mode === "system" ? (media.matches ? "dark" : "light") : mode;
+  const paint = (resolved: ResolvedTheme) => {
+    const root = document.documentElement;
+    if (attribute === "class") root.classList.toggle("dark", resolved === "dark");
+    else root.setAttribute(attribute, resolved);
+    if (themeColor)
+      document
+        .querySelectorAll('meta[name="theme-color"]')
+        .forEach((meta) => meta.setAttribute("content", themeColor[resolved]));
+  };
+
+  const initial = read() ?? defaultMode;
+  let snapshot: ThemeSnapshot = { mode: initial, resolved: resolve(initial) };
+  const apply = (mode: ThemeMode) => {
+    const resolved = resolve(mode);
+    paint(resolved);
+    if (mode === snapshot.mode && resolved === snapshot.resolved) return;
+    snapshot = { mode, resolved };
+    listeners.forEach((listener) => listener());
+  };
+  const sync = () => {
+    const stored = read();
+    if (stored) apply(stored);
+  };
+
+  paint(snapshot.resolved);
+  media.addEventListener("change", () => apply(snapshot.mode));
+  window.addEventListener("storage", (event) => {
+    if (event.key === key || event.key === null) sync();
+  });
+  window.addEventListener("pageshow", sync);
+
+  const controller: ThemeController = {
+    getSnapshot: () => snapshot,
+    setMode(mode) {
+      if (!isMode(mode)) return;
+      try {
+        window.localStorage.setItem(key, mode);
+      } catch {
+        // Blocked: the choice lasts until the page is left.
+      }
+      apply(mode);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+  window.__frontkitTheme = controller;
+  return controller;
+}
+
+export interface Theme {
+  /** The choice and what it resolves to, re-rendering when either changes. */
+  useTheme(): ThemeSnapshot & { setMode(mode: ThemeMode): void };
+  /** For code outside React: a keyboard shortcut, a command palette. Browser only. */
+  setMode(mode: ThemeMode): void;
+  /** For code outside React. Answers the prerender snapshot where there is no window. */
+  getSnapshot(): ThemeSnapshot;
+}
+
+/**
+ * The React side of {@link startTheme}. Nothing starts at import, so a module calling this at
+ * its top level is safe to prerender. The controller starts on first use, or is found if the
+ * pre-paint script already started it.
+ *
+ * During a prerender, and while hydrating, `useTheme` answers the default. `"system"` cannot be
+ * resolved without a window, so it reads as light, as `color-scheme` does before the pre-paint
+ * script runs. React then re-renders with the real snapshot, so a toggle hydrates cleanly and
+ * shows the right choice a frame later instead of failing to hydrate.
+ */
+export function createTheme(options: ThemeOptions): Theme {
+  const defaultMode = options.defaultMode ?? "system";
+  const serverSnapshot: ThemeSnapshot = {
+    mode: defaultMode,
+    resolved: defaultMode === "dark" ? "dark" : "light",
+  };
+  const subscribe = (listener: () => void) => startTheme(options).subscribe(listener);
+  const getSnapshot = () =>
+    typeof window === "undefined" ? serverSnapshot : startTheme(options).getSnapshot();
+  const getServerSnapshot = () => serverSnapshot;
+  const setMode = (mode: ThemeMode) => startTheme(options).setMode(mode);
+
+  function useTheme() {
+    return { ...useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot), setMode };
+  }
+
+  return { useTheme, setMode, getSnapshot };
+}