@terpjs/react-core 0.7.0 → 0.9.0

package/src/locale.tsx

@@ -218,8 +218,28 @@ export function LanguageSwitcher({ variant = "stacked" }: LanguageSwitcherProps)
   if (context === null || context.locales.length < 2) {
     return null;
   }
+  // Hoisted out of the attribute rather than inlined as `variant === "inline"`, and not for
+  // readability: the marker inventory scanner reads every string literal inside a
+  // `data-terp={…}` expression as a marker, so the comparison's own "inline" was picked up as
+  // a component marker that nothing styles. Keep marker expressions to marker literals.
+  const isInline = variant === "inline";
   const menu = (
-    <Menu trigger={<Icon name="globe" size="1.15rem" />} triggerLabel={strings.language}>
+    <Menu
+      // Claim the root ONLY when this Menu is the root, which is the inline variant. The
+      // stacked variant renders its own div and puts the menu inside it, so stamping the
+      // same marker unconditionally put it on BOTH elements — and the inner wrapper then
+      // matched the stacked grid rule instead of the popover wrapper's geometry. The
+      // baselines did not catch that: a one-child grid and a one-child inline-flex box
+      // shrink-wrap to the same pixels, so it was wrong and invisible at the same time.
+      data-terp={isInline ? "language-switcher" : undefined}
+      data-variant={isInline ? "inline" : undefined}
+      // Unconditional, unlike the root marker: the panel is the same panel in both variants, so
+      // a rule for it must reach both. Deriving the owner from the conditional root marker made
+      // this panel "language-switcher" when inline and "popover" when stacked.
+      data-owner="language-switcher"
+      trigger={<Icon name="globe" size="1.15rem" />}
+      triggerLabel={strings.language}
+    >
       {({ close }) => (
         <>
           {context.locales.map((code) => (
@@ -237,12 +257,12 @@ export function LanguageSwitcher({ variant = "stacked" }: LanguageSwitcherProps)
       )}
     </Menu>
   );
-  if (variant === "inline") {
+  if (isInline) {
     return menu;
   }
   return (
-    <div style={{ display: "grid", justifyItems: "start", gap: "var(--space-1)", fontSize: "var(--font-size-sm)" }}>
-      <span style={{ color: "var(--color-neutral-600)" }}>{strings.language}</span>
+    <div data-terp="language-switcher" data-variant="stacked">
+      <span data-terp="language-switcher-label">{strings.language}</span>
       {menu}
     </div>
   );

package/src/markers.test.ts

@@ -21,6 +21,8 @@ import { describe, expect, it } from "vitest";
 //
 // The ambient `ImportMeta.glob` type lives in raw.d.ts, shared with the other scanning tests.
 
+import manifest from "../package.json";
+
 const sources = import.meta.glob("./**/*.{ts,tsx}", {
   query: "?raw",
   import: "default",
@@ -37,51 +39,193 @@ 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",
+  "alert-title",
+  "appshell",
+  "appshell-backdrop",
   "appshell-brand",
+  "appshell-brand-row",
+  "appshell-brand-title",
+  "appshell-column",
+  "appshell-footer",
+  "appshell-header",
+  "appshell-header-group",
+  "appshell-main",
   "appshell-nav",
+  "appshell-nav-label",
+  "appshell-nav-list",
+  "appshell-sidebar",
   "badge",
   "breadcrumbs",
+  "breadcrumbs-current",
+  "breadcrumbs-separator",
   "button",
+  "button-icon",
+  "calendar",
+  "calendar-day",
+  "calendar-grid",
+  "calendar-header",
+  "calendar-title",
+  "calendar-week",
+  "calendar-weekday",
   "card",
   "card-actions",
+  "card-description",
   "card-header",
+  "card-heading",
+  "card-title",
   "checkbox",
+  "combobox",
+  "combobox-empty",
+  "combobox-field",
+  "combobox-list",
+  "combobox-option",
+  "control-label",
   "dataview",
+  "dataview-actions-cell",
   "dataview-card",
+  "dataview-card-body",
+  "dataview-card-expanded",
+  "dataview-card-fields",
+  "dataview-card-heading",
+  "dataview-card-list",
+  "dataview-card-main",
+  "dataview-card-meta",
+  "dataview-card-status",
+  "dataview-card-title",
+  "dataview-column-option",
+  "dataview-column-resizer",
+  "dataview-column-settings",
+  "dataview-column-settings-title",
+  "dataview-column-sort",
+  "dataview-error",
+  "dataview-expand-cell",
+  "dataview-expanded-cell",
+  "dataview-inline-action",
+  "dataview-pager",
+  "dataview-pagination",
   "dataview-row",
+  "dataview-row-actions",
   "dataview-row-open",
+  "dataview-scroll",
+  "dataview-select-cell",
+  "dataview-skeleton",
   "dataview-table",
   "dataview-toolbar",
+  "dataview-toolbar-actions",
+  "dataview-toolbar-count",
+  "dataview-toolbar-layout",
+  "dataview-toolbar-search",
+  "dataview-toolbar-spacer",
+  "dataview-toolbar-status",
   "detail-list",
+  "detail-list-term",
+  "detail-list-value",
   "dialog",
+  "dialog-actions",
+  "dialog-body",
+  "dialog-description",
+  "dialog-title",
   "drawer-focus-end",
   "drawer-focus-start",
   "empty-state",
+  "empty-state-description",
+  "empty-state-icon",
+  "empty-state-title",
   "error-state",
+  "error-state-description",
+  "error-state-icon",
+  "error-state-title",
+  "field",
+  "field-error",
+  "field-hint",
+  "field-label",
+  "field-label-text",
   "hubcard",
   "hubcard-body",
   "hubcard-description",
+  "hubcard-heading",
+  "hubcard-icon",
   "hubcard-link",
   "hubcard-stat",
   "hubcard-title",
+  "hubpage-grid",
+  "icon",
   "iconbutton",
   "input",
+  "language-switcher",
+  "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",
+  "menu-item-check",
+  "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",
   "tab",
+  "tab-list",
+  "tab-panel",
   "tabs",
+  "theme-toggle",
+  "theme-toggle-label",
+  "toast",
+  "toast-body",
+  "toast-icon",
+  "toast-title",
+  "toast-viewport",
   "tooltip",
+  "tooltip-anchor",
+  "user-menu",
+  "user-menu-avatar",
+  "user-menu-email",
+  "user-menu-header",
+  "user-menu-identity",
+  "user-menu-role",
 ];
 
 /**
@@ -98,34 +242,154 @@ const MARKERS = [
  * the reason splits into two shapes worth knowing before the styling migration is planned:
  *
  *   - **Delegates its root.** `theme.tsx` (ThemeToggle) and `locale.tsx` (LanguageSwitcher)
- *     return a bare `Menu` in their `inline` variant — the variant the app shell header
- *     actually uses — so their root already carries `data-terp="menu"` and is
- *     indistinguishable from any other menu. `UserMenu` is the same shape. Marking them
- *     means either threading a marker through `Menu` or introducing a wrapper element.
- *   - **Returns a fragment.** `Markdown` emits a sequence of block elements with no root at
- *     all. A marker requires a wrapper, and a wrapper is a new block box in every consumer's
- *     layout.
+ *     returned a bare `Menu` in their `inline` variant — the variant the app shell header
+ *     actually uses — so their root was `Popover`'s wrapper and indistinguishable from any
+ *     other popover. Both have graduated, and the answer added no DOM: `Popover` takes the
+ *     root's marker as a prop named `data-terp`, `Menu` threads it through, and each
+ *     component names its own root with `data-variant` separating the variants. `UserMenu` was
+ *     the same shape and has graduated too — it was also the last consumer of `Menu`'s
+ *     `triggerStyle` and `panelStyle` props, which are gone: a marked root makes the trigger
+ *     reachable by descending from it, and the PANEL, which is portalled to `document.body`
+ *     and so reachable from nowhere, carries a `data-owner` attribute naming whose panel it
+ *     is.
+ *
+ *     The prop is named for the attribute deliberately. The scanner below reads `data-terp`
+ *     sites in component source, so `<Menu data-terp="theme-toggle">` is seen exactly where
+ *     it looks; a `rootMarker` prop would have put the only mention of the name somewhere the
+ *     scanner never looks, and a marker rendered by nobody's `data-terp` site is precisely
+ *     the blind spot this file exists to close.
+ *   - **Returned a fragment.** `Markdown` emitted a sequence of block elements with no root at
+ *     all, and the objection to marking it was that a wrapper is a new block box in every
+ *     consumer's layout. It has graduated, and that objection turned out to be answerable
+ *     rather than true: the wrapper is `display: contents`, which generates no box, so the
+ *     blocks stay in-flow siblings and become real flex or grid items of any parent that
+ *     spaces its children with `gap`. Zero diff by construction — and a prose-rhythm block
+ *     wrapper remains a later, deliberate change rather than a side effect of marking.
  *
  * Both are styling decisions with visible consequences, not bookkeeping, so they belong to
- * the migration itself rather than to preparation for it. The archetypes, `Field`,
- * `PageActions` and the DataView internals are still unexamined.
+ * the migration itself rather than to preparation for it. The archetypes and the DataView
+ * internals are still unexamined.
+ *
+ * `PageActions` has graduated, and it was the easiest of the shapes above: it already rendered
+ * a real root of its own, so the marker landed on an element that existed and no DOM moved.
+ * Note the one thing it does that a rule cannot — it returns `null` when it has no actions at
+ * all, so its presence is conditional rather than styled, and `:empty` is not a substitute.
+ *
+ * `files.tsx` has left the list without gaining a marker, which is the one exit this ratchet
+ * allows that is not a migration: it turned out to have no styled surface. Its single
+ * declaration was `display: none` on the file picker's hidden plumbing input — the visible
+ * control is a `Button` — and that element is now `hidden`, the attribute HTML provides for
+ * 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
+ * respectively, because each rendered one `iconbutton` or one `dialog`. Both have since
+ * migrated; the gap in the ratchet has not.
+ *
+ * `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",
-  "./Field.tsx",
-  "./LoginView.tsx",
-  "./OverviewPage.tsx",
-  "./PageActions.tsx",
-  "./ProfileView.tsx",
-  "./UserMenu.tsx",
-  "./dataview/DataViewColumnSettings.tsx",
-  "./dataview/DataViewExpandableRow.tsx",
-  "./dataview/DataViewRowActions.tsx",
-  "./files.tsx",
-  "./locale.tsx",
-  "./theme.tsx",
-  "./ui/Markdown.tsx",
-];
+const UNMARKED_STYLED_SURFACES: string[] = [];
+
+/**
+ * How many module-scope base style objects each file still declares — the migration's own
+ * measurable, as a ratchet.
+ *
+ * This exists because `UNMARKED_STYLED_SURFACES` above flatters a file: it lists modules with
+ * NO `data-terp` at all, so a single marker on a single element exempts everything else in the
+ * file. `toast.tsx` and `ConfirmDialog.tsx` were never on that list while styling five and four
+ * unreachable elements respectively, because each rendered one `iconbutton` or one `dialog`.
+ * Both have migrated, and the gap had not — until this.
+ *
+ * Counted per file rather than as a set of filenames, so a PARTIAL migration shows: moving half
+ * of `AppShell`'s twenty-two objects into the sheet has to update the number here. Asserted as
+ * exact equality, which makes it a ratchet in both directions — a new base style object fails,
+ * and a removed one fails until the ledger is corrected. That is the same bargain `MARKERS`
+ * strikes, and it is the point: the number is meant to be read during review.
+ *
+ * What is deliberately NOT counted: a measured value passed inline at a call site. `Icon` sizes
+ * its box from a prop that takes any CSS length, `Stack` passes `align` / `justify` through, and
+ * `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> = {};
+
+/**
+ * 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,
+};
 
 /**
  * `text` with comments removed, so prose naming a marker cannot stand in for rendering one.
@@ -144,6 +408,13 @@ function stripComments(text: string) {
  *
  * A regex anchored to `data-terp="…"` alone misses the conditional form — which is how the
  * DataView row markers are written — so renaming one of those would not fail anything.
+ *
+ * The cost of reading a whole expression is that EVERY string literal inside one counts as a
+ * marker. `data-terp={variant === "inline" ? "theme-toggle" : undefined}` reports both
+ * `inline` and `theme-toggle`, and the first is not a marker at all. That is caught rather
+ * than tolerated — the inventory assertion fails on the phantom name — and the fix is to keep
+ * a marker expression to marker literals by hoisting the comparison out. Worth knowing before
+ * writing a conditional marker, because the failure names a marker nobody added.
  */
 function markersIn(text: string) {
   const source = stripComments(text);
@@ -242,4 +513,62 @@ describe("data-terp markers", () => {
       "the worklist must stay sorted and duplicate-free",
     ).toEqual([...new Set(UNMARKED_STYLED_SURFACES)].sort());
   });
+  it("keeps the inline base-style ledger honest, file by file", () => {
+    // The migration's measurable, gated. A base style object is a module-scope CSSProperties
+    // literal or factory — the shape a component uses to style its own root, and the shape the
+    // sheet replaces. Comments are stripped first so prose naming the type cannot count.
+    const declared: Record<string, number> = {};
+    for (const [file, text] of production) {
+      const matches = stripComments(text).match(/CSSProperties\s*(?:=\s*\{|=>\s*\()/g);
+      if (matches !== null) {
+        declared[file] = matches.length;
+      }
+    }
+    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
+    // from it loads every module and two dozen of them inject. That guarantee is a packaging
+    // property, and nothing asserted it — a `sideEffects: false` added for bundle size, plus
+    // tree-shaking, would remove it silently and the first symptom would be Markdown's blocks
+    // collapsing into one grid item. So the property itself is what this pins.
+    expect(Object.keys(manifest.exports)).toEqual(["."]);
+    expect(manifest.exports["."]).toBe("./src/index.ts");
+    expect(
+      "sideEffects" in manifest,
+      "declaring sideEffects would let a bundler drop the modules that inject the stylesheet",
+    ).toBe(false);
+    // And the sheet has many independent injectors reachable from that entry, or the packaging
+    // properties above prove nothing on their own. The entry does NOT re-export ./styles — the
+    // injection is a module side effect of the components themselves, which is exactly why the
+    // sideEffects assertion is the one that matters.
+    const injectors = production.filter(([, text]) =>
+      stripComments(text).includes("injectTerpStyles()"),
+    );
+    expect(injectors.length).toBeGreaterThan(20);
+    const index = sources["./index.ts"] ?? "";
+    for (const [file] of injectors.slice(0, 3)) {
+      const module = file.replace(/^\.\//, "./").replace(/\.tsx?$/, "");
+      expect(index, `${file} injects the sheet but is not reachable from the entry point`).toContain(
+        `from "${module}"`,
+      );
+    }
+  });
 });

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];