@gusnips/react 0.9.5 → 0.9.7

package/src/supabase-session.test.ts

@@ -8,6 +8,7 @@ import { describe, expect, it, vi } from "vitest";
 import {
   createSupabaseSessionAdapter,
   isAuthOutage,
+  parseAuthCallback,
   type SupabaseSessionAuth,
 } from "./supabase-session.ts";
 
@@ -154,3 +155,70 @@ describe("isAuthOutage", () => {
     expect(isAuthOutage(unreadable)).toBe(false);
   });
 });
+
+describe("parseAuthCallback", () => {
+  it("reads an email link, including the types an app's templates may not send yet", () => {
+    expect(parseAuthCallback("?token_hash=pkce_abc&type=recovery")).toEqual({
+      kind: "email-link",
+      tokenHash: "pkce_abc",
+      type: "recovery",
+    });
+    // An operator can invite from Studio whatever the product does; rejecting the type put
+    // "invalid link" on a real, branded invitation.
+    expect(parseAuthCallback(new URLSearchParams("token_hash=abc&type=invite"))).toMatchObject({
+      kind: "email-link",
+      type: "invite",
+    });
+  });
+
+  it("refuses an email link whose type is missing or made up", () => {
+    expect(parseAuthCallback("?token_hash=abc")).toEqual({ kind: "invalid" });
+    expect(parseAuthCallback("?token_hash=abc&type=admin")).toEqual({ kind: "invalid" });
+    // A key every object inherits is still not a link type.
+    expect(parseAuthCallback("?token_hash=abc&type=toString")).toEqual({ kind: "invalid" });
+    expect(parseAuthCallback("", "")).toEqual({ kind: "invalid" });
+  });
+
+  it("hands back the session a URL carries, in either flow", () => {
+    expect(parseAuthCallback("?code=4f1c")).toEqual({
+      kind: "session",
+      type: null,
+      credential: { code: "4f1c" },
+    });
+    // The implicit flow puts the tokens, and a recovery's type, in the fragment.
+    expect(
+      parseAuthCallback("", "#access_token=at&expires_in=3600&refresh_token=rt&type=recovery"),
+    ).toEqual({
+      kind: "session",
+      type: "recovery",
+      credential: { access_token: "at", refresh_token: "rt" },
+    });
+    expect(parseAuthCallback("", "#access_token=at")).toEqual({ kind: "invalid" });
+  });
+
+  it("tells a person who pressed Cancel from a link that expired", () => {
+    // A refusal relayed from the provider: GoTrue writes it to both halves, with no code.
+    const cancel = "error=access_denied&error_description=The+user+denied+the+request";
+    expect(parseAuthCallback(`?${cancel}`, `#${cancel}&sb=`)).toEqual({
+      kind: "error",
+      error: "access_denied",
+      code: null,
+      cancelled: true,
+    });
+    // GoTrue's own refusal of an implicit-flow email link: the SAME error, a code beside it,
+    // and only in the fragment — a query-only reader sees nothing at all.
+    expect(
+      parseAuthCallback(
+        "",
+        "#error=access_denied&error_code=otp_expired&error_description=Email+link+is+invalid+or+has+expired&sb=",
+      ),
+    ).toEqual({ kind: "error", error: "access_denied", code: "otp_expired", cancelled: false });
+  });
+
+  it("reads a failure that carries no `error` at all", () => {
+    // Statuses outside GoTrue's OAuth mapping, a 429 among them, write only the code.
+    expect(
+      parseAuthCallback("", "#error_code=over_email_send_rate_limit&error_description=x&sb="),
+    ).toEqual({ kind: "error", error: null, code: "over_email_send_rate_limit", cancelled: false });
+  });
+});

package/src/supabase-session.ts

@@ -97,3 +97,107 @@ export function createSupabaseSessionAdapter(auth: SupabaseSessionAuth): Session
     },
   };
 }
+
+/**
+ * Every link type a GoTrue email can carry — not only the ones this app's templates send today.
+ * One donor rejected `invite` because "invites are never sent", which was true of the product and
+ * false of the deployment: an operator inviting somebody from Studio sent a branded email whose
+ * link then said it was invalid. A type the templates never emit costs nothing to accept: the hash
+ * is the proof, and GoTrue opens a session only for the person whose one-time token it is.
+ *
+ * Closed on purpose: auth-js's own `EmailOtpType` ends in `(string & {})`, so it cannot make a
+ * destination map name every case. `Record<EmailLinkType, string>` can, and that is where an app
+ * decides that `recovery` and `invite` both continue to the new-password screen — GoTrue creates
+ * an invited account with NO password, so landing one "inside" signs them in once and locks them
+ * out after.
+ */
+export type EmailLinkType =
+  "signup" | "invite" | "magiclink" | "recovery" | "email_change" | "email";
+
+const EMAIL_LINK_TYPES: Record<EmailLinkType, true> = {
+  signup: true,
+  invite: true,
+  magiclink: true,
+  recovery: true,
+  email_change: true,
+  email: true,
+};
+
+function isEmailLinkType(value: string): value is EmailLinkType {
+  // Not `in`: `"toString" in EMAIL_LINK_TYPES` is true, and the type is typed by whoever sends
+  // the link.
+  return Object.hasOwn(EMAIL_LINK_TYPES, value);
+}
+
+/** Everything an auth callback address can carry, decided from the address alone. */
+export type AuthCallback =
+  /** An email link with a one-use `token_hash`: trade it with `verifyOtp`, exactly once. */
+  | { kind: "email-link"; tokenHash: string; type: EmailLinkType }
+  /**
+   * A session arriving in the address: a PKCE `code`, or the implicit flow's tokens. In a browser
+   * with `detectSessionInUrl` on, the client has already taken it — wait for the session, and do
+   * not trade it again, which would be a second exchange racing the first. Where nothing reads
+   * the address for you (React Native), `credential` is what `exchangeCodeForSession` or
+   * `setSession` takes.
+   */
+  | {
+      kind: "session";
+      type: EmailLinkType | null;
+      credential: { code: string } | { access_token: string; refresh_token: string };
+    }
+  /**
+   * GoTrue, or the provider behind it, reported a failure in the address. `code` is GoTrue's
+   * stable `error_code` (`otp_expired`, `bad_oauth_state`, …) and is what to choose words by;
+   * `error_description` is left out on purpose — it is English-only and often names the wrong
+   * cause.
+   */
+  | { kind: "error"; error: string | null; code: string | null; cancelled: boolean }
+  /** Nothing usable: cut short between the mail client and here, or edited by hand. */
+  | { kind: "invalid" };
+
+/**
+ * Reads an auth callback address. Pure, so every edge case is testable without a router or a
+ * client — pass `location.search` and `location.hash`, or the two halves of a deep link.
+ *
+ * GoTrue writes a failure into the FRAGMENT on every path and into the query only on some — the
+ * query too after a provider round trip, the fragment alone after an implicit-flow email link —
+ * so a callback reading one of the two misses a failure the other carries, and the person lands
+ * on a screen that says nothing. Both are read here.
+ *
+ * `cancelled` is the provider refusing on its own, which for Google is the person pressing Cancel
+ * — their choice, not a failure to report. It is NOT `error === "access_denied"`: GoTrue writes
+ * that same value for an expired email link, a banned user and a disabled signup, each with an
+ * `error_code` beside it, while a refusal relayed from the provider arrives with none. The obvious
+ * test reads an expired link as a change of mind. And `error` itself is absent for a status
+ * outside GoTrue's OAuth mapping — a rate-limited link arrives with `error_code` alone.
+ */
+export function parseAuthCallback(search: string | URLSearchParams, hash = ""): AuthCallback {
+  const query = new URLSearchParams(search);
+  const fragment = new URLSearchParams(hash.replace(/^#/, ""));
+  const read = (name: string) => query.get(name) || fragment.get(name) || null;
+
+  const error = read("error");
+  const code = read("error_code");
+  if (error || code || read("error_description"))
+    return { kind: "error", error, code, cancelled: error === "access_denied" && code === null };
+
+  const rawType = read("type") ?? "";
+  const type = isEmailLinkType(rawType) ? rawType : null;
+
+  const tokenHash = query.get("token_hash")?.trim();
+  if (tokenHash) return type ? { kind: "email-link", tokenHash, type } : { kind: "invalid" };
+
+  const pkceCode = query.get("code");
+  if (pkceCode) return { kind: "session", type, credential: { code: pkceCode } };
+
+  const accessToken = fragment.get("access_token");
+  const refreshToken = fragment.get("refresh_token");
+  if (accessToken && refreshToken)
+    return {
+      kind: "session",
+      type,
+      credential: { access_token: accessToken, refresh_token: refreshToken },
+    };
+
+  return { kind: "invalid" };
+}

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 };
+}