@terpjs/react-core 0.5.9 → 0.6.0

package/src/layoutContract.test.tsx

@@ -21,6 +21,7 @@ import {
 import { OverviewPage } from "./OverviewPage";
 import { Page } from "./Page";
 import { DetailList, Stack } from "./layout";
+import { Card } from "./ui/Card";
 
 afterEach(cleanup);
 
@@ -120,6 +121,7 @@ describe("runtime slot enforcement", () => {
   it("passes a DetailPage of record sections and refuses a rogue one", async () => {
     underContract(
       <DetailPage title="Record 1" parents={[{ label: "Records", to: "/records" }]}>
+        <Card title="A section">the sanctioned visual separation, directly in the slot</Card>
         <Stack>
           <DetailList items={[{ label: "Status", value: "open" }]} />
         </Stack>

package/src/layoutContract.ts

@@ -9,6 +9,10 @@ import { createContext, useContext } from "react";
  * a `data-terp` marker on its root — and refuses the view, fail closed, with the same
  * agent-directive message the `terp/layout-contract` lint rule phrases.
  *
+ * Both halves govern the slot's DIRECT children only: an allowed container's own
+ * subtree (a Card's body, a Stack's rows) is the app's to compose — nesting content
+ * inside an allowed component is sanctioned composition, not an escape hatch.
+ *
  * This table is the TypeScript mirror of the spec-as-data source in
  * `@terpjs/eslint-boundaries/src/layouts.js` (react-core ships standalone, so it cannot
  * import a lint package); the parity test in ./layoutContract.test.tsx keeps the two
@@ -33,8 +37,9 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
       "The standard three-level shape: hub bodies are card grids (HubCard only), " +
       "overview bodies are data collections (DataView / ResourceList + framework " +
       "states), detail bodies are record sections (DetailList / Stack / Tabs + " +
-      "framework states). A bespoke screen composes the plain Page, which the " +
-      "contract deliberately leaves unconstrained.",
+      "framework states); Card is allowed in overview and detail bodies as the " +
+      "sanctioned visual separation between sections. A bespoke screen composes " +
+      "the plain Page, which the contract deliberately leaves unconstrained.",
     slots: {
       HubPage: {
         components: { HubCard: "hubcard" },
@@ -45,6 +50,7 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
           ResourceList: "resource-list",
           ModuleNav: "module-nav",
           Stack: "stack",
+          Card: "card",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",
@@ -59,6 +65,7 @@ export const LAYOUT_CONTRACTS: Readonly<Record<string, LayoutContractSpec>> = {
           Tabs: "tabs",
           ModuleNav: "module-nav",
           DataView: "dataview",
+          Card: "card",
           EmptyState: "empty-state",
           ErrorState: "error-state",
           LoadingState: "loading-state",

package/src/routeTypes.ts

@@ -0,0 +1,63 @@
+/**
+ * The type-level route table an app's generated `routes.gen.d.ts` augments (ADR 0092).
+ *
+ * `buildAppRouter` realises routes at runtime from manifest data, so TanStack Router's
+ * own type registry is empty for every Terp app: no route path and no param name is
+ * checked anywhere, and a typo ships green. The information to check them is already
+ * checked in — the manifests are static data — so `terp routes` extracts it and emits a
+ * committed declaration file that augments this interface:
+ *
+ * ```ts
+ * declare module "@terpjs/react-core" {
+ *   interface TerpRouteTable {
+ *     "/records": Record<never, never>;
+ *     "/records/:recordId": { recordId: string };
+ *   }
+ * }
+ * ```
+ *
+ * Paths are keyed in the manifest's stack-agnostic spelling (`:recordId`, not `$recordId`),
+ * which is the spelling {@link useTerpNavigate} accepts and translates.
+ *
+ * Deliberately empty here: with no generated file the table has no keys, every helper
+ * below falls back to `string`, and an app that has not generated keeps exactly today's
+ * behavior. Generating is what turns these checks on.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- augmentation target
+export interface TerpRouteTable {}
+
+/** True when no `routes.gen.d.ts` has augmented {@link TerpRouteTable}. */
+type Ungenerated = keyof TerpRouteTable extends never ? true : false;
+
+/** Every route path the app's manifests declare — or `string` before generating. */
+export type TerpRoutePath = Ungenerated extends true ? string : keyof TerpRouteTable & string;
+
+/** The params of one declared route (`Record<never, never>` for a paramless route). */
+export type TerpRouteParams<P extends TerpRoutePath> = P extends keyof TerpRouteTable
+  ? TerpRouteTable[P]
+  : Record<string, string>;
+
+/**
+ * Every param name declared by any route — or `string` before generating.
+ *
+ * This is the union across all routes, not per route: it refuses a name no route
+ * declares (the reported failure mode, where a typo silently yielded `undefined`),
+ * while a name belonging to a *different* route stays a runtime refusal. Read params
+ * through {@link useRouteParams} when you want the exact, per-route check.
+ */
+export type TerpRouteParamName = Ungenerated extends true
+  ? string
+  : { [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.
+ */
+export type TerpNavigateTarget = Ungenerated extends true
+  ? { to: string; params?: Record<string, string> }
+  : {
+      [P in keyof TerpRouteTable & string]: keyof TerpRouteTable[P] extends never
+        ? { to: P; params?: undefined }
+        : { to: P; params: TerpRouteTable[P] };
+    }[keyof TerpRouteTable & string];

package/src/router.test.tsx

@@ -5,7 +5,7 @@ import { useEffect, useState } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ModuleManifest } from "@terpjs/contract";
 
-import { buildAppRouter } from "./router";
+import { buildAppRouter, useRouteParam, useRouteParams, useTerpNavigate } from "./router";
 import { Page } from "./Page";
 import { TerpProvider, useAuth } from "./TerpProvider";
 
@@ -16,6 +16,22 @@ function jsonResponse(body: unknown): Response {
   });
 }
 
+/** The login + session-probe fetch a routed test needs to reach a guarded view. */
+function sessionFetch() {
+  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",
+    });
+  });
+}
+
 afterEach(() => {
   cleanup();
   vi.restoreAllMocks();
@@ -126,6 +142,167 @@ describe("buildAppRouter", () => {
     }
   });
 
+  it("useRouteParam reads a declared param and refuses an undeclared name, fail closed", async () => {
+    // buildAppRouter realises routes at runtime, so TanStack's type registry cannot
+    // check a param name for any app — useRouteParam is the sanctioned read: the
+    // declared param comes back, an undeclared name throws a directive error instead
+    // of silently yielding undefined (the failure mode of the raw `as {...}` cast).
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const fetchMock = 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" });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    function ThingView() {
+      const thingId = useRouteParam("thingId");
+      return <Page title={`Thing ${thingId}`}>thing body</Page>;
+    }
+    const router = buildAppRouter(
+      [{ name: "things", routes: [{ path: "/things/:thingId", view: "Thing" }], nav: [] }],
+      {
+        views: { Thing: ThingView },
+        title: "Terp",
+        history: createMemoryHistory({ initialEntries: ["/things/abc"] }),
+      },
+    );
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={router} />
+      </TerpProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Thing abc" })).toBeInTheDocument(),
+    );
+    cleanup();
+
+    function WrongParamView() {
+      const nope = useRouteParam("thisParamDoesNotExist");
+      return <Page title={`Wrong ${nope}`}>wrong body</Page>;
+    }
+    const wrongRouter = buildAppRouter(
+      [{ name: "things", routes: [{ path: "/things/:thingId", view: "Thing" }], nav: [] }],
+      {
+        views: { Thing: WrongParamView },
+        title: "Terp",
+        history: createMemoryHistory({ initialEntries: ["/things/abc"] }),
+      },
+    );
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider router={wrongRouter} />
+      </TerpProvider>,
+    );
+    // The view throws before it can render; the screen never shows the wrong body.
+    await waitFor(() => expect(console.error).toHaveBeenCalled());
+    expect(screen.queryByRole("heading", { name: /Wrong/ })).not.toBeInTheDocument();
+  });
+
+  it("useRouteParams reads a whole declared route's params, and refuses a stale one", async () => {
+    // The exact read (ADR 0092): keyed by the manifest path, every param that path
+    // declares must be present. A generated table that no longer matches the manifest
+    // therefore fails closed naming the param, instead of leaking undefined into a request.
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function PairView() {
+      const { spaceId, itemId } = useRouteParams("/spaces/:spaceId/items/:itemId");
+      return <Page title={`${spaceId}/${itemId}`}>pair body</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "spaces", routes: [{ path: "/spaces/:spaceId/items/:itemId", view: "Pair" }] }],
+            {
+              views: { Pair: PairView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/spaces/s1/items/i9"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "s1/i9" })).toBeInTheDocument(),
+    );
+    cleanup();
+
+    // The same view under a route that declares only one of the two params.
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [{ name: "spaces", routes: [{ path: "/spaces/:spaceId", view: "Pair" }] }],
+            {
+              views: { Pair: PairView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/spaces/s1"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+    await waitFor(() => expect(console.error).toHaveBeenCalled());
+    expect(screen.queryByRole("heading", { name: /s1/ })).not.toBeInTheDocument();
+  });
+
+  it("useTerpNavigate navigates by the manifest's path spelling, carrying params", async () => {
+    // The manifest spells a param `:id`; TanStack wants `$id`. useTerpNavigate takes the
+    // manifest spelling (what the generated table is keyed by) and translates, so a caller
+    // never holds two spellings — and the params ride along.
+    vi.stubGlobal("fetch", sessionFetch());
+
+    function ListView() {
+      const navigate = useTerpNavigate();
+      return (
+        <Page title="Things view">
+          <button type="button" onClick={() => void navigate({ to: "/things/:thingId", params: { thingId: "abc" } })}>
+            open abc
+          </button>
+        </Page>
+      );
+    }
+    function DetailView() {
+      return <Page title={`Thing ${useRouteParam("thingId")}`}>thing body</Page>;
+    }
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <LogInOnMount />
+        <RouterProvider
+          router={buildAppRouter(
+            [
+              {
+                name: "things",
+                routes: [
+                  { path: "/things", view: "ThingsList" },
+                  { path: "/things/:thingId", view: "ThingDetail" },
+                ],
+              },
+            ],
+            {
+              views: { ThingsList: ListView, ThingDetail: DetailView },
+              title: "Terp",
+              history: createMemoryHistory({ initialEntries: ["/things"] }),
+            },
+          )}
+        />
+      </TerpProvider>,
+    );
+
+    fireEvent.click(await screen.findByRole("button", { name: "open abc" }));
+    await waitFor(() =>
+      expect(screen.getByRole("heading", { name: "Thing abc" })).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

@@ -4,6 +4,8 @@ import {
   createRouter,
   Link,
   Outlet,
+  useNavigate,
+  useParams,
   useRouter,
   type AnyRoute,
   type RouterHistory,
@@ -14,6 +16,12 @@ import type { ModuleManifest } from "@terpjs/contract";
 
 import { AppShell } from "./AppShell";
 import { ProfileView } from "./ProfileView";
+import type {
+  TerpNavigateTarget,
+  TerpRouteParamName,
+  TerpRouteParams,
+  TerpRoutePath,
+} from "./routeTypes";
 import { LAYOUT_CONTRACTS, LayoutContractContext } from "./layoutContract";
 import { visibleNav } from "./nav";
 import { NavLinkContext } from "./navLink";
@@ -47,6 +55,123 @@ export function routerPath(path: string): string {
   return path.replace(/(^|\/):([A-Za-z_][A-Za-z0-9_]*)/g, "$1$$$2");
 }
 
+/** Read the router's params bag, whatever route matched (a hook: it reads router state). */
+function useCurrentParams(): Record<string, string | undefined> {
+  return useParams({ strict: false }) as Record<string, string | undefined>;
+}
+
+/** The shared refusal both param reads raise, phrased as a directive. */
+function missingParam(name: string, params: Record<string, string | undefined>): Error {
+  const seen = Object.keys(params);
+  return new Error(
+    `Route param "${name}" is not present on the current route (params seen: ` +
+      `${seen.length > 0 ? seen.join(", ") : "none"}). A param is declared in the ` +
+      `module manifest's route path (e.g. "/records/:${name}") and must be read ` +
+      "under that route — check the name against the manifest, and run `terp routes` " +
+      "if the manifest changed.",
+  );
+}
+
+/**
+ * Read one route param by name, fail closed — the untyped core.
+ *
+ * Internal on purpose. The app-facing {@link useRouteParam} checks the name against the
+ * app's generated route table, and this package's own packaged screens (the admin area)
+ * must NOT be checked against it: their routes come from this package's manifest, not
+ * from the app's, so constraining them to the app's declared params would fail an app
+ * that simply declares no params of its own. A packaged screen's route correctness is
+ * this package's own test surface.
+ */
+export function useDeclaredParam(name: string): string {
+  const params = useCurrentParams();
+  const value = params[name];
+  if (value === undefined) {
+    throw missingParam(name, params);
+  }
+  return value;
+}
+
+/**
+ * Read one route param, fail closed when it is absent.
+ *
+ * The name is checked against the app's generated route table when there is one
+ * ({@link TerpRouteParamName} — every param name any manifest route declares), and is
+ * a plain `string` before `terp routes` has generated. Either way a name the *current*
+ * route did not declare throws a directive error instead of silently yielding
+ * `undefined`, which is what the raw `useParams({ strict: false }) as {…}` cast did.
+ *
+ * Reach for {@link useRouteParams} when you want the exact, per-route check: keyed by
+ * the route path, it refuses a param that route does not declare, not merely one no
+ * route declares.
+ */
+export function useRouteParam(name: TerpRouteParamName): string {
+  return useDeclaredParam(name);
+}
+
+/**
+ * Read a declared route's params as a typed object — the exact read (ADR 0092).
+ *
+ * ```tsx
+ * const { recordId } = useRouteParams("/records/:recordId");
+ * ```
+ *
+ * Once `terp routes` has generated the app's route table, the path must be one the
+ * manifests declare and the returned object carries exactly that route's params, so a
+ * typo in either the path or a param name is a typecheck error rather than a runtime
+ * surprise. Before generating, the path is a plain `string` and the result is a
+ * string-keyed record.
+ *
+ * The path is the manifest's stack-agnostic spelling (`:recordId`). Every declared
+ * param must be present at runtime; a missing one fails closed, which is how a stale
+ * generated table (manifest changed, `terp routes` not re-run) surfaces as an error
+ * naming the param instead of `undefined` flowing into a request.
+ */
+export function useRouteParams<P extends TerpRoutePath>(path: P): TerpRouteParams<P> {
+  const params = useCurrentParams();
+  const declared = declaredParamNames(path);
+  const resolved: Record<string, string> = {};
+  for (const name of declared) {
+    const value = params[name];
+    if (value === undefined) {
+      throw missingParam(name, params);
+    }
+    resolved[name] = value;
+  }
+  return resolved as TerpRouteParams<P>;
+}
+
+/** The param names a manifest path declares, in declaration order (`:name` segments). */
+function declaredParamNames(path: string): string[] {
+  return [...path.matchAll(/(?:^|\/)[:$]([A-Za-z_][A-Za-z0-9_]*)/g)].map((match) => match[1]!);
+}
+
+/**
+ * Navigate to a declared route, with that route's params (ADR 0092).
+ *
+ * ```tsx
+ * const navigate = useTerpNavigate();
+ * void navigate({ to: "/records/:recordId", params: { recordId: row.id } });
+ * ```
+ *
+ * The reason to prefer this over the router's own `navigate`: once the route table is
+ * generated, an undeclared path is a typecheck error, a parameterised route *requires*
+ * its params, and the param names are the manifest's. A typo'd path was previously a
+ * dead link that shipped green — nothing checked it, because the route tree is built at
+ * runtime. Paths are written in the manifest spelling and translated to the router's
+ * dialect here ({@link routerPath}), so callers never hold two spellings.
+ */
+export function useTerpNavigate(): (target: TerpNavigateTarget) => Promise<void> {
+  const navigate = useNavigate();
+  return (target: TerpNavigateTarget) =>
+    navigate({
+      to: routerPath(target.to),
+      // The reducer form, not a bare object: on a router whose route tree is built at
+      // 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 ?? {}) }),
+    });
+}
+
 export interface BuildAppRouterOptions {
   /** Maps a manifest route's `view` id to the component that renders it. */
   views: Record<string, ComponentType>;

package/src/ui/Badge.tsx

@@ -26,7 +26,11 @@ const toneColor: Record<BadgeTone, string> = {
   danger: "var(--color-status-danger)",
 };
 
-const toneSoft: Record<BadgeTone, string> = {
+/**
+ * Soft tint per tone — exported (not via the package barrel) so DataView's row/card
+ * tinting resolves a tone to the exact same tokens the Badge pill uses.
+ */
+export const toneSoftColors: Record<BadgeTone, string> = {
   neutral: "var(--color-neutral-100)",
   info: "var(--color-status-info-soft)",
   success: "var(--color-status-success-soft)",
@@ -37,11 +41,11 @@ const toneSoft: Record<BadgeTone, string> = {
 const badgeStyle = (tone: BadgeTone): CSSProperties => ({
   display: "inline-flex",
   alignItems: "center",
-  border: `1px solid ${toneSoft[tone]}`,
+  border: `1px solid ${toneSoftColors[tone]}`,
   borderRadius: "var(--radius-full)",
   padding: "2px var(--space-2)",
   color: toneColor[tone],
-  background: toneSoft[tone],
+  background: toneSoftColors[tone],
   fontSize: "var(--font-size-xs)",
   fontWeight: "var(--font-weight-semibold)" as never,
   lineHeight: 1.4,

package/src/ui/Card.tsx

@@ -52,9 +52,11 @@ const descriptionStyle: CSSProperties = {
 
 /**
  * A token-styled surface that groups one block of a page — the sanctioned way to give
- * sections visual separation (border + background + padding) without module CSS. An
- * optional header row carries a semantic `<h3>` title, a muted description and an
- * `actions` slot; the body stacks its children on the token spacing scale.
+ * sections visual separation (border + background + padding) without module CSS, and
+ * allowed directly in `OverviewPage` / `DetailPage` body slots under the `standard`
+ * layout contract. An optional header row carries a semantic `<h3>` title, a muted
+ * description and an `actions` slot; the body stacks its children on the token
+ * spacing scale.
  */
 export function Card({
   title,

package/src/unwrap.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { ApiError, unwrap } from "./unwrap";
+import { ApiError, unwrap, unwrapOptional } from "./unwrap";
 
 function response(status: number): Response {
   return new Response(null, { status });
@@ -65,3 +65,34 @@ describe("unwrap", () => {
     expect(apiError.message).toBe("Row changed.");
   });
 });
+
+describe("unwrapOptional", () => {
+  it("returns the data on a 2xx result, like unwrap", () => {
+    expect(unwrapOptional({ data: { id: "s1" }, response: response(200) })).toEqual({
+      id: "s1",
+    });
+  });
+
+  it("returns null on a 404 — absence is a normal state, not a failure", () => {
+    expect(
+      unwrapOptional({
+        error: { code: "not_found", detail: "No snapshot published yet." },
+        response: response(404),
+      }),
+    ).toBeNull();
+  });
+
+  it("throws the same ApiError as unwrap for every other failure", () => {
+    let caught: unknown;
+    try {
+      unwrapOptional({
+        error: { code: "permission_denied", detail: "You do not have permission." },
+        response: response(403),
+      });
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toBeInstanceOf(ApiError);
+    expect((caught as ApiError).status).toBe(403);
+  });
+});

package/src/unwrap.ts

@@ -40,6 +40,22 @@ export class ApiError extends Error {
   }
 }
 
+/**
+ * {@link unwrap} for a resource whose absence is a normal state, not a failure: returns
+ * the data on success, `null` on a 404, and throws the same {@link ApiError} for every
+ * other failure. The client-side analog of the backend's `BaseService.find` beside
+ * `get` — reach for `unwrap` when a missing record ends the request, `unwrapOptional`
+ * when "not there yet" is an answer (a `/latest` snapshot that has not been published,
+ * an optional singleton). Without it, expressing that state means exception control
+ * flow around `unwrap` at every call site.
+ */
+export function unwrapOptional<T>(result: FetchResult<T>): T | null {
+  if (result.response.status === 404) {
+    return null;
+  }
+  return unwrap(result);
+}
+
 /** Return the result's `data` on success, or throw an {@link ApiError} describing the failure. */
 export function unwrap<T>(result: FetchResult<T>): T {
   if (result.error !== undefined || !result.response.ok) {

package/src/useRecord.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useRecord } from "./useRecord";
+
+afterEach(cleanup);
+
+describe("useRecord", () => {
+  it("loads on mount and exposes the record", async () => {
+    const { result } = renderHook(() =>
+      useRecord<{ id: string }>({ get: async () => ({ id: "r1" }) }),
+    );
+    expect(result.current.loading).toBe(true);
+    expect(result.current.item).toBeNull();
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.item).toEqual({ id: "r1" });
+    expect(result.current.error).toBeNull();
+  });
+
+  it("treats a null get as a normal absent state, not an error (unwrapOptional composes)", async () => {
+    const { result } = renderHook(() => useRecord<{ id: string }>({ get: async () => null }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.item).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("reloads when a declared dependency changes (in-place route-param navigation)", async () => {
+    const get = vi.fn(async (id: string) => ({ id }));
+    const { result, rerender } = renderHook(
+      ({ id }: { id: string }) => useRecord({ get: () => get(id) }, [id]),
+      { initialProps: { id: "r1" } },
+    );
+    await waitFor(() => expect(result.current.item).toEqual({ id: "r1" }));
+
+    rerender({ id: "r2" });
+    await waitFor(() => expect(result.current.item).toEqual({ id: "r2" }));
+    expect(get).toHaveBeenCalledTimes(2);
+
+    // A rerender with the same dependency does not refetch.
+    rerender({ id: "r2" });
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(get).toHaveBeenCalledTimes(2);
+  });
+
+  it("captures a get error as a message and its cause", async () => {
+    const { result } = renderHook(() =>
+      useRecord<string>({
+        get: async () => {
+          throw new Error("boom");
+        },
+      }),
+    );
+    await waitFor(() => expect(result.current.error).toBe("boom"));
+    expect(result.current.cause).toBeInstanceOf(Error);
+    expect(result.current.item).toBeNull();
+  });
+
+  it("mutate surfaces write failures, rejects, and reloads on success", async () => {
+    let label = "before";
+    const { result } = renderHook(() => useRecord({ get: async () => ({ label }) }));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    await act(async () => {
+      await expect(
+        result.current.mutate(async () => {
+          throw new Error("Save failed.");
+        }),
+      ).rejects.toThrow("Save failed.");
+    });
+    expect(result.current.error).toBe("Save failed.");
+
+    await act(async () => {
+      await result.current.mutate(async () => {
+        label = "after";
+      });
+    });
+    expect(result.current.item).toEqual({ label: "after" });
+    expect(result.current.error).toBeNull();
+  });
+});