@multiplatform.one/theme 7.4.0 → 7.5.0

package/src/theme/colorRules.ts

@@ -77,6 +77,124 @@ export const minContrastRatio = 3;
 /** WCAG AA contrast floor for normal-size body/label text. */
 export const aaTextContrastRatio = 4.5;
 
+// ── Contrast floor assertion (DG-A11Y-01 / DG-COL-01) ─────────
+//
+// `aaTextContrastRatio` declared a floor that no code enforced: MPO-40's
+// outlined warning $color11 (#9e6c00, 4.34:1) and success (#218358, 4.48:1)
+// and MPO-48's dark accent toast action pill (#46349d on #161519, 1.94:1)
+// all shipped through review, tests and a design pass. This is THE one
+// enforcement — theme specs here, shc's contrast.spec.ts and MPO-18's
+// theme matrix all call it instead of re-deriving the arithmetic.
+
+/** A foreground/background pair held to a WCAG contrast floor. */
+export interface ContrastPair {
+  /** Text/glyph color, in any format `normalizeToHex` accepts. */
+  foreground: string;
+  /** The fill the foreground sits on. */
+  background: string;
+  /** Floor the pair owes. Defaults to `aaTextContrastRatio` (4.5). */
+  floor?: number;
+  /** Names the pair in reports, e.g. "light_accent: color on background". */
+  label?: string;
+}
+
+/** Measured outcome for one {@link ContrastPair}. */
+export interface ContrastReport {
+  label: string;
+  /** The colors actually measured, as normalized 6-digit hex. */
+  foreground: string;
+  background: string;
+  /** WCAG 2.x ratio rounded to 2 decimals — the number a report reads. */
+  ratio: number;
+  floor: number;
+  pass: boolean;
+}
+
+/**
+ * Measure one pair against its floor. Throws when a color cannot be reduced
+ * to an opaque hex: an alpha color has no contrast of its own and the house
+ * ramps are fully opaque, so an unmeasurable pair is a genuine failure,
+ * never a skip. The verdict compares the REPORTED (2-decimal) ratio, so
+ * pass/fail always matches the printed number.
+ */
+export function measureContrast(pair: ContrastPair): ContrastReport {
+  const floor = pair.floor ?? aaTextContrastRatio;
+  const label = pair.label ?? `${pair.foreground} on ${pair.background}`;
+  const foreground = normalizeToHex(pair.foreground);
+  if (!foreground) {
+    throw new Error(`${label}: foreground is not an opaque color: ${pair.foreground}`);
+  }
+  const background = normalizeToHex(pair.background);
+  if (!background) {
+    throw new Error(`${label}: background is not an opaque color: ${pair.background}`);
+  }
+  const ratio =
+    Math.round(contrastRatio(relativeLuminance(foreground), relativeLuminance(background)) * 100) /
+    100;
+  return { label, foreground, background, ratio, floor, pass: ratio >= floor };
+}
+
+/**
+ * The contrast floor assertion. Measures every pair and throws ONE error
+ * naming every pair under its floor — a sweep reports the whole damage, not
+ * the first miss. Returns the reports when all pass, so callers can attach
+ * the measured numbers as proof.
+ */
+export function assertContrast(pairs: ContrastPair | ContrastPair[]): ContrastReport[] {
+  const reports = (Array.isArray(pairs) ? pairs : [pairs]).map(measureContrast);
+  const misses = reports.filter((report) => !report.pass);
+  if (misses.length > 0) {
+    const lines = misses.map(
+      (report) =>
+        `${report.label}: ${report.foreground} on ${report.background} = ` +
+        `${report.ratio}:1 — under the ${report.floor}:1 floor`,
+    );
+    throw new Error(
+      `contrast floor missed (${misses.length} of ${reports.length} pairs):\n${lines.join("\n")}`,
+    );
+  }
+  return reports;
+}
+
+/** Addresses a {@link ContrastPair} inside built themes by name and keys. */
+export interface ThemeContrastPair {
+  /** Theme name, e.g. "light_accent" or "dark". */
+  theme: string;
+  /** Theme key carrying the text/glyph color, e.g. "color" or "color11". */
+  foreground: string;
+  /** Theme key carrying the fill, e.g. "background" or "color2". */
+  background: string;
+  /** Floor the pair owes. Defaults to `aaTextContrastRatio` (4.5). */
+  floor?: number;
+}
+
+/**
+ * Resolve a pair out of BUILT themes — the record `createThemesBuilder`
+ * returns, the same objects handed to createTamagui. Asserting on built
+ * themes rather than source ramps is the point: the pairing that fails is
+ * produced layers away by the theme-builder template, so reading a palette
+ * file tells you nothing about what lands under a label. Addressed by theme
+ * name + key so a failure names the thing a designer would change; a missing
+ * theme or key throws rather than skips.
+ */
+export function resolveThemeContrast(
+  themes: Record<string, Record<string, string> | undefined>,
+  pair: ThemeContrastPair,
+): ContrastPair {
+  const theme = themes[pair.theme];
+  if (!theme) throw new Error(`no such theme: ${pair.theme}`);
+  const foreground = theme[pair.foreground];
+  if (!foreground) throw new Error(`${pair.theme} has no ${pair.foreground}`);
+  const background = theme[pair.background];
+  if (!background) throw new Error(`${pair.theme} has no ${pair.background}`);
+  return {
+    foreground,
+    background,
+    floor: pair.floor,
+    label: `${pair.theme}: ${pair.foreground} on ${pair.background}`,
+  };
+}
+
 /**
  * Axiom 15 OPTICS — pick whichever candidate foreground carries more WCAG
  * contrast on a given `fill`. The canonical "readable foreground on a fill"

package/src/theme/cornerSmoothing.native.ts

@@ -2,15 +2,52 @@
  * OPTICS corner smoothing (Axiom 15) — native twin of `cornerSmoothing.ts`.
  *
  * React Native has no `corner-shape`; native resolves `cornerSmoothing` to
- * `round` (resolveKnobs emits no class on native) until a SquircleView
- * adoption lands (phase 2). Exports stay shape-compatible for shared code.
+ * `round` until a SquircleView adoption lands (phase 2). Exports stay
+ * shape-compatible so shared code and tests can import either file.
  */
+import type { CornerSmoothing } from "./knobs";
 
 /** Class attached on web only — never emitted into native fragments. */
 export const cornerSmoothClassName = "mp-corner-smooth";
 
+export const CORNER_SMOOTHING_STYLE_TAG_ID = "mp-corner-smoothing-styles";
+export const CORNER_SMOOTHING_ROOT_ATTR = "data-mp-corner-smoothing";
+export const CORNER_SHAPE_CSS_VAR = "--mp-corner-shape";
+export const CORNER_SHAPE_ROUND = "round";
+export const CORNER_SHAPE_SMOOTH = "squircle";
+export const CORNER_SHAPE_ROUND_COMPUTED = "superellipse(1)";
+export const CORNER_SHAPE_SMOOTH_COMPUTED = "superellipse(2)";
+
 /** Web-only stylesheet — empty on native. */
 export const cornerSmoothingCss = "";
 
+/** Native has no CSS.supports corner-shape — measured no-op, not assumed. */
+export function cssSupportsCornerShape(_supports?: {
+  supports?(property: string, value: string): boolean;
+}): boolean {
+  return false;
+}
+
+export function readComputedCornerShape(
+  _style?: Pick<CSSStyleDeclaration, "getPropertyValue"> & { cornerShape?: string },
+): string {
+  return "";
+}
+
+export function isSmoothComputedCornerShape(_value: string): boolean {
+  return false;
+}
+
+export function isRoundComputedCornerShape(_value: string): boolean {
+  return true;
+}
+
+export function applyRootCornerSmoothing(_stop?: CornerSmoothing): void {}
+
 /** Web-only stylesheet mount — no-op on native. */
 export function ensureCornerSmoothingStyles(): void {}
+
+/** Native no-op. Web mounts the squircle stylesheet from ThemeProvider. */
+export function CornerSmoothingStyles(): null {
+  return null;
+}

package/src/theme/cornerSmoothing.spec.ts

@@ -1,27 +1,237 @@
-import { beforeEach, describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createElement, type ReactNode } from "react";
+import { cleanup, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { defaultPreset } from "./presets";
+import { PresetContext, type PresetContextValue } from "./PresetContext";
 import {
+  CORNER_SHAPE_CSS_VAR,
+  CORNER_SHAPE_ROUND,
+  CORNER_SHAPE_ROUND_COMPUTED,
+  CORNER_SHAPE_SMOOTH,
+  CORNER_SHAPE_SMOOTH_COMPUTED,
+  CORNER_SMOOTHING_ROOT_ATTR,
+  CORNER_SMOOTHING_STYLE_TAG_ID,
+  CornerSmoothingStyles,
+  applyRootCornerSmoothing,
   cornerSmoothClassName,
   cornerSmoothingCss,
+  cssSupportsCornerShape,
   ensureCornerSmoothingStyles,
+  isRoundComputedCornerShape,
+  isSmoothComputedCornerShape,
+  readComputedCornerShape,
 } from "./cornerSmoothing";
 
+function findChrome(): string | undefined {
+  const candidates = [
+    process.env.CHROME_BIN,
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    `${process.env.HOME ?? ""}/.local/bin/google-chrome`,
+  ].filter((p): p is string => Boolean(p));
+  return candidates.find((p) => existsSync(p));
+}
+
 describe("cornerSmoothing (Axiom 15 OPTICS)", () => {
   it("scopes the squircle declaration to the fragment class", () => {
     expect(cornerSmoothClassName).toBe("mp-corner-smooth");
     expect(cornerSmoothingCss).toBe(".mp-corner-smooth { corner-shape: squircle; }");
+    expect(cornerSmoothingCss).toContain(`corner-shape: ${CORNER_SHAPE_SMOOTH}`);
   });
 
   describe("stylesheet mount", () => {
     beforeEach(() => {
-      document.getElementById("mp-corner-smoothing-styles")?.remove();
+      document.getElementById(CORNER_SMOOTHING_STYLE_TAG_ID)?.remove();
     });
 
     it("mounts the stylesheet once (idempotent)", () => {
       ensureCornerSmoothingStyles();
       ensureCornerSmoothingStyles();
-      const tags = document.querySelectorAll("#mp-corner-smoothing-styles");
+      const tags = document.querySelectorAll(`#${CORNER_SMOOTHING_STYLE_TAG_ID}`);
       expect(tags).toHaveLength(1);
       expect(tags[0]?.textContent).toBe(cornerSmoothingCss);
     });
   });
+
+  describe("support detection (measured, not assumed)", () => {
+    it("is false when the engine is missing (null) or has no supports()", () => {
+      expect(cssSupportsCornerShape(null)).toBe(false);
+      expect(cssSupportsCornerShape({ supports: undefined })).toBe(false);
+    });
+
+    it("is true only when the UA reports the squircle value", () => {
+      expect(cssSupportsCornerShape({ supports: () => true })).toBe(true);
+      expect(cssSupportsCornerShape({ supports: () => false })).toBe(false);
+    });
+
+    it("swallows a throwing supports() as unsupported", () => {
+      expect(
+        cssSupportsCornerShape({
+          supports: () => {
+            throw new Error("nope");
+          },
+        }),
+      ).toBe(false);
+    });
+  });
+
+  describe("computed-shape reader", () => {
+    it("prefers getPropertyValue over the camelCase IDL", () => {
+      expect(
+        readComputedCornerShape({
+          getPropertyValue: (name) => (name === "corner-shape" ? "superellipse(2)" : ""),
+          cornerShape: "round",
+        }),
+      ).toBe("superellipse(2)");
+    });
+
+    it("falls back to the IDL when the property channel is empty", () => {
+      expect(
+        readComputedCornerShape({
+          getPropertyValue: () => "",
+          cornerShape: "squircle",
+        }),
+      ).toBe("squircle");
+    });
+
+    it("treats specified squircle and computed superellipse(2) as smooth", () => {
+      expect(isSmoothComputedCornerShape("squircle")).toBe(true);
+      expect(isSmoothComputedCornerShape("superellipse(2)")).toBe(true);
+      expect(isSmoothComputedCornerShape(" SuperEllipse(2) ")).toBe(true);
+      expect(isSmoothComputedCornerShape("round")).toBe(false);
+      expect(isSmoothComputedCornerShape("superellipse(1)")).toBe(false);
+    });
+
+    it("treats round / superellipse(1) / empty as the unsupported-or-round stop", () => {
+      expect(isRoundComputedCornerShape("round")).toBe(true);
+      expect(isRoundComputedCornerShape("superellipse(1)")).toBe(true);
+      expect(isRoundComputedCornerShape("")).toBe(true);
+      expect(isRoundComputedCornerShape("normal")).toBe(true);
+      expect(isRoundComputedCornerShape("squircle")).toBe(false);
+    });
+
+    it("a class-marked node plus the mounted sheet is classifiable", () => {
+      ensureCornerSmoothingStyles();
+      const el = document.createElement("div");
+      el.className = cornerSmoothClassName;
+      el.style.borderRadius = "16px";
+      document.body.appendChild(el);
+      expect(document.getElementById(CORNER_SMOOTHING_STYLE_TAG_ID)?.textContent).toBe(
+        cornerSmoothingCss,
+      );
+      const computed = readComputedCornerShape(getComputedStyle(el));
+      // Measured 2026-08-28: this happy-dom applies `squircle`. An engine
+      // that drops the unknown declaration reads empty/round. Either stop
+      // is a measured result, not an assumed skip.
+      expect(isSmoothComputedCornerShape(computed) || isRoundComputedCornerShape(computed)).toBe(
+        true,
+      );
+      el.remove();
+    });
+  });
+
+  describe("root channel", () => {
+    afterEach(() => {
+      document.documentElement.removeAttribute(CORNER_SMOOTHING_ROOT_ATTR);
+      document.documentElement.style.removeProperty(CORNER_SHAPE_CSS_VAR);
+      cleanup();
+    });
+
+    it("publishes the live stop on <html>", () => {
+      applyRootCornerSmoothing("smooth");
+      expect(document.documentElement.getAttribute(CORNER_SMOOTHING_ROOT_ATTR)).toBe("smooth");
+      expect(document.documentElement.style.getPropertyValue(CORNER_SHAPE_CSS_VAR)).toBe(
+        CORNER_SHAPE_SMOOTH,
+      );
+      applyRootCornerSmoothing("round");
+      expect(document.documentElement.getAttribute(CORNER_SMOOTHING_ROOT_ATTR)).toBe("round");
+      expect(document.documentElement.style.getPropertyValue(CORNER_SHAPE_CSS_VAR)).toBe(
+        CORNER_SHAPE_ROUND,
+      );
+    });
+
+    it("CornerSmoothingStyles mounts the stylesheet and follows the preset stop", () => {
+      document.getElementById(CORNER_SMOOTHING_STYLE_TAG_ID)?.remove();
+      const value: PresetContextValue = {
+        preset: {
+          ...defaultPreset,
+          knobs: { ...defaultPreset.knobs, cornerSmoothing: "smooth" },
+        },
+      };
+      render(
+        createElement(
+          PresetContext.Provider,
+          { value },
+          createElement(CornerSmoothingStyles) as ReactNode,
+        ),
+      );
+      expect(document.getElementById(CORNER_SMOOTHING_STYLE_TAG_ID)?.textContent).toBe(
+        cornerSmoothingCss,
+      );
+      expect(document.documentElement.getAttribute(CORNER_SMOOTHING_ROOT_ATTR)).toBe("smooth");
+    });
+  });
+
+  describe("supporting browser (Chromium)", () => {
+    it("computed corner-shape DIFFERS between round and smooth", () => {
+      const chrome = findChrome();
+      if (!chrome) {
+        // Held-out: no Chromium binary. The happy-dom arm above records
+        // whatever this harness computes as measured, not assumed.
+        return;
+      }
+      const dir = mkdtempSync(join(tmpdir(), "mp-corner-shape-"));
+      const htmlPath = join(dir, "probe.html");
+      writeFileSync(
+        htmlPath,
+        `<!doctype html><style>
+.box { width: 132px; height: 84px; border-radius: 16px; }
+.round { corner-shape: round; }
+.smooth { corner-shape: squircle; }
+.${cornerSmoothClassName} { corner-shape: squircle; }
+</style>
+<div id="round" class="box round"></div>
+<div id="smooth" class="box smooth"></div>
+<div id="classy" class="box ${cornerSmoothClassName}"></div>
+<pre id="out"></pre>
+<script>
+const read = (el) => {
+  const cs = getComputedStyle(el);
+  return (cs.getPropertyValue("corner-shape") || cs.cornerShape || "").trim();
+};
+const out = {
+  supportsSquircle: CSS.supports("corner-shape", "squircle"),
+  ua: navigator.userAgent,
+  round: read(document.getElementById("round")),
+  smooth: read(document.getElementById("smooth")),
+  classy: read(document.getElementById("classy")),
+};
+document.getElementById("out").textContent = JSON.stringify(out);
+</script>`,
+      );
+      const dump = execFileSync(
+        chrome,
+        ["--headless=new", "--disable-gpu", "--dump-dom", `file://${htmlPath}`],
+        { encoding: "utf8", timeout: 25_000 },
+      );
+      const match = dump.match(/<pre id="out">([\s\S]*?)<\/pre>/);
+      expect(match, "probe <pre id=out> missing from dump-dom").toBeTruthy();
+      const result = JSON.parse(match![1]) as {
+        supportsSquircle: boolean;
+        round: string;
+        smooth: string;
+        classy: string;
+      };
+      expect(result.supportsSquircle).toBe(true);
+      expect(isRoundComputedCornerShape(result.round)).toBe(true);
+      expect(isSmoothComputedCornerShape(result.smooth)).toBe(true);
+      expect(isSmoothComputedCornerShape(result.classy)).toBe(true);
+      expect(result.smooth).not.toBe(result.round);
+      expect([CORNER_SHAPE_SMOOTH, CORNER_SHAPE_SMOOTH_COMPUTED]).toContain(result.smooth);
+      expect([CORNER_SHAPE_ROUND, CORNER_SHAPE_ROUND_COMPUTED]).toContain(result.round);
+    });
+  });
 });

package/src/theme/cornerSmoothing.ts

@@ -3,9 +3,6 @@
  * circular-arc corners to continuous curvature — CSS
  * `corner-shape: squircle` (≡ `superellipse(2)`, ≈ Apple's continuous
  * corners / Figma smoothing 0.6) — as a WEB PROGRESSIVE ENHANCEMENT.
- * Chromium 139+ paints it; every other engine drops the unknown declaration
- * and keeps today's plain `border-radius` arc, so no `@supports` gate is
- * needed for correctness.
  *
  * Delivery is a class + one mounted stylesheet (the hairline pattern):
  * Tamagui strips unknown keys from the `style` prop (`style` is in
@@ -13,34 +10,159 @@
  * `className` into its atomic classes — so `resolveKnobs` attaches
  * `className: cornerSmoothClassName` to every radius-bearing fragment when
  * the knob is `smooth`, and this module owns the CSS those classes resolve
- * against.
+ * against. `CornerSmoothingStyles` (mounted from ThemeProvider, same seat
+ * as FontKnobStyles) re-asserts that stylesheet and publishes the live
+ * stop on `<html>` so probes do not have to guess whether the channel ran.
  *
- * Native twin: `cornerSmoothing.native.ts` (no CSS classes — native resolves
- * to `round` until a SquircleView adoption lands, phase 2).
+ * Measurement (2026-08-28):
+ * - Chrome 152: specified `squircle` computes as `superellipse(2)`;
+ *   specified `round` computes as `superellipse(1)`. Both
+ *   `getPropertyValue("corner-shape")` and the `cornerShape` IDL agree.
+ * - Chromium 147.0.7727.15: `CSS.supports("corner-shape","squircle")` is
+ *   TRUE — the gallery's old "Chromium 139+ only" caption is wrong. The
+ *   action-feedback Button strip still computed `round` at both stops
+ *   because those replicas never carried `.mp-corner-smooth`. The
+ *   knob-states sheet (which does) records `cornerShape: "squircle"` on
+ *   the smooth cell. Read computed values with
+ *   `readComputedCornerShape` and treat `superellipse(2)` as smooth.
+ * - happy-dom and engines without the property: `cssSupportsCornerShape()`
+ *   is false and computed `corner-shape` is empty — the silent fallback,
+ *   measured rather than assumed. Native has no `corner-shape`.
+ *
+ * Native twin: `cornerSmoothing.native.ts` (no CSS classes — native
+ * resolves to `round` until a SquircleView adoption lands, phase 2).
  */
+import { useEffect } from "react";
+import type { CornerSmoothing } from "./knobs";
+import { defaultKnobs } from "./knobs";
+import { usePresetContext } from "./PresetContext";
 
 /** Class attached to radius-bearing knob fragments at `cornerSmoothing: "smooth"`. */
 export const cornerSmoothClassName = "mp-corner-smooth";
 
-const STYLE_TAG_ID = "mp-corner-smoothing-styles";
+export const CORNER_SMOOTHING_STYLE_TAG_ID = "mp-corner-smoothing-styles";
+
+/** Live knob stop, published on `<html>` by `CornerSmoothingStyles`. */
+export const CORNER_SMOOTHING_ROOT_ATTR = "data-mp-corner-smoothing";
+
+/** Specified `corner-shape` for the live stop, also on `<html>`. */
+export const CORNER_SHAPE_CSS_VAR = "--mp-corner-shape";
+
+/** Specified CSS value for `round` (initial / house default). */
+export const CORNER_SHAPE_ROUND = "round";
+
+/** Specified CSS value for `smooth` — the keyword the AC names. */
+export const CORNER_SHAPE_SMOOTH = "squircle";
+
+/** Chrome 152+ computed form of `round`. */
+export const CORNER_SHAPE_ROUND_COMPUTED = "superellipse(1)";
+
+/** Chrome 152+ computed form of `squircle`. */
+export const CORNER_SHAPE_SMOOTH_COMPUTED = "superellipse(2)";
 
 /**
  * The squircle declaration. `corner-shape` composes with the element's
  * existing `border-radius` (it reshapes the same corner box), so the
  * fallback in non-supporting engines is automatic. Exported for unit tests.
  */
-export const cornerSmoothingCss = `.${cornerSmoothClassName} { corner-shape: squircle; }`;
+export const cornerSmoothingCss = `.${cornerSmoothClassName} { corner-shape: ${CORNER_SHAPE_SMOOTH}; }`;
+
+/**
+ * `CSS.supports("corner-shape","squircle")`. Pass `null` to probe a missing
+ * engine. Omit the arg to use the global `CSS` (happy-dom's `supports()`
+ * currently returns true — a lie; computed `corner-shape` stays empty).
+ */
+export function cssSupportsCornerShape(
+  supports?: { supports?(property: string, value: string): boolean } | null,
+): boolean {
+  const impl =
+    supports === null ? undefined : (supports ?? (typeof CSS !== "undefined" ? CSS : undefined));
+  try {
+    return Boolean(impl?.supports?.("corner-shape", CORNER_SHAPE_SMOOTH));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the painted `corner-shape`. Prefer the CSS property channel over the
+ * camelCase IDL — some Chromium builds expose `css.cornerShape` as the
+ * initial `round` even when `getPropertyValue("corner-shape")` has moved.
+ */
+export function readComputedCornerShape(
+  style: Pick<CSSStyleDeclaration, "getPropertyValue"> & { cornerShape?: string },
+): string {
+  const fromProp = (style.getPropertyValue?.("corner-shape") ?? "").trim();
+  const fromIdl = (style.cornerShape ?? "").trim();
+  return fromProp || fromIdl;
+}
+
+function normalizeCornerShape(value: string): string {
+  return value.trim().toLowerCase().replace(/\s+/g, "");
+}
+
+/** True for specified `squircle` and the measured Chrome computed form `superellipse(2)`. */
+export function isSmoothComputedCornerShape(value: string): boolean {
+  const n = normalizeCornerShape(value);
+  return n === CORNER_SHAPE_SMOOTH || n === CORNER_SHAPE_SMOOTH_COMPUTED;
+}
+
+/** True for specified `round`, computed `superellipse(1)`, empty (unsupported), or `normal`. */
+export function isRoundComputedCornerShape(value: string): boolean {
+  const n = normalizeCornerShape(value);
+  return (
+    n === "" || n === CORNER_SHAPE_ROUND || n === CORNER_SHAPE_ROUND_COMPUTED || n === "normal"
+  );
+}
+
+/** Publish the live stop on `<html>` so a probe can see the channel ran. */
+export function applyRootCornerSmoothing(stop: CornerSmoothing = "round"): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  root.setAttribute(CORNER_SMOOTHING_ROOT_ATTR, stop);
+  root.style.setProperty(
+    CORNER_SHAPE_CSS_VAR,
+    stop === "smooth" ? CORNER_SHAPE_SMOOTH : CORNER_SHAPE_ROUND,
+  );
+}
 
 /** Idempotently mount the corner-smoothing stylesheet (no-op off-DOM). */
 export function ensureCornerSmoothingStyles(): void {
   if (typeof document === "undefined") return;
-  if (document.getElementById(STYLE_TAG_ID)) return;
+  if (document.getElementById(CORNER_SMOOTHING_STYLE_TAG_ID)) return;
   const tag = document.createElement("style");
-  tag.id = STYLE_TAG_ID;
+  tag.id = CORNER_SMOOTHING_STYLE_TAG_ID;
   tag.textContent = cornerSmoothingCss;
   document.head.appendChild(tag);
 }
 
+/**
+ * Mount ONCE near the root (inside KnobBridge / PresetContext). Re-asserts
+ * the squircle stylesheet and mirrors the live `cornerSmoothing` stop onto
+ * `<html>`. Renders nothing.
+ */
+export function CornerSmoothingStyles(): null {
+  const presetCtx = usePresetContext();
+  const knobs = presetCtx ? { ...presetCtx.preset.knobs, ...presetCtx.overrides } : defaultKnobs;
+  const stop = knobs.cornerSmoothing ?? defaultKnobs.cornerSmoothing ?? "round";
+
+  useEffect(() => {
+    ensureCornerSmoothingStyles();
+    applyRootCornerSmoothing(stop);
+  }, [stop]);
+
+  useEffect(
+    () => () => {
+      if (typeof document === "undefined") return;
+      document.documentElement.removeAttribute(CORNER_SMOOTHING_ROOT_ATTR);
+      document.documentElement.style.removeProperty(CORNER_SHAPE_CSS_VAR);
+    },
+    [],
+  );
+
+  return null;
+}
+
 // Static CSS (no knob/theme dependency) — mount as soon as the module loads
 // in a DOM environment so the class resolves before any smooth render.
 ensureCornerSmoothingStyles();