partial-content 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.0.1 (2026-07-06)
+
+Docs-only release, no code changes.
+
+- README restructured around evaluation flow: quick starts, comparison, and design summary up front.
+- Deep-dives moved into the shipped `docs/` folder: full API reference (`docs/API.md`), framework/kernel recipes (`docs/EXAMPLES.md`), and the complete benchmark methodology (`docs/BENCHMARKS.md`).
+- The npm tarball now includes the whole `docs/` folder (previously only `DESIGN.md`).
+
 ## 1.0.0 (2026-07-06)
 
 Initial public release. Zero-dependency, ESM-only HTTP file-serving protocol layer for any storage backend.

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/partial-content.svg)](https://www.npmjs.com/package/partial-content)
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/partial-content)
-[![tests](https://img.shields.io/badge/tests-703%20passed-brightgreen.svg)](https://www.npmjs.com/package/partial-content)
+[![ci](https://github.com/nordvec/partial-content/actions/workflows/ci.yml/badge.svg)](https://github.com/nordvec/partial-content/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6.svg)](https://www.typescriptlang.org/)
 
@@ -61,66 +61,28 @@ partial-content/memory       In-memory store (tests, demos, embedded assets)
 partial-content/mime         Curated zero-dep MIME lookup
 ```
 
-Cloud SDKs are **optional peer dependencies**:
-
-```bash
-# S3 users
-npm install partial-content @aws-sdk/client-s3
-# add @aws-sdk/s3-request-presigner only if you use createSignedUrl()
-
-# GCS users
-npm install partial-content @google-cloud/storage
-
-# Azure users
-npm install partial-content @azure/storage-blob
-
-# Filesystem or kernel only (zero extra deps)
-npm install partial-content
-```
+Cloud SDKs are **optional peer dependencies**: `@aws-sdk/client-s3` for `/s3` (plus `@aws-sdk/s3-request-presigner` only if you use `createSignedUrl()`), `@google-cloud/storage` for `/gcs`, `@azure/storage-blob` for `/azure`, `hono` for `/hono`. The kernel, `/web`, `/node`, `/fs`, `/http`, `/r2`, `/memory`, and `/mime` need nothing beyond the platform.
 
 ## Features
 
 - **One call does everything**: `evaluateConditionalRequest()` handles the complete evaluation chain (412 > 304 > If-Range > Range) in correct order
 - **Write-side OCC**: `evaluateConditionalWrite()` handles If-Match/If-None-Match for PUT/PATCH/DELETE with correct 412 semantics
 - **RFC 9530 Repr-Digest**: End-to-end integrity verification via `sha-256=:<base64>:` header, with `Want-Repr-Digest` negotiation -- first-class support that `send`, `sirv`, and the framework static middlewares lack
-- **Built-in storage adapters**: S3, R2 (native), GCS, Azure, local filesystem
-- **Built-in framework adapters**: Fetch API (Next.js/SvelteKit/Remix/Workers), Node.js (Express/Fastify/Koa), Hono
-- Range requests (206 Partial Content, 416 Range Not Satisfiable), including multi-range `multipart/byteranges` with overlapping/adjacent-range coalescing and range-amplification defense (`maxRanges`)
-- Conditional requests (304 Not Modified, 412 Precondition Failed) with sub-second timestamp flooring
+- **Built-in storage adapters**: S3-compatible (AWS, R2 S3-mode, Hetzner, MinIO, Backblaze, Wasabi), R2 native, GCS, Azure, local filesystem, any range-capable HTTP origin, in-memory
+- **Built-in framework adapters**: Fetch API (Next.js, SvelteKit, Remix, Nuxt, Astro, Workers, Bun.serve, Deno.serve), Node.js (Express/Fastify/Koa/raw http), Hono
+- Range requests (206, 416), including multi-range `multipart/byteranges` with overlapping/adjacent-range coalescing and range-amplification defense (`maxRanges`)
+- Conditional requests (304, 412) with sub-second timestamp flooring
 - ETag generation from storage metadata (strong for content hash, weak for size+mtime, safe undefined fallback)
 - Content-Disposition with non-ASCII filename encoding, CRLF injection prevention, path traversal protection, and bidi spoofing defense
 - Published `ObjectStore` interface for building custom storage adapters against a stable contract
-- Pure functions, zero I/O, zero dependencies; the hot path constructs no fetch primitives, no stream machinery for small bodies, and re-parses no dates (validators derive once at stat time)
+- Pure functions, zero I/O, zero dependencies; the hot path constructs no fetch primitives, no stream machinery for small bodies, and re-parses no dates
 - ESM-only. Works across Node.js 20+, Bun, Deno, Cloudflare Workers, and edge runtimes
 
-### Storage Adapters
-
-| Adapter | Backends | Extra Dependencies |
-|---------|----------|--------------------|
-| `partial-content/s3` | AWS S3, R2 (S3 mode), Hetzner, MinIO, Backblaze, Wasabi | `@aws-sdk/client-s3` |
-| `partial-content/r2` | Cloudflare R2 (native) | None (uses R2 bindings) |
-| `partial-content/gcs` | Google Cloud Storage | `@google-cloud/storage` |
-| `partial-content/azure` | Azure Blob Storage | `@azure/storage-blob` |
-| `partial-content/fs` | Local filesystem | None (Node.js builtins) |
-| `partial-content/http` | Supabase Storage, presigned URLs, CDNs, any range-capable HTTP origin | None (global fetch) |
-| `partial-content/memory` | In-memory objects (tests, demos, embedded assets) | None |
-
-### Framework Adapters
-
-| Adapter | Works With |
-|---------|------------|
-| `partial-content/web` | Next.js, SvelteKit, Remix, Nuxt 3, SolidStart, Astro, Fresh (Deno), Elysia (Bun), Cloudflare Workers, Bun.serve, Deno.serve, and any Fetch API runtime |
-| `partial-content/node` | Express, Fastify, Koa, NestJS, Angular SSR, raw `http.createServer` |
-| `partial-content/hono` | Hono (all runtimes) |
-| Kernel only | Anything. Pure functions, zero runtime assumptions. |
-
 ## Quick Start
 
-### High-Level: Built-in Adapters
+The handler manages the full HTTP protocol (200, 206, 304, 412, 416, HEAD) automatically: combine a storage adapter with a framework adapter.
 
-For most applications, combine a storage adapter with a framework adapter. The handler manages the full HTTP protocol (200, 206, 304, 412, 416, HEAD) automatically.
-
-#### Next.js / SvelteKit / Remix (Fetch API)
+### Next.js / SvelteKit / Remix (Fetch API)
 
 ```typescript
 import { serveObject } from "partial-content/web";
@@ -138,7 +100,7 @@ export async function GET(req: Request, { params }: { params: { id: string } })
 export const HEAD = GET;
 ```
 
-#### Express / Node.js
+### Express / Node.js
 
 ```typescript
 import express from "express";
@@ -156,42 +118,7 @@ app.get("/files/:key", serveObject(store, {
 }));
 ```
 
-#### Hono
-
-```typescript
-import { Hono } from "hono";
-import { serveObject } from "partial-content/hono";
-import { s3Store } from "partial-content/s3";
-
-const store = s3Store({ client, bucket: "media" });
-const app = new Hono();
-
-app.get("/media/:key", serveObject(store, {
-  key: (c) => c.req.param("key"),
-  cacheControl: "public, max-age=31536000, immutable",
-}));
-```
-
-#### Cloudflare Workers (R2 native, no AWS SDK)
-
-```typescript
-import { Hono } from "hono";
-import { serveObject } from "partial-content/hono";
-import { r2Store } from "partial-content/r2";
-
-const app = new Hono<{ Bindings: { MY_BUCKET: R2Bucket } }>();
-
-app.get("/files/:key", (c) => {
-  const store = r2Store({ bucket: c.env.MY_BUCKET });
-  return serveObject(store, { key: (c) => c.req.param("key") })(c);
-});
-```
-
-### Low-Level: Kernel Only
-
-For custom integrations, use the kernel primitives directly. You control the storage I/O, the kernel handles the protocol.
-
-#### One call does everything
+### Kernel only (bring your own I/O)
 
 ```typescript
 import { evaluateConditionalRequest } from "partial-content";
@@ -218,117 +145,7 @@ const { stream } = range
 return new Response(stream, { status, headers });
 ```
 
-```
-Request                        evaluateConditionalRequest()
-  │                                       │
-  │  If-Match / If-Unmodified-Since       ├──► 412 Precondition Failed
-  │  If-None-Match / If-Modified-Since    ├──► 304 Not Modified
-  │  If-Range + Range                     ├──► 416 Range Not Satisfiable
-  │                                       ├──► 206 Partial Content
-  │                                       └──► 200 OK
-  │
-  ▼
-Fetch bytes from storage (you control this)
-  │
-  ▼
-new Response(body, { status, headers })
-```
-
-#### Node.js / Express (kernel only)
-
-```typescript
-import { fromNodeHeaders, evaluateConditionalRequest } from "partial-content";
-
-app.get("/files/:key", (req, res) => {
-  const headers = fromNodeHeaders(req.headers);
-  const { status, headers: resHeaders, range } = evaluateConditionalRequest(
-    headers,
-    { totalSize: fileSize, etag, lastModified, contentType },
-  );
-  res.writeHead(status, resHeaders);
-  // ...
-});
-```
-
-### Content-Disposition
-
-```typescript
-import { buildContentDisposition } from "partial-content";
-
-buildContentDisposition("report.pdf");
-// => 'attachment; filename=report.pdf'
-
-buildContentDisposition("Årlig_Rapport.pdf");
-// => 'attachment; filename="?rlig_Rapport.pdf"; filename*=UTF-8''%C3%85rlig_Rapport.pdf'
-
-buildContentDisposition("slides.pdf", { type: "inline" });
-// => 'inline; filename=slides.pdf'
-
-// Handles untrusted input safely
-buildContentDisposition("../../etc/passwd");        // Path traversal stripped
-buildContentDisposition("evil\r\nX-Injected: yes"); // CRLF injection stripped
-buildContentDisposition(null, { fallback: "export.csv" }); // Graceful fallback
-```
-
-### RFC 9530 Repr-Digest (End-to-End Integrity)
-
-Pass a SHA-256 digest from your storage backend for automatic `Repr-Digest` headers:
-
-```typescript
-const { status, headers, range } = evaluateConditionalRequest(
-  request.headers,
-  {
-    totalSize: fileSize,
-    etag: '"abc123"',
-    // S3: x-amz-checksum-sha256, GCS: x-goog-hash (sha256 component)
-    digest: "d2VsY29tZQ==",  // raw base64 SHA-256
-  },
-);
-// Response headers include: Repr-Digest: sha-256=:d2VsY29tZQ==:
-// Same digest on both 200 (full) and 206 (partial) -- covers the full representation
-```
-
-### Advanced: Manual Primitives
-
-For full control over the evaluation chain:
-
-```typescript
-import {
-  parseRangeHeader,
-  buildRangeResponseHeaders,
-  isConditionalFresh,
-  isPreconditionFailure,
-  isRangeFresh,
-  build304Headers,
-  build412Headers,
-  build416Headers,
-} from "partial-content";
-
-// Step 1: Preconditions (If-Match / If-Unmodified-Since)
-if (isPreconditionFailure(reqHeaders, etag, lastModified)) {
-  return new Response(null, build412Headers());
-}
-
-// Step 2: Freshness (If-None-Match / If-Modified-Since)
-if (isConditionalFresh(reqHeaders, etag, lastModified)) {
-  return new Response(null, build304Headers(etag, lastModified));
-}
-
-// Step 3: Range (If-Range + Range header)
-const range = isRangeFresh(reqHeaders, etag, lastModified)
-  ? parseRangeHeader(reqHeaders.get("range"), fileSize)
-  : null;
-
-if (range === "unsatisfiable") {
-  return new Response(null, build416Headers(fileSize));
-}
-
-const { status, headers } = buildRangeResponseHeaders({
-  totalSize: fileSize, range, contentType, etag, lastModified,
-  digest: checksum,          // RFC 9530 Repr-Digest
-  cacheControl: "private, no-cache",
-});
-```
+More recipes in **[docs/EXAMPLES.md](docs/EXAMPLES.md)**: Hono, Cloudflare Workers (R2 native), kernel-only Express, Content-Disposition, Repr-Digest, and the manual step-by-step primitives.
 
 ## Real-world example: authorized proxy from object storage
 
@@ -372,149 +189,34 @@ async function serveFile(request: Request, key: string) {
 
 This is the path behind `<video>`/`<audio>` seeking and PDF.js progressive loading: the media element sends `Range` to **your** origin, you re-check access, and stream just that slice from storage. If you could hand the client a signed URL instead, the storage backend would speak this protocol for you and you wouldn't need a protocol layer -- see [Scope](docs/DESIGN.md#scope) for when this library earns its place.
 
-## API Reference
-
-### Kernel (`partial-content`)
-
-**`evaluateConditionalRequest(reqHeaders, meta)`** - One-call handler for the full HTTP evaluation chain (GET/HEAD). Returns `{ status, headers, range }`.
-
-**`evaluateConditionalWrite(reqHeaders, meta)`** - One-call handler for write requests (PUT/PATCH/DELETE). Returns `{ proceed: true }` or `{ proceed: false, status: 412, headers }`. The 412 response includes the current `ETag` when available, so the client can resync without a follow-up GET.
-
-**`parseRangeHeader(rangeHeader, totalSize)`** - Returns `{ start, end }`, `"unsatisfiable"`, or `null`.
-
-**`buildRangeResponseHeaders(opts)`** - Build 200 or 206 response headers.
-
-**`parseContentRange(header)`** - Parse a `Content-Range` response header (e.g. `bytes 0-499/1000`). Returns `{ start, end, totalSize }` or `null`.
-
-**`generateETag(source)`** - Derive an entity-tag from storage metadata. Returns a strong `"<hash>"` when a content digest is available, a weak `W/"<size>-<mtime>"` when only size and modification time are known, or `undefined` when there is insufficient metadata.
-
-**`buildContentDisposition(filename, options?)`** - Security-hardened `Content-Disposition` header builder with CRLF injection prevention, path traversal protection, bidi override stripping, and RFC 8187 non-ASCII encoding.
-
-**`fromNodeHeaders(headers)`** - Convert Node.js `IncomingHttpHeaders` to the `{ get(name) }` interface.
-
-**`isConditionalFresh(reqHeaders, etag, lastModified)`** - `true` if not modified (304).
-
-**`isPreconditionFailure(reqHeaders, etag, lastModified, exists?)`** - `true` if precondition failed (412). Pass `exists` when the resource's presence is known independently of its validators (e.g. `If-Match: *` upload guards).
-
-**`isRangeFresh(reqHeaders, etag, lastModified)`** - `true` if If-Range passes (honor the range).
-
-**`build304Headers(etag, lastModified, cacheControl?)`** - Build 304 headers.
-
-**`build412Headers()`** - Build 412 headers.
-
-**`build416Headers(totalSize)`** - Build 416 Range Not Satisfiable headers.
-
-**`clientWantsDigest(reqHeaders)`** - RFC 9530 Section 4 negotiation: `true` when the client's `Want-Repr-Digest` / `Want-Content-Digest` headers accept `sha-256` (or are absent). The web adapter and orchestrator both honor this, so `Want-Repr-Digest: sha-256=0` suppresses digest emission everywhere.
-
-### MIME Lookup (`partial-content/mime`)
-
-**`lookupMime(filenameOrExt)`** - Curated, zero-dependency extension -> MIME lookup for documents, media, archives, fonts, and web assets. Case-insensitive, resolves the last dot segment (`archive.tar.gz` -> `application/gzip`), returns `undefined` for unknown types so the caller controls the fallback. `html` is deliberately absent: serving stored uploads as `text/html` is stored XSS, so that decision must be explicit at the call site.
-
-```typescript
-import { lookupMime } from "partial-content/mime";
-
-app.get("/files/:key", serveObject(store, {
-  key: (req) => req.params.key,
-  mime: (req) => lookupMime(req.params.key),
-}));
-```
-
-### Universal HTTP Store (`partial-content/http`)
-
-**`httpStore({ url, headers?, fetch?, redirect? })`** - Serve from ANY range-capable HTTP origin over plain `fetch`: Supabase Storage, presigned S3/GCS/Azure URLs, CDN origins, or another partial-content server. Pinned reads map to `If-Match` (origin 412 -> `ObjectChangedError`), `Repr-Digest` response headers are extracted, and requests are sent `Accept-Encoding: identity` and any response that still carries a non-identity `Content-Encoding` is refused, so transparent compression can never corrupt byte accounting. Redirects error by default (a hostile origin must not 3xx the store toward internal/metadata IPs); set `redirect: "follow"` for origins that legitimately redirect, paired with a validating `fetch` when keys are untrusted (see SECURITY.md).
-
-```typescript
-import { httpStore } from "partial-content/http";
-
-const store = httpStore({
-  url: (key) => `${SUPABASE_URL}/storage/v1/object/documents/${key}`,
-  headers: { Authorization: `Bearer ${serviceRoleKey}` },
-});
-```
-
-### Memory Store (`partial-content/memory`)
-
-**`memoryStore({ objects })`** - A spec-faithful in-memory store for consumer test suites, demos, and small embedded assets. Fabricates correct Content-Range values, honors `ifMatch` pinning (mutate the map to simulate overwrites and exercise retry logic), and streams zero-byte objects correctly.
-
-### Web Adapter (`partial-content/web`)
-
-**`serveObject(store, options?)`** - Create a Fetch API handler that serves files from an ObjectStore. Returns `(req: Request, ctx: ServeContext) => Promise<Response>`.
-
-**`serveObjectRaw(store, options?)`** - The same engine returning `RawResponseParts` (`{ status, statusText, headers, body }`) instead of a `Response`, for server adapters that write to their runtime natively (the bundled node adapter uses it). Skips all fetch-primitive construction on the hot path.
-
-Options: `disposition`, `cacheControl`, `immutable`, `securityHeaders`, `crossOriginResourcePolicy`, `timingAllowOrigin`, `timing`, `onTiming`, `onError`, `onServe`, `onTransfer`, `maxRanges`, `enforceCharset`, `fallbackFilename`.
-
-### Node Adapter (`partial-content/node`)
-
-**`serveObject(store, options)`** - Create a Node.js `(req, res) => Promise<void>` handler for Express, Fastify (compat), Koa, and raw `http.createServer`. Extends the web adapter options with `key` (required, extracts the storage key from `IncomingMessage`), `mime?`, and `filename?`.
-
-**`writeStallTimeoutMs?`** (default `60000`) - Bounds how long the streaming pump waits for a single backpressure `drain` before treating the client as stalled and tearing the transfer down (cancel the storage read, destroy the response). A client that stops reading but holds its socket open would otherwise pin a backend storage connection indefinitely (a slow-read attack). Set to `0` to disable and rely on an upstream proxy / socket timeout instead. Only the raw-Node pump needs this; Fetch-runtime backpressure is the platform's own concern.
+## API
 
-`ServeContext`: `key` (required), `mime?`, `filename?`, `cacheControl?` (per-request override of the handler-level value, e.g. `immutable` for content-addressed keys next to `private, no-cache` user uploads from the same handler).
+The full reference lives in **[docs/API.md](docs/API.md)**. The shape of the surface:
 
-`cacheControl` is emitted verbatim on 200/206/304, so any directive vocabulary your CDN or edge understands passes straight through: RFC 9111 `s-maxage` / `must-revalidate` / `proxy-revalidate` and the RFC 5861 resilience directives `stale-while-revalidate` and `stale-if-error`. The library does not synthesize or reorder directives (only appending `immutable` when the `immutable` option is set and it is not already present), so you keep full control of the response caching policy. `Vary` (e.g. `Vary: Accept-Encoding`) rides `securityHeaders` / `extraHeaders`.
-
-### Storage Contract
-
-**`ObjectStore`** (interface) - Read-only storage backend abstraction. Implementations provide `headObject(key, opts?)` for metadata and `getObject(key, opts?)` for streaming, where `opts` carries `range`, `signal`, `ifMatch` (pinned reads), and `pin` (an opaque token issued by `headObject` for stores whose version identifier is not the ETag; GCS uses it to stream a pinned generation without re-fetching metadata). Optional `createSignedUrl(key, opts)` for backends that cannot stream ranges through the origin. Optional `authoritativeRange: true` declares that ranged responses report the backend's ACTUAL served bounds (parsed Content-Range) -- the web adapter then serves plain range requests in a single round-trip with no validating HEAD (S3, Azure, R2, and http set it; video seeking and PDF.js chunking hit this path constantly).
-
-**`ObjectMetadata`** (type) - HEAD response shape: `contentLength`, `etag?`, `lastModified?`, `digest?`.
-
-**`ObjectStream`** (type) - GET response shape: `body` (a `ReadableStream`, or a plain `Uint8Array` when the adapter already holds the exact bytes -- consumers then skip stream machinery entirely), `contentLength`, `totalSize`, `range?` (the `{ start, end }` the backend ACTUALLY served; absent = full content), `etag?`, `lastModified?`, `digest?`.
-
-**`classifyStoreRead(key, op, classifiers)`** - The ordered error-classification pipeline the built-in SDK adapters share, exported for custom adapter authors. Runs `op()` and maps its failure to the contract's error types in a fixed precedence: `notFound` -> `ObjectNotFoundError` (404), `changed` -> `ObjectChangedError` (412), `throttled` -> `StoreUnavailableError` (503), otherwise rethrow untouched. Supply one `StoreErrorClassifiers` set and reuse it for both `headObject` and `getObject` so the two paths cannot drift; predicates must be mutually exclusive on a given backend.
-
-```typescript
-import { classifyStoreRead, type StoreErrorClassifiers } from "partial-content";
-
-const classifiers: StoreErrorClassifiers = {
-  notFound: (e) => (e as { statusCode?: number }).statusCode === 404,
-  changed: (e) => (e as { statusCode?: number }).statusCode === 412,   // omit if the pin is an etag compare
-  throttled: (e) => (e as { statusCode?: number }).statusCode === 503,
-};
-
-const meta = await classifyStoreRead(key, () => backend.head(key), classifiers);
-```
-
-**`StoreUnavailableError`** (class) - Throw from an adapter when the backend is transiently unavailable (throttled/overloaded after the adapter's own retries). Carries an optional `retryAfterSeconds` echoed as `Retry-After`. Distinct from a malformed-response `502`: this is the retryable `503` case.
+- **Kernel** (`partial-content`): `evaluateConditionalRequest` / `evaluateConditionalWrite` (the one-call orchestrators), the step-by-step primitives (`parseRangeHeader`, `parseRanges`, `isConditionalFresh`, `isPreconditionFailure`, `isRangeFresh`, the `build*Headers` family), `generateETag`, `buildContentDisposition`, `clientWantsDigest`, `fromNodeHeaders`, `sanitizeHeaderValue`
+- **Serving** (`/web`, `/node`, `/hono`): `serveObject` handlers with `disposition`, `cacheControl` (verbatim passthrough), security headers, `onServe` / `onTransfer` / `onError` / `onTiming` observability hooks, `maxRanges`, and a slow-read stall bound on the Node pump
+- **Stores** (`/s3`, `/r2`, `/gcs`, `/azure`, `/fs`, `/http`, `/memory`): ready-made `ObjectStore` implementations with pinned reads and truthful error mapping (404 / retryable 503 + `Retry-After` / 502)
+- **Custom adapters**: the published `ObjectStore` contract plus the primitives the built-ins are made of (`classifyStoreRead`, `nodeStreamToWeb`, `guardStreamLength`, `resolveServedRange`)
 
 ## Design Decisions
 
-**Multi-range is served as `multipart/byteranges`.** Overlapping and adjacent ranges are coalesced, and a range-amplification defense (`maxRanges`, default 50; plus a "ranges cover the whole file" check) degrades pathological requests to a full 200. The single-range fast path is untouched. See DESIGN.md for the framing and the eager-first-part re-validation.
+**Multi-range is served as `multipart/byteranges`.** Overlapping and adjacent ranges are coalesced, and a range-amplification defense (`maxRanges`, default 50; plus a "ranges cover the whole file" check) degrades pathological requests to a full 200. The single-range fast path is untouched.
 
 **Weak ETag matching.** Storage providers (S3, R2, GCS) emit `W/` prefixes inconsistently. We strip `W/` for pragmatic matching to avoid false 412s.
 
 **Sub-second timestamp flooring.** Storage backends return ISO-8601 with milliseconds. HTTP dates use whole seconds. All comparisons floor both sides to prevent permanent false-stale results.
 
-**Atomic pinned reads (TOCTOU elimination).** After validating conditionals against HEAD metadata, the web adapter pins the GET to that exact representation via the store's native conditional read (S3 `IfMatch`, R2 `onlyIf.etagMatches`, Azure `conditions.ifMatch`, GCS generation pinning). If the object changes in the HEAD->GET window, the store throws `ObjectChangedError` and the request is re-validated once against the new state -- a stale `If-Range` then correctly yields a full 200 of the new bytes. For stores that cannot pin, a response-side guard remains: validators come from the GET response, the emitted 206 bounds come from the backend's actual Content-Range, and a missing Content-Range degrades to 200 (never a lying 206).
+**Atomic pinned reads (TOCTOU elimination).** After validating conditionals against HEAD metadata, the web adapter pins the GET to that exact representation via the store's native conditional read (S3 `IfMatch`, R2 `onlyIf.etagMatches`, Azure `conditions.ifMatch`, GCS generation pinning). If the object changes in the HEAD->GET window, the store throws `ObjectChangedError` and the request is re-validated once against the new state. For stores that cannot pin, a response-side guard remains: validators come from the GET response, the emitted 206 bounds come from the backend's actual Content-Range, and a missing Content-Range degrades to 200 (never a lying 206).
 
-**Single-round-trip range serving.** Plain range requests (no conditionals, no `If-Range`) skip the HEAD entirely on `authoritativeRange` stores: one GET, with validators and bounds taken from the response itself -- inherently TOCTOU-atomic, and half the latency on media seeks. Backend-rejected ranges self-heal through the validating HEAD path, which emits the correct 416.
+**Single-round-trip range serving.** Plain range requests (no conditionals, no `If-Range`) skip the HEAD entirely on `authoritativeRange` stores: one GET, with validators and bounds taken from the response itself -- inherently TOCTOU-atomic, and half the latency on media seeks.
 
-**Store failures map to the truthful status.** A missing object (the store throws `ObjectNotFoundError`, or an error with `status: 404`) becomes a `404`. A transiently unavailable backend -- throttling or overload after the adapter's own retries are exhausted -- is a distinct, retryable case: throw `StoreUnavailableError` (or an error with `status: 503`) and the web adapter emits `503 Service Unavailable`, echoing its optional `retryAfterSeconds` as a `Retry-After` header so clients and shared caches back off. Everything else -- a malformed response, an unparseable `Content-Range`, an empty body -- is a `502 Bad Gateway`. The bundled `/s3`, `/gcs`, `/azure`, and `/http` adapters classify `503 SlowDown` / `429 TooManyRequests` / SDK throttle signals into `StoreUnavailableError` automatically; the `/azure` and `/http` adapters additionally surface the backend's `Retry-After` when it sends one. Every error response carries `Cache-Control: no-store`, `nosniff`, and a `default-src 'none'` CSP; the `404`/`502`/`503` bodies also set `Accept-Ranges: none`, while a `416` keeps its RFC-mandated `Accept-Ranges: bytes` and `Content-Range`.
+**Store failures map to the truthful status.** Missing object -> `404`. Transiently unavailable backend (throttling/overload) -> `503` + `Retry-After` (`StoreUnavailableError`). Malformed upstream response -> `502`. Every error response carries `Cache-Control: no-store`, `nosniff`, and a `default-src 'none'` CSP.
 
 See [docs/DESIGN.md](docs/DESIGN.md) for full RFC deviation notes, response header matrix, and parsing details.
 
 ## Benchmarks
 
-Representative throughput measured on Bun 1.3 (single core, 2M iterations). Benchmarks measure library overhead only -- they do not include network or storage latency.
-
-| Function | Throughput |
-|----------|-----------|
-| `parseRangeHeader` | 10.1M ops/sec |
-| `isPreconditionFailure` | 10.2M ops/sec |
-| `isRangeFresh` | 13.9M ops/sec |
-| `isConditionalFresh` | 4.7M ops/sec |
-| `buildRangeResponseHeaders` | 4.2M ops/sec |
-| `evaluateConditionalRequest` | 1.7M ops/sec |
-| `buildContentDisposition` | 1.7M ops/sec |
-
-### End-to-end vs `send` and `sirv`
-
-Full HTTP serving (Node 24, `http.createServer`, loopback, 40 connections,
-autocannon, identical fixtures; every cell correctness-verified before
-timing; the load generator runs in a separate process so its parse cost
-never throttles the server column). partial-content runs its shipped dist
-through the node adapter + fsStore. Reproduce with `npm run bench`.
+Full HTTP serving vs `send` and `sirv` (Node 24, loopback, out-of-process autocannon, every cell correctness-verified before timing; reproduce with `npm run bench`):
 
 | Scenario | partial-content | + `cache` | send | sirv |
 |---|---|---|---|---|
@@ -523,55 +225,11 @@ through the node adapter + fsStore. Reproduce with `npm run bench`.
 | Range 64 KB of 1 MB (206) | 1,441 req/s | 1,413 req/s | 1,403 req/s | 1,443 req/s |
 | Revalidation (304) | 11,716 req/s | **19,542 req/s** | 10,081 req/s | 23,774 req/s* |
 
-The `cache` column is `fsStore({ root, cache: { ttlMs: 1000 } })`: an opt-in
-hot-object cache with nginx `open_file_cache` semantics (TTL revalidation,
-metadata + bytes captured atomically, bodies only at or below 128 KiB,
-LRU-evicted under both an entry cap (`maxEntries`, default 1024) and a body
-byte budget (`maxBytes`, default 64 MiB; `0` = metadata-only)). Hot small
-files and their ranges serve from memory with zero syscalls. The trade is explicit: after an overwrite, responses (including
-304 revalidations) can affirm the previous representation for up to
-`ttlMs`; size it against acceptable staleness (see DESIGN.md).
-
-\* sirv's 304 figure buys throughput with a different contract: at
-`dev: false` it pre-renders complete header sets for a directory snapshot
-taken at boot, so a file created after startup is a 404. In the
-configuration that CAN see runtime-created files (`dev: true`), the same
-run measures sirv at 4,957 req/s -- a quarter of the `cache` column. For a
-fixed directory of immutable assets sirv's trade is exactly right; for
-object storage (where uploads happen while the server runs) it is
-disqualifying, which is why the boot-snapshot design stays a non-goal here.
-On the rows where server code matters (4 KB bodies, revalidations), the
-`cache` column is the fastest contender that can serve a file uploaded a
-second ago; at 64 KB and above, all four columns converge on I/O parity.
-
-Same code on Bun 1.3 (`Bun.serve`, same machine, same out-of-process
-client -- the web adapter's Request/Response ARE the runtime's native
-primitives there, no node bridge): GET 4 KB 9,418 req/s plain and
-22,898 req/s with the cache; revalidation 12,538 plain and **38,090 req/s**
-with the cache -- a TTL-revalidating cache serving runtime uploads,
-outrunning even sirv's boot-frozen Node figure by 60%. `send` and `sirv`
-are node-stream libraries and cannot ride `Bun.serve` natively. Reproduce:
-`bun bench/bun-server.ts` (plain :18778, cache :18779) + autocannon.
-
-Read this fairly in both directions:
-
-- At payload sizes where file serving actually spends its time (>= 64 KB),
-  the contenders are at parity: I/O dominates.
-- Small-body transfers and revalidations lead `send` and `sirv` even
-  without the cache, while doing strictly more per request: RFC 9530
-  digest negotiation, audit hooks, pinned-read plumbing, and storage
-  abstraction. Four things make that possible: transfers at or below
-  128 KiB take a single positional-read fast path in the fs store, small
-  bodies travel as plain bytes (no stream machinery), the node adapter
-  consumes `serveObjectRaw` (zero fetch primitives constructed on the Node
-  hot path), and validators are derived once at stat time instead of
-  re-parsing dates on every request.
-- Correctness note found while building this benchmark: `send` honors a
-  request `Cache-Control: no-cache` during conditional evaluation, and
-  spec-compliant fetch clients (undici, browsers) auto-append exactly that
-  header to manually-conditional requests -- so `send` never answers 304 to
-  a fetch()-based revalidation. partial-content deliberately ignores request
-  cache directives here (matching Go stdlib and nginx; see DESIGN.md).
+- At payload sizes where file serving actually spends its time (>= 64 KB), all contenders converge on I/O parity.
+- Small bodies and revalidations lead `send` and `sirv` even without the cache, while doing strictly more per request (digest negotiation, audit hooks, pinned-read plumbing, storage abstraction).
+- The `cache` column is the opt-in fs hot-object cache (nginx `open_file_cache` semantics: TTL revalidation, `maxEntries` + `maxBytes` LRU bounds). \* sirv's 304 figure comes from a boot-time directory snapshot that 404s files created after startup; in the mode that can serve runtime uploads it measures 4,957 req/s.
+
+Kernel micro-benchmarks, the Bun.serve numbers (38k req/s revalidation with cache), and the full fairness notes are in **[docs/BENCHMARKS.md](docs/BENCHMARKS.md)**.
 
 ## Security & Compliance
 

package/docs/API.md

@@ -0,0 +1,115 @@
+# API Reference
+
+The complete export surface. Everything is typed; your editor's IntelliSense mirrors this page.
+
+## Kernel (`partial-content`)
+
+**`evaluateConditionalRequest(reqHeaders, meta)`** - One-call handler for the full HTTP evaluation chain (GET/HEAD). Returns `{ status, headers, range }`.
+
+**`evaluateConditionalWrite(reqHeaders, meta)`** - One-call handler for write requests (PUT/PATCH/DELETE). Returns `{ proceed: true }` or `{ proceed: false, status: 412, headers }`. The 412 response includes the current `ETag` when available, so the client can resync without a follow-up GET.
+
+**`parseRangeHeader(rangeHeader, totalSize)`** - Returns `{ start, end }`, `"unsatisfiable"`, or `null`.
+
+**`parseRanges(rangeHeader, totalSize, maxRanges?)`** - Multi-range parsing for `multipart/byteranges`: coalesces overlapping/adjacent ranges and applies range-amplification defenses. Returns a `RangeSet`, `"unsatisfiable"`, or `null` (serve the full 200).
+
+**`buildRangeResponseHeaders(opts)`** - Build 200 or 206 response headers.
+
+**`buildMultipartHeaders(opts)` / `buildMultipartPartHeader(...)` / `multipartEpilogue(boundary)` / `generateMultipartBoundary()`** - The `multipart/byteranges` framing primitives with exact precomputed Content-Length (never chunked).
+
+**`parseContentRange(header)`** - Parse a `Content-Range` response header (e.g. `bytes 0-499/1000`). Returns `{ start, end, totalSize }` or `null`.
+
+**`generateETag(source)`** - Derive an entity-tag from storage metadata. Returns a strong `"<hash>"` when a content digest is available, a weak `W/"<size>-<mtime>"` when only size and modification time are known, or `undefined` when there is insufficient metadata.
+
+**`buildContentDisposition(filename, options?)`** - Security-hardened `Content-Disposition` header builder with CRLF injection prevention, path traversal protection, bidi override stripping, and RFC 8187 non-ASCII encoding.
+
+**`fromNodeHeaders(headers)`** - Convert Node.js `IncomingHttpHeaders` to the `{ get(name) }` interface.
+
+**`isConditionalFresh(reqHeaders, etag, lastModified)`** - `true` if not modified (304).
+
+**`isPreconditionFailure(reqHeaders, etag, lastModified, exists?)`** - `true` if precondition failed (412). Pass `exists` when the resource's presence is known independently of its validators (e.g. `If-Match: *` upload guards).
+
+**`isRangeFresh(reqHeaders, etag, lastModified)`** - `true` if If-Range passes (honor the range).
+
+**`build304Headers(etag, lastModified, cacheControl?)`** - Build 304 headers.
+
+**`build412Headers()`** - Build 412 headers.
+
+**`build416Headers(totalSize)`** - Build 416 Range Not Satisfiable headers.
+
+**`clientWantsDigest(reqHeaders)`** - RFC 9530 Section 4 negotiation: `true` when the client's `Want-Repr-Digest` / `Want-Content-Digest` headers accept `sha-256` (or are absent). The web adapter and orchestrator both honor this, so `Want-Repr-Digest: sha-256=0` suppresses digest emission everywhere.
+
+**`sanitizeHeaderValue(s)`** - Strip every byte outside RFC 9110 field-value grammar. The kernel applies it to all metadata-derived headers; exported so adapters can sanitize headers they build themselves.
+
+## MIME Lookup (`partial-content/mime`)
+
+**`lookupMime(filenameOrExt)`** - Curated, zero-dependency extension -> MIME lookup for documents, media, archives, fonts, and web assets. Case-insensitive, resolves the last dot segment (`archive.tar.gz` -> `application/gzip`), returns `undefined` for unknown types so the caller controls the fallback. `html` is deliberately absent: serving stored uploads as `text/html` is stored XSS, so that decision must be explicit at the call site.
+
+```typescript
+import { lookupMime } from "partial-content/mime";
+
+app.get("/files/:key", serveObject(store, {
+  key: (req) => req.params.key,
+  mime: (req) => lookupMime(req.params.key),
+}));
+```
+
+## Universal HTTP Store (`partial-content/http`)
+
+**`httpStore({ url, headers?, fetch?, redirect? })`** - Serve from ANY range-capable HTTP origin over plain `fetch`: Supabase Storage, presigned S3/GCS/Azure URLs, CDN origins, or another partial-content server. Pinned reads map to `If-Match` (origin 412 -> `ObjectChangedError`), `Repr-Digest` response headers are extracted, and requests are sent `Accept-Encoding: identity` and any response that still carries a non-identity `Content-Encoding` is refused, so transparent compression can never corrupt byte accounting. Redirects error by default (a hostile origin must not 3xx the store toward internal/metadata IPs); set `redirect: "follow"` for origins that legitimately redirect, paired with a validating `fetch` when keys are untrusted (see SECURITY.md).
+
+```typescript
+import { httpStore } from "partial-content/http";
+
+const store = httpStore({
+  url: (key) => `${SUPABASE_URL}/storage/v1/object/documents/${key}`,
+  headers: { Authorization: `Bearer ${serviceRoleKey}` },
+});
+```
+
+## Memory Store (`partial-content/memory`)
+
+**`memoryStore({ objects })`** - A spec-faithful in-memory store for consumer test suites, demos, and small embedded assets. Fabricates correct Content-Range values, honors `ifMatch` pinning (mutate the map to simulate overwrites and exercise retry logic), and streams zero-byte objects correctly.
+
+## Web Adapter (`partial-content/web`)
+
+**`serveObject(store, options?)`** - Create a Fetch API handler that serves files from an ObjectStore. Returns `(req: Request, ctx: ServeContext) => Promise<Response>`.
+
+**`serveObjectRaw(store, options?)`** - The same engine returning `RawResponseParts` (`{ status, statusText, headers, body }`) instead of a `Response`, for server adapters that write to their runtime natively (the bundled node adapter uses it). Skips all fetch-primitive construction on the hot path.
+
+Options: `disposition`, `cacheControl`, `immutable`, `securityHeaders`, `crossOriginResourcePolicy`, `timingAllowOrigin`, `timing`, `onTiming`, `onError`, `onServe`, `onTransfer`, `maxRanges`, `enforceCharset`, `fallbackFilename`.
+
+`ServeContext`: `key` (required), `mime?`, `filename?`, `cacheControl?` (per-request override of the handler-level value, e.g. `immutable` for content-addressed keys next to `private, no-cache` user uploads from the same handler).
+
+`cacheControl` is emitted verbatim on 200/206/304, so any directive vocabulary your CDN or edge understands passes straight through: RFC 9111 `s-maxage` / `must-revalidate` / `proxy-revalidate` and the RFC 5861 resilience directives `stale-while-revalidate` and `stale-if-error`. The library does not synthesize or reorder directives (only appending `immutable` when the `immutable` option is set and it is not already present), so you keep full control of the response caching policy. `Vary` (e.g. `Vary: Accept-Encoding`) rides `securityHeaders` / `extraHeaders`.
+
+## Node Adapter (`partial-content/node`)
+
+**`serveObject(store, options)`** - Create a Node.js `(req, res) => Promise<void>` handler for Express, Fastify (compat), Koa, and raw `http.createServer`. Extends the web adapter options with `key` (required, extracts the storage key from `IncomingMessage`), `mime?`, and `filename?`.
+
+**`writeStallTimeoutMs?`** (default `60000`) - Bounds how long the streaming pump waits for a single backpressure `drain` before treating the client as stalled and tearing the transfer down (cancel the storage read, destroy the response). A client that stops reading but holds its socket open would otherwise pin a backend storage connection indefinitely (a slow-read attack). Set to `0` to disable and rely on an upstream proxy / socket timeout instead. Only the raw-Node pump needs this; Fetch-runtime backpressure is the platform's own concern.
+
+## Storage Contract
+
+**`ObjectStore`** (interface) - Read-only storage backend abstraction. Implementations provide `headObject(key, opts?)` for metadata and `getObject(key, opts?)` for streaming, where `opts` carries `range`, `signal`, `ifMatch` (pinned reads), and `pin` (an opaque token issued by `headObject` for stores whose version identifier is not the ETag; GCS uses it to stream a pinned generation without re-fetching metadata). Optional `createSignedUrl(key, opts)` for backends that cannot stream ranges through the origin. Optional `authoritativeRange: true` declares that ranged responses report the backend's ACTUAL served bounds (parsed Content-Range) -- the web adapter then serves plain range requests in a single round-trip with no validating HEAD (S3, Azure, R2, and http set it; video seeking and PDF.js chunking hit this path constantly).
+
+**`ObjectMetadata`** (type) - HEAD response shape: `contentLength`, `etag?`, `lastModified?`, `digest?`.
+
+**`ObjectStream`** (type) - GET response shape: `body` (a `ReadableStream`, or a plain `Uint8Array` when the adapter already holds the exact bytes -- consumers then skip stream machinery entirely), `contentLength`, `totalSize`, `range?` (the `{ start, end }` the backend ACTUALLY served; absent = full content), `etag?`, `lastModified?`, `digest?`.
+
+**`classifyStoreRead(key, op, classifiers)`** - The ordered error-classification pipeline the built-in SDK adapters share, exported for custom adapter authors. Runs `op()` and maps its failure to the contract's error types in a fixed precedence: `notFound` -> `ObjectNotFoundError` (404), `changed` -> `ObjectChangedError` (412), `throttled` -> `StoreUnavailableError` (503), otherwise rethrow untouched. Supply one `StoreErrorClassifiers` set and reuse it for both `headObject` and `getObject` so the two paths cannot drift; predicates must be mutually exclusive on a given backend.
+
+```typescript
+import { classifyStoreRead, type StoreErrorClassifiers } from "partial-content";
+
+const classifiers: StoreErrorClassifiers = {
+  notFound: (e) => (e as { statusCode?: number }).statusCode === 404,
+  changed: (e) => (e as { statusCode?: number }).statusCode === 412,   // omit if the pin is an etag compare
+  throttled: (e) => (e as { statusCode?: number }).statusCode === 503,
+};
+
+const meta = await classifyStoreRead(key, () => backend.head(key), classifiers);
+```
+
+**`StoreUnavailableError`** (class) - Throw from an adapter when the backend is transiently unavailable (throttled/overloaded after the adapter's own retries). Carries an optional `retryAfterSeconds` echoed as `Retry-After`. Distinct from a malformed-response `502`: this is the retryable `503` case.
+
+**`nodeStreamToWeb(iterable, opts?)` / `guardStreamLength(stream, expectedBytes)` / `resolveServedRange(contentRange)` / `parseRetryAfterSeconds(raw, opts?)`** - The stream/accounting primitives the built-in adapters are made of, exported for custom adapter authors: Node-to-web stream conversion with backpressure, abort propagation, and short-read detection; a committed-length guard for web streams; backend `Content-Range` resolution with the unknown-total (`bytes a-b/*`) sentinel; and the shared `Retry-After` parser.

package/docs/BENCHMARKS.md

@@ -0,0 +1,85 @@
+# Benchmarks
+
+Two suites: kernel micro-benchmarks (library overhead only) and end-to-end HTTP serving against `send` and `sirv`. Reproduce with `bun bench.ts` and `npm run bench`.
+
+## Kernel micro-benchmarks
+
+Representative throughput measured on Bun 1.3 (single core, 2M iterations). These measure library overhead only -- they do not include network or storage latency.
+
+| Function | Throughput |
+|----------|-----------|
+| `parseRangeHeader` | 10.1M ops/sec |
+| `isPreconditionFailure` | 10.2M ops/sec |
+| `isRangeFresh` | 13.9M ops/sec |
+| `isConditionalFresh` | 4.7M ops/sec |
+| `buildRangeResponseHeaders` | 4.2M ops/sec |
+| `evaluateConditionalRequest` | 1.7M ops/sec |
+| `buildContentDisposition` | 1.7M ops/sec |
+
+## End-to-end vs `send` and `sirv`
+
+Full HTTP serving (Node 24, `http.createServer`, loopback, 40 connections,
+autocannon, identical fixtures; every cell correctness-verified before
+timing; the load generator runs in a separate process so its parse cost
+never throttles the server column). partial-content runs its shipped dist
+through the node adapter + fsStore. Reproduce with `npm run bench`.
+
+| Scenario | partial-content | + `cache` | send | sirv |
+|---|---|---|---|---|
+| GET 4 KB (200) | 9,210 req/s | **15,772 req/s** | 6,557 req/s | 7,162 req/s |
+| GET 1 MB (200) | 118 req/s | 116 req/s | 117 req/s | 119 req/s |
+| Range 64 KB of 1 MB (206) | 1,441 req/s | 1,413 req/s | 1,403 req/s | 1,443 req/s |
+| Revalidation (304) | 11,716 req/s | **19,542 req/s** | 10,081 req/s | 23,774 req/s* |
+
+The `cache` column is `fsStore({ root, cache: { ttlMs: 1000 } })`: an opt-in
+hot-object cache with nginx `open_file_cache` semantics (TTL revalidation,
+metadata + bytes captured atomically, bodies only at or below 128 KiB,
+LRU-evicted under both an entry cap (`maxEntries`, default 1024) and a body
+byte budget (`maxBytes`, default 64 MiB; `0` = metadata-only)). Hot small
+files and their ranges serve from memory with zero syscalls. The trade is
+explicit: after an overwrite, responses (including 304 revalidations) can
+affirm the previous representation for up to `ttlMs`; size it against
+acceptable staleness (see DESIGN.md).
+
+\* sirv's 304 figure buys throughput with a different contract: at
+`dev: false` it pre-renders complete header sets for a directory snapshot
+taken at boot, so a file created after startup is a 404. In the
+configuration that CAN see runtime-created files (`dev: true`), the same
+run measures sirv at 4,957 req/s -- a quarter of the `cache` column. For a
+fixed directory of immutable assets sirv's trade is exactly right; for
+object storage (where uploads happen while the server runs) it is
+disqualifying, which is why the boot-snapshot design stays a non-goal here.
+On the rows where server code matters (4 KB bodies, revalidations), the
+`cache` column is the fastest contender that can serve a file uploaded a
+second ago; at 64 KB and above, all four columns converge on I/O parity.
+
+## Bun runtime
+
+Same code on Bun 1.3 (`Bun.serve`, same machine, same out-of-process
+client -- the web adapter's Request/Response ARE the runtime's native
+primitives there, no node bridge): GET 4 KB 9,418 req/s plain and
+22,898 req/s with the cache; revalidation 12,538 plain and **38,090 req/s**
+with the cache -- a TTL-revalidating cache serving runtime uploads,
+outrunning even sirv's boot-frozen Node figure by 60%. `send` and `sirv`
+are node-stream libraries and cannot ride `Bun.serve` natively. Reproduce:
+`bun bench/bun-server.ts` (plain :18778, cache :18779) + autocannon.
+
+## Read this fairly in both directions
+
+- At payload sizes where file serving actually spends its time (>= 64 KB),
+  the contenders are at parity: I/O dominates.
+- Small-body transfers and revalidations lead `send` and `sirv` even
+  without the cache, while doing strictly more per request: RFC 9530
+  digest negotiation, audit hooks, pinned-read plumbing, and storage
+  abstraction. Four things make that possible: transfers at or below
+  128 KiB take a single positional-read fast path in the fs store, small
+  bodies travel as plain bytes (no stream machinery), the node adapter
+  consumes `serveObjectRaw` (zero fetch primitives constructed on the Node
+  hot path), and validators are derived once at stat time instead of
+  re-parsing dates on every request.
+- Correctness note found while building this benchmark: `send` honors a
+  request `Cache-Control: no-cache` during conditional evaluation, and
+  spec-compliant fetch clients (undici, browsers) auto-append exactly that
+  header to manually-conditional requests -- so `send` never answers 304 to
+  a fetch()-based revalidation. partial-content deliberately ignores request
+  cache directives here (matching Go stdlib and nginx; see DESIGN.md).

package/docs/EXAMPLES.md

@@ -0,0 +1,148 @@
+# Examples
+
+Recipes beyond the README's Quick Start. Every handler manages the full HTTP protocol (200, 206, 304, 412, 416, HEAD) automatically.
+
+## Hono
+
+```typescript
+import { Hono } from "hono";
+import { serveObject } from "partial-content/hono";
+import { s3Store } from "partial-content/s3";
+
+const store = s3Store({ client, bucket: "media" });
+const app = new Hono();
+
+app.get("/media/:key", serveObject(store, {
+  key: (c) => c.req.param("key"),
+  cacheControl: "public, max-age=31536000, immutable",
+}));
+```
+
+## Cloudflare Workers (R2 native, no AWS SDK)
+
+```typescript
+import { Hono } from "hono";
+import { serveObject } from "partial-content/hono";
+import { r2Store } from "partial-content/r2";
+
+const app = new Hono<{ Bindings: { MY_BUCKET: R2Bucket } }>();
+
+app.get("/files/:key", (c) => {
+  const store = r2Store({ bucket: c.env.MY_BUCKET });
+  return serveObject(store, { key: (c) => c.req.param("key") })(c);
+});
+```
+
+## Kernel only: the evaluation flow
+
+```
+Request                        evaluateConditionalRequest()
+  │                                       │
+  │  If-Match / If-Unmodified-Since       ├──► 412 Precondition Failed
+  │  If-None-Match / If-Modified-Since    ├──► 304 Not Modified
+  │  If-Range + Range                     ├──► 416 Range Not Satisfiable
+  │                                       ├──► 206 Partial Content
+  │                                       └──► 200 OK
+  │
+  ▼
+Fetch bytes from storage (you control this)
+  │
+  ▼
+new Response(body, { status, headers })
+```
+
+## Node.js / Express (kernel only)
+
+```typescript
+import { fromNodeHeaders, evaluateConditionalRequest } from "partial-content";
+
+app.get("/files/:key", (req, res) => {
+  const headers = fromNodeHeaders(req.headers);
+  const { status, headers: resHeaders, range } = evaluateConditionalRequest(
+    headers,
+    { totalSize: fileSize, etag, lastModified, contentType },
+  );
+  res.writeHead(status, resHeaders);
+  // ...
+});
+```
+
+## Content-Disposition
+
+```typescript
+import { buildContentDisposition } from "partial-content";
+
+buildContentDisposition("report.pdf");
+// => 'attachment; filename=report.pdf'
+
+buildContentDisposition("Årlig_Rapport.pdf");
+// => 'attachment; filename="?rlig_Rapport.pdf"; filename*=UTF-8''%C3%85rlig_Rapport.pdf'
+
+buildContentDisposition("slides.pdf", { type: "inline" });
+// => 'inline; filename=slides.pdf'
+
+// Handles untrusted input safely
+buildContentDisposition("../../etc/passwd");        // Path traversal stripped
+buildContentDisposition("evil\r\nX-Injected: yes"); // CRLF injection stripped
+buildContentDisposition(null, { fallback: "export.csv" }); // Graceful fallback
+```
+
+## RFC 9530 Repr-Digest (end-to-end integrity)
+
+Pass a SHA-256 digest from your storage backend for automatic `Repr-Digest` headers:
+
+```typescript
+const { status, headers, range } = evaluateConditionalRequest(
+  request.headers,
+  {
+    totalSize: fileSize,
+    etag: '"abc123"',
+    // S3: x-amz-checksum-sha256, GCS: x-goog-hash (sha256 component)
+    digest: "d2VsY29tZQ==",  // raw base64 SHA-256
+  },
+);
+// Response headers include: Repr-Digest: sha-256=:d2VsY29tZQ==:
+// Same digest on both 200 (full) and 206 (partial) -- covers the full representation
+```
+
+## Advanced: manual primitives
+
+For full control over the evaluation chain:
+
+```typescript
+import {
+  parseRangeHeader,
+  buildRangeResponseHeaders,
+  isConditionalFresh,
+  isPreconditionFailure,
+  isRangeFresh,
+  build304Headers,
+  build412Headers,
+  build416Headers,
+} from "partial-content";
+
+// Step 1: Preconditions (If-Match / If-Unmodified-Since)
+if (isPreconditionFailure(reqHeaders, etag, lastModified)) {
+  return new Response(null, build412Headers());
+}
+
+// Step 2: Freshness (If-None-Match / If-Modified-Since)
+if (isConditionalFresh(reqHeaders, etag, lastModified)) {
+  return new Response(null, build304Headers(etag, lastModified));
+}
+
+// Step 3: Range (If-Range + Range header)
+const range = isRangeFresh(reqHeaders, etag, lastModified)
+  ? parseRangeHeader(reqHeaders.get("range"), fileSize)
+  : null;
+
+if (range === "unsatisfiable") {
+  return new Response(null, build416Headers(fileSize));
+}
+
+const { status, headers } = buildRangeResponseHeaders({
+  totalSize: fileSize, range, contentType, etag, lastModified,
+  digest: checksum,          // RFC 9530 Repr-Digest
+  cacheControl: "private, no-cache",
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partial-content",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "RFC-compliant HTTP file serving for any storage backend. Range requests (206), conditional caching (304/412), Content-Disposition, and ETag generation. Zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",
@@ -73,7 +73,7 @@
     "src",
     "!src/__tests__",
     "README.md",
-    "docs/DESIGN.md",
+    "docs",
     "CHANGELOG.md",
     "SECURITY.md",
     "LICENSE"