@terpjs/react-core 0.8.0 → 0.10.0

package/src/router.test.tsx

@@ -5,9 +5,16 @@ import { useEffect, useState } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ModuleManifest } from "@terpjs/contract";
 
-import { buildAppRouter, useRouteParam, useRouteParams, useTerpNavigate } from "./router";
+import {
+  buildAppRouter,
+  useRouteParam,
+  useRouteParams,
+  useRouteSearch,
+  useTerpNavigate,
+} from "./router";
 import { Page } from "./Page";
 import { TerpProvider, useAuth } from "./TerpProvider";
+import { useNavLink } from "./navLink";
 
 function jsonResponse(body: unknown): Response {
   return new Response(JSON.stringify(body), {
@@ -303,6 +310,190 @@ describe("buildAppRouter", () => {
     );
   });
 
+  it("useRouteSearch reads the route's declared query-string keys, absent ones as undefined", async () => {
+    // The hole this closes: a list screen's filters live in the query string, so before
+    // search was declarable EVERY filtered screen left the typed seam for the router's own
+    // useSearch — losing path and param checking too, on the majority of screens.
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const { status, page } = useRouteSearch("/records");
+      return (
+        <Page title="Records">
+          <p>{`status=${status ?? "-"} page=${page ?? "-"}`}</p>
+        </Page>
+      );
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [
+              {
+                name: "records",
+                routes: [{ path: "/records", view: "List", search: ["status", "page"] }],
+              },
+            ],
+            {
+              views: { List: ListView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/records?status=open"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    // `status` came from the URL; `page` is declared but unset, which is `undefined` rather
+    // than a missing key a screen has to guard.
+    expect(await screen.findByText("status=open page=-")).toBeInTheDocument();
+  });
+
+  it("useRouteSearch returns only declared keys, so a stray URL key cannot reach a screen", async () => {
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const search = useRouteSearch("/records") as Record<string, string | undefined>;
+      return <Page title="Records">{`keys=${Object.keys(search).join(",") || "none"}`}</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "records", routes: [{ path: "/records", view: "List", search: ["status"] }] }],
+            {
+              views: { List: ListView },
+              title: "Terp",
+              history: createMemoryHistory({
+                initialEntries: ["/records?status=open&smuggled=yes"],
+              }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    expect(await screen.findByText("keys=status")).toBeInTheDocument();
+  });
+
+  it("useRouteSearch refuses a path the router never mounted, naming what is mounted", async () => {
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      // A silently empty bag would hand the screen `undefined` for every key it asked
+      // for, which reads as "no filters applied" — the failure this refusal replaces.
+      let message = "no refusal";
+      try {
+        (useRouteSearch as (path: string) => unknown)("/typo");
+      } catch (error) {
+        message = (error as Error).message;
+      }
+      return <Page title="Records">{message}</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter([{ name: "records", routes: [{ path: "/records", view: "List" }] }], {
+            views: { List: ListView },
+            title: "Terp",
+            history: createMemoryHistory({ initialEntries: ["/records"] }),
+          })}
+        />
+      </TerpProvider>,
+    );
+
+    expect(await screen.findByText(/is not a mounted route/)).toBeInTheDocument();
+    expect(screen.getByText(/mounted: \/records/)).toBeInTheDocument();
+  });
+
+  it("useTerpNavigate carries search onto the URL, and clearing a key removes it", async () => {
+    // Replace, not merge (ADR 0096): clearing a filter means sending the key as
+    // undefined, and a merge would keep the old value — so "clear" would not clear.
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const navigate = useTerpNavigate();
+      const { status } = useRouteSearch("/records");
+      return (
+        <Page title="Records">
+          <p>{`status=${status ?? "-"}`}</p>
+          <button
+            type="button"
+            onClick={() => void navigate({ to: "/records", search: { status: "open" } })}
+          >
+            filter open
+          </button>
+          <button
+            type="button"
+            onClick={() => void navigate({ to: "/records", search: { status: undefined } })}
+          >
+            clear
+          </button>
+        </Page>
+      );
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "records", routes: [{ path: "/records", view: "List", search: ["status"] }] }],
+            {
+              views: { List: ListView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/records"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    fireEvent.click(await screen.findByRole("button", { name: "filter open" }));
+    await waitFor(() => expect(screen.getByText("status=open")).toBeInTheDocument());
+
+    fireEvent.click(screen.getByRole("button", { name: "clear" }));
+    await waitFor(() => expect(screen.getByText("status=-")).toBeInTheDocument());
+  });
+
+  it("a second composed router does not inherit the first one's declared searches", async () => {
+    // The declarations are published per router through a context, not a module-level
+    // table: a shared table would let one app embedding another (or one test process
+    // composing two) read routes it never mounted.
+    vi.stubGlobal("fetch", sessionFetch());
+    buildAppRouter([{ name: "a", routes: [{ path: "/a", view: "V", search: ["x"] }] }], {
+      views: { V: () => <Page title="A">a</Page> },
+      title: "Terp",
+      history: createMemoryHistory({ initialEntries: ["/a"] }),
+    });
+
+    function BView() {
+      let message = "no refusal";
+      try {
+        (useRouteSearch as (path: string) => unknown)("/a");
+      } catch (error) {
+        message = (error as Error).message;
+      }
+      return <Page title="B">{message}</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter([{ name: "b", routes: [{ path: "/b", view: "V" }] }], {
+            views: { V: BView },
+            title: "Terp",
+            history: createMemoryHistory({ initialEntries: ["/b"] }),
+          })}
+        />
+      </TerpProvider>,
+    );
+
+    expect(await screen.findByText(/"\/a" is not a mounted route/)).toBeInTheDocument();
+  });
+
   it("gives breadcrumbs and hub cards the router's link without being asked", async () => {
     // A crumb rendered without `renderLink` used to fall back to a raw <a href>: a full
     // page reload, silently, with nothing to catch it. Inside a Terp router the default
@@ -412,7 +603,7 @@ describe("buildAppRouter", () => {
 
     // The sidebar's user menu shows the signed-in user's email; sign-out lives inside it.
     await waitFor(() => expect(screen.getByText("editor@example.com")).toBeInTheDocument());
-    fireEvent.click(screen.getByRole("button", { name: "Account menu" }));
+    fireEvent.click(screen.getByRole("button", { name: /editor@example\.com/ }));
     // Clicking sign-out revokes the token server-side (ADR 0031).
     fireEvent.click(screen.getByRole("menuitem", { name: "Sign out" }));
     await waitFor(() =>
@@ -535,7 +726,7 @@ describe("buildAppRouter", () => {
     );
 
     await waitFor(() => expect(screen.getByText("editor@example.com")).toBeInTheDocument());
-    fireEvent.click(screen.getByRole("button", { name: "Account menu" }));
+    fireEvent.click(screen.getByRole("button", { name: /editor@example\.com/ }));
     fireEvent.click(screen.getByRole("menuitem", { name: "Settings" }));
 
     await waitFor(() =>
@@ -576,3 +767,575 @@ describe("buildAppRouter", () => {
     );
   });
 });
+
+describe("buildAppRouter — which nav item is current (ADR 0097 §6, amended in 4e)", () => {
+  // A nav where one destination is an ancestor of another. This is not a contrived shape: the
+  // packaged admin module ships `/admin` and the example app adds `/admin/grants` and
+  // `/admin/webhooks` beside it, so every generated app has it.
+  const nested: ModuleManifest[] = [
+    { name: "home", routes: [{ path: "/", view: "Home" }], nav: [{ label: "Home", to: "/" }] },
+    {
+      name: "settings",
+      routes: [
+        { path: "/settings", view: "Settings" },
+        { path: "/settings/users", view: "SettingsUsers" },
+        { path: "/settings/appearance", view: "SettingsAppearance" },
+      ],
+      nav: [
+        { label: "Settings", to: "/settings" },
+        { label: "Members", to: "/settings/users" },
+      ],
+    },
+  ];
+  const nestedViews = {
+    Home: () => <Page title="Home view">home</Page>,
+    Settings: () => <Page title="Settings view">settings</Page>,
+    SettingsUsers: () => <Page title="Members view">members</Page>,
+    SettingsAppearance: () => <Page title="Appearance view">appearance</Page>,
+  };
+
+  async function renderAt(path: string) {
+    vi.stubGlobal("fetch", sessionFetch());
+    const router = buildAppRouter(nested, {
+      views: nestedViews,
+      title: "Terp",
+      history: createMemoryHistory({ initialEntries: [path] }),
+    });
+    const result = render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+    await waitFor(() =>
+      expect(document.querySelector('[data-terp="appshell-nav"] a')).not.toBeNull(),
+    );
+    return result;
+  }
+
+  /** Every nav link the shell rendered that claims to be the current page. */
+  function currentLinks(): string[] {
+    return [...document.querySelectorAll('[data-terp="appshell-nav"] a[aria-current="page"]')].map(
+      (a) => a.getAttribute("href") ?? "",
+    );
+  }
+
+  it("names exactly one current item where a per-link predicate names two", async () => {
+    // The defect. The router decides `isActive` per link with no knowledge of siblings, and
+    // before 4e the adapter left every item prefix-matching — so at /settings/users BOTH
+    // /settings and /settings/users carried aria-current="page", both painted, and a screen
+    // reader announced two current pages.
+    await renderAt("/settings/users");
+    await waitFor(() => expect(currentLinks()).toEqual(["/settings/users"]));
+  });
+
+  it("keeps the ancestor current on a page that is not itself a nav item", async () => {
+    // The other half, and why per-item `exact` is not the fix: /settings/appearance is a real
+    // route with no nav entry, so making /settings exact would leave the sidebar with nothing
+    // current at all.
+    await renderAt("/settings/appearance");
+    await waitFor(() => expect(currentLinks()).toEqual(["/settings"]));
+  });
+
+  it("does not let the root item claim a page it does not own", async () => {
+    // `/` prefixes every path as a string. The adapter used to work around that with a
+    // hand-written `exact: item.to === "/"`; the predicate matches on segments instead, so the
+    // workaround is gone and the behaviour is unchanged.
+    await renderAt("/settings");
+    await waitFor(() => expect(currentLinks()).toEqual(["/settings"]));
+  });
+
+  it("keeps the router from volunteering a second current item", async () => {
+    // The mechanism, asserted directly rather than through its effect. `data-status` is the one
+    // attribute only the router writes, so it shows what the router thought independently of
+    // what the shell told it. With activeOptions.exact it can only agree.
+    await renderAt("/settings/users");
+    await waitFor(() =>
+      expect(
+        document.querySelectorAll('[data-terp="appshell-nav"] a[data-status="active"]'),
+      ).toHaveLength(1),
+    );
+  });
+});
+
+describe("AppShell without activePath", () => {
+  it("claims nothing when nobody tells it where it is", async () => {
+    // The absent-prop half of the density idiom. A bare shell must not invent a current item —
+    // and the nine workbench specimens depend on this, because they supply aria-current from
+    // their own renderLink and would otherwise fight the shell.
+    const { AppShell } = await import("./AppShell");
+    render(
+      <AppShell
+        title="Terp"
+        nav={[{ label: "Notes", to: "/notes" }]}
+        renderLink={(item, children, { active }) => (
+          <a href={item.to} aria-current={active ? "page" : undefined}>
+            {children}
+          </a>
+        )}
+      >
+        <p>body</p>
+      </AppShell>,
+    );
+    expect(document.querySelectorAll('[aria-current="page"]')).toHaveLength(0);
+  });
+});
+
+describe("buildAppRouter — the shell's navigation subscription", () => {
+  it("keeps the published link renderer stable across a navigation", async () => {
+    // A gate for a fix, not for a feature. Reading the pathname makes `Shell` re-render on every
+    // navigation, where before it re-rendered only when the session changed. `Outlet` is
+    // memoised with no props, so a plain re-render stops at that boundary — but a CONTEXT VALUE
+    // punches through a memo bailout, and this value is used AS A COMPONENT (Breadcrumbs and
+    // HubCard render it through useNavLink). An unstable identity therefore remounts every
+    // in-app link in the tree on each navigation, which is worse than the re-render it looks
+    // like. The assertion is reference equality, because that is the actual contract.
+    vi.stubGlobal("fetch", sessionFetch());
+    const seen: unknown[] = [];
+    function Probe() {
+      seen.push(useNavLink());
+      return null;
+    }
+    const probeManifests: ModuleManifest[] = [
+      {
+        name: "home",
+        routes: [
+          { path: "/", view: "Home" },
+          { path: "/notes", view: "NotesList" },
+        ],
+        nav: [
+          { label: "Home", to: "/" },
+          { label: "Notes", to: "/notes" },
+        ],
+      },
+    ];
+    const router = buildAppRouter(probeManifests, {
+      views: {
+        Home: () => (
+          <Page title="Home view">
+            <Probe />
+          </Page>
+        ),
+        NotesList: () => (
+          <Page title="Notes view">
+            <Probe />
+          </Page>
+        ),
+      },
+      title: "Terp",
+      history: createMemoryHistory({ initialEntries: ["/"] }),
+    });
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+    await waitFor(() => expect(seen.length).toBeGreaterThan(0));
+    const before = seen.at(-1);
+
+    await router.navigate({ to: "/notes" });
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Notes view" })).toBeInTheDocument(),
+    );
+
+    expect(seen.at(-1)).toBe(before);
+    expect(new Set(seen).size).toBe(1);
+  });
+});
+
+describe("buildAppRouter — a declared permission gates the ROUTE, not just the link", () => {
+  // The asymmetry this exists to prevent: hiding a nav link while leaving its route reachable by
+  // URL is not a weaker form of authorization, it is the appearance of one. `role` has never had
+  // that gap — it is declared on both NavItem and ModuleRoute — and `permission` does not get to
+  // introduce it. The mutation that motivated this test (gate the route on `role` alone) left the
+  // whole suite green.
+  const gated: ModuleManifest[] = [
+    {
+      name: "billing",
+      routes: [{ path: "/export", view: "Export", permission: "billing.export" }],
+      nav: [{ label: "Export", to: "/export", permission: "billing.export" }],
+    },
+  ];
+  const gatedViews = { Export: () => <Page title="Export view">export body</Page> };
+
+  function sessionWithPermissions(permissions: string[]) {
+    return vi.fn<typeof fetch>(async (input) => {
+      const url = (input as Request).url;
+      if (url.endsWith("/api/v1/auth/login")) {
+        return jsonResponse({ access_token: "t", token_type: "bearer" });
+      }
+      return jsonResponse({
+        id: "1",
+        email: "editor@example.com",
+        role_rank: 20,
+        role_name: "editor",
+        permissions,
+      });
+    });
+  }
+
+  async function renderWith(permissions: string[]) {
+    vi.stubGlobal("fetch", sessionWithPermissions(permissions));
+    const router = buildAppRouter(gated, {
+      views: gatedViews,
+      title: "Terp",
+      history: createMemoryHistory({ initialEntries: ["/export"] }),
+    });
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+  }
+
+  it("renders the view when the grant is held", async () => {
+    await renderWith(["billing.export"]);
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Export view" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("link", { name: "Export" })).toBeInTheDocument();
+  });
+
+  it("refuses the route when the grant is missing, even though the rank clears", async () => {
+    // rank 20 clears every role floor this manifest declares — the ONLY thing withheld is the
+    // named grant, so a route gated on `role` alone would render the page in full.
+    await renderWith([]);
+    await waitFor(() =>
+      expect(screen.getByText("You do not have access to this page.")).toBeInTheDocument(),
+    );
+    expect(screen.queryByRole("heading", { name: "Export view" })).not.toBeInTheDocument();
+    // ...and the link is gone too, which is the half that was already working.
+    expect(screen.queryByRole("link", { name: "Export" })).not.toBeInTheDocument();
+  });
+});
+
+describe("buildAppRouter navGroups", () => {
+  it("passes the app's declared groups through to the shell", async () => {
+    // The pass-through is a hand-written enumeration of option names, and nothing covered it:
+    // `navPlacement`, `contentWidth` and `density` all reach the shell through the same list and
+    // no test asserts any of them arrives. So every other gate on groups can be green while the
+    // one line that carries them to the shell is missing, and every app using the sanctioned
+    // entry point gets nothing. Mutation: delete `navGroups={options.navGroups}` from the
+    // AppShell element, and the labelled list loses its name.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async (input) => {
+        const url = (input as Request).url;
+        if (url.endsWith("/api/v1/auth/login")) {
+          return jsonResponse({ access_token: "t", token_type: "bearer" });
+        }
+        return jsonResponse({
+          id: "1",
+          email: "editor@example.com",
+          role_rank: 20,
+          role_name: "editor",
+        });
+      }),
+    );
+
+    const router = buildAppRouter(
+      [
+        {
+          name: "notes",
+          routes: [{ path: "/notes", view: "NotesList" }],
+          nav: [{ label: "Notes", to: "/notes", group: "work" }],
+        },
+      ],
+      {
+        views: { NotesList: views.NotesList },
+        title: "Terp",
+        navGroups: [{ id: "work", label: "Werkruimte" }],
+        history: createMemoryHistory({ initialEntries: ["/notes"] }),
+      },
+    );
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Notes view" })).toBeInTheDocument(),
+    );
+    // Asserted by accessible NAME, which is the only form that survives both a dropped
+    // attribute and a dangling IDREF — see AppShell.test.tsx for why no lane catches either.
+    expect(screen.getByRole("list", { name: "Werkruimte" })).toBeInTheDocument();
+  });
+
+  it("carries a DECLARED density all the way to the shell root", async () => {
+    // The gap the two comments above name, closed for the key that arrives by a different
+    // route. `density` reaches the shell through the same hand-written enumeration, and now it
+    // can also come from the app's checked-in layout-contract.json — so there are two ways for
+    // it to go missing and this covers the new one end to end: file -> resolver -> AppShell
+    // prop -> rendered attribute.
+    //
+    // Mutations, both red: change `density={layout.density}` back to `options.density` in the
+    // AppShell element (the resolver runs and its answer is thrown away), or drop
+    // `density: options.density` from the resolver call (the option path dies instead).
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async (input) => {
+        const url = (input as Request).url;
+        if (url.endsWith("/api/v1/auth/login")) {
+          return jsonResponse({ access_token: "t", token_type: "bearer" });
+        }
+        return jsonResponse({
+          id: "1",
+          email: "editor@example.com",
+          role_rank: 20,
+          role_name: "editor",
+        });
+      }),
+    );
+
+    const router = buildAppRouter(
+      [{ name: "notes", routes: [{ path: "/notes", view: "NotesList" }] }],
+      {
+        views: { NotesList: views.NotesList },
+        title: "Terp",
+        layout: { shell: { density: "compact" } },
+        history: createMemoryHistory({ initialEntries: ["/notes"] }),
+      },
+    );
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Notes view" })).toBeInTheDocument(),
+    );
+    expect(document.querySelector('[data-terp="appshell"]')).toHaveAttribute(
+      "data-density",
+      "compact",
+    );
+  });
+
+  it("carries DECLARED groups all the way to the rendered navigation", async () => {
+    // The array key end to end: file -> resolver -> AppShell prop -> the list's accessible name.
+    // The sibling test above proves the option path and this proves the file path, because they
+    // are two different lines and either can go missing on its own.
+    //
+    // The empty label is the interesting half. The document spells "render no label at all" as
+    // `""` and NavGroup spells it `null`, so the resolver maps between them — and a resolver
+    // that passed `""` straight through would give the shell a labelled list whose name is the
+    // empty string, which is a list with no accessible name at all and no error anywhere.
+    //
+    // Mutations, both red: `navGroups={options.navGroups}` in the AppShell element, or removing
+    // the `"" -> null` map. NOT the third one this comment used to name — dropping
+    // `navGroups: options.navGroups` from the resolver call — because this test passes no
+    // groups OPTION, so that key is already undefined here and removing it changes nothing
+    // observable. That line is gated in bootstrap.test.tsx, by the conflict it exists to raise.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async (input) => {
+        const url = (input as Request).url;
+        if (url.endsWith("/api/v1/auth/login")) {
+          return jsonResponse({ access_token: "t", token_type: "bearer" });
+        }
+        return jsonResponse({
+          id: "1",
+          email: "editor@example.com",
+          role_rank: 20,
+          role_name: "editor",
+        });
+      }),
+    );
+
+    const router = buildAppRouter(
+      [
+        {
+          name: "notes",
+          routes: [
+            { path: "/notes", view: "NotesList" },
+            { path: "/pinned", view: "NotesList" },
+          ],
+          nav: [
+            { label: "Notes", to: "/notes", group: "work" },
+            { label: "Pinned", to: "/pinned", group: "quiet" },
+          ],
+        },
+      ],
+      {
+        views: { NotesList: views.NotesList },
+        title: "Terp",
+        layout: {
+          shell: {
+            // Declared in the OPPOSITE order to the one they must render in. Written the
+            // obvious way round first, and the ordering assertion below was then vacuous:
+            // with the sort key dropped every group ties at 0 and the stable sort keeps
+            // declaration order, which was already the answer being asserted. Only a
+            // declaration order the sort has to undo can observe the sort.
+            navGroups: [
+              { id: "work", label: "Werkruimte", order: 2 },
+              { id: "quiet", label: "", order: 1 },
+            ],
+          },
+        },
+        history: createMemoryHistory({ initialEntries: ["/notes"] }),
+      },
+    );
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Notes view" })).toBeInTheDocument(),
+    );
+    expect(screen.getByRole("list", { name: "Werkruimte" })).toBeInTheDocument();
+    // Exactly ONE group label element, which is what proves the `"" -> null` map ran. This
+    // assertion was written the wrong way first — comparing the lists' `aria-label` and
+    // `aria-labelledby` ATTRIBUTES against `""` — and the mutation walked straight past it,
+    // because an unmapped `""` does not produce an empty attribute. It produces a label element
+    // containing nothing and an `aria-labelledby` pointing at it, so the list claims a name and
+    // has none: a defect no attribute check and no role-name query can see, since a list with
+    // an empty name and a list with no name are indistinguishable to both. Counting the label
+    // elements is the form that sees it.
+    expect(document.querySelectorAll('[data-terp="appshell-nav-group-label"]')).toHaveLength(1);
+    // And the declared sort key put the unlabelled group first: `order: 1` against `order: 2`,
+    // rather than whichever order they happened to render in. `getAllByRole` is document order.
+    const first = screen.getAllByRole("list")[0]!;
+    expect(first.getAttribute("aria-labelledby")).toBeNull();
+  });
+
+  it("renders a DECLARED mark, and refuses it declared twice", async () => {
+    // End to end for the third key that could only be said in code: file -> resolver -> the
+    // AppShell slot -> an <img> in the rendered header. `alt=""` on purpose — the shell renders
+    // the app's title beside the mark, so a name here announces the app twice.
+    //
+    // Mutations, both red: hand `options.logo` to AppShell instead of the resolved path, or
+    // drop `brand` from the resolver's output.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async (input) => {
+        const url = (input as Request).url;
+        if (url.endsWith("/api/v1/auth/login")) {
+          return jsonResponse({ access_token: "t", token_type: "bearer" });
+        }
+        return jsonResponse({
+          id: "1",
+          email: "editor@example.com",
+          role_rank: 20,
+          role_name: "editor",
+        });
+      }),
+    );
+
+    const router = buildAppRouter(
+      [{ name: "notes", routes: [{ path: "/notes", view: "NotesList" }] }],
+      {
+        views: { NotesList: views.NotesList },
+        title: "Terp",
+        layout: { shell: { brand: { logo: "/logo.png" } } },
+        history: createMemoryHistory({ initialEntries: ["/notes"] }),
+      },
+    );
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Notes view" })).toBeInTheDocument(),
+    );
+    const mark = document.querySelector('[data-terp="appshell-mark"] img');
+    expect(mark).toHaveAttribute("src", "/logo.png");
+    expect(mark).toHaveAttribute("alt", "");
+  });
+
+  it("refuses a mark declared in the file and passed as an option", () => {
+    // Refused in the router rather than the resolver, because a path and a rendered element are
+    // not comparable values — so the message names the slots rather than pretending to compare.
+    expect(() =>
+      buildAppRouter([], {
+        views: {},
+        title: "Terp",
+        layout: { shell: { brand: { logo: "/logo.png", logoDark: "/logo-dark.png" } } },
+        logo: "x",
+        logoDark: "y",
+      }),
+    ).toThrow(
+      /declares shell\.brand\.logo and shell\.brand\.logoDark and the bootstrap options pass logo and logoDark/,
+    );
+    // And only the slot that is actually declared twice.
+    expect(() =>
+      buildAppRouter([], {
+        views: {},
+        title: "Terp",
+        layout: { shell: { brand: { logo: "/logo.png" } } },
+        logoDark: "y",
+      }),
+    ).not.toThrow();
+  });
+
+  it("refuses the app's declaration and its options declaring one fact twice", () => {
+    // Compose time, beside the duplicate-group refusal below and for the same reason: an
+    // authoring error with no legitimate transient form. The message names both sources
+    // because the reader otherwise cannot tell which value they are looking at.
+    expect(() =>
+      buildAppRouter([], {
+        views: {},
+        title: "Terp",
+        layoutContract: "standard",
+        layout: { contract: "standard" },
+      }),
+    ).toThrow(/both declare "contract" \(file: "standard", code: "standard"\)/);
+    expect(() =>
+      buildAppRouter([], {
+        views: {},
+        title: "Terp",
+        layout: { shell: { density: "compakt" as "compact" } },
+      }),
+    ).toThrow(/shell\.density is "compakt"/);
+  });
+
+  it("refuses a duplicate group id when the router is composed", () => {
+    // An authoring error with no legitimate transient form, so it is refused once here rather
+    // than absorbed on every render. Deliberately NOT symmetrical with an item naming an
+    // undeclared group, which is the normal state of an app mid-adoption and falls open.
+    expect(() =>
+      buildAppRouter([], {
+        views: {},
+        title: "Terp",
+        navGroups: [
+          { id: "work", label: "Werkruimte" },
+          { id: "work", label: "Weer werkruimte" },
+        ],
+      }),
+    ).toThrow(/duplicate id\(s\): work/);
+  });
+
+  it("does not refuse an item naming a group nobody declared", () => {
+    // The counterpart to the row above, and the reason the throw is narrow: a module ships on
+    // its own schedule, so an undeclared id is ordinary rather than wrong. The link must still
+    // be reachable. Mutation: widen the composition check to unreferenced/undeclared ids and
+    // this throws.
+    expect(() =>
+      buildAppRouter(
+        [
+          {
+            name: "notes",
+            routes: [{ path: "/notes", view: "NotesList" }],
+            nav: [{ label: "Notes", to: "/notes", group: "not-declared-yet" }],
+          },
+        ],
+        { views: { NotesList: views.NotesList }, title: "Terp", navGroups: [] },
+      ),
+    ).not.toThrow();
+  });
+});