@gusnips/react 0.1.0

package/src/describe-error.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { ApiError } from "./api-error.ts";
+import { createErrorDescriber, humanizeWait, retryAfterSecs } from "./describe-error.ts";
+
+/** A translator that echoes the key, so a test can see exactly which one was asked for. */
+const t = (key: string, params?: Record<string, unknown>) =>
+  params && Object.keys(params).length > 0 ? `${key}(${JSON.stringify(params)})` : key;
+
+describe("humanizeWait", () => {
+  // The thresholds are 90s and 90min, not 60 and 60. "in 75 seconds" must not round down to
+  // the vaguer "in 1 minute" — the whole job of this function is to be more useful than the
+  // raw number, and a lossy rounding at the boundary is less useful.
+  it("keeps the more precise unit past the round boundary", () => {
+    expect(humanizeWait(t, 75, "errors.")).toBe('errors.waitSeconds({"count":75})');
+    expect(humanizeWait(t, 95, "errors.")).toBe('errors.waitMinutes({"count":2})');
+    expect(humanizeWait(t, 80 * 60, "errors.")).toBe('errors.waitMinutes({"count":80})');
+    expect(humanizeWait(t, 2 * 3600, "errors.")).toBe('errors.waitHours({"count":2})');
+  });
+
+  it("never says 'in 0 seconds'", () => {
+    expect(humanizeWait(t, 0.2, "errors.")).toBe('errors.waitSeconds({"count":1})');
+  });
+});
+
+describe("retryAfterSecs", () => {
+  it("reads the number out of details, and refuses anything else", () => {
+    expect(
+      retryAfterSecs(
+        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: 30 } }),
+      ),
+    ).toBe(30);
+    expect(
+      retryAfterSecs(
+        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: "30" } }),
+      ),
+    ).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, { code: "X", message: "", details: null }))).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
+  });
+});
+
+describe("createErrorDescriber", () => {
+  const describeError = createErrorDescriber({
+    t,
+    knownMessageKeys: ["quotaDay", "suspended"],
+    codes: {
+      QUOTA_EXCEEDED: ({ says, wait }) => ({
+        cause: says ?? "errors.quota",
+        hint: wait ? `errors.retryIn(${wait})` : undefined,
+      }),
+    },
+  });
+
+  it("reads a thrown non-response as the network, with a way forward", () => {
+    const { cause, hint } = describeError(new TypeError("Failed to fetch"));
+    expect(cause).toBe("errors.network");
+    // The hint is the point. A cause with no hint is the dead end this module exists to stop.
+    expect(hint).toBe("errors.networkHint");
+  });
+
+  it("resolves a messageKey this build carries, with its params", () => {
+    const error = new ApiError(429, {
+      code: "QUOTA_EXCEEDED",
+      message: "Daily cap reached",
+      messageKey: "serverErrors.quotaDay",
+      params: { limit: 100 },
+      details: { retryAfterSecs: 3600 },
+    });
+    expect(describeError(error).cause).toBe('serverErrors.quotaDay({"limit":100})');
+  });
+
+  // A deploy can land ahead of the bundle a tab is still running, so the server names a
+  // sentence this build has never heard of. Falling back to the server's English beats
+  // rendering the raw key at somebody.
+  it("falls back to the server's English for a key this build does not have", () => {
+    const error = new ApiError(429, {
+      code: "QUOTA_EXCEEDED",
+      message: "Daily cap reached",
+      messageKey: "serverErrors.shippedLastTuesday",
+    });
+    expect(describeError(error).cause).toBe("errors.quota");
+  });
+
+  // The server names a SENTENCE, not any key in the app. A messageKey outside the namespace
+  // is ignored rather than resolved — otherwise a compromised or careless server could point
+  // the client at arbitrary copy.
+  it("ignores a messageKey outside the server namespace", () => {
+    const error = new ApiError(500, {
+      code: "UNKNOWN",
+      message: "boom",
+      messageKey: "billing.upgradeNow",
+    });
+    expect(describeError(error).cause).toBe("boom");
+  });
+
+  it("offers a retry on a 5xx and withholds it on a 4xx", () => {
+    // A 5xx genuinely clears on its own. A 4xx does not, and saying so would cost the reader
+    // another attempt for nothing.
+    expect(describeError(new ApiError(503, null)).hint).toBe("errors.retrySoon");
+    expect(describeError(new ApiError(403, null)).hint).toBeUndefined();
+  });
+});

package/src/describe-error.ts

@@ -0,0 +1,140 @@
+import { ApiError } from "./api-error.ts";
+
+/**
+ * Turning anything thrown into copy a person can act on.
+ *
+ * The API already answers with a message written for a developer, a stable `messageKey` for the
+ * domain refusals, and `details` carrying the parts that make a refusal actionable. This is the
+ * one place that decides what the SCREEN says — which is not always the same sentence.
+ * "Monthly quota spent, upgrade or buy a pack" is right in a JSON body and wrong under a button
+ * that could just say what to do next.
+ *
+ * `cause` is what happened. `hint` is what to do about it. **A surface that shows only the first
+ * half is the dead end this exists to prevent** — which is why the type has two fields and not
+ * one, and why `hint` being absent should be a deliberate choice at each call site rather than
+ * the default nobody noticed.
+ *
+ * The per-code switch stays in the product: two donors' switches shared their SHAPE and almost
+ * no arms, because the arms are that API's vocabulary. What ships is the scaffolding around it,
+ * which is the part that was written twice and got subtly different both times.
+ */
+
+export interface DescribedError {
+  /** What happened, in the reader's words. */
+  cause: string;
+  /** What to do about it. Its absence should be a decision, not an oversight. */
+  hint?: string;
+}
+
+/** The subset of i18next's `t` this module needs — typed here so `i18next` stays optional. */
+export type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+/** Seconds until a refusal clears, when the envelope carries them. */
+export function retryAfterSecs(error: ApiError): number | null {
+  const details = error.details;
+  if (typeof details !== "object" || details === null) return null;
+  const value = (details as { retryAfterSecs?: unknown }).retryAfterSecs;
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
+ *
+ * The thresholds are deliberately not round: 90 seconds rather than 60, so "in 75 seconds" does
+ * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
+ * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` in the catalog, each with a
+ * `count` plural.
+ */
+export function humanizeWait(t: Translate, secs: number, prefix = ""): string {
+  const key = (name: string): string => `${prefix}${name}`;
+  if (secs < 90) return t(key("waitSeconds"), { count: Math.max(1, Math.round(secs)) });
+  if (secs < 90 * 60) return t(key("waitMinutes"), { count: Math.round(secs / 60) });
+  return t(key("waitHours"), { count: Math.round(secs / 3600) });
+}
+
+export interface ErrorDescriberOptions<Code extends string> {
+  t: Translate;
+  /**
+   * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
+   * ignored — the server names a sentence, it does not get to name any key in the app.
+   */
+  messageKeyPrefix?: string;
+  /**
+   * The keys this build actually carries, usually `Object.keys(en.serverErrors)`.
+   *
+   * Membership is checked with `hasOwnProperty` and not `in`, which would accept `"toString"`.
+   * A key that is absent falls back to the server's English `message`, because a deploy can land
+   * ahead of the bundle a tab is still running and a missing translation must degrade to
+   * readable rather than render the key itself at somebody.
+   */
+  knownMessageKeys?: readonly string[] | Record<string, unknown>;
+  /** Catalog namespace for this module's own copy. Defaults to `"errors."`. */
+  copyPrefix?: string;
+  /** Per-code copy. Everything not listed falls through to the default arm below. */
+  codes?: Partial<Record<Code, (ctx: ErrorContext) => DescribedError>>;
+}
+
+export interface ErrorContext {
+  error: ApiError;
+  /** The server's own localized sentence, when `messageKey` named one this build carries. */
+  says: string | null;
+  /** Seconds until it clears, already humanized. Null when the envelope did not say. */
+  wait: string | null;
+  waitSecs: number | null;
+  t: Translate;
+}
+
+/**
+ * Build the describer. Needs `network`, `networkHint`, `unexpected`, `retrySoon`,
+ * `waitSeconds`, `waitMinutes` and `waitHours` under `copyPrefix` in every locale.
+ */
+export function createErrorDescriber<Code extends string>({
+  t,
+  messageKeyPrefix = "serverErrors.",
+  knownMessageKeys,
+  copyPrefix = "errors.",
+  codes = {},
+}: ErrorDescriberOptions<Code>): (error: unknown) => DescribedError {
+  const known = Array.isArray(knownMessageKeys)
+    ? new Set<string>(knownMessageKeys)
+    : new Set(Object.keys(knownMessageKeys ?? {}));
+
+  const has = (name: string): boolean => known.size === 0 || known.has(name);
+  const key = (name: string): string => `${copyPrefix}${name}`;
+
+  function serverSentence(error: ApiError): string | null {
+    const messageKey = error.messageKey;
+    if (messageKey === undefined || !messageKey.startsWith(messageKeyPrefix)) return null;
+    const name = messageKey.slice(messageKeyPrefix.length);
+    return has(name) ? t(messageKey, error.params) : null;
+  }
+
+  return function describeError(error: unknown): DescribedError {
+    if (!(error instanceof ApiError)) {
+      // Not a response at all — the request never landed. Almost always the network, and almost
+      // never worth showing a stack trace for.
+      return { cause: t(key("network")), hint: t(key("networkHint")) };
+    }
+
+    const waitSecs = retryAfterSecs(error);
+    const ctx: ErrorContext = {
+      error,
+      says: serverSentence(error),
+      wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
+      waitSecs,
+      t,
+    };
+
+    const arm = error.code === undefined ? undefined : codes[error.code as Code];
+    if (arm) return arm(ctx);
+
+    // Anything unmapped: the server's own sentence is still the most specific thing we have,
+    // and support can act on it. A 5xx additionally gets "try again shortly", because that one
+    // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
+    // the reader another attempt.
+    return {
+      cause: ctx.says ?? (error.message || t(key("unexpected"))),
+      hint: error.status >= 500 ? t(key("retrySoon")) : undefined,
+    };
+  };
+}

package/src/error-boundary.tsx

@@ -0,0 +1,88 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+/**
+ * The last stop before a white screen.
+ *
+ * React unmounts the whole tree when a render throws, and an app with no boundary anywhere
+ * answers that with a blank page: no words, no navigation, no reload — the most complete dead
+ * end a product can produce, and the one the never-dead-end rule cannot reach, because by then
+ * there is no component left to render a state from.
+ *
+ * It is deliberately dumb. No retry loop, no error reporting, no reset on a timer: it catches,
+ * it hands the error to a `fallback` the app draws in its own words, and it offers `reset`.
+ * Every donor that baked its own UI in here had to keep a second copy for its second surface;
+ * a render prop has no such problem, and the brand stays in the product where it belongs.
+ *
+ * A class, because `getDerivedStateFromError` has no hook equivalent — this is the one thing in
+ * the kit React still has no other way to express.
+ */
+
+export interface ErrorBoundaryFallbackProps {
+  error: Error;
+  /** Put the children back. */
+  reset: () => void;
+  /**
+   * True when the throw was a failed lazy-chunk import — a deploy landed while this tab was
+   * open, so the fix is a reload and NOT a retry (a rejected dynamic import rethrows on
+   * re-render forever). Draw the "updating" screen, not the crash screen.
+   */
+  isChunkError: boolean;
+}
+
+export interface ErrorBoundaryProps {
+  /** Drawn instead of the children once something has thrown. */
+  fallback: (props: ErrorBoundaryFallbackProps) => ReactNode;
+  /**
+   * Changing this value clears the error and remounts the children — pass the route, so
+   * navigating away from a screen that broke actually leaves it rather than carrying its
+   * wreckage to every page after it.
+   */
+  resetKey?: string;
+  /** Called once per catch. Report to whatever the app reports to. */
+  onError?: (error: Error, info: ErrorInfo) => void;
+  /**
+   * Classify a chunk-load failure. Pass `isChunkLoadError` from this package; it is a
+   * parameter rather than a hard import so an app that does not lazy-load pays nothing.
+   */
+  isChunkError?: (error: unknown) => boolean;
+  children: ReactNode;
+}
+
+interface State {
+  error: Error | null;
+  /** Which `resetKey` the current error belongs to. */
+  key: string | undefined;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+  override state: State = { error: null, key: undefined };
+
+  static getDerivedStateFromError(error: Error): Pick<State, "error"> {
+    return { error };
+  }
+
+  static getDerivedStateFromProps(props: ErrorBoundaryProps, state: State): State | null {
+    if (state.error === null) return { error: null, key: props.resetKey };
+    // The error belongs to the screen it happened on. Somewhere else is a fresh start, and
+    // staying broken there would strand somebody who already did the sensible thing and
+    // navigated away.
+    return state.key === props.resetKey ? null : { error: null, key: props.resetKey };
+  }
+
+  override componentDidCatch(error: Error, info: ErrorInfo): void {
+    this.props.onError?.(error, info);
+    if (!this.props.onError) console.error("Unhandled render error", error, info.componentStack);
+  }
+
+  private readonly reset = (): void => this.setState({ error: null, key: undefined });
+
+  override render(): ReactNode {
+    const { error } = this.state;
+    if (error === null) return this.props.children;
+    return this.props.fallback({
+      error,
+      reset: this.reset,
+      isChunkError: this.props.isChunkError?.(error) ?? false,
+    });
+  }
+}

package/src/guards.tsx

@@ -0,0 +1,99 @@
+import type { ReactNode } from "react";
+import { Navigate, useLocation } from "react-router-dom";
+
+/**
+ * Route guards.
+ *
+ * Two donors wrote these four, gave two of them the same names, and explained them in nearly
+ * the same words. What differed was one line — and that line is invariant 4, so it is the
+ * reason this file exists rather than being copied a ninth time.
+ *
+ * These are factories because the destinations are the app's: `paths.signIn` is not something a
+ * package can know, and one donor hardcoded `/login` in four places for exactly that reason.
+ *
+ * A guard is a COURTESY, never the boundary. The API refuses what it refuses whatever any of
+ * these decide. What they buy is that somebody who types a URL lands on one screen that
+ * explains itself instead of four panels each failing separately.
+ */
+
+/** What the guard needs off the session store. */
+export interface SessionState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+}
+
+/**
+ * The answer to a "who is this?" query, in the three states it actually has.
+ *
+ * This shape is invariant 4. A guard reading `!me?.isStaff` collapses "loading", "failed" and
+ * "no" into one branch — so an operator arriving while `/auth/me` is 500ing is told the page
+ * does not exist. Wrong cause, no retry, and no request id to quote to support. One donor hit
+ * that and fixed it; the other still has the collapsed version.
+ */
+export type MeQuery<TMe> =
+  { status: "loading" } | { status: "error"; error: unknown } | { status: "success"; data: TMe };
+
+export interface GuardOptions {
+  /** Drawn while the session or the profile is still resolving. */
+  loading: ReactNode;
+}
+
+/**
+ * Signed in, or off to sign in — remembering where they were headed, so the redirect afterwards
+ * lands on the page they actually wanted rather than the home screen.
+ */
+export function createRequireAuth(
+  useSession: () => SessionState,
+  signInPath: string,
+  { loading }: GuardOptions,
+) {
+  return function RequireAuth({ children }: { children: ReactNode }) {
+    const { isAuthenticated, isLoading } = useSession();
+    const location = useLocation();
+    if (isLoading) return <>{loading}</>;
+    if (!isAuthenticated)
+      return (
+        <Navigate to={signInPath} replace state={{ from: location.pathname + location.search }} />
+      );
+    return <>{children}</>;
+  };
+}
+
+/** The mirror: somebody already signed in has no business on the sign-in screen. */
+export function createRequireAnonymous(
+  useSession: () => SessionState,
+  homePath: string,
+  { loading }: GuardOptions,
+) {
+  return function RequireAnonymous({ children }: { children: ReactNode }) {
+    const { isAuthenticated, isLoading } = useSession();
+    if (isLoading) return <>{loading}</>;
+    if (isAuthenticated) return <Navigate to={homePath} replace />;
+    return <>{children}</>;
+  };
+}
+
+/**
+ * A gate on something the profile says — suspended, staff, on a given plan.
+ *
+ * `allow` gets the profile and answers yes or no. `onDenied` draws the refusal; `onError` draws
+ * the failure, and they are SEPARATE arguments on purpose. That separation is the whole point
+ * of this file: "you may not see this" and "we could not find out" are different sentences, and
+ * showing the first when the second is true is how an outage becomes a support ticket about
+ * permissions.
+ */
+export function createRequireProfile<TMe>(useMe: () => MeQuery<TMe>, { loading }: GuardOptions) {
+  return function requireProfile(
+    allow: (me: TMe) => boolean,
+    onDenied: ReactNode | (() => ReactNode),
+    onError: (error: unknown) => ReactNode,
+  ) {
+    return function RequireProfile({ children }: { children: ReactNode }) {
+      const query = useMe();
+      if (query.status === "loading") return <>{loading}</>;
+      if (query.status === "error") return <>{onError(query.error)}</>;
+      if (!allow(query.data)) return <>{typeof onDenied === "function" ? onDenied() : onDenied}</>;
+      return <>{children}</>;
+    };
+  };
+}

package/src/hydrate.ts

@@ -0,0 +1,36 @@
+/**
+ * The browser half of prerendering: deciding whether to hydrate or to mount fresh.
+ *
+ * Three separate repos invented all of this independently — same constant name, same string
+ * value, same decision, and near-identical explaining comments. That is not a coincidence worth
+ * deduping; it is one lesson learned three times, and it belongs somewhere it can be learned
+ * once.
+ *
+ * The constants themselves live in `prerender-contract.ts`, which imports nothing, because the
+ * BUILD needs them too and must not pull `react-dom/client` into a Node process to get a string.
+ */
+import type { ReactNode } from "react";
+import { createRoot, hydrateRoot } from "react-dom/client";
+import { PRERENDERED_ROUTE_ATTR } from "./prerender-contract.ts";
+
+export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
+
+/**
+ * Hydrate the render this file IS, and mount fresh over anything else.
+ *
+ * "Does the root have children" is the wrong question, and getting it wrong is silent. A static
+ * host answers every address it does not publish with the nearest `404.html` — and that file has
+ * the not-found page rendered INTO it — so an address served from a shell arrives at a full root
+ * holding somebody else's markup. Hydrating that is React reconciling two different pages: it
+ * recovers by throwing the whole tree away and says so in the console, which is a page that
+ * works and a bug nobody sees. The file names the route it is a render of, so we can simply ask.
+ *
+ * `route` is passed in rather than read from `window.location` on purpose. A localized app
+ * serves `/pt/pricing` from a file rendered for `/pricing`, with the locale carried in the
+ * router's `basename` — so the address and the route are different strings, and only the caller
+ * knows which one the build wrote.
+ */
+export function hydrateOrMount(rootEl: Element, tree: ReactNode, route: string): void {
+  if (rootEl.getAttribute(PRERENDERED_ROUTE_ATTR) === route) hydrateRoot(rootEl, tree);
+  else createRoot(rootEl).render(tree);
+}

package/src/i18n.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { applyBrandVars, i18nInitOptions } from "./i18n.ts";
+
+describe("applyBrandVars", () => {
+  it("fills placeholders anywhere in the tree and leaves the input alone", () => {
+    const input = { a: { b: ["Welcome to {{brand}}", "at {{brandDomain}}"] }, n: 1 };
+    const out = applyBrandVars(input, { brand: "Example", brandDomain: "example.com" });
+
+    expect(out).toEqual({ a: { b: ["Welcome to Example", "at example.com"] }, n: 1 });
+    expect(input.a.b[0]).toBe("Welcome to {{brand}}");
+  });
+
+  // The names come from `vars`, so adding one needs no edit here. Both donors hardcoded their
+  // own list inside the regex and both had to remember to keep it in step.
+  it("derives the placeholder names from vars, not from a hardcoded list", () => {
+    expect(applyBrandVars("{{anythingAtAll}}", { anythingAtAll: "yes" })).toBe("yes");
+  });
+
+  it("leaves an unknown placeholder alone rather than blanking it", () => {
+    // Blanking would silently ship "Contact  for help". Leaving it visible fails loudly.
+    expect(applyBrandVars("Contact {{nobody}}", { brand: "Example" })).toBe("Contact {{nobody}}");
+  });
+
+  it("is a no-op with no vars", () => {
+    const input = { a: "{{brand}}" };
+    expect(applyBrandVars(input, {})).toBe(input);
+  });
+});
+
+describe("i18nInitOptions", () => {
+  // The comment in both donors names the bug: `nonExplicitSupportedLngs` validates the BASE
+  // subtag, which rejects "pt-BR" (its base "pt" is not listed) and silently falls the whole
+  // app back to English. Its absence is load-bearing.
+  it("does not set nonExplicitSupportedLngs", () => {
+    const options = i18nInitOptions({
+      fallbackLng: "en",
+      supportedLngs: ["en", "pt-BR"],
+      storageKey: "app.locale",
+    });
+    expect(options).not.toHaveProperty("nonExplicitSupportedLngs");
+  });
+
+  // Only one donor had the query parameter, and it is the only detection source somebody chose
+  // on purpose and just now — so it goes first, ahead of storage and the browser.
+  it("detects the query parameter first when one is given", () => {
+    expect(
+      i18nInitOptions({
+        fallbackLng: "en",
+        supportedLngs: ["en"],
+        storageKey: "app.locale",
+        queryKey: "lang",
+      }).detection,
+    ).toMatchObject({
+      order: ["querystring", "localStorage", "navigator"],
+      lookupQuerystring: "lang",
+    });
+  });
+
+  it("omits the query source entirely when no key is given", () => {
+    const { detection } = i18nInitOptions({
+      fallbackLng: "en",
+      supportedLngs: ["en"],
+      storageKey: "app.locale",
+    });
+    expect(detection.order).toEqual(["localStorage", "navigator"]);
+    expect(detection).not.toHaveProperty("lookupQuerystring");
+  });
+});

package/src/i18n.ts

@@ -0,0 +1,101 @@
+/**
+ * The i18next bootstrap two donors wrote nearly comment-for-comment.
+ *
+ * Each browser surface spreads these into its own init with its own bundled resources:
+ *
+ * ```ts
+ * i18n.use(LanguageDetector).use(initReactI18next).init({ resources, ...i18nInitOptions({…}) })
+ * ```
+ *
+ * Keeping the options here is what stops a console, a storefront and a docs site in the same
+ * product from drifting apart on the details below — each of which is a bug somebody already
+ * shipped.
+ */
+
+export interface I18nInitOptions {
+  /** The language everything falls back to. */
+  fallbackLng: string;
+  /** Every language this app ships, as the exact tags used in the catalogs. */
+  supportedLngs: readonly string[];
+  /**
+   * Where the reader's choice is remembered.
+   *
+   * One key everywhere is a convention, not a mechanism: `localStorage` is scoped to an ORIGIN,
+   * so a console on `app.example.com` shares nothing with a storefront on `example.com` no
+   * matter what the key is called. Which is why {@link queryKey} exists.
+   */
+  storageKey: string;
+  /**
+   * The query parameter that hands a language ACROSS an origin, e.g. `"lang"`.
+   *
+   * When set it is detected FIRST, ahead of storage and the browser — it is the only one of the
+   * three that somebody chose on purpose and just now. A reader who picked Português on the
+   * storefront and followed a link into the app means it more than their laptop's locale does.
+   * It is cached on arrival, so it decides once and no URL inside the app has to carry it.
+   *
+   * Only one donor had this. The other has the same split-origin layout and the same problem.
+   */
+  queryKey?: string;
+}
+
+export function i18nInitOptions({
+  fallbackLng,
+  supportedLngs,
+  storageKey,
+  queryKey,
+}: I18nInitOptions) {
+  return {
+    fallbackLng,
+    supportedLngs: [...supportedLngs],
+    load: "currentOnly" as const,
+    interpolation: { escapeValue: false }, // React already escapes.
+    detection: {
+      order: queryKey
+        ? ["querystring", "localStorage", "navigator"]
+        : ["localStorage", "navigator"],
+      caches: ["localStorage"],
+      ...(queryKey ? { lookupQuerystring: queryKey } : {}),
+      lookupLocalStorage: storageKey,
+    },
+    react: { useSuspense: false },
+    // `nonExplicitSupportedLngs` is omitted deliberately, and both donors say so in the same
+    // words. Enabling it validates the BASE subtag against `supportedLngs`, which rejects a
+    // region-coded "pt-BR" (its base "pt" is not in the list) and silently falls the whole app
+    // back to English. Detected sub-locales like "en-US" already resolve to their base through
+    // i18next's ordinary fallback hierarchy, so the flag buys nothing and breaks pt-BR.
+  };
+}
+
+/**
+ * Substitute `{{brand}}`-style placeholders through a bundled resource tree, once, before
+ * i18next ever sees it.
+ *
+ * Done here rather than through interpolation because i18next v26 has no global interpolation
+ * defaults, and these strings are often resolved by dynamic key — so a wrapping `t()` would not
+ * reach them. The point is that a rename or a domain move is ONE edit in the brand constants
+ * instead of a sweep across every locale file.
+ *
+ * Returns a fresh tree; the input is untouched. The placeholder names come from `vars`, so
+ * adding one needs no change here — two donors hardcoded their own list in the regex and both
+ * had to remember to update it.
+ */
+export function applyBrandVars<T>(resources: T, vars: Record<string, string>): T {
+  const names = Object.keys(vars);
+  if (names.length === 0) return resources;
+  const pattern = new RegExp(
+    `\\{\\{(${names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\}\\}`,
+    "g",
+  );
+
+  const fill = (s: string): string => s.replace(pattern, (_, name: string) => vars[name] ?? "");
+
+  const walk = (value: unknown): unknown => {
+    if (typeof value === "string") return fill(value);
+    if (Array.isArray(value)) return value.map(walk);
+    if (value && typeof value === "object")
+      return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, walk(v)]));
+    return value;
+  };
+
+  return walk(resources) as T;
+}