@terpjs/react-core 0.7.0 → 0.9.0

package/src/download.tsx

@@ -0,0 +1,132 @@
+/**
+ * Handing bytes to the browser as a named download (ADR 0096).
+ *
+ * `useFileDownload` covers the stored-file case: a `FileMeta` id, fetched from the files
+ * capability's content endpoint. What it does not cover is the other half of the same
+ * need — **an artifact the backend generates on demand** ("download this revision as
+ * proof", a CSV export, a signed evidence bundle). Those have no stored file id, and the
+ * only ways to reach them were a raw `fetch` (refused: one typed egress path) or a raw
+ * `<a href>` (which carries no bearer token, so it 401s or, worse, silently downloads an
+ * error page). The observed outcome was the feature being dropped rather than built.
+ *
+ * So the blob-to-anchor dance lives here once, and `useEndpointDownload` reaches any
+ * authorized GET through the session client. `path` is a plain string, deliberately and
+ * unusually: the generated client is keyed by the app's own schema, which this package
+ * cannot see, and a byte-stream route is app-specific by nature. Everything else that
+ * matters — the base URL, the bearer token, cookie credentials, the refusal on a non-2xx —
+ * still comes from the client, which is what the raw alternatives threw away.
+ */
+
+import { useCallback } from "react";
+
+import { useTerpClient } from "./TerpProvider";
+import type { TerpClient } from "@terpjs/contract";
+
+/** What to download: where the bytes come from, and what the file should be called. */
+export interface DownloadTarget {
+  /** API path, e.g. `/api/v1/revisions/{id}/evidence` with `params` filling `{id}`. */
+  path: string;
+  /** Filename offered to the browser (extension included). */
+  filename: string;
+  /** Path placeholders to substitute, e.g. `{ id: revision.id }`. */
+  params?: Record<string, string>;
+  /** Query string to append; `undefined` values are omitted. */
+  query?: Record<string, string | undefined>;
+}
+
+/**
+ * Save *blob* as a named download.
+ *
+ * Exported because it is the one piece a screen cannot avoid re-implementing when it
+ * already holds the bytes (a client-side CSV, a canvas export) — and every hand-rolled
+ * copy leaks the object URL, which is why the revoke is in a `finally` here.
+ */
+export function saveBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  try {
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = filename;
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/** Fill `{placeholder}` segments and append the query string, dropping unset values. */
+export function downloadUrl(target: DownloadTarget): string {
+  let path = target.path;
+  for (const [name, value] of Object.entries(target.params ?? {})) {
+    path = path.replaceAll(`{${name}}`, encodeURIComponent(value));
+  }
+  const unfilled = /\{([A-Za-z_][A-Za-z0-9_]*)\}/.exec(path);
+  if (unfilled !== null) {
+    // Fail closed rather than requesting a literal `{id}`: the server would 404 or, on a
+    // permissive route, hand back somebody else's bytes.
+    throw new Error(
+      `Download path "${target.path}" still contains the placeholder "${unfilled[0]}" — ` +
+        `pass it in \`params\` (e.g. params: { ${unfilled[1]}: row.id }).`,
+    );
+  }
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(target.query ?? {})) {
+    if (value !== undefined) {
+      query.append(name, value);
+    }
+  }
+  const suffix = query.toString();
+  return suffix.length > 0 ? `${path}?${suffix}` : path;
+}
+
+/**
+ * Download a generated artifact from an authorized endpoint (ADR 0096).
+ *
+ * ```tsx
+ * const download = useEndpointDownload();
+ * void download({
+ *   path: "/api/v1/revisions/{revisionId}/evidence",
+ *   params: { revisionId: revision.id },
+ *   filename: `revision-${revision.number}.json`,
+ * });
+ * ```
+ *
+ * Rejects on a non-2xx response, so a caller can surface the failure — a raw anchor would
+ * have saved the error body under the intended filename instead.
+ */
+export function useEndpointDownload(): (target: DownloadTarget) => Promise<void> {
+  const client = useTerpClient();
+  return useCallback(
+    async (target: DownloadTarget) => {
+      const blob = await fetchDownload(client as unknown as TerpClient, target);
+      saveBlob(blob, target.filename);
+    },
+    [client],
+  );
+}
+
+/**
+ * Fetch a download target's bytes through the session client.
+ *
+ * Separate from the hook so a caller that wants the blob for something *other* than
+ * saving it (a preview, a checksum) does not have to save it first.
+ */
+export async function fetchDownload(client: TerpClient, target: DownloadTarget): Promise<Blob> {
+  const url = downloadUrl(target);
+  const { data, error, response } = await (
+    client as unknown as {
+      GET: (
+        path: string,
+        init: { parseAs: "blob" },
+      ) => Promise<{ data?: unknown; error?: unknown; response: Response }>;
+    }
+  ).GET(url, { parseAs: "blob" });
+  if (error !== undefined || !response.ok) {
+    throw new Error(
+      `Download of ${url} failed with HTTP ${response.status}. The endpoint must be a GET ` +
+        "the current session is authorized for.",
+    );
+  }
+  return data as Blob;
+}

package/src/feedback.test.tsx

@@ -82,6 +82,32 @@ describe("ConfirmDialog", () => {
     expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
   });
 
+  it("links the consequence text to the dialog, and only when there is one", () => {
+    const { rerender } = render(
+      <ConfirmDialog
+        open
+        onOpenChange={() => {}}
+        onConfirm={() => {}}
+        title="Delete this link?"
+        description="Its mappings and its run history are removed with it."
+      />,
+    );
+    // A modal announces its name and its description on open. Unlinked body copy is reached
+    // only by manual exploration — the wrong ergonomics for the one screen whose whole job is
+    // telling someone what a destructive action will do.
+    const dialog = screen.getByRole("dialog");
+    const describedBy = dialog.getAttribute("aria-describedby");
+    expect(describedBy).not.toBeNull();
+    expect(document.getElementById(describedBy!)?.textContent).toBe(
+      "Its mappings and its run history are removed with it.",
+    );
+    // No description means no attribute, rather than an idref pointing at nothing.
+    rerender(
+      <ConfirmDialog open onOpenChange={() => {}} onConfirm={() => {}} title="Delete this link?" />,
+    );
+    expect(screen.getByRole("dialog")).not.toHaveAttribute("aria-describedby");
+  });
+
   it("confirms and cancels through the labelled buttons", () => {
     const onConfirm = vi.fn();
     const onOpenChange = vi.fn();

package/src/files.test.tsx

@@ -71,6 +71,24 @@ describe("FileUpload", () => {
     await waitFor(() => expect(onUploaded).toHaveBeenCalledWith(STORED));
   });
 
+  it("hides the picker input with the hidden attribute, not an inline style", () => {
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <FileUpload />
+      </TerpProvider>,
+    );
+    // The visible control is the button; this input exists only so a programmatic click can
+    // open the native dialog. `hidden` is the platform's own way to say that, and it keeps the
+    // file free of a style object that would read as unmigrated styling.
+    const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+    expect(input).not.toBeNull();
+    expect(input.hidden).toBe(true);
+    expect(input.getAttribute("style")).toBeNull();
+    // Belt and braces, kept deliberately: both survive an author rule that resurrects the box.
+    expect(input).toHaveAttribute("aria-hidden", "true");
+    expect(input.tabIndex).toBe(-1);
+  });
+
   it("reports a failed upload through onError", async () => {
     stubFetch(async (request) => {
       if (request.url.endsWith("/api/v1/files/") && request.method === "POST") {

package/src/files.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useRef, useState } from "react";
-import type { ChangeEvent, CSSProperties } from "react";
+import type { ChangeEvent } from "react";
 
+import { saveBlob } from "./download";
 import { useTerpClient } from "./TerpProvider";
 import { Button } from "./ui/Button";
 import { useStrings, useUiText, type UiText } from "./uiText";
@@ -91,24 +92,12 @@ export function useFileDownload(): (file: Pick<FileMeta, "id" | "filename">) =>
   return useCallback(
     async (file: Pick<FileMeta, "id" | "filename">) => {
       const blob = await fetchFileContent(client as unknown as TerpClient, file.id);
-      const url = URL.createObjectURL(blob);
-      try {
-        const anchor = document.createElement("a");
-        anchor.href = url;
-        anchor.download = file.filename;
-        document.body.appendChild(anchor);
-        anchor.click();
-        anchor.remove();
-      } finally {
-        URL.revokeObjectURL(url);
-      }
+      saveBlob(blob, file.filename);
     },
     [client],
   );
 }
 
-const hiddenInputStyle: CSSProperties = { display: "none" };
-
 export interface FileUploadProps {
   /** Called with the stored metadata after a successful upload. */
   onUploaded?: (file: FileMeta) => void;
@@ -152,11 +141,22 @@ export function FileUpload({ onUploaded, onError, label, accept, disabled }: Fil
 
   return (
     <>
+      {/* The platform attribute, not an inline display:none.
+
+          This input is the file picker's plumbing: the visible control is the Button below,
+          and this element exists only so `.click()` can open the native dialog. So it is not
+          a styled surface at all, and the alternatives both misdescribe it — giving it a
+          marker and a `display: none` rule would put a component with no visual design into
+          the sheet, and keeping the inline object would leave the one declaration in the file
+          looking like styling that had not been migrated yet. `hidden` is what HTML provides
+          for "not relevant", and a programmatic click still opens the dialog. The
+          `aria-hidden` and `tabIndex` become redundant beside it and are kept anyway: they
+          cost nothing and they survive an author rule that resurrects the box. */}
       <input
         ref={inputRef}
         type="file"
         accept={accept}
-        style={hiddenInputStyle}
+        hidden
         onChange={(event) => void onChange(event)}
         aria-hidden="true"
         tabIndex={-1}

package/src/icons.test.tsx

@@ -11,7 +11,10 @@ describe("NavIcon", () => {
     const { container } = render(<NavIcon name="users" label="Users" />);
     const slot = container.querySelector('[data-terp="nav-icon"]');
     const svg = container.querySelector("svg");
-    expect(slot).toHaveStyle({ width: "1.25rem", height: "1.25rem", flex: "0 0 1.25rem" });
+    // The rail slot's fixed 1.25rem box is a sheet rule now (ADR 0094); what this test
+    // owns is that the named glyph resolved and stayed decorative.
+    expect(slot).not.toBeNull();
+    expect(slot?.getAttribute("style")).toBeNull();
     expect(svg).not.toBeNull();
     expect(svg).toHaveAttribute("aria-hidden", "true");
   });
@@ -19,11 +22,12 @@ describe("NavIcon", () => {
   it("falls back to the label's initial for an unknown or missing name", () => {
     const { container } = render(<NavIcon name="no-such-glyph" label="widgets" />);
     expect(screen.getByText("W")).toBeInTheDocument();
-    expect(container.querySelector('[data-terp="nav-icon"]')).toHaveStyle({
-      width: "1.25rem",
-      height: "1.25rem",
-      flex: "0 0 1.25rem",
-    });
+    // The fallback tile is its own marker, so the rail can style "an initial in a tile"
+    // separately from "a glyph" — which is the distinction a theme cares about.
+    expect(
+      container.querySelector('[data-terp="nav-icon-fallback"]'),
+      "the initial renders in the fallback tile",
+    ).not.toBeNull();
     render(<NavIcon label="records" />);
     expect(screen.getByText("R")).toBeInTheDocument();
   });

package/src/icons.tsx

@@ -1,4 +1,8 @@
-import type { CSSProperties, ReactNode } from "react";
+import type { ReactNode } from "react";
+
+import { injectTerpStyles } from "./styles";
+
+injectTerpStyles();
 
 /**
  * The dependency-free icon layer: a small set of inline SVG glyphs the shell's
@@ -431,31 +435,6 @@ export const ICON_GLYPHS: Record<string, ReactNode> = {
   ),
 };
 
-const navIconStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "1.25rem",
-  height: "1.25rem",
-  flex: "0 0 1.25rem",
-  fontSize: "1rem",
-  lineHeight: 1,
-};
-
-const fallbackStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  justifyContent: "center",
-  width: "100%",
-  height: "100%",
-  borderRadius: "var(--radius-sm, 4px)",
-  background: "var(--color-brand-primary-soft, var(--color-neutral-200))",
-  color: "var(--color-brand-primary, var(--color-neutral-700))",
-  fontSize: "0.7em",
-  fontWeight: "var(--font-weight-medium)" as CSSProperties["fontWeight"],
-  lineHeight: 1,
-};
-
 export interface NavIconProps {
   /** Glyph name (a `NavItem.icon` value); unknown / missing falls back to the initial. */
   name?: string;
@@ -470,9 +449,9 @@ export interface NavIconProps {
 export function NavIcon({ name, label }: NavIconProps) {
   const glyph = name !== undefined ? ICON_GLYPHS[name] : undefined;
   return (
-    <span aria-hidden="true" data-terp="nav-icon" style={navIconStyle}>
+    <span aria-hidden="true" data-terp="nav-icon">
       {glyph ?? (
-        <span style={fallbackStyle}>
+        <span data-terp="nav-icon-fallback">
           {(label[0] ?? "?").toUpperCase()}
         </span>
       )}
@@ -511,15 +490,8 @@ export function Icon({ name, size = "1em", title }: IconProps) {
       aria-hidden={labelled ? undefined : true}
       role={labelled ? "img" : undefined}
       aria-label={labelled ? title : undefined}
-      style={{
-        display: "inline-flex",
-        alignItems: "center",
-        justifyContent: "center",
-        width: px,
-        height: px,
-        lineHeight: 1,
-        color: "inherit",
-      }}
+      data-terp="icon"
+      style={{ width: px, height: px }}
     >
       {glyph}
     </span>

package/src/index.ts

@@ -8,7 +8,7 @@ export { canPerform, DEFAULT_RANK_THRESHOLDS } from "./capabilities";
 export type { RankThresholds } from "./capabilities";
 export { createAuthClient } from "./createAuthClient";
 export type { AuthClientOptions, TokenGetter } from "./createAuthClient";
-export { Authorized, useCan } from "./Authorized";
+export { Authorized, useCan, useHasPermission, usePermissions } from "./Authorized";
 export type { AuthorizedProps } from "./Authorized";
 export { useResource } from "./useResource";
 export type { Resource, ResourceSource } from "./useResource";
@@ -30,9 +30,6 @@ export type { RequireAuthProps } from "./RequireAuth";
 export { visibleNav } from "./nav";
 export {
   AppShell,
-  NAV_LINK_STYLE,
-  NAV_LINK_COLLAPSED_STYLE,
-  NAV_LINK_ACTIVE_STYLE,
   SIDEBAR_STORAGE_KEY,
 } from "./AppShell";
 export type {
@@ -112,6 +109,8 @@ export { Alert } from "./ui/Alert";
 export type { AlertProps, AlertTone } from "./ui/Alert";
 export { Markdown } from "./ui/Markdown";
 export type { MarkdownProps } from "./ui/Markdown";
+export { saveBlob, useEndpointDownload, fetchDownload, downloadUrl } from "./download";
+export type { DownloadTarget } from "./download";
 export { Field } from "./Field";
 export type { FieldProps } from "./Field";
 export { Stack, DetailList } from "./layout";
@@ -122,6 +121,7 @@ export {
   PROFILE_PATH,
   useRouteParam,
   useRouteParams,
+  useRouteSearch,
   useTerpNavigate,
 } from "./router";
 export type { BuildAppRouterOptions } from "./router";
@@ -132,6 +132,9 @@ export type {
   TerpRouteParamName,
   TerpRouteParams,
   TerpRoutePath,
+  TerpRouteSearch,
+  TerpRouteSearchKey,
+  TerpRouteSearchTable,
   TerpRouteTable,
 } from "./routeTypes";
 export { LoginView } from "./LoginView";

package/src/layout.test.tsx

@@ -7,7 +7,7 @@ import { DetailList, Stack } from "./layout";
 afterEach(cleanup);
 
 describe("Stack", () => {
-  it("renders a flex column with a token gap by default", () => {
+  it("names a column at the default gap, with no inline styling", () => {
     render(
       <Stack data-testid="stack">
         <span>a</span>
@@ -16,24 +16,39 @@ describe("Stack", () => {
     );
     const el = screen.getByTestId("stack");
     expect(el.tagName).toBe("DIV");
-    expect(el.style.display).toBe("flex");
-    expect(el.style.flexDirection).toBe("column");
-    expect(el.style.gap).toBe("var(--space-2)");
+    expect(el).toHaveAttribute("data-direction", "column");
+    expect(el).toHaveAttribute("data-gap", "2");
+    expect(el).not.toHaveAttribute("data-wrap");
+    expect(el.getAttribute("style")).toBeNull();
   });
 
-  it("renders the requested element with direction, gap, alignment and wrap", () => {
+  it("renders the requested element and names direction, gap and wrap", () => {
     render(
-      <Stack data-testid="row" as="section" direction="row" gap={4} align="center" justify="space-between" wrap>
+      <Stack data-testid="row" as="section" direction="row" gap={4} wrap>
         <span>a</span>
       </Stack>,
     );
     const el = screen.getByTestId("row");
     expect(el.tagName).toBe("SECTION");
-    expect(el.style.flexDirection).toBe("row");
-    expect(el.style.gap).toBe("var(--space-4)");
+    expect(el).toHaveAttribute("data-direction", "row");
+    expect(el).toHaveAttribute("data-gap", "4");
+    expect(el).toHaveAttribute("data-wrap", "true");
+    expect(el.getAttribute("style")).toBeNull();
+  });
+
+  it("keeps alignment inline, because it is an open set of CSS keywords", () => {
+    // align/justify accept any alignment keyword, so they cannot become a rule per value
+    // without inventing a vocabulary CSS already has (ADR 0094). They stay inline, and
+    // the geometry attributes stay attributes — the two halves of the same element.
+    render(
+      <Stack data-testid="aligned" align="center" justify="space-between">
+        <span>a</span>
+      </Stack>,
+    );
+    const el = screen.getByTestId("aligned");
     expect(el.style.alignItems).toBe("center");
     expect(el.style.justifyContent).toBe("space-between");
-    expect(el.style.flexWrap).toBe("wrap");
+    expect(el.style.display).toBe("");
   });
 
   it("works as a form (submit handler fires)", () => {

package/src/layout.tsx

@@ -38,16 +38,27 @@ export function Stack({
   wrap = false,
   ...rest
 }: StackProps) {
-  const style: CSSProperties = {
-    display: "flex",
-    flexDirection: direction,
-    gap: `var(--space-${gap})`,
-    margin: 0,
-    ...(align !== undefined ? { alignItems: align } : undefined),
-    ...(justify !== undefined ? { justifyContent: justify } : undefined),
-    ...(wrap ? { flexWrap: "wrap" } : undefined),
-  };
-  return <Component {...rest} data-terp="stack" style={style} />;
+  // `direction`, `gap` and `wrap` are closed sets, so they are attributes the sheet keys
+  // on. `align` and `justify` take any alignment keyword CSS accepts, so they stay inline
+  // rather than turning an open vocabulary into a rule per value (ADR 0094). Undefined on
+  // both means no style attribute at all.
+  const alignment: CSSProperties | undefined =
+    align === undefined && justify === undefined
+      ? undefined
+      : {
+          ...(align !== undefined ? { alignItems: align } : undefined),
+          ...(justify !== undefined ? { justifyContent: justify } : undefined),
+        };
+  return (
+    <Component
+      {...rest}
+      data-terp="stack"
+      data-direction={direction}
+      data-gap={String(gap)}
+      data-wrap={wrap ? "true" : undefined}
+      style={alignment}
+    />
+  );
 }
 
 export interface DetailItem {
@@ -62,14 +73,6 @@ export interface DetailListProps extends Omit<HTMLAttributes<HTMLDListElement>,
   items: readonly DetailItem[];
 }
 
-const detailListStyle: CSSProperties = {
-  margin: 0,
-  display: "grid",
-  gap: "var(--space-1)",
-};
-const detailTermStyle: CSSProperties = { display: "inline", fontWeight: "var(--font-weight-medium)" };
-const detailValueStyle: CSSProperties = { display: "inline", margin: 0 };
-
 /**
  * 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
@@ -78,11 +81,11 @@ const detailValueStyle: CSSProperties = { display: "inline", margin: 0 };
 export function DetailList({ items, ...rest }: DetailListProps) {
   const text = useUiText();
   return (
-    <dl {...rest} data-terp="detail-list" style={detailListStyle}>
+    <dl {...rest} data-terp="detail-list">
       {items.map((item, index) => (
         <div key={index}>
-          <dt style={detailTermStyle}>{text(item.label)}: </dt>
-          <dd style={detailValueStyle}>{item.value}</dd>
+          <dt data-terp="detail-list-term">{text(item.label)}: </dt>
+          <dd data-terp="detail-list-value">{item.value}</dd>
         </div>
       ))}
     </dl>

package/src/layoutContract.test.tsx

@@ -21,6 +21,9 @@ import {
 import { OverviewPage } from "./OverviewPage";
 import { Page } from "./Page";
 import { DetailList, Stack } from "./layout";
+import { PageActions } from "./PageActions";
+import { ThemeProvider, ThemeToggle } from "./theme";
+import { Button } from "./ui/Button";
 import { Card } from "./ui/Card";
 
 afterEach(cleanup);
@@ -179,3 +182,95 @@ describe("runtime slot enforcement", () => {
     expect(verifySlotChildren("standard", "Page", [])).toBeNull();
   });
 });
+
+// The styling migration (ADR 0094) is renaming rendered roots: components that used to emit
+// an unmarked <div>, or to borrow Popover's `popover`, now name themselves. Every one of those
+// names is read by this check, because the check IS the marker join — so the question is not
+// whether the names look sensible but whether any slot's verdict moved.
+//
+// It did not, and the reason is worth stating rather than re-derived: verifySlotChildren
+// refuses a direct body-slot child whose data-terp is not in the slot's allow table, and a
+// missing attribute is refused too (`marker === null`). None of the new names is in any table,
+// and neither was the unmarked element each replaced. So each of these was refused before the
+// migration and is refused after it. What changed is the MESSAGE — describeElement now reports
+// a named component instead of a bare tag, which is strictly more useful to the person reading
+// the refusal, and is also a string a test could have pinned.
+describe("layout contract survives the roots the styling migration renames", () => {
+  it("still refuses a chrome menu in a governed body, and now names it", async () => {
+    underContract(
+      // The provider renders no element of its own, so the slot's direct child is still the
+      // toggle. Without it ThemeToggle returns null and the body is empty — which passes for
+      // no reason at all.
+      <ThemeProvider>
+        <OverviewPage title="Records">
+          <ThemeToggle variant="stacked" />
+        </OverviewPage>
+      </ThemeProvider>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "OverviewPage", '<div data-terp="theme-toggle">'),
+      );
+    });
+  });
+
+  it("still refuses an action cluster in a governed body, and now names it", async () => {
+    underContract(
+      <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+        <PageActions primary={<Button>Publish</Button>} />
+      </DetailPage>,
+    );
+    await waitFor(() => {
+      expect(screen.getByTestId("refused").textContent).toBe(
+        slotViolationMessage("standard", "DetailPage", '<div data-terp="page-actions">'),
+      );
+    });
+  });
+
+  it("keeps every marker the allow tables name out of the migration's way", () => {
+    // The tables are the audit surface: a rename of one of THESE would widen or close a slot
+    // silently, so they are the markers the migration may not touch without changing both
+    // halves of the contract. Asserted as a set so an addition has to be deliberate.
+    const named = new Set(
+      Object.values(LAYOUT_CONTRACTS.standard!.slots).flatMap((slot) =>
+        Object.values(slot.components),
+      ),
+    );
+    expect([...named].sort()).toEqual([
+      "alert",
+      "card",
+      "dataview",
+      "detail-list",
+      "dialog",
+      "empty-state",
+      "error-state",
+      "hubcard",
+      "loading-state",
+      "module-nav",
+      "resource-list",
+      "stack",
+      "tabs",
+    ]);
+  });
+
+  it("passes a governed body whose children are still allowed components", async () => {
+    // The other direction: the migration must not have widened anything either. A Stack and a
+    // Card are allowed, and they stay allowed with their markers unchanged.
+    underContract(
+      <ThemeProvider>
+        <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+          <Card title="A section">body</Card>
+          <Stack>
+            <ThemeToggle variant="stacked" />
+          </Stack>
+        </DetailPage>
+      </ThemeProvider>,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    // And the toggle really did render, or this asserts nothing.
+    expect(document.querySelector('[data-terp="theme-toggle"]')).not.toBeNull();
+    // Nested inside an allowed container is sanctioned composition — the check reads direct
+    // children only, which is what makes a marked root safe to put anywhere below one.
+    expect(screen.queryByTestId("refused")).toBeNull();
+  });
+});