fix(shared,nextjs): suggest :path* subtree form in createRouteMatcher path types

.changeset/path-matcher-segment-wildcard.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/nextjs': patch
+---
+
+`createPathMatcher()` and `createRouteMatcher()` route suggestions now use the `:path*` subtree form (e.g. `/dashboard/:path*`) instead of `(.*)`. Unlike `/dashboard(.*)`, which also matches sibling routes such as `/dashboardxyz`, `/dashboard/:path*` matches only `/dashboard` and its path-segment subtree. The new suggestion type is exported as `WithPathSegmentWildcard`; the existing `WithPathPatternWildcard` type is unchanged (now deprecated), and `(.*)` patterns keep working. This only changes the type-level autocomplete suggestion.

packages/nextjs/src/server/routeMatcher.ts

@@ -1,10 +1,10 @@
-import { createPathMatcher, type WithPathPatternWildcard } from '@clerk/shared/pathMatcher';
+import { createPathMatcher, type WithPathSegmentWildcard } from '@clerk/shared/pathMatcher';
 import type { Autocomplete } from '@clerk/shared/types';
 import type Link from 'next/link';
 import type { NextRequest } from 'next/server';
 
 type NextTypedRoute<T = Parameters<typeof Link>['0']['href']> = T extends string ? T : never;
-type RouteMatcherWithNextTypedRoutes = Autocomplete<WithPathPatternWildcard<NextTypedRoute> | NextTypedRoute>;
+type RouteMatcherWithNextTypedRoutes = Autocomplete<WithPathSegmentWildcard<NextTypedRoute> | NextTypedRoute>;
 
 export type RouteMatcherParam =
   | Array<RegExp | RouteMatcherWithNextTypedRoutes>

packages/shared/src/pathMatcher.ts

@@ -1,8 +1,26 @@
 import { pathToRegexp } from './pathToRegexp';
 import type { Autocomplete } from './types';
 
+/**
+ * @deprecated Prefer {@link WithPathSegmentWildcard}; `(.*)` also matches sibling routes
+ * (e.g. `/dashboard(.*)` matches `/dashboardxyz`).
+ */
 export type WithPathPatternWildcard<T = string> = `${T & string}(.*)`;
-export type PathPattern = Autocomplete<WithPathPatternWildcard>;
+
+type StripTrailingSlash<T extends string> = T extends '/'
+  ? T
+  : T extends `${infer Prefix}/`
+    ? StripTrailingSlash<Prefix>
+    : T;
+
+/**
+ * Suggests the `:path*` subtree form (e.g. `/dashboard/:path*`), which matches on
+ * path-segment boundaries. `/` is special-cased to `/:path*` to avoid a malformed `//:path*`.
+ */
+export type WithPathSegmentWildcard<T = string> = T extends '/'
+  ? '/:path*'
+  : `${StripTrailingSlash<T & string>}/:path*`;
+export type PathPattern = Autocomplete<WithPathSegmentWildcard>;
 export type PathMatcherParam = Array<RegExp | PathPattern> | RegExp | PathPattern;
 
 export class MalformedURLError extends Error {