madison-ai-labs
diff --git a/‎.github/workflows/publish.yml‎
Lines changed: 5 additions & 4 deletions b/‎.github/workflows/publish.yml‎
Lines changed: 5 additions & 4 deletions
diff --git a/‎CHANGELOG.md‎
Lines changed: 28 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 28 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 60 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 60 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 23 additions & 0 deletions b/‎README.md‎
Lines changed: 23 additions & 0 deletions
diff --git a/‎docs/api/middleware-express.md‎
Lines changed: 17 additions & 12 deletions b/‎docs/api/middleware-express.md‎
Lines changed: 17 additions & 12 deletions
diff --git a/‎docs/api/middleware-fastify.md‎
Lines changed: 17 additions & 12 deletions b/‎docs/api/middleware-fastify.md‎
Lines changed: 17 additions & 12 deletions
@@ -46,9 +46,10 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      - name: Extract release notes from changelog
+        id: release-notes
+        uses: ffurrer2/extract-release-notes@v3
+
       - uses: softprops/action-gh-release@v2
         with:
-          generate_release_notes: true
-          files: |
-            packages/probe/dist/device-router-probe.min.js
-            packages/probe/dist/device-router-probe.min.js.gz
+          body: ${{ steps.release-notes.outputs.release_notes }}
@@ -1,5 +1,33 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.0 (2026-02-23)
+
+### Breaking Changes
+
+- **userAgent and viewport stripped from stored profiles** — `userAgent` and `viewport` are no longer persisted in device profiles. They are still collected by the probe and used for bot/crawler filtering at the endpoint, but stripped before storage. Stored `RawSignals` no longer contain `userAgent` or `viewport` fields
+
+### Bug Fixes
+
+- **Redis error handling** — `RedisStorageAdapter` now catches connection failures and corrupted JSON on all methods. `get()`/`exists()` return safe defaults (`null`/`false`), `set()`/`delete()` silently degrade instead of throwing unhandled errors
+
+### Documentation
+
+- **Deployment guide** — New `docs/deployment.md` covering Docker (Node.js + Redis), Cloudflare Workers (Hono + KV), and serverless platforms (Lambda, Vercel). Includes Dockerfiles, docker-compose, custom StorageAdapter examples for edge runtimes, and production checklists
+- **Streaming injection limitation** — Documented that probe auto-injection requires a string response body; streaming responses are silently skipped (or buffered on Hono). Added framework-specific notes to all package READMEs and getting-started guide
+
+### Features
+
+- **Secure cookie option** — New `cookieSecure` option on all middleware packages sets the `Secure` flag on the session cookie. Set `cookieSecure: true` for HTTPS deployments
+- **Threshold validation** — `createDeviceRouter()` now validates custom thresholds at startup: rejects inverted bounds (e.g. `lowUpperBound >= midUpperBound`), non-positive values, and non-RegExp GPU patterns. Fails fast with descriptive errors instead of silently producing wrong classifications
+- **First-request fallback** — Opt-in strategies to provide a classified profile on the very first page load, before the probe has run
+- **Header-based classification** — `classifyFromHeaders: true` classifies devices from User-Agent and Client Hints headers (`Sec-CH-UA-Mobile`, `Device-Memory`, `Save-Data`), sets `Accept-CH` response header to request hints from Chromium browsers
+- **Fallback profiles** — `fallbackProfile` option accepts `'conservative'` (low-end defaults), `'optimistic'` (high-end defaults), or custom `DeviceTiers`
+- **Profile source tracking** — New `source` field on `ClassifiedProfile` indicates origin: `'probe'`, `'headers'`, or `'fallback'`
+- **Preset tier constants** — `CONSERVATIVE_TIERS` and `OPTIMISTIC_TIERS` exported from `@device-router/types`
+- **Bot/crawler filtering** — Probe endpoints reject bot submissions by default (`rejectBots: true`). New `isBotSignals()` detects bots via UA patterns, headless GPU renderers, and empty signal payloads
+
 ## 0.2.0 (2026-02-22)
 
 ### Features
 
@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+pnpm install             # Install dependencies (uses frozen lockfile in CI)
+pnpm build               # Build all packages (tsc -b per package, esbuild for probe bundle)
+pnpm test                # Run Vitest once with coverage
+pnpm test:watch          # Run Vitest in watch mode
+pnpm test:coverage       # Run tests with explicit coverage report
+pnpm lint                # ESLint check
+pnpm format              # Prettier write
+pnpm format:check        # Prettier check
+pnpm clean               # Remove all dist/ and build artifacts
+```
+
+To run a single test file:
+
+```bash
+pnpm vitest run packages/types/src/__tests__/classify.test.ts
+```
+
+## Architecture
+
+DeviceRouter is a pnpm monorepo that detects real device capabilities server-side and derives rendering hints. A tiny client probe collects browser signals, posts them to a middleware endpoint, and subsequent requests get a classified device profile attached.
+
+### Package dependency graph
+
+```
+@device-router/types        ← Core: types, classify(), deriveHints(), validation
+       ↑
+       ├── @device-router/probe     ← Client-side signal collection (~1 KB gzipped, enforced in CI)
+       ├── @device-router/storage   ← StorageAdapter interface + MemoryStorage / RedisStorage
+       └── middleware-{express,fastify,hono,koa}  ← Framework adapters (all depend on types + storage)
+```
+
+### Middleware packages follow an identical pattern
+
+Each middleware package exports a factory `createDeviceRouter(options)` that produces three pieces:
+
+1. **middleware** — reads session cookie → retrieves profile from storage → classifies + derives hints → attaches to request
+2. **endpoint** — `POST /device-router/probe` handler: validates payload, stores profile, sets cookie
+3. **inject** — intercepts HTML responses and injects the minified probe script before `</head>` (supports CSP nonce)
+
+### Key flows
+
+- `collectSignals()` (probe) → POST to endpoint → `isValidSignals()` + `classify()` + `deriveHints()` (types) → store via `StorageAdapter` → attach `ClassifiedProfile` to request on next hit
+
+## Code Conventions
+
+- **TypeScript:** ES2022 target, strict mode, Node16 module resolution, ESM throughout
+- **Unused params** must be prefixed with `_` (ESLint enforced)
+- **Prettier:** 100 char width, 2-space indent, single quotes, trailing commas, semicolons
+- **Tests:** Vitest, files in `src/__tests__/*.test.ts`, 80% coverage threshold (branches/functions/lines/statements)
+- **Probe size budget:** must be ≤ 1 KB gzipped (checked in CI via `packages/probe/scripts/bundle.js`)
+- **Node version:** ≥20 (.nvmrc: v20)
+- **Always run `pnpm format` before committing** — CI enforces `format:check` and will fail on unformatted code
+- **No author/co-author attribution** in commits, code, or docs
@@ -97,6 +97,8 @@ app.get('/', (req, res) => {
 
 All signals are optional — the probe gracefully degrades based on what the browser supports.
 
+> **Note:** The probe also collects `navigator.userAgent` and viewport dimensions for [bot/crawler filtering](docs/getting-started.md). They are used during probe submission and stripped before the profile is stored.
+
 ## Tier Classification
 
 Devices are classified across three dimensions:
@@ -136,6 +138,8 @@ const { middleware, probeEndpoint } = createDeviceRouter({
 });
 ```
 
+Thresholds are validated at startup — inverted bounds (e.g. `lowUpperBound >= midUpperBound`), non-positive values, and non-RegExp GPU patterns throw immediately.
+
 ## Probe Auto-Injection
 
 Automatically inject the probe script into HTML responses:
@@ -153,6 +157,24 @@ const { middleware, probeEndpoint, injectionMiddleware } = createDeviceRouter({
 
 No need to manually add `<script>` tags — the probe is injected before `</head>` in every HTML response.
 
+## First-Request Handling
+
+By default, `deviceProfile` is `null` on the first page load before the probe runs. Two opt-in strategies provide immediate classification:
+
+```typescript
+const { middleware, probeEndpoint } = createDeviceRouter({
+  storage,
+  // Option 1: Classify from User-Agent + Client Hints headers
+  classifyFromHeaders: true,
+  // Option 2: Fall back to preset defaults
+  fallbackProfile: 'conservative', // or 'optimistic' or custom DeviceTiers
+});
+```
+
+When `classifyFromHeaders` is enabled, mobile/tablet/desktop detection happens from the UA string, and Chromium Client Hints (`Device-Memory`, `Save-Data`) refine the result. Check `profile.source` to know the origin: `'probe'`, `'headers'`, or `'fallback'`.
+
+See [Getting Started — First-Request Handling](docs/getting-started.md#first-request-handling) for details.
+
 ## Packages
 
 | Package                                                               | Description                                           | Size              |
@@ -208,6 +230,7 @@ Open http://localhost:3000 — the probe runs on first load, refresh to see your
 ## Documentation
 
 - [Getting Started](docs/getting-started.md)
+- [Deployment Guide](docs/deployment.md) — Docker, Cloudflare Workers, serverless
 - [Profile Schema Reference](docs/profile-schema.md)
 - API Reference: [types](docs/api/types.md) | [probe](docs/api/probe.md) | [storage](docs/api/storage.md) | [express](docs/api/middleware-express.md) | [fastify](docs/api/middleware-fastify.md) | [hono](docs/api/middleware-hono.md) | [koa](docs/api/middleware-koa.md)
 
 
@@ -21,16 +21,20 @@ app.use(middleware);
 
 ### Options
 
-| Option        | Type                                   | Default                  | Description                                    |
-| ------------- | -------------------------------------- | ------------------------ | ---------------------------------------------- |
-| `storage`     | `StorageAdapter`                       | required                 | Storage backend                                |
-| `cookieName`  | `string`                               | `'dr_session'`           | Session cookie name                            |
-| `cookiePath`  | `string`                               | `'/'`                    | Cookie path                                    |
-| `ttl`         | `number`                               | `86400`                  | Profile TTL in seconds                         |
-| `thresholds`  | `TierThresholds`                       | built-in defaults        | Custom tier classification thresholds          |
-| `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          |
+| 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               |
 
 ### Returns
 
@@ -47,12 +51,13 @@ The middleware attaches a `ClassifiedProfile | null` to `req.deviceProfile`:
 ```typescript
 interface ClassifiedProfile {
   profile: DeviceProfile; // Raw profile with signals
-  tiers: DeviceTiers; // { cpu, memory, connection }
+  tiers: DeviceTiers; // { cpu, memory, connection, gpu }
   hints: RenderingHints; // { deferHeavyComponents, ... }
+  source: ProfileSource; // 'probe' | 'headers' | 'fallback'
 }
 ```
 
-`null` when no session cookie is present or profile has expired.
+`null` when no session cookie is present or profile has expired (unless `classifyFromHeaders` or `fallbackProfile` is configured).
 
 ## Probe Auto-Injection
 
 
@@ -23,16 +23,20 @@ await app.register(plugin, pluginOptions);
 
 ### Options
 
-| Option        | Type                                          | Default                  | Description                                    |
-| ------------- | --------------------------------------------- | ------------------------ | ---------------------------------------------- |
-| `storage`     | `StorageAdapter`                              | required                 | Storage backend                                |
-| `cookieName`  | `string`                                      | `'dr_session'`           | Session cookie name                            |
-| `cookiePath`  | `string`                                      | `'/'`                    | Cookie path                                    |
-| `ttl`         | `number`                                      | `86400`                  | Profile TTL in seconds                         |
-| `thresholds`  | `TierThresholds`                              | built-in defaults        | Custom tier classification thresholds          |
-| `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          |
+| 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               |
 
 ### Returns
 
@@ -50,12 +54,13 @@ The plugin attaches a `ClassifiedProfile | null` to `req.deviceProfile`:
 ```typescript
 interface ClassifiedProfile {
   profile: DeviceProfile; // Raw profile with signals
-  tiers: DeviceTiers; // { cpu, memory, connection }
+  tiers: DeviceTiers; // { cpu, memory, connection, gpu }
   hints: RenderingHints; // { deferHeavyComponents, ... }
+  source: ProfileSource; // 'probe' | 'headers' | 'fallback'
 }
 ```
 
-`null` when no session cookie is present or profile has expired.
+`null` when no session cookie is present or profile has expired (unless `classifyFromHeaders` or `fallbackProfile` is configured).
 
 ## Probe Auto-Injection