docs: document type-safe router labels and per-label userData typing

Add a "Type-safe router labels and `userData`" section to the TypeScript
projects guide explaining how to declare a route map and pass it as the
second type argument to a `createXRouter` factory for per-label `userData`
typing. Mirrored into the latest (3.17) docs snapshot for the patch release.

Author: B4nan

docs/guides/typescript_project.mdx

@@ -4,6 +4,8 @@ title: TypeScript Projects
 description: Stricter, safer, and better development experience
 ---
 
+import ApiLink from '@site/src/components/ApiLink';
+
 Crawlee is built with TypeScript, which means it provides the type definition directly in the package. This allows writing code with auto-completion for TypeScript and JavaScript code alike. Besides that, projects written in TypeScript can take advantage of compile-time type-checking and avoid many coding mistakes, while providing documentation for functions, parameters and return values. It will also help with refactoring a lot, and ensuring the least amount of bugs will sneak through.
 
 ## Setting up a TypeScript project
@@ -152,3 +154,36 @@ Let's wrap it up to. In addition to the scripts we described above, we also need
     }
 }
 ```
+
+## Type-safe router labels and `userData`
+
+When you structure a crawler with a <ApiLink to="core/class/Router">`Router`</ApiLink>, each route handler reads `request.userData`. By default `userData` is loosely typed, so a typo in a label or a wrong `userData` property is only caught at runtime.
+
+You can instead declare a **route map** — an `interface` (or `type`) that maps each label to the shape of `userData` expected for it — and pass it as the second type argument to a `createXRouter` factory (or <ApiLink to="core/class/Router#create">`Router.create`</ApiLink>). Handlers then get `request.userData` typed per label, and unknown labels become a compile-time error:
+
+```ts
+import { createCheerioRouter, type CheerioCrawlingContext } from 'crawlee';
+
+interface Routes {
+    PRODUCT: { sku: string; price: number };
+    CATEGORY: { categoryId: string };
+}
+
+const router = createCheerioRouter<CheerioCrawlingContext, Routes>();
+
+router.addHandler('PRODUCT', async ({ request }) => {
+    request.userData.sku; // string
+    request.userData.price; // number
+});
+
+router.addHandler('CATEGORY', async ({ request }) => {
+    request.userData.categoryId; // string
+});
+
+// ❌ compile error: 'TYPO' is not a label declared in `Routes`
+router.addHandler('TYPO', async () => {});
+```
+
+The default handler registered via `addDefaultHandler` receives the union of all declared `userData` shapes.
+
+This is a compile-time-only feature with **no runtime cost**, and it is fully backwards compatible — omitting the route map keeps the original loose typing, and passing a plain `userData` shape (e.g. `createCheerioRouter<CheerioCrawlingContext, { token: string }>()`) still types every handler with that shape, exactly as before.

website/versioned_docs/version-3.17/guides/typescript_project.mdx

@@ -4,6 +4,8 @@ title: TypeScript Projects
 description: Stricter, safer, and better development experience
 ---
 
+import ApiLink from '@site/src/components/ApiLink';
+
 Crawlee is built with TypeScript, which means it provides the type definition directly in the package. This allows writing code with auto-completion for TypeScript and JavaScript code alike. Besides that, projects written in TypeScript can take advantage of compile-time type-checking and avoid many coding mistakes, while providing documentation for functions, parameters and return values. It will also help with refactoring a lot, and ensuring the least amount of bugs will sneak through.
 
 ## Setting up a TypeScript project
@@ -152,3 +154,36 @@ Let's wrap it up to. In addition to the scripts we described above, we also need
     }
 }
 ```
+
+## Type-safe router labels and `userData`
+
+When you structure a crawler with a <ApiLink to="core/class/Router">`Router`</ApiLink>, each route handler reads `request.userData`. By default `userData` is loosely typed, so a typo in a label or a wrong `userData` property is only caught at runtime.
+
+You can instead declare a **route map** — an `interface` (or `type`) that maps each label to the shape of `userData` expected for it — and pass it as the second type argument to a `createXRouter` factory (or <ApiLink to="core/class/Router#create">`Router.create`</ApiLink>). Handlers then get `request.userData` typed per label, and unknown labels become a compile-time error:
+
+```ts
+import { createCheerioRouter, type CheerioCrawlingContext } from 'crawlee';
+
+interface Routes {
+    PRODUCT: { sku: string; price: number };
+    CATEGORY: { categoryId: string };
+}
+
+const router = createCheerioRouter<CheerioCrawlingContext, Routes>();
+
+router.addHandler('PRODUCT', async ({ request }) => {
+    request.userData.sku; // string
+    request.userData.price; // number
+});
+
+router.addHandler('CATEGORY', async ({ request }) => {
+    request.userData.categoryId; // string
+});
+
+// ❌ compile error: 'TYPO' is not a label declared in `Routes`
+router.addHandler('TYPO', async () => {});
+```
+
+The default handler registered via `addDefaultHandler` receives the union of all declared `userData` shapes.
+
+This is a compile-time-only feature with **no runtime cost**, and it is fully backwards compatible — omitting the route map keeps the original loose typing, and passing a plain `userData` shape (e.g. `createCheerioRouter<CheerioCrawlingContext, { token: string }>()`) still types every handler with that shape, exactly as before.