@terpjs/react-core 0.9.0 → 0.10.0

package/src/nav.test.ts

@@ -1,21 +1,251 @@
 import { describe, expect, it } from "vitest";
 import type { ModuleManifest } from "@terpjs/contract";
 
-import { visibleNav } from "./nav";
+import { groupNav, isDeclarationVisible, visibleNav } from "./nav";
+import type { NavVisibilityContext } from "./nav";
 
 const manifests: ModuleManifest[] = [
   { name: "notes", routes: [], nav: [{ label: "Notes", to: "/notes" }] },
   { name: "admin", routes: [], nav: [{ label: "Users", to: "/users", role: "admin" }] },
+  {
+    name: "billing",
+    routes: [],
+    nav: [{ label: "Export", to: "/export", permission: "billing.export" }],
+  },
+  {
+    name: "audit",
+    // Both gates on one item, which is the case the AND exists for.
+    routes: [],
+    nav: [{ label: "Audit", to: "/audit", role: "admin", permission: "audit.read" }],
+  },
   { name: "noNav", routes: [] },
 ];
 
+/** A context that says yes to everything, so each test can deny exactly one thing. */
+function allowAll(overrides: Partial<NavVisibilityContext> = {}): NavVisibilityContext {
+  return {
+    canSeeRole: () => true,
+    permissions: ["billing.export", "audit.read"],
+    ...overrides,
+  };
+}
+
 describe("visibleNav", () => {
   it("flattens nav across manifests when everything is visible", () => {
-    expect(visibleNav(manifests, () => true).map((i) => i.to)).toEqual(["/notes", "/users"]);
+    expect(visibleNav(manifests, allowAll()).map((i) => i.to)).toEqual([
+      "/notes",
+      "/users",
+      "/export",
+      "/audit",
+    ]);
   });
 
   it("filters items by their required role", () => {
-    const onlyPublic = visibleNav(manifests, (role) => role === undefined);
-    expect(onlyPublic.map((i) => i.to)).toEqual(["/notes"]);
+    const onlyPublic = visibleNav(manifests, allowAll({ canSeeRole: (role) => role === undefined }));
+    // /export declares no role, so the role gate lets it through; /audit declares both.
+    expect(onlyPublic.map((i) => i.to)).toEqual(["/notes", "/export"]);
+  });
+
+  it("filters items by their required permission", () => {
+    const noGrants = visibleNav(manifests, allowAll({ permissions: [] }));
+    expect(noGrants.map((i) => i.to)).toEqual(["/notes", "/users"]);
+  });
+});
+
+describe("isDeclarationVisible", () => {
+  it("requires BOTH gates when an item declares both", () => {
+    // The composition, stated as a truth table. Either alone is not enough, which is what the
+    // server does: a Policy carrying a Permission enforces the permission's role floor AND the
+    // grant. A client checking one would disagree with the endpoint in one direction or another.
+    const both = { role: "admin", permission: "audit.read" };
+    expect(isDeclarationVisible(both, allowAll())).toBe(true);
+    expect(isDeclarationVisible(both, allowAll({ canSeeRole: () => false }))).toBe(false);
+    expect(isDeclarationVisible(both, allowAll({ permissions: [] }))).toBe(false);
+    expect(
+      isDeclarationVisible(both, { canSeeRole: () => false, permissions: [] }),
+    ).toBe(false);
+  });
+
+  it("is unchanged for a declaration that names neither gate", () => {
+    // The additivity claim. Nothing an existing manifest declares moves, because a missing
+    // permission short-circuits to true and `role` keeps its exact meaning.
+    expect(isDeclarationVisible({}, allowAll({ permissions: [] }))).toBe(true);
+    expect(isDeclarationVisible({}, allowAll({ canSeeRole: () => false }))).toBe(false);
+  });
+
+  it("fails closed on a permission nobody granted", () => {
+    // Three ways in, one outcome. A misspelled name is indistinguishable from an ungranted one,
+    // and that is correct: both mean "the server would refuse this".
+    expect(isDeclarationVisible({ permission: "billing.exprot" }, allowAll())).toBe(false);
+    // An app that mounts no grant capability has an empty list — which must hide the item, not
+    // wave it through. This is the branch a "treat empty as unrestricted" shortcut would break.
+    expect(isDeclarationVisible({ permission: "billing.export" }, allowAll({ permissions: [] }))).toBe(
+      false,
+    );
+    // Signed out: `canSeeRole` already answers false for a null rank, before permissions matter.
+    expect(
+      isDeclarationVisible({ permission: "billing.export" }, {
+        canSeeRole: () => false,
+        permissions: ["billing.export"],
+      }),
+    ).toBe(false);
+  });
+});
+
+// `groupNav` — the app's declared groups meeting the modules' declared items.
+//
+// Every row below names the mutation that turns it red, because two of this phase's earlier
+// gates could not fail and were only found by trying. Two are worth reading before adding a row
+// here. "Sorts stably" cannot be falsified by DELETING the sort: `Array.prototype.sort` is stable
+// by specification, so a tied array comes out in declaration order whether or not it was sorted,
+// and the assertion passes over the mutant. The comparator that does reorder ties is
+// `(a, b) => ((a.order ?? 0) - (b.order ?? 0)) || -1`, which was measured in this repo's node to
+// fully reverse a tied array at every length from 2 upward. And "sorts" is only falsifiable
+// against `?? Infinity` if the fixture carries a POSITIVE order beside an absent one — with only
+// negatives and absents the two rules agree.
+describe("groupNav", () => {
+  const items = (...tos: string[]) => tos.map((to) => ({ label: to, to }));
+  const tos = (sections: ReturnType<typeof groupNav>) =>
+    sections.map((section) => section.items.map((item) => item.to));
+  /** Section identity and heading, without the items — asserted separately via `tos`. */
+  const shape = (sections: ReturnType<typeof groupNav>) =>
+    sections.map((section) => ({ id: section.id, label: section.label }));
+
+  it("renders one unlabelled section when the app declares no groups", () => {
+    // The additivity claim, as a test rather than an argument: same items, same order, one
+    // section that renders no heading. Mutation: `return [{ id: "default", label: "", items }]`,
+    // which falsifies the null id and the null label together.
+    expect(groupNav(items("/a", "/b", "/c"))).toEqual([
+      { id: null, label: null, items: items("/a", "/b", "/c") },
+    ]);
+  });
+
+  it("emits the ungrouped bucket last, after every declared group", () => {
+    // The rule that changed under review. The packaged admin entry carries no `group` and no app
+    // can give it one, so a first-emitted default bucket would hoist it to the top of the sidebar
+    // the moment an app declared its first group. Mutation: emit the ungrouped section first.
+    const sections = groupNav(
+      [
+        { label: "Loose", to: "/loose" },
+        { label: "Sales", to: "/sales", group: "work" },
+      ],
+      [{ id: "work", label: "Werkruimte" }],
+    );
+    expect(sections.map((section) => section.id)).toEqual(["work", null]);
+    expect(tos(sections)).toEqual([["/sales"], ["/loose"]]);
+  });
+
+  it("drops a group left empty rather than rendering a label over nothing", () => {
+    // Reachable on a first render: a group holding only the role-gated `/admin` entry is empty
+    // for everyone who is not an admin, because `visibleNav` has already removed it.
+    // Mutation: push the section regardless of `bucket.length`.
+    const sections = groupNav(items("/a"), [
+      { id: "empty", label: "Beheer" },
+      { id: "used", label: "Werk" },
+    ]);
+    expect(sections.map((section) => section.id)).toEqual([null]);
+    expect(sections.some((section) => section.label === "Beheer")).toBe(false);
+  });
+
+  it("falls an item naming an undeclared group open into the ungrouped bucket", () => {
+    // A module ships before the app declares its group; the link must still be reachable.
+    // Mutation: drop the `declared.has(item.group)` half of the key expression, and the item
+    // lands in a bucket nothing reads — it vanishes from the sidebar with nothing reporting it.
+    const sections = groupNav(
+      [{ label: "Orphan", to: "/orphan", group: "not-declared" }],
+      [{ id: "work", label: "Werkruimte" }],
+    );
+    expect(tos(sections)).toEqual([["/orphan"]]);
+    expect(sections[0]!.id).toBeNull();
+  });
+
+  it("sorts items on order, treating absent as 0", () => {
+    // Mutation: `order ?? Infinity`, which sends both unordered items to the end and yields
+    // /up, /down, /a, /b. The POSITIVE order is what makes the two rules disagree.
+    const sections = groupNav([
+      { label: "down", to: "/down", order: 1 },
+      { label: "a", to: "/a" },
+      { label: "up", to: "/up", order: -1 },
+      { label: "b", to: "/b" },
+    ]);
+    expect(tos(sections)).toEqual([["/up", "/a", "/b", "/down"]]);
+  });
+
+  it("keeps tied items in declaration order", () => {
+    // Mutation: `((a.order ?? 0) - (b.order ?? 0)) || -1` — measured to reverse a tied array at
+    // every length from 2 up. Deleting the sort does NOT falsify this, which is the point.
+    expect(tos(groupNav(items("/first", "/second", "/third")))).toEqual([
+      ["/first", "/second", "/third"],
+    ]);
+  });
+
+  it("sorts groups on order, treating absent as 0", () => {
+    // Same shape one level up, and the same `?? Infinity` mutation.
+    const sections = groupNav(
+      [
+        { label: "d", to: "/d", group: "down" },
+        { label: "p", to: "/p", group: "plain" },
+        { label: "u", to: "/u", group: "up" },
+      ],
+      [
+        { id: "down", label: "Down", order: 1 },
+        { id: "plain", label: "Plain" },
+        { id: "up", label: "Up", order: -1 },
+      ],
+    );
+    expect(sections.map((section) => section.id)).toEqual(["up", "plain", "down"]);
+  });
+
+  it("keeps tied groups in declaration order", () => {
+    const sections = groupNav(
+      [
+        { label: "a", to: "/a", group: "one" },
+        { label: "b", to: "/b", group: "two" },
+        { label: "c", to: "/c", group: "three" },
+      ],
+      [
+        { id: "one", label: "One" },
+        { id: "two", label: "Two" },
+        { id: "three", label: "Three" },
+      ],
+    );
+    expect(sections.map((section) => section.id)).toEqual(["one", "two", "three"]);
+  });
+
+  it("lets the first declaration of a duplicated id win, without duplicating its items", () => {
+    // `groupNav` stays total so a render can never throw; `buildAppRouter` refuses the duplicate
+    // at composition time instead. Mutation: drop the `declared.has` guard on insertion, and the
+    // second declaration overwrites the first, so the label becomes "Second".
+    const sections = groupNav([{ label: "a", to: "/a", group: "dup" }], [
+      { id: "dup", label: "First" },
+      { id: "dup", label: "Second" },
+    ]);
+    expect(shape(sections)).toEqual([{ id: "dup", label: "First" }]);
+    expect(tos(sections)).toEqual([["/a"]]);
+  });
+
+  it("treats the empty string as a real group id, not as the ungrouped bucket", () => {
+    // The default bucket is keyed on `null` rather than on a falsy sentinel precisely so that
+    // `id: ""` — a legal string — stays a group of its own. Mutation: key the bucket on `""`,
+    // and this item's group merges into the ungrouped section and loses its label.
+    const sections = groupNav([{ label: "a", to: "/a", group: "" }], [{ id: "", label: "Blank" }]);
+    expect(shape(sections)).toEqual([{ id: "", label: "Blank" }]);
+    expect(tos(sections)).toEqual([["/a"]]);
+  });
+
+  it("renders a null-labelled group as pure positioning", () => {
+    // The escape an app uses to place its otherwise-ungrouped items somewhere other than last.
+    const sections = groupNav(
+      [
+        { label: "main", to: "/main", group: "main" },
+        { label: "loose", to: "/loose" },
+      ],
+      [{ id: "main", label: null }],
+    );
+    expect(shape(sections)).toEqual([
+      { id: "main", label: null },
+      { id: null, label: null },
+    ]);
+    expect(tos(sections)).toEqual([["/main"], ["/loose"]]);
   });
 });

package/src/nav.ts

@@ -1,13 +1,187 @@
-import type { ModuleManifest, NavItem } from "@terpjs/contract";
+import type { ModuleManifest, NavGroup, NavItem } from "@terpjs/contract";
 
 /**
- * Flatten the nav of every module manifest into one ordered sidebar list, keeping only
- * the items the current user may see. `canSeeRole(role)` decides visibility for an item's
- * required role (an item with no `role` is visible to any authenticated user).
+ * What a manifest's declared visibility is resolved against.
+ *
+ * Built from what `/me` actually returns, which is the whole reason this type is two fields and
+ * not four. ADR 0097 §5 specified a context of module grants, per-module role ranks, superuser
+ * and internal-versus-external; `CurrentUser` carries none of them. It carries `role_rank`,
+ * `role_name` and `permissions`, and the last of those is the general mechanism the decision
+ * never named. A context built from what is real is honest; one built from that list would be
+ * vocabulary with no source behind it.
+ */
+export interface NavVisibilityContext {
+  /** Whether the caller clears a named role's floor — the existing `role` gate, unchanged. */
+  canSeeRole: (role: string | undefined) => boolean;
+  /**
+   * The caller's named grants, from `CurrentUser.permissions`.
+   *
+   * Empty when signed out and empty for an app that mounts no grant capability, which is what
+   * makes the gate fail closed in both cases rather than failing open in the second.
+   */
+  permissions: readonly string[];
+}
+
+/**
+ * Whether one declared item is visible to the caller.
+ *
+ * `role` and `permission` are **ANDed**, which is deliberately what the server does: a `Policy`
+ * carrying a `Permission` enforces the permission's role floor *and* the grant, so a client that
+ * checked either alone would disagree with the endpoint in one direction or the other. It is the
+ * same composition `Authorized` already ships, and reusing it means the navigation gains the gate
+ * the buttons already have rather than a second vocabulary for the same idea.
+ *
+ * Exported because routes need it too. A nav-only gate would hide the link and leave the route
+ * reachable by URL — `role` has never had that asymmetry, since it is declared on both
+ * `NavItem` and `ModuleRoute`, and `permission` must not introduce one.
+ */
+export function isDeclarationVisible(
+  declaration: { role?: string; permission?: string },
+  context: NavVisibilityContext,
+): boolean {
+  if (!context.canSeeRole(declaration.role)) {
+    return false;
+  }
+  return (
+    declaration.permission === undefined ||
+    context.permissions.includes(declaration.permission)
+  );
+}
+
+/**
+ * Flatten the nav of every module manifest into one ordered sidebar list, keeping only the items
+ * the current user may see.
+ *
+ * The context is a **required** argument, and that is a breaking change taken on purpose. Making
+ * it optional would have been source-compatible and silently wrong: an existing two-argument
+ * caller would fail closed on every item that gained a `permission`, removing links from a
+ * sidebar with no error anywhere. A required parameter turns that into a typecheck error at the
+ * one call site each app has.
  */
 export function visibleNav(
   manifests: readonly ModuleManifest[],
-  canSeeRole: (role: string | undefined) => boolean,
+  context: NavVisibilityContext,
 ): NavItem[] {
-  return manifests.flatMap((manifest) => manifest.nav ?? []).filter((item) => canSeeRole(item.role));
+  return manifests
+    .flatMap((manifest) => manifest.nav ?? [])
+    .filter((item) => isDeclarationVisible(item, context));
+}
+
+/**
+ * One rendered section of the primary navigation: a declared {@link NavGroup} with the items that
+ * named it, or the default headerless group with everything that named nothing.
+ *
+ * The group is flattened into `id` and `label` rather than carried whole, and that is what lets
+ * one shape describe both cases. The default group has no declaration to carry — it is not a
+ * `NavGroup` an app wrote, it is the absence of one — so a section holding an optional `NavGroup`
+ * would force every reader through `section.group?.label` to ask a question that has the same
+ * answer either way: what, if anything, do I render above this list.
+ */
+export interface NavSection {
+  /** The declared group's id, or `null` for the default headerless group. */
+  id: string | null;
+  /** The label to render above the list, or `null` when the section renders none. */
+  label: string | null;
+  items: NavItem[];
+}
+
+/** Stable ascending sort on `order ?? 0` — see {@link groupNav} for why absent is 0. */
+function byOrder<T extends { order?: number }>(values: T[]): T[] {
+  return values.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+}
+
+/**
+ * Arrange visible nav items into the app's declared groups.
+ *
+ * Groups fix the defect ADR 0097 names in its own Context: sidebar order is "an accident of
+ * `import.meta.glob` key order", because the sidebar is one flat list flattened out of whatever
+ * sequence the module manifests happened to arrive in. A group spans modules, so no module can
+ * own one — the app declares them, modules reference them by id, and this function is where the
+ * two halves meet.
+ *
+ * **Additive by construction.** An app that declares no groups gets exactly one section holding
+ * exactly the items it passed in, in the order it passed them: `groups` defaults to empty, every
+ * item falls into the default bucket, and a stable sort over keys that are all 0 is the identity.
+ * That is not an argument that it *should* be additive — it is the code path, and the shell
+ * renders the same list it renders today.
+ *
+ * Four rules, and each one is a decision:
+ *
+ * **An unknown group id falls into the default bucket rather than dropping the item.** A group is
+ * declared by the app; the item is declared by a module that ships on its own schedule. An id
+ * with no declaration yet is therefore the ordinary state of a module the app has not finished
+ * adopting, not a corruption — and the two ways to be wrong are not symmetric. An ungrouped link
+ * is in the wrong place and works; a dropped link is a screen the user cannot reach, with nothing
+ * anywhere saying why. Nothing warns about it either: this is a state the design calls normal,
+ * and a diagnostic for a normal state is noise that teaches people to ignore diagnostics.
+ *
+ * **A section with no items is not emitted.** Reachable on the first render of any app that
+ * groups the packaged admin entry's neighbours: `/admin` declares `role: "admin"`, so
+ * {@link visibleNav} removes it for everyone else and a group holding only it is left empty. A
+ * label over a void is worse than no label, because it names a place the user is being refused
+ * and cannot see.
+ *
+ * **The default bucket is emitted LAST, and it is not part of the group sort.** This is the rule
+ * that changed under review, and the case that decided it is the one case every app has. The
+ * packaged admin area is appended after the app's own manifests, so its nav entry renders last
+ * today. Emit the default bucket first and that entry — which no app authors and therefore no app
+ * can annotate with a `group` — jumps to the top of the sidebar the moment the app declares its
+ * first group. Emitting last leaves it exactly where it already is. It also puts an item naming
+ * an undeclared group at the bottom rather than above the app's own structure, which is the
+ * better place for a fail-open result to surface.
+ *
+ * The trade is real and is worth stating: an app that groups a *minority* of its items sees the
+ * ungrouped majority sink below them. That is app-authored, visible on the first render, and
+ * fixed in one line by declaring `{ id: "main", label: null, order: -1 }` and pointing those
+ * items at it — a group with a `null` label renders no heading, so it is pure positioning. The
+ * admin case has no such fix, which is what makes it decisive rather than merely also true.
+ *
+ * **Absent `order` is 0, everywhere, and the sort is stable.** Not `Infinity`: a single numbered
+ * item would then leap above an entire unnumbered list, which breaks the additivity the rest of
+ * this function is built on. Absent-is-0 is CSS `order` semantics exactly — positive sorts below
+ * its unordered siblings, negative above — which is the vocabulary a framework styled in tokens
+ * already speaks, and it means a manifest that numbers nothing is untouched.
+ *
+ * A duplicate group id is not an error here: the first declaration wins and the second is
+ * inert, so this function stays total and a render can never throw. `buildAppRouter` refuses the
+ * duplicate at composition time instead, where an authoring error belongs and where it can be
+ * reported once rather than on every frame.
+ */
+export function groupNav(
+  items: readonly NavItem[],
+  groups: readonly NavGroup[] = [],
+): NavSection[] {
+  // First declaration wins. A Map also gives the declared ids an O(1) membership test, which is
+  // what separates "this item names a real group" from "this item falls open".
+  const declared = new Map<string, NavGroup>();
+  for (const group of groups) {
+    if (!declared.has(group.id)) {
+      declared.set(group.id, group);
+    }
+  }
+
+  // `null` keys the default bucket. It cannot collide with a declared id: an id is a string, and
+  // the empty string — which is a legal id and would collide with any falsy sentinel — is a
+  // distinct Map key from null.
+  const buckets = new Map<string | null, NavItem[]>([[null, []]]);
+  for (const id of declared.keys()) {
+    buckets.set(id, []);
+  }
+  for (const item of items) {
+    const key = item.group !== undefined && declared.has(item.group) ? item.group : null;
+    buckets.get(key)!.push(item);
+  }
+
+  const sections: NavSection[] = [];
+  for (const group of byOrder([...declared.values()])) {
+    const bucket = buckets.get(group.id)!;
+    if (bucket.length > 0) {
+      sections.push({ id: group.id, label: group.label, items: byOrder(bucket) });
+    }
+  }
+  const ungrouped = buckets.get(null)!;
+  if (ungrouped.length > 0) {
+    sections.push({ id: null, label: null, items: byOrder(ungrouped) });
+  }
+  return sections;
 }

package/src/navActive.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import { activeNavPath, isNavItemActive } from "./navActive";
+
+// The predicate the sidebar and ModuleNav share (ADR 0097 §6, amended in 4e).
+//
+// Every case here is a URL shape where something in the framework got it wrong, or would have.
+// The set-level ones are the point of the file: `activeNavPath` exists because "at most one item
+// is current" cannot be decided one link at a time, and three of the four cases below are
+// invisible to a per-item test.
+
+describe("isNavItemActive", () => {
+  it("matches a segment-aligned prefix, not a string prefix", () => {
+    expect(isNavItemActive("/settings/users", "/settings")).toBe(true);
+    // The guard that matters: /settings-users starts with /settings as a STRING.
+    expect(isNavItemActive("/settings-users", "/settings")).toBe(false);
+  });
+
+  it("normalises a trailing slash on both operands, in both branches", () => {
+    // The exact branch had this from the start; the prefix branch did not, and an earlier draft
+    // of the rule attached the normalisation to `exact` alone.
+    expect(isNavItemActive("/settings/", "/settings")).toBe(true);
+    expect(isNavItemActive("/settings", "/settings/")).toBe(true);
+    expect(isNavItemActive("/settings/", "/settings", true)).toBe(true);
+    expect(isNavItemActive("/settings", "/settings/", true)).toBe(true);
+    // ...and the root is not normalised away to the empty string.
+    expect(isNavItemActive("/", "/")).toBe(true);
+  });
+
+  it("ignores the query string and the hash", () => {
+    // A nav tab's identity is its path. Filtering a list must not unhighlight the tab the user
+    // is standing on, which is what the router does on an exact link with includeSearch left at
+    // its default.
+    expect(isNavItemActive("/records", "/records")).toBe(true);
+    expect(isNavItemActive("/records", "/records", true)).toBe(true);
+  });
+
+  it("treats a `to` that is not an absolute path as inactive", () => {
+    // Not tidiness. The router resolves a relative or empty `to` against the CURRENT location,
+    // so `to: ""` is a link to wherever you already are — and a raw prefix test would light
+    // every item at once, because every path starts with the empty string.
+    expect(isNavItemActive("/records", "")).toBe(false);
+    expect(isNavItemActive("/records", "records")).toBe(false);
+    expect(isNavItemActive("/records", "./records")).toBe(false);
+  });
+
+  it("exact refuses the children a prefix would take", () => {
+    expect(isNavItemActive("/settings/users", "/settings", true)).toBe(false);
+    expect(isNavItemActive("/settings", "/settings", true)).toBe(true);
+  });
+
+  it("lets the root claim nothing but itself, with no rule of its own", () => {
+    // `/` prefixes every path as a STRING, which is why the router adapter carried a
+    // hand-written `exact: item.to === "/"`. Matching on SEGMENTS makes that unnecessary:
+    // `/profile`'s second character is not a slash.
+    expect(isNavItemActive("/profile", "/")).toBe(false);
+    expect(isNavItemActive("/", "/")).toBe(true);
+  });
+
+  it("collapses repeated slashes, which is the one shape the segment test would let through", () => {
+    // The gate for the normalisation, and it is the only input that distinguishes it: `/` has
+    // length 1, so the boundary test asks whether current[1] is a slash — true for exactly
+    // `//foo`. The router never emits that (it collapses on the way in), but `activePath` is a
+    // plain string and window.location.pathname is not normalised by anyone.
+    expect(isNavItemActive("//foo", "/")).toBe(false);
+    expect(activeNavPath("//foo", [{ to: "/" }])).toBeUndefined();
+    // ...and a doubled slash deeper in the path resolves to the same item either way.
+    expect(isNavItemActive("/settings//users", "/settings")).toBe(true);
+  });
+});
+
+describe("activeNavPath", () => {
+  const NAV = [{ to: "/" }, { to: "/settings" }, { to: "/settings/users" }];
+
+  it("returns exactly one item where a per-link predicate returns two", () => {
+    // The defect this whole file exists for. Both /settings and /settings/users match
+    // /settings/users on their own, so a router — which decides per link — marks both current,
+    // paints both, and announces "current page" twice.
+    expect(NAV.filter((item) => isNavItemActive("/settings/users", item.to))).toHaveLength(2);
+    expect(activeNavPath("/settings/users", NAV)).toBe("/settings/users");
+  });
+
+  it("keeps the parent lit on a URL that is not itself a nav item", () => {
+    // The other half, and the reason per-item `exact` is not the fix: turn exact on to stop the
+    // case above and this one goes dark, leaving a page with nothing current at all.
+    expect(activeNavPath("/settings/appearance", NAV)).toBe("/settings");
+  });
+
+  it("does not let the root item claim an unrelated page", () => {
+    // The example app ships `{ label: "Notes", to: "/" }`, and PROFILE_PATH is mounted by
+    // buildAppRouter and is in no manifest's nav. A STRING-prefix longest-match would light
+    // "Notes" while the user is on their profile; a segment-aligned one does not.
+    expect(activeNavPath("/profile", NAV)).toBeUndefined();
+    expect(activeNavPath("/", NAV)).toBe("/");
+  });
+
+  it("returns undefined when nothing matches", () => {
+    expect(activeNavPath("/explorer", [{ to: "/settings" }])).toBeUndefined();
+  });
+
+  it("honours an item's own exact flag", () => {
+    const nav = [{ to: "/settings", exact: true }, { to: "/records" }];
+    expect(activeNavPath("/settings/users", nav)).toBeUndefined();
+    expect(activeNavPath("/settings", nav)).toBe("/settings");
+  });
+
+  it("is not fooled by declaration order", () => {
+    // Longest wins, not first — otherwise the answer depends on `import.meta.glob` key order,
+    // which is the same accident 0097 names as the reason nav needs explicit ordering at all.
+    const shallowFirst = [{ to: "/settings" }, { to: "/settings/users" }];
+    const deepFirst = [{ to: "/settings/users" }, { to: "/settings" }];
+    expect(activeNavPath("/settings/users", shallowFirst)).toBe("/settings/users");
+    expect(activeNavPath("/settings/users", deepFirst)).toBe("/settings/users");
+  });
+});