@terpjs/react-core 0.8.0 → 0.9.0

package/src/markers.test.ts

@@ -39,6 +39,9 @@ const STYLESHEET = "./styles.ts";
  * stylesheet and the layout contract, so it belongs in a release note.
  */
 const MARKERS = [
+  "admin-form",
+  "admin-payload",
+  "admin-section-title",
   "alert",
   "alert-body",
   "alert-icon",
@@ -159,6 +162,15 @@ const MARKERS = [
   "language-switcher-label",
   "loading-state",
   "loading-state-spinner",
+  "login-brand",
+  "login-card",
+  "login-error",
+  "login-form",
+  "login-separator",
+  "login-separator-rule",
+  "login-sso",
+  "login-title",
+  "login-view",
   "markdown",
   "menu",
   "menu-item",
@@ -166,16 +178,32 @@ const MARKERS = [
   "menu-item-icon",
   "menu-trigger",
   "module-nav",
+  "module-nav-link",
+  "module-nav-list",
   "nav-icon",
   "nav-icon-fallback",
+  "page",
   "page-actions",
+  "page-breadcrumbs",
+  "page-header",
+  "page-heading",
+  "page-title",
   "popover",
   "popover-panel",
+  "profile-avatar",
+  "profile-card",
+  "profile-email",
+  "profile-role",
   "radio",
   "radio-group",
   "radio-group-legend",
   "radio-group-options",
   "resource-list",
+  "resource-list-create",
+  "resource-list-empty",
+  "resource-list-error",
+  "resource-list-items",
+  "resource-list-row",
   "spinner-ring",
   "stack",
   "switch",
@@ -254,6 +282,17 @@ const MARKERS = [
  * exactly this. A marker plus a `display: none` rule would have put a component with no visual
  * design into the sheet and offered an app the chance to un-hide it.
  *
+ * `DetailPage` and `OverviewPage` have left the same way, and they were on this list by
+ * mistake rather than by migration: each is a `LayoutSlotContext.Provider` wrapped around
+ * `Page` and renders no element of its own at all, so they are view compositions — which the
+ * paragraph above already excludes. There is nothing to mark without inventing a box, and the
+ * box is the one thing that must not exist here: `Page`'s slot check reads `article.children`,
+ * so a wrapper around the body — `display: contents` included, since that check is a DOM
+ * traversal and the node is still in the collection — becomes the sole body-slot child, is in
+ * no allow table, and fails every governed page closed. Their archetype identity is a context
+ * value, which is the right place for it: `Page` renders the only box either of them has, and
+ * it is marked.
+ *
  * Worth knowing about the shape of this list, because it flatters two files: it names files
  * with NO marker at all, so one marker on one element exempts the rest of the file. `toast.tsx`
  * and `ConfirmDialog.tsx` were never on it despite styling five and four unreachable elements
@@ -262,13 +301,14 @@ const MARKERS = [
  *
  * `Field` has graduated: it renders a root plus label, label text, hint and error markers,
  * so each part of a form field is addressable from the sheet.
+ *
+ * THE LIST IS EMPTY. `LoginView` was the last entry, and it is kept rather than deleted for
+ * the same reason as the ledger below: this is where a new unmarked styled surface has to
+ * argue for itself. Note what an empty list does NOT say, because the shape above already
+ * flatters two files — it names modules with NO marker at all, so one marker anywhere in a
+ * file exempts the rest of it.
  */
-const UNMARKED_STYLED_SURFACES = [
-  "./DetailPage.tsx",
-  "./LoginView.tsx",
-  "./OverviewPage.tsx",
-  "./ProfileView.tsx",
-];
+const UNMARKED_STYLED_SURFACES: string[] = [];
 
 /**
  * How many module-scope base style objects each file still declares — the migration's own
@@ -291,13 +331,64 @@ const UNMARKED_STYLED_SURFACES = [
  * `Popover` positions its panel from a rect it measured — ADR 0094 §3 puts all three on the
  * inline side of the line permanently, so counting them would make this list unable to reach
  * zero and therefore unable to mean anything.
+ *
+ * IT HAS REACHED ZERO, and the honest reading of that is narrow. The detector matches a
+ * module-scope declaration annotated `CSSProperties`, which means a call-site literal and an
+ * unannotated module-scope object are both invisible to it. Four of the built-in admin views
+ * carried five base styles through this entire migration for exactly that reason — four as
+ * call-site object literals (two of them the same `<h2>` declaration, two the same form
+ * measure) and one as an unannotated `payloadStyle` — while both ratchets read clean.
+ * The next commit widens the detector and migrates them, so that zero means what it looks
+ * like it means.
  */
-const INLINE_BASE_STYLES: Record<string, number> = {
-  "./LoginView.tsx": 9,
-  "./ModuleNav.tsx": 4,
-  "./Page.tsx": 5,
-  "./ProfileView.tsx": 3,
-  "./ResourceList.tsx": 2,
+const INLINE_BASE_STYLES: Record<string, number> = {};
+
+/**
+ * Every module that renders an inline `style={}` at all, and how many times.
+ *
+ * This closes the gap the ledger above leaves, and the gap was not theoretical. That one
+ * matches a module-scope declaration annotated `CSSProperties`, so a call-site literal and
+ * an unannotated module-scope object are both invisible to it — and four of the built-in
+ * admin views carried five base styles through the entire styling migration for exactly
+ * that reason, with both ratchets reading clean the whole time. Widening the annotation
+ * pattern would not have found them either. What finds them is counting the SITES.
+ *
+ * So this list is the complete one, and every entry has to be a value ADR 0094 §3 puts on
+ * the inline side permanently. There are only two such kinds, and a new entry is a claim
+ * that there is a third:
+ *
+ *   - A measured value the sheet has no business owning. `icons.tsx` and `LoadingState.tsx`
+ *     size a box from a prop taking any CSS length; `layout.tsx` passes Stack's `align` /
+ *     `justify`, an open vocabulary CSS already has; `ui/Popover.tsx` positions its panel
+ *     from a rect measured at runtime; `dataview/DataViewTable.tsx` carries a column's width
+ *     while it is being dragged.
+ *   - The caller's own `style` prop, forwarded to a root. `ui/Checkbox.tsx`, `ui/Radio.tsx`,
+ *     `ui/Switch.tsx` and `ui/Combobox.tsx` do this and nothing else — it is not the
+ *     component styling itself, it is the escape a framework component owes its caller, and
+ *     `ui/Button.test.tsx` asserts it keeps working.
+ *
+ * Exact equality in both directions, like the ledger above: a new site fails, and a removed
+ * one fails until this record is corrected. Comments are stripped first, because this file's
+ * own prose says `style={}` repeatedly and the measure is otherwise a grep of its own
+ * documentation.
+ *
+ * Counted with a regex rather than by splitting on the literal `style={`, and that is not
+ * tidying. JSX permits whitespace around the `=`, so `style = {{ … }}` and a value on the
+ * next line are both valid and both invisible to a literal split — either would have let a
+ * base style back in past a green gate, which is the exact failure this list exists to
+ * prevent. Verified: the two forms count 0 under the split and 1 under the regex, while
+ * every file above counts identically either way.
+ */
+const INLINE_STYLE_SITES: Record<string, number> = {
+  "./LoadingState.tsx": 1,
+  "./dataview/DataViewTable.tsx": 1,
+  "./icons.tsx": 1,
+  "./layout.tsx": 1,
+  "./ui/Checkbox.tsx": 1,
+  "./ui/Combobox.tsx": 1,
+  "./ui/Popover.tsx": 1,
+  "./ui/Radio.tsx": 1,
+  "./ui/Switch.tsx": 1,
 };
 
 /**
@@ -436,6 +527,21 @@ describe("data-terp markers", () => {
     expect(declared).toEqual(INLINE_BASE_STYLES);
   });
 
+  it("accounts for every inline style site, not only the annotated ones", () => {
+    // The measure the admin views escaped. A base style declared as a call-site literal, or
+    // as a module-scope object nobody annotated, is a base style either way — and the ledger
+    // above cannot see either. This one counts sites, so the only way to stay out of it is to
+    // render no inline style at all.
+    const sites: Record<string, number> = {};
+    for (const [file, text] of production) {
+      const count = stripComments(text).match(/style\s*=\s*\{/g)?.length ?? 0;
+      if (count > 0) {
+        sites[file] = count;
+      }
+    }
+    expect(sites).toEqual(INLINE_STYLE_SITES);
+  });
+
   it("injects the sheet from every module that owns a rule, or is reachable from one that does", () => {
     // Twelve marker-rendering modules never call injectTerpStyles and do not need to: the
     // package publishes ONE entry point and declares no `sideEffects`, so importing anything

package/src/routeSearch.ts

@@ -0,0 +1,73 @@
+import { createContext, useContext } from "react";
+
+import type { ModuleManifest } from "@terpjs/contract";
+
+/**
+ * The runtime half of a route's declared query-string keys (ADR 0096).
+ *
+ * The generated `routes.gen.d.ts` is types only — it vanishes at runtime — so
+ * `useRouteSearch` needs the same declarations as data. They come from the manifests the
+ * router was built from, published through a context rather than a module-level table:
+ * a table would be shared by every router composed in one process, so an app embedding
+ * another (or a test file composing two) would read declarations it never mounted.
+ */
+export const RouteSearchContext = createContext<ReadonlyMap<string, readonly string[]> | null>(
+  null,
+);
+
+/** The manifest spelling (`:id`), so a `$id` manifest and a `:id` read agree on one key. */
+export function canonicalRoutePath(path: string): string {
+  return path.replace(/(^|\/)\$([A-Za-z_][A-Za-z0-9_]*)/g, "$1:$2");
+}
+
+/**
+ * Index every manifest route's declared search keys by its canonical path.
+ *
+ * Two manifests mounting one path union their keys, matching what the generator emits into
+ * the type table — so the runtime read and the compile-time check agree.
+ */
+export function indexSearchKeys(
+  manifests: readonly ModuleManifest[],
+): ReadonlyMap<string, readonly string[]> {
+  const index = new Map<string, readonly string[]>();
+  for (const manifest of manifests) {
+    for (const route of manifest.routes) {
+      const key = canonicalRoutePath(route.path);
+      index.set(key, [...new Set([...(index.get(key) ?? []), ...(route.search ?? [])])]);
+    }
+  }
+  return index;
+}
+
+/**
+ * The search keys declared for *path*, or a refusal naming what is mounted.
+ *
+ * A path the router never mounted is a programming error, not an empty result: returning
+ * `{}` would hand a screen `undefined` for every key it asked for, which reads as "no
+ * filters applied" — the silent-wrong-answer this refusal replaces.
+ */
+export function declaredSearchKeys(
+  index: ReadonlyMap<string, readonly string[]> | null,
+  path: string,
+): readonly string[] {
+  if (index === null) {
+    throw new Error(
+      `useRouteSearch("${path}") was called outside a Terp router. It reads the declarations ` +
+        "the router was built from, so it only works under a view mounted by buildAppRouter.",
+    );
+  }
+  const declared = index.get(canonicalRoutePath(path));
+  if (declared === undefined) {
+    throw new Error(
+      `Route "${path}" is not a mounted route, so its search keys are unknown (mounted: ` +
+        `${[...index.keys()].join(", ") || "none"}). useRouteSearch takes the path as written ` +
+        "in the module manifest — check it there, and run `terp routes` if the manifest changed.",
+    );
+  }
+  return declared;
+}
+
+/** The mounted routes' search-key index, or null outside a Terp router. */
+export function useRouteSearchIndex(): ReadonlyMap<string, readonly string[]> | null {
+  return useContext(RouteSearchContext);
+}

package/src/routeTypes.ts

@@ -26,6 +26,24 @@
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentation target
 export interface TerpRouteTable {}
 
+/**
+ * The query-string half of the same table (ADR 0096): path -> its declared search keys.
+ *
+ * Params were checked and search keys were not, which sounds like a gap and behaves like
+ * a hole: a list screen's filters, its sort and its page cursor all live in the query
+ * string, so *every* screen with a filter had to leave the typed seam and reach for the
+ * router's own `useNavigate` / `useSearch` — losing path checking too, on the majority of
+ * screens. Declaring the keys in the manifest (`search: ["status", "page"]`) is what lets
+ * navigation and reads stay inside the checked seam.
+ *
+ * Keyed only for routes that declare keys, so a route with none refuses `search` outright
+ * rather than accepting anything. Values are `string | undefined`: a query parameter is
+ * text and is absent until set — parsing is the screen's business, and the declaration is
+ * what stops the *key* being a typo.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentation target
+export interface TerpRouteSearchTable {}
+
 /** True when no `routes.gen.d.ts` has augmented {@link TerpRouteTable}. */
 type Ungenerated = keyof TerpRouteTable extends never ? true : false;
 
@@ -50,14 +68,40 @@ export type TerpRouteParamName = Ungenerated extends true
   : { [P in keyof TerpRouteTable]: keyof TerpRouteTable[P] }[keyof TerpRouteTable] & string;
 
 /**
- * A navigation target: a declared path, plus that path's params when it takes any.
- * A paramless route refuses a `params` object; a parameterised one requires it, with
- * the names the manifest declared. Before generating, this is the loose shape.
+ * One route's declared query-string keys, all optional.
+ *
+ * Three cases, and the middle one is the point. Before `terp routes` has generated, the
+ * shape is loose (like {@link TerpRouteParams}) so an app that has not adopted keeps
+ * today's behavior. Once generated, a route that declared keys gets exactly those; a
+ * route that declared **none** gets `Record<never, never>`, so passing `search` to it is a
+ * typecheck error rather than a value silently dropped into the URL.
+ */
+export type TerpRouteSearch<P extends TerpRoutePath> = P extends keyof TerpRouteSearchTable
+  ? TerpRouteSearchTable[P]
+  : Ungenerated extends true
+    ? Record<string, string | undefined>
+    : Record<never, never>;
+
+/** Every search key any route declares — or `string` before generating. */
+export type TerpRouteSearchKey = Ungenerated extends true
+  ? string
+  : { [P in keyof TerpRouteSearchTable]: keyof TerpRouteSearchTable[P] }[keyof TerpRouteSearchTable] &
+      string;
+
+/**
+ * A navigation target: a declared path, that path's params when it takes any, and that
+ * path's declared search keys when it reads any.
+ *
+ * A paramless route refuses a `params` object; a parameterised one requires it, with the
+ * names the manifest declared. `search` is always optional (a route may be visited with
+ * no filters applied) but its *keys* are the declared ones, so a typo is a typecheck
+ * error and a route that declares no search keys refuses the property. Before generating,
+ * this is the loose shape.
  */
 export type TerpNavigateTarget = Ungenerated extends true
-  ? { to: string; params?: Record<string, string> }
+  ? { to: string; params?: Record<string, string>; search?: Record<string, string | undefined> }
   : {
-      [P in keyof TerpRouteTable & string]: keyof TerpRouteTable[P] extends never
+      [P in keyof TerpRouteTable & string]: (keyof TerpRouteTable[P] extends never
         ? { to: P; params?: undefined }
-        : { to: P; params: TerpRouteTable[P] };
+        : { to: P; params: TerpRouteTable[P] }) & { search?: TerpRouteSearch<P> };
     }[keyof TerpRouteTable & string];

package/src/router.test.tsx

@@ -5,7 +5,13 @@ 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";
 
@@ -303,6 +309,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

package/src/router.tsx

@@ -7,6 +7,7 @@ import {
   useNavigate,
   useParams,
   useRouter,
+  useSearch,
   type AnyRoute,
   type RouterHistory,
 } from "@tanstack/react-router";
@@ -21,11 +22,18 @@ import type {
   TerpRouteParamName,
   TerpRouteParams,
   TerpRoutePath,
+  TerpRouteSearch,
 } from "./routeTypes";
 import { LAYOUT_CONTRACTS, LayoutContractContext } from "./layoutContract";
 import { visibleNav } from "./nav";
 import { NavLinkContext } from "./navLink";
 import { PageMarkerContext } from "./pageMarker";
+import {
+  RouteSearchContext,
+  declaredSearchKeys,
+  indexSearchKeys,
+  useRouteSearchIndex,
+} from "./routeSearch";
 import { useAuth } from "./TerpProvider";
 import { UserMenu } from "./UserMenu";
 import { useStrings } from "./uiText";
@@ -169,9 +177,56 @@ export function useTerpNavigate(): (target: TerpNavigateTarget) => Promise<void>
       // runtime TanStack types `params` as a reducer (or `true`), and merging over the
       // previous params is also the honest semantic for an in-place param change.
       params: (previous: Record<string, unknown>) => ({ ...previous, ...(target.params ?? {}) }),
+      // Search is REPLACED, not merged (ADR 0096). Merging reads as convenient and is the
+      // wrong default for the case this exists to serve: clearing a filter means sending
+      // the key as undefined, and a merge would keep the old value instead — so "clear"
+      // would silently not clear. A screen that wants to keep other keys passes them,
+      // which is also the only form that stays checkable against the declared key set.
+      search: dropUndefined(target.search),
     });
 }
 
+/**
+ * Drop `undefined` values so a cleared filter leaves the URL instead of appearing as
+ * `?status=undefined`, and an all-cleared search yields a bare path.
+ */
+function dropUndefined(
+  search: Record<string, string | undefined> | undefined,
+): Record<string, string> {
+  const kept: Record<string, string> = {};
+  for (const [key, value] of Object.entries(search ?? {})) {
+    if (value !== undefined) {
+      kept[key] = value;
+    }
+  }
+  return kept;
+}
+
+/**
+ * Read the current route's declared query-string keys (ADR 0096).
+ *
+ * ```tsx
+ * const { status, page } = useRouteSearch("/records");
+ * ```
+ *
+ * Every key is `string | undefined`, because a query parameter is text and is absent
+ * until someone sets it — so a screen destructures with defaults rather than branching on
+ * a bag of `unknown`. Reading a key the route did not declare is a typecheck error once
+ * `terp routes` has generated; before that the shape is loose, exactly like the params
+ * helpers. Undeclared keys present in the URL are **not** returned: the declaration is the
+ * surface, so a stray key someone hand-typed cannot leak into a screen's logic.
+ */
+export function useRouteSearch<P extends TerpRoutePath>(path: P): TerpRouteSearch<P> {
+  const search = useSearch({ strict: false }) as Record<string, unknown>;
+  const declared = declaredSearchKeys(useRouteSearchIndex(), path);
+  const resolved: Record<string, string | undefined> = {};
+  for (const name of declared) {
+    const value = search[name];
+    resolved[name] = typeof value === "string" ? value : undefined;
+  }
+  return resolved as TerpRouteSearch<P>;
+}
+
 export interface BuildAppRouterOptions {
   /** Maps a manifest route's `view` id to the component that renders it. */
   views: Record<string, ComponentType>;
@@ -251,6 +306,15 @@ export function buildAppRouter(
     );
   }
 
+  // The runtime half of the search declaration (ADR 0096): the generated table is types
+  // only, so `useRouteSearch` reads the keys from the manifests this router was built from,
+  // published per router through a context (never a module-level table, which every router
+  // in the process would share).
+  const searchKeys = new Map(indexSearchKeys(manifests));
+  if (!searchKeys.has(PROFILE_PATH)) {
+    searchKeys.set(PROFILE_PATH, []);
+  }
+
   function Shell() {
     const router = useRouter();
     const rank = useAuth().currentUser()?.role_rank ?? null;
@@ -330,15 +394,17 @@ export function buildAppRouter(
         return <Unauthorized />;
       }
       return (
-        <LayoutContractContext.Provider value={layoutContract}>
-          <PageMarkerContext.Provider
-            value={() => {
-              marked.current = true;
-            }}
-          >
-            <View />
-          </PageMarkerContext.Provider>
-        </LayoutContractContext.Provider>
+        <RouteSearchContext.Provider value={searchKeys}>
+          <LayoutContractContext.Provider value={layoutContract}>
+            <PageMarkerContext.Provider
+              value={() => {
+                marked.current = true;
+              }}
+            >
+              <View />
+            </PageMarkerContext.Provider>
+          </LayoutContractContext.Provider>
+        </RouteSearchContext.Provider>
       );
     }
     return createRoute({