@gusnips/native 0.0.0-stage → 0.1.0

package/dist/sse.js

@@ -0,0 +1,135 @@
+/**
+ * Server-sent events on React Native, over `XMLHttpRequest`.
+ *
+ * React Native's `fetch` never gives a response body you can read as it arrives: there is no
+ * `ReadableStream` on it, so `readSseStream` from `@gusnips/react` has nothing to read. XHR does
+ * fire `onprogress` with a `responseText` that grows as bytes land, and that is the channel every
+ * RN app streaming from a server ends up on. The framing is `@gusnips/react`'s `createSseParser`,
+ * the same state machine the web reads with. Only the feed is different: here it is handed the new
+ * slice of `responseText` on each progress event.
+ *
+ * A second transport has a cost the kit already paid for once: it drifts from the API client. So
+ * this one keeps to the client's contract where it can. A refused handshake throws the client's own
+ * `ApiError`, read from the same envelope and the same `Retry-After` header, so a 402 on a stream
+ * gets the sentence and the button any other 402 in the app gets. The token and the 401 refresh come
+ * from the same `SessionAdapter` the client is built on. Single flight is the adapter's job and this
+ * adds none of its own, so a stream opening mid-load joins the refresh every other request is
+ * waiting on instead of racing it. GoTrue rotates the refresh token on use, and the loser of that race would sign the
+ * person out. The donor kept a hand-rolled single flight beside its client for this; it existed only
+ * because the adapter did not have one.
+ *
+ * No reconnect. The donor's chat store had its own recovery (it refetches the transcript when a
+ * stream breaks), and a loop here would have been a second one nobody asked for.
+ */
+import { isApiError } from "@gusnips/http";
+import { parseRetryAfter } from "@gusnips/http/retry";
+import { ApiError, createSseParser } from "@gusnips/react";
+/** The request id header `createApiClient` reads by default. */
+const REQUEST_ID_HEADER = "x-request-id";
+/**
+ * Open a stream. It starts at once; keep the handle to stop it.
+ *
+ * ```ts
+ * const stream = openSseStream({
+ *   url: `${API_URL}/chat/stream`,
+ *   body: { message },
+ *   session, // the same adapter createApiClient uses
+ *   onFrame: ({ event, data }) => handle(event, JSON.parse(data)),
+ * });
+ * ```
+ *
+ * ponytail: XHR keeps the whole response in `responseText`, so memory grows with the length of the
+ * stream. A chat turn is fine. A feed left open all day is not; that needs a native streaming module.
+ */
+export function openSseStream(options) {
+    const { url, method = "POST", body, session, headers, onFrame, onError, onClose } = options;
+    let aborted = false;
+    let refreshed = false;
+    let current = null;
+    const fail = (error) => {
+        if (aborted)
+            return;
+        onError?.(error);
+        onClose?.();
+    };
+    const asError = (thrown, fallback) => thrown instanceof Error ? thrown : new Error(fallback);
+    function start(token) {
+        if (aborted)
+            return;
+        const xhr = new XMLHttpRequest();
+        current = xhr;
+        let read = 0;
+        const parser = createSseParser((frame) => {
+            if (!aborted)
+                onFrame(frame);
+        });
+        xhr.open(method, url);
+        if (method !== "GET")
+            xhr.setRequestHeader("Content-Type", "application/json");
+        xhr.setRequestHeader("Accept", "text/event-stream");
+        for (const [name, value] of Object.entries(headers?.() ?? {}))
+            xhr.setRequestHeader(name, value);
+        if (token)
+            xhr.setRequestHeader("Authorization", `Bearer ${token}`);
+        // `responseText` is everything so far, not the new part. Feed only what was not fed yet, or
+        // every frame is delivered again on every progress event.
+        const drain = () => {
+            if (aborted || xhr.responseText.length <= read)
+                return;
+            const next = xhr.responseText.slice(read);
+            read = xhr.responseText.length;
+            parser.feed(next);
+        };
+        xhr.onprogress = drain;
+        xhr.onload = () => {
+            if (aborted)
+                return;
+            if (xhr.status === 401 && session && !refreshed) {
+                refreshed = true;
+                const refused = refusalOf(xhr);
+                // No token back means no session to retry with, whether auth refused or never answered.
+                // The stream ends with the 401; signing out stays the API client's call, so a dead session
+                // has one place that ends it.
+                session.refresh().then(({ token: fresh }) => (fresh ? start(fresh) : fail(refused)), (thrown) => fail(asError(thrown, "Could not refresh the session")));
+                return;
+            }
+            if (xhr.status < 200 || xhr.status >= 300) {
+                fail(refusalOf(xhr));
+                return;
+            }
+            // A last frame the server closed without its blank line. Two newlines close it whether the
+            // stream ended mid-frame or after one newline; after a complete frame they add nothing.
+            drain();
+            parser.feed("\n\n");
+            onClose?.();
+        };
+        xhr.onerror = () => fail(new Error("The stream lost its connection"));
+        xhr.ontimeout = () => fail(new Error("The stream timed out"));
+        xhr.send(method === "GET" ? null : JSON.stringify(body ?? {}));
+    }
+    (session ? session.getToken() : Promise.resolve(null)).then(start, (thrown) => fail(asError(thrown, "Could not read the session")));
+    return {
+        get aborted() {
+            return aborted;
+        },
+        abort() {
+            aborted = true;
+            current?.abort();
+        },
+    };
+}
+/** The refusal as the API client would have thrown it: the envelope, the request id, the wait. */
+function refusalOf(xhr) {
+    let parsed = null;
+    try {
+        parsed = JSON.parse(xhr.responseText);
+    }
+    catch {
+        // Not JSON, such as a gateway's HTML page. The status is all there is.
+    }
+    return new ApiError(xhr.status, isApiError(parsed) ? parsed.error : null, {
+        requestId: xhr.getResponseHeader(REQUEST_ID_HEADER) ?? undefined,
+        retryAfterSecs: parseRetryAfter(xhr.getResponseHeader("retry-after")),
+    });
+}
+//# sourceMappingURL=sse.js.map

package/dist/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAsC,MAAM,gBAAgB,CAAC;AAiC/F,gEAAgE;AAChE,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,OAAyB;IACrD,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5F,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,OAAO,GAA0B,IAAI,CAAC;IAE1C,MAAM,IAAI,GAAG,CAAC,KAAY,EAAE,EAAE;QAC5B,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QACjB,OAAO,EAAE,EAAE,CAAC;IACd,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,MAAe,EAAE,QAAgB,EAAE,EAAE,CACpD,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEzD,SAAS,KAAK,CAAC,KAAoB;QACjC,IAAI,OAAO;YAAE,OAAO;QACpB,MAAM,GAAG,GAAG,IAAI,cAAc,EAAE,CAAC;QACjC,OAAO,GAAG,GAAG,CAAC;QACd,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,MAAM,MAAM,GAAG,eAAe,CAAC,CAAC,KAAK,EAAE,EAAE;YACvC,IAAI,CAAC,OAAO;gBAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACtB,IAAI,MAAM,KAAK,KAAK;YAAE,GAAG,CAAC,gBAAgB,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;QAC/E,GAAG,CAAC,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;QACpD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC;YAC3D,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACpC,IAAI,KAAK;YAAE,GAAG,CAAC,gBAAgB,CAAC,eAAe,EAAE,UAAU,KAAK,EAAE,CAAC,CAAC;QAEpE,4FAA4F;QAC5F,0DAA0D;QAC1D,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,IAAI,OAAO,IAAI,GAAG,CAAC,YAAY,CAAC,MAAM,IAAI,IAAI;gBAAE,OAAO;YACvD,MAAM,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,GAAG,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC;QACF,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC;QAEvB,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE;YAChB,IAAI,OAAO;gBAAE,OAAO;YACpB,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;gBAChD,SAAS,GAAG,IAAI,CAAC;gBACjB,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;gBAC/B,wFAAwF;gBACxF,2FAA2F;gBAC3F,8BAA8B;gBAC9B,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CACpB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAC5D,CAAC,MAAe,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC,CAC5E,CAAC;gBACF,OAAO;YACT,CAAC;YACD,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;gBAC1C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;gBACrB,OAAO;YACT,CAAC;YACD,2FAA2F;YAC3F,wFAAwF;YACxF,KAAK,EAAE,CAAC;YACR,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACpB,OAAO,EAAE,EAAE,CAAC;QACd,CAAC,CAAC;QACF,GAAG,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC;QACtE,GAAG,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC,CAAC;QAE9D,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC;IAED,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,MAAe,EAAE,EAAE,CACrF,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC,CACpD,CAAC;IAEF,OAAO;QACL,IAAI,OAAO;YACT,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,KAAK;YACH,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,SAAS,SAAS,CAAC,GAAmB;IACpC,IAAI,MAAM,GAAY,IAAI,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE;QACxE,SAAS,EAAE,GAAG,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,IAAI,SAAS;QAChE,cAAc,EAAE,eAAe,CAAC,GAAG,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;KACtE,CAAC,CAAC;AACL,CAAC"}

package/dist/supabase.d.ts

@@ -0,0 +1,18 @@
+import { type SupabaseSessionStorage } from "@gusnips/react/supabase";
+/**
+ * The phone's `supabaseAuthStorage`. Build it once and pass it both to `createClient`'s `auth` and
+ * to `signOutEvenOffline`, so the sign-out clears the exact key the client reads:
+ *
+ * ```ts
+ * export const authStorage = supabaseAuthStorage(SUPABASE_URL);
+ * export const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
+ *   auth: { ...authStorage, detectSessionInUrl: false, flowType: "pkce" },
+ * });
+ * ```
+ *
+ * The key is the one supabase-js picks for itself, so moving an app onto this signs nobody out.
+ * On a phone, pass `flowType: "pkce"` as above: a sign-in comes back through a custom scheme any app
+ * can claim, and under the implicit flow that URL carries the refresh token itself.
+ */
+export declare function supabaseAuthStorage(supabaseUrl: string): SupabaseSessionStorage;
+//# sourceMappingURL=supabase.d.ts.map

package/dist/supabase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../src/supabase.ts"],"names":[],"mappings":"AASA,OAAO,EAAsB,KAAK,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAE1F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAE/E"}

package/dist/supabase.js

@@ -0,0 +1,29 @@
+/**
+ * Where supabase-js keeps the session on a phone.
+ *
+ * AsyncStorage and not the keychain (or a SecureStore): a session is the access token, the refresh
+ * token and the user's metadata in one JSON value, and it routinely passes the roughly 2 KB a
+ * platform keystore takes per value. AsyncStorage is private to the app on both platforms, and it is
+ * what Supabase's own React Native guide uses.
+ */
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { supabaseStorageKey } from "@gusnips/react/supabase";
+/**
+ * The phone's `supabaseAuthStorage`. Build it once and pass it both to `createClient`'s `auth` and
+ * to `signOutEvenOffline`, so the sign-out clears the exact key the client reads:
+ *
+ * ```ts
+ * export const authStorage = supabaseAuthStorage(SUPABASE_URL);
+ * export const supabase = createClient(SUPABASE_URL, SUPABASE_KEY, {
+ *   auth: { ...authStorage, detectSessionInUrl: false, flowType: "pkce" },
+ * });
+ * ```
+ *
+ * The key is the one supabase-js picks for itself, so moving an app onto this signs nobody out.
+ * On a phone, pass `flowType: "pkce"` as above: a sign-in comes back through a custom scheme any app
+ * can claim, and under the implicit flow that URL carries the refresh token itself.
+ */
+export function supabaseAuthStorage(supabaseUrl) {
+    return { storage: AsyncStorage, storageKey: supabaseStorageKey(supabaseUrl) };
+}
+//# sourceMappingURL=supabase.js.map

package/dist/supabase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supabase.js","sourceRoot":"","sources":["../src/supabase.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,YAAY,MAAM,2CAA2C,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAA+B,MAAM,yBAAyB,CAAC;AAE1F;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC;AAChF,CAAC"}

package/dist/theme.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvedTheme, Theme, ThemeMode, ThemeSnapshot } from "@gusnips/react/theme";
+export type { ResolvedTheme, ThemeMode, ThemeSnapshot };
+export interface NativeThemeOptions {
+    /** The AsyncStorage key holding the choice. Keep the key your app already uses. */
+    key: string;
+    /** What an empty or unrecognised key means. Defaults to `"system"`. */
+    defaultMode?: ThemeMode;
+}
+export interface NativeTheme extends Theme {
+    /**
+     * Load the stored choice, apply it, and keep it applied each time the app comes back to the
+     * foreground. Returns the function that stops it, so it fits a root `useEffect` as it is:
+     * `useEffect(() => theme.start(), [])`.
+     */
+    start(): () => void;
+}
+/**
+ * Nothing runs at import: the snapshot is read on first use, and storage only in `start()`.
+ *
+ * ```ts
+ * export const theme = createNativeTheme({ key: "app:theme" });
+ * ```
+ */
+export declare function createNativeTheme({ key, defaultMode, }: NativeThemeOptions): NativeTheme;
+//# 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":"AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI3F,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,MAAM,WAAW,WAAY,SAAQ,KAAK;IACxC;;;;OAIG;IACH,KAAK,IAAI,MAAM,IAAI,CAAC;CACrB;AAOD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,GAAG,EACH,WAAsB,GACvB,EAAE,kBAAkB,GAAG,WAAW,CA0ElC"}

package/dist/theme.js

@@ -0,0 +1,99 @@
+/**
+ * Light, dark, or whatever the phone says, remembered across launches.
+ *
+ * The phone's half of `@gusnips/react/theme`: the same three modes, the same snapshot and the same
+ * `useTheme`, so a settings screen written against one reads the same against the other. What
+ * differs is where it lands. On the web the theme is a class on `<html>`; here it is
+ * `Appearance.setColorScheme`, which is what `useColorScheme()` and react-native-css's `dark:`
+ * variant both read. `"system"` clears the override, so the OS decides again, live.
+ *
+ * Two things the donor's store taught:
+ *
+ * - **Android drops the override when the activity is recreated** under a running JS context (a
+ *   system overlay, a configuration change), and the app comes back in the OS scheme with the old
+ *   choice still in memory. So the choice is applied again every time the app returns to the
+ *   foreground. No storage read for that, only the mode already held.
+ * - **A choice made while the stored one is still loading wins.** The read is async. A tap on
+ *   "Dark" in the first second of a launch must not be undone by the stored "Light" arriving after
+ *   it, which the donor's store would have done.
+ */
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { useSyncExternalStore } from "react";
+import { AppState, Appearance } from "react-native";
+const MODES = ["light", "dark", "system"];
+const isMode = (value) => value !== null && MODES.includes(value);
+/**
+ * Nothing runs at import: the snapshot is read on first use, and storage only in `start()`.
+ *
+ * ```ts
+ * export const theme = createNativeTheme({ key: "app:theme" });
+ * ```
+ */
+export function createNativeTheme({ key, defaultMode = "system", }) {
+    let mode = defaultMode;
+    let chosen = false;
+    let snapshot = null;
+    const listeners = new Set();
+    let appearance = null;
+    const resolved = () => (Appearance.getColorScheme() === "dark" ? "dark" : "light");
+    function getSnapshot() {
+        snapshot ??= { mode, resolved: resolved() };
+        return snapshot;
+    }
+    // `useSyncExternalStore` compares snapshots by identity, so a new object goes out only when
+    // something a screen can see has changed.
+    function publish() {
+        const next = { mode, resolved: resolved() };
+        if (snapshot && snapshot.mode === next.mode && snapshot.resolved === next.resolved)
+            return;
+        snapshot = next;
+        for (const listener of listeners)
+            listener();
+    }
+    // `setColorScheme` updates what `getColorScheme` answers at once, and emits no change event of
+    // its own, so this publishes rather than waiting for one.
+    function apply() {
+        Appearance.setColorScheme(mode === "system" ? "unspecified" : mode);
+        publish();
+    }
+    function setMode(next) {
+        chosen = true;
+        mode = next;
+        apply();
+        AsyncStorage.setItem(key, next).catch(() => {
+            // Not remembered across launches, and still applied for this one.
+        });
+    }
+    function subscribe(listener) {
+        listeners.add(listener);
+        // The OS switching scheme (a phone that goes dark at sunset) while the mode is "system".
+        appearance ??= Appearance.addChangeListener(publish);
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0) {
+                appearance?.remove();
+                appearance = null;
+            }
+        };
+    }
+    function start() {
+        AsyncStorage.getItem(key).then((stored) => {
+            if (chosen)
+                return;
+            mode = isMode(stored) ? stored : defaultMode;
+            apply();
+        }, () => {
+            // Nothing readable: the default stands, and a choice made now is still applied.
+        });
+        const foreground = AppState.addEventListener("change", (state) => {
+            if (state === "active")
+                apply();
+        });
+        return () => foreground.remove();
+    }
+    function useTheme() {
+        return { ...useSyncExternalStore(subscribe, getSnapshot), setMode };
+    }
+    return { useTheme, setMode, getSnapshot, start };
+}
+//# 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,152 @@
 {
   "name": "@gusnips/native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "What a bare React Native app needs beside @gusnips/react: streams over XHR, React Query on app focus and network, theme and language that remember the choice, the Supabase session storage, the Metro config for a bun monorepo, and the Tailwind to react-native-css build.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/kit/tree/main/native#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/kit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./theme": {
+      "types": "./dist/theme.d.ts",
+      "default": "./dist/theme.js"
+    },
+    "./network": {
+      "types": "./dist/network.d.ts",
+      "default": "./dist/network.js"
+    },
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "default": "./dist/query.js"
+    },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "default": "./dist/i18n.js"
+    },
+    "./supabase": {
+      "types": "./dist/supabase.d.ts",
+      "default": "./dist/supabase.js"
+    },
+    "./metro": {
+      "types": "./dist/node/metro.d.ts",
+      "default": "./dist/node/metro.js"
+    },
+    "./css": {
+      "types": "./dist/node/css.d.ts",
+      "default": "./dist/node/css.js"
+    }
+  },
+  "bin": {
+    "gusnips-native-css": "./dist/node/bin/gusnips-native-css.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "^20.19.4 || ^22.13.0 || >=24.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react-native",
+    "metro",
+    "tailwind",
+    "react-native-css",
+    "nativewind",
+    "react-query",
+    "i18next",
+    "supabase",
+    "sse"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "oxlint -c .oxlintrc.json src",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "peerDependencies": {
+    "@gusnips/http": ">=0.2.0 <1",
+    "@gusnips/react": ">=0.10.1 <1",
+    "@react-native-async-storage/async-storage": ">=3",
+    "@react-native-community/netinfo": ">=12",
+    "@supabase/supabase-js": "^2",
+    "@tailwindcss/cli": "^4",
+    "@tanstack/react-query": "^5",
+    "i18next": ">=25",
+    "react": "^19",
+    "react-native": ">=0.86",
+    "react-native-css": "^3.0.7",
+    "react-native-localize": ">=3",
+    "tailwindcss": "^4"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
+    "@react-native-community/netinfo": {
+      "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
+    },
+    "@tailwindcss/cli": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    },
+    "react-native-css": {
+      "optional": true
+    },
+    "react-native-localize": {
+      "optional": true
+    },
+    "tailwindcss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@gusnips/http": ">=0.2.0 <1",
+    "@gusnips/react": ">=0.10.0 <1",
+    "@react-native-async-storage/async-storage": "^3.1.1",
+    "@react-native-community/netinfo": "^12.0.1",
+    "@supabase/supabase-js": "^2.113.0",
+    "@tanstack/react-query": "^5.102.8",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "i18next": "^26.3.1",
+    "react": "^19.2.4",
+    "react-native": "0.86.2",
+    "react-native-css": "3.0.7",
+    "react-native-localize": "^3.7.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/kit.git",
+    "directory": "native"
+  }
+}

package/src/device-locale.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { pickDeviceLocale } from "./device-locale.ts";
+
+// The same table `matchLocale` in @gusnips/locale is held to, so a phone and a browser with the
+// same languages land on the same one.
+describe("pickDeviceLocale", () => {
+  const SHIPPED = ["en", "pt-BR", "es"];
+
+  it("walks the phone's list in its own order", () => {
+    expect(pickDeviceLocale(["es", "en"], SHIPPED)).toBe("es");
+    // i18next's matcher answers English here: an exact match anywhere beats a base subtag.
+    expect(pickDeviceLocale(["pt-PT", "en"], SHIPPED)).toBe("pt-BR");
+    expect(pickDeviceLocale(["pt"], SHIPPED)).toBe("pt-BR");
+    expect(pickDeviceLocale(["PT-br"], SHIPPED)).toBe("pt-BR");
+    expect(pickDeviceLocale(["de", "es-MX"], SHIPPED)).toBe("es");
+  });
+
+  it("looks past the first language, which the donor did not", () => {
+    expect(pickDeviceLocale(["fr-FR", "en-US"], SHIPPED)).toBe("en");
+  });
+
+  it("answers null when nothing matches, so i18next's fallback applies", () => {
+    expect(pickDeviceLocale(["de", "fr"], SHIPPED)).toBeNull();
+    expect(pickDeviceLocale(["", " "], SHIPPED)).toBeNull();
+    expect(pickDeviceLocale([], SHIPPED)).toBeNull();
+  });
+
+  it("takes an exact tag over an earlier language that only shares its base", () => {
+    const both = ["pt-BR", "pt-PT"];
+    expect(pickDeviceLocale(["pt-PT"], both)).toBe("pt-PT");
+    expect(pickDeviceLocale(["pt"], both)).toBe("pt-BR");
+  });
+});

package/src/device-locale.ts

@@ -0,0 +1,28 @@
+/**
+ * The language we ship that the phone's list asks for first, or `null` when none of them is one.
+ *
+ * Walk the phone's list in ITS order, and for each tag take an exact match (any case), then a
+ * language with the same base subtag. So a phone set to `["pt-PT", "en-US"]` gets our `pt-BR`: the
+ * person put Portuguese first. The donor looked at the first tag only, so a phone on
+ * `["fr-FR", "en-US"]` got the fallback instead of the English the person also reads.
+ *
+ * This is `matchLocale` from `@gusnips/locale`, written again because that package is a leaf
+ * nothing in this repo depends on (AGENTS.md says why). `@gusnips/react`'s `i18nInitOptions` keeps
+ * a third copy. The test holds this one to the same table, so a reader lands on one language
+ * whichever road they come in by.
+ */
+export function pickDeviceLocale(
+  deviceTags: readonly string[],
+  supported: readonly string[],
+): string | null {
+  for (const tag of deviceTags) {
+    const lower = tag.trim().toLowerCase();
+    if (lower === "") continue;
+    const base = lower.split("-")[0];
+    const found =
+      supported.find((lng) => lng.toLowerCase() === lower) ??
+      supported.find((lng) => lng.split("-")[0]?.toLowerCase() === base);
+    if (found !== undefined) return found;
+  }
+  return null;
+}

package/src/i18n.ts

@@ -0,0 +1,91 @@
+/**
+ * The app's language on a phone: the one the person picked, else the phone's own, else your
+ * fallback.
+ *
+ * The detector reads the phone's languages with react-native-localize, synchronously, so the first
+ * render is already in a real language. A choice saved earlier is read from AsyncStorage after
+ * that (`restore`), and wins.
+ *
+ * **Only `choose` writes the saved choice.** i18next calls a detector's `cacheUserLanguage` on
+ * EVERY language change, the one it detected at launch included. The donor's detector saved there,
+ * so the first launch saved the phone's language as though the person had picked it, and when they
+ * later switched the phone to another language the app stayed in the old one for good. That is
+ * `storageWriter: "app"` in `@gusnips/react`'s `i18nInitOptions`, the same lesson from the web: one
+ * writer per key, and here the writer is your language control.
+ */
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import type { i18n as I18n, LanguageDetectorModule } from "i18next";
+import { getLocales } from "react-native-localize";
+import { pickDeviceLocale } from "./device-locale.ts";
+
+export interface NativeLanguageOptions {
+  /** Every language this app ships, as the exact tags its catalogs use. */
+  supported: readonly string[];
+  /** The AsyncStorage key holding the person's choice. Keep the key your app already uses. */
+  storageKey: string;
+}
+
+export interface NativeLanguage {
+  /** Hand to `i18n.use()` before `init`. */
+  detector: LanguageDetectorModule;
+  /** Apply the saved choice, if there is one. Call once at launch, after `init`. */
+  restore(): Promise<void>;
+  /**
+   * The person picked a language: switch to it and remember it. `null` means "follow the phone":
+   * forget the choice and switch to what the phone asks for.
+   */
+  choose(language: string | null): Promise<void>;
+}
+
+/**
+ * ```ts
+ * import i18n from "i18next";
+ *
+ * export const language = createNativeLanguage(i18n, {
+ *   supported: ["pt-BR", "en"],
+ *   storageKey: "app:language",
+ * });
+ * i18n.use(language.detector).use(initReactI18next).init({ resources, fallbackLng: "pt-BR" });
+ * ```
+ *
+ * A phone whose languages are none of `supported` gets `fallbackLng`: the detector answers nothing
+ * and i18next falls back on its own.
+ */
+export function createNativeLanguage(i18n: I18n, options: NativeLanguageOptions): NativeLanguage {
+  const { supported, storageKey } = options;
+  // A choice made while the saved one is still loading wins over it.
+  let chosen = false;
+
+  const fromDevice = () =>
+    pickDeviceLocale(
+      getLocales().map((locale) => locale.languageTag),
+      supported,
+    ) ?? undefined;
+
+  const detector: LanguageDetectorModule = {
+    type: "languageDetector",
+    init: () => {},
+    detect: fromDevice,
+    // Deliberately empty. See the top of this file.
+    cacheUserLanguage: () => {},
+  };
+
+  async function restore(): Promise<void> {
+    const stored = await AsyncStorage.getItem(storageKey).catch(() => null);
+    if (chosen || stored === null || !supported.includes(stored)) return;
+    if (i18n.language !== stored) await i18n.changeLanguage(stored);
+  }
+
+  async function choose(language: string | null): Promise<void> {
+    chosen = true;
+    const write =
+      language === null
+        ? AsyncStorage.removeItem(storageKey)
+        : AsyncStorage.setItem(storageKey, language);
+    // Not remembered across launches when storage fails, and still applied for this one.
+    await write.catch(() => {});
+    await i18n.changeLanguage(language ?? fromDevice());
+  }
+
+  return { detector, restore, choose };
+}