@eifi1/ui-kit 0.31.1 → 0.32.0

package/src/theme/contrast-tokens.ts

@@ -0,0 +1,112 @@
+import { contrast, oklchToRgb, parseHex, rgbToOklch, toHex } from "./color";
+import type { TokenSet } from "./palette-presets";
+
+/**
+ * The "More contrast" step on a token set (docs/text-size-harmonization.md §5, §10.5).
+ * INTERNAL — `applyTokenSet` and the contrast layer share it; it is not re-exported.
+ *
+ * The step happens HERE, in JS, because the tokens it changes are written inline on
+ * `<html>` by `applyTokenSet`: an inline value beats any `[data-contrast=more]` rule and
+ * any `@media (prefers-contrast: more)` block, so a stylesheet cannot do it (§10.5, the
+ * keksdose review). `--text-placeholder` is a CSS-derived token, and it is written inline
+ * here too rather than redefined per attribute in tokens.css.
+ *
+ * What moves (§5):
+ * - `--text-muted` becomes the set's `--text-secondary`;
+ * - `--text-secondary` moves halfway to `--text-primary`;
+ * - `--text-placeholder` becomes the set's `--text-muted` (4.6–5.5:1 on every shipped
+ *   preset, where the CSS formula gives 2.4–2.8:1) — the order primary > secondary >
+ *   muted > placeholder survives the step;
+ * - `--border` moves toward `--text-primary` until it clears 3:1 against the worst of the
+ *   three surfaces (WCAG 1.4.11, a field's boundary), and never less far than
+ *   `--border-strong`'s 45 % — so every border is at least as strong as a "strong" one was.
+ *   `--border-strong` stays derived in tokens.css and grows with it.
+ */
+
+/** The custom properties a contrast step writes. */
+export const CONTRAST_STEPPED_VARS = ["--text-secondary", "--text-muted", "--text-placeholder", "--border"] as const;
+
+export interface ContrastStep {
+  textSecondary: string;
+  textMuted: string;
+  textPlaceholder: string;
+  border: string;
+}
+
+interface Lab {
+  l: number;
+  a: number;
+  b: number;
+}
+
+function toLab(hex: string): Lab | null {
+  const rgb = parseHex(hex);
+  if (!rgb) return null;
+  const { l, c, h } = rgbToOklch(rgb);
+  const rad = (h * Math.PI) / 180;
+  return { l, a: c * Math.cos(rad), b: c * Math.sin(rad) };
+}
+
+/** `color-mix(in oklab, a p, b)` as a hex — the same formula tokens.css's derived roles
+ *  use, so a stepped value sits where the stylesheet would have put it. A colour that is
+ *  not hex (a consumer's own token set) comes back unmixed. */
+function mix(a: string, b: string, p: number): string {
+  const A = toLab(a);
+  const B = toLab(b);
+  if (!A || !B) return a;
+  const l = A.l * p + B.l * (1 - p);
+  const x = A.a * p + B.a * (1 - p);
+  const y = A.b * p + B.b * (1 - p);
+  const c = Math.hypot(x, y);
+  const h = c < 1e-6 ? 0 : ((Math.atan2(y, x) * 180) / Math.PI + 360) % 360;
+  return toHex(oklchToRgb({ l, c, h }));
+}
+
+/** WCAG 1.4.11 for a component's boundary. */
+const BORDER_TARGET = 3;
+/** `--border-strong` in tokens.css: 55 % border, 45 % text. */
+const BORDER_STRONG_SHARE = 0.45;
+
+function worstContrast(color: string, t: TokenSet): number {
+  return Math.min(contrast(color, t.bgPage), contrast(color, t.bgSurface), contrast(color, t.bgSurface2));
+}
+
+function steppedBorder(t: TokenSet): string {
+  // The share of `--text-primary` in the border: at least --border-strong's, more until
+  // 3:1. Monotonic in the share (the mix walks from the border to the text, away from
+  // every surface), so a bisection finds the least that clears it.
+  let lo = BORDER_STRONG_SHARE;
+  if (worstContrast(mix(t.border, t.textPrimary, 1 - lo), t) >= BORDER_TARGET) return mix(t.border, t.textPrimary, 1 - lo);
+  let hi = 1;
+  for (let i = 0; i < 16; i++) {
+    const mid = (lo + hi) / 2;
+    if (worstContrast(mix(t.border, t.textPrimary, 1 - mid), t) >= BORDER_TARGET) hi = mid;
+    else lo = mid;
+  }
+  return mix(t.border, t.textPrimary, 1 - hi);
+}
+
+/** The four stepped values for `t`. Pure. */
+export function contrastStep(t: TokenSet): ContrastStep {
+  return {
+    textSecondary: mix(t.textSecondary, t.textPrimary, 0.5),
+    textMuted: t.textSecondary,
+    textPlaceholder: t.textMuted,
+    border: steppedBorder(t),
+  };
+}
+
+/* ── The token set last written to an element ───────────────────────────── */
+
+const lastWritten = new WeakMap<HTMLElement, TokenSet>();
+
+/** Remember the set `applyTokenSet` wrote, so a contrast change can re-apply it. */
+export function rememberTokenSet(el: HTMLElement, t: TokenSet): void {
+  lastWritten.set(el, t);
+}
+
+/** The set `applyTokenSet` last wrote to `el`, or undefined when nothing did — an app
+ *  without the palette layer, whose base tokens come from tokens.css. */
+export function rememberedTokenSet(el: HTMLElement): TokenSet | undefined {
+  return lastWritten.get(el);
+}

package/src/theme/contrast.ts

@@ -0,0 +1,224 @@
+import { useEffect } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { logger } from "../lib/logger";
+import { readStored } from "../lib/safe-storage";
+import { useMediaQuery } from "../hooks/use-media-query";
+import { CONTRAST_STEPPED_VARS, contrastStep, rememberedTokenSet } from "./contrast-tokens";
+import { applyTokenSet, DEFAULT_PRESET } from "./palette-presets";
+import type { PersistedAppearanceOptions } from "./text-size";
+
+/**
+ * "More contrast" (docs/text-size-harmonization.md §2.4, §5, §10.5, §10.6): a switch
+ * beside the text size, on by choice or — on "System" — when the device asks for more
+ * contrast (`prefers-contrast: more`). Any text size.
+ *
+ * In force it is `<html data-contrast="more">` (else `"standard"`), which does two things:
+ * - the inline colour tokens are re-written one step stronger (`applyTokenSet`'s
+ *   contrast flag — see contrast-tokens.ts for what moves and why it is JS);
+ * - tokens.css raises `--focus-ring-width` from 2 to 3 px and turns on the `contrast:`
+ *   variant for anything else a component wants to change.
+ *
+ * The names below are frozen like the text size's: server-kit's `CONTRAST_MODES`, the
+ * stored format, the attribute.
+ */
+
+/** The stored choices (§10.6): server-kit's `CONTRAST_MODES`. "system" IS a stored value
+ *  — the PATCH rule refuses an explicit null, so null means only "never chosen". */
+export const CONTRAST_MODES = ["system", "standard", "more"] as const;
+
+export type ContrastMode = (typeof CONTRAST_MODES)[number];
+
+/** What is in force on `<html data-contrast>`: a mode with "system" resolved. */
+export type ContrastLevel = "standard" | "more";
+
+const CONTRAST_ATTRIBUTE = "data-contrast";
+const PREFERS_MORE_QUERY = "(prefers-contrast: more)";
+
+export function isContrastMode(value: unknown): value is ContrastMode {
+  return value === "system" || value === "standard" || value === "more";
+}
+
+/** The mode in force: **this device's own choice → the account's → "system"** (§2.6).
+ *  The one order the pre-paint call, the apply hook and `useAccountAppearance` share. */
+export function resolveContrastMode(device: unknown, account?: unknown): ContrastMode {
+  if (isContrastMode(device)) return device;
+  if (isContrastMode(account)) return account;
+  return "system";
+}
+
+/** Whether the device asks for more contrast now. False without `matchMedia`. */
+export function prefersMoreContrast(): boolean {
+  try {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function"
+      ? window.matchMedia(PREFERS_MORE_QUERY).matches
+      : false;
+  } catch {
+    return false;
+  }
+}
+
+/** A mode to the level it puts on `<html>`; "system" asks the device (or takes
+ *  `prefersMore`, when the caller already knows). */
+export function contrastLevel(mode: ContrastMode, prefersMore: boolean = prefersMoreContrast()): ContrastLevel {
+  return mode === "more" || (mode === "system" && prefersMore) ? "more" : "standard";
+}
+
+/** The level `<html>` carries now; "standard" without one. */
+export function readContrastLevel(): ContrastLevel {
+  if (typeof document === "undefined") return "standard";
+  return document.documentElement.getAttribute(CONTRAST_ATTRIBUTE) === "more" ? "more" : "standard";
+}
+
+/**
+ * Re-write the contrast-dependent tokens on `el` for its current `data-contrast`.
+ *
+ * With a palette layer (`applyTokenSet` has written a set here), that set is applied
+ * again and steps itself. Without one — an app whose base tokens come from tokens.css,
+ * like Kurvenschmiede's — the four stepped tokens are written over the stylesheet for
+ * the default preset in the current light/dark, or removed again.
+ */
+function reapplyContrastTokens(el: HTMLElement): void {
+  const written = rememberedTokenSet(el);
+  if (written) {
+    applyTokenSet(el, written);
+    return;
+  }
+  for (const name of CONTRAST_STEPPED_VARS) el.style.removeProperty(name);
+  if (el.getAttribute(CONTRAST_ATTRIBUTE) !== "more") return;
+  const step = contrastStep(DEFAULT_PRESET[el.classList.contains("dark") ? "dark" : "light"]);
+  el.style.setProperty("--text-secondary", step.textSecondary);
+  el.style.setProperty("--text-muted", step.textMuted);
+  el.style.setProperty("--text-placeholder", step.textPlaceholder);
+  el.style.setProperty("--border", step.border);
+}
+
+/** Put `level` on `<html>` and re-write the colour tokens for it. */
+export function applyContrast(level: ContrastLevel): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  root.setAttribute(CONTRAST_ATTRIBUTE, level);
+  reapplyContrastTokens(root);
+}
+
+/* ── Storage: the frozen format, the pre-paint call ─────────────────────── */
+
+/**
+ * What a contrast store persists under its key — FROZEN, like the text size's:
+ *
+ *     {"state":{"contrast":"more"},"version":1}
+ *
+ * `contrast` is one of {@link CONTRAST_MODES}, or `null` / absent when this device never
+ * chose.
+ */
+export interface PersistedContrast {
+  state?: { contrast?: ContrastMode | null };
+  version?: number;
+}
+
+/** This device's own choice under `storageKey`, or `null` when it never chose. */
+export function readPersistedContrast(storageKey: string): ContrastMode | null {
+  try {
+    const blob = JSON.parse(readStored(storageKey) ?? "null") as PersistedContrast | null;
+    const mode = blob?.state?.contrast;
+    return isContrastMode(mode) ? mode : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pre-paint (§10.3, §10.5): this device's choice under `storageKey` — else the account's
+ * last known value, else "system" — resolved against `prefers-contrast` and applied
+ * BEFORE `createRoot`. Call it next to `applyPersistedPalette`, in either order: the
+ * palette steps itself when `data-contrast` is already set, and this re-applies the
+ * palette's set when it is not. Returns the level applied.
+ */
+export function applyPersistedContrast(storageKey: string, options: PersistedAppearanceOptions = {}): ContrastLevel {
+  let account: unknown;
+  try {
+    account = options.account?.();
+  } catch {
+    account = undefined;
+  }
+  const level = contrastLevel(resolveContrastMode(readPersistedContrast(storageKey), account));
+  applyContrast(level);
+  return level;
+}
+
+/* ── The store ──────────────────────────────────────────────────────────── */
+
+export interface ContrastState {
+  /** This device's own choice (persisted), or `null` when it never chose — then the
+   *  account's value applies, else "system". */
+  contrast: ContrastMode | null;
+  /** Store this device's choice; `null` forgets it. */
+  setContrast: (contrast: ContrastMode | null) => void;
+}
+
+export interface ApplyContrastOptions {
+  /** The account's value (`/auth/me`'s `contrast`): it applies while this device has no
+   *  choice of its own. */
+  account?: string | null;
+}
+
+/**
+ * Build a contrast store bound to a consumer-supplied localStorage key, shaped like
+ * `createThemeStore` and {@link createTextSizeStore} (§6). It holds the DEVICE's choice;
+ * the account's value comes in through `useApplyContrast({ account })`.
+ *
+ * `useApplyContrast` — mount it once near the root, beside `useApplyPalette`:
+ * - puts the level on `<html>` and steps the tokens;
+ * - on "System", follows `prefers-contrast: more` live (§10.5);
+ * - without a palette layer, re-writes the stepped tokens when the light/dark class
+ *   changes, since they differ per theme.
+ *
+ * The persisted format is {@link PersistedContrast}, and frozen.
+ */
+export function createContrastStore(storageKey: string) {
+  const useContrastStore = create<ContrastState>()(
+    logger(
+      persist(
+        (set) => ({
+          contrast: null,
+          setContrast: (contrast) => set({ contrast: isContrastMode(contrast) ? contrast : null }),
+        }),
+        {
+          name: storageKey,
+          version: 1,
+          partialize: (s) => ({ contrast: s.contrast }),
+          merge: (persisted, current) => {
+            const value = (persisted as { contrast?: unknown } | null)?.contrast;
+            return { ...current, contrast: isContrastMode(value) ? value : null };
+          },
+        },
+      ),
+      "contrast",
+    ),
+  );
+
+  function useApplyContrast({ account }: ApplyContrastOptions = {}): ContrastLevel {
+    const device = useContrastStore((s) => s.contrast);
+    // Subscribed whatever the mode (hooks cannot be skipped); only "system" reads it.
+    const prefersMore = useMediaQuery(PREFERS_MORE_QUERY, false);
+    const level = contrastLevel(resolveContrastMode(device, account), prefersMore);
+    useEffect(() => {
+      applyContrast(level);
+    }, [level]);
+    // Without a palette layer the stepped tokens are per theme: follow `.dark`.
+    useEffect(() => {
+      if (typeof MutationObserver === "undefined") return;
+      const root = document.documentElement;
+      const observer = new MutationObserver(() => {
+        if (!rememberedTokenSet(root)) reapplyContrastTokens(root);
+      });
+      observer.observe(root, { attributes: true, attributeFilter: ["class"] });
+      return () => observer.disconnect();
+    }, []);
+    return level;
+  }
+
+  return { useContrastStore, useApplyContrast };
+}
+
+export type ContrastStore = ReturnType<typeof createContrastStore>;

package/src/theme/palette-presets.ts

@@ -15,6 +15,7 @@
 // (the default preset here mirrors those exactly).
 
 import type { HeatStops } from "./chart-palette";
+import { contrastStep, rememberTokenSet } from "./contrast-tokens";
 
 export interface TokenSet {
   // Backgrounds & chrome
@@ -740,15 +741,34 @@ export function presetById(id: string): PalettePreset {
  * have been silent and only a dead function would have noticed. The list is gone;
  * the test beside this asserts instead that every field of a `TokenSet` reaches the
  * element, which is what that list was standing in for.
+ *
+ * **More contrast (0.32, docs/text-size-harmonization.md §5, §10.5).** With `contrast`
+ * the text and border tokens are written one step stronger, and `--text-placeholder` —
+ * otherwise derived in tokens.css — is written inline too; without it that inline
+ * placeholder is removed again, so the stylesheet's formula applies. The step is made
+ * HERE because these tokens are inline: no `[data-contrast=more]` rule could beat them.
+ *
+ * `contrast` defaults to the element's own `data-contrast="more"`, which the contrast
+ * layer (`applyContrast`, `useApplyContrast`) sets first. That is how the palette and the
+ * contrast cooperate without knowing each other: a palette change re-applies through
+ * here and keeps the contrast, and a contrast change re-applies the set remembered here.
  */
-export function applyTokenSet(el: HTMLElement, t: TokenSet): void {
+export function applyTokenSet(
+  el: HTMLElement,
+  t: TokenSet,
+  contrast: boolean = el.getAttribute("data-contrast") === "more",
+): void {
+  rememberTokenSet(el, t);
+  const step = contrast ? contrastStep(t) : null;
   el.style.setProperty("--bg-page", t.bgPage);
   el.style.setProperty("--bg-surface", t.bgSurface);
   el.style.setProperty("--bg-surface-2", t.bgSurface2);
-  el.style.setProperty("--border", t.border);
+  el.style.setProperty("--border", step?.border ?? t.border);
   el.style.setProperty("--text-primary", t.textPrimary);
-  el.style.setProperty("--text-secondary", t.textSecondary);
-  el.style.setProperty("--text-muted", t.textMuted);
+  el.style.setProperty("--text-secondary", step?.textSecondary ?? t.textSecondary);
+  el.style.setProperty("--text-muted", step?.textMuted ?? t.textMuted);
+  if (step) el.style.setProperty("--text-placeholder", step.textPlaceholder);
+  else el.style.removeProperty("--text-placeholder");
   el.style.setProperty("--brand", t.brand);
   el.style.setProperty("--brand-hover", t.brandHover);
   el.style.setProperty("--brand-contrast", t.brandContrast);

package/src/theme/palette-store.ts

@@ -60,7 +60,12 @@ export function createPaletteStore(
   /** Apply the active preset's tokens to <html> as inline CSS custom properties,
    *  re-applying when the preset or the light/dark theme changes. Tailwind v4
    *  strips a bare root token block from the bundle, so this inline write from
-   *  the TS source of truth is what actually drives the colours. */
+   *  the TS source of truth is what actually drives the colours.
+   *
+   *  0.32: keeps More contrast. `applyTokenSet` reads `<html data-contrast>`, which the
+   *  contrast store sets, and steps the tokens itself; the contrast store re-applies
+   *  the set written here when the contrast changes (docs/text-size-harmonization.md
+   *  §10.5). Neither store needs the other. */
   function useApplyPalette(): void {
     const id = usePalette((s) => s.id);
     const mode = useTheme((s) => s.mode);

package/src/theme/text-size.ts

@@ -0,0 +1,267 @@
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { logger } from "../lib/logger";
+import { readStored } from "../lib/safe-storage";
+
+/**
+ * The text size (docs/text-size-harmonization.md §2.1, §3.1, §10.3, §10.6).
+ *
+ * ONE scale on `<html>`: `data-text-size="normal|large|xlarge"`, and `tokens.css` turns
+ * it into `font-size: 100% / 125% / 150%` — percent, never px, so "Normal" keeps
+ * whatever size the person set in the browser. Tailwind's spacing and type are rem, so
+ * about 90 % of every screen grows with that one declaration; the breakpoints follow too
+ * (tokens.css redefines `sm:` … `3xl:` per size, {@link useBreakpoint} answers the same
+ * in JS).
+ *
+ * The names below are the mechanism's public vocabulary and are FROZEN: an app's
+ * storage, its `/auth/me` column (server-kit's `TEXT_SIZES`) and the inline boot snippet
+ * all spell them this way.
+ */
+
+/** The three steps, in order (§2.1, §10.6): server-kit's `TEXT_SIZES`, value for value. */
+export const TEXT_SIZES = ["normal", "large", "xlarge"] as const;
+
+export type TextSize = (typeof TEXT_SIZES)[number];
+
+/** The root font size each step sets, as a factor of the browser's own (tokens.css). For
+ *  what CSS cannot reach: a canvas or SVG chart's px constants, a windowed list's row
+ *  estimate, a popover width in px (§3.2). */
+export const TEXT_SCALE: Readonly<Record<TextSize, number>> = { normal: 1, large: 1.25, xlarge: 1.5 };
+
+/** The attribute on `<html>` that carries the size. */
+const TEXT_SIZE_ATTRIBUTE = "data-text-size";
+
+export function isTextSize(value: unknown): value is TextSize {
+  return value === "normal" || value === "large" || value === "xlarge";
+}
+
+/**
+ * The size in force: **this device's own choice → the account's → Normal** (§2.2, §2.6).
+ * Each is taken only when it is one of {@link TEXT_SIZES}; anything else (a stale value,
+ * `null` = never chosen) falls through to the next. The one order the pre-paint call, the
+ * apply hook and `useAccountAppearance` all use, so the three can never disagree.
+ */
+export function resolveTextSize(device: unknown, account?: unknown): TextSize {
+  if (isTextSize(device)) return device;
+  if (isTextSize(account)) return account;
+  return "normal";
+}
+
+/* ── <html data-text-size> and the subscribers that read it ─────────────── */
+
+const listeners = new Set<() => void>();
+let observer: MutationObserver | null = null;
+
+function notify(): void {
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  // Also catches writers that are not this module — the inline boot snippet, an app
+  // setting the attribute by hand, a test.
+  if (!observer && typeof MutationObserver !== "undefined" && typeof document !== "undefined") {
+    observer = new MutationObserver(notify);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: [TEXT_SIZE_ATTRIBUTE] });
+  }
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) {
+      observer?.disconnect();
+      observer = null;
+    }
+  };
+}
+
+/** The size `<html>` carries now; Normal without one (or outside a browser). */
+export function readTextSize(): TextSize {
+  if (typeof document === "undefined") return "normal";
+  const value = document.documentElement.getAttribute(TEXT_SIZE_ATTRIBUTE);
+  return isTextSize(value) ? value : "normal";
+}
+
+/** Put `size` on `<html>`. Every {@link useTextSize} re-renders with it. */
+export function applyTextSize(size: TextSize): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  if (root.getAttribute(TEXT_SIZE_ATTRIBUTE) === size) return;
+  root.setAttribute(TEXT_SIZE_ATTRIBUTE, size);
+  notify();
+}
+
+export interface TextSizeInfo {
+  size: TextSize;
+  /** {@link TEXT_SCALE} for `size`: 1, 1.25 or 1.5. */
+  scale: number;
+}
+
+/**
+ * The size in force on this page, and its scale (§3.1) — read from `<html>`, so it needs
+ * no store and works in every kit component: whoever applied the size (the app's store,
+ * the pre-paint call, the inline snippet), this follows it.
+ *
+ * Only for what CSS cannot do. A class that should differ at Large is a `large:`
+ * variant; a layout switch is a breakpoint, which already scales.
+ */
+export function useTextSize(): TextSizeInfo {
+  const size = useSyncExternalStore(subscribe, readTextSize, () => "normal" as const);
+  return useMemo(() => ({ size, scale: TEXT_SCALE[size] }), [size]);
+}
+
+/* ── Storage: the frozen format, the pre-paint call ─────────────────────── */
+
+/**
+ * What a text-size store persists under its key — zustand's persist envelope, and FROZEN
+ * (§10.3) because an app's inline `<head>` snippet reads it before any module loads:
+ *
+ *     {"state":{"size":"large"},"version":1}
+ *
+ * `size` is one of {@link TEXT_SIZES}, or `null` / absent when this device never chose.
+ * A future change adds a key; it never renames `state.size` or changes its values.
+ */
+export interface PersistedTextSize {
+  state?: { size?: TextSize | null };
+  version?: number;
+}
+
+/** This device's own choice under `storageKey`, or `null` when it never chose (or the
+ *  storage is blocked, malformed, or holds a value that is not a size). */
+export function readPersistedTextSize(storageKey: string): TextSize | null {
+  try {
+    const blob = JSON.parse(readStored(storageKey) ?? "null") as PersistedTextSize | null;
+    const size = blob?.state?.size;
+    return isTextSize(size) ? size : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface PersistedAppearanceOptions {
+  /**
+   * The account's last known value, for a device without a choice of its own (§10.3):
+   * what the app persisted with its user (keksdose keeps `/auth/me` in localStorage), so
+   * a cold boot paints the account's size instead of Normal and then jumping — offline
+   * too. Called once, guarded: a throw counts as "no account value".
+   */
+  account?: () => string | null | undefined;
+}
+
+function readAccount(account: PersistedAppearanceOptions["account"]): unknown {
+  if (!account) return undefined;
+  try {
+    return account();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Pre-paint (§3.1, §10.3): read this device's choice under `storageKey` — else the
+ * account's last known value — and put it on `<html>` BEFORE `createRoot`, next to
+ * `applyPersistedTheme`, so the first paint already has the right size. Returns the size
+ * applied.
+ *
+ * ```ts
+ * applyPersistedTextSize("keksdose-text-size", {
+ *   account: () => readPersistedUser()?.text_size,
+ * });
+ * ```
+ */
+export function applyPersistedTextSize(storageKey: string, options: PersistedAppearanceOptions = {}): TextSize {
+  const size = resolveTextSize(readPersistedTextSize(storageKey), readAccount(options.account));
+  applyTextSize(size);
+  return size;
+}
+
+/**
+ * The same pre-paint as {@link applyPersistedTextSize}, as an inline `<head>` script for
+ * a boot splash painted from `index.html` before any module runs (§10.3). A function
+ * EXPRESSION: call it with the storage key and, optionally, a function returning the
+ * account's last known value.
+ *
+ * ```html
+ * <script>
+ *   (function(k,a){…})("keksdose-text-size", function () {
+ *     return JSON.parse(localStorage.getItem("keksdose-auth")).state.user.text_size;
+ *   });
+ * </script>
+ * ```
+ *
+ * Paste the constant's value in place of `(function(k,a){…})`. It reads the frozen
+ * {@link PersistedTextSize} format, never throws, and sets only `data-text-size`; the
+ * splash itself sizes in rem so the attribute reaches it (tokens.css, or the splash's own
+ * `html[data-text-size=large]{font-size:125%}` if it paints before the stylesheet).
+ */
+export const TEXT_SIZE_INLINE_SCRIPT =
+  "(function(k,a){function ok(v){return v==='normal'||v==='large'||v==='xlarge'}" +
+  "var v=null;try{var s=JSON.parse(localStorage.getItem(k)||'null');v=s&&s.state&&s.state.size}catch(e){}" +
+  "if(!ok(v)){v=null;try{v=a?a():null}catch(e){}}" +
+  "try{document.documentElement.setAttribute('data-text-size',ok(v)?v:'normal')}catch(e){}})";
+
+/* ── The store ──────────────────────────────────────────────────────────── */
+
+export interface TextSizeState {
+  /** This device's own choice (persisted), or `null` when it never chose — then the
+   *  account's value applies (§2.2). */
+  size: TextSize | null;
+  /** Store this device's choice; `null` forgets it, so the account's applies again. */
+  setSize: (size: TextSize | null) => void;
+}
+
+export interface ApplyTextSizeOptions {
+  /** The account's value (`/auth/me`'s `text_size`): it applies while this device has no
+   *  choice of its own. Leave it out where there is no account. */
+  account?: string | null;
+}
+
+/**
+ * Build a text-size store bound to a consumer-supplied localStorage key, shaped like
+ * `createThemeStore` (§6). It holds the DEVICE's choice only; the account's value comes
+ * in through `useApplyTextSize({ account })` and `useAccountAppearance`, and the size in
+ * force is always {@link resolveTextSize} of the two.
+ *
+ * - `useTextSizeStore` — the zustand hook: `size` (device choice or null) and `setSize`.
+ * - `useApplyTextSize({ account })` — the effect that puts the size in force on `<html>`.
+ *   Mount it once near the root, beside `useApplyTheme`.
+ *
+ * The persisted format is {@link PersistedTextSize}, and frozen.
+ */
+export function createTextSizeStore(storageKey: string) {
+  const useTextSizeStore = create<TextSizeState>()(
+    logger(
+      persist(
+        (set) => ({
+          size: null,
+          setSize: (size) => set({ size: isTextSize(size) ? size : null }),
+        }),
+        {
+          name: storageKey,
+          version: 1,
+          partialize: (s) => ({ size: s.size }),
+          // A hand-edited or future value must not reach <html> as an unknown size.
+          merge: (persisted, current) => ({
+            ...current,
+            size: isTextSize((persisted as { size?: unknown } | null)?.size)
+              ? ((persisted as { size: TextSize }).size)
+              : null,
+          }),
+        },
+      ),
+      "text-size",
+    ),
+  );
+
+  function useApplyTextSize({ account }: ApplyTextSizeOptions = {}): TextSize {
+    const device = useTextSizeStore((s) => s.size);
+    const size = resolveTextSize(device, account);
+    useEffect(() => {
+      applyTextSize(size);
+    }, [size]);
+    return size;
+  }
+
+  return { useTextSizeStore, useApplyTextSize };
+}
+
+export type TextSizeStore = ReturnType<typeof createTextSizeStore>;