@pithy-sh/ui-react 0.1.0

package/templates/src/client.test.tsx

@@ -0,0 +1,98 @@
+// @vitest-environment happy-dom
+
+import { act, type ReactNode } from "react";
+import { expect, test, vi } from "vitest";
+
+/**
+ * **The app mounts into a node it creates, so nothing in `index.html` can rename it out from under it.**
+ *
+ * This file used to find its mount point with `document.getElementById("root")` and render inside
+ * `if (container) { … }`, against a `<div id="root">` declared in `index.html`. Two strings, nothing
+ * comparing them. Renaming the div — an ordinary edit to your own HTML — produced an empty document
+ * with a 200: no throw, no log, a clean build and a green suite. The failure mode hardest to attribute,
+ * because the first three things anyone suspects are their own code, their build and their Worker, and
+ * none of them is wrong (#394).
+ *
+ * ## What this proves, and how it goes red
+ *
+ * The document is given a mount node with a **deliberately wrong id** before `client.tsx` is imported —
+ * exactly the document an adopter who renamed the div would have. Code that looks an id up finds
+ * nothing and renders nothing, and this goes red; only code that creates its own node can pass. The id
+ * is invented here and reachable from nowhere else, which is what a canary is for: asserting `"root"`
+ * would have passed against the very edit this catches.
+ *
+ * `./router` is stubbed for the same reason `src/turnstile.test.tsx` stubs `./pithy-config` — the real
+ * one resolves every screen, and those read `virtual:pithy/*` modules that only a Vite build serves.
+ * Mounting is what is under test here, not routing.
+ *
+ * ## And the app is mounted **under a translator**, which is the second thing this file proves
+ *
+ * `src/pithy-locale.tsx` has its own gate, and that gate mounts `<PithyLocale>` itself — so it proves
+ * the component works and never that anything renders it. Deleting the element and its import from
+ * this file left the whole repository green: an app with no translator over it, every screen in
+ * English under whatever `lang` was negotiated, and not one test anywhere going red. That is the very
+ * defect the seeded-gate convention exists to stop, one level up — the file that was broken is the
+ * file with no gate on it.
+ *
+ * So `./pithy-locale` is stubbed with a wrapper that marks the subtree it draws, and the app has to be
+ * found **inside** it. A stub rather than the real component on purpose: with nothing composed the real
+ * one renders its children untouched, which is indistinguishable from not being rendered at all — the
+ * assertion could not exist. What language it then mounts is `pithy-locale.test.tsx`'s subject, and
+ * this file does not restate it.
+ *
+ * **And `./pithy-config` is stubbed too, which is not a detail.** `src/pithy-locale.tsx` reads the i18n
+ * projection through it, so a `client.tsx` that reached the real module would reach a `virtual:pithy/*`
+ * one — and a seeded gate that needs one of those runs in this repository, where the kit\'s own Vitest
+ * config aliases them, and nowhere else. It would fail in every adopter\'s repository, on the first
+ * `vitest run` after scaffolding, over a file they had not touched. The stub above keeps that module
+ * out of the graph today; this one is what keeps this file green if it is ever narrowed. The projection
+ * is stubbed disabled, which is the shape a project that never composed `i18n` projects.
+ */
+
+/** The id the document's mount node carries. Not the one anything renders into, on purpose. */
+const CANARY_ID = "pithy-gate-canary-not-the-mount-id";
+
+/** What the stubbed router draws. Finding it in the document is the whole assertion. */
+const MOUNTED = "pithy-gate-canary-mounted";
+
+/** The attribute the stubbed provider marks its subtree with. Invented here, like every canary above. */
+const WRAPPED = "data-pithy-gate-locale";
+
+vi.mock("./router", () => ({ Router: () => MOUNTED }));
+
+vi.mock("./pithy-locale", () => ({
+  PithyLocale: ({ children }: { children: ReactNode }) => <div {...{ [WRAPPED]: "" }}>{children}</div>,
+}));
+
+vi.mock("./pithy-config", () => ({ i18nConfig: { enabled: false } }));
+
+// React refuses to run `act` unless the environment says it is a test one.
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+test("the app mounts even though no node in the document carries the id it once looked for", async () => {
+  // The canary must not have drifted onto the real value: an id of "root" would pass against the bug.
+  expect(CANARY_ID).not.toBe("root");
+
+  document.body.innerHTML = `<div id="${CANARY_ID}"></div>`;
+
+  // Imported inside the case, because importing it is what mounts.
+  await act(async () => {
+    await import("./client");
+  });
+
+  expect(document.body.textContent, "nothing rendered — client.tsx did not mount into a node of its own").toContain(
+    MOUNTED,
+  );
+  // And it did not mount into the adopter's element. The node it renders into is its own.
+  expect(document.getElementById(CANARY_ID)?.textContent).toBe("");
+
+  // The app is under a translator, and this is the only place that is true of. Delete `<PithyLocale>`
+  // from `client.tsx` and every screen renders English under whatever language the document declares —
+  // with nothing else in the repository noticing, which is how it got shipped once already.
+  const wrapped = document.querySelector(`[${WRAPPED}]`);
+  expect(wrapped, "client.tsx renders no <PithyLocale> — the app mounts with no translator over it").not.toBeNull();
+  // Inside it, not beside it. A provider rendered as a sibling of the app translates nothing.
+  expect(wrapped?.textContent, "the app is not inside <PithyLocale> — nothing under it reads a catalog").toContain(
+    MOUNTED,
+  );
+});

package/templates/src/client.tsx

@@ -0,0 +1,51 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { PithyLocale } from "./pithy-locale";
+import { Router } from "./router";
+// Yours, and Pithy's. `styles.css` is written once and then belongs to you; `pithy-screens.css` carries
+// the classes Pithy's own screens render, in a cascade layer, so anything you write here wins over it.
+// Pithy's screens import it themselves as well — that is what keeps them styled when they are added to
+// a project whose `client.tsx` was written before they were.
+import "./styles.css";
+import "./pithy-screens.css";
+
+/**
+ * The mount node, created here rather than found in `index.html`.
+ *
+ * **This is the whole of the mount contract, and it is one statement.** It used to be two: a
+ * `<div id="root">` in `index.html` and a `getElementById("root")` here, with an `if (container)`
+ * around the render. Renaming that div — an ordinary thing to do to your own HTML — made the app
+ * render nothing, throw nothing and log nothing: an empty document with a 200, a clean build and a
+ * green suite (#394). The guard was the defect; deleting it alone would have made the same rename an
+ * immediate error, and not having the second string at all means there is no rename to make.
+ *
+ * The id is still set, so `#root` works as a styling hook. Nothing reads it.
+ *
+ * Put whatever you like in `index.html`'s `<body>` — a splash, a `<noscript>` — and the app mounts
+ * after it. If you need it somewhere else in the document, append it there; this is ordinary DOM code,
+ * not a convention. The `<script type="module">` that loads this file is deferred, so `document.body`
+ * exists by the time this runs.
+ */
+const container = document.body.appendChild(document.createElement("div"));
+container.id = "root";
+
+/**
+ * The app, in one language.
+ *
+ * `<PithyLocale>` is the whole of the i18n wiring, and it is one component rather than a call here
+ * because `lang` on the document and the words on the page have to come from a **single** resolved
+ * locale. They used to come from two places: this file negotiated a locale and set `lang` from it, and
+ * nothing mounted a translator at all — so a Spanish reader met `<html lang="es">` over a page rendering
+ * English, which is worse for a screen reader than never having negotiated. `src/pithy-locale.tsx` holds
+ * the argument in full.
+ *
+ * With no i18n capability composed it renders its children untouched, and every screen reads the English
+ * it was scaffolded with. Your own catalogs go on it: `<PithyLocale messages={{ fr: … }}>`.
+ */
+createRoot(container).render(
+  <StrictMode>
+    <PithyLocale>
+      <Router />
+    </PithyLocale>
+  </StrictMode>,
+);

package/templates/src/payments.tsx

@@ -0,0 +1,147 @@
+import type { Translator } from "@pithy-sh/core/src/i18n/translator";
+import { getEntitlements, type PaymentsFailure } from "@pithy-sh/payments/src/client/api";
+import type { PriceVisitor } from "@pithy-sh/payments/src/pricing/location";
+import { fetchPriceVisitor, type PriceVisitorOptions } from "@pithy-sh/payments/src/pricing/visitor";
+import { useEffect, useState } from "react";
+import { paymentsConfig } from "./pithy-config";
+
+/**
+ * The thin bridge between the narrowed projection and the package's headless hooks.
+ *
+ * Two things live here and nothing else. {@link paymentsClient} binds every call to this project's own
+ * base path, once, so a screen never repeats it — and because it is a module constant it is a stable
+ * reference, which keeps the hooks' effects from re-running on every render.
+ *
+ * {@link holdsEntitlement} is the data half of the router's entitlement guard. The guard is a **UX
+ * affordance, never a security boundary**: the server's `requireEntitlement()` is the boundary, and this
+ * exists so a visitor without `pro` lands on the paywall instead of watching a screen 403. Anything this
+ * answers wrongly costs a redirect, never access.
+ *
+ * Everything the purchase flow actually does — the calls, the redirect-and-return dance, the error
+ * mapping — lives in `@pithy-sh/payments`, not here. That split is deliberate: this file is written once
+ * and is yours from then on, and store rules move. A paywall frozen in an adopter's repo is one Pithy
+ * cannot fix; a paywall that calls the package's hooks upgrades with a minor release.
+ */
+
+/** Where the payments routes are, bound once. Pass it to every hook. */
+export const paymentsClient = { basePath: paymentsConfig.basePath };
+
+/**
+ * The class Paddle renders an inline checkout into.
+ *
+ * A class name, not an id — that is Paddle's `frameTarget` contract. The container is rendered only when
+ * the handoff asks for it, from `paddle.checkout` in your config: switch that to `inline` and the form
+ * appears in the page instead of over it, with no edit to any screen.
+ *
+ * **It is here because two screens sell.** The paywall and the pricing page each declared their own copy
+ * of this string, and the class is the one thing about it you are meant to act on — `.pithy-checkout` is
+ * an adopter hook, deliberately styled by no stylesheet Pithy ships, so that the frame lands where your
+ * layout wants it. A styling instruction against two names that agree today is one that styles half your
+ * checkouts the day somebody renames one (#391, item E).
+ *
+ * That is also why the unstyled report never mentions it: it has no rule anywhere on purpose, and a
+ * class read out of an identifier is not a literal that report can see. Both facts are intended.
+ */
+export const CHECKOUT_FRAME = "pithy-checkout";
+
+/**
+ * What Paddle.js starts with, or null when this project has no Paddle rail.
+ *
+ * Null rather than absent, because every hook that takes it takes null and reads it as "nothing to
+ * load". That is what keeps a pricing screen free of a conditional hook call, and it is why the rail
+ * being switched off is an empty state rather than an error about a provider nobody asked for.
+ *
+ * **The client token is the only credential in this bundle, and it belongs here.** Paddle publishes it
+ * for exactly this — a browser opens a checkout with it. The API key and the webhook signing secret are
+ * in the secrets store and are not expressible in a projection.
+ */
+export const paddleSetup = paymentsConfig.paddle;
+
+/**
+ * What a refusal from the store reads as, in the reader's language.
+ *
+ * **A `PaymentsFailure` carries a namespaced `code`, and the code is the catalog key.** Every screen
+ * here used to render `failure.message` — the sentence the server put on the wire, which is English and
+ * is only ever English, because `message` is written at the throw site in the one language a throw site
+ * has. So a reader on an otherwise-Spanish page met English the moment anything went wrong, which is
+ * the moment copy matters most and the moment nobody tests.
+ *
+ * This is the contract `docs/I18N.md` § *Errors* states, and the reason it is `maybe` rather than `t`:
+ * `t` is total, so a code no catalog covers would render as the code itself — `payments/product_not_found`
+ * on a buyer's screen, in place of the English sentence the server took care to send. `maybe` answers
+ * null on a miss, and the `??` is what makes the server's own words the floor.
+ *
+ * So a project that never composed `i18n` renders exactly what it always did, byte for byte: the baked
+ * translator holds only the screen's own English, no key matches a `payments/…` code, and the message
+ * comes straight through. The `client/…` sentinels this package mints for a browser that is offline or
+ * an answer it cannot read take the same path, and their English is likewise unchanged.
+ *
+ * It lives here, with `CHECKOUT_FRAME`, for the same reason that does: three screens render a failure,
+ * and three copies of one lookup is two screens that keep saying it in English the day somebody fixes
+ * the third.
+ */
+export function failureText(t: Translator, failure: PaymentsFailure): string {
+  // `params` and not just the code: `interpolate` leaves an unsupplied placeholder exactly as written,
+  // so a translated sentence that names one would render `{board}` on the screen — worse than the
+  // English it replaced. `docs/I18N.md` states the contract as `t.maybe(code, params) ?? message`.
+  return t.maybe(failure.code, failure.params) ?? failure.message;
+}
+
+/**
+ * Whether the visitor holds `key` right now.
+ *
+ * "The visitor" is shorthand for whoever the server says this session holds entitlements for — the person
+ * under a project that bills users, the organization they are acting for under one that bills
+ * organizations. Nothing here names either, and nothing here should: the read carries the session and the
+ * server decides the holder, so no argument this file could pass would be one it was entitled to choose.
+ *
+ * `true` when payments is not composed, which is the same direction the session guard takes when there is
+ * no auth: a guard that arrives with a capability must not lock a screen when the capability is gone. The
+ * server is what protects the feature.
+ *
+ * A read that fails answers `false` — this is a route guard, so it is a lock, and a lock fails shut. The
+ * choice is written here rather than inherited from the reader: a caller that *named* the visitor's plan
+ * would need the opposite, and `getEntitlements` hands both callers the same honest answer.
+ */
+export async function holdsEntitlement(key: string): Promise<boolean> {
+  if (!paymentsConfig.enabled) return true;
+  const held = await getEntitlements(paymentsClient);
+  return held.ok && held.value.some((entitlement) => entitlement.key === key && entitlement.granted);
+}
+
+/**
+ * Who Paddle prices this visitor as, once there is a session to ask about.
+ *
+ * The customer it answers is the store customer for whoever the session holds purchases for — a person, or
+ * the organization they buy on behalf of — read on the server from that session and never named here.
+ *
+ * **Two renders, and that is the design rather than a flicker to hide.** A pricing screen paints before
+ * the session resolves, so the first figure is the IP estimate — labelled `Estimated.`, because it is —
+ * and the second is the price the checkout will charge, from the billing address on file. Every checkout
+ * on the web recalculates when the address arrives; the only thing that makes it a broken promise is a
+ * first figure that did not admit what it was.
+ *
+ * `ask` is false for a stranger and while the session is still being read, so a marketing page makes no
+ * round trip for an answer known in advance to be "nobody".
+ *
+ * The reading and the guarding live in `@pithy-sh/payments`, not here — this file is yours from the day
+ * it is written, and where a customer id comes from is not a thing to freeze into your repository. A
+ * failed read answers null, which quotes from the IP and says so.
+ */
+export function usePriceVisitor(ask: boolean, options?: PriceVisitorOptions): PriceVisitor | null {
+  const [visitor, setVisitor] = useState<PriceVisitor | null>(null);
+
+  useEffect(() => {
+    if (!ask || !paymentsConfig.enabled) return;
+    let live = true;
+    void fetchPriceVisitor(options).then((answer) => {
+      if (live) setVisitor(answer);
+    });
+    return () => {
+      live = false;
+    };
+    // `options` is `paymentsClient`, a module constant, so this asks once per session resolution.
+  }, [ask, options]);
+
+  return visitor;
+}

package/templates/src/pithy-config.tsx

@@ -0,0 +1,93 @@
+import authModule from "virtual:pithy/auth";
+import i18nModule from "virtual:pithy/i18n";
+import paymentsModule from "virtual:pithy/payments";
+import turnstileModule from "virtual:pithy/turnstile";
+
+/**
+ * The composed capabilities' client-safe config, narrowed once for the whole client.
+ *
+ * `virtual:pithy/<capability>` is a union discriminated on `enabled`, because a capability that is
+ * not composed projects `{ enabled: false }` and nothing else — that is what makes importing an
+ * absent capability safe instead of a build error. Narrowing at every use would put a guard in front
+ * of every field read, so it happens here instead, once.
+ *
+ * The `enabled: false` branch carries the capability's own defaults rather than `undefined`, so a
+ * screen reads a field without a guard. Those defaults are not a fallback anyone should rely on:
+ * `pithy ui add --auth` refuses a Worker that does not compose `auth`, so on a scaffolded project the
+ * enabled branch is always the live one. They exist for the case where the capability is removed from
+ * `pithy.config.ts` *after* the scaffold — the screens keep compiling, and `enabled` is there so one
+ * can bail cleanly rather than render a form that posts nowhere.
+ */
+export const authConfig = authModule.enabled
+  ? authModule
+  : {
+      enabled: false as const,
+      basePath: "/auth",
+      providers: { google: false, apple: false, facebook: false, github: false },
+      otpLength: 6,
+      signUpEnabled: true,
+    };
+
+/** Turnstile's projection, narrowed the same way. `enabled` is false unless a login widget resolved. */
+export const turnstileConfig = turnstileModule.enabled
+  ? turnstileModule
+  : {
+      enabled: false as const,
+      sitekey: "",
+      // Blank for the same reason the sitekey is: a widget that cannot render has no action to solve
+      // for, and a plausible-looking default here would be a second copy of a string the enabled branch
+      // is the only statement of (#377).
+      action: "",
+      mode: "visible" as const,
+      token: { field: "cf-turnstile-response", header: null },
+    };
+
+/**
+ * Payments' projection, narrowed the same way. `enabled` is false when the capability is not composed, and
+ * also when it is composed with an empty catalog — a paywall with nothing on it is nothing to render, so
+ * the two read alike and a screen branches once.
+ *
+ * Only the browser-safe half of the catalog is here. Apple's issuer id, Google's service-account
+ * credentials and Stripe's secret and signing keys live in the secrets store and never enter a projection.
+ */
+export const paymentsConfig = paymentsModule.enabled
+  ? paymentsModule
+  : {
+      enabled: false as const,
+      environment: "dev",
+      rails: { apple: false, google: false, stripe: false, lemonSqueezy: false, paddle: false },
+      basePath: "/payments",
+      paddle: null as { clientToken: string; environment: "sandbox" | "production"; checkout: string } | null,
+      products: [] as {
+        id: string;
+        type: "consumable" | "non_consumable" | "subscription";
+        entitlements: string[];
+        name: string;
+        skus: { stripe: string | null; lemonSqueezy: string | null; paddle: string | null };
+      }[],
+    };
+
+/**
+ * The i18n capability's projection, narrowed the same way. `enabled` is false unless the capability is
+ * composed, and then every screen renders the English it was scaffolded with — which is the whole of
+ * what makes this capability optional.
+ *
+ * **Locale metadata only. Never catalogs.** The projection is inlined into the main chunk, so a catalog
+ * carried here would be downloaded by every reader in every language before the first paint. Catalogs
+ * arrive by dynamic import, one chunk per locale, from `@pithy-sh/i18n`.
+ *
+ * The disabled branch is the kit's own defaults, for the reason the three above carry theirs: a screen
+ * reads a field without a guard. `en` is not a claim that this project speaks English — it is what the
+ * templates are written in, and it is what `t()` falls back to when nothing negotiated.
+ */
+export const i18nConfig = i18nModule.enabled
+  ? i18nModule
+  : {
+      enabled: false as const,
+      supportedLocales: ["en"],
+      defaultLocale: "en",
+      queryParam: "lang",
+      storageKey: "pithy.locale",
+      browserResolvers: ["query", "account", "storage", "navigator", "server", "default"],
+      exceptions: {} as Record<string, string>,
+    };

package/templates/src/pithy-locale.test.tsx

@@ -0,0 +1,140 @@
+// @vitest-environment happy-dom
+
+import { KIT_CATALOGS } from "@pithy-sh/i18n/src/catalogs/kit";
+import { useTranslator } from "@pithy-sh/i18n/src/react/translator";
+import { act, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, test, vi } from "vitest";
+
+/**
+ * **The document may not declare a language the page does not speak.**
+ *
+ * `client.tsx` negotiated a locale and put it on `<html lang>`, and nothing mounted a translator behind
+ * it. A project composing `i18n` therefore served `<html lang="es">` over a page rendering the English
+ * every screen bakes — and that is worse than leaving `lang="en"` alone, because assistive technology
+ * believes the attribute: a screen reader switches voice and pronounces English with Spanish phonetics.
+ *
+ * `src/pithy-locale.tsx` is what makes the two one statement, and this is the gate that keeps them one
+ * after the file is yours. Both halves are asserted from a single mount, which is the whole point — a
+ * test that checked them separately would pass on a page where each was independently reasonable.
+ *
+ * ## What this proves, and how it goes red
+ *
+ * The projection is mocked to negotiate a locale the kit has a real translation for, and a probe screen
+ * is rendered underneath with **invented** English baked into it. The probe's rendered text must be the
+ * kit's Spanish and not the English it carries, and `document.documentElement.lang` must be the same
+ * locale that produced those words. Delete the provider and the probe renders its baked English; delete
+ * the negotiation and `lang` never moves. Either way this goes red.
+ *
+ * The invented English is what makes the first assertion mean anything: a plausible sentence could
+ * coincide with a catalog entry, and then a page that mounted no provider at all would still pass.
+ *
+ * `./pithy-config` is mocked for the reason `src/turnstile.test.tsx` and `src/routes/pithy/sign-in.test.tsx`
+ * mock it — it imports the `virtual:pithy/*` modules, which only a Vite build serves. Mocked here it is
+ * also the input: this is the one gate whose subject is what the projection says.
+ */
+
+/** The locale the mocked projection negotiates. Not `en`, on purpose — see below. */
+const CANARY_LOCALE = "es";
+
+/** The key the probe renders. Base-group copy: `router.tsx` says it while a route loads. */
+const KEY = "app/loading";
+
+/** What the probe bakes for {@link KEY}. Invented here, so no catalog can answer with it by accident. */
+const CANARY_ENGLISH = "pithy-gate-canary-untranslated";
+
+vi.mock("./pithy-config", () => ({
+  i18nConfig: {
+    enabled: true,
+    supportedLocales: [CANARY_LOCALE],
+    defaultLocale: CANARY_LOCALE,
+    queryParam: "lang",
+    storageKey: "pithy.locale",
+    // Only the link that cannot read a global, so this case is about the wiring and not about whatever
+    // a test environment happens to have in `localStorage` or on the URL.
+    browserResolvers: ["default"],
+    exceptions: {},
+  },
+}));
+
+// React refuses to run `act` unless the environment says it is a test one.
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+/**
+ * How long the catalog gets to land, and how long each poll waits.
+ *
+ * **A deadline in milliseconds, waited on — not a fixed number of turns, and not no wait at all.** The
+ * catalog arrives by dynamic `import()`, so how long it takes is the machine's answer and not this
+ * file's: a cold import plus its transform under a loaded CI runner is orders of magnitude slower than
+ * a warm one, and this file is copied into every adopter's repository, where the first `vitest run`
+ * after scaffolding is the coldest run that will ever happen there. A gate that reds on a file the
+ * adopter never wrote is a gate they delete.
+ *
+ * Ten seconds is hundreds of times the measured cold cost, and the case below states its own 30s
+ * timeout so the deadline is what reports the failure rather than Vitest's default five — which the
+ * kit raises for its own suites and an adopter's runner does not.
+ */
+const SETTLE_DEADLINE_MS = 10_000;
+const SETTLE_POLL_MS = 5;
+const CASE_TIMEOUT_MS = 30_000;
+
+/**
+ * Wait until the translator has mounted, rather than assuming it has by now.
+ *
+ * The transition **is** the signal: until the catalog lands the tree renders {@link CANARY_ENGLISH},
+ * and the whole assertion is that it stops. Polling on a macrotask rather than flushing microtasks,
+ * because `loadKitCatalog` is a real `import()` and Vitest resolves that off the module graph rather
+ * than out of the current tick.
+ */
+async function untilTranslated(container: HTMLElement): Promise<void> {
+  const deadline = Date.now() + SETTLE_DEADLINE_MS;
+  while (container.textContent === CANARY_ENGLISH) {
+    if (Date.now() > deadline) {
+      throw new Error(
+        `The tree still renders its baked English after ${SETTLE_DEADLINE_MS}ms — no translator was mounted over it.`,
+      );
+    }
+    await act(async () => {
+      await new Promise((resume) => setTimeout(resume, SETTLE_POLL_MS));
+    });
+  }
+}
+
+/** A screen, as every seeded screen is written: one key, and the English it was scaffolded with. */
+function Probe(): ReactNode {
+  const t = useTranslator({ [KEY]: CANARY_ENGLISH });
+  return t.t(KEY);
+}
+
+test(
+  "the page renders the language the document declares",
+  async () => {
+    // The canary, refused. Run this at `en` and it passes against the exact defect it exists to catch:
+    // a page with no provider at all renders English, and `lang="en"` agrees with it.
+    expect(CANARY_LOCALE).not.toBe("en");
+    // And the kit really translates the key, so "not the baked English" is a reachable state.
+    const translated = KIT_CATALOGS[CANARY_LOCALE]?.[KEY];
+    expect(translated, `the kit ships no ${CANARY_LOCALE} for ${KEY}`).toBeTypeOf("string");
+    expect(translated).not.toBe(CANARY_ENGLISH);
+
+    const { PithyLocale } = await import("./pithy-locale");
+    const container = document.body.appendChild(document.createElement("div"));
+    await act(async () => {
+      createRoot(container).render(
+        <PithyLocale>
+          <Probe />
+        </PithyLocale>,
+      );
+    });
+
+    // The catalog arrives by dynamic import, so the provider mounts some time after the first paint —
+    // how long is the machine's answer, not this file's. Waited on rather than counted out.
+    await untilTranslated(container);
+
+    expect(container.textContent, "the tree rendered its baked English — no translator was mounted over it").toBe(
+      translated,
+    );
+    expect(document.documentElement.lang, "the document declares a language nothing negotiated").toBe(CANARY_LOCALE);
+  },
+  CASE_TIMEOUT_MS,
+);