@terpjs/react-core 0.9.0 → 0.10.0

package/src/layout.tsx

@@ -6,13 +6,45 @@ import type { UiText } from "./uiText";
 /** The spacing scale — indexes into the `--space-*` design tokens (no arbitrary pixel gaps). */
 export type SpaceToken = 0 | 1 | 2 | 3 | 4 | 6 | 8;
 
+/**
+ * A value, or one value below the framework's viewport cutover and another above it.
+ *
+ * There is one cutover and not a scale of them, deliberately: `wide` is the complement of the
+ * width at which the shell becomes a drawer and the DataView becomes cards, so a responsive
+ * `Stack` changes over at exactly the moment the chrome around it does. A second breakpoint is
+ * a rule per value per breakpoint in the sheet, and nothing has asked for one — the same reason
+ * the density scale has two steps rather than five.
+ */
+export type Responsive<T> = T | { narrow: T; wide: T };
+
+/** Split a possibly-responsive prop into its two halves. */
+function responsive<T>(value: Responsive<T>): { narrow: T; wide: T | undefined } {
+  return value !== null && typeof value === "object" && "narrow" in value
+    ? { narrow: value.narrow, wide: value.wide }
+    : { narrow: value as T, wide: undefined };
+}
+
 export interface StackProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
   /** The rendered element (`"div"` by default; use `"form"`, `"section"`, `"ul"`, …). */
   as?: ElementType;
-  /** Main axis: `"column"` (default) stacks, `"row"` lines up. */
-  direction?: "column" | "row";
+  /**
+   * Main axis: `"column"` (default) stacks, `"row"` lines up.
+   *
+   * Takes a {@link Responsive} pair for the toolbar case — `{ narrow: "column", wide: "row" }`
+   * is a row of controls that stacks below the cutover, which was previously inexpressible
+   * without a `style` an app module may not write.
+   */
+  direction?: Responsive<"column" | "row">;
   /** Gap between children, as a step on the token spacing scale (default `2`). */
-  gap?: SpaceToken;
+  gap?: Responsive<SpaceToken>;
+  /**
+   * Inset around the children, as a step on the token spacing scale (default none).
+   *
+   * The dimension the diagnosis named first — "no padding" — and the one that made a padded
+   * region reachable only through a `Card`, whose border and background came with it whether
+   * they were wanted or not.
+   */
+  padding?: SpaceToken;
   /** Cross-axis alignment (e.g. `"center"`, `"start"`, `"end"`, `"stretch"`). */
   align?: CSSProperties["alignItems"];
   /** Main-axis distribution (e.g. `"space-between"`, `"center"`, `"end"`). */
@@ -33,6 +65,7 @@ export function Stack({
   as: Component = "div",
   direction = "column",
   gap = 2,
+  padding,
   align,
   justify,
   wrap = false,
@@ -49,18 +82,140 @@ export function Stack({
           ...(align !== undefined ? { alignItems: align } : undefined),
           ...(justify !== undefined ? { justifyContent: justify } : undefined),
         };
+  // A responsive prop is two attributes, and the wide half is stamped only when it was asked
+  // for — so a non-responsive Stack renders exactly the attributes it always did and every
+  // existing baseline is untouched by construction.
+  const directions = responsive(direction);
+  const gaps = responsive(gap);
   return (
     <Component
       {...rest}
       data-terp="stack"
-      data-direction={direction}
-      data-gap={String(gap)}
+      data-direction={directions.narrow}
+      data-direction-wide={directions.wide}
+      data-gap={String(gaps.narrow)}
+      data-gap-wide={gaps.wide === undefined ? undefined : String(gaps.wide)}
+      data-padding={padding === undefined ? undefined : String(padding)}
       data-wrap={wrap ? "true" : undefined}
       style={alignment}
     />
   );
 }
 
+/** Fixed column count, or `"auto"` — as many columns as fit above `minColumn`. */
+export type GridColumns = 1 | 2 | 3 | 4 | "auto";
+
+/** Track floor for an `"auto"` grid: the width below which a column stops being one. */
+export type GridMinColumn = "xs" | "sm" | "md" | "lg";
+
+export interface GridProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
+  /** The rendered element (`"div"` by default; use `"ul"`, `"section"`, `"dl"`, …). */
+  as?: ElementType;
+  /**
+   * Columns: a fixed count, or `"auto"` (the default) for as many as fit above
+   * {@link GridProps.minColumn}.
+   *
+   * `"auto"` is the responsive answer and it takes no breakpoint: the track floor makes the
+   * grid reflow to whatever its **container** can hold, which is what a caller almost always
+   * means and is more nearly right than a viewport query — a grid inside a narrow panel
+   * should go one-column whatever the window is doing.
+   */
+  columns?: GridColumns;
+  /** Track floor for an `"auto"` grid (default `"sm"`); ignored at a fixed count. */
+  minColumn?: GridMinColumn;
+  /** Gap between cells, as a step on the token spacing scale (default `4`). */
+  gap?: SpaceToken;
+  /** Inset around the cells, as a step on the token spacing scale (default none). */
+  padding?: SpaceToken;
+  /**
+   * Block alignment of each cell within its row (default `"stretch"`).
+   *
+   * A closed set of four, unlike `Stack`'s `align` — see the note on {@link Grid}.
+   */
+  align?: "start" | "center" | "end" | "stretch";
+  children?: ReactNode;
+}
+
+/**
+ * The two-dimensional layout primitive, and the one that lifts a real ceiling: with `Stack`
+ * as the entire vocabulary, a two-column form could not be expressed at all, so a fifteen-field
+ * form shipped as one long vertical run. App modules may not write `style` or `className`
+ * (ADR 0059), so that was not awkwardness — it was unbuildable.
+ *
+ * Every prop is a closed set and becomes a `data-*` attribute with a rule each, so `Grid`
+ * renders **no inline style** and stays out of the inline-style ledger (ADR 0097). Three
+ * consequences of that are worth knowing, because each was a choice:
+ *
+ * - **`align` takes four values, where `Stack`'s takes any alignment keyword.** The divergence
+ *   is deliberate rather than an oversight. `Stack`'s is open because it was already inline
+ *   when ADR 0094 drew the line, and an open vocabulary stays inline; a *new* component picks
+ *   the closed set so it needs no `style` at all. `justify` is absent for the same reason it
+ *   would be least useful: a grid's tracks already fill their container, so distributing them
+ *   is a question about the tracks rather than the cells, and no consumer has asked.
+ * - **`minColumn` is a scale, not a length.** `Icon`'s `size` takes any CSS length and stays
+ *   inline for it; a grid's column floor could have gone the same way. It is a scale instead
+ *   for the reason `Stack`'s `gap` is a token index: so there are no arbitrary widths. An app
+ *   wanting 17.5rem cannot have it, which is the same trade `gap` already makes.
+ * - **There is no `span`,** and therefore no twelve-column option. A span system needs a child
+ *   component to carry it, and a `columns={12}` with no way to span is a grid of twelve narrow
+ *   cells rather than a layout system — worse than not offering it.
+ */
+export function Grid({
+  as: Component = "div",
+  columns = "auto",
+  minColumn = "sm",
+  gap = 4,
+  padding,
+  align = "stretch",
+  ...rest
+}: GridProps) {
+  return (
+    <Component
+      {...rest}
+      data-terp="grid"
+      // The defaults are the base rule, so their attributes match nothing and are left off —
+      // the shape density and Button's `md` already use. String(columns) rather than the
+      // number, because a `data-` attribute is text and `columns={2}` must produce "2".
+      data-columns={columns === "auto" ? undefined : String(columns)}
+      data-min-column={columns === "auto" && minColumn !== "sm" ? minColumn : undefined}
+      data-gap={String(gap)}
+      data-padding={padding === undefined ? undefined : String(padding)}
+      data-align={align === "stretch" ? undefined : align}
+    />
+  );
+}
+
+export interface DividerProps extends Omit<HTMLAttributes<HTMLElement>, "style"> {
+  /** `"horizontal"` (default) rules across a column; `"vertical"` separates a row. */
+  orientation?: "horizontal" | "vertical";
+}
+
+/**
+ * A rule between two groups of content — `Separator` under its other common name, shipped
+ * once rather than twice.
+ *
+ * An `<hr>`, so the separation is in the accessibility tree rather than only in the pixels; a
+ * bordered `<div>` is what a module reaches for when it has no primitive, and it says nothing
+ * to a screen reader. The vertical form carries `aria-orientation`, which `<hr>` does not
+ * imply.
+ *
+ * The vertical case needs a height from somewhere and deliberately does not invent one: it
+ * stretches to its flex or grid line, so it works between the items of a row `Stack` and is
+ * zero-height in a plain block parent. That is the one thing about it worth knowing before
+ * reaching for it, and the reason its specimen renders inside a fixed-height row.
+ */
+export function Divider({ orientation = "horizontal", ...rest }: DividerProps) {
+  return (
+    <hr
+      {...rest}
+      data-terp="divider"
+      // Horizontal is the base rule, so only the vertical case carries an attribute.
+      data-orientation={orientation === "vertical" ? "vertical" : undefined}
+      aria-orientation={orientation === "vertical" ? "vertical" : undefined}
+    />
+  );
+}
+
 export interface DetailItem {
   /** The item's label (rendered as `<dt>`). */
   label: UiText;
@@ -68,23 +223,65 @@ export interface DetailItem {
   value: ReactNode;
 }
 
+/** How a pair is arranged. */
+export type DetailListLayout = "inline" | "aligned" | "stacked";
+
 export interface DetailListProps extends Omit<HTMLAttributes<HTMLDListElement>, "style"> {
   /** The label/value pairs to render, in order. */
   items: readonly DetailItem[];
+  /**
+   * How each pair reads (default `"inline"` — `Label: value` on one line).
+   *
+   * `"aligned"` puts every label in a shared left column, so the values line up; `"stacked"`
+   * puts the label above its value, which is what a narrow column or a long value wants.
+   *
+   * The default is the old behaviour on purpose: this component is in the `standard` layout
+   * contract's detail-page slot, so every governed detail screen already renders one.
+   */
+  layout?: DetailListLayout;
+  /** Pairs per row (default `1`). */
+  columns?: 1 | 2;
 }
 
 /**
  * Token-styled label/value pairs as a semantic `<dl>` — record metadata on a detail page,
- * an expanded row's summary. Centralizes the "Label: value" pattern so modules never
- * hand-style definition lists.
+ * an expanded row's summary.
+ *
+ * A real grid rather than an inline run, which is the thing the diagnosis was pointing at: nine
+ * pairs including two 64-character digests, "through an inline run 4px apart with no
+ * alignment". Two fixes rather than one, and the second was the actual defect:
+ *
+ * - `layout="aligned"` gives the labels a shared column. The row wrapper becomes
+ *   `display: contents` so the `<dt>` and `<dd>` are grid items of the `<dl>` itself — no DOM
+ *   change, and the only way to align across rows without one.
+ * - **The tracks are floored at zero.** An implicit grid column is `auto`, which floors at
+ *   *min-content* — so a 64-character digest with nothing to break on widened the column and
+ *   pushed the list past its container. `minmax(0, 1fr)` is what stops that, and it is the same
+ *   declaration `Grid`'s fixed counts need for the same reason.
+ *
+ * The colon lives in the sheet rather than in the markup, because it belongs to the inline
+ * layout alone — `aligned` and `stacked` must not have one, and a text node cannot be
+ * withdrawn by a rule. It is decorative either way: the `<dt>` / `<dd>` pairing is what carries
+ * the relationship to assistive tech.
  */
-export function DetailList({ items, ...rest }: DetailListProps) {
+export function DetailList({
+  items,
+  layout = "inline",
+  columns = 1,
+  ...rest
+}: DetailListProps) {
   const text = useUiText();
   return (
-    <dl {...rest} data-terp="detail-list">
+    <dl
+      {...rest}
+      data-terp="detail-list"
+      // `inline` and one column are the base rule, so neither stamps an attribute.
+      data-layout={layout === "inline" ? undefined : layout}
+      data-columns={columns === 1 ? undefined : String(columns)}
+    >
       {items.map((item, index) => (
-        <div key={index}>
-          <dt data-terp="detail-list-term">{text(item.label)}: </dt>
+        <div key={index} data-terp="detail-list-row">
+          <dt data-terp="detail-list-term">{text(item.label)}</dt>
           <dd data-terp="detail-list-value">{item.value}</dd>
         </div>
       ))}

package/src/layoutContract.test.tsx

@@ -1,5 +1,5 @@
 // @vitest-environment jsdom
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { Component } from "react";
 import { afterEach, describe, expect, it } from "vitest";
@@ -11,6 +11,11 @@ import { afterEach, describe, expect, it } from "vitest";
 import * as lintLayouts from "../../eslint-boundaries/src/layouts.js";
 
 import { DetailPage } from "./DetailPage";
+import { FormPage } from "./FormPage";
+import { SettingsPage } from "./SettingsPage";
+import { SplitPage, SplitPane } from "./SplitPage";
+import { Input } from "./ui/Input";
+import { Field } from "./Field";
 import { HubCard, HubPage } from "./HubPage";
 import {
   LAYOUT_CONTRACTS,
@@ -19,8 +24,17 @@ import {
   verifySlotChildren,
 } from "./layoutContract";
 import { OverviewPage } from "./OverviewPage";
+
+// The public surface, as source: the archetype-coverage check below derives its list from
+// the entry point's own exports rather than restating one. `raw.d.ts` declares the ambient
+// ImportMeta.glob type this shares with the other scanning tests in the package.
+const entryPoint = Object.values(
+  import.meta.glob("./index.ts", { query: "?raw", import: "default", eager: true }),
+)[0] as string;
 import { Page } from "./Page";
-import { DetailList, Stack } from "./layout";
+import { EmptyState } from "./EmptyState";
+import { DetailList, Divider, Grid, Stack } from "./layout";
+import { Text } from "./typography";
 import { PageActions } from "./PageActions";
 import { ThemeProvider, ThemeToggle } from "./theme";
 import { Button } from "./ui/Button";
@@ -55,6 +69,30 @@ function underContract(children: ReactNode, contract: string | null = "standard"
   );
 }
 
+/**
+ * Assert that a composition was ACCEPTED — after actually letting the check run.
+ *
+ * The obvious spelling is a false green, and it was the shape every acceptance test in this file
+ * used:
+ *
+ *     await waitFor(() => expect(screen.queryByTestId("refused")).toBeNull());
+ *
+ * `waitFor` retries until its callback stops throwing, so a callback asserting that something is
+ * ABSENT passes on the very first attempt — before `Page`'s `setTimeout(0)` slot check has run at
+ * all. It waits for nothing and can never fail. Nine tests claimed to gate the acceptance half of
+ * ADR 0079 and gated nothing; verified by putting a `Grid` — which the OverviewPage slot table
+ * does not admit — into a governed overview body and watching the suite stay green.
+ *
+ * Flushing one macrotask inside `act` is what makes the assertion mean something: the check has
+ * then either thrown into the boundary or decided the body was legal.
+ */
+async function expectAccepted() {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+  expect(screen.queryByTestId("refused")).toBeNull();
+}
+
 describe("layout contract parity (docs/data can't drift)", () => {
   it("mirrors the eslint-boundaries contract table byte-for-byte", () => {
     expect(JSON.parse(JSON.stringify(LAYOUT_CONTRACTS))).toEqual(
@@ -69,6 +107,124 @@ describe("layout contract parity (docs/data can't drift)", () => {
   });
 });
 
+describe("every archetype the package exports is governed, or says it is not", () => {
+  // The gap this closes was a green build. `verifySlotChildren` returns null for a slot the
+  // table does not name (layoutContract.ts:138-141) and the lint rule early-returns the same
+  // way, so an archetype exported WITHOUT a table entry is silently ungoverned by both halves
+  // of the control — no error, no warning, and a governed app renders it with the body slot
+  // wide open. Nothing asserted the two lists agreed, which means "forgot the table entry"
+  // was indistinguishable from "deliberately unconstrained".
+  //
+  // Derived from the public surface rather than restated as a list, because a list is the
+  // thing that was missing: a new `FormPage` export joins this check by existing, and has to
+  // either take a slot or come here and say why.
+  // Two independent derivations, unioned, because each has a blind spot the other covers.
+  //
+  // The named-export scan reads `export { X } from` and `export { X as Y } from` — the alias
+  // form matters, since the exported name is what a consumer writes. It cannot see
+  // `export * from`, and index.ts already contains one (`./dataview`), so on its own this
+  // derivation would let an archetype re-exported through a sub-namespace escape all three
+  // assertions below INCLUDING the vacuity guard, which is built from the same scan.
+  //
+  // The filename scan covers exactly that: an archetype lives in `<Name>Page.tsx` by
+  // convention, wherever in the tree it sits. It cannot see an archetype declared inside some
+  // other file — which the export scan can.
+  const namedExports = [...entryPoint.matchAll(/^export \{([^}]*)\} from/gm)]
+    .flatMap((match) => match[1]!.split(","))
+    // `A as B` exports B; a bare name exports itself.
+    .map((entry) => entry.trim().split(/\s+as\s+/).pop()!.trim());
+  const archetypeFiles = Object.keys(
+    import.meta.glob("./**/*Page.tsx", { query: "?raw", import: "default", eager: true }),
+  )
+    .filter((file) => !file.includes(".test."))
+    .map((file) => file.split("/").pop()!.replace(/\.tsx$/, ""));
+  const exported = [
+    ...new Set(
+      [...namedExports, ...archetypeFiles]
+        // `endsWith` rather than a `\w*Page$` regex, which cannot match "Page" itself:
+        // after the leading capital there is no "Page" left to match. The vacuity guard below
+        // caught that on the first run, which is the whole reason it is there.
+        .filter((name) => /^[A-Z]\w*$/.test(name) && name.endsWith("Page")),
+    ),
+  ].sort();
+
+  /**
+   * Archetypes with no slot entry, and the reason each is unconstrained.
+   *
+   * One entry, and it is the contract's own pressure valve rather than an omission: the
+   * plain `Page` is what a bespoke screen composes when no archetype fits, and the
+   * contract's description says so in as many words. Anything else added here is a claim
+   * that a screen shape has no vocabulary, which is the claim the table exists to refuse.
+   */
+  const DELIBERATELY_UNCONSTRAINED: Record<string, string> = {
+    Page: "the bespoke pressure valve — a screen no archetype fits composes this, and the contract leaves it open by design",
+  };
+
+  it("finds the archetype exports it is meant to check", () => {
+    // Vacuity guard: a derivation that matched nothing would make every assertion below pass.
+    expect(exported).toEqual([
+      "DetailPage",
+      "FormPage",
+      "HubPage",
+      "OverviewPage",
+      "Page",
+      "SettingsPage",
+      "SplitPage",
+    ]);
+  });
+
+  it("pins the namespace re-exports, which neither derivation can look inside", () => {
+    // `export * from "./x"` is opaque to both scans: the filename scan only sees files named
+    // `*Page.tsx`, and the named-export scan sees no names at all. So the set of namespace
+    // re-exports is pinned instead — adding one is the moment to check it carries no archetype,
+    // and this assertion is what forces that look.
+    const namespaces = [...entryPoint.matchAll(/^export \* from "([^"]+)"/gm)].map(
+      (match) => match[1]!,
+    );
+    expect(namespaces).toEqual(["./dataview"]);
+  });
+
+  it("keeps no excuse for an archetype that is no longer exported", () => {
+    // The reverse-direction test filters these keys out of its comparison, so a stale excuse
+    // changes nothing there and would sit in the file for ever — quietly claiming that a
+    // component nobody exports is deliberately unconstrained.
+    for (const excused of Object.keys(DELIBERATELY_UNCONSTRAINED)) {
+      expect(
+        exported,
+        `${excused} is excused from the slot table but is not an exported archetype — the excuse is stale`,
+      ).toContain(excused);
+    }
+  });
+
+  it("gives every exported archetype a slot, or a named reason for having none", () => {
+    const slots = LAYOUT_CONTRACTS.standard!.slots;
+    for (const archetype of exported) {
+      const governed = archetype in slots;
+      const excused = archetype in DELIBERATELY_UNCONSTRAINED;
+      expect(
+        governed || excused,
+        `${archetype} is exported but has no LAYOUT_CONTRACTS.standard.slots entry, so both ` +
+          "halves of the layout contract silently skip it. Add the slot (in this file AND in " +
+          "eslint-boundaries/src/layouts.js), or add it to DELIBERATELY_UNCONSTRAINED with the " +
+          "reason its body has no vocabulary.",
+      ).toBe(true);
+      expect(
+        governed && excused,
+        `${archetype} is both governed and excused — the excuse is stale, delete it`,
+      ).toBe(false);
+    }
+  });
+
+  it("names no slot that no archetype exports", () => {
+    // The other direction: a slot for an archetype that was renamed or withdrawn is a table
+    // entry nothing can ever satisfy, and the message it phrases names a component that is
+    // no longer there.
+    expect(Object.keys(LAYOUT_CONTRACTS.standard!.slots).sort()).toEqual(
+      exported.filter((name) => !(name in DELIBERATELY_UNCONSTRAINED)),
+    );
+  });
+});
+
 describe("runtime slot enforcement", () => {
   it("refuses a non-HubCard child in a HubPage grid, fail closed, with the directive message", async () => {
     underContract(
@@ -242,14 +398,18 @@ describe("layout contract survives the roots the styling migration renames", ()
       "dataview",
       "detail-list",
       "dialog",
+      "divider",
       "empty-state",
       "error-state",
+      "grid",
       "hubcard",
       "loading-state",
       "module-nav",
       "resource-list",
+      "splitpane",
       "stack",
       "tabs",
+      "text",
     ]);
   });
 
@@ -274,3 +434,152 @@ describe("layout contract survives the roots the styling migration renames", ()
     expect(screen.queryByTestId("refused")).toBeNull();
   });
 });
+
+describe("what 4b's widening does and does not admit", () => {
+  it("accepts a Grid in a detail body, which is the two-column form case", async () => {
+    // The diagnosis's headline evidence was a fifteen-field form shipped as one vertical run.
+    // Shipping `Grid` without this widening would have shipped a component no governed page
+    // could use — and only a copier-generated project has the contract switched on, so the
+    // example app could not have detected that either.
+    underContract(
+      <DetailPage title="Record" parents={[{ label: "Records", to: "/records" }]}>
+        <Grid columns={2}>
+          <span>one</span>
+          <span>two</span>
+        </Grid>
+      </DetailPage>,
+    );
+    await expectAccepted();
+  });
+
+  it("still refuses a Grid in an overview body, because a grid there is a hub", () => {
+    // The asymmetry IS the decision, so it is pinned rather than left to the table. An
+    // overview body is a data collection; a grid of summary cards is a hub, and the contract
+    // has a hub archetype for that. Widening both slots identically would have been the easy
+    // move and would have dissolved the distinction the three levels exist to carry.
+    underContract(
+      <OverviewPage title="Records">
+        <Grid columns={2}>
+          <span>one</span>
+        </Grid>
+      </OverviewPage>,
+    );
+    return waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "OverviewPage", '<div data-terp="grid">'),
+      );
+    });
+  });
+
+  it("refuses a bare Field at the top of a form body, because that form cannot submit", () => {
+    // The one refusal in FormPage's slot that is a decision rather than an omission. A run of
+    // bare fields looks like a finished form and cannot be submitted: Enter does nothing
+    // without a <form>, and the house spelling of one is `Stack as="form"`. So the slot takes
+    // the container and not the fields — which is the opposite of what a reader would guess
+    // from "a form page's body is fields".
+    underContract(
+      <FormPage title="New sync" parents={[{ label: "Syncs", to: "/syncs" }]}>
+        <Field label="Name">
+          <Input />
+        </Field>
+      </FormPage>,
+    );
+    return waitFor(() => {
+      expect(screen.getByTestId("refused")).toHaveTextContent(
+        /the FormPage body slot accepts only Stack \/ Grid \/ Card/,
+      );
+    });
+  });
+
+  it("accepts a form body that is a form container with sections beside it", () => {
+    underContract(
+      <FormPage title="New sync" parents={[{ label: "Syncs", to: "/syncs" }]}>
+        <Text>Every definition needs a source and a target.</Text>
+        <Stack as="form">
+          <Field label="Name">
+            <Input />
+          </Field>
+        </Stack>
+      </FormPage>,
+    );
+    return waitFor(() => {
+      expect(screen.queryByTestId("refused")).not.toBeInTheDocument();
+    });
+  });
+
+  it("refuses a collection in a settings body, because that screen is an overview", () => {
+    // SettingsPage's slot is Card sections and nothing that holds a collection. A settings
+    // screen whose body is a table is an overview with the wrong chrome, and the contract is
+    // where that distinction is enforceable rather than advisory.
+    underContract(
+      <SettingsPage title="Preferences">
+        <DetailList items={[{ label: "Theme", value: "Dark" }]} />
+      </SettingsPage>,
+    );
+    return waitFor(() => {
+      expect(screen.getByTestId("refused")).toHaveTextContent(
+        /the SettingsPage body slot accepts only Card \/ Stack/,
+      );
+    });
+  });
+
+  it("refuses anything but a SplitPane inside a split, and accepts the two panes", async () => {
+    // The split governs its PANE ROW rather than the page body, which is HubPage's shape and
+    // not DetailPage's — so this is the assertion that the choice actually took effect. A
+    // Card dropped straight into the split is the realistic mistake.
+    underContract(
+      <SplitPage title="Syncs">
+        <Card title="Not a pane" />
+      </SplitPage>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused")).toHaveTextContent(
+        /the SplitPage body slot accepts only SplitPane/,
+      );
+    });
+    cleanup();
+    underContract(
+      <SplitPage title="Syncs">
+        <SplitPane role="list" label="Definitions">
+          <DetailList items={[{ label: "Customer master", value: "ok" }]} />
+        </SplitPane>
+        <SplitPane role="detail" label="Selected definition">
+          <Card title="Customer master" />
+        </SplitPane>
+      </SplitPage>,
+    );
+    await waitFor(() => {
+      expect(screen.queryByTestId("refused")).not.toBeInTheDocument();
+    });
+  });
+
+  it("accepts a Divider and a lead paragraph in both governed bodies", async () => {
+    // A rule between sections and a paragraph above them — the two things a body wanted that
+    // needed no container. `Heading` is deliberately NOT admitted: a heading in a governed body
+    // must own its section, and `Card` (plain or boxed) is how a section is owned. A bare
+    // heading with siblings after it is a grouping the contract cannot see.
+    for (const page of [
+      <OverviewPage key="o" title="Records">
+        <Text>Lead paragraph.</Text>
+        <Divider />
+        <EmptyState title="No records yet" />
+      </OverviewPage>,
+      <DetailPage key="d" title="Record" parents={[{ label: "Records", to: "/records" }]}>
+        <Text>Lead paragraph.</Text>
+        <Divider />
+        <DetailList items={[{ label: "Owner", value: "Ada" }]} />
+      </DetailPage>,
+    ]) {
+      cleanup();
+      underContract(page);
+      // Per iteration, not once after the loop. Two separate faults met here and only the
+      // second one mattered. `Page` schedules its check as a setTimeout(0) and clears it on
+      // unmount while RTL's `cleanup` unmounts synchronously, so a single trailing assertion
+      // cancelled the OverviewPage timer and only ever reached the DetailPage. But moving the
+      // assertion inside the loop changed nothing on its own, because the assertion itself
+      // could not fail — see `expectAccepted`. Verified together: an illegal Grid in the
+      // OverviewPage body above is green under either old form and red under this one.
+      await expectAccepted();
+    }
+  });
+});