Expose resolved invocation targets in next-routing (#91242)

### What?

This PR extends `@next/routing` so `resolveRoutes()` returns the
concrete route resolution data callers need after rewrites and dynamic
matches:

- rename `matchedPathname` to `resolvedPathname`
- add `resolvedQuery`
- add `invocationTarget` for the concrete pathname/query that should be
invoked
- export the new query/invocation target types from the package
entrypoint

It also removes the leftover `query` alias so the result shape
consistently uses `resolvedQuery`.

### Why?

`matchedPathname` only described part of the result, and it was
ambiguous for dynamic routes because the resolved route template and the
concrete invocation target are not always the same thing.

For example, a dynamic route can resolve to `/blog/[slug]` while the
actual invocation target is `/blog/post-1`, and rewrites can merge query
params that callers need to preserve. Exposing these values directly
makes the package easier to consume from adapters without each caller
reconstructing them manually.

### How?

- thread resolved query construction through the route resolution paths
- build `invocationTarget` alongside `resolvedPathname` wherever
rewrites, static matches, and dynamic matches resolve successfully
- preserve merged rewrite query params in `resolvedQuery`
- update the public types, README example, and existing tests to use
`resolvedPathname`
- add coverage for resolved query + invocation target behavior on
rewrite and dynamic route matches

Verified with:
- `pnpm --filter @next/routing test -- --runInBand`
- `pnpm --filter @next/routing build`

Author: ijjk

docs/01-app/03-api-reference/05-config/01-next-config-js/adapterPath.mdx

@@ -444,8 +444,22 @@ const result = await resolveRoutes({
     return {}
   },
 })
+
+if (result.resolvedPathname) {
+  console.log('Resolved pathname:', result.resolvedPathname)
+  console.log('Resolved query:', result.resolvedQuery)
+  console.log('Invocation target:', result.invocationTarget)
+}
 ```
 
+`resolveRoutes()` returns:
+
+- `resolvedPathname`: The route pathname selected by Next.js routing. For dynamic routes, this is the matched route template such as `/blog/[slug]`.
+- `resolvedQuery`: The final query after rewrites or middleware have added or replaced search params.
+- `invocationTarget`: The concrete pathname and query to invoke for the matched route.
+
+For example, if `/blog/post-1?draft=1` matches `/blog/[slug]?slug=post-1`, `resolvedPathname` is `/blog/[slug]` while `invocationTarget.pathname` is `/blog/post-1`.
+
 ## Implementing PPR in an Adapter
 
 For partially prerendered app routes, `onBuildComplete` gives you the data needed to seed and resume PPR:

packages/next-routing/README.md

@@ -39,8 +39,10 @@ const result = await resolveRoutes({
   },
 })
 
-if (result.matchedPathname) {
-  console.log('Matched:', result.matchedPathname)
+if (result.resolvedPathname) {
+  console.log('Resolved pathname:', result.resolvedPathname)
+  console.log('Resolved query:', result.resolvedQuery)
+  console.log('Invocation target:', result.invocationTarget)
 }
 ```
 

packages/next-routing/src/__tests__/captures.test.ts

@@ -54,7 +54,7 @@ describe('Regex Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/posts/my-post')
+    expect(result.resolvedPathname).toBe('/posts/my-post')
   })
 
   it('should replace multiple numbered captures $1, $2, $3', async () => {
@@ -78,7 +78,7 @@ describe('Regex Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/archive/2024/01/post-title')
+    expect(result.resolvedPathname).toBe('/archive/2024/01/post-title')
   })
 
   it('should replace named captures in destination', async () => {
@@ -102,7 +102,7 @@ describe('Regex Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/u/alice/p/123')
+    expect(result.resolvedPathname).toBe('/u/alice/p/123')
   })
 
   it('should mix numbered and named captures', async () => {
@@ -126,7 +126,7 @@ describe('Regex Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/internal/v1/user/john')
+    expect(result.resolvedPathname).toBe('/internal/v1/user/john')
   })
 
   it('should use captures in query parameters', async () => {
@@ -150,7 +150,7 @@ describe('Regex Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/api/products')
+    expect(result.resolvedPathname).toBe('/api/products')
   })
 
   it('should replace captures in external rewrite', async () => {
@@ -240,7 +240,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/users/12345/profile')
+    expect(result.resolvedPathname).toBe('/users/12345/profile')
   })
 
   it('should use cookie value in destination', async () => {
@@ -275,7 +275,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/sessions/abc123xyz/dashboard')
+    expect(result.resolvedPathname).toBe('/sessions/abc123xyz/dashboard')
   })
 
   it('should use query parameter value in destination', async () => {
@@ -305,7 +305,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/results/nextjs')
+    expect(result.resolvedPathname).toBe('/results/nextjs')
   })
 
   it('should combine regex captures and has captures', async () => {
@@ -340,7 +340,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/tenants/acme/users/123')
+    expect(result.resolvedPathname).toBe('/tenants/acme/users/123')
   })
 
   it('should combine named regex captures and has captures', async () => {
@@ -375,7 +375,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/api/v2/products/electronics')
+    expect(result.resolvedPathname).toBe('/api/v2/products/electronics')
   })
 
   it('should use multiple has captures in destination', async () => {
@@ -415,7 +415,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/regions/us-west/tenants/acme/data')
+    expect(result.resolvedPathname).toBe('/regions/us-west/tenants/acme/data')
   })
 
   it('should use has captures with regex pattern match', async () => {
@@ -451,7 +451,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/localized/en-US/page')
+    expect(result.resolvedPathname).toBe('/localized/en-US/page')
   })
 
   it('should use has captures in query string', async () => {
@@ -486,7 +486,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/internal/dashboard')
+    expect(result.resolvedPathname).toBe('/internal/dashboard')
   })
 
   it('should use has captures in external rewrite', async () => {
@@ -601,7 +601,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/users/123')
+    expect(result.resolvedPathname).toBe('/users/123')
     expect(result.resolvedHeaders?.get('Location')).toBe('/profiles/123')
     expect(result.resolvedHeaders?.get('x-user-id')).toBe('123')
     expect(result.resolvedHeaders?.get('x-language')).toBe('es')
@@ -650,7 +650,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/api/posts')
+    expect(result.resolvedPathname).toBe('/api/posts')
     expect(result.resolvedHeaders?.get('x-resource')).toBe('posts')
     expect(result.resolvedHeaders?.get('x-language')).toBe('fr')
     expect(result.resolvedHeaders?.get('x-combined')).toBe('posts-fr')
@@ -689,7 +689,7 @@ describe('Has Condition Captures in Destination', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/fr/profile/john')
+    expect(result.resolvedPathname).toBe('/fr/profile/john')
     expect(result.routeMatches).toEqual({
       '1': 'john',
     })
@@ -736,7 +736,7 @@ describe('Complex Capture Scenarios', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe(
+    expect(result.resolvedPathname).toBe(
       '/orgs/myorg/users/john/projects/backend/issues/42'
     )
   })
@@ -762,7 +762,7 @@ describe('Complex Capture Scenarios', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/a/test/b/test/c/test')
+    expect(result.resolvedPathname).toBe('/a/test/b/test/c/test')
   })
 
   it('should handle capture with special characters', async () => {
@@ -786,7 +786,7 @@ describe('Complex Capture Scenarios', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/storage/my-file.test.js')
+    expect(result.resolvedPathname).toBe('/storage/my-file.test.js')
   })
 
   it('should not replace undefined captures', async () => {
@@ -810,7 +810,7 @@ describe('Complex Capture Scenarios', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/result/$1/$2')
+    expect(result.resolvedPathname).toBe('/result/$1/$2')
   })
 
   it('should handle captures across chained rewrites', async () => {
@@ -838,6 +838,6 @@ describe('Complex Capture Scenarios', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/internal/user-service/alice')
+    expect(result.resolvedPathname).toBe('/internal/user-service/alice')
   })
 })

packages/next-routing/src/__tests__/conditions.test.ts

@@ -66,7 +66,7 @@ describe('Has conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/admin-dashboard')
+    expect(result.resolvedPathname).toBe('/admin-dashboard')
   })
 
   it('should match route with cookie condition', async () => {
@@ -102,7 +102,7 @@ describe('Has conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/dark-theme-page')
+    expect(result.resolvedPathname).toBe('/dark-theme-page')
   })
 
   it('should match route with query condition', async () => {
@@ -133,7 +133,7 @@ describe('Has conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/preview-page')
+    expect(result.resolvedPathname).toBe('/preview-page')
   })
 
   it('should match route with host condition', async () => {
@@ -163,7 +163,7 @@ describe('Has conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/subdomain-home')
+    expect(result.resolvedPathname).toBe('/subdomain-home')
   })
 
   it('should match when has condition checks key existence only', async () => {
@@ -199,7 +199,7 @@ describe('Has conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/feature-enabled')
+    expect(result.resolvedPathname).toBe('/feature-enabled')
   })
 
   it('should match with regex pattern in has condition', async () => {
@@ -235,7 +235,7 @@ describe('Has conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/mobile')
+    expect(result.resolvedPathname).toBe('/mobile')
   })
 
   it('should require ALL has conditions to match', async () => {
@@ -277,7 +277,7 @@ describe('Has conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/admin-beta-feature')
+    expect(result.resolvedPathname).toBe('/admin-beta-feature')
   })
 
   it('should NOT match when one has condition fails', async () => {
@@ -320,7 +320,7 @@ describe('Has conditions', () => {
     const result = await resolveRoutes(params)
 
     // Should not match the route, so stays at /feature
-    expect(result.matchedPathname).toBe('/feature')
+    expect(result.resolvedPathname).toBe('/feature')
   })
 })
 
@@ -357,7 +357,7 @@ describe('Missing conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/no-debug-page')
+    expect(result.resolvedPathname).toBe('/no-debug-page')
   })
 
   it('should NOT match when missing condition is present', async () => {
@@ -393,7 +393,7 @@ describe('Missing conditions', () => {
     const result = await resolveRoutes(params)
 
     // Route should not match, stays at /page
-    expect(result.matchedPathname).toBe('/page')
+    expect(result.resolvedPathname).toBe('/page')
   })
 
   it('should match when missing cookie is not present', async () => {
@@ -428,7 +428,7 @@ describe('Missing conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/no-tracking')
+    expect(result.resolvedPathname).toBe('/no-tracking')
   })
 
   it('should match when missing query is not present', async () => {
@@ -458,7 +458,7 @@ describe('Missing conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/no-preview')
+    expect(result.resolvedPathname).toBe('/no-preview')
   })
 
   it('should require ALL missing conditions to be absent', async () => {
@@ -498,7 +498,7 @@ describe('Missing conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/standard-page')
+    expect(result.resolvedPathname).toBe('/standard-page')
   })
 })
 
@@ -543,7 +543,7 @@ describe('Combined has and missing conditions', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/member-content')
+    expect(result.resolvedPathname).toBe('/member-content')
   })
 
   it('should NOT match when has is satisfied but missing is present', async () => {
@@ -587,7 +587,7 @@ describe('Combined has and missing conditions', () => {
     const result = await resolveRoutes(params)
 
     // Should not match, stays at /content
-    expect(result.matchedPathname).toBe('/content')
+    expect(result.resolvedPathname).toBe('/content')
   })
 
   it('should NOT match when has fails even if missing is satisfied', async () => {
@@ -631,7 +631,7 @@ describe('Combined has and missing conditions', () => {
     const result = await resolveRoutes(params)
 
     // Should not match, stays at /content
-    expect(result.matchedPathname).toBe('/content')
+    expect(result.resolvedPathname).toBe('/content')
   })
 })
 
@@ -657,7 +657,7 @@ describe('Dynamic routes', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/posts/123')
+    expect(result.resolvedPathname).toBe('/posts/123')
     expect(result.routeMatches).toEqual({
       '1': '123',
     })
@@ -684,7 +684,7 @@ describe('Dynamic routes', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/users/alice/posts/456')
+    expect(result.resolvedPathname).toBe('/users/alice/posts/456')
     expect(result.routeMatches).toEqual({
       '1': 'alice',
       '2': '456',
@@ -726,7 +726,7 @@ describe('Dynamic routes', () => {
 
     const result = await resolveRoutes(params)
 
-    expect(result.matchedPathname).toBe('/profile/john')
+    expect(result.resolvedPathname).toBe('/profile/john')
     expect(result.routeMatches).toEqual({
       '1': 'john',
     })