Add Next proxy adapter foundation (#116)

* Add Next proxy adapter foundation

- Adds createEmulateProxy with single-target and service-target forwarding, prefix handling, forwarded headers, and response rewriting for native runtimes.

- Keeps embedded Next adapter behavior intact while adding focused proxy tests and adapter test wiring.

- Updates docs and skills to distinguish embedded mode from native runtime proxy mode.

* Fix Next proxy redirect handling

* Fix Next proxy prefix rewriting

* Harden Next proxy response rewriting

Author: ctate

README.md

@@ -713,7 +713,7 @@ The experimental native Go runtime serves the same current Resend routes, suppor
 
 ## Next.js Integration
 
-Embed emulators directly in your Next.js app so they run on the same origin. This solves the Vercel preview deployment problem where OAuth callback URLs change with every deployment.
+Use `@emulators/adapter-next` to run emulator routes on the same origin as your Next.js app. Embedded mode runs JavaScript emulators directly in the app. Proxy mode forwards to a separately running native runtime.
 
 ### Install
 
@@ -723,9 +723,9 @@ npm install @emulators/adapter-next @emulators/github @emulators/google
 
 Only install the emulators you need. Each `@emulators/*` package is published independently.
 
-### Route handler
+### Embedded route handler
 
-Create a catch-all route that serves emulator traffic:
+Create a catch-all route that serves emulator traffic in-process:
 
 ```typescript
 // app/emulate/[...path]/route.ts
@@ -752,6 +752,48 @@ export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
 })
 ```
 
+Embedded mode is the current zero-infra path for Vercel preview deployments. The emulator code runs in the Next.js function, so OAuth callback URLs can point at the preview origin.
+
+### Native runtime proxy
+
+Use `createEmulateProxy` when a native runtime is running separately and the Next.js route should forward requests to it:
+
+```typescript
+// app/emulate/[...path]/route.ts
+import { createEmulateProxy } from '@emulators/adapter-next'
+
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  targets: {
+    resend: 'http://127.0.0.1:4018',
+    aws: 'http://127.0.0.1:4020',
+  },
+})
+```
+
+With `targets`, the first path segment selects the service and is stripped before forwarding. `/emulate/resend/emails` forwards to `http://127.0.0.1:4018/emails`, while response `Location` headers and HTML links are rewritten back to `/emulate/resend/*`.
+
+If multiple services share one native runtime URL, keep using `targets` and point each service at that runtime when the runtime expects service-local paths:
+
+```typescript
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  targets: {
+    resend: 'http://127.0.0.1:4000',
+    aws: 'http://127.0.0.1:4000',
+  },
+})
+```
+
+Use single `target` only when the upstream expects every path segment after the public route prefix:
+
+```typescript
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  routePrefix: '/emulate',
+  target: 'http://127.0.0.1:4020',
+})
+```
+
+Single target mode preserves every path segment. `/emulate/aws/sqs` forwards to `http://127.0.0.1:4020/aws/sqs`. For deployed previews, the target URL must be reachable from the Next.js serverless function.
+
 ### Auth.js / NextAuth configuration
 
 Point your provider at the emulator paths on the same origin:

apps/web/app/api/docs-chat/route.ts

@@ -14,7 +14,7 @@ const DEFAULT_MODEL = "anthropic/claude-haiku-4.5";
 
 const SYSTEM_PROMPT = `You are a helpful documentation assistant for emulate, a local drop-in replacement for Vercel, GitHub, Google, Slack, Apple, Microsoft, AWS, Okta, MongoDB Atlas, Resend, and Stripe APIs used in CI and no-network sandboxes.
 
-emulate provides fully stateful, production-fidelity API emulation, not mocks. The CLI is installed as the "emulate" npm package and run via "npx emulate". It also supports a programmatic API via createEmulator and a Next.js adapter (@emulators/adapter-next) for embedding emulators in your app.
+emulate provides fully stateful, production-fidelity API emulation, not mocks. The CLI is installed as the "emulate" npm package and run via "npx emulate". It also supports a programmatic API via createEmulator and a Next.js adapter (@emulators/adapter-next) for embedded emulators or native runtime proxy routes in your app.
 
 You have access to the full emulate documentation via the bash and readFile tools. The docs are available as markdown files in the /workspace/ directory.
 

apps/web/app/docs/nextjs/page.mdx

@@ -1,6 +1,6 @@
 # Next.js Integration
 
-The `@emulators/adapter-next` package embeds emulators directly into a Next.js app, running them on the same origin. This is particularly useful for Vercel preview deployments where OAuth callback URLs change with every deployment.
+The `@emulators/adapter-next` package supports two App Router modes. Embedded mode runs JavaScript emulators directly inside the Next.js app. Proxy mode exposes a separately running native runtime on the same origin.
 
 ## Install
 
@@ -10,9 +10,9 @@ npm install @emulators/adapter-next @emulators/github @emulators/google
 
 Only install the emulators you need. Each `@emulators/*` package is published independently, keeping your serverless bundles small.
 
-## Route Handler
+## Embedded Route Handler
 
-Create a catch-all route that serves emulator traffic:
+Create a catch-all route that serves emulator traffic in-process:
 
 ```typescript
 // app/emulate/[...path]/route.ts
@@ -44,6 +44,50 @@ This creates the following routes:
 - `/emulate/github/**` serves the GitHub emulator
 - `/emulate/google/**` serves the Google emulator
 
+Embedded mode is the current zero-infra path for Vercel preview deployments. The emulator code runs in the Next.js function, so OAuth callback URLs can point at the preview origin.
+
+## Native Runtime Proxy
+
+Use `createEmulateProxy` when a native runtime is running separately and the Next.js route should forward requests to it:
+
+```typescript
+// app/emulate/[...path]/route.ts
+import { createEmulateProxy } from '@emulators/adapter-next'
+
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  targets: {
+    resend: 'http://127.0.0.1:4018',
+    aws: 'http://127.0.0.1:4020',
+  },
+})
+```
+
+With `targets`, the first path segment selects the service and is stripped before forwarding. `/emulate/resend/emails` forwards to `http://127.0.0.1:4018/emails`, while response `Location` headers and HTML links are rewritten back to `/emulate/resend/*`.
+
+If multiple services share one native runtime URL, keep using `targets` and point each service at that runtime when the runtime expects service-local paths:
+
+```typescript
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  targets: {
+    resend: 'http://127.0.0.1:4000',
+    aws: 'http://127.0.0.1:4000',
+  },
+})
+```
+
+Use single `target` only when the upstream expects every path segment after the public route prefix:
+
+```typescript
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  routePrefix: '/emulate',
+  target: 'http://127.0.0.1:4020',
+})
+```
+
+Single target mode preserves every path segment. `/emulate/aws/sqs` forwards to `http://127.0.0.1:4020/aws/sqs`.
+
+The proxy adds `x-forwarded-host`, `x-forwarded-proto`, `x-forwarded-port` when known, `x-forwarded-prefix`, `x-emulate-proxy: next`, `x-emulate-original-path`, and `x-emulate-service` for service targets. For deployed previews, the target URL must be reachable from the Next.js serverless function.
+
 ## Auth.js / NextAuth Configuration
 
 Point your provider at the emulator paths on the same origin:

apps/web/app/docs/page.mdx

@@ -85,4 +85,4 @@ You can also use emulate as a library in your tests. See the [Programmatic API](
 
 ## Next.js Integration
 
-Embed emulators directly in your Next.js app so they run on the same origin. See the [Next.js Integration](/docs/nextjs) page for setup instructions.
+Run emulator routes on the same origin as your Next.js app with embedded mode or native runtime proxy mode. See the [Next.js Integration](/docs/nextjs) page for setup instructions.

packages/@emulators/adapter-next/README.md

@@ -1,6 +1,6 @@
 # @emulators/adapter-next
 
-Next.js App Router integration for emulate. Embed emulators directly in your Next.js app so they run on the same origin, solving the Vercel preview deployment problem where OAuth callback URLs change with every deployment.
+Next.js App Router integration for emulate. Use embedded mode to run JavaScript emulators directly inside your app, or proxy mode to expose a separately running native runtime on the same origin.
 
 Part of [emulate](https://github.com/vercel-labs/emulate) — local drop-in replacement services for CI and no-network sandboxes.
 
@@ -16,9 +16,9 @@ Only install the emulators you need alongside the adapter:
 npm install @emulators/adapter-next @emulators/github @emulators/google
 ```
 
-## Route handler
+## Embedded route handler
 
-Create a catch-all route that serves emulator traffic:
+Create a catch-all route that serves emulator traffic in-process:
 
 ```typescript
 // app/emulate/[...path]/route.ts
@@ -45,6 +45,50 @@ export const { GET, POST, PUT, PATCH, DELETE } = createEmulateHandler({
 })
 ```
 
+Embedded mode is the current zero-infra path for Vercel preview deployments. The emulator code runs in the Next.js function, so OAuth callback URLs can point at the preview origin.
+
+## Native runtime proxy
+
+Use `createEmulateProxy` when a native runtime is running separately and the Next.js route should forward requests to it:
+
+```typescript
+// app/emulate/[...path]/route.ts
+import { createEmulateProxy } from '@emulators/adapter-next'
+
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  targets: {
+    resend: 'http://127.0.0.1:4018',
+    aws: 'http://127.0.0.1:4020',
+  },
+})
+```
+
+With `targets`, the first path segment selects the service and is stripped before forwarding. `/emulate/resend/emails` forwards to `http://127.0.0.1:4018/emails`, while response `Location` headers and HTML links are rewritten back to `/emulate/resend/*`.
+
+If multiple services share one native runtime URL, keep using `targets` and point each service at that runtime when the runtime expects service-local paths:
+
+```typescript
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  targets: {
+    resend: 'http://127.0.0.1:4000',
+    aws: 'http://127.0.0.1:4000',
+  },
+})
+```
+
+Use single `target` only when the upstream expects every path segment after the public route prefix:
+
+```typescript
+export const { GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS } = createEmulateProxy({
+  routePrefix: '/emulate',
+  target: 'http://127.0.0.1:4020',
+})
+```
+
+Single target mode preserves every path segment. `/emulate/aws/sqs` forwards to `http://127.0.0.1:4020/aws/sqs`.
+
+The proxy adds `x-forwarded-host`, `x-forwarded-proto`, `x-forwarded-port` when known, `x-forwarded-prefix`, `x-emulate-proxy: next`, `x-emulate-original-path`, and `x-emulate-service` for service targets. For deployed previews, the target URL must be reachable from the Next.js serverless function.
+
 ## Auth.js / NextAuth configuration
 
 Point your provider at the emulator paths on the same origin:

packages/@emulators/adapter-next/package.json

@@ -31,6 +31,7 @@
     "build": "tsup --clean",
     "dev": "tsup --watch",
     "clean": "rm -rf dist .turbo",
+    "test": "vitest run",
     "type-check": "tsc --noEmit",
     "lint": "eslint src"
   },
@@ -39,6 +40,7 @@
   },
   "devDependencies": {
     "tsup": "^8",
-    "typescript": "^5.7"
+    "typescript": "^5.7",
+    "vitest": "^4.1.6"
   }
 }