@multiplatform.one/forms 7.5.0 → 7.6.1

package/src/fields/Input/index.tsx

@@ -1,6 +1,6 @@
 import type { ComponentProps, ReactElement, ReactNode } from "react";
-import { useRef } from "react";
-import { WarningCircleIcon } from "@phosphor-icons/react";
+import { useCallback, useRef } from "react";
+import { ClipboardIcon, WarningCircleIcon } from "@phosphor-icons/react";
 import { MIN_PRESS_TARGET, pressTargetHitSlop } from "@multiplatform.one/theme";
 import type {
   InputKeyboardType,
@@ -9,7 +9,7 @@ import type {
   SizeTokens,
   TamaguiElement,
 } from "tamagui";
-import { Text } from "tamagui";
+import { isWeb, Text } from "tamagui";
 import { Skeleton } from "../../Skeleton";
 import { resolveFieldInputProps } from "../../fieldDefaults";
 import { Field, FieldLayout } from "../../fieldLayout";
@@ -27,6 +27,23 @@ import { LinkCell } from "../../utils/LinkCell";
 
 type InputAreaProps = ComponentProps<typeof InputParts.Area>;
 
+/** F1 / reference §10: standalone Input rings at offset 0, not the inset −2. */
+const INPUT_FIELD_RING_STYLE_ID = "mp-input-field-ring-offset";
+
+export function ensureInputFieldRingOffset(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(INPUT_FIELD_RING_STYLE_ID)) return;
+  const tag = document.createElement("style");
+  tag.id = INPUT_FIELD_RING_STYLE_ID;
+  tag.textContent = `[data-mp-input-field][data-mp-ring="inset"]:has(input:focus),
+[data-mp-input-field][data-mp-ring="inset"]:has(textarea:focus),
+[data-mp-input-field][data-mp-ring="inset"]:has([data-mp-input-area]:focus),
+[data-mp-input-field][data-mp-ring="inset"]:focus-visible {
+  outline-offset: 0px !important;
+}`;
+  document.head.appendChild(tag);
+}
+
 export interface InputProps {
   name?: string;
   form?: AnyFormApi;
@@ -91,6 +108,25 @@ export interface InputProps {
   compact?: boolean;
   /** When true, renders without borders/background (for toolbar integration) */
   chromeless?: boolean;
+  /**
+   * Declared copy end-cap (CopyField / LC-16 second consumer of Input.Button).
+   * Empty omits the cap. Disabled keeps geometry and drops the tab stop.
+   */
+  copy?: boolean;
+  /** Called after a copy attempt. CopyField routes this through notify(). */
+  onCopyResult?: (ok: boolean) => void;
+}
+
+const COPY_LABEL = "Copy to clipboard";
+
+async function writeClipboard(text: string): Promise<boolean> {
+  try {
+    if (typeof navigator === "undefined" || !navigator.clipboard?.writeText) return false;
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 export function Input({
@@ -130,6 +166,8 @@ export function Input({
   skeleton,
   compact,
   chromeless,
+  copy,
+  onCopyResult,
 }: InputProps) {
   const { resolvedForm, knobProps, control, id } = useFormField({
     form: formProp,
@@ -138,6 +176,7 @@ export function Input({
   });
   const inputRef = useRef<TamaguiElement>(null);
   const focusTrigger = useForwardFocus(inputRef);
+  if (isWeb) ensureInputFieldRingOffset();
 
   const resolvedValidators = useResolvedValidators(required, validators, label, name);
 
@@ -161,6 +200,10 @@ export function Input({
     "data-visual-height": String(visualHeight),
     "data-press-floor": belowFloor ? "slop" : "box",
     "data-ring-target": "box",
+    "data-radius-class": "DEFAULT",
+    "data-radius-part": "Input",
+    "data-ring-offset": "0",
+    "data-mp-input-field": "true",
     ...(belowFloor ? { hitSlop: pressTargetHitSlop(visualHeight) } : undefined),
   } as const;
 
@@ -186,7 +229,8 @@ export function Input({
   const layoutBind = {
     id,
     label: visibleLabel,
-    labelProps,
+    // R7 / §6.1: label is weight 400. Consumer labelProps still eject last.
+    labelProps: { fontWeight: "400" as const, ...labelProps },
     helperText,
     required,
     disabled,
@@ -201,6 +245,23 @@ export function Input({
   const areaName =
     visibleLabel || !resolvedAriaLabel ? undefined : { "aria-label": resolvedAriaLabel };
 
+  const handleCopy = useCallback(
+    async (text: string) => {
+      const ok = await writeClipboard(text);
+      onCopyResult?.(ok);
+    },
+    [onCopyResult],
+  );
+
+  // Identifier values (tokens, URLs) ride the mono register (LC-12).
+  const identifierProps = copy
+    ? ({
+        fontFamily: "$mono",
+        letterSpacing: 0,
+        "data-register": "identifier",
+      } as const)
+    : undefined;
+
   // Render skeleton placeholder — FieldLayout keeps label/helper anatomy
   // (LC-20); only the control chrome is the skeleton.
   if (skeleton) {
@@ -226,96 +287,134 @@ export function Input({
     handleChange?: (text: string) => void,
     handleBlur?: (...args: any[]) => void,
     hasError?: boolean,
-  ) => (
-    <InputParts.Box
-      {...boxContract}
-      {...(handleBlur ? { onBlur: handleBlur } : undefined)}
-      // LC-40: the Box owns the disabled chrome treatment (read-only renders
-      // its own branch below and never dims).
-      disabled={disabled}
-      {...chromelessProps}
-    >
-      {leftIcon && (
-        <InputParts.Icon adornment="leading" {...focusTrigger}>
-          {leftIcon}
-        </InputParts.Icon>
-      )}
-      {readOnly ? (
-        linkResolver ? (
-          <LinkCell value={inputValue} linkResolver={linkResolver}>
-            <Text
+  ) => {
+    const copyText = String(inputValue ?? "");
+    // Empty omits the cap so the field stays one tab stop (LC-49).
+    const showCopy = Boolean(copy && copyText);
+    const activateCopy = () => {
+      if (disabled) return;
+      void handleCopy(copyText);
+    };
+    return (
+      <InputParts.Box
+        {...boxContract}
+        {...(handleBlur ? { onBlur: handleBlur } : undefined)}
+        // LC-40: the Box owns the disabled chrome treatment (read-only renders
+        // its own branch below and never dims).
+        disabled={disabled}
+        {...(showCopy ? { paddingInlineEnd: 0 } : undefined)}
+        {...chromelessProps}
+      >
+        {leftIcon && (
+          <InputParts.Icon adornment="leading" {...focusTrigger}>
+            {leftIcon}
+          </InputParts.Icon>
+        )}
+        {readOnly ? (
+          linkResolver ? (
+            <LinkCell value={inputValue} linkResolver={linkResolver}>
+              <Text
+                id={id}
+                aria-readonly="true"
+                aria-required={required || undefined}
+                aria-invalid={hasError || undefined}
+                {...areaName}
+                {...identifierProps}
+                color="$color"
+              >
+                {inputValue ?? ""}
+              </Text>
+            </LinkCell>
+          ) : (
+            <InputParts.Area
+              ref={inputRef}
+              value={inputValue ?? ""}
+              readOnly
               id={id}
               aria-readonly="true"
               aria-required={required || undefined}
               aria-invalid={hasError || undefined}
+              {...identifierProps}
               {...areaName}
-              color="$color"
-            >
-              {inputValue ?? ""}
-            </Text>
-          </LinkCell>
+            />
+          )
         ) : (
           <InputParts.Area
             ref={inputRef}
-            value={inputValue ?? ""}
-            readOnly
+            {...(purposeInputProps.inputMode !== undefined
+              ? { inputMode: purposeInputProps.inputMode }
+              : undefined)}
+            {...(purposeInputProps.keyboardType !== undefined
+              ? { keyboardType: purposeInputProps.keyboardType }
+              : undefined)}
+            {...(purposeInputProps.autoComplete !== undefined
+              ? { autoComplete: purposeInputProps.autoComplete }
+              : undefined)}
+            {...inputProps}
+            {...identifierProps}
+            {...(multiline !== undefined ? { multiline } : undefined)}
+            {...(maxLength !== undefined ? { maxLength } : undefined)}
+            {...(keyboardType !== undefined ? { keyboardType } : undefined)}
+            {...(textContentType !== undefined ? { textContentType } : undefined)}
+            {...(autoComplete !== undefined ? { autoComplete } : undefined)}
+            {...(secureTextEntry !== undefined ? { secureTextEntry } : undefined)}
+            {...(placeholder !== undefined ? { placeholder } : undefined)}
+            disabled={disabled}
             id={id}
-            aria-readonly="true"
+            {...(handleChange ? { value: inputValue ?? "" } : { defaultValue: inputValue })}
             aria-required={required || undefined}
             aria-invalid={hasError || undefined}
             {...areaName}
+            onChange={onChange}
+            onChangeText={(text) => {
+              if (disabled) return;
+              handleChange?.(text);
+              onChangeText?.(text);
+            }}
           />
-        )
-      ) : (
-        <InputParts.Area
-          ref={inputRef}
-          {...(purposeInputProps.inputMode !== undefined
-            ? { inputMode: purposeInputProps.inputMode }
-            : undefined)}
-          {...(purposeInputProps.keyboardType !== undefined
-            ? { keyboardType: purposeInputProps.keyboardType }
-            : undefined)}
-          {...(purposeInputProps.autoComplete !== undefined
-            ? { autoComplete: purposeInputProps.autoComplete }
-            : undefined)}
-          {...inputProps}
-          {...(multiline !== undefined ? { multiline } : undefined)}
-          {...(maxLength !== undefined ? { maxLength } : undefined)}
-          {...(keyboardType !== undefined ? { keyboardType } : undefined)}
-          {...(textContentType !== undefined ? { textContentType } : undefined)}
-          {...(autoComplete !== undefined ? { autoComplete } : undefined)}
-          {...(secureTextEntry !== undefined ? { secureTextEntry } : undefined)}
-          {...(placeholder !== undefined ? { placeholder } : undefined)}
-          disabled={disabled}
-          id={id}
-          {...(handleChange ? { value: inputValue ?? "" } : { defaultValue: inputValue })}
-          aria-required={required || undefined}
-          aria-invalid={hasError || undefined}
-          {...areaName}
-          onChange={onChange}
-          onChangeText={(text) => {
-            if (disabled) return;
-            handleChange?.(text);
-            onChangeText?.(text);
-          }}
-        />
-      )}
-      {rightIcon ? (
-        <InputParts.Icon
-          adornment="trailing"
-          {...(rightIconInteractive ? undefined : focusTrigger)}
-        >
-          {rightIcon}
-        </InputParts.Icon>
-      ) : hasError ? (
-        // M3 / Polaris / Spectrum: in-field error glyph (color is not the
-        // only channel). Omitted when the consumer owns the trailing slot.
-        <InputParts.Icon adornment="trailing" color={formCommonColors.error}>
-          <WarningCircleIcon aria-hidden />
-        </InputParts.Icon>
-      ) : null}
-    </InputParts.Box>
-  );
+        )}
+        {showCopy ? (
+          <InputParts.Button
+            glyphRing
+            size={resolvedSize}
+            type="button"
+            disabled={disabled}
+            tabIndex={disabled ? -1 : 0}
+            aria-label={COPY_LABEL}
+            hitSlop={belowFloor ? pressTargetHitSlop(visualHeight) : undefined}
+            onPress={disabled ? undefined : activateCopy}
+            onKeyDown={
+              ((e: KeyboardEvent) => {
+                if (disabled) return;
+                if (e.key === "Enter" || e.key === " ") {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  activateCopy();
+                }
+              }) as unknown as () => void
+            }
+          >
+            <InputParts.Icon aria-hidden>
+              <ClipboardIcon />
+            </InputParts.Icon>
+          </InputParts.Button>
+        ) : rightIcon ? (
+          <InputParts.Icon
+            adornment="trailing"
+            {...(rightIconInteractive ? undefined : focusTrigger)}
+          >
+            {rightIcon}
+          </InputParts.Icon>
+        ) : hasError ? (
+          // M3 / Polaris / Spectrum: in-field error glyph (color is not the
+          // only channel). Omitted when the consumer owns the trailing slot.
+          <InputParts.Icon adornment="trailing" color={formCommonColors.error}>
+            <WarningCircleIcon aria-hidden />
+          </InputParts.Icon>
+        ) : null}
+      </InputParts.Box>
+    );
+  };
 
   if (!resolvedForm || !name) {
     return (

package/src/fields/MentionInput/index.tsx

@@ -790,11 +790,19 @@ export function MentionInput<
 
   // ── Floating dropdown ──────────────────────────────────────
 
+  // Same clobber the FloatingPanel web branch carried (MPO-38): the complete
+  // `elevatedSurface` fragment ends in a web-only `style: { boxShadow }`, and a
+  // second `style` prop on one element replaces rather than merges — so
+  // spreading it after the positioning style dropped `position: fixed`. Fold
+  // its style in instead of letting the two compete.
+  const { style: elevatedSurfaceStyle, ...elevatedSurfaceProps } = panel.knobProps.elevatedSurface;
+
   const floatingDropdown = panel.mounted ? (
     <YStack
       {...getFloatingProps({
         ref: panel.refs.setFloating,
         style: {
+          ...elevatedSurfaceStyle,
           position: panel.strategy,
           top: panel.y ?? 0,
           left: panel.x ?? 0,
@@ -810,7 +818,7 @@ export function MentionInput<
       })}
       outlineWidth={0}
       pointerEvents={panel.visible ? "auto" : "none"}
-      {...panel.knobProps.elevatedSurface}
+      {...elevatedSurfaceProps}
       borderRadius={panel.dropdownRadius}
       padding={0}
       maxHeight={suggestionsMaxHeight}

package/src/fields/OTPInput/OtpInput.spec.tsx

@@ -2,11 +2,17 @@ import { useForm } from "@tanstack/react-form";
 import { act, fireEvent, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
 import { TestProviders, renderWithProviders } from "@multiplatform.one/test-utils";
-import { Preset, resolveRadiusClass, type BorderRadius } from "@multiplatform.one/theme";
+import { getSize } from "@tamagui/get-token";
+import { getVariableValue, type SizeTokens } from "tamagui";
+import {
+  Preset,
+  resolveRadiusClass,
+  sizeRecipeForToken,
+  type BorderRadius,
+} from "@multiplatform.one/theme";
 import { Form } from "../../Form";
 import { Button } from "../../Button";
-import { getFieldHeight } from "../../shared/utils";
-import { OTPInput, extractOtpCode } from "./index";
+import { OTPInput, extractOtpCode, otpCellHeightPx } from "./index";
 
 describe("OTPInput", () => {
   describe("basic rendering", () => {
@@ -708,7 +714,10 @@ describe("OTPInput", () => {
     }
 
     it("cell measures height/2 at full and 0 at none, riding the token scale between", () => {
-      const heightPx = getFieldHeight("$4");
+      // the cell's own painted edge — `height={cellSize}` is the `$size` token,
+      // so the circle is that token halved. Reading the recipe here instead would
+      // pass on a desktop run and lie on a touch one (recipe $4 = 48 vs token 44).
+      const heightPx = getVariableValue(getSize("$4" as SizeTokens)) as number;
       for (const stop of RADIUS_STOPS) {
         const result = renderWithProviders(
           <Preset overrides={{ borderRadius: stop }}>
@@ -727,5 +736,28 @@ describe("OTPInput", () => {
         expect(paintedRadiusPx(cell as HTMLElement), `cell @ ${stop}`).toBe(expected);
       }
     });
+
+    it("halves the cell's painted token, not the touch-floored recipe height", () => {
+      for (const token of ["$2", "$3", "$4", "$6"] as const) {
+        const painted = getVariableValue(getSize(token as SizeTokens)) as number;
+        expect(otpCellHeightPx(token), `painted height @ ${token}`).toBe(painted);
+        // The recipe's touch column is a different number at EVERY step (44/44/48/68
+        // against 28/36/44/64). Halving it puts the radius past the cell's own edge,
+        // and the engine clamps it back — the browser clamp MPO-56 exists to kill.
+        const touchHeight = sizeRecipeForToken(token, { touch: true }).height;
+        expect(touchHeight, `touch recipe @ ${token}`).not.toBe(painted);
+        expect(
+          resolveRadiusClass("CIRCULAR-AT-FULL", "full", { heightPx: otpCellHeightPx(token) }),
+          `full @ ${token}`,
+        ).toBe(painted / 2);
+      }
+    });
+
+    it("an explicit numeric cell size is its own painted height", () => {
+      expect(otpCellHeightPx(52)).toBe(52);
+      expect(
+        resolveRadiusClass("CIRCULAR-AT-FULL", "full", { heightPx: otpCellHeightPx(52) }),
+      ).toBe(26);
+    });
   });
 });

package/src/fields/OTPInput/index.tsx

@@ -15,7 +15,8 @@ import {
   useState,
 } from "react";
 import { useProps, type SizeTokens, type TamaguiElement } from "tamagui";
-import { Input, Text, XStack, isWeb, useDidFinishSSR } from "tamagui";
+import { Input, Text, XStack, getVariableValue, isWeb, useDidFinishSSR } from "tamagui";
+import { getSize } from "@tamagui/get-token";
 import { Button } from "../../Button";
 import { Field, FieldLayout } from "../../fieldLayout";
 import {
@@ -132,9 +133,23 @@ function digitFontSize(cellSize: string | number | undefined): string {
   return "$6";
 }
 
-function otpCellHeightPx(cellSize: string | number | undefined): number {
+/**
+ * The height the cell PAINTS, which is what CIRCULAR-AT-FULL halves (DG-RAD-02).
+ *
+ * The cell sets `height={cellSize}`, so its painted edge is the `$size` token —
+ * NOT the touch-floored recipe height. On a touch surface those disagree at every
+ * step (`sizeRecipeForToken("$4", { touch: true }).height` is 48 against a 44pt
+ * token, `$2` is 44 against 28), and a resolver fed the recipe height resolves 24
+ * on a 44pt cell: over the edge, so the engine clamps it back to 22. That clamp is
+ * exactly the defect MPO-56 killed, so the radius rides the painted token instead.
+ * Same source as the avatar square face (`avatarTokenPx`, components/Avatar).
+ */
+export function otpCellHeightPx(cellSize: string | number | undefined): number {
   if (typeof cellSize === "number" && Number.isFinite(cellSize) && cellSize > 0) return cellSize;
-  return getFieldHeight((cellSize ?? "$4") as SizeTokens);
+  const token = (cellSize ?? "$4") as SizeTokens;
+  const painted = getVariableValue(getSize(token));
+  if (typeof painted === "number" && Number.isFinite(painted) && painted > 0) return painted;
+  return getFieldHeight(token);
 }
 
 /**

package/src/fields/OTPInput/otpCellHeightTouch.spec.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from "vitest";
+
+/**
+ * The touch arm of DG-RAD-02 for the OTP cell, in its own file because the
+ * surface probe is module-level state: `getFieldHeight` reads `isTouchSurface()`
+ * on every call, and a desktop run cannot tell the painted token from the recipe
+ * height (they are the same number there). Only on a touch surface do the two
+ * ladders separate — 28/36/44/64 painted against 44/44/48/68 recipe — which is
+ * where a resolver fed the wrong one hands the circle back to the engine clamp.
+ */
+vi.mock("@multiplatform.one/theme", async () => {
+  const actual = await vi.importActual<typeof import("@multiplatform.one/theme")>(
+    "@multiplatform.one/theme",
+  );
+  return { ...actual, isTouchSurface: () => true };
+});
+
+import { getSize } from "@tamagui/get-token";
+import { resolveRadiusClass } from "@multiplatform.one/theme";
+import { getVariableValue, type SizeTokens } from "tamagui";
+import { getFieldHeight } from "../../shared/utils";
+import { otpCellHeightPx } from "./index";
+
+const tokens = ["$2", "$3", "$4", "$6"] as const;
+
+describe("OTP cell geometry on a touch surface (DG-RAD-02)", () => {
+  it("the two ladders really do separate, or this file proves nothing", () => {
+    for (const token of tokens) {
+      const painted = getVariableValue(getSize(token as SizeTokens)) as number;
+      expect(getFieldHeight(token as SizeTokens), `recipe height @ ${token}`).not.toBe(painted);
+    }
+  });
+
+  it("the cell resolves against the height it paints, not the recipe height", () => {
+    for (const token of tokens) {
+      const painted = getVariableValue(getSize(token as SizeTokens)) as number;
+      expect(otpCellHeightPx(token), `painted height @ ${token}`).toBe(painted);
+      expect(
+        resolveRadiusClass("CIRCULAR-AT-FULL", "full", { heightPx: otpCellHeightPx(token) }),
+        `full @ ${token}`,
+      ).toBe(painted / 2);
+    }
+  });
+});

package/src/fields/PhoneInput/index.tsx

@@ -347,6 +347,7 @@ export function PhoneInput<
                 <XStack
                   alignItems="center"
                   gap="$1.5"
+                  // size-recipe-escape: zero-reset — the country trigger rides inside Input.Box, which owns the inset (LC-71)
                   paddingHorizontal={0}
                   height="100%"
                   cursor={disabled ? "not-allowed" : "pointer"}

package/src/fields/SearchInput/index.tsx

@@ -7,9 +7,11 @@
  * second focusable and rings its own glyph (chip-dismiss, LC-16).
  *
  * Clear is a View sized from the size-recipe square (same geometry as
- * Input.Button). Origin/main's TButton swallows className, so the
- * chip-dismiss ring classes cannot ride Input.Button until glyphRing
- * lands — do not rewrite Input/ from this lane.
+ * Input.Button). It was hand-rolled because TButton swallows className, so
+ * the chip-dismiss ring classes could not ride Input.Button. `glyphRing`
+ * now exists (InputParts/index.tsx, MPO-52) and renders this exact pair, so
+ * this block can collapse onto `<Input.Button glyphRing>` — in SearchInput's
+ * own lane, not this one.
  */
 import { MagnifyingGlassIcon, XIcon } from "@phosphor-icons/react";
 import {

package/src/shared/utils.spec.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
+import type { BorderRadius } from "@multiplatform.one/theme";
+import { borderRadiusMap, resolveRadiusClass } from "@multiplatform.one/theme";
 import {
   clampRadiusForControl,
   clampRadiusForLargeComponent,
@@ -180,6 +182,50 @@ describe("clampRadiusInStateProps", () => {
         expect(result?.[key]?.borderRadius).toBe(THUMB_H / 2);
       }
     });
+
+    // LC-16 ONE-IMPLEMENTATION. The BINARY row is doctrine-GENERATED
+    // (radiusClassTable.generated.ts, from docs/design-guidelines.md §13).
+    // A state bag must resolve through THAT table, not through a copy of it
+    // living in forms — otherwise a DG-RAD edit reaches the base radius and
+    // silently misses every hover/press/focus bag. Driven off borderRadiusMap
+    // so a stop added to the doctrine is covered without touching this test.
+    const STOPS = Object.keys(borderRadiusMap) as BorderRadius[];
+
+    it.each(STOPS)("agrees with resolveRadiusClass('BINARY') at the %s stop", (stop) => {
+      for (const heightPx of [THUMB_H, TRACK_H, 21]) {
+        const expected = resolveRadiusClass("BINARY", stop, { heightPx });
+        for (const spelling of [stop, borderRadiusMap[stop]]) {
+          const result = clampRadiusInStateProps(
+            { borderRadius: spelling },
+            { radiusClass: "BINARY", heightPx },
+          );
+          expect(result?.borderRadius).toBe(expected);
+        }
+      }
+    });
+
+    it("reads the token/stop mapping off borderRadiusMap rather than a hand-kept copy", () => {
+      for (const stop of STOPS) {
+        const byName = clampRadiusInStateProps(
+          { borderRadius: stop },
+          { radiusClass: "BINARY", heightPx: THUMB_H },
+        );
+        const byToken = clampRadiusInStateProps(
+          { borderRadius: borderRadiusMap[stop] },
+          { radiusClass: "BINARY", heightPx: THUMB_H },
+        );
+        expect(byName?.borderRadius).toBe(byToken?.borderRadius);
+      }
+    });
+
+    it("refuses a BINARY bag with no height instead of guessing one", () => {
+      expect(() =>
+        clampRadiusInStateProps({ borderRadius: "$12" }, { radiusClass: "BINARY" }),
+      ).toThrow(/heightPx/);
+      expect(() =>
+        clampRadiusInStateProps({ borderRadius: "$0" }, { radiusClass: "BINARY", heightPx: 0 }),
+      ).toThrow(/heightPx/);
+    });
   });
 });
 

package/src/shared/utils.ts

@@ -229,20 +229,25 @@ export interface ClampRadiusInStatePropsOptions {
 
 const STATE_STYLE_KEYS = ["hoverStyle", "pressStyle", "focusStyle", "focusVisibleStyle"] as const;
 
-const RADIUS_TOKEN_TO_STOP: Record<string, BorderRadius> = {
-  $0: "none",
-  "0": "none",
-  none: "none",
-  $2: "small",
-  small: "small",
-  $4: "medium",
-  medium: "medium",
-  $6: "large",
-  large: "large",
-  $12: "full",
-  full: "full",
-};
+/**
+ * Token/stop-name lookup DERIVED from `borderRadiusMap` — the same single
+ * source `otpRadiusStop` reads a few lines up. A hand-kept second copy of the
+ * token scale is how this file would end up with two answers for one stop, so
+ * there is only one (LC-16 ONE-IMPLEMENTATION).
+ */
+const RADIUS_TOKEN_TO_STOP = Object.fromEntries(
+  (Object.keys(borderRadiusMap) as BorderRadius[]).flatMap((stop) => [
+    [stop, stop],
+    [borderRadiusMap[stop], stop],
+  ]),
+) as Record<string, BorderRadius>;
 
+/**
+ * A state bag carries whatever the recipe put in it — a stop name, a radius
+ * token, or a raw px value. An unrecognised value resolves to `full`, which
+ * for BINARY is h/2: the safe direction, because the class has no
+ * intermediate value to fall back to.
+ */
 function radiusValueToStop(value: unknown): BorderRadius {
   if (value == null || value === 0) return "none";
   const key = String(value).trim();
@@ -251,8 +256,18 @@ function radiusValueToStop(value: unknown): BorderRadius {
 }
 
 /**
- * BINARY class contract (DG-RAD-03 / resolveRadiusClass("BINARY")): none is
- * square, every other stop is h/2. Tracks square with their thumbs (§R2).
+ * BINARY class contract (DG-RAD-03): none is square, every other stop is h/2,
+ * and tracks square with their thumbs (§R2).
+ *
+ * The table is NOT restated here. It is read from the doctrine-GENERATED
+ * resolver in `@multiplatform.one/theme`, so a DG-RAD edit reaches per-state
+ * override bags the same way it reaches the base radius — a local copy of the
+ * BINARY row would keep answering with the old doctrine (LC-16).
+ *
+ * The `heightPx` guard is the CALLER's contract rather than the table's: the
+ * doctrine only needs a height for the h/2 stops, but a part that declares
+ * BINARY without its height would resolve at `none` and throw at every other
+ * stop. Refusing up front beats working in one state and throwing in the next.
  */
 function resolveBinaryStateRadius(value: unknown, heightPx: number | undefined): number {
   if (heightPx === undefined || heightPx <= 0) {
@@ -260,7 +275,7 @@ function resolveBinaryStateRadius(value: unknown, heightPx: number | undefined):
       "clampRadiusInStateProps: BINARY resolves to 0 or h/2 and needs heightPx — the part's own painted height (shorter edge)",
     );
   }
-  return radiusValueToStop(value) === "none" ? 0 : heightPx / 2;
+  return resolveRadiusClass("BINARY", radiusValueToStop(value), { heightPx });
 }
 
 function clampOneStateRadius(