@pithy-sh/ui-react-native 0.0.0-stage → 0.2.0

package/templates/src/routes/pithy/subscription.tsx

@@ -0,0 +1,240 @@
+import type { MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import {
+  PAYMENTS_HOSTED_RAILS,
+  type PaymentsClientOptions,
+  type PaymentsClientRail,
+} from "@pithy-sh/payments/src/client/api";
+import { useSubscription } from "@pithy-sh/payments/src/client/hooks";
+import type { PaymentsRailChoice } from "@pithy-sh/payments/src/client/railChoice";
+import { type ReactNode, useMemo, useRef } from "react";
+import { Pressable, Text, View } from "react-native";
+import { failureText, returningClient } from "../../payments";
+import { paymentsConfig, platformRails } from "../../pithy-config";
+import { devicePlatform } from "../../platform";
+import { Link, useScreenPath } from "../../router";
+import { type Theme, useTheme } from "../../theme";
+import { useAppFocus } from "../../useAppFocus";
+
+export const path = "/subscription";
+
+// What the paywall and the pricing screen link to as "what do I already have?". Rename `path` above and both
+// follow, because they read this claim rather than keeping a copy of the string.
+export const role = "subscription";
+
+// The entitlements shown are the caller's own; the server resolves them from the session. Under a project that
+// bills organizations they are the organization's, resolved from that same session. Either way this screen names no
+// holder and cannot, which is what stops it becoming a way to read somebody else's.
+export const session = "required";
+
+// Pithy's screen. Yours to override: put your own file at this path under src/routes/app/ and it wins.
+
+/**
+ * This screen's English, baked in: the only catalog that survives being copied into your repository.
+ *
+ * The renewal date is not in here, and could not be: a date is `Intl`'s to render, in the reader's own locale,
+ * from the translator's `formattingLocale`. What the message carries is the sentence around it.
+ */
+const EN = {
+  "payments/subscription.subscribed": "You're subscribed.",
+  "payments/subscription.empty": "Nothing yet.",
+  "payments/subscription.unreadable": "We couldn't check.",
+  "payments/subscription.nothing_held": "You don't hold anything on this account.",
+  "payments/subscription.loading": "One moment.",
+  "payments/subscription.holding.ended": "Ended.",
+  "payments/subscription.holding.ended_not_renewing": "Ended, and not renewing.",
+  "payments/subscription.holding.kept": "Yours to keep.",
+  "payments/subscription.holding.renews": "Renews {date}.",
+  "payments/subscription.manage": "Manage billing",
+  "payments/subscription.apple": "Bought on the App Store",
+  "payments/subscription.google": "Bought on Google Play",
+  "payments/subscription.more": "See what else there is",
+} satisfies MessageCatalog;
+
+/**
+ * What to say about one entitlement.
+ *
+ * `granted` comes first: the server applies the expiry itself on every read, so a row can come back
+ * `granted: false` while its own `expiresAt` still says nothing is wrong. A refunded non-consumable is
+ * `{ granted: false, expiresAt: null }`, and reading only the date would print "Yours to keep." over a purchase the
+ * holder no longer has.
+ */
+function holding(t: Translator, entitlement: { granted: boolean; expiresAt: string | null }): string {
+  if (!entitlement.granted) {
+    return entitlement.expiresAt === null
+      ? t.t("payments/subscription.holding.ended")
+      : t.t("payments/subscription.holding.ended_not_renewing");
+  }
+  if (entitlement.expiresAt === null) return t.t("payments/subscription.holding.kept");
+  // The app's locale, not the device's: a reader who chose Spanish inside the app reads a Spanish date.
+  return t.t("payments/subscription.holding.renews", { date: t.formatDate(new Date(entitlement.expiresAt)) });
+}
+
+/** One of this screen's buttons. The first is filled with the accent; the rest are outlined. */
+function Action(props: {
+  theme: Theme;
+  label: string;
+  primary?: boolean;
+  disabled?: boolean;
+  onPress: () => void;
+}): ReactNode {
+  const { theme } = props;
+  return (
+    <Pressable
+      role="button"
+      disabled={props.disabled}
+      aria-disabled={props.disabled}
+      onPress={props.onPress}
+      style={{
+        borderWidth: 1,
+        borderColor: props.primary ? theme.colors.accent : theme.colors.border,
+        backgroundColor: props.primary ? theme.colors.accent : "transparent",
+        borderRadius: theme.radius,
+        paddingVertical: theme.spacing.sm,
+        paddingHorizontal: theme.spacing.md,
+        alignSelf: "flex-start",
+        opacity: props.disabled ? 0.5 : 1,
+      }}
+    >
+      <Text style={[theme.type.button, { color: props.primary ? theme.colors.onAccent : theme.colors.text }]}>
+        {props.label}
+      </Text>
+    </Pressable>
+  );
+}
+
+export interface SubscriptionScreenProps {
+  /**
+   * The translator this screen renders through. Absent, the screen reads the provider a `TranslatorProvider`
+   * mounted, and with no provider it reads {@link EN}.
+   */
+  readonly t?: Translator;
+  /**
+   * Which rails the Worker sells through: `paymentsConfig.rails`. Keyed by the rail union rather than by `string`,
+   * so a rail added to the package whose projection nobody widened stops compiling here.
+   */
+  readonly rails: Readonly<Record<PaymentsClientRail, boolean>>;
+  /**
+   * The rail this platform sells through, from `pithy-config.generated.ts`. `none` is a build that sells nothing:
+   * it shows what the account holds and offers no way to buy or manage a purchase.
+   */
+  readonly choice: PaymentsRailChoice;
+  /**
+   * Where the payments routes are, and the fetch to reach them with. Absent, the app's own, with the system
+   * browser's close reported back so the screen reads the subscription again.
+   */
+  readonly client?: PaymentsClientOptions;
+  /** Where "see what else there is" points: the path the paywall screen declares, read through its role. */
+  readonly paywallPath: string;
+}
+
+/**
+ * The subscription screen, taking its projection rather than reading it, so a test mounts it against any set of
+ * rails and looks for the buttons a reader would.
+ *
+ * Managing a subscription belongs to whoever sold it. A hosted rail's billing portal is a page the Worker mints,
+ * which opens in the system browser on a phone; Apple's and Google's are pages in their own stores. Coming back to
+ * the app reads the subscription again, so a cancellation shows the moment the reader returns.
+ */
+export function SubscriptionScreen({
+  rails,
+  choice,
+  client,
+  paywallPath,
+  t: given,
+}: SubscriptionScreenProps): ReactNode {
+  const refreshAfter = useRef<() => void>(() => undefined);
+  const returning = useMemo(() => returningClient(() => refreshAfter.current()), []);
+  const { entitlements, subscribed, loading, refresh, manage, manageStore, managing, failure, readFailure } =
+    useSubscription(client ?? returning);
+  refreshAfter.current = refresh;
+  useAppFocus(refresh);
+  // Called unconditionally, and chosen from afterwards: `given ?? useTranslator(EN)` would skip the hook whenever
+  // the prop is passed, which is a hook count that changes between renders.
+  const baked = useTranslator(EN);
+  const t = given ?? baked;
+  const theme = useTheme();
+  const muted = [theme.type.body, { color: theme.colors.muted }];
+
+  if (loading) {
+    return (
+      <View style={{ flex: 1, padding: theme.spacing.lg, backgroundColor: theme.colors.background }}>
+        <Text style={muted}>{t.t("payments/subscription.loading")}</Text>
+      </View>
+    );
+  }
+
+  const sells = choice !== "none";
+
+  return (
+    <View
+      style={{ flex: 1, padding: theme.spacing.lg, gap: theme.spacing.md, backgroundColor: theme.colors.background }}
+    >
+      {/* A read that failed is not an account that holds nothing. "Nothing yet." over an unreachable Worker tells a
+          paying subscriber they have no subscription, one tap from the paywall that would sell them a second. */}
+      <Text role="heading" style={[theme.type.title, { color: theme.colors.text }]}>
+        {readFailure
+          ? t.t("payments/subscription.unreadable")
+          : subscribed
+            ? t.t("payments/subscription.subscribed")
+            : t.t("payments/subscription.empty")}
+      </Text>
+
+      {readFailure ? (
+        <Text style={muted}>{failureText(t, readFailure)}</Text>
+      ) : entitlements.length === 0 ? (
+        <Text style={muted}>{t.t("payments/subscription.nothing_held")}</Text>
+      ) : (
+        <View style={{ gap: theme.spacing.sm }}>
+          {entitlements.map((entitlement) => (
+            <Text key={entitlement.key} style={[theme.type.body, { color: theme.colors.text }]}>
+              <Text style={{ fontWeight: "700" }}>{entitlement.key}</Text>{" "}
+              <Text style={{ color: theme.colors.muted }}>{holding(t, entitlement)}</Text>
+            </Text>
+          ))}
+        </View>
+      )}
+
+      {failure && <Text style={muted}>{failureText(t, failure)}</Text>}
+
+      {sells && (
+        <View style={{ gap: theme.spacing.sm }}>
+          {/* Every hosted rail mints a portal, and the Worker picks whichever one this account bought on. The list
+              is the package's, so a rail added to Pithy reaches this screen without an edit. */}
+          {PAYMENTS_HOSTED_RAILS.some((rail) => rails[rail]) && (
+            <Action
+              theme={theme}
+              primary
+              label={t.t("payments/subscription.manage")}
+              disabled={managing}
+              onPress={() => void manage()}
+            />
+          )}
+          {/* Named one at a time: each store has its own sentence, and its own page. */}
+          {rails.apple && (
+            <Action theme={theme} label={t.t("payments/subscription.apple")} onPress={() => manageStore("apple")} />
+          )}
+          {rails.google && (
+            <Action theme={theme} label={t.t("payments/subscription.google")} onPress={() => manageStore("google")} />
+          )}
+          <Link to={paywallPath} style={{ color: theme.colors.muted }}>
+            {t.t("payments/subscription.more")}
+          </Link>
+        </View>
+      )}
+    </View>
+  );
+}
+
+export default function Subscription(): ReactNode {
+  // The paywall names itself; this reads the path it declared rather than keeping a copy.
+  const paywallPath = useScreenPath("paywall");
+  return (
+    <SubscriptionScreen
+      rails={paymentsConfig.rails}
+      choice={platformRails[devicePlatform()]}
+      paywallPath={paywallPath}
+    />
+  );
+}

package/templates/src/session.tsx

@@ -0,0 +1,349 @@
+import type { AuthSession, AuthUser } from "@pithy-sh/auth/src/client/api";
+import {
+  AUTH_UNREACHABLE,
+  AUTH_UNREADABLE,
+  callAuth,
+  signOut as endSession,
+  getSession as readSession,
+} from "@pithy-sh/auth/src/client/api";
+import { createHandoffVerifier, exchangeHandoff, handoffCallbackURL } from "@pithy-sh/auth/src/client/handoff";
+import { accountRefusal } from "@pithy-sh/auth/src/client/lifecycle";
+import { useRead } from "@pithy-sh/ui-core/src/read";
+import { matchPath, type ScreenRole, screenPath } from "@pithy-sh/ui-core/src/routes";
+import { CryptoDigestAlgorithm, digest, getRandomBytes } from "expo-crypto";
+import { useCallback } from "react";
+import { Linking } from "react-native";
+import { authConfig, origin, universalLinkOrigin } from "./pithy-config";
+import { appLink, onDevice, openExternal, parseQuery, queryString } from "./platform";
+import { routeTable, useGo } from "./router";
+import { secureStore, transport } from "./transport";
+
+/**
+ * Session state, read from the Worker.
+ *
+ * The transport is `./transport`'s: a bearer credential in the secure store on a phone, the page's httpOnly cookie
+ * on the web. The requests themselves live in `@pithy-sh/auth/src/client/api` and `.../bearer`, which upgrade with
+ * a minor release; this file decides what the app does with their answers.
+ */
+
+/** The signed-in user, as the session route returns them. */
+export type SessionUser = AuthUser;
+
+/** A live session, or `null` when nobody is signed in. */
+export type Session = AuthSession;
+
+/**
+ * The current session, or `null`. On a phone the stored credential is restored first, and reading the session is
+ * what tells the bearer session when its credential expires, so it rotates in time.
+ *
+ * Never throws. A Worker that could not be reached reads as signed out here.
+ */
+export async function getSession(): Promise<Session> {
+  if (!authConfig.enabled) return null;
+  await transport.session();
+  const result = await readSession(transport.auth);
+  return result.ok ? result.value : null;
+}
+
+/**
+ * Hold the session a sign-in just answered with. On a phone that is the raw `token` in the answer's body, kept in
+ * the secure store before this resolves; on the web the Worker already set the cookie. `false` when a phone got an
+ * answer with no token in it, which is a sign-in that did not take.
+ */
+export async function adoptSignIn(answer: unknown): Promise<boolean> {
+  if (!transport.bearer) return true;
+  const token = typeof answer === "object" && answer !== null ? (answer as { token?: unknown }).token : undefined;
+  if (typeof token !== "string" || token === "") return false;
+  await transport.adopt(token);
+  await readSession(transport.auth);
+  return true;
+}
+
+/** How a sign-in on a phone ended: the session is held, or the code the Worker refused it with. */
+export type SignInOutcome = { ok: true } | { ok: false; code: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Who the provider says signed in, beside the token. Apple puts no name in its identity token and hands the name
+ * and address to the app on the first sign-in only, so the Worker learns them from this or never.
+ */
+export interface IdTokenUser {
+  readonly name?: { readonly firstName?: string; readonly lastName?: string };
+  readonly email?: string;
+}
+
+/**
+ * Sign in with an id token a provider's own SDK handed the app: Apple's identity token, or Google's id token
+ * for the web client id. The Worker checks the token's audience and answers with the raw session token, which
+ * is adopted before this resolves. A phone only: the web signs in through the redirect.
+ */
+export async function signInWithIdToken(
+  provider: "apple" | "google",
+  idToken: { token: string; nonce?: string; user?: IdTokenUser },
+): Promise<SignInOutcome> {
+  const result = await callAuth(
+    "/sign-in/social",
+    { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ provider, idToken }) },
+    transport.auth,
+    isRecord,
+  );
+  if (!result.ok) return { ok: false, code: result.failure.code };
+  return (await adoptSignIn(result.value)) ? { ok: true } : { ok: false, code: AUTH_UNREADABLE.code };
+}
+
+/**
+ * Where the verifier of a redirect sign-in waits while the system browser has it. The secure store rather than
+ * memory, because a magic link is opened from the mail app, and the app may be gone by the time it returns.
+ */
+export const HANDOFF_VERIFIER_KEY = "pithy.auth.handoff";
+
+/** The code {@link completeHandoff} answers when no sign-in from this device is waiting for a code. */
+export const NO_HANDOFF = "client/no_handoff";
+
+/**
+ * The link a sign-in in the system browser returns to `path` on: the universal link when `universalLinkOrigin` is
+ * set, which only this app can claim, and the app's own scheme otherwise. The Worker's `trustedOrigins` names it.
+ */
+export function returnLink(path: string): string {
+  return universalLinkOrigin === null ? appLink(path) : `${universalLinkOrigin}${path}`;
+}
+
+/**
+ * Start a redirect sign-in on a phone: make a verifier, keep it, and answer the `callbackURL` that returns to
+ * `path` in this app carrying the verifier's challenge. The Worker sends the browser back there with a one-time
+ * code instead of a cookie the app could never read. One sign-in waits at a time; starting another replaces it.
+ */
+export async function beginHandoff(path: string): Promise<string> {
+  const { verifier, challenge } = await createHandoffVerifier({
+    randomBytes: getRandomBytes,
+    // A copy over a fresh `ArrayBuffer`: `BufferSource` takes no view over a `SharedArrayBuffer`.
+    sha256: (data) => digest(CryptoDigestAlgorithm.SHA256, new Uint8Array(data)),
+  });
+  await secureStore.setItem(HANDOFF_VERIFIER_KEY, verifier);
+  return handoffCallbackURL(returnLink(path), challenge);
+}
+
+/** Forget the waiting verifier: the sign-in it belonged to was abandoned. */
+export async function abandonHandoff(): Promise<void> {
+  try {
+    await secureStore.deleteItem(HANDOFF_VERIFIER_KEY);
+  } catch {
+    // The next sign-in replaces it, and the Worker spends the code it stood for within a minute anyway.
+  }
+}
+
+async function trade(code: string): Promise<SignInOutcome> {
+  let verifier: string | null;
+  try {
+    verifier = await secureStore.getItem(HANDOFF_VERIFIER_KEY);
+  } catch {
+    verifier = null;
+  }
+  if (verifier === null || verifier === "") return { ok: false, code: NO_HANDOFF };
+  const traded = await exchangeHandoff({ code, verifier }, transport.auth);
+  // A refused code may be a stray link's, so the verifier waits on for the code its own sign-in returns with.
+  if (!traded.ok) return { ok: false, code: traded.failure.code };
+  await abandonHandoff();
+  return (await adoptSignIn(traded.value)) ? { ok: true } : { ok: false, code: AUTH_UNREADABLE.code };
+}
+
+const trades = new Map<string, Promise<SignInOutcome>>();
+
+/**
+ * Trade the one-time code a redirect sign-in returned with for the session, and adopt it. The sign-in screen
+ * reads the code off the browser's answer and the callback screen reads it off the deep link, and on Android
+ * both see the same return: they share one trade per code, because the Worker honors a code once. A trade that
+ * never reached the Worker left the code unspent, so it is forgotten and the next call tries again.
+ */
+export function completeHandoff(code: string): Promise<SignInOutcome> {
+  const running = trades.get(code);
+  if (running) return running;
+  const started = trade(code).then(
+    (outcome) => {
+      if (!outcome.ok && outcome.code === AUTH_UNREACHABLE.code) trades.delete(code);
+      return outcome;
+    },
+    (error: unknown) => {
+      trades.delete(code);
+      throw error;
+    },
+  );
+  trades.set(code, started);
+  return started;
+}
+
+/**
+ * The screen for an account that may not act, from the code its refusal carried, or `null` for any other code.
+ * The callback and the sign-in screen both route through it, by role.
+ */
+export function refusedAccountScreen(code: string | null | undefined): ScreenRole | null {
+  const refused = accountRefusal(code);
+  if (refused === "suspended") return "account-suspended";
+  if (refused === "deleted") return "account-deleted";
+  return null;
+}
+
+/** End the session: the Worker's first, then the credential this device holds. */
+export async function signOut(): Promise<void> {
+  await endSession(transport.auth);
+  await transport.forget();
+}
+
+/** {@link signOut}, then the sign-in screen. */
+export function useSignOut(): () => Promise<void> {
+  const go = useGo();
+  return useCallback(async () => {
+    await signOut();
+    go(screenPath(await routeTable(), "sign-in"));
+  }, [go]);
+}
+
+/** The session as component state, plus a `refresh` for after a sign-in completes. */
+export function useSession(): { session: Session; loading: boolean; refresh: () => void } {
+  const read = useRead("session", getSession);
+  return { session: read.value ?? null, loading: read.loading, refresh: read.refresh };
+}
+
+/** The query parameter a sign-in carries the request it should resume in. */
+export const RESUME_PARAM = "resume";
+
+/**
+ * `path` when it is a path on the Worker's own origin, or `null`. A rooted path with no second slash or backslash
+ * after the first, and no control character: a URL parser drops tab, CR and LF before it reads, so `"/\t/evil.test"`
+ * is a protocol-relative URL to it.
+ */
+function ownPath(path: string): string | null {
+  if (!path.startsWith("/")) return null;
+  if (path[1] === "/" || path[1] === "\\") return null;
+  for (const char of path) {
+    const code = char.charCodeAt(0);
+    if (code < 0x20 || code === 0x7f || char === "\\") return null;
+  }
+  return path;
+}
+
+/** Where this screen's sign-in should resume, read off its query, or `null`. */
+export function resumeTarget(search: string): string | null {
+  const path = parseQuery(search)[RESUME_PARAM];
+  return path === undefined ? null : ownPath(path);
+}
+
+/** `?resume=…` to carry a sign-in's resume target onward, or the empty string. */
+export function resumeQuery(search: string): string {
+  const target = resumeTarget(search);
+  return target === null ? "" : queryString({ [RESUME_PARAM]: target });
+}
+
+/**
+ * Leave for a page in this tab, on the web. React Native Web's own `Linking.openURL` takes the target as a second
+ * argument that React Native's types leave out; `expo-linking` drops it, and a link opened without it is a new
+ * tab, which a popup blocker stops once an await has passed.
+ */
+const pageLinking: { openURL(url: string, target?: string): Promise<unknown> } = Linking;
+
+/** Leave the app for `url` in this tab, on the web: a provider's authorization page, which returns with a cookie. */
+export async function leaveInPlace(url: string): Promise<void> {
+  await pageLinking.openURL(url, "_self");
+}
+
+/** Whether `target` is one of this app's own screens, such as an invitation, rather than a page the Worker serves. */
+async function isScreen(target: string): Promise<boolean> {
+  const at = target.indexOf("?");
+  return matchPath((await routeTable()).patterns, at === -1 ? target : target.slice(0, at)) !== null;
+}
+
+/**
+ * After a sign-in: go where the query says to resume. `true` when the app is going there.
+ *
+ * One of this app's own screens, such as the invitation that sent somebody to sign in, is gone to in the app
+ * through `go`: pass the screen's `useGo()`. Anything else is the Worker's own page, such as an authorization
+ * request: on the web it loads in place, and on a phone it opens in the system browser.
+ */
+export async function resumeAfterSignIn(search: string, go?: (to: string) => void): Promise<boolean> {
+  const target = resumeTarget(search);
+  if (target === null) return false;
+  if (go && (await isScreen(target))) {
+    go(target);
+    return true;
+  }
+  // The system browser holds no session of the app's: the Worker's page signs the person in there itself.
+  if (onDevice()) return openExternal(`${origin}${target}`);
+  await pageLinking.openURL(target, "_self");
+  return true;
+}
+
+/**
+ * Where a sign-in that took goes next, or `null` when the page is leaving for the Worker's own page in place.
+ *
+ * One of this app's own screens, such as the invitation that sent somebody to sign in, is that screen, on every
+ * platform. The Worker's own page, such as an authorization request, loads in place on the web and opens in the
+ * system browser on a phone, where the app goes home beneath it. With nothing to resume, home.
+ */
+export async function afterSignIn(search: string): Promise<string | null> {
+  const target = resumeTarget(search);
+  if (target !== null && (await isScreen(target))) return target;
+  if ((await resumeAfterSignIn(search)) && !onDevice()) return null;
+  return "/";
+}
+
+/** The key the code screen's address waits under in this tab's session storage. */
+const OTP_ADDRESS_KEY = "pithy.auth.otp-address";
+
+/** The address, held in memory too: a phone has no session storage, and a private window may refuse it. */
+let otpAddress: string | null = null;
+
+/** The slice of the Web Storage API the held address uses. */
+interface TabStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+
+/** This tab's session storage, or `null` where there is none or it refuses to be read. */
+function tabStorage(): TabStorage | null {
+  try {
+    return (globalThis as { sessionStorage?: TabStorage }).sessionStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Hand the code screen the address a code was sent to, before going there.
+ *
+ * **Never in the URL.** A path or a query string is written to every request log between the browser and the
+ * Worker the moment a reload, a bookmark or a shared link sends it, so the address waits in memory and in this
+ * tab's session storage instead. A reload of the code screen keeps it; a new tab, a bookmark or a link somebody
+ * else opens does not, and the screen goes back to sign-in.
+ */
+export function holdOtpAddress(email: string): void {
+  otpAddress = email;
+  try {
+    tabStorage()?.setItem(OTP_ADDRESS_KEY, email);
+  } catch {
+    // Storage refused: memory still holds it for this page.
+  }
+}
+
+/** The address the code screen was handed, or `null`. */
+export function heldOtpAddress(): string | null {
+  if (otpAddress !== null) return otpAddress;
+  try {
+    return tabStorage()?.getItem(OTP_ADDRESS_KEY) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Forget the held address, once the code has done its work. */
+export function releaseOtpAddress(): void {
+  otpAddress = null;
+  try {
+    tabStorage()?.removeItem(OTP_ADDRESS_KEY);
+  } catch {
+    // Nothing to forget.
+  }
+}

package/templates/src/theme.ts

@@ -0,0 +1,100 @@
+import { type TextStyle, useColorScheme } from "react-native";
+
+/**
+ * The look every Pithy screen draws with: colors, spacing and type, light and dark. The palette is the one the
+ * web screens use, so an app on both reads as one product.
+ *
+ * Edit the values here and every screen follows. A screen never writes a color or a size of its own; it asks
+ * {@link useTheme} for the palette the device is in and reads a token, so a dark device gets the dark palette
+ * without a screen branching on it.
+ */
+export interface Theme {
+  /** Light or dark: which palette this is. */
+  readonly scheme: "light" | "dark";
+  /** Colors, by the job they do. */
+  readonly colors: {
+    /** Behind everything. */
+    readonly background: string;
+    /** A raised surface: a card, an input. */
+    readonly surface: string;
+    /** Body text. */
+    readonly text: string;
+    /** Secondary text: a hint, a caption. */
+    readonly muted: string;
+    /** Borders and dividers. */
+    readonly border: string;
+    /** The one action a screen wants taken. */
+    readonly accent: string;
+    /** Text drawn on {@link Theme.colors.accent}. */
+    readonly onAccent: string;
+    /** A failure the reader has to act on. */
+    readonly danger: string;
+  };
+  /** Spacing, in density-independent pixels. */
+  readonly spacing: {
+    readonly xs: number;
+    readonly sm: number;
+    readonly md: number;
+    readonly lg: number;
+    readonly xl: number;
+  };
+  /** Corner radius for surfaces and buttons. */
+  readonly radius: number;
+  /** Text styles, by role. Colors are left to the screen, so one style serves both palettes. */
+  readonly type: {
+    readonly title: TextStyle;
+    readonly body: TextStyle;
+    readonly caption: TextStyle;
+    readonly button: TextStyle;
+  };
+}
+
+const spacing = { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 } as const;
+
+const type = {
+  title: { fontSize: 28, lineHeight: 34, fontWeight: "700" },
+  body: { fontSize: 16, lineHeight: 24, fontWeight: "400" },
+  caption: { fontSize: 13, lineHeight: 18, fontWeight: "400" },
+  button: { fontSize: 16, lineHeight: 20, fontWeight: "600" },
+} as const satisfies Theme["type"];
+
+/** The light palette. */
+export const light: Theme = {
+  scheme: "light",
+  colors: {
+    background: "#fafaf6",
+    surface: "#ffffff",
+    text: "#111111",
+    muted: "#5f5d57",
+    border: "#e5e3db",
+    accent: "#d4a017",
+    onAccent: "#111111",
+    danger: "#b3261e",
+  },
+  spacing,
+  radius: 10,
+  type,
+};
+
+/** The dark palette. */
+export const dark: Theme = {
+  scheme: "dark",
+  colors: {
+    background: "#111111",
+    surface: "#1a1a19",
+    text: "#fafaf6",
+    muted: "#9a988f",
+    border: "#2e2e2b",
+    accent: "#d4a017",
+    onAccent: "#111111",
+    danger: "#f2b8b5",
+  },
+  spacing,
+  radius: 10,
+  type,
+};
+
+/** The palette for the scheme the device is in now. Re-renders when the device switches. */
+export function useTheme(): Theme {
+  return useColorScheme() === "dark" ? dark : light;
+}