remix 3.0.0-rc.1 → 3.0.0-rc.2

package/dist/multiple-import-maps-polyfill.d.ts

@@ -0,0 +1,2 @@
+export * from '@remix-run/multiple-import-maps-polyfill';
+//# sourceMappingURL=multiple-import-maps-polyfill.d.ts.map

package/dist/multiple-import-maps-polyfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiple-import-maps-polyfill.d.ts","sourceRoot":"","sources":["../src/multiple-import-maps-polyfill.ts"],"names":[],"mappings":"AACA,cAAc,0CAA0C,CAAA"}

package/dist/multiple-import-maps-polyfill.js

@@ -0,0 +1,2 @@
+// IMPORTANT: This file is auto-generated, please do not edit manually.
+export * from '@remix-run/multiple-import-maps-polyfill';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remix",
-  "version": "3.0.0-rc.1",
+  "version": "3.0.0-rc.2",
   "description": "The Remix web framework",
   "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
@@ -261,6 +261,10 @@
       "types": "./dist/multipart-parser/node.d.ts",
       "default": "./dist/multipart-parser/node.js"
     },
+    "./multiple-import-maps-polyfill": {
+      "types": "./dist/multiple-import-maps-polyfill.d.ts",
+      "default": "./dist/multiple-import-maps-polyfill.js"
+    },
     "./node-fetch-server": {
       "types": "./dist/node-fetch-server.d.ts",
       "default": "./dist/node-fetch-server.js"
@@ -512,53 +516,54 @@
     "typescript": "^7.0.2"
   },
   "dependencies": {
-    "@remix-run/assets": "^0.6.0",
-    "@remix-run/auth": "^0.3.0",
-    "@remix-run/async-context-middleware": "^0.3.5",
-    "@remix-run/auth-middleware": "^0.2.5",
-    "@remix-run/ui": "^0.8.0",
-    "@remix-run/compression-middleware": "^0.1.13",
-    "@remix-run/cop-middleware": "^0.1.8",
-    "@remix-run/cors-middleware": "^0.1.8",
-    "@remix-run/csrf-middleware": "^0.1.8",
+    "@remix-run/auth": "^0.3.1",
+    "@remix-run/auth-middleware": "^0.2.6",
+    "@remix-run/ui": "^0.9.0",
+    "@remix-run/compression-middleware": "^0.1.14",
+    "@remix-run/assets": "^0.7.0",
+    "@remix-run/async-context-middleware": "^0.3.6",
+    "@remix-run/cors-middleware": "^0.1.9",
+    "@remix-run/csrf-middleware": "^0.1.9",
+    "@remix-run/data-table": "^0.5.1",
     "@remix-run/cookie": "^0.6.0",
-    "@remix-run/data-table-postgres": "^0.5.1",
-    "@remix-run/data-schema": "^0.3.0",
-    "@remix-run/data-table": "^0.5.0",
-    "@remix-run/data-table-mysql": "^0.5.1",
+    "@remix-run/data-table-postgres": "^0.5.2",
+    "@remix-run/cop-middleware": "^0.1.9",
+    "@remix-run/data-table-sqlite": "^0.6.2",
     "@remix-run/fetch-proxy": "^0.8.5",
+    "@remix-run/data-schema": "^0.3.0",
+    "@remix-run/fetch-router": "^0.22.0",
     "@remix-run/file-storage": "^0.13.7",
+    "@remix-run/data-table-mysql": "^0.5.2",
     "@remix-run/file-storage-s3": "^0.1.4",
-    "@remix-run/form-data-middleware": "^0.3.5",
-    "@remix-run/form-data-parser": "^0.17.5",
-    "@remix-run/fetch-router": "^0.21.0",
-    "@remix-run/data-table-sqlite": "^0.6.1",
+    "@remix-run/form-data-middleware": "^0.3.6",
     "@remix-run/fs": "^0.4.6",
-    "@remix-run/headers": "^0.21.1",
     "@remix-run/lazy-file": "^5.0.6",
-    "@remix-run/logger-middleware": "^0.3.5",
+    "@remix-run/logger-middleware": "^0.3.6",
+    "@remix-run/form-data-parser": "^0.17.5",
+    "@remix-run/method-override-middleware": "^0.1.14",
+    "@remix-run/headers": "^0.21.1",
     "@remix-run/html-template": "^0.3.1",
-    "@remix-run/method-override-middleware": "^0.1.13",
     "@remix-run/mime": "^0.4.2",
-    "@remix-run/multipart-parser": "^0.16.4",
-    "@remix-run/node-fetch-server": "^0.14.1",
     "@remix-run/node-tsx": "^0.1.1",
+    "@remix-run/multipart-parser": "^0.16.4",
     "@remix-run/response": "^0.3.8",
-    "@remix-run/session-middleware": "^0.4.0",
+    "@remix-run/node-fetch-server": "^0.14.1",
+    "@remix-run/route-pattern": "^0.24.0",
     "@remix-run/session": "^0.4.2",
-    "@remix-run/tar-parser": "^0.7.1",
+    "@remix-run/session-middleware": "^0.4.1",
+    "@remix-run/session-storage-memcache": "^0.1.2",
     "@remix-run/assert": "^0.3.0",
-    "@remix-run/cli": "^0.6.0",
     "@remix-run/session-storage-redis": "^0.1.1",
-    "@remix-run/route-pattern": "^0.24.0",
-    "@remix-run/render-middleware": "^0.2.0",
-    "@remix-run/ui-hmr": "^0.1.0",
-    "@remix-run/node-hmr": "^0.1.0",
-    "@remix-run/spa": "^0.1.0",
-    "@remix-run/static-middleware": "^0.4.14",
+    "@remix-run/test": "^0.6.0",
+    "@remix-run/cli": "^0.7.0",
+    "@remix-run/tar-parser": "^0.7.1",
+    "@remix-run/spa": "^0.1.1",
+    "@remix-run/static-middleware": "^0.4.15",
+    "@remix-run/render-middleware": "^0.3.0",
     "@remix-run/terminal": "^0.1.1",
-    "@remix-run/session-storage-memcache": "^0.1.2",
-    "@remix-run/test": "^0.6.0"
+    "@remix-run/multiple-import-maps-polyfill": "^0.1.0",
+    "@remix-run/ui-hmr": "^0.1.0",
+    "@remix-run/node-hmr": "^0.2.0"
   },
   "bin": {
     "remix": "./dist/cli-entry.js"

package/src/assets/README.md

@@ -10,7 +10,7 @@ Fetch-based server for compiling browser assets on demand.
 - **Preloads** - Generate preload URLs for scripts and styles based on imports
 - **Inspection** - List browser-reachable assets and explain URL-to-file mappings
 - **Caching** - Conservative caching by default with stable URLs, ETags, and revalidation
-- **Optional Fingerprinting** - Source-based fingerprinted URLs for long-lived browser caching
+- **Optional Fingerprinting** - Content-based fingerprinted URLs for long-lived browser caching
 - **Source Maps** - Serve inline or external sourcemaps
 - **Hot Module Reloading** - Handle live code updates in development
 - **Script Loaders** - Post-process compiled JavaScript with Node-compatible loaders
@@ -164,6 +164,8 @@ let assetServer = createAssetServer({
 })
 ```
 
+Package managers that install outside `rootDir`, such as pnpm's global virtual store, are handled without configuration: the asset server reads the store location from the nearest `node_modules/.modules.yaml` and mounts it internally so those package files still resolve to public URLs. A store that a configured mount already covers, such as pnpm's default `node_modules/.pnpm`, is left alone.
+
 ### File watching
 
 The file system is watched by default so source changes are picked up without requiring a server restart.
@@ -212,13 +214,68 @@ let assetServer = createAssetServer({
 })
 ```
 
+## Script Entries
+
+Use `assetServer.getScriptEntry()` to get everything needed to load a script and its dependencies.
+
+```ts
+let { href, importMap, preloads } = await assetServer.getScriptEntry('app/assets/entry.tsx')
+```
+
+This can be used when rendering a document shell:
+
+```tsx
+import type { Handle, RemixNode } from 'remix/ui'
+import { ImportMap } from 'remix/ui/server'
+import { assetServer } from './assets.ts'
+
+let { href, importMap, preloads } = await assetServer.getScriptEntry('app/assets/entry.tsx')
+
+export function Document(handle: Handle<{ children: RemixNode }>) {
+  return () => (
+    <html>
+      <head>
+        {/* ... */}
+        <ImportMap value={importMap} />
+        {preloads.map((preload) => (
+          <link rel="modulepreload" href={preload} />
+        ))}
+        <script type="module" src={href} />
+      </head>
+      <body>{handle.props.children}</body>
+    </html>
+  )
+}
+```
+
+This can also be used for resolved client entries in [`remix/ui`](https://github.com/remix-run/remix/tree/main/packages/ui) when using `import.meta.url` as the client entry ID:
+
+```tsx
+import { renderToStream } from 'remix/ui/server'
+import { assetServer } from './assets.ts'
+
+let stream = renderToStream(<App />, {
+  async resolveClientEntry(entryId, component) {
+    let { href, importMap, preloads } = await assetServer.getScriptEntry(entryId)
+
+    return {
+      href,
+      importMap,
+      preloads,
+      exportName: entryId.split('#')[1] || component.name,
+    }
+  },
+  // ...
+})
+```
+
 ## Hrefs
 
 Use `assetServer.getHref()` when you need the public URL for a served asset. You can provide a root-relative or absolute file path, or a `file://` URL.
 
 ```ts
-let src = await assetServer.getHref('app/actions/public/entry.ts')
-// '/assets/app/actions/public/entry.ts'
+let src = await assetServer.getHref('app/media/public/logo.svg')
+// '/assets/app/media/public/logo.svg'
 ```
 
 ## Inspection
@@ -244,6 +301,16 @@ let src = await assetServer.getHref('app/media/public/image.png', {
 // '/assets/app/media/public/image.png?transform=resize%3A100x100&transform=webp'
 ```
 
+## Import Maps
+
+Scripts retain their imports as authored and rely on import maps for resolution in the browser. `assetServer.getScriptEntry()` returns the import map for a single rendered script entry. Use `assetServer.getImportMap()` directly when you need to generate a combined import map for multiple script roots or other custom graph-level behavior.
+
+```ts
+let importMap = await assetServer.getImportMap(['app/assets/entry.tsx', 'app/assets/search.tsx'])
+```
+
+Without fingerprinting, import maps resolve authored specifiers to stable asset URLs. With fingerprinting enabled, the same import maps resolve stable asset URLs to content-fingerprinted asset URLs.
+
 ## Preloads
 
 Use `assetServer.getPreloads()` when rendering HTML so you can turn the returned URLs into `<link rel="modulepreload">`, stylesheet preload tags, or `Link` headers for one or more assets and their dependencies. You can provide root-relative or absolute file paths, or `file://` URLs.
@@ -266,7 +333,7 @@ let preloads = await assetServer.getPreloads([
 
 By default, assets are served at stable URLs with ETags and `Cache-Control: no-cache`.
 
-If you want clients to cache assets aggressively without revalidation, you can opt into source-based fingerprinting.
+If you want clients to cache assets aggressively without revalidation, you can opt into content-based fingerprinting.
 
 ```ts
 import { createAssetServer } from 'remix/assets'
@@ -276,15 +343,13 @@ let assetServer = createAssetServer({
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   watch: false,
-  fingerprint: {
-    buildId: process.env.GITHUB_SHA,
-  },
+  fingerprint: true,
 })
 ```
 
 When fingerprinting is enabled, assets use a `.@<fingerprint>` segment before the file extension and are served with `Cache-Control: public, max-age=31536000, immutable`.
 
-Source fingerprints are based on the original file contents and the build ID. The build ID must change for each deployment so that fingerprinted assets are invalidated together. This fingerprinting strategy assumes that files on disk won't change, so fingerprinting requires `watch: false`.
+Fingerprints are based on emitted asset contents. This allows unchanged assets to keep the same URL across deployments, but it assumes that files on disk won't change after a URL is generated, so fingerprinting requires `watch: false`.
 
 ## Target
 
@@ -542,11 +607,9 @@ let assetServer = createAssetServer({
 
 #### File transform caching
 
-Use `files.cache` to store transformed file outputs via a [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) backend.
-
-Without `files.cache`, transformed file outputs are recomputed per request.
+Use `files.cache` to store transformed file outputs via a [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) backend. Without `files.cache`, transformed file outputs are recomputed per request.
 
-If `fingerprint.buildId` is set, the file cache can be reused across server restarts for the same build.
+`files.cacheKey` scopes transformed file cache entries. Use a stable identifier, such as a commit SHA, when you want unchanged transformed files to be reused across server restarts for the same build.
 
 ```ts
 import * as path from 'node:path'
@@ -559,6 +622,7 @@ let assetServer = createAssetServer({
   allowPackages: ['remix'],
   files: {
     cache: createFsFileStorage(path.resolve('.tmp/assets-cache')),
+    cacheKey: process.env.GIT_COMMIT_SHA,
     extensions: ['.svg', '.png', '.jpg', '.jpeg', '.woff2'],
     transforms: {
       /*...*/
@@ -647,7 +711,7 @@ let isDevelopment = process.env.NODE_ENV === 'development'
 let assetServer = createAssetServer({
   basePath: '/assets',
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
-  denyFiles: ['app/**/*.test.*'],
+  allowPackages: ['remix'],
   hmr: isDevelopment
     ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
     : undefined,
@@ -655,6 +719,30 @@ let assetServer = createAssetServer({
 })
 ```
 
+Use `moduleImporter` to customize how HMR dynamically imports updated browser modules. It is resolved relative to the asset server's root directory and must point to a browser module exporting:
+
+```ts
+export function importModule(specifier: string, parentUrl: string): Promise<Record<string, unknown>>
+```
+
+HMR appends mappings for updated modules to the document in additional `<script type="importmap">` elements. Use `remix/multiple-import-maps-polyfill` when these updates must work in browsers without native support for multiple import maps:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+import { createBrowserHmrChannel } from 'remix/node-hmr/runtime'
+
+let assetServer = createAssetServer({
+  basePath: '/assets',
+  allowFiles: ['app/routes.ts', 'app/**/public/**'],
+  allowPackages: ['remix'],
+  hmr: {
+    channel: createBrowserHmrChannel,
+    moduleImporter: 'remix/multiple-import-maps-polyfill',
+  },
+  watch: true,
+})
+```
+
 ### `import.meta.hot`
 
 The `import.meta.hot` API provided by `assets` is a small runtime contract for modules that can handle updates without reloading the page. It is primarily intended for browser modules compiled by `assets`, but it can also be used directly.

package/src/fetch-router/README.md

@@ -237,6 +237,45 @@ router.map(routes.contact, {
 })
 ```
 
+#### Method Not Allowed Responses
+
+When a request URL matches one or more route patterns, but none of those routes are registered for the request method, the router first falls through to any less specific route that can handle the method (including `ANY` routes). If no route can handle the request, the router responds with `405 Method Not Allowed` and an [`Allow` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Allow) listing the methods that are registered for that URL, instead of treating the request as a 404.
+
+```ts
+import { createRouter } from 'remix/router'
+
+let router = createRouter()
+
+router.get('/users/:id', ({ params }) => new Response(`User ${params.id}`))
+router.put('/users/:id', ({ params }) => new Response(`Updated ${params.id}`))
+
+let response = await router.fetch('https://remix.run/users/1', { method: 'DELETE' })
+// 405 Method Not Allowed
+// Allow: GET, HEAD, PUT
+```
+
+If you want a handler to receive every request method at a given URL instead, register an `ANY` route for it.
+
+#### HEAD Requests
+
+Routes registered for `GET` also serve `HEAD` requests. The `GET` handler runs as usual, and the router strips the body from its response, so a `HEAD` request observes the same status and headers as the equivalent `GET` request.
+
+```ts
+let router = createRouter()
+
+router.get(
+  '/report',
+  () => new Response('report data', { headers: { 'Content-Type': 'text/csv' } }),
+)
+
+let response = await router.fetch('https://remix.run/report', { method: 'HEAD' })
+// 200 OK
+// Content-Type: text/csv
+// (empty body)
+```
+
+If you register an explicit `HEAD` route for the same pattern, it takes precedence over the `GET` route for `HEAD` requests.
+
 ### 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.

package/src/multiple-import-maps-polyfill/README.md

@@ -0,0 +1,107 @@
+# multiple-import-maps-polyfill
+
+Polyfill for dynamic JavaScript imports that depend on import maps added after the document's initial import map. Browsers with native support for multiple import maps continue to use native dynamic imports.
+
+The module loading logic in this package was adapted from [ES Module Shims](https://github.com/guybedford/es-module-shims) by Guy Bedford.
+
+This package assumes the initial document contains one complete import map before any module scripts. It is designed to load dynamic imports that depend on additional import maps installed after the initial page load.
+
+## Features
+
+- Detects native support for multiple import maps
+- Loads dynamic imports through every import map in the document when a polyfill is required
+- Preloads dynamic modules through the same polyfill cache
+- Resolves native module types through import maps while leaving their loading semantics to the browser
+- Supports import-map integrity metadata
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+Use `importModule` in place of `import()` when a dynamic import may depend on an import map added at runtime:
+
+```ts
+import { importModule } from 'remix/multiple-import-maps-polyfill'
+
+let moduleUrl = new URL('./features/search.ts', import.meta.url).href
+let feature = await importModule(moduleUrl)
+feature.openSearch()
+```
+
+`importModule` uses native `import()` when the browser supports multiple import maps. In other browsers, it loads the module through the polyfill using every import map currently installed in the document.
+
+Use `detectMultipleImportMapSupport` and `preloadShim` when an integration also manages module preloads. For example, configure Remix UI to load client entries discovered during navigation:
+
+```ts
+import {
+  detectMultipleImportMapSupport,
+  importModule,
+  preloadShim,
+} from 'remix/multiple-import-maps-polyfill'
+import { run } from 'remix/ui'
+
+run({
+  async loadModule(moduleUrl, exportName) {
+    let module = await importModule(moduleUrl)
+    let Component = module[exportName]
+    if (typeof Component !== 'function') {
+      throw new Error(`Unknown component: ${moduleUrl}#${exportName}`)
+    }
+    return Component
+  },
+  async processClientEntryPreloads(preloads) {
+    if (await detectMultipleImportMapSupport()) return preloads
+
+    preloadShim(preloads)
+    return []
+  },
+})
+```
+
+Browsers with multiple import map support retain native module loading and native `<link rel="modulepreload">` elements. Other browsers load late client entries and preloads through the polyfill.
+
+`detectMultipleImportMapSupport()` returns a cached promise. When it detects that the polyfill is required, it begins loading the polyfill runtime in the background so the work can overlap with a later `importShim()` or `preloadShim()` call. Browsers with multiple import map support do not load the polyfill runtime.
+
+`importShim()` always uses the polyfill to load a dynamic JavaScript import using every import map currently installed in the document. It does not detect native support. `preloadShim()` always uses the polyfill fetch cache rather than native module preload links. Like native module preloads, it fetches only the supplied module specifier or array of specifiers and caches their responses for later imports. Preload failures are ignored. `importShim()` reports the failure if the module is later required.
+
+## Content Security Policy
+
+Polyfilled module graphs are evaluated from blob URLs, and `es-module-lexer` compiles its parser from Wasm. Content Security Policies must allow `blob:` module scripts and Wasm compilation with `'wasm-unsafe-eval'`.
+
+The support detector creates a Trusted Types policy named `remix/multiple-import-maps-polyfill`. Allow this policy when Trusted Types are required for scripts, for example:
+
+```http
+Content-Security-Policy: script-src 'self' blob: 'wasm-unsafe-eval'; require-trusted-types-for 'script'; trusted-types remix/multiple-import-maps-polyfill;
+```
+
+## `remix/assets` HMR Support
+
+HMR appends mappings for updated modules to the document in additional `<script type="importmap">` elements. Configure the Remix asset server's `hmr.moduleImporter` option to use the polyfilled `importModule` function when these updates must work in browsers without native support for multiple import maps:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+import { createBrowserHmrChannel } from 'remix/node-hmr/runtime'
+
+let assets = createAssetServer({
+  hmr: {
+    channel: createBrowserHmrChannel,
+    moduleImporter: 'remix/multiple-import-maps-polyfill',
+  },
+  watch: true,
+})
+```
+
+The module importer and its dependencies must be available through the document's initial import map. Importing `remix/multiple-import-maps-polyfill` from the application's main client entry satisfies this requirement.
+
+## Related Packages
+
+- [`assets`](https://github.com/remix-run/remix/tree/main/packages/assets) - Compiles and serves browser assets
+- [`ui`](https://github.com/remix-run/remix/tree/main/packages/ui) - Loads client entries discovered during navigation
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/packages/multiple-import-maps-polyfill/LICENSE)

package/src/multiple-import-maps-polyfill.ts

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

package/src/render-middleware/README.md

@@ -6,7 +6,7 @@ Request-scoped response rendering for Remix. It provides the conventional Remix
 
 - **Remix UI rendering** - Stream nodes to HTML responses with `render()`
 - **Framework-owned frames** - Resolve nested and targeted `<Frame>` requests through the current router
-- **Client entry assets** - Resolve source-based `clientEntry()` modules and their preloads through an asset server
+- **Client entry assets** - Resolve source-based `clientEntry()` modules, import maps, and preloads through an asset server
 - **Typed context** - Preserve renderer input and response option types on `context.render`
 - **Custom renderers** - Install JSON, email, or other response pipelines with `renderWith()`
 
@@ -72,7 +72,7 @@ The middleware forwards request credentials and session headers to internal fram
 
 ### Options
 
-- **`assets`** - An asset server that resolves source-based client entry IDs to browser module URLs and preload URLs. Omit it when client entries already use public URLs or the app has no client entries.
+- **`assets`** - An asset server that resolves source-based client entry IDs to browser module URLs, import maps, and preload URLs. Omit it when client entries already use public URLs or the app has no client entries.
 - **`onError`** - A callback for server rendering errors. When omitted, the UI renderer uses its default error reporting.
 
 ## Custom renderers

package/src/ui/README.md

@@ -79,10 +79,9 @@ function Actions() {
 }
 ```
 
-## Frame Navigation
+## Client Entry Loading
 
-`run()` progressively enhances same-origin links and forms using a default `resolveFrame` that
-fetches the frame source:
+`run()` hydrates client entries by calling `loadModule` for each component module:
 
 ```tsx
 import { run } from 'remix/ui'
@@ -97,6 +96,47 @@ let app = run({
 await app.ready()
 ```
 
+Client entries introduced after the initial document may depend on import maps added at runtime.
+When targeting browsers without native support for multiple import maps, use
+`remix/multiple-import-maps-polyfill` to load these modules and process their preloads:
+
+```tsx
+import {
+  detectMultipleImportMapSupport,
+  importModule,
+  preloadShim,
+} from 'remix/multiple-import-maps-polyfill'
+
+let app = run({
+  async loadModule(moduleUrl, exportName) {
+    let module = await importModule(moduleUrl)
+    let Component = module[exportName]
+    if (typeof Component !== 'function') {
+      throw new Error(`Unknown component: ${moduleUrl}#${exportName}`)
+    }
+    return Component
+  },
+  async processClientEntryPreloads(preloads) {
+    if (await detectMultipleImportMapSupport()) return preloads
+
+    preloadShim(preloads)
+    return []
+  },
+})
+```
+
+## Frame Navigation
+
+The same runtime represents the current document as `app.frames.top` and intercepts eligible
+same-origin links and forms through the browser's Navigation API. Those navigations fetch HTML with
+the frame resolver and update the existing document in place instead of loading a new document.
+This soft-navigation behavior applies even when the page only uses `clientEntry()` and does not
+render an explicit `<Frame>`.
+
+Frame navigation requires both `window.navigation` and `NavigateEvent.sourceElement`. Browsers
+missing either capability use document navigation for links, forms, and `navigate()`. Hydration and
+explicit frame reloads still work.
+
 The default resolver is equivalent to:
 
 ```js
@@ -108,7 +148,8 @@ async function resolveFrame(src, options) {
     signal: options?.signal,
   })
 
-  if (!response.ok) {
+  let isHtml = response.headers.get('Content-Type')?.toLowerCase().includes('text/html')
+  if (response.status >= 500 || (response.status >= 300 && !isHtml)) {
     throw new Error(`Failed to resolve frame: ${response.status} ${response.statusText}`.trimEnd())
   }
 
@@ -149,11 +190,18 @@ CRLF-delimited text, and `multipart/form-data` submissions use `FormData`. Pass
 `resolveFrame` when the server requires additional headers, another body encoding, or a different
 response policy.
 
-Add `data-rmx-document` to a link or form to leave its navigation to the browser.
+Add `data-rmx-document` to a link or form to leave that navigation to the browser. To keep all links
+and forms as document navigations while still hydrating client entries and using explicit frames,
+register a listener before calling `run()`:
+
+```ts
+window.navigation?.addEventListener('navigate', (e) => e.stopImmediatePropagation())
+```
+
+This prevents Remix from intercepting Navigation API events. Explicit frame reloads such as
+`handle.frame.reload()` continue to use the frame resolver.
 
-The default resolver rejects non-OK responses with an error containing their status and status text.
-A custom `resolveFrame` may return a `Response` with any status when it wants Remix UI to render the
-response body.
+The default resolver accepts `2xx` responses and `3xx` or `4xx` responses whose `Content-Type` includes `text/html`, ignoring case. It rejects other `3xx` or `4xx` responses and all `5xx` responses with an error containing their status and status text. A custom `resolveFrame` may return a `Response` with any status when it wants Remix UI to render the response body.
 
 Forms remain ordinary HTML forms before the runtime starts. Add `data-rmx-target` to reload a named frame, or `data-rmx-document` to require a full-document submission:
 

package/src/ui/server/README.md

@@ -33,12 +33,10 @@ let stream = renderToStream(<App />, {
     return fetchHtml(frameUrl)
   },
   async resolveClientEntry(entryId, component) {
-    let [href, preloads] = await Promise.all([
-      assetServer.getHref(entryId),
-      assetServer.getPreloads(entryId),
-    ])
+    let { href, importMap, preloads } = await assetServer.getScriptEntry(entryId)
     return {
       href,
+      importMap,
       exportName: entryId.split('#')[1] || component.name,
       preloads,
     }
@@ -59,7 +57,7 @@ return new Response(stream, {
 - **`topFrameSrc`** - Overrides the root frame URL used for `handle.frames.top.src`. This is mainly useful when calling `renderToStream()` from inside `resolveFrame()` for a nested frame render.
 - **`signal`** - Cancels pending server rendering work. Pass `request.signal` so client disconnects can stop unresolved frame work without invoking `onError` for the disconnect itself.
 - **`resolveFrame(src, target, context)`** - Called when a `<Frame>` needs its content. Return a string of HTML, a `ReadableStream<Uint8Array>`, or a promise of either. `context.currentFrameSrc` is the URL for the frame that contains the `<Frame>`, and `context.topFrameSrc` is the outer document URL. Required if your component tree contains `<Frame>` elements.
-- **`resolveClientEntry(entryId, component)`** - Resolves the public module URL, export name, and optional module preload hrefs for a hydrated client entry.
+- **`resolveClientEntry(entryId, component)`** - Resolves the public module URL, export name, optional import map, and optional module preload hrefs for a hydrated client entry.
 - **`onError(error)`** - Called when a rendering error occurs. If not provided, the stream rejects with the error.
 
 When you render nested frame responses with `renderToStream()` inside `resolveFrame()`, pass `frameSrc` for the frame being rendered and carry `topFrameSrc` forward from the parent context. That preserves `handle.frames.top.src` across the whole SSR frame tree.
@@ -97,6 +95,28 @@ function ProductPage() {
 
 Components using the `css(...)` mixin through `mix` have their styles collected during rendering and emitted as a single `<style>` tag in the `<head>`. No client-side style injection is needed for server-rendered content.
 
+### Import maps
+
+Use `<ImportMap>` when the document needs one initial import map containing both authored mappings and mappings from blocking client entries. The server merges these mappings into the component before sending the initial HTML.
+
+Regular `<script type="importmap">` elements remain supported. The server leaves them unchanged and emits any additional client entry mappings separately, omitting entries already present in authored maps.
+
+```tsx
+import type { Handle, RemixNode } from 'remix/ui'
+import { ImportMap } from 'remix/ui/server'
+
+function Document(handle: Handle<{ children: RemixNode }>) {
+  return () => (
+    <html>
+      <head>
+        <ImportMap value={scriptEntry.importMap} />
+      </head>
+      <body>{handle.props.children}</body>
+    </html>
+  )
+}
+```
+
 ## See Also
 
 - [Hydration](https://github.com/remix-run/remix/blob/main/packages/ui/docs/hydration.md) - Making server-rendered components interactive on the client

package/src/ui-hmr/README.md

@@ -39,7 +39,10 @@ let assetServer = createAssetServer({
   allowPackages: ['remix'],
   denyFiles: ['app/**/*.test.*'],
   hmr: isDevelopment
-    ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
+    ? {
+        channel: async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel(),
+        moduleImporter: 'remix/multiple-import-maps-polyfill',
+      }
     : undefined,
   scripts: {
     loaders: isDevelopment ? [uiHmr()] : undefined,
@@ -48,6 +51,8 @@ let assetServer = createAssetServer({
 })
 ```
 
+HMR appends mappings for updated modules to the document in additional `<script type="importmap">` elements. The module importer allows browsers without native support for multiple import maps to load these updates.
+
 ## Direct Transforms
 
 Use the direct transform APIs when you are writing your own loader, Node module hooks, or build integration.