@multiplatform.one/components 7.5.0 → 7.6.1

package/src/Text.spec.tsx

@@ -12,19 +12,18 @@
  * family. Between knob flips and against explicit-prop renders of the
  * same value. Hashed class names are compared by identity only.
  *
- * WEB arm: the default module graph (isWeb true).
- * NATIVE arm: `@multiplatform.one/platform` mocked to isWeb:false on a fresh
- * module graph (the resolveKnobs.spec.ts elevation-native pattern), with
- * Preset/render/Text all imported from that same graph. FontKnobStyles'
- * CSS-variable rescue is absent in BOTH arms (renderWithProviders mounts no
- * theme provider), so a flip that reaches the node proves the PROPS channel
- * — the only channel native has.
+ * This file is the WEB arm (the default module graph, isWeb true). The NATIVE
+ * arm is ./Text.native.spec.tsx, a separate FILE so that a file-scoped
+ * `vi.mock` gives it one coherent module graph. FontKnobStyles' CSS-variable
+ * rescue is absent in BOTH arms (renderWithProviders mounts no theme
+ * provider), so a flip that reaches the node proves the PROPS channel — the
+ * only channel native has.
  */
 import { cleanup, screen } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Preset } from "@multiplatform.one/theme";
 import { XStack } from "tamagui";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { Text } from "./Text";
 
 afterEach(cleanup);
@@ -182,65 +181,8 @@ describe("house Text — fontWeight and bodyFont reach the text node", () => {
   });
 });
 
-describe("house Text — NATIVE environment (isWeb false, fresh module graph)", () => {
-  it("textAccent and fontWeight flips still reach the text node", async () => {
-    vi.resetModules();
-    vi.doMock("@multiplatform.one/platform", async (importOriginal) => ({
-      ...(await importOriginal<typeof import("@multiplatform.one/platform")>()),
-      isWeb: false,
-      isNative: true,
-    }));
-    try {
-      // Everything must come from the SAME fresh graph: a Preset from the
-      // old graph would provide a context the fresh Text never reads.
-      const [{ Text: NativeText }, { Preset: NativePreset }, testUtils, testingLibrary] =
-        await Promise.all([
-          import("./Text"),
-          import("@multiplatform.one/theme"),
-          import("@multiplatform.one/test-utils"),
-          import("@testing-library/react"),
-        ]);
-
-      const renderNative = (node: React.ReactElement, prefixes: string[]): string[] => {
-        testUtils.renderWithProviders(node);
-        const el = testingLibrary.screen.getByText(LABEL);
-        const classes = classesByPrefix(el, prefixes);
-        testingLibrary.cleanup();
-        return classes;
-      };
-
-      const high = renderNative(
-        <NativePreset overrides={{ textAccent: "high" }}>
-          <NativeText>{LABEL}</NativeText>
-        </NativePreset>,
-        ["_col-"],
-      );
-      const low = renderNative(
-        <NativePreset overrides={{ textAccent: "low" }}>
-          <NativeText>{LABEL}</NativeText>
-        </NativePreset>,
-        ["_col-"],
-      );
-      expect(high).not.toHaveLength(0);
-      expect(high).not.toEqual(low);
-
-      const regular = renderNative(
-        <NativePreset overrides={{ fontWeight: "regular" }}>
-          <NativeText>{LABEL}</NativeText>
-        </NativePreset>,
-        ["_fow-"],
-      );
-      const bold = renderNative(
-        <NativePreset overrides={{ fontWeight: "bold" }}>
-          <NativeText>{LABEL}</NativeText>
-        </NativePreset>,
-        ["_fow-"],
-      );
-      expect(regular).not.toHaveLength(0);
-      expect(regular).not.toEqual(bold);
-    } finally {
-      vi.doUnmock("@multiplatform.one/platform");
-      vi.resetModules();
-    }
-  });
-});
+// The NATIVE arm lives in ./Text.native.spec.tsx. It used to sit here as a
+// `vi.resetModules()` + dynamic-import block, but that returned a SPLIT module
+// graph — a fresh `renderWithProviders` over a stale `useResolvedKnobs` — and
+// threw "Missing theme." instead of measuring anything. A file-scoped
+// `vi.mock` in its own spec file is one coherent graph.

package/src/Tooltip/tooltipGapContract.spec.ts

@@ -0,0 +1,54 @@
+/**
+ * MPO-38 AC-7, the source half: Tooltip owns no gap constant of its own.
+ *
+ * The runtime value is asserted where it lives — `layoutTokens.spec.ts` pins
+ * `OVERLAY_ANCHOR_GAP` at 4. Asserting that number again from a Tooltip spec
+ * proves nothing about Tooltip: it passes just as happily if this component
+ * goes back to a hardcoded `offset={4}`, which is exactly the drift the AC
+ * was written to close.
+ *
+ * So this is the source half, in the shape of `panelWidthContract.spec.ts`.
+ * A Tooltip is a FREE overlay — no trigger to attach to — so it is one of the
+ * few overlays `OVERLAY_ANCHOR_GAP` still governs after the cover ruling
+ * (`OVERLAY_ATTACH_GAP = 0`). It must READ that token rather than restate its
+ * value under a second name (LC-16 ONE-IMPLEMENTATION).
+ *
+ * Both twins are checked. The web/native split is where a duplicate constant
+ * survives longest: fixing one file and leaving the other still renders the
+ * right gap on the platform anyone happened to look at.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const tooltipDir = dirname(fileURLToPath(import.meta.url));
+
+/** The web twin, the native twin, and the module they share. */
+const tooltipSources = ["index.tsx", "index.native.tsx", "tooltipShared.tsx"];
+
+function read(relative: string): string {
+  return readFileSync(resolve(tooltipDir, relative), "utf8");
+}
+
+describe("Tooltip gap contract (MPO-38 AC-7)", () => {
+  it.each(tooltipSources)("%s declares no gap constant of its own", (relative) => {
+    // Named for the constant this AC deleted, but the assertion is the rule,
+    // not the name: any local OFFSET/GAP constant is the same drift again.
+    expect(read(relative)).not.toMatch(/\b(?:const|let|var)\s+\w*(?:OFFSET|GAP)\w*\s*=/);
+  });
+
+  it.each(["index.tsx", "index.native.tsx"])(
+    "%s positions the bubble with the shared FREE-overlay token",
+    (relative) => {
+      const source = read(relative);
+      expect(source).toMatch(
+        /import\s*\{[^}]*\bOVERLAY_ANCHOR_GAP\b[^}]*\}\s*from\s*"@multiplatform\.one\/theme"/s,
+      );
+      expect(source).toContain("offset={OVERLAY_ANCHOR_GAP}");
+      // A literal offset is the regression: it renders the same 4px today and
+      // silently stops tracking the token the moment the house rule moves.
+      expect(source).not.toMatch(/offset=\{\s*\d/);
+    },
+  );
+});

package/src/Wizard/Wizard.spec.tsx

@@ -1,8 +1,9 @@
 import { Form, Input, Switch, useFormContext } from "@multiplatform.one/forms";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { __resetDevWarnSeen } from "@multiplatform.one/theme";
 import { act, fireEvent } from "@testing-library/react";
 import { useEffect } from "react";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { Wizard, useWizard, type WizardFormLike, type WizardStep } from "./index";
 
 const STEPS: WizardStep[] = [
@@ -214,6 +215,27 @@ describe("Wizard LC-63 / DG-VAL", () => {
   });
 });
 
+describe("Wizard LC-57 guardrail-clean at rest", () => {
+  it("a ready wizard at rest emits zero [theme] guardrail warnings", async () => {
+    __resetDevWarnSeen();
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    try {
+      renderWizard();
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
+      const themeWarns = [...warn.mock.calls, ...error.mock.calls]
+        .map((args) => String(args[0]))
+        .filter((msg) => msg.startsWith("[theme]"));
+      expect(themeWarns).toEqual([]);
+    } finally {
+      warn.mockRestore();
+      error.mockRestore();
+    }
+  });
+});
+
 describe("Wizard states", () => {
   it("draws loading, empty, and error shells", () => {
     const loading = renderWithProviders(

package/src/Wizard/index.tsx

@@ -521,17 +521,10 @@ function WizardRoot({
         {...props}
       >
         <YStack data-wizard-rail="" width="100%">
-          {/*
-           * MPO-81: no `labels` prop here. ProgressStepsProps does not declare
-           * one and ProgressSteps reads no such prop, so passing it was inert
-           * at runtime and failed the build with TS2322. `hideLabels` still
-           * drives the per-step caption below, which is where it has always
-           * had a real effect. Re-add the pass in the same change that gives
-           * ProgressSteps a labels prop it actually honours.
-           */}
           <ProgressSteps
             steps={railSteps}
             current={current}
+            labels={hideLabels ? "hidden" : "visible"}
             compact={compact}
             linear
             onStepChange={(index) => {

package/src/code/CodeBlock/CodeBlock.spec.tsx

@@ -85,19 +85,19 @@ function greet() {
 describe("CodeBlock", () => {
   it("keeps the copy action reachable at the 44px press floor", () => {
     renderWithProviders(<CodeBlock>const x = 1;</CodeBlock>);
-    const button = screen.getByLabelText("Copy code to clipboard");
+    const button = screen.getByLabelText("Copy to clipboard");
     expect(button).toBeTruthy();
     expect(button.getAttribute("data-press-min")).toBe(String(MIN_PRESS_TARGET));
+    // Default knob: the glyph-ring end-cap square itself meets the floor
+    // (44). Smaller size steps keep the floor by spilling hitSlop instead
+    // (CodeBlock.copy.spec covers the 36/52 cap geometry).
+    expect(Number(button.getAttribute("data-end-cap"))).toBeGreaterThanOrEqual(MIN_PRESS_TARGET);
     const style = getComputedStyle(button);
     expect(style.display).not.toBe("none");
-    const minWidth = Number.parseFloat(style.minWidth);
-    const minHeight = Number.parseFloat(style.minHeight);
-    if (!Number.isNaN(minWidth)) expect(minWidth).toBeGreaterThanOrEqual(MIN_PRESS_TARGET);
-    if (!Number.isNaN(minHeight)) expect(minHeight).toBeGreaterThanOrEqual(MIN_PRESS_TARGET);
   });
 
   it("hides the copy action only when disableCopy is set", () => {
     renderWithProviders(<CodeBlock disableCopy>const x = 1;</CodeBlock>);
-    expect(screen.queryByLabelText("Copy code to clipboard")).toBeNull();
+    expect(screen.queryByLabelText("Copy to clipboard")).toBeNull();
   });
 });

package/src/code/CodeBlock/index.tsx

@@ -7,21 +7,28 @@
  */
 
 import { LinearGradient } from "@tamagui/linear-gradient";
-import { CheckCircleIcon, ClipboardIcon, WarningCircleIcon } from "@phosphor-icons/react";
-import { MIN_PRESS_TARGET, useResolvedKnobs } from "@multiplatform.one/theme";
+import { ClipboardIcon } from "@phosphor-icons/react";
+import {
+  MIN_PRESS_TARGET,
+  isTouchSurface,
+  pressTargetHitSlop,
+  sizeRecipeForToken,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import { useEffect, useRef, useState } from "react";
 import { useTranslation } from "../../shared/i18n";
 import type { TamaguiElement } from "tamagui";
 import { ScrollView } from "tamagui";
-import { Button, zIndex } from "@multiplatform.one/forms";
-import { Spacer, TooltipSimple, XStack, YStack } from "tamagui";
+import { Button, Input, zIndex } from "@multiplatform.one/forms";
+import { Spacer, XStack, YStack } from "tamagui";
 import { settleMs } from "../../AnimateHeight";
 import { ErrorBoundary } from "../../ErrorBoundary";
+import { NotifyRegion } from "../../feedback/NotifyHost";
+import { copyAndNotify } from "../../feedback/copy";
 import { Code } from "../Code";
 import { HighlightedCode } from "../HighlightedCode";
 import { useShikiTokens } from "../Highlighter";
 import { Pre } from "../Pre";
-import { useClipboard } from "../../hooks/useClipboard";
 
 /** Visible lines before the "show more" clamp (content constraint, LC-18). */
 const VISIBLE_LINES = 22;
@@ -111,7 +118,14 @@ export function CodeBlock({
     }, settleMs(transition));
   };
   const clamped = isCutoff || expandTarget != null;
-  const { hasCopied, hasCopyFailed, onCopy } = useClipboard(codeText);
+  // Copy is the same Input.Button glyph-ring cap the CopyField/Password
+  // slot uses (LC-16); confirm is notify() and the glyph does not flip
+  // (DG-FB-01 — the D-copyfield verdict replaces TooltipSimple + icon-swap).
+  const showCopy = Boolean(codeText) && !disableCopy;
+  const activateCopy = () => {
+    void copyAndNotify(codeText);
+  };
+  const capSquare = sizeRecipeForToken(String(codeSize), { touch: isTouchSurface() }).height;
 
   return (
     <YStack position="relative" marginBottom="$4">
@@ -156,6 +170,7 @@ export function CodeBlock({
                 borderWidth={0}
                 {...knobProps.panelPadding}
                 size={codeSize}
+                data-register="code"
               >
                 <HighlightedCode
                   tokens={tokens}
@@ -168,33 +183,35 @@ export function CodeBlock({
               </Code>
             </ScrollView>
           </Pre>
-          {!disableCopy && (
-            <XStack position="absolute" top="$3" insetInlineEnd="$3">
-              <TooltipSimple
-                label={
-                  hasCopied
-                    ? t("Copied")
-                    : hasCopyFailed
-                      ? t("Copy failed")
-                      : t("Copy to clipboard")
+          {showCopy && (
+            <XStack position="absolute" top={0} insetInlineEnd={0} zIndex={zIndex.localTop}>
+              <Input.Button
+                glyphRing
+                size={codeSize}
+                type="button"
+                aria-label="Copy to clipboard"
+                data-press-min={MIN_PRESS_TARGET}
+                hitSlop={capSquare < MIN_PRESS_TARGET ? pressTargetHitSlop(capSquare) : undefined}
+                onPress={activateCopy}
+                onKeyDown={
+                  ((e: KeyboardEvent) => {
+                    if (e.key === "Enter" || e.key === " ") {
+                      e.preventDefault();
+                      e.stopPropagation();
+                      activateCopy();
+                    }
+                  }) as unknown as () => void
                 }
               >
-                <Button
-                  aria-label={t("Copy code to clipboard")}
-                  size={codeSize}
-                  minWidth={MIN_PRESS_TARGET}
-                  minHeight={MIN_PRESS_TARGET}
-                  data-press-min={MIN_PRESS_TARGET}
-                  icon={
-                    hasCopied ? CheckCircleIcon : hasCopyFailed ? WarningCircleIcon : ClipboardIcon
-                  }
-                  onPress={onCopy}
-                />
-              </TooltipSimple>
+                <Input.Icon aria-hidden>
+                  <ClipboardIcon />
+                </Input.Icon>
+              </Input.Button>
             </XStack>
           )}
         </YStack>
       </ErrorBoundary>
+      <NotifyRegion scope="field" compact />
     </YStack>
   );
 }

package/src/index.ts

@@ -15,6 +15,7 @@ export type {
 export * from "./Badge";
 export * from "./Carousel";
 export * from "./Chip";
+export * from "./CopyField";
 export * from "./DotIndicator";
 export * from "./DropdownMenu";
 export * from "./ContextMenu";
@@ -154,12 +155,17 @@ export type { AnchorProps, ParagraphProps, SizableTextProps, TextProps } from ".
 export { H1, H2, H3, H4, H5, H6, Heading } from "./Heading";
 export type { HeadingProps } from "./Heading";
 
-// Shadow tamagui Separator with the house Separator (MPO-47): the raw
-// primitive painted NOTHING — 96 of 96 measured separators were transparent
-// 1px boxes. The house rule is a painted 1px line in $borderColor (measured
-// law §7.3: 1px never 0.5px; quiet = opacity 0.5, never a lighter colour).
-// The curated ./tamagui surface no longer exports the bare name; raw stays
-// reachable as TamaguiSeparator.
+// Shadow tamagui Separator with the house Separator (MPO-47). Two reasons,
+// both measured: LC-45 / LC-70 — a bare name a house barrel exports is a
+// catalog part, and this one resolved to a raw primitive; and DG-OVF-07 —
+// the raw primitive is a `flex: 1` item, so the rule can absorb free space.
+// The house rule is a painted 1px line in $borderColor (measured law §7.3:
+// 1px never 0.5px; quiet = opacity 0.5, never a lighter colour) that cannot
+// flex-grow. The curated ./tamagui surface no longer exports the bare name;
+// raw stays reachable as TamaguiSeparator.
+//
+// Correction 2026-09-01: the ticket's "96 of 96 paint nothing" was a probe
+// artefact, not a defect — see ./Separator/index.tsx for the measurement.
 export { Separator } from "./Separator";
 export type { SeparatorProps } from "./Separator";
 

package/src/overlayElevation.spec.tsx

@@ -0,0 +1,154 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { cleanup } from "@testing-library/react";
+import { AlertDialog, Dialog, Theme } from "tamagui";
+import { afterEach, describe, expect, it } from "vitest";
+import { Button } from "./Button";
+import { AlertDialogContent, DialogContent } from "./surfaces";
+
+afterEach(cleanup);
+
+// ── What this file measures, and why not the class list ──────────────────
+//
+// MPO-49 AC: "DialogContent paints the reference §8 overlay shadow" and "a
+// spec asserts the dialog shadow differs from the Button shadow".
+//
+// The obvious probe — read the frame's `_bxsh-*` atom — passes on a frame
+// that paints something else entirely. `resolveKnobs.elevationPaint` emits
+// its web paint as `style: { boxShadow }`, an INLINE style, and Tamagui only
+// stamps `!important` on PSEUDO atoms (`getCSSStylesAtomic`: `const
+// important = !!pseudo`). A base atom therefore loses the cascade to any
+// inline style on the same node. Measured on `6eb0995`, before this lane:
+//
+//   class  _bxsh-0px12px24px…                      (the §8 value — dead)
+//   style  0 3px 6px rgba(0,0,0,0.15), 0 2px 4px … (the `$2` value — painted)
+//
+// So these assert the INLINE style, which is what a browser paints, and read
+// the class only to prove the two now agree. Reading the class alone is the
+// same hole MPO-40 / MPO-44 / MPO-48 all fell through, one layer further in:
+// the fragment reaches the frame and still never reaches the pixel.
+
+/** Reference §8, tamagui-rendered-reference.md — the one dialog shadow. */
+const referenceOverlayShadow = "0px 12px 24px rgba(0,0,0,0.12)";
+/** Same §8 geometry and alpha, hue inverted — LC-85 forbids a dark umbra. */
+const referenceOverlayShadowDark = "0px 12px 24px rgba(255,255,255,0.12)";
+/** `webShadowLight.$1` — the in-page control stop every Button carries. */
+const controlStopPaint = "0 1px 2px rgba(0,0,0,0.12), 0 0 1px rgba(0,0,0,0.08)";
+/** `webShadowLight.$2` — `elevatedSurface`'s own overlay paint. */
+const elevatedSurfacePaint = "0 3px 6px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.10)";
+
+function frame(id: string): HTMLElement {
+  const el = document.querySelector(`[data-testid="${id}"]`);
+  if (!el) throw new Error(`no frame rendered for ${id}`);
+  return el as HTMLElement;
+}
+
+/** The value a browser paints: the inline style wins over every base atom. */
+function paintedShadow(id: string): string {
+  return frame(id).style.boxShadow;
+}
+
+function shadowAtoms(id: string): string[] {
+  return String(frame(id).className || "")
+    .split(/\s+/)
+    .filter((c) => c.startsWith("_bxsh-"))
+    .sort();
+}
+
+function bgAtoms(id: string): string[] {
+  return String(frame(id).className || "")
+    .split(/\s+/)
+    .filter((c) => c.startsWith("_bg-"));
+}
+
+function renderDialogsBesideAButton() {
+  renderWithProviders(
+    <Preset>
+      <Button testID="control">Save</Button>
+      <Dialog modal open>
+        <Dialog.Portal>
+          <DialogContent testID="dialog">dialog</DialogContent>
+        </Dialog.Portal>
+      </Dialog>
+      <AlertDialog open>
+        <AlertDialog.Portal>
+          <AlertDialogContent testID="alertdialog">confirm</AlertDialogContent>
+        </AlertDialog.Portal>
+      </AlertDialog>
+    </Preset>,
+  );
+}
+
+describe("overlay elevation is a different distance off the surface (MPO-49)", () => {
+  it("DialogContent PAINTS the reference §8 shadow, not the $2 fragment underneath it", () => {
+    renderDialogsBesideAButton();
+    expect(paintedShadow("dialog")).toBe(referenceOverlayShadow);
+    expect(paintedShadow("dialog")).not.toBe(elevatedSurfacePaint);
+    expect(paintedShadow("dialog")).not.toBe(controlStopPaint);
+  });
+
+  it("the atom and the inline style agree — no dead §8 class over a live $2 paint", () => {
+    renderDialogsBesideAButton();
+    // The atom half alone does NOT discriminate: it reads `_bxsh-0px12px24px…`
+    // with the defect present too, which is why a class-only probe passes
+    // against a frame painting `$2`. Pair it with the painted value.
+    expect(shadowAtoms("dialog")).toHaveLength(1);
+    expect(shadowAtoms("dialog")[0]).toMatch(/^_bxsh-0px12px24px/);
+    expect(paintedShadow("dialog")).toContain("12px 24px");
+  });
+
+  it("the dialog shadow differs from the Button shadow, and the Button keeps the $1 stop", () => {
+    renderDialogsBesideAButton();
+    // "differs" alone does not discriminate: with the defect present the
+    // dialog paints `$2` and the Button `$1`, which also differ. The §8 value
+    // itself is pinned by the first case in this file; here the control side
+    // is pinned to `$1` so a Button regression cannot fake this one either.
+    expect(paintedShadow("control")).toBe(controlStopPaint);
+    expect(paintedShadow("dialog")).not.toBe(paintedShadow("control"));
+    expect(shadowAtoms("dialog")).not.toEqual(shadowAtoms("control"));
+  });
+
+  it("AlertDialogContent wears the same §8 shadow — one dialog row, one distance", () => {
+    // Tamagui's AlertDialog.Content IS Dialog.Content, and reference §8
+    // carries a single dialog row. confirm-dialog-{destructive,gated,warning}
+    // render through this frame.
+    renderDialogsBesideAButton();
+    expect(paintedShadow("alertdialog")).toBe(referenceOverlayShadow);
+    expect(paintedShadow("alertdialog")).toBe(paintedShadow("dialog"));
+  });
+
+  it("dark inverts the hue and keeps the §8 geometry; the ground steps up the ramp (LC-85)", () => {
+    renderWithProviders(
+      <Preset>
+        <Dialog modal open>
+          <Dialog.Portal>
+            <DialogContent testID="dialog">dialog</DialogContent>
+          </Dialog.Portal>
+        </Dialog>
+      </Preset>,
+    );
+    expect(paintedShadow("dialog")).toBe(referenceOverlayShadow);
+    expect(bgAtoms("dialog")).toEqual(["_bg-background"]);
+    cleanup();
+
+    renderWithProviders(
+      <Theme name="dark">
+        <Preset>
+          <Dialog modal open>
+            <Dialog.Portal>
+              <DialogContent testID="dialog">dialog</DialogContent>
+            </Dialog.Portal>
+          </Dialog>
+        </Preset>
+      </Theme>,
+    );
+    // LC-85 DARK-ELEVATION-TINT: light-coloured shadow, never a black umbra.
+    expect(paintedShadow("dialog")).toBe(referenceOverlayShadowDark);
+    expect(paintedShadow("dialog")).not.toBe(referenceOverlayShadow);
+    expect(paintedShadow("dialog")).not.toMatch(/rgba\(0,\s*0,\s*0/);
+    // resolveKnobs owns the dark ground: `overlayFill` steps the filled rest
+    // fill up the ramp under dark + elevation (LC-85). Asserted so a later
+    // change to that rule shows up here rather than silently on a board.
+    expect(bgAtoms("dialog")).toEqual(["_bg-color2"]);
+  });
+});

package/src/surfaces.spec.tsx

@@ -1,8 +1,12 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { cleanup } from "@testing-library/react";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Card as TamaguiCard, Dialog, Popover, Sheet } from "tamagui";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
+import { Button } from "./Button";
 import * as pkg from "./index";
 import {
   Card,
@@ -21,6 +25,8 @@ import {
   SheetFrame,
 } from "./surfaces";
 
+afterEach(cleanup);
+
 describe("surfaces package exports", () => {
   it("package Card is the themed surface, not the tamagui primitive", () => {
     expect(pkg.Card).toBe(Card);
@@ -86,3 +92,94 @@ describe("DialogContent overlay elevation (MPO-49)", () => {
     expect(dialog).toContain("panelPadding");
   });
 });
+
+// ── Render proofs ────────────────────────────────────────────────────────
+//
+// The source-text assertions above prove the CALL SITE. These prove the
+// FRAME, which is the distinction MPO-40 / MPO-44 / MPO-48 all fell through:
+// a fragment that exists in source and dies on the way to the frame reads
+// identical to one that never existed.
+//
+// happy-dom cannot cascade Tamagui's class CSS, so — as in Button.spec.tsx —
+// these read the atomic classes the knob emits. The atom name is hashed from
+// the VALUE, so the class IS the value, and no theme config is needed: what
+// the fragment addresses is visible in the class name itself.
+//
+// Measured both ways on 2026-09-01 by reverting each defect in the working
+// tree and re-running (see the MR description):
+//
+//   surface addressing   defect `$color1`  -> `_bg-color1`
+//                        fixed  `$background` -> `_bg-background`
+//   dialog elevation     defect Button/control `$1` -> `_bxsh-0px1px2px…`
+//                        fixed  reference §8        -> `_bxsh-0px12px24px…`
+//
+// A "differs from the Button" assertion does NOT discriminate: the Button
+// paints `0 6px 12px` from its own source in both states, so that comparison
+// passes with the defect present. Assert against the $1 CONTROL stop.
+
+function atomsWithPrefix(el: Element | null, prefix: string): string[] {
+  if (!el) return [];
+  return String((el as HTMLElement).className || "")
+    .split(/\s+/)
+    .filter((c) => c.startsWith(prefix))
+    .sort();
+}
+
+/** The `$1` control paint — `webShadowLight.$1`, "0 1px 2px …" (resolveKnobs.ts). */
+const controlStopShadowAtom = /^_bxsh-0px1px2px/;
+/** Rendered reference §8 DialogContent — `rgba(0,0,0,0.12) 0 12px 24px`. */
+const overlayStopShadowAtom = /^_bxsh-0px12px24px/;
+
+describe("surfaces address $background at the FRAME (MPO-19 X5/X6)", () => {
+  it("Card, Panel and DialogContent all paint _bg-background, never a raw ramp step", () => {
+    renderWithProviders(
+      <Preset>
+        <Card testID="mpo-card">card</Card>
+        <Panel testID="mpo-panel">panel</Panel>
+        <Dialog modal open>
+          <Dialog.Portal>
+            <DialogContent testID="mpo-dialog">dialog</DialogContent>
+          </Dialog.Portal>
+        </Dialog>
+      </Preset>,
+    );
+
+    for (const id of ["mpo-card", "mpo-panel", "mpo-dialog"]) {
+      const frame = document.querySelector(`[data-testid="${id}"]`);
+      expect(frame, `${id} frame`).toBeTruthy();
+      const bg = atomsWithPrefix(frame, "_bg-");
+      expect(bg, `${id} background atom`).toEqual(["_bg-background"]);
+      expect(bg.join(" "), `${id} must not address a raw ramp step`).not.toMatch(/_bg-color[12]\b/);
+    }
+  });
+});
+
+describe("DialogContent paints the OVERLAY elevation stop, not the control one (MPO-49)", () => {
+  it("renders the reference §8 shadow and not the Button $1 stop", () => {
+    renderWithProviders(
+      <Preset>
+        <Button testID="mpo-button-control">Save</Button>
+        <Dialog modal open>
+          <Dialog.Portal>
+            <DialogContent testID="mpo-dialog-overlay">body</DialogContent>
+          </Dialog.Portal>
+        </Dialog>
+      </Preset>,
+    );
+
+    const dialog = document.querySelector('[data-testid="mpo-dialog-overlay"]');
+    const button = document.querySelector('[data-testid="mpo-button-control"]');
+    expect(dialog, "DialogContent frame").toBeTruthy();
+    expect(button, "Button frame").toBeTruthy();
+
+    const dialogShadow = atomsWithPrefix(dialog, "_bxsh-");
+    expect(dialogShadow, "DialogContent paints exactly one shadow atom").toHaveLength(1);
+    expect(dialogShadow[0], "dialog wears the §8 overlay shadow").toMatch(overlayStopShadowAtom);
+    expect(dialogShadow[0], "dialog must not wear the $1 control stop").not.toMatch(
+      controlStopShadowAtom,
+    );
+    expect(dialogShadow, "dialog and control are different distances off the surface").not.toEqual(
+      atomsWithPrefix(button, "_bxsh-"),
+    );
+  });
+});