@remix-run/cli 0.3.4 → 0.4.0

package/src/lib/route-map.ts

@@ -1,15 +1,15 @@
-import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
 import * as process from 'node:process'
 import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 
+import { findAppRoot } from './app-root.ts'
 import {
   ROOT_ROUTE_NAME,
   inspectControllerOwnership,
   type ControllerOwnership,
   type OwnedSubtree,
-  type RouteDirectoryPlan,
+  type RouteDirectory,
 } from './controller-ownership.ts'
 import {
   routeMapLoaderFailed,
@@ -152,29 +152,17 @@ function decorateRouteTree(
     ownership.routeDirectories.map((directory) => [directory.routeName, directory]),
   )
 
-  return decorateRouteTreeWithLookup(
-    rawTree,
-    subtreesByRouteName,
-    directoriesByRouteName,
-    ownership.scan.routeDirectoryPaths,
-  )
+  return decorateRouteTreeWithLookup(rawTree, subtreesByRouteName, directoriesByRouteName)
 }
 
 function decorateRouteTreeWithLookup(
   rawTree: RawRouteTreeNode[],
   subtreesByRouteName: Map<string, OwnedSubtree>,
-  directoriesByRouteName: Map<string, RouteDirectoryPlan>,
-  actualRouteDirectories: Set<string>,
+  directoriesByRouteName: Map<string, RouteDirectory>,
   parentSegments: string[] = [],
 ): RouteTreeNode[] {
   return rawTree.map((rawNode) => {
-    let owner = getRouteOwner(
-      rawNode,
-      parentSegments,
-      subtreesByRouteName,
-      directoriesByRouteName,
-      actualRouteDirectories,
-    )
+    let owner = getRouteOwner(rawNode, parentSegments, subtreesByRouteName, directoriesByRouteName)
     let nextParentSegments =
       rawNode.kind === 'group' ? [...parentSegments, rawNode.key] : parentSegments
 
@@ -185,7 +173,6 @@ function decorateRouteTreeWithLookup(
               rawNode.children,
               subtreesByRouteName,
               directoriesByRouteName,
-              actualRouteDirectories,
               nextParentSegments,
             )
           : [],
@@ -203,8 +190,7 @@ function getRouteOwner(
   rawNode: RawRouteTreeNode,
   parentSegments: string[],
   subtreesByRouteName: Map<string, OwnedSubtree>,
-  directoriesByRouteName: Map<string, RouteDirectoryPlan>,
-  actualRouteDirectories: Set<string>,
+  directoriesByRouteName: Map<string, RouteDirectory>,
 ): RouteTreeOwner {
   let ownerRouteName =
     rawNode.kind === 'group'
@@ -230,7 +216,7 @@ function getRouteOwner(
     }
 
     return {
-      exists: actualRouteDirectories.has(directory.directoryPath),
+      exists: directory.exists,
       kind: 'directory',
       path: directory.directoryPath,
     }
@@ -296,36 +282,13 @@ function assertRawRouteTreeNode(value: unknown): RawRouteTreeNode {
 }
 
 async function findRemixAppRoot(startDir: string): Promise<string> {
-  let currentDir = path.resolve(startDir)
-
-  while (true) {
-    if (await pathExists(path.join(currentDir, 'app', 'routes.ts'))) {
-      return currentDir
-    }
+  let appRoot = await findAppRoot(startDir, 'app/routes.ts')
 
-    let parentDir = path.dirname(currentDir)
-    if (parentDir === currentDir) {
-      break
-    }
-
-    currentDir = parentDir
+  if (appRoot == null) {
+    throw routesFileNotFound(startDir)
   }
 
-  throw routesFileNotFound(startDir)
-}
-
-async function pathExists(filePath: string): Promise<boolean> {
-  try {
-    await fs.access(filePath)
-    return true
-  } catch (error) {
-    let nodeError = error as NodeJS.ErrnoException
-    if (nodeError.code === 'ENOENT') {
-      return false
-    }
-
-    throw error
-  }
+  return appRoot
 }
 
 function getRouteMapWorkerPath(): string {

package/template/.agents/skills/remix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: remix
-description: Build and review Remix 3 applications using the `remix` npm package and subpath imports. Use when working on Remix app structure, routes, controllers, middleware, validation, data access, auth, sessions, file uploads, server setup, UI components, hydration, navigation, or tests.
+description: Build and review Remix 3 applications using the `remix` npm package and subpath imports. Use when working on Remix app structure, routes, controllers, middleware, validation, data access, auth, sessions, file uploads, server setup, UI components, hydration, HMR, navigation, or tests.
 ---
 
 # Build a Remix App
@@ -42,19 +42,19 @@ Classify the task first, then load the smallest useful reference set. Each refer
 
 Use the table below to find candidates. Loading more than two or three files at once is usually a sign that the task hasn't been narrowed enough yet.
 
-| Task involves...                                                              | Start with                                  |
-| ----------------------------------------------------------------------------- | ------------------------------------------- |
-| Defining URLs, writing controllers and actions, returning responses           | `references/routing-and-controllers.md`     |
-| Composing the request lifecycle, ordering middleware, bridging to a server    | `references/middleware-and-server.md`       |
-| Compiling and serving browser modules, asset URL namespaces, preloads         | `references/assets-and-browser-modules.md`  |
-| Parsing input, validating with schemas, defining tables, querying, migrations | `references/data-and-validation.md`         |
-| Per-browser state, login flows, route protection, identity                    | `references/auth-and-sessions.md`           |
-| Component setup, state, lifecycle, updates, `queueTask`, context              | `references/component-model.md`             |
-| Event handlers, styles, refs, click/key behavior, simple animations           | `references/mixins-styling-events.md`       |
-| `clientEntry`, `run`, `<Frame>`, navigation, `<head>`                         | `references/hydration-frames-navigation.md` |
-| Router tests, component tests, test isolation                                 | `references/testing-patterns.md`            |
-| Spring physics, tweens, layout transitions                                    | `references/animate-elements.md`            |
-| Authoring custom reusable mixins                                              | `references/create-mixins.md`               |
+| Task involves...                                                                            | Start with                                  |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| Defining URLs, writing controllers and actions, returning responses                         | `references/routing-and-controllers.md`     |
+| Composing the request lifecycle, ordering middleware, bridging to a server, development HMR | `references/middleware-and-server.md`       |
+| Compiling and serving browser modules, asset URL namespaces, preloads, browser HMR          | `references/assets-and-browser-modules.md`  |
+| Parsing input, validating with schemas, defining tables, querying, migrations               | `references/data-and-validation.md`         |
+| Per-browser state, login flows, route protection, identity                                  | `references/auth-and-sessions.md`           |
+| Component setup, state, lifecycle, updates, `queueTask`, context                            | `references/component-model.md`             |
+| Event handlers, styles, refs, click/key behavior, simple animations                         | `references/mixins-styling-events.md`       |
+| `clientEntry`, `run`, `<Frame>`, navigation, browser HMR update handling, `<head>`          | `references/hydration-frames-navigation.md` |
+| Router tests, component tests, test isolation                                               | `references/testing-patterns.md`            |
+| Spring physics, tweens, layout transitions                                                  | `references/animate-elements.md`            |
+| Authoring custom reusable mixins                                                            | `references/create-mixins.md`               |
 
 Common bundles:
 
@@ -62,6 +62,7 @@ Common bundles:
 - **Protected area** -> auth and sessions, routing, testing
 - **Interactive widget** -> component model, mixins and styling; add hydration only if it runs in the browser
 - **Browser asset pipeline** -> assets and browser modules, hydration, middleware and server
+- **Development HMR** -> middleware and server, assets and browser modules, hydration
 - **File upload** -> middleware and server, data and validation, testing
 - **Navigation or frames** -> hydration, frames, navigation
 
@@ -83,19 +84,19 @@ Use these root directories consistently:
 
 - `app/` for runtime application code
 - `db/` for migrations and local database files
-- `public/` for static assets served as-is
+- root `public/` for static assets served as-is from the app root
 - `test/` for shared helpers, fixtures, and integration coverage
 - `tmp/` for uploads, caches, local session files, and other scratch data
 
 Inside `app/`, organize by responsibility:
 
-- `assets/` for client entrypoints and client-owned browser behavior
 - `actions/` for controller-owned route handlers, route-local response rendering, and route-local UI/helpers that are not shared across route areas
 - `data/` for schema, queries, persistence setup, migrations, and runtime data initialization
 - `middleware/` for request lifecycle concerns such as auth, sessions, uploads, and database injection
+- `public/` directories inside the narrowest owner for browser-reachable source code, with the browser runtime entrypoint at `app/actions/public/entry.ts`
 - `ui/` for shared cross-route UI primitives
 - `utils/` only for genuinely cross-layer helpers that do not clearly belong elsewhere
-- `routes.ts` for the route contract
+- `routes.ts` for the shared server-and-browser route contract and type-safe href generation
 - `router.ts` for router setup and wiring
 
 ### Placement Precedence
@@ -147,10 +148,11 @@ When code could live in multiple places:
 - Model HTTP behavior explicitly. Status codes, headers, redirects, cache rules, and content types are part of the route contract
 - Make the server route correct first. A POST should already return the right HTML, redirect, or error response on its own before `clientEntry(...)` layers interactivity on top
 - Validate input at the boundary using `remix/data-schema` (and `remix/data-schema/form-data` for forms). `parseSafe` makes the failure path a return value instead of an exception
-- Derive `AppContext` from the middleware stack so `get(Database)`, `get(Session)`, `get(Auth)`, and similar keys stay typed. If the controller never reads from context, it doesn't need the harness
+- Derive `AppContext` from the middleware stack so `get(databaseContext)`, `get(Session)`, `get(Auth)`, and similar keys stay typed. If the controller never reads from context, it doesn't need the harness
 - Outside actions and controllers, only use `getContext()` when `asyncContext()` is in the middleware stack
 - Remix Component is not React: write `function Name(handle: Handle<Props>) { return () => ... }`, read props from `handle.props`, keep state in setup-scope variables, call `handle.update()` explicitly, and do DOM-sensitive work in event handlers or `queueTask(...)`, not in render
 - Prefer host-element mixins via `mix={mixin(...)}` for behavior and styling instead of inventing custom host prop conventions. Use `mix={[...]}` only when composing multiple mixins
+- Keep short, one-off static styles inline with `mix={css(...)}`. Extract a module-scoped style descriptor when it forms a reused visual recipe, has substantial selectors, media queries, or keyframes, or is large enough to obscure the component. Export a style descriptor only after multiple modules need the same visual recipe; otherwise keep it with its narrowest owner
 - Hydrated `clientEntry(...)` props must be serializable. Do not pass functions, class instances, or opaque runtime objects
 
 ## Security And Session Defaults
@@ -205,7 +207,11 @@ Use this map to find the right package quickly. Each entry says what the package
 - `remix/router` — the router itself. Use for `createRouter`, controllers, middleware types, and registering routes
 - `remix/routes` — declarative route builders. Use for `route`, `get`, `post`, `put`, `del`, `form`, `resources` when defining `app/routes.ts`
 - `remix/node-fetch-server` — default Node adapter for new apps. Use `createRequestListener` with `node:http`, `node:https`, or `node:http2` in `server.ts` when booting the template-style app
-- `remix/assets` — browser asset server. Use for `createAssetServer` when serving compiled scripts and styles, getting public hrefs, and emitting preloads. Configure a `basePath`, and keep `fileMap` URL patterns relative to it. Shared compiler options such as `target`, `sourceMaps`, `sourceMapSourcePaths`, and `minify` live at the top level
+- `remix/node-hmr` — optional development Node HMR runner for rapid UI edits. Use `run` in `hmr.ts` to supervise `server.ts` behind an `hmr` script, and use `createHmrReadyFetch` when a stable public proxy should wait for child server readiness during updates
+- `remix/node-hmr/runtime` — child-process runtime API for code running under `remix/node-hmr`. Use to create browser HMR channels for asset servers and to emit server readiness after the child server starts listening
+- `remix/node-hmr/types` — type-only entry for `import.meta.hot` in Node modules
+- `remix/assets` — browser asset server. Use for `createAssetServer` when serving compiled scripts and styles, getting public hrefs, emitting preloads, and wiring browser HMR. Configure a `basePath`, keep `fileMap` URL patterns relative to it, use `allowFiles`/`denyFiles` for path and glob rules, and use exact package names in `allowPackages` for package-level access. Shared compiler options such as `target`, `sourceMaps`, `sourceMapSourcePaths`, and `minify` live at the top level
+- `remix/assets/types/hmr` — type-only entry for `import.meta.hot` in browser modules compiled by `remix/assets`
 - `remix/headers` — `SuperHeaders` plus typed header parsers and builders. Use the default export when you want a `Headers` subclass with typed accessors like `headers.contentType`, `headers.cacheControl`, and `headers.setCookie`; use named classes such as `CacheControl`, `ContentDisposition`, and `Vary` when working with individual header values
 - `remix/response/redirect` — `redirect(href, status?)`. Use for the canonical "POST then redirect" pattern and other location changes
 - `remix/response/html` — `createHtmlResponse`. Use when you need an HTML `Response` from a string or stream without rendering through `remix/ui`
@@ -222,12 +228,12 @@ Use this map to find the right package quickly. Each entry says what the package
 - `remix/data-schema/coerce` — coercion helpers for strings, numbers, booleans, dates, and ids. Use when input arrives as a string but should be a typed value
 - `remix/data-schema/form-data` — `f.object` and `f.field` for parsing `FormData` directly. Use in actions that read browser forms
 - `remix/data-schema/lazy` — recursive or mutually-referential schemas. Use when a schema needs to refer to itself or another schema that is declared later
-- `remix/data-table` — typed tables and a `Database` interface. Use for `table`, `column`, `createDatabase` when modeling persisted data
-- `remix/data-table/sqlite`, `remix/data-table/postgres`, `remix/data-table/mysql` — adapters. Use to back `createDatabase` with a real engine. SQLite accepts Node, Bun, and compatible synchronous clients with the shared `prepare`/`exec` surface
-- `remix/data-table/migrations` — migration authoring and runners. Use for `createMigration`, `createMigrationRunner`
+- `remix/data-table` — typed tables and the shared `Database` API. Use `table` and `column` when modeling persisted data, then create a concrete database from the matching dialect package. Integration packages can implement `DatabaseDriver` and extend `Database` to add another SQL dialect
+- `remix/data-table/sqlite`, `remix/data-table/postgres`, `remix/data-table/mysql` — concrete database integrations. Use `createSqliteDatabase`, `createPostgresDatabase`, or `createMysqlDatabase`. SQLite accepts Node, Bun, and compatible synchronous clients with the shared `prepare`/`exec` surface
+- `remix/data-table/migrations` — migration authoring and registries. Use for `createMigration` and `createMigrationRegistry`; run migrations with `Database.migrate()`
 - `remix/data-table/migrations/node` — `loadMigrations` from disk. Use in startup scripts that apply migrations
 - `remix/data-table/operators` — query operators such as `inList(...)`. Use when `where` clauses need set or comparison logic
-- `remix/data-table/sql-helpers` — SQL helper utilities for adapter or advanced query work. Avoid this in normal app code unless you are intentionally working below the table/query API
+- `remix/data-table/sql-helpers` — SQL helper utilities for database integrations or advanced query work. Avoid this in normal app code unless you are intentionally working below the table/query API
 
 ### Auth, Sessions, and Cookies
 
@@ -244,6 +250,10 @@ Use this map to find the right package quickly. Each entry says what the package
 
 - `remix/ui` — the component runtime: components, core mixins, `clientEntry`, `run`, `<Frame>`, navigation helpers, and `createRoot`. Use for app UI behavior
 - `remix/ui/server` — server rendering: `renderToStream`, `renderToString`. Use in the `app/actions/render.tsx` helper that returns HTML responses
+- `remix/ui-hmr` — direct Remix UI component HMR transforms. Use only when writing a custom module hook or build integration
+- `remix/ui-hmr/node` — Node import hook for Remix UI component HMR. Use with `--import remix/ui-hmr/node` in development servers that run through `remix/node-hmr`
+- `remix/ui-hmr/assets` — `remix/assets` loader for Remix UI component HMR. Use `uiHmr()` in `createAssetServer({ scripts: { loaders } })` during development
+- `remix/ui/dev/refresh` — development refresh support used by HMR tooling, not normal application code
 - `remix/ui/animation` — animation APIs: `animateEntrance`, `animateExit`, `animateLayout`, `spring`, `tween`, and `easings`
 - `remix/ui/<primitive>` — UI primitives, mixins, and component helpers. Current subpaths include `remix/ui/accordion`, `remix/ui/anchor`, `remix/ui/button`, `remix/ui/checkbox`, `remix/ui/combobox`, `remix/ui/input`, `remix/ui/listbox`, `remix/ui/menu`, `remix/ui/popover`, and `remix/ui/select`
 - `remix/ui/test` — component test rendering helpers such as `render`
@@ -309,17 +319,18 @@ export const routes = route({
 ```typescript
 import { createController } from 'remix/router'
 
+import { databaseContext } from '../middleware/database.ts'
 import { routes } from '../routes.ts'
 
 export default createController(routes.books, {
   actions: {
     async index({ get }) {
-      let db = get(Database)
+      let db = get(databaseContext)
       let allBooks = await db.findMany(books, { orderBy: ['id', 'asc'] })
       return render(<BooksIndexPage allBooks={allBooks} />)
     },
     async show({ get, params }) {
-      let db = get(Database)
+      let db = get(databaseContext)
       let book = await db.findOne(books, { where: { slug: params.slug } })
       if (!book) return new Response('Not Found', { status: 404 })
       return render(<BookShowPage book={book} />)
@@ -384,8 +395,8 @@ import { redirect } from 'remix/response/redirect'
 import * as s from 'remix/data-schema'
 import * as f from 'remix/data-schema/form-data'
 import { Session } from 'remix/session'
-import { Database } from 'remix/data-table'
 
+import { databaseContext } from '../middleware/database.ts'
 import { routes } from '../routes.ts'
 
 let bookSchema = f.object({
@@ -401,7 +412,7 @@ export default createController(routes.books, {
         return render(<NewBookPage errors={parsed.issues} />, { status: 400 })
       }
 
-      let db = get(Database)
+      let db = get(databaseContext)
       let book = await db.create(books, parsed.value)
 
       let session = get(Session)

package/template/.agents/skills/remix/references/assets-and-browser-modules.md

@@ -4,16 +4,17 @@
 
 How to serve browser scripts and styles from source. Read this when the task involves:
 
-- Configuring `createAssetServer` (`basePath`, `fileMap`, `allow`, `deny`, fingerprinting, compiler options)
+- Configuring `createAssetServer` (`basePath`, `fileMap`, `allowFiles`, `allowPackages`, `denyFiles`, fingerprinting, compiler options)
 - Choosing between `staticFiles()` for already-built files and `createAssetServer()` for source assets that need import rewriting, preloads, or fingerprinted URLs
 - Generating script URLs or `<link rel="modulepreload">` tags for a client entry
-- Keeping server-only files out of the browser via `deny` rules
+- Enabling browser HMR for source-served modules
+- Keeping files such as tests out of the browser via `denyFiles` rules
 
-For routing the URL namespace itself, see `routing-and-controllers.md`. For client entry hydration, see `hydration-frames-navigation.md`.
+For routing the URL namespace itself, see `routing-and-controllers.md`. For client entry hydration and browser update handling, see `hydration-frames-navigation.md`. For the Node HMR runner and browser HMR channel, see `middleware-and-server.md`.
 
 ## When To Reach For It
 
-Use `remix/assets` when the app serves browser JavaScript, TypeScript, or CSS from source files. This is the right tool for client entrypoints, browser-only helpers, styles under `app/assets/`, and monorepo code that should be compiled and served under a public URL namespace.
+Use `remix/assets` when the app serves browser JavaScript, TypeScript, or CSS from source files. This is the right tool for client entrypoints, browser-only helpers, styles, and monorepo code that should be compiled and served under a public URL namespace.
 
 Use `staticFiles()` for files that already exist on disk exactly as they should be served. Use `createAssetServer()` for source scripts or styles that need rewriting, dependency scanning, preloads, sourcemaps, or fingerprinted URLs.
 
@@ -35,8 +36,9 @@ let assetServer = createAssetServer({
     'app/*path': 'app/*path',
     'node_modules/*path': 'node_modules/*path',
   },
-  allow: ['app/assets/**', 'node_modules/**'],
-  deny: ['app/**/*.server.*'],
+  allowFiles: ['app/routes.ts', 'app/**/public/**'],
+  allowPackages: ['remix'],
+  denyFiles: ['app/**/*.test.*'],
   target: { es: '2020', chrome: '109', safari: '16.4' },
   sourceMaps: process.env.NODE_ENV === 'development' ? 'external' : undefined,
   minify: process.env.NODE_ENV === 'production',
@@ -58,8 +60,13 @@ export default createController(routes, {
 
 ## Rules
 
-- Treat `allow` and `deny` as the security boundary for browser-reachable source files.
-- Add a `deny` list for server-only modules such as `*.server.*`, private config, or other files that should never be exposed.
+- Treat `allowFiles`/`allowPackages` and `denyFiles` as the security boundary for browser-reachable source files.
+- Put browser-reachable app source in a `public/` directory inside `app/`, beside its narrowest owner, such as `app/ui/public/` or `app/actions/cart/public/`.
+- Every local dependency in a browser module graph must match `allowFiles`, so keep the whole graph inside those `public/` directories. `app/routes.ts` is allowed separately so browser modules can build type-safe links with `routes.*.href(...)`.
+- Deny test modules with `denyFiles` so tests can be colocated inside a `public/` directory without becoming browser-reachable.
+- Use `allowFiles` and `denyFiles` for file paths and globs. Relative values resolve from `rootDir`.
+- Use `allowPackages` for exact package names, not globs or subpaths. Packages allowed by `allowPackages` also allow their installed `dependencies` and `optionalDependencies`; peer dependencies must be listed explicitly if they should be browser-reachable.
+- `denyFiles` takes precedence over both file and package allow rules.
 - Set `rootDir` explicitly in monorepos so relative paths resolve from the intended project root.
 - `basePath` is the public URL namespace handled by the asset server.
 - `fileMap` keys are URL patterns relative to `basePath`, and values are root-relative file path patterns. They use `route-pattern` syntax on both sides.
@@ -71,8 +78,8 @@ export default createController(routes, {
 Use `getHref()` when you need the public URL for one module, and `getPreloads()` when you want `<link rel="modulepreload">` tags or `Link` headers for one or more entrypoints and their dependencies.
 
 ```typescript
-let entryHref = await assetServer.getHref('app/assets/entry.ts')
-let preloads = await assetServer.getPreloads(['app/assets/entry.ts'])
+let entryHref = await assetServer.getHref('app/actions/public/entry.ts')
+let entryPreloads = await assetServer.getPreloads('app/actions/public/entry.ts')
 ```
 
 Use this when rendering documents or layouts that boot browser behavior with a known client entry.
@@ -86,6 +93,8 @@ In development:
 - Keep `watch` enabled so source changes are picked up without restarting the server
 - Prefer stable URLs with normal revalidation
 - Enable source maps when debugging browser code
+- Use `hmr` only when the app is running under `remix/node-hmr`
+- Use `scripts.loaders` for development-only browser transforms such as `uiHmr()`
 
 In deployment:
 
@@ -95,6 +104,39 @@ In deployment:
 
 Fingerprinting assumes files on disk are stable and requires `watch: false`.
 
+## Browser HMR
+
+Use browser HMR when source-served browser modules should update without a full page reload during development. Let `remix/node-hmr` own the browser HMR channel so browser updates stay coordinated with server restarts.
+
+```typescript
+import { createAssetServer } from 'remix/assets'
+import { uiHmr } from 'remix/ui-hmr/assets'
+
+const isDevelopment = process.env.NODE_ENV === 'development'
+const isHmr = Boolean(isDevelopment && process.env.REMIX_NODE_HMR)
+
+const assetServer = createAssetServer({
+  basePath: '/assets',
+  fileMap: { '/app/*path': 'app/*path' },
+  allowFiles: ['app/routes.ts', 'app/**/public/**'],
+  denyFiles: ['app/**/*.test.*'],
+  watch: isDevelopment,
+  hmr: isHmr
+    ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
+    : undefined,
+  scripts: {
+    loaders: isHmr ? [uiHmr()] : undefined,
+  },
+})
+```
+
+Rules:
+
+- Guard `remix/node-hmr/runtime` imports with `process.env.REMIX_NODE_HMR`; that runtime API is only available inside the supervised child process.
+- Keep browser HMR and loaders development-only.
+- Add `remix/assets/types/hmr` to `compilerOptions.types` only when browser source modules use `import.meta.hot` directly.
+- Write HMR accept calls directly as `import.meta.hot.accept(...)` with literal dependency specifiers.
+
 ## Useful Compiler Options
 
 - `minify` for production minification of scripts and styles
@@ -103,6 +145,7 @@ Fingerprinting assumes files on disk are stable and requires `watch: false`.
 - `target` as an object for shared browser targets and script-only ECMAScript output, such as `{ es: '2020', chrome: '109', safari: '16.4' }`
 - `scripts.define` to replace globals such as `process.env.NODE_ENV`
 - `scripts.external` to leave specific script imports untouched
+- `scripts.loaders` to transform browser modules during compilation
 
 Do not nest shared compiler options under `scripts`. Use top-level `minify`, `sourceMaps`, `sourceMapSourcePaths`, and `target` so they apply to styles as well as scripts.
 

package/template/.agents/skills/remix/references/auth-and-sessions.md

@@ -137,7 +137,7 @@ Notice that there is no manual `Set-Cookie` plumbing in the action — the sessi
 ```typescript
 import { auth, createSessionAuthScheme } from 'remix/middleware/auth'
 import { Session } from 'remix/session'
-import { Database } from 'remix/data-table'
+import { databaseContext } from '~/middleware/database.ts'
 
 export function loadAuth() {
   return auth({
@@ -148,7 +148,7 @@ export function loadAuth() {
           return data ?? null
         },
         async verify(value, context) {
-          let db = context.get(Database)
+          let db = context.get(databaseContext)
           return (await db.find(users, value.userId)) ?? null
         },
         invalidate(session) {
@@ -195,7 +195,7 @@ export let passwordProvider = createCredentialsAuthProvider({
     return s.parse(loginSchema, formData)
   },
   async verify({ email, password }, context) {
-    let db = context.get(Database)
+    let db = context.get(databaseContext)
     let user = await db.findOne(users, { where: { email } })
     if (!user || !(await verifyPassword(password, user.password_hash))) {
       return null
@@ -300,7 +300,7 @@ export default createController(routes.auth.google, {
     async callback(context) {
       let { result, returnTo } = await finishExternalAuth(googleProvider, context)
 
-      let db = context.get(Database)
+      let db = context.get(databaseContext)
       let { user, authAccount } = await resolveExternalAuth(db, result)
 
       let session = completeAuth(context)
@@ -322,7 +322,7 @@ Use `refreshExternalAuth(provider, tokens)` when an app has stored OAuth/OIDC to
 
 ```typescript
 async function refreshGoogleTokens({ get }) {
-  let db = get(Database)
+  let db = get(databaseContext)
   let account = await db.findOne(authAccounts, { where: { provider: 'google' } })
   if (!account) return null
 

package/template/.agents/skills/remix/references/data-and-validation.md

@@ -113,30 +113,30 @@ export const books = table({
 
 ## Database Setup
 
-Create a database with an adapter and expose it via middleware:
+Create a database and expose it via middleware:
 
 ```typescript
 import BetterSqlite3 from 'better-sqlite3'
-import { createDatabase, Database } from 'remix/data-table'
-import { createSqliteDatabaseAdapter } from 'remix/data-table/sqlite'
+import { createSqliteDatabase } from 'remix/data-table/sqlite'
 
 let sqlite = new BetterSqlite3('./db/app.db')
 sqlite.pragma('foreign_keys = ON')
-let adapter = createSqliteDatabaseAdapter(sqlite)
-export let db = createDatabase(adapter)
+export let db = createSqliteDatabase(sqlite)
 ```
 
-`createSqliteDatabaseAdapter` accepts synchronous SQLite clients with a shared `prepare`/`exec` surface, including Node's `node:sqlite`, Bun's `bun:sqlite`, and compatible clients. Use whichever client fits the runtime instead of assuming `better-sqlite3` is required.
+`createSqliteDatabase` accepts synchronous SQLite clients with a shared `prepare`/`exec` surface, including Node's `node:sqlite`, Bun's `bun:sqlite`, and compatible clients. Use whichever client fits the runtime instead of assuming `better-sqlite3` is required.
 
 ### Database middleware
 
 ```typescript
-import type { Middleware } from 'remix/router'
-import { Database } from 'remix/data-table'
+import type { Database } from 'remix/data-table'
+import { createContextKey, type Middleware } from 'remix/router'
+
+export const databaseContext = createContextKey<Database>()
 
 export function loadDatabase(): Middleware {
   return async (context, next) => {
-    context.set(Database, db)
+    context.set(databaseContext, db)
     return next()
   }
 }
@@ -145,7 +145,7 @@ export function loadDatabase(): Middleware {
 ### Querying
 
 ```typescript
-let db = get(Database)
+let db = get(databaseContext)
 
 // Find by primary key
 let book = await db.find(books, id)
@@ -220,7 +220,7 @@ Do **not** import app code (e.g. `app/data/schema.ts`) into migration files. Mig
 
 ### Transaction modes
 
-Migrations run inside a transaction by default (when the adapter supports transactional DDL). Override per migration with a directive comment in `up.sql`:
+Migrations run inside a transaction by default (when the database supports transactional DDL). Override per migration with a directive comment in `up.sql`:
 
 ```sql
 -- data-table/transaction: none
@@ -232,15 +232,15 @@ Modes: `auto` (default — wrap when supported), `required` (wrap; throw if unsu
 ### Running migrations
 
 ```typescript
-import { createMigrationRunner } from 'remix/data-table/migrations'
 import { loadMigrations } from 'remix/data-table/migrations/node'
 
 let migrations = await loadMigrations('./db/migrations')
-let runner = createMigrationRunner(adapter, migrations)
-await runner.up()
+await db.migrate(migrations)
 ```
 
-The runner checksums each `up.sql` and detects drift if a previously applied migration changes. Use `runner.status()` to inspect applied/pending/drifted state, and `runner.down()` to revert.
+The database checksums each `up.sql` and detects drift if a previously applied migration changes.
+Use `db.migrationStatus(migrations)` to inspect applied/pending/drifted state, and
+`db.migrate(migrations, { direction: 'down' })` to revert.
 
 ## Input Validation (`remix/data-schema`)
 

package/template/.agents/skills/remix/references/hydration-frames-navigation.md

@@ -7,11 +7,12 @@ How server-rendered UI becomes interactive in the browser, and how the page upda
 - Marking a component for client-side hydration with `clientEntry`
 - Booting the client runtime with `run`
 - Streaming server content into a region of the page with `<Frame>` and reloading those regions
+- Handling browser HMR updates for hydrated entries
 - Triggering Navigation API transitions with `navigate(...)` or `link(...)`
 - Server rendering with `renderToStream` or `renderToString`
 - Managing the document `<head>`
 
-For component-local state and updates, see `component-model.md`. For host-element behavior and events, see `mixins-styling-events.md`.
+For component-local state and updates, see `component-model.md`. For host-element behavior and events, see `mixins-styling-events.md`. For browser asset HMR setup, see `assets-and-browser-modules.md`.
 
 ## Server First, Then Hydrate
 
@@ -94,21 +95,39 @@ Client entry props must be serializable: strings, numbers, booleans, `null`, `un
 Use `run` to start the client runtime. It scans the document for client entry markers, loads modules, and hydrates each one:
 
 ```tsx
+import type { ResolveFrameOptions } from 'remix/ui'
 import { run } from 'remix/ui'
 
-let app = run({
+const app = run({
   async loadModule(moduleUrl, exportName) {
     let mod = await import(moduleUrl)
     return mod[exportName]
   },
-  async resolveFrame(src, signal, target) {
-    let headers = new Headers({ accept: 'text/html' })
-    if (target) headers.set('x-remix-target', target)
-    let response = await fetch(src, { headers, signal })
+  async resolveFrame(src, options) {
+    let headers = new Headers({ accept: 'text/html', 'x-remix-frame': 'true' })
+    if (options?.target) headers.set('x-remix-target', options.target)
+    let response = await fetch(src, {
+      body: getRequestBody(options),
+      headers,
+      method: options?.method,
+      signal: options?.signal,
+    })
     return response.body ?? (await response.text())
   },
 })
 
+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
+}
+
 app.addEventListener('error', (event) => {
   console.error('Component error:', event.error)
 })
@@ -119,7 +138,7 @@ await app.ready()
 ### `run` options
 
 - **`loadModule(moduleUrl, exportName)`** (required) — return the component function for each client entry. Typically uses dynamic `import()`.
-- **`resolveFrame(src, signal, target)`** (optional) — called when a `<Frame>` loads or reloads content. `target` is available when frame targeting matters.
+- **`resolveFrame(src, options)`** (optional) — called when a `<Frame>` loads or reloads content and for intercepted link and form navigations. `options` may contain `signal` and `target`; non-GET forms also provide `formData`, `method`, and `encType`.
 
 ### `app` methods
 
@@ -129,6 +148,19 @@ await app.ready()
 
 `app` is an `EventTarget` that emits `error` events from any hydrated component.
 
+## Browser HMR Updates
+
+When `remix/node-hmr` reports a server update, reload the top frame to apply the latest server-rendered document while preserving browser state:
+
+```tsx
+if (import.meta.hot) {
+  import.meta.hot.on('server:update', async () => {
+    await app.ready()
+    await app.frames.top.reload()
+  })
+}
+```
+
 ## Frames
 
 A `<Frame>` renders server content into the page. Frames stream after the initial HTML, nest inside other frames, contain client entries, and can be reloaded without full page navigation.
@@ -175,6 +207,20 @@ handle.frames.top.reload()
 
 When a frame reloads, matching DOM nodes are updated in place. Client entries receive updated props while preserving their local component state.
 
+### Form navigation
+
+When `run({ resolveFrame })` is active, eligible same-origin forms progressively enhance into frame navigations. Native validation and the form's `submit` event still run first.
+
+- Forms target `handle.frames.top` by default.
+- `rmx-target` selects a named frame.
+- `rmx-src` selects a different frame request URL while preserving the form action as the navigation destination.
+- `rmx-history="push|replace"` overrides how the navigation updates history.
+- `rmx-reset-scroll="false"` preserves scroll position.
+- `rmx-document` opts back into a document submission.
+- Cross-origin forms, `method="dialog"`, and `target="_blank"` remain browser-owned.
+
+GET controls are already encoded in `src`, so GET forms reach the resolver like links. Non-GET forms provide their native `FormData`, effective method, and encoding. The resolver owns body encoding and method-override conventions. Non-GET submissions to the current URL replace its history entry; GET submissions and submissions to a different URL push one. The `rmx-history` attribute overrides those defaults.
+
 ### Nested frames
 
 Frames can nest. Each frame owns its own DOM region and hydrates client entries independently. During SSR, `handle.frame.src` points at the frame being rendered, while `handle.frames.top.src` stays fixed at the outer document URL.
@@ -238,7 +284,7 @@ navigate('/dashboard', { history: 'replace' })
 
 Options: `src`, `target`, `history` (`'push' | 'replace'`), `resetScroll`.
 
-Attributes understood by the runtime: `rmx-target`, `rmx-src`, `rmx-document`.
+Attributes understood by the runtime: `rmx-target`, `rmx-src`, `rmx-history`, `rmx-reset-scroll`, `rmx-document`.
 
 ## Head Management