remix 3.0.0-beta.5 → 3.0.0-beta.6

package/src/route-pattern/README.md

@@ -8,7 +8,7 @@ Type-safe URL matching and href generation for JavaScript. `route-pattern` suppo
 - **Expressive** - Variables, wildcards, optionals, and search constraints
 - **Full URL support** - Match protocol, hostname, port, pathname, and search
 - **Simple & deterministic ranking** - Predictable left-to-right priority for static, variable, and wildcard patterns
-- **Fast** - Trie-based matching for scalable performance
+- **Fast** - Indexed, bounded-state matching without variant expansion or regex backtracking
 - **Modular** - Import only the features you need to for smaller bundles
 - **Runtime agnostic** - Works across Node.js, Bun, Deno, Cloudflare Workers, and browsers
 
@@ -84,9 +84,14 @@ Protocol must be `http`, `https`, or `http(s)`:
 
 ```ts
 'users/:id' // matches /users/123
-'blog/:year-:month-:day/:slug' // matches /blog/2024-01-15/hello
+'blog/:date/:slug' // matches /blog/2024-01-15/hello
+'files/:name.:ext' // matches /files/readme.md
 ```
 
+Pathname variables possessively capture the largest non-empty run up to `/` or `.`. Hyphens are data, so UUIDs and slugs remain intact. A variable may have static text before it, but every path through following optionals must reach `/`, `.`, a wildcard, or the end of the hostname or pathname. Capture an inseparable value such as a date with one variable instead of `:year-:month-:day`.
+
+Raw `/` and `.` are structural delimiters. Their percent-encoded forms remain data and are decoded in the resulting param. Static pattern text may use either decoded text or percent encoding, so `/café` and `/caf%C3%A9` match the same pathname text.
+
 **Wildcards** match multi-segment paths using `*name`:
 
 ```ts
@@ -95,6 +100,8 @@ Protocol must be `http`, `https`, or `http(s)`:
 'files/*' // matches any path under /files, but doesn't capture the wildcard value
 ```
 
+Patterns may contain any number of wildcards when static text or a delimiter separates them. Adjacent wildcards such as `*left*right` are rejected because their capture boundary is ambiguous.
+
 **Optionals** make parts optional using `()`:
 
 ```ts
@@ -104,7 +111,9 @@ Protocol must be `http`, `https`, or `http(s)`:
 'api(/v:major(.:minor))' // matches /api, /api/v2, /api/v2.1
 ```
 
-While variables, wilcards, and optionals are most prevalent in pathnames, you can also use them in hostnames:
+Optionals compile as state branches rather than concrete variants, so independent and nested optionals do not cause exponential matcher construction. Empty optionals and adjacent optional branches that give the same URL different capture schemas are rejected.
+
+While variables, wildcards, and optionals are most prevalent in pathnames, you can also use them in hostnames:
 
 ```ts
 ':tenant.example.com/dashboard' // matches acme.example.com/dashboard
@@ -113,6 +122,19 @@ 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
 ```
 
+Capture names may repeat. `params` uses the last participating capture in pattern order, while `paramsMeta` retains every participating capture:
+
+```ts
+let matcher = createMatcher('/:id/:id')
+let match = matcher.match('https://example.com/first/second')
+
+match?.params
+// { id: 'second' }
+
+match?.paramsMeta.pathname.map(({ name, value }) => ({ name, value }))
+// [{ name: 'id', value: 'first' }, { name: 'id', value: 'second' }]
+```
+
 **Escape characters** with `\`:
 
 ```ts
@@ -151,7 +173,21 @@ docsMatcher.match(url)?.params
 // Type safe params     ^? { tenant: string | undefined, path: string, ext: string } | undefined
 ```
 
-Matchers accept absolute URL strings or `URL` objects. Relative strings such as `/blog/v3` are not accepted because matching uses the platform `URL` parser; wrap relative paths with a known origin before matching them.
+Matchers accept absolute URL strings or `URL` objects. To match a relative URL reference, pass an absolute `baseURL`; the input is resolved with the same semantics as `new URL(input, baseURL)`, and the resolved URL is returned on the match.
+
+```ts
+let match = blogMatcher.match('../blog/v3', {
+  baseURL: 'https://example.com/admin/settings',
+})
+
+match?.params
+// { slug: 'v3' }
+
+match?.url.href
+// 'https://example.com/blog/v3'
+```
+
+This works for root-relative, path-relative, query-relative, and network-path references. Without `baseURL`, string inputs must still be absolute.
 
 ### Match against multiple patterns
 
@@ -195,6 +231,14 @@ matcher.match('https://example.com/docs/Intro')?.params
 // { slug: 'Intro' }
 ```
 
+Matchers limit individual pattern size, total matcher size, and the work performed by one match. Pattern and matcher sizes are measured in UTF-8 bytes. Direct package consumers may lower or raise individual limits. Exceeding one throws `MatcherResourceError` with structured `details` instead of silently abandoning matching:
+
+```ts
+let matcher = createMultiMatcher({
+  limits: { maxPatternSize: 4096, maxMatchWork: 100_000 },
+})
+```
+
 ### Ranking matches by specificity
 
 When multiple patterns match the same URL, `route-pattern` chooses the most specific match deterministically. Matches are ranked left-to-right, character-by-character:
@@ -216,12 +260,12 @@ import { descending } from 'remix/route-pattern/specificity'
 let matcher = createMultiMatcher()
 matcher.add('files/*path', null)
 matcher.add('files/:name', null)
-matcher.add('files/readme.md', null)
+matcher.add('files/readme', null)
 
-let matches = matcher.matchAll('https://example.com/files/readme.md')
+let matches = matcher.matchAll('https://example.com/files/readme')
 
 matches.sort(descending).map((match) => match.pattern.toString())
-// ['/files/readme.md', '/files/:name', '/files/*path']
+// ['/files/readme', '/files/:name', '/files/*path']
 ```
 
 ## Generate hrefs
@@ -247,8 +291,41 @@ createHref('http(s)://:region.cdn.com/assets/*file.:ext', {
 })
 // 'https://us-west.cdn.com/assets/images/logo.png'
 
-createHref('blog/:slug?ref=docs', { slug: 'v3' }, { utm_source: 'newsletter' })
+createHref(
+  'blog/:slug?ref=docs',
+  { slug: 'v3' },
+  {
+    searchParams: { utm_source: 'newsletter' },
+  },
+)
 // '/blog/v3?utm_source=newsletter&ref=docs'
+
+createHref('users/:id', { id: 'a.b' })
+// '/users/a%2Eb' (the encoded dot remains variable data when matched)
+```
+
+Pass `baseURL` to generate a path-relative reference to a same-origin route. Patterns with a different origin remain absolute.
+
+```ts
+let baseURL = new URL('https://example.com/admin/settings')
+
+createHref('users/:id', { id: '123' }, { baseURL })
+// '../users/123'
+
+createHref('https://cdn.example.com/assets/*path', { path: 'logo.svg' }, { baseURL })
+// 'https://cdn.example.com/assets/logo.svg'
+```
+
+The `searchParams` option accepts a plain object or `URLSearchParams`. Use `URLSearchParams` when duplicate keys or their order matter:
+
+```ts
+let searchParams = new URLSearchParams([
+  ['tag', 'featured'],
+  ['tag', 'popular'],
+])
+
+createHref('search', undefined, { searchParams })
+// '/search?tag=featured&tag=popular'
 ```
 
 `createHref()` throws `CreateHrefError` when it cannot safely generate an href. The error exposes stable structured details on `error.details`; the string message is for humans.
@@ -300,7 +377,13 @@ The public support types are:
 - `RoutePatternCapture` from `remix/route-pattern`
 - `RoutePatternJSON` from `remix/route-pattern`
 - `CreateHrefErrorDetails` from `remix/route-pattern/href`
+- `CreateHrefOptions` and `CreateHrefSearchParams` from `remix/route-pattern/href`
 - `MatchParamMeta` from `remix/route-pattern/match`
+- `MatchOptions` from `remix/route-pattern/match`
+- `MatcherLimits` from `remix/route-pattern/match`
+- `MatcherResourceError` and `MatcherResourceErrorDetails` from `remix/route-pattern/match`
+
+Literal patterns are validated and infer named params until the type-level parser reaches its 64-step complexity budget. Larger runtime-valid patterns remain accepted and fall back to safe general pattern types instead of risking a TypeScript excessive-instantiation error.
 
 ## Combine patterns
 

package/src/session-middleware/README.md

@@ -24,7 +24,6 @@ import { session } from 'remix/middleware/session'
 
 let sessionCookie = createCookie('__session', {
   secrets: ['s3cr3t'], // session cookies must be signed!
-  httpOnly: true,
   secure: true,
   sameSite: 'lax',
 })
@@ -50,21 +49,24 @@ The middleware:
 Use `context.session` (or `context.get(Session)`) for normal session reads and writes.
 
 Note: The session cookie must be signed for security. This prevents tampering with the session data on the client.
+Session cookies are HTTP-only by default.
 
 ### Login/Logout Flow
 
 A basic login/logout flow could look like this:
 
 ```ts
-import * as res from 'remix/router/response-helpers'
+import { html } from 'remix/html-template'
+import { createHtmlResponse } from 'remix/response/html'
+import { redirect } from 'remix/response/redirect'
 
 router.get('/login', ({ session }) => {
   let error = session.get('error')
-  return res.html(`
+  return createHtmlResponse(html`
     <html>
       <body>
         <h1>Login</h1>
-        ${typeof error === 'string' ? <div class="error">${error}</div> : null}
+        ${typeof error === 'string' ? html`<div class="error">${error}</div>` : null}
         <form method="POST" action="/login">
           <input type="text" name="username" placeholder="Username" />
           <input type="password" name="password" placeholder="Password" />
@@ -83,18 +85,18 @@ router.post('/login', ({ get, session }) => {
   let user = authenticateUser(username, password)
   if (!user) {
     session.flash('error', 'Invalid username or password')
-    return res.redirect('/login')
+    return redirect('/login')
   }
 
   session.regenerateId()
   session.set('userId', user.id)
 
-  return res.redirect('/dashboard')
+  return redirect('/dashboard')
 })
 
 router.post('/logout', ({ session }) => {
   session.destroy()
-  return res.redirect('/')
+  return redirect('/')
 })
 ```
 

package/src/test/README.md

@@ -12,7 +12,7 @@ A test framework for JavaScript and TypeScript projects.
 - 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`)
+- Static CLI configuration through `remix.json`
 
 ## Installation
 
@@ -42,127 +42,145 @@ Run tests with the CLI:
 remix test
 ```
 
-By default, `remix test` discovers all files matching `**/*.test{,.e2e}.{ts,tsx}`. Pass one or more globs as positional arguments to override:
+By default, `remix test` discovers all files matching `**/*.test{,.browser,.e2e}.{ts,tsx}`. Pass one or more globs as positional arguments to override:
 
 ```sh
 remix test "src/**/*.test.ts"
 remix test "src/**/*.test.ts" "tests/**/*.test.tsx"
 ```
 
-Or, you may control via the `glob.test` config field/CLI arg. Each `glob.*` field accepts a single string or an array of patterns, and `--glob.*` flags can be repeated on the CLI.
+You may also repeat the `--glob.*` flags. Positional globs take precedence over `--glob.test`.
 
 ### Config File
 
-Create a `remix-test.config.ts` (or `.js`) file at the root of your project (shown with default values):
+Create an optional `remix.json` at the root of your project. It is parsed as JSONC, so comments and
+trailing commas are allowed:
+
+```jsonc
+{
+  "$schema": "https://remix.run/schemas/remix.json",
+  "test": {
+    "files": ["**/*.test{,.browser,.e2e}.{ts,tsx}"],
+    "browserFiles": ["**/*.test.browser.{ts,tsx}"],
+    "e2eFiles": ["**/*.test.e2e.{ts,tsx}"],
+    "exclude": ["node_modules/**", "dist/**"],
+    "type": ["server", "browser", "e2e"],
+    "only": ["/checkout/i"],
+
+    "concurrency": 2,
+    "pool": "forks",
+    "setup": "./test/setup.ts",
+    "watch": false,
+
+    "playwright": {
+      "echo": false,
+      "open": false,
+      "configFile": "./playwright.config.ts",
+      "projects": ["chromium", "firefox"],
+    },
 
-```ts
-import type { RemixTestConfig } from 'remix/test'
-
-export default {
-  // Browser options for E2E tests
-  browser: {
-    // Echo browser console output to the terminal
-    echo: false,
-    // Open browser (via playwright `headless:false`) and keep it open after tests
-    // complete (useful for debugging)
-    open: false,
+    "reporter": "spec",
+    "quiet": false,
+
+    "coverage": {
+      "enabled": true,
+      "dir": ".coverage",
+      "include": ["src/**"],
+      "exclude": ["src/**/*.test.ts"],
+      "statements": 80,
+      "lines": 80,
+      "branches": 80,
+      "functions": 80,
+    },
   },
+}
+```
 
-  // Max number of concurrent test workers (default `os.availableParallelism()`)
-  concurrency: 2,
-
-  // Pool for server and E2E test files ("forks", "threads")
-  pool: 'forks',
-
-  // Code coverage options
-  coverage: {
-    // Enable coverage reporting
-    enabled: true,
-    // Output directory (default: ".coverage")
-    dir: '.coverage',
-    // Glob pattern(s) to include/exclude
-    include: 'src/**',
-    exclude: 'src/**/*.test.ts',
-    // Minimum thresholds (%)
-    statements: 80,
-    lines: 80,
-    branches: 80,
-    functions: 80,
-  },
+Every field is optional. Relative paths and globs resolve from the directory containing the config
+file. Explicit CLI flags and positional globs take precedence. Repeatable flags replace configured
+arrays, and nested Playwright and coverage values merge by field.
 
-  // Glob pattern(s) identifying test files
-  glob: {
-    // All test files (default: "**/*.test{,.browser,.e2e}.{ts,tsx}").
-    test: '**/*.test{,.browser,.e2e}.ts',
-    // Browser test files (default: "**/*.test.browser.{ts,tsx}")
-    browser: '**/*.test.browser.ts',
-    // E2E test files (default: "**/*.test.e2e.{ts,tsx}")
-    e2e: '**/*.test.e2e.ts',
-  },
+`remix-test.config.ts` and `remix-test.config.js` are no longer discovered. Move their static values
+under `remix.json#test`. Move inline Playwright configuration into `playwright.config.ts` and point
+`playwright.configFile` at it. Use slash-delimited strings for regular expressions, and use CLI flags
+or package scripts for environment-specific overrides.
 
-  // Playwright configuration for E2E tests, or string path to an existing
-  // config file on disk
-  playwrightConfig: {
-    projects: [
-      { name: 'chromium', use: { browserName: 'chromium' } },
-      { name: 'firefox', use: { browserName: 'firefox' } },
-    ],
-    use: {
-      navigationTimeout: 5_000,
-      actionTimeout: 5_000,
-    },
-  },
+### CLI Options
 
-  // Playwright project(s) to run E2E tests for
-  project: 'chromium',
+Use the global `--config` flag to select another Remix config file. The flag path resolves from the
+current working directory:
 
-  // Test reporter ("spec", "files", "tap", "dot")
-  reporter: 'spec',
+```sh
+remix test --config ./config/remix.ci.json
+```
 
-  // Path to a setup module (see Setup section below)
-  setup: './test/setup.ts',
+You may specify any test setting as a CLI flag. Boolean settings have negative forms so configured
+`true` values can be disabled explicitly:
+
+| Flag                        | Short |
+| --------------------------- | ----- |
+| `--browser.echo`            |       |
+| `--no-browser.echo`         |       |
+| `--browser.open`            |       |
+| `--no-browser.open`         |       |
+| `--concurrency <n>`         | `-c`  |
+| `--coverage`                |       |
+| `--no-coverage`             |       |
+| `--coverage.dir <path>`     |       |
+| `--coverage.include`        |       |
+| `--coverage.exclude`        |       |
+| `--coverage.statements`     |       |
+| `--coverage.lines`          |       |
+| `--coverage.branches`       |       |
+| `--coverage.functions`      |       |
+| `--glob.test`               |       |
+| `--glob.browser`            |       |
+| `--glob.e2e`                |       |
+| `--glob.exclude`            |       |
+| `--playwrightConfig <path>` |       |
+| `--only <pattern>`          |       |
+| `--pool <forks\|threads>`   |       |
+| `--project <name>`          | `-p`  |
+| `--quiet`                   | `-q`  |
+| `--no-quiet`                |       |
+| `--reporter <name>`         | `-r`  |
+| `--setup <path>`            | `-s`  |
+| `--type <name>`             | `-t`  |
+| `--watch`                   | `-w`  |
+| `--no-watch`                |       |
+
+The standalone `remix-test` executable is no longer installed. Update scripts to use the main Remix CLI:
+
+```diff
+- "test": "remix-test --type server"
++ "test": "remix test --type server"
+```
 
-  // Test type(s) to run ("server", "browser", "e2e")
-  type: ['server', 'browser', 'e2e'],
+### Focusing Tests
 
-  // Watch for file changes and re-run
-  watch: false,
-} satisfies RemixTestConfig
-```
+Use `.only` to focus a suite or test while developing:
 
-### CLI Options
+```ts
+describe.only('Cart routes', () => {
+  it('loads cart items', () => {})
+})
 
-You can point to a different config file location with the `--config` flag:
+describe('Checkout routes', () => {
+  it.only('redirects anonymous users', () => {})
+})
+```
+
+Use `--only <pattern>` to focus tests from the CLI without editing source. Plain patterns are case-insensitive JavaScript regular expressions matched against suite names and full test names:
 
 ```sh
-remix test --config ./tests/config.ts
+remix test --only 'Cart routes'
+remix test --only 'Checkout routes > redirects anonymous users'
+remix test --only '/anonymous users$/'
 ```
 
-You may also specify any config field as a CLI flag which will take precedence over config file values:
-
-| Flag                        | Short     |
-| --------------------------- | --------- | --- |
-| `--browser.echo`            |           |
-| `--browser.open`            |           |
-| `--concurrency <n>`         | `-c`      |
-| `--coverage`                |           |
-| `--coverage.dir <path>`     |           |
-| `--coverage.include`        |           |
-| `--coverage.exclude`        |           |
-| `--coverage.statements`     |           |
-| `--coverage.lines`          |           |
-| `--coverage.branches`       |           |
-| `--coverage.functions`      |           |
-| `--glob.test`               |           |
-| `--glob.browser`            |           |
-| `--glob.e2e`                |           |
-| `--playwrightConfig <path>` |           |
-| `--pool <forks              | threads>` |     |
-| `--project <name>`          | `-p`      |
-| `--reporter <name>`         | `-r`      |
-| `--setup <path>`            | `-s`      |
-| `--type <name>`             | `-t`      |
-| `--watch`                   | `-w`      |
+Slash-delimited CLI and `remix.json` patterns preserve their flags, so `/pattern/` is case-sensitive and `/pattern/i` is case-insensitive. Plain string patterns are case-insensitive. Programmatic callers may also pass `RegExp` values.
+
+Full test names join nested `describe` names and the test name with `>`. For example, `describe('Cart routes', () => describe('loader', () => it('loads cart items', ...)))` has the full test name `Cart routes > loader > loads cart items`.
 
 ### Setup
 
@@ -221,12 +239,19 @@ suite('My Test Suite', () => {
 import { runRemixTest } from 'remix/test/cli'
 
 let exitCode = await runRemixTest({
-  argv: ['--type', 'server'],
+  concurrency: 1,
   cwd: process.cwd(),
+  glob: { test: 'src/**/*.test.ts' },
+  type: ['server'],
 })
 ```
 
-`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.
+The programmatic runner accepts structured options only; it does not discover or load configuration
+files. Programmatic callers may pass richer values such as an inline Playwright config or `RegExp`
+test-name filters. The main Remix CLI owns `remix.json` loading and passes the resolved options to the
+runner.
+
+`runRemixTest()` does not read `process.argv` or terminate the process; it returns the runner exit code. The main `remix` executable owns argument parsing and passes the final code to `process.exit()` so open workers, browsers, or project handles cannot keep the CLI alive. `@remix-run/test` does not install a standalone executable.
 
 ### Test Context
 
@@ -426,28 +451,49 @@ describe('checkout', () => {
 })
 ```
 
-Configure Playwright (browsers, timeouts, viewport, etc.) via `playwrightConfig` in your config file:
+Configure Playwright's browsers, timeouts, viewport, and other executable settings in
+`playwright.config.ts`:
 
 ```ts
-export default {
-  playwrightConfig: {
-    projects: [
-      { name: 'chromium', use: { browserName: 'chromium' } },
-      { name: 'firefox', use: { browserName: 'firefox' } },
-      { name: 'webkit', use: { browserName: 'webkit' } },
-    ],
-    use: {
-      navigationTimeout: 5_000,
-      actionTimeout: 5_000,
-    },
+import { defineConfig } from 'playwright/test'
+
+export default defineConfig({
+  projects: [
+    { name: 'chromium', use: { browserName: 'chromium' } },
+    { name: 'firefox', use: { browserName: 'firefox' } },
+    { name: 'webkit', use: { browserName: 'webkit' } },
+  ],
+  use: {
+    navigationTimeout: 5_000,
+    actionTimeout: 5_000,
   },
+})
+```
 
-  // Or, point to an existing playwright config file
-  // playwrightConfig: './playwright.config.ts'
-} satisfies RemixTestConfig
+Reference it from `remix.json` when it is not at the default location:
+
+```jsonc
+{
+  "test": {
+    "playwright": {
+      "configFile": "./playwright.config.ts",
+    },
+  },
+}
 ```
 
-Set `browser.open: true` to keep the browser open after tests finish — useful for debugging failures.
+Set `test.playwright.open` to `true`, or pass `--browser.open`, to keep the browser open after tests
+finish—useful for debugging failures.
+
+## Related Packages
+
+- [`assert`](https://github.com/remix-run/remix/tree/main/packages/assert) provides assertions that work in server and browser tests.
+- [`ui`](https://github.com/remix-run/remix/tree/main/packages/ui) provides the `remix/ui/test` browser rendering utilities.
+
+## Related Work
+
+- [Playwright](https://playwright.dev) provides the browser automation used by browser and E2E tests.
+- [Node.js test runner](https://nodejs.org/api/test.html) provides prior art for the test framework API and reporting model.
 
 ## License
 

package/src/ui/README.md

@@ -4,7 +4,7 @@ Runtime UI primitives for Remix apps, including the component runtime, server re
 
 ## Features
 
-- Component runtime APIs for rendering, hydration, frame navigation, and JSX
+- Component runtime APIs for rendering, hydration, link and form frame navigation, and JSX
 - Server rendering APIs for streaming Remix UI trees and frames
 - `mix` composition with event, ref, CSS, and animation helpers
 - Headless behavior primitives for controls such as menus, listboxes, popovers, selects, and comboboxes
@@ -79,6 +79,79 @@ function Actions() {
 }
 ```
 
+## Frame Navigation
+
+Configure `resolveFrame` once to progressively enhance same-origin links and forms. The resolver owns the fetch request and receives native submission metadata for non-GET forms:
+
+```tsx
+import type { ResolveFrameOptions } from 'remix/ui'
+import { run } from 'remix/ui'
+
+let app = run({
+  async loadModule(moduleUrl, exportName) {
+    let mod = await import(moduleUrl)
+    return mod[exportName]
+  },
+  async resolveFrame(src, options) {
+    return fetch(src, {
+      headers: { Accept: 'text/html', 'X-Remix-Frame': 'true' },
+      method: options?.method,
+      body: getRequestBody(options),
+      signal: options?.signal,
+    })
+  },
+})
+
+function getRequestBody(options?: ResolveFrameOptions): BodyInit | undefined {
+  let formData = options?.formData
+  if (!formData) return
+  if (options.encType !== 'application/x-www-form-urlencoded') return formData
+
+  let body = new URLSearchParams()
+  for (let [name, value] of formData) {
+    body.append(name, typeof value === 'string' ? value : value.name)
+  }
+  return body
+}
+
+await app.ready()
+```
+
+Forms remain ordinary HTML forms before the runtime starts. Add `rmx-target` to reload a named frame, or `rmx-document` to require a full-document submission:
+
+```tsx
+import { Frame } from 'remix/ui'
+
+function AccountPage() {
+  return () => (
+    <>
+      <Frame name="account" src="/account/edit" />
+      <form action="/account/edit" method="post" rmx-target="account">
+        <label for="display-name">Display name</label>
+        <input id="display-name" name="displayName" required />
+        <button type="submit">Save</button>
+      </form>
+    </>
+  )
+}
+```
+
+Native constraint validation and submitter overrides still apply. GET form values arrive in `src`; non-GET forms provide `formData`, `method`, and `encType` to the resolver. See [Frames](https://github.com/remix-run/remix/blob/main/packages/ui/docs/frames.md#form-navigation) for targeting, history behavior, request encoding, opt-outs, and server response guidance.
+
+Use `rmx-history="push|replace"` on an enhanced anchor or form to control how the navigation updates history. This can override the automatic replacement used for non-GET form submissions to the current URL.
+
+## Preserving Client-Owned DOM
+
+Use `rmx-preserve-dom` on the smallest element whose live DOM should belong to client code after initial render, such as a custom element or third-party widget:
+
+```tsx
+<pagefind-ui data-key="search" rmx-preserve-dom>
+  <button type="button">Search</button>
+</pagefind-ui>
+```
+
+Remix UI still renders the element's children during SSR and still hydrates any initial client entries inside it. On later frame reloads, matched `rmx-preserve-dom` elements keep their current attributes and children instead of accepting incoming DOM updates. See [Preserving client-owned DOM](https://github.com/remix-run/remix/blob/main/packages/ui/docs/frames.md#preserving-client-owned-dom) for guidance and caveats.
+
 ## Cascade Layers
 
 Remix UI emits generated `css(...)` rules under the `rmx` cascade layer. Unlayered CSS outranks layered CSS, so use explicit layer order when mixing Remix UI with global styles.

package/src/ui/dev/refresh.ts

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