@gusnips/react 0.9.5 → 0.9.7

package/README.md

@@ -86,11 +86,70 @@ Supabase email links have two complete patterns. Keep either one, never half of
 - A link carrying `ConfirmationURL` needs `detectSessionInUrl` enabled. That reader consumes an
   implicit `#access_token` or a PKCE `?code`; it does not consume `token_hash`.
 
+Either pattern can carry a destination — the `token_hash` one has to be asked. GoTrue hands every
+template a `{{ .RedirectTo }}`: the `redirectTo` the app passed, already checked against the
+allowlist, falling back to the Site URL when it was absent or not on it. A `{{ .ConfirmationURL }}`
+link carries it for you. A template that writes its own landing drops it unless it asks:
+
+```
+{{ .SiteURL }}/auth/callback?token_hash={{ .TokenHash }}&type=recovery&next={{ .RedirectTo }}
+```
+
+Leave that parameter off and `redirectTo` and `emailRedirectTo` do nothing on every e-mail flow,
+however carefully the app sets them — four of the codebases this came from pass one that the
+template throws away, so a person bounced off a protected page signs in and lands on the front
+door. Nothing reports it: the app's call is correct, the link works, and the destination was
+dropped in an HTML file hosted somewhere else.
+
+`{{ .RedirectTo }}` arrives as an absolute URL rather than a path, so the landing reads it as one:
+
+```ts
+const raw = new URLSearchParams(location.search).get("next");
+const url = raw ? new URL(raw, location.origin) : null;
+const next = url?.origin === location.origin ? safeInternalPath(url.pathname + url.search) : null;
+```
+
+Validate it on arrival even though GoTrue already did: that check is against a list of origins,
+so it says the link may come back here, not which page it may open.
+
 Recovery and invite links continue to the new-password screen after the session opens. A callback
 must also tell a used or expired link apart from a request that never landed — or one that landed
 and came back 5xx: the first needs a new link, and the other two can retry the same one, because
 the hash was never spent.
 
+`parseAuthCallback` reads a callback address and says what arrived:
+
+```ts
+import { parseAuthCallback } from "@gusnips/react/supabase";
+
+parseAuthCallback("?token_hash=abc&type=recovery");
+// → { kind: "email-link", tokenHash: "abc", type: "recovery" }
+```
+
+There are four kinds. `email-link` needs your one `verifyOtp` call. `session` is a PKCE `code` or
+implicit-flow tokens; in a browser the client has already taken it, so wait for the session, and on
+React Native hand `credential` to `exchangeCodeForSession` or `setSession`. `error` is a failure
+GoTrue wrote into the address. `invalid` is a link that was cut short or edited.
+
+Pass the fragment too — `parseAuthCallback(location.search, location.hash)`. GoTrue writes a
+failure into the fragment every time and into the query only sometimes: after an implicit-flow
+email link it is in the fragment alone, so a query-only reader shows nothing to somebody whose
+link expired.
+
+Choose the words by `code` (GoTrue's `error_code`, such as `otp_expired`), not by `error`.
+`access_denied` covers an expired link, a banned user and a disabled signup as well as a person
+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.
+
 There is also a deadline on every request, which none of the codebases this came from had. A
 request with no timeout is a spinner with no end.
 
@@ -279,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,
@@ -343,15 +451,16 @@ something.
 `@gusnips/react` itself needs `react` and nothing else. Anything that needs another runtime peer
 lives behind a subpath, so you install a dependency only if you import the thing that uses it:
 
-| Import from               | What is in it                  | What you must have    |
-| ------------------------- | ------------------------------ | --------------------- |
-| `@gusnips/react`          | the client and rest            | react                 |
-| `@gusnips/react/store`    | `createAuthStore`, `authSlice` | zustand               |
-| `@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/ui`       | the seven wrappers             | @base-ui/react        |
-| `@gusnips/react/contract` | two prerender names            | nothing               |
+| Import from               | What is in it                            | What you must have    |
+| ------------------------- | ---------------------------------------- | --------------------- |
+| `@gusnips/react`          | the client and rest                      | react                 |
+| `@gusnips/react/store`    | `createAuthStore`, `authSlice`           | zustand               |
+| `@gusnips/react/guards`   | the route guards                         | react-router-dom      |
+| `@gusnips/react/hydrate`  | `hydrateOrMount`                         | react-dom             |
+| `@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/supabase-session.d.ts

@@ -53,5 +53,77 @@ export declare function isAuthOutage(error: unknown): boolean;
  * stays on that side of the line too.
  */
 export declare function createSupabaseSessionAdapter(auth: SupabaseSessionAuth): SessionAdapter;
+/**
+ * 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";
+/** 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 declare function parseAuthCallback(search: string | URLSearchParams, hash?: string): AuthCallback;
 export {};
 //# sourceMappingURL=supabase-session.d.ts.map

package/dist/supabase-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supabase-session.d.ts","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,UAAU,qBAAqB;IAC7B,IAAI,EAAE;QAAE,OAAO,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD;AAED,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,UAAU,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7C,cAAc,IAAI,OAAO,CAAC,qBAAqB,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,OAAO,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASpD;AAaD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,cAAc,CAsBtF"}
+{"version":3,"file":"supabase-session.d.ts","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,UAAU,qBAAqB;IAC7B,IAAI,EAAE;QAAE,OAAO,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD;AAED,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,UAAU,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7C,cAAc,IAAI,OAAO,CAAC,qBAAqB,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,OAAO,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACxC;AAOD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASpD;AAaD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,cAAc,CAsBtF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GACvB,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,CAAC;AAiB5E,qFAAqF;AACrF,MAAM,MAAM,YAAY;AACtB,0FAA0F;AACxF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE;AAChE;;;;;;GAMG;GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF;AACH;;;;;GAKG;GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE;AAClF,qFAAqF;GACnF;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,IAAI,SAAK,GAAG,YAAY,CA6B3F"}

package/dist/supabase-session.js

@@ -82,4 +82,59 @@ export function createSupabaseSessionAdapter(auth) {
         },
     };
 }
+const EMAIL_LINK_TYPES = {
+    signup: true,
+    invite: true,
+    magiclink: true,
+    recovery: true,
+    email_change: true,
+    email: true,
+};
+function isEmailLinkType(value) {
+    // 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);
+}
+/**
+ * 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, hash = "") {
+    const query = new URLSearchParams(search);
+    const fragment = new URLSearchParams(hash.replace(/^#/, ""));
+    const read = (name) => 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" };
+}
 //# sourceMappingURL=supabase-session.js.map

package/dist/supabase-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"supabase-session.js","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,yBAAyB,EAAuB,MAAM,uBAAuB,CAAC;AAmBpG;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,4FAA4F;IAC5F,6EAA6E;IAC7E,8FAA8F;IAC9F,8FAA8F;IAC9F,gFAAgF;IAChF,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC;IAChC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,yBAAyB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC;AACxE,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,0FAA0F;IAC1F,uFAAuF;IACvF,kFAAkF;IAClF,8EAA8E;IAC9E,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7D,8FAA8F;IAC9F,8FAA8F;IAC9F,OAAO,KAAK,CAAC,IAAI,KAAK,2BAA2B,CAAC;AACpD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAyB;IACpE,OAAO;QACL,QAAQ,EAAE,KAAK,IAAI,EAAE;YACnB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC,OAAO,EAAE,YAAY,IAAI,IAAI,CAAC;QAC5C,CAAC;QACD,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,IAAI,CAAC;gBACH,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpD,OAAO;oBACL,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,IAAI,IAAI;oBACzC,WAAW,EAAE,KAAK,KAAK,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC;iBAClD,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1D,CAAC;QACH,CAAC;QACD,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACvC,IAAI,KAAK;gBAAE,MAAM,KAAK,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"supabase-session.js","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"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"}

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAoD7C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,UAAU,CAAC,OAAqB;IAC9C,MAAM,OAAO,GAAG,MAAM,CAAC,eAAe,CAAC;IACvC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,QAAQ,EAAE,SAAS,GAAG,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IACjF,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IACxC,MAAM,MAAM,GAAG,CAAC,KAAc,EAAsB,EAAE,CACpD,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ,CAAC;IAC9D,MAAM,IAAI,GAAG,GAA0B,EAAE;QACvC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAChD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,IAAe,EAAiB,EAAE,CACjD,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,MAAM,KAAK,GAAG,CAAC,QAAuB,EAAE,EAAE;QACxC,MAAM,IAAI,GAAG,QAAQ,CAAC,eAAe,CAAC;QACtC,IAAI,SAAS,KAAK,OAAO;YAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,KAAK,MAAM,CAAC,CAAC;;YACzE,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC5C,IAAI,UAAU;YACZ,QAAQ;iBACL,gBAAgB,CAAC,0BAA0B,CAAC;iBAC5C,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC7E,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,WAAW,CAAC;IACtC,IAAI,QAAQ,GAAkB,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;IAC5E,MAAM,KAAK,GAAG,CAAC,IAAe,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,KAAK,CAAC,QAAQ,CAAC,CAAC;QAChB,IAAI,IAAI,KAAK,QAAQ,CAAC,IAAI,IAAI,QAAQ,KAAK,QAAQ,CAAC,QAAQ;YAAE,OAAO;QACrE,QAAQ,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC9B,SAAS,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC9C,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,MAAM,MAAM,GAAG,IAAI,EAAE,CAAC;QACtB,IAAI,MAAM;YAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC,CAAC;IAEF,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzB,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;QAC3C,IAAI,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,KAAK,CAAC,GAAG,KAAK,IAAI;YAAE,IAAI,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAE1C,MAAM,UAAU,GAAoB;QAClC,WAAW,EAAE,GAAG,EAAE,CAAC,QAAQ;QAC3B,OAAO,CAAC,IAAI;YACV,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;gBAAE,OAAO;YAC1B,IAAI,CAAC;gBACH,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,oDAAoD;YACtD,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,CAAC;QACd,CAAC;QACD,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC,CAAC;QACJ,CAAC;KACF,CAAC;IACF,MAAM,CAAC,eAAe,GAAG,UAAU,CAAC;IACpC,OAAO,UAAU,CAAC;AACpB,CAAC;AAWD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,QAAQ,CAAC;IACpD,MAAM,cAAc,GAAkB;QACpC,IAAI,EAAE,WAAW;QACjB,QAAQ,EAAE,WAAW,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO;KACpD,CAAC;IACF,MAAM,SAAS,GAAG,CAAC,QAAoB,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpF,MAAM,WAAW,GAAG,GAAG,EAAE,CACvB,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IACrF,MAAM,iBAAiB,GAAG,GAAG,EAAE,CAAC,cAAc,CAAC;IAC/C,MAAM,OAAO,GAAG,CAAC,IAAe,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE,SAAS,QAAQ;QACf,OAAO,EAAE,GAAG,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,EAAE,OAAO,EAAE,CAAC;IACzF,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AAC5C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.5",
+  "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