@multiplatform.one/components 7.4.1 → 7.6.0

package/src/ErrorBoundary/ErrorBoundary.spec.tsx

@@ -3,6 +3,7 @@ import { H1 } from "tamagui";
 import { expect, vitest } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { ErrorBoundary } from "./index";
+import * as ErrorBoundaryModule from "./index";
 
 const ChildThatThrows = () => {
   throw new Error("Test Error");
@@ -11,6 +12,13 @@ const ChildThatRenders = () => {
   return <H1>Hello from child!</H1>;
 };
 
+function weightClasses(el: Element): string[] {
+  return String((el as HTMLElement).className || "")
+    .split(" ")
+    .filter((c) => c.startsWith("_fow-"))
+    .sort();
+}
+
 describe("ErrorBoundary", () => {
   it("should render children when no error occurs", () => {
     renderWithProviders(
@@ -29,6 +37,22 @@ describe("ErrorBoundary", () => {
     );
     expect(screen.getByText("Oops, there is an error!")).toBeInTheDocument();
     expect(screen.getByText("Try again?")).toBeInTheDocument();
+    expect(document.querySelector("[data-error-boundary]")).toBeTruthy();
+    expect(document.querySelector('[data-empty-intent="error"]')).toBeTruthy();
+  });
+
+  it("R7: Retry label TEXT NODE is weight 400, never 500/600", () => {
+    renderWithProviders(
+      <ErrorBoundary>
+        <ChildThatThrows />
+      </ErrorBoundary>,
+    );
+    const node = screen.getByText("Try again?");
+    expect(node.tagName).not.toBe("BUTTON");
+    expect(node.className).toMatch(/_fow-400\b/);
+    expect(node.className).not.toMatch(/_fow-500\b/);
+    expect(node.className).not.toMatch(/_fow-600\b/);
+    expect(weightClasses(node).some((c) => c.includes("400"))).toBe(true);
   });
 
   it("should reset error state and re-render children when retry button is clicked", async () => {
@@ -57,4 +81,9 @@ describe("ErrorBoundary", () => {
     );
     spy.mockRestore();
   });
+
+  it("exposes named ErrorBoundary export and no default", () => {
+    expect(ErrorBoundaryModule.ErrorBoundary).toBe(ErrorBoundary);
+    expect("default" in ErrorBoundaryModule).toBe(false);
+  });
 });

package/src/ErrorBoundary/index.tsx

@@ -1,8 +1,9 @@
 import type { ErrorInfo, ReactNode } from "react";
 import { Component } from "react";
+import { Text } from "tamagui";
 import { useTranslation } from "../shared/i18n";
-import { Button } from "@multiplatform.one/forms";
-import { H2, YStack } from "tamagui";
+import { Button } from "../Button";
+import { EmptyState } from "../layouts/EmptyState";
 
 const logger = console;
 
@@ -18,11 +19,19 @@ interface ErrorBoundaryState {
 
 function ErrorFallback({ onRetry }: { onRetry: () => void }) {
   const { t } = useTranslation();
+  // R7 / §6.1: Retry is an inline action label — weight 400 on the TEXT NODE.
+  const retryLabel = t("Try again?");
   return (
-    <YStack>
-      <H2>{t("Oops, there is an error!")}</H2>
-      <Button onPress={onRetry}>{t("Try again?")}</Button>
-    </YStack>
+    <EmptyState
+      intent="error"
+      data-error-boundary=""
+      title={t("Oops, there is an error!")}
+      action={
+        <Button onPress={onRetry}>
+          <Text fontWeight="400">{retryLabel}</Text>
+        </Button>
+      }
+    />
   );
 }
 

package/src/Heading.native.spec.tsx

@@ -0,0 +1,156 @@
+/**
+ * House Heading knob wiring, NATIVE arm (MPO-20).
+ *
+ * Why this lives in its OWN file. The arm originally sat inside
+ * `Heading.spec.tsx` as a `vi.resetModules()` + dynamic-import block whose
+ * comment promised "everything must come from the SAME fresh graph". It did
+ * not: measured on origin/main, after `vi.resetModules()` the re-imported
+ * `@multiplatform.one/test-utils` was a NEW instance while
+ * `@multiplatform.one/theme` came back as the ORIGINAL one
+ * (`Preset === Preset` true, `renderWithProviders === renderWithProviders`
+ * false). So the fresh `renderWithProviders` mounted a fresh TamaguiProvider
+ * whose theme context the stale `useResolvedKnobs` never read: the Text arm
+ * threw "Missing theme.", and the Heading arm silently fell back to the
+ * DEFAULT preset for both sides of the flip and compared `_fow-400` with
+ * `_fow-400`. A knob-dead component would have passed that assertion the same
+ * way — the exact class of hole MPO-40/44/48 came from.
+ *
+ * One spec FILE is one module registry in vitest, so a file-scoped
+ * `vi.mock` applies the native platform to the WHOLE graph — theme,
+ * test-utils and tamagui included — with no resetModules gymnastics.
+ *
+ * What the arm proves and what it does not. `renderWithProviders` leaves the
+ * mpo ThemeProvider off by default, so FontKnobStyles' web-only CSS-variable
+ * rescue is mounted in NEITHER arm; the props channel is the only channel
+ * carrying the knob here, which is the channel native has. It does NOT
+ * execute the React Native renderer — it is the standing substitute for a
+ * simulator capture (`agent-os/standards/testing/falsifiability.md`), not a
+ * replacement for one.
+ */
+import { cleanup, screen } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { H1, H3, Heading } from "./Heading";
+
+vi.mock("@multiplatform.one/platform", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@multiplatform.one/platform")>()),
+  isWeb: false,
+  isNative: true,
+}));
+
+afterEach(cleanup);
+
+const TITLE = "Workspace Settings";
+
+function classesByPrefix(el: Element, prefixes: string[]): string[] {
+  return String((el as HTMLElement).className || "")
+    .split(" ")
+    .filter((c) => prefixes.some((p) => c.startsWith(p)))
+    .sort();
+}
+
+/** Render, guard the text node's tag, read its prefixed classes, clean up. */
+function renderHeadingClasses(
+  node: React.ReactElement,
+  prefixes: string[],
+  expectedTag?: string,
+): string[] {
+  renderWithProviders(node);
+  const textNode = screen.getByText(TITLE);
+  if (expectedTag) {
+    // The text node IS the heading element — not a frame around it.
+    expect(textNode.tagName).toBe(expectedTag);
+  }
+  const classes = classesByPrefix(textNode, prefixes);
+  cleanup();
+  return classes;
+}
+
+describe("house Heading — NATIVE environment (isWeb false)", () => {
+  it("really is running with the native platform flags", async () => {
+    const platform = await import("@multiplatform.one/platform");
+    expect(platform.isWeb).toBe(false);
+    expect(platform.isNative).toBe(true);
+  });
+
+  it("changes weight on a fontWeight flip, pinned to 400/700", () => {
+    const regular = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "regular" }}>
+        <Heading>{TITLE}</Heading>
+      </Preset>,
+      ["_fow-"],
+    );
+    const bold = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "bold" }}>
+        <Heading>{TITLE}</Heading>
+      </Preset>,
+      ["_fow-"],
+    );
+    const explicit400 = renderHeadingClasses(<Heading fontWeight="400">{TITLE}</Heading>, [
+      "_fow-",
+    ]);
+    const explicit700 = renderHeadingClasses(<Heading fontWeight="700">{TITLE}</Heading>, [
+      "_fow-",
+    ]);
+    expect(regular).not.toHaveLength(0);
+    expect(regular).not.toEqual(bold);
+    expect(regular).toEqual(explicit400);
+    expect(bold).toEqual(explicit700);
+  });
+
+  it("H1 changes size on a pageTitleScale flip, resolved through the D-11 table", () => {
+    const moderate = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "moderate" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H1",
+    );
+    const display = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "display" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H1",
+    );
+    const explicit8 = renderHeadingClasses(<H1 size="$8">{TITLE}</H1>, ["_fos-", "_lh-"], "H1");
+    const explicit10 = renderHeadingClasses(<H1 size="$10">{TITLE}</H1>, ["_fos-", "_lh-"], "H1");
+    expect(moderate).not.toHaveLength(0);
+    expect(moderate).not.toEqual(display);
+    expect(moderate).toEqual(explicit8);
+    expect(display).toEqual(explicit10);
+  });
+
+  it("H1 carries the fontWeight flip too — pageTitle does not swallow it", () => {
+    const regular = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "regular" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fow-"],
+      "H1",
+    );
+    const bold = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "bold" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fow-"],
+      "H1",
+    );
+    expect(regular).not.toHaveLength(0);
+    expect(regular).not.toEqual(bold);
+  });
+
+  it("H3 stays mono 400 — subordinate headings ignore the heading knobs", () => {
+    const byDefault = renderHeadingClasses(<H3>{TITLE}</H3>, ["_fow-"], "H3");
+    const underBoldSans = renderHeadingClasses(
+      <Preset overrides={{ headingFont: "sans-serif", fontWeight: "bold" }}>
+        <H3>{TITLE}</H3>
+      </Preset>,
+      ["_fow-"],
+      "H3",
+    );
+    expect(byDefault).not.toHaveLength(0);
+    expect(byDefault).toEqual(underBoldSans);
+  });
+});

package/src/Heading.spec.tsx

@@ -0,0 +1,256 @@
+/**
+ * House Heading knob wiring (MPO-20) — headingFont / fontWeight reach every
+ * heading's TEXT NODE and pageTitleScale re-steps H1, on the props channel
+ * that serves every platform.
+ *
+ * Measurement discipline (MPO-40/44/48): assertions read the TEXT NODE — the
+ * H1/H2/span element `screen.getByText` returns, tag-guarded — never a
+ * wrapping frame. jsdom/happy-dom cannot cascade Tamagui's class-based CSS,
+ * so the specs compare atomic style classes (`_fow-` weight, `_fos-`/`_lh-`
+ * size step — the pageTitleScale.spec.tsx technique) and the font-scope
+ * class (`font_heading` / `font_mono`) for family, between knob flips and
+ * against explicit-prop renders of the same value. Hashed class names are
+ * compared by identity only.
+ *
+ * This file is the WEB arm (the default module graph). The NATIVE arm is
+ * ./Heading.native.spec.tsx, a separate FILE so that a file-scoped `vi.mock`
+ * gives it one coherent module graph. FontKnobStyles' web-only CSS rescue is
+ * mounted in NEITHER arm, so flips reaching the node prove 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 { afterEach, describe, expect, it } from "vitest";
+import { H1, H2, H3, Heading } from "./Heading";
+
+afterEach(cleanup);
+
+const TITLE = "Workspace Settings";
+
+function classesByPrefix(el: Element, prefixes: string[]): string[] {
+  return String((el as HTMLElement).className || "")
+    .split(" ")
+    .filter((c) => prefixes.some((p) => c.startsWith(p)))
+    .sort();
+}
+
+/** Tamagui font-scope class on the TEXT NODE (`font_heading` / `font_mono` / …). */
+function fontScopeClass(el: Element): string {
+  return (
+    String((el as HTMLElement).className || "")
+      .split(" ")
+      .find((c) => c.startsWith("font_")) ?? ""
+  );
+}
+
+/** Render, guard the text node's tag, read its prefixed classes, clean up. */
+function renderHeadingClasses(
+  node: React.ReactElement,
+  prefixes: string[],
+  expectedTag?: string,
+): string[] {
+  renderWithProviders(node);
+  const textNode = screen.getByText(TITLE);
+  if (expectedTag) {
+    // The text node IS the heading element — not a frame around it.
+    expect(textNode.tagName).toBe(expectedTag);
+  }
+  const classes = classesByPrefix(textNode, prefixes);
+  cleanup();
+  return classes;
+}
+
+describe("house Heading — fontWeight reaches the heading text node (MPO-20)", () => {
+  it("changes weight on a fontWeight flip, pinned to 400/700", () => {
+    const regular = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "regular" }}>
+        <Heading>{TITLE}</Heading>
+      </Preset>,
+      ["_fow-"],
+    );
+    const bold = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "bold" }}>
+        <Heading>{TITLE}</Heading>
+      </Preset>,
+      ["_fow-"],
+    );
+    const explicit400 = renderHeadingClasses(<Heading fontWeight="400">{TITLE}</Heading>, [
+      "_fow-",
+    ]);
+    const explicit700 = renderHeadingClasses(<Heading fontWeight="700">{TITLE}</Heading>, [
+      "_fow-",
+    ]);
+    expect(regular).not.toHaveLength(0);
+    expect(regular).not.toEqual(bold);
+    expect(regular).toEqual(explicit400);
+    expect(bold).toEqual(explicit700);
+  });
+
+  it("H1 changes weight on the same flip (the page title is a heading too)", () => {
+    const regular = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "regular" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fow-"],
+      "H1",
+    );
+    const bold = renderHeadingClasses(
+      <Preset overrides={{ fontWeight: "bold" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fow-"],
+      "H1",
+    );
+    const explicit400 = renderHeadingClasses(<H1 fontWeight="400">{TITLE}</H1>, ["_fow-"], "H1");
+    const explicit700 = renderHeadingClasses(<H1 fontWeight="700">{TITLE}</H1>, ["_fow-"], "H1");
+    expect(regular).not.toHaveLength(0);
+    expect(regular).not.toEqual(bold);
+    expect(regular).toEqual(explicit400);
+    expect(bold).toEqual(explicit700);
+  });
+
+  it("changes family on a headingFont flip (props, not the web-only CSS rescue)", () => {
+    const scope = (node: React.ReactElement) => {
+      renderWithProviders(node);
+      const cls = fontScopeClass(screen.getByText(TITLE));
+      cleanup();
+      return cls;
+    };
+    const sans = scope(
+      <Preset overrides={{ headingFont: "sans-serif" }}>
+        <Heading>{TITLE}</Heading>
+      </Preset>,
+    );
+    const mono = scope(
+      <Preset overrides={{ headingFont: "mono" }}>
+        <Heading>{TITLE}</Heading>
+      </Preset>,
+    );
+    expect(sans).toBe("font_heading");
+    expect(mono).toBe("font_mono");
+  });
+});
+
+describe("house H3 — subordinate headings are mono 400 on the TEXT NODE", () => {
+  it("pins family and weight to mono 400, ignoring heading knobs", () => {
+    const byDefault = renderHeadingClasses(<H3>{TITLE}</H3>, ["_fow-"], "H3");
+    const explicit = renderHeadingClasses(
+      <H3 fontFamily="$mono" fontWeight="400">
+        {TITLE}
+      </H3>,
+      ["_fow-"],
+      "H3",
+    );
+    const headingSans = renderHeadingClasses(
+      <Preset overrides={{ headingFont: "sans-serif", fontWeight: "bold" }}>
+        <H3>{TITLE}</H3>
+      </Preset>,
+      ["_fow-"],
+      "H3",
+    );
+    expect(byDefault).not.toHaveLength(0);
+    expect(byDefault).toEqual(explicit);
+    expect(headingSans).toEqual(explicit);
+
+    renderWithProviders(<H3>{TITLE}</H3>);
+    expect(fontScopeClass(screen.getByText(TITLE))).toBe("font_mono");
+    cleanup();
+  });
+
+  it("consumer eject still wins over the house pin (STD-EJECT-LAST)", () => {
+    const ejected = renderHeadingClasses(
+      <H3 fontFamily="$heading" fontWeight="700">
+        {TITLE}
+      </H3>,
+      ["_ff-", "_fow-"],
+      "H3",
+    );
+    const explicit = renderHeadingClasses(
+      <H3 fontFamily="$heading" fontWeight="700">
+        {TITLE}
+      </H3>,
+      ["_ff-", "_fow-"],
+      "H3",
+    );
+    expect(ejected).toEqual(explicit);
+    expect(ejected).not.toEqual(renderHeadingClasses(<H3>{TITLE}</H3>, ["_ff-", "_fow-"], "H3"));
+  });
+});
+
+describe("house H1 — pageTitleScale reaches the title text node (LC-17 / D-11)", () => {
+  it("changes size on a pageTitleScale flip, and moderate is the default", () => {
+    const byDefault = renderHeadingClasses(<H1>{TITLE}</H1>, ["_fos-", "_lh-"], "H1");
+    const moderate = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "moderate" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H1",
+    );
+    const display = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "display" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H1",
+    );
+    expect(byDefault).not.toHaveLength(0);
+    expect(byDefault).toEqual(moderate);
+    expect(byDefault).not.toEqual(display);
+  });
+
+  it("resolves through the one D-11 table: the knob equals the explicit size step", () => {
+    // moderate → $8, display → $10 on the heading scale (resolveKnobs
+    // pageTitleSizeMap). Identity against explicit size props pins the
+    // fragment to the table without hardcoding hashed classes or px.
+    const moderate = renderHeadingClasses(<H1>{TITLE}</H1>, ["_fos-", "_lh-"], "H1");
+    const explicit8 = renderHeadingClasses(<H1 size="$8">{TITLE}</H1>, ["_fos-", "_lh-"], "H1");
+    const display = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "display" }}>
+        <H1>{TITLE}</H1>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H1",
+    );
+    const explicit10 = renderHeadingClasses(<H1 size="$10">{TITLE}</H1>, ["_fos-", "_lh-"], "H1");
+    expect(moderate).toEqual(explicit8);
+    expect(display).toEqual(explicit10);
+  });
+
+  it("does NOT re-step H2 — the dial is the page title's, not every heading's", () => {
+    const moderate = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "moderate" }}>
+        <H2>{TITLE}</H2>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H2",
+    );
+    const display = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "display" }}>
+        <H2>{TITLE}</H2>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H2",
+    );
+    expect(moderate).toEqual(display);
+  });
+
+  it("the per-instance eject still wins over the knob (PageHeader contract)", () => {
+    const ejected = renderHeadingClasses(
+      <Preset overrides={{ pageTitleScale: "display" }}>
+        <H1 size="$8">{TITLE}</H1>
+      </Preset>,
+      ["_fos-", "_lh-"],
+      "H1",
+    );
+    const moderate = renderHeadingClasses(<H1>{TITLE}</H1>, ["_fos-", "_lh-"], "H1");
+    expect(ejected).toEqual(moderate);
+  });
+});
+
+// The NATIVE arm lives in ./Heading.native.spec.tsx. It used to sit here as a
+// `vi.resetModules()` + dynamic-import block, but that returned a SPLIT module
+// graph in which the knob overrides never reached the heading, so both sides
+// of the flip measured `_fow-400` and the assertion passed a knob-dead render.
+// A file-scoped `vi.mock` in its own spec file is one coherent graph.

package/src/Heading.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Preset } from "@multiplatform.one/theme";
+import { YStack } from "tamagui";
+import { H1, H2, H3, Heading } from "./Heading";
+import { Text } from "./Text";
+
+const meta: Meta<typeof Heading> = {
+  title: "Components/Heading",
+  component: Heading,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "House headings (MPO-20). Heading/H1/H2 spread knobProps.heading as props — headingFont and fontWeight restyle those on every platform — and H1 additionally rides knobProps.pageTitle, the D-11 page-title dial (moderate 32px default, display 64px hero opt-in). H3–H6 are subordinate: mono at weight 400, knobs do not restyle them. Flip the toolbar knobs to see.",
+      },
+    },
+  },
+  argTypes: {
+    children: { control: "text" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Heading>;
+
+export const Default: Story = {
+  name: "Main",
+  args: {
+    children: "Heading follows the headingFont and fontWeight knobs",
+  },
+};
+
+export const TitleLadder: Story = {
+  render: () => (
+    <YStack gap="$3" maxWidth={640}>
+      <H1>H1 page title — rides the pageTitleScale dial</H1>
+      <H2>H2 display heading — headingFont / fontWeight</H2>
+      <H3>H3 subordinate — mono 400</H3>
+      <Text>Body text for scale comparison.</Text>
+    </YStack>
+  ),
+};
+
+export const PageTitleScaleFlip: Story = {
+  name: "pageTitleScale flip (moderate vs display)",
+  render: () => (
+    <YStack gap="$4" maxWidth={760}>
+      <Preset overrides={{ pageTitleScale: "moderate" }}>
+        <H1>moderate — the product default (32px class)</H1>
+      </Preset>
+      <Preset overrides={{ pageTitleScale: "display" }}>
+        <H1>display — the hero opt-in (64px class)</H1>
+      </Preset>
+    </YStack>
+  ),
+};
+
+export const FontWeightFlip: Story = {
+  name: "fontWeight flip (regular vs bold)",
+  render: () => (
+    <YStack gap="$3" maxWidth={640}>
+      <Preset overrides={{ fontWeight: "regular" }}>
+        <Heading>regular — 400</Heading>
+      </Preset>
+      <Preset overrides={{ fontWeight: "bold" }}>
+        <Heading>bold — 700</Heading>
+      </Preset>
+    </YStack>
+  ),
+};

package/src/Heading.tsx

@@ -0,0 +1,79 @@
+/**
+ * House heading voices for the components catalog — Heading and H1–H6
+ * (MPO-20, LC-70 CURATED-REEXPORT-IS-CATALOG; sibling of ./Text.tsx, see
+ * its header for the full architecture note).
+ *
+ * The raw tamagui headings were knob-dead on native and weight/scale-dead
+ * everywhere: headingFont reached them on web only (FontKnobStyles CSS
+ * variables), fontWeight and pageTitleScale never. Every composed surface
+ * that wanted a knob-correct title had to hand-wire the fragments
+ * (PageHeader does exactly that). These shadows spread the fragments as
+ * props so the knob channel reaches the TEXT NODE on every platform, with
+ * consumer props last (STD-EJECT-LAST — explicit fontWeight/size/fontSize
+ * ejects keep working, so PageSection's sectionHeading spread and
+ * PageHeader's titleScale eject are unaffected).
+ *
+ * Knob channels wired here:
+ *  - headingFont    → knobProps.heading.fontFamily (every platform)
+ *  - fontWeight     → knobProps.heading.fontWeight (regular 400 / bold 700)
+ *  - pageTitleScale → knobProps.pageTitle on H1 ONLY (LC-17 / D-11: the
+ *    page-title step is a pinned dial — moderate $8 = 32px product default,
+ *    display $10 = 64px hero opt-in). H2 is a display heading (weight 700
+ *    is lawful here). H3–H6 are subordinate: house law pins them to the
+ *    mono face at weight 400 (tamagui-rendered-reference.md §9) — heading
+ *    knobs do not restyle them. Section titles composed with the shared
+ *    sectionHeading token (LC-17) carry the same mono/400 voice.
+ *
+ * Raw primitives stay reachable as TamaguiHeading / TamaguiH1..TamaguiH6
+ * (./tamagui.ts escape hatches, LC-45).
+ */
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  H1 as RawH1,
+  H2 as RawH2,
+  H3 as RawH3,
+  H4 as RawH4,
+  H5 as RawH5,
+  H6 as RawH6,
+  Heading as RawHeading,
+  type HeadingProps,
+} from "tamagui";
+
+export type { HeadingProps };
+
+/** Subordinate heading voice — mono, weight 400. Consumer props still eject. */
+const SUBORDINATE = { fontFamily: "$mono", fontWeight: "400" } as const;
+
+export function Heading(props: HeadingProps) {
+  const { knobProps } = useResolvedKnobs();
+  return <RawHeading {...knobProps.heading} {...props} />;
+}
+
+export function H1(props: HeadingProps) {
+  const { knobProps } = useResolvedKnobs();
+  // pageTitle first: H1's size variant paints `_fow-f-weight-8` (the $8
+  // heading-weight token). heading.fontWeight must land AFTER that so
+  // regular/bold reach the TEXT NODE instead of being swallowed.
+  return <RawH1 {...knobProps.pageTitle} {...knobProps.heading} {...props} />;
+}
+
+export function H2(props: HeadingProps) {
+  const { knobProps } = useResolvedKnobs();
+  return <RawH2 {...knobProps.heading} {...props} />;
+}
+
+export function H3(props: HeadingProps) {
+  return <RawH3 {...SUBORDINATE} {...props} />;
+}
+
+export function H4(props: HeadingProps) {
+  return <RawH4 {...SUBORDINATE} {...props} />;
+}
+
+export function H5(props: HeadingProps) {
+  return <RawH5 {...SUBORDINATE} {...props} />;
+}
+
+export function H6(props: HeadingProps) {
+  return <RawH6 {...SUBORDINATE} {...props} />;
+}