@multiplatform.one/forms 6.6.0 → 7.0.0

package/src/fields/RadioGroup/index.tsx

@@ -1,5 +1,15 @@
 import type { ReactNode } from "react";
 import { useCallback, useRef, useState } from "react";
+import {
+  ensureFocusVisibleRing,
+  ensureKeyboardModalityTracking,
+  useReadableTextOn,
+  wasKeyboardFocus,
+  type ControlStateProps,
+  type DisabledChromeProps,
+  type KnobProps,
+  type KnobRecipe,
+} from "@multiplatform.one/theme";
 import type { AnyFormApi } from "../../types";
 import type { FontSizeTokens, LabelProps, SizeTokens, TamaguiElement } from "tamagui";
 import {
@@ -51,17 +61,20 @@ const RadioItemFrame = styled(TamaguiRadioGroup.Item, {
   backgroundColor: "transparent",
   alignItems: "center",
   justifyContent: "center",
+  overflow: "visible",
+  // LC-71: the 44px hit target never carries a ring. Ring lives on the glyph
+  // of the focused radio only (keyboard modality), never every sibling.
+  outlineWidth: 0,
   hoverStyle: { backgroundColor: "transparent" },
   pressStyle: { backgroundColor: "transparent" },
-  focusStyle: { backgroundColor: "transparent" },
-  focusVisibleStyle: { backgroundColor: "transparent" },
+  focusStyle: { backgroundColor: "transparent", outlineWidth: 0 },
+  focusVisibleStyle: { backgroundColor: "transparent", outlineWidth: 0 },
 });
 
 // Visual radio circle, sized like tamagui's radio item (size token * 0.5).
-// DF-06 / WCAG 1.4.11: classic empty-ring anatomy — transparent fill with a
-// ≥3:1 boundary ring. The old filled disc ($color5 fill + $color7 border)
-// measured 1.26:1 vs the page and 1.20:1 border-vs-disc: three identical
-// gray blobs under a squint. The control's shape now comes from its ring.
+// Unselected (Polaris / Spectrum): DF-06 empty-ring — transparent fill with a
+// ≥3:1 boundary. Selected (Primer + LC-71): accent fill via direct props, not
+// a second outline on every sibling. Keyboard ring is painted on this glyph.
 const RadioGlyph = styled(View, {
   borderRadius: 1000,
   backgroundColor: "transparent",
@@ -90,13 +103,12 @@ const radioRingWidth = (knobBorderWidth: number | undefined) => Math.max(knobBor
 
 const RadioIndicatorFrame = styled(TamaguiRadioGroup.Indicator, {
   borderRadius: 1000,
-  // DF-06 optics rider (Axiom 15): the selected dot fills ~half the OUTER
-  // disc — the platform-convention 0.45–0.55 band. Percentage sizes resolve
-  // against the glyph's content box (disc minus the 2px ring), so 60% of
-  // content ≈ 0.49 of the disc at the 22px default. The previous 33%
-  // (6.6px in a 22px disc, 0.30) under-signaled the checked state.
-  width: "60%",
-  height: "60%",
+  // Primer / Spectrum inner mark on a FILLED disc (LC-71 selected=fill): the
+  // inverse center is ~1/3 of the outer control (Primer radial-gradient 33%,
+  // Spectrum inner pip). Percentage sizes resolve against the glyph content
+  // box (disc minus the 2px ring), so 40% of content ≈ 0.33 of the disc.
+  width: "40%",
+  height: "40%",
 });
 
 export interface RadioGroupOption {
@@ -152,6 +164,147 @@ export interface RadioGroupProps {
   card?: boolean;
 }
 
+interface RadioOptionItemProps {
+  option: RadioGroupOption;
+  itemId: string;
+  a11y?: { "aria-labelledby"?: string; "aria-describedby"?: string };
+  selected: boolean;
+  isTabStop?: boolean;
+  itemRadius: number;
+  indicatorRadius: number;
+  knobProps: KnobProps;
+  control: KnobRecipe<ControlStateProps>;
+  disabledChrome?: DisabledChromeProps;
+  groupDisabled?: boolean;
+  readOnly?: boolean;
+  elevationWrapperProps: Record<string, unknown>;
+}
+
+/**
+ * One radio: Primer/Spectrum/Polaris anatomy under LC-71.
+ * Unselected = empty disc (Polaris/Spectrum boundary ring). Selected = accent
+ * fill with an inverse inner pip (Primer). Keyboard ring on this glyph only.
+ */
+function RadioOptionItem({
+  option,
+  itemId,
+  a11y,
+  selected,
+  isTabStop,
+  itemRadius,
+  indicatorRadius,
+  knobProps,
+  control,
+  disabledChrome,
+  groupDisabled,
+  readOnly,
+  elevationWrapperProps,
+}: RadioOptionItemProps) {
+  const [kbFocus, setKbFocus] = useState(false);
+  ensureKeyboardModalityTracking();
+  const detachKb = useRef<(() => void) | null>(null);
+  const frameRef = useCallback((node: TamaguiElement | null) => {
+    detachKb.current?.();
+    detachKb.current = null;
+    if (!isWeb || !node) return;
+    const el = node as unknown as HTMLElement;
+    const onIn = () => {
+      if (wasKeyboardFocus()) setKbFocus(true);
+    };
+    const onOut = () => setKbFocus(false);
+    el.addEventListener("focusin", onIn);
+    el.addEventListener("focusout", onOut);
+    detachKb.current = () => {
+      el.removeEventListener("focusin", onIn);
+      el.removeEventListener("focusout", onOut);
+    };
+  }, []);
+  const onMark = useReadableTextOn(formSelectedColors.mark);
+  const hoverProps = stripRadiusFromStateProps(control.hoverKnobProps);
+  const pressProps = stripRadiusFromStateProps(control.pressKnobProps);
+  const focusProps = stripRadiusFromStateProps(control.focusKnobProps);
+
+  const glyph = (
+    <RadioGlyph
+      size={knobProps.sizeToken as SizeTokens}
+      borderWidth={radioRingWidth(knobProps.borderRadius.borderWidth)}
+      borderRadius={itemRadius}
+      outlined={knobProps.outlined}
+      // Direct props (not a selected variant): fill must win over hover/press
+      // fragments the way ToggleGroup's selected fill does.
+      backgroundColor={selected ? formSelectedColors.mark : "transparent"}
+      borderColor={selected ? formSelectedColors.mark : formControlColors.boundary}
+      {...(kbFocus ? ensureFocusVisibleRing() : { outlineWidth: 0 as const })}
+      data-radio-kb-focus={kbFocus ? "true" : "false"}
+      {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
+    >
+      <RadioIndicatorFrame
+        borderRadius={indicatorRadius}
+        backgroundColor={onMark ?? "$color1"}
+        {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
+      />
+    </RadioGlyph>
+  );
+
+  return (
+    <RadioItemFrame
+      value={option.value}
+      id={itemId}
+      // Roving tabindex (single tab stop): tamagui's vendored roving-focus
+      // item leaves tabIndex=0 on every radio, so a 3-option group was 3
+      // tab stops. Only the checked radio (or the first enabled one when
+      // none is checked) stays in the page tab order; arrows move + select.
+      {...(isWeb && isTabStop !== undefined ? { tabIndex: isTabStop ? 0 : -1 } : undefined)}
+      borderRadius={itemRadius === 0 ? 0 : 1000}
+      transition={knobProps.transition}
+      disabled={groupDisabled || option.disabled}
+      // LC-40 DISABLED-VISIBLE: ring is text-free chrome — dim it while the
+      // sibling label stays readable (read-only never dims).
+      {...(groupDisabled || option.disabled ? disabledChrome : undefined)}
+      pointerEvents={readOnly ? "none" : undefined}
+      {...a11y}
+      // RN only exposes the radio to the a11y tree when `accessible` is set;
+      // web keeps Tamagui's role=radio + label association untouched.
+      {...(!isWeb
+        ? {
+            accessible: true,
+            "aria-label": typeof option.label === "string" ? option.label : String(option.value),
+            "aria-checked": selected,
+          }
+        : {})}
+      {...(hoverProps && {
+        hoverStyle: {
+          ...hoverProps,
+          backgroundColor: "transparent",
+        },
+      })}
+      {...(pressProps && {
+        pressStyle: {
+          ...pressProps,
+          backgroundColor: "transparent",
+        },
+      })}
+      {...(focusProps && {
+        focusStyle: {
+          ...focusProps,
+          backgroundColor: "transparent",
+          outlineWidth: 0,
+        },
+      })}
+      focusVisibleStyle={{ backgroundColor: "transparent", outlineWidth: 0 }}
+      ref={isWeb ? frameRef : undefined}
+    >
+      {elevationWrapperProps.elevation ? (
+        <View {...elevationWrapperProps} borderRadius={itemRadius}>
+          {glyph}
+        </View>
+      ) : (
+        glyph
+      )}
+    </RadioItemFrame>
+  );
+}
+
 export function RadioGroup({
   name,
   form: formProp,
@@ -273,86 +426,23 @@ export function RadioGroup({
     a11y?: { "aria-labelledby"?: string; "aria-describedby"?: string },
     selected?: boolean,
     isTabStop?: boolean,
-  ) => {
-    const glyph = (
-      <RadioGlyph
-        size={knobProps.sizeToken}
-        borderWidth={radioRingWidth(knobProps.borderRadius.borderWidth)}
-        borderRadius={itemRadius}
-        outlined={knobProps.outlined}
-        {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
-      >
-        <RadioIndicatorFrame
-          borderRadius={indicatorRadius}
-          // LC-05: the dot is the selection mark, so it paints the active
-          // accent — `textAccentColor` is the LABEL ink tier ($color/$color11)
-          // and made the checked radio read as ink, not as chosen (D-01).
-          backgroundColor={formSelectedColors.mark}
-          {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
-        />
-      </RadioGlyph>
-    );
-    return (
-      <RadioItemFrame
-        value={option.value}
-        id={itemId}
-        // Roving tabindex (single tab stop): tamagui's vendored roving-focus
-        // item leaves tabIndex=0 on every radio, so a 3-option group was 3
-        // tab stops. Only the checked radio (or the first enabled one when
-        // none is checked) stays in the page tab order; arrows move + select.
-        {...(isWeb && isTabStop !== undefined ? { tabIndex: isTabStop ? 0 : -1 } : undefined)}
-        borderRadius={itemRadius === 0 ? 0 : 1000}
-        transition={knobProps.transition}
-        disabled={disabled || option.disabled}
-        // LC-40 DISABLED-VISIBLE: ring is text-free chrome — dim it while the
-        // sibling label stays readable (read-only never dims).
-        {...(disabled || option.disabled ? disabledState.chromeKnobProps : undefined)}
-        pointerEvents={readOnly ? "none" : undefined}
-        {...a11y}
-        // RN only exposes the radio to the a11y tree when `accessible` is set;
-        // web keeps Tamagui's role=radio + label association untouched.
-        {...(!isWeb
-          ? {
-              accessible: true,
-              "aria-label": typeof option.label === "string" ? option.label : String(option.value),
-              "aria-checked": selected ?? false,
-            }
-          : {})}
-        {...(stripRadiusFromStateProps(control.hoverKnobProps) && {
-          hoverStyle: {
-            backgroundColor: "transparent",
-            ...stripRadiusFromStateProps(control.hoverKnobProps),
-          },
-        })}
-        {...(stripRadiusFromStateProps(control.pressKnobProps) && {
-          pressStyle: {
-            backgroundColor: "transparent",
-            ...stripRadiusFromStateProps(control.pressKnobProps),
-          },
-        })}
-        {...(stripRadiusFromStateProps(control.focusKnobProps) && {
-          focusStyle: {
-            backgroundColor: "transparent",
-            ...stripRadiusFromStateProps(control.focusKnobProps),
-          },
-        })}
-        {...(stripRadiusFromStateProps(control.focusVisibleKnobProps) && {
-          focusVisibleStyle: {
-            backgroundColor: "transparent",
-            ...stripRadiusFromStateProps(control.focusVisibleKnobProps),
-          },
-        })}
-      >
-        {elevationWrapperProps.elevation ? (
-          <View {...elevationWrapperProps} borderRadius={itemRadius}>
-            {glyph}
-          </View>
-        ) : (
-          glyph
-        )}
-      </RadioItemFrame>
-    );
-  };
+  ) => (
+    <RadioOptionItem
+      option={option}
+      itemId={itemId}
+      a11y={a11y}
+      selected={!!selected}
+      isTabStop={isTabStop}
+      itemRadius={itemRadius}
+      indicatorRadius={indicatorRadius}
+      knobProps={knobProps}
+      control={control}
+      disabledChrome={disabledState.chromeKnobProps}
+      groupDisabled={disabled}
+      readOnly={readOnly}
+      elevationWrapperProps={elevationWrapperProps}
+    />
+  );
 
   const renderItems = (currentValue: string | undefined, emit: (val: string) => void) => {
     if (children) return children;

package/src/fields/Rating/Rating.spec.tsx

@@ -139,6 +139,96 @@ describe("Rating", () => {
       expect(filled!.getAttribute("data-color")).toContain("accentBackground");
       expect(empty!.getAttribute("data-color")).not.toContain("accentBackground");
     });
+
+    // Material Rating is a radio group: one checked value, stars 1..N fill as
+    // a consequence. aria-pressed-on-every-filled-star was the old lie.
+    it("exposes a radiogroup where only the committed star is checked", () => {
+      const result = renderWithProviders(
+        <Rating label="Quality" value={0.6} starIcon={MockStarIcon} />,
+      );
+      const group = result.container.querySelector("[data-rating-row]");
+      expect(group?.getAttribute("role")).toBe("radiogroup");
+      const radios = Array.from(result.container.querySelectorAll("[data-rating-star]"));
+      expect(radios.map((el) => el.getAttribute("role"))).toEqual([
+        "radio",
+        "radio",
+        "radio",
+        "radio",
+        "radio",
+      ]);
+      expect(radios.map((el) => el.getAttribute("aria-checked"))).toEqual([
+        "false",
+        "false",
+        "true",
+        "false",
+        "false",
+      ]);
+    });
+
+    // LC-71: pointer focus paints no ring (wasKeyboardFocus is pinned false
+    // in test-utils). The ring node is only mounted for keyboard-origin.
+    it("does not paint a focus ring on pointer focus", () => {
+      const result = renderWithProviders(
+        <Rating label="Quality" value={0.4} starIcon={MockStarIcon} />,
+      );
+      const star = result.container.querySelector("[data-rating-index='2']") as HTMLElement;
+      fireEvent.focus(star);
+      expect(result.container.querySelector("[data-rating-ring]")).toBeNull();
+    });
+
+    it("read-only rating is an image, not a tab stop", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Rating label="Score" value={0.8} readOnly starIcon={MockStarIcon} onChange={onChange} />,
+      );
+      const row = result.container.querySelector("[data-rating-row]");
+      expect(row?.getAttribute("role")).toBe("img");
+      const stars = Array.from(result.container.querySelectorAll("[data-rating-star]"));
+      expect(stars).toHaveLength(5);
+      for (const star of stars) {
+        expect(star.getAttribute("tabindex")).toBeNull();
+        expect(star.getAttribute("role")).toBeNull();
+      }
+      fireEvent.click(stars[0] as HTMLElement);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("scales the star glyph with the size token", () => {
+      const small = renderWithProviders(
+        <Rating label="Small" value={0.6} size="$2" starIcon={MockStarIcon} />,
+      );
+      const large = renderWithProviders(
+        <Rating label="Large" value={0.6} size="$5" starIcon={MockStarIcon} />,
+      );
+      const smallSize = Number(
+        small.container.querySelector("[data-testid='star']")?.getAttribute("data-size"),
+      );
+      const largeSize = Number(
+        large.container.querySelector("[data-testid='star']")?.getAttribute("data-size"),
+      );
+      expect(smallSize).toBeGreaterThan(0);
+      expect(largeSize).toBeGreaterThan(smallSize);
+    });
+
+    it("clamps overflow values to maxStars and shows a live value", () => {
+      const result = renderWithProviders(
+        <Rating label="Clamped" value={3} maxStars={5} starIcon={MockStarIcon} />,
+      );
+      const filled = result.container.querySelectorAll("[data-rating-star='filled']");
+      expect(filled.length).toBe(5);
+      const readout = result.container.querySelector("[data-rating-value]");
+      expect(readout?.textContent).toMatch(/5/);
+    });
+
+    it("arrow keys move focus and commit the rating", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Rating label="Kbd" value={0.4} starIcon={MockStarIcon} onChange={onChange} />,
+      );
+      const star2 = result.container.querySelector("[data-rating-index='2']") as HTMLElement;
+      fireEvent.keyDown(star2, { key: "ArrowRight" });
+      expect(onChange).toHaveBeenCalledWith(0.6);
+    });
   });
 
   describe("with form context", () => {
@@ -150,5 +240,18 @@ describe("Rating", () => {
       );
       expect(result.findTextElement("Rate")).toBeDefined();
     });
+
+    it("read-only form field does not commit", () => {
+      const onChange = vi.fn();
+      const result = renderWithProviders(
+        <Form formOptions={{ defaultValues: { rating: 0.6 } }} submitText="Submit">
+          <Rating name="rating" label="Rate" readOnly starIcon={MockStarIcon} onChange={onChange} />
+        </Form>,
+      );
+      const star = result.container.querySelector("[data-rating-index='5']") as HTMLElement;
+      fireEvent.click(star);
+      expect(onChange).not.toHaveBeenCalled();
+      expect(result.container.querySelector("[data-rating-row]")?.getAttribute("role")).toBe("img");
+    });
   });
 });

package/src/fields/Rating/Rating.stories.tsx

@@ -212,7 +212,7 @@ export const Interactive: Story = {
         <YStack gap="$4" maxWidth={300}>
           <Rating
             label="How would you rate this?"
-            helperText={`${Math.round(value * 5)} out of 5 stars`}
+            helperText="Click a star, or hover to preview"
             value={value}
             onChange={(v) => {
               setValue(v);
@@ -220,6 +220,7 @@ export const Interactive: Story = {
             }}
             starIcon={StarIcon}
           />
+          <Rating label="Read only" value={0.8} readOnly starIcon={StarIcon} />
           <Rating label="Disabled" value={0.8} disabled starIcon={StarIcon} />
         </YStack>
       );

package/src/fields/Rating/StarInk.native.spec.tsx

@@ -0,0 +1,175 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { StarInk, inkMotionProps } from "./StarInk.native";
+import { StarInk as StarInkWeb } from "./StarInk";
+import type { StarIconType } from "./types";
+
+/**
+ * Native ink layer (LC-25). The device arm is BLOCKED — see
+ * `p-results/fix-rating-native-ink.md` — so this is the native evidence:
+ * `.native` specs are the standing substitute for a simulator capture
+ * (`agent-os/standards/testing/falsifiability.md`, "Record the verdict
+ * against the code that ran").
+ *
+ * It cannot prove the RN driver's frame output. What it CAN prove is the
+ * property that made the star dead: the ink change has to land on a key the
+ * driver animates, driven by the knob token, with silence at `none`.
+ */
+
+const captured: Array<{ size: number; weight: string; color: string; keys: string[] }> = [];
+
+/** Records EVERY prop the contract hands the glyph, so an added one shows up. */
+const SpyStarIcon: StarIconType = (props) => {
+  captured.push({ ...props, keys: Object.keys(props).sort() });
+  return <span data-testid="glyph" data-weight={props.weight} data-color={props.color} />;
+};
+
+function renderInk(overrides: Partial<Parameters<typeof StarInk>[0]> = {}) {
+  captured.length = 0;
+  return renderWithProviders(
+    <StarInk
+      StarIcon={SpyStarIcon}
+      size={24}
+      filled={false}
+      filledColor="#634FC4"
+      emptyColor="#D3D1D6"
+      transition="quick"
+      {...overrides}
+    />,
+  );
+}
+
+const layer = (container: HTMLElement, which: "empty" | "filled") =>
+  container.querySelector(`[data-rating-ink='${which}']`) as HTMLElement | null;
+
+/** Tamagui emits opacity as the atomic class `_o-<value>`, not inline style. */
+function opacityOf(container: HTMLElement, which: "empty" | "filled"): number | null {
+  const match = layer(container, which)?.className.match(/(?:^|\s)_o-([\d.]+)(?:\s|$)/);
+  return match ? Number(match[1]) : null;
+}
+
+describe("StarInk (native) motion props", () => {
+  // Axiom 4: the token IS the knob's. A hardcoded duration, or a token not
+  // scoped to opacity, fails here.
+  it("scopes the knob token to opacity", () => {
+    expect(inkMotionProps("quick")).toEqual({ transition: { opacity: "quick" } });
+    // A different knob must produce a different token — pinning only "quick"
+    // would pass against a hardcoded default.
+    expect(inkMotionProps("bouncy")).toEqual({ transition: { opacity: "bouncy" } });
+  });
+
+  // Axiom 3 / LC-25. The positive control is the assertion above: the same
+  // helper demonstrably yields a transition when a token exists, so the empty
+  // object here is a measured absence rather than a probe that sees nothing.
+  it("emits NO transition at animation=none / reduced motion", () => {
+    expect(inkMotionProps(undefined)).toEqual({});
+  });
+
+  // The web fix deliberately dropped `|| "quick"`; native must not reintroduce
+  // it. `none` resolving to a token is exactly the regression this catches.
+  it("never substitutes a default token for a missing knob", () => {
+    expect(inkMotionProps(undefined)).not.toHaveProperty("transition");
+  });
+});
+
+describe("StarInk (native) layer stack", () => {
+  // The defect: one glyph swapped in place, so the ink could only jump. Both
+  // states must be MOUNTED for opacity to have anything to cross-fade.
+  it("mounts both glyph states so the ink rides opacity", () => {
+    const { container } = renderInk({ filled: false });
+    expect(layer(container, "empty")).not.toBeNull();
+    expect(layer(container, "filled")).not.toBeNull();
+    expect(captured.map((c) => c.weight).sort()).toEqual(["fill", "regular"]);
+  });
+
+  it("cross-fades opacity with the filled state", () => {
+    const empty = renderInk({ filled: false });
+    expect(opacityOf(empty.container, "empty")).toBe(1);
+    expect(opacityOf(empty.container, "filled")).toBe(0);
+
+    const full = renderInk({ filled: true });
+    expect(opacityOf(full.container, "empty")).toBe(0);
+    expect(opacityOf(full.container, "filled")).toBe(1);
+  });
+
+  // LC-25 settled-state parity: exactly one layer is visible at rest, so a
+  // filled star is the fill glyph alone and an empty star the outline alone —
+  // the same pixels the pre-fix single-glyph render produced. A cross-fade
+  // that left both layers partly visible at rest would dim every star.
+  it("shows exactly one layer at rest in both states", () => {
+    for (const filled of [false, true]) {
+      const { container } = renderInk({ filled });
+      const opacities = (["empty", "filled"] as const).map((which) => opacityOf(container, which));
+      expect(opacities.filter((o) => o === 1)).toHaveLength(1);
+      expect(opacities.filter((o) => o === 0)).toHaveLength(1);
+    }
+  });
+
+  // The prop has to survive onto the element, not just out of the helper: the
+  // transition must name `opacity` (never `all`, which would drag the layout
+  // props animating alongside it).
+  it("arms an opacity-scoped transition on both layers", () => {
+    const { container } = renderInk({ transition: "quick" });
+    for (const which of ["empty", "filled"] as const) {
+      const declared = layer(container, which)?.style.transition ?? "";
+      expect(declared).toContain("opacity");
+      expect(declared).not.toContain("all");
+    }
+  });
+
+  // Axiom 4 end to end: swapping the knob must change the motion the element
+  // declares. Identical strings here would mean a hardcoded duration.
+  it("changes the declared motion when the knob changes", () => {
+    const quick = layer(renderInk({ transition: "quick" }).container, "filled")?.style.transition;
+    const lazy = layer(renderInk({ transition: "lazy" }).container, "filled")?.style.transition;
+    expect(quick).toBeTruthy();
+    expect(lazy).toBeTruthy();
+    expect(lazy).not.toBe(quick);
+  });
+
+  // Axiom 3 at the element. Positive control: the two tests above show this
+  // same probe reading a real transition off these same layers, so an empty
+  // string here is a measured silence, not a blind spot.
+  it("declares no transition at all when the knob is none", () => {
+    const { container } = renderInk({ transition: undefined });
+    for (const which of ["empty", "filled"] as const) {
+      expect(layer(container, which)?.style.transition ?? "").toBe("");
+    }
+  });
+
+  // The whole point of the layer-stack route: the icon never learns about it.
+  it("hands starIcon the three contract props and nothing else", () => {
+    renderInk({ filled: true });
+    expect(captured).toHaveLength(2);
+    for (const props of captured) {
+      expect(props.keys).toEqual(["color", "size", "weight"]);
+    }
+    expect(captured.find((c) => c.weight === "fill")?.color).toBe("#634FC4");
+    expect(captured.find((c) => c.weight === "regular")?.color).toBe("#D3D1D6");
+  });
+});
+
+describe("StarInk web/native parity", () => {
+  // Axiom 13 ONE BODY: same contract, same props, two renderers. The web half
+  // must stay the bare glyph — the descendant stylesheet in index.tsx arms it,
+  // and an extra wrapper node would sit between the ink class and the svg.
+  it("web renders the single glyph the stylesheet targets", () => {
+    captured.length = 0;
+    const { container } = renderWithProviders(
+      <StarInkWeb
+        StarIcon={SpyStarIcon}
+        size={24}
+        filled
+        filledColor="#634FC4"
+        emptyColor="#D3D1D6"
+        transition="quick"
+      />,
+    );
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.weight).toBe("fill");
+    expect(captured[0]?.color).toBe("#634FC4");
+    expect(captured[0]?.keys).toEqual(["color", "size", "weight"]);
+    // No ink layers on web: the cascade does that job there.
+    expect(container.querySelector("[data-rating-ink]")).toBeNull();
+  });
+});