@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.121

package/package.json

@@ -1,34 +1,44 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.12",
-  "type": "module",
+  "version": "0.0.0-experimental.121",
   "description": "Django-inspired RSC router with composable URL patterns",
-  "author": "Ivo Todorov",
+  "keywords": [
+    "react",
+    "react-server-components",
+    "router",
+    "rsc",
+    "vite"
+  ],
+  "homepage": "https://github.com/ivogt/vite-rsc#readme",
+  "bugs": {
+    "url": "https://github.com/ivogt/vite-rsc/issues"
+  },
   "license": "MIT",
+  "author": "Ivo Todorov",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ivogt/vite-rsc.git",
     "directory": "packages/rangojs-router"
   },
-  "homepage": "https://github.com/ivogt/vite-rsc#readme",
-  "bugs": {
-    "url": "https://github.com/ivogt/vite-rsc/issues"
-  },
-  "publishConfig": {
-    "access": "public",
-    "tag": "experimental"
+  "bin": {
+    "rango": "./dist/bin/rango.js"
   },
-  "keywords": [
-    "react",
-    "rsc",
-    "react-server-components",
-    "router",
-    "vite"
+  "files": [
+    "src",
+    "!src/**/__tests__",
+    "!src/**/__mocks__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "dist",
+    "skills",
+    "AGENTS.md",
+    "README.md"
   ],
+  "type": "module",
   "exports": {
     ".": {
-      "react-server": "./src/index.rsc.ts",
       "types": "./src/index.rsc.ts",
+      "react-server": "./src/index.rsc.ts",
       "default": "./src/index.ts"
     },
     "./server": {
@@ -36,8 +46,8 @@
       "import": "./src/server.ts"
     },
     "./client": {
-      "react-server": "./src/client.rsc.tsx",
       "types": "./src/client.tsx",
+      "react-server": "./src/client.rsc.tsx",
       "default": "./src/client.tsx"
     },
     "./browser": {
@@ -49,8 +59,8 @@
       "default": "./src/ssr/index.tsx"
     },
     "./rsc": {
-      "react-server": "./src/rsc/index.ts",
       "types": "./src/rsc/index.ts",
+      "react-server": "./src/rsc/index.ts",
       "default": "./src/rsc/index.ts"
     },
     "./vite": {
@@ -58,7 +68,7 @@
       "import": "./dist/vite/index.js"
     },
     "./types": {
-      "types": "./src/vite/version.d.ts"
+      "types": "./src/vite/plugins/version.d.ts"
     },
     "./__internal": {
       "types": "./src/__internal.ts",
@@ -73,8 +83,8 @@
       "default": "./src/deps/ssr.ts"
     },
     "./internal/deps/rsc": {
-      "react-server": "./src/deps/rsc.ts",
       "types": "./src/deps/rsc.ts",
+      "react-server": "./src/deps/rsc.ts",
       "default": "./src/deps/rsc.ts"
     },
     "./internal/deps/html-stream-client": {
@@ -86,15 +96,20 @@
       "default": "./src/deps/html-stream-server.ts"
     },
     "./internal/rsc-handler": {
-      "react-server": "./src/rsc/handler.ts",
       "types": "./src/rsc/handler.ts",
+      "react-server": "./src/rsc/handler.ts",
       "default": "./src/rsc/handler.ts"
     },
     "./cache": {
-      "react-server": "./src/cache/index.ts",
       "types": "./src/cache/index.ts",
+      "react-server": "./src/cache/index.ts",
       "default": "./src/cache/index.ts"
     },
+    "./cache-runtime": {
+      "types": "./src/cache/cache-runtime.ts",
+      "react-server": "./src/cache/cache-runtime.ts",
+      "default": "./src/cache/cache-runtime.ts"
+    },
     "./theme": {
       "types": "./src/theme/index.ts",
       "default": "./src/theme/index.ts"
@@ -104,8 +119,8 @@
       "import": "./src/build/index.ts"
     },
     "./host": {
-      "react-server": "./src/host/index.ts",
       "types": "./src/host/index.ts",
+      "react-server": "./src/host/index.ts",
       "default": "./src/host/index.ts"
     },
     "./host/testing": {
@@ -113,51 +128,31 @@
       "default": "./src/host/testing.ts"
     }
   },
-  "files": [
-    "src",
-    "!src/**/__tests__",
-    "!src/**/__mocks__",
-    "!src/**/*.test.ts",
-    "!src/**/*.test.tsx",
-    "dist",
-    "skills",
-    "CLAUDE.md",
-    "README.md"
-  ],
-  "bin": {
-    "rango": "./dist/bin/rango.js"
+  "publishConfig": {
+    "access": "public",
+    "tag": "experimental"
   },
   "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node'",
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
     "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.strict-check.json --noEmit && tsc -p tsconfig.augment-check.json --noEmit",
     "test": "playwright test",
     "test:ui": "playwright test --ui",
+    "test:hmr-local": "playwright test --project=dev-warmup --project=hmr-routes --project=hmr-basename --project=hmr-prerender --no-deps --workers=1",
     "test:unit": "vitest run",
     "test:unit:watch": "vitest"
   },
-  "peerDependencies": {
-    "@cloudflare/vite-plugin": "^1.21.0",
-    "@vitejs/plugin-rsc": "^0.5.14",
-    "react": "^18.0.0 || ^19.0.0",
-    "vite": "^7.3.0"
-  },
-  "peerDependenciesMeta": {
-    "@cloudflare/vite-plugin": {
-      "optional": true
-    },
-    "vite": {
-      "optional": true
-    }
-  },
   "dependencies": {
-    "@vitejs/plugin-rsc": "^0.5.14",
+    "@types/debug": "^4.1.12",
+    "@vitejs/plugin-rsc": "^0.5.26",
+    "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.3",
     "rsc-html-stream": "^0.0.7"
   },
   "devDependencies": {
     "@playwright/test": "^1.49.1",
+    "@shared/e2e": "workspace:*",
     "@types/node": "^24.10.1",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
@@ -168,5 +163,20 @@
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@cloudflare/vite-plugin": "^1.38.0",
+    "@vitejs/plugin-rsc": "^0.5.26",
+    "react": ">=19.2.6 <20",
+    "react-dom": ">=19.2.6 <20",
+    "vite": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/vite-plugin": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   }
 }

package/skills/api-client/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: api-client
+description: Build a typed client for consuming your own response-route JSON APIs (no codegen)
+---
+
+# Typed API Client
+
+Response routes (`path.json()`) already ship typed responses — `RouteResponse<typeof patterns, "name">` resolves to the **bare payload**, inferred from your handler with no codegen. This skill wraps that inference in a small **typed client** so first-party TypeScript code calls your endpoints like functions instead of hand-writing `fetch` + URL building per call site.
+
+This is a **recipe, not a framework feature** — copy the helper below into your app. It depends only on **type-only** imports from `@rangojs/router` (`RouteResponse`, `ExtractParams`, `ProblemDetails`), which are erased at build time, so it runs anywhere a `fetch` does — **browser, worker, or server**. Nothing new to install or version.
+
+> **Scope:** the typed client is a **first-party TypeScript** convenience. External/third-party consumers use the plain wire directly — bare JSON on success, RFC 9457 `application/problem+json` on error — which needs no client. (Language-agnostic OpenAPI generation is a separate, future feature.)
+
+## What you get
+
+```ts
+const api = createApiClient(apiShopPatterns, routes, { baseUrl });
+
+await api.health.get(); // no params → callable bare
+await api.product.get({ params: { productId } }); // params typed + required
+await api.cart.post({ body: { productId, qty: 2 } }); // body sent as JSON
+//    ^ result is the bare payload type (RouteResponse), not `any`, no `.data`
+```
+
+- **Output typed** from the handler's return (`RouteResponse`), zero codegen.
+- **Params required + typed** from the route pattern (`/catalog/:productId` → `{ productId: string }`); a missing or misspelled param is a **compile error**, not a runtime 404.
+- **Autocomplete** over every route name; rename-safe.
+- **Errors throw a typed `ApiError`** carrying the `ProblemDetails` body.
+
+(`search` and `body` are _not_ route-typed — see Notes.)
+
+## The two inputs
+
+1. **The `urls()` patterns value** — the type source. `typeof apiShopPatterns` carries the per-route response payloads (`_responses`) and patterns (`_routes`).
+2. **The generated route map** — the name → pattern source. `rango generate` emits a per-module `<name>.gen.ts` exporting `routes`:
+
+```ts
+// api-shop.gen.ts (generated — do not edit)
+export const routes = {
+  catalog: "/catalog",
+  product: "/catalog/:productId",
+  cart: "/cart",
+  // ...
+} as const;
+```
+
+Routes that declare a **search schema** are generated as objects instead — `index: { path: "/", search: { q: "string" } }`. The helper accepts both the string and `{ path }` forms. If a `urls()` block is mounted under a name prefix, build a local-keyed map from your global `NamedRoutes` so the keys match the block's route names (e.g. `{ catalog: NamedRoutes["apiShop.catalog"], ... } as const`).
+
+## The helper (copy into your app)
+
+```ts
+// lib/api-client.ts
+import type {
+  RouteResponse,
+  ExtractParams,
+  ProblemDetails,
+} from "@rangojs/router";
+
+type SearchParams = Record<string, string | number | boolean>;
+
+// A generated route-map entry is a pattern string, or an object with `path`
+// (routes that declare a search schema generate the object form).
+type RouteMapEntry = string | { readonly path: string };
+type PatternOf<E> = E extends string
+  ? E
+  : E extends { readonly path: infer P extends string }
+    ? P
+    : never;
+
+// `params` is optional when the route has no *required* params (incl.
+// optional-only routes like `/:locale?`), required otherwise. Typed as
+// `ExtractParams` (not `undefined`) so optional params can still be passed.
+type Args<TPattern extends string> =
+  {} extends ExtractParams<TPattern>
+    ? {
+        params?: ExtractParams<TPattern>;
+        search?: SearchParams;
+        body?: unknown;
+      }
+    : {
+        params: ExtractParams<TPattern>;
+        search?: SearchParams;
+        body?: unknown;
+      };
+
+type Method<TPatterns, K extends string, TEntry> =
+  {} extends ExtractParams<PatternOf<TEntry>>
+    ? (args?: Args<PatternOf<TEntry>>) => Promise<RouteResponse<TPatterns, K>>
+    : (args: Args<PatternOf<TEntry>>) => Promise<RouteResponse<TPatterns, K>>;
+
+type ApiClient<TPatterns, TRouteMap extends Record<string, RouteMapEntry>> = {
+  [K in keyof TRouteMap & string]: {
+    get: Method<TPatterns, K, TRouteMap[K]>;
+    post: Method<TPatterns, K, TRouteMap[K]>;
+    put: Method<TPatterns, K, TRouteMap[K]>;
+    patch: Method<TPatterns, K, TRouteMap[K]>;
+    delete: Method<TPatterns, K, TRouteMap[K]>;
+  };
+};
+
+/** Thrown on a non-2xx response; carries the RFC 9457 problem body. */
+export class ApiError extends Error {
+  status: number;
+  problem: ProblemDetails;
+  constructor(status: number, problem: ProblemDetails) {
+    super(problem.detail || `HTTP ${status}`);
+    this.name = "ApiError";
+    this.status = status;
+    this.problem = problem;
+  }
+}
+
+// Client-safe path builder: substitutes :params (incl. optional/constrained
+// forms) into the pattern. No dependency on the server-only createReverse.
+function fillPath(pattern: string, params?: Record<string, string>): string {
+  return pattern
+    .replace(/:([A-Za-z0-9_]+)(?:\([^)]*\))?\??/g, (_m, name: string) => {
+      const v = params?.[name];
+      return v == null ? "" : encodeURIComponent(String(v));
+    })
+    .replace(/\/{2,}/g, "/");
+}
+
+export function createApiClient<
+  TPatterns,
+  const TRouteMap extends Record<string, RouteMapEntry>,
+>(
+  _patterns: TPatterns,
+  routeMap: TRouteMap,
+  opts: { baseUrl?: string; fetch?: typeof fetch } = {},
+): ApiClient<TPatterns, TRouteMap> {
+  const doFetch = opts.fetch ?? fetch;
+  const baseUrl = opts.baseUrl ?? "";
+  const call =
+    (name: string, method: string) =>
+    async (args?: {
+      params?: Record<string, string>;
+      search?: SearchParams;
+      body?: unknown;
+    }) => {
+      const entry = routeMap[name];
+      const pattern = typeof entry === "string" ? entry : entry.path;
+      let url = baseUrl + fillPath(pattern, args?.params);
+      if (args?.search) {
+        const qs = new URLSearchParams();
+        for (const [k, v] of Object.entries(args.search)) {
+          if (v != null) qs.append(k, String(v));
+        }
+        const s = qs.toString();
+        if (s) url += (url.includes("?") ? "&" : "?") + s;
+      }
+      const res = await doFetch(url, {
+        method,
+        ...(args?.body !== undefined
+          ? {
+              body: JSON.stringify(args.body),
+              headers: { "content-type": "application/json" },
+            }
+          : {}),
+      });
+      if (!res.ok) {
+        const problem = (await res.json().catch(() => ({}))) as ProblemDetails;
+        throw new ApiError(res.status, problem);
+      }
+      return res.json();
+    };
+  return new Proxy({} as any, {
+    get: (_t, name: string) => ({
+      get: call(name, "GET"),
+      post: call(name, "POST"),
+      put: call(name, "PUT"),
+      patch: call(name, "PATCH"),
+      delete: call(name, "DELETE"),
+    }),
+  }) as ApiClient<TPatterns, TRouteMap>;
+}
+```
+
+## Using it
+
+```ts
+import { apiShopPatterns } from "./urls/api-shop";
+import { routes } from "./urls/api-shop.gen";
+import { createApiClient, ApiError } from "./lib/api-client";
+
+const api = createApiClient(apiShopPatterns, routes, {
+  baseUrl: import.meta.env.VITE_API_URL ?? "",
+});
+
+try {
+  const product = await api.product.get({ params: { productId: "42" } });
+  // `product` is the handler's bare return type — e.g. `product.name` is typed.
+} catch (err) {
+  if (err instanceof ApiError && err.status === 404) {
+    console.warn(err.problem.code, err.problem.detail); // typed ProblemDetails
+  } else {
+    throw err;
+  }
+}
+```
+
+## Notes
+
+- **Client-safe by construction.** The helper imports only **types** from `@rangojs/router` (erased at build) and builds URLs itself by substituting `:params` into the pattern — it does **not** use `createReverse`, which is a server/RSC-only export that throws in the browser. So `createApiClient` works in client components, workers, and on the server alike.
+- **Params are route-typed; search and body are not.** Path params come from the route pattern (`ExtractParams`), so they are precise and required. `search` is generically typed (`Record<string, string | number | boolean>`), and `body` is `unknown` (serialized to JSON). Typed request **input** needs a declared schema layer, which is intentionally out of scope here — thread per-route schemas in yourself if you want typed search/body.
+- **Verb-agnostic wire.** Rango response routes do not dispatch on HTTP method — `.get`/`.post`/etc. set the request method but hit the same handler. Use whichever verb reads best for the operation.
+- **Path building.** `fillPath` handles standard `:param`, optional `:param?`, and constrained `:param(a|b)` forms. For exotic patterns or strict trailing-slash policies, swap in your own builder (or the router's `reverse` on the server).
+- **Want a return-based style instead of throwing?** Branch on `res.ok` yourself: the wire is the bare value on 2xx and `ProblemDetails` on non-2xx (see `/response-routes`). Wrapping the calls in a `{ ok, data } | { ok: false, error }` result type is a small variation on the same helper.
+- **Third parties.** The typed client is TypeScript-only and needs your route types. External consumers in any language use the plain wire as-is (bare JSON + problem+json); no client required.
+
+See `/response-routes` for the endpoint side and `/typesafety` for how `RouteResponse` / `PathResponse` inference works.

package/skills/breadcrumbs/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: breadcrumbs
+description: Built-in Breadcrumbs handle for accumulating breadcrumb navigation across route segments
+argument-hint: [setup]
+---
+
+# Breadcrumbs
+
+Built-in handle for accumulating breadcrumb items across route segments.
+Each layout/route pushes items via `ctx.use(Breadcrumbs)`, and they are
+collected in parent-to-child order with automatic deduplication by `href`.
+
+## BreadcrumbItem Type
+
+```typescript
+interface BreadcrumbItem {
+  label: string; // Display text
+  href: string; // URL the breadcrumb links to
+  content?: ReactNode | Promise<ReactNode>; // Optional extra content (sync or async)
+}
+```
+
+## Pushing Breadcrumbs (Server)
+
+Import `Breadcrumbs` from `@rangojs/router` in RSC/server context:
+
+```typescript
+import { urls, Breadcrumbs } from "@rangojs/router";
+import { Outlet } from "@rangojs/router/client";
+
+export const urlpatterns = urls(({ path, layout }) => [
+  // Root layout pushes "Home"
+  layout((ctx) => {
+    const breadcrumb = ctx.use(Breadcrumbs);
+    breadcrumb({ label: "Home", href: "/" });
+    return <RootLayout />;
+  }, () => [
+    path("/", HomePage, { name: "home" }),
+
+    // Nested layout pushes "Blog"
+    layout((ctx) => {
+      const breadcrumb = ctx.use(Breadcrumbs);
+      breadcrumb({ label: "Blog", href: "/blog" });
+      return <BlogLayout />;
+    }, () => [
+      path("/blog", BlogIndex, { name: "blog.index" }),
+
+      // Route handler pushes post title
+      path("/blog/:slug", (ctx) => {
+        const breadcrumb = ctx.use(Breadcrumbs);
+        breadcrumb({ label: ctx.params.slug, href: `/blog/${ctx.params.slug}` });
+        return <BlogPost slug={ctx.params.slug} />;
+      }, { name: "blog.post" }),
+    ]),
+  ]),
+]);
+```
+
+On `/blog/my-post`, breadcrumbs accumulate: `Home > Blog > my-post`.
+
+## Async Content
+
+The `content` field supports `Promise<ReactNode>` for streaming:
+
+```typescript
+path("/product/:id", async (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  const productPromise = fetchProduct(ctx.params.id);
+
+  breadcrumb({
+    label: "Product",
+    href: `/product/${ctx.params.id}`,
+    content: productPromise.then((p) => <span>({p.category})</span>),
+  });
+
+  const product = await productPromise;
+  return <ProductPage product={product} />;
+}, { name: "product" })
+```
+
+Async content is a `Promise<ReactNode>`. Resolve it in your component
+with React's `use()` hook wrapped in `<Suspense>`.
+
+## Consuming Breadcrumbs (Client)
+
+Use `useHandle(Breadcrumbs)` in a client component to read the accumulated items:
+
+```tsx
+"use client";
+import { useHandle, Breadcrumbs, Link } from "@rangojs/router/client";
+
+function BreadcrumbNav() {
+  const breadcrumbs = useHandle(Breadcrumbs);
+
+  if (!breadcrumbs.length) return null;
+
+  return (
+    <nav aria-label="Breadcrumb">
+      <ol>
+        {breadcrumbs.map((crumb, i) => (
+          <li key={crumb.href}>
+            {i === breadcrumbs.length - 1 ? (
+              <span aria-current="page">{crumb.label}</span>
+            ) : (
+              <Link to={crumb.href}>{crumb.label}</Link>
+            )}
+          </li>
+        ))}
+      </ol>
+    </nav>
+  );
+}
+```
+
+### With Selector
+
+Re-render only when the selected value changes:
+
+```tsx
+// Only the last breadcrumb
+const current = useHandle(Breadcrumbs, (data) => data.at(-1));
+
+// Breadcrumb count
+const count = useHandle(Breadcrumbs, (data) => data.length);
+```
+
+## Deduplication
+
+The built-in collect function deduplicates by `href`. If multiple segments
+push the same `href`, the last one wins. This prevents duplicates when
+navigating between sibling routes that share a common breadcrumb.
+
+## Passing as Props
+
+Breadcrumbs handle can be passed from server to client components:
+
+```tsx
+// Server component
+path("/dashboard", (ctx) => {
+  const breadcrumb = ctx.use(Breadcrumbs);
+  breadcrumb({ label: "Dashboard", href: "/dashboard" });
+  return <DashboardNav handle={Breadcrumbs} />;
+});
+```
+
+```tsx
+// Client component
+"use client";
+import { useHandle, type Breadcrumbs } from "@rangojs/router/client";
+
+function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
+  const crumbs = useHandle(handle);
+  return (
+    <nav>
+      {crumbs.map((c) => (
+        <a href={c.href}>{c.label}</a>
+      ))}
+    </nav>
+  );
+}
+```
+
+## Complete Example
+
+```typescript
+// urls.tsx
+import { urls, Breadcrumbs, Meta } from "@rangojs/router";
+import { Outlet, MetaTags } from "@rangojs/router/client";
+import { BreadcrumbNav } from "./components/BreadcrumbNav";
+
+function RootLayout() {
+  return (
+    <html lang="en">
+      <head><MetaTags /></head>
+      <body>
+        <BreadcrumbNav />
+        <main><Outlet /></main>
+      </body>
+    </html>
+  );
+}
+
+export const urlpatterns = urls(({ path, layout }) => [
+  layout((ctx) => {
+    ctx.use(Breadcrumbs)({ label: "Home", href: "/" });
+    ctx.use(Meta)({ title: "My App" });
+    return <RootLayout />;
+  }, () => [
+    path("/", () => <h1>Welcome</h1>, { name: "home" }),
+
+    layout((ctx) => {
+      ctx.use(Breadcrumbs)({ label: "Shop", href: "/shop" });
+      return <Outlet />;
+    }, () => [
+      path("/shop", () => <h1>Shop</h1>, { name: "shop" }),
+      path("/shop/:slug", (ctx) => {
+        ctx.use(Breadcrumbs)({
+          label: ctx.params.slug,
+          href: `/shop/${ctx.params.slug}`,
+        });
+        return <h1>Product: {ctx.params.slug}</h1>;
+      }, { name: "shop.product" }),
+    ]),
+  ]),
+]);
+```
+
+Navigating to `/shop/widget` produces: `Home / Shop / widget`
+
+## Custom Handles
+
+Create your own handle with `createHandle()`:
+
+```typescript
+import { createHandle } from "@rangojs/router";
+
+// Default: flatten into array
+export const PageTitle = createHandle<string, string>(
+  (segments) => segments.flat().at(-1) ?? "Default Title",
+);
+
+// No collect function: default flattens into T[]
+export const Warnings = createHandle<string>();
+```
+
+The Vite `exposeInternalIds` plugin auto-injects a stable `$$id` based on
+file path and export name. No manual naming required for project-local code.
+
+### Handles in 3rd-party packages
+
+The `exposeInternalIds` plugin skips `node_modules/`, so handles defined in
+published packages won't get auto-injected IDs. Pass a manual tag as the
+second argument to `createHandle()`:
+
+```typescript
+import { createHandle } from "@rangojs/router";
+
+// With a collect function (reducer): collect is first arg, tag is second
+export const Breadcrumbs = createHandle<BreadcrumbItem, BreadcrumbItem[]>(
+  collectBreadcrumbs,
+  "__my_package_breadcrumbs__",
+);
+
+// Without a collect function: pass undefined, then the tag
+export const Warnings = createHandle<string>(
+  undefined,
+  "__my_package_warnings__",
+);
+```
+
+The tag must be globally unique and stable across builds. Without it,
+`createHandle` throws in development mode.