<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for DeepSeek: scripts/model-profiles.json -->

#Task boundary

1. Implement exactly the task as stated. Do not add abstractions, options, config, or files the task did not name.
2. Comments, identifiers, commit messages and log strings are English only.
3. Stop when the checklist at the end passes. Do not refactor or "improve" surrounding code.
4. Every checklist item below is backed by an assertion in a test or by pasted command output, never by a sentence.

---

#Purpose

Rules for routing in a web application. The URL is the application's public interface: it is what users bookmark, share, and return to. Treat it as a contract, not an implementation detail.

Route-level code splitting is Frontend/code-splitting; metadata is Frontend/metadata.

---

#The URL carries state

Anything that changes what the user sees belongs in the URL.

bash
/orders?status=paid&sort=-createdAt&page=2      ✅ shareable, bookmarkable, back-button-correct
/orders                                          ❌ filters in component state

If state is not in the URL, a refresh loses it and a shared link shows something different — reported by users as "the link doesn't work".

Rules for the URL itself:

1. Lowercase, hyphenated, plural collections: /payment-methods/{id}.
2. Stable. A changed URL is a broken bookmark and a lost search ranking; when you must change one, 301 the old path. → Frontend/seo
3. Never put a secret, token or personal data in a query string — it lands in server logs, browser history and Referer headers. → API/api-security
4. Omit defaults (?page=1 adds nothing) so the canonical URL is unambiguous.
5. Validate and coerce every parameter: a route parameter is untrusted input.

---

#Structure with nested layouts

ini
app/
  layout.tsx                 # shell: header, nav — never re-renders on child navigation
  orders/
    layout.tsx               # orders sidebar
    page.tsx                 # /orders
    [id]/page.tsx            # /orders/:id
    loading.tsx              # streamed fallback
    error.tsx                # boundary for this subtree

Nested layouts preserve state across navigation within a section — scroll position in a sidebar, an open panel — which a flat route table cannot do.

1. Colocate loading and error boundaries per segment, so a failure in one panel does not blank the page.
2. Every route needs a not-found path for a bad or deleted id, returning a real 404 rather than an empty page.
3. Keep dynamic segments shallow. /users/:u/orders/:o/items/:i exposes a hierarchy that will change; one level of nesting is usually enough. → API/rest

---

#Route guards are not authorization

tsx
// A client-side redirect. The data was already fetched, or is one fetch away.
if (!user.isAdmin) return <Navigate to="/" />;

A client-side guard is a user-experience feature: it avoids showing a page that will fail. It is not a control — the user can call the API directly, and the JavaScript that decides is running on their machine.

1. Enforce authorization on the server, on every request that returns data. → Backend/authorization
2. Redirect unauthenticated users to a login page that preserves the intended destination (?next=/orders/123), and validate that parameter against an allowlist of internal paths — an unvalidated redirect target is an open-redirect vulnerability used in phishing.
3. Never render protected content and hide it with CSS. It is in the DOM.

---

#Navigation must not lose the user

Client-side routing replaces a full page load, so the browser behaviours it provided must be reimplemented.

Focus and announcement are the ones most often missed, and they make an application unusable with a screen reader — the user activates a link and nothing tells them anything changed. → Testing/accessibility

Use real <a href> elements (or the router's <Link>, which renders one). A <div onClick={navigate}> breaks middle-click, open-in-new-tab, copy-link, and keyboard access.

---

#Data and transitions

1. Fetch per route with the router's loader or a server component, so the request starts with the navigation rather than after the component mounts.
2. Prefetch on hover, focus or viewport entry — the code and the data.
3. Keep the old view visible during a pending navigation (useTransition, startTransition) rather than flashing a spinner over content that was fine.
4. Handle a failed navigation: leave the user where they were with an error, not on a blank route.

---

#Anti-patterns

---

#Checklist

• Filters, sort, pagination, tab and selection are all in the URL
• No secrets or personal data appear in URLs
• Default parameter values are omitted
• Every route parameter is validated and coerced
• URL changes are accompanied by permanent redirects
• Layouts are nested so shared shell state survives navigation
• Each segment has loading and error boundaries
• A not-found route exists and returns a real 404
• Authorization is enforced server-side; client guards are UX only
• Post-login redirect targets are validated against an allowlist
• Navigation uses real anchor elements
• Scroll resets on new routes and restores on back/forward
• Focus moves to the main content after navigation
• Route changes are announced to assistive technology
• The document title updates per route
• Data loads with the navigation, not after mount
• Routes and their data are prefetched on intent
• Pending navigations keep the previous view visible