@remix-run/cli 0.5.0 → 0.6.0

package/src/lib/completion.ts

@@ -6,8 +6,9 @@ export interface CompletionResult {
 }
 
 const COMPLETION_SHELLS = ['bash', 'zsh'] as const
-const DB_COMMANDS = ['migrate', 'reset', 'seed', 'status', 'wipe'] as const
+const DB_COMMANDS = ['migrate', 'reset', 'rollback', 'seed', 'status', 'wipe'] as const
 const HELP_COMMANDS = [
+  'assets',
   'completion',
   'db',
   'doctor',
@@ -18,6 +19,7 @@ const HELP_COMMANDS = [
   'version',
 ] as const
 const ROOT_COMMANDS = [
+  'assets',
   'completion',
   'db',
   'doctor',
@@ -225,6 +227,10 @@ function completeCommand(
     return completeHelp(tokens, currentWord, usedGlobalFlags)
   }
 
+  if (command === 'assets') {
+    return completeAssets(tokens, currentWord, usedGlobalFlags)
+  }
+
   if (command === 'new') {
     return completeNew(tokens, currentWord, usedGlobalFlags)
   }
@@ -261,6 +267,30 @@ function completeCommand(
   return completeValues([], currentWord)
 }
 
+function completeAssets(
+  tokens: string[],
+  currentWord: string,
+  usedGlobalFlags: Set<string>,
+): CompletionResult {
+  let filteredTokens = filterGlobalCommandTokens(tokens, usedGlobalFlags)
+  if (filteredTokens == null) {
+    return completeValues([], currentWord)
+  }
+
+  if (filteredTokens.length === 0) {
+    return completeValues(withHelpFlags(['inspect'], usedGlobalFlags), currentWord)
+  }
+
+  let [subcommand, ...rest] = filteredTokens
+  if (subcommand !== 'inspect' || rest.length > 0) {
+    return completeValues([], currentWord)
+  }
+
+  return currentWord.startsWith('-')
+    ? completeValues(withHelpFlags([], usedGlobalFlags), currentWord)
+    : { mode: 'files' }
+}
+
 function completeTest(
   tokens: string[],
   currentWord: string,
@@ -533,6 +563,16 @@ function completeDb(
     )
   }
 
+  if (subcommand === 'rollback') {
+    return completeDbOptions(
+      rest,
+      currentWord,
+      usedGlobalFlags,
+      ['--dry-run'],
+      ['--connection-env', '--journal-table', '--migrations', '--step', '--to'],
+    )
+  }
+
   if (subcommand === 'wipe') {
     return completeDbOptions(rest, currentWord, usedGlobalFlags, ['--force'], ['--connection-env'])
   }

package/src/lib/database-command.ts

@@ -1,22 +1,26 @@
 import type { RemixDbAdapterConfig } from './remix-config.ts'
 
-export type DatabaseCommand = 'migrate' | 'reset' | 'seed' | 'status' | 'wipe'
+export type DatabaseCommand = 'migrate' | 'reset' | 'rollback' | 'seed' | 'status' | 'wipe'
 
 export interface DatabaseCommandInvocation {
   command: DatabaseCommand
   connectionEnv?: string
+  dryRun?: boolean
   journalTable?: string
   migrations?: string
   seed?: string
+  step?: number
   to?: string
 }
 
 export interface DatabaseCommandPlan {
   adapter: RemixDbAdapterConfig
   command: DatabaseCommand
+  dryRun?: boolean
   journalTable?: string
   migrations?: string
   seed?: string
+  step?: number
   to?: string
 }
 
@@ -24,6 +28,7 @@ export function isDatabaseCommand(value: unknown): value is DatabaseCommand {
   return (
     value === 'migrate' ||
     value === 'reset' ||
+    value === 'rollback' ||
     value === 'seed' ||
     value === 'status' ||
     value === 'wipe'

package/src/lib/errors.ts

@@ -28,6 +28,11 @@ export const CLI_ERROR_DEFINITIONS = {
     title: 'Could not determine an app name',
     fix: 'Pass --app-name or choose a target directory name that can become an app name.',
   },
+  assetsConfigRequired: {
+    code: 'RMX_ASSETS_CONFIG_REQUIRED',
+    title: 'Asset configuration is required',
+    fix: 'Add an assets configuration to remix.json.',
+  },
   dbConfigRequired: {
     code: 'RMX_DB_CONFIG_REQUIRED',
     title: 'Database configuration is required',
@@ -194,6 +199,12 @@ export function appNameUnavailable(targetDir?: string): UsageError {
   })
 }
 
+export function assetsConfigRequired(): CliError {
+  return createCliError(CLI_ERROR_DEFINITIONS.assetsConfigRequired, {
+    message: 'Asset configuration is missing from remix.json.',
+  })
+}
+
 export function dbConfigRequired(filePath: string): CliError {
   return createCliError(CLI_ERROR_DEFINITIONS.dbConfigRequired, {
     context: { filePath },

package/src/lib/remix-config.ts

@@ -1,5 +1,7 @@
 import * as fs from 'node:fs/promises'
 import * as path from 'node:path'
+import * as process from 'node:process'
+import { fileURLToPath } from 'node:url'
 import {
   findNodeAtLocation,
   getNodeValue,
@@ -8,8 +10,10 @@ import {
   type Node as JsonNode,
   type ParseError,
 } from 'jsonc-parser'
+import type { AssetServerOptions } from '@remix-run/assets'
 import type { RemixTestPool } from '@remix-run/test/cli'
 
+import { findAppRoot } from './app-root.ts'
 import { invalidRemixConfig, remixConfigNotFound } from './errors.ts'
 
 const reporters = ['spec', 'files', 'tap', 'dot'] as const
@@ -21,12 +25,29 @@ type TestPool = RemixTestPool
 type TestType = (typeof testTypes)[number]
 type JsonPath = Array<number | string>
 
+/** Validated configuration loaded from a Remix project config file. */
 export interface RemixConfig {
+  /** Shared asset mapping and browser access configuration. */
+  assets?: RemixAssetsConfig
+  /** Database command configuration. */
   db?: RemixDbCommandConfig
+  /** Project health-check configuration. */
   doctor?: RemixDoctorCommandConfig
+  /** Test runner configuration. */
   test?: RemixTestCommandConfig
 }
 
+/** JSON-compatible asset server configuration loaded from `remix.json`. */
+export interface RemixAssetsConfig extends Pick<
+  AssetServerOptions,
+  'allowFiles' | 'allowPackages' | 'basePath' | 'denyFiles' | 'mounts'
+> {
+  /** Leaf file asset configuration. */
+  files?: Pick<NonNullable<AssetServerOptions['files']>, 'extensions'>
+  /** Absolute root directory used to resolve asset file paths. */
+  rootDir: string
+}
+
 export type RemixDbString = string | { env: string; default?: string }
 
 export type RemixDbAdapterConfig =
@@ -99,6 +120,36 @@ interface ConfigSource {
   text: string
 }
 
+/**
+ * Loads the nearest Remix project configuration or an explicitly selected config file.
+ *
+ * @param from A config file or directory from which to search upward for `remix.json`. Defaults to
+ * `process.cwd()`.
+ * @returns The validated Remix project configuration, or an empty object when no config is found.
+ */
+export async function loadConfig(from: string | URL = process.cwd()): Promise<RemixConfig> {
+  let fromPath = path.resolve(from instanceof URL ? fileURLToPath(from) : from)
+  let stat
+
+  try {
+    stat = await fs.stat(fromPath)
+  } catch (error) {
+    if (isNodeError(error) && error.code === 'ENOENT') throw remixConfigNotFound(fromPath)
+    throw error
+  }
+
+  if (stat.isFile()) {
+    return loadRemixConfig(path.dirname(fromPath), path.basename(fromPath))
+  }
+
+  if (!stat.isDirectory()) {
+    throw new TypeError(`Expected a Remix config file or directory: ${fromPath}`)
+  }
+
+  let configDir = await findAppRoot(fromPath, 'remix.json')
+  return configDir === null ? {} : loadRemixConfig(configDir, undefined)
+}
+
 export async function loadRemixConfig(
   cwd: string,
   configPath: string | undefined,
@@ -153,7 +204,7 @@ function parseConfig(
   cwd: string,
 ): RemixConfig {
   let object = requireObject(value, source, [])
-  requireKnownProperties(object, ['$schema', 'db', 'doctor', 'test'], source, [])
+  requireKnownProperties(object, ['$schema', 'assets', 'db', 'doctor', 'test'], source, [])
 
   if (object.$schema !== undefined) {
     requireString(object.$schema, source, ['$schema'])
@@ -161,6 +212,10 @@ function parseConfig(
 
   let config: RemixConfig = {}
 
+  if (object.assets !== undefined) {
+    config.assets = parseAssetsConfig(object.assets, source, configDir)
+  }
+
   if (object.db !== undefined) {
     config.db = parseDbConfig(object.db, source, configDir)
   }
@@ -176,6 +231,54 @@ function parseConfig(
   return config
 }
 
+function parseAssetsConfig(
+  value: unknown,
+  source: ConfigSource,
+  configDir: string,
+): RemixAssetsConfig {
+  let objectPath = ['assets']
+  let object = requireObject(value, source, objectPath)
+  requireKnownProperties(
+    object,
+    ['allowFiles', 'allowPackages', 'basePath', 'denyFiles', 'files', 'mounts', 'rootDir'],
+    source,
+    objectPath,
+  )
+
+  let config: RemixAssetsConfig = {
+    allowFiles: requireStringArray(object.allowFiles, source, [...objectPath, 'allowFiles']),
+    basePath: requireString(object.basePath, source, [...objectPath, 'basePath']),
+    rootDir: path.resolve(
+      configDir,
+      optionalString(object.rootDir, source, [...objectPath, 'rootDir']) ?? '.',
+    ),
+  }
+  let allowPackages = optionalStringArray(object.allowPackages, source, [
+    ...objectPath,
+    'allowPackages',
+  ])
+  let denyFiles = optionalStringArray(object.denyFiles, source, [...objectPath, 'denyFiles'])
+  let mounts =
+    object.mounts === undefined
+      ? undefined
+      : requireStringRecord(object.mounts, source, [...objectPath, 'mounts'])
+
+  if (allowPackages !== undefined) config.allowPackages = allowPackages
+  if (denyFiles !== undefined) config.denyFiles = denyFiles
+  if (mounts !== undefined) config.mounts = mounts
+
+  if (object.files !== undefined) {
+    let filesPath = [...objectPath, 'files']
+    let files = requireObject(object.files, source, filesPath)
+    requireKnownProperties(files, ['extensions'], source, filesPath)
+    config.files = {
+      extensions: requireStringArray(files.extensions, source, [...filesPath, 'extensions']),
+    }
+  }
+
+  return config
+}
+
 function parseDbConfig(
   value: unknown,
   source: ConfigSource,
@@ -507,15 +610,36 @@ function requireString(value: unknown, source: ConfigSource, propertyPath: JsonP
   return value
 }
 
+function requireStringArray(
+  value: unknown,
+  source: ConfigSource,
+  propertyPath: JsonPath,
+): string[] {
+  if (!Array.isArray(value)) throwConfigError(source, propertyPath, 'Expected an array of strings')
+  return value.map((item, index) => requireString(item, source, [...propertyPath, index]))
+}
+
+function requireStringRecord(
+  value: unknown,
+  source: ConfigSource,
+  propertyPath: JsonPath,
+): Record<string, string> {
+  let object = requireObject(value, source, propertyPath)
+  return Object.fromEntries(
+    Object.entries(object).map(([key, item]) => [
+      key,
+      requireString(item, source, [...propertyPath, key]),
+    ]),
+  )
+}
+
 function optionalStringArray(
   value: unknown,
   source: ConfigSource,
   propertyPath: JsonPath,
 ): string[] | undefined {
   if (value === undefined) return undefined
-  if (!Array.isArray(value)) throwConfigError(source, propertyPath, 'Expected an array of strings')
-
-  return value.map((item, index) => requireString(item, source, [...propertyPath, index]))
+  return requireStringArray(value, source, propertyPath)
 }
 
 function optionalEnum<const value extends string>(

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

@@ -122,8 +122,9 @@ When code could live in multiple places:
 
 ### Response Rendering And Utilities
 
-- Treat response rendering as action-layer code: modules that return `Response`, choose HTTP status or headers, call `redirect(...)`, or call the local `render(...)` helper belong in `app/actions`
-- Keep `app/actions/render.tsx` small; it should adapt `remix/ui/server` output to `createHtmlResponse(...)`. Route-specific response assembly can live in flat action modules, but directories under `app/actions/` must still match route-map keys
+- Install `render()` from `remix/middleware/render` in the router middleware stack for normal Remix UI applications. Pass `render({ assets })` when source-based `clientEntry()` modules need browser URLs
+- Render UI responses at the action boundary with `context.render(node, init)`. Status, headers, and other response policy remain explicit in the action
+- Use `renderWith(...)`, `renderToStream(...)`, and `createHtmlResponse(...)` only when an application intentionally owns a custom renderer contract or replaces the standard UI response pipeline
 - Put pure support code in focused `app/utils/<topic>.ts` modules. Formatting, MIME classification, path parsing, sorting, and normalization should be testable without a router, request context, or `Response`, and should not import from `app/actions`, `remix/ui/server`, or `remix/response/*`
 - Do not introduce page-data intermediary shapes only to keep route-specific renderers away from `render(...)`; keep response assembly in actions and extract only the pure helpers
 
@@ -210,7 +211,7 @@ Use this map to find the right package quickly. Each entry says what the package
 - `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` — browser asset server. Use for `createAssetServer` when serving compiled scripts and styles, getting public hrefs, emitting preloads, and wiring browser HMR. Configure a `basePath`; use optional directory `mounts` configuration when the default mounts that serve `app` at `app` and `node_modules` at `npm` are not enough; 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
@@ -243,13 +244,13 @@ Use this map to find the right package quickly. Each entry says what the package
 - `remix/session-storage/redis` — Redis-backed storage. Use for multi-process or multi-host deployments
 - `remix/session-storage/memcache` — Memcache-backed storage. Same multi-host use case as Redis
 - `remix/cookie` — `createCookie` for plain signed/unsigned cookies. Use for non-sensitive preferences where the client is allowed to control the value (theme, locale, dismissed banner). For state where tampering matters, prefer `remix/session`
-- `remix/auth` — credentials, OAuth, OIDC, and Atmosphere providers. Use to define how identity is verified, start/finish external login, and refresh stored OAuth/OIDC token bundles with `refreshExternalAuth(...)`
+- `remix/auth` — credentials, OAuth, and OIDC providers. Use to define how identity is verified, start/finish external login, and refresh stored OAuth/OIDC token bundles with `refreshExternalAuth(...)`
 - `remix/middleware/auth` — `auth({ schemes })`, `requireAuth`, the `Auth` context key. Use to resolve identity into the request context and to gate routes
 
 ### UI, Hydration, and Browser Behavior
 
 - `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/server` — low-level server rendering with `renderToStream` and `renderToString`. Normal apps should install `render()` from `remix/middleware/render`; use this subpath for custom pipelines and static string rendering
 - `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
@@ -264,6 +265,7 @@ Use this map to find the right package quickly. Each entry says what the package
 
 ### Middleware
 
+- `remix/middleware/render` — `render({ assets?, onError? })` for the standard Remix UI renderer and `renderWith(factory)` for custom request-scoped renderers. Normal UI actions return `context.render(node, init)`
 - `remix/middleware/static` — `staticFiles(dir)`. Use to serve files from `public/` exactly as they exist on disk
 - `remix/middleware/form-data` — `formData()`. Use to parse `FormData` once and expose it via `get(FormData)` instead of calling `await request.formData()` in each action
 - `remix/form-data-parser` — lower-level `parseFormData`, `FileUpload`. Use when implementing custom upload handlers. Upload handler errors propagate directly

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

@@ -4,7 +4,7 @@
 
 How to serve browser scripts and styles from source. Read this when the task involves:
 
-- Configuring `createAssetServer` (`basePath`, `fileMap`, `allowFiles`, `allowPackages`, `denyFiles`, fingerprinting, compiler options)
+- Configuring `createAssetServer` (`basePath`, `mounts`, `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
 - Enabling browser HMR for source-served modules
@@ -29,13 +29,9 @@ export const routes = route({
   assets: get('/assets/*path'),
 })
 
-let assetServer = createAssetServer({
+let assets = createAssetServer({
   basePath: '/assets',
   rootDir: process.cwd(),
-  fileMap: {
-    'app/*path': 'app/*path',
-    'node_modules/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   denyFiles: ['app/**/*.test.*'],
@@ -52,7 +48,7 @@ let assetServer = createAssetServer({
 export default createController(routes, {
   actions: {
     async assets({ request }) {
-      return (await assetServer.fetch(request)) ?? new Response('Not Found', { status: 404 })
+      return (await assets.fetch(request)) ?? new Response('Not Found', { status: 404 })
     },
   },
 })
@@ -69,8 +65,8 @@ export default createController(routes, {
 - `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.
-- Keep the same wildcard params on both sides of a `fileMap` entry so import rewriting can map source files back to public URLs.
+- The default mounts serve the `app` directory at `/app` and `node_modules` at `/npm`. Use `mounts` to replace these defaults when the app needs different public or root-relative directory roots.
+- Mounts preserve every path segment beneath their public and filesystem roots. Do not configure overlapping public or filesystem roots.
 - CSS files are compiled and served alongside scripts. Local CSS `@import` rules are rewritten and fingerprinted with the same asset server routing rules.
 
 ## Rendering HTML
@@ -78,13 +74,13 @@ 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/actions/public/entry.ts')
-let entryPreloads = await assetServer.getPreloads('app/actions/public/entry.ts')
+let entryHref = await assets.getHref('app/actions/public/entry.ts')
+let entryPreloads = await assets.getPreloads('app/actions/public/entry.ts')
 ```
 
 Use this when rendering documents or layouts that boot browser behavior with a known client entry.
 
-When resolving hydrated client entries during server rendering, pass the source entry ID from `clientEntry(import.meta.url, ...)` to `getHref()` and `getPreloads()` inside `resolveClientEntry`. Return those preload hrefs through the entry's `preloads` property so the browser can fetch the module graph without walking it serially. Keep this resolution in the shared render helper rather than hard-coding public asset URLs in source-owned component modules.
+For normal Remix applications, pass the asset server to `render({ assets })` from `remix/middleware/render`. The middleware resolves source entry IDs from `clientEntry(import.meta.url, ...)` with `getHref()` and `getPreloads()` and applies the UI renderer's explicit-hash or named-component export rules. Use a custom `resolveClientEntry` callback only when building a custom rendering pipeline.
 
 ## Development vs Deployment
 
@@ -117,7 +113,6 @@ 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,

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

@@ -247,7 +247,6 @@ function logout(context) {
 
 ```typescript
 import {
-  createAtmosphereAuthProvider,
   createGoogleAuthProvider,
   createGitHubAuthProvider,
   startExternalAuth,
@@ -267,21 +266,8 @@ let githubProvider = createGitHubAuthProvider({
   clientSecret: process.env.GITHUB_CLIENT_SECRET,
   redirectUri: new URL(routes.auth.github.callback.href(), origin),
 })
-
-let atmosphereSessionSecret = process.env.ATMOSPHERE_SESSION_SECRET
-if (!atmosphereSessionSecret && process.env.NODE_ENV !== 'test') {
-  throw new Error('ATMOSPHERE_SESSION_SECRET is required')
-}
-
-let atmosphereProvider = createAtmosphereAuthProvider({
-  clientId: 'https://app.example.com/oauth/client-metadata.json',
-  redirectUri: new URL(routes.auth.atmosphere.callback.href(), origin),
-  sessionSecret: atmosphereSessionSecret ?? 'test-only-secret',
-})
 ```
 
-For Atmosphere-compatible atproto OAuth, create the provider once, call `atmosphereProvider.prepare(handleOrDid)` before `startExternalAuth(...)`, then pass the same module-scope provider to `finishExternalAuth(...)` and `refreshExternalAuth(...)`.
-
 ### OAuth controller
 
 ```typescript
@@ -318,7 +304,7 @@ export default createController(routes.auth.google, {
 
 ### Refresh stored provider tokens
 
-Use `refreshExternalAuth(provider, tokens)` when an app has stored OAuth/OIDC tokens and needs a fresh access token from a refresh token. Built-in OIDC providers, X, and Atmosphere support refresh-token exchange. If the provider does not rotate the refresh token, the refreshed bundle preserves the current one.
+Use `refreshExternalAuth(provider, tokens)` when an app has stored OAuth/OIDC tokens and needs a fresh access token from a refresh token. Built-in OIDC providers and X support refresh-token exchange. If the provider does not rotate the refresh token, the refreshed bundle preserves the current one.
 
 ```typescript
 async function refreshGoogleTokens({ get }) {

package/template/.agents/skills/remix/references/component-model.md

@@ -210,7 +210,7 @@ function ThemedContent(handle: Handle) {
 For granular updates without re-rendering the full subtree, use `TypedEventTarget`:
 
 ```tsx
-import { TypedEventTarget, addEventListeners } from 'remix/ui'
+import { TypedEventTarget } from 'remix/ui'
 
 class Theme extends TypedEventTarget<{ change: Event }> {
   #value: 'light' | 'dark' = 'light'
@@ -239,32 +239,34 @@ function ThemeProvider(handle: Handle<{ children?: RemixNode }, Theme>) {
 
 function ThemedContent(handle: Handle) {
   let theme = handle.context.get(ThemeProvider)
-  addEventListeners(theme, handle.signal, {
-    change() {
-      handle.update()
-    },
-  })
+  theme.addEventListener('change', () => handle.update(), { signal: handle.signal })
   return () => <div>Theme: {theme.value}</div>
 }
 ```
 
 ## Global Events
 
-Use `addEventListeners(target, handle.signal, listeners)` to listen to global targets with automatic cleanup when the component disconnects:
+Use `on(...)` for element events. For browser globals such as `window` or `document`, schedule setup with `handle.queueTask()` and pass `handle.signal` to `addEventListener()` so the listener is removed when the component disconnects:
 
 ```tsx
-import { addEventListeners, type Handle } from 'remix/ui'
+import type { Handle } from 'remix/ui'
 
-function ResizeTracker(handle: Handle) {
-  let width = window.innerWidth
+function ViewportWidth(handle: Handle) {
+  let width: number | undefined
 
-  addEventListeners(window, handle.signal, {
-    resize() {
-      width = window.innerWidth
-      handle.update()
-    },
+  handle.queueTask(() => {
+    width = window.innerWidth
+    window.addEventListener(
+      'resize',
+      () => {
+        width = window.innerWidth
+        handle.update()
+      },
+      { signal: handle.signal },
+    )
+    handle.update()
   })
 
-  return () => <div>{width}</div>
+  return () => <div>{width === undefined ? 'Measuring…' : `${width}px`}</div>
 }
 ```