From 843451a09743967e9e7d6f0f7a412c38c18fb100 Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Tue, 24 Feb 2026 13:52:46 +0100
Subject: [PATCH 01/12] Make composable middleware pieces first-class (#28)

- Add validateThresholds() to createMiddleware() in all 4 packages so
  standalone usage validates thresholds at creation time
- Add loadProbeScript() utility to all 4 packages, extracting probe
  bundle loading from createDeviceRouter() into a reusable export
- Refactor createDeviceRouter() to use loadProbeScript() internally
- Add standalone API docs (option tables, examples, quickstart) to all
  4 framework API docs and package READMEs
- Fix test thresholds that became invalid with eager validation
---
 CHANGELOG.md                                  |   5 +
 README.md                                     |  21 +++
 docs/api/middleware-express.md                | 137 ++++++++++++++++
 docs/api/middleware-fastify.md                | 135 ++++++++++++++++
 docs/api/middleware-hono.md                   | 133 ++++++++++++++++
 docs/api/middleware-koa.md                    | 147 ++++++++++++++++++
 packages/middleware-express/README.md         |  29 +++-
 .../src/__tests__/middleware.test.ts          |   5 +-
 packages/middleware-express/src/index.ts      |  24 +--
 packages/middleware-express/src/middleware.ts |   3 +
 packages/middleware-fastify/README.md         |  29 +++-
 .../src/__tests__/middleware.test.ts          |   2 +-
 packages/middleware-fastify/src/index.ts      |  24 +--
 packages/middleware-fastify/src/middleware.ts |   3 +
 packages/middleware-hono/README.md            |  29 +++-
 .../src/__tests__/middleware.test.ts          |   5 +-
 packages/middleware-hono/src/index.ts         |  24 +--
 packages/middleware-hono/src/middleware.ts    |   3 +
 packages/middleware-koa/README.md             |  28 +++-
 .../src/__tests__/middleware.test.ts          |   2 +-
 packages/middleware-koa/src/index.ts          |  24 +--
 packages/middleware-koa/src/middleware.ts     |   3 +
 22 files changed, 759 insertions(+), 56 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 479bccf..52288a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Features
+
+- **Composable middleware** — `createMiddleware()`, `createProbeEndpoint()`, and `createInjectionMiddleware()` are now first-class exports with full threshold validation and documentation. Use them independently for fine-grained control without the `createDeviceRouter()` factory
+- **`loadProbeScript()` utility** — New helper exported from all middleware packages that reads the minified probe bundle and optionally rewrites the endpoint URL. Pairs with `createInjectionMiddleware()` for standalone probe injection
+
 ## 0.4.0 (2026-02-24)
 
 ### Features
diff --git a/README.md b/README.md
index d926db9..3f47100 100644
--- a/README.md
+++ b/README.md
@@ -157,6 +157,27 @@ const { middleware, probeEndpoint, injectionMiddleware } = createDeviceRouter({
 
 No need to manually add `<script>` tags — the probe is injected before `</head>` in every HTML response.
 
+## Composable Middleware
+
+Don't need the full factory? Use the individual pieces directly:
+
+```typescript
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-express';
+
+const middleware = createMiddleware({ storage, thresholds });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+```
+
+Each piece validates its own options at creation time. See the [API docs](docs/api/middleware-express.md#standalone-functions) for full option tables.
+
 ## First-Request Handling
 
 By default, `deviceProfile` is `null` on the first page load before the probe runs. Two opt-in strategies provide immediate classification:
diff --git a/docs/api/middleware-express.md b/docs/api/middleware-express.md
index 45a8c83..7be6b39 100644
--- a/docs/api/middleware-express.md
+++ b/docs/api/middleware-express.md
@@ -82,6 +82,143 @@ The script is injected before `</head>`, falling back to `</body>`. JSON and oth
 
 **Note:** Injection intercepts `res.send()`. Streaming responses (`res.write()`) are not intercepted — serve the probe script tag manually in streamed HTML.
 
+## Standalone Functions
+
+The individual pieces can be used independently for more granular control.
+
+### loadProbeScript(options?)
+
+Reads and returns the minified probe script. Use this with `createInjectionMiddleware()` when you need probe injection without the full factory.
+
+```typescript
+import { loadProbeScript } from '@device-router/middleware-express';
+
+const probeScript = loadProbeScript();
+// or with a custom endpoint path:
+const probeScript = loadProbeScript({ probePath: '/custom/probe' });
+```
+
+| Option      | Type     | Default | Description                                                 |
+| ----------- | -------- | ------- | ----------------------------------------------------------- |
+| `probePath` | `string` | —       | Custom probe endpoint path (rewrites the URL in the script) |
+
+### createMiddleware(options)
+
+Creates the classification middleware independently. Thresholds are validated at creation time.
+
+```typescript
+import { createMiddleware } from '@device-router/middleware-express';
+
+const middleware = createMiddleware({
+  storage,
+  thresholds: { cpu: { lowUpperBound: 4, midUpperBound: 8 } },
+  classifyFromHeaders: true,
+});
+
+app.use(middleware);
+```
+
+#### MiddlewareOptions
+
+| Option                | Type              | Default        | Description                                    |
+| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+
+### createProbeEndpoint(options)
+
+Creates the probe POST handler independently.
+
+```typescript
+import { createProbeEndpoint } from '@device-router/middleware-express';
+
+const endpoint = createProbeEndpoint({
+  storage,
+  ttl: 3600,
+  rejectBots: true,
+});
+
+app.post('/device-router/probe', endpoint);
+```
+
+#### EndpointOptions
+
+| Option         | Type              | Default        | Description                          |
+| -------------- | ----------------- | -------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+
+### createInjectionMiddleware(options)
+
+Creates the probe script injection middleware independently. Pair with `loadProbeScript()` to load the probe bundle.
+
+```typescript
+import { createInjectionMiddleware, loadProbeScript } from '@device-router/middleware-express';
+
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript({ probePath: '/api/probe' }),
+  nonce: 'my-csp-nonce',
+});
+
+app.use(injection);
+```
+
+#### InjectOptions
+
+| Option        | Type                                   | Default      | Description                       |
+| ------------- | -------------------------------------- | ------------ | --------------------------------- |
+| `probeScript` | `string`                               | _(required)_ | The minified probe script source  |
+| `nonce`       | `string \| ((req: Request) => string)` | —            | CSP nonce for the injected script |
+
+### Standalone quickstart
+
+Use the pieces independently when you need fine-grained control:
+
+```typescript
+import express from 'express';
+import cookieParser from 'cookie-parser';
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-express';
+import { MemoryStorageAdapter } from '@device-router/storage';
+
+const app = express();
+const storage = new MemoryStorageAdapter();
+
+app.use(express.json());
+app.use(cookieParser());
+
+// Each piece is configured independently
+const middleware = createMiddleware({ storage });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.use(injection);
+app.post('/device-router/probe', endpoint);
+app.use(middleware);
+
+app.get('/', (req, res) => {
+  const profile = req.deviceProfile;
+  res.json({ tiers: profile?.tiers });
+});
+
+app.listen(3000);
+```
+
 ## Requirements
 
 - `cookie-parser` middleware must be applied before the DeviceRouter middleware
diff --git a/docs/api/middleware-fastify.md b/docs/api/middleware-fastify.md
index ba38166..3af7208 100644
--- a/docs/api/middleware-fastify.md
+++ b/docs/api/middleware-fastify.md
@@ -76,6 +76,141 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 The script is injected before `</head>`, falling back to `</body>`. JSON and other non-HTML responses pass through unmodified.
 
+## Standalone Functions
+
+The individual pieces can be used independently for more granular control.
+
+### loadProbeScript(options?)
+
+Reads and returns the minified probe script. Use this with `createInjectionMiddleware()` when you need probe injection without the full factory.
+
+```typescript
+import { loadProbeScript } from '@device-router/middleware-fastify';
+
+const probeScript = loadProbeScript();
+// or with a custom endpoint path:
+const probeScript = loadProbeScript({ probePath: '/custom/probe' });
+```
+
+| Option      | Type     | Default | Description                                                 |
+| ----------- | -------- | ------- | ----------------------------------------------------------- |
+| `probePath` | `string` | —       | Custom probe endpoint path (rewrites the URL in the script) |
+
+### createMiddleware(options)
+
+Creates the `preHandler` hook independently. Thresholds are validated at creation time.
+
+```typescript
+import { createMiddleware } from '@device-router/middleware-fastify';
+
+const hook = createMiddleware({
+  storage,
+  thresholds: { cpu: { lowUpperBound: 4, midUpperBound: 8 } },
+});
+
+app.addHook('preHandler', hook);
+```
+
+#### MiddlewareOptions
+
+| Option                | Type              | Default        | Description                                    |
+| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+
+### createProbeEndpoint(options)
+
+Creates the probe POST handler independently.
+
+```typescript
+import { createProbeEndpoint } from '@device-router/middleware-fastify';
+
+const endpoint = createProbeEndpoint({
+  storage,
+  ttl: 3600,
+  rejectBots: true,
+});
+
+app.post('/device-router/probe', endpoint);
+```
+
+#### EndpointOptions
+
+| Option         | Type              | Default        | Description                          |
+| -------------- | ----------------- | -------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+
+### createInjectionMiddleware(options)
+
+Creates the `onSend` injection hook independently. Pair with `loadProbeScript()` to load the probe bundle.
+
+```typescript
+import { createInjectionMiddleware, loadProbeScript } from '@device-router/middleware-fastify';
+
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript({ probePath: '/api/probe' }),
+  nonce: 'my-csp-nonce',
+});
+
+app.addHook('onSend', injection);
+```
+
+#### InjectOptions
+
+| Option        | Type                                          | Default      | Description                       |
+| ------------- | --------------------------------------------- | ------------ | --------------------------------- |
+| `probeScript` | `string`                                      | _(required)_ | The minified probe script source  |
+| `nonce`       | `string \| ((req: FastifyRequest) => string)` | —            | CSP nonce for the injected script |
+
+### Standalone quickstart
+
+Use the pieces independently when you need fine-grained control:
+
+```typescript
+import Fastify from 'fastify';
+import cookie from '@fastify/cookie';
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-fastify';
+import { MemoryStorageAdapter } from '@device-router/storage';
+
+const app = Fastify();
+const storage = new MemoryStorageAdapter();
+
+await app.register(cookie);
+
+// Each piece is configured independently
+const hook = createMiddleware({ storage });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.addHook('preHandler', hook);
+app.addHook('onSend', injection);
+app.post('/device-router/probe', endpoint);
+
+app.get('/', (req, reply) => {
+  const profile = req.deviceProfile;
+  reply.send({ tiers: profile?.tiers });
+});
+
+app.listen({ port: 3000 });
+```
+
 ## Requirements
 
 - `@fastify/cookie` must be registered before the DeviceRouter middleware
diff --git a/docs/api/middleware-hono.md b/docs/api/middleware-hono.md
index 5599997..1c6de85 100644
--- a/docs/api/middleware-hono.md
+++ b/docs/api/middleware-hono.md
@@ -86,6 +86,139 @@ app.use('*', middleware);
 
 **Note:** `fs.readFileSync` is called once at initialization to load the probe bundle. At runtime, only Web APIs are used.
 
+## Standalone Functions
+
+The individual pieces can be used independently for more granular control.
+
+### loadProbeScript(options?)
+
+Reads and returns the minified probe script. Use this with `createInjectionMiddleware()` when you need probe injection without the full factory.
+
+```typescript
+import { loadProbeScript } from '@device-router/middleware-hono';
+
+const probeScript = loadProbeScript();
+// or with a custom endpoint path:
+const probeScript = loadProbeScript({ probePath: '/custom/probe' });
+```
+
+| Option      | Type     | Default | Description                                                 |
+| ----------- | -------- | ------- | ----------------------------------------------------------- |
+| `probePath` | `string` | —       | Custom probe endpoint path (rewrites the URL in the script) |
+
+### createMiddleware(options)
+
+Creates the Hono middleware independently. Thresholds are validated at creation time.
+
+```typescript
+import { createMiddleware } from '@device-router/middleware-hono';
+
+const middleware = createMiddleware({
+  storage,
+  thresholds: { cpu: { lowUpperBound: 4, midUpperBound: 8 } },
+});
+
+app.use('*', middleware);
+```
+
+#### MiddlewareOptions
+
+| Option                | Type              | Default        | Description                                    |
+| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+
+### createProbeEndpoint(options)
+
+Creates the probe POST handler independently.
+
+```typescript
+import { createProbeEndpoint } from '@device-router/middleware-hono';
+
+const endpoint = createProbeEndpoint({
+  storage,
+  ttl: 3600,
+  rejectBots: true,
+});
+
+app.post('/device-router/probe', endpoint);
+```
+
+#### EndpointOptions
+
+| Option         | Type              | Default        | Description                          |
+| -------------- | ----------------- | -------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+
+### createInjectionMiddleware(options)
+
+Creates the probe script injection middleware independently. Pair with `loadProbeScript()` to load the probe bundle.
+
+```typescript
+import { createInjectionMiddleware, loadProbeScript } from '@device-router/middleware-hono';
+
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript({ probePath: '/api/probe' }),
+  nonce: 'my-csp-nonce',
+});
+
+app.use('*', injection);
+```
+
+#### InjectOptions
+
+| Option        | Type                                 | Default      | Description                       |
+| ------------- | ------------------------------------ | ------------ | --------------------------------- |
+| `probeScript` | `string`                             | _(required)_ | The minified probe script source  |
+| `nonce`       | `string \| ((c: Context) => string)` | —            | CSP nonce for the injected script |
+
+### Standalone quickstart
+
+Use the pieces independently when you need fine-grained control:
+
+```typescript
+import { Hono } from 'hono';
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-hono';
+import type { DeviceRouterEnv } from '@device-router/middleware-hono';
+import { MemoryStorageAdapter } from '@device-router/storage';
+
+const app = new Hono<DeviceRouterEnv>();
+const storage = new MemoryStorageAdapter();
+
+// Each piece is configured independently
+const middleware = createMiddleware({ storage });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.use('*', injection);
+app.use('*', middleware);
+app.post('/device-router/probe', endpoint);
+
+app.get('/', (c) => {
+  const profile = c.get('deviceProfile');
+  return c.json({ tiers: profile?.tiers });
+});
+
+export default app;
+```
+
 ## Requirements
 
 - Hono uses built-in cookie helpers (`hono/cookie`) — no additional cookie package needed
diff --git a/docs/api/middleware-koa.md b/docs/api/middleware-koa.md
index b7a0525..a0b11d2 100644
--- a/docs/api/middleware-koa.md
+++ b/docs/api/middleware-koa.md
@@ -83,6 +83,153 @@ if (injectionMiddleware) {
 app.use(middleware);
 ```
 
+## Standalone Functions
+
+The individual pieces can be used independently for more granular control.
+
+### loadProbeScript(options?)
+
+Reads and returns the minified probe script. Use this with `createInjectionMiddleware()` when you need probe injection without the full factory.
+
+```typescript
+import { loadProbeScript } from '@device-router/middleware-koa';
+
+const probeScript = loadProbeScript();
+// or with a custom endpoint path:
+const probeScript = loadProbeScript({ probePath: '/custom/probe' });
+```
+
+| Option      | Type     | Default | Description                                                 |
+| ----------- | -------- | ------- | ----------------------------------------------------------- |
+| `probePath` | `string` | —       | Custom probe endpoint path (rewrites the URL in the script) |
+
+### createMiddleware(options)
+
+Creates the Koa middleware independently. Thresholds are validated at creation time.
+
+```typescript
+import { createMiddleware } from '@device-router/middleware-koa';
+
+const middleware = createMiddleware({
+  storage,
+  thresholds: { cpu: { lowUpperBound: 4, midUpperBound: 8 } },
+});
+
+app.use(middleware);
+```
+
+#### MiddlewareOptions
+
+| Option                | Type              | Default        | Description                                    |
+| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+
+### createProbeEndpoint(options)
+
+Creates the probe POST handler independently.
+
+```typescript
+import { createProbeEndpoint } from '@device-router/middleware-koa';
+
+const endpoint = createProbeEndpoint({
+  storage,
+  ttl: 3600,
+  rejectBots: true,
+});
+
+// Route manually or with koa-router
+app.use(async (ctx, next) => {
+  if (ctx.path === '/device-router/probe' && ctx.method === 'POST') {
+    await endpoint(ctx);
+    return;
+  }
+  await next();
+});
+```
+
+#### EndpointOptions
+
+| Option         | Type              | Default        | Description                          |
+| -------------- | ----------------- | -------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+
+### createInjectionMiddleware(options)
+
+Creates the probe script injection middleware independently. Pair with `loadProbeScript()` to load the probe bundle.
+
+```typescript
+import { createInjectionMiddleware, loadProbeScript } from '@device-router/middleware-koa';
+
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript({ probePath: '/api/probe' }),
+  nonce: 'my-csp-nonce',
+});
+
+app.use(injection);
+```
+
+#### InjectOptions
+
+| Option        | Type                                   | Default      | Description                       |
+| ------------- | -------------------------------------- | ------------ | --------------------------------- |
+| `probeScript` | `string`                               | _(required)_ | The minified probe script source  |
+| `nonce`       | `string \| ((ctx: Context) => string)` | —            | CSP nonce for the injected script |
+
+### Standalone quickstart
+
+Use the pieces independently when you need fine-grained control:
+
+```typescript
+import Koa from 'koa';
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-koa';
+import { MemoryStorageAdapter } from '@device-router/storage';
+
+const app = new Koa();
+const storage = new MemoryStorageAdapter();
+
+// Each piece is configured independently
+const middleware = createMiddleware({ storage });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.use(injection);
+
+app.use(async (ctx, next) => {
+  if (ctx.path === '/device-router/probe' && ctx.method === 'POST') {
+    await endpoint(ctx);
+    return;
+  }
+  await next();
+});
+
+app.use(middleware);
+
+app.use(async (ctx) => {
+  const profile = ctx.state.deviceProfile;
+  ctx.body = { tiers: profile?.tiers };
+});
+
+app.listen(3000);
+```
+
 ## Requirements
 
 - A JSON body parser must be applied before the probe endpoint (Koa does not include one by default)
diff --git a/packages/middleware-express/README.md b/packages/middleware-express/README.md
index 2c661c2..e182958 100644
--- a/packages/middleware-express/README.md
+++ b/packages/middleware-express/README.md
@@ -118,12 +118,39 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 See the [Observability guide](https://github.com/SimplyLiz/DeviceRouter/blob/main/docs/observability.md) for details.
 
+## Standalone usage
+
+Use the individual pieces when you need fine-grained control over each component:
+
+```typescript
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-express';
+
+// Use only what you need
+const middleware = createMiddleware({ storage, thresholds });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.use(injection);
+app.post('/device-router/probe', endpoint);
+app.use(middleware);
+```
+
+`loadProbeScript()` reads the `@device-router/probe` bundle and optionally rewrites the endpoint URL via `{ probePath }`. Thresholds passed to `createMiddleware()` are validated at creation time.
+
 ## Exports
 
 - `createDeviceRouter(options)` — All-in-one setup returning `{ middleware, probeEndpoint, injectionMiddleware? }`
-- `createMiddleware(options)` — Standalone middleware
+- `createMiddleware(options)` — Standalone middleware (validates thresholds)
 - `createProbeEndpoint(options)` — Standalone probe endpoint handler
 - `createInjectionMiddleware(options)` — Standalone probe injection middleware
+- `loadProbeScript(options?)` — Load the minified probe script for use with `createInjectionMiddleware()`
 
 ## Prerequisites
 
diff --git a/packages/middleware-express/src/__tests__/middleware.test.ts b/packages/middleware-express/src/__tests__/middleware.test.ts
index bacf497..05ac106 100644
--- a/packages/middleware-express/src/__tests__/middleware.test.ts
+++ b/packages/middleware-express/src/__tests__/middleware.test.ts
@@ -132,7 +132,10 @@ describe('createMiddleware', () => {
     // Custom thresholds: raise lowUpperBound to 6 → 4 cores = low
     const mwCustom = createMiddleware({
       storage,
-      thresholds: { cpu: { lowUpperBound: 6 }, memory: { lowUpperBound: 6 } },
+      thresholds: {
+        cpu: { lowUpperBound: 6, midUpperBound: 8 },
+        memory: { lowUpperBound: 6, midUpperBound: 8 },
+      },
     });
     const req2 = createMockReq({ dr_session: 'tok2' });
     await mwCustom(req2, createMockRes(), vi.fn());
diff --git a/packages/middleware-express/src/index.ts b/packages/middleware-express/src/index.ts
index 1bb9b21..988670b 100644
--- a/packages/middleware-express/src/index.ts
+++ b/packages/middleware-express/src/index.ts
@@ -2,7 +2,7 @@ import { createRequire } from 'node:module';
 import { readFileSync } from 'node:fs';
 import type { StorageAdapter } from '@device-router/storage';
 import type { TierThresholds, FallbackProfile, OnEventCallback } from '@device-router/types';
-import { validateThresholds, createProbeHealthCheck } from '@device-router/types';
+import { createProbeHealthCheck } from '@device-router/types';
 import { createMiddleware } from './middleware.js';
 import { createProbeEndpoint } from './endpoint.js';
 import { createInjectionMiddleware } from './inject.js';
@@ -40,8 +40,6 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
     onEvent,
   } = options;
 
-  if (thresholds) validateThresholds(thresholds);
-
   const isNonProd = process.env.NODE_ENV !== 'production';
   const effectiveProbePath = probePath ?? '/device-router/probe';
 
@@ -92,16 +90,8 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   };
 
   if (injectProbe) {
-    const require = createRequire(import.meta.url);
-    const probeBundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
-    let probeScript = readFileSync(probeBundlePath, 'utf-8');
-
-    if (probePath) {
-      probeScript = probeScript.replace('"/device-router/probe"', JSON.stringify(probePath));
-    }
-
     result.injectionMiddleware = createInjectionMiddleware({
-      probeScript,
+      probeScript: loadProbeScript({ probePath }),
       nonce: probeNonce,
     });
   }
@@ -109,6 +99,16 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   return result;
 }
 
+export function loadProbeScript(options?: { probePath?: string }): string {
+  const require = createRequire(import.meta.url);
+  const bundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
+  let script = readFileSync(bundlePath, 'utf-8');
+  if (options?.probePath) {
+    script = script.replace('"/device-router/probe"', JSON.stringify(options.probePath));
+  }
+  return script;
+}
+
 export { createMiddleware } from './middleware.js';
 export { createProbeEndpoint } from './endpoint.js';
 export { createInjectionMiddleware } from './inject.js';
diff --git a/packages/middleware-express/src/middleware.ts b/packages/middleware-express/src/middleware.ts
index 58b4c28..f00435d 100644
--- a/packages/middleware-express/src/middleware.ts
+++ b/packages/middleware-express/src/middleware.ts
@@ -6,6 +6,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  validateThresholds,
 } from '@device-router/types';
 import type {
   ClassifiedProfile,
@@ -43,6 +44,8 @@ export function createMiddleware(options: MiddlewareOptions) {
     onEvent,
   } = options;
 
+  if (thresholds) validateThresholds(thresholds);
+
   return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
     try {
       if (useHeaders) {
diff --git a/packages/middleware-fastify/README.md b/packages/middleware-fastify/README.md
index 823a84d..6da8efb 100644
--- a/packages/middleware-fastify/README.md
+++ b/packages/middleware-fastify/README.md
@@ -114,12 +114,39 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 See the [Observability guide](https://github.com/SimplyLiz/DeviceRouter/blob/main/docs/observability.md) for details.
 
+## Standalone usage
+
+Use the individual pieces when you need fine-grained control over each component:
+
+```typescript
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-fastify';
+
+// Use only what you need
+const hook = createMiddleware({ storage, thresholds });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.addHook('preHandler', hook);
+app.addHook('onSend', injection);
+app.post('/device-router/probe', endpoint);
+```
+
+`loadProbeScript()` reads the `@device-router/probe` bundle and optionally rewrites the endpoint URL via `{ probePath }`. Thresholds passed to `createMiddleware()` are validated at creation time.
+
 ## Exports
 
 - `createDeviceRouter(options)` — All-in-one setup returning `{ middleware, probeEndpoint, injectionMiddleware? }`
-- `createMiddleware(options)` — Standalone preHandler hook
+- `createMiddleware(options)` — Standalone preHandler hook (validates thresholds)
 - `createProbeEndpoint(options)` — Standalone probe endpoint handler
 - `createInjectionMiddleware(options)` — Standalone onSend injection hook
+- `loadProbeScript(options?)` — Load the minified probe script for use with `createInjectionMiddleware()`
 
 ## Compatibility
 
diff --git a/packages/middleware-fastify/src/__tests__/middleware.test.ts b/packages/middleware-fastify/src/__tests__/middleware.test.ts
index 95a8f20..c62d78b 100644
--- a/packages/middleware-fastify/src/__tests__/middleware.test.ts
+++ b/packages/middleware-fastify/src/__tests__/middleware.test.ts
@@ -106,7 +106,7 @@ describe('createMiddleware', () => {
 
     const hook = createMiddleware({
       storage,
-      thresholds: { cpu: { lowUpperBound: 6 } },
+      thresholds: { cpu: { lowUpperBound: 6, midUpperBound: 8 } },
     });
     const req = createMockReq({ dr_session: 'tok2' });
 
diff --git a/packages/middleware-fastify/src/index.ts b/packages/middleware-fastify/src/index.ts
index 3764f20..ea66c9e 100644
--- a/packages/middleware-fastify/src/index.ts
+++ b/packages/middleware-fastify/src/index.ts
@@ -2,7 +2,7 @@ import { createRequire } from 'node:module';
 import { readFileSync } from 'node:fs';
 import type { StorageAdapter } from '@device-router/storage';
 import type { TierThresholds, FallbackProfile, OnEventCallback } from '@device-router/types';
-import { validateThresholds, createProbeHealthCheck } from '@device-router/types';
+import { createProbeHealthCheck } from '@device-router/types';
 import type { FastifyRequest, FastifyReply } from 'fastify';
 import fp from 'fastify-plugin';
 import { createMiddleware } from './middleware.js';
@@ -42,8 +42,6 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
     probeNonce,
   } = options;
 
-  if (thresholds) validateThresholds(thresholds);
-
   const isNonProd = process.env.NODE_ENV !== 'production';
   const effectiveProbePath = probePath ?? '/device-router/probe';
 
@@ -74,16 +72,8 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   let injectionMiddleware: ReturnType<typeof createInjectionMiddleware> | undefined;
 
   if (injectProbe) {
-    const require = createRequire(import.meta.url);
-    const probeBundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
-    let probeScript = readFileSync(probeBundlePath, 'utf-8');
-
-    if (probePath) {
-      probeScript = probeScript.replace('"/device-router/probe"', JSON.stringify(probePath));
-    }
-
     injectionMiddleware = createInjectionMiddleware({
-      probeScript,
+      probeScript: loadProbeScript({ probePath }),
       nonce: probeNonce,
     });
   }
@@ -120,6 +110,16 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   };
 }
 
+export function loadProbeScript(options?: { probePath?: string }): string {
+  const require = createRequire(import.meta.url);
+  const bundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
+  let script = readFileSync(bundlePath, 'utf-8');
+  if (options?.probePath) {
+    script = script.replace('"/device-router/probe"', JSON.stringify(options.probePath));
+  }
+  return script;
+}
+
 export { createMiddleware } from './middleware.js';
 export { createProbeEndpoint } from './endpoint.js';
 export { createInjectionMiddleware } from './inject.js';
diff --git a/packages/middleware-fastify/src/middleware.ts b/packages/middleware-fastify/src/middleware.ts
index da62488..20c4228 100644
--- a/packages/middleware-fastify/src/middleware.ts
+++ b/packages/middleware-fastify/src/middleware.ts
@@ -7,6 +7,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  validateThresholds,
 } from '@device-router/types';
 import type {
   ClassifiedProfile,
@@ -41,6 +42,8 @@ export function createMiddleware(options: MiddlewareOptions) {
     onEvent,
   } = options;
 
+  if (thresholds) validateThresholds(thresholds);
+
   return async (req: FastifyRequest, reply: FastifyReply): Promise<void> => {
     try {
       if (useHeaders) {
diff --git a/packages/middleware-hono/README.md b/packages/middleware-hono/README.md
index 5c82b1d..d75c2fb 100644
--- a/packages/middleware-hono/README.md
+++ b/packages/middleware-hono/README.md
@@ -122,12 +122,39 @@ const app = new Hono<DeviceRouterEnv>();
 // c.get('deviceProfile') is now typed
 ```
 
+## Standalone usage
+
+Use the individual pieces when you need fine-grained control over each component:
+
+```typescript
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-hono';
+
+// Use only what you need
+const middleware = createMiddleware({ storage, thresholds });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.use('*', injection);
+app.use('*', middleware);
+app.post('/device-router/probe', endpoint);
+```
+
+`loadProbeScript()` reads the `@device-router/probe` bundle and optionally rewrites the endpoint URL via `{ probePath }`. Thresholds passed to `createMiddleware()` are validated at creation time.
+
 ## Exports
 
 - `createDeviceRouter(options)` — All-in-one setup returning `{ middleware, probeEndpoint, injectionMiddleware? }`
-- `createMiddleware(options)` — Standalone middleware
+- `createMiddleware(options)` — Standalone middleware (validates thresholds)
 - `createProbeEndpoint(options)` — Standalone probe endpoint handler
 - `createInjectionMiddleware(options)` — Standalone injection middleware
+- `loadProbeScript(options?)` — Load the minified probe script for use with `createInjectionMiddleware()`
 - `DeviceRouterEnv` — Hono env type for typed context access
 
 ## Compatibility
diff --git a/packages/middleware-hono/src/__tests__/middleware.test.ts b/packages/middleware-hono/src/__tests__/middleware.test.ts
index 076fb77..793cb2c 100644
--- a/packages/middleware-hono/src/__tests__/middleware.test.ts
+++ b/packages/middleware-hono/src/__tests__/middleware.test.ts
@@ -78,7 +78,10 @@ describe('createMiddleware (hono)', () => {
     storage._store.set('tok2', profile);
 
     const app = new Hono<DeviceRouterEnv>();
-    app.use('*', createMiddleware({ storage, thresholds: { cpu: { lowUpperBound: 6 } } }));
+    app.use(
+      '*',
+      createMiddleware({ storage, thresholds: { cpu: { lowUpperBound: 6, midUpperBound: 8 } } }),
+    );
     app.get('/test', (c) => {
       const dp = c.get('deviceProfile');
       return c.json({ cpu: dp?.tiers.cpu });
diff --git a/packages/middleware-hono/src/index.ts b/packages/middleware-hono/src/index.ts
index fad7dad..141876e 100644
--- a/packages/middleware-hono/src/index.ts
+++ b/packages/middleware-hono/src/index.ts
@@ -2,7 +2,7 @@ import { createRequire } from 'node:module';
 import { readFileSync } from 'node:fs';
 import type { StorageAdapter } from '@device-router/storage';
 import type { TierThresholds, FallbackProfile, OnEventCallback } from '@device-router/types';
-import { validateThresholds, createProbeHealthCheck } from '@device-router/types';
+import { createProbeHealthCheck } from '@device-router/types';
 import type { Context } from 'hono';
 import { createMiddleware } from './middleware.js';
 import { createProbeEndpoint } from './endpoint.js';
@@ -41,8 +41,6 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
     probeNonce,
   } = options;
 
-  if (thresholds) validateThresholds(thresholds);
-
   const isNonProd = process.env.NODE_ENV !== 'production';
   const effectiveProbePath = probePath ?? '/device-router/probe';
 
@@ -93,16 +91,8 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   };
 
   if (injectProbe) {
-    const require = createRequire(import.meta.url);
-    const probeBundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
-    let probeScript = readFileSync(probeBundlePath, 'utf-8');
-
-    if (probePath) {
-      probeScript = probeScript.replace('"/device-router/probe"', JSON.stringify(probePath));
-    }
-
     result.injectionMiddleware = createInjectionMiddleware({
-      probeScript,
+      probeScript: loadProbeScript({ probePath }),
       nonce: probeNonce,
     });
   }
@@ -110,6 +100,16 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   return result;
 }
 
+export function loadProbeScript(options?: { probePath?: string }): string {
+  const require = createRequire(import.meta.url);
+  const bundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
+  let script = readFileSync(bundlePath, 'utf-8');
+  if (options?.probePath) {
+    script = script.replace('"/device-router/probe"', JSON.stringify(options.probePath));
+  }
+  return script;
+}
+
 export { createMiddleware } from './middleware.js';
 export { createProbeEndpoint } from './endpoint.js';
 export { createInjectionMiddleware } from './inject.js';
diff --git a/packages/middleware-hono/src/middleware.ts b/packages/middleware-hono/src/middleware.ts
index 5a4eff9..4eb29d5 100644
--- a/packages/middleware-hono/src/middleware.ts
+++ b/packages/middleware-hono/src/middleware.ts
@@ -7,6 +7,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  validateThresholds,
 } from '@device-router/types';
 import type {
   ClassifiedProfile,
@@ -41,6 +42,8 @@ export function createMiddleware(options: MiddlewareOptions): MiddlewareHandler<
     onEvent,
   } = options;
 
+  if (thresholds) validateThresholds(thresholds);
+
   return async (c: Context<DeviceRouterEnv>, next) => {
     try {
       if (useHeaders) {
diff --git a/packages/middleware-koa/README.md b/packages/middleware-koa/README.md
index cc2a32d..432ff8d 100644
--- a/packages/middleware-koa/README.md
+++ b/packages/middleware-koa/README.md
@@ -115,12 +115,38 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 See the [Observability guide](https://github.com/SimplyLiz/DeviceRouter/blob/main/docs/observability.md) for details.
 
+## Standalone usage
+
+Use the individual pieces when you need fine-grained control over each component:
+
+```typescript
+import {
+  createMiddleware,
+  createProbeEndpoint,
+  createInjectionMiddleware,
+  loadProbeScript,
+} from '@device-router/middleware-koa';
+
+// Use only what you need
+const middleware = createMiddleware({ storage, thresholds });
+const endpoint = createProbeEndpoint({ storage, ttl: 3600 });
+const injection = createInjectionMiddleware({
+  probeScript: loadProbeScript(),
+});
+
+app.use(injection);
+app.use(middleware);
+```
+
+`loadProbeScript()` reads the `@device-router/probe` bundle and optionally rewrites the endpoint URL via `{ probePath }`. Thresholds passed to `createMiddleware()` are validated at creation time.
+
 ## Exports
 
 - `createDeviceRouter(options)` — All-in-one setup returning `{ middleware, probeEndpoint, injectionMiddleware? }`
-- `createMiddleware(options)` — Standalone middleware
+- `createMiddleware(options)` — Standalone middleware (validates thresholds)
 - `createProbeEndpoint(options)` — Standalone probe endpoint handler
 - `createInjectionMiddleware(options)` — Standalone injection middleware
+- `loadProbeScript(options?)` — Load the minified probe script for use with `createInjectionMiddleware()`
 
 ## Compatibility
 
diff --git a/packages/middleware-koa/src/__tests__/middleware.test.ts b/packages/middleware-koa/src/__tests__/middleware.test.ts
index 6cbc6f0..02fc103 100644
--- a/packages/middleware-koa/src/__tests__/middleware.test.ts
+++ b/packages/middleware-koa/src/__tests__/middleware.test.ts
@@ -116,7 +116,7 @@ describe('createMiddleware (koa)', () => {
 
     const mw = createMiddleware({
       storage,
-      thresholds: { cpu: { lowUpperBound: 6 } },
+      thresholds: { cpu: { lowUpperBound: 6, midUpperBound: 8 } },
     });
     const ctx = createMockCtx({ dr_session: 'tok2' });
     const next = vi.fn();
diff --git a/packages/middleware-koa/src/index.ts b/packages/middleware-koa/src/index.ts
index 4a368b7..e508f67 100644
--- a/packages/middleware-koa/src/index.ts
+++ b/packages/middleware-koa/src/index.ts
@@ -2,7 +2,7 @@ import { createRequire } from 'node:module';
 import { readFileSync } from 'node:fs';
 import type { StorageAdapter } from '@device-router/storage';
 import type { TierThresholds, FallbackProfile, OnEventCallback } from '@device-router/types';
-import { validateThresholds, createProbeHealthCheck } from '@device-router/types';
+import { createProbeHealthCheck } from '@device-router/types';
 import type { Context } from 'koa';
 import { createMiddleware } from './middleware.js';
 import { createProbeEndpoint } from './endpoint.js';
@@ -41,8 +41,6 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
     probeNonce,
   } = options;
 
-  if (thresholds) validateThresholds(thresholds);
-
   const isNonProd = process.env.NODE_ENV !== 'production';
   const effectiveProbePath = probePath ?? '/device-router/probe';
 
@@ -93,16 +91,8 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   };
 
   if (injectProbe) {
-    const require = createRequire(import.meta.url);
-    const probeBundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
-    let probeScript = readFileSync(probeBundlePath, 'utf-8');
-
-    if (probePath) {
-      probeScript = probeScript.replace('"/device-router/probe"', JSON.stringify(probePath));
-    }
-
     result.injectionMiddleware = createInjectionMiddleware({
-      probeScript,
+      probeScript: loadProbeScript({ probePath }),
       nonce: probeNonce,
     });
   }
@@ -110,6 +100,16 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   return result;
 }
 
+export function loadProbeScript(options?: { probePath?: string }): string {
+  const require = createRequire(import.meta.url);
+  const bundlePath = require.resolve('@device-router/probe/dist/device-router-probe.min.js');
+  let script = readFileSync(bundlePath, 'utf-8');
+  if (options?.probePath) {
+    script = script.replace('"/device-router/probe"', JSON.stringify(options.probePath));
+  }
+  return script;
+}
+
 export { createMiddleware } from './middleware.js';
 export { createProbeEndpoint } from './endpoint.js';
 export { createInjectionMiddleware } from './inject.js';
diff --git a/packages/middleware-koa/src/middleware.ts b/packages/middleware-koa/src/middleware.ts
index 7ff0595..900c0a8 100644
--- a/packages/middleware-koa/src/middleware.ts
+++ b/packages/middleware-koa/src/middleware.ts
@@ -6,6 +6,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  validateThresholds,
 } from '@device-router/types';
 import type {
   ClassifiedProfile,
@@ -40,6 +41,8 @@ export function createMiddleware(options: MiddlewareOptions) {
     onEvent,
   } = options;
 
+  if (thresholds) validateThresholds(thresholds);
+
   return async (ctx: Context, next: Next): Promise<void> => {
     try {
       if (useHeaders) {

From c336b51ba4a4fe42f4ec5b56f33632a8a299f78e Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Tue, 24 Feb 2026 14:22:52 +0100
Subject: [PATCH 02/12] Normalize Fastify return shape to match
 Express/Hono/Koa (#29)

Return raw hooks from createDeviceRouter() instead of a fastify-plugin
wrapped plugin. Users now wire up middleware with addHook() like every
other framework adapter.
---
 CHANGELOG.md                                  |  4 ++++
 docs/api/middleware-fastify.md                | 21 ++++++++++++-------
 docs/getting-started.md                       |  2 +-
 examples/fastify-basic/src/server.ts          |  4 ++--
 packages/middleware-fastify/README.md         | 13 +++++++++---
 packages/middleware-fastify/package.json      |  6 ++----
 .../src/__tests__/diagnostics.test.ts         | 10 ++++-----
 .../src/__tests__/integration.test.ts         |  9 +++++---
 packages/middleware-fastify/src/index.ts      | 13 +-----------
 pnpm-lock.yaml                                |  3 ---
 10 files changed, 44 insertions(+), 41 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52288a8..8624e81 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Breaking Changes
+
+- **middleware-fastify: normalized return shape** — `createDeviceRouter()` now returns raw Fastify hooks instead of a `fastify-plugin` wrapped plugin. Migrate `await app.register(middleware)` → `app.addHook('preHandler', middleware)`. When using `injectProbe: true`, register the injection hook separately: `app.addHook('onSend', injectionMiddleware)`. Removed `fastify-plugin` dependency
+
 ### Features
 
 - **Composable middleware** — `createMiddleware()`, `createProbeEndpoint()`, and `createInjectionMiddleware()` are now first-class exports with full threshold validation and documentation. Use them independently for fine-grained control without the `createDeviceRouter()` factory
diff --git a/docs/api/middleware-fastify.md b/docs/api/middleware-fastify.md
index 3af7208..d9fb3eb 100644
--- a/docs/api/middleware-fastify.md
+++ b/docs/api/middleware-fastify.md
@@ -18,7 +18,7 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 });
 
 app.post('/device-router/probe', probeEndpoint);
-await app.register(middleware);
+app.addHook('preHandler', middleware);
 ```
 
 ### Options
@@ -41,11 +41,11 @@ await app.register(middleware);
 
 ### Returns
 
-| Property              | Type                         | Description                                                  |
-| --------------------- | ---------------------------- | ------------------------------------------------------------ |
-| `middleware`          | Fastify plugin               | Registers `preHandler` hook (and `onSend` hook if injecting) |
-| `probeEndpoint`       | Fastify route handler        | Handles `POST` from probe, validates and stores signals      |
-| `injectionMiddleware` | `onSend` hook or `undefined` | Only present when `injectProbe: true`                        |
+| Property              | Type                         | Description                                             |
+| --------------------- | ---------------------------- | ------------------------------------------------------- |
+| `middleware`          | `preHandler` hook            | Classifies the device and attaches profile to `req`     |
+| `probeEndpoint`       | Fastify route handler        | Handles `POST` from probe, validates and stores signals |
+| `injectionMiddleware` | `onSend` hook or `undefined` | Only present when `injectProbe: true`                   |
 
 ## req.deviceProfile
 
@@ -64,14 +64,19 @@ interface ClassifiedProfile {
 
 ## Probe Auto-Injection
 
-When `injectProbe: true`, the middleware registers an `onSend` hook that automatically injects the probe `<script>` into HTML responses. Requires `@device-router/probe` to be installed.
+When `injectProbe: true`, `injectionMiddleware` is returned as an `onSend` hook that injects the probe `<script>` into HTML responses. Register it yourself. Requires `@device-router/probe` to be installed.
 
 ```typescript
-const { middleware, probeEndpoint } = createDeviceRouter({
+const { middleware, probeEndpoint, injectionMiddleware } = createDeviceRouter({
   storage,
   injectProbe: true,
   probeNonce: 'my-nonce', // or (req) => req.headers['x-nonce']
 });
+
+app.addHook('preHandler', middleware);
+if (injectionMiddleware) {
+  app.addHook('onSend', injectionMiddleware);
+}
 ```
 
 The script is injected before `</head>`, falling back to `</body>`. JSON and other non-HTML responses pass through unmodified.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c239bf0..ae9950d 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -62,7 +62,7 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 });
 
 app.post('/device-router/probe', probeEndpoint);
-await app.register(middleware);
+app.addHook('preHandler', middleware);
 
 app.get('/', (req, reply) => {
   const profile = req.deviceProfile;
diff --git a/examples/fastify-basic/src/server.ts b/examples/fastify-basic/src/server.ts
index a66052c..dbd3e16 100644
--- a/examples/fastify-basic/src/server.ts
+++ b/examples/fastify-basic/src/server.ts
@@ -31,8 +31,8 @@ app.get('/device-router-probe.min.js', (_req, reply) => {
   reply.type('application/javascript').send(script);
 });
 
-// Register the device-router middleware (adds preHandler hook)
-await app.register(middleware);
+// Register the device-router preHandler hook
+app.addHook('preHandler', middleware);
 
 // Routes
 app.get('/', (req, reply) => {
diff --git a/packages/middleware-fastify/README.md b/packages/middleware-fastify/README.md
index 6da8efb..99f73ce 100644
--- a/packages/middleware-fastify/README.md
+++ b/packages/middleware-fastify/README.md
@@ -28,9 +28,9 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 });
 
 await app.register(cookie);
-await app.register(middleware);
 
 app.post('/device-router/probe', probeEndpoint);
+app.addHook('preHandler', middleware);
 
 app.get('/', (req, reply) => {
   const profile = req.deviceProfile;
@@ -50,7 +50,7 @@ app.listen({ port: 3000 });
 ## How it works
 
 1. **Probe endpoint** receives device signals from the browser and stores a classified profile
-2. **Middleware** registers a `preHandler` hook that reads the session cookie, loads the profile from storage, and attaches it to `req.deviceProfile`
+2. **Middleware** is a `preHandler` hook that reads the session cookie, loads the profile from storage, and attaches it to `req.deviceProfile`
 3. Your route handlers use `req.deviceProfile.hints` and `req.deviceProfile.tiers` to adapt responses
 
 ## Probe auto-injection
@@ -65,7 +65,14 @@ const { middleware, probeEndpoint, injectionMiddleware } = createDeviceRouter({
 });
 ```
 
-When `injectProbe` is enabled, the middleware registers an `onSend` hook that injects the script before `</head>`.
+When `injectProbe` is enabled, `injectionMiddleware` is returned as an `onSend` hook. Register it to inject the script before `</head>`:
+
+```typescript
+app.addHook('preHandler', middleware);
+if (injectionMiddleware) {
+  app.addHook('onSend', injectionMiddleware);
+}
+```
 
 > **Streaming responses:** The `onSend` hook receives the serialized payload as a string. If you stream responses via `reply.raw`, the hook is bypassed and injection is skipped. Add the probe `<script>` tag to your HTML shell manually instead.
 
diff --git a/packages/middleware-fastify/package.json b/packages/middleware-fastify/package.json
index cdd4337..2ed1eed 100644
--- a/packages/middleware-fastify/package.json
+++ b/packages/middleware-fastify/package.json
@@ -2,7 +2,7 @@
   "name": "@device-router/middleware-fastify",
   "version": "0.4.0",
   "type": "module",
-  "description": "Fastify plugin for DeviceRouter — device classification and rendering hints per request",
+  "description": "Fastify middleware for DeviceRouter — device classification and rendering hints per request",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,7 +16,6 @@
   "keywords": [
     "device-router",
     "fastify",
-    "fastify-plugin",
     "device-detection",
     "server-side-rendering"
   ],
@@ -62,7 +61,6 @@
   "devDependencies": {
     "@device-router/probe": "workspace:*",
     "@fastify/cookie": "^11.0.1",
-    "fastify": "^5.2.1",
-    "fastify-plugin": "^5.0.1"
+    "fastify": "^5.2.1"
   }
 }
diff --git a/packages/middleware-fastify/src/__tests__/diagnostics.test.ts b/packages/middleware-fastify/src/__tests__/diagnostics.test.ts
index a341bfa..523ae43 100644
--- a/packages/middleware-fastify/src/__tests__/diagnostics.test.ts
+++ b/packages/middleware-fastify/src/__tests__/diagnostics.test.ts
@@ -66,7 +66,7 @@ describe('diagnostics (fastify)', () => {
       await app.register(cookie);
 
       const { middleware } = createDeviceRouter({ storage });
-      await app.register(middleware);
+      app.addHook('preHandler', middleware);
       app.get('/test', (_req, reply) => reply.send({ ok: true }));
 
       await app.listen({ port: 0 });
@@ -94,7 +94,7 @@ describe('diagnostics (fastify)', () => {
 
       const { middleware, probeEndpoint } = createDeviceRouter({ storage });
       app.post('/device-router/probe', probeEndpoint);
-      await app.register(middleware);
+      app.addHook('preHandler', middleware);
       app.get('/test', (_req, reply) => reply.send({ ok: true }));
 
       await app.listen({ port: 0 });
@@ -128,7 +128,7 @@ describe('diagnostics (fastify)', () => {
       await app.register(cookie);
 
       const { middleware } = createDeviceRouter({ storage });
-      await app.register(middleware);
+      app.addHook('preHandler', middleware);
       app.get('/test', (_req, reply) => reply.send({ ok: true }));
 
       await app.listen({ port: 0 });
@@ -151,7 +151,7 @@ describe('diagnostics (fastify)', () => {
       await app.register(cookie);
 
       const { middleware } = createDeviceRouter({ storage });
-      await app.register(middleware);
+      app.addHook('preHandler', middleware);
       app.get('/test', (_req, reply) => reply.send({ ok: true }));
 
       await app.listen({ port: 0 });
@@ -178,7 +178,7 @@ describe('diagnostics (fastify)', () => {
       await app.register(cookie);
 
       const { middleware } = createDeviceRouter({ storage, onEvent });
-      await app.register(middleware);
+      app.addHook('preHandler', middleware);
       app.get('/test', (_req, reply) => reply.send({ ok: true }));
 
       await app.listen({ port: 0 });
diff --git a/packages/middleware-fastify/src/__tests__/integration.test.ts b/packages/middleware-fastify/src/__tests__/integration.test.ts
index 65c0a17..79a1e9b 100644
--- a/packages/middleware-fastify/src/__tests__/integration.test.ts
+++ b/packages/middleware-fastify/src/__tests__/integration.test.ts
@@ -18,7 +18,7 @@ describe('integration: probe → middleware → route (fastify)', () => {
     const { middleware, probeEndpoint } = createDeviceRouter({ storage });
 
     app.post('/device-router/probe', probeEndpoint);
-    await app.register(middleware);
+    app.addHook('preHandler', middleware);
 
     app.get('/test', (req, reply) => {
       if (req.deviceProfile) {
@@ -87,12 +87,15 @@ describe('integration: probe injection (fastify)', () => {
     app = Fastify();
     await app.register(cookie);
 
-    const { middleware } = createDeviceRouter({
+    const { middleware, injectionMiddleware } = createDeviceRouter({
       storage,
       injectProbe: true,
     });
 
-    await app.register(middleware);
+    app.addHook('preHandler', middleware);
+    if (injectionMiddleware) {
+      app.addHook('onSend', injectionMiddleware);
+    }
 
     app.get('/html', (_req, reply) => {
       reply.type('text/html').send('<html><head><title>Test</title></head><body></body></html>');
diff --git a/packages/middleware-fastify/src/index.ts b/packages/middleware-fastify/src/index.ts
index ea66c9e..5b90239 100644
--- a/packages/middleware-fastify/src/index.ts
+++ b/packages/middleware-fastify/src/index.ts
@@ -4,7 +4,6 @@ import type { StorageAdapter } from '@device-router/storage';
 import type { TierThresholds, FallbackProfile, OnEventCallback } from '@device-router/types';
 import { createProbeHealthCheck } from '@device-router/types';
 import type { FastifyRequest, FastifyReply } from 'fastify';
-import fp from 'fastify-plugin';
 import { createMiddleware } from './middleware.js';
 import { createProbeEndpoint } from './endpoint.js';
 import { createInjectionMiddleware } from './inject.js';
@@ -78,16 +77,6 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
     });
   }
 
-  const middleware = fp(
-    async (fastify) => {
-      fastify.addHook('preHandler', hook);
-      if (injectionMiddleware) {
-        fastify.addHook('onSend', injectionMiddleware);
-      }
-    },
-    { name: 'device-router' },
-  );
-
   const rawEndpoint = createProbeEndpoint({
     storage,
     cookieName,
@@ -99,7 +88,7 @@ export function createDeviceRouter(options: DeviceRouterOptions) {
   });
 
   return {
-    middleware,
+    middleware: hook,
     probeEndpoint: health
       ? async (req: FastifyRequest, reply: FastifyReply) => {
           health.onProbeReceived();
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e519695..517b6e0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -207,9 +207,6 @@ importers:
       fastify:
         specifier: ^5.2.1
         version: 5.7.4
-      fastify-plugin:
-        specifier: ^5.0.1
-        version: 5.1.0
 
   packages/middleware-hono:
     dependencies:

From 715d362fc412e303c4fb3f7f7a97aca8d803e12d Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Tue, 24 Feb 2026 14:43:48 +0100
Subject: [PATCH 03/12] Rename ConnectionTier value 'fast' to 'high' (#30)

Aligns connection tier vocabulary with CPU, memory, and GPU tiers
which all use 'low' | 'mid' | 'high'.
---
 CHANGELOG.md                                  |  1 +
 docs/DeviceRouter_PRD.md                      |  2 +-
 docs/api/types.md                             |  6 ++---
 docs/getting-started.md                       |  2 +-
 docs/profile-schema.md                        |  2 +-
 examples/shared/demo-template.ts              |  2 +-
 .../src/__tests__/middleware.test.ts          |  2 +-
 .../src/__tests__/middleware.test.ts          |  2 +-
 .../src/__tests__/middleware.test.ts          |  2 +-
 .../src/__tests__/middleware.test.ts          |  2 +-
 packages/types/README.md                      |  4 ++--
 packages/types/src/__tests__/classify.test.ts | 10 ++++----
 packages/types/src/__tests__/events.test.ts   |  2 +-
 packages/types/src/__tests__/headers.test.ts  |  8 +++----
 packages/types/src/__tests__/hints.test.ts    | 24 +++++++++----------
 packages/types/src/classify.ts                |  6 ++---
 packages/types/src/headers.ts                 |  2 +-
 packages/types/src/profile.ts                 |  2 +-
 18 files changed, 41 insertions(+), 40 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8624e81..ef4cfae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Breaking Changes
 
+- **Rename `ConnectionTier` value `'fast'` → `'high'`** — Aligns connection tier vocabulary with CPU, memory, and GPU tiers which all use `'low' | 'mid' | 'high'`. Update any code comparing `tiers.connection === 'fast'` to use `'high'` instead
 - **middleware-fastify: normalized return shape** — `createDeviceRouter()` now returns raw Fastify hooks instead of a `fastify-plugin` wrapped plugin. Migrate `await app.register(middleware)` → `app.addHook('preHandler', middleware)`. When using `injectProbe: true`, register the injection hook separately: `app.addHook('onSend', injectionMiddleware)`. Removed `fastify-plugin` dependency
 
 ### Features
diff --git a/docs/DeviceRouter_PRD.md b/docs/DeviceRouter_PRD.md
index 8e384d6..382c7c9 100644
--- a/docs/DeviceRouter_PRD.md
+++ b/docs/DeviceRouter_PRD.md
@@ -125,7 +125,7 @@ Language-specific adapters that sit in the request pipeline. On each incoming re
 The capability object exposes three abstraction levels:
 
 - **Raw signals:** the actual values collected by the probe (e.g. `hardwareConcurrency: 4`).
-- **Inferred tiers:** normalised classifications (`cpu: 'low' | 'mid' | 'high'`, `connection: '2g' | '3g' | '4g' | 'fast'`).
+- **Inferred tiers:** normalised classifications (`cpu: 'low' | 'mid' | 'high'`, `connection: '2g' | '3g' | '4g' | 'high'`).
 - **Rendering hints:** opinionated suggestions (`deferHeavyComponents: true`, `serveMinimalCSS: true`) derived from the tier data.
 
 **Official adapters for v1:** Node.js / Express, Node.js / Fastify, Python / FastAPI, Python / Django, Go / net/http.
diff --git a/docs/api/types.md b/docs/api/types.md
index d1e857b..83de3c4 100644
--- a/docs/api/types.md
+++ b/docs/api/types.md
@@ -14,7 +14,7 @@ const tiers = classify({
   deviceMemory: 8,
   connection: { effectiveType: '4g', downlink: 50 },
 });
-// { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'none' }
+// { cpu: 'high', memory: 'high', connection: 'high', gpu: 'none' }
 ```
 
 ### `deriveHints(tiers: DeviceTiers, signals?: RawSignals): RenderingHints`
@@ -100,7 +100,7 @@ const tiers = classifyFromHeaders({
 });
 // Mobile UA → { cpu: 'low', memory: 'low', connection: '4g', gpu: 'mid' }
 // Tablet UA → { cpu: 'mid', memory: 'mid', connection: '4g', gpu: 'mid' }
-// Desktop UA → { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'mid' }
+// Desktop UA → { cpu: 'high', memory: 'high', connection: 'high', gpu: 'mid' }
 ```
 
 Client Hints refine the base classification when present:
@@ -130,7 +130,7 @@ Preset `DeviceTiers` for a conservative (low-end) assumption: `{ cpu: 'low', mem
 
 ### `OPTIMISTIC_TIERS`
 
-Preset `DeviceTiers` for an optimistic (high-end) assumption: `{ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'mid' }`.
+Preset `DeviceTiers` for an optimistic (high-end) assumption: `{ cpu: 'high', memory: 'high', connection: 'high', gpu: 'mid' }`.
 
 ### `ACCEPT_CH_VALUE`
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index ae9950d..201dd49 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -357,7 +357,7 @@ The middleware classifies devices into tiers based on collected signals:
 | None | —         | —      | —          | No WebGL                      |
 | Low  | 1-2 cores | ≤2 GB  | 2g         | Software renderer             |
 | Mid  | 3-4 cores | 2-4 GB | 3g, 4g     | Integrated / older discrete   |
-| High | 5+ cores  | >4 GB  | fast       | RTX, RX 5000+, Apple M-series |
+| High | 5+ cores  | >4 GB  | high       | RTX, RX 5000+, Apple M-series |
 
 ## Rendering Hints
 
diff --git a/docs/profile-schema.md b/docs/profile-schema.md
index d243978..5019ae5 100644
--- a/docs/profile-schema.md
+++ b/docs/profile-schema.md
@@ -44,7 +44,7 @@ All fields are optional — the probe collects what it can based on browser API
 | ------------ | ------------------------------------ | ---------------------------------- |
 | `cpu`        | `'low' \| 'mid' \| 'high'`           | CPU tier based on core count       |
 | `memory`     | `'low' \| 'mid' \| 'high'`           | Memory tier based on device memory |
-| `connection` | `'2g' \| '3g' \| '4g' \| 'fast'`     | Connection tier                    |
+| `connection` | `'2g' \| '3g' \| '4g' \| 'high'`     | Connection tier                    |
 | `gpu`        | `'none' \| 'low' \| 'mid' \| 'high'` | GPU tier based on renderer string  |
 
 ## ClassifiedProfile (derived)
diff --git a/examples/shared/demo-template.ts b/examples/shared/demo-template.ts
index fe58588..b2c4d6d 100644
--- a/examples/shared/demo-template.ts
+++ b/examples/shared/demo-template.ts
@@ -50,7 +50,7 @@ export function renderDemoPage({
 
   // Connection tier -> badge class
   const connClass = profile
-    ? profile.tiers.connection === 'fast' || profile.tiers.connection === '4g'
+    ? profile.tiers.connection === 'high' || profile.tiers.connection === '4g'
       ? 'high'
       : profile.tiers.connection === '3g'
         ? 'mid'
diff --git a/packages/middleware-express/src/__tests__/middleware.test.ts b/packages/middleware-express/src/__tests__/middleware.test.ts
index 05ac106..215638c 100644
--- a/packages/middleware-express/src/__tests__/middleware.test.ts
+++ b/packages/middleware-express/src/__tests__/middleware.test.ts
@@ -170,7 +170,7 @@ describe('createMiddleware', () => {
       expect(req.deviceProfile!.source).toBe('fallback');
       expect(req.deviceProfile!.tiers.cpu).toBe('high');
       expect(req.deviceProfile!.tiers.memory).toBe('high');
-      expect(req.deviceProfile!.tiers.connection).toBe('fast');
+      expect(req.deviceProfile!.tiers.connection).toBe('high');
     });
 
     it('returns custom DeviceTiers fallback', async () => {
diff --git a/packages/middleware-fastify/src/__tests__/middleware.test.ts b/packages/middleware-fastify/src/__tests__/middleware.test.ts
index c62d78b..6d8aff7 100644
--- a/packages/middleware-fastify/src/__tests__/middleware.test.ts
+++ b/packages/middleware-fastify/src/__tests__/middleware.test.ts
@@ -136,7 +136,7 @@ describe('createMiddleware', () => {
 
       expect(req.deviceProfile!.source).toBe('fallback');
       expect(req.deviceProfile!.tiers.cpu).toBe('high');
-      expect(req.deviceProfile!.tiers.connection).toBe('fast');
+      expect(req.deviceProfile!.tiers.connection).toBe('high');
     });
 
     it('returns custom DeviceTiers fallback', async () => {
diff --git a/packages/middleware-hono/src/__tests__/middleware.test.ts b/packages/middleware-hono/src/__tests__/middleware.test.ts
index 793cb2c..83255ef 100644
--- a/packages/middleware-hono/src/__tests__/middleware.test.ts
+++ b/packages/middleware-hono/src/__tests__/middleware.test.ts
@@ -116,7 +116,7 @@ describe('createMiddleware (hono)', () => {
       const data = (await res.json()) as ClassifiedProfile;
       expect(data.source).toBe('fallback');
       expect(data.tiers.cpu).toBe('high');
-      expect(data.tiers.connection).toBe('fast');
+      expect(data.tiers.connection).toBe('high');
     });
 
     it('returns custom DeviceTiers fallback', async () => {
diff --git a/packages/middleware-koa/src/__tests__/middleware.test.ts b/packages/middleware-koa/src/__tests__/middleware.test.ts
index 02fc103..267efbc 100644
--- a/packages/middleware-koa/src/__tests__/middleware.test.ts
+++ b/packages/middleware-koa/src/__tests__/middleware.test.ts
@@ -148,7 +148,7 @@ describe('createMiddleware (koa)', () => {
 
       expect(ctx.state.deviceProfile!.source).toBe('fallback');
       expect(ctx.state.deviceProfile!.tiers.cpu).toBe('high');
-      expect(ctx.state.deviceProfile!.tiers.connection).toBe('fast');
+      expect(ctx.state.deviceProfile!.tiers.connection).toBe('high');
     });
 
     it('returns custom DeviceTiers fallback', async () => {
diff --git a/packages/types/README.md b/packages/types/README.md
index 2e4063f..ce680b4 100644
--- a/packages/types/README.md
+++ b/packages/types/README.md
@@ -21,7 +21,7 @@ const tiers = classify({
   connection: { effectiveType: '4g', downlink: 50 },
   gpuRenderer: 'ANGLE (Apple, Apple M2 Pro, OpenGL 4.1)',
 });
-// { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' }
+// { cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' }
 ```
 
 ### Derive rendering hints
@@ -103,7 +103,7 @@ if (isValidSignals(requestBody)) {
 | -------------- | ----------------- | ------------ | ----------------------------- |
 | **CPU**        | 1-2 cores         | 3-4 cores    | 5+ cores                      |
 | **Memory**     | <=2 GB            | 2-4 GB       | >4 GB                         |
-| **Connection** | 2G                | 3G / slow 4G | Fast 4G+ (>=5 Mbps)           |
+| **Connection** | 2G                | 3G / slow 4G | 4G+ (>=5 Mbps)                |
 | **GPU**        | Software renderer | Mid-range    | RTX, RX 5000+, Apple M-series |
 
 ## Exports
diff --git a/packages/types/src/__tests__/classify.test.ts b/packages/types/src/__tests__/classify.test.ts
index 75d8751..1ac9116 100644
--- a/packages/types/src/__tests__/classify.test.ts
+++ b/packages/types/src/__tests__/classify.test.ts
@@ -81,14 +81,14 @@ describe('classifyConnection', () => {
   });
 
   it('returns fast for 4g with high downlink', () => {
-    expect(classifyConnection('4g', 10)).toBe('fast');
+    expect(classifyConnection('4g', 10)).toBe('high');
   });
 
   it('classifies by downlink alone when no effectiveType', () => {
     expect(classifyConnection(undefined, 0.3)).toBe('2g');
     expect(classifyConnection(undefined, 1)).toBe('3g');
     expect(classifyConnection(undefined, 3)).toBe('4g');
-    expect(classifyConnection(undefined, 10)).toBe('fast');
+    expect(classifyConnection(undefined, 10)).toBe('high');
   });
 
   it('uses custom downlink thresholds', () => {
@@ -99,7 +99,7 @@ describe('classifyConnection', () => {
 
     // Custom 4g upper bound
     expect(classifyConnection(undefined, 8, { downlink4gUpperBound: 10 })).toBe('4g');
-    expect(classifyConnection(undefined, 8)).toBe('fast');
+    expect(classifyConnection(undefined, 8)).toBe('high');
   });
 
   it('effectiveType string matches are not affected by thresholds', () => {
@@ -181,7 +181,7 @@ describe('classify', () => {
       deviceMemory: 8,
       connection: { effectiveType: '4g', downlink: 50 },
     });
-    expect(result).toEqual({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'none' });
+    expect(result).toEqual({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'none' });
   });
 
   it('classifies with missing signals', () => {
@@ -207,7 +207,7 @@ describe('classify', () => {
         connection: { downlink4gUpperBound: 3 },
       },
     );
-    expect(result).toEqual({ cpu: 'low', memory: 'low', connection: 'fast', gpu: 'none' });
+    expect(result).toEqual({ cpu: 'low', memory: 'low', connection: 'high', gpu: 'none' });
   });
 
   it('applies custom GPU thresholds', () => {
diff --git a/packages/types/src/__tests__/events.test.ts b/packages/types/src/__tests__/events.test.ts
index f12691e..d09bb5a 100644
--- a/packages/types/src/__tests__/events.test.ts
+++ b/packages/types/src/__tests__/events.test.ts
@@ -5,7 +5,7 @@ import type { DeviceRouterEvent } from '../events.js';
 const sampleEvent: DeviceRouterEvent = {
   type: 'profile:classify',
   sessionToken: 'tok1',
-  tiers: { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'mid' },
+  tiers: { cpu: 'high', memory: 'high', connection: 'high', gpu: 'mid' },
   hints: {
     deferHeavyComponents: false,
     serveMinimalCSS: false,
diff --git a/packages/types/src/__tests__/headers.test.ts b/packages/types/src/__tests__/headers.test.ts
index 307376b..5a8653e 100644
--- a/packages/types/src/__tests__/headers.test.ts
+++ b/packages/types/src/__tests__/headers.test.ts
@@ -8,7 +8,7 @@ describe('classifyFromHeaders', () => {
       'user-agent':
         'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/120.0.0.0',
     });
-    expect(tiers).toEqual({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'mid' });
+    expect(tiers).toEqual({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'mid' });
   });
 
   it('classifies iPhone UA as mobile', () => {
@@ -47,13 +47,13 @@ describe('classifyFromHeaders', () => {
     expect(classifyFromHeaders({})).toEqual({
       cpu: 'high',
       memory: 'high',
-      connection: 'fast',
+      connection: 'high',
       gpu: 'mid',
     });
     expect(classifyFromHeaders({ 'user-agent': '' })).toEqual({
       cpu: 'high',
       memory: 'high',
-      connection: 'fast',
+      connection: 'high',
       gpu: 'mid',
     });
   });
@@ -175,7 +175,7 @@ describe('preset constants', () => {
     expect(OPTIMISTIC_TIERS).toEqual({
       cpu: 'high',
       memory: 'high',
-      connection: 'fast',
+      connection: 'high',
       gpu: 'mid',
     });
   });
diff --git a/packages/types/src/__tests__/hints.test.ts b/packages/types/src/__tests__/hints.test.ts
index 4c0e0a4..ba37244 100644
--- a/packages/types/src/__tests__/hints.test.ts
+++ b/packages/types/src/__tests__/hints.test.ts
@@ -16,7 +16,7 @@ describe('deriveHints', () => {
   });
 
   it('returns permissive hints for high-end device', () => {
-    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' });
+    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' });
     expect(hints).toEqual({
       deferHeavyComponents: false,
       serveMinimalCSS: false,
@@ -30,7 +30,7 @@ describe('deriveHints', () => {
 
   it('respects prefersReducedMotion signal', () => {
     const hints = deriveHints(
-      { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' },
+      { cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' },
       { prefersReducedMotion: true },
     );
     expect(hints.reduceAnimations).toBe(true);
@@ -46,34 +46,34 @@ describe('deriveHints', () => {
   });
 
   it('serves minimal CSS for low CPU regardless of connection', () => {
-    const hints = deriveHints({ cpu: 'low', memory: 'high', connection: 'fast', gpu: 'high' });
+    const hints = deriveHints({ cpu: 'low', memory: 'high', connection: 'high', gpu: 'high' });
     expect(hints.serveMinimalCSS).toBe(true);
     expect(hints.preferServerRendering).toBe(true);
   });
 
   it('disables 3d effects for no GPU', () => {
-    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'none' });
+    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'none' });
     expect(hints.disable3dEffects).toBe(true);
   });
 
   it('disables 3d effects for low GPU', () => {
-    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'low' });
+    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'low' });
     expect(hints.disable3dEffects).toBe(true);
   });
 
   it('enables 3d effects for mid GPU', () => {
-    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'mid' });
+    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'mid' });
     expect(hints.disable3dEffects).toBe(false);
   });
 
   it('enables 3d effects for high GPU', () => {
-    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' });
+    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' });
     expect(hints.disable3dEffects).toBe(false);
   });
 
   it('constrains hints on low battery unplugged even for high-end device', () => {
     const hints = deriveHints(
-      { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' },
+      { cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' },
       { battery: { level: 0.08, charging: false } },
     );
     expect(hints.deferHeavyComponents).toBe(true);
@@ -88,7 +88,7 @@ describe('deriveHints', () => {
 
   it('does not constrain when low battery but charging', () => {
     const hints = deriveHints(
-      { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' },
+      { cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' },
       { battery: { level: 0.05, charging: true } },
     );
     expect(hints.deferHeavyComponents).toBe(false);
@@ -98,7 +98,7 @@ describe('deriveHints', () => {
 
   it('does not constrain when battery above threshold', () => {
     const hints = deriveHints(
-      { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' },
+      { cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' },
       { battery: { level: 0.5, charging: false } },
     );
     expect(hints.deferHeavyComponents).toBe(false);
@@ -107,7 +107,7 @@ describe('deriveHints', () => {
   });
 
   it('does not change behavior when battery signal is absent', () => {
-    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' }, {});
+    const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' }, {});
     expect(hints.deferHeavyComponents).toBe(false);
     expect(hints.reduceAnimations).toBe(false);
     expect(hints.disableAutoplay).toBe(false);
@@ -115,7 +115,7 @@ describe('deriveHints', () => {
 
   it('does not constrain at exactly 0.15 (strict less-than)', () => {
     const hints = deriveHints(
-      { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'high' },
+      { cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' },
       { battery: { level: 0.15, charging: false } },
     );
     expect(hints.deferHeavyComponents).toBe(false);
diff --git a/packages/types/src/classify.ts b/packages/types/src/classify.ts
index c646d0b..323d8fa 100644
--- a/packages/types/src/classify.ts
+++ b/packages/types/src/classify.ts
@@ -47,12 +47,12 @@ export function classifyConnection(
   if (effectiveType === 'slow-2g' || effectiveType === '2g') return '2g';
   if (effectiveType === '3g') return '3g';
   if (effectiveType === '4g' && downlink != null && downlink < downlink4gUpperBound) return '4g';
-  if (effectiveType === '4g') return 'fast';
+  if (effectiveType === '4g') return 'high';
   if (downlink != null) {
     if (downlink < downlink2gUpperBound) return '2g';
     if (downlink < downlink3gUpperBound) return '3g';
     if (downlink < downlink4gUpperBound) return '4g';
-    return 'fast';
+    return 'high';
   }
   return '4g';
 }
@@ -91,6 +91,6 @@ export const CONSERVATIVE_TIERS: DeviceTiers = {
 export const OPTIMISTIC_TIERS: DeviceTiers = {
   cpu: 'high',
   memory: 'high',
-  connection: 'fast',
+  connection: 'high',
   gpu: 'mid',
 };
diff --git a/packages/types/src/headers.ts b/packages/types/src/headers.ts
index f24283b..00179b2 100644
--- a/packages/types/src/headers.ts
+++ b/packages/types/src/headers.ts
@@ -20,7 +20,7 @@ export function classifyFromHeaders(headers: Record<string, string | undefined>)
   } else if (TABLET_UA.test(ua)) {
     tiers = { cpu: 'mid', memory: 'mid', connection: '4g', gpu: 'mid' };
   } else {
-    tiers = { cpu: 'high', memory: 'high', connection: 'fast', gpu: 'mid' };
+    tiers = { cpu: 'high', memory: 'high', connection: 'high', gpu: 'mid' };
   }
 
   if (deviceMemory) {
diff --git a/packages/types/src/profile.ts b/packages/types/src/profile.ts
index ab68997..fc100b5 100644
--- a/packages/types/src/profile.ts
+++ b/packages/types/src/profile.ts
@@ -35,7 +35,7 @@ export interface DeviceProfile {
 
 export type CpuTier = 'low' | 'mid' | 'high';
 export type MemoryTier = 'low' | 'mid' | 'high';
-export type ConnectionTier = '2g' | '3g' | '4g' | 'fast';
+export type ConnectionTier = '2g' | '3g' | '4g' | 'high';
 export type GpuTier = 'none' | 'low' | 'mid' | 'high';
 
 export interface DeviceTiers {

From 0223ff7c29fd0469eb91a7fadd411d86f406713a Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Tue, 24 Feb 2026 15:19:29 +0100
Subject: [PATCH 04/12] Narrow classify() and deriveHints() to StoredSignals
 (#31)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Narrow classify() and deriveHints() to accept StoredSignals

Neither function uses userAgent or viewport, which are stripped before
storage. Accepting RawSignals made the API claim those fields were
relevant when they never were. StoredSignals is the honest contract.

* Narrow profile:store event to StoredSignals

The event emitted the raw probe payload (with userAgent/viewport)
but is named 'profile:store' — it should carry what was actually
stored. Endpoints now emit storedSignals, and the event type matches.

* Test that profile:store event strips userAgent and viewport

Verifies all four middleware endpoints emit StoredSignals (without
userAgent/viewport) in the profile:store event, not the raw probe payload.
---
 CHANGELOG.md                                  |  2 ++
 docs/api/types.md                             |  8 +++---
 .../src/__tests__/endpoint.test.ts            | 25 +++++++++++++++++++
 packages/middleware-express/src/endpoint.ts   |  7 +++++-
 .../src/__tests__/endpoint.test.ts            | 21 ++++++++++++++++
 packages/middleware-fastify/src/endpoint.ts   |  7 +++++-
 .../src/__tests__/endpoint.test.ts            | 25 +++++++++++++++++++
 packages/middleware-hono/src/endpoint.ts      |  7 +++++-
 .../src/__tests__/endpoint.test.ts            | 24 ++++++++++++++++++
 packages/middleware-koa/src/endpoint.ts       |  7 +++++-
 packages/types/src/classify.ts                |  4 +--
 packages/types/src/events.ts                  | 10 ++++++--
 packages/types/src/hints.ts                   |  4 +--
 13 files changed, 137 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef4cfae..1bf3457 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,8 @@
 ### Breaking Changes
 
 - **Rename `ConnectionTier` value `'fast'` → `'high'`** — Aligns connection tier vocabulary with CPU, memory, and GPU tiers which all use `'low' | 'mid' | 'high'`. Update any code comparing `tiers.connection === 'fast'` to use `'high'` instead
+- **`classify()` and `deriveHints()` now accept `StoredSignals` instead of `RawSignals`** — These functions never used `userAgent` or `viewport` (which are stripped before storage). The narrower type makes the API honest. Existing call sites are unaffected — `RawSignals` is structurally assignable to `StoredSignals`
+- **`profile:store` event now carries `StoredSignals` instead of `RawSignals`** — The event previously emitted the raw probe payload (including `userAgent`/`viewport`), not what was actually stored. The `signals` field now matches the persisted data. `bot:reject` still carries `RawSignals` (it fires before stripping)
 - **middleware-fastify: normalized return shape** — `createDeviceRouter()` now returns raw Fastify hooks instead of a `fastify-plugin` wrapped plugin. Migrate `await app.register(middleware)` → `app.addHook('preHandler', middleware)`. When using `injectProbe: true`, register the injection hook separately: `app.addHook('onSend', injectionMiddleware)`. Removed `fastify-plugin` dependency
 
 ### Features
diff --git a/docs/api/types.md b/docs/api/types.md
index 83de3c4..eed5b11 100644
--- a/docs/api/types.md
+++ b/docs/api/types.md
@@ -2,9 +2,9 @@
 
 ## Functions
 
-### `classify(signals: RawSignals): DeviceTiers`
+### `classify(signals: StoredSignals): DeviceTiers`
 
-Classifies raw device signals into capability tiers.
+Classifies device signals into capability tiers.
 
 ```typescript
 import { classify } from '@device-router/types';
@@ -17,7 +17,7 @@ const tiers = classify({
 // { cpu: 'high', memory: 'high', connection: 'high', gpu: 'none' }
 ```
 
-### `deriveHints(tiers: DeviceTiers, signals?: RawSignals): RenderingHints`
+### `deriveHints(tiers: DeviceTiers, signals?: StoredSignals): RenderingHints`
 
 Derives rendering hints from device tiers.
 
@@ -224,7 +224,7 @@ type DeviceRouterEvent =
       source: ProfileSource;
       durationMs: number;
     }
-  | { type: 'profile:store'; sessionToken: string; signals: RawSignals; durationMs: number }
+  | { type: 'profile:store'; sessionToken: string; signals: StoredSignals; durationMs: number }
   | { type: 'bot:reject'; sessionToken: string; signals: RawSignals }
   | { type: 'error'; error: unknown; phase: 'middleware' | 'endpoint'; sessionToken?: string };
 ```
diff --git a/packages/middleware-express/src/__tests__/endpoint.test.ts b/packages/middleware-express/src/__tests__/endpoint.test.ts
index 691c259..ec62822 100644
--- a/packages/middleware-express/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-express/src/__tests__/endpoint.test.ts
@@ -256,6 +256,31 @@ describe('createProbeEndpoint', () => {
       expect(typeof event.durationMs).toBe('number');
     });
 
+    it('strips userAgent and viewport from profile:store signals', async () => {
+      const events: DeviceRouterEvent[] = [];
+      const onEvent = vi.fn((e: DeviceRouterEvent) => {
+        events.push(e);
+      });
+
+      const handler = createProbeEndpoint({ storage, onEvent });
+      const req = createMockReq({
+        hardwareConcurrency: 4,
+        userAgent: 'Mozilla/5.0 Test',
+        viewport: { width: 1920, height: 1080 },
+      });
+      const res = createMockRes();
+
+      await handler(req, res);
+
+      const event = events.find((e) => e.type === 'profile:store') as Extract<
+        DeviceRouterEvent,
+        { type: 'profile:store' }
+      >;
+      expect(event.signals).toEqual({ hardwareConcurrency: 4 });
+      expect(event.signals).not.toHaveProperty('userAgent');
+      expect(event.signals).not.toHaveProperty('viewport');
+    });
+
     it('emits bot:reject when bot detected', async () => {
       const events: DeviceRouterEvent[] = [];
       const onEvent = vi.fn((e: DeviceRouterEvent) => {
diff --git a/packages/middleware-express/src/endpoint.ts b/packages/middleware-express/src/endpoint.ts
index cc8e4e7..68044bf 100644
--- a/packages/middleware-express/src/endpoint.ts
+++ b/packages/middleware-express/src/endpoint.ts
@@ -63,7 +63,12 @@ export function createProbeEndpoint(options: EndpointOptions) {
       await storage.set(sessionToken, profile, ttl);
       const durationMs = performance.now() - start;
 
-      emitEvent(onEvent, { type: 'profile:store', sessionToken, signals, durationMs });
+      emitEvent(onEvent, {
+        type: 'profile:store',
+        sessionToken,
+        signals: storedSignals,
+        durationMs,
+      });
 
       res.cookie(cookieName, sessionToken, {
         path: cookiePath,
diff --git a/packages/middleware-fastify/src/__tests__/endpoint.test.ts b/packages/middleware-fastify/src/__tests__/endpoint.test.ts
index aef1104..cc10fc3 100644
--- a/packages/middleware-fastify/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-fastify/src/__tests__/endpoint.test.ts
@@ -215,6 +215,27 @@ describe('createProbeEndpoint', () => {
       );
     });
 
+    it('strips userAgent and viewport from profile:store signals', async () => {
+      const onEvent = vi.fn();
+      const handler = createProbeEndpoint({ storage, onEvent });
+      const req = createMockReq({
+        hardwareConcurrency: 4,
+        userAgent: 'Mozilla/5.0 Test',
+        viewport: { width: 1920, height: 1080 },
+      });
+      const reply = createMockReply();
+
+      await handler(req, reply);
+
+      const event = onEvent.mock.calls[0][0] as Extract<
+        DeviceRouterEvent,
+        { type: 'profile:store' }
+      >;
+      expect(event.signals).toEqual({ hardwareConcurrency: 4 });
+      expect(event.signals).not.toHaveProperty('userAgent');
+      expect(event.signals).not.toHaveProperty('viewport');
+    });
+
     it('emits bot:reject when bot detected', async () => {
       const onEvent = vi.fn();
       const handler = createProbeEndpoint({ storage, onEvent });
diff --git a/packages/middleware-fastify/src/endpoint.ts b/packages/middleware-fastify/src/endpoint.ts
index 132806d..aa719a4 100644
--- a/packages/middleware-fastify/src/endpoint.ts
+++ b/packages/middleware-fastify/src/endpoint.ts
@@ -64,7 +64,12 @@ export function createProbeEndpoint(options: EndpointOptions) {
       await storage.set(sessionToken, profile, ttl);
       const durationMs = performance.now() - start;
 
-      emitEvent(onEvent, { type: 'profile:store', sessionToken, signals, durationMs });
+      emitEvent(onEvent, {
+        type: 'profile:store',
+        sessionToken,
+        signals: storedSignals,
+        durationMs,
+      });
 
       reply.setCookie(cookieName, sessionToken, {
         path: cookiePath,
diff --git a/packages/middleware-hono/src/__tests__/endpoint.test.ts b/packages/middleware-hono/src/__tests__/endpoint.test.ts
index 4133a20..95fa10f 100644
--- a/packages/middleware-hono/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-hono/src/__tests__/endpoint.test.ts
@@ -196,6 +196,31 @@ describe('createProbeEndpoint (hono)', () => {
       expect(typeof (event as { durationMs: number }).durationMs).toBe('number');
     });
 
+    it('strips userAgent and viewport from profile:store signals', async () => {
+      const onEvent = vi.fn();
+      const app = new Hono();
+      app.post('/probe', createProbeEndpoint({ storage, onEvent }));
+
+      const res = await app.request('/probe', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          hardwareConcurrency: 4,
+          userAgent: 'Mozilla/5.0 Test',
+          viewport: { width: 1920, height: 1080 },
+        }),
+      });
+
+      expect(res.status).toBe(200);
+      const event = onEvent.mock.calls[0][0] as Extract<
+        DeviceRouterEvent,
+        { type: 'profile:store' }
+      >;
+      expect(event.signals).toEqual({ hardwareConcurrency: 4 });
+      expect(event.signals).not.toHaveProperty('userAgent');
+      expect(event.signals).not.toHaveProperty('viewport');
+    });
+
     it('emits bot:reject when bot detected', async () => {
       const onEvent = vi.fn();
       const app = new Hono();
diff --git a/packages/middleware-hono/src/endpoint.ts b/packages/middleware-hono/src/endpoint.ts
index 983ecb1..06b18ef 100644
--- a/packages/middleware-hono/src/endpoint.ts
+++ b/packages/middleware-hono/src/endpoint.ts
@@ -66,7 +66,12 @@ export function createProbeEndpoint(options: EndpointOptions): Handler {
       await storage.set(sessionToken, profile, ttl);
       const durationMs = performance.now() - start;
 
-      emitEvent(onEvent, { type: 'profile:store', sessionToken, signals, durationMs });
+      emitEvent(onEvent, {
+        type: 'profile:store',
+        sessionToken,
+        signals: storedSignals,
+        durationMs,
+      });
 
       setCookie(c, cookieName, sessionToken, {
         path: cookiePath,
diff --git a/packages/middleware-koa/src/__tests__/endpoint.test.ts b/packages/middleware-koa/src/__tests__/endpoint.test.ts
index a4f3f4f..17beb22 100644
--- a/packages/middleware-koa/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-koa/src/__tests__/endpoint.test.ts
@@ -189,6 +189,30 @@ describe('createProbeEndpoint (koa)', () => {
       expect(typeof event.durationMs).toBe('number');
     });
 
+    it('strips userAgent and viewport from profile:store signals', async () => {
+      const events: DeviceRouterEvent[] = [];
+      const onEvent = vi.fn((e: DeviceRouterEvent) => {
+        events.push(e);
+      });
+
+      const handler = createProbeEndpoint({ storage, onEvent });
+      const ctx = createMockCtx({
+        hardwareConcurrency: 4,
+        userAgent: 'Mozilla/5.0 Test',
+        viewport: { width: 1920, height: 1080 },
+      });
+
+      await handler(ctx);
+
+      const event = events.find((e) => e.type === 'profile:store') as Extract<
+        DeviceRouterEvent,
+        { type: 'profile:store' }
+      >;
+      expect(event.signals).toEqual({ hardwareConcurrency: 4 });
+      expect(event.signals).not.toHaveProperty('userAgent');
+      expect(event.signals).not.toHaveProperty('viewport');
+    });
+
     it('emits bot:reject when bot detected', async () => {
       const events: DeviceRouterEvent[] = [];
       const onEvent = vi.fn((e: DeviceRouterEvent) => {
diff --git a/packages/middleware-koa/src/endpoint.ts b/packages/middleware-koa/src/endpoint.ts
index b5ada34..2191624 100644
--- a/packages/middleware-koa/src/endpoint.ts
+++ b/packages/middleware-koa/src/endpoint.ts
@@ -65,7 +65,12 @@ export function createProbeEndpoint(options: EndpointOptions) {
       await storage.set(sessionToken, profile, ttl);
       const durationMs = performance.now() - start;
 
-      emitEvent(onEvent, { type: 'profile:store', sessionToken, signals, durationMs });
+      emitEvent(onEvent, {
+        type: 'profile:store',
+        sessionToken,
+        signals: storedSignals,
+        durationMs,
+      });
 
       ctx.cookies.set(cookieName, sessionToken, {
         path: cookiePath,
diff --git a/packages/types/src/classify.ts b/packages/types/src/classify.ts
index 323d8fa..9abca98 100644
--- a/packages/types/src/classify.ts
+++ b/packages/types/src/classify.ts
@@ -1,5 +1,5 @@
 import type {
-  RawSignals,
+  StoredSignals,
   CpuTier,
   MemoryTier,
   ConnectionTier,
@@ -68,7 +68,7 @@ export function classifyGpu(
   return 'mid';
 }
 
-export function classify(signals: RawSignals, thresholds?: TierThresholds): DeviceTiers {
+export function classify(signals: StoredSignals, thresholds?: TierThresholds): DeviceTiers {
   return {
     cpu: classifyCpu(signals.hardwareConcurrency, thresholds?.cpu),
     memory: classifyMemory(signals.deviceMemory, thresholds?.memory),
diff --git a/packages/types/src/events.ts b/packages/types/src/events.ts
index 153feb5..0e16812 100644
--- a/packages/types/src/events.ts
+++ b/packages/types/src/events.ts
@@ -1,4 +1,10 @@
-import type { DeviceTiers, RenderingHints, RawSignals, ProfileSource } from './profile.js';
+import type {
+  DeviceTiers,
+  RenderingHints,
+  StoredSignals,
+  RawSignals,
+  ProfileSource,
+} from './profile.js';
 
 export type DeviceRouterEvent =
   | {
@@ -12,7 +18,7 @@ export type DeviceRouterEvent =
   | {
       type: 'profile:store';
       sessionToken: string;
-      signals: RawSignals;
+      signals: StoredSignals;
       durationMs: number;
     }
   | {
diff --git a/packages/types/src/hints.ts b/packages/types/src/hints.ts
index 4a3cb2c..41dcd69 100644
--- a/packages/types/src/hints.ts
+++ b/packages/types/src/hints.ts
@@ -1,6 +1,6 @@
-import type { DeviceTiers, RenderingHints, RawSignals } from './profile.js';
+import type { DeviceTiers, RenderingHints, StoredSignals } from './profile.js';
 
-export function deriveHints(tiers: DeviceTiers, signals?: RawSignals): RenderingHints {
+export function deriveHints(tiers: DeviceTiers, signals?: StoredSignals): RenderingHints {
   const isLowEnd = tiers.cpu === 'low' || tiers.memory === 'low';
   const isSlowConnection = tiers.connection === '2g' || tiers.connection === '3g';
   const isBatteryConstrained =

From f28f1f8c192dde08fcdced6b8ebf7592dcd81eb6 Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Tue, 24 Feb 2026 15:44:26 +0100
Subject: [PATCH 05/12] Rename default cookie from dr_session to
 device-router-session (#32)

Self-documenting name before 1.0 locks the cookie in. Also removes
redundant `new` from `RegExp()` call in probe to stay within the
1 KB gzipped size budget.
---
 CHANGELOG.md                                  |  1 +
 docs/api/middleware-express.md                | 66 +++++++++----------
 docs/api/middleware-fastify.md                | 64 +++++++++---------
 docs/api/middleware-hono.md                   | 64 +++++++++---------
 docs/api/middleware-koa.md                    | 64 +++++++++---------
 docs/api/probe.md                             |  2 +-
 docs/getting-started.md                       |  4 +-
 packages/middleware-express/README.md         | 30 ++++-----
 .../src/__tests__/endpoint.test.ts            | 11 ++--
 .../src/__tests__/integration.test.ts         |  2 +-
 .../src/__tests__/middleware.test.ts          | 20 +++---
 packages/middleware-express/src/endpoint.ts   |  2 +-
 packages/middleware-express/src/index.ts      |  2 +-
 packages/middleware-express/src/middleware.ts |  2 +-
 packages/middleware-fastify/README.md         | 30 ++++-----
 .../src/__tests__/endpoint.test.ts            | 11 ++--
 .../src/__tests__/integration.test.ts         |  2 +-
 .../src/__tests__/middleware.test.ts          | 14 ++--
 packages/middleware-fastify/src/endpoint.ts   |  2 +-
 packages/middleware-fastify/src/index.ts      |  2 +-
 packages/middleware-fastify/src/middleware.ts |  2 +-
 packages/middleware-hono/README.md            | 30 ++++-----
 .../src/__tests__/endpoint.test.ts            |  2 +-
 .../src/__tests__/integration.test.ts         |  2 +-
 .../src/__tests__/middleware.test.ts          | 12 ++--
 packages/middleware-hono/src/endpoint.ts      |  2 +-
 packages/middleware-hono/src/index.ts         |  2 +-
 packages/middleware-hono/src/middleware.ts    |  2 +-
 packages/middleware-koa/README.md             | 30 ++++-----
 .../src/__tests__/endpoint.test.ts            | 11 ++--
 .../src/__tests__/integration.test.ts         |  2 +-
 .../src/__tests__/middleware.test.ts          | 14 ++--
 packages/middleware-koa/src/endpoint.ts       |  2 +-
 packages/middleware-koa/src/index.ts          |  2 +-
 packages/middleware-koa/src/middleware.ts     |  2 +-
 packages/probe/README.md                      | 32 ++++-----
 packages/probe/src/__tests__/probe.test.ts    |  4 +-
 packages/probe/src/probe.ts                   |  4 +-
 38 files changed, 281 insertions(+), 271 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1bf3457..0809df2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@
 - **Rename `ConnectionTier` value `'fast'` → `'high'`** — Aligns connection tier vocabulary with CPU, memory, and GPU tiers which all use `'low' | 'mid' | 'high'`. Update any code comparing `tiers.connection === 'fast'` to use `'high'` instead
 - **`classify()` and `deriveHints()` now accept `StoredSignals` instead of `RawSignals`** — These functions never used `userAgent` or `viewport` (which are stripped before storage). The narrower type makes the API honest. Existing call sites are unaffected — `RawSignals` is structurally assignable to `StoredSignals`
 - **`profile:store` event now carries `StoredSignals` instead of `RawSignals`** — The event previously emitted the raw probe payload (including `userAgent`/`viewport`), not what was actually stored. The `signals` field now matches the persisted data. `bot:reject` still carries `RawSignals` (it fires before stripping)
+- **Rename default cookie `dr_session` → `device-router-session`** — Self-documenting name before 1.0 locks the cookie in. If you hardcode `cookieName: 'dr_session'` in your options you are unaffected; if you rely on the default, existing sessions will reset once on deploy
 - **middleware-fastify: normalized return shape** — `createDeviceRouter()` now returns raw Fastify hooks instead of a `fastify-plugin` wrapped plugin. Migrate `await app.register(middleware)` → `app.addHook('preHandler', middleware)`. When using `injectProbe: true`, register the injection hook separately: `app.addHook('onSend', injectionMiddleware)`. Removed `fastify-plugin` dependency
 
 ### Features
diff --git a/docs/api/middleware-express.md b/docs/api/middleware-express.md
index 7be6b39..70f3172 100644
--- a/docs/api/middleware-express.md
+++ b/docs/api/middleware-express.md
@@ -10,7 +10,7 @@ import { MemoryStorageAdapter } from '@device-router/storage';
 
 const { middleware, probeEndpoint } = createDeviceRouter({
   storage: new MemoryStorageAdapter(),
-  cookieName: 'dr_session', // Default
+  cookieName: 'device-router-session', // Default
   cookiePath: '/', // Default
   ttl: 86400, // Default: 24 hours
 });
@@ -21,21 +21,21 @@ app.use(middleware);
 
 ### Options
 
-| Option                | Type                                   | Default                  | Description                                                               |
-| --------------------- | -------------------------------------- | ------------------------ | ------------------------------------------------------------------------- |
-| `storage`             | `StorageAdapter`                       | required                 | Storage backend                                                           |
-| `cookieName`          | `string`                               | `'dr_session'`           | Session cookie name                                                       |
-| `cookiePath`          | `string`                               | `'/'`                    | Cookie path                                                               |
-| `cookieSecure`        | `boolean`                              | `false`                  | Set `Secure` flag on the session cookie                                   |
-| `ttl`                 | `number`                               | `86400`                  | Profile TTL in seconds                                                    |
-| `rejectBots`          | `boolean`                              | `true`                   | Reject bot/crawler probe submissions (returns 403)                        |
-| `thresholds`          | `TierThresholds`                       | built-in defaults        | Custom tier classification thresholds (validated at startup)              |
-| `injectProbe`         | `boolean`                              | `false`                  | Auto-inject probe script into HTML responses                              |
-| `probePath`           | `string`                               | `'/device-router/probe'` | Custom probe endpoint path for injected script                            |
-| `probeNonce`          | `string \| ((req: Request) => string)` | —                        | CSP nonce for the injected script tag                                     |
-| `fallbackProfile`     | `FallbackProfile`                      | —                        | Fallback profile for first requests without probe data                    |
-| `classifyFromHeaders` | `boolean`                              | `false`                  | Classify from UA/Client Hints on first request                            |
-| `onEvent`             | `OnEventCallback`                      | —                        | Observability callback for logging/metrics ([guide](../observability.md)) |
+| Option                | Type                                   | Default                   | Description                                                               |
+| --------------------- | -------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `storage`             | `StorageAdapter`                       | required                  | Storage backend                                                           |
+| `cookieName`          | `string`                               | `'device-router-session'` | Session cookie name                                                       |
+| `cookiePath`          | `string`                               | `'/'`                     | Cookie path                                                               |
+| `cookieSecure`        | `boolean`                              | `false`                   | Set `Secure` flag on the session cookie                                   |
+| `ttl`                 | `number`                               | `86400`                   | Profile TTL in seconds                                                    |
+| `rejectBots`          | `boolean`                              | `true`                    | Reject bot/crawler probe submissions (returns 403)                        |
+| `thresholds`          | `TierThresholds`                       | built-in defaults         | Custom tier classification thresholds (validated at startup)              |
+| `injectProbe`         | `boolean`                              | `false`                   | Auto-inject probe script into HTML responses                              |
+| `probePath`           | `string`                               | `'/device-router/probe'`  | Custom probe endpoint path for injected script                            |
+| `probeNonce`          | `string \| ((req: Request) => string)` | —                         | CSP nonce for the injected script tag                                     |
+| `fallbackProfile`     | `FallbackProfile`                      | —                         | Fallback profile for first requests without probe data                    |
+| `classifyFromHeaders` | `boolean`                              | `false`                   | Classify from UA/Client Hints on first request                            |
+| `onEvent`             | `OnEventCallback`                      | —                         | Observability callback for logging/metrics ([guide](../observability.md)) |
 
 ### Returns
 
@@ -120,14 +120,14 @@ app.use(middleware);
 
 #### MiddlewareOptions
 
-| Option                | Type              | Default        | Description                                    |
-| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
-| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
-| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
-| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
-| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
-| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
-| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+| Option                | Type              | Default                   | Description                                    |
+| --------------------- | ----------------- | ------------------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_              | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'device-router-session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in                  | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —                         | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`                   | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —                         | Observability callback                         |
 
 ### createProbeEndpoint(options)
 
@@ -147,15 +147,15 @@ app.post('/device-router/probe', endpoint);
 
 #### EndpointOptions
 
-| Option         | Type              | Default        | Description                          |
-| -------------- | ----------------- | -------------- | ------------------------------------ |
-| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
-| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
-| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
-| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
-| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
-| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
-| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+| Option         | Type              | Default                   | Description                          |
+| -------------- | ----------------- | ------------------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_              | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'device-router-session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`                     | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`                   | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`                   | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`                    | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —                         | Observability callback               |
 
 ### createInjectionMiddleware(options)
 
diff --git a/docs/api/middleware-fastify.md b/docs/api/middleware-fastify.md
index d9fb3eb..70914af 100644
--- a/docs/api/middleware-fastify.md
+++ b/docs/api/middleware-fastify.md
@@ -23,21 +23,21 @@ app.addHook('preHandler', middleware);
 
 ### Options
 
-| Option                | Type                                          | Default                  | Description                                                               |
-| --------------------- | --------------------------------------------- | ------------------------ | ------------------------------------------------------------------------- |
-| `storage`             | `StorageAdapter`                              | required                 | Storage backend                                                           |
-| `cookieName`          | `string`                                      | `'dr_session'`           | Session cookie name                                                       |
-| `cookiePath`          | `string`                                      | `'/'`                    | Cookie path                                                               |
-| `cookieSecure`        | `boolean`                                     | `false`                  | Set `Secure` flag on the session cookie                                   |
-| `ttl`                 | `number`                                      | `86400`                  | Profile TTL in seconds                                                    |
-| `rejectBots`          | `boolean`                                     | `true`                   | Reject bot/crawler probe submissions (returns 403)                        |
-| `thresholds`          | `TierThresholds`                              | built-in defaults        | Custom tier classification thresholds (validated at startup)              |
-| `injectProbe`         | `boolean`                                     | `false`                  | Auto-inject probe script into HTML responses                              |
-| `probePath`           | `string`                                      | `'/device-router/probe'` | Custom probe endpoint path for injected script                            |
-| `probeNonce`          | `string \| ((req: FastifyRequest) => string)` | —                        | CSP nonce for the injected script tag                                     |
-| `fallbackProfile`     | `FallbackProfile`                             | —                        | Fallback profile for first requests without probe data                    |
-| `classifyFromHeaders` | `boolean`                                     | `false`                  | Classify from UA/Client Hints on first request                            |
-| `onEvent`             | `OnEventCallback`                             | —                        | Observability callback for logging/metrics ([guide](../observability.md)) |
+| Option                | Type                                          | Default                   | Description                                                               |
+| --------------------- | --------------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `storage`             | `StorageAdapter`                              | required                  | Storage backend                                                           |
+| `cookieName`          | `string`                                      | `'device-router-session'` | Session cookie name                                                       |
+| `cookiePath`          | `string`                                      | `'/'`                     | Cookie path                                                               |
+| `cookieSecure`        | `boolean`                                     | `false`                   | Set `Secure` flag on the session cookie                                   |
+| `ttl`                 | `number`                                      | `86400`                   | Profile TTL in seconds                                                    |
+| `rejectBots`          | `boolean`                                     | `true`                    | Reject bot/crawler probe submissions (returns 403)                        |
+| `thresholds`          | `TierThresholds`                              | built-in defaults         | Custom tier classification thresholds (validated at startup)              |
+| `injectProbe`         | `boolean`                                     | `false`                   | Auto-inject probe script into HTML responses                              |
+| `probePath`           | `string`                                      | `'/device-router/probe'`  | Custom probe endpoint path for injected script                            |
+| `probeNonce`          | `string \| ((req: FastifyRequest) => string)` | —                         | CSP nonce for the injected script tag                                     |
+| `fallbackProfile`     | `FallbackProfile`                             | —                         | Fallback profile for first requests without probe data                    |
+| `classifyFromHeaders` | `boolean`                                     | `false`                   | Classify from UA/Client Hints on first request                            |
+| `onEvent`             | `OnEventCallback`                             | —                         | Observability callback for logging/metrics ([guide](../observability.md)) |
 
 ### Returns
 
@@ -118,14 +118,14 @@ app.addHook('preHandler', hook);
 
 #### MiddlewareOptions
 
-| Option                | Type              | Default        | Description                                    |
-| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
-| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
-| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
-| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
-| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
-| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
-| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+| Option                | Type              | Default                   | Description                                    |
+| --------------------- | ----------------- | ------------------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_              | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'device-router-session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in                  | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —                         | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`                   | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —                         | Observability callback                         |
 
 ### createProbeEndpoint(options)
 
@@ -145,15 +145,15 @@ app.post('/device-router/probe', endpoint);
 
 #### EndpointOptions
 
-| Option         | Type              | Default        | Description                          |
-| -------------- | ----------------- | -------------- | ------------------------------------ |
-| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
-| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
-| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
-| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
-| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
-| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
-| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+| Option         | Type              | Default                   | Description                          |
+| -------------- | ----------------- | ------------------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_              | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'device-router-session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`                     | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`                   | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`                   | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`                    | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —                         | Observability callback               |
 
 ### createInjectionMiddleware(options)
 
diff --git a/docs/api/middleware-hono.md b/docs/api/middleware-hono.md
index 1c6de85..5de172b 100644
--- a/docs/api/middleware-hono.md
+++ b/docs/api/middleware-hono.md
@@ -22,21 +22,21 @@ app.use('*', middleware);
 
 ### Options
 
-| Option                | Type                                 | Default                  | Description                                                               |
-| --------------------- | ------------------------------------ | ------------------------ | ------------------------------------------------------------------------- |
-| `storage`             | `StorageAdapter`                     | required                 | Storage backend                                                           |
-| `cookieName`          | `string`                             | `'dr_session'`           | Session cookie name                                                       |
-| `cookiePath`          | `string`                             | `'/'`                    | Cookie path                                                               |
-| `cookieSecure`        | `boolean`                            | `false`                  | Set `Secure` flag on the session cookie                                   |
-| `ttl`                 | `number`                             | `86400`                  | Profile TTL in seconds                                                    |
-| `rejectBots`          | `boolean`                            | `true`                   | Reject bot/crawler probe submissions (returns 403)                        |
-| `thresholds`          | `TierThresholds`                     | built-in defaults        | Custom tier classification thresholds (validated at startup)              |
-| `injectProbe`         | `boolean`                            | `false`                  | Auto-inject probe script into HTML responses                              |
-| `probePath`           | `string`                             | `'/device-router/probe'` | Custom probe endpoint path for injected script                            |
-| `probeNonce`          | `string \| ((c: Context) => string)` | —                        | CSP nonce for the injected script tag                                     |
-| `fallbackProfile`     | `FallbackProfile`                    | —                        | Fallback profile for first requests without probe data                    |
-| `classifyFromHeaders` | `boolean`                            | `false`                  | Classify from UA/Client Hints on first request                            |
-| `onEvent`             | `OnEventCallback`                    | —                        | Observability callback for logging/metrics ([guide](../observability.md)) |
+| Option                | Type                                 | Default                   | Description                                                               |
+| --------------------- | ------------------------------------ | ------------------------- | ------------------------------------------------------------------------- |
+| `storage`             | `StorageAdapter`                     | required                  | Storage backend                                                           |
+| `cookieName`          | `string`                             | `'device-router-session'` | Session cookie name                                                       |
+| `cookiePath`          | `string`                             | `'/'`                     | Cookie path                                                               |
+| `cookieSecure`        | `boolean`                            | `false`                   | Set `Secure` flag on the session cookie                                   |
+| `ttl`                 | `number`                             | `86400`                   | Profile TTL in seconds                                                    |
+| `rejectBots`          | `boolean`                            | `true`                    | Reject bot/crawler probe submissions (returns 403)                        |
+| `thresholds`          | `TierThresholds`                     | built-in defaults         | Custom tier classification thresholds (validated at startup)              |
+| `injectProbe`         | `boolean`                            | `false`                   | Auto-inject probe script into HTML responses                              |
+| `probePath`           | `string`                             | `'/device-router/probe'`  | Custom probe endpoint path for injected script                            |
+| `probeNonce`          | `string \| ((c: Context) => string)` | —                         | CSP nonce for the injected script tag                                     |
+| `fallbackProfile`     | `FallbackProfile`                    | —                         | Fallback profile for first requests without probe data                    |
+| `classifyFromHeaders` | `boolean`                            | `false`                   | Classify from UA/Client Hints on first request                            |
+| `onEvent`             | `OnEventCallback`                    | —                         | Observability callback for logging/metrics ([guide](../observability.md)) |
 
 ### Returns
 
@@ -123,14 +123,14 @@ app.use('*', middleware);
 
 #### MiddlewareOptions
 
-| Option                | Type              | Default        | Description                                    |
-| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
-| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
-| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
-| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
-| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
-| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
-| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+| Option                | Type              | Default                   | Description                                    |
+| --------------------- | ----------------- | ------------------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_              | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'device-router-session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in                  | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —                         | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`                   | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —                         | Observability callback                         |
 
 ### createProbeEndpoint(options)
 
@@ -150,15 +150,15 @@ app.post('/device-router/probe', endpoint);
 
 #### EndpointOptions
 
-| Option         | Type              | Default        | Description                          |
-| -------------- | ----------------- | -------------- | ------------------------------------ |
-| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
-| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
-| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
-| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
-| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
-| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
-| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+| Option         | Type              | Default                   | Description                          |
+| -------------- | ----------------- | ------------------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_              | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'device-router-session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`                     | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`                   | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`                   | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`                    | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —                         | Observability callback               |
 
 ### createInjectionMiddleware(options)
 
diff --git a/docs/api/middleware-koa.md b/docs/api/middleware-koa.md
index a0b11d2..a3ed562 100644
--- a/docs/api/middleware-koa.md
+++ b/docs/api/middleware-koa.md
@@ -29,21 +29,21 @@ app.use(middleware);
 
 ### Options
 
-| Option                | Type                                   | Default                  | Description                                                               |
-| --------------------- | -------------------------------------- | ------------------------ | ------------------------------------------------------------------------- |
-| `storage`             | `StorageAdapter`                       | required                 | Storage backend                                                           |
-| `cookieName`          | `string`                               | `'dr_session'`           | Session cookie name                                                       |
-| `cookiePath`          | `string`                               | `'/'`                    | Cookie path                                                               |
-| `cookieSecure`        | `boolean`                              | `false`                  | Set `Secure` flag on the session cookie                                   |
-| `ttl`                 | `number`                               | `86400`                  | Profile TTL in seconds                                                    |
-| `rejectBots`          | `boolean`                              | `true`                   | Reject bot/crawler probe submissions (returns 403)                        |
-| `thresholds`          | `TierThresholds`                       | built-in defaults        | Custom tier classification thresholds (validated at startup)              |
-| `injectProbe`         | `boolean`                              | `false`                  | Auto-inject probe script into HTML responses                              |
-| `probePath`           | `string`                               | `'/device-router/probe'` | Custom probe endpoint path for injected script                            |
-| `probeNonce`          | `string \| ((ctx: Context) => string)` | —                        | CSP nonce for the injected script tag                                     |
-| `fallbackProfile`     | `FallbackProfile`                      | —                        | Fallback profile for first requests without probe data                    |
-| `classifyFromHeaders` | `boolean`                              | `false`                  | Classify from UA/Client Hints on first request                            |
-| `onEvent`             | `OnEventCallback`                      | —                        | Observability callback for logging/metrics ([guide](../observability.md)) |
+| Option                | Type                                   | Default                   | Description                                                               |
+| --------------------- | -------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| `storage`             | `StorageAdapter`                       | required                  | Storage backend                                                           |
+| `cookieName`          | `string`                               | `'device-router-session'` | Session cookie name                                                       |
+| `cookiePath`          | `string`                               | `'/'`                     | Cookie path                                                               |
+| `cookieSecure`        | `boolean`                              | `false`                   | Set `Secure` flag on the session cookie                                   |
+| `ttl`                 | `number`                               | `86400`                   | Profile TTL in seconds                                                    |
+| `rejectBots`          | `boolean`                              | `true`                    | Reject bot/crawler probe submissions (returns 403)                        |
+| `thresholds`          | `TierThresholds`                       | built-in defaults         | Custom tier classification thresholds (validated at startup)              |
+| `injectProbe`         | `boolean`                              | `false`                   | Auto-inject probe script into HTML responses                              |
+| `probePath`           | `string`                               | `'/device-router/probe'`  | Custom probe endpoint path for injected script                            |
+| `probeNonce`          | `string \| ((ctx: Context) => string)` | —                         | CSP nonce for the injected script tag                                     |
+| `fallbackProfile`     | `FallbackProfile`                      | —                         | Fallback profile for first requests without probe data                    |
+| `classifyFromHeaders` | `boolean`                              | `false`                   | Classify from UA/Client Hints on first request                            |
+| `onEvent`             | `OnEventCallback`                      | —                         | Observability callback for logging/metrics ([guide](../observability.md)) |
 
 ### Returns
 
@@ -120,14 +120,14 @@ app.use(middleware);
 
 #### MiddlewareOptions
 
-| Option                | Type              | Default        | Description                                    |
-| --------------------- | ----------------- | -------------- | ---------------------------------------------- |
-| `storage`             | `StorageAdapter`  | _(required)_   | Storage backend for profiles                   |
-| `cookieName`          | `string`          | `'dr_session'` | Session cookie name                            |
-| `thresholds`          | `TierThresholds`  | Built-in       | Custom tier thresholds (validated at creation) |
-| `fallbackProfile`     | `FallbackProfile` | —              | Fallback profile for first requests            |
-| `classifyFromHeaders` | `boolean`         | `false`        | Classify from UA/Client Hints on first request |
-| `onEvent`             | `OnEventCallback` | —              | Observability callback                         |
+| Option                | Type              | Default                   | Description                                    |
+| --------------------- | ----------------- | ------------------------- | ---------------------------------------------- |
+| `storage`             | `StorageAdapter`  | _(required)_              | Storage backend for profiles                   |
+| `cookieName`          | `string`          | `'device-router-session'` | Session cookie name                            |
+| `thresholds`          | `TierThresholds`  | Built-in                  | Custom tier thresholds (validated at creation) |
+| `fallbackProfile`     | `FallbackProfile` | —                         | Fallback profile for first requests            |
+| `classifyFromHeaders` | `boolean`         | `false`                   | Classify from UA/Client Hints on first request |
+| `onEvent`             | `OnEventCallback` | —                         | Observability callback                         |
 
 ### createProbeEndpoint(options)
 
@@ -154,15 +154,15 @@ app.use(async (ctx, next) => {
 
 #### EndpointOptions
 
-| Option         | Type              | Default        | Description                          |
-| -------------- | ----------------- | -------------- | ------------------------------------ |
-| `storage`      | `StorageAdapter`  | _(required)_   | Storage backend for profiles         |
-| `cookieName`   | `string`          | `'dr_session'` | Session cookie name                  |
-| `cookiePath`   | `string`          | `'/'`          | Cookie path                          |
-| `cookieSecure` | `boolean`         | `false`        | Set `Secure` flag on the cookie      |
-| `ttl`          | `number`          | `86400`        | Profile TTL in seconds               |
-| `rejectBots`   | `boolean`         | `true`         | Reject bot/crawler probe submissions |
-| `onEvent`      | `OnEventCallback` | —              | Observability callback               |
+| Option         | Type              | Default                   | Description                          |
+| -------------- | ----------------- | ------------------------- | ------------------------------------ |
+| `storage`      | `StorageAdapter`  | _(required)_              | Storage backend for profiles         |
+| `cookieName`   | `string`          | `'device-router-session'` | Session cookie name                  |
+| `cookiePath`   | `string`          | `'/'`                     | Cookie path                          |
+| `cookieSecure` | `boolean`         | `false`                   | Set `Secure` flag on the cookie      |
+| `ttl`          | `number`          | `86400`                   | Profile TTL in seconds               |
+| `rejectBots`   | `boolean`         | `true`                    | Reject bot/crawler probe submissions |
+| `onEvent`      | `OnEventCallback` | —                         | Observability callback               |
 
 ### createInjectionMiddleware(options)
 
diff --git a/docs/api/probe.md b/docs/api/probe.md
index 0026fb1..3facbba 100644
--- a/docs/api/probe.md
+++ b/docs/api/probe.md
@@ -17,7 +17,7 @@ import { runProbe } from '@device-router/probe';
 
 await runProbe({
   endpoint: '/device-router/probe', // POST endpoint
-  cookieName: 'dr_session', // Session cookie name
+  cookieName: 'device-router-session', // Session cookie name
   cookiePath: '/', // Cookie path
 });
 ```
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 201dd49..98f96f8 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -266,7 +266,7 @@ Thresholds are validated at startup — inverted bounds, non-positive values, or
 ```typescript
 const { middleware, probeEndpoint } = createDeviceRouter({
   storage,              // Required: StorageAdapter instance
-  cookieName: 'dr_session',   // Default: 'dr_session'
+  cookieName: 'device-router-session',   // Default: 'device-router-session'
   cookiePath: '/',            // Default: '/'
   cookieSecure: false,        // Default: false — set to true for HTTPS deployments
   ttl: 86400,                 // Default: 86400 (24 hours)
@@ -316,7 +316,7 @@ The signals DeviceRouter collects overlap with known browser fingerprinting vect
 
 Two regulations apply independently:
 
-- **ePrivacy Directive (Article 5(3))** covers both setting the `dr_session` cookie _and_ reading device signals from browser APIs. Both count as accessing information stored on terminal equipment. The "strictly necessary" exemption is interpreted narrowly by the EDPB, CNIL, and ICO — it requires that the service _cannot function_ without the data, not that it functions _better_ with it. Adaptive rendering has not been recognized as strictly necessary by any regulator.
+- **ePrivacy Directive (Article 5(3))** covers both setting the `device-router-session` cookie _and_ reading device signals from browser APIs. Both count as accessing information stored on terminal equipment. The "strictly necessary" exemption is interpreted narrowly by the EDPB, CNIL, and ICO — it requires that the service _cannot function_ without the data, not that it functions _better_ with it. Adaptive rendering has not been recognized as strictly necessary by any regulator.
 
 - **GDPR** applies because the collected signals in aggregate constitute personal data (Recital 30 explicitly references device identifiers and the profiles they can create). You need a lawful basis under Article 6 — consent (Article 6(1)(a)) is the most defensible option.
 
diff --git a/packages/middleware-express/README.md b/packages/middleware-express/README.md
index e182958..9efdfc1 100644
--- a/packages/middleware-express/README.md
+++ b/packages/middleware-express/README.md
@@ -87,21 +87,21 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 ## Options
 
-| Option                | Type                                   | Default           | Description                                   |
-| --------------------- | -------------------------------------- | ----------------- | --------------------------------------------- |
-| `storage`             | `StorageAdapter`                       | _(required)_      | Storage backend for profiles                  |
-| `cookieName`          | `string`                               | `'dr_session'`    | Session cookie name                           |
-| `cookiePath`          | `string`                               | `'/'`             | Cookie path                                   |
-| `cookieSecure`        | `boolean`                              | `false`           | Set `Secure` flag on the session cookie       |
-| `ttl`                 | `number`                               | `86400` (24h)     | Profile TTL in seconds                        |
-| `rejectBots`          | `boolean`                              | `true`            | Reject bot/crawler probe submissions          |
-| `probePath`           | `string`                               | —                 | Custom probe endpoint path                    |
-| `thresholds`          | `TierThresholds`                       | Built-in defaults | Custom tier thresholds (validated at startup) |
-| `injectProbe`         | `boolean`                              | `false`           | Auto-inject probe into HTML                   |
-| `probeNonce`          | `string \| ((req: Request) => string)` | —                 | CSP nonce for injected script                 |
-| `fallbackProfile`     | `FallbackProfile`                      | —                 | Fallback profile for first requests           |
-| `classifyFromHeaders` | `boolean`                              | `false`           | Classify from UA/Client Hints                 |
-| `onEvent`             | `OnEventCallback`                      | —                 | Observability callback for logging/metrics    |
+| Option                | Type                                   | Default                   | Description                                   |
+| --------------------- | -------------------------------------- | ------------------------- | --------------------------------------------- |
+| `storage`             | `StorageAdapter`                       | _(required)_              | Storage backend for profiles                  |
+| `cookieName`          | `string`                               | `'device-router-session'` | Session cookie name                           |
+| `cookiePath`          | `string`                               | `'/'`                     | Cookie path                                   |
+| `cookieSecure`        | `boolean`                              | `false`                   | Set `Secure` flag on the session cookie       |
+| `ttl`                 | `number`                               | `86400` (24h)             | Profile TTL in seconds                        |
+| `rejectBots`          | `boolean`                              | `true`                    | Reject bot/crawler probe submissions          |
+| `probePath`           | `string`                               | —                         | Custom probe endpoint path                    |
+| `thresholds`          | `TierThresholds`                       | Built-in defaults         | Custom tier thresholds (validated at startup) |
+| `injectProbe`         | `boolean`                              | `false`                   | Auto-inject probe into HTML                   |
+| `probeNonce`          | `string \| ((req: Request) => string)` | —                         | CSP nonce for injected script                 |
+| `fallbackProfile`     | `FallbackProfile`                      | —                         | Fallback profile for first requests           |
+| `classifyFromHeaders` | `boolean`                              | `false`                   | Classify from UA/Client Hints                 |
+| `onEvent`             | `OnEventCallback`                      | —                         | Observability callback for logging/metrics    |
 
 ## Observability
 
diff --git a/packages/middleware-express/src/__tests__/endpoint.test.ts b/packages/middleware-express/src/__tests__/endpoint.test.ts
index ec62822..944a13b 100644
--- a/packages/middleware-express/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-express/src/__tests__/endpoint.test.ts
@@ -52,7 +52,7 @@ describe('createProbeEndpoint', () => {
       sessionToken: expect.any(String),
     });
     expect(res.cookie).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({
         httpOnly: true,
@@ -70,7 +70,7 @@ describe('createProbeEndpoint', () => {
     await handler(req, res);
 
     expect(res.cookie).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({ secure: false }),
     );
@@ -84,7 +84,7 @@ describe('createProbeEndpoint', () => {
     await handler(req, res);
 
     expect(res.cookie).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({ secure: true }),
     );
@@ -92,7 +92,10 @@ describe('createProbeEndpoint', () => {
 
   it('reuses existing session token from cookie', async () => {
     const handler = createProbeEndpoint({ storage });
-    const req = createMockReq({ hardwareConcurrency: 4 }, { dr_session: 'existing-tok' });
+    const req = createMockReq(
+      { hardwareConcurrency: 4 },
+      { 'device-router-session': 'existing-tok' },
+    );
     const res = createMockRes();
 
     await handler(req, res);
diff --git a/packages/middleware-express/src/__tests__/integration.test.ts b/packages/middleware-express/src/__tests__/integration.test.ts
index 2fe6f41..cc06864 100644
--- a/packages/middleware-express/src/__tests__/integration.test.ts
+++ b/packages/middleware-express/src/__tests__/integration.test.ts
@@ -82,7 +82,7 @@ describe('integration: probe → middleware → route', () => {
 
     // Step 2: Make request with session cookie
     const testRes = await request(`${baseUrl}/test`, {
-      headers: { Cookie: `dr_session=${probeData.sessionToken}` },
+      headers: { Cookie: `device-router-session=${probeData.sessionToken}` },
     });
 
     const testData = (await testRes.json()) as { tier: string; hints: Record<string, boolean> };
diff --git a/packages/middleware-express/src/__tests__/middleware.test.ts b/packages/middleware-express/src/__tests__/middleware.test.ts
index 215638c..963561e 100644
--- a/packages/middleware-express/src/__tests__/middleware.test.ts
+++ b/packages/middleware-express/src/__tests__/middleware.test.ts
@@ -56,7 +56,7 @@ describe('createMiddleware', () => {
 
   it('sets deviceProfile to null when profile not found', async () => {
     const mw = createMiddleware({ storage });
-    const req = createMockReq({ dr_session: 'unknown' });
+    const req = createMockReq({ 'device-router-session': 'unknown' });
     const next = vi.fn();
 
     await mw(req, createMockRes(), next);
@@ -76,7 +76,7 @@ describe('createMiddleware', () => {
     (storage as unknown as { _store: Map<string, DeviceProfile> })._store.set('tok1', profile);
 
     const mw = createMiddleware({ storage });
-    const req = createMockReq({ dr_session: 'tok1' });
+    const req = createMockReq({ 'device-router-session': 'tok1' });
     const next = vi.fn();
 
     await mw(req, createMockRes(), next);
@@ -104,7 +104,7 @@ describe('createMiddleware', () => {
   it('calls next with error on storage failure', async () => {
     storage.get = vi.fn().mockRejectedValue(new Error('Storage down'));
     const mw = createMiddleware({ storage });
-    const req = createMockReq({ dr_session: 'tok' });
+    const req = createMockReq({ 'device-router-session': 'tok' });
     const next = vi.fn();
 
     await mw(req, createMockRes(), next);
@@ -124,7 +124,7 @@ describe('createMiddleware', () => {
 
     // Default thresholds: 4 cores = mid, 4 GB = mid
     const mwDefault = createMiddleware({ storage });
-    const req1 = createMockReq({ dr_session: 'tok2' });
+    const req1 = createMockReq({ 'device-router-session': 'tok2' });
     await mwDefault(req1, createMockRes(), vi.fn());
     expect(req1.deviceProfile!.tiers.cpu).toBe('mid');
     expect(req1.deviceProfile!.tiers.memory).toBe('mid');
@@ -137,7 +137,7 @@ describe('createMiddleware', () => {
         memory: { lowUpperBound: 6, midUpperBound: 8 },
       },
     });
-    const req2 = createMockReq({ dr_session: 'tok2' });
+    const req2 = createMockReq({ 'device-router-session': 'tok2' });
     await mwCustom(req2, createMockRes(), vi.fn());
     expect(req2.deviceProfile!.tiers.cpu).toBe('low');
     expect(req2.deviceProfile!.tiers.memory).toBe('low');
@@ -194,7 +194,7 @@ describe('createMiddleware', () => {
 
     it('falls back when cookie exists but profile not in storage', async () => {
       const mw = createMiddleware({ storage, fallbackProfile: 'conservative' });
-      const req = createMockReq({ dr_session: 'expired-token' });
+      const req = createMockReq({ 'device-router-session': 'expired-token' });
       const next = vi.fn();
 
       await mw(req, createMockRes(), next);
@@ -284,7 +284,7 @@ describe('createMiddleware', () => {
     it('classifies from headers when cookie exists but storage misses', async () => {
       const mw = createMiddleware({ storage, classifyFromHeaders: true });
       const req = createMockReq(
-        { dr_session: 'expired' },
+        { 'device-router-session': 'expired' },
         { 'user-agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0) Mobile' },
       );
       const next = vi.fn();
@@ -312,7 +312,7 @@ describe('createMiddleware', () => {
       (storage as unknown as { _store: Map<string, DeviceProfile> })._store.set('tok-ev1', profile);
 
       const mw = createMiddleware({ storage, onEvent });
-      const req = createMockReq({ dr_session: 'tok-ev1' });
+      const req = createMockReq({ 'device-router-session': 'tok-ev1' });
       const next = vi.fn();
 
       await mw(req, createMockRes(), next);
@@ -384,7 +384,7 @@ describe('createMiddleware', () => {
 
       storage.get = vi.fn().mockRejectedValue(new Error('Storage down'));
       const mw = createMiddleware({ storage, onEvent });
-      const req = createMockReq({ dr_session: 'tok-err' });
+      const req = createMockReq({ 'device-router-session': 'tok-err' });
       const next = vi.fn();
 
       await mw(req, createMockRes(), next);
@@ -416,7 +416,7 @@ describe('createMiddleware', () => {
       );
 
       const mw = createMiddleware({ storage, onEvent });
-      const req = createMockReq({ dr_session: 'tok-safe' });
+      const req = createMockReq({ 'device-router-session': 'tok-safe' });
       const next = vi.fn();
 
       await mw(req, createMockRes(), next);
diff --git a/packages/middleware-express/src/endpoint.ts b/packages/middleware-express/src/endpoint.ts
index 68044bf..88b0fe2 100644
--- a/packages/middleware-express/src/endpoint.ts
+++ b/packages/middleware-express/src/endpoint.ts
@@ -17,7 +17,7 @@ export interface EndpointOptions {
 export function createProbeEndpoint(options: EndpointOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure = false,
     ttl = 86400,
diff --git a/packages/middleware-express/src/index.ts b/packages/middleware-express/src/index.ts
index 988670b..35e6f52 100644
--- a/packages/middleware-express/src/index.ts
+++ b/packages/middleware-express/src/index.ts
@@ -26,7 +26,7 @@ export interface DeviceRouterOptions {
 export function createDeviceRouter(options: DeviceRouterOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure,
     ttl = 86400,
diff --git a/packages/middleware-express/src/middleware.ts b/packages/middleware-express/src/middleware.ts
index f00435d..3590e03 100644
--- a/packages/middleware-express/src/middleware.ts
+++ b/packages/middleware-express/src/middleware.ts
@@ -37,7 +37,7 @@ export interface MiddlewareOptions {
 export function createMiddleware(options: MiddlewareOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     thresholds,
     fallbackProfile,
     classifyFromHeaders: useHeaders,
diff --git a/packages/middleware-fastify/README.md b/packages/middleware-fastify/README.md
index 99f73ce..83faeec 100644
--- a/packages/middleware-fastify/README.md
+++ b/packages/middleware-fastify/README.md
@@ -90,21 +90,21 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 ## Options
 
-| Option                | Type                                          | Default           | Description                                   |
-| --------------------- | --------------------------------------------- | ----------------- | --------------------------------------------- |
-| `storage`             | `StorageAdapter`                              | _(required)_      | Storage backend for profiles                  |
-| `cookieName`          | `string`                                      | `'dr_session'`    | Session cookie name                           |
-| `cookiePath`          | `string`                                      | `'/'`             | Cookie path                                   |
-| `cookieSecure`        | `boolean`                                     | `false`           | Set `Secure` flag on the session cookie       |
-| `ttl`                 | `number`                                      | `86400` (24h)     | Profile TTL in seconds                        |
-| `rejectBots`          | `boolean`                                     | `true`            | Reject bot/crawler probe submissions          |
-| `thresholds`          | `TierThresholds`                              | Built-in defaults | Custom tier thresholds (validated at startup) |
-| `injectProbe`         | `boolean`                                     | `false`           | Auto-inject probe into HTML                   |
-| `probePath`           | `string`                                      | —                 | Custom probe endpoint path                    |
-| `probeNonce`          | `string \| ((req: FastifyRequest) => string)` | —                 | CSP nonce for injected script                 |
-| `fallbackProfile`     | `FallbackProfile`                             | —                 | Fallback profile for first requests           |
-| `classifyFromHeaders` | `boolean`                                     | `false`           | Classify from UA/Client Hints                 |
-| `onEvent`             | `OnEventCallback`                             | —                 | Observability callback for logging/metrics    |
+| Option                | Type                                          | Default                   | Description                                   |
+| --------------------- | --------------------------------------------- | ------------------------- | --------------------------------------------- |
+| `storage`             | `StorageAdapter`                              | _(required)_              | Storage backend for profiles                  |
+| `cookieName`          | `string`                                      | `'device-router-session'` | Session cookie name                           |
+| `cookiePath`          | `string`                                      | `'/'`                     | Cookie path                                   |
+| `cookieSecure`        | `boolean`                                     | `false`                   | Set `Secure` flag on the session cookie       |
+| `ttl`                 | `number`                                      | `86400` (24h)             | Profile TTL in seconds                        |
+| `rejectBots`          | `boolean`                                     | `true`                    | Reject bot/crawler probe submissions          |
+| `thresholds`          | `TierThresholds`                              | Built-in defaults         | Custom tier thresholds (validated at startup) |
+| `injectProbe`         | `boolean`                                     | `false`                   | Auto-inject probe into HTML                   |
+| `probePath`           | `string`                                      | —                         | Custom probe endpoint path                    |
+| `probeNonce`          | `string \| ((req: FastifyRequest) => string)` | —                         | CSP nonce for injected script                 |
+| `fallbackProfile`     | `FallbackProfile`                             | —                         | Fallback profile for first requests           |
+| `classifyFromHeaders` | `boolean`                                     | `false`                   | Classify from UA/Client Hints                 |
+| `onEvent`             | `OnEventCallback`                             | —                         | Observability callback for logging/metrics    |
 
 ## Observability
 
diff --git a/packages/middleware-fastify/src/__tests__/endpoint.test.ts b/packages/middleware-fastify/src/__tests__/endpoint.test.ts
index cc10fc3..db05ffb 100644
--- a/packages/middleware-fastify/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-fastify/src/__tests__/endpoint.test.ts
@@ -51,7 +51,7 @@ describe('createProbeEndpoint', () => {
       sessionToken: expect.any(String),
     });
     expect(reply.setCookie).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({
         httpOnly: true,
@@ -69,7 +69,7 @@ describe('createProbeEndpoint', () => {
     await handler(req, reply);
 
     expect(reply.setCookie).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({ secure: false }),
     );
@@ -83,7 +83,7 @@ describe('createProbeEndpoint', () => {
     await handler(req, reply);
 
     expect(reply.setCookie).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({ secure: true }),
     );
@@ -91,7 +91,10 @@ describe('createProbeEndpoint', () => {
 
   it('reuses existing session token from cookie', async () => {
     const handler = createProbeEndpoint({ storage });
-    const req = createMockReq({ hardwareConcurrency: 4 }, { dr_session: 'existing-tok' });
+    const req = createMockReq(
+      { hardwareConcurrency: 4 },
+      { 'device-router-session': 'existing-tok' },
+    );
     const reply = createMockReply();
 
     await handler(req, reply);
diff --git a/packages/middleware-fastify/src/__tests__/integration.test.ts b/packages/middleware-fastify/src/__tests__/integration.test.ts
index 79a1e9b..6522f1d 100644
--- a/packages/middleware-fastify/src/__tests__/integration.test.ts
+++ b/packages/middleware-fastify/src/__tests__/integration.test.ts
@@ -68,7 +68,7 @@ describe('integration: probe → middleware → route (fastify)', () => {
     expect(setCookie).toBeTruthy();
 
     const testRes = await fetch(`${baseUrl}/test`, {
-      headers: { Cookie: `dr_session=${probeData.sessionToken}` },
+      headers: { Cookie: `device-router-session=${probeData.sessionToken}` },
     });
 
     const testData = (await testRes.json()) as { tier: string; hints: Record<string, boolean> };
diff --git a/packages/middleware-fastify/src/__tests__/middleware.test.ts b/packages/middleware-fastify/src/__tests__/middleware.test.ts
index 6d8aff7..5e26f30 100644
--- a/packages/middleware-fastify/src/__tests__/middleware.test.ts
+++ b/packages/middleware-fastify/src/__tests__/middleware.test.ts
@@ -55,7 +55,7 @@ describe('createMiddleware', () => {
 
   it('sets deviceProfile to null when profile not found', async () => {
     const hook = createMiddleware({ storage });
-    const req = createMockReq({ dr_session: 'unknown' });
+    const req = createMockReq({ 'device-router-session': 'unknown' });
 
     await hook(req, createMockReply());
 
@@ -73,7 +73,7 @@ describe('createMiddleware', () => {
     storage._store.set('tok1', profile);
 
     const hook = createMiddleware({ storage });
-    const req = createMockReq({ dr_session: 'tok1' });
+    const req = createMockReq({ 'device-router-session': 'tok1' });
 
     await hook(req, createMockReply());
 
@@ -108,7 +108,7 @@ describe('createMiddleware', () => {
       storage,
       thresholds: { cpu: { lowUpperBound: 6, midUpperBound: 8 } },
     });
-    const req = createMockReq({ dr_session: 'tok2' });
+    const req = createMockReq({ 'device-router-session': 'tok2' });
 
     await hook(req, createMockReply());
 
@@ -159,7 +159,7 @@ describe('createMiddleware', () => {
 
     it('falls back when cookie exists but profile not in storage', async () => {
       const hook = createMiddleware({ storage, fallbackProfile: 'conservative' });
-      const req = createMockReq({ dr_session: 'expired-token' });
+      const req = createMockReq({ 'device-router-session': 'expired-token' });
 
       await hook(req, createMockReply());
 
@@ -249,7 +249,7 @@ describe('createMiddleware', () => {
       storage._store.set('tok1', profile);
 
       const hook = createMiddleware({ storage, onEvent });
-      const req = createMockReq({ dr_session: 'tok1' });
+      const req = createMockReq({ 'device-router-session': 'tok1' });
 
       await hook(req, createMockReply());
 
@@ -311,7 +311,7 @@ describe('createMiddleware', () => {
       storage.get = vi.fn().mockRejectedValue(new Error('Redis down'));
 
       const hook = createMiddleware({ storage, onEvent });
-      const req = createMockReq({ dr_session: 'tok1' });
+      const req = createMockReq({ 'device-router-session': 'tok1' });
 
       await expect(hook(req, createMockReply())).rejects.toThrow('Redis down');
 
@@ -342,7 +342,7 @@ describe('createMiddleware', () => {
       storage._store.set('tok1', profile);
 
       const hook = createMiddleware({ storage, onEvent });
-      const req = createMockReq({ dr_session: 'tok1' });
+      const req = createMockReq({ 'device-router-session': 'tok1' });
 
       await hook(req, createMockReply());
 
diff --git a/packages/middleware-fastify/src/endpoint.ts b/packages/middleware-fastify/src/endpoint.ts
index aa719a4..226b43a 100644
--- a/packages/middleware-fastify/src/endpoint.ts
+++ b/packages/middleware-fastify/src/endpoint.ts
@@ -18,7 +18,7 @@ export interface EndpointOptions {
 export function createProbeEndpoint(options: EndpointOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure = false,
     ttl = 86400,
diff --git a/packages/middleware-fastify/src/index.ts b/packages/middleware-fastify/src/index.ts
index 5b90239..3733e29 100644
--- a/packages/middleware-fastify/src/index.ts
+++ b/packages/middleware-fastify/src/index.ts
@@ -27,7 +27,7 @@ export interface DeviceRouterOptions {
 export function createDeviceRouter(options: DeviceRouterOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure,
     ttl = 86400,
diff --git a/packages/middleware-fastify/src/middleware.ts b/packages/middleware-fastify/src/middleware.ts
index 20c4228..4098cd0 100644
--- a/packages/middleware-fastify/src/middleware.ts
+++ b/packages/middleware-fastify/src/middleware.ts
@@ -35,7 +35,7 @@ export interface MiddlewareOptions {
 export function createMiddleware(options: MiddlewareOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     thresholds,
     fallbackProfile,
     classifyFromHeaders: useHeaders,
diff --git a/packages/middleware-hono/README.md b/packages/middleware-hono/README.md
index d75c2fb..71837fa 100644
--- a/packages/middleware-hono/README.md
+++ b/packages/middleware-hono/README.md
@@ -80,21 +80,21 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 ## Options
 
-| Option                | Type                                 | Default           | Description                                   |
-| --------------------- | ------------------------------------ | ----------------- | --------------------------------------------- |
-| `storage`             | `StorageAdapter`                     | _(required)_      | Storage backend for profiles                  |
-| `cookieName`          | `string`                             | `'dr_session'`    | Session cookie name                           |
-| `cookiePath`          | `string`                             | `'/'`             | Cookie path                                   |
-| `cookieSecure`        | `boolean`                            | `false`           | Set `Secure` flag on the session cookie       |
-| `ttl`                 | `number`                             | `86400` (24h)     | Profile TTL in seconds                        |
-| `rejectBots`          | `boolean`                            | `true`            | Reject bot/crawler probe submissions          |
-| `thresholds`          | `TierThresholds`                     | Built-in defaults | Custom tier thresholds (validated at startup) |
-| `injectProbe`         | `boolean`                            | `false`           | Auto-inject probe into HTML                   |
-| `probePath`           | `string`                             | —                 | Custom probe endpoint path                    |
-| `probeNonce`          | `string \| ((c: Context) => string)` | —                 | CSP nonce for injected script                 |
-| `fallbackProfile`     | `FallbackProfile`                    | —                 | Fallback profile for first requests           |
-| `classifyFromHeaders` | `boolean`                            | `false`           | Classify from UA/Client Hints                 |
-| `onEvent`             | `OnEventCallback`                    | —                 | Observability callback for logging/metrics    |
+| Option                | Type                                 | Default                   | Description                                   |
+| --------------------- | ------------------------------------ | ------------------------- | --------------------------------------------- |
+| `storage`             | `StorageAdapter`                     | _(required)_              | Storage backend for profiles                  |
+| `cookieName`          | `string`                             | `'device-router-session'` | Session cookie name                           |
+| `cookiePath`          | `string`                             | `'/'`                     | Cookie path                                   |
+| `cookieSecure`        | `boolean`                            | `false`                   | Set `Secure` flag on the session cookie       |
+| `ttl`                 | `number`                             | `86400` (24h)             | Profile TTL in seconds                        |
+| `rejectBots`          | `boolean`                            | `true`                    | Reject bot/crawler probe submissions          |
+| `thresholds`          | `TierThresholds`                     | Built-in defaults         | Custom tier thresholds (validated at startup) |
+| `injectProbe`         | `boolean`                            | `false`                   | Auto-inject probe into HTML                   |
+| `probePath`           | `string`                             | —                         | Custom probe endpoint path                    |
+| `probeNonce`          | `string \| ((c: Context) => string)` | —                         | CSP nonce for injected script                 |
+| `fallbackProfile`     | `FallbackProfile`                    | —                         | Fallback profile for first requests           |
+| `classifyFromHeaders` | `boolean`                            | `false`                   | Classify from UA/Client Hints                 |
+| `onEvent`             | `OnEventCallback`                    | —                         | Observability callback for logging/metrics    |
 
 ## Observability
 
diff --git a/packages/middleware-hono/src/__tests__/endpoint.test.ts b/packages/middleware-hono/src/__tests__/endpoint.test.ts
index 95fa10f..095659e 100644
--- a/packages/middleware-hono/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-hono/src/__tests__/endpoint.test.ts
@@ -46,7 +46,7 @@ describe('createProbeEndpoint (hono)', () => {
 
     const setCookie = res.headers.get('set-cookie');
     expect(setCookie).toBeTruthy();
-    expect(setCookie).toContain('dr_session=');
+    expect(setCookie).toContain('device-router-session=');
     expect(setCookie).not.toContain('Secure');
   });
 
diff --git a/packages/middleware-hono/src/__tests__/integration.test.ts b/packages/middleware-hono/src/__tests__/integration.test.ts
index a27c185..c623e5d 100644
--- a/packages/middleware-hono/src/__tests__/integration.test.ts
+++ b/packages/middleware-hono/src/__tests__/integration.test.ts
@@ -51,7 +51,7 @@ describe('integration: probe → middleware → route (hono)', () => {
     expect(probeData.sessionToken).toBeTruthy();
 
     const testRes = await app.request('/test', {
-      headers: { Cookie: `dr_session=${probeData.sessionToken}` },
+      headers: { Cookie: `device-router-session=${probeData.sessionToken}` },
     });
 
     const testData = (await testRes.json()) as { tier: string; hints: Record<string, boolean> };
diff --git a/packages/middleware-hono/src/__tests__/middleware.test.ts b/packages/middleware-hono/src/__tests__/middleware.test.ts
index 83255ef..c259874 100644
--- a/packages/middleware-hono/src/__tests__/middleware.test.ts
+++ b/packages/middleware-hono/src/__tests__/middleware.test.ts
@@ -59,7 +59,7 @@ describe('createMiddleware (hono)', () => {
     });
 
     const res = await app.request('/test', {
-      headers: { Cookie: 'dr_session=tok1' },
+      headers: { Cookie: 'device-router-session=tok1' },
     });
     const data = (await res.json()) as { cpu: string; defer: boolean; source: string };
     expect(data.cpu).toBe('high');
@@ -88,7 +88,7 @@ describe('createMiddleware (hono)', () => {
     });
 
     const res = await app.request('/test', {
-      headers: { Cookie: 'dr_session=tok2' },
+      headers: { Cookie: 'device-router-session=tok2' },
     });
     const data = (await res.json()) as { cpu: string };
     expect(data.cpu).toBe('low');
@@ -142,7 +142,7 @@ describe('createMiddleware (hono)', () => {
       app.get('/test', (c) => c.json(c.get('deviceProfile')));
 
       const res = await app.request('/test', {
-        headers: { Cookie: 'dr_session=expired' },
+        headers: { Cookie: 'device-router-session=expired' },
       });
       const data = (await res.json()) as ClassifiedProfile;
       expect(data.source).toBe('fallback');
@@ -240,7 +240,7 @@ describe('createMiddleware (hono)', () => {
       app.get('/test', (c) => c.json(c.get('deviceProfile')));
 
       await app.request('/test', {
-        headers: { Cookie: 'dr_session=tok1' },
+        headers: { Cookie: 'device-router-session=tok1' },
       });
 
       expect(onEvent).toHaveBeenCalledOnce();
@@ -303,7 +303,7 @@ describe('createMiddleware (hono)', () => {
       app.get('/test', (c) => c.json(c.get('deviceProfile')));
 
       const res = await app.request('/test', {
-        headers: { Cookie: 'dr_session=tok1' },
+        headers: { Cookie: 'device-router-session=tok1' },
       });
 
       expect(res.status).toBe(500);
@@ -334,7 +334,7 @@ describe('createMiddleware (hono)', () => {
       app.get('/test', (c) => c.json({ ok: true }));
 
       const res = await app.request('/test', {
-        headers: { Cookie: 'dr_session=tok1' },
+        headers: { Cookie: 'device-router-session=tok1' },
       });
 
       expect(res.status).toBe(200);
diff --git a/packages/middleware-hono/src/endpoint.ts b/packages/middleware-hono/src/endpoint.ts
index 06b18ef..8149271 100644
--- a/packages/middleware-hono/src/endpoint.ts
+++ b/packages/middleware-hono/src/endpoint.ts
@@ -17,7 +17,7 @@ export interface EndpointOptions {
 export function createProbeEndpoint(options: EndpointOptions): Handler {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure = false,
     ttl = 86400,
diff --git a/packages/middleware-hono/src/index.ts b/packages/middleware-hono/src/index.ts
index 141876e..239072e 100644
--- a/packages/middleware-hono/src/index.ts
+++ b/packages/middleware-hono/src/index.ts
@@ -27,7 +27,7 @@ export interface DeviceRouterOptions {
 export function createDeviceRouter(options: DeviceRouterOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure,
     ttl = 86400,
diff --git a/packages/middleware-hono/src/middleware.ts b/packages/middleware-hono/src/middleware.ts
index 4eb29d5..ce078bd 100644
--- a/packages/middleware-hono/src/middleware.ts
+++ b/packages/middleware-hono/src/middleware.ts
@@ -35,7 +35,7 @@ export type DeviceRouterEnv = {
 export function createMiddleware(options: MiddlewareOptions): MiddlewareHandler<DeviceRouterEnv> {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     thresholds,
     fallbackProfile,
     classifyFromHeaders: useHeaders,
diff --git a/packages/middleware-koa/README.md b/packages/middleware-koa/README.md
index 432ff8d..80f2e6a 100644
--- a/packages/middleware-koa/README.md
+++ b/packages/middleware-koa/README.md
@@ -84,21 +84,21 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 
 ## Options
 
-| Option                | Type                                   | Default           | Description                                   |
-| --------------------- | -------------------------------------- | ----------------- | --------------------------------------------- |
-| `storage`             | `StorageAdapter`                       | _(required)_      | Storage backend for profiles                  |
-| `cookieName`          | `string`                               | `'dr_session'`    | Session cookie name                           |
-| `cookiePath`          | `string`                               | `'/'`             | Cookie path                                   |
-| `cookieSecure`        | `boolean`                              | `false`           | Set `Secure` flag on the session cookie       |
-| `ttl`                 | `number`                               | `86400` (24h)     | Profile TTL in seconds                        |
-| `rejectBots`          | `boolean`                              | `true`            | Reject bot/crawler probe submissions          |
-| `thresholds`          | `TierThresholds`                       | Built-in defaults | Custom tier thresholds (validated at startup) |
-| `injectProbe`         | `boolean`                              | `false`           | Auto-inject probe into HTML                   |
-| `probePath`           | `string`                               | —                 | Custom probe endpoint path                    |
-| `probeNonce`          | `string \| ((ctx: Context) => string)` | —                 | CSP nonce for injected script                 |
-| `fallbackProfile`     | `FallbackProfile`                      | —                 | Fallback profile for first requests           |
-| `classifyFromHeaders` | `boolean`                              | `false`           | Classify from UA/Client Hints                 |
-| `onEvent`             | `OnEventCallback`                      | —                 | Observability callback for logging/metrics    |
+| Option                | Type                                   | Default                   | Description                                   |
+| --------------------- | -------------------------------------- | ------------------------- | --------------------------------------------- |
+| `storage`             | `StorageAdapter`                       | _(required)_              | Storage backend for profiles                  |
+| `cookieName`          | `string`                               | `'device-router-session'` | Session cookie name                           |
+| `cookiePath`          | `string`                               | `'/'`                     | Cookie path                                   |
+| `cookieSecure`        | `boolean`                              | `false`                   | Set `Secure` flag on the session cookie       |
+| `ttl`                 | `number`                               | `86400` (24h)             | Profile TTL in seconds                        |
+| `rejectBots`          | `boolean`                              | `true`                    | Reject bot/crawler probe submissions          |
+| `thresholds`          | `TierThresholds`                       | Built-in defaults         | Custom tier thresholds (validated at startup) |
+| `injectProbe`         | `boolean`                              | `false`                   | Auto-inject probe into HTML                   |
+| `probePath`           | `string`                               | —                         | Custom probe endpoint path                    |
+| `probeNonce`          | `string \| ((ctx: Context) => string)` | —                         | CSP nonce for injected script                 |
+| `fallbackProfile`     | `FallbackProfile`                      | —                         | Fallback profile for first requests           |
+| `classifyFromHeaders` | `boolean`                              | `false`                   | Classify from UA/Client Hints                 |
+| `onEvent`             | `OnEventCallback`                      | —                         | Observability callback for logging/metrics    |
 
 ## Observability
 
diff --git a/packages/middleware-koa/src/__tests__/endpoint.test.ts b/packages/middleware-koa/src/__tests__/endpoint.test.ts
index 17beb22..fc4b4af 100644
--- a/packages/middleware-koa/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-koa/src/__tests__/endpoint.test.ts
@@ -48,7 +48,7 @@ describe('createProbeEndpoint (koa)', () => {
     expect((ctx.body as { ok: boolean }).ok).toBe(true);
     expect((ctx.body as { sessionToken: string }).sessionToken).toBeTruthy();
     expect(ctx.cookies.set).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({
         httpOnly: true,
@@ -65,7 +65,7 @@ describe('createProbeEndpoint (koa)', () => {
     await handler(ctx);
 
     expect(ctx.cookies.set).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({ secure: false }),
     );
@@ -78,7 +78,7 @@ describe('createProbeEndpoint (koa)', () => {
     await handler(ctx);
 
     expect(ctx.cookies.set).toHaveBeenCalledWith(
-      'dr_session',
+      'device-router-session',
       expect.any(String),
       expect.objectContaining({ secure: true }),
     );
@@ -86,7 +86,10 @@ describe('createProbeEndpoint (koa)', () => {
 
   it('reuses existing session token from cookie', async () => {
     const handler = createProbeEndpoint({ storage });
-    const ctx = createMockCtx({ hardwareConcurrency: 4 }, { dr_session: 'existing-tok' });
+    const ctx = createMockCtx(
+      { hardwareConcurrency: 4 },
+      { 'device-router-session': 'existing-tok' },
+    );
 
     await handler(ctx);
 
diff --git a/packages/middleware-koa/src/__tests__/integration.test.ts b/packages/middleware-koa/src/__tests__/integration.test.ts
index 428388d..a92426d 100644
--- a/packages/middleware-koa/src/__tests__/integration.test.ts
+++ b/packages/middleware-koa/src/__tests__/integration.test.ts
@@ -93,7 +93,7 @@ describe('integration: probe → middleware → route (koa)', () => {
     expect(setCookie).toBeTruthy();
 
     const testRes = await fetch(`${baseUrl}/test`, {
-      headers: { Cookie: `dr_session=${probeData.sessionToken}` },
+      headers: { Cookie: `device-router-session=${probeData.sessionToken}` },
     });
 
     const testData = (await testRes.json()) as { tier: string; hints: Record<string, boolean> };
diff --git a/packages/middleware-koa/src/__tests__/middleware.test.ts b/packages/middleware-koa/src/__tests__/middleware.test.ts
index 267efbc..427b34a 100644
--- a/packages/middleware-koa/src/__tests__/middleware.test.ts
+++ b/packages/middleware-koa/src/__tests__/middleware.test.ts
@@ -59,7 +59,7 @@ describe('createMiddleware (koa)', () => {
 
   it('sets deviceProfile to null when profile not found', async () => {
     const mw = createMiddleware({ storage });
-    const ctx = createMockCtx({ dr_session: 'unknown' });
+    const ctx = createMockCtx({ 'device-router-session': 'unknown' });
     const next = vi.fn();
 
     await mw(ctx, next);
@@ -79,7 +79,7 @@ describe('createMiddleware (koa)', () => {
     storage._store.set('tok1', profile);
 
     const mw = createMiddleware({ storage });
-    const ctx = createMockCtx({ dr_session: 'tok1' });
+    const ctx = createMockCtx({ 'device-router-session': 'tok1' });
     const next = vi.fn();
 
     await mw(ctx, next);
@@ -118,7 +118,7 @@ describe('createMiddleware (koa)', () => {
       storage,
       thresholds: { cpu: { lowUpperBound: 6, midUpperBound: 8 } },
     });
-    const ctx = createMockCtx({ dr_session: 'tok2' });
+    const ctx = createMockCtx({ 'device-router-session': 'tok2' });
     const next = vi.fn();
 
     await mw(ctx, next);
@@ -172,7 +172,7 @@ describe('createMiddleware (koa)', () => {
 
     it('falls back when cookie exists but profile not in storage', async () => {
       const mw = createMiddleware({ storage, fallbackProfile: 'conservative' });
-      const ctx = createMockCtx({ dr_session: 'expired-token' });
+      const ctx = createMockCtx({ 'device-router-session': 'expired-token' });
       const next = vi.fn();
 
       await mw(ctx, next);
@@ -270,7 +270,7 @@ describe('createMiddleware (koa)', () => {
       storage._store.set('tok1', profile);
 
       const mw = createMiddleware({ storage, onEvent });
-      const ctx = createMockCtx({ dr_session: 'tok1' });
+      const ctx = createMockCtx({ 'device-router-session': 'tok1' });
       const next = vi.fn();
 
       await mw(ctx, next);
@@ -342,7 +342,7 @@ describe('createMiddleware (koa)', () => {
 
       storage.get = vi.fn().mockRejectedValue(new Error('Storage down'));
       const mw = createMiddleware({ storage, onEvent });
-      const ctx = createMockCtx({ dr_session: 'tok-err' });
+      const ctx = createMockCtx({ 'device-router-session': 'tok-err' });
       const next = vi.fn();
 
       await expect(mw(ctx, next)).rejects.toThrow('Storage down');
@@ -370,7 +370,7 @@ describe('createMiddleware (koa)', () => {
       storage._store.set('tok-safe', profile);
 
       const mw = createMiddleware({ storage, onEvent });
-      const ctx = createMockCtx({ dr_session: 'tok-safe' });
+      const ctx = createMockCtx({ 'device-router-session': 'tok-safe' });
       const next = vi.fn();
 
       await mw(ctx, next);
diff --git a/packages/middleware-koa/src/endpoint.ts b/packages/middleware-koa/src/endpoint.ts
index 2191624..e1bbaea 100644
--- a/packages/middleware-koa/src/endpoint.ts
+++ b/packages/middleware-koa/src/endpoint.ts
@@ -17,7 +17,7 @@ export interface EndpointOptions {
 export function createProbeEndpoint(options: EndpointOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure = false,
     ttl = 86400,
diff --git a/packages/middleware-koa/src/index.ts b/packages/middleware-koa/src/index.ts
index e508f67..2f816b3 100644
--- a/packages/middleware-koa/src/index.ts
+++ b/packages/middleware-koa/src/index.ts
@@ -27,7 +27,7 @@ export interface DeviceRouterOptions {
 export function createDeviceRouter(options: DeviceRouterOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
     cookieSecure,
     ttl = 86400,
diff --git a/packages/middleware-koa/src/middleware.ts b/packages/middleware-koa/src/middleware.ts
index 900c0a8..3dbef03 100644
--- a/packages/middleware-koa/src/middleware.ts
+++ b/packages/middleware-koa/src/middleware.ts
@@ -34,7 +34,7 @@ export interface MiddlewareOptions {
 export function createMiddleware(options: MiddlewareOptions) {
   const {
     storage,
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     thresholds,
     fallbackProfile,
     classifyFromHeaders: useHeaders,
diff --git a/packages/probe/README.md b/packages/probe/README.md
index 6c8bbce..3384532 100644
--- a/packages/probe/README.md
+++ b/packages/probe/README.md
@@ -13,21 +13,21 @@ pnpm add @device-router/probe
 The probe runs once per session in the browser. It collects device signals using standard browser APIs, then POSTs them to your server's probe endpoint. A session cookie prevents repeated collection.
 
 ```
-Browser                          Server
-  │                                │
-  │  collectSignals()              │
-  │  getBattery()                  │
-  │                                │
-  │  POST /device-router/probe     │
-  │  ─────────────────────────>    │
-  │  { hardwareConcurrency: 8,     │
-  │    deviceMemory: 8, ... }      │
-  │                                │
-  │  { sessionToken: "abc123" }    │
-  │  <─────────────────────────    │
-  │                                │
-  │  Set cookie: dr_session=abc123 │
-  └────────────────────────────────┘
+Browser                                      Server
+  │                                            │
+  │  collectSignals()                          │
+  │  getBattery()                              │
+  │                                            │
+  │  POST /device-router/probe                 │
+  │  ─────────────────────────────────────>    │
+  │  { hardwareConcurrency: 8,                 │
+  │    deviceMemory: 8, ... }                  │
+  │                                            │
+  │  { sessionToken: "abc123" }                │
+  │  <─────────────────────────────────────    │
+  │                                            │
+  │  Set cookie: device-router-session=abc123  │
+  └────────────────────────────────────────────┘
 ```
 
 ## Usage
@@ -60,7 +60,7 @@ import { runProbe } from '@device-router/probe';
 
 await runProbe({
   endpoint: '/device-router/probe', // default
-  cookieName: 'dr_session', // default
+  cookieName: 'device-router-session', // default
   cookiePath: '/', // default
 });
 ```
diff --git a/packages/probe/src/__tests__/probe.test.ts b/packages/probe/src/__tests__/probe.test.ts
index 50d0828..093feac 100644
--- a/packages/probe/src/__tests__/probe.test.ts
+++ b/packages/probe/src/__tests__/probe.test.ts
@@ -56,7 +56,7 @@ describe('runProbe', () => {
 
   it('skips probe when session cookie exists', async () => {
     Object.defineProperty(globalThis, 'document', {
-      value: { cookie: 'dr_session=abc123' },
+      value: { cookie: 'device-router-session=abc123' },
       writable: true,
       configurable: true,
     });
@@ -99,7 +99,7 @@ describe('runProbe', () => {
 
     await runProbe();
 
-    expect(mockDoc.cookie).toContain('dr_session=test-token');
+    expect(mockDoc.cookie).toContain('device-router-session=test-token');
   });
 
   it('uses custom endpoint and cookie name', async () => {
diff --git a/packages/probe/src/probe.ts b/packages/probe/src/probe.ts
index 5469368..b622cbd 100644
--- a/packages/probe/src/probe.ts
+++ b/packages/probe/src/probe.ts
@@ -7,7 +7,7 @@ export interface ProbeOptions {
 }
 
 function getCookie(name: string): string | null {
-  const match = document.cookie.match(new RegExp('(^|; )' + name + '=([^;]*)'));
+  const match = document.cookie.match(RegExp('(^|; )' + name + '=([^;]*)'));
   return match ? decodeURIComponent(match[2]) : null;
 }
 
@@ -18,7 +18,7 @@ function setCookie(name: string, value: string, path: string): void {
 export async function runProbe(options: ProbeOptions = {}): Promise<void> {
   const {
     endpoint = '/device-router/probe',
-    cookieName = 'dr_session',
+    cookieName = 'device-router-session',
     cookiePath = '/',
   } = options;
 

From c4e8f87dc788f2d2713bca62893b7eec7cbc40a8 Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Tue, 24 Feb 2026 16:35:48 +0100
Subject: [PATCH 06/12] Normalize ConnectionThresholds field names + remove
 disableAutoplay (#33)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Remove disableAutoplay rendering hint

Redundant with deferHeavyComponents — both triggered on identical
conditions (isLowEnd || isSlowConnection || isBatteryConstrained).

* Normalize ConnectionThresholds field names

Rename downlink2gUpperBound/downlink3gUpperBound/downlink4gUpperBound
to lowUpperBound/midUpperBound/highUpperBound, matching the pattern
used by CpuThresholds and MemoryThresholds.
---
 CHANGELOG.md                                  |  4 ++-
 README.md                                     |  7 ++---
 docs/api/types.md                             | 16 +++++-----
 docs/getting-started.md                       |  3 +-
 docs/profile-schema.md                        |  1 -
 examples/shared/demo-template.ts              | 29 +------------------
 packages/types/README.md                      |  4 +--
 packages/types/src/__tests__/classify.test.ts | 10 +++----
 packages/types/src/__tests__/events.test.ts   |  1 -
 packages/types/src/__tests__/hints.test.ts    |  8 -----
 packages/types/src/__tests__/validate.test.ts | 20 ++++++-------
 packages/types/src/classify.ts                | 10 +++----
 packages/types/src/hints.ts                   |  1 -
 packages/types/src/profile.ts                 |  1 -
 packages/types/src/thresholds.ts              | 12 ++++----
 packages/types/src/validate.ts                | 17 +++++------
 16 files changed, 49 insertions(+), 95 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0809df2..bee267a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,10 +4,12 @@
 
 ### Breaking Changes
 
+- **Normalize `ConnectionThresholds` field names** — Renamed `downlink2gUpperBound` → `lowUpperBound`, `downlink3gUpperBound` → `midUpperBound`, `downlink4gUpperBound` → `highUpperBound` to match the `CpuThresholds`/`MemoryThresholds` naming pattern. Update any custom `connection` threshold objects in your `thresholds` config
 - **Rename `ConnectionTier` value `'fast'` → `'high'`** — Aligns connection tier vocabulary with CPU, memory, and GPU tiers which all use `'low' | 'mid' | 'high'`. Update any code comparing `tiers.connection === 'fast'` to use `'high'` instead
 - **`classify()` and `deriveHints()` now accept `StoredSignals` instead of `RawSignals`** — These functions never used `userAgent` or `viewport` (which are stripped before storage). The narrower type makes the API honest. Existing call sites are unaffected — `RawSignals` is structurally assignable to `StoredSignals`
 - **`profile:store` event now carries `StoredSignals` instead of `RawSignals`** — The event previously emitted the raw probe payload (including `userAgent`/`viewport`), not what was actually stored. The `signals` field now matches the persisted data. `bot:reject` still carries `RawSignals` (it fires before stripping)
 - **Rename default cookie `dr_session` → `device-router-session`** — Self-documenting name before 1.0 locks the cookie in. If you hardcode `cookieName: 'dr_session'` in your options you are unaffected; if you rely on the default, existing sessions will reset once on deploy
+- **Remove `disableAutoplay` rendering hint** — `disableAutoplay` triggered on identical conditions to `deferHeavyComponents` (`isLowEnd || isSlowConnection || isBatteryConstrained`). Use `deferHeavyComponents` instead
 - **middleware-fastify: normalized return shape** — `createDeviceRouter()` now returns raw Fastify hooks instead of a `fastify-plugin` wrapped plugin. Migrate `await app.register(middleware)` → `app.addHook('preHandler', middleware)`. When using `injectProbe: true`, register the injection hook separately: `app.addHook('onSend', injectionMiddleware)`. Removed `fastify-plugin` dependency
 
 ### Features
@@ -60,7 +62,7 @@
 ### Features
 
 - **GPU detection** — Classify GPU tier from WebGL renderer string: software renderers → `low`, RTX/RX 5000+/Apple M-series → `high`, everything else → `mid`
-- **Battery API signal** — Collect battery level and charging status via `navigator.getBattery()` (Chromium-only, silently skipped elsewhere). When unplugged and below 15%, `deferHeavyComponents`, `reduceAnimations`, and `disableAutoplay` are forced on
+- **Battery API signal** — Collect battery level and charging status via `navigator.getBattery()` (Chromium-only, silently skipped elsewhere). When unplugged and below 15%, `deferHeavyComponents` and `reduceAnimations` are forced on
 - **Signal validation** — New `isValidSignals()` type guard for validating incoming probe payloads
 - **Custom GPU thresholds** — `softwarePattern` and `highEndPattern` are configurable via `GpuThresholds`
 
diff --git a/README.md b/README.md
index 3f47100..ae8ac83 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ A **~1 KB** client probe. One middleware call. Full device awareness on every re
 Responsive design adapts layout. DeviceRouter adapts **what you serve**.
 
 - A budget phone on 2G? Skip the heavy animations, defer non-critical components, prefer server-side rendering.
-- A flagship on fiber? Go all out — autoplay, full interactivity, rich visuals.
+- A flagship on fiber? Go all out — full interactivity, rich visuals.
 
 No user-agent sniffing. No guesswork. Real signals from real devices, classified into actionable tiers and rendering hints your server can act on immediately.
 
@@ -120,7 +120,6 @@ Based on tiers and user preferences, DeviceRouter derives actionable booleans:
 | `serveMinimalCSS`       | Low-end device                                         |
 | `reduceAnimations`      | Low-end device, prefers reduced motion, or low battery |
 | `useImagePlaceholders`  | Slow connection (2G/3G)                                |
-| `disableAutoplay`       | Low-end device, slow connection, or low battery        |
 | `preferServerRendering` | Low-end device                                         |
 | `disable3dEffects`      | No GPU or software renderer                            |
 
@@ -245,8 +244,8 @@ new RedisStorageAdapter(redisClient, { prefix: 'dr:profile:' });
 
 Each framework has an example app that renders a product landing page adapting in real time to device capabilities:
 
-- **Full experience** (high-end device) — animated gradient hero, SVG icons, inline charts, pulsing CTA, hover transitions, autoplay visualizer
-- **Lite experience** (low-end device) — flat solid backgrounds, Unicode icons, placeholder boxes, no animations, autoplay disabled
+- **Full experience** (high-end device) — animated gradient hero, SVG icons, inline charts, pulsing CTA, hover transitions
+- **Lite experience** (low-end device) — flat solid backgrounds, Unicode icons, placeholder boxes, no animations
 
 Run any example to see it in action:
 
diff --git a/docs/api/types.md b/docs/api/types.md
index eed5b11..38419f4 100644
--- a/docs/api/types.md
+++ b/docs/api/types.md
@@ -21,7 +21,7 @@ const tiers = classify({
 
 Derives rendering hints from device tiers.
 
-The `battery` signal bypasses tier classification entirely — it's transient state, not a capability. When the device is unplugged and below 15% charge, `deferHeavyComponents`, `reduceAnimations`, and `disableAutoplay` are forced on to conserve power.
+The `battery` signal bypasses tier classification entirely — it's transient state, not a capability. When the device is unplugged and below 15% charge, `deferHeavyComponents` and `reduceAnimations` are forced on to conserve power.
 
 ```typescript
 import { classify, deriveHints } from '@device-router/types';
@@ -54,7 +54,7 @@ Validates custom tier thresholds after merging with defaults. Throws a descripti
 **Validation rules:**
 
 - **CPU/Memory**: `lowUpperBound` must be less than `midUpperBound`
-- **Connection**: `downlink2gUpperBound` < `downlink3gUpperBound` < `downlink4gUpperBound`
+- **Connection**: `lowUpperBound` < `midUpperBound` < `highUpperBound`
 - **GPU**: `softwarePattern` and `highEndPattern` must be `RegExp` instances
 - All numeric values must be positive (> 0)
 
@@ -156,11 +156,11 @@ Custom thresholds for tier classification. All fields are optional — unset fie
 
 ### ConnectionThresholds
 
-| Field                  | Type     | Default | Description                    |
-| ---------------------- | -------- | ------- | ------------------------------ |
-| `downlink2gUpperBound` | `number` | `0.5`   | Mbps at or below → `'2g'` tier |
-| `downlink3gUpperBound` | `number` | `2`     | Mbps at or below → `'3g'` tier |
-| `downlink4gUpperBound` | `number` | `5`     | Mbps at or below → `'4g'` tier |
+| Field            | Type     | Default | Description                    |
+| ---------------- | -------- | ------- | ------------------------------ |
+| `lowUpperBound`  | `number` | `0.5`   | Mbps at or below → `'2g'` tier |
+| `midUpperBound`  | `number` | `2`     | Mbps at or below → `'3g'` tier |
+| `highUpperBound` | `number` | `5`     | Mbps at or below → `'4g'` tier |
 
 ### GpuThresholds
 
@@ -177,7 +177,7 @@ import { classify } from '@device-router/types';
 const tiers = classify(signals, {
   cpu: { lowUpperBound: 4, midUpperBound: 8 },
   memory: { midUpperBound: 8 },
-  connection: { downlink4gUpperBound: 10 },
+  connection: { highUpperBound: 10 },
   gpu: { highEndPattern: /\bRTX\b|\bGTX\b/i },
 });
 ```
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 98f96f8..641aeee 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -252,7 +252,7 @@ const { middleware, probeEndpoint } = createDeviceRouter({
   thresholds: {
     cpu: { lowUpperBound: 4, midUpperBound: 8 },
     memory: { midUpperBound: 8 },
-    connection: { downlink4gUpperBound: 10 },
+    connection: { highUpperBound: 10 },
   },
 });
 ```
@@ -367,6 +367,5 @@ Based on device tiers, the middleware provides boolean rendering hints:
 - `serveMinimalCSS` — Send reduced stylesheets
 - `reduceAnimations` — Disable or simplify animations
 - `useImagePlaceholders` — Show placeholders instead of full images
-- `disableAutoplay` — Prevent auto-playing media
 - `preferServerRendering` — Favor SSR over client-side rendering
 - `disable3dEffects` — Disable WebGL/3D content (no GPU or software renderer)
diff --git a/docs/profile-schema.md b/docs/profile-schema.md
index 5019ae5..52bf2bd 100644
--- a/docs/profile-schema.md
+++ b/docs/profile-schema.md
@@ -74,6 +74,5 @@ The full classified result attached to requests by the middleware.
 | `serveMinimalCSS`       | `boolean` | Low-end device                                         |
 | `reduceAnimations`      | `boolean` | Low-end device, prefers reduced motion, or low battery |
 | `useImagePlaceholders`  | `boolean` | Slow connection (2g/3g)                                |
-| `disableAutoplay`       | `boolean` | Low-end device, slow connection, or low battery        |
 | `preferServerRendering` | `boolean` | Low-end device                                         |
 | `disable3dEffects`      | `boolean` | No GPU or software renderer                            |
diff --git a/examples/shared/demo-template.ts b/examples/shared/demo-template.ts
index b2c4d6d..4b24a49 100644
--- a/examples/shared/demo-template.ts
+++ b/examples/shared/demo-template.ts
@@ -18,7 +18,6 @@ export function renderDemoPage({
           serveMinimalCSS: true,
           reduceAnimations: true,
           useImagePlaceholders: true,
-          disableAutoplay: true,
           preferServerRendering: true,
           disable3dEffects: true,
         }
@@ -28,18 +27,16 @@ export function renderDemoPage({
             serveMinimalCSS: false,
             reduceAnimations: false,
             useImagePlaceholders: false,
-            disableAutoplay: false,
             preferServerRendering: false,
             disable3dEffects: false,
           }
         : profile?.hints;
 
-  // Five booleans derived from hints drive all rendering decisions
+  // Four booleans derived from hints drive all rendering decisions
   const full = !hints?.deferHeavyComponents;
   const animate = !hints?.reduceAnimations;
   const richCSS = !hints?.serveMinimalCSS;
   const showImages = !hints?.useImagePlaceholders;
-  const autoplay = !hints?.disableAutoplay;
 
   const activeMode = forceParam === 'full' ? 'full' : forceParam === 'lite' ? 'lite' : 'auto';
 
@@ -97,10 +94,6 @@ export function renderDemoPage({
     .gallery-tile{background:#fff;border-radius:12px;padding:1.5rem;text-align:center;border:1px solid #e2e8f0}
     .gallery-tile h4{margin-top:0.75rem;font-size:0.8125rem;color:#64748b;font-weight:500}
     .placeholder{background:#e2e8f0;border-radius:8px;height:120px;display:flex;align-items:center;justify-content:center;color:#94a3b8;font-size:0.8rem}
-    .autoplay-section{text-align:center;padding:1.5rem;max-width:960px;margin:0 auto}
-    .autoplay-bars{display:flex;gap:4px;justify-content:center;align-items:flex-end;height:40px;margin-bottom:0.75rem}
-    .autoplay-bars span{display:block;width:6px;background:#4f46e5;border-radius:3px}
-    .autoplay-label{font-size:0.8125rem;color:#64748b}
     .profile-panel{max-width:960px;margin:1.5rem auto;padding:0 1.5rem}
     .profile-panel summary{cursor:pointer;font-weight:600;padding:0.75rem 0;font-size:1rem}
     .profile-panel pre{background:#f1f5f9;padding:1rem;border-radius:8px;overflow-x:auto;font-size:0.8rem;line-height:1.6}
@@ -139,13 +132,6 @@ ${
     .gallery-tile:nth-child(2){animation-delay:0.15s}
     .gallery-tile:nth-child(3){animation-delay:0.3s}
     @keyframes bounce{0%,100%{height:8px}50%{height:100%}}
-    .autoplay-bars.animated span{animation:bounce 0.8s ease-in-out infinite}
-    .autoplay-bars.animated span:nth-child(2){animation-delay:0.1s}
-    .autoplay-bars.animated span:nth-child(3){animation-delay:0.2s}
-    .autoplay-bars.animated span:nth-child(4){animation-delay:0.3s}
-    .autoplay-bars.animated span:nth-child(5){animation-delay:0.4s}
-    .autoplay-bars.animated span:nth-child(6){animation-delay:0.5s}
-    .autoplay-bars.animated span:nth-child(7){animation-delay:0.6s}
   </style>`
     : ''
 }
@@ -223,19 +209,6 @@ ${
 }
   </div>
 
-  <div class="autoplay-section">
-    <div class="autoplay-bars${autoplay ? ' animated' : ''}">
-      <span style="height:12px"></span>
-      <span style="height:28px"></span>
-      <span style="height:20px"></span>
-      <span style="height:36px"></span>
-      <span style="height:16px"></span>
-      <span style="height:32px"></span>
-      <span style="height:24px"></span>
-    </div>
-    <div class="autoplay-label">Autoplay: ${autoplay ? 'On' : 'Disabled'}</div>
-  </div>
-
   <details class="profile-panel">
     <summary>Device Profile</summary>
 ${
diff --git a/packages/types/README.md b/packages/types/README.md
index ce680b4..8dc2355 100644
--- a/packages/types/README.md
+++ b/packages/types/README.md
@@ -36,7 +36,6 @@ const hints = deriveHints(tiers, signals);
 //   serveMinimalCSS: false,
 //   reduceAnimations: false,
 //   useImagePlaceholders: false,
-//   disableAutoplay: false,
 //   preferServerRendering: false,
 //   disable3dEffects: false,
 // }
@@ -50,7 +49,6 @@ Rendering hints are derived from tiers and transient signals:
 | `serveMinimalCSS`       | Low-end device                                         |
 | `reduceAnimations`      | Low-end device, prefers reduced motion, or low battery |
 | `useImagePlaceholders`  | Slow connection (2G/3G)                                |
-| `disableAutoplay`       | Low-end device, slow connection, or low battery        |
 | `preferServerRendering` | Low-end device                                         |
 | `disable3dEffects`      | No GPU or software renderer                            |
 
@@ -66,7 +64,7 @@ import { classify } from '@device-router/types';
 const tiers = classify(signals, {
   cpu: { lowUpperBound: 4, midUpperBound: 8 },
   memory: { midUpperBound: 8 },
-  connection: { downlink4gUpperBound: 10 },
+  connection: { highUpperBound: 10 },
   gpu: { highEndPattern: /\bRTX\b|\bGTX\b/i },
 });
 ```
diff --git a/packages/types/src/__tests__/classify.test.ts b/packages/types/src/__tests__/classify.test.ts
index 1ac9116..d93572d 100644
--- a/packages/types/src/__tests__/classify.test.ts
+++ b/packages/types/src/__tests__/classify.test.ts
@@ -93,18 +93,18 @@ describe('classifyConnection', () => {
 
   it('uses custom downlink thresholds', () => {
     // With wider 2g band (up to 1 Mbps)
-    expect(classifyConnection(undefined, 0.8, { downlink2gUpperBound: 1 })).toBe('2g');
+    expect(classifyConnection(undefined, 0.8, { lowUpperBound: 1 })).toBe('2g');
     // Default would classify 0.8 as 3g, custom keeps it as 2g
     expect(classifyConnection(undefined, 0.8)).toBe('3g');
 
     // Custom 4g upper bound
-    expect(classifyConnection(undefined, 8, { downlink4gUpperBound: 10 })).toBe('4g');
+    expect(classifyConnection(undefined, 8, { highUpperBound: 10 })).toBe('4g');
     expect(classifyConnection(undefined, 8)).toBe('high');
   });
 
   it('effectiveType string matches are not affected by thresholds', () => {
-    expect(classifyConnection('2g', undefined, { downlink2gUpperBound: 0.1 })).toBe('2g');
-    expect(classifyConnection('3g', undefined, { downlink3gUpperBound: 0.1 })).toBe('3g');
+    expect(classifyConnection('2g', undefined, { lowUpperBound: 0.1 })).toBe('2g');
+    expect(classifyConnection('3g', undefined, { midUpperBound: 0.1 })).toBe('3g');
   });
 });
 
@@ -204,7 +204,7 @@ describe('classify', () => {
       {
         cpu: { lowUpperBound: 4 },
         memory: { lowUpperBound: 4 },
-        connection: { downlink4gUpperBound: 3 },
+        connection: { highUpperBound: 3 },
       },
     );
     expect(result).toEqual({ cpu: 'low', memory: 'low', connection: 'high', gpu: 'none' });
diff --git a/packages/types/src/__tests__/events.test.ts b/packages/types/src/__tests__/events.test.ts
index d09bb5a..b7b456f 100644
--- a/packages/types/src/__tests__/events.test.ts
+++ b/packages/types/src/__tests__/events.test.ts
@@ -11,7 +11,6 @@ const sampleEvent: DeviceRouterEvent = {
     serveMinimalCSS: false,
     reduceAnimations: false,
     useImagePlaceholders: false,
-    disableAutoplay: false,
     preferServerRendering: false,
     disable3dEffects: false,
   },
diff --git a/packages/types/src/__tests__/hints.test.ts b/packages/types/src/__tests__/hints.test.ts
index ba37244..514774d 100644
--- a/packages/types/src/__tests__/hints.test.ts
+++ b/packages/types/src/__tests__/hints.test.ts
@@ -9,7 +9,6 @@ describe('deriveHints', () => {
       serveMinimalCSS: true,
       reduceAnimations: true,
       useImagePlaceholders: true,
-      disableAutoplay: true,
       preferServerRendering: true,
       disable3dEffects: true,
     });
@@ -22,7 +21,6 @@ describe('deriveHints', () => {
       serveMinimalCSS: false,
       reduceAnimations: false,
       useImagePlaceholders: false,
-      disableAutoplay: false,
       preferServerRendering: false,
       disable3dEffects: false,
     });
@@ -40,7 +38,6 @@ describe('deriveHints', () => {
     const hints = deriveHints({ cpu: 'high', memory: 'high', connection: '3g', gpu: 'high' });
     expect(hints.deferHeavyComponents).toBe(true);
     expect(hints.useImagePlaceholders).toBe(true);
-    expect(hints.disableAutoplay).toBe(true);
     expect(hints.serveMinimalCSS).toBe(false);
     expect(hints.preferServerRendering).toBe(false);
   });
@@ -78,7 +75,6 @@ describe('deriveHints', () => {
     );
     expect(hints.deferHeavyComponents).toBe(true);
     expect(hints.reduceAnimations).toBe(true);
-    expect(hints.disableAutoplay).toBe(true);
     // Capability-based hints stay permissive
     expect(hints.serveMinimalCSS).toBe(false);
     expect(hints.useImagePlaceholders).toBe(false);
@@ -93,7 +89,6 @@ describe('deriveHints', () => {
     );
     expect(hints.deferHeavyComponents).toBe(false);
     expect(hints.reduceAnimations).toBe(false);
-    expect(hints.disableAutoplay).toBe(false);
   });
 
   it('does not constrain when battery above threshold', () => {
@@ -103,14 +98,12 @@ describe('deriveHints', () => {
     );
     expect(hints.deferHeavyComponents).toBe(false);
     expect(hints.reduceAnimations).toBe(false);
-    expect(hints.disableAutoplay).toBe(false);
   });
 
   it('does not change behavior when battery signal is absent', () => {
     const hints = deriveHints({ cpu: 'high', memory: 'high', connection: 'high', gpu: 'high' }, {});
     expect(hints.deferHeavyComponents).toBe(false);
     expect(hints.reduceAnimations).toBe(false);
-    expect(hints.disableAutoplay).toBe(false);
   });
 
   it('does not constrain at exactly 0.15 (strict less-than)', () => {
@@ -120,6 +113,5 @@ describe('deriveHints', () => {
     );
     expect(hints.deferHeavyComponents).toBe(false);
     expect(hints.reduceAnimations).toBe(false);
-    expect(hints.disableAutoplay).toBe(false);
   });
 });
diff --git a/packages/types/src/__tests__/validate.test.ts b/packages/types/src/__tests__/validate.test.ts
index 4dbec63..ef31b77 100644
--- a/packages/types/src/__tests__/validate.test.ts
+++ b/packages/types/src/__tests__/validate.test.ts
@@ -99,7 +99,7 @@ describe('validateThresholds', () => {
       validateThresholds({
         cpu: { lowUpperBound: 2, midUpperBound: 4 },
         memory: { lowUpperBound: 2, midUpperBound: 8 },
-        connection: { downlink2gUpperBound: 0.5, downlink3gUpperBound: 2, downlink4gUpperBound: 5 },
+        connection: { lowUpperBound: 0.5, midUpperBound: 2, highUpperBound: 5 },
         gpu: { softwarePattern: /SwiftShader/i, highEndPattern: /RTX/i },
       }),
     ).not.toThrow();
@@ -138,19 +138,17 @@ describe('validateThresholds', () => {
     );
   });
 
-  it('throws on inverted connection bounds (2g >= 3g)', () => {
+  it('throws on inverted connection bounds (low >= mid)', () => {
     expect(() =>
-      validateThresholds({ connection: { downlink2gUpperBound: 5, downlink3gUpperBound: 2 } }),
-    ).toThrow(
-      /connection\.downlink2gUpperBound \(5\) must be less than connection\.downlink3gUpperBound \(2\)/,
-    );
+      validateThresholds({ connection: { lowUpperBound: 5, midUpperBound: 2 } }),
+    ).toThrow(/connection\.lowUpperBound \(5\) must be less than connection\.midUpperBound \(2\)/);
   });
 
-  it('throws on inverted connection bounds (3g >= 4g)', () => {
+  it('throws on inverted connection bounds (mid >= high)', () => {
     expect(() =>
-      validateThresholds({ connection: { downlink3gUpperBound: 10, downlink4gUpperBound: 5 } }),
+      validateThresholds({ connection: { midUpperBound: 10, highUpperBound: 5 } }),
     ).toThrow(
-      /connection\.downlink3gUpperBound \(10\) must be less than connection\.downlink4gUpperBound \(5\)/,
+      /connection\.midUpperBound \(10\) must be less than connection\.highUpperBound \(5\)/,
     );
   });
 
@@ -167,8 +165,8 @@ describe('validateThresholds', () => {
   });
 
   it('throws on negative connection threshold', () => {
-    expect(() => validateThresholds({ connection: { downlink2gUpperBound: -0.5 } })).toThrow(
-      /connection\.downlink2gUpperBound must be positive/,
+    expect(() => validateThresholds({ connection: { lowUpperBound: -0.5 } })).toThrow(
+      /connection\.lowUpperBound must be positive/,
     );
   });
 
diff --git a/packages/types/src/classify.ts b/packages/types/src/classify.ts
index 9abca98..ef95b3e 100644
--- a/packages/types/src/classify.ts
+++ b/packages/types/src/classify.ts
@@ -39,19 +39,19 @@ export function classifyConnection(
   downlink?: number,
   thresholds?: Partial<import('./thresholds.js').ConnectionThresholds>,
 ): ConnectionTier {
-  const { downlink2gUpperBound, downlink3gUpperBound, downlink4gUpperBound } = {
+  const { lowUpperBound, midUpperBound, highUpperBound } = {
     ...DEFAULT_CONNECTION_THRESHOLDS,
     ...thresholds,
   };
 
   if (effectiveType === 'slow-2g' || effectiveType === '2g') return '2g';
   if (effectiveType === '3g') return '3g';
-  if (effectiveType === '4g' && downlink != null && downlink < downlink4gUpperBound) return '4g';
+  if (effectiveType === '4g' && downlink != null && downlink < highUpperBound) return '4g';
   if (effectiveType === '4g') return 'high';
   if (downlink != null) {
-    if (downlink < downlink2gUpperBound) return '2g';
-    if (downlink < downlink3gUpperBound) return '3g';
-    if (downlink < downlink4gUpperBound) return '4g';
+    if (downlink < lowUpperBound) return '2g';
+    if (downlink < midUpperBound) return '3g';
+    if (downlink < highUpperBound) return '4g';
     return 'high';
   }
   return '4g';
diff --git a/packages/types/src/hints.ts b/packages/types/src/hints.ts
index 41dcd69..cd0b108 100644
--- a/packages/types/src/hints.ts
+++ b/packages/types/src/hints.ts
@@ -11,7 +11,6 @@ export function deriveHints(tiers: DeviceTiers, signals?: StoredSignals): Render
     serveMinimalCSS: isLowEnd,
     reduceAnimations: isLowEnd || signals?.prefersReducedMotion === true || isBatteryConstrained,
     useImagePlaceholders: isSlowConnection,
-    disableAutoplay: isLowEnd || isSlowConnection || isBatteryConstrained,
     preferServerRendering: isLowEnd,
     disable3dEffects: tiers.gpu === 'none' || tiers.gpu === 'low',
   };
diff --git a/packages/types/src/profile.ts b/packages/types/src/profile.ts
index fc100b5..23ab1a6 100644
--- a/packages/types/src/profile.ts
+++ b/packages/types/src/profile.ts
@@ -50,7 +50,6 @@ export interface RenderingHints {
   serveMinimalCSS: boolean;
   reduceAnimations: boolean;
   useImagePlaceholders: boolean;
-  disableAutoplay: boolean;
   preferServerRendering: boolean;
   disable3dEffects: boolean;
 }
diff --git a/packages/types/src/thresholds.ts b/packages/types/src/thresholds.ts
index e353392..a1c00b8 100644
--- a/packages/types/src/thresholds.ts
+++ b/packages/types/src/thresholds.ts
@@ -9,9 +9,9 @@ export interface MemoryThresholds {
 }
 
 export interface ConnectionThresholds {
-  downlink2gUpperBound: number;
-  downlink3gUpperBound: number;
-  downlink4gUpperBound: number;
+  lowUpperBound: number;
+  midUpperBound: number;
+  highUpperBound: number;
 }
 
 export interface GpuThresholds {
@@ -37,9 +37,9 @@ export const DEFAULT_MEMORY_THRESHOLDS: MemoryThresholds = {
 };
 
 export const DEFAULT_CONNECTION_THRESHOLDS: ConnectionThresholds = {
-  downlink2gUpperBound: 0.5,
-  downlink3gUpperBound: 2,
-  downlink4gUpperBound: 5,
+  lowUpperBound: 0.5,
+  midUpperBound: 2,
+  highUpperBound: 5,
 };
 
 export const DEFAULT_GPU_THRESHOLDS: GpuThresholds = {
diff --git a/packages/types/src/validate.ts b/packages/types/src/validate.ts
index 9223c12..7d4052e 100644
--- a/packages/types/src/validate.ts
+++ b/packages/types/src/validate.ts
@@ -31,19 +31,16 @@ export function validateThresholds(thresholds: TierThresholds): void {
 
   if (thresholds.connection) {
     const conn = { ...DEFAULT_CONNECTION_THRESHOLDS, ...thresholds.connection };
-    if (conn.downlink2gUpperBound <= 0)
-      errors.push('connection.downlink2gUpperBound must be positive');
-    if (conn.downlink3gUpperBound <= 0)
-      errors.push('connection.downlink3gUpperBound must be positive');
-    if (conn.downlink4gUpperBound <= 0)
-      errors.push('connection.downlink4gUpperBound must be positive');
-    if (conn.downlink2gUpperBound >= conn.downlink3gUpperBound)
+    if (conn.lowUpperBound <= 0) errors.push('connection.lowUpperBound must be positive');
+    if (conn.midUpperBound <= 0) errors.push('connection.midUpperBound must be positive');
+    if (conn.highUpperBound <= 0) errors.push('connection.highUpperBound must be positive');
+    if (conn.lowUpperBound >= conn.midUpperBound)
       errors.push(
-        `connection.downlink2gUpperBound (${conn.downlink2gUpperBound}) must be less than connection.downlink3gUpperBound (${conn.downlink3gUpperBound})`,
+        `connection.lowUpperBound (${conn.lowUpperBound}) must be less than connection.midUpperBound (${conn.midUpperBound})`,
       );
-    if (conn.downlink3gUpperBound >= conn.downlink4gUpperBound)
+    if (conn.midUpperBound >= conn.highUpperBound)
       errors.push(
-        `connection.downlink3gUpperBound (${conn.downlink3gUpperBound}) must be less than connection.downlink4gUpperBound (${conn.downlink4gUpperBound})`,
+        `connection.midUpperBound (${conn.midUpperBound}) must be less than connection.highUpperBound (${conn.highUpperBound})`,
       );
   }
 

From 478229effd1ebbe7c4471f06d8bb1ef9cd2ed870 Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Wed, 25 Feb 2026 07:52:10 +0100
Subject: [PATCH 07/12] Add 6 additive pre-1.0 features (#34)

* Add 6 additive pre-1.0 features

StorageAdapter:
- Add clear() to interface, implement on Memory + Redis
- Add count(), keys(), has() introspection methods

Events:
- Add durationMs to bot:reject event for timing visibility
- Add errorMessage to error events + extractErrorMessage() helper

Rendering hints:
- Add limitVideoQuality, useSystemFonts, disablePrefetch

Probe:
- Add runProbeWithRetry() with exponential backoff + jitter (ESM only,
  IIFE bundle unchanged at 1022 bytes)

* Add .ckb/ to .gitignore

* Fix PR #34 review issues: remove has(), add SCAN, fix retry on 5xx

- Remove redundant has() from StorageAdapter (pure alias for exists())
- Replace Redis KEYS with SCAN-based iteration, fall back to KEYS
- Fix runProbeWithRetry to retry on 5xx (was silently returning)
- Extract shared probe internals to _internal.ts to eliminate duplication
- Move Hono validationStart before JSON parse for consistency
- Add JSDoc to durationMs fields clarifying measurement semantics
- Improve extractErrorMessage to handle plain objects with .message
- Add tests for 5xx retry, SCAN operations, extractErrorMessage
- Update CHANGELOG with has() breaking change and migration guide
---
 .gitignore                                    |   1 +
 CHANGELOG.md                                  |  15 ++
 docs/api/types.md                             |  14 +-
 docs/getting-started.md                       |   3 +
 docs/profile-schema.md                        |   3 +
 examples/shared/demo-template.ts              |   6 +
 .../src/__tests__/endpoint.test.ts            |   5 +
 .../src/__tests__/middleware.test.ts          |   4 +
 packages/middleware-express/src/endpoint.ts   |   7 +-
 packages/middleware-express/src/middleware.ts |   2 +
 .../src/__tests__/endpoint.test.ts            |   5 +
 .../src/__tests__/middleware.test.ts          |   4 +
 packages/middleware-fastify/src/endpoint.ts   |   7 +-
 packages/middleware-fastify/src/middleware.ts |   2 +
 .../src/__tests__/endpoint.test.ts            |   5 +
 .../src/__tests__/middleware.test.ts          |   4 +
 packages/middleware-hono/src/endpoint.ts      |   8 +-
 packages/middleware-hono/src/middleware.ts    |   2 +
 .../src/__tests__/endpoint.test.ts            |   5 +
 .../src/__tests__/middleware.test.ts          |   4 +
 packages/middleware-koa/src/endpoint.ts       |   7 +-
 packages/middleware-koa/src/middleware.ts     |   2 +
 packages/probe/README.md                      |  20 ++
 packages/probe/src/__tests__/retry.test.ts    | 211 ++++++++++++++++++
 packages/probe/src/_internal.ts               |  31 +++
 packages/probe/src/index.ts                   |   2 +
 packages/probe/src/probe.ts                   |   4 +-
 packages/probe/src/retry.ts                   |  51 +++++
 packages/storage/README.md                    |  18 +-
 packages/storage/src/__tests__/memory.test.ts |  47 +++-
 packages/storage/src/__tests__/redis.test.ts  | 125 ++++++++++-
 packages/storage/src/interface.ts             |   3 +
 packages/storage/src/memory.ts                |  22 +-
 packages/storage/src/redis.ts                 |  50 ++++-
 packages/types/README.md                      |   7 +
 packages/types/src/__tests__/events.test.ts   |  31 ++-
 packages/types/src/__tests__/hints.test.ts    |  13 ++
 packages/types/src/events.ts                  |  18 ++
 packages/types/src/hints.ts                   |   3 +
 packages/types/src/index.ts                   |   2 +-
 packages/types/src/profile.ts                 |   3 +
 41 files changed, 755 insertions(+), 21 deletions(-)
 create mode 100644 packages/probe/src/__tests__/retry.test.ts
 create mode 100644 packages/probe/src/_internal.ts
 create mode 100644 packages/probe/src/retry.ts

diff --git a/.gitignore b/.gitignore
index fb8e427..485e666 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,4 +7,5 @@ coverage/
 *.tsbuildinfo
 .turbo/
 .DS_Store
+.ckb/
 *.log
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bee267a..cd67e24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,12 +10,27 @@
 - **`profile:store` event now carries `StoredSignals` instead of `RawSignals`** — The event previously emitted the raw probe payload (including `userAgent`/`viewport`), not what was actually stored. The `signals` field now matches the persisted data. `bot:reject` still carries `RawSignals` (it fires before stripping)
 - **Rename default cookie `dr_session` → `device-router-session`** — Self-documenting name before 1.0 locks the cookie in. If you hardcode `cookieName: 'dr_session'` in your options you are unaffected; if you rely on the default, existing sessions will reset once on deploy
 - **Remove `disableAutoplay` rendering hint** — `disableAutoplay` triggered on identical conditions to `deferHeavyComponents` (`isLowEnd || isSlowConnection || isBatteryConstrained`). Use `deferHeavyComponents` instead
+- **Remove `has()` from `StorageAdapter`** — `has()` was a redundant alias for `exists()`. Custom adapters must remove their `has()` implementation
 - **middleware-fastify: normalized return shape** — `createDeviceRouter()` now returns raw Fastify hooks instead of a `fastify-plugin` wrapped plugin. Migrate `await app.register(middleware)` → `app.addHook('preHandler', middleware)`. When using `injectProbe: true`, register the injection hook separately: `app.addHook('onSend', injectionMiddleware)`. Removed `fastify-plugin` dependency
 
+### Migration Guide
+
+If you have a custom `StorageAdapter` implementation:
+
+- Remove the `has()` method — use `exists()` instead
+- Replace any `adapter.has(token)` calls with `adapter.exists(token)`
+
 ### Features
 
 - **Composable middleware** — `createMiddleware()`, `createProbeEndpoint()`, and `createInjectionMiddleware()` are now first-class exports with full threshold validation and documentation. Use them independently for fine-grained control without the `createDeviceRouter()` factory
 - **`loadProbeScript()` utility** — New helper exported from all middleware packages that reads the minified probe bundle and optionally rewrites the endpoint URL. Pairs with `createInjectionMiddleware()` for standalone probe injection
+- **`clear()` on StorageAdapter** — `clear()` is now part of the `StorageAdapter` interface. `MemoryStorageAdapter` and `RedisStorageAdapter` both implement it. Redis implementation uses SCAN (when available) or KEYS + `DEL` with graceful error handling
+- **StorageAdapter introspection** — New `count()` and `keys()` methods on `StorageAdapter` for inspecting stored profiles. `keys()` returns session tokens (not prefixed keys). All methods handle errors gracefully on Redis
+- **Redis SCAN support** — `RedisStorageAdapter` uses the optional `scan()` method on the client for `clear()`, `count()`, and `keys()` operations, avoiding the blocking `KEYS` command. Falls back to `KEYS` when `scan` is not available
+- **`durationMs` on `bot:reject` event** — The `bot:reject` event now includes `durationMs` measuring validation and bot detection time, matching the pattern used by `profile:store`
+- **`errorMessage` on error events** — Error events now include a pre-extracted `errorMessage: string` field, avoiding the need to narrow the `error: unknown` field. New `extractErrorMessage()` helper exported from `@device-router/types`
+- **New rendering hints** — Three new hints: `limitVideoQuality` (slow connection or low battery), `useSystemFonts` (low-end device or slow connection), `disablePrefetch` (slow connection or low battery)
+- **Probe retry logic** — New `runProbeWithRetry()` function with exponential backoff and jitter. Exported from `@device-router/probe` as an ESM-only export (does not affect the IIFE bundle size)
 
 ## 0.4.0 (2026-02-24)
 
diff --git a/docs/api/types.md b/docs/api/types.md
index 38419f4..15e44fd 100644
--- a/docs/api/types.md
+++ b/docs/api/types.md
@@ -85,6 +85,10 @@ if (isBotSignals(signals)) {
 }
 ```
 
+### `extractErrorMessage(err: unknown): string`
+
+Extracts a string message from an unknown error value. Returns `err.message` for `Error` instances, otherwise `String(err)`.
+
 ### `classifyFromHeaders(headers): DeviceTiers`
 
 Classifies device capabilities from HTTP request headers (User-Agent and Client Hints). Useful for first-request classification before the probe has run.
@@ -225,8 +229,14 @@ type DeviceRouterEvent =
       durationMs: number;
     }
   | { type: 'profile:store'; sessionToken: string; signals: StoredSignals; durationMs: number }
-  | { type: 'bot:reject'; sessionToken: string; signals: RawSignals }
-  | { type: 'error'; error: unknown; phase: 'middleware' | 'endpoint'; sessionToken?: string };
+  | { type: 'bot:reject'; sessionToken: string; signals: RawSignals; durationMs: number }
+  | {
+      type: 'error';
+      error: unknown;
+      errorMessage: string;
+      phase: 'middleware' | 'endpoint';
+      sessionToken?: string;
+    };
 ```
 
 ### `OnEventCallback`
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 641aeee..cde76ab 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -369,3 +369,6 @@ Based on device tiers, the middleware provides boolean rendering hints:
 - `useImagePlaceholders` — Show placeholders instead of full images
 - `preferServerRendering` — Favor SSR over client-side rendering
 - `disable3dEffects` — Disable WebGL/3D content (no GPU or software renderer)
+- `limitVideoQuality` — Serve lower resolution video, skip HD streams
+- `useSystemFonts` — Skip loading custom web fonts
+- `disablePrefetch` — Don't speculatively fetch resources
diff --git a/docs/profile-schema.md b/docs/profile-schema.md
index 52bf2bd..8ef3013 100644
--- a/docs/profile-schema.md
+++ b/docs/profile-schema.md
@@ -76,3 +76,6 @@ The full classified result attached to requests by the middleware.
 | `useImagePlaceholders`  | `boolean` | Slow connection (2g/3g)                                |
 | `preferServerRendering` | `boolean` | Low-end device                                         |
 | `disable3dEffects`      | `boolean` | No GPU or software renderer                            |
+| `limitVideoQuality`     | `boolean` | Slow connection or low battery                         |
+| `useSystemFonts`        | `boolean` | Low-end device or slow connection                      |
+| `disablePrefetch`       | `boolean` | Slow connection or low battery                         |
diff --git a/examples/shared/demo-template.ts b/examples/shared/demo-template.ts
index 4b24a49..0381d73 100644
--- a/examples/shared/demo-template.ts
+++ b/examples/shared/demo-template.ts
@@ -20,6 +20,9 @@ export function renderDemoPage({
           useImagePlaceholders: true,
           preferServerRendering: true,
           disable3dEffects: true,
+          limitVideoQuality: true,
+          useSystemFonts: true,
+          disablePrefetch: true,
         }
       : forceParam === 'full'
         ? {
@@ -29,6 +32,9 @@ export function renderDemoPage({
             useImagePlaceholders: false,
             preferServerRendering: false,
             disable3dEffects: false,
+            limitVideoQuality: false,
+            useSystemFonts: false,
+            disablePrefetch: false,
           }
         : profile?.hints;
 
diff --git a/packages/middleware-express/src/__tests__/endpoint.test.ts b/packages/middleware-express/src/__tests__/endpoint.test.ts
index 944a13b..33454b4 100644
--- a/packages/middleware-express/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-express/src/__tests__/endpoint.test.ts
@@ -9,6 +9,9 @@ function createMockStorage(): StorageAdapter {
     set: vi.fn().mockResolvedValue(undefined),
     delete: vi.fn().mockResolvedValue(undefined),
     exists: vi.fn().mockResolvedValue(false),
+    clear: vi.fn().mockResolvedValue(undefined),
+    count: vi.fn().mockResolvedValue(0),
+    keys: vi.fn().mockResolvedValue([]),
   };
 }
 
@@ -302,6 +305,7 @@ describe('createProbeEndpoint', () => {
       const event = botEvents[0] as Extract<DeviceRouterEvent, { type: 'bot:reject' }>;
       expect(typeof event.sessionToken).toBe('string');
       expect(event.signals).toEqual({});
+      expect(typeof event.durationMs).toBe('number');
     });
 
     it('emits error event on storage failure', async () => {
@@ -323,6 +327,7 @@ describe('createProbeEndpoint', () => {
       expect(event.phase).toBe('endpoint');
       expect(event.error).toBeInstanceOf(Error);
       expect((event.error as Error).message).toBe('Redis down');
+      expect(event.errorMessage).toBe('Redis down');
       expect(res.status).toHaveBeenCalledWith(500);
     });
 
diff --git a/packages/middleware-express/src/__tests__/middleware.test.ts b/packages/middleware-express/src/__tests__/middleware.test.ts
index 963561e..493d30b 100644
--- a/packages/middleware-express/src/__tests__/middleware.test.ts
+++ b/packages/middleware-express/src/__tests__/middleware.test.ts
@@ -14,6 +14,9 @@ function createMockStorage(): StorageAdapter {
       store.delete(token);
     }),
     exists: vi.fn(async (token: string) => store.has(token)),
+    clear: vi.fn(async () => store.clear()),
+    count: vi.fn(async () => store.size),
+    keys: vi.fn(async () => [...store.keys()]),
     _store: store,
   } as StorageAdapter & { _store: Map<string, DeviceProfile> };
 }
@@ -395,6 +398,7 @@ describe('createMiddleware', () => {
       expect(event.phase).toBe('middleware');
       expect(event.error).toBeInstanceOf(Error);
       expect((event.error as Error).message).toBe('Storage down');
+      expect(event.errorMessage).toBe('Storage down');
       expect(next).toHaveBeenCalledWith(expect.any(Error));
     });
 
diff --git a/packages/middleware-express/src/endpoint.ts b/packages/middleware-express/src/endpoint.ts
index 88b0fe2..bacbcc4 100644
--- a/packages/middleware-express/src/endpoint.ts
+++ b/packages/middleware-express/src/endpoint.ts
@@ -1,7 +1,7 @@
 import type { Request, Response } from 'express';
 import type { StorageAdapter } from '@device-router/storage';
 import type { DeviceProfile, RawSignals, OnEventCallback } from '@device-router/types';
-import { isValidSignals, isBotSignals, emitEvent } from '@device-router/types';
+import { isValidSignals, isBotSignals, emitEvent, extractErrorMessage } from '@device-router/types';
 import { randomUUID } from 'node:crypto';
 
 export interface EndpointOptions {
@@ -29,6 +29,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
     let sessionToken: string | undefined;
     try {
       const signals = req.body as unknown;
+      const validationStart = performance.now();
 
       if (!isValidSignals(signals)) {
         res.status(400).json({ ok: false, error: 'Invalid probe payload' });
@@ -39,7 +40,8 @@ export function createProbeEndpoint(options: EndpointOptions) {
       sessionToken = existingToken || randomUUID();
 
       if (rejectBots && isBotSignals(signals)) {
-        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals });
+        const durationMs = performance.now() - validationStart;
+        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals, durationMs });
         res.status(403).json({ ok: false, error: 'Bot detected' });
         return;
       }
@@ -83,6 +85,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'endpoint',
         sessionToken,
       });
diff --git a/packages/middleware-express/src/middleware.ts b/packages/middleware-express/src/middleware.ts
index 3590e03..4f20859 100644
--- a/packages/middleware-express/src/middleware.ts
+++ b/packages/middleware-express/src/middleware.ts
@@ -6,6 +6,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  extractErrorMessage,
   validateThresholds,
 } from '@device-router/types';
 import type {
@@ -111,6 +112,7 @@ export function createMiddleware(options: MiddlewareOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'middleware',
         sessionToken: req.cookies?.[cookieName] as string | undefined,
       });
diff --git a/packages/middleware-fastify/src/__tests__/endpoint.test.ts b/packages/middleware-fastify/src/__tests__/endpoint.test.ts
index db05ffb..8cf3ad3 100644
--- a/packages/middleware-fastify/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-fastify/src/__tests__/endpoint.test.ts
@@ -8,6 +8,9 @@ function createMockStorage(): StorageAdapter {
     set: vi.fn().mockResolvedValue(undefined),
     delete: vi.fn().mockResolvedValue(undefined),
     exists: vi.fn().mockResolvedValue(false),
+    clear: vi.fn().mockResolvedValue(undefined),
+    count: vi.fn().mockResolvedValue(0),
+    keys: vi.fn().mockResolvedValue([]),
   };
 }
 
@@ -252,6 +255,7 @@ describe('createProbeEndpoint', () => {
           type: 'bot:reject',
           sessionToken: expect.any(String),
           signals: {},
+          durationMs: expect.any(Number),
         }),
       );
     });
@@ -270,6 +274,7 @@ describe('createProbeEndpoint', () => {
           type: 'error',
           phase: 'endpoint',
           error: expect.any(Error),
+          errorMessage: 'Redis down',
         }),
       );
       const event = onEvent.mock.calls.find(
diff --git a/packages/middleware-fastify/src/__tests__/middleware.test.ts b/packages/middleware-fastify/src/__tests__/middleware.test.ts
index 5e26f30..44df46a 100644
--- a/packages/middleware-fastify/src/__tests__/middleware.test.ts
+++ b/packages/middleware-fastify/src/__tests__/middleware.test.ts
@@ -14,6 +14,9 @@ function createMockStorage(): StorageAdapter {
       store.delete(token);
     }),
     exists: vi.fn(async (token: string) => store.has(token)),
+    clear: vi.fn(async () => store.clear()),
+    count: vi.fn(async () => store.size),
+    keys: vi.fn(async () => [...store.keys()]),
     _store: store,
   } as StorageAdapter & { _store: Map<string, DeviceProfile> };
 }
@@ -320,6 +323,7 @@ describe('createMiddleware', () => {
           type: 'error',
           phase: 'middleware',
           error: expect.any(Error),
+          errorMessage: 'Redis down',
         }),
       );
       const event = onEvent.mock.calls.find(
diff --git a/packages/middleware-fastify/src/endpoint.ts b/packages/middleware-fastify/src/endpoint.ts
index 226b43a..55bd3fd 100644
--- a/packages/middleware-fastify/src/endpoint.ts
+++ b/packages/middleware-fastify/src/endpoint.ts
@@ -2,7 +2,7 @@ import type { FastifyRequest, FastifyReply } from 'fastify';
 import '@fastify/cookie';
 import type { StorageAdapter } from '@device-router/storage';
 import type { DeviceProfile, RawSignals, OnEventCallback } from '@device-router/types';
-import { isValidSignals, isBotSignals, emitEvent } from '@device-router/types';
+import { isValidSignals, isBotSignals, emitEvent, extractErrorMessage } from '@device-router/types';
 import { randomUUID } from 'node:crypto';
 
 export interface EndpointOptions {
@@ -30,6 +30,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
     let sessionToken: string | undefined;
     try {
       const signals = req.body as unknown;
+      const validationStart = performance.now();
 
       if (!isValidSignals(signals)) {
         reply.status(400).send({ ok: false, error: 'Invalid probe payload' });
@@ -40,7 +41,8 @@ export function createProbeEndpoint(options: EndpointOptions) {
       sessionToken = existingToken || randomUUID();
 
       if (rejectBots && isBotSignals(signals)) {
-        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals });
+        const durationMs = performance.now() - validationStart;
+        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals, durationMs });
         reply.status(403).send({ ok: false, error: 'Bot detected' });
         return;
       }
@@ -84,6 +86,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'endpoint',
         sessionToken,
       });
diff --git a/packages/middleware-fastify/src/middleware.ts b/packages/middleware-fastify/src/middleware.ts
index 4098cd0..9ac7d81 100644
--- a/packages/middleware-fastify/src/middleware.ts
+++ b/packages/middleware-fastify/src/middleware.ts
@@ -7,6 +7,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  extractErrorMessage,
   validateThresholds,
 } from '@device-router/types';
 import type {
@@ -106,6 +107,7 @@ export function createMiddleware(options: MiddlewareOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'middleware',
         sessionToken: req.cookies?.[cookieName],
       });
diff --git a/packages/middleware-hono/src/__tests__/endpoint.test.ts b/packages/middleware-hono/src/__tests__/endpoint.test.ts
index 095659e..98ea3fa 100644
--- a/packages/middleware-hono/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-hono/src/__tests__/endpoint.test.ts
@@ -10,6 +10,9 @@ function createMockStorage(): StorageAdapter {
     set: vi.fn().mockResolvedValue(undefined),
     delete: vi.fn().mockResolvedValue(undefined),
     exists: vi.fn().mockResolvedValue(false),
+    clear: vi.fn().mockResolvedValue(undefined),
+    count: vi.fn().mockResolvedValue(0),
+    keys: vi.fn().mockResolvedValue([]),
   };
 }
 
@@ -238,6 +241,7 @@ describe('createProbeEndpoint (hono)', () => {
       expect(event.type).toBe('bot:reject');
       const botEvent = event as Extract<DeviceRouterEvent, { type: 'bot:reject' }>;
       expect(botEvent.signals).toEqual({});
+      expect(typeof botEvent.durationMs).toBe('number');
     });
 
     it('emits error event on storage failure', async () => {
@@ -261,6 +265,7 @@ describe('createProbeEndpoint (hono)', () => {
       const errorEvent = event as Extract<DeviceRouterEvent, { type: 'error' }>;
       expect(errorEvent.error).toBeInstanceOf(Error);
       expect((errorEvent.error as Error).message).toBe('storage down');
+      expect(errorEvent.errorMessage).toBe('storage down');
     });
 
     it('callback errors do not break endpoint', async () => {
diff --git a/packages/middleware-hono/src/__tests__/middleware.test.ts b/packages/middleware-hono/src/__tests__/middleware.test.ts
index c259874..3d6d684 100644
--- a/packages/middleware-hono/src/__tests__/middleware.test.ts
+++ b/packages/middleware-hono/src/__tests__/middleware.test.ts
@@ -16,6 +16,9 @@ function createMockStorage(): StorageAdapter & { _store: Map<string, DeviceProfi
       store.delete(token);
     }),
     exists: vi.fn(async (token: string) => store.has(token)),
+    clear: vi.fn(async () => store.clear()),
+    count: vi.fn(async () => store.size),
+    keys: vi.fn(async () => [...store.keys()]),
     _store: store,
   } as StorageAdapter & { _store: Map<string, DeviceProfile> };
 }
@@ -314,6 +317,7 @@ describe('createMiddleware (hono)', () => {
       const errorEvent = event as Extract<DeviceRouterEvent, { type: 'error' }>;
       expect(errorEvent.error).toBeInstanceOf(Error);
       expect((errorEvent.error as Error).message).toBe('storage down');
+      expect(errorEvent.errorMessage).toBe('storage down');
     });
 
     it('callback errors do not break middleware', async () => {
diff --git a/packages/middleware-hono/src/endpoint.ts b/packages/middleware-hono/src/endpoint.ts
index 8149271..5e46bbd 100644
--- a/packages/middleware-hono/src/endpoint.ts
+++ b/packages/middleware-hono/src/endpoint.ts
@@ -2,7 +2,7 @@ import type { Context, Handler } from 'hono';
 import { getCookie, setCookie } from 'hono/cookie';
 import type { StorageAdapter } from '@device-router/storage';
 import type { DeviceProfile, RawSignals, OnEventCallback } from '@device-router/types';
-import { isValidSignals, isBotSignals, emitEvent } from '@device-router/types';
+import { isValidSignals, isBotSignals, emitEvent, extractErrorMessage } from '@device-router/types';
 
 export interface EndpointOptions {
   storage: StorageAdapter;
@@ -28,6 +28,8 @@ export function createProbeEndpoint(options: EndpointOptions): Handler {
   return async (c: Context) => {
     let sessionToken: string | undefined;
     try {
+      const validationStart = performance.now();
+
       let signals: unknown;
       try {
         signals = await c.req.json();
@@ -43,7 +45,8 @@ export function createProbeEndpoint(options: EndpointOptions): Handler {
       sessionToken = existingToken || globalThis.crypto.randomUUID();
 
       if (rejectBots && isBotSignals(signals)) {
-        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals });
+        const durationMs = performance.now() - validationStart;
+        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals, durationMs });
         return c.json({ ok: false, error: 'Bot detected' }, 403);
       }
 
@@ -86,6 +89,7 @@ export function createProbeEndpoint(options: EndpointOptions): Handler {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'endpoint',
         sessionToken,
       });
diff --git a/packages/middleware-hono/src/middleware.ts b/packages/middleware-hono/src/middleware.ts
index ce078bd..a08aa7f 100644
--- a/packages/middleware-hono/src/middleware.ts
+++ b/packages/middleware-hono/src/middleware.ts
@@ -7,6 +7,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  extractErrorMessage,
   validateThresholds,
 } from '@device-router/types';
 import type {
@@ -109,6 +110,7 @@ export function createMiddleware(options: MiddlewareOptions): MiddlewareHandler<
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'middleware',
         sessionToken: getCookie(c, cookieName),
       });
diff --git a/packages/middleware-koa/src/__tests__/endpoint.test.ts b/packages/middleware-koa/src/__tests__/endpoint.test.ts
index fc4b4af..0f0f440 100644
--- a/packages/middleware-koa/src/__tests__/endpoint.test.ts
+++ b/packages/middleware-koa/src/__tests__/endpoint.test.ts
@@ -9,6 +9,9 @@ function createMockStorage(): StorageAdapter {
     set: vi.fn().mockResolvedValue(undefined),
     delete: vi.fn().mockResolvedValue(undefined),
     exists: vi.fn().mockResolvedValue(false),
+    clear: vi.fn().mockResolvedValue(undefined),
+    count: vi.fn().mockResolvedValue(0),
+    keys: vi.fn().mockResolvedValue([]),
   };
 }
 
@@ -231,6 +234,7 @@ describe('createProbeEndpoint (koa)', () => {
       expect(events[0].type).toBe('bot:reject');
       const event = events[0] as Extract<DeviceRouterEvent, { type: 'bot:reject' }>;
       expect(event.signals).toEqual({});
+      expect(typeof event.durationMs).toBe('number');
     });
 
     it('emits error event on storage failure', async () => {
@@ -252,6 +256,7 @@ describe('createProbeEndpoint (koa)', () => {
       expect(event.phase).toBe('endpoint');
       expect(event.error).toBeInstanceOf(Error);
       expect((event.error as Error).message).toBe('Redis down');
+      expect(event.errorMessage).toBe('Redis down');
     });
 
     it('callback errors do not break endpoint', async () => {
diff --git a/packages/middleware-koa/src/__tests__/middleware.test.ts b/packages/middleware-koa/src/__tests__/middleware.test.ts
index 427b34a..18aa45f 100644
--- a/packages/middleware-koa/src/__tests__/middleware.test.ts
+++ b/packages/middleware-koa/src/__tests__/middleware.test.ts
@@ -14,6 +14,9 @@ function createMockStorage(): StorageAdapter & { _store: Map<string, DeviceProfi
       store.delete(token);
     }),
     exists: vi.fn(async (token: string) => store.has(token)),
+    clear: vi.fn(async () => store.clear()),
+    count: vi.fn(async () => store.size),
+    keys: vi.fn(async () => [...store.keys()]),
     _store: store,
   } as StorageAdapter & { _store: Map<string, DeviceProfile> };
 }
@@ -353,6 +356,7 @@ describe('createMiddleware (koa)', () => {
       expect(event.phase).toBe('middleware');
       expect(event.error).toBeInstanceOf(Error);
       expect((event.error as Error).message).toBe('Storage down');
+      expect(event.errorMessage).toBe('Storage down');
     });
 
     it('callback errors do not break middleware', async () => {
diff --git a/packages/middleware-koa/src/endpoint.ts b/packages/middleware-koa/src/endpoint.ts
index e1bbaea..274edf3 100644
--- a/packages/middleware-koa/src/endpoint.ts
+++ b/packages/middleware-koa/src/endpoint.ts
@@ -1,7 +1,7 @@
 import type { Context } from 'koa';
 import type { StorageAdapter } from '@device-router/storage';
 import type { DeviceProfile, RawSignals, OnEventCallback } from '@device-router/types';
-import { isValidSignals, isBotSignals, emitEvent } from '@device-router/types';
+import { isValidSignals, isBotSignals, emitEvent, extractErrorMessage } from '@device-router/types';
 import { randomUUID } from 'node:crypto';
 
 export interface EndpointOptions {
@@ -29,6 +29,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
     let sessionToken: string | undefined;
     try {
       const signals = (ctx.request as unknown as { body: unknown }).body;
+      const validationStart = performance.now();
 
       if (!isValidSignals(signals)) {
         ctx.status = 400;
@@ -40,7 +41,8 @@ export function createProbeEndpoint(options: EndpointOptions) {
       sessionToken = existingToken || randomUUID();
 
       if (rejectBots && isBotSignals(signals)) {
-        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals });
+        const durationMs = performance.now() - validationStart;
+        emitEvent(onEvent, { type: 'bot:reject', sessionToken, signals, durationMs });
         ctx.status = 403;
         ctx.body = { ok: false, error: 'Bot detected' };
         return;
@@ -85,6 +87,7 @@ export function createProbeEndpoint(options: EndpointOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'endpoint',
         sessionToken,
       });
diff --git a/packages/middleware-koa/src/middleware.ts b/packages/middleware-koa/src/middleware.ts
index 3dbef03..66c4719 100644
--- a/packages/middleware-koa/src/middleware.ts
+++ b/packages/middleware-koa/src/middleware.ts
@@ -6,6 +6,7 @@ import {
   classifyFromHeaders,
   resolveFallback,
   emitEvent,
+  extractErrorMessage,
   validateThresholds,
 } from '@device-router/types';
 import type {
@@ -108,6 +109,7 @@ export function createMiddleware(options: MiddlewareOptions) {
       emitEvent(onEvent, {
         type: 'error',
         error: err,
+        errorMessage: extractErrorMessage(err),
         phase: 'middleware',
         sessionToken: ctx.cookies.get(cookieName),
       });
diff --git a/packages/probe/README.md b/packages/probe/README.md
index 3384532..59f790f 100644
--- a/packages/probe/README.md
+++ b/packages/probe/README.md
@@ -65,6 +65,23 @@ await runProbe({
 });
 ```
 
+### Programmatic with retry
+
+```typescript
+import { runProbeWithRetry } from '@device-router/probe';
+
+await runProbeWithRetry({
+  endpoint: '/device-router/probe',
+  retry: {
+    maxRetries: 3, // default: 3
+    baseDelay: 500, // default: 500ms
+    maxDelay: 5000, // default: 5000ms
+  },
+});
+```
+
+Uses exponential backoff with jitter on network failure. Signals are collected once before the retry loop. Does not affect the IIFE bundle size.
+
 ## Signals collected
 
 | Signal                 | API                        | Browser Support     |
@@ -92,6 +109,9 @@ The IIFE bundle is strictly capped at **1024 bytes gzipped**. This is enforced a
 - `collectSignals()` — Collect all synchronous device signals
 - `ProbeSignals` — Type for the collected signal object
 - `ProbeOptions` — Configuration type for `runProbe`
+- `runProbeWithRetry(options?)` — Run the probe with retry on failure
+- `RetryOptions` — Retry configuration type
+- `ProbeWithRetryOptions` — Configuration type for `runProbeWithRetry`
 
 Individual collectors are also exported for selective use:
 
diff --git a/packages/probe/src/__tests__/retry.test.ts b/packages/probe/src/__tests__/retry.test.ts
new file mode 100644
index 0000000..e67fad4
--- /dev/null
+++ b/packages/probe/src/__tests__/retry.test.ts
@@ -0,0 +1,211 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { runProbeWithRetry } from '../retry.js';
+
+describe('runProbeWithRetry', () => {
+  const originalDocument = globalThis.document;
+  const originalNavigator = globalThis.navigator;
+  const originalWindow = globalThis.window;
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    Object.defineProperty(globalThis, 'document', {
+      value: { cookie: '' },
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, 'navigator', {
+      value: {
+        hardwareConcurrency: 4,
+        userAgent: 'Test/1.0',
+      },
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, 'window', {
+      value: {
+        innerWidth: 1024,
+        innerHeight: 768,
+        devicePixelRatio: 2,
+        matchMedia: vi.fn(() => ({ matches: false })),
+      },
+      writable: true,
+      configurable: true,
+    });
+    globalThis.fetch = vi.fn();
+  });
+
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'document', {
+      value: originalDocument,
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, 'navigator', {
+      value: originalNavigator,
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, 'window', {
+      value: originalWindow,
+      writable: true,
+      configurable: true,
+    });
+    globalThis.fetch = originalFetch;
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('succeeds on first attempt without retry', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ sessionToken: 'tok1' }),
+    });
+    globalThis.fetch = mockFetch;
+
+    await runProbeWithRetry();
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch).toHaveBeenCalledWith('/device-router/probe', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: expect.any(String),
+    });
+  });
+
+  it('retries on network failure and succeeds on 2nd attempt', async () => {
+    const mockDoc = { cookie: '' };
+    Object.defineProperty(globalThis, 'document', {
+      value: mockDoc,
+      writable: true,
+      configurable: true,
+    });
+
+    const mockFetch = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('Network error'))
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ sessionToken: 'retry-tok' }),
+      });
+    globalThis.fetch = mockFetch;
+
+    await runProbeWithRetry({ retry: { baseDelay: 10, maxDelay: 100 } });
+
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(mockDoc.cookie).toContain('device-router-session=retry-tok');
+  });
+
+  it('exhausts retries and fails silently', async () => {
+    const mockFetch = vi.fn().mockRejectedValue(new Error('Network error'));
+    globalThis.fetch = mockFetch;
+
+    await expect(
+      runProbeWithRetry({ retry: { maxRetries: 2, baseDelay: 10, maxDelay: 50 } }),
+    ).resolves.toBeUndefined();
+
+    expect(mockFetch).toHaveBeenCalledTimes(3); // initial + 2 retries
+  });
+
+  it('respects maxRetries option', async () => {
+    const mockFetch = vi.fn().mockRejectedValue(new Error('fail'));
+    globalThis.fetch = mockFetch;
+
+    await runProbeWithRetry({ retry: { maxRetries: 1, baseDelay: 10, maxDelay: 50 } });
+
+    expect(mockFetch).toHaveBeenCalledTimes(2); // initial + 1 retry
+  });
+
+  it('backoff delay increases exponentially', async () => {
+    const delays: number[] = [];
+
+    const mockFetch = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('fail'))
+      .mockRejectedValueOnce(new Error('fail'))
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ sessionToken: 'tok' }),
+      });
+    globalThis.fetch = mockFetch;
+
+    // Use real timers to track actual delay values
+    vi.useRealTimers();
+
+    const sleepSpy = vi.spyOn(globalThis, 'setTimeout').mockImplementation(((
+      fn: () => void,
+      ms: number,
+    ) => {
+      delays.push(ms);
+      fn();
+      return 0 as unknown as ReturnType<typeof setTimeout>;
+    }) as typeof setTimeout);
+
+    await runProbeWithRetry({ retry: { baseDelay: 100, maxDelay: 5000 } });
+
+    sleepSpy.mockRestore();
+
+    // First delay: baseDelay * 2^0 + jitter = 100..200
+    // Second delay: baseDelay * 2^1 + jitter = 200..300
+    expect(delays.length).toBe(2);
+    expect(delays[0]).toBeGreaterThanOrEqual(100);
+    expect(delays[0]).toBeLessThan(200);
+    expect(delays[1]).toBeGreaterThanOrEqual(200);
+    expect(delays[1]).toBeLessThan(300);
+    // Second delay should be larger
+    expect(delays[1]).toBeGreaterThan(delays[0]);
+  });
+
+  it('retries on 500 server error', async () => {
+    const mockDoc = { cookie: '' };
+    Object.defineProperty(globalThis, 'document', {
+      value: mockDoc,
+      writable: true,
+      configurable: true,
+    });
+
+    const mockFetch = vi
+      .fn()
+      .mockResolvedValueOnce({ ok: false, status: 500 })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ sessionToken: 'recovered' }),
+      });
+    globalThis.fetch = mockFetch;
+
+    await runProbeWithRetry({ retry: { baseDelay: 10, maxDelay: 100 } });
+
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(mockDoc.cookie).toContain('device-router-session=recovered');
+  });
+
+  it('does not retry on 400 client error', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({ ok: false, status: 400 });
+    globalThis.fetch = mockFetch;
+
+    await runProbeWithRetry({ retry: { maxRetries: 3, baseDelay: 10, maxDelay: 50 } });
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('exhausts retries on persistent 503', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({ ok: false, status: 503 });
+    globalThis.fetch = mockFetch;
+
+    await runProbeWithRetry({ retry: { maxRetries: 2, baseDelay: 10, maxDelay: 50 } });
+
+    expect(mockFetch).toHaveBeenCalledTimes(3); // initial + 2 retries
+  });
+
+  it('skips if session cookie exists', async () => {
+    Object.defineProperty(globalThis, 'document', {
+      value: { cookie: 'device-router-session=existing' },
+      writable: true,
+      configurable: true,
+    });
+
+    await runProbeWithRetry();
+
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/probe/src/_internal.ts b/packages/probe/src/_internal.ts
new file mode 100644
index 0000000..bf4f210
--- /dev/null
+++ b/packages/probe/src/_internal.ts
@@ -0,0 +1,31 @@
+import { setCookie } from './probe.js';
+import type { ProbeSignals } from './signals.js';
+
+export async function collectBattery(signals: ProbeSignals): Promise<void> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const bm = await (navigator as any).getBattery();
+    signals.battery = { level: bm.level, charging: bm.charging };
+  } catch {
+    // API unavailable (Firefox, Safari) — leave undefined
+  }
+}
+
+export function sendProbe(signals: ProbeSignals, endpoint: string): Promise<Response> {
+  return fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(signals),
+  });
+}
+
+export async function handleProbeResponse(
+  response: Response,
+  cookieName: string,
+  cookiePath: string,
+): Promise<void> {
+  const data = (await response.json()) as { sessionToken?: string };
+  if (data.sessionToken) {
+    setCookie(cookieName, data.sessionToken, cookiePath);
+  }
+}
diff --git a/packages/probe/src/index.ts b/packages/probe/src/index.ts
index f3f7391..85c5497 100644
--- a/packages/probe/src/index.ts
+++ b/packages/probe/src/index.ts
@@ -2,3 +2,5 @@ export { collectSignals } from './signals.js';
 export { runProbe } from './probe.js';
 export type { ProbeOptions } from './probe.js';
 export type { ProbeSignals } from './signals.js';
+export { runProbeWithRetry } from './retry.js';
+export type { RetryOptions, ProbeWithRetryOptions } from './retry.js';
diff --git a/packages/probe/src/probe.ts b/packages/probe/src/probe.ts
index b622cbd..4fa8cdb 100644
--- a/packages/probe/src/probe.ts
+++ b/packages/probe/src/probe.ts
@@ -6,12 +6,12 @@ export interface ProbeOptions {
   cookiePath?: string;
 }
 
-function getCookie(name: string): string | null {
+export function getCookie(name: string): string | null {
   const match = document.cookie.match(RegExp('(^|; )' + name + '=([^;]*)'));
   return match ? decodeURIComponent(match[2]) : null;
 }
 
-function setCookie(name: string, value: string, path: string): void {
+export function setCookie(name: string, value: string, path: string): void {
   document.cookie = `${name}=${encodeURIComponent(value)};path=${path};SameSite=Lax`;
 }
 
diff --git a/packages/probe/src/retry.ts b/packages/probe/src/retry.ts
new file mode 100644
index 0000000..764df06
--- /dev/null
+++ b/packages/probe/src/retry.ts
@@ -0,0 +1,51 @@
+import { collectSignals } from './signals.js';
+import { getCookie } from './probe.js';
+import { collectBattery, sendProbe, handleProbeResponse } from './_internal.js';
+import type { ProbeOptions } from './probe.js';
+
+export interface RetryOptions {
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+}
+
+export interface ProbeWithRetryOptions extends ProbeOptions {
+  retry?: RetryOptions;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function runProbeWithRetry(options: ProbeWithRetryOptions = {}): Promise<void> {
+  const {
+    endpoint = '/device-router/probe',
+    cookieName = 'device-router-session',
+    cookiePath = '/',
+    retry = {},
+  } = options;
+
+  const { maxRetries = 3, baseDelay = 500, maxDelay = 5000 } = retry;
+
+  if (getCookie(cookieName)) return;
+
+  const signals = collectSignals();
+  await collectBattery(signals);
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await sendProbe(signals, endpoint);
+      if (response.ok) {
+        await handleProbeResponse(response, cookieName, cookiePath);
+        return;
+      }
+      if (response.status < 500) return; // 4xx — don't retry
+      // 5xx — fall through to backoff
+    } catch {
+      // Network error — fall through to backoff
+    }
+    if (attempt >= maxRetries) return;
+    const delay = Math.min(baseDelay * 2 ** attempt + Math.random() * baseDelay, maxDelay);
+    await sleep(delay);
+  }
+}
diff --git a/packages/storage/README.md b/packages/storage/README.md
index 48d944b..d9f7e21 100644
--- a/packages/storage/README.md
+++ b/packages/storage/README.md
@@ -41,7 +41,9 @@ const storage = new RedisStorageAdapter({
 });
 ```
 
-The `client` option accepts any object with `get`, `set`, `del`, and `exists` methods matching the ioredis interface. This means you can use any Redis-compatible client.
+The `client` option accepts any object with `get`, `set`, `del`, `exists`, and `keys` methods matching the ioredis interface. This means you can use any Redis-compatible client.
+
+The client may also provide an optional `scan(cursor, ...args)` method. When available, `clear()`, `count()`, and `keys()` use SCAN-based iteration instead of the blocking `KEYS` command. This is recommended for production to avoid blocking the Redis event loop on large datasets.
 
 ### Custom adapter
 
@@ -64,6 +66,15 @@ class MyAdapter implements StorageAdapter {
   async exists(sessionToken: string): Promise<boolean> {
     /* ... */
   }
+  async clear(): Promise<void> {
+    /* ... */
+  }
+  async count(): Promise<number> {
+    /* ... */
+  }
+  async keys(): Promise<string[]> {
+    /* ... */
+  }
 }
 ```
 
@@ -77,12 +88,17 @@ class MyAdapter implements StorageAdapter {
 | `set`    | `(sessionToken: string, profile: DeviceProfile, ttl: number) => Promise<void>` | Store with TTL (seconds)  |
 | `delete` | `(sessionToken: string) => Promise<void>`                                      | Remove a profile          |
 | `exists` | `(sessionToken: string) => Promise<boolean>`                                   | Check if a profile exists |
+| `clear`  | `() => Promise<void>`                                                          | Remove all entries        |
+| `count`  | `() => Promise<number>`                                                        | Count stored profiles     |
+| `keys`   | `() => Promise<string[]>`                                                      | List session tokens       |
 
 ### `MemoryStorageAdapter`
 
 Implements `StorageAdapter` plus:
 
 - `clear()` — Remove all entries and cancel timers
+- `count()` — Count stored profiles
+- `keys()` — List session tokens
 
 ### `RedisStorageAdapter`
 
diff --git a/packages/storage/src/__tests__/memory.test.ts b/packages/storage/src/__tests__/memory.test.ts
index 4c88db6..d7897f3 100644
--- a/packages/storage/src/__tests__/memory.test.ts
+++ b/packages/storage/src/__tests__/memory.test.ts
@@ -18,8 +18,8 @@ describe('MemoryStorageAdapter', () => {
     vi.useFakeTimers();
   });
 
-  afterEach(() => {
-    adapter.clear();
+  afterEach(async () => {
+    await adapter.clear();
     vi.useRealTimers();
   });
 
@@ -70,8 +70,49 @@ describe('MemoryStorageAdapter', () => {
   it('clears all entries', async () => {
     await adapter.set('a', makeProfile('a'), 3600);
     await adapter.set('b', makeProfile('b'), 3600);
-    adapter.clear();
+    await adapter.clear();
     expect(await adapter.get('a')).toBeNull();
     expect(await adapter.get('b')).toBeNull();
   });
+
+  describe('count', () => {
+    it('returns zero when empty', async () => {
+      expect(await adapter.count()).toBe(0);
+    });
+
+    it('returns the number of stored entries', async () => {
+      await adapter.set('a', makeProfile('a'), 3600);
+      await adapter.set('b', makeProfile('b'), 3600);
+      expect(await adapter.count()).toBe(2);
+    });
+
+    it('excludes expired entries', async () => {
+      await adapter.set('a', makeProfile('a'), 1);
+      await adapter.set('b', makeProfile('b'), 3600);
+      vi.advanceTimersByTime(1500);
+      expect(await adapter.count()).toBe(1);
+    });
+  });
+
+  describe('keys', () => {
+    it('returns empty array when empty', async () => {
+      expect(await adapter.keys()).toEqual([]);
+    });
+
+    it('returns session token keys', async () => {
+      await adapter.set('tok1', makeProfile('tok1'), 3600);
+      await adapter.set('tok2', makeProfile('tok2'), 3600);
+      const keys = await adapter.keys();
+      expect(keys).toHaveLength(2);
+      expect(keys).toContain('tok1');
+      expect(keys).toContain('tok2');
+    });
+
+    it('excludes expired entries', async () => {
+      await adapter.set('a', makeProfile('a'), 1);
+      await adapter.set('b', makeProfile('b'), 3600);
+      vi.advanceTimersByTime(1500);
+      expect(await adapter.keys()).toEqual(['b']);
+    });
+  });
 });
diff --git a/packages/storage/src/__tests__/redis.test.ts b/packages/storage/src/__tests__/redis.test.ts
index bd40d9b..ae1be8d 100644
--- a/packages/storage/src/__tests__/redis.test.ts
+++ b/packages/storage/src/__tests__/redis.test.ts
@@ -30,12 +30,29 @@ function createMockClient() {
       store.set(key, entry);
       return 'OK';
     }),
-    del: vi.fn(async (key: string) => {
+    del: vi.fn(async (key: string | string[]) => {
+      if (Array.isArray(key)) {
+        let count = 0;
+        for (const k of key) {
+          if (store.delete(k)) count++;
+        }
+        return count;
+      }
       return store.delete(key) ? 1 : 0;
     }),
     exists: vi.fn(async (key: string) => {
       return store.has(key) ? 1 : 0;
     }),
+    keys: vi.fn(async (pattern: string) => {
+      const prefix = pattern.replace('*', '');
+      return [...store.keys()].filter((k) => k.startsWith(prefix));
+    }),
+    scan: vi.fn(async (cursor: number, ..._args: string[]) => {
+      if (cursor !== 0) return ['0', []] as [string, string[]];
+      const prefix = _args[1]?.replace('*', '') ?? '';
+      const matched = [...store.keys()].filter((k) => k.startsWith(prefix));
+      return ['0', matched] as [string, string[]];
+    }),
     _store: store,
   };
 }
@@ -117,4 +134,110 @@ describe('RedisStorageAdapter', () => {
       expect(await adapter.exists('tok1')).toBe(false);
     });
   });
+
+  describe('clear', () => {
+    it('deletes all keys matching the prefix', async () => {
+      await adapter.set('tok1', makeProfile('tok1'), 3600);
+      await adapter.set('tok2', makeProfile('tok2'), 3600);
+
+      await adapter.clear();
+
+      expect(client.scan).toHaveBeenCalled();
+      expect(client.keys).not.toHaveBeenCalled();
+      expect(client.del).toHaveBeenCalled();
+      expect(await adapter.get('tok1')).toBeNull();
+      expect(await adapter.get('tok2')).toBeNull();
+    });
+
+    it('does not call del when no keys match', async () => {
+      client.del.mockClear();
+      await adapter.clear();
+
+      expect(client.scan).toHaveBeenCalled();
+      expect(client.del).not.toHaveBeenCalled();
+    });
+
+    it('does not throw on connection error', async () => {
+      client.scan.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+      await expect(adapter.clear()).resolves.toBeUndefined();
+    });
+  });
+
+  describe('count', () => {
+    it('returns the number of stored entries', async () => {
+      await adapter.set('tok1', makeProfile('tok1'), 3600);
+      await adapter.set('tok2', makeProfile('tok2'), 3600);
+      expect(await adapter.count()).toBe(2);
+    });
+
+    it('returns 0 when empty', async () => {
+      expect(await adapter.count()).toBe(0);
+    });
+
+    it('returns 0 on connection error', async () => {
+      client.keys.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+      expect(await adapter.count()).toBe(0);
+    });
+  });
+
+  describe('keys', () => {
+    it('returns session tokens without prefix', async () => {
+      await adapter.set('tok1', makeProfile('tok1'), 3600);
+      await adapter.set('tok2', makeProfile('tok2'), 3600);
+      const keys = await adapter.keys();
+      expect(keys).toHaveLength(2);
+      expect(keys).toContain('tok1');
+      expect(keys).toContain('tok2');
+    });
+
+    it('returns empty array when empty', async () => {
+      expect(await adapter.keys()).toEqual([]);
+    });
+
+    it('returns empty array on connection error', async () => {
+      client.scan.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+      expect(await adapter.keys()).toEqual([]);
+    });
+  });
+
+  describe('SCAN-based operations', () => {
+    it('uses scan instead of keys when scan is available', async () => {
+      await adapter.set('tok1', makeProfile('tok1'), 3600);
+      client.keys.mockClear();
+
+      await adapter.count();
+
+      expect(client.scan).toHaveBeenCalled();
+      expect(client.keys).not.toHaveBeenCalled();
+    });
+
+    it('handles multi-page scan', async () => {
+      await adapter.set('tok1', makeProfile('tok1'), 3600);
+      await adapter.set('tok2', makeProfile('tok2'), 3600);
+
+      client.scan
+        .mockResolvedValueOnce(['42', ['dr:profile:tok1']])
+        .mockResolvedValueOnce(['0', ['dr:profile:tok2']]);
+
+      const count = await adapter.count();
+      expect(count).toBe(2);
+      expect(client.scan).toHaveBeenCalledTimes(2);
+    });
+
+    it('falls back to keys when scan is absent', async () => {
+      const clientNoScan = {
+        get: client.get,
+        set: client.set,
+        del: client.del,
+        exists: client.exists,
+        keys: client.keys,
+      };
+      const fallbackAdapter = new RedisStorageAdapter({ client: clientNoScan });
+      await fallbackAdapter.set('tok1', makeProfile('tok1'), 3600);
+
+      const count = await fallbackAdapter.count();
+      expect(count).toBe(1);
+      expect(client.keys).toHaveBeenCalledWith('dr:profile:*');
+    });
+  });
 });
diff --git a/packages/storage/src/interface.ts b/packages/storage/src/interface.ts
index 5412d1a..d4cc86a 100644
--- a/packages/storage/src/interface.ts
+++ b/packages/storage/src/interface.ts
@@ -5,4 +5,7 @@ export interface StorageAdapter {
   set(sessionToken: string, profile: DeviceProfile, ttlSeconds: number): Promise<void>;
   delete(sessionToken: string): Promise<void>;
   exists(sessionToken: string): Promise<boolean>;
+  clear(): Promise<void>;
+  count(): Promise<number>;
+  keys(): Promise<string[]>;
 }
diff --git a/packages/storage/src/memory.ts b/packages/storage/src/memory.ts
index 0df1239..076e806 100644
--- a/packages/storage/src/memory.ts
+++ b/packages/storage/src/memory.ts
@@ -53,10 +53,30 @@ export class MemoryStorageAdapter implements StorageAdapter {
     return profile !== null;
   }
 
-  clear(): void {
+  async clear(): Promise<void> {
     for (const entry of this.store.values()) {
       clearTimeout(entry.timer);
     }
     this.store.clear();
   }
+
+  async count(): Promise<number> {
+    this.evictExpired();
+    return this.store.size;
+  }
+
+  async keys(): Promise<string[]> {
+    this.evictExpired();
+    return [...this.store.keys()];
+  }
+
+  private evictExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now >= entry.expiresAt) {
+        clearTimeout(entry.timer);
+        this.store.delete(key);
+      }
+    }
+  }
 }
diff --git a/packages/storage/src/redis.ts b/packages/storage/src/redis.ts
index 06c3399..033e808 100644
--- a/packages/storage/src/redis.ts
+++ b/packages/storage/src/redis.ts
@@ -6,8 +6,12 @@ export interface RedisStorageOptions {
   client: {
     get(key: string): Promise<string | null>;
     set(key: string, value: string, ...args: string[]): Promise<unknown>;
-    del(key: string): Promise<number>;
+    del(key: string | string[]): Promise<number>;
     exists(key: string): Promise<number>;
+    /** Fallback used when `scan` is not available. Blocks the Redis event loop on large datasets. */
+    keys(pattern: string): Promise<string[]>;
+    /** Optional SCAN-based iteration. Preferred over `keys` for production use. */
+    scan?(cursor: number, ...args: string[]): Promise<[string, string[]]>;
   };
 }
 
@@ -24,6 +28,21 @@ export class RedisStorageAdapter implements StorageAdapter {
     return `${this.prefix}${sessionToken}`;
   }
 
+  private async scanKeys(): Promise<string[]> {
+    if (!this.client.scan) {
+      return this.client.keys(`${this.prefix}*`);
+    }
+
+    const allKeys: string[] = [];
+    let cursor = 0;
+    do {
+      const [nextCursor, keys] = await this.client.scan(cursor, 'MATCH', `${this.prefix}*`);
+      cursor = typeof nextCursor === 'string' ? parseInt(nextCursor, 10) : nextCursor;
+      allKeys.push(...keys);
+    } while (cursor !== 0);
+    return allKeys;
+  }
+
   async get(sessionToken: string): Promise<DeviceProfile | null> {
     try {
       const data = await this.client.get(this.key(sessionToken));
@@ -63,4 +82,33 @@ export class RedisStorageAdapter implements StorageAdapter {
       return false;
     }
   }
+
+  async clear(): Promise<void> {
+    try {
+      const keys = await this.scanKeys();
+      if (keys.length > 0) {
+        await this.client.del(keys);
+      }
+    } catch {
+      // Gracefully degrade — keys will expire via TTL
+    }
+  }
+
+  async count(): Promise<number> {
+    try {
+      const keys = await this.scanKeys();
+      return keys.length;
+    } catch {
+      return 0;
+    }
+  }
+
+  async keys(): Promise<string[]> {
+    try {
+      const keys = await this.scanKeys();
+      return keys.map((k) => k.slice(this.prefix.length));
+    } catch {
+      return [];
+    }
+  }
 }
diff --git a/packages/types/README.md b/packages/types/README.md
index 8dc2355..c04e73c 100644
--- a/packages/types/README.md
+++ b/packages/types/README.md
@@ -38,6 +38,9 @@ const hints = deriveHints(tiers, signals);
 //   useImagePlaceholders: false,
 //   preferServerRendering: false,
 //   disable3dEffects: false,
+//   limitVideoQuality: false,
+//   useSystemFonts: false,
+//   disablePrefetch: false,
 // }
 ```
 
@@ -51,6 +54,9 @@ Rendering hints are derived from tiers and transient signals:
 | `useImagePlaceholders`  | Slow connection (2G/3G)                                |
 | `preferServerRendering` | Low-end device                                         |
 | `disable3dEffects`      | No GPU or software renderer                            |
+| `limitVideoQuality`     | Slow connection or low battery                         |
+| `useSystemFonts`        | Low-end device or slow connection                      |
+| `disablePrefetch`       | Slow connection or low battery                         |
 
 The `battery` signal bypasses tier classification — it's transient state, not a capability. When unplugged and below 15% charge, power-sensitive hints are forced on.
 
@@ -119,6 +125,7 @@ if (isValidSignals(requestBody)) {
 - `isBotSignals(signals)` — Detect bot/crawler/headless browser probe submissions
 - `classifyFromHeaders(headers)` — Classify from UA/Client Hints headers
 - `resolveFallback(fallback)` — Resolve a fallback profile preset or custom tiers
+- `extractErrorMessage(err)` — Extract a string message from an unknown error value
 
 ### Constants
 
diff --git a/packages/types/src/__tests__/events.test.ts b/packages/types/src/__tests__/events.test.ts
index b7b456f..750184f 100644
--- a/packages/types/src/__tests__/events.test.ts
+++ b/packages/types/src/__tests__/events.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { emitEvent } from '../events.js';
+import { emitEvent, extractErrorMessage } from '../events.js';
 import type { DeviceRouterEvent } from '../events.js';
 
 const sampleEvent: DeviceRouterEvent = {
@@ -13,6 +13,9 @@ const sampleEvent: DeviceRouterEvent = {
     useImagePlaceholders: false,
     preferServerRendering: false,
     disable3dEffects: false,
+    limitVideoQuality: false,
+    useSystemFonts: false,
+    disablePrefetch: false,
   },
   source: 'probe',
   durationMs: 5,
@@ -65,3 +68,29 @@ describe('emitEvent', () => {
     await new Promise((r) => setTimeout(r, 10));
   });
 });
+
+describe('extractErrorMessage', () => {
+  it('extracts message from Error instance', () => {
+    expect(extractErrorMessage(new Error('test error'))).toBe('test error');
+  });
+
+  it('converts string to message', () => {
+    expect(extractErrorMessage('string error')).toBe('string error');
+  });
+
+  it('extracts message from plain object with message property', () => {
+    expect(extractErrorMessage({ message: 'fail', code: 42 })).toBe('fail');
+  });
+
+  it('converts object without message to string', () => {
+    expect(extractErrorMessage({ code: 42 })).toBe('[object Object]');
+  });
+
+  it('handles null', () => {
+    expect(extractErrorMessage(null)).toBe('null');
+  });
+
+  it('handles undefined', () => {
+    expect(extractErrorMessage(undefined)).toBe('undefined');
+  });
+});
diff --git a/packages/types/src/__tests__/hints.test.ts b/packages/types/src/__tests__/hints.test.ts
index 514774d..d62b1c0 100644
--- a/packages/types/src/__tests__/hints.test.ts
+++ b/packages/types/src/__tests__/hints.test.ts
@@ -11,6 +11,9 @@ describe('deriveHints', () => {
       useImagePlaceholders: true,
       preferServerRendering: true,
       disable3dEffects: true,
+      limitVideoQuality: true,
+      useSystemFonts: true,
+      disablePrefetch: true,
     });
   });
 
@@ -23,6 +26,9 @@ describe('deriveHints', () => {
       useImagePlaceholders: false,
       preferServerRendering: false,
       disable3dEffects: false,
+      limitVideoQuality: false,
+      useSystemFonts: false,
+      disablePrefetch: false,
     });
   });
 
@@ -40,6 +46,9 @@ describe('deriveHints', () => {
     expect(hints.useImagePlaceholders).toBe(true);
     expect(hints.serveMinimalCSS).toBe(false);
     expect(hints.preferServerRendering).toBe(false);
+    expect(hints.limitVideoQuality).toBe(true);
+    expect(hints.useSystemFonts).toBe(true);
+    expect(hints.disablePrefetch).toBe(true);
   });
 
   it('serves minimal CSS for low CPU regardless of connection', () => {
@@ -80,6 +89,10 @@ describe('deriveHints', () => {
     expect(hints.useImagePlaceholders).toBe(false);
     expect(hints.preferServerRendering).toBe(false);
     expect(hints.disable3dEffects).toBe(false);
+    // Battery-constrained hints
+    expect(hints.limitVideoQuality).toBe(true);
+    expect(hints.disablePrefetch).toBe(true);
+    expect(hints.useSystemFonts).toBe(false);
   });
 
   it('does not constrain when low battery but charging', () => {
diff --git a/packages/types/src/events.ts b/packages/types/src/events.ts
index 0e16812..194ef15 100644
--- a/packages/types/src/events.ts
+++ b/packages/types/src/events.ts
@@ -13,22 +13,27 @@ export type DeviceRouterEvent =
       tiers: DeviceTiers;
       hints: RenderingHints;
       source: ProfileSource;
+      /** Time in ms to run classify() + deriveHints() */
       durationMs: number;
     }
   | {
       type: 'profile:store';
       sessionToken: string;
       signals: StoredSignals;
+      /** Time in ms for the storage.set() I/O operation */
       durationMs: number;
     }
   | {
       type: 'bot:reject';
       sessionToken: string;
       signals: RawSignals;
+      /** Time in ms for signal validation + bot detection */
+      durationMs: number;
     }
   | {
       type: 'error';
       error: unknown;
+      errorMessage: string;
       phase: 'middleware' | 'endpoint';
       sessionToken?: string;
     }
@@ -40,6 +45,19 @@ export type DeviceRouterEvent =
 
 export type OnEventCallback = (event: DeviceRouterEvent) => void | Promise<void>;
 
+export function extractErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (
+    typeof err === 'object' &&
+    err !== null &&
+    'message' in err &&
+    typeof (err as Record<string, unknown>).message === 'string'
+  ) {
+    return (err as Record<string, unknown>).message as string;
+  }
+  return String(err);
+}
+
 export function emitEvent(onEvent: OnEventCallback | undefined, event: DeviceRouterEvent): void {
   if (!onEvent) return;
   try {
diff --git a/packages/types/src/hints.ts b/packages/types/src/hints.ts
index cd0b108..cbdf4e7 100644
--- a/packages/types/src/hints.ts
+++ b/packages/types/src/hints.ts
@@ -13,5 +13,8 @@ export function deriveHints(tiers: DeviceTiers, signals?: StoredSignals): Render
     useImagePlaceholders: isSlowConnection,
     preferServerRendering: isLowEnd,
     disable3dEffects: tiers.gpu === 'none' || tiers.gpu === 'low',
+    limitVideoQuality: isSlowConnection || isBatteryConstrained,
+    useSystemFonts: isLowEnd || isSlowConnection,
+    disablePrefetch: isSlowConnection || isBatteryConstrained,
   };
 }
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index f71f5b9..e5b21db 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -43,5 +43,5 @@ export { isValidSignals, validateThresholds } from './validate.js';
 export { isBotSignals } from './bot.js';
 export { classifyFromHeaders, resolveFallback, ACCEPT_CH_VALUE } from './headers.js';
 export type { DeviceRouterEvent, OnEventCallback } from './events.js';
-export { emitEvent } from './events.js';
+export { emitEvent, extractErrorMessage } from './events.js';
 export { createProbeHealthCheck, NO_PROBE_DATA_THRESHOLD } from './health.js';
diff --git a/packages/types/src/profile.ts b/packages/types/src/profile.ts
index 23ab1a6..e6fcf2c 100644
--- a/packages/types/src/profile.ts
+++ b/packages/types/src/profile.ts
@@ -52,6 +52,9 @@ export interface RenderingHints {
   useImagePlaceholders: boolean;
   preferServerRendering: boolean;
   disable3dEffects: boolean;
+  limitVideoQuality: boolean;
+  useSystemFonts: boolean;
+  disablePrefetch: boolean;
 }
 
 export type ProfileSource = 'probe' | 'headers' | 'fallback';

From 4fae90691d927698d0544fa9b7f10c456b648054 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 3 Mar 2026 09:51:11 +0100
Subject: [PATCH 08/12] Bump the prod-deps group with 3 updates (#37)

Bumps the prod-deps group with 3 updates: [hono](https://github.com/honojs/hono), [koa](https://github.com/koajs/koa) and [ioredis](https://github.com/luin/ioredis).


Updates `hono` from 4.12.2 to 4.12.3
- [Release notes](https://github.com/honojs/hono/releases)
- [Commits](https://github.com/honojs/hono/compare/v4.12.2...v4.12.3)

Updates `koa` from 3.1.1 to 3.1.2
- [Release notes](https://github.com/koajs/koa/releases)
- [Changelog](https://github.com/koajs/koa/blob/master/History.md)
- [Commits](https://github.com/koajs/koa/compare/v3.1.1...v3.1.2)

Updates `ioredis` from 5.9.3 to 5.10.0
- [Release notes](https://github.com/luin/ioredis/releases)
- [Changelog](https://github.com/redis/ioredis/blob/main/CHANGELOG.md)
- [Commits](https://github.com/luin/ioredis/compare/v5.9.3...v5.10.0)

---
updated-dependencies:
- dependency-name: hono
  dependency-version: 4.12.3
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: prod-deps
- dependency-name: koa
  dependency-version: 3.1.2
  dependency-type: direct:production
  update-type: version-update:semver-patch
  dependency-group: prod-deps
- dependency-name: ioredis
  dependency-version: 5.10.0
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: prod-deps
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 examples/hono-basic/package.json      |  2 +-
 examples/koa-basic/package.json       |  2 +-
 examples/observability/package.json   |  2 +-
 packages/middleware-hono/package.json |  2 +-
 packages/middleware-koa/package.json  |  2 +-
 packages/storage/package.json         |  4 +-
 pnpm-lock.yaml                        | 71 +++++++++++----------------
 7 files changed, 36 insertions(+), 49 deletions(-)

diff --git a/examples/hono-basic/package.json b/examples/hono-basic/package.json
index d3d8bd7..84276d8 100644
--- a/examples/hono-basic/package.json
+++ b/examples/hono-basic/package.json
@@ -13,7 +13,7 @@
     "@device-router/storage": "workspace:*",
     "@device-router/types": "workspace:*",
     "@hono/node-server": "^1.13.8",
-    "hono": "^4.12.2"
+    "hono": "^4.12.3"
   },
   "devDependencies": {
     "tsx": "^4.0.0"
diff --git a/examples/koa-basic/package.json b/examples/koa-basic/package.json
index 7a2b978..b8d0ef8 100644
--- a/examples/koa-basic/package.json
+++ b/examples/koa-basic/package.json
@@ -12,7 +12,7 @@
     "@device-router/middleware-koa": "workspace:*",
     "@device-router/storage": "workspace:*",
     "@device-router/types": "workspace:*",
-    "koa": "^3.1.1"
+    "koa": "^3.1.2"
   },
   "devDependencies": {
     "@types/koa": "^3.0.1",
diff --git a/examples/observability/package.json b/examples/observability/package.json
index c2aa763..5001c46 100644
--- a/examples/observability/package.json
+++ b/examples/observability/package.json
@@ -14,7 +14,7 @@
     "@device-router/types": "workspace:*",
     "cookie-parser": "^1.4.7",
     "express": "^5.0.1",
-    "ioredis": "^5.6.1",
+    "ioredis": "^5.10.0",
     "prom-client": "^15.1.3"
   },
   "devDependencies": {
diff --git a/packages/middleware-hono/package.json b/packages/middleware-hono/package.json
index 93c32f1..0c09320 100644
--- a/packages/middleware-hono/package.json
+++ b/packages/middleware-hono/package.json
@@ -60,6 +60,6 @@
   },
   "devDependencies": {
     "@device-router/probe": "workspace:*",
-    "hono": "^4.12.2"
+    "hono": "^4.12.3"
   }
 }
diff --git a/packages/middleware-koa/package.json b/packages/middleware-koa/package.json
index 25ecdf8..82787a9 100644
--- a/packages/middleware-koa/package.json
+++ b/packages/middleware-koa/package.json
@@ -61,6 +61,6 @@
   "devDependencies": {
     "@device-router/probe": "workspace:*",
     "@types/koa": "^3.0.1",
-    "koa": "^3.1.1"
+    "koa": "^3.1.2"
   }
 }
diff --git a/packages/storage/package.json b/packages/storage/package.json
index 546565c..781aa76 100644
--- a/packages/storage/package.json
+++ b/packages/storage/package.json
@@ -50,7 +50,7 @@
     "@device-router/types": "workspace:*"
   },
   "peerDependencies": {
-    "ioredis": "^5.0.0"
+    "ioredis": "^5.10.0"
   },
   "peerDependenciesMeta": {
     "ioredis": {
@@ -58,6 +58,6 @@
     }
   },
   "devDependencies": {
-    "ioredis": "^5.0.0"
+    "ioredis": "^5.10.0"
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 517b6e0..8fa5724 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -99,10 +99,10 @@ importers:
         version: link:../../packages/types
       '@hono/node-server':
         specifier: ^1.13.8
-        version: 1.19.9(hono@4.12.2)
+        version: 1.19.9(hono@4.12.3)
       hono:
-        specifier: ^4.12.2
-        version: 4.12.2
+        specifier: ^4.12.3
+        version: 4.12.3
     devDependencies:
       tsx:
         specifier: ^4.0.0
@@ -120,8 +120,8 @@ importers:
         specifier: workspace:*
         version: link:../../packages/types
       koa:
-        specifier: ^3.1.1
-        version: 3.1.1
+        specifier: ^3.1.2
+        version: 3.1.2
     devDependencies:
       '@types/koa':
         specifier: ^3.0.1
@@ -148,8 +148,8 @@ importers:
         specifier: ^5.0.1
         version: 5.2.1
       ioredis:
-        specifier: ^5.6.1
-        version: 5.9.3
+        specifier: ^5.10.0
+        version: 5.10.0
       prom-client:
         specifier: ^15.1.3
         version: 15.1.3
@@ -221,8 +221,8 @@ importers:
         specifier: workspace:*
         version: link:../probe
       hono:
-        specifier: ^4.12.2
-        version: 4.12.2
+        specifier: ^4.12.3
+        version: 4.12.3
 
   packages/middleware-koa:
     dependencies:
@@ -240,8 +240,8 @@ importers:
         specifier: ^3.0.1
         version: 3.0.1
       koa:
-        specifier: ^3.1.1
-        version: 3.1.1
+        specifier: ^3.1.2
+        version: 3.1.2
 
   packages/probe:
     devDependencies:
@@ -256,8 +256,8 @@ importers:
         version: link:../types
     devDependencies:
       ioredis:
-        specifier: ^5.0.0
-        version: 5.9.3
+        specifier: ^5.10.0
+        version: 5.10.0
 
   packages/types: {}
 
@@ -522,8 +522,8 @@ packages:
     resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
     engines: {node: '>=18.18'}
 
-  '@ioredis/commands@1.5.0':
-    resolution: {integrity: sha512-eUgLqrMf8nJkZxT24JvVRrQya1vZkQh8BBeYNwGDqa5I0VUi8ACx7uFvAaLxintokpTenkK6DASvo/bvNbBGow==}
+  '@ioredis/commands@1.5.1':
+    resolution: {integrity: sha512-JH8ZL/ywcJyR9MmJ5BNqZllXNZQqQbnVZOqpPQqE1vHiFgAw4NHbvE0FOduNU8IX9babitBT46571OnPTT0Zcw==}
 
   '@jridgewell/resolve-uri@3.1.2':
     resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
@@ -922,10 +922,6 @@ packages:
     resolution: {integrity: sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA==}
     engines: {node: '>=0.10.0'}
 
-  content-disposition@0.5.4:
-    resolution: {integrity: sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==}
-    engines: {node: '>= 0.6'}
-
   content-disposition@1.0.1:
     resolution: {integrity: sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==}
     engines: {node: '>=18'}
@@ -1207,8 +1203,8 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
-  hono@4.12.2:
-    resolution: {integrity: sha512-gJnaDHXKDayjt8ue0n8Gs0A007yKXj4Xzb8+cNjZeYsSzzwKc0Lr+OZgYwVfB0pHfUs17EPoLvrOsEaJ9mj+Tg==}
+  hono@4.12.3:
+    resolution: {integrity: sha512-SFsVSjp8sj5UumXOOFlkZOG6XS9SJDKw0TbwFeV+AJ8xlST8kxK5Z/5EYa111UY8732lK2S/xB653ceuaoGwpg==}
     engines: {node: '>=16.9.0'}
 
   html-escaper@2.0.2:
@@ -1245,8 +1241,8 @@ packages:
   inherits@2.0.4:
     resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
 
-  ioredis@5.9.3:
-    resolution: {integrity: sha512-VI5tMCdeoxZWU5vjHWsiE/Su76JGhBvWF1MJnV9ZtGltHk9BmD48oDq8Tj8haZ85aceXZMxLNDQZRVo5QKNgXA==}
+  ioredis@5.10.0:
+    resolution: {integrity: sha512-HVBe9OFuqs+Z6n64q09PQvP1/R4Bm+30PAyyD4wIEqssh3v9L21QjCVk4kRLucMBcDokJTcLjsGeVRlq/nH6DA==}
     engines: {node: '>=12.22.0'}
 
   ipaddr.js@1.9.1:
@@ -1311,8 +1307,8 @@ packages:
   koa-compose@4.1.0:
     resolution: {integrity: sha512-8ODW8TrDuMYvXRwra/Kh7/rJo9BtOfPc6qO8eAfC80CnCvSjSl0bkRM24X6/XBBEyj0v1nRUQ1LyOy3dbqOWXw==}
 
-  koa@3.1.1:
-    resolution: {integrity: sha512-KDDuvpfqSK0ZKEO2gCPedNjl5wYpfj+HNiuVRlbhd1A88S3M0ySkdf2V/EJ4NWt5dwh5PXCdcenrKK2IQJAxsg==}
+  koa@3.1.2:
+    resolution: {integrity: sha512-2LOQnFKu3m0VxpE+5sb5+BRTSKrXmNxGgxVRiKwD9s5KQB1zID/FRXhtzeV7RT1L2GVpdEEAfVuclFOMGl1ikA==}
     engines: {node: '>= 18'}
 
   levn@0.4.1:
@@ -1543,9 +1539,6 @@ packages:
     resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
     engines: {node: '>= 18'}
 
-  safe-buffer@5.2.1:
-    resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
-
   safe-regex2@5.0.0:
     resolution: {integrity: sha512-YwJwe5a51WlK7KbOJREPdjNrpViQBI3p4T50lfwPuDhZnE3XGVTlGvi+aolc5+RvxDD6bnUmjVsU9n1eboLUYw==}
 
@@ -1968,9 +1961,9 @@ snapshots:
       '@fastify/forwarded': 3.0.1
       ipaddr.js: 2.3.0
 
-  '@hono/node-server@1.19.9(hono@4.12.2)':
+  '@hono/node-server@1.19.9(hono@4.12.3)':
     dependencies:
-      hono: 4.12.2
+      hono: 4.12.3
 
   '@humanfs/core@0.19.1': {}
 
@@ -1983,7 +1976,7 @@ snapshots:
 
   '@humanwhocodes/retry@0.4.3': {}
 
-  '@ioredis/commands@1.5.0': {}
+  '@ioredis/commands@1.5.1': {}
 
   '@jridgewell/resolve-uri@3.1.2': {}
 
@@ -2398,10 +2391,6 @@ snapshots:
 
   cluster-key-slot@1.1.2: {}
 
-  content-disposition@0.5.4:
-    dependencies:
-      safe-buffer: 5.2.1
-
   content-disposition@1.0.1: {}
 
   content-type@1.0.5: {}
@@ -2739,7 +2728,7 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
-  hono@4.12.2: {}
+  hono@4.12.3: {}
 
   html-escaper@2.0.2: {}
 
@@ -2776,9 +2765,9 @@ snapshots:
 
   inherits@2.0.4: {}
 
-  ioredis@5.9.3:
+  ioredis@5.10.0:
     dependencies:
-      '@ioredis/commands': 1.5.0
+      '@ioredis/commands': 1.5.1
       cluster-key-slot: 1.1.2
       debug: 4.4.3
       denque: 2.1.0
@@ -2841,10 +2830,10 @@ snapshots:
 
   koa-compose@4.1.0: {}
 
-  koa@3.1.1:
+  koa@3.1.2:
     dependencies:
       accepts: 1.3.8
-      content-disposition: 0.5.4
+      content-disposition: 1.0.1
       content-type: 1.0.5
       cookies: 0.9.1
       delegates: 1.0.0
@@ -3092,8 +3081,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  safe-buffer@5.2.1: {}
-
   safe-regex2@5.0.0:
     dependencies:
       ret: 0.5.0

From 466f8596b352a54d7d61840189afb56b0fdd49c7 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 3 Mar 2026 09:56:28 +0100
Subject: [PATCH 09/12] Bump @types/node from 25.3.0 to 25.3.3 in the dev-deps
 group (#36)

Bumps the dev-deps group with 1 update: [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node).


Updates `@types/node` from 25.3.0 to 25.3.3
- [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases)
- [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node)

---
updated-dependencies:
- dependency-name: "@types/node"
  dependency-version: 25.3.3
  dependency-type: direct:development
  update-type: version-update:semver-patch
  dependency-group: dev-deps
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 package.json   |  2 +-
 pnpm-lock.yaml | 50 +++++++++++++++++++++++++-------------------------
 2 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/package.json b/package.json
index b477305..ef7c71d 100644
--- a/package.json
+++ b/package.json
@@ -37,7 +37,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.3",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.2",
     "prettier": "^3.8.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8fa5724..70bd13e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -15,11 +15,11 @@ importers:
         specifier: ^10.0.1
         version: 10.0.1(eslint@10.0.2)
       '@types/node':
-        specifier: ^25.3.0
-        version: 25.3.0
+        specifier: ^25.3.3
+        version: 25.3.3
       '@vitest/coverage-v8':
         specifier: ^4.0.18
-        version: 4.0.18(vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.0)(tsx@4.21.0))
+        version: 4.0.18(vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.3)(tsx@4.21.0))
       eslint:
         specifier: ^10.0.2
         version: 10.0.2
@@ -34,7 +34,7 @@ importers:
         version: 8.56.1(eslint@10.0.2)(typescript@5.9.3)
       vitest:
         specifier: ^4.0.18
-        version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.0)(tsx@4.21.0)
+        version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.3)(tsx@4.21.0)
 
   examples/express-basic:
     dependencies:
@@ -726,8 +726,8 @@ packages:
   '@types/koa@3.0.1':
     resolution: {integrity: sha512-VkB6WJUQSe0zBpR+Q7/YIUESGp5wPHcaXr0xueU5W0EOUWtlSbblsl+Kl31lyRQ63nIILh0e/7gXjQ09JXJIHw==}
 
-  '@types/node@25.3.0':
-    resolution: {integrity: sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A==}
+  '@types/node@25.3.3':
+    resolution: {integrity: sha512-DpzbrH7wIcBaJibpKo9nnSQL0MTRdnWttGyE5haGwK86xgMOkFLp7vEyfQPGLOJh5wNYiJ3V9PmUMDhV9u8kkQ==}
 
   '@types/qs@6.14.0':
     resolution: {integrity: sha512-eOunJqu0K1923aExK6y8p6fsihYEn/BYuQ4g0CxAAgFc4b/ZLN4CrsRZ55srTdqoiLzU2B2evC+apEIxprEzkQ==}
@@ -2070,12 +2070,12 @@ snapshots:
 
   '@types/accepts@1.3.7':
     dependencies:
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
 
   '@types/body-parser@1.19.6':
     dependencies:
       '@types/connect': 3.4.38
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
 
   '@types/chai@5.2.3':
     dependencies:
@@ -2084,7 +2084,7 @@ snapshots:
 
   '@types/connect@3.4.38':
     dependencies:
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
 
   '@types/content-disposition@0.5.9': {}
 
@@ -2097,7 +2097,7 @@ snapshots:
       '@types/connect': 3.4.38
       '@types/express': 5.0.6
       '@types/keygrip': 1.0.6
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
 
   '@types/deep-eql@4.0.2': {}
 
@@ -2107,7 +2107,7 @@ snapshots:
 
   '@types/express-serve-static-core@5.1.1':
     dependencies:
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
       '@types/qs': 6.14.0
       '@types/range-parser': 1.2.7
       '@types/send': 1.2.1
@@ -2139,9 +2139,9 @@ snapshots:
       '@types/http-errors': 2.0.5
       '@types/keygrip': 1.0.6
       '@types/koa-compose': 3.2.9
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
 
-  '@types/node@25.3.0':
+  '@types/node@25.3.3':
     dependencies:
       undici-types: 7.18.2
 
@@ -2151,12 +2151,12 @@ snapshots:
 
   '@types/send@1.2.1':
     dependencies:
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
 
   '@types/serve-static@2.2.0':
     dependencies:
       '@types/http-errors': 2.0.5
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
 
   '@typescript-eslint/eslint-plugin@8.56.1(@typescript-eslint/parser@8.56.1(eslint@10.0.2)(typescript@5.9.3))(eslint@10.0.2)(typescript@5.9.3)':
     dependencies:
@@ -2249,7 +2249,7 @@ snapshots:
       '@typescript-eslint/types': 8.56.1
       eslint-visitor-keys: 5.0.1
 
-  '@vitest/coverage-v8@4.0.18(vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.0)(tsx@4.21.0))':
+  '@vitest/coverage-v8@4.0.18(vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.3)(tsx@4.21.0))':
     dependencies:
       '@bcoe/v8-coverage': 1.0.2
       '@vitest/utils': 4.0.18
@@ -2261,7 +2261,7 @@ snapshots:
       obug: 2.1.1
       std-env: 3.10.0
       tinyrainbow: 3.0.3
-      vitest: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.0)(tsx@4.21.0)
+      vitest: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.3)(tsx@4.21.0)
 
   '@vitest/expect@4.0.18':
     dependencies:
@@ -2272,13 +2272,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.0.3
 
-  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@25.3.0)(tsx@4.21.0))':
+  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@25.3.3)(tsx@4.21.0))':
     dependencies:
       '@vitest/spy': 4.0.18
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.1(@types/node@25.3.0)(tsx@4.21.0)
+      vite: 7.3.1(@types/node@25.3.3)(tsx@4.21.0)
 
   '@vitest/pretty-format@4.0.18':
     dependencies:
@@ -3249,7 +3249,7 @@ snapshots:
 
   vary@1.1.2: {}
 
-  vite@7.3.1(@types/node@25.3.0)(tsx@4.21.0):
+  vite@7.3.1(@types/node@25.3.3)(tsx@4.21.0):
     dependencies:
       esbuild: 0.27.3
       fdir: 6.5.0(picomatch@4.0.3)
@@ -3258,14 +3258,14 @@ snapshots:
       rollup: 4.59.0
       tinyglobby: 0.2.15
     optionalDependencies:
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
       fsevents: 2.3.3
       tsx: 4.21.0
 
-  vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.0)(tsx@4.21.0):
+  vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@25.3.3)(tsx@4.21.0):
     dependencies:
       '@vitest/expect': 4.0.18
-      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@25.3.0)(tsx@4.21.0))
+      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@25.3.3)(tsx@4.21.0))
       '@vitest/pretty-format': 4.0.18
       '@vitest/runner': 4.0.18
       '@vitest/snapshot': 4.0.18
@@ -3282,11 +3282,11 @@ snapshots:
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
       tinyrainbow: 3.0.3
-      vite: 7.3.1(@types/node@25.3.0)(tsx@4.21.0)
+      vite: 7.3.1(@types/node@25.3.3)(tsx@4.21.0)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@opentelemetry/api': 1.9.0
-      '@types/node': 25.3.0
+      '@types/node': 25.3.3
     transitivePeerDependencies:
       - jiti
       - less

From db86bc9c8c0905c8bfd7800d02a13e1854cfdd7b Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Tue, 3 Mar 2026 17:58:25 +0100
Subject: [PATCH 10/12] Add CI jobs for package-lint + e2e, widen koa peer dep,
 remove PRD doc

- Add publint + attw CI job to catch packaging issues
- Add e2e smoke test CI job with launch helper
- Widen middleware-koa peer dep to koa ^2.0.0 || ^3.0.0
- Remove obsolete DeviceRouter_PRD.md
---
 .github/workflows/ci.yml             |  39 +++
 docs/DeviceRouter_PRD.md             | 262 ----------------
 e2e/.gitignore                       |   3 +
 e2e/run.sh                           |  45 +++
 e2e/smoke.mjs                        | 379 +++++++++++++++++++++++
 launch.py                            | 179 +++++++++++
 package.json                         |   5 +
 packages/middleware-koa/package.json |   2 +-
 pnpm-lock.yaml                       | 442 +++++++++++++++++++++++++++
 9 files changed, 1093 insertions(+), 263 deletions(-)
 delete mode 100644 docs/DeviceRouter_PRD.md
 create mode 100644 e2e/.gitignore
 create mode 100755 e2e/run.sh
 create mode 100644 e2e/smoke.mjs
 create mode 100755 launch.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 07b151f..3e4faed 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -69,3 +69,42 @@ jobs:
           size=$(stat -c%s packages/probe/dist/device-router-probe.min.js.gz 2>/dev/null || stat -f%z packages/probe/dist/device-router-probe.min.js.gz)
           echo "Probe gzipped size: ${size} bytes"
           [ "$size" -le 1024 ] || (echo "Probe exceeds 1 KB limit" && exit 1)
+
+  package-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+
+      - name: publint
+        run: pnpm lint:publint
+
+      - name: attw
+        run: pnpm lint:attw
+
+  e2e:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm test:e2e
diff --git a/docs/DeviceRouter_PRD.md b/docs/DeviceRouter_PRD.md
deleted file mode 100644
index 382c7c9..0000000
--- a/docs/DeviceRouter_PRD.md
+++ /dev/null
@@ -1,262 +0,0 @@
-# DeviceRouter
-
-**The server does the thinking. The client does the displaying.**
-
-_Product Requirements Document · v1.1 · Open Source (MIT)_
-
-|         |                                               |
-| ------- | --------------------------------------------- |
-| Status  | Draft                                         |
-| Version | 1.1                                           |
-| License | MIT — fully open source                       |
-| Target  | Framework-agnostic (Node, Python, Go, PHP...) |
-| Author  | Community — contributions welcome             |
-
----
-
-## 1. Problem Statement
-
-> The median webpage ships 558 KB of JavaScript. 44% of it is never executed. A mid-range Android parses JavaScript 25× slower than a development machine. React sites generate 431% more main-thread time on mobile than desktop. This is not an engineering trade-off. It is contempt through negligence.
-
-The root cause is a flawed architectural assumption: that every device should receive the same response, and that the client should sort out what it can handle. This assumption was never stated explicitly — it simply became the default as SPAs and JavaScript-heavy frameworks dominated the industry.
-
-The consequences are real and measurable:
-
-- Heavy JS triggers sustained CPU load, which triggers thermal throttling, which slows the chip further — a feedback loop with no exit. Result: +146% frame defects on mid-range mobile devices. _(CatchJS 2024)_
-- Per byte delivered, nothing drains a battery like JavaScript. Images and video route through dedicated hardware decoders. JavaScript demands the main CPU continuously: parsing, compiling, executing, garbage-collecting.
-- A 500 KB bundle takes ~200 ms to parse on a MacBook Pro. On a throttled mid-range Android: ~5 seconds. The developer never sees this. The user lives with it. _(V8 Blog)_
-- "Mobile First" in practice means: same application, smaller viewport. Same bundle. Same framework overhead. Shipped to a device with a fraction of the compute and a battery the size of a biscuit.
-
-The scale of the problem becomes concrete when you look at the products everyone uses daily. The following are uncompressed JavaScript payload sizes, measured by Nikita Tonsky in 2024:
-
-| Product  | Uncompressed JS Payload |
-| -------- | ----------------------- |
-| Slack    | 55 MB                   |
-| LinkedIn | 31 MB                   |
-| Gmail    | 20 MB                   |
-
-A chat message is 100 bytes. The Slack client weighs 550,000 times more. This is the industry norm, not the exception.
-
-The counter-proof already exists. HTMA (HTML Augmented — [htma.run](https://htma.run)) demonstrates that a fully reactive page with direct DOM mutation, no virtual DOM, no hydration, and no build step can be delivered in a single file of 8.8 KB gzipped — with a state-and-render round-trip of ~19 ms. The browser was always capable. The weight was never necessary.
-
-DeviceRouter exists to fix the architectural assumption at the layer where it does the most damage: the server response pipeline.
-
----
-
-## 2. Vision
-
-DeviceRouter is an open-source framework-agnostic toolkit that inverts the current model. Instead of shipping everything and letting the client sort it out, DeviceRouter detects device capabilities once — server-side — and builds a response tailored precisely to what that device needs.
-
-**The server does the thinking. The client does the displaying.**
-
-This is not responsive design. Responsive design changes layout via CSS breakpoints — the same bundle still lands on every device. DeviceRouter changes what is sent at the response-building level: different asset bundles, different component complexity, different CSS scope, all determined before the first byte of HTML is written.
-
-> DeviceRouter is free, open source (MIT), and maintained by the community. It will never have a paid tier. It exists because the web deserves better, not because it is a business opportunity.
-
----
-
-## 3. Goals & Non-Goals
-
-### Goals
-
-- Provide a minimal, droppable capability probe (< 1 KB gzipped) that any web page can include.
-- Provide server-side middleware adapters for major frameworks (Express, FastAPI, Laravel, Rails, Go net/http...) that read device profiles and expose capability context to the rendering layer.
-- Provide a dashboard (self-hostable) showing real-world device distribution across a site's user base, with bundle cost breakdowns per device class.
-- Provide a static analysis CLI that audits a JavaScript bundle and identifies code paths unreachable on mobile device profiles.
-- Be genuinely framework-agnostic: the core specification and probe are language-independent; official adapters exist for common ecosystems; community adapters can be built against a documented interface.
-- Be zero-dependency in the probe itself. The probe must not require a build step, a CDN, or a runtime framework.
-
-### Non-Goals
-
-- DeviceRouter is not a JavaScript framework and does not replace React, Vue, or any frontend library.
-- DeviceRouter is not a CDN, edge network, or hosting platform.
-- DeviceRouter does not make decisions about your content — it provides capability context; what you do with it is your choice.
-- DeviceRouter does not enforce any particular rendering architecture. It is compatible with SSR, SSG, edge rendering, and traditional server-side templates.
-- DeviceRouter will never collect user data centrally. All device profiles are stored in your own infrastructure.
-
----
-
-## 4. User Stories
-
-### Developer — Integration
-
-- As a backend developer, I want to drop a single middleware into my existing Express/FastAPI/Rails app and immediately have access to a device capability object in my request context, so that I can make rendering decisions without rewriting my architecture.
-- As a frontend developer, I want the capability probe to be a single script tag I can add to any HTML page, so that device profiling begins without a build step or framework dependency.
-- As a developer deploying to the edge, I want the middleware to work as a standalone function with no framework coupling, so that I can use it in Cloudflare Workers or similar environments.
-
-### Engineering Lead — Visibility
-
-- As an engineering lead, I want to open a dashboard and see what devices my actual users are running — CPU tier, memory class, connection type — so that I can make informed decisions about what to invest in optimising.
-- As an engineering lead, I want to see a breakdown of my JavaScript bundle cost expressed in estimated parse time per device class, so that the cost is expressed in terms my team can act on.
-- As an engineering lead, I want to run a CLI audit on our bundle before a release and get a report of code paths that are unreachable on mobile device profiles, so that we can catch regressions before they ship.
-
-### Contributor — Open Source
-
-- As a contributor, I want a clearly documented middleware interface specification so that I can build an adapter for any language or framework without waiting for an official one.
-- As a contributor, I want a test harness that lets me validate my adapter against the DeviceRouter specification, so that I can be confident in correctness before submitting.
-
----
-
-## 5. Architecture Overview
-
-DeviceRouter is composed of four independent modules that can be used separately or together.
-
-### Module 1 — Capability Probe (Client)
-
-A single JavaScript file, no dependencies, no build step. Included via a standard script tag. Collects a minimal set of device signals on first page load and sends them to a configurable endpoint. Subsequent requests include a session token; the server reads the stored profile without re-probing.
-
-**Signals collected:**
-
-- Hardware concurrency (CPU core count)
-- Device memory (`navigator.deviceMemory`)
-- Connection type and effective bandwidth (NetworkInformation API)
-- User agent string (for OS and device class inference)
-- Viewport dimensions and pixel density
-- Preference signals: `prefers-reduced-motion`, `prefers-color-scheme`
-
-**What is explicitly NOT collected:** IP address, precise location, any identifier that persists across sessions without consent. The probe is privacy-by-design.
-
-**Target size:** < 1 KB gzipped. Stretch goal: < 500 bytes.
-
-### Module 2 — Server Middleware
-
-Language-specific adapters that sit in the request pipeline. On each incoming request, the middleware checks for a session token, retrieves the stored device profile, normalises it into a standard capability object, and attaches it to the request context.
-
-The capability object exposes three abstraction levels:
-
-- **Raw signals:** the actual values collected by the probe (e.g. `hardwareConcurrency: 4`).
-- **Inferred tiers:** normalised classifications (`cpu: 'low' | 'mid' | 'high'`, `connection: '2g' | '3g' | '4g' | 'high'`).
-- **Rendering hints:** opinionated suggestions (`deferHeavyComponents: true`, `serveMinimalCSS: true`) derived from the tier data.
-
-**Official adapters for v1:** Node.js / Express, Node.js / Fastify, Python / FastAPI, Python / Django, Go / net/http.
-
-Community adapter specification published at launch. Any language or framework can implement it.
-
-### Module 3 — Analytics Dashboard
-
-A self-hostable web application (Docker image provided). Reads from your DeviceRouter storage backend (Redis or PostgreSQL) and visualises device distribution, connection class breakdown, and bundle cost estimates.
-
-**Key views:**
-
-- Device class heatmap: what percentage of your users fall into each CPU/memory/connection tier.
-- Bundle cost per tier: your current JS bundle size expressed as estimated parse time across device classes.
-- Trend over time: are your users' devices getting faster or slower relative to your bundle growth?
-- Geography overlay: device class distribution by country or region.
-
-The dashboard has no external dependencies. It does not phone home. All data stays in your infrastructure.
-
-### Module 4 — Static Analysis CLI
-
-A command-line tool that takes a JavaScript bundle (or a source directory with a bundler config) and produces a capability audit report. Dead code detection is genuinely hard; this module does not pretend otherwise. The approach is heuristic static analysis: the CLI builds a call graph from the bundle, maps browser API usage to device capability requirements, and flags code paths that depend on capabilities outside the target device tier. It will produce false negatives on heavily minified or dynamically-evaluated code. This is documented explicitly; the tool is a guide, not a guarantee.
-
-**Capabilities:**
-
-- **Dead code detection:** identifies code paths statically unreachable on a given device capability profile, using call graph analysis. Accuracy improves with source maps.
-- **Bundle cost report:** parse time estimates per device class, derived from V8 benchmark data extrapolated to CPU tier classifications.
-- **Regression detection:** CI mode exits non-zero if bundle cost for a given device tier exceeds a configurable threshold.
-- **Diff mode:** compare two bundles (e.g. before/after a dependency update) and show cost delta per device tier.
-- **Known limitation:** dynamically evaluated code (`eval`, `Function` constructor, dynamic import with variable paths) cannot be statically analysed. The CLI warns on detection of these patterns.
-
----
-
-## 6. What DeviceRouter Is Not
-
-The most common misreading of DeviceRouter will be: "isn't this just User-Agent sniffing?" It deserves a direct answer, not a footnote.
-
-### Not User-Agent sniffing
-
-User-Agent sniffing infers device capabilities from a browser string. It is unreliable (UA strings are easily spoofed and increasingly frozen by browsers), unmaintainable (device databases require constant updates), and coarse (the same UA string covers devices with wildly different real-world performance).
-
-DeviceRouter measures actual device signals at runtime: hardware concurrency, device memory, network information, and pixel density. These are real values from the device itself. A UA string tells you what a browser claims to be. DeviceRouter tells you what the device can actually do.
-
-### Not a JavaScript framework
-
-DeviceRouter does not replace React, Vue, Svelte, or any frontend library. It does not touch the client rendering layer. It operates entirely in the server request pipeline and surfaces capability context to whatever rendering system you already use.
-
-### Not responsive design
-
-Responsive design changes visual layout via CSS breakpoints. The same HTML, the same JavaScript bundle, and the same component tree land on every device. DeviceRouter changes what is sent before the response is built. A low-tier device receives a structurally different response — fewer components, lighter CSS, deferred assets — not a rearranged version of the same one.
-
-### Not a fingerprinting tool
-
-DeviceRouter does not create persistent cross-session device identifiers. Profiles are scoped to a session token with a configurable TTL (default 24 hours). The probe collects no PII. It is designed to be operated within the bounds of GDPR without requiring explicit consent for the probe itself — see the Privacy section of Technical Requirements for the legal basis analysis.
-
-### Not a hosted service
-
-DeviceRouter is infrastructure you run. There is no cloud component, no data sent to a third party, no dependency on any external service. The dashboard is self-hostable. The storage backend is yours. If the project ceases to be maintained, every deployment already in production continues to function unchanged.
-
----
-
-## 7. Technical Requirements
-
-| Requirement        | Detail                                                                                                                                                                                                                                                                                           |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Probe size         | < 1 KB gzipped. Must parse and execute in < 5 ms on a low-tier Android.                                                                                                                                                                                                                          |
-| Session storage    | Server-side only. Client holds only an opaque session token (no PII in client storage).                                                                                                                                                                                                          |
-| Storage backends   | Redis (default), PostgreSQL, in-memory (for testing). Interface is pluggable.                                                                                                                                                                                                                    |
-| Profile TTL        | Configurable. Default: 24 hours. Profiles expire and are re-collected on next visit.                                                                                                                                                                                                             |
-| Middleware latency | Profile lookup must add < 1 ms to request processing time (Redis p99).                                                                                                                                                                                                                           |
-| Framework coupling | Zero. Core specification is a documented JSON contract. Adapters are thin wrappers.                                                                                                                                                                                                              |
-| Privacy / GDPR     | Signals collected are technical characteristics, not personal data under GDPR Art. 4(1). Lawful basis: legitimate interest (Art. 6(1)(f)). No consent banner required for the probe alone. Deployments combining DeviceRouter profiles with authenticated user data must conduct their own DPIA. |
-| Profile schema     | Published as a versioned JSON Schema. All adapters must read and write to this schema. Schema version is included in every stored profile. Breaking changes require a major version bump and a documented migration path.                                                                        |
-| License            | MIT. No CLA required for contributions.                                                                                                                                                                                                                                                          |
-| Test coverage      | All modules require > 80% coverage. Middleware specification includes a conformance test suite.                                                                                                                                                                                                  |
-| Documentation      | Every public API documented. Getting-started guide must achieve integration in < 15 minutes.                                                                                                                                                                                                     |
-
----
-
-## 8. Sources
-
-| Claim                                      | Source                                                                                                                 |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| 558 KB median JS, 44% never executed       | HTTP Archive 2024 — [httparchive.org/reports/state-of-javascript](https://httparchive.org/reports/state-of-javascript) |
-| 25× slower JS parsing on mobile            | V8 Blog — [v8.dev/blog/cost-of-javascript-2019](https://v8.dev/blog/cost-of-javascript-2019)                           |
-| 431% more main-thread time on React mobile | CatchJS 2024 — [catchjs.com/Blog/PerformanceInTheWild](https://catchjs.com/Blog/PerformanceInTheWild)                  |
-| Slack 55 MB / LinkedIn 31 MB / Gmail 20 MB | Tonsky 2024 — [tonsky.me/blog/js-bloat/](https://tonsky.me/blog/js-bloat/)                                             |
-| HTMA: 8.8 KB gzipped, ~19 ms round-trip    | [htma.run](https://htma.run) — [gitlab.com/min2max/htma](https://gitlab.com/min2max/htma)                              |
-
----
-
-## 9. Release Milestones
-
-| Milestone              | Scope                                                                           | Target    |
-| ---------------------- | ------------------------------------------------------------------------------- | --------- |
-| v0.1 — Probe Alpha     | Capability probe + Express middleware + Redis storage. No dashboard.            | Month 1–2 |
-| v0.2 — Adapters        | FastAPI, Django, Go adapters. Conformance test suite published.                 | Month 2–3 |
-| v0.3 — Dashboard Alpha | Self-hostable dashboard with device distribution and bundle cost views.         | Month 3–4 |
-| v0.4 — CLI Alpha       | Static analysis CLI with dead code detection and bundle cost report.            | Month 4–5 |
-| v1.0 — Stable          | All modules stable. Full documentation. Docker images. Community adapter guide. | Month 6   |
-
----
-
-## 10. Success Metrics
-
-DeviceRouter is not a business. There is no revenue metric. Success is measured by impact and adoption.
-
-- GitHub stars are a vanity metric. The real signal is issues filed, PRs submitted, and community adapters built.
-- A successful v1 is one where a developer can go from zero to a working capability-aware rendering layer in under 15 minutes, using only the documentation.
-- A successful project is one where developers report measurably reduced JS parse time on low-tier devices after integrating DeviceRouter — and where those numbers are shared publicly.
-- A successful community is one where the core team is not the bottleneck: community adapters exist for ecosystems the core team never touched.
-- Long-term: DeviceRouter patterns influence how mainstream frameworks think about server-side capability detection — even if they never adopt DeviceRouter directly. The idea spreading matters more than the project being the one that spreads it.
-
----
-
-## 11. Contributing
-
-DeviceRouter is built in the open from day one. There is no private roadmap, no internal Slack, no decisions made behind closed doors. Everything happens on GitHub.
-
-### How to Contribute
-
-- Build an adapter for your language or framework. The specification is the contract; everything else is up to you.
-- File issues for bugs, missing device signals, or documentation gaps.
-- Improve the probe. If you can get it smaller or faster without losing signal quality, that is the single most impactful contribution possible.
-- Test on real devices. Run the probe on the oldest Android you can find. File what breaks.
-- Write about it. A case study showing before/after parse times on a real site is worth more than any marketing.
-
-### Governance
-
-DeviceRouter uses a simple governance model: decisions are made by maintainers through public discussion on GitHub. There are no hidden stakeholders. The project will never be acquired or commercialised without an explicit community vote. If it ever is, the MIT license ensures the community can fork it freely.
-
----
-
-> The browser was always capable. We just buried it under abstractions built for developer convenience rather than user experience. DeviceRouter is an attempt to dig it back out — one request pipeline at a time.
diff --git a/e2e/.gitignore b/e2e/.gitignore
new file mode 100644
index 0000000..c3ed9c2
--- /dev/null
+++ b/e2e/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+package-lock.json
+*.tgz
diff --git a/e2e/run.sh b/e2e/run.sh
new file mode 100755
index 0000000..019c4d6
--- /dev/null
+++ b/e2e/run.sh
@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+WORK_DIR=$(mktemp -d)
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+echo "=== Packing all packages ==="
+PACKAGES=(types probe storage middleware-express middleware-fastify middleware-hono middleware-koa)
+for pkg in "${PACKAGES[@]}"; do
+  pnpm --filter "@device-router/$pkg" pack --pack-destination "$WORK_DIR" > /dev/null 2>&1
+  echo "  packed @device-router/$pkg"
+done
+
+echo "=== Setting up consumer project ==="
+cat > "$WORK_DIR/package.json" << 'EOF'
+{
+  "name": "device-router-e2e",
+  "private": true,
+  "type": "module"
+}
+EOF
+
+cd "$WORK_DIR"
+
+# Install all tarballs + peer deps needed for the express middleware test
+npm install --no-audit --no-fund \
+  ./device-router-types-*.tgz \
+  ./device-router-probe-*.tgz \
+  ./device-router-storage-*.tgz \
+  ./device-router-middleware-express-*.tgz \
+  ./device-router-middleware-fastify-*.tgz \
+  ./device-router-middleware-hono-*.tgz \
+  ./device-router-middleware-koa-*.tgz \
+  express@5 cookie-parser@1 \
+  fastify@5 @fastify/cookie@11 \
+  hono@4 \
+  koa@3 2>/dev/null
+
+echo "=== Running smoke test ==="
+cp "$SCRIPT_DIR/smoke.mjs" "$WORK_DIR/smoke.mjs"
+node smoke.mjs
+
+echo "=== All e2e tests passed ==="
diff --git a/e2e/smoke.mjs b/e2e/smoke.mjs
new file mode 100644
index 0000000..b90645c
--- /dev/null
+++ b/e2e/smoke.mjs
@@ -0,0 +1,379 @@
+/**
+ * E2E smoke test for all @device-router/* packages.
+ *
+ * Installs packages from local tarballs (exactly what npm publish ships)
+ * and exercises every public export as a real consumer would.
+ *
+ * Catches: broken exports maps, missing dist files, ESM resolution failures,
+ * cross-package dependency issues, and runtime import errors.
+ */
+
+// ---------------------------------------------------------------------------
+// Imports — every public export across all packages
+// ---------------------------------------------------------------------------
+
+// @device-router/types
+import {
+  classify,
+  classifyCpu,
+  classifyMemory,
+  classifyConnection,
+  classifyGpu,
+  deriveHints,
+  isValidSignals,
+  validateThresholds,
+  isBotSignals,
+  classifyFromHeaders,
+  resolveFallback,
+  emitEvent,
+  extractErrorMessage,
+  createProbeHealthCheck,
+  ACCEPT_CH_VALUE,
+  CONSERVATIVE_TIERS,
+  OPTIMISTIC_TIERS,
+  DEFAULT_CPU_THRESHOLDS,
+  DEFAULT_MEMORY_THRESHOLDS,
+  DEFAULT_CONNECTION_THRESHOLDS,
+  DEFAULT_GPU_THRESHOLDS,
+  NO_PROBE_DATA_THRESHOLD,
+} from '@device-router/types';
+
+// @device-router/probe
+import { collectSignals, runProbe, runProbeWithRetry } from '@device-router/probe';
+
+// @device-router/storage
+import { MemoryStorageAdapter, RedisStorageAdapter } from '@device-router/storage';
+
+// @device-router/middleware-express
+import {
+  createDeviceRouter as createExpressRouter,
+  loadProbeScript as loadExpressProbe,
+  createMiddleware as createExpressMw,
+  createProbeEndpoint as createExpressEndpoint,
+  createInjectionMiddleware as createExpressInject,
+} from '@device-router/middleware-express';
+
+// @device-router/middleware-fastify
+import {
+  createDeviceRouter as createFastifyRouter,
+  loadProbeScript as loadFastifyProbe,
+  createMiddleware as createFastifyMw,
+  createProbeEndpoint as createFastifyEndpoint,
+  createInjectionMiddleware as createFastifyInject,
+} from '@device-router/middleware-fastify';
+
+// @device-router/middleware-hono
+import {
+  createDeviceRouter as createHonoRouter,
+  loadProbeScript as loadHonoProbe,
+  createMiddleware as createHonoMw,
+  createProbeEndpoint as createHonoEndpoint,
+  createInjectionMiddleware as createHonoInject,
+} from '@device-router/middleware-hono';
+
+// @device-router/middleware-koa
+import {
+  createDeviceRouter as createKoaRouter,
+  loadProbeScript as loadKoaProbe,
+  createMiddleware as createKoaMw,
+  createProbeEndpoint as createKoaEndpoint,
+  createInjectionMiddleware as createKoaInject,
+} from '@device-router/middleware-koa';
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+const validSignals = {
+  hardwareConcurrency: 8,
+  deviceMemory: 8,
+  viewport: { width: 1920, height: 1080 },
+  connection: { downlink: 10, rtt: 50, effectiveType: '4g', saveData: false },
+  gpu: { vendor: 'Google Inc. (NVIDIA)', renderer: 'ANGLE (NVIDIA GeForce RTX 3080)' },
+  timestamp: Date.now(),
+};
+
+// ---------------------------------------------------------------------------
+// Harness
+// ---------------------------------------------------------------------------
+
+let passed = 0;
+let failed = 0;
+
+function assert(cond, label) {
+  if (cond) {
+    passed++;
+    console.log(`  \u2713 ${label}`);
+  } else {
+    failed++;
+    console.error(`  \u2717 ${label}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+console.log('1. @device-router/types — classify()');
+{
+  const tiers = classify(validSignals);
+  assert(typeof tiers.cpu === 'string', `cpu tier: ${tiers.cpu}`);
+  assert(typeof tiers.memory === 'string', `memory tier: ${tiers.memory}`);
+  assert(typeof tiers.connection === 'string', `connection tier: ${tiers.connection}`);
+  assert(typeof tiers.gpu === 'string', `gpu tier: ${tiers.gpu}`);
+}
+
+console.log('\n2. @device-router/types — individual classifiers');
+{
+  assert(typeof classifyCpu(8) === 'string', 'classifyCpu');
+  assert(typeof classifyMemory(8) === 'string', 'classifyMemory');
+  assert(
+    typeof classifyConnection({ downlink: 10, rtt: 50, effectiveType: '4g', saveData: false }) ===
+      'string',
+    'classifyConnection',
+  );
+  assert(typeof classifyGpu('ANGLE (NVIDIA GeForce RTX 3080)') === 'string', 'classifyGpu');
+}
+
+console.log('\n3. @device-router/types — deriveHints()');
+{
+  const tiers = classify(validSignals);
+  const hints = deriveHints(tiers);
+  assert(
+    typeof hints.deferHeavyComponents === 'boolean',
+    `deferHeavyComponents: ${hints.deferHeavyComponents}`,
+  );
+  assert(
+    typeof hints.reduceAnimations === 'boolean',
+    `reduceAnimations: ${hints.reduceAnimations}`,
+  );
+  assert(
+    typeof hints.limitVideoQuality === 'boolean',
+    `limitVideoQuality: ${hints.limitVideoQuality}`,
+  );
+  assert(typeof hints.serveMinimalCSS === 'boolean', `serveMinimalCSS: ${hints.serveMinimalCSS}`);
+  assert(
+    typeof hints.disable3dEffects === 'boolean',
+    `disable3dEffects: ${hints.disable3dEffects}`,
+  );
+  assert(
+    typeof hints.useImagePlaceholders === 'boolean',
+    `useImagePlaceholders: ${hints.useImagePlaceholders}`,
+  );
+  assert(
+    typeof hints.preferServerRendering === 'boolean',
+    `preferServerRendering: ${hints.preferServerRendering}`,
+  );
+  assert(typeof hints.useSystemFonts === 'boolean', `useSystemFonts: ${hints.useSystemFonts}`);
+  assert(typeof hints.disablePrefetch === 'boolean', `disablePrefetch: ${hints.disablePrefetch}`);
+}
+
+console.log('\n4. @device-router/types — validation');
+{
+  assert(isValidSignals(validSignals) === true, 'valid signals pass');
+  assert(isValidSignals(null) === false, 'null fails');
+  assert(isValidSignals('string') === false, 'string fails');
+  assert(isValidSignals({ hardwareConcurrency: 'not-a-number' }) === false, 'wrong type fails');
+  // validateThresholds throws on invalid, returns void on valid
+  let threw = false;
+  try {
+    validateThresholds({ cpu: { lowUpperBound: -1, midUpperBound: 4 } });
+  } catch {
+    threw = true;
+  }
+  assert(threw, 'validateThresholds throws on invalid');
+  let valid = true;
+  try {
+    validateThresholds({ cpu: DEFAULT_CPU_THRESHOLDS });
+  } catch {
+    valid = false;
+  }
+  assert(valid, 'validateThresholds accepts valid thresholds');
+}
+
+console.log('\n5. @device-router/types — bot detection');
+{
+  assert(typeof isBotSignals === 'function', 'isBotSignals exported');
+  assert(isBotSignals(validSignals) === false, 'normal signals not bot');
+}
+
+console.log('\n6. @device-router/types — header classification');
+{
+  assert(typeof classifyFromHeaders === 'function', 'classifyFromHeaders exported');
+  assert(typeof resolveFallback === 'function', 'resolveFallback exported');
+  assert(typeof ACCEPT_CH_VALUE === 'string', `ACCEPT_CH_VALUE: ${ACCEPT_CH_VALUE}`);
+}
+
+console.log('\n7. @device-router/types — constants');
+{
+  assert(typeof CONSERVATIVE_TIERS === 'object', 'CONSERVATIVE_TIERS exported');
+  assert(typeof OPTIMISTIC_TIERS === 'object', 'OPTIMISTIC_TIERS exported');
+  assert(typeof DEFAULT_CPU_THRESHOLDS === 'object', 'DEFAULT_CPU_THRESHOLDS exported');
+  assert(typeof DEFAULT_MEMORY_THRESHOLDS === 'object', 'DEFAULT_MEMORY_THRESHOLDS exported');
+  assert(
+    typeof DEFAULT_CONNECTION_THRESHOLDS === 'object',
+    'DEFAULT_CONNECTION_THRESHOLDS exported',
+  );
+  assert(typeof DEFAULT_GPU_THRESHOLDS === 'object', 'DEFAULT_GPU_THRESHOLDS exported');
+  assert(
+    typeof NO_PROBE_DATA_THRESHOLD === 'number',
+    `NO_PROBE_DATA_THRESHOLD: ${NO_PROBE_DATA_THRESHOLD}`,
+  );
+}
+
+console.log('\n8. @device-router/types — events');
+{
+  assert(typeof emitEvent === 'function', 'emitEvent exported');
+  assert(typeof extractErrorMessage === 'function', 'extractErrorMessage exported');
+  assert(typeof createProbeHealthCheck === 'function', 'createProbeHealthCheck exported');
+}
+
+console.log('\n9. @device-router/probe — exports');
+{
+  assert(typeof collectSignals === 'function', 'collectSignals exported');
+  assert(typeof runProbe === 'function', 'runProbe exported');
+  assert(typeof runProbeWithRetry === 'function', 'runProbeWithRetry exported');
+}
+
+console.log('\n10. @device-router/storage — MemoryStorageAdapter');
+{
+  const storage = new MemoryStorageAdapter();
+  const profile = {
+    tiers: classify(validSignals),
+    hints: deriveHints(classify(validSignals)),
+    signals: validSignals,
+  };
+  await storage.set('test-session', profile);
+  const retrieved = await storage.get('test-session');
+  assert(retrieved !== null, 'profile retrieved from memory');
+  assert(retrieved.tiers.cpu === profile.tiers.cpu, 'cpu tier matches after storage round-trip');
+  assert(
+    retrieved.hints.reduceAnimations === profile.hints.reduceAnimations,
+    'hints match after storage round-trip',
+  );
+  await storage.delete('test-session');
+  const deleted = await storage.get('test-session');
+  assert(deleted === null, 'profile deleted successfully');
+}
+
+console.log('\n11. @device-router/storage — RedisStorageAdapter');
+{
+  assert(typeof RedisStorageAdapter === 'function', 'RedisStorageAdapter exported');
+}
+
+console.log('\n12. @device-router/storage — cross-package dependency');
+{
+  // Storage depends on types. Verify the dependency resolution works:
+  // classify() from types produces data that storage can persist
+  const tiers = classify(validSignals);
+  const hints = deriveHints(tiers);
+  const store = new MemoryStorageAdapter();
+  const profile = { tiers, hints, signals: validSignals };
+  await store.set('cross-pkg', profile);
+  const got = await store.get('cross-pkg');
+  assert(got.tiers.cpu === tiers.cpu, 'types -> storage dependency works');
+}
+
+console.log('\n13. @device-router/middleware-express — exports');
+{
+  assert(typeof createExpressRouter === 'function', 'createDeviceRouter');
+  assert(typeof loadExpressProbe === 'function', 'loadProbeScript');
+  assert(typeof createExpressMw === 'function', 'createMiddleware');
+  assert(typeof createExpressEndpoint === 'function', 'createProbeEndpoint');
+  assert(typeof createExpressInject === 'function', 'createInjectionMiddleware');
+}
+
+console.log('\n14. @device-router/middleware-express — factory');
+{
+  const storage = new MemoryStorageAdapter();
+  const { middleware, probeEndpoint } = createExpressRouter({ storage });
+  assert(typeof middleware === 'function', 'middleware is a function');
+  assert(typeof probeEndpoint === 'function', 'probeEndpoint is a function');
+}
+
+console.log('\n15. @device-router/middleware-express — loadProbeScript');
+{
+  const script = loadExpressProbe();
+  assert(
+    typeof script === 'string' && script.length > 0,
+    `probe script loaded (${script.length} chars)`,
+  );
+}
+
+console.log('\n16. @device-router/middleware-fastify — exports + factory');
+{
+  assert(typeof createFastifyRouter === 'function', 'createDeviceRouter');
+  assert(typeof loadFastifyProbe === 'function', 'loadProbeScript');
+  assert(typeof createFastifyMw === 'function', 'createMiddleware');
+  assert(typeof createFastifyEndpoint === 'function', 'createProbeEndpoint');
+  assert(typeof createFastifyInject === 'function', 'createInjectionMiddleware');
+
+  const storage = new MemoryStorageAdapter();
+  const { middleware, probeEndpoint } = createFastifyRouter({ storage });
+  assert(typeof middleware === 'function', 'factory produces middleware');
+  assert(typeof probeEndpoint === 'function', 'factory produces probeEndpoint');
+}
+
+console.log('\n17. @device-router/middleware-hono — exports + factory');
+{
+  assert(typeof createHonoRouter === 'function', 'createDeviceRouter');
+  assert(typeof loadHonoProbe === 'function', 'loadProbeScript');
+  assert(typeof createHonoMw === 'function', 'createMiddleware');
+  assert(typeof createHonoEndpoint === 'function', 'createProbeEndpoint');
+  assert(typeof createHonoInject === 'function', 'createInjectionMiddleware');
+
+  const storage = new MemoryStorageAdapter();
+  const { middleware, probeEndpoint } = createHonoRouter({ storage });
+  assert(typeof middleware === 'function', 'factory produces middleware');
+  assert(typeof probeEndpoint === 'function', 'factory produces probeEndpoint');
+}
+
+console.log('\n18. @device-router/middleware-koa — exports + factory');
+{
+  assert(typeof createKoaRouter === 'function', 'createDeviceRouter');
+  assert(typeof loadKoaProbe === 'function', 'loadProbeScript');
+  assert(typeof createKoaMw === 'function', 'createMiddleware');
+  assert(typeof createKoaEndpoint === 'function', 'createProbeEndpoint');
+  assert(typeof createKoaInject === 'function', 'createInjectionMiddleware');
+
+  const storage = new MemoryStorageAdapter();
+  const { middleware, probeEndpoint } = createKoaRouter({ storage });
+  assert(typeof middleware === 'function', 'factory produces middleware');
+  assert(typeof probeEndpoint === 'function', 'factory produces probeEndpoint');
+}
+
+console.log('\n19. Cross-package: types -> storage -> middleware');
+{
+  // Full chain: classify signals, store profile, middleware factory works with shared storage
+  const tiers = classify(validSignals);
+  const hints = deriveHints(tiers);
+  const storage = new MemoryStorageAdapter();
+  await storage.set('full-chain', { tiers, hints, signals: validSignals });
+
+  // All four middleware packages can use the same storage instance
+  const expr = createExpressRouter({ storage });
+  const fast = createFastifyRouter({ storage });
+  const hono = createHonoRouter({ storage });
+  const koa = createKoaRouter({ storage });
+
+  assert(typeof expr.middleware === 'function', 'express middleware with shared storage');
+  assert(typeof fast.middleware === 'function', 'fastify middleware with shared storage');
+  assert(typeof hono.middleware === 'function', 'hono middleware with shared storage');
+  assert(typeof koa.middleware === 'function', 'koa middleware with shared storage');
+
+  // Verify storage still works after middleware setup
+  const got = await storage.get('full-chain');
+  assert(got.tiers.cpu === tiers.cpu, 'storage data intact after middleware setup');
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log(`\n${'='.repeat(40)}`);
+console.log(`Results: ${passed} passed, ${failed} failed`);
+console.log('='.repeat(40));
+
+if (failed > 0) {
+  process.exit(1);
+}
diff --git a/launch.py b/launch.py
new file mode 100755
index 0000000..e9d7b70
--- /dev/null
+++ b/launch.py
@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""DeviceRouter local launcher.
+
+Usage:
+    python launch.py
+
+Presents an interactive menu to build, run examples, and manage Docker services.
+Requires: Python 3.8+, pnpm, Docker (for Redis/observability options).
+
+Docs: docs/getting-started.md
+"""
+
+import os
+import subprocess
+import sys
+
+ROOT = os.path.dirname(os.path.abspath(__file__))
+
+EXAMPLES = {
+    "1": {
+        "name": "Express",
+        "dir": "examples/express-basic",
+        "url": "http://localhost:3000",
+        "doc": "docs/getting-started.md#quick-start--express",
+    },
+    "2": {
+        "name": "Fastify",
+        "dir": "examples/fastify-basic",
+        "url": "http://localhost:3000",
+        "doc": "docs/getting-started.md#quick-start--fastify",
+    },
+    "3": {
+        "name": "Hono",
+        "dir": "examples/hono-basic",
+        "url": "http://localhost:3000",
+        "doc": "docs/getting-started.md#quick-start--hono",
+    },
+    "4": {
+        "name": "Koa",
+        "dir": "examples/koa-basic",
+        "url": "http://localhost:3000",
+        "doc": "docs/getting-started.md#quick-start--koa",
+    },
+}
+
+
+def run(cmd, cwd=ROOT):
+    print(f"\n> {cmd}")
+    subprocess.run(cmd, shell=True, cwd=cwd, check=True)
+
+
+def header():
+    print("\n╔══════════════════════════════════════════════╗")
+    print("║         DeviceRouter Local Launcher          ║")
+    print("╚══════════════════════════════════════════════╝\n")
+
+
+def menu():
+    header()
+    print("  Build")
+    print("  ─────")
+    print("  b   Install deps & build all packages        (pnpm install && pnpm build)")
+    print()
+    print("  Examples  (MemoryStorage, no Docker needed)")
+    print("  ────────")
+    for key, ex in EXAMPLES.items():
+        print(f"  {key}   {ex['name']:<12} {ex['url']:<30} {ex['doc']}")
+    print()
+    print("  Docker")
+    print("  ──────")
+    print("  r   Redis only                               (docker compose — express-basic)")
+    print("  o   Observability stack                      (app + Redis + Prometheus + Grafana)")
+    print("  d   Stop all Docker services")
+    print()
+    print("  Other")
+    print("  ─────")
+    print("  t   Run tests                                (pnpm test)")
+    print("  l   Lint                                     (pnpm lint)")
+    print("  q   Quit")
+    print()
+
+
+def build():
+    run("pnpm install")
+    run("pnpm build")
+    print("\nBuild complete.")
+
+
+def run_example(key):
+    ex = EXAMPLES[key]
+    example_dir = os.path.join(ROOT, ex["dir"])
+    print(f"\nStarting {ex['name']} example...")
+    print(f"Open {ex['url']} in your browser.")
+    print(f"Docs: {ex['doc']}")
+    print("Press Ctrl+C to stop.\n")
+    try:
+        run("pnpm dev", cwd=example_dir)
+    except KeyboardInterrupt:
+        print(f"\n{ex['name']} server stopped.")
+
+
+def redis_up():
+    compose_dir = os.path.join(ROOT, "examples/express-basic")
+    run("docker compose up -d", cwd=compose_dir)
+    print("\nRedis running on localhost:6379")
+    print("Update your server.ts to use RedisStorageAdapter to connect.")
+
+
+def observability_up():
+    compose_dir = os.path.join(ROOT, "examples/observability")
+    print("\nStarting observability stack (app + Redis + Prometheus + Grafana)...")
+    print("  App:        http://localhost:3000")
+    print("  Grafana:    http://localhost:3001  (admin/admin)")
+    print("  Prometheus: http://localhost:9090")
+    print("  Docs:       docs/observability.md")
+    print("\nPress Ctrl+C to stop.\n")
+    try:
+        run("docker compose up", cwd=compose_dir)
+    except KeyboardInterrupt:
+        print("\nStopping observability stack...")
+        run("docker compose down", cwd=compose_dir)
+
+
+def docker_down():
+    for d in ["examples/express-basic", "examples/observability"]:
+        compose_dir = os.path.join(ROOT, d)
+        compose_file = os.path.join(compose_dir, "docker-compose.yml")
+        if os.path.exists(compose_file):
+            run("docker compose down", cwd=compose_dir)
+    print("\nAll Docker services stopped.")
+
+
+def run_tests():
+    run("pnpm test")
+
+
+def lint():
+    run("pnpm lint")
+
+
+def main():
+    if not os.path.exists(os.path.join(ROOT, "package.json")):
+        print("Error: launch.py must be in the DeviceRouter repo root.")
+        sys.exit(1)
+
+    while True:
+        menu()
+        choice = input("  Choose an option: ").strip().lower()
+
+        try:
+            if choice == "b":
+                build()
+            elif choice in EXAMPLES:
+                run_example(choice)
+            elif choice == "r":
+                redis_up()
+            elif choice == "o":
+                observability_up()
+            elif choice == "d":
+                docker_down()
+            elif choice == "t":
+                run_tests()
+            elif choice == "l":
+                lint()
+            elif choice == "q":
+                print("Bye!")
+                break
+            else:
+                print(f"Unknown option: {choice}")
+        except subprocess.CalledProcessError as e:
+            print(f"\nCommand failed (exit {e.returncode}). Check output above.")
+        except KeyboardInterrupt:
+            print()
+
+        input("\nPress Enter to continue...")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/package.json b/package.json
index ef7c71d..8cadb9e 100644
--- a/package.json
+++ b/package.json
@@ -19,8 +19,11 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint .",
+    "lint:publint": "pnpm -r --filter './packages/*' exec publint",
+    "lint:attw": "pnpm -r --filter './packages/*' exec attw --pack --entrypoints . --ignore-rules cjs-resolves-to-esm",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "test:e2e": "pnpm build && bash e2e/run.sh",
     "clean": "pnpm -r run clean"
   },
   "engines": {
@@ -36,11 +39,13 @@
     }
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
     "@eslint/js": "^10.0.1",
     "@types/node": "^25.3.3",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.2",
     "prettier": "^3.8.1",
+    "publint": "^0.3.17",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
diff --git a/packages/middleware-koa/package.json b/packages/middleware-koa/package.json
index 82787a9..5bcfafc 100644
--- a/packages/middleware-koa/package.json
+++ b/packages/middleware-koa/package.json
@@ -51,7 +51,7 @@
     "@device-router/types": "workspace:*"
   },
   "peerDependencies": {
-    "koa": "^2.0.0"
+    "koa": "^2.0.0 || ^3.0.0"
   },
   "peerDependenciesMeta": {
     "@device-router/probe": {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 70bd13e..b209d42 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -11,6 +11,9 @@ importers:
 
   .:
     devDependencies:
+      '@arethetypeswrong/cli':
+        specifier: ^0.18.2
+        version: 0.18.2
       '@eslint/js':
         specifier: ^10.0.1
         version: 10.0.1(eslint@10.0.2)
@@ -26,6 +29,9 @@ importers:
       prettier:
         specifier: ^3.8.1
         version: 3.8.1
+      publint:
+        specifier: ^0.3.17
+        version: 0.3.17
       typescript:
         specifier: ^5.9.3
         version: 5.9.3
@@ -263,6 +269,18 @@ importers:
 
 packages:
 
+  '@andrewbranch/untar.js@1.0.3':
+    resolution: {integrity: sha512-Jh15/qVmrLGhkKJBdXlK1+9tY4lZruYjsgkDFj08ZmDiWVBLJcqkok7Z0/R0In+i1rScBpJlSvrTS2Lm41Pbnw==}
+
+  '@arethetypeswrong/cli@0.18.2':
+    resolution: {integrity: sha512-PcFM20JNlevEDKBg4Re29Rtv2xvjvQZzg7ENnrWFSS0PHgdP2njibVFw+dRUhNkPgNfac9iUqO0ohAXqQL4hbw==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  '@arethetypeswrong/core@0.18.2':
+    resolution: {integrity: sha512-GiwTmBFOU1/+UVNqqCGzFJYfBXEytUkiI+iRZ6Qx7KmUVtLm00sYySkfe203C9QtPG11yOz1ZaMek8dT/xnlgg==}
+    engines: {node: '>=20'}
+
   '@babel/helper-string-parser@7.27.1':
     resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
     engines: {node: '>=6.9.0'}
@@ -284,6 +302,13 @@ packages:
     resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==}
     engines: {node: '>=18'}
 
+  '@braidai/lang@1.1.2':
+    resolution: {integrity: sha512-qBcknbBufNHlui137Hft8xauQMTZDKdophmLFv05r2eNmdIv/MlPuP4TdUknHG68UdWLgVZwgxVe735HzJNIwA==}
+
+  '@colors/colors@1.5.0':
+    resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==}
+    engines: {node: '>=0.1.90'}
+
   '@esbuild/aix-ppc64@0.27.3':
     resolution: {integrity: sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==}
     engines: {node: '>=18'}
@@ -535,6 +560,9 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
 
+  '@loaderkit/resolve@1.0.4':
+    resolution: {integrity: sha512-rJzYKVcV4dxJv+vW6jlvagF8zvGxHJ2+HTr1e2qOejfmGhAApgJHl8Aog4mMszxceTRiKTTbnpgmTO1bEZHV/A==}
+
   '@opentelemetry/api@1.9.0':
     resolution: {integrity: sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==}
     engines: {node: '>=8.0.0'}
@@ -542,6 +570,10 @@ packages:
   '@pinojs/redact@0.4.0':
     resolution: {integrity: sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==}
 
+  '@publint/pack@0.1.4':
+    resolution: {integrity: sha512-HDVTWq3H0uTXiU0eeSQntcVUTPP3GamzeXI41+x7uU9J65JgWQh3qWZHblR1i0npXfFtF+mxBiU2nJH8znxWnQ==}
+    engines: {node: '>=18'}
+
   '@rollup/rollup-android-arm-eabi@4.59.0':
     resolution: {integrity: sha512-upnNBkA6ZH2VKGcBj9Fyl9IGNPULcjXRlg0LLeaioQWueH30p6IXtJEbKAgvyv+mJaMxSm1l6xwDXYjpEMiLMg==}
     cpu: [arm]
@@ -667,6 +699,10 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@sindresorhus/is@4.6.0':
+    resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
+    engines: {node: '>=10'}
+
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
@@ -873,6 +909,25 @@ packages:
   ajv@8.18.0:
     resolution: {integrity: sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==}
 
+  ansi-escapes@7.3.0:
+    resolution: {integrity: sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==}
+    engines: {node: '>=18'}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  any-promise@1.3.0:
+    resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==}
+
   assertion-error@2.0.1:
     resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
     engines: {node: '>=12'}
@@ -918,10 +973,48 @@ packages:
     resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
     engines: {node: '>=18'}
 
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
+  char-regex@1.0.2:
+    resolution: {integrity: sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==}
+    engines: {node: '>=10'}
+
+  cjs-module-lexer@1.4.3:
+    resolution: {integrity: sha512-9z8TZaGM1pfswYeXrUpzPrkx8UnWYdhJclsiYMm6x/w5+nN+8Tf/LnAgfLGQCm59qAOxU8WwHEq2vNwF6i4j+Q==}
+
+  cli-highlight@2.1.11:
+    resolution: {integrity: sha512-9KDcoEVwyUXrjcJNvHD0NFc/hiwe/WPVYIleQh2O1N2Zro5gWJZ/K+3DGn8w8P/F6FxOgzyC5bxDyHIgCSPhGg==}
+    engines: {node: '>=8.0.0', npm: '>=5.0.0'}
+    hasBin: true
+
+  cli-table3@0.6.5:
+    resolution: {integrity: sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ==}
+    engines: {node: 10.* || >= 12.*}
+
+  cliui@7.0.4:
+    resolution: {integrity: sha512-OcRE68cOsVMXp1Yvonl/fzkQOyjLSu/8bhPDfQt0e0/Eb283TKP20Fs2MqoPsr9SwA595rRCA+QMzYc9nBP+JQ==}
+
   cluster-key-slot@1.1.2:
     resolution: {integrity: sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA==}
     engines: {node: '>=0.10.0'}
 
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  commander@10.0.1:
+    resolution: {integrity: sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug==}
+    engines: {node: '>=14'}
+
   content-disposition@1.0.1:
     resolution: {integrity: sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==}
     engines: {node: '>=18'}
@@ -1002,10 +1095,20 @@ packages:
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
+  emoji-regex@8.0.0:
+    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+
+  emojilib@2.4.0:
+    resolution: {integrity: sha512-5U0rVMU5Y2n2+ykNLQqMoqklN9ICBT/KsvC1Gz6vqHbz2AXXGkG+Pm5rMWk/8Vjrr/mY9985Hi8DYzn1F09Nyw==}
+
   encodeurl@2.0.0:
     resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
     engines: {node: '>= 0.8'}
 
+  environment@1.1.0:
+    resolution: {integrity: sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==}
+    engines: {node: '>=18'}
+
   es-define-property@1.0.1:
     resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
     engines: {node: '>= 0.4'}
@@ -1026,6 +1129,10 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
   escape-html@1.0.3:
     resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
 
@@ -1129,6 +1236,9 @@ packages:
       picomatch:
         optional: true
 
+  fflate@0.8.2:
+    resolution: {integrity: sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A==}
+
   file-entry-cache@8.0.0:
     resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}
     engines: {node: '>=16.0.0'}
@@ -1172,6 +1282,10 @@ packages:
   function-bind@1.1.2:
     resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
 
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
   get-intrinsic@1.3.0:
     resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
     engines: {node: '>= 0.4'}
@@ -1203,6 +1317,9 @@ packages:
     resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
     engines: {node: '>= 0.4'}
 
+  highlight.js@10.7.3:
+    resolution: {integrity: sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==}
+
   hono@4.12.3:
     resolution: {integrity: sha512-SFsVSjp8sj5UumXOOFlkZOG6XS9SJDKw0TbwFeV+AJ8xlST8kxK5Z/5EYa111UY8732lK2S/xB653ceuaoGwpg==}
     engines: {node: '>=16.9.0'}
@@ -1257,6 +1374,10 @@ packages:
     resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
     engines: {node: '>=0.10.0'}
 
+  is-fullwidth-code-point@3.0.0:
+    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
+    engines: {node: '>=8'}
+
   is-glob@4.0.3:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
@@ -1328,6 +1449,10 @@ packages:
   lodash.isarguments@3.1.0:
     resolution: {integrity: sha512-chi4NHZlZqZD18a0imDHnZPrDeBbTtVN7GXMwuGdRH9qotxAjYs3aVLKc7zNOG9eddR5Ksd8rvFEBc9SsggPpg==}
 
+  lru-cache@11.2.6:
+    resolution: {integrity: sha512-ESL2CrkS/2wTPfuend7Zhkzo2u0daGJ/A2VucJOgQ/C48S/zB8MMeMHSGKYpXhIjbPxfuezITkaBH1wqv00DDQ==}
+    engines: {node: 20 || >=22}
+
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
@@ -1338,6 +1463,17 @@ packages:
     resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==}
     engines: {node: '>=10'}
 
+  marked-terminal@7.3.0:
+    resolution: {integrity: sha512-t4rBvPsHc57uE/2nJOLmMbZCQ4tgAccAED3ngXQqW6g+TxA488JzJ+FK3lQkzBQOI1mRV/r/Kq+1ZlJ4D0owQw==}
+    engines: {node: '>=16.0.0'}
+    peerDependencies:
+      marked: '>=1 <16'
+
+  marked@9.1.6:
+    resolution: {integrity: sha512-jcByLnIFkd5gSXZmjNvS1TlmRhCXZjIzHYlaGkPlLIekG55JDR2Z4va9tZwCiP+/RDERiNhMOFu01xd6O5ct1Q==}
+    engines: {node: '>= 16'}
+    hasBin: true
+
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
@@ -1370,9 +1506,16 @@ packages:
     resolution: {integrity: sha512-+G4CpNBxa5MprY+04MbgOw1v7So6n5JY166pFi9KfYwT78fxScCeSNQSNzp6dpPSW2rONOps6Ocam1wFhCgoVw==}
     engines: {node: 18 || 20 || >=22}
 
+  mri@1.2.0:
+    resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
+    engines: {node: '>=4'}
+
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
+  mz@2.7.0:
+    resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
+
   nanoid@3.3.11:
     resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -1389,6 +1532,14 @@ packages:
     resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
     engines: {node: '>= 0.6'}
 
+  node-emoji@2.2.0:
+    resolution: {integrity: sha512-Z3lTE9pLaJF47NyMhd4ww1yFTAP8YhYI8SleJiHzM46Fgpm5cnNzSl9XfzFNqbaz+VlJrIj3fXQ4DeN1Rjm6cw==}
+    engines: {node: '>=18'}
+
+  object-assign@4.1.1:
+    resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
+    engines: {node: '>=0.10.0'}
+
   object-inspect@1.13.4:
     resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
     engines: {node: '>= 0.4'}
@@ -1419,6 +1570,18 @@ packages:
     resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
     engines: {node: '>=10'}
 
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
+  parse5-htmlparser2-tree-adapter@6.0.1:
+    resolution: {integrity: sha512-qPuWvbLgvDGilKc5BoicRovlT4MtYT6JfJyBOMDsKoiT+GiuP5qyrPCnR9HcPECIJJmZh5jRndyNThnhhb/vlA==}
+
+  parse5@5.1.1:
+    resolution: {integrity: sha512-ugq4DFI0Ptb+WWjAdOK16+u/nHfiIrcE+sh8kZMaM0WllQKLI9rOUq6c2b7cwPkXdzfQESqvoqK6ug7U/Yyzug==}
+
+  parse5@6.0.1:
+    resolution: {integrity: sha512-Ofn/CTFzRGTTxwpNEs9PP93gXShHcTq255nzRYSKe8AkVpZY7e1fpmTfOyoIvjP5HG7Z2ZM7VS9PPhQGW2pOpw==}
+
   parseurl@1.3.3:
     resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
     engines: {node: '>= 0.8'}
@@ -1481,6 +1644,11 @@ packages:
     resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
     engines: {node: '>= 0.10'}
 
+  publint@0.3.17:
+    resolution: {integrity: sha512-Q3NLegA9XM6usW+dYQRG1g9uEHiYUzcCVBJDJ7yMcWRqVU9LYZUWdqbwMZfmTCFC5PZLQpLAmhvRcQRl3exqkw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   punycode@2.3.1:
     resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
     engines: {node: '>=6'}
@@ -1512,6 +1680,10 @@ packages:
     resolution: {integrity: sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A==}
     engines: {node: '>=4'}
 
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
   require-from-string@2.0.2:
     resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
     engines: {node: '>=0.10.0'}
@@ -1539,6 +1711,10 @@ packages:
     resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
     engines: {node: '>= 18'}
 
+  sade@1.8.1:
+    resolution: {integrity: sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==}
+    engines: {node: '>=6'}
+
   safe-regex2@5.0.0:
     resolution: {integrity: sha512-YwJwe5a51WlK7KbOJREPdjNrpViQBI3p4T50lfwPuDhZnE3XGVTlGvi+aolc5+RvxDD6bnUmjVsU9n1eboLUYw==}
 
@@ -1598,6 +1774,10 @@ packages:
   siginfo@2.0.0:
     resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
 
+  skin-tone@2.0.0:
+    resolution: {integrity: sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA==}
+    engines: {node: '>=8'}
+
   sonic-boom@4.2.1:
     resolution: {integrity: sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==}
 
@@ -1626,13 +1806,32 @@ packages:
   std-env@3.10.0:
     resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==}
 
+  string-width@4.2.3:
+    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
+    engines: {node: '>=8'}
+
+  strip-ansi@6.0.1:
+    resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
+    engines: {node: '>=8'}
+
   supports-color@7.2.0:
     resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
     engines: {node: '>=8'}
 
+  supports-hyperlinks@3.2.0:
+    resolution: {integrity: sha512-zFObLMyZeEwzAoKCyu1B91U79K2t7ApXuQfo8OuxwXLDgcKxuwM+YvcbIhm6QWqz7mHUH1TVytR1PwVVjEuMig==}
+    engines: {node: '>=14.18'}
+
   tdigest@0.1.2:
     resolution: {integrity: sha512-+G0LLgjjo9BZX2MfdvPfH+MKLCrxlXSYec5DaPYP1fe6Iyhf0/fSmJ0bFiZ1F8BT6cGXl2LpltQptzjXKWEkKA==}
 
+  thenify-all@1.6.0:
+    resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==}
+    engines: {node: '>=0.8'}
+
+  thenify@3.3.1:
+    resolution: {integrity: sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw==}
+
   thread-stream@4.0.0:
     resolution: {integrity: sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA==}
     engines: {node: '>=20'}
@@ -1690,6 +1889,11 @@ packages:
       eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
       typescript: '>=4.8.4 <6.0.0'
 
+  typescript@5.6.1-rc:
+    resolution: {integrity: sha512-E3b2+1zEFu84jB0YQi9BORDjz9+jGbwwy1Zi3G0LUNw7a7cePUrHMRNy8aPh53nXpkFGVHSxIZo5vKTfYaFiBQ==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
   typescript@5.9.3:
     resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
     engines: {node: '>=14.17'}
@@ -1698,6 +1902,10 @@ packages:
   undici-types@7.18.2:
     resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
 
+  unicode-emoji-modifier-base@1.0.0:
+    resolution: {integrity: sha512-yLSH4py7oFH3oG/9K+XWrz1pSi3dfUrWEnInbxMfArOfc1+33BlGPQtLsOYwvdMy11AwUBetYuaRxSPqgkq+8g==}
+    engines: {node: '>=4'}
+
   unpipe@1.0.0:
     resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
     engines: {node: '>= 0.8'}
@@ -1705,6 +1913,10 @@ packages:
   uri-js@4.4.1:
     resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
 
+  validate-npm-package-name@5.0.1:
+    resolution: {integrity: sha512-OljLrQ9SQdOUqTaQxqL5dEfZWrXExyyWsozYlAWFawPVNuD83igl7uJD2RTkNMbniIYgt8l81eCJGIdQF7avLQ==}
+    engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0}
+
   vary@1.1.2:
     resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
     engines: {node: '>= 0.8'}
@@ -1797,15 +2009,54 @@ packages:
     resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
     engines: {node: '>=0.10.0'}
 
+  wrap-ansi@7.0.0:
+    resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
+    engines: {node: '>=10'}
+
   wrappy@1.0.2:
     resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
 
+  y18n@5.0.8:
+    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+    engines: {node: '>=10'}
+
+  yargs-parser@20.2.9:
+    resolution: {integrity: sha512-y11nGElTIV+CT3Zv9t7VKl+Q3hTQoT9a1Qzezhhl6Rp21gJ/IVTW7Z3y9EWXhuUBC2Shnf+DX0antecpAwSP8w==}
+    engines: {node: '>=10'}
+
+  yargs@16.2.0:
+    resolution: {integrity: sha512-D1mvvtDG0L5ft/jGWkLpG1+m0eQxOfaBvTNELraWj22wSVUMWxZUvYgJYcKh6jGGIkJFhH4IZPQhR4TKpc8mBw==}
+    engines: {node: '>=10'}
+
   yocto-queue@0.1.0:
     resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
     engines: {node: '>=10'}
 
 snapshots:
 
+  '@andrewbranch/untar.js@1.0.3': {}
+
+  '@arethetypeswrong/cli@0.18.2':
+    dependencies:
+      '@arethetypeswrong/core': 0.18.2
+      chalk: 4.1.2
+      cli-table3: 0.6.5
+      commander: 10.0.1
+      marked: 9.1.6
+      marked-terminal: 7.3.0(marked@9.1.6)
+      semver: 7.7.4
+
+  '@arethetypeswrong/core@0.18.2':
+    dependencies:
+      '@andrewbranch/untar.js': 1.0.3
+      '@loaderkit/resolve': 1.0.4
+      cjs-module-lexer: 1.4.3
+      fflate: 0.8.2
+      lru-cache: 11.2.6
+      semver: 7.7.4
+      typescript: 5.6.1-rc
+      validate-npm-package-name: 5.0.1
+
   '@babel/helper-string-parser@7.27.1': {}
 
   '@babel/helper-validator-identifier@7.28.5': {}
@@ -1821,6 +2072,11 @@ snapshots:
 
   '@bcoe/v8-coverage@1.0.2': {}
 
+  '@braidai/lang@1.1.2': {}
+
+  '@colors/colors@1.5.0':
+    optional: true
+
   '@esbuild/aix-ppc64@0.27.3':
     optional: true
 
@@ -1987,10 +2243,16 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  '@loaderkit/resolve@1.0.4':
+    dependencies:
+      '@braidai/lang': 1.1.2
+
   '@opentelemetry/api@1.9.0': {}
 
   '@pinojs/redact@0.4.0': {}
 
+  '@publint/pack@0.1.4': {}
+
   '@rollup/rollup-android-arm-eabi@4.59.0':
     optional: true
 
@@ -2066,6 +2328,8 @@ snapshots:
   '@rollup/rollup-win32-x64-msvc@4.59.0':
     optional: true
 
+  '@sindresorhus/is@4.6.0': {}
+
   '@standard-schema/spec@1.1.0': {}
 
   '@types/accepts@1.3.7':
@@ -2338,6 +2602,20 @@ snapshots:
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
+  ansi-escapes@7.3.0:
+    dependencies:
+      environment: 1.1.0
+
+  ansi-regex@5.0.1: {}
+
+  ansi-regex@6.2.2: {}
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  any-promise@1.3.0: {}
+
   assertion-error@2.0.1: {}
 
   ast-v8-to-istanbul@0.3.11:
@@ -2389,8 +2667,48 @@ snapshots:
 
   chai@6.2.2: {}
 
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
+  chalk@5.6.2: {}
+
+  char-regex@1.0.2: {}
+
+  cjs-module-lexer@1.4.3: {}
+
+  cli-highlight@2.1.11:
+    dependencies:
+      chalk: 4.1.2
+      highlight.js: 10.7.3
+      mz: 2.7.0
+      parse5: 5.1.1
+      parse5-htmlparser2-tree-adapter: 6.0.1
+      yargs: 16.2.0
+
+  cli-table3@0.6.5:
+    dependencies:
+      string-width: 4.2.3
+    optionalDependencies:
+      '@colors/colors': 1.5.0
+
+  cliui@7.0.4:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
   cluster-key-slot@1.1.2: {}
 
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  commander@10.0.1: {}
+
   content-disposition@1.0.1: {}
 
   content-type@1.0.5: {}
@@ -2447,8 +2765,14 @@ snapshots:
 
   ee-first@1.1.1: {}
 
+  emoji-regex@8.0.0: {}
+
+  emojilib@2.4.0: {}
+
   encodeurl@2.0.0: {}
 
+  environment@1.1.0: {}
+
   es-define-property@1.0.1: {}
 
   es-errors@1.3.0: {}
@@ -2488,6 +2812,8 @@ snapshots:
       '@esbuild/win32-ia32': 0.27.3
       '@esbuild/win32-x64': 0.27.3
 
+  escalade@3.2.0: {}
+
   escape-html@1.0.3: {}
 
   escape-string-regexp@4.0.0: {}
@@ -2648,6 +2974,8 @@ snapshots:
     optionalDependencies:
       picomatch: 4.0.3
 
+  fflate@0.8.2: {}
+
   file-entry-cache@8.0.0:
     dependencies:
       flat-cache: 4.0.1
@@ -2692,6 +3020,8 @@ snapshots:
 
   function-bind@1.1.2: {}
 
+  get-caller-file@2.0.5: {}
+
   get-intrinsic@1.3.0:
     dependencies:
       call-bind-apply-helpers: 1.0.2
@@ -2728,6 +3058,8 @@ snapshots:
     dependencies:
       function-bind: 1.1.2
 
+  highlight.js@10.7.3: {}
+
   hono@4.12.3: {}
 
   html-escaper@2.0.2: {}
@@ -2785,6 +3117,8 @@ snapshots:
 
   is-extglob@2.1.1: {}
 
+  is-fullwidth-code-point@3.0.0: {}
+
   is-glob@4.0.3:
     dependencies:
       is-extglob: 2.1.1
@@ -2870,6 +3204,8 @@ snapshots:
 
   lodash.isarguments@3.1.0: {}
 
+  lru-cache@11.2.6: {}
+
   magic-string@0.30.21:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
@@ -2884,6 +3220,19 @@ snapshots:
     dependencies:
       semver: 7.7.4
 
+  marked-terminal@7.3.0(marked@9.1.6):
+    dependencies:
+      ansi-escapes: 7.3.0
+      ansi-regex: 6.2.2
+      chalk: 5.6.2
+      cli-highlight: 2.1.11
+      cli-table3: 0.6.5
+      marked: 9.1.6
+      node-emoji: 2.2.0
+      supports-hyperlinks: 3.2.0
+
+  marked@9.1.6: {}
+
   math-intrinsics@1.1.0: {}
 
   media-typer@1.1.0: {}
@@ -2906,8 +3255,16 @@ snapshots:
     dependencies:
       brace-expansion: 5.0.3
 
+  mri@1.2.0: {}
+
   ms@2.1.3: {}
 
+  mz@2.7.0:
+    dependencies:
+      any-promise: 1.3.0
+      object-assign: 4.1.1
+      thenify-all: 1.6.0
+
   nanoid@3.3.11: {}
 
   natural-compare@1.4.0: {}
@@ -2916,6 +3273,15 @@ snapshots:
 
   negotiator@1.0.0: {}
 
+  node-emoji@2.2.0:
+    dependencies:
+      '@sindresorhus/is': 4.6.0
+      char-regex: 1.0.2
+      emojilib: 2.4.0
+      skin-tone: 2.0.0
+
+  object-assign@4.1.1: {}
+
   object-inspect@1.13.4: {}
 
   obug@2.1.1: {}
@@ -2947,6 +3313,16 @@ snapshots:
     dependencies:
       p-limit: 3.1.0
 
+  package-manager-detector@1.6.0: {}
+
+  parse5-htmlparser2-tree-adapter@6.0.1:
+    dependencies:
+      parse5: 6.0.1
+
+  parse5@5.1.1: {}
+
+  parse5@6.0.1: {}
+
   parseurl@1.3.3: {}
 
   path-exists@4.0.0: {}
@@ -3005,6 +3381,13 @@ snapshots:
       forwarded: 0.2.0
       ipaddr.js: 1.9.1
 
+  publint@0.3.17:
+    dependencies:
+      '@publint/pack': 0.1.4
+      package-manager-detector: 1.6.0
+      picocolors: 1.1.1
+      sade: 1.8.1
+
   punycode@2.3.1: {}
 
   qs@6.15.0:
@@ -3030,6 +3413,8 @@ snapshots:
     dependencies:
       redis-errors: 1.2.0
 
+  require-directory@2.1.1: {}
+
   require-from-string@2.0.2: {}
 
   resolve-pkg-maps@1.0.0: {}
@@ -3081,6 +3466,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  sade@1.8.1:
+    dependencies:
+      mri: 1.2.0
+
   safe-regex2@5.0.0:
     dependencies:
       ret: 0.5.0
@@ -3158,6 +3547,10 @@ snapshots:
 
   siginfo@2.0.0: {}
 
+  skin-tone@2.0.0:
+    dependencies:
+      unicode-emoji-modifier-base: 1.0.0
+
   sonic-boom@4.2.1:
     dependencies:
       atomic-sleep: 1.0.0
@@ -3176,14 +3569,37 @@ snapshots:
 
   std-env@3.10.0: {}
 
+  string-width@4.2.3:
+    dependencies:
+      emoji-regex: 8.0.0
+      is-fullwidth-code-point: 3.0.0
+      strip-ansi: 6.0.1
+
+  strip-ansi@6.0.1:
+    dependencies:
+      ansi-regex: 5.0.1
+
   supports-color@7.2.0:
     dependencies:
       has-flag: 4.0.0
 
+  supports-hyperlinks@3.2.0:
+    dependencies:
+      has-flag: 4.0.0
+      supports-color: 7.2.0
+
   tdigest@0.1.2:
     dependencies:
       bintrees: 1.0.2
 
+  thenify-all@1.6.0:
+    dependencies:
+      thenify: 3.3.1
+
+  thenify@3.3.1:
+    dependencies:
+      any-promise: 1.3.0
+
   thread-stream@4.0.0:
     dependencies:
       real-require: 0.2.0
@@ -3237,16 +3653,22 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  typescript@5.6.1-rc: {}
+
   typescript@5.9.3: {}
 
   undici-types@7.18.2: {}
 
+  unicode-emoji-modifier-base@1.0.0: {}
+
   unpipe@1.0.0: {}
 
   uri-js@4.4.1:
     dependencies:
       punycode: 2.3.1
 
+  validate-npm-package-name@5.0.1: {}
+
   vary@1.1.2: {}
 
   vite@7.3.1(@types/node@25.3.3)(tsx@4.21.0):
@@ -3311,6 +3733,26 @@ snapshots:
 
   word-wrap@1.2.5: {}
 
+  wrap-ansi@7.0.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
   wrappy@1.0.2: {}
 
+  y18n@5.0.8: {}
+
+  yargs-parser@20.2.9: {}
+
+  yargs@16.2.0:
+    dependencies:
+      cliui: 7.0.4
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 20.2.9
+
   yocto-queue@0.1.0: {}

From ef9f5666667c9c87f0689219a4a26e0146e163ef Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Wed, 4 Mar 2026 18:10:22 +0100
Subject: [PATCH 11/12] Exclude e2e/ from ESLint

---
 eslint.config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eslint.config.js b/eslint.config.js
index a95657e..c9e56df 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -5,7 +5,7 @@ export default tseslint.config(
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ['**/dist/', '**/coverage/', '**/node_modules/', 'examples/', '**/scripts/'],
+    ignores: ['**/dist/', '**/coverage/', '**/node_modules/', 'examples/', '**/scripts/', 'e2e/'],
   },
   {
     rules: {

From 6af1c6e74159e1d7c5155d307ac1e5e65524d3b9 Mon Sep 17 00:00:00 2001
From: Lisa <lisa.welsch1985@gmail.com>
Date: Wed, 4 Mar 2026 18:11:42 +0100
Subject: [PATCH 12/12] chore: bump all packages to 1.0.0

---
 CHANGELOG.md                             | 2 +-
 package.json                             | 2 +-
 packages/middleware-express/package.json | 2 +-
 packages/middleware-fastify/package.json | 2 +-
 packages/middleware-hono/package.json    | 2 +-
 packages/middleware-koa/package.json     | 2 +-
 packages/probe/package.json              | 2 +-
 packages/storage/package.json            | 2 +-
 packages/types/package.json              | 2 +-
 9 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cd67e24..8b4b1c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## 1.0.0 (2026-03-04)
 
 ### Breaking Changes
 
diff --git a/package.json b/package.json
index 8cadb9e..3eb53e7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "device-router",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "private": true,
   "type": "module",
   "license": "MIT",
diff --git a/packages/middleware-express/package.json b/packages/middleware-express/package.json
index 306f147..c8f926c 100644
--- a/packages/middleware-express/package.json
+++ b/packages/middleware-express/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@device-router/middleware-express",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Express middleware for DeviceRouter — device classification and rendering hints per request",
   "license": "MIT",
diff --git a/packages/middleware-fastify/package.json b/packages/middleware-fastify/package.json
index 2ed1eed..34ca168 100644
--- a/packages/middleware-fastify/package.json
+++ b/packages/middleware-fastify/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@device-router/middleware-fastify",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Fastify middleware for DeviceRouter — device classification and rendering hints per request",
   "license": "MIT",
diff --git a/packages/middleware-hono/package.json b/packages/middleware-hono/package.json
index 0c09320..43e22e3 100644
--- a/packages/middleware-hono/package.json
+++ b/packages/middleware-hono/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@device-router/middleware-hono",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Hono middleware for DeviceRouter — device classification and rendering hints, edge-compatible",
   "license": "MIT",
diff --git a/packages/middleware-koa/package.json b/packages/middleware-koa/package.json
index 5bcfafc..af3c86f 100644
--- a/packages/middleware-koa/package.json
+++ b/packages/middleware-koa/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@device-router/middleware-koa",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Koa middleware for DeviceRouter — device classification and rendering hints per request",
   "license": "MIT",
diff --git a/packages/probe/package.json b/packages/probe/package.json
index c0308c8..200ac9a 100644
--- a/packages/probe/package.json
+++ b/packages/probe/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@device-router/probe",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Lightweight (~1 KB gzipped) client-side probe for collecting device capability signals",
   "license": "MIT",
diff --git a/packages/storage/package.json b/packages/storage/package.json
index 781aa76..169d7e6 100644
--- a/packages/storage/package.json
+++ b/packages/storage/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@device-router/storage",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Storage adapters (memory, Redis) for persisting device profiles in DeviceRouter",
   "license": "MIT",
diff --git a/packages/types/package.json b/packages/types/package.json
index c4637a4..4b4756e 100644
--- a/packages/types/package.json
+++ b/packages/types/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@device-router/types",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Core types, device classification, and rendering hint derivation for DeviceRouter",
   "license": "MIT",