npm - @remix-run/cli - Versions diffs - 0.1.0 → 0.3.0 - Mend

@remix-run/cli 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (110) hide show

package/README.md +0 -3
package/dist/lib/bootstrap-project.d.ts.map +1 -1
package/dist/lib/bootstrap-project.js +32 -9
package/dist/lib/cli.d.ts +29 -0
package/dist/lib/cli.d.ts.map +1 -1
package/dist/lib/cli.js +33 -14
package/dist/lib/commands/completion.d.ts.map +1 -1
package/dist/lib/commands/completion.js +5 -1
package/dist/lib/commands/doctor.js +18 -18
package/dist/lib/commands/help.d.ts.map +1 -1
package/dist/lib/commands/help.js +9 -33
package/dist/lib/commands/routes.js +3 -3
package/dist/lib/commands/test.d.ts +1 -1
package/dist/lib/commands/test.d.ts.map +1 -1
package/dist/lib/commands/test.js +8 -4
package/dist/lib/completion.d.ts.map +1 -1
package/dist/lib/completion.js +4 -106
package/dist/lib/controller-files.d.ts +0 -1
package/dist/lib/controller-files.d.ts.map +1 -1
package/dist/lib/controller-files.js +3 -5
package/dist/lib/controller-ownership.d.ts +9 -9
package/dist/lib/controller-ownership.d.ts.map +1 -1
package/dist/lib/controller-ownership.js +56 -91
package/dist/lib/doctor/controller-findings.d.ts +1 -1
package/dist/lib/doctor/controller-findings.d.ts.map +1 -1
package/dist/lib/doctor/controller-findings.js +15 -87
package/dist/lib/doctor/controller-fix-plans.d.ts.map +1 -1
package/dist/lib/doctor/controller-fix-plans.js +13 -24
package/dist/lib/doctor/controller-placeholders.d.ts +2 -3
package/dist/lib/doctor/controller-placeholders.d.ts.map +1 -1
package/dist/lib/doctor/controller-placeholders.js +18 -149
package/dist/lib/doctor/controllers.js +1 -1
package/dist/lib/doctor/project.js +60 -52
package/dist/lib/doctor/types.d.ts +2 -2
package/dist/lib/doctor/types.d.ts.map +1 -1
package/dist/lib/errors.d.ts +0 -6
package/dist/lib/errors.d.ts.map +1 -1
package/dist/lib/errors.js +0 -11
package/dist/lib/load-route-map-worker.js +17 -9
package/dist/lib/route-map.d.ts +1 -1
package/dist/lib/route-map.d.ts.map +1 -1
package/dist/lib/route-map.js +29 -17
package/package.json +4 -5
package/src/lib/bootstrap-project.ts +39 -13
package/src/lib/cli.ts +46 -15
package/src/lib/commands/completion.ts +6 -1
package/src/lib/commands/doctor.ts +18 -21
package/src/lib/commands/help.ts +9 -43
package/src/lib/commands/routes.ts +3 -3
package/src/lib/commands/test.ts +10 -4
package/src/lib/completion.ts +4 -151
package/src/lib/controller-files.ts +4 -8
package/src/lib/controller-ownership.ts +78 -141
package/src/lib/doctor/controller-findings.ts +20 -97
package/src/lib/doctor/controller-fix-plans.ts +13 -29
package/src/lib/doctor/controller-placeholders.ts +17 -189
package/src/lib/doctor/controllers.ts +1 -1
package/src/lib/doctor/project.ts +60 -52
package/src/lib/doctor/types.ts +1 -5
package/src/lib/errors.ts +0 -12
package/src/lib/load-route-map-worker.ts +19 -10
package/src/lib/route-map.ts +61 -16
package/template/.agents/skills/remix/SKILL.md +588 -0
package/template/.agents/skills/remix/references/animate-elements.md +195 -0
package/template/.agents/skills/remix/references/assets-and-browser-modules.md +130 -0
package/template/.agents/skills/remix/references/auth-and-sessions.md +443 -0
package/template/.agents/skills/remix/references/component-model.md +282 -0
package/template/.agents/skills/remix/references/create-mixins.md +158 -0
package/template/.agents/skills/remix/references/data-and-validation.md +379 -0
package/template/.agents/skills/remix/references/hydration-frames-navigation.md +297 -0
package/template/.agents/skills/remix/references/middleware-and-server.md +233 -0
package/template/.agents/skills/remix/references/mixins-styling-events.md +213 -0
package/template/.agents/skills/remix/references/routing-and-controllers.md +391 -0
package/template/.agents/skills/remix/references/testing-patterns.md +172 -0
package/{bootstrap → template}/AGENTS.md +13 -8
package/template/README.md +29 -0
package/template/app/actions/controller.tsx +18 -0
package/template/app/assets/entry.ts +8 -0
package/template/app/assets/prompt-button.tsx +163 -0
package/template/app/assets.ts +20 -0
package/template/app/middleware/render.tsx +43 -0
package/template/app/router.ts +20 -0
package/template/app/routes.ts +6 -0
package/template/app/ui/document.tsx +33 -0
package/template/app/ui/scaffold-home-page.tsx +527 -0
package/template/gitignore +4 -0
package/{bootstrap → template}/package.json +5 -6
package/template/public/favicon.svg +11 -0
package/{bootstrap → template}/server.ts +4 -5
package/{bootstrap → template}/tsconfig.json +3 -3
package/bootstrap/README.md +0 -27
package/bootstrap/app/controllers/auth.tsx +0 -21
package/bootstrap/app/controllers/home.tsx +0 -26
package/bootstrap/app/router.ts +0 -10
package/bootstrap/app/routes.ts +0 -6
package/bootstrap/app/ui/document.tsx +0 -21
package/bootstrap/app/ui/layout.tsx +0 -22
package/bootstrap/app/utils/render.tsx +0 -7
package/dist/lib/commands/skills.d.ts +0 -6
package/dist/lib/commands/skills.d.ts.map +0 -1
package/dist/lib/commands/skills.js +0 -222
package/dist/lib/skills-cache.d.ts +0 -19
package/dist/lib/skills-cache.d.ts.map +0 -1
package/dist/lib/skills-cache.js +0 -89
package/dist/lib/skills.d.ts +0 -30
package/dist/lib/skills.d.ts.map +0 -1
package/dist/lib/skills.js +0 -441
package/src/lib/commands/skills.ts +0 -306
package/src/lib/skills-cache.ts +0 -140
package/src/lib/skills.ts +0 -706

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

@@ -0,0 +1,588 @@
+---
+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.
+---
+# Build a Remix App
+Use this skill for end-to-end Remix app work. This skill helps you choose the right layer
+first, reach for the right package, and avoid the most common Remix-specific mistakes.
+## Full Package Documentation
+This skill is the quick guide. When you need fuller API documentation, examples, or package-specific
+details for a `remix/*` subpath, first look for a README next to the relevant generated source file
+in the published `remix` package:
+`node_modules/remix/src/<subpath>/README.md`. If that README does not exist, look for the nearest
+parent README because some subpaths share their parent package documentation.
+Examples:
+- `remix/router` -> `node_modules/remix/src/fetch-router/README.md`
+- `remix/ui/button` -> `node_modules/remix/src/ui/button/README.md`
+## What Remix Is
+Remix 3 is a server-first web framework built on Web APIs such as `Request`, `Response`, `URL`,
+and `FormData`. All packages ship from a single npm package, `remix`, and are imported via
+subpath. There is no top-level `remix` import.
+A Remix app has four main pieces:
+- **Routes** in `app/routes.ts` define the typed URL contract and power `href()` generation.
+- **Controllers** in `app/actions` implement that contract and return `Response` objects.
+- **Middleware** composes request lifecycle behavior and populates typed context via
+  `context.set(Key, value)`.
+- **Components** render UI with `remix/ui`. This is not React. A component receives a
+  `handle`, reads current props from `handle.props`, and returns a render function.
+## When To Use This Skill
+Use this skill for:
+- new features or refactors that touch routing, controllers, middleware, data, auth, sessions, UI,
+  or tests
+- reviewing Remix app code for correctness, architecture, or framework usage
+- answering "how should this be structured in Remix?" questions
+- finding the right package, reference doc, or default pattern for a task
+## Load Only The References You Need
+Classify the task first, then load the smallest useful reference set. Each reference file starts
+with a "What This Covers" section that lists the topics inside it — read that first to confirm
+the file is relevant before reading the rest.
+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`               |
+Common bundles:
+- **Form or CRUD feature** -> routing, data and validation, testing; add auth if user-specific
+- **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
+- **File upload** -> middleware and server, data and validation, testing
+- **Navigation or frames** -> hydration, frames, navigation
+## Default Workflow
+1. **Classify the change.** Decide whether it changes the route contract, request lifecycle, data
+   model, auth or session behavior, or only UI.
+2. **Start from the server contract.** Add or update `app/routes.ts` before wiring handlers or UI.
+3. **Put code in the narrowest owner.** Favor route-local code first, then promote only when reuse
+   is real.
+4. **Make the server path correct before adding browser behavior.** A route should return the right
+   `Response` via `router.fetch(...)` before you add `clientEntry(...)`, animations, or DOM
+   effects.
+5. **Add middleware deliberately.** Keep fast-exit middleware early and request-enriching
+   middleware later. Export a typed `AppContext` from the root middleware stack and use it in
+   controllers.
+6. **Validate input at the boundary.** Parse and validate `Request`, `FormData`, params, cookies,
+   and external payloads before they reach rendering or persistence logic.
+7. **Hydrate only when necessary.** Prefer server-rendered UI. Use `clientEntry(...)` and `run(...)`
+   only for real browser interactivity or browser-only APIs.
+8. **Test the narrowest meaningful layer.** Prefer router tests for route behavior. Use component
+   tests when the behavior is truly interactive or DOM-specific.
+9. **Finish with verification.** Re-read the route flow, confirm auth and authorization boundaries,
+   and run the smallest relevant test and typecheck loop.
+## Project Layout
+Use these root directories consistently:
+- `app/` for runtime application code
+- `db/` for migrations and local database files
+- `public/` for static assets served as-is
+- `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
+- `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
+- `router.ts` for router setup and wiring
+### Placement Precedence
+When code could live in multiple places:
+1. Put it in the narrowest owner first.
+2. If it belongs to one route, keep it with that route.
+3. If it is shared UI across route areas, move it to `app/ui/`.
+4. If it is request lifecycle setup, keep it in `app/middleware/`.
+5. If it is schema, query, persistence, or startup data logic, keep it in `app/data/`.
+6. Use `app/utils/` only as a last resort for truly cross-layer helpers.
+### Route Ownership
+- Put top-level leaf actions in `app/actions/controller.tsx`
+- A controller's `actions` object contains only direct leaf route keys from the route map passed to
+  `router.map(...)`
+- Add `app/actions/<route-key>/controller.tsx` for each nested route map that needs actions or
+  middleware, and map it explicitly with `router.map(routes.<routeKey>, controller)`
+- Name directories under `app/actions/` after route-map keys, not URL path segments
+- Keep route-local UI and helpers next to the controller that owns them
+- Move shared cross-route UI to `app/ui/`
+- If a top-level leaf grows into a route map, move its handler into the nested route-key
+  controller and update `app/router.ts` to map that route map explicitly
+### 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
+- 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
+### Layout Anti-Patterns
+- Do not create `app/lib/` as a generic dumping ground
+- Do not create `app/components/` as a second shared UI bucket when `app/ui/` already owns that
+  role
+- Do not create `app/controllers/`; Remix app route handlers live under `app/actions/`
+- Do not put shared cross-route UI in `app/actions/`
+- Do not create standalone root action files; put root route actions in `app/actions/controller.tsx`
+- Do not put nested route-map keys in a controller's `actions`
+- Do not register normal app leaf routes directly in `app/router.ts` when they belong in a
+  controller
+- Do not rely on middleware from one controller to protect another controller; map middleware
+  explicitly in each controller that needs it
+- Do not put middleware or persistence helpers in `app/utils/` when they have a clearer home
+## Core Remix Rules
+- Import from `remix/<subpath>`, never `import { ... } from 'remix'`
+- Treat `app/routes.ts` as the source of truth for URLs. Use `routes.<name>.href(...)` for
+  redirects, links, tests, and internal URL construction
+- Controllers should return explicit `Response` objects, including redirects, 404s, and
+  validation failures. At the route boundary, prefer returning a `Response` for expected outcomes
+  (validation errors, conflicts, not found) over throwing for control flow
+- `router.map(routes, controller)` maps only the direct leaf routes in `routes`; nested route maps
+  must be mapped with their own explicit controllers
+- 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 root 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
+- Outside actions and controllers, only use `getContext()` when `asyncContext()` is in the
+  middleware stack
+- Remix Component is not React: 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
+- Hydrated `clientEntry(...)` props must be serializable. Do not pass functions, class instances, or
+  opaque runtime objects
+## Security And Session Defaults
+- Never ship demo secrets. In non-test environments, require session and provider secrets from the
+  environment and fail fast if they are missing
+- Use hardened cookies: `httpOnly` always, `sameSite` by default, and `secure` when serving over
+  HTTPS
+- Regenerate session IDs on login, logout, and privilege changes
+- Use `requireAuth()` to protect authenticated route areas, but still authorize resource ownership
+  inside handlers and data writes
+- Add CSRF protection when browser forms mutate state using cookie-backed sessions
+- Add CORS only for endpoints that must be called cross-origin. Prefer same-origin by default
+- Prefer JSX or `remix/html-template` for HTML generation so escaping stays correct
+- Validate uploads for size, type, and destination. Treat filenames and content as untrusted input
+## Testing Defaults
+- Prefer server and router tests first. Drive the app with `router.fetch(new Request(...))` and
+  assert on the returned `Response`
+- Keep controller tests shaped like controllers: root route behavior belongs in
+  `app/actions/controller.test.ts(x)`, and nested route-map behavior belongs beside that route-key
+  controller
+- Build a fresh router per test or per suite so sessions, in-memory storage, and database state
+  stay isolated
+- Use `routes.<name>.href(...)` in tests so URLs stay coupled to the route contract
+- For auth or session scenarios, use a test cookie and `createMemorySessionStorage()` instead of
+  production storage
+- Co-locate tests for pure `app/utils` helpers beside their modules. Test response behavior through
+  router or controller tests
+- Use component tests only for interactive or DOM-specific behavior. Render with `createRoot(...)`,
+  interact with the real DOM, and call `root.flush()` between steps
+- Prefer one representative behavior test over many repetitive assertion variants
+## Common Mistakes To Avoid
+- Treating Remix Component like React and reaching for hooks or implicit rerendering
+- Importing from a top-level `remix` entry instead of a subpath
+- Adding `clientEntry(...)` before the server-rendered route behavior is correct
+- Passing non-serializable props into `clientEntry(...)`
+- Calling `getContext()` without `asyncContext()` in the middleware stack
+- Getting middleware order wrong; fast exits like static files belong early, request enrichment later
+- Skipping boundary validation and trusting raw `FormData`, params, cookies, or external payloads
+- Letting route-local domain errors leak out of the controller. Translate expected outcomes
+  (validation, conflicts, not-found) into the HTTP `Response` the route means to return rather than
+  throwing a custom `Error` subclass and catching it elsewhere
+- Reaching for `createCookie` when a tamper-sensitive or server-managed per-browser fact really
+  wants `remix/session`. If editing the value would be a bug, use a session
+- Building a JSON-only RPC layer when a normal form POST, redirect, or resource route would be
+  simpler. Fetch-from-the-client is a layer on top of sound route behavior, not a replacement for
+  it
+- Treating JSON state endpoints and `<Frame>` reloads as mutually exclusive patterns. Pick the
+  lightest sync mechanism that fits the UX; small widgets may reasonably poll a JSON endpoint
+- Assuming authentication is enough without per-resource authorization checks
+- Dropping shared code into vague buckets like `utils.ts`, `helpers.ts`, or `common.ts` when
+  ownership is known
+- Recreating the old `app/controllers` or standalone root action file layout instead of using
+  controllers under `app/actions`
+- Putting nested route-map keys inside a controller `actions` object. Map nested route maps
+  explicitly in `app/router.ts`
+- Treating direct `router.get(...)`/`router.post(...)` registrations as the default app structure
+  instead of using controllers
+- Assuming controller middleware applies to controllers registered for nested route maps
+- Writing only component tests for a feature whose main behavior is really an HTTP route concern
+## Package Map
+Use this map to find the right package quickly. Each entry says what the package is for, not just
+what it exports. Open the linked reference file when you need full examples.
+### Routing, Server, and Responses
+- `remix/router` — the router itself. Use for `createRouter`, controller and 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/node-serve` — managed high-performance Node server. Use `serve` when you want Remix to
+  manage the server lifecycle, TLS options, or uWebSockets.js setup around a Fetch handler
+- `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/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`
+- `remix/response/compress` — `compressResponse`. Use when compressing one-off responses outside
+  the global `compression()` middleware
+- `remix/response/file` — file-download responses. Use for `Content-Disposition: attachment`
+  responses
+- `remix/route-pattern` — low-level URL matching and generation. Use `RoutePattern` or
+  `createMatcher` when working with raw patterns outside the router. `href(...)` encodes pathname
+  and search params for you, and `match(...)` returns decoded params
+- `remix/route-pattern/specificity` — pattern ranking helpers. Use only when building custom
+  matcher or reporting logic outside the normal router/matcher APIs
+- `remix/fetch-proxy` — Fetch-based HTTP proxying. Use to forward a request to another origin; pass
+  `xForwardedHeaders` when the upstream needs forwarded proto, host, and port. It also rewrites
+  proxied `Set-Cookie` domain/path attributes by default
+### Data, Validation, and Persistence
+- `remix/data-schema` — schema builders for runtime validation. Use for `parse` and `parseSafe`
+  to validate any input that crosses a trust boundary, and `.transform(...)` when validated output
+  should map to a different value or type
+- `remix/data-schema/checks` — common check helpers (`email`, `minLength`, `maxLength`, etc.).
+  Use to compose into a schema
+- `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/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
+### Auth, Sessions, and Cookies
+- `remix/session` — the `Session` object: `get`, `set`, `flash`, `unset`, `regenerateId`. Use for
+  any per-browser state where tampering would be a bug (login, "I submitted this form already",
+  cart, flash messages)
+- `remix/middleware/session` — `session(cookie, storage)`. Use to wire a session cookie and
+  storage backend into the root middleware stack
+- `remix/session-storage/fs`, `remix/session-storage/memory`, `remix/session-storage/cookie` —
+  storage backends. Use `fs-storage` for single-process apps, `memory-storage` for tests,
+  `cookie-storage` for stateless deployments where data fits in a cookie
+- `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/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/animation` — animation APIs: `animateEntrance`, `animateExit`, `animateLayout`,
+  `spring`, `tween`, and `easings`
+- `remix/ui/<primitive>` — UI primitives, mixins, glyphs, and theme helpers. Current subpaths
+  include `remix/ui/accordion`, `remix/ui/anchor`, `remix/ui/breadcrumbs`, `remix/ui/button`,
+  `remix/ui/combobox`, `remix/ui/glyph`, `remix/ui/listbox`, `remix/ui/menu`,
+  `remix/ui/popover`, `remix/ui/scroll-lock`, `remix/ui/select`, `remix/ui/separator`, and
+  `remix/ui/theme`
+- `remix/ui/test` — component test rendering helpers such as `render`
+- `remix/ui/jsx-runtime` and `remix/ui/jsx-dev-runtime` — JSX transform targets. Configured in
+  `tsconfig.json`, rarely imported directly
+- `remix/html-template` — escaped HTML template literals. Use when generating HTML outside the
+  component system (RSS feeds, email bodies, error pages)
+- `remix/file-storage` — backend-agnostic `File` storage interface. Use as the type bound for
+  upload destinations
+- `remix/file-storage/fs`, `remix/file-storage/memory`, `remix/file-storage/s3` — storage
+  backends. Use to implement an upload destination
+### Middleware
+- `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
+- `remix/multipart-parser` and `remix/multipart-parser/node` — low-level multipart stream parsing.
+  `MultipartPart.headers` is a plain object keyed by lower-case header name; read values with
+  bracket notation such as `part.headers['content-type']`
+- `remix/middleware/compression` — `compression()`. Use globally for text-like responses
+- `remix/middleware/logger` — `logger()`. Use in development for request logs; pass `colors` to
+  force terminal color output on or off
+- `remix/middleware/method-override` — `methodOverride()`. Use when HTML forms need `PUT`,
+  `PATCH`, or `DELETE`
+- `remix/middleware/async-context` — `asyncContext()`, `getContext()`. Use when helpers outside
+  actions need request context without threading it through every call
+- `remix/middleware/cors` — `cors(opts?)`. Use for endpoints called cross-origin
+- `remix/middleware/csrf` — `csrf(opts?)`. Use when session-backed forms mutate state and need
+  synchronizer-token CSRF protection
+- `remix/middleware/cop` — cross-origin protection. Use to reject unsafe cross-origin browser
+  requests
+### Test
+- `remix/test` — `describe`, `it`, and lifecycle hooks. Use as the test framework
+- `remix/test/cli` — programmatic test runner APIs such as `runRemixTest`
+- `remix/node-fetch-server/test` — `createTestServer` for end-to-end tests that need a real local
+  HTTP server around a Fetch handler
+- `remix/cli` — programmatic Remix CLI API. Use the `remix` executable for project commands such
+  as `remix test`, `remix routes`, `remix doctor`, and `remix version`
+- `remix/assert` — assertion helpers. Use in place of `node:assert` so messages render cleanly
+  in the runner
+- `remix/terminal` — ANSI styles, color detection, style factories, and testable terminal streams.
+  Use for CLIs and terminal output instead of hand-rolled escape sequences
+- `remix/fs` — small filesystem helpers such as `openLazyFile` and `writeFile`. Use in Node-only
+  app or tooling code when you need lazy file responses or safe file writes
+- `remix/lazy-file` — `LazyFile` primitives and byte-range helpers. Use when implementing file or
+  range responses below the higher-level response/file helpers
+- `remix/mime` — content-type and MIME detection helpers. Use instead of maintaining app-local
+  extension maps
+- `remix/tar-parser` — streaming tar parsing. Use for import/export tooling that consumes tar
+  archives
+## Canonical Patterns
+### Define routes first
+```typescript
+import { form, get, post, resources, route } from 'remix/routes'
+export const routes = route({
+  home: '/',
+  contact: form('contact'),
+  books: {
+    index: '/books',
+    show: '/books/:slug',
+  },
+  auth: route('auth', {
+    login: form('login'),
+    logout: post('logout'),
+  }),
+  admin: route('admin', {
+    index: get('/'),
+    books: resources('books', { param: 'bookId' }),
+  }),
+})
+```
+### Type controllers against the route contract
+```typescript
+import { createController } from 'remix/router'
+import { routes } from '../routes.ts'
+export default createController(routes.books, {
+  actions: {
+    async index({ get }) {
+      let db = get(Database)
+      let allBooks = await db.findMany(books, { orderBy: ['id', 'asc'] })
+      return render(<BooksIndexPage allBooks={allBooks} />)
+    },
+    async show({ get, params }) {
+      let db = get(Database)
+      let book = await db.findOne(books, { where: { slug: params.slug } })
+      if (!book) return new Response('Not Found', { status: 404 })
+      return render(<BookShowPage book={book} />)
+    },
+  },
+})
+```
+### Register Controllers Explicitly
+```typescript
+import { createRouter } from 'remix/router'
+import rootController from './actions/controller.tsx'
+import adminController from './actions/admin/controller.tsx'
+import adminBooksController from './actions/admin/books/controller.tsx'
+import authController from './actions/auth/controller.tsx'
+import authLoginController from './actions/auth/login/controller.tsx'
+import booksController from './actions/books/controller.tsx'
+import contactController from './actions/contact/controller.tsx'
+import { routes } from './routes.ts'
+export const router = createRouter({ middleware })
+router.map(routes, rootController)
+router.map(routes.contact, contactController)
+router.map(routes.books, booksController)
+router.map(routes.auth, authController)
+router.map(routes.auth.login, authLoginController)
+router.map(routes.admin, adminController)
+router.map(routes.admin.books, adminBooksController)
+```
+### Compose middleware deliberately
+```typescript
+import { createRouter } from 'remix/router'
+let middleware = []
+if (process.env.NODE_ENV === 'development') {
+  middleware.push(logger())
+}
+middleware.push(compression())
+middleware.push(staticFiles('./public'))
+middleware.push(formData())
+middleware.push(methodOverride())
+middleware.push(session(cookie, storage))
+middleware.push(asyncContext())
+middleware.push(loadDatabase())
+middleware.push(loadAuth())
+let router = createRouter({ middleware })
+```
+### Validate, mutate, and respond
+```typescript
+import { createController } from 'remix/router'
+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 { routes } from '../routes.ts'
+let bookSchema = f.object({
+  slug: f.field(s.string()),
+  title: f.field(s.string()),
+})
+export default createController(routes.books, {
+  actions: {
+    async create({ get }) {
+      let parsed = s.parseSafe(bookSchema, get(FormData))
+      if (!parsed.success) {
+        return render(<NewBookPage errors={parsed.issues} />, { status: 400 })
+      }
+      let db = get(Database)
+      let book = await db.create(books, parsed.value)
+      let session = get(Session)
+      session.flash('message', `Added ${book.title}.`)
+      return redirect(routes.books.show.href({ slug: book.slug }))
+    },
+  },
+})
+```
+This shape works without JavaScript, returns a `Response` for every outcome, and is ready for
+`clientEntry(...)` interactivity when the UI needs it.
+### Build UI from handle props plus render
+```tsx
+import { on, type Handle } from 'remix/ui'
+function Counter(handle: Handle<{ initialCount?: number; label: string }>) {
+  let count = handle.props.initialCount ?? 0
+  return () => (
+    <button
+      mix={on('click', () => {
+        count++
+        handle.update()
+      })}
+    >
+      {handle.props.label}: {count}
+    </button>
+  )
+}
+```
+Only add `clientEntry(...)` and `run(...)` when the component needs browser interactivity or
+browser-only APIs.