@gusnips/react 0.1.0

package/src/api-client.ts

@@ -0,0 +1,305 @@
+import { isApiError, type ApiSuccess } from "@gusnips/http";
+import { ApiError } from "./api-error.ts";
+
+/**
+ * The app's one door to the API. Nothing else should call `fetch`.
+ *
+ * Every route answers the same envelope, so unwrapping and error-shaping belong here once
+ * rather than in every hook. Three donors built this independently and all three arrived at
+ * single-flight token refresh — see {@link SessionAdapter.refresh} for the reason, which is
+ * the sharpest thing in this file.
+ *
+ * Four things deliberately did NOT come across from the donors, because they belong to a
+ * product and not to a client:
+ *
+ * - **Toasts.** Whether a failure is spoken aloud is a design decision that differs per surface.
+ *   Throw, and let the caller decide.
+ * - **In-flight GET deduplication.** react-query already dedups by key, so the client's copy is
+ *   redundant — and one donor's version returned a `clone()` of a body already being consumed,
+ *   which is a race with no symptom until it has one.
+ * - **Service-status tracking and impersonation.** One donor's, and firmly its own.
+ * - **Analytics correlation headers.** Injected through {@link ApiClientOptions.headers}.
+ */
+
+/** What a refresh attempt actually learned. */
+export interface RefreshResult {
+  token: string | null;
+  /**
+   * False when the refresh never got an ANSWER out of the auth server — a dropped connection,
+   * a 5xx, a captive portal.
+   *
+   * This flag is invariant 3, and only one of three donors had it. Losing a packet says nothing
+   * about whether a session is still good, so a client that collapses "auth said no" into
+   * "auth did not answer" signs people out over a Wi-Fi blip and costs them their place for
+   * nothing. Auth libraries usually name this: Supabase throws `AuthRetryableFetchError`, so
+   * an adapter answers `reachedAuth: !(error instanceof AuthRetryableFetchError)`.
+   */
+  reachedAuth: boolean;
+}
+
+/**
+ * The seam onto whatever holds the session. Supabase in every donor so far, but nothing here
+ * knows that — an adapter is four lines and keeps the auth vendor out of this package.
+ */
+export interface SessionAdapter {
+  getToken(): Promise<string | null>;
+  refresh(): Promise<RefreshResult>;
+  signOut(): Promise<void>;
+}
+
+export interface ApiClientOptions {
+  /** Origin + prefix, e.g. `https://api.example.com/v1`. No trailing slash. */
+  baseUrl: string;
+  session: SessionAdapter;
+  /**
+   * Extra headers, computed per request.
+   *
+   * A function, not an object, and that matters: one donor read
+   * `document.documentElement.lang` inline in its request builder, which crashes a prerender
+   * outright. Anything that touches the DOM, the current locale or the clock goes in here,
+   * where it runs only when a request is actually being sent.
+   */
+  headers?: () => Record<string, string>;
+  /**
+   * The session is gone and cannot be renewed — send them to sign in.
+   *
+   * The client does not know the route, and it deliberately still THROWS after calling this:
+   * `location.replace()` does not stop the current frame, so a caller's own `onError` must
+   * still run or a half-finished screen keeps rendering against data that will never arrive.
+   * The error it throws carries `expected: true`.
+   */
+  onSessionDead: () => void;
+  /**
+   * Every failed response, seen once, just before it is thrown.
+   *
+   * For a reaction that belongs to the whole app rather than to one call site. The donor's case
+   * is the sharp one: a mid-session account suspension 403s every authed route except
+   * `GET /auth/me`, so the moment one arrives the app has to refresh `me` and route to the
+   * screen that explains it — otherwise every query on the page fails at once and the shell
+   * half-renders behind an error storm until `me` goes stale on its own.
+   *
+   * It cannot live at a call site, because the point is that it fires from whichever call
+   * happened to be first. It went in the donor's client directly, which made the client import
+   * its query cache and its query keys — a cycle that this hook removes.
+   *
+   * Observation only: the error is thrown either way, and throwing from here would replace a
+   * real API failure with whatever the listener hit.
+   */
+  onError?: (error: ApiError) => void;
+  /**
+   * Abort a request that has not answered. Default 30s.
+   *
+   * Neither donor bounded its authenticated requests at all — both bounded only their keyless
+   * clients — so a stalled connection was a spinner with no end. providerkit learned the same
+   * lesson about streams: a request with no deadline is a bug that only shows up on a bad
+   * network, which is exactly when nobody can reproduce it.
+   */
+  timeoutMs?: number;
+  /** How many times to refresh-and-retry a 401. Default 2. */
+  maxRefreshAttempts?: number;
+  /** Pause between refresh attempts. Default 500ms. */
+  refreshRetryDelayMs?: number;
+  /**
+   * How long to wait for `signOut()` before redirecting anyway. Default 3s.
+   *
+   * A fail-safe, and one donor added it after the failure it prevents: awaiting `signOut()`
+   * covers a rejection but not a HANG, and a hang leaves the tab signed out in name only —
+   * still on the page, every request 401ing, nothing left that could redirect it.
+   */
+  signOutTimeoutMs?: number;
+  /** Header carrying the server's request id, echoed onto {@link ApiError.requestId}. */
+  requestIdHeader?: string;
+}
+
+export interface RequestOptions extends Omit<RequestInit, "headers"> {
+  headers?: Record<string, string>;
+  /** Override the client's default timeout for this call. `null` disables it (streams). */
+  timeoutMs?: number | null;
+}
+
+export interface ApiClient {
+  /** The raw `Response`, past auth and error handling. For blobs, streams and downloads. */
+  request(path: string, options?: RequestOptions): Promise<Response>;
+  /** `data` out of the success envelope. */
+  get<T>(path: string, options?: RequestOptions): Promise<T>;
+  post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  /**
+   * DELETE, discarding whatever comes back. Returns `void` because 204 is the usual answer and
+   * a 204 has NO BODY — `res.json()` on one throws `Unexpected end of JSON input`, which reads
+   * like a malformed response and is really just a success nobody was allowed to parse.
+   *
+   * Split from {@link ApiClient.delJson} rather than guessing per response, because the guess is
+   * the part that hides a bug: a route that was supposed to answer with data and returned
+   * nothing should fail loudly here, not hand back a silent `undefined` that surfaces three
+   * layers away. The donor that hit this had written exactly these two functions.
+   */
+  del(path: string, options?: RequestOptions): Promise<void>;
+  /** The DELETE that answers with something worth reading — a queue entry it handed back. */
+  delJson<T>(path: string, options?: RequestOptions): Promise<T>;
+  /** The whole envelope, for a list route whose counts live in `meta`. */
+  page<T, M>(path: string, options?: RequestOptions): Promise<ApiSuccess<T, M>>;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+export function createApiClient({
+  baseUrl,
+  session,
+  headers: extraHeaders,
+  onSessionDead,
+  onError,
+  timeoutMs = 30_000,
+  maxRefreshAttempts = 2,
+  refreshRetryDelayMs = 500,
+  signOutTimeoutMs = 3_000,
+  requestIdHeader = "x-request-id",
+}: ApiClientOptions): ApiClient {
+  /**
+   * Single-flight refresh.
+   *
+   * A page that fires six queries at once must not send six refreshes. The auth server rotates
+   * the refresh token on use, so the losers of that race each invalidate the winner — and the
+   * person is signed out in the middle of a load that was working. All three donors found this
+   * the hard way and all three fixed it the same way.
+   */
+  let refreshing: Promise<RefreshResult> | null = null;
+  function refresh(): Promise<RefreshResult> {
+    refreshing ??= session
+      .refresh()
+      .catch(() => ({ token: null, reachedAuth: false }))
+      .finally(() => {
+        refreshing = null;
+      });
+    return refreshing;
+  }
+
+  /** Latches, so whichever request gets here first owns the sign-out and the rest are no-ops. */
+  let signingOut = false;
+  function sessionDead(): never {
+    if (!signingOut) {
+      signingOut = true;
+      let done = false;
+      const go = (): void => {
+        if (done) return;
+        done = true;
+        onSessionDead();
+      };
+      void session
+        .signOut()
+        .catch(() => {})
+        .finally(go);
+      setTimeout(go, signOutTimeoutMs);
+    }
+    // Thrown even though the redirect is under way: see `onSessionDead`.
+    throw new ApiError(
+      401,
+      { code: "UNAUTHORIZED", message: "Session expired" },
+      { expected: true },
+    );
+  }
+
+  function buildHeaders(token: string | null, extra?: Record<string, string>): Headers {
+    const headers = new Headers({ ...extraHeaders?.(), ...extra });
+    if (token) headers.set("Authorization", `Bearer ${token}`);
+    return headers;
+  }
+
+  async function send(
+    path: string,
+    token: string | null,
+    { headers, timeoutMs: perCall, signal, ...init }: RequestOptions,
+  ): Promise<Response> {
+    const budget = perCall === undefined ? timeoutMs : perCall;
+    if (budget === null)
+      return fetch(`${baseUrl}${path}`, { ...init, signal, headers: buildHeaders(token, headers) });
+
+    // `AbortSignal.any` rather than a listener: it also catches the already-aborted race, where
+    // a caller's signal fired before we ever attached. It keeps the caller's abort and our
+    // timeout distinguishable at the source, which is what lets `isAbortError` stay honest.
+    const timeout = AbortSignal.timeout(budget);
+    return fetch(`${baseUrl}${path}`, {
+      ...init,
+      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+      headers: buildHeaders(token, headers),
+    });
+  }
+
+  async function request(path: string, options: RequestOptions = {}): Promise<Response> {
+    let res = await send(path, await session.getToken(), options);
+
+    if (res.status === 401) {
+      // Only a refresh that actually REACHED auth proves the session is gone. Anything else is
+      // a network problem, and the 401 falls through as an ordinary error — the next request
+      // refreshes cleanly once the connection is back. Invariant 3.
+      let answered = false;
+      for (let attempt = 0; attempt < maxRefreshAttempts; attempt++) {
+        if (attempt > 0) await sleep(refreshRetryDelayMs);
+        const result = await refresh();
+        answered = result.reachedAuth;
+        if (!result.token) continue;
+        res = await send(path, result.token, options);
+        if (res.status !== 401) break;
+      }
+      if (res.status === 401 && answered) sessionDead();
+    }
+
+    if (!res.ok) {
+      const body: unknown = await res.json().catch(() => null);
+      const error = new ApiError(res.status, isApiError(body) ? body.error : null, {
+        requestId: res.headers.get(requestIdHeader) ?? undefined,
+      });
+      // A listener that throws must not become the error the caller sees: the API failure is
+      // the real news, and swallowing it for a bug in a side effect would send everyone
+      // debugging the wrong thing.
+      try {
+        onError?.(error);
+      } catch {
+        // ignored on purpose — see above
+      }
+      throw error;
+    }
+    return res;
+  }
+
+  /**
+   * The success envelope. `request` has already thrown on anything that is not one, so what is
+   * left is `{data, meta?}` by contract — this is the single place that assertion is made.
+   */
+  async function envelope<T, M>(res: Response): Promise<ApiSuccess<T, M>> {
+    return (await res.json()) as ApiSuccess<T, M>;
+  }
+
+  const json = (body: unknown, options: RequestOptions = {}): RequestOptions =>
+    body === undefined
+      ? options
+      : {
+          ...options,
+          body: JSON.stringify(body),
+          headers: { "Content-Type": "application/json", ...options.headers },
+        };
+
+  async function data<T>(path: string, options: RequestOptions): Promise<T> {
+    return (await envelope<T, never>(await request(path, options))).data;
+  }
+
+  return {
+    request,
+    get: <T>(path: string, options: RequestOptions = {}) =>
+      data<T>(path, { ...options, method: "GET" }),
+    post: <T>(path: string, body?: unknown, options: RequestOptions = {}) =>
+      data<T>(path, json(body, { ...options, method: "POST" })),
+    put: <T>(path: string, body?: unknown, options: RequestOptions = {}) =>
+      data<T>(path, json(body, { ...options, method: "PUT" })),
+    patch: <T>(path: string, body?: unknown, options: RequestOptions = {}) =>
+      data<T>(path, json(body, { ...options, method: "PATCH" })),
+    del: async (path: string, options: RequestOptions = {}) => {
+      await request(path, { ...options, method: "DELETE" });
+    },
+    delJson: <T>(path: string, options: RequestOptions = {}) =>
+      data<T>(path, { ...options, method: "DELETE" }),
+    page: async <T, M>(path: string, options: RequestOptions = {}) =>
+      envelope<T, M>(await request(path, { ...options, method: "GET" })),
+  };
+}

package/src/api-error.ts

@@ -0,0 +1,60 @@
+import type { ApiError as ApiErrorBody } from "@gusnips/http";
+
+/**
+ * A refusal, with the whole envelope intact.
+ *
+ * `code` is what the UI switches on, `messageKey` is what gets localized, and `details` carries
+ * the parts that make a refusal actionable — the `resetAt` on a 429, the plan that lifts a 402.
+ * Keeping all of it means a caller never has to re-parse a response body that has already been
+ * read once.
+ *
+ * A real `class` and not an interface with a factory: one donor used the interface shape, which
+ * works until something needs `instanceof` across a module boundary or wants a subclass.
+ */
+export class ApiError extends Error {
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly messageKey: string | undefined;
+  readonly params: Record<string, string | number> | undefined;
+  readonly details: unknown;
+  readonly requestId: string | undefined;
+
+  /**
+   * The client raised this itself to stop a caller while it was already handling the
+   * situation — today, the 401 thrown after a dead session, where the person is already on
+   * their way to the sign-in page.
+   *
+   * It is control flow, not a fault. Exception reporting should skip it, and an error surface
+   * should not ask somebody to retry something that is not broken. One donor had this and it is
+   * the difference between a clean sign-out and a crash report every time a session expires.
+   */
+  readonly expected: boolean;
+
+  constructor(
+    status: number,
+    body: ApiErrorBody["error"] | null,
+    opts: { requestId?: string; expected?: boolean; message?: string } = {},
+  ) {
+    super(opts.message ?? body?.message ?? `Request failed (${status})`);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = body?.code;
+    this.messageKey = body?.messageKey;
+    this.params = body?.params;
+    this.details = body?.details;
+    this.requestId = opts.requestId;
+    this.expected = opts.expected ?? false;
+  }
+}
+
+/**
+ * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
+ * component waiting on it.
+ *
+ * Worth its own predicate because it is the one failure that must NOT be reported, retried or
+ * shown: nobody is waiting for the answer. Distinguishing it from a real failure is what keeps
+ * a route change from filling the console with errors nobody caused.
+ */
+export function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}

package/src/auth-store.ts

@@ -0,0 +1,59 @@
+import { create, type StoreApi, type UseBoundStore } from "zustand";
+
+/**
+ * Session FLAGS only.
+ *
+ * Who the person is — their plan, their staff bit, whether they are suspended — comes from
+ * `GET /auth/me` through react-query, never from here. Mirroring server state in a client store
+ * is how two sources of truth start disagreeing, and the one that is wrong is always the one on
+ * screen. Three repos wrote this same store; two of them wrote that same warning in a comment.
+ *
+ * `TUser` stays generic because it is the one part that differs: one product carries an
+ * anonymous-browsing flag, another does not. Keep it to what a GUARD needs — an id and an
+ * email is what all three donors had.
+ */
+export interface AuthState<TUser> {
+  user: TUser | null;
+  isAuthenticated: boolean;
+  /**
+   * True until the first session lookup resolves. The guards must not bounce somebody to
+   * /login while we are still finding out whether they are signed in.
+   */
+  isLoading: boolean;
+  /**
+   * Set (or clear) the signed-in user. This ENDS the loading state — knowing who they are is
+   * what the bootstrap was waiting for. Two of the three donors left `isLoading` alone here and
+   * relied on a separate `setLoading(false)`; forgetting that call leaves every guard spinning,
+   * so the safe default is to do it in one write.
+   */
+  setUser: (user: TUser | null) => void;
+  setLoading: (isLoading: boolean) => void;
+  /** Sign-out: clears the user and ends the loading state in one write. */
+  clear: () => void;
+}
+
+/**
+ * Create the store.
+ *
+ * The whole reason this is a factory and not a store: `isLoading` must start FALSE where there
+ * is no window, and only a factory can decide that at the call site rather than at import.
+ *
+ * A session bootstrap can only be in flight in a browser. The BUILD renders this app to files
+ * with no window at all, so `true` there is a wait that never ends — one donor shipped a route
+ * guard holding its loading screen forever, and prerendered a public page as 1,174 bytes of
+ * `role="status"`: a spinner as the indexable body of a page whose entire purpose was to be
+ * found. With no browser there is no session and never will be, which is exactly the state a
+ * first-time visitor arrives in, so that is what the page should render.
+ *
+ * Only one of the three donors knew this. It is invariant 7.
+ */
+export function createAuthStore<TUser>(): UseBoundStore<StoreApi<AuthState<TUser>>> {
+  return create<AuthState<TUser>>((set) => ({
+    user: null,
+    isAuthenticated: false,
+    isLoading: typeof window !== "undefined",
+    setUser: (user) => set({ user, isAuthenticated: Boolean(user), isLoading: false }),
+    setLoading: (isLoading) => set({ isLoading }),
+    clear: () => set({ user: null, isAuthenticated: false, isLoading: false }),
+  }));
+}

package/src/chunk-reload.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { isChunkLoadError, isPreloadHintFailure } from "./chunk-reload.ts";
+
+// No browser gives a failed dynamic import a shared type, so this is matched by message and
+// every phrasing has to be here. A miss is a white screen after a deploy — the exact failure
+// this module exists to catch — and it only reproduces on a real deploy, so the test is the
+// only place these strings get checked.
+describe("isChunkLoadError", () => {
+  it.each([
+    ["Chrome/Edge", "Failed to fetch dynamically imported module: https://x/assets/a.js"],
+    ["Firefox", "error loading dynamically imported module"],
+    ["Safari", "Importing a module script failed."],
+    ["webpack", "Loading chunk 42 failed."],
+    // The one that actually fires on a static host: the missing .js is answered with the SPA
+    // fallback, so the browser refuses the HTML rather than reporting a 404.
+    [
+      "SPA fallback",
+      "Expected a JavaScript module script but the server responded with a MIME type of text/html",
+    ],
+  ])("matches %s", (_browser, message) => {
+    expect(isChunkLoadError(new Error(message))).toBe(true);
+  });
+
+  it("matches a named ChunkLoadError whatever its message", () => {
+    const error = new Error("nothing recognisable");
+    error.name = "ChunkLoadError";
+    expect(isChunkLoadError(error)).toBe(true);
+  });
+
+  it("does not match an ordinary render error", () => {
+    expect(isChunkLoadError(new TypeError("Cannot read properties of undefined"))).toBe(false);
+    expect(isChunkLoadError(null)).toBe(false);
+  });
+});
+
+// The distinction that matters: swallowing a real module failure resolves the import with
+// `undefined`, React.lazy reads `.default` off nothing, and the developer gets a TypeError with
+// only React frames in it — naming no chunk. Only the CSS hint is safe to swallow.
+describe("isPreloadHintFailure", () => {
+  it("matches Vite's CSS preload hint and nothing else", () => {
+    expect(isPreloadHintFailure(new Error("Unable to preload CSS for /assets/a.css"))).toBe(true);
+    expect(isPreloadHintFailure(new Error("Failed to fetch dynamically imported module"))).toBe(
+      false,
+    );
+  });
+});

package/src/chunk-reload.ts

@@ -0,0 +1,94 @@
+/**
+ * Surviving a deploy that lands while a tab is open.
+ *
+ * Every app on this stack is a Vite SPA with `lazy()` routes, deployed on push. When a build
+ * replaces the one a tab is running, the next navigation asks for a chunk whose hashed name no
+ * longer exists — and a static host answers a missing asset with the SPA fallback, so the
+ * import gets HTML where it expected a module. React's lazy boundary throws, and the person
+ * gets a white screen on a click that worked a minute ago.
+ *
+ * One repo in the fleet had all of this. The others had none of it, and none of them knew.
+ */
+
+const RELOAD_FLAG_KEY = "frontkit:chunk-reload-at";
+const RELOAD_WINDOW_MS = 60_000;
+
+/**
+ * A lazy-chunk fetch failure — recoverable by reloading.
+ *
+ * Matched by message because no browser gives it a shared type. Every phrasing in the wild is
+ * here: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "error loading
+ * dynamically imported module", Safari "Importing a module script failed", webpack's
+ * ChunkLoadError and "Loading chunk N failed", and the SPA-fallback "MIME type" refusal —
+ * which is the one that actually fires on a static host, because the missing `.js` is answered
+ * with `index.html`.
+ *
+ * A standalone predicate rather than a method on the boundary, so a global `unhandledrejection`
+ * handler can classify the same failure without importing a component.
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (error instanceof Error && error.name === "ChunkLoadError") return true;
+  const message = (error instanceof Error ? error.message : String(error) || "").toLowerCase();
+  return (
+    message.includes("dynamically imported module") ||
+    message.includes("importing a module script failed") ||
+    message.includes("mime type") ||
+    message.includes("loading chunk")
+  );
+}
+
+/**
+ * Hard-reload once to pick up the fresh deploy. Returns false when the guard suppressed it.
+ *
+ * The guard is the part that matters. Reloading on a chunk error is obvious; reloading on a
+ * chunk error that the reload does not fix is an infinite loop with the user inside it. At most
+ * one reload per minute, so a genuinely missing chunk degrades to the error UI — which can at
+ * least say something — instead of flickering forever.
+ *
+ * `sessionStorage` and not `localStorage`: the guard is about this tab's current predicament,
+ * and a stale flag in another tab must not suppress a reload this one needs. Wrapped because
+ * storage throws outright when site data is blocked, and a privacy setting must not be the
+ * reason somebody cannot recover.
+ */
+export function reloadOnceForChunkError(): boolean {
+  const now = Date.now();
+  try {
+    const last = Number(sessionStorage.getItem(RELOAD_FLAG_KEY) ?? 0);
+    if (now - last < RELOAD_WINDOW_MS) return false;
+    sessionStorage.setItem(RELOAD_FLAG_KEY, String(now));
+  } catch {
+    // Storage blocked — proceed with the reload rather than refusing to recover.
+  }
+  window.location.reload();
+  return true;
+}
+
+/**
+ * Vite's *hint* failure, which is not the same thing and must not be treated as one.
+ *
+ * Vite injects a speculative `<link rel="stylesheet">` for a chunk's CSS before importing it.
+ * When that link fails, the import itself still runs right after and usually succeeds — so this
+ * one is worth swallowing, where a failure of the import is the real thing
+ * {@link isChunkLoadError} matches. Vite builds this message in exactly one place and only ever
+ * for a stylesheet link; script hints never reject.
+ */
+export function isPreloadHintFailure(error: unknown): boolean {
+  return error instanceof Error && error.message.startsWith("Unable to preload CSS for");
+}
+
+/**
+ * Install the `vite:preloadError` listener. Call once, from the browser entry.
+ *
+ * Vite offers `preventDefault()` here so an app can own a failed asset itself — but taking that
+ * deal unconditionally resolves the dynamic import with `undefined` (Vite's helper ends in
+ * `baseModule().catch(handlePreloadError)`), and `React.lazy` then reads `.default` off nothing.
+ * The user gets the crash screen and the developer gets a TypeError with only React frames in
+ * it, naming no chunk. So it is taken ONLY for a failed preload hint, where the import still
+ * runs. A real module failure is left to throw, where the error boundary can recognise it.
+ */
+export function installPreloadErrorHandler(): void {
+  window.addEventListener("vite:preloadError", (event) => {
+    const payload = (event as Event & { payload?: unknown }).payload;
+    if (isPreloadHintFailure(payload)) event.preventDefault();
+  });
+}

package/src/cn.ts

@@ -0,0 +1,16 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Compose class names, letting later Tailwind utilities win over earlier ones
+ * (`p-2 p-4` → `p-4`).
+ *
+ * That precedence is the whole point, and it is why this is not `clsx` alone: a caller's
+ * `className` has to be able to OVERRIDE a component's defaults rather than fight them at
+ * equal specificity, where the winner would be whichever rule Tailwind happened to emit last.
+ *
+ * Ten repos wrote this function. All ten wrote it identically.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}