@eifi1/ui-kit 0.32.2 → 0.33.0

package/src/billing/checkout-return.ts

@@ -0,0 +1,90 @@
+/**
+ * The way back from the provider's checkout (docs/billing-harmonization.md §14.4,
+ * decision 20): `?checkout=done` on the app's subscription page — kastlan's
+ * `/admin/billing`, keksdose's and Kurvenschmiede's `/settings/subscription`.
+ *
+ * The checkout request carries NO success URL: a redirect the client chooses is an open
+ * redirect, and Paddle's create-transaction takes none. The way back is configuration
+ * instead — the pay page's Paddle.js `successUrl` (`checkoutReturnUrl(returnUrl)`), or a
+ * hosted checkout's redirect in Paddle's dashboard — and the page that lands reads the
+ * marker with {@link isCheckoutReturn}, then drops it with `replace`
+ * ({@link withoutCheckoutReturn}) so a reload or a shared link does not count twice.
+ *
+ * Pure and router-agnostic, and imports nothing: the pay page (`dist/pay/`, no React)
+ * bundles this module too. server-kit names the same two values
+ * (`CHECKOUT_RETURN_PARAM`, `CHECKOUT_RETURN_VALUE`, `checkout_return_url`) for the
+ * deploy notes and its tests.
+ */
+
+/** The query parameter of the way back. */
+export const CHECKOUT_RETURN_PARAM = "checkout";
+/** Its one value: the buyer came back from a completed checkout. */
+export const CHECKOUT_RETURN_VALUE = "done";
+
+/** The query of `where`, however the app holds it: a search string ("?a=1"), a whole
+ *  URL, `URLSearchParams`, or a location (`{ search }`). */
+function paramsOf(where: string | URLSearchParams | { search: string }): URLSearchParams {
+  if (where instanceof URLSearchParams) return where;
+  const text = typeof where === "string" ? where : where.search;
+  const query = text.includes("?") ? text.slice(text.indexOf("?") + 1) : text;
+  // A whole URL's hash is not part of its query.
+  return new URLSearchParams(query.split("#")[0]);
+}
+
+/**
+ * Whether the page was reached as the way back from a checkout: `?checkout=done`.
+ *
+ *     const returned = isCheckoutReturn(location.search);       // react-router's useLocation()
+ *     const returned = isCheckoutReturn(searchParams);           // useSearchParams()[0]
+ */
+export function isCheckoutReturn(where: string | URLSearchParams | { search: string }): boolean {
+  return paramsOf(where).get(CHECKOUT_RETURN_PARAM) === CHECKOUT_RETURN_VALUE;
+}
+
+/**
+ * The same parameters without the marker — every other one kept, in order. A new
+ * object; the one passed in is not changed:
+ *
+ *     setSearchParams((p) => withoutCheckoutReturn(p), { replace: true });
+ */
+export function withoutCheckoutReturn(params: URLSearchParams): URLSearchParams {
+  const next = new URLSearchParams(params);
+  next.delete(CHECKOUT_RETURN_PARAM);
+  return next;
+}
+
+/**
+ * The subscription page's way-back URL: `page` with `checkout=done` in its query —
+ * after any query it already has, before its hash. A marker already there is replaced,
+ * not doubled.
+ *
+ *     checkoutReturnUrl("https://keksdose.app/settings/subscription")
+ *     // → "https://keksdose.app/settings/subscription?checkout=done"
+ *
+ * What the pay page hands Paddle.js as `successUrl`, and what a hosted checkout's
+ * redirect is set to in Paddle's dashboard.
+ */
+export function checkoutReturnUrl(page: string): string {
+  const hashAt = page.indexOf("#");
+  const hash = hashAt === -1 ? "" : page.slice(hashAt);
+  const beforeHash = hashAt === -1 ? page : page.slice(0, hashAt);
+  const queryAt = beforeHash.indexOf("?");
+  const path = queryAt === -1 ? beforeHash : beforeHash.slice(0, queryAt);
+  // Kept as written, part by part: a URLSearchParams round trip would re-encode the
+  // page's own parameters (a space as "+").
+  const kept = (queryAt === -1 ? "" : beforeHash.slice(queryAt + 1))
+    .split("&")
+    .filter((part) => part !== "" && decodeKey(part) !== CHECKOUT_RETURN_PARAM);
+  kept.push(`${CHECKOUT_RETURN_PARAM}=${CHECKOUT_RETURN_VALUE}`);
+  return `${path}?${kept.join("&")}${hash}`;
+}
+
+/** The decoded key of one `key=value` part of a query. */
+function decodeKey(part: string): string {
+  const key = part.split("=")[0].replace(/\+/g, " ");
+  try {
+    return decodeURIComponent(key);
+  } catch {
+    return key;
+  }
+}

package/src/billing/pay-page.ts

@@ -0,0 +1,242 @@
+import type { UiKitLabels } from "../i18n/kit-labels";
+import { checkoutReturnUrl } from "./checkout-return";
+
+/**
+ * The kit's pay page (docs/billing-harmonization.md §14.4, decision 19 as amended): a
+ * standalone static page that ui-kit ships as `dist/pay/`, and that each app serves on
+ * its own pay host, `pay.<app domain>` — a separate origin, approved in Paddle, where
+ * Paddle.js shares the origin with nothing: no sign-in, no app code, no storage.
+ *
+ * Paddle's create-transaction answers `checkout.url`: the pay page's URL plus
+ * `?_ptxn=<txn>`, and Paddle.js on that page opens the transaction by itself. The app
+ * sends the buyer there with {@link payPageUrl}, which adds the buyer's language; the
+ * page maps it to Paddle's checkout locale ({@link paddleLocale}). Everything else the
+ * page needs — the client-side token, sandbox or live, the way back — is the app's
+ * `pay-config.json`, written at its web build by the `eifi1-pay-page` script.
+ *
+ * Pure, and React-free: the page's own script (`pay-page/pay.ts`) and that build script
+ * bundle this module. The exports below the barrel's four are theirs.
+ */
+
+/** Paddle's two environments: the sandbox's client-side tokens start `test_`, live
+ *  ones `live_`. */
+export type PaddleEnvironment = "sandbox" | "live";
+
+/** The pay page's language parameter: `?lang=<kit locale>`. */
+export const PAY_PAGE_LANG_PARAM = "lang";
+
+/** The kit's seven languages (`KitLanguageCode`), as the page reads them. */
+const PAY_PAGE_LANGUAGES = ["de-CH", "en", "es", "fr", "it", "hu", "zh"] as const;
+
+/** One of the kit's languages, as the page speaks it. */
+export type PayPageLanguage = (typeof PAY_PAGE_LANGUAGES)[number];
+
+/**
+ * The kit's language → Paddle's checkout locale (`Paddle.Checkout.open`,
+ * `settings.locale`, read 2026-10-09: ar, zh-Hans, zh-TW, da, nl, en, fr, de, it, ja, ko,
+ * no, pl, pt, pt-BR, tr, ru, es, sv). Paddle has no Hungarian: a Hungarian buyer gets
+ * English always, not Paddle's guess from the browser. The page's own lines stay in the
+ * kit's language, Hungarian included.
+ */
+const PADDLE_LOCALES: Readonly<Record<PayPageLanguage, string>> = {
+  en: "en",
+  "de-CH": "de",
+  fr: "fr",
+  it: "it",
+  es: "es",
+  zh: "zh-Hans",
+  hu: "en",
+};
+
+/** Paddle's transaction parameter on a pay page link. @internal */
+export const PAY_PAGE_TRANSACTION_PARAM = "_ptxn";
+
+/**
+ * The kit language one tag names, or undefined — `resolveLanguage`'s rule
+ * (src/i18n/languages.ts), restated here because that module loads the seven catalogues
+ * and the page must stay a few kilobytes: exact first, ignoring case and reading `_` as
+ * `-`; then by language, so every German is `de-CH`, every Chinese `zh` (Simplified),
+ * and any regional form its base (`fr-CA` → `fr`).
+ */
+function kitLanguageOf(tag: unknown): PayPageLanguage | undefined {
+  if (typeof tag !== "string") return undefined;
+  const clean = tag.trim().replace(/_/g, "-");
+  if (!clean) return undefined;
+  const lower = clean.toLowerCase();
+  const exact = PAY_PAGE_LANGUAGES.find((code) => code.toLowerCase() === lower);
+  if (exact) return exact;
+  const language = lower.split("-")[0];
+  return PAY_PAGE_LANGUAGES.find((code) => code.split("-")[0].toLowerCase() === language);
+}
+
+/**
+ * The kit's locale → Paddle's checkout locale: `de-CH` → `de`, `zh` → `zh-Hans`, `hu` →
+ * `en` (Paddle has no Hungarian), the others as they are. Any tag is read as the kit
+ * reads it (`de-AT` is the one German, `zh-TW` the one Chinese); one the kit doesn't
+ * ship is English.
+ */
+export function paddleLocale(kitLocale: string): string {
+  return PADDLE_LOCALES[kitLanguageOf(kitLocale) ?? "en"];
+}
+
+/**
+ * The checkout's `{url}` with the buyer's language: `lang=<kit locale>` on a pay page
+ * link (one that carries `_ptxn`); any other URL — a hosted checkout's, which takes its
+ * own `locale` — unchanged, as is a locale the kit doesn't ship.
+ *
+ *     const { url } = await api.checkout({ plan, interval, currency });
+ *     noteCheckoutStarted(user.id, overview);
+ *     window.location.assign(payPageUrl(url, i18n.language));
+ *
+ * A wrong `lang` costs nothing but the language: the page falls back to the browser's.
+ */
+export function payPageUrl(checkoutUrl: string, locale: string): string {
+  const language = kitLanguageOf(locale);
+  if (!language) return checkoutUrl;
+  let url: URL;
+  try {
+    url = new URL(checkoutUrl);
+  } catch {
+    return checkoutUrl;
+  }
+  if (!url.searchParams.has(PAY_PAGE_TRANSACTION_PARAM)) return checkoutUrl;
+  url.searchParams.set(PAY_PAGE_LANG_PARAM, language);
+  return url.toString();
+}
+
+/**
+ * The language the page speaks: its `lang` parameter, else the browser's languages in
+ * their order, each matched to the kit's; else English. @internal
+ */
+export function payPageLanguage(
+  lang: string | null | undefined,
+  browserLanguages: readonly string[] = [],
+): PayPageLanguage {
+  for (const candidate of [lang, ...browserLanguages]) {
+    const found = kitLanguageOf(candidate);
+    if (found) return found;
+  }
+  return "en";
+}
+
+/* ── The page's words ──────────────────────────────────────────────────────── */
+
+/**
+ * The page's words in one language — built into `pay.js` at the kit's build from the
+ * seven catalogues, since the page has no React and no provider. @internal
+ */
+export interface PayPageStrings {
+  /** `billing.payOpening`, while the checkout opens. */
+  opening: string;
+  /** `billing.payNothing`: no `_ptxn`, or no token (billing off). */
+  nothing: string;
+  /** `billing.payFailed`: Paddle.js didn't load, or the configuration is wrong. */
+  failed: string;
+  /** `billing.payBack`: the buyer closed the checkout. */
+  closed: string;
+  /** `common.back`: the link to the app's subscription page. */
+  back: string;
+  /** `legal.links.terms` and `legal.links.privacy`: the footer's links. */
+  terms: string;
+  privacy: string;
+  /** `legal.navLabel`: the footer's `<nav>`. */
+  legal: string;
+}
+
+/** The page's words, read from one of the kit's catalogues. @internal */
+export function payPageStrings(labels: UiKitLabels): PayPageStrings {
+  return {
+    opening: labels.billing.payOpening,
+    nothing: labels.billing.payNothing,
+    failed: labels.billing.payFailed,
+    closed: labels.billing.payBack,
+    back: labels.common.back,
+    terms: labels.legal.links.terms,
+    privacy: labels.legal.links.privacy,
+    legal: labels.legal.navLabel,
+  };
+}
+
+/* ── pay-config.json ───────────────────────────────────────────────────────── */
+
+/** The configuration file beside the page, written at each app's web build. @internal */
+export const PAY_CONFIG_FILE = "pay-config.json";
+
+/**
+ * `pay-config.json`: what the page needs that differs per app and deployment. Read by
+ * the page from its own origin — never from the query, where Paddle's own links (it
+ * puts only `_ptxn` there) would lack it and a return URL would be an open redirect on
+ * an approved payment domain. @internal
+ */
+export interface PayPageConfig {
+  /** Paddle's client-side token (`test_…` for the sandbox, `live_…` for live); null
+   *  while billing is off, and the page says `payNothing`. */
+  token: string | null;
+  environment: PaddleEnvironment | null;
+  /** The app's subscription page. Paddle.js's `successUrl` is
+   *  `checkoutReturnUrl(returnUrl)`; "Back" goes here. */
+  returnUrl: string;
+  appName: string;
+  termsUrl: string;
+  privacyUrl: string;
+}
+
+/** Paddle's client-side token prefixes, per environment. */
+const TOKEN_PREFIX: Readonly<Record<PaddleEnvironment, string>> = { sandbox: "test_", live: "live_" };
+
+/** `https://`, or `http://` on this machine only (`localhost`, `127.0.0.1`, `[::1]`). */
+function isPageUrl(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:") return true;
+  return url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+}
+
+/**
+ * What is wrong with a `pay-config.json`, one line each — `[]` when nothing is. The
+ * build script refuses to write a file with any (so a wrong pairing fails the build,
+ * not a buyer), and the page says `payFailed` for one it reads:
+ *
+ * - a token whose prefix disagrees with the environment (`test_` ↔ sandbox, `live_` ↔
+ *   live), or a token without an environment;
+ * - a return, terms or privacy URL that isn't `https://` (`http://` for localhost only);
+ * - no app name. @internal
+ */
+export function payPageConfigProblems(config: unknown): string[] {
+  if (typeof config !== "object" || config === null) return ["the configuration is not an object"];
+  const c = config as Record<string, unknown>;
+  const problems: string[] = [];
+  const { token, environment } = c;
+  if (environment !== null && environment !== undefined && environment !== "sandbox" && environment !== "live") {
+    problems.push(`environment must be "sandbox" or "live", not ${JSON.stringify(environment)}`);
+  }
+  if (token !== null && token !== undefined) {
+    if (typeof token !== "string" || token === "") {
+      problems.push("token must be Paddle's client-side token, or null while billing is off");
+    } else if (environment !== "sandbox" && environment !== "live") {
+      problems.push("a token needs its environment: sandbox or live");
+    } else if (!token.startsWith(TOKEN_PREFIX[environment]) || token.length === TOKEN_PREFIX[environment].length) {
+      const other = environment === "sandbox" ? "live" : "sandbox";
+      problems.push(
+        token.startsWith(TOKEN_PREFIX[other])
+          ? `the token is a ${other} token (${TOKEN_PREFIX[other]}…), but the environment is ${environment}`
+          : `a ${environment} token starts with ${TOKEN_PREFIX[environment]}`,
+      );
+    }
+  }
+  for (const key of ["returnUrl", "termsUrl", "privacyUrl"] as const) {
+    if (!isPageUrl(c[key])) problems.push(`${key} must be an https:// URL (http:// for localhost only)`);
+  }
+  if (typeof c.appName !== "string" || c.appName.trim() === "") problems.push("appName is missing");
+  return problems;
+}
+
+/** Paddle.js's `successUrl` for a configuration: the way back, `?checkout=done`. @internal */
+export function paySuccessUrl(config: Pick<PayPageConfig, "returnUrl">): string {
+  return checkoutReturnUrl(config.returnUrl);
+}

package/src/billing/plan-limit-toast.tsx

@@ -0,0 +1,91 @@
+import { useCallback } from "react";
+
+import { useKitLocale } from "../i18n/kit-labels";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { documentNavigation } from "../lib/document-navigation";
+import { formatNumber } from "../lib/format";
+import { toast } from "../components/toast";
+import type { ToastAction, ToastId } from "../components/toast";
+import { useBillingLabels } from "./billing-labels";
+import type { BillingLabels } from "./billing-labels";
+import type { PlanLimitRefusal } from "./plan-limit";
+import { planLimitMailto } from "./plan-limit-notice";
+
+export interface PlanLimitToastOptions {
+  /** `upgrade`: plans are bought — "Choose a plan". `contact`: the operator grants them
+   *  by hand — "Ask for more", a mail to support. */
+  mode: "upgrade" | "contact";
+  /** `upgrade`: the app's navigation to its subscription page (the kit has no router).
+   *  Left out, the toast has no action. */
+  onChoosePlan?: () => void;
+  /** `contact`: support@ the app's domain, opened as `planLimitMailto(email,
+   *  contactSubject(name))`. Left out, the toast has no action. */
+  email?: string;
+  /** The app's word per dimension: `{ budgets: "Budgets", scans: "Scans this month" }`.
+   *  A dimension without one is named by its key. */
+  dimensionLabels?: Readonly<Record<string, string>>;
+  /** How a figure is written — kastlan's storage limit is bytes. Default: a number in
+   *  the kit's locale. */
+  formatValue?: (dimension: string, value: number) => string;
+  /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
+  labels?: LabelOverride<BillingLabels>;
+}
+
+/**
+ * `PlanLimitNotice`'s words as a toast (docs/billing-harmonization.md §14.11), for a
+ * refused create with no room for the notice — a row's button, a share target: "Plan
+ * limit reached", what to do, the figure when the refusal has one ("Budgets: 3 of 3"),
+ * and the mode's action.
+ *
+ *     const showLimit = usePlanLimitToast({
+ *       mode: "upgrade",
+ *       onChoosePlan: () => navigate("/settings/subscription"),
+ *       dimensionLabels: { budgets: t("billing.dim_budgets") },
+ *     });
+ *     catch (err) { const hit = isPlanLimit(err); if (hit) showLimit(hit); }
+ *
+ * One toast per dimension: its id is `plan-limit:<dimension>`, so a repeat replaces it
+ * in place instead of stacking a second (keksdose's own hook stacked). Called with no
+ * hit, it says the words without a figure, under `plan-limit`. No `limit` in the
+ * refusal, no figure line; keksdose's legacy `plan_budget_limit` reads as `budgets`
+ * (`isPlanLimit`, §12.16). Returns the toast's id.
+ */
+export function usePlanLimitToast(options: PlanLimitToastOptions): (hit?: PlanLimitRefusal) => ToastId {
+  const { mode, onChoosePlan, email, dimensionLabels, formatValue, labels: labelsProp } = options;
+  const labels = useBillingLabels(labelsProp);
+  const locale = useKitLocale();
+  return useCallback(
+    (hit?: PlanLimitRefusal) => {
+      const dimension = hit?.dimension ?? "";
+      const name = dimensionLabels?.[dimension] ?? dimension;
+      const figure = (value: number) =>
+        formatValue ? formatValue(dimension, value) : formatNumber(value, { locale });
+      // A body without `used` was refused for being AT the limit (PlanLimitNotice's rule).
+      const usage =
+        hit?.limit !== undefined
+          ? labels.limitUsageLine(name, figure(hit.used ?? hit.limit), figure(hit.limit))
+          : undefined;
+      const action: ToastAction | undefined =
+        mode === "upgrade"
+          ? onChoosePlan && { label: labels.choosePlan, onClick: () => onChoosePlan() }
+          : email
+            ? {
+                label: labels.askForMore,
+                // A mailto: hands the address to the reader's mail client; the page stays.
+                onClick: () => documentNavigation.replace(planLimitMailto(email, labels.contactSubject(name))),
+              }
+            : undefined;
+      return toast.warning(labels.limitReached, {
+        id: dimension ? `plan-limit:${dimension}` : "plan-limit",
+        description: (
+          <span data-plan-limit-mode={mode} data-dimension={dimension || undefined}>
+            <span className="block">{mode === "upgrade" ? labels.limitUpgrade : labels.limitContact}</span>
+            {usage !== undefined && <span className="block tabular-nums">{usage}</span>}
+          </span>
+        ),
+        action,
+      });
+    },
+    [mode, onChoosePlan, email, dimensionLabels, formatValue, labels, locale],
+  );
+}

package/src/billing/subscription-actions.tsx

@@ -5,18 +5,36 @@ import { cn } from "../lib/cn";
 import { Button } from "../components/ui";
 import { useBillingLabels } from "./billing-labels";
 import type { BillingLabels } from "./billing-labels";
+import type { PortalTarget } from "./billing-overview";
 
 export interface SubscriptionActionsProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
   /** "Payment and invoices", as a link — or {@link onManage}. Without either, none. */
   manageHref?: string;
-  /** "Payment and invoices", as the app's call: `POST /billing/portal`, then off to its
-   *  `url` (§4). The kit sends no request. */
+  /** "Payment and invoices", as the app's call: `POST /billing/portal` with
+   *  `{target: "overview"}`, then off to its `url` (§4, §14.5). The kit sends no
+   *  request. */
   onManage?: () => void;
   /** "Cancel subscription", as a link — or {@link onCancel}. Without either, none. */
   cancelHref?: string;
-  /** "Cancel subscription", as the app's call — usually the portal again, where the
-   *  provider's cancel and withdrawal functions are (§12.26). */
+  /** "Cancel subscription", as the app's call: the portal again, with `{target:
+   *  "cancel"}` — its cancel link, where the provider's cancel and withdrawal functions
+   *  are (§12.26, §14.5). Not the overview. */
   onCancel?: () => void;
+  /**
+   * Both, as one call that says where to ({@link PortalTarget}, the body of
+   * `POST /billing/portal`): `"overview"` for "Payment and invoices",
+   * `"cancel"` for "Cancel subscription" — so the target can't be mixed up (kastlan's
+   * cancel opened the overview). {@link onManage} and {@link onCancel} win over it.
+   */
+  onPortal?: (target: PortalTarget) => void;
+  /**
+   * The overview's `at_provider` (§14.5): whether the payer has reached the provider.
+   * `false`: no customer there yet, so nothing to open — a caption (`notAtProvider`)
+   * stands in place of both actions. `true`: both show, WHATEVER the status or source —
+   * a payer who bought under a grant keeps the way to the invoices and to "Cancel"
+   * (§12.26). Default true (0.32's behaviour).
+   */
+  atProvider?: boolean;
   /** Which of the two is under way: its spinner, no second press. */
   pending?: "manage" | "cancel" | null;
   /** Prop > `<UiKitProvider labels={{ billing }}>` > English. */
@@ -34,25 +52,40 @@ export interface SubscriptionActionsProps extends Omit<ComponentPropsWithoutRef<
  *
  * Neither takes the write lock: a read-only payer must be able to pay, leave or cancel
  * (§3.3).
+ *
+ * Before the payer has reached the provider (`atProvider={false}`, a trial without a
+ * card, a beta) there is no portal to open: the part says so in a caption instead of
+ * offering two buttons that could only end in `409 billing_not_at_provider`.
  */
 export function SubscriptionActions({
   manageHref,
   onManage,
   cancelHref,
   onCancel,
+  onPortal,
+  atProvider = true,
   pending,
   labels: labelsProp,
   className,
   ...rest
 }: SubscriptionActionsProps) {
   const labels = useBillingLabels(labelsProp);
+  if (!atProvider) {
+    return (
+      <div {...rest} data-at-provider="false" className={cn("text-sm text-[var(--text-muted)]", className)}>
+        <p>{labels.notAtProvider}</p>
+      </div>
+    );
+  }
+  const manageCall = onManage ?? (onPortal ? () => onPortal("overview") : undefined);
+  const cancelCall = onCancel ?? (onPortal ? () => onPortal("cancel") : undefined);
   const manage =
     manageHref !== undefined ? (
       <Button href={manageHref} variant="secondary">
         {labels.manage}
       </Button>
-    ) : onManage !== undefined ? (
-      <Button type="button" variant="secondary" onClick={onManage} pending={pending === "manage"}>
+    ) : manageCall !== undefined ? (
+      <Button type="button" variant="secondary" onClick={manageCall} pending={pending === "manage"}>
         {labels.manage}
       </Button>
     ) : null;
@@ -61,8 +94,8 @@ export function SubscriptionActions({
       <Button href={cancelHref} variant="link" tone="danger">
         {labels.cancel}
       </Button>
-    ) : onCancel !== undefined ? (
-      <Button type="button" variant="link" tone="danger" onClick={onCancel} pending={pending === "cancel"}>
+    ) : cancelCall !== undefined ? (
+      <Button type="button" variant="link" tone="danger" onClick={cancelCall} pending={pending === "cancel"}>
         {labels.cancel}
       </Button>
     ) : null;

package/src/components/account-settings.tsx

@@ -22,6 +22,7 @@ import type {
   ProfileSettingLabels,
   TwoFactorSettingLabels,
 } from "./account-settings-labels";
+import { COMMIT_EXCEPT_BILLING } from "./write-lock";
 
 // The label types moved beside the namespace's defaults (0.12.0); re-exported here so
 // every existing `import type { ProfileSettingLabels }` keeps resolving.
@@ -115,7 +116,10 @@ export type ProfileSettingProps = ProfileSettingDisplayNameProps | ProfileSettin
  *
  * The two-field form owns its drafts, starting from the saved names and following them
  * when they change; Save waits for a change, holds — saying why — while a name is
- * blank, and is a `commit` (a {@link WriteLockProvider} locks it, keksdose's demo).
+ * blank, and is a `commit` (a {@link WriteLockProvider} locks it, keksdose's demo) —
+ * every lock but a lapsed plan's (`COMMIT_EXCEPT_BILLING`, 0.33): a profile is the
+ * account's own settings, which billing never locks (docs/billing-harmonization.md §3.3,
+ * §12.36).
  */
 export function ProfileSetting(props: ProfileSettingProps) {
   const { name, email, role, memberSince, labels: labelsProp, id } = props;
@@ -271,7 +275,7 @@ function PersonNameFields({
       </div>
       <Button
         type="submit"
-        commit
+        commit={COMMIT_EXCEPT_BILLING}
         pending={busy}
         // A blank name is a reason the person can act on; an unchanged one is not —
         // there is nothing to save, and the button is simply off.

package/src/components/autocomplete.tsx

@@ -33,6 +33,7 @@ import {
   useLockReason,
 } from "./field-parts";
 import { mergeDescribedBy } from "./choice-parts";
+import type { CommitScope } from "./write-lock";
 
 /**
  * `value`/`onChange` are the TEXT's, and `onSelect` is "a suggestion was taken" —
@@ -161,7 +162,7 @@ export interface AutocompleteProps<V extends string | number = string>
    * whose result is only draft state — the form's Save writes it — leaves this off and
    * stays live under the lock. No provider, or an unlocked one: no effect.
    */
-  commit?: boolean;
+  commit?: CommitScope;
 }
 
 function AutocompleteInner<V extends string | number = string>(
@@ -329,8 +330,10 @@ function AutocompleteInner<V extends string | number = string>(
                   // label's first letters, which float at the same start inset. On the
                   // value line it is beside what it describes, and the label keeps the
                   // start edge every other label in the form's column shares.
+                  // At Large the label stands above the field and the strip is gone
+                  // (0.33, §10.17): the value's line is under FIELD_BASE's `py-2`.
                   hasLabel
-                    ? "top-[calc(1rem+1px)] h-5 items-center"
+                    ? "top-[calc(1rem+1px)] h-5 items-center large:top-[calc(0.5rem+1px)]"
                     : "top-1/2 -translate-y-1/2",
                 )}
               >

package/src/components/button-group.tsx

@@ -178,7 +178,10 @@ export interface ButtonGroupLinkProps extends Omit<ComponentPropsWithoutRef<"a">
   ref?: Ref<HTMLAnchorElement>;
 }
 
-const LINK_CURRENT = "bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]";
+// The brand AS TEXT is `--brand-muted` (0.33, docs/colour-roles-harmonization.md §5.5):
+// `--brand` itself is solved to 3:1 and read 2.97:1 on its own wash in the derived dark
+// presets; the muted form holds 4.5:1 on it in every preset.
+const LINK_CURRENT = "bg-[var(--brand-bg)] text-brand-muted hover:bg-[var(--brand-bg-hover)]";
 
 /**
  * A {@link ButtonGroup} member that navigates: a link drawn as a {@link Button}, so it

package/src/components/calculator.tsx

@@ -73,13 +73,17 @@ const KEYS: Key[] = [
 const KEY_BASE =
   "flex h-9 items-center justify-center rounded-md text-sm font-medium transition-colors focus:outline-none focus:ring-[length:var(--focus-ring-width)] focus:ring-[var(--border-strong)]";
 // Two key families, two fills: digits sit on the inset surface and darken on
-// hover, operators sit a step down on `--border` and lift toward that surface —
+// hover, operators sit a step down on `--bg-active` and lift toward that surface —
 // the same split `NumberPadSheet` uses for this keypad on a phone. The tokens
 // flip with the theme, so neither needs a `dark:` twin.
-const KEY_DIGIT =
-  "bg-[var(--bg-surface-2)] text-[var(--text-primary)] hover:bg-[var(--bg-hover)]";
-const KEY_ACCENT =
-  "bg-[var(--border)] text-[var(--text-secondary)] hover:bg-[var(--bg-surface-2)]";
+//
+// 0.33 (docs/colour-roles-harmonization.md §12.2, §12.9): the digits hover onto
+// `--bg-active`, 1.11–1.18:1 from the key — `--bg-hover` is mixed against the card and
+// sat only 1.04:1 from the well, which in light is the page. The operators rest on
+// `--bg-active` rather than `--border`: More contrast steps the border until it is a
+// 3:1 LINE, and as a fill under the label that left 2.2–2.7:1.
+const KEY_DIGIT = "bg-surface-2 text-primary hover:bg-active";
+const KEY_ACCENT = "bg-active text-secondary hover:bg-surface-2";
 
 function seed(initial: string): string {
   const t = initial.trim();
@@ -186,7 +190,7 @@ function CalculatorPanel({
           // "C" is a convention, not a name: read aloud it is the letter.
           aria-label={labels.clear}
           onClick={clearAll}
-          className={cn(KEY_BASE, "col-span-2 bg-[var(--border)] text-[var(--text-secondary)] hover:bg-[var(--bg-surface-2)]")}
+          className={cn(KEY_BASE, "col-span-2", KEY_ACCENT)}
         >
           C
         </button>

package/src/components/checkbox-group.tsx

@@ -3,7 +3,7 @@ import type { ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { Checkbox } from "./checkbox";
 import { hasMessage, mergeDescribedBy } from "./choice-parts";
-import { useCommitReason } from "./write-lock";
+import { useCommitReason, type CommitScope } from "./write-lock";
 import { RequiredStarOnLegend } from "./field-parts";
 
 /** One box of a {@link CheckboxGroup}. */
@@ -76,7 +76,7 @@ export interface CheckboxGroupProps<T extends string = string> {
    * per-locale grants). Under a locked {@link WriteLockProvider} every box is locked
    * the focusable way with the lock's reason. See {@link Checkbox}'s `commit`.
    */
-  commit?: boolean;
+  commit?: CommitScope;
   /** Why no box can be changed — every box gets it, and it wins over `disabled` (the
    *  boxes stay focusable to say it). See {@link Checkbox}'s `disabledReason`. */
   disabledReason?: ReactNode;

package/src/components/checkbox.tsx

@@ -12,6 +12,7 @@ import {
   type DisabledReasonDisplay,
 } from "./field-parts";
 import { FOCUS_RING } from "./focus-ring";
+import type { CommitScope } from "./write-lock";
 
 /**
  * A checkbox that is still `<input type="checkbox">`.
@@ -134,7 +135,7 @@ export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement
    * locked the `disabledReason` way with the lock's reason (which wins over its own).
    * No provider, or an unlocked one: no effect. Button's `commit`, for keksdose K3.
    */
-  commit?: boolean;
+  commit?: CommitScope;
 }
 
 /**