@multiplatform.one/theme 7.7.6 → 7.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.7.6",
+  "version": "7.8.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -53,8 +53,8 @@
     "@tamagui/toast": "2.7.6",
     "@tamagui/web": "2.7.6",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/platform": "7.7.6",
-    "@multiplatform.one/store": "7.7.6"
+    "@multiplatform.one/store": "7.8.0",
+    "@multiplatform.one/platform": "7.8.0"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.7.6",
@@ -68,8 +68,8 @@
     "tamagui": "2.7.6",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "7.7.6",
-    "@multiplatform.one/test-utils": "7.7.6"
+    "@multiplatform.one/test-utils": "7.8.0",
+    "@multiplatform.one/config": "7.8.0"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",

package/src/audit/constraintAudit.spec.ts

@@ -0,0 +1,157 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { defaultConfig } from "@tamagui/config/v5";
+import { defaultHeadingFont } from "../theme/defaults/fonts";
+import { defaultKnobs } from "../theme/knobs";
+import { resolveKnobs } from "../theme/resolveKnobs";
+import { GAP_KNOB, GAP_LG_KNOB, runConstraintAudit } from "./constraintAudit";
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+// Deliberately loses module scope, like Playwright page.evaluate.
+const audit = new Function(
+  `return (${runConstraintAudit.toString()})()`,
+) as typeof runConstraintAudit;
+
+function specimen(style: string, attrs: Record<string, string> = {}) {
+  const el = document.createElement("div");
+  el.id = "specimen";
+  el.style.cssText = style;
+  for (const [key, value] of Object.entries(attrs)) el.setAttribute(key, value);
+  document.body.append(el);
+  return el;
+}
+
+function measured() {
+  return audit().elements.find((el) => el.id === "specimen");
+}
+
+function card(radius: string, space: string, tier = "content") {
+  return {
+    "data-constraint-container": "Card",
+    "data-tier": tier,
+    "data-radius-knob": radius,
+    "data-space-knob": space,
+  };
+}
+
+describe("Card container cap, independently measured against canonical stops", () => {
+  for (const tier of ["content", "elevated"]) {
+    for (const [radius, stop] of Object.entries({
+      none: 0,
+      small: 5,
+      medium: 9,
+      large: 16,
+      full: 50,
+    })) {
+      for (const [space, inset] of Object.entries({ small: 13, medium: 18, large: 32 })) {
+        it(`${tier}/${radius}/${space} accepts all four capped corners`, () => {
+          specimen(
+            `border-radius:${Math.min(stop, inset)}px;padding:${inset}px`,
+            card(radius, space, tier),
+          );
+          expect(measured()?.violations).toEqual([]);
+          expect(measured()?.paddingTop?.value).toBe(inset);
+        });
+      }
+    }
+  }
+
+  it.each([
+    ["unrelated 13px", "border-radius:13px;padding:13px", {}],
+    [
+      "tier alone is not Card provenance",
+      "border-radius:13px;padding:13px",
+      { "data-tier": "content" },
+    ],
+    ["16 exceeds 13 inset", "border-radius:16px;padding:13px", card("large", "small")],
+    ["wrong last corner", "border-radius:13px 13px 13px 9px;padding:13px", card("full", "small")],
+    ["nonzero at none", "border-radius:5px;padding:13px", card("none", "small")],
+    ["arbitrary matching inset", "border-radius:14px;padding:14px", card("full", "small")],
+    ["wrong canonical inset", "border-radius:18px;padding:18px", card("full", "small")],
+    ["missing inset", "border-radius:0;padding:0", card("none", "small")],
+    [
+      "wrong individual inset",
+      "border-radius:13px;padding:13px 18px 13px 13px",
+      card("full", "small"),
+    ],
+    ["percent radius cannot bypass cap", "border-radius:50%;padding:13px", card("full", "small")],
+    [
+      "elliptical corner cannot bypass cap",
+      "border-radius:13px / 16px;padding:13px",
+      card("full", "small"),
+    ],
+  ])("rejects %s", (_label, style, attrs) => {
+    specimen(style, attrs);
+    expect(measured()?.violations.length).toBeGreaterThan(0);
+  });
+
+  it("leaves ordinary control radius rules intact", () => {
+    specimen("border-radius:16px;padding:13px");
+    expect(measured()?.violations).toEqual([]);
+  });
+
+  it.each([
+    "border-top-left-radius",
+    "border-top-right-radius",
+    "border-bottom-right-radius",
+    "border-bottom-left-radius",
+  ])("rejects a wrong %s even when every radius is on the generic scale", (corner) => {
+    const el = specimen("border-radius:9px;padding:13px", card("medium", "small"));
+    el.style.setProperty(corner, "5px");
+    expect(measured()?.borderRadius?.offScale).toBe(true);
+    expect(measured()?.violations).toHaveLength(1);
+  });
+});
+
+describe("canonical gapLg parity in the serialized audit", () => {
+  for (const space of ["small", "medium", "large"] as const) {
+    it(space, () => {
+      const token = resolveKnobs({ ...defaultKnobs, space }).knobProps.gapLg.gap;
+      const px = defaultConfig.tokens.space[token as keyof typeof defaultConfig.tokens.space];
+      expect(GAP_LG_KNOB[space]).toBe(px);
+      const gapToken = resolveKnobs({ ...defaultKnobs, space }).knobProps.gap.gap;
+      const gapPx = defaultConfig.tokens.space[gapToken as keyof typeof defaultConfig.tokens.space];
+      expect(GAP_KNOB[space]).toBe(gapPx);
+      specimen(`row-gap:${px}px;column-gap:${gapPx}px`);
+      expect(measured()?.rowGap?.offScale).toBe(false);
+      expect(measured()?.columnGap?.offScale).toBe(false);
+    });
+  }
+  it.each([22, 25, 31, 33])("rejects non-recipe gap %i", (gap) => {
+    specimen(`row-gap:${gap}px`);
+    expect(measured()?.rowGap?.offScale).toBe(true);
+  });
+});
+
+describe("font weight provenance", () => {
+  it("pins the configured heading source behind the self-contained whitelist", () => {
+    expect([...new Set(Object.values(defaultHeadingFont.weight).map(Number))].sort()).toEqual([
+      600, 700, 800,
+    ]);
+  });
+  it.each([600, 800])("accepts configured heading weight %i as unitless", (weight) => {
+    expect(Object.values(defaultConfig.fonts.heading.weight)).toContain(String(weight));
+    specimen(`font-weight:${weight}`, { class: "font_heading" });
+    expect(measured()?.fontWeight).toMatchObject({ value: weight, unit: "", offScale: false });
+    expect(measured()?.fontWeight?.knob).toContain("configured heading");
+  });
+  it.each([500, 650, 900])("rejects unconfigured weight %i", (weight) => {
+    specimen(`font-weight:${weight}`, { class: "font_heading" });
+    expect(measured()?.fontWeight?.offScale).toBe(true);
+    expect(measured()?.violations.join(" ")).not.toContain(`${weight}px`);
+  });
+  it("does not grant arbitrary elements heading weights", () => {
+    specimen("font-weight:800");
+    expect(measured()?.fontWeight?.offScale).toBe(true);
+  });
+  it.each([
+    ["regular", 700],
+    ["bold", 800],
+    ["bold", 400],
+  ])("checks explicit %s recipe against %i even when configured", (knob, weight) => {
+    specimen(`font-weight:${weight}`, { class: "font_heading", "data-font-weight-knob": knob });
+    expect(measured()?.fontWeight?.offScale).toBe(true);
+  });
+});

package/src/audit/constraintAudit.ts

@@ -27,6 +27,8 @@ export interface TextPropertyAudit {
 export interface ElementAudit {
   /** Human-readable element descriptor */
   label: string;
+  /** Stable DOM position within the audited surface, distinct for sibling controls. */
+  key?: string;
   /** Tag name */
   tag: string;
   /** id attribute if present */
@@ -35,6 +37,10 @@ export interface ElementAudit {
   classes: string[];
   /** Audited properties (only populated when value is non-default/non-zero) */
   borderRadius?: PropertyAudit;
+  borderTopLeftRadius?: PropertyAudit;
+  borderTopRightRadius?: PropertyAudit;
+  borderBottomRightRadius?: PropertyAudit;
+  borderBottomLeftRadius?: PropertyAudit;
   borderWidth?: PropertyAudit;
   gap?: PropertyAudit;
   rowGap?: PropertyAudit;
@@ -154,22 +160,22 @@ const BORDER_WIDTH_KNOB: Record<string, number> = {
 
 /**
  * Gap (inner spacing) knob → pixel value
- * Source: gapMap in resolveKnobs.ts ($2, $3, $4 space tokens)
+ * Source: gapMap in resolveKnobs.ts ($2, $4, $5 space tokens)
  */
-const GAP_KNOB: Record<string, number> = {
+export const GAP_KNOB: Record<string, number> = {
   small: SPACE_TOKENS[2], // 7px
-  medium: SPACE_TOKENS[3], // 13px
-  large: SPACE_TOKENS[4], // 18px
+  medium: SPACE_TOKENS[4], // 18px
+  large: SPACE_TOKENS[5], // 24px
 };
 
 /**
  * Gap large (gapLg) knob → pixel value
- * Source: gapLgMap in resolveKnobs.ts ($3, $4, $5 space tokens)
+ * Source: gapLgMap in resolveKnobs.ts ($3, $5, $6 space tokens)
  */
-const GAP_LG_KNOB: Record<string, number> = {
+export const GAP_LG_KNOB: Record<string, number> = {
   small: SPACE_TOKENS[3], // 13px
-  medium: SPACE_TOKENS[4], // 18px
-  large: SPACE_TOKENS[5], // 24px
+  medium: SPACE_TOKENS[5], // 24px
+  large: SPACE_TOKENS[6], // 32px
 };
 
 /**
@@ -327,7 +333,7 @@ function reverseMapFontFamily(computed: string): { knob: string; offScale: boole
  *
  * Returns an AuditReport object describing all structural CSS violations.
  */
-export function runConstraintAudit(): AuditReport {
+export function runConstraintAudit(rootSelector?: string): AuditReport {
   // ── Inline token definitions (must be self-contained for page.evaluate) ──
 
   const _RADIUS_TOKENS: Record<number, number> = {
@@ -369,13 +375,13 @@ export function runConstraintAudit(): AuditReport {
   };
   const _GAP_KNOB: Record<string, number> = {
     small: 7,
-    medium: 13,
-    large: 18,
+    medium: 18,
+    large: 24,
   };
   const _GAP_LG_KNOB: Record<string, number> = {
     small: 13,
-    medium: 18,
-    large: 24,
+    medium: 24,
+    large: 32,
   };
   const _PANEL_PADDING_KNOB: Record<string, number> = {
     small: 13,
@@ -576,6 +582,36 @@ export function runConstraintAudit(): AuditReport {
     return `${tag}${id}${cls}${role}${testId}` || tag;
   }
 
+  function elementKey(el: Element, scope: Element | Document): string {
+    const path: string[] = [];
+    for (let node: Element | null = el; node; node = node.parentElement) {
+      const siblings = node.parentElement
+        ? Array.from(node.parentElement.children).filter(
+            (sibling) => sibling.tagName === node.tagName,
+          )
+        : [node];
+      path.unshift(`${node.tagName.toLowerCase()}:nth-of-type(${siblings.indexOf(node) + 1})`);
+      if (node === scope) break;
+    }
+    return path.join(" > ");
+  }
+
+  function isPainted(el: Element): boolean {
+    const ownStyle = getComputedStyle(el);
+    // Visibility can be restored by a child, unlike display or opacity.
+    if (ownStyle.visibility === "hidden" || ownStyle.visibility === "collapse") return false;
+    for (let node: Element | null = el; node; node = node.parentElement) {
+      const style = getComputedStyle(node);
+      if (
+        style.display === "none" ||
+        (node !== el && style.contentVisibility === "hidden") ||
+        Number.parseFloat(style.opacity) === 0
+      )
+        return false;
+    }
+    return true;
+  }
+
   // ── Helper: audit a single numeric property ───────────────────────────────
 
   function auditProp(
@@ -653,14 +689,19 @@ export function runConstraintAudit(): AuditReport {
   const DEVTOOLS_SELECTORS = ["#tanstack_devtools", "[data-testid=tanstack_devtools]"];
   const devtoolsRoots = DEVTOOLS_SELECTORS.flatMap((s) => Array.from(document.querySelectorAll(s)));
 
-  const allElements = Array.from(document.querySelectorAll("*"));
+  const scope = rootSelector ? document.querySelector(rootSelector) : document;
+  if (!scope) throw new Error(`Constraint audit scope not found: ${rootSelector}`);
+  const allElements = [
+    ...(scope instanceof Element ? [scope] : []),
+    ...Array.from(scope.querySelectorAll("*")),
+  ];
   const candidates = allElements.filter((el) => {
     const tag = el.tagName.toLowerCase();
     if (SKIP_TAGS.has(tag)) return false;
     // Skip SVG internals
     if (el.namespaceURI === "http://www.w3.org/2000/svg" && tag !== "svg") return false;
-    // Skip hidden elements — display:none means the style has no visual impact
-    if ((el as HTMLElement).style?.display === "none") return false;
+    // A hidden error panel can carry arbitrary framework styles without painting.
+    if (!isPainted(el)) return false;
     // Skip third-party devtools overlays
     if (devtoolsRoots.some((root) => root.contains(el))) return false;
     return true;
@@ -677,6 +718,7 @@ export function runConstraintAudit(): AuditReport {
 
     const entry: ElementAudit = {
       label: elementLabel(el),
+      key: elementKey(el, scope),
       tag,
       id: el.id || "",
       classes: Array.from(el.classList)
@@ -687,11 +729,73 @@ export function runConstraintAudit(): AuditReport {
 
     let hasAnyProp = false;
 
-    // ── Border Radius ───────────────────────────────────────────────────────
-    // Skip percentage-based border-radius (used for circles, not knob system)
-    if (!isPercentageBorderRadius(el)) {
-      const brRaw = style.borderTopLeftRadius || style.borderRadius;
-      const br = parsePx(brRaw);
+    // Axiom 1 / DG-RAD-04: only the documented padded Card tiers own this
+    // cap. Provenance is declarative; every inset and corner is still measured.
+    const cardContainer =
+      el.getAttribute("data-constraint-container") === "Card" &&
+      ["content", "elevated"].includes(el.getAttribute("data-tier") ?? "");
+    if (cardContainer) {
+      const radiusKnob = el.getAttribute("data-radius-knob") ?? "";
+      const spaceKnob = el.getAttribute("data-space-knob") ?? "";
+      const radiusStop = Object.hasOwn(_BORDER_RADIUS_KNOB, radiusKnob)
+        ? _BORDER_RADIUS_KNOB[radiusKnob]
+        : undefined;
+      const inset = Object.hasOwn(_PANEL_PADDING_KNOB, spaceKnob)
+        ? _PANEL_PADDING_KNOB[spaceKnob]
+        : undefined;
+      const paddingSides = ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft"] as const;
+      const measuredInsets = paddingSides.map((prop) => parsePx(style[prop]));
+      for (const [index, prop] of paddingSides.entries()) {
+        const value = measuredInsets[index];
+        const offScale = inset === undefined || value !== inset;
+        entry[prop] = {
+          value: value ?? 0,
+          unit: "px",
+          knob: `Card panelPadding:${spaceKnob}`,
+          offScale,
+        };
+        if (offScale)
+          entry.violations.push(
+            `${prop}: ${style[prop]} does not match Card panelPadding:${spaceKnob} (${inset ?? "unknown"}px)`,
+          );
+      }
+      const expected =
+        radiusStop === undefined || inset === undefined || measuredInsets.some((v) => v === null)
+          ? undefined
+          : Math.min(radiusStop, inset, ...(measuredInsets as number[]));
+      const corners = [
+        "borderTopLeftRadius",
+        "borderTopRightRadius",
+        "borderBottomRightRadius",
+        "borderBottomLeftRadius",
+      ] as const;
+      for (const prop of corners) {
+        const raw = style[prop];
+        // A corner may have two elliptical axes. Percentages are not px caps.
+        const axes = raw.trim().split(/\s+/);
+        const offScale =
+          expected === undefined ||
+          axes.some((axis) => !/^\d+(?:\.\d+)?(?:px)?$/.test(axis) || parsePx(axis) !== expected);
+        const result = {
+          value: parsePx(raw) ?? 0,
+          unit: "px",
+          knob: `Card min(radius:${radiusKnob}, panelPadding:${spaceKnob})`,
+          offScale,
+        };
+        entry[prop] = result;
+        if (offScale)
+          entry.violations.push(
+            `${prop}: ${raw} does not match Card cap (${expected ?? "unknown"}px)`,
+          );
+      }
+      entry.borderRadius = {
+        ...entry.borderTopLeftRadius!,
+        offScale: corners.some((prop) => entry[prop]?.offScale),
+      };
+      hasAnyProp = true;
+    } else if (!isPercentageBorderRadius(el)) {
+      // Ordinary controls and identity recipes retain their existing scales.
+      const br = parsePx(style.borderTopLeftRadius || style.borderRadius);
       if (br !== null && br > 0) {
         entry.borderRadius = auditProp(
           br,
@@ -735,7 +839,7 @@ export function runConstraintAudit(): AuditReport {
     // Only check padding on elements that look like surfaces (have border-radius
     // or border-width already audited). Padding on all elements creates too many
     // false positives from browser defaults and third-party components.
-    if (entry.borderRadius || entry.borderWidth) {
+    if (!cardContainer && (entry.borderRadius || entry.borderWidth)) {
       const sides = [
         ["paddingTop", style.paddingTop],
         ["paddingRight", style.paddingRight],
@@ -757,19 +861,34 @@ export function runConstraintAudit(): AuditReport {
 
     // ── Font Weight ─────────────────────────────────────────────────────────
     const fw = parsePx(style.fontWeight);
-    if (fw !== null && fw !== 400) {
-      // Only flag non-regular weights that aren't in our valid set
-      const result = auditProp(
-        fw,
-        _VALID_FONT_WEIGHT,
-        _reverseFontWeight,
-        "fontWeight",
-        entry.violations,
-      );
-      if (result) {
-        entry.fontWeight = result;
-        hasAnyProp = true;
-      }
+    const weightKnob = el.getAttribute("data-font-weight-knob");
+    if (fw !== null && (fw !== 400 || weightKnob !== null)) {
+      // defaults/fonts.ts takes heading.weight from @tamagui/config/v5:
+      // $0–$5 = 600, $6–$8 = 700, $9+ = 800. FontKnobStyles preserves
+      // font_heading while changing its family. These are typography defaults,
+      // not alternatives to an explicitly declared regular/bold recipe.
+      const configuredHeading =
+        el.classList.contains("font_heading") && [600, 700, 800].includes(fw);
+      const expected =
+        weightKnob !== null && ["regular", "bold"].includes(weightKnob)
+          ? _FONT_WEIGHT_KNOB[weightKnob]
+          : undefined;
+      const offScale =
+        weightKnob !== null
+          ? expected === undefined || fw !== expected
+          : !_VALID_FONT_WEIGHT.has(fw) && !configuredHeading;
+      const knob =
+        weightKnob !== null
+          ? `fontWeight:${weightKnob}`
+          : configuredHeading
+            ? "configured heading (@tamagui/config/v5)"
+            : _reverseFontWeight(fw);
+      entry.fontWeight = { value: fw, unit: "", knob, offScale };
+      if (offScale)
+        entry.violations.push(
+          `fontWeight: ${fw} does not match ${weightKnob !== null ? knob : "a configured typography weight"}`,
+        );
+      hasAnyProp = true;
     }
 
     // ── Font Family ──────────────────────────────────────────────────────────

package/src/audit/constraintScope.spec.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { runConstraintAudit } from "./constraintAudit";
+
+const audit = new Function("scope", `return (${runConstraintAudit.toString()})(scope)`) as (
+  scope?: string,
+) => ReturnType<typeof runConstraintAudit>;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("constraint audit scope and painted visibility", () => {
+  it("audits the requested surface while keeping the document-wide default", () => {
+    document.body.innerHTML = `<div id="outside" style="border-radius:14px"></div><main id="story"><button id="inside" style="border-radius:15px">Inside</button></main>`;
+    expect(audit("#story").violations.map((entry) => entry.id)).toEqual(["inside"]);
+    expect(audit().violations.map((entry) => entry.id)).toEqual(["outside", "inside"]);
+  });
+
+  it("rejects a missing requested surface instead of returning a clean report", () => {
+    expect(() => audit("#missing")).toThrow(/scope/i);
+  });
+
+  it.each(["display:none", "visibility:hidden", "opacity:0"])(
+    "ignores unpainted descendants under %s and reports them when shown",
+    (style) => {
+      document.body.innerHTML = `<main id="story"><div id="hidden" style="${style}"><button id="bad" style="border-radius:15px">Hidden error chrome</button></div></main>`;
+      expect(audit("#story").violations).toEqual([]);
+      document.querySelector("#hidden")!.removeAttribute("style");
+      expect(audit("#story").violations.map((entry) => entry.id)).toEqual(["bad"]);
+    },
+  );
+
+  it("keeps painted children that explicitly override inherited visibility", () => {
+    document.body.innerHTML = `<main id="story" style="visibility:hidden"><button id="shown" style="visibility:visible;border-radius:15px">Visible</button></main>`;
+    expect(audit("#story").violations.map((entry) => entry.id)).toEqual(["shown"]);
+  });
+
+  it("retains distinct stable paths for otherwise identical failing controls", () => {
+    document.body.innerHTML = `<main id="story"><button style="border-radius:15px">Same</button><button style="border-radius:15px">Same</button></main>`;
+    const first = audit("#story").violations;
+    expect(first).toHaveLength(2);
+    expect(first[0].key).toBeTruthy();
+    expect(first[1].key).not.toBe(first[0].key);
+    expect(audit("#story").violations.map((entry) => entry.key)).toEqual(
+      first.map((entry) => entry.key),
+    );
+  });
+});

package/src/audit/index.ts

@@ -9,9 +9,21 @@ export { runConstraintAudit } from "./constraintAudit";
 export type { AuditDiff, ElementDiff, PropertyDiff } from "./diffReport";
 export { diffAuditReports, formatAuditReport } from "./diffReport";
 export type {
+  ChartKind,
+  ChartProofResult,
+  ChartProofViolation,
+  ChartUnmeasurableReason,
+  MatrixChartPaint,
+  MatrixChartSample,
   GeometryDiff,
   GeometryMove,
+  IconContrastResult,
+  IconContrastViolation,
+  IconExclusion,
+  IconUnmeasurableReason,
+  IconUnverified,
   MatrixElementGeometry,
+  MatrixIconSample,
   MatrixRect,
   MatrixSnapshot,
   MatrixTextSample,
@@ -25,5 +37,9 @@ export {
   captureMatrixSnapshot,
   diffGeometry,
   evaluateNoBreakage,
+  evaluateIconContrast,
+  evaluateChartProof,
+  chartProofSignatures,
+  iconContrastSignatures,
   evaluateTextContrast,
 } from "./themeMatrix";