@multiplatform.one/theme 7.4.0 → 7.5.0

package/src/theme/radiusClass.spec.ts

@@ -0,0 +1,394 @@
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+import type { BorderRadius } from "./knobs";
+import { radiusOverrideFor, resolveRadiusClass, resolveRadiusForPart } from "./radiusClass";
+import {
+  OPEN_RADIUS_ADJUDICATIONS,
+  RADIUS_OVERRIDE_TABLE,
+  RADIUS_RESOLUTION_COMPOSITION,
+  RADIUS_RESOLUTION_STOPS,
+  RADIUS_RESOLUTION_TABLE,
+} from "./radiusClassTable.generated";
+import { capContainerRadius } from "./resolveKnobs";
+
+// The generator is the doctrine's reading end — the spec imports it directly so a
+// doctrine edit and a generated-table edit are compared in the same run. Vite
+// rewrites import.meta.url to an http URL, so we resolve from cwd (public/theme)
+// and force a file: specifier the ESM loader will accept.
+const registry = await import(
+  pathToFileURL(join(process.cwd(), "../../scripts/radius-class-registry.mjs")).href
+);
+const doctrine = registry.readRadiusClassDoctrine();
+
+const STOPS = ["none", "small", "medium", "large", "full"] as const;
+
+// Sample geometry: a 44px control (h/2 = 22) and the three space-stop paddings
+// the doctrine names (13/18/32 — panelPaddingPxMap).
+const H = 44;
+const PADS = { small: 13, medium: 18, large: 32 } as const;
+
+describe("the doctrine table, cell by cell (DG-RAD-01..04)", () => {
+  const expected: Record<string, Record<BorderRadius, number>> = {
+    DEFAULT: { none: 0, small: 5, medium: 9, large: 16, full: 50 },
+    "CIRCULAR-AT-FULL": { none: 0, small: 5, medium: 9, large: 16, full: H / 2 },
+    BINARY: { none: 0, small: H / 2, medium: H / 2, large: H / 2, full: H / 2 },
+  };
+
+  for (const [radiusClass, row] of Object.entries(expected)) {
+    for (const stop of STOPS) {
+      it(`${radiusClass} at ${stop} resolves to ${row[stop]}`, () => {
+        expect(
+          resolveRadiusClass(radiusClass as keyof typeof RADIUS_RESOLUTION_TABLE, stop, {
+            heightPx: H,
+          }),
+        ).toBe(row[stop]);
+      });
+    }
+  }
+
+  const containerCap: Record<keyof typeof PADS, Record<BorderRadius, number>> = {
+    small: { none: 0, small: 5, medium: 9, large: 13, full: 13 },
+    medium: { none: 0, small: 5, medium: 9, large: 16, full: 18 },
+    large: { none: 0, small: 5, medium: 9, large: 16, full: 32 },
+  };
+
+  for (const space of Object.keys(containerCap) as (keyof typeof PADS)[]) {
+    for (const stop of STOPS) {
+      it(`CONTAINER-CAP at ${stop} under space=${space} resolves to ${containerCap[space][stop]}`, () => {
+        expect(resolveRadiusClass("CONTAINER-CAP", stop, { paddingPx: PADS[space] })).toBe(
+          containerCap[space][stop],
+        );
+      });
+    }
+  }
+});
+
+describe("capContainerRadius agrees with the CONTAINER-CAP column (DG-RAD-04, unchanged)", () => {
+  // capContainerRadius returns the TOKEN while it fits and the padding px once
+  // it would exceed; mirror the token px scale to compare resolutions.
+  const tokenPx: Record<string, number> = { $0: 0, $2: 5, $4: 9, $6: 16, $12: 50 };
+  const asPx = (value: string | number): number =>
+    typeof value === "number" ? value : tokenPx[value];
+
+  for (const space of Object.keys(PADS) as (keyof typeof PADS)[]) {
+    for (const stop of STOPS) {
+      it(`at ${stop} under space=${space}`, () => {
+        expect(asPx(capContainerRadius(stop, space))).toBe(
+          resolveRadiusClass("CONTAINER-CAP", stop, { paddingPx: PADS[space] }),
+        );
+      });
+    }
+  }
+
+  it("the cap is the container's own padding at full, under every space", () => {
+    expect(capContainerRadius("full", "small")).toBe(13);
+    expect(capContainerRadius("full", "medium")).toBe(18);
+    expect(capContainerRadius("full", "large")).toBe(32);
+  });
+
+  it("the cap bites at large under space=small (16 > 13) and nowhere else below full", () => {
+    expect(capContainerRadius("large", "small")).toBe(13);
+    expect(capContainerRadius("large", "medium")).toBe("$6");
+    expect(capContainerRadius("large", "large")).toBe("$6");
+    expect(capContainerRadius("medium", "small")).toBe("$4");
+    expect(capContainerRadius("small", "small")).toBe("$2");
+    expect(capContainerRadius("none", "small")).toBe("$0");
+  });
+});
+
+describe("the generated table is the doctrine, not a hand-kept copy", () => {
+  it("RADIUS_RESOLUTION_TABLE matches a fresh parse of docs/design-guidelines.md", () => {
+    expect(JSON.parse(JSON.stringify(RADIUS_RESOLUTION_TABLE))).toEqual(doctrine.classes);
+  });
+
+  it("RADIUS_OVERRIDE_TABLE matches the doctrine's DG-RAD-05 table", () => {
+    expect(JSON.parse(JSON.stringify(RADIUS_OVERRIDE_TABLE))).toEqual(doctrine.overrides);
+  });
+
+  it("OPEN_RADIUS_ADJUDICATIONS matches the doctrine's open list", () => {
+    expect(JSON.parse(JSON.stringify(OPEN_RADIUS_ADJUDICATIONS))).toEqual(
+      doctrine.openAdjudications,
+    );
+  });
+
+  it("the stops and the composition order are the doctrine's", () => {
+    expect([...RADIUS_RESOLUTION_STOPS]).toEqual(doctrine.stops);
+    expect([...RADIUS_RESOLUTION_COMPOSITION]).toEqual(doctrine.composition);
+  });
+
+  it("the class set is exactly the four ruled classes — no silent widening", () => {
+    expect(Object.keys(RADIUS_RESOLUTION_TABLE).sort()).toEqual([
+      "BINARY",
+      "CIRCULAR-AT-FULL",
+      "CONTAINER-CAP",
+      "DEFAULT",
+    ]);
+  });
+});
+
+describe("a doctrine edit the code cannot spell FAILS loudly", () => {
+  const tempPaths: string[] = [];
+  afterAll(() => {
+    for (const path of tempPaths) rmSync(path, { force: true });
+  });
+
+  const parseMutated = (mutate: (source: string) => string) => {
+    const source = readFileSync(registry.DOCTRINE_PATH, "utf-8");
+    const mutated = mutate(source);
+    expect(mutated).not.toBe(source); // the mutation must have landed
+    const path = join(tmpdir(), `dg-rad-spec-${process.pid}-${tempPaths.length}.md`);
+    writeFileSync(path, mutated);
+    tempPaths.push(path);
+    return () => registry.readRadiusClassDoctrine(path);
+  };
+
+  it("rejects a cell spelling outside the closed grammar", () => {
+    expect(
+      parseMutated((s) =>
+        s.replace("| BINARY           | 0    | h/2", "| BINARY           | 0    | thumb-ish"),
+      ),
+    ).toThrow(/not a spelling the radius registry can read/);
+  });
+
+  it("rejects a class that resolves `none` to nonzero (DG-RAD-01)", () => {
+    expect(
+      parseMutated((s) => s.replace("| BINARY           | 0    |", "| BINARY           | 3    |")),
+    ).toThrow(/does not resolve `none` to 0/);
+  });
+
+  it("rejects a table that loses one of the four ruled classes", () => {
+    expect(
+      parseMutated((s) => s.replace("| CIRCULAR-AT-FULL | 0", "| CIRCLE-ISH-MAYBE | 0")),
+    ).toThrow(/missing CIRCULAR-AT-FULL/);
+  });
+
+  it("rejects a Checkbox override spelled h/2 — R2b is a ruling, not a cell", () => {
+    expect(
+      parseMutated((s) =>
+        s.replace(
+          "| Checkbox   | 0    | 5     | 5      | 5     | 5",
+          "| Checkbox   | 0    | 5     | 5      | 5     | h/2",
+        ),
+      ),
+    ).toThrow(/Checkbox override spells h\/2/);
+  });
+
+  it("rejects a Radio disc override that is not h/2 — radio is always round (R2c)", () => {
+    expect(
+      parseMutated((s) =>
+        s.replace(
+          "| Radio disc | h/2  | h/2   | h/2    | h/2   | h/2",
+          "| Radio disc | 0    | h/2   | h/2    | h/2   | h/2",
+        ),
+      ),
+    ).toThrow(/Radio disc override is not h\/2/);
+  });
+
+  it("rejects a doctrine that drops the composition order sentence", () => {
+    expect(
+      parseMutated((s) =>
+        s.replace(
+          "immunity wins, then a declared override, then the class",
+          "the class wins, probably",
+        ),
+      ),
+    ).toThrow(/composition note no longer spells the order/);
+  });
+
+  it("resolveRadiusClass throws on a class the doctrine never ruled", () => {
+    expect(() => resolveRadiusClass("R-VIBES" as never, "full")).toThrow(/not a class/);
+  });
+
+  it("resolveRadiusClass throws on a stop the table does not know", () => {
+    expect(() => resolveRadiusClass("DEFAULT", "extra-full" as never)).toThrow(/not a radius stop/);
+  });
+
+  it("h/2 cells demand the part's own painted height", () => {
+    expect(() => resolveRadiusClass("BINARY", "small")).toThrow(/needs geometry\.heightPx/);
+    expect(() => resolveRadiusClass("CIRCULAR-AT-FULL", "full", {})).toThrow(
+      /needs geometry\.heightPx/,
+    );
+    expect(() => resolveRadiusClass("BINARY", "small", { heightPx: 0 })).toThrow(
+      /needs geometry\.heightPx/,
+    );
+  });
+
+  it("CONTAINER-CAP cells demand the container's own padding", () => {
+    expect(() => resolveRadiusClass("CONTAINER-CAP", "full")).toThrow(/needs geometry\.paddingPx/);
+    expect(() => resolveRadiusClass("CONTAINER-CAP", "small", { heightPx: H })).toThrow(
+      /needs geometry\.paddingPx/,
+    );
+  });
+});
+
+describe("the override layer wins over the class layer (DG-RAD-05)", () => {
+  it("Checkbox measures a square-cornered box at every stop, never h/2 (R2b)", () => {
+    const glyph = 20; // the checkbox glyph is 20×20, so h/2 would be 10
+    for (const stop of STOPS) {
+      const resolved = resolveRadiusForPart({
+        part: "Checkbox",
+        radiusClass: "CIRCULAR-AT-FULL", // its kin class by shape — the override must beat it
+        stop,
+        heightPx: glyph,
+      });
+      expect(resolved.source).toBe("override");
+      expect(resolved.px).toBe(stop === "none" ? 0 : 5);
+      expect(resolved.px).not.toBe(glyph / 2);
+      expect(resolved.overrideWhy).toMatch(/reads as a radio/);
+    }
+  });
+
+  it("Checkbox at full is the clamp (5), not the kin circle (10) and not the token (50)", () => {
+    const resolved = resolveRadiusForPart({
+      part: "Checkbox",
+      radiusClass: "CIRCULAR-AT-FULL",
+      stop: "full",
+      heightPx: 20,
+    });
+    expect(resolved.px).toBe(5);
+  });
+
+  it("the Radio disc is round at every stop, including none (R2c — R2b inverted)", () => {
+    const disc = 20;
+    for (const stop of STOPS) {
+      const resolved = resolveRadiusForPart({
+        part: "Radio disc",
+        radiusClass: "BINARY",
+        stop,
+        heightPx: disc,
+      });
+      expect(resolved.source).toBe("override");
+      expect(resolved.px).toBe(disc / 2);
+    }
+  });
+
+  it("override lookup matches the doctrine spelling case-insensitively", () => {
+    expect(radiusOverrideFor("checkbox")?.component).toBe("Checkbox");
+    expect(radiusOverrideFor("RADIO DISC")?.component).toBe("Radio disc");
+    expect(radiusOverrideFor("Button")).toBeUndefined();
+  });
+
+  it("an UNDECLARED part still resolves by its class", () => {
+    const resolved = resolveRadiusForPart({ part: "Button", radiusClass: "DEFAULT", stop: "full" });
+    expect(resolved.source).toBe("class");
+    expect(resolved.px).toBe(50);
+    expect(resolved.overrideWhy).toBeUndefined();
+    // and with no part at all, the class is the resolution
+    expect(resolveRadiusForPart({ radiusClass: "BINARY", stop: "medium", heightPx: H }).px).toBe(
+      H / 2,
+    );
+  });
+});
+
+describe("knob-immunity COMPOSES above resolution (LC-60 / D-09, R2a)", () => {
+  it("a declared R-PILL mark stays round at none — the knob never reaches it", () => {
+    const dot = 8;
+    const resolved = resolveRadiusForPart({
+      part: "Badge count/dot",
+      radiusClass: "DEFAULT",
+      immunity: "R-PILL",
+      stop: "none",
+      heightPx: dot,
+    });
+    expect(resolved.source).toBe("immunity");
+    expect(resolved.px).toBe(dot / 2); // round, not the class table's 0
+  });
+
+  it("a declared R-IDENTITY part stays round at every stop", () => {
+    for (const stop of STOPS) {
+      const resolved = resolveRadiusForPart({
+        part: "Avatar",
+        radiusClass: "CIRCULAR-AT-FULL",
+        immunity: "R-IDENTITY",
+        stop,
+        heightPx: 40,
+      });
+      expect(resolved.source).toBe("immunity");
+      expect(resolved.px).toBe(20);
+    }
+  });
+
+  it("immunity wins over a declared override — composed, never replaced", () => {
+    const resolved = resolveRadiusForPart({
+      part: "Checkbox",
+      immunity: "R-IDENTITY",
+      stop: "full",
+      heightPx: 20,
+    });
+    expect(resolved.source).toBe("immunity");
+    expect(resolved.px).toBe(10);
+  });
+
+  it("immunity is round geometry, so it demands the painted height", () => {
+    expect(() =>
+      resolveRadiusForPart({ part: "Badge count/dot", immunity: "R-PILL", stop: "none" }),
+    ).toThrow(/needs geometry\.heightPx/);
+  });
+
+  it("the doctrine's layering order is immunity, then override, then class", () => {
+    expect([...RADIUS_RESOLUTION_COMPOSITION]).toEqual(["immunity", "override", "class"]);
+  });
+});
+
+describe("open adjudications are REPORTED, never silently skipped (MPO-56 AC-6)", () => {
+  it("the exclusion list is empty — R2 leftovers closed by RULINGS-2026-08-28", () => {
+    expect(OPEN_RADIUS_ADJUDICATIONS).toEqual([]);
+  });
+});
+
+describe("closed R2 leftovers (RULINGS-2026-08-28)", () => {
+  it("a single-line control at full is the DEFAULT pill token (50), not clampRadiusForControl's 16 (R2d)", () => {
+    const resolved = resolveRadiusForPart({
+      part: "Input",
+      radiusClass: "DEFAULT",
+      stop: "full",
+      heightPx: 44,
+    });
+    expect(resolved.source).toBe("class");
+    expect(resolved.px).toBe(50);
+    expect(resolved.px).not.toBe(16);
+  });
+
+  it("an icon well rides DEFAULT — square at none, token on the scale, no override (R2e)", () => {
+    expect(radiusOverrideFor("icon well")).toBeUndefined();
+    expect(radiusOverrideFor("empty icon well")).toBeUndefined();
+    const atNone = resolveRadiusForPart({
+      part: "empty icon well",
+      radiusClass: "DEFAULT",
+      stop: "none",
+      heightPx: 44,
+    });
+    expect(atNone.source).toBe("class");
+    expect(atNone.px).toBe(0);
+    expect(
+      resolveRadiusForPart({ part: "empty icon well", radiusClass: "DEFAULT", stop: "medium" }).px,
+    ).toBe(9);
+    expect(
+      resolveRadiusForPart({ part: "empty icon well", radiusClass: "DEFAULT", stop: "full" }).px,
+    ).toBe(50);
+  });
+
+  it("BINARY at none is 0 for thumb AND track — they square together (R2f)", () => {
+    for (const part of ["Switch thumb", "Switch track", "Slider thumb", "Slider rail"]) {
+      const resolved = resolveRadiusForPart({
+        part,
+        radiusClass: "BINARY",
+        stop: "none",
+        heightPx: 28,
+      });
+      expect(resolved.source).toBe("class");
+      expect(resolved.px).toBe(0);
+    }
+    expect(
+      resolveRadiusForPart({
+        part: "Switch track",
+        radiusClass: "BINARY",
+        stop: "small",
+        heightPx: 28,
+      }).px,
+    ).toBe(14);
+  });
+});

package/src/theme/radiusClass.ts

@@ -1,5 +1,24 @@
 /**
- * Radius-class declarations (D-09 / LC-60).
+ * Radius-class declarations (D-09 / LC-60) and the radius RESOLUTION resolver
+ * (DG-RAD-01..05, Clay ruling 2026-08-28).
+ *
+ * Two axes live here, and they COMPOSE rather than replace each other:
+ *
+ * 1. Knob-IMMUNITY (`R-PILL` / `R-IDENTITY`, LC-60/D-09): the knob does not
+ *    reach the part at all — roundness is the part's identity, so it stays
+ *    round at every stop including `none`. Declared via `radiusClassProps`,
+ *    registered in `docs/theme-propagation-spec.md` § Radius.
+ * 2. RESOLUTION (DG-RAD, `docs/design-guidelines.md` §13): given that a part
+ *    listens to the knob, what a stop resolves to. Four classes (DEFAULT /
+ *    CIRCULAR-AT-FULL / BINARY / CONTAINER-CAP), with a per-component
+ *    override layer on top where meaning demands it (DG-RAD-05 — Checkbox
+ *    never becomes a circle; the Radio disc never stops being one).
+ *
+ * `resolveRadiusForPart` layers them in doctrine order: immunity wins, then a
+ * declared override, then the class. The tables are GENERATED from the DG-RAD
+ * doctrine section (`scripts/radius-class-registry.mjs` --emit/--check), so
+ * code and doctrine cannot drift — the same contract the immunity axis has
+ * with `scripts/radius-identity-registry.mjs`.
  *
  * Most parts prove they obey the radius knob by simply going square at
  * `borderRadius:none`. A few legitimately do not — an ornamental dot has no
@@ -15,13 +34,25 @@
  * module is the writing end; `docs/theme-propagation-spec.md` is the registry.
  */
 
+import type { BorderRadius } from "./knobs";
+import {
+  RADIUS_OVERRIDE_TABLE,
+  RADIUS_RESOLUTION_COMPOSITION,
+  RADIUS_RESOLUTION_TABLE,
+  type RadiusOverrideEntry,
+  type RadiusResolutionCell,
+  type RadiusResolutionClass,
+} from "./radiusClassTable.generated";
+
 /**
  * The radius classes whose parts stay round at `borderRadius:none`.
  *
  * - `R-PILL` — a pill/circle at every radius value (ornamental dots, badge
- *   indicators, icon wells). Size still tracks the size knob.
- * - `R-IDENTITY` — the shape IS the part's identity (Avatar, brand marks).
- *   Membership is enumerated in the spec table and enforced per part.
+ *   indicators). Size still tracks the size knob. Icon wells are DEFAULT,
+ *   not R-PILL (R2e) — unless the well IS a count badge.
+ * - `R-IDENTITY` — the shape IS the part's identity (Avatar, brand marks,
+ *   Radio disc). Membership is enumerated in the spec table and enforced
+ *   per part.
  */
 export type KnobImmuneRadiusClass = "R-PILL" | "R-IDENTITY";
 
@@ -49,3 +80,171 @@ export function radiusClassProps(
 ): RadiusClassDeclaration {
   return { "data-radius-class": radiusClass, "data-radius-part": part };
 }
+
+// ── Radius resolution (DG-RAD-01..05) ─────────────────────────
+
+/**
+ * The geometry a doctrine cell may need. `h/2` cells need the part's own
+ * painted height (shorter edge); CONTAINER-CAP cells need the container's own
+ * padding at the current space stop (13/18/32 — `panelPaddingPxMap`).
+ */
+export interface RadiusClassGeometry {
+  heightPx?: number;
+  paddingPx?: number;
+}
+
+function resolveCell(
+  cell: RadiusResolutionCell,
+  geometry: RadiusClassGeometry,
+  where: string,
+): number {
+  switch (cell.kind) {
+    case "px":
+      return cell.px;
+    case "half-height": {
+      if (geometry.heightPx === undefined || geometry.heightPx <= 0) {
+        throw new Error(
+          `resolveRadiusClass: ${where} resolves to h/2 and needs geometry.heightPx — the part's own painted height (shorter edge)`,
+        );
+      }
+      return geometry.heightPx / 2;
+    }
+    case "min-token-padding": {
+      if (geometry.paddingPx === undefined || geometry.paddingPx < 0) {
+        throw new Error(
+          `resolveRadiusClass: ${where} caps at the container's own padding and needs geometry.paddingPx`,
+        );
+      }
+      return Math.min(cell.tokenPx, geometry.paddingPx);
+    }
+    case "padding": {
+      if (geometry.paddingPx === undefined || geometry.paddingPx < 0) {
+        throw new Error(
+          `resolveRadiusClass: ${where} resolves to the container's own padding and needs geometry.paddingPx`,
+        );
+      }
+      return geometry.paddingPx;
+    }
+  }
+}
+
+/**
+ * Resolve one radius-resolution class at one knob stop to px (DG-RAD-01..04).
+ *
+ * This is the CLASS layer only — the doctrine's DEFAULT resolution. Parts with
+ * a declared per-component override or a knob-immunity declaration resolve
+ * through `resolveRadiusForPart`, which layers all three.
+ *
+ * Fails loudly on anything the doctrine table cannot spell: an unknown class,
+ * an unknown stop, or an `h/2`/padding cell without its geometry. Silent
+ * defaults are how tables widen.
+ */
+export function resolveRadiusClass(
+  radiusClass: RadiusResolutionClass,
+  stop: BorderRadius,
+  geometry: RadiusClassGeometry = {},
+): number {
+  const row = RADIUS_RESOLUTION_TABLE[radiusClass];
+  if (!row) {
+    throw new Error(
+      `resolveRadiusClass: "${radiusClass}" is not a class in the DG-RAD doctrine table (docs/design-guidelines.md §13)`,
+    );
+  }
+  const cell = row[stop];
+  if (!cell) {
+    throw new Error(
+      `resolveRadiusClass: "${stop}" is not a radius stop the DG-RAD doctrine table knows`,
+    );
+  }
+  return resolveCell(cell, geometry, `${radiusClass} at ${stop}`);
+}
+
+/**
+ * Look up a part's declared per-component override (DG-RAD-05), if any.
+ * Matching is by the doctrine's component name, case-insensitive — the same
+ * contract the R-IDENTITY membership registry uses. Sweeps use this to PASS a
+ * declared override instead of reporting it as a violation.
+ */
+export function radiusOverrideFor(part: string): RadiusOverrideEntry | undefined {
+  const needle = part.trim().toLowerCase();
+  return RADIUS_OVERRIDE_TABLE.find((entry) => entry.component.toLowerCase() === needle);
+}
+
+export type ResolvedRadiusSource = (typeof RADIUS_RESOLUTION_COMPOSITION)[number];
+
+export interface ResolveRadiusForPartOptions extends RadiusClassGeometry {
+  /** the knob stop being resolved */
+  stop: BorderRadius;
+  /**
+   * the part's resolution class as doctrine assigns it — DEFAULT unless
+   * assigned otherwise (knobs-enumerated.md Part 2b / DG-RAD)
+   */
+  radiusClass?: RadiusResolutionClass;
+  /**
+   * the part name as the doctrine's override table spells it (`Checkbox`,
+   * `Radio disc`) — enables the DG-RAD-05 override lookup
+   */
+  part?: string;
+  /**
+   * the part's declared knob-immunity (`R-PILL` / `R-IDENTITY`, LC-60/D-09),
+   * if it carries one. Immunity COMPOSES above both other layers: the knob
+   * never reaches the part, so it stays round at every stop including `none`.
+   */
+  immunity?: KnobImmuneRadiusClass;
+}
+
+export interface ResolvedPartRadius {
+  px: number;
+  /** which layer resolved it: declared immunity > declared override > class */
+  source: ResolvedRadiusSource;
+  /** the class the part would resolve by, for sweeps that report both */
+  radiusClass: RadiusResolutionClass;
+  /** the recorded DG-RAD-05 reason, when an override won */
+  overrideWhy?: string;
+}
+
+/**
+ * Resolve a part's radius at a knob stop through all three doctrine layers,
+ * in doctrine order (DG-RAD-05 composition note): a declared knob-immunity
+ * wins, then a declared per-component override, then the resolution class.
+ *
+ * A declared immunity is COMPOSED with, never replaced: even at `none` the
+ * part measures h/2, because roundness is its identity, not a radius (Clay
+ * 2026-08-28 resolving R2a — badge count pill, status dots, DotIndicator
+ * marks, presence pip stay round in the square world).
+ */
+export function resolveRadiusForPart(options: ResolveRadiusForPartOptions): ResolvedPartRadius {
+  const radiusClass: RadiusResolutionClass = options.radiusClass ?? "DEFAULT";
+  const geometry: RadiusClassGeometry = {
+    heightPx: options.heightPx,
+    paddingPx: options.paddingPx,
+  };
+  if (options.immunity) {
+    if (options.heightPx === undefined || options.heightPx <= 0) {
+      throw new Error(
+        `resolveRadiusForPart: a declared ${options.immunity} part is round at every stop (h/2) and needs geometry.heightPx`,
+      );
+    }
+    return { px: options.heightPx / 2, source: "immunity", radiusClass };
+  }
+  const override = options.part === undefined ? undefined : radiusOverrideFor(options.part);
+  if (override) {
+    const cell = override.cells[options.stop];
+    if (!cell) {
+      throw new Error(
+        `resolveRadiusForPart: "${options.stop}" is not a radius stop the DG-RAD override table knows`,
+      );
+    }
+    return {
+      px: resolveCell(cell, geometry, `override ${override.component} at ${options.stop}`),
+      source: "override",
+      radiusClass,
+      overrideWhy: override.why,
+    };
+  }
+  return {
+    px: resolveRadiusClass(radiusClass, options.stop, geometry),
+    source: "class",
+    radiusClass,
+  };
+}