remix 3.0.0-beta.2 → 3.0.0-beta.4

package/src/fetch-router/README.md

@@ -8,7 +8,7 @@ A minimal, composable router built on the [web Fetch API](https://developer.mozi
 - **Type-Safe Routing**: Leverage TypeScript for compile-time route validation and parameter inference
 - **Typed Request Context**: Carry request-scoped context through routers, controllers, and actions
 - **Declarative Route Maps**: Define your route structure upfront with type-safe route names and request methods
-- **Flexible Middleware**: Apply middleware globally, per-route, or to controllers
+- **Flexible Middleware**: Use router, controller, and action middleware for each request boundary
 - **Easy Testing**: Use standard `fetch()` to test your routes - no special test harness required
 
 ## Installation
@@ -237,6 +237,85 @@ router.map(routes.contact, {
 })
 ```
 
+### Composing Route Groups
+
+As applications grow, it is useful to let one file own the routes for a specific area of the app while the top-level router decides where that area is mounted. Use `router.mount()` with a route installer to register a group of routes under a route pattern prefix.
+
+A route installer receives a `RouteBuilder`, not a full `Router`, so it can register routes but cannot dispatch requests. The parent router remains the only router that owns request dispatch, the matcher, and the default handler.
+
+```ts
+import { createRouter, type RouteBuilder } from 'remix/router'
+import { get, route } from 'remix/routes'
+
+const adminRouteDefs = {
+  index: get('/'),
+  users: {
+    show: get('/users/:id'),
+  },
+}
+
+// Use relative route groups inside installers. These routes are registered below
+// the mount prefix when `installAdminRoutes()` runs.
+const adminRouteGroup = route(adminRouteDefs)
+
+// Use full app routes for links and redirects.
+const routes = {
+  admin: route('/admin', adminRouteDefs),
+}
+
+function installAdminRoutes<context extends AppContext>(router: RouteBuilder<context>) {
+  router.map(adminRouteGroup, {
+    actions: {
+      index() {
+        return new Response('Admin')
+      },
+    },
+  })
+
+  router.map(adminRouteGroup.users, {
+    actions: {
+      show({ params, currentUser }) {
+        return new Response(`User ${params.id} for ${currentUser.id}`)
+      },
+    },
+  })
+}
+
+let router = createRouter<AppContext>({ middleware })
+
+router.mount('/admin', installAdminRoutes)
+```
+
+Mount prefixes are route patterns. They compose with routes registered inside the installer using `joinPatterns()`, so params from the mount prefix are available to mounted handlers:
+
+```ts
+router.mount('/orgs/:orgId', (org) => {
+  org.get('/users/:userId', ({ params }) => {
+    // params is { orgId: string, userId: string }
+    return new Response(`${params.orgId}:${params.userId}`)
+  })
+})
+```
+
+When a mount prefix and child route use the same param name, the right-most route param wins, matching `route-pattern` behavior.
+
+Middleware stays on routers, controllers, and actions. If an entire route group needs auth or another boundary, put that middleware on the controllers or actions owned by the installer:
+
+```ts
+function installAdminRoutes<context extends AppContext>(router: RouteBuilder<context>) {
+  router.map(adminRouteGroup, {
+    middleware: [requireAdmin()],
+    actions: {
+      index({ admin }) {
+        return new Response(admin.id)
+      },
+    },
+  })
+}
+```
+
+Unknown paths below a mounted prefix fall through to the parent router's default handler. If a route group needs its own catch-all response, register one explicitly inside the installer.
+
 ### Declaring Routes
 
 In addition to the `{ method, pattern }` syntax shown above, the router provides a few shorthand methods that help eliminate some of the boilerplate when building complex route maps:
@@ -504,10 +583,12 @@ type Routes = typeof routes
 
 Middleware functions run code before and/or after actions. They are a powerful way to add functionality to your app.
 
+Every middleware must either return a `Response`, return the response from `next()`, or call `await next()` before it returns. Middleware that returns without calling `next()` throws at runtime.
+
 A basic logging middleware might look like this:
 
 ```ts
-import type { Middleware } from 'remix/router'
+import { type Middleware } from 'remix/router'
 
 // You can use the `Middleware` type to type middleware functions.
 function logger(): Middleware {
@@ -567,8 +648,9 @@ function loadDatabase(): Middleware<{
   value: Database
   property: 'db'
 }> {
-  return async (context) => {
+  return async (context, next) => {
     context.set(Database, await connectDatabase(), { property: 'db' })
+    return next()
   }
 }
 
@@ -580,13 +662,13 @@ router.get('/books', async (context) => {
 
 Use `context.db` (or `context.get(Database)`). If two values use the same property name, the router throws.
 
-Middleware may be used at three levels: globally on the router, on a controller, or inline on an individual action.
+Middleware has three API-owned forms: router middleware, controller middleware, and action middleware.
 
-Global middleware is added to the router when it is created using the `createRouter({ middleware })` option. This middleware runs before any routes are matched and is useful for doing things like logging, serving static files, profiling, and a variety of other things. Global middleware runs on every request, so it's important to keep them lightweight and fast.
+Router middleware is added to the router when it is created using the `createRouter({ middleware })` option. This middleware runs before any routes are matched and is useful for doing things like logging, serving static files, profiling, and a variety of other things. Router middleware runs on every request, so it's important to keep it lightweight and fast.
 
-Controller middleware runs for every direct action in a controller. Action middleware runs only for one action, whether that action is registered in a controller or directly with `router.map()` or one of the method-specific helpers like `router.get()`, `router.post()`, `router.put()`, `router.delete()`, etc. The object form for actions is `{ handler, middleware? }`, so you can omit `middleware` entirely when you do not need it.
+Controller middleware runs for every direct action in a controller. Action middleware runs only for one action, whether that action is created with `createAction()`, registered in a controller, or registered directly with `router.map()` or one of the method-specific helpers like `router.get()`, `router.post()`, `router.put()`, `router.delete()`, etc. The object form for actions is `{ handler, middleware? }`, so you can omit `middleware` entirely when you do not need it.
 
-A controller's `middleware` applies only to the direct route actions in that controller, and its `actions` object may not include nested route-map keys. Map nested route maps explicitly so each controller owns the direct route actions for one route map.
+A controller's `middleware` applies only to the direct route actions in that controller, and its `actions` object may not include nested route-map keys. This is the router's scoped middleware model: map nested route maps explicitly so each controller owns the direct route actions for one route map, and share middleware arrays between controllers that need the same boundary.
 
 ```tsx
 let routes = route({
@@ -598,21 +680,21 @@ let routes = route({
 })
 
 let router = createRouter({
-  // This middleware runs on all requests.
+  // Router middleware runs on all requests.
   middleware: [staticFiles('./public')],
 })
 
 router.map(routes.home, () => new Response('Home'))
 
 router.map(routes.admin, {
-  // This middleware applies to all actions in this controller.
+  // Controller middleware applies to all direct actions in this controller.
   middleware: [auth({ token: 'secret' })],
   actions: {
     dashboard() {
       return new Response('Dashboard')
     },
     settings: {
-      // This middleware applies only to this action.
+      // Action middleware applies only to this action.
       middleware: [requireAdmin()],
       handler() {
         return new Response('Settings')
@@ -655,17 +737,11 @@ router.get('/posts/:id', (context) => {
 
 Route params are only half of a handler's type contract. In many apps, handlers also depend on values that middleware loads into request context, like sessions, database connections, or authenticated users.
 
-`fetch-router` lets you carry that context contract through the router and into stored controllers and actions. A common pattern is to derive one app-local context type from your router middleware, augment `RouterTypes.context` with it, then use `createAction()` and `createController()` to type stored handlers.
+`fetch-router` lets you carry that context contract through the router and into direct route registration, stored controllers, and stored actions. A common pattern is to derive one application context type from your middleware, augment `RouterTypes.context` with it, then use `createAction()` and `createController()` to type stored handlers.
 
 ```ts
 import { Auth, requireAuth } from 'remix/middleware/auth'
-import {
-  createAction,
-  createController,
-  type AnyParams,
-  type ContextWithParams,
-  type MiddlewareContext,
-} from 'remix/router'
+import { createAction, createController, createRouter, type RouterContext } from 'remix/router'
 import { route } from 'remix/routes'
 import { loadDatabase } from './middleware/database.ts'
 import { loadSession } from './middleware/session.ts'
@@ -675,12 +751,12 @@ let routes = route({
 })
 
 type AuthIdentity = { id: string }
-type RootMiddleware = [ReturnType<typeof loadSession>, ReturnType<typeof loadDatabase>]
 
-type AppContext<params extends AnyParams = {}> = ContextWithParams<
-  MiddlewareContext<RootMiddleware>,
-  params
->
+export const router = createRouter({
+  middleware: [loadSession(), loadDatabase()],
+})
+
+type AppContext = RouterContext<typeof router>
 
 declare module 'remix/router' {
   interface RouterTypes {
@@ -688,19 +764,16 @@ declare module 'remix/router' {
   }
 }
 
-let accountMiddleware = [requireAuth<AuthIdentity>()] as const
-type AccountContext = MiddlewareContext<typeof accountMiddleware, AppContext>
-
-let accountAction = createAction<typeof routes.account, AccountContext>(routes.account, {
-  middleware: accountMiddleware,
+let accountAction = createAction(routes.account, {
+  middleware: [requireAuth<AuthIdentity>()],
   handler(context) {
     let auth = context.get(Auth)
     return Response.json({ id: auth.identity.id })
   },
 })
 
-let accountController = createController<typeof routes, AccountContext>(routes, {
-  middleware: accountMiddleware,
+let accountController = createController(routes, {
+  middleware: [requireAuth<AuthIdentity>()],
   actions: {
     account(context) {
       let auth = context.get(Auth)
@@ -710,11 +783,13 @@ let accountController = createController<typeof routes, AccountContext>(routes,
 })
 ```
 
-In this example, `RootMiddleware` is the middleware tuple that defines the app context contract. It should include middleware instances. When a middleware is created by a factory function like `loadSession()`, use `ReturnType<typeof loadSession>` so the type describes the middleware value that actually runs. `AccountContext` applies local account middleware on top of that base context before the handler runs.
+In this example, the router's inline middleware array defines the app context contract. `RouterContext<typeof router>` extracts the request context that the router provides, so `RouterTypes.context` can use that context without storing the middleware chain separately.
+
+Prefer plain inline arrays for `middleware` options on routers, controllers, actions, and route helpers. Inline arrays already give TypeScript enough information to infer middleware-provided context for downstream handlers, so `createAction()` and direct action objects see action middleware context, and `createController()` sees controller middleware context without `createMiddleware()`.
 
-For small apps with a stable tuple-typed runtime array, `MiddlewareContext<typeof middleware>` is a fine shortcut. For larger apps, prefer the named `RootMiddleware` and `AppContext` pattern so runtime middleware assembly and context typing can evolve independently.
+Use `createMiddleware()` only when a middleware chain is stored somewhere and its exact tuple type needs to survive that boundary. The common cases are deriving `MiddlewareContext<typeof rootMiddleware>` without a router value, exporting a reusable chain, or returning a chain from a factory. A standalone array like `let middleware = [loadSession(), loadDatabase()]` widens to a normal array, so `MiddlewareContext<typeof middleware>` cannot derive the ordered middleware context.
 
-When manually annotating stored handlers, use `Action<typeof route, Context>` for values that may be either a plain handler function or an action object with optional middleware.
+When manually annotating stored handlers with `Action<typeof route, Context>` or `Controller<typeof routes, Context>`, compose any action or controller middleware chain into `Context` with `MiddlewareContext<typeof actionOrControllerMiddleware, AppContext>`.
 
 #### Middleware Provider Guidance
 
@@ -729,7 +804,12 @@ If you're authoring a middleware package that stores values in request context,
 Apps can derive request context from the middleware tuple with `MiddlewareContext`. If they need to describe a context shape without a middleware tuple, they can use the core `ContextWithEntry` and `ContextWithEntries` helpers directly.
 
 ```ts
-import { createContextKey, type Middleware, type MiddlewareContext } from 'remix/router'
+import {
+  createContextKey,
+  createMiddleware,
+  type Middleware,
+  type MiddlewareContext,
+} from 'remix/router'
 
 // The context key that consumers will need to read from `context.get(...)`
 export const CurrentUser = createContextKey<User | null>()
@@ -747,7 +827,7 @@ export function loadCurrentUser(): Middleware<{
   }
 }
 
-let middleware = [loadCurrentUser()] as const
+let middleware = createMiddleware(loadCurrentUser())
 type AppContext = MiddlewareContext<typeof middleware>
 
 // Use context.currentUser (or context.get(CurrentUser)).

package/src/file-storage-s3/README.md

@@ -1,7 +1,6 @@
 # file-storage-s3
 
-S3 backend for [`remix/file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage).
-Use this package when you want the `FileStorage` API backed by AWS S3 or an S3-compatible provider.
+S3 backend for [`remix/file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage). Use this package when you want the `FileStorage` API backed by AWS S3 or an S3-compatible provider.
 
 ## Features
 

package/src/form-data-middleware/README.md

@@ -69,8 +69,7 @@ let router = createRouter({
 
 ### Limit Multipart Growth
 
-`formData()` forwards multipart limit options to `parseFormData()`, so you can cap uploads with
-`maxHeaderSize`, `maxFiles`, `maxFileSize`, `maxParts`, and `maxTotalSize`.
+`formData()` forwards multipart limit options to `parseFormData()`, so you can cap uploads with `maxHeaderSize`, `maxFiles`, `maxFileSize`, `maxParts`, and `maxTotalSize`.
 
 ```ts
 let router = createRouter({

package/src/form-data-parser/README.md

@@ -72,8 +72,7 @@ async function requestHandler(request: Request) {
 }
 ```
 
-To validate the resulting `FormData` object with `remix/data-schema`, use the
-`remix/data-schema/form-data` helpers.
+To validate the resulting `FormData` object with `remix/data-schema`, use the `remix/data-schema/form-data` helpers.
 
 To limit the overall shape of multipart requests, use the `maxHeaderSize`, `maxFileSize`, `maxFiles`, `maxParts`, and `maxTotalSize` options. By default, `parseFormData()` uses `maxFiles = 20`, `maxParts = 1000`, and `maxTotalSize = maxFiles * maxFileSize + 1 MiB`.
 
@@ -150,8 +149,7 @@ The [`demos` directory](https://github.com/remix-run/remix/tree/main/packages/fo
 
 ## Related Packages
 
-- [`data-schema`](https://github.com/remix-run/remix/tree/main/packages/data-schema) - Tiny,
-  standards-aligned validation with a `form-data` export for `FormData` and `URLSearchParams`
+- [`data-schema`](https://github.com/remix-run/remix/tree/main/packages/data-schema) - Tiny, standards-aligned validation with a `form-data` export for `FormData` and `URLSearchParams`
 - [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) - A simple key/value interface for storing `FileUpload` objects you get from the parser
 - [`multipart-parser`](https://github.com/remix-run/remix/tree/main/packages/multipart-parser) - The parser used internally for parsing `multipart/form-data` HTTP messages
 

package/src/headers/README.md

@@ -94,6 +94,16 @@ The following headers are currently supported:
 - [Set-Cookie](./README.md#set-cookie)
 - [Vary](./README.md#vary)
 
+If you only need a specific header parser (for example, just `Content-Type`), import that parser directly from its subpath. This avoids pulling the package barrel and `SuperHeaders`:
+
+```ts
+import { ContentType } from 'remix/headers/content-type'
+import { SetCookie } from 'remix/headers/set-cookie'
+
+let contentType = ContentType.from('text/plain; charset=utf-8')
+let setCookie = new SetCookie('session=abc; Path=/')
+```
+
 ### Accept
 
 Parse, manipulate and stringify [`Accept` headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept).

package/src/headers/accept-encoding.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/accept-encoding'

package/src/headers/accept-language.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/accept-language'

package/src/headers/accept.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/accept'

package/src/headers/cache-control.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/cache-control'

package/src/headers/content-disposition.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/content-disposition'

package/src/headers/content-range.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/content-range'

package/src/headers/content-type.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/content-type'

package/src/headers/cookie.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/cookie'

package/src/headers/if-match.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/if-match'

package/src/headers/if-none-match.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/if-none-match'

package/src/headers/if-range.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/if-range'

package/src/headers/range.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/range'

package/src/headers/raw-headers.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/raw-headers'

package/src/headers/set-cookie.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/set-cookie'

package/src/headers/vary.ts

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/headers/vary'

package/src/node-fetch-server/README.md

@@ -124,8 +124,7 @@ async function handler(request: Request) {
 
 ### Custom Hostname Configuration
 
-Configure custom hostnames for deployment on VPS or custom environments. `node-fetch-server` uses
-the `host` option when constructing `request.url`.
+Configure custom hostnames for deployment on VPS or custom environments. `node-fetch-server` uses the `host` option when constructing `request.url`.
 
 ```ts
 import * as http from 'node:http'

package/src/node-tsx/README.md

@@ -2,13 +2,9 @@
 
 Run Node.js with TypeScript and JSX syntax support in `.ts`, `.tsx`, and `.jsx` files.
 
-`node-tsx` transforms supported source files before Node.js executes them, including
-TypeScript syntax that requires JavaScript code generation such as enums, runtime
-namespaces, and parameter properties. JSX compiler options are read from the nearest
-`tsconfig.json` for each loaded file.
+`node-tsx` transforms supported source files before Node.js executes them, including TypeScript syntax that requires JavaScript code generation such as enums, runtime namespaces, and parameter properties. JSX compiler options are read from the nearest `tsconfig.json` for each loaded file.
 
-The loader does not type check, change Node.js module resolution, apply TypeScript
-path aliases, or downlevel JavaScript syntax for older runtimes.
+The loader does not type check, change Node.js module resolution, apply TypeScript path aliases, or downlevel JavaScript syntax for older runtimes.
 
 ## Installation
 
@@ -47,8 +43,7 @@ Since import resolution still follows Node.js, configure type checking to match
 - [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig/#verbatimModuleSyntax) requires type-only imports and exports to be marked so runtime imports are unambiguous.
 - [`rewriteRelativeImportExtensions`](https://www.typescriptlang.org/tsconfig/#rewriteRelativeImportExtensions) preserves a `tsc` emit path by rewriting relative `.ts` and `.tsx` imports to JavaScript extensions.
 
-Do not enable `erasableSyntaxOnly` if you want TypeScript to accept the same
-transform-only syntax that `node-tsx` can execute.
+Do not enable `erasableSyntaxOnly` if you want TypeScript to accept the same transform-only syntax that `node-tsx` can execute.
 
 ### Programmatic usage
 

package/src/route-pattern/README.md

@@ -55,15 +55,13 @@ createHref('http(s)://:region.cdn.com/assets/*file.:ext', {
 
 ## API at a glance
 
-**remix/route-pattern** - Parse and stringify patterns.
-
-**remix/route-pattern/href** - Generate hrefs for patterns with type safe params.
-
-**remix/route-pattern/match** - Match against one pattern with type inference for params. Or match against many patterns with deterministic ranking and attached data.
-
-**remix/route-pattern/join** - Combine two patterns into one. Override protocol, hostname, port. Join pathnames. Merge search constraints.
-
-**remix/route-pattern/specificity** - Rank matches by [specificity](#ranking-matches-by-specificity).
+| Import                            | Description                                                                                                                            |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `remix/route-pattern`             | Parse and stringify patterns.                                                                                                          |
+| `remix/route-pattern/href`        | Generate hrefs for patterns with type safe params.                                                                                     |
+| `remix/route-pattern/match`       | Match against one pattern with type inference for params, or match against many patterns with deterministic ranking and attached data. |
+| `remix/route-pattern/join`        | Combine two patterns into one. Override protocol, hostname, port. Join pathnames. Merge search constraints.                            |
+| `remix/route-pattern/specificity` | Rank matches by [specificity](#ranking-matches-by-specificity).                                                                        |
 
 For in-depth reference, visit the [`route-pattern` API docs](https://api.remix.run/api/remix/route-pattern)
 
@@ -113,6 +111,15 @@ While variables, wilcards, and optionals are most prevalent in pathnames, you ca
 '(:locale.)example.com/docs(/:section)' // matches en.example.com/docs, en.example.com/docs/guides
 ```
 
+**Escape characters** with `\`:
+
+```ts
+'time/12\\:30' // matches /time/12:30
+'calculator/2\\*3' // matches /calculator/2*3
+'wiki/Mercury_\\(planet\\)' // matches /wiki/Mercury_(planet)
+'wiki/AC\\/DC' // matches /wiki/AC%2FDC
+```
+
 ### Search
 
 **Search constraints** narrow matches using `?key` or `?key=value`:
@@ -175,8 +182,7 @@ When multiple patterns match the same URL, `route-pattern` chooses the most spec
 
 This is the same ranking used by `createMultiMatcher`.
 
-For advanced use cases, `/specificity` provides comparison utilities: `lessThan`, `greaterThan`, `equal`, `descending`, `ascending`, `compare`.
-For example:
+For advanced use cases, `/specificity` provides comparison utilities: `lessThan`, `greaterThan`, `equal`, `descending`, `ascending`, `compare`. For example:
 
 ```ts
 import { createMultiMatcher } from 'remix/route-pattern/match'
@@ -195,8 +201,7 @@ matches.sort(descending).map((match) => match.pattern.toString())
 
 ## Generate hrefs
 
-`createHref` turns a pattern and params into a URL string.
-Required variables and wildcards must be provided, while params inside optional groups may be omitted.
+`createHref` turns a pattern and params into a URL string. Required variables and wildcards must be provided, while params inside optional groups may be omitted.
 
 ```ts
 import { createHref } from 'remix/route-pattern/href'

package/src/session-storage-redis/README.md

@@ -1,7 +1,6 @@
 # session-storage-redis
 
-Redis-backed session storage for [`remix/session`](https://github.com/remix-run/remix/tree/main/packages/session).
-Use this package when app servers need to share session state through Redis.
+Redis-backed session storage for [`remix/session`](https://github.com/remix-run/remix/tree/main/packages/session). Use this package when app servers need to share session state through Redis.
 
 ## Installation
 

package/src/test/README.md

@@ -9,6 +9,7 @@ A test framework for JavaScript and TypeScript projects.
 - Playwright E2E testing via `t.serve`
 - In-browser component testing (pair with `render` from `remix/ui/test`)
 - Mock functions and method spies via `t.mock.fn` / `t.mock.method`
+- Per-test and hook timeouts with `t.signal` abort support
 - Unified code coverage reporting across unit and E2E tests
 - Watch mode
 - Config file support (`remix-test.config.ts`)
@@ -193,6 +194,11 @@ describe('My Test Suite', () => {
   afterEach(() => {})
 
   it('tests something', () => {})
+  it('skips with a reason', { skip: 'requires API credentials' }, () => {})
+  it('tracks planned work', { todo: 'add retry coverage' }, () => {})
+  it('fails if it takes too long', { timeout: 5_000 }, async (t) => {
+    await fetchSomething({ signal: t.signal })
+  })
   it('tests something else', () => {})
 })
 ```
@@ -209,8 +215,7 @@ suite('My Test Suite', () => {
 
 ### Programmatic runner
 
-`remix/test/cli` exports `runRemixTest()` for tools that want to run the test runner without
-exiting the current process:
+`remix/test/cli` exports `runRemixTest()` for tools that want to run the test runner without exiting the current process:
 
 ```ts
 import { runRemixTest } from 'remix/test/cli'
@@ -221,9 +226,7 @@ let exitCode = await runRemixTest({
 })
 ```
 
-`runRemixTest()` returns the runner exit code. The `remix test` bin wrapper calls
-`process.exit()` with that code when the run finishes so open workers, browsers, or project handles
-cannot keep the CLI alive.
+`runRemixTest()` returns the runner exit code. The `remix test` bin wrapper calls `process.exit()` with that code when the run finishes so open workers, browsers, or project handles cannot keep the CLI alive.
 
 ### Test Context
 
@@ -232,6 +235,9 @@ Each test callback receives a `TestContext` (`t`) as its first argument with hel
 ```ts
 // from 'remix/test'
 interface TestContext {
+  // Aborts when the test times out or when the user-provided test signal aborts
+  signal: AbortSignal
+
   // Register a cleanup function to run after the test completes
   after(fn: () => void): void
 
@@ -287,6 +293,24 @@ it('cleanup', (t) => {
 })
 ```
 
+#### Timeouts and Signals
+
+Pass `{ timeout: ms }` to `it()` or after any lifecycle hook callback to fail that work if it takes too long. Timed-out tests abort `t.signal`, so async code that accepts an `AbortSignal` can cancel promptly.
+
+```ts
+it('loads data', { timeout: 5_000 }, async (t) => {
+  let response = await fetch('/api/data', { signal: t.signal })
+  assert.equal(response.status, 200)
+})
+
+beforeEach(
+  async () => {
+    await resetDatabase()
+  },
+  { timeout: 1_000 },
+)
+```
+
 #### Fake Timers
 
 `t.useFakeTimers()` replaces the global timer functions (`setTimeout`, `setInterval`, etc.) with controllable fakes that are automatically restored after the test. It works in any test environment — server unit tests, browser tests, or E2E setup code.

package/src/ui/anchor/README.md

@@ -1,6 +1,6 @@
 # anchor
 
-`anchor` positions a floating element against an anchor element and keeps it constrained to the viewport. Use it for custom floating surfaces that need placement, flipping, offsets, and optional relative alignment.
+`anchor` positions a floating element against an anchor element or viewport coordinates and keeps it constrained to the viewport. Use it for custom floating surfaces that need placement, flipping, offsets, and optional relative alignment.
 
 ## Usage
 
@@ -49,11 +49,19 @@ popover.addEventListener('beforetoggle', (event) => {
 })
 ```
 
+Anchor to coordinates when the surface should open at a pointer location.
+
+```tsx
+let cleanup = anchor(popover, { x: event.clientX, y: event.clientY }, { placement: 'bottom-start' })
+```
+
 ## `anchor.*`
 
-- `anchor(floatingElement, anchorElement, options)`: positions `floatingElement` against `anchorElement`, starts animation-frame polling for geometry changes, and returns a cleanup function.
+- `anchor(floatingElement, anchorTarget, options)`: positions `floatingElement` against an element or coordinate target, starts animation-frame polling for geometry changes, and returns a cleanup function.
 - `AnchorOptions`: placement, inset, relative alignment, and offset options.
+- `AnchorPoint`: viewport coordinate target with `x`, `y`, and optional `width`/`height`.
 - `AnchorPlacement`: exported placement names for the main sides and top/bottom start/end alignment.
+- `AnchorTarget`: an `HTMLElement` or `AnchorPoint`.
 
 ## Placements
 
@@ -149,5 +157,5 @@ anchor(listbox, trigger, {
 - Oversized inset surfaces with `relativeTo` preserve alignment by scrolling the nearest scrollable descendant when possible.
 - `offset`, `offsetX`, and `offsetY` may be numbers or functions that receive the floating element.
 - `relativeTo` lets a surface align to an inner element, which is useful for selected options inside popovers.
-- `anchor` polls on animation frames for anchor or floating geometry changes and repositions when either changes.
+- `anchor` polls on animation frames for anchor target or floating geometry changes and repositions when either changes.
 - The returned cleanup function cancels animation-frame polling.