@rsc-kit/mcp 0.14.0 → 0.16.0

package/guides/redirects.md

@@ -0,0 +1,143 @@
+# Redirects
+
+> Leaving a page from inside the render, and what that costs.
+
+```tsx title="src/app/products/[slug]/page.tsx"
+import { redirect } from '@rsc-kit/core/redirect';
+import { findProduct } from '../../../data';
+
+export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const product = await findProduct(slug);
+
+  if (!product) redirect('/products');
+
+  return <h1>{product.name}</h1>;
+}
+```
+
+`redirect` never returns — it throws, which is what stops the component. The
+default status is `307`, because it preserves the method: a redirect out of a
+`POST` does not silently become a `GET` of the target.
+
+A redirect during a navigation stays a navigation. The document does not reload,
+the layouts you are inside stay mounted, and only the part below them changes.
+
+The url that redirected replaces its history entry rather than adding one, so
+Back does not land on it and redirect you again.
+
+## Where you call it matters
+
+This is the part worth understanding, because it is also the security-relevant
+part. Headers flush early on purpose — that is what makes the first paint fast
+— so a redirect decided late has no status line left to use. There are two
+windows, and nothing you write chooses between them:
+
+| Called | Answered with | What the browser saw first |
+| --- | --- | --- |
+| Above every `<Suspense>` boundary | A real `3xx`, or `X-RSC-Redirect` on a navigation | Nothing at all |
+| Inside a boundary | The shell, then the redirect | Layouts, and the fallbacks standing in for what never arrived |
+
+Neither buffers the response. Before anything is written the host is still
+waiting on the shell, so a component that redirects instead of rendering is
+caught there. After that, React already carries an error digest to the client
+and the destination rides along in it.
+
+<Aside type="caution" title="Middleware belongs above the boundaries">
+  A `loading.tsx` wraps the whole page in `<Suspense>`. That is usually what you
+  want — it is how a page gets a frozen shell — but it also means an `await` at
+  the top of that page is *inside* a boundary, and a redirect after it arrives
+  in the second window.
+
+  Nothing from inside the boundary was shown, so a not-found redirect is fine
+  there. An authorization check is different: the layouts above it already
+  rendered and already went out. If a page must reveal nothing at all, the
+  check has to run somewhere that blocks the shell.
+</Aside>
+
+## Where to put an authorization check
+
+In order of preference:
+
+**In `middleware.ts`.** A file beside the layout, run before anything at or below it
+renders, on every path. This is the one built for the job.
+
+
+<Aside type="danger" title="A layout is not a security boundary">
+  It is tempting — a layout renders above the page's boundary, so on a full
+  page load a redirect there happens before anything is sent. But a navigation
+  tells the server which layouts the client already has, in `X-RSC-Segments`,
+  and the server skips re-rendering those. A client that *claims* to hold your
+  layout skips the check:
+
+  ```bash
+  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout' /guarded
+  # 204, X-RSC-Redirect: /orders        ← the middleware ran
+
+  curl -H 'X-RSC: true' -H 'X-RSC-Segments: app/layout,app/guarded/layout' /guarded
+  # 200, and the page's content         ← it did not
+  ```
+
+  The header is not verified and cannot be. Put the check in a `middleware.ts`
+  beside the layout instead — it runs before anything below it renders, on
+  every path. See [Authorization](/guides/authorization).
+</Aside>
+
+**At the top of a page with no `loading.tsx`.** Runs on every render of that
+page, so it is not skippable the way a layout is — but fragile in a different
+way: adding a `loading.tsx` later silently moves the check into the second
+window, and nothing warns.
+
+<Aside type="danger" title="Never catch it and continue">
+  `redirect` communicates by throwing. A `try`/`catch` that swallows everything
+  turns the redirect into a blank region — the component stops, and nothing
+  takes its place. If you must wrap the call, rethrow what you do not
+  recognise:
+
+  ```ts
+  import { isRedirectSignal } from '@rsc-kit/core/redirect';
+
+  try {
+    await mightRedirect();
+  } catch (error) {
+    if (isRedirectSignal(error)) throw error;
+    // …
+  }
+  ```
+</Aside>
+
+## From a server action
+
+An action is not a render, so there is no shell to be on either side of. Throw
+from the action and the client follows it:
+
+```ts title="src/actions.ts"
+'use server'
+
+import { redirect } from '@rsc-kit/core/redirect';
+
+export async function createPost(title: string) {
+  const post = await savePost(title);
+
+  redirect(`/posts/${post.slug}`);
+}
+```
+
+## A route that only redirects
+
+The redirect itself is stored, so it costs no render at all:
+
+```text
+○  /old-pricing   (redirects to /pricing)
+```
+
+The build writes the status and the location, and the host answers from that
+file — a document gets the status code, a navigation gets `X-RSC-Redirect` and
+does it as an SPA navigation. Nothing is rendered per request, and a static
+export can carry it.
+
+## Loops
+
+A navigation follows at most **8** redirects before throwing. A page that
+redirects to itself is a mistake someone will make, and without a ceiling it is
+an unbounded run of full renders rather than an error you can see.

package/guides/response-headers.md

@@ -0,0 +1,66 @@
+# Headers and cookies
+
+> Setting response headers and cookies during a render.
+
+## Reading
+
+Anywhere in a server component or action:
+
+```tsx
+import { headers, cookies, searchParams } from '@rsc-kit/core/request'
+
+export default async function Page() {
+  const h = await headers()
+  const jar = await cookies()
+
+  return <p>Hello {jar.get('name')?.value ?? 'stranger'}</p>
+}
+```
+
+## Writing
+
+```tsx
+import { responseHeaders, cookies } from '@rsc-kit/core/request'
+
+export async function middleware() {
+  responseHeaders().set('X-Frame-Options', 'DENY')
+
+  const jar = await cookies()
+  jar.set('last-seen', new Date().toISOString(), { httpOnly: true, path: '/' })
+}
+```
+
+**Writing only works in middleware.** Middleware runs before the render, while
+the response line has not been sent yet. A component runs *during* streaming,
+when the headers are already on the wire — writing from one throws rather than
+being silently dropped, so you find out immediately.
+
+A redirect carries them too, which is what lets middleware remember where
+someone was going before sending them to log in:
+
+```tsx
+export async function middleware() {
+  const jar = await cookies()
+
+  if (!jar.get('session')) {
+    jar.set('intended', '/dashboard', { path: '/' })
+    redirect('/login')
+  }
+}
+```
+
+## Cookie options
+
+```ts
+jar.set('name', 'value', {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'lax',      // 'strict' | 'lax' | 'none'
+  path: '/',
+  maxAge: 60 * 60 * 24,
+  expires: new Date('2027-01-01'),
+})
+```
+
+Names are validated as cookie tokens and `sameSite` / `expires` are checked, so
+a typo is an error rather than a header the browser quietly ignores.

package/guides/route-interception.md

@@ -0,0 +1,206 @@
+# Route interception
+
+> Opening a route as a modal over the page you were on.
+
+Route interception lets you load a route from a different part of your app within the current layout. When a user clicks a link, the intercepted component renders in a parallel slot (like a modal) while the current page stays visible behind it. On hard navigation (refresh or direct URL), the normal page renders instead.
+
+This follows the same convention as Next.js — using `(.)folder`, `(..)folder`, and `(...)folder` prefixes.
+
+## Convention
+
+| Prefix | Intercepts |
+| --- | --- |
+| (.)folder | Same level — matches a sibling route |
+| (..)folder | One level up — matches a route in the parent segment |
+| (...)folder | Root level — matches a route from the app root |
+
+## A photo modal
+
+The most common use case is showing content in a modal on SPA navigation, with the full page as a fallback on hard navigation.
+
+### File Structure
+
+```tsx title="File structure"
+src/app/
+├── layout.tsx              ← renders {children} + {modal}
+├── page.tsx                ← feed page
+├── @modal/
+│   ├── default.tsx         ← empty by default (no modal open)
+│   └── (.)photo/[id]/
+│       └── page.tsx        ← photo modal (interceptor)
+└── photo/[id]/
+    └── page.tsx            ← full photo page (hard nav)
+```
+
+### Root Layout
+
+The layout receives the `modal` parallel slot as a prop. No special wrapper component needed — just render it directly:
+
+```tsx title="app/layout.tsx"
+export default function Layout({
+  children,
+  modal,
+}: {
+  children: React.ReactNode;
+  modal: React.ReactNode;
+}) {
+  return (
+    <div>
+      <main>{children}</main>
+      {modal}
+    </div>
+  );
+}
+```
+
+### Default Slot
+
+The `@modal/default.tsx` renders when no interception is active:
+
+```tsx title="app/@modal/default.tsx"
+export default function ModalDefault() {
+  return null;
+}
+```
+
+### Interceptor Component
+
+The interceptor at `@modal/(.)photo/[id]/page.tsx` receives the target route's params. It can be a server component — only the frame around it needs to be interactive:
+
+```tsx title="app/@modal/(.)photo/[id]/page.tsx"
+import { ModalShell } from '../../../components/ModalShell';
+import { findPhoto } from '../../../../data';
+
+export default async function PhotoModal({ id }: { id: string }) {
+  const photo = await findPhoto(id);
+
+  return (
+    <ModalShell>
+      <h2>{photo.title}</h2>
+      <p>This renders in a modal on SPA navigation.</p>
+    </ModalShell>
+  );
+}
+```
+
+Read the same data the full page reads. An interceptor pointed at a
+different source than the page it stands in for looks exactly like a
+broken interception: the modal opens correctly and says the record does
+not exist.
+
+### Closing It
+
+The engine puts the interceptor in the slot; the affordances for dismissing it are yours to write. A modal needs three, and the last two are the ones that get forgotten — a close control, the `Escape` key, and a click on the backdrop:
+
+```tsx title="components/ModalShell.tsx"
+"use client";
+
+import { useEffect, useRef } from 'react';
+import type { ReactNode } from 'react';
+
+export function ModalShell({ children }: { children: ReactNode }) {
+  const close = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    // The only way to dismiss a dialog without a pointer.
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') history.back();
+    };
+
+    window.addEventListener('keydown', onKey);
+    close.current?.focus();
+
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
+  return (
+    <div className="modal-backdrop" onClick={() => history.back()}>
+      {/* A click inside the dialog is not a click on the backdrop. */}
+      <article role="dialog" aria-modal="true" onClick={(e) => e.stopPropagation()}>
+        <button ref={close} aria-label="Close" onClick={() => history.back()}>
+          ×
+        </button>
+        {children}
+      </article>
+    </div>
+  );
+}
+```
+
+Closing is `history.back()` rather than a link to a fixed URL. The modal was opened by pushing a history entry over the page beneath, so going back is both what the browser's own back button does and what returns to whatever page it was opened *over* — a hardcoded destination is wrong the moment the same modal is reachable from two places.
+
+The router recognises that as leaving an interception and empties the slot without asking the server for anything. The page underneath never left, so closing costs no request and everything typed into it is still there.
+
+A modal reachable from exactly one place can link to that place instead, and a real `<Link>` is worth keeping for it — a link can be opened in a new tab, and it still works before the page hydrates. `history.back()` is for a shell used from several.
+
+### Full Page (Hard Nav)
+
+When a user navigates directly to `/photo/123` (hard refresh, shared link), the normal page renders:
+
+```tsx title="app/photo/[id]/page.tsx"
+export default function PhotoPage({ id }: { id: string }) {
+  return (
+    <div>
+      <h1>Photo {id}</h1>
+      <p>Full photo page — shown on direct navigation or refresh.</p>
+    </div>
+  );
+}
+```
+
+## How it works
+
+On **SPA navigation** (clicking a Link):
+
+- The client checks the intercept manifest (generated at build time)
+- If the target URL matches an intercept pattern, headers are added to the request
+- The server resolves the current page from the referer URL, to know which slot the interceptor belongs in
+- It renders the interceptor *alone*, and says so with `X-RSC-Revalidate: modal`
+- The client puts it in that slot. The page underneath is never re-rendered — so a half-filled form on it is still half-filled
+
+On **hard navigation** (direct URL, refresh):
+
+- Normal route matching — `/photo/123` renders `photo/[id]/page.tsx`
+- No interception — the full photo page renders
+
+Re-rendering the page underneath would put the modal on screen at the
+cost of rebuilding everything below the layout that declares the slot.
+That page is already mounted and still correct; only the slot is new.
+
+## Nested interception
+
+Use `(..)` to intercept routes one level up, or `(...)` to intercept from the app root:
+
+```tsx title="Intercepting from a nested page"
+// From /feed, intercept /photo/[id] at the same level
+app/@modal/(.)photo/[id]/page.tsx
+
+// From /feed/trending, intercept /photo/[id] one level up
+app/feed/@modal/(..)photo/[id]/page.tsx
+
+// From /dashboard/settings, intercept /photo/[id] from root
+app/dashboard/settings/@drawer/(...)photo/[id]/page.tsx
+```
+
+## Several slots
+
+You can intercept the same route into different slots:
+
+```tsx title="File structure"
+app/
+├── @modal/(.)photo/[id]/page.tsx     ← renders in "modal" slot
+├── @preview/(.)photo/[id]/page.tsx   ← renders in "preview" slot
+└── photo/[id]/page.tsx               ← full page
+```
+
+## Seeing it work
+
+The example app in the repository has a working one: `@modal/(.)posts/[slug]`
+over a feed of posts. Click a post to open it in a modal, then refresh to get
+the same route as a page.
+
+---
+
+Route interception builds on [parallel routes](/guides/routing). The `@folder`
+convention is worth being comfortable with first — an interceptor is a page
+inside a slot, and everything a slot does applies to it.